@opengeni/react 0.48.0 → 0.57.0

package/src/hooks/use-supergrok-accounts.ts

@@ -0,0 +1,81 @@
+import type { SuperGrokAccount, SuperGrokAccountsResponse } from "@opengeni/sdk";
+import { useCallback } from "react";
+
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { useMutationRunner, usePolledValue } from "./internal";
+
+export type SuperGrokAccountsClientLike = {
+  listSuperGrokAccounts: (workspaceId: string) => Promise<SuperGrokAccountsResponse>;
+  activateSuperGrokAccount?: (
+    workspaceId: string,
+    accountId: string,
+  ) => Promise<{ activated: boolean; accountId: string }>;
+};
+
+export type UseSuperGrokAccountsOptions = ClientOverride & {
+  enabled?: boolean | undefined;
+  pollIntervalMs?: number | undefined;
+  supergrokClient?: SuperGrokAccountsClientLike | undefined;
+};
+
+export type UseSuperGrokAccountsResult = {
+  accounts: SuperGrokAccount[];
+  activeAccountId: string | null;
+  settings: SuperGrokAccountsResponse["settings"];
+  loading: boolean;
+  refresh: () => Promise<void>;
+  activate: (accountId: string) => Promise<boolean>;
+  activating: boolean;
+  mutationError: Error | null;
+};
+
+const EMPTY: SuperGrokAccountsResponse = {
+  accounts: [],
+  activeAccountId: null,
+  settings: {
+    rotationEnabled: false,
+    rotationStrategy: "sharded",
+    activeCredentialId: null,
+  },
+};
+
+/** Workspace-visible xAI accounts. Workspace scope is the connection default. */
+export function useSuperGrokAccounts(
+  options: UseSuperGrokAccountsOptions = {},
+): UseSuperGrokAccountsResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const supergrokClient =
+    options.supergrokClient ?? (client as unknown as SuperGrokAccountsClientLike);
+  const load = useCallback(
+    async () => await supergrokClient.listSuperGrokAccounts(workspaceId),
+    [supergrokClient, workspaceId],
+  );
+  const { data, loading, refresh } = usePolledValue(load, {
+    enabled: options.enabled,
+    pollIntervalMs: options.pollIntervalMs,
+  });
+  const { run, mutating: activating, mutationError } = useMutationRunner();
+  const activate = useCallback(
+    async (accountId: string): Promise<boolean> => {
+      if (!supergrokClient.activateSuperGrokAccount) return false;
+      const result = await run(async () => {
+        await supergrokClient.activateSuperGrokAccount!(workspaceId, accountId);
+        return true;
+      });
+      if (result) await refresh();
+      return result === true;
+    },
+    [refresh, run, supergrokClient, workspaceId],
+  );
+  const state = data ?? EMPTY;
+  return {
+    accounts: state.accounts,
+    activeAccountId: state.activeAccountId,
+    settings: state.settings,
+    loading,
+    refresh,
+    activate,
+    activating,
+    mutationError,
+  };
+}

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

@@ -7,7 +7,16 @@ import {
   ttydResizeFrame,
   TtydServerCommand,
 } from "@opengeni/sdk";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  decodeStreamFrame,
+  decodeStreamOpenAck,
+  encodeStreamFrame,
+  encodeStreamOpen,
+  type RelayChannel,
+  STREAM_KIND_PTY,
+  STREAM_ROLE_CLIENT,
+} from "../lib/relay-wire";
 
 /** The ttyd connection lifecycle as surfaced to the component. */
 export type TerminalStreamStatus = "connecting" | "open" | "closed" | "error";
@@ -17,11 +26,14 @@ 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. */
   onTitle?: ((title: string) => void) | undefined;
+  /** Requests a fresh negotiated terminal grant after an unexpected transport
+   * failure. Intentional disconnects and effect cleanup never call it. */
+  onReconnectNeeded?: (() => void) | undefined;
   /** Initial PTY size to seed the ttyd auth frame + first resize. */
   initialCols?: number | undefined;
   initialRows?: number | undefined;
