@aitne/daemon 0.1.6 → 0.1.8

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

@@ -0,0 +1,320 @@
+/**
+ * `POST /api/integrations/:key/invoke` — RESERVED reactivation slot.
+ *
+ * The handler and the supporting `resolveCanonicalBareTool` helper were
+ * commented out 2026-05-01 as part of the /exec-only migration. They are
+ * preserved verbatim below for future reactivation. Today this register
+ * function is a no-op so the route does not exist; `/exec` (see
+ * `./exec.ts`) is the canonical surface.
+ *
+ * Why this file exists despite registering nothing:
+ *   - Keeping the reservation block in its own file gives future
+ *     reactivation a clear, self-contained home — uncomment the block,
+ *     re-import the helpers it needs (`matchToolPattern`,
+ *     `mapErrorClassToHttpStatus`, `IntegrationBackendConnector`,
+ *     `INTEGRATION_DESCRIPTORS`, `readIntegrations`,
+ *     `markIntegrationWrite`, `extractWriteItemIds`, `composeIssue`,
+ *     `respondWithAgentError`, `createLogger`, `readJsonBody`), and
+ *     register the route inside this function.
+ *   - Co-locating with the rest of the integrations routes keeps the
+ *     directory inventory complete (every entry in the file inventory
+ *     section of `docs/design/appendices/api-route-decomposition.md`
+ *     §5.4 maps to a real file).
+ *
+ * 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`).
+ *
+ * DO NOT DELETE the comment block — 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.
+ */
+export function registerInvokeRoutes(_app, _deps) {
+    // Intentional no-op. See block comments below for the dormant route
+    // body and the dormant `resolveCanonicalBareTool` helper preserved
+    // verbatim for future reactivation.
+}
+// ─────────────────────────────────────────────────────────────────────
+// 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 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 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 ────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────
+// 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=invoke.js.map

package/dist/api/routes/integrations/integrations/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../../../../../src/api/routes/integrations/integrations/invoke.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAU,EACV,KAAsB;IAEtB,oEAAoE;IACpE,mEAAmE;IACnE,oCAAoC;AACtC,CAAC;AAED,wEAAwE;AACxE,sEAAsE;AACtE,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,mEAAmE;AACnE,mEAAmE;AACnE,6DAA6D;AAC7D,oEAAoE;AACpE,wDAAwD;AACxD,oEAAoE;AACpE,6DAA6D;AAC7D,EAAE;AACF,sEAAsE;AACtE,sEAAsE;AACtE,iEAAiE;AACjE,sEAAsE;AACtE,iEAAiE;AACjE,+DAA+D;AAC/D,wDAAwD;AACxD,8DAA8D;AAC9D,gCAAgC;AAChC,EAAE;AACF,qEAAqE;AACrE,6DAA6D;AAC7D,2DAA2D;AAC3D,iEAAiE;AACjE,EAAE;AACF,mEAAmE;AACnE,uEAAuE;AACvE,mEAAmE;AACnE,qCAAqC;AACrC,oEAAoE;AACpE,kEAAkE;AAClE,gEAAgE;AAChE,8DAA8D;AAC9D,qEAAqE;AACrE,EAAE;AACF,kDAAkD;AAClD,sEAAsE;AACtE,6EAA6E;AAC7E,wEAAwE;AACxE,0EAA0E;AAC1E,2EAA2E;AAC3E,qBAAqB;AACrB,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,EAAE;AACF,+DAA+D;AAC/D,yDAAyD;AACzD,8CAA8C;AAC9C,wEAAwE;AACxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgME;AACF,wEAAwE;AAExE,wEAAwE;AACxE,wCAAwC;AACxC,EAAE;AACF,uEAAuE;AACvE,uDAAuD;AACvD,EAAE;AACF,mEAAmE;AACnE,mEAAmE;AACnE,mEAAmE;AACnE,+DAA+D;AAC/D,mEAAmE;AACnE,gEAAgE;AAChE,qCAAqC;AACrC,EAAE;AACF,iBAAiB;AACjB,wEAAwE;AACxE;;;;;;;;;;;;;;;;EAgBE"}

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

@@ -0,0 +1,21 @@
+import type { Hono } from "hono";
+import type { ApiDependencies } from "../../server.js";
+/**
+ * Register `POST /integrations/:key/probe` — evaluate or read the cached
+ * connector probe for a given backend. Phase 2 supports two modes:
+ *   - Live probe: `{liveProbe: true}` spawns the backend and enumerates
+ *     its MCP tool list, then persists.
+ *   - Cached read: body omits `tools`. Returns the latest stored row, or
+ *     `{result: null}` if no probe has been taken yet.
+ *   - Inline tools: `{tools: [...]}` accepts a pre-collected tool list
+ *     (the names the agent subprocess reported) and evaluates without
+ *     spawning. The dashboard's refresh button uses the live path;
+ *     `/health` and the setup wizard's initial render use the cached
+ *     path.
+ *
+ * No live agent subprocess is launched in the default path — keeping
+ * that out of the boot critical path is what saves the per-Opus probe
+ * cost called out in the §7 POC.
+ */
+export declare function registerProbeRoutes(app: Hono, deps: ApiDependencies): void;
+//# sourceMappingURL=probe.d.ts.map

