@stigmer/sdk 3.0.9-dev.20260615153829 → 3.1.0

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);
       }

package/src/execution/__tests__/tool-view.output-ref.test.ts

@@ -0,0 +1,76 @@
+// Covers the offloaded tool-output path: when a result is spilled to artifact
+// storage the runner replaces it with a ToolCallOutputRef. The view must surface
+// the STABLE storageKey (+ contentHash) so consumers resolve the bytes/URL on
+// demand — it must never depend on a persisted (ephemeral) URL.
+
+import { describe, it, expect } from "vitest";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import {
+  ToolCallSchema,
+  ToolCallOutputRefSchema,
+} 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";
+
+function toolCallWithOutputRef(ref: ReturnType<typeof create<typeof ToolCallOutputRefSchema>> | undefined, result = "") {
+  return create(ToolCallSchema, {
+    id: "tc-1",
+    name: "some_tool",
+    toolKind: ToolKind.UNSPECIFIED,
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    args: {} as JsonObject,
+    result,
+    outputRef: ref,
+  });
+}
+
+describe("normalizeToolResult — offloaded output ref", () => {
+  it("emits an outputRef view carrying the stable storageKey and contentHash", () => {
+    const ref = create(ToolCallOutputRefSchema, {
+      storageKey: "artifacts/exec-1/toolcalls/tc-1.txt",
+      contentHash: "sha256:abc",
+      sizeBytes: 900_000n,
+      mimeType: "text/plain",
+      isImage: false,
+      truncatedPreview: "head of the output…",
+    });
+
+    const view = normalizeToolResult(toolCallWithOutputRef(ref, "[output truncated]"));
+
+    expect(view.type).toBe("outputRef");
+    if (view.type !== "outputRef") return;
+    expect(view.storageKey).toBe("artifacts/exec-1/toolcalls/tc-1.txt");
+    expect(view.contentHash).toBe("sha256:abc");
+    expect(view.isImage).toBe(false);
+    expect(view.mimeType).toBe("text/plain");
+    expect(view.sizeBytes).toBe(900_000);
+    expect(view.preview).toBe("head of the output…");
+  });
+
+  it("gates on storageKey, not a URL — an image ref renders inline", () => {
+    const ref = create(ToolCallOutputRefSchema, {
+      storageKey: "artifacts/exec-1/toolcalls/tc-1.png",
+      contentHash: "sha256:img",
+      sizeBytes: 12_345n,
+      mimeType: "image/png",
+      isImage: true,
+    });
+
+    const view = normalizeToolResult(toolCallWithOutputRef(ref));
+
+    expect(view.type).toBe("outputRef");
+    if (view.type !== "outputRef") return;
+    expect(view.isImage).toBe(true);
+    expect(view.storageKey).toBe("artifacts/exec-1/toolcalls/tc-1.png");
+  });
+
+  it("does not produce an outputRef view when no storageKey is present", () => {
+    // A ref with no storageKey is not a usable offload pointer; fall back to text.
+    const ref = create(ToolCallOutputRefSchema, { sizeBytes: 10n });
+    const view = normalizeToolResult(toolCallWithOutputRef(ref, "plain result"));
+    expect(view.type).not.toBe("outputRef");
+  });
+});