@stigmer/react 3.0.9-dev.20260615153829 → 3.1.0

package/src/execution/__tests__/useToolOutputContent.test.tsx

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import { ToolCallOutputRefSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { UseArtifactContentReturn } from "../useArtifactContent";
+
+// Mock the underlying content fetch so the test asserts the derivation logic
+// (execId from storageKey) and the lazy `enabled` gate, not the network.
+const responses = new Map<string, Partial<UseArtifactContentReturn>>();
+const calls: Array<{
+  executionId: string | null;
+  storageKey: string | null;
+  contentHash?: string;
+}> = [];
+
+vi.mock("../useArtifactContent", () => ({
+  useArtifactContent: (
+    executionId: string | null,
+    storageKey: string | null,
+    _entryPath?: string | null,
+    contentHash?: string,
+  ) => {
+    calls.push({ executionId, storageKey, contentHash });
+    const base: UseArtifactContentReturn = {
+      content: null,
+      contentType: null,
+      isTruncated: false,
+      isLoading: false,
+      isRefetching: false,
+      error: null,
+      refetch: () => {},
+    };
+    if (!storageKey) return base;
+    return { ...base, ...responses.get(storageKey) };
+  },
+}));
+
+const { useToolOutputContent } = await import("../useToolOutputContent");
+
+beforeEach(() => {
+  responses.clear();
+  calls.length = 0;
+});
+
+function ref(storageKey: string, contentHash = "h") {
+  return create(ToolCallOutputRefSchema, { storageKey, contentHash });
+}
+
+describe("useToolOutputContent", () => {
+  it("stays idle until enabled (lazy expand)", () => {
+    const { result } = renderHook(() =>
+      useToolOutputContent(ref("artifacts/exec-1/toolcalls/tc.txt"), false),
+    );
+    expect(result.current.content).toBeNull();
+    // The underlying fetch is skipped (null storage key passed through).
+    expect(calls.every((c) => c.storageKey === null)).toBe(true);
+  });
+
+  it("derives the execId from the storage key and fetches when enabled", () => {
+    const key = "artifacts/exec-9/toolcalls/tc.txt";
+    responses.set(key, { content: "FULL", isTruncated: false });
+    const { result } = renderHook(() => useToolOutputContent(ref(key), true));
+
+    expect(result.current.content).toBe("FULL");
+    const call = calls.find((c) => c.storageKey === key);
+    expect(call?.executionId).toBe("exec-9");
+    expect(call?.contentHash).toBe("h");
+  });
+
+  it("passes through truncation", () => {
+    const key = "artifacts/exec-9/toolcalls/tc.txt";
+    responses.set(key, { content: "head", isTruncated: true });
+    const { result } = renderHook(() => useToolOutputContent(ref(key), true));
+    expect(result.current.isTruncated).toBe(true);
+  });
+
+  it("skips when the ref is null", () => {
+    const { result } = renderHook(() => useToolOutputContent(null, true));
+    expect(result.current.content).toBeNull();
+    expect(calls.every((c) => c.storageKey === null)).toBe(true);
+  });
+});

package/src/execution/approval-provenance.ts

@@ -0,0 +1,8 @@
+// Re-export the framework-agnostic provenance label from @stigmer/sdk so the
+// React surface (ApprovalCard "why-gated" line, ToolCallDetail) shares one
+// source of truth with @stigmer/ink and the Go CLI. See the sdk module for the
+// mapping rationale.
+export {
+  describeApprovalPolicySource,
+  isInformativePolicySource,
+} from "@stigmer/sdk";

package/src/execution/artifact-utils.ts

@@ -80,24 +80,6 @@ export function isTextArtifact(artifact: ExecutionArtifact): boolean {
   return TEXT_EXTENSIONS.has(ext);
 }
 
-/**
- * Checks whether an artifact's pre-signed download URL has expired.
- *
- * Returns `true` when:
- * - `expiresAt` is empty or cannot be parsed as a valid date
- * - The current time is past the expiration timestamp
- *
- * Expired URLs can be refreshed via `stigmer.agentExecution.getArtifactDownloadUrl()`.
- */
-export function isArtifactExpired(artifact: ExecutionArtifact): boolean {
-  if (!artifact.expiresAt) return true;
-
-  const expiresMs = Date.parse(artifact.expiresAt);
-  if (Number.isNaN(expiresMs)) return true;
-
-  return Date.now() >= expiresMs;
-}
-
 // ---------------------------------------------------------------------------
 // Render mode classification
 // ---------------------------------------------------------------------------

package/src/execution/execution-phases.ts

@@ -1,16 +1,4 @@
-import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-
-const TERMINAL_PHASES: ReadonlySet<ExecutionPhase> = new Set([
-  ExecutionPhase.EXECUTION_COMPLETED,
-  ExecutionPhase.EXECUTION_FAILED,
-  ExecutionPhase.EXECUTION_CANCELLED,
-  ExecutionPhase.EXECUTION_TERMINATED,
-]);
-
-/**
- * Returns `true` when the given phase represents a final, immutable
- * execution state — no further updates will arrive from the server.
- */
-export function isTerminalPhase(phase: ExecutionPhase): boolean {
-  return TERMINAL_PHASES.has(phase);
-}
+// Re-export the framework-agnostic execution-phase predicates from @stigmer/sdk
+// so the React surface shares one source of truth with @stigmer/ink and the pure
+// SDK logic (e.g. the file-review fold). See the sdk module for the definitions.
+export { isTerminalPhase } from "@stigmer/sdk";

package/src/execution/file-path-resolver.ts

@@ -41,6 +41,44 @@ export function classifyPath(path: string): PathClassification {
   return { kind: "workspace", remainder: clean };
 }
 
+/** A file path split into its directory prefix and final segment for display. */
+export interface DisplayPath {
+  /**
+   * The directory portion including the trailing slash (e.g. `"src/app/"`), or
+   * `""` when the path has no directory. Rendered dimmed and allowed to
+   * truncate — it is context, not identity.
+   */
+  readonly dir: string;
+  /**
+   * The final path segment — the file name (e.g. `"main.ts"`). This is the
+   * identity of the change and must never be clipped.
+   */
+  readonly base: string;
+}
+
+/**
+ * Splits a file path into `{ dir, base }` for filename-first display.
+ *
+ * The motivation: a raw tool-call path is frequently an absolute, deeply-nested
+ * string (`/Users/me/scm/.../notes.md`), and naive CSS `truncate` on the whole
+ * path clips the *end* — hiding the file name, the one part that identifies the
+ * change. Splitting lets the renderer keep the base name always visible and
+ * truncate only the (dimmed) directory.
+ *
+ * Pure (no React) so it is unit-testable in isolation and reusable by any
+ * surface. A trailing slash is tolerated (a directory path keeps its last
+ * segment as the base); a path with no slash is all base.
+ */
+export function splitDisplayPath(path: string): DisplayPath {
+  if (!path) return { dir: "", base: "" };
+  const trimmed = path.replace(/\/+$/, "");
+  const idx = trimmed.lastIndexOf("/");
+  if (idx < 0) return { dir: "", base: trimmed };
+  const base = trimmed.slice(idx + 1);
+  // A path that was only slashes collapses to the original — never an empty base.
+  return base ? { dir: trimmed.slice(0, idx + 1), base } : { dir: "", base: trimmed };
+}
+
 /**
  * Constructs a browsable GitHub blob URL from a git clone URL.
  *

package/src/execution/file-review-status.ts

@@ -0,0 +1,219 @@
+import type {
+  CapturedFileChange,
+  FileChangeSet,
+  FileDecision,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  DiffCompleteness,
+  FileChangeSetStatus,
+  FileDecisionAction,
+  FileDecisionScope,
+  FileReviewBlockReason,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/**
+ * Why an `"unavailable"` file cannot be reviewed — the honest per-file cause the
+ * runner records on `CapturedFileChange.blocked_reason` (design doc 15).
+ *
+ * - `"secret"` — the path looks like a secret; the bytes were deliberately never
+ *   captured (there is nothing to review, by design).
+ * - `"size"` — the diff was captured but its bodies were dropped to keep the
+ *   persisted status under its size limit.
+ * - `"unknown"` — incomplete for a reason the wire does not name (a defensive
+ *   catch-all; historical rows and future/unmapped causes land here).
+ */
+export type FileBlockReason = "secret" | "size" | "unknown";
+
+/**
+ * How completely a single captured file change can be reviewed before a decision
+ * is made — the classification that decides whether a file can be kept. A
+ * discriminated union so every consumer handles each case exhaustively and reads
+ * the block reason from one place (no "classify, then separately look up why").
+ *
+ * - `{ kind: "reviewable" }` — the full before/after diff is available; the
+ *   reviewer can see exactly what changed and Keep or Discard it.
+ * - `{ kind: "binary" }` — a binary file changed; there is no text diff to
+ *   review (the bytes are captured and flagged, but a byte diff is not
+ *   human-reviewable). Binary is proven by `FileContent.is_binary`, not by the
+ *   block reason.
+ * - `{ kind: "unavailable"; reason }` — the diff is not available to review at
+ *   all, with the honest {@link FileBlockReason} the runner recorded.
+ *
+ * Both `"binary"` and `"unavailable"` are non-reviewable: the file cannot be
+ * approved (kept), only discarded. This mirrors the server, which blocks
+ * approval of any change set that is not fully complete.
+ */
+export type FileReviewability =
+  | { readonly kind: "reviewable" }
+  | { readonly kind: "binary" }
+  | { readonly kind: "unavailable"; readonly reason: FileBlockReason };
+
+/**
+ * Classify a {@link CapturedFileChange} by how completely it can be reviewed,
+ * from the signals the runner authors onto the change (see the file-review
+ * producer in the runner's `shared/filereview`).
+ *
+ * The mapping is derived from three proto signals, in order:
+ *
+ * 1. `diff_complete === true` → `"reviewable"`. The change set can only be
+ *    `COMPLETE` when every file is complete, so a complete file is always
+ *    reviewable.
+ * 2. otherwise, a binary side (`before.is_binary` or `after.is_binary`) →
+ *    `"binary"`. The runner marks a git-tracked file incomplete precisely
+ *    because a side is binary (`diff_complete = !binary`); a CAS file carries
+ *    `is_binary` on its blob ref. `is_binary` is preserved when a large body is
+ *    offloaded from an inline value to a storage ref, so this holds regardless
+ *    of offload. Binary is therefore derived here, never duplicated onto the
+ *    block reason (doc 15).
+ * 3. otherwise → `"unavailable"` with the honest cause from
+ *    `blocked_reason`: `SECRET_WITHHELD → "secret"`, `SIZE_ELIDED → "size"`,
+ *    else `"unknown"`. Before doc 15 this bucket was cause-agnostic (the wire
+ *    could not prove secret-withheld vs size-dropped); the runner now records
+ *    the cause at capture time, so the UI can say *why* rather than only *that*
+ *    the diff is unavailable.
+ */
+export function fileReviewability(change: CapturedFileChange): FileReviewability {
+  if (change.diffComplete) return { kind: "reviewable" };
+  if (change.before?.isBinary || change.after?.isBinary) return { kind: "binary" };
+  return { kind: "unavailable", reason: blockReasonOf(change.blockedReason) };
+}
+
+/** Map the proto {@link FileReviewBlockReason} to the UI {@link FileBlockReason}. */
+function blockReasonOf(reason: FileReviewBlockReason): FileBlockReason {
+  switch (reason) {
+    case FileReviewBlockReason.SECRET_WITHHELD:
+      return "secret";
+    case FileReviewBlockReason.SIZE_ELIDED:
+      return "size";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * How completely a whole {@link FileChangeSet} can be reviewed — the set-level
+ * sibling of {@link FileReviewability} that decides whether the set can be kept
+ * in one action. Drives the card's bulk affordance and keeps headless builders
+ * on the same classification.
+ *
+ * - `"complete"` — every file is reviewable; the set can be approved as-is.
+ * - `"binary-only"` — the set's ONLY blocker is binary files (every non-binary
+ *   file is fully reviewable). No text diff for the binaries, but their exact
+ *   bytes are captured and reconcilable, so the whole set can be KEPT in one
+ *   acknowledged action ("Keep all"). Includes mixed sets (text edits + images).
+ * - `"blocked"` — at least one file is unavailable to review with no keepable
+ *   bytes (secret-withheld / size-elided / uncapturable), so the set cannot be
+ *   approved at once; it must be resolved per file.
+ */
+export type ChangeSetReviewability = "complete" | "binary-only" | "blocked";
+
+/**
+ * Classify a {@link FileChangeSet} from its server-derived `diff_completeness`
+ * rollup (the field exists precisely so clients need not re-fold the per-file
+ * signals). The runner and the size backstop both derive that value from the
+ * same rule the backend gate re-checks, so this classification, the per-file
+ * {@link fileReviewability} fold, and the server gate agree by construction.
+ */
+export function changeSetReviewability(set: FileChangeSet): ChangeSetReviewability {
+  switch (set.diffCompleteness) {
+    case DiffCompleteness.COMPLETE:
+      return "complete";
+    case DiffCompleteness.BINARY_SUMMARY_ONLY:
+      return "binary-only";
+    default:
+      return "blocked";
+  }
+}
+
+/**
+ * Each file's EFFECTIVE verdict for a settled set, folding the decisions the
+ * way the runner reconcile does (most-specific-wins): the last CHANGE_SET
+ * decision is the baseline for every file, and a later-or-earlier FILE decision
+ * overrides it for that file (FILE > CHANGE_SET regardless of ledger order;
+ * within a scope, last write wins).
+ *
+ * This is the fold for DISPLAYING history — a set decided via "Keep all"
+ * correctly reads every file as kept. The interactive per-file selected state
+ * deliberately uses the FILE-only fold instead (a CHANGE_SET decision cannot
+ * coexist with an open review, so it never pre-selects anything there).
+ */
+export function deriveEffectiveVerdicts(
+  set: FileChangeSet,
+): ReadonlyMap<string, FileDecisionAction> {
+  let bulk: FileDecisionAction | null = null;
+  const byFileId = new Map<string, FileDecisionAction>();
+  for (const d of set.decisions as readonly FileDecision[]) {
+    if (d.scope === FileDecisionScope.CHANGE_SET) bulk = d.action;
+    else if (d.scope === FileDecisionScope.FILE && d.fileChangeId) {
+      byFileId.set(d.fileChangeId, d.action);
+    }
+  }
+  const effective = new Map<string, FileDecisionAction>();
+  for (const c of set.changes) {
+    const verdict = byFileId.get(c.id) ?? bulk;
+    if (verdict != null) effective.set(c.id, verdict);
+  }
+  return effective;
+}
+
+/**
+ * The captured change a transcript row's file path refers to, or `null`. The
+ * row's path may be absolute (harness tool args) while captured paths are
+ * workspace-root-relative, so the match accepts an exact match or a
+ * `/`-boundary suffix. Presentation-only — never a correlation key.
+ */
+export function changeForRowPath(
+  set: FileChangeSet,
+  rowPath: string,
+): CapturedFileChange | null {
+  if (!rowPath) return null;
+  const normalized = rowPath.replace(/\\/g, "/");
+  for (const c of set.changes) {
+    const path = c.pathAfter || c.pathBefore;
+    if (path && (normalized === path || normalized.endsWith(`/${path}`))) {
+      return c;
+    }
+  }
+  return null;
+}
+
+/**
+ * The review state a stamped transcript row should badge — how this file edit
+ * stands in its change set's review lifecycle. `null` means "show no badge",
+ * chosen over guessing: a missing set (not yet projected), a CAPTURING set, or
+ * a row whose file is absent from the set (its edit was superseded or fully
+ * reverted within the turn) renders unbadged, never mislabeled.
+ *
+ * - `"pending"` — the set is AWAITING_REVIEW; this edit's net result is on the
+ *   decision surface now.
+ * - `"kept"` / `"discarded"` — the set is decided/reconciled and this file's
+ *   effective verdict is known ({@link deriveEffectiveVerdicts}).
+ * - `"failed"` — the set's reconcile failed; the workspace outcome for this
+ *   edit is not the reviewed one.
+ */
+export type FileReviewRowState = "pending" | "kept" | "discarded" | "failed";
+
+export function fileReviewRowState(
+  set: FileChangeSet | undefined,
+  rowPath: string | null,
+): FileReviewRowState | null {
+  if (!set) return null;
+  switch (set.status) {
+    case FileChangeSetStatus.AWAITING_REVIEW:
+      return "pending";
+    case FileChangeSetStatus.FAILED:
+      return "failed";
+    case FileChangeSetStatus.DECIDED:
+    case FileChangeSetStatus.RECONCILED: {
+      if (!rowPath) return null;
+      const change = changeForRowPath(set, rowPath);
+      if (!change) return null;
+      const verdict = deriveEffectiveVerdicts(set).get(change.id);
+      if (verdict === FileDecisionAction.APPROVE) return "kept";
+      if (verdict === FileDecisionAction.REJECT) return "discarded";
+      return null;
+    }
+    default:
+      return null;
+  }
+}

package/src/execution/index.ts

@@ -47,15 +47,38 @@ export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts";
 export { useArtifactContent } from "./useArtifactContent";
 export type { UseArtifactContentReturn } from "./useArtifactContent";
 
+export { useArtifactDownloadUrl } from "./useArtifactDownloadUrl";
+export type {
+  UseArtifactDownloadUrlReturn,
+  UseArtifactDownloadUrlOptions,
+} from "./useArtifactDownloadUrl";
+
+export { useArtifactDownload } from "./useArtifactDownload";
+export type { UseArtifactDownloadReturn } from "./useArtifactDownload";
+
+export { useToolOutputContent } from "./useToolOutputContent";
+export type {
+  UseToolOutputContentReturn,
+  ToolOutputRefLike,
+} from "./useToolOutputContent";
+
+export { useFileChangeContent, execIdFromStorageKey } from "./useFileChangeContent";
+export type { UseFileChangeContentReturn } from "./useFileChangeContent";
+
 export { useWorkspaceWriteBacks } from "./useWorkspaceWriteBacks";
 export type { UseWorkspaceWriteBacksReturn } from "./useWorkspaceWriteBacks";
 
 export { WriteBackCard } from "./WriteBackCard";
 export type { WriteBackCardProps } from "./WriteBackCard";
 
+export { FileChangesView, FileChangeDiff } from "./FileChangesView";
+export type { FileChangesViewProps, FileChangeDiffProps } from "./FileChangesView";
+
+export { EmptyChangeNotice } from "./EmptyChangeNotice";
+export type { EmptyChangeNoticeProps, EmptyChangeKind } from "./EmptyChangeNotice";
+
 export {
   isTextArtifact,
-  isArtifactExpired,
   formatArtifactSize,
   getArtifactExtension,
   getFileExtension,
@@ -75,9 +98,17 @@ export type { SetupProgressProps } from "./SetupProgress";
 export { ToolCallGroup } from "./ToolCallGroup";
 export type { ToolCallGroupProps } from "./ToolCallGroup";
 
+export { ToolRunGroup } from "./ToolRunGroup";
+export type { ToolRunGroupProps } from "./ToolRunGroup";
+
+export { segmentToolCalls } from "./segment-tool-calls";
+export type { ToolSegment } from "./segment-tool-calls";
+
 export { ToolCallDetail, formatDuration } from "./ToolCallDetail";
 export type { ToolCallDetailProps } from "./ToolCallDetail";
 
+export { describeApprovalPolicySource } from "./approval-provenance";
+
 export { McpToolDetail, McpArgsView, McpMetadataRow, parseMcpResult } from "./McpToolDetail";
 export type {
   McpToolDetailProps,
@@ -91,6 +122,9 @@ export type { ToolArgsViewProps } from "./ToolArgsView";
 export { ResultView, summarizeResultView } from "./ResultView";
 export type { ResultViewProps } from "./ResultView";
 
+export { TerminalSession } from "./TerminalSession";
+export type { TerminalSessionProps } from "./TerminalSession";
+
 export {
   useToolPresentation,
   registerToolPresenter,
@@ -145,12 +179,56 @@ export {
 } from "./TodoList";
 export type { TodoListProps } from "./TodoList";
 
+export { TodoCard } from "./TodoCard";
+export type { TodoCardProps } from "./TodoCard";
+
 
 export { useSubmitApproval } from "./useSubmitApproval";
 export type { UseSubmitApprovalReturn } from "./useSubmitApproval";
 
-export { ApprovalCard } from "./ApprovalCard";
-export type { ApprovalCardProps } from "./ApprovalCard";
+export { useFileReview, fileDecisionKey } from "./useFileReview";
+export type { UseFileReviewReturn, FileDecisionOptions } from "./useFileReview";
+
+export {
+  fileReviewability,
+  changeSetReviewability,
+  deriveEffectiveVerdicts,
+  changeForRowPath,
+  fileReviewRowState,
+} from "./file-review-status";
+export type {
+  FileReviewability,
+  FileBlockReason,
+  ChangeSetReviewability,
+  FileReviewRowState,
+} from "./file-review-status";
+
+// Settled/historical file-review display: the ledger fold + its read seam +
+// the display-projection adapter, re-exported from @stigmer/sdk (pure, shared).
+export {
+  foldFileReviewEventStream,
+  displayFileChangeSets,
+  toDisplayFileChange,
+} from "@stigmer/sdk";
+
+export { ApprovalCard, ApprovalCardHeader, ApprovalCardBody } from "./ApprovalCard";
+export type {
+  ApprovalCardProps,
+  ApprovalCardHeaderProps,
+  ApprovalCardBodyProps,
+} from "./ApprovalCard";
+
+export { FileReviewCard } from "./FileReviewCard";
+export type { FileReviewCardProps } from "./FileReviewCard";
+
+export { FileReviewDock } from "./FileReviewDock";
+export type { FileReviewDockProps } from "./FileReviewDock";
+
+export { ApprovalContext, useApproval } from "./ApprovalContext";
+export type { ApprovalContextValue, UseApprovalResult } from "./ApprovalContext";
+
+export { FileReviewContext, useFileReviewRowState } from "./FileReviewContext";
+export type { FileReviewContextValue } from "./FileReviewContext";
 
 export { ArtifactCard } from "./ArtifactCard";
 export type { ArtifactCardProps } from "./ArtifactCard";
@@ -175,8 +253,10 @@ export {
   extractPrimaryArg,
   extractPrimaryArgFromPreview,
   humanizeToolName,
+  defaultDisclosureForCategory,
+  isRunGroupableCategory,
 } from "./tool-categories";
-export type { ToolCategory, ToolCategoryInfo } from "./tool-categories";
+export type { ToolCategory, ToolCategoryInfo, ToolDisclosure } from "./tool-categories";
 
 export { FilePathLink } from "./FilePathLink";
 export type { FilePathLinkProps } from "./FilePathLink";

package/src/execution/segment-tool-calls.ts

@@ -0,0 +1,101 @@
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { resolveToolCategoryFromCall } from "./tool-categories";
+import type { ToolCategory } from "./tool-categories";
+import { resolveRunGroupable } from "./tool-presenter";
+
+/**
+ * Minimum number of consecutive same-category groupable calls before they fold
+ * into a chip. A lone groupable call (e.g. a single `Read foo.ts`) reads better
+ * as its own row than as a one-item "Read 1 file" chip, so grouping only kicks
+ * in at two or more.
+ */
+const MIN_RUN_LENGTH = 2;
+
+/**
+ * One renderable unit of a turn's tool activity.
+ *
+ * - `row` — a single tool call rendered as a persistent timeline row.
+ * - `run` — a maximal run of >= {@link MIN_RUN_LENGTH} consecutive low-signal
+ *   same-category calls (e.g. reads), folded into one collapsible chip.
+ */
+export type ToolSegment =
+  | { readonly kind: "row"; readonly toolCall: ToolCall; readonly key: string }
+  | {
+      readonly kind: "run";
+      readonly category: ToolCategory;
+      readonly toolCalls: readonly ToolCall[];
+      readonly key: string;
+    };
+
+/** Stable key for a single tool-call row (mirrors the prior group keying). */
+function rowKey(toolCall: ToolCall): string {
+  return toolCall.id || toolCall.name;
+}
+
+/**
+ * Partitions a turn's tool calls into a chronological sequence of {@link
+ * ToolSegment}s: maximal runs of consecutive low-signal same-category calls
+ * (read / list / search) fold into one `run` chip, while every other call —
+ * and any groupable call that has no same-kind neighbour — stays a persistent
+ * `row`.
+ *
+ * This is the layout pass behind the "persistent-row timeline": instead of
+ * hiding a whole turn behind one collapse, only repetitive noise is compressed,
+ * and high-signal rows (edits, shell, MCP, sub-agents) always remain visible.
+ * Chronology is preserved — a run never reorders calls, and an interleaving of
+ * categories (read, search, read) yields three separate segments, not one.
+ *
+ * Pure and dependency-light so it can be unit-tested exhaustively and memoized
+ * by the caller; groupability is resolved through {@link resolveRunGroupable},
+ * so a consumer's registry override is honoured here exactly as in the
+ * component layer.
+ *
+ * @example
+ * ```ts
+ * // read, read, read, edit  ->  [run(read x3), row(edit)]
+ * // read, search, read      ->  [row(read), row(search), row(read)]
+ * const segments = segmentToolCalls(message.toolCalls);
+ * ```
+ */
+export function segmentToolCalls(
+  toolCalls: readonly ToolCall[],
+): ToolSegment[] {
+  const segments: ToolSegment[] = [];
+
+  // Resolve category + groupability once per call so the scan below is a cheap
+  // index walk rather than repeated kind resolution.
+  const categories = toolCalls.map(
+    (tc) => resolveToolCategoryFromCall(tc).category,
+  );
+  const groupable = toolCalls.map((tc) => resolveRunGroupable(tc));
+
+  let i = 0;
+  while (i < toolCalls.length) {
+    const category = categories[i];
+
+    if (groupable[i]) {
+      // Extend the run while the next call is the same groupable category.
+      let j = i + 1;
+      while (j < toolCalls.length && groupable[j] && categories[j] === category) {
+        j++;
+      }
+
+      if (j - i >= MIN_RUN_LENGTH) {
+        const run = toolCalls.slice(i, j);
+        segments.push({
+          kind: "run",
+          category,
+          toolCalls: run,
+          key: `run-${category}-${rowKey(run[0])}`,
+        });
+        i = j;
+        continue;
+      }
+    }
+
+    segments.push({ kind: "row", toolCall: toolCalls[i], key: rowKey(toolCalls[i]) });
+    i++;
+  }
+
+  return segments;
+}