@opengeni/react 0.46.1 → 0.52.1

package/src/hooks/use-sandbox-git.ts

@@ -1,11 +1,13 @@
 import type {
   GitFileDiff,
+  SessionCapabilities,
   SessionEvent,
   WorkspaceCaptureManifest,
   WorkspaceCaptureRepo,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import { type ClientOverride, useOpenGeni } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 export type UseSandboxGitOptions = ClientOverride & {
   /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
@@ -18,21 +20,32 @@ export type UseSandboxGitOptions = ClientOverride & {
   repoPaths?: readonly string[] | undefined;
   /** Diff the staged index vs HEAD (`--cached`) instead of the working tree. */
   staged?: boolean | undefined;
+  /** Review scope. `branch` compares the current branch with the remote default
+   *  branch, `working` shows uncommitted edits, and `staged` shows the index.
+   *  `staged` above remains as a compatibility alias. */
+  comparison?: SandboxGitComparison | undefined;
   /** Hold off the initial fetch. Default true. */
   enabled?: boolean | undefined;
-  /** Lease liveness ("warm" | "draining" | "cold"). When NOT warm, the diff is
-   *  served from the capture (cold/offline) instead of a live `gitDiff` RPC. */
-  liveness?: string | undefined;
+  /** Pause live reads/invalidation while preserving the last rendered result. */
+  active?: boolean | undefined;
+  /** Lease liveness. `null` means capability negotiation is still pending and
+   *  blocks live I/O. When not warm, the diff is served from the capture instead
+   *  of a live `gitDiff` RPC. Omission preserves legacy direct-hook behavior. */
+  liveness?: SessionCapabilities["liveness"] | null | undefined;
   /** The latest turn-end capture (from `useWorkspaceCapture`). Seeds the diff
    *  immediately; a warm box reconciles live and leaves this durable review
    *  surface in place if the live request is temporarily unavailable. */
   capture?: WorkspaceCaptureManifest | null | undefined;
 };
 
+export type SandboxGitComparison = "branch" | "working" | "staged";
+
 /** A Git diff qualified into workspace scope. `repoRoot` is present for the
  *  workspace-wide path and lets review UI group real repositories without
  *  guessing from the first path segment. */
-export type SandboxGitFileDiff = GitFileDiff & { repoRoot?: string | undefined };
+export type SandboxGitFileDiff = GitFileDiff & {
+  repoRoot?: string | undefined;
+};
 
 export type UseSandboxGitResult = {
   /** Working-tree (or staged) diff vs HEAD — the structured hunks the Pierre
@@ -83,6 +96,11 @@ function uniqueRoots(roots: readonly string[]): string[] {
   return [...new Set(roots.map(normalizeRoot))].sort((a, b) => a.localeCompare(b));
 }
 
+// GitReadBatchRequest is contract-bounded to 32 items. Keep workspace-wide
+// reads bounded without changing the wire limit; sequential chunks preserve
+// deterministic root/result mapping and cap Channel-A lease concurrency at one.
+const GIT_READ_BATCH_REQUEST_LIMIT = 32;
+
 /** Find the capture repo matching `repoPath` (default workspace root). */
 function repoForPath(
   manifest: WorkspaceCaptureManifest,
@@ -175,6 +193,7 @@ export function useSandboxGit(
 ): UseSandboxGitResult {
   const { client, workspaceId } = useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const active = options.active ?? true;
   const repoPath = options.repoPath ?? "";
   const workspaceWide = options.repoPaths !== undefined;
   // Serialize the caller's array so inline values do not retrigger effects. An
@@ -183,10 +202,21 @@ export function useSandboxGit(
     options.repoPaths && options.repoPaths.length > 0 ? options.repoPaths : [repoPath],
   ).join("\u0000");
   const repoPaths = useMemo(() => repoPathsKey.split("\u0000"), [repoPathsKey]);
-  const staged = options.staged ?? false;
-  const capture = options.capture ?? null;
-  const isLive = options.liveness === "warm" || options.liveness === "draining";
-  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${repoPathsKey}\u0000${workspaceWide}\u0000${staged}`;
+  const comparison: SandboxGitComparison =
+    options.comparison ?? (options.staged ? "staged" : "working");
+  const hasAdvertisedRepoPaths = (options.repoPaths?.length ?? 0) > 0;
+  // New captures retain both working-tree and branch comparisons. Staged state
+  // remains live-only; legacy captures simply lack branchDiff and fall back via
+  // the workspace controller without inventing an empty branch comparison.
+  const capture = comparison === "staged" ? null : (options.capture ?? null);
+  const isLive = sandboxAcceptsLiveIo(options.liveness);
+  // `liveness` is optional for compatibility with direct hook consumers. Explicit
+  // `null` (negotiating) and lifecycle values require authoritative warm.
+  const acceptsEventReads = options.liveness === undefined || isLive;
+  const acceptsEventReadsRef = useRef(acceptsEventReads);
+  acceptsEventReadsRef.current = acceptsEventReads;
+  const hasLiveIoFence = options.liveness !== undefined;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${repoPathsKey}\u0000${workspaceWide}\u0000${comparison}`;
 
   const [diff, setDiff] = useState<SandboxGitFileDiff[]>([]);
   const [branch, setBranch] = useState<string | null>(null);
@@ -204,6 +234,7 @@ export function useSandboxGit(
   const refreshGenerationRef = useRef(0);
   const refreshAbortRef = useRef<AbortController | null>(null);
   const lastChangeRef = useRef(0);
+  const commandRefreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const refresh = useCallback(async () => {
     if (!sessionId) return;
@@ -214,17 +245,88 @@ export function useSandboxGit(
     setLoading(true);
     setError(null);
     try {
-      const statuses = await Promise.all(
-        repoPaths.map(async (root) => ({
-          root,
-          status: await client.gitStatus(
-            workspaceId,
-            sessionId,
-            { path: root },
-            { signal: refreshAbort.signal },
-          ),
-        })),
-      );
+      const diffRequest = (root: string) =>
+        client.gitDiff(
+          workspaceId,
+          sessionId,
+          {
+            path: root,
+            ...(comparison === "branch"
+              ? { fromRef: "origin/HEAD", includeUntracked: true }
+              : comparison === "working"
+                ? { fromRef: "HEAD", includeUntracked: true }
+                : { staged: true, includeUntracked: false }),
+          },
+          { signal: refreshAbort.signal },
+        );
+
+      // Capability-advertised roots are known repositories. Fetch status metadata
+      // and diff hunks together: both are independent Channel-A reads and each can
+      // take several seconds on a remote sandbox. The legacy root probe remains
+      // serial so a non-repository workspace never receives a failing git diff.
+      const prefetched = hasAdvertisedRepoPaths
+        ? await (async () => {
+            const prefetchedRepos: Array<{
+              root: string;
+              status: Awaited<ReturnType<typeof client.gitStatus>>;
+              result: Awaited<ReturnType<typeof client.gitDiff>>;
+            }> = [];
+            for (
+              let offset = 0;
+              offset < repoPaths.length;
+              offset += GIT_READ_BATCH_REQUEST_LIMIT
+            ) {
+              const roots = repoPaths.slice(offset, offset + GIT_READ_BATCH_REQUEST_LIMIT);
+              const batch = await client.gitReadBatch(
+                workspaceId,
+                sessionId,
+                {
+                  requests: roots.map((root) => ({
+                    status: { path: root },
+                    diff: {
+                      path: root,
+                      ...(comparison === "branch"
+                        ? { fromRef: "origin/HEAD", includeUntracked: true }
+                        : comparison === "working"
+                          ? { fromRef: "HEAD", includeUntracked: true }
+                          : { staged: true, includeUntracked: false }),
+                    },
+                  })),
+                },
+                { signal: refreshAbort.signal },
+              );
+              if (batch.results.length !== roots.length) {
+                throw new Error(
+                  `Workspace Git batch returned ${batch.results.length} results for ${roots.length} repositories.`,
+                );
+              }
+              batch.results.forEach((item, index) => {
+                prefetchedRepos.push({
+                  root: roots[index]!,
+                  status: item.status,
+                  result: item.diff ?? {
+                    files: [],
+                    revision: item.status.revision,
+                  },
+                });
+              });
+            }
+            return prefetchedRepos;
+          })()
+        : null;
+      const statuses =
+        prefetched ??
+        (await Promise.all(
+          repoPaths.map(async (root) => ({
+            root,
+            status: await client.gitStatus(
+              workspaceId,
+              sessionId,
+              { path: root },
+              { signal: refreshAbort.signal },
+            ),
+          })),
+        ));
       if (refreshGenerationRef.current !== generation) return;
       const repositories = statuses.filter(({ status }) => status.isRepo);
       const roots = repositories.map(({ root }) => root);
@@ -239,19 +341,11 @@ export function useSandboxGit(
         setSource("live");
         return;
       }
+      const prefetchedByRoot = new Map(prefetched?.map(({ root, result }) => [root, result]));
       const results = await Promise.all(
         repositories.map(async ({ root }) => ({
           root,
-          result: await client.gitDiff(
-            workspaceId,
-            sessionId,
-            {
-              path: root,
-              staged,
-              includeUntracked: !staged,
-            },
-            { signal: refreshAbort.signal },
-          ),
+          result: prefetchedByRoot.get(root) ?? (await diffRequest(root)),
         })),
       );
       if (refreshGenerationRef.current !== generation) return;
@@ -273,15 +367,25 @@ export function useSandboxGit(
       if (refreshGenerationRef.current === generation) setLoading(false);
       if (refreshAbortRef.current === refreshAbort) refreshAbortRef.current = null;
     }
-  }, [client, workspaceId, sessionId, repoPaths, staged, workspaceWide]);
+  }, [
+    client,
+    workspaceId,
+    sessionId,
+    repoPaths,
+    hasAdvertisedRepoPaths,
+    workspaceWide,
+    comparison,
+  ]);
 
-  // Serve the diff from a capture (the cold/offline source). `staged` has no
-  // meaning here: the capture records the combined turn-end change surface vs HEAD.
+  // Serve the requested review scope from a capture when that scope exists.
   const seedFromCapture = useCallback(
     (manifest: WorkspaceCaptureManifest) => {
       const repositories = workspaceWide
         ? manifest.repos
         : ([repoForPath(manifest, repoPath)].filter(Boolean) as WorkspaceCaptureRepo[]);
+      if (comparison === "branch" && repositories.some((repo) => repo.branchDiff === undefined)) {
+        return;
+      }
       if (repositories.length === 0) {
         setIsRepo(false);
         setBranch(null);
@@ -301,16 +405,19 @@ export function useSandboxGit(
       setDiff((prev) =>
         mergeDiffs(
           prev,
-          repositories.flatMap((repo) =>
-            workspaceWide ? repo.diff.map((file) => qualifyDiff(repo.root, file)) : repo.diff,
-          ),
+          repositories.flatMap((repo) => {
+            const capturedDiff = comparison === "branch" ? (repo.branchDiff ?? []) : repo.diff;
+            return workspaceWide
+              ? capturedDiff.map((file) => qualifyDiff(repo.root, file))
+              : capturedDiff;
+          }),
         ),
       );
       sourceRef.current = "capture";
       setSource("capture");
       setError(null);
     },
-    [repoPath, workspaceWide],
+    [comparison, repoPath, workspaceWide],
   );
 
   // Source selection on mount / liveness / capture-revision change. Key on the
@@ -349,7 +456,11 @@ export function useSandboxGit(
     if (currentCapture && (identityChanged || !isLive || sourceRef.current !== "live")) {
       seedFromCapture(currentCapture);
     }
-    if (isLive || !currentCapture) {
+    if (!active) {
+      if (!active) setLoading(false);
+      return;
+    }
+    if (isLive || (!hasLiveIoFence && !currentCapture)) {
       void refresh();
     }
     return () => {
@@ -357,25 +468,76 @@ export function useSandboxGit(
       refreshAbortRef.current = null;
       refreshGenerationRef.current += 1;
     };
-  }, [enabled, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
+  }, [
+    enabled,
+    active,
+    isLive,
+    hasLiveIoFence,
+    captureRevision,
+    identityKey,
+    refresh,
+    seedFromCapture,
+  ]);
 
-  // git.changed → re-fetch the LIVE diff. A git.changed only originates from a
-  // live box, so this both keeps warm sessions fresh and folds a cold box that
-  // just came up (unchanged from the pre-capture behavior).
+  // git.changed → re-fetch the LIVE diff. Agent tool completion is also an
+  // invalidation point because shell/apply-patch writes can bypass Channel-A and
+  // therefore emit no git.changed event. This is event-driven, never polling.
   const events = options.events;
   useEffect(() => {
-    if (!enabled || !events) return;
+    if (!enabled || !events) {
+      if (commandRefreshTimerRef.current) {
+        clearTimeout(commandRefreshTimerRef.current);
+        commandRefreshTimerRef.current = null;
+      }
+      return;
+    }
+    // Historical events describe the capture we already loaded. Inactive tabs
+    // and holderless draining/cold leases advance the cursor without issuing
+    // provider I/O; becoming warm performs one authoritative reconcile above.
+    if (!active || !acceptsEventReads) {
+      for (const event of events) {
+        if (event.sequence > lastChangeRef.current) lastChangeRef.current = event.sequence;
+      }
+      if (commandRefreshTimerRef.current) {
+        clearTimeout(commandRefreshTimerRef.current);
+        commandRefreshTimerRef.current = null;
+      }
+      return;
+    }
     let latest = lastChangeRef.current;
+    let immediate = false;
+    let commandDelta = false;
     for (const event of events) {
-      if (event.type === "git.changed" && event.sequence > latest) {
+      if (event.sequence <= latest) continue;
+      if (event.type === "git.changed" || event.type === "agent.toolCall.output") {
+        latest = event.sequence;
+        immediate = true;
+      } else if (event.type === "sandbox.command.output.delta") {
         latest = event.sequence;
+        commandDelta = true;
       }
     }
     if (latest > lastChangeRef.current) {
       lastChangeRef.current = latest;
-      void refresh();
+      if (immediate) {
+        if (commandRefreshTimerRef.current) clearTimeout(commandRefreshTimerRef.current);
+        commandRefreshTimerRef.current = null;
+        if (acceptsEventReadsRef.current) void refresh();
+      } else if (commandDelta && !commandRefreshTimerRef.current) {
+        commandRefreshTimerRef.current = setTimeout(() => {
+          commandRefreshTimerRef.current = null;
+          if (acceptsEventReadsRef.current) void refresh();
+        }, 1_000);
+      }
     }
-  }, [enabled, events, refresh]);
+  }, [enabled, active, acceptsEventReads, events, refresh]);
+
+  useEffect(
+    () => () => {
+      if (commandRefreshTimerRef.current) clearTimeout(commandRefreshTimerRef.current);
+    },
+    [],
+  );
 
   const identityMatches = enabled && stateIdentity === identityKey;
   const visibleRepoRoots = identityMatches ? repoRoots : [];

package/src/hooks/use-sandbox-terminal.ts

@@ -7,6 +7,7 @@ import type {
 import { OpenGeniApiError } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 export type TerminalChunk = {
   /** Stable key (the source event id) so the xterm writer tracks a written-cursor. */
@@ -107,9 +108,9 @@ export function useSandboxTerminal(
   // projection is the single source of truth for what's written). The open is
   // gated on a WARM box: opening on a cold/warming lease races the box (the PTY
   // exec-session is created on a box that the next op may not resume), which is
-  // exactly the "session not found" terminal failure; we wait for warm/draining.
+  // exactly the "session not found" terminal failure; we wait for warm.
   const openInFlight = useRef(false);
-  const boxWarm = liveness === undefined || liveness === "warm" || liveness === "draining";
+  const boxWarm = liveness === undefined || sandboxAcceptsLiveIo(liveness);
   useEffect(() => {
     if (!interactive || !sessionId || ptyFilter || !boxWarm) {
       setOpenError(null);