@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/execution/FileReviewContext.ts

@@ -0,0 +1,53 @@
+import { createContext, useContext } from "react";
+import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  fileReviewRowState,
+  type FileReviewRowState,
+} from "./file-review-status";
+
+/**
+ * Context value that carries the session's captured change sets to the
+ * transcript tool rows that reference them, so a stamped file-edit row
+ * (`ToolCall.file_change_set_id`) can badge itself with the set's live review
+ * state — pending review, kept, discarded — right where the edit happened.
+ *
+ * The sibling of {@link ApprovalContext}, and the same discipline: provided by
+ * {@link MessageThread}, keyed by a stable id, rebuilt only when the underlying
+ * change sets actually change (structural sharing keeps set references stable
+ * across streaming frames), and an empty default so consumers without a
+ * provider render no badge (backward compatible).
+ *
+ * Read-only by design: the row badge is presentation of the set's state, never
+ * a decision surface — decisions live exclusively on the set's decision bar
+ * ({@link FileReviewCard}).
+ */
+export interface FileReviewContextValue {
+  /** Every displayable change set across the session, keyed by `FileChangeSet.id`. */
+  readonly changeSetsById: ReadonlyMap<string, FileChangeSet>;
+}
+
+const DEFAULT_VALUE: FileReviewContextValue = {
+  changeSetsById: new Map(),
+};
+
+/** Context that supplies the session's change sets to stamped tool rows. */
+export const FileReviewContext =
+  createContext<FileReviewContextValue>(DEFAULT_VALUE);
+
+/**
+ * The review state a stamped tool row should badge, or `null` for no badge
+ * (unstamped row, unknown set, or a file absent from its set — see
+ * {@link fileReviewRowState} for the honest-degradation rules).
+ *
+ * @param fileChangeSetId The row's `ToolCall.file_change_set_id` (may be "").
+ * @param rowPath The row's file path (the presenter's primary arg), used to
+ *   resolve this file's verdict once the set is decided.
+ */
+export function useFileReviewRowState(
+  fileChangeSetId: string,
+  rowPath: string | null,
+): FileReviewRowState | null {
+  const { changeSetsById } = useContext(FileReviewContext);
+  if (!fileChangeSetId) return null;
+  return fileReviewRowState(changeSetsById.get(fileChangeSetId), rowPath);
+}

