@opengeni/react 3.1.0 → 3.1.2

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

@@ -17,6 +17,11 @@ import {
   STREAM_KIND_PTY,
   STREAM_ROLE_CLIENT,
 } from "../lib/relay-wire";
+import {
+  TERMINAL_INPUT_READY_PREFERENCE,
+  TERMINAL_INPUT_READY_PROTOCOL,
+  terminalInputReadyDecoder,
+} from "../lib/terminal-input-readiness";
 
 /** The ttyd connection lifecycle as surfaced to the component. */
 export type TerminalStreamStatus = "connecting" | "open" | "closed" | "error";
@@ -25,8 +30,12 @@ export type UseTerminalStreamOptions = {
   /** The Terminal cell of the negotiated capabilities (`capabilities.Terminal`).
    *  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" | "expiresAt"> | null;
+   *  falls back to the Channel-A firehose. Explicit PTY-capable cold cells may
+   *  buffer input, but cannot connect or flush until the grant arrives. */
+  capability:
+    | (Pick<TerminalCapability, "transport" | "url" | "token" | "expiresAt"> &
+        Partial<Pick<TerminalCapability, "ptyCapable" | "reason">>)
+    | 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. */
@@ -40,11 +49,16 @@ export type UseTerminalStreamOptions = {
 };
 
 export type UseTerminalStreamResult = {
-  /** True once the ttyd socket is open (and the auth frame has been sent). */
+  /** True when input can be sent. Legacy ttyd does not guarantee shell readiness. */
   connected: boolean;
   status: TerminalStreamStatus;
+  /** `waiting` requires explicit shell readiness; `legacy` has no such guarantee. */
+  inputReadiness: "pending" | "waiting" | "ready" | "legacy";
+  /** Deliberate escape for startup prompts/no-Readline shells. Clears queued
+   * typing without executing it, then enables unguaranteed manual input. */
+  useLegacyInput: () => void;
   /** Pipe a keystroke/paste to PTY stdin. Input during CONNECTING is bounded and
-   *  replayed only after ttyd authentication succeeds. */
+   *  replayed after negotiated readiness (or legacy ttyd preferences). */
   write: (data: string) => void;
   /** Tell ttyd the PTY window changed size (on xterm fit/resize). */
   resize: (cols: number, rows: number) => void;
@@ -52,8 +66,8 @@ 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
+// Keystrokes entered during startup are held until the negotiated input boundary.
+// Old ttyd servers retain explicitly legacy semantics. Bound 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.
@@ -161,7 +175,7 @@ function closeSocket(socket: WebSocket | null): void {
  *   - first frame: `JSON.stringify({ AuthToken: "" })` (+ optional columns/rows).
  *   - client→server: INPUT = "0"+data ; RESIZE = "1"+JSON({columns,rows}).
  *   - server→client: "0" = OUTPUT (→ xterm) ; "1" = SET_WINDOW_TITLE ;
- *     "2" = SET_PREFERENCES (ignored). Binary frames are decoded the same way.
+ *     "2" = SET_PREFERENCES (readiness negotiation). Binary frames decode identically.
  *
  * On a `url`/`token` rotation (a box rollover folds a fresh address into the cell)
  * the effect re-runs: the old socket closes and a fresh one connects — a brief
@@ -171,11 +185,15 @@ function closeSocket(socket: WebSocket | null): void {
 export function useTerminalStream(options: UseTerminalStreamOptions): UseTerminalStreamResult {
   const { capability, onOutput, onTitle, onReconnectNeeded, initialCols, initialRows } = options;
   const [status, setStatus] = useState<TerminalStreamStatus>("closed");
+  const [inputReadiness, setInputReadiness] =
+    useState<UseTerminalStreamResult["inputReadiness"]>("pending");
   const [reconnectGeneration, setReconnectGeneration] = useState(0);
   const wsRef = useRef<WebSocket | null>(null);
   const pendingInputRef = useRef("");
   const socketFailedRef = useRef(false);
   const socketAuthenticatedRef = useRef(false);
+  const legacyInputRef = useRef<(() => void) | null>(null);
+  const manuallyDisconnectedRef = useRef(false);
   const relayChannelRef = useRef<RelayChannel | null>(null);
   const relayIdentityRef = useRef<string | null>(null);
   const relayInputSequenceRef = useRef(0n);
@@ -205,8 +223,18 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
   const expiresAt = capability?.expiresAt ?? null;
   const transportRef = useRef(transport);
   transportRef.current = transport;
+  // A cold, explicitly PTY-capable cell may collect input before its viewer
+  // grant arrives. This is not a socket credential or a readiness assertion.
+  const acquiringPty =
+    transport === "sse-events" &&
+    capability?.ptyCapable === true &&
+    (capability.reason === "lease_cold" || capability.reason === "not_provisioned");
+  const acquiringPtyRef = useRef(acquiringPty);
+  acquiringPtyRef.current = acquiringPty;
 
   useEffect(() => {
+    manuallyDisconnectedRef.current = false;
+    setInputReadiness("pending");
     // 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;
@@ -222,6 +250,7 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
       reconnectAttemptRef.current = 0;
       credentialIdentityRef.current = null;
       refreshRequestedRef.current = false;
+      socketFailedRef.current = false;
       setStatus("closed");
       return;
     }
@@ -258,6 +287,11 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
     let socket: WebSocket;
     let relayChannel: RelayChannel | null = null;
+    let authSent = false;
+    let preferencesReceived = false;
+    let readinessNegotiated = false;
+    let sentSize: { cols: number; rows: number } | null = null;
+    const decodeReadyOutput = terminalInputReadyDecoder();
     const relayOutputDecoder = new TextDecoder();
     setStatus("connecting");
     try {
@@ -311,12 +345,47 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
       setStatus("connecting");
       reconnectTimer = setTimeout(() => {
         reconnectTimer = null;
-        if (!disposed) setReconnectGeneration((generation) => generation + 1);
+        if (!disposed && !manuallyDisconnectedRef.current)
+          setReconnectGeneration((generation) => generation + 1);
       }, delay);
     };
 
+    const openTtydInput = (mode: "ready" | "legacy", discardPending = false) => {
+      if (
+        disposed ||
+        wsRef.current !== socket ||
+        socket.readyState !== WebSocket.OPEN ||
+        !authSent ||
+        socketFailedRef.current
+      )
+        return;
+      if (discardPending) pendingInputRef.current = "";
+      try {
+        // A fit/resize may have happened while shell readiness was pending.
+        if (sentSize?.cols !== sizeRef.current.cols || sentSize.rows !== sizeRef.current.rows) {
+          socket.send(ttydResizeFrame(sizeRef.current.cols, sizeRef.current.rows));
+          sentSize = { ...sizeRef.current };
+        }
+        if (pendingInputRef.current.length > 0) {
+          socket.send(ttydInputFrame(pendingInputRef.current));
+          pendingInputRef.current = "";
+        }
+        socketAuthenticatedRef.current = true;
+        legacyInputRef.current = null;
+        setInputReadiness(mode);
+        setStatus("open");
+        reconnectAttemptRef.current = 0;
+        refreshRequestedRef.current = false;
+      } catch {
+        socketAuthenticatedRef.current = false;
+        setInputReadiness("pending");
+        setStatus("connecting");
+        closeSocket(socket);
+      }
+    };
+
     socket.onopen = () => {
-      if (disposed) return;
+      if (disposed || wsRef.current !== socket || socketFailedRef.current) return;
       if (relay && relayChannel) {
         try {
           socket.send(
@@ -343,26 +412,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;
+        sentSize = { ...sizeRef.current };
+        authSent = true;
       } catch {
         socketFailedRef.current = false;
         setStatus("connecting");
         closeSocket(socket);
         return;
       }
-      setStatus("open");
-      reconnectAttemptRef.current = 0;
-      refreshRequestedRef.current = false;
     };
 
     socket.onmessage = (ev: MessageEvent) => {
-      if (disposed) return;
+      if (disposed || wsRef.current !== socket || socketFailedRef.current) return;
       if (relay) {
         if (!(ev.data instanceof ArrayBuffer) || !relayChannel) return;
         const bytes = new Uint8Array(ev.data);
@@ -386,6 +447,7 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
               pendingInputRef.current = "";
             }
             setStatus("open");
+            setInputReadiness("ready");
           } catch {
             socketFailedRef.current = true;
             setStatus("error");
@@ -410,19 +472,49 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
       const { command, payload } = decodeFrame(ev.data as string | ArrayBuffer);
       switch (command) {
         case TtydServerCommand.OUTPUT:
-          onOutputRef.current?.(payload);
+          if (readinessNegotiated) {
+            const decoded = decodeReadyOutput(payload);
+            if (decoded.output) onOutputRef.current?.(decoded.output);
+            if (decoded.ready && !socketAuthenticatedRef.current) openTtydInput("ready");
+          } else {
+            onOutputRef.current?.(payload);
+          }
           break;
         case TtydServerCommand.SET_WINDOW_TITLE:
           onTitleRef.current?.(payload);
           break;
-        // SET_PREFERENCES ("2") and anything else: ignored.
+        case TtydServerCommand.SET_PREFERENCES:
+          if (!authSent || preferencesReceived || socketAuthenticatedRef.current) break;
+          preferencesReceived = true;
+          try {
+            const preferences = JSON.parse(payload) as Record<string, unknown>;
+            if (!preferences || typeof preferences !== "object" || Array.isArray(preferences)) {
+              throw new Error("invalid ttyd preferences");
+            }
+            const protocol = preferences[TERMINAL_INPUT_READY_PREFERENCE];
+            if (protocol === undefined) {
+              // Old images/running daemons do not acquire a guarantee merely
+              // because this client is new. Preserve their legacy input path.
+              openTtydInput("legacy");
+            } else {
+              readinessNegotiated = protocol === TERMINAL_INPUT_READY_PROTOCOL;
+              setInputReadiness("waiting");
+              legacyInputRef.current = () => openTtydInput("legacy", true);
+            }
+          } catch {
+            // Invalid negotiation is not readiness. Manual input remains a
+            // deliberate escape, never an automatic fallback or timer flush.
+            setInputReadiness("waiting");
+            legacyInputRef.current = () => openTtydInput("legacy", true);
+          }
+          break;
         default:
           break;
       }
     };
 
     socket.onerror = () => {
-      if (!disposed) {
+      if (!disposed && wsRef.current === socket && !intentionalCloseRef.current.has(socket)) {
         // A network/relay outage is retryable with the same credential and PTY.
         // Keep accepting bounded input while the transport comes back.
         socketFailedRef.current = false;
@@ -431,8 +523,11 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
       }
     };
     socket.onclose = () => {
+      if (disposed || wsRef.current !== socket) return;
       if (wsRef.current === socket) wsRef.current = null;
       socketAuthenticatedRef.current = false;
+      legacyInputRef.current = null;
+      setInputReadiness("pending");
       if (!disposed) {
         if (socketFailedRef.current) setStatus("error");
         else scheduleTransportReconnect();
@@ -443,6 +538,7 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
       disposed = true;
       wsRef.current = null;
       socketAuthenticatedRef.current = false;
+      legacyInputRef.current = null;
       relayChannelRef.current = null;
       if (reconnectTimer !== null) clearTimeout(reconnectTimer);
       // Drop handlers so an in-flight close/error doesn't mutate state post-unmount.
@@ -454,7 +550,7 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     };
     // A url/token change (rotation) re-runs this effect → close old, open new.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [transport, url, token, expiresAt, reconnectGeneration]);
+  }, [transport, url, token, expiresAt, acquiringPty, reconnectGeneration]);
 
   const write = useCallback((data: string) => {
     const currentTransport = transportRef.current;
@@ -468,12 +564,30 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
           ws.send(ttydInputFrame(data));
         }
       } catch {
+        // A synchronous ttyd send failure did not enqueue these bytes. Retain
+        // them for the next explicit readiness boundary, never replay a send
+        // which returned successfully. Relay sequencing keeps its own contract.
+        if (currentTransport === "pty-ws") {
+          const nextSize = pendingInputRef.current.length + data.length;
+          if (nextSize > MAX_PENDING_TERMINAL_INPUT_CODE_UNITS) {
+            pendingInputRef.current = "";
+            socketFailedRef.current = true;
+            socketAuthenticatedRef.current = false;
+            setStatus("error");
+            closeSocket(ws);
+            return;
+          }
+          pendingInputRef.current += data;
+        }
+        socketAuthenticatedRef.current = false;
         socketFailedRef.current = false;
         setStatus("connecting");
         closeSocket(ws);
       }
     } else if (
-      (currentTransport === "pty-ws" || currentTransport === "relay-pty") &&
+      (currentTransport === "pty-ws" ||
+        currentTransport === "relay-pty" ||
+        acquiringPtyRef.current) &&
       !socketFailedRef.current
     ) {
       const nextSize = pendingInputRef.current.length + data.length;
@@ -502,18 +616,30 @@ export function useTerminalStream(options: UseTerminalStreamOptions): UseTermina
     }
   }, []);
   const disconnect = useCallback(() => {
+    manuallyDisconnectedRef.current = true;
     const ws = wsRef.current;
     wsRef.current = null;
     pendingInputRef.current = "";
     socketFailedRef.current = false;
     socketAuthenticatedRef.current = false;
+    legacyInputRef.current = null;
     relayChannelRef.current = null;
     setStatus("closed");
+    setInputReadiness("pending");
     if (ws) intentionalCloseRef.current.add(ws);
     closeSocket(ws);
   }, []);
+  const useLegacyInput = useCallback(() => legacyInputRef.current?.(), []);
 
   return useMemo<UseTerminalStreamResult>(() => {
-    return { connected: status === "open", status, write, resize, disconnect };
-  }, [status, write, resize, disconnect]);
+    return {
+      connected: status === "open",
+      status,
+      inputReadiness,
+      useLegacyInput,
+      write,
+      resize,
+      disconnect,
+    };
+  }, [status, inputReadiness, useLegacyInput, write, resize, disconnect]);
 }

package/src/hooks/use-transcription.ts

@@ -611,6 +611,12 @@ function classifyStartError(error: unknown): TranscriptionErrorCode {
 
 export function normalizeTranscriptionErrorCode(code: unknown): TranscriptionErrorCode {
   switch (code) {
+    case "insufficient_credits":
+    case "allowance_exhausted":
+    case "monthly_model_cost_limit":
+    case "unavailable":
+    case "too_large":
+    case "invalid_audio":
     case "permission_denied":
     case "not_supported":
     case "network":

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

@@ -10,6 +10,7 @@ import type {
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
+import { normalizeError } from "../lib/error-message";
 import {
   useDebouncedCallback,
   usePageLiveActivity,
@@ -463,7 +464,7 @@ function operationKey(): string {
 }
 
 function asError(cause: unknown): Error {
-  return cause instanceof Error ? cause : new Error(String(cause));
+  return normalizeError(cause);
 }
 
 function isOutcomeUnknownError(cause: unknown): boolean {

package/src/hooks/use-usage.ts

@@ -0,0 +1,100 @@
+import type { OpenGeniClient } from "@opengeni/sdk";
+import {
+  getMyUsage,
+  type UsageAllowancePeriod,
+  type WorkspaceUsageResponse,
+} from "@opengeni/sdk/usage-allowances";
+import { useCallback, useContext, useEffect, useMemo, useRef } from "react";
+
+import { OpenGeniContext } from "../session-context";
+import { summarizeUsage, type UsageSummary } from "../usage/summary";
+import { usePolledValue } from "./internal";
+
+/**
+ * Anything that can read the signed-in member's own usage: the root SDK client
+ * pointed at your session proxy (`getMyUsage`), or any client exposing
+ * `requestJson` (for example the narrower browser client).
+ */
+export type UsageClientLike =
+  | Pick<OpenGeniClient, "getMyUsage">
+  | Pick<OpenGeniClient, "requestJson">;
+
+export type UseUsageOptions = {
+  /** Defaults to the `<OpenGeniProvider>` client. */
+  client?: UsageClientLike | undefined;
+  /** Defaults to the `<OpenGeniProvider>` workspace. */
+  workspaceId?: string | undefined;
+  /** `"current"` (default) or a `YYYY-MM` allowance period. */
+  period?: UsageAllowancePeriod | undefined;
+  /** Re-read on an interval. Off by default; usage changes only when work settles. */
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+  /**
+   * Re-read whenever this value changes, keeping the current reading while it
+   * loads. Pass something that changes when work settles (a turn count, the
+   * session status) so the meter follows real usage without polling.
+   */
+  refreshKey?: unknown;
+};
+
+export type UseUsageResult = {
+  /** The raw `/usage/me` response: the workspace pool and your own row. */
+  usage: WorkspaceUsageResponse | null;
+  /** What to tell this member; null until loaded. */
+  summary: UsageSummary | null;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+
+function readOwnUsage(
+  client: UsageClientLike,
+  workspaceId: string,
+  period: UsageAllowancePeriod | undefined,
+  signal: AbortSignal | undefined,
+): Promise<WorkspaceUsageResponse> {
+  const query = period === undefined ? {} : { period };
+  const options = signal ? { signal } : {};
+  if ("getMyUsage" in client && typeof client.getMyUsage === "function") {
+    return client.getMyUsage(workspaceId, query, options);
+  }
+  if ("requestJson" in client && typeof client.requestJson === "function") {
+    return getMyUsage(client, workspaceId, query, options);
+  }
+  throw new Error("@opengeni/react: the usage client needs getMyUsage or requestJson.");
+}
+
+/**
+ * The signed-in member's own usage in one workspace, read through `/usage/me`
+ * (the session proxy serves exactly this route). Never reads another member.
+ */
+export function useUsage(options: UseUsageOptions = {}): UseUsageResult {
+  const context = useContext(OpenGeniContext);
+  const client = (options.client ?? context?.client) as UsageClientLike | undefined;
+  const workspaceId = options.workspaceId ?? context?.workspaceId;
+  if (!client || !workspaceId) {
+    throw new Error(
+      "@opengeni/react: useUsage needs a client and workspace. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId }.",
+    );
+  }
+  const period = options.period;
+  const load = useCallback(
+    (signal?: AbortSignal) => readOwnUsage(client, workspaceId, period, signal),
+    [client, workspaceId, period],
+  );
+  const state = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  const refreshKey = options.refreshKey;
+  const seenKey = useRef(refreshKey);
+  const refresh = state.refresh;
+  useEffect(() => {
+    if (Object.is(seenKey.current, refreshKey)) return;
+    seenKey.current = refreshKey;
+    void refresh();
+  }, [refreshKey, refresh]);
+  const usage = state.data;
+  const summary = useMemo(() => (usage ? summarizeUsage(usage) : null), [usage]);
+  return { usage, summary, loading: state.loading, error: state.error, refresh };
+}

package/src/hooks/use-vaults.ts

@@ -0,0 +1,153 @@
+import { useCallback, useMemo } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import type {
+  ListVaultItemsQuery,
+  SessionSecretsView,
+  VaultFieldVersionMeta,
+  VaultItem,
+  VaultItemSummary,
+  VaultSummary,
+} from "@opengeni/sdk";
+import { asVaultClient, vaultsApi, type VaultsApi } from "@opengeni/sdk";
+import { usePolledValue } from "./internal";
+
+export type UseVaultQueryOptions = ClientOverride & {
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+};
+
+type QueryResult<T> = {
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+} & T;
+
+/**
+ * The workspace's vault REST surface for the current client. Mutations are
+ * plain promises: callers refresh the affected query afterwards. Plaintext
+ * (`revealField`) is returned to the caller only and never stored here.
+ */
+export function useVaultsApi(options: ClientOverride = {}): VaultsApi {
+  const { client, workspaceId } = useOpenGeni(options);
+  return useMemo(() => vaultsApi(asVaultClient(client), workspaceId), [client, workspaceId]);
+}
+
+/** Vaults the caller can see in this workspace (metadata only). */
+export function useVaults(
+  options: UseVaultQueryOptions = {},
+): QueryResult<{ vaults: VaultSummary[] | null; api: VaultsApi }> {
+  const api = useVaultsApi(options);
+  const load = useCallback((signal?: AbortSignal) => api.listVaults(signal), [api]);
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  return { vaults: data, loading, error, refresh, api };
+}
+
+/** One vault's metadata. */
+export function useVault(
+  vaultId: string,
+  options: UseVaultQueryOptions = {},
+): QueryResult<{ vault: VaultSummary | null; api: VaultsApi }> {
+  const api = useVaultsApi(options);
+  const load = useCallback((signal?: AbortSignal) => api.getVault(vaultId, signal), [api, vaultId]);
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  return { vault: data, loading, error, refresh, api };
+}
+
+/** The contract's maximum page size (`ListVaultItemsQuery.limit`). */
+export const VAULT_ITEM_PAGE_LIMIT = 200;
+
+/**
+ * A vault's items (metadata only). Follows cursors so a dense vault renders
+ * as one list; `q`/`type` filter server-side.
+ */
+export function useVaultItems(
+  vaultId: string,
+  query: ListVaultItemsQuery = {},
+  options: UseVaultQueryOptions = {},
+): QueryResult<{ items: VaultItemSummary[] | null; api: VaultsApi }> {
+  const api = useVaultsApi(options);
+  const { q, type, includeArchived } = query;
+  const load = useCallback(
+    async (signal?: AbortSignal) => {
+      const items: VaultItemSummary[] = [];
+      let cursor: string | undefined;
+      for (let page = 0; page < 40; page += 1) {
+        const result = await api.listItems(
+          vaultId,
+          { q, type, includeArchived, cursor, limit: VAULT_ITEM_PAGE_LIMIT },
+          signal,
+        );
+        items.push(...result.items);
+        if (!result.nextCursor) break;
+        cursor = result.nextCursor;
+      }
+      return items;
+    },
+    [api, vaultId, q, type, includeArchived],
+  );
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  return { items: data, loading, error, refresh, api };
+}
+
+/** One item with its fields' metadata (concealed values are never included). */
+export function useVaultItem(
+  vaultId: string,
+  itemId: string,
+  options: UseVaultQueryOptions = {},
+): QueryResult<{ item: VaultItem | null; api: VaultsApi }> {
+  const api = useVaultsApi(options);
+  const load = useCallback(
+    (signal?: AbortSignal) => api.getItem(vaultId, itemId, signal),
+    [api, vaultId, itemId],
+  );
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  return { item: data, loading, error, refresh, api };
+}
+
+/** A field's version history (metadata only). */
+export function useVaultFieldVersions(
+  vaultId: string,
+  itemId: string,
+  fieldId: string,
+  options: UseVaultQueryOptions = {},
+): QueryResult<{ versions: VaultFieldVersionMeta[] | null }> {
+  const api = useVaultsApi(options);
+  const load = useCallback(
+    (signal?: AbortSignal) => api.listFieldVersions(vaultId, itemId, fieldId, signal),
+    [api, vaultId, itemId, fieldId],
+  );
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  return { versions: data, loading, error, refresh };
+}
+
+/** A session's secrets view: policy, reachable vaults and its task vault. */
+export function useSessionSecrets(
+  sessionId: string | null | undefined,
+  options: UseVaultQueryOptions = {},
+): QueryResult<{ secrets: SessionSecretsView | null; api: VaultsApi }> {
+  const api = useVaultsApi(options);
+  const load = useCallback(
+    (signal?: AbortSignal) => api.getSessionSecrets(sessionId ?? "", signal),
+    [api, sessionId],
+  );
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: (options.enabled ?? true) && !!sessionId,
+  });
+  return { secrets: data, loading, error, refresh, api };
+}

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

@@ -15,7 +15,7 @@ export function useVideoArtifactPlaybackLoader(
   return useMemo(
     () => async (artifactId: string, signal?: AbortSignal) => {
       if (typeof client.createVideoArtifactPlaybackSource !== "function") {
-        throw new Error("This OpenGeni host does not expose retained-video playback.");
+        throw new Error("This Opengeni host does not expose retained-video playback.");
       }
       return await client.createVideoArtifactPlaybackSource(
         workspaceId,