@aitne/daemon 0.1.7 → 0.1.9

package/dist/api/routes/integrations/crud.js

@@ -0,0 +1,157 @@
+import { BACKEND_IDS, INTEGRATION_DESCRIPTORS, INTEGRATION_KEYS, isIntegrationKey, } from "@aitne/shared";
+import { readIntegrations } from "../../../db/integrations-store.js";
+import { listProxyModelOptions, resolveCanonicalDelegatedModel, } from "../../../core/backends/proxy-model-registry.js";
+import { composeIssue, respondWithAgentError } from "../../helpers/agent-errors.js";
+import { handleIntegrationPatch } from "./crud-patch.js";
+/**
+ * Register the integration CRUD routes:
+ *   - `GET    /integrations`
+ *   - `GET    /integrations/:key/recent-proxy-calls`
+ *   - `GET    /integrations/proxy-models/:backend`
+ *   - `PATCH  /integrations/:key`
+ *
+ * PATCH body lives in `./crud-patch.ts:handleIntegrationPatch` because the
+ * full lifecycle (validate / flip-lock / probe-cache / re-materialise /
+ * audit) is ~700 lines and would push this file past the ~800-line soft
+ * ceiling.
+ */
+export function registerCrudRoutes(app, deps) {
+    const { db } = 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 respondWithAgentError(c, 404, [
+                composeIssue("integrations.unknown_integration", {
+                    field: "key",
+                    received: key,
+                }),
+            ], { legacyFields: { key } });
+        }
+        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 respondWithAgentError(c, 400, [
+                    composeIssue("integrations.invalid_limit", {
+                        field: "limit",
+                        received: rawLimit,
+                    }),
+                ], {
+                    legacyFields: {
+                        message: "limit must be a positive integer (default 50, max 200)",
+                    },
+                });
+            }
+            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) => {
+            /* c8 ignore next -- sql WHERE json_extract filters out rows with null detail */
+            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", (c) => handleIntegrationPatch(c, deps));
+}
+function safeParseJson(s) {
+    try {
+        const parsed = JSON.parse(s);
+        /* c8 ignore next -- sql WHERE guarantees only object-typed detail rows reach here */
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        return parsed;
+        /* c8 ignore start -- sql WHERE json_extract would reject malformed JSON rows */
+    }
+    catch {
+        return null;
+    }
+    /* c8 ignore stop */
+}

package/dist/api/routes/integrations/exec.d.ts

@@ -0,0 +1,22 @@
+import type { Hono } from "hono";
+import type { ApiDependencies } from "../../server.js";
+/**
+ * Register `POST /integrations/:key/exec` — task-mode delegated invocation
+ * (DELEGATED-TASK-MODE-DESIGN.md §4.1).
+ *
+ * Pre-flight order (cheapest first; matches the dormant /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. x-session-backend header (if set) ≠ delegatedBackend (409 same
+ *      defense-in-depth as /invoke — same-backend should use native MCP).
+ *   7. Invoker wired (501).
+ *
+ * Risk tier: Autonomous (no Bearer required). Tool-level safety lives
+ * in `state.deniedTools` + `destructiveTools`, both enforced at the
+ * chokepoint by the invoker.
+ */
+export declare function registerExecRoutes(app: Hono, deps: ApiDependencies): void;

package/dist/api/routes/integrations/exec.js

