@opengeni/react 0.52.1 → 1.0.1

package/src/model-policy.ts

@@ -1,6 +1,10 @@
 import type { ClientModel, ReasoningEffort, WorkspaceModelCatalogModel } from "@opengeni/sdk";
 
-export type PickerBillingClass = "opengeni_credits" | "codex_subscription" | "byok";
+export type PickerBillingClass =
+  | "opengeni_credits"
+  | "codex_subscription"
+  | "supergrok_subscription"
+  | "byok";
 
 export type PickerModelRow<TCatalog extends ClientModel = WorkspaceModelCatalogModel> = {
   id: string;
@@ -21,12 +25,14 @@ export type LatencyModeId = "standard" | "priority" | "fast";
 const BILLING_CLASS_ORDER: PickerBillingClass[] = [
   "opengeni_credits",
   "codex_subscription",
+  "supergrok_subscription",
   "byok",
 ];
 
 const BILLING_CLASS_LABELS: Record<PickerBillingClass, string> = {
   opengeni_credits: "OpenGeni",
   codex_subscription: "Codex",
+  supergrok_subscription: "SuperGrok",
   byok: "Your Gateway",
 };
 
@@ -41,6 +47,9 @@ const AVAILABILITY_REASON_LABELS: Record<string, string> = {
 };
 
 export function billingClassForModel(model: ClientModel): PickerBillingClass {
+  if (model.source === "supergrok") {
+    return "supergrok_subscription";
+  }
   if (model.source === "codex") {
     return "codex_subscription";
   }
@@ -48,7 +57,9 @@ export function billingClassForModel(model: ClientModel): PickerBillingClass {
     return "byok";
   }
   if (model.credentialSource?.kind === "connected_subscription") {
-    return "codex_subscription";
+    return model.credentialSource.provider === "xai"
+      ? "supergrok_subscription"
+      : "codex_subscription";
   }
   if (model.credentialSource?.kind === "workspace_connection") {
     return "byok";
@@ -135,7 +146,9 @@ export function payerSummaryForModel(model: ClientModel): string {
     return "OpenGeni credits · automatic managed route";
   }
   if (billing.upstreamPayer === "connected_subscription") {
-    return "Codex subscription · external billing";
+    return model.source === "supergrok"
+      ? "SuperGrok subscription · external billing"
+      : "Codex subscription · external billing";
   }
   if (billing.upstreamPayer === "workspace") {
     return "Billed to your AI Gateway";
@@ -149,7 +162,9 @@ export function advancedSourceSummary(model: ClientModel): string | null {
     return null;
   }
   if (source.kind === "connected_subscription") {
-    return "Connected Codex subscription";
+    return source.provider === "xai"
+      ? "Connected SuperGrok subscription"
+      : "Connected Codex subscription";
   }
   if (source.kind === "workspace_connection") {
     return "Workspace AI Gateway";

package/src/provider.tsx

@@ -3,6 +3,7 @@ import {
   OPENGENI_API_CONTRACT_REVISION,
   type StreamConnectionState,
   type WorkspaceControlEvent,
+  type WorkspaceInteractionRevisionEvent,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import type { SessionClientLike } from "./client";
@@ -17,6 +18,7 @@ export type OpenGeniProviderProps = {
   client: SessionClientLike;
   workspaceId: string;
   onWorkspaceControlEvent?: ((event: WorkspaceControlEvent) => void) | undefined;
+  onWorkspaceInteractionEvent?: ((event: WorkspaceInteractionRevisionEvent) => void) | undefined;
   children?: ReactNode;
 };
 
@@ -28,6 +30,7 @@ export function OpenGeniProvider({
   client,
   workspaceId,
   onWorkspaceControlEvent,
+  onWorkspaceInteractionEvent,
   children,
 }: OpenGeniProviderProps) {
   const [workspaceControlEvent, setWorkspaceControlEvent] = useState<WorkspaceControlEvent | null>(
@@ -36,15 +39,25 @@ export function OpenGeniProvider({
   const [workspaceControlConnectionState, setWorkspaceControlConnectionState] = useState<
     StreamConnectionState | "idle" | "error"
   >("idle");
+  const [workspaceInteractionEvent, setWorkspaceInteractionEvent] =
+    useState<WorkspaceInteractionRevisionEvent | null>(null);
+  const [workspaceInteractionConnectionState, setWorkspaceInteractionConnectionState] = useState<
+    StreamConnectionState | "idle" | "error"
+  >("idle");
   const [contractMismatch, setContractMismatch] = useState<OpenGeniApiContractMismatchError | null>(
     null,
   );
   const callbackRef = useRef(onWorkspaceControlEvent);
+  const interactionCallbackRef = useRef(onWorkspaceInteractionEvent);
   const reconcilersRef = useRef(new Map<string, Map<string, () => Promise<void>>>());
   const reconcileInFlightRef = useRef(new Map<string, Promise<void>>());
   const workspaceControlSequencesRef = useRef(new Map<string, number>());
+  const workspaceInteractionSequencesRef = useRef(new Map<string, number>());
   const pageLive = usePageLiveActivity();
+  const supportsWorkspaceLiveStream =
+    "streamWorkspaceLiveEvents" in client && typeof client.streamWorkspaceLiveEvents === "function";
   callbackRef.current = onWorkspaceControlEvent;
+  interactionCallbackRef.current = onWorkspaceInteractionEvent;
 
   const verifyApiContract = useCallback(async (): Promise<void> => {
     try {
@@ -105,6 +118,78 @@ export function OpenGeniProvider({
   );
 
   useEffect(() => {
+    if (!supportsWorkspaceLiveStream) return;
+    const openLiveStream = client.streamWorkspaceLiveEvents!;
+    setWorkspaceControlEvent(null);
+    setWorkspaceInteractionEvent(null);
+    if (!pageLive) {
+      setWorkspaceControlConnectionState("idle");
+      setWorkspaceInteractionConnectionState("idle");
+      return;
+    }
+    const controller = new AbortController();
+    const setConnectionState = (state: StreamConnectionState) => {
+      setWorkspaceControlConnectionState(state);
+      setWorkspaceInteractionConnectionState(state);
+    };
+    setConnectionState("connecting");
+    void (async () => {
+      try {
+        await verifyApiContract();
+        const workspace = await client.getWorkspace(workspaceId);
+        const controlAfter = Math.max(
+          workspaceControlSequencesRef.current.get(workspaceId) ?? 0,
+          workspace.inferenceControl.revision,
+        );
+        const interactionAfter = workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0;
+        workspaceControlSequencesRef.current.set(workspaceId, controlAfter);
+        const stream = openLiveStream.call(client, workspaceId, {
+          controlAfter,
+          interactionAfter,
+          signal: controller.signal,
+          onStateChange: setConnectionState,
+        });
+        for await (const event of stream) {
+          if (controller.signal.aborted) return;
+          if (event.type === "workspace.control.changed") {
+            workspaceControlSequencesRef.current.set(
+              workspaceId,
+              Math.max(workspaceControlSequencesRef.current.get(workspaceId) ?? 0, event.sequence),
+            );
+            setWorkspaceControlEvent((current) =>
+              !current || event.sequence > current.sequence ? event : current,
+            );
+            callbackRef.current?.(event);
+          } else {
+            workspaceInteractionSequencesRef.current.set(
+              workspaceId,
+              Math.max(
+                workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0,
+                event.sequence,
+              ),
+            );
+            setWorkspaceInteractionEvent((current) =>
+              !current || event.sequence > current.sequence ? event : current,
+            );
+            interactionCallbackRef.current?.(event);
+          }
+        }
+      } catch (error) {
+        if (error instanceof OpenGeniApiContractMismatchError) {
+          setContractMismatch(error);
+          reloadForContractMismatchOnce(error);
+        }
+        if (!controller.signal.aborted) {
+          setWorkspaceControlConnectionState("error");
+          setWorkspaceInteractionConnectionState("error");
+        }
+      }
+    })();
+    return () => controller.abort();
+  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
+
+  useEffect(() => {
+    if (supportsWorkspaceLiveStream) return;
     if (!pageLive) {
       setWorkspaceControlConnectionState("idle");
       return;
@@ -145,7 +230,50 @@ export function OpenGeniProvider({
       }
     })();
     return () => controller.abort();
-  }, [client, pageLive, verifyApiContract, workspaceId]);
+  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
+
+  useEffect(() => {
+    if (supportsWorkspaceLiveStream) return;
+    setWorkspaceInteractionEvent(null);
+    if (!pageLive) {
+      setWorkspaceInteractionConnectionState("idle");
+      return;
+    }
+    const controller = new AbortController();
+    setWorkspaceInteractionConnectionState("connecting");
+    void (async () => {
+      try {
+        await verifyApiContract();
+        const resumeAfter = workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0;
+        const stream = client.streamWorkspaceInteractionRevisions(workspaceId, {
+          after: resumeAfter,
+          signal: controller.signal,
+          onStateChange: setWorkspaceInteractionConnectionState,
+        });
+        for await (const event of stream) {
+          if (controller.signal.aborted) return;
+          workspaceInteractionSequencesRef.current.set(
+            workspaceId,
+            Math.max(
+              workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0,
+              event.sequence,
+            ),
+          );
+          setWorkspaceInteractionEvent((current) =>
+            !current || event.sequence > current.sequence ? event : current,
+          );
+          interactionCallbackRef.current?.(event);
+        }
+      } catch (error) {
+        if (error instanceof OpenGeniApiContractMismatchError) {
+          setContractMismatch(error);
+          reloadForContractMismatchOnce(error);
+        }
+        if (!controller.signal.aborted) setWorkspaceInteractionConnectionState("error");
+      }
+    })();
+    return () => controller.abort();
+  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
 
   const value = useMemo(
     () => ({
@@ -153,6 +281,8 @@ export function OpenGeniProvider({
       workspaceId,
       workspaceControlEvent,
       workspaceControlConnectionState,
+      workspaceInteractionEvent,
+      workspaceInteractionConnectionState,
       registerSessionReconciler,
       reconcileSession,
     }),
@@ -161,6 +291,8 @@ export function OpenGeniProvider({
       workspaceId,
       workspaceControlEvent,
       workspaceControlConnectionState,
+      workspaceInteractionEvent,
+      workspaceInteractionConnectionState,
       registerSessionReconciler,
       reconcileSession,
     ],

package/src/realtime/realtime-control.tsx

@@ -57,7 +57,7 @@ import {
 export type RealtimeModelOption = {
   id: SessionRealtimeModel;
   label: string;
-  provider: "OpenGeni" | "Connected Codex" | "Your Gateway";
+  provider: "OpenGeni" | "Connected Codex" | "Connected SuperGrok" | "Your Gateway";
   description: string;
   available: boolean;
   unavailableReason: string | null;
@@ -74,7 +74,12 @@ const CODEX_LIVE_MODEL: RealtimeModelOption = {
   recommended: false,
 };
 
-const REALTIME_MODEL_PROVIDERS = ["OpenGeni", "Connected Codex", "Your Gateway"] as const;
+const REALTIME_MODEL_PROVIDERS = [
+  "OpenGeni",
+  "Connected Codex",
+  "Connected SuperGrok",
+  "Your Gateway",
+] as const;
 type RealtimeModelProvider = (typeof REALTIME_MODEL_PROVIDERS)[number];
 
 const REALTIME_PROVIDER_META: Record<
@@ -86,12 +91,115 @@ const REALTIME_PROVIDER_META: Record<
     billingClass: "codex_subscription",
     hint: "ChatGPT / Codex plan",
   },
+  "Connected SuperGrok": {
+    billingClass: "supergrok_subscription",
+    hint: "SuperGrok / xAI plan",
+  },
   "Your Gateway": { billingClass: "byok", hint: "Billed to your AI Gateway" },
 };
 const REALTIME_MODEL_STORAGE_PREFIX = "opengeni:realtime-model";
+const REALTIME_MODEL_CATALOG_CACHE_TTL_MS = 60_000;
+const REALTIME_MODEL_CATALOG_CACHE_MAX_WORKSPACES = 64;
 
 type RealtimeControllerClient = EmbeddedRealtimeSessionClientLike & SessionRealtimeClientLike;
 
+type RealtimeModelCatalogCacheEntry =
+  | { state: "loading"; promise: Promise<RealtimeModelOption[]> }
+  | { state: "ready"; models: RealtimeModelOption[]; expiresAt: number };
+
+// Scope advisory availability to the exact client object and workspace. The
+// server still authorizes every realtime operation; changing principals should
+// replace the client just as it does for the rest of the SDK state.
+const realtimeModelCatalogCache = new WeakMap<
+  RealtimeControllerClient,
+  Map<string, RealtimeModelCatalogCacheEntry>
+>();
+
+function realtimeModelFallback(codexConnected: boolean): RealtimeModelOption[] {
+  return [
+    {
+      ...CODEX_LIVE_MODEL,
+      available: codexConnected,
+      unavailableReason: codexConnected ? null : CODEX_LIVE_MODEL.unavailableReason,
+    },
+  ];
+}
+
+function realtimeModelCatalogCacheFor(
+  client: RealtimeControllerClient,
+): Map<string, RealtimeModelCatalogCacheEntry> {
+  const existing = realtimeModelCatalogCache.get(client);
+  if (existing) return existing;
+  const created = new Map<string, RealtimeModelCatalogCacheEntry>();
+  realtimeModelCatalogCache.set(client, created);
+  return created;
+}
+
+function readCachedRealtimeModelCatalog(
+  client: RealtimeControllerClient,
+  workspaceId: string,
+  now = Date.now(),
+): RealtimeModelOption[] | null {
+  const cache = realtimeModelCatalogCache.get(client);
+  const entry = cache?.get(workspaceId);
+  if (!entry || entry.state === "loading") return null;
+  if (entry.expiresAt > now) return entry.models;
+  cache?.delete(workspaceId);
+  return null;
+}
+
+function pruneRealtimeModelCatalogCache(
+  cache: Map<string, RealtimeModelCatalogCacheEntry>,
+  now: number,
+): void {
+  for (const [workspaceId, entry] of cache) {
+    if (entry.state === "ready" && entry.expiresAt <= now) cache.delete(workspaceId);
+  }
+  while (cache.size >= REALTIME_MODEL_CATALOG_CACHE_MAX_WORKSPACES) {
+    const oldestWorkspaceId = cache.keys().next().value;
+    if (oldestWorkspaceId === undefined) return;
+    cache.delete(oldestWorkspaceId);
+  }
+}
+
+function loadRealtimeModelCatalog(
+  client: RealtimeControllerClient,
+  workspaceId: string,
+): Promise<RealtimeModelOption[]> | null {
+  const load = client.getWorkspaceRealtimeModelCatalog;
+  if (!load) return null;
+  const now = Date.now();
+  const cache = realtimeModelCatalogCacheFor(client);
+  const entry = cache.get(workspaceId);
+  if (entry?.state === "loading") return entry.promise;
+  if (entry?.state === "ready" && entry.expiresAt > now) return Promise.resolve(entry.models);
+  if (entry) cache.delete(workspaceId);
+  pruneRealtimeModelCatalogCache(cache, now);
+
+  const promise = load
+    .call(client, workspaceId)
+    .then((response) => response.models.map(toRealtimeModelOption))
+    .then((models) => {
+      const current = cache.get(workspaceId);
+      if (current?.state === "loading" && current.promise === promise) {
+        cache.delete(workspaceId);
+        cache.set(workspaceId, {
+          state: "ready",
+          models,
+          expiresAt: Date.now() + REALTIME_MODEL_CATALOG_CACHE_TTL_MS,
+        });
+      }
+      return models;
+    })
+    .catch((error: unknown) => {
+      const current = cache.get(workspaceId);
+      if (current?.state === "loading" && current.promise === promise) cache.delete(workspaceId);
+      throw error;
+    });
+  cache.set(workspaceId, { state: "loading", promise });
+  return promise;
+}
+
 export type SessionRealtimeControllerFactory = (
   options: CreateSessionRealtimeControllerOptions,
 ) => SessionRealtimeController;
@@ -129,6 +237,8 @@ export function useSessionRealtime(options: {
   model?: SessionRealtimeModel | undefined;
   modelAvailable?: boolean | undefined;
   modelUnavailableReason?: string | null | undefined;
+  /** Model-visible application context captured with each durable realtime message. */
+  getModelContext?: (() => string | undefined) | undefined;
   /** Deterministic browser-test/demo seam. Production hosts should use the SDK default. */
   controllerFactory?: SessionRealtimeControllerFactory | undefined;
 }) {
@@ -140,8 +250,14 @@ export function useSessionRealtime(options: {
   const audioRef = useRef<HTMLAudioElement>(null);
   const controllerRef = useRef<SessionRealtimeController | null>(null);
   const controllerModelRef = useRef<SessionRealtimeModel | null>(null);
+  const modelContextProviderRef = useRef(options.getModelContext);
+  modelContextProviderRef.current = options.getModelContext;
   const [snapshot, setSnapshot] = useState<SessionRealtimeControllerSnapshot>(() => ({
-    status: hasStoredSessionRealtimeOwnerProof({ workspaceId, sessionId: options.sessionId, model })
+    status: hasStoredSessionRealtimeOwnerProof({
+      workspaceId,
+      sessionId: options.sessionId,
+      model,
+    })
       ? "recovering"
       : "idle",
     realtimeId: null,
@@ -180,6 +296,7 @@ export function useSessionRealtime(options: {
           sessionId: options.sessionId,
           ...(audioRef.current ? { remoteAudio: audioRef.current } : {}),
           model,
+          getModelContext: () => modelContextProviderRef.current?.(),
         });
         controllerRef.current = controller;
         controllerModelRef.current = model;
@@ -293,6 +410,8 @@ export function SessionRealtimeControl(props: {
   events: SessionEvent[];
   eventsReady: boolean;
   codexConnected: boolean;
+  /** Model-visible application context captured with each durable realtime message. */
+  getModelContext?: (() => string | undefined) | undefined;
   realtimeAutostartModel?: SessionRealtimeModel | undefined;
   onRealtimeAutostartConsumed?: (() => void) | undefined;
   /** Host hides dictate (and can choreograph layout) while realtime voice is live. */
@@ -398,31 +517,52 @@ export function useRealtimeModelSelection(options: {
     workspaceId: options.workspaceId,
   });
   const activeModel = options.activeModel;
-  const [catalog, setCatalog] = useState<RealtimeModelOption[]>(() => [
-    {
-      ...CODEX_LIVE_MODEL,
-      available: options.codexConnected,
-      unavailableReason: options.codexConnected ? null : CODEX_LIVE_MODEL.unavailableReason,
-    },
-  ]);
-  const [selectedModelId, setSelectedModelId] = useState<SessionRealtimeModel>(
-    () => readRealtimeModelPreference(workspaceId) ?? CODEX_LIVE_MODEL.id,
+  const initialCachedCatalog = readCachedRealtimeModelCatalog(client, workspaceId);
+  const [catalog, setCatalog] = useState<RealtimeModelOption[]>(
+    () => initialCachedCatalog ?? realtimeModelFallback(options.codexConnected),
   );
+  const catalogScopeRef = useRef({
+    client,
+    workspaceId,
+    source: initialCachedCatalog ? ("cache" as const) : ("fallback" as const),
+  });
+  const [selectedModelId, setSelectedModelId] = useState<SessionRealtimeModel>(() => {
+    const preferred = readRealtimeModelPreference(workspaceId) ?? CODEX_LIVE_MODEL.id;
+    if (!initialCachedCatalog) return preferred;
+    if (initialCachedCatalog.some((model) => model.id === preferred && model.available)) {
+      return preferred;
+    }
+    return initialCachedCatalog.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
+  });
 
   useEffect(() => {
     let disposed = false;
-    const load = client.getWorkspaceRealtimeModelCatalog;
-    if (!load) return;
-    void load
-      .call(client, workspaceId)
-      .then((response) => {
+    const applyCatalog = (models: RealtimeModelOption[]) => {
+      catalogScopeRef.current = { client, workspaceId, source: "cache" };
+      setCatalog(models);
+      setSelectedModelId((current) => {
+        if (models.some((model) => model.id === current && model.available)) return current;
+        return models.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
+      });
+    };
+    const cached = readCachedRealtimeModelCatalog(client, workspaceId);
+    if (cached) {
+      const scope = catalogScopeRef.current;
+      if (
+        scope.client !== client ||
+        scope.workspaceId !== workspaceId ||
+        scope.source !== "cache"
+      ) {
+        applyCatalog(cached);
+      }
+      return;
+    }
+    const loading = loadRealtimeModelCatalog(client, workspaceId);
+    if (!loading) return;
+    void loading
+      .then((models) => {
         if (disposed) return;
-        const models = response.models.map(toRealtimeModelOption);
-        setCatalog(models);
-        setSelectedModelId((current) => {
-          if (models.some((model) => model.id === current && model.available)) return current;
-          return models.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
-        });
+        applyCatalog(models);
       })
       .catch(() => undefined);
     return () => {
@@ -684,7 +824,13 @@ export function RealtimeVoiceControl(props: {
                 opacity: 1,
                 transition: reduceMotion
                   ? { duration: 0 }
-                  : { delay: 0.32, type: "spring", stiffness: 320, damping: 30, mass: 0.8 },
+                  : {
+                      delay: 0.32,
+                      type: "spring",
+                      stiffness: 320,
+                      damping: 30,
+                      mass: 0.8,
+                    },
               }}
               {...(reduceMotion
                 ? {}
@@ -1160,7 +1306,11 @@ function statusContent(
         };
       }
       if (!canStart && admissionBlocker) {
-        return { phase: "unavailable", label: "Voice unavailable", detail: admissionBlocker };
+        return {
+          phase: "unavailable",
+          label: "Voice unavailable",
+          detail: admissionBlocker,
+        };
       }
       return {
         phase: "idle",
@@ -1268,7 +1418,11 @@ function RealtimeStatusDot(props: { phase: RealtimeVisualPhase; reduceMotion: bo
         <motion.span
           className="absolute inset-0 rounded-full bg-og-status-running"
           animate={{ opacity: [0.45, 0], scale: [1, 2.2] }}
-          transition={{ duration: 1.4, ease: "easeOut", repeat: Number.POSITIVE_INFINITY }}
+          transition={{
+            duration: 1.4,
+            ease: "easeOut",
+            repeat: Number.POSITIVE_INFINITY,
+          }}
         />
       ) : null}
       <span
@@ -1343,6 +1497,7 @@ function isRealtimeModel(value: string | null): value is SessionRealtimeModel {
     value === "opengeni-gateway/openai/gpt-realtime-2.1" ||
     value === "opengeni-gateway/openai/gpt-realtime-mini" ||
     value === "opengeni-gateway/xai/grok-voice-think-fast-2.0" ||
+    value === "supergrok/grok-voice-think-fast-2.0" ||
     value === "workspace-gateway/openai/gpt-realtime-2.1" ||
     value === "workspace-gateway/openai/gpt-realtime-mini" ||
     value === "workspace-gateway/xai/grok-voice-think-fast-2.0"