@plotday/twister 0.55.0 → 0.56.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  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 * 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    /** 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  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/**\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   * 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\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\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   * 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 * 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";

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   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Pub/Sub** (`pubsub: true`): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   Use this for services that deliver events via Pub/Sub (e.g., Google Workspace Events API).\n   *   A Pub/Sub topic and push subscription are created automatically; the returned topic name\n   *   can be passed to any Google API that accepts a Pub/Sub notification endpoint.\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 and Gmail)\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 Gmail/Pub/Sub, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Pub/Sub webhook for Workspace Events API\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: true },\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 - auto-detected from scopes, returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook(\n   *   {},\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      /** When true, creates a Google Pub/Sub topic instead of a webhook URL. */\n      pubsub?: boolean;\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 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";

package/src/plot.ts

@@ -788,6 +788,16 @@ export type NewNote = Partial<
      * - `undefined` (omitted): not a reply
      */
     reNote?: { id: Uuid } | { key: string } | null;
+
+    /**
+     * A link carried by this note (note-attached, NOT a thread-level canonical
+     * link). Use for augmenter content (e.g. Granola meeting notes) that should
+     * attach to an existing canonical thread without becoming its primary link.
+     * The runtime creates the link note-scoped, binds `note.link_id` to it, and
+     * — when `thread: { source }` resolves to no existing thread — find-or-creates
+     * the thread by that source so a later canonical sync can fill the primary.
+     */
+    link?: NewLink;
   };
 
 /**
@@ -1025,6 +1035,12 @@ export type Link = {
    * meeting-notes connector can bundle by setting the same alias.
    */
   sources: string[];
+  /**
+   * Connector-supplied ranking used by clients to choose the single displayed
+   * (primary) canonical link when a thread has more than one. Higher wins;
+   * ties break on earliest creation. Default 0.
+   */
+  priority: number;
 };
 
 /**
@@ -1082,12 +1098,36 @@ export type NewLink = Partial<
      * - undefined (default): Preserve current archive state
      */
     archived?: boolean;
+    /**
+     * Mark the thread as the connection owner's to-do at create time.
+     * - true: the thread is added to the owner's to-do (active) bucket and
+     *   their per-user archive is lifted, atomically with the save — no
+     *   separate `integrations.setThreadToDo()` round-trip needed.
+     * - false: the owner's thread_state is marked read (cleared from to-do).
+     * - undefined (omitted, default): leave to-do state untouched.
+     *
+     * Use for messaging-style "saved for later" flags (e.g. a starred Slack
+     * thread). This is the first-class replacement for overloading a
+     * `statuses[]` entry with `active: true`.
+     */
+    todo?: boolean;
+    /**
+     * The to-do date used when `todo` is true. Defaults to the "Now"
+     * sentinel (today's bucket) when omitted. Ignored when `todo` is not true.
+     */
+    todoDate?: Date | string;
     /**
      * Explicit focus (disables automatic focus matching).
      * Only used when the link creates a new thread. When omitted, the
      * server classifies the thread using the user's focus rules.
      */
     focus?: Pick<Focus, "id">;
+    /**
+     * Primary-link ranking for this canonical link (default 0). Set higher on
+     * the connection that "owns" the external item (e.g. the calendar that owns
+     * an event vs a subscribed copy) so clients display it as the primary.
+     */
+    priority?: number;
   };
 
 /**
@@ -1109,6 +1149,25 @@ export type NewLinkWithNotes = NewLink & {
   schedules?: Array<Omit<NewSchedule, "threadId">>;
   /** Schedule occurrence overrides */
   scheduleOccurrences?: NewScheduleOccurrence[];