package/dist/api/routes/integrations/integrations/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../../../../src/api/routes/integrations/integrations/probe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAwB1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIvD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CAuM1E"}

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

@@ -0,0 +1,247 @@
+import { BACKEND_IDS, INTEGRATION_DESCRIPTORS, isIntegrationKey, } from "@aitne/shared";
+import { evaluateProbe, getConnector, makeUserManagedProbeResult, } from "../../../core/integration-probe.js";
+import { LiveProbeUnsupportedError } from "../../../core/agent-core.js";
+import { readIntegrations, } from "../../../db/integrations-store.js";
+import { readProbe, writeProbe, } from "../../../db/integration-probe-store.js";
+import { createLogger } from "../../../logging.js";
+import { composeIssue, respondWithAgentError } from "../../helpers/agent-errors.js";
+const logger = createLogger("integrations-api");
+/**
+ * Register `POST /integrations/:key/probe` — evaluate or read the cached
+ * connector probe for a given backend. Phase 2 supports two modes:
+ *   - Live probe: `{liveProbe: true}` spawns the backend and enumerates
+ *     its MCP tool list, then persists.
+ *   - Cached read: body omits `tools`. Returns the latest stored row, or
+ *     `{result: null}` if no probe has been taken yet.
+ *   - Inline tools: `{tools: [...]}` accepts a pre-collected tool list
+ *     (the names the agent subprocess reported) and evaluates without
+ *     spawning. The dashboard's refresh button uses the live path;
+ *     `/health` and the setup wizard's initial render use the cached
+ *     path.
+ *
+ * No live agent subprocess is launched in the default path — keeping
+ * that out of the boot critical path is what saves the per-Opus probe
+ * cost called out in the §7 POC.
+ */
+export function registerProbeRoutes(app, deps) {
+    const { db } = deps;
+    app.post("/integrations/:key/probe", 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 body = await readOptionalJsonBody(c);
+        if (body === null) {
+            return respondWithAgentError(c, 400, [
+                composeIssue("integrations.invalid_json_body", {
+                    field: "body",
+                    received: "<not_json>",
+                }),
+            ]);
+        }
+        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);
+            /* c8 ignore start -- every registered (integration, backend) pair ships with a connector today; forward-compat guard for future partial connectors */
+            if (!connector) {
+                return c.json({
+                    error: "backend_not_supported",
+                    key,
+                    backend: backend.value,
+                    availableBackends: Object.keys(descriptorForProbe.backendConnectors),
+                }, 400);
+            }
+            /* c8 ignore stop */
+        }
+        // §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,
+            });
+            /* c8 ignore start -- evaluateProbe / writeProbe success path is always taken in tests; catch is defensive */
+        }
+        catch (err) {
+            logger.error({ err, key, backend: backend.value }, "probe evaluation failed");
+            return respondWithAgentError(c, 500, [
+                composeIssue("integrations.internal_error", {
+                    field: "<server>",
+                    received: "<probe_evaluation_failed>",
+                }),
+            ]);
+        }
+        /* c8 ignore stop */
+    });
+}
+/**
+ * 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.",
+        },
+    };
+}
+//# sourceMappingURL=probe.js.map

package/dist/api/routes/integrations/integrations/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../../../../src/api/routes/integrations/integrations/probe.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,38 @@
+import type { Hono } from "hono";
+import type { ApiDependencies } from "../../server.js";
+/**
+ * `POST /api/integrations/:key/invoke` — RESERVED reactivation slot.
+ *
+ * The handler and the supporting `resolveCanonicalBareTool` helper were
+ * commented out 2026-05-01 as part of the /exec-only migration. They are
+ * preserved verbatim below for future reactivation. Today this register
+ * function is a no-op so the route does not exist; `/exec` (see
+ * `./exec.ts`) is the canonical surface.
+ *
+ * Why this file exists despite registering nothing:
+ *   - Keeping the reservation block in its own file gives future
+ *     reactivation a clear, self-contained home — uncomment the block,
+ *     re-import the helpers it needs (`matchToolPattern`,
+ *     `mapErrorClassToHttpStatus`, `IntegrationBackendConnector`,
+ *     `INTEGRATION_DESCRIPTORS`, `readIntegrations`,
+ *     `markIntegrationWrite`, `extractWriteItemIds`, `composeIssue`,
+ *     `respondWithAgentError`, `createLogger`, `readJsonBody`), and
+ *     register the route inside this function.
+ *   - Co-locating with the rest of the integrations routes keeps the
+ *     directory inventory complete (every entry in the file inventory
+ *     section of `docs/design/appendices/api-route-decomposition.md`
+ *     §5.4 maps to a real file).
+ *
+ * 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`).
+ *
+ * DO NOT DELETE the comment block — 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.
+ */
+export declare function registerInvokeRoutes(_app: Hono, _deps: ApiDependencies): void;
+//# sourceMappingURL=invoke.d.ts.map

package/dist/api/routes/integrations/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../../../src/api/routes/integrations/invoke.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,eAAe,GACrB,IAAI,CAIN"}