@plotday/twister 0.57.0 → 0.58.0

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

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  type NewNote,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /**\n   * Whether this channel should be selected by default when the user first\n   * adds the connection. Tri-state:\n   * - `true`  — pre-select it (e.g. the user's own/primary calendar).\n   * - `false` — exclude it from the default selection (low-value or\n   *   irrelevant resources that would crowd the user's view, or containers\n   *   whose contents are too broad to sync wholesale — e.g. a holiday or\n   *   someone-else's shared calendar, a GitHub org that cascades to every\n   *   repo, a Microsoft Teams team container). The user can still enable it\n   *   manually.\n   * - `undefined` — no opinion; the client decides. The client defaults to\n   *   enabling the channel unless its title looks low-value (holidays,\n   *   birthdays, spam/sent/draft, …).\n   *\n   * The guiding principle is \"sync everything the user would reasonably want\n   * by default\" — for most connectors that's all channels, so only set this\n   * where the connector can distinguish the user's own/relevant channels from\n   * low-value ones (e.g. Google Calendar via `accessRole === \"owner\"`).\n   */\n  enabledByDefault?: boolean;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Curated status-icon vocabulary. Connectors map each declared status to the\n * closest icon; clients render a single glyph per value. Required on every\n * status so the UI always has something to show.\n */\nexport type StatusIcon =\n  | \"backlog\"\n  | \"todo\"\n  | \"inProgress\"\n  | \"blocked\"\n  | \"done\"\n  | \"cancelled\"\n  | \"confirmed\"\n  | \"tentative\";\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type — used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /**\n   * Placeholder shown in the editor when this link type is the target of a\n   * new thread (NewThreadPage). Example: \"Send a Gmail email\".\n   * If unset, Plot derives \"Create a new {connector} {label.toLowerCase()}\".\n   */\n  composePlaceholder?: string;\n  /**\n   * Label for the Send button on NewThreadPage when this link type is the\n   * target. Example: \"Send\". If unset, defaults to \"Create\".\n   */\n  composeVerb?: string;\n  /**\n   * Placeholder shown in the in-thread editor for the default reply mode.\n   * Example: \"Reply\" (Gmail), \"Add a comment\" (Linear). If unset, Plot derives\n   * \"Add a {noteLabel.toLowerCase()}\" or \"Add a note\".\n   */\n  replyPlaceholder?: string;\n  /**\n   * Label for the Send button in the in-thread editor. Example: \"Send\"\n   * (Gmail), \"Comment\" (Linear). If unset, defaults to \"Send\".\n   */\n  replyVerb?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Curated icon for this status (required so the UI always has a glyph). */\n    icon: StatusIcon;\n    /**\n     * Suppress this status's icon on the feed row (ThreadWidget) while still\n     * showing it in the ThreadPage header. Use for a \"resting\" default state\n     * that would otherwise clutter the feed (e.g. calendar \"Confirmed\").\n     */\n    hiddenDefault?: boolean;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now — Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Marks this status as the connector's \"to-do\" / active state. When a\n     * user brings a done thread back into Plot's agenda, done-status links\n     * are flipped to the status marked `todo: true` (e.g. Gmail's \"starred\",\n     * Linear's \"unstarted\"); connectors that don't mark one fall back to the\n     * first non-done status.\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /**\n   * Whether this link type produces time-anchored schedule/agenda items\n   * (i.e. calendar events). The Plot app shows the agenda (the bottom-nav\n   * tab on mobile and the left-sidebar agenda on desktop) only when the\n   * user has at least one active connection whose link types include one\n   * with `includesSchedules: true`. Calendar connectors (Google / Apple /\n   * Outlook Calendar) set this on their `event` link type. Defaults to\n   * false — non-calendar link types (messages, issues, tasks, docs) omit it.\n   */\n  includesSchedules?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new …\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   → [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar → [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Whether a note/reply on this link type can carry a link (a pasted URL or\n   * connector-created item) that Plot forwards to the source. When false (the\n   * default), the \"Add link\" button is hidden for threads of this link type.\n   * Only set true if the connector's reply path actually forwards the link\n   * action to the source. Private Plot notes (no link type) always allow links.\n   */\n  supportsLinks?: boolean;\n  /**\n   * Whether a note/reply on this link type can carry an uploaded file that Plot\n   * forwards to the source as an attachment. When false (the default), the\n   * \"Attach file\" button is hidden for threads of this link type. Only set true\n   * if the connector's reply path actually uploads file actions to the source.\n   * Private Plot notes (no link type) always allow attachments.\n   */\n  supportsFileAttachments?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   * - `\"none\"`: the link type has no recipient roster at all. No\n   *   contacts/sharing UI is shown for these threads. Use for purely\n   *   personal destinations with no sharing concept (e.g. Google\n   *   Tasks). The per-thread `contacts` array is ignored for sharing UI.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\" | \"none\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new …\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker — used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector — see\n   * `connectors/linear/src/linear.ts`).\n   *\n   * Omit for status-less link types (e.g. messaging connectors that don't\n   * model a status): composed links are created with no status.\n   */\n  status?: string;\n  /**\n   * Optional override for the picker chip / \"Create new …\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid —\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications — set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n\n  /**\n   * True when the channel is being observed because the user composed a Plot\n   * thread INTO it (via `onCreateLink`), not because they explicitly enabled\n   * it. The connector should register webhooks / mark the channel observed so\n   * inbound events (replies, reactions) on the composed thread sync back —\n   * but must NOT backfill history. Only go-forward events matter; pulling the\n   * channel's existing content would be surprising for a channel the user\n   * only posted one thread into.\n   *\n   * Connectors whose `onChannelEnabled` already skips historical backfill can\n   * ignore this flag. Connectors that initial-sync on enable MUST short-\n   * circuit that backfill when `observeOnly` is true (still set up webhooks\n   * and any go-forward state).\n   */\n  observeOnly?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's focus.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} — saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Save one or more notes. Unlike saveLink (which creates a thread-level\n   * canonical link), these notes attach to an EXISTING thread — addressed by\n   * `note.thread: { id }` or `{ source }` — and may carry their own\n   * note-attached link via `note.link` (a note-scoped link, NOT a thread-level\n   * canonical link). When `{ source }` resolves to no thread yet, the runtime\n   * find-or-creates the thread by that source. Use for augmenter content\n   * (e.g. meeting notes attached to a calendar event).\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveNotes(notes: NewNote[]): Promise<(Uuid | null)[]>;\n  /** Save a single note. See {@link saveNotes}. */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveNote(note: NewNote): Promise<Uuid | null>;\n  /**\n   * Archive every note this connector created (optionally scoped to a channel),\n   * plus their note-attached links. Mirror of {@link archiveLinks} for the\n   * note-attached content model. Use in `onChannelDisabled`.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveNotes(filter: ArchiveNotesFilter): Promise<void>;\n\n  /**\n   * Upserts contacts into the connector's focus without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing…\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking — only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state — connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh — e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n  /**\n   * Upsert workspace custom emoji into Plot's shared cache so reactions using\n   * `provider:workspace/name` refs render as images and round-trip. Idempotent;\n   * keyed on `id`. Pass `archived: true` to mark an emoji removed. Workspace-\n   * scoped (shared across all users of that workspace).\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveCustomEmoji(emoji: NewCustomEmoji[]): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Filter criteria for archiving notes (and their note-attached links).\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveNotesFilter = {\n  /** Restrict to notes whose note-attached link is on this channel. */\n  channelId?: string;\n};\n\n/**\n * A workspace custom emoji to cache so Plot can render and round-trip it as a\n * reaction. `id` is the provider-scoped ref stored on reactions, of the form\n * `<provider>:<workspace>/<name>` (e.g. `slack:T0123ABC/party_parrot`).\n */\nexport type NewCustomEmoji = {\n  /** Provider-scoped ref: `<provider>:<workspace>/<name>`. The reaction value. */\n  id: string;\n  /** e.g. \"slack\". */\n  provider: string;\n  /** Provider workspace/team id (e.g. Slack team id `T0123ABC`). */\n  workspace: string;\n  /** Bare emoji name without colons (e.g. \"party_parrot\"). */\n  name: string;\n  /** Image URL to render, or null for an alias (see `aliasOf`). */\n  imageUrl: string | null;\n  /** When this emoji aliases another, the target ref (`id` of the canonical emoji); else null. */\n  aliasOf: string | null;\n  /** True to mark the emoji removed (archive it) rather than upsert it. */\n  archived: boolean;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  type NewNote,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /**\n   * Whether this channel should be selected by default when the user first\n   * adds the connection. Tri-state:\n   * - `true`  — pre-select it (e.g. the user's own/primary calendar).\n   * - `false` — exclude it from the default selection (low-value or\n   *   irrelevant resources that would crowd the user's view, or containers\n   *   whose contents are too broad to sync wholesale — e.g. a holiday or\n   *   someone-else's shared calendar, a GitHub org that cascades to every\n   *   repo, a Microsoft Teams team container). The user can still enable it\n   *   manually.\n   * - `undefined` — no opinion; the client decides. The client defaults to\n   *   enabling the channel unless its title looks low-value (holidays,\n   *   birthdays, spam/sent/draft, …).\n   *\n   * The guiding principle is \"sync everything the user would reasonably want\n   * by default\" — for most connectors that's all channels, so only set this\n   * where the connector can distinguish the user's own/relevant channels from\n   * low-value ones (e.g. Google Calendar via `accessRole === \"owner\"`).\n   */\n  enabledByDefault?: boolean;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Curated status-icon vocabulary. Connectors map each declared status to the\n * closest icon; clients render a single glyph per value. Required on every\n * status so the UI always has something to show.\n */\nexport type StatusIcon =\n  | \"backlog\"\n  | \"todo\"\n  | \"inProgress\"\n  | \"blocked\"\n  | \"done\"\n  | \"cancelled\"\n  | \"confirmed\"\n  | \"tentative\";\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type — used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /**\n   * Placeholder shown in the editor when this link type is the target of a\n   * new thread (NewThreadPage). Example: \"Send a Gmail email\".\n   * If unset, Plot derives \"Create a new {connector} {label.toLowerCase()}\".\n   */\n  composePlaceholder?: string;\n  /**\n   * Label for the Send button on NewThreadPage when this link type is the\n   * target. Example: \"Send\". If unset, defaults to \"Create\".\n   */\n  composeVerb?: string;\n  /**\n   * Placeholder shown in the in-thread editor for the default reply mode.\n   * Example: \"Reply\" (Gmail), \"Add a comment\" (Linear). If unset, Plot derives\n   * \"Add a {noteLabel.toLowerCase()}\" or \"Add a note\".\n   */\n  replyPlaceholder?: string;\n  /**\n   * Label for the Send button in the in-thread editor. Example: \"Send\"\n   * (Gmail), \"Comment\" (Linear). If unset, defaults to \"Send\".\n   */\n  replyVerb?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Curated icon for this status (required so the UI always has a glyph). */\n    icon: StatusIcon;\n    /**\n     * Suppress this status's icon on the feed row (ThreadWidget) while still\n     * showing it in the ThreadPage header. Use for a \"resting\" default state\n     * that would otherwise clutter the feed (e.g. calendar \"Confirmed\").\n     */\n    hiddenDefault?: boolean;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now — Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Marks this status as the connector's \"to-do\" / active state. When a\n     * user brings a done thread back into Plot's agenda, done-status links\n     * are flipped to the status marked `todo: true` (e.g. Gmail's \"starred\",\n     * Linear's \"unstarted\"); connectors that don't mark one fall back to the\n     * first non-done status.\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /**\n   * Whether this link type produces time-anchored schedule/agenda items\n   * (i.e. calendar events). The Plot app shows the agenda (the bottom-nav\n   * tab on mobile and the left-sidebar agenda on desktop) only when the\n   * user has at least one active connection whose link types include one\n   * with `includesSchedules: true`. Calendar connectors (Google / Apple /\n   * Outlook Calendar) set this on their `event` link type. Defaults to\n   * false — non-calendar link types (messages, issues, tasks, docs) omit it.\n   */\n  includesSchedules?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new …\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   → [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar → [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Whether a note/reply on this link type can carry a link (a pasted URL or\n   * connector-created item) that Plot forwards to the source. When false (the\n   * default), the \"Add link\" button is hidden for threads of this link type.\n   * Only set true if the connector's reply path actually forwards the link\n   * action to the source. Private Plot notes (no link type) always allow links.\n   */\n  supportsLinks?: boolean;\n  /**\n   * Whether a note/reply on this link type can carry an uploaded file that Plot\n   * forwards to the source as an attachment. When false (the default), the\n   * \"Attach file\" button is hidden for threads of this link type. Only set true\n   * if the connector's reply path actually uploads file actions to the source.\n   * Private Plot notes (no link type) always allow attachments.\n   */\n  supportsFileAttachments?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   * - `\"none\"`: the link type has no recipient roster at all. No\n   *   contacts/sharing UI is shown for these threads. Use for purely\n   *   personal destinations with no sharing concept (e.g. Google\n   *   Tasks). The per-thread `contacts` array is ignored for sharing UI.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\" | \"none\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new …\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker — used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector — see\n   * `connectors/linear/src/linear.ts`).\n   *\n   * Omit for status-less link types (e.g. messaging connectors that don't\n   * model a status): composed links are created with no status.\n   */\n  status?: string;\n  /**\n   * Optional override for the picker chip / \"Create new …\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid —\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications — set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n\n  /**\n   * True when the channel is being observed because the user composed a Plot\n   * thread INTO it (via `onCreateLink`), not because they explicitly enabled\n   * it. The connector should register webhooks / mark the channel observed so\n   * inbound events (replies, reactions) on the composed thread sync back —\n   * but must NOT backfill history. Only go-forward events matter; pulling the\n   * channel's existing content would be surprising for a channel the user\n   * only posted one thread into.\n   *\n   * Connectors whose `onChannelEnabled` already skips historical backfill can\n   * ignore this flag. Connectors that initial-sync on enable MUST short-\n   * circuit that backfill when `observeOnly` is true (still set up webhooks\n   * and any go-forward state).\n   */\n  observeOnly?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's focus.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} — saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Save one or more notes. Unlike saveLink (which creates a thread-level\n   * canonical link), these notes attach to an EXISTING thread — addressed by\n   * `note.thread: { id }` or `{ source }` — and may carry their own\n   * note-attached link via `note.link` (a note-scoped link, NOT a thread-level\n   * canonical link). When `{ source }` resolves to no thread yet, the runtime\n   * find-or-creates the thread by that source. Use for augmenter content\n   * (e.g. meeting notes attached to a calendar event).\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveNotes(notes: NewNote[]): Promise<(Uuid | null)[]>;\n  /** Save a single note. See {@link saveNotes}. */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveNote(note: NewNote): Promise<Uuid | null>;\n  /**\n   * Archive every note this connector created (optionally scoped to a channel),\n   * plus their note-attached links. Mirror of {@link archiveLinks} for the\n   * note-attached content model. Use in `onChannelDisabled`.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveNotes(filter: ArchiveNotesFilter): Promise<void>;\n\n  /**\n   * Upserts contacts into the connector's focus without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing…\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking — only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state — connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh — e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n  /**\n   * Upsert workspace custom emoji into Plot's shared cache so reactions using\n   * `provider:workspace/name` refs render as images and round-trip. Idempotent;\n   * keyed on `id`. Pass `archived: true` to mark an emoji removed. Workspace-\n   * scoped (shared across all users of that workspace).\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveCustomEmoji(emoji: NewCustomEmoji[]): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Filter criteria for archiving notes (and their note-attached links).\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveNotesFilter = {\n  /** Restrict to notes whose note-attached link is on this channel. */\n  channelId?: string;\n};\n\n/**\n * A workspace custom emoji to cache so Plot can render and round-trip it as a\n * reaction. `id` is the provider-scoped ref stored on reactions, of the form\n * `<provider>:<workspace>/<name>` (e.g. `slack:T0123ABC/party_parrot`).\n */\nexport type NewCustomEmoji = {\n  /** Provider-scoped ref: `<provider>:<workspace>/<name>`. The reaction value. */\n  id: string;\n  /** e.g. \"slack\". */\n  provider: string;\n  /** Provider workspace/team id (e.g. Slack team id `T0123ABC`). */\n  workspace: string;\n  /** Bare emoji name without colons (e.g. \"party_parrot\"). */\n  name: string;\n  /** Image URL to render, or null for an alias (see `aliasOf`). */\n  imageUrl: string | null;\n  /** When this emoji aliases another, the target ref (`id` of the canonical emoji); else null. */\n  aliasOf: string | null;\n  /** True to mark the emoji removed (archive it) rather than upsert it. */\n  archived: boolean;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - team_id: The Slack workspace/team ID\n   * - team_name: The Slack workspace/team name\n   * - enterprise_id: The Enterprise Grid org ID (when applicable)\n   */\n  provider?: Record<string, string>;\n};\n";

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

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import { ITool } from \"..\";\nimport { type JSONValue, Serializable } from \"../utils/types\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: JSONValue;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook(\n *       {},\n *       this.onCalendarEvent,\n *       calendarId,\n *       \"google\"\n *     );\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Pub/Sub** (`pubsub: \"gmail\" | \"workspace\"`): Returns a Google Pub/Sub topic name instead\n   *   of a webhook URL. `\"gmail\"` targets Gmail `users.watch` (set this only on the Gmail\n   *   connector); `\"workspace\"` targets Google Workspace Events (Chat, etc.). A Pub/Sub topic and\n   *   push subscription are created automatically; the returned topic name (e.g.\n   *   \"projects/plot-prod/topics/gmail-abc123\") is passed to the relevant Google API. Other Google\n   *   connectors (Calendar, Drive) omit `pubsub` and use the default HTTPS webhook.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack)\n   * @param options.pubsub - Optional Google Pub/Sub push product (\"gmail\" | \"workspace\")\n   * @param callback - Function receiving (request, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise resolving to the webhook URL, or for Pub/Sub, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Pub/Sub webhook for Workspace Events API (Chat, etc.)\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: \"workspace\" },\n   *   this.onEventReceived,\n   *   channelId\n   * );\n   * // topicName: \"projects/plot-prod/topics/ps-abc123\"\n   *\n   * // Pass topic name to Workspace Events API\n   * await api.createSubscription(targetResource, topicName, eventTypes);\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns a Gmail Pub/Sub topic name for users.watch\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: \"gmail\" },\n   *   this.onGmailNotification,\n   *   \"inbox\"\n   * );\n   * ```\n   */\n  abstract createWebhook<\n    TArgs extends Serializable[],\n    TCallback extends (request: WebhookRequest, ...args: TArgs) => any\n  >(\n    options: {\n      provider?: AuthProvider;\n      authorization?: Authorization;\n      /**\n       * Create a Google Pub/Sub topic instead of a webhook URL, and return\n       * the topic name. Selects the push product:\n       *\n       * - `\"gmail\"` — Gmail `users.watch` (topic published to by\n       *   `gmail-api-push`). Set this only on the Gmail connector.\n       * - `\"workspace\"` — Google Workspace Events (Chat, etc.).\n       *\n       * This opt-in must be explicit. Other Google connectors (Calendar,\n       * Drive) omit it and receive a standard HTTPS webhook URL — they must\n       * never be routed to a Pub/Sub topic, which `events.watch` /\n       * `files.watch` reject as non-HTTPS.\n       */\n      pubsub?: \"gmail\" | \"workspace\";\n      /**\n       * Controls whether the returned webhook URL runs callbacks synchronously\n       * or asynchronously.\n       *\n       * **Async (default, `async: true`)** — Plot enqueues each incoming\n       * request and immediately returns `200 { queued: true }`. A background\n       * queue consumer runs the callback with bounded concurrency. The\n       * sender never sees the callback's return value or any error thrown\n       * by it, and delivery is at-least-once (the callback must be\n       * idempotent). This is the right default for the vast majority of\n       * webhooks — service event notifications, bulk-import fan-out, etc. —\n       * because it removes ingress-path database pressure and prevents\n       * sender-side retry storms when callbacks are slow.\n       *\n       * **Sync (`async: false`)** — Plot runs the callback inline and\n       * responds with the callback's return value. Required when:\n       * - The sender reads the response body (e.g. Microsoft Graph\n       *   subscription validation, which POSTs with a `validationToken` and\n       *   expects the token echoed as `text/plain`).\n       * - The sender uses the HTTP status code to decide whether to retry\n       *   (e.g. to surface 4xx for permanent failures).\n       * - The handler must observe throws before the sender times out.\n       *\n       * When `async: false`, a callback returning a `string` is sent back\n       * with `Content-Type: text/plain`; any other value is serialized as\n       * JSON. `undefined` / `void` yields a plain `200 OK` body.\n       *\n       * Defaults to `true`.\n       */\n      async?: boolean;\n    },\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport { type JSONValue, Serializable } from \"../utils/types\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: JSONValue;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook(\n *       {},\n *       this.onCalendarEvent,\n *       calendarId,\n *       \"google\"\n *     );\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Pub/Sub** (`pubsub: \"gmail\" | \"workspace\"`): Returns a Google Pub/Sub topic name instead\n   *   of a webhook URL. `\"gmail\"` targets Gmail `users.watch` (set this only on the Gmail\n   *   connector); `\"workspace\"` targets Google Workspace Events (Chat, etc.). A Pub/Sub topic and\n   *   push subscription are created automatically; the returned topic name (e.g.\n   *   \"projects/plot-prod/topics/gmail-abc123\") is passed to the relevant Google API. Other Google\n   *   connectors (Calendar, Drive) omit `pubsub` and use the default HTTPS webhook.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack)\n   * @param options.pubsub - Optional Google Pub/Sub push product (\"gmail\" | \"workspace\")\n   * @param callback - Function receiving (request, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise resolving to the webhook URL, or for Pub/Sub, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Pub/Sub webhook for Workspace Events API (Chat, etc.)\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: \"workspace\" },\n   *   this.onEventReceived,\n   *   channelId\n   * );\n   * // topicName: \"projects/plot-prod/topics/ps-abc123\"\n   *\n   * // Pass topic name to Workspace Events API\n   * await api.createSubscription(targetResource, topicName, eventTypes);\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns a Gmail Pub/Sub topic name for users.watch\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: \"gmail\" },\n   *   this.onGmailNotification,\n   *   \"inbox\"\n   * );\n   * ```\n   */\n  abstract createWebhook<\n    TArgs extends Serializable[],\n    TCallback extends (request: WebhookRequest, ...args: TArgs) => any\n  >(\n    options: {\n      provider?: AuthProvider;\n      authorization?: Authorization;\n      /**\n       * Create a Google Pub/Sub topic instead of a webhook URL, and return\n       * the topic name. Selects the push product:\n       *\n       * - `\"gmail\"` — Gmail `users.watch` (topic published to by\n       *   `gmail-api-push`). Set this only on the Gmail connector.\n       * - `\"workspace\"` — Google Workspace Events (Chat, etc.).\n       *\n       * This opt-in must be explicit. Other Google connectors (Calendar,\n       * Drive) omit it and receive a standard HTTPS webhook URL — they must\n       * never be routed to a Pub/Sub topic, which `events.watch` /\n       * `files.watch` reject as non-HTTPS.\n       */\n      pubsub?: \"gmail\" | \"workspace\";\n      /**\n       * Controls whether the returned webhook URL runs callbacks synchronously\n       * or asynchronously.\n       *\n       * **Async (default, `async: true`)** — Plot enqueues each incoming\n       * request and immediately returns `200 { queued: true }`. A background\n       * queue consumer runs the callback with bounded concurrency. The\n       * sender never sees the callback's return value or any error thrown\n       * by it, and delivery is at-least-once (the callback must be\n       * idempotent). This is the right default for the vast majority of\n       * webhooks — service event notifications, bulk-import fan-out, etc. —\n       * because it removes ingress-path database pressure and prevents\n       * sender-side retry storms when callbacks are slow.\n       *\n       * **Sync (`async: false`)** — Plot runs the callback inline and\n       * responds with the callback's return value. Required when:\n       * - The sender reads the response body (e.g. Microsoft Graph\n       *   subscription validation, which POSTs with a `validationToken` and\n       *   expects the token echoed as `text/plain`).\n       * - The sender uses the HTTP status code to decide whether to retry\n       *   (e.g. to surface 4xx for permanent failures).\n       * - The handler must observe throws before the sender times out.\n       *\n       * When `async: false`, a callback returning a `string` is sent back\n       * with `Content-Type: text/plain`; any other value is serialized as\n       * JSON. `undefined` / `void` yields a plain `200 OK` body.\n       *\n       * Defaults to `true`.\n       */\n      async?: boolean;\n    },\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Pub/Sub).\n   *\n   * **For Pub/Sub webhooks (Gmail and Workspace Events):** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name\n   *              (Gmail/Workspace Events), or an opaque identifier (Slack).\n   *              Always pass the exact value returned from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";

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

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import {\n  type Action,\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type LinkUpdate,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewNote,\n  type NewFocus,\n  type Note,\n  type NoteUpdate,\n  type PlanOperation,\n  type Focus,\n  type FocusUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\nimport type { Callback } from \"./callbacks\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n  /**\n   * List/query all Threads owned by the twist's user.\n   * Update any Thread (title, tags, archived, type, focus) regardless of creator.\n   * Create Notes on any Thread (not just own or mentioned).\n   * All Create permissions.\n   */\n  Full,\n}\n\nexport enum FocusAccess {\n  /**\n   * Create new Focuses for the twist owner.\n   * Update Focuses created by the twist.\n   */\n  Create,\n  /**\n   * Read all Focuses owned by the twist's user.\n   * Create new Focuses for the twist owner.\n   * Update and archive any Focus owned by the twist's user.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n}\n\nexport enum LinkAccess {\n  /** Read links on any thread owned by the twist's user. */\n  Read,\n  /** Read + update links, including moving links between threads owned by the twist's user. */\n  Full,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\ntype SearchResultBase = {\n  thread: { id: string; title: string | null };\n  focus: { id: string; title: string | null };\n  similarity: number;\n};\n\nexport type NoteSearchResult = SearchResultBase & {\n  type: 'note';\n  id: string;\n  content: string | null;\n};\n\nexport type LinkSearchResult = SearchResultBase & {\n  type: 'link';\n  id: string;\n  title: string | null;\n  sourceUrl: string | null;\n  content: string | null;\n};\n\nexport type SearchResult = NoteSearchResult | LinkSearchResult;\n\n/** Default number of search results returned */\nexport const SEARCH_DEFAULT_LIMIT = 10;\n/** Maximum number of search results allowed */\nexport const SEARCH_MAX_LIMIT = 30;\n\nexport type SearchOptions = {\n  /** Max results to return (default: 10, max: 30) */\n  limit?: number;\n  /** Minimum similarity score 0-1 (default: 0.3) */\n  threshold?: number;\n  /**\n   * Scope search to this focus. Must be owned by the twist owner. When\n   * omitted, the server scopes the search across all of the owner's focuses.\n   */\n  focusId?: string;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * focuses, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate() {\n *     // Create a welcome thread\n *     await this.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       actions: [{\n *         title: \"Get Started\",\n *         type: ActionType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       focus: {\n   *         access: FocusAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Read\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n      /** When true, auto-mention this twist on new notes in threads where it authored content. */\n      defaultMention?: boolean;\n    };\n    note?: {\n      /** When true, auto-mention this twist on new notes in threads where it was @-mentioned. */\n      defaultMention?: boolean;\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Single conversational handler for mentions.\n       *\n       * When set, EVERY mention of this twist is routed directly to this\n       * handler — intent matching (and the built-in \"What can you do?\" /\n       * \"Remove yourself\" intents) is skipped. Use this to build a\n       * general-purpose conversational assistant that responds to any\n       * request, rather than classifying into a fixed set of `intents`.\n       *\n       * `handler` and `intents` are mutually exclusive; when both are\n       * present, `handler` takes precedence and `intents` is ignored.\n       *\n       * @example\n       * ```typescript\n       * note: {\n       *   defaultMention: true,\n       *   handler: this.respond, // (note: Note) => Promise<void>\n       * }\n       * ```\n       */\n      handler?: (note: Note) => Promise<void>;\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true | {\n      /** Access level for links. When omitted with `link: true`, only source channel links are accessible. */\n      access?: LinkAccess;\n    };\n    focus?: {\n      access?: FocusAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n    /** Enable semantic search across notes and links owned by the twist's user. */\n    search?: true;\n    /**\n     * When true, admin write operations (on threads/notes/links/focuses not created by this twist)\n     * require user approval via plan actions instead of executing immediately.\n     * Read operations and operations on the twist's own content still work directly.\n     */\n    requireApproval?: boolean;\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * Set `focus` to move the thread to a different focus.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateThread({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateThread({\n   *   id: \"thread-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   note: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new focus in the Plot system.\n   *\n   * Focuses serve as organizational containers for threads and twists.\n   * The created focus will be automatically assigned a unique ID.\n   *\n   * @param focus - The focus data to create\n   * @returns Promise resolving to the complete created focus\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createFocus(focus: NewFocus): Promise<Focus & { created: boolean }>;\n\n  /**\n   * Retrieves a focus by ID or key.\n   *\n   * Archived focuses are included in the results.\n   *\n   * @param focus - Focus lookup by ID or key\n   * @returns Promise resolving to the matching focus or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getFocus(\n    focus: { id: Uuid } | { key: string }\n  ): Promise<Focus | null>;\n\n  /**\n   * Updates an existing focus in the Plot system.\n   *\n   * The focus is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Focus update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateFocus(update: FocusUpdate): Promise<void>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Returns the full Actor for the user who installed this twist.\n   * Useful for per-user operations like schedule creation, or when\n   * the owner's name or email is needed.\n   */\n  abstract getOwner(): Promise<Actor>;\n\n  /**\n   * Returns the user ID (`twist_instance.owner_id`) that installed this\n   * twist. This is the same value exposed on Twist via `this.userId`.\n   */\n  abstract getUserId(): Promise<string>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n\n  /**\n   * Searches notes and links using semantic similarity.\n   *\n   * Requires `search: true` in Plot options.\n   *\n   * @param query - The search query text\n   * @param options - Optional search configuration\n   * @returns Promise resolving to array of search results ordered by similarity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;\n\n  /**\n   * Lists threads owned by the twist's user.\n   *\n   * Requires `ThreadAccess.Full`.\n   *\n   * @param options - Query options for filtering threads\n   * @returns Promise resolving to array of threads\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThreads(options?: {\n    /**\n     * Focus to list threads from. Must be owned by the twist owner.\n     * When omitted, defaults to the owner's Inbox.\n     */\n    focusId?: Uuid;\n    /** Include archived threads. Default: false. */\n    includeArchived?: boolean;\n    /** Maximum number of threads to return. Default: 50, max: 200. */\n    limit?: number;\n    /** Number of threads to skip for pagination. Default: 0. */\n    offset?: number;\n  }): Promise<Thread[]>;\n\n  /**\n   * Lists focuses owned by the twist's user.\n   *\n   * Requires `FocusAccess.Full`.\n   *\n   * @param options - Query options for filtering focuses\n   * @returns Promise resolving to array of focuses\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getFocuses(options?: {\n    /** Include archived focuses. Default: false. */\n    includeArchived?: boolean;\n  }): Promise<Focus[]>;\n\n  /**\n   * Updates a link.\n   *\n   * Requires `LinkAccess.Full`. Set `threadId` to move the link to a different thread.\n   *\n   * @param link - The link update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateLink(link: LinkUpdate): Promise<void>;\n\n  /**\n   * Creates a plan of operations for user approval.\n   *\n   * Returns an Action that can be attached to a note. The user can approve,\n   * deny, or request changes. On approval, operations are executed by the API.\n   *\n   * Requires `requireApproval: true` in Plot options.\n   *\n   * @param options - Plan configuration\n   * @returns An Action of type `plan` to attach to a note\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPlan(options: {\n    /** Human-readable title summarizing the plan */\n    title: string;\n    /** Array of operations to execute on approval */\n    operations: PlanOperation[];\n    /** Callback invoked with (action, approved: boolean) when the user responds */\n    callback: Callback;\n  }): Action;\n}\n";
+export default "import {\n  type Action,\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type LinkUpdate,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewNote,\n  type NewFocus,\n  type Note,\n  type NoteUpdate,\n  type PlanOperation,\n  type Focus,\n  type FocusUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\nimport type { Callback } from \"./callbacks\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n  /**\n   * List/query all Threads owned by the twist's user.\n   * Update any Thread (title, tags, archived, type, focus) regardless of creator.\n   * Create Notes on any Thread (not just own or mentioned).\n   * All Create permissions.\n   */\n  Full,\n}\n\nexport enum FocusAccess {\n  /**\n   * Create new Focuses for the twist owner.\n   * Update Focuses created by the twist.\n   */\n  Create,\n  /**\n   * Read all Focuses owned by the twist's user.\n   * Create new Focuses for the twist owner.\n   * Update and archive any Focus owned by the twist's user.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n}\n\nexport enum LinkAccess {\n  /** Read links on any thread owned by the twist's user. */\n  Read,\n  /** Read + update links, including moving links between threads owned by the twist's user. */\n  Full,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\ntype SearchResultBase = {\n  thread: { id: string; title: string | null };\n  focus: { id: string; title: string | null };\n  similarity: number;\n};\n\nexport type NoteSearchResult = SearchResultBase & {\n  type: 'note';\n  id: string;\n  content: string | null;\n};\n\nexport type LinkSearchResult = SearchResultBase & {\n  type: 'link';\n  id: string;\n  title: string | null;\n  sourceUrl: string | null;\n  content: string | null;\n};\n\nexport type SearchResult = NoteSearchResult | LinkSearchResult;\n\n/** Default number of search results returned */\nexport const SEARCH_DEFAULT_LIMIT = 10;\n/** Maximum number of search results allowed */\nexport const SEARCH_MAX_LIMIT = 30;\n\nexport type SearchOptions = {\n  /** Max results to return (default: 10, max: 30) */\n  limit?: number;\n  /** Minimum similarity score 0-1 (default: 0.3) */\n  threshold?: number;\n  /**\n   * Scope search to this focus. Must be owned by the twist owner. When\n   * omitted, the server scopes the search across all of the owner's focuses.\n   */\n  focusId?: string;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * focuses, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       plot: build(Plot, {\n *         thread: { access: ThreadAccess.Create },\n *       }),\n *     };\n *   }\n *\n *   async activate() {\n *     // Create a welcome thread with an opening note\n *     await this.tools.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       notes: [{\n *         content: \"Get started with Plot:\",\n *         actions: [{\n *           type: ActionType.external,\n *           title: \"Get Started\",\n *           url: \"https://plot.day/docs\"\n *         }]\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       focus: {\n   *         access: FocusAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Read\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n      /** When true, auto-mention this twist on new notes in threads where it authored content. */\n      defaultMention?: boolean;\n    };\n    note?: {\n      /** When true, auto-mention this twist on new notes in threads where it was @-mentioned. */\n      defaultMention?: boolean;\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n      /**\n       * Single conversational handler for mentions.\n       *\n       * When set, EVERY mention of this twist is routed directly to this\n       * handler — intent matching (and the built-in \"What can you do?\" /\n       * \"Remove yourself\" intents) is skipped. Use this to build a\n       * general-purpose conversational assistant that responds to any\n       * request, rather than classifying into a fixed set of `intents`.\n       *\n       * `handler` and `intents` are mutually exclusive; when both are\n       * present, `handler` takes precedence and `intents` is ignored.\n       *\n       * @example\n       * ```typescript\n       * note: {\n       *   defaultMention: true,\n       *   handler: this.respond, // (note: Note) => Promise<void>\n       * }\n       * ```\n       */\n      handler?: (note: Note) => Promise<void>;\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true | {\n      /** Access level for links. When omitted with `link: true`, only source channel links are accessible. */\n      access?: LinkAccess;\n    };\n    focus?: {\n      access?: FocusAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n    /** Enable semantic search across notes and links owned by the twist's user. */\n    search?: true;\n    /**\n     * When true, admin write operations (on threads/notes/links/focuses not created by this twist)\n     * require user approval via plan actions instead of executing immediately.\n     * Read operations and operations on the twist's own content still work directly.\n     */\n    requireApproval?: boolean;\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For the twist's own tags, use `twistTags`: a record mapping tag ID to a\n   * boolean, where true adds the tag and false removes it. Tags not included\n   * in the update remain unchanged.\n   *\n   * Set `focus` to move the thread to a different focus.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Archive a thread\n   * await this.tools.plot.updateThread({\n   *   id: threadId,\n   *   archived: true\n   * });\n   *\n   * // Add and remove the twist's tags\n   * await this.tools.plot.updateThread({\n   *   id: threadId,\n   *   twistTags: {\n   *     [Tag.Todo]: true,  // Add the to-do tag\n   *     [Tag.Done]: false  // Remove the done tag\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.tools.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   content: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.tools.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   content: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.tools.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     content: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     content: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.tools.plot.updateNote({\n   *   id: \"note-123\",\n   *   content: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.tools.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Todo]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new focus in the Plot system.\n   *\n   * Focuses serve as organizational containers for threads and twists.\n   * The created focus will be automatically assigned a unique ID.\n   *\n   * @param focus - The focus data to create\n   * @returns Promise resolving to the complete created focus\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createFocus(focus: NewFocus): Promise<Focus & { created: boolean }>;\n\n  /**\n   * Retrieves a focus by ID or key.\n   *\n   * Archived focuses are included in the results.\n   *\n   * @param focus - Focus lookup by ID or key\n   * @returns Promise resolving to the matching focus or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getFocus(\n    focus: { id: Uuid } | { key: string }\n  ): Promise<Focus | null>;\n\n  /**\n   * Updates an existing focus in the Plot system.\n   *\n   * The focus is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Focus update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateFocus(update: FocusUpdate): Promise<void>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Returns the full Actor for the user who installed this twist.\n   * Useful for per-user operations like schedule creation, or when\n   * the owner's name or email is needed.\n   */\n  abstract getOwner(): Promise<Actor>;\n\n  /**\n   * Returns the user ID (`twist_instance.owner_id`) that installed this\n   * twist. This is the same value exposed on Twist via `this.userId`.\n   */\n  abstract getUserId(): Promise<string>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.tools.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.tools.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n\n  /**\n   * Searches notes and links using semantic similarity.\n   *\n   * Requires `search: true` in Plot options.\n   *\n   * @param query - The search query text\n   * @param options - Optional search configuration\n   * @returns Promise resolving to array of search results ordered by similarity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;\n\n  /**\n   * Lists threads owned by the twist's user.\n   *\n   * Requires `ThreadAccess.Full`.\n   *\n   * @param options - Query options for filtering threads\n   * @returns Promise resolving to array of threads\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThreads(options?: {\n    /**\n     * Focus to list threads from. Must be owned by the twist owner.\n     * When omitted, defaults to the owner's Inbox.\n     */\n    focusId?: Uuid;\n    /** Include archived threads. Default: false. */\n    includeArchived?: boolean;\n    /** Maximum number of threads to return. Default: 50, max: 200. */\n    limit?: number;\n    /** Number of threads to skip for pagination. Default: 0. */\n    offset?: number;\n  }): Promise<Thread[]>;\n\n  /**\n   * Lists focuses owned by the twist's user.\n   *\n   * Requires `FocusAccess.Full`.\n   *\n   * @param options - Query options for filtering focuses\n   * @returns Promise resolving to array of focuses\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getFocuses(options?: {\n    /** Include archived focuses. Default: false. */\n    includeArchived?: boolean;\n  }): Promise<Focus[]>;\n\n  /**\n   * Updates a link.\n   *\n   * Requires `LinkAccess.Full`. Set `threadId` to move the link to a different thread.\n   *\n   * @param link - The link update containing the ID and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateLink(link: LinkUpdate): Promise<void>;\n\n  /**\n   * Creates a plan of operations for user approval.\n   *\n   * Returns an Action that can be attached to a note. The user can approve,\n   * deny, or request changes. On approval, operations are executed by the API.\n   *\n   * Requires `requireApproval: true` in Plot options.\n   *\n   * @param options - Plan configuration\n   * @returns An Action of type `plan` to attach to a note\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPlan(options: {\n    /** Human-readable title summarizing the plan */\n    title: string;\n    /** Array of operations to execute on approval */\n    operations: PlanOperation[];\n    /** Callback invoked with (action, approved: boolean) when the user responds */\n    callback: Callback;\n  }): Action;\n}\n";

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

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import { ITool } from \"..\";\n\n/** Opaque session handle returned by connect(). */\nexport type SmtpSession = string;\n\n/** Credentials and server info for connecting to an SMTP server. */\nexport type SmtpConnectOptions = {\n  /** SMTP server hostname (e.g. \"smtp.mail.me.com\") */\n  host: string;\n  /** SMTP server port (e.g. 465 for TLS, 587 for STARTTLS) */\n  port: number;\n  /** Whether to use implicit TLS (true for port 465) */\n  tls: boolean;\n  /** Whether to upgrade to TLS via STARTTLS (true for port 587) */\n  starttls: boolean;\n  /** SMTP username (typically the email address) */\n  username: string;\n  /** SMTP password (app-specific password for Apple) */\n  password: string;\n};\n\n/** An email address with optional display name. */\nexport type SmtpAddress = {\n  /** Display name (e.g. \"John Doe\") */\n  name?: string;\n  /** Email address (e.g. \"john@example.com\") */\n  address: string;\n};\n\n/** An email message to send. */\nexport type SmtpMessage = {\n  /** Sender address */\n  from: SmtpAddress;\n  /** Primary recipients */\n  to: SmtpAddress[];\n  /** Carbon copy recipients */\n  cc?: SmtpAddress[];\n  /** Blind carbon copy recipients (not visible in headers) */\n  bcc?: SmtpAddress[];\n  /** Reply-To address (if different from From) */\n  replyTo?: SmtpAddress;\n  /** Message-ID of the message being replied to (for threading) */\n  inReplyTo?: string;\n  /** Message-ID chain for threading */\n  references?: string[];\n  /** Email subject line */\n  subject: string;\n  /** Plain text body */\n  text?: string;\n  /** HTML body */\n  html?: string;\n  /** Custom Message-ID; auto-generated as <uuid@plot.day> if omitted */\n  messageId?: string;\n};\n\n/** Result of sending an email. */\nexport type SmtpSendResult = {\n  /** The Message-ID that was used (auto-generated or from SmtpMessage) */\n  messageId: string;\n  /** Email addresses that were accepted by the server */\n  accepted: string[];\n  /** Email addresses that were rejected by the server */\n  rejected: string[];\n};\n\n/**\n * Built-in tool for SMTP email sending.\n *\n * Provides high-level SMTP operations for composing and sending email.\n * Handles TCP/TLS connections, STARTTLS upgrades, SMTP protocol details,\n * and RFC 2822 message formatting internally.\n *\n * **Permission model:** Connectors declare which SMTP hosts they need access\n * to. Connections to undeclared hosts are rejected.\n *\n * @example\n * ```typescript\n * class AppleMailConnector extends Connector<AppleMailConnector> {\n *   build(build: ConnectorBuilder) {\n *     return {\n *       options: build(Options, {\n *         email: { type: \"text\", label: \"Apple ID Email\", default: \"\" },\n *         password: { type: \"text\", label: \"App-Specific Password\", secure: true, default: \"\" },\n *       }),\n *\n *       imap: build(Imap, { hosts: [\"imap.mail.me.com\"] }),\n *       smtp: build(Smtp, { hosts: [\"smtp.mail.me.com\"] }),\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async sendReply(originalMessage: ImapMessage, replyBody: string) {\n *     const session = await this.tools.smtp.connect({\n *       host: \"smtp.mail.me.com\",\n *       port: 587,\n *       tls: false,\n *       starttls: true,\n *       username: this.tools.options.email,\n *       password: this.tools.options.password,\n *     });\n *\n *     try {\n *       const result = await this.tools.smtp.send(session, {\n *         from: { address: this.tools.options.email },\n *         to: originalMessage.from ?? [],\n *         subject: `Re: ${originalMessage.subject ?? \"(no subject)\"}`,\n *         text: replyBody,\n *         inReplyTo: originalMessage.messageId,\n *         references: [\n *           ...(originalMessage.references ?? []),\n *           ...(originalMessage.messageId ? [originalMessage.messageId] : []),\n *         ],\n *       });\n *\n *       console.log(`Sent reply, Message-ID: ${result.messageId}`);\n *     } finally {\n *       await this.tools.smtp.disconnect(session);\n *     }\n *   }\n * }\n * ```\n */\nexport abstract class Smtp extends ITool {\n  static readonly Options: {\n    /** SMTP server hostnames this tool is allowed to connect to. */\n    hosts: string[];\n  };\n\n  /**\n   * Opens a connection to an SMTP server and authenticates.\n   *\n   * Handles the full SMTP handshake: greeting, EHLO, optional STARTTLS\n   * upgrade, and AUTH LOGIN authentication.\n   *\n   * @param options - Server address, port, TLS/STARTTLS setting, and credentials\n   * @returns An opaque session handle for subsequent operations\n   * @throws If the host is not in the declared hosts list, connection fails, or auth fails\n   */\n  abstract connect(options: SmtpConnectOptions): Promise<SmtpSession>;\n\n  /**\n   * Sends an email message.\n   *\n   * Constructs a properly formatted RFC 2822 message with MIME support\n   * and sends it via the SMTP protocol. Handles multipart messages when\n   * both text and HTML bodies are provided.\n   *\n   * @param session - Session handle from connect()\n   * @param message - The email message to send\n   * @returns Send result with Message-ID and per-recipient acceptance status\n   * @throws If the session is invalid or the server rejects the message entirely\n   */\n  abstract send(\n    session: SmtpSession,\n    message: SmtpMessage\n  ): Promise<SmtpSendResult>;\n\n  /**\n   * Closes the SMTP connection.\n   *\n   * Always call this when done, preferably in a finally block.\n   *\n   * @param session - Session handle from connect()\n   */\n  abstract disconnect(session: SmtpSession): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\n\n/** Opaque session handle returned by connect(). */\nexport type SmtpSession = string;\n\n/** Credentials and server info for connecting to an SMTP server. */\nexport type SmtpConnectOptions = {\n  /** SMTP server hostname (e.g. \"smtp.mail.me.com\") */\n  host: string;\n  /** SMTP server port (e.g. 465 for TLS, 587 for STARTTLS) */\n  port: number;\n  /** Whether to use implicit TLS (true for port 465) */\n  tls: boolean;\n  /** Whether to upgrade to TLS via STARTTLS (true for port 587) */\n  starttls: boolean;\n  /** SMTP username (typically the email address) */\n  username: string;\n  /** SMTP password (app-specific password for Apple) */\n  password: string;\n};\n\n/** An email address with optional display name. */\nexport type SmtpAddress = {\n  /** Display name (e.g. \"John Doe\") */\n  name?: string;\n  /** Email address (e.g. \"john@example.com\") */\n  address: string;\n};\n\n/** An email message to send. */\nexport type SmtpMessage = {\n  /** Sender address */\n  from: SmtpAddress;\n  /** Primary recipients */\n  to: SmtpAddress[];\n  /** Carbon copy recipients */\n  cc?: SmtpAddress[];\n  /** Blind carbon copy recipients (not visible in headers) */\n  bcc?: SmtpAddress[];\n  /** Reply-To address (if different from From) */\n  replyTo?: SmtpAddress;\n  /** Message-ID of the message being replied to (for threading) */\n  inReplyTo?: string;\n  /** Message-ID chain for threading */\n  references?: string[];\n  /** Email subject line */\n  subject: string;\n  /** Plain text body */\n  text?: string;\n  /** HTML body */\n  html?: string;\n  /** Custom Message-ID; auto-generated as <uuid@plot.day> if omitted */\n  messageId?: string;\n};\n\n/** Result of sending an email. */\nexport type SmtpSendResult = {\n  /** The Message-ID that was used (auto-generated or from SmtpMessage) */\n  messageId: string;\n  /** Email addresses that were accepted by the server */\n  accepted: string[];\n  /** Email addresses that were rejected by the server */\n  rejected: string[];\n};\n\n/**\n * Built-in tool for SMTP email sending.\n *\n * Provides high-level SMTP operations for composing and sending email.\n * Handles TCP/TLS connections, STARTTLS upgrades, SMTP protocol details,\n * and RFC 2822 message formatting internally.\n *\n * **Permission model:** Connectors declare which SMTP hosts they need access\n * to. Connections to undeclared hosts are rejected.\n *\n * @example\n * ```typescript\n * class AppleMailConnector extends Connector<AppleMailConnector> {\n *   build(build: ToolBuilder) {\n *     return {\n *       options: build(Options, {\n *         email: { type: \"text\", label: \"Apple ID Email\", default: \"\" },\n *         password: { type: \"text\", label: \"App-Specific Password\", secure: true, default: \"\" },\n *       }),\n *\n *       imap: build(Imap, { hosts: [\"imap.mail.me.com\"] }),\n *       smtp: build(Smtp, { hosts: [\"smtp.mail.me.com\"] }),\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async sendReply(originalMessage: ImapMessage, replyBody: string) {\n *     const session = await this.tools.smtp.connect({\n *       host: \"smtp.mail.me.com\",\n *       port: 587,\n *       tls: false,\n *       starttls: true,\n *       username: this.tools.options.email,\n *       password: this.tools.options.password,\n *     });\n *\n *     try {\n *       const result = await this.tools.smtp.send(session, {\n *         from: { address: this.tools.options.email },\n *         to: originalMessage.from ?? [],\n *         subject: `Re: ${originalMessage.subject ?? \"(no subject)\"}`,\n *         text: replyBody,\n *         inReplyTo: originalMessage.messageId,\n *         references: [\n *           ...(originalMessage.references ?? []),\n *           ...(originalMessage.messageId ? [originalMessage.messageId] : []),\n *         ],\n *       });\n *\n *       console.log(`Sent reply, Message-ID: ${result.messageId}`);\n *     } finally {\n *       await this.tools.smtp.disconnect(session);\n *     }\n *   }\n * }\n * ```\n */\nexport abstract class Smtp extends ITool {\n  static readonly Options: {\n    /** SMTP server hostnames this tool is allowed to connect to. */\n    hosts: string[];\n  };\n\n  /**\n   * Opens a connection to an SMTP server and authenticates.\n   *\n   * Handles the full SMTP handshake: greeting, EHLO, optional STARTTLS\n   * upgrade, and AUTH LOGIN authentication.\n   *\n   * @param options - Server address, port, TLS/STARTTLS setting, and credentials\n   * @returns An opaque session handle for subsequent operations\n   * @throws If the host is not in the declared hosts list, connection fails, or auth fails\n   */\n  abstract connect(options: SmtpConnectOptions): Promise<SmtpSession>;\n\n  /**\n   * Sends an email message.\n   *\n   * Constructs a properly formatted RFC 2822 message with MIME support\n   * and sends it via the SMTP protocol. Handles multipart messages when\n   * both text and HTML bodies are provided.\n   *\n   * @param session - Session handle from connect()\n   * @param message - The email message to send\n   * @returns Send result with Message-ID and per-recipient acceptance status\n   * @throws If the session is invalid or the server rejects the message entirely\n   */\n  abstract send(\n    session: SmtpSession,\n    message: SmtpMessage\n  ): Promise<SmtpSendResult>;\n\n  /**\n   * Closes the SMTP connection.\n   *\n   * Always call this when done, preferably in a finally block.\n   *\n   * @param session - Session handle from connect()\n   */\n  abstract disconnect(session: SmtpSession): Promise<void>;\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 {\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(\"processBatch\", { batchNumber: 1 });\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(args: any, context: { 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(\"processBatch\", {\n *         batchNumber: context.batchNumber + 1\n *       });\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(\"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(\"syncBatch\", { page: 1 });\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport type { Callback } from \"./callbacks\";\n\n/**\n * Run background tasks and scheduled jobs.\n *\n * The Tasks tool enables twists and tools to queue callbacks for execution in separate\n * worker contexts. **This is critical for staying under request limits**: each execution\n * has a limit of ~1000 requests (HTTP requests, tool calls, database operations), and\n * running a task creates a NEW execution with a fresh request limit.\n *\n * **Key distinction:**\n * - **Calling a callback** (via `this.run()`) continues the same execution and shares the request count\n * - **Running a task** (via `this.runTask()`) creates a NEW execution with fresh ~1000 request limit\n *\n * **When to use tasks:**\n * - Processing large datasets that would exceed 1000 requests\n * - Breaking loops into chunks where each chunk stays under the request limit\n * - Scheduling operations for future execution\n *\n * **Note:** Tasks tool methods are also available directly on Twist and Tool classes\n * via `this.runTask()`, `this.cancelTask()`, and `this.cancelAllTasks()`.\n * This is the recommended approach for most use cases.\n *\n * **Best Practices:**\n * - Size batches to stay under ~1000 requests per execution\n * - Calculate requests per item to determine safe batch size\n * - Create callbacks first using `this.callback()`\n * - Store intermediate state using the Store tool\n *\n * @example\n * ```typescript\n * class SyncTool extends Tool<SyncTool> {\n *   async startBatchSync(totalItems: number) {\n *     // Store initial state using built-in set method\n *     await this.set(\"sync_progress\", { processed: 0, total: totalItems });\n *\n *     // Create callback and queue first batch\n *     const callback = await this.callback(this.processBatch, 1);\n *     // runTask creates NEW execution with fresh ~1000 request limit\n *     await this.runTask(callback);\n *   }\n *\n *   async processBatch(batchNumber: number) {\n *     // Process one batch of items (sized to stay under request limit)\n *     const progress = await this.get(\"sync_progress\");\n *\n *     // If each item makes ~10 requests, process ~100 items per batch\n *     // 100 items × 10 requests = 1000 requests (at limit)\n *     const batchSize = 100;\n *     const items = await this.fetchItems(progress.processed, batchSize);\n *\n *     for (const item of items) {\n *       await this.processItem(item); // Makes ~10 requests per item\n *     }\n *\n *     await this.set(\"sync_progress\", {\n *       processed: progress.processed + batchSize,\n *       total: progress.total\n *     });\n *\n *     if (progress.processed < progress.total) {\n *       // Queue next batch - creates NEW execution with fresh request limit\n *       const callback = await this.callback(this.processBatch, batchNumber + 1);\n *       await this.runTask(callback);\n *     }\n *   }\n *\n *   async scheduleCleanup() {\n *     const tomorrow = new Date();\n *     tomorrow.setDate(tomorrow.getDate() + 1);\n *\n *     const callback = await this.callback(this.cleanupOldData);\n *     // Schedule for future execution\n *     return await this.runTask(callback, { runAt: tomorrow });\n *   }\n * }\n * ```\n */\nexport abstract class Tasks extends ITool {\n  /**\n   * Queues a callback to execute in a separate worker context with a fresh request limit.\n   *\n   * **Creates a NEW execution** with its own request limit of ~1000 requests (HTTP requests,\n   * tool calls, database operations). This is the primary way to stay under request limits\n   * when processing large datasets or making many API calls.\n   *\n   * The callback will be invoked either immediately or at a scheduled time\n   * in an isolated execution environment. Each execution has ~1000 requests and ~60 seconds\n   * CPU time. Use this for breaking loops into chunks that stay under the request limit.\n   *\n   * **Key distinction:**\n   * - `this.run(callback)` - Continues same execution, shares request count\n   * - `this.runTask(callback)` - NEW execution, fresh request limit\n   *\n   * @param callback - Callback created with `this.callback()`\n   * @param options - Optional configuration for the execution\n   * @param options.runAt - If provided, schedules execution at this time; otherwise runs immediately\n   * @returns Promise resolving to a cancellation token (only for scheduled executions)\n   *\n   * @example\n   * ```typescript\n   * // Break large loop into batches to stay under request limit\n   * const callback = await this.callback(this.syncBatch, 1);\n   * await this.runTask(callback); // Fresh execution with ~1000 requests\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract runTask(\n    callback: Callback,\n    options?: { runAt?: Date }\n  ): Promise<string | void>;\n\n  /**\n   * Cancels a previously scheduled execution.\n   *\n   * Prevents a scheduled function from executing. No error is thrown\n   * if the token is invalid or the execution has already completed.\n   *\n   * @param token - The cancellation token returned by runTask() with runAt option\n   * @returns Promise that resolves when the cancellation is processed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract cancelTask(token: string): Promise<void>;\n\n  /**\n   * Cancels all scheduled executions for this tool/twist.\n   *\n   * Cancels all pending scheduled executions created by this tool or twist\n   * instance. Immediate executions cannot be cancelled.\n   *\n   * @returns Promise that resolves when all cancellations are processed\n   */\n  abstract cancelAllTasks(): Promise<void>;\n}\n";

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

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import { type Callback, ITool } from \"..\";\n\n/**\n * Twist source code structure containing dependencies and source files.\n */\nexport interface TwistSource {\n  /**\n   * Package dependencies with version specifiers\n   * @example { \"@plotday/twister\": \"workspace:^\", \"@plotday/tool-google-calendar\": \"^1.0.0\" }\n   */\n  dependencies: Record<string, string>;\n\n  /**\n   * Source files with their content\n   * Must include \"index.ts\" as the entry point\n   * @example { \"index.ts\": \"export default class MyTwist extends Twist {...}\" }\n   */\n  files: Record<string, string>;\n}\n\n/**\n * Represents a log entry from a twist execution.\n */\nexport type Log = {\n  timestamp: Date;\n  environment: \"personal\" | \"private\" | \"review\" | \"public\";\n  severity: \"log\" | \"error\" | \"warn\" | \"info\";\n  message: string;\n};\n\n/**\n * Twist permissions returned after deployment.\n * Nested structure mapping domains to entities to permission flags.\n *\n * Format: { domain: { entity: flags[] } }\n * - domain: Tool name (e.g., \"network\", \"plot\")\n * - entity: Domain-specific identifier (e.g., URL pattern, resource type)\n * - flags: Array of permission flags (\"read\", \"write\", \"update\", \"use\")\n *\n * @example\n * ```typescript\n * {\n *   \"network\": {\n *     \"https://api.example.com/*\": [\"use\"],\n *     \"https://googleapis.com/*\": [\"use\"]\n *   },\n *   \"plot\": {\n *     \"thread:mentioned\": [\"read\", \"write\", \"update\"],\n *     \"focus\": [\"read\", \"write\", \"update\"]\n *   }\n * }\n * ```\n */\nexport type TwistPermissions = Record<string, Record<string, string[]>>;\n\n/**\n * Built-in tool for managing twists and deployments.\n *\n * The Twists tool provides twists with the ability to create twist IDs\n * and programmatically deploy twists.\n *\n * @example\n * ```typescript\n * class TwistBuilderTwist extends Twist {\n *   build(build: ToolBuilder) {\n *    return {\n *      twists: build.get(Twists)\n *    }\n *   }\n *\n *   async activate() {\n *     const twistId = await this.tools.twists.create();\n *     // Display twist ID to user\n *   }\n * }\n * ```\n */\nexport abstract class Twists extends ITool {\n  /**\n   * Creates a new twist ID and grants access to people in the current focus.\n   *\n   * @returns Promise resolving to the generated twist ID\n   * @throws When twist creation fails\n   *\n   * @example\n   * ```typescript\n   * const twistId = await twist.create();\n   * console.log(`Your twist ID: ${twistId}`);\n   * ```\n   */\n  abstract create(): Promise<string>;\n\n  /**\n   * Generates twist source code from a specification using AI.\n   *\n   * This method uses Claude AI to generate TypeScript source code and dependencies\n   * from a markdown specification. The generated source is validated by attempting\n   * to build it, with iterative error correction (up to 3 attempts).\n   *\n   * @param spec - Markdown specification describing the twist functionality\n   * @returns Promise resolving to twist source (dependencies and files)\n   * @throws When generation fails after maximum attempts\n   *\n   * @example\n   * ```typescript\n   * const source = await twist.generate(`\n   * # Calendar Sync Twist\n   *\n   * This twist syncs Google Calendar events to Plot activities.\n   *\n   * ## Features\n   * - Authenticate with Google\n   * - Sync calendar events\n   * - Create activities from events\n   * `);\n   *\n   * // source.dependencies: { \"@plotday/twister\": \"workspace:^\", ... }\n   * // source.files: { \"index.ts\": \"export default class...\" }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract generate(spec: string): Promise<TwistSource>;\n\n  /**\n   * Deploys a twist programmatically.\n   *\n   * This method provides the same functionality as the plot deploy CLI\n   * command, but can be called from within a twist. Accepts either:\n   * - A pre-bundled module (JavaScript code)\n   * - A source object (dependencies + files) which is built in a sandbox\n   *\n   * @param options - Deployment configuration\n   * @param options.twistId - Twist ID for deployment\n   * @param options.module - Pre-bundled twist module code (mutually exclusive with source)\n   * @param options.source - Twist source code with dependencies (mutually exclusive with module)\n   * @param options.environment - Target environment (defaults to \"personal\")\n   * @param options.name - Optional twist name (required for first deploy)\n   * @param options.description - Optional twist description (required for first deploy)\n   * @param options.dryRun - If true, validates without deploying (returns errors if any)\n   * @returns Promise resolving to deployment result with version and optional errors\n   * @throws When deployment fails or user lacks access\n   *\n   * @example\n   * ```typescript\n   * // Deploy with a module\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   module: 'export default class MyTwist extends Twist {...}',\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   *   description: 'Does something cool'\n   * });\n   * console.log(`Deployed version ${result.version}`);\n   *\n   * // Deploy with source\n   * const source = await twist.generate(spec);\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   * });\n   *\n   * // Validate with dryRun\n   * const result = await twist.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   dryRun: true,\n   * });\n   * if (result.errors?.length) {\n   *   console.error('Build errors:', result.errors);\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract deploy(\n    options: {\n      twistId: string;\n      environment?: \"personal\" | \"private\" | \"review\";\n      name?: string;\n      description?: string;\n      dryRun?: boolean;\n    } & (\n      | {\n          module: string;\n        }\n      | {\n          source: TwistSource;\n        }\n    )\n  ): Promise<{\n    version: string;\n    permissions: TwistPermissions;\n    errors?: string[];\n  }>;\n\n  /**\n   * Subscribes to logs from a twist.\n   *\n   * This method registers a callback to receive batches of logs from twist executions.\n   * The callback will be invoked with an array of logs whenever new logs are captured\n   * from the twist's console output.\n   *\n   * @param twistId - Twist ID (root ID) to watch logs for\n   * @param callback - Callback token created via CallbackTool that will receive log batches\n   * @returns Promise that resolves when the subscription is created\n   * @throws When subscription fails\n   *\n   * @example\n   * ```typescript\n   * // Create twist and callback\n   * const twistId = await this.twist.create();\n   * const callback = await this.callback.create(\"onLogs\");\n   *\n   * // Subscribe to logs\n   * await this.twist.watchLogs(twistId, callback);\n   *\n   * // Implement handler\n   * async onLogs(logs: Log[]) {\n   *   for (const log of logs) {\n   *     console.log(`[${log.environment}] ${log.severity}: ${log.message}`);\n   *   }\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract watchLogs(twistId: string, callback: Callback): Promise<void>;\n}\n";
+export default "import { type Callback, ITool } from \"..\";\n\n/**\n * Twist source code structure containing dependencies and source files.\n */\nexport interface TwistSource {\n  /**\n   * Package dependencies with version specifiers\n   * @example { \"@plotday/twister\": \"workspace:^\", \"@plotday/tool-google-calendar\": \"^1.0.0\" }\n   */\n  dependencies: Record<string, string>;\n\n  /**\n   * Source files with their content\n   * Must include \"index.ts\" as the entry point\n   * @example { \"index.ts\": \"export default class MyTwist extends Twist {...}\" }\n   */\n  files: Record<string, string>;\n}\n\n/**\n * Represents a log entry from a twist execution.\n */\nexport type Log = {\n  timestamp: Date;\n  environment: \"personal\" | \"private\" | \"review\" | \"public\";\n  severity: \"log\" | \"error\" | \"warn\" | \"info\";\n  message: string;\n};\n\n/**\n * Twist permissions returned after deployment.\n * Nested structure mapping domains to entities to permission flags.\n *\n * Format: { domain: { entity: flags[] } }\n * - domain: Tool name (e.g., \"network\", \"plot\")\n * - entity: Domain-specific identifier (e.g., URL pattern, resource type)\n * - flags: Array of permission flags (\"read\", \"write\", \"update\", \"use\")\n *\n * @example\n * ```typescript\n * {\n *   \"network\": {\n *     \"https://api.example.com/*\": [\"use\"],\n *     \"https://googleapis.com/*\": [\"use\"]\n *   },\n *   \"plot\": {\n *     \"thread:mentioned\": [\"read\", \"write\", \"update\"],\n *     \"focus\": [\"read\", \"write\", \"update\"]\n *   }\n * }\n * ```\n */\nexport type TwistPermissions = Record<string, Record<string, string[]>>;\n\n/**\n * Built-in tool for managing twists and deployments.\n *\n * The Twists tool provides twists with the ability to create twist IDs\n * and programmatically deploy twists.\n *\n * @example\n * ```typescript\n * class TwistBuilderTwist extends Twist<TwistBuilderTwist> {\n *   build(build: ToolBuilder) {\n *    return {\n *      twists: build(Twists)\n *    }\n *   }\n *\n *   async activate() {\n *     const twistId = await this.tools.twists.create();\n *     // Display twist ID to user\n *   }\n * }\n * ```\n */\nexport abstract class Twists extends ITool {\n  /**\n   * Creates a new twist package ID. Ownership of the ID is claimed lazily\n   * on first deploy — no upfront registration happens beyond generating it.\n   *\n   * @returns Promise resolving to the generated twist ID\n   * @throws When twist creation fails\n   *\n   * @example\n   * ```typescript\n   * const twistId = await this.tools.twists.create();\n   * console.log(`Your twist ID: ${twistId}`);\n   * ```\n   */\n  abstract create(): Promise<string>;\n\n  /**\n   * Generates twist source code from a specification using AI.\n   *\n   * This method uses Claude AI to generate TypeScript source code and dependencies\n   * from a markdown specification. The generated source is validated by attempting\n   * to build it, with iterative error correction (up to 3 attempts).\n   *\n   * @param spec - Markdown specification describing the twist functionality\n   * @returns Promise resolving to twist source (dependencies and files)\n   * @throws When generation fails after maximum attempts\n   *\n   * @example\n   * ```typescript\n   * const source = await this.tools.twists.generate(`\n   * # Calendar Sync Twist\n   *\n   * This twist syncs Google Calendar events to Plot threads.\n   *\n   * ## Features\n   * - Authenticate with Google\n   * - Sync calendar events\n   * - Create threads from events\n   * `);\n   *\n   * // source.dependencies: { \"@plotday/twister\": \"workspace:^\", ... }\n   * // source.files: { \"index.ts\": \"export default class...\" }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract generate(spec: string): Promise<TwistSource>;\n\n  /**\n   * Deploys a twist programmatically.\n   *\n   * This method provides the same functionality as the plot deploy CLI\n   * command, but can be called from within a twist. Accepts either:\n   * - A pre-bundled module (JavaScript code)\n   * - A source object (dependencies + files) which is built in a sandbox\n   *\n   * @param options - Deployment configuration\n   * @param options.twistId - Twist ID for deployment\n   * @param options.module - Pre-bundled twist module code (mutually exclusive with source)\n   * @param options.source - Twist source code with dependencies (mutually exclusive with module)\n   * @param options.environment - Target environment (defaults to \"personal\")\n   * @param options.name - Optional twist name (required for first deploy)\n   * @param options.description - Optional twist description (required for first deploy)\n   * @param options.dryRun - If true, validates without deploying (returns errors if any)\n   * @returns Promise resolving to deployment result with version and optional errors\n   * @throws When deployment fails or user lacks access\n   *\n   * @example\n   * ```typescript\n   * // Deploy with a module\n   * const result = await this.tools.twists.deploy({\n   *   twistId: 'abc-123-...',\n   *   module: 'export default class MyTwist extends Twist {...}',\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   *   description: 'Does something cool'\n   * });\n   * console.log(`Deployed version ${result.version}`);\n   *\n   * // Deploy with source\n   * const source = await this.tools.twists.generate(spec);\n   * const result = await this.tools.twists.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   environment: 'personal',\n   *   name: 'My Twist',\n   * });\n   *\n   * // Validate with dryRun\n   * const result = await this.tools.twists.deploy({\n   *   twistId: 'abc-123-...',\n   *   source,\n   *   dryRun: true,\n   * });\n   * if (result.errors?.length) {\n   *   console.error('Build errors:', result.errors);\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract deploy(\n    options: {\n      twistId: string;\n      environment?: \"personal\" | \"private\" | \"review\";\n      name?: string;\n      description?: string;\n      dryRun?: boolean;\n    } & (\n      | {\n          module: string;\n        }\n      | {\n          source: TwistSource;\n        }\n    )\n  ): Promise<{\n    version: string;\n    permissions: TwistPermissions;\n    errors?: string[];\n  }>;\n\n  /**\n   * Subscribes to logs from a twist.\n   *\n   * This method registers a callback to receive batches of logs from twist executions.\n   * The callback will be invoked with an array of logs whenever new logs are captured\n   * from the twist's console output.\n   *\n   * @param twistId - Twist ID (root ID) to watch logs for\n   * @param callback - Callback token created via CallbackTool that will receive log batches\n   * @returns Promise that resolves when the subscription is created\n   * @throws When subscription fails\n   *\n   * @example\n   * ```typescript\n   * // Create twist and callback\n   * const twistId = await this.tools.twists.create();\n   * const callback = await this.callback(this.onLogs);\n   *\n   * // Subscribe to logs\n   * await this.tools.twists.watchLogs(twistId, callback);\n   *\n   * // Implement handler\n   * async onLogs(logs: Log[]) {\n   *   for (const log of logs) {\n   *     console.log(`[${log.environment}] ${log.severity}: ${log.message}`);\n   *   }\n   * }\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract watchLogs(twistId: string, callback: Callback): Promise<void>;\n}\n";

package/src/llm-docs/twist-guide-template.ts

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