@plotday/twister 0.47.0 → 0.49.0

package/dist/llm-docs/connector.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import { type Actor, type ActorId, type Link, type NewLinkWithNotes, type Note, type Thread } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n  type AuthProvider,\n  type AuthToken,\n  type Authorization,\n  type Channel,\n  type LinkTypeConfig,\n  type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose — connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\nexport type CreateLinkDraft = {\n  /** The channel (account + resource) the new item belongs to. */\n  channelId: string;\n  /** Link type identifier, matches a `LinkTypeConfig.type`. */\n  type: string;\n  /** Status the user selected. Matches a `statuses[].status` for `type`. */\n  status: string;\n  /** Title of the originating Plot thread (post AI title generation). */\n  title: string;\n  /** Markdown content of the thread's first note, or null if none. */\n  noteContent: string | null;\n  /**\n   * Contacts attached to the originating Plot thread, excluding the\n   * creating user. Use these as recipients (email, chat DM members, etc.)\n   * when the external item is a message or invite. An empty list means\n   * the user did not add anyone to the thread.\n   */\n  contacts: Actor[];\n};\n\n/**\n * Base class for connectors — twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n *   readonly provider = AuthProvider.Linear;\n *   readonly scopes = [\"read\", \"write\"];\n *   readonly linkTypes = [{\n *     type: \"issue\",\n *     label: \"Issue\",\n *     statuses: [\n *       { status: \"open\", label: \"Open\" },\n *       { status: \"done\", label: \"Done\" },\n *     ],\n *   }];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const teams = await this.listTeams(token);\n *     return teams.map(t => ({ id: t.id, title: t.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     const issues = await this.fetchIssues(channel.id);\n *     for (const issue of issues) {\n *       await this.tools.integrations.saveLink(issue);\n *     }\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Clean up webhooks, sync state, etc.\n *   }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n  /**\n   * Static marker to identify Connector subclasses without instanceof checks\n   * across worker boundaries.\n   */\n  static readonly isConnector = true;\n\n  // ---- Identity (abstract — every connector must declare) ----\n\n  /** The OAuth provider this connector authenticates with. */\n  readonly provider?: AuthProvider;\n\n  /** OAuth scopes to request for this connector. */\n  readonly scopes?: string[];\n\n  // ---- Auth model ----\n\n  /**\n   * When true, one credential is shared across all users in the workspace,\n   * entered once by the installer. When false (default), each user provides\n   * their own credential.\n   *\n   * Applies to both OAuth and key-based connectors:\n   * - Shared OAuth: e.g. Slack bot token (workspace-level)\n   * - Shared key: e.g. Attio workspace API key\n   * - Individual OAuth: e.g. Google Calendar (per-user)\n   * - Individual key: e.g. Fellow (per-user API key)\n   */\n  readonly shared?: boolean;\n\n  /**\n   * The Options field name that contains the authentication key (e.g. \"apiKey\").\n   * Must reference a `secure: true` field in the Options schema.\n   *\n   * When set, this connector uses key-based auth instead of OAuth.\n   * For individual connectors (`shared` is false), this field is stored\n   * per-user rather than in shared config.\n   */\n  readonly keyOption?: string;\n\n  // ---- Optional metadata ----\n\n  /**\n   * When true, this connector has a single implicit channel.\n   * `getChannels()` must return exactly one Channel.\n   * The UI will show channel config inline instead of a channel list.\n   */\n  readonly singleChannel?: boolean;\n\n  /**\n   * Registry of link types this connector creates (e.g., issue, event, message).\n   * Used for display in the UI (icons, labels, statuses).\n   */\n  readonly linkTypes?: LinkTypeConfig[];\n\n  /**\n   * When true, this connector is mentioned by default on replies to threads it created.\n   * When false (default), this connector cannot be mentioned at all.\n   *\n   * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n   * messaging) where user replies should be written back to the external service.\n   */\n  static readonly handleReplies?: boolean;\n\n  // ---- Account identity (abstract — every connector must implement) ----\n\n  /**\n   * Returns a human-readable name for the connected account.\n   * Shown in the connections list and edit modal to identify this connection.\n   *\n   * For OAuth connectors, this is typically the workspace or organization name\n   * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n   * could be the workspace name from the external service.\n   *\n   * Override this in your connector to return a meaningful account name.\n   *\n   * @param auth - The authorization (null for no-provider connectors)\n   * @param token - The access token (null for no-provider connectors)\n   * @returns Promise resolving to the account display name\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  getAccountName(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<string | null> {\n    return Promise.resolve(null);\n  }\n\n  // ---- Channel lifecycle (abstract — every connector must implement) ----\n\n  /**\n   * Returns available channels for the authorized actor.\n   * Called after OAuth is complete, during the setup/edit modal.\n   *\n   * @param auth - The completed authorization with provider and actor info\n   * @param token - The access token for making API calls\n   * @returns Promise resolving to available channels for the user to select\n   */\n  abstract getChannels(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<Channel[]>;\n\n  /**\n   * Called when a channel resource is enabled for syncing.\n   *\n   * **IMPORTANT: This method runs inline in the HTTP request handler.**\n   * Any long-running work (webhook setup, API calls, sync) MUST be queued\n   * as a separate task via `this.runTask()`, not executed inline. Blocking\n   * here causes the client to spin waiting for the response.\n   *\n   * Only lightweight operations should appear directly in this method:\n   * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n   *\n   * @example\n   * ```typescript\n   * async onChannelEnabled(channel: Channel): Promise<void> {\n   *   await this.set(`sync_enabled_${channel.id}`, true);\n   *   await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n   *\n   *   // Queue sync as a task — do NOT use this.run() or call sync methods inline\n   *   const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n   *   await this.runTask(syncCallback);\n   *\n   *   // Queue webhook setup as a task — do NOT call setupWebhook() inline\n   *   const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n   *   await this.runTask(webhookCallback);\n   * }\n   * ```\n   *\n   * @param channel - The channel that was enabled\n   * @param context - Optional sync context with plan-based hints (e.g. syncHistoryMin)\n   */\n  abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n  /**\n   * Called when a channel resource is disabled.\n   * Should stop sync, clean up webhooks, and remove state.\n   *\n   * @param channel - The channel that was disabled\n   */\n  abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n  // ---- Write-back hooks (optional, default no-ops) ----\n\n  /**\n   * Called when a link created by this connector is updated by the user.\n   * Override to write back changes to the external service\n   * (e.g., changing issue status in Linear when marked done in Plot).\n   *\n   * @param link - The updated link\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkUpdated(link: Link): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user creates a thread in Plot that should create a new\n   * item in this connector's external system.\n   *\n   * A connector opts in to Plot-initiated creation by declaring a status\n   * with `createDefault: true` on the relevant `LinkTypeConfig`. When a\n   * user picks \"Create new <type>\" from the Add link modal and the thread\n   * is synced, the runtime calls this method with the draft fields.\n   *\n   * Implementations should create the item in the external service and\n   * return a `NewLinkWithNotes` describing the created item. The platform\n   * attaches the returned link to the originating thread — do not call\n   * `integrations.saveLink` yourself.\n   *\n   * Returning `null` aborts creation silently (the thread is still saved\n   * without a link).\n   *\n   * @param draft - The fields captured in Plot for the new item.\n   * @returns The link to attach, or null to abort creation.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n    return Promise.resolve(null);\n  }\n\n  /**\n   * Called when a note is created on a thread owned by this connector.\n   * Override to write back comments to the external service\n   * (e.g., adding a comment to a Linear issue).\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 created note\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   * @returns Optional note key for external deduplication\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteCreated(note: Note, thread: Thread): Promise<string | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a note on a thread owned by this connector is updated.\n   * Override to write back changes to the external service\n   * (e.g., syncing reaction tags as emoji reactions).\n   *\n   * @param note - The updated note (includes current tags)\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteUpdated(note: Note, thread: Thread): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user reads or unreads a thread owned by this connector.\n   * Override to write back read status to the external service\n   * (e.g., marking an email as read in Gmail).\n   *\n   * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n   * @param actor - The user who performed the action\n   * @param unread - false when marked as read, true when marked as unread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user marks or unmarks a thread as todo.\n   * Override to sync todo status to the external service\n   * (e.g., starring an email in Gmail when marked as todo).\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param actor - The user who changed the todo status\n   * @param todo - true when marked as todo, false when done or removed\n   * @param options - Additional context\n   * @param options.date - The todo date (when todo=true)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n   * Override to sync RSVP changes back to the external calendar.\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param scheduleId - The schedule ID\n   * @param contactId - The contact whose status changed\n   * @param status - The new RSVP status ('attend', 'skip', or null)\n   * @param actor - The user who changed the status\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n    return Promise.resolve();\n  }\n\n  // ---- Activation ----\n\n  /**\n   * Called when the connector is activated after OAuth is complete.\n   *\n   * Connectors receive the authorization in addition to the activating actor.\n   * When this runs, `this.userId` is already populated with the installing\n   * user's ID.\n   *\n   * Default implementation does nothing. Override for custom setup.\n   *\n   * @param context - The activation context\n   * @param context.auth - The completed OAuth authorization\n   * @param context.actor - The actor who activated the connector\n   */\n  // @ts-ignore - Connector.activate() has a Connector-specific context type.\n  activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";
+export default "import { type Actor, type ActorId, type Link, type NewLinkWithNotes, type Note, type Thread } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n  type AuthProvider,\n  type AuthToken,\n  type Authorization,\n  type Channel,\n  type LinkTypeConfig,\n  type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose — connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\n/**\n * Result returned from {@link Connector.onNoteCreated} and\n * {@link Connector.onNoteUpdated} to report what the external system now\n * has stored for the note.\n *\n * The runtime hashes `externalContent` and stores it as the note's sync\n * baseline. On the next sync-in, if the incoming content hashes to the\n * same value, the runtime knows the external side hasn't changed and\n * preserves Plot's (possibly formatted) content. When the external side\n * is edited, the hash diverges and the runtime overwrites Plot's content\n * with the new external version.\n *\n * Omitting `externalContent` skips baseline tracking — the next sync-in\n * will overwrite Plot's content (previous behavior). Always provide it\n * when the write-back's return value reflects what the external system\n * actually stored (often lossy plain-text), so the round-trip does not\n * clobber the original Plot markdown.\n *\n * The hash covers only the content string — the runtime intentionally\n * does not include a content-type in the hash, so write-back and sync-in\n * do not have to agree on a content-type label for the same underlying\n * bytes. Return exactly the string your connector's sync-in path will\n * emit as `NewNote.content` for this note on the next re-ingest.\n *\n * For back-compat, `onNoteCreated` may also return a plain string, which\n * is treated as `{ key }` with no baseline.\n */\nexport type NoteWriteBackResult = {\n  /**\n   * External system identifier assigned to this note. Set as the note's\n   * `key` for future upsert matching. Required when the runtime does not\n   * already know the key (i.e., from `onNoteCreated`); ignored from\n   * `onNoteUpdated` when the key was already established on create.\n   */\n  key?: string;\n  /**\n   * The content string as the external system now stores it, post-write.\n   * For systems whose write-back returns a representation of what was\n   * actually stored (e.g. Google Drive comment `content` after a create),\n   * pass that verbatim. For systems that only accept plain text, this\n   * will often be a lossy plain-text version of the Plot markdown — that\n   * is exactly the point: storing the lossy form as baseline lets the\n   * next sync-in recognize it and skip overwriting the richer Plot\n   * version.\n   *\n   * Must exactly match the string your connector's sync-in path emits as\n   * `NewNote.content` for this note on re-ingest.\n   */\n  externalContent?: string;\n};\n\nexport type CreateLinkDraft = {\n  /** The channel (account + resource) the new item belongs to. */\n  channelId: string;\n  /** Link type identifier, matches a `LinkTypeConfig.type`. */\n  type: string;\n  /** Status the user selected. Matches a `statuses[].status` for `type`. */\n  status: string;\n  /** Title of the originating Plot thread (post AI title generation). */\n  title: string;\n  /** Markdown content of the thread's first note, or null if none. */\n  noteContent: string | null;\n  /**\n   * Contacts attached to the originating Plot thread, excluding the\n   * creating user. Use these as recipients (email, chat DM members, etc.)\n   * when the external item is a message or invite. An empty list means\n   * the user did not add anyone to the thread.\n   */\n  contacts: Actor[];\n};\n\n/**\n * Base class for connectors — twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n *   readonly provider = AuthProvider.Linear;\n *   readonly scopes = [\"read\", \"write\"];\n *   readonly linkTypes = [{\n *     type: \"issue\",\n *     label: \"Issue\",\n *     statuses: [\n *       { status: \"open\", label: \"Open\" },\n *       { status: \"done\", label: \"Done\" },\n *     ],\n *   }];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const teams = await this.listTeams(token);\n *     return teams.map(t => ({ id: t.id, title: t.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     const issues = await this.fetchIssues(channel.id);\n *     for (const issue of issues) {\n *       await this.tools.integrations.saveLink(issue);\n *     }\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Clean up webhooks, sync state, etc.\n *   }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n  /**\n   * Static marker to identify Connector subclasses without instanceof checks\n   * across worker boundaries.\n   */\n  static readonly isConnector = true;\n\n  // ---- Identity (abstract — every connector must declare) ----\n\n  /** The OAuth provider this connector authenticates with. */\n  readonly provider?: AuthProvider;\n\n  /** OAuth scopes to request for this connector. */\n  readonly scopes?: string[];\n\n  // ---- Auth model ----\n\n  /**\n   * When true, one credential is shared across all users in the workspace,\n   * entered once by the installer. When false (default), each user provides\n   * their own credential.\n   *\n   * Applies to both OAuth and key-based connectors:\n   * - Shared OAuth: e.g. Slack bot token (workspace-level)\n   * - Shared key: e.g. Attio workspace API key\n   * - Individual OAuth: e.g. Google Calendar (per-user)\n   * - Individual key: e.g. Fellow (per-user API key)\n   */\n  readonly shared?: boolean;\n\n  /**\n   * The Options field name that contains the authentication key (e.g. \"apiKey\").\n   * Must reference a `secure: true` field in the Options schema.\n   *\n   * When set, this connector uses key-based auth instead of OAuth.\n   * For individual connectors (`shared` is false), this field is stored\n   * per-user rather than in shared config.\n   */\n  readonly keyOption?: string;\n\n  // ---- Optional metadata ----\n\n  /**\n   * When true, this connector has a single implicit channel.\n   * `getChannels()` must return exactly one Channel.\n   * The UI will show channel config inline instead of a channel list.\n   */\n  readonly singleChannel?: boolean;\n\n  /**\n   * Registry of link types this connector creates (e.g., issue, event, message).\n   * Used for display in the UI (icons, labels, statuses).\n   */\n  readonly linkTypes?: LinkTypeConfig[];\n\n  /**\n   * When true, this connector is mentioned by default on replies to threads it created.\n   * When false (default), this connector cannot be mentioned at all.\n   *\n   * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n   * messaging) where user replies should be written back to the external service.\n   */\n  static readonly handleReplies?: boolean;\n\n  // ---- Account identity (abstract — every connector must implement) ----\n\n  /**\n   * Returns a human-readable name for the connected account.\n   * Shown in the connections list and edit modal to identify this connection.\n   *\n   * For OAuth connectors, this is typically the workspace or organization name\n   * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n   * could be the workspace name from the external service.\n   *\n   * Override this in your connector to return a meaningful account name.\n   *\n   * @param auth - The authorization (null for no-provider connectors)\n   * @param token - The access token (null for no-provider connectors)\n   * @returns Promise resolving to the account display name\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  getAccountName(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<string | null> {\n    return Promise.resolve(null);\n  }\n\n  // ---- Channel lifecycle (abstract — every connector must implement) ----\n\n  /**\n   * Returns available channels for the authorized actor.\n   * Called after OAuth is complete, during the setup/edit modal.\n   *\n   * @param auth - The completed authorization with provider and actor info\n   * @param token - The access token for making API calls\n   * @returns Promise resolving to available channels for the user to select\n   */\n  abstract getChannels(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<Channel[]>;\n\n  /**\n   * Called when a channel resource is enabled for syncing.\n   *\n   * **IMPORTANT: This method runs inline in the HTTP request handler.**\n   * Any long-running work (webhook setup, API calls, sync) MUST be queued\n   * as a separate task via `this.runTask()`, not executed inline. Blocking\n   * here causes the client to spin waiting for the response.\n   *\n   * Only lightweight operations should appear directly in this method:\n   * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n   *\n   * @example\n   * ```typescript\n   * async onChannelEnabled(channel: Channel): Promise<void> {\n   *   await this.set(`sync_enabled_${channel.id}`, true);\n   *   await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n   *\n   *   // Queue sync as a task — do NOT use this.run() or call sync methods inline\n   *   const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n   *   await this.runTask(syncCallback);\n   *\n   *   // Queue webhook setup as a task — do NOT call setupWebhook() inline\n   *   const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n   *   await this.runTask(webhookCallback);\n   * }\n   * ```\n   *\n   * @param channel - The channel that was enabled\n   * @param context - Optional sync context with plan-based hints (e.g. syncHistoryMin)\n   */\n  abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n  /**\n   * Called when a channel resource is disabled.\n   * Should stop sync, clean up webhooks, and remove state.\n   *\n   * @param channel - The channel that was disabled\n   */\n  abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n  // ---- Write-back hooks (optional, default no-ops) ----\n\n  /**\n   * Called when a link created by this connector is updated by the user.\n   * Override to write back changes to the external service\n   * (e.g., changing issue status in Linear when marked done in Plot).\n   *\n   * @param link - The updated link\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkUpdated(link: Link): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user creates a thread in Plot that should create a new\n   * item in this connector's external system.\n   *\n   * A connector opts in to Plot-initiated creation by declaring a status\n   * with `createDefault: true` on the relevant `LinkTypeConfig`. When a\n   * user picks \"Create new <type>\" from the Add link modal and the thread\n   * is synced, the runtime calls this method with the draft fields.\n   *\n   * Implementations should create the item in the external service and\n   * return a `NewLinkWithNotes` describing the created item. The platform\n   * attaches the returned link to the originating thread — do not call\n   * `integrations.saveLink` yourself.\n   *\n   * Returning `null` aborts creation silently (the thread is still saved\n   * without a link).\n   *\n   * @param draft - The fields captured in Plot for the new item.\n   * @returns The link to attach, or null to abort creation.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n    return Promise.resolve(null);\n  }\n\n  /**\n   * Called when a note is created on a thread owned by this connector.\n   * Override to write back comments to the external service\n   * (e.g., adding a comment to a Linear issue).\n   *\n   * Returning a string or {@link NoteWriteBackResult} links the Plot note\n   * to its external counterpart. A plain string sets the note's `key`.\n   * A `NoteWriteBackResult` additionally sets a sync baseline (via\n   * `externalContent`) so the next sync-in can recognize the round-tripped\n   * content and preserve Plot's formatted version. See\n   * {@link NoteWriteBackResult} for details.\n   *\n   * @param note - The created note\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a note on a thread owned by this connector is updated.\n   * Override to write back changes to the external service\n   * (e.g., syncing reaction tags as emoji reactions, or editing a comment\n   * whose content changed in Plot).\n   *\n   * Return a {@link NoteWriteBackResult} with `externalContent` to update\n   * the sync baseline after a successful write-back, so the next sync-in\n   * recognizes the external version as already-seen and preserves Plot's\n   * content.\n   *\n   * @param note - The updated note (includes current tags)\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   * @returns Optional NoteWriteBackResult for baseline tracking\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user reads or unreads a thread owned by this connector.\n   * Override to write back read status to the external service\n   * (e.g., marking an email as read in Gmail).\n   *\n   * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n   * @param actor - The user who performed the action\n   * @param unread - false when marked as read, true when marked as unread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user marks or unmarks a thread as todo.\n   * Override to sync todo status to the external service\n   * (e.g., starring an email in Gmail when marked as todo).\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param actor - The user who changed the todo status\n   * @param todo - true when marked as todo, false when done or removed\n   * @param options - Additional context\n   * @param options.date - The todo date (when todo=true)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n   * Override to sync RSVP changes back to the external calendar.\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param scheduleId - The schedule ID\n   * @param contactId - The contact whose status changed\n   * @param status - The new RSVP status ('attend', 'skip', or null)\n   * @param actor - The user who changed the status\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n    return Promise.resolve();\n  }\n\n  // ---- Activation ----\n\n  /**\n   * Called when the connector is activated after OAuth is complete.\n   *\n   * Connectors receive the authorization in addition to the activating actor.\n   * When this runs, `this.userId` is already populated with the installing\n   * user's ID.\n   *\n   * Default implementation does nothing. Override for custom setup.\n   *\n   * @param context - The activation context\n   * @param context.auth - The completed OAuth authorization\n   * @param context.actor - The actor who activated the connector\n   */\n  // @ts-ignore - Connector.activate() has a Connector-specific context type.\n  activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";
 //# sourceMappingURL=connector.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/llm-docs/connector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,qjcAAqjc,CAAC"}
