@stigmer/ink 3.1.1 → 3.1.3

package/src/components/MessageThread.tsx

@@ -9,17 +9,25 @@ import type {
 import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
 import {
   ApprovalAction,
   ExecutionPhase,
+  FileChangeSetStatus,
   MessageType,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { isTerminalPhase } from "@stigmer/react";
+import {
+  isTerminalPhase,
+  FileReviewContext,
+  type FileReviewContextValue,
+} from "@stigmer/react";
+import { displayFileChangeSets } from "@stigmer/sdk";
 import { MessageEntry } from "./MessageEntry.js";
 import { ToolCallGroup } from "./ToolCallGroup.js";
 import { SubAgentBlock } from "./SubAgentBlock.js";
 import { ExecutionProgress } from "./ExecutionProgress.js";
 import { ApprovalPrompt } from "./ApprovalPrompt.js";
+import { FileReviewRecord } from "./FileReviewRecord.js";
 
 /** Props for {@link MessageThread}. */
 export interface MessageThreadProps {
@@ -38,6 +46,14 @@ export interface MessageThreadProps {
   readonly submittingApprovalIds?: ReadonlySet<string>;
   /** Whether tool call groups should be rendered in expanded mode. Toggled via Ctrl+O. */
   readonly expandToolCalls?: boolean;
+  /**
+   * Whether to render a read-only settled record for each decided/reconciled/
+   * failed change set (the terminal analogue of the web's in-thread record,
+   * DD-27 D2). Off by default so bare consumers stay minimal; `SessionView`
+   * opts in. Pending (AWAITING_REVIEW) sets are never records here — their
+   * decision surface is the docked `FileReviewPrompt`.
+   */
+  readonly showFileReviewRecords?: boolean;
 }
 
 type ThreadItem =
@@ -46,71 +62,137 @@ type ThreadItem =
   | { readonly kind: "sub-agent"; readonly subAgent: SubAgentExecution; readonly key: string }
   | { readonly kind: "phase"; readonly phase: ExecutionPhase; readonly key: string }
   | { readonly kind: "pending-message"; readonly content: string; readonly key: string }
+  | { readonly kind: "file-review-record"; readonly set: FileChangeSet; readonly key: string }
   | { readonly kind: "approval"; readonly pendingApproval: PendingApproval; readonly key: string };
 
+/** A change set is "settled" once a decision has been folded (or reconcile failed). */
+function isSettledSet(status: FileChangeSetStatus): boolean {
+  return (
+    status === FileChangeSetStatus.DECIDED ||
+    status === FileChangeSetStatus.RECONCILED ||
+    status === FileChangeSetStatus.FAILED
+  );
+}
+
+/**
+ * Builds the observational thread items for a single execution: the spec
+ * message, each AI/human message, tool-call groups, and sub-agent blocks —
+ * plus (when `includeFileReviewRecords`) a read-only settled record appended at
+ * the execution's tail for each decided/reconciled/failed change set.
+ */
+function buildExecutionSegment(
+  exec: AgentExecution,
+  ei: number,
+  includeFileReviewRecords: boolean,
+): ThreadItem[] {
+  const seg: ThreadItem[] = [];
+  const messages = exec.status?.messages ?? [];
+  const subAgents = exec.status?.subAgentExecutions ?? [];
+
+  const specMessage = exec.spec?.message;
+  if (specMessage && specMessage !== "execute") {
+    const humanMsg = create(AgentMessageSchema);
+    humanMsg.type = MessageType.MESSAGE_HUMAN;
+    humanMsg.content = specMessage;
+    seg.push({ kind: "message", message: humanMsg, key: `e${ei}-spec` });
+  }
+
+  for (let mi = 0; mi < messages.length; mi++) {
+    const msg = messages[mi];
+    if (msg.type === MessageType.MESSAGE_TOOL) continue;
+
+    const isEmptyAi = msg.type === MessageType.MESSAGE_AI && !msg.content.trim();
+
+    if (!isEmptyAi) {
+      seg.push({ kind: "message", message: msg, key: `e${ei}-m${mi}` });
+    }
+
+    if (msg.type === MessageType.MESSAGE_AI && msg.toolCalls.length > 0) {
+      // Split tool calls: "task" tools become sub-agent blocks,
+      // everything else goes into a regular tool group.
+      const regularTools = msg.toolCalls.filter((tc) => tc.name !== "task");
+      const taskTools = msg.toolCalls.filter((tc) => tc.name === "task");
+
+      if (regularTools.length > 0) {
+        seg.push({
+          kind: "tool-group",
+          toolCalls: regularTools,
+          key: `e${ei}-m${mi}-tc`,
+        });
+      }
+
+      for (let ti = 0; ti < taskTools.length; ti++) {
+        const matchedSub = subAgents.find((sa) => sa.id === taskTools[ti].id);
+        if (matchedSub) {
+          seg.push({
+            kind: "sub-agent",
+            subAgent: matchedSub,
+            key: `e${ei}-m${mi}-sa-${ti}`,
+          });
+        }
+      }
+    }
+  }
+
+  if (includeFileReviewRecords) {
+    // `displayFileChangeSets` returns the server projection for a live
+    // execution and folds the durable ledger for a terminal one, so a settled
+    // record renders for both. Appended at the segment tail (the terminal
+    // analogue of the web's last-stamped-row anchor); this is the only trace a
+    // shell-made set — which stamps no rows — leaves behind (DD-27 D2).
+    for (const set of displayFileChangeSets(exec.status)) {
+      if (!isSettledSet(set.status) || set.changes.length === 0) continue;
+      seg.push({ kind: "file-review-record", set, key: `e${ei}-frr-${set.id}` });
+    }
+  }
+
+  return seg;
+}
+
+/**
+ * Builds the full thread item list and the index at which the live region
+ * begins (`liveStart`).
+ *
+ * The split is by execution identity, not a trailing count: every completed
+ * execution's items are immutable history (safe for ink's append-only
+ * `<Static>`), while the active execution's items — plus the trailing transient
+ * items (phase, approvals, optimistic pending message) — stay live so their
+ * review badges can transition and the optimistic message can be cleared
+ * without shrinking the Static array.
+ */
 function buildThreadItems(
   executions: readonly AgentExecution[],
   activeStreamExecution: AgentExecution | null | undefined,
   pendingUserMessage: string | null | undefined,
   includeApprovals: boolean,
-): ThreadItem[] {
+  includeFileReviewRecords: boolean,
+): { items: ThreadItem[]; liveStart: number } {
   const items: ThreadItem[] = [];
   const allExecutions = activeStreamExecution
     ? [...executions, activeStreamExecution]
     : executions;
 
-  for (let ei = 0; ei < allExecutions.length; ei++) {
-    const exec = allExecutions[ei];
-    const messages = exec.status?.messages ?? [];
-    const subAgents = exec.status?.subAgentExecutions ?? [];
+  // Boundary between immutable history and the live region. When there is an
+  // active execution, it is the item count right before that execution's
+  // segment; otherwise the transient tail (below) is the only live region.
+  let liveStart = 0;
+  let liveStartSet = false;
 
-    const specMessage = exec.spec?.message;
-    if (specMessage && specMessage !== "execute") {
-      const humanMsg = create(AgentMessageSchema);
-      humanMsg.type = MessageType.MESSAGE_HUMAN;
-      humanMsg.content = specMessage;
-      items.push({ kind: "message", message: humanMsg, key: `e${ei}-spec` });
+  for (let ei = 0; ei < allExecutions.length; ei++) {
+    if (activeStreamExecution && ei === executions.length) {
+      liveStart = items.length;
+      liveStartSet = true;
     }
+    items.push(...buildExecutionSegment(allExecutions[ei], ei, includeFileReviewRecords));
+  }
 
-    for (let mi = 0; mi < messages.length; mi++) {
-      const msg = messages[mi];
-      if (msg.type === MessageType.MESSAGE_TOOL) continue;
-
-      const isEmptyAi =
-        msg.type === MessageType.MESSAGE_AI && !msg.content.trim();
-
-      if (!isEmptyAi) {
-        items.push({ kind: "message", message: msg, key: `e${ei}-m${mi}` });
-      }
-
-      if (msg.type === MessageType.MESSAGE_AI && msg.toolCalls.length > 0) {
-        // Split tool calls: "task" tools become sub-agent blocks,
-        // everything else goes into a regular tool group.
-        const regularTools = msg.toolCalls.filter((tc) => tc.name !== "task");
-        const taskTools = msg.toolCalls.filter((tc) => tc.name === "task");
-
-        if (regularTools.length > 0) {
-          items.push({
-            kind: "tool-group",
-            toolCalls: regularTools,
-            key: `e${ei}-m${mi}-tc`,
-          });
-        }
-
-        for (let ti = 0; ti < taskTools.length; ti++) {
-          const matchedSub = subAgents.find((sa) => sa.id === taskTools[ti].id);
-          if (matchedSub) {
-            items.push({
-              kind: "sub-agent",
-              subAgent: matchedSub,
-              key: `e${ei}-m${mi}-sa-${ti}`,
-            });
-          }
-        }
-      }
-    }
+  if (!liveStartSet) {
+    // No active execution: every execution body is history; only the transient
+    // tail appended below (e.g. an optimistic pending message) stays live.
+    liveStart = items.length;
   }
 
+  // --- Transient tail (always live) ---
   const lastExec = allExecutions[allExecutions.length - 1];
   const lastPhase =
     lastExec?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
@@ -144,20 +226,48 @@ function buildThreadItems(
     }
   }
 
-  return items;
+  return { items, liveStart };
+}
+
+/**
+ * Builds the id→change-set map that backs the file-review row badges, folding
+ * every execution's change sets (via `displayFileChangeSets`, which reads the
+ * live projection or the durable ledger). The active stream wins on an id
+ * collision so a live decision is reflected before it is persisted.
+ */
+function buildChangeSetsById(
+  executions: readonly AgentExecution[],
+  activeStreamExecution: AgentExecution | null | undefined,
+): FileReviewContextValue {
+  const changeSetsById = new Map<string, FileChangeSet>();
+  for (const exec of executions) {
+    for (const set of displayFileChangeSets(exec.status)) {
+      changeSetsById.set(set.id, set);
+    }
+  }
+  if (activeStreamExecution) {
+    for (const set of displayFileChangeSets(activeStreamExecution.status)) {
+      changeSetsById.set(set.id, set);
+    }
+  }
+  return { changeSetsById };
 }
 
 /**
  * Renders a continuous conversation thread from one or more
  * `AgentExecution` snapshots in the terminal.
  *
- * Composes {@link MessageEntry}, {@link ToolCallGroup},
- * {@link ExecutionProgress}, and {@link ApprovalPrompt} into a
- * scrolling terminal log.
+ * Composes {@link MessageEntry}, {@link ToolCallGroup}, {@link SubAgentBlock},
+ * {@link ExecutionProgress}, {@link ApprovalPrompt}, and (for settled change
+ * sets) {@link FileReviewRecord} into a scrolling terminal log.
  *
- * Historical items are rendered via Ink's `<Static>` component so
- * they are written once and don't re-render, keeping terminal
- * output efficient for long conversations.
+ * Completed executions are rendered via Ink's `<Static>` component so they are
+ * written once and don't re-render, keeping terminal output efficient for long
+ * conversations. The active execution renders live so its file-review row
+ * badges transition (Pending review → Kept/Discarded) in place, then freeze
+ * into `<Static>` when the execution reaches a terminal phase. The thread is
+ * wrapped in a `FileReviewContext` provider so every {@link ToolCallItem}
+ * can badge its stamped edit rows.
  */
 export function MessageThread({
   executions,
@@ -166,65 +276,56 @@ export function MessageThread({
   onApprovalSubmit,
   submittingApprovalIds,
   expandToolCalls = false,
+  showFileReviewRecords = false,
 }: MessageThreadProps) {
   const includeApprovals = onApprovalSubmit != null;
-  const items = useMemo(
+  const { items, liveStart } = useMemo(
     () =>
       buildThreadItems(
         executions,
         activeStreamExecution,
         pendingUserMessage,
         includeApprovals,
+        showFileReviewRecords,
       ),
-    [executions, activeStreamExecution, pendingUserMessage, includeApprovals],
+    [
+      executions,
+      activeStreamExecution,
+      pendingUserMessage,
+      includeApprovals,
+      showFileReviewRecords,
+    ],
+  );
+
+  const fileReviewContext = useMemo(
+    () => buildChangeSetsById(executions, activeStreamExecution),
+    [executions, activeStreamExecution],
   );
 
-  const historyItems = activeStreamExecution ? items.slice(0, -getActiveCount(items)) : items;
-  const liveItems = activeStreamExecution ? items.slice(items.length - getActiveCount(items)) : [];
+  const historyItems = items.slice(0, liveStart);
+  const liveItems = items.slice(liveStart);
 
   return (
-    <Box flexDirection="column">
-      <Static items={historyItems}>
-        {(item) => (
+    <FileReviewContext.Provider value={fileReviewContext}>
+      <Box flexDirection="column">
+        <Static items={historyItems}>
+          {(item) => (
+            <Box key={item.key} flexDirection="column" marginBottom={1}>
+              {renderItem(item, onApprovalSubmit, submittingApprovalIds, expandToolCalls)}
+            </Box>
+          )}
+        </Static>
+
+        {liveItems.map((item) => (
           <Box key={item.key} flexDirection="column" marginBottom={1}>
             {renderItem(item, onApprovalSubmit, submittingApprovalIds, expandToolCalls)}
           </Box>
-        )}
-      </Static>
-
-      {liveItems.map((item) => (
-        <Box key={item.key} flexDirection="column" marginBottom={1}>
-          {renderItem(item, onApprovalSubmit, submittingApprovalIds, expandToolCalls)}
-        </Box>
-      ))}
-    </Box>
+        ))}
+      </Box>
+    </FileReviewContext.Provider>
   );
 }
 
-function getActiveCount(items: ThreadItem[]): number {
-  let count = 0;
-  for (let i = items.length - 1; i >= 0; i--) {
-    const item = items[i];
-    if (
-      item.kind === "approval" ||
-      item.kind === "pending-message" ||
-      item.kind === "phase"
-    ) {
-      count++;
-    } else if (
-      item.kind === "message" &&
-      item.message.type === MessageType.MESSAGE_AI &&
-      item.message.isStreaming
-    ) {
-      count++;
-      break;
-    } else {
-      break;
-    }
-  }
-  return count;
-}
-
 function renderItem(
   item: ThreadItem,
   onApprovalSubmit?: (toolCallId: string, action: ApprovalAction) => void,
@@ -240,6 +341,8 @@ function renderItem(
       return <SubAgentBlock subAgent={item.subAgent} defaultExpanded={expandToolCalls} />;
     case "phase":
       return <ExecutionProgress phase={item.phase} />;
+    case "file-review-record":
+      return <FileReviewRecord fileChangeSet={item.set} />;
     case "approval":
       return onApprovalSubmit ? (
         <ApprovalPrompt

package/src/components/ToolCallGroup.tsx

@@ -1,7 +1,13 @@
-import React, { useState } from "react";
+import React, { useContext, useState } from "react";
 import { Box, Text, useInput } from "ink";
 import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  FileReviewContext,
+  fileReviewRowState,
+  extractPrimaryArg,
+  type FileReviewRowState,
+} from "@stigmer/react";
 import { ToolCallItem } from "./ToolCallItem.js";
 
 /** Props for {@link ToolCallGroup}. */
@@ -42,6 +48,45 @@ const STATUS_STYLE: Record<AggregateStatus, { symbol: string; color?: string }>
   pending: { symbol: "○" },
 };
 
+/**
+ * A compact file-review cue for the collapsed summary line, so a pending edit is
+ * visible without expanding the group. Folds the group's stamped edit rows via
+ * the same pure {@link fileReviewRowState} the per-row badges use, reading the
+ * change sets from {@link FileReviewContext}. Pending takes precedence (it is
+ * the actionable state); otherwise a settled group shows its kept/discarded
+ * tally. Returns `null` when no row in the group is stamped.
+ */
+function useReviewCue(
+  toolCalls: readonly ToolCall[],
+): { readonly label: string; readonly color: string } | null {
+  const { changeSetsById } = useContext(FileReviewContext);
+  const counts: Record<FileReviewRowState, number> = {
+    pending: 0,
+    kept: 0,
+    discarded: 0,
+    failed: 0,
+  };
+  for (const tc of toolCalls) {
+    if (!tc.fileChangeSetId) continue;
+    const state = fileReviewRowState(
+      changeSetsById.get(tc.fileChangeSetId),
+      extractPrimaryArg(tc),
+    );
+    if (state) counts[state]++;
+  }
+  if (counts.pending > 0) {
+    return { label: `${counts.pending} pending review`, color: "yellow" };
+  }
+  if (counts.failed > 0) {
+    return { label: `${counts.failed} review failed`, color: "red" };
+  }
+  const settled: string[] = [];
+  if (counts.kept > 0) settled.push(`${counts.kept} kept`);
+  if (counts.discarded > 0) settled.push(`${counts.discarded} discarded`);
+  if (settled.length > 0) return { label: settled.join(" · "), color: "gray" };
+  return null;
+}
+
 /**
  * Renders a collapsible group of tool calls with an aggregate status.
  *
@@ -58,6 +103,7 @@ export function ToolCallGroup({
   const [expanded, setExpanded] = useState(defaultExpanded);
   const status = deriveAggregateStatus(toolCalls);
   const style = STATUS_STYLE[status];
+  const reviewCue = useReviewCue(toolCalls);
 
   useInput(
     (_input, key) => {
@@ -79,6 +125,9 @@ export function ToolCallGroup({
         <Text color={style.color}>{style.symbol}</Text>
         <Text dimColor>{expanded ? "▼" : "▶"}</Text>
         <Text>{summary}</Text>
+        {reviewCue && (
+          <Text color={reviewCue.color}>· {reviewCue.label}</Text>
+        )}
       </Box>
       {expanded && (
         <Box flexDirection="column" paddingLeft={2} marginTop={1}>

package/src/components/ToolCallItem.tsx

@@ -4,6 +4,11 @@ import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { ToolKind, resolveToolKind, normalizeToolResult } from "@stigmer/sdk";
 import type { ToolResultView } from "@stigmer/sdk";
+import {
+  extractPrimaryArg,
+  useFileReviewRowState,
+  type FileReviewRowState,
+} from "@stigmer/react";
 
 /** Props for {@link ToolCallItem}. */
 export interface ToolCallItemProps {
@@ -37,6 +42,15 @@ const KIND_LABEL: Partial<Record<ToolKind, string>> = {
   [ToolKind.SUBAGENT]: "Sub-agent",
 };
 
+// File-review row badges, mirroring the web console's per-row badge labels and
+// tones. Keyed by the shared `fileReviewRowState` classification.
+const REVIEW_BADGE: Record<FileReviewRowState, { label: string; color: string }> = {
+  pending: { label: "Pending review", color: "yellow" },
+  kept: { label: "Kept", color: "green" },
+  discarded: { label: "Discarded", color: "red" },
+  failed: { label: "Review failed", color: "red" },
+};
+
 /**
  * Renders a single tool call with a status indicator, label, and an optional
  * expanded result. Labels and results come from the shared `@stigmer/sdk` view
@@ -51,6 +65,16 @@ export function ToolCallItem({ toolCall, expanded = false }: ToolCallItemProps)
   const view = normalizeToolResult(toolCall);
   const resultText = expanded ? describeResultView(view) : null;
 
+  // A flowed file edit stamped with its change set id badges the set's live
+  // review state right on the row (the observational record stays in place; the
+  // decision surface is the docked FileReviewPrompt). Null for unstamped rows
+  // and honest-degradation cases (missing/capturing set, superseded edit).
+  const reviewState = useFileReviewRowState(
+    toolCall.fileChangeSetId,
+    extractPrimaryArg(toolCall),
+  );
+  const reviewBadge = reviewState ? REVIEW_BADGE[reviewState] : null;
+
   return (
     <Box flexDirection="column">
       <Box gap={1}>
@@ -59,6 +83,7 @@ export function ToolCallItem({ toolCall, expanded = false }: ToolCallItemProps)
         {toolCall.status === ToolCallStatus.TOOL_CALL_RUNNING && (
           <Text dimColor>running</Text>
         )}
+        {reviewBadge && <Text color={reviewBadge.color}>{reviewBadge.label}</Text>}
       </Box>
       {view.type === "error" ? (
         expanded && (

package/src/file-review.ts

@@ -0,0 +1,135 @@
+import type {
+  CapturedFileChange,
+  FileChangeProgressEntry,
+  FileChangeSet,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  FileChangeKind,
+  FileDecisionAction,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { deriveEffectiveVerdicts, fileReviewability } from "@stigmer/react";
+
+/**
+ * Single-letter badge for a file change's kind, matching the web review card:
+ * `A` added, `M` modified, `D` deleted, `R` renamed. A binary change reads as
+ * `M` — "binary" is a review-completeness property (from `FileContent.is_binary`
+ * via `fileReviewability`), not a distinct edit kind.
+ */
+export function kindLetter(kind: FileChangeKind): string {
+  switch (kind) {
+    case FileChangeKind.ADD:
+      return "A";
+    case FileChangeKind.DELETE:
+      return "D";
+    case FileChangeKind.RENAME:
+      return "R";
+    default:
+      return "M";
+  }
+}
+
+/**
+ * The one rename-aware path-display rule for the terminal, over the raw
+ * before/after/kind triple shared by every file-change shape (reviewable
+ * `CapturedFileChange` and slim `FileChangeProgressEntry` alike). Kept private
+ * and fed by the typed adapters below so the two surfaces can never grow
+ * divergent rename formatting.
+ */
+function displayChangePath(
+  pathBefore: string,
+  pathAfter: string,
+  kind: FileChangeKind,
+): string {
+  if (kind === FileChangeKind.RENAME && pathBefore && pathAfter) {
+    return `${pathBefore} → ${pathAfter}`;
+  }
+  return pathAfter || pathBefore;
+}
+
+/**
+ * The path to show for a reviewable change: the post-edit path, or the pre-edit
+ * path for a deletion. A rename shows `before → after` so both sides are visible.
+ */
+export function changeDisplayPath(change: CapturedFileChange): string {
+  return displayChangePath(change.pathBefore, change.pathAfter, change.kind);
+}
+
+/**
+ * The path to show for a mid-run progress entry (DD-32), using the same
+ * rename-aware rule as {@link changeDisplayPath}. The slim entry carries no
+ * bodies or digests, only the same before/after/kind triple, so the terminal
+ * renders its path identically to the reviewable surfaces.
+ */
+export function progressEntryDisplayPath(entry: FileChangeProgressEntry): string {
+  return displayChangePath(entry.pathBefore, entry.pathAfter, entry.kind);
+}
+
+/**
+ * The honest, one-line reason a change cannot be kept as-is, or `null` when it
+ * is fully reviewable. Mirrors the web card's per-file block-reason copy so the
+ * terminal reviewer sees the same explanation.
+ */
+export function blockReasonNote(change: CapturedFileChange): string | null {
+  const reviewability = fileReviewability(change);
+  switch (reviewability.kind) {
+    case "reviewable":
+      return null;
+    case "binary":
+      return "binary — no text diff; keep as-is or discard";
+    case "unavailable":
+      switch (reviewability.reason) {
+        case "secret":
+          return "contents withheld (looks like a secret) — discard only";
+        case "size":
+          return "diff too large to display — discard only";
+        default:
+          return "diff unavailable — discard only";
+      }
+  }
+}
+
+/** The effective per-file verdict counts for a settled change set. */
+export interface SettledCounts {
+  /** Files kept (effective verdict APPROVE). */
+  readonly kept: number;
+  /** Files discarded (effective verdict REJECT). */
+  readonly discarded: number;
+  /** Files with no effective verdict (neither kept nor discarded). */
+  readonly notReviewed: number;
+}
+
+/**
+ * Folds a settled change set's decisions into kept / discarded / not-reviewed
+ * counts, using the same `deriveEffectiveVerdicts` fold the web uses so a
+ * "Keep all" set correctly reads every file as kept.
+ */
+export function settledCounts(set: FileChangeSet): SettledCounts {
+  const verdicts = deriveEffectiveVerdicts(set);
+  let kept = 0;
+  let discarded = 0;
+  for (const change of set.changes) {
+    const verdict = verdicts.get(change.id);
+    if (verdict === FileDecisionAction.APPROVE) kept++;
+    else if (verdict === FileDecisionAction.REJECT) discarded++;
+  }
+  return {
+    kept,
+    discarded,
+    notReviewed: set.changes.length - kept - discarded,
+  };
+}
+
+/**
+ * A one-line summary of a settled change set's outcome, e.g. `2 kept · 1
+ * discarded`, or `3 files changed` when nothing was individually decided.
+ */
+export function settledSummary(set: FileChangeSet): string {
+  const { kept, discarded, notReviewed } = settledCounts(set);
+  const parts: string[] = [];
+  if (kept) parts.push(`${kept} kept`);
+  if (discarded) parts.push(`${discarded} discarded`);
+  if (notReviewed) parts.push(`${notReviewed} not reviewed`);
+  if (parts.length > 0) return parts.join(" · ");
+  const n = set.changes.length;
+  return `${n} file${n === 1 ? "" : "s"} changed`;
+}

package/src/index.ts

@@ -19,6 +19,23 @@ export { ToolCallGroup, type ToolCallGroupProps } from "./components/ToolCallGro
 export { SubAgentBlock, type SubAgentBlockProps } from "./components/SubAgentBlock.js";
 export { TodoList, type TodoListProps } from "./components/TodoList.js";
 export { ApprovalPrompt, type ApprovalPromptProps } from "./components/ApprovalPrompt.js";
+export { FileReviewPrompt, type FileReviewPromptProps } from "./components/FileReviewPrompt.js";
+export { FileReviewRecord, type FileReviewRecordProps } from "./components/FileReviewRecord.js";
+export {
+  FileChangeProgressBar,
+  type FileChangeProgressBarProps,
+} from "./components/FileChangeProgressBar.js";
+
+// File-review pure helpers (kind letters, paths, block reasons, settled counts)
+export {
+  kindLetter,
+  changeDisplayPath,
+  progressEntryDisplayPath,
+  blockReasonNote,
+  settledCounts,
+  settledSummary,
+  type SettledCounts,
+} from "./file-review.js";
 export { ExecutionProgress, type ExecutionProgressProps } from "./components/ExecutionProgress.js";
 export { FollowUpInput, type FollowUpInputProps } from "./components/FollowUpInput.js";
 export { UsageWidget, type UsageWidgetProps } from "./components/UsageWidget.js";