@opengeni/react 3.1.0 → 3.1.2

package/src/hooks/use-realtime-voice-models.ts

@@ -0,0 +1,46 @@
+import { useEffect, useState } from "react";
+import type { RealtimeControllerClient, RealtimeModelOption } from "../realtime/session-realtime";
+
+/**
+ * Voice models this user can start in the workspace, or an empty list while
+ * disabled, unsupported or unknown. Shares the stock voice control's catalog
+ * cache, without eagerly loading voice code for a text-only embed.
+ */
+export function useRealtimeVoiceModels(
+  client: unknown,
+  workspaceId: string,
+  enabled: boolean,
+): RealtimeModelOption[] {
+  const [snapshot, setSnapshot] = useState<{
+    client: unknown;
+    workspaceId: string;
+    models: RealtimeModelOption[];
+  } | null>(null);
+  useEffect(() => {
+    if (!enabled || !workspaceId) return;
+    const controller = new AbortController();
+    void import("../realtime/session-realtime")
+      .then(async ({ loadRealtimeModelCatalog }) => {
+        const models = await loadRealtimeModelCatalog(
+          client as RealtimeControllerClient,
+          workspaceId,
+          controller.signal,
+        );
+        if (!controller.signal.aborted) {
+          setSnapshot({
+            client,
+            workspaceId,
+            models: models?.filter((model) => model.available) ?? [],
+          });
+        }
+      })
+      .catch(() => undefined);
+    return () => controller.abort();
+  }, [client, workspaceId, enabled]);
+  return enabled &&
+    snapshot !== null &&
+    snapshot.client === client &&
+    snapshot.workspaceId === workspaceId
+    ? snapshot.models
+    : [];
+}

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

