@stigmer/react 3.1.3 → 3.1.5

package/src/session/useSessionConversation.ts

@@ -117,6 +117,15 @@ export interface SendFollowUpOptions {
    * @see {@link CreateAgentExecutionInput.workspaceFileRefs}
    */
   readonly workspaceFileRefs?: string[];
+  /**
+   * ID of the execution this follow-up supersedes (edit-and-resubmit).
+   *
+   * The conversation read model hides the superseded execution so the
+   * edited message replaces the original in place.
+   *
+   * @see {@link CreateAgentExecutionInput.supersedesExecutionId}
+   */
+  readonly supersedesExecutionId?: string;
 }
 
 /**
@@ -129,7 +138,14 @@ export interface SendFollowUpOptions {
 export interface UseSessionConversationReturn {
   /** The session object, or null while loading. */
   readonly session: Session | null;
-  /** Executions in terminal phases, in chronological order. */
+  /**
+   * Executions in terminal phases, in chronological order.
+   *
+   * Excludes turns replaced via edit-and-resubmit (an execution whose id
+   * appears as another execution's `supersedesExecutionId`) — the edited
+   * message stands in the original's place. Superseded records remain in
+   * execution history surfaces; only the conversation view hides them.
+   */
   readonly completedExecutions: readonly AgentExecution[];
   /** Currently streaming execution (stream or fetch fallback), or null. */
   readonly activeStreamExecution: AgentExecution | null;
@@ -491,12 +507,37 @@ export function useSessionConversation(
     }
   }, [activeExecutionId, stream.phase, refetch]);
 
+  // Executions replaced via edit-and-resubmit. The successor carries
+  // `spec.supersedes_execution_id`; hiding the superseded turn makes the
+  // edited message read as a single corrected exchange (in-place replace).
+  // The link must also be read off the live stream copy — right after a
+  // resubmit, the successor streams before the list refetch delivers it.
+  // Display-only: the raw `executions` list (and therefore active-id
+  // resolution above) is never filtered.
+  //
+  // Dep is the scalar link, NOT stream.execution: the stream object changes
+  // reference every frame, and rebuilding the Set per frame would hand
+  // MessageThread a fresh executions array mid-stream, defeating its
+  // memoization (DD-010).
+  const streamSupersededId =
+    stream.execution?.spec?.supersedesExecutionId || null;
+  const supersededIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const e of executions) {
+      const superseded = e.spec?.supersedesExecutionId;
+      if (superseded) ids.add(superseded);
+    }
+    if (streamSupersededId) ids.add(streamSupersededId);
+    return ids;
+  }, [executions, streamSupersededId]);
+
   const completedExecutions = useMemo(() => {
-    if (!activeExecutionId) return executions;
-    return executions.filter(
-      (e) => (e.metadata?.id ?? "") !== activeExecutionId,
-    );
-  }, [executions, activeExecutionId]);
+    return executions.filter((e) => {
+      const id = e.metadata?.id ?? "";
+      if (activeExecutionId && id === activeExecutionId) return false;
+      return !supersededIds.has(id);
+    });
+  }, [executions, activeExecutionId, supersededIds]);
 
   const fetchedActiveExecution = useMemo(() => {
     if (!activeExecutionId) return null;
@@ -604,6 +645,7 @@ export function useSessionConversation(
           buildFromPlan: options?.buildFromPlan,
           autoApproveAll: options?.autoApproveAll,
           workspaceFileRefs: options?.workspaceFileRefs,
+          supersedesExecutionId: options?.supersedesExecutionId,
         });
         setPendingExecutionId(result.executionId);
         refetch();

package/src/session/useSessionPageFlow.ts

@@ -410,6 +410,7 @@ export function useSessionPageFlow(
         // not from the composer (the pre-arm toggle was removed).
         autoApproveAll: autoApproveAll || undefined,
         workspaceFileRefs: context?.workspaceFileRefs,
+        supersedesExecutionId: context?.supersedesExecutionId,
       });
 
       sessionVariables.clear();

package/src/session/useSessionPanel.ts