@@ -31,7 +43,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 +52,84 @@ 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;
+const TERMINAL_RECONNECT_INITIAL_MS = 100;
+const TERMINAL_RECONNECT_MAX_MS = 3_000;
+const RELAY_TAG_OPEN = 1;
+const RELAY_TAG_OPEN_ACK = 2;
+const RELAY_TAG_FRAME = 3;
+
+function relayDatagram(tag: number, body: Uint8Array): ArrayBuffer {
+  const bytes = new Uint8Array(body.length + 1);
+  bytes[0] = tag;
+  bytes.set(body, 1);
+  return bytes.buffer;
+}
+
+function relayChannelFromUrl(url: string): RelayChannel {
+  const endpoint = new URL(url);
+  const channel: RelayChannel = {
+    channelId: endpoint.searchParams.get("channel") ?? "",
+    workspaceId: endpoint.searchParams.get("ws") ?? "",
+    agentId: endpoint.searchParams.get("agent") ?? "",
+    kind: STREAM_KIND_PTY,
+    port: Number(endpoint.searchParams.get("port") ?? "0"),
+  };
+  if (
+    !channel.channelId ||
+    !channel.workspaceId ||
+    !channel.agentId ||
+    !Number.isSafeInteger(channel.port) ||
+    channel.port <= 0
+  ) {
+    throw new Error("terminal relay endpoint is incomplete");
+  }
+  return channel;
+}
+
+function sendRelayInput(
+  socket: WebSocket,
+  channel: RelayChannel,
+  sequence: bigint,
+  data: string,
+): void {
+  socket.send(
+    relayDatagram(
+      RELAY_TAG_FRAME,
+      encodeStreamFrame({
+        channelId: channel.channelId,
+        seq: sequence.toString(),
+        data: new TextEncoder().encode(data),
+        producedAtMs: String(Date.now()),
+      }),
+    ),
+  );
+}
+
+/** 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?.transport !== "relay-pty") ||
+    !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 +143,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
@@ -70,9 +169,21 @@ function decodeFrame(data: string | ArrayBuffer): { command: string; payload: st
  * SSR-safe: the socket open lives in `useEffect`, so a server render is a no-op.
  */
 export function useTerminalStream(options: UseTerminalStreamOptions): UseTerminalStreamResult {
-  const { capability, onOutput, onTitle, initialCols, initialRows } = options;
+  const { capability, onOutput, onTitle, onReconnectNeeded, initialCols, initialRows } = options;
   const [status, setStatus] = useState<TerminalStreamStatus>("closed");
+  const [reconnectGeneration, setReconnectGeneration] = useState(0);
   const wsRef = useRef<WebSocket | null>(null);
+  const pendingInputRef = useRef("");
+  const socketFailedRef = useRef(false);
+  const socketAuthenticatedRef = useRef(false);
+  const relayChannelRef = useRef<RelayChannel | null>(null);
+  const relayIdentityRef = useRef<string | null>(null);
+  const relayInputSequenceRef = useRef(0n);
+  const relayOutputSequenceRef = useRef(0n);
+  const reconnectAttemptRef = useRef(0);
+  const credentialIdentityRef = useRef<string | null>(null);
+  const refreshRequestedRef = useRef(false);
+  const intentionalCloseRef = useRef<WeakSet<WebSocket>>(new WeakSet());
   // 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 }>({
@@ -83,52 +194,219 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
   // render (the parent passes fresh closures each time).
   const onOutputRef = useRef(onOutput);
   const onTitleRef = useRef(onTitle);
+  const onReconnectNeededRef = useRef(onReconnectNeeded);
   onOutputRef.current = onOutput;
   onTitleRef.current = onTitle;
+  onReconnectNeededRef.current = onReconnectNeeded;
 
   const transport = capability?.transport ?? null;
   const url = capability?.url ?? null;
   const token = capability?.token ?? null;
+  const expiresAt = capability?.expiresAt ?? null;
+  const transportRef = useRef(transport);
+  transportRef.current = transport;
 
   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) {
+    const relay = transport === "relay-pty";
+    if (transport !== "pty-ws" && !relay) {
+      // 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;
+      relayIdentityRef.current = null;
+      relayInputSequenceRef.current = 0n;
+      relayOutputSequenceRef.current = 0n;
+      reconnectAttemptRef.current = 0;
+      credentialIdentityRef.current = null;
+      refreshRequestedRef.current = false;
+      setStatus("closed");
+      return;
+    }
+    const credentialIdentity = `${transport}\u0000${url ?? ""}\u0000${token ?? ""}\u0000${expiresAt ?? ""}`;
+    if (credentialIdentityRef.current !== credentialIdentity) {
+      credentialIdentityRef.current = credentialIdentity;
+      reconnectAttemptRef.current = 0;
+      refreshRequestedRef.current = false;
+    }
+    // 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. Ask once for the exact fresh grant.
       setStatus("closed");
+      if (!refreshRequestedRef.current) {
+        refreshRequestedRef.current = true;
+        onReconnectNeededRef.current?.();
+      }
       return;
     }
 
     let disposed = false;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
     let socket: WebSocket;