@@ -1,4 +1,5 @@
 import type {
+  FileSystemRouteIdentity,
   FsChangedPayload,
   FsReadResponse,
   FsTreeNode,
@@ -84,6 +85,9 @@ export type UseSandboxFilesOptions = ClientOverride & {
   events?: SessionEvent[] | undefined;
   /** Initial path to list (workspace root by default). */
   rootPath?: string | undefined;
+  /** Exact capability identity for the selected filesystem route. A route/root
+   * change resets this hook and makes stale provider requests fail retryably. */
+  route?: FileSystemRouteIdentity | undefined;
   /** Hold off the initial list (e.g. panel collapsed). Default true. */
   enabled?: boolean | undefined;
   /** Pause live reads/invalidation while preserving the last rendered result. */
@@ -169,8 +173,12 @@ function normalizeRoot(root: string): string {
   return normalized === "." ? "" : normalized;
 }
 
+function isAbsoluteTreePath(path: string): boolean {
+  return path.startsWith("/") || /^[A-Za-z]:\//u.test(path);
+}
+
 function joinTreeRoot(root: string, path: string): string {
-  if (!root || path.startsWith("/")) return path;
+  if (!root || isAbsoluteTreePath(path)) return path;
   return root === "/" ? `/${path}` : `${root}/${path}`;
 }
 
@@ -301,6 +309,7 @@ const FS_LIST_BATCH_REQUEST_LIMIT = 16;
 function initialDirectoryFrontier(rootPath: string, repoPaths: readonly string[]): string[] {
   const root = normalizeRoot(rootPath);
   const rootParts = root.split("/").filter(Boolean);
+  const rootPrefix = root.startsWith("//") ? "//" : root.startsWith("/") ? "/" : "";
   const paths = new Set<string>();
   for (const repoPath of repoPaths) {
     const canonicalRepoPath = joinTreeRoot(root, normalizeRoot(repoPath));
@@ -308,7 +317,7 @@ function initialDirectoryFrontier(rootPath: string, repoPaths: readonly string[]
     if (rootParts.some((part, index) => parts[index] !== part)) continue;
     for (let depth = rootParts.length + 1; depth <= parts.length; depth += 1) {
       const path = parts.slice(0, depth).join("/");
-      paths.add(root.startsWith("/") ? `/${path}` : path);
+      paths.add(`${rootPrefix}${path}`);
     }
   }
   // A workspace with hundreds of repositories should remain lazy. This still
@@ -491,6 +500,15 @@ export function useSandboxFiles(
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const active = options.active ?? true;
   const rootPath = options.rootPath ?? "";
+  const routeEpoch = options.route?.epoch ?? null;
+  const routeRoot = options.route?.root ?? null;
+  const route = useMemo<FileSystemRouteIdentity | undefined>(
+    () =>
+      routeEpoch !== null && routeRoot !== null
+        ? { epoch: routeEpoch, root: routeRoot }
+        : undefined,
+    [routeEpoch, routeRoot],
+  );
   const repoPathsKey = [
     ...new Set((options.repoPaths?.length ? options.repoPaths : [rootPath]).map(normalizeRoot)),
   ].join("\u0000");
@@ -503,7 +521,7 @@ export function useSandboxFiles(
   const acceptsEventReadsRef = useRef(acceptsEventReads);
   acceptsEventReadsRef.current = acceptsEventReads;
   const hasLiveIoFence = options.liveness !== undefined;
-  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${rootPath}\u0000${repoPathsKey}`;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${rootPath}\u0000${repoPathsKey}\u0000${routeEpoch ?? ""}\u0000${routeRoot ?? ""}`;
 
   const [tree, setTree] = useState<FileTreeNode[]>([]);
   // A ref mirror of the current tree — lets the optimistic path snapshot the
@@ -597,6 +615,7 @@ export function useSandboxFiles(
       const listRequests = [rootPath, ...frontierPaths].map((path) => ({
         path,
         depth: 1,
+        ...(route ? { route } : {}),
       }));
       // Root plus the bounded repository frontier share one API request, one
       // direct holder, and one provider attach. The old per-directory fan-out
@@ -677,7 +696,7 @@ export function useSandboxFiles(
       if (refreshGenerationRef.current === generation) setGitLoading(false);
       if (refreshAbortRef.current === refreshAbort) refreshAbortRef.current = null;
     }
-  }, [client, workspaceId, sessionId, rootPath, repoPaths, applyStatus]);
+  }, [client, workspaceId, sessionId, rootPath, repoPaths, route, applyStatus]);
 
   // Seed (or re-seed) the tree from a turn-end capture — the COLD/offline paint,
   // zero Channel-A calls. The tree index is workspace-relative (`treeIndex`); the
@@ -737,7 +756,7 @@ export function useSandboxFiles(
         const listed = await client.fsList(
           workspaceId,
           sessionId,
-          { path, depth: 1 },
+          { path, depth: 1, ...(route ? { route } : {}) },
           { signal: identitySignal },
         );
         if (identityGenerationRef.current !== identityGeneration) return;
@@ -757,7 +776,7 @@ export function useSandboxFiles(
         }
       }
     },
-    [client, workspaceId, sessionId, capture, source, applyStatus],
+    [client, workspaceId, sessionId, capture, source, route, applyStatus],
   );
 
   const readFile = useCallback(
@@ -850,9 +869,14 @@ export function useSandboxFiles(
         }
         throw new Error("Captured file download failed after refreshing its URL.");
       }
-      return await client.fsRead(workspaceId, sessionId, { path }, { signal });
+      return await client.fsRead(
+        workspaceId,
+        sessionId,
+        { path, ...(route ? { route } : {}) },
+        { signal },
+      );
     },
-    [client, workspaceId, sessionId, capture, source],
+    [client, workspaceId, sessionId, capture, source, route],
   );
 
   // TARGETED reconcile of a single directory — re-list ONE parent at depth 1 and
