@opengeni/react 1.0.1 → 1.0.2-canary.37202341988001

package/src/realtime/dropdown-menu.tsx

@@ -4,6 +4,15 @@ import { ChevronRightIcon } from "lucide-react";
 import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui";
 import { createContext, useContext, type ComponentProps, type Ref } from "react";
 import { cn } from "../lib/cn";
+import {
+  MENU_CHEVRON_CLASS,
+  MENU_ITEM_CLASS,
+  MENU_SEPARATOR_CLASS,
+  MENU_SURFACE_CLASS,
+} from "../lib/menu-styles";
+
+const MENU_MOTION_CLASS =
+  "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95";
 import { usePortalTokenSource, usePortalTokenStyle } from "../lib/use-portal-token-style";
 
 type DropdownMenuSourceContextValue = {
@@ -58,7 +67,9 @@ function DropdownMenuContent({
         data-slot="dropdown-menu-content"
         sideOffset={sideOffset}
         className={cn(
-          "og-root z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+          "og-root z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto",
+          MENU_SURFACE_CLASS,
+          MENU_MOTION_CLASS,
           className,
         )}
         style={{ ...portalStyle, ...style }}
@@ -82,10 +93,7 @@ function DropdownMenuItem({
       data-slot="dropdown-menu-item"
       data-inset={inset}
       data-variant={variant}
-      className={cn(
-        "relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-og-menu outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-muted-foreground data-[variant=destructive]:*:[svg]:text-destructive!",
-        className,
-      )}
+      className={cn(MENU_ITEM_CLASS, "data-[inset]:pl-9", className)}
       {...props}
     />
   );
@@ -98,7 +106,7 @@ function DropdownMenuSeparator({
   return (
     <DropdownMenuPrimitive.Separator
       data-slot="dropdown-menu-separator"
-      className={cn("-mx-1 my-1 h-px bg-border", className)}
+      className={cn(MENU_SEPARATOR_CLASS, className)}
       {...props}
     />
   );
@@ -118,14 +126,11 @@ function DropdownMenuSubTrigger({
     <DropdownMenuPrimitive.SubTrigger
       data-slot="dropdown-menu-sub-trigger"
       data-inset={inset}
-      className={cn(
-        "flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-og-menu outline-hidden select-none focus:bg-accent focus:text-accent-foreground data-[inset]:pl-8 data-[state=open]:bg-accent data-[state=open]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-muted-foreground",
-        className,
-      )}
+      className={cn(MENU_ITEM_CLASS, "data-[inset]:pl-9", className)}
       {...props}
     >
       {children}
-      <ChevronRightIcon className="ml-auto size-4" />
+      <ChevronRightIcon aria-hidden="true" className={cn(MENU_CHEVRON_CLASS, "ml-auto")} />
     </DropdownMenuPrimitive.SubTrigger>
   );
 }
@@ -141,7 +146,9 @@ function DropdownMenuSubContent({
     <DropdownMenuPrimitive.SubContent
       data-slot="dropdown-menu-sub-content"
       className={cn(
-        "og-root z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-lg data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+        "og-root z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden",
+        MENU_SURFACE_CLASS,
+        MENU_MOTION_CLASS,
         className,
       )}
       style={{ ...portalStyle, ...style }}

package/src/realtime/realtime-control.tsx

@@ -6,6 +6,7 @@ import {
   type SessionRealtimeController,
   type SessionRealtimeControllerSnapshot,
   type CreateSessionRealtimeControllerOptions,
+  type SessionRealtimeLifecycleProjection,
   type SessionRealtimeModel,
   type WorkspaceRealtimeModelCatalogItem,
 } from "@opengeni/sdk/realtime";
@@ -53,6 +54,7 @@ import {
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "./dropdown-menu";
+import { MENU_CHECK_CLASS } from "../lib/menu-styles";
 
 export type RealtimeModelOption = {
   id: SessionRealtimeModel;
@@ -104,7 +106,12 @@ const REALTIME_MODEL_CATALOG_CACHE_MAX_WORKSPACES = 64;
 type RealtimeControllerClient = EmbeddedRealtimeSessionClientLike & SessionRealtimeClientLike;
 
 type RealtimeModelCatalogCacheEntry =
-  | { state: "loading"; promise: Promise<RealtimeModelOption[]> }
+  | {
+      state: "loading";
+      promise: Promise<RealtimeModelOption[]>;
+      controller: AbortController;
+      consumers: number;
+    }
   | { state: "ready"; models: RealtimeModelOption[]; expiresAt: number };
 
 // Scope advisory availability to the exact client object and workspace. The
@@ -165,19 +172,26 @@ function pruneRealtimeModelCatalogCache(
 function loadRealtimeModelCatalog(
   client: RealtimeControllerClient,
   workspaceId: string,
+  signal?: AbortSignal,
 ): Promise<RealtimeModelOption[]> | null {
   const load = client.getWorkspaceRealtimeModelCatalog;
   if (!load) return null;
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason ?? new DOMException("Request aborted", "AbortError"));
+  }
   const now = Date.now();
   const cache = realtimeModelCatalogCacheFor(client);
   const entry = cache.get(workspaceId);
-  if (entry?.state === "loading") return entry.promise;
+  if (entry?.state === "loading" && !entry.controller.signal.aborted) {
+    return consumeRealtimeModelCatalog(entry, signal);
+  }
   if (entry?.state === "ready" && entry.expiresAt > now) return Promise.resolve(entry.models);
   if (entry) cache.delete(workspaceId);
   pruneRealtimeModelCatalogCache(cache, now);
 
+  const controller = new AbortController();
   const promise = load
-    .call(client, workspaceId)
+    .call(client, workspaceId, { signal: controller.signal })
     .then((response) => response.models.map(toRealtimeModelOption))
     .then((models) => {
       const current = cache.get(workspaceId);
@@ -196,8 +210,43 @@ function loadRealtimeModelCatalog(
       if (current?.state === "loading" && current.promise === promise) cache.delete(workspaceId);
       throw error;
     });
-  cache.set(workspaceId, { state: "loading", promise });
-  return promise;
+  const loading: RealtimeModelCatalogCacheEntry & { state: "loading" } = {
+    state: "loading",
+    promise,
+    controller,
+    consumers: 0,
+  };
+  cache.set(workspaceId, loading);
+  return consumeRealtimeModelCatalog(loading, signal);
+}
+
+function consumeRealtimeModelCatalog(
+  entry: RealtimeModelCatalogCacheEntry & { state: "loading" },
+  signal?: AbortSignal,
+): Promise<RealtimeModelOption[]> {
+  entry.consumers += 1;
+  return new Promise((resolve, reject) => {
+    let released = false;
+    const release = (abandoned: boolean) => {
+      if (released) return;
+      released = true;
+      entry.consumers = Math.max(0, entry.consumers - 1);
+      if (abandoned && entry.consumers === 0) {
+        entry.controller.abort(
+          signal?.reason ?? new DOMException("Request abandoned", "AbortError"),
+        );
+      }
+    };
+    const onAbort = () => {
+      release(true);
+      reject(signal?.reason ?? new DOMException("Request aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    void entry.promise.then(resolve, reject).finally(() => {
+      signal?.removeEventListener("abort", onAbort);
+      release(false);
+    });
+  });
 }
 
 export type SessionRealtimeControllerFactory = (
@@ -280,7 +329,7 @@ export function useSessionRealtime(options: {
   const eventsReadyRef = useRef(options.eventsReady);
   lifecycleRef.current = lifecycle;
   eventsReadyRef.current = options.eventsReady;
-  const lifecycleActive = lifecycle?.state === "active";
+  const lifecycleActive = sessionRealtimeLifecycleIsActive(lifecycle);
 
   useEffect(() => {
     let disposed = false;
@@ -401,6 +450,14 @@ export function useSessionRealtime(options: {
   };
 }
 
+function sessionRealtimeLifecycleIsActive(
+  lifecycle: SessionRealtimeLifecycleProjection | null,
+): boolean {
+  if (lifecycle?.state !== "active") return false;
+  const leaseExpiresAt = Date.parse(lifecycle.leaseExpiresAt);
+  return !Number.isFinite(leaseExpiresAt) || leaseExpiresAt > Date.now();
+}
+
 export function SessionRealtimeControl(props: {
   client?: RealtimeControllerClient | undefined;
   workspaceId?: string | undefined;
@@ -423,15 +480,18 @@ export function SessionRealtimeControl(props: {
    * `none` never attaches a model menu to the bar button.
    */
   modelMenu?: "split" | "split-desktop" | "none" | undefined;
+  /** Explicitly expose low-level controller diagnostics; disabled by default. */
+  showDiagnostics?: boolean | undefined;
   /** Deterministic browser-test/demo seam. Production hosts should use the SDK default. */
   controllerFactory?: SessionRealtimeControllerFactory | undefined;
 }) {
   const lifecycle = useMemo(() => projectSessionRealtimeLifecycle(props.events), [props.events]);
+  const lifecycleActive = sessionRealtimeLifecycleIsActive(lifecycle);
   const selection = useRealtimeModelSelection({
     client: props.client,
     workspaceId: props.workspaceId,
     codexConnected: props.codexConnected,
-    activeModel: lifecycle?.state === "active" ? lifecycle.model : null,
+    activeModel: lifecycleActive && lifecycle?.state === "active" ? lifecycle.model : null,
   });
   const selectedModel = selection.selectedModel;
   const realtime = useSessionRealtime({
@@ -455,7 +515,7 @@ export function SessionRealtimeControl(props: {
 
   useEffect(() => {
     const pending = autostartModelRef.current;
-    if (!pending || autostartStartedRef.current || lifecycle?.state === "active") return;
+    if (!pending || autostartStartedRef.current || lifecycleActive) return;
     const available = models.some((model) => model.id === pending && model.available);
     if (!available) return;
     if (selectedRealtimeModel.id !== pending) {
@@ -474,7 +534,7 @@ export function SessionRealtimeControl(props: {
       });
   }, [
     canStart,
-    lifecycle?.state,
+    lifecycleActive,
     models,
     props.sessionId,
     props.workspaceId,
@@ -492,6 +552,7 @@ export function SessionRealtimeControl(props: {
       modelAvailable={selectedModel.available}
       menuSide="top"
       modelMenu={props.modelMenu ?? "split"}
+      showDiagnostics={props.showDiagnostics}
       audioRef={realtime.audioRef}
       selectedModel={selectedModel}
       models={selection.models}
@@ -537,6 +598,7 @@ export function useRealtimeModelSelection(options: {
 
   useEffect(() => {
     let disposed = false;
+    const requestAbort = new AbortController();
     const applyCatalog = (models: RealtimeModelOption[]) => {
       catalogScopeRef.current = { client, workspaceId, source: "cache" };
       setCatalog(models);
@@ -557,7 +619,7 @@ export function useRealtimeModelSelection(options: {
       }
       return;
     }
-    const loading = loadRealtimeModelCatalog(client, workspaceId);
+    const loading = loadRealtimeModelCatalog(client, workspaceId, requestAbort.signal);
     if (!loading) return;
     void loading
       .then((models) => {
@@ -567,6 +629,7 @@ export function useRealtimeModelSelection(options: {
       .catch(() => undefined);
     return () => {
       disposed = true;
+      requestAbort.abort();
     };
   }, [client, workspaceId]);
 
@@ -609,7 +672,7 @@ const IDLE_REALTIME_SNAPSHOT: SessionRealtimeControllerSnapshot = {
   error: null,
 };
 
-export function NewSessionRealtimeControl(props: {
+type NewSessionRealtimeControlProps = {
   client?: RealtimeControllerClient | undefined;
   workspaceId?: string | undefined;
   codexConnected: boolean;
@@ -627,20 +690,43 @@ export function NewSessionRealtimeControl(props: {
    * `none` never attaches a model menu to the bar button.
    */
   modelMenu?: "split" | "split-desktop" | "none" | undefined;
-}) {
-  const internalSelection = useRealtimeModelSelection({
+};
+
+type NewSessionRealtimeSelection = {
+  models: readonly RealtimeModelOption[];
+  selectedModel: RealtimeModelOption;
+  selectModel: (modelId: string) => void;
+};
+
+export function NewSessionRealtimeControl(props: NewSessionRealtimeControlProps) {
+  if (props.models && props.selectedModel && props.onSelectModel) {
+    return (
+      <NewSessionRealtimeControlView
+        {...props}
+        selection={{
+          models: props.models,
+          selectedModel: props.selectedModel,
+          selectModel: props.onSelectModel,
+        }}
+      />
+    );
+  }
+  return <NewSessionRealtimeControlWithInternalSelection {...props} />;
+}
+
+function NewSessionRealtimeControlWithInternalSelection(props: NewSessionRealtimeControlProps) {
+  const selection = useRealtimeModelSelection({
     client: props.client,
     workspaceId: props.workspaceId,
     codexConnected: props.codexConnected,
   });
-  const selection =
-    props.models && props.selectedModel && props.onSelectModel
-      ? {
-          models: props.models,
-          selectedModel: props.selectedModel,
-          selectModel: props.onSelectModel,
-        }
-      : internalSelection;
+  return <NewSessionRealtimeControlView {...props} selection={selection} />;
+}
+
+function NewSessionRealtimeControlView(
+  props: NewSessionRealtimeControlProps & { selection: NewSessionRealtimeSelection },
+) {
+  const selection = props.selection;
   const audioRef = useRef<HTMLAudioElement>(null);
   const [starting, setStarting] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -709,7 +795,7 @@ export function RealtimeVoiceControl(props: {
    * `none` = start button only.
    */
   modelMenu?: "split" | "split-desktop" | "none" | undefined;
-  showDiagnostics?: boolean;
+  showDiagnostics?: boolean | undefined;
   /** Extra classes on the in-bar mute cluster (e.g. `max-sm:hidden` when mutes live in “+”). */
   muteControlsClassName?: string | undefined;
   audioRef: RefObject<HTMLAudioElement | null>;
@@ -763,7 +849,7 @@ export function RealtimeVoiceControl(props: {
       : modeOwned
         ? props.onStop
         : props.onStart;
-  const diagnosticsVisible = props.showDiagnostics ?? import.meta.env.DEV;
+  const diagnosticsVisible = props.showDiagnostics ?? false;
   const modelMenu = props.modelMenu ?? "split";
   const showAttachedModelMenu = modelMenu === "split" || modelMenu === "split-desktop";
   const desktopOnlyModelMenu = modelMenu === "split-desktop";
@@ -920,7 +1006,7 @@ export function RealtimeVoiceControl(props: {
               align="end"
               sideOffset={8}
               collisionPadding={12}
-              className="og-realtime-menu flex w-72 max-h-[min(20rem,var(--radix-dropdown-menu-content-available-height))] flex-col overflow-hidden rounded-xl border-border bg-surface p-1.5 shadow-xl"
+              className="og-realtime-menu flex w-72 max-h-[min(20rem,var(--radix-dropdown-menu-content-available-height))] flex-col overflow-hidden"
               onCloseAutoFocus={(event) => event.preventDefault()}
             >
               <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain">
@@ -943,9 +1029,15 @@ export function RealtimeVoiceControl(props: {
                 />
               </div>
 
-              {status.phase !== "idle" ? (
+              {status.phase !== "idle" &&
+              // Say it once: the selected model's row already carries its reason.
+              !(
+                status.phase === "unavailable" &&
+                pickerProvider === selectedModel.provider &&
+                selectedModel.unavailableReason === status.detail
+              ) ? (
                 <>
-                  <DropdownMenuSeparator className="mx-1 bg-og-border" />
+                  <DropdownMenuSeparator />
                   <div className="px-2.5 py-2" role="status" aria-live="polite">
                     <div className="flex items-center gap-2 text-og-sm font-medium text-og-fg">
                       <RealtimeStatusDot
@@ -961,7 +1053,6 @@ export function RealtimeVoiceControl(props: {
 
               {audioBlocked ? (
                 <DropdownMenuItem
-                  className="rounded-og-md"
                   onSelect={() => void props.onRetryAudibleOutput().catch(() => undefined)}
                 >
                   <Volume2Icon />
@@ -969,10 +1060,7 @@ export function RealtimeVoiceControl(props: {
                 </DropdownMenuItem>
               ) : null}
               {retryConnection ? (
-                <DropdownMenuItem
-                  className="rounded-og-md"
-                  onSelect={() => void props.onRetry().catch(() => undefined)}
-                >
+                <DropdownMenuItem onSelect={() => void props.onRetry().catch(() => undefined)}>
                   <RotateCcwIcon />
                   Retry connection
                 </DropdownMenuItem>
@@ -980,7 +1068,6 @@ export function RealtimeVoiceControl(props: {
               {modeOwned && props.snapshot.status !== "lost_owner" ? (
                 <DropdownMenuItem
                   variant="destructive"
-                  className="rounded-og-md"
                   disabled={props.snapshot.status === "stopping"}
                   onSelect={() => void props.onStop().catch(() => undefined)}
                 >
@@ -1020,16 +1107,14 @@ export function RealtimeVoiceModelPanel(props: {
 
   return (
     <div className="flex min-h-0 flex-1 flex-col" data-testid="realtime-voice-model-panel">
-      <div className="flex shrink-0 items-start gap-1 px-2 pt-1 pb-1.5">
+      <div className="flex min-h-10 shrink-0 items-center gap-2 border-b border-og-border px-2 pb-2">
         {props.leading}
-        <div className="min-w-0">
-          <div className="text-og-menu font-medium text-og-fg">Voice model</div>
-          <p className="mt-0.5 text-og-control text-og-fg-subtle">
-            Used when you start a voice conversation.
-          </p>
-        </div>
+        <div className="min-w-0 flex-1 text-og-menu font-medium text-og-fg">Voice model</div>
       </div>
-      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain px-1.5 pb-1.5">
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain p-2">
+        <p className="mb-3 text-og-control text-og-fg-muted">
+          Used when you start a voice conversation.
+        </p>
         <RealtimeModelPickerMenu
           models={props.models}
           selectedModel={props.selectedModel}
@@ -1143,7 +1228,9 @@ export function RealtimeModelPickerMenu(props: {
                 title={model.unavailableReason ?? model.description}
                 active={selected}
                 showChevron={false}
-                trailing={selected ? <CheckIcon className="size-3.5" aria-hidden /> : undefined}
+                trailing={
+                  selected ? <CheckIcon className={MENU_CHECK_CLASS} aria-hidden /> : undefined
+                }
                 testId={`realtime-model-choice-${model.id}`}
                 onClick={() => props.onSelect(model.id)}
               />
@@ -1206,12 +1293,12 @@ function RealtimeDiagnosticsMenu({ snapshot }: { snapshot: SessionRealtimeContro
 
   return (
     <>
-      <DropdownMenuSeparator className="mx-1 bg-og-border" />
+      <DropdownMenuSeparator />
       <DropdownMenuSub>
-        <DropdownMenuSubTrigger className="rounded-og-md text-og-fg-muted">
+        <DropdownMenuSubTrigger className="text-og-fg-muted">
           Realtime diagnostics
         </DropdownMenuSubTrigger>
-        <DropdownMenuSubContent className="max-h-80 w-72 overflow-y-auto rounded-og-lg border-og-border bg-og-surface-1 p-1.5 text-og-fg shadow-og-lg">
+        <DropdownMenuSubContent className="max-h-80 w-72 overflow-y-auto">
           {rows.map(([label, value]) => (
             <DropdownMenuItem
               key={label}
@@ -1443,7 +1530,7 @@ function RealtimeStatusDot(props: { phase: RealtimeVisualPhase; reduceMotion: bo
 
 function voiceButtonTone(phase: RealtimeVisualPhase): string {
   if (phase === "listening" || phase === "speaking") {
-    return "border border-og-accent/45 bg-og-accent text-og-accent-fg shadow-og-sm hover:bg-og-accent-strong";
+    return "border border-og-primary-border bg-og-primary text-og-primary-fg hover:bg-og-primary-hover";
   }
   if (phase === "blocked" || phase === "error") {
     return "border border-og-status-waiting/35 bg-og-status-waiting/10 text-og-status-waiting hover:bg-og-status-waiting/15";
@@ -1457,7 +1544,7 @@ function voiceButtonTone(phase: RealtimeVisualPhase): string {
 
 function voiceChevronTone(phase: RealtimeVisualPhase): string {
   if (phase === "listening" || phase === "speaking") {
-    return "border border-l-0 border-og-accent/45 bg-og-accent text-og-accent-fg hover:bg-og-accent-strong";
+    return "border border-l-0 border-og-primary-border bg-og-primary text-og-primary-fg hover:bg-og-primary-hover";
   }
   if (phase === "blocked" || phase === "error") {
     return "border border-l-0 border-og-status-waiting/35 bg-og-status-waiting/10 text-og-status-waiting hover:bg-og-status-waiting/15";

package/src/session-auth-recommendation.ts

@@ -0,0 +1,48 @@
+import type { AuthNeededItem } from "./timeline/types";
+import type { CapabilityCatalogItem } from "@opengeni/sdk";
+
+/** Recovery events identify runtime servers/connections, while recommendation
+ * events already carry a catalog id. Never guess among same-domain accounts. */
+export function sessionAuthRecommendation(
+  item: AuthNeededItem,
+  catalog: CapabilityCatalogItem[],
+): AuthNeededItem | undefined {
+  if (
+    item.authoritySource === "host" ||
+    item.reason === "unsupported_auth" ||
+    item.reason === "resource_scope_unavailable"
+  )
+    return undefined;
+  if (item.capability) return item;
+  const recoveryServerId = item.canonicalServerId ?? item.serverId;
+  const matches = catalog.filter(
+    (candidate) =>
+      (recoveryServerId !== null &&
+        candidate.runtime.mcpServerId === recoveryServerId &&
+        recoveryServerId !== "opengeni") ||
+      (item.connectionId !== null && candidate.connectionRef?.connectionId === item.connectionId),
+  );
+  if (matches.length !== 1) return undefined;
+  const entry = matches[0]!;
+  const personalAccess = item.reason === "personal_authority_unavailable";
+  if (
+    personalAccess &&
+    ((item.connectionSubjectScope ?? entry.connectionRef?.subjectScope) !== "subject" ||
+      entry.connectionRef?.authoritySource === "host")
+  )
+    return undefined;
+  return {
+    ...item,
+    capability: {
+      id: entry.id,
+      name: entry.name,
+      kind: entry.kind,
+      source: entry.source,
+      action: "connect",
+      rationale: personalAccess
+        ? "Review permission to use your personal account in this conversation."
+        : "Reconnect this integration to use its tools in this conversation.",
+      requiredVariables: [],
+    },
+  };
+}

package/src/session-capability-policy.ts

@@ -0,0 +1,83 @@
+import type { FirstPartyMcpToolName, CapabilityCatalogItem } from "@opengeni/sdk";
+import type { OpenGeniBrowserClient as OpenGeniClient } from "@opengeni/sdk/browser";
+
+/** Catalog tool discovery may be lazy; selecting the installed server does not
+ * require its individual tool inventory to have been fetched. */
+export function sessionCapabilityTools(item: CapabilityCatalogItem) {
+  const serverId = item.kind === "mcp" ? item.runtime?.mcpServerId : undefined;
+  return serverId && !item.tools.some((tool) => tool.kind === "mcp" && tool.id === serverId)
+    ? [...item.tools, { kind: "mcp" as const, id: serverId }]
+    : item.tools;
+}
+
+/** A connection never resets the human's existing tool selection. Default-mode
+ * sessions discover newly enabled servers at admission; explicit/inherited
+ * policies add only this reviewed capability, with the existing CAS fence. */
+export async function attachSessionCapability(
+  client: OpenGeniClient,
+  workspaceId: string,
+  sessionId: string,
+  item: CapabilityCatalogItem,
+  stillCurrent: () => boolean = () => true,
+): Promise<void> {
+  const tools = sessionCapabilityTools(item);
+  if (item.kind === "skill" || tools.length === 0) return;
+  if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+  const session = await client.getSession(workspaceId, sessionId);
+  if (!stillCurrent()) throw new Error("Connection setup was interrupted.");
+  // Session.tools includes mandatory runtime servers, which must never be
+  // echoed into the human's explicit selection.
+  let existing = session.tools.filter(
+    (tool) => !session.effectiveToolPolicy?.mandatoryIds?.includes(tool.id),
+  );
+  if (session.toolPolicy.mode === "workspace_default") {
+    const policy = session.effectiveToolPolicy;
+    if (!policy || policy.idsTruncated)
+      throw new Error(
+        "Connected, but the full session tool selection could not be read. Review the Tools picker before continuing.",
+      );
+    // A workspace may choose a restricted default instead of all enabled servers.
+    // Preserve that exact selection if this connection needs an explicit addition.
+    // selectedIds contains only explicit additions, and is normally empty for
+    // automatic selection. Compare against the resolved defaults instead.
+    existing = policy.effectiveIds
+      .filter((id) => !policy.mandatoryIds.includes(id))
+      .map((id) => ({ kind: "mcp" as const, id }));
+  }
+  const additions = tools.filter(
+    (tool) => !existing.some((current) => current.kind === tool.kind && current.id === tool.id),
+  );
+  const recommended = Array.isArray(item.metadata?.firstPartyMcpTools)
+    ? (item.metadata.firstPartyMcpTools.filter(
+        (name): name is string => typeof name === "string",
+      ) as FirstPartyMcpToolName[])
+    : [];
+  const firstParty = [...new Set([...session.firstPartyMcpTools, ...recommended])];
+  if (additions.length === 0 && firstParty.length === session.firstPartyMcpTools.length) return;
+  await client.updateSessionToolPolicy(workspaceId, sessionId, {
+    mode: "explicit",
+    tools: [...existing, ...additions],
+    firstPartyMcpTools: firstParty,
+    expectedVersion: session.toolPolicyVersion,
+  });
+}
+
+/** Native OAuth callbacks have already saved the provider connection. Finish
+ * the separate, version-fenced session tool selection before reporting success. */
+export async function completeSessionCapabilityOAuth(
+  client: OpenGeniClient,
+  workspaceId: string,
+  sessionId: string,
+  capabilityId: string | null,
+): Promise<void> {
+  if (!capabilityId)
+    throw new Error(
+      "The authorized integration could not be identified. Review its connection card to finish setup.",
+    );
+  const connected = (await client.listCapabilities(workspaceId)).items.find(
+    (item) => item.id === capabilityId,
+  );
+  if (!connected?.enabled)
+    throw new Error("The connection was authorized, but enabling its tools could not be verified.");
+  await attachSessionCapability(client, workspaceId, sessionId, connected);
+}

package/src/session-context.ts

@@ -129,7 +129,7 @@ function useEmbeddedClientRefinement<TClient extends object>(
   const workspaceId = override.workspaceId ?? context?.workspaceId;
   if (!candidate || !workspaceId) {
     throw new Error(
-      "@opengeni/react: no OpenGeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
+      "@opengeni/react: no Opengeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
     );
   }
   const methods = candidate as Record<string, unknown>;
@@ -164,7 +164,7 @@ export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue
   const workspaceId = override.workspaceId ?? context?.workspaceId;
   if (!client || !workspaceId) {
     throw new Error(
-      "@opengeni/react: no OpenGeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
+      "@opengeni/react: no Opengeni client/workspace available. Wrap the tree in <OpenGeniProvider> or pass { client, workspaceId } to the hook.",
     );
   }
   return {
@@ -316,6 +316,7 @@ export function useEmbeddedSession(
       "streamEvents",
       "getComposerDraft",
       "saveComposerDraft",
+      "submitComposerDraft",
       "sendMessage",
       "steerMessage",
       "getQueue",
@@ -422,7 +423,7 @@ export function useOpenGeniClient(
   const client = override.client ?? context?.client;
   if (!client) {
     throw new Error(
-      "@opengeni/react: no OpenGeni client available. Wrap the tree in <OpenGeniProvider> or pass { client } to the hook.",
+      "@opengeni/react: no Opengeni client available. Wrap the tree in <OpenGeniProvider> or pass { client } to the hook.",
     );
   }
   return client;