@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/src/shared/status.ts

@@ -21,6 +21,7 @@ import {
 import type { StigmerClient } from "../client/stigmer-client.js";
 import {
   offloadOversizedToolOutputs,
+  offloadCandidateChangesToFit,
   enforceStatusSizeLimit,
   STATUS_PAYLOAD_HARD_LIMIT_BYTES,
   type ToolOutputOffloadContext,
@@ -112,6 +113,18 @@ export async function persistStatus(
     } catch (err) {
       console.warn(`[persistStatus] ${executionId}: tool-output offload failed (non-fatal): ${err}`);
     }
+    // File-review ledger: if the status still exceeds the soft cap after per-item
+    // offload, offload the largest still-inline captured bodies to retrievable
+    // refs so those files stay REVIEWABLE (lazily fetched) instead of being
+    // dropped by the backstop below. Guarded on the presence of file-review
+    // events so an ordinary (non-review) turn pays nothing. Non-fatal.
+    if (status.fileReviewEventStream?.events?.length) {
+      try {
+        await offloadCandidateChangesToFit(status, offload);
+      } catch (err) {
+        console.warn(`[persistStatus] ${executionId}: file-review offload-to-fit failed (non-fatal): ${err}`);
+      }
+    }
   }
   if (enforceStatusSizeLimit(status)) {
     console.warn(

package/src/shared/tool-kind.ts

@@ -89,3 +89,36 @@ export function classifyTool(name: string, mcpServerSlug?: string): ToolKind {
   }
   return ToolKind.UNSPECIFIED;
 }
+
+/**
+ * The coarse, cross-taxonomy approval category of a gated built-in tool, or
+ * undefined for tools that are not gated by category (read-only built-ins, MCP
+ * tools, and unknown names).
+ *
+ * FILE_WRITE and FILE_EDIT both collapse to "write" on purpose: the Cursor
+ * preToolUse hook reports every file mutation — create or edit — as `Write`,
+ * while the SDK stream names them `edit`/`write`. The category is therefore the
+ * only tool identity that is stable across the hook and stream taxonomies, which
+ * is exactly what the Cursor approval grant (and the Phase-2 coarse approval
+ * fingerprint) must match on. Built on {@link classifyTool} so this collapse is
+ * defined once.
+ *
+ * This is the single source of truth for the approval category;
+ * execute-cursor/approval-policy.ts re-exports it so the two harnesses cannot
+ * drift.
+ */
+export type ToolApprovalCategory = "write" | "delete" | "shell";
+
+export function toolApprovalCategory(name: string): ToolApprovalCategory | undefined {
+  switch (classifyTool(name)) {
+    case ToolKind.FILE_WRITE:
+    case ToolKind.FILE_EDIT:
+      return "write";
+    case ToolKind.FILE_DELETE:
+      return "delete";
+    case ToolKind.SHELL:
+      return "shell";
+    default:
+      return undefined;
+  }
+}

package/src/shared/tool-row.ts

@@ -0,0 +1,135 @@
+/**
+ * Harness-agnostic helpers for a transcript tool-call row's file-review
+ * presentation.
+ *
+ * When file edits are reviewed as a captured `FileChangeSet` (the apply-then-
+ * review model), each flowed file-edit row STAYS visible at its transcript
+ * position as an observational/audit record — "the agent edited this file,
+ * here" — and is stamped with the change set id it contributed to
+ * ({@link stampFileEditRow}). The ledger remains the single DECISION surface;
+ * the row is never one (the research report's "transcript row references
+ * change_set_id" / "tool-call rows are observational/audit-only for file
+ * tools"). Both harnesses (Cursor deny-gate + deep-agent middleware) stamp rows
+ * the same way, so the operation lives here.
+ *
+ * {@link hideToolCallRow} / {@link isToolCallRowHidden} remain for the OTHER
+ * collapse consumer — a superseded same-turn denial twin — and as the render
+ * shape of legacy (pre-stamping) sessions whose flowed edit rows were hidden.
+ */
+
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { extractFilePath } from "./file-tools.js";
+import { isSecretLikePath } from "./filereview/secret-paths.js";
+import { utcTimestamp } from "./status.js";
+
+/**
+ * Stamp a flowed file-edit row with the change set that captured its turn.
+ * PRESENTATION/AUDIT-ONLY (see `ToolCall.file_change_set_id`): clients badge
+ * the row with the set's review state and anchor the set's decision surface
+ * after the turn's last stamped row. Never a correlation or enforcement key.
+ *
+ * Additive by design — the row keeps its args/result/status so the per-edit
+ * diff the user watched stream stays rendered in place. The captured net diff
+ * on the ledger is the only REVIEWED artifact; the row is a historical record.
+ *
+ * An already-stamped row is left untouched. This is load-bearing, not hygiene:
+ * the turn-boundary pass re-walks the whole transcript, which on a resume
+ * includes the prior turn's seeded rows — without this guard, turn N would
+ * re-stamp turn N-1's rows with its own per-turn change set id (silent
+ * mis-attribution).
+ *
+ * Defensive secret clear (DD-12 D4 belt-and-braces): flowed rows are never
+ * secret in practice — the Cursor hook hard-denies secret-like writes before
+ * they flow — but a write to a TRACKED secret-like path (e.g. a committed
+ * credentials file) is outside the hook's gitignored scope. Such a row keeps
+ * its path (a filename is not itself the secret) and is stripped of content
+ * (`args` body, `result` diff, `args_preview`). Fail-closed: a file row whose
+ * path cannot be determined is stripped rather than trusted.
+ */
+export function stampFileEditRow(tc: ToolCall, changeSetId: string): void {
+  if (tc.fileChangeSetId) return;
+  tc.fileChangeSetId = changeSetId;
+
+  const path = extractFilePath((tc.args ?? {}) as Record<string, unknown>) ?? "";
+  if (isSecretLikePath(path)) {
+    tc.args = path ? { path } : undefined;
+    tc.result = "";
+    tc.argsPreview = "";
+  }
+}
+
+/**
+ * Collapse a tool-call row to the hidden shape the SDK renders as absent: a
+ * SKIPPED row with no approval state, result, error, preview, or args.
+ * Idempotent (re-running yields the same shape).
+ *
+ * `args` is cleared, not just `args_preview`. A hidden row is redundant with the
+ * `file_change_set` (the single review surface), so its content must not linger
+ * anywhere: for a file-mutating tool `args` holds the full write body, which for
+ * a secret-like path would otherwise persist into the transcript / Temporal
+ * history in violation of the never-persist-secret-contents contract (design
+ * doc 12, D4). Dropping it is safe at resume — identity is carried by
+ * `approval_content_digest`, deliberately immune to `args` being absent (the
+ * size-limit elision already drops `args`); no consumer reads a hidden row's
+ * `args`.
+ */
+export function hideToolCallRow(tc: ToolCall): void {
+  tc.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+  tc.requiresApproval = false;
+  tc.approvalRequestedAt = "";
+  tc.approvalMessage = "";
+  tc.error = "";
+  tc.result = "";
+  tc.argsPreview = "";
+  tc.args = undefined;
+  if (!tc.completedAt) tc.completedAt = utcTimestamp();
+}
+
+/**
+ * Whether a tool-call row is already collapsed/hidden (the SDK's absent-row
+ * predicate). Used to keep {@link hideToolCallRow} idempotent across re-persists
+ * and activity retries.
+ */
+export function isToolCallRowHidden(tc: ToolCall): boolean {
+  return (
+    tc.status === ToolCallStatus.TOOL_CALL_SKIPPED &&
+    !tc.requiresApproval &&
+    tc.args === undefined &&
+    !tc.result &&
+    !tc.error
+  );
+}
+
+/**
+ * Collect every tool-call id present in a set of sub-agent executions.
+ *
+ * Used by both harnesses to snapshot, BEFORE a turn's stream, the sub-agent
+ * tool-call ids that already existed — so the turn-boundary stamp can scope
+ * itself to rows CREATED this turn (a tool-call id absent from the snapshot).
+ *
+ * Why tool-call-id novelty is the current-turn signal for sub-agent rows (and
+ * not the `{unstamped}` heuristic the top-level pass uses): a top-level flowed
+ * edit row is guaranteed to be from this turn because prior turns' rows are
+ * either already stamped or hidden. Sub-agent rows have neither shield — before
+ * sub-agent stamping existed, ALL of them are unstamped and never hidden — so a
+ * naive `{unstamped}` walk would mis-attribute a resumed execution's prior
+ * sub-agent rows to the current change set. Keying on tool-call-id novelty is
+ * also correct for a sub-agent that spans invocations (an internal tool gate):
+ * its id pre-exists on resume, but its continuation edit rows carry fresh ids
+ * and stamp with the completing turn's set. It is likewise independent of how
+ * each harness seeds prior sub-agents (deep-agent replaces per-turn and holds
+ * none; Cursor clones them in) — the snapshot reflects whatever is present.
+ */
+export function collectSubAgentToolCallIds(
+  subAgents: readonly SubAgentExecution[],
+): Set<string> {
+  const ids = new Set<string>();
+  for (const sa of subAgents) {
+    for (const msg of sa.messages) {
+      for (const tc of msg.toolCalls) ids.add(tc.id);
+    }
+  }
+  return ids;
+}

package/src/shared/workspace/platform-dir.ts

@@ -18,11 +18,50 @@
 import { join } from "node:path";
 import { mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+
+/** The runner-owned `~/.stigmer` root (overridable via HOME for tests/sandboxes). */
+function getStigmerHome(): string {
+  return process.env.HOME || process.env.USERPROFILE || homedir();
+}
 
 /** Root of a session's runner-owned directory tree (outside the workspace). */
 function getSessionDir(sessionId: string): string {
-  const home = process.env.HOME || process.env.USERPROFILE || homedir();
-  return join(home, ".stigmer", "sessions", sessionId);
+  return join(getStigmerHome(), ".stigmer", "sessions", sessionId);
+}
+
+/**
+ * Compute the WORKSPACE-scoped HITL gate directory — the home for the STABLE
+ * hook script and the per-turn "active turn" pointer.
+ *
+ * Why workspace-scoped, not session-scoped: the Cursor SDK loads the workspace's
+ * `.cursor/hooks.json` (the hook script PATH) ONCE per runner process and caches
+ * it; later per-execution rewrites are ignored. A per-session hook script (with
+ * per-session baked state/ledger paths) therefore gets cached at the FIRST
+ * execution and reused for every later one — so later executions' denials are
+ * recorded to the FIRST session's ledger and the current runner reads its own
+ * empty ledger, silently completing instead of pausing for approval.
+ *
+ * The fix is a single STABLE script per workspace (so the SDK's cached path is
+ * always correct) that resolves the CURRENT turn's state/ledger/runner from an
+ * atomically-updated pointer the script re-reads on every invocation. This dir
+ * holds both. It is keyed by a hash of the absolute workspace path so distinct
+ * workspaces never collide, and lives under `~/.stigmer` (never the repo, per
+ * issue #173). Pure function — performs no I/O.
+ */
+export function getHitlGateDir(workspaceRoot: string): string {
+  const key = createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16);
+  return join(getStigmerHome(), ".stigmer", "hitl-gate", key);
+}
+
+/**
+ * Ensure the workspace-scoped HITL gate directory exists and return its path.
+ * Idempotent — safe across executions, HITL reinvocations, and activity retries.
+ */
+export async function ensureHitlGateDir(workspaceRoot: string): Promise<string> {
+  const dir = getHitlGateDir(workspaceRoot);
+  await mkdir(dir, { recursive: true });
+  return dir;
 }
 
 /**

package/src/workflow-engine/__tests__/golden-execution.test.ts

@@ -385,7 +385,7 @@ describe("Golden Execution — Tier 1d: Advanced Tasks", () => {
     const state = createState();
     state.input = { pr_number: 7, repo: "acme/app", diff: "--- a/main.ts" };
 
-    const mockCallAgent = vi.fn(async () => ({
+    const mockCallAgent = vi.fn<TaskExecutionContext["callAgent"]>(async () => ({
       structured: { severity: "low", category: "style", customer_impact: false },
       final_text: "LGTM",
       agent_execution_id: "aex-verify",
@@ -434,7 +434,7 @@ describe("Golden Execution — Tier 1d: Advanced Tasks", () => {
     const model = loadWorkflowFromYaml(crossOrgYaml);
     const state = createState();
 
-    const mockCallAgent = vi.fn(async () => ({
+    const mockCallAgent = vi.fn<TaskExecutionContext["callAgent"]>(async () => ({
       final_text: "done",
     }));
     const ctx = makeCtx({ callAgent: mockCallAgent });
@@ -678,9 +678,11 @@ describe("Golden Execution — Structured Output Pipeline", () => {
     await executeDoTasks(model.do, null, state, model, evaluateExpressionBatch, ctx);
 
     expect(mockCallAgent).toHaveBeenCalledOnce();
-    expect(state.context.analyze.dau).toBe(7175);
-    expect(state.context.analyze.executive_summary).toBe("DAU stable at 7175");
-    expect(state.context.analyze.cohorts).toHaveLength(2);
+    // `$context` is dynamic (typed `unknown` in production); narrow to the shape this golden produces.
+    const context = state.context as { analyze: { dau: number; executive_summary: string; cohorts: unknown[] } };
+    expect(context.analyze.dau).toBe(7175);
+    expect(context.analyze.executive_summary).toBe("DAU stable at 7175");
+    expect(context.analyze.cohorts).toHaveLength(2);
     expect(state.data.report_dau).toBe(7175);
     expect(state.data.cohort_count).toBe(2);
     expect(state.data.first_cohort).toBe("D1 New Players");
@@ -838,8 +840,10 @@ describe("Golden Execution — Structured Output Pipeline", () => {
 
     await executeDoTasks(model.do, null, state, model, evaluateExpressionBatch, ctx);
 
-    expect(state.context.analyze.dau).toBe(7175);
-    expect(state.context.analyze.executive_summary).toBe("DAU stable at 7175");
+    // `$context` is dynamic (typed `unknown` in production); narrow to the shape this golden produces.
+    const context = state.context as { analyze: { dau: number; executive_summary: string } };
+    expect(context.analyze.dau).toBe(7175);
+    expect(context.analyze.executive_summary).toBe("DAU stable at 7175");
     expect(state.data.report_dau).toBe(7175);
     expect(state.data.summary).toBe("DAU stable at 7175");
   });
@@ -979,9 +983,11 @@ describe("Golden Execution — Structured Output Pipeline", () => {
 
     await executeDoTasks(model.do, null, state, model, evaluateExpressionBatch, ctx);
 
-    expect(state.context.analyze.dau).toBe(7175);
-    expect(state.context.analyze.cohorts).toHaveLength(2);
-    expect(state.context.analyze.anomalies).toHaveLength(1);
+    // `$context` is dynamic (typed `unknown` in production); narrow to the shape this golden produces.
+    const context = state.context as { analyze: { dau: number; cohorts: unknown[]; anomalies: unknown[] } };
+    expect(context.analyze.dau).toBe(7175);
+    expect(context.analyze.cohorts).toHaveLength(2);
+    expect(context.analyze.anomalies).toHaveLength(1);
     expect(state.data.summary).toBe("Garden Design Makeover DAU remains stable at 7,175");
     expect(state.data.anomaly_count).toBe(1);
   });
@@ -991,7 +997,7 @@ describe("Golden Execution — Structured Output Pipeline", () => {
     const state = createState();
     state.env = { NOTIFICATION_DATE: "2026-05-26" };
 
-    const mockCallAgent = vi.fn(async () => ({
+    const mockCallAgent = vi.fn<TaskExecutionContext["callAgent"]>(async () => ({
       structured: {
         executive_summary: "Garden Design Makeover DAU stable at 7,185",
         dau: 7185,
@@ -1019,13 +1025,22 @@ describe("Golden Execution — Structured Output Pipeline", () => {
     expect(mockCallAgent).toHaveBeenCalledOnce();
     const [config, env, metadata] = mockCallAgent.mock.calls[0];
 
-    // Schema must survive expression resolution
-    expect(config.output).toBeDefined();
+    // Schema must survive expression resolution. `output.schema` is an arbitrary
+    // JSON schema (typed `Record<string, unknown>` in production); narrow to the
+    // concrete shape this golden asserts against.
+    if (!config.output) throw new Error("expected an output contract on the agent call");
+    const schema = config.output.schema as {
+      required: string[];
+      properties: {
+        cohorts: { items: { required: string[] } };
+        anomalies: { items: { properties: { severity: { enum: string[] } } } };
+      };
+    };
     expect(config.output.schema).toBeDefined();
-    expect(config.output.schema.required).toEqual(["executive_summary", "cohorts", "anomalies"]);
-    expect(config.output.schema.properties.cohorts.items.required)
+    expect(schema.required).toEqual(["executive_summary", "cohorts", "anomalies"]);
+    expect(schema.properties.cohorts.items.required)
       .toEqual(["name", "size", "action_needed"]);
-    expect(config.output.schema.properties.anomalies.items.properties.severity.enum)
+    expect(schema.properties.anomalies.items.properties.severity.enum)
       .toEqual(["warning", "critical"]);
     expect(config.output.on_invalid).toBe("ON_INVALID_FAIL");
 
@@ -1040,8 +1055,10 @@ describe("Golden Execution — Structured Output Pipeline", () => {
     expect(metadata.taskName).toBe("analyze_player_data");
 
     // Structured output exported to context and consumed downstream
-    expect(state.context.analyze_player_data.dau).toBe(7185);
-    expect(state.context.analyze_player_data.executive_summary).toContain("7,185");
+    // `$context` is dynamic (typed `unknown` in production); narrow to the shape this golden produces.
+    const context = state.context as { analyze_player_data: { dau: number; executive_summary: string } };
+    expect(context.analyze_player_data.dau).toBe(7185);
+    expect(context.analyze_player_data.executive_summary).toContain("7,185");
     expect(state.data.final_dau).toBe(7185);
     expect(state.data.anomaly_count).toBe(1);
   });

package/src/workflow-engine/__tests__/tasks/try.test.ts

@@ -554,7 +554,7 @@ describe("executeTryTask — retryContext propagation", () => {
 
     let capturedRetryContext: unknown = undefined;
     const spyEmitEvents = vi.fn(async function (this: TaskExecutionContext, events: WorkflowEventDescriptor[]) {
-      capturedRetryContext = (this as Record<string, unknown>)?.retryContext;
+      capturedRetryContext = this.retryContext;
     });
 
     let callCount = 0;