+{"version":3,"file":"connector.js","sourceRoot":"","sources":["../../src/llm-docs/connector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,+jiBAA+jiB,CAAC"}

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,4zBAA4zB;AAA30B,wBAA40B"}
+{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../src/llm-docs/tag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,y/BAAy/B;AAAxgC,wBAAygC"}

package/dist/llm-docs/tag.js

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

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

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

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Whether this status represents the connector's \"to-do\" / active state.\n     * When a user adds a thread to Plot's agenda, done-status links flip to\n     * the status marked `todo: true` (e.g., Gmail's \"starred\", Linear's\n     * \"todo\") so the link widget and thread tags reflect the active state.\n     * At most one status per type should set this.\n     */\n    todo?: boolean;\n    /**\n     * Default status applied when Plot asks the connector to create a new\n     * item of this type via `Connector.onCreateLink`. Declaring at least one\n     * status with `createDefault: true` is how a link type opts in to\n     * Plot-initiated creation. At most one status per type should set this.\n     */\n    createDefault?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) \u2014 the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+declare const _default: "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Whether this status represents the connector's \"to-do\" / active state.\n     * When a user adds a thread to Plot's agenda, done-status links flip to\n     * the status marked `todo: true` (e.g., Gmail's \"starred\", Linear's\n     * \"todo\") so the link widget and thread tags reflect the active state.\n     * At most one status per type should set this.\n     */\n    todo?: boolean;\n    /**\n     * Default status applied when Plot asks the connector to create a new\n     * item of this type via `Connector.onCreateLink`. Declaring at least one\n     * status with `createDefault: true` is how a link type opts in to\n     * Plot-initiated creation. At most one status per type should set this.\n     */\n    createDefault?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) \u2014 the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} \u2014 saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
 export default _default;
 //# sourceMappingURL=integrations.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,w5XAAm5X;AAAl6X,wBAAm6X"}
+{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,+qaAAqqa;AAApra,wBAAqra"}

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

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Whether this status represents the connector's \"to-do\" / active state.\n     * When a user adds a thread to Plot's agenda, done-status links flip to\n     * the status marked `todo: true` (e.g., Gmail's \"starred\", Linear's\n     * \"todo\") so the link widget and thread tags reflect the active state.\n     * At most one status per type should set this.\n     */\n    todo?: boolean;\n    /**\n     * Default status applied when Plot asks the connector to create a new\n     * item of this type via `Connector.onCreateLink`. Declaring at least one\n     * status with `createDefault: true` is how a link type opts in to\n     * Plot-initiated creation. At most one status per type should set this.\n     */\n    createDefault?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Whether this status represents the connector's \"to-do\" / active state.\n     * When a user adds a thread to Plot's agenda, done-status links flip to\n     * the status marked `todo: true` (e.g., Gmail's \"starred\", Linear's\n     * \"todo\") so the link widget and thread tags reflect the active state.\n     * At most one status per type should set this.\n     */\n    todo?: boolean;\n    /**\n     * Default status applied when Plot asks the connector to create a new\n     * item of this type via `Connector.onCreateLink`. Declaring at least one\n     * status with `createDefault: true` is how a link type opts in to\n     * Plot-initiated creation. At most one status per type should set this.\n     */\n    createDefault?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} — saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
 //# sourceMappingURL=integrations.js.map

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

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

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

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: cli/templates/AGENTS.template.md
  */
-declare const _default: "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)\n- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)\n- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit\n- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count\n- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Threads and Notes\n\n**CRITICAL CONCEPT**: A **Thread** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that thread.\n\n**Think of a Thread as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message\n3. **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.\n4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)\n5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`\n\n### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)\n\n```\nNew event/task/conversation from external system?\n  \u251C\u2500 Has stable URL or ID?\n  \u2502   \u2514\u2500 Yes \u2192 Set Thread.source to the canonical URL/ID\n  \u2502             Create Thread (Plot handles deduplication automatically)\n  \u2502             Use Note.key for different note types:\n  \u2502               - \"description\" for main content\n  \u2502               - \"metadata\" for status/priority/assignee\n  \u2502               - \"comment-{id}\" for individual comments\n  \u2502\n  \u2514\u2500 No stable identifier OR need multiple Plot threads per external item?\n      \u2514\u2500 Use Advanced Pattern (Strategy 3: Generate and Store IDs)\n          See SYNC_STRATEGIES.md for details\n```\n\n### Advanced Decision Tree (Strategy 3: Generate and Store IDs)\n\nOnly use when source/key upserts aren't sufficient (e.g., creating multiple threads from one external item):\n\n```\nNew event/task/conversation?\n  \u251C\u2500 Yes \u2192 Generate UUID with Uuid.Generate()\n  \u2502         Create new Thread with that UUID\n  \u2502         Store mapping: external_id \u2192 thread_uuid\n  \u2502\n  \u2514\u2500 No (update/reply/comment) \u2192 Look up mapping by external_id\n      \u251C\u2500 Found \u2192 Add Note to existing Thread using stored UUID\n      \u2514\u2500 Not found \u2192 Create new Thread with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Thread,\n  type NewThreadWithNotes,\n  type ThreadFilter,\n  type Priority,\n  type ToolBuilder,\n  Twist,\n  ThreadType,\n} from \"@plotday/twister\";\nimport { ThreadAccess, Plot } from \"@plotday/twister/tools/plot\";\n// Import your sources or tools as needed\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot, {\n        thread: { access: ThreadAccess.Create },\n      }),\n    };\n  }\n\n  async activate(_priority: Pick<Priority, \"id\">) {\n    // Auth and resource selection handled in the twist edit modal.\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Auth and resource selection are handled automatically via the twist edit modal when using external tools with Integrations.\n\nMost twists have an empty or minimal `activate()`:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Auth and resource selection are handled in the twist edit modal.\n  // Only add custom initialization here if needed.\n}\n```\n\n**Store Parent Thread for Later (optional):**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const threadId = await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Setup complete\",\n    notes: [{\n      content: \"Your twist is ready. Threads will appear as they sync.\",\n    }],\n  });\n  await this.set(\"setup_thread_id\", threadId);\n}\n```\n\n### Event Callbacks (via build options)\n\nTwists respond to events through callbacks declared in `build()`:\n\n**React to thread changes (for two-way sync):**\n\n```typescript\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\nasync onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {\n  const tool = this.getToolForThread(thread);\n  if (tool?.updateIssue) await tool.updateIssue(thread);\n}\n\nasync onNoteCreated(note: Note): Promise<void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment\n}\n```\n\n**Respond to mentions (AI twist pattern):**\n\n```typescript\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    intents: [{\n      description: \"Respond to general questions\",\n      examples: [\"What's the weather?\", \"Help me plan my week\"],\n      handler: this.respond,\n    }],\n  },\n}),\n```\n\n**Default mention on replies:**\n\nWhen your twist processes replies (two-way comment sync or conversational AI), set `defaultMention: true` so the user doesn't have to manually re-mention your twist on every note:\n\n- `thread.defaultMention` \u2014 Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` \u2014 Auto-mention on follow-up notes in threads where your twist was @-mentioned (e.g., conversational agents)\n\n```typescript\n// Connector with two-way comment sync\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    defaultMention: true,  // Users replying to synced threads will mention this twist by default\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\n// Conversational AI twist\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    defaultMention: true,  // Follow-up notes auto-mention this twist\n    intents: [{ description: \"...\", examples: [...], handler: this.respond }],\n  },\n}),\n```\n\nWithout `defaultMention`, the twist chip appears toggled OFF by default \u2014 the user can still enable it manually per-note.\n\n## Actions\n\nActions enable user interaction:\n\n```typescript\nimport { type Action, ActionType } from \"@plotday/twister\";\n\n// External URL action\nconst urlAction: Action = {\n  title: \"Open website\",\n  type: ActionType.external,\n  url: \"https://example.com\",\n};\n\n// Callback action (uses Callbacks tool \u2014 use linkCallback, not callback)\nconst token = await this.linkCallback(this.onActionClicked, \"context\");\nconst callbackAction: Action = {\n  title: \"Click me\",\n  type: ActionType.callback,\n  callback: token,\n};\n\n// Add to thread note\nawait this.tools.plot.createThread({\n  type: ThreadType.Note,\n  title: \"Task with actions\",\n  notes: [\n    {\n      content: \"Click the actions below to take action.\",\n      actions: [urlAction, callbackAction],\n    },\n  ],\n});\n\n// Callback handler receives the Action as first argument\nasync onActionClicked(action: Action, context: string): Promise<void> {\n  // Handle action click\n}\n```\n\n## Authentication Pattern\n\nAuth is handled automatically via the Integrations tool. Tools declare their OAuth provider in `build()`, and users connect in the twist edit modal. **You do not need to create auth activities manually.**\n\n```typescript\n// In your tool's build() method:\nbuild(build: ToolBuilder) {\n  return {\n    integrations: build(Integrations, {\n      providers: [{\n        provider: AuthProvider.Google,\n        scopes: [\"https://www.googleapis.com/auth/calendar\"],\n        getChannels: this.getChannels,          // List available resources after auth\n        onChannelEnabled: this.onChannelEnabled, // User enabled a resource\n        onChannelDisabled: this.onChannelDisabled, // User disabled a resource\n      }],\n    }),\n    // ...\n  };\n}\n\n// Get a token for API calls:\nconst token = await this.tools.integrations.get(AuthProvider.Google, channelId);\nif (!token) throw new Error(\"No auth token available\");\nconst client = new ApiClient({ accessToken: token.token });\n```\n\nFor per-user write-backs (e.g., RSVP, comments attributed to the acting user):\n\n```typescript\nawait this.tools.integrations.actAs(\n  AuthProvider.Google,\n  actorId,       // The user who performed the action\n  threadId,      // Thread to prompt for auth if needed\n  this.performWriteBack,\n  ...extraArgs\n);\n```\n\n## Sync Pattern\n\n### Upsert via Source/Key (Strategy 2)\n\nUse source/key for automatic upserts:\n\n```typescript\nasync handleEvent(event: ExternalEvent): Promise<void> {\n  const thread: NewThreadWithNotes = {\n    source: event.htmlLink,  // Canonical URL for automatic deduplication\n    type: ThreadType.Event,\n    title: event.summary || \"(No title)\",\n    notes: [],\n  };\n\n  if (event.description) {\n    thread.notes.push({\n      thread: { source: event.htmlLink },\n      key: \"description\",  // This key enables note-level upserts\n      content: event.description,\n    });\n  }\n\n  // Create or update \u2014 Plot handles deduplication automatically\n  await this.tools.plot.createThread(thread);\n}\n```\n\n### Advanced: Generate and Store IDs (Strategy 3)\n\nOnly use this pattern when you need to create multiple Plot threads from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.\n\n```typescript\nasync handleEventAdvanced(\n  incomingThread: NewThreadWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingThread.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingThreadId = await this.get<Uuid>(mappingKey);\n\n  if (existingThreadId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingThread.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        thread: { id: existingThreadId },\n        content: incomingThread.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const threadId = Uuid.Generate();\n  await this.set(mappingKey, threadId);\n\n  // Create new Thread with initial Note (new thread with first message)\n  await this.tools.plot.createThread({\n    ...incomingThread,\n    id: threadId,\n  });\n}\n```\n\n## Resource Selection\n\nResource selection (calendars, projects, channels) is handled automatically in the twist edit modal via the Integrations tool. Users see a list of available resources returned by your tool's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.\n\n```typescript\n// In your tool:\nasync getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {\n  const client = new ApiClient({ accessToken: token.token });\n  const calendars = await client.listCalendars();\n  return calendars.map(c => ({\n    id: c.id,\n    title: c.name,\n    children: c.subCalendars?.map(sc => ({ id: sc.id, title: sc.name })),\n  }));\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.\n\n### Key Principles\n\n1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.\n2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests\n3. **Store state between batches**: Use the Store tool to persist progress\n4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)\n5. **Clean up when done**: Delete stored state after completion\n6. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n    initialSync: true,  // Track whether this is the first sync\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  // runTask creates NEW execution with fresh ~1000 request limit\n  await this.runTask(callback);\n}\n\nasync syncBatch(resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (size to stay under ~1000 request limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results using source/key pattern (automatic upserts, no manual tracking)\n  // If each item makes ~10 requests, keep batch size \u2264 100 items to stay under limit\n  for (const item of result.items) {\n    // Each createThread may make ~5-10 requests depending on notes/links\n    await this.tools.plot.createThread({\n      source: item.url, // Use item's canonical URL for automatic deduplication\n      type: ThreadType.Note,\n      title: item.title,\n      notes: [{\n        activity: { source: item.url },\n        key: \"description\", // Use key for upsertable notes\n        content: item.description,\n      }],\n      ...(state.initialSync ? { unread: false } : {}), // false for initial, omit for incremental\n      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n      initialSync: state.initialSync, // Preserve initialSync flag across batches\n    });\n\n    // Queue next batch - creates NEW execution with fresh request limit\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createThread({\n      type: ThreadType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Thread Sync Best Practices\n\nWhen syncing threads from external systems, follow these patterns for optimal user experience:\n\n### The `initialSync` Flag\n\nAll sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):\n\n| Field | Initial Sync | Incremental Sync | Reason |\n|-------|--------------|------------------|---------|\n| `unread` | `false` | *omit* | Initial: mark read for all. Incremental: auto-mark read for author only |\n| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |\n\n**Example:**\n```typescript\nconst thread: NewThread = {\n  type: ThreadType.Event,\n  source: event.url,\n  title: event.title,\n  ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental\n  ...(initialSync ? { archived: false } : {}),    // unarchive on initial only\n};\n```\n\n**Why this matters:**\n- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports\n- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved\n- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)\n\n### Two-Way Sync: Avoiding Race Conditions\n\nWhen implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Thread/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.\n\n**Solution:** Embed the Plot `Thread.id` / `Note.id` in the external item's metadata when creating it, and update `Thread.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.\n\n```typescript\nasync pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {\n  // Create external item with Plot ID in metadata for webhook correlation\n  const externalComment = await externalApi.createComment(externalItemId, {\n    body: note.content,\n    metadata: { plotNoteId: note.id },\n  });\n\n  // Update Note with external key AFTER creation\n  // A webhook may arrive before this completes \u2014 that's OK (see onWebhook below)\n  await this.tools.plot.updateNote({\n    id: note.id,\n    key: `comment-${externalComment.id}`,\n  });\n}\n\nasync onWebhook(payload: WebhookPayload): Promise<void> {\n  const comment = payload.comment;\n\n  // Use Plot ID from metadata if present (handles race condition),\n  // otherwise fall back to upserting by activity source and key\n  await this.tools.plot.createNote({\n    ...(comment.metadata?.plotNoteId\n      ? { id: comment.metadata.plotNoteId }\n      : { activity: { source: payload.itemUrl } }),\n    key: `comment-${comment.id}`,\n    content: comment.body,\n  });\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created threads** - Other users may change a Thread created by the twist, resulting in a callback. Be sure to check the `changes === null` and/or `thread.author.id !== this.id` to avoid re-processing.\n- **Always create Threads with Notes** - See \"Understanding Threads and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.\n- **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).\n- **Add Notes to existing Threads** - For source/key pattern, reference threads by source. For UUID pattern, look up stored mappings before creating new Threads. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n- **CRITICAL: Maintain callback backward compatibility** - All callbacks (webhooks, tasks, batch operations) automatically upgrade to new twist versions. You **must** maintain backward compatibility in callback method signatures. Only add optional parameters at the end, never remove or reorder parameters. For breaking changes, implement migration logic in the `upgrade()` lifecycle method to recreate affected callbacks.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
+declare const _default: "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)\n- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)\n- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit\n- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count\n- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Threads and Notes\n\n**CRITICAL CONCEPT**: A **Thread** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that thread.\n\n**Think of a Thread as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message\n3. **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.\n4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)\n5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`\n\n### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)\n\n```\nNew event/task/conversation from external system?\n  \u251C\u2500 Has stable URL or ID?\n  \u2502   \u2514\u2500 Yes \u2192 Set Thread.source to the canonical URL/ID\n  \u2502             Create Thread (Plot handles deduplication automatically)\n  \u2502             Use Note.key for different note types:\n  \u2502               - \"description\" for main content\n  \u2502               - \"metadata\" for status/priority/assignee\n  \u2502               - \"comment-{id}\" for individual comments\n  \u2502\n  \u2514\u2500 No stable identifier OR need multiple Plot threads per external item?\n      \u2514\u2500 Use Advanced Pattern (Strategy 3: Generate and Store IDs)\n          See SYNC_STRATEGIES.md for details\n```\n\n### Advanced Decision Tree (Strategy 3: Generate and Store IDs)\n\nOnly use when source/key upserts aren't sufficient (e.g., creating multiple threads from one external item):\n\n```\nNew event/task/conversation?\n  \u251C\u2500 Yes \u2192 Generate UUID with Uuid.Generate()\n  \u2502         Create new Thread with that UUID\n  \u2502         Store mapping: external_id \u2192 thread_uuid\n  \u2502\n  \u2514\u2500 No (update/reply/comment) \u2192 Look up mapping by external_id\n      \u251C\u2500 Found \u2192 Add Note to existing Thread using stored UUID\n      \u2514\u2500 Not found \u2192 Create new Thread with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Thread,\n  type NewThreadWithNotes,\n  type ThreadFilter,\n  type Priority,\n  type ToolBuilder,\n  Twist,\n  ThreadType,\n} from \"@plotday/twister\";\nimport { ThreadAccess, Plot } from \"@plotday/twister/tools/plot\";\n// Import your sources or tools as needed\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot, {\n        thread: { access: ThreadAccess.Create },\n      }),\n    };\n  }\n\n  async activate(_priority: Pick<Priority, \"id\">) {\n    // Auth and resource selection handled in the twist edit modal.\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Auth and resource selection are handled automatically via the twist edit modal when using external tools with Integrations.\n\nMost twists have an empty or minimal `activate()`:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Auth and resource selection are handled in the twist edit modal.\n  // Only add custom initialization here if needed.\n}\n```\n\n**Store Parent Thread for Later (optional):**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const threadId = await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Setup complete\",\n    notes: [{\n      content: \"Your twist is ready. Threads will appear as they sync.\",\n    }],\n  });\n  await this.set(\"setup_thread_id\", threadId);\n}\n```\n\n### Event Callbacks (via build options)\n\nTwists respond to events through callbacks declared in `build()`:\n\n**React to thread changes (for two-way sync):**\n\n```typescript\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\nasync onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {\n  const tool = this.getToolForThread(thread);\n  if (tool?.updateIssue) await tool.updateIssue(thread);\n}\n\nasync onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment. Return the external\n  // system's id + stored content so the runtime can set note.key AND\n  // record a sync baseline that preserves Plot's content on round-trip.\n  // See connectors/AGENTS.md \u2192 \"Sync baseline preservation\".\n  const comment = await externalApi.createComment(thread.meta.externalId, { body: note.content ?? \"\" });\n  if (!comment?.id) return;\n  return { key: `comment-${comment.id}`, externalContent: comment.body };\n}\n```\n\n**Respond to mentions (AI twist pattern):**\n\n```typescript\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    intents: [{\n      description: \"Respond to general questions\",\n      examples: [\"What's the weather?\", \"Help me plan my week\"],\n      handler: this.respond,\n    }],\n  },\n}),\n```\n\n**Default mention on replies:**\n\nWhen your twist processes replies (two-way comment sync or conversational AI), set `defaultMention: true` so the user doesn't have to manually re-mention your twist on every note:\n\n- `thread.defaultMention` \u2014 Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` \u2014 Auto-mention on follow-up notes in threads where your twist was @-mentioned (e.g., conversational agents)\n\n```typescript\n// Connector with two-way comment sync\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    defaultMention: true,  // Users replying to synced threads will mention this twist by default\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\n// Conversational AI twist\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    defaultMention: true,  // Follow-up notes auto-mention this twist\n    intents: [{ description: \"...\", examples: [...], handler: this.respond }],\n  },\n}),\n```\n\nWithout `defaultMention`, the twist chip appears toggled OFF by default \u2014 the user can still enable it manually per-note.\n\n## Actions\n\nActions enable user interaction:\n\n```typescript\nimport { type Action, ActionType } from \"@plotday/twister\";\n\n// External URL action\nconst urlAction: Action = {\n  title: \"Open website\",\n  type: ActionType.external,\n  url: \"https://example.com\",\n};\n\n// Callback action (uses Callbacks tool \u2014 use linkCallback, not callback)\nconst token = await this.linkCallback(this.onActionClicked, \"context\");\nconst callbackAction: Action = {\n  title: \"Click me\",\n  type: ActionType.callback,\n  callback: token,\n};\n\n// Add to thread note\nawait this.tools.plot.createThread({\n  type: ThreadType.Note,\n  title: \"Task with actions\",\n  notes: [\n    {\n      content: \"Click the actions below to take action.\",\n      actions: [urlAction, callbackAction],\n    },\n  ],\n});\n\n// Callback handler receives the Action as first argument\nasync onActionClicked(action: Action, context: string): Promise<void> {\n  // Handle action click\n}\n```\n\n## Authentication Pattern\n\nAuth is handled automatically via the Integrations tool. Tools declare their OAuth provider in `build()`, and users connect in the twist edit modal. **You do not need to create auth activities manually.**\n\n```typescript\n// In your tool's build() method:\nbuild(build: ToolBuilder) {\n  return {\n    integrations: build(Integrations, {\n      providers: [{\n        provider: AuthProvider.Google,\n        scopes: [\"https://www.googleapis.com/auth/calendar\"],\n        getChannels: this.getChannels,          // List available resources after auth\n        onChannelEnabled: this.onChannelEnabled, // User enabled a resource\n        onChannelDisabled: this.onChannelDisabled, // User disabled a resource\n      }],\n    }),\n    // ...\n  };\n}\n\n// Get a token for API calls:\nconst token = await this.tools.integrations.get(AuthProvider.Google, channelId);\nif (!token) throw new Error(\"No auth token available\");\nconst client = new ApiClient({ accessToken: token.token });\n```\n\nFor per-user write-backs (e.g., RSVP, comments attributed to the acting user):\n\n```typescript\nawait this.tools.integrations.actAs(\n  AuthProvider.Google,\n  actorId,       // The user who performed the action\n  threadId,      // Thread to prompt for auth if needed\n  this.performWriteBack,\n  ...extraArgs\n);\n```\n\n## Sync Pattern\n\n### Upsert via Source/Key (Strategy 2)\n\nUse source/key for automatic upserts:\n\n```typescript\nasync handleEvent(event: ExternalEvent): Promise<void> {\n  const thread: NewThreadWithNotes = {\n    source: event.htmlLink,  // Canonical URL for automatic deduplication\n    type: ThreadType.Event,\n    title: event.summary || \"(No title)\",\n    notes: [],\n  };\n\n  if (event.description) {\n    thread.notes.push({\n      thread: { source: event.htmlLink },\n      key: \"description\",  // This key enables note-level upserts\n      content: event.description,\n    });\n  }\n\n  // Create or update \u2014 Plot handles deduplication automatically\n  await this.tools.plot.createThread(thread);\n}\n```\n\n### Advanced: Generate and Store IDs (Strategy 3)\n\nOnly use this pattern when you need to create multiple Plot threads from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.\n\n```typescript\nasync handleEventAdvanced(\n  incomingThread: NewThreadWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingThread.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingThreadId = await this.get<Uuid>(mappingKey);\n\n  if (existingThreadId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingThread.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        thread: { id: existingThreadId },\n        content: incomingThread.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const threadId = Uuid.Generate();\n  await this.set(mappingKey, threadId);\n\n  // Create new Thread with initial Note (new thread with first message)\n  await this.tools.plot.createThread({\n    ...incomingThread,\n    id: threadId,\n  });\n}\n```\n\n## Resource Selection\n\nResource selection (calendars, projects, channels) is handled automatically in the twist edit modal via the Integrations tool. Users see a list of available resources returned by your tool's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.\n\n```typescript\n// In your tool:\nasync getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {\n  const client = new ApiClient({ accessToken: token.token });\n  const calendars = await client.listCalendars();\n  return calendars.map(c => ({\n    id: c.id,\n    title: c.name,\n    children: c.subCalendars?.map(sc => ({ id: sc.id, title: sc.name })),\n  }));\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.\n\n### Key Principles\n\n1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.\n2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests\n3. **Store state between batches**: Use the Store tool to persist progress\n4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)\n5. **Clean up when done**: Delete stored state after completion\n6. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n    initialSync: true,  // Track whether this is the first sync\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  // runTask creates NEW execution with fresh ~1000 request limit\n  await this.runTask(callback);\n}\n\nasync syncBatch(resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (size to stay under ~1000 request limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results using source/key pattern (automatic upserts, no manual tracking)\n  // If each item makes ~10 requests, keep batch size \u2264 100 items to stay under limit\n  for (const item of result.items) {\n    // Each createThread may make ~5-10 requests depending on notes/links\n    await this.tools.plot.createThread({\n      source: item.url, // Use item's canonical URL for automatic deduplication\n      type: ThreadType.Note,\n      title: item.title,\n      notes: [{\n        activity: { source: item.url },\n        key: \"description\", // Use key for upsertable notes\n        content: item.description,\n      }],\n      ...(state.initialSync ? { unread: false } : {}), // false for initial, omit for incremental\n      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n      initialSync: state.initialSync, // Preserve initialSync flag across batches\n    });\n\n    // Queue next batch - creates NEW execution with fresh request limit\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createThread({\n      type: ThreadType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Thread Sync Best Practices\n\nWhen syncing threads from external systems, follow these patterns for optimal user experience:\n\n### The `initialSync` Flag\n\nAll sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):\n\n| Field | Initial Sync | Incremental Sync | Reason |\n|-------|--------------|------------------|---------|\n| `unread` | `false` | *omit* | Initial: mark read for all. Incremental: auto-mark read for author only |\n| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |\n\n**Example:**\n```typescript\nconst thread: NewThread = {\n  type: ThreadType.Event,\n  source: event.url,\n  title: event.title,\n  ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental\n  ...(initialSync ? { archived: false } : {}),    // unarchive on initial only\n};\n```\n\n**Why this matters:**\n- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports\n- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved\n- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)\n\n### Two-Way Sync: Avoiding Race Conditions\n\nWhen implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Thread/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.\n\n**Solution:** Embed the Plot `Thread.id` / `Note.id` in the external item's metadata when creating it, and update `Thread.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.\n\n```typescript\nasync pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {\n  // Create external item with Plot ID in metadata for webhook correlation\n  const externalComment = await externalApi.createComment(externalItemId, {\n    body: note.content,\n    metadata: { plotNoteId: note.id },\n  });\n\n  // Update Note with external key AFTER creation\n  // A webhook may arrive before this completes \u2014 that's OK (see onWebhook below)\n  await this.tools.plot.updateNote({\n    id: note.id,\n    key: `comment-${externalComment.id}`,\n  });\n}\n\nasync onWebhook(payload: WebhookPayload): Promise<void> {\n  const comment = payload.comment;\n\n  // Use Plot ID from metadata if present (handles race condition),\n  // otherwise fall back to upserting by activity source and key\n  await this.tools.plot.createNote({\n    ...(comment.metadata?.plotNoteId\n      ? { id: comment.metadata.plotNoteId }\n      : { activity: { source: payload.itemUrl } }),\n    key: `comment-${comment.id}`,\n    content: comment.body,\n  });\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created threads** - Other users may change a Thread created by the twist, resulting in a callback. Be sure to check the `changes === null` and/or `thread.author.id !== this.id` to avoid re-processing.\n- **Always create Threads with Notes** - See \"Understanding Threads and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.\n- **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).\n- **Add Notes to existing Threads** - For source/key pattern, reference threads by source. For UUID pattern, look up stored mappings before creating new Threads. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n- **CRITICAL: Maintain callback backward compatibility** - All callbacks (webhooks, tasks, batch operations) automatically upgrade to new twist versions. You **must** maintain backward compatibility in callback method signatures. Only add optional parameters at the end, never remove or reorder parameters. For breaking changes, implement migration logic in the `upgrade()` lifecycle method to recreate affected callbacks.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
 export default _default;
 //# sourceMappingURL=twist-guide-template.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,0yvBAAumvB;AAAtnvB,wBAAunvB"}
+{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,gxwBAAwkwB;AAAvlwB,wBAAwlwB"}

package/dist/llm-docs/twist-guide-template.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: cli/templates/AGENTS.template.md
  */
-export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)\n- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)\n- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit\n- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count\n- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Threads and Notes\n\n**CRITICAL CONCEPT**: A **Thread** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that thread.\n\n**Think of a Thread as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message\n3. **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.\n4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)\n5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`\n\n### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)\n\n```\nNew event/task/conversation from external system?\n  ├─ Has stable URL or ID?\n  │   └─ Yes → Set Thread.source to the canonical URL/ID\n  │             Create Thread (Plot handles deduplication automatically)\n  │             Use Note.key for different note types:\n  │               - \"description\" for main content\n  │               - \"metadata\" for status/priority/assignee\n  │               - \"comment-{id}\" for individual comments\n  │\n  └─ No stable identifier OR need multiple Plot threads per external item?\n      └─ Use Advanced Pattern (Strategy 3: Generate and Store IDs)\n          See SYNC_STRATEGIES.md for details\n```\n\n### Advanced Decision Tree (Strategy 3: Generate and Store IDs)\n\nOnly use when source/key upserts aren't sufficient (e.g., creating multiple threads from one external item):\n\n```\nNew event/task/conversation?\n  ├─ Yes → Generate UUID with Uuid.Generate()\n  │         Create new Thread with that UUID\n  │         Store mapping: external_id → thread_uuid\n  │\n  └─ No (update/reply/comment) → Look up mapping by external_id\n      ├─ Found → Add Note to existing Thread using stored UUID\n      └─ Not found → Create new Thread with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Thread,\n  type NewThreadWithNotes,\n  type ThreadFilter,\n  type Priority,\n  type ToolBuilder,\n  Twist,\n  ThreadType,\n} from \"@plotday/twister\";\nimport { ThreadAccess, Plot } from \"@plotday/twister/tools/plot\";\n// Import your sources or tools as needed\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot, {\n        thread: { access: ThreadAccess.Create },\n      }),\n    };\n  }\n\n  async activate(_priority: Pick<Priority, \"id\">) {\n    // Auth and resource selection handled in the twist edit modal.\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Auth and resource selection are handled automatically via the twist edit modal when using external tools with Integrations.\n\nMost twists have an empty or minimal `activate()`:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Auth and resource selection are handled in the twist edit modal.\n  // Only add custom initialization here if needed.\n}\n```\n\n**Store Parent Thread for Later (optional):**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const threadId = await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Setup complete\",\n    notes: [{\n      content: \"Your twist is ready. Threads will appear as they sync.\",\n    }],\n  });\n  await this.set(\"setup_thread_id\", threadId);\n}\n```\n\n### Event Callbacks (via build options)\n\nTwists respond to events through callbacks declared in `build()`:\n\n**React to thread changes (for two-way sync):**\n\n```typescript\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\nasync onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {\n  const tool = this.getToolForThread(thread);\n  if (tool?.updateIssue) await tool.updateIssue(thread);\n}\n\nasync onNoteCreated(note: Note): Promise<void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment\n}\n```\n\n**Respond to mentions (AI twist pattern):**\n\n```typescript\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    intents: [{\n      description: \"Respond to general questions\",\n      examples: [\"What's the weather?\", \"Help me plan my week\"],\n      handler: this.respond,\n    }],\n  },\n}),\n```\n\n**Default mention on replies:**\n\nWhen your twist processes replies (two-way comment sync or conversational AI), set `defaultMention: true` so the user doesn't have to manually re-mention your twist on every note:\n\n- `thread.defaultMention` — Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` — Auto-mention on follow-up notes in threads where your twist was @-mentioned (e.g., conversational agents)\n\n```typescript\n// Connector with two-way comment sync\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    defaultMention: true,  // Users replying to synced threads will mention this twist by default\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\n// Conversational AI twist\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    defaultMention: true,  // Follow-up notes auto-mention this twist\n    intents: [{ description: \"...\", examples: [...], handler: this.respond }],\n  },\n}),\n```\n\nWithout `defaultMention`, the twist chip appears toggled OFF by default — the user can still enable it manually per-note.\n\n## Actions\n\nActions enable user interaction:\n\n```typescript\nimport { type Action, ActionType } from \"@plotday/twister\";\n\n// External URL action\nconst urlAction: Action = {\n  title: \"Open website\",\n  type: ActionType.external,\n  url: \"https://example.com\",\n};\n\n// Callback action (uses Callbacks tool — use linkCallback, not callback)\nconst token = await this.linkCallback(this.onActionClicked, \"context\");\nconst callbackAction: Action = {\n  title: \"Click me\",\n  type: ActionType.callback,\n  callback: token,\n};\n\n// Add to thread note\nawait this.tools.plot.createThread({\n  type: ThreadType.Note,\n  title: \"Task with actions\",\n  notes: [\n    {\n      content: \"Click the actions below to take action.\",\n      actions: [urlAction, callbackAction],\n    },\n  ],\n});\n\n// Callback handler receives the Action as first argument\nasync onActionClicked(action: Action, context: string): Promise<void> {\n  // Handle action click\n}\n```\n\n## Authentication Pattern\n\nAuth is handled automatically via the Integrations tool. Tools declare their OAuth provider in `build()`, and users connect in the twist edit modal. **You do not need to create auth activities manually.**\n\n```typescript\n// In your tool's build() method:\nbuild(build: ToolBuilder) {\n  return {\n    integrations: build(Integrations, {\n      providers: [{\n        provider: AuthProvider.Google,\n        scopes: [\"https://www.googleapis.com/auth/calendar\"],\n        getChannels: this.getChannels,          // List available resources after auth\n        onChannelEnabled: this.onChannelEnabled, // User enabled a resource\n        onChannelDisabled: this.onChannelDisabled, // User disabled a resource\n      }],\n    }),\n    // ...\n  };\n}\n\n// Get a token for API calls:\nconst token = await this.tools.integrations.get(AuthProvider.Google, channelId);\nif (!token) throw new Error(\"No auth token available\");\nconst client = new ApiClient({ accessToken: token.token });\n```\n\nFor per-user write-backs (e.g., RSVP, comments attributed to the acting user):\n\n```typescript\nawait this.tools.integrations.actAs(\n  AuthProvider.Google,\n  actorId,       // The user who performed the action\n  threadId,      // Thread to prompt for auth if needed\n  this.performWriteBack,\n  ...extraArgs\n);\n```\n\n## Sync Pattern\n\n### Upsert via Source/Key (Strategy 2)\n\nUse source/key for automatic upserts:\n\n```typescript\nasync handleEvent(event: ExternalEvent): Promise<void> {\n  const thread: NewThreadWithNotes = {\n    source: event.htmlLink,  // Canonical URL for automatic deduplication\n    type: ThreadType.Event,\n    title: event.summary || \"(No title)\",\n    notes: [],\n  };\n\n  if (event.description) {\n    thread.notes.push({\n      thread: { source: event.htmlLink },\n      key: \"description\",  // This key enables note-level upserts\n      content: event.description,\n    });\n  }\n\n  // Create or update — Plot handles deduplication automatically\n  await this.tools.plot.createThread(thread);\n}\n```\n\n### Advanced: Generate and Store IDs (Strategy 3)\n\nOnly use this pattern when you need to create multiple Plot threads from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.\n\n```typescript\nasync handleEventAdvanced(\n  incomingThread: NewThreadWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingThread.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingThreadId = await this.get<Uuid>(mappingKey);\n\n  if (existingThreadId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingThread.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        thread: { id: existingThreadId },\n        content: incomingThread.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const threadId = Uuid.Generate();\n  await this.set(mappingKey, threadId);\n\n  // Create new Thread with initial Note (new thread with first message)\n  await this.tools.plot.createThread({\n    ...incomingThread,\n    id: threadId,\n  });\n}\n```\n\n## Resource Selection\n\nResource selection (calendars, projects, channels) is handled automatically in the twist edit modal via the Integrations tool. Users see a list of available resources returned by your tool's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.\n\n```typescript\n// In your tool:\nasync getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {\n  const client = new ApiClient({ accessToken: token.token });\n  const calendars = await client.listCalendars();\n  return calendars.map(c => ({\n    id: c.id,\n    title: c.name,\n    children: c.subCalendars?.map(sc => ({ id: sc.id, title: sc.name })),\n  }));\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.\n\n### Key Principles\n\n1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.\n2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests\n3. **Store state between batches**: Use the Store tool to persist progress\n4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)\n5. **Clean up when done**: Delete stored state after completion\n6. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n    initialSync: true,  // Track whether this is the first sync\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  // runTask creates NEW execution with fresh ~1000 request limit\n  await this.runTask(callback);\n}\n\nasync syncBatch(resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (size to stay under ~1000 request limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results using source/key pattern (automatic upserts, no manual tracking)\n  // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit\n  for (const item of result.items) {\n    // Each createThread may make ~5-10 requests depending on notes/links\n    await this.tools.plot.createThread({\n      source: item.url, // Use item's canonical URL for automatic deduplication\n      type: ThreadType.Note,\n      title: item.title,\n      notes: [{\n        activity: { source: item.url },\n        key: \"description\", // Use key for upsertable notes\n        content: item.description,\n      }],\n      ...(state.initialSync ? { unread: false } : {}), // false for initial, omit for incremental\n      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n      initialSync: state.initialSync, // Preserve initialSync flag across batches\n    });\n\n    // Queue next batch - creates NEW execution with fresh request limit\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createThread({\n      type: ThreadType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Thread Sync Best Practices\n\nWhen syncing threads from external systems, follow these patterns for optimal user experience:\n\n### The `initialSync` Flag\n\nAll sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):\n\n| Field | Initial Sync | Incremental Sync | Reason |\n|-------|--------------|------------------|---------|\n| `unread` | `false` | *omit* | Initial: mark read for all. Incremental: auto-mark read for author only |\n| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |\n\n**Example:**\n```typescript\nconst thread: NewThread = {\n  type: ThreadType.Event,\n  source: event.url,\n  title: event.title,\n  ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental\n  ...(initialSync ? { archived: false } : {}),    // unarchive on initial only\n};\n```\n\n**Why this matters:**\n- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports\n- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved\n- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)\n\n### Two-Way Sync: Avoiding Race Conditions\n\nWhen implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Thread/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.\n\n**Solution:** Embed the Plot `Thread.id` / `Note.id` in the external item's metadata when creating it, and update `Thread.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.\n\n```typescript\nasync pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {\n  // Create external item with Plot ID in metadata for webhook correlation\n  const externalComment = await externalApi.createComment(externalItemId, {\n    body: note.content,\n    metadata: { plotNoteId: note.id },\n  });\n\n  // Update Note with external key AFTER creation\n  // A webhook may arrive before this completes — that's OK (see onWebhook below)\n  await this.tools.plot.updateNote({\n    id: note.id,\n    key: `comment-${externalComment.id}`,\n  });\n}\n\nasync onWebhook(payload: WebhookPayload): Promise<void> {\n  const comment = payload.comment;\n\n  // Use Plot ID from metadata if present (handles race condition),\n  // otherwise fall back to upserting by activity source and key\n  await this.tools.plot.createNote({\n    ...(comment.metadata?.plotNoteId\n      ? { id: comment.metadata.plotNoteId }\n      : { activity: { source: payload.itemUrl } }),\n    key: `comment-${comment.id}`,\n    content: comment.body,\n  });\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created threads** - Other users may change a Thread created by the twist, resulting in a callback. Be sure to check the `changes === null` and/or `thread.author.id !== this.id` to avoid re-processing.\n- **Always create Threads with Notes** - See \"Understanding Threads and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.\n- **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).\n- **Add Notes to existing Threads** - For source/key pattern, reference threads by source. For UUID pattern, look up stored mappings before creating new Threads. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n- **CRITICAL: Maintain callback backward compatibility** - All callbacks (webhooks, tasks, batch operations) automatically upgrade to new twist versions. You **must** maintain backward compatibility in callback method signatures. Only add optional parameters at the end, never remove or reorder parameters. For breaking changes, implement migration logic in the `upgrade()` lifecycle method to recreate affected callbacks.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
+export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited requests per execution**: Each execution has ~1000 requests (HTTP requests, tool calls, database operations)\n- **Limited CPU time**: Each execution has limited CPU time (typically ~60 seconds) and memory (128MB)\n- **Use tasks to get fresh request limits**: `this.runTask()` creates a NEW execution with a fresh ~1000 request limit\n- **Calling callbacks continues same execution**: `this.run()` continues the same execution and shares the request count\n- **Break long loops**: Split large operations into batches that each stay under the ~1000 request limit\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Threads and Notes\n\n**CRITICAL CONCEPT**: A **Thread** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that thread.\n\n**Think of a Thread as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Threads with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Threads for updates** - Don't create a new Thread for each related message\n3. **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.\n4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot threads per external item (see SYNC_STRATEGIES.md)\n5. **Most Threads should be `ThreadType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`\n\n### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)\n\n```\nNew event/task/conversation from external system?\n  ├─ Has stable URL or ID?\n  │   └─ Yes → Set Thread.source to the canonical URL/ID\n  │             Create Thread (Plot handles deduplication automatically)\n  │             Use Note.key for different note types:\n  │               - \"description\" for main content\n  │               - \"metadata\" for status/priority/assignee\n  │               - \"comment-{id}\" for individual comments\n  │\n  └─ No stable identifier OR need multiple Plot threads per external item?\n      └─ Use Advanced Pattern (Strategy 3: Generate and Store IDs)\n          See SYNC_STRATEGIES.md for details\n```\n\n### Advanced Decision Tree (Strategy 3: Generate and Store IDs)\n\nOnly use when source/key upserts aren't sufficient (e.g., creating multiple threads from one external item):\n\n```\nNew event/task/conversation?\n  ├─ Yes → Generate UUID with Uuid.Generate()\n  │         Create new Thread with that UUID\n  │         Store mapping: external_id → thread_uuid\n  │\n  └─ No (update/reply/comment) → Look up mapping by external_id\n      ├─ Found → Add Note to existing Thread using stored UUID\n      └─ Not found → Create new Thread with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Thread,\n  type NewThreadWithNotes,\n  type ThreadFilter,\n  type Priority,\n  type ToolBuilder,\n  Twist,\n  ThreadType,\n} from \"@plotday/twister\";\nimport { ThreadAccess, Plot } from \"@plotday/twister/tools/plot\";\n// Import your sources or tools as needed\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot, {\n        thread: { access: ThreadAccess.Create },\n      }),\n    };\n  }\n\n  async activate(_priority: Pick<Priority, \"id\">) {\n    // Auth and resource selection handled in the twist edit modal.\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Auth and resource selection are handled automatically via the twist edit modal when using external tools with Integrations.\n\nMost twists have an empty or minimal `activate()`:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Auth and resource selection are handled in the twist edit modal.\n  // Only add custom initialization here if needed.\n}\n```\n\n**Store Parent Thread for Later (optional):**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const threadId = await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Setup complete\",\n    notes: [{\n      content: \"Your twist is ready. Threads will appear as they sync.\",\n    }],\n  });\n  await this.set(\"setup_thread_id\", threadId);\n}\n```\n\n### Event Callbacks (via build options)\n\nTwists respond to events through callbacks declared in `build()`:\n\n**React to thread changes (for two-way sync):**\n\n```typescript\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\nasync onThreadUpdated(thread: Thread, changes: { tagsAdded, tagsRemoved }): Promise<void> {\n  const tool = this.getToolForThread(thread);\n  if (tool?.updateIssue) await tool.updateIssue(thread);\n}\n\nasync onNoteCreated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n  if (note.author.type === ActorType.Twist) return; // Prevent loops\n  // Sync note to external service as a comment. Return the external\n  // system's id + stored content so the runtime can set note.key AND\n  // record a sync baseline that preserves Plot's content on round-trip.\n  // See connectors/AGENTS.md → \"Sync baseline preservation\".\n  const comment = await externalApi.createComment(thread.meta.externalId, { body: note.content ?? \"\" });\n  if (!comment?.id) return;\n  return { key: `comment-${comment.id}`, externalContent: comment.body };\n}\n```\n\n**Respond to mentions (AI twist pattern):**\n\n```typescript\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    intents: [{\n      description: \"Respond to general questions\",\n      examples: [\"What's the weather?\", \"Help me plan my week\"],\n      handler: this.respond,\n    }],\n  },\n}),\n```\n\n**Default mention on replies:**\n\nWhen your twist processes replies (two-way comment sync or conversational AI), set `defaultMention: true` so the user doesn't have to manually re-mention your twist on every note:\n\n- `thread.defaultMention` — Auto-mention on replies to threads your twist created (e.g., synced issues, emails)\n- `note.defaultMention` — Auto-mention on follow-up notes in threads where your twist was @-mentioned (e.g., conversational agents)\n\n```typescript\n// Connector with two-way comment sync\nplot: build(Plot, {\n  thread: {\n    access: ThreadAccess.Create,\n    defaultMention: true,  // Users replying to synced threads will mention this twist by default\n    updated: this.onThreadUpdated,\n  },\n  note: {\n    created: this.onNoteCreated,\n  },\n}),\n\n// Conversational AI twist\nplot: build(Plot, {\n  thread: { access: ThreadAccess.Respond },\n  note: {\n    defaultMention: true,  // Follow-up notes auto-mention this twist\n    intents: [{ description: \"...\", examples: [...], handler: this.respond }],\n  },\n}),\n```\n\nWithout `defaultMention`, the twist chip appears toggled OFF by default — the user can still enable it manually per-note.\n\n## Actions\n\nActions enable user interaction:\n\n```typescript\nimport { type Action, ActionType } from \"@plotday/twister\";\n\n// External URL action\nconst urlAction: Action = {\n  title: \"Open website\",\n  type: ActionType.external,\n  url: \"https://example.com\",\n};\n\n// Callback action (uses Callbacks tool — use linkCallback, not callback)\nconst token = await this.linkCallback(this.onActionClicked, \"context\");\nconst callbackAction: Action = {\n  title: \"Click me\",\n  type: ActionType.callback,\n  callback: token,\n};\n\n// Add to thread note\nawait this.tools.plot.createThread({\n  type: ThreadType.Note,\n  title: \"Task with actions\",\n  notes: [\n    {\n      content: \"Click the actions below to take action.\",\n      actions: [urlAction, callbackAction],\n    },\n  ],\n});\n\n// Callback handler receives the Action as first argument\nasync onActionClicked(action: Action, context: string): Promise<void> {\n  // Handle action click\n}\n```\n\n## Authentication Pattern\n\nAuth is handled automatically via the Integrations tool. Tools declare their OAuth provider in `build()`, and users connect in the twist edit modal. **You do not need to create auth activities manually.**\n\n```typescript\n// In your tool's build() method:\nbuild(build: ToolBuilder) {\n  return {\n    integrations: build(Integrations, {\n      providers: [{\n        provider: AuthProvider.Google,\n        scopes: [\"https://www.googleapis.com/auth/calendar\"],\n        getChannels: this.getChannels,          // List available resources after auth\n        onChannelEnabled: this.onChannelEnabled, // User enabled a resource\n        onChannelDisabled: this.onChannelDisabled, // User disabled a resource\n      }],\n    }),\n    // ...\n  };\n}\n\n// Get a token for API calls:\nconst token = await this.tools.integrations.get(AuthProvider.Google, channelId);\nif (!token) throw new Error(\"No auth token available\");\nconst client = new ApiClient({ accessToken: token.token });\n```\n\nFor per-user write-backs (e.g., RSVP, comments attributed to the acting user):\n\n```typescript\nawait this.tools.integrations.actAs(\n  AuthProvider.Google,\n  actorId,       // The user who performed the action\n  threadId,      // Thread to prompt for auth if needed\n  this.performWriteBack,\n  ...extraArgs\n);\n```\n\n## Sync Pattern\n\n### Upsert via Source/Key (Strategy 2)\n\nUse source/key for automatic upserts:\n\n```typescript\nasync handleEvent(event: ExternalEvent): Promise<void> {\n  const thread: NewThreadWithNotes = {\n    source: event.htmlLink,  // Canonical URL for automatic deduplication\n    type: ThreadType.Event,\n    title: event.summary || \"(No title)\",\n    notes: [],\n  };\n\n  if (event.description) {\n    thread.notes.push({\n      thread: { source: event.htmlLink },\n      key: \"description\",  // This key enables note-level upserts\n      content: event.description,\n    });\n  }\n\n  // Create or update — Plot handles deduplication automatically\n  await this.tools.plot.createThread(thread);\n}\n```\n\n### Advanced: Generate and Store IDs (Strategy 3)\n\nOnly use this pattern when you need to create multiple Plot threads from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.\n\n```typescript\nasync handleEventAdvanced(\n  incomingThread: NewThreadWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingThread.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingThreadId = await this.get<Uuid>(mappingKey);\n\n  if (existingThreadId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingThread.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        thread: { id: existingThreadId },\n        content: incomingThread.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const threadId = Uuid.Generate();\n  await this.set(mappingKey, threadId);\n\n  // Create new Thread with initial Note (new thread with first message)\n  await this.tools.plot.createThread({\n    ...incomingThread,\n    id: threadId,\n  });\n}\n```\n\n## Resource Selection\n\nResource selection (calendars, projects, channels) is handled automatically in the twist edit modal via the Integrations tool. Users see a list of available resources returned by your tool's `getChannels()` method and toggle them on/off. You do **not** need to build custom selection UI.\n\n```typescript\n// In your tool:\nasync getChannels(_auth: Authorization, token: AuthToken): Promise<Channel[]> {\n  const client = new ApiClient({ accessToken: token.token });\n  const calendars = await client.listCalendars();\n  return calendars.map(c => ({\n    id: c.id,\n    title: c.name,\n    children: c.subCalendars?.map(sc => ({ id: sc.id, title: sc.name })),\n  }));\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited requests per execution (~1000 requests), you must break long operations into batches. Each batch runs independently in a new execution context with its own fresh request limit.\n\n### Key Principles\n\n1. **Stay under request limits**: Each execution has ~1000 requests. Size batches accordingly.\n2. **Use runTask() for fresh limits**: Each call to `this.runTask()` creates a NEW execution with fresh ~1000 requests\n3. **Store state between batches**: Use the Store tool to persist progress\n4. **Calculate safe batch sizes**: Determine requests per item to size batches (e.g., ~10 requests per item = ~100 items per batch)\n5. **Clean up when done**: Delete stored state after completion\n6. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n    initialSync: true,  // Track whether this is the first sync\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  // runTask creates NEW execution with fresh ~1000 request limit\n  await this.runTask(callback);\n}\n\nasync syncBatch(resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (size to stay under ~1000 request limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results using source/key pattern (automatic upserts, no manual tracking)\n  // If each item makes ~10 requests, keep batch size ≤ 100 items to stay under limit\n  for (const item of result.items) {\n    // Each createThread may make ~5-10 requests depending on notes/links\n    await this.tools.plot.createThread({\n      source: item.url, // Use item's canonical URL for automatic deduplication\n      type: ThreadType.Note,\n      title: item.title,\n      notes: [{\n        activity: { source: item.url },\n        key: \"description\", // Use key for upsertable notes\n        content: item.description,\n      }],\n      ...(state.initialSync ? { unread: false } : {}), // false for initial, omit for incremental\n      ...(state.initialSync ? { archived: false } : {}), // unarchive on initial only\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n      initialSync: state.initialSync, // Preserve initialSync flag across batches\n    });\n\n    // Queue next batch - creates NEW execution with fresh request limit\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createThread({\n      type: ThreadType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Thread Sync Best Practices\n\nWhen syncing threads from external systems, follow these patterns for optimal user experience:\n\n### The `initialSync` Flag\n\nAll sync-based tools should distinguish between initial sync (first import) and incremental sync (ongoing updates):\n\n| Field | Initial Sync | Incremental Sync | Reason |\n|-------|--------------|------------------|---------|\n| `unread` | `false` | *omit* | Initial: mark read for all. Incremental: auto-mark read for author only |\n| `archived` | `false` | *omit* | Unarchive on install, preserve user choice on updates |\n\n**Example:**\n```typescript\nconst thread: NewThread = {\n  type: ThreadType.Event,\n  source: event.url,\n  title: event.title,\n  ...(initialSync ? { unread: false } : {}),     // false for initial, omit for incremental\n  ...(initialSync ? { archived: false } : {}),    // unarchive on initial only\n};\n```\n\n**Why this matters:**\n- **Initial sync**: Activities are unarchived and marked as read for all users, preventing spam from bulk historical imports\n- **Incremental sync**: Activities are auto-marked read for the author (twist owner), unread for everyone else. Archived state is preserved\n- **Reinstall**: Acts as initial sync, so previously archived activities are unarchived (fresh start)\n\n### Two-Way Sync: Avoiding Race Conditions\n\nWhen implementing two-way sync where items created in Plot are pushed to an external system (e.g. Notes becoming comments), a race condition can occur: the external system may send a webhook for the newly created item before you've updated the Thread/Note with the external key. The webhook handler won't find the item by external key and may create a duplicate.\n\n**Solution:** Embed the Plot `Thread.id` / `Note.id` in the external item's metadata when creating it, and update `Thread.source` / `Note.key` after creation. When processing webhooks, check for the Plot ID in metadata first.\n\n```typescript\nasync pushNoteAsComment(note: Note, externalItemId: string): Promise<void> {\n  // Create external item with Plot ID in metadata for webhook correlation\n  const externalComment = await externalApi.createComment(externalItemId, {\n    body: note.content,\n    metadata: { plotNoteId: note.id },\n  });\n\n  // Update Note with external key AFTER creation\n  // A webhook may arrive before this completes — that's OK (see onWebhook below)\n  await this.tools.plot.updateNote({\n    id: note.id,\n    key: `comment-${externalComment.id}`,\n  });\n}\n\nasync onWebhook(payload: WebhookPayload): Promise<void> {\n  const comment = payload.comment;\n\n  // Use Plot ID from metadata if present (handles race condition),\n  // otherwise fall back to upserting by activity source and key\n  await this.tools.plot.createNote({\n    ...(comment.metadata?.plotNoteId\n      ? { id: comment.metadata.plotNoteId }\n      : { activity: { source: payload.itemUrl } }),\n    key: `comment-${comment.id}`,\n    content: comment.body,\n  });\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createThread({\n    type: ThreadType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created threads** - Other users may change a Thread created by the twist, resulting in a callback. Be sure to check the `changes === null` and/or `thread.author.id !== this.id` to avoid re-processing.\n- **Always create Threads with Notes** - See \"Understanding Threads and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Thread types** - Most should be `ThreadType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.\n- **Use Thread.source and Note.key for automatic upserts (Recommended)** - Set Thread.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).\n- **Add Notes to existing Threads** - For source/key pattern, reference threads by source. For UUID pattern, look up stored mappings before creating new Threads. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget request limits** - Each execution has ~1000 requests (HTTP requests, tool calls). Break long loops into batches with `this.runTask()` to get fresh request limits. Calculate requests per item to determine safe batch size (e.g., if each item needs ~10 requests, batch size = ~100 items).\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n- **CRITICAL: Maintain callback backward compatibility** - All callbacks (webhooks, tasks, batch operations) automatically upgrade to new twist versions. You **must** maintain backward compatibility in callback method signatures. Only add optional parameters at the end, never remove or reorder parameters. For breaking changes, implement migration logic in the `upgrade()` lifecycle method to recreate affected callbacks.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
 //# sourceMappingURL=twist-guide-template.js.map

package/dist/llm-docs/twist-guide-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,umvBAAumvB,CAAC"}
+{"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,wkwBAAwkwB,CAAC"}