@opengeni/react 0.45.0 → 0.48.0

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

@@ -5,7 +5,7 @@ import type {
   WorkspaceCaptureRepo,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import { type ClientOverride, useOpenGeni } from "../provider";
 
 export type UseSandboxGitOptions = ClientOverride & {
   /** Live event log (usually `useSessionEvents().events`) — drives auto-refresh
@@ -18,8 +18,14 @@ 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;
+  /** Pause live reads/invalidation while preserving the last rendered result. */
+  active?: 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;
@@ -29,10 +35,14 @@ export type UseSandboxGitOptions = ClientOverride & {
   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
@@ -175,6 +185,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 +194,15 @@ 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 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 = options.liveness === "warm" || options.liveness === "draining";
-  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${repoPathsKey}\u0000${workspaceWide}\u0000${staged}`;
+  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 +220,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 +231,69 @@ 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 client
+            .gitReadBatch(
+              workspaceId,
+              sessionId,
+              {
+                requests: repoPaths.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 },
+            )
+            .then((batch) =>
+              batch.results.map((item, index) => ({
+                root: repoPaths[index] ?? "",
+                status: item.status,
+                result: item.diff ?? {
+                  files: [],
+                  revision: item.status.revision,
+                },
+              })),
+            )
+        : 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 +308,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 +334,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 +372,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,6 +423,10 @@ export function useSandboxGit(
     if (currentCapture && (identityChanged || !isLive || sourceRef.current !== "live")) {
       seedFromCapture(currentCapture);
     }
+    if (!active) {
+      if (!active) setLoading(false);
+      return;
+    }
     if (isLive || !currentCapture) {
       void refresh();
     }
@@ -357,25 +435,54 @@ export function useSandboxGit(
       refreshAbortRef.current = null;
       refreshGenerationRef.current += 1;
     };
-  }, [enabled, isLive, captureRevision, identityKey, refresh, seedFromCapture]);
+  }, [enabled, active, isLive, 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 || !active || !events) {
+      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;
+        void refresh();
+      } else if (commandDelta && !commandRefreshTimerRef.current) {
+        commandRefreshTimerRef.current = setTimeout(() => {
+          commandRefreshTimerRef.current = null;
+          void refresh();
+        }, 1_000);
+      }
     }
-  }, [enabled, events, refresh]);
+  }, [enabled, active, events, refresh]);
+
+  useEffect(
+    () => () => {
+      if (commandRefreshTimerRef.current) clearTimeout(commandRefreshTimerRef.current);
+    },
+    [],
+  );
 
   const identityMatches = enabled && stateIdentity === identityKey;
   const visibleRepoRoots = identityMatches ? repoRoots : [];

package/src/hooks/use-session-capabilities.ts

@@ -7,6 +7,7 @@ import {
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+import { usePageLiveActivity } from "./internal";
 
 // "on-demand" is the boxless-benign resting state: the lease is cold and NOTHING
 // asked to warm a box (no viewer/consent action, no files-tab warm). Under lazy
@@ -157,6 +158,8 @@ export function useSessionCapabilities(
 ): UseSessionCapabilitiesResult {
   const { client, workspaceId } = useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const pageLive = usePageLiveActivity();
+  const lifecycleEnabled = enabled && pageLive;
   const attachDesktop = options.attachDesktop ?? false;
   const attachTerminal = options.attachTerminal ?? false;
   const attachFiles = options.attachFiles ?? false;
@@ -201,21 +204,21 @@ export function useSessionCapabilities(
       epochRef.current = 0;
       viewerIdRef.current = null;
     }
-    if (!enabled || !sessionId) {
+    if (!lifecycleEnabled || !sessionId) {
       setState("idle");
       setCapabilities(null);
       return;
     }
     let cancelled = false;
     let pollTimer: ReturnType<typeof setTimeout> | null = null;
-    let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+    let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
     let localViewerId: string | null = null;
     const requestAbort = new AbortController();
     const startedAt = Date.now();
 
     const clearTimers = () => {
       if (pollTimer !== null) clearTimeout(pollTimer);
-      if (heartbeatTimer !== null) clearInterval(heartbeatTimer);
+      if (heartbeatTimer !== null) clearTimeout(heartbeatTimer);
       pollTimer = null;
       heartbeatTimer = null;
     };
@@ -231,27 +234,35 @@ export function useSessionCapabilities(
       if (!localViewerId || heartbeatTimer !== null) return;
       const intervalMs =
         caps.viewerHeartbeatIntervalMs > 0 ? caps.viewerHeartbeatIntervalMs : 30_000;
-      heartbeatTimer = setInterval(() => {
+      const schedule = () => {
         if (cancelled || !localViewerId) return;
-        void client
-          .heartbeatViewer(workspaceId, sessionId, localViewerId, { leaseEpoch: epochRef.current })
-          .then((res) => {
-            // alive:false ⇒ the holder was reaped or the epoch moved under us;
-            // re-negotiate to re-acquire against the new owner.
-            if (!res.alive && !cancelled) {
-              renegotiate();
-            }
-          })
-          .catch((cause) => {
-            if (cancelled) return;
-            if (
-              cause instanceof OpenGeniApiError &&
-              (cause.status === 409 || cause.status === 410)
-            ) {
-              renegotiate();
-            }
-          });
-      }, intervalMs);
+        heartbeatTimer = setTimeout(() => {
+          heartbeatTimer = null;
+          if (cancelled || !localViewerId) return;
+          void client
+            .heartbeatViewer(workspaceId, sessionId, localViewerId, {
+              leaseEpoch: epochRef.current,
+            })
+            .then((res) => {
+              // alive:false ⇒ the holder was reaped or the epoch moved under us;
+              // re-negotiate to re-acquire against the new owner.
+              if (!res.alive && !cancelled) {
+                renegotiate();
+              }
+            })
+            .catch((cause) => {
+              if (cancelled) return;
+              if (
+                cause instanceof OpenGeniApiError &&
+                (cause.status === 409 || cause.status === 410)
+              ) {
+                renegotiate();
+              }
+            })
+            .finally(schedule);
+        }, intervalMs);
+      };
+      schedule();
     };
 
     const pollUntilWarm = () => {
@@ -455,7 +466,7 @@ export function useSessionCapabilities(
     client,
     workspaceId,
     sessionId,
-    enabled,
+    lifecycleEnabled,
     attachDesktop,
     attachTerminal,
     attachFiles,

package/src/hooks/use-session-events.ts

@@ -4,6 +4,7 @@ import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../sessi
 import { buildTimeline, groupTimeline, sessionStatusFromEvents } from "../timeline/projection";
 import type { TimelineItem } from "../timeline/types";
 import type { EmbeddedSessionClientLike } from "../client";
+import { usePageLiveActivity } from "./internal";
 
 export type SessionEventsConnectionState = StreamConnectionState | "idle" | "ended" | "error";
 
@@ -135,6 +136,8 @@ export function useSessionEvents(
 ): UseSessionEventsResult {
   const { client, workspaceId, reconcileSession } = useEmbeddedSession(options);
   const enabled = options.enabled ?? true;
+  const pageLive = usePageLiveActivity();
+  const streamEnabled = enabled && pageLive;
   const after = options.after ?? 0;
   const replay = options.replay ?? "windowed";
   const fullReplay = replay === "full" || after !== 0;
@@ -224,7 +227,7 @@ export function useSessionEvents(
       loadingOlderRef.current = false;
       setLoadingOlder(false);
     }
-    if (!sessionId || !enabled) {
+    if (!sessionId || !streamEnabled) {
       setConnectionState("idle");
       return;
     }
@@ -338,7 +341,18 @@ export function useSessionEvents(
         const stream = client.streamEvents(workspaceId, sessionId, {
           after: streamResumeSequenceRef.current,
           signal: controller.signal,
-          beforeLive: async () => await reconcileSession(sessionId),
+          onOpen: () => {
+            // Reconciliation repairs projections, but it must not block reading
+            // the already-open SSE body. Otherwise live events accumulate in the
+            // browser and appear as one delayed burst after every reconciler ends.
+            void Promise.resolve()
+              .then(() => reconcileSession(sessionId))
+              .catch((cause) => {
+                if (isCurrent()) {
+                  setError(cause instanceof Error ? cause : new Error(String(cause)));
+                }
+              });
+          },
           onStateChange: (state) => {
             if (isCurrent()) {
               setConnectionState(state);
@@ -399,7 +413,7 @@ export function useSessionEvents(
     workspaceId,
     sessionId,
     after,
-    enabled,
+    streamEnabled,
     fullReplay,
     streamKey,
     streamEpoch,
@@ -1175,7 +1189,7 @@ async function loadPreviousPage(
     compact: true,
     // Monitoring summaries omit correlation fields once a bounded durable
     // payload exceeds their preview threshold. The browser timeline needs the
-    // sanitized stored payload so persisted tool outputs still match their
+    // exact stored payload so persisted tool outputs still match their
     // calls and expose truthful truncation telemetry after a reload.
     payloadMode: "full",
   });

package/src/hooks/use-transcription.ts

@@ -214,7 +214,7 @@ export type UseTranscriptionOptions = {
   disabled?: boolean | undefined;
   createLocalSessionId?: (() => string) | undefined;
   lifecycleTimeouts?: Partial<TranscriptionLifecycleTimeouts> | undefined;
-  /** Receives bounded, redacted diagnostics; this detail is never rendered by the hook. */
+  /** Receives the exact diagnostic emitted by the transcription transport. */
   onDiagnostic?: ((diagnostic: TranscriptionDiagnostic) => void) | undefined;
 };
 
@@ -277,7 +277,7 @@ export function useTranscription({
     (diagnostic: unknown) => {
       if (!onDiagnostic) return;
       try {
-        onDiagnostic(sanitizeTranscriptionDiagnostic(diagnostic));
+        onDiagnostic(normalizeTranscriptionDiagnostic(diagnostic));
       } catch {
         // Observability must never break the local privacy or UI lifecycle.
       }
@@ -625,7 +625,7 @@ export function normalizeTranscriptionErrorCode(code: unknown): TranscriptionErr
   }
 }
 
-export function sanitizeTranscriptionDiagnostic(diagnostic: unknown): TranscriptionDiagnostic {
+export function normalizeTranscriptionDiagnostic(diagnostic: unknown): TranscriptionDiagnostic {
   const source = isRecord(diagnostic) ? diagnostic : {};
   const operation =
     source.operation === "start" ||
@@ -635,20 +635,10 @@ export function sanitizeTranscriptionDiagnostic(diagnostic: unknown): Transcript
       ? source.operation
       : "session";
   const rawDetail = typeof source.detail === "string" ? source.detail : "No diagnostic detail.";
-  const detail = rawDetail
-    .replace(/[\u0000-\u001f\u007f]+/gu, " ")
-    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/giu, "Bearer [REDACTED]")
-    .replace(/\bsk-[A-Za-z0-9_-]{4,}\b/gu, "[REDACTED]")
-    .replace(
-      /\b(api[-_ ]?key|authorization|access[-_ ]?token|refresh[-_ ]?token|token|secret)\b\s*[:=]\s*[^\s,;]+/giu,
-      "$1=[REDACTED]",
-    )
-    .trim()
-    .slice(0, 512);
   return {
     operation,
     code: normalizeTranscriptionErrorCode(source.code),
-    detail: detail || "No diagnostic detail.",
+    detail: rawDetail,
   };
 }
 

package/src/hooks/use-turn-queue.ts

@@ -12,6 +12,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
 import {
   useDebouncedCallback,
+  usePageLiveActivity,
   useSessionEventTrigger,
   type SessionEventFeedOptions,
 } from "./internal";
@@ -91,6 +92,7 @@ export function useTurnQueue(
     useEmbeddedSession(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
+  const pageLive = usePageLiveActivity();
   const [snapshot, setSnapshot] = useState<SessionQueueSnapshot | null>(null);
   const [stateTargetKey, setStateTargetKey] = useState(targetKey);
   const [loading, setLoading] = useState(enabled);
@@ -174,24 +176,34 @@ export function useTurnQueue(
   );
 
   useEffect(() => {
-    if (!enabled) {
+    if (!enabled || !pageLive) {
       setLoading(false);
       return;
     }
     setLoading(true);
-    void load();
     const pollIntervalMs = options.pollIntervalMs;
     if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
+      void load();
       return () => {
         readGeneration.current += 1;
       };
     }
-    const timer = setInterval(() => void load(), pollIntervalMs);
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const schedule = () => {
+      if (cancelled) return;
+      timer = setTimeout(() => {
+        timer = null;
+        void load().finally(schedule);
+      }, pollIntervalMs);
+    };
+    void load().finally(schedule);
     return () => {
-      clearInterval(timer);
+      cancelled = true;
+      if (timer !== null) clearTimeout(timer);
       readGeneration.current += 1;
     };
-  }, [load, enabled, options.pollIntervalMs]);
+  }, [load, enabled, pageLive, options.pollIntervalMs]);
 
   useEffect(() => {
     if (enabled && workspaceControlEvent) void load();