@plotday/twister 0.57.0 → 0.58.0

package/src/llm-docs/twist.ts

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import type { NoteWriteBackResult } from \"./connector\";\nimport { type Action, type Actor, type ActorId, type Link, type Note, type Thread, Uuid } from \"./plot\";\nimport type { Tag } from \"./tag\";\nimport { type ITool } from \"./tool\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type { Serializable } from \"./utils/serializable\";\nimport type { InferTools, ToolBuilder, ToolShed } from \"./utils/types\";\n\n/**\n * Base class for all twists.\n *\n * A twist is installed at the workspace level and is owned by a single user\n * (see `this.userId`). It has no inherent focus scope: threads, notes, and\n * links it creates are filed against the owner's focuses, with automatic\n * focus matching when no explicit target is provided.\n *\n * Override `build()` to declare tool dependencies and lifecycle methods to\n * handle events.\n *\n * @example\n * ```typescript\n * class FlatteringTwist extends Twist<FlatteringTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       plot: build(Plot),\n *     };\n *   }\n *\n *   async activate() {\n *     await this.tools.plot.createThread({\n *       title: \"Hello, good looking!\",\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Twist<TSelf> {\n  /**\n   * When `true`, users may install multiple instances of this twist within\n   * the same scope (personal workspace or team). Each instance must have a\n   * distinct name.\n   *\n   * Defaults to `false` (single instance per scope).\n   *\n   * @example\n   * ```typescript\n   * class WorkflowTwist extends Twist<WorkflowTwist> {\n   *   static readonly multipleInstances = true;\n   *   // ...\n   * }\n   * ```\n   */\n  static readonly multipleInstances?: boolean;\n\n  /**\n   * The user ID (`twist_instance.owner_id`) that installed this twist.\n   * Populated by the runtime before any lifecycle method runs.\n   */\n  protected userId!: Uuid;\n\n  constructor(protected id: Uuid, private toolShed: ToolShed) {}\n\n  /**\n   * Gets the initialized tools for this twist.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools(): InferTools<TSelf> {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this twist.\n   * Return an object mapping tool names to build() promises.\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot),\n   *     calendar: build(GoogleCalendar, { apiKey: \"...\" }),\n   *   };\n   * }\n   * ```\n   */\n  abstract build(build: ToolBuilder): Record<string, Promise<ITool>>;\n\n  /**\n   * Creates a persistent callback to a method on this twist.\n   *\n   * ExtraArgs are strongly typed to match the method's signature. They must be serializable.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback>;\n  // Overload when caller provides the first argument\n  protected callback<\n    TArgs extends Serializable[],\n    Fn extends (arg1: any, ...extraArgs: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback>;\n  protected async callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: any[]) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Like callback(), but for an Action, which receives the action as the first argument.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass after the action\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.actionCallback(this.doSomething, 123);\n   * const action: Action = {\n   *    type: ActionType.callback,\n   *    title: \"Do Something\",\n   *    callback,\n   * };\n   * ```\n   */\n  protected async actionCallback<\n    TArgs extends Serializable[],\n    Fn extends (action: Action, ...extraArgs: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this twist.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token inline in the current execution.\n   *\n   * **Use `this.runTask()` instead for batch continuations and long-running work.**\n   * `this.run()` executes inline, sharing the current request count (~1000 limit)\n   * and blocking the HTTP response. This causes timeouts when used in lifecycle\n   * methods like `onChannelEnabled` or `syncBatch` continuations.\n   *\n   * `this.run()` is appropriate when you need the callback's **return value** —\n   * e.g., running a parent callback token that returns data. For fire-and-forget\n   * work, always prefer `this.runTask()`.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: []): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends import(\"./index\").Serializable>(\n    key: string\n  ): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // ✅ undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<string>(\"handler_token\");\n   * await this.run(token, args);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends import(\"./index\").Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this twist's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this twist.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called when the twist is installed by a user.\n   *\n   * This method should contain initialization logic such as seeding\n   * initial threads, configuring webhooks, or establishing external\n   * connections. When it runs, `this.userId` is already populated with\n   * the installing user's ID.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  activate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a new version of the twist is deployed.\n   *\n   * This method should contain migration logic for updating old data structures\n   * or setting up new resources that weren't needed by the previous version.\n   * It is called once per active twist_instance with the new version.\n   *\n   * @returns Promise that resolves when upgrade is complete\n   */\n  upgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist's options configuration changes.\n   *\n   * Override to react to option changes, e.g. archiving items when a sync\n   * type is toggled off, or starting sync when a type is toggled on.\n   *\n   * @param oldOptions - The previously resolved options\n   * @param newOptions - The newly resolved options\n   * @returns Promise that resolves when the change is handled\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onOptionsChanged(\n    oldOptions: Record<string, any>,\n    newOptions: Record<string, any>\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist is uninstalled.\n   *\n   * This method should contain cleanup logic such as removing webhooks,\n   * cleaning up external resources, or performing final data operations.\n   *\n   * @returns Promise that resolves when deactivation is complete\n   */\n  deactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a thread created by this twist is updated.\n   * Override to implement two-way sync with an external system.\n   *\n   * @param thread - The updated thread\n   * @param changes - Tag additions and removals on the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadUpdated(\n    thread: Thread,\n    changes: {\n      tagsAdded: Record<Tag, ActorId[]>;\n      tagsRemoved: Record<Tag, ActorId[]>;\n    }\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a note is created on a thread created by this twist.\n   * Override to implement two-way sync (e.g. syncing notes as comments).\n   *\n   * Notes created by the twist itself are filtered out to prevent loops.\n   *\n   * Returning a string sets the note's `key` for future upsert matching,\n   * linking the Plot note to its external counterpart so that subsequent\n   * syncs (reactions, edits) update the existing note instead of creating duplicates.\n   *\n   * @param note - The newly created note\n   * @returns Optional note key for external deduplication\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteCreated(note: Note, ...args: any[]): Promise<string | NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a link is created in a connected source channel.\n   * Requires `link: true` in Plot options.\n   *\n   * @param link - The newly created link\n   * @param notes - Notes on the link's thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkCreated(link: Link, notes: Note[]): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a link in a connected source channel is updated.\n   * Requires `link: true` in Plot options.\n   *\n   * @param link - The updated link\n   * @param notes - Notes on the link's thread (optional)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkUpdated(link: Link, notes?: Note[]): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a note is created on a thread with a link from a connected channel.\n   * Requires `link: true` in Plot options.\n   *\n   * @param note - The newly created note\n   * @param link - The link associated with the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkNoteCreated(note: Note, link: Link): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
+export default "import type { NoteWriteBackResult } from \"./connector\";\nimport { type Action, type Actor, type ActorId, type Link, type Note, type Thread, Uuid } from \"./plot\";\nimport type { Tag } from \"./tag\";\nimport { type ITool } from \"./tool\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type { Serializable } from \"./utils/serializable\";\nimport type { InferTools, ToolBuilder, ToolShed } from \"./utils/types\";\n\n/**\n * Base class for all twists.\n *\n * A twist is installed at the workspace level and is owned by a single user\n * (see `this.userId`). It has no inherent focus scope: threads, notes, and\n * links it creates are filed against the owner's focuses, with automatic\n * focus matching when no explicit target is provided.\n *\n * Override `build()` to declare tool dependencies and lifecycle methods to\n * handle events.\n *\n * @example\n * ```typescript\n * class FlatteringTwist extends Twist<FlatteringTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       plot: build(Plot),\n *     };\n *   }\n *\n *   async activate() {\n *     await this.tools.plot.createThread({\n *       title: \"Hello, good looking!\",\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Twist<TSelf> {\n  /**\n   * When `true`, users may install multiple instances of this twist within\n   * the same scope (personal workspace or team). Each instance must have a\n   * distinct name.\n   *\n   * Defaults to `false` (single instance per scope).\n   *\n   * @example\n   * ```typescript\n   * class WorkflowTwist extends Twist<WorkflowTwist> {\n   *   static readonly multipleInstances = true;\n   *   // ...\n   * }\n   * ```\n   */\n  static readonly multipleInstances?: boolean;\n\n  /**\n   * The user ID (`twist_instance.owner_id`) that installed this twist.\n   * Populated by the runtime before any lifecycle method runs.\n   */\n  protected userId!: Uuid;\n\n  constructor(protected id: Uuid, private toolShed: ToolShed) {}\n\n  /**\n   * Gets the initialized tools for this twist.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools(): InferTools<TSelf> {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this twist.\n   * Return an object mapping tool names to build() promises.\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot),\n   *     calendar: build(GoogleCalendar, { apiKey: \"...\" }),\n   *   };\n   * }\n   * ```\n   */\n  abstract build(build: ToolBuilder): Record<string, Promise<ITool>>;\n\n  /**\n   * Creates a persistent callback to a method on this twist.\n   *\n   * ExtraArgs are strongly typed to match the method's signature. They must be serializable.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback>;\n  // Overload when caller provides the first argument\n  protected callback<\n    TArgs extends Serializable[],\n    Fn extends (arg1: any, ...extraArgs: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback>;\n  protected async callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: any[]) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Like callback(), but for an Action, which receives the action as the first argument.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass after the action\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.actionCallback(this.doSomething, 123);\n   * const action: Action = {\n   *    type: ActionType.callback,\n   *    title: \"Do Something\",\n   *    callback,\n   * };\n   * ```\n   */\n  protected async actionCallback<\n    TArgs extends Serializable[],\n    Fn extends (action: Action, ...extraArgs: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this twist.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token inline in the current execution.\n   *\n   * **Use `this.runTask()` instead for batch continuations and long-running work.**\n   * `this.run()` executes inline, sharing the current request count (~1000 limit)\n   * and blocking the HTTP response. This causes timeouts when used in lifecycle\n   * methods like `onChannelEnabled` or `syncBatch` continuations.\n   *\n   * `this.run()` is appropriate when you need the callback's **return value** —\n   * e.g., running a parent callback token that returns data. For fire-and-forget\n   * work, always prefer `this.runTask()`.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: []): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends import(\"./index\").Serializable>(\n    key: string\n  ): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // ✅ undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<Callback>(\"handler_token\");\n   * await this.run(token);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends import(\"./index\").Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this twist's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this twist.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called when the twist is installed by a user.\n   *\n   * This method should contain initialization logic such as seeding\n   * initial threads, configuring webhooks, or establishing external\n   * connections. When it runs, `this.userId` is already populated with\n   * the installing user's ID.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  activate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a new version of the twist is deployed.\n   *\n   * This method should contain migration logic for updating old data structures\n   * or setting up new resources that weren't needed by the previous version.\n   * It is called once per active twist_instance with the new version.\n   *\n   * @returns Promise that resolves when upgrade is complete\n   */\n  upgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist's options configuration changes.\n   *\n   * Override to react to option changes, e.g. archiving items when a sync\n   * type is toggled off, or starting sync when a type is toggled on.\n   *\n   * @param oldOptions - The previously resolved options\n   * @param newOptions - The newly resolved options\n   * @returns Promise that resolves when the change is handled\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onOptionsChanged(\n    oldOptions: Record<string, any>,\n    newOptions: Record<string, any>\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when the twist is uninstalled.\n   *\n   * This method should contain cleanup logic such as removing webhooks,\n   * cleaning up external resources, or performing final data operations.\n   *\n   * @returns Promise that resolves when deactivation is complete\n   */\n  deactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a thread created by this twist is updated.\n   * Override to implement two-way sync with an external system.\n   *\n   * @param thread - The updated thread\n   * @param changes - Tag additions and removals on the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadUpdated(\n    thread: Thread,\n    changes: {\n      tagsAdded: Record<Tag, ActorId[]>;\n      tagsRemoved: Record<Tag, ActorId[]>;\n    }\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a note is created on a thread created by this twist.\n   * Override to implement two-way sync (e.g. syncing notes as comments).\n   *\n   * Notes created by the twist itself are filtered out to prevent loops.\n   *\n   * Returning a string sets the note's `key` for future upsert matching,\n   * linking the Plot note to its external counterpart so that subsequent\n   * syncs (reactions, edits) update the existing note instead of creating duplicates.\n   *\n   * @param note - The newly created note\n   * @returns Optional note key for external deduplication\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteCreated(note: Note, ...args: any[]): Promise<string | NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a link is created in a connected source channel.\n   * Requires `link: true` in Plot options.\n   *\n   * @param link - The newly created link\n   * @param notes - Notes on the link's thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkCreated(link: Link, notes: Note[]): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a link in a connected source channel is updated.\n   * Requires `link: true` in Plot options.\n   *\n   * @param link - The updated link\n   * @param notes - Notes on the link's thread (optional)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkUpdated(link: Link, notes?: Note[]): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a note is created on a thread with a link from a connected channel.\n   * Requires `link: true` in Plot options.\n   *\n   * @param note - The newly created note\n   * @param link - The link associated with the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkNoteCreated(note: Note, link: Link): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";

