@plotday/twister 0.22.0 → 0.27.0

package/dist/llm-docs/tools/callbacks.d.ts

@@ -1,9 +1,9 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/callbacks
+ * Generated LLM documentation for @plotday/twister/tools/callbacks
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import { ITool } from \"..\";\nimport type { CallbackMethods, NoFunctions, NonFunction } from \"../utils/types\";\n\n// Re-export types for consumers\nexport type { CallbackMethods, NoFunctions, NonFunction };\n\n/**\n * Represents a callback token for persistent function references.\n *\n * Callbacks enable tools and twists to create persistent references to functions\n * that can survive worker restarts and be invoked across different execution contexts.\n *\n * This is a branded string type to prevent mixing callback tokens with regular strings.\n *\n * @example\n * ```typescript\n * const callback = await this.callback(this.onCalendarSelected, \"primary\", \"google\");\n * ```\n */\nexport type Callback = string & { readonly __brand: \"Callback\" };\n\n/**\n * Built-in tool for creating and managing persistent callback references.\n *\n * The Callbacks tool enables twists and tools to create callback links that persist\n * across worker invocations and restarts. This is essential for webhook handlers,\n * scheduled operations, and user interaction flows that need to survive runtime\n * boundaries.\n *\n * **Note:** Callback methods are also available directly on Twist and Tool classes\n * via `this.callback()`, `this.deleteCallback()`, `this.deleteAllCallbacks()`, and\n * `this.run()`. This is the recommended approach for most use cases.\n *\n * **When to use callbacks:**\n * - Webhook handlers that need persistent function references\n * - Scheduled operations that run after worker timeouts\n * - User interaction links (ActivityLinkType.callback)\n * - Cross-tool communication that survives restarts\n *\n * **Type Safety:**\n * Callbacks are fully type-safe - extraArgs are type-checked against the function signature.\n *\n * @example\n * ```typescript\n * class MyTool extends Tool {\n *   async setupWebhook() {\n *     // Using built-in callback method (recommended)\n *     const callback = await this.callback(this.handleWebhook, \"calendar\");\n *     return `https://api.plot.day/webhook/${callback}`;\n *   }\n *\n *   async handleWebhook(data: any, webhookType: string) {\n *     console.log(\"Webhook received:\", data, webhookType);\n *   }\n * }\n * ```\n */\nexport abstract class Callbacks extends ITool {\n  /**\n   * Creates a persistent callback to a method on the current class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract create(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback>;\n\n  /**\n   * Creates a persistent callback to a function from the parent twist/tool.\n   * Use this when the callback function is passed in from outside this class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable, validated at runtime)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createFromParent(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback>;\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param callback - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract delete(callback: Callback): Promise<void>;\n\n  /**\n   * Deletes all callbacks for the tool's parent.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  abstract deleteAll(): Promise<void>;\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param callback - The callback token returned by create()\n   * @param args - Optional arguments to pass to the callback function\n   * @returns Promise resolving to the callback result\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract run<T = unknown>(callback: Callback, ...args: any[]): Promise<T>;\n}\n";
+declare const _default: "import { ITool } from \"..\";\nimport type { CallbackMethods, NoFunctions, NonFunction } from \"../utils/types\";\n\n// Re-export types for consumers\nexport type { CallbackMethods, NoFunctions, NonFunction };\n\n/**\n * Represents a callback token for persistent function references.\n *\n * Callbacks enable tools and twists to create persistent references to functions\n * that can survive worker restarts and be invoked across different execution contexts.\n *\n * This is a branded string type to prevent mixing callback tokens with regular strings.\n *\n * @example\n * ```typescript\n * const callback = await this.callback(this.onCalendarSelected, \"primary\", \"google\");\n * ```\n */\nexport type Callback = string & { readonly __brand: \"Callback\" };\n\n/**\n * Built-in tool for creating and managing persistent callback references.\n *\n * The Callbacks tool enables twists and tools to create callback links that persist\n * across worker invocations and restarts. This is essential for webhook handlers,\n * scheduled operations, and user interaction flows that need to survive runtime\n * boundaries.\n *\n * **Note:** Callback methods are also available directly on Twist and Tool classes\n * via `this.callback()`, `this.deleteCallback()`, `this.deleteAllCallbacks()`, and\n * `this.run()`. This is the recommended approach for most use cases.\n *\n * **When to use callbacks:**\n * - Webhook handlers that need persistent function references\n * - Scheduled operations that run after worker timeouts\n * - User interaction links (ActivityLinkType.callback)\n * - Cross-tool communication that survives restarts\n *\n * **Type Safety:**\n * Callbacks are fully type-safe - extraArgs are type-checked against the function signature.\n *\n * @example\n * ```typescript\n * class MyTool extends Tool {\n *   async setupWebhook() {\n *     // Using built-in callback method (recommended)\n *     const callback = await this.callback(this.handleWebhook, \"calendar\");\n *     return `https://api.plot.day/webhook/${callback}`;\n *   }\n *\n *   async handleWebhook(data: any, webhookType: string) {\n *     console.log(\"Webhook received:\", data, webhookType);\n *   }\n * }\n * ```\n */\nexport abstract class Callbacks extends ITool {\n  /**\n   * Creates a persistent callback to a method on the current class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract create<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback>;\n\n  /**\n   * Creates a persistent callback to a function from the parent twist/tool.\n   * Use this when the callback function is passed in from outside this class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable, validated at runtime)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createFromParent(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback>;\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param callback - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract delete(callback: Callback): Promise<void>;\n\n  /**\n   * Deletes all callbacks for the tool's parent.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  abstract deleteAll(): Promise<void>;\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param callback - The callback token returned by create()\n   * @param args - Optional arguments to pass to the callback function\n   * @returns Promise resolving to the callback result\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract run<T = unknown>(callback: Callback, ...args: any[]): Promise<T>;\n}\n";
 export default _default;
 //# sourceMappingURL=callbacks.d.ts.map

package/dist/llm-docs/tools/callbacks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/callbacks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,6jIAA6jI;AAA5kI,wBAA6kI"}
+{"version":3,"file":"callbacks.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/callbacks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,omIAAomI;AAAnnI,wBAAonI"}

package/dist/llm-docs/tools/callbacks.js

