@opengeni/react 0.48.0 → 0.52.1

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);

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

@@ -7,10 +7,13 @@ import {
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
+import { terminalCanAcquirePty } from "../lib/terminal-capability";
 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
+// "on-demand" is the boxless-benign resting state: the lease is not currently
+// holder-backed and NOTHING asked to warm a box (no viewer/consent action, no
+// files-tab warm). Under lazy
 // provisioning a chat-only turn never creates a box, so this is the correct calm
 // terminal state — NOT an error. It is distinct from "cold", which now means "a
 // warm-up is genuinely in flight" (a viewer attach was requested) and therefore
@@ -84,7 +87,8 @@ export type UseSessionCapabilitiesResult = {
   error: Error | null;
   /**
    * 409 from the desktop attach: the un-redacted (or shared) plane needs explicit
-   * acknowledgment before a viewer holder is granted. Drives the consent prompt.
+   * acknowledgment before a viewer holder is granted. The workbench uses this
+   * to complete acknowledgment automatically while Desktop is opening.
    */
   acknowledgmentRequired: "unredacted" | "shared" | null;
   /** 429 from the desktop attach: the per-session viewer cap is reached. */
@@ -112,24 +116,10 @@ function desktopAttachable(cell: SessionCapabilities["DesktopStream"]): boolean
 
 /**
  * Whether warming the box for the interactive terminal (pty-ws) is worth it.
- * The Terminal cell is ALWAYS feasible when the backend advertises a transport at
- * all (`sse-events` on a cold box, `pty-ws` once warm) — only a genuinely
- * terminal-less backend reports transport:null with a hard reason. The attach is
- * what flips `sse-events` → `pty-ws` by warming the box and minting the ttyd
- * tunnel URL, so we attach whenever the terminal is not hard-unavailable.
+ * A real-PTY descriptor is attachable when already routed as `pty-ws`, or while
+ * transiently cold. A firehose-only backend and policy/OS/backend degradation
+ * cannot become interactive, so attaching there would only waste a holder.
  */
-function terminalAttachable(cell: SessionCapabilities["Terminal"]): boolean {
-  if (cell.transport === null) {
-    // No terminal at all unless the only blocker is a transient cold state.
-    return (
-      cell.reason === "lease_cold" || cell.reason === "not_provisioned" || cell.reason === null
-    );
-  }
-  // Already pty-ws (warm) is fine to (re)attach; sse-events is the cold state the
-  // attach upgrades. Either way it's attachable.
-  return true;
-}
-
 /** Read `stream.url.rotated` payloads off the live event log, newest last. */
 function rotationsFrom(events: SessionEvent[]): StreamUrlRotatedPayload[] {
   const out: StreamUrlRotatedPayload[] = [];
@@ -149,8 +139,8 @@ function rotationsFrom(events: SessionEvent[]): StreamUrlRotatedPayload[] {
  *
  * Degradation is a value, never a crash: an unsupported surface comes back
  * `available:false`/`transport:null` + a `reason`; the components render the
- * reason-aware empty state. 409 (consent) and 429 (viewer cap) are surfaced as
- * typed signals, not thrown.
+ * reason-aware empty state. 409 (acknowledgment) and 429 (viewer cap) are
+ * surfaced as typed signals, not thrown.
  */
 export function useSessionCapabilities(
   sessionId: string | null | undefined,
@@ -207,8 +197,15 @@ export function useSessionCapabilities(
     if (!lifecycleEnabled || !sessionId) {
       setState("idle");
       setCapabilities(null);
+      viewerIdRef.current = null;
+      setViewerId(null);
       return;
     }
+    // The preceding effect cleanup released any old holder before this fresh
+    // lifecycle starts. Never project that stale id while re-negotiating or if
+    // the replacement grant degrades.
+    viewerIdRef.current = null;
+    setViewerId(null);
     let cancelled = false;
     let pollTimer: ReturnType<typeof setTimeout> | null = null;
     let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
@@ -273,7 +270,7 @@ export function useSessionCapabilities(
           .then((caps) => {
             if (cancelled) return;
             settle(caps);
-            if (caps.liveness === "warm" || caps.liveness === "draining") {
+            if (sandboxAcceptsLiveIo(caps.liveness)) {
               setState("ready");
               return;
             }
@@ -308,8 +305,8 @@ export function useSessionCapabilities(
         // attach serves BOTH live planes — the desktop pixel stream AND the
         // interactive terminal (ttyd pty-ws) ride the same warm box and the same
         // holder; the response folds the minted address for each requested plane.
-        // The consent gate (409) and the viewer cap (429) surface as typed signals
-        // rather than throwing — the tabs degrade gracefully.
+        // The acknowledgment requirement (409) and viewer cap (429) surface as
+        // typed signals rather than throwing — the tabs degrade gracefully.
         //
         // KEY: the handshake (getStreamCapabilities) NEVER spins up a cold box, so
         // on a cold/warming lease the desktop cell comes back transport:null and
@@ -321,7 +318,7 @@ export function useSessionCapabilities(
         // already live OR cold-but-feasible — and let POST /viewers warm the box and
         // mint the URLs. Only a genuinely-unsupported reason suppresses the attach.
         const wantDesktopAttach = attachDesktop && desktopAttachable(caps.DesktopStream);
-        const wantTerminalAttach = attachTerminal && terminalAttachable(caps.Terminal);
+        const wantTerminalAttach = attachTerminal && terminalCanAcquirePty(caps.Terminal);
         // The Files attach warms the box for a file WRITE (wake-on-edit intent). It
         // folds no live URL (files are stateless HTTP) — the attach is purely a
         // liveness refcount. Unlike the previous "keep the box warm while the Files
@@ -339,6 +336,8 @@ export function useSessionCapabilities(
             // pty-ws terminal cell WITHOUT tripping the desktop consent 409.
             const holder = await client.attachViewer(workspaceId, sessionId, {
               desktop: wantDesktopAttach,
+              terminal: wantTerminalAttach,
+              files: wantFilesAttach,
             });
             if (cancelled) {
               // The attach crossed an identity/unmount boundary after the server
@@ -348,6 +347,18 @@ export function useSessionCapabilities(
               void client.detachViewer(workspaceId, sessionId, holder.viewerId).catch(() => {});
               return;
             }
+            if (
+              (wantDesktopAttach &&
+                (!holder.dataPlaneUrl || !holder.transport || !holder.client)) ||
+              (wantTerminalAttach && (!holder.terminalUrl || !holder.terminalTransport))
+            ) {
+              // Nullable plane cells are valid graceful-degradation values at
+              // the raw API boundary, but an explicit UI grant must not become
+              // a successful holder that waits forever. Release it and surface
+              // a retryable error instead of retaining stale credentials.
+              await client.detachViewer(workspaceId, sessionId, holder.viewerId).catch(() => {});
+              throw new Error("live plane unavailable");
+            }
             localViewerId = holder.viewerId;
             viewerIdRef.current = holder.viewerId;
             setViewerId(holder.viewerId);
@@ -367,24 +378,24 @@ export function useSessionCapabilities(
                           ...prev.DesktopStream,
                           transport: holder.transport ?? prev.DesktopStream.transport,
                           client: holder.client ?? prev.DesktopStream.client,
-                          url: holder.dataPlaneUrl ?? prev.DesktopStream.url,
-                          token: holder.streamToken ?? prev.DesktopStream.token,
-                          expiresAt: holder.streamExpiresAt ?? prev.DesktopStream.expiresAt,
+                          url: holder.dataPlaneUrl,
+                          token: holder.streamToken,
+                          expiresAt: holder.streamExpiresAt,
                           resolution: holder.resolution ?? prev.DesktopStream.resolution,
                         }
                       : prev.DesktopStream,
-                    Terminal:
-                      holder.terminalUrl && holder.terminalTransport
-                        ? {
-                            ...prev.Terminal,
-                            transport: holder.terminalTransport,
-                            url: holder.terminalUrl,
-                            token: holder.terminalToken ?? prev.Terminal.token,
-                            // A live pty-ws means the box is pty-capable for real.
-                            ptyCapable: true,
-                            reason: null,
-                          }
-                        : prev.Terminal,
+                    Terminal: wantTerminalAttach
+                      ? {
+                          ...prev.Terminal,
+                          transport: holder.terminalTransport ?? prev.Terminal.transport,
+                          url: holder.terminalUrl,
+                          token: holder.terminalToken,
+                          expiresAt: holder.terminalExpiresAt,
+                          // A live pty-ws means the box is pty-capable for real.
+                          ptyCapable: holder.terminalTransport ? true : prev.Terminal.ptyCapable,
+                          reason: holder.terminalTransport ? null : prev.Terminal.reason,
+                        }
+                      : prev.Terminal,
                   }
                 : prev,
             );
@@ -393,8 +404,8 @@ export function useSessionCapabilities(
             if (cause instanceof OpenGeniApiError) {
               if (cause.status === 409) {
                 // The un-redacted/shared consent gate is a DESKTOP requirement. A
-                // terminal-only warm attach needs no consent, so a 409 there is not
-                // a consent prompt — the terminal just stays on the read-only
+                // terminal-only warm attach needs no acknowledgment, so a 409 there
+                // is not a desktop-open signal — the terminal stays on the read-only
                 // firehose. Only raise the consent requirement when the desktop was
                 // the (or a) reason we attached.
                 if (wantDesktopAttach) {
@@ -408,6 +419,8 @@ export function useSessionCapabilities(
                 setState("error");
                 setError(cause);
                 return;
+              } else {
+                throw cause;
               }
               // 409/429 are recoverable: structured surfaces still negotiated;
               // keep going to set ready/cold below.
@@ -418,16 +431,16 @@ export function useSessionCapabilities(
         }
 
         // Whether ANYTHING asked to warm a box this negotiation. Only then is a
-        // cold lease "warming in flight" — worth polling, and worth surfacing a
+        // non-warm lease "warming in flight" — worth polling, and worth surfacing a
         // stall as an error. With no warm-up requested a cold lease is the benign
         // boxless resting state (below), never an error.
         const warmUpRequested = wantDesktopAttach || wantTerminalAttach || wantFilesAttach;
-        if (caps.liveness === "warm" || caps.liveness === "draining" || localViewerId) {
+        if (sandboxAcceptsLiveIo(caps.liveness) || localViewerId) {
           setState("ready");
           startHeartbeat(caps);
         } else if (warmUpRequested) {
           // A warm-up is genuinely in flight (a viewer attach was requested) but the
-          // box isn't warm yet — poll until it warms, with the patience deadline so a
+          // box isn't holder-confirmed warm yet — poll until it is, with the deadline so a
           // real stall surfaces as an error.
           setState("cold");
           pollUntilWarm();

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

@@ -17,7 +17,7 @@ export type UseTerminalStreamOptions = {
    *  The stream connects ONLY when `transport === "pty-ws"` and `url` is set; on a
    *  cold box (`transport === "sse-events"` / no url) it stays idle and the caller
    *  falls back to the Channel-A read-only firehose. */
-  capability: Pick<TerminalCapability, "transport" | "url" | "token"> | null;
+  capability: Pick<TerminalCapability, "transport" | "url" | "token" | "expiresAt"> | null;
   /** Called for each OUTPUT payload from ttyd (write verbatim into xterm). */
   onOutput?: ((data: string) => void) | undefined;
   /** Called when ttyd sends a SET_WINDOW_TITLE frame. */
@@ -31,7 +31,8 @@ export type UseTerminalStreamResult = {
   /** True once the ttyd socket is open (and the auth frame has been sent). */
   connected: boolean;
   status: TerminalStreamStatus;
-  /** Pipe a keystroke/paste to the PTY stdin. No-op until the socket is open. */
+  /** Pipe a keystroke/paste to PTY stdin. Input during CONNECTING is bounded and
+   *  replayed only after ttyd authentication succeeds. */
   write: (data: string) => void;
   /** Tell ttyd the PTY window changed size (on xterm fit/resize). */
   resize: (cols: number, rows: number) => void;
@@ -39,6 +40,27 @@ export type UseTerminalStreamResult = {
   disconnect: () => void;
 };
 
+// Keystrokes entered during the websocket handshake are held until ttyd has
+// accepted its auth/resize frames. Bound the queue by UTF-16 code units (a hard
+// <=128 KiB string payload in current JS engines) so a paste cannot turn a slow
+// handshake into unbounded renderer memory. Overflow rejects the whole pending
+// input rather than ever executing a truncated shell command.
+export const MAX_PENDING_TERMINAL_INPUT_CODE_UNITS = 64 * 1024;
+const TERMINAL_CONNECT_EXPIRY_SKEW_MS = 5_000;
+
+/** A bearer must remain valid long enough to finish a new websocket handshake.
+ * Existing open sockets are unaffected: this is evaluated only when the
+ * credential identity changes and the connection effect attempts a new socket. */
+export function terminalStreamCredentialUsable(
+  capability: Pick<TerminalCapability, "transport" | "url" | "expiresAt"> | null | undefined,
+  nowMs = Date.now(),
+): boolean {
+  if (capability?.transport !== "pty-ws" || !capability.url) return false;
+  if (!capability.expiresAt) return true;
+  const expiresAt = Date.parse(capability.expiresAt);
+  return Number.isFinite(expiresAt) && expiresAt > nowMs + TERMINAL_CONNECT_EXPIRY_SKEW_MS;
+}
+
 /** Decode an inbound ttyd frame's payload (everything after the 1-char command).
  *  ttyd may send either a text frame (string) or a binary frame (ArrayBuffer);
  *  for binary we slice off the first byte (the command) and utf-8 decode the rest. */
@@ -52,6 +74,14 @@ function decodeFrame(data: string | ArrayBuffer): { command: string; payload: st
   return { command, payload };
 }
 
+function closeSocket(socket: WebSocket | null): void {
+  try {
+    socket?.close();
+  } catch {
+    // Already closed or rejected by the host WebSocket implementation.
+  }
+}
+
 /**
  * Drive a ttyd PTY-over-websocket connection from a `pty-ws` Terminal capability,
  * symmetric with `use-desktop-stream` (the noVNC-over-tunnel hook). The scoped
@@ -73,6 +103,9 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
   const { capability, onOutput, onTitle, initialCols, initialRows } = options;
   const [status, setStatus] = useState<TerminalStreamStatus>("closed");
   const wsRef = useRef<WebSocket | null>(null);
+  const pendingInputRef = useRef("");
+  const socketFailedRef = useRef(false);
+  const socketAuthenticatedRef = useRef(false);
   // Latest size, so a resize() before the socket opens is replayed on open, and a
   // reconnect seeds the right geometry.
   const sizeRef = useRef<{ cols: number; rows: number }>({
@@ -89,12 +122,35 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
   const transport = capability?.transport ?? null;
   const url = capability?.url ?? null;
   const token = capability?.token ?? null;
+  const expiresAt = capability?.expiresAt ?? null;
 
   useEffect(() => {
     // SSR / no WebSocket / not a live pty-ws cell: stay closed; the caller falls
     // back to the Channel-A read-only firehose.
     if (typeof window === "undefined" || typeof WebSocket === "undefined") return;
-    if (transport !== "pty-ws" || !url) {
+    if (transport !== "pty-ws") {
+      // A transport downgrade is a real semantic boundary. Do not replay input
+      // captured for a PTY if this surface later changes back from firehose mode.
+      pendingInputRef.current = "";
+      socketAuthenticatedRef.current = false;
+      setStatus("closed");
+      return;
+    }
+    // A changed/cleared credential is a new connection attempt boundary. It may
+    // receive input while its exact grant is pending even if the prior socket
+    // failed; the unchanged failed identity remains fenced because this effect
+    // does not re-run for a status-only render.
+    socketFailedRef.current = false;
+    socketAuthenticatedRef.current = false;
+    if (!url) {
+      // Exact grants arrive asynchronously. Preserve the bounded first input
+      // while the descriptor remains pty-ws, but never open without a credential.
+      setStatus("closed");
+      return;
+    }
+    if (!terminalStreamCredentialUsable({ transport, url, expiresAt })) {
+      // A descriptor from an older rolling server may still carry a bearer that
+      // aged out before this surface mounted. Wait for the exact fresh grant.
       setStatus("closed");
       return;
     }
@@ -107,6 +163,7 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
       // it. The scoped token is already in the tunnel `url`.
       socket = new WebSocket(terminalSocketUrl({ url }), TTYD_SUBPROTOCOL);
     } catch {
+      socketFailedRef.current = true;
       setStatus("error");
       return;
     }
@@ -121,8 +178,18 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
       try {
         socket.send(ttydAuthFrame({ columns: sizeRef.current.cols, rows: sizeRef.current.rows }));
         socket.send(ttydResizeFrame(sizeRef.current.cols, sizeRef.current.rows));
+        if (pendingInputRef.current.length > 0) {
+          // One websocket frame makes the pre-open queue all-or-nothing from this
+          // client's perspective; never execute a prefix of a buffered command.
+          socket.send(ttydInputFrame(pendingInputRef.current));
+          pendingInputRef.current = "";
+        }
+        socketAuthenticatedRef.current = true;
       } catch {
-        // a closed socket between open and send — onclose handles state.
+        socketFailedRef.current = true;
+        setStatus("error");
+        closeSocket(socket);
+        return;
       }
       setStatus("open");
     };
@@ -144,46 +211,60 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     };
 
     socket.onerror = () => {
-      if (!disposed) setStatus("error");
+      if (!disposed) {
+        socketFailedRef.current = true;
+        setStatus("error");
+      }
     };
     socket.onclose = () => {
-      if (!disposed) setStatus("closed");
+      if (wsRef.current === socket) wsRef.current = null;
+      socketAuthenticatedRef.current = false;
+      if (!disposed) setStatus(socketFailedRef.current ? "error" : "closed");
     };
 
     return () => {
       disposed = true;
       wsRef.current = null;
+      socketAuthenticatedRef.current = false;
       // Drop handlers so an in-flight close/error doesn't mutate state post-unmount.
       socket.onopen = null;
       socket.onmessage = null;
       socket.onerror = null;
       socket.onclose = null;
-      try {
-        socket.close();
-      } catch {
-        // ignore teardown errors
-      }
+      closeSocket(socket);
     };
     // A url/token change (rotation) re-runs this effect → close old, open new.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [transport, url, token]);
+  }, [transport, url, token, expiresAt]);
 
   return useMemo<UseTerminalStreamResult>(() => {
     const write = (data: string) => {
       const ws = wsRef.current;
-      if (ws && ws.readyState === WebSocket.OPEN) {
+      if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
         try {
           ws.send(ttydInputFrame(data));
         } catch {
-          // socket raced closed — the reconnect effect will re-establish.
+          socketFailedRef.current = true;
+          setStatus("error");
+          closeSocket(ws);
+        }
+      } else if (transport === "pty-ws" && !socketFailedRef.current) {
+        const nextSize = pendingInputRef.current.length + data.length;
+        if (nextSize > MAX_PENDING_TERMINAL_INPUT_CODE_UNITS) {
+          pendingInputRef.current = "";
+          socketFailedRef.current = true;
+          setStatus("error");
+          closeSocket(ws);
+          return;
         }
+        pendingInputRef.current += data;
       }
     };
     const resize = (cols: number, rows: number) => {
       if (cols <= 0 || rows <= 0) return;
       sizeRef.current = { cols, rows };
       const ws = wsRef.current;
-      if (ws && ws.readyState === WebSocket.OPEN) {
+      if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
         try {
           ws.send(ttydResizeFrame(cols, rows));
         } catch {
@@ -194,14 +275,12 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     const disconnect = () => {
       const ws = wsRef.current;
       wsRef.current = null;
-      if (ws) {
-        try {
-          ws.close();
-        } catch {
-          // ignore
-        }
-      }
+      pendingInputRef.current = "";
+      socketFailedRef.current = false;
+      socketAuthenticatedRef.current = false;
+      setStatus("closed");
+      closeSocket(ws);
     };
     return { connected: status === "open", status, write, resize, disconnect };
-  }, [status]);
+  }, [status, transport]);
 }

package/src/hooks/use-video-artifact-playback.ts

@@ -0,0 +1,28 @@
+import { useMemo } from "react";
+import type { VideoArtifactPlaybackLoader } from "../timeline";
+import { useOpenGeni, type ClientOverride } from "../session-context";
+
+/**
+ * Bind the current public SDK client/workspace to MessageTimeline's renewable
+ * video-source boundary. Proxy hosts may omit the method until they support
+ * retained video; the failure remains local to the player instead of loading
+ * any video bytes through React.
+ */
+export function useVideoArtifactPlaybackLoader(
+  options: ClientOverride = {},
+): VideoArtifactPlaybackLoader {
+  const { client, workspaceId } = useOpenGeni(options);
+  return useMemo(
+    () => async (artifactId: string, signal?: AbortSignal) => {
+      if (typeof client.createVideoArtifactPlaybackSource !== "function") {
+        throw new Error("This OpenGeni host does not expose retained-video playback.");
+      }
+      return await client.createVideoArtifactPlaybackSource(
+        workspaceId,
+        artifactId,
+        signal ? { signal } : {},
+      );
+    },
+    [client, workspaceId],
+  );
+}

package/src/hooks/use-workspace-edit.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 
 /**
  * The wake-on-edit state machine. This hook owns the logic and the UI renders
@@ -73,7 +74,7 @@ export type UseWorkspaceEditResult = {
 };
 
 function isLive(liveness: string | undefined): boolean {
-  return liveness === "warm" || liveness === "draining";
+  return sandboxAcceptsLiveIo(liveness);
 }
 
 /**

package/src/index.ts

@@ -9,9 +9,12 @@
 // container-responsive composers additionally import responsive.css.
 
 export type {
+  EmbeddedBrowserInteractionClientLike,
+  EmbeddedComputerInteractionClientLike,
   EmbeddedFileAttachmentClientLike,
   EmbeddedGoalClientLike,
   EmbeddedHumanInputSessionClientLike,
+  EmbeddedInteractionClientLike,
   EmbeddedSessionEventClientLike,
   EmbeddedSessionLineageClientLike,
   EmbeddedSessionMcpApprovalPolicyClientLike,
@@ -22,6 +25,7 @@ export type {
 export { OpenGeniProvider } from "./provider";
 export type { OpenGeniProviderProps } from "./provider";
 export { useOpenGeni, useOpenGeniClient } from "./session-context";
+export { useVideoArtifactPlaybackLoader } from "./hooks/use-video-artifact-playback";
 export type { ClientOverride, OpenGeniContextValue } from "./session-context";
 export { usePageLiveActivity } from "./hooks/internal";
 
@@ -332,6 +336,9 @@ export {
 } from "./timeline";
 export type {
   CreateToolRegistryOptions,
+  RetainedArtifactLoader,
+  RetainedScreenshotLoader,
+  VideoArtifactPlaybackLoader,
   ToolRegistry,
   ToolRegistryEntry,
   ToolRenderer,
@@ -464,6 +471,8 @@ export {
 } from "./model-policy";
 export type { LatencyModeId, PickerBillingClass, PickerModelRow } from "./model-policy";
 export { MessageTimeline, TimelineRow } from "./components/message-timeline";
+export { GeneratedVideoPlayer } from "./components/generated-video-player";
+export type { GeneratedVideoPlayerProps } from "./components/generated-video-player";
 export type { MessageTimelineProps } from "./components/message-timeline";
 export { UserMessageBody, userMessageLikelyNeedsDisclosure } from "./components/user-message-body";
 export type { UserMessageBodyProps } from "./components/user-message-body";
@@ -511,6 +520,7 @@ export {
   WORKBENCH_TAB_CHANGES,
   WORKBENCH_TAB_FILES,
   WORKBENCH_TAB_TERMINAL,
+  WORKBENCH_TAB_BROWSER,
   WORKBENCH_TAB_DESKTOP,
   WORKBENCH_SURFACES,
 } from "./components/sandbox-workspace";

package/src/interaction.ts

@@ -0,0 +1,71 @@
+// @opengeni/react/interaction — standalone Browser/Computer resource UI.
+// Framework hosts may pass a narrow structural client instead of the full provider.
+export type {
+  EmbeddedBrowserInteractionClientLike,
+  EmbeddedComputerInteractionClientLike,
+  EmbeddedInteractionClientLike,
+} from "./client";
+export {
+  useEmbeddedBrowserInteraction,
+  useEmbeddedComputerInteraction,
+  useEmbeddedInteraction,
+} from "./session-context";
+export type {
+  EmbeddedBrowserInteractionClientOverride,
+  EmbeddedComputerInteractionClientOverride,
+  EmbeddedInteractionClientOverride,
+} from "./session-context";
+export { useAttachedBrowsers } from "./hooks/use-attached-browsers";
+export type {
+  AttachedBrowsersClient,
+  UseAttachedBrowsersOptions,
+  UseAttachedBrowsersResult,
+} from "./hooks/use-attached-browsers";
+export { useBrowserSessions } from "./hooks/use-browser-sessions";
+export type {
+  BrowserSessionsClient,
+  UseBrowserSessionsOptions,
+  UseBrowserSessionsResult,
+} from "./hooks/use-browser-sessions";
+export { useBrowserIdentities } from "./hooks/use-browser-identities";
+export type {
+  BrowserIdentitiesClient,
+  UseBrowserIdentitiesOptions,
+  UseBrowserIdentitiesResult,
+} from "./hooks/use-browser-identities";
+export { useBrowserSession } from "./hooks/use-browser-session";
+export type {
+  UseBrowserSessionOptions,
+  UseBrowserSessionResult,
+} from "./hooks/use-browser-session";
+export { useBrowserFrameStream } from "./hooks/use-browser-frame-stream";
+export type {
+  BrowserFrameConnectionState,
+  BrowserFrameWebSocket,
+  BrowserFrameWebSocketFactory,
+  UseBrowserFrameStreamOptions,
+  UseBrowserFrameStreamResult,
+} from "./hooks/use-browser-frame-stream";
+export { BrowserViewer } from "./components/browser-viewer";
+export type { BrowserViewerNotification, BrowserViewerProps } from "./components/browser-viewer";
+export { useComputerSessions } from "./hooks/use-computer-sessions";
+export type {
+  ComputerSessionsClient,
+  UseComputerSessionsOptions,
+  UseComputerSessionsResult,
+} from "./hooks/use-computer-sessions";
+export { useComputerSession } from "./hooks/use-computer-session";
+export type {
+  UseComputerSessionOptions,
+  UseComputerSessionResult,
+} from "./hooks/use-computer-session";
+export { useComputerFrameStream } from "./hooks/use-computer-frame-stream";
+export type {
+  ComputerFrameConnectionState,
+  ComputerFrameWebSocket,
+  ComputerFrameWebSocketFactory,
+  UseComputerFrameStreamOptions,
+  UseComputerFrameStreamResult,
+} from "./hooks/use-computer-frame-stream";
+export { ComputerViewer } from "./components/computer-viewer";
+export type { ComputerViewerNotification, ComputerViewerProps } from "./components/computer-viewer";

package/src/lib/relay-wire.ts

@@ -17,6 +17,10 @@ import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
 
 /** `StreamKind.STREAM_KIND_DESKTOP` (agent-proto enum value). */
 export const STREAM_KIND_DESKTOP = 2;
+/** `StreamKind.STREAM_KIND_BROWSER` (agent-proto enum value). */
+export const STREAM_KIND_BROWSER = 3;
+/** `StreamKind.STREAM_KIND_COMPUTER` (agent-proto enum value). */
+export const STREAM_KIND_COMPUTER = 4;
 /** `StreamRole.STREAM_ROLE_CLIENT` (agent-proto enum value). */
 export const STREAM_ROLE_CLIENT = 2;
 

package/src/lib/sandbox-liveness.ts

@@ -0,0 +1,11 @@
+/**
+ * A sandbox is available for new I/O only after a holder has observed `warm`.
+ *
+ * `draining` means the holder count is zero and teardown owns the provider
+ * instance. The provider may disappear before the durable lease reaches `cold`,
+ * so treating `draining` as live races capture/termination. Explicit user intent
+ * reacquires a holder; only its subsequent `warm` state re-enables live I/O.
+ */
+export function sandboxAcceptsLiveIo(liveness: string | null | undefined): boolean {
+  return liveness === "warm";
+}