AbstractProtectedtoolsGets the initialized tools for this tool.
Declares tool dependencies for this tool. Return an object mapping tool names to build() promises. Default implementation returns empty object (no custom tools).
The build function to use for declaring dependencies
Object mapping tool names to tool promises
ProtectedcallbackCreates a persistent callback to a method on this tool.
ExtraArgs are strongly typed to match the method's signature.
Promise resolving to a persistent callback token
ProtecteddeleteDeletes a specific callback by its token.
The callback token to delete
Promise that resolves when the callback is deleted
ProtecteddeleteDeletes all callbacks for this tool.
Promise that resolves when all callbacks are deleted
ProtectedrunExecutes a callback by its token.
The callback token to execute
Optional arguments to pass to the callback
Promise resolving to the callback result
ProtectedgetRetrieves a value from persistent storage by key.
Values are automatically deserialized using SuperJSON, which properly restores Date objects, Maps, Sets, and other complex types.
The expected type of the stored value (must be Serializable)
The storage key to retrieve
Promise resolving to the stored value or null
ProtectedsetStores a value in persistent storage.
The value will be serialized using SuperJSON and stored persistently. SuperJSON automatically handles Date objects, Maps, Sets, undefined values, and other complex types that standard JSON doesn't support.
Important: Functions and Symbols cannot be stored. For function references: Use callbacks instead of storing functions directly.
The type of value being stored (must be Serializable)
The storage key to use
The value to store (must be SuperJSON-serializable)
Promise that resolves when the value is stored
// ✅ Date objects are preserved
await this.set("sync_state", {
lastSync: new Date(),
minDate: new Date(2024, 0, 1)
});
// ✅ undefined is now supported
await this.set("data", { name: "test", optional: undefined });
// ✅ Arrays with undefined are supported
await this.set("items", [1, undefined, 3]);
await this.set("items", [1, null, 3]); // Also works
// ✅ Maps and Sets are supported
await this.set("mapping", new Map([["key", "value"]]));
await this.set("tags", new Set(["tag1", "tag2"]));
// ❌ 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);
ProtectedlistLists all storage keys matching a prefix.
The prefix to match keys against
Promise resolving to an array of matching key strings
ProtectedclearRemoves a specific key from persistent storage.
The storage key to remove
Promise that resolves when the key is removed
ProtectedclearRemoves all keys from this tool's storage.
Promise that resolves when all keys are removed
ProtectedrunQueues a callback to execute in a separate worker context with a fresh request limit.
Creates a NEW execution with its own request limit of ~1000 requests (HTTP requests, tool calls, database operations). This is the primary way to stay under request limits when processing large datasets or making many API calls.
Use this to break long loops into chunks that each stay under the ~1000 request limit. Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.
The callback token created with this.callback()
Optionaloptions: { runAt?: Date }Optional configuration for the execution
OptionalrunAt?: DateIf provided, schedules execution at this time; otherwise runs immediately
Promise resolving to a cancellation token (only for scheduled executions)
ProtectedcancelCancels a previously scheduled execution.
The cancellation token returned by runTask() with runAt option
Promise that resolves when the cancellation is processed
ProtectedcancelCancels all scheduled executions for this tool.
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.
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.
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.
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.
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.
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.
Promise that resolves when post-deactivation is complete
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.
Example