@stigmer/sdk 3.0.9-dev.20260616060535 → 3.1.1

package/src/execution/__tests__/approval-provenance.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import {
+  ApprovalPolicySource,
+  describeApprovalPolicySource,
+  isInformativePolicySource,
+} from "../approval-provenance";
+
+describe("describeApprovalPolicySource", () => {
+  it("maps each known source to a stable human phrase", () => {
+    expect(describeApprovalPolicySource(ApprovalPolicySource.CLASSIFIER_DEFAULT)).toBe(
+      "required by the tool's default policy",
+    );
+    expect(describeApprovalPolicySource(ApprovalPolicySource.BUILTIN_CATEGORY)).toBe(
+      "required by built-in tool policy",
+    );
+    expect(describeApprovalPolicySource(ApprovalPolicySource.AGENT_OVERRIDE)).toBe(
+      "required by agent override",
+    );
+    expect(
+      describeApprovalPolicySource(ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN),
+    ).toBe("required: marked destructive by the server");
+  });
+
+  it("returns null for UNSPECIFIED (legacy / ungated)", () => {
+    expect(describeApprovalPolicySource(ApprovalPolicySource.UNSPECIFIED)).toBeNull();
+  });
+});
+
+describe("isInformativePolicySource", () => {
+  it("suppresses the everyday default gating reasons", () => {
+    // These add nothing beyond "this tool needs approval" — noise at the gate.
+    expect(isInformativePolicySource(ApprovalPolicySource.CLASSIFIER_DEFAULT)).toBe(false);
+    expect(isInformativePolicySource(ApprovalPolicySource.BUILTIN_CATEGORY)).toBe(false);
+    expect(isInformativePolicySource(ApprovalPolicySource.UNSPECIFIED)).toBe(false);
+  });
+
+  it("surfaces reasons that change the user's understanding of the gate", () => {
+    expect(isInformativePolicySource(ApprovalPolicySource.PINNED_OVERRIDE)).toBe(true);
+    expect(isInformativePolicySource(ApprovalPolicySource.AGENT_OVERRIDE)).toBe(true);
+    expect(
+      isInformativePolicySource(ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN),
+    ).toBe(true);
+    expect(isInformativePolicySource(ApprovalPolicySource.AUTO_APPROVE_ALL)).toBe(true);
+    expect(isInformativePolicySource(ApprovalPolicySource.APPROVAL_LEASE)).toBe(true);
+  });
+
+  it("only surfaces a reason that also has a phrase to show", () => {
+    // The card renders `isInformative(source) && describe(source) != null`; the
+    // two must never disagree for a surfaced source.
+    for (const source of [
+      ApprovalPolicySource.PINNED_OVERRIDE,
+      ApprovalPolicySource.AGENT_OVERRIDE,
+      ApprovalPolicySource.ANNOTATION_DESTRUCTIVE_TIGHTEN,
+      ApprovalPolicySource.AUTO_APPROVE_ALL,
+      ApprovalPolicySource.APPROVAL_LEASE,
+    ]) {
+      expect(describeApprovalPolicySource(source)).not.toBeNull();
+    }
+  });
+});

package/src/execution/__tests__/file-review-fold.corpus.test.ts

