@opengeni/react 1.3.0 → 1.4.2

package/src/hooks/use-voice-input.ts

@@ -11,6 +11,7 @@ import {
 } from "../voice-recording-store";
 import {
   acquireDefaultVoiceRecordingOwnerLease,
+  liveVoiceRecordingOwnerIds,
   type VoiceRecordingOwnerLease,
 } from "../voice-recording-owner";
 import { appendFinalTranscript } from "./use-transcription";
@@ -65,6 +66,10 @@ export type UseVoiceInputResult = {
   stream: MediaStream | null;
   recordingId: string | null;
   durationSeconds: number;
+  /** Wall-clock start of the current capture (epoch ms), or null when not recording. */
+  recordingStartedAt: number | null;
+  /** Capture stops and transcribes automatically after this many seconds. */
+  maxRecordingSeconds: number | null;
   locallySaved: boolean;
   hasRecoverableRecording: boolean;
   savedTranscript: string | null;
@@ -75,7 +80,10 @@ export type UseVoiceInputResult = {
   retry: () => void;
   /** Explicitly insert a durably saved transcript whose prior handoff may be uncertain. */
   insertSavedTranscript: () => Promise<void>;
-  /** Cancel active work. A stopped/transcribing recording remains recoverable. */
+  /**
+   * Cancel active work without losing speech: a recording longer than a few
+   * seconds and any stopped/transcribing recording stay locally recoverable.
+   */
   cancel: () => void;
   /** Intentionally delete the current durable recording. */
   discard: () => Promise<void>;
@@ -85,6 +93,8 @@ export const VOICE_RECORDING_TIMESLICE_MILLISECONDS = 5_000;
 export const VOICE_RECORDING_OWNER_HEARTBEAT_MILLISECONDS = 5_000;
 export const VOICE_RECORDING_OWNER_STALE_MILLISECONDS = 30_000;
 export const VOICE_RECORDING_CLIENT_MAX_DURATION_SECONDS = 600;
+// Cancel deletes only an accidental start; anything longer is kept for the user.
+const VOICE_RECORDING_DISCARD_ON_CANCEL_MAX_MILLISECONDS = 3_000;
 export const VOICE_RECORDING_RESUMABLE_CLIENT_MAX_DURATION_SECONDS = 8 * 60 * 60;
 export const VOICE_RECORDING_RECOVERY_STATUS_POLL_MILLISECONDS = 2_000;
 export const VOICE_RECORDING_RECOVERY_MAX_MUTATION_DELAY_MILLISECONDS = 30_000;
@@ -159,6 +169,9 @@ export function useVoiceInput({
   const recorderRef = useRef<MediaRecorder | null>(null);
   const streamRef = useRef<MediaStream | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Cancel/Escape/voice takeover keep a real dictation instead of deleting it.
+  const holdOnStopRef = useRef(false);
+  const recordingStartedAtRef = useRef(0);
   const automaticRetryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const automaticRetryAttemptRef = useRef(0);
   const ownerHeartbeatTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -321,15 +334,31 @@ export function useVoiceInput({
         generation === generationRef.current && workspaceIdRef.current === workspaceId;
       const [store, ownerId] = await Promise.all([ensureStore(), ensureOwnerId()]);
       if (!active()) return;
-      const staleBefore = new Date(
+      const heartbeatStaleBefore = new Date(
         readNow().getTime() - VOICE_RECORDING_OWNER_STALE_MILLISECONDS,
       ).toISOString();
-      await store.cleanupHandedOffManifests({ ownerId, staleBefore }).catch(() => undefined);
+      await store
+        .cleanupHandedOffManifests({ ownerId, staleBefore: heartbeatStaleBefore })
+        .catch(() => undefined);
       if (!active()) return;
-      const manifests = await store.listRecoverableManifests(workspaceId, {
-        ownerId,
-        staleBefore,
-      });
+      // A closed or crashed tab releases its owner lock at once: recover its
+      // recording now rather than after the heartbeat window (the user who
+      // reopens the app right away must still see their dictation).
+      const liveOwners =
+        createOwnerIdRef.current === undefined ? await liveVoiceRecordingOwnerIds() : null;
+      if (!active()) return;
+      const staleBefore = liveOwners ? readNow().toISOString() : heartbeatStaleBefore;
+      const manifests = (
+        await store.listRecoverableManifests(workspaceId, { ownerId, staleBefore })
+      ).filter(
+        (manifest) =>
+          !liveOwners ||
+          !manifest.ownerId ||
+          manifest.ownerId === ownerId ||
+          !liveOwners.has(manifest.ownerId) ||
+          !manifest.ownerHeartbeatAt ||
+          manifest.ownerHeartbeatAt <= heartbeatStaleBefore,
+      );
       if (!active()) return;
       for (const candidate of manifests) {
         try {
@@ -353,14 +382,20 @@ export function useVoiceInput({
           }
           rememberManifest(claimed);
           beginOwnerHeartbeat(claimed);
+          const transcriptReady =
+            claimed.finalizationState === "transcript-ready" && claimed.transcriptText !== null;
           setStatus(
-            claimed.finalizationState === "transcript-ready" && claimed.transcriptText !== null
+            transcriptReady
               ? "transcript-ready"
               : claimed.recoveryMode === "automatic"
                 ? "retrying"
                 : "recovered",
           );
-          setError(null);
+          // An append-mode transcript may already be in the draft (the page
+          // closed between appending and recording the handoff).
+          setError(
+            transcriptReady && candidate.handoffMode === "append" ? "handoff_uncertain" : null,
+          );
           return;
         } catch (reason) {
           if (reason instanceof VoiceRecordingOwnedError) continue;
@@ -464,8 +499,9 @@ export function useVoiceInput({
 
         automaticRetryAttemptRef.current = 0;
         if (ready.handoffMode === "explicit") {
+          // Never appended: offer an explicit insert, not an "already inserted?" warning.
           setStatus("transcript-ready");
-          setError("handoff_uncertain");
+          setError(null);
           focusInput();
           return;
         }
@@ -824,6 +860,15 @@ export function useVoiceInput({
               await preserveForRetry(retained, attemptCaptureLimitError, generation);
               return;
             }
+            if (holdOnStopRef.current) {
+              holdOnStopRef.current = false;
+              const retained = await updateManifestBestEffort(stopped, {
+                recoveryMode: "manual",
+                handoffMode: "explicit",
+              });
+              await preserveForRetry(retained, null, generation);
+              return;
+            }
             await finalizePersistedRecording(generation);
           });
       };
@@ -832,6 +877,8 @@ export function useVoiceInput({
         resolveCaptureSettledRef.current = resolve;
       });
       attemptRecordingStartedAt = readNow().getTime();
+      recordingStartedAtRef.current = attemptRecordingStartedAt;
+      holdOnStopRef.current = false;
       recorder.start(VOICE_RECORDING_TIMESLICE_MILLISECONDS);
       recorderStarted = true;
       setStatus("recording");
@@ -1069,7 +1116,27 @@ export function useVoiceInput({
   ]);
 
   const cancel = useCallback(() => {
-    if (status === "recording" || status === "requesting-permission") {
+    if (status === "recording") {
+      const recorder = recorderRef.current;
+      const elapsed = readNow().getTime() - recordingStartedAtRef.current;
+      if (
+        recorder &&
+        recorder.state !== "inactive" &&
+        elapsed >= VOICE_RECORDING_DISCARD_ON_CANCEL_MAX_MILLISECONDS
+      ) {
+        // Never delete real speech on Cancel/Escape: stop, keep it locally, and
+        // let the user transcribe or explicitly discard it.
+        if (timerRef.current) clearTimeout(timerRef.current);
+        timerRef.current = null;
+        holdOnStopRef.current = true;
+        setStatus("saving");
+        recorder.stop();
+        return;
+      }
+      void discard();
+      return;
+    }
+    if (status === "requesting-permission") {
       void discard();
       return;
     }
@@ -1093,7 +1160,7 @@ export function useVoiceInput({
         await preserveForRetry(retained, null, generation);
       });
     }
-  }, [discard, preserveForRetry, status, updateManifestBestEffort]);
+  }, [discard, preserveForRetry, readNow, status, updateManifestBestEffort]);
 
   useEffect(() => {
     const current = manifestRef.current;
@@ -1156,6 +1223,8 @@ export function useVoiceInput({
     const onKeyDown = (event: KeyboardEvent) => {
       if (
         event.key === "Escape" &&
+        // A dialog, menu, or popover that handled Escape owns it.
+        !event.defaultPrevented &&
         (status === "requesting-permission" ||
           status === "recording" ||
           status === "saving" ||
@@ -1179,6 +1248,19 @@ export function useVoiceInput({
       automaticRetryTimerRef.current = null;
       const manifest = manifestRef.current;
       const ownerReady = ownerIdPromiseRef.current;
+      const knownOwnerId = ownerIdRef.current;
+      const ownerLease = ownerLeaseRef.current;
+      const closingStore = storeRef.current;
+      const ownsClosingStore = ownsStoreRef.current;
+      // Detach synchronously: a remount of this instance (React StrictMode,
+      // keyed re-render) must open a fresh store and owner instead of reusing
+      // the connection this cleanup is about to close.
+      storeRef.current = null;
+      storePromiseRef.current = null;
+      ownerIdRef.current = null;
+      ownerIdPromiseRef.current = null;
+      ownerLeaseRef.current = null;
+      manifestRef.current = null;
       stopOwnerHeartbeat();
       const recorder = recorderRef.current;
       let captureSettled = persistenceQueueRef.current;
@@ -1190,9 +1272,8 @@ export function useVoiceInput({
       void captureSettled
         .catch(() => undefined)
         .then(async () => {
-          const ownerId =
-            ownerIdRef.current ?? (ownerReady ? await ownerReady.catch(() => null) : null);
-          const store = storeRef.current;
+          const ownerId = knownOwnerId ?? (ownerReady ? await ownerReady.catch(() => null) : null);
+          const store = closingStore;
           if (store && manifest && ownerId) {
             const wasProcessing =
               statusRef.current === "saving" ||
@@ -1221,12 +1302,11 @@ export function useVoiceInput({
               )
               .catch(() => undefined);
           }
-          if (ownsStoreRef.current) await store?.close();
+          if (ownsClosingStore) await store?.close();
         })
         .catch(() => undefined)
         .finally(() => {
-          ownerLeaseRef.current?.release();
-          ownerLeaseRef.current = null;
+          ownerLease?.release();
         });
     },
     [clearCaptureRuntime, readNow, stopOwnerHeartbeat],
@@ -1239,6 +1319,17 @@ export function useVoiceInput({
     stream,
     recordingId,
     durationSeconds,
+    recordingStartedAt: status === "recording" ? recordingStartedAtRef.current || null : null,
+    maxRecordingSeconds: capability
+      ? Math.min(
+          capability.resumable && isResumableVoiceInputClient(client)
+            ? capability.resumable.maxDurationSeconds
+            : capability.maxDurationSeconds,
+          capability.resumable && isResumableVoiceInputClient(client)
+            ? VOICE_RECORDING_RESUMABLE_CLIENT_MAX_DURATION_SECONDS
+            : VOICE_RECORDING_CLIENT_MAX_DURATION_SECONDS,
+        )
+      : null,
     locallySaved,
     hasRecoverableRecording: manifestRef.current !== null && status !== "recording",
     savedTranscript:
@@ -1503,6 +1594,12 @@ function errorCode(error: unknown): string {
 }
 
 function isRetryableVoiceInputError(error: unknown): boolean {
+  if (
+    ["insufficient_credits", "allowance_exhausted", "monthly_model_cost_limit"].includes(
+      errorCode(error),
+    )
+  )
+    return false;
   if (error instanceof OpenGeniApiError) {
     return error.retryable && error.status !== 409;
   }

package/src/index.ts

@@ -16,6 +16,9 @@ export {
 export {
   attachSessionCapability,
   completeSessionCapabilityOAuth,
+  prepareSessionCapabilityAccess,
+  applySessionCapabilityAccess,
+  type SessionCapabilityAccessPlan,
 } from "./session-capability-policy";
 export { retainedImageId } from "./components/markdown";
 // oxlint-disable-next-line typescript/triple-slash-reference -- package consumers must load the ambient type for this optional untyped peer without emitting a runtime import.
@@ -388,14 +391,20 @@ export type {
 // Tool-renderer registry + the per-tool renderers (the timeline's extension API)
 export {
   createDefaultToolRegistry,
+  createSessionRetainedScreenshotLoader,
   createToolRegistry,
+  createWorkspaceRetainedArtifactLoader,
+  createWorkspaceRetainedVideoLoader,
   defaultToolRegistry,
   rawTypeOf,
 } from "./timeline";
 export type {
   CreateToolRegistryOptions,
   RetainedArtifactLoader,
+  RetainedArtifactLoaderClient,
   RetainedScreenshotLoader,
+  RetainedScreenshotLoaderClient,
+  RetainedVideoLoaderClient,
   VideoArtifactPlaybackLoader,
   ToolRegistry,
   ToolRegistryEntry,

package/src/realtime/embedded-voice.tsx

@@ -0,0 +1,81 @@
+import type { EffectiveSessionControl, SessionEvent, SessionStatus } from "@opengeni/sdk";
+import { projectSessionRealtimeLifecycle } from "@opengeni/sdk/realtime";
+import { useEffect, useMemo, useState } from "react";
+
+import {
+  RealtimeVoiceControl,
+  useSessionRealtime,
+  type RealtimeModelOption,
+} from "./realtime-control";
+
+/**
+ * The stock conversation's live voice button (lazy chunk). The conversation
+ * mounts it only when the workspace catalog offers an available voice model;
+ * this owns choosing among those models and the call itself.
+ */
+export default function EmbeddedRealtimeVoice(props: {
+  /** The conversation's client, which serves the realtime routes (or a proxy of them). */
+  client: unknown;
+  workspaceId: string;
+  /** Available voice models, already filtered by the conversation. */
+  models: readonly RealtimeModelOption[];
+  sessionId: string;
+  sessionStatus: SessionStatus;
+  effectiveControl: EffectiveSessionControl;
+  events: SessionEvent[];
+  eventsReady: boolean;
+  onVoiceActiveChange?: ((active: boolean) => void) | undefined;
+}) {
+  const lifecycle = useMemo(() => projectSessionRealtimeLifecycle(props.events), [props.events]);
+  // A call already running (this browser after reload, or another one) fixes the model.
+  const activeModel =
+    lifecycle?.state === "active" && !(Date.parse(lifecycle.leaseExpiresAt) <= Date.now())
+      ? lifecycle.model
+      : null;
+  const [chosen, setChosen] = useState<string | null>(null);
+  const fallback = props.models.find((model) => model.recommended) ?? props.models[0]!;
+  const selected =
+    props.models.find((model) => model.id === (activeModel ?? chosen)) ??
+    (activeModel ? { ...fallback, id: activeModel } : fallback);
+  const realtime = useSessionRealtime({
+    client: props.client as Parameters<typeof useSessionRealtime>[0]["client"],
+    workspaceId: props.workspaceId,
+    sessionId: props.sessionId,
+    sessionStatus: props.sessionStatus,
+    effectiveControl: props.effectiveControl,
+    events: props.events,
+    eventsReady: props.eventsReady,
+    codexConnected: false,
+    model: selected.id,
+    modelAvailable: selected.available,
+    modelUnavailableReason: selected.unavailableReason,
+  });
+  const voiceActive = realtime.snapshot.mode?.state === "active";
+  const onVoiceActiveChange = props.onVoiceActiveChange;
+  useEffect(() => {
+    onVoiceActiveChange?.(voiceActive);
+  }, [onVoiceActiveChange, voiceActive]);
+  useEffect(() => () => onVoiceActiveChange?.(false), [onVoiceActiveChange]);
+
+  return (
+    <RealtimeVoiceControl
+      snapshot={realtime.snapshot}
+      canStart={realtime.canStart}
+      admissionBlocker={realtime.admissionBlocker}
+      modelAvailable={selected.available}
+      menuSide="top"
+      modelMenu="split"
+      showDiagnostics={false}
+      audioRef={realtime.audioRef}
+      selectedModel={selected}
+      models={props.models}
+      onSelectModel={realtime.lifecycleActive ? undefined : setChosen}
+      onStart={realtime.start}
+      onStop={realtime.stop}
+      onRetry={realtime.retry}
+      onRetryAudibleOutput={realtime.retryAudibleOutput}
+      onSetInputMuted={realtime.setInputMuted}
+      onSetOutputMuted={realtime.setOutputMuted}
+    />
+  );
+}

package/src/realtime/realtime-control.tsx

@@ -1,3 +1,7 @@
+import {
+  COMPOSER_VOICE_INPUT_START_EVENT,
+  composerVoiceEventScope,
+} from "../composer-voice-events";
 import { type EffectiveSessionControl, type SessionEvent, type SessionStatus } from "@opengeni/sdk";
 import {
   hasStoredSessionRealtimeOwnerProof,
@@ -22,6 +26,7 @@ import {
   SquareIcon,
   Volume2Icon,
   VolumeXIcon,
+  XIcon,
 } from "lucide-react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import {
@@ -63,9 +68,26 @@ export type RealtimeModelOption = {
   description: string;
   available: boolean;
   unavailableReason: string | null;
+  /** Machine-readable reason, e.g. `insufficient_credits` (same codes as voice input). */
+  unavailableCode?: string | null | undefined;
   recommended: boolean;
 };
 
+/** 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";
+    default:
+      return null;
+  }
+}
+
 const CODEX_LIVE_MODEL: RealtimeModelOption = {
   id: "gpt-live-1-boulder-alpha",
   label: "Codex Live",
@@ -86,19 +108,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" },
+  "Your Gateway": {
+    billingClass: "byok",
+    label: "Your Gateway",
+    hint: "Billed to your AI Gateway",
+  },
 };
+/** Display name; the catalog's `provider` value stays the wire identifier. */
+function realtimeProviderLabel(provider: RealtimeModelProvider): string {
+  return provider === "OpenGeni" ? "Opengeni" : provider;
+}
 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;
@@ -524,14 +557,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,
@@ -567,6 +599,18 @@ export function SessionRealtimeControl(props: {
   );
 }
 
+/**
+ * First available model; otherwise the model whose blocker the user can act on
+ * (for example adding credits) rather than an unrelated "connect" prompt.
+ */
+function fallbackRealtimeModelId(models: readonly RealtimeModelOption[]): SessionRealtimeModel {
+  return (
+    models.find((model) => model.available)?.id ??
+    models.find((model) => model.unavailableCode)?.id ??
+    CODEX_LIVE_MODEL.id
+  );
+}
+
 export function useRealtimeModelSelection(options: {
   client?: RealtimeControllerClient | undefined;
   workspaceId?: string | undefined;
@@ -593,7 +637,7 @@ export function useRealtimeModelSelection(options: {
     if (initialCachedCatalog.some((model) => model.id === preferred && model.available)) {
       return preferred;
     }
-    return initialCachedCatalog.find((model) => model.available)?.id ?? CODEX_LIVE_MODEL.id;
+    return fallbackRealtimeModelId(initialCachedCatalog);
   });
 
   useEffect(() => {
@@ -604,7 +648,7 @@ export function useRealtimeModelSelection(options: {
       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;
+        return fallbackRealtimeModelId(models);
       });
     };
     const cached = readCachedRealtimeModelCatalog(client, workspaceId);
@@ -822,6 +866,7 @@ export function RealtimeVoiceControl(props: {
     props.canStart,
     props.admissionBlocker ?? null,
     selectedModel.label,
+    selectedModel.unavailableCode ?? null,
   );
   const modeOwned = props.snapshot.mode?.state === "active";
   const retryConnection =
@@ -830,6 +875,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" ||
@@ -841,7 +891,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
@@ -858,6 +912,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);
@@ -865,6 +933,7 @@ export function RealtimeVoiceControl(props: {
 
   return (
     <div
+      ref={rootRef}
       role="group"
       aria-label="Realtime voice"
       data-picker-side={props.menuSide ?? "top"}
@@ -946,6 +1015,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"
@@ -1202,7 +1285,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}
@@ -1245,7 +1328,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}
@@ -1333,6 +1416,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 {
@@ -1379,6 +1463,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",
@@ -1388,7 +1479,7 @@ function statusContent(
       if (!modelAvailable) {
         return {
           phase: "unavailable",
-          label: "Voice model unavailable",
+          label: realtimeRefusalLabel(unavailableCode) ?? "Voice model unavailable",
           detail: admissionBlocker ?? "Choose another voice model.",
         };
       }
@@ -1580,6 +1671,7 @@ function writeRealtimeModelPreference(workspaceId: string, model: SessionRealtim
 
 function isRealtimeModel(value: string | null): value is SessionRealtimeModel {
   return (
+    value === "opengeni-azure/gpt-live-1" ||
     value === "gpt-live-1-boulder-alpha" ||
     value === "opengeni-gateway/openai/gpt-realtime-2.1" ||
     value === "opengeni-gateway/openai/gpt-realtime-mini" ||