@ateam-ai-mobile/ui 0.1.5 → 0.1.7

package/src/voice/voiceSession.ts

@@ -0,0 +1,628 @@
+/**
+ * voiceSession — the ONE live voice session, headless and app-root-owned.
+ *
+ * WHY THIS EXISTS. The session used to live inside `useVoiceCall`, whose WebView
+ * was rendered by VoiceCallSheet. Unmount the sheet and the WebView unmounted
+ * with it, so the session died — not by design, just by where the WebView lived.
+ * That made the built-in screen the ONLY way to hold a live loop, exactly the
+ * state the camera was in before sensing and preview were split.
+ *
+ * The fix is the same one VisionStreamHost applied to the camera: move the thing
+ * that must stay alive to the app root, and make every surface a READER of it.
+ * This module is that thing — a singleton that owns session state and drives the
+ * WebView; `VoiceSessionHost` mounts the (offscreen) WebView bound to it once, at
+ * the root; `useVoiceCall` / `props.voice` are views onto it.
+ *
+ * It is the provider handed to `setVoiceProvider` (plugin-runtime), so a plugin's
+ * gated `props.voice` and the built-in sheet drive the SAME session — one phone,
+ * one mic, one Realtime loop, one bill (spec invariant 2).
+ *
+ * TRUST. The device-tool channel (origin-checked postMessage) is preserved
+ * verbatim from the hook: the model's tool calls arrive on THIS phone over the
+ * WebView's own WebRTC, and only a message from the voice app's own origin may
+ * drive the device. `prompt()` is an AGENT turn, never forged user speech, and it
+ * cannot reach the WebView beyond that one injected call.
+ */
+import { getVoiceApiUrl, getToken, getTenant, getUser, refreshToken } from '@ateam-ai-mobile/core';
+import {
+  callDeviceTool,
+  ensureDeviceToolsLoaded,
+  listDeviceTools,
+  PLATFORM_VOICE_CALLER,
+  type VoiceSessionProvider,
+  type VoiceCaller,
+  type VoiceSnapshot,
+  type VoiceState,
+  type VoiceTranscriptEntry,
+  type VoiceStartOptions,
+  type VoiceEvent,
+  type VoiceSubscription,
+} from '@ateam-ai-mobile/plugin-runtime';
+
+// Re-export the transcript/state shapes under their historical names so existing
+// importers (useVoiceCall, VoiceCallSheet) keep compiling. The canonical
+// definitions live in plugin-runtime (the layer both ui and plugins depend on).
+export type CallState = VoiceState;
+export type TranscriptEntry = VoiceTranscriptEntry;
+
+/** How long to wait for the WebView to reach 'connected' before start() rejects.
+ *  A hung promise (e.g. no VoiceSessionHost mounted) is worse than a clear error. */
+const CONNECT_TIMEOUT_MS = 30_000;
+
+/**
+ * The voice WebView bakes the JWT into its URL once at mount and never refreshes
+ * it (unlike the SDK REST client, which self-heals on 401). Refresh a stale/near-
+ * expiry token BEFORE the WebView mounts so it gets a fresh one. Cheap unless
+ * actually near expiry (decoded locally, no network unless needed).
+ */
+const TOKEN_REFRESH_SKEW_MS = 90_000;
+function tokenNeedsRefresh(token: string | null): boolean {
+  if (!token) return true;
+  try {
+    const payloadB64 = token.split('.')[1];
+    const padded = payloadB64.replace(/-/g, '+').replace(/_/g, '/');
+    const json = typeof atob === 'function'
+      ? atob(padded)
+      : Buffer.from(padded, 'base64').toString('utf8');
+    const exp = JSON.parse(json)?.exp;
+    if (typeof exp !== 'number') return false;
+    return Date.now() >= exp * 1000 - TOKEN_REFRESH_SKEW_MS;
+  } catch {
+    return false;
+  }
+}
+
+// Installed BEFORE the voice app loads — captures every audio track that could
+// reach the peer connection so setMuted can flip enabled=false on all of them,
+// however the voice app obtained the track. (Verbatim from useVoiceCall.)
+export const INJECT_TRACK_HOOK = `
+(function() {
+  if (window._adaTrackHookInstalled) return;
+  window._adaTrackHookInstalled = true;
+  window._allAudioTracks = [];
+  window._adaPeerConnections = [];
+
+  function track(t) {
+    if (t && t.kind === 'audio' && window._allAudioTracks.indexOf(t) === -1) {
+      window._allAudioTracks.push(t);
+    }
+  }
+
+  try {
+    if (navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
+      const origGUM = navigator.mediaDevices.getUserMedia.bind(navigator.mediaDevices);
+      navigator.mediaDevices.getUserMedia = async function(constraints) {
+        const stream = await origGUM(constraints);
+        if (constraints && constraints.audio) {
+          try { stream.getAudioTracks().forEach(track); } catch (e) {}
+        }
+        return stream;
+      };
+    }
+  } catch (e) {}
+
+  try {
+    if (window.RTCPeerConnection) {
+      const origPC = window.RTCPeerConnection;
+      const origAddTrack = origPC.prototype.addTrack;
+      const origAddStream = origPC.prototype.addStream;
+      const origAddTransceiver = origPC.prototype.addTransceiver;
+
+      origPC.prototype.addTrack = function(t) {
+        if (t && t.kind === 'audio') track(t);
+        return origAddTrack.apply(this, arguments);
+      };
+      if (origAddStream) {
+        origPC.prototype.addStream = function(stream) {
+          try { stream.getAudioTracks().forEach(track); } catch (e) {}
+          return origAddStream.apply(this, arguments);
+        };
+      }
+      if (origAddTransceiver) {
+        origPC.prototype.addTransceiver = function(arg) {
+          if (arg && arg.kind === undefined && arg.track && arg.track.kind === 'audio') {
+            track(arg.track);
+          }
+          const tx = origAddTransceiver.apply(this, arguments);
+          try {
+            if (tx && tx.sender && tx.sender.track && tx.sender.track.kind === 'audio') track(tx.sender.track);
+          } catch (e) {}
+          return tx;
+        };
+      }
+    }
+  } catch (e) {}
+
+  window._adaSetMuted = function(muted) {
+    let n = 0;
+    if (Array.isArray(window._allAudioTracks)) {
+      window._allAudioTracks.forEach(function(t) {
+        try { t.enabled = !muted; n++; } catch (e) {}
+      });
+    }
+    return n;
+  };
+})(); true;
+`;
+
+const buildMuteScript = (muted: boolean) => `
+(function(muted) {
+  if (typeof window.setMuted === 'function') { window.setMuted(muted); }
+  let n = 0;
+  if (typeof window._adaSetMuted === 'function') {
+    n = window._adaSetMuted(muted);
+  }
+  if (n === 0 && Array.isArray(window._allAudioTracks)) {
+    window._allAudioTracks.forEach(function(t) {
+      try { t.enabled = !muted; n++; } catch (e) {}
+    });
+  }
+  console.log('[ada-mute]', muted ? 'MUTED' : 'UNMUTED', 'tracks=', n);
+})(${muted}); true;
+`;
+
+/**
+ * The agent-initiated turn — the guide speaking first. Calls the voice app's
+ * `__adasAgentTurn(input)`, which must issue a Realtime `response.create` into
+ * the ALREADY-OPEN session (Core owns that function; see the spec §4.2).
+ *
+ * REFUSE, DON'T NO-OP: an undefined function called through injectJavaScript
+ * fails SILENTLY in the WebView, and the author sees a guide that simply never
+ * speaks first — indistinguishable from a model that chose silence. So if the
+ * hook is absent (an older voice page), we post a notice back that surfaces as
+ * `lastError`, without ending the session.
+ */
+const buildAgentTurnScript = (input: string) => `
+(function(input) {
+  if (typeof window.__adasAgentTurn === 'function') {
+    try { window.__adasAgentTurn(input); }
+    catch (e) {
+      window.ReactNativeWebView && window.ReactNativeWebView.postMessage(JSON.stringify({
+        type: 'agentTurnFailed', message: String(e && e.message || e),
+      }));
+    }
+  } else if (window.ReactNativeWebView) {
+    window.ReactNativeWebView.postMessage(JSON.stringify({
+      type: 'agentTurnUnsupported',
+      message: 'voice app does not support agent turns (__adasAgentTurn missing) — update the voice page',
+    }));
+  }
+})(${JSON.stringify(input)}); true;
+`;
+
+/**
+ * A silent OBSERVATION — tell the model something without asking it to speak.
+ * Calls the voice app's `__adasObserve(text)`, which adds a `system` conversation
+ * item and does NOT request a response (Core owns that function). This is the
+ * cheap channel for a continuous stream — e.g. what the camera sees while the
+ * user walks — as opposed to `__adasAgentTurn`, which asks the model to speak.
+ *
+ * Same refuse-don't-no-op contract as the agent turn: a missing hook posts a
+ * notice back rather than failing silently.
+ */
+const buildObserveScript = (text: string) => `
+(function(text) {
+  if (typeof window.__adasObserve === 'function') {
+    try { window.__adasObserve(text); }
+    catch (e) {
+      window.ReactNativeWebView && window.ReactNativeWebView.postMessage(JSON.stringify({
+        type: 'observeFailed', message: String(e && e.message || e),
+      }));
+    }
+  } else if (window.ReactNativeWebView) {
+    window.ReactNativeWebView.postMessage(JSON.stringify({
+      type: 'observeUnsupported',
+      message: 'voice app does not support observe (__adasObserve missing) — update the voice page',
+    }));
+  }
+})(${JSON.stringify(text)}); true;
+`;
+
+/** Origin of a URL, or null if it can't be parsed. */
+function originOf(url?: string | null): string | null {
+  if (!url) return null;
+  const m = /^([a-z][a-z0-9+.-]*:\/\/[^/?#]+)/i.exec(url);
+  return m ? m[1].toLowerCase() : null;
+}
+
+interface InternalState {
+  callState: CallState;
+  sessionId: string | null;
+  error: string | null;
+  transcript: TranscriptEntry[];
+  aiPartial: string;
+  userPartial: string;
+  muted: boolean;
+  /** User VAD, from the mini-app's speechActivity events. */
+  userSpeaking: boolean;
+  /** Epoch ms of the last speaking:false, or null before the first utterance. */
+  lastUserSpeechEndedAt: number | null;
+  /** The WebView should be mounted (a session is wanted / live). */
+  mounted: boolean;
+  /** The WebView source, computed ONCE at start() so state changes (transcript,
+   *  partials) never remount the WebView and drop the session. */
+  webViewSource: { uri: string } | null;
+  skillSlug?: string;
+}
+
+const IDLE: InternalState = {
+  callState: 'idle',
+  sessionId: null,
+  error: null,
+  transcript: [],
+  aiPartial: '',
+  userPartial: '',
+  muted: false,
+  userSpeaking: false,
+  lastUserSpeechEndedAt: null,
+  mounted: false,
+  webViewSource: null,
+  skillSlug: undefined,
+};
+
+type Pending = { resolve: (s: VoiceSnapshot) => void; reject: (e: Error) => void; timer: any };
+
+class VoiceSessionManager implements VoiceSessionProvider {
+  private state: InternalState = { ...IDLE };
+  private listeners = new Set<(e: VoiceEvent) => void>();
+  private webView: { injectJavaScript?: (js: string) => void } | null = null;
+  private pending: Pending[] = [];
+  /**
+   * WHO owns the one physical session. Set to the caller that started it from
+   * idle (a plugin's pluginId, or the PLATFORM symbol for the built-in sheet),
+   * and kept after stop until the next start reassigns it — so a plugin can read
+   * its own just-ended transcript but another plugin never can.
+   *
+   * ISOLATION (GPT blocker on 8881225): every access is scoped through this. A
+   * different plugin must not read, control, or attach to another plugin's live
+   * conversation just because it declared voice.
+   */
+  private owner: VoiceCaller | null = null;
+
+  /** The platform (built-in sheet, mic indicator, session host) sees and
+   *  controls any session — it is the user's own surface. A plugin caller may
+   *  only touch a session it owns. */
+  private canAccess(caller: VoiceCaller): boolean {
+    return caller === PLATFORM_VOICE_CALLER || this.owner === caller;
+  }
+
+  private foreignError(): Error {
+    const err: any = new Error(
+      'voice: another solution is using the microphone — one live session per device.',
+    );
+    err.code = 'RESTRICTED';
+    return err;
+  }
+
+  // ── Host wiring (used only by VoiceSessionHost) ──────────────
+
+  /** The offscreen WebView sets its ref here so the session can inject into it. */
+  setWebView(ref: { injectJavaScript?: (js: string) => void } | null): void {
+    this.webView = ref;
+  }
+
+  /** Whole state — the host reads `mounted` + `webViewSource` to decide what to
+   *  render, and every reader derives its snapshot from this. */
+  getInternal(): Readonly<InternalState> {
+    return this.state;
+  }
+
+  readonly injectedTrackHook = INJECT_TRACK_HOOK;
+
+  // ── VoiceAPI (what props.voice and useVoiceCall call) ────────
+
+  async start(opts?: VoiceStartOptions, caller: VoiceCaller = PLATFORM_VOICE_CALLER): Promise<VoiceSnapshot> {
+    // Single session: if one is live or connecting, ATTACH — never a second
+    // Realtime loop (invariant 2). But ONLY the owner (or the platform) may
+    // attach; a different plugin that declared voice is REFUSED, not silently
+    // joined to a conversation it does not own (GPT isolation blocker). A
+    // different skillSlug does NOT restart it.
+    if (this.state.callState === 'connected') {
+      if (!this.canAccess(caller)) throw this.foreignError();
+      return this.realSnapshot();
+    }
+    if (this.state.callState === 'connecting') {
+      if (!this.canAccess(caller)) throw this.foreignError();
+      return this.waitForConnect();
+    }
+
+    // Device tools only exist once their bundle is evaluated; a user who goes
+    // straight to voice can otherwise ask for a tool the phone never loaded.
+    // Best-effort — a failure just means no device tools this time.
+    try {
+      await ensureDeviceToolsLoaded();
+    } catch (e: any) {
+      console.warn('[voiceSession] device tool preload failed:', e?.message || String(e));
+    }
+
+    // Hand the WebView a FRESH token before it mounts (it never refreshes once
+    // mounted). Only pays a round-trip when near expiry.
+    try {
+      if (tokenNeedsRefresh(getToken())) await refreshToken();
+    } catch {
+      // Proceed with whatever token we have; voice-backend surfaces a clean auth
+      // error rather than us blocking the call.
+    }
+
+    // Idle → this caller becomes the owner of the new session.
+    this.owner = caller;
+    const skillSlug = opts?.skillSlug;
+    this.setState({
+      callState: 'connecting',
+      error: null,
+      transcript: [],
+      aiPartial: '',
+      userPartial: '',
+      muted: false,
+      mounted: true,
+      skillSlug,
+      webViewSource: { uri: this.buildUri(skillSlug) },
+    });
+    return this.waitForConnect();
+  }
+
+  stop(caller: VoiceCaller = PLATFORM_VOICE_CALLER): void {
+    // A plugin may not hang up another solution's live call. (Idle stop is a
+    // harmless no-op for anyone.)
+    if (this.state.callState !== 'idle' && !this.canAccess(caller)) throw this.foreignError();
+    this.webView?.injectJavaScript?.('window.hangUp && window.hangUp(); true;');
+    this.rejectPending(new Error('voice: session stopped before it connected'));
+    this.setState({
+      ...IDLE,
+      // keep the transcript of the call that just ended for any reader still up
+      transcript: this.state.transcript,
+    });
+    // owner is intentionally KEPT (not reset to null): the next start() from
+    // idle reassigns it, and until then the owner can still read its own
+    // just-ended transcript while others cannot.
+  }
+
+  setMuted(muted: boolean, caller: VoiceCaller = PLATFORM_VOICE_CALLER): void {
+    if (this.state.callState !== 'idle' && !this.canAccess(caller)) throw this.foreignError();
+    this.webView?.injectJavaScript?.(buildMuteScript(muted));
+    this.setState({ muted });
+  }
+
+  prompt(input: string, caller: VoiceCaller = PLATFORM_VOICE_CALLER): void {
+    if (this.state.callState !== 'connected') {
+      throw new Error('voice: session is not connected — call start() and await it before prompt().');
+    }
+    if (!this.canAccess(caller)) throw this.foreignError();
+    this.webView?.injectJavaScript?.(buildAgentTurnScript(input));
+  }
+
+  /**
+   * Stream a silent observation into the live session — tell the model without
+   * asking it to speak. The cheap, high-frequency channel (safe once or twice a
+   * second) behind a future props.voice.observe(); today the host uses it to run
+   * the real-device stream proof (VOICE_RT_STREAM_DEVICE_PROOF) before the gated
+   * plugin API is added. Owner-scoped like every other control.
+   */
+  observe(text: string, caller: VoiceCaller = PLATFORM_VOICE_CALLER): void {
+    if (this.state.callState !== 'connected') {
+      throw new Error('voice: session is not connected — observe() needs a live session.');
+    }
+    if (!this.canAccess(caller)) throw this.foreignError();
+    this.webView?.injectJavaScript?.(buildObserveScript(text));
+  }
+
+  getSnapshot(caller: VoiceCaller = PLATFORM_VOICE_CALLER): VoiceSnapshot {
+    // A non-owner sees "you have no session" — which is TRUE for it — and learns
+    // nothing about the conversation another solution is holding. This is not a
+    // fake idle (invariant 6 is about an UNDECLARED plugin): a declared plugin
+    // that does not own the live session genuinely has none of its own.
+    return this.canAccess(caller) ? this.realSnapshot() : this.foreignSnapshot();
+  }
+
+  private realSnapshot(): VoiceSnapshot {
+    const s = this.state;
+    return {
+      state: s.callState,
+      sessionId: s.sessionId,
+      muted: s.muted,
+      speaking: !!s.aiPartial,
+      listening: !!s.userPartial,
+      userSpeaking: s.userSpeaking,
+      lastUserSpeechEndedAt: s.lastUserSpeechEndedAt,
+      lastError: s.error,
+    };
+  }
+
+  private foreignSnapshot(): VoiceSnapshot {
+    return {
+      state: 'idle', sessionId: null, muted: false, speaking: false, listening: false,
+      userSpeaking: false, lastUserSpeechEndedAt: null, lastError: null,
+    };
+  }
+
+  subscribe(cb: (event: VoiceEvent) => void, caller: VoiceCaller = PLATFORM_VOICE_CALLER): VoiceSubscription {
+    // Scope the stream: a non-owner's callback never fires (it has no session to
+    // observe), so a plugin cannot watch another solution's conversation by
+    // pre-registering a subscription before/while it is live. When this caller
+    // later owns a session, canAccess flips true and its callback starts firing.
+    const wrapped = (event: VoiceEvent) => { if (this.canAccess(caller)) cb(event); };
+    this.listeners.add(wrapped);
+    return { unsubscribe: () => { this.listeners.delete(wrapped); } };
+  }
+
+  transcript(caller: VoiceCaller = PLATFORM_VOICE_CALLER): TranscriptEntry[] {
+    return this.canAccess(caller) ? this.state.transcript.slice() : [];
+  }
+
+  // ── WebView plumbing ─────────────────────────────────────────
+
+  private buildUri(skillSlug?: string): string {
+    const token = getToken();
+    const tenant = getTenant();
+    const actorId = getUser()?.actorId || '';
+    const skillParam = skillSlug ? `&skillSlug=${encodeURIComponent(skillSlug)}` : '';
+    return `${getVoiceApiUrl()}/app?mode=mini&embedded=rn&authToken=${encodeURIComponent(token || '')}&tenant=${encodeURIComponent(tenant)}&actorId=${encodeURIComponent(actorId)}${skillParam}`;
+  }
+
+  /** Handle a postMessage from the WebView. `event` is the RN WebView event. */
+  handleMessage(event: any): void {
+    let data: any;
+    try {
+      data = JSON.parse(event.nativeEvent.data);
+    } catch {
+      return;
+    }
+    switch (data.type) {
+      case 'callState':
+      case 'call-state':
+        if (data.state) this.setState({ callState: data.state });
+        if (data.sessionId) this.setState({ sessionId: data.sessionId });
+        if (data.error) this.setState({ error: data.error });
+        if (data.state === 'connected') this.resolvePending();
+        if (data.state === 'error') this.rejectPending(new Error(data.error || 'voice: connection error'));
+        break;
+      case 'transcript':
+        this.appendTranscript({ role: data.role, text: data.text, ts: Date.now() });
+        break;
+      case 'aiPartial':
+        this.setState({ aiPartial: data.text });
+        break;
+      case 'userPartial':
+        this.setState({ userPartial: data.text });
+        break;
+      case 'clearPartials':
+        this.setState({ aiPartial: '', userPartial: '' });
+        break;
+      // User VAD from the mini-app. `at` is when it happened; on speaking:false
+      // we stamp lastUserSpeechEndedAt so a solution can gate "speak after N s of
+      // silence" on the first real stop, never before the user has spoken.
+      case 'speechActivity': {
+        const speaking = !!data.speaking;
+        const at = typeof data.at === 'number' ? data.at : Date.now();
+        this.setState(
+          speaking
+            ? { userSpeaking: true }
+            : { userSpeaking: false, lastUserSpeechEndedAt: at },
+        );
+        break;
+      }
+      case 'error':
+        this.setState({ error: data.message, callState: 'error' });
+        this.rejectPending(new Error(data.message || 'voice: error'));
+        break;
+      // A proactive turn couldn't run (older voice page / hook threw). NON-FATAL:
+      // the session stays live; we only surface why the guide didn't speak.
+      case 'agentTurnUnsupported':
+      case 'agentTurnFailed':
+      case 'observeUnsupported':
+      case 'observeFailed':
+        this.setState({ error: data.message || 'voice: channel notice' });
+        break;
+      // Device tools — executed locally, origin-checked. The model's function
+      // call already arrived on this phone; only the voice app's own origin may
+      // drive the camera/GPS.
+      case 'device-tool-list': {
+        const listSender = originOf(event?.nativeEvent?.url);
+        const listExpected = originOf(getVoiceApiUrl());
+        if (!listSender || !listExpected || listSender !== listExpected) break;
+        this.sendDeviceToolList(data.correlationId);
+        break;
+      }
+      case 'device-tool-call': {
+        const sender = originOf(event?.nativeEvent?.url);
+        const expected = originOf(getVoiceApiUrl());
+        if (!sender || !expected || sender !== expected) {
+          console.warn(`[voiceSession] REFUSED device tool call from "${sender || 'unknown origin'}" (expected "${expected}")`);
+          break;
+        }
+        void this.runDeviceTool(data);
+        break;
+      }
+    }
+  }
+
+  /** Answer "what device tools do you have?" — the client is the authority. */
+  private sendDeviceToolList(correlationId: string): void {
+    const tools = listDeviceTools().map(t => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.input_schema,
+    }));
+    this.webView?.injectJavaScript?.(
+      `window.__adasDeviceToolResult && window.__adasDeviceToolResult(${JSON.stringify(
+        JSON.stringify({ correlationId, ok: true, tools }),
+      )}); true;`,
+    );
+  }
+
+  /** Run a device tool and post the outcome back into the WebView. */
+  private async runDeviceTool(data: any): Promise<void> {
+    const { correlationId, name, args, timeoutMs } = data || {};
+    if (!correlationId || typeof name !== 'string') return;
+    let payload: any;
+    try {
+      const outcome = await callDeviceTool(name, args || {}, { timeoutMs });
+      payload = outcome.ok
+        ? { correlationId, ok: true, result: outcome.result }
+        : { correlationId, ok: false, error: outcome.error, reason: outcome.reason };
+    } catch (err: any) {
+      payload = { correlationId, ok: false, reason: 'failed', error: err?.message || String(err) };
+    }
+    this.webView?.injectJavaScript?.(
+      `window.__adasDeviceToolResult && window.__adasDeviceToolResult(${JSON.stringify(
+        JSON.stringify(payload),
+      )}); true;`,
+    );
+  }
+
+  // ── internals ────────────────────────────────────────────────
+
+  private setState(partial: Partial<InternalState>): void {
+    this.state = { ...this.state, ...partial };
+    this.emit({ type: 'state' });
+  }
+
+  private appendTranscript(entry: TranscriptEntry): void {
+    this.state = { ...this.state, transcript: [...this.state.transcript, entry] };
+    this.emit({ type: 'transcript' });
+  }
+
+  private emit(event: VoiceEvent): void {
+    for (const cb of this.listeners) {
+      try { cb(event); } catch (e) { console.warn('[voiceSession] listener threw', e); }
+    }
+  }
+
+  private waitForConnect(): Promise<VoiceSnapshot> {
+    return new Promise<VoiceSnapshot>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending = this.pending.filter(p => p.timer !== timer);
+        reject(new Error('voice: timed out waiting to connect (is VoiceSessionHost mounted?)'));
+      }, CONNECT_TIMEOUT_MS);
+      this.pending.push({ resolve, reject, timer });
+    });
+  }
+
+  private resolvePending(): void {
+    // Everyone still waiting on connect already passed the access check in
+    // start(), so they get the real snapshot.
+    const snap = this.realSnapshot();
+    const waiting = this.pending;
+    this.pending = [];
+    for (const p of waiting) { clearTimeout(p.timer); p.resolve(snap); }
+  }
+
+  private rejectPending(err: Error): void {
+    const waiting = this.pending;
+    this.pending = [];
+    for (const p of waiting) { clearTimeout(p.timer); p.reject(err); }
+  }
+
+  /** TEST ONLY: reset the singleton to a clean idle state (mirrors the
+   *  __resetSessionSyncForTest precedent). Not part of any surface. */
+  __resetForTest(): void {
+    this.rejectPending(new Error('voice: reset'));
+    this.state = { ...IDLE };
+    this.owner = null;
+    this.listeners.clear();
+    this.webView = null;
+  }
+}
+
+/** The one live session. Handed to setVoiceProvider(voiceSession) at startup. */
+export const voiceSession = new VoiceSessionManager();