@opengeni/react 3.3.2 → 3.4.0

package/src/realtime/realtime-control.tsx

@@ -1,14 +1,12 @@
+import {
+  COMPOSER_VOICE_INPUT_START_EVENT,
+  composerVoiceEventScope,
+} from "../composer-voice-events";
 import { type EffectiveSessionControl, type SessionEvent, type SessionStatus } from "@opengeni/sdk";
 import {
-  hasStoredSessionRealtimeOwnerProof,
   projectSessionRealtimeLifecycle,
-  type SessionRealtimeClientLike,
-  type SessionRealtimeController,
   type SessionRealtimeControllerSnapshot,
-  type CreateSessionRealtimeControllerOptions,
-  type SessionRealtimeLifecycleProjection,
   type SessionRealtimeModel,
-  type WorkspaceRealtimeModelCatalogItem,
 } from "@opengeni/sdk/realtime";
 import {
   AudioLinesIcon,
@@ -22,6 +20,7 @@ import {
   SquareIcon,
   Volume2Icon,
   VolumeXIcon,
+  XIcon,
 } from "lucide-react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import {
@@ -40,10 +39,8 @@ import {
   PickerBackHeader,
   PickerNavRow,
 } from "../components/model-policy-picker";
-import type { EmbeddedRealtimeSessionClientLike } from "../client";
 import { cn } from "../lib/cn";
 import type { PickerBillingClass as BillingClass } from "../model-policy";
-import { useEmbeddedRealtimeSession } from "../session-context";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -54,26 +51,43 @@ import {
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "./dropdown-menu";
-
-export type RealtimeModelOption = {
-  id: SessionRealtimeModel;
-  label: string;
-  provider: "OpenGeni" | "Connected Codex" | "Connected SuperGrok" | "Your Gateway";
-  description: string;
-  available: boolean;
-  unavailableReason: string | null;
-  recommended: boolean;
-};
-
-const CODEX_LIVE_MODEL: RealtimeModelOption = {
-  id: "gpt-live-1-boulder-alpha",
-  label: "Codex Live",
-  provider: "Connected Codex",
-  description: "Deep session integration",
-  available: false,
-  unavailableReason: "Connect Codex to use this voice model",
-  recommended: false,
-};
+import { MENU_CHECK_CLASS } from "../lib/menu-styles";
+import {
+  CODEX_LIVE_MODEL,
+  type RealtimeControllerClient,
+  type RealtimeModelOption,
+  type SessionRealtimeControllerFactory,
+  sessionRealtimeLifecycleIsActive,
+  useRealtimeModelSelection,
+  useSessionRealtime,
+} from "./session-realtime";
+
+export {
+  codexRealtimeAdmissionAllowed,
+  codexRealtimeAdmissionBlocker,
+  CODEX_LIVE_MODEL,
+  sessionRealtimeLifecycleIsActive,
+  useRealtimeModelSelection,
+  useSessionRealtime,
+} from "./session-realtime";
+export type { RealtimeModelOption, SessionRealtimeControllerFactory } from "./session-realtime";
+
+/** Short status label for a credit/availability refusal (shared with the model menu). */
+function realtimeRefusalLabel(code: string | null | undefined): string | null {
+  switch (code) {
+    case "insufficient_credits":
+      return "Credits needed";
+    case "allowance_exhausted":
+    case "monthly_model_cost_limit":
+      return "Usage limit reached";
+    case "realtime_voice_unavailable":
+      return "Voice unavailable";
+    case "credits_disabled":
+      return "Credits off";
+    default:
+      return null;
+  }
+}
 
 const REALTIME_MODEL_PROVIDERS = [
   "OpenGeni",
@@ -85,378 +99,30 @@ type RealtimeModelProvider = (typeof REALTIME_MODEL_PROVIDERS)[number];
 
 const REALTIME_PROVIDER_META: Record<
   RealtimeModelProvider,
-  { billingClass: BillingClass; hint: string }
+  { billingClass: BillingClass; label: string; hint: string }
 > = {
-  OpenGeni: { billingClass: "opengeni_credits", hint: "Will use credits" },
+  // The wire value keeps its historical spelling; the product name is Opengeni.
+  OpenGeni: { billingClass: "opengeni_credits", label: "Opengeni", hint: "Uses Opengeni credits" },
   "Connected Codex": {
     billingClass: "codex_subscription",
+    label: "Connected Codex",
     hint: "ChatGPT / Codex plan",
   },
   "Connected SuperGrok": {
     billingClass: "supergrok_subscription",
+    label: "Connected SuperGrok",
     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[]>;
-      controller: AbortController;
-      consumers: number;
-    }
-  | { 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,
-  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" && !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, { signal: controller.signal })
-    .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;
-    });
-  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 = (
-  options: CreateSessionRealtimeControllerOptions,
-) => SessionRealtimeController;
-
-type AdmissionInput = {
-  sessionStatus: SessionStatus;
-  controlState: "active" | "paused";
-  settlement: { state: string } | null;
-  codexConnected: boolean;
-  lifecycleActive: boolean;
+  "Your Gateway": {
+    billingClass: "byok",
+    label: "Your Gateway",
+    hint: "Billed to your AI Gateway",
+  },
 };
-
-export function codexRealtimeAdmissionAllowed(input: AdmissionInput): boolean {
-  return codexRealtimeAdmissionBlocker(input) === null;
-}
-
-export function codexRealtimeAdmissionBlocker(input: AdmissionInput): string | null {
-  if (input.sessionStatus === "cancelled") return "This session was cancelled.";
-  if (input.controlState !== "active") return "Resume this session before starting voice.";
-  if (input.settlement !== null) return "Wait for the current session transition to finish.";
-  if (!input.codexConnected) return "Connect Codex to use this voice model.";
-  if (input.lifecycleActive) return "Voice is already active for this session.";
-  return null;
+/** Display name; the catalog's `provider` value stays the wire identifier. */
+function realtimeProviderLabel(provider: RealtimeModelProvider): string {
+  return provider === "OpenGeni" ? "Opengeni" : provider;
 }
-
-export function useSessionRealtime(options: {
-  client?: RealtimeControllerClient | undefined;
-  workspaceId?: string | undefined;
-  sessionId: string;
-  sessionStatus: SessionStatus;
-  effectiveControl: EffectiveSessionControl;
-  events: SessionEvent[];
-  eventsReady: boolean;
-  codexConnected: boolean;
-  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;
-}) {
-  const { client, workspaceId } = useEmbeddedRealtimeSession({
-    client: options.client,
-    workspaceId: options.workspaceId,
-  });
-  const model = options.model ?? CODEX_LIVE_MODEL.id;
-  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,
-    })
-      ? "recovering"
-      : "idle",
-    realtimeId: null,
-    mode: null,
-    bridge: null,
-    microphone: "inactive",
-    inputMuted: false,
-    audibleOutput: "inactive",
-    outputMuted: false,
-    connectionGeneration: 0,
-    reconnectAttempt: 0,
-    diagnostic: null,
-    error: null,
-  }));
-  const lifecycle = useMemo(
-    () => projectSessionRealtimeLifecycle(options.events),
-    [options.events],
-  );
-  const lifecycleRef = useRef(lifecycle);
-  const eventsReadyRef = useRef(options.eventsReady);
-  lifecycleRef.current = lifecycle;
-  eventsReadyRef.current = options.eventsReady;
-  const lifecycleActive = sessionRealtimeLifecycleIsActive(lifecycle);
-
-  useEffect(() => {
-    let disposed = false;
-    let controller: SessionRealtimeController | null = null;
-    let unsubscribe: (() => void) | null = null;
-    void import("@opengeni/sdk/realtime")
-      .then(({ createSessionRealtimeController }) => {
-        if (disposed) return;
-        const controllerFactory = options.controllerFactory ?? createSessionRealtimeController;
-        controller = controllerFactory({
-          client,
-          workspaceId,
-          sessionId: options.sessionId,
-          ...(audioRef.current ? { remoteAudio: audioRef.current } : {}),
-          model,
-          getModelContext: () => modelContextProviderRef.current?.(),
-        });
-        controllerRef.current = controller;
-        controllerModelRef.current = model;
-        unsubscribe = controller.subscribe(setSnapshot);
-        if (eventsReadyRef.current) {
-          void controller.observeLifecycle(lifecycleRef.current).catch(() => undefined);
-        }
-      })
-      .catch((error: unknown) => {
-        if (disposed) return;
-        setSnapshot({
-          status: "error",
-          realtimeId: null,
-          mode: null,
-          bridge: null,
-          microphone: "inactive",
-          inputMuted: false,
-          audibleOutput: "inactive",
-          outputMuted: false,
-          connectionGeneration: 0,
-          reconnectAttempt: 0,
-          diagnostic: {
-            kind: "negotiation_failure",
-            message:
-              error instanceof Error ? error.message : "Codex realtime controller failed to load",
-            recoverable: false,
-            connectionGeneration: 0,
-            attempt: 0,
-          },
-          error:
-            error instanceof Error ? error.message : "Codex realtime controller failed to load",
-        });
-      });
-    return () => {
-      disposed = true;
-      unsubscribe?.();
-      controller?.close();
-      if (controllerRef.current === controller) {
-        controllerRef.current = null;
-        controllerModelRef.current = null;
-      }
-    };
-  }, [client, model, options.controllerFactory, options.sessionId, workspaceId]);
-
-  useEffect(() => {
-    if (!options.eventsReady) return;
-    void controllerRef.current?.observeLifecycle(lifecycle).catch(() => undefined);
-  }, [lifecycle, options.eventsReady]);
-
-  const start = useCallback(async () => {
-    const controller = controllerRef.current;
-    if (!controller || controllerModelRef.current !== model) {
-      throw new Error("The selected voice model is still preparing");
-    }
-    await controller.start();
-  }, [model]);
-  const stop = useCallback(async () => {
-    await controllerRef.current?.stop();
-  }, []);
-  const retry = useCallback(async () => {
-    await controllerRef.current?.retry();
-  }, []);
-  const retryAudibleOutput = useCallback(async () => {
-    await controllerRef.current?.retryAudibleOutput();
-  }, []);
-  const setInputMuted = useCallback((muted: boolean) => {
-    controllerRef.current?.setInputMuted(muted);
-  }, []);
-  const setOutputMuted = useCallback((muted: boolean) => {
-    controllerRef.current?.setOutputMuted(muted);
-  }, []);
-  const admissionInput = {
-    sessionStatus: options.sessionStatus,
-    controlState: options.effectiveControl.state,
-    settlement: options.effectiveControl.settlement,
-    codexConnected: options.modelAvailable ?? options.codexConnected,
-    lifecycleActive,
-  } satisfies AdmissionInput;
-  const admissionBlocker =
-    options.modelAvailable === false
-      ? (options.modelUnavailableReason ?? "This voice model is unavailable.")
-      : codexRealtimeAdmissionBlocker(admissionInput);
-  const canStart =
-    controllerRef.current !== null &&
-    controllerModelRef.current === model &&
-    ["idle", "error"].includes(snapshot.status) &&
-    admissionBlocker === null;
-
-  return {
-    snapshot,
-    lifecycleActive,
-    canStart,
-    admissionBlocker,
-    codexConnected: options.codexConnected,
-    audioRef,
-    start,
-    stop,
-    retry,
-    retryAudibleOutput,
-    setInputMuted,
-    setOutputMuted,
-  };
-}
-
-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;
@@ -511,6 +177,7 @@ export function SessionRealtimeControl(props: {
   useEffect(() => {
     onVoiceActiveChange?.(voiceActive);
   }, [onVoiceActiveChange, voiceActive]);
+  useEffect(() => () => onVoiceActiveChange?.(false), [onVoiceActiveChange]);
 
   useEffect(() => {
     const pending = autostartModelRef.current;
@@ -523,14 +190,13 @@ export function SessionRealtimeControl(props: {
     }
     if (!canStart) return;
     autostartStartedRef.current = true;
-    void start()
-      .then(() => {
-        autostartModelRef.current = null;
-        onRealtimeAutostartConsumed?.();
-      })
-      .catch(() => {
-        autostartStartedRef.current = false;
-      });
+    // One automatic attempt. A failed start stays visible with its reason and
+    // the user retries explicitly; re-arming would loop on a definitive refusal.
+    const consume = () => {
+      autostartModelRef.current = null;
+      onRealtimeAutostartConsumed?.();
+    };
+    void start().then(consume, consume);
   }, [
     canStart,
     lifecycleActive,
@@ -566,96 +232,6 @@ export function SessionRealtimeControl(props: {
   );
 }
 
-export function useRealtimeModelSelection(options: {
-  client?: RealtimeControllerClient | undefined;
-  workspaceId?: string | undefined;
-  codexConnected: boolean;
-  activeModel?: SessionRealtimeModel | null | undefined;
-}) {
-  const { client, workspaceId } = useEmbeddedRealtimeSession({
-    client: options.client,
-    workspaceId: options.workspaceId,
-  });
-  const activeModel = options.activeModel;
-  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 requestAbort = new AbortController();
-    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, requestAbort.signal);
-    if (!loading) return;
-    void loading
-      .then((models) => {
-        if (disposed) return;
-        applyCatalog(models);
-      })
-      .catch(() => undefined);
-    return () => {
-      disposed = true;
-      requestAbort.abort();
-    };
-  }, [client, workspaceId]);
-
-  useEffect(() => {
-    if (activeModel) setSelectedModelId(activeModel);
-  }, [activeModel]);
-
-  const selectedModel =
-    catalog.find((model) => model.id === selectedModelId) ??
-    ({
-      ...CODEX_LIVE_MODEL,
-      available: options.codexConnected,
-      unavailableReason: options.codexConnected ? null : CODEX_LIVE_MODEL.unavailableReason,
-    } satisfies RealtimeModelOption);
-  const selectModel = useCallback(
-    (value: string) => {
-      const model = catalog.find((candidate) => candidate.id === value);
-      if (!model || !model.available || activeModel) return;
-      setSelectedModelId(model.id);
-      writeRealtimeModelPreference(workspaceId, model.id);
-    },
-    [activeModel, catalog, workspaceId],
-  );
-
-  return { models: catalog, selectedModel, selectModel };
-}
-
 const IDLE_REALTIME_SNAPSHOT: SessionRealtimeControllerSnapshot = {
   status: "idle",
   realtimeId: null,
@@ -821,6 +397,7 @@ export function RealtimeVoiceControl(props: {
     props.canStart,
     props.admissionBlocker ?? null,
     selectedModel.label,
+    selectedModel.unavailableCode ?? null,
   );
   const modeOwned = props.snapshot.mode?.state === "active";
   const retryConnection =
@@ -829,6 +406,11 @@ export function RealtimeVoiceControl(props: {
     props.snapshot.status !== "active" &&
     props.snapshot.diagnostic?.recoverable === true;
   const audioBlocked = props.snapshot.audibleOutput === "blocked" && !props.snapshot.outputMuted;
+  // A call that ended in a failure keeps its reason on screen, not only in a
+  // tooltip or the model menu, until the user starts again or changes model.
+  const startFailed = props.snapshot.status === "error" && !modeOwned;
+  const failureText =
+    status.label === "Voice unavailable" ? status.detail : `${status.label}. ${status.detail}`;
   const mainDisabled =
     props.snapshot.status === "stopping" ||
     props.snapshot.status === "lost_owner" ||
@@ -840,7 +422,11 @@ export function RealtimeVoiceControl(props: {
       ? "Retry voice connection"
       : modeOwned
         ? "End voice conversation"
-        : `Start voice with ${selectedModel.label}`;
+        : !props.canStart && status.phase === "unavailable"
+          ? `${status.label}: ${status.detail}`
+          : startFailed
+            ? `Try voice again with ${selectedModel.label}`
+            : `Start voice with ${selectedModel.label}`;
   const runMainAction = audioBlocked
     ? props.onRetryAudibleOutput
     : retryConnection
@@ -857,6 +443,20 @@ export function RealtimeVoiceControl(props: {
     selectedModel.provider,
   );
   const [pickerDirection, setPickerDirection] = useState<1 | -1>(1);
+  const [failureDismissed, setFailureDismissed] = useState(false);
+  useEffect(() => {
+    if (!startFailed) setFailureDismissed(false);
+  }, [startFailed]);
+  const rootRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!startFailed) return;
+    // Starting dictation in this composer supersedes a stale start failure.
+    const scope = composerVoiceEventScope(rootRef.current);
+    if (!scope) return;
+    const dismiss = () => setFailureDismissed(true);
+    scope.addEventListener(COMPOSER_VOICE_INPUT_START_EVENT, dismiss);
+    return () => scope.removeEventListener(COMPOSER_VOICE_INPUT_START_EVENT, dismiss);
+  }, [startFailed]);
 
   useEffect(() => {
     if (!pickerOpen) setPickerProvider(selectedModel.provider);
@@ -864,6 +464,7 @@ export function RealtimeVoiceControl(props: {
 
   return (
     <div
+      ref={rootRef}
       role="group"
       aria-label="Realtime voice"
       data-picker-side={props.menuSide ?? "top"}
@@ -945,6 +546,20 @@ export function RealtimeVoiceControl(props: {
           </motion.div>
         ) : null}
       </AnimatePresence>
+      {startFailed && !failureDismissed ? (
+        <button
+          type="button"
+          data-realtime-attention=""
+          data-testid="realtime-failure-reason"
+          title="Dismiss"
+          aria-label={`Dismiss: ${failureText}`}
+          onClick={() => setFailureDismissed(true)}
+          className="og-realtime-failure mr-1.5 inline-flex min-w-0 items-center gap-1 rounded-og-sm text-right text-og-xs leading-tight text-og-status-failed outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent/45"
+        >
+          <span className="og-realtime-failure-label line-clamp-2 max-w-56">{failureText}</span>
+          <XIcon className="size-3 shrink-0 opacity-70" aria-hidden />
+        </button>
+      ) : null}
       <div className="inline-flex shrink-0 items-center">
         <motion.button
           type="button"
@@ -1005,7 +620,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">
@@ -1028,9 +643,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
@@ -1046,7 +667,6 @@ export function RealtimeVoiceControl(props: {
 
               {audioBlocked ? (
                 <DropdownMenuItem
-                  className="rounded-og-md"
                   onSelect={() => void props.onRetryAudibleOutput().catch(() => undefined)}
                 >
                   <Volume2Icon />
@@ -1054,10 +674,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>
@@ -1065,7 +682,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)}
                 >
@@ -1105,16 +721,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}
@@ -1202,7 +816,7 @@ export function RealtimeModelPickerMenu(props: {
   const body = props.provider ? (
     <div data-testid="realtime-model-picker-models">
       <PickerBackHeader
-        label={props.provider}
+        label={realtimeProviderLabel(props.provider)}
         icon={
           <BillingClassMark
             billingClass={REALTIME_PROVIDER_META[props.provider].billingClass}
@@ -1228,7 +842,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)}
               />
@@ -1243,7 +859,7 @@ export function RealtimeModelPickerMenu(props: {
         return (
           <PickerNavRow
             key={provider}
-            label={provider}
+            label={realtimeProviderLabel(provider)}
             hint={meta.hint}
             icon={<BillingClassMark billingClass={meta.billingClass} aria-label="" />}
             active={props.selectedModel.provider === provider}
@@ -1291,12 +907,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}
@@ -1331,6 +947,7 @@ function statusContent(
   canStart: boolean,
   admissionBlocker: string | null,
   modelLabel: string,
+  unavailableCode: string | null = null,
 ): { phase: RealtimeVisualPhase; label: string; detail: string } {
   if (snapshot.audibleOutput === "blocked" && !snapshot.outputMuted) {
     return {
@@ -1377,6 +994,13 @@ function statusContent(
         detail: "Return to the browser that started it, or wait for that connection to expire.",
       };
     case "error":
+      if (snapshot.refusal) {
+        return {
+          phase: "unavailable",
+          label: realtimeRefusalLabel(snapshot.refusal.code) ?? "Voice unavailable",
+          detail: snapshot.refusal.message,
+        };
+      }
       return {
         phase: "error",
         label: "Voice unavailable",
@@ -1386,7 +1010,7 @@ function statusContent(
       if (!modelAvailable) {
         return {
           phase: "unavailable",
-          label: "Voice model unavailable",
+          label: realtimeRefusalLabel(unavailableCode) ?? "Voice model unavailable",
           detail: admissionBlocker ?? "Choose another voice model.",
         };
       }
@@ -1528,7 +1152,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";
@@ -1542,7 +1166,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";
@@ -1553,42 +1177,6 @@ function voiceChevronTone(phase: RealtimeVisualPhase): string {
   return "text-og-fg-muted hover:bg-og-surface-2 hover:text-og-fg";
 }
 
-function toRealtimeModelOption(model: WorkspaceRealtimeModelCatalogItem): RealtimeModelOption {
-  return { ...model };
-}
-
-function readRealtimeModelPreference(workspaceId: string): SessionRealtimeModel | null {
-  if (typeof localStorage === "undefined") return null;
-  try {
-    const value = localStorage.getItem(`${REALTIME_MODEL_STORAGE_PREFIX}:${workspaceId}`);
-    return isRealtimeModel(value) ? value : null;
-  } catch {
-    return null;
-  }
-}
-
-function writeRealtimeModelPreference(workspaceId: string, model: SessionRealtimeModel): void {
-  if (typeof localStorage === "undefined") return;
-  try {
-    localStorage.setItem(`${REALTIME_MODEL_STORAGE_PREFIX}:${workspaceId}`, model);
-  } catch {
-    // Voice selection still works when browser storage is unavailable.
-  }
-}
-
-function isRealtimeModel(value: string | null): value is SessionRealtimeModel {
-  return (
-    value === "gpt-live-1-boulder-alpha" ||
-    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"
-  );
-}
-
 /** @deprecated Use the provider-neutral realtime names. */
 export const useSessionCodexRealtime = useSessionRealtime;
 /** @deprecated Use the provider-neutral realtime names. */