@@ -1,8 +1,8 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/callbacks
+ * Generated LLM documentation for @plotday/twister/tools/callbacks
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { ITool } from \"..\";\nimport type { CallbackMethods, NoFunctions, NonFunction } from \"../utils/types\";\n\n// Re-export types for consumers\nexport type { CallbackMethods, NoFunctions, NonFunction };\n\n/**\n * Represents a callback token for persistent function references.\n *\n * Callbacks enable tools and twists to create persistent references to functions\n * that can survive worker restarts and be invoked across different execution contexts.\n *\n * This is a branded string type to prevent mixing callback tokens with regular strings.\n *\n * @example\n * ```typescript\n * const callback = await this.callback(this.onCalendarSelected, \"primary\", \"google\");\n * ```\n */\nexport type Callback = string & { readonly __brand: \"Callback\" };\n\n/**\n * Built-in tool for creating and managing persistent callback references.\n *\n * The Callbacks tool enables twists and tools to create callback links that persist\n * across worker invocations and restarts. This is essential for webhook handlers,\n * scheduled operations, and user interaction flows that need to survive runtime\n * boundaries.\n *\n * **Note:** Callback methods are also available directly on Twist and Tool classes\n * via `this.callback()`, `this.deleteCallback()`, `this.deleteAllCallbacks()`, and\n * `this.run()`. This is the recommended approach for most use cases.\n *\n * **When to use callbacks:**\n * - Webhook handlers that need persistent function references\n * - Scheduled operations that run after worker timeouts\n * - User interaction links (ActivityLinkType.callback)\n * - Cross-tool communication that survives restarts\n *\n * **Type Safety:**\n * Callbacks are fully type-safe - extraArgs are type-checked against the function signature.\n *\n * @example\n * ```typescript\n * class MyTool extends Tool {\n *   async setupWebhook() {\n *     // Using built-in callback method (recommended)\n *     const callback = await this.callback(this.handleWebhook, \"calendar\");\n *     return `https://api.plot.day/webhook/${callback}`;\n *   }\n *\n *   async handleWebhook(data: any, webhookType: string) {\n *     console.log(\"Webhook received:\", data, webhookType);\n *   }\n * }\n * ```\n */\nexport abstract class Callbacks extends ITool {\n  /**\n   * Creates a persistent callback to a method on the current class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract create(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback>;\n\n  /**\n   * Creates a persistent callback to a function from the parent twist/tool.\n   * Use this when the callback function is passed in from outside this class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable, validated at runtime)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createFromParent(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback>;\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param callback - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract delete(callback: Callback): Promise<void>;\n\n  /**\n   * Deletes all callbacks for the tool's parent.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  abstract deleteAll(): Promise<void>;\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param callback - The callback token returned by create()\n   * @param args - Optional arguments to pass to the callback function\n   * @returns Promise resolving to the callback result\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract run<T = unknown>(callback: Callback, ...args: any[]): Promise<T>;\n}\n";
+export default "import { ITool } from \"..\";\nimport type { CallbackMethods, NoFunctions, NonFunction } from \"../utils/types\";\n\n// Re-export types for consumers\nexport type { CallbackMethods, NoFunctions, NonFunction };\n\n/**\n * Represents a callback token for persistent function references.\n *\n * Callbacks enable tools and twists to create persistent references to functions\n * that can survive worker restarts and be invoked across different execution contexts.\n *\n * This is a branded string type to prevent mixing callback tokens with regular strings.\n *\n * @example\n * ```typescript\n * const callback = await this.callback(this.onCalendarSelected, \"primary\", \"google\");\n * ```\n */\nexport type Callback = string & { readonly __brand: \"Callback\" };\n\n/**\n * Built-in tool for creating and managing persistent callback references.\n *\n * The Callbacks tool enables twists and tools to create callback links that persist\n * across worker invocations and restarts. This is essential for webhook handlers,\n * scheduled operations, and user interaction flows that need to survive runtime\n * boundaries.\n *\n * **Note:** Callback methods are also available directly on Twist and Tool classes\n * via `this.callback()`, `this.deleteCallback()`, `this.deleteAllCallbacks()`, and\n * `this.run()`. This is the recommended approach for most use cases.\n *\n * **When to use callbacks:**\n * - Webhook handlers that need persistent function references\n * - Scheduled operations that run after worker timeouts\n * - User interaction links (ActivityLinkType.callback)\n * - Cross-tool communication that survives restarts\n *\n * **Type Safety:**\n * Callbacks are fully type-safe - extraArgs are type-checked against the function signature.\n *\n * @example\n * ```typescript\n * class MyTool extends Tool {\n *   async setupWebhook() {\n *     // Using built-in callback method (recommended)\n *     const callback = await this.callback(this.handleWebhook, \"calendar\");\n *     return `https://api.plot.day/webhook/${callback}`;\n *   }\n *\n *   async handleWebhook(data: any, webhookType: string) {\n *     console.log(\"Webhook received:\", data, webhookType);\n *   }\n * }\n * ```\n */\nexport abstract class Callbacks extends ITool {\n  /**\n   * Creates a persistent callback to a method on the current class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract create<Fn extends (...args: any[]) => any>(\n    fn: Fn,\n    ...extraArgs: Parameters<Fn>\n  ): Promise<Callback>;\n\n  /**\n   * Creates a persistent callback to a function from the parent twist/tool.\n   * Use this when the callback function is passed in from outside this class.\n   *\n   * @param fn - The function to callback\n   * @param extraArgs - Additional arguments to pass to the function (must be serializable, validated at runtime)\n   * @returns Promise resolving to a persistent callback token\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createFromParent(\n    fn: Function,\n    ...extraArgs: any[]\n  ): Promise<Callback>;\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param callback - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract delete(callback: Callback): Promise<void>;\n\n  /**\n   * Deletes all callbacks for the tool's parent.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  abstract deleteAll(): Promise<void>;\n\n  /**\n   * Executes a callback by its token.\n   *\n   * @param callback - The callback token returned by create()\n   * @param args - Optional arguments to pass to the callback function\n   * @returns Promise resolving to the callback result\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract run<T = unknown>(callback: Callback, ...args: any[]): Promise<T>;\n}\n";
 //# sourceMappingURL=callbacks.js.map

package/dist/llm-docs/tools/callbacks.js.map

@@ -1 +1 @@
-{"version":3,"file":"callbacks.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/callbacks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,6jIAA6jI,CAAC"}
+{"version":3,"file":"callbacks.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/callbacks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,omIAAomI,CAAC"}

package/dist/llm-docs/tools/integrations.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/integrations
+ * Generated LLM documentation for @plotday/twister/tools/integrations
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts

package/dist/llm-docs/tools/integrations.js

@@ -1,5 +1,5 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/integrations
+ * Generated LLM documentation for @plotday/twister/tools/integrations
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts

package/dist/llm-docs/tools/network.d.ts

@@ -1,9 +1,9 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/network
+ * Generated LLM documentation for @plotday/twister/tools/network
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import { ITool } from \"..\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: any;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook({\n *       callback: this.onCalendarEvent,\n *       extraArgs: [calendarId, \"google\"]\n *     });\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.callback - Function receiving (request, ...extraArgs)\n   * @param options.extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook({\n   *   callback: this.onGmailNotification,\n   *   provider: AuthProvider.Google,\n   *   authorization: gmailAuth,\n   *   extraArgs: [\"inbox\"]\n   * });\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(options: {\n    callback: TCallback;\n    extraArgs?: TCallback extends (req: any, ...rest: infer R) => any ? R : [];\n    provider?: AuthProvider;\n    authorization?: Authorization;\n  }): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
+declare const _default: "import { ITool } from \"..\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: any;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook({\n *       callback: this.onCalendarEvent,\n *       extraArgs: [calendarId, \"google\"]\n *     });\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.callback - Function receiving (request, ...extraArgs)\n   * @param options.extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook({\n   *   callback: this.onGmailNotification,\n   *   provider: AuthProvider.Google,\n   *   authorization: gmailAuth,\n   *   extraArgs: [\"inbox\"]\n   * });\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(options: {\n    callback: TCallback;\n    extraArgs?: TCallback extends (req: any, ...rest: infer R) => any ? R : [];\n    provider?: AuthProvider;\n    authorization?: Authorization;\n  }): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
 export default _default;
 //# sourceMappingURL=network.d.ts.map

package/dist/llm-docs/tools/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/network.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,46NAA46N;AAA37N,wBAA47N"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/network.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,y/NAAy/N;AAAxgO,wBAAygO"}

package/dist/llm-docs/tools/network.js

