@plotday/twister 0.61.0 → 0.62.0

package/dist/twist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../src/twist.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"twist.d.ts","sourceRoot":"","sources":["../src/twist.ts"],"names":[],"mappings":"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"}

package/dist/twist.js

@@ -246,6 +246,21 @@ export class Twist {
     async cancelScheduledTask(key) {
         return this.tools.tasks.cancelScheduledTask(key);
     }
+    /**
+     * Schedules a durable recurring task under a stable key. The platform
+     * re-arms the task every `intervalMs` automatically — the callback does NOT
+     * need to reschedule itself. Re-scheduling under the same key atomically
+     * replaces the pending occurrence (at most one live task per key). Tear down
+     * with {@link cancelScheduledTask}. See {@link Tasks.scheduleRecurring}.
+     *
+     * @param key - Stable identifier, e.g. `"mailbox-self-heal"`
+     * @param callback - Callback token created with `this.callback()`
+     * @param options.intervalMs - Safety-ceiling cadence in milliseconds
+     * @param options.firstRunAt - Optional precise time for the next fire
+     */
+    async scheduleRecurring(key, callback, options) {
+        return this.tools.tasks.scheduleRecurring(key, callback, options);
+    }
     /**
      * Called when the twist is installed by a user.
      *

package/dist/twist.js.map

@@ -1 +1 @@
-{"version":3,"file":"twist.js","sourceRoot":"","sources":["../src/twist.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"twist.js","sourceRoot":"","sources":["../src/twist.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plotday/twister",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Plot Twist Creator - Build intelligent extensions that integrate and automate",
   "type": "module",
   "main": "./dist/index.js",

package/src/connector.ts

@@ -397,6 +397,21 @@ export abstract class Connector<TSelf> extends Twist<TSelf> {
    */
   readonly reactionCapabilities?: ReactionCapabilities;
 
+  /**
+   * When true, this connector's effective link types are computed dynamically
+   * from its enabled channels' per-channel link types (each channel carries the
+   * link types for whatever product/resource it represents), rather than the
+   * static union of all declared providers' link types. Lets one connection
+   * surface different link types depending on what the user has enabled — e.g.
+   * a combined Google connection shows calendar/event link types (and thus the
+   * agenda) only when a calendar channel is enabled.
+   *
+   * Defaults to false (static link types — the behavior for every connector
+   * that doesn't set this). Requires the connector to attach per-channel
+   * `linkTypes` on the channels returned by `getChannels`.
+   */
+  readonly dynamicLinkTypes?: boolean;
+
   /**
    * When true, this connector is mentioned by default on replies to threads it created.
    * When false (default), this connector cannot be mentioned at all.

package/src/llm-docs/connector.ts

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import { type Actor, type ActorId, type Contact, type DeliveryError, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } 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 * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n *   indicates whether the platform additionally supports workspace\n *   custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n *   `subset` lists the allowed emoji (omit for \"currently full Unicode\n *   per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n *   Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n  | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n  | { mode: \"unicode-subset\"; subset?: readonly string[] }\n  | { mode: \"fixed\"; allowed: readonly string[] };\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   * Reports that the outbound send / write-back for this note FAILED and\n   * could not be recovered (after the connector's own retries). The runtime\n   * records it on the note — surfacing a \"Failed to send\" affordance (Retry /\n   * Discard) to the user — and marks the thread unread.\n   *\n   * - object → record the failure.\n   * - `null` → clear a previously-recorded failure (e.g. a successful retry).\n   * - omitted (`undefined`) → leave any existing delivery state untouched.\n   *\n   * A successful write-back (any result without a `deliveryError`) also clears\n   * a previously-recorded failure, so connectors usually only need to SET this\n   * on failure.\n   *\n   * Prefer RETURNING this over throwing for expected, user-visible failures\n   * (rejected recipient, message too large, quota exhausted): a thrown error\n   * pages error tracking, whereas a returned `deliveryError` does not. Reserve\n   * throwing for genuinely unexpected errors. Connectors that simply throw on a\n   * failed write-back still get a generic \"Failed to send\" surfaced by the\n   * runtime, just without a specific reason.\n   */\n  deliveryError?: DeliveryError | null;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n  /** Plot contact UUID */\n  id: Uuid;\n  /** Display name, or null if not set */\n  name: string | null;\n  /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U…`, LinkedIn URN, Gmail email address) */\n  externalAccountId: string;\n  /**\n   * The contact's role on the originating thread, resolved from\n   * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n   * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n   * explicit role entry — connectors should treat `null` as the link\n   * type's default role (the `contactRoles` entry marked `default: true`).\n   *\n   * Connectors that distinguish roles MUST honor this when addressing the\n   * recipient — e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n   * Cc/Bcc headers, never the To header, so BCC recipients are not\n   * exposed to the other recipients. Connectors that don't distinguish\n   * roles (Slack, Linear) can ignore it.\n   */\n  role: string | null;\n};\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  /**\n   * Status the user selected. Matches a `statuses[].status` for `type`,\n   * or null for status-less link types (the parent linkType declares no\n   * `statuses` and no `compose.status`).\n   */\n  status: string | null;\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   * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n   * re-resolving contacts yourself: the runtime pre-resolves each contact\n   * to its platform account ID (`externalAccountId`) and populates\n   * `recipients` before `onCreateLink` is called.\n   */\n  contacts: Actor[];\n  /**\n   * Pre-resolved recipients for link types whose `compose.targets` is\n   * `\"contacts\"` or `\"addresses\"`.\n   *\n   * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n   * contact UUID, the platform-specific account ID\n   * (`externalAccountId`) the connector should use to address the\n   * recipient without performing its own lookup, and the contact's\n   * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n   * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n   * a connection-scoped row fall back to `contact.email`.\n   */\n  recipients?: ResolvedRecipient[];\n  /**\n   * Free-form addresses the user typed into the picker (no Plot contact\n   * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n   * undefined. Connectors should append these alongside `recipients`\n   * when constructing the recipient list (e.g. `To:` header for Gmail).\n   */\n  inviteEmails?: string[];\n};\n\n/** An optional OAuth scope group the user can toggle at connect time. */\nexport type OptionalScopeGroup = {\n  /** Stable id used to track the user's selection. */\n  id: string;\n  /** Value-forward switch label, e.g. \"Add names to events using contacts\". */\n  label: string;\n  /** Optional secondary line shown under the label. */\n  description?: string;\n  /** The OAuth scope strings this group grants. */\n  scopes: string[];\n  /** Whether the group is requested by default (switch on). */\n  default: boolean;\n};\n\n/**\n * Structured scope declaration. `required` scopes must be granted — auth fails\n * and re-prompts if any is declined. `optional` groups are requested by default\n * but auth still succeeds if the user declines them; the connector should detect\n * the absence via the granted `token.scopes` and degrade gracefully.\n */\nexport type ScopeConfig = {\n  required: string[];\n  optional?: OptionalScopeGroup[];\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\", icon: \"todo\" },\n *       { status: \"done\", label: \"Done\", icon: \"done\", done: true },\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 — a flat list (all required), or\n   *  a {@link ScopeConfig} declaring required + optional scope groups. */\n  readonly scopes?: string[] | ScopeConfig;\n\n  /**\n   * Plain-language bullets describing what access connecting this service\n   * grants the user — shown on the connect screen regardless of auth mechanism\n   * (OAuth, API key, or hosted). For OAuth connectors it also previews what the\n   * provider's consent screen will request. These are justifications for what\n   * Plot accesses, not a one-to-one mapping of scope strings.\n   */\n  readonly access?: 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   * The user-facing noun for this connector's channels — what each\n   * {@link Channel} returned by {@link getChannels} actually represents in the\n   * external service. Many connectors map \"channels\" onto a domain concept\n   * (folders, projects, calendars, labels, spaces, repositories, …), so the\n   * generic word \"channel\" reads as jargon. Set this and the UI substitutes it\n   * everywhere it would otherwise say \"channel(s)\" — e.g. the per-connection\n   * toggle becomes \"Sync new folders\" / \"When a new folder is added, …\".\n   *\n   * Provide lowercase nouns (the UI capitalizes where needed):\n   * `{ singular: \"folder\", plural: \"folders\" }`. Defaults to\n   * `{ singular: \"channel\", plural: \"channels\" }` when omitted.\n   */\n  readonly channelNoun?: { singular: string; plural: string };\n\n  /**\n   * Whether the per-connection \"Sync new channels\" preference starts ON for\n   * newly added connections of this connector. Defaults to `false` (opt-in).\n   *\n   * Set `true` for connectors that select **all** of their channels by default\n   * (i.e. {@link getChannels} returns no channels marked\n   * `enabledByDefault: false`). If syncing every channel is the intended\n   * default, then channels discovered later should also sync automatically.\n   * Leave `false`/omitted for selective connectors that exclude some channels\n   * by default (e.g. Gmail syncs only Inbox/Sent, Google Calendar only\n   * owner calendars) — for those, a newly discovered channel is just as\n   * uncertain and should wait for the user to opt in.\n   *\n   * Only affects the **default** for new connections; the user's explicit\n   * toggle always wins, and existing connections keep their stored preference.\n   */\n  readonly autoEnableNewChannelsByDefault?: boolean;\n\n  /**\n   * Whether this connector supports the platform's sequential auto-threading —\n   * folding a conversation that arrives as a run of separate top-level messages\n   * into a single thread. Set `true` for conversational connectors (chat,\n   * messaging) that mark eligible links with {@link NewLink.autoThread}. The UI\n   * shows a per-connection \"Group related messages into conversations\" toggle\n   * only for connectors that declare this.\n   *\n   * Leave undefined/false for connectors whose items are not conversational\n   * (calendars, issue trackers, file storage) — marking a link does nothing\n   * unless the connection both declares support and the user opted in.\n   */\n  readonly autoThreading?: boolean;\n\n  /**\n   * Whether the per-connection auto-threading preference starts ON for newly\n   * added connections of this connector. Defaults to `false` (opt-in) — the\n   * least-surprise default, since a wrong fold is irreversible. Only meaningful\n   * when {@link autoThreading} is `true`. The user's explicit toggle always\n   * wins, and existing connections keep their stored preference.\n   */\n  readonly autoThreadingByDefault?: 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   * Declares how this connector's platform handles emoji reactions.\n   * Used to filter the reaction picker for notes whose primary connector\n   * is this one, and to guard outbound dispatch from sending emoji the\n   * platform can't accept.\n   *\n   * Leave undefined for connectors whose platform has no concept of\n   * reactions (calendar, file storage, issue trackers without reactions).\n   */\n  readonly reactionCapabilities?: ReactionCapabilities;\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   * The framework dispatches this in three cases:\n   *  1. **Initial enable** — user toggled the channel on for the first time.\n   *  2. **Auto-enable** — `setChannels` discovered a new channel on a\n   *     connection with `auto_enable_new_channels` set.\n   *  3. **Recovery after re-auth** — the user re-authorized a previously-\n   *     broken connection. The framework calls `onChannelEnabled` for every\n   *     channel that was already enabled at the time of re-auth, with\n   *     `context.recovering = true`. See {@link SyncContext.recovering}.\n   *\n   * Implementations should be **idempotent and overwrite stored state**:\n   * the same channel may receive multiple `onChannelEnabled` calls across\n   * its lifetime. Use unconditional `this.set()` writes rather than\n   * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n   * cursors and state from the prior session.\n   *\n   * **Sync state tracking is automatic.** The framework stamps the\n   * connection as \"syncing\" when it dispatches this method and clears\n   * that state when:\n   *  - the connector calls `tools.integrations.channelSyncCompleted(id)`\n   *    once the initial backfill is done, OR\n   *  - this method throws an unhandled exception (auto-cleared so the UI\n   *    doesn't get stuck in \"syncing\" forever).\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, context?: SyncContext): Promise<void> {\n   *   // Recovery: drop stale cursors so the next sync re-walks history.\n   *   if (context?.recovering) {\n   *     await this.clear(`last_sync_token_${channel.id}`);\n   *   }\n   *\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 (plan-based hints, recovery flag)\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\n   * `compose` block on the relevant `LinkTypeConfig` (see\n   * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n   * Add link modal and the thread is synced, the runtime calls this method\n   * 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   * Resolve a `fileRef` action's bytes for download. Called when a user opens\n   * an attachment in Plot. Return either a redirect URL (preferred for sources\n   * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n   * streamed body (required when bytes are only reachable through an\n   * authenticated API call, like Gmail attachments.get).\n   *\n   * @param ref Opaque value the connector previously emitted on a fileRef action.\n   * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n   * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n   *\n   * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n   */\n  async downloadAttachment(\n    ref: string,\n  ): Promise<\n    | { redirectUrl: string }\n    | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n  > {\n    throw new Error(\n      `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n    );\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 changes the **thread-level sharing** of a thread owned\n   * by this connector — adding or removing a contact, or (for connectors with\n   * roles) changing a contact's role. Override on connectors whose external\n   * source can reflect that membership change, e.g. a group DM / multi-party\n   * chat (`LinkTypeConfig.sharingModel: \"thread\"`) or an email's To/Cc/Bcc\n   * recipients (`sharingModel: \"message\"`). Connectors backed by an immutable\n   * roster (most group DMs today) or by channel-level membership\n   * (`sharingModel: \"channel\"`) leave this as the default no-op.\n   *\n   * `role`/`from`/`to` are **null** for connectors without roles (group DMs\n   * have no roles); they carry a `contactRoles` id only for connectors that\n   * declare roles (e.g. email `to`/`cc`/`bcc`).\n   *\n   * The dispatch fires after Plot has persisted the change. A connector may\n   * reflect it actively (e.g. add/remove a participant on the external chat)\n   * or passively on the next outbound note (e.g. building To/Cc/Bcc headers\n   * from the current `thread.contacts` × `thread.contactMeta`) — this callback\n   * is not the right place to send a standalone notification.\n   *\n   * @param thread - The thread whose contacts changed\n   * @param changes - The added/removed contacts and any role transitions on existing contacts\n   */\n  /* eslint-disable @typescript-eslint/no-unused-vars */\n  onContactsChanged(\n    thread: Thread,\n    changes: {\n      added: Array<{ contact: Contact; role: string | null }>;\n      removed: Array<{ contact: Contact; role: string | null }>;\n      changed: Array<{ contact: Contact; from: string | null; to: string | null }>;\n    },\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n  /* eslint-enable @typescript-eslint/no-unused-vars */\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  /**\n   * Called when a user adds or removes a single emoji reaction on a note\n   * (one event per `(note, actor, emoji)` state transition).\n   *\n   * Dispatch is routed to the reacting user's own connector instance via\n   * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n   * already runs under the reactor's auth. Fetch the API client with the\n   * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n   * and the external write — e.g. Slack `reactions.add` — will be attributed\n   * to the correct user. No `actAs` step required.\n   *\n   * If the reacting user has no connection of this type, no dispatch fires\n   * for that reaction (it stays in Plot only).\n   *\n   * Override to sync per-actor reactions back to the external system.\n   *\n   * @param note  - The note that was reacted on (partial; `id`, `key`, `content` populated)\n   * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n   * @param actor - The contact who added/removed the reaction\n   * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n   * @param added - `true` if the reaction is now present, `false` if it was removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): 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 Contact, type DeliveryError, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } 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 * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n *   indicates whether the platform additionally supports workspace\n *   custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n *   `subset` lists the allowed emoji (omit for \"currently full Unicode\n *   per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n *   Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n  | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n  | { mode: \"unicode-subset\"; subset?: readonly string[] }\n  | { mode: \"fixed\"; allowed: readonly string[] };\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   * Reports that the outbound send / write-back for this note FAILED and\n   * could not be recovered (after the connector's own retries). The runtime\n   * records it on the note — surfacing a \"Failed to send\" affordance (Retry /\n   * Discard) to the user — and marks the thread unread.\n   *\n   * - object → record the failure.\n   * - `null` → clear a previously-recorded failure (e.g. a successful retry).\n   * - omitted (`undefined`) → leave any existing delivery state untouched.\n   *\n   * A successful write-back (any result without a `deliveryError`) also clears\n   * a previously-recorded failure, so connectors usually only need to SET this\n   * on failure.\n   *\n   * Prefer RETURNING this over throwing for expected, user-visible failures\n   * (rejected recipient, message too large, quota exhausted): a thrown error\n   * pages error tracking, whereas a returned `deliveryError` does not. Reserve\n   * throwing for genuinely unexpected errors. Connectors that simply throw on a\n   * failed write-back still get a generic \"Failed to send\" surfaced by the\n   * runtime, just without a specific reason.\n   */\n  deliveryError?: DeliveryError | null;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n  /** Plot contact UUID */\n  id: Uuid;\n  /** Display name, or null if not set */\n  name: string | null;\n  /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U…`, LinkedIn URN, Gmail email address) */\n  externalAccountId: string;\n  /**\n   * The contact's role on the originating thread, resolved from\n   * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n   * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n   * explicit role entry — connectors should treat `null` as the link\n   * type's default role (the `contactRoles` entry marked `default: true`).\n   *\n   * Connectors that distinguish roles MUST honor this when addressing the\n   * recipient — e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n   * Cc/Bcc headers, never the To header, so BCC recipients are not\n   * exposed to the other recipients. Connectors that don't distinguish\n   * roles (Slack, Linear) can ignore it.\n   */\n  role: string | null;\n};\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  /**\n   * Status the user selected. Matches a `statuses[].status` for `type`,\n   * or null for status-less link types (the parent linkType declares no\n   * `statuses` and no `compose.status`).\n   */\n  status: string | null;\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   * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n   * re-resolving contacts yourself: the runtime pre-resolves each contact\n   * to its platform account ID (`externalAccountId`) and populates\n   * `recipients` before `onCreateLink` is called.\n   */\n  contacts: Actor[];\n  /**\n   * Pre-resolved recipients for link types whose `compose.targets` is\n   * `\"contacts\"` or `\"addresses\"`.\n   *\n   * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n   * contact UUID, the platform-specific account ID\n   * (`externalAccountId`) the connector should use to address the\n   * recipient without performing its own lookup, and the contact's\n   * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n   * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n   * a connection-scoped row fall back to `contact.email`.\n   */\n  recipients?: ResolvedRecipient[];\n  /**\n   * Free-form addresses the user typed into the picker (no Plot contact\n   * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n   * undefined. Connectors should append these alongside `recipients`\n   * when constructing the recipient list (e.g. `To:` header for Gmail).\n   */\n  inviteEmails?: string[];\n};\n\n/** An optional OAuth scope group the user can toggle at connect time. */\nexport type OptionalScopeGroup = {\n  /** Stable id used to track the user's selection. */\n  id: string;\n  /** Value-forward switch label, e.g. \"Add names to events using contacts\". */\n  label: string;\n  /** Optional secondary line shown under the label. */\n  description?: string;\n  /** The OAuth scope strings this group grants. */\n  scopes: string[];\n  /** Whether the group is requested by default (switch on). */\n  default: boolean;\n};\n\n/**\n * Structured scope declaration. `required` scopes must be granted — auth fails\n * and re-prompts if any is declined. `optional` groups are requested by default\n * but auth still succeeds if the user declines them; the connector should detect\n * the absence via the granted `token.scopes` and degrade gracefully.\n */\nexport type ScopeConfig = {\n  required: string[];\n  optional?: OptionalScopeGroup[];\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\", icon: \"todo\" },\n *       { status: \"done\", label: \"Done\", icon: \"done\", done: true },\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 — a flat list (all required), or\n   *  a {@link ScopeConfig} declaring required + optional scope groups. */\n  readonly scopes?: string[] | ScopeConfig;\n\n  /**\n   * Plain-language bullets describing what access connecting this service\n   * grants the user — shown on the connect screen regardless of auth mechanism\n   * (OAuth, API key, or hosted). For OAuth connectors it also previews what the\n   * provider's consent screen will request. These are justifications for what\n   * Plot accesses, not a one-to-one mapping of scope strings.\n   */\n  readonly access?: 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   * The user-facing noun for this connector's channels — what each\n   * {@link Channel} returned by {@link getChannels} actually represents in the\n   * external service. Many connectors map \"channels\" onto a domain concept\n   * (folders, projects, calendars, labels, spaces, repositories, …), so the\n   * generic word \"channel\" reads as jargon. Set this and the UI substitutes it\n   * everywhere it would otherwise say \"channel(s)\" — e.g. the per-connection\n   * toggle becomes \"Sync new folders\" / \"When a new folder is added, …\".\n   *\n   * Provide lowercase nouns (the UI capitalizes where needed):\n   * `{ singular: \"folder\", plural: \"folders\" }`. Defaults to\n   * `{ singular: \"channel\", plural: \"channels\" }` when omitted.\n   */\n  readonly channelNoun?: { singular: string; plural: string };\n\n  /**\n   * Whether the per-connection \"Sync new channels\" preference starts ON for\n   * newly added connections of this connector. Defaults to `false` (opt-in).\n   *\n   * Set `true` for connectors that select **all** of their channels by default\n   * (i.e. {@link getChannels} returns no channels marked\n   * `enabledByDefault: false`). If syncing every channel is the intended\n   * default, then channels discovered later should also sync automatically.\n   * Leave `false`/omitted for selective connectors that exclude some channels\n   * by default (e.g. Gmail syncs only Inbox/Sent, Google Calendar only\n   * owner calendars) — for those, a newly discovered channel is just as\n   * uncertain and should wait for the user to opt in.\n   *\n   * Only affects the **default** for new connections; the user's explicit\n   * toggle always wins, and existing connections keep their stored preference.\n   */\n  readonly autoEnableNewChannelsByDefault?: boolean;\n\n  /**\n   * Whether this connector supports the platform's sequential auto-threading —\n   * folding a conversation that arrives as a run of separate top-level messages\n   * into a single thread. Set `true` for conversational connectors (chat,\n   * messaging) that mark eligible links with {@link NewLink.autoThread}. The UI\n   * shows a per-connection \"Group related messages into conversations\" toggle\n   * only for connectors that declare this.\n   *\n   * Leave undefined/false for connectors whose items are not conversational\n   * (calendars, issue trackers, file storage) — marking a link does nothing\n   * unless the connection both declares support and the user opted in.\n   */\n  readonly autoThreading?: boolean;\n\n  /**\n   * Whether the per-connection auto-threading preference starts ON for newly\n   * added connections of this connector. Defaults to `false` (opt-in) — the\n   * least-surprise default, since a wrong fold is irreversible. Only meaningful\n   * when {@link autoThreading} is `true`. The user's explicit toggle always\n   * wins, and existing connections keep their stored preference.\n   */\n  readonly autoThreadingByDefault?: 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   * Declares how this connector's platform handles emoji reactions.\n   * Used to filter the reaction picker for notes whose primary connector\n   * is this one, and to guard outbound dispatch from sending emoji the\n   * platform can't accept.\n   *\n   * Leave undefined for connectors whose platform has no concept of\n   * reactions (calendar, file storage, issue trackers without reactions).\n   */\n  readonly reactionCapabilities?: ReactionCapabilities;\n\n  /**\n   * When true, this connector's effective link types are computed dynamically\n   * from its enabled channels' per-channel link types (each channel carries the\n   * link types for whatever product/resource it represents), rather than the\n   * static union of all declared providers' link types. Lets one connection\n   * surface different link types depending on what the user has enabled — e.g.\n   * a combined Google connection shows calendar/event link types (and thus the\n   * agenda) only when a calendar channel is enabled.\n   *\n   * Defaults to false (static link types — the behavior for every connector\n   * that doesn't set this). Requires the connector to attach per-channel\n   * `linkTypes` on the channels returned by `getChannels`.\n   */\n  readonly dynamicLinkTypes?: boolean;\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   * The framework dispatches this in three cases:\n   *  1. **Initial enable** — user toggled the channel on for the first time.\n   *  2. **Auto-enable** — `setChannels` discovered a new channel on a\n   *     connection with `auto_enable_new_channels` set.\n   *  3. **Recovery after re-auth** — the user re-authorized a previously-\n   *     broken connection. The framework calls `onChannelEnabled` for every\n   *     channel that was already enabled at the time of re-auth, with\n   *     `context.recovering = true`. See {@link SyncContext.recovering}.\n   *\n   * Implementations should be **idempotent and overwrite stored state**:\n   * the same channel may receive multiple `onChannelEnabled` calls across\n   * its lifetime. Use unconditional `this.set()` writes rather than\n   * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n   * cursors and state from the prior session.\n   *\n   * **Sync state tracking is automatic.** The framework stamps the\n   * connection as \"syncing\" when it dispatches this method and clears\n   * that state when:\n   *  - the connector calls `tools.integrations.channelSyncCompleted(id)`\n   *    once the initial backfill is done, OR\n   *  - this method throws an unhandled exception (auto-cleared so the UI\n   *    doesn't get stuck in \"syncing\" forever).\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, context?: SyncContext): Promise<void> {\n   *   // Recovery: drop stale cursors so the next sync re-walks history.\n   *   if (context?.recovering) {\n   *     await this.clear(`last_sync_token_${channel.id}`);\n   *   }\n   *\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 (plan-based hints, recovery flag)\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\n   * `compose` block on the relevant `LinkTypeConfig` (see\n   * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n   * Add link modal and the thread is synced, the runtime calls this method\n   * 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   * Resolve a `fileRef` action's bytes for download. Called when a user opens\n   * an attachment in Plot. Return either a redirect URL (preferred for sources\n   * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n   * streamed body (required when bytes are only reachable through an\n   * authenticated API call, like Gmail attachments.get).\n   *\n   * @param ref Opaque value the connector previously emitted on a fileRef action.\n   * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n   * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n   *\n   * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n   */\n  async downloadAttachment(\n    ref: string,\n  ): Promise<\n    | { redirectUrl: string }\n    | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n  > {\n    throw new Error(\n      `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n    );\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 changes the **thread-level sharing** of a thread owned\n   * by this connector — adding or removing a contact, or (for connectors with\n   * roles) changing a contact's role. Override on connectors whose external\n   * source can reflect that membership change, e.g. a group DM / multi-party\n   * chat (`LinkTypeConfig.sharingModel: \"thread\"`) or an email's To/Cc/Bcc\n   * recipients (`sharingModel: \"message\"`). Connectors backed by an immutable\n   * roster (most group DMs today) or by channel-level membership\n   * (`sharingModel: \"channel\"`) leave this as the default no-op.\n   *\n   * `role`/`from`/`to` are **null** for connectors without roles (group DMs\n   * have no roles); they carry a `contactRoles` id only for connectors that\n   * declare roles (e.g. email `to`/`cc`/`bcc`).\n   *\n   * The dispatch fires after Plot has persisted the change. A connector may\n   * reflect it actively (e.g. add/remove a participant on the external chat)\n   * or passively on the next outbound note (e.g. building To/Cc/Bcc headers\n   * from the current `thread.contacts` × `thread.contactMeta`) — this callback\n   * is not the right place to send a standalone notification.\n   *\n   * @param thread - The thread whose contacts changed\n   * @param changes - The added/removed contacts and any role transitions on existing contacts\n   */\n  /* eslint-disable @typescript-eslint/no-unused-vars */\n  onContactsChanged(\n    thread: Thread,\n    changes: {\n      added: Array<{ contact: Contact; role: string | null }>;\n      removed: Array<{ contact: Contact; role: string | null }>;\n      changed: Array<{ contact: Contact; from: string | null; to: string | null }>;\n    },\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n  /* eslint-enable @typescript-eslint/no-unused-vars */\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  /**\n   * Called when a user adds or removes a single emoji reaction on a note\n   * (one event per `(note, actor, emoji)` state transition).\n   *\n   * Dispatch is routed to the reacting user's own connector instance via\n   * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n   * already runs under the reactor's auth. Fetch the API client with the\n   * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n   * and the external write — e.g. Slack `reactions.add` — will be attributed\n   * to the correct user. No `actAs` step required.\n   *\n   * If the reacting user has no connection of this type, no dispatch fires\n   * for that reaction (it stays in Plot only).\n   *\n   * Override to sync per-actor reactions back to the external system.\n   *\n   * @param note  - The note that was reacted on (partial; `id`, `key`, `content` populated)\n   * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n   * @param actor - The contact who added/removed the reaction\n   * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n   * @param added - `true` if the reaction is now present, `false` if it was removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): 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";

package/src/llm-docs/tool.ts

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

package/src/llm-docs/tools/tasks.ts

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks for execution in separate\n * worker contexts. **This is critical for staying under request limits**: each execution\n * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and\n * running a task creates a NEW execution with a fresh request limit.\n *\n * **Key distinction:**\n * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count\n * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit\n *\n * **When to use tasks:**\n * - Processing large datasets that would exceed 1000 requests\n * - Breaking loops into chunks where each chunk stays under the request limit\n * - Scheduling operations for future execution\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Size batches to stay under ~1000 requests per execution\n * - Calculate requests per item to determine safe batch size\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool<SyncTool> {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch\n *     const callback = await this.callback(this.processBatch, 1);\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(batchNumber: number) {\n *     // Process one batch of items (sized to stay under request limit)\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // If each item makes ~10 requests, process ~100 items per batch\n *     // 100 items × 10 requests = 1000 requests (at limit)\n *     const batchSize = 100;\n *     const items = await this.fetchItems(progress.processed, batchSize);\n *\n *     for (const item of items) {\n *       await this.processItem(item); // Makes ~10 requests per item\n *     }\n *\n *     await this.set(\"sync_progress\", {\n *       processed: progress.processed + batchSize,\n *       total: progress.total\n *     });\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch - creates NEW execution with fresh request limit\n *       const callback = await this.callback(this.processBatch, batchNumber + 1);\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(this.cleanupOldData);\n *     // Schedule for future execution\n *     return await this.runTask(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds\n   * CPU time. Use this for breaking loops into chunks that stay under the request limit.\n   *\n   * **Key distinction:**\n   * - `this.run(callback)` - Continues same execution, shares request count\n   * - `this.runTask(callback)` - NEW execution, fresh request limit\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches to stay under request limit\n   * const callback = await this.callback(this.syncBatch, 1);\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n\n  /**\n   * Schedules a **singleton** task identified by `key`: scheduling under a key\n   * that already has a pending task atomically cancels the existing one and\n   * replaces it. At most one scheduled task per `key` is ever live.\n   *\n   * Use this for any recurring/self-renewing job — webhook/watch renewals,\n   * periodic polling, deferred cleanup — instead of hand-managing tokens with\n   * `runTask()` + `cancelTask()`. The manual pattern (store the token, cancel\n   * it before re-scheduling) is easy to get wrong: a renewal callback that\n   * re-schedules itself, combined with any *extra* scheduling call (a\n   * re-dispatched `onChannelEnabled`, a re-init), leaks parallel self-\n   * perpetuating chains that accumulate forever and can trip the runtime's\n   * execution quota. Keying makes that leak impossible by construction.\n   *\n   * Replacement is atomic on the server, so concurrent executions racing to\n   * schedule the same key converge on a single task rather than leaking.\n   *\n   * @param key - Stable identifier for this logical task. Scope it to what it\n   *   renews, e.g. `` `watch-renewal:${folderId}` ``.\n   * @param callback - Callback created with `this.callback()`\n   * @param options.runAt - When to run. Required: keying only applies to\n   *   scheduled tasks (immediate tasks go straight to the queue).\n   * @returns Promise resolving to the cancellation token for the scheduled task\n   *\n   * @example\n   * ```typescript\n   * const cb = await this.callback(this.renewWatch, folderId);\n   * await this.scheduleTask(`watch-renewal:${folderId}`, cb, { runAt });\n   * // ...later, on disable:\n   * await this.cancelScheduledTask(`watch-renewal:${folderId}`);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract scheduleTask(\n    key: string,\n    callback: Callback,\n    options: { runAt: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels the singleton task previously scheduled under `key` (if any).\n   *\n   * No error is thrown if no task exists for the key or it has already run.\n   * Pair this with {@link scheduleTask} in teardown paths (e.g.\n   * `onChannelDisabled`, `stopSync`).\n   *\n   * @param key - The same key passed to {@link scheduleTask}\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelScheduledTask(key: string): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks for execution in separate\n * worker contexts. **This is critical for staying under request limits**: each execution\n * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and\n * running a task creates a NEW execution with a fresh request limit.\n *\n * **Key distinction:**\n * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count\n * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit\n *\n * **When to use tasks:**\n * - Processing large datasets that would exceed 1000 requests\n * - Breaking loops into chunks where each chunk stays under the request limit\n * - Scheduling operations for future execution\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Size batches to stay under ~1000 requests per execution\n * - Calculate requests per item to determine safe batch size\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool<SyncTool> {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch\n *     const callback = await this.callback(this.processBatch, 1);\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(batchNumber: number) {\n *     // Process one batch of items (sized to stay under request limit)\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // If each item makes ~10 requests, process ~100 items per batch\n *     // 100 items × 10 requests = 1000 requests (at limit)\n *     const batchSize = 100;\n *     const items = await this.fetchItems(progress.processed, batchSize);\n *\n *     for (const item of items) {\n *       await this.processItem(item); // Makes ~10 requests per item\n *     }\n *\n *     await this.set(\"sync_progress\", {\n *       processed: progress.processed + batchSize,\n *       total: progress.total\n *     });\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch - creates NEW execution with fresh request limit\n *       const callback = await this.callback(this.processBatch, batchNumber + 1);\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(this.cleanupOldData);\n *     // Schedule for future execution\n *     return await this.runTask(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds\n   * CPU time. Use this for breaking loops into chunks that stay under the request limit.\n   *\n   * **Key distinction:**\n   * - `this.run(callback)` - Continues same execution, shares request count\n   * - `this.runTask(callback)` - NEW execution, fresh request limit\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches to stay under request limit\n   * const callback = await this.callback(this.syncBatch, 1);\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n\n  /**\n   * Schedules a **one-shot singleton** task identified by `key`: scheduling\n   * under a key that already has a pending task atomically cancels the existing\n   * one and replaces it. At most one scheduled task per `key` is ever live.\n   *\n   * Use this for **one-shot keyed deferred work** — a single future task whose\n   * pending occurrence should be atomically replaced if re-scheduled (e.g.\n   * a deferred cleanup, a one-time expiry action, a single future send).\n   *\n   * For **recurring/self-renewing jobs** (watch renewals, polling loops,\n   * periodic syncs, self-heal checks), use {@link scheduleRecurring} instead.\n   * It owns the cadence on the platform side, so the chain survives dropped\n   * runs, suspensions, and deploys without the callback needing to reschedule\n   * itself.\n   *\n   * Replacement is atomic on the server, so concurrent executions racing to\n   * schedule the same key converge on a single task rather than leaking.\n   *\n   * @param key - Stable identifier for this logical task. Scope it to what it\n   *   renews, e.g. `` `watch-renewal:${folderId}` ``.\n   * @param callback - Callback created with `this.callback()`\n   * @param options.runAt - When to run. Required: keying only applies to\n   *   scheduled tasks (immediate tasks go straight to the queue).\n   * @returns Promise resolving to the cancellation token for the scheduled task\n   *\n   * @example\n   * ```typescript\n   * const cb = await this.callback(this.renewWatch, folderId);\n   * await this.scheduleTask(`watch-renewal:${folderId}`, cb, { runAt });\n   * // ...later, on disable:\n   * await this.cancelScheduledTask(`watch-renewal:${folderId}`);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract scheduleTask(\n    key: string,\n    callback: Callback,\n    options: { runAt: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels the singleton task previously scheduled under `key` (if any).\n   *\n   * No error is thrown if no task exists for the key or it has already run.\n   * Pair this with {@link scheduleTask} in teardown paths (e.g.\n   * `onChannelDisabled`, `stopSync`).\n   *\n   * @param key - The same key passed to {@link scheduleTask}\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelScheduledTask(key: string): Promise<void>;\n\n  /**\n   * Schedules a **durable recurring** task identified by `key`. Unlike\n   * {@link scheduleTask} (one-shot, deleted when it fires), a recurring task's\n   * next occurrence is owned by the platform: the runtime re-arms it every\n   * `intervalMs` automatically, so the chain survives a dropped queue message,\n   * a suspension, a deploy/eviction, or a callback that throws before it could\n   * reschedule. The callback just does the work, idempotently — it does NOT\n   * need to reschedule itself.\n   *\n   * `intervalMs` is a **safety ceiling** (the maximum gap between fires). For\n   * data-dependent cadence (e.g. renew 24h before a provider-returned expiry),\n   * pass `firstRunAt` for the precise next fire and re-call `scheduleRecurring`\n   * with the same key on each run to keep tightening it; the ceiling guarantees\n   * the chain still fires if a run is lost. `firstRunAt` can pull the next fire\n   * earlier than the ceiling but never later.\n   *\n   * Recurring tasks are keyed/singleton: re-scheduling under the same key\n   * atomically replaces the pending occurrence (one live task per key). Tear\n   * down with {@link cancelScheduledTask}.\n   *\n   * @param key - Stable identifier, scoped to what it maintains, e.g.\n   *   `` `watch-renewal:${folderId}` `` or `\"mailbox-self-heal\"`.\n   * @param callback - Callback created with `this.callback()`.\n   * @param options.intervalMs - Safety-ceiling cadence in milliseconds.\n   * @param options.firstRunAt - Optional precise time for the next fire\n   *   (clamped to no later than now + intervalMs).\n   *\n   * @example\n   * ```typescript\n   * // Fixed cadence (self-heal, polling): register once, never reschedule.\n   * const cb = await this.callback(this.selfHealCheck);\n   * await this.scheduleRecurring(\"mailbox-self-heal\", cb, { intervalMs: 60 * 60 * 1000 });\n   *\n   * // Variable cadence (watch renewal): precise firstRunAt + safety ceiling.\n   * const renew = await this.callback(this.renewWatch, folderId);\n   * await this.scheduleRecurring(`watch-renewal:${folderId}`, renew, {\n   *   intervalMs: 3.5 * 24 * 60 * 60 * 1000,   // ceiling: half the 7-day watch\n   *   firstRunAt: new Date(expiry.getTime() - 24 * 60 * 60 * 1000),\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract scheduleRecurring(\n    key: string,\n    callback: Callback,\n    options: { intervalMs: number; firstRunAt?: Date }\n  ): Promise<void>;\n}\n";

package/src/llm-docs/twist.ts

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

package/src/tool.ts

@@ -320,6 +320,26 @@ export abstract class Tool<TSelf> implements ITool {
     return this.tools.tasks.cancelScheduledTask(key);
   }
 
+  /**
+   * Schedules a durable recurring task under a stable key. The platform
+   * re-arms the task every `intervalMs` automatically — the callback does NOT
+   * need to reschedule itself. Re-scheduling under the same key atomically
+   * replaces the pending occurrence (at most one live task per key). Tear down
+   * with {@link cancelScheduledTask}. See {@link Tasks.scheduleRecurring}.
+   *
+   * @param key - Stable identifier, e.g. `"mailbox-self-heal"`
+   * @param callback - Callback token created with `this.callback()`
+   * @param options.intervalMs - Safety-ceiling cadence in milliseconds
+   * @param options.firstRunAt - Optional precise time for the next fire
+   */
+  protected async scheduleRecurring(
+    key: string,
+    callback: Callback,
+    options: { intervalMs: number; firstRunAt?: Date }
+  ): Promise<void> {
+    return this.tools.tasks.scheduleRecurring(key, callback, options);
+  }
+
   /**
    * Called before the twist's activate method, starting from the deepest tool dependencies.
    *

package/src/tools/tasks.ts

@@ -134,18 +134,19 @@ export abstract class Tasks extends ITool {
   abstract cancelAllTasks(): Promise<void>;
 
   /**
-   * Schedules a **singleton** task identified by `key`: scheduling under a key
-   * that already has a pending task atomically cancels the existing one and
-   * replaces it. At most one scheduled task per `key` is ever live.
-   *
-   * Use this for any recurring/self-renewing job — webhook/watch renewals,
-   * periodic polling, deferred cleanup — instead of hand-managing tokens with
-   * `runTask()` + `cancelTask()`. The manual pattern (store the token, cancel
-   * it before re-scheduling) is easy to get wrong: a renewal callback that
-   * re-schedules itself, combined with any *extra* scheduling call (a
-   * re-dispatched `onChannelEnabled`, a re-init), leaks parallel self-
-   * perpetuating chains that accumulate forever and can trip the runtime's
-   * execution quota. Keying makes that leak impossible by construction.
+   * Schedules a **one-shot singleton** task identified by `key`: scheduling
+   * under a key that already has a pending task atomically cancels the existing
+   * one and replaces it. At most one scheduled task per `key` is ever live.
+   *
+   * Use this for **one-shot keyed deferred work** — a single future task whose
+   * pending occurrence should be atomically replaced if re-scheduled (e.g.
+   * a deferred cleanup, a one-time expiry action, a single future send).
+   *
+   * For **recurring/self-renewing jobs** (watch renewals, polling loops,
+   * periodic syncs, self-heal checks), use {@link scheduleRecurring} instead.
+   * It owns the cadence on the platform side, so the chain survives dropped
+   * runs, suspensions, and deploys without the callback needing to reschedule
+   * itself.
    *
    * Replacement is atomic on the server, so concurrent executions racing to
    * schedule the same key converge on a single task rather than leaking.
@@ -184,4 +185,52 @@ export abstract class Tasks extends ITool {
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract cancelScheduledTask(key: string): Promise<void>;
+
+  /**
+   * Schedules a **durable recurring** task identified by `key`. Unlike
+   * {@link scheduleTask} (one-shot, deleted when it fires), a recurring task's
+   * next occurrence is owned by the platform: the runtime re-arms it every
+   * `intervalMs` automatically, so the chain survives a dropped queue message,
+   * a suspension, a deploy/eviction, or a callback that throws before it could
+   * reschedule. The callback just does the work, idempotently — it does NOT
+   * need to reschedule itself.
+   *
+   * `intervalMs` is a **safety ceiling** (the maximum gap between fires). For
+   * data-dependent cadence (e.g. renew 24h before a provider-returned expiry),
+   * pass `firstRunAt` for the precise next fire and re-call `scheduleRecurring`
+   * with the same key on each run to keep tightening it; the ceiling guarantees
+   * the chain still fires if a run is lost. `firstRunAt` can pull the next fire
+   * earlier than the ceiling but never later.
+   *
+   * Recurring tasks are keyed/singleton: re-scheduling under the same key
+   * atomically replaces the pending occurrence (one live task per key). Tear
+   * down with {@link cancelScheduledTask}.
+   *
+   * @param key - Stable identifier, scoped to what it maintains, e.g.
+   *   `` `watch-renewal:${folderId}` `` or `"mailbox-self-heal"`.
+   * @param callback - Callback created with `this.callback()`.
+   * @param options.intervalMs - Safety-ceiling cadence in milliseconds.
+   * @param options.firstRunAt - Optional precise time for the next fire
+   *   (clamped to no later than now + intervalMs).
+   *
+   * @example
+   * ```typescript
+   * // Fixed cadence (self-heal, polling): register once, never reschedule.
+   * const cb = await this.callback(this.selfHealCheck);
+   * await this.scheduleRecurring("mailbox-self-heal", cb, { intervalMs: 60 * 60 * 1000 });
+   *
+   * // Variable cadence (watch renewal): precise firstRunAt + safety ceiling.
+   * const renew = await this.callback(this.renewWatch, folderId);
+   * await this.scheduleRecurring(`watch-renewal:${folderId}`, renew, {
+   *   intervalMs: 3.5 * 24 * 60 * 60 * 1000,   // ceiling: half the 7-day watch
+   *   firstRunAt: new Date(expiry.getTime() - 24 * 60 * 60 * 1000),
+   * });
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract scheduleRecurring(
+    key: string,
+    callback: Callback,
+    options: { intervalMs: number; firstRunAt?: Date }
+  ): Promise<void>;
 }