@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/src/activities/__tests__/discover-mcp-server.test.ts

@@ -168,6 +168,33 @@ describe("DiscoverMcpServer activity", () => {
       );
     });
 
+    it("returns previous tool definitions for incremental diffing", async () => {
+      const { extractPreviousState } = await import("../discover-mcp-server.js");
+      const server = makeMcpServer({
+        status: {
+          discoveredCapabilities: {
+            tools: [
+              { name: "search", description: "Search things", inputSchema: { type: "object" } },
+              { name: "delete_repo", description: "Delete a repo", inputSchema: null },
+            ],
+            resourceTemplates: [],
+          },
+          toolApprovals: [{ toolName: "delete_repo", message: "Delete" }],
+        },
+      });
+      const state = extractPreviousState(server);
+      expect(state.tools).toEqual([
+        { name: "search", description: "Search things", inputSchema: { type: "object" } },
+        { name: "delete_repo", description: "Delete a repo", inputSchema: null },
+      ]);
+    });
+
+    it("returns empty previous tools when server has no status", async () => {
+      const { extractPreviousState } = await import("../discover-mcp-server.js");
+      const state = extractPreviousState(makeMcpServer({ status: undefined }));
+      expect(state.tools).toEqual([]);
+    });
+
     it("extracts tool approvals from status", async () => {
       const { extractPreviousState } = await import("../discover-mcp-server.js");
       const server = makeMcpServer({
@@ -444,6 +471,9 @@ describe("DiscoverMcpServer activity", () => {
       expect(result.previousToolApprovals).toEqual([
         { toolName: "old_tool", requiresApproval: true, message: "Approve old_tool" },
       ]);
+      expect(result.previousTools).toEqual([
+        { name: "old_tool", description: "Old", inputSchema: null },
+      ]);
       expect(result.tools[0].name).toBe("new_tool");
       expect(result.newToolsFingerprint).toHaveLength(64);
       expect(result.newToolsFingerprint).not.toBe(result.previousToolsFingerprint);

package/src/activities/__tests__/workflow-event-activities.test.ts

@@ -329,7 +329,8 @@ describe("toProtoEvent", () => {
         attemptNumber: 1,
       };
       const proto = toProtoEvent(desc);
-      expect(proto.payload.value?.taskKind).toBe(WorkflowTaskKind.agent_call);
+      if (proto.payload.case !== "taskStarted") throw new Error("unexpected");
+      expect(proto.payload.value.taskKind).toBe(WorkflowTaskKind.agent_call);
     });
   });
 

package/src/activities/call-agent-status.ts

@@ -15,9 +15,9 @@
 import { StigmerClient } from "../client/stigmer-client.js";
 import { loadConfig } from "../config.js";
 import { create } from "@bufbuild/protobuf";
-import { WorkflowExecutionStatusSchema, WorkflowPendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionStatusSchema, WorkflowPendingApprovalSchema, WorkflowPendingFileReviewSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
 import type { ChildApprovalNotification } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
-import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ToolCallStatus, FileChangeSetStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 function buildClient(): StigmerClient {
   const config = loadConfig();
@@ -34,12 +34,13 @@ export async function updateWorkflowTaskApprovalStatus(
 ): Promise<void> {
   if (!executionId) return;
 
+  const childExecId = notification.executionId;
   const client = buildClient();
   const pendingApprovals = (notification.pendingApprovals ?? []).map(
     (approval) =>
       create(WorkflowPendingApprovalSchema, {
         approval,
-        childAgentExecutionId: notification.executionId,
+        childAgentExecutionId: childExecId,
       }),
   );
 
@@ -47,24 +48,91 @@ export async function updateWorkflowTaskApprovalStatus(
     pendingApprovals,
   });
 
+  // Per-child merge scoped to this child: the write replaces only this child's
+  // approvals and preserves every parallel sibling's entries.
   await client.updateWorkflowExecutionStatus(executionId, status, {
     updatePendingApprovals: true,
+    pendingUpdateChildAgentExecutionId: childExecId,
   });
 }
 
 export async function clearWorkflowApprovalStatus(
   executionId: string,
+  childExecutionId: string,
 ): Promise<void> {
-  if (!executionId) return;
+  if (!executionId || !childExecutionId) return;
 
   const client = buildClient();
   const status = create(WorkflowExecutionStatusSchema, {
     pendingApprovals: [],
   });
 
+  // Scoped clear: empty list for this child clears only its approvals; sibling
+  // children still awaiting approval are untouched.
   await client.updateWorkflowExecutionStatus(executionId, status, {
     updatePendingApprovals: true,
+    pendingUpdateChildAgentExecutionId: childExecutionId,
+  });
+}
+
+/**
+ * Surfaces (or clears) a child agent's file-review gate on the parent workflow.
+ *
+ * Reference-only: writes a single WorkflowPendingFileReview naming the child and
+ * the change_set ids it currently has AWAITING_REVIEW — never the diffs, which
+ * stay single-sourced on the child. Passing an empty changeSetIds clears this
+ * child's entry (per-child merge, so parallel siblings are never disturbed).
+ */
+export async function updateWorkflowFileReviewStatus(
+  executionId: string,
+  childExecutionId: string,
+  changeSetIds: string[],
+): Promise<void> {
+  if (!executionId || !childExecutionId) return;
+
+  const client = buildClient();
+  const pendingFileReviews =
+    changeSetIds.length > 0
+      ? [
+          create(WorkflowPendingFileReviewSchema, {
+            childAgentExecutionId: childExecutionId,
+            changeSetId: changeSetIds,
+          }),
+        ]
+      : [];
+
+  const status = create(WorkflowExecutionStatusSchema, {
+    pendingFileReviews,
   });
+
+  await client.updateWorkflowExecutionStatus(executionId, status, {
+    updatePendingFileReviews: true,
+    pendingUpdateChildAgentExecutionId: childExecutionId,
+  });
+}
+
+/**
+ * Reads the child agent execution and returns the ids of its change sets that
+ * are currently AWAITING_REVIEW. The gated child is non-terminal, so its last
+ * status write stored a populated file_change_sets projection; GET returns it
+ * (the same reason getAgentExecutionProgress reads status.messages).
+ */
+export async function getAwaitingFileReviewChangeSetIds(
+  childExecutionId: string,
+): Promise<string[]> {
+  if (!childExecutionId) return [];
+
+  try {
+    const client = buildClient();
+    const execution = await client.getExecution(childExecutionId);
+    const changeSets = execution?.status?.fileChangeSets ?? [];
+    return changeSets
+      .filter((cs) => cs.status === FileChangeSetStatus.AWAITING_REVIEW)
+      .map((cs) => cs.id);
+  } catch (err) {
+    console.warn("Failed to fetch child file-review state (non-fatal):", String(err));
+    return [];
+  }
 }
 
 /**
@@ -125,6 +193,8 @@ export function createCallAgentStatusActivities() {
   return {
     UpdateWorkflowTaskApprovalStatus: updateWorkflowTaskApprovalStatus,
     ClearWorkflowApprovalStatus: clearWorkflowApprovalStatus,
+    UpdateWorkflowFileReviewStatus: updateWorkflowFileReviewStatus,
+    GetAwaitingFileReviewChangeSetIds: getAwaitingFileReviewChangeSetIds,
     GetAgentExecutionProgress: getAgentExecutionProgress,
   };
 }

package/src/activities/call-llm.ts

@@ -16,8 +16,6 @@
  *   Output: LlmCallResult
  */
 
-import { ChatAnthropic } from "@langchain/anthropic";
-import { ChatOpenAI } from "@langchain/openai";
 import { HumanMessage, SystemMessage } from "@langchain/core/messages";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import type { BaseMessageChunk } from "@langchain/core/messages";
@@ -28,12 +26,11 @@ import { jsonSchemaToZod } from "../shared/json-schema-to-zod.js";
 import {
   inferProvider,
   stripProviderPrefix,
-  resolveProxyBaseUrl,
-  buildProxyHeaders,
   type LlmProvider,
 } from "../shared/llm-proxy.js";
 import { computeLlmCostMicros, ensureLoaded as ensurePricingLoaded } from "../shared/model-pricing.js";
 import { resolveToApiModelId } from "../shared/model-registry.js";
+import { buildChatModel } from "../shared/model-client.js";
 
 export interface LlmCallConfig {
   readonly model: string;
@@ -54,54 +51,6 @@ export interface LlmCallResult {
   readonly parse_error?: string;
 }
 
-function constructModel(
-  provider: LlmProvider,
-  modelId: string,
-  config: LlmCallConfig,
-  baseUrl?: string,
-  headers?: Record<string, string>,
-): BaseChatModel {
-  if (provider === "openai") {
-    const apiKey = baseUrl
-      ? (headers?.Authorization?.replace("Bearer ", "") ?? "proxy-managed")
-      : (process.env.OPENAI_API_KEY ?? "");
-
-    return new ChatOpenAI({
-      model: modelId,
-      temperature: config.temperature ?? 0,
-      maxTokens: config.max_tokens,
-      ...(baseUrl || headers
-        ? {
-            configuration: {
-              ...(baseUrl ? { baseURL: baseUrl } : {}),
-              ...(headers ? { defaultHeaders: headers } : {}),
-            },
-          }
-        : {}),
-      apiKey,
-    });
-  }
-
-  const apiKey = baseUrl
-    ? (headers?.Authorization?.replace("Bearer ", "") ?? "proxy-managed")
-    : (process.env.ANTHROPIC_API_KEY ?? "");
-
-  return new ChatAnthropic({
-    model: modelId,
-    temperature: config.temperature ?? 0,
-    maxTokens: config.max_tokens ?? 4096,
-    ...(baseUrl || headers
-      ? {
-          clientOptions: {
-            ...(baseUrl ? { baseURL: baseUrl } : {}),
-            ...(headers ? { defaultHeaders: headers } : {}),
-          },
-        }
-      : {}),
-    apiKey,
-  });
-}
-
 /**
  * Stream a chat model invocation and collect the response.
  *
@@ -274,22 +223,18 @@ export async function callLlmAction(
     `structured=${!!config.response_schema} execution=${executionId}`,
   );
 
-  let baseUrl: string | undefined;
-  let headers: Record<string, string> | undefined;
-
-  if (proxyActive) {
-    baseUrl = resolveProxyBaseUrl(proxyEndpoint!, provider);
-    headers = buildProxyHeaders(stigmerToken!, { workflowExecutionId: executionId });
-  } else if (provider === "openai") {
-    if (!process.env.OPENAI_API_KEY) {
+  // Direct mode (no proxy) requires the provider's own API key. Validated here
+  // rather than in buildChatModel so the shared module stays free of Temporal
+  // failure types.
+  if (!proxyActive) {
+    if (provider === "openai" && !process.env.OPENAI_API_KEY) {
       throw ApplicationFailure.nonRetryable(
         `OPENAI_API_KEY is not set and no proxy is configured. ` +
         `Set the API key in your environment or connect to a Stigmer Cloud deployment.`,
         "LLM_MISSING_API_KEY",
       );
     }
-  } else {
-    if (!process.env.ANTHROPIC_API_KEY) {
+    if (provider === "anthropic" && !process.env.ANTHROPIC_API_KEY) {
       throw ApplicationFailure.nonRetryable(
         `ANTHROPIC_API_KEY is not set and no proxy is configured. ` +
         `Set the API key in your environment or connect to a Stigmer Cloud deployment.`,
@@ -298,7 +243,17 @@ export async function callLlmAction(
     }
   }
 
-  const model = constructModel(provider, modelId, config, baseUrl, headers);
+  // Anthropic requires an explicit maxTokens; preserve the 4096 default here
+  // (buildChatModel intentionally imposes none). resolvedModel is already an
+  // API id, so buildChatModel's resolve step is a no-op for it.
+  const { model } = await buildChatModel({
+    modelName: resolvedModel,
+    proxyEndpoint: proxyActive ? proxyEndpoint : undefined,
+    stigmerToken: proxyActive ? stigmerToken : undefined,
+    headerScope: { workflowExecutionId: executionId },
+    temperature: config.temperature,
+    maxTokens: provider === "anthropic" ? (config.max_tokens ?? 4096) : config.max_tokens,
+  });
 
   const messages: (HumanMessage | SystemMessage)[] = [];
   if (config.system_prompt) {

package/src/activities/classify-tool-approvals.ts

@@ -19,11 +19,10 @@
  */
 
 import { z } from "zod";
-import { ChatOpenAI } from "@langchain/openai";
 import { SystemMessage, HumanMessage } from "@langchain/core/messages";
 import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { getSummarizationModel } from "../shared/model-registry.js";
-import { resolveProxyBaseUrl, buildProxyHeaders } from "../shared/llm-proxy.js";
+import { buildChatModel } from "../shared/model-client.js";
 import type { Config } from "../config.js";
 
 const BATCH_SIZE = 40;
@@ -51,6 +50,15 @@ export interface ToolApprovalResult {
   tool_name: string;
   requires_approval: boolean;
   message: string;
+  /**
+   * True when the connect-time fail-closed tightener force-gated this tool from
+   * its destructiveHint annotation (see applyDestructiveHintTightener), not the
+   * classifier. Persisted on ToolApprovalPolicy.from_destructive_hint so the
+   * runner attributes the gate to the annotation
+   * (ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN) instead of the
+   * classifier default. Absent/false on classifier and human-pinned entries.
+   */
+  from_destructive_hint?: boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -89,9 +97,12 @@ safe (auto-approve) or sensitive (requires human approval before execution).
 
 Classification rules:
 
-1. READ-ONLY operations → requires_approval: false
-   Examples: search, list, get, query, read, fetch, describe, count
-   These only retrieve data and have no side effects.
+1. READ-ONLY / OBSERVATION operations → requires_approval: false
+   Examples: search, list, get, query, read, fetch, describe, count, view,
+   inspect, status, screenshot, snapshot, and "get state" style tools.
+   These only retrieve or observe data and have no side effects. When a tool
+   name begins with one of these verbs (e.g. get_app_state, list_apps), prefer
+   requires_approval: false unless its description clearly says it mutates.
 
 2. CREATE or MODIFY operations → requires_approval: true
    Examples: create, update, put, set, add, edit, modify, write, post, send
@@ -120,6 +131,19 @@ For tools that do NOT require approval, leave message empty.
 
 Output one classification per tool, maintaining the input order.`;
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Read-only authority
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Read-only auto-approval is owned SOLELY by the trusted LLM classifier above.
+// There is deliberately no deterministic name-based relax here: a tool name is
+// an untrusted, server-supplied signal, and relaxing a gate on it is the unsafe
+// direction (e.g. `get_and_delete_stale_records` leads with `get` yet deletes).
+// A prior name-prefix heuristic was removed for exactly this reason. Annotations
+// are likewise never trusted to relax — the connect workflow uses `destructiveHint`
+// only to TIGHTEN (see applyDestructiveHintTightener). Anything the classifier
+// does not affirmatively clear stays gated (fail closed).
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Core Classification Logic (no Temporal coupling)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -168,7 +192,17 @@ export async function classifyTools(
         batchIdx,
         totalBatches: batches.length,
       });
-      allApprovals.push(...batchResult);
+      // Reconcile against the input batch: a tool the model omitted must fail
+      // closed, never slip through un-gated. Partial output is as dangerous as
+      // an outage for the missing tools.
+      const { reconciled, failedClosedCount } = reconcileBatchClassifications(batch, batchResult);
+      if (failedClosedCount > 0) {
+        console.warn(
+          `[ClassifyToolApprovals] Batch ${batchIdx + 1}/${batches.length} for '${serverName}': ` +
+          `${failedClosedCount} tool(s) missing from classifier output — failing closed (requires_approval=true)`,
+        );
+      }
+      allApprovals.push(...reconciled);
     } catch (err) {
       console.error(
         `[ClassifyToolApprovals] Batch ${batchIdx + 1}/${batches.length} failed ` +
@@ -179,6 +213,10 @@ export async function classifyTools(
     }
   }
 
+  // The LLM classifier is the sole read-only authority: only tools it
+  // affirmatively cleared (requires_approval=false) are auto-approved. Tools it
+  // gated, omitted (reconciled to fail-closed), or that fell back on an outage
+  // all remain gated. No name-based relax runs here by design.
   const approved = allApprovals.filter((a) => a.requires_approval);
 
   console.log(
@@ -214,22 +252,22 @@ async function classifyBatch(params: ClassifyBatchParams): Promise<ToolApprovalR
 
   const maxTokens = Math.max(MIN_MAX_TOKENS, batch.length * MAX_TOKENS_PER_TOOL);
 
-  const resolvedBaseUrl = resolveProxyBaseUrl(proxyEndpoint, "openai");
-  const headers = stigmerToken
-    ? buildProxyHeaders(stigmerToken, { mcpServerId: mcpServerId ?? undefined })
-    : {};
-
-  const llm = new ChatOpenAI({
-    model,
-    temperature: 0,
+  // Provider is inferred from the resolved economy model — for an Anthropic
+  // primary this routes to Claude, not the hardcoded OpenAI path it used to.
+  const { model: llm } = await buildChatModel({
+    modelName: model,
+    proxyEndpoint,
+    stigmerToken: stigmerToken ?? undefined,
+    headerScope: { mcpServerId: mcpServerId ?? undefined },
     maxTokens,
-    configuration: {
-      baseURL: resolvedBaseUrl,
-      defaultHeaders: headers,
-    },
   });
 
-  const structuredLlm = llm.withStructuredOutput(ClassifyToolApprovalsOutputSchema);
+  // Explicit type param: BaseChatModel.withStructuredOutput widens to
+  // Record<string, any>, unlike the concrete SDK overloads, so pin the schema's
+  // output type here.
+  const structuredLlm = llm.withStructuredOutput<ClassifyToolApprovalsOutput>(
+    ClassifyToolApprovalsOutputSchema,
+  );
 
   const toolsPayload = buildToolsPayload(batch);
   const userPrompt =
@@ -264,7 +302,51 @@ async function classifyBatch(params: ClassifyBatchParams): Promise<ToolApprovalR
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Reconcile a batch's LLM classifications against the tools that were actually
+ * sent. The canonical result is built from the INPUT batch, never the raw model
+ * output, so the classifier can never silently disarm a gate by omission:
+ *
+ * - A tool the model classified is kept as-is (its requires_approval + message).
+ * - A tool the model OMITTED fails closed (requires_approval=true) — a missing
+ *   decision is treated exactly like an outage for that one tool.
+ * - A name the model returned that was never in the batch (a hallucinated or
+ *   duplicated entry) is dropped — only real tools earn a policy.
+ */
+export function reconcileBatchClassifications(
+  batch: ToolDescriptor[],
+  llmResults: ToolApprovalResult[],
+): { reconciled: ToolApprovalResult[]; failedClosedCount: number } {
+  const byName = new Map<string, ToolApprovalResult>();
+  for (const r of llmResults) {
+    if (r.tool_name) byName.set(r.tool_name, r);
+  }
+
+  const reconciled: ToolApprovalResult[] = [];
+  let failedClosedCount = 0;
+  for (const tool of batch) {
+    const classified = byName.get(tool.name);
+    if (classified) {
+      reconciled.push(classified);
+      continue;
+    }
+    reconciled.push({
+      tool_name: tool.name,
+      requires_approval: true,
+      message: `Execute ${tool.name}`,
+    });
+    failedClosedCount++;
+  }
+
+  return { reconciled, failedClosedCount };
+}
+
 export function fallbackApprovals(tools: ToolDescriptor[]): ToolApprovalResult[] {
+  // Full fail-closed: when the classifier batch throws, every tool in it is
+  // gated. With no trusted classification we cannot safely auto-approve anything
+  // — a name is an untrusted signal — so the entire batch requires approval
+  // until a reconnect re-classifies it. The accepted tradeoff is that, during a
+  // rare classifier outage, benign read tools briefly prompt for approval.
   return tools.map((tool) => ({
     tool_name: tool.name,
     requires_approval: true,

package/src/activities/discover-mcp-server.ts

@@ -47,6 +47,18 @@ export interface DiscoveredToolResult {
   name: string;
   description: string;
   inputSchema?: Record<string, unknown> | null;
+  // MCP server-supplied behaviour hints. UNTRUSTED — the MCP spec is explicit
+  // that clients must never make tool-use decisions on annotations from
+  // untrusted servers. We therefore consume them only to TIGHTEN gating
+  // (destructiveHint → force-gate), never to relax it. Kept in-memory for the
+  // connect workflow's tightener; deliberately excluded from `toolsFingerprint`
+  // / `toolSignature` so incremental-classification reuse stays content-stable.
+  annotations?: DiscoveredToolAnnotations | null;
+}
+
+export interface DiscoveredToolAnnotations {
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
 }
 
 export interface DiscoveredResourceTemplateResult {
@@ -62,6 +74,11 @@ export interface DiscoverMcpServerOutput {
   previousToolsFingerprint: string;
   previousToolApprovals: ToolApprovalDict[];
   newToolsFingerprint: string;
+  // Full definitions of the tools discovered on the previous connect, read from
+  // status.discovered_capabilities. The connect workflow diffs these against the
+  // freshly discovered tools to reuse prior approval decisions for unchanged
+  // tools and (re)classify only the new or changed ones. Empty on first connect.
+  previousTools: DiscoveredToolResult[];
 }
 
 export interface ToolApprovalDict {
@@ -97,11 +114,12 @@ export function toolsFingerprint(tools: DiscoveredToolResult[]): string {
 interface PreviousState {
   fingerprint: string;
   toolApprovals: ToolApprovalDict[];
+  tools: DiscoveredToolResult[];
 }
 
 export function extractPreviousState(mcpServer: McpServer): PreviousState {
   const status = mcpServer.status;
-  if (!status) return { fingerprint: "", toolApprovals: [] };
+  if (!status) return { fingerprint: "", toolApprovals: [], tools: [] };
 
   const caps = status.discoveredCapabilities;
   const prevTools: DiscoveredToolResult[] = [];
@@ -131,6 +149,7 @@ export function extractPreviousState(mcpServer: McpServer): PreviousState {
   return {
     fingerprint: toolsFingerprint(prevTools),
     toolApprovals,
+    tools: prevTools,
   };
 }
 
@@ -244,6 +263,7 @@ export async function discoverMcpServer(
     previousToolsFingerprint: previousState.fingerprint,
     previousToolApprovals: previousState.toolApprovals,
     newToolsFingerprint: newFp,
+    previousTools: previousState.tools,
   };
 }
 
@@ -323,6 +343,14 @@ async function connectAndDiscover(
           inputSchema: tool.inputSchema
             ? (tool.inputSchema as Record<string, unknown>)
             : null,
+          // Capture only the two hints the tightener uses. Stored verbatim from
+          // the server (untrusted): used to tighten, never to relax.
+          annotations: tool.annotations
+            ? {
+                readOnlyHint: tool.annotations.readOnlyHint,
+                destructiveHint: tool.annotations.destructiveHint,
+              }
+            : null,
         });
       }