@stigmer/react 3.0.9-dev.20260615153829 → 3.1.0

package/src/execution/useFileReview.ts

@@ -0,0 +1,197 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  FileDecisionAction,
+  FileDecisionScope,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { SubmitFileDecisionInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Options narrowing a file decision to a single file and binding its digest. */
+export interface FileDecisionOptions {
+  /**
+   * Decision scope. Defaults to `FILE` when {@link fileChangeId} is set, else
+   * `CHANGE_SET` (the whole-set decision that covers every file).
+   */
+  readonly scope?: FileDecisionScope;
+  /** The captured file this decision targets; required for `FILE` scope. */
+  readonly fileChangeId?: string;
+  /**
+   * The digest the reviewer saw (`aggregate_digest` for CHANGE_SET,
+   * `file_digest` for FILE). The server enforces it at decision time and the
+   * runner re-verifies it at reconcile — "what you approve is what gets applied".
+   */
+  readonly expectedDigest?: string;
+  /** Optional free-text comment recorded on the decision (audit trail). */
+  readonly reason?: string;
+  /**
+   * Set on an APPROVE to consciously KEEP a change whose diff could not be fully
+   * reviewed. Honored only for a binary file at `FILE` scope (a binary has no
+   * text diff, but its exact bytes are captured and reconcilable). It never
+   * relaxes the digest gate, and is ignored for other incompleteness. See DD-16.
+   */
+  readonly acknowledgeUnreviewable?: boolean;
+}
+
+/** Return value of {@link useFileReview}. */
+export interface UseFileReviewReturn {
+  /**
+   * Submit an approve/reject decision for a change set (or one file within it).
+   * Resolves when the backend accepts the decision; the execution stream will
+   * deliver the updated `file_change_sets` projection.
+   */
+  readonly submitFileDecision: (
+    executionId: string,
+    changeSetId: string,
+    action: FileDecisionAction,
+    options?: FileDecisionOptions,
+  ) => Promise<void>;
+  /**
+   * Keys (`changeSetId` for a whole-set decision, `changeSetId:fileChangeId` for
+   * a per-file one) currently being submitted — drives per-button loading state
+   * when a reviewer decides files independently. Build a key with
+   * {@link fileDecisionKey}.
+   */
+  readonly submittingDecisionKeys: ReadonlySet<string>;
+  /**
+   * Per-decision failures, keyed exactly like {@link submittingDecisionKeys}
+   * (via {@link fileDecisionKey}). This is the per-target parallel of the
+   * in-flight Set: a review card has many decision targets (the whole set plus
+   * each file), so a failure must be attributable to the *one* control that
+   * failed — a single scalar cannot say which file. {@link FileReviewCard}
+   * consumes this map to render the error in-card, beside the failed control.
+   */
+  readonly decisionErrors: ReadonlyMap<string, Error>;
+  /** Clear the error for one decision key (e.g. before a retry of that target). */
+  readonly clearDecisionError: (key: string) => void;
+  /**
+   * The most-recent decision failure, or `null` when healthy — a convenience
+   * mirror of {@link decisionErrors} for a headless consumer that wants a single
+   * error value (a banner). The map is authoritative for per-control surfacing.
+   */
+  readonly error: Error | null;
+  /** Reset every decision error (both {@link decisionErrors} and {@link error}). */
+  readonly clearError: () => void;
+}
+
+/**
+ * The loading-state key for a file decision: the change set id for a whole-set
+ * (CHANGE_SET) decision, or `changeSetId:fileChangeId` for a per-file one.
+ */
+export function fileDecisionKey(changeSetId: string, fileChangeId?: string): string {
+  return fileChangeId ? `${changeSetId}:${fileChangeId}` : changeSetId;
+}
+
+/** A stable empty map so an error-free hook keeps a constant `decisionErrors` ref. */
+const NO_DECISION_ERRORS: ReadonlyMap<string, Error> = new Map();
+
+/**
+ * Behavior hook that wraps `agentExecution.submitFileDecision()` with per-decision
+ * loading state and error management — the file-review sibling of
+ * {@link useSubmitApproval}.
+ *
+ * File edits are reviewed as a captured change set (the `file_change_sets`
+ * projection), NOT as tool-call approvals. Platform builders who want full
+ * control over the review UI use this hook directly; those who prefer a drop-in
+ * surface use {@link FileReviewCard}, which accepts the callback shape this
+ * hook produces.
+ *
+ * @example
+ * ```tsx
+ * const { submitFileDecision, submittingDecisionKeys } = useFileReview();
+ *
+ * // Approve the whole change set:
+ * await submitFileDecision(executionId, changeSet.id, FileDecisionAction.APPROVE, {
+ *   expectedDigest: changeSet.aggregateDigest,
+ * });
+ * ```
+ */
+export function useFileReview(): UseFileReviewReturn {
+  const stigmer = useStigmer();
+  const [submittingKeys, setSubmittingKeys] = useState<ReadonlySet<string>>(
+    new Set(),
+  );
+  const [decisionErrors, setDecisionErrors] =
+    useState<ReadonlyMap<string, Error>>(NO_DECISION_ERRORS);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearDecisionError = useCallback((key: string) => {
+    setDecisionErrors((prev) => {
+      if (!prev.has(key)) return prev;
+      const next = new Map(prev);
+      next.delete(key);
+      return next;
+    });
+  }, []);
+
+  const clearError = useCallback(() => {
+    setDecisionErrors(NO_DECISION_ERRORS);
+    setError(null);
+  }, []);
+
+  const submitFileDecision = useCallback(
+    async (
+      executionId: string,
+      changeSetId: string,
+      action: FileDecisionAction,
+      options?: FileDecisionOptions,
+    ): Promise<void> => {
+      const fileChangeId = options?.fileChangeId ?? "";
+      const scope =
+        options?.scope ??
+        (fileChangeId ? FileDecisionScope.FILE : FileDecisionScope.CHANGE_SET);
+      const key = fileDecisionKey(changeSetId, fileChangeId || undefined);
+
+      setSubmittingKeys((prev) => {
+        const next = new Set(prev);
+        next.add(key);
+        return next;
+      });
+      // Clear this target's prior failure (and the scalar mirror) so a retry
+      // starts clean — the map and `error` are updated together, never drift.
+      clearDecisionError(key);
+      setError(null);
+
+      try {
+        const input = create(SubmitFileDecisionInputSchema, {
+          agentExecutionId: executionId,
+          changeSetId,
+          scope,
+          fileChangeId,
+          action,
+          expectedDigest: options?.expectedDigest ?? "",
+          reason: options?.reason ?? "",
+          acknowledgeUnreviewable: options?.acknowledgeUnreviewable ?? false,
+        });
+        await stigmer.agentExecution.submitFileDecision(input);
+      } catch (err) {
+        const e = toError(err);
+        setDecisionErrors((prev) => new Map(prev).set(key, e));
+        setError(e);
+        throw err;
+      } finally {
+        setSubmittingKeys((prev) => {
+          const next = new Set(prev);
+          next.delete(key);
+          return next;
+        });
+      }
+    },
+    [stigmer, clearDecisionError],
+  );
+
+  return useMemo(
+    () => ({
+      submitFileDecision,
+      submittingDecisionKeys: submittingKeys,
+      decisionErrors,
+      clearDecisionError,
+      error,
+      clearError,
+    }),
+    [submitFileDecision, submittingKeys, decisionErrors, clearDecisionError, error, clearError],
+  );
+}

package/src/execution/useSubmitApproval.ts

@@ -1,11 +1,12 @@
 "use client";
 
-import { useCallback, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { SubmitApprovalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
+import { useKeyedSubmission } from "../internal/useKeyedSubmission";
 
 /** Return value of {@link useSubmitApproval}. */
 export interface UseSubmitApprovalReturn {
@@ -26,9 +27,24 @@ export interface UseSubmitApprovalReturn {
    * approve one tool while another decision is still in flight.
    */
   readonly submittingToolCallIds: ReadonlySet<string>;
-  /** Error from the last failed approval submission, or `null` when healthy. */
+  /**
+   * Per-tool-call failures, keyed by `toolCallId` exactly like
+   * {@link submittingToolCallIds}. This is the per-target parallel of the
+   * in-flight Set: a thread can hold many simultaneous gates (one per inline
+   * tool row, plus the bottom backstop), so a failure must be attributable to
+   * the *one* gate that failed — a single scalar cannot say which. {@link
+   * ApprovalCard} / {@link ApprovalCardBody} consume this (threaded via
+   * {@link ApprovalContext}) to render the error in-card, beside the failed gate.
+   */
+  readonly errorsByToolCallId: ReadonlyMap<string, Error>;
+  /**
+   * Error from the last failed approval submission, or `null` when healthy — a
+   * convenience mirror of {@link errorsByToolCallId} for a headless consumer
+   * that wants a single error value (e.g. a banner, or the `ink` surface). The
+   * map is authoritative for per-gate surfacing.
+   */
   readonly error: Error | null;
-  /** Reset `error` to `null`. */
+  /** Reset every approval error (both {@link errorsByToolCallId} and {@link error}). */
   readonly clearError: () => void;
 }
 
@@ -54,12 +70,16 @@ export interface UseSubmitApprovalReturn {
  */
 export function useSubmitApproval(): UseSubmitApprovalReturn {
   const stigmer = useStigmer();
-  const [submittingIds, setSubmittingIds] = useState<ReadonlySet<string>>(
-    new Set(),
-  );
+  // Per-gate in-flight + error state, keyed by tool-call id, lives in the
+  // shared keyed-submission primitive. The scalar `error` below is a thin
+  // mirror kept in lockstep for headless / ink consumers.
+  const keyed = useKeyedSubmission<void>();
   const [error, setError] = useState<Error | null>(null);
 
-  const clearError = useCallback(() => setError(null), []);
+  const clearError = useCallback(() => {
+    keyed.clearErrors();
+    setError(null);
+  }, [keyed.clearErrors]);
 
   const submitApproval = useCallback(
     async (
@@ -68,34 +88,36 @@ export function useSubmitApproval(): UseSubmitApprovalReturn {
       action: ApprovalAction,
       comment?: string,
     ): Promise<void> => {
-      setSubmittingIds((prev) => {
-        const next = new Set(prev);
-        next.add(toolCallId);
-        return next;
-      });
+      // Clear the scalar mirror at submit-start; `keyed.run` clears this gate's
+      // keyed entry, so the map and `error` are updated together and never drift.
       setError(null);
-
       try {
-        const input = create(SubmitApprovalInputSchema, {
-          agentExecutionId: executionId,
-          toolCallId,
-          action,
-          comment: comment ?? "",
+        await keyed.run(toolCallId, async () => {
+          await stigmer.agentExecution.submitApproval(
+            create(SubmitApprovalInputSchema, {
+              agentExecutionId: executionId,
+              toolCallId,
+              action,
+              comment: comment ?? "",
+            }),
+          );
         });
-        await stigmer.agentExecution.submitApproval(input);
       } catch (err) {
         setError(toError(err));
         throw err;
-      } finally {
-        setSubmittingIds((prev) => {
-          const next = new Set(prev);
-          next.delete(toolCallId);
-          return next;
-        });
       }
     },
-    [stigmer],
+    [stigmer, keyed.run],
   );
 
-  return { submitApproval, submittingToolCallIds: submittingIds, error, clearError };
+  return useMemo(
+    () => ({
+      submitApproval,
+      submittingToolCallIds: keyed.submittingKeys,
+      errorsByToolCallId: keyed.errorsByKey,
+      error,
+      clearError,
+    }),
+    [submitApproval, keyed.submittingKeys, keyed.errorsByKey, error, clearError],
+  );
 }

package/src/execution/useToolOutputContent.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useMemo } from "react";
+import type { ToolCallOutputRef } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { useArtifactContent } from "./useArtifactContent";
+import { execIdFromStorageKey } from "./useFileChangeContent";
+
+/** Return value of {@link useToolOutputContent}. */
+export interface UseToolOutputContentReturn {
+  /**
+   * Full text content of the offloaded tool output, or `null` while the
+   * request is in-flight, failed, or the hook is disabled.
+   */
+  readonly content: string | null;
+  /** `true` while the content request is in-flight. */
+  readonly isLoading: boolean;
+  /**
+   * `true` when the server truncated the content at its size cap. The inline
+   * view is then incomplete — offer a full download via the presigned URL.
+   */
+  readonly isTruncated: boolean;
+  /** Error from a failed fetch, or `null`. */
+  readonly error: Error | null;
+}
+
+/**
+ * Minimal shape this hook needs from an offloaded-output reference. Both a full
+ * {@link ToolCallOutputRef} and the SDK's normalized `outputRef` view satisfy it.
+ */
+export type ToolOutputRefLike = Pick<ToolCallOutputRef, "storageKey" | "contentHash">;
+
+/**
+ * Behavior hook that resolves the full text of a tool output that the runner
+ * offloaded to artifact storage (a {@link ToolCallOutputRef}).
+ *
+ * Mirrors {@link useFileChangeContent}: it ignores any URL baked into the ref
+ * and fetches the bytes on demand through the CORS-safe `getArtifactContent`
+ * endpoint, deriving the execution id from the ref's own `storageKey`
+ * (`artifacts/{executionId}/...`). This is what lets a "View full output" link
+ * keep working long after the original presigned URL would have expired.
+ *
+ * Fetching is gated by `enabled` so callers can defer the request until the
+ * user actually expands the output (lazy), keeping long threads cheap.
+ *
+ * @param outputRef - The offloaded-output reference, or `null` to skip.
+ * @param enabled - When `false`, the hook stays idle. Defaults to `true`.
+ *
+ * @see useArtifactContent — the underlying content fetch
+ * @see useArtifactDownloadUrl — for the truncated/binary full-download fallback
+ */
+export function useToolOutputContent(
+  outputRef: ToolOutputRefLike | null | undefined,
+  enabled = true,
+): UseToolOutputContentReturn {
+  const storageKey = outputRef?.storageKey || null;
+  const active = enabled && !!storageKey;
+  const executionId = active ? execIdFromStorageKey(storageKey!) : null;
+
+  const { content, isLoading, isTruncated, error } = useArtifactContent(
+    active ? executionId : null,
+    active ? storageKey : null,
+    null,
+    outputRef?.contentHash || undefined,
+  );
+
+  return useMemo(
+    () => ({ content, isLoading, isTruncated, error }),
+    [content, isLoading, isTruncated, error],
+  );
+}

package/src/index.ts

@@ -95,6 +95,7 @@ export {
   useSessionConversation,
   useSessionArtifacts,
   useSessionWriteBacks,
+  useSessionFileChanges,
   useSessionUsage,
   useAgentRefFromSession,
   useNewSessionFlow,
@@ -134,6 +135,7 @@ export type {
   UseSessionArtifactsReturn,
   SessionWriteBackEntry,
   UseSessionWriteBacksReturn,
+  UseSessionFileChangesReturn,
   ModelCostEntry,
   UseSessionUsageReturn,
   UseAgentRefFromSessionReturn,
@@ -182,11 +184,22 @@ export {
   useExecutionStream,
   useAgentExecutionActions,
   useSubmitApproval,
+  useFileReview,
+  fileDecisionKey,
+  fileReviewability,
+  changeSetReviewability,
+  deriveEffectiveVerdicts,
+  changeForRowPath,
+  fileReviewRowState,
+  foldFileReviewEventStream,
+  displayFileChangeSets,
+  toDisplayFileChange,
   ExecutionPhaseBadge,
   InteractionModeBadge,
   SetupProgress,
   ExecutionProgress,
   TodoList,
+  TodoCard,
   TodoInProgressIcon,
   findActiveTodo,
   todoCompletionSummary,
@@ -202,6 +215,7 @@ export {
   ToolCallDetail,
   ResultView,
   summarizeResultView,
+  TerminalSession,
   useToolPresentation,
   registerToolPresenter,
   getToolPresenter,
@@ -209,6 +223,7 @@ export {
   resolveToolCategoryFromCall,
   resolveToolCategoryFromKind,
   toolKindToCategoryInfo,
+  defaultDisclosureForCategory,
   McpToolDetail,
   parseMcpResult,
   formatDuration,
@@ -220,6 +235,14 @@ export {
   ThreadSkeleton,
   FollowUpInput,
   ApprovalCard,
+  ApprovalCardHeader,
+  ApprovalCardBody,
+  FileReviewCard,
+  FileReviewDock,
+  ApprovalContext,
+  useApproval,
+  FileReviewContext,
+  useFileReviewRowState,
   ArtifactCard,
   ArtifactContentRenderer,
   ArtifactPreviewContent,
@@ -238,10 +261,17 @@ export {
   SessionVariablesInput,
   useExecutionArtifacts,
   useArtifactContent,
+  useArtifactDownloadUrl,
+  useArtifactDownload,
+  useToolOutputContent,
+  useFileChangeContent,
+  execIdFromStorageKey,
   useWorkspaceWriteBacks,
   WriteBackCard,
+  FileChangesView,
+  FileChangeDiff,
+  EmptyChangeNotice,
   isTextArtifact,
-  isArtifactExpired,
   formatArtifactSize,
   getArtifactExtension,
   getFileExtension,
@@ -255,11 +285,18 @@ export type {
   UseAgentExecutionActionsOptions,
   UseAgentExecutionActionsReturn,
   UseSubmitApprovalReturn,
+  UseFileReviewReturn,
+  FileDecisionOptions,
+  FileReviewability,
+  FileBlockReason,
+  ChangeSetReviewability,
+  FileReviewRowState,
   ExecutionPhaseBadgeProps,
   InteractionModeBadgeProps,
   SetupProgressProps,
   ExecutionProgressProps,
   TodoListProps,
+  TodoCardProps,
   UsageWidgetProps,
   ContextGaugeProps,
   SummarizationBadgeProps,
@@ -271,8 +308,10 @@ export type {
   ToolCallGroupProps,
   ToolCallDetailProps,
   ResultViewProps,
+  TerminalSessionProps,
   ToolPresentation,
   ToolPresenter,
+  ToolDisclosure,
   McpToolDetailProps,
   McpArgsViewProps,
   McpMetadataRowProps,
@@ -284,6 +323,13 @@ export type {
   ThreadSkeletonProps,
   FollowUpInputProps,
   ApprovalCardProps,
+  ApprovalCardHeaderProps,
+  ApprovalCardBodyProps,
+  FileReviewCardProps,
+  FileReviewDockProps,
+  ApprovalContextValue,
+  UseApprovalResult,
+  FileReviewContextValue,
   ArtifactCardProps,
   ArtifactContentRendererProps,
   ArtifactRenderMode,
@@ -300,8 +346,18 @@ export type {
   SessionVariablesInputProps,
   UseExecutionArtifactsReturn,
   UseArtifactContentReturn,
+  UseArtifactDownloadUrlReturn,
+  UseArtifactDownloadUrlOptions,
+  UseArtifactDownloadReturn,
+  UseToolOutputContentReturn,
+  ToolOutputRefLike,
+  UseFileChangeContentReturn,
   UseWorkspaceWriteBacksReturn,
   WriteBackCardProps,
+  FileChangesViewProps,
+  FileChangeDiffProps,
+  EmptyChangeNoticeProps,
+  EmptyChangeKind,
 } from "./execution";
 
 // Execution — proto type re-exports for artifact consumers
@@ -1207,6 +1263,7 @@ export {
   WorkflowExecutionCostPanel,
   WorkflowExecutionArtifactPanel,
   WorkflowExecutionApprovalCard,
+  WorkflowFileReviewList,
   serializeWorkflowYaml,
   parseWorkflowYaml,
   useWorkflowYaml,
@@ -1318,6 +1375,8 @@ export type {
   WorkflowExecutionCostPanelProps,
   WorkflowExecutionArtifactPanelProps,
   WorkflowExecutionApprovalCardProps,
+  WorkflowFileReviewListProps,
+  WorkflowFileDecisionSubmit,
   UseWorkflowYamlReturn,
   UseWorkflowSaveReturn,
   UseWorkflowValidationReturn,

package/src/internal/ApprovalPeekBar.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+interface ApprovalPeekBarProps {
+  /** Whether the bar is shown — typically `notFollowing && count > 0`. */
+  readonly visible: boolean;
+  /** Number of unresolved approvals, for the label ("1 approval needed"). */
+  readonly count: number;
+  /** Jumps to the live frontier where the gated tool call (and its inline approval) sits. */
+  readonly onClick: () => void;
+}
+
+/**
+ * Floating affordance that surfaces a pending approval the user has scrolled
+ * away from. A run halts at its first approval gate, so the waiting tool call
+ * sits at the live frontier — clicking jumps there (reusing the thread's
+ * existing jump-to-latest), landing on the inline approval card.
+ *
+ * Takes the {@link JumpToLatestButton}'s slot when approvals are pending (the
+ * two are mutually exclusive by the caller), styled in `warning` so a gate is
+ * never missed off-screen. Always mounted for enter/exit transitions.
+ *
+ * @internal Not part of the public API.
+ */
+export function ApprovalPeekBar({ visible, count, onClick }: ApprovalPeekBarProps) {
+  const label =
+    count === 1 ? "1 approval needed" : `${count} approvals needed`;
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={`${label} — jump to it`}
+      aria-hidden={!visible}
+      tabIndex={visible ? 0 : -1}
+      className={cn(
+        "absolute bottom-3 left-1/2 z-10 -translate-x-1/2",
+        "flex items-center gap-1.5 rounded-full",
+        "border border-warning/40 bg-warning/10 px-3 py-1.5",
+        "text-xs font-medium text-warning shadow-md",
+        "transition-[opacity,transform] duration-[var(--stgm-motion-duration)]",
+        "hover:bg-warning/20",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        visible
+          ? "pointer-events-auto translate-y-0 opacity-100"
+          : "pointer-events-none translate-y-2 opacity-0",
+      )}
+    >
+      <ClockIcon />
+      {label}
+    </button>
+  );
+}
+
+function ClockIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 12 12"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="6" cy="6" r="4.5" />
+      <path d="M6 3.5V6L7.5 7.5" />
+    </svg>
+  );
+}