@stigmer/react 3.1.4 → 3.1.5

package/src/github/useGitHubTreeLister.ts

@@ -38,7 +38,8 @@ const TRUNCATION_MARKER: WorkspaceFileEntry = {
  * Creates a {@link WorkspaceFileLister} backed by the GitHub Trees API.
  *
  * Uses the existing client-side OAuth token (same one that powers
- * `GitHubRepoPicker`) to call `GET /repos/{owner}/{repo}/git/trees/{branch}?recursive=1`.
+ * `GitHubRepoPicker`) to call `GET /repos/{owner}/{repo}/git/trees/{ref}?recursive=1`,
+ * where the ref is the entry's `readRef` (write-back commit) or `gitBranch`.
  *
  * Returns `null` for:
  * - Non-git workspace entries
@@ -64,8 +65,11 @@ export function useGitHubTreeLister(
       const parsed = parseGitUrl(entry.gitUrl);
       if (!parsed) return null;
 
-      const branch = entry.gitBranch || "main";
-      const url = `${GITHUB_TREES_API}/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(branch)}?recursive=1`;
+      // readRef (the session's write-back commit SHA, when one exists) wins
+      // over the configured branch, so the tree includes agent-created files.
+      // The Trees API accepts a branch name or a commit SHA interchangeably.
+      const ref = entry.readRef || entry.gitBranch || "main";
+      const url = `${GITHUB_TREES_API}/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
 
       const resp = await fetch(url, {
         headers: { Authorization: `Bearer ${token}` },

package/src/index.ts

@@ -71,6 +71,7 @@ export {
   useWorkspaceContentSearch,
   useWorkspaceSources,
   MAX_WORKSPACE_FILE_READ_BYTES,
+  WorkspaceFileNotFoundError,
   WorkspaceEditor,
   WorkspaceFileSearch,
   WorkspaceContentSearch,
@@ -131,6 +132,7 @@ export {
   useSessionArtifacts,
   artifactKey,
   useSessionWriteBacks,
+  useWorkspaceReadRefs,
   useSessionFileChanges,
   useSessionUsage,
   useAgentRefFromSession,
@@ -233,6 +235,7 @@ export {
   deriveEffectiveVerdicts,
   changeForRowPath,
   fileReviewRowState,
+  fileReviewRowChange,
   foldFileReviewEventStream,
   displayFileChangeSets,
   toDisplayFileChange,
@@ -290,6 +293,7 @@ export {
   useApproval,
   FileReviewContext,
   useFileReviewRowState,
+  useFileReviewRowChange,
   ArtifactRow,
   ArtifactContentRenderer,
   ArtifactContentBody,

package/src/internal/VirtualizedThread.tsx

@@ -15,6 +15,7 @@ import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 import {
   ThreadItemRenderer,
   threadContentColumnClass,
+  type MessageThreadSlots,
   type ThreadItem,
   type ThreadContentColumn,
 } from "../execution/MessageThread.js";
@@ -55,6 +56,7 @@ export interface VirtualizedThreadProps {
   readonly onRetrySend?: () => void;
   readonly onRetryExecution?: (message: string) => void;
   readonly onEditMessage?: (text: string) => void;
+  readonly slots?: MessageThreadSlots;
 }
 
 // ---------------------------------------------------------------------------
@@ -124,6 +126,7 @@ export function VirtualizedThread({
   onRetrySend,
   onRetryExecution,
   onEditMessage,
+  slots,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -161,8 +164,9 @@ export function VirtualizedThread({
       onRetrySend,
       onRetryExecution,
       onEditMessage,
+      slots,
     }),
-    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, onOpenPlan, org, planActionsDisabled, planBuildPending, onRetrySend, onRetryExecution, onEditMessage],
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds, approvalErrors, onBuildFromPlan, onOpenPlan, org, planActionsDisabled, planBuildPending, onRetrySend, onRetryExecution, onEditMessage, slots],
   );
 
   return (

package/src/session/SessionViewer.tsx

@@ -24,7 +24,7 @@ import { SelectionStore } from "../internal/store/selection-store.js";
 import { useWorkspaceEditors, isVirtualEntryId } from "../internal/store/index.js";
 import { ThreadSelectionContext } from "../execution/ThreadSelectionContext.js";
 import { useSelectedThreadItem } from "../execution/useThreadSelection.js";
-import { MessageThread } from "../execution/MessageThread.js";
+import { MessageThread, type MessageThreadSlots } from "../execution/MessageThread.js";
 import { FileChangeProgressBar } from "../execution/FileChangeProgressBar.js";
 import { FileReviewDock } from "../execution/FileReviewDock.js";
 import {
@@ -53,6 +53,7 @@ import { useSessionRailViews } from "./useSessionRailViews.js";
 import { useSessionPanel, type SessionPanelController } from "./useSessionPanel.js";
 import { SessionPanelChip } from "./SessionPanelChip.js";
 import { useSessionWriteBacks } from "./useSessionWriteBacks.js";
+import { useWorkspaceReadRefs } from "./useWorkspaceReadRefs.js";
 import {
   useSessionArtifacts,
   artifactKey,
@@ -228,6 +229,15 @@ export interface SessionViewerProps {
   readonly accessSlot?: ReactNode;
   /** Called after a resource is applied from the Artifacts tab. */
   readonly onApplied?: (result: ApplyResourceResult) => void;
+  /**
+   * Component overrides for the conversation thread's chrome (message
+   * bubbles, approval card, to-dos card, plan cards, thinking indicator) —
+   * forwarded to the inner {@link MessageThread}. See
+   * {@link MessageThreadSlots}. Define the object and its components at
+   * module level (or memoize) so thread rows keep their streaming
+   * re-render guarantees.
+   */
+  readonly threadSlots?: MessageThreadSlots;
   /** Additional CSS classes for the root container. */
   readonly className?: string;
 }
@@ -289,6 +299,7 @@ export function SessionViewer({
   headerActions,
   accessSlot,
   onApplied,
+  threadSlots,
   className,
 }: SessionViewerProps) {
   const flow = useSessionPageFlow({ sessionId, org, getRuntimeEnv });
@@ -572,6 +583,7 @@ export function SessionViewer({
               onDismissPlanAttachFailed={() => setPlanAttachFailed(false)}
               onFilePathClick={handleTranscriptFilePathClick}
               isEndUser={isEndUser}
+              threadSlots={threadSlots}
             />
           }
           secondary={
@@ -637,6 +649,7 @@ interface ConversationColumnProps {
    */
   readonly onFilePathClick: (path: string) => boolean;
   readonly isEndUser: boolean;
+  readonly threadSlots?: MessageThreadSlots;
 }
 
 const ConversationColumn = memo(function ConversationColumn({
@@ -658,6 +671,7 @@ const ConversationColumn = memo(function ConversationColumn({
   onDismissPlanAttachFailed,
   onFilePathClick,
   isEndUser,
+  threadSlots,
 }: ConversationColumnProps) {
   const { conv } = flow;
   // Approval failures are NOT folded into this banner: they now surface in-card,
@@ -770,6 +784,7 @@ const ConversationColumn = memo(function ConversationColumn({
         planActionsDisabled={!conv.canSendFollowUp || isBuildingFromPlan}
         planBuildPending={isBuildingFromPlan}
         contentColumn="center"
+        slots={threadSlots}
         className="flex-1"
       />
       <div className={CONVERSATION_COLUMN_CLASS}>
@@ -1133,9 +1148,19 @@ function SessionPanelRegion({
     if (path) flow.workspace.addLocalPath(path);
   }, [onBrowseLocalFolder, flow.workspace.addLocalPath]);
 
+  // Entries decorated with per-entry read refs (the latest write-back commit
+  // SHA), so the surface's read-side capabilities — file viewer, tree listing,
+  // name search — resolve at the ref the agent's changes actually live on. A
+  // read-side projection only: `flow.workspace.entries` stays undecorated for
+  // setup and session input.
+  const surfaceEntries = useWorkspaceReadRefs(
+    flow.allExecutions,
+    flow.workspace.entries,
+  );
+
   return (
     <WorkspaceSurface
-      entries={flow.workspace.entries}
+      entries={surfaceEntries}
       lister={workspaceFileLister}
       reader={workspaceFileReader}
       searcher={workspaceContentSearcher}

package/src/session/__tests__/useWorkspaceReadRefs.test.ts

@@ -0,0 +1,245 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import {
+  WorkspaceWriteBackSchema,
+  WorkspaceWriteBackPhase,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+import type { WorkspaceEntry } from "../../workspace/useWorkspaceEntries";
+import { useWorkspaceReadRefs } from "../useWorkspaceReadRefs";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function gitEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: "ws-1",
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+function localEntry(): WorkspaceEntry {
+  return {
+    id: "ws-local",
+    name: "dev/project",
+    type: "local",
+    localPath: "/Users/dev/project",
+  };
+}
+
+function execWithWriteBacks(
+  id: string,
+  writeBacks: ReadonlyArray<{
+    entryName: string;
+    commitSha: string;
+    phase?: WorkspaceWriteBackPhase;
+  }>,
+): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id });
+  exec.status = create(AgentExecutionStatusSchema);
+  exec.status.workspaceWriteBacks = writeBacks.map((wb) =>
+    create(WorkspaceWriteBackSchema, {
+      workspaceEntryName: wb.entryName,
+      commitSha: wb.commitSha,
+      phase: wb.phase ?? WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_PUSHED,
+    }),
+  );
+  return exec;
+}
+
+// ---------------------------------------------------------------------------
+// useWorkspaceReadRefs
+// ---------------------------------------------------------------------------
+
+describe("useWorkspaceReadRefs", () => {
+  it("returns the same entries reference when there are no write-backs", () => {
+    const entries = [gitEntry()];
+    const { result } = renderHook(() => useWorkspaceReadRefs([], entries));
+    expect(result.current).toBe(entries);
+  });
+
+  it("decorates a single git entry from a write-back with a matching name", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-1" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-1");
+  });
+
+  it("applies an empty-name write-back to the lone git entry (single-entry convention)", () => {
+    // Single-entry sessions provision with entryName "" — the runner's
+    // WriteBackCoordinator writes back under that empty name.
+    const entries = [gitEntry()];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "", commitSha: "sha-solo" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-solo");
+  });
+
+  it("claims a lone mismatched name for a lone git entry, but never for multiple entries", () => {
+    const solo = renderHook(() =>
+      useWorkspaceReadRefs(
+        [execWithWriteBacks("e1", [{ entryName: "other-name", commitSha: "sha-x" }])],
+        [gitEntry()],
+      ),
+    );
+    expect(solo.result.current[0].readRef).toBe("sha-x");
+
+    // With two git entries an unmatched name is ambiguous — decorate nothing.
+    const multi = renderHook(() =>
+      useWorkspaceReadRefs(
+        [execWithWriteBacks("e1", [{ entryName: "other-name", commitSha: "sha-x" }])],
+        [
+          gitEntry({ id: "ws-1", name: "acme/api" }),
+          gitEntry({ id: "ws-2", name: "acme/web" }),
+        ],
+      ),
+    );
+    expect(multi.result.current[0].readRef).toBeUndefined();
+    expect(multi.result.current[1].readRef).toBeUndefined();
+  });
+
+  it("the latest non-empty SHA wins across executions in order", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-old" }]),
+      execWithWriteBacks("e2", [{ entryName: "acme/api", commitSha: "sha-new" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-new");
+  });
+
+  it("a FAILED write-back with no SHA never regresses an earlier successful ref", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-good" }]),
+      execWithWriteBacks("e2", [
+        {
+          entryName: "acme/api",
+          commitSha: "",
+          phase: WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_FAILED,
+        },
+      ]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-good");
+  });
+
+  it("returns entries unchanged when only FAILED no-SHA write-backs exist", () => {
+    const entries = [gitEntry()];
+    const executions = [
+      execWithWriteBacks("e1", [
+        {
+          entryName: "",
+          commitSha: "",
+          phase: WorkspaceWriteBackPhase.WORKSPACE_WRITE_BACK_FAILED,
+        },
+      ]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current).toBe(entries);
+  });
+
+  it("matches strictly by name in multi-entry sessions", () => {
+    const entries = [
+      gitEntry({ id: "ws-1", name: "frontend" }),
+      gitEntry({ id: "ws-2", name: "backend" }),
+    ];
+    const executions = [
+      execWithWriteBacks("e1", [
+        { entryName: "frontend", commitSha: "sha-fe" },
+        { entryName: "backend", commitSha: "sha-be" },
+      ]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBe("sha-fe");
+    expect(result.current[1].readRef).toBe("sha-be");
+  });
+
+  it("never decorates local entries", () => {
+    const entries = [localEntry()];
+    const executions = [
+      execWithWriteBacks("e1", [{ entryName: "", commitSha: "sha-1" }]),
+    ];
+
+    const { result } = renderHook(() =>
+      useWorkspaceReadRefs(executions, entries),
+    );
+
+    expect(result.current[0].readRef).toBeUndefined();
+    expect(result.current).toBe(entries);
+  });
+
+  it("returns a stable array across streaming frames that change no SHA (DD-010)", () => {
+    const entries = [gitEntry({ name: "acme/api" })];
+    const { result, rerender } = renderHook(
+      (props: { executions: readonly AgentExecution[] }) =>
+        useWorkspaceReadRefs(props.executions, entries),
+      {
+        initialProps: {
+          executions: [
+            execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-1" }]),
+          ] as readonly AgentExecution[],
+        },
+      },
+    );
+
+    const first = result.current;
+    expect(first[0].readRef).toBe("sha-1");
+
+    // A new executions array (fresh identity, e.g. a streaming frame) with the
+    // same SHA must return the identical decorated array.
+    rerender({
+      executions: [
+        execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-1" }]),
+      ],
+    });
+    expect(result.current).toBe(first);
+
+    // Advancing the SHA produces a new decoration.
+    rerender({
+      executions: [
+        execWithWriteBacks("e1", [{ entryName: "acme/api", commitSha: "sha-2" }]),
+      ],
+    });
+    expect(result.current[0].readRef).toBe("sha-2");
+  });
+});

package/src/session/index.ts

@@ -45,6 +45,8 @@ export type {
   UseSessionWriteBacksReturn,
 } from "./useSessionWriteBacks.js";
 
+export { useWorkspaceReadRefs } from "./useWorkspaceReadRefs.js";
+
 export { useSessionFileChanges } from "./useSessionFileChanges.js";
 export type { UseSessionFileChangesReturn } from "./useSessionFileChanges.js";
 

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;
+}