@opengeni/react 7.6.1 → 7.7.0-canary.37090756480001

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

@@ -8,7 +8,10 @@ import type {
   ComputerTarget,
 } from "@opengeni/sdk/interaction";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { isNonRetryableInteractionError } from "../lib/interaction-errors";
+import {
+  isInteractionControlUnavailable,
+  isNonRetryableInteractionError,
+} from "../lib/interaction-errors";
 import {
   type EmbeddedComputerInteractionClientOverride,
   useEmbeddedComputerInteraction,
@@ -29,6 +32,8 @@ export type UseComputerSessionResult = {
   loading: boolean;
   mutating: boolean;
   error: Error | null;
+  /** Control service loss, independent of target accessibility inspection and media. */
+  controlError: Error | null;
   refresh: () => Promise<void>;
   readClipboard: () => Promise<ComputerClipboard>;
   /** Changes only this viewer's target cursor; it never takes ownership or
@@ -105,6 +110,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
     requestRef.current.controller?.abort();
     const controller = new AbortController();
     requestRef.current = { id, controller };
+    let discoveryCompleted = false;
     try {
       const [session, targetResponse] = await Promise.all([
         client.getComputerSession(workspaceId, computerSessionId, {
@@ -114,6 +120,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
           signal: controller.signal,
         }),
       ]);
+      discoveryCompleted = true;
       if (!mountedRef.current || requestRef.current.id !== id) return;
       const targets = sortComputerTargets(targetResponse.targets);
       const selected = chooseTarget(targets, selectedTargetIdRef.current, session.platform);
@@ -141,6 +148,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
               observation: retainedObservation,
               loading: false,
               error: null,
+              controlError: null,
             }
           : current,
       );
@@ -168,12 +176,19 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
       );
     } catch (cause) {
       if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id) return;
+      const error = cause instanceof Error ? cause : new Error(String(cause));
       setState((current) =>
         current.computerSessionId === computerSessionId
           ? {
               ...current,
               loading: false,
-              error: cause instanceof Error ? cause : new Error(String(cause)),
+              error,
+              controlError: isInteractionControlUnavailable(
+                error,
+                discoveryCompleted ? "observation" : "control",
+              )
+                ? error
+                : current.controlError,
             }
           : current,
       );
@@ -239,11 +254,23 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
           : current,
       );
       try {
-        return await operation();
+        const result = await operation();
+        setState((current) =>
+          current.computerSessionId === scopeComputerSessionId
+            ? { ...current, controlError: null }
+            : current,
+        );
+        return result;
       } catch (cause) {
         const error = cause instanceof Error ? cause : new Error(String(cause));
         setState((current) =>
-          current.computerSessionId === scopeComputerSessionId ? { ...current, error } : current,
+          current.computerSessionId === scopeComputerSessionId
+            ? {
+                ...current,
+                error,
+                controlError: isInteractionControlUnavailable(error) ? error : current.controlError,
+              }
+            : current,
         );
         throw error;
       } finally {
@@ -298,7 +325,14 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
         const error = cause instanceof Error ? cause : new Error(String(cause));
         setState((current) =>
           current.computerSessionId === computerSessionId && current.selectedTargetId === target.id
-            ? { ...current, loading: false, error }
+            ? {
+                ...current,
+                loading: false,
+                error,
+                controlError: isInteractionControlUnavailable(error, "observation")
+                  ? error
+                  : current.controlError,
+              }
             : current,
         );
         throw error;
@@ -405,7 +439,21 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
 
   const readClipboard = useCallback(async (): Promise<ComputerClipboard> => {
     if (!computerSessionId) throw new Error("No desktop is selected.");
-    return await client.readComputerClipboard(workspaceId, computerSessionId);
+    try {
+      return await client.readComputerClipboard(workspaceId, computerSessionId);
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      setState((current) =>
+        current.computerSessionId === computerSessionId
+          ? {
+              ...current,
+              error,
+              controlError: isInteractionControlUnavailable(error) ? error : current.controlError,
+            }
+          : current,
+      );
+      throw error;
+    }
   }, [client, computerSessionId, workspaceId]);
 
   return {
@@ -417,6 +465,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
     loading: visible.loading,
     mutating: visible.mutating,
     error: visible.error,
+    controlError: visible.controlError,
     refresh,
     readClipboard,
     selectTarget,
@@ -434,6 +483,7 @@ type ComputerControlState = {
   loading: boolean;
   mutating: boolean;
   error: Error | null;
+  controlError: Error | null;
 };
 
 function emptyState(computerSessionId: string | null, loading: boolean): ComputerControlState {
@@ -446,6 +496,7 @@ function emptyState(computerSessionId: string | null, loading: boolean): Compute
     loading,
     mutating: false,
     error: null,
+    controlError: null,
   };
 }
 

package/src/hooks/use-file-attachments.ts

@@ -4,6 +4,7 @@ import {
   useEmbeddedFileAttachments,
   type EmbeddedFileAttachmentClientOverride,
 } from "../session-context";
+import { useErrorMessage } from "../lib/error-message";
 
 export type UseFileAttachmentsOptions = EmbeddedFileAttachmentClientOverride & {
   /**
@@ -31,6 +32,8 @@ export type FileAttachment = {
   /** Stable SDK failure code for UI behavior that must not parse error copy. */
   errorCode?: "secure_context_required" | undefined;
   error?: string | undefined;
+  /** Original diagnostic failure; presentation copy is kept separately in `error`. */
+  errorCause?: unknown;
 };
 
 export type UseFileAttachmentsResult = {
@@ -120,6 +123,7 @@ export function useFileAttachments(
   options: UseFileAttachmentsOptions = {},
 ): UseFileAttachmentsResult {
   const { client, workspaceId } = useEmbeddedFileAttachments(options);
+  const formatError = useErrorMessage();
   const pasteFilter = options.pasteFilter ?? isImage;
   const [attachments, setAttachments] = useState<FileAttachment[]>([]);
   const attachmentsRef = useRef(attachments);
@@ -234,6 +238,7 @@ export function useFileAttachments(
                     sizeBytes: asset.sizeBytes,
                     errorCode: undefined,
                     error: undefined,
+                    errorCause: undefined,
                   }
                 : attachment,
             ),
@@ -248,14 +253,15 @@ export function useFileAttachments(
                     ...attachment,
                     status: "failed",
                     errorCode: secureContextRequiredErrorCode(error),
-                    error: error instanceof Error ? error.message : String(error),
+                    error: formatError(error),
+                    errorCause: error,
                   }
                 : attachment,
             ),
           );
         });
     },