@@ -874,7 +898,12 @@ export function useSandboxFiles(
       // visible to update; they re-list fresh on the next expand).
       if (!parentIsLoaded(treeRef.current, path, rootPath)) return;
       try {
-        const listed = await client.fsList(workspaceId, sessionId, { path, depth: 1 }, { signal });
+        const listed = await client.fsList(
+          workspaceId,
+          sessionId,
+          { path, depth: 1, ...(route ? { route } : {}) },
+          { signal },
+        );
         if (identityGenerationRef.current !== identityGeneration) return;
         const children = (listed.root.children ?? []).map((node) => fsNodeToTree(node));
         if (path === normalizeRoot(rootPath)) {
@@ -892,7 +921,7 @@ export function useSandboxFiles(
         // root-refresh here (that would collapse the tree the user is working in).
       }
     },
-    [client, workspaceId, sessionId, rootPath, applyStatus],
+    [client, workspaceId, sessionId, rootPath, route, applyStatus],
   );
 
   // Reconcile the visible directory frontier through bounded batch requests.
@@ -915,7 +944,13 @@ export function useSandboxFiles(
           const listed = await client.fsListBatch(
             workspaceId,
             sessionId,
-            { requests: chunk.map((path) => ({ path, depth: 1 })) },
+            {
+              requests: chunk.map((path) => ({
+                path,
+                depth: 1,
+                ...(route ? { route } : {}),
+              })),
+            },
             { signal },
           );
           if (identityGenerationRef.current !== identityGeneration) return;
@@ -943,7 +978,7 @@ export function useSandboxFiles(
         }
       }
     },
-    [client, workspaceId, sessionId, rootPath, applyStatus],
+    [client, workspaceId, sessionId, rootPath, route, applyStatus],
   );
 
   // Run a Channel-A op behind an OPTIMISTIC tree edit. `apply` splices the change
@@ -1027,7 +1062,7 @@ export function useSandboxFiles(
             const live = await client.fsRead(
               workspaceId,
               sessionId,
-              { path },
+              { path, ...(route ? { route } : {}) },
               { signal: identitySignal },
             );
             if (identityGenerationRef.current !== identityGeneration) {
@@ -1046,12 +1081,13 @@ export function useSandboxFiles(
             path,
             content,
             overwrite: true,
+            ...(route ? { route } : {}),
           });
         },
         exists ? [] : [parent],
       );
     },
