@stigmer/react 3.0.9-dev.20260616060535 → 3.1.1

package/src/execution/index.ts

@@ -1,102 +1,136 @@
-export { useCreateAgentExecution } from "./useCreateAgentExecution";
+export { useCreateAgentExecution } from "./useCreateAgentExecution.js";
 export type {
   CreateAgentExecutionInput,
   CreateAgentExecutionResult,
   UseCreateAgentExecutionReturn,
-} from "./useCreateAgentExecution";
+} from "./useCreateAgentExecution.js";
 
-export { isTerminalPhase } from "./execution-phases";
+export { isTerminalPhase } from "./execution-phases.js";
 
-export { useExecutionStream } from "./useExecutionStream";
-export type { UseExecutionStreamReturn } from "./useExecutionStream";
+export { useExecutionStream } from "./useExecutionStream.js";
+export type { UseExecutionStreamReturn } from "./useExecutionStream.js";
 
-export { useAgentExecutionActions } from "./useAgentExecutionActions";
+export { useAgentExecutionActions } from "./useAgentExecutionActions.js";
 export type {
   UseAgentExecutionActionsOptions,
   UseAgentExecutionActionsReturn,
-} from "./useAgentExecutionActions";
+} from "./useAgentExecutionActions.js";
 
-export { UsageWidget, formatCost, formatTokenCount } from "./UsageWidget";
-export type { UsageWidgetProps } from "./UsageWidget";
+export { UsageWidget, formatCost, formatTokenCount } from "./UsageWidget.js";
+export type { UsageWidgetProps } from "./UsageWidget.js";
 
-export { useContextWindow } from "./useContextWindow";
+export { useContextWindow } from "./useContextWindow.js";
 export type {
   ContextHealth,
   SummarizationEventView,
   UseContextWindowReturn,
-} from "./useContextWindow";
+} from "./useContextWindow.js";
 
-export { ContextGauge } from "./ContextGauge";
-export type { ContextGaugeProps } from "./ContextGauge";
+export { ContextGauge } from "./ContextGauge.js";
+export type { ContextGaugeProps } from "./ContextGauge.js";
 
-export { SummarizationBadge } from "./SummarizationBadge";
-export type { SummarizationBadgeProps } from "./SummarizationBadge";
+export { SummarizationBadge } from "./SummarizationBadge.js";
+export type { SummarizationBadgeProps } from "./SummarizationBadge.js";
 
-export { SummarizationCard } from "./SummarizationCard";
-export type { SummarizationCardProps } from "./SummarizationCard";
+export { SummarizationCard } from "./SummarizationCard.js";
+export type { SummarizationCardProps } from "./SummarizationCard.js";
 
-export { PlanCompletionCard } from "./PlanCompletionCard";
-export type { PlanCompletionCardProps } from "./PlanCompletionCard";
+export { PlanCompletionCard } from "./PlanCompletionCard.js";
+export type { PlanCompletionCardProps } from "./PlanCompletionCard.js";
 
-export { PlanArtifactCard } from "./PlanArtifactCard";
-export type { PlanArtifactCardProps } from "./PlanArtifactCard";
+export { PlanArtifactCard } from "./PlanArtifactCard.js";
+export type { PlanArtifactCardProps } from "./PlanArtifactCard.js";
 
-export { useExecutionArtifacts } from "./useExecutionArtifacts";
-export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts";
+export { useExecutionArtifacts } from "./useExecutionArtifacts.js";
+export type { UseExecutionArtifactsReturn } from "./useExecutionArtifacts.js";
 
-export { useArtifactContent } from "./useArtifactContent";
-export type { UseArtifactContentReturn } from "./useArtifactContent";
+export { useArtifactContent } from "./useArtifactContent.js";
+export type { UseArtifactContentReturn } from "./useArtifactContent.js";
 
