@stigmer/sdk 3.0.9-dev.20260615153829 → 3.1.0

package/execution/file-review-fold.js

@@ -0,0 +1,182 @@
+// Framework-agnostic fold of the file-review event ledger into FileChangeSets.
+//
+// The server persists an append-only `file_review_event_stream` ledger on the
+// execution status and computes `file_change_sets` as its projection. That
+// server projection is phase-aware: it is nil for a TERMINAL execution (a dead
+// execution has no *actionable* review). Settled/historical display therefore
+// cannot read the projection — it must fold the always-preserved ledger itself.
+//
+// `foldFileReviewEventStream` is the TypeScript port of the Go projector
+// `ProjectFileChangeSets` (backend/services/stigmer-server/pkg/domain/
+// agentexecution/filereview/project.go), and its Java mirror
+// `FileChangeSetProjector`. It is byte-for-byte identical to them EXCEPT it does
+// not apply the terminal-phase gate — that is the whole point of the client-side
+// fold (it must render settled sets for a terminal execution). Every other rule
+// (first-seen change-set ordering, last-writer-wins scalars, decision
+// accumulation, wholesale change replacement, sticky terminal status) matches
+// the server exactly, so live and settled views agree.
+//
+// Parity is not maintained by discipline: the shared cross-edition corpus at
+// apis/testdata/hitl/file-review/*.json — already replayed by the Go and Java
+// projector suites — is replayed against this fold too (see the corpus parity
+// test), so a drift between TS and the backends fails a test rather than
+// shipping.
+//
+// This module has no React/framework dependency (mirrors tool-view.ts) so it is
+// shared by @stigmer/react and @stigmer/ink and mirror-able by the Go CLI.
+import { create } from "@bufbuild/protobuf";
+import { FileChangeSetSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { FileChangeSetStatus, FileDecisionScope, FileReviewEventType, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/**
+ * Folds a file-review event ledger into its list of {@link FileChangeSet}s,
+ * grouped by `change_set_id` in first-seen order.
+ *
+ * This is the display fold: unlike the server projection it does NOT collapse to
+ * an empty list for a terminal execution, so a completed/failed/cancelled
+ * execution still yields its settled sets for read-only display. For the LIVE
+ * (actionable) view, prefer the server-computed `status.file_change_sets`
+ * projection (it is structurally shared across stream frames); this fold is the
+ * settled/terminal complement — see {@link displayFileChangeSets}.
+ *
+ * The fold is a faithful port of the Go/Java projector: scalar and snapshot
+ * fields are last-writer-wins, `decisions` accumulate, `changes` are replaced
+ * wholesale by the latest `CANDIDATE_CAPTURED`, and terminal `RECONCILED` /
+ * `FAILED` statuses are sticky (a later non-terminal event never downgrades
+ * them).
+ *
+ * @param stream - The execution's `file_review_event_stream`, or `undefined`.
+ * @returns One {@link FileChangeSet} per `change_set_id`, in first-seen order.
+ */
+export function foldFileReviewEventStream(stream) {
+    if (!stream || stream.events.length === 0)
+        return [];
+    const order = [];
+    const byId = new Map();
+    for (const ev of stream.events) {
+        const changeSetId = ev.changeSetId;
+        // An event with no correlation id cannot be attributed to a set; the server
+        // skips it, so we do too.
+        if (!changeSetId)
+            continue;
+        let set = byId.get(changeSetId);
+        if (!set) {
+            set = create(FileChangeSetSchema, { id: changeSetId });
+            byId.set(changeSetId, set);
+            order.push(changeSetId);
+        }
+        applyEvent(set, ev);
+    }
+    return order.map((id) => byId.get(id));
+}
+/**
+ * The single read seam for displaying an execution's file change sets.
+ *
+ * Returns the server-computed `status.file_change_sets` projection when it is
+ * present (a LIVE execution — the projection is structurally shared across
+ * stream frames, so consumers keep stable references and streaming re-renders
+ * stay scoped to the actively-changing card), and otherwise folds the ledger
+ * (a TERMINAL execution — the server projects nil there, but the ledger is
+ * preserved). The fold therefore never runs on the streaming hot path; it only
+ * reconstructs the settled sets a dead execution would otherwise not display.
+ *
+ * The two branches are equivalent by construction for a non-terminal execution
+ * (the fold minus its terminal gate IS the server projection — locked by the
+ * corpus parity test), so this accessor is a single consistent source whichever
+ * branch it takes.
+ *
+ * @param status - The execution status, or `undefined`.
+ * @returns The change sets to display, or an empty array when there are none.
+ */
+export function displayFileChangeSets(status) {
+    const projected = status?.fileChangeSets;
+    if (projected && projected.length > 0)
+        return projected;
+    return foldFileReviewEventStream(status?.fileReviewEventStream);
+}
+/**
+ * Applies one ledger event to its change-set accumulator, mirroring the Go
+ * projector's `applyEvent`. The switch is keyed on `event_type` (the coarse
+ * bucket the server keys on); the typed payload is read defensively so a
+ * malformed event degrades to zero values exactly as the Go nil-getters do,
+ * rather than throwing.
+ */
+function applyEvent(set, ev) {
+    switch (ev.eventType) {
+        case FileReviewEventType.BASELINE_CAPTURED: {
+            const b = ev.payload.case === "baselineCaptured" ? ev.payload.value : undefined;
+            set.turnId = b?.turnId ?? "";
+            set.harnessId = b?.harnessId ?? "";
+            set.baselineSnapshot = b?.baselineSnapshot;
+            set.status = FileChangeSetStatus.CAPTURING;
+            break;
+        }
+        case FileReviewEventType.CANDIDATE_CAPTURED: {
+            const c = ev.payload.case === "candidateCaptured" ? ev.payload.value : undefined;
+            set.candidateSnapshot = c?.candidateSnapshot;
+            set.changes = c?.changes ?? [];
+            set.aggregateDigest = c?.aggregateDigest ?? "";
+            set.diffCompleteness = c?.diffCompleteness ?? set.diffCompleteness;
+            set.status = deriveStatusAfterCandidate(set);
+            break;
+        }
+        case FileReviewEventType.FILE_DECIDED: {
+            if (ev.payload.case === "fileDecided") {
+                set.decisions.push(ev.payload.value);
+            }
+            set.status = deriveStatusAfterCandidate(set);
+            break;
+        }
+        case FileReviewEventType.RECONCILED: {
+            const r = ev.payload.case === "reconciled" ? ev.payload.value : undefined;
+            set.approvedSnapshot = r?.approvedSnapshot;
+            set.status = FileChangeSetStatus.RECONCILED;
+            break;
+        }
+        case FileReviewEventType.FAILED: {
+            set.status = FileChangeSetStatus.FAILED;
+            break;
+        }
+        // UNSPECIFIED / any future type: ignored, matching the Go projector.
+        default:
+            break;
+    }
+}
+/**
+ * Derives a change set's status after a candidate or decision event, mirroring
+ * the Go projector's `deriveStatusAfterCandidate`. Terminal statuses are sticky:
+ * a `FILE_DECIDED` arriving after `RECONCILED`/`FAILED` never reverts the set to
+ * an actionable state.
+ */
+function deriveStatusAfterCandidate(set) {
+    if (set.status === FileChangeSetStatus.RECONCILED ||
+        set.status === FileChangeSetStatus.FAILED) {
+        return set.status;
+    }
+    return isFullyDecided(set)
+        ? FileChangeSetStatus.DECIDED
+        : FileChangeSetStatus.AWAITING_REVIEW;
+}
+/**
+ * Whether every captured change in the set has a verdict, mirroring the Go
+ * projector's `isFullyDecided`: a set with no captured changes is never fully
+ * decided; any CHANGE_SET-scoped decision covers all files; otherwise every
+ * change id must appear among the FILE-scoped decisions.
+ */
+function isFullyDecided(set) {
+    if (set.changes.length === 0)
+        return false;
+    const decidedFileIds = new Set();
+    for (const decision of set.decisions) {
+        if (decision.scope === FileDecisionScope.CHANGE_SET)
+            return true;
+        if (decision.scope === FileDecisionScope.FILE) {
+            decidedFileIds.add(decision.fileChangeId);
+        }
+    }
+    for (const change of set.changes) {
+        if (!decidedFileIds.has(change.id))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=file-review-fold.js.map

package/execution/file-review-fold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-review-fold.js","sourceRoot":"","sources":["../../src/execution/file-review-fold.ts"],"names":[],"mappings":"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"}

package/execution/to-display-file-change.d.ts

@@ -0,0 +1,14 @@
+import type { CapturedFileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+/**
+ * Adapts a {@link CapturedFileChange} to the {@link FileChange} the diff
+ * renderers consume. The two reuse the same `FileContent` for before/after, so
+ * the bodies map directly; a capture is always WHOLE_FILE (the candidate carries
+ * the byte-exact sides), so the resulting `FileChange` renders as a true
+ * before/after diff.
+ *
+ * @param captured - A captured file change from a `FileChangeSet`.
+ * @returns The equivalent display-side {@link FileChange}.
+ */
+export declare function toDisplayFileChange(captured: CapturedFileChange): FileChange;
+//# sourceMappingURL=to-display-file-change.d.ts.map

package/execution/to-display-file-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-display-file-change.d.ts","sourceRoot":"","sources":["../../src/execution/to-display-file-change.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oEAAoE,CAAC;AAC7G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iEAAiE,CAAC;AAQlG;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,UAAU,CAU5E"}

package/execution/to-display-file-change.js

@@ -0,0 +1,57 @@
+// Projects a CapturedFileChange (the file-review ledger/domain type) onto the
+// FileChange display view-model that every diff renderer speaks.
+//
+// The two representations coexist by design (see the CapturedFileChange proto
+// comment): CapturedFileChange is the apply-then-review domain type (always
+// whole-file, byte-exact before/after, carries digests / capture_class /
+// blocked_reason for enforcement), while FileChange is the *display superset* —
+// it additionally models captureLevel and inline HUNK_ONLY diffs, which the
+// still-live deny-gate approval produces directly. Because FileChange is the
+// superset, this projection is lossless; the reverse would not be (a whole-file
+// CapturedFileChange has no inline hunk to lose, but a HUNK_ONLY FileChange has
+// no whole-file bytes). That asymmetry is exactly why display renders through
+// FileChange and this adapter only ever runs one way.
+//
+// This is a pure derive-on-read projection from the single source (the ledger),
+// not a stored second copy: it is called at render time by both FileReviewCard
+// and useSessionFileChanges, never persisted.
+//
+// Framework-agnostic (no React) so it is shared across @stigmer/react,
+// @stigmer/ink, and mirror-able by the Go CLI, alongside tool-view.ts.
+import { create } from "@bufbuild/protobuf";
+import { FileChangeSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { FileChangeCaptureLevel, FileChangeKind, FileChangeType, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/**
+ * Adapts a {@link CapturedFileChange} to the {@link FileChange} the diff
+ * renderers consume. The two reuse the same `FileContent` for before/after, so
+ * the bodies map directly; a capture is always WHOLE_FILE (the candidate carries
+ * the byte-exact sides), so the resulting `FileChange` renders as a true
+ * before/after diff.
+ *
+ * @param captured - A captured file change from a `FileChangeSet`.
+ * @returns The equivalent display-side {@link FileChange}.
+ */
+export function toDisplayFileChange(captured) {
+    return create(FileChangeSchema, {
+        path: captured.pathAfter || captured.pathBefore,
+        changeType: toFileChangeType(captured.kind),
+        captureLevel: FileChangeCaptureLevel.WHOLE_FILE,
+        before: captured.before,
+        after: captured.after,
+        renameFrom: captured.kind === FileChangeKind.RENAME ? captured.pathBefore : "",
+    });
+}
+/** Maps the ledger's {@link FileChangeKind} to the display {@link FileChangeType}. */
+function toFileChangeType(kind) {
+    switch (kind) {
+        case FileChangeKind.ADD:
+            return FileChangeType.CREATE;
+        case FileChangeKind.DELETE:
+            return FileChangeType.DELETE;
+        case FileChangeKind.RENAME:
+            return FileChangeType.RENAME;
+        default:
+            return FileChangeType.MODIFY;
+    }
+}
+//# sourceMappingURL=to-display-file-change.js.map

package/execution/to-display-file-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-display-file-change.js","sourceRoot":"","sources":["../../src/execution/to-display-file-change.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iEAAiE;AACjE,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,yEAAyE;AACzE,gFAAgF;AAChF,4EAA4E;AAC5E,6EAA6E;AAC7E,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,sDAAsD;AACtD,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,8CAA8C;AAC9C,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AAEvE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAG5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iEAAiE,CAAC;AACnG,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,cAAc,GACf,MAAM,8DAA8D,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA4B;IAC9D,OAAO,MAAM,CAAC,gBAAgB,EAAE;QAC9B,IAAI,EAAE,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,UAAU;QAC/C,UAAU,EAAE,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC3C,YAAY,EAAE,sBAAsB,CAAC,UAAU;QAC/C,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,UAAU,EACR,QAAQ,CAAC,IAAI,KAAK,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;KACrE,CAAC,CAAC;AACL,CAAC;AAED,sFAAsF;AACtF,SAAS,gBAAgB,CAAC,IAAoB;IAC5C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,cAAc,CAAC,GAAG;YACrB,OAAO,cAAc,CAAC,MAAM,CAAC;QAC/B,KAAK,cAAc,CAAC,MAAM;YACxB,OAAO,cAAc,CAAC,MAAM,CAAC;QAC/B,KAAK,cAAc,CAAC,MAAM;YACxB,OAAO,cAAc,CAAC,MAAM,CAAC;QAC/B;YACE,OAAO,cAAc,CAAC,MAAM,CAAC;IACjC,CAAC;AACH,CAAC"}

package/execution/tool-view.d.ts

@@ -1,6 +1,7 @@
 import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { FileChangeCaptureLevel } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-export { ToolKind };
+export { ToolKind, FileChangeCaptureLevel };
 /** A single match in a search/grep result. */
 export interface ToolSearchMatch {
     /** File path the match was found in, when the result format provides it. */
@@ -33,6 +34,7 @@ export type ToolResultView = {
     readonly linesAdded?: number;
     readonly linesRemoved?: number;
     readonly unifiedDiff?: string;
+    readonly captureLevel?: FileChangeCaptureLevel;
 } | {
     readonly type: "file";
     readonly path: string;
@@ -41,6 +43,7 @@ export type ToolResultView = {
     readonly truncated: boolean;
 } | {
     readonly type: "terminal";
+    readonly command?: string;
     readonly stdout: string;
     readonly stderr: string;
     readonly exitCode?: number;
@@ -48,6 +51,8 @@ export type ToolResultView = {
     readonly type: "search";
     readonly matches: readonly ToolSearchMatch[];
     readonly count: number;
+    readonly kind?: "files" | "content";
+    readonly truncated?: boolean;
 } | {
     readonly type: "list";
     readonly entries: readonly string[];
@@ -67,7 +72,8 @@ export type ToolResultView = {
     readonly message: string;
 } | {
     readonly type: "outputRef";
-    readonly downloadUrl: string;
+    readonly storageKey: string;
+    readonly contentHash: string;
     readonly isImage: boolean;
     readonly mimeType: string;
     readonly sizeBytes: number;

package/execution/tool-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-view.d.ts","sourceRoot":"","sources":["../../src/execution/tool-view.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,8DAA8D,CAAC;AAExF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iEAAiE,CAAC;AAEhG,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAKtB;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,GAGD;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B,GAED;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtF;IACE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAIpD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GAED;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAgE/B;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,UAAU,CAAC,GAAG,QAAQ,CAKzG;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,QAAQ,CASpF;AAaD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CA+CtE"}
+{"version":3,"file":"tool-view.d.ts","sourceRoot":"","sources":["../../src/execution/tool-view.ts"],"names":[],"mappings":"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"}

package/execution/tool-view.js

@@ -8,13 +8,24 @@
 //     that presentation layers (React, Ink, the Go CLI's equivalent) render
 //     without re-parsing third-party engine formats.
 //
+// For file edits, normalizeToolResult prefers the runner's authoritative
+// before/after capture (ToolCall.file_changes, #186) over reconstructing a diff
+// from args, surfacing the capture's fidelity via the diff view's captureLevel so
+// the renderer is honest about whole-file vs hunk-only. The capture is a clean,
+// structured proto, so it is consumed proto-first rather than re-modeled here;
+// the repeated/multi-file projection and offloaded-body fetching live in the
+// React layer. Counts and unified diffs for a whole-file capture stay derivable
+// by the presentation layer (the runner emits 0/"" sentinels for them), keeping
+// one diff implementation as the source of truth.
+//
 // This module has no React or framework dependency so it can be shared by
 // @stigmer/react and @stigmer/ink. The Go CLI mirrors it; the shared contract
 // is test/fixtures/tool-view/. Engine result formats are version-fragile, so
 // every assumption here is fixture-backed and degrades gracefully to json/text.
 import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-export { ToolKind };
+import { FileChangeCaptureLevel } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+export { ToolKind, FileChangeCaptureLevel };
 // ---------------------------------------------------------------------------
 // Identity: resolveToolKind
 // ---------------------------------------------------------------------------
@@ -107,12 +118,15 @@ export function normalizeToolResult(toolCall) {
     }
     // Output was offloaded to artifact storage (too large to inline): the real
     // bytes are no longer in `result` (which holds only a short head/label), so
-    // render from the reference instead of re-parsing the placeholder.
-    if (toolCall.outputRef && toolCall.outputRef.downloadUrl) {
+    // render from the reference instead of re-parsing the placeholder. The view
+    // carries the stable `storageKey` so consumers resolve the bytes/URL on
+    // demand — the persisted URL was ephemeral and is no longer trusted.
+    if (toolCall.outputRef && toolCall.outputRef.storageKey) {
         const ref = toolCall.outputRef;
         return {
             type: "outputRef",
-            downloadUrl: ref.downloadUrl,
+            storageKey: ref.storageKey,
+            contentHash: ref.contentHash,
             isImage: ref.isImage,
             mimeType: ref.mimeType,
             sizeBytes: Number(ref.sizeBytes),
@@ -130,7 +144,7 @@ export function normalizeToolResult(toolCall) {
         case ToolKind.FILE_DELETE:
             return result ? { type: "text", text: result } : { type: "empty" };
         case ToolKind.SHELL:
-            return normalizeShell(result);
+            return normalizeShell(result, args);
         case ToolKind.SEARCH:
             return normalizeSearch(result);
         case ToolKind.LIST:
@@ -144,14 +158,16 @@ export function normalizeToolResult(toolCall) {
     }
 }
 function normalizeEdit(args, result) {
+    // The inline transcript diff for a file edit is reconstructed from the tool
+    // args (there is no captured `file_changes` mirror — apply-then-review renders
+    // captured diffs via FileReviewCard/FileChangeDiff, not here). The native
+    // engine returns prose with no diff, so the presentation layer computes the
+    // visual diff from the args fragments; the Cursor SDK returns a stringified
+    // envelope with precomputed diff stats.
     const path = firstString(args, PATH_FIELDS) ?? "";
     const oldText = firstString(args, OLD_TEXT_FIELDS);
     const newText = firstString(args, NEW_TEXT_FIELDS);
-    // The Cursor SDK returns a stringified envelope with precomputed diff stats;
-    // prefer those when present. The native engine returns prose with no diff, so
-    // the presentation layer computes the visual diff from oldText/newText.
-    const envelope = tryParseJson(result);
-    const value = isRecord(envelope) && isRecord(envelope.value) ? envelope.value : undefined;
+    const value = cursorEnvelopeValue(tryParseJson(result));
     const linesAdded = value ? asNumber(value.linesAdded) : undefined;
     const linesRemoved = value ? asNumber(value.linesRemoved) : undefined;
     const unifiedDiff = value ? asString(value.diffString) : undefined;
@@ -166,6 +182,8 @@ function normalizeEdit(args, result) {
     };
 }
 function normalizeWrite(args) {
+    // The inline transcript view for a file write is the proposed content from the
+    // tool args (captured diffs render via FileReviewCard, not here).
     const path = firstString(args, PATH_FIELDS) ?? "";
     const content = firstString(args, WRITE_CONTENT_FIELDS) ?? "";
     return { type: "file", path, content, language: languageFromPath(path), truncated: false };
@@ -184,15 +202,26 @@ function normalizeRead(args, result) {
 // or "[Command succeeded]". Format owned by the engine — see DD-003; covered by
 // test/fixtures/tool-view/result-views.json so a format change fails one test.
 const SHELL_EXIT_MARKER = /\n?\[Command (?:succeeded|failed with exit code (\d+))\]\s*$/;
-function normalizeShell(result) {
-    // Cursor sub-agent steps can carry a structured {stdout,stderr,exitCode}.
+function normalizeShell(result, args) {
+    // The command is the session's prompt line. "command" matches the shell
+    // primaryField shared with the runner/Go classifier and both native and
+    // Cursor args, so no fallback fields are needed.
+    const command = firstString(args, ["command"]);
+    // Two shapes carry structured shell output: native sub-agent steps emit the
+    // {stdout,stderr,exitCode} record directly; the Cursor SDK nests it under a
+    // {status, value} envelope (the same envelope the edit tool uses). Read
+    // whichever is present so the real output surfaces instead of the raw JSON
+    // string. A failed shell never reaches here — normalizeToolResult routes
+    // TOOL_CALL_FAILED to the error view first — so only success is handled.
     const parsed = tryParseJson(result);
-    if (isRecord(parsed) && ("stdout" in parsed || "exitCode" in parsed)) {
+    const shell = hasShellFields(parsed) ? parsed : cursorEnvelopeValue(parsed);
+    if (hasShellFields(shell)) {
         return {
             type: "terminal",
-            stdout: asString(parsed.stdout) ?? "",
-            stderr: asString(parsed.stderr) ?? "",
-            exitCode: asNumber(parsed.exitCode),
+            command,
+            stdout: asString(shell.stdout) ?? "",
+            stderr: asString(shell.stderr) ?? "",
+            exitCode: asNumber(shell.exitCode),
         };
     }
     const marker = result.match(SHELL_EXIT_MARKER);
@@ -200,23 +229,166 @@ function normalizeShell(result) {
         const stdout = result.replace(SHELL_EXIT_MARKER, "");
         // Group 1 is set only on failure; a matched marker without it is success (0).
         const exitCode = marker[1] !== undefined ? Number(marker[1]) : 0;
-        return { type: "terminal", stdout, stderr: "", exitCode };
+        return { type: "terminal", command, stdout, stderr: "", exitCode };
     }
-    return { type: "terminal", stdout: result, stderr: "" };
+    return { type: "terminal", command, stdout: result, stderr: "" };
 }
 // A grep-style match line, e.g. "  12: // TODO: fix".
 const GREP_MATCH_LINE = /^\s*\d+[:\t]/;
+// The Cursor SDK returns search results as a stringified JSON envelope, not the
+// plain text the native harness emits. Two shapes are observed, both fixture-
+// backed in test/fixtures/tool-view/result-views.json:
+//   - file-name search (Glob/file_search): the {status,value} envelope with
+//     value.files (paths), value.totalFiles, and the truncation flags.
+//   - grep / codebase search: {workspaceResults: {<path>: {type, output}}},
+//     where each workspace's output carries files and/or line-bearing matches.
+// Anything we don't recognise degrades to the json view (readable) rather than
+// being wrapped as a single fake match by the plain-text path below.
 function normalizeSearch(result) {
+    const parsed = tryParseJson(result);
+    if (parsed !== undefined) {
+        const fromEnvelope = searchFromEnvelope(parsed);
+        if (fromEnvelope) {
+            return fromEnvelope;
+        }
+        // Recognised JSON shape but nothing searchable in it (or an unknown shape):
+        // a clean json/object view beats wrapping the raw string as one "match".
+        if (isRecord(parsed) || Array.isArray(parsed)) {
+            return { type: "json", value: parsed };
+        }
+    }
+    return searchFromPlainText(result);
+}
+// Projects a parsed Cursor search envelope into a search view, or null when the
+// parsed JSON is not one of the recognised search shapes.
+//
+// Both shapes are wrapped in the Cursor {status,value} envelope (shared with
+// edit/shell), so the payload lives under `value`: file-name search puts `files`
+// there, grep/codebase search puts `workspaceResults` there. We read the inner
+// value when present and fall back to the parsed object itself, so a future
+// un-enveloped shape still resolves rather than dropping to the json fallback.
+function searchFromEnvelope(parsed) {
+    const inner = cursorEnvelopeValue(parsed) ?? (isRecord(parsed) ? parsed : undefined);
+    if (!inner)
+        return null;
+    const truncated = Boolean(inner.clientTruncated) || Boolean(inner.ripgrepTruncated);
+    // file-name search (Glob/file_search): inner.files is an array of path strings.
+    if (Array.isArray(inner.files)) {
+        const matches = pathsToFileMatches(inner.files);
+        const count = asNumber(inner.totalFiles) ?? matches.length;
+        // Safety net: the engine reports results but we extracted none — the shape
+        // drifted (e.g. files are objects, not strings). Surface the raw JSON rather
+        // than a misleading "No files found" that hides real data. (Truncation always
+        // returns a non-empty page, so this never fires on a legitimately capped result.)
+        if (count > 0 && matches.length === 0)
+            return null;
+        return { type: "search", matches, count, kind: "files", truncated };
+    }
+    // grep / codebase search: inner.workspaceResults maps a workspace path to its
+    // { type, output }. Flatten every workspace's output into one match list so a
+    // multi-root search reads as a single result. Truncation can be reported at the
+    // envelope level (passed in) or per-workspace (read inside).
+    if (isRecord(inner.workspaceResults)) {
+        return searchFromWorkspaceResults(inner.workspaceResults, truncated);
+    }
+    return null;
+}
+// Flattens the per-workspace results of a grep/codebase search. Each workspace's
+// `output` carries `files` (path matches) and/or `matches` (line-bearing content
+// matches); both are collected, and `truncated` is OR-ed across workspaces.
+//
+// Returns null when the engine reports results (count > 0) but none could be
+// extracted — a shape drift — so the caller degrades to the raw JSON view rather
+// than silently rendering "No files found" over data that is actually there.
+function searchFromWorkspaceResults(workspaceResults, envelopeTruncated) {
+    const fileMatches = [];
+    const contentMatches = [];
+    let reportedCount = 0;
+    let hasReportedCount = false;
+    let truncated = envelopeTruncated;
+    for (const ws of Object.values(workspaceResults)) {
+        const output = isRecord(ws) ? ws.output : undefined;
+        if (!isRecord(output))
+            continue;
+        if (Array.isArray(output.files)) {
+            fileMatches.push(...pathsToFileMatches(output.files));
+        }
+        if (Array.isArray(output.matches)) {
+            contentMatches.push(...toContentMatches(output.matches));
+        }
+        const count = asNumber(output.count);
+        if (count !== undefined) {
+            reportedCount += count;
+            hasReportedCount = true;
+        }
+        if (Boolean(output.clientTruncated) || Boolean(output.ripgrepTruncated)) {
+            truncated = true;
+        }
+    }
+    // Content matches are the richer signal, so when present they drive the view;
+    // otherwise the result is a file-name list.
+    const isContent = contentMatches.length > 0;
+    const matches = isContent ? contentMatches : fileMatches;
+    // Safety net: results were reported but none extracted — the per-workspace
+    // output shape drifted. Bail to the raw JSON view (see the caller) instead of
+    // hiding the data behind a "No matches".
+    if (hasReportedCount && reportedCount > 0 && matches.length === 0) {
+        return null;
+    }
+    return {
+        type: "search",
+        matches,
+        count: hasReportedCount ? reportedCount : matches.length,
+        kind: isContent ? "content" : "files",
+        truncated,
+    };
+}
+// Maps an engine-provided array of file paths into file-name matches. Both
+// `file` and `text` are set to the path so a kind-unaware consumer (e.g. the Ink
+// summary) still shows something useful. Non-string entries are skipped.
+function pathsToFileMatches(files) {
+    const matches = [];
+    for (const f of files) {
+        if (typeof f === "string" && f.length > 0) {
+            matches.push({ file: f, text: f });
+        }
+    }
+    return matches;
+}
+// Maps an engine-provided array of grep matches into content matches. Each entry
+// is read defensively (the exact shape is engine-fragile): a `file`/`path` and a
+// 1-based `line` are carried when present, and the line text is taken from the
+// first available text field, falling back to the stringified entry.
+function toContentMatches(rawMatches) {
+    const matches = [];
+    for (const m of rawMatches) {
+        if (typeof m === "string") {
+            if (m.length > 0)
+                matches.push({ text: m });
+            continue;
+        }
+        if (!isRecord(m))
+            continue;
+        const file = asString(m.file) ?? asString(m.path);
+        const line = asNumber(m.line) ?? asNumber(m.lineNumber);
+        const text = asString(m.text) ?? asString(m.line_text) ?? asString(m.content) ?? "";
+        matches.push({ file, line, text });
+    }
+    return matches;
+}
+// The plain-text path for the native harness: grep emits "  12: match" lines;
+// glob/semantic search emit one path per line.
+function searchFromPlainText(result) {
     const lines = nonEmptyLines(result);
     const matchLines = lines.filter((l) => GREP_MATCH_LINE.test(l));
     if (matchLines.length > 0) {
         const matches = matchLines.map((l) => ({ text: l.trim() }));
-        return { type: "search", matches, count: matches.length };
+        return { type: "search", matches, count: matches.length, kind: "content" };
     }
     // Path/name results (glob, semantic search): each meaningful line is a match.
     const entries = lines.filter((l) => !/^no (files|matches|results)/i.test(l));
-    const matches = entries.map((text) => ({ text }));
-    return { type: "search", matches, count: matches.length };
+    const matches = entries.map((text) => ({ file: text, text }));
+    return { type: "search", matches, count: matches.length, kind: "files" };
 }
 function normalizeList(result) {
     const entries = nonEmptyLines(result);
@@ -289,6 +461,18 @@ function extractContentBlocks(parsed) {
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
+// The Cursor SDK wraps tool payloads in a {status, value} envelope. Returns the
+// inner `value` record when present, so edit and shell read the envelope through
+// one definition instead of each re-deriving its shape.
+function cursorEnvelopeValue(parsed) {
+    return isRecord(parsed) && isRecord(parsed.value) ? parsed.value : undefined;
+}
+// True when a record carries structured shell output (stdout/exitCode). Used to
+// pick between the un-enveloped native shape and the Cursor envelope's inner
+// value in normalizeShell.
+function hasShellFields(v) {
+    return isRecord(v) && ("stdout" in v || "exitCode" in v);
+}
 function asString(v) {
     return typeof v === "string" ? v : undefined;
 }