@athenaintel/react 0.43.0 → 0.50.0

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

@@ -1,5 +1,5 @@
 import { useStatewireSendCommand, useStatewireState } from "@assistant-ui/react-statewire";
-import { useRef, useCallback, useState, useEffect, useMemo } from "react";
+import { useRef, useCallback, useState, useMemo, useEffect } from "react";
 import { statewireRejectionPayload } from "./errors.js";
 import { readDeepAgentStreamValues, isDeepAgentStateHydrated } from "./statewire-state.js";
 const readSendFailure = (error) => {
@@ -67,6 +67,47 @@ const parseVoiceLiveKitAnswer = (answer) => {
   }
   return { serverUrl, token, roomName };
 };
+class VoiceTransferRoomDroppedError extends Error {
+  constructor(reason) {
+    super(`The voice room disconnected before the call moved (${reason})`);
+    this.reason = reason;
+    this.name = "VoiceTransferRoomDroppedError";
+  }
+}
+const withAnswerDeadline = async (promise, ms) => {
+  let timer = null;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new VoiceAnswerTimeoutError()), ms);
+      })
+    ]);
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+  }
+};
+const readTransferOffer = (result) => {
+  const record = result !== null && typeof result === "object" ? result : null;
+  const answer = record == null ? void 0 : record.answer;
+  const transferId = record == null ? void 0 : record.transferId;
+  return {
+    answer: typeof answer === "string" && answer !== "" ? answer : null,
+    transferId: typeof transferId === "string" && transferId !== "" ? transferId : null
+  };
+};
+const classifyTransferFailure = (error, stage) => {
+  const underlying = stage === "commit" ? error instanceof VoiceTransferRoomDroppedError ? { kind: "room_failed" } : classifyVoiceStartError(error) : classifyStartFailure(error, stage);
+  return {
+    kind: "transfer_failed",
+    stage,
+    message: describeVoiceTransferFailure({ reason: underlying.kind }),
+    reason: underlying.kind,
+    ...underlying.code !== void 0 && { code: underlying.code },
+    ...underlying.status !== void 0 && { status: underlying.status },
+    ...underlying.fate !== void 0 && { fate: underlying.fate }
+  };
+};
 const classifyStartFailure = (error, stage) => {
   const message = errorMessage(error);
   switch (stage) {
@@ -109,6 +150,7 @@ const isMicrophoneDenied = (error) => {
   }
   return /permission|denied|not allowed/i.test(errorMessage(error));
 };
+const describeVoiceTransferFailure = ({ reason }) => reason === "microphone_denied" ? "Microphone access is blocked, so the call stayed on your other device. Allow the microphone for Athena and try again." : "The call couldn't move here and is still on your other device. Try again.";
 const describeVoiceFailure = (failure) => {
   switch (failure.kind) {
     case "microphone_denied":
@@ -123,6 +165,8 @@ const describeVoiceFailure = (failure) => {
       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 "transfer_failed":
+      return describeVoiceTransferFailure({ reason: failure.reason });
     case "server_rejected":
       if (failure.code === "voice-active") {
         return "A voice session is already live on another device or tab. End it there first.";
@@ -188,6 +232,8 @@ 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 TRANSFER_OFFER_TIMEOUT_MS = 15e3;
+const TRANSFER_COMMIT_TIMEOUT_MS = 15e3;
 const mintVoiceId = ({ kind }) => `voice${kind}_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
 const formatVoiceElapsed = (sinceMs, nowMs = Date.now()) => {
   const total = Math.max(0, Math.floor((nowMs - sinceMs) / 1e3));
@@ -207,6 +253,42 @@ const useVoiceElapsed = (since) => {
   }, [since]);
   return since === null ? null : formatVoiceElapsed(since, now);
 };
+const VOICE_SURFACE_LABELS = {
+  web: "browser",
+  mobile: "phone",
+  chrome: "Chrome",
+  desktop: "desktop app",
+  office: "Office"
+};
+const voiceSurfaceLabel = (surface) => VOICE_SURFACE_LABELS[surface];
+const VOICE_MOVE_CALL_HERE_LABEL = "Move call here";
+const VOICE_MOVE_HERE_ACTION = "Move here";
+const VOICE_CONTINUE_BY_VOICE_LABEL = "Continue by voice";
+const describeVoiceLiveElsewhere = (surface) => `Live call on your ${voiceSurfaceLabel(surface)}`;
+const describeVoiceMovedTo = (surface) => `Call moved to your ${voiceSurfaceLabel(surface)}`;
+const VOICE_MOVED_NOTICE_MS = 6e3;
+const useVoiceMovedNotice = (movedTo) => {
+  const [expired, setExpired] = useState(null);
+  useEffect(() => {
+    if (movedTo === null) return;
+    const timer = setTimeout(() => setExpired(movedTo), VOICE_MOVED_NOTICE_MS);
+    return () => clearTimeout(timer);
+  }, [movedTo]);
+  return movedTo !== null && expired !== movedTo ? describeVoiceMovedTo(movedTo.surface) : null;
+};
+const VOICE_SURFACES = new Set(Object.keys(VOICE_SURFACE_LABELS));
+const parseVoiceOwner = (value) => {
+  if (value === null || typeof value !== "object") return null;
+  const { clientId, surface, since, transferable } = value;
+  if (typeof clientId !== "string" || clientId === "") return null;
+  if (typeof since !== "number" || !Number.isFinite(since)) return null;
+  return {
+    clientId,
+    surface: typeof surface === "string" && VOICE_SURFACES.has(surface) ? surface : "web",
+    since,
+    transferable: transferable === true
+  };
+};
 const REQUEST_LABELS = {
   "session.commentary.append": "a result for the voice conversation",
   "session.thinking.append": "a context update",
@@ -275,6 +357,11 @@ const waitForRelayOpen = (ws, timeoutMs) => new Promise((resolve, reject) => {
     reject(new Error("The voice relay closed before it opened"));
   });
 });
+const useRetainedHydrated = (value, initial) => {
+  const ref = useRef(initial);
+  if (value !== void 0) ref.current = value;
+  return ref.current;
+};
 const useDeepAgentVoice = (options = {}) => {
   const wireSendCommand = useStatewireSendCommand();
   const sendCommandRef = useRef(wireSendCommand);
@@ -332,6 +419,8 @@ const useDeepAgentVoice = (options = {}) => {
   modelRef.current = options.model;
   const onDiagnosticRef = useRef(options.onDiagnostic);
   onDiagnosticRef.current = options.onDiagnostic;
+  const onCallMovedRef = useRef(options.onCallMoved);
+  onCallMovedRef.current = options.onCallMoved;
   const timeoutsRef = useRef(options.timeouts);
   timeoutsRef.current = options.timeouts;
   const phaseRef = useRef("idle");
@@ -340,6 +429,50 @@ const useDeepAgentVoice = (options = {}) => {
   const activeAudioSessionRef = useRef(null);
   const startingAudioSessionRef = useRef(null);
   const audioSessionIdleRef = useRef(Promise.resolve());
+  const ownClientIdRef = useRef(null);
+  const lastOwnedClientIdRef = useRef(null);
+  const transferRef = useRef(null);
+  const [movedTo, setMovedTo] = useState(null);
+  const hydratedTransferCapable = useStatewireState(
+    (s) => isDeepAgentStateHydrated(s) ? "voiceOwner" in readDeepAgentStreamValues(s) : void 0
+  );
+  const hydratedVoiceOwner = useStatewireState(
+    (s) => isDeepAgentStateHydrated(s) ? readDeepAgentStreamValues(s).voiceOwner ?? null : void 0
+  );
+  const hydratedWireOwnerId = useStatewireState((s) => {
+    if (!isDeepAgentStateHydrated(s)) return void 0;
+    const wire = readDeepAgentStreamValues(s).voice;
+    return typeof (wire == null ? void 0 : wire.clientId) === "string" && wire.clientId !== "" ? wire.clientId : null;
+  });
+  const hydratedWireLive = useStatewireState((s) => {
+    if (!isDeepAgentStateHydrated(s)) return void 0;
+    const wire = readDeepAgentStreamValues(s).voice;
+    return (wire == null ? void 0 : wire.status) === "live";
+  });
+  const transferCapable = useRetainedHydrated(hydratedTransferCapable, false);
+  const wireVoiceOwner = useRetainedHydrated(hydratedVoiceOwner, null);
+  const wireOwnerId = useRetainedHydrated(hydratedWireOwnerId, null);
+  const wireLive = useRetainedHydrated(hydratedWireLive, false);
+  const voiceOwner = useMemo(
+    () => transferCapable ? parseVoiceOwner(wireVoiceOwner) : null,
+    [transferCapable, wireVoiceOwner]
+  );
+  const transferCapableRef = useRef(transferCapable);
+  transferCapableRef.current = transferCapable;
+  const voiceOwnerRef = useRef(voiceOwner);
+  voiceOwnerRef.current = voiceOwner;
+  const wireOwnerIdRef = useRef(wireOwnerId);
+  wireOwnerIdRef.current = wireOwnerId;
+  const canTakeCall = transportRef.current === "livekit" && livekitAdapterRef.current !== void 0;
+  const elsewhere = voiceOwner !== null && voiceOwner.transferable && wireLive && canTakeCall && (phase === "idle" || phase === "error") && voiceOwner.clientId !== lastOwnedClientIdRef.current ? voiceOwner : null;
+  const elsewhereSurface = (elsewhere == null ? void 0 : elsewhere.surface) ?? null;
+  const elsewhereSince = (elsewhere == null ? void 0 : elsewhere.since) ?? null;
+  const liveElsewhere = useMemo(
+    () => elsewhereSurface === null || elsewhereSince === null ? null : { surface: elsewhereSurface, since: elsewhereSince },
+    [elsewhereSurface, elsewhereSince]
+  );
+  const liveElsewhereRef = useRef(liveElsewhere);
+  liveElsewhereRef.current = liveElsewhere;
   const report = useCallback(
     (event, attempt, data) => {
       const observer = onDiagnosticRef.current;
@@ -364,7 +497,15 @@ const useDeepAgentVoice = (options = {}) => {
     activeAudioSessionRef.current = null;
     audioSessionIdleRef.current = audioSessionIdleRef.current.then(() => session.stop()).catch(() => void 0);
   }, []);
-  const teardown = useCallback(() => {
+  const notifyCallMoved = useCallback((move) => {
+    const observer = onCallMovedRef.current;
+    if (!observer) return;
+    try {
+      void Promise.resolve(observer(move)).catch(() => void 0);
+    } catch {
+    }
+  }, []);
+  const teardown = useCallback((options2) => {
     attemptRef.current += 1;
     const livekitAbort = livekitAbortRef.current;
     livekitAbortRef.current = null;
@@ -373,7 +514,7 @@ const useDeepAgentVoice = (options = {}) => {
       var _a, _b;
       return (_b = (_a = startingAudioSessionRef.current) == null ? void 0 : _a.cancelStart) == null ? void 0 : _b.call(_a);
     });
-    releaseAudioSession();
+    if ((options2 == null ? void 0 : options2.keepAudioSession) !== true) releaseAudioSession();
     const releasePeerListeners = releasePeerListenersRef.current;
     releasePeerListenersRef.current = null;
     releaseSafely(() => releasePeerListeners == null ? void 0 : releasePeerListeners());
@@ -421,6 +562,101 @@ const useDeepAgentVoice = (options = {}) => {
     },
     [report, teardown]
   );
+  const handleMovedAway = useCallback(() => {
+    var _a;
+    const surface = ((_a = voiceOwnerRef.current) == null ? void 0 : _a.surface) ?? "web";
+    report("moved", attemptRef.current, { toSurface: surface });
+    notifyCallMoved({ direction: "away", surface });
+    teardown();
+    ownClientIdRef.current = null;
+    micMutedRef.current = false;
+    setMicMutedState(false);
+    setHandoffTask(null);
+    setFailure(null);
+    setPhase("idle");
+    setMovedTo({ surface });
+  }, [notifyCallMoved, report, teardown]);
+  const ownerMovedAway = useCallback(() => {
+    const own = ownClientIdRef.current;
+    const current = wireOwnerIdRef.current;
+    return transferCapableRef.current && own !== null && current !== null && current !== own;
+  }, []);
+  const acquireAudioSession = useCallback(
+    async ({
+      attempt,
+      audioSession
+    }) => {
+      const held = activeAudioSessionRef.current;
+      if (held !== null && held !== audioSession) releaseAudioSession();
+      await audioSessionIdleRef.current;
+      if (attemptRef.current !== attempt) {
+        report("stale-attempt", attempt, { stage: "audio-session" });
+        return false;
+      }
+      if (activeAudioSessionRef.current === audioSession) {
+        report("audio-session-ready", attempt, { reused: true });
+        return true;
+      }
+      startingAudioSessionRef.current = audioSession;
+      try {
+        await audioSession.start();
+      } finally {
+        startingAudioSessionRef.current = null;
+      }
+      activeAudioSessionRef.current = audioSession;
+      if (attemptRef.current !== attempt) {
+        report("stale-attempt", attempt, { stage: "audio-session" });
+        releaseAudioSession();
+        return false;
+      }
+      report("audio-session-ready", attempt);
+      return true;
+    },
+    [releaseAudioSession, report]
+  );
+  const joinVoiceRoom = useCallback(
+    async ({
+      attempt,
+      room,
+      adapter,
+      controller = new AbortController(),
+      onDisconnectedAfterJoin
+    }) => {
+      let joined = false;
+      let disconnectedWhileJoining = false;
+      livekitAbortRef.current = controller;
+      const session = await adapter.connect(room, {
+        micMuted: micMutedRef.current,
+        signal: controller.signal,
+        onDisconnected: (reason) => {
+          if (attemptRef.current !== attempt) return;
+          if (!joined) {
+            disconnectedWhileJoining = true;
+            return;
+          }
+          onDisconnectedAfterJoin(reason);
+        },
+        // Telemetry about this attempt's room stays this attempt's even after
+        // it ended: the room's closing summary arrives after teardown.
+        onEvent: (event) => {
+          report("media-event", attempt, { ...event.data, type: event.type });
+        }
+      });
+      if (attemptRef.current !== attempt) {
+        releaseSafely(() => session.disconnect());
+        return false;
+      }
+      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 });
+      return true;
+    },
+    [report]
+  );
   const handleMediaLossRef = useRef(
     async () => void 0
   );
@@ -478,12 +714,15 @@ const useDeepAgentVoice = (options = {}) => {
     node.start(startAt);
     playheadRef.current = startAt + buffer.duration;
   }, []);
-  const runStartSession = useCallback(async () => {
+  const runStartSession = useCallback(async ({
+    opening
+  } = {}) => {
     var _a, _b, _c;
     const attempt = attemptRef.current += 1;
     const attemptId = mintVoiceId({ kind: "attempt" });
     const previousAttemptId = observedAttemptRef.current;
     callAttemptIdRef.current = attemptId;
+    ownClientIdRef.current = null;
     startingRef.current = true;
     attemptStartedAtRef.current = Date.now();
     setFailure(null);
@@ -497,7 +736,10 @@ const useDeepAgentVoice = (options = {}) => {
       report("stale-attempt", attempt, { stage });
       releaseAudioSession();
     };
-    report("start-requested", attempt, { transport: transportRef.current });
+    report("start-requested", attempt, {
+      transport: transportRef.current,
+      ...opening !== void 0 && { opening }
+    });
     try {
       const transport = transportRef.current;
       const mediaDevices = (_a = voiceGlobals.navigator) == null ? void 0 : _a.mediaDevices;
@@ -519,23 +761,7 @@ const useDeepAgentVoice = (options = {}) => {
       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);
+        if (!await acquireAudioSession({ attempt, audioSession })) return;
       }
       const modelOption = modelRef.current;
       const requestedModel = typeof modelOption === "function" ? modelOption() : modelOption;
@@ -545,7 +771,8 @@ const useDeepAgentVoice = (options = {}) => {
         offer: offer2,
         attemptId,
         ...previousAttemptId !== void 0 && { previousAttemptId },
-        ...model2 !== void 0 && { model: model2 }
+        ...model2 !== void 0 && { model: model2 },
+        ...opening !== void 0 && { opening }
       });
       const negotiateStart = async (offer2) => {
         stage = "negotiate";
@@ -590,34 +817,16 @@ const useDeepAgentVoice = (options = {}) => {
         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);
-            }
+          const joinedRoom = await joinVoiceRoom({
+            attempt,
+            room,
+            adapter: livekitAdapter,
+            onDisconnectedAfterJoin: (reason) => void handleMediaLossRef.current(attempt, reason)
           });
-          if (attemptRef.current !== attempt) {
-            releaseSafely(() => session.disconnect());
+          if (!joinedRoom) {
             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", attemptId }).catch(() => void 0);
@@ -779,10 +988,19 @@ const useDeepAgentVoice = (options = {}) => {
     } finally {
       startingRef.current = false;
     }
-  }, [fail, playRelayChunk, releaseAudioSession, report, sendCommand, watchConnection]);
-  const startSession = useCallback(async () => {
+  }, [
+    acquireAudioSession,
+    fail,
+    joinVoiceRoom,
+    playRelayChunk,
+    releaseAudioSession,
+    report,
+    sendCommand,
+    watchConnection
+  ]);
+  const startSession = useCallback(async (options2 = {}) => {
     if (pcRef.current || wsRef.current || livekitRef.current || startingRef.current) return;
-    const run = runStartSession();
+    const run = runStartSession(options2);
     startPromiseRef.current = run;
     try {
       await run;
@@ -795,13 +1013,18 @@ const useDeepAgentVoice = (options = {}) => {
   const handleMediaLoss = useCallback(
     async (attempt, reason) => {
       if (attemptRef.current !== attempt) return;
+      if (ownerMovedAway()) {
+        handleMovedAway();
+        return;
+      }
+      const restarting = !autoRestartedRef.current;
       report("media-loss", attempt, {
         reason,
-        restartBudgetLeft: !autoRestartedRef.current
+        restartBudgetLeft: restarting
       });
       if (lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
       const ending = sendCommand({ type: "voice/end", attemptId: callAttemptIdRef.current }).catch(() => void 0);
-      teardown();
+      teardown({ keepAudioSession: restarting });
       const recovery = attemptRef.current;
       setPhase("idle");
       let endTimer;
@@ -818,6 +1041,10 @@ const useDeepAgentVoice = (options = {}) => {
       const inflight = startPromiseRef.current;
       if (inflight) await inflight.catch(() => void 0);
       if (attemptRef.current !== recovery) return;
+      if (ownerMovedAway()) {
+        handleMovedAway();
+        return;
+      }
       if (!autoRestartedRef.current) {
         autoRestartedRef.current = true;
         report("auto-restart", recovery, { trigger: "media-loss", reason });
@@ -840,49 +1067,251 @@ const useDeepAgentVoice = (options = {}) => {
       setFailure(lost);
       setPhase("error");
     },
-    [report, sendCommand, teardown]
+    [handleMovedAway, ownerMovedAway, report, sendCommand, teardown]
   );
   handleMediaLossRef.current = handleMediaLoss;
-  const start = useCallback(async () => {
+  const start = useCallback(async (options2) => {
     if (pcRef.current || wsRef.current || livekitRef.current || startingRef.current) return;
     micMutedRef.current = false;
     setMicMutedState(false);
     autoRestartedRef.current = false;
     setHandoffTask(null);
-    await startSession();
+    setMovedTo(null);
+    await startSession((options2 == null ? void 0 : options2.opening) === "recap" ? { opening: "recap" } : {});
   }, [startSession]);
+  const runTransferHere = useCallback(async () => {
+    var _a;
+    const fromSurface = ((_a = liveElsewhereRef.current) == null ? void 0 : _a.surface) ?? "web";
+    const attempt = attemptRef.current += 1;
+    const attemptId = mintVoiceId({ kind: "attempt" });
+    callAttemptIdRef.current = attemptId;
+    ownClientIdRef.current = null;
+    const transfer = { attempt, transferId: null };
+    transferRef.current = transfer;
+    startingRef.current = true;
+    attemptStartedAtRef.current = Date.now();
+    setFailure(null);
+    setPhase("connecting");
+    let stage = "preflight";
+    const timeouts = timeoutsRef.current;
+    const offerMs = Math.min((timeouts == null ? void 0 : timeouts.answerMs) ?? ANSWER_TIMEOUT_MS, TRANSFER_OFFER_TIMEOUT_MS);
+    const commitMs = (timeouts == null ? void 0 : timeouts.transferCommitMs) ?? TRANSFER_COMMIT_TIMEOUT_MS;
+    const cancel = () => {
+      const transferId = transfer.transferId;
+      if (transferId === null) return;
+      void sendCommand({ type: "voice/transfer-cancel", transferId }).catch(() => void 0);
+    };
+    let promotedCallEnded = false;
+    const endPromotedCall = () => {
+      if (promotedCallEnded) return;
+      promotedCallEnded = true;
+      void sendCommand({ type: "voice/end", attemptId }).catch(() => void 0);
+    };
+    const stale = () => {
+      report("stale-attempt", attempt, { stage, transfer: true });
+      if (transferRef.current === transfer) {
+        transferRef.current = null;
+        cancel();
+      }
+      releaseAudioSession();
+    };
+    const controller = new AbortController();
+    livekitAbortRef.current = controller;
+    const superseded = new Promise((_, reject) => {
+      controller.signal.addEventListener("abort", () => reject(new Error("The move was superseded")), {
+        once: true
+      });
+    });
+    void superseded.catch(() => void 0);
+    report("start-requested", attempt, { transport: "livekit", transfer: true });
+    try {
+      const livekitAdapter = livekitAdapterRef.current;
+      if (transportRef.current !== "livekit" || !livekitAdapter)
+        throw new Error("Voice is unavailable in this environment");
+      const audioSession = audioSessionRef.current;
+      if (audioSession) {
+        stage = "audio-session";
+        if (!await acquireAudioSession({ attempt, audioSession })) {
+          stale();
+          return;
+        }
+      }
+      stage = "negotiate";
+      const negotiationStartedAt = Date.now();
+      const offer = sendCommand({ type: "voice/transfer-offer", attemptId });
+      void offer.then((result) => {
+        if (attemptRef.current === attempt) return;
+        const { transferId } = readTransferOffer(result);
+        if (transferId !== null)
+          void sendCommand({ type: "voice/transfer-cancel", transferId }).catch(() => void 0);
+      }).catch(() => void 0);
+      const offered = readTransferOffer(
+        await withAnswerDeadline(Promise.race([offer, superseded]), offerMs)
+      );
+      report("answer-received", attempt, {
+        negotiationMs: Date.now() - negotiationStartedAt,
+        transfer: true
+      });
+      if (attemptRef.current !== attempt) {
+        stale();
+        return;
+      }
+      stage = "answer";
+      transfer.transferId = offered.transferId;
+      if (offered.transferId === null || offered.answer === null)
+        throw new VoiceNoAnswerError("voice/transfer-offer returned no voice room");
+      const room = parseVoiceLiveKitAnswer(offered.answer);
+      stage = "room";
+      let moved = false;
+      let roomDropped = () => void 0;
+      const dropped = new Promise((_, reject) => {
+        roomDropped = (reason) => reject(new VoiceTransferRoomDroppedError(reason));
+      });
+      void dropped.catch(() => void 0);
+      const joinedRoom = await joinVoiceRoom({
+        attempt,
+        room,
+        adapter: livekitAdapter,
+        controller,
+        onDisconnectedAfterJoin: (reason) => {
+          if (moved) void handleMediaLossRef.current(attempt, reason);
+          else roomDropped(reason);
+        }
+      });
+      if (!joinedRoom) {
+        stale();
+        return;
+      }
+      stage = "commit";
+      const commit = sendCommand({
+        type: "voice/transfer-commit",
+        transferId: offered.transferId,
+        attemptId
+      });
+      void commit.then(
+        () => {
+          if (attemptRef.current !== attempt) endPromotedCall();
+        },
+        (commitError) => {
+          if (attemptRef.current === attempt) return;
+          const failure2 = readSendFailure(commitError);
+          if (failure2 !== null && failure2.fate !== "rejected") endPromotedCall();
+        }
+      );
+      await withAnswerDeadline(Promise.race([commit, dropped, superseded]), commitMs);
+      if (attemptRef.current !== attempt) {
+        stale();
+        return;
+      }
+      moved = true;
+      transferRef.current = null;
+      report("live", attempt, { transport: "livekit", transfer: true });
+      setPhase("live");
+      setLiveSince(Date.now());
+      notifyCallMoved({ direction: "here", surface: fromSurface });
+    } catch (transferError) {
+      if (attemptRef.current !== attempt) {
+        stale();
+        return;
+      }
+      cancel();
+      const sendFailure = readSendFailure(transferError);
+      if (stage === "commit" && sendFailure !== null && sendFailure.fate !== "rejected")
+        endPromotedCall();
+      transferRef.current = null;
+      fail(classifyTransferFailure(transferError, stage));
+    } finally {
+      startingRef.current = false;
+    }
+  }, [
+    acquireAudioSession,
+    fail,
+    joinVoiceRoom,
+    notifyCallMoved,
+    releaseAudioSession,
+    report,
+    sendCommand
+  ]);
+  const transferHere = useCallback(async () => {
+    if (pcRef.current || wsRef.current || livekitRef.current || startingRef.current) return;
+    if (liveElsewhereRef.current === null) return;
+    micMutedRef.current = false;
+    setMicMutedState(false);
+    autoRestartedRef.current = false;
+    setHandoffTask(null);
+    setMovedTo(null);
+    const run = runTransferHere();
+    startPromiseRef.current = run;
+    try {
+      await run;
+    } finally {
+      if (startPromiseRef.current === run) startPromiseRef.current = null;
+    }
+  }, [runTransferHere]);
+  const releaseCall = useCallback(() => {
+    const transfer = transferRef.current;
+    transferRef.current = null;
+    if (transfer !== null) {
+      if (transfer.transferId !== null) {
+        void sendCommand({ type: "voice/transfer-cancel", transferId: transfer.transferId }).catch(
+          () => void 0
+        );
+      }
+      return;
+    }
+    void sendCommand({ type: "voice/end", attemptId: callAttemptIdRef.current }).catch(() => void 0);
+  }, [sendCommand]);
   const end = useCallback(() => {
     if (phase === "connecting" || phase === "live") {
       report("end", attemptRef.current, { source: "user", phase });
-      void sendCommand({ type: "voice/end", attemptId: callAttemptIdRef.current }).catch(() => void 0);
-      if (lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
+      const moving = transferRef.current !== null;
+      releaseCall();
+      if (!moving && lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
     }
     teardown();
     micMutedRef.current = false;
     setMicMutedState(false);
     setPhase("idle");
-  }, [phase, report, sendCommand, teardown]);
+  }, [phase, releaseCall, report, teardown]);
   const setMicMuted = useCallback(
     (muted) => {
       if (phase !== "live") return;
       const attempt = attemptRef.current;
+      const attemptId = callAttemptIdRef.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));
+        const mediaFailed = () => {
+          if (attemptRef.current !== attempt || micChangeRef.current !== change || livekitRef.current !== room) return;
+          void sendCommand({ type: "voice/end", attemptId }).catch(() => void 0);
+          if (lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
+          fail({
+            kind: "media_lost",
+            stage: "media",
+            reason: "microphone-control-failed",
+            message: "Voice ended because the microphone could not be changed. Start a new call to try again."
+          });
+        };
+        try {
+          for (const track of ((_a = streamRef.current) == null ? void 0 : _a.getTracks()) ?? []) track.enabled = !value;
+          if (room) void room.setMicrophoneEnabled(!value).catch(mediaFailed);
+          return true;
+        } catch {
+          mediaFailed();
+          return false;
+        }
       };
-      applyLocal(muted);
-      void sendCommand({ type: "voice/set-mic", paused: muted, attemptId: callAttemptIdRef.current }).catch(() => {
+      if (!applyLocal(muted)) return;
+      void sendCommand({ type: "voice/set-mic", paused: muted, attemptId }).catch(() => {
         if (!muted && attemptRef.current === attempt && micChangeRef.current === change) {
           applyLocal(true);
         }
       });
     },
-    [phase, sendCommand]
+    [phase, sendCommand, fail]
   );
   const sessionGone = useStatewireState(
     (s) => isDeepAgentStateHydrated(s) && (readDeepAgentStreamValues(s).voice ?? null) === null
@@ -890,18 +1319,31 @@ const useDeepAgentVoice = (options = {}) => {
   useEffect(() => {
     var _a;
     if (phase !== "live" || !sessionGone) return;
+    const restarting = !autoRestartedRef.current;
     report("server-ended", attemptRef.current, {
-      restartBudgetLeft: !autoRestartedRef.current
+      restartBudgetLeft: restarting
     });
     if (lastActiveTaskRef.current) setHandoffTask(lastActiveTaskRef.current);
-    teardown();
+    teardown({ keepAudioSession: restarting });
     setPhase("idle");
-    if (!autoRestartedRef.current) {
+    if (restarting) {
       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(() => {
+    if (phase !== "live" || !transferCapable || wireOwnerId === null) return;
+    const own = ownClientIdRef.current;
+    if (own === null) {
+      const fence = observedAttemptRef.current;
+      if (fence !== void 0 && fence !== callAttemptIdRef.current) return;
+      ownClientIdRef.current = wireOwnerId;
+      lastOwnedClientIdRef.current = wireOwnerId;
+      return;
+    }
+    if (wireOwnerId !== own) handleMovedAway();
+  }, [phase, transferCapable, wireOwnerId, observedAttempt, handleMovedAway]);
   useEffect(
     () => () => {
       const phaseAtUnmount = phaseRef.current;
@@ -910,11 +1352,12 @@ const useDeepAgentVoice = (options = {}) => {
           source: "unmount",
           phase: phaseAtUnmount
         });
-        void sendCommand({ type: "voice/end", attemptId: callAttemptIdRef.current }).catch(() => void 0);
+        releaseCall();
       }
+      transferRef.current = null;
       teardown();
     },
-    [report, sendCommand, teardown]
+    [releaseCall, report, teardown]
   );
   const activeTask = (voice == null ? void 0 : voice.activeTask) ?? null;
   useEffect(() => {
@@ -991,7 +1434,10 @@ const useDeepAgentVoice = (options = {}) => {
       notice,
       sendContext,
       model,
-      modelOptions
+      modelOptions,
+      liveElsewhere,
+      transferHere,
+      movedTo
     }),
     [
       phase,
@@ -1009,26 +1455,38 @@ const useDeepAgentVoice = (options = {}) => {
       notice,
       sendContext,
       model,
-      modelOptions
+      modelOptions,
+      liveElsewhere,
+      transferHere,
+      movedTo
     ]
   );
 };
 export {
+  VOICE_CONTINUE_BY_VOICE_LABEL,
   VOICE_LIVEKIT_ANSWER_PREFIX,
   VOICE_LIVEKIT_OFFER,
+  VOICE_MOVED_NOTICE_MS,
+  VOICE_MOVE_CALL_HERE_LABEL,
+  VOICE_MOVE_HERE_ACTION,
   VOICE_RELAY_ANSWER_PREFIX,
   VOICE_RELAY_SAMPLE_RATE,
   VOICE_WEBSOCKET_OFFER,
   classifyVoiceStartError,
   describeVoiceFailure,
+  describeVoiceLiveElsewhere,
+  describeVoiceMovedTo,
   describeVoiceWireError,
   float32FromPcm16,
   formatVoiceElapsed,
   parseVoiceLiveKitAnswer,
   parseVoiceModelOptions,
+  parseVoiceOwner,
   pcm16FromFloat32,
   useDeepAgentVoice,
   useVoiceElapsed,
-  voiceRelayUrl
+  useVoiceMovedNotice,
+  voiceRelayUrl,
+  voiceSurfaceLabel
 };
 //# sourceMappingURL=use-deep-agent-voice.js.map