-export { useWorkspaceWriteBacks } from "./useWorkspaceWriteBacks";
-export type { UseWorkspaceWriteBacksReturn } from "./useWorkspaceWriteBacks";
+export { useArtifactDownloadUrl } from "./useArtifactDownloadUrl.js";
+export type {
+  UseArtifactDownloadUrlReturn,
+  UseArtifactDownloadUrlOptions,
+} from "./useArtifactDownloadUrl.js";
+
+export { useArtifactDownload } from "./useArtifactDownload.js";
+export type { UseArtifactDownloadReturn } from "./useArtifactDownload.js";
+
+export { useToolOutputContent } from "./useToolOutputContent.js";
+export type {
+  UseToolOutputContentReturn,
+  ToolOutputRefLike,
+} from "./useToolOutputContent.js";
+
+export { useFileChangeContent, execIdFromStorageKey } from "./useFileChangeContent.js";
+export type { UseFileChangeContentReturn } from "./useFileChangeContent.js";
+
+export { useWorkspaceWriteBacks } from "./useWorkspaceWriteBacks.js";
+export type { UseWorkspaceWriteBacksReturn } from "./useWorkspaceWriteBacks.js";
 
-export { WriteBackCard } from "./WriteBackCard";
-export type { WriteBackCardProps } from "./WriteBackCard";
+export { WriteBackCard } from "./WriteBackCard.js";
+export type { WriteBackCardProps } from "./WriteBackCard.js";
+
+export { FileChangesView, FileChangeDiff } from "./FileChangesView.js";
+export type { FileChangesViewProps, FileChangeDiffProps } from "./FileChangesView.js";
+
+export { EmptyChangeNotice } from "./EmptyChangeNotice.js";
+export type { EmptyChangeNoticeProps, EmptyChangeKind } from "./EmptyChangeNotice.js";
 
 export {
   isTextArtifact,
-  isArtifactExpired,
   formatArtifactSize,
   getArtifactExtension,
   getFileExtension,
   getArtifactRenderMode,
-} from "./artifact-utils";
-export type { ArtifactRenderMode } from "./artifact-utils";
+} from "./artifact-utils.js";
+export type { ArtifactRenderMode } from "./artifact-utils.js";
+
+export { ExecutionPhaseBadge } from "./ExecutionPhaseBadge.js";
+export type { ExecutionPhaseBadgeProps } from "./ExecutionPhaseBadge.js";
 
-export { ExecutionPhaseBadge } from "./ExecutionPhaseBadge";
-export type { ExecutionPhaseBadgeProps } from "./ExecutionPhaseBadge";
+export { InteractionModeBadge } from "./InteractionModeBadge.js";
+export type { InteractionModeBadgeProps } from "./InteractionModeBadge.js";
 
-export { InteractionModeBadge } from "./InteractionModeBadge";
-export type { InteractionModeBadgeProps } from "./InteractionModeBadge";
+export { SetupProgress } from "./SetupProgress.js";
+export type { SetupProgressProps } from "./SetupProgress.js";
 
-export { SetupProgress } from "./SetupProgress";
-export type { SetupProgressProps } from "./SetupProgress";
+export { ToolCallGroup } from "./ToolCallGroup.js";
+export type { ToolCallGroupProps } from "./ToolCallGroup.js";
 
-export { ToolCallGroup } from "./ToolCallGroup";
-export type { ToolCallGroupProps } from "./ToolCallGroup";
+export { ToolRunGroup } from "./ToolRunGroup.js";
+export type { ToolRunGroupProps } from "./ToolRunGroup.js";
 
-export { ToolCallDetail, formatDuration } from "./ToolCallDetail";
-export type { ToolCallDetailProps } from "./ToolCallDetail";
+export { segmentToolCalls } from "./segment-tool-calls.js";
+export type { ToolSegment } from "./segment-tool-calls.js";
 
-export { McpToolDetail, McpArgsView, McpMetadataRow, parseMcpResult } from "./McpToolDetail";
+export { ToolCallDetail, formatDuration } from "./ToolCallDetail.js";
+export type { ToolCallDetailProps } from "./ToolCallDetail.js";
+
+export { describeApprovalPolicySource } from "./approval-provenance.js";
+
+export { McpToolDetail, McpArgsView, McpMetadataRow, parseMcpResult } from "./McpToolDetail.js";
 export type {
   McpToolDetailProps,
   McpArgsViewProps,
   McpMetadataRowProps,
-} from "./McpToolDetail";
+} from "./McpToolDetail.js";
+
+export { ToolArgsView } from "./ToolArgsView.js";
+export type { ToolArgsViewProps } from "./ToolArgsView.js";
 