@@ -2,6 +2,7 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { isTerminalPhase } from "../execution/execution-phases.js";
 import type { SelectedThreadItem } from "../internal/store/selection-store.js";
 import {
@@ -10,6 +11,8 @@ import {
   type WorkspaceEditorsStore,
 } from "../internal/store/index.js";
 import { PLAN_DOCUMENT_ENTRY_ID, PLAN_DOCUMENT_PATH } from "./plan-document.js";
+import { ARTIFACT_DOCUMENT_ENTRY_ID } from "./artifact-document.js";
+import { artifactKey } from "./useSessionArtifacts.js";
 
 /** Options for {@link useSessionPanel}. */
 export interface UseSessionPanelOptions {
@@ -118,6 +121,25 @@ export interface SessionPanelController {
    * both when a plan STARTS STREAMING and when it publishes (see `planKey`).
    */
   readonly openPlanDocument: () => void;
+  /**
+   * Open (or focus) an artifact as an editor-pane document tab and expand the
+   * panel. Uses the PREVIEW slot — like files and content-search hits, casual
+   * artifact browsing reuses one tab (single-click), and double-clicking the
+   * tab pins it. Distinct from `openPlanDocument`, which pins its single tab: a
+   * plan is the turn's deliverable, artifacts are browsable outputs. The
+   * artifact's {@link artifactKey} is the tab identity, shared with the
+   * `SurfaceVirtualDocument` the viewer builds for the open tab.
+   */
+  readonly openArtifact: (artifact: ExecutionArtifact) => void;
+  /**
+   * Pin an artifact's tab (clear its preview state) — the double-click half of
+   * the open/activate split, the encapsulated sibling of {@link openArtifact}.
+   * Delegates to the editors store's generic `pin`, exactly as the file tree
+   * pins via `pinEditor`: the leading single-click of the double-click has
+   * already opened the preview tab, so this promotes it to a persistent tab. A
+   * no-op if the artifact is not open.
+   */
+  readonly pinArtifact: (artifact: ExecutionArtifact) => void;
   /**
    * Report the current thread-item selection. Called from an effect inside the
    * panel subtree (the level that subscribes to the selection store), keeping
@@ -224,6 +246,21 @@ export function useSessionPanel({
     [editorsStore],
   );
 
+  const openArtifact = useCallback(
+    (artifact: ExecutionArtifact) => {
+      editorsStore.openPreview(ARTIFACT_DOCUMENT_ENTRY_ID, artifactKey(artifact));
+      setIsOpen(true);
+    },
+    [editorsStore],
+  );
+
+  const pinArtifact = useCallback(
+    (artifact: ExecutionArtifact) => {
+      editorsStore.pin(ARTIFACT_DOCUMENT_ENTRY_ID, artifactKey(artifact));
+    },
+    [editorsStore],
+  );
+
   const activateEditor = useCallback(
     (entryId: string, path: string) => editorsStore.activate(entryId, path),
     [editorsStore],
@@ -268,6 +305,8 @@ export function useSessionPanel({
       pinEditor,
       closeEditor,
       openPlanDocument,
+      openArtifact,
+      pinArtifact,
       notifySelection,
     }),
     [
@@ -282,6 +321,8 @@ export function useSessionPanel({
       pinEditor,
       closeEditor,
       openPlanDocument,
+      openArtifact,
+      pinArtifact,
       notifySelection,
     ],
   );

package/src/session/useSessionRailViews.tsx

@@ -6,7 +6,10 @@ import type { SurfaceRailView } from "../workspace/WorkspaceSurface.js";
 import type { SelectedThreadItem } from "../internal/store/selection-store.js";
 import type { ApplyResourceResult } from "../library/useApplyResource.js";
 import { useSessionWriteBacks } from "./useSessionWriteBacks.js";
-import { useSessionArtifacts } from "./useSessionArtifacts.js";
+import {
+  useSessionArtifacts,
+  type SessionArtifactEntry,
+} from "./useSessionArtifacts.js";
 import { SetupTab, type SetupTabProps } from "./facets/SetupTab.js";
 import { ChangesTab } from "./facets/ChangesTab.js";
 import { ArtifactsTab } from "./facets/ArtifactsTab.js";
@@ -33,6 +36,17 @@ export interface UseSessionRailViewsOptions {
    * of the preview modal.
    */
   readonly onOpenPlan?: (executionId: string) => void;
+  /**
+   * Open a (non-plan) artifact as an editor-pane document tab. Routed to the
+   * Artifacts facet so clicking an artifact opens it in the editor area (VS
+   * Code "each file is a tab") instead of the preview modal.
+   */
+  readonly onOpenArtifact?: (entry: SessionArtifactEntry) => void;
+  /**
+   * Pin a (non-plan) artifact's document tab — the double-click half of the
+   * Artifacts facet's open/activate split. Routed through to the facet's rows.
+   */
+  readonly onActivateArtifact?: (entry: SessionArtifactEntry) => void;
   /**
    * Whether to offer the execution-derived facets (Changes / Artifacts /
    * Usage). The launcher passes `false` — before a session exists there are no
@@ -60,6 +74,8 @@ export function useSessionRailViews({
   onApplied,
   onImplementPlan,
   onOpenPlan,
+  onOpenArtifact,
+  onActivateArtifact,
   includeExecutionFacets = true,
 }: UseSessionRailViewsOptions): readonly SurfaceRailView[] {
   const { hasWriteBacks, writeBackCount } = useSessionWriteBacks(allExecutions);
@@ -101,6 +117,8 @@ export function useSessionRailViews({
               onApplied={onApplied}
               onImplementPlan={onImplementPlan}
               onOpenPlan={onOpenPlan}
+              onOpenArtifact={onOpenArtifact}
+              onActivateArtifact={onActivateArtifact}
             />
           ),
         });
@@ -136,6 +154,8 @@ export function useSessionRailViews({
     onApplied,
     onImplementPlan,
     onOpenPlan,
+    onOpenArtifact,
+    onActivateArtifact,
     selectedItem,
   ]);
 }

package/src/session/useWorkspaceReadRefs.ts

@@ -0,0 +1,118 @@
+"use client";
+
+import { useMemo } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
+
+/**
+ * Pure derivation hook that projects the session's workspace write-backs onto
+ * its workspace entries as per-entry read refs.
+ *
+ * The agent's file changes land on a write-back branch (`stigmer/<id>`), not
+ * the branch the session was configured with — so read-side surfaces (file
+ * viewer, tree listing, name search) pointed at the configured branch would
+ * 404 on agent-created files and silently show stale content for modified
+ * ones. This hook returns the entries with `readRef` set to the latest
+ * write-back commit SHA, which those surfaces resolve in preference to
+ * `gitBranch`. A commit SHA (not the branch name) so reads are immutable-ref
+ * exact, immune to branch eventual-consistency.
+ *
+ * **Ref selection:** the latest write-back with a non-empty `commitSha` wins
+ * per workspace entry, across all executions in chronological order. FAILED
+ * write-back records carry no SHA and never regress the ref.
+ *
+ * **Entry matching** mirrors the runner's `WriteBackCoordinator.resolveEntry`:
+ * single-entry sessions provision with an empty `workspaceEntryName`, so when
+ * the session has exactly one git entry every write-back applies to it;
+ * multi-entry sessions match strictly by name.
+ *
+ * **Reference stability (DD-010):** the decorated array is memoized on the
+ * entries array and a value signature of the derived refs — streaming frames
+ * that don't change any write-back SHA return the identical array, so
+ * downstream listing/content effects never churn.
+ *
+ * @param executions - All executions for the session, in chronological order
+ *   (same input contract as {@link useSessionWriteBacks}).
+ * @param entries - The session's workspace entries. Returned as-is (same
+ *   reference) when no entry derives a ref.
+ *
+ * @example
+ * ```tsx
+ * const surfaceEntries = useWorkspaceReadRefs(flow.allExecutions, flow.workspace.entries);
+ * <WorkspaceSurface entries={surfaceEntries} ... />
+ * ```
+ *
+ * @see useSessionWriteBacks — the write-back list this projection derives from
+ * @see WorkspaceEntry.readRef — the field this hook populates
+ */
+export function useWorkspaceReadRefs(
+  executions: readonly AgentExecution[],
+  entries: readonly WorkspaceEntry[],
+): readonly WorkspaceEntry[] {
+  // Cheap per-render pass; memoizing on `executions` would defeat the point —
+  // its identity changes every streaming frame while the SHAs rarely do. The
+  // signature collapses those frames into a stable memo key.
+  const refByName = collectLatestShas(executions);
+  const signature = [...refByName]
+    .map(([name, sha]) => `${name}\u0001${sha}`)
+    .join("\u0000");
+
+  return useMemo(() => {
+    if (refByName.size === 0) return entries;
+
+    const gitEntries = entries.filter((entry) => entry.type === "git");
+    let decorated = false;
+
+    const next = entries.map((entry) => {
+      const readRef = resolveReadRef(entry, gitEntries.length, refByName);
+      if (!readRef || readRef === entry.readRef) return entry;
+      decorated = true;
+      return { ...entry, readRef };
+    });
+
+    return decorated ? next : entries;
+    // `signature` is the value-equality key for `refByName` (rebuilt each
+    // render); the map itself must stay out of the deps.
+  }, [entries, signature]);
+}
+
+/** Latest non-empty write-back commit SHA per workspace entry name. */
+function collectLatestShas(
+  executions: readonly AgentExecution[],
+): Map<string, string> {
+  const refByName = new Map<string, string>();
+  for (const execution of executions) {
+    for (const wb of execution.status?.workspaceWriteBacks ?? []) {
+      if (wb.commitSha) refByName.set(wb.workspaceEntryName, wb.commitSha);
+    }
+  }
+  return refByName;
+}
+
+/**
+ * The write-back SHA for one entry, honoring the runner's single-entry
+ * convention: with exactly one git entry, any write-back applies to it
+ * (single-entry sessions write back under an empty entry name).
+ */
+function resolveReadRef(
+  entry: WorkspaceEntry,
+  gitEntryCount: number,
+  refByName: ReadonlyMap<string, string>,
+): string | undefined {
+  if (entry.type !== "git") return undefined;
+
+  const byName = refByName.get(entry.name);
+  if (byName) return byName;
+
+  if (gitEntryCount === 1) {
+    // Single-entry sessions write back under an empty entry name; a lone
+    // unambiguous name is equally safe to claim. Anything else (multiple
+    // names against one entry) is malformed status data — decorate nothing
+    // rather than guess.
+    const unnamed = refByName.get("");
+    if (unnamed) return unnamed;
+    if (refByName.size === 1) return refByName.values().next().value;
+  }
+
+  return undefined;
+}

package/src/workspace/FileViewer.tsx

@@ -11,14 +11,21 @@ import {
 } from "react";
 import { cn } from "@stigmer/theme";
 import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
-import { FileChangeType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  FileChangeCaptureLevel,
+  FileChangeType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { ArtifactContentRenderer } from "../execution/ArtifactContentRenderer.js";
 import { FileChangeDiff } from "../execution/FileChangesView.js";
+import { useFileChangeContent } from "../execution/useFileChangeContent.js";
 import type { RevealTarget } from "../internal/useRevealLine.js";
 import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
 import { useWorkspaceFileContent } from "./useWorkspaceFileContent.js";
 import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
-import type { WorkspaceFileReader } from "./WorkspaceFileReader.js";
+import {
+  WorkspaceFileNotFoundError,
+  type WorkspaceFileReader,
+} from "./WorkspaceFileReader.js";
 
 /** Line-skeleton widths, mirroring `FileContentStateView` in `ArtifactPreviewModal`. */
 const SKELETON_LINE_WIDTHS = [85, 72, 90, 65, 78, 88, 70, 82] as const;
@@ -218,22 +225,16 @@ export const FileViewer = forwardRef<FileViewerHandle, FileViewerProps>(
             <FileChangeDiff change={change} showFileName={false} showStats />
           </div>
         ) : (
-          <>
-            {change && (
-              <p className="border-b border-border-muted px-4 py-1.5 text-[0.65rem] text-muted-foreground">
-                Live — may differ from the reviewed change.
-              </p>
-            )}
-            <FileViewerBody
-              basename={basename}
-              content={content}
-              isLoading={isLoading}
-              isUnsupported={isUnsupported}
-              error={error}
-              onRetry={refetch}
-              reveal={reveal}
-            />
-          </>
+          <FileViewerBody
+            basename={basename}
+            content={content}
+            isLoading={isLoading}
+            isUnsupported={isUnsupported}
+            error={error}
+            onRetry={refetch}
+            reveal={reveal}
+            change={change}
+          />
         )}
       </div>
     </div>
@@ -328,6 +329,23 @@ function ViewerModeToggle({
 // Body — exactly one state, mirroring FileContentStateView + workspace extras
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether the session captured this change's full after-content — the
+ * precondition for serving it when the live substrate can't (a cloud file not
+ * yet pushed to any readable ref). A DELETE has no after side, and a
+ * HUNK_ONLY capture carries only the diff, never the whole file.
+ */
+function hasCapturedAfterContent(
+  change: FileChange | undefined,
+): change is FileChange {
+  return (
+    change !== undefined &&
+    change.changeType !== FileChangeType.DELETE &&
+    change.captureLevel !== FileChangeCaptureLevel.HUNK_ONLY &&
+    change.after !== undefined
+  );
+}
+
 function FileViewerBody({
   basename,
   content,
@@ -336,6 +354,7 @@ function FileViewerBody({
   error,
   onRetry,
   reveal,
+  change,
 }: {
   readonly basename: string;
   readonly content: ReturnType<typeof useWorkspaceFileContent>["content"];
@@ -344,7 +363,20 @@ function FileViewerBody({
   readonly error: Error | null;
   readonly onRetry: () => void;
   readonly reveal?: RevealTarget;
+  readonly change?: FileChange;
 }) {
+  // A live read that can't be served (unsupported substrate, or the file
+  // isn't at the read ref yet) degrades to the session's captured
+  // after-content when the change carries it — the same bytes the Diff view
+  // renders, so nothing is fabricated. Other errors keep the retry path.
+  const isNotFound = error instanceof WorkspaceFileNotFoundError;
+  const canFallBackToCaptured =
+    (isUnsupported || isNotFound) && hasCapturedAfterContent(change);
+
+  if (canFallBackToCaptured) {
+    return <CapturedFileContent change={change} basename={basename} reveal={reveal} />;
+  }
+
   // Unsupported comes first: a missing reader means there is nothing to load.
   if (isUnsupported) {
     return (
@@ -355,21 +387,25 @@ function FileViewerBody({
   }
 
   if (isLoading) {
+    return <LoadingSkeleton />;
+  }
+
+  if (isNotFound) {
+    // Expected while the agent's write-back is still syncing to the ref —
+    // a calm notice (DD-006), not a failure.
     return (
-      <div
-        role="status"
-        className="space-y-2 p-4"
-        aria-busy="true"
-        aria-label="Loading file"
-      >
-        {SKELETON_LINE_WIDTHS.map((width, i) => (
-          <div
-            key={i}
-            className="h-4 animate-pulse rounded bg-muted"
-            style={{ width: `${width}%` }}
-            aria-hidden="true"
-          />
-        ))}
+      <div className="flex flex-col items-center justify-center gap-2 p-8 text-center">
+        <p className="text-xs text-muted-foreground">
+          This file isn&rsquo;t available in the workspace source yet. The
+          agent&rsquo;s latest changes may still be syncing.
+        </p>
+        <button
+          type="button"
+          onClick={onRetry}
+          className="text-xs font-medium text-foreground underline underline-offset-2 hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:rounded-sm"
+        >
+          Check again
+        </button>
       </div>
     );
   }
@@ -417,12 +453,82 @@ function FileViewerBody({
   }
 
   return (
-    <ArtifactContentRenderer
-      content={content.text}
-      fileName={basename}
-      isTruncated={content.truncated}
-      reveal={reveal}
-    />
+    <>
+      {change && (
+        <p className="border-b border-border-muted px-4 py-1.5 text-[0.65rem] text-muted-foreground">
+          Live — may differ from the reviewed change.
+        </p>
+      )}
+      <ArtifactContentRenderer
+        content={content.text}
+        fileName={basename}
+        isTruncated={content.truncated}
+        reveal={reveal}
+      />
+    </>
+  );
+}
+
+/**
+ * The captured-content fallback: renders a change's after-side text (the
+ * bytes the session already holds — inline or offloaded to artifact storage)
+ * when no live substrate can serve the file. Mounted only when eligible, so
+ * its content fetch never runs for live-served files.
+ */
+function CapturedFileContent({
+  change,
+  basename,
+  reveal,
+}: {
+  readonly change: FileChange;
+  readonly basename: string;
+  readonly reveal?: RevealTarget;
+}) {
+  const { afterText, isBinary, isLoading, error } = useFileChangeContent(change);
+
+  if (isLoading) {
+    return <LoadingSkeleton />;
+  }
+
+  if (isBinary) {
+    return <MessageState>Binary file — not shown.</MessageState>;
+  }
+
+  if (error || afterText === null) {
+    return <MessageState>Content not available for preview.</MessageState>;
+  }
+
+  return (
+    <>
+      <p className="border-b border-border-muted px-4 py-1.5 text-[0.65rem] text-muted-foreground">
+        As of the agent&rsquo;s last change — not yet in the workspace source.
+      </p>
+      <ArtifactContentRenderer
+        content={afterText}
+        fileName={basename}
+        reveal={reveal}
+      />
+    </>
+  );
+}
+
+function LoadingSkeleton() {
+  return (
+    <div
+      role="status"
+      className="space-y-2 p-4"
+      aria-busy="true"
+      aria-label="Loading file"
+    >
+      {SKELETON_LINE_WIDTHS.map((width, i) => (
+        <div
+          key={i}
+          className="h-4 animate-pulse rounded bg-muted"
+          style={{ width: `${width}%` }}
+          aria-hidden="true"
+        />
+      ))}
+    </div>
   );
 }
 

package/src/workspace/WorkspaceFileReader.ts

@@ -32,6 +32,25 @@ export interface WorkspaceFileContent {
   readonly truncated?: boolean;
 }
 
+/**
+ * Thrown by a {@link WorkspaceFileReader} when the requested path does not
+ * exist at the entry's read ref — as opposed to a transport or permission
+ * failure.
+ *
+ * The distinction matters to consumers: a file the agent just created exists
+ * in session state before it exists at any readable ref, so "not found" is a
+ * recoverable, expected condition (the viewer falls back to the session's
+ * captured content), while a network error or 5xx is a genuine failure worth
+ * a retry affordance. Platform builders implementing custom readers should
+ * throw this class for their substrate's not-found condition.
+ */
+export class WorkspaceFileNotFoundError extends Error {
+  constructor(path: string) {
+    super(`"${path}" doesn't exist at the workspace's current ref.`);
+    this.name = "WorkspaceFileNotFoundError";
+  }
+}
+
 /**
  * Platform-injected callback that reads the content of a single workspace file.
  *
@@ -46,6 +65,8 @@ export interface WorkspaceFileContent {
  * - **Throws** on a genuine failure (404, network error, 5xx, unreadable file,
  *   a directory path). Consumers catch this into a distinct error state — a
  *   clicked file that 404s is "failed to load," not "unsupported here."
+ *   A missing path should throw {@link WorkspaceFileNotFoundError} so
+ *   consumers can distinguish "not there yet" from "broken."
  *
  * `path` is repo-relative for git entries and root-relative for local entries —
  * exactly the strings the matching `WorkspaceFileLister` emits, so a file-tree