@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/src/activities/execute-cursor/command-provenance.ts

@@ -0,0 +1,168 @@
+/**
+ * Approved-command turn provenance (DD-28): the runner-owned qualification for
+ * the auto-keep policy.
+ *
+ * A turn whose ONLY mutation source was shell commands the human had already
+ * authorized should not re-gate its file effects at the turn-boundary review —
+ * the user consented to the command, and the command's file effects are the
+ * consented outcome. The server cannot derive this itself (tool calls carry no
+ * turn marker), so the runner — the only component that owns turn scoping —
+ * derives the facts here and attaches them to the CANDIDATE_CAPTURED event as
+ * {@link TurnCommandProvenance}.
+ *
+ * TRUST BOUNDARY. This module asserts turn FACTS (which tools ran this turn),
+ * the same trust level as the captured bytes themselves. It never asserts
+ * CONSENT: `consentToolCallIds` merely POINT at transcript rows whose
+ * `approval_action` was authored by the server's SubmitApproval (and is
+ * preserved against runner writes) — the backend re-verifies every claimed row
+ * against that server-owned record before authoring the policy decision, so a
+ * runner cannot mint authorization it was never given.
+ *
+ * FAIL-CLOSED. Every uncertainty disqualifies (returns undefined → the set
+ * reviews manually, exactly as before DD-28): a file-tool call, an MCP tool, a
+ * sub-agent delegation, an unrecognized tool name, or an executed shell command
+ * with no provable consent source. Being conservative here costs only an extra
+ * review; being permissive would silently waive one.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { TurnCommandProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { TurnCommandProvenance } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { ApprovalAction, ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool, toolApprovalCategory } from "../../shared/tool-kind.js";
+import { isToolCallRowHidden } from "../../shared/tool-row.js";
+import { toolCallIdentityToken } from "./message-translator.js";
+
+/**
+ * Tool kinds that can never mutate the workspace: their presence in a turn is
+ * irrelevant to change-set provenance. Everything OUTSIDE this set is either a
+ * consent-mapped shell command or a disqualifier — never silently ignored.
+ */
+const NON_MUTATING_KINDS: ReadonlySet<ToolKind> = new Set([
+  ToolKind.FILE_READ,
+  ToolKind.SEARCH,
+  ToolKind.LIST,
+  ToolKind.FETCH,
+  ToolKind.WEB_SEARCH,
+  ToolKind.THINK,
+  ToolKind.TODO,
+]);
+
+export interface CommandProvenanceInputs {
+  /**
+   * The full transcript at capture time. Turn scoping is positional: messages
+   * from index {@link turnStartIndex} onward were produced by THIS turn's
+   * stream; everything before was seeded from prior turns. Lease consent rows
+   * (APPROVE_ALL) are looked up across the WHOLE transcript — a lease is
+   * run-lifetime, its granting row usually lives in a prior turn.
+   */
+  readonly messages: readonly AgentMessage[];
+  /** Index of the first message created by this turn's stream. */
+  readonly turnStartIndex: number;
+  /**
+   * Identity tokens the hook denied THIS turn (the denial ledger). A denied
+   * shell row never executed — it is this turn's pending gate, not a mutation
+   * source — so it neither needs consent nor disqualifies.
+   */
+  readonly deniedTokens: ReadonlySet<string>;
+  /**
+   * Grant token → the tool-call id of the approval row that minted the grant
+   * (the row carrying the server-authored approval_action). An executed shell
+   * command whose identity token is a key here was authorized by that
+   * per-command approval.
+   */
+  readonly grantTokenToConsentId: ReadonlyMap<string, string>;
+  /** True when the pre-armed spec.auto_approve_all bypassed the gate. */
+  readonly globalBypass: boolean;
+}
+
+/**
+ * Derive the {@link TurnCommandProvenance} for the turn, or undefined when the
+ * turn does not qualify (any non-shell mutation-capable call, any unknown tool,
+ * any executed command without a provable consent source, or no executed
+ * consented command at all).
+ */
+export function deriveTurnCommandProvenance(
+  inputs: CommandProvenanceInputs,
+): TurnCommandProvenance | undefined {
+  const { messages, turnStartIndex, deniedTokens, grantTokenToConsentId, globalBypass } = inputs;
+
+  const consentIds = new Set<string>();
+  let authorizedByAutoApproveAll = false;
+  let executedCommandCount = 0;
+
+  for (let i = turnStartIndex; i < messages.length; i++) {
+    for (const tc of messages[i].toolCalls) {
+      // A hidden row is a collapsed twin/reaction — it never executed.
+      if (isToolCallRowHidden(tc)) continue;
+
+      const kind = classifyTool(tc.name, tc.mcpServerSlug);
+      if (NON_MUTATING_KINDS.has(kind)) continue;
+
+      if (kind !== ToolKind.SHELL) {
+        // A file tool (mixed turn), a sub-agent (unattributable mutations), an
+        // MCP tool (opaque side effects), or an unrecognized name — the turn's
+        // mutations cannot be attributed to consented commands. Fail closed.
+        return undefined;
+      }
+
+      const token = toolCallIdentityToken(tc);
+      if (deniedTokens.has(token)) {
+        // This turn's pending gate — denied by the hook, never executed.
+        continue;
+      }
+      executedCommandCount++;
+
+      const consentId = grantTokenToConsentId.get(token);
+      if (consentId) {
+        consentIds.add(consentId);
+        continue;
+      }
+      const leaseConsentId = findLeaseConsentId(messages, tc.name);
+      if (leaseConsentId) {
+        consentIds.add(leaseConsentId);
+        continue;
+      }
+      if (globalBypass) {
+        authorizedByAutoApproveAll = true;
+        continue;
+      }
+      // An executed shell command with no grant, no lease, and no bypass should
+      // be impossible (the hook gates every un-consented shell); if it ever
+      // happens, the honest answer is a manual review, not a waived one.
+      return undefined;
+    }
+  }
+
+  // A turn that executed no consented command has nothing to attribute the
+  // change set to — whatever changed came from somewhere else. Manual review.
+  if (executedCommandCount === 0) return undefined;
+
+  return create(TurnCommandProvenanceSchema, {
+    consentToolCallIds: [...consentIds],
+    authorizedByAutoApproveAll,
+  });
+}
+
+/**
+ * Find the transcript row whose APPROVE_ALL authored the run-lifetime lease
+ * covering `toolName`'s category — the consent row a lease-executed command
+ * cites. Searched across the whole transcript (a lease usually originates in a
+ * prior turn); the first (earliest) APPROVE_ALL of the category is the lease's
+ * origin. Returns undefined when no lease row exists for the category.
+ */
+function findLeaseConsentId(
+  messages: readonly AgentMessage[],
+  toolName: string,
+): string | undefined {
+  const category = toolApprovalCategory(toolName);
+  if (!category) return undefined;
+  for (const msg of messages) {
+    for (const tc of msg.toolCalls) {
+      if (tc.approvalAction !== ApprovalAction.APPROVE_ALL) continue;
+      if (toolApprovalCategory(tc.name) === category) return tc.id;
+    }
+  }
+  return undefined;
+}