package/src/plot.ts

@@ -1,3 +1,4 @@
+import type { ThreadFacets } from "./facets";
 import type { NewSchedule, NewScheduleOccurrence, Schedule } from "./schedule";
 import { type Tag } from "./tag";
 import { type Callback } from "./tools/callbacks";
@@ -21,7 +22,7 @@ export { type AuthProvider } from "./tools/integrations";
  * - **Required fields**: No `?`, cannot be `undefined`
  *   - Example: `id: Uuid`, `title: string`
  * - **Nullable fields**: Use `| null` to allow explicit clearing
- *   - Example: `assignee: ActorId | null`, `done: Date | null`
+ *   - Example: `key: string | null`, `status: string | null`
  *   - `null` = field is explicitly unset/cleared
  *   - Non-null value = field has a value
  * - **Optional nullable fields**: Use `?` with `| null` for permission-based access
@@ -68,9 +69,9 @@ export { type AuthProvider } from "./tools/integrations";
  * Represents a unique user, contact, or twist in Plot.
  *
  * ActorIds are used throughout Plot for:
- * - Activity authors and assignees
- * - Tag creators (actor_id in activity_tag/note_tag)
- * - Mentions in activities and notes
+ * - Thread and note authors, link assignees
+ * - Tag creators (actor_id in thread_tag/note_tag)
+ * - Mentions in notes
  * - Any entity that can perform actions in Plot
  */
 export type ActorId = string & { readonly __brand: "ActorId" };