-    [client, workspaceId, sessionId, tree, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, tree, rootPath, route, runOptimistic],
   );
 
   const createFile = useCallback(
@@ -1072,11 +1108,12 @@ export function useSandboxFiles(
             path,
             content: "",
             overwrite: false,
+            ...(route ? { route } : {}),
           }),
         [parent],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const createDir = useCallback(
@@ -1094,11 +1131,16 @@ export function useSandboxFiles(
       await runOptimistic(
         "create folder",
         (nodes) => insertNode(nodes, parent, node, rootPath),
-        () => client.fsMkdir(workspaceId, sessionId, { path, recursive: true }),
+        () =>
+          client.fsMkdir(workspaceId, sessionId, {
+            path,
+            recursive: true,
+            ...(route ? { route } : {}),
+          }),
         [parent],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const deleteEntry = useCallback(
@@ -1107,11 +1149,16 @@ export function useSandboxFiles(
       await runOptimistic(
         "delete",
         (nodes) => removeNode(nodes, path, rootPath),
-        () => client.fsDelete(workspaceId, sessionId, { path, recursive }),
+        () =>
+          client.fsDelete(workspaceId, sessionId, {
+            path,
+            recursive,
+            ...(route ? { route } : {}),
+          }),
         [parentWithinTree(path, rootPath)],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   const moveEntry = useCallback(
@@ -1133,11 +1180,12 @@ export function useSandboxFiles(
             path,
             newPath,
             overwrite: opts?.overwrite ?? false,
+            ...(route ? { route } : {}),
           }),
         to === from ? [from] : [from, to],
       );
     },
-    [client, workspaceId, sessionId, rootPath, runOptimistic],
+    [client, workspaceId, sessionId, rootPath, route, runOptimistic],
   );
 
   // Initial paint + reset on identity change. Source selection:

package/src/hooks/use-session-background-commands.ts

@@ -1,5 +1,5 @@
 import type { SessionBackgroundCommand } from "@opengeni/sdk";
-import { useCallback } from "react";
+import { useCallback, useEffect, useRef } from "react";
 
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { usePolledValue } from "./internal";
@@ -23,28 +23,39 @@ export function useSessionBackgroundCommands(
 ): UseSessionBackgroundCommandsResult {
   const { client, workspaceId } = useOpenGeni(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
-  const load = useCallback(async () => {
-    if (!sessionId) return { commands: [] };
-    if (!client.listSessionBackgroundCommands) {
-      throw new Error("The configured OpenGeni client does not support background commands");
-    }
-    return await client.listSessionBackgroundCommands(workspaceId, sessionId);
-  }, [client, workspaceId, sessionId]);
+  const load = useCallback(
+    async (signal?: AbortSignal) => {
+      if (!sessionId) return { commands: [] };
+      if (!client.listSessionBackgroundCommands) {
+        throw new Error("The configured Opengeni client does not support background commands");
+      }
+      return await client.listSessionBackgroundCommands(workspaceId, sessionId, { signal });
+    },
+    [client, workspaceId, sessionId],
+  );
   const state = usePolledValue(load, {
     enabled,
     pollIntervalMs: options.pollIntervalMs,
   });
   const refresh = state.refresh;
+  const generation = useRef(0);
+  useEffect(() => {
+    generation.current += 1;
+    return () => {
+      generation.current += 1;
+    };
+  }, [client, workspaceId, sessionId, enabled]);
   const cancel = useCallback(
     async (commandId: string): Promise<void> => {
       if (!sessionId) return;
       if (!client.cancelSessionBackgroundCommand) {
-        throw new Error("The configured OpenGeni client does not support background commands");
+        throw new Error("The configured Opengeni client does not support background commands");
       }
+      const ticket = generation.current;
       await client.cancelSessionBackgroundCommand(workspaceId, sessionId, commandId);
-      await refresh();
+      if (enabled && ticket === generation.current) await refresh();
     },
-    [client, workspaceId, sessionId, refresh],
+    [client, workspaceId, sessionId, refresh, enabled],
   );
   return {
     commands: state.data?.commands ?? [],

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-conversation.ts

@@ -0,0 +1,150 @@
+import type { SendMessageInput } from "@opengeni/sdk";
+import { useLayoutEffect, useMemo, useRef } from "react";
+import { projectPendingApprovals } from "../approvals";
+import { conversationTimeline } from "../conversation-timeline";
+import { useOpenGeni, type ClientOverride } from "../session-context";
+import { useWorkspaceModelCatalog } from "./use-available-models";
+import { useClientConfigFlags } from "./use-client-config-flags";
+import { useComposer, type UseComposerOptions } from "./use-composer";
+import { useFileAttachments } from "./use-file-attachments";
+import { useHumanInputRequests } from "./use-human-input";
+import { useSession } from "./use-session";
+import { useSessionControl } from "./use-session-control";
+import { useSessionEvents } from "./use-session-events";
+import { useTurnQueue } from "./use-turn-queue";
+
+export type UseSessionConversationOptions = ClientOverride & {
+  /** Uploads remain subject to the client's capabilities. Defaults to true. */
+  attachments?: boolean | undefined;
+  /** Defaults to the client's model-selection offer. */
+  modelPicker?: boolean | undefined;
+  /**
+   * Optional host context and notifications. The stock composer still owns
+   * draft validation, annotations, retry identity, queueing and delivery.
+   * File cleanup and upload blocking are composed with, not replaced by, these hooks.
+   */
+  composerOptions?:
+    | Pick<
+        UseComposerOptions,
+        "sendExtras" | "sendBlocked" | "onSubmitted" | "onSent" | "onDeliveryError" | "initialDraft"
+      >
+    | undefined;
+};
+
+export type SessionConversationController = ReturnType<typeof useSessionConversation>;
+
+/**
+ * The complete conversation's state, independent of its layout. Mount once in
+ * a stable host and pass the result to SessionConversationView, or compose the
+ * stock timeline/chrome/composer around the same controller. Unmounting a view
+ * does not dispose the stream, draft or uploads while this hook stays mounted.
+ * The ordinary SessionConversation component uses this exact implementation.
+ */
+export function useSessionConversation(
+  sessionId: string,
+  options: UseSessionConversationOptions = {},
+) {
+  const context = useOpenGeni(options);
+  const scope = { client: context.client, workspaceId: context.workspaceId };
+  const config = useClientConfigFlags(context.client);
+  const showModelPicker = options.modelPicker ?? config.modelSelection;
+  const catalog = useWorkspaceModelCatalog({ ...scope, enabled: showModelPicker });
+  const feed = useSessionEvents(sessionId, scope);
+  const eventOptions = { ...scope, events: feed.events };
+  const detail = useSession(sessionId, eventOptions);
+  const queue = useTurnQueue(sessionId, eventOptions);
+  const human = useHumanInputRequests(sessionId, eventOptions);
+  const control = useSessionControl(sessionId, scope);
+  const approvals = useMemo(() => projectPendingApprovals(feed.events), [feed.events]);
+  const files = useFileAttachments(scope);
+  const clearFiles = files.clear;
+  const attachmentSession = useRef(sessionId);
+  useLayoutEffect(() => {
+    if (attachmentSession.current === sessionId) return;
+    attachmentSession.current = sessionId;
+    // Upload transport is workspace-scoped; these unsent cards belong to one
+    // conversation. Retiring them also makes late settlements no-ops because
+    // their local attachment identities no longer exist in the queue.
+    clearFiles();
+  }, [clearFiles, sessionId]);
+  const uploadsEnabled = (options.attachments ?? true) && config.uploads;
+  const status = feed.sessionStatus ?? detail.session?.status;
+  const terminal = status === "cancelled";
+  const importedArchive = detail.session?.importedArchive?.readOnly === true;
+  const host = options.composerOptions;
+  const resolveExtras = () =>
+    typeof host?.sendExtras === "function" ? host.sendExtras() : host?.sendExtras;
+  const releaseSentFiles = (input: SendMessageInput) =>
+    files.removeReadyFiles(
+      (input.resources ?? []).flatMap((resource) =>
+        resource.kind === "file" ? [resource.fileId] : [],
+      ),
+    );
+  const composer = useComposer(sessionId, {
+    ...eventOptions,
+    initialDraft: host?.initialDraft,
+    effectiveControl: queue.effectiveControl ?? detail.session?.effectiveControl,
+    sendDestination: () => (queue.queue.length > 0 || status === "running" ? "queue" : "chat"),
+    sendExtras: () => {
+      const extras = resolveExtras();
+      return {
+        ...extras,
+        resources: [...(extras?.resources ?? []), ...(uploadsEnabled ? files.readyResources : [])],
+      };
+    },
+    sendBlocked: () =>
+      terminal ||
+      importedArchive ||
+      (uploadsEnabled && files.hasUnresolved) ||
+      host?.sendBlocked?.() === true,
+    onSubmitted: (text, input) => {
+      releaseSentFiles(input);
+      return host?.onSubmitted?.(text, input);
+    },
+    onSent: (text, input) => {
+      releaseSentFiles(input);
+      return host?.onSent?.(text, input);
+    },
+    onDeliveryError: host?.onDeliveryError,
+  });
+  const timeline = useMemo(
+    () => conversationTimeline(feed.timeline, queue, composer),
+    [feed.timeline, queue, composer],
+  );
+  const error = detail.error ?? feed.error ?? human.error;
+  const loadFailed = Boolean(feed.error) && !feed.initialHistoryReady;
+  const retry = async () => {
+    await Promise.all([
+      ...(detail.error ? [detail.refresh()] : []),
+      ...(human.error ? [human.refresh()] : []),
+      ...(feed.error ? [feed.jumpToLatest()] : []),
+    ]);
+  };
+
+  return {
+    ...scope,
+    sessionId,
+    config,
+    catalog,
+    showModelPicker,
+    feed,
+    detail,
+    queue,
+    human,
+    control,
+    approvals,
+    files,
+    uploadsEnabled,
+    composer,
+    /** The same live application context for text and durable voice messages. */
+    getModelContext: () => resolveExtras()?.modelContext,
+    timeline,
+    status,
+    terminal,
+    importedArchive,
+    running: status === "running" || status === "recovering" || status === "waiting_capacity",
+    error,
+    loadFailed,
+    retry,
+  };
+}