+    let relayChannel: RelayChannel | null = null;
+    const relayOutputDecoder = new TextDecoder();
     setStatus("connecting");
     try {
-      // The ttyd "tty" subprotocol is REQUIRED — ttyd rejects a handshake without
-      // it. The scoped token is already in the tunnel `url`.
-      socket = new WebSocket(terminalSocketUrl({ url }), TTYD_SUBPROTOCOL);
+      if (relay) {
+        relayChannel = relayChannelFromUrl(url);
+        const relayIdentity = [
+          relayChannel.workspaceId,
+          relayChannel.agentId,
+          relayChannel.port,
+          relayChannel.channelId,
+        ].join("\u0000");
+        if (relayIdentityRef.current !== relayIdentity) {
+          relayIdentityRef.current = relayIdentity;
+          relayInputSequenceRef.current = 0n;
+          relayOutputSequenceRef.current = 0n;
+        }
+        relayChannelRef.current = relayChannel;
+        socket = new WebSocket(url);
+      } else {
+        // The ttyd "tty" subprotocol is REQUIRED — ttyd rejects a handshake without
+        // it. The scoped token is already in the tunnel `url`.
+        socket = new WebSocket(terminalSocketUrl({ url }), TTYD_SUBPROTOCOL);
+      }
     } catch {
+      socketFailedRef.current = true;
       setStatus("error");
       return;
     }
     socket.binaryType = "arraybuffer";
     wsRef.current = socket;
 
+    const requestFreshGrant = () => {
+      if (disposed || refreshRequestedRef.current || intentionalCloseRef.current.has(socket))
+        return;
+      refreshRequestedRef.current = true;
+      onReconnectNeededRef.current?.();
+    };
+
+    const scheduleTransportReconnect = () => {
+      if (disposed || reconnectTimer !== null || intentionalCloseRef.current.has(socket)) return;
+      if (refreshRequestedRef.current) return;
+      if (!terminalStreamCredentialUsable({ transport, url, expiresAt })) {
+        requestFreshGrant();
+        return;
+      }
+      const attempt = reconnectAttemptRef.current++;
+      const delay = Math.min(
+        TERMINAL_RECONNECT_INITIAL_MS * 2 ** Math.min(attempt, 8),
+        TERMINAL_RECONNECT_MAX_MS,
+      );
+      setStatus("connecting");
+      reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        if (!disposed) setReconnectGeneration((generation) => generation + 1);
+      }, delay);
+    };
+
     socket.onopen = () => {
       if (disposed) return;
+      if (relay && relayChannel) {
+        try {
+          socket.send(
+            relayDatagram(
+              RELAY_TAG_OPEN,
+              encodeStreamOpen({
+                channel: relayChannel,
+                token: token ?? "",
+                role: STREAM_ROLE_CLIENT,
+                resumeFromSeq: relayOutputSequenceRef.current.toString(),
+              }),
+            ),
+          );
+        } catch {
+          socketFailedRef.current = false;
+          setStatus("connecting");
+          closeSocket(socket);
+        }
+        return;
+      }
       // ttyd's required first frame: the auth message (empty token — the gate is
       // the tunnel url + scoped stream token, not a ttyd -c credential), seeded
       // with the current PTY geometry. Then an explicit resize to be safe.
       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 = false;
+        setStatus("connecting");
+        closeSocket(socket);
+        return;
       }
       setStatus("open");