-export { ToolArgsView } from "./ToolArgsView";
-export type { ToolArgsViewProps } from "./ToolArgsView";
+export { ResultView, summarizeResultView } from "./ResultView.js";
+export type { ResultViewProps } from "./ResultView.js";
 
-export { ResultView, summarizeResultView } from "./ResultView";
-export type { ResultViewProps } from "./ResultView";
+export { TerminalSession } from "./TerminalSession.js";
+export type { TerminalSessionProps } from "./TerminalSession.js";
 
 export {
   useToolPresentation,
   registerToolPresenter,
   getToolPresenter,
-} from "./tool-presenter";
-export type { ToolPresentation, ToolPresenter } from "./tool-presenter";
+} from "./tool-presenter.js";
+export type { ToolPresentation, ToolPresenter } from "./tool-presenter.js";
 
 export {
   CollapsibleCode,
@@ -109,63 +143,107 @@ export {
   formatResult,
   isScalar,
   humanizeArgKey,
-} from "./tool-rendering-primitives";
+} from "./tool-rendering-primitives.js";
 export type {
   CollapsibleCodeProps,
   CollapsiblePreProps,
   CollapsibleJsonBlockProps,
-} from "./tool-rendering-primitives";
+} from "./tool-rendering-primitives.js";
 
-export { ToolCallItem } from "./ToolCallItem";
-export type { ToolCallItemProps } from "./ToolCallItem";
+export { ToolCallItem } from "./ToolCallItem.js";
+export type { ToolCallItemProps } from "./ToolCallItem.js";
 
-export { SubAgentSection } from "./SubAgentSection";
-export type { SubAgentSectionProps } from "./SubAgentSection";
+export { SubAgentSection } from "./SubAgentSection.js";
+export type { SubAgentSectionProps } from "./SubAgentSection.js";
 
-export { MessageEntry } from "./MessageEntry";
-export type { MessageEntryProps } from "./MessageEntry";
+export { MessageEntry } from "./MessageEntry.js";
+export type { MessageEntryProps } from "./MessageEntry.js";
 
-export { MessageThread } from "./MessageThread";
-export type { MessageThreadProps } from "./MessageThread";
+export { MessageThread } from "./MessageThread.js";
+export type { MessageThreadProps } from "./MessageThread.js";
 
-export { ThreadSkeleton } from "./ThreadSkeleton";
-export type { ThreadSkeletonProps } from "./ThreadSkeleton";
+export { ThreadSkeleton } from "./ThreadSkeleton.js";
+export type { ThreadSkeletonProps } from "./ThreadSkeleton.js";
 
-export { FollowUpInput } from "./FollowUpInput";
-export type { FollowUpInputProps } from "./FollowUpInput";
+export { FollowUpInput } from "./FollowUpInput.js";
+export type { FollowUpInputProps } from "./FollowUpInput.js";
 
-export { ExecutionProgress } from "./ExecutionProgress";
-export type { ExecutionProgressProps } from "./ExecutionProgress";
+export { ExecutionProgress } from "./ExecutionProgress.js";
+export type { ExecutionProgressProps } from "./ExecutionProgress.js";
 
 export {
   TodoList,
   TodoInProgressIcon,
   findActiveTodo,
   todoCompletionSummary,
-} from "./TodoList";
-export type { TodoListProps } from "./TodoList";
+} from "./TodoList.js";
+export type { TodoListProps } from "./TodoList.js";
+
+export { TodoCard } from "./TodoCard.js";
+export type { TodoCardProps } from "./TodoCard.js";
+
+
+export { useSubmitApproval } from "./useSubmitApproval.js";
+export type { UseSubmitApprovalReturn } from "./useSubmitApproval.js";
+
+export { useFileReview, fileDecisionKey } from "./useFileReview.js";
+export type { UseFileReviewReturn, FileDecisionOptions } from "./useFileReview.js";
+
+export {
+  fileReviewability,
+  changeSetReviewability,
+  deriveEffectiveVerdicts,
+  changeForRowPath,
+  fileReviewRowState,
+} from "./file-review-status.js";
+export type {
+  FileReviewability,
+  FileBlockReason,
+  ChangeSetReviewability,
+  FileReviewRowState,
+} from "./file-review-status.js";
+
+// 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.js";
+export type {
+  ApprovalCardProps,
+  ApprovalCardHeaderProps,
+  ApprovalCardBodyProps,
+} from "./ApprovalCard.js";
+
+export { FileReviewCard } from "./FileReviewCard.js";
+export type { FileReviewCardProps } from "./FileReviewCard.js";
 
