@plotday/twister 0.60.0 → 0.61.0

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 { Cta, ThreadFacets } from \"./facets\";\nimport type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\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, focuses, 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, Focus, 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: `key: string | null`, `status: string | 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, NewFocus)\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 NewFocus\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 * - Thread and note authors, link assignees\n * - Tag creators (actor_id in thread_tag/note_tag)\n * - Mentions in notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for focuses.\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 focus within Plot.\n *\n * A focus is similar to a project or area-of-life. Every thread is in a focus.\n * Focuses are flat — they have no parent and no children. Threads not matched\n * to any focus live in the Inbox.\n */\nexport type Focus = {\n  /** Unique identifier for the focus */\n  id: Uuid;\n  /** Human-readable title for the focus */\n  title: string;\n  /** Whether this focus has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this focus.\n   * Keys are unique per user.\n   */\n  key: string | null;\n  /** Optional theme color for the focus (0-7). Defaults to 7 (Resolution) when not set. */\n  color: ThemeColor | null;\n  /** Optional icon for the focus (a curated icon key). Defaults to the focus icon when not set. */\n  icon: string | null;\n};\n\n/**\n * Type for creating new focuses.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the focus\n * - Provide a key for upsert within the user's focuses\n * - Omit both to auto-generate a new UUID\n */\nexport type NewFocus = Pick<Focus, \"title\"> &\n  Partial<Omit<Focus, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the focus, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert focuses.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the focus within the user's focuses.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot focus.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  );\n\n/**\n * Type for updating existing focuses.\n * Must provide either id or key to identify the focus to update.\n */\nexport type FocusUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Focus, \"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  /** Reference to an attachment hosted by a connector's source system */\n  fileRef = \"fileRef\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n  /** Structured plan of operations for user approval */\n  plan = \"plan\",\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      /** Reference to an attachment hosted by a connector's source system */\n      type: ActionType.fileRef;\n      /** Opaque identifier interpreted only by the owning connector */\n      ref: string;\n      /** Display filename */\n      fileName: string;\n      /** File size in bytes if known */\n      fileSize: number | null;\n      /** MIME type */\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      /** Structured plan of operations for user approval */\n      type: ActionType.plan;\n      /** Human-readable summary of the plan */\n      title: string;\n      /** Operations to execute on approval */\n      operations: PlanOperation[];\n      /** Callback invoked with (action, approved: boolean) */\n      callback: Callback;\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 focus is shared:\n * - Private focuses: \"action\" (default for tasks), \"notes\" (default), \"idea\", \"goal\", \"decision\"\n * - Shared focuses: all above plus \"discussion\" (default), \"announcement\", \"ask\"\n */\nexport type ThreadType =\n  | \"action\"\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 * A single emoji reaction key. Either:\n * - A Unicode emoji grapheme cluster (e.g. `\"👍\"`, `\"👨‍👩‍👧\"`), or\n * - A provider-scoped custom-emoji ref of the form\n *   `\"<provider>:<workspaceId>/<name>\"` (e.g. `\"slack:T0123/party_parrot\"`).\n *\n * Anything matching a known provider prefix is treated as a custom-emoji\n * reference; everything else is rendered as the Unicode it contains.\n *\n * Reactions are the open-set replacement for {@link Tag}'s retired count\n * range (`1000+`). Use reactions for emoji that round-trip with chat platforms;\n * use tags for Plot-managed compute/toggle state (todo, pinned, urgent,\n * ...).\n */\nexport type Reaction = string;\n\n/**\n * Emoji reactions on an item, keyed by emoji string, with the list of\n * actors who added each reaction.\n */\nexport type Reactions = Record<Reaction, ActorId[]>;\n\n/**\n * A set of reactions to add to an item, along with the actors adding each\n * reaction. To remove a reaction for a given actor, omit them from the\n * `NewActor[]` list — passing an empty list removes the reaction entirely.\n */\nexport type NewReactions = Record<Reaction, NewActor[]>;\n\n/**\n * Thread access level determining visibility.\n * - \"public\": Visible to all users with focus access\n * - \"members\": Visible to focus members (default for shared focuses)\n * - \"private\": Visible only to creator and contacts listed in accessContacts\n */\nexport type ThreadAccessLevel = \"public\" | \"members\" | \"private\";\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 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  /**\n   * Emoji reactions on this item. Maps each emoji (Unicode grapheme or\n   * `provider:workspace/name` custom-emoji ref) to the list of actor IDs\n   * who reacted with it.\n   */\n  reactions: Reactions;\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 focus context this thread belongs to */\n  focus: Focus;\n  /** The thread's sub-type/category. Determines the displayed icon. */\n  type: ThreadType | null;\n  /** Thread access level: \"public\", \"members\", or \"private\" */\n  access: ThreadAccessLevel;\n  /** Contacts who can see a private thread (empty array for creator-only). Only meaningful when access is \"private\". */\n  accessContacts: Contact[];\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 * 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, \"focus\" | \"tags\" | \"reactions\" | \"id\" | \"accessContacts\">\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    /** Explicit focus - disables automatic focus matching. When omitted, the server classifies the thread using the user's focus rules. */\n    focus?: Pick<Focus, \"id\">;\n  } & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to set on the new thread.\n     * Each emoji maps to the list of actors who reacted with it.\n     */\n    reactions?: NewReactions;\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     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\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 focus 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\" | \"access\" | \"archived\">\n> & {\n  /** Contacts who can see a private thread. Pass NewContact objects (email-based); resolved by the API. */\n  accessContacts?: NewContact[];\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   * Emoji reactions to change on the thread. Pass an empty `NewActor[]` to\n   * remove a reaction entirely; omit an emoji to leave it untouched.\n   */\n  reactions?: NewReactions;\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  /**\n   * Move the thread to a different focus. Requires ThreadAccess.Full.\n   * The target focus must be owned by the twist's user.\n   */\n  focus?: Pick<Focus, \"id\">;\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 + link.\n   * Can be used to upsert without knowing the id.\n   *\n   * Note keys are scoped to a `(thread, link)` pair — two links on the same\n   * thread (e.g. after a merge) can each carry a `\"description\"` note without\n   * colliding. The runtime infers the link from the surrounding `saveLink`\n   * call. For bare `saveNote` calls outside a `saveLink`, the runtime\n   * resolves the link by looking up the connector's links on the thread\n   * and errors if more than one matches.\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   * Contacts who can see this note, or null if the note inherits thread visibility.\n   * When set (even to []), the note is private to the listed contacts plus the creator.\n   */\n  accessContacts: ActorId[] | null;\n  /** Focus twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */\n  mentions: ActorId[];\n  /**\n   * A time-sensitive call-to-action extracted from this note's message\n   * (OTP code or confirm link). Null when none detected. Set by the runtime\n   * from the connector's extraction; clients read it to show an ephemeral prompt.\n   */\n  cta: Cta | 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\" | \"reactions\" | \"mentions\" | \"accessContacts\" | \"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     * Emoji reactions to set on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * Contacts who can see this note, or null/undefined to inherit thread visibility.\n     * Accepts resolved ActorId UUIDs or email-based NewContact objects (resolved server-side).\n     * Include all participants who should see the note (sender + recipients).\n     * The note author is NOT implicitly included — add them explicitly.\n     * When set (even to []), the note is private to the listed contacts plus the creator.\n     */\n    accessContacts?: (ActorId | NewContact)[] | null;\n\n    /**\n     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\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 focus 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     * When true, the server will use AI to detect tasks in this note's content\n     * and create separate Plot-authored reply notes for each detected task.\n     * Use for messaging connectors (email, chat) where tasks are implicit\n     * in conversation rather than explicitly structured.\n     */\n    checkForTasks?: 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     * A link carried by this note (note-attached, NOT a thread-level canonical\n     * link). Use for augmenter content (e.g. Granola meeting notes) that should\n     * attach to an existing canonical thread without becoming its primary link.\n     * The runtime creates the link note-scoped, binds `note.link_id` to it, and\n     * — when `thread: { source }` resolves to no existing thread — find-or-creates\n     * the thread by that source so a later canonical sync can fill the primary.\n     */\n    link?: NewLink;\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, \"accessContacts\" | \"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     * Emoji reactions to change on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\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     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\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 * A resolved contact with identity info. Used for access control lists\n * where only human contacts (not twists) are relevant.\n */\nexport type Contact = {\n  /** Unique identifier for the contact */\n  id: ActorId;\n  /** Email address, or null if not set */\n  email: string | null;\n  /** Display name, or null if not set */\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 threads, 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 */\n/**\n * Common fields shared by all NewContact variants.\n */\ntype NewContactBase = {\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   * The runtime scopes the resulting `contact_external_account` row to\n   * the dispatching twist instance (i.e. one row per connection per\n   * contact), so the same Plot contact can have multiple rows when\n   * reachable through multiple connections (e.g. two Slack workspaces,\n   * Gmail + Google Chat sharing one Google account).\n   */\n  source?: { accountId: string };\n  /**\n   * Optional connector-defined role for this contact on the thread, matching\n   * a `LinkTypeConfig.contactRoles[].id` (e.g. \"to\" / \"cc\" / \"bcc\" for\n   * email, \"required\" / \"optional\" for calendar). Omitted ⇒ default role.\n   * Connectors set this on inbound sync; the runtime persists it under\n   * `thread.contact_meta[contact_id].role`.\n   */\n  role?: string;\n};\n\n/**\n * At least one of `email` or `name` must be provided so the contact can be\n * identified in the UI. Contacts with neither would display as \"Unknown\".\n */\nexport type NewContact = NewContactBase &\n  ({ email: string; name?: string } | { email?: string; name: string });\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 *   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  /** 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   * Cross-connector thread bundling key.\n   *\n   * @deprecated Use `sources` instead. Reads return the first element of\n   * `sources` for backward compatibility; new writes should populate `sources`.\n   */\n  relatedSource: string | null;\n  /**\n   * Canonical identifiers for this link. Two links whose `sources` arrays\n   * overlap share the same thread (array overlap, `sources && new.sources`).\n   *\n   * Use this to bundle with another connector via a canonical alias. For\n   * example, every calendar connector emits `icaluid:<iCalUID>` so any\n   * meeting-notes connector can bundle by setting the same alias.\n   */\n  sources: string[];\n  /**\n   * Connector-supplied ranking used by clients to choose the single displayed\n   * (primary) canonical link when a thread has more than one. Higher wins;\n   * ties break on earliest creation. Default 0.\n   */\n  priority: number;\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 = Partial<\n  Omit<Link, \"author\" | \"assignee\" | \"threadId\">\n> & {\n  /**\n   * Canonical ID for the item in an external system.\n   * When set, uniquely identifies the link for the user. This performs\n   * an upsert.\n   *\n   * @deprecated Pass `sources: [...]` instead. Both fields can be set during\n   * the transition; the runtime will normalize.\n   */\n  source?: string;\n  /**\n   * Canonical identifiers for this item. Any element shared with another\n   * link's `sources` bundles the two links into the same thread. Used for\n   * cross-connector bundling — e.g. a meeting-notes connector setting\n   * `[\"granola:<id>\", \"icaluid:<uid>\"]` to attach onto a calendar event\n   * thread that includes `icaluid:<uid>` in its own `sources`.\n   */\n  sources?: string[];\n    /**\n     * Heuristic facets describing this item (format / automation / reach),\n     * used as internal classifier signal. Omit a dimension (or set null) when\n     * no heuristic is confident. See `@plotday/twister/facets`.\n     */\n    facets?: ThreadFacets;\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     * Thread access level: \"public\", \"members\" (default), or \"private\".\n     * When \"private\", thread visibility is limited to the creator and contacts in accessContacts.\n     */\n    access?: ThreadAccessLevel;\n    /**\n     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\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 focus 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     * Mark the thread as the connection owner's to-do at create time.\n     * - true: the thread is added to the owner's to-do (active) bucket and\n     *   their per-user archive is lifted, atomically with the save — no\n     *   separate `integrations.setThreadToDo()` round-trip needed.\n     * - false: the owner's thread_state is marked read (cleared from to-do).\n     * - undefined (omitted, default): leave to-do state untouched.\n     *\n     * Use for messaging-style \"saved for later\" flags (e.g. a starred Slack\n     * thread). This is the first-class replacement for overloading a\n     * `statuses[]` entry with `active: true`.\n     */\n    todo?: boolean;\n    /**\n     * The to-do date used when `todo` is true. Defaults to the \"Now\"\n     * sentinel (today's bucket) when omitted. Ignored when `todo` is not true.\n     */\n    todoDate?: Date | string;\n    /**\n     * Explicit focus (disables automatic focus matching).\n     * Only used when the link creates a new thread. When omitted, the\n     * server classifies the thread using the user's focus rules.\n     */\n    focus?: Pick<Focus, \"id\">;\n    /**\n     * Primary-link ranking for this canonical link (default 0). Set higher on\n     * the connection that \"owns\" the external item (e.g. the calendar that owns\n     * an event vs a subscribed copy) so clients display it as the primary.\n     */\n    priority?: number;\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   * Omit to preserve the existing title (e.g. for cancelled events where the\n   * title may not be available in the webhook payload).\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   * For `onCreateLink` only: binds the thread's opening note (the message the\n   * user composed in Plot, which this hook just posted to the external system)\n   * to its external counterpart. Mirrors the `NoteWriteBackResult` a reply\n   * returns from `onNoteCreated` — `key` is the external message id and\n   * `externalContent` is the post-write content baseline. Without this the\n   * opening note stays keyless, so reactions and edits on it can't be routed\n   * back to the external system. Ignored outside `onCreateLink`.\n   */\n  originatingNote?: {\n    /** External message id; set as the opening note's `key`. */\n    key?: string;\n    /**\n     * Content as the external system stored it post-write, for the sync\n     * baseline. Must equal what your sync-in path emits as this note's\n     * `content` on re-ingest (same contract as `NoteWriteBackResult.externalContent`).\n     */\n    externalContent?: string;\n  };\n};\n\n/**\n * Type for updating existing links.\n *\n * Set `threadId` to move the link to a different thread.\n * Requires LinkAccess.Full.\n */\nexport type LinkUpdate = { id: Uuid } & {\n  /** Move the link to a different thread owned by the twist's user. */\n  threadId?: Uuid;\n};\n\n/**\n * A single operation within a plan submitted for user approval.\n *\n * Operations include display metadata (titles) so the app can render\n * a human-readable summary without additional lookups.\n */\nexport type PlanOperation =\n  | {\n      type: \"updateThread\";\n      threadId: Uuid;\n      /** Current thread title for display */\n      threadTitle: string;\n      changes: Partial<Pick<ThreadFields, \"archived\" | \"title\" | \"type\">> & {\n        /** Move to this focus */\n        focus?: { id: Uuid; title: string };\n      };\n    }\n  | {\n      type: \"updateLink\";\n      linkId: Uuid;\n      /** Current link title for display */\n      linkTitle: string;\n      changes: {\n        /** Move to this thread */\n        threadId?: Uuid;\n        threadTitle?: string;\n      };\n    }\n  | {\n      type: \"createThread\";\n      title: string;\n      focusId: Uuid;\n      /** Focus title for display */\n      focusTitle: string;\n    }\n  | {\n      type: \"createNote\";\n      threadId: Uuid;\n      /** Thread title for display */\n      threadTitle: string;\n      content: string;\n    }\n  | {\n      type: \"updateFocus\";\n      focusId: Uuid;\n      /** Current focus title for display */\n      focusTitle: string;\n      changes: Partial<Pick<Focus, \"title\" | \"archived\">>;\n    };\n";
+export default "import type { Cta, ThreadFacets } from \"./facets\";\nimport type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\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, focuses, 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, Focus, 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: `key: string | null`, `status: string | 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, NewFocus)\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 NewFocus\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 * - Thread and note authors, link assignees\n * - Tag creators (actor_id in thread_tag/note_tag)\n * - Mentions in notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for focuses.\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 focus within Plot.\n *\n * A focus is similar to a project or area-of-life. Every thread is in a focus.\n * Focuses are flat — they have no parent and no children. Threads not matched\n * to any focus live in the Inbox.\n */\nexport type Focus = {\n  /** Unique identifier for the focus */\n  id: Uuid;\n  /** Human-readable title for the focus */\n  title: string;\n  /** Whether this focus has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this focus.\n   * Keys are unique per user.\n   */\n  key: string | null;\n  /** Optional theme color for the focus (0-7). Defaults to 7 (Resolution) when not set. */\n  color: ThemeColor | null;\n  /** Optional icon for the focus (a curated icon key). Defaults to the focus icon when not set. */\n  icon: string | null;\n};\n\n/**\n * Type for creating new focuses.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the focus\n * - Provide a key for upsert within the user's focuses\n * - Omit both to auto-generate a new UUID\n */\nexport type NewFocus = Pick<Focus, \"title\"> &\n  Partial<Omit<Focus, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the focus, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert focuses.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the focus within the user's focuses.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot focus.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  );\n\n/**\n * Type for updating existing focuses.\n * Must provide either id or key to identify the focus to update.\n */\nexport type FocusUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Focus, \"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  /** Reference to an attachment hosted by a connector's source system */\n  fileRef = \"fileRef\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n  /** Structured plan of operations for user approval */\n  plan = \"plan\",\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      /** Reference to an attachment hosted by a connector's source system */\n      type: ActionType.fileRef;\n      /** Opaque identifier interpreted only by the owning connector */\n      ref: string;\n      /** Display filename */\n      fileName: string;\n      /** File size in bytes if known */\n      fileSize: number | null;\n      /** MIME type */\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      /** Structured plan of operations for user approval */\n      type: ActionType.plan;\n      /** Human-readable summary of the plan */\n      title: string;\n      /** Operations to execute on approval */\n      operations: PlanOperation[];\n      /** Callback invoked with (action, approved: boolean) */\n      callback: Callback;\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 focus is shared:\n * - Private focuses: \"action\" (default for tasks), \"notes\" (default), \"idea\", \"goal\", \"decision\"\n * - Shared focuses: all above plus \"discussion\" (default), \"announcement\", \"ask\"\n */\nexport type ThreadType =\n  | \"action\"\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 * A single emoji reaction key. Either:\n * - A Unicode emoji grapheme cluster (e.g. `\"👍\"`, `\"👨‍👩‍👧\"`), or\n * - A provider-scoped custom-emoji ref of the form\n *   `\"<provider>:<workspaceId>/<name>\"` (e.g. `\"slack:T0123/party_parrot\"`).\n *\n * Anything matching a known provider prefix is treated as a custom-emoji\n * reference; everything else is rendered as the Unicode it contains.\n *\n * Reactions are the open-set replacement for {@link Tag}'s retired count\n * range (`1000+`). Use reactions for emoji that round-trip with chat platforms;\n * use tags for Plot-managed compute/toggle state (todo, pinned, urgent,\n * ...).\n */\nexport type Reaction = string;\n\n/**\n * Emoji reactions on an item, keyed by emoji string, with the list of\n * actors who added each reaction.\n */\nexport type Reactions = Record<Reaction, ActorId[]>;\n\n/**\n * A set of reactions to add to an item, along with the actors adding each\n * reaction. To remove a reaction for a given actor, omit them from the\n * `NewActor[]` list — passing an empty list removes the reaction entirely.\n */\nexport type NewReactions = Record<Reaction, NewActor[]>;\n\n/**\n * Thread access level determining visibility.\n * - \"public\": Visible to all users with focus access\n * - \"members\": Visible to focus members (default for shared focuses)\n * - \"private\": Visible only to creator and contacts listed in accessContacts\n */\nexport type ThreadAccessLevel = \"public\" | \"members\" | \"private\";\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 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  /**\n   * Emoji reactions on this item. Maps each emoji (Unicode grapheme or\n   * `provider:workspace/name` custom-emoji ref) to the list of actor IDs\n   * who reacted with it.\n   */\n  reactions: Reactions;\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 focus context this thread belongs to */\n  focus: Focus;\n  /** The thread's sub-type/category. Determines the displayed icon. */\n  type: ThreadType | null;\n  /** Thread access level: \"public\", \"members\", or \"private\" */\n  access: ThreadAccessLevel;\n  /** Contacts who can see a private thread (empty array for creator-only). Only meaningful when access is \"private\". */\n  accessContacts: Contact[];\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 * 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, \"focus\" | \"tags\" | \"reactions\" | \"id\" | \"accessContacts\">\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    /** Explicit focus - disables automatic focus matching. When omitted, the server classifies the thread using the user's focus rules. */\n    focus?: Pick<Focus, \"id\">;\n  } & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to set on the new thread.\n     * Each emoji maps to the list of actors who reacted with it.\n     */\n    reactions?: NewReactions;\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     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\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 focus 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\" | \"access\" | \"archived\">\n> & {\n  /** Contacts who can see a private thread. Pass NewContact objects (email-based); resolved by the API. */\n  accessContacts?: NewContact[];\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   * Emoji reactions to change on the thread. Pass an empty `NewActor[]` to\n   * remove a reaction entirely; omit an emoji to leave it untouched.\n   */\n  reactions?: NewReactions;\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  /**\n   * Move the thread to a different focus. Requires ThreadAccess.Full.\n   * The target focus must be owned by the twist's user.\n   */\n  focus?: Pick<Focus, \"id\">;\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 */\n/**\n * Reports that an outbound send / write-back for a note could not be\n * delivered to the external system, so Plot can surface it to the user.\n *\n * Returned (not thrown) from a write-back hook — see\n * `NoteWriteBackResult.deliveryError` and `NewLinkWithNotes.originatingNote` —\n * after the connector has exhausted its own retries (or immediately for a\n * permanent failure such as a rejected recipient). The runtime records it on\n * the note (the app then shows a \"Failed to send\" affordance with Retry /\n * Discard) and marks the thread unread so the user notices.\n */\nexport type DeliveryError = {\n  /**\n   * Short, stable machine code for the failure category, e.g. `\"rejected\"`,\n   * `\"too_large\"`, `\"rate_limited\"`, `\"invalid_recipient\"`, or the generic\n   * `\"send_failed\"`. Used for logging/diagnostics, not shown verbatim to users.\n   */\n  code: string;\n  /**\n   * Human-readable, user-safe explanation to show beside \"Failed to send\"\n   * (e.g. \"Recipient address rejected\"). Null/omitted when the connector has\n   * no safe message to surface — the app then shows just \"Failed to send\".\n   */\n  message?: string | null;\n};\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 + link.\n   * Can be used to upsert without knowing the id.\n   *\n   * Note keys are scoped to a `(thread, link)` pair — two links on the same\n   * thread (e.g. after a merge) can each carry a `\"description\"` note without\n   * colliding. The runtime infers the link from the surrounding `saveLink`\n   * call. For bare `saveNote` calls outside a `saveLink`, the runtime\n   * resolves the link by looking up the connector's links on the thread\n   * and errors if more than one matches.\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   * Contacts who can see this note, or null if the note inherits thread visibility.\n   * When set (even to []), the note is private to the listed contacts plus the creator.\n   */\n  accessContacts: ActorId[] | null;\n  /** Focus twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */\n  mentions: ActorId[];\n  /**\n   * A time-sensitive call-to-action extracted from this note's message\n   * (OTP code or confirm link). Null when none detected. Set by the runtime\n   * from the connector's extraction; clients read it to show an ephemeral prompt.\n   */\n  cta: Cta | 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\" | \"reactions\" | \"mentions\" | \"accessContacts\" | \"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     * Emoji reactions to set on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * Contacts who can see this note, or null/undefined to inherit thread visibility.\n     * Accepts resolved ActorId UUIDs or email-based NewContact objects (resolved server-side).\n     * Include all participants who should see the note (sender + recipients).\n     * The note author is NOT implicitly included — add them explicitly.\n     * When set (even to []), the note is private to the listed contacts plus the creator.\n     */\n    accessContacts?: (ActorId | NewContact)[] | null;\n\n    /**\n     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\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 focus 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     * When true, the server will use AI to detect tasks in this note's content\n     * and create separate Plot-authored reply notes for each detected task.\n     * Use for messaging connectors (email, chat) where tasks are implicit\n     * in conversation rather than explicitly structured.\n     */\n    checkForTasks?: 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     * A link carried by this note (note-attached, NOT a thread-level canonical\n     * link). Use for augmenter content (e.g. Granola meeting notes) that should\n     * attach to an existing canonical thread without becoming its primary link.\n     * The runtime creates the link note-scoped, binds `note.link_id` to it, and\n     * — when `thread: { source }` resolves to no existing thread — find-or-creates\n     * the thread by that source so a later canonical sync can fill the primary.\n     */\n    link?: NewLink;\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, \"accessContacts\" | \"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     * Emoji reactions to change on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\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     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\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 * A resolved contact with identity info. Used for access control lists\n * where only human contacts (not twists) are relevant.\n */\nexport type Contact = {\n  /** Unique identifier for the contact */\n  id: ActorId;\n  /** Email address, or null if not set */\n  email: string | null;\n  /** Display name, or null if not set */\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 threads, 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 */\n/**\n * Common fields shared by all NewContact variants.\n */\ntype NewContactBase = {\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   * The runtime scopes the resulting `contact_external_account` row to\n   * the dispatching twist instance (i.e. one row per connection per\n   * contact), so the same Plot contact can have multiple rows when\n   * reachable through multiple connections (e.g. two Slack workspaces,\n   * Gmail + Google Chat sharing one Google account).\n   */\n  source?: { accountId: string };\n  /**\n   * Optional connector-defined role for this contact on the thread, matching\n   * a `LinkTypeConfig.contactRoles[].id` (e.g. \"to\" / \"cc\" / \"bcc\" for\n   * email, \"required\" / \"optional\" for calendar). Omitted ⇒ default role.\n   * Connectors set this on inbound sync; the runtime persists it under\n   * `thread.contact_meta[contact_id].role`.\n   */\n  role?: string;\n};\n\n/**\n * At least one of `email` or `name` must be provided so the contact can be\n * identified in the UI. Contacts with neither would display as \"Unknown\".\n */\nexport type NewContact = NewContactBase &\n  ({ email: string; name?: string } | { email?: string; name: string });\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 *   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  /** 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   * Cross-connector thread bundling key.\n   *\n   * @deprecated Use `sources` instead. Reads return the first element of\n   * `sources` for backward compatibility; new writes should populate `sources`.\n   */\n  relatedSource: string | null;\n  /**\n   * Canonical identifiers for this link. Two links whose `sources` arrays\n   * overlap share the same thread (array overlap, `sources && new.sources`).\n   *\n   * Use this to bundle with another connector via a canonical alias. For\n   * example, every calendar connector emits `icaluid:<iCalUID>` so any\n   * meeting-notes connector can bundle by setting the same alias.\n   */\n  sources: string[];\n  /**\n   * Connector-supplied ranking used by clients to choose the single displayed\n   * (primary) canonical link when a thread has more than one. Higher wins;\n   * ties break on earliest creation. Default 0.\n   */\n  priority: number;\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 = Partial<\n  Omit<Link, \"author\" | \"assignee\" | \"threadId\">\n> & {\n  /**\n   * Canonical ID for the item in an external system.\n   * When set, uniquely identifies the link for the user. This performs\n   * an upsert.\n   *\n   * @deprecated Pass `sources: [...]` instead. Both fields can be set during\n   * the transition; the runtime will normalize.\n   */\n  source?: string;\n  /**\n   * Canonical identifiers for this item. Any element shared with another\n   * link's `sources` bundles the two links into the same thread. Used for\n   * cross-connector bundling — e.g. a meeting-notes connector setting\n   * `[\"granola:<id>\", \"icaluid:<uid>\"]` to attach onto a calendar event\n   * thread that includes `icaluid:<uid>` in its own `sources`.\n   */\n  sources?: string[];\n    /**\n     * Heuristic facets describing this item (format / automation / reach),\n     * used as internal classifier signal. Omit a dimension (or set null) when\n     * no heuristic is confident. See `@plotday/twister/facets`.\n     */\n    facets?: ThreadFacets;\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     * Thread access level: \"public\", \"members\" (default), or \"private\".\n     * When \"private\", thread visibility is limited to the creator and contacts in accessContacts.\n     */\n    access?: ThreadAccessLevel;\n    /**\n     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\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 focus 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     * Mark the thread as the connection owner's to-do at create time.\n     * - true: the thread is added to the owner's to-do (active) bucket and\n     *   their per-user archive is lifted, atomically with the save — no\n     *   separate `integrations.setThreadToDo()` round-trip needed.\n     * - false: the owner's thread_state is marked read (cleared from to-do).\n     * - undefined (omitted, default): leave to-do state untouched.\n     *\n     * Use for messaging-style \"saved for later\" flags (e.g. a starred Slack\n     * thread). This is the first-class replacement for overloading a\n     * `statuses[]` entry with `active: true`.\n     */\n    todo?: boolean;\n    /**\n     * The to-do date used when `todo` is true. Defaults to the \"Now\"\n     * sentinel (today's bucket) when omitted. Ignored when `todo` is not true.\n     */\n    todoDate?: Date | string;\n    /**\n     * Explicit focus (disables automatic focus matching).\n     * Only used when the link creates a new thread. When omitted, the\n     * server classifies the thread using the user's focus rules.\n     */\n    focus?: Pick<Focus, \"id\">;\n    /**\n     * Primary-link ranking for this canonical link (default 0). Set higher on\n     * the connection that \"owns\" the external item (e.g. the calendar that owns\n     * an event vs a subscribed copy) so clients display it as the primary.\n     */\n    priority?: number;\n    /**\n     * Opt this message into the platform's sequential auto-threading. When a\n     * connection has auto-threading enabled, the runtime decides — once,\n     * globally, at ingest — whether this message starts a new thread or folds\n     * (as a note) into the thread of the conversation it continues. Set it on\n     * every message of a conversational surface (a chat channel, a DM); the\n     * runtime keys the sequential chain on {@link AutoThreadConfig.key}.\n     *\n     * Marking a link is a no-op unless the connection opted in, so connectors\n     * can set it unconditionally on eligible links. Leave undefined/null for\n     * non-conversational items (issues, events, files). See\n     * {@link Connector.autoThreading}.\n     */\n    autoThread?: AutoThreadConfig | null;\n  };\n\n/**\n * How the runtime groups a connector's messages into threads when\n * auto-threading is enabled for the connection.\n *\n * - `\"sequential\"`: a chat **channel**. Each message either continues the\n *   previous message's conversation (folds in as a note) or starts a new\n *   thread, decided by a high-confidence continuation check. Use for\n *   multi-participant channels where consecutive top-level messages often\n *   form one conversation.\n * - `\"fold\"`: a **DM** / one-to-one surface. Every message folds into a\n *   single running thread for that {@link AutoThreadConfig.key} (no per-message\n *   judgment). Use for direct messages, which read naturally as one continuous\n *   conversation.\n */\nexport type AutoThreadMode = \"sequential\" | \"fold\";\n\n/** Per-link auto-threading directive. See {@link NewLink.autoThread}. */\nexport type AutoThreadConfig = {\n  /**\n   * The conversation grouping the sequential chain runs within — typically the\n   * connector's channel id ({@link Link.channelId}). DMs and each channel form\n   * independent chains. Messages are only ever folded into another message\n   * that shares this key.\n   */\n  key: string;\n  /** Channel (`\"sequential\"`) vs DM (`\"fold\"`) grouping. */\n  mode: AutoThreadMode;\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   * Omit to preserve the existing title (e.g. for cancelled events where the\n   * title may not be available in the webhook payload).\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   * For `onCreateLink` only: binds the thread's opening note (the message the\n   * user composed in Plot, which this hook just posted to the external system)\n   * to its external counterpart. Mirrors the `NoteWriteBackResult` a reply\n   * returns from `onNoteCreated` — `key` is the external message id and\n   * `externalContent` is the post-write content baseline. Without this the\n   * opening note stays keyless, so reactions and edits on it can't be routed\n   * back to the external system. Ignored outside `onCreateLink`.\n   */\n  originatingNote?: {\n    /** External message id; set as the opening note's `key`. */\n    key?: string;\n    /**\n     * Content as the external system stored it post-write, for the sync\n     * baseline. Must equal what your sync-in path emits as this note's\n     * `content` on re-ingest (same contract as `NoteWriteBackResult.externalContent`).\n     */\n    externalContent?: string;\n    /**\n     * Reports that sending the composed message FAILED (the `onCreateLink`\n     * send could not be delivered). The runtime records it on the opening\n     * note — surfacing a \"Failed to send\" affordance (Retry / Discard) — and\n     * marks the thread unread. Same contract as\n     * `NoteWriteBackResult.deliveryError`: object records, `null` clears,\n     * omitted leaves untouched. Return the link anyway (so the user's composed\n     * content is preserved in Plot) with this set, rather than returning\n     * `null`, when a compose send fails.\n     */\n    deliveryError?: DeliveryError | null;\n  };\n};\n\n/**\n * Type for updating existing links.\n *\n * Set `threadId` to move the link to a different thread.\n * Requires LinkAccess.Full.\n */\nexport type LinkUpdate = { id: Uuid } & {\n  /** Move the link to a different thread owned by the twist's user. */\n  threadId?: Uuid;\n};\n\n/**\n * A single operation within a plan submitted for user approval.\n *\n * Operations include display metadata (titles) so the app can render\n * a human-readable summary without additional lookups.\n */\nexport type PlanOperation =\n  | {\n      type: \"updateThread\";\n      threadId: Uuid;\n      /** Current thread title for display */\n      threadTitle: string;\n      changes: Partial<Pick<ThreadFields, \"archived\" | \"title\" | \"type\">> & {\n        /** Move to this focus */\n        focus?: { id: Uuid; title: string };\n      };\n    }\n  | {\n      type: \"updateLink\";\n      linkId: Uuid;\n      /** Current link title for display */\n      linkTitle: string;\n      changes: {\n        /** Move to this thread */\n        threadId?: Uuid;\n        threadTitle?: string;\n      };\n    }\n  | {\n      type: \"createThread\";\n      title: string;\n      focusId: Uuid;\n      /** Focus title for display */\n      focusTitle: string;\n    }\n  | {\n      type: \"createNote\";\n      threadId: Uuid;\n      /** Thread title for display */\n      threadTitle: string;\n      content: string;\n    }\n  | {\n      type: \"updateFocus\";\n      focusId: Uuid;\n      /** Current focus title for display */\n      focusTitle: string;\n      changes: Partial<Pick<Focus, \"title\" | \"archived\">>;\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,+60CAA+60C,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,4t8CAA4t8C,CAAC"}

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Actor,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstract parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token inline in the current execution.\n   *\n   * **Use `this.runTask()` instead for batch continuations and long-running work.**\n   * `this.run()` executes inline, sharing the current request count (~1000 limit)\n   * and blocking the HTTP response. This causes timeouts when used in lifecycle\n   * methods like `onChannelEnabled` or `syncBatch` continuations.\n   *\n   * `this.run()` is appropriate when you need the callback's **return value** \u2014\n   * e.g., running a parent callback token that returns data. For fire-and-forget\n   * work, always prefer `this.runTask()`.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u2705 Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // \u2705 undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // \u2705 Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // \u2705 Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<Callback>(\"handler_token\");\n   * await this.run(token);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Lists all storage keys matching a prefix.\n   *\n   * @param prefix - The prefix to match keys against\n   * @returns Promise resolving to an array of matching key strings\n   */\n  protected async list(prefix: string): Promise<string[]> {\n    return this.tools.store.list(prefix);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(this.processBatch, 1);\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
+declare const _default: "import {\n  type Actor,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstract parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token inline in the current execution.\n   *\n   * **Use `this.runTask()` instead for batch continuations and long-running work.**\n   * `this.run()` executes inline, sharing the current request count (~1000 limit)\n   * and blocking the HTTP response. This causes timeouts when used in lifecycle\n   * methods like `onChannelEnabled` or `syncBatch` continuations.\n   *\n   * `this.run()` is appropriate when you need the callback's **return value** \u2014\n   * e.g., running a parent callback token that returns data. For fire-and-forget\n   * work, always prefer `this.runTask()`.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // \u2705 Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // \u2705 undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // \u2705 Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // \u2705 Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // \u274C WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // \u2705 CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<Callback>(\"handler_token\");\n   * await this.run(token);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Lists all storage keys matching a prefix.\n   *\n   * @param prefix - The prefix to match keys against\n   * @returns Promise resolving to an array of matching key strings\n   */\n  protected async list(prefix: string): Promise<string[]> {\n    return this.tools.store.list(prefix);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(this.processBatch, 1);\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Schedules a **singleton** task keyed by `key`: re-scheduling under the same\n   * key atomically replaces any pending task, so at most one is ever live.\n   *\n   * Prefer this over `runTask({ runAt })` for recurring/self-renewing jobs\n   * (watch renewals, polling, deferred cleanup) \u2014 it removes the error-prone\n   * \"store token, cancel before re-scheduling\" bookkeeping that otherwise leaks\n   * parallel task chains. See {@link Tasks.scheduleTask}.\n   *\n   * @param key - Stable identifier scoped to what the task renews\n   * @param callback - The callback token created with `this.callback()`\n   * @param options.runAt - When to run (required)\n   * @returns Promise resolving to the scheduled task's cancellation token\n   */\n  protected async scheduleTask(\n    key: string,\n    callback: Callback,\n    options: { runAt: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.scheduleTask(key, callback, options);\n  }\n\n  /**\n   * Cancels the singleton task previously scheduled under `key` (if any).\n   * No-op if none exists or it already ran. See {@link Tasks.cancelScheduledTask}.\n   *\n   * @param key - The same key passed to {@link scheduleTask}\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelScheduledTask(key: string): Promise<void> {\n    return this.tools.tasks.cancelScheduledTask(key);\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
 export default _default;
 //# sourceMappingURL=tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,iiZAA8/Y;AAA7gZ,wBAA8gZ"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,26bAAm4b;AAAl5b,wBAAm5b"}