+      reconnectAttemptRef.current = 0;
+      refreshRequestedRef.current = false;
     };
 
     socket.onmessage = (ev: MessageEvent) => {
       if (disposed) return;
+      if (relay) {
+        if (!(ev.data instanceof ArrayBuffer) || !relayChannel) return;
+        const bytes = new Uint8Array(ev.data);
+        if (bytes.length < 1) return;
+        const tag = bytes[0];
+        const body = bytes.subarray(1);
+        if (tag === RELAY_TAG_OPEN_ACK) {
+          try {
+            const ack = decodeStreamOpenAck(body);
+            if (!ack.accepted) throw new Error(ack.error?.message ?? "terminal relay rejected");
+            reconnectAttemptRef.current = 0;
+            refreshRequestedRef.current = false;
+            socketAuthenticatedRef.current = true;
+            if (pendingInputRef.current.length > 0) {
+              sendRelayInput(
+                socket,
+                relayChannel,
+                relayInputSequenceRef.current++,
+                pendingInputRef.current,
+              );
+              pendingInputRef.current = "";
+            }
+            setStatus("open");
+          } catch {
+            socketFailedRef.current = true;
+            setStatus("error");
+            requestFreshGrant();
+            closeSocket(socket);
+          }
+        } else if (tag === RELAY_TAG_FRAME && socketAuthenticatedRef.current) {
+          try {
+            const frame = decodeStreamFrame(body);
+            const sequence = BigInt(frame.seq);
+            if (sequence < relayOutputSequenceRef.current) return;
+            relayOutputSequenceRef.current = sequence + 1n;
+            if (frame.data.length > 0) {
+              onOutputRef.current?.(relayOutputDecoder.decode(frame.data, { stream: true }));
+            }
+          } catch {
+            // Ignore one malformed frame; the live PTY remains usable.
+          }
+        }
+        return;
+      }
       const { command, payload } = decodeFrame(ev.data as string | ArrayBuffer);
       switch (command) {
         case TtydServerCommand.OUTPUT:
@@ -144,64 +422,98 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     };
 
     socket.onerror = () => {
-      if (!disposed) setStatus("error");
+      if (!disposed) {
+        // A network/relay outage is retryable with the same credential and PTY.
+        // Keep accepting bounded input while the transport comes back.
+        socketFailedRef.current = false;
+        setStatus("connecting");
+        closeSocket(socket);
+      }
     };
     socket.onclose = () => {
-      if (!disposed) setStatus("closed");
+      if (wsRef.current === socket) wsRef.current = null;
+      socketAuthenticatedRef.current = false;
+      if (!disposed) {
+        if (socketFailedRef.current) setStatus("error");
+        else scheduleTransportReconnect();
+      }
     };
 
     return () => {
       disposed = true;
       wsRef.current = null;
+      socketAuthenticatedRef.current = false;
+      relayChannelRef.current = null;
+      if (reconnectTimer !== null) clearTimeout(reconnectTimer);
       // 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, reconnectGeneration]);
 
-  return useMemo<UseTerminalStreamResult>(() => {
-    const write = (data: string) => {
-      const ws = wsRef.current;
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        try {
+  const write = useCallback((data: string) => {
+    const currentTransport = transportRef.current;
+    const ws = wsRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
+      try {
+        const relayChannel = relayChannelRef.current;
+        if (currentTransport === "relay-pty" && relayChannel) {
+          sendRelayInput(ws, relayChannel, relayInputSequenceRef.current++, data);
+        } else {
           ws.send(ttydInputFrame(data));
-        } catch {
-          // socket raced closed — the reconnect effect will re-establish.
         }
+      } catch {
+        socketFailedRef.current = false;
+        setStatus("connecting");
+        closeSocket(ws);
       }
-    };
-    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) {
-        try {
-          ws.send(ttydResizeFrame(cols, rows));
-        } catch {
-          // socket raced closed — geometry is replayed on the next open.
-        }
+    } else if (
+      (currentTransport === "pty-ws" || currentTransport === "relay-pty") &&
+      !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;
       }
-    };
-    const disconnect = () => {
-      const ws = wsRef.current;
-      wsRef.current = null;
-      if (ws) {
-        try {
-          ws.close();
-        } catch {
-          // ignore
-        }
+      pendingInputRef.current += data;
+    }
+  }, []);
+  const resize = useCallback((cols: number, rows: number) => {
+    if (cols <= 0 || rows <= 0) return;
+    sizeRef.current = { cols, rows };
+    const ws = wsRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN && socketAuthenticatedRef.current) {
+      try {
+        // Self-hosted relay PTYs carry raw input/output frames. Resize remains
+        // an out-of-band control operation; do not send ttyd framing into them.
+        if (transportRef.current === "pty-ws") ws.send(ttydResizeFrame(cols, rows));
+      } catch {
+        // socket raced closed — geometry is replayed on the next open.
       }
-    };
+    }
+  }, []);
+  const disconnect = useCallback(() => {
+    const ws = wsRef.current;
+    wsRef.current = null;
+    pendingInputRef.current = "";
+    socketFailedRef.current = false;
+    socketAuthenticatedRef.current = false;
+    relayChannelRef.current = null;
+    setStatus("closed");
+    if (ws) intentionalCloseRef.current.add(ws);
+    closeSocket(ws);
+  }, []);
+
+  return useMemo<UseTerminalStreamResult>(() => {
     return { connected: status === "open", status, write, resize, disconnect };
-  }, [status]);
+  }, [status, write, resize, disconnect]);
 }

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);
 }
 
 /**