@ateam-ai-mobile/ui 0.1.5 → 0.1.8

package/src/voice/voiceSession.ts

@@ -0,0 +1,807 @@
+/**
+ * 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,
+  hasDeviceTool,
+  PLATFORM_VOICE_CALLER,
+  type VoiceSessionProvider,
+  type VoiceCaller,
+  type VoiceSnapshot,
+  type VoiceState,
+  type VoiceTranscriptEntry,
+  type VoiceStartOptions,
+  type VoicePersona,
+  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 last device-tool call the model made (name + when), or null. */
+  lastDeviceTool: { name: string; at: 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;
+  /** Per-call persona override ({ name, style }) — sent to the voice page on the
+   *  session URL and declared on POST /session; the server layers it. */
+  persona?: VoicePersona;
+}
+
+const IDLE: InternalState = {
+  callState: 'idle',
+  sessionId: null,
+  error: null,
+  transcript: [],
+  aiPartial: '',
+  userPartial: '',
+  muted: false,
+  userSpeaking: false,
+  lastUserSpeechEndedAt: null,
+  lastDeviceTool: 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;
+
+  /** EVERY start() still in its pre-mount awaits (tool preload, token refresh).
+   *  The session is not 'connecting' yet, so a stop() arriving now would otherwise
+   *  be an idle no-op — and a start would then mount a call for a screen that has
+   *  already gone. A set, not one slot: two concurrent starts must BOTH be
+   *  cancellable. stop() cancels every pending start of its caller (the platform:
+   *  all of them); another plugin's stop cancels none. */
+  private pendingStarts = new Set<{ caller: VoiceCaller; cancelled: boolean }>();
+
+  /**
+   * The device-tool names Core ALLOWED for this voice session — Core's sanitized
+   * allowset, delivered to the phone in a `deviceToolAllowset` message.
+   * Authorization gates against THIS (necessary, alongside the registry's can-do).
+   *
+   * WHY (GPT gate 1, corrected): the phone only PROPOSES its available tools
+   * (sendDeviceToolList); CORE is the session authority and decides which are
+   * accepted (session.device_tools). Freezing the phone's own proposal would let
+   * a tool Core REJECTED still run locally. So the authz set is populated from
+   * Core's accepted set, never from listDeviceTools(). Until Core's set arrives
+   * this is null and every call FAILS CLOSED. Pinned once per session; the live
+   * registry (which drifts via lazy loads / host registration / tenant changes)
+   * never feeds it.
+   */
+  private frozenTools: Set<string> | null = null;
+
+  /** The voice `sessionId` the current allowset is BOUND to. Authorization
+   *  requires it to equal the active session's id (state.sessionId), so a stale
+   *  allowset from a previous/other session is refused. */
+  private frozenSessionId: string | null = null;
+
+  /** A CLEAN call (skills:'none') started by a plugin offers and runs ONLY that
+   *  plugin's own device tools — not other solutions' tools that happen to be
+   *  registered on the same phone. null = every registered tool (a normal call,
+   *  or the platform's). Set by every start(); like `owner`, kept after stop.
+   *  ONE identity: the caller is the TRUSTED manifest pluginId gateVoice stamps,
+   *  and the bundleManager registers a plugin's tools under that same id (never
+   *  the bundle's own short `id`), so exact equality is the whole check. */
+  private toolScope: string | 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();
+    }
+
+    if (opts?.skills === 'none' && opts?.skillSlug) {
+      throw new Error("voice: skills:'none' (a clean call) cannot also hand the mic to a skill (skillSlug).");
+    }
+    const ticket = { caller, cancelled: false };
+    this.pendingStarts.add(ticket);
+
+    // 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.
+    }
+
+    this.pendingStarts.delete(ticket);
+    if (ticket.cancelled) throw new Error('voice: stopped before the session started');
+    // Another start() may have mounted a session while we awaited — attach to it
+    // (or be refused) exactly as the entry checks would have, never mount twice.
+    // (Re-read: the awaits above can change it; the entry checks' narrowing can't.)
+    const after = this.getInternal().callState;
+    if (after === 'connected') {
+      if (!this.canAccess(caller)) throw this.foreignError();
+      return this.realSnapshot();
+    }
+    if (after === 'connecting') {
+      if (!this.canAccess(caller)) throw this.foreignError();
+      return this.waitForConnect();
+    }
+
+    // Idle → this caller becomes the owner of the new session. A NEW session
+    // re-freezes its tool set on the next tool-list request.
+    this.owner = caller;
+    this.toolScope = opts?.skills === 'none' && typeof caller === 'string' ? caller : null;
+    this.frozenTools = null;
+    this.frozenSessionId = null;
+    const skillSlug = opts?.skillSlug;
+    this.setState({
+      callState: 'connecting',
+      error: null,
+      transcript: [],
+      aiPartial: '',
+      userPartial: '',
+      muted: false,
+      mounted: true,
+      skillSlug,
+      persona: opts?.persona,
+      webViewSource: { uri: this.buildUri(skillSlug, opts?.persona, opts?.skills) },
+    });
+    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();
+    // Starts still before their mount: cancel ALL of this caller's (the platform:
+    // everyone's) — another plugin must not be able to abort someone's call.
+    for (const t of [...this.pendingStarts]) {
+      if (caller === PLATFORM_VOICE_CALLER || caller === t.caller) {
+        t.cancelled = true;
+        this.pendingStarts.delete(t);
+      }
+    }
+    this.webView?.injectJavaScript?.('window.hangUp && window.hangUp(); true;');
+    this.rejectPending(new Error('voice: session stopped before it connected'));
+    this.frozenTools = null; // the session's authorized set ends with the session
+    this.frozenSessionId = null;
+    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 channel behind the gated props.voice.observe();
+   * every item stays in the model's context for the call, so a caller sends only
+   * material changes. 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,
+      lastDeviceTool: s.lastDeviceTool,
+      authorizedSessionId: this.frozenSessionId,
+      lastError: s.error,
+    };
+  }
+
+  private foreignSnapshot(): VoiceSnapshot {
+    return {
+      state: 'idle', sessionId: null, muted: false, speaking: false, listening: false,
+      userSpeaking: false, lastUserSpeechEndedAt: null, lastDeviceTool: null,
+      authorizedSessionId: 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, persona?: VoicePersona, skills?: VoiceStartOptions['skills']): string {
+    const token = getToken();
+    const tenant = getTenant();
+    const actorId = getUser()?.actorId || '';
+    const skillParam = skillSlug ? `&skillSlug=${encodeURIComponent(skillSlug)}` : '';
+    // Declared start option, carried on the same URL as tenant/authToken; the
+    // voice page forwards it as POST /session `persona`, where it's sanitized.
+    const p = persona && (persona.name || persona.style)
+      ? { ...(persona.name ? { name: persona.name } : {}), ...(persona.style ? { style: persona.style } : {}) }
+      : null;
+    const personaParam = p ? `&persona=${encodeURIComponent(JSON.stringify(p))}` : '';
+    // Clean call: only the one reduce-only value is ever sent; anything else is
+    // not a request at all (the server accepts only 'none' too).
+    const skillsParam = skills === 'none' ? '&skills=none' : '';
+    return `${getVoiceApiUrl()}/app?mode=mini&embedded=rn&authToken=${encodeURIComponent(token || '')}&tenant=${encodeURIComponent(tenant)}&actorId=${encodeURIComponent(actorId)}${skillParam}${personaParam}${skillsParam}`;
+  }
+
+  /** 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;
+      }
+      // CORE's ALLOWSET for this session — what the model may ASK for. Core sends
+      // it (even empty, on purpose) at session start. It is a NECESSARY gate, not
+      // the whole story: a call must be in the allowset AND the device must
+      // actually have the tool (the registry check inside callDeviceTool) — Core
+      // says what may be asked, the device decides what it will do.
+      //
+      // Origin-checked (only the voice app may set it) and pinned ONCE per session
+      // (a later message cannot widen it). An EMPTY allowset (arrived) refuses
+      // everything but is distinct from NEVER-arrived (frozenTools stays null);
+      // both fail closed here — we never fall back to the phone's own registry,
+      // which is the seam this closes.
+      case 'deviceToolAllowset': {
+        const sender = originOf(event?.nativeEvent?.url);
+        const expected = originOf(getVoiceApiUrl());
+        if (!sender || !expected || sender !== expected) break;
+        // Bind the allowset to its sessionId. Pin (or REPLACE for a different
+        // session) but never WIDEN within the same session — a second allowset
+        // for the same sessionId is ignored. Requires a string sessionId, so an
+        // allowset without one never authorizes anything (fail closed).
+        if (Array.isArray(data.tools) && typeof data.sessionId === 'string' && data.sessionId !== this.frozenSessionId) {
+          this.frozenTools = new Set(data.tools.filter((n: unknown) => typeof n === 'string'));
+          this.frozenSessionId = data.sessionId;
+        }
+        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;
+        }
+        if (data.name) this.setState({ lastDeviceTool: { name: data.name, at: Date.now() } });
+        // AUTHORIZATION against the FROZEN session set, not the live registry
+        // (GPT gate 1). A tool that appeared after connect — the drift case — is
+        // refused here, before execution, even if it is registered right now.
+        if (!this.isToolAuthorized(data.name)) {
+          // Both refuse (fail closed), but they are DIFFERENT answers to the model:
+          // NOT-YET-TOLD (Core's allowset hasn't arrived) is transient — retry;
+          // TOLD-AND-DENIED (allowset present, tool not in it / wrong session /
+          // unregistered) is final. Same refusal, different sentence.
+          const notReady = this.frozenTools === null;
+          console.warn(`[voiceSession] REFUSED "${data.name}" — ${notReady ? 'allowset not received yet' : 'not authorized for this session'}`);
+          this.postDeviceToolRefusal(data.correlationId, data.name, notReady);
+          break;
+        }
+        void this.runDeviceTool(data);
+        break;
+      }
+    }
+  }
+
+  /**
+   * Final authorization = Core's frozen allowset ∩ the current valid local
+   * registry, bound to the ACTIVE session. All must hold:
+   *  - a Core allowset arrived and is bound to THIS session (frozenSessionId ===
+   *    the active state.sessionId) — a missing or stale/wrong-session allowset
+   *    fails closed;
+   *  - the tool is IN that allowset (Core approved it); AND
+   *  - the tool is STILL registered locally right now (removed-after-approval is
+   *    refused; a lazily-added tool Core never approved is refused) — and, on a
+   *    clean call, registered by the call's owner.
+   * No fallback to the live registry alone, ever.
+   */
+  private isToolAuthorized(name: unknown): boolean {
+    if (typeof name !== 'string') return false;
+    if (this.frozenTools === null || this.frozenSessionId === null) return false;
+    if (this.frozenSessionId !== this.state.sessionId) return false;
+    if (!this.frozenTools.has(name)) return false;
+    return hasDeviceTool(name, this.toolScope ?? undefined); // still registered locally right now
+  }
+
+  /** Tell the mini-app the call was refused — a stated reason, never a silent drop.
+   *  `notReady` distinguishes a transient "allowset not here yet" (retry) from a
+   *  final "not allowed in this session". */
+  private postDeviceToolRefusal(correlationId: string, name: string, notReady: boolean): void {
+    const payload = notReady
+      ? {
+          correlationId, ok: false, reason: 'not_ready',
+          error: 'The voice session is still starting up — its tool allowset has not arrived yet. Try again in a moment.',
+        }
+      : {
+          correlationId, ok: false, reason: 'not_authorized',
+          error: `"${name}" is not available in this voice session.`,
+        };
+    this.webView?.injectJavaScript?.(
+      `window.__adasDeviceToolResult && window.__adasDeviceToolResult(${JSON.stringify(
+        JSON.stringify(payload),
+      )}); true;`,
+    );
+  }
+
+  /** PROPOSE the phone's available tools — this is an offer to Core, not the
+   *  authorization set. Core sanitizes it and returns the accepted set in a
+   *  `deviceToolAllowset` message, which is what actually gates execution. */
+  private sendDeviceToolList(correlationId: string): void {
+    const scope = this.toolScope;
+    const tools = listDeviceTools().filter(t => scope === null || t.pluginId === scope).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.toolScope = null;
+    this.pendingStarts.clear();
+    this.frozenTools = null;
+    this.frozenSessionId = null;
+    this.listeners.clear();
+    this.webView = null;
+  }
+}
+
+/** The one live session. Handed to setVoiceProvider(voiceSession) at startup. */
+export const voiceSession = new VoiceSessionManager();