package/dist/llm-docs/tool.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import {\n  type Actor,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstract parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token inline in the current execution.\n   *\n   * **Use `this.runTask()` instead for batch continuations and long-running work.**\n   * `this.run()` executes inline, sharing the current request count (~1000 limit)\n   * and blocking the HTTP response. This causes timeouts when used in lifecycle\n   * methods like `onChannelEnabled` or `syncBatch` continuations.\n   *\n   * `this.run()` is appropriate when you need the callback's **return value** —\n   * e.g., running a parent callback token that returns data. For fire-and-forget\n   * work, always prefer `this.runTask()`.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // ✅ undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // ✅ Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // ✅ Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<Callback>(\"handler_token\");\n   * await this.run(token);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Lists all storage keys matching a prefix.\n   *\n   * @param prefix - The prefix to match keys against\n   * @returns Promise resolving to an array of matching key strings\n   */\n  protected async list(prefix: string): Promise<string[]> {\n    return this.tools.store.list(prefix);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(this.processBatch, 1);\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
+export default "import {\n  type Actor,\n} from \"./plot\";\nimport type { Callback } from \"./tools/callbacks\";\nimport type {\n  InferOptions,\n  InferTools,\n  Serializable,\n  ToolBuilder,\n  ToolShed,\n} from \"./utils/types\";\n\nexport type { ToolBuilder };\n\n/**\n * Abstract parent for both built-in tools and regular Tools.\n * Regular tools extend Tool.\n */\nexport abstract class ITool {}\n\n/**\n * Base class for regular tools.\n *\n * Regular tools run in isolation and can only access other tools declared\n * in their build method. They are ideal for external API integrations\n * and reusable functionality that doesn't require Plot's internal infrastructure.\n *\n * @example\n * ```typescript\n * class GoogleCalendarTool extends Tool<GoogleCalendarTool> {\n *   constructor(id: string, options: { clientId: string }) {\n *     super(id, options);\n *   }\n *\n *   build(tools: ToolBuilder) {\n *     return {\n *       auth: tools.build(Integrations),\n *       network: tools.build(Network),\n *     };\n *   }\n *\n *   async getCalendars() {\n *     const token = await this.tools.auth.get(...);\n *     // Implementation\n *   }\n * }\n * ```\n */\nexport abstract class Tool<TSelf> implements ITool {\n  constructor(\n    protected id: string,\n    protected options: InferOptions<TSelf>,\n    private toolShed: ToolShed\n  ) {}\n\n  /**\n   * Gets the initialized tools for this tool.\n   * @throws Error if called before initialization is complete\n   */\n  protected get tools() {\n    return this.toolShed.getTools<InferTools<TSelf>>();\n  }\n\n  /**\n   * Declares tool dependencies for this tool.\n   * Return an object mapping tool names to build() promises.\n   * Default implementation returns empty object (no custom tools).\n   *\n   * @param build - The build function to use for declaring dependencies\n   * @returns Object mapping tool names to tool promises\n   *\n   * @example\n   * ```typescript\n   * build(build: ToolBuilder) {\n   *   return {\n   *     network: build(Network, { urls: [\"https://api.example.com/*\"] }),\n   *   };\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  build(build: ToolBuilder): Record<string, Promise<ITool>> {\n    return {};\n  }\n\n  /**\n   * Creates a persistent callback to a method on this tool.\n   *\n   * ExtraArgs are strongly typed to match the method's signature.\n   *\n   * @param fn - The method to callback\n   * @param extraArgs - Additional arguments to pass (type-checked, must be serializable)\n   * @returns Promise resolving to a persistent callback token\n   *\n   * @example\n   * ```typescript\n   * const callback = await this.callback(this.onWebhook, \"calendar\", 123);\n   * ```\n   */\n  protected async callback<\n    TArgs extends Serializable[],\n    Fn extends (...args: TArgs) => any\n  >(fn: Fn, ...extraArgs: TArgs): Promise<Callback> {\n    return this.tools.callbacks.create(fn, ...extraArgs);\n  }\n\n  /**\n   * Deletes a specific callback by its token.\n   *\n   * @param token - The callback token to delete\n   * @returns Promise that resolves when the callback is deleted\n   */\n  protected async deleteCallback(token: Callback): Promise<void> {\n    return this.tools.callbacks.delete(token);\n  }\n\n  /**\n   * Deletes all callbacks for this tool.\n   *\n   * @returns Promise that resolves when all callbacks are deleted\n   */\n  protected async deleteAllCallbacks(): Promise<void> {\n    return this.tools.callbacks.deleteAll();\n  }\n\n  /**\n   * Executes a callback by its token inline in the current execution.\n   *\n   * **Use `this.runTask()` instead for batch continuations and long-running work.**\n   * `this.run()` executes inline, sharing the current request count (~1000 limit)\n   * and blocking the HTTP response. This causes timeouts when used in lifecycle\n   * methods like `onChannelEnabled` or `syncBatch` continuations.\n   *\n   * `this.run()` is appropriate when you need the callback's **return value** —\n   * e.g., running a parent callback token that returns data. For fire-and-forget\n   * work, always prefer `this.runTask()`.\n   *\n   * @param token - The callback token to execute\n   * @param args - Optional arguments to pass to the callback\n   * @returns Promise resolving to the callback result\n   */\n  protected async run(token: Callback, ...args: any[]): Promise<any> {\n    return this.tools.callbacks.run(token, ...args);\n  }\n\n  /**\n   * Retrieves a value from persistent storage by key.\n   *\n   * Values are automatically deserialized using SuperJSON, which\n   * properly restores Date objects, Maps, Sets, and other complex types.\n   *\n   * @template T - The expected type of the stored value (must be Serializable)\n   * @param key - The storage key to retrieve\n   * @returns Promise resolving to the stored value or null\n   */\n  protected async get<T extends Serializable>(key: string): Promise<T | null> {\n    return this.tools.store.get(key);\n  }\n\n  /**\n   * Stores a value in persistent storage.\n   *\n   * The value will be serialized using SuperJSON and stored persistently.\n   * SuperJSON automatically handles Date objects, Maps, Sets, undefined values,\n   * and other complex types that standard JSON doesn't support.\n   *\n   * **Important**: Functions and Symbols cannot be stored.\n   * **For function references**: Use callbacks instead of storing functions directly.\n   *\n   * @example\n   * ```typescript\n   * // ✅ Date objects are preserved\n   * await this.set(\"sync_state\", {\n   *   lastSync: new Date(),\n   *   minDate: new Date(2024, 0, 1)\n   * });\n   *\n   * // ✅ undefined is now supported\n   * await this.set(\"data\", { name: \"test\", optional: undefined });\n   *\n   * // ✅ Arrays with undefined are supported\n   * await this.set(\"items\", [1, undefined, 3]);\n   * await this.set(\"items\", [1, null, 3]); // Also works\n   *\n   * // ✅ Maps and Sets are supported\n   * await this.set(\"mapping\", new Map([[\"key\", \"value\"]]));\n   * await this.set(\"tags\", new Set([\"tag1\", \"tag2\"]));\n   *\n   * // ❌ WRONG: Cannot store functions directly\n   * await this.set(\"handler\", this.myHandler);\n   *\n   * // ✅ CORRECT: Create a callback token first\n   * const token = await this.callback(this.myHandler, \"arg1\", \"arg2\");\n   * await this.set(\"handler_token\", token);\n   *\n   * // Later, execute the callback\n   * const token = await this.get<Callback>(\"handler_token\");\n   * await this.run(token);\n   * ```\n   *\n   * @template T - The type of value being stored (must be Serializable)\n   * @param key - The storage key to use\n   * @param value - The value to store (must be SuperJSON-serializable)\n   * @returns Promise that resolves when the value is stored\n   */\n  protected async set<T extends Serializable>(\n    key: string,\n    value: T\n  ): Promise<void> {\n    return this.tools.store.set(key, value);\n  }\n\n  /**\n   * Lists all storage keys matching a prefix.\n   *\n   * @param prefix - The prefix to match keys against\n   * @returns Promise resolving to an array of matching key strings\n   */\n  protected async list(prefix: string): Promise<string[]> {\n    return this.tools.store.list(prefix);\n  }\n\n  /**\n   * Removes a specific key from persistent storage.\n   *\n   * @param key - The storage key to remove\n   * @returns Promise that resolves when the key is removed\n   */\n  protected async clear(key: string): Promise<void> {\n    return this.tools.store.clear(key);\n  }\n\n  /**\n   * Removes all keys from this tool's storage.\n   *\n   * @returns Promise that resolves when all keys are removed\n   */\n  protected async clearAll(): Promise<void> {\n    return this.tools.store.clearAll();\n  }\n\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * Use this to break long loops into chunks that each stay under the ~1000 request limit.\n   * Each task runs in an isolated execution environment with ~1000 requests and ~60 seconds CPU time.\n   *\n   * @param callback - The callback token created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches\n   * const callback = await this.callback(this.processBatch, 1);\n   * await this.runTask(callback); // New execution with fresh request limit\n   * ```\n   */\n  protected async runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.runTask(callback, options);\n  }\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelTask(token: string): Promise<void> {\n    return this.tools.tasks.cancelTask(token);\n  }\n\n  /**\n   * Cancels all scheduled executions for this tool.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  protected async cancelAllTasks(): Promise<void> {\n    return this.tools.tasks.cancelAllTasks();\n  }\n\n  /**\n   * Schedules a **singleton** task keyed by `key`: re-scheduling under the same\n   * key atomically replaces any pending task, so at most one is ever live.\n   *\n   * Prefer this over `runTask({ runAt })` for recurring/self-renewing jobs\n   * (watch renewals, polling, deferred cleanup) — it removes the error-prone\n   * \"store token, cancel before re-scheduling\" bookkeeping that otherwise leaks\n   * parallel task chains. See {@link Tasks.scheduleTask}.\n   *\n   * @param key - Stable identifier scoped to what the task renews\n   * @param callback - The callback token created with `this.callback()`\n   * @param options.runAt - When to run (required)\n   * @returns Promise resolving to the scheduled task's cancellation token\n   */\n  protected async scheduleTask(\n    key: string,\n    callback: Callback,\n    options: { runAt: Date }\n  ): Promise<string | void> {\n    return this.tools.tasks.scheduleTask(key, callback, options);\n  }\n\n  /**\n   * Cancels the singleton task previously scheduled under `key` (if any).\n   * No-op if none exists or it already ran. See {@link Tasks.cancelScheduledTask}.\n   *\n   * @param key - The same key passed to {@link scheduleTask}\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  protected async cancelScheduledTask(key: string): Promise<void> {\n    return this.tools.tasks.cancelScheduledTask(key);\n  }\n\n  /**\n   * Called before the twist's activate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * activate method is called.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when pre-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  preActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's activate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @param context - Optional context containing the actor who triggered activation\n   * @returns Promise that resolves when post-activation is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  postActivate(context?: { actor: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's upgrade method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * upgrade method is called.\n   *\n   * @returns Promise that resolves when pre-upgrade is complete\n   */\n  preUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's upgrade method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-upgrade is complete\n   */\n  postUpgrade(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called before the twist's deactivate method, starting from the deepest tool dependencies.\n   *\n   * This method is called in a depth-first manner, with the deepest dependencies\n   * being called first, bubbling up to the top-level tools before the twist's\n   * deactivate method is called.\n   *\n   * @returns Promise that resolves when pre-deactivation is complete\n   */\n  preDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called after the twist's deactivate method, starting from the top-level tools.\n   *\n   * This method is called in reverse order, with top-level tools being called\n   * first, then cascading down to the deepest dependencies.\n   *\n   * @returns Promise that resolves when post-deactivation is complete\n   */\n  postDeactivate(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Waits for tool initialization to complete.\n   * Called automatically by the entrypoint before lifecycle methods.\n   * @internal\n   */\n  async waitForReady(): Promise<void> {\n    await this.toolShed.waitForReady();\n  }\n}\n";
 //# sourceMappingURL=tool.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,8/YAA8/Y,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/llm-docs/tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,m4bAAm4b,CAAC"}

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks for execution in separate\n * worker contexts. **This is critical for staying under request limits**: each execution\n * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and\n * running a task creates a NEW execution with a fresh request limit.\n *\n * **Key distinction:**\n * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count\n * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit\n *\n * **When to use tasks:**\n * - Processing large datasets that would exceed 1000 requests\n * - Breaking loops into chunks where each chunk stays under the request limit\n * - Scheduling operations for future execution\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Size batches to stay under ~1000 requests per execution\n * - Calculate requests per item to determine safe batch size\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool<SyncTool> {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch\n *     const callback = await this.callback(this.processBatch, 1);\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(batchNumber: number) {\n *     // Process one batch of items (sized to stay under request limit)\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // If each item makes ~10 requests, process ~100 items per batch\n *     // 100 items \u00D7 10 requests = 1000 requests (at limit)\n *     const batchSize = 100;\n *     const items = await this.fetchItems(progress.processed, batchSize);\n *\n *     for (const item of items) {\n *       await this.processItem(item); // Makes ~10 requests per item\n *     }\n *\n *     await this.set(\"sync_progress\", {\n *       processed: progress.processed + batchSize,\n *       total: progress.total\n *     });\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch - creates NEW execution with fresh request limit\n *       const callback = await this.callback(this.processBatch, batchNumber + 1);\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(this.cleanupOldData);\n *     // Schedule for future execution\n *     return await this.runTask(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds\n   * CPU time. Use this for breaking loops into chunks that stay under the request limit.\n   *\n   * **Key distinction:**\n   * - `this.run(callback)` - Continues same execution, shares request count\n   * - `this.runTask(callback)` - NEW execution, fresh request limit\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches to stay under request limit\n   * const callback = await this.callback(this.syncBatch, 1);\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";
+declare const _default: "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks for execution in separate\n * worker contexts. **This is critical for staying under request limits**: each execution\n * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and\n * running a task creates a NEW execution with a fresh request limit.\n *\n * **Key distinction:**\n * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count\n * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit\n *\n * **When to use tasks:**\n * - Processing large datasets that would exceed 1000 requests\n * - Breaking loops into chunks where each chunk stays under the request limit\n * - Scheduling operations for future execution\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Size batches to stay under ~1000 requests per execution\n * - Calculate requests per item to determine safe batch size\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool<SyncTool> {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch\n *     const callback = await this.callback(this.processBatch, 1);\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(batchNumber: number) {\n *     // Process one batch of items (sized to stay under request limit)\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // If each item makes ~10 requests, process ~100 items per batch\n *     // 100 items \u00D7 10 requests = 1000 requests (at limit)\n *     const batchSize = 100;\n *     const items = await this.fetchItems(progress.processed, batchSize);\n *\n *     for (const item of items) {\n *       await this.processItem(item); // Makes ~10 requests per item\n *     }\n *\n *     await this.set(\"sync_progress\", {\n *       processed: progress.processed + batchSize,\n *       total: progress.total\n *     });\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch - creates NEW execution with fresh request limit\n *       const callback = await this.callback(this.processBatch, batchNumber + 1);\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(this.cleanupOldData);\n *     // Schedule for future execution\n *     return await this.runTask(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds\n   * CPU time. Use this for breaking loops into chunks that stay under the request limit.\n   *\n   * **Key distinction:**\n   * - `this.run(callback)` - Continues same execution, shares request count\n   * - `this.runTask(callback)` - NEW execution, fresh request limit\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches to stay under request limit\n   * const callback = await this.callback(this.syncBatch, 1);\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n\n  /**\n   * Schedules a **singleton** task identified by `key`: scheduling under a key\n   * that already has a pending task atomically cancels the existing one and\n   * replaces it. At most one scheduled task per `key` is ever live.\n   *\n   * Use this for any recurring/self-renewing job \u2014 webhook/watch renewals,\n   * periodic polling, deferred cleanup \u2014 instead of hand-managing tokens with\n   * `runTask()` + `cancelTask()`. The manual pattern (store the token, cancel\n   * it before re-scheduling) is easy to get wrong: a renewal callback that\n   * re-schedules itself, combined with any *extra* scheduling call (a\n   * re-dispatched `onChannelEnabled`, a re-init), leaks parallel self-\n   * perpetuating chains that accumulate forever and can trip the runtime's\n   * execution quota. Keying makes that leak impossible by construction.\n   *\n   * Replacement is atomic on the server, so concurrent executions racing to\n   * schedule the same key converge on a single task rather than leaking.\n   *\n   * @param key - Stable identifier for this logical task. Scope it to what it\n   *   renews, e.g. `` `watch-renewal:${folderId}` ``.\n   * @param callback - Callback created with `this.callback()`\n   * @param options.runAt - When to run. Required: keying only applies to\n   *   scheduled tasks (immediate tasks go straight to the queue).\n   * @returns Promise resolving to the cancellation token for the scheduled task\n   *\n   * @example\n   * ```typescript\n   * const cb = await this.callback(this.renewWatch, folderId);\n   * await this.scheduleTask(`watch-renewal:${folderId}`, cb, { runAt });\n   * // ...later, on disable:\n   * await this.cancelScheduledTask(`watch-renewal:${folderId}`);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract scheduleTask(\n    key: string,\n    callback: Callback,\n    options: { runAt: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels the singleton task previously scheduled under `key` (if any).\n   *\n   * No error is thrown if no task exists for the key or it has already run.\n   * Pair this with {@link scheduleTask} in teardown paths (e.g.\n   * `onChannelDisabled`, `stopSync`).\n   *\n   * @param key - The same key passed to {@link scheduleTask}\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelScheduledTask(key: string): Promise<void>;\n}\n";
 export default _default;
 //# sourceMappingURL=tasks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/tasks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,gjLAA2iL;AAA1jL,wBAA2jL"}
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/tasks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,6+PAA89P;AAA7+P,wBAA8+P"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks for execution in separate\n * worker contexts. **This is critical for staying under request limits**: each execution\n * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and\n * running a task creates a NEW execution with a fresh request limit.\n *\n * **Key distinction:**\n * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count\n * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit\n *\n * **When to use tasks:**\n * - Processing large datasets that would exceed 1000 requests\n * - Breaking loops into chunks where each chunk stays under the request limit\n * - Scheduling operations for future execution\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Size batches to stay under ~1000 requests per execution\n * - Calculate requests per item to determine safe batch size\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool<SyncTool> {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch\n *     const callback = await this.callback(this.processBatch, 1);\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(batchNumber: number) {\n *     // Process one batch of items (sized to stay under request limit)\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // If each item makes ~10 requests, process ~100 items per batch\n *     // 100 items × 10 requests = 1000 requests (at limit)\n *     const batchSize = 100;\n *     const items = await this.fetchItems(progress.processed, batchSize);\n *\n *     for (const item of items) {\n *       await this.processItem(item); // Makes ~10 requests per item\n *     }\n *\n *     await this.set(\"sync_progress\", {\n *       processed: progress.processed + batchSize,\n *       total: progress.total\n *     });\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch - creates NEW execution with fresh request limit\n *       const callback = await this.callback(this.processBatch, batchNumber + 1);\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(this.cleanupOldData);\n *     // Schedule for future execution\n *     return await this.runTask(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds\n   * CPU time. Use this for breaking loops into chunks that stay under the request limit.\n   *\n   * **Key distinction:**\n   * - `this.run(callback)` - Continues same execution, shares request count\n   * - `this.runTask(callback)` - NEW execution, fresh request limit\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches to stay under request limit\n   * const callback = await this.callback(this.syncBatch, 1);\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks for execution in separate\n * worker contexts. **This is critical for staying under request limits**: each execution\n * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and\n * running a task creates a NEW execution with a fresh request limit.\n *\n * **Key distinction:**\n * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count\n * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit\n *\n * **When to use tasks:**\n * - Processing large datasets that would exceed 1000 requests\n * - Breaking loops into chunks where each chunk stays under the request limit\n * - Scheduling operations for future execution\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Size batches to stay under ~1000 requests per execution\n * - Calculate requests per item to determine safe batch size\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool<SyncTool> {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch\n *     const callback = await this.callback(this.processBatch, 1);\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(batchNumber: number) {\n *     // Process one batch of items (sized to stay under request limit)\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // If each item makes ~10 requests, process ~100 items per batch\n *     // 100 items × 10 requests = 1000 requests (at limit)\n *     const batchSize = 100;\n *     const items = await this.fetchItems(progress.processed, batchSize);\n *\n *     for (const item of items) {\n *       await this.processItem(item); // Makes ~10 requests per item\n *     }\n *\n *     await this.set(\"sync_progress\", {\n *       processed: progress.processed + batchSize,\n *       total: progress.total\n *     });\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch - creates NEW execution with fresh request limit\n *       const callback = await this.callback(this.processBatch, batchNumber + 1);\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(this.cleanupOldData);\n *     // Schedule for future execution\n *     return await this.runTask(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds\n   * CPU time. Use this for breaking loops into chunks that stay under the request limit.\n   *\n   * **Key distinction:**\n   * - `this.run(callback)` - Continues same execution, shares request count\n   * - `this.runTask(callback)` - NEW execution, fresh request limit\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches to stay under request limit\n   * const callback = await this.callback(this.syncBatch, 1);\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n\n  /**\n   * Schedules a **singleton** task identified by `key`: scheduling under a key\n   * that already has a pending task atomically cancels the existing one and\n   * replaces it. At most one scheduled task per `key` is ever live.\n   *\n   * Use this for any recurring/self-renewing job — webhook/watch renewals,\n   * periodic polling, deferred cleanup — instead of hand-managing tokens with\n   * `runTask()` + `cancelTask()`. The manual pattern (store the token, cancel\n   * it before re-scheduling) is easy to get wrong: a renewal callback that\n   * re-schedules itself, combined with any *extra* scheduling call (a\n   * re-dispatched `onChannelEnabled`, a re-init), leaks parallel self-\n   * perpetuating chains that accumulate forever and can trip the runtime's\n   * execution quota. Keying makes that leak impossible by construction.\n   *\n   * Replacement is atomic on the server, so concurrent executions racing to\n   * schedule the same key converge on a single task rather than leaking.\n   *\n   * @param key - Stable identifier for this logical task. Scope it to what it\n   *   renews, e.g. `` `watch-renewal:${folderId}` ``.\n   * @param callback - Callback created with `this.callback()`\n   * @param options.runAt - When to run. Required: keying only applies to\n   *   scheduled tasks (immediate tasks go straight to the queue).\n   * @returns Promise resolving to the cancellation token for the scheduled task\n   *\n   * @example\n   * ```typescript\n   * const cb = await this.callback(this.renewWatch, folderId);\n   * await this.scheduleTask(`watch-renewal:${folderId}`, cb, { runAt });\n   * // ...later, on disable:\n   * await this.cancelScheduledTask(`watch-renewal:${folderId}`);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract scheduleTask(\n    key: string,\n    callback: Callback,\n    options: { runAt: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels the singleton task previously scheduled under `key` (if any).\n   *\n   * No error is thrown if no task exists for the key or it has already run.\n   * Pair this with {@link scheduleTask} in teardown paths (e.g.\n   * `onChannelDisabled`, `stopSync`).\n   *\n   * @param key - The same key passed to {@link scheduleTask}\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelScheduledTask(key: string): Promise<void>;\n}\n";
 //# sourceMappingURL=tasks.js.map

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

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,+idAAshd;AAArid,wBAAsid"}
+{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,y7fAA25f;AAA16f,wBAA26f"}