@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/src/workflows/connect-mcp-server.ts

@@ -18,8 +18,15 @@
 
 import { proxyActivities, log } from "@temporalio/workflow";
 
-import type { createDiscoverMcpServerActivities } from "../activities/discover-mcp-server.js";
-import type { createClassifyToolApprovalsActivities } from "../activities/classify-tool-approvals.js";
+import type {
+  createDiscoverMcpServerActivities,
+  DiscoveredToolResult,
+  ToolApprovalDict,
+} from "../activities/discover-mcp-server.js";
+import type {
+  createClassifyToolApprovalsActivities,
+  ToolApprovalResult,
+} from "../activities/classify-tool-approvals.js";
 
 import type {
   ConnectMcpServerWorkflowInput,
@@ -48,6 +55,135 @@ function classifyWithTimeout(numTools: number) {
   });
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Incremental classification planner (pure, deterministic, sandbox-safe)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical, order-stable signature of a single tool's definition.
+ *
+ * Mirrors the shape `toolsFingerprint` hashes (name + description + input_schema)
+ * so "unchanged" here means the same thing it means for the whole-server
+ * fingerprint. Uses only JSON — no `node:crypto` — so it is safe to call from
+ * inside the Temporal deterministic V8 isolate.
+ */
+function toolSignature(tool: DiscoveredToolResult): string {
+  return JSON.stringify({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema ?? null,
+  });
+}
+
+/**
+ * Partition the freshly discovered tools into those that must be classified and
+ * the prior approval decisions that can be carried forward verbatim.
+ *
+ * Reuse is **content-addressed**: a prior decision is kept only when a tool's
+ * name AND full definition are byte-identical to the previous connect. This is
+ * deliberately stricter than reusing by name alone — a tool can keep its name
+ * while its schema changes from benign to destructive, and such a tool MUST be
+ * re-evaluated rather than left with a stale "auto-approve". Tools that are
+ * unchanged are never re-classified (stable, deterministic, no LLM cost; no
+ * flapping for borderline tools), and a tool present last time but gone now is
+ * simply absent from both outputs (dropped).
+ *
+ * The previous approval list is a presence-set of *gated* tools (a tool in
+ * `previousToolApprovals` requires approval; a known tool absent from it was
+ * auto-approved). So a reused tool emits a carried-forward entry only when it
+ * was gated; reused auto-approved tools emit nothing, which correctly keeps them
+ * un-gated. `ClassifyToolApprovals` likewise returns only gated entries, so the
+ * union `[...carriedForward, ...classified]` is the complete gated set.
+ *
+ * Pure and free of Temporal APIs so it can be exhaustively unit-tested and is
+ * safe to evaluate inside the workflow sandbox.
+ */
+export function planIncrementalClassification(
+  previousTools: DiscoveredToolResult[],
+  previousToolApprovals: ToolApprovalDict[],
+  currentTools: DiscoveredToolResult[],
+): { toolsToClassify: DiscoveredToolResult[]; carriedForward: ToolApprovalResult[] } {
+  const prevSigByName = new Map<string, string>();
+  for (const tool of previousTools) {
+    prevSigByName.set(tool.name, toolSignature(tool));
+  }
+
+  const prevGatedByName = new Map<string, ToolApprovalDict>();
+  for (const approval of previousToolApprovals) {
+    prevGatedByName.set(approval.toolName, approval);
+  }
+
+  const toolsToClassify: DiscoveredToolResult[] = [];
+  const carriedForward: ToolApprovalResult[] = [];
+
+  for (const tool of currentTools) {
+    const prevSig = prevSigByName.get(tool.name);
+    const unchanged = prevSig !== undefined && prevSig === toolSignature(tool);
+
+    if (!unchanged) {
+      toolsToClassify.push(tool);
+      continue;
+    }
+
+    const gated = prevGatedByName.get(tool.name);
+    if (gated) {
+      carriedForward.push({
+        tool_name: gated.toolName,
+        requires_approval: true,
+        message: gated.message,
+      });
+    }
+    // An unchanged tool that was not gated stays auto-approved — emit nothing.
+  }
+
+  return { toolsToClassify, carriedForward };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// destructiveHint fail-closed tightener (pure, deterministic, sandbox-safe)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Force-gate any tool whose live MCP annotation declares `destructiveHint:true`
+ * but that the classifier (or carry-forward) left un-gated.
+ *
+ * This is the ONLY way annotations influence policy, and it is deliberately
+ * one-directional. The MCP spec warns that clients must never make tool-use
+ * decisions on annotations from untrusted servers; trusting a server's
+ * "I am destructive" claim only ever ADDS an approval prompt (the safe
+ * direction), so it cannot be abused. The inverse — trusting `readOnlyHint` to
+ * AUTO-APPROVE — is exactly the unsafe direction the spec forbids, so a spoofed
+ * `readOnlyHint:true` on a destructive tool must never relax it. Read-only
+ * auto-approval authority lives solely with the trusted LLM classifier.
+ *
+ * Recomputed from live discovery on every connect, so it has zero coupling to
+ * `toolSignature`/incremental reuse and needs no persistence. Pure JS so it is
+ * safe to evaluate inside the Temporal deterministic isolate.
+ */
+export function applyDestructiveHintTightener(
+  gated: ToolApprovalResult[],
+  currentTools: DiscoveredToolResult[],
+): { tightened: ToolApprovalResult[]; addedCount: number } {
+  const gatedNames = new Set(gated.map((g) => g.tool_name));
+  const tightened = [...gated];
+  let addedCount = 0;
+
+  for (const tool of currentTools) {
+    if (tool.annotations?.destructiveHint === true && !gatedNames.has(tool.name)) {
+      tightened.push({
+        tool_name: tool.name,
+        requires_approval: true,
+        message: `Execute ${tool.name}`,
+        from_destructive_hint: true,
+      });
+      gatedNames.add(tool.name);
+      addedCount++;
+    }
+  }
+
+  return { tightened, addedCount };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // ConnectMcpServerWorkflow — primary connect flow
 // ─────────────────────────────────────────────────────────────────────────────
@@ -61,32 +197,32 @@ export async function connectMcpServer(
     invokerIdentityAccountId: input.invoker_identity_account_id ?? null,
   });
 
-  const canReusePreviousApprovals =
-    discovery.newToolsFingerprint !== "" &&
-    discovery.newToolsFingerprint === discovery.previousToolsFingerprint &&
-    discovery.previousToolApprovals.length > 0;
+  // Content-addressed incremental classification: reuse prior decisions for
+  // tools whose definition is unchanged, and classify only the new or changed
+  // ones. Keeps decisions stable/deterministic across reconnects and avoids
+  // redundant LLM calls, while still re-evaluating a tool whose schema changed.
+  const { toolsToClassify, carriedForward } = planIncrementalClassification(
+    discovery.previousTools,
+    discovery.previousToolApprovals,
+    discovery.tools,
+  );
 
-  let toolApprovals: Array<{
-    tool_name: string;
-    requires_approval: boolean;
-    message: string;
-  }>;
+  let toolApprovals: ToolApprovalResult[];
 
-  if (canReusePreviousApprovals) {
+  if (toolsToClassify.length === 0) {
     log.info(
-      `Tools unchanged for '${input.mcp_server_id}' ` +
-        `(fingerprint ${discovery.newToolsFingerprint.slice(0, 12)}) — ` +
-        `reusing ${discovery.previousToolApprovals.length} previous approval(s)`,
+      `Tools unchanged for '${input.mcp_server_id}' — reusing ` +
+        `${carriedForward.length} previous approval(s), no classification needed`,
     );
-
-    toolApprovals = discovery.previousToolApprovals.map((a) => ({
-      tool_name: a.toolName,
-      requires_approval: a.requiresApproval,
-      message: a.message,
-    }));
+    toolApprovals = carriedForward;
   } else {
+    log.info(
+      `Classifying ${toolsToClassify.length} new/changed tool(s) for ` +
+        `'${input.mcp_server_id}', reusing ${carriedForward.length} prior decision(s)`,
+    );
+
     const classifyInput = {
-      tools: discovery.tools.map((t) => ({
+      tools: toolsToClassify.map((t) => ({
         name: t.name,
         description: t.description,
         input_schema: t.inputSchema ?? null,
@@ -96,9 +232,28 @@ export async function connectMcpServer(
       mcpServerId: input.mcp_server_id,
     };
 
-    const classify = classifyWithTimeout(discovery.tools.length);
-    toolApprovals = await classify.ClassifyToolApprovals(classifyInput);
+    const classify = classifyWithTimeout(toolsToClassify.length);
+    const classified = await classify.ClassifyToolApprovals(classifyInput);
+    toolApprovals = [...carriedForward, ...classified];
+  }
+
+  // Fail-closed tightener over the FULL live tool set: a tool the server's own
+  // annotation marks destructiveHint=true is force-gated if it slipped through
+  // un-gated. Runs on live discovery (not the reused/classified subset), so it
+  // also re-asserts gating for carried-forward tools whose server later flips a
+  // tool to destructive. We never trust readOnlyHint to relax — see the
+  // tightener's contract for the MCP untrusted-hints rationale.
+  const { tightened, addedCount } = applyDestructiveHintTightener(
+    toolApprovals,
+    discovery.tools,
+  );
+  if (addedCount > 0) {
+    log.info(
+      `Force-gated ${addedCount} tool(s) via destructiveHint annotation for ` +
+        `'${input.mcp_server_id}'`,
+    );
   }
+  toolApprovals = tightened;
 
   return {
     tools: discovery.tools.map((t) => ({

package/src/workflows/types.ts

@@ -49,6 +49,14 @@ export interface WireToolApproval {
   tool_name: string;
   requires_approval: boolean;
   message: string;
+  /**
+   * True when the connect-time destructiveHint tightener force-gated this tool
+   * (see applyDestructiveHintTightener). Persisted to
+   * ToolApprovalPolicy.from_destructive_hint so the runner attributes the gate to
+   * the annotation rather than the classifier. Omitted on classifier/pinned
+   * entries.
+   */
+  from_destructive_hint?: boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────