@@ -0,0 +1,127 @@
+// Cross-edition parity lock for the file-review projection.
+//
+// The Go (`FileChangeSetProjector` / project.go) and Java (`FileChangeSetProjector`)
+// projectors replay the shared corpus at apis/testdata/hitl/file-review/*.json.
+// This test replays the SAME corpus against the TypeScript fold, so a drift
+// between the SDK and either backend fails here rather than shipping.
+//
+// The corpus `expected` is the server (actionable) projection, which is empty
+// for a terminal execution. The SDK's display fold intentionally has no terminal
+// gate, so to reproduce the server contract exactly this test applies the phase
+// gate the accessor's callers apply: isTerminalPhase(phase) ? [] : fold(stream).
+// That both proves parity for non-terminal vectors AND pins the terminal-empty
+// vector — the one place the SDK deliberately differs is covered by the accessor
+// test in file-review-fold.test.ts, not here.
+
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { describe, it, expect } from "vitest";
+import { create, fromJson, type JsonValue } from "@bufbuild/protobuf";
+import {
+  FileReviewEventSchema,
+  FileReviewEventStreamSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  ExecutionPhase,
+  FileChangeSetStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { foldFileReviewEventStream } from "../file-review-fold";
+import { isTerminalPhase } from "../execution-phases";
+
+const here = dirname(fileURLToPath(import.meta.url));
+// sdk/typescript/src/execution/__tests__ -> repo root is five levels up.
+const corpusDir = resolve(here, "../../../../../apis/testdata/hitl/file-review");
+
+/** The `expected` summary shape each vector pins (see the corpus README). */
+interface ExpectedSet {
+  id: string;
+  status: string; // full proto enum name, e.g. FILE_CHANGE_SET_STATUS_DECIDED
+  change_ids?: string[];
+  decision_count?: number;
+  aggregate_digest?: string;
+  has_approved_snapshot?: boolean;
+}
+
+interface Vector {
+  name: string;
+  description?: string;
+  execution_id: string;
+  phase: string;
+  events: JsonValue[];
+  expected: ExpectedSet[];
+}
+
+function statusFromName(name: string): FileChangeSetStatus {
+  const key = name.replace(
+    /^FILE_CHANGE_SET_STATUS_/,
+    "",
+  ) as keyof typeof FileChangeSetStatus;
+  const value = FileChangeSetStatus[key];
+  if (typeof value !== "number") {
+    throw new Error(`unknown FileChangeSetStatus in corpus: ${name}`);
+  }
+  return value;
+}
+
+function phaseFromName(name: string): ExecutionPhase {
+  const value = ExecutionPhase[name as keyof typeof ExecutionPhase];
+  if (typeof value !== "number") {
+    throw new Error(`unknown ExecutionPhase in corpus: ${name}`);
+  }
+  return value;
+}
+
+const vectorFiles = readdirSync(corpusDir).filter(
+  (f) => f.endsWith(".json") && f !== "schema.json",
+);
+
+describe("file-review fold — cross-edition corpus parity", () => {
+  it("finds the corpus vectors", () => {
+    expect(vectorFiles.length).toBeGreaterThan(0);
+  });
+
+  for (const file of vectorFiles) {
+    const vector = JSON.parse(
+      readFileSync(resolve(corpusDir, file), "utf8"),
+    ) as Vector;
+
+    it(`${file}: ${vector.name}`, () => {
+      // Decode each event with the generated schema so a malformed fixture fails
+      // loudly (matching the backend corpus drivers), then build the stream.
+      const events = vector.events.map((ev) =>
+        fromJson(FileReviewEventSchema, ev),
+      );
+      const stream = create(FileReviewEventStreamSchema, {
+        executionId: vector.execution_id,
+        events,
+      });
+
+      const phase = phaseFromName(vector.phase);
+      // Reproduce the server's actionable projection: phase-gated fold.
+      const projected = isTerminalPhase(phase)
+        ? []
+        : foldFileReviewEventStream(stream);
+
+      const actual = projected.map((set) => ({
+        id: set.id,
+        status: set.status,
+        change_ids: set.changes.map((c) => c.id),
+        decision_count: set.decisions.length,
+        aggregate_digest: set.aggregateDigest,
+        has_approved_snapshot: set.approvedSnapshot !== undefined,
+      }));
+
+      const expected = vector.expected.map((e) => ({
+        id: e.id,
+        status: statusFromName(e.status),
+        change_ids: e.change_ids ?? [],
+        decision_count: e.decision_count ?? 0,
+        aggregate_digest: e.aggregate_digest ?? "",
+        has_approved_snapshot: e.has_approved_snapshot ?? false,
+      }));
+
+      expect(actual).toEqual(expected);
+    });
+  }
+});

package/src/execution/__tests__/file-review-fold.test.ts

@@ -0,0 +1,281 @@
+// Unit tests for the file-review fold and its display read-seam. The
+// cross-edition parity with the Go/Java projectors is locked separately by
+// file-review-fold.corpus.test.ts; these cover the TS-specific edges and the
+// deliberate terminal divergence of displayFileChangeSets.
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  FileChangeSetSchema,
+  CapturedFileChangeSchema,
+  FileDecisionSchema,
+  FileReviewEventSchema,
+  FileReviewEventStreamSchema,
+  FileReviewBaselineCapturedSchema,
+  FileReviewCandidateCapturedSchema,
+  FileReviewReconciledSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  FileChangeKind,
+  FileChangeSetStatus,
+  FileDecisionAction,
+  FileDecisionScope,
+  FileReviewEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { CapturedFileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  displayFileChangeSets,
+  foldFileReviewEventStream,
+} from "../file-review-fold";
+
+// ---------------------------------------------------------------------------
+// Event builders (keep the tests readable)
+// ---------------------------------------------------------------------------
+
+function change(id: string, path = `src/${id}.ts`): CapturedFileChange {
+  return create(CapturedFileChangeSchema, {
+    id,
+    pathAfter: path,
+    kind: FileChangeKind.MODIFY,
+    diffComplete: true,
+  });
+}
+
+function baseline(changeSetId: string) {
+  return create(FileReviewEventSchema, {
+    changeSetId,
+    eventType: FileReviewEventType.BASELINE_CAPTURED,
+    payload: {
+      case: "baselineCaptured",
+      value: create(FileReviewBaselineCapturedSchema, {
+        changeSetId,
+        turnId: "t1",
+        harnessId: "deep-agent",
+      }),
+    },
+  });
+}
+
+function candidate(changeSetId: string, changes: CapturedFileChange[], agg = "agg") {
+  return create(FileReviewEventSchema, {
+    changeSetId,
+    eventType: FileReviewEventType.CANDIDATE_CAPTURED,
+    payload: {
+      case: "candidateCaptured",
+      value: create(FileReviewCandidateCapturedSchema, {
+        changeSetId,
+        changes,
+        aggregateDigest: agg,
+      }),
+    },
+  });
+}
+
+function fileDecision(
+  changeSetId: string,
+  fileChangeId: string,
+  action = FileDecisionAction.APPROVE,
+) {
+  return create(FileReviewEventSchema, {
+    changeSetId,
+    eventType: FileReviewEventType.FILE_DECIDED,
+    payload: {
+      case: "fileDecided",
+      value: create(FileDecisionSchema, {
+        changeSetId,
+        fileChangeId,
+        scope: FileDecisionScope.FILE,
+        action,
+      }),
+    },
+  });
+}
+
+function changeSetDecision(changeSetId: string) {
+  return create(FileReviewEventSchema, {
+    changeSetId,
+    eventType: FileReviewEventType.FILE_DECIDED,
+    payload: {
+      case: "fileDecided",
+      value: create(FileDecisionSchema, {
+        changeSetId,
+        scope: FileDecisionScope.CHANGE_SET,
+        action: FileDecisionAction.APPROVE,
+      }),
+    },
+  });
+}
+
+function reconciled(changeSetId: string) {
+  return create(FileReviewEventSchema, {
+    changeSetId,
+    eventType: FileReviewEventType.RECONCILED,
+    payload: {
+      case: "reconciled",
+      value: create(FileReviewReconciledSchema, { changeSetId }),
+    },
+  });
+}
+
+function failed(changeSetId: string) {
+  return create(FileReviewEventSchema, {
+    changeSetId,
+    eventType: FileReviewEventType.FAILED,
+    payload: { case: undefined },
+  });
+}
+
+function stream(...events: ReturnType<typeof baseline>[]) {
+  return create(FileReviewEventStreamSchema, { executionId: "aex_1", events });
+}
+
+// ---------------------------------------------------------------------------
+// foldFileReviewEventStream
+// ---------------------------------------------------------------------------
+
+describe("foldFileReviewEventStream", () => {
+  it("returns [] for undefined / empty streams", () => {
+    expect(foldFileReviewEventStream(undefined)).toEqual([]);
+    expect(foldFileReviewEventStream(stream())).toEqual([]);
+  });
+
+  it("opens a set as CAPTURING on baseline, before any candidate", () => {
+    const [set] = foldFileReviewEventStream(stream(baseline("cs1")));
+    expect(set.status).toBe(FileChangeSetStatus.CAPTURING);
+    expect(set.turnId).toBe("t1");
+    expect(set.harnessId).toBe("deep-agent");
+    expect(set.changes).toHaveLength(0);
+  });
+
+  it("moves to AWAITING_REVIEW once a candidate carries changes", () => {
+    const [set] = foldFileReviewEventStream(
+      stream(baseline("cs1"), candidate("cs1", [change("fc1")], "agg1")),
+    );
+    expect(set.status).toBe(FileChangeSetStatus.AWAITING_REVIEW);
+    expect(set.changes.map((c) => c.id)).toEqual(["fc1"]);
+    expect(set.aggregateDigest).toBe("agg1");
+  });
+
+  it("replaces the change list wholesale on a later candidate", () => {
+    const [set] = foldFileReviewEventStream(
+      stream(
+        baseline("cs1"),
+        candidate("cs1", [change("fc1"), change("fc2")]),
+        candidate("cs1", [change("fc3")]),
+      ),
+    );
+    expect(set.changes.map((c) => c.id)).toEqual(["fc3"]);
+  });
+
+  it("marks DECIDED only when every file has a verdict", () => {
+    const partial = foldFileReviewEventStream(
+      stream(
+        baseline("cs1"),
+        candidate("cs1", [change("fc1"), change("fc2")]),
+        fileDecision("cs1", "fc1"),
+      ),
+    )[0];
+    expect(partial.status).toBe(FileChangeSetStatus.AWAITING_REVIEW);
+    expect(partial.decisions).toHaveLength(1);
+
+    const full = foldFileReviewEventStream(
+      stream(
+        baseline("cs1"),
+        candidate("cs1", [change("fc1"), change("fc2")]),
+        fileDecision("cs1", "fc1"),
+        fileDecision("cs1", "fc2"),
+      ),
+    )[0];
+    expect(full.status).toBe(FileChangeSetStatus.DECIDED);
+  });
+
+  it("treats a CHANGE_SET decision as covering every file", () => {
+    const [set] = foldFileReviewEventStream(
+      stream(
+        baseline("cs1"),
+        candidate("cs1", [change("fc1"), change("fc2")]),
+        changeSetDecision("cs1"),
+      ),
+    );
+    expect(set.status).toBe(FileChangeSetStatus.DECIDED);
+  });
+
+  it("keeps terminal RECONCILED/FAILED sticky against a later decision", () => {
+    const reconciledSet = foldFileReviewEventStream(
+      stream(
+        baseline("cs1"),
+        candidate("cs1", [change("fc1")]),
+        reconciled("cs1"),
+        fileDecision("cs1", "fc1"), // arrives after reconcile — must not downgrade
+      ),
+    )[0];
+    expect(reconciledSet.status).toBe(FileChangeSetStatus.RECONCILED);
+
+    const failedSet = foldFileReviewEventStream(
+      stream(baseline("cs1"), candidate("cs1", [change("fc1")]), failed("cs1"))
+    )[0];
+    expect(failedSet.status).toBe(FileChangeSetStatus.FAILED);
+  });
+
+  it("groups multiple change sets in first-seen order", () => {
+    const sets = foldFileReviewEventStream(
+      stream(
+        baseline("cs2"),
+        candidate("cs2", [change("fc-a")]),
+        baseline("cs1"),
+        candidate("cs1", [change("fc-b")]),
+      ),
+    );
+    expect(sets.map((s) => s.id)).toEqual(["cs2", "cs1"]);
+  });
+
+  it("skips events with no change_set_id", () => {
+    const orphan = create(FileReviewEventSchema, {
+      changeSetId: "",
+      eventType: FileReviewEventType.BASELINE_CAPTURED,
+    });
+    expect(foldFileReviewEventStream(stream(orphan))).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// displayFileChangeSets — projection-first, fold-on-terminal
+// ---------------------------------------------------------------------------
+
+describe("displayFileChangeSets", () => {
+  it("returns [] for undefined status", () => {
+    expect(displayFileChangeSets(undefined)).toEqual([]);
+  });
+
+  it("prefers the server projection when present (preserving its reference)", () => {
+    const projected = [create(FileChangeSetSchema, { id: "cs1" })];
+    const status = create(AgentExecutionStatusSchema, {
+      fileChangeSets: projected,
+      // A ledger is also present, but the projection wins for a live execution.
+      fileReviewEventStream: stream(baseline("cs1")),
+    });
+    const result = displayFileChangeSets(status);
+    expect(result).toBe(status.fileChangeSets); // same ref — no re-fold, memo-safe
+  });
+
+  it("folds the ledger when the projection is empty (terminal execution)", () => {
+    const status = create(AgentExecutionStatusSchema, {
+      fileChangeSets: [], // terminal: server projects nil
+      fileReviewEventStream: stream(
+        baseline("cs1"),
+        candidate("cs1", [change("fc1")]),
+        changeSetDecision("cs1"),
+        reconciled("cs1"),
+      ),
+    });
+    const result = displayFileChangeSets(status);
+    expect(result.map((s) => s.id)).toEqual(["cs1"]);
+    expect(result[0].status).toBe(FileChangeSetStatus.RECONCILED);
+  });
+
+  it("returns [] when neither projection nor ledger has content", () => {
+    const status = create(AgentExecutionStatusSchema, {});
+    expect(displayFileChangeSets(status)).toEqual([]);
+  });
+});

package/src/execution/__tests__/to-display-file-change.test.ts

@@ -0,0 +1,91 @@
+// Unit tests for the CapturedFileChange -> FileChange display projection.
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  CapturedFileChangeSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { FileContentSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  FileChangeCaptureLevel,
+  FileChangeKind,
+  FileChangeType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { toDisplayFileChange } from "../to-display-file-change";
+
+function inline(text: string) {
+  return create(FileContentSchema, { body: { case: "inline", value: text } });
+}
+
+describe("toDisplayFileChange", () => {
+  it("maps a MODIFY with both sides to a WHOLE_FILE before/after change", () => {
+    const fc = toDisplayFileChange(
+      create(CapturedFileChangeSchema, {
+        id: "fc1",
+        pathBefore: "src/a.ts",
+        pathAfter: "src/a.ts",
+        kind: FileChangeKind.MODIFY,
+        before: inline("old"),
+        after: inline("new"),
+      }),
+    );
+    expect(fc.path).toBe("src/a.ts");
+    expect(fc.changeType).toBe(FileChangeType.MODIFY);
+    expect(fc.captureLevel).toBe(FileChangeCaptureLevel.WHOLE_FILE);
+    expect(fc.before?.body.case).toBe("inline");
+    expect(fc.after?.body.case).toBe("inline");
+    expect(fc.renameFrom).toBe("");
+  });
+
+  it("maps ADD -> CREATE and uses pathAfter", () => {
+    const fc = toDisplayFileChange(
+      create(CapturedFileChangeSchema, {
+        id: "fc1",
+        pathAfter: "src/new.ts",
+        kind: FileChangeKind.ADD,
+        after: inline("hello"),
+      }),
+    );
+    expect(fc.changeType).toBe(FileChangeType.CREATE);
+    expect(fc.path).toBe("src/new.ts");
+  });
+
+  it("maps DELETE -> DELETE and uses pathBefore when pathAfter is empty", () => {
+    const fc = toDisplayFileChange(
+      create(CapturedFileChangeSchema, {
+        id: "fc1",
+        pathBefore: "src/gone.ts",
+        kind: FileChangeKind.DELETE,
+        before: inline("bye"),
+      }),
+    );
+    expect(fc.changeType).toBe(FileChangeType.DELETE);
+    expect(fc.path).toBe("src/gone.ts");
+  });
+
+  it("maps RENAME -> RENAME and carries renameFrom = pathBefore", () => {
+    const fc = toDisplayFileChange(
+      create(CapturedFileChangeSchema, {
+        id: "fc1",
+        pathBefore: "src/old-name.ts",
+        pathAfter: "src/new-name.ts",
+        kind: FileChangeKind.RENAME,
+      }),
+    );
+    expect(fc.changeType).toBe(FileChangeType.RENAME);
+    expect(fc.path).toBe("src/new-name.ts");
+    expect(fc.renameFrom).toBe("src/old-name.ts");
+  });
+
+  it("carries a binary side through so the renderer can detect it", () => {
+    const fc = toDisplayFileChange(
+      create(CapturedFileChangeSchema, {
+        id: "fc1",
+        pathAfter: "img.png",
+        kind: FileChangeKind.ADD,
+        after: create(FileContentSchema, { isBinary: true }),
+      }),
+    );
+    expect(fc.after?.isBinary).toBe(true);
+  });
+});

package/src/execution/__tests__/tool-view.file-changes.test.ts

@@ -0,0 +1,100 @@
+// Covers normalizeToolResult's file-edit / file-write views, reconstructed from
+// the tool args (and the Cursor result envelope). Phase 5 Slice 4 removed the
+// ToolCall.file_changes capture (message.proto field 22), so the args are the
+// single source for the inline transcript diff; captured file review renders via
+// FileReviewCard / the FileChangeSet ledger, tested separately.
+
+import { describe, it, expect } from "vitest";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import { ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ToolCallStatus,
+  ToolKind,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { normalizeToolResult } from "../tool-view";
+
+/** A completed FILE_EDIT tool call carrying the given args/result. */
+function editToolCall(opts: { args?: Record<string, unknown>; result?: string }) {
+  return create(ToolCallSchema, {
+    id: "tc-1",
+    name: "edit_file",
+    toolKind: ToolKind.FILE_EDIT,
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    args: (opts.args ?? {}) as JsonObject,
+    result: opts.result ?? "",
+  });
+}
+
+/** A completed FILE_WRITE tool call carrying the given args. */
+function writeToolCall(opts: { args?: Record<string, unknown> }) {
+  return create(ToolCallSchema, {
+    id: "tc-w",
+    name: "write_file",
+    toolKind: ToolKind.FILE_WRITE,
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    args: (opts.args ?? {}) as JsonObject,
+  });
+}
+
+describe("normalizeEdit — from args", () => {
+  it("reconstructs a diff from old_string / new_string", () => {
+    const view = normalizeToolResult(
+      editToolCall({
+        args: { path: "legacy.ts", old_string: "foo", new_string: "bar" },
+        result: "Successfully replaced 1 occurrence(s)",
+      }),
+    );
+    expect(view.type).toBe("diff");
+    if (view.type !== "diff") return;
+    expect(view.oldText).toBe("foo");
+    expect(view.newText).toBe("bar");
+    expect(view.path).toBe("legacy.ts");
+    // The row carries no whole-file capture; captureLevel is left unset.
+    expect(view.captureLevel).toBeUndefined();
+  });
+
+  it("parses the Cursor result envelope stats when present", () => {
+    const view = normalizeToolResult(
+      editToolCall({
+        args: { path: "x.ts" },
+        result: JSON.stringify({
+          value: { linesAdded: 3, linesRemoved: 2, diffString: "@@ patch @@" },
+        }),
+      }),
+    );
+    if (view.type !== "diff") return;
+    expect(view.linesAdded).toBe(3);
+    expect(view.linesRemoved).toBe(2);
+    expect(view.unifiedDiff).toBe("@@ patch @@");
+    expect(view.captureLevel).toBeUndefined();
+  });
+
+  it("resolves the path from the args (path / file_path / file / filename)", () => {
+    expect(
+      (() => {
+        const v = normalizeToolResult(editToolCall({ args: { file_path: "src/app/main.ts", old_string: "a", new_string: "b" } }));
+        return v.type === "diff" ? v.path : "";
+      })(),
+    ).toBe("src/app/main.ts");
+  });
+});
+
+describe("normalizeWrite — from args", () => {
+  it("renders the proposed whole-file content from the args (contents)", () => {
+    const CONTENT = "# Notes\n\n- first\n- second\n";
+    const view = normalizeToolResult(
+      writeToolCall({ args: { path: "notes.md", contents: CONTENT } }),
+    );
+    expect(view.type).toBe("file");
+    if (view.type !== "file") return;
+    expect(view.path).toBe("notes.md");
+    expect(view.content).toBe(CONTENT);
+  });
+
+  it("defaults to empty content when the args carry none", () => {
+    const view = normalizeToolResult(writeToolCall({ args: { path: "empty.ts" } }));
+    if (view.type !== "file") return;
+    expect(view.content).toBe("");
+    expect(view.path).toBe("empty.ts");
+  });
+});

package/src/execution/__tests__/tool-view.fixtures.test.ts

@@ -49,6 +49,7 @@ describe("result-view fixtures", () => {
       type: string;
       path?: string;
       exitCode?: number;
+      command?: string;
       count?: number;
       mcpServerSlug?: string;
       linesAdded?: number;
@@ -92,6 +93,9 @@ describe("result-view fixtures", () => {
       if (c.expected.exitCode !== undefined && view.type === "terminal") {
         expect(view.exitCode).toBe(c.expected.exitCode);
       }
+      if (c.expected.command !== undefined && view.type === "terminal") {
+        expect(view.command).toBe(c.expected.command);
+      }
       if (c.expected.count !== undefined && view.type === "search") {
         expect(view.count).toBe(c.expected.count);
       }