Creating Plot Twists
    Preparing search index...

    Class Tool<TSelf>Abstract

    Base class for regular tools.

    Regular tools run in isolation and can only access other tools declared in their build method. They are ideal for external API integrations and reusable functionality that doesn't require Plot's internal infrastructure.

    class GoogleCalendarTool extends Tool<GoogleCalendarTool> {
      constructor(id: string, options: { clientId: string }) {
        super(id, options);
      }

      build(tools: ToolBuilder) {
        return {
          auth: tools.build(Integrations),
          network: tools.build(Network),
        };
      }

      async getCalendars() {
        const token = await this.tools.auth.get(...);
        // Implementation
      }
    }

    Type Parameters

    • TSelf

    Implements

    Index

    Accessors

    tools

    Constructors

    constructor

    Methods

    build callback deleteCallback deleteAllCallbacks run get set clear clearAll runTask cancelTask cancelAllTasks preActivate postActivate preUpgrade postUpgrade preDeactivate postDeactivate

    Properties

    id options

    Accessors

    Constructors

    Methods

    • Declares tool dependencies for this tool. Return an object mapping tool names to build() promises. Default implementation returns empty object (no custom tools).

      Parameters

      • build: ToolBuilder

        The build function to use for declaring dependencies

      Returns Record<string, Promise<ITool>>

      Object mapping tool names to tool promises

      build(build: ToolBuilder) {
        return {
          network: build(Network, { urls: ["https://api.example.com/*"] }),
        };
      }

    • Creates a persistent callback to a method on this tool.

      ExtraArgs are strongly typed to match the method's signature after the first argument.

      Parameters

      • fn: Function

        The method to callback

      • ...extraArgs: any[]

        Additional arguments to pass (type-checked, must be serializable)

      Returns Promise<Callback>

      Promise resolving to a persistent callback token

      const callback = await this.callback(this.onWebhook, "calendar", 123);

    • Deletes a specific callback by its token.

      Parameters

      • token: Callback

        The callback token to delete

      Returns Promise<void>

      Promise that resolves when the callback is deleted

    • Deletes all callbacks for this tool.

      Returns Promise<void>

      Promise that resolves when all callbacks are deleted

    • Executes a callback by its token.

      Parameters

      • token: Callback

        The callback token to execute

      • Optionalargs: any

        Optional arguments to pass to the callback

      Returns Promise<any>

      Promise resolving to the callback result

    • Retrieves a value from persistent storage by key.

      Type Parameters

      • T

        The expected type of the stored value

      Parameters

      • key: string

        The storage key to retrieve

      Returns Promise<T | null>

      Promise resolving to the stored value or null

    • Stores a value in persistent storage.

      Important: Values must be JSON-serializable. Functions, Symbols, and undefined values cannot be stored directly.

      For function references: Use callbacks instead of storing functions directly.

      Type Parameters

      • T

        The type of value being stored

      Parameters

      • key: string

        The storage key to use

      • value: T

        The value to store (must be JSON-serializable)

      Returns Promise<void>

      Promise that resolves when the value is stored

      // ❌ WRONG: Cannot store functions directly
      await this.set("handler", this.myHandler);

      // ✅ CORRECT: Create a callback token first
      const token = await this.callback(this.myHandler, "arg1", "arg2");
      await this.set("handler_token", token);

      // Later, execute the callback
      const token = await this.get<string>("handler_token");
      await this.run(token, args);

    • Removes a specific key from persistent storage.

      Parameters

      • key: string

        The storage key to remove

      Returns Promise<void>

      Promise that resolves when the key is removed

    • Removes all keys from this tool's storage.

      Returns Promise<void>

      Promise that resolves when all keys are removed

    • Queues a callback to execute in a separate worker context.

      Parameters

      • callback: Callback

        The callback token created with this.callback()

      • Optionaloptions: { runAt?: Date }

        Optional configuration for the execution

        • OptionalrunAt?: Date

          If provided, schedules execution at this time; otherwise runs immediately

      Returns Promise<string | void>

      Promise resolving to a cancellation token (only for scheduled executions)

    • Cancels a previously scheduled execution.

      Parameters

      • token: string

        The cancellation token returned by runTask() with runAt option

      Returns Promise<void>

      Promise that resolves when the cancellation is processed

    • Cancels all scheduled executions for this tool.

      Returns Promise<void>

      Promise that resolves when all cancellations are processed

    • Called before the twist's activate method, starting from the deepest tool dependencies.

      This method is called in a depth-first manner, with the deepest dependencies being called first, bubbling up to the top-level tools before the twist's activate method is called.

      Parameters

      • priority: Priority

        The priority context containing the priority ID

      Returns Promise<void>

      Promise that resolves when pre-activation is complete

    • Called after the twist's activate method, starting from the top-level tools.

      This method is called in reverse order, with top-level tools being called first, then cascading down to the deepest dependencies.

      Parameters

      • priority: Priority

        The priority context containing the priority ID

      Returns Promise<void>

      Promise that resolves when post-activation is complete

    • Called before the twist's upgrade method, starting from the deepest tool dependencies.

      This method is called in a depth-first manner, with the deepest dependencies being called first, bubbling up to the top-level tools before the twist's upgrade method is called.

      Returns Promise<void>

      Promise that resolves when pre-upgrade is complete

    • Called after the twist's upgrade method, starting from the top-level tools.

      This method is called in reverse order, with top-level tools being called first, then cascading down to the deepest dependencies.

      Returns Promise<void>

      Promise that resolves when post-upgrade is complete

    • Called before the twist's deactivate method, starting from the deepest tool dependencies.

      This method is called in a depth-first manner, with the deepest dependencies being called first, bubbling up to the top-level tools before the twist's deactivate method is called.

      Returns Promise<void>

      Promise that resolves when pre-deactivation is complete

    • Called after the twist's deactivate method, starting from the top-level tools.

      This method is called in reverse order, with top-level tools being called first, then cascading down to the deepest dependencies.

      Returns Promise<void>

      Promise that resolves when post-deactivation is complete

    Properties

    id: string
    options: InferOptions<TSelf>

    Settings

    Member Visibility

    On This Page

    Accessors
    Constructors
    Methods
    Properties