-    [client, workspaceId, options.scope],
+    [client, workspaceId, options.scope, formatError],
   );
 
   const addFiles = useCallback(
@@ -291,7 +297,13 @@ export function useFileAttachments(
       setAttachments((current) =>
         current.map((attachment) =>
           attachment.id === id
-            ? { ...attachment, status: "uploading", errorCode: undefined, error: undefined }
+            ? {
+                ...attachment,
+                status: "uploading",
+                errorCode: undefined,
+                error: undefined,
+                errorCause: undefined,
+              }
             : attachment,
         ),
       );
@@ -343,6 +355,7 @@ export function useFileAttachments(
                 file,
                 errorCode: undefined,
                 error: undefined,
+                errorCause: undefined,
               }
             : {
                 id: `restored:${file.id}`,

package/src/hooks/use-goal.ts

@@ -1,6 +1,7 @@
 import { OpenGeniApiError, type SessionEvent, type SessionGoal } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useEmbeddedGoal, type EmbeddedGoalClientOverride } from "../session-context";
+import { normalizeError } from "../lib/error-message";
 import {
   useDebouncedCallback,
   useMutationRunner,
@@ -117,7 +118,7 @@ export function useGoal(
         setGoal(null);
         setError(null);
       } else {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        setError(normalizeError(cause));
       }
       setLoading(false);
     } finally {

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

@@ -9,6 +9,7 @@ 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 { normalizeError } from "../lib/error-message";
 import { usePageLiveActivity } from "./internal";
 
 // "on-demand" is the boxless-benign resting state: the lease is not currently
@@ -289,7 +290,7 @@ export function useSessionCapabilities(
                 return;
               }
               setState("error");
-              setError(cause instanceof Error ? cause : new Error(String(cause)));
+              setError(normalizeError(cause));
             }
           });
       }, warmingPollMs);
@@ -469,7 +470,7 @@ export function useSessionCapabilities(
           return;
         }
         setState("error");
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
+        setError(normalizeError(cause));
       }
     })();
 

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

@@ -10,6 +10,7 @@ import { createOlderHistoryLoadReceipt, type OlderHistoryLoadReceipt } from "../
 import { buildTimeline, groupTimeline, sessionStatusFromEvents } from "../timeline/projection";
 import type { TimelineItem } from "../timeline/types";
 import type { EmbeddedSessionClientLike } from "../client";
