@plotday/twister 0.53.0 → 0.54.0

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import type { Static, TSchema } from \"typebox\";\n\nimport { ITool } from \"..\";\n\n/**\n * Built-in tool for prompting Large Language Models (LLMs).\n *\n * The AI tool provides twists and tools with access to LLM capabilities\n * for natural language processing, text generation, data extraction,\n * and intelligent decision making within their workflows.\n *\n * **Features:**\n * - Access to multiple AI providers (OpenAI, Anthropic, Google, Workers AI)\n * - Multi-turn conversation support with `messages`\n * - Tool calling with automatic execution\n * - Structured output with Typebox schemas via `outputSchema`\n * - Unified API across all models via Vercel AI SDK\n * - Automatic response parsing and validation with full type inference\n *\n * @example\n * ```typescript\n * import { Type } from \"typebox\";\n *\n * class SmartEmailTool extends Tool {\n *   private ai: AI;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.ai = tools.get(AI);\n *   }\n *\n *   async categorizeEmail(emailContent: string) {\n *     // Define the output schema using Typebox\n *     const schema = Type.Object({\n *       category: Type.Union([\n *         Type.Literal(\"work\"),\n *         Type.Literal(\"personal\"),\n *         Type.Literal(\"spam\"),\n *         Type.Literal(\"promotional\")\n *       ]),\n *       confidence: Type.Number({ minimum: 0, maximum: 1 }),\n *       reasoning: Type.Optional(Type.String())\n *     });\n *\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Classify emails into categories: work, personal, spam, or promotional.\",\n *       prompt: `Categorize this email: ${emailContent}`,\n *       outputSchema: schema\n *     });\n *\n *     return response.output;\n *   }\n *\n *   async generateResponse(emailContent: string) {\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Generate professional email responses that are helpful and concise.\",\n *       prompt: `Write a response to: ${emailContent}`\n *     });\n *\n *     return response.text;\n *   }\n * }\n * ```\n */\nexport abstract class AI extends ITool {\n  /**\n   * Returns which AI capabilities are currently available.\n   * Check this before calling prompt() or embed() to gracefully\n   * handle cases where AI is disabled by the user.\n   */\n  abstract available(): AICapabilities;\n\n  /**\n   * Sends a request to an AI model and returns the response using the Vercel AI SDK.\n   *\n   * Supports text generation, multi-turn conversations, structured outputs,\n   * and tool calling across multiple AI providers via Cloudflare AI Gateway.\n   *\n   * @param request - AI request with model, prompt/messages, and optional configuration\n   * @returns Promise resolving to the AI response with generated text and metadata\n   *\n   * @example\n   * ```typescript\n   * // Simple text generation\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Explain quantum computing in simple terms\"\n   * });\n   * console.log(response.text);\n   *\n   * // Fast and cheap for simple tasks\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"low\" },\n   *   prompt: \"Summarize this text...\"\n   * });\n   * console.log(response.text);\n   *\n   * // With system instructions for complex reasoning\n   * const response = await ai.prompt({\n   *   model: { speed: \"capable\", cost: \"high\" },\n   *   system: \"You are a helpful physics tutor.\",\n   *   prompt: \"Explain quantum entanglement\"\n   * });\n   * console.log(response.text);\n   *\n   * // Multi-turn conversation\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   messages: [\n   *     { role: \"user\", content: \"What is 2+2?\" },\n   *     { role: \"assistant\", content: \"2+2 equals 4.\" },\n   *     { role: \"user\", content: \"What about 3+3?\" }\n   *   ]\n   * });\n   * console.log(response.text);\n   *\n   * // Structured output with Typebox schema\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Extract information: John is 30 years old\",\n   *   outputSchema: Type.Object({\n   *     name: Type.String(),\n   *     age: Type.Number()\n   *   })\n   * });\n   * console.log(response.output); // { name: \"John\", age: 30 }\n   *\n   * // Tool calling\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   prompt: \"What's the weather in San Francisco?\",\n   *   tools: {\n   *     getWeather: {\n   *       description: \"Get weather for a city\",\n   *       parameters: Type.Object({\n   *         city: Type.String()\n   *       }),\n   *       execute: async ({ city }) => {\n   *         return { temp: 72, condition: \"sunny\" };\n   *       }\n   *     }\n   *   }\n   * });\n   * console.log(response.text); // Model's response using tool results\n   * console.log(response.toolCalls); // Array of tool calls made\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract prompt<TOOLS extends AIToolSet, SCHEMA extends TSchema = never>(\n    request: AIRequest<TOOLS, SCHEMA>\n  ): Promise<AIResponse<TOOLS, SCHEMA>>;\n}\n\n/** Options for configuring AI tool usage in a twist. */\nexport type AIOptions = {\n  /** Whether AI is required for this twist to function. Default: true */\n  required?: boolean;\n};\n\n/** Describes which AI capabilities are currently available to this twist. */\nexport type AICapabilities = {\n  /** Whether AI prompting (text generation) is available. */\n  prompt: boolean;\n  /** Whether AI embedding generation is available. */\n  embed: boolean;\n};\n\n/**\n * Model preferences for selecting an AI model based on performance and cost requirements.\n * This allows Plot to match those preferences with user preferences (such as preferred or\n * disallowed providers), as well as availability of newer and better models.\n *\n * @example\n * ```typescript\n * // Fast and cheap - uses Workers AI models like Llama 3.2 1B\n * const response = await ai.prompt({\n *   model: { speed: \"fast\", cost: \"low\" },\n *   prompt: \"Summarize this in one sentence: ...\"\n * });\n *\n * // Balanced performance - uses GPT-5 Mini or Gemini 2.5 Flash\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\" },\n *   prompt: \"Analyze this data...\"\n * });\n *\n * // Most capable - uses Claude Sonnet 4.5 or Opus 4.1\n * const response = await ai.prompt({\n *   model: { speed: \"capable\", cost: \"high\" },\n *   prompt: \"Solve this complex reasoning problem...\"\n * });\n *\n * // Request a specific model with a hint\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\", hint: AIModel.CLAUDE_SONNET_45 },\n *   prompt: \"...\"\n * });\n * ```\n */\nexport type ModelPreferences = {\n  /**\n   * Desired speed tier:\n   * - \"fast\": Optimized for low latency and quick responses\n   * - \"balanced\": Good balance of speed and capability\n   * - \"capable\": Maximum reasoning and problem-solving ability\n   */\n  speed: \"fast\" | \"balanced\" | \"capable\";\n\n  /**\n   * Desired cost tier:\n   * - \"low\": Minimal cost, often using Workers AI models (free/very cheap)\n   * - \"medium\": Moderate pricing for good performance\n   * - \"high\": Premium pricing for best-in-class models\n   */\n  cost: \"low\" | \"medium\" | \"high\";\n\n  /**\n   * Optional hint to suggest a specific model. The system will use this\n   * model if possible, but may override it based on user preferences.\n   */\n  hint?: AIModel;\n};\n\n/**\n * Supported AI models available through Cloudflare AI Gateway and Workers AI.\n *\n * Models are organized by provider:\n * - **OpenAI**: Latest GPT models via AI Gateway\n * - **Anthropic**: Claude models via AI Gateway (prefix with \"anthropic/\")\n * - **Google**: Gemini models via AI Gateway (prefix with \"google-ai-studio/\")\n * - **Workers AI**: Models running on Cloudflare's network (free/low cost)\n */\nexport enum AIModel {\n  // OpenAI models - Latest GPT and reasoning models\n  GPT_5 = \"openai/gpt-5\",\n  GPT_5_PRO = \"openai/gpt-5-pro\",\n  GPT_5_MINI = \"openai/gpt-5-mini\",\n  GPT_5_NANO = \"openai/gpt-5-nano\",\n  GPT_4O = \"openai/gpt-4o\",\n  GPT_4O_MINI = \"openai/gpt-4o-mini\",\n  O3 = \"openai/o3\",\n  O3_MINI = \"openai/o3-mini\",\n\n  // Anthropic models - Claude 4.x series\n  CLAUDE_OPUS_46 = \"anthropic/claude-opus-4-6\",\n  CLAUDE_SONNET_46 = \"anthropic/claude-sonnet-4-6\",\n  CLAUDE_HAIKU_45 = \"anthropic/claude-haiku-4-5\",\n\n  // Google models - Gemini 2.x series\n  GEMINI_25_PRO = \"google/gemini-2.5-pro\",\n  GEMINI_25_FLASH = \"google/gemini-2.5-flash\",\n  GEMINI_25_FLASH_LITE = \"google/gemini-2.5-flash-lite\",\n  GEMINI_20_FLASH = \"google/gemini-2.0-flash\",\n  GEMINI_20_FLASH_LITE = \"google/gemini-2.0-flash-lite\",\n\n  // Cloudflare Workers AI models - Free/low-cost models running on Cloudflare's network\n  LLAMA_4_SCOUT_17B = \"meta/llama-4-scout-17b-16e-instruct\",\n  LLAMA_33_70B = \"meta/llama-3.3-70b-instruct-fp8-fast\",\n  LLAMA_31_8B = \"meta/llama-3.1-8b-instruct-fp8\",\n  LLAMA_32_1B = \"meta/llama-3.2-1b-instruct\",\n  DEEPSEEK_R1_32B = \"deepseek-ai/deepseek-r1-distill-qwen-32b\",\n}\n\n/**\n * Request parameters for AI text generation, matching Vercel AI SDK's generateText() function.\n */\nexport interface AIRequest<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * Model selection preferences based on desired speed and cost characteristics.\n   * Plot will automatically select the best available model matching these preferences.\n   *\n   * @example\n   * // Fast and cheap - good for simple tasks\n   * model: { speed: \"fast\", cost: \"low\" }\n   *\n   * @example\n   * // Balanced performance - general purpose\n   * model: { speed: \"balanced\", cost: \"medium\" }\n   *\n   * @example\n   * // Maximum capability - complex reasoning\n   * model: { speed: \"capable\", cost: \"high\" }\n   *\n   * @example\n   * // With a specific model hint\n   * model: { speed: \"balanced\", cost: \"medium\", hint: \"anthropic/claude-sonnet-4-6\" }\n   */\n  model: ModelPreferences;\n\n  /**\n   * System instructions to guide the model's behavior.\n   */\n  system?: string;\n\n  /**\n   * The user's input prompt. Can be a simple string or an array of messages for multi-turn conversations.\n   */\n  prompt?: string;\n\n  /**\n   * Conversation messages for multi-turn interactions.\n   * Replaces 'prompt' for more complex conversations.\n   */\n  messages?: AIMessage[];\n\n  /**\n   * Tools that the model can call during generation.\n   * Each tool definition includes a description, input schema, and optional execute function.\n   */\n  tools?: TOOLS;\n\n  /**\n   * Controls which tools the model can use.\n   * - \"auto\": Model decides whether to use tools\n   * - \"none\": Model cannot use tools\n   * - \"required\": Model must use at least one tool\n   * - { type: \"tool\", toolName: string }: Model must use specific tool\n   */\n  toolChoice?: ToolChoice<TOOLS>;\n\n  /**\n   * Structured output schema using Typebox.\n   * Typebox schemas are JSON Schema objects that provide full TypeScript type inference.\n   */\n  outputSchema?: SCHEMA;\n\n  /**\n   * Maximum number of tokens to generate.\n   */\n  maxOutputTokens?: number;\n\n  /**\n   * Temperature for controlling randomness (0-2).\n   * Higher values make output more random, lower values more deterministic.\n   */\n  temperature?: number;\n\n  /**\n   * Top P sampling parameter (0-1).\n   * Controls diversity by limiting to top probability tokens.\n   */\n  topP?: number;\n}\n\n/**\n * Response from AI text generation, matching Vercel AI SDK's GenerateTextResult.\n */\nexport interface AIResponse<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * The generated text.\n   */\n  text: string;\n\n  /**\n   * Tool calls made by the model during generation.\n   */\n  toolCalls?: ToolCallArray<TOOLS>;\n\n  /**\n   * Results from tool executions.\n   */\n  toolResults?: ToolResultArray<TOOLS>;\n\n  /**\n   * Reason why the model stopped generating.\n   */\n  finishReason:\n    | \"stop\"\n    | \"length\"\n    | \"content-filter\"\n    | \"tool-calls\"\n    | \"error\"\n    | \"other\"\n    | \"unknown\";\n\n  /**\n   * Token usage information for this generation.\n   */\n  usage: AIUsage;\n\n  /**\n   * Sources used by the model (if supported).\n   */\n  sources?: Array<AISource>;\n\n  /**\n   * Structured output when using outputSchema.\n   * Type is automatically inferred from the Typebox schema.\n   */\n  output?: Static<SCHEMA>;\n\n  /**\n   * Response metadata including messages.\n   */\n  response?: {\n    id?: string;\n    timestamp?: Date;\n    modelId?: string;\n    messages?: AIMessage[];\n  };\n}\n\n// ============================================================================\n// Message Types\n// ============================================================================\n\n/**\n * A system message. It can contain system information.\n *\n * Note: using the \"system\" part of the prompt is strongly preferred\n * to increase the resilience against prompt injection attacks,\n * and because not all providers support several system messages.\n */\nexport type AISystemMessage = {\n  role: \"system\";\n  content: string;\n};\n\n/**\n * A user message. It can contain text or a combination of text and images.\n */\nexport type AIUserMessage = {\n  role: \"user\";\n  content: string | Array<TextPart | ImagePart | FilePart>;\n};\n\n/**\n * An assistant message. It can contain text, tool calls, or a combination of text and tool calls.\n */\nexport type AIAssistantMessage = {\n  role: \"assistant\";\n  content:\n    | string\n    | Array<\n        TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart\n      >;\n};\n\n/**\n * A tool message. It contains the result of one or more tool calls.\n */\nexport type AIToolMessage = {\n  role: \"tool\";\n  content: Array<ToolResultPart>;\n};\n\n/**\n * A message that can be used in the `messages` field of a prompt.\n * It can be a user message, an assistant message, or a tool message.\n */\nexport type AIMessage =\n  | AISystemMessage\n  | AIUserMessage\n  | AIAssistantMessage\n  | AIToolMessage;\n\n// ============================================================================\n// Usage & Sources\n// ============================================================================\n\n/**\n * Represents the number of tokens used in a prompt and completion.\n */\nexport type AIUsage = {\n  /**\n   * The number of tokens used in the prompt.\n   */\n  inputTokens?: number;\n  /**\n   * The number of tokens used in the completion.\n   */\n  outputTokens?: number;\n  /**\n   * The total number of tokens used (promptTokens + completionTokens).\n   */\n  totalTokens?: number;\n  /**\n   * The number of reasoning tokens used in the completion.\n   */\n  reasoningTokens?: number;\n};\n\n/**\n * A source that has been used as input to generate the response.\n */\nexport type AISource =\n  | {\n      type: \"source\";\n      /**\n       * A URL source. This is returned by web search RAG models.\n       */\n      sourceType: \"url\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * The URL of the source.\n       */\n      url: string;\n      /**\n       * The title of the source.\n       */\n      title?: string;\n    }\n  | {\n      type: \"source\";\n      /**\n       * The type of source - document sources reference files/documents.\n       */\n      sourceType: \"document\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * IANA media type of the document (e.g., 'application/pdf').\n       */\n      mediaType: string;\n      /**\n       * The title of the document.\n       */\n      title: string;\n      /**\n       * Optional filename of the document.\n       */\n      filename?: string;\n    };\n\n// ============================================================================\n// Content Parts\n// ============================================================================\n\n/**\n * Text content part of a prompt. It contains a string of text.\n */\nexport interface TextPart {\n  type: \"text\";\n  /**\n   * The text content.\n   */\n  text: string;\n}\n\n/**\n * Data content. Can either be a base64-encoded string, a Uint8Array, or an ArrayBuffer.\n */\nexport type DataContent = string | Uint8Array | ArrayBuffer;\n\n/**\n * Image content part of a prompt. It contains an image.\n */\nexport interface ImagePart {\n  type: \"image\";\n  /**\n   * Image data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the image\n   */\n  image: DataContent | URL;\n  /**\n   * Optional mime type of the image.\n   */\n  mimeType?: string;\n}\n\n/**\n * File content part of a prompt. It contains a file.\n */\nexport interface FilePart {\n  type: \"file\";\n  /**\n   * File data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the file\n   */\n  data: DataContent | URL;\n  /**\n   * Optional filename of the file.\n   */\n  filename?: string;\n  /**\n   * IANA media type of the file.\n   *\n   * @see https://www.iana.org/assignments/media-types/media-types.xhtml\n   */\n  mediaType: string;\n}\n\n/**\n * Reasoning content part of a prompt. It contains a reasoning.\n */\nexport interface ReasoningPart {\n  type: \"reasoning\";\n  /**\n   * The reasoning text.\n   */\n  text: string;\n  /**\n   * An optional signature for verifying that the reasoning originated from the model.\n   */\n  signature?: string;\n}\n\n/**\n * Redacted reasoning content part of a prompt.\n */\nexport interface RedactedReasoningPart {\n  type: \"redacted-reasoning\";\n  /**\n   * Redacted reasoning data.\n   */\n  data: string;\n}\n\n/**\n * Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).\n */\nexport interface ToolCallPart {\n  type: \"tool-call\";\n  /**\n   * ID of the tool call. This ID is used to match the tool call with the tool result.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that is being called.\n   */\n  toolName: string;\n  /**\n   * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.\n   */\n  input: unknown;\n}\n\ntype JSONValue = null | string | number | boolean | JSONObject | JSONArray;\ntype JSONObject = {\n  [key: string]: JSONValue;\n};\ntype JSONArray = JSONValue[];\n\n/**\n * Tool result content part of a prompt. It contains the result of the tool call with the matching ID.\n */\nexport interface ToolResultPart {\n  type: \"tool-result\";\n  /**\n   * ID of the tool call that this result is associated with.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that generated this result.\n   */\n  toolName: string;\n  /**\n   * Result of the tool call. This is a JSON-serializable object.\n   */\n  output:\n    | {\n        type: \"text\";\n        value: string;\n      }\n    | {\n        type: \"json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"error-text\";\n        value: string;\n      }\n    | {\n        type: \"error-json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"content\";\n        value: Array<\n          | {\n              type: \"text\";\n              /**\nText content.\n*/\n              text: string;\n            }\n          | {\n              type: \"media\";\n              /**\nBase-64 encoded media data.\n*/\n              data: string;\n              /**\nIANA media type.\n@see https://www.iana.org/assignments/media-types/media-types.xhtml\n*/\n              mediaType: string;\n            }\n        >;\n      };\n}\n\n// ============================================================================\n// Tool Types\n// ============================================================================\n\ntype ToolParameters = TSchema;\n\ntype inferParameters<PARAMETERS extends ToolParameters> = Static<PARAMETERS>;\n\n/**\n * Options passed to tool execution functions.\n */\nexport interface ToolExecutionOptions {\n  /**\n   * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.\n   */\n  toolCallId: string;\n  /**\n   * Messages that were sent to the language model to initiate the response that contained the tool call.\n   * The messages **do not** include the system prompt nor the assistant response that contained the tool call.\n   */\n  messages: AIMessage[];\n  /**\n   * An optional abort signal that indicates that the overall operation should be aborted.\n   */\n  abortSignal?: AbortSignal;\n}\n\n/**\n * A tool contains the description and the schema of the input that the tool expects.\n * This enables the language model to generate the input.\n *\n * The tool can also contain an optional execute function for the actual execution function of the tool.\n */\nexport type AITool<PARAMETERS extends ToolParameters = any, RESULT = any> = {\n  /**\n   * The schema of the input that the tool expects. The language model will use this to generate the input.\n   * It is also used to validate the output of the language model.\n   * Use descriptions to make the input understandable for the language model.\n   */\n  parameters: PARAMETERS;\n  /**\n   * The schema of the input that the tool expects. The language model will use this to generate the input.\n   * It is also used to validate the output of the language model.\n   * Use descriptions to make the input understandable for the language model.\n   */\n  inputSchema: TSchema;\n  /**\n   * An optional description of what the tool does.\n   * Will be used by the language model to decide whether to use the tool.\n   * Not used for provider-defined tools.\n   */\n  description?: string;\n  /**\n   * An async function that is called with the arguments from the tool call and produces a result.\n   * If not provided, the tool will not be executed automatically.\n   *\n   * @param args - The input of the tool call\n   * @param options - Execution options including abort signal and messages\n   */\n  execute?: (\n    args: inferParameters<PARAMETERS>,\n    options: ToolExecutionOptions\n  ) => PromiseLike<RESULT>;\n} & (\n  | {\n      /**\n       * Function tool.\n       */\n      type?: undefined | \"function\";\n    }\n  | {\n      /**\n       * Provider-defined tool.\n       */\n      type: \"provider-defined\";\n      /**\n       * The ID of the tool. Should follow the format `<provider-name>.<tool-name>`.\n       */\n      id: `${string}.${string}`;\n      /**\n       * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.\n       */\n      args: Record<string, unknown>;\n    }\n);\n\n/**\n * Tool choice for the generation. It supports the following settings:\n *\n * - `auto` (default): the model can choose whether and which tools to call.\n * - `required`: the model must call a tool. It can choose which tool to call.\n * - `none`: the model must not call tools\n * - `{ type: 'tool', toolName: string (typed) }`: the model must call the specified tool\n */\ntype ToolChoice<TOOLS extends Record<string, unknown>> =\n  | \"auto\"\n  | \"none\"\n  | \"required\"\n  | {\n      type: \"tool\";\n      toolName: Extract<keyof TOOLS, string>;\n    };\n\nexport type AIToolSet = Record<\n  string,\n  (\n    | AITool<never, never>\n    | AITool<any, any>\n    | AITool<any, never>\n    | AITool<never, any>\n  ) &\n    Pick<AITool<any, any>, \"execute\">\n>;\n\n// ============================================================================\n// Internal Helper Types\n// ============================================================================\n\ntype ToolCallUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-call\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n};\n\ntype ToolCallArray<TOOLS extends AIToolSet> = Array<ToolCallUnion<TOOLS>>;\n\ntype ToolResultUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-result\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n  result?: unknown;\n};\n\ntype ToolResultArray<TOOLS extends AIToolSet> = Array<ToolResultUnion<TOOLS>>;\n";
+declare const _default: "import type { Static, TSchema } from \"typebox\";\n\nimport { ITool } from \"..\";\n\n/**\n * Built-in tool for prompting Large Language Models (LLMs).\n *\n * The AI tool provides twists and tools with access to LLM capabilities\n * for natural language processing, text generation, data extraction,\n * and intelligent decision making within their workflows.\n *\n * **Features:**\n * - Access to multiple AI providers (OpenAI, Anthropic, Google, Workers AI)\n * - Multi-turn conversation support with `messages`\n * - Tool calling with automatic execution\n * - Structured output with Typebox schemas via `outputSchema`\n * - Unified API across all models via Vercel AI SDK\n * - Automatic response parsing and validation with full type inference\n *\n * @example\n * ```typescript\n * import { Type } from \"typebox\";\n *\n * class SmartEmailTool extends Tool {\n *   private ai: AI;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.ai = tools.get(AI);\n *   }\n *\n *   async categorizeEmail(emailContent: string) {\n *     // Define the output schema using Typebox\n *     const schema = Type.Object({\n *       category: Type.Union([\n *         Type.Literal(\"work\"),\n *         Type.Literal(\"personal\"),\n *         Type.Literal(\"spam\"),\n *         Type.Literal(\"promotional\")\n *       ]),\n *       confidence: Type.Number({ minimum: 0, maximum: 1 }),\n *       reasoning: Type.Optional(Type.String())\n *     });\n *\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Classify emails into categories: work, personal, spam, or promotional.\",\n *       prompt: `Categorize this email: ${emailContent}`,\n *       outputSchema: schema\n *     });\n *\n *     return response.output;\n *   }\n *\n *   async generateResponse(emailContent: string) {\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Generate professional email responses that are helpful and concise.\",\n *       prompt: `Write a response to: ${emailContent}`\n *     });\n *\n *     return response.text;\n *   }\n * }\n * ```\n */\nexport abstract class AI extends ITool {\n  /**\n   * Returns which AI capabilities are currently available.\n   * Check this before calling prompt() or embed() to gracefully\n   * handle cases where AI is disabled by the user.\n   *\n   * Built-in tools are accessed as RPC stubs, so from a twist this call\n   * resolves asynchronously \u2014 always `await` it.\n   */\n  abstract available(): AICapabilities | Promise<AICapabilities>;\n\n  /**\n   * Sends a request to an AI model and returns the response using the Vercel AI SDK.\n   *\n   * Supports text generation, multi-turn conversations, structured outputs,\n   * and tool calling across multiple AI providers via Cloudflare AI Gateway.\n   *\n   * @param request - AI request with model, prompt/messages, and optional configuration\n   * @returns Promise resolving to the AI response with generated text and metadata\n   *\n   * @example\n   * ```typescript\n   * // Simple text generation\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Explain quantum computing in simple terms\"\n   * });\n   * console.log(response.text);\n   *\n   * // Fast and cheap for simple tasks\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"low\" },\n   *   prompt: \"Summarize this text...\"\n   * });\n   * console.log(response.text);\n   *\n   * // With system instructions for complex reasoning\n   * const response = await ai.prompt({\n   *   model: { speed: \"capable\", cost: \"high\" },\n   *   system: \"You are a helpful physics tutor.\",\n   *   prompt: \"Explain quantum entanglement\"\n   * });\n   * console.log(response.text);\n   *\n   * // Multi-turn conversation\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   messages: [\n   *     { role: \"user\", content: \"What is 2+2?\" },\n   *     { role: \"assistant\", content: \"2+2 equals 4.\" },\n   *     { role: \"user\", content: \"What about 3+3?\" }\n   *   ]\n   * });\n   * console.log(response.text);\n   *\n   * // Structured output with Typebox schema\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Extract information: John is 30 years old\",\n   *   outputSchema: Type.Object({\n   *     name: Type.String(),\n   *     age: Type.Number()\n   *   })\n   * });\n   * console.log(response.output); // { name: \"John\", age: 30 }\n   *\n   * // Tool calling\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   prompt: \"What's the weather in San Francisco?\",\n   *   tools: {\n   *     getWeather: {\n   *       description: \"Get weather for a city\",\n   *       inputSchema: Type.Object({\n   *         city: Type.String()\n   *       }),\n   *       execute: async ({ city }) => {\n   *         return { temp: 72, condition: \"sunny\" };\n   *       }\n   *     }\n   *   }\n   * });\n   * console.log(response.text); // Model's response using tool results\n   * console.log(response.toolCalls); // Array of tool calls made\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract prompt<TOOLS extends AIToolSet, SCHEMA extends TSchema = never>(\n    request: AIRequest<TOOLS, SCHEMA>\n  ): Promise<AIResponse<TOOLS, SCHEMA>>;\n}\n\n/** Options for configuring AI tool usage in a twist. */\nexport type AIOptions = {\n  /** Whether AI is required for this twist to function. Default: true */\n  required?: boolean;\n};\n\n/** Describes which AI capabilities are currently available to this twist. */\nexport type AICapabilities = {\n  /** Whether AI prompting (text generation) is available. */\n  prompt: boolean;\n  /** Whether AI embedding generation is available. */\n  embed: boolean;\n  /**\n   * Whether provider-native web search is available. True for Plot AI and\n   * Anthropic/Google BYOK providers; false for OpenAI/custom BYOK providers\n   * that don't expose a server-side web search tool through this runtime.\n   */\n  webSearch: boolean;\n};\n\n/**\n * Model preferences for selecting an AI model based on performance and cost requirements.\n * This allows Plot to match those preferences with user preferences (such as preferred or\n * disallowed providers), as well as availability of newer and better models.\n *\n * @example\n * ```typescript\n * // Fast and cheap - uses Workers AI models like Llama 3.2 1B\n * const response = await ai.prompt({\n *   model: { speed: \"fast\", cost: \"low\" },\n *   prompt: \"Summarize this in one sentence: ...\"\n * });\n *\n * // Balanced performance - uses GPT-5 Mini or Gemini 2.5 Flash\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\" },\n *   prompt: \"Analyze this data...\"\n * });\n *\n * // Most capable - uses Claude Sonnet 4.5 or Opus 4.1\n * const response = await ai.prompt({\n *   model: { speed: \"capable\", cost: \"high\" },\n *   prompt: \"Solve this complex reasoning problem...\"\n * });\n *\n * // Request a specific model with a hint\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\", hint: AIModel.CLAUDE_SONNET_45 },\n *   prompt: \"...\"\n * });\n * ```\n */\nexport type ModelPreferences = {\n  /**\n   * Desired speed tier:\n   * - \"fast\": Optimized for low latency and quick responses\n   * - \"balanced\": Good balance of speed and capability\n   * - \"capable\": Maximum reasoning and problem-solving ability\n   */\n  speed: \"fast\" | \"balanced\" | \"capable\";\n\n  /**\n   * Desired cost tier:\n   * - \"low\": Minimal cost, often using Workers AI models (free/very cheap)\n   * - \"medium\": Moderate pricing for good performance\n   * - \"high\": Premium pricing for best-in-class models\n   */\n  cost: \"low\" | \"medium\" | \"high\";\n\n  /**\n   * Optional hint to suggest a specific model. The system will use this\n   * model if possible, but may override it based on user preferences.\n   */\n  hint?: AIModel;\n};\n\n/**\n * Supported AI models available through Cloudflare AI Gateway and Workers AI.\n *\n * Models are organized by provider:\n * - **OpenAI**: Latest GPT models via AI Gateway\n * - **Anthropic**: Claude models via AI Gateway (prefix with \"anthropic/\")\n * - **Google**: Gemini models via AI Gateway (prefix with \"google-ai-studio/\")\n * - **Workers AI**: Models running on Cloudflare's network (free/low cost)\n */\nexport enum AIModel {\n  // OpenAI models - Latest GPT and reasoning models\n  GPT_5 = \"openai/gpt-5\",\n  GPT_5_PRO = \"openai/gpt-5-pro\",\n  GPT_5_MINI = \"openai/gpt-5-mini\",\n  GPT_5_NANO = \"openai/gpt-5-nano\",\n  GPT_4O = \"openai/gpt-4o\",\n  GPT_4O_MINI = \"openai/gpt-4o-mini\",\n  O3 = \"openai/o3\",\n  O3_MINI = \"openai/o3-mini\",\n\n  // Anthropic models - Claude 4.x series\n  CLAUDE_OPUS_46 = \"anthropic/claude-opus-4-6\",\n  CLAUDE_SONNET_46 = \"anthropic/claude-sonnet-4-6\",\n  CLAUDE_HAIKU_45 = \"anthropic/claude-haiku-4-5\",\n\n  // Google models - Gemini 2.x series\n  GEMINI_25_PRO = \"google/gemini-2.5-pro\",\n  GEMINI_25_FLASH = \"google/gemini-2.5-flash\",\n  GEMINI_25_FLASH_LITE = \"google/gemini-2.5-flash-lite\",\n  GEMINI_20_FLASH = \"google/gemini-2.0-flash\",\n  GEMINI_20_FLASH_LITE = \"google/gemini-2.0-flash-lite\",\n\n  // Cloudflare Workers AI models - Free/low-cost models running on Cloudflare's network\n  LLAMA_4_SCOUT_17B = \"meta/llama-4-scout-17b-16e-instruct\",\n  LLAMA_33_70B = \"meta/llama-3.3-70b-instruct-fp8-fast\",\n  LLAMA_31_8B = \"meta/llama-3.1-8b-instruct-fp8\",\n  LLAMA_32_1B = \"meta/llama-3.2-1b-instruct\",\n  DEEPSEEK_R1_32B = \"deepseek-ai/deepseek-r1-distill-qwen-32b\",\n}\n\n/**\n * Request parameters for AI text generation, matching Vercel AI SDK's generateText() function.\n */\nexport interface AIRequest<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * Model selection preferences based on desired speed and cost characteristics.\n   * Plot will automatically select the best available model matching these preferences.\n   *\n   * @example\n   * // Fast and cheap - good for simple tasks\n   * model: { speed: \"fast\", cost: \"low\" }\n   *\n   * @example\n   * // Balanced performance - general purpose\n   * model: { speed: \"balanced\", cost: \"medium\" }\n   *\n   * @example\n   * // Maximum capability - complex reasoning\n   * model: { speed: \"capable\", cost: \"high\" }\n   *\n   * @example\n   * // With a specific model hint\n   * model: { speed: \"balanced\", cost: \"medium\", hint: \"anthropic/claude-sonnet-4-6\" }\n   */\n  model: ModelPreferences;\n\n  /**\n   * System instructions to guide the model's behavior.\n   */\n  system?: string;\n\n  /**\n   * The user's input prompt. Can be a simple string or an array of messages for multi-turn conversations.\n   */\n  prompt?: string;\n\n  /**\n   * Conversation messages for multi-turn interactions.\n   * Replaces 'prompt' for more complex conversations.\n   */\n  messages?: AIMessage[];\n\n  /**\n   * Tools that the model can call during generation.\n   * Each tool definition includes a description, input schema, and optional execute function.\n   */\n  tools?: TOOLS;\n\n  /**\n   * Controls which tools the model can use.\n   * - \"auto\": Model decides whether to use tools\n   * - \"none\": Model cannot use tools\n   * - \"required\": Model must use at least one tool\n   * - { type: \"tool\", toolName: string }: Model must use specific tool\n   */\n  toolChoice?: ToolChoice<TOOLS>;\n\n  /**\n   * Structured output schema using Typebox.\n   * Typebox schemas are JSON Schema objects that provide full TypeScript type inference.\n   */\n  outputSchema?: SCHEMA;\n\n  /**\n   * Maximum number of tokens to generate.\n   */\n  maxOutputTokens?: number;\n\n  /**\n   * Temperature for controlling randomness (0-2).\n   * Higher values make output more random, lower values more deterministic.\n   */\n  temperature?: number;\n\n  /**\n   * Top P sampling parameter (0-1).\n   * Controls diversity by limiting to top probability tokens.\n   */\n  topP?: number;\n\n  /**\n   * Enable provider-native web search so the model can retrieve\n   * up-to-date information from the web. The search is executed\n   * server-side by the provider and any pages used are returned in\n   * {@link AIResponse.sources}.\n   *\n   * Only available on web-search-capable providers (Anthropic and\n   * Google). Check {@link AICapabilities.webSearch} via `available()`\n   * before relying on it; on unsupported providers the flag is ignored.\n   *\n   * Pass `true` for defaults, or an object to cap the number of searches.\n   */\n  webSearch?: boolean | { maxUses?: number };\n\n  /**\n   * Maximum number of sequential generation steps for agentic tool use.\n   * When the model calls a tool, its result is fed back and the model is\n   * called again, up to `maxSteps` times, until it produces a final answer.\n   *\n   * Defaults to 1 (single step \u2014 tool calls are returned but not looped),\n   * preserving prior behavior. Set higher (e.g. 6) to let the model chain\n   * tool calls into a final answer.\n   */\n  maxSteps?: number;\n}\n\n/**\n * Response from AI text generation, matching Vercel AI SDK's GenerateTextResult.\n */\nexport interface AIResponse<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * The generated text.\n   */\n  text: string;\n\n  /**\n   * Tool calls made by the model during generation.\n   */\n  toolCalls?: ToolCallArray<TOOLS>;\n\n  /**\n   * Results from tool executions.\n   */\n  toolResults?: ToolResultArray<TOOLS>;\n\n  /**\n   * Reason why the model stopped generating.\n   */\n  finishReason:\n    | \"stop\"\n    | \"length\"\n    | \"content-filter\"\n    | \"tool-calls\"\n    | \"error\"\n    | \"other\"\n    | \"unknown\";\n\n  /**\n   * Token usage information for this generation.\n   */\n  usage: AIUsage;\n\n  /**\n   * Sources used by the model (if supported).\n   */\n  sources?: Array<AISource>;\n\n  /**\n   * Structured output when using outputSchema.\n   * Type is automatically inferred from the Typebox schema.\n   */\n  output?: Static<SCHEMA>;\n\n  /**\n   * Response metadata including messages.\n   */\n  response?: {\n    id?: string;\n    timestamp?: Date;\n    modelId?: string;\n    messages?: AIMessage[];\n  };\n}\n\n// ============================================================================\n// Message Types\n// ============================================================================\n\n/**\n * A system message. It can contain system information.\n *\n * Note: using the \"system\" part of the prompt is strongly preferred\n * to increase the resilience against prompt injection attacks,\n * and because not all providers support several system messages.\n */\nexport type AISystemMessage = {\n  role: \"system\";\n  content: string;\n};\n\n/**\n * A user message. It can contain text or a combination of text and images.\n */\nexport type AIUserMessage = {\n  role: \"user\";\n  content: string | Array<TextPart | ImagePart | FilePart>;\n};\n\n/**\n * An assistant message. It can contain text, tool calls, or a combination of text and tool calls.\n */\nexport type AIAssistantMessage = {\n  role: \"assistant\";\n  content:\n    | string\n    | Array<\n        TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart\n      >;\n};\n\n/**\n * A tool message. It contains the result of one or more tool calls.\n */\nexport type AIToolMessage = {\n  role: \"tool\";\n  content: Array<ToolResultPart>;\n};\n\n/**\n * A message that can be used in the `messages` field of a prompt.\n * It can be a user message, an assistant message, or a tool message.\n */\nexport type AIMessage =\n  | AISystemMessage\n  | AIUserMessage\n  | AIAssistantMessage\n  | AIToolMessage;\n\n// ============================================================================\n// Usage & Sources\n// ============================================================================\n\n/**\n * Represents the number of tokens used in a prompt and completion.\n */\nexport type AIUsage = {\n  /**\n   * The number of tokens used in the prompt.\n   */\n  inputTokens?: number;\n  /**\n   * The number of tokens used in the completion.\n   */\n  outputTokens?: number;\n  /**\n   * The total number of tokens used (promptTokens + completionTokens).\n   */\n  totalTokens?: number;\n  /**\n   * The number of reasoning tokens used in the completion.\n   */\n  reasoningTokens?: number;\n};\n\n/**\n * A source that has been used as input to generate the response.\n */\nexport type AISource =\n  | {\n      type: \"source\";\n      /**\n       * A URL source. This is returned by web search RAG models.\n       */\n      sourceType: \"url\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * The URL of the source.\n       */\n      url: string;\n      /**\n       * The title of the source.\n       */\n      title?: string;\n    }\n  | {\n      type: \"source\";\n      /**\n       * The type of source - document sources reference files/documents.\n       */\n      sourceType: \"document\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * IANA media type of the document (e.g., 'application/pdf').\n       */\n      mediaType: string;\n      /**\n       * The title of the document.\n       */\n      title: string;\n      /**\n       * Optional filename of the document.\n       */\n      filename?: string;\n    };\n\n// ============================================================================\n// Content Parts\n// ============================================================================\n\n/**\n * Text content part of a prompt. It contains a string of text.\n */\nexport interface TextPart {\n  type: \"text\";\n  /**\n   * The text content.\n   */\n  text: string;\n}\n\n/**\n * Data content. Can either be a base64-encoded string, a Uint8Array, or an ArrayBuffer.\n */\nexport type DataContent = string | Uint8Array | ArrayBuffer;\n\n/**\n * Image content part of a prompt. It contains an image.\n */\nexport interface ImagePart {\n  type: \"image\";\n  /**\n   * Image data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the image\n   */\n  image: DataContent | URL;\n  /**\n   * Optional mime type of the image.\n   */\n  mimeType?: string;\n}\n\n/**\n * File content part of a prompt. It contains a file.\n */\nexport interface FilePart {\n  type: \"file\";\n  /**\n   * File data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the file\n   */\n  data: DataContent | URL;\n  /**\n   * Optional filename of the file.\n   */\n  filename?: string;\n  /**\n   * IANA media type of the file.\n   *\n   * @see https://www.iana.org/assignments/media-types/media-types.xhtml\n   */\n  mediaType: string;\n}\n\n/**\n * Reasoning content part of a prompt. It contains a reasoning.\n */\nexport interface ReasoningPart {\n  type: \"reasoning\";\n  /**\n   * The reasoning text.\n   */\n  text: string;\n  /**\n   * An optional signature for verifying that the reasoning originated from the model.\n   */\n  signature?: string;\n}\n\n/**\n * Redacted reasoning content part of a prompt.\n */\nexport interface RedactedReasoningPart {\n  type: \"redacted-reasoning\";\n  /**\n   * Redacted reasoning data.\n   */\n  data: string;\n}\n\n/**\n * Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).\n */\nexport interface ToolCallPart {\n  type: \"tool-call\";\n  /**\n   * ID of the tool call. This ID is used to match the tool call with the tool result.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that is being called.\n   */\n  toolName: string;\n  /**\n   * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.\n   */\n  input: unknown;\n}\n\ntype JSONValue = null | string | number | boolean | JSONObject | JSONArray;\ntype JSONObject = {\n  [key: string]: JSONValue;\n};\ntype JSONArray = JSONValue[];\n\n/**\n * Tool result content part of a prompt. It contains the result of the tool call with the matching ID.\n */\nexport interface ToolResultPart {\n  type: \"tool-result\";\n  /**\n   * ID of the tool call that this result is associated with.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that generated this result.\n   */\n  toolName: string;\n  /**\n   * Result of the tool call. This is a JSON-serializable object.\n   */\n  output:\n    | {\n        type: \"text\";\n        value: string;\n      }\n    | {\n        type: \"json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"error-text\";\n        value: string;\n      }\n    | {\n        type: \"error-json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"content\";\n        value: Array<\n          | {\n              type: \"text\";\n              /**\nText content.\n*/\n              text: string;\n            }\n          | {\n              type: \"media\";\n              /**\nBase-64 encoded media data.\n*/\n              data: string;\n              /**\nIANA media type.\n@see https://www.iana.org/assignments/media-types/media-types.xhtml\n*/\n              mediaType: string;\n            }\n        >;\n      };\n}\n\n// ============================================================================\n// Tool Types\n// ============================================================================\n\ntype ToolParameters = TSchema;\n\ntype inferParameters<PARAMETERS extends ToolParameters> = Static<PARAMETERS>;\n\n/**\n * Options passed to tool execution functions.\n */\nexport interface ToolExecutionOptions {\n  /**\n   * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.\n   */\n  toolCallId: string;\n  /**\n   * Messages that were sent to the language model to initiate the response that contained the tool call.\n   * The messages **do not** include the system prompt nor the assistant response that contained the tool call.\n   */\n  messages: AIMessage[];\n  /**\n   * An optional abort signal that indicates that the overall operation should be aborted.\n   */\n  abortSignal?: AbortSignal;\n}\n\n/**\n * A tool contains the description and the schema of the input that the tool expects.\n * This enables the language model to generate the input.\n *\n * The tool can also contain an optional execute function for the actual execution function of the tool.\n */\nexport type AITool<PARAMETERS extends ToolParameters = any, RESULT = any> = {\n  /**\n   * The schema of the input that the tool expects, expressed as a Typebox\n   * schema. The language model uses this to generate (and the runtime to\n   * validate) the tool input. Use field descriptions to make the input\n   * understandable for the model.\n   *\n   * This is the canonical field read by the runtime. `parameters` is an\n   * accepted alias for backwards compatibility.\n   */\n  inputSchema: TSchema;\n  /**\n   * @deprecated Alias for {@link inputSchema}. Prefer `inputSchema`.\n   */\n  parameters?: PARAMETERS;\n  /**\n   * An optional description of what the tool does.\n   * Will be used by the language model to decide whether to use the tool.\n   * Not used for provider-defined tools.\n   */\n  description?: string;\n  /**\n   * An async function that is called with the arguments from the tool call and produces a result.\n   * If not provided, the tool will not be executed automatically.\n   *\n   * @param args - The input of the tool call\n   * @param options - Execution options including abort signal and messages\n   */\n  execute?: (\n    args: inferParameters<PARAMETERS>,\n    options: ToolExecutionOptions\n  ) => PromiseLike<RESULT>;\n} & (\n  | {\n      /**\n       * Function tool.\n       */\n      type?: undefined | \"function\";\n    }\n  | {\n      /**\n       * Provider-defined tool.\n       */\n      type: \"provider-defined\";\n      /**\n       * The ID of the tool. Should follow the format `<provider-name>.<tool-name>`.\n       */\n      id: `${string}.${string}`;\n      /**\n       * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.\n       */\n      args: Record<string, unknown>;\n    }\n);\n\n/**\n * Tool choice for the generation. It supports the following settings:\n *\n * - `auto` (default): the model can choose whether and which tools to call.\n * - `required`: the model must call a tool. It can choose which tool to call.\n * - `none`: the model must not call tools\n * - `{ type: 'tool', toolName: string (typed) }`: the model must call the specified tool\n */\ntype ToolChoice<TOOLS extends Record<string, unknown>> =\n  | \"auto\"\n  | \"none\"\n  | \"required\"\n  | {\n      type: \"tool\";\n      toolName: Extract<keyof TOOLS, string>;\n    };\n\nexport type AIToolSet = Record<\n  string,\n  (\n    | AITool<never, never>\n    | AITool<any, any>\n    | AITool<any, never>\n    | AITool<never, any>\n  ) &\n    Pick<AITool<any, any>, \"execute\">\n>;\n\n// ============================================================================\n// Internal Helper Types\n// ============================================================================\n\ntype ToolCallUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-call\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n};\n\ntype ToolCallArray<TOOLS extends AIToolSet> = Array<ToolCallUnion<TOOLS>>;\n\ntype ToolResultUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-result\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n  result?: unknown;\n};\n\ntype ToolResultArray<TOOLS extends AIToolSet> = Array<ToolResultUnion<TOOLS>>;\n";
 export default _default;
 //# sourceMappingURL=ai.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/ai.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,qnwBAAqnwB;AAApowB,wBAAqowB"}
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/ai.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,yhzBAA+gzB;AAA9hzB,wBAA+hzB"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import type { Static, TSchema } from \"typebox\";\n\nimport { ITool } from \"..\";\n\n/**\n * Built-in tool for prompting Large Language Models (LLMs).\n *\n * The AI tool provides twists and tools with access to LLM capabilities\n * for natural language processing, text generation, data extraction,\n * and intelligent decision making within their workflows.\n *\n * **Features:**\n * - Access to multiple AI providers (OpenAI, Anthropic, Google, Workers AI)\n * - Multi-turn conversation support with `messages`\n * - Tool calling with automatic execution\n * - Structured output with Typebox schemas via `outputSchema`\n * - Unified API across all models via Vercel AI SDK\n * - Automatic response parsing and validation with full type inference\n *\n * @example\n * ```typescript\n * import { Type } from \"typebox\";\n *\n * class SmartEmailTool extends Tool {\n *   private ai: AI;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.ai = tools.get(AI);\n *   }\n *\n *   async categorizeEmail(emailContent: string) {\n *     // Define the output schema using Typebox\n *     const schema = Type.Object({\n *       category: Type.Union([\n *         Type.Literal(\"work\"),\n *         Type.Literal(\"personal\"),\n *         Type.Literal(\"spam\"),\n *         Type.Literal(\"promotional\")\n *       ]),\n *       confidence: Type.Number({ minimum: 0, maximum: 1 }),\n *       reasoning: Type.Optional(Type.String())\n *     });\n *\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Classify emails into categories: work, personal, spam, or promotional.\",\n *       prompt: `Categorize this email: ${emailContent}`,\n *       outputSchema: schema\n *     });\n *\n *     return response.output;\n *   }\n *\n *   async generateResponse(emailContent: string) {\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Generate professional email responses that are helpful and concise.\",\n *       prompt: `Write a response to: ${emailContent}`\n *     });\n *\n *     return response.text;\n *   }\n * }\n * ```\n */\nexport abstract class AI extends ITool {\n  /**\n   * Returns which AI capabilities are currently available.\n   * Check this before calling prompt() or embed() to gracefully\n   * handle cases where AI is disabled by the user.\n   */\n  abstract available(): AICapabilities;\n\n  /**\n   * Sends a request to an AI model and returns the response using the Vercel AI SDK.\n   *\n   * Supports text generation, multi-turn conversations, structured outputs,\n   * and tool calling across multiple AI providers via Cloudflare AI Gateway.\n   *\n   * @param request - AI request with model, prompt/messages, and optional configuration\n   * @returns Promise resolving to the AI response with generated text and metadata\n   *\n   * @example\n   * ```typescript\n   * // Simple text generation\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Explain quantum computing in simple terms\"\n   * });\n   * console.log(response.text);\n   *\n   * // Fast and cheap for simple tasks\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"low\" },\n   *   prompt: \"Summarize this text...\"\n   * });\n   * console.log(response.text);\n   *\n   * // With system instructions for complex reasoning\n   * const response = await ai.prompt({\n   *   model: { speed: \"capable\", cost: \"high\" },\n   *   system: \"You are a helpful physics tutor.\",\n   *   prompt: \"Explain quantum entanglement\"\n   * });\n   * console.log(response.text);\n   *\n   * // Multi-turn conversation\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   messages: [\n   *     { role: \"user\", content: \"What is 2+2?\" },\n   *     { role: \"assistant\", content: \"2+2 equals 4.\" },\n   *     { role: \"user\", content: \"What about 3+3?\" }\n   *   ]\n   * });\n   * console.log(response.text);\n   *\n   * // Structured output with Typebox schema\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Extract information: John is 30 years old\",\n   *   outputSchema: Type.Object({\n   *     name: Type.String(),\n   *     age: Type.Number()\n   *   })\n   * });\n   * console.log(response.output); // { name: \"John\", age: 30 }\n   *\n   * // Tool calling\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   prompt: \"What's the weather in San Francisco?\",\n   *   tools: {\n   *     getWeather: {\n   *       description: \"Get weather for a city\",\n   *       parameters: Type.Object({\n   *         city: Type.String()\n   *       }),\n   *       execute: async ({ city }) => {\n   *         return { temp: 72, condition: \"sunny\" };\n   *       }\n   *     }\n   *   }\n   * });\n   * console.log(response.text); // Model's response using tool results\n   * console.log(response.toolCalls); // Array of tool calls made\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract prompt<TOOLS extends AIToolSet, SCHEMA extends TSchema = never>(\n    request: AIRequest<TOOLS, SCHEMA>\n  ): Promise<AIResponse<TOOLS, SCHEMA>>;\n}\n\n/** Options for configuring AI tool usage in a twist. */\nexport type AIOptions = {\n  /** Whether AI is required for this twist to function. Default: true */\n  required?: boolean;\n};\n\n/** Describes which AI capabilities are currently available to this twist. */\nexport type AICapabilities = {\n  /** Whether AI prompting (text generation) is available. */\n  prompt: boolean;\n  /** Whether AI embedding generation is available. */\n  embed: boolean;\n};\n\n/**\n * Model preferences for selecting an AI model based on performance and cost requirements.\n * This allows Plot to match those preferences with user preferences (such as preferred or\n * disallowed providers), as well as availability of newer and better models.\n *\n * @example\n * ```typescript\n * // Fast and cheap - uses Workers AI models like Llama 3.2 1B\n * const response = await ai.prompt({\n *   model: { speed: \"fast\", cost: \"low\" },\n *   prompt: \"Summarize this in one sentence: ...\"\n * });\n *\n * // Balanced performance - uses GPT-5 Mini or Gemini 2.5 Flash\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\" },\n *   prompt: \"Analyze this data...\"\n * });\n *\n * // Most capable - uses Claude Sonnet 4.5 or Opus 4.1\n * const response = await ai.prompt({\n *   model: { speed: \"capable\", cost: \"high\" },\n *   prompt: \"Solve this complex reasoning problem...\"\n * });\n *\n * // Request a specific model with a hint\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\", hint: AIModel.CLAUDE_SONNET_45 },\n *   prompt: \"...\"\n * });\n * ```\n */\nexport type ModelPreferences = {\n  /**\n   * Desired speed tier:\n   * - \"fast\": Optimized for low latency and quick responses\n   * - \"balanced\": Good balance of speed and capability\n   * - \"capable\": Maximum reasoning and problem-solving ability\n   */\n  speed: \"fast\" | \"balanced\" | \"capable\";\n\n  /**\n   * Desired cost tier:\n   * - \"low\": Minimal cost, often using Workers AI models (free/very cheap)\n   * - \"medium\": Moderate pricing for good performance\n   * - \"high\": Premium pricing for best-in-class models\n   */\n  cost: \"low\" | \"medium\" | \"high\";\n\n  /**\n   * Optional hint to suggest a specific model. The system will use this\n   * model if possible, but may override it based on user preferences.\n   */\n  hint?: AIModel;\n};\n\n/**\n * Supported AI models available through Cloudflare AI Gateway and Workers AI.\n *\n * Models are organized by provider:\n * - **OpenAI**: Latest GPT models via AI Gateway\n * - **Anthropic**: Claude models via AI Gateway (prefix with \"anthropic/\")\n * - **Google**: Gemini models via AI Gateway (prefix with \"google-ai-studio/\")\n * - **Workers AI**: Models running on Cloudflare's network (free/low cost)\n */\nexport enum AIModel {\n  // OpenAI models - Latest GPT and reasoning models\n  GPT_5 = \"openai/gpt-5\",\n  GPT_5_PRO = \"openai/gpt-5-pro\",\n  GPT_5_MINI = \"openai/gpt-5-mini\",\n  GPT_5_NANO = \"openai/gpt-5-nano\",\n  GPT_4O = \"openai/gpt-4o\",\n  GPT_4O_MINI = \"openai/gpt-4o-mini\",\n  O3 = \"openai/o3\",\n  O3_MINI = \"openai/o3-mini\",\n\n  // Anthropic models - Claude 4.x series\n  CLAUDE_OPUS_46 = \"anthropic/claude-opus-4-6\",\n  CLAUDE_SONNET_46 = \"anthropic/claude-sonnet-4-6\",\n  CLAUDE_HAIKU_45 = \"anthropic/claude-haiku-4-5\",\n\n  // Google models - Gemini 2.x series\n  GEMINI_25_PRO = \"google/gemini-2.5-pro\",\n  GEMINI_25_FLASH = \"google/gemini-2.5-flash\",\n  GEMINI_25_FLASH_LITE = \"google/gemini-2.5-flash-lite\",\n  GEMINI_20_FLASH = \"google/gemini-2.0-flash\",\n  GEMINI_20_FLASH_LITE = \"google/gemini-2.0-flash-lite\",\n\n  // Cloudflare Workers AI models - Free/low-cost models running on Cloudflare's network\n  LLAMA_4_SCOUT_17B = \"meta/llama-4-scout-17b-16e-instruct\",\n  LLAMA_33_70B = \"meta/llama-3.3-70b-instruct-fp8-fast\",\n  LLAMA_31_8B = \"meta/llama-3.1-8b-instruct-fp8\",\n  LLAMA_32_1B = \"meta/llama-3.2-1b-instruct\",\n  DEEPSEEK_R1_32B = \"deepseek-ai/deepseek-r1-distill-qwen-32b\",\n}\n\n/**\n * Request parameters for AI text generation, matching Vercel AI SDK's generateText() function.\n */\nexport interface AIRequest<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * Model selection preferences based on desired speed and cost characteristics.\n   * Plot will automatically select the best available model matching these preferences.\n   *\n   * @example\n   * // Fast and cheap - good for simple tasks\n   * model: { speed: \"fast\", cost: \"low\" }\n   *\n   * @example\n   * // Balanced performance - general purpose\n   * model: { speed: \"balanced\", cost: \"medium\" }\n   *\n   * @example\n   * // Maximum capability - complex reasoning\n   * model: { speed: \"capable\", cost: \"high\" }\n   *\n   * @example\n   * // With a specific model hint\n   * model: { speed: \"balanced\", cost: \"medium\", hint: \"anthropic/claude-sonnet-4-6\" }\n   */\n  model: ModelPreferences;\n\n  /**\n   * System instructions to guide the model's behavior.\n   */\n  system?: string;\n\n  /**\n   * The user's input prompt. Can be a simple string or an array of messages for multi-turn conversations.\n   */\n  prompt?: string;\n\n  /**\n   * Conversation messages for multi-turn interactions.\n   * Replaces 'prompt' for more complex conversations.\n   */\n  messages?: AIMessage[];\n\n  /**\n   * Tools that the model can call during generation.\n   * Each tool definition includes a description, input schema, and optional execute function.\n   */\n  tools?: TOOLS;\n\n  /**\n   * Controls which tools the model can use.\n   * - \"auto\": Model decides whether to use tools\n   * - \"none\": Model cannot use tools\n   * - \"required\": Model must use at least one tool\n   * - { type: \"tool\", toolName: string }: Model must use specific tool\n   */\n  toolChoice?: ToolChoice<TOOLS>;\n\n  /**\n   * Structured output schema using Typebox.\n   * Typebox schemas are JSON Schema objects that provide full TypeScript type inference.\n   */\n  outputSchema?: SCHEMA;\n\n  /**\n   * Maximum number of tokens to generate.\n   */\n  maxOutputTokens?: number;\n\n  /**\n   * Temperature for controlling randomness (0-2).\n   * Higher values make output more random, lower values more deterministic.\n   */\n  temperature?: number;\n\n  /**\n   * Top P sampling parameter (0-1).\n   * Controls diversity by limiting to top probability tokens.\n   */\n  topP?: number;\n}\n\n/**\n * Response from AI text generation, matching Vercel AI SDK's GenerateTextResult.\n */\nexport interface AIResponse<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * The generated text.\n   */\n  text: string;\n\n  /**\n   * Tool calls made by the model during generation.\n   */\n  toolCalls?: ToolCallArray<TOOLS>;\n\n  /**\n   * Results from tool executions.\n   */\n  toolResults?: ToolResultArray<TOOLS>;\n\n  /**\n   * Reason why the model stopped generating.\n   */\n  finishReason:\n    | \"stop\"\n    | \"length\"\n    | \"content-filter\"\n    | \"tool-calls\"\n    | \"error\"\n    | \"other\"\n    | \"unknown\";\n\n  /**\n   * Token usage information for this generation.\n   */\n  usage: AIUsage;\n\n  /**\n   * Sources used by the model (if supported).\n   */\n  sources?: Array<AISource>;\n\n  /**\n   * Structured output when using outputSchema.\n   * Type is automatically inferred from the Typebox schema.\n   */\n  output?: Static<SCHEMA>;\n\n  /**\n   * Response metadata including messages.\n   */\n  response?: {\n    id?: string;\n    timestamp?: Date;\n    modelId?: string;\n    messages?: AIMessage[];\n  };\n}\n\n// ============================================================================\n// Message Types\n// ============================================================================\n\n/**\n * A system message. It can contain system information.\n *\n * Note: using the \"system\" part of the prompt is strongly preferred\n * to increase the resilience against prompt injection attacks,\n * and because not all providers support several system messages.\n */\nexport type AISystemMessage = {\n  role: \"system\";\n  content: string;\n};\n\n/**\n * A user message. It can contain text or a combination of text and images.\n */\nexport type AIUserMessage = {\n  role: \"user\";\n  content: string | Array<TextPart | ImagePart | FilePart>;\n};\n\n/**\n * An assistant message. It can contain text, tool calls, or a combination of text and tool calls.\n */\nexport type AIAssistantMessage = {\n  role: \"assistant\";\n  content:\n    | string\n    | Array<\n        TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart\n      >;\n};\n\n/**\n * A tool message. It contains the result of one or more tool calls.\n */\nexport type AIToolMessage = {\n  role: \"tool\";\n  content: Array<ToolResultPart>;\n};\n\n/**\n * A message that can be used in the `messages` field of a prompt.\n * It can be a user message, an assistant message, or a tool message.\n */\nexport type AIMessage =\n  | AISystemMessage\n  | AIUserMessage\n  | AIAssistantMessage\n  | AIToolMessage;\n\n// ============================================================================\n// Usage & Sources\n// ============================================================================\n\n/**\n * Represents the number of tokens used in a prompt and completion.\n */\nexport type AIUsage = {\n  /**\n   * The number of tokens used in the prompt.\n   */\n  inputTokens?: number;\n  /**\n   * The number of tokens used in the completion.\n   */\n  outputTokens?: number;\n  /**\n   * The total number of tokens used (promptTokens + completionTokens).\n   */\n  totalTokens?: number;\n  /**\n   * The number of reasoning tokens used in the completion.\n   */\n  reasoningTokens?: number;\n};\n\n/**\n * A source that has been used as input to generate the response.\n */\nexport type AISource =\n  | {\n      type: \"source\";\n      /**\n       * A URL source. This is returned by web search RAG models.\n       */\n      sourceType: \"url\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * The URL of the source.\n       */\n      url: string;\n      /**\n       * The title of the source.\n       */\n      title?: string;\n    }\n  | {\n      type: \"source\";\n      /**\n       * The type of source - document sources reference files/documents.\n       */\n      sourceType: \"document\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * IANA media type of the document (e.g., 'application/pdf').\n       */\n      mediaType: string;\n      /**\n       * The title of the document.\n       */\n      title: string;\n      /**\n       * Optional filename of the document.\n       */\n      filename?: string;\n    };\n\n// ============================================================================\n// Content Parts\n// ============================================================================\n\n/**\n * Text content part of a prompt. It contains a string of text.\n */\nexport interface TextPart {\n  type: \"text\";\n  /**\n   * The text content.\n   */\n  text: string;\n}\n\n/**\n * Data content. Can either be a base64-encoded string, a Uint8Array, or an ArrayBuffer.\n */\nexport type DataContent = string | Uint8Array | ArrayBuffer;\n\n/**\n * Image content part of a prompt. It contains an image.\n */\nexport interface ImagePart {\n  type: \"image\";\n  /**\n   * Image data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the image\n   */\n  image: DataContent | URL;\n  /**\n   * Optional mime type of the image.\n   */\n  mimeType?: string;\n}\n\n/**\n * File content part of a prompt. It contains a file.\n */\nexport interface FilePart {\n  type: \"file\";\n  /**\n   * File data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the file\n   */\n  data: DataContent | URL;\n  /**\n   * Optional filename of the file.\n   */\n  filename?: string;\n  /**\n   * IANA media type of the file.\n   *\n   * @see https://www.iana.org/assignments/media-types/media-types.xhtml\n   */\n  mediaType: string;\n}\n\n/**\n * Reasoning content part of a prompt. It contains a reasoning.\n */\nexport interface ReasoningPart {\n  type: \"reasoning\";\n  /**\n   * The reasoning text.\n   */\n  text: string;\n  /**\n   * An optional signature for verifying that the reasoning originated from the model.\n   */\n  signature?: string;\n}\n\n/**\n * Redacted reasoning content part of a prompt.\n */\nexport interface RedactedReasoningPart {\n  type: \"redacted-reasoning\";\n  /**\n   * Redacted reasoning data.\n   */\n  data: string;\n}\n\n/**\n * Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).\n */\nexport interface ToolCallPart {\n  type: \"tool-call\";\n  /**\n   * ID of the tool call. This ID is used to match the tool call with the tool result.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that is being called.\n   */\n  toolName: string;\n  /**\n   * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.\n   */\n  input: unknown;\n}\n\ntype JSONValue = null | string | number | boolean | JSONObject | JSONArray;\ntype JSONObject = {\n  [key: string]: JSONValue;\n};\ntype JSONArray = JSONValue[];\n\n/**\n * Tool result content part of a prompt. It contains the result of the tool call with the matching ID.\n */\nexport interface ToolResultPart {\n  type: \"tool-result\";\n  /**\n   * ID of the tool call that this result is associated with.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that generated this result.\n   */\n  toolName: string;\n  /**\n   * Result of the tool call. This is a JSON-serializable object.\n   */\n  output:\n    | {\n        type: \"text\";\n        value: string;\n      }\n    | {\n        type: \"json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"error-text\";\n        value: string;\n      }\n    | {\n        type: \"error-json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"content\";\n        value: Array<\n          | {\n              type: \"text\";\n              /**\nText content.\n*/\n              text: string;\n            }\n          | {\n              type: \"media\";\n              /**\nBase-64 encoded media data.\n*/\n              data: string;\n              /**\nIANA media type.\n@see https://www.iana.org/assignments/media-types/media-types.xhtml\n*/\n              mediaType: string;\n            }\n        >;\n      };\n}\n\n// ============================================================================\n// Tool Types\n// ============================================================================\n\ntype ToolParameters = TSchema;\n\ntype inferParameters<PARAMETERS extends ToolParameters> = Static<PARAMETERS>;\n\n/**\n * Options passed to tool execution functions.\n */\nexport interface ToolExecutionOptions {\n  /**\n   * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.\n   */\n  toolCallId: string;\n  /**\n   * Messages that were sent to the language model to initiate the response that contained the tool call.\n   * The messages **do not** include the system prompt nor the assistant response that contained the tool call.\n   */\n  messages: AIMessage[];\n  /**\n   * An optional abort signal that indicates that the overall operation should be aborted.\n   */\n  abortSignal?: AbortSignal;\n}\n\n/**\n * A tool contains the description and the schema of the input that the tool expects.\n * This enables the language model to generate the input.\n *\n * The tool can also contain an optional execute function for the actual execution function of the tool.\n */\nexport type AITool<PARAMETERS extends ToolParameters = any, RESULT = any> = {\n  /**\n   * The schema of the input that the tool expects. The language model will use this to generate the input.\n   * It is also used to validate the output of the language model.\n   * Use descriptions to make the input understandable for the language model.\n   */\n  parameters: PARAMETERS;\n  /**\n   * The schema of the input that the tool expects. The language model will use this to generate the input.\n   * It is also used to validate the output of the language model.\n   * Use descriptions to make the input understandable for the language model.\n   */\n  inputSchema: TSchema;\n  /**\n   * An optional description of what the tool does.\n   * Will be used by the language model to decide whether to use the tool.\n   * Not used for provider-defined tools.\n   */\n  description?: string;\n  /**\n   * An async function that is called with the arguments from the tool call and produces a result.\n   * If not provided, the tool will not be executed automatically.\n   *\n   * @param args - The input of the tool call\n   * @param options - Execution options including abort signal and messages\n   */\n  execute?: (\n    args: inferParameters<PARAMETERS>,\n    options: ToolExecutionOptions\n  ) => PromiseLike<RESULT>;\n} & (\n  | {\n      /**\n       * Function tool.\n       */\n      type?: undefined | \"function\";\n    }\n  | {\n      /**\n       * Provider-defined tool.\n       */\n      type: \"provider-defined\";\n      /**\n       * The ID of the tool. Should follow the format `<provider-name>.<tool-name>`.\n       */\n      id: `${string}.${string}`;\n      /**\n       * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.\n       */\n      args: Record<string, unknown>;\n    }\n);\n\n/**\n * Tool choice for the generation. It supports the following settings:\n *\n * - `auto` (default): the model can choose whether and which tools to call.\n * - `required`: the model must call a tool. It can choose which tool to call.\n * - `none`: the model must not call tools\n * - `{ type: 'tool', toolName: string (typed) }`: the model must call the specified tool\n */\ntype ToolChoice<TOOLS extends Record<string, unknown>> =\n  | \"auto\"\n  | \"none\"\n  | \"required\"\n  | {\n      type: \"tool\";\n      toolName: Extract<keyof TOOLS, string>;\n    };\n\nexport type AIToolSet = Record<\n  string,\n  (\n    | AITool<never, never>\n    | AITool<any, any>\n    | AITool<any, never>\n    | AITool<never, any>\n  ) &\n    Pick<AITool<any, any>, \"execute\">\n>;\n\n// ============================================================================\n// Internal Helper Types\n// ============================================================================\n\ntype ToolCallUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-call\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n};\n\ntype ToolCallArray<TOOLS extends AIToolSet> = Array<ToolCallUnion<TOOLS>>;\n\ntype ToolResultUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-result\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n  result?: unknown;\n};\n\ntype ToolResultArray<TOOLS extends AIToolSet> = Array<ToolResultUnion<TOOLS>>;\n";
+export default "import type { Static, TSchema } from \"typebox\";\n\nimport { ITool } from \"..\";\n\n/**\n * Built-in tool for prompting Large Language Models (LLMs).\n *\n * The AI tool provides twists and tools with access to LLM capabilities\n * for natural language processing, text generation, data extraction,\n * and intelligent decision making within their workflows.\n *\n * **Features:**\n * - Access to multiple AI providers (OpenAI, Anthropic, Google, Workers AI)\n * - Multi-turn conversation support with `messages`\n * - Tool calling with automatic execution\n * - Structured output with Typebox schemas via `outputSchema`\n * - Unified API across all models via Vercel AI SDK\n * - Automatic response parsing and validation with full type inference\n *\n * @example\n * ```typescript\n * import { Type } from \"typebox\";\n *\n * class SmartEmailTool extends Tool {\n *   private ai: AI;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.ai = tools.get(AI);\n *   }\n *\n *   async categorizeEmail(emailContent: string) {\n *     // Define the output schema using Typebox\n *     const schema = Type.Object({\n *       category: Type.Union([\n *         Type.Literal(\"work\"),\n *         Type.Literal(\"personal\"),\n *         Type.Literal(\"spam\"),\n *         Type.Literal(\"promotional\")\n *       ]),\n *       confidence: Type.Number({ minimum: 0, maximum: 1 }),\n *       reasoning: Type.Optional(Type.String())\n *     });\n *\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Classify emails into categories: work, personal, spam, or promotional.\",\n *       prompt: `Categorize this email: ${emailContent}`,\n *       outputSchema: schema\n *     });\n *\n *     return response.output;\n *   }\n *\n *   async generateResponse(emailContent: string) {\n *     const response = await this.ai.prompt({\n *       model: { speed: \"fast\", cost: \"medium\" },\n *       system: \"Generate professional email responses that are helpful and concise.\",\n *       prompt: `Write a response to: ${emailContent}`\n *     });\n *\n *     return response.text;\n *   }\n * }\n * ```\n */\nexport abstract class AI extends ITool {\n  /**\n   * Returns which AI capabilities are currently available.\n   * Check this before calling prompt() or embed() to gracefully\n   * handle cases where AI is disabled by the user.\n   *\n   * Built-in tools are accessed as RPC stubs, so from a twist this call\n   * resolves asynchronously — always `await` it.\n   */\n  abstract available(): AICapabilities | Promise<AICapabilities>;\n\n  /**\n   * Sends a request to an AI model and returns the response using the Vercel AI SDK.\n   *\n   * Supports text generation, multi-turn conversations, structured outputs,\n   * and tool calling across multiple AI providers via Cloudflare AI Gateway.\n   *\n   * @param request - AI request with model, prompt/messages, and optional configuration\n   * @returns Promise resolving to the AI response with generated text and metadata\n   *\n   * @example\n   * ```typescript\n   * // Simple text generation\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Explain quantum computing in simple terms\"\n   * });\n   * console.log(response.text);\n   *\n   * // Fast and cheap for simple tasks\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"low\" },\n   *   prompt: \"Summarize this text...\"\n   * });\n   * console.log(response.text);\n   *\n   * // With system instructions for complex reasoning\n   * const response = await ai.prompt({\n   *   model: { speed: \"capable\", cost: \"high\" },\n   *   system: \"You are a helpful physics tutor.\",\n   *   prompt: \"Explain quantum entanglement\"\n   * });\n   * console.log(response.text);\n   *\n   * // Multi-turn conversation\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   messages: [\n   *     { role: \"user\", content: \"What is 2+2?\" },\n   *     { role: \"assistant\", content: \"2+2 equals 4.\" },\n   *     { role: \"user\", content: \"What about 3+3?\" }\n   *   ]\n   * });\n   * console.log(response.text);\n   *\n   * // Structured output with Typebox schema\n   * const response = await ai.prompt({\n   *   model: { speed: \"fast\", cost: \"medium\" },\n   *   prompt: \"Extract information: John is 30 years old\",\n   *   outputSchema: Type.Object({\n   *     name: Type.String(),\n   *     age: Type.Number()\n   *   })\n   * });\n   * console.log(response.output); // { name: \"John\", age: 30 }\n   *\n   * // Tool calling\n   * const response = await ai.prompt({\n   *   model: { speed: \"balanced\", cost: \"medium\" },\n   *   prompt: \"What's the weather in San Francisco?\",\n   *   tools: {\n   *     getWeather: {\n   *       description: \"Get weather for a city\",\n   *       inputSchema: Type.Object({\n   *         city: Type.String()\n   *       }),\n   *       execute: async ({ city }) => {\n   *         return { temp: 72, condition: \"sunny\" };\n   *       }\n   *     }\n   *   }\n   * });\n   * console.log(response.text); // Model's response using tool results\n   * console.log(response.toolCalls); // Array of tool calls made\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract prompt<TOOLS extends AIToolSet, SCHEMA extends TSchema = never>(\n    request: AIRequest<TOOLS, SCHEMA>\n  ): Promise<AIResponse<TOOLS, SCHEMA>>;\n}\n\n/** Options for configuring AI tool usage in a twist. */\nexport type AIOptions = {\n  /** Whether AI is required for this twist to function. Default: true */\n  required?: boolean;\n};\n\n/** Describes which AI capabilities are currently available to this twist. */\nexport type AICapabilities = {\n  /** Whether AI prompting (text generation) is available. */\n  prompt: boolean;\n  /** Whether AI embedding generation is available. */\n  embed: boolean;\n  /**\n   * Whether provider-native web search is available. True for Plot AI and\n   * Anthropic/Google BYOK providers; false for OpenAI/custom BYOK providers\n   * that don't expose a server-side web search tool through this runtime.\n   */\n  webSearch: boolean;\n};\n\n/**\n * Model preferences for selecting an AI model based on performance and cost requirements.\n * This allows Plot to match those preferences with user preferences (such as preferred or\n * disallowed providers), as well as availability of newer and better models.\n *\n * @example\n * ```typescript\n * // Fast and cheap - uses Workers AI models like Llama 3.2 1B\n * const response = await ai.prompt({\n *   model: { speed: \"fast\", cost: \"low\" },\n *   prompt: \"Summarize this in one sentence: ...\"\n * });\n *\n * // Balanced performance - uses GPT-5 Mini or Gemini 2.5 Flash\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\" },\n *   prompt: \"Analyze this data...\"\n * });\n *\n * // Most capable - uses Claude Sonnet 4.5 or Opus 4.1\n * const response = await ai.prompt({\n *   model: { speed: \"capable\", cost: \"high\" },\n *   prompt: \"Solve this complex reasoning problem...\"\n * });\n *\n * // Request a specific model with a hint\n * const response = await ai.prompt({\n *   model: { speed: \"balanced\", cost: \"medium\", hint: AIModel.CLAUDE_SONNET_45 },\n *   prompt: \"...\"\n * });\n * ```\n */\nexport type ModelPreferences = {\n  /**\n   * Desired speed tier:\n   * - \"fast\": Optimized for low latency and quick responses\n   * - \"balanced\": Good balance of speed and capability\n   * - \"capable\": Maximum reasoning and problem-solving ability\n   */\n  speed: \"fast\" | \"balanced\" | \"capable\";\n\n  /**\n   * Desired cost tier:\n   * - \"low\": Minimal cost, often using Workers AI models (free/very cheap)\n   * - \"medium\": Moderate pricing for good performance\n   * - \"high\": Premium pricing for best-in-class models\n   */\n  cost: \"low\" | \"medium\" | \"high\";\n\n  /**\n   * Optional hint to suggest a specific model. The system will use this\n   * model if possible, but may override it based on user preferences.\n   */\n  hint?: AIModel;\n};\n\n/**\n * Supported AI models available through Cloudflare AI Gateway and Workers AI.\n *\n * Models are organized by provider:\n * - **OpenAI**: Latest GPT models via AI Gateway\n * - **Anthropic**: Claude models via AI Gateway (prefix with \"anthropic/\")\n * - **Google**: Gemini models via AI Gateway (prefix with \"google-ai-studio/\")\n * - **Workers AI**: Models running on Cloudflare's network (free/low cost)\n */\nexport enum AIModel {\n  // OpenAI models - Latest GPT and reasoning models\n  GPT_5 = \"openai/gpt-5\",\n  GPT_5_PRO = \"openai/gpt-5-pro\",\n  GPT_5_MINI = \"openai/gpt-5-mini\",\n  GPT_5_NANO = \"openai/gpt-5-nano\",\n  GPT_4O = \"openai/gpt-4o\",\n  GPT_4O_MINI = \"openai/gpt-4o-mini\",\n  O3 = \"openai/o3\",\n  O3_MINI = \"openai/o3-mini\",\n\n  // Anthropic models - Claude 4.x series\n  CLAUDE_OPUS_46 = \"anthropic/claude-opus-4-6\",\n  CLAUDE_SONNET_46 = \"anthropic/claude-sonnet-4-6\",\n  CLAUDE_HAIKU_45 = \"anthropic/claude-haiku-4-5\",\n\n  // Google models - Gemini 2.x series\n  GEMINI_25_PRO = \"google/gemini-2.5-pro\",\n  GEMINI_25_FLASH = \"google/gemini-2.5-flash\",\n  GEMINI_25_FLASH_LITE = \"google/gemini-2.5-flash-lite\",\n  GEMINI_20_FLASH = \"google/gemini-2.0-flash\",\n  GEMINI_20_FLASH_LITE = \"google/gemini-2.0-flash-lite\",\n\n  // Cloudflare Workers AI models - Free/low-cost models running on Cloudflare's network\n  LLAMA_4_SCOUT_17B = \"meta/llama-4-scout-17b-16e-instruct\",\n  LLAMA_33_70B = \"meta/llama-3.3-70b-instruct-fp8-fast\",\n  LLAMA_31_8B = \"meta/llama-3.1-8b-instruct-fp8\",\n  LLAMA_32_1B = \"meta/llama-3.2-1b-instruct\",\n  DEEPSEEK_R1_32B = \"deepseek-ai/deepseek-r1-distill-qwen-32b\",\n}\n\n/**\n * Request parameters for AI text generation, matching Vercel AI SDK's generateText() function.\n */\nexport interface AIRequest<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * Model selection preferences based on desired speed and cost characteristics.\n   * Plot will automatically select the best available model matching these preferences.\n   *\n   * @example\n   * // Fast and cheap - good for simple tasks\n   * model: { speed: \"fast\", cost: \"low\" }\n   *\n   * @example\n   * // Balanced performance - general purpose\n   * model: { speed: \"balanced\", cost: \"medium\" }\n   *\n   * @example\n   * // Maximum capability - complex reasoning\n   * model: { speed: \"capable\", cost: \"high\" }\n   *\n   * @example\n   * // With a specific model hint\n   * model: { speed: \"balanced\", cost: \"medium\", hint: \"anthropic/claude-sonnet-4-6\" }\n   */\n  model: ModelPreferences;\n\n  /**\n   * System instructions to guide the model's behavior.\n   */\n  system?: string;\n\n  /**\n   * The user's input prompt. Can be a simple string or an array of messages for multi-turn conversations.\n   */\n  prompt?: string;\n\n  /**\n   * Conversation messages for multi-turn interactions.\n   * Replaces 'prompt' for more complex conversations.\n   */\n  messages?: AIMessage[];\n\n  /**\n   * Tools that the model can call during generation.\n   * Each tool definition includes a description, input schema, and optional execute function.\n   */\n  tools?: TOOLS;\n\n  /**\n   * Controls which tools the model can use.\n   * - \"auto\": Model decides whether to use tools\n   * - \"none\": Model cannot use tools\n   * - \"required\": Model must use at least one tool\n   * - { type: \"tool\", toolName: string }: Model must use specific tool\n   */\n  toolChoice?: ToolChoice<TOOLS>;\n\n  /**\n   * Structured output schema using Typebox.\n   * Typebox schemas are JSON Schema objects that provide full TypeScript type inference.\n   */\n  outputSchema?: SCHEMA;\n\n  /**\n   * Maximum number of tokens to generate.\n   */\n  maxOutputTokens?: number;\n\n  /**\n   * Temperature for controlling randomness (0-2).\n   * Higher values make output more random, lower values more deterministic.\n   */\n  temperature?: number;\n\n  /**\n   * Top P sampling parameter (0-1).\n   * Controls diversity by limiting to top probability tokens.\n   */\n  topP?: number;\n\n  /**\n   * Enable provider-native web search so the model can retrieve\n   * up-to-date information from the web. The search is executed\n   * server-side by the provider and any pages used are returned in\n   * {@link AIResponse.sources}.\n   *\n   * Only available on web-search-capable providers (Anthropic and\n   * Google). Check {@link AICapabilities.webSearch} via `available()`\n   * before relying on it; on unsupported providers the flag is ignored.\n   *\n   * Pass `true` for defaults, or an object to cap the number of searches.\n   */\n  webSearch?: boolean | { maxUses?: number };\n\n  /**\n   * Maximum number of sequential generation steps for agentic tool use.\n   * When the model calls a tool, its result is fed back and the model is\n   * called again, up to `maxSteps` times, until it produces a final answer.\n   *\n   * Defaults to 1 (single step — tool calls are returned but not looped),\n   * preserving prior behavior. Set higher (e.g. 6) to let the model chain\n   * tool calls into a final answer.\n   */\n  maxSteps?: number;\n}\n\n/**\n * Response from AI text generation, matching Vercel AI SDK's GenerateTextResult.\n */\nexport interface AIResponse<\n  TOOLS extends AIToolSet,\n  SCHEMA extends TSchema = never\n> {\n  /**\n   * The generated text.\n   */\n  text: string;\n\n  /**\n   * Tool calls made by the model during generation.\n   */\n  toolCalls?: ToolCallArray<TOOLS>;\n\n  /**\n   * Results from tool executions.\n   */\n  toolResults?: ToolResultArray<TOOLS>;\n\n  /**\n   * Reason why the model stopped generating.\n   */\n  finishReason:\n    | \"stop\"\n    | \"length\"\n    | \"content-filter\"\n    | \"tool-calls\"\n    | \"error\"\n    | \"other\"\n    | \"unknown\";\n\n  /**\n   * Token usage information for this generation.\n   */\n  usage: AIUsage;\n\n  /**\n   * Sources used by the model (if supported).\n   */\n  sources?: Array<AISource>;\n\n  /**\n   * Structured output when using outputSchema.\n   * Type is automatically inferred from the Typebox schema.\n   */\n  output?: Static<SCHEMA>;\n\n  /**\n   * Response metadata including messages.\n   */\n  response?: {\n    id?: string;\n    timestamp?: Date;\n    modelId?: string;\n    messages?: AIMessage[];\n  };\n}\n\n// ============================================================================\n// Message Types\n// ============================================================================\n\n/**\n * A system message. It can contain system information.\n *\n * Note: using the \"system\" part of the prompt is strongly preferred\n * to increase the resilience against prompt injection attacks,\n * and because not all providers support several system messages.\n */\nexport type AISystemMessage = {\n  role: \"system\";\n  content: string;\n};\n\n/**\n * A user message. It can contain text or a combination of text and images.\n */\nexport type AIUserMessage = {\n  role: \"user\";\n  content: string | Array<TextPart | ImagePart | FilePart>;\n};\n\n/**\n * An assistant message. It can contain text, tool calls, or a combination of text and tool calls.\n */\nexport type AIAssistantMessage = {\n  role: \"assistant\";\n  content:\n    | string\n    | Array<\n        TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart\n      >;\n};\n\n/**\n * A tool message. It contains the result of one or more tool calls.\n */\nexport type AIToolMessage = {\n  role: \"tool\";\n  content: Array<ToolResultPart>;\n};\n\n/**\n * A message that can be used in the `messages` field of a prompt.\n * It can be a user message, an assistant message, or a tool message.\n */\nexport type AIMessage =\n  | AISystemMessage\n  | AIUserMessage\n  | AIAssistantMessage\n  | AIToolMessage;\n\n// ============================================================================\n// Usage & Sources\n// ============================================================================\n\n/**\n * Represents the number of tokens used in a prompt and completion.\n */\nexport type AIUsage = {\n  /**\n   * The number of tokens used in the prompt.\n   */\n  inputTokens?: number;\n  /**\n   * The number of tokens used in the completion.\n   */\n  outputTokens?: number;\n  /**\n   * The total number of tokens used (promptTokens + completionTokens).\n   */\n  totalTokens?: number;\n  /**\n   * The number of reasoning tokens used in the completion.\n   */\n  reasoningTokens?: number;\n};\n\n/**\n * A source that has been used as input to generate the response.\n */\nexport type AISource =\n  | {\n      type: \"source\";\n      /**\n       * A URL source. This is returned by web search RAG models.\n       */\n      sourceType: \"url\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * The URL of the source.\n       */\n      url: string;\n      /**\n       * The title of the source.\n       */\n      title?: string;\n    }\n  | {\n      type: \"source\";\n      /**\n       * The type of source - document sources reference files/documents.\n       */\n      sourceType: \"document\";\n      /**\n       * The ID of the source.\n       */\n      id: string;\n      /**\n       * IANA media type of the document (e.g., 'application/pdf').\n       */\n      mediaType: string;\n      /**\n       * The title of the document.\n       */\n      title: string;\n      /**\n       * Optional filename of the document.\n       */\n      filename?: string;\n    };\n\n// ============================================================================\n// Content Parts\n// ============================================================================\n\n/**\n * Text content part of a prompt. It contains a string of text.\n */\nexport interface TextPart {\n  type: \"text\";\n  /**\n   * The text content.\n   */\n  text: string;\n}\n\n/**\n * Data content. Can either be a base64-encoded string, a Uint8Array, or an ArrayBuffer.\n */\nexport type DataContent = string | Uint8Array | ArrayBuffer;\n\n/**\n * Image content part of a prompt. It contains an image.\n */\nexport interface ImagePart {\n  type: \"image\";\n  /**\n   * Image data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the image\n   */\n  image: DataContent | URL;\n  /**\n   * Optional mime type of the image.\n   */\n  mimeType?: string;\n}\n\n/**\n * File content part of a prompt. It contains a file.\n */\nexport interface FilePart {\n  type: \"file\";\n  /**\n   * File data. Can either be:\n   *\n   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer\n   * - URL: a URL that points to the file\n   */\n  data: DataContent | URL;\n  /**\n   * Optional filename of the file.\n   */\n  filename?: string;\n  /**\n   * IANA media type of the file.\n   *\n   * @see https://www.iana.org/assignments/media-types/media-types.xhtml\n   */\n  mediaType: string;\n}\n\n/**\n * Reasoning content part of a prompt. It contains a reasoning.\n */\nexport interface ReasoningPart {\n  type: \"reasoning\";\n  /**\n   * The reasoning text.\n   */\n  text: string;\n  /**\n   * An optional signature for verifying that the reasoning originated from the model.\n   */\n  signature?: string;\n}\n\n/**\n * Redacted reasoning content part of a prompt.\n */\nexport interface RedactedReasoningPart {\n  type: \"redacted-reasoning\";\n  /**\n   * Redacted reasoning data.\n   */\n  data: string;\n}\n\n/**\n * Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).\n */\nexport interface ToolCallPart {\n  type: \"tool-call\";\n  /**\n   * ID of the tool call. This ID is used to match the tool call with the tool result.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that is being called.\n   */\n  toolName: string;\n  /**\n   * Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.\n   */\n  input: unknown;\n}\n\ntype JSONValue = null | string | number | boolean | JSONObject | JSONArray;\ntype JSONObject = {\n  [key: string]: JSONValue;\n};\ntype JSONArray = JSONValue[];\n\n/**\n * Tool result content part of a prompt. It contains the result of the tool call with the matching ID.\n */\nexport interface ToolResultPart {\n  type: \"tool-result\";\n  /**\n   * ID of the tool call that this result is associated with.\n   */\n  toolCallId: string;\n  /**\n   * Name of the tool that generated this result.\n   */\n  toolName: string;\n  /**\n   * Result of the tool call. This is a JSON-serializable object.\n   */\n  output:\n    | {\n        type: \"text\";\n        value: string;\n      }\n    | {\n        type: \"json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"error-text\";\n        value: string;\n      }\n    | {\n        type: \"error-json\";\n        value: JSONValue;\n      }\n    | {\n        type: \"content\";\n        value: Array<\n          | {\n              type: \"text\";\n              /**\nText content.\n*/\n              text: string;\n            }\n          | {\n              type: \"media\";\n              /**\nBase-64 encoded media data.\n*/\n              data: string;\n              /**\nIANA media type.\n@see https://www.iana.org/assignments/media-types/media-types.xhtml\n*/\n              mediaType: string;\n            }\n        >;\n      };\n}\n\n// ============================================================================\n// Tool Types\n// ============================================================================\n\ntype ToolParameters = TSchema;\n\ntype inferParameters<PARAMETERS extends ToolParameters> = Static<PARAMETERS>;\n\n/**\n * Options passed to tool execution functions.\n */\nexport interface ToolExecutionOptions {\n  /**\n   * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.\n   */\n  toolCallId: string;\n  /**\n   * Messages that were sent to the language model to initiate the response that contained the tool call.\n   * The messages **do not** include the system prompt nor the assistant response that contained the tool call.\n   */\n  messages: AIMessage[];\n  /**\n   * An optional abort signal that indicates that the overall operation should be aborted.\n   */\n  abortSignal?: AbortSignal;\n}\n\n/**\n * A tool contains the description and the schema of the input that the tool expects.\n * This enables the language model to generate the input.\n *\n * The tool can also contain an optional execute function for the actual execution function of the tool.\n */\nexport type AITool<PARAMETERS extends ToolParameters = any, RESULT = any> = {\n  /**\n   * The schema of the input that the tool expects, expressed as a Typebox\n   * schema. The language model uses this to generate (and the runtime to\n   * validate) the tool input. Use field descriptions to make the input\n   * understandable for the model.\n   *\n   * This is the canonical field read by the runtime. `parameters` is an\n   * accepted alias for backwards compatibility.\n   */\n  inputSchema: TSchema;\n  /**\n   * @deprecated Alias for {@link inputSchema}. Prefer `inputSchema`.\n   */\n  parameters?: PARAMETERS;\n  /**\n   * An optional description of what the tool does.\n   * Will be used by the language model to decide whether to use the tool.\n   * Not used for provider-defined tools.\n   */\n  description?: string;\n  /**\n   * An async function that is called with the arguments from the tool call and produces a result.\n   * If not provided, the tool will not be executed automatically.\n   *\n   * @param args - The input of the tool call\n   * @param options - Execution options including abort signal and messages\n   */\n  execute?: (\n    args: inferParameters<PARAMETERS>,\n    options: ToolExecutionOptions\n  ) => PromiseLike<RESULT>;\n} & (\n  | {\n      /**\n       * Function tool.\n       */\n      type?: undefined | \"function\";\n    }\n  | {\n      /**\n       * Provider-defined tool.\n       */\n      type: \"provider-defined\";\n      /**\n       * The ID of the tool. Should follow the format `<provider-name>.<tool-name>`.\n       */\n      id: `${string}.${string}`;\n      /**\n       * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.\n       */\n      args: Record<string, unknown>;\n    }\n);\n\n/**\n * Tool choice for the generation. It supports the following settings:\n *\n * - `auto` (default): the model can choose whether and which tools to call.\n * - `required`: the model must call a tool. It can choose which tool to call.\n * - `none`: the model must not call tools\n * - `{ type: 'tool', toolName: string (typed) }`: the model must call the specified tool\n */\ntype ToolChoice<TOOLS extends Record<string, unknown>> =\n  | \"auto\"\n  | \"none\"\n  | \"required\"\n  | {\n      type: \"tool\";\n      toolName: Extract<keyof TOOLS, string>;\n    };\n\nexport type AIToolSet = Record<\n  string,\n  (\n    | AITool<never, never>\n    | AITool<any, any>\n    | AITool<any, never>\n    | AITool<never, any>\n  ) &\n    Pick<AITool<any, any>, \"execute\">\n>;\n\n// ============================================================================\n// Internal Helper Types\n// ============================================================================\n\ntype ToolCallUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-call\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n};\n\ntype ToolCallArray<TOOLS extends AIToolSet> = Array<ToolCallUnion<TOOLS>>;\n\ntype ToolResultUnion<_TOOLS extends AIToolSet> = {\n  type: \"tool-result\";\n  toolCallId: string;\n  toolName: string;\n  args?: unknown;\n  result?: unknown;\n};\n\ntype ToolResultArray<TOOLS extends AIToolSet> = Array<ToolResultUnion<TOOLS>>;\n";
 //# sourceMappingURL=ai.js.map

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

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

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import { ITool } from \"..\";\n\n/**\n * Built-in tool for reading files attached to notes in Plot.\n *\n * Files are uploaded by clients via POST /files which creates an\n * ActionType.file entry on a note. Connectors call read() during outbound\n * (e.g. onNoteCreated) to retrieve those bytes and send them to the source\n * system.\n *\n * For inbound attachments, connectors emit ActionType.fileRef actions and\n * implement Connector.downloadAttachment \u2014 no upload tool is needed because\n * inbound bytes never enter Plot's R2 storage.\n */\nexport abstract class Files extends ITool {\n  /**\n   * Read a file uploaded by a client and attached to a note in a priority\n   * where this twist is installed.\n   *\n   * @param fileId The id from an ActionType.file action.\n   * @returns Bytes plus original metadata.\n   * @throws FileNotFoundError if the file is missing or out of scope.\n   */\n  abstract read(fileId: string): Promise<{\n    data: Uint8Array;\n    fileName: string;\n    mimeType: string;\n    fileSize: number;\n  }>;\n}\n\nexport class FileNotFoundError extends Error {\n  constructor(fileId: string) {\n    super(`File not found or out of scope: ${fileId}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n";
+declare const _default: "import { ITool } from \"..\";\n\n/**\n * Built-in tool for reading files attached to notes in Plot.\n *\n * Files are uploaded by clients via POST /files which creates an\n * ActionType.file entry on a note. Connectors call read() during outbound\n * (e.g. onNoteCreated) to retrieve those bytes and send them to the source\n * system.\n *\n * For inbound attachments, connectors emit ActionType.fileRef actions and\n * implement Connector.downloadAttachment \u2014 no upload tool is needed because\n * inbound bytes never enter Plot's R2 storage.\n */\nexport abstract class Files extends ITool {\n  /**\n   * Read a file uploaded by a client and attached to a note in a focus\n   * where this twist is installed.\n   *\n   * @param fileId The id from an ActionType.file action.\n   * @returns Bytes plus original metadata.\n   * @throws FileNotFoundError if the file is missing or out of scope.\n   */\n  abstract read(fileId: string): Promise<{\n    data: Uint8Array;\n    fileName: string;\n    mimeType: string;\n    fileSize: number;\n  }>;\n}\n\nexport class FileNotFoundError extends Error {\n  constructor(fileId: string) {\n    super(`File not found or out of scope: ${fileId}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n";
 export default _default;
 //# sourceMappingURL=files.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/files.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,4tCAAutC;AAAtuC,wBAAuuC"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/files.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,ytCAAotC;AAAnuC,wBAAouC"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { ITool } from \"..\";\n\n/**\n * Built-in tool for reading files attached to notes in Plot.\n *\n * Files are uploaded by clients via POST /files which creates an\n * ActionType.file entry on a note. Connectors call read() during outbound\n * (e.g. onNoteCreated) to retrieve those bytes and send them to the source\n * system.\n *\n * For inbound attachments, connectors emit ActionType.fileRef actions and\n * implement Connector.downloadAttachment — no upload tool is needed because\n * inbound bytes never enter Plot's R2 storage.\n */\nexport abstract class Files extends ITool {\n  /**\n   * Read a file uploaded by a client and attached to a note in a priority\n   * where this twist is installed.\n   *\n   * @param fileId The id from an ActionType.file action.\n   * @returns Bytes plus original metadata.\n   * @throws FileNotFoundError if the file is missing or out of scope.\n   */\n  abstract read(fileId: string): Promise<{\n    data: Uint8Array;\n    fileName: string;\n    mimeType: string;\n    fileSize: number;\n  }>;\n}\n\nexport class FileNotFoundError extends Error {\n  constructor(fileId: string) {\n    super(`File not found or out of scope: ${fileId}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n";
