@athenaintel/react 0.41.2 → 0.42.1

package/dist/agent-runtime/src/use-deep-agent-voice.js

@@ -0,0 +1,999 @@
+import { useStatewireSendCommand, useStatewireState } from "@assistant-ui/react-statewire";
+import { useRef, useCallback, useState, useEffect, useMemo } from "react";
+import { statewireRejectionPayload } from "./errors.js";
+import { readDeepAgentStreamValues, isDeepAgentStateHydrated } from "./statewire-state.js";
+const readSendFailure = (error) => {
+  const failure = error == null ? void 0 : error.failure;
+  if (failure === null || typeof failure !== "object") return null;
+  return typeof failure.fate === "string" ? failure : null;
+};
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+class VoiceAnswerTimeoutError extends Error {
+  constructor() {
+    super("The voice session did not answer in time");
+    this.name = "VoiceAnswerTimeoutError";
+  }
+}
+const classifyVoiceStartError = (error) => {
+  if (error instanceof VoiceAnswerTimeoutError) {
+    return { kind: "answer_timeout", message: error.message };
+  }
+  const failure = readSendFailure(error);
+  if (failure === null) return { kind: "unknown", message: errorMessage(error) };
+  if (failure.fate === "rejected") {
+    const payload = failure.payload;
+    const detail = payload == null ? void 0 : payload.detail;
+    const reason = typeof (payload == null ? void 0 : payload.reason) === "string" ? payload.reason : void 0;
+    const detailCode = typeof (detail == null ? void 0 : detail.code) === "string" ? detail.code : void 0;
+    const detailMessage = typeof (detail == null ? void 0 : detail.message) === "string" ? detail.message : void 0;
+    const code = reason ?? detailCode ?? failure.code;
+    const status = typeof (payload == null ? void 0 : payload.status) === "number" ? payload.status : void 0;
+    return {
+      kind: "server_rejected",
+      message: failure.message ?? detailMessage ?? errorMessage(error),
+      ...code !== void 0 && { code },
+      ...status !== void 0 && { status }
+    };
+  }
+  return {
+    kind: "command_failed",
+    message: failure.message ?? errorMessage(error),
+    fate: failure.fate,
+    ...failure.cause !== void 0 && failure.cause !== "server" && { reason: failure.cause }
+  };
+};
+class VoiceNoAnswerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VoiceNoAnswerError";
+  }
+}
+const parseVoiceLiveKitAnswer = (answer) => {
+  if (!answer.startsWith(VOICE_LIVEKIT_ANSWER_PREFIX)) {
+    throw new VoiceNoAnswerError("voice/start returned no voice room");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(answer.slice(VOICE_LIVEKIT_ANSWER_PREFIX.length));
+  } catch {
+    throw new VoiceNoAnswerError("voice/start returned a malformed voice room");
+  }
+  const record = parsed ?? null;
+  const serverUrl = record == null ? void 0 : record.serverUrl;
+  const token = record == null ? void 0 : record.token;
+  const roomName = record == null ? void 0 : record.roomName;
+  if (typeof serverUrl !== "string" || serverUrl === "" || typeof token !== "string" || token === "" || typeof roomName !== "string" || roomName === "") {
+    throw new VoiceNoAnswerError("voice/start returned an incomplete voice room");
+  }
+  return { serverUrl, token, roomName };
+};
+const classifyStartFailure = (error, stage) => {
+  const message = errorMessage(error);
+  switch (stage) {
+    case "preflight":
+      return { kind: "unsupported", stage, message };
+    case "audio-session":
+      return { kind: "audio_session", stage, message };
+    case "capture":
+      return {
+        kind: isMicrophoneDenied(error) ? "microphone_denied" : "capture_failed",
+        stage,
+        message
+      };
+    case "offer":
+      return { kind: "offer_failed", stage, message };
+    case "negotiate":
+      return { ...classifyVoiceStartError(error), stage };
+    case "answer":
+      return {
+        kind: error instanceof VoiceNoAnswerError ? "no_answer" : "answer_failed",
+        stage,
+        message
+      };
+    case "relay":
+      return { kind: "relay_failed", stage, message };
+    case "room":
+      return {
+        kind: isMicrophoneDenied(error) ? "microphone_denied" : "room_failed",
+        stage,
+        message
+      };
+    default:
+      return { kind: "unknown", stage, message };
+  }
+};
+const isMicrophoneDenied = (error) => {
+  const name = error == null ? void 0 : error.name;
+  if (name === "SecurityError" || name === "NotAllowedError" || name === "PermissionDeniedError") {
+    return true;
+  }
+  return /permission|denied|not allowed/i.test(errorMessage(error));
+};
+const describeVoiceFailure = (failure) => {
+  switch (failure.kind) {
+    case "microphone_denied":
+      return "Microphone access is blocked. Allow the microphone for Athena and try again.";
+    case "unsupported":
+      return "Voice mode is not available in this environment.";
+    case "audio_session":
+      return `The audio session could not start: ${failure.message}`;
+    case "answer_timeout":
+      return "The voice session did not answer in time. Check your connection and try again.";
+    case "room_failed":
+      return "The voice room could not be joined. Check your connection and try again.";
+    case "media_lost":
+      return "The voice connection was lost. Start voice again to continue.";
+    case "server_rejected":
+      if (failure.code === "voice-active") {
+        return "A voice session is already live on another device or tab. End it there first.";
+      }
+      if (failure.code === "voice-not-enabled") {
+        return "Voice mode is not enabled for this workspace.";
+      }
+      return failure.message;
+    default:
+      return failure.message;
+  }
+};
+const VOICE_WEBSOCKET_OFFER = "athena-voice-transport:websocket/v1";
+const VOICE_RELAY_ANSWER_PREFIX = "athena-voice-relay:";
+const VOICE_RELAY_SAMPLE_RATE = 24e3;
+const VOICE_LIVEKIT_OFFER = "athena-voice-transport:livekit/v1";
+const VOICE_LIVEKIT_ANSWER_PREFIX = "athena-voice-livekit:";
+const VOICE_MODEL_PROVIDERS = /* @__PURE__ */ new Set(["openai_live", "google"]);
+const parseVoiceModelOptions = (value) => {
+  if (!Array.isArray(value)) return null;
+  const options = [];
+  for (const entry of value) {
+    if (entry === null || typeof entry !== "object") continue;
+    const { id, label, provider, enabled, description } = entry;
+    if (typeof id !== "string" || id === "" || typeof label !== "string" || typeof provider !== "string" || !VOICE_MODEL_PROVIDERS.has(provider) || typeof enabled !== "boolean" || typeof description !== "string") {
+      continue;
+    }
+    options.push({
+      id,
+      label,
+      provider,
+      enabled,
+      description
+    });
+  }
+  return options;
+};
+const sameVoiceModelOptions = (a, b) => a.length === b.length && a.every((option, index) => {
+  const other = b[index];
+  return other !== void 0 && option.id === other.id && option.label === other.label && option.provider === other.provider && option.enabled === other.enabled && option.description === other.description;
+});
+function releaseCaptureStream(stream) {
+  if (!stream) return;
+  releaseSafely(() => {
+    for (const track of stream.getTracks()) releaseSafely(() => track.stop());
+  });
+  releaseSafely(() => {
+    var _a;
+    return (_a = stream.release) == null ? void 0 : _a.call(stream);
+  });
+}
+function releaseSafely(release) {
+  try {
+    void Promise.resolve(release()).catch(() => void 0);
+  } catch {
+  }
+}
+const voiceGlobals = globalThis;
+const ANSWER_TIMEOUT_MS = 45e3;
+const ICE_TIMEOUT_MS = 1e4;
+const RELAY_OPEN_TIMEOUT_MS = 1e4;
+const RELAY_CAPTURE_FRAME_SAMPLES = 1024;
+const RELAY_PLAYBACK_LEAD_SECONDS = 0.02;
+const MEDIA_DISCONNECT_GRACE_MS = 5e3;
+const END_BEFORE_RESTART_TIMEOUT_MS = 3e3;
+const mintVoiceTextId = () => `voicetext_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+const REQUEST_LABELS = {
+  "session.commentary.append": "a result for the voice conversation",
+  "session.thinking.append": "a context update",
+  "session.input_audio.mute": "the mute request",
+  "session.input_audio.unmute": "the unmute request",
+  "response.item.create": "a tool result"
+};
+const describeVoiceWireError = (error) => {
+  const subject = error.requestType ? REQUEST_LABELS[error.requestType] ?? `a ${error.requestType} event` : "a session event";
+  return `The voice service rejected ${subject}: ${error.message}`;
+};
+const voiceRelayUrl = (relayUrl, ticket) => `${relayUrl.replace(/^http/, "ws").replace(/\/+$/, "")}/api/voice/relay?ticket=${encodeURIComponent(ticket)}`;
+const pcm16FromFloat32 = (samples) => {
+  const pcm = new Int16Array(samples.length);
+  for (let index = 0; index < samples.length; index += 1) {
+    const clamped = Math.max(-1, Math.min(1, samples[index] ?? 0));
+    pcm[index] = clamped < 0 ? Math.round(clamped * 32768) : Math.round(clamped * 32767);
+  }
+  return pcm;
+};
+const float32FromPcm16 = (pcm) => {
+  const samples = new Float32Array(pcm.length);
+  for (let index = 0; index < pcm.length; index += 1) {
+    samples[index] = (pcm[index] ?? 0) / 32768;
+  }
+  return samples;
+};
+const isRecoveredCommandAuthRejection = (error) => {
+  const payload = statewireRejectionPayload(error);
+  if ((payload == null ? void 0 : payload.status) !== 503) return false;
+  const detail = payload.detail;
+  return (detail == null ? void 0 : detail.code) === "command_auth_context_expired" && detail.retryable === true;
+};
+const waitForIce = (pc, timeoutMs) => new Promise((resolve) => {
+  if (pc.iceGatheringState === "complete") {
+    resolve("complete");
+    return;
+  }
+  const timeout = setTimeout(() => {
+    pc.removeEventListener("icegatheringstatechange", check);
+    resolve("timeout");
+  }, timeoutMs);
+  const check = () => {
+    if (pc.iceGatheringState !== "complete") return;
+    clearTimeout(timeout);
+    pc.removeEventListener("icegatheringstatechange", check);
+    resolve("complete");
+  };
+  pc.addEventListener("icegatheringstatechange", check);
+});
+const waitForRelayOpen = (ws, timeoutMs) => new Promise((resolve, reject) => {
+  const timeout = setTimeout(
+    () => reject(new Error("The voice relay did not open in time")),
+    timeoutMs
+  );
+  ws.addEventListener("open", () => {
+    clearTimeout(timeout);
+    resolve();
+  });
+  ws.addEventListener("error", () => {
+    clearTimeout(timeout);
+    reject(new Error("The voice relay connection failed"));
+  });
+  ws.addEventListener("close", () => {
+    clearTimeout(timeout);
+    reject(new Error("The voice relay closed before it opened"));
+  });
+});
+const useDeepAgentVoice = (options = {}) => {
+  const wireSendCommand = useStatewireSendCommand();
+  const sendCommandRef = useRef(wireSendCommand);
+  sendCommandRef.current = wireSendCommand;
+  const sendCommand = useCallback(
+    async (command) => sendCommandRef.current(command),
+    []
+  );
+  const voice = useStatewireState(
+    // The raw wire state is non-object until the attach snapshot hydrates it.
+    (s) => readDeepAgentStreamValues(s).voice ?? null
+  );
+  const [phase, setPhase] = useState("idle");
+  const [failure, setFailure] = useState(null);
+  const error = (failure == null ? void 0 : failure.message) ?? null;
+  const [micMuted, setMicMutedState] = useState(false);
+  const micMutedRef = useRef(false);
+  const micChangeRef = useRef(0);
+  const [liveSince, setLiveSince] = useState(null);
+  const [handoffTask, setHandoffTask] = useState(null);
+  const lastActiveTaskRef = useRef(null);
+  const pcRef = useRef(null);
+  const releasePeerListenersRef = useRef(null);
+  const streamRef = useRef(null);
+  const wsRef = useRef(null);
+  const audioContextRef = useRef(null);
+  const audioNodesRef = useRef([]);
+  const playheadRef = useRef(0);
+  const livekitRef = useRef(null);
+  const livekitAbortRef = useRef(null);
+  const attemptRef = useRef(0);
+  const startingRef = useRef(false);
+  const startPromiseRef = useRef(null);
+  const autoRestartedRef = useRef(false);
+  const onRemoteStreamRef = useRef(options.onRemoteStream);
+  onRemoteStreamRef.current = options.onRemoteStream;
+  const audioSessionRef = useRef(options.audioSession);
+  audioSessionRef.current = options.audioSession;
+  const transportRef = useRef(options.transport ?? "webrtc");
+  transportRef.current = options.transport ?? "webrtc";
+  const relayUrlRef = useRef(options.relayUrl);
+  relayUrlRef.current = options.relayUrl;
+  const livekitAdapterRef = useRef(options.livekit);
+  livekitAdapterRef.current = options.livekit;
+  const modelRef = useRef(options.model);
+  modelRef.current = options.model;
+  const onDiagnosticRef = useRef(options.onDiagnostic);
+  onDiagnosticRef.current = options.onDiagnostic;
+  const timeoutsRef = useRef(options.timeouts);
+  timeoutsRef.current = options.timeouts;
+  const phaseRef = useRef("idle");
+  phaseRef.current = phase;
+  const attemptStartedAtRef = useRef(0);
+  const activeAudioSessionRef = useRef(null);
+  const startingAudioSessionRef = useRef(null);
+  const audioSessionIdleRef = useRef(Promise.resolve());
+  const report = useCallback(
+    (event, attempt, data) => {
+      const observer = onDiagnosticRef.current;
+      if (!observer) return;
+      const at = Date.now();
+      try {
+        observer({
+          event,
+          attempt,
+          at,
+          sinceStartMs: Math.max(0, at - attemptStartedAtRef.current),
+          ...data !== void 0 && { data }
+        });
+      } catch {
+      }
+    },
+    []
+  );
+  const releaseAudioSession = useCallback(() => {
+    const session = activeAudioSessionRef.current;
+    if (!session) return;
+    activeAudioSessionRef.current = null;
+    audioSessionIdleRef.current = audioSessionIdleRef.current.then(() => session.stop()).catch(() => void 0);
+  }, []);
+  const teardown = useCallback(() => {
+    attemptRef.current += 1;
+    const livekitAbort = livekitAbortRef.current;
+    livekitAbortRef.current = null;
+    releaseSafely(() => livekitAbort == null ? void 0 : livekitAbort.abort());
+    releaseSafely(() => {
+      var _a, _b;
+      return (_b = (_a = startingAudioSessionRef.current) == null ? void 0 : _a.cancelStart) == null ? void 0 : _b.call(_a);
+    });
+    releaseAudioSession();
+    const releasePeerListeners = releasePeerListenersRef.current;
+    releasePeerListenersRef.current = null;
+    releaseSafely(() => releasePeerListeners == null ? void 0 : releasePeerListeners());
+    const pc = pcRef.current;
+    pcRef.current = null;
+    releaseSafely(() => pc == null ? void 0 : pc.close());
+    const ws = wsRef.current;
+    wsRef.current = null;
+    releaseSafely(() => {
+      if (ws && ws.readyState < 2) ws.close(1e3, "client end");
+    });
+    const nodes = audioNodesRef.current;
+    audioNodesRef.current = [];
+    for (const node of nodes) releaseSafely(() => node.disconnect());
+    const audio = audioContextRef.current;
+    audioContextRef.current = null;
+    releaseSafely(() => audio == null ? void 0 : audio.close());
+    playheadRef.current = 0;
+    const livekit = livekitRef.current;
+    livekitRef.current = null;
+    releaseSafely(() => livekit == null ? void 0 : livekit.disconnect());
+    const stream = streamRef.current;
+    streamRef.current = null;
+    releaseCaptureStream(stream);
+    setLiveSince(null);
+    releaseSafely(() => {
+      var _a;
+      return (_a = onRemoteStreamRef.current) == null ? void 0 : _a.call(onRemoteStreamRef, null);
+    });
+  }, [releaseAudioSession]);
+  const fail = useCallback(
+    (nextFailure) => {
+      report("error", attemptRef.current, {
+        kind: nextFailure.kind,
+        stage: nextFailure.stage,
+        message: nextFailure.message,
+        code: nextFailure.code ?? null,
+        status: nextFailure.status ?? null,
+        fate: nextFailure.fate ?? null,
+        reason: nextFailure.reason ?? null
+      });
+      teardown();
+      setFailure(nextFailure);
+      setPhase("error");
+    },
+    [report, teardown]
+  );
+  const handleMediaLossRef = useRef(
+    async () => void 0
+  );
+  const watchConnection = useCallback((pc, attempt) => {
+    let disconnectTimer = null;
+    const clearDisconnectTimer = () => {
+      if (disconnectTimer === null) return;
+      clearTimeout(disconnectTimer);
+      disconnectTimer = null;
+    };
+    const onChange = () => {
+      if (attemptRef.current !== attempt) {
+        clearDisconnectTimer();
+        return;
+      }
+      const state = pc.connectionState ?? pc.iceConnectionState;
+      report("media-state", attempt, {
+        connectionState: pc.connectionState ?? null,
+        iceConnectionState: pc.iceConnectionState ?? null
+      });
+      if (state === "failed" || state === "closed") {
+        clearDisconnectTimer();
+        void handleMediaLossRef.current(attempt, state);
+        return;
+      }
+      if (state === "disconnected") {
+        if (disconnectTimer !== null) return;
+        disconnectTimer = setTimeout(() => {
+          disconnectTimer = null;
+          if (attemptRef.current !== attempt) return;
+          void handleMediaLossRef.current(attempt, "disconnected");
+        }, MEDIA_DISCONNECT_GRACE_MS);
+        return;
+      }
+      clearDisconnectTimer();
+    };
+    pc.addEventListener("connectionstatechange", onChange);
+    pc.addEventListener("iceconnectionstatechange", onChange);
+    return () => {
+      clearDisconnectTimer();
+      releaseSafely(() => pc.removeEventListener("connectionstatechange", onChange));
+      releaseSafely(() => pc.removeEventListener("iceconnectionstatechange", onChange));
+    };
+  }, [report]);
+  const playRelayChunk = useCallback((audio, data) => {
+    const pcm = new Int16Array(data);
+    if (pcm.length === 0) return;
+    const samples = float32FromPcm16(pcm);
+    const buffer = audio.createBuffer(1, samples.length, VOICE_RELAY_SAMPLE_RATE);
+    buffer.copyToChannel(samples, 0);
+    const node = audio.createBufferSource();
+    node.buffer = buffer;
+    node.connect(audio.destination);
+    const startAt = Math.max(audio.currentTime + RELAY_PLAYBACK_LEAD_SECONDS, playheadRef.current);
+    node.start(startAt);
+    playheadRef.current = startAt + buffer.duration;
+  }, []);
+  const runStartSession = useCallback(async () => {
+    var _a, _b, _c;
+    const attempt = attemptRef.current += 1;
+    startingRef.current = true;
+    attemptStartedAtRef.current = Date.now();
+    setFailure(null);
+    setPhase("connecting");
+    let stage = "preflight";
+    const timeouts = timeoutsRef.current;
+    const iceGatheringMs = (timeouts == null ? void 0 : timeouts.iceGatheringMs) ?? ICE_TIMEOUT_MS;
+    const answerMs = (timeouts == null ? void 0 : timeouts.answerMs) ?? ANSWER_TIMEOUT_MS;
+    const relayOpenMs = (timeouts == null ? void 0 : timeouts.relayOpenMs) ?? RELAY_OPEN_TIMEOUT_MS;
+    const stale = () => {
+      report("stale-attempt", attempt, { stage });
+      releaseAudioSession();
+    };
+    report("start-requested", attempt, { transport: transportRef.current });
+    try {
+      const transport = transportRef.current;
+      const mediaDevices = (_a = voiceGlobals.navigator) == null ? void 0 : _a.mediaDevices;
+      const PeerConnection = voiceGlobals.RTCPeerConnection;
+      const WebSocketCtor = voiceGlobals.WebSocket;
+      const AudioContextCtor = voiceGlobals.AudioContext;
+      const livekitAdapter = livekitAdapterRef.current;
+      if (transport === "livekit" && !livekitAdapter)
+        throw new Error("Voice is unavailable in this environment");
+      if (transport !== "livekit" && !mediaDevices)
+        throw new Error("Microphone capture is unavailable in this environment");
+      if (transport === "webrtc" && !PeerConnection)
+        throw new Error("WebRTC is unavailable in this environment");
+      if (transport === "websocket" && (!WebSocketCtor || !AudioContextCtor))
+        throw new Error("WebSocket audio is unavailable in this environment");
+      const relayUrl = relayUrlRef.current;
+      if (transport === "websocket" && !relayUrl)
+        throw new Error("The websocket voice transport needs a relay URL");
+      const audioSession = audioSessionRef.current;
+      if (audioSession) {
+        stage = "audio-session";
+        await audioSessionIdleRef.current;
+        if (attemptRef.current !== attempt) {
+          report("stale-attempt", attempt, { stage });
+          return;
+        }
+        startingAudioSessionRef.current = audioSession;
+        try {
+          await audioSession.start();
+        } finally {
+          startingAudioSessionRef.current = null;
+        }
+        activeAudioSessionRef.current = audioSession;
+        if (attemptRef.current !== attempt) {
+          stale();
+          return;
+        }
+        report("audio-session-ready", attempt);
+      }
+      const modelOption = modelRef.current;
+      const requestedModel = typeof modelOption === "function" ? modelOption() : modelOption;
+      const model2 = typeof requestedModel === "string" && requestedModel !== "" ? requestedModel : void 0;
+      const sendVoiceStart = (offer2) => sendCommand({
+        type: "voice/start",
+        offer: offer2,
+        ...model2 !== void 0 && { model: model2 }
+      });
+      const negotiateStart = async (offer2) => {
+        stage = "negotiate";
+        const negotiationStartedAt = Date.now();
+        const commandPromise = sendVoiceStart(offer2).catch((commandError) => {
+          if (!isRecoveredCommandAuthRejection(commandError)) throw commandError;
+          return sendVoiceStart(offer2);
+        });
+        void commandPromise.then(() => {
+          if (attemptRef.current !== attempt)
+            void sendCommand({ type: "voice/end" }).catch(() => void 0);
+        }).catch(() => void 0);
+        let answerTimer = null;
+        let result;
+        try {
+          result = await Promise.race([
+            commandPromise,
+            new Promise((_, reject) => {
+              answerTimer = setTimeout(() => reject(new VoiceAnswerTimeoutError()), answerMs);
+            })
+          ]);
+        } finally {
+          if (answerTimer !== null) clearTimeout(answerTimer);
+        }
+        report("answer-received", attempt, {
+          negotiationMs: Date.now() - negotiationStartedAt
+        });
+        stage = "answer";
+        const answer2 = result == null ? void 0 : result.answer;
+        if (typeof answer2 !== "string" || answer2 === "")
+          throw new VoiceNoAnswerError("voice/start returned no answer");
+        return answer2;
+      };
+      if (transport === "livekit") {
+        if (!livekitAdapter) return;
+        const answer2 = await negotiateStart(VOICE_LIVEKIT_OFFER);
+        if (attemptRef.current !== attempt) {
+          stale();
+          return;
+        }
+        try {
+          const room = parseVoiceLiveKitAnswer(answer2);
+          stage = "room";
+          let joined = false;
+          let disconnectedWhileJoining = false;
+          const controller = new AbortController();
+          livekitAbortRef.current = controller;
+          const session = await livekitAdapter.connect(room, {
+            micMuted: micMutedRef.current,
+            signal: controller.signal,
+            onDisconnected: (reason) => {
+              if (attemptRef.current !== attempt) return;
+              if (!joined) {
+                disconnectedWhileJoining = true;
+                return;
+              }
+              void handleMediaLossRef.current(attempt, reason);
+            }
+          });
+          if (attemptRef.current !== attempt) {
+            releaseSafely(() => session.disconnect());
+            stale();
+            return;
+          }
+          if (disconnectedWhileJoining) {
+            releaseSafely(() => session.disconnect());
+            throw new Error("The voice room disconnected while joining");
+          }
+          joined = true;
+          livekitRef.current = session;
+          report("room-joined", attempt, { roomName: room.roomName });
+        } catch (roomError) {
+          if (attemptRef.current === attempt)
+            void sendCommand({ type: "voice/end" }).catch(() => void 0);
+          throw roomError;
+        }
+        report("live", attempt, { transport, ...model2 !== void 0 && { model: model2 } });
+        if (micMutedRef.current) {
+          void sendCommand({ type: "voice/set-mic", paused: true }).catch(() => void 0);
+        }
+        setPhase("live");
+        setLiveSince(Date.now());
+        return;
+      }
+      if (!mediaDevices) return;
+      stage = "capture";
+      const stream = await mediaDevices.getUserMedia({ audio: true });
+      if (attemptRef.current !== attempt) {
+        releaseCaptureStream(stream);
+        stale();
+        return;
+      }
+      streamRef.current = stream;
+      for (const track of stream.getTracks()) track.enabled = !micMutedRef.current;
+      report("microphone-captured", attempt, {
+        tracks: stream.getTracks().length
+      });
+      if (transport === "websocket") {
+        if (!WebSocketCtor || !AudioContextCtor || !relayUrl) return;
+        const answer2 = await negotiateStart(VOICE_WEBSOCKET_OFFER);
+        if (attemptRef.current !== attempt) {
+          stale();
+          return;
+        }
+        if (!answer2.startsWith(VOICE_RELAY_ANSWER_PREFIX))
+          throw new VoiceNoAnswerError("voice/start returned no relay ticket");
+        stage = "relay";
+        const ticket = answer2.slice(VOICE_RELAY_ANSWER_PREFIX.length);
+        const ws = new WebSocketCtor(voiceRelayUrl(relayUrl, ticket));
+        ws.binaryType = "arraybuffer";
+        wsRef.current = ws;
+        await waitForRelayOpen(ws, relayOpenMs);
+        if (attemptRef.current !== attempt) {
+          stale();
+          return;
+        }
+        const audio = new AudioContextCtor({
+          sampleRate: VOICE_RELAY_SAMPLE_RATE
+        });
+        audioContextRef.current = audio;
+        await ((_b = audio.resume) == null ? void 0 : _b.call(audio));
+        if (attemptRef.current !== attempt) {
+          stale();
+          return;
+        }
+        const source = audio.createMediaStreamSource(stream);
+        const processor = audio.createScriptProcessor(RELAY_CAPTURE_FRAME_SAMPLES, 1, 1);
+        const sink = audio.createGain();
+        sink.gain.value = 0;
+        processor.onaudioprocess = (event) => {
+          if (attemptRef.current !== attempt || ws.readyState !== 1) return;
+          ws.send(pcm16FromFloat32(event.inputBuffer.getChannelData(0)).buffer);
+        };
+        source.connect(processor);
+        processor.connect(sink);
+        sink.connect(audio.destination);
+        audioNodesRef.current = [source, processor, sink];
+        playheadRef.current = 0;
+        ws.addEventListener("message", (event) => {
+          if (attemptRef.current !== attempt) return;
+          if (event.data instanceof ArrayBuffer) playRelayChunk(audio, event.data);
+        });
+        ws.addEventListener("close", () => {
+          if (attemptRef.current !== attempt) return;
+          void handleMediaLossRef.current(attempt, "relay-closed");
+        });
+        ws.addEventListener("error", () => {
+          if (attemptRef.current !== attempt) return;
+          void handleMediaLossRef.current(attempt, "relay-error");
+        });
+        report("live", attempt, { transport });
+        if (micMutedRef.current) {
+          void sendCommand({ type: "voice/set-mic", paused: true }).catch(() => void 0);
+        }
+        setPhase("live");
+        setLiveSince(Date.now());
+        return;
+      }
+      if (!PeerConnection) return;
+      stage = "offer";
+      const pc = new PeerConnection();
+      pcRef.current = pc;
+      for (const track of stream.getTracks()) pc.addTrack(track, stream);
+      const onTrack = async (trackEvent) => {
+        var _a2;
+        if (attemptRef.current !== attempt) return;
+        try {
+          const remote = trackEvent.streams[0] ?? (voiceGlobals.MediaStream ? new voiceGlobals.MediaStream([trackEvent.track]) : null);
+          if (!remote) return;
+          await ((_a2 = onRemoteStreamRef.current) == null ? void 0 : _a2.call(onRemoteStreamRef, remote));
+        } catch (playError) {
+          if (attemptRef.current !== attempt) return;
+          void sendCommand({ type: "voice/end" }).catch(() => void 0);
+          fail({
+            kind: "playback_failed",
+            stage: "playback",
+            message: `Audio playback: ${errorMessage(playError)}`
+          });
+        }
+      };
+      pc.addEventListener("track", onTrack);
+      const unwatchConnection = watchConnection(pc, attempt);
+      releasePeerListenersRef.current = () => {
+        unwatchConnection();
+        releaseSafely(() => pc.removeEventListener("track", onTrack));
+      };
+      const offer = await pc.createOffer();
+      await pc.setLocalDescription(offer);
+      const iceStartedAt = Date.now();
+      const iceOutcome = await waitForIce(pc, iceGatheringMs);
+      if (attemptRef.current !== attempt) {
+        stale();
+        return;
+      }
+      if (iceOutcome === "timeout") {
+        report("ice-gathering-timeout", attempt, {
+          waitedMs: Date.now() - iceStartedAt,
+          iceGatheringState: pc.iceGatheringState
+        });
+      }
+      const sdp = (_c = pc.localDescription) == null ? void 0 : _c.sdp;
+      if (!sdp) throw new Error("failed to create a local SDP offer");
+      report("offer-ready", attempt, {
+        iceGatheringMs: Date.now() - iceStartedAt,
+        iceGathering: iceOutcome,
+        sdpBytes: sdp.length
+      });
+      const answer = await negotiateStart(sdp);
+      if (attemptRef.current !== attempt) {
+        stale();
+        return;
+      }
+      await pc.setRemoteDescription({ type: "answer", sdp: answer });
+      if (attemptRef.current !== attempt) {
+        stale();
+        return;
+      }
+      report("live", attempt, { transport });
+      if (micMutedRef.current) {
+        void sendCommand({ type: "voice/set-mic", paused: true }).catch(() => void 0);
+      }
+      setPhase("live");
+      setLiveSince(Date.now());
+    } catch (startError) {
+      if (attemptRef.current !== attempt) {
+        stale();
+        return;
+      }
+      fail(classifyStartFailure(startError, stage));
+    } finally {
+      startingRef.current = false;
+    }
+  }, [fail, playRelayChunk, releaseAudioSession, report, sendCommand, watchConnection]);
+  const startSession = useCallback(async () => {
+    if (pcRef.current || wsRef.current || livekitRef.current || startingRef.current) return;
+    const run = runStartSession();
+    startPromiseRef.current = run;
+    try {
+      await run;
+    } finally {
+      if (startPromiseRef.current === run) startPromiseRef.current = null;
+    }
+  }, [runStartSession]);
+  const startRef = useRef(startSession);
+  startRef.current = startSession;
+  const handleMediaLoss = useCallback(
+    async (attempt, reason) => {
+      if (attemptRef.current !== attempt) return;
+      report("media-loss", attempt, {
+        reason,
+        restartBudgetLeft: !autoRestartedRef.current
+      });
+      if (lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
+      const ending = sendCommand({ type: "voice/end" }).catch(() => void 0);
+      teardown();
+      const recovery = attemptRef.current;
+      setPhase("idle");
+      let endTimer;
+      try {
+        await Promise.race([
+          ending,
+          new Promise((resolve) => {
+            endTimer = setTimeout(resolve, END_BEFORE_RESTART_TIMEOUT_MS);
+          })
+        ]);
+      } finally {
+        clearTimeout(endTimer);
+      }
+      const inflight = startPromiseRef.current;
+      if (inflight) await inflight.catch(() => void 0);
+      if (attemptRef.current !== recovery) return;
+      if (!autoRestartedRef.current) {
+        autoRestartedRef.current = true;
+        report("auto-restart", recovery, { trigger: "media-loss", reason });
+        await startRef.current();
+        return;
+      }
+      if (startingRef.current || pcRef.current || wsRef.current || livekitRef.current) return;
+      const lost = {
+        kind: "media_lost",
+        stage: "media",
+        message: `The voice connection was lost (${reason})`,
+        reason
+      };
+      report("error", recovery, {
+        kind: lost.kind,
+        stage: lost.stage,
+        message: lost.message,
+        reason
+      });
+      setFailure(lost);
+      setPhase("error");
+    },
+    [report, sendCommand, teardown]
+  );
+  handleMediaLossRef.current = handleMediaLoss;
+  const start = useCallback(async () => {
+    if (pcRef.current || wsRef.current || livekitRef.current || startingRef.current) return;
+    micMutedRef.current = false;
+    setMicMutedState(false);
+    autoRestartedRef.current = false;
+    setHandoffTask(null);
+    await startSession();
+  }, [startSession]);
+  const end = useCallback(() => {
+    if (phase === "connecting" || phase === "live") {
+      report("end", attemptRef.current, { source: "user", phase });
+      void sendCommand({ type: "voice/end" }).catch(() => void 0);
+      if (lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
+    }
+    teardown();
+    micMutedRef.current = false;
+    setMicMutedState(false);
+    setPhase("idle");
+  }, [phase, report, sendCommand, teardown]);
+  const setMicMuted = useCallback(
+    (muted) => {
+      if (phase !== "live") return;
+      const attempt = attemptRef.current;
+      const change = ++micChangeRef.current;
+      const applyLocal = (value) => {
+        var _a;
+        micMutedRef.current = value;
+        setMicMutedState(value);
+        for (const track of ((_a = streamRef.current) == null ? void 0 : _a.getTracks()) ?? []) track.enabled = !value;
+        const room = livekitRef.current;
+        if (room) releaseSafely(() => room.setMicrophoneEnabled(!value));
+      };
+      applyLocal(muted);
+      void sendCommand({ type: "voice/set-mic", paused: muted }).catch(() => {
+        if (!muted && attemptRef.current === attempt && micChangeRef.current === change) {
+          applyLocal(true);
+        }
+      });
+    },
+    [phase, sendCommand]
+  );
+  const sessionGone = useStatewireState(
+    (s) => isDeepAgentStateHydrated(s) && (readDeepAgentStreamValues(s).voice ?? null) === null
+  );
+  useEffect(() => {
+    var _a;
+    if (phase !== "live" || !sessionGone) return;
+    report("server-ended", attemptRef.current, {
+      restartBudgetLeft: !autoRestartedRef.current
+    });
+    if (lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
+    teardown();
+    setPhase("idle");
+    if (!autoRestartedRef.current) {
+      autoRestartedRef.current = true;
+      report("auto-restart", attemptRef.current, { trigger: "server-ended" });
+      void ((_a = startRef.current) == null ? void 0 : _a.call(startRef));
+    }
+  }, [phase, report, sessionGone, teardown]);
+  useEffect(
+    () => () => {
+      const phaseAtUnmount = phaseRef.current;
+      if (phaseAtUnmount === "connecting" || phaseAtUnmount === "live") {
+        report("end", attemptRef.current, {
+          source: "unmount",
+          phase: phaseAtUnmount
+        });
+        void sendCommand({ type: "voice/end" }).catch(() => void 0);
+      }
+      teardown();
+    },
+    [report, sendCommand, teardown]
+  );
+  const activeTask = (voice == null ? void 0 : voice.activeTask) ?? null;
+  useEffect(() => {
+    if (phase === "live") lastActiveTaskRef.current = activeTask;
+    else if (phase === "idle" || phase === "error") lastActiveTaskRef.current = null;
+  }, [phase, activeTask]);
+  const handoffRunActive = useStatewireState((s) => {
+    if (!isDeepAgentStateHydrated(s)) return true;
+    const status = readDeepAgentStreamValues(s).status;
+    return status === "running" || status === "stopping" || status === "input-required";
+  });
+  useEffect(() => {
+    if (handoffTask !== null && !handoffRunActive) setHandoffTask(null);
+  }, [handoffTask, handoffRunActive]);
+  const wireError = useStatewireState(
+    (s) => isDeepAgentStateHydrated(s) ? readDeepAgentStreamValues(s).voiceLastError ?? null : null
+  );
+  const notice = phase === "live" && wireError ? describeVoiceWireError(wireError) : null;
+  const model = useStatewireState((s) => {
+    if (!isDeepAgentStateHydrated(s)) return null;
+    const value = readDeepAgentStreamValues(s).voiceModel;
+    return typeof value === "string" && value !== "" ? value : null;
+  });
+  const wireModelOptions = useStatewireState(
+    (s) => isDeepAgentStateHydrated(s) ? readDeepAgentStreamValues(s).voiceModelOptions ?? null : null
+  );
+  const modelOptionsRef = useRef(null);
+  const modelOptions = useMemo(() => {
+    const next = parseVoiceModelOptions(wireModelOptions);
+    const previous = modelOptionsRef.current;
+    if (previous !== null && next !== null && sameVoiceModelOptions(previous, next)) return previous;
+    modelOptionsRef.current = next;
+    return next;
+  }, [wireModelOptions]);
+  const syncProfile = useCallback(() => {
+    if (phase !== "connecting" && phase !== "live") return;
+    void sendCommand({ type: "voice/profile-sync" }).catch(() => void 0);
+  }, [phase, sendCommand]);
+  const sendContext = useCallback(
+    (text) => {
+      const trimmed = text.trim();
+      if (phase !== "live" || !trimmed) return;
+      void sendCommand({ type: "voice/context", text: trimmed }).catch(() => void 0);
+    },
+    [phase, sendCommand]
+  );
+  const sendUserText = useCallback(
+    async (text) => {
+      if (phase !== "live" || !text.trim()) return false;
+      const messageId = mintVoiceTextId();
+      try {
+        await sendCommand({ type: "voice/user-text", text, messageId });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    [phase, sendCommand]
+  );
+  return useMemo(
+    () => ({
+      phase,
+      error,
+      failure,
+      start,
+      end,
+      activeTask,
+      liveSince,
+      micMuted,
+      setMicMuted,
+      sendUserText,
+      handoffTask,
+      syncProfile,
+      notice,
+      sendContext,
+      model,
+      modelOptions
+    }),
+    [
+      phase,
+      error,
+      failure,
+      start,
+      end,
+      activeTask,
+      liveSince,
+      micMuted,
+      setMicMuted,
+      sendUserText,
+      handoffTask,
+      syncProfile,
+      notice,
+      sendContext,
+      model,
+      modelOptions
+    ]
+  );
+};
+export {
+  VOICE_LIVEKIT_ANSWER_PREFIX,
+  VOICE_LIVEKIT_OFFER,
+  VOICE_RELAY_ANSWER_PREFIX,
+  VOICE_RELAY_SAMPLE_RATE,
+  VOICE_WEBSOCKET_OFFER,
+  classifyVoiceStartError,
+  describeVoiceFailure,
+  describeVoiceWireError,
+  float32FromPcm16,
+  parseVoiceLiveKitAnswer,
+  parseVoiceModelOptions,
+  pcm16FromFloat32,
+  useDeepAgentVoice,
+  voiceRelayUrl
+};
+//# sourceMappingURL=use-deep-agent-voice.js.map