@@ -0,0 +1,349 @@
+import { DELEGATED_TASK_HARD_CAPS, INTEGRATION_DESCRIPTORS, isIntegrationKey, } from "@aitne/shared";
+import { checkOutputSchema } from "../../../services/delegated-task-runtime.js";
+import { readIntegrations } from "../../../db/integrations-store.js";
+import { readJsonBody } from "../../json-body.js";
+import { createLogger } from "../../../logging.js";
+import { composeIssue, respondWithAgentError } from "../../helpers/agent-errors.js";
+import { extractWriteItemIds } from "../../../services/integrations/extract-write-item-id.js";
+import { markIntegrationWrite } from "../../../safety/integration-write-tracker.js";
+const logger = createLogger("integrations-api");
+/**
+ * Register `POST /integrations/:key/exec` — task-mode delegated invocation
+ * (DELEGATED-TASK-MODE-DESIGN.md §4.1).
+ *
+ * Pre-flight order (cheapest first; matches the dormant /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. x-session-backend header (if set) ≠ delegatedBackend (409 same
+ *      defense-in-depth as /invoke — same-backend should use native MCP).
+ *   7. Invoker wired (501).
+ *
+ * Risk tier: Autonomous (no Bearer required). Tool-level safety lives
+ * in `state.deniedTools` + `destructiveTools`, both enforced at the
+ * chokepoint by the invoker.
+ */
+export function registerExecRoutes(app, deps) {
+    app.post("/integrations/:key/exec", async (c) => {
+        const key = c.req.param("key");
+        if (!isIntegrationKey(key)) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("integrations.unknown_integration", {
+                    field: "key",
+                    received: key,
+                }),
+            ], { legacyFields: { key } });
+        }
+        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 uses daemon-side stream pre-emption (see
+        // codex-core.ts `runDelegatedTask`) to gate allowed-tools / destructive
+        // calls without relying on a CLI-level allowedTools surface. Codex
+        // /exec requests 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);
+    });
+}
+/**
+ * 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;
+    }
+}
+/**
+ * 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 one surface today:
+ *   - The `/exec` success path — 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 (id-in-response writes like send_email /
+ *     create_event / notion-create-pages are recovered in addition to
+ *     id-in-args deletes / updates / labels).
+ *
+ * The internal guards on `connector` / `destructiveTools` membership are
+ * retained as defense-in-depth (c8 ignored) so any future second caller
+ * can re-share the helper safely without re-deriving the pre-filter
+ * contract.
+ *
+ * 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) {
+    /* c8 ignore next -- /exec callsite pre-filters via `if (connector)`; this guard is defense-in-depth that survives /invoke retirement and protects any future re-share */
+    if (!args.connector)
+        return;
+    /* c8 ignore next -- /exec callsite pre-filters via `if (destructiveTools.includes(...))`; same defense-in-depth as above */
+    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");
+}

package/dist/api/routes/integrations/index.d.ts

@@ -0,0 +1,61 @@
+import { Hono } from "hono";
+import type { ApiDependencies } from "../../server.js";
+/**
+ * Integration Delegation Framework — `/api/integrations` routes.
+ *
+ * Surface:
+ *   - `GET /api/integrations` — list every registered integration with its
+ *     descriptor metadata and current state.
+ *   - `GET /api/integrations/:key/recent-proxy-calls` — last N delegated
+ *     proxy invocations for the dashboard's IntegrationCard.
+ *   - `GET /api/integrations/proxy-models/:backend` — registered + pinned
+ *     proxy-model options for the dashboard's model dropdown.
+ *   - `PATCH /api/integrations/:key` — change a single integration's mode.
+ *     Runs the full lifecycle: validate → flip-lock acquire → §14.7 probe →
+ *     DB update → `integrations.md` re-render → running-session
+ *     re-materialisation → audit row → flip-lock release.
+ *   - `POST /api/integrations/:key/exec` — cross-backend delegated proxy
+ *     (DELEGATED-MODE-V2-DESIGN.md §11 / `docs/design/14-integration-delegation.md` §14.4.5).
+ *   - `POST /api/integrations/:key/probe` — descriptor + cached + live
+ *     probe paths (`docs/design/14-integration-delegation.md` §14.7).
+ *
+ * The historical `POST /api/integrations/:key/invoke` RPC chokepoint was
+ * retired 2026-05-01 as part of the /exec-only migration. The dormant
+ * stub file `invoke.ts` was removed in the api-route-decomposition.md
+ * PR-5 follow-up (commented-out handler body lives in git history; the
+ * `runDelegatedTool()` internals it relied on remain wired through
+ * `delegated-sync-worker` for hourly drift detection). Future
+ * reactivation should land back at the same `RiskTier.Autonomous`
+ * classification preserved in `risk-classifier.ts`.
+ *
+ * Observer gating, the route-410 middleware (`integration-route-gate.ts`),
+ * skill / task-flow variant selection, and the connector probe are all
+ * production paths.
+ *
+ * Mode model. `IntegrationMode = "direct" | "delegated" | "native" | "disabled"`.
+ *   - `direct` — daemon poller + `/api/<integration>/*` daemon routes.
+ *   - `delegated` — `delegated-sync-worker` cadences + `/exec` proxy.
+ *   - `native` — main backend reaches the integration via its own native
+ *     MCP / connector; daemon does no polling. Per-tick data acquisition
+ *     for routines (morning / evening / hourly / weekly / monthly) runs in a
+ *     separate pre-pass session on the `routine.fetch_window` ProcessKey
+ *     and POSTs observations to `/api/observations`. See
+ *     [`docs/design/appendices/routine-data-acquisition.md`](../../../../../docs/design/appendices/routine-data-acquisition.md)
+ *     for the per-routine × per-integration acquisition contract.
+ *   - `disabled` — silence. Routes 410 with `X-Integration-Mode: disabled`.
+ *
+ * User-managed connectors (`descriptor.userManagedConnector === true`,
+ * today `outlook_mail` / `outlook_calendar`) skip the descriptor-driven
+ * variant gates: there is no daemon-shipped `SKILL.<mode>.<backend>.md`
+ * for them, and routine-side acquisition flows through the per-integration
+ * partial (RDAD §6.8) rather than a variant fan-out.
+ *
+ * Risk tier: Approve (dashboard-only mutation, registered in
+ * `risk-classifier.ts`).
+ *
+ * Registration order matches the original handler declaration order so
+ * Hono route-match precedence is byte-identical to the pre-split file
+ * (file-split-plan R2). Verify with
+ * `app.routes.map(r => r.path)` before/after when in doubt.
+ */
+export declare function createIntegrationRoutes(deps: ApiDependencies): Hono;

