@aitne/shared 0.1.0

package/dist/integrations.d.ts

@@ -0,0 +1,675 @@
+import { z } from "zod";
+import { type BackendId } 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 declare const INTEGRATION_KEYS: readonly ["gmail", "google_calendar", "notion", "git", "github", "outlook_mail", "outlook_calendar"];
+export type IntegrationKey = (typeof INTEGRATION_KEYS)[number];
+export declare function isIntegrationKey(value: string): value is IntegrationKey;
+export declare const INTEGRATION_MODES: readonly ["direct", "delegated", "disabled"];
+export type IntegrationMode = (typeof INTEGRATION_MODES)[number];
+export declare function isIntegrationMode(value: string): value is IntegrationMode;
+export interface IntegrationBackendConnector {
+    /** Prefix that vendor-shipped MCP tools share, e.g. `mcp__claude_ai_Gmail__`. */
+    toolNamespace: string;
+    /** Capabilities that must all be present for delegated mode to be offered. */
+    requiredCapabilities: readonly string[];
+    /** Capabilities the feature matrix renders from (tick/cross UI). */
+    optionalCapabilities: readonly string[];
+    /**
+     * Maps each capability name to the unsuffixed tool names that satisfy it.
+     * Used by the probe to translate a live MCP tool list into per-capability
+     * presence. Tool names are the part after `toolNamespace` (e.g. for the
+     * Claude Gmail connector `toolNamespace = "mcp__claude_ai_Gmail__"`,
+     * `"search"` maps to `["search_threads"]`).
+     *
+     * Every capability listed in `requiredCapabilities` ∪ `optionalCapabilities`
+     * MUST have an entry here. An empty array means "no shipped tool satisfies
+     * this capability" (always absent in the probe). The registry
+     * self-consistency test in `integration-probe.test.ts` enforces this.
+     */
+    capabilityTools: Readonly<Record<string, readonly string[]>>;
+    /**
+     * DELEGATED-TASK-MODE-DESIGN.md §7.3 — bare tool names (same form as
+     * `capabilityTools` values) whose invocation mutates user-visible state
+     * in a way that requires explicit confirmation per the CLAUDE.md
+     * "destructive ops require user confirmation" invariant. Concrete tool
+     * names rather than capability keys because some capabilities mix reads
+     * and writes (Gemini Gmail's `label` covers `listLabels` (read) and
+     * `modify` (write)); a tool-level list lets us deny the writes without
+     * classifying the read as destructive.
+     *
+     * Used by:
+     *   - Task mode `runDelegatedTask`: when `allowDestructive: false`,
+     *     these are removed from the SDK's `allowedTools` (Claude) /
+     *     emitted as priority-998 deny rules (Gemini), and the subprocess
+     *     is instructed to return `{needsConfirmation, confirmationPlan}`.
+     *   - The `destructive-coverage.test.ts` drift test asserts every entry
+     *     in `RECOMMENDED_STARTER_DENIED_TOOLS` for this connector appears
+     *     here (i.e. the recommended starter list is a subset of the
+     *     descriptor's destructive set).
+     *
+     * Every entry MUST also appear in some `capabilityTools[k]` array — a
+     * destructive tool the descriptor doesn't otherwise know about would be
+     * dead weight. Enforced by the same self-consistency test that covers
+     * the rest of the descriptor surface.
+     */
+    destructiveTools: readonly string[];
+}
+export interface IntegrationDirectSetup {
+    /** Keychain keys that must be present for direct mode to function. */
+    credentialKeys: readonly string[];
+    /** Documentation URL shown in the setup wizard and dashboard cards. */
+    helpUrl: string;
+}
+export interface IntegrationDescriptor {
+    key: IntegrationKey;
+    displayName: string;
+    supportedModes: readonly IntegrationMode[];
+    directSetup?: IntegrationDirectSetup;
+    backendConnectors: Partial<Record<BackendId, IntegrationBackendConnector>>;
+    /** Skill slugs whose bodies depend on this integration. Declarative only in Phase 1. */
+    skillsTouched: readonly string[];
+    /** Task-flow keys same. Declarative only in Phase 1. */
+    taskFlowsTouched: readonly string[];
+    /**
+     * Runtime observer names gated by `integration.mode === "direct"`. Each
+     * string is the value the observer exposes via its `Observer.name`
+     * property — `ObserverManager.has()` / `stopAndUnregister()` look up by
+     * that exact key. (The design doc uses class names like `MailPoller`
+     * for human readability; the registry uses the runtime name so the
+     * lifecycle module can act without a translation table.)
+     */
+    observersTouched: readonly string[];
+    /**
+     * Path prefixes the registry middleware 410-gates when delegated. The
+     * 410 is **defense-in-depth** in v2 (DELEGATED-MODE-V2-DESIGN.md §6.3):
+     * cross-backend skill prose directs the agent at
+     * `POST /api/integrations/:key/invoke`, and same-backend skill is not
+     * provisioned at all. The gate fires only when the agent invents a
+     * call the variant prose did not teach it.
+     *
+     * Multi-provider routes (e.g. Gmail under `/api/mail/*`) are
+     * intentionally NOT listed here — prefix matching would also block
+     * other providers (iCloud, Outlook, IMAP). Per-account 410 inside the
+     * route handler covers those cases. Single-provider surfaces like
+     * `/api/calendar` can be listed safely.
+     */
+    apiRoutesTouched: readonly string[];
+    /**
+     * Skill slugs whose `SKILL.md` body should be filtered by this
+     * integration's `deniedTools` independently of `skillsTouched` —
+     * forward-compat hook for skill bodies that touch the integration but
+     * should not trigger variant resolution. Today, `skillsTouched`
+     * already covers every body that needs the deny pass; this field
+     * remains for symmetry with non-default-variant cases.
+     */
+    deniedToolsAppliesToSkills?: readonly string[];
+    /**
+     * Subset of `skillsTouched` whose body the integration's same-backend
+     * connector tools fully cover. When `selectSkillVariantFile` resolves
+     * to "same-backend", a touched skill is dropped (returns `null`) only
+     * if EVERY touching integration declares it here. Skills broader than
+     * the integration (e.g. `mail` covers IMAP/Outlook on top of Gmail;
+     * `external-services` covers Obsidian/GitHub/scheduling on top of
+     * Google Calendar) must NOT appear here — dropping them would orphan
+     * the non-delegated functionality. Skills that are pure connector
+     * wrappers (e.g. `notion` is solely Notion) belong here.
+     */
+    sameBackendDropsSkillBody?: readonly string[];
+    /**
+     * Marks an integration whose delegated mode relies on an MCP server or
+     * connector the user installs on the agent backend (Claude Code / Codex /
+     * Gemini CLI) themselves. The daemon does not ship a tool inventory for
+     * these connectors, so:
+     *   - `backendConnectors` may be empty (no descriptor-driven feature
+     *     matrix or capability probe).
+     *   - The PATCH `/integrations/:key` endpoint accepts any `delegatedBackend`
+     *     supported by the daemon — capability probing is the user's
+     *     responsibility on the backend side.
+     *   - The probe and route-gate surfaces fall back to a generic
+     *     "user-managed connector" path that does not enforce the daemon's
+     *     normal tool-inventory checks.
+     *
+     * Today: `outlook_mail` and `outlook_calendar`. Microsoft does not ship
+     * a hosted MCP connector for Claude / Codex / Gemini; users register an
+     * Outlook / Microsoft Graph MCP server on their backend (Claude Code
+     * Connector, Codex MCP, Gemini extension) and we trust that wiring.
+     */
+    userManagedConnector?: boolean;
+}
+/**
+ * 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 declare const INTEGRATION_DESCRIPTORS: Readonly<Record<IntegrationKey, IntegrationDescriptor>>;
+export declare function getIntegrationDescriptor(key: IntegrationKey): IntegrationDescriptor;
+export declare function listIntegrationDescriptors(): readonly IntegrationDescriptor[];
+/**
+ * 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 declare const integrationStateSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        direct: "direct";
+        delegated: "delegated";
+        disabled: "disabled";
+    }>;
+    delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        gemini: "gemini";
+    }>>>>;
+    delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+    deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    lastChangedAt: z.ZodString;
+}, z.core.$strip>;
+export type IntegrationState = z.infer<typeof integrationStateSchema>;
+/**
+ * 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 declare const integrationsMapSchema: z.ZodObject<{
+    git: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            direct: "direct";
+            delegated: "delegated";
+            disabled: "disabled";
+        }>;
+        delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+        }>>>>;
+        delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+        deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        lastChangedAt: z.ZodString;
+    }, z.core.$strip>>;
+    gmail: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            direct: "direct";
+            delegated: "delegated";
+            disabled: "disabled";
+        }>;
+        delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+        }>>>>;
+        delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+        deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        lastChangedAt: z.ZodString;
+    }, z.core.$strip>>;
+    google_calendar: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            direct: "direct";
+            delegated: "delegated";
+            disabled: "disabled";
+        }>;
+        delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+        }>>>>;
+        delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+        deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        lastChangedAt: z.ZodString;
+    }, z.core.$strip>>;
+    notion: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            direct: "direct";
+            delegated: "delegated";
+            disabled: "disabled";
+        }>;
+        delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+        }>>>>;
+        delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+        deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        lastChangedAt: z.ZodString;
+    }, z.core.$strip>>;
+    github: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            direct: "direct";
+            delegated: "delegated";
+            disabled: "disabled";
+        }>;
+        delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+        }>>>>;
+        delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+        deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        lastChangedAt: z.ZodString;
+    }, z.core.$strip>>;
+    outlook_mail: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            direct: "direct";
+            delegated: "delegated";
+            disabled: "disabled";
+        }>;
+        delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+        }>>>>;
+        delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+        deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        lastChangedAt: z.ZodString;
+    }, z.core.$strip>>;
+    outlook_calendar: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            direct: "direct";
+            delegated: "delegated";
+            disabled: "disabled";
+        }>;
+        delegatedBackend: z.ZodOptional<z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            gemini: "gemini";
+        }>>>>;
+        delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+        deniedTools: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        lastChangedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type IntegrationsMap = Partial<Record<IntegrationKey, IntegrationState>>;
+/** Build the default integration map used for fresh installs. */
+export declare function defaultIntegrationsMap(now?: string): Record<IntegrationKey, IntegrationState>;
+/**
+ * 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 declare const integrationPatchSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        direct: "direct";
+        delegated: "delegated";
+        disabled: "disabled";
+    }>;
+    delegatedBackend: z.ZodNullable<z.ZodOptional<z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        gemini: "gemini";
+    }>>>;
+    delegatedModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    delegatedMaxTurns: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    delegatedSyncEnabled: z.ZodOptional<z.ZodBoolean>;
+    deniedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type IntegrationPatch = z.infer<typeof integrationPatchSchema>;
+/**
+ * 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 declare function selectSkillVariantFile(skillSlug: string, sessionBackend: BackendId, integrations: Partial<Record<IntegrationKey, IntegrationState>>): string | null;
+/**
+ * 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 declare function selectTaskFlowVariantSuffix(taskFlowKey: string, backendId: BackendId, integrations: Partial<Record<IntegrationKey, IntegrationState>>): string;
+/**
+ * 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 declare function delegatedIntegrationsForProcessKey(processKey: string, integrations: Partial<Record<IntegrationKey, IntegrationState>>): IntegrationKey[];
+/**
+ * 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 declare function backendHasIntegrationConnector(integrationKey: IntegrationKey, backendId: BackendId): boolean;
+/**
+ * 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 declare function matchToolPattern(pattern: string, tool: string): boolean;
+export type ValidateDeniedToolsResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: "no_connector";
+    backendId: BackendId;
+} | {
+    ok: false;
+    error: "unknown_tool";
+    tool: string;
+    knownTools: readonly string[];
+} | {
+    ok: false;
+    error: "denial_breaks_required_capability";
+    capability: string;
+    remainingTools: readonly string[];
+};
+/**
+ * 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 declare function validateDeniedTools(integrationKey: IntegrationKey, backendId: BackendId, deniedTools: readonly string[]): ValidateDeniedToolsResult;
+/**
+ * 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 declare function filterDeniedToolsForBackend(integrationKey: IntegrationKey, backendId: BackendId, deniedTools: readonly string[]): {
+    active: string[];
+    stale: string[];
+};
+/**
+ * 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 declare function recommendedStarterDeniedTools(integrationKey: IntegrationKey, backendId: BackendId): string[];
+/**
+ * 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 declare function destructiveTaskTools(integrationKey: IntegrationKey, backendId: BackendId): string[];
+/**
+ * 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 declare function destructiveTaskToolsBare(integrationKey: IntegrationKey, backendId: BackendId): string[];
+/**
+ * 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 declare function collectSessionDeniedTools(integrations: Partial<Record<IntegrationKey, IntegrationState>>, sessionBackend: BackendId): Map<IntegrationKey, string[]>;
+/**
+ * Predicates accepted by `applyIntegrationModeFilter`. Each one keeps the
+ * wrapped section when its condition holds for the given integration key
+ * and session backend.
+ */
+export declare const INTEGRATION_MODE_PREDICATES: readonly ["direct", "delegated", "delegated-same", "delegated-cross", "disabled"];
+export type IntegrationModePredicate = (typeof INTEGRATION_MODE_PREDICATES)[number];
+/**
+ * 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 declare function applyIntegrationModeFilter(content: string, integrations: Partial<Record<IntegrationKey, IntegrationState>>, sessionBackend: BackendId): string;
+/**
+ * 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 declare const MCP_PATTERN_REGEX: RegExp;
+export type ValidateRunAllowedToolsResult = {
+    ok: true;
+} | {
+    ok: false;
+    errorClass: "bad_allowed_tools";
+    pattern: string;
+    reason: "empty" | "bare_star" | "leading_star" | "prefix_too_short" | "shell_metachar" | "shape_invalid";
+    message: string;
+};
+/** Validate a single pattern entry. Exported for unit tests. */
+export declare function validateRunAllowedTool(pattern: unknown): ValidateRunAllowedToolsResult;
+/**
+ * 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 declare function validateRunAllowedTools(patterns: readonly unknown[]): ValidateRunAllowedToolsResult;
+/**
+ * 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 declare function matchRunAllowedToolPattern(pattern: string, tool: string): boolean;
+//# sourceMappingURL=integrations.d.ts.map