+  /**
+   * For `onCreateLink` only: binds the thread's opening note (the message the
+   * user composed in Plot, which this hook just posted to the external system)
+   * to its external counterpart. Mirrors the `NoteWriteBackResult` a reply
+   * returns from `onNoteCreated` — `key` is the external message id and
+   * `externalContent` is the post-write content baseline. Without this the
+   * opening note stays keyless, so reactions and edits on it can't be routed
+   * back to the external system. Ignored outside `onCreateLink`.
+   */
+  originatingNote?: {
+    /** External message id; set as the opening note's `key`. */
+    key?: string;
+    /**
+     * Content as the external system stored it post-write, for the sync
+     * baseline. Must equal what your sync-in path emits as this note's
+     * `content` on re-ingest (same contract as `NoteWriteBackResult.externalContent`).
+     */
+    externalContent?: string;
+  };
 };
 
 /**

package/src/tools/integrations.ts

@@ -43,6 +43,21 @@ export type Channel = {
   linkTypes?: LinkTypeConfig[];
 };
 
+/**
+ * Curated status-icon vocabulary. Connectors map each declared status to the
+ * closest icon; clients render a single glyph per value. Required on every
+ * status so the UI always has something to show.
+ */
+export type StatusIcon =
+  | "backlog"
+  | "todo"
+  | "inProgress"
+  | "blocked"
+  | "done"
+  | "cancelled"
+  | "confirmed"
+  | "tentative";
+
 /**
  * Describes a link type that a connector creates.
  * Used for display in the UI (icons, labels).
@@ -93,6 +108,14 @@ export type LinkTypeConfig = {
     status: string;
     /** Human-readable label (e.g., "Open", "Done") */
     label: string;
+    /** Curated icon for this status (required so the UI always has a glyph). */
+    icon: StatusIcon;
+    /**
+     * Suppress this status's icon on the feed row (ThreadWidget) while still
+     * showing it in the ThreadPage header. Use for a "resting" default state
+     * that would otherwise clutter the feed (e.g. calendar "Confirmed").
+     */
+    hiddenDefault?: boolean;
     /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */
     done?: boolean;
     /**
@@ -227,8 +250,11 @@ export type ComposeConfig = {
    * `onCreateLink` resolves itself (e.g. Linear's `"unstarted"` category is
    * resolved per-team to a state UUID inside the connector — see
    * `connectors/linear/src/linear.ts`).
+   *
+   * Omit for status-less link types (e.g. messaging connectors that don't
+   * model a status): composed links are created with no status.
    */
-  status: string;
+  status?: string;
   /**
    * Optional override for the picker chip / "Create new …" copy. Defaults
    * to the parent linkType's `label`. Use to disambiguate compose entries
@@ -297,6 +323,22 @@ export type SyncContext = {
    * overwrites stored state rather than appending to it.
    */
   recovering?: boolean;
+
+  /**
+   * True when the channel is being observed because the user composed a Plot
+   * thread INTO it (via `onCreateLink`), not because they explicitly enabled
+   * it. The connector should register webhooks / mark the channel observed so
+   * inbound events (replies, reactions) on the composed thread sync back —
+   * but must NOT backfill history. Only go-forward events matter; pulling the
+   * channel's existing content would be surprising for a channel the user
+   * only posted one thread into.
+   *
+   * Connectors whose `onChannelEnabled` already skips historical backfill can
+   * ignore this flag. Connectors that initial-sync on enable MUST short-
+   * circuit that backfill when `observeOnly` is true (still set up webhooks
+   * and any go-forward state).
+   */
+  observeOnly?: boolean;
 };
 
 /**
@@ -499,6 +541,15 @@ export abstract class Integrations extends ITool {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract markNeedsReauth(channelId: string): Promise<void>;
 
+  /**
+   * Upsert workspace custom emoji into Plot's shared cache so reactions using
+   * `provider:workspace/name` refs render as images and round-trip. Idempotent;
+   * keyed on `id`. Pass `archived: true` to mark an emoji removed. Workspace-
+   * scoped (shared across all users of that workspace).
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  abstract saveCustomEmoji(emoji: NewCustomEmoji[]): Promise<void>;
+
 }
 
 /**
@@ -516,6 +567,28 @@ export type ArchiveLinkFilter = {
   meta?: Record<string, JSONValue>;
 };
 
+/**
+ * A workspace custom emoji to cache so Plot can render and round-trip it as a
+ * reaction. `id` is the provider-scoped ref stored on reactions, of the form
+ * `<provider>:<workspace>/<name>` (e.g. `slack:T0123ABC/party_parrot`).
+ */
+export type NewCustomEmoji = {
+  /** Provider-scoped ref: `<provider>:<workspace>/<name>`. The reaction value. */
+  id: string;
+  /** e.g. "slack". */
+  provider: string;
+  /** Provider workspace/team id (e.g. Slack team id `T0123ABC`). */
+  workspace: string;
+  /** Bare emoji name without colons (e.g. "party_parrot"). */
+  name: string;
+  /** Image URL to render, or null for an alias (see `aliasOf`). */
+  imageUrl: string | null;
+  /** When this emoji aliases another, the target ref (`id` of the canonical emoji); else null. */
+  aliasOf: string | null;
+  /** True to mark the emoji removed (archive it) rather than upsert it. */
+  archived: boolean;
+};
+
 /**
  * Enumeration of supported OAuth providers.
  *

package/src/tools/network.ts

@@ -133,27 +133,27 @@ export abstract class Network extends ITool {
    *
    * **Provider-Specific Behavior:**
    * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.
-   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.
-   *   The topic name (e.g., "projects/plot-prod/topics/gmail-webhook-abc123") should be passed
-   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.
-   * - **Pub/Sub** (`pubsub: true`): Returns a Google Pub/Sub topic name instead of a webhook URL.
-   *   Use this for services that deliver events via Pub/Sub (e.g., Google Workspace Events API).
-   *   A Pub/Sub topic and push subscription are created automatically; the returned topic name
-   *   can be passed to any Google API that accepts a Pub/Sub notification endpoint.
+   * - **Pub/Sub** (`pubsub: "gmail" | "workspace"`): Returns a Google Pub/Sub topic name instead
+   *   of a webhook URL. `"gmail"` targets Gmail `users.watch` (set this only on the Gmail
+   *   connector); `"workspace"` targets Google Workspace Events (Chat, etc.). A Pub/Sub topic and
+   *   push subscription are created automatically; the returned topic name (e.g.
+   *   "projects/plot-prod/topics/gmail-abc123") is passed to the relevant Google API. Other Google
+   *   connectors (Calendar, Drive) omit `pubsub` and use the default HTTPS webhook.
    * - **Default**: Returns a standard webhook URL for all other cases.
    *
    * @param options - Webhook creation options
    * @param options.provider - Optional provider for provider-specific webhook routing
-   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)
+   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack)
+   * @param options.pubsub - Optional Google Pub/Sub push product ("gmail" | "workspace")
    * @param callback - Function receiving (request, ...extraArgs)
    * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
-   * @returns Promise resolving to the webhook URL, or for Gmail/Pub/Sub, a Pub/Sub topic name
+   * @returns Promise resolving to the webhook URL, or for Pub/Sub, a Pub/Sub topic name
    *
    * @example
    * ```typescript
-   * // Pub/Sub webhook for Workspace Events API
+   * // Pub/Sub webhook for Workspace Events API (Chat, etc.)
    * const topicName = await this.tools.network.createWebhook(
-   *   { pubsub: true },
+   *   { pubsub: "workspace" },
    *   this.onEventReceived,
    *   channelId
    * );
@@ -165,9 +165,9 @@ export abstract class Network extends ITool {
    *
    * @example
    * ```typescript
-   * // Gmail webhook - auto-detected from scopes, returns Pub/Sub topic name
+   * // Gmail webhook - returns a Gmail Pub/Sub topic name for users.watch
    * const topicName = await this.tools.network.createWebhook(
-   *   {},
+   *   { pubsub: "gmail" },
    *   this.onGmailNotification,
    *   "inbox"
    * );
@@ -180,8 +180,20 @@ export abstract class Network extends ITool {
     options: {
       provider?: AuthProvider;
       authorization?: Authorization;
-      /** When true, creates a Google Pub/Sub topic instead of a webhook URL. */
-      pubsub?: boolean;
+      /**
+       * Create a Google Pub/Sub topic instead of a webhook URL, and return
+       * the topic name. Selects the push product:
+       *
+       * - `"gmail"` — Gmail `users.watch` (topic published to by
+       *   `gmail-api-push`). Set this only on the Gmail connector.
+       * - `"workspace"` — Google Workspace Events (Chat, etc.).
+       *
+       * This opt-in must be explicit. Other Google connectors (Calendar,
+       * Drive) omit it and receive a standard HTTPS webhook URL — they must
+       * never be routed to a Pub/Sub topic, which `events.watch` /
+       * `files.watch` reject as non-HTTPS.
+       */
+      pubsub?: "gmail" | "workspace";
       /**
        * Controls whether the returned webhook URL runs callbacks synchronously
        * or asynchronously.