package/src/execution/FileReviewDock.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+import { memo, useCallback } from "react";
+import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { FileDecisionAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { cn } from "@stigmer/theme";
+import { FileReviewCard } from "./FileReviewCard";
+import type { FileDecisionOptions } from "./useFileReview";
+
+/** Props for {@link FileReviewDock}. */
+export interface FileReviewDockProps {
+  /**
+   * The change sets awaiting review. Renders nothing when empty. Feed this from
+   * `useSessionConversation().fileChangeSets` — the AWAITING_REVIEW sets of the
+   * active execution, the same seam whose `submitFileDecision` routes decisions
+   * to that execution, so what the dock shows and what it can decide are
+   * consistent by construction.
+   */
+  readonly changeSets: readonly FileChangeSet[];
+  /**
+   * Called when the user makes a decision on one of the docked sets. Wire to
+   * `useSessionConversation().submitFileDecision` (or an equivalent
+   * {@link useFileReview}-backed handler bound to the owning execution).
+   */
+  readonly onSubmit: (
+    changeSetId: string,
+    action: FileDecisionAction,
+    options?: FileDecisionOptions,
+  ) => void;
+  /**
+   * Decision keys ({@link fileDecisionKey}) currently being submitted. Drives
+   * per-control loading state — see {@link FileReviewCardProps.submittingDecisionKeys}.
+   */
+  readonly submittingDecisionKeys?: ReadonlySet<string>;
+  /**
+   * Per-decision failures, keyed like {@link submittingDecisionKeys} — surfaced
+   * in-card beside the control that failed.
+   */
+  readonly decisionErrors?: ReadonlyMap<string, Error>;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * The composer-docked decision surface for pending file reviews: renders each
+ * AWAITING_REVIEW {@link FileChangeSet} as an interactive {@link FileReviewCard}
+ * decision bar, pinned in the fixed strip above the composer.
+ *
+ * WHY DOCKED, NOT IN-THREAD. The transcript's stamped edit rows are
+ * observational — they show what changed, badged with the live review state —
+ * but a *decision* the agent is blocked on must never scroll out of view. An
+ * in-thread card does exactly that on a long conversation. Docking the bar to
+ * the composer keeps the pending decision visible regardless of scroll
+ * position, matching the shape of Cursor's own review bar. Once decided, the
+ * dock empties and the thread's read-only record (and the rows' Kept/Discarded
+ * badges) carry the history.
+ *
+ * This placement deliberately diverges from tool approvals, which stay inline
+ * on their rows (with `ApprovalPeekBar` as the scroll backstop): an approval is
+ * call-anchored — "run *this* command" — while a file review is a turn-scoped
+ * aggregate over many calls, with no single row that owns it.
+ *
+ * The expanded per-file body is height-capped with internal scroll: a set that
+ * needs per-file attention starts expanded (see {@link FileReviewCard}), and an
+ * unconstrained list in a fixed strip would swallow the viewport.
+ *
+ * Purely presentational — the data and decision routing live in
+ * `useSessionConversation` (headless-first, DD-003). `SessionViewer` wires it
+ * in by default; platform builders composing a custom layout mount it over the
+ * same seam.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId);
+ * <FileReviewDock
+ *   changeSets={conv.fileChangeSets}
+ *   onSubmit={conv.submitFileDecision}
+ *   submittingDecisionKeys={conv.submittingFileDecisionKeys}
+ *   decisionErrors={conv.fileDecisionErrors}
+ * />
+ * ```
+ */
+export function FileReviewDock({
+  changeSets,
+  onSubmit,
+  submittingDecisionKeys,
+  decisionErrors,
+  className,
+}: FileReviewDockProps) {
+  if (changeSets.length === 0) return null;
+
+  return (
+    <div
+      role="region"
+      aria-label="File changes awaiting review"
+      data-cursor-target="file-review-dock"
+      className={cn("border-t border-border-muted", className)}
+    >
+      {/* The cap bounds the dock, not each card: with the (defensive) multi-set
+          case the whole surface stays within reach of the composer. */}
+      <div className="max-h-[40vh] space-y-2 overflow-y-auto px-4 py-2">
+        {changeSets.map((changeSet) => (
+          <DockedChangeSet
+            key={changeSet.id}
+            changeSet={changeSet}
+            onSubmit={onSubmit}
+            submittingDecisionKeys={submittingDecisionKeys}
+            decisionErrors={decisionErrors}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+interface DockedChangeSetProps {
+  readonly changeSet: FileChangeSet;
+  readonly onSubmit: (
+    changeSetId: string,
+    action: FileDecisionAction,
+    options?: FileDecisionOptions,
+  ) => void;
+  readonly submittingDecisionKeys?: ReadonlySet<string>;
+  readonly decisionErrors?: ReadonlyMap<string, Error>;
+}
+
+/**
+ * One docked set — binds the set id into the card's `(action, options)` submit
+ * signature with a stable callback so `FileReviewCard`'s `React.memo` holds
+ * across unrelated stream frames.
+ */
+const DockedChangeSet = memo(function DockedChangeSet({
+  changeSet,
+  onSubmit,
+  submittingDecisionKeys,
+  decisionErrors,
+}: DockedChangeSetProps) {
+  const handleSubmit = useCallback(
+    (action: FileDecisionAction, options?: FileDecisionOptions) => {
+      onSubmit(changeSet.id, action, options);
+    },
+    [onSubmit, changeSet.id],
+  );
+
+  return (
+    <FileReviewCard
+      fileChangeSet={changeSet}
+      onSubmit={handleSubmit}
+      submittingDecisionKeys={submittingDecisionKeys}
+      decisionErrors={decisionErrors}
+      // The transcript's stamped edit rows show every diff in place, so the
+      // docked card renders the compact file list — the decision surface never
+      // duplicates the thread's diffs.
+      showDiffs={false}
+    />
+  );
+});

package/src/execution/McpToolDetail.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useMemo, useState } from "react";
 import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { cn } from "@stigmer/theme";
 import { formatDuration } from "./ToolCallDetail";
@@ -12,6 +13,10 @@ import {
   isScalar,
   humanizeArgKey,
 } from "./tool-rendering-primitives";
+import { execIdFromStorageKey } from "./useFileChangeContent";
+import { useArtifactDownloadUrl } from "./useArtifactDownloadUrl";
+import { useArtifactDownload } from "./useArtifactDownload";
+import { useToolOutputContent } from "./useToolOutputContent";
 
 /** Props for {@link McpToolDetail}. */
 export interface McpToolDetailProps {
@@ -55,7 +60,7 @@ export function McpToolDetail({ toolCall, className }: McpToolDetailProps) {
         <McpArgsView args={toolCall.args as Record<string, unknown>} />
       )}
 
-      {toolCall.outputRef?.downloadUrl ? (
+      {toolCall.outputRef?.storageKey ? (
         <McpOffloadedOutputView outputRef={toolCall.outputRef} />
       ) : (
         toolCall.result && <McpResultView result={toolCall.result} />
@@ -76,51 +81,112 @@ function formatBytes(n: number): string {
 
 /**
  * Renders an MCP result whose bytes were offloaded to artifact storage (e.g. a
- * computer-use screenshot). Images render inline; other large output shows its
- * preview head plus a link to the full content. Mirrors ResultView's outputRef
- * treatment so MCP and non-MCP offloads look consistent.
+ * computer-use screenshot). The bytes are resolved on demand from the stable
+ * `storageKey` — never from a baked URL, which expires. Images render inline via
+ * a freshly minted URL; other large output expands in-app. Mirrors ResultView's
+ * outputRef treatment so MCP and non-MCP offloads look consistent (DD-016).
  */
 function McpOffloadedOutputView({
   outputRef,
 }: {
   readonly outputRef: NonNullable<ToolCall["outputRef"]>;
 }) {
-  const size = Number(outputRef.sizeBytes);
   return (
     <div className="space-y-1">
       <span className="font-medium text-muted-foreground">Result</span>
       {outputRef.isImage ? (
-        <a
-          href={outputRef.downloadUrl}
-          target="_blank"
-          rel="noreferrer"
-          className="inline-block focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-        >
-          <img
-            src={outputRef.downloadUrl}
-            alt="Tool output screenshot"
-            loading="lazy"
-            className="max-h-96 w-auto rounded-md border border-border"
-          />
-        </a>
+        <McpOffloadedImage storageKey={outputRef.storageKey} />
       ) : (
-        <div className="space-y-1">
+        <McpOffloadedText outputRef={outputRef} />
+      )}
+    </div>
+  );
+}
+
+/** Offloaded MCP image output, rendered from an always-fresh presigned URL. */
+function McpOffloadedImage({ storageKey }: { readonly storageKey: string }) {
+  const executionId = useMemo(() => execIdFromStorageKey(storageKey), [storageKey]);
+  const { url, error } = useArtifactDownloadUrl(executionId, storageKey);
+
+  if (error) {
+    return <p className="text-xs text-destructive">Couldn&apos;t load image output.</p>;
+  }
+  if (!url) {
+    return (
+      <div
+        className="h-40 w-64 animate-pulse rounded-md border border-border bg-muted"
+        aria-busy="true"
+        aria-label="Loading image output"
+      />
+    );
+  }
+  return (
+    <a
+      href={url}
+      target="_blank"
+      rel="noreferrer"
+      className="inline-block focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      <img
+        src={url}
+        alt="Tool output screenshot"
+        loading="lazy"
+        className="max-h-96 w-auto rounded-md border border-border"
+      />
+    </a>
+  );
+}
+
+/**
+ * Offloaded MCP text output. Preview head + a "View full output" toggle that
+ * lazily fetches the full content in-app, with a download fallback when the
+ * server truncates it.
+ */
+function McpOffloadedText({
+  outputRef,
+}: {
+  readonly outputRef: NonNullable<ToolCall["outputRef"]>;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const executionId = useMemo(() => execIdFromStorageKey(outputRef.storageKey), [outputRef.storageKey]);
+  const { content, isLoading, isTruncated, error } = useToolOutputContent(outputRef, expanded);
+  const { download, isDownloading } = useArtifactDownload(executionId);
+
+  const size = Number(outputRef.sizeBytes);
+  const sizeSuffix = size ? ` (${formatBytes(size)})` : "";
+  const previewClass = "max-h-80 overflow-auto rounded-md border border-border bg-muted-subtle p-2 text-foreground";
+  const linkClass = "inline-block text-xs font-medium text-primary underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+
+  return (
+    <div className="space-y-1">
+      {!expanded ? (
+        <>
           {outputRef.truncatedPreview && (
-            <CollapsiblePre
-              content={outputRef.truncatedPreview}
-              className="max-h-80 overflow-auto rounded-md border border-border bg-muted-subtle p-2 text-foreground"
-            />
+            <CollapsiblePre content={outputRef.truncatedPreview} className={previewClass} />
+          )}
+          <button type="button" onClick={() => setExpanded(true)} className={linkClass}>
+            View full output{sizeSuffix}
+          </button>
+        </>
+      ) : isLoading ? (
+        <p className="text-xs text-muted-foreground">Loading full output…</p>
+      ) : error ? (
+        <p className="text-xs text-destructive">Couldn&apos;t load full output. Try again.</p>
+      ) : content !== null ? (
+        <div className="space-y-1">
+          <CollapsiblePre content={content} className={previewClass} />
+          {isTruncated && (
+            <button
+              type="button"
+              onClick={() => download(outputRef.storageKey)}
+              disabled={isDownloading}
+              className={cn(linkClass, "disabled:opacity-50")}
+            >
+              {isDownloading ? "Preparing download…" : `Output truncated — download full file${sizeSuffix}`}
+            </button>
           )}
-          <a
-            href={outputRef.downloadUrl}
-            target="_blank"
-            rel="noreferrer"
-            className="inline-block text-xs font-medium text-primary underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-          >
-            View full output{size ? ` (${formatBytes(size)})` : ""}
-          </a>
         </div>
-      )}
+      ) : null}
     </div>
   );
 }