@aitne/daemon 0.1.0

package/dist/api/routes/integrations.js

@@ -0,0 +1,1384 @@
+import { Hono } from "hono";
+import { BACKEND_IDS, DELEGATED_TASK_HARD_CAPS, INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, filterDeniedToolsForBackend, integrationPatchSchema, isIntegrationKey, recommendedStarterDeniedTools, validateDeniedTools, } from "@aitne/shared";
+// `matchToolPattern` and `mapErrorClassToHttpStatus` were used by the
+// dormant `/invoke` route reservation block-commented at lines ~708-896.
+// They are removed from the import list because eslint flags them as
+// unused; re-add when un-commenting that block.
+import { checkOutputSchema } from "../../services/delegated-task-runtime.js";
+import { readIntegrations, updateIntegrationState, } from "../../db/integrations-store.js";
+import { writeManagementMd } from "../../core/management-md.js";
+import { missingDelegatedVariants } from "../../core/skills-compiler.js";
+import { evaluateProbe, getConnector, makeUserManagedProbeResult, } from "../../core/integration-probe.js";
+import { LiveProbeUnsupportedError } from "../../core/agent-core.js";
+import { deleteProbesForIntegration, readProbe, writeProbe, } from "../../db/integration-probe-store.js";
+import { knownProxyModels, listProxyModelOptions, proxyModelIsKnown, resolveCanonicalDelegatedModel, } from "../../core/backends/proxy-model-registry.js";
+import { readJsonBody } from "../json-body.js";
+import { createLogger } from "../../logging.js";
+import { extractWriteItemIds } from "../../services/integrations/extract-write-item-id.js";
+import { markIntegrationWrite } from "../../safety/integration-write-tracker.js";
+import { createSettingsStore } from "../../settings/settings-store.js";
+const logger = createLogger("integrations-api");
+/**
+ * Integration Delegation Framework — `/api/integrations` routes (Phase 1).
+ *
+ * Scope per `GOOGLE_AUTH_DELEGATION_DESIGN.md` Phase 1:
+ *   - `GET /api/integrations` — list every registered integration with its
+ *     descriptor metadata and current state.
+ *   - `PATCH /api/integrations/:key` — change a single integration's mode.
+ *     Runs a minimal lifecycle: validate → DB update → re-render
+ *     `integrations.md` → audit row. Observer gating, route-410 middleware,
+ *     skill variant selection, and the connector probe all land in later
+ *     phases.
+ *
+ * Risk tier: Approve (dashboard-only mutation, registered in
+ * `risk-classifier.ts`).
+ */
+export function createIntegrationRoutes(deps) {
+    const app = new Hono();
+    const { db, config } = deps;
+    app.get("/integrations", (c) => {
+        const state = readIntegrations(db);
+        const integrations = INTEGRATION_KEYS.map((key) => {
+            const descriptor = INTEGRATION_DESCRIPTORS[key];
+            return {
+                key: descriptor.key,
+                displayName: descriptor.displayName,
+                supportedModes: descriptor.supportedModes,
+                directSetup: descriptor.directSetup ?? null,
+                backendConnectors: descriptor.backendConnectors,
+                skillsTouched: descriptor.skillsTouched,
+                taskFlowsTouched: descriptor.taskFlowsTouched,
+                observersTouched: descriptor.observersTouched,
+                apiRoutesTouched: descriptor.apiRoutesTouched,
+                userManagedConnector: descriptor.userManagedConnector ?? false,
+                state: state[key],
+            };
+        });
+        return c.json({ integrations });
+    });
+    // DELEGATED-PROXY-API-DESIGN.md §7 — last N delegated-proxy invocations for
+    // an integration. Drives the IntegrationCard's "Recent calls" collapsible
+    // table so the user can spot slow / failing connectors without leaving the
+    // /connections page. Daemon-side filter (rather than dashboard reading the
+    // generic cost table and post-filtering) because:
+    //   - integrationKey lives inside `detail` JSON; SQLite-side JSON1 extract
+    //     keeps the response payload small and skips the parent-event noise.
+    //   - cost.ts dashboards already aggregate; a per-integration debug view
+    //     belongs alongside the integration's other state for cohesion.
+    //
+    // Limit defaults to 50 (the design's stated cap), bounded at 200 so a
+    // typo-driven `?limit=99999` cannot DoS the response.
+    app.get("/integrations/:key/recent-proxy-calls", (c) => {
+        const key = c.req.param("key");
+        if (!isIntegrationKey(key)) {
+            return c.json({ error: "unknown_integration", key }, 404);
+        }
+        const rawLimit = c.req.query("limit");
+        let limit = 50;
+        if (rawLimit !== undefined) {
+            const parsed = Number.parseInt(rawLimit, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                return c.json({
+                    error: "invalid_limit",
+                    message: "limit must be a positive integer (default 50, max 200)",
+                }, 400);
+            }
+            limit = Math.min(parsed, 200);
+        }
+        const rows = db
+            .prepare(`SELECT id, started_at, completed_at, model_used, backend,
+                cost_usd, tokens_input, tokens_output, duration_ms,
+                num_turns, result, error, detail
+           FROM agent_actions
+          WHERE action_type = 'delegated_proxy.invoke'
+            AND json_extract(detail, '$.integrationKey') = ?
+          ORDER BY id DESC
+          LIMIT ?`)
+            .all(key, limit);
+        const calls = rows.map((row) => {
+            const detail = row.detail ? safeParseJson(row.detail) : null;
+            return {
+                id: row.id,
+                startedAt: row.started_at,
+                completedAt: row.completed_at,
+                modelId: row.model_used,
+                backend: row.backend,
+                costUsd: row.cost_usd,
+                tokensInput: row.tokens_input,
+                tokensOutput: row.tokens_output,
+                durationMs: row.duration_ms,
+                numTurns: row.num_turns,
+                result: row.result,
+                // detail.errorClass is the structured DelegatedErrorClass when the
+                // call failed inside the proxy pipeline (auth_error, no_tool_call,
+                // etc.). detail.toolName is always present. We surface both so the
+                // table can render a human label without re-parsing on the client.
+                errorClass: detail?.errorClass ?? null,
+                toolName: detail?.toolName ?? null,
+                errorMessage: row.error,
+            };
+        });
+        return c.json({
+            key,
+            limit,
+            calls,
+        });
+    });
+    // DELEGATED-PROXY-API-DESIGN.md §6.1 / §7 — list known proxy-model options
+    // for a backend (registered + custom-pinned). Drives the dashboard model
+    // dropdown so the daemon stays the source of truth for the registered
+    // model surface; clients don't need to keep their own registry mirror.
+    app.get("/integrations/proxy-models/:backend", (c) => {
+        const backend = c.req.param("backend");
+        if (!BACKEND_IDS.includes(backend)) {
+            return c.json({
+                error: "invalid_backend",
+                message: `Unknown backend '${backend}'.`,
+                supportedBackends: BACKEND_IDS,
+            }, 400);
+        }
+        const backendId = backend;
+        const options = listProxyModelOptions(backendId);
+        const canonical = resolveCanonicalDelegatedModel(backendId, db);
+        return c.json({
+            backend: backendId,
+            canonical,
+            options,
+        });
+    });
+    app.patch("/integrations/:key", async (c) => {
+        const key = c.req.param("key");
+        if (!isIntegrationKey(key)) {
+            return c.json({ error: "unknown_integration", key }, 404);
+        }
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const parsed = integrationPatchSchema.safeParse(parsedBody.body);
+        if (!parsed.success) {
+            return c.json({
+                error: "validation_error",
+                issues: parsed.error.issues.map((i) => ({
+                    path: i.path,
+                    message: i.message,
+                })),
+            }, 400);
+        }
+        const descriptor = INTEGRATION_DESCRIPTORS[key];
+        if (!descriptor.supportedModes.includes(parsed.data.mode)) {
+            return c.json({
+                error: "unsupported_mode",
+                key,
+                mode: parsed.data.mode,
+                supportedModes: descriptor.supportedModes,
+            }, 400);
+        }
+        const previous = readIntegrations(db)[key];
+        // Compute the side-effect-relevant flags up-front:
+        //  - modeChanged: probe-cache eviction + lifecycle observer flip + variants
+        //    gate all key off this. A pure deniedTools edit must NOT trigger any of
+        //    them — those are mode-change concerns.
+        //  - effectiveBackend: which backend the post-PATCH state will run against.
+        //    Used for both the missing-variants gate and the deniedTools validator.
+        //    If the user omits delegatedBackend on a delegated→delegated edit
+        //    (e.g. just toggling tool permissions), we keep the previous backend.
+        const modeChanged = parsed.data.mode !== previous.mode
+            || (parsed.data.delegatedBackend ?? null) !==
+                (previous.delegatedBackend ?? null);
+        const effectiveBackend = parsed.data.mode === "delegated"
+            ? (parsed.data.delegatedBackend ?? previous.delegatedBackend ?? null)
+            : null;
+        if (parsed.data.mode === "delegated") {
+            if (!effectiveBackend) {
+                return c.json({
+                    error: "validation_error",
+                    issues: [{
+                            path: ["delegatedBackend"],
+                            message: "delegatedBackend is required when mode is 'delegated'",
+                        }],
+                }, 400);
+            }
+            // User-managed connector integrations (e.g. Outlook) skip the
+            // descriptor-driven connector check and the variant gate: the user
+            // installs an Outlook / Microsoft Graph MCP on their selected
+            // backend (Claude Code Connector / Codex MCP / Gemini extension)
+            // and the daemon trusts that wiring. Capability probing is the
+            // user's responsibility on the backend side.
+            if (!descriptor.userManagedConnector) {
+                if (!descriptor.backendConnectors[effectiveBackend]) {
+                    return c.json({
+                        error: "backend_not_supported",
+                        key,
+                        backend: effectiveBackend,
+                        availableBackends: Object.keys(descriptor.backendConnectors),
+                    }, 400);
+                }
+                // §4.7 "Missing-variant policy" — only re-run the gate when the user
+                // is actually changing mode or backend. A pure deniedTools edit on an
+                // already-delegated integration leaves the variant set unchanged, so
+                // re-walking the file system would be wasted work AND would surface a
+                // stale-during-author error if a variant was momentarily missing.
+                //
+                // DELEGATED-MODE-V2-DESIGN.md §11 (Phase 3) re-activated the
+                // legacy variant gate for every delegated integration. gmail and
+                // google_calendar now ship `SKILL.delegated.<sessionBackend>.md`
+                // (cross-backend) and resolve to `null` for same-backend, so
+                // missing variants are a real configuration error.
+                if (modeChanged) {
+                    const missing = missingDelegatedVariants(config.workspaceDir, key, effectiveBackend);
+                    if (missing.skills.length > 0 || missing.taskFlows.length > 0) {
+                        return c.json({
+                            error: "missing_variants",
+                            key,
+                            backend: effectiveBackend,
+                            missingSkills: missing.skills,
+                            missingTaskFlows: missing.taskFlows,
+                            message: `Cannot enter delegated mode for '${key}' on backend '${effectiveBackend}' — ${missing.skills.length + missing.taskFlows.length} variant file(s) missing. Author the listed files or narrow the registry's skillsTouched / taskFlowsTouched before retrying.`,
+                        }, 400);
+                    }
+                }
+            }
+        }
+        // DELEGATED-PROXY-API-DESIGN.md §6.1 — `delegatedModel` validation.
+        // The schema rejects empty strings already; here we additionally
+        // reject values that don't appear in the registered model list for
+        // the effective backend (or in user-pinned `process_backend_config`
+        // rows for the same backend, per §4.2's "trust custom pins" rule).
+        // The value is *allowed* on any mode so the user can pre-stage a pin
+        // before flipping to delegated; validation only runs when we have a
+        // backend to validate against.
+        if (parsed.data.delegatedModel !== undefined
+            && parsed.data.delegatedModel !== null
+            && effectiveBackend) {
+            const candidate = parsed.data.delegatedModel;
+            if (!proxyModelIsKnown(db, effectiveBackend, candidate)) {
+                return c.json({
+                    error: "unknown_model",
+                    key,
+                    backend: effectiveBackend,
+                    model: candidate,
+                    knownModels: knownProxyModels(db, effectiveBackend),
+                    message: `Model '${candidate}' is not registered for backend '${effectiveBackend}'. Pick one of the known models or pass null to use the canonical light-tier default.`,
+                }, 400);
+            }
+        }
+        // §7.7 — `deniedTools` validation. We accept the field on any mode so
+        // the user can pre-stage a deny list before flipping to delegated, but
+        // validation only runs against the effective backend when one exists.
+        // For non-delegated modes, deniedTools persists as-is (no live backend
+        // to validate against — the value is inert until delegated).
+        //
+        // DELEGATED-MODE-V2-DESIGN.md §4.5.4 — first-time delegated setup
+        // pre-populates `deniedTools` with the recommended starter list when
+        // the caller didn't supply one (PATCH omits the field). This keeps the
+        // CLAUDE.md "destructive ops require user confirmation" invariant
+        // intact on a fresh install. The user opts out explicitly by passing
+        // `deniedTools: []` (empty array, distinct from undefined).
+        //
+        // The starter floor fires in two distinct shapes — both arrive at an
+        // effectively-empty deny set after the PATCH and would otherwise leave
+        // the agent unconstrained:
+        //
+        //   (a) Entering delegated mode for the first time on this integration
+        //       (previous mode was direct/disabled) AND no curated list was
+        //       already pre-staged — re-entry from disabled with prior denies
+        //       kept means the user already curated, don't overwrite.
+        //
+        //   (b) Backend swap (delegated → delegated, different `delegatedBackend`)
+        //       where every entry in `previous.deniedTools` is namespace-stale on
+        //       the new backend. The user's curation referenced tools the new
+        //       connector doesn't expose (e.g. Claude's `label_message` carried
+        //       into a Codex session), so the materializer's stale-drop pass
+        //       would empty the disallowedTools array silently — closing the
+        //       same §4.5.4 floor the design wrote (a) to defend. The original
+        //       design framed §4.5.4 as "first delegated setup only" and missed
+        //       this case; surfaced during the 2026-04-26 implementation review.
+        //
+        // The wizard UI for the opt-out / "use recommended" / "I'll edit"
+        // branches is Phase 4 polish (see §Phase 4.2). For now the API default
+        // closes the safety floor; the dashboard editor card surfaces the
+        // populated list for editing.
+        const enteringDelegated = parsed.data.mode === "delegated" && previous.mode !== "delegated";
+        const omittedDeniedTools = parsed.data.deniedTools === undefined;
+        const previousDeniedToolsEmpty = (previous.deniedTools ?? []).length === 0;
+        const swappingDelegatedBackend = parsed.data.mode === "delegated"
+            && previous.mode === "delegated"
+            && effectiveBackend !== null
+            && previous.delegatedBackend !== undefined
+            && previous.delegatedBackend !== effectiveBackend;
+        // For shape (b): the previous list had at least one entry (otherwise the
+        // floor was already empty and shape (a)'s logic doesn't apply here either),
+        // and *every* entry is stale on the new backend.
+        const swapWipesAllDenies = swappingDelegatedBackend
+            && (previous.deniedTools ?? []).length > 0
+            && filterDeniedToolsForBackend(key, effectiveBackend, previous.deniedTools ?? []).active.length === 0;
+        const useStarter = effectiveBackend !== null
+            && omittedDeniedTools
+            && ((enteringDelegated && previousDeniedToolsEmpty)
+                || swapWipesAllDenies);
+        const finalDeniedTools = useStarter
+            ? recommendedStarterDeniedTools(key, effectiveBackend)
+            : parsed.data.deniedTools !== undefined
+                ? parsed.data.deniedTools
+                : (previous.deniedTools ?? []);
+        if (useStarter && finalDeniedTools.length > 0) {
+            logger.info({
+                key,
+                backend: effectiveBackend,
+                starter: finalDeniedTools,
+                // Distinguish the two shapes so log readers can spot the
+                // backend-swap fallback separately from first-time setup.
+                // `enteringDelegated` covers shape (a); `swapWipesAllDenies`
+                // covers shape (b). They are mutually exclusive by construction
+                // (a requires `previous.mode !== "delegated"`, b requires
+                // `previous.mode === "delegated"`).
+                trigger: enteringDelegated ? "first_delegated" : "backend_swap_stale",
+                previousBackend: swappingDelegatedBackend
+                    ? previous.delegatedBackend
+                    : null,
+            }, "applied starter deniedTools floor");
+        }
+        if (effectiveBackend && parsed.data.deniedTools !== undefined) {
+            const result = validateDeniedTools(key, effectiveBackend, finalDeniedTools);
+            if (!result.ok) {
+                if (result.error === "unknown_tool") {
+                    return c.json({
+                        error: "unknown_tool",
+                        key,
+                        backend: effectiveBackend,
+                        tool: result.tool,
+                        knownTools: result.knownTools,
+                        message: `Tool '${result.tool}' is not declared in the ${effectiveBackend} connector for '${key}'. Pick a tool from the descriptor's capability list.`,
+                    }, 400);
+                }
+                if (result.error === "denial_breaks_required_capability") {
+                    return c.json({
+                        error: "denial_breaks_required_capability",
+                        key,
+                        backend: effectiveBackend,
+                        capability: result.capability,
+                        remainingTools: result.remainingTools,
+                        message: `Denying these tools removes the only path for required capability '${result.capability}'. Keep at least one of: ${result.remainingTools.join(", ")}.`,
+                    }, 400);
+                }
+                // "no_connector" should be unreachable — we already validated
+                // `descriptor.backendConnectors[effectiveBackend]` above. Map to a
+                // 500 rather than a 400 because it indicates a server-side mismatch.
+                return c.json({ error: "internal_error" }, 500);
+            }
+        }
+        // DELEGATED-PROXY-API-DESIGN.md §4.2 — `delegatedModel` carry-over
+        // rules:
+        //   - PATCH omits the field → preserve previous value (mode-flip
+        //     idempotent: direct ↔ delegated keeps the pin).
+        //   - PATCH passes `null` → clear the pin (canonical fallback at
+        //     call time). Surfaced by the dashboard's "Reset to default"
+        //     affordance after a backend swap.
+        //   - PATCH passes a non-empty string → validated above and stored.
+        // Same shape for `delegatedMaxTurns` (forward-compat — no UI yet).
+        const finalDelegatedModel = parsed.data.delegatedModel === undefined
+            ? (previous.delegatedModel ?? null)
+            : parsed.data.delegatedModel;
+        const finalDelegatedMaxTurns = parsed.data.delegatedMaxTurns === undefined
+            ? (previous.delegatedMaxTurns ?? null)
+            : parsed.data.delegatedMaxTurns;
+        const finalDelegatedSyncEnabled = parsed.data.delegatedSyncEnabled === undefined
+            ? previous.delegatedSyncEnabled
+            : parsed.data.delegatedSyncEnabled;
+        const stamped = new Date().toISOString();
+        try {
+            const next = updateIntegrationState(db, key, {
+                mode: parsed.data.mode,
+                // Only carry delegatedBackend when mode is delegated. The schema
+                // already enforces presence in that branch (superRefine), so a
+                // direct/disabled flip drops it cleanly. Don't fall back to the
+                // previous value here — that breaks the delegated → direct path
+                // (the integration would keep its old backend forever).
+                ...(parsed.data.mode === "delegated" && parsed.data.delegatedBackend
+                    ? { delegatedBackend: parsed.data.delegatedBackend }
+                    : {}),
+                // Always persist the resolved delegatedModel/delegatedMaxTurns —
+                // null clears, undefined was already collapsed above to the
+                // previous value or null. Keeps the JSON blob shape stable
+                // across PATCHes even when the field is inert (mode !== delegated).
+                ...(finalDelegatedModel !== null
+                    ? { delegatedModel: finalDelegatedModel }
+                    : {}),
+                ...(finalDelegatedMaxTurns !== null
+                    ? { delegatedMaxTurns: finalDelegatedMaxTurns }
+                    : {}),
+                ...(finalDelegatedSyncEnabled === false
+                    ? { delegatedSyncEnabled: false }
+                    : {}),
+                deniedTools: finalDeniedTools,
+                lastChangedAt: stamped,
+            });
+            await writeManagementMd(config.dataDir, next, {
+                externalObsidianVaultPath: config.externalObsidianVaultPath,
+                externalObsidianWatch: config.externalObsidianWatch,
+            });
+            // §4.11 probe-cache eviction is a *mode-change* concern. A pure
+            // deniedTools edit doesn't invalidate which capabilities the
+            // connector exposes — the live probe answer is identical, only what
+            // the agent is allowed to invoke from the skill body changes. So
+            // gate eviction on modeChanged.
+            if (modeChanged) {
+                const cleared = deleteProbesForIntegration(db, key);
+                if (cleared > 0) {
+                    logger.info({ key, cleared }, "cleared stale probe cache after integration mode change");
+                }
+            }
+            // DELEGATED-MODE-V2-DESIGN.md §4.4 #2 — a deniedTools-only edit must
+            // also re-materialize active DM workdirs, since the per-session
+            // `disallowedTools` array (Claude SDK), admin-policy TOML (Gemini),
+            // and AGENTS.md prose block (Codex) are derived from `state.deniedTools`
+            // at materialization time. A stale workdir would leak the old policy
+            // into the next turn. We compute the policy diff up front so we can
+            // gate the lifecycle callback on it.
+            const policyDiff = diffDeniedTools(previous.deniedTools ?? [], next[key].deniedTools ?? []);
+            const policyChanged = policyDiff.added.length > 0 || policyDiff.removed.length > 0;
+            const syncChanged = (previous.delegatedSyncEnabled ?? true)
+                !== (next[key].delegatedSyncEnabled ?? true);
+            // §4.10 lifecycle step 4 — observer flip side of the callback is
+            // gated on `wasDirect !== isDirect` inside `applyIntegrationModeChange`,
+            // so calling it on a deniedTools-only edit is safe: observer
+            // start/stop is a no-op, only `rematerializeDmSessions` fires.
+            if ((modeChanged || policyChanged || syncChanged) && deps.onIntegrationModeChange) {
+                void Promise.resolve()
+                    .then(() => deps.onIntegrationModeChange?.(key, previous, next[key]))
+                    .catch((err) => {
+                    logger.error({ err, key }, "integration mode-change side-effects failed — DB state already updated");
+                });
+            }
+            // §7.7 audit. Two distinct action types so log readers can filter:
+            //  - integration.mode_change: mode or delegatedBackend moved
+            //  - integration.policy_change: deniedTools diff (with no mode flip)
+            // Both can fire on a single PATCH when the user changes mode AND
+            // deniedTools simultaneously — that's intentional, the diff is at
+            // different granularities.
+            if (modeChanged) {
+                recordAuditModeChange(db, key, previous, next[key]);
+            }
+            if (policyChanged) {
+                recordAuditPolicyChange(db, key, policyDiff);
+            }
+            logger.info({
+                key,
+                from: previous.mode,
+                to: next[key].mode,
+                delegatedBackend: next[key].delegatedBackend,
+                delegatedModelFrom: previous.delegatedModel ?? null,
+                delegatedModelTo: next[key].delegatedModel ?? null,
+                deniedToolsAdded: policyDiff.added,
+                deniedToolsRemoved: policyDiff.removed,
+            }, modeChanged
+                ? "integration mode updated"
+                : "integration policy updated (deniedTools / delegatedModel)");
+            // Auto-enable the global task-mode flag the first time *any*
+            // integration enters delegated mode. Rationale:
+            //   - The legacy `/integrations/:key/invoke` RPC is dead (commented
+            //     out 2026-05-01 in this same file); every delegated skill body
+            //     and task flow now talks to `/exec`.
+            //   - `/exec` is gated by `delegatedTaskModeEnabled`, originally a
+            //     Phase-1 canary that defaults `false`. With `/invoke` gone,
+            //     "delegated mode + task mode off" is a degenerate state with
+            //     no productive use — the agent calls `/exec`, gets 503,
+            //     fails. So flipping an integration to delegated *is* the
+            //     enablement signal.
+            //   - We only flip on the transition into delegated, not on every
+            //     PATCH against an already-delegated integration. A pure
+            //     deniedTools edit must not silently re-enable a flag the
+            //     operator manually toggled off; emergency-disable is the
+            //     flag's remaining role.
+            const enteringDelegated = next[key].mode === "delegated" && previous.mode !== "delegated";
+            if (enteringDelegated && !config.delegatedTaskModeEnabled) {
+                try {
+                    createSettingsStore(db).set("delegatedTaskModeEnabled", true);
+                    config.delegatedTaskModeEnabled = true;
+                    logger.info({ key, backend: effectiveBackend, trigger: "first_delegated" }, "auto-enabled delegatedTaskModeEnabled — first delegated integration");
+                }
+                catch (err) {
+                    // Settings write is best-effort: even if persistence fails the
+                    // in-memory config update above keeps /exec working for this
+                    // process; a daemon restart would re-apply the same heal via
+                    // the startup default-correction path in index.ts.
+                    logger.error({ err, key }, "failed to persist delegatedTaskModeEnabled auto-enable; in-memory config still updated");
+                }
+            }
+            return c.json({ ok: true, integration: next[key] });
+        }
+        catch (err) {
+            logger.error({ err, key }, "integration mode update failed");
+            return c.json({ error: "internal_error" }, 500);
+        }
+    });
+    // ─────────────────────────────────────────────────────────────────────
+    // RESERVED — POST /integrations/:key/invoke (RPC-style tool dispatch)
+    //
+    // Commented out 2026-05-01 as part of the /exec-only migration. The
+    // RPC `{tool, args}` shape required the caller to know the delegated
+    // backend's exact bare tool name (Claude `search_threads` vs Codex
+    // `search_emails` vs Gemini `search`) and arg names (`pageSize` vs
+    // `max_results` vs `maxResults`). That coupling broke under:
+    //   - cross-backend tool-name divergence (the alias-translation gap
+    //     that caused the 2026-05-01 wrong_tool incidents),
+    //   - any custom MCP server the user installs (registry-invisible),
+    //   - backend swaps that should be transparent to the agent.
+    //
+    // `POST /integrations/:key/exec` (task mode) is the canonical surface
+    // now: the agent describes intent in natural language + outputSchema,
+    // the daemon's delegate picks the tool. The handler body and the
+    // supporting `resolveCanonicalBareTool` helper are preserved verbatim
+    // for **future reactivation** — possible reactivation scenarios:
+    //   1. A low-latency RPC fast path for cost-sensitive callers.
+    //   2. A debug/admin endpoint for direct tool dispatch.
+    //   3. A per-integration opt-in once full cross-backend alias
+    //      translation is in place.
+    //
+    // DO NOT DELETE. The internal `DelegatedBackendInvoker.invoke()` API
+    // and each core's `runDelegatedTool()` remain wired (used by
+    // `delegated-sync-worker` for hourly drift detection — see
+    // `packages/daemon/src/observers/delegated-sync-worker.ts:504`).
+    //
+    // Original docstring (preserved for the reactivation-time author):
+    //   POST /integrations/:key/invoke — DELEGATED-MODE-V2-DESIGN.md §4.2.
+    //   Generic chokepoint for cross-backend delegated tool calls. The
+    //   agent's cross-backend skill body
+    //   (`SKILL.delegated.<sessionBackend>.md`) directs it here for any
+    //   connector tool on a delegatedBackend that differs from the DM
+    //   session backend. Body: `{tool, args}` — the daemon does NOT
+    //   enumerate or validate the tool name (no per-tool routeMap
+    //   maintenance); it forwards verbatim to `DelegatedBackendInvoker`.
+    //
+    //   Pre-flight order (cheapest first, fail-fast):
+    //     1. Integration must be in `delegated` mode (409 mode_mismatch).
+    //     2. If `x-session-backend` is set and matches `state.delegatedBackend`,
+    //        the caller is misusing the endpoint — same-backend agents have
+    //        native MCP and the skill is not provisioned (§4.1.2). Surface as
+    //        409 to make accidental misuse loud rather than spawning a useless
+    //        subprocess.
+    //     3. `state.deniedTools` patterns enforced via `matchToolPattern`. The
+    //        stored entries are bare names (no `mcp__*` prefix), so we strip the
+    //        connector's `toolNamespace` from the body's `tool` before matching.
+    //
+    //   Risk tier: Autonomous (no Bearer required). Cost / failure
+    //   attribution lands in `agent_actions` via the invoker
+    //   (`action_type='delegated_proxy.invoke'`).
+    // ─────────────────────────────────────────────────────────────────────
+    /*
+    app.post("/integrations/:key/invoke", async (c) => {
+      const key = c.req.param("key");
+      if (!isIntegrationKey(key)) {
+        return c.json({ error: "unknown_integration", key }, 404);
+      }
+  
+      const parsedBody = await readJsonBody(c);
+      if (!parsedBody.ok) return parsedBody.response;
+  
+      const body = parsedBody.body as { tool?: unknown; args?: unknown } | null;
+      const toolRaw = body?.tool;
+      if (typeof toolRaw !== "string" || toolRaw.length === 0) {
+        return c.json(
+          {
+            error: "validation_error",
+            message: "`tool` must be a non-empty string (bare tool name or fully-qualified MCP name)",
+          },
+          400,
+        );
+      }
+      // §4.2.1 contract — `args` is `object`. Reject arrays, scalars, and null
+      // here so the failure surfaces at the route boundary with a precise 400
+      // rather than as a downstream invoker / connector parse error.
+      const argsRaw = body?.args;
+      if (
+        argsRaw !== undefined
+        && (argsRaw === null
+          || typeof argsRaw !== "object"
+          || Array.isArray(argsRaw))
+      ) {
+        return c.json(
+          {
+            error: "validation_error",
+            message: "`args` must be a JSON object (or omitted to send {})",
+          },
+          400,
+        );
+      }
+      const args = (argsRaw as Record<string, unknown> | undefined) ?? {};
+  
+      if (!deps.delegatedInvoker) {
+        // Boot ordering / test wiring case — invoker not registered. Surface
+        // explicitly so the caller knows this isn't a precondition mismatch.
+        return c.json(
+          {
+            error: "unimplemented",
+            message: "delegated invoker is not wired into this daemon instance",
+            integration: key,
+            backend: null,
+            mode: "delegated",
+          },
+          501,
+        );
+      }
+  
+      const state = readIntegrations(db)[key];
+      if (!state || state.mode !== "delegated" || !state.delegatedBackend) {
+        return c.json(
+          {
+            error: "mode_mismatch",
+            message: `${key} is not in delegated mode (mode=${state?.mode ?? "missing"})`,
+            integration: key,
+            backend: null,
+            mode: "delegated",
+          },
+          409,
+        );
+      }
+  
+      const sessionBackendHeader = c.req.header("x-session-backend");
+      if (
+        sessionBackendHeader
+        && sessionBackendHeader === state.delegatedBackend
+      ) {
+        return c.json(
+          {
+            error: "mode_mismatch",
+            message: `session backend matches delegatedBackend (${sessionBackendHeader}) — use native MCP instead`,
+            integration: key,
+            backend: state.delegatedBackend,
+            mode: "delegated",
+          },
+          409,
+        );
+      }
+  
+      // Strip the connector's namespace prefix if the body included it,
+      // then translate cross-backend aliases to the delegated connector's
+      // canonical tool name. Translation runs BEFORE the deniedTools check
+      // because deny entries are stored as backend-canonical names (the
+      // skill body trains the user on that form): checking pre-translation
+      // silently lets a denied call through if the agent used a sibling
+      // backend's alias.
+      const connector = INTEGRATION_DESCRIPTORS[key].backendConnectors[state.delegatedBackend];
+      const namespace = connector?.toolNamespace ?? "";
+      const incomingBareTool = namespace && toolRaw.startsWith(namespace)
+        ? toolRaw.slice(namespace.length)
+        : toolRaw;
+      const bareTool = resolveCanonicalBareTool(connector, incomingBareTool);
+      if (bareTool !== incomingBareTool) {
+        logger.debug(
+          {
+            integration: key,
+            backend: state.delegatedBackend,
+            from: incomingBareTool,
+            to: bareTool,
+          },
+          "delegated invoke: translated cross-backend tool alias",
+        );
+      }
+  
+      if ((state.deniedTools ?? []).some((pattern) => matchToolPattern(pattern, bareTool))) {
+        return c.json(
+          {
+            error: "denied_tool",
+            message: `tool '${bareTool}' is denied by user settings for integration '${key}'`,
+            integration: key,
+            backend: state.delegatedBackend,
+            mode: "delegated",
+            tool: bareTool,
+          },
+          403,
+        );
+      }
+  
+      // The invoker forwards verbatim — connector validates the tool name and
+      // arg shape. We always send the fully-qualified tool string so the
+      // subprocess prompt unambiguously points at one tool.
+      const fullyQualifiedTool = namespace ? `${namespace}${bareTool}` : bareTool;
+  
+      const result = await deps.delegatedInvoker.invoke({
+        integrationKey: key,
+        toolName: fullyQualifiedTool,
+        toolArgs: args,
+        parentEventId: c.req.header("x-event-id"),
+        parentProcessKey: c.req.header("x-process-key"),
+      });
+  
+      if (result.ok) {
+        // INTEGRATION-DRIFT-DETECTION-PLAN.md §11 Phase 4 — actor attribution.
+        // Successful writes mark the persistent `integration_writes` table so
+        // the next reconcile diff resolves `actor='agent'` and the agent does
+        // not re-discover its own write as a user-originated observation.
+        // Decision tree:
+        //   1. `bareTool` in `connector.destructiveTools` → it's a write.
+        //   2. Walk `result.toolResult` for canonical id keys (extractor).
+        //   3. If the response had no id (label_message / label_thread /
+        //      bulk_label_matching_emails return `{ ok: true }`), fall back
+        //      to `args.messageId` / `args.threadId` / each entry of
+        //      `args.messageIds` / `args.threadIds`.
+        // Failure to extract any id is logged at debug and the call still
+        // returns 2xx — losing one attribution mark causes one self-noticed
+        // observation, never data loss.
+        maybeMarkIntegrationWrite(deps.db, {
+          integration: key,
+          connector,
+          bareTool,
+          toolResult: result.toolResult,
+          args,
+        });
+        return c.json({
+          toolResult: result.toolResult,
+          cost: {
+            tokensInput: result.cost.tokensInput,
+            tokensOutput: result.cost.tokensOutput,
+            cacheCreationTokens: result.cost.cacheCreationTokens,
+            cacheReadTokens: result.cost.cacheReadTokens,
+            costUsd: result.cost.costUsd,
+            durationMs: result.cost.durationMs,
+            numTurns: result.cost.numTurns,
+          },
+        });
+      }
+  
+      const status = mapErrorClassToHttpStatus(result.errorClass);
+      return c.json(
+        {
+          error: result.errorClass,
+          message: result.message,
+          integration: key,
+          backend: result.backendId ?? state.delegatedBackend,
+          mode: "delegated",
+        },
+        status,
+      );
+    });
+    */
+    // ── end of reserved /invoke route ────────────────────────────────────
+    // POST /integrations/:key/exec — DELEGATED-TASK-MODE-DESIGN.md §4.1.
+    // Task-mode invocation: the calling agent describes intent in natural
+    // language and pins an `outputSchema`; the daemon spawns the
+    // delegatedBackend with `allowedTools` restricted to the integration's
+    // connector and validates the final assistant JSON against the schema.
+    //
+    // Pre-flight order (cheapest first; matches /invoke ordering):
+    //   1. Integration is registered (404 unknown_integration).
+    //   2. Body is valid JSON (400 invalid_json_body).
+    //   3. Body fields parse: task non-empty string, outputSchema present
+    //      and within 4 KB, caps within hard bounds, allowDestructive bool.
+    //   4. Kill switch (config.delegatedTaskModeEnabled): 503 if false.
+    //   5. Integration is delegated with non-null delegatedBackend (409).
+    //   6. delegatedBackend ∈ {claude, gemini} — Codex returns 501.
+    //   7. x-session-backend header (if set) ≠ delegatedBackend (409 same
+    //      defense-in-depth as /invoke — same-backend should use native MCP).
+    //   8. Invoker wired (501).
+    //
+    // Risk tier: Autonomous (no Bearer required). Same rationale as /invoke —
+    // tool-level safety lives in `state.deniedTools` + `destructiveTools`,
+    // both enforced at the chokepoint by the invoker.
+    app.post("/integrations/:key/exec", async (c) => {
+        const key = c.req.param("key");
+        if (!isIntegrationKey(key)) {
+            return c.json({ error: "unknown_integration", key }, 404);
+        }
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        // Field-level validation. Each branch maps to `validation_error` /
+        // `schema_too_large` per §10.
+        if (typeof body?.task !== "string" || body.task.trim().length === 0) {
+            return c.json({
+                error: "validation_error",
+                message: "`task` must be a non-empty string",
+            }, 400);
+        }
+        const schemaCheck = checkOutputSchema(body.outputSchema);
+        if (!schemaCheck.ok) {
+            const errorCode = schemaCheck.reason === "too_large"
+                ? "schema_too_large"
+                : "validation_error";
+            return c.json({
+                error: errorCode,
+                message: schemaCheck.message,
+                field: "outputSchema",
+            }, 400);
+        }
+        const outputSchema = body.outputSchema;
+        const config = deps.config;
+        if (!config.delegatedTaskModeEnabled) {
+            return c.json({
+                error: "task_mode_disabled",
+                // Auto-enable on `PATCH /api/integrations/:key` to delegated
+                // (and the matching startup heal in `index.ts`) make this
+                // path a deliberate operator action: the flag was either
+                // explicitly disabled via `PATCH /api/config` or its
+                // emergency-disable use case fired. Surface that fact rather
+                // than promising a dashboard toggle that does not exist.
+                message: "Task mode is currently disabled (config.delegatedTaskModeEnabled=false). Re-enable via PATCH /api/config { delegatedTaskModeEnabled: true }, or flip an integration to delegated to auto-enable.",
+                integration: key,
+                mode: "delegated",
+            }, 503);
+        }
+        const allowDestructive = body.allowDestructive === true;
+        const maxToolCalls = clampNumber(body.maxToolCalls, config.delegatedTaskDefaultMaxToolCalls, 1, DELEGATED_TASK_HARD_CAPS.maxToolCalls);
+        if (maxToolCalls === null) {
+            return c.json({
+                error: "validation_error",
+                message: `maxToolCalls must be an integer between 1 and ${DELEGATED_TASK_HARD_CAPS.maxToolCalls}`,
+            }, 400);
+        }
+        const maxBudgetUsd = clampNumber(body.maxBudgetUsd, config.delegatedTaskDefaultMaxBudgetUsd, 0, DELEGATED_TASK_HARD_CAPS.maxBudgetUsd, true);
+        if (maxBudgetUsd === null) {
+            return c.json({
+                error: "validation_error",
+                message: `maxBudgetUsd must be a number between 0 and ${DELEGATED_TASK_HARD_CAPS.maxBudgetUsd}`,
+            }, 400);
+        }
+        const timeoutMs = clampNumber(body.timeoutMs, config.delegatedTaskDefaultTimeoutMs, 1000, DELEGATED_TASK_HARD_CAPS.maxTimeoutMs);
+        if (timeoutMs === null) {
+            return c.json({
+                error: "validation_error",
+                message: `timeoutMs must be an integer between 1000 and ${DELEGATED_TASK_HARD_CAPS.maxTimeoutMs}`,
+            }, 400);
+        }
+        if (!deps.delegatedInvoker) {
+            return c.json({
+                error: "unimplemented",
+                message: "delegated invoker is not wired into this daemon instance",
+                integration: key,
+                backend: null,
+                mode: "delegated",
+            }, 501);
+        }
+        const state = readIntegrations(deps.db)[key];
+        if (!state || state.mode !== "delegated" || !state.delegatedBackend) {
+            return c.json({
+                error: "mode_mismatch",
+                message: `${key} is not in delegated mode (mode=${state?.mode ?? "missing"})`,
+                integration: key,
+                backend: null,
+                mode: "delegated",
+            }, 409);
+        }
+        // Codex task mode landed in Phase 1.5 — daemon-side stream pre-emption
+        // (see codex-core.ts `runDelegatedTask`) gates allowed-tools / destructive
+        // calls without relying on a CLI-level allowedTools surface. The 501
+        // short-circuit that previously fired here for `state.delegatedBackend
+        // === "codex"` is gone; Codex /exec requests now flow through the
+        // invoker like Claude and Gemini.
+        const sessionBackendHeader = c.req.header("x-session-backend");
+        if (sessionBackendHeader
+            && sessionBackendHeader === state.delegatedBackend) {
+            return c.json({
+                error: "mode_mismatch",
+                message: `session backend matches delegatedBackend (${sessionBackendHeader}) — use native MCP instead`,
+                integration: key,
+                backend: state.delegatedBackend,
+                mode: "delegated",
+            }, 409);
+        }
+        const result = await deps.delegatedInvoker.task({
+            integrationKey: key,
+            task: body.task.trim(),
+            outputSchema,
+            maxToolCalls,
+            maxBudgetUsd,
+            timeoutMs,
+            allowDestructive,
+            heavy: body.heavy === true,
+            // §13 Phase 3.3 — pass-through opt-in. Defense-in-depth: the
+            // invoker also enforces `allowDestructive === false` before
+            // checking the cache, so a buggy caller that sets cacheable on a
+            // destructive task can't poison the cache.
+            cacheable: body.cacheable === true,
+            parentEventId: c.req.header("x-event-id"),
+            parentProcessKey: c.req.header("x-process-key"),
+        });
+        // INTEGRATION-DRIFT-DETECTION-PLAN.md §11 Phase 4 — actor
+        // attribution at the /exec chokepoint. /invoke called this once per
+        // request because there was a single tool. /exec is a loop: walk
+        // the trace and mark every successful destructive step.
+        //
+        // Runs BEFORE the result.ok / error split because failed tasks
+        // still strand real side effects in the trace:
+        //   - timeout / subprocess_crashed / loop_aborted / budget_exhausted:
+        //     earlier ok steps already landed before the wall-clock /
+        //     budget / turn cap fired.
+        //   - schema_violation / parse_error: the model called the tool
+        //     successfully and then mis-formatted its final JSON. The §6.2
+        //     retry is suppressed when `writeClassToolFired` is true, so
+        //     the side effect landed exactly once and needs marking
+        //     exactly once.
+        //   - policy_violation: the violating step is `status: "error"`
+        //     (Codex aborts before pairing) but earlier ok destructive
+        //     steps in the same task are still real.
+        // Skipping the loop on failure was the same shape of bug as the
+        // old /invoke→/exec migration miss: an agent-issued send_email
+        // that schema-violates on output would land in Gmail, return 502,
+        // and surface as "I noticed you sent…" on the next reconcile.
+        //
+        // Bare-tool resolution: trace `toolName` is the fully-qualified
+        // `mcp__server__tool` (or dotted `server.tool`) form the core
+        // observed mid-stream. Strip `connector.toolNamespace` to recover
+        // the bare name for the destructiveTools membership check; if the
+        // namespace doesn't match, the tool wasn't from this connector
+        // (e.g. an internal Read/Write step) and we ignore it.
+        //
+        // Each trace step carries the upstream `toolResult` (the cores
+        // JSON-parse the connector response when possible, fall back to
+        // raw string). extractWriteItemIds first walks the response
+        // shape (recovers id-in-response writes — send_email,
+        // create_event, notion-create-pages) and then falls back to
+        // args-side extraction (recovers id-in-args writes — delete /
+        // update / label / archive). Older snapshots / stub cores that
+        // don't populate toolResult degrade to args-only without crashing.
+        //
+        // `result.trace` is required on the success union and optional on
+        // the error union — guard with truthiness.
+        if (result.trace && result.trace.length > 0) {
+            const descriptor = INTEGRATION_DESCRIPTORS[key];
+            const connector = descriptor.backendConnectors[state.delegatedBackend];
+            if (connector) {
+                const namespace = connector.toolNamespace;
+                for (const step of result.trace) {
+                    if (step.status !== "ok")
+                        continue;
+                    if (!step.toolName.startsWith(namespace))
+                        continue;
+                    const bareTool = step.toolName.slice(namespace.length);
+                    if (!connector.destructiveTools.includes(bareTool))
+                        continue;
+                    maybeMarkIntegrationWrite(deps.db, {
+                        integration: key,
+                        connector,
+                        bareTool,
+                        toolResult: step.toolResult,
+                        args: step.toolArgs,
+                    });
+                }
+            }
+        }
+        if (result.ok) {
+            return c.json({
+                result: result.result,
+                needsConfirmation: result.needsConfirmation,
+                confirmationPlan: result.confirmationPlan,
+                trace: result.trace,
+                cost: result.cost,
+            });
+        }
+        const status = mapTaskErrorClassToHttpStatus(result.errorClass);
+        return c.json({
+            error: result.errorClass,
+            message: result.message,
+            ...(result.raw !== undefined ? { raw: result.raw } : {}),
+            ...(result.trace ? { trace: result.trace } : {}),
+            ...(result.cost ? { cost: result.cost } : {}),
+            integration: key,
+            backend: result.backendId ?? state.delegatedBackend,
+            mode: "delegated",
+        }, status);
+    });
+    // POST /integrations/:key/probe — evaluate or read the cached connector
+    // probe for a given backend. Phase 2 supports two modes:
+    //   - Live probe: caller passes `{tools: [...]}` (the names the agent
+    //     subprocess reported). The evaluator computes presence + persists.
+    //   - Cached read: body omits `tools`. Returns the latest stored row, or
+    //     a 404 marker if no probe has been taken yet. The dashboard's
+    //     refresh button and post-Apply background refresh use the live path;
+    //     /health and the setup wizard's initial render use the cached path.
+    // No live agent subprocess is launched here — keeping that out of the
+    // boot critical path is what saves the per-Opus probe cost called out
+    // in the §7 POC.
+    app.post("/integrations/:key/probe", async (c) => {
+        const key = c.req.param("key");
+        if (!isIntegrationKey(key)) {
+            return c.json({ error: "unknown_integration", key }, 404);
+        }
+        const body = await readOptionalJsonBody(c);
+        if (body === null) {
+            return c.json({ error: "invalid_json_body" }, 400);
+        }
+        const backend = resolveProbeBackend(body.backend, db, key);
+        if (!backend.ok)
+            return c.json(backend.error, backend.status);
+        const descriptorForProbe = INTEGRATION_DESCRIPTORS[key];
+        const isUserManaged = descriptorForProbe.userManagedConnector === true;
+        // Connector existence is a descriptor-driven precondition. User-
+        // managed integrations (Outlook today) intentionally ship with an
+        // empty `backendConnectors` and skip this check — the user's MCP /
+        // connector on the chosen backend is the source of truth, not the
+        // registry. Backend availability + auth still get verified for
+        // user-managed in the live-probe branch below.
+        if (!isUserManaged) {
+            const connector = getConnector(key, backend.value);
+            if (!connector) {
+                return c.json({
+                    error: "backend_not_supported",
+                    key,
+                    backend: backend.value,
+                    availableBackends: Object.keys(descriptorForProbe.backendConnectors),
+                }, 400);
+            }
+        }
+        // §4.11 live probe — `liveProbe: true` asks the daemon to spawn the
+        // target backend and enumerate its MCP tool list. User-initiated only;
+        // never fired from boot or PATCH. The descriptor + cached read paths
+        // cover the other two calling conventions.
+        //
+        // For user-managed integrations the spawn + probeTools() call still
+        // fires (this is what enforces §4.12.2 checks #1 backend resolvable
+        // and #2 backend auth valid). Only the descriptor-side capability
+        // evaluation is replaced by `makeUserManagedProbeResult`, which
+        // carries the full live tool list as `presentTools` so dashboards
+        // can show "we found N tools on your backend."
+        if (body.liveProbe === true) {
+            const core = deps.agentBackends?.find((c) => c.backendId === backend.value);
+            if (!core) {
+                return c.json({
+                    error: "backend_core_unavailable",
+                    backend: backend.value,
+                    message: `Backend '${backend.value}' is not registered in this daemon — cannot run live probe.`,
+                }, 503);
+            }
+            try {
+                const tools = await core.probeTools();
+                const result = isUserManaged
+                    ? makeUserManagedProbeResult(key, backend.value, tools)
+                    : evaluateProbe({
+                        tools,
+                        integration: key,
+                        backend: backend.value,
+                    });
+                writeProbe(db, result);
+                logger.info({
+                    key,
+                    backend: backend.value,
+                    present: result.present,
+                    missingRequired: result.missingRequired,
+                    toolCount: result.presentTools.length,
+                    userManaged: isUserManaged,
+                }, "integration live probe persisted");
+                return c.json({
+                    ok: true,
+                    cached: false,
+                    liveProbe: true,
+                    ...(isUserManaged ? { userManaged: true } : {}),
+                    result,
+                });
+            }
+            catch (err) {
+                if (err instanceof LiveProbeUnsupportedError) {
+                    return c.json({
+                        error: "live_probe_unsupported",
+                        backend: backend.value,
+                        message: err.reason,
+                    }, 501);
+                }
+                logger.error({ err, key, backend: backend.value }, "live probe failed");
+                return c.json({
+                    error: "live_probe_failed",
+                    backend: backend.value,
+                    message: err instanceof Error ? err.message : String(err),
+                }, 500);
+            }
+        }
+        const tools = body?.tools;
+        if (tools === undefined) {
+            const cached = readProbe(db, key, backend.value);
+            // 200 + result:null when there's no cached row — distinguishes
+            // "endpoint missing" (which the unknown_integration / 404 above
+            // covers) from "endpoint worked but the cache is empty," so the
+            // dashboard callers can branch without parsing error codes.
+            return c.json({
+                ok: true,
+                cached: cached !== null,
+                ...(isUserManaged ? { userManaged: true } : {}),
+                result: cached,
+            });
+        }
+        if (!Array.isArray(tools) || tools.some((t) => typeof t !== "string")) {
+            return c.json({
+                error: "invalid_body",
+                message: "`tools` must be an array of MCP tool names (strings).",
+            }, 400);
+        }
+        try {
+            const result = isUserManaged
+                ? makeUserManagedProbeResult(key, backend.value, tools)
+                : evaluateProbe({
+                    tools: tools,
+                    integration: key,
+                    backend: backend.value,
+                });
+            writeProbe(db, result);
+            logger.info({
+                key,
+                backend: backend.value,
+                present: result.present,
+                missingRequired: result.missingRequired,
+                toolCount: result.presentTools.length,
+                userManaged: isUserManaged,
+            }, "integration probe persisted");
+            return c.json({
+                ok: true,
+                cached: false,
+                ...(isUserManaged ? { userManaged: true } : {}),
+                result,
+            });
+        }
+        catch (err) {
+            logger.error({ err, key, backend: backend.value }, "probe evaluation failed");
+            return c.json({ error: "internal_error" }, 500);
+        }
+    });
+    return app;
+}
+/**
+ * Tolerant JSON body reader for POST routes that accept an empty body
+ * (e.g. `POST /integrations/:key/probe` with no `tools` defaults to a
+ * cached read). Returns `{}` for an empty body, `null` for invalid JSON,
+ * and the parsed value otherwise.
+ */
+async function readOptionalJsonBody(c) {
+    try {
+        const raw = await c.req.text();
+        if (raw.trim() === "")
+            return {};
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveProbeBackend(raw, db, key) {
+    if (typeof raw === "string") {
+        if (!BACKEND_IDS.includes(raw)) {
+            return {
+                ok: false,
+                status: 400,
+                error: {
+                    error: "invalid_backend",
+                    message: `Unknown backend '${raw}'.`,
+                    supportedBackends: BACKEND_IDS,
+                },
+            };
+        }
+        return { ok: true, value: raw };
+    }
+    if (raw !== undefined) {
+        return {
+            ok: false,
+            status: 400,
+            error: {
+                error: "invalid_backend",
+                message: "`backend` must be a string when provided.",
+            },
+        };
+    }
+    // Default to the integration's `delegatedBackend` when one is
+    // configured — this is the backend the wizard would commit against.
+    const state = readIntegrations(db)[key];
+    if (state.delegatedBackend) {
+        return { ok: true, value: state.delegatedBackend };
+    }
+    return {
+        ok: false,
+        status: 400,
+        error: {
+            error: "backend_required",
+            message: "Pass `backend` in the request body — this integration is not currently delegated, so the daemon cannot infer one.",
+        },
+    };
+}
+function recordAuditModeChange(db, key, previous, next) {
+    try {
+        db.prepare(`INSERT INTO agent_actions
+         (event_id, action_type, trigger, result, detail, started_at, completed_at)
+       VALUES (?, 'integration.mode_change', 'reactive', 'success', ?, datetime('now'), datetime('now'))`).run(`integration:${key}:${Date.now()}`, JSON.stringify({
+            key,
+            from: {
+                mode: previous.mode,
+                delegatedBackend: previous.delegatedBackend ?? null,
+            },
+            to: {
+                mode: next.mode,
+                delegatedBackend: next.delegatedBackend ?? null,
+            },
+        }));
+    }
+    catch (err) {
+        logger.warn({ err, key }, "failed to write integration audit row");
+    }
+}
+function recordAuditPolicyChange(db, key, diff) {
+    try {
+        db.prepare(`INSERT INTO agent_actions
+         (event_id, action_type, trigger, result, detail, started_at, completed_at)
+       VALUES (?, 'integration.policy_change', 'reactive', 'success', ?, datetime('now'), datetime('now'))`).run(`integration:${key}:policy:${Date.now()}`, JSON.stringify({ key, deniedTools: diff }));
+    }
+    catch (err) {
+        logger.warn({ err, key }, "failed to write integration policy audit row");
+    }
+}
+function diffDeniedTools(previous, next) {
+    const prevSet = new Set(previous);
+    const nextSet = new Set(next);
+    const added = next.filter((t) => !prevSet.has(t));
+    const removed = previous.filter((t) => !nextSet.has(t));
+    return { added, removed };
+}
+/**
+ * Clamp a numeric request-body field to [min, max], applying `defaultValue`
+ * when omitted. Returns null on invalid input (NaN / wrong type), letting
+ * the caller surface a validation_error. When `allowFloat` is true (used
+ * for USD budgets), accepts floating-point; otherwise integer-only.
+ */
+function clampNumber(raw, defaultValue, min, max, allowFloat = false) {
+    if (raw === undefined || raw === null)
+        return defaultValue;
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return null;
+    if (!allowFloat && !Number.isInteger(raw))
+        return null;
+    if (raw < min || raw > max)
+        return null;
+    return raw;
+}
+/**
+ * DELEGATED-TASK-MODE-DESIGN.md §10 — map the task-mode error class to an
+ * HTTP status code. Mirrors the design's table 1:1.
+ */
+function mapTaskErrorClassToHttpStatus(errorClass) {
+    switch (errorClass) {
+        case "task_mode_disabled":
+            return 503;
+        case "task_quota_exhausted":
+            return 429;
+        case "task_mode_unsupported":
+            return 501;
+        case "delegated_proxy_busy":
+            return 503;
+        case "denied_tool":
+            return 403;
+        case "precondition":
+            return 409;
+        case "auth_error":
+            return 502;
+        case "tool_failed":
+        case "tool_unavailable":
+        case "parse_error":
+        case "schema_violation":
+        case "policy_violation":
+        case "post_write_format_failure":
+        case "loop_aborted":
+        case "budget_exhausted":
+            return 502;
+        case "timeout":
+        case "cancelled":
+            return 504;
+        case "subprocess_crashed":
+        default:
+            return 500;
+    }
+}
+function safeParseJson(s) {
+    try {
+        const parsed = JSON.parse(s);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * INTEGRATION-DRIFT-DETECTION-PLAN.md §11 Phase 4 — delegated chokepoint
+ * actor attribution. Branches on `connector.destructiveTools` membership;
+ * non-destructive tools (search / read / list) are left untouched. For
+ * write tools we run the response-shape extractor and fall back to args-
+ * shape extraction (for `{ ok: true }`-only label / archive responses);
+ * each surfaced id is marked in the persistent `integration_writes`
+ * table with the per-integration default TTL.
+ *
+ * Called from two surfaces:
+ *   - The `/exec` success path (active) — once per successful destructive
+ *     trace step. Each trace entry carries the parsed upstream
+ *     `toolResult`, so the response-shape extractor and the args-side
+ *     fallback both fire normally — symmetric to the legacy /invoke path
+ *     (id-in-response writes like send_email / create_event /
+ *     notion-create-pages are recovered in addition to id-in-args
+ *     deletes / updates / labels).
+ *   - The reserved `/invoke` route (commented) — once per call with the
+ *     full upstream `result.toolResult`. Same response-shape walk.
+ *
+ * Idempotent on extraction miss: returning early without any mark is the
+ * documented degradation path (causes one self-noticed observation, not
+ * data loss). The route handler always returns 2xx on a successful
+ * upstream call — this helper never throws back.
+ */
+function maybeMarkIntegrationWrite(db, args) {
+    if (!args.connector)
+        return;
+    if (!args.connector.destructiveTools.includes(args.bareTool))
+        return;
+    const extracted = extractWriteItemIds({
+        integration: args.integration,
+        bareTool: args.bareTool,
+        toolResult: args.toolResult,
+        args: args.args,
+    });
+    if (extracted.itemIds.length === 0) {
+        logger.debug({
+            integration: args.integration,
+            bareTool: args.bareTool,
+            reason: extracted.reason,
+        }, "destructive tool succeeded but no item id extracted — actor attribution will fall through to 'user' on next reconcile");
+        return;
+    }
+    for (const id of extracted.itemIds) {
+        markIntegrationWrite(db, args.integration, id);
+    }
+    logger.debug({
+        integration: args.integration,
+        bareTool: args.bareTool,
+        reason: extracted.reason,
+        itemCount: extracted.itemIds.length,
+    }, "marked integration_writes for destructive delegated call");
+}
+// ─────────────────────────────────────────────────────────────────────
+// RESERVED — `resolveCanonicalBareTool`
+//
+// Helper for the commented-out RPC `/invoke` route. Preserved verbatim
+// alongside the route handler for future reactivation.
+//
+// The /exec migration removed the brittle "agent supplies the bare
+// tool name" coupling that this helper compensated for; future RPC
+// re-introduction (admin endpoint, cost-sensitive fast path) would
+// likely want a *more* complete cross-backend alias translator
+// (walk every connector under the integration, not just the active
+// one) — see the alias-divergence root-cause notes in the route
+// handler comment above for context.
+//
+// DO NOT DELETE.
+// ─────────────────────────────────────────────────────────────────────
+/*
+function resolveCanonicalBareTool(
+  connector: IntegrationBackendConnector | undefined,
+  bare: string,
+): string {
+  if (!connector) return bare;
+  const capTools = connector.capabilityTools;
+  for (const aliases of Object.values(capTools)) {
+    if (aliases.includes(bare)) return bare;
+  }
+  const aliasesForKey = capTools[bare];
+  if (aliasesForKey && aliasesForKey.length > 0) {
+    return aliasesForKey[0];
+  }
+  return bare;
+}
+*/
+//# sourceMappingURL=integrations.js.map