+import { normalizeError } from "../lib/error-message";
 import { usePageLiveActivity } from "./internal";
 import type { LatestQuestionOptions } from "./latest-question";
 
@@ -114,8 +115,11 @@ const FOREGROUND_COMPACT_CATCHUP_MAX_GROUPS = 16;
 const FOREGROUND_COMPACT_CATCHUP_MAX_BYTES = 512 * 1024;
 const EMPTY_EVENTS: SessionEvent[] = [];
 const encoder = new TextEncoder();
-export const SESSION_EVENT_BROWSER_MAX_BYTES = 160 * 1024 * 1024;
-export const SESSION_EVENT_BROWSER_MAX_COUNT = 200_000;
+// Durable history remains on the server and is available through bounded
+// navigation. Keep the live browser working set small across multiple tabs;
+// serialized payloads also expand into objects and timeline projections.
+export const SESSION_EVENT_BROWSER_MAX_BYTES = 16 * 1024 * 1024;
+export const SESSION_EVENT_BROWSER_MAX_COUNT = 20_000;
 export const SESSION_EVENT_BROWSER_PENDING_MAX_BYTES = 1024 * 1024;
 export const SESSION_EVENT_BROWSER_PENDING_MAX_COUNT = 256;
 
@@ -495,7 +499,7 @@ export function useSessionEvents(
               .then(() => reconcileSession(sessionId))
               .catch((cause) => {
                 if (isCurrent()) {
-                  setError(cause instanceof Error ? cause : new Error(String(cause)));
+                  setError(normalizeError(cause));
                 }
               });
           },
@@ -536,7 +540,7 @@ export function useSessionEvents(
       } catch (cause) {
         if (isCurrent()) {
           flush();
-          setError(cause instanceof Error ? cause : new Error(String(cause)));
+          setError(normalizeError(cause));
           setConnectionState("error");
           // A failed first compact-tail request has no later success path in
           // this effect instance. End the loading gate so hosts can render the
@@ -878,7 +882,7 @@ export function useSessionEvents(
       if (!isCurrent()) {
         return false;
       }
-      setNewerError(reason instanceof Error ? reason : new Error(String(reason)));
+      setNewerError(normalizeError(reason));
       // Keep authorization and integrity failures actionable for callers;
       // timeline-owned invocations attach their own explicit recovery UI.
       throw reason;
@@ -1078,10 +1082,13 @@ export function useSessionEvents(
       visibleEvents.some((event) => event.sequence === questionEvidence.anchor)
         ? questionEvidence.events
         : EMPTY_EVENTS;
+    const timelineOptions = { partialStart: hasOlder || eventWindow.truncated || after > 0 };
+    if (witness.length === 0) return buildTimeline(visibleEvents, timelineOptions);
     const ids = new Set(visibleEvents.map((event) => event.id));
-    return buildTimeline([...visibleEvents, ...witness.filter((event) => !ids.has(event.id))], {
-      partialStart: hasOlder || eventWindow.truncated || after > 0,
-    });
+    return buildTimeline(
+      [...visibleEvents, ...witness.filter((event) => !ids.has(event.id))],
+      timelineOptions,
+    );
   }, [visibleEvents, hasOlder, eventWindow.truncated, after, questionEvidence, client, streamKey]);
 
   return {

package/src/hooks/use-slash-commands.ts

@@ -1,5 +1,6 @@
 import type { KeyboardEvent } from "react";
 import { useCallback, useMemo, useRef, useState } from "react";
+import { useErrorMessage } from "../lib/error-message";
 import {
   argHint,
   filterCommands,
@@ -81,6 +82,7 @@ export type UseSlashCommandsResult = {
 };
 
 export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashCommandsResult {
+  const formatError = useErrorMessage();
   const { commands, context, handlers, value, setValue } = options;
   const [highlight, setHighlight] = useState(0);
   // Escape closes the palette but keeps the draft. We remember the dismissed
@@ -153,9 +155,9 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
       if (!context) {
         return null;
       }
-      return { ...context, ...handlers, confirm: () => handlers.confirm(command) };
+      return { ...context, ...handlers, formatError, confirm: () => handlers.confirm(command) };
     },
-    [context, handlers],
+    [context, handlers, formatError],
   );
 
   const execute = useCallback(
@@ -173,10 +175,10 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
           setValue("");
         }
       } catch (cause) {
-        ctx.notice({ tone: "error", message: errorMessage(cause) });
+        ctx.notice({ tone: "error", message: formatError(cause) });
       }
     },
-    [buildContext, setValue],
+    [buildContext, setValue, formatError],
   );
 
   const autocomplete = useCallback(
@@ -359,10 +361,3 @@ export function useSlashCommands(options: UseSlashCommandsOptions): UseSlashComm
     autocompleteHighlighted,
   };
 }