package/dist/api/routes/integrations/index.js

@@ -0,0 +1,69 @@
+import { Hono } from "hono";
+import { registerCrudRoutes } from "./crud.js";
+import { registerExecRoutes } from "./exec.js";
+import { registerProbeRoutes } from "./probe.js";
+/**
+ * Integration Delegation Framework — `/api/integrations` routes.
+ *
+ * Surface:
+ *   - `GET /api/integrations` — list every registered integration with its
+ *     descriptor metadata and current state.
+ *   - `GET /api/integrations/:key/recent-proxy-calls` — last N delegated
+ *     proxy invocations for the dashboard's IntegrationCard.
+ *   - `GET /api/integrations/proxy-models/:backend` — registered + pinned
+ *     proxy-model options for the dashboard's model dropdown.
+ *   - `PATCH /api/integrations/:key` — change a single integration's mode.
+ *     Runs the full lifecycle: validate → flip-lock acquire → §14.7 probe →
+ *     DB update → `integrations.md` re-render → running-session
+ *     re-materialisation → audit row → flip-lock release.
+ *   - `POST /api/integrations/:key/exec` — cross-backend delegated proxy
+ *     (DELEGATED-MODE-V2-DESIGN.md §11 / `docs/design/14-integration-delegation.md` §14.4.5).
+ *   - `POST /api/integrations/:key/probe` — descriptor + cached + live
+ *     probe paths (`docs/design/14-integration-delegation.md` §14.7).
+ *
+ * The historical `POST /api/integrations/:key/invoke` RPC chokepoint was
+ * retired 2026-05-01 as part of the /exec-only migration. The dormant
+ * stub file `invoke.ts` was removed in the api-route-decomposition.md
+ * PR-5 follow-up (commented-out handler body lives in git history; the
+ * `runDelegatedTool()` internals it relied on remain wired through
+ * `delegated-sync-worker` for hourly drift detection). Future
+ * reactivation should land back at the same `RiskTier.Autonomous`
+ * classification preserved in `risk-classifier.ts`.
+ *
+ * Observer gating, the route-410 middleware (`integration-route-gate.ts`),
+ * skill / task-flow variant selection, and the connector probe are all
+ * production paths.
+ *
+ * Mode model. `IntegrationMode = "direct" | "delegated" | "native" | "disabled"`.
+ *   - `direct` — daemon poller + `/api/<integration>/*` daemon routes.
+ *   - `delegated` — `delegated-sync-worker` cadences + `/exec` proxy.
+ *   - `native` — main backend reaches the integration via its own native
+ *     MCP / connector; daemon does no polling. Per-tick data acquisition
+ *     for routines (morning / evening / hourly / weekly / monthly) runs in a
+ *     separate pre-pass session on the `routine.fetch_window` ProcessKey
+ *     and POSTs observations to `/api/observations`. See
+ *     [`docs/design/appendices/routine-data-acquisition.md`](../../../../../docs/design/appendices/routine-data-acquisition.md)
+ *     for the per-routine × per-integration acquisition contract.
+ *   - `disabled` — silence. Routes 410 with `X-Integration-Mode: disabled`.
+ *
+ * User-managed connectors (`descriptor.userManagedConnector === true`,
+ * today `outlook_mail` / `outlook_calendar`) skip the descriptor-driven
+ * variant gates: there is no daemon-shipped `SKILL.<mode>.<backend>.md`
+ * for them, and routine-side acquisition flows through the per-integration
+ * partial (RDAD §6.8) rather than a variant fan-out.
+ *
+ * Risk tier: Approve (dashboard-only mutation, registered in
+ * `risk-classifier.ts`).
+ *
+ * Registration order matches the original handler declaration order so
+ * Hono route-match precedence is byte-identical to the pre-split file
+ * (file-split-plan R2). Verify with
+ * `app.routes.map(r => r.path)` before/after when in doubt.
+ */
+export function createIntegrationRoutes(deps) {
+    const app = new Hono();
+    registerCrudRoutes(app, deps);
+    registerExecRoutes(app, deps);
+    registerProbeRoutes(app, deps);
+    return app;
+}