+export { FileReviewDock } from "./FileReviewDock.js";
+export type { FileReviewDockProps } from "./FileReviewDock.js";
 
-export { useSubmitApproval } from "./useSubmitApproval";
-export type { UseSubmitApprovalReturn } from "./useSubmitApproval";
+export { ApprovalContext, useApproval } from "./ApprovalContext.js";
+export type { ApprovalContextValue, UseApprovalResult } from "./ApprovalContext.js";
 
-export { ApprovalCard } from "./ApprovalCard";
-export type { ApprovalCardProps } from "./ApprovalCard";
+export { FileReviewContext, useFileReviewRowState } from "./FileReviewContext.js";
+export type { FileReviewContextValue } from "./FileReviewContext.js";
 
-export { ArtifactCard } from "./ArtifactCard";
-export type { ArtifactCardProps } from "./ArtifactCard";
+export { ArtifactCard } from "./ArtifactCard.js";
+export type { ArtifactCardProps } from "./ArtifactCard.js";
 
-export { ArtifactContentRenderer } from "./ArtifactContentRenderer";
-export type { ArtifactContentRendererProps } from "./ArtifactContentRenderer";
+export { ArtifactContentRenderer } from "./ArtifactContentRenderer.js";
+export type { ArtifactContentRendererProps } from "./ArtifactContentRenderer.js";
 
-export { ArtifactPreviewContent, ArtifactPreviewModal } from "./ArtifactPreviewModal";
-export type { ArtifactPreviewContentProps, ArtifactPreviewModalProps } from "./ArtifactPreviewModal";
+export { ArtifactPreviewContent, ArtifactPreviewModal } from "./ArtifactPreviewModal.js";
+export type { ArtifactPreviewContentProps, ArtifactPreviewModalProps } from "./ArtifactPreviewModal.js";
 
-export { ArtifactsWidget } from "./ArtifactsWidget";
-export type { ArtifactsWidgetProps } from "./ArtifactsWidget";
+export { ArtifactsWidget } from "./ArtifactsWidget.js";
+export type { ArtifactsWidgetProps } from "./ArtifactsWidget.js";
 
-export { WriteBacksWidget } from "./WriteBacksWidget";
-export type { WriteBacksWidgetProps } from "./WriteBacksWidget";
+export { WriteBacksWidget } from "./WriteBacksWidget.js";
+export type { WriteBacksWidgetProps } from "./WriteBacksWidget.js";
 
 export {
   resolveToolCategory,
@@ -175,27 +253,29 @@ export {
   extractPrimaryArg,
   extractPrimaryArgFromPreview,
   humanizeToolName,
-} from "./tool-categories";
-export type { ToolCategory, ToolCategoryInfo } from "./tool-categories";
+  defaultDisclosureForCategory,
+  isRunGroupableCategory,
+} from "./tool-categories.js";
+export type { ToolCategory, ToolCategoryInfo, ToolDisclosure } from "./tool-categories.js";
 
-export { FilePathLink } from "./FilePathLink";
-export type { FilePathLinkProps } from "./FilePathLink";
+export { FilePathLink } from "./FilePathLink.js";
+export type { FilePathLinkProps } from "./FilePathLink.js";
 
-export { FilePathContext } from "./FilePathContext";
-export type { FilePathContextValue } from "./FilePathContext";
+export { FilePathContext } from "./FilePathContext.js";
+export type { FilePathContextValue } from "./FilePathContext.js";
 
-export { normalizeSandboxPaths } from "./sandbox-path-normalizer";
-export { SandboxContext, useSandboxNormalize } from "./SandboxContext";
-export type { SandboxContextValue } from "./SandboxContext";
+export { normalizeSandboxPaths } from "./sandbox-path-normalizer.js";
+export { SandboxContext, useSandboxNormalize } from "./SandboxContext.js";
+export type { SandboxContextValue } from "./SandboxContext.js";
 