@@ -1,8 +1,8 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/network
+ * Generated LLM documentation for @plotday/twister/tools/network
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { ITool } from \"..\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: any;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook({\n *       callback: this.onCalendarEvent,\n *       extraArgs: [calendarId, \"google\"]\n *     });\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.callback - Function receiving (request, ...extraArgs)\n   * @param options.extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook({\n   *   callback: this.onGmailNotification,\n   *   provider: AuthProvider.Google,\n   *   authorization: gmailAuth,\n   *   extraArgs: [\"inbox\"]\n   * });\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(options: {\n    callback: TCallback;\n    extraArgs?: TCallback extends (req: any, ...rest: infer R) => any ? R : [];\n    provider?: AuthProvider;\n    authorization?: Authorization;\n  }): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: any;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook({\n *       callback: this.onCalendarEvent,\n *       extraArgs: [calendarId, \"google\"]\n *     });\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.callback - Function receiving (request, ...extraArgs)\n   * @param options.extraArgs - Additional arguments to pass to the callback (type-checked)\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @returns Promise resolving to the webhook URL, or for Gmail, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook({\n   *   callback: this.onGmailNotification,\n   *   provider: AuthProvider.Google,\n   *   authorization: gmailAuth,\n   *   extraArgs: [\"inbox\"]\n   * });\n   * // topicName: \"projects/plot-prod/topics/gmail-webhook-abc123\"\n   *\n   * // Pass topic name to Gmail API\n   * await gmailApi.users.watch({\n   *   userId: 'me',\n   *   requestBody: {\n   *     topicName: topicName,  // Use the returned topic name\n   *     labelIds: ['INBOX']\n   *   }\n   * });\n   * ```\n   */\n  abstract createWebhook<\n    TCallback extends (request: WebhookRequest, ...args: any[]) => any\n  >(options: {\n    callback: TCallback;\n    extraArgs?: TCallback extends (req: any, ...rest: infer R) => any ? R : [];\n    provider?: AuthProvider;\n    authorization?: Authorization;\n  }): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
 //# sourceMappingURL=network.js.map

package/dist/llm-docs/tools/network.js.map

@@ -1 +1 @@
-{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/network.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,46NAA46N,CAAC"}
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/network.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,y/NAAy/N,CAAC"}

package/dist/llm-docs/tools/plot.d.ts

@@ -1,9 +1,9 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/plot
+ * Generated LLM documentation for @plotday/twister/tools/plot
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Activity,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contacts. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Optional changes object containing the previous version and tag modifications\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   doneAt: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   noteType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * @param source - The meta.source value to search for\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(source: string): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
+declare const _default: "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contacts. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   doneAt: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

package/dist/llm-docs/tools/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,07YAA07Y;AAAz8Y,wBAA08Y"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,ipcAAipc;AAAhqc,wBAAiqc"}

package/dist/llm-docs/tools/plot.js

