@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/execution/ApprovalContext.ts

@@ -0,0 +1,109 @@
+import { createContext, useCallback, useContext } from "react";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/**
+ * Context value that carries the run's pending approvals to the tool rows
+ * that own them, so an approval gate can render *inline* on the exact tool
+ * call it blocks (parent thread and nested sub-agents alike) instead of as a
+ * detached card at the bottom of the thread.
+ *
+ * Provided by {@link MessageThread} (or a platform builder's custom wrapper),
+ * beside {@link FilePathContext} / `SandboxContext`. When no provider is
+ * present — or the consumer did not supply an `onApprovalSubmit` handler — the
+ * map is empty and {@link useApproval} returns `null`, so the inline UI is a
+ * no-op (backward compatible).
+ *
+ * The map is keyed by `tool_call_id` and rebuilt only when the underlying
+ * `pendingApprovals` list changes (not per streaming frame), so subscribing
+ * tool rows re-render on approval events, not on every snapshot — preserving
+ * the thread's streaming re-render isolation (DD-009 / DD-010).
+ */
+export interface ApprovalContextValue {
+  /** Unresolved approvals, keyed by the `tool_call_id` they gate. */
+  readonly approvalsByToolCallId: ReadonlyMap<string, PendingApproval>;
+  /**
+   * Submits a decision for a gated tool call. Wired to the same handler the
+   * bottom {@link ApprovalCard} backstop uses; when absent, no inline approval
+   * UI is shown.
+   */
+  readonly onSubmit?: (
+    toolCallId: string,
+    action: ApprovalAction,
+    comment?: string,
+  ) => void;
+  /** Tool-call ids whose decision RPC is in flight, for per-card spinners. */
+  readonly submittingIds: ReadonlySet<string>;
+  /**
+   * Per-tool-call failures, keyed by `tool_call_id` (the parallel of
+   * {@link submittingIds}). A failed decision is surfaced in-card, beside the
+   * exact gate that failed, so the inline row can name *which* action did not
+   * take and why. Empty when no provider supplies it.
+   */
+  readonly errorsByToolCallId: ReadonlyMap<string, Error>;
+}
+
+const DEFAULT_VALUE: ApprovalContextValue = {
+  approvalsByToolCallId: new Map(),
+  submittingIds: new Set(),
+  errorsByToolCallId: new Map(),
+};
+
+/** Context that supplies a run's pending approvals to the tool rows they gate. */
+export const ApprovalContext =
+  createContext<ApprovalContextValue>(DEFAULT_VALUE);
+
+/**
+ * Resolved inline-approval state for a single tool call. Its shape is a superset
+ * of the props {@link ApprovalCardBody} reads, so a consumer can spread it
+ * directly: `<ApprovalCardBody {...approval} />`.
+ */
+export interface UseApprovalResult {
+  /** The pending approval gating this tool call. */
+  readonly pendingApproval: PendingApproval;
+  /** Submits a decision for this tool call (id already bound). */
+  readonly onSubmit: (action: ApprovalAction, comment?: string) => void;
+  /** True while this tool call's decision RPC is in flight. */
+  readonly isSubmitting: boolean;
+  /** This gate's last failed decision, or `null` — surfaced in-card beside it. */
+  readonly error: Error | null;
+}
+
+/**
+ * Returns the inline-approval state for a tool call, or `null` when the call
+ * is not currently gated (no matching approval, or no submit handler wired).
+ *
+ * The returned `onSubmit` is pre-bound to `toolCallId` and stable across
+ * renders, so it can flow straight into a memoized approval body.
+ *
+ * @example
+ * ```tsx
+ * const approval = useApproval(toolCall.id);
+ * if (approval) {
+ *   return <ApprovalCardBody {...approval} />;
+ * }
+ * ```
+ */
+export function useApproval(toolCallId: string): UseApprovalResult | null {
+  const { approvalsByToolCallId, onSubmit, submittingIds, errorsByToolCallId } =
+    useContext(ApprovalContext);
+
+  const handleSubmit = useCallback(
+    (action: ApprovalAction, comment?: string) => {
+      onSubmit?.(toolCallId, action, comment);
+    },
+    [onSubmit, toolCallId],
+  );
+
+  const pendingApproval = toolCallId
+    ? approvalsByToolCallId.get(toolCallId)
+    : undefined;
+  if (!pendingApproval || !onSubmit) return null;
+
+  return {
+    pendingApproval,
+    onSubmit: handleSubmit,
+    isSubmitting: submittingIds.has(toolCallId),
+    error: errorsByToolCallId.get(toolCallId) ?? null,
+  };
+}