package/src/activities/execute-cursor/exact-apply.ts

@@ -0,0 +1,253 @@
+/**
+ * Resume-time exact-apply for approved whole-file writes (Cursor deny-only HITL).
+ *
+ * THE GUARANTEE THIS RESTORES
+ * ---------------------------
+ * A user must get "what you approve is what gets applied" — the contract the
+ * native LangGraph harness and Cursor's own IDE honor by pausing at the exact
+ * tool call and applying its exact args on approval. The Cursor deny-only
+ * harness cannot pause: it denies the tool, grants the RESOURCE (`write\n<path>`),
+ * and reinvokes the model, which REGENERATES content from scratch. So the bytes
+ * that land can differ from the bytes the gate showed (observed in production: a
+ * gate previewing one edit, an applied file carrying more).
+ *
+ * The fix turns an approved WHOLE-FILE write into a runner-executed action: the
+ * runner writes the EXACT approved bytes itself, marks the tool COMPLETED, and —
+ * crucially — issues NO resource grant for it. Any FURTHER write the model makes
+ * to that file on reinvocation is therefore re-gated, so the user sees and
+ * approves every change. This module owns the apply AND the grant-exclusion
+ * derivation ({@link excludeAppliedFromGrants}, the "issues NO grant" half); the
+ * caller wires the resulting grants and the prompt split (so the model is told
+ * the write is already applied and does not redo it).
+ *
+ * SCOPE — whole-file writes only. A hunk edit (`old_string`/`new_string`) is left
+ * on the grant + reinvocation path: applying a hunk would require locating the
+ * fragment in the file, which would make the runner a second source of truth for
+ * the edit result. Shell/MCP grants are already command-/name-specific, so their
+ * approved==applied property is already tight.
+ *
+ * SOURCE OF TRUTH — the approved whole-file bytes and target path are read from
+ * the gated tool call's `args` (the authoritative proposed content the deny-gate
+ * stamped from the hook input; see execute-cursor/message-translator.ts
+ * `applyGateInput`). This is the single copy — there is no separate captured
+ * `file_changes` mirror — so "what was shown == what is applied" holds by
+ * construction. (Phase 5 Slice 4 removed the redundant `ToolCall.file_changes`
+ * copy; `args` was always its source.)
+ *
+ * SAFETY — exact-apply writes ONLY a fully-resolved body. It never writes a
+ * truncated preview or the elision marker (which would silently corrupt the
+ * file); an unresolvable body or any write failure degrades to the existing
+ * grant + reinvocation path. Corruption is never an option — degradation to the
+ * prior behavior is.
+ *
+ * TESTING — the apply + grant-exclusion + re-gating composition is proven
+ * end-to-end (real workspace backend + the real deny-oracle hook) in
+ * `__tests__/deny-gate-exact-apply.test.ts`. That deterministic runner test is
+ * the achievable substitute for a pure-Go offline e2e, which is structurally
+ * infeasible (there is no offline Cursor agent driver — see DD-23).
+ */
+
+import { isAbsolute, relative, resolve } from "node:path";
+import {
+  ApprovalAction,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type {
+  AgentMessage,
+  ToolCall,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import { ELISION_MARKER } from "../../shared/status-offload.js";
+import { extractFilePath, extractWriteContent } from "../../shared/file-tools.js";
+import { resolveWorkspacePath } from "../../shared/file-change.js";
+import type { WorkspaceBackend } from "../../shared/workspace/types.js";
+import { utcTimestamp } from "../../shared/status.js";
+
+/** Options for {@link applyApprovedWholeFileWrites}. */
+export interface ExactApplyOptions {
+  /** The (seeded) transcript whose approved tool calls are applied in place. */
+  readonly messages: AgentMessage[];
+  /** Workspace the files live in (local FS for OSS, sandbox in cloud). */
+  readonly workspaceBackend: WorkspaceBackend;
+  /** Configured workspace roots; a write is refused outside all of them. */
+  readonly workspaceDirs: readonly string[];
+  /** For structured logs. */
+  readonly executionId: string;
+}
+
+/**
+ * Apply every APPROVED whole-file write in `messages` to disk with its EXACT
+ * approved bytes, marking each applied tool call COMPLETED in place.
+ *
+ * Returns the set of tool-call ids that were exact-applied, so the caller can
+ * (a) exclude their resources from the approval grants — the key to re-gating a
+ * later write — and (b) describe them as "already applied" in the reinvocation
+ * prompt rather than asking the model to redo them.
+ *
+ * Idempotent: a call already COMPLETED (a Temporal activity retry re-runs this
+ * phase) is skipped, never written twice. Every uncertain case (no resolvable
+ * body, out-of-workspace target, write failure) is SKIPPED, leaving the call
+ * WAITING_APPROVAL so the existing grant + reinvocation path handles it — the
+ * conservative fallback that can never corrupt a file.
+ */
+export async function applyApprovedWholeFileWrites(
+  opts: ExactApplyOptions,
+): Promise<Set<string>> {
+  const applied = new Set<string>();
+
+  for (const msg of opts.messages) {
+    for (const tc of msg.toolCalls) {
+      if (!isApprovedWholeFileWrite(tc)) continue;
+
+      const args = argsRecord(tc);
+      const rawPath = extractFilePath(args);
+      if (!rawPath) {
+        // A whole-file write always carries a path arg; a missing one is
+        // unexpected — do not guess a path, fall back.
+        logSkip(opts.executionId, tc, "no file path in tool args");
+        continue;
+      }
+      // Resolve against the workspace root with the same convention the gate used
+      // (Cursor: real paths, not virtual), so the applied path matches the one the
+      // user approved.
+      const { absolutePath: target } = resolveWorkspacePath(
+        rawPath,
+        opts.workspaceBackend.rootDir,
+        /* virtualRoot */ false,
+      );
+      if (!isWithinWorkspace(target, opts.workspaceDirs)) {
+        logSkip(opts.executionId, tc, `target outside workspace: ${target}`);
+        continue;
+      }
+
+      const content = resolveApprovedWholeFileContent(tc);
+      if (content === null) {
+        logSkip(opts.executionId, tc, "exact approved bytes unresolvable");
+        continue;
+      }
+
+      try {
+        await opts.workspaceBackend.writeFile(target, content);
+      } catch (err) {
+        logSkip(
+          opts.executionId,
+          tc,
+          `write failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        continue;
+      }
+
+      // The tool is now genuinely done: the runner applied exactly what the user
+      // approved (the same `args` bytes the gate showed). Mark COMPLETED in place
+      // (same id — the backend's append-only-at-identity guard accepts a status
+      // change). The approval_action is preserved as the audit trail; the status
+      // flip removes it from the server's pending_approvals projection (which
+      // keys on WAITING_APPROVAL).
+      tc.status = ToolCallStatus.TOOL_CALL_COMPLETED;
+      if (!tc.completedAt) tc.completedAt = utcTimestamp();
+      tc.error = "";
+      applied.add(tc.id);
+      console.log(
+        `ExecuteCursor exact-apply: wrote approved bytes to ${target} ` +
+          `(tool=${tc.id}); no resource grant issued, so a further change ` +
+          `re-gates. execution=${opts.executionId}`,
+      );
+    }
+  }
+
+  return applied;
+}
+
+/**
+ * The adjudicated approvals MINUS the ones the runner already exact-applied — the
+ * set the caller turns into resource grants for the resumed agent.
+ *
+ * This is the "issues NO grant for an applied write" half of the guarantee: an
+ * exact-applied whole-file write is intentionally NOT granted, so if the
+ * reinvoked model writes to that same file again it is re-gated and the user
+ * reviews the new change (the deny-gate's "what you approve is what gets applied"
+ * property). Non-applied approvals (hunk edits, shell, MCP, and every reject /
+ * skip) pass through unchanged — they still need their grant to flow on resume.
+ *
+ * Pure and order-independent. Load-bearing because the caller computes the
+ * adjudicated set ONCE (before {@link applyApprovedWholeFileWrites} flips the
+ * applied calls to COMPLETED) and never re-derives it, so this exclusion is the
+ * only thing that keeps an applied write out of the grants.
+ */
+export function excludeAppliedFromGrants(
+  adjudicatedApprovals: readonly PendingApproval[],
+  appliedToolCallIds: ReadonlySet<string>,
+): PendingApproval[] {
+  return adjudicatedApprovals.filter((pa) => !appliedToolCallIds.has(pa.toolCallId));
+}
+
+/**
+ * The exact approved bytes for a whole-file write, or `null` when they cannot be
+ * recovered (in which case the caller must fall back, never write).
+ *
+ * The bytes come from the gated call's `args` whole-file content — the single
+ * authoritative copy of the proposed body (the deny-gate stamped it from the
+ * hook input; see {@link isApprovedWholeFileWrite}). `args` is never offloaded to
+ * a ref (only dropped wholesale by the aggregate size backstop), so when present
+ * it is intact.
+ *
+ * It NEVER returns the elision marker: that is a lossy stand-in and writing it
+ * would corrupt the file. An `args` body equal to the marker is treated as
+ * unresolved, and the caller degrades to grant + reinvocation.
+ */
+export function resolveApprovedWholeFileContent(tc: ToolCall): string | null {
+  const content = extractWriteContent(argsRecord(tc));
+  if (content !== null && content !== ELISION_MARKER) return content;
+  return null;
+}
+
+/**
+ * Whether `tc` is an approved, still-pending WHOLE-FILE write eligible for
+ * exact-apply. APPROVE and APPROVE_ALL both approve the clicked tool (the latter
+ * also leases the class, handled separately by the caller). A SKIP/REJECT, an
+ * edit-family call (`old_string`/`new_string`, which carries no whole-file body),
+ * and an already-applied (COMPLETED) call are all excluded.
+ *
+ * The whole-file predicate is `extractWriteContent(args) !== null` — the exact
+ * condition the removed field-22 capture used to classify a change WHOLE_FILE
+ * (a whole-file body present) vs HUNK_ONLY (an edit fragment). Reading it from
+ * `args` keeps eligibility on the single source of truth.
+ */
+function isApprovedWholeFileWrite(tc: ToolCall): boolean {
+  if (tc.status !== ToolCallStatus.TOOL_CALL_WAITING_APPROVAL) return false;
+  if (
+    tc.approvalAction !== ApprovalAction.APPROVE &&
+    tc.approvalAction !== ApprovalAction.APPROVE_ALL
+  ) {
+    return false;
+  }
+  return extractWriteContent(argsRecord(tc)) !== null;
+}
+
+/** The gated tool call's structured args as a plain record (empty when absent). */
+function argsRecord(tc: ToolCall): Record<string, unknown> {
+  return tc.args && typeof tc.args === "object"
+    ? (tc.args as Record<string, unknown>)
+    : {};
+}
+
+/** Whether `absTarget` resolves inside one of the configured workspace roots. */
+function isWithinWorkspace(
+  absTarget: string,
+  workspaceDirs: readonly string[],
+): boolean {
+  const target = resolve(absTarget);
+  return workspaceDirs.some((dir) => {
+    const root = resolve(dir);
+    if (target === root) return true;
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+  });
+}
+
+function logSkip(executionId: string, tc: ToolCall, reason: string): void {
+  console.log(
+    `ExecuteCursor exact-apply skipped (falling back to grant+reinvocation): ` +
+      `tool=${tc.id} reason="${reason}" execution=${executionId}`,
+  );
+}