@@ -1,8 +1,8 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/plot
+ * Generated LLM documentation for @plotday/twister/tools/plot
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import {\n  type Activity,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contacts. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Optional changes object containing the previous version and tag modifications\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   doneAt: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   noteType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * @param source - The meta.source value to search for\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(source: string): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
+export default "import {\n  type Activity,\n  type ActivityMeta,\n  type ActivityUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type NewActivity,\n  type NewActivityWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type Tag,\n} from \"..\";\n\nexport enum ActivityAccess {\n  /**\n   * Create new Note on an Activity where the twist was mentioned.\n   * Add/remove tags on Activity or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Activity.\n   * Create new Note in an Activity the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contacts. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for activity mentions.\n * Defines how the twist should respond when mentioned in an activity.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage activities,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome activity\n *     await this.plot.createActivity({\n *       type: ActivityType.Note,\n *       title: \"Welcome to Plot!\",\n *       links: [{\n *         title: \"Get Started\",\n *         type: ActivityLinkType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  static readonly Options: {\n    activity?: {\n      /**\n       * Capability to create Notes and modify tags.\n       */\n      access?: ActivityAccess;\n      /**\n       * Called when an activity created by this twist is updated.\n       * This is often used to implement two-way sync with an external system.\n       *\n       * @param activity - The updated activity\n       * @param changes - Changes to the activity and the previous version\n       */\n      updated?: (\n        activity: Activity,\n        changes: {\n          update: ActivityUpdate;\n          previous: Activity;\n          tagsAdded: Record<Tag, ActorId[]>;\n          tagsRemoved: Record<Tag, ActorId[]>;\n        }\n      ) => Promise<void>;\n    };\n    note?: {\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Called when a note is created on an activity created by this twist.\n       * This is often used to implement two-way sync with an external system,\n       * such as syncing notes as comments back to the source system.\n       *\n       * Notes created by the twist itself are automatically filtered out to prevent loops.\n       * The parent activity is available via note.activity.\n       *\n       * @param note - The newly created note\n       */\n      created?: (note: Note) => Promise<void>;\n    };\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n  };\n\n  /**\n   * Creates a new activity in the Plot system.\n   *\n   * The activity will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewActivity\n   * will be preserved in the created activity.\n   *\n   * @param activity - The activity data to create\n   * @returns Promise resolving to the complete created activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivity(\n    activity: NewActivity | NewActivityWithNotes\n  ): Promise<Activity>;\n\n  /**\n   * Creates multiple activities in a single batch operation.\n   *\n   * This method efficiently creates multiple activities at once, which is\n   * more performant than calling createActivity() multiple times individually.\n   * All activities are created with the same author and access control rules.\n   *\n   * @param activities - Array of activity data to create\n   * @returns Promise resolving to array of created activities\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createActivities(\n    activities: (NewActivity | NewActivityWithNotes)[]\n  ): Promise<Activity[]>;\n\n  /**\n   * Updates an existing activity in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire activity object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the activity's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * When updating scheduling fields (start, end, recurrence*), the database will\n   * automatically recalculate duration and range values to maintain consistency.\n   *\n   * @param activity - The activity update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateActivity({\n   *   id: \"task-123\",\n   *   doneAt: new Date()\n   * });\n   *\n   * // Reschedule an event\n   * await this.plot.updateActivity({\n   *   id: \"event-456\",\n   *   start: new Date(\"2024-03-15T10:00:00Z\"),\n   *   end: new Date(\"2024-03-15T11:00:00Z\")\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateActivity({\n   *   id: \"activity-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   *\n   * // Update a recurring event exception\n   * await this.plot.updateActivity({\n   *   id: \"exception-123\",\n   *   occurrence: new Date(\"2024-03-20T09:00:00Z\"),\n   *   title: \"Rescheduled meeting\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateActivity(activity: ActivityUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within an activity.\n   *\n   * Notes are detailed entries within an activity, ordered by creation time.\n   * Each note can contain markdown content, links, and other detailed information\n   * related to the parent activity.\n   *\n   * @param activity - The activity whose notes to retrieve\n   * @returns Promise resolving to array of notes in the activity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(activity: Activity): Promise<Note[]>;\n\n  /**\n   * Creates a new note in an activity.\n   *\n   * Notes provide detailed content within an activity, supporting markdown,\n   * links, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the complete created note\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with links\n   * await this.plot.createNote({\n   *   activity: { id: \"activity-456\" },\n   *   note: \"Meeting recording available\",\n   *   links: [{\n   *     type: ActivityLinkType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Note>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created notes\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     activity: { id: \"activity-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Note[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Finds an activity by its meta.source.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param source - The meta.source value to search for\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityBySource(\n    source: string,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Finds an activity by its metadata.\n   *\n   * This method enables lookup of activities that were created from external\n   * systems, using the metadata to locate the corresponding Plot activity.\n   * Uses JSON containment matching - the provided meta must be contained\n   * within the activity's meta field.\n   *\n   * By default, archived activities are excluded from the search. Set includeArchived\n   * to true to include them in the results.\n   *\n   * @param meta - The metadata to search for (uses JSON containment matching)\n   * @param includeArchived - Whether to include archived activities in search (default: false)\n   * @returns Promise resolving to the matching activity or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActivityByMeta(\n    meta: ActivityMeta,\n    includeArchived?: boolean\n  ): Promise<Activity | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for activities and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with activities, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n}\n";
 //# sourceMappingURL=plot.js.map

package/dist/llm-docs/tools/plot.js.map

@@ -1 +1 @@
-{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,07YAA07Y,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,ipcAAipc,CAAC"}

package/dist/llm-docs/tools/store.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/store
+ * Generated LLM documentation for @plotday/twister/tools/store
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts

package/dist/llm-docs/tools/store.js

@@ -1,5 +1,5 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/store
+ * Generated LLM documentation for @plotday/twister/tools/store
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts

package/dist/llm-docs/tools/tasks.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/tasks
+ * Generated LLM documentation for @plotday/twister/tools/tasks
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts

package/dist/llm-docs/tools/tasks.js

@@ -1,5 +1,5 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/tasks
+ * Generated LLM documentation for @plotday/twister/tools/tasks
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts

package/dist/llm-docs/tools/twists.d.ts

@@ -1,9 +1,9 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/twists
+ * Generated LLM documentation for @plotday/twister/tools/twists
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import { type Callback, ITool } from \"..\";\n\n/**\n * Twist source code structure containing dependencies and source files.\n */\nexport interface TwistSource {\n  /**\n   * Package dependencies with version specifiers\n   * @example { \"@plotday/sdk\": \"workspace:^\", \"@plotday/tool-google-calendar\": \"^1.0.0\" }\n   */\n  dependencies: Record<string, string>;\n\n  /**\n   * Source files with their content\n   * Must include \"index.ts\" as the entry point\n   * @example { \"index.ts\": \"export default class MyTwist extends Twist {...}\" }\n   */\n  files: Record<string, string>;\n}\n\n/**\n * Represents a log entry from a twist execution.\n */\nexport type Log = {\n  timestamp: Date;\n  environment: \"personal\" | \"private\" | \"review\" | \"public\";\n  severity: \"log\" | \"error\" | \"warn\" | \"info\";\n  message: string;\n};\n\n/**\n * Twist permissions returned after deployment.\n * Nested structure mapping domains to entities to permission flags.\n *\n * Format: { domain: { entity: flags[] } }\n * - domain: Tool name (e.g., \"network\", \"plot\")\n * - entity: Domain-specific identifier (e.g., URL pattern, resource type)\n * - flags: Array of permission flags (\"read\", \"write\", \"update\", \"use\")\n *\n * @example\n * ```typescript\n * {\n *   \"network\": {\n *     \"https://api.example.com/*\": [\"use\"],\n *     \"https://googleapis.com/*\": [\"use\"]\n *   },\n *   \"plot\": {\n *     \"activity:mentioned\": [\"read\", \"write\", \"update\"],\n *     \"priority\": [\"read\", \"write\", \"update\"]\n *   }\n * }\n * ```\n */\nexport type TwistPermissions = Record<string, Record<string, string[]>>;\n\n/**\n * Built-in tool for managing twists and deployments.\n *\n * The Twists tool provides twists with the ability to create twist IDs\n * and programmatically deploy twists.\n *\n * @example\n * ```typescript\n * class TwistBuilderTwist extends Twist {\n *   build(build: ToolBuilder) {\n *    return {\n *      twists: build.get(Twists)\n *    }\n *   }\n *\n *   async activate() {\n *     const twistId = await this.tools.twists.create();\n *     // Display twist ID to user\n *   }\n * }\n * ```\n */\nexport abstract class Twists extends ITool {\n  /**\n   * Creates a new twist ID and grants access to people in the current priority.\n   *\n   * @returns Promise resolving to the generated twist ID\n   * @throws When twist creation fails\n   *\n   * @example\n   * ```typescript\n   * const twistId = await twist.create();\n   * console.log(`Your twist ID: ${twistId}`);\n   * ```\n   */\n  abstract create(): Promise<string>;\n\n  /**\n   * Generates twist source code from a specification using AI.\n   *\n   * This method uses Claude AI to generate TypeScript source code and dependencies\n   * from a markdown specification. The generated source is validated by attempting\n   * to build it, with iterative error correction (up to 3 attempts).\n   *\n   * @param spec - Markdown specification describing the twist functionality\n   * @returns Promise resolving to twist source (dependencies and files)\n   * @throws When generation fails after maximum attempts\n   *\n   * @example\n   * ```typescript\n   * const source = await twist.generate(`\n   * # Calendar Sync Twist\n   *\n   * This twist syncs Google Calendar events to Plot activities.\n   *\n   * ## Features\n   * - Authenticate with Google\n   * - Sync calendar events\n   * - Create activities from events\n   * `);\n   *\n   * // source.dependencies: { \"@plotday/sdk\": \"workspace:^\", ... }\n   * // source.files: { \"index.ts\": \"export default class...\" }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract generate(spec: string): Promise<TwistSource>;\n\n  /**\n   * Deploys a twist programmatically.\n   *\n   * This method provides the same functionality as the plot deploy CLI\n   * command, but can be called from within a twist. Accepts either:\n   * - A pre-bundled module (JavaScript code)\n   * - A source object (dependencies + files) which is built in a sandbox\n   *\n   * @param options - Deployment configuration\n   * @param options.twistId - Twist ID for deployment\n   * @param options.module - Pre-bundled twist module code (mutually exclusive with source)\n   * @param options.source - Twist source code with dependencies (mutually exclusive with module)\n   * @param options.environment - Target environment (defaults to \"personal\")\n   * @param options.name - Optional twist name (required for first deploy)\n   * @param options.description - Optional twist description (required for first deploy)\n   * @param options.dryRun - If true, validates without deploying (returns errors if any)\n   * @returns Promise resolving to deployment result with version and optional errors\n   * @throws When deployment fails or user lacks access\n   *\n   * @example\n   * ```typescript\n   * // Deploy with a module\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   module: 'export default class MyTwist extends Twist {...}',\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   *   description: 'Does something cool'\n   * });\n   * console.log(`Deployed version ${result.version}`);\n   *\n   * // Deploy with source\n   * const source = await twist.generate(spec);\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   * });\n   *\n   * // Validate with dryRun\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   dryRun: true,\n   * });\n   * if (result.errors?.length) {\n   *   console.error('Build errors:', result.errors);\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract deploy(\n    options: {\n      twistId: string;\n      environment?: \"personal\" | \"private\" | \"review\";\n      name?: string;\n      description?: string;\n      dryRun?: boolean;\n    } & (\n      | {\n          module: string;\n        }\n      | {\n          source: TwistSource;\n        }\n    )\n  ): Promise<{\n    version: string;\n    permissions: TwistPermissions;\n    errors?: string[];\n  }>;\n\n  /**\n   * Subscribes to logs from a twist.\n   *\n   * This method registers a callback to receive batches of logs from twist executions.\n   * The callback will be invoked with an array of logs whenever new logs are captured\n   * from the twist's console output.\n   *\n   * @param twistId - Twist ID (root ID) to watch logs for\n   * @param callback - Callback token created via CallbackTool that will receive log batches\n   * @returns Promise that resolves when the subscription is created\n   * @throws When subscription fails\n   *\n   * @example\n   * ```typescript\n   * // Create twist and callback\n   * const twistId = await this.twist.create();\n   * const callback = await this.callback.create(\"onLogs\");\n   *\n   * // Subscribe to logs\n   * await this.twist.watchLogs(twistId, callback);\n   *\n   * // Implement handler\n   * async onLogs(logs: Log[]) {\n   *   for (const log of logs) {\n   *     console.log(`[${log.environment}] ${log.severity}: ${log.message}`);\n   *   }\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract watchLogs(twistId: string, callback: Callback): Promise<void>;\n}\n";
+declare const _default: "import { type Callback, ITool } from \"..\";\n\n/**\n * Twist source code structure containing dependencies and source files.\n */\nexport interface TwistSource {\n  /**\n   * Package dependencies with version specifiers\n   * @example { \"@plotday/twister\": \"workspace:^\", \"@plotday/tool-google-calendar\": \"^1.0.0\" }\n   */\n  dependencies: Record<string, string>;\n\n  /**\n   * Source files with their content\n   * Must include \"index.ts\" as the entry point\n   * @example { \"index.ts\": \"export default class MyTwist extends Twist {...}\" }\n   */\n  files: Record<string, string>;\n}\n\n/**\n * Represents a log entry from a twist execution.\n */\nexport type Log = {\n  timestamp: Date;\n  environment: \"personal\" | \"private\" | \"review\" | \"public\";\n  severity: \"log\" | \"error\" | \"warn\" | \"info\";\n  message: string;\n};\n\n/**\n * Twist permissions returned after deployment.\n * Nested structure mapping domains to entities to permission flags.\n *\n * Format: { domain: { entity: flags[] } }\n * - domain: Tool name (e.g., \"network\", \"plot\")\n * - entity: Domain-specific identifier (e.g., URL pattern, resource type)\n * - flags: Array of permission flags (\"read\", \"write\", \"update\", \"use\")\n *\n * @example\n * ```typescript\n * {\n *   \"network\": {\n *     \"https://api.example.com/*\": [\"use\"],\n *     \"https://googleapis.com/*\": [\"use\"]\n *   },\n *   \"plot\": {\n *     \"activity:mentioned\": [\"read\", \"write\", \"update\"],\n *     \"priority\": [\"read\", \"write\", \"update\"]\n *   }\n * }\n * ```\n */\nexport type TwistPermissions = Record<string, Record<string, string[]>>;\n\n/**\n * Built-in tool for managing twists and deployments.\n *\n * The Twists tool provides twists with the ability to create twist IDs\n * and programmatically deploy twists.\n *\n * @example\n * ```typescript\n * class TwistBuilderTwist extends Twist {\n *   build(build: ToolBuilder) {\n *    return {\n *      twists: build.get(Twists)\n *    }\n *   }\n *\n *   async activate() {\n *     const twistId = await this.tools.twists.create();\n *     // Display twist ID to user\n *   }\n * }\n * ```\n */\nexport abstract class Twists extends ITool {\n  /**\n   * Creates a new twist ID and grants access to people in the current priority.\n   *\n   * @returns Promise resolving to the generated twist ID\n   * @throws When twist creation fails\n   *\n   * @example\n   * ```typescript\n   * const twistId = await twist.create();\n   * console.log(`Your twist ID: ${twistId}`);\n   * ```\n   */\n  abstract create(): Promise<string>;\n\n  /**\n   * Generates twist source code from a specification using AI.\n   *\n   * This method uses Claude AI to generate TypeScript source code and dependencies\n   * from a markdown specification. The generated source is validated by attempting\n   * to build it, with iterative error correction (up to 3 attempts).\n   *\n   * @param spec - Markdown specification describing the twist functionality\n   * @returns Promise resolving to twist source (dependencies and files)\n   * @throws When generation fails after maximum attempts\n   *\n   * @example\n   * ```typescript\n   * const source = await twist.generate(`\n   * # Calendar Sync Twist\n   *\n   * This twist syncs Google Calendar events to Plot activities.\n   *\n   * ## Features\n   * - Authenticate with Google\n   * - Sync calendar events\n   * - Create activities from events\n   * `);\n   *\n   * // source.dependencies: { \"@plotday/twister\": \"workspace:^\", ... }\n   * // source.files: { \"index.ts\": \"export default class...\" }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract generate(spec: string): Promise<TwistSource>;\n\n  /**\n   * Deploys a twist programmatically.\n   *\n   * This method provides the same functionality as the plot deploy CLI\n   * command, but can be called from within a twist. Accepts either:\n   * - A pre-bundled module (JavaScript code)\n   * - A source object (dependencies + files) which is built in a sandbox\n   *\n   * @param options - Deployment configuration\n   * @param options.twistId - Twist ID for deployment\n   * @param options.module - Pre-bundled twist module code (mutually exclusive with source)\n   * @param options.source - Twist source code with dependencies (mutually exclusive with module)\n   * @param options.environment - Target environment (defaults to \"personal\")\n   * @param options.name - Optional twist name (required for first deploy)\n   * @param options.description - Optional twist description (required for first deploy)\n   * @param options.dryRun - If true, validates without deploying (returns errors if any)\n   * @returns Promise resolving to deployment result with version and optional errors\n   * @throws When deployment fails or user lacks access\n   *\n   * @example\n   * ```typescript\n   * // Deploy with a module\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   module: 'export default class MyTwist extends Twist {...}',\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   *   description: 'Does something cool'\n   * });\n   * console.log(`Deployed version ${result.version}`);\n   *\n   * // Deploy with source\n   * const source = await twist.generate(spec);\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   * });\n   *\n   * // Validate with dryRun\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   dryRun: true,\n   * });\n   * if (result.errors?.length) {\n   *   console.error('Build errors:', result.errors);\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract deploy(\n    options: {\n      twistId: string;\n      environment?: \"personal\" | \"private\" | \"review\";\n      name?: string;\n      description?: string;\n      dryRun?: boolean;\n    } & (\n      | {\n          module: string;\n        }\n      | {\n          source: TwistSource;\n        }\n    )\n  ): Promise<{\n    version: string;\n    permissions: TwistPermissions;\n    errors?: string[];\n  }>;\n\n  /**\n   * Subscribes to logs from a twist.\n   *\n   * This method registers a callback to receive batches of logs from twist executions.\n   * The callback will be invoked with an array of logs whenever new logs are captured\n   * from the twist's console output.\n   *\n   * @param twistId - Twist ID (root ID) to watch logs for\n   * @param callback - Callback token created via CallbackTool that will receive log batches\n   * @returns Promise that resolves when the subscription is created\n   * @throws When subscription fails\n   *\n   * @example\n   * ```typescript\n   * // Create twist and callback\n   * const twistId = await this.twist.create();\n   * const callback = await this.callback.create(\"onLogs\");\n   *\n   * // Subscribe to logs\n   * await this.twist.watchLogs(twistId, callback);\n   *\n   * // Implement handler\n   * async onLogs(logs: Log[]) {\n   *   for (const log of logs) {\n   *     console.log(`[${log.environment}] ${log.severity}: ${log.message}`);\n   *   }\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract watchLogs(twistId: string, callback: Callback): Promise<void>;\n}\n";
 export default _default;
 //# sourceMappingURL=twists.d.ts.map

package/dist/llm-docs/tools/twists.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twists.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/twists.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,kuOAAkuO;AAAjvO,wBAAkvO"}
+{"version":3,"file":"twists.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/twists.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,0uOAA0uO;AAAzvO,wBAA0vO"}

package/dist/llm-docs/tools/twists.js

@@ -1,8 +1,8 @@
 /**
- * Generated LLM documentation for @plotday/sdk/tools/twists
+ * Generated LLM documentation for @plotday/twister/tools/twists
  *
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { type Callback, ITool } from \"..\";\n\n/**\n * Twist source code structure containing dependencies and source files.\n */\nexport interface TwistSource {\n  /**\n   * Package dependencies with version specifiers\n   * @example { \"@plotday/sdk\": \"workspace:^\", \"@plotday/tool-google-calendar\": \"^1.0.0\" }\n   */\n  dependencies: Record<string, string>;\n\n  /**\n   * Source files with their content\n   * Must include \"index.ts\" as the entry point\n   * @example { \"index.ts\": \"export default class MyTwist extends Twist {...}\" }\n   */\n  files: Record<string, string>;\n}\n\n/**\n * Represents a log entry from a twist execution.\n */\nexport type Log = {\n  timestamp: Date;\n  environment: \"personal\" | \"private\" | \"review\" | \"public\";\n  severity: \"log\" | \"error\" | \"warn\" | \"info\";\n  message: string;\n};\n\n/**\n * Twist permissions returned after deployment.\n * Nested structure mapping domains to entities to permission flags.\n *\n * Format: { domain: { entity: flags[] } }\n * - domain: Tool name (e.g., \"network\", \"plot\")\n * - entity: Domain-specific identifier (e.g., URL pattern, resource type)\n * - flags: Array of permission flags (\"read\", \"write\", \"update\", \"use\")\n *\n * @example\n * ```typescript\n * {\n *   \"network\": {\n *     \"https://api.example.com/*\": [\"use\"],\n *     \"https://googleapis.com/*\": [\"use\"]\n *   },\n *   \"plot\": {\n *     \"activity:mentioned\": [\"read\", \"write\", \"update\"],\n *     \"priority\": [\"read\", \"write\", \"update\"]\n *   }\n * }\n * ```\n */\nexport type TwistPermissions = Record<string, Record<string, string[]>>;\n\n/**\n * Built-in tool for managing twists and deployments.\n *\n * The Twists tool provides twists with the ability to create twist IDs\n * and programmatically deploy twists.\n *\n * @example\n * ```typescript\n * class TwistBuilderTwist extends Twist {\n *   build(build: ToolBuilder) {\n *    return {\n *      twists: build.get(Twists)\n *    }\n *   }\n *\n *   async activate() {\n *     const twistId = await this.tools.twists.create();\n *     // Display twist ID to user\n *   }\n * }\n * ```\n */\nexport abstract class Twists extends ITool {\n  /**\n   * Creates a new twist ID and grants access to people in the current priority.\n   *\n   * @returns Promise resolving to the generated twist ID\n   * @throws When twist creation fails\n   *\n   * @example\n   * ```typescript\n   * const twistId = await twist.create();\n   * console.log(`Your twist ID: ${twistId}`);\n   * ```\n   */\n  abstract create(): Promise<string>;\n\n  /**\n   * Generates twist source code from a specification using AI.\n   *\n   * This method uses Claude AI to generate TypeScript source code and dependencies\n   * from a markdown specification. The generated source is validated by attempting\n   * to build it, with iterative error correction (up to 3 attempts).\n   *\n   * @param spec - Markdown specification describing the twist functionality\n   * @returns Promise resolving to twist source (dependencies and files)\n   * @throws When generation fails after maximum attempts\n   *\n   * @example\n   * ```typescript\n   * const source = await twist.generate(`\n   * # Calendar Sync Twist\n   *\n   * This twist syncs Google Calendar events to Plot activities.\n   *\n   * ## Features\n   * - Authenticate with Google\n   * - Sync calendar events\n   * - Create activities from events\n   * `);\n   *\n   * // source.dependencies: { \"@plotday/sdk\": \"workspace:^\", ... }\n   * // source.files: { \"index.ts\": \"export default class...\" }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract generate(spec: string): Promise<TwistSource>;\n\n  /**\n   * Deploys a twist programmatically.\n   *\n   * This method provides the same functionality as the plot deploy CLI\n   * command, but can be called from within a twist. Accepts either:\n   * - A pre-bundled module (JavaScript code)\n   * - A source object (dependencies + files) which is built in a sandbox\n   *\n   * @param options - Deployment configuration\n   * @param options.twistId - Twist ID for deployment\n   * @param options.module - Pre-bundled twist module code (mutually exclusive with source)\n   * @param options.source - Twist source code with dependencies (mutually exclusive with module)\n   * @param options.environment - Target environment (defaults to \"personal\")\n   * @param options.name - Optional twist name (required for first deploy)\n   * @param options.description - Optional twist description (required for first deploy)\n   * @param options.dryRun - If true, validates without deploying (returns errors if any)\n   * @returns Promise resolving to deployment result with version and optional errors\n   * @throws When deployment fails or user lacks access\n   *\n   * @example\n   * ```typescript\n   * // Deploy with a module\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   module: 'export default class MyTwist extends Twist {...}',\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   *   description: 'Does something cool'\n   * });\n   * console.log(`Deployed version ${result.version}`);\n   *\n   * // Deploy with source\n   * const source = await twist.generate(spec);\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   * });\n   *\n   * // Validate with dryRun\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   dryRun: true,\n   * });\n   * if (result.errors?.length) {\n   *   console.error('Build errors:', result.errors);\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract deploy(\n    options: {\n      twistId: string;\n      environment?: \"personal\" | \"private\" | \"review\";\n      name?: string;\n      description?: string;\n      dryRun?: boolean;\n    } & (\n      | {\n          module: string;\n        }\n      | {\n          source: TwistSource;\n        }\n    )\n  ): Promise<{\n    version: string;\n    permissions: TwistPermissions;\n    errors?: string[];\n  }>;\n\n  /**\n   * Subscribes to logs from a twist.\n   *\n   * This method registers a callback to receive batches of logs from twist executions.\n   * The callback will be invoked with an array of logs whenever new logs are captured\n   * from the twist's console output.\n   *\n   * @param twistId - Twist ID (root ID) to watch logs for\n   * @param callback - Callback token created via CallbackTool that will receive log batches\n   * @returns Promise that resolves when the subscription is created\n   * @throws When subscription fails\n   *\n   * @example\n   * ```typescript\n   * // Create twist and callback\n   * const twistId = await this.twist.create();\n   * const callback = await this.callback.create(\"onLogs\");\n   *\n   * // Subscribe to logs\n   * await this.twist.watchLogs(twistId, callback);\n   *\n   * // Implement handler\n   * async onLogs(logs: Log[]) {\n   *   for (const log of logs) {\n   *     console.log(`[${log.environment}] ${log.severity}: ${log.message}`);\n   *   }\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract watchLogs(twistId: string, callback: Callback): Promise<void>;\n}\n";
+export default "import { type Callback, ITool } from \"..\";\n\n/**\n * Twist source code structure containing dependencies and source files.\n */\nexport interface TwistSource {\n  /**\n   * Package dependencies with version specifiers\n   * @example { \"@plotday/twister\": \"workspace:^\", \"@plotday/tool-google-calendar\": \"^1.0.0\" }\n   */\n  dependencies: Record<string, string>;\n\n  /**\n   * Source files with their content\n   * Must include \"index.ts\" as the entry point\n   * @example { \"index.ts\": \"export default class MyTwist extends Twist {...}\" }\n   */\n  files: Record<string, string>;\n}\n\n/**\n * Represents a log entry from a twist execution.\n */\nexport type Log = {\n  timestamp: Date;\n  environment: \"personal\" | \"private\" | \"review\" | \"public\";\n  severity: \"log\" | \"error\" | \"warn\" | \"info\";\n  message: string;\n};\n\n/**\n * Twist permissions returned after deployment.\n * Nested structure mapping domains to entities to permission flags.\n *\n * Format: { domain: { entity: flags[] } }\n * - domain: Tool name (e.g., \"network\", \"plot\")\n * - entity: Domain-specific identifier (e.g., URL pattern, resource type)\n * - flags: Array of permission flags (\"read\", \"write\", \"update\", \"use\")\n *\n * @example\n * ```typescript\n * {\n *   \"network\": {\n *     \"https://api.example.com/*\": [\"use\"],\n *     \"https://googleapis.com/*\": [\"use\"]\n *   },\n *   \"plot\": {\n *     \"activity:mentioned\": [\"read\", \"write\", \"update\"],\n *     \"priority\": [\"read\", \"write\", \"update\"]\n *   }\n * }\n * ```\n */\nexport type TwistPermissions = Record<string, Record<string, string[]>>;\n\n/**\n * Built-in tool for managing twists and deployments.\n *\n * The Twists tool provides twists with the ability to create twist IDs\n * and programmatically deploy twists.\n *\n * @example\n * ```typescript\n * class TwistBuilderTwist extends Twist {\n *   build(build: ToolBuilder) {\n *    return {\n *      twists: build.get(Twists)\n *    }\n *   }\n *\n *   async activate() {\n *     const twistId = await this.tools.twists.create();\n *     // Display twist ID to user\n *   }\n * }\n * ```\n */\nexport abstract class Twists extends ITool {\n  /**\n   * Creates a new twist ID and grants access to people in the current priority.\n   *\n   * @returns Promise resolving to the generated twist ID\n   * @throws When twist creation fails\n   *\n   * @example\n   * ```typescript\n   * const twistId = await twist.create();\n   * console.log(`Your twist ID: ${twistId}`);\n   * ```\n   */\n  abstract create(): Promise<string>;\n\n  /**\n   * Generates twist source code from a specification using AI.\n   *\n   * This method uses Claude AI to generate TypeScript source code and dependencies\n   * from a markdown specification. The generated source is validated by attempting\n   * to build it, with iterative error correction (up to 3 attempts).\n   *\n   * @param spec - Markdown specification describing the twist functionality\n   * @returns Promise resolving to twist source (dependencies and files)\n   * @throws When generation fails after maximum attempts\n   *\n   * @example\n   * ```typescript\n   * const source = await twist.generate(`\n   * # Calendar Sync Twist\n   *\n   * This twist syncs Google Calendar events to Plot activities.\n   *\n   * ## Features\n   * - Authenticate with Google\n   * - Sync calendar events\n   * - Create activities from events\n   * `);\n   *\n   * // source.dependencies: { \"@plotday/twister\": \"workspace:^\", ... }\n   * // source.files: { \"index.ts\": \"export default class...\" }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract generate(spec: string): Promise<TwistSource>;\n\n  /**\n   * Deploys a twist programmatically.\n   *\n   * This method provides the same functionality as the plot deploy CLI\n   * command, but can be called from within a twist. Accepts either:\n   * - A pre-bundled module (JavaScript code)\n   * - A source object (dependencies + files) which is built in a sandbox\n   *\n   * @param options - Deployment configuration\n   * @param options.twistId - Twist ID for deployment\n   * @param options.module - Pre-bundled twist module code (mutually exclusive with source)\n   * @param options.source - Twist source code with dependencies (mutually exclusive with module)\n   * @param options.environment - Target environment (defaults to \"personal\")\n   * @param options.name - Optional twist name (required for first deploy)\n   * @param options.description - Optional twist description (required for first deploy)\n   * @param options.dryRun - If true, validates without deploying (returns errors if any)\n   * @returns Promise resolving to deployment result with version and optional errors\n   * @throws When deployment fails or user lacks access\n   *\n   * @example\n   * ```typescript\n   * // Deploy with a module\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   module: 'export default class MyTwist extends Twist {...}',\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   *   description: 'Does something cool'\n   * });\n   * console.log(`Deployed version ${result.version}`);\n   *\n   * // Deploy with source\n   * const source = await twist.generate(spec);\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   * });\n   *\n   * // Validate with dryRun\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   dryRun: true,\n   * });\n   * if (result.errors?.length) {\n   *   console.error('Build errors:', result.errors);\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract deploy(\n    options: {\n      twistId: string;\n      environment?: \"personal\" | \"private\" | \"review\";\n      name?: string;\n      description?: string;\n      dryRun?: boolean;\n    } & (\n      | {\n          module: string;\n        }\n      | {\n          source: TwistSource;\n        }\n    )\n  ): Promise<{\n    version: string;\n    permissions: TwistPermissions;\n    errors?: string[];\n  }>;\n\n  /**\n   * Subscribes to logs from a twist.\n   *\n   * This method registers a callback to receive batches of logs from twist executions.\n   * The callback will be invoked with an array of logs whenever new logs are captured\n   * from the twist's console output.\n   *\n   * @param twistId - Twist ID (root ID) to watch logs for\n   * @param callback - Callback token created via CallbackTool that will receive log batches\n   * @returns Promise that resolves when the subscription is created\n   * @throws When subscription fails\n   *\n   * @example\n   * ```typescript\n   * // Create twist and callback\n   * const twistId = await this.twist.create();\n   * const callback = await this.callback.create(\"onLogs\");\n   *\n   * // Subscribe to logs\n   * await this.twist.watchLogs(twistId, callback);\n   *\n   * // Implement handler\n   * async onLogs(logs: Log[]) {\n   *   for (const log of logs) {\n   *     console.log(`[${log.environment}] ${log.severity}: ${log.message}`);\n   *   }\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract watchLogs(twistId: string, callback: Callback): Promise<void>;\n}\n";
 //# sourceMappingURL=twists.js.map

package/dist/llm-docs/tools/twists.js.map

@@ -1 +1 @@
-{"version":3,"file":"twists.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/twists.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,kuOAAkuO,CAAC"}
+{"version":3,"file":"twists.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/twists.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,0uOAA0uO,CAAC"}

package/dist/llm-docs/twist-guide-template.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: cli/templates/AGENTS.template.md
  */
-declare const _default: "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## twist Structure Pattern\n\n```typescript\nimport {\n  type Activity,\n  twist,\n  type Priority,\n  type ToolBuilder,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot),\n    };\n  }\n\n  async activate(priority: Pick<Priority, \"id\">) {\n    // Called when twist is enabled for a priority\n    // Common actions: request auth, create setup activities\n  }\n\n  async activity(activity: Activity) {\n    // Called when an activity is routed to this twist\n    // Common actions: process external events, update activities\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@plotday/twister\": \"workspace:^\",\n    \"@plotday/tool-google-calendar\": \"workspace:^\"\n  }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const authLink = await this.tools.externalTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Action,\n    title: \"Connect your account\",\n    links: [authLink],\n  });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n  type: ActivityType.Action,\n  title: \"Setup\",\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n  await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n  if (activity.completed) {\n    await this.handleCompletion(activity);\n  }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n  title: \"Open website\",\n  type: ActivityLinkType.url,\n  url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n  title: \"Click me\",\n  type: ActivityLinkType.callback,\n  token: token,\n};\n\n// Add to activity\nawait this.tools.plot.createActivity({\n  type: ActivityType.Action,\n  title: \"Task with links\",\n  links: [urlLink, callbackLink],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Request auth link from tool with callback\n  const authLink = await this.tools.googleTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  // Create activity with auth link\n  const activity = await this.tools.plot.createActivity({\n    type: ActivityType.Action,\n    title: \"Connect Google account\",\n    links: [authLink],\n  });\n\n  // Store for later use\n  await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n  // Store auth token\n  await this.set(`${provider}_auth`, authResult.authToken);\n\n  // Continue setup flow\n  await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data with callbacks:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n\n  await this.tools.calendarTool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    calendarId\n  );\n}\n\nasync handleEvent(activity: Activity, calendarId: string): Promise<void> {\n  // Process incoming event from external service\n  await this.tools.plot.createActivity(activity);\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n  await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n  provider: string,\n  calendars: Calendar[],\n  authToken: string\n): Promise<void> {\n  const links: ActivityLink[] = [];\n\n  for (const calendar of calendars) {\n    const token = await this.callback(\n      this.onCalendarSelected,\n      provider,\n      calendar.id,\n      calendar.name,\n      authToken\n    );\n\n    links.push({\n      title: `\uD83D\uDCC5 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n      type: ActivityLinkType.callback,\n      token: token,\n    });\n  }\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Which calendars would you like to connect?\",\n    links,\n  });\n}\n\nasync onCalendarSelected(\n  link: ActivityLink,\n  provider: string,\n  calendarId: string,\n  calendarName: string,\n  authToken: string\n): Promise<void> {\n  // Start sync for selected calendar\n  await this.tools.tool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    provider,\n    calendarId\n  );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (keep under time limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results\n  for (const item of result.items) {\n    await this.tools.plot.createActivity(item);\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n    });\n\n    // Queue next batch (runs in new execution context)\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      note: `Sync complete: ${state.itemsProcessed + result.items.length} items processed`,\n    });\n  }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    note: `Failed to complete operation: ${error.message}`,\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- Most activity should be `type = ActivityType.Note` with a `title` and `note`, and no `start` or `end`. This represents a typical message. `start` and `end` should only be used for a note if it should be displayed for a specific date or time, such as a birthday.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
+declare const _default: "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Activities and Notes\n\n**CRITICAL CONCEPT**: An **Activity** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that activity.\n\n**Think of an Activity as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message\n3. **Track external items using generated UUIDs** - Store mappings between external IDs and Plot UUIDs for deduplication\n4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`\n\n### Decision Tree\n\n```\nNew event/task/conversation?\n  \u251C\u2500 Yes \u2192 Generate UUID with Uuid.Generate()\n  \u2502         Create new Activity with that UUID\n  \u2502         Store mapping: external_id \u2192 activity_uuid\n  \u2502\n  \u2514\u2500 No (update/reply/comment) \u2192 Look up mapping by external_id\n      \u251C\u2500 Found \u2192 Add Note to existing Activity using stored UUID\n      \u2514\u2500 Not found \u2192 Create new Activity with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Activity,\n  type Priority,\n  type ToolBuilder,\n  twist,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\nimport { Uuid } from \"@plotday/twister/utils/uuid\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot),\n    };\n  }\n\n  async activate(priority: Pick<Priority, \"id\">) {\n    // Called when twist is enabled for a priority\n    // Common actions: request auth, create setup activities\n  }\n\n  async activity(activity: Activity) {\n    // Called when an activity is routed to this twist\n    // Common actions: process external events, update activities\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@plotday/twister\": \"workspace:^\",\n    \"@plotday/tool-google-calendar\": \"workspace:^\"\n  }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const authLink = await this.tools.externalTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect your account\",\n    notes: [\n      {\n        content: \"Click the link below to connect your account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Setup\",\n  notes: [\n    {\n      content: \"Your twist is being set up. Configuration steps will appear here.\",\n    },\n  ],\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n  await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n  if (activity.completed) {\n    await this.handleCompletion(activity);\n  }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n  title: \"Open website\",\n  type: ActivityLinkType.url,\n  url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n  title: \"Click me\",\n  type: ActivityLinkType.callback,\n  token: token,\n};\n\n// Add to activity note\nawait this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Task with links\",\n  notes: [\n    {\n      content: \"Click the links below to take action.\",\n      links: [urlLink, callbackLink],\n    },\n  ],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Request auth link from tool with callback\n  const authLink = await this.tools.googleTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  // Create activity with auth link\n  const activity = await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect Google account\",\n    notes: [\n      {\n        content: \"Click below to connect your Google account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n\n  // Store for later use\n  await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n  // Store auth token\n  await this.set(`${provider}_auth`, authResult.authToken);\n\n  // Continue setup flow\n  await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data - demonstrates adding Notes to existing Activities:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n\n  await this.tools.calendarTool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    calendarId\n  );\n}\n\nasync handleEvent(\n  incomingActivity: NewActivityWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingActivity.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingActivityId = await this.get<Uuid>(mappingKey);\n\n  if (existingActivityId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingActivity.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        activity: { id: existingActivityId },\n        content: incomingActivity.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const activityId = Uuid.Generate();\n  await this.set(mappingKey, activityId);\n\n  // Create new Activity with initial Note (new thread with first message)\n  await this.tools.plot.createActivity({\n    ...incomingActivity,\n    id: activityId,\n  });\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n  await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n  provider: string,\n  calendars: Calendar[],\n  authToken: string\n): Promise<void> {\n  const links: ActivityLink[] = [];\n\n  for (const calendar of calendars) {\n    const token = await this.callback(\n      this.onCalendarSelected,\n      provider,\n      calendar.id,\n      calendar.name,\n      authToken\n    );\n\n    links.push({\n      title: `\uD83D\uDCC5 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n      type: ActivityLinkType.callback,\n      token: token,\n    });\n  }\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Which calendars would you like to connect?\",\n    notes: [\n      {\n        content: \"Select the calendars you want to sync:\",\n        links,\n      },\n    ],\n  });\n}\n\nasync onCalendarSelected(\n  link: ActivityLink,\n  provider: string,\n  calendarId: string,\n  calendarName: string,\n  authToken: string\n): Promise<void> {\n  // Start sync for selected calendar\n  await this.tools.tool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    provider,\n    calendarId\n  );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (keep under time limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results (create activities with Notes)\n  for (const item of result.items) {\n    // Check if already synced\n    const mappingKey = `item_mapping:${resourceId}:${item.id}`;\n    const existingId = await this.get<Uuid>(mappingKey);\n\n    if (!existingId) {\n      // New item - generate UUID and store mapping\n      const activityId = Uuid.Generate();\n      await this.set(mappingKey, activityId);\n\n      await this.tools.plot.createActivity({\n        id: activityId,\n        type: ActivityType.Note,\n        title: item.title,\n        notes: [{ id: Uuid.Generate(), content: item.description }],\n      });\n    }\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n    });\n\n    // Queue next batch (runs in new execution context)\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- **Always create Activities with Notes** - See \"Understanding Activities and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.\n- **Track external items with UUID mappings** - Generate UUIDs with `Uuid.Generate()` and store mappings (`external_id \u2192 uuid`) for deduplication. Never rely on the `source` field.\n- **Add Notes to existing Activities** - Look up stored UUID mappings before creating new Activities. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
 export default _default;
 //# sourceMappingURL=twist-guide-template.d.ts.map

package/dist/llm-docs/twist-guide-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,ynZAA+mZ;AAA9nZ,wBAA+nZ"}
+{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,0lhBAA2/gB;AAA1ghB,wBAA2ghB"}