@plotday/twister 0.41.0 → 0.43.0

package/dist/llm-docs/plot.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 { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with threads, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Thread, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `title: string`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewThread, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `title: string` in NewPriority\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new thread\n * const newThread: NewThread = {\n *   title: \"Review pull request\",\n * };\n *\n * // Updating a thread - only change what's specified\n * const update: ThreadUpdate = {\n *   id: threadId,\n *   archived: true,\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported action types.\n *\n * Different action types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActionType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback actions that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable action attached to a thread.\n *\n * Thread actions are rendered as buttons that enable user interaction with threads.\n * Different action types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External action - opens URL in browser\n * const externalAction: Action = {\n *   type: ActionType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing action - opens video conference with provider info\n * const conferencingAction: Action = {\n *   type: ActionType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations action - initiates OAuth flow\n * const authAction: Action = {\n *   type: ActionType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback action - triggers a twist method\n * const callbackAction: Action = {\n *   type: ActionType.callback,\n *   title: \"\uD83D\uDCC5 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type Action =\n  | {\n      /** External web link that opens in browser */\n      type: ActionType.external;\n      /** Display text for the action button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing action with provider-specific handling */\n      type: ActionType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication action that initiates an OAuth flow */\n      type: ActionType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback action that triggers a twist method when clicked */\n      type: ActionType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment action stored in R2 */\n      type: ActionType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n    }\n  | {\n      /** Thread reference action for navigating to a related thread */\n      type: ActionType.thread;\n      /** UUID of the referenced thread */\n      threadId: Uuid;\n    };\n\n/**\n * Represents metadata about a thread, typically from an external system.\n *\n * Thread metadata enables storing additional information about threads,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createThread({\n *   title: \"Team Meeting\",\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createThread({\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ThreadMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Thread and Note entities.\n */\nexport type ThreadCommon = {\n  /** Unique identifier for the thread */\n  id: Uuid;\n  /**\n   * When this item was created.\n   *\n   * **For sources:** Set this to the external system's timestamp (e.g., email\n   * sent date, comment creation date), NOT the sync time. If omitted, defaults\n   * to the current time, which is almost never correct for synced data.\n   */\n  created: Date;\n  /** Whether this thread is private (only visible to creator) */\n  private: boolean;\n  /** Whether this thread has been archived */\n  archived: boolean;\n  /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\n};\n\n/**\n * Fields on a Thread entity.\n * Threads are simple containers for links and notes.\n */\ntype ThreadFields = ThreadCommon & {\n  /** The display title/summary of the thread */\n  title: string;\n  /** The priority context this thread belongs to */\n  priority: Priority;\n  /** The schedule associated with this thread, if any */\n  schedule?: Schedule;\n  /** Source-specific metadata from the thread's link, populated on callbacks */\n  meta?: ThreadMeta;\n};\n\nexport type Thread = ThreadFields;\n\nexport type ThreadWithNotes = Thread & {\n  notes: Note[];\n};\n\nexport type NewThreadWithNotes = NewThread & {\n  notes: Omit<NewNote, \"thread\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new threads.\n *\n * Threads are simple containers. All other fields are optional.\n *\n * @example\n * ```typescript\n * const thread: NewThread = {\n *   title: \"Review pull request\"\n * };\n * ```\n */\nexport type NewThread = Partial<\n  Omit<ThreadFields, \"priority\" | \"tags\" | \"mentions\" | \"id\">\n> &\n  (\n    | {\n        /** Unique identifier for the thread, generated by Uuid.Generate(). */\n        id: Uuid;\n      }\n    | {\n        /* id is optional. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the thread. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     */\n    preview?: string | null;\n\n    /**\n     * Optional schedules to create alongside the thread.\n     */\n    schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n\n    /**\n     * Optional schedule occurrence overrides.\n     */\n    scheduleOccurrences?: NewScheduleOccurrence[];\n  };\n\nexport type ThreadFilter = {\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many threads are included.\n */\ntype ThreadBulkUpdateFields = Partial<\n  Pick<ThreadFields, \"title\" | \"private\" | \"archived\">\n>;\n\n/**\n * Fields supported by single-thread updates via `id` or `source`.\n * Includes all bulk fields plus tags and preview.\n */\ntype ThreadSingleUpdateFields = ThreadBulkUpdateFields & {\n  /**\n   * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n   * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n   */\n  tags?: NewTags;\n\n  /**\n   * Add or remove the twist's tags.\n   * Maps tag ID to boolean: true = add tag, false = remove tag.\n   * This is allowed on all threads the twist has access to.\n   */\n  twistTags?: Partial<Record<Tag, boolean>>;\n\n  /**\n   * Optional preview content for the thread. Can be Markdown formatted.\n   * The preview will be automatically generated from this content (truncated to 100 chars).\n   *\n   * - string: Use this content for preview generation\n   * - null: Explicitly disable preview (no preview will be shown)\n   * - undefined (omitted): Preserve current preview value\n   *\n   * This field is write-only and won't be returned when reading threads.\n   */\n  preview?: string | null;\n};\n\nexport type ThreadUpdate =\n  | (({ id: Uuid } | { source: string }) & ThreadSingleUpdateFields)\n  | ({\n      /**\n       * Update all threads matching the specified criteria. Only threads\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ThreadFilter;\n    } & ThreadBulkUpdateFields);\n\n/**\n * Represents a note within a thread.\n *\n * Notes contain the detailed content (note text, actions) associated with a thread.\n * They are always ordered by creation time within their parent thread.\n */\nexport type Note = ThreadCommon & {\n  /** The author of this note */\n  author: Actor;\n  /**\n   * Globally unique, stable identifier for the note within its thread.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent thread this note belongs to */\n  thread: Thread;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive actions attached to the note */\n  actions: Array<Action> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the thread reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the thread\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<\n    Note,\n    \"author\" | \"thread\" | \"tags\" | \"mentions\" | \"id\" | \"key\" | \"reNote\"\n  >\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent thread (required) */\n    thread:\n      | Pick<Thread, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent thread as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<\n    Pick<Note, \"private\" | \"archived\" | \"content\" | \"actions\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with threads as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create threads.\n *\n * The author type affects how threads are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Threads created by human users */\n  User,\n  /** Threads created by external contacts */\n  Contact,\n  /** Threads created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /**\n   * Email address of the contact.\n   * Either email or source must be provided for contact resolution.\n   */\n  email?: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for identity resolution\n   * when email is unavailable and for privacy compliance reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n\n/**\n * Represents an external entity linked to a thread.\n *\n * Links are created by sources to represent external entities (issues, emails, calendar events)\n * attached to a thread container. A thread can have multiple links (1:many).\n * Links store source-specific data like type, status, metadata, and embeddings.\n *\n * @example\n * ```typescript\n * // A link representing a Linear issue\n * const link: Link = {\n *   id: \"...\" as Uuid,\n *   threadId: \"...\" as Uuid,\n *   source: \"linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b\",\n *   created: new Date(),\n *   author: { id: \"...\" as ActorId, type: ActorType.Contact, name: \"Alice\" },\n *   title: \"Fix login bug\",\n *   type: \"issue\",\n *   status: \"open\",\n *   meta: { projectId: \"TEAM\", url: \"https://linear.app/team/TEAM-123\" },\n *   assignee: null,\n *   actions: null,\n * };\n * ```\n */\nexport type Link = {\n  /** Unique identifier for the link */\n  id: Uuid;\n  /** The thread this link belongs to */\n  threadId: Uuid;\n  /** External source identifier for dedup/upsert */\n  source: string | null;\n  /** When this link was originally created in its source system */\n  created: Date;\n  /** The actor credited with creating this link */\n  author: Actor | null;\n  /** Display title */\n  title: string;\n  /** Truncated preview */\n  preview: string | null;\n  /** The actor assigned to this link */\n  assignee: Actor | null;\n  /** Source-defined type string (e.g., issue, pull_request, email, event) */\n  type: string | null;\n  /** Source-defined status string (e.g., open, done, closed) */\n  status: string | null;\n  /** Interactive action buttons */\n  actions: Array<Action> | null;\n  /** Source metadata */\n  meta: ThreadMeta | null;\n  /** URL to open the original item in its source application (e.g., \"Open in Linear\") */\n  sourceUrl: string | null;\n  /** Channel ID that produced this link (matches source_channel.channel_id) */\n  channelId: string | null;\n};\n\n/**\n * Type for creating new links.\n *\n * Links are created by sources to represent external entities.\n * Requires a source identifier for dedup/upsert.\n */\nexport type NewLink = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\n    /** The person that created the item. By default, it will be the twist itself. */\n    author?: NewActor;\n    /** The person assigned to the item. */\n    assignee?: NewActor | null;\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n    /**\n     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"id\">;\n  };\n\n/**\n * A new link with notes to save via integrations.saveLink().\n * Creates a thread+link pair, with notes attached to the thread.\n */\nexport type NewLinkWithNotes = NewLink & {\n  /**\n   * Title for the link and its thread container.\n   * Must be the real entity title (e.g. issue title, message subject),\n   * never a placeholder or ID. This value overwrites the existing title on upsert.\n   * If the title is not available in the webhook payload, fetch it from the API.\n   */\n  title: string;\n  /** Notes to attach to the thread */\n  notes?: Omit<NewNote, \"thread\">[];\n  /** Schedules to create for the link */\n  schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n  /** Schedule occurrence overrides */\n  scheduleOccurrences?: NewScheduleOccurrence[];\n};\n";
+declare const _default: "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with threads, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Thread, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `title: string`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewThread, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `title: string` in NewPriority\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new thread\n * const newThread: NewThread = {\n *   title: \"Review pull request\",\n * };\n *\n * // Updating a thread - only change what's specified\n * const update: ThreadUpdate = {\n *   id: threadId,\n *   archived: true,\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported action types.\n *\n * Different action types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActionType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback actions that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable action attached to a thread.\n *\n * Thread actions are rendered as buttons that enable user interaction with threads.\n * Different action types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External action - opens URL in browser\n * const externalAction: Action = {\n *   type: ActionType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing action - opens video conference with provider info\n * const conferencingAction: Action = {\n *   type: ActionType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations action - initiates OAuth flow\n * const authAction: Action = {\n *   type: ActionType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback action - triggers a twist method\n * const callbackAction: Action = {\n *   type: ActionType.callback,\n *   title: \"\uD83D\uDCC5 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type Action =\n  | {\n      /** External web link that opens in browser */\n      type: ActionType.external;\n      /** Display text for the action button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing action with provider-specific handling */\n      type: ActionType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication action that initiates an OAuth flow */\n      type: ActionType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback action that triggers a twist method when clicked */\n      type: ActionType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment action stored in R2 */\n      type: ActionType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n      /** Intrinsic width of the image in pixels (only for image files) */\n      imageWidth?: number | null;\n      /** Intrinsic height of the image in pixels (only for image files) */\n      imageHeight?: number | null;\n    }\n  | {\n      /** Thread reference action for navigating to a related thread */\n      type: ActionType.thread;\n      /** UUID of the referenced thread */\n      threadId: Uuid;\n    };\n\n/**\n * Represents metadata about a thread, typically from an external system.\n *\n * Thread metadata enables storing additional information about threads,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createThread({\n *   title: \"Team Meeting\",\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createThread({\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ThreadMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Thread sub-type that determines the thread's icon and category.\n * Available types depend on whether the priority is shared:\n * - Private priorities: \"notes\" (default), \"idea\", \"goal\", \"decision\"\n * - Shared priorities: all above plus \"discussion\" (default), \"announcement\", \"ask\"\n */\nexport type ThreadType =\n  | \"notes\"\n  | \"idea\"\n  | \"goal\"\n  | \"decision\"\n  | \"discussion\"\n  | \"announcement\"\n  | \"ask\";\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Thread and Note entities.\n */\nexport type ThreadCommon = {\n  /** Unique identifier for the thread */\n  id: Uuid;\n  /**\n   * When this item was created.\n   *\n   * **For sources:** Set this to the external system's timestamp (e.g., email\n   * sent date, comment creation date), NOT the sync time. If omitted, defaults\n   * to the current time, which is almost never correct for synced data.\n   */\n  created: Date;\n  /** Whether this thread is private (only visible to creator) */\n  private: boolean;\n  /** Whether this thread has been archived */\n  archived: boolean;\n  /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\n};\n\n/**\n * Fields on a Thread entity.\n * Threads are simple containers for links and notes.\n */\ntype ThreadFields = ThreadCommon & {\n  /** The display title/summary of the thread */\n  title: string;\n  /** The priority context this thread belongs to */\n  priority: Priority;\n  /** The thread's sub-type/category. Determines the displayed icon. */\n  type: ThreadType | null;\n  /** The schedule associated with this thread, if any */\n  schedule?: Schedule;\n  /** Source-specific metadata from the thread's link, populated on callbacks */\n  meta?: ThreadMeta;\n};\n\nexport type Thread = ThreadFields;\n\nexport type ThreadWithNotes = Thread & {\n  notes: Note[];\n};\n\nexport type NewThreadWithNotes = NewThread & {\n  notes: Omit<NewNote, \"thread\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new threads.\n *\n * Threads are simple containers. All other fields are optional.\n *\n * @example\n * ```typescript\n * const thread: NewThread = {\n *   title: \"Review pull request\"\n * };\n * ```\n */\nexport type NewThread = Partial<\n  Omit<ThreadFields, \"priority\" | \"tags\" | \"mentions\" | \"id\">\n> &\n  (\n    | {\n        /** Unique identifier for the thread, generated by Uuid.Generate(). */\n        id: Uuid;\n      }\n    | {\n        /* id is optional. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * The thread's sub-type/category. Sets the thread's icon.\n     * If omitted, defaults to \"notes\" (private) or \"discussion\" (shared).\n     */\n    type?: ThreadType;\n\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the thread. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     */\n    preview?: string | null;\n\n    /**\n     * Optional schedules to create alongside the thread.\n     */\n    schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n\n    /**\n     * Optional schedule occurrence overrides.\n     */\n    scheduleOccurrences?: NewScheduleOccurrence[];\n  };\n\nexport type ThreadFilter = {\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many threads are included.\n */\ntype ThreadBulkUpdateFields = Partial<\n  Pick<ThreadFields, \"title\" | \"private\" | \"archived\">\n>;\n\n/**\n * Fields supported by single-thread updates via `id` or `source`.\n * Includes all bulk fields plus tags and preview.\n */\ntype ThreadSingleUpdateFields = ThreadBulkUpdateFields & {\n  /**\n   * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n   * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n   */\n  tags?: NewTags;\n\n  /**\n   * Add or remove the twist's tags.\n   * Maps tag ID to boolean: true = add tag, false = remove tag.\n   * This is allowed on all threads the twist has access to.\n   */\n  twistTags?: Partial<Record<Tag, boolean>>;\n\n  /**\n   * Update the thread's sub-type/category.\n   */\n  type?: ThreadType;\n\n  /**\n   * Optional preview content for the thread. Can be Markdown formatted.\n   * The preview will be automatically generated from this content (truncated to 100 chars).\n   *\n   * - string: Use this content for preview generation\n   * - null: Explicitly disable preview (no preview will be shown)\n   * - undefined (omitted): Preserve current preview value\n   *\n   * This field is write-only and won't be returned when reading threads.\n   */\n  preview?: string | null;\n};\n\nexport type ThreadUpdate =\n  | (({ id: Uuid } | { source: string }) & ThreadSingleUpdateFields)\n  | ({\n      /**\n       * Update all threads matching the specified criteria. Only threads\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ThreadFilter;\n    } & ThreadBulkUpdateFields);\n\n/**\n * Represents a note within a thread.\n *\n * Notes contain the detailed content (note text, actions) associated with a thread.\n * They are always ordered by creation time within their parent thread.\n */\nexport type Note = ThreadCommon & {\n  /** The author of this note */\n  author: Actor;\n  /**\n   * Globally unique, stable identifier for the note within its thread.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent thread this note belongs to */\n  thread: Thread;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive actions attached to the note */\n  actions: Array<Action> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the thread reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the thread\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<\n    Note,\n    \"author\" | \"thread\" | \"tags\" | \"mentions\" | \"id\" | \"key\" | \"reNote\"\n  >\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent thread (required) */\n    thread:\n      | Pick<Thread, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent thread as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<\n    Pick<Note, \"private\" | \"archived\" | \"content\" | \"actions\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with threads as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create threads.\n *\n * The author type affects how threads are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Threads created by human users */\n  User,\n  /** Threads created by external contacts */\n  Contact,\n  /** Threads created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /**\n   * Email address of the contact.\n   * Either email or source must be provided for contact resolution.\n   */\n  email?: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for identity resolution\n   * when email is unavailable and for privacy compliance reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n\n/**\n * Represents an external entity linked to a thread.\n *\n * Links are created by sources to represent external entities (issues, emails, calendar events)\n * attached to a thread container. A thread can have multiple links (1:many).\n * Links store source-specific data like type, status, metadata, and embeddings.\n *\n * @example\n * ```typescript\n * // A link representing a Linear issue\n * const link: Link = {\n *   id: \"...\" as Uuid,\n *   threadId: \"...\" as Uuid,\n *   source: \"linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b\",\n *   created: new Date(),\n *   author: { id: \"...\" as ActorId, type: ActorType.Contact, name: \"Alice\" },\n *   title: \"Fix login bug\",\n *   type: \"issue\",\n *   status: \"open\",\n *   meta: { projectId: \"TEAM\", url: \"https://linear.app/team/TEAM-123\" },\n *   assignee: null,\n *   actions: null,\n * };\n * ```\n */\nexport type Link = {\n  /** Unique identifier for the link */\n  id: Uuid;\n  /** The thread this link belongs to */\n  threadId: Uuid;\n  /** External source identifier for dedup/upsert */\n  source: string | null;\n  /** When this link was originally created in its source system */\n  created: Date;\n  /** The actor credited with creating this link */\n  author: Actor | null;\n  /** Display title */\n  title: string;\n  /** Truncated preview */\n  preview: string | null;\n  /** The actor assigned to this link */\n  assignee: Actor | null;\n  /** Source-defined type string (e.g., issue, pull_request, email, event) */\n  type: string | null;\n  /** Source-defined status string (e.g., open, done, closed) */\n  status: string | null;\n  /** Interactive action buttons */\n  actions: Array<Action> | null;\n  /** Source metadata */\n  meta: ThreadMeta | null;\n  /** URL to open the original item in its source application (e.g., \"Open in Linear\") */\n  sourceUrl: string | null;\n  /** Channel ID that produced this link (matches source_channel.channel_id) */\n  channelId: string | null;\n};\n\n/**\n * Type for creating new links.\n *\n * Links are created by sources to represent external entities.\n * Requires a source identifier for dedup/upsert.\n */\nexport type NewLink = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\n    /** The person that created the item. By default, it will be the twist itself. */\n    author?: NewActor;\n    /** The person assigned to the item. */\n    assignee?: NewActor | null;\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n    /**\n     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"id\">;\n  };\n\n/**\n * A new link with notes to save via integrations.saveLink().\n * Creates a thread+link pair, with notes attached to the thread.\n */\nexport type NewLinkWithNotes = NewLink & {\n  /**\n   * Title for the link and its thread container.\n   * Must be the real entity title (e.g. issue title, message subject),\n   * never a placeholder or ID. This value overwrites the existing title on upsert.\n   * If the title is not available in the webhook payload, fetch it from the API.\n   */\n  title: string;\n  /** Notes to attach to the thread */\n  notes?: Omit<NewNote, \"thread\">[];\n  /** Schedules to create for the link */\n  schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n  /** Schedule occurrence overrides */\n  scheduleOccurrences?: NewScheduleOccurrence[];\n};\n";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,886BAAo86B;AAAn96B,wBAAo96B"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,2+8BAAi+8B;AAAh/8B,wBAAi/8B"}

package/dist/llm-docs/plot.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with threads, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Thread, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `title: string`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewThread, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `title: string` in NewPriority\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new thread\n * const newThread: NewThread = {\n *   title: \"Review pull request\",\n * };\n *\n * // Updating a thread - only change what's specified\n * const update: ThreadUpdate = {\n *   id: threadId,\n *   archived: true,\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported action types.\n *\n * Different action types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActionType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback actions that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable action attached to a thread.\n *\n * Thread actions are rendered as buttons that enable user interaction with threads.\n * Different action types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External action - opens URL in browser\n * const externalAction: Action = {\n *   type: ActionType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing action - opens video conference with provider info\n * const conferencingAction: Action = {\n *   type: ActionType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations action - initiates OAuth flow\n * const authAction: Action = {\n *   type: ActionType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback action - triggers a twist method\n * const callbackAction: Action = {\n *   type: ActionType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type Action =\n  | {\n      /** External web link that opens in browser */\n      type: ActionType.external;\n      /** Display text for the action button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing action with provider-specific handling */\n      type: ActionType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication action that initiates an OAuth flow */\n      type: ActionType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback action that triggers a twist method when clicked */\n      type: ActionType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment action stored in R2 */\n      type: ActionType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n    }\n  | {\n      /** Thread reference action for navigating to a related thread */\n      type: ActionType.thread;\n      /** UUID of the referenced thread */\n      threadId: Uuid;\n    };\n\n/**\n * Represents metadata about a thread, typically from an external system.\n *\n * Thread metadata enables storing additional information about threads,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createThread({\n *   title: \"Team Meeting\",\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createThread({\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ThreadMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Thread and Note entities.\n */\nexport type ThreadCommon = {\n  /** Unique identifier for the thread */\n  id: Uuid;\n  /**\n   * When this item was created.\n   *\n   * **For sources:** Set this to the external system's timestamp (e.g., email\n   * sent date, comment creation date), NOT the sync time. If omitted, defaults\n   * to the current time, which is almost never correct for synced data.\n   */\n  created: Date;\n  /** Whether this thread is private (only visible to creator) */\n  private: boolean;\n  /** Whether this thread has been archived */\n  archived: boolean;\n  /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\n};\n\n/**\n * Fields on a Thread entity.\n * Threads are simple containers for links and notes.\n */\ntype ThreadFields = ThreadCommon & {\n  /** The display title/summary of the thread */\n  title: string;\n  /** The priority context this thread belongs to */\n  priority: Priority;\n  /** The schedule associated with this thread, if any */\n  schedule?: Schedule;\n  /** Source-specific metadata from the thread's link, populated on callbacks */\n  meta?: ThreadMeta;\n};\n\nexport type Thread = ThreadFields;\n\nexport type ThreadWithNotes = Thread & {\n  notes: Note[];\n};\n\nexport type NewThreadWithNotes = NewThread & {\n  notes: Omit<NewNote, \"thread\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new threads.\n *\n * Threads are simple containers. All other fields are optional.\n *\n * @example\n * ```typescript\n * const thread: NewThread = {\n *   title: \"Review pull request\"\n * };\n * ```\n */\nexport type NewThread = Partial<\n  Omit<ThreadFields, \"priority\" | \"tags\" | \"mentions\" | \"id\">\n> &\n  (\n    | {\n        /** Unique identifier for the thread, generated by Uuid.Generate(). */\n        id: Uuid;\n      }\n    | {\n        /* id is optional. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the thread. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     */\n    preview?: string | null;\n\n    /**\n     * Optional schedules to create alongside the thread.\n     */\n    schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n\n    /**\n     * Optional schedule occurrence overrides.\n     */\n    scheduleOccurrences?: NewScheduleOccurrence[];\n  };\n\nexport type ThreadFilter = {\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many threads are included.\n */\ntype ThreadBulkUpdateFields = Partial<\n  Pick<ThreadFields, \"title\" | \"private\" | \"archived\">\n>;\n\n/**\n * Fields supported by single-thread updates via `id` or `source`.\n * Includes all bulk fields plus tags and preview.\n */\ntype ThreadSingleUpdateFields = ThreadBulkUpdateFields & {\n  /**\n   * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n   * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n   */\n  tags?: NewTags;\n\n  /**\n   * Add or remove the twist's tags.\n   * Maps tag ID to boolean: true = add tag, false = remove tag.\n   * This is allowed on all threads the twist has access to.\n   */\n  twistTags?: Partial<Record<Tag, boolean>>;\n\n  /**\n   * Optional preview content for the thread. Can be Markdown formatted.\n   * The preview will be automatically generated from this content (truncated to 100 chars).\n   *\n   * - string: Use this content for preview generation\n   * - null: Explicitly disable preview (no preview will be shown)\n   * - undefined (omitted): Preserve current preview value\n   *\n   * This field is write-only and won't be returned when reading threads.\n   */\n  preview?: string | null;\n};\n\nexport type ThreadUpdate =\n  | (({ id: Uuid } | { source: string }) & ThreadSingleUpdateFields)\n  | ({\n      /**\n       * Update all threads matching the specified criteria. Only threads\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ThreadFilter;\n    } & ThreadBulkUpdateFields);\n\n/**\n * Represents a note within a thread.\n *\n * Notes contain the detailed content (note text, actions) associated with a thread.\n * They are always ordered by creation time within their parent thread.\n */\nexport type Note = ThreadCommon & {\n  /** The author of this note */\n  author: Actor;\n  /**\n   * Globally unique, stable identifier for the note within its thread.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent thread this note belongs to */\n  thread: Thread;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive actions attached to the note */\n  actions: Array<Action> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the thread reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the thread\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<\n    Note,\n    \"author\" | \"thread\" | \"tags\" | \"mentions\" | \"id\" | \"key\" | \"reNote\"\n  >\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent thread (required) */\n    thread:\n      | Pick<Thread, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent thread as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<\n    Pick<Note, \"private\" | \"archived\" | \"content\" | \"actions\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with threads as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create threads.\n *\n * The author type affects how threads are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Threads created by human users */\n  User,\n  /** Threads created by external contacts */\n  Contact,\n  /** Threads created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /**\n   * Email address of the contact.\n   * Either email or source must be provided for contact resolution.\n   */\n  email?: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for identity resolution\n   * when email is unavailable and for privacy compliance reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n\n/**\n * Represents an external entity linked to a thread.\n *\n * Links are created by sources to represent external entities (issues, emails, calendar events)\n * attached to a thread container. A thread can have multiple links (1:many).\n * Links store source-specific data like type, status, metadata, and embeddings.\n *\n * @example\n * ```typescript\n * // A link representing a Linear issue\n * const link: Link = {\n *   id: \"...\" as Uuid,\n *   threadId: \"...\" as Uuid,\n *   source: \"linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b\",\n *   created: new Date(),\n *   author: { id: \"...\" as ActorId, type: ActorType.Contact, name: \"Alice\" },\n *   title: \"Fix login bug\",\n *   type: \"issue\",\n *   status: \"open\",\n *   meta: { projectId: \"TEAM\", url: \"https://linear.app/team/TEAM-123\" },\n *   assignee: null,\n *   actions: null,\n * };\n * ```\n */\nexport type Link = {\n  /** Unique identifier for the link */\n  id: Uuid;\n  /** The thread this link belongs to */\n  threadId: Uuid;\n  /** External source identifier for dedup/upsert */\n  source: string | null;\n  /** When this link was originally created in its source system */\n  created: Date;\n  /** The actor credited with creating this link */\n  author: Actor | null;\n  /** Display title */\n  title: string;\n  /** Truncated preview */\n  preview: string | null;\n  /** The actor assigned to this link */\n  assignee: Actor | null;\n  /** Source-defined type string (e.g., issue, pull_request, email, event) */\n  type: string | null;\n  /** Source-defined status string (e.g., open, done, closed) */\n  status: string | null;\n  /** Interactive action buttons */\n  actions: Array<Action> | null;\n  /** Source metadata */\n  meta: ThreadMeta | null;\n  /** URL to open the original item in its source application (e.g., \"Open in Linear\") */\n  sourceUrl: string | null;\n  /** Channel ID that produced this link (matches source_channel.channel_id) */\n  channelId: string | null;\n};\n\n/**\n * Type for creating new links.\n *\n * Links are created by sources to represent external entities.\n * Requires a source identifier for dedup/upsert.\n */\nexport type NewLink = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\n    /** The person that created the item. By default, it will be the twist itself. */\n    author?: NewActor;\n    /** The person assigned to the item. */\n    assignee?: NewActor | null;\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n    /**\n     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"id\">;\n  };\n\n/**\n * A new link with notes to save via integrations.saveLink().\n * Creates a thread+link pair, with notes attached to the thread.\n */\nexport type NewLinkWithNotes = NewLink & {\n  /**\n   * Title for the link and its thread container.\n   * Must be the real entity title (e.g. issue title, message subject),\n   * never a placeholder or ID. This value overwrites the existing title on upsert.\n   * If the title is not available in the webhook payload, fetch it from the API.\n   */\n  title: string;\n  /** Notes to attach to the thread */\n  notes?: Omit<NewNote, \"thread\">[];\n  /** Schedules to create for the link */\n  schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n  /** Schedule occurrence overrides */\n  scheduleOccurrences?: NewScheduleOccurrence[];\n};\n";
+export default "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with threads, notes, priorities, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Thread, Priority, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `title: string`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewThread, NewNote, NewPriority)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `title: string` in NewPriority\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new thread\n * const newThread: NewThread = {\n *   title: \"Review pull request\",\n * };\n *\n * // Updating a thread - only change what's specified\n * const update: ThreadUpdate = {\n *   id: threadId,\n *   archived: true,\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for priorities.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported action types.\n *\n * Different action types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActionType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback actions that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable action attached to a thread.\n *\n * Thread actions are rendered as buttons that enable user interaction with threads.\n * Different action types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External action - opens URL in browser\n * const externalAction: Action = {\n *   type: ActionType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing action - opens video conference with provider info\n * const conferencingAction: Action = {\n *   type: ActionType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations action - initiates OAuth flow\n * const authAction: Action = {\n *   type: ActionType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback action - triggers a twist method\n * const callbackAction: Action = {\n *   type: ActionType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type Action =\n  | {\n      /** External web link that opens in browser */\n      type: ActionType.external;\n      /** Display text for the action button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing action with provider-specific handling */\n      type: ActionType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication action that initiates an OAuth flow */\n      type: ActionType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback action that triggers a twist method when clicked */\n      type: ActionType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment action stored in R2 */\n      type: ActionType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n      /** Intrinsic width of the image in pixels (only for image files) */\n      imageWidth?: number | null;\n      /** Intrinsic height of the image in pixels (only for image files) */\n      imageHeight?: number | null;\n    }\n  | {\n      /** Thread reference action for navigating to a related thread */\n      type: ActionType.thread;\n      /** UUID of the referenced thread */\n      threadId: Uuid;\n    };\n\n/**\n * Represents metadata about a thread, typically from an external system.\n *\n * Thread metadata enables storing additional information about threads,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createThread({\n *   title: \"Team Meeting\",\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createThread({\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ThreadMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Thread sub-type that determines the thread's icon and category.\n * Available types depend on whether the priority is shared:\n * - Private priorities: \"notes\" (default), \"idea\", \"goal\", \"decision\"\n * - Shared priorities: all above plus \"discussion\" (default), \"announcement\", \"ask\"\n */\nexport type ThreadType =\n  | \"notes\"\n  | \"idea\"\n  | \"goal\"\n  | \"decision\"\n  | \"discussion\"\n  | \"announcement\"\n  | \"ask\";\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * Common fields shared by both Thread and Note entities.\n */\nexport type ThreadCommon = {\n  /** Unique identifier for the thread */\n  id: Uuid;\n  /**\n   * When this item was created.\n   *\n   * **For sources:** Set this to the external system's timestamp (e.g., email\n   * sent date, comment creation date), NOT the sync time. If omitted, defaults\n   * to the current time, which is almost never correct for synced data.\n   */\n  created: Date;\n  /** Whether this thread is private (only visible to creator) */\n  private: boolean;\n  /** Whether this thread has been archived */\n  archived: boolean;\n  /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\n};\n\n/**\n * Fields on a Thread entity.\n * Threads are simple containers for links and notes.\n */\ntype ThreadFields = ThreadCommon & {\n  /** The display title/summary of the thread */\n  title: string;\n  /** The priority context this thread belongs to */\n  priority: Priority;\n  /** The thread's sub-type/category. Determines the displayed icon. */\n  type: ThreadType | null;\n  /** The schedule associated with this thread, if any */\n  schedule?: Schedule;\n  /** Source-specific metadata from the thread's link, populated on callbacks */\n  meta?: ThreadMeta;\n};\n\nexport type Thread = ThreadFields;\n\nexport type ThreadWithNotes = Thread & {\n  notes: Note[];\n};\n\nexport type NewThreadWithNotes = NewThread & {\n  notes: Omit<NewNote, \"thread\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new threads.\n *\n * Threads are simple containers. All other fields are optional.\n *\n * @example\n * ```typescript\n * const thread: NewThread = {\n *   title: \"Review pull request\"\n * };\n * ```\n */\nexport type NewThread = Partial<\n  Omit<ThreadFields, \"priority\" | \"tags\" | \"mentions\" | \"id\">\n> &\n  (\n    | {\n        /** Unique identifier for the thread, generated by Uuid.Generate(). */\n        id: Uuid;\n      }\n    | {\n        /* id is optional. An id will be generated and returned. */\n      }\n  ) &\n  (\n    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * The thread's sub-type/category. Sets the thread's icon.\n     * If omitted, defaults to \"notes\" (private) or \"discussion\" (shared).\n     */\n    type?: ThreadType;\n\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the thread. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     */\n    preview?: string | null;\n\n    /**\n     * Optional schedules to create alongside the thread.\n     */\n    schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n\n    /**\n     * Optional schedule occurrence overrides.\n     */\n    scheduleOccurrences?: NewScheduleOccurrence[];\n  };\n\nexport type ThreadFilter = {\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many threads are included.\n */\ntype ThreadBulkUpdateFields = Partial<\n  Pick<ThreadFields, \"title\" | \"private\" | \"archived\">\n>;\n\n/**\n * Fields supported by single-thread updates via `id` or `source`.\n * Includes all bulk fields plus tags and preview.\n */\ntype ThreadSingleUpdateFields = ThreadBulkUpdateFields & {\n  /**\n   * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n   * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n   */\n  tags?: NewTags;\n\n  /**\n   * Add or remove the twist's tags.\n   * Maps tag ID to boolean: true = add tag, false = remove tag.\n   * This is allowed on all threads the twist has access to.\n   */\n  twistTags?: Partial<Record<Tag, boolean>>;\n\n  /**\n   * Update the thread's sub-type/category.\n   */\n  type?: ThreadType;\n\n  /**\n   * Optional preview content for the thread. Can be Markdown formatted.\n   * The preview will be automatically generated from this content (truncated to 100 chars).\n   *\n   * - string: Use this content for preview generation\n   * - null: Explicitly disable preview (no preview will be shown)\n   * - undefined (omitted): Preserve current preview value\n   *\n   * This field is write-only and won't be returned when reading threads.\n   */\n  preview?: string | null;\n};\n\nexport type ThreadUpdate =\n  | (({ id: Uuid } | { source: string }) & ThreadSingleUpdateFields)\n  | ({\n      /**\n       * Update all threads matching the specified criteria. Only threads\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ThreadFilter;\n    } & ThreadBulkUpdateFields);\n\n/**\n * Represents a note within a thread.\n *\n * Notes contain the detailed content (note text, actions) associated with a thread.\n * They are always ordered by creation time within their parent thread.\n */\nexport type Note = ThreadCommon & {\n  /** The author of this note */\n  author: Actor;\n  /**\n   * Globally unique, stable identifier for the note within its thread.\n   * Can be used to upsert without knowing the id.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent thread this note belongs to */\n  thread: Thread;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive actions attached to the note */\n  actions: Array<Action> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the thread reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the thread\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<\n    Note,\n    \"author\" | \"thread\" | \"tags\" | \"mentions\" | \"id\" | \"key\" | \"reNote\"\n  >\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent thread (required) */\n    thread:\n      | Pick<Thread, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent thread as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the priority at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<\n    Pick<Note, \"private\" | \"archived\" | \"content\" | \"actions\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Change the mentions on the note.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with threads as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create threads.\n *\n * The author type affects how threads are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Threads created by human users */\n  User,\n  /** Threads created by external contacts */\n  Contact,\n  /** Threads created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\nexport type NewContact = {\n  /**\n   * Email address of the contact.\n   * Either email or source must be provided for contact resolution.\n   */\n  email?: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for identity resolution\n   * when email is unavailable and for privacy compliance reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n\n/**\n * Represents an external entity linked to a thread.\n *\n * Links are created by sources to represent external entities (issues, emails, calendar events)\n * attached to a thread container. A thread can have multiple links (1:many).\n * Links store source-specific data like type, status, metadata, and embeddings.\n *\n * @example\n * ```typescript\n * // A link representing a Linear issue\n * const link: Link = {\n *   id: \"...\" as Uuid,\n *   threadId: \"...\" as Uuid,\n *   source: \"linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b\",\n *   created: new Date(),\n *   author: { id: \"...\" as ActorId, type: ActorType.Contact, name: \"Alice\" },\n *   title: \"Fix login bug\",\n *   type: \"issue\",\n *   status: \"open\",\n *   meta: { projectId: \"TEAM\", url: \"https://linear.app/team/TEAM-123\" },\n *   assignee: null,\n *   actions: null,\n * };\n * ```\n */\nexport type Link = {\n  /** Unique identifier for the link */\n  id: Uuid;\n  /** The thread this link belongs to */\n  threadId: Uuid;\n  /** External source identifier for dedup/upsert */\n  source: string | null;\n  /** When this link was originally created in its source system */\n  created: Date;\n  /** The actor credited with creating this link */\n  author: Actor | null;\n  /** Display title */\n  title: string;\n  /** Truncated preview */\n  preview: string | null;\n  /** The actor assigned to this link */\n  assignee: Actor | null;\n  /** Source-defined type string (e.g., issue, pull_request, email, event) */\n  type: string | null;\n  /** Source-defined status string (e.g., open, done, closed) */\n  status: string | null;\n  /** Interactive action buttons */\n  actions: Array<Action> | null;\n  /** Source metadata */\n  meta: ThreadMeta | null;\n  /** URL to open the original item in its source application (e.g., \"Open in Linear\") */\n  sourceUrl: string | null;\n  /** Channel ID that produced this link (matches source_channel.channel_id) */\n  channelId: string | null;\n};\n\n/**\n * Type for creating new links.\n *\n * Links are created by sources to represent external entities.\n * Requires a source identifier for dedup/upsert.\n */\nexport type NewLink = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\n    /** The person that created the item. By default, it will be the twist itself. */\n    author?: NewActor;\n    /** The person assigned to the item. */\n    assignee?: NewActor | null;\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - false: Thread is marked as read for all users in the priority at creation time\n     */\n    unread?: boolean;\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n    /**\n     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"id\">;\n  };\n\n/**\n * A new link with notes to save via integrations.saveLink().\n * Creates a thread+link pair, with notes attached to the thread.\n */\nexport type NewLinkWithNotes = NewLink & {\n  /**\n   * Title for the link and its thread container.\n   * Must be the real entity title (e.g. issue title, message subject),\n   * never a placeholder or ID. This value overwrites the existing title on upsert.\n   * If the title is not available in the webhook payload, fetch it from the API.\n   */\n  title: string;\n  /** Notes to attach to the thread */\n  notes?: Omit<NewNote, \"thread\">[];\n  /** Schedules to create for the link */\n  schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n  /** Schedule occurrence overrides */\n  scheduleOccurrences?: NewScheduleOccurrence[];\n};\n";
 //# sourceMappingURL=plot.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,o86BAAo86B,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,i+8BAAi+8B,CAAC"}

package/dist/llm-docs/tag.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "/**\n * Thread tags. Three types:\n * 1. Special tags, which trigger other behaviors\n * 2. Toggle tags, which anyone can toggle a shared value on or off\n * 3. Count tags, where everyone can add or remove their own\n */\nexport enum Tag {\n  // Special tags\n  Todo = 1,\n  Done = 3,\n\n  // Toggle tags\n  Pinned = 100,\n  Urgent = 101,\n  Goal = 103,\n  Decision = 104,\n  Waiting = 105,\n  Blocked = 106,\n  Warning = 107,\n  Question = 108,\n  Twist = 109,\n  Star = 110,\n  Idea = 111,\n\n  // Count tags\n  Yes = 1000,\n  No = 1001,\n  Volunteer = 1002,\n  Tada = 1003,\n  Fire = 1004,\n  Totally = 1005,\n  Looking = 1006,\n  Love = 1007,\n  Rocket = 1008,\n  Sparkles = 1009,\n  Thanks = 1010,\n  Smile = 1011,\n  Wave = 1012,\n  Praise = 1015,\n  Applause = 1016,\n  Cool = 1017,\n  Sad = 1018,\n}\n";
+declare const _default: "/**\n * Thread tags. Three types:\n * 1. Special tags, which trigger other behaviors\n * 2. Toggle tags, which anyone can toggle a shared value on or off\n * 3. Count tags, where everyone can add or remove their own\n */\nexport enum Tag {\n  // Special tags\n  Todo = 1,\n  Done = 3,\n\n  // Toggle tags\n  Pinned = 100,\n  Urgent = 101,\n  Goal = 103,\n  Decision = 104,\n  Waiting = 105,\n  Blocked = 106,\n  Warning = 107,\n  Question = 108,\n  Twist = 109,\n  Star = 110,\n  Idea = 111,\n\n  // Count tags\n  Yes = 1000,\n  No = 1001,\n  Volunteer = 1002,\n  Tada = 1003,\n  Fire = 1004,\n  Totally = 1005,\n  Looking = 1006,\n  Love = 1007,\n  Rocket = 1008,\n  Sparkles = 1009,\n  Thanks = 1010,\n  Smile = 1011,\n  Wave = 1012,\n  Praise = 1015,\n  Applause = 1016,\n  Cool = 1017,\n  Sad = 1018,\n  Reply = 1019,\n}\n";
 export default _default;
 //# sourceMappingURL=tag.d.ts.map

package/dist/llm-docs/tag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,2yBAA2yB;AAA1zB,wBAA2zB"}
+{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,4zBAA4zB;AAA30B,wBAA40B"}

package/dist/llm-docs/tag.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "/**\n * Thread tags. Three types:\n * 1. Special tags, which trigger other behaviors\n * 2. Toggle tags, which anyone can toggle a shared value on or off\n * 3. Count tags, where everyone can add or remove their own\n */\nexport enum Tag {\n  // Special tags\n  Todo = 1,\n  Done = 3,\n\n  // Toggle tags\n  Pinned = 100,\n  Urgent = 101,\n  Goal = 103,\n  Decision = 104,\n  Waiting = 105,\n  Blocked = 106,\n  Warning = 107,\n  Question = 108,\n  Twist = 109,\n  Star = 110,\n  Idea = 111,\n\n  // Count tags\n  Yes = 1000,\n  No = 1001,\n  Volunteer = 1002,\n  Tada = 1003,\n  Fire = 1004,\n  Totally = 1005,\n  Looking = 1006,\n  Love = 1007,\n  Rocket = 1008,\n  Sparkles = 1009,\n  Thanks = 1010,\n  Smile = 1011,\n  Wave = 1012,\n  Praise = 1015,\n  Applause = 1016,\n  Cool = 1017,\n  Sad = 1018,\n}\n";
+export default "/**\n * Thread tags. Three types:\n * 1. Special tags, which trigger other behaviors\n * 2. Toggle tags, which anyone can toggle a shared value on or off\n * 3. Count tags, where everyone can add or remove their own\n */\nexport enum Tag {\n  // Special tags\n  Todo = 1,\n  Done = 3,\n\n  // Toggle tags\n  Pinned = 100,\n  Urgent = 101,\n  Goal = 103,\n  Decision = 104,\n  Waiting = 105,\n  Blocked = 106,\n  Warning = 107,\n  Question = 108,\n  Twist = 109,\n  Star = 110,\n  Idea = 111,\n\n  // Count tags\n  Yes = 1000,\n  No = 1001,\n  Volunteer = 1002,\n  Tada = 1003,\n  Fire = 1004,\n  Totally = 1005,\n  Looking = 1006,\n  Love = 1007,\n  Rocket = 1008,\n  Sparkles = 1009,\n  Thanks = 1010,\n  Smile = 1011,\n  Wave = 1012,\n  Praise = 1015,\n  Applause = 1016,\n  Cool = 1017,\n  Sad = 1018,\n  Reply = 1019,\n}\n";
 //# sourceMappingURL=tag.js.map

package/dist/llm-docs/tag.js.map

@@ -1 +1 @@
-{"version":3,"file":"tag.js","sourceRoot":"","sources":["../../src/llm-docs/tag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,2yBAA2yB,CAAC"}
+{"version":3,"file":"tag.js","sourceRoot":"","sources":["../../src/llm-docs/tag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,4zBAA4zB,CAAC"}

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 and 3.7 series\n  CLAUDE_SONNET_45 = \"anthropic/claude-sonnet-4-5\",\n  CLAUDE_HAIKU_45 = \"anthropic/claude-haiku-4-5\",\n  CLAUDE_OPUS_41 = \"anthropic/claude-opus-4-1\",\n  CLAUDE_37_SONNET = \"anthropic/claude-3-7-sonnet-latest\",\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-5\" }\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  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 _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,2rwBAA2rwB;AAA1swB,wBAA2swB"}
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/ai.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,qnwBAAqnwB;AAApowB,wBAAqowB"}