+export default "import { ITool } from \"..\";\n\n/**\n * Built-in tool for reading files attached to notes in Plot.\n *\n * Files are uploaded by clients via POST /files which creates an\n * ActionType.file entry on a note. Connectors call read() during outbound\n * (e.g. onNoteCreated) to retrieve those bytes and send them to the source\n * system.\n *\n * For inbound attachments, connectors emit ActionType.fileRef actions and\n * implement Connector.downloadAttachment — no upload tool is needed because\n * inbound bytes never enter Plot's R2 storage.\n */\nexport abstract class Files extends ITool {\n  /**\n   * Read a file uploaded by a client and attached to a note in a focus\n   * where this twist is installed.\n   *\n   * @param fileId The id from an ActionType.file action.\n   * @returns Bytes plus original metadata.\n   * @throws FileNotFoundError if the file is missing or out of scope.\n   */\n  abstract read(fileId: string): Promise<{\n    data: Uint8Array;\n    fileName: string;\n    mimeType: string;\n    fileSize: number;\n  }>;\n}\n\nexport class FileNotFoundError extends Error {\n  constructor(fileId: string) {\n    super(`File not found or out of scope: ${fileId}`);\n    this.name = \"FileNotFoundError\";\n  }\n}\n";
 //# sourceMappingURL=files.js.map

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

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

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type \u2014 used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now \u2014 Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Mark the thread `task=true` in Plot when a link enters this status.\n     * Use for project-tracker assignments \u2014 Linear / Todoist / Jira / etc.\n     * `task` puts the thread on the user's task list without flooding their\n     * inbox under `active`: the user explicitly flips it to `active` when\n     * they decide to start.\n     */\n    task?: boolean;\n    /**\n     * Mark the thread `to_read=true` in Plot when a link enters this status.\n     * Use for connectors that explicitly track read-later state (Pocket\n     * archives, Slack \"remind me\", etc).\n     */\n    toRead?: boolean;\n    /**\n     * @deprecated Use `active` (messaging) or `task` (project tracker) instead.\n     * Treated as `task: true` for backward compatibility.\n     *\n     * Original meaning: whether this status represents the connector's\n     * \"to-do\" / active state. When a user adds a thread to Plot's agenda,\n     * done-status links flip to the status marked `todo: true` (e.g.,\n     * Gmail's \"starred\", Linear's \"todo\").\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new \u2026\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   \u2192 [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar \u2192 [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new \u2026\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker \u2014 used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector \u2014 see\n   * `connectors/linear/src/linear.ts`).\n   */\n  status: string;\n  /**\n   * Optional override for the picker chip / \"Create new \u2026\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) \u2014 the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid \u2014\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications \u2014 set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} \u2014 saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Upserts contacts into the connector's priority without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing\u2026\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking \u2014 only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state \u2014 connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh \u2014 e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+declare const _default: "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type \u2014 used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now \u2014 Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Marks this status as the connector's \"to-do\" / active state. When a\n     * user brings a done thread back into Plot's agenda, done-status links\n     * are flipped to the status marked `todo: true` (e.g. Gmail's \"starred\",\n     * Linear's \"unstarted\"); connectors that don't mark one fall back to the\n     * first non-done status.\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new \u2026\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   \u2192 [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar \u2192 [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new \u2026\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker \u2014 used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector \u2014 see\n   * `connectors/linear/src/linear.ts`).\n   */\n  status: string;\n  /**\n   * Optional override for the picker chip / \"Create new \u2026\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) \u2014 the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid \u2014\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications \u2014 set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's focus.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} \u2014 saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Upserts contacts into the connector's focus without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing\u2026\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking \u2014 only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state \u2014 connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh \u2014 e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
 export default _default;
 //# sourceMappingURL=integrations.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,i4rBAAuyrB;AAAtzrB,wBAAuzrB"}
+{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,qsqBAAgnqB;AAA/nqB,wBAAgoqB"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type — used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now — Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Mark the thread `task=true` in Plot when a link enters this status.\n     * Use for project-tracker assignments — Linear / Todoist / Jira / etc.\n     * `task` puts the thread on the user's task list without flooding their\n     * inbox under `active`: the user explicitly flips it to `active` when\n     * they decide to start.\n     */\n    task?: boolean;\n    /**\n     * Mark the thread `to_read=true` in Plot when a link enters this status.\n     * Use for connectors that explicitly track read-later state (Pocket\n     * archives, Slack \"remind me\", etc).\n     */\n    toRead?: boolean;\n    /**\n     * @deprecated Use `active` (messaging) or `task` (project tracker) instead.\n     * Treated as `task: true` for backward compatibility.\n     *\n     * Original meaning: whether this status represents the connector's\n     * \"to-do\" / active state. When a user adds a thread to Plot's agenda,\n     * done-status links flip to the status marked `todo: true` (e.g.,\n     * Gmail's \"starred\", Linear's \"todo\").\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new …\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   → [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar → [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new …\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker — used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector — see\n   * `connectors/linear/src/linear.ts`).\n   */\n  status: string;\n  /**\n   * Optional override for the picker chip / \"Create new …\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid —\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications — set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} — saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Upserts contacts into the connector's priority without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing…\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking — only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state — connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh — e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type — used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now — Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Marks this status as the connector's \"to-do\" / active state. When a\n     * user brings a done thread back into Plot's agenda, done-status links\n     * are flipped to the status marked `todo: true` (e.g. Gmail's \"starred\",\n     * Linear's \"unstarted\"); connectors that don't mark one fall back to the\n     * first non-done status.\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new …\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   → [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar → [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new …\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker — used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector — see\n   * `connectors/linear/src/linear.ts`).\n   */\n  status: string;\n  /**\n   * Optional override for the picker chip / \"Create new …\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid —\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications — set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's focus.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} — saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Upserts contacts into the connector's focus without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing…\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking — only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state — connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh — e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
 //# sourceMappingURL=integrations.js.map

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

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