-export { classifyPath, resolveGitBrowseUrl, resolvePathAction } from "./file-path-resolver";
-export type { PathClassification, ResolvedPathAction } from "./file-path-resolver";
+export { classifyPath, resolveGitBrowseUrl, resolvePathAction } from "./file-path-resolver.js";
+export type { PathClassification, ResolvedPathAction } from "./file-path-resolver.js";
 
-export { useSessionVariables } from "./useSessionVariables";
+export { useSessionVariables } from "./useSessionVariables.js";
 export type {
   SessionVariableEntry,
   UseSessionVariablesReturn,
-} from "./useSessionVariables";
+} from "./useSessionVariables.js";
 
-export { SessionVariablesInput } from "./SessionVariablesInput";
-export type { SessionVariablesInputProps } from "./SessionVariablesInput";
+export { SessionVariablesInput } from "./SessionVariablesInput.js";
+export type { SessionVariablesInputProps } from "./SessionVariablesInput.js";

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.js";
+import type { ToolCategory } from "./tool-categories.js";
+import { resolveRunGroupable } from "./tool-presenter.js";
+
+/**
+ * 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;
+}

package/src/execution/tool-categories.ts

@@ -1,4 +1,5 @@
 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 type { JsonObject } from "@bufbuild/protobuf";
 import { ToolKind, resolveToolKind, resolveToolKindByName } from "@stigmer/sdk";
 
@@ -27,6 +28,96 @@ export type ToolCategory =
   | "mcp"
   | "unknown";
 
+/**
+ * How much of a settled tool call to reveal inline by default in the thread.
+ *
+ * - `"summary"` — a compact one-line row. Used when the label + primary arg +
+ *   result summary already tell the story (`Read foo.ts`, `Edit bar.ts +40 -0`,
+ *   `Search … 2 matches`). The full detail is one click away.
+ * - `"preview"` — the row renders its result body **always** (no card chevron),
+ *   because the one-liner cannot convey what happened so the content itself IS
+ *   the information (a shell command's output, an MCP result such as a
+ *   screenshot, a fetched page, a web-search answer, or an unrecognised tool's
+ *   output). The body's own in-place reveal expands it beyond the height budget.
+ *
+ * This is the *disclosure* axis (how much of a result to show); it is
+ * orthogonal to {@link isRunGroupableCategory} (whether consecutive same-kind
+ * calls fold into one chip). A category can be result-rich but never folded
+ * (`shell`), or foldable but never previewed (`read`).
+ */
+export type ToolDisclosure = "summary" | "preview";
+
+/**
+ * Categories whose result is foregrounded as a persistent bounded preview by
+ * default — those for which the compact one-liner cannot convey what happened,
+ * so the output itself carries the meaning. All other categories default to
+ * `"summary"`.
+ *
+ * File edits and writes are previewed: a `+N -M` summary says how much changed
+ * but not *what* — and the change is the decision-relevant content. Surfacing a
+ * bounded diff inline (Cursor-style) is the point of a code agent. The body is
+ * height-clamped with a single in-place reveal for the rest, so density stays
+ * under control even in turns with many edits.
+ */
+const PREVIEW_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
+  "shell",
+  "edit",
+  "write",
+  "mcp",
+  "web-search",
+  "fetch",
+  "unknown",
+]);
+
+/**
+ * Low-signal categories whose consecutive runs fold into a single collapsible
+ * "Read 5 files" chip in the thread. These are the read-only, repetitive
+ * operations whose individual rows are noise in bulk; everything else renders
+ * as a persistent row. This is the *run-grouping* axis, orthogonal to
+ * {@link ToolDisclosure} — see {@link isRunGroupableCategory}.
+ */
+const RUN_GROUPABLE_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
+  "read",
+  "list",
+  "search",
+]);
+
+/**
+ * Returns the default inline {@link ToolDisclosure} for a presentation
+ * category. This is the headless policy behind the thread's "keep a live
+ * preview for shell/MCP/unknown, keep generic tools compact" behaviour;
+ * consumers can override per {@link ToolKind} via {@link registerToolPresenter}.
+ */
+export function defaultDisclosureForCategory(
+  category: ToolCategory,
+): ToolDisclosure {
+  return PREVIEW_CATEGORIES.has(category) ? "preview" : "summary";
+}
+
+/**
+ * Returns whether a presentation category participates in run-grouping — i.e.
+ * whether a maximal run of consecutive calls of this category folds into one
+ * collapsible chip. See {@link RUN_GROUPABLE_CATEGORIES} and `segmentToolCalls`.
+ */
+export function isRunGroupableCategory(category: ToolCategory): boolean {
+  return RUN_GROUPABLE_CATEGORIES.has(category);
+}
+
+/**
+ * Returns whether a category's primary argument is a file path — the file
+ * tools (read / write / edit / delete). These render their path filename-first
+ * via {@link FilePathLink} (full path on hover) in headers and previews, rather
+ * than as a raw, often-absolute string.
+ */
+export function isFileCategory(category: ToolCategory): boolean {
+  return (
+    category === "read" ||
+    category === "write" ||
+    category === "edit" ||
+    category === "delete"
+  );
+}
+
 /** Resolved display metadata for a tool call, returned by {@link resolveToolCategory}. */
 export interface ToolCategoryInfo {
   /** Semantic category of the tool. */
@@ -72,6 +163,31 @@ export function isInternalTool(toolName: string): boolean {
   return resolveToolKindByName(toolName) === ToolKind.TODO;
 }
 
+/**
+ * Returns true for a tool call the runner collapsed in place — a superseded
+ * same-turn duplicate of an approval gate.
+ *
+ * When the agent emits one resource twice in a turn and both attempts are denied,
+ * the runner overlays the FIRST as the WAITING_APPROVAL gate and blanks the
+ * redundant twin to a content-less SKIPPED row (it cannot drop it — the backend's
+ * append-only-at-identity guard forbids removing a committed tool-call id). This
+ * predicate recognizes that blanked twin so the thread renders one card, not two.
+ *
+ * The signature is precise: a SKIPPED row with no approval flag, no result, no
+ * error, and no args preview. A genuinely user-skipped tool always retains the
+ * preview/args the user reviewed before skipping, so it is never blank and is
+ * never hidden by this.
+ */
+export function isCollapsedToolCall(toolCall: ToolCall): boolean {
+  return (
+    toolCall.status === ToolCallStatus.TOOL_CALL_SKIPPED &&
+    !toolCall.requiresApproval &&
+    !toolCall.result &&
+    !toolCall.error &&
+    !toolCall.argsPreview
+  );
+}
+
 /** Maps a {@link ToolKind} to its presentation metadata. */
 export function toolKindToCategoryInfo(
   kind: ToolKind,
@@ -226,11 +342,19 @@ export function extractPrimaryArg(toolCall: ToolCall): string | null {
  * Extracts the primary argument value from a JSON string
  * (typically `PendingApproval.argsPreview`). Returns `null` if
  * parsing fails or the expected field is not found.
+ *
+ * When the caller has the denormalized wire `tool_kind` (as `PendingApproval`
+ * does), pass it so resolution honors the same kind that drives the label/icon —
+ * a file tool whose NAME the classifier doesn't recognize still resolves to its
+ * `path` field. This mirrors {@link extractPrimaryArg}, which uses the wire kind
+ * via `resolveToolCategoryFromCall`. Falls back to name-based resolution when
+ * the kind is unset (legacy executions).
  */
 export function extractPrimaryArgFromPreview(
   toolName: string,
   argsPreview: string,
   mcpServerSlug?: string,
+  toolKind?: ToolKind,
 ): string | null {
   if (!argsPreview) return null;
 
@@ -238,7 +362,10 @@ export function extractPrimaryArgFromPreview(
     const parsed = JSON.parse(argsPreview);
     if (typeof parsed !== "object" || parsed === null) return null;
 
-    const info = resolveToolCategory(toolName, mcpServerSlug);
+    const info =
+      toolKind !== undefined
+        ? resolveToolCategoryFromKind(toolKind, toolName, mcpServerSlug)
+        : resolveToolCategory(toolName, mcpServerSlug);
     return extractArgValue(
       parsed as JsonObject,
       info.primaryArgField,