package/src/execution/ArtifactCard.tsx

@@ -4,6 +4,7 @@ import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agent
 import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 import { useArtifactContent } from "./useArtifactContent";
+import { useArtifactDownload } from "./useArtifactDownload";
 import { isTextArtifact, formatArtifactSize } from "./artifact-utils";
 import { useDetectStigmerResource } from "../library/useDetectStigmerResource";
 import { useDetectSkillPackage } from "../library/useDetectSkillPackage";
@@ -148,6 +149,8 @@ export function ArtifactCard({
 
   const canPreview = !!onPreview && (isTextArtifact(artifact) || isDirectory);
 
+  const { download, isDownloading } = useArtifactDownload(executionId);
+
   const parentDir =
     hasNameCollision && artifact.sandboxPath
       ? parentDirectory(artifact.sandboxPath)
@@ -211,17 +214,18 @@ export function ArtifactCard({
             Preview
           </button>
         )}
-        <a
-          href={artifact.downloadUrl}
-          download
+        <button
+          type="button"
+          onClick={() => download(artifact.storageKey, artifact.name)}
+          disabled={isDownloading}
           className={cn(
-            "inline-flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground",
+            "inline-flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground disabled:opacity-50",
             FOCUS_RING_CLASSES,
           )}
         >
           <DownloadIcon />
-          {isDirectory ? "Download ZIP" : "Download"}
-        </a>
+          {isDownloading ? "Preparing…" : isDirectory ? "Download ZIP" : "Download"}
+        </button>
       </div>
 
     </div>

package/src/execution/ArtifactPreviewModal.tsx

@@ -5,6 +5,7 @@ import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agent
 import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 import { useArtifactContent } from "./useArtifactContent";
+import { useArtifactDownload } from "./useArtifactDownload";
 import { isTextArtifact, formatArtifactSize } from "./artifact-utils";
 import { ArtifactContentRenderer } from "./ArtifactContentRenderer";
 import { useDetectStigmerResource } from "../library/useDetectStigmerResource";
@@ -269,6 +270,7 @@ export function ArtifactPreviewContent({
 
       <ActionBar
         artifact={artifact}
+        executionId={executionId}
         isDirectory={isDirectory}
         hasContent={content !== null}
         copied={copied}
@@ -622,6 +624,7 @@ function EntryIcon({ name }: { readonly name: string }) {
 
 function ActionBar({
   artifact,
+  executionId,
   isDirectory,
   hasContent,
   copied,
@@ -636,6 +639,7 @@ function ActionBar({
   onImplement,
 }: {
   readonly artifact: ExecutionArtifact;
+  readonly executionId: string;
   readonly isDirectory: boolean;
   readonly hasContent: boolean;
   readonly copied: boolean;
@@ -649,6 +653,7 @@ function ActionBar({
   readonly onApply: () => void;
   readonly onImplement?: () => void;
 }) {
+  const { download, isDownloading } = useArtifactDownload(executionId);
   return (
     <div className="flex items-center justify-between gap-3 border-t border-border px-4 py-3">
       <div className="flex items-center gap-3">
@@ -670,17 +675,18 @@ function ActionBar({
           </button>
         )}
 
-        <a
-          href={artifact.downloadUrl}
-          download
+        <button
+          type="button"
+          onClick={() => download(artifact.storageKey, artifact.name)}
+          disabled={isDownloading}
           className={cn(
-            "inline-flex items-center gap-1.5 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground",
+            "inline-flex items-center gap-1.5 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground disabled:opacity-50",
             FOCUS_RING_CLASSES,
           )}
         >
           <DownloadIcon />
-          {isDirectory ? "Download ZIP" : "Download"}
-        </a>
+          {isDownloading ? "Preparing…" : isDirectory ? "Download ZIP" : "Download"}
+        </button>
       </div>
 
       <div className="flex shrink-0 items-center gap-3">

package/src/execution/EmptyChangeNotice.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+/**
+ * Which empty file-change state to describe.
+ *
+ * - `"empty-create"` — a new file proven to have no content (the approval gate's
+ *   proto `FileChange` carries `changeType === CREATE` with an empty body).
+ * - `"create"` — a new file IS being written, but its proposed content could not
+ *   be captured for preview (the rare content-less FILE_WRITE gate, e.g. a
+ *   no-stream denial synthesis). Distinguished from `empty-create` because the
+ *   file is not proven empty — only proven to be a write/create.
+ * - `"no-preview"` — the change carries no renderable diff/content AND cannot be
+ *   proven to be a create (e.g. a path-only resume placeholder for an edit).
+ *   Never claims emptiness or creation it cannot prove.
+ */
+export type EmptyChangeKind = "empty-create" | "create" | "no-preview";
+
+const MESSAGE: Record<EmptyChangeKind, string> = {
+  "empty-create": "New empty file",
+  create: "New file — preview unavailable",
+  "no-preview": "No preview available for this change",
+};
+
+/** Props for {@link EmptyChangeNotice}. */
+export interface EmptyChangeNoticeProps {
+  /** The empty-change state to describe. */
+  readonly kind: EmptyChangeKind;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * A quiet, neutral notice rendered in place of a diff when a file change has
+ * nothing to show — a newly created empty file, or a change whose content is
+ * genuinely unavailable.
+ *
+ * It is the single owner of both messages so the approval gate and the
+ * post-execution detail can never drift apart in wording. The two cases are
+ * deliberately distinct: an honest "new empty file" requires proof (the gate's
+ * proto change type), while everything else degrades to the non-committal
+ * "no preview available" rather than misrepresenting an uncaptured change as
+ * empty.
+ *
+ * Styled to match the `Notice` used elsewhere in the change views (neutral
+ * border + muted surface, tokens only — DD-005).
+ */
+export function EmptyChangeNotice({ kind, className }: EmptyChangeNoticeProps) {
+  return (
+    <div
+      role="status"
+      data-cursor-target="empty-change-notice"
+      className={cn(
+        "rounded-md border border-border bg-muted-subtle px-3 py-2 text-xs text-muted-foreground",
+        className,
+      )}
+    >
+      {MESSAGE[kind]}
+    </div>
+  );
+}

package/src/execution/FileChangesView.tsx

@@ -0,0 +1,383 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  FileChangeCaptureLevel,
+  FileChangeType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { cn } from "@stigmer/theme";
+import { BoundedContent } from "../internal/BoundedContent";
+import { computeDiff } from "../version-history/computeDiff";
+import { DiffViewer } from "../version-history/DiffViewer";
+import { DiffFileList } from "../version-history/DiffFileList";
+import { DiffSummary } from "../version-history/DiffSummary";
+import { UnifiedDiffView } from "../version-history/UnifiedDiffView";
+import type { DiffHunk, FileDiffEntry } from "../version-history/types";
+import { FilePathLink } from "./FilePathLink";
+import { EmptyChangeNotice } from "./EmptyChangeNotice";
+import { useFileChangeContent } from "./useFileChangeContent";
+
+/** Props for {@link FileChangesView}. */
+export interface FileChangesViewProps {
+  /**
+   * Net file changes to render, typically from {@link useSessionFileChanges}.
+   * One entry per changed file.
+   */
+  readonly changes: readonly FileChange[];
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Consolidated, GitHub-style view of the files an agent changed: a summary
+ * bar, a file selector (when more than one file changed), and the unified diff
+ * for the selected file.
+ *
+ * Renders the runner's authoritative {@link FileChange} captures directly
+ * (proto-first). Whole-file captures (native) become a true before/after diff;
+ * hunk-only captures (Cursor today) render their unified diff; offloaded bodies
+ * are fetched lazily only when their file is opened (see {@link FileChangeDiff}).
+ *
+ * Zero Console dependencies — safe for platform builder embedding.
+ *
+ * @example
+ * ```tsx
+ * const { fileChanges } = useSessionFileChanges(allExecutions);
+ * <FileChangesView changes={fileChanges} />
+ * ```
+ */
+export function FileChangesView({ changes, className }: FileChangesViewProps) {
+  const entries = useMemo<readonly FileDiffEntry[]>(
+    () => changes.map(toFileDiffEntry),
+    [changes],
+  );
+
+  const [selectedPath, setSelectedPath] = useState<string | null>(
+    changes[0]?.path ?? null,
+  );
+
+  const selected =
+    changes.find((c) => c.path === selectedPath) ?? changes[0] ?? null;
+
+  const totals = useMemo(
+    () =>
+      entries.reduce(
+        (acc, e) => ({
+          additions: acc.additions + e.additions,
+          deletions: acc.deletions + e.deletions,
+        }),
+        { additions: 0, deletions: 0 },
+      ),
+    [entries],
+  );
+
+  if (changes.length === 0 || !selected) return null;
+
+  return (
+    <div className={cn("flex flex-col gap-3", className)}>
+      <DiffSummary
+        fileCount={changes.length}
+        additions={totals.additions}
+        deletions={totals.deletions}
+      />
+
+      {changes.length > 1 && (
+        <div className="overflow-hidden rounded-lg border border-border">
+          <DiffFileList
+            files={entries}
+            selectedPath={selected.path}
+            onSelect={setSelectedPath}
+          />
+        </div>
+      )}
+
+      <FileChangeDiff key={selected.path} change={selected} />
+    </div>
+  );
+}
+
+/** Props for {@link FileChangeDiff}. */
+export interface FileChangeDiffProps {
+  /** The single file change to render. */
+  readonly change: FileChange;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+  /**
+   * Optional class applied to the scrolling diff body (the `DiffViewer` table or
+   * unified-diff `<pre>`). A raw height cap with no reveal control; prefer
+   * {@link bounded} for the consistent clamp-and-reveal used across tool cards.
+   */
+  readonly bodyClassName?: string;
+  /**
+   * When `true`, the diff body is wrapped in the shared {@link BoundedContent}
+   * primitive: clamped to the standard preview height with a bottom fade and an
+   * in-place "Show more" / "Show less", identical to the always-visible
+   * edit/write diff body in the timeline. Defaults to `false` so the dedicated
+   * Changes view ({@link FileChangesView}) renders the full diff; the approval
+   * gate opts in so a large change cannot push the decision buttons off-screen
+   * while still letting the reviewer expand the whole diff in place.
+   */
+  readonly bounded?: boolean;
+  /**
+   * Whether to render the filename header (the `FilePathLink` + any rename
+   * prefix). Defaults to `true`. Set to `false` where an ancestor already names
+   * the file — the approval gate header, or a tool-call row — so the diff is not
+   * captioned with a path the user just read; the `+N -M` stats still render.
+   */
+  readonly showFileName?: boolean;
+  /**
+   * Whether to render the `+N -M` summary. Defaults to `true`. Set to `false`
+   * where an ancestor row already shows the result summary (a tool-call row) so
+   * the body does not repeat the counts. Orthogonal to {@link showFileName}: the
+   * approval gate suppresses the name but keeps the stats.
+   */
+  readonly showStats?: boolean;
+}
+
+/**
+ * Renders the diff for a single {@link FileChange}, adapting to how completely
+ * the runner captured it:
+ *
+ * - **Whole-file** (native): a true before/after diff via {@link DiffViewer}.
+ *   Offloaded bodies are fetched lazily; loading, error, and too-large
+ *   (server-truncated) states are surfaced honestly.
+ * - **Hunk-only** (Cursor today): the captured unified diff, labeled as such.
+ * - **Binary**: a "binary file changed" notice instead of a text diff.
+ *
+ * Importable on its own by platform builders composing custom change UIs.
+ */
+export function FileChangeDiff({
+  change,
+  className,
+  bodyClassName,
+  bounded = false,
+  showFileName = true,
+  showStats = true,
+}: FileChangeDiffProps) {
+  const { beforeText, afterText, isBinary, isLoading, error, isTruncated, downloadUrl } =
+    useFileChangeContent(change);
+
+  const hunks = useMemo<readonly DiffHunk[]>(() => {
+    if (beforeText === null || afterText === null) return [];
+    return computeDiff(beforeText, afterText);
+  }, [beforeText, afterText]);
+
+  const stats = useMemo(() => {
+    if (change.captureLevel === FileChangeCaptureLevel.HUNK_ONLY) {
+      return { additions: change.linesAdded, deletions: change.linesRemoved };
+    }
+    return countHunks(hunks);
+  }, [change.captureLevel, change.linesAdded, change.linesRemoved, hunks]);
+
+  const showStatsRow = showStats && (stats.additions > 0 || stats.deletions > 0);
+
+  return (
+    <div
+      className={cn("flex flex-col gap-1.5", className)}
+      data-cursor-target="file-diff"
+    >
+      {(showFileName || showStatsRow) && (
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          {showFileName &&
+            change.changeType === FileChangeType.RENAME &&
+            change.renameFrom && (
+              <span className="min-w-0 truncate font-mono text-muted-foreground-faint">
+                {change.renameFrom} →
+              </span>
+            )}
+          {showFileName && (
+            <FilePathLink path={change.path} dirDisplay="dim" className="text-xs" />
+          )}
+          {showStatsRow && (
+            <span className="shrink-0 tabular-nums">
+              <span className="text-diff-added-fg">+{stats.additions}</span>{" "}
+              <span className="text-diff-removed-fg">-{stats.deletions}</span>
+            </span>
+          )}
+        </div>
+      )}
+
+      <FileChangeBody
+        change={change}
+        hunks={hunks}
+        isBinary={isBinary}
+        isLoading={isLoading}
+        error={error}
+        isTruncated={isTruncated}
+        downloadUrl={downloadUrl}
+        bodyClassName={bodyClassName}
+        bounded={bounded}
+      />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Body — the capture-level / fetch-state switch
+// ---------------------------------------------------------------------------
+
+function FileChangeBody({
+  change,
+  hunks,
+  isBinary,
+  isLoading,
+  error,
+  isTruncated,
+  downloadUrl,
+  bodyClassName,
+  bounded,
+}: {
+  change: FileChange;
+  hunks: readonly DiffHunk[];
+  isBinary: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  isTruncated: boolean;
+  downloadUrl: string | null;
+  bodyClassName?: string;
+  bounded: boolean;
+}) {
+  // A CREATE with no renderable diff is a genuinely empty new file; anything
+  // else with no content degrades to the non-committal "no preview" (we never
+  // claim emptiness we cannot prove from the capture).
+  const emptyKind =
+    change.changeType === FileChangeType.CREATE ? "empty-create" : "no-preview";
+
+  // When bounded, the actual diff renderers (and only those — short notices need
+  // no clamp) are wrapped in the shared BoundedContent budget, so the gate's
+  // diff matches the timeline edit/write diff and never crowds out the buttons.
+  const bound = (node: React.ReactNode) =>
+    bounded ? (
+      <BoundedContent cursorTarget="file-diff-expand">{node}</BoundedContent>
+    ) : (
+      node
+    );
+
+  if (isBinary) {
+    return <Notice>Binary file changed.</Notice>;
+  }
+
+  if (change.captureLevel === FileChangeCaptureLevel.HUNK_ONLY) {
+    return change.unifiedDiff ? (
+      bound(<UnifiedDiffView patch={change.unifiedDiff} className={bodyClassName} />)
+    ) : (
+      <EmptyChangeNotice kind={emptyKind} className={bodyClassName} />
+    );
+  }
+
+  // Whole-file: content may be inline (ready) or offloaded (fetched lazily).
+  if (isTruncated) {
+    return (
+      <Notice>
+        This file is too large to diff inline.{" "}
+        {downloadUrl && (
+          <a
+            href={downloadUrl}
+            target="_blank"
+            rel="noreferrer"
+            className="font-medium text-primary underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            Download the full file
+          </a>
+        )}
+      </Notice>
+    );
+  }
+
+  if (isLoading) {
+    return <Notice>Loading diff…</Notice>;
+  }
+
+  if (error) {
+    return <Notice variant="error">Could not load this file's contents.</Notice>;
+  }
+
+  if (hunks.length === 0) {
+    return <EmptyChangeNotice kind={emptyKind} className={bodyClassName} />;
+  }
+
+  return bound(<DiffViewer hunks={hunks} className={bodyClassName} />);
+}
+
+function Notice({
+  children,
+  variant = "muted",
+}: {
+  children: React.ReactNode;
+  variant?: "muted" | "error";
+}) {
+  return (
+    <div
+      role="status"
+      className={cn(
+        "rounded-md border border-border bg-muted-subtle px-3 py-2 text-xs",
+        variant === "error" ? "text-destructive" : "text-muted-foreground",
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function countHunks(hunks: readonly DiffHunk[]): {
+  additions: number;
+  deletions: number;
+} {
+  let additions = 0;
+  let deletions = 0;
+  for (const hunk of hunks) {
+    for (const line of hunk.lines) {
+      if (line.type === "added") additions++;
+      else if (line.type === "removed") deletions++;
+    }
+  }
+  return { additions, deletions };
+}
+
+/**
+ * Projects a {@link FileChange} into a {@link FileDiffEntry} for the file list.
+ *
+ * Counts: hunk-only uses the runner's authoritative numbers; whole-file inline
+ * is derived from the content; an offloaded whole-file side has no synchronous
+ * content, so its count stays 0 until the file is opened and fetched.
+ */
+function toFileDiffEntry(change: FileChange): FileDiffEntry {
+  const changeType =
+    change.changeType === FileChangeType.CREATE
+      ? "added"
+      : change.changeType === FileChangeType.DELETE
+        ? "removed"
+        : "modified";
+
+  if (change.captureLevel === FileChangeCaptureLevel.HUNK_ONLY) {
+    return {
+      path: change.path,
+      changeType,
+      additions: change.linesAdded,
+      deletions: change.linesRemoved,
+    };
+  }
+
+  const before = inlineSide(change.before);
+  const after = inlineSide(change.after);
+  if (before !== null && after !== null) {
+    const { additions, deletions } = countHunks(computeDiff(before, after));
+    return { path: change.path, changeType, additions, deletions };
+  }
+
+  return { path: change.path, changeType, additions: 0, deletions: 0 };
+}
+
+/** Inline text of a side, or null when absent/offloaded/binary. */
+function inlineSide(
+  side: FileChange["before"],
+): string | null {
+  if (!side) return "";
+  if (side.isBinary) return null;
+  return side.body.case === "inline" ? side.body.value : null;
+}