-
-function errorMessage(cause: unknown): string {
-  if (cause instanceof Error) {
-    return cause.message;
-  }
-  return String(cause);
-}

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-workspace-sessions.ts

@@ -1,15 +1,19 @@
-import type { Session } from "@opengeni/sdk";
+import type { Session, SessionListEntry } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { usePolledValue } from "./internal";
 
 export type UseWorkspaceSessionsOptions = ClientOverride & {
+  /** Compact list records; detail reads remain full sessions. */
+  projection?: "summary" | undefined;
   limit?: number | undefined;
   parentSessionId?: string | null | undefined;
   cursor?: string | undefined;
   search?: string | undefined;
   /** Return only the complete personal pinned projection. */
   pinsOnly?: boolean | undefined;
+  /** Skip pinned details when the pinned section is loaded separately. */
+  includePinned?: boolean | undefined;
   archivedOnly?: boolean | undefined;
   sortBy?: "updatedAt" | "createdAt" | "name" | undefined;
   archiveStatus?: "active" | "archived" | "all" | undefined;
@@ -20,14 +24,14 @@ export type UseWorkspaceSessionsOptions = ClientOverride & {
   beginRead?: (() => number) | undefined;
 };
 
-export type UseWorkspaceSessionsResult = {
+export type UseWorkspaceSessionsResult<T extends Session | SessionListEntry = Session> = {
   /**
    * All visible rows, with pins first. This preserves the pre-pinning hook
    * contract for consumers that only read `sessions`.
    */
-  sessions: Session[];
+  sessions: T[];
   /** The complete personal pinned section, also present in `sessions`. */
-  pinned: Session[];
+  pinned: T[];
   /** True when the server omitted older pins from its bounded pinned section. */
   pinnedTruncated: boolean;
   nextCursor: string | null;
@@ -41,15 +45,26 @@ export type UseWorkspaceSessionsResult = {
 };
 
 /** List the workspace's sessions — the data behind fleet and manager views. */
+export function useWorkspaceSessions(
+  options: UseWorkspaceSessionsOptions & { projection: "summary" },
+): UseWorkspaceSessionsResult<SessionListEntry>;
+export function useWorkspaceSessions(
+  options?: UseWorkspaceSessionsOptions & { projection?: undefined },
+): UseWorkspaceSessionsResult;
+export function useWorkspaceSessions(
+  options: UseWorkspaceSessionsOptions,
+): UseWorkspaceSessionsResult<Session | SessionListEntry>;
 export function useWorkspaceSessions(
   options: UseWorkspaceSessionsOptions = {},
-): UseWorkspaceSessionsResult {
+): UseWorkspaceSessionsResult<Session | SessionListEntry> {
   const { client, workspaceId } = useOpenGeni(options);
+  const projection = options.projection;
   const limit = options.limit;
   const parentSessionId = options.parentSessionId;
   const cursor = options.cursor;
   const search = options.search;
   const pinsOnly = options.pinsOnly;
+  const includePinned = options.includePinned;
   const archivedOnly = options.archivedOnly;
   const sortBy = options.sortBy;
   const archiveStatus = options.archiveStatus;
@@ -59,11 +74,13 @@ export function useWorkspaceSessions(
   const beginRead = options.beginRead;
   const queryKey = [
     workspaceId,
+    projection ?? "full",
     limit ?? "",
     parentSessionId === null ? "null" : (parentSessionId ?? ""),
     cursor ?? "",
     search ?? "",
     pinsOnly ? "1" : "",
+    includePinned === false ? "no-pins" : "",
     archivedOnly ? "archived" : "active",
     sortBy ?? "",
     archiveStatus ?? "",
@@ -76,17 +93,31 @@ export function useWorkspaceSessions(
   const load = useCallback(
     async (signal?: AbortSignal) => {
       const readGeneration = beginRead?.() ?? ++nextReadGeneration.current;
-      const page = await client.listSessionPage(workspaceId, {
+      const query = {
         ...(limit !== undefined ? { limit } : {}),
         ...(parentSessionId !== undefined ? { parentSessionId } : {}),
         ...(cursor !== undefined ? { cursor } : {}),
         ...(search !== undefined ? { search } : {}),
         ...(pinsOnly ? { pinsOnly: true } : {}),
+        ...(includePinned === false ? { includePinned: false } : {}),
         ...(archivedOnly ? { archivedOnly: true } : {}),
         ...(sortBy ? { sortBy } : {}),
         ...(archiveStatus ? { archiveStatus } : {}),
         signal,
-      });
+      };
+      const page =
+        projection === "summary"
+          ? client.listSessionSummaryPage
+            ? await client.listSessionSummaryPage(workspaceId, query)
+            : await client.listSessionPage(workspaceId, query).then(async (full) => {
+                const { sessionListEntry } = await import("@opengeni/sdk/session-list-entries");
+                return {
+                  ...full,
+                  pinned: full.pinned.map(sessionListEntry),
+                  sessions: full.sessions.map(sessionListEntry),
+                };
+              })
+          : await client.listSessionPage(workspaceId, query);
       return {
         queryKey,
         page,
@@ -98,11 +129,13 @@ export function useWorkspaceSessions(
       beginRead,
       client,
       workspaceId,
+      projection,
       limit,
       parentSessionId,
       cursor,
       search,
       pinsOnly,
+      includePinned,
       archivedOnly,
       sortBy,
       archiveStatus,

package/src/index.ts

@@ -43,7 +43,7 @@ export type {
   SessionClientLike,
 } from "./client";
 export { OpenGeniProvider } from "./provider";
-export type { OpenGeniProviderProps } from "./provider";
+export type { OpenGeniProviderProps, ErrorMessageFormatter } from "./provider";
 export { useOpenGeni, useOpenGeniClient } from "./session-context";
 export { useVideoArtifactPlaybackLoader } from "./hooks/use-video-artifact-playback";
 export type { ClientOverride, OpenGeniContextValue } from "./session-context";
@@ -130,7 +130,12 @@ export type {
   VoiceRecordingTranscriptionState,
   VoiceRecordingUploadState,
 } from "./voice-recording-store";
-export { COMPOSER_PAYMENT_REQUIRED_MESSAGE, composerSubmissionErrorMessage } from "./lib/format";
+export {
+  COMPOSER_MODEL_UNAVAILABLE_MESSAGE,
+  COMPOSER_PAYMENT_REQUIRED_MESSAGE,
+  composerSubmissionErrorMessage,
+  isModelUnavailableSubmissionError,
+} from "./lib/format";
 export {
   INITIAL_TRANSCRIPTION_CONTROL_STATE,
   appendFinalTranscript,

package/src/interaction.ts

@@ -58,6 +58,7 @@ export type {
 } from "./hooks/use-browser-identities";
 export { useBrowserSession } from "./hooks/use-browser-session";
 export type {
+  BrowserInputFailure,
   UseBrowserSessionOptions,
   UseBrowserSessionResult,
 } from "./hooks/use-browser-session";

package/src/lib/error-message.ts

@@ -0,0 +1,37 @@
+import { formatErrorMessage } from "@opengeni/sdk";
+import { createContext, useCallback, useContext, useRef } from "react";
+
+/** Original diagnostic error and the library's neutral, state-aware display copy. */
+export type ErrorMessageFormatter = (error: unknown, defaultMessage: string) => string | undefined;
+
+export const ErrorMessageContext = createContext<ErrorMessageFormatter | undefined>(undefined);
+
+const originalCauses = new WeakMap<Error, unknown>();
+
+/** Keep existing Error-typed state while retaining non-Error rejections privately. */
+export function normalizeError(cause: unknown): Error {
+  if (cause instanceof Error) return cause;
+  const error = new Error(String(cause));
+  originalCauses.set(error, cause);
+  return error;
+}
+
+/** Presentation only: callers retain their errors and delivery/retry state. */
+export function useErrorMessage(): (error: unknown, defaultMessage?: string) => string {
+  const formatter = useContext(ErrorMessageContext);
+  const formatterRef = useRef(formatter);
+  formatterRef.current = formatter;
+  return useCallback((error, fallback) => {
+    const original =
+      error instanceof Error && originalCauses.has(error) ? originalCauses.get(error) : error;
+    const defaultMessage = fallback ?? formatErrorMessage(original);
+    try {
+      const message = formatterRef.current?.(original, defaultMessage);
+      return typeof message === "string" && message ? message : defaultMessage;
+    } catch {
+      // Host presentation must never interrupt delivery-state settlement or
+      // cause an already-started mutation to be retried.
+      return defaultMessage;
+    }
+  }, []);
+}