@@ -100,7 +101,7 @@ export enum ThemeColor {
 /**
  * Represents a focus within Plot.
  *
- * A focus is similar to a project or area-of-life. All Activity is in a Focus.
+ * A focus is similar to a project or area-of-life. Every thread is in a focus.
  * Focuses are flat — they have no parent and no children. Threads not matched
  * to any focus live in the Inbox.
  */
@@ -402,8 +403,8 @@ export type NewTags = { [K in Tag]?: NewActor[] };
  * Anything matching a known provider prefix is treated as a custom-emoji
  * reference; everything else is rendered as the Unicode it contains.
  *
- * Reactions are the open-set counterpart to {@link Tag}'s count range
- * (`1000+`). Use reactions for emoji that round-trip with chat platforms;
+ * Reactions are the open-set replacement for {@link Tag}'s retired count
+ * range (`1000+`). Use reactions for emoji that round-trip with chat platforms;
  * use tags for Plot-managed compute/toggle state (todo, pinned, urgent,
  * ...).
  */
@@ -921,7 +922,7 @@ export enum ActorType {
  * Represents contact information for creating a new contact.
  *
  * Contacts are used throughout Plot for representing people associated
- * with activities, such as event attendees or task assignees.
+ * with threads, such as event attendees or task assignees.
  *
  * @example
  * ```typescript
@@ -1069,6 +1070,12 @@ export type NewLink = Partial<
    * thread that includes `icaluid:<uid>` in its own `sources`.
    */
   sources?: string[];
+    /**
+     * Heuristic facets describing this item (format / automation / reach),
+     * used as internal classifier signal. Omit a dimension (or set null) when
+     * no heuristic is confident. See `@plotday/twister/facets`.
+     */
+    facets?: ThreadFacets;
     /** The person that created the item. By default, it will be the twist itself. */
     author?: NewActor;
     /** The person assigned to the item. */

package/src/tool.ts

@@ -13,7 +13,7 @@ import type {
 export type { ToolBuilder };
 
 /**
- * Abstrtact parent for both built-in tools and regular Tools.
+ * Abstract parent for both built-in tools and regular Tools.
  * Regular tools extend Tool.
  */
 export abstract class ITool {}
@@ -194,8 +194,8 @@ export abstract class Tool<TSelf> implements ITool {
    * await this.set("handler_token", token);
    *
    * // Later, execute the callback
-   * const token = await this.get<string>("handler_token");
-   * await this.run(token, args);
+   * const token = await this.get<Callback>("handler_token");
+   * await this.run(token);
    * ```
    *
    * @template T - The type of value being stored (must be Serializable)
@@ -257,7 +257,7 @@ export abstract class Tool<TSelf> implements ITool {
    * @example
    * ```typescript
    * // Break large loop into batches
-   * const callback = await this.callback("processBatch", { page: 1 });
+   * const callback = await this.callback(this.processBatch, 1);
    * await this.runTask(callback); // New execution with fresh request limit
    * ```
    */

package/src/tools/ai.ts

@@ -21,12 +21,11 @@ import { ITool } from "..";
  * ```typescript
  * import { Type } from "typebox";
  *
- * class SmartEmailTool extends Tool {
- *   private ai: AI;
- *
- *   constructor(id: string, tools: ToolBuilder) {
- *     super();
- *     this.ai = tools.get(AI);
+ * class SmartEmailTool extends Tool<SmartEmailTool> {
+ *   build(build: ToolBuilder) {
+ *     return {
+ *       ai: build(AI),
+ *     };
  *   }
  *
  *   async categorizeEmail(emailContent: string) {
@@ -42,7 +41,7 @@ import { ITool } from "..";
  *       reasoning: Type.Optional(Type.String())
  *     });
  *
- *     const response = await this.ai.prompt({
+ *     const response = await this.tools.ai.prompt({
  *       model: { speed: "fast", cost: "medium" },
  *       system: "Classify emails into categories: work, personal, spam, or promotional.",
  *       prompt: `Categorize this email: ${emailContent}`,
@@ -53,7 +52,7 @@ import { ITool } from "..";
  *   }
  *
  *   async generateResponse(emailContent: string) {
- *     const response = await this.ai.prompt({
+ *     const response = await this.tools.ai.prompt({
  *       model: { speed: "fast", cost: "medium" },
  *       system: "Generate professional email responses that are helpful and concise.",
  *       prompt: `Write a response to: ${emailContent}`
@@ -67,7 +66,7 @@ import { ITool } from "..";
 export abstract class AI extends ITool {
   /**
    * Returns which AI capabilities are currently available.
-   * Check this before calling prompt() or embed() to gracefully
+   * Check this before calling prompt() to gracefully
    * handle cases where AI is disabled by the user.
    *
    * Built-in tools are accessed as RPC stubs, so from a twist this call
@@ -195,7 +194,7 @@ export type AICapabilities = {
  *   prompt: "Analyze this data..."
  * });
  *
- * // Most capable - uses Claude Sonnet 4.5 or Opus 4.1
+ * // Most capable - uses models like GPT-5, Claude Sonnet 4.6, or Gemini 2.5 Pro
  * const response = await ai.prompt({
  *   model: { speed: "capable", cost: "high" },
  *   prompt: "Solve this complex reasoning problem..."
@@ -203,7 +202,7 @@ export type AICapabilities = {
  *
  * // Request a specific model with a hint
  * const response = await ai.prompt({
- *   model: { speed: "balanced", cost: "medium", hint: AIModel.CLAUDE_SONNET_45 },
+ *   model: { speed: "balanced", cost: "medium", hint: AIModel.CLAUDE_SONNET_46 },
  *   prompt: "..."
  * });
  * ```
@@ -238,7 +237,7 @@ export type ModelPreferences = {
  * Models are organized by provider:
  * - **OpenAI**: Latest GPT models via AI Gateway
  * - **Anthropic**: Claude models via AI Gateway (prefix with "anthropic/")
- * - **Google**: Gemini models via AI Gateway (prefix with "google-ai-studio/")
+ * - **Google**: Gemini models via AI Gateway (prefix with "google/")
  * - **Workers AI**: Models running on Cloudflare's network (free/low cost)
  */
 export enum AIModel {
@@ -513,7 +512,7 @@ export type AIUsage = {
    */
   outputTokens?: number;
   /**
-   * The total number of tokens used (promptTokens + completionTokens).
+   * The total number of tokens used (inputTokens + outputTokens).
    */
   totalTokens?: number;
   /**

package/src/tools/callbacks.ts

@@ -7,7 +7,7 @@ import { Serializable } from "../utils/types";
  * Callbacks enable tools and twists to create persistent references to functions
  * that can survive worker restarts and be invoked across different execution contexts.
  *
- * This is a branded strin
+ * This is a branded string
  * type to prevent mixing callback tokens with regular strings.
  *
  * @example

package/src/tools/files.ts

@@ -14,8 +14,8 @@ import { ITool } from "..";
  */
 export abstract class Files extends ITool {
   /**
-   * Read a file uploaded by a client and attached to a note in a focus
-   * where this twist is installed.
+   * Read a file uploaded by a client and attached to a note on a thread
+   * in one of the twist owner's focuses.
    *
    * @param fileId The id from an ActionType.file action.
    * @returns Bytes plus original metadata.

package/src/tools/imap.ts

@@ -129,7 +129,7 @@ export type ImapFlagOperation = "add" | "remove" | "set";
  * @example
  * ```typescript
  * class AppleMailConnector extends Connector<AppleMailConnector> {
- *   build(build: ConnectorBuilder) {
+ *   build(build: ToolBuilder) {
  *     return {
  *       options: build(Options, {
  *         email: { type: "text", label: "Apple ID Email", default: "" },

package/src/tools/integrations.ts

@@ -685,8 +685,9 @@ export type AuthToken = {
    *
    * For Slack (AuthProvider.Slack):
    * - authed_user_id: The authenticated user's Slack ID
-   * - bot_user_id: The bot user's Slack ID
+   * - team_id: The Slack workspace/team ID
    * - team_name: The Slack workspace/team name
+   * - enterprise_id: The Enterprise Grid org ID (when applicable)
    */
   provider?: Record<string, string>;
 };

package/src/tools/network.ts

@@ -233,9 +233,9 @@ export abstract class Network extends ITool {
    * Deletes an existing webhook endpoint.
    *
    * Removes the webhook endpoint and stops processing requests.
-   * Works with all webhook types (standard, Slack, and Gmail).
+   * Works with all webhook types (standard, Slack, and Pub/Sub).
    *
-   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.
+   * **For Pub/Sub webhooks (Gmail and Workspace Events):** Also deletes the associated Google Pub/Sub topic and subscription.
    *
    * **For Slack webhooks:** Removes the callback registration for the specific team.
    *
@@ -243,9 +243,9 @@ export abstract class Network extends ITool {
    * to the deleted webhook will return 404.
    *
    * @param url - The webhook identifier returned from `createWebhook()`.
-   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),
-   *              or an opaque identifier (Slack). Always pass the exact value returned
-   *              from `createWebhook()`.
+   *              This can be a URL (standard webhooks), a Pub/Sub topic name
+   *              (Gmail/Workspace Events), or an opaque identifier (Slack).
+   *              Always pass the exact value returned from `createWebhook()`.
    * @returns Promise that resolves when the webhook is deleted
    */
   abstract deleteWebhook(url: string): Promise<void>;

package/src/tools/plot.ts

@@ -146,22 +146,26 @@ export type SearchOptions = {
  *
  * @example
  * ```typescript
- * class MyTwist extends Twist {
- *   private plot: Plot;
- *
- *   constructor(id: string, tools: ToolBuilder) {
- *     super();
- *     this.plot = tools.get(Plot);
+ * class MyTwist extends Twist<MyTwist> {
+ *   build(build: ToolBuilder) {
+ *     return {
+ *       plot: build(Plot, {
+ *         thread: { access: ThreadAccess.Create },
+ *       }),
+ *     };
  *   }
  *
  *   async activate() {
- *     // Create a welcome thread
- *     await this.plot.createThread({
+ *     // Create a welcome thread with an opening note
+ *     await this.tools.plot.createThread({
  *       title: "Welcome to Plot!",
- *       actions: [{
- *         title: "Get Started",
- *         type: ActionType.external,
- *         url: "https://plot.day/docs"
+ *       notes: [{
+ *         content: "Get started with Plot:",
+ *         actions: [{
+ *           type: ActionType.external,
+ *           title: "Get Started",
+ *           url: "https://plot.day/docs"
+ *         }]
  *       }]
  *     });
  *   }
@@ -330,8 +334,9 @@ export abstract class Plot extends ITool {
    * remain unchanged. This enables partial updates without needing to fetch and resend
    * the entire thread object.
    *
-   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.
-   * Tags not included in the update remain unchanged.
+   * For the twist's own tags, use `twistTags`: a record mapping tag ID to a
+   * boolean, where true adds the tag and false removes it. Tags not included
+   * in the update remain unchanged.
    *
    * Set `focus` to move the thread to a different focus.
    *
@@ -343,18 +348,18 @@ export abstract class Plot extends ITool {
    *
    * @example
    * ```typescript
-   * // Mark a task as complete
-   * await this.plot.updateThread({
-   *   id: "task-123",
-   *   done: new Date()
+   * // Archive a thread
+   * await this.tools.plot.updateThread({
+   *   id: threadId,
+   *   archived: true
    * });
    *
-   * // Add and remove tags
-   * await this.plot.updateThread({
-   *   id: "thread-789",
-   *   tags: {
-   *     1: true,  // Add tag with ID 1
-   *     2: false  // Remove tag with ID 2
+   * // Add and remove the twist's tags
+   * await this.tools.plot.updateThread({
+   *   id: threadId,
+   *   twistTags: {
+   *     [Tag.Todo]: true,  // Add the to-do tag
+   *     [Tag.Done]: false  // Remove the done tag
    *   }
    * });
    * ```
@@ -388,16 +393,16 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Create a note with content
-   * await this.plot.createNote({
+   * await this.tools.plot.createNote({
    *   thread: { id: "thread-123" },
-   *   note: "Discussion notes from the meeting...",
+   *   content: "Discussion notes from the meeting...",
    *   contentType: "markdown"
    * });
    *
    * // Create a note with actions
-   * await this.plot.createNote({
+   * await this.tools.plot.createNote({
    *   thread: { id: "thread-456" },
-   *   note: "Meeting recording available",
+   *   content: "Meeting recording available",
    *   actions: [{
    *     type: ActionType.external,
    *     title: "View Recording",
@@ -422,14 +427,14 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Create multiple notes in one batch
-   * await this.plot.createNotes([
+   * await this.tools.plot.createNotes([
    *   {
    *     thread: { id: "thread-123" },
-   *     note: "First message in thread"
+   *     content: "First message in thread"
    *   },
    *   {
    *     thread: { id: "thread-123" },
-   *     note: "Second message in thread"
+   *     content: "Second message in thread"
    *   }
    * ]);
    * ```
@@ -454,16 +459,16 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Update note content
-   * await this.plot.updateNote({
+   * await this.tools.plot.updateNote({
    *   id: "note-123",
-   *   note: "Updated content with more details"
+   *   content: "Updated content with more details"
    * });
    *
    * // Add tags to a note
-   * await this.plot.updateNote({
+   * await this.tools.plot.updateNote({
    *   id: "note-456",
    *   twistTags: {
-   *     [Tag.Important]: true
+   *     [Tag.Todo]: true
    *   }
    * });
    * ```
@@ -573,10 +578,10 @@ export abstract class Plot extends ITool {
    * @example
    * ```typescript
    * // Schedule a timed event
-   * const threadId = await this.plot.createThread({
+   * const threadId = await this.tools.plot.createThread({
    *   title: "Team standup"
    * });
-   * await this.plot.createSchedule({
+   * await this.tools.plot.createSchedule({
    *   threadId,
    *   start: new Date("2025-01-15T10:00:00Z"),
    *   end: new Date("2025-01-15T10:30:00Z"),

package/src/tools/smtp.ts

@@ -76,7 +76,7 @@ export type SmtpSendResult = {
  * @example
  * ```typescript
  * class AppleMailConnector extends Connector<AppleMailConnector> {
- *   build(build: ConnectorBuilder) {
+ *   build(build: ToolBuilder) {
  *     return {
  *       options: build(Options, {
  *         email: { type: "text", label: "Apple ID Email", default: "" },

package/src/tools/tasks.ts

@@ -30,18 +30,18 @@ import type { Callback } from "./callbacks";
  *
  * @example
  * ```typescript
- * class SyncTool extends Tool {
+ * class SyncTool extends Tool<SyncTool> {
  *   async startBatchSync(totalItems: number) {
  *     // Store initial state using built-in set method
  *     await this.set("sync_progress", { processed: 0, total: totalItems });
  *
  *     // Create callback and queue first batch
- *     const callback = await this.callback("processBatch", { batchNumber: 1 });
+ *     const callback = await this.callback(this.processBatch, 1);
  *     // runTask creates NEW execution with fresh ~1000 request limit
  *     await this.runTask(callback);
  *   }
  *
- *   async processBatch(args: any, context: { batchNumber: number }) {
+ *   async processBatch(batchNumber: number) {
  *     // Process one batch of items (sized to stay under request limit)
  *     const progress = await this.get("sync_progress");
  *
@@ -61,9 +61,7 @@ import type { Callback } from "./callbacks";
  *
  *     if (progress.processed < progress.total) {
  *       // Queue next batch - creates NEW execution with fresh request limit
- *       const callback = await this.callback("processBatch", {
- *         batchNumber: context.batchNumber + 1
- *       });
+ *       const callback = await this.callback(this.processBatch, batchNumber + 1);
  *       await this.runTask(callback);
  *     }
  *   }
@@ -72,7 +70,7 @@ import type { Callback } from "./callbacks";
  *     const tomorrow = new Date();
  *     tomorrow.setDate(tomorrow.getDate() + 1);
  *
- *     const callback = await this.callback("cleanupOldData");
+ *     const callback = await this.callback(this.cleanupOldData);
  *     // Schedule for future execution
  *     return await this.runTask(callback, { runAt: tomorrow });
  *   }
@@ -103,7 +101,7 @@ export abstract class Tasks extends ITool {
    * @example
    * ```typescript
    * // Break large loop into batches to stay under request limit
-   * const callback = await this.callback("syncBatch", { page: 1 });
+   * const callback = await this.callback(this.syncBatch, 1);
    * await this.runTask(callback); // Fresh execution with ~1000 requests
    * ```
    */

package/src/tools/twists.ts

@@ -61,10 +61,10 @@ export type TwistPermissions = Record<string, Record<string, string[]>>;
  *
  * @example
  * ```typescript
- * class TwistBuilderTwist extends Twist {
+ * class TwistBuilderTwist extends Twist<TwistBuilderTwist> {
  *   build(build: ToolBuilder) {
  *    return {
- *      twists: build.get(Twists)
+ *      twists: build(Twists)
  *    }
  *   }
  *
@@ -77,14 +77,15 @@ export type TwistPermissions = Record<string, Record<string, string[]>>;
  */
 export abstract class Twists extends ITool {
   /**
-   * Creates a new twist ID and grants access to people in the current focus.
+   * Creates a new twist package ID. Ownership of the ID is claimed lazily
+   * on first deploy — no upfront registration happens beyond generating it.
    *
    * @returns Promise resolving to the generated twist ID
    * @throws When twist creation fails
    *
    * @example
    * ```typescript
-   * const twistId = await twist.create();
+   * const twistId = await this.tools.twists.create();
    * console.log(`Your twist ID: ${twistId}`);
    * ```
    */
@@ -103,15 +104,15 @@ export abstract class Twists extends ITool {
    *
    * @example
    * ```typescript
-   * const source = await twist.generate(`
+   * const source = await this.tools.twists.generate(`
    * # Calendar Sync Twist
    *
-   * This twist syncs Google Calendar events to Plot activities.
+   * This twist syncs Google Calendar events to Plot threads.
    *
    * ## Features
    * - Authenticate with Google
    * - Sync calendar events
-   * - Create activities from events
+   * - Create threads from events
    * `);
    *
    * // source.dependencies: { "@plotday/twister": "workspace:^", ... }
@@ -143,7 +144,7 @@ export abstract class Twists extends ITool {
    * @example
    * ```typescript
    * // Deploy with a module
-   * const result = await twist.deploy({
+   * const result = await this.tools.twists.deploy({
    *   twistId: 'abc-123-...',
    *   module: 'export default class MyTwist extends Twist {...}',
    *   environment: 'personal',
@@ -153,8 +154,8 @@ export abstract class Twists extends ITool {
    * console.log(`Deployed version ${result.version}`);
    *
    * // Deploy with source
-   * const source = await twist.generate(spec);
-   * const result = await twist.deploy({
+   * const source = await this.tools.twists.generate(spec);
+   * const result = await this.tools.twists.deploy({
    *   twistId: 'abc-123-...',
    *   source,
    *   environment: 'personal',
@@ -162,7 +163,7 @@ export abstract class Twists extends ITool {
    * });
    *
    * // Validate with dryRun
-   * const result = await twist.deploy({
+   * const result = await this.tools.twists.deploy({
    *   twistId: 'abc-123-...',
    *   source,
    *   dryRun: true,
@@ -209,11 +210,11 @@ export abstract class Twists extends ITool {
    * @example
    * ```typescript
    * // Create twist and callback
-   * const twistId = await this.twist.create();
-   * const callback = await this.callback.create("onLogs");
+   * const twistId = await this.tools.twists.create();
+   * const callback = await this.callback(this.onLogs);
    *
    * // Subscribe to logs
-   * await this.twist.watchLogs(twistId, callback);
+   * await this.tools.twists.watchLogs(twistId, callback);
    *
    * // Implement handler
    * async onLogs(logs: Log[]) {

package/src/twist.ts

@@ -225,8 +225,8 @@ export abstract class Twist<TSelf> {
    * await this.set("handler_token", token);
    *
    * // Later, execute the callback
-   * const token = await this.get<string>("handler_token");
-   * await this.run(token, args);
+   * const token = await this.get<Callback>("handler_token");
+   * await this.run(token);
    * ```
    *
    * @template T - The type of value being stored (must be Serializable)