@aitne/shared 0.1.0

package/dist/integrations.js

@@ -0,0 +1,1656 @@
+import { z } from "zod";
+import { BACKEND_IDS } from "./backend.js";
+/**
+ * Integration Delegation Framework — shared types (Phase 1–3).
+ *
+ * See `GOOGLE_AUTH_DELEGATION_DESIGN.md` v3. Phase 1 ships the registry +
+ * per-integration mode config with Gmail + Calendar as the first two keys.
+ * Phase 3 adds skill / task-flow variant selection helpers consumed by
+ * SkillsCompiler and prompts.ts. Git lifecycle Phase 4 retroactively registers
+ * the local Git / GitHub observers under the same mode framework.
+ */
+/**
+ * Mode-aware integrations — the ones that can flip between `direct` and
+ * `delegated` and route through the per-backend probe / connector / skill
+ * filter framework. Other surfaces (lifestyle services like
+ * receipts/books/travel-bookings, Obsidian) integrate via dedicated routes
+ * and observers without participating in this registry.
+ */
+export const INTEGRATION_KEYS = [
+    "gmail",
+    "google_calendar",
+    "notion",
+    "git",
+    "github",
+    "outlook_mail",
+    "outlook_calendar",
+];
+const integrationKeySet = new Set(INTEGRATION_KEYS);
+export function isIntegrationKey(value) {
+    return integrationKeySet.has(value);
+}
+export const INTEGRATION_MODES = ["direct", "delegated", "disabled"];
+const integrationModeSet = new Set(INTEGRATION_MODES);
+export function isIntegrationMode(value) {
+    return integrationModeSet.has(value);
+}
+function readOnlyCliConnector(toolNamespace) {
+    return {
+        // Git/GitHub delegation runs through the selected backend's shell/CLI
+        // context (`git` / `gh`) rather than a hosted MCP connector. Keeping the
+        // capability lists empty makes DelegatedProbeObserver a liveness/audit
+        // heartbeat for these integrations without fabricating MCP tools the
+        // backend cannot actually list.
+        toolNamespace,
+        requiredCapabilities: [],
+        optionalCapabilities: [],
+        capabilityTools: {},
+        destructiveTools: [],
+    };
+}
+/**
+ * The registry. Single source of truth for which integrations exist, what
+ * backends can delegate for them, and which parts of the daemon they touch.
+ *
+ * `backendConnectors` is a `Partial` record — omitting a backend means
+ * delegation through that backend is unsupported.
+ *
+ * Gemini namespace convention differs from Claude / Codex. Gemini CLI's
+ * MCP_TOOL_PREFIX is `mcp_` (single underscore) and the per-server prefix
+ * is `mcp_<serverName>_`, so a tool registered as `gmail.search` on the
+ * `google-workspace` extension surfaces as `mcp_google-workspace_gmail.search`.
+ * Hyphens and dots in the registered name are preserved. The tool-name
+ * format was confirmed by stream-event probe (2026-04-26 — see
+ * `gemini -p ... --output-format stream-json` `tool_use` events) and is
+ * the source of truth for `toolNamespace` and `capabilityTools` below.
+ *
+ * Gemini connectors require host-side MCP setup the daemon does not
+ * manage:
+ *  - Gmail + Calendar: `~/.gemini/extensions/google-workspace/`
+ *    (install via `gemini extensions install <url>`).
+ *  - Notion: register Notion's official MCP server under the server name
+ *    `notion` (e.g. `gemini mcp add notion <url>`); changing the server
+ *    name breaks the namespace assumption — see Gemini Notion descriptor
+ *    notes below.
+ */
+export const INTEGRATION_DESCRIPTORS = {
+    gmail: {
+        key: "gmail",
+        displayName: "Gmail",
+        supportedModes: ["direct", "delegated", "disabled"],
+        // DELEGATED-MODE-V2-DESIGN.md §3.4 / §5.1 — delegated-mode calls flow
+        // through the generic `POST /api/integrations/gmail/invoke` chokepoint.
+        // The legacy per-route `routeMap` proxy was removed in Phase 3.5; the
+        // per-mode skill variant model (`SKILL.delegated.<sessionBackend>.md`)
+        // restored in Phase 3 covers cross-backend prose, and same-backend
+        // sessions use native MCP without a skill body.
+        directSetup: {
+            credentialKeys: ["googleCredentialsJson", "googleTokenJson"],
+            // Google Workspace's end-to-end OAuth setup walkthrough — covers project
+            // creation, API enablement, consent screen, and OAuth client credentials.
+            // The setup wizard's `GCP_LINKS` deep-links each step; this URL is the
+            // overview / fallback for users who want the official prose.
+            helpUrl: "https://developers.google.com/workspace/guides/create-credentials",
+        },
+        backendConnectors: {
+            claude: {
+                toolNamespace: "mcp__claude_ai_Gmail__",
+                // Claude's hosted Gmail connector is draft-only. Send/forward/delete/
+                // attachment capabilities are deliberately absent — dashboard + skill
+                // variants branch on this gap.
+                requiredCapabilities: ["search", "read", "draft", "label"],
+                optionalCapabilities: ["draft", "label", "create_label"],
+                capabilityTools: {
+                    search: ["search_threads"],
+                    read: ["get_thread"],
+                    draft: ["create_draft", "list_drafts"],
+                    label: ["label_message", "label_thread", "unlabel_message", "unlabel_thread", "list_labels"],
+                    create_label: ["create_label"],
+                },
+                // Claude's hosted Gmail connector exposes no send/delete/forward —
+                // label mutations are the only state-changing tools. The four
+                // label_* tools mutate thread/message labels; `list_labels` is a
+                // read and is intentionally excluded. `create_label` modifies the
+                // user's label taxonomy and is included.
+                destructiveTools: [
+                    "label_message",
+                    "label_thread",
+                    "unlabel_message",
+                    "unlabel_thread",
+                    "create_label",
+                ],
+            },
+            codex: {
+                toolNamespace: "mcp__codex_apps__gmail._",
+                requiredCapabilities: ["search", "read", "draft", "label", "send"],
+                optionalCapabilities: [
+                    "draft",
+                    "label",
+                    "create_label",
+                    "update_draft",
+                    "send",
+                    "forward",
+                    "delete",
+                    "read_attachment",
+                    "batch",
+                ],
+                // The Codex namespace already terminates with `._`, so capability
+                // tool names are the rest of the symbol (no leading underscore).
+                // E.g. `mcp__codex_apps__gmail._` + `search_emails`
+                // = `mcp__codex_apps__gmail._search_emails` (the actual tool).
+                capabilityTools: {
+                    search: ["search_emails", "search_email_ids"],
+                    read: ["read_email", "read_email_thread"],
+                    draft: ["create_draft", "list_drafts"],
+                    update_draft: ["update_draft"],
+                    send: ["send_email", "send_draft"],
+                    forward: ["forward_emails"],
+                    label: ["apply_labels_to_emails", "list_labels", "bulk_label_matching_emails"],
+                    create_label: ["create_label"],
+                    delete: ["delete_emails", "archive_emails"],
+                    read_attachment: ["read_attachment"],
+                    batch: ["batch_modify_email", "batch_read_email", "batch_read_email_threads"],
+                },
+                // Send/delete/forward + label mutations + create_label. `list_labels`,
+                // `read_*`, `search_*`, `read_attachment`, and the read-side batch
+                // tools (`batch_read_*`) are read-only and intentionally excluded.
+                // `update_draft` mutates a not-yet-sent draft and is reversible (the
+                // user can edit again before sending) — listed as write-class in
+                // §7.4, NOT destructive.
+                destructiveTools: [
+                    "send_email",
+                    "send_draft",
+                    "forward_emails",
+                    "delete_emails",
+                    "archive_emails",
+                    "apply_labels_to_emails",
+                    "bulk_label_matching_emails",
+                    "create_label",
+                    "batch_modify_email",
+                ],
+            },
+            gemini: {
+                // Gemini CLI's `google-workspace` extension exposes Gmail tools
+                // under the `gmail.*` registration. Combined with Gemini's MCP
+                // namespace convention (`mcp_<server>_<tool>`, single underscore),
+                // a search call surfaces as `mcp_google-workspace_gmail.search` in
+                // `tool_use` stream events. `capabilityTools` entries below are
+                // the bare suffix (the part after `gmail.`), matching how Codex's
+                // namespace also terminates with a separator.
+                toolNamespace: "mcp_google-workspace_gmail.",
+                // Required capabilities mirror Codex's full-auto floor; the
+                // google-workspace extension covers all of search/read/draft/
+                // label/send.
+                requiredCapabilities: ["search", "read", "draft", "label", "send"],
+                // `delete` and `forward` are not surfaced as optional capabilities:
+                // the google-workspace extension has no dedicated tool for either
+                // (delete = `modify` + add TRASH label; forward = `send` with
+                // re-quoted body). Listing them would imply parity the connector
+                // doesn't have. Agents that need either compose them from the
+                // primitives.
+                optionalCapabilities: [
+                    "draft",
+                    "label",
+                    "create_label",
+                    "send",
+                    "read_attachment",
+                    "batch",
+                ],
+                capabilityTools: {
+                    search: ["search"],
+                    read: ["get"],
+                    draft: ["createDraft"],
+                    // sendDraft = dispatch a previously-created draft. send =
+                    // compose-and-send in one call (the irreversible path; default-
+                    // denied via RECOMMENDED_STARTER_DENIED_TOOLS).
+                    send: ["send", "sendDraft"],
+                    // `modify` / `modifyThread` apply or remove labels (including
+                    // the system TRASH label). `listLabels` is a read; included
+                    // here for the same reason Codex includes `list_labels` —
+                    // labelling typically requires enumerating existing labels first.
+                    label: ["modify", "modifyThread", "listLabels"],
+                    create_label: ["createLabel"],
+                    read_attachment: ["downloadAttachment"],
+                    batch: ["batchModify"],
+                },
+                // `send`/`sendDraft` (irreversible dispatch), `modify`/`modifyThread`
+                // (mutate labels including TRASH), `createLabel` (taxonomy edit), and
+                // `batchModify` (mass mutation). `listLabels`, `search`, `get`,
+                // `downloadAttachment`, and `createDraft` (reversible — the user
+                // can edit before sending) stay write-class only. This list is the
+                // tool-name version of the design's `destructiveCapabilities` set
+                // for the Gemini connector, with the read-mixed `label` capability
+                // split apart to keep `listLabels` allowed.
+                destructiveTools: [
+                    "send",
+                    "sendDraft",
+                    "modify",
+                    "modifyThread",
+                    "createLabel",
+                    "batchModify",
+                ],
+                // The google-workspace extension authenticates the user's signed-in
+                // Google account on first tool call (no separate subscription).
+            },
+        },
+        // DELEGATED-MODE-V2-DESIGN.md §3.4 / §5.1 — restored in Phase 3 so
+        // `selectSkillVariantFile` engages on the `mail` skill.
+        // `SKILL.delegated.<sessionBackend>.md` is materialized for
+        // cross-backend pairs; same-backend resolves to `null` (native MCP,
+        // no skill body).
+        skillsTouched: ["mail"],
+        // `routine.hourly_check` retains a delegated variant: when Gmail is
+        // delegated, MailPoller's per-account filter (mail-poller.ts:173-181)
+        // stops Gmail-account polling, so `mail:lifecycle` observations
+        // disappear. The variant's Step 0a fetches the equivalent window via
+        // the connector. Listing the task-flow here is what triggers
+        // `selectTaskFlowVariantSuffix` to pick the variant.
+        taskFlowsTouched: ["routine.hourly_check"],
+        observersTouched: [],
+        // Multi-provider routes (`/api/mail/*`) are intentionally not gated
+        // here — prefix matching would also block iCloud / Outlook / IMAP
+        // accounts. Per-account 410 inside the mail handler covers Gmail
+        // accounts when delegated (DELEGATED-MODE-V2-DESIGN.md §6.3
+        // defense-in-depth).
+        apiRoutesTouched: [],
+        deniedToolsAppliesToSkills: ["mail"],
+    },
+    google_calendar: {
+        key: "google_calendar",
+        displayName: "Google Calendar",
+        supportedModes: ["direct", "delegated", "disabled"],
+        // DELEGATED-MODE-V2-DESIGN.md §3.4 / §5.1 — delegated-mode calls flow
+        // through `POST /api/integrations/google_calendar/invoke`. Per-mode
+        // skill variants restored in Phase 3.
+        directSetup: {
+            credentialKeys: ["googleCredentialsJson", "googleTokenJson"],
+            // Same OAuth flow as Gmail — Google Workspace's official setup guide.
+            helpUrl: "https://developers.google.com/workspace/guides/create-credentials",
+        },
+        backendConnectors: {
+            claude: {
+                toolNamespace: "mcp__claude_ai_Google_Calendar__",
+                requiredCapabilities: ["list_events", "get_event", "create_event"],
+                optionalCapabilities: [
+                    "list_events",
+                    "get_event",
+                    "create_event",
+                    "update_event",
+                    "delete_event",
+                    "respond_to_event",
+                    "suggest_time",
+                    "list_calendars",
+                ],
+                capabilityTools: {
+                    list_events: ["list_events"],
+                    get_event: ["get_event"],
+                    create_event: ["create_event"],
+                    update_event: ["update_event"],
+                    delete_event: ["delete_event"],
+                    respond_to_event: ["respond_to_event"],
+                    suggest_time: ["suggest_time"],
+                    list_calendars: ["list_calendars"],
+                },
+                // Mutating calendar ops. `respond_to_event` is destructive because
+                // the response is fired off to the organizer; `suggest_time` is
+                // pure compute with no calendar side effects.
+                destructiveTools: [
+                    "create_event",
+                    "update_event",
+                    "delete_event",
+                    "respond_to_event",
+                ],
+            },
+            codex: {
+                toolNamespace: "mcp__codex_apps__google_calendar._",
+                requiredCapabilities: ["search", "read", "create_event"],
+                optionalCapabilities: [
+                    "search",
+                    "read",
+                    "create_event",
+                    "update_event",
+                    "delete_event",
+                    "respond_event",
+                    "get_availability",
+                    "batch_read",
+                ],
+                capabilityTools: {
+                    search: ["search", "search_events"],
+                    read: ["read_event", "fetch"],
+                    create_event: ["create_event"],
+                    update_event: ["update_event"],
+                    delete_event: ["delete_event"],
+                    respond_event: ["respond_event"],
+                    get_availability: ["get_availability"],
+                    batch_read: ["batch_read_event"],
+                },
+                destructiveTools: [
+                    "create_event",
+                    "update_event",
+                    "delete_event",
+                    "respond_event",
+                ],
+            },
+            gemini: {
+                // google-workspace extension's Calendar tools: registered as
+                // `calendar.*`, surfaced as `mcp_google-workspace_calendar.*`.
+                toolNamespace: "mcp_google-workspace_calendar.",
+                requiredCapabilities: ["list_events", "get_event", "create_event"],
+                optionalCapabilities: [
+                    "list_events",
+                    "get_event",
+                    "create_event",
+                    "update_event",
+                    "delete_event",
+                    "respond_to_event",
+                    "find_free_time",
+                    "list_calendars",
+                ],
+                capabilityTools: {
+                    list_events: ["listEvents"],
+                    get_event: ["getEvent"],
+                    create_event: ["createEvent"],
+                    update_event: ["updateEvent"],
+                    delete_event: ["deleteEvent"],
+                    respond_to_event: ["respondToEvent"],
+                    find_free_time: ["findFreeTime"],
+                    list_calendars: ["list"],
+                },
+                destructiveTools: [
+                    "createEvent",
+                    "updateEvent",
+                    "deleteEvent",
+                    "respondToEvent",
+                ],
+            },
+        },
+        // DELEGATED-MODE-V2-DESIGN.md §3.4 / §5.1 — restored in Phase 3 so
+        // `selectSkillVariantFile` engages on the `external-services` skill.
+        skillsTouched: ["external-services"],
+        // `routine.hourly_check` retains a delegated variant: when Calendar is
+        // delegated, the CalendarPoller stops (see `observersTouched` below)
+        // so `calendar:*` observations and `schedule.approaching` events are
+        // lost. The variant's Step 0b restores both via two connector fetches
+        // (imminent-window + 24h change-detection).
+        taskFlowsTouched: ["routine.hourly_check"],
+        // CalendarPoller still stops on a delegated flip — it polls via direct
+        // OAuth credentials that the user has not necessarily set when running
+        // delegated. The variant compensates for the observation surface.
+        observersTouched: ["calendar"],
+        // Single-provider surface — the `/api/calendar` prefix can be 410-gated
+        // safely (DELEGATED-MODE-V2-DESIGN.md §6.3 defense-in-depth). Cross-
+        // backend skill prose directs the agent at the invoke endpoint, but
+        // hallucinated `/api/calendar/*` calls now interdict at the gate.
+        apiRoutesTouched: ["/api/calendar"],
+        deniedToolsAppliesToSkills: ["external-services"],
+    },
+    notion: {
+        key: "notion",
+        displayName: "Notion",
+        supportedModes: ["direct", "delegated", "disabled"],
+        directSetup: {
+            credentialKeys: ["notionApiKey"],
+            // Notion's official guide for creating an internal integration and
+            // obtaining the API key required by direct mode.
+            helpUrl: "https://developers.notion.com/docs/create-a-notion-integration",
+        },
+        backendConnectors: {
+            claude: {
+                toolNamespace: "mcp__claude_ai_Notion__",
+                // Minimum set that makes delegated mode worth the user's time:
+                // search + read + create + property update + content patch +
+                // archive. Schema-admin, comments, and the rest are bonuses —
+                // declared in optionalCapabilities. The framework's tool-deny
+                // policy (NOTION_DELEGATION_DESIGN.md §7.7) lets the user carve
+                // those out per-tool from the dashboard.
+                //
+                // Archive caveat (v0.4): `notion-update-page` does NOT trash
+                // pages — `in_trash` is rejected as a property and there is no
+                // dedicated trash tool. The `archive` capability stays in the
+                // required set because the property-update workaround
+                // (Status="Archived" + status-property write) does route through
+                // `notion-update-page`, but the skill body labels it as
+                // workaround-only. See NOTION_DELEGATION_DESIGN.md §3 + §7.4.
+                requiredCapabilities: [
+                    "search",
+                    "read",
+                    "create_page",
+                    "update_properties",
+                    "patch_content",
+                    "archive",
+                ],
+                optionalCapabilities: [
+                    "search",
+                    "read",
+                    "create_page",
+                    "update_properties",
+                    "patch_content",
+                    "replace_content",
+                    "archive",
+                    "comments",
+                    "duplicate_page",
+                    "move_page",
+                    "apply_template",
+                    "schema_admin",
+                    "users",
+                    "teams",
+                ],
+                // Several capabilities (`update_properties`, `patch_content`,
+                // `replace_content`, `archive`, `apply_template`) all map to the
+                // single `notion-update-page` tool. The probe is tool-name based,
+                // so they flip to "true" together — accurate at the tool level
+                // even though it doesn't verify each sub-command. Per
+                // NOTION_DELEGATION_DESIGN.md §5 (capability-tool overlap note).
+                capabilityTools: {
+                    search: ["notion-search"],
+                    read: ["notion-fetch"],
+                    create_page: ["notion-create-pages"],
+                    update_properties: ["notion-update-page"],
+                    patch_content: ["notion-update-page"],
+                    replace_content: ["notion-update-page"],
+                    archive: ["notion-update-page"],
+                    comments: ["notion-create-comment", "notion-get-comments"],
+                    duplicate_page: ["notion-duplicate-page"],
+                    move_page: ["notion-move-pages"],
+                    apply_template: ["notion-update-page"],
+                    schema_admin: [
+                        "notion-create-database",
+                        "notion-update-data-source",
+                        "notion-create-view",
+                        "notion-update-view",
+                    ],
+                    users: ["notion-get-users"],
+                    teams: ["notion-get-teams"],
+                },
+                // Page mutations + comment writes + schema admin. The read-only
+                // tools (`notion-search`, `notion-fetch`, `notion-get-comments`,
+                // `notion-get-users`, `notion-get-teams`) are intentionally
+                // excluded. `notion-update-page` covers update_properties,
+                // patch_content, replace_content, apply_template, AND archive
+                // (the property-update workaround for trash) — listing it once
+                // here gates all five.
+                destructiveTools: [
+                    "notion-create-pages",
+                    "notion-update-page",
+                    "notion-duplicate-page",
+                    "notion-move-pages",
+                    "notion-create-comment",
+                    "notion-create-database",
+                    "notion-update-data-source",
+                    "notion-create-view",
+                    "notion-update-view",
+                ],
+            },
+            codex: {
+                toolNamespace: "mcp__codex_apps__notion._",
+                // Same required set as Claude — these are framework requirements
+                // (search/read/create/property update/content patch/archive) that
+                // make delegated mode worth the user's time. Codex carries strict
+                // parity on each: `_search` and `_fetch` for read, `_notion_create_pages`,
+                // and `_notion_update_page` (same 5 commands as Claude:
+                // update_properties, update_content, replace_content,
+                // apply_template, update_verification). The page-archive gap is
+                // identical to Claude — no `in_trash` on pages — so the skill
+                // body uses the same property-update / move-to-trash workarounds.
+                // The `archive` capability stays in `requiredCapabilities` for
+                // the same reason as the Claude block above (workaround routes
+                // through `_notion_update_page`). NOTION_DELEGATION_DESIGN.md
+                // §3 + §7.4.
+                requiredCapabilities: [
+                    "search",
+                    "read",
+                    "create_page",
+                    "update_properties",
+                    "patch_content",
+                    "archive",
+                ],
+                // Codex exposes two capabilities Claude's connector lacks:
+                //  - `query_data_sources` — `_notion_query_data_sources` runs
+                //    SQLite queries against a data source, including parameterized
+                //    structured-property filters (`WHERE Status = ? AND Priority = ?`).
+                //    This natively closes the gap §3.2 / Q2 accepted for Claude
+                //    delegation; the delegated skill body documents the SQL pattern.
+                //  - `query_meeting_notes` — `_notion_query_meeting_notes` runs a
+                //    structured filter against the user's meeting-notes data source.
+                //    Niche but free, surfaced as a capability.
+                optionalCapabilities: [
+                    "search",
+                    "read",
+                    "create_page",
+                    "update_properties",
+                    "patch_content",
+                    "replace_content",
+                    "archive",
+                    "comments",
+                    "duplicate_page",
+                    "move_page",
+                    "apply_template",
+                    "schema_admin",
+                    "users",
+                    "teams",
+                    "query_data_sources",
+                    "query_meeting_notes",
+                ],
+                // Tool names are unsuffixed (the Codex namespace already terminates
+                // with `._`, so `mcp__codex_apps__notion._` + `notion_create_pages`
+                // = `mcp__codex_apps__notion._notion_create_pages`). Note `_search`
+                // and `_fetch` are bare — they're not Notion-prefixed in Codex's
+                // namespace, only the rest are.
+                capabilityTools: {
+                    search: ["search"],
+                    read: ["fetch"],
+                    create_page: ["notion_create_pages"],
+                    update_properties: ["notion_update_page"],
+                    patch_content: ["notion_update_page"],
+                    replace_content: ["notion_update_page"],
+                    archive: ["notion_update_page"],
+                    comments: ["notion_create_comment", "notion_get_comments"],
+                    duplicate_page: ["notion_duplicate_page"],
+                    move_page: ["notion_move_pages"],
+                    apply_template: ["notion_update_page"],
+                    schema_admin: [
+                        "notion_create_database",
+                        "notion_update_data_source",
+                        "notion_create_view",
+                        "notion_update_view",
+                    ],
+                    users: ["notion_get_users"],
+                    teams: ["notion_get_teams"],
+                    query_data_sources: ["notion_query_data_sources"],
+                    query_meeting_notes: ["notion_query_meeting_notes"],
+                },
+                // Same shape as the Claude namespace but underscore-separated. The
+                // two query_* tools (`_notion_query_data_sources`,
+                // `_notion_query_meeting_notes`) are read-only structured queries
+                // and intentionally excluded.
+                destructiveTools: [
+                    "notion_create_pages",
+                    "notion_update_page",
+                    "notion_duplicate_page",
+                    "notion_move_pages",
+                    "notion_create_comment",
+                    "notion_create_database",
+                    "notion_update_data_source",
+                    "notion_create_view",
+                    "notion_update_view",
+                ],
+            },
+            gemini: {
+                // Notion's official MCP server is added to Gemini CLI by the
+                // user (`gemini mcp add notion <url>` or via the dashboard's MCP
+                // page). This descriptor assumes the server is registered under
+                // the literal name `notion` — Gemini surfaces tools as
+                // `mcp_notion_<tool>`. If the user picks a different name the
+                // probe will report every required capability missing; the
+                // dashboard surfaces this as an actionable "wrong server name"
+                // hint.
+                //
+                // Tool names match Notion's hosted MCP wire format (same names
+                // Anthropic's hosted Notion connector uses, with hyphenated
+                // identifiers). Same required-capability floor as Claude / Codex.
+                toolNamespace: "mcp_notion_",
+                requiredCapabilities: [
+                    "search",
+                    "read",
+                    "create_page",
+                    "update_properties",
+                    "patch_content",
+                    "archive",
+                ],
+                optionalCapabilities: [
+                    "search",
+                    "read",
+                    "create_page",
+                    "update_properties",
+                    "patch_content",
+                    "replace_content",
+                    "archive",
+                    "comments",
+                    "duplicate_page",
+                    "move_page",
+                    "apply_template",
+                    "schema_admin",
+                    "users",
+                    "teams",
+                ],
+                capabilityTools: {
+                    search: ["notion-search"],
+                    read: ["notion-fetch"],
+                    create_page: ["notion-create-pages"],
+                    update_properties: ["notion-update-page"],
+                    patch_content: ["notion-update-page"],
+                    replace_content: ["notion-update-page"],
+                    archive: ["notion-update-page"],
+                    comments: ["notion-create-comment", "notion-get-comments"],
+                    duplicate_page: ["notion-duplicate-page"],
+                    move_page: ["notion-move-pages"],
+                    apply_template: ["notion-update-page"],
+                    schema_admin: [
+                        "notion-create-database",
+                        "notion-update-data-source",
+                        "notion-create-view",
+                        "notion-update-view",
+                    ],
+                    users: ["notion-get-users"],
+                    teams: ["notion-get-teams"],
+                },
+                destructiveTools: [
+                    "notion-create-pages",
+                    "notion-update-page",
+                    "notion-duplicate-page",
+                    "notion-move-pages",
+                    "notion-create-comment",
+                    "notion-create-database",
+                    "notion-update-data-source",
+                    "notion-create-view",
+                    "notion-update-view",
+                ],
+            },
+        },
+        skillsTouched: ["notion"],
+        // `routine.hourly_check` is the only routine that consumes Notion
+        // observations today (NotionPoller → observations table → routine via
+        // the `observations` skill). When Notion is delegated the poller
+        // stops; the hourly_check delegated variant compensates by pulling
+        // recent edits via `notion-search` inline. See §7.5 of the design.
+        taskFlowsTouched: ["routine.hourly_check"],
+        observersTouched: ["notion-poller"],
+        // Fine-grained gating: leave `/api/notion/databases` ungated (it's a
+        // config dump with no Notion API call). Gate the routes that hit the
+        // API. The route-gate middleware uses longest-prefix matching with
+        // strict boundary semantics (`pathname === prefix ||
+        // startsWith(prefix + "/")`), so `/api/notion/databases` never
+        // matches any of these. See §5 + §7.2 of the design.
+        apiRoutesTouched: [
+            "/api/notion/query",
+            "/api/notion/search",
+            "/api/notion/pages",
+        ],
+        // The `notion` skill body is purely a wrapper over `/api/notion/*`
+        // (no IMAP/Obsidian/etc. side-content). When notion is delegated
+        // same-backend the connector's own tool descriptions cover the
+        // surface, so dropping the skill body avoids redundant prose.
+        sameBackendDropsSkillBody: ["notion"],
+    },
+    git: {
+        key: "git",
+        displayName: "Git",
+        supportedModes: ["direct", "delegated", "disabled"],
+        backendConnectors: {
+            claude: readOnlyCliConnector("cli:git:claude:"),
+            codex: readOnlyCliConnector("cli:git:codex:"),
+            gemini: readOnlyCliConnector("cli:git:gemini:"),
+        },
+        // Git event task-flows are backend-neutral observer flows, not MCP
+        // connector wrappers. Delegated Git uses a dedicated cron task-flow,
+        // so no SKILL.delegated.* variants are required here.
+        skillsTouched: [],
+        taskFlowsTouched: [],
+        observersTouched: ["git"],
+        apiRoutesTouched: [],
+    },
+    github: {
+        key: "github",
+        displayName: "GitHub",
+        supportedModes: ["direct", "delegated", "disabled"],
+        backendConnectors: {
+            claude: readOnlyCliConnector("cli:github:claude:"),
+            codex: readOnlyCliConnector("cli:github:codex:"),
+            gemini: readOnlyCliConnector("cli:github:gemini:"),
+        },
+        // GitHub delegated mode also relies on the chosen backend's read-only
+        // `gh` CLI access, not daemon-proxied MCP tools.
+        skillsTouched: [],
+        taskFlowsTouched: [],
+        observersTouched: ["github"],
+        apiRoutesTouched: [],
+    },
+    // SETUP-FLOW-REDESIGN-PLAN §6.1 — Outlook Mail. Microsoft does not
+    // ship a hosted Outlook MCP connector for Claude / Codex / Gemini, so
+    // `backendConnectors` stays empty and delegated mode runs as
+    // "user-managed connector": the user installs an Outlook / Microsoft
+    // Graph MCP server on the agent backend they pick (Claude Code
+    // Connector / Codex MCP / Gemini extension) and the daemon trusts that
+    // wiring. The `userManagedConnector` flag relaxes the PATCH /
+    // probe / variant gates that otherwise require a descriptor-supplied
+    // connector. The dashboard surfaces a "user must configure MCP on the
+    // selected backend" notice when delegated is selected.
+    outlook_mail: {
+        key: "outlook_mail",
+        displayName: "Outlook Mail",
+        supportedModes: ["direct", "delegated", "disabled"],
+        userManagedConnector: true,
+        directSetup: {
+            // MSAL token cache + per-account BYOA client config. Per §6.1 of
+            // the redesign plan, the token cache key is `mail:outlook:<accountId>`
+            // and the client-config blob is the canonical
+            // `mail:outlook:client-config` (see services/mail/outlook/client-config.ts).
+            credentialKeys: ["mail:outlook:client-config"],
+            // Microsoft Identity platform OAuth onboarding for personal +
+            // organizational accounts (BYOA pattern, public client).
+            helpUrl: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+        },
+        backendConnectors: {},
+        // The unified `mail` skill already routes per-account on
+        // MailProviderKind ("outlook") for direct mode. Delegated mode for
+        // outlook is user-managed (no daemon-side variant materialization),
+        // so the registry intentionally does NOT declare `skillsTouched`
+        // here — `selectSkillVariantFile` would otherwise resolve to a
+        // Gmail-specific delegated variant when only outlook is delegated.
+        //
+        // Trade-off accepted: when ONLY outlook_mail is delegated and
+        // gmail/etc. stay direct, the agent reads the standard `mail`
+        // SKILL.md prose describing `/api/mail/*` for all kinds. Calls
+        // against outlook accounts then 410 with the user-managed message
+        // (see `delegatedMailIntegrationMessage` in api/routes/mail.ts),
+        // which redirects the agent to its own MCP. One round-trip cost
+        // on first attempt vs. authoring + maintaining outlook-specific
+        // skill variants — the round-trip wins for Phase 1.
+        skillsTouched: [],
+        taskFlowsTouched: [],
+        // The unified mail poller handles all `MailProviderKind` rows,
+        // including `kind="outlook"`; lifecycle stops Outlook polling when
+        // outlook_mail flips to delegated.
+        observersTouched: ["mail-poller"],
+        // Multi-provider routes `/api/mail/*` cannot be safely prefix-gated;
+        // per-account 410 inside the handler covers the delegated case.
+        // (Same exception Gmail makes — see `gatedIntegrationForKind` in
+        // mail.ts.)
+        apiRoutesTouched: [],
+    },
+    // SETUP-FLOW-REDESIGN-PLAN §6.1 — Outlook Calendar. Single-provider
+    // surface (mirrors `google_calendar`). v1 ships on-demand Graph
+    // fetches; no `OutlookCalendarPoller`. `observersTouched: []`
+    // reflects the deferral honestly. Delegated mode is user-managed —
+    // see the `outlook_mail` block for the contract.
+    outlook_calendar: {
+        key: "outlook_calendar",
+        displayName: "Outlook Calendar",
+        supportedModes: ["direct", "delegated", "disabled"],
+        userManagedConnector: true,
+        directSetup: {
+            // Token shared with `outlook_mail` via the MSAL cache plugin's
+            // per-account row. The same `mail:outlook:client-config` BYOA blob
+            // is reused — calendar does not register a separate client.
+            credentialKeys: ["mail:outlook:client-config"],
+            helpUrl: "https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app",
+        },
+        backendConnectors: {},
+        // No daemon-side skill variant for delegated outlook calendar —
+        // user-managed MCP exposes itself on the backend natively.
+        skillsTouched: [],
+        taskFlowsTouched: [],
+        observersTouched: [],
+        // Single-provider surface — `/api/calendar/outlook` is safely
+        // prefix-gated to 410 when delegated. The route gate's user-managed
+        // message points the agent at its backend's MCP rather than
+        // `/api/integrations/.../invoke` (no daemon-side proxy exists).
+        apiRoutesTouched: ["/api/calendar/outlook"],
+    },
+};
+export function getIntegrationDescriptor(key) {
+    return INTEGRATION_DESCRIPTORS[key];
+}
+export function listIntegrationDescriptors() {
+    return INTEGRATION_KEYS.map((k) => INTEGRATION_DESCRIPTORS[k]);
+}
+/**
+ * DELEGATED-MODE-V2-DESIGN.md §3 — integrations whose delegated task-flow
+ * variant uses the daemon's generic `/api/integrations/:key/invoke` proxy
+ * rather than native MCP. The router's
+ * {@link delegatedIntegrationsForProcessKey} skips these when computing
+ * fallback-refusal candidates: the daemon proxies the connector via
+ * `delegatedBackend`'s spawned subprocess regardless of which agent
+ * backend handles the process key, so the agent backend's identity does
+ * not need to constrain fallback.
+ *
+ * Replaces the v1 `proxiedAtDaemon` descriptor flag (removed in
+ * Phase 3.5). New v2 integrations that adopt the proxy task-flow add
+ * themselves here. Native-MCP-driven integrations (today: notion) are
+ * intentionally absent so their fallback-refusal semantics remain.
+ */
+const PROXY_DRIVEN_INTEGRATIONS = new Set([
+    "gmail",
+    "google_calendar",
+]);
+/**
+ * Per-integration runtime state. Persisted as a single JSON blob in the
+ * `settings` table under key `"integrations"`; rendered into
+ * `~/.personal-agent/integrations.md` so users can edit by hand.
+ */
+export const integrationStateSchema = z
+    .object({
+    mode: z.enum(INTEGRATION_MODES),
+    delegatedBackend: z
+        .enum(BACKEND_IDS)
+        .optional()
+        // zod 4 emits `null` defaults as `undefined` when the field is optional;
+        // keep it explicit so JSON round-trips don't flip between.
+        .nullable()
+        .optional(),
+    /**
+     * DELEGATED-PROXY-API-DESIGN.md §4.2 / §5.1 — user-pinned model used by
+     * `DelegatedBackendInvoker` for proxy invocations. Null / undefined
+     * means "use the canonical light-tier model for `delegatedBackend`",
+     * resolved at call time rather than PATCH time so plan changes
+     * automatically retrack the canonical pick.
+     *
+     * Mode-flip behaviour: preserved across `direct ↔ delegated` and
+     * `delegated → disabled`; on a `delegatedBackend` swap a stale value
+     * is silently dropped at call time (dashboard surfaces a "Reset to
+     * default" affordance). PATCH validation rejects values that don't
+     * appear in the registered model list for `delegatedBackend`.
+     */
+    delegatedModel: z.string().min(1).nullable().optional(),
+    /**
+     * DELEGATED-PROXY-API-DESIGN.md §4.2 — per-call max-turns override.
+     * Sized for the rare connector that needs a tool-list lookup before
+     * the actual call. v0.1 ships UI only for `delegatedModel`;
+     * `delegatedMaxTurns` is registry-default (DELEGATED_PROXY_DEFAULTS
+     * in `delegated-proxy-config.ts`) and lifted later if observation
+     * warrants. Field exists in the schema for forward compatibility.
+     */
+    delegatedMaxTurns: z.number().int().min(1).max(10).nullable().optional(),
+    /**
+     * INTEGRATION-DRIFT-DETECTION-PLAN Phase 3 — hard kill switch for the
+     * daemon-side delegated drift worker. Omitted means enabled; storing
+     * only `false` keeps existing settings JSON compact and preserves
+     * backward compatibility with rows written before the worker existed.
+     */
+    delegatedSyncEnabled: z.boolean().optional(),
+    /**
+     * §7.7 tool-deny policy. Each entry is the unsuffixed tool name as
+     * declared in the descriptor's `capabilityTools` (e.g. for Claude
+     * Notion: `"notion-create-database"`; for Codex Notion:
+     * `"notion_create_database"`). Tools listed here are stripped from the
+     * delegated skill body at materialization time (hard enforcement on
+     * Claude via `allowed-tools` frontmatter; soft enforcement on Codex /
+     * Gemini via a prose "Denied tools" block). Default empty = all
+     * allowed. Stale entries (tool name not present in the active
+     * backend's capability tools) are silently ignored.
+     */
+    deniedTools: z.array(z.string()).optional().default([]),
+    /** ISO-8601 timestamp the user / daemon last changed this field. */
+    lastChangedAt: z.string(),
+})
+    .superRefine((value, ctx) => {
+    if (value.mode === "delegated") {
+        if (!value.delegatedBackend) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["delegatedBackend"],
+                message: "delegatedBackend is required when mode is 'delegated'",
+            });
+        }
+    }
+    // `delegatedModel` is allowed in any mode — it's inert when not
+    // delegated. Cross-field validation (model belongs to backend) lives
+    // in the PATCH handler so it can read the live model registry / plan
+    // preset; doing it here would couple every settings round-trip to
+    // that lookup.
+});
+/**
+ * The full integrations map stored in the `settings` table. Every registered
+ * integration key has an entry; missing keys are filled with the per-key
+ * default before persistence. Gmail / Calendar / Notion stay disabled on
+ * fresh installs, while Git / GitHub default to direct mode to preserve the
+ * pre-registry observer behaviour and match the Git lifecycle design.
+ */
+export const integrationsMapSchema = z
+    .object(Object.fromEntries(INTEGRATION_KEYS.map((key) => [key, integrationStateSchema.optional()])))
+    .strict();
+function defaultModeForIntegration(key) {
+    return key === "git" || key === "github" ? "direct" : "disabled";
+}
+/** Build the default integration map used for fresh installs. */
+export function defaultIntegrationsMap(now = new Date().toISOString()) {
+    const out = {};
+    for (const key of INTEGRATION_KEYS) {
+        out[key] = {
+            mode: defaultModeForIntegration(key),
+            deniedTools: [],
+            lastChangedAt: now,
+        };
+    }
+    return out;
+}
+/**
+ * Narrow user input (from integrations.md or PATCH /api/integrations/:key) to a
+ * valid state. Used by the parser and the API route so both enforce identical
+ * rules.
+ */
+export const integrationPatchSchema = z
+    .object({
+    mode: z.enum(INTEGRATION_MODES),
+    delegatedBackend: z.enum(BACKEND_IDS).optional().nullable(),
+    /**
+     * DELEGATED-PROXY-API-DESIGN.md §6.1 — user-pinned proxy model. Empty
+     * string is rejected (use `null` to clear). Cross-field validation
+     * (the value must appear in the registered model list for the
+     * effective backend) lives in the PATCH route handler so it can
+     * consult the live model registry / plan preset; here we only narrow
+     * the shape.
+     *
+     * Omitting the field preserves the previously stored value across
+     * `direct ↔ delegated` flips. Passing `null` explicitly clears the
+     * pin — useful when the dashboard "Reset to default" affordance is
+     * triggered after a backend swap.
+     */
+    delegatedModel: z.string().min(1).nullable().optional(),
+    /**
+     * DELEGATED-PROXY-API-DESIGN.md §4.2 — forward-compat field for
+     * per-integration max-turns overrides. v0.1 surfaces no UI for this;
+     * the schema accepts it so a future dashboard release can land
+     * without a migration. PATCH-time validation matches the state
+     * schema's int(1..10) bound.
+     */
+    delegatedMaxTurns: z.number().int().min(1).max(10).nullable().optional(),
+    /**
+     * Optional hard kill switch for DelegatedSyncWorker. Omitted = enabled.
+     * Accepted in any mode so the user can pre-stage the setting before
+     * flipping an integration to delegated.
+     */
+    delegatedSyncEnabled: z.boolean().optional(),
+    /**
+     * §7.7 — optional tool-deny list. Validation against
+     * descriptor.capabilityTools and required-capability coverage runs in
+     * the API route via `validateDeniedTools`; here we only narrow the
+     * shape. Omitting the field on PATCH preserves the previously stored
+     * list (mode-independent — direct ↔ delegated does not clear it).
+     */
+    deniedTools: z.array(z.string()).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (value.mode === "delegated" && !value.delegatedBackend) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["delegatedBackend"],
+            message: "delegatedBackend is required when mode is 'delegated'",
+        });
+    }
+    if (value.mode !== "delegated" && value.delegatedBackend) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["delegatedBackend"],
+            message: "delegatedBackend must be omitted unless mode is 'delegated'",
+        });
+    }
+});
+// ── Phase 3: Skill / task-flow variant selection (§4.7) ──────────────────────
+/**
+ * DELEGATED-MODE-V2-DESIGN.md §4.1.1 — pick the SKILL.md variant for a given
+ * skill, **session backend**, and integration state. Three outcomes:
+ *
+ *   - `"SKILL.md"`      — direct/default body. Used when no touched
+ *                         integration is delegated, when the skill is
+ *                         integration-agnostic, OR when every touched
+ *                         integration is same-backend delegated but the
+ *                         skill body covers more than the connector
+ *                         exposes (see `sameBackendDropsSkillBody`).
+ *   - `null`            — do **not** materialize the skill at all. Reached
+ *                         when every touched integration is delegated AND
+ *                         `delegatedBackend === sessionBackend` AND every
+ *                         touching integration declares the skill in its
+ *                         `sameBackendDropsSkillBody` (i.e. the connector
+ *                         covers the entire skill surface). The agent
+ *                         already has the connector's tools natively, so
+ *                         a redundant skill body is omitted.
+ *   - `"SKILL.delegated.<sessionBackend>.md"` — cross-backend variant. The
+ *                         DM session runs on `sessionBackend` but the
+ *                         connector for at least one touched integration
+ *                         lives on a *different* backend, so the agent
+ *                         must call the daemon's generic invoke endpoint
+ *                         which spawns the delegatedBackend subprocess.
+ *
+ * Combination rule for skills that touch multiple integrations: cross-backend
+ * wins over same-backend (a single skill body cannot reliably span both
+ * worlds), and same-backend → null wins over direct only when *every*
+ * touched integration resolves to same-backend AND every touched integration
+ * declares the skill in `sameBackendDropsSkillBody`. Any other configuration
+ * falls back to `"SKILL.md"`.
+ *
+ * Callers are responsible for existence-checking: if the returned variant
+ * file does not exist on disk, fall back to `"SKILL.md"`.
+ */
+export function selectSkillVariantFile(skillSlug, sessionBackend, integrations) {
+    const touchingKeys = INTEGRATION_KEYS.filter((k) => INTEGRATION_DESCRIPTORS[k].skillsTouched.includes(skillSlug));
+    if (touchingKeys.length === 0)
+        return "SKILL.md";
+    const verdicts = touchingKeys.map((k) => resolveOneVariant(integrations[k], sessionBackend));
+    if (verdicts.some((v) => v === "cross-backend")) {
+        return `SKILL.delegated.${sessionBackend}.md`;
+    }
+    if (verdicts.every((v) => v === "same-backend")) {
+        // The skill body is dropped only when every touching integration's
+        // descriptor confirms its connector covers the skill end-to-end.
+        // Multi-purpose skills (`mail` covers IMAP/Outlook; `external-services`
+        // covers Obsidian/GitHub/scheduling) keep the direct body so the
+        // non-delegated functionality survives.
+        const allDrop = touchingKeys.every((k) => INTEGRATION_DESCRIPTORS[k].sameBackendDropsSkillBody?.includes(skillSlug)
+            ?? false);
+        return allDrop ? null : "SKILL.md";
+    }
+    return "SKILL.md";
+}
+function resolveOneVariant(state, sessionBackend) {
+    // Skill not bound to this integration, or integration not yet seeded into
+    // state (defaults to disabled) — direct.
+    if (!state)
+        return "direct";
+    if (state.mode !== "delegated")
+        return "direct";
+    if (state.delegatedBackend === sessionBackend)
+        return "same-backend";
+    return "cross-backend";
+}
+/**
+ * Return the task-flow variant suffix for a given event type, backend, and
+ * integration state. Returns `"direct"` when no touched integration is
+ * delegated. Returns `"delegated.<backendId>"` otherwise.
+ *
+ * The caller constructs the filename as `<eventType>.<suffix>.md` and checks
+ * for existence before falling back to `<eventType>.md`.
+ */
+export function selectTaskFlowVariantSuffix(taskFlowKey, backendId, integrations) {
+    const touchingKeys = INTEGRATION_KEYS.filter((k) => INTEGRATION_DESCRIPTORS[k].taskFlowsTouched.includes(taskFlowKey));
+    if (touchingKeys.every((k) => (integrations[k]?.mode ?? "disabled") !== "delegated")) {
+        return "direct";
+    }
+    return `delegated.${backendId}`;
+}
+// ── Phase 4: Backend-router delegated-integration gating (§4 Phase 4) ────────
+/**
+ * Return the delegated integrations whose `taskFlowsTouched` declares a
+ * dependency on this process key. Skills are intentionally not consulted —
+ * skills load on demand mid-session, so the router cannot predict them from
+ * a process key alone.
+ *
+ * **Excludes proxy-driven integrations** (see {@link PROXY_DRIVEN_INTEGRATIONS}).
+ * The router uses this helper only to decide whether to refuse a fallback
+ * because the fallback backend lacks the integration's connector. For
+ * proxy-driven integrations the connector lives on `delegatedBackend` and
+ * is invoked by the daemon — the agent backend never touches it, so the
+ * fallback gate is irrelevant. (Gmail/Calendar still appear in
+ * `taskFlowsTouched` because their delegated variant is what
+ * `selectTaskFlowVariantSuffix` reads to compensate for stopped pollers;
+ * the asymmetry is intentional.)
+ *
+ * Returns an empty array when no native-MCP delegated integration touches
+ * the key.
+ */
+export function delegatedIntegrationsForProcessKey(processKey, integrations) {
+    return INTEGRATION_KEYS.filter((k) => {
+        const state = integrations[k];
+        if (!state || state.mode !== "delegated")
+            return false;
+        if (PROXY_DRIVEN_INTEGRATIONS.has(k))
+            return false;
+        return INTEGRATION_DESCRIPTORS[k].taskFlowsTouched.includes(processKey);
+    });
+}
+/**
+ * True when the registry declares a connector for `(integrationKey, backendId)`.
+ * Descriptor presence is the contract the BackendRouter consults on the
+ * fallback path — a missing entry means the backend has no connector for
+ * this integration, so routing a delegated-integration process key through
+ * it would silently execute with the wrong tool surface.
+ *
+ * This does NOT consult capability lists or live probe state; `PATCH
+ * /api/integrations/:key` already enforces `requiredCapabilities` against
+ * the live probe before a delegated flip is accepted, and the router does
+ * not re-run that check at dispatch time.
+ */
+export function backendHasIntegrationConnector(integrationKey, backendId) {
+    return INTEGRATION_DESCRIPTORS[integrationKey].backendConnectors[backendId] !== undefined;
+}
+// ── §7.7: Tool-deny policy validation + helpers ──────────────────────────────
+/**
+ * DELEGATED-MODE-V2-DESIGN.md §4.3.5 — match a deny pattern against a single
+ * tool name. Patterns are bare unsuffixed tool names — no `mcp__*` prefix,
+ * no leading underscore (the connector's `toolNamespace` already terminates
+ * as needed; e.g. Codex Gmail's namespace is `mcp__codex_apps__gmail._`,
+ * so the bare match key is `send_email`, not `_send_email`). Optionally
+ * suffixed with `*`:
+ *
+ *   `send_email`      — exact match
+ *   `send_*`          — prefix match, anything starting with `send_`
+ *   `*`               — matches anything (deny everything; rare)
+ *
+ * Anchors are implicit; `*` is only honored as a suffix to keep the pattern
+ * language single-purpose. `*` mid-string is treated as literal text.
+ *
+ * Used by `validateDeniedTools` (typo defense at PATCH time),
+ * `filterDeniedToolsForBackend` (active/stale partition during
+ * materialization), and the `/api/integrations/:key/invoke` chokepoint
+ * (per-call deny enforcement).
+ */
+export function matchToolPattern(pattern, tool) {
+    if (pattern === tool)
+        return true;
+    if (pattern.endsWith("*")) {
+        const prefix = pattern.slice(0, -1);
+        return tool.startsWith(prefix);
+    }
+    return false;
+}
+/**
+ * Expand a deny pattern against a connector's known-tool universe. Exact
+ * patterns return `[pattern]` if known, `[]` if not. Glob patterns return
+ * the subset of known tools whose name starts with the prefix.
+ *
+ * Pure data — both inputs come from the integration registry, no I/O.
+ */
+function expandDenyPattern(pattern, knownTools) {
+    if (pattern.endsWith("*")) {
+        const prefix = pattern.slice(0, -1);
+        const out = [];
+        for (const tool of knownTools) {
+            if (tool.startsWith(prefix))
+                out.push(tool);
+        }
+        return out;
+    }
+    return knownTools.has(pattern) ? [pattern] : [];
+}
+/**
+ * Validate a proposed `deniedTools` list against an integration's
+ * descriptor for a given `delegatedBackend`. Returns the first failure;
+ * callers map this to the documented 400 shapes.
+ *
+ * Patterns: each entry is either an exact tool name (e.g. `_send_email`)
+ * or a `*`-suffixed glob (e.g. `_delete_*`, `*`). See {@link matchToolPattern}.
+ *
+ *  - **`unknown_tool`**: an exact entry isn't in any of the connector's
+ *    `capabilityTools` arrays, OR a glob entry matches no known tool
+ *    (typo defense for both forms). Helps users catch typos and stale
+ *    Claude / Codex names after a backend swap. (Note: the *materializer*
+ *    tolerates stale entries silently per §7.7 — but PATCH is strict so
+ *    the user sees the typo before saving. The dashboard's stale-entries
+ *    UI handles the soft case after a backend flip.)
+ *  - **`denial_breaks_required_capability`**: collectively, the proposal
+ *    drops every tool that satisfies at least one `requiredCapability`.
+ *    Multi-cap overlap matters — Notion's `notion-update-page` covers
+ *    `update_properties`, `patch_content`, `archive`, and `apply_template`,
+ *    so denying it breaks all four required caps at once. The error names
+ *    the first failing capability and lists what's still in the
+ *    `capabilityTools[capability]` set after the deny — so the dashboard
+ *    can show a "you'd need to keep X, Y, or Z" hint without a second call.
+ *    Globs are expanded against the connector's known tools before the
+ *    capability-coverage check runs.
+ */
+export function validateDeniedTools(integrationKey, backendId, deniedTools) {
+    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
+    const connector = descriptor.backendConnectors[backendId];
+    // Forward-compat: today every (integrationKey, BackendId) pair has a
+    // connector — this branch is reserved for a future integration that
+    // omits one. See integrations.test.ts for the assertion that BackendId
+    // membership is exhaustive.
+    /* c8 ignore next 3 */
+    if (!connector) {
+        return { ok: false, error: "no_connector", backendId };
+    }
+    // Compute the known-tool universe once: union of every tool name appearing
+    // in any capabilityTools entry. Used for both unknown-tool detection and
+    // for the remaining-tools error payload.
+    const knownToolSet = new Set();
+    for (const tools of Object.values(connector.capabilityTools)) {
+        for (const t of tools)
+            knownToolSet.add(t);
+    }
+    // Validate each pattern, then expand globs into concrete tool names so the
+    // capability-coverage check below can see the full impact.
+    const expandedDenied = new Set();
+    for (const tool of deniedTools) {
+        const matches = expandDenyPattern(tool, knownToolSet);
+        if (matches.length === 0) {
+            // Exact-name typo or a glob that matches nothing in the connector.
+            return {
+                ok: false,
+                error: "unknown_tool",
+                tool,
+                knownTools: [...knownToolSet].sort(),
+            };
+        }
+        for (const m of matches)
+            expandedDenied.add(m);
+    }
+    for (const capability of connector.requiredCapabilities) {
+        // every requiredCapability is keyed in capabilityTools via the
+        // descriptor self-consistency test; the `?? []` is defensive
+        // against future descriptor edits that drop a capability mapping.
+        /* c8 ignore next */
+        const tools = connector.capabilityTools[capability] ?? [];
+        const remaining = tools.filter((t) => !expandedDenied.has(t));
+        if (remaining.length === 0) {
+            // Surface the capability + what would still be available if the user
+            // un-denied at least one of these. Lets the dashboard render an
+            // actionable hint without a second round-trip.
+            return {
+                ok: false,
+                error: "denial_breaks_required_capability",
+                capability,
+                remainingTools: tools,
+            };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Filter a `deniedTools` list down to entries that exist in the active
+ * backend's capability tools, expanding glob patterns. Used by the
+ * materializer to silently drop stale names after a `delegatedBackend`
+ * swap (§7.7 mode-flip behavior) and by `collectSessionDeniedTools` to
+ * produce concrete namespaced tool names for backend `disallowedTools`.
+ *
+ * The output `active` list is the **expanded** concrete tool name set
+ * (globs replaced by their matches) so callers can feed it directly into
+ * an SDK `disallowedTools` array or `applyDeniedTools`. `stale` carries
+ * the original user-entered patterns that matched nothing on this
+ * backend's tool universe (typo or post-swap leftover).
+ *
+ * Distinct from `validateDeniedTools` — the API rejects unknown tools at
+ * PATCH time, but a user who flips claude → codex carries Claude-namespaced
+ * entries that the API didn't see at PATCH time. The materializer ignores
+ * them; the dashboard surfaces them as "stale" so the user can clean up.
+ */
+export function filterDeniedToolsForBackend(integrationKey, backendId, deniedTools) {
+    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
+    const connector = descriptor.backendConnectors[backendId];
+    // Forward-compat: see validateDeniedTools comment above.
+    /* c8 ignore next */
+    if (!connector)
+        return { active: [], stale: [...deniedTools] };
+    const known = new Set();
+    for (const tools of Object.values(connector.capabilityTools)) {
+        for (const t of tools)
+            known.add(t);
+    }
+    const activeSet = new Set();
+    const stale = [];
+    for (const pattern of deniedTools) {
+        const matches = expandDenyPattern(pattern, known);
+        if (matches.length === 0) {
+            stale.push(pattern);
+            continue;
+        }
+        for (const m of matches)
+            activeSet.add(m);
+    }
+    return { active: [...activeSet], stale };
+}
+/**
+ * DELEGATED-MODE-V2-DESIGN.md §4.5.4 — recommended starter denylist used
+ * by the setup wizard / PATCH route when the user first picks delegated
+ * mode for an integration. The list errs conservative: strictly-destructive
+ * ops (send / trash / delete) are always denied; reversible-but-easy-to-
+ * lose-track-of ops (archive / mass-relabel / event-update) are denied so
+ * the agent can't silently churn through cleanup work. The user opts out
+ * explicitly per §4.5.4.
+ *
+ * Keyed on `(integrationKey, backendId)` because the same logical
+ * destructive op uses different tool names per connector — Codex's Gmail
+ * uses `_send_email`, Claude's Gmail has no send tool at all (the
+ * connector is draft-only). Backends without a starter list resolve to
+ * `[]` (no floor — caller can still PATCH explicit denies).
+ *
+ * The list contains only tool names already declared in the connector's
+ * `capabilityTools`, so `validateDeniedTools` accepts them without the
+ * `*`-glob extension.
+ */
+const RECOMMENDED_STARTER_DENIED_TOOLS = {
+    gmail: {
+        // Codex's Gmail descriptor lists `send` in `requiredCapabilities` with
+        // `["send_email", "send_draft"]`. Denying both would remove every path
+        // to satisfy `send`, which `validateDeniedTools` rejects. The starter
+        // list therefore denies `send_email` only — the irreversible "compose
+        // and send right now" path — and leaves `send_draft` (send a previously
+        // drafted message, which the user already vetted in the UI) available.
+        // `delete_emails` and `archive_emails` together empty the optional
+        // `delete` capability, which the validator allows. `apply_labels_to_emails`
+        // is one of three tools in `label`; the floor is conservative without
+        // breaking the capability.
+        codex: [
+            "send_email",
+            "delete_emails",
+            "archive_emails",
+            "apply_labels_to_emails",
+        ],
+        // Claude's hosted Gmail connector is draft-only (no send/delete);
+        // label mutations are the only mutating ops. `label_message` and
+        // `label_thread` deny 2 of 5 tools in `label`, keeping the capability
+        // satisfiable.
+        claude: ["label_message", "label_thread"],
+        // Gemini's google-workspace connector. `send` covers
+        // compose-and-send-now (irreversible); `sendDraft` stays available
+        // so the agent can dispatch a draft the user already vetted in the
+        // UI. `batchModify` is the mass-mutation path; default-deny it the
+        // way Codex's `apply_labels_to_emails` is denied. `modify` /
+        // `modifyThread` are kept available — they're the only label-write
+        // path the connector exposes, so denying them empties the required
+        // `label` capability.
+        gemini: ["send", "batchModify"],
+    },
+    google_calendar: {
+        codex: ["delete_event", "update_event"],
+        claude: ["delete_event", "update_event"],
+        gemini: ["deleteEvent", "updateEvent"],
+    },
+};
+/**
+ * Lookup the recommended starter denylist for `(integrationKey,
+ * backendId)`. Returns a fresh array each call so the caller can store it
+ * directly without aliasing the registry constant.
+ */
+export function recommendedStarterDeniedTools(integrationKey, backendId) {
+    const list = RECOMMENDED_STARTER_DENIED_TOOLS[integrationKey]?.[backendId] ?? [];
+    return [...list];
+}
+/**
+ * DELEGATED-TASK-MODE-DESIGN.md §7.3 — destructive tool list for
+ * `(integrationKey, backendId)`, returned as **fully-qualified names**
+ * (`toolNamespace + bareName`). Used by `runDelegatedTask` to feed into
+ * SDK `disallowedTools` (Claude) or admin-policy deny rules (Gemini)
+ * when `allowDestructive: false`.
+ *
+ * Returns `[]` when the backend has no connector for the integration
+ * (forward-compat: this never happens today; every backend has a
+ * connector for every registered integration).
+ */
+export function destructiveTaskTools(integrationKey, backendId) {
+    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
+    const connector = descriptor.backendConnectors[backendId];
+    /* c8 ignore next */
+    if (!connector)
+        return [];
+    return connector.destructiveTools.map((t) => `${connector.toolNamespace}${t}`);
+}
+/**
+ * DELEGATED-TASK-MODE-DESIGN.md §7.3 — bare-name version of
+ * {@link destructiveTaskTools}, returned WITHOUT the `toolNamespace`
+ * prefix. Used by anti-prompt-injection assertions and by callers that
+ * already namespace separately.
+ */
+export function destructiveTaskToolsBare(integrationKey, backendId) {
+    const descriptor = INTEGRATION_DESCRIPTORS[integrationKey];
+    const connector = descriptor.backendConnectors[backendId];
+    /* c8 ignore next */
+    if (!connector)
+        return [];
+    return [...connector.destructiveTools];
+}
+/**
+ * DELEGATED-MODE-V2-DESIGN.md §4.3.3 — collect every `deniedTools` entry
+ * that applies to the **session backend's own native MCP** (the
+ * "same-backend" delegated state). For each integration whose
+ * `delegatedBackend === sessionBackend`, expand the user's deny patterns
+ * against the connector's known tools and return the namespaced tool names
+ * (`mcp__<connector>__<tool>`) ready to drop into:
+ *
+ *   - Claude Code SDK `disallowedTools` array (hard enforcement)
+ *   - Gemini admin policy `denied_tools` rules (hard enforcement)
+ *   - Codex agent profile prose block (soft enforcement — accepted gap,
+ *     §4.3.4 outcome γ)
+ *
+ * Cross-backend (delegatedBackend !== sessionBackend) integrations are
+ * excluded — those calls go through `/api/integrations/:key/invoke` which
+ * enforces deny at the daemon chokepoint (§4.3.2). Disabled / direct
+ * integrations are excluded — deny only applies to delegated mode.
+ *
+ * Returns a `Map` keyed by integration so callers can attribute denies
+ * per-integration in logs / prose. Empty entries are omitted.
+ */
+export function collectSessionDeniedTools(integrations, sessionBackend) {
+    const out = new Map();
+    for (const key of INTEGRATION_KEYS) {
+        const state = integrations[key];
+        if (!state || state.mode !== "delegated")
+            continue;
+        if (state.delegatedBackend !== sessionBackend)
+            continue;
+        // Zod schema defaults deniedTools to `[]`; the `?? []` is defensive
+        // against legacy state objects predating the default.
+        /* c8 ignore next */
+        const denied = state.deniedTools ?? [];
+        if (denied.length === 0)
+            continue;
+        const descriptor = INTEGRATION_DESCRIPTORS[key];
+        const connector = descriptor.backendConnectors[sessionBackend];
+        // Forward-compat: every (integration, backend) pair currently has a
+        // connector. This branch survives in code as registry drift insurance.
+        /* c8 ignore next */
+        if (!connector)
+            continue;
+        const { active } = filterDeniedToolsForBackend(key, sessionBackend, denied);
+        if (active.length === 0)
+            continue;
+        const namespaced = active.map((t) => `${connector.toolNamespace}${t}`);
+        out.set(key, namespaced);
+    }
+    return out;
+}
+// ── Mode-conditional section filter ──────────────────────────────────────────
+/**
+ * Predicates accepted by `applyIntegrationModeFilter`. Each one keeps the
+ * wrapped section when its condition holds for the given integration key
+ * and session backend.
+ */
+export const INTEGRATION_MODE_PREDICATES = [
+    "direct",
+    "delegated",
+    "delegated-same",
+    "delegated-cross",
+    "disabled",
+];
+const integrationModePredicateSet = new Set(INTEGRATION_MODE_PREDICATES);
+/**
+ * Strip mode-conditional sections from a task-flow or skill body based on
+ * current integration state and session backend. Mirrors the
+ * `<!-- service:* -->` family used by `stripUnconfiguredServices` in
+ * skills-compiler.ts.
+ *
+ * Section syntax (HTML comment delimiters, kept literal so authoring stays
+ * markdown-friendly):
+ *
+ *   <!-- mode:<predicate>:<key> -->
+ *   ...content shown only when the predicate holds...
+ *   <!-- /mode:<predicate>:<key> -->
+ *
+ * Predicates and the state they keep content for:
+ *
+ *   direct           — `integrations[key].mode === "direct"`
+ *   delegated        — `mode === "delegated"` (regardless of which backend)
+ *   delegated-same   — delegated AND `delegatedBackend === sessionBackend`
+ *                      (the connector is signed in to this same session's
+ *                      backend; the agent uses native MCP tools and skill
+ *                      bodies are typically not materialized)
+ *   delegated-cross  — delegated AND `delegatedBackend !== sessionBackend`
+ *                      (the agent reaches the connector via the daemon
+ *                      proxy at `POST /api/integrations/:key/invoke`)
+ *   disabled         — `mode === "disabled"` OR no state row (treated as
+ *                      disabled by `defaultIntegrationsMap`)
+ *
+ * Behaviour notes:
+ *
+ *  - **Unknown predicate**: section preserved verbatim. Surfaces the typo in
+ *    the rendered prompt rather than silently losing or duplicating prose.
+ *  - **Unknown integration key**: section preserved verbatim. Same rationale —
+ *    a misspelled key (or registry drift mid-deploy) should remain visible.
+ *  - **Sections do not nest**: the regex is non-greedy and matches the
+ *    first close tag. Two sibling blocks at the same level work; nesting
+ *    a same-key block inside another doesn't and is unsupported.
+ *  - **Idempotent**: running the filter twice on the same content with the
+ *    same state produces identical output.
+ *
+ * Apply this AFTER any whole-file variant selection (e.g. `SKILL.delegated.
+ * <backend>.md`) so the variant author can use mode markers freely without
+ * worrying about pre-filtering interactions.
+ */
+export function applyIntegrationModeFilter(content, integrations, sessionBackend) {
+    return content.replace(/<!-- mode:([a-z][a-z-]*):([a-z_][a-z0-9_]*) -->\n?([\s\S]*?)<!-- \/mode:\1:\2 -->\n?/g, (match, predicate, key, body) => {
+        if (!integrationModePredicateSet.has(predicate))
+            return match;
+        if (!isIntegrationKey(key))
+            return match;
+        const keep = evaluateIntegrationModePredicate(predicate, integrations[key], sessionBackend);
+        return keep ? body : "";
+    });
+}
+function evaluateIntegrationModePredicate(predicate, state, sessionBackend) {
+    // Treat missing state as disabled (matches `defaultIntegrationsMap`).
+    const mode = state?.mode ?? "disabled";
+    const delegatedBackend = state?.delegatedBackend ?? null;
+    switch (predicate) {
+        case "direct":
+            return mode === "direct";
+        case "delegated":
+            return mode === "delegated";
+        case "delegated-same":
+            return mode === "delegated" && delegatedBackend === sessionBackend;
+        case "delegated-cross":
+            return (mode === "delegated"
+                && delegatedBackend !== null
+                && delegatedBackend !== sessionBackend);
+        case "disabled":
+            return mode === "disabled";
+    }
+}
+// ── DELEGATED-TASK-MODE-DESIGN.md §4.2 — `/api/delegated/run` allowedTools ───
+/**
+ * Validation regex for an `allowedTools` entry on `POST /api/delegated/run`
+ * (Phase 2 generic task mode for unregistered MCPs).
+ *
+ * Spec §4.2 reads: "Specifically rejected: bare `*`, patterns starting with
+ * `*`, prefixes shorter than 4 characters before `*` (e.g. `mcp_*`), and
+ * anything containing shell metacharacters." The literal example `mcp_*`
+ * has a 4-character prefix yet must be rejected — i.e. the spec's prose
+ * intent is "≥5 chars before `*`," and the {4,} quantifier in the literal
+ * regex contradicts the example. We honor the example: prefix-before-`*`
+ * must be ≥5 chars, and bare/leading `*` is rejected outright.
+ *
+ * Allowed shape:
+ *   - 5+ chars of `[A-Za-z0-9_-]` to start.
+ *   - Optional dotted/underscored continuation segments
+ *     (`([._][A-Za-z0-9_-]+)*`).
+ *   - Optional trailing `*` for a glob.
+ *
+ * Examples accepted: `mcp_my-server_*`, `mcp_my-server_subtool.action`,
+ * `mcp__custom-srv_doIt`. Examples rejected: `*`, `*foo`, `mcp_*`,
+ * `mcp_my-server_*.action`, `srv;rm -rf /`.
+ *
+ * Shell-metacharacter rejection is doubled-up: even if a pattern slipped
+ * through the regex (it can't — the character class excludes them), the
+ * dedicated check in {@link validateRunAllowedTool} would reject. This
+ * keeps the safety floor obvious in review.
+ */
+export const MCP_PATTERN_REGEX = /^[A-Za-z0-9_-]{5,}([._][A-Za-z0-9_-]+)*\*?$/;
+/**
+ * Shell metacharacters not allowed anywhere in an `allowedTools` entry.
+ * The regex above already excludes them from the character class, but a
+ * standalone check is what {@link validateRunAllowedTool} cites in its
+ * `bad_allowed_tools` message so callers see *why* the pattern was rejected
+ * (without re-deriving from the regex).
+ */
+const SHELL_METACHAR_RE = /[;&|`$()<>'"\\\s\n\r\t{}\[\]?#~^!=,]/;
+/** Validate a single pattern entry. Exported for unit tests. */
+export function validateRunAllowedTool(pattern) {
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        return {
+            ok: false,
+            errorClass: "bad_allowed_tools",
+            pattern: typeof pattern === "string" ? pattern : "",
+            reason: "empty",
+            message: "allowedTools entries must be non-empty strings",
+        };
+    }
+    if (pattern === "*") {
+        return {
+            ok: false,
+            errorClass: "bad_allowed_tools",
+            pattern,
+            reason: "bare_star",
+            message: "bare `*` is not an allowed pattern — it would match every tool",
+        };
+    }
+    if (pattern.startsWith("*")) {
+        return {
+            ok: false,
+            errorClass: "bad_allowed_tools",
+            pattern,
+            reason: "leading_star",
+            message: "patterns must not start with `*` — anchor with a literal prefix",
+        };
+    }
+    if (SHELL_METACHAR_RE.test(pattern)) {
+        return {
+            ok: false,
+            errorClass: "bad_allowed_tools",
+            pattern,
+            reason: "shell_metachar",
+            message: "patterns must not contain shell metacharacters or whitespace",
+        };
+    }
+    // Trailing-star prefix length must be ≥5; the regex enforces this, but
+    // we surface a clearer error class for the common typo.
+    if (pattern.endsWith("*")) {
+        const prefix = pattern.slice(0, -1);
+        if (prefix.length < 5) {
+            return {
+                ok: false,
+                errorClass: "bad_allowed_tools",
+                pattern,
+                reason: "prefix_too_short",
+                message: "glob prefix must be at least 5 characters before `*` (e.g. `mcp_my-server_*`)",
+            };
+        }
+    }
+    if (!MCP_PATTERN_REGEX.test(pattern)) {
+        return {
+            ok: false,
+            errorClass: "bad_allowed_tools",
+            pattern,
+            reason: "shape_invalid",
+            message: "pattern must match ^[A-Za-z0-9_-]{5,}([._][A-Za-z0-9_-]+)*\\*?$ — letters/digits/underscores/dashes with optional `._`-separated segments and an optional trailing `*`",
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Validate every entry in a `/api/delegated/run` `allowedTools` array.
+ * Returns the first failing entry (HTTP 400 maps to that), or `{ok: true}`
+ * if every pattern is well-formed and the array is non-empty.
+ */
+export function validateRunAllowedTools(patterns) {
+    if (!Array.isArray(patterns) || patterns.length === 0) {
+        return {
+            ok: false,
+            errorClass: "bad_allowed_tools",
+            pattern: "",
+            reason: "empty",
+            message: "allowedTools must be a non-empty array",
+        };
+    }
+    for (const p of patterns) {
+        const r = validateRunAllowedTool(p);
+        if (!r.ok)
+            return r;
+    }
+    return { ok: true };
+}
+/**
+ * Match an `/api/delegated/run` allowedTools entry against a fully
+ * qualified tool name observed in the subprocess stream. Mirrors the
+ * `matchToolPattern` semantics used elsewhere — exact equality or
+ * `*`-suffix prefix match — but the input space is fully-qualified MCP
+ * names, not the bare deny vocabulary, so we expose it as a separate
+ * symbol.
+ */
+export function matchRunAllowedToolPattern(pattern, tool) {
+    if (pattern === tool)
+        return true;
+    if (pattern.endsWith("*")) {
+        const prefix = pattern.slice(0, -1);
+        return tool.startsWith(prefix);
+    }
+    return false;
+}
+//# sourceMappingURL=integrations.js.map