@athenaintel/react 0.43.0 → 0.50.0

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const reactStatewire = require("@assistant-ui/react-statewire");
-const react = require("react");
+const require$$0 = require("react");
 const errors = require("./errors.cjs");
 const statewireState = require("./statewire-state.cjs");
 const readSendFailure = (error) => {
@@ -69,6 +69,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) {
@@ -111,6 +152,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":
@@ -125,6 +167,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.";
@@ -190,6 +234,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));
@@ -200,8 +246,8 @@ const formatVoiceElapsed = (sinceMs, nowMs = Date.now()) => {
   return hours > 0 ? `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}` : mmss;
 };
 const useVoiceElapsed = (since) => {
-  const [now, setNow] = react.useState(() => Date.now());
-  react.useEffect(() => {
+  const [now, setNow] = require$$0.useState(() => Date.now());
+  require$$0.useEffect(() => {
     if (since === null) return;
     setNow(Date.now());
     const timer = setInterval(() => setNow(Date.now()), 1e3);
@@ -209,6 +255,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] = require$$0.useState(null);
+  require$$0.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",
@@ -277,11 +359,16 @@ const waitForRelayOpen = (ws, timeoutMs) => new Promise((resolve, reject) => {
     reject(new Error("The voice relay closed before it opened"));
   });
 });
+const useRetainedHydrated = (value, initial) => {
+  const ref = require$$0.useRef(initial);
+  if (value !== void 0) ref.current = value;
+  return ref.current;
+};
 const useDeepAgentVoice = (options = {}) => {
   const wireSendCommand = reactStatewire.useStatewireSendCommand();
-  const sendCommandRef = react.useRef(wireSendCommand);
+  const sendCommandRef = require$$0.useRef(wireSendCommand);
   sendCommandRef.current = wireSendCommand;
-  const sendCommand = react.useCallback(
+  const sendCommand = require$$0.useCallback(
     async (command) => sendCommandRef.current(command),
     []
   );
@@ -289,60 +376,106 @@ const useDeepAgentVoice = (options = {}) => {
     // The raw wire state is non-object until the attach snapshot hydrates it.
     (s) => statewireState.readDeepAgentStreamValues(s).voice ?? null
   );
-  const [phase, setPhase] = react.useState("idle");
-  const [failure, setFailure] = react.useState(null);
+  const [phase, setPhase] = require$$0.useState("idle");
+  const [failure, setFailure] = require$$0.useState(null);
   const error = (failure == null ? void 0 : failure.message) ?? null;
-  const [micMuted, setMicMutedState] = react.useState(false);
-  const micMutedRef = react.useRef(false);
-  const micChangeRef = react.useRef(0);
-  const [liveSince, setLiveSince] = react.useState(null);
-  const [handoffTask, setHandoffTask] = react.useState(null);
-  const lastActiveTaskRef = react.useRef(null);
-  const pcRef = react.useRef(null);
-  const releasePeerListenersRef = react.useRef(null);
-  const streamRef = react.useRef(null);
-  const wsRef = react.useRef(null);
-  const audioContextRef = react.useRef(null);
-  const audioNodesRef = react.useRef([]);
-  const playheadRef = react.useRef(0);
-  const livekitRef = react.useRef(null);
-  const livekitAbortRef = react.useRef(null);
-  const attemptRef = react.useRef(0);
-  const callAttemptIdRef = react.useRef("");
+  const [micMuted, setMicMutedState] = require$$0.useState(false);
+  const micMutedRef = require$$0.useRef(false);
+  const micChangeRef = require$$0.useRef(0);
+  const [liveSince, setLiveSince] = require$$0.useState(null);
+  const [handoffTask, setHandoffTask] = require$$0.useState(null);
+  const lastActiveTaskRef = require$$0.useRef(null);
+  const pcRef = require$$0.useRef(null);
+  const releasePeerListenersRef = require$$0.useRef(null);
+  const streamRef = require$$0.useRef(null);
+  const wsRef = require$$0.useRef(null);
+  const audioContextRef = require$$0.useRef(null);
+  const audioNodesRef = require$$0.useRef([]);
+  const playheadRef = require$$0.useRef(0);
+  const livekitRef = require$$0.useRef(null);
+  const livekitAbortRef = require$$0.useRef(null);
+  const attemptRef = require$$0.useRef(0);
+  const callAttemptIdRef = require$$0.useRef("");
   const observedAttempt = reactStatewire.useStatewireState((s) => {
     if (!statewireState.isDeepAgentStateHydrated(s)) return void 0;
     const values = statewireState.readDeepAgentStreamValues(s);
     const value = values.voiceStartFence ?? values.voiceAttemptId;
     return typeof value === "string" ? value : null;
   });
-  const observedAttemptRef = react.useRef(void 0);
+  const observedAttemptRef = require$$0.useRef(void 0);
   if (observedAttempt !== void 0) observedAttemptRef.current = observedAttempt ?? void 0;
-  const startingRef = react.useRef(false);
-  const startPromiseRef = react.useRef(null);
-  const autoRestartedRef = react.useRef(false);
-  const onRemoteStreamRef = react.useRef(options.onRemoteStream);
+  const startingRef = require$$0.useRef(false);
+  const startPromiseRef = require$$0.useRef(null);
+  const autoRestartedRef = require$$0.useRef(false);
+  const onRemoteStreamRef = require$$0.useRef(options.onRemoteStream);
   onRemoteStreamRef.current = options.onRemoteStream;
-  const audioSessionRef = react.useRef(options.audioSession);
+  const audioSessionRef = require$$0.useRef(options.audioSession);
   audioSessionRef.current = options.audioSession;
-  const transportRef = react.useRef(options.transport ?? "webrtc");
+  const transportRef = require$$0.useRef(options.transport ?? "webrtc");
   transportRef.current = options.transport ?? "webrtc";
-  const relayUrlRef = react.useRef(options.relayUrl);
+  const relayUrlRef = require$$0.useRef(options.relayUrl);
   relayUrlRef.current = options.relayUrl;
-  const livekitAdapterRef = react.useRef(options.livekit);
+  const livekitAdapterRef = require$$0.useRef(options.livekit);
   livekitAdapterRef.current = options.livekit;
-  const modelRef = react.useRef(options.model);
+  const modelRef = require$$0.useRef(options.model);
   modelRef.current = options.model;
-  const onDiagnosticRef = react.useRef(options.onDiagnostic);
+  const onDiagnosticRef = require$$0.useRef(options.onDiagnostic);
   onDiagnosticRef.current = options.onDiagnostic;
-  const timeoutsRef = react.useRef(options.timeouts);
+  const onCallMovedRef = require$$0.useRef(options.onCallMoved);
+  onCallMovedRef.current = options.onCallMoved;
+  const timeoutsRef = require$$0.useRef(options.timeouts);
   timeoutsRef.current = options.timeouts;
-  const phaseRef = react.useRef("idle");
+  const phaseRef = require$$0.useRef("idle");
   phaseRef.current = phase;
-  const attemptStartedAtRef = react.useRef(0);
-  const activeAudioSessionRef = react.useRef(null);
-  const startingAudioSessionRef = react.useRef(null);
-  const audioSessionIdleRef = react.useRef(Promise.resolve());
-  const report = react.useCallback(
+  const attemptStartedAtRef = require$$0.useRef(0);
+  const activeAudioSessionRef = require$$0.useRef(null);
+  const startingAudioSessionRef = require$$0.useRef(null);
+  const audioSessionIdleRef = require$$0.useRef(Promise.resolve());
+  const ownClientIdRef = require$$0.useRef(null);
+  const lastOwnedClientIdRef = require$$0.useRef(null);
+  const transferRef = require$$0.useRef(null);
+  const [movedTo, setMovedTo] = require$$0.useState(null);
+  const hydratedTransferCapable = reactStatewire.useStatewireState(
+    (s) => statewireState.isDeepAgentStateHydrated(s) ? "voiceOwner" in statewireState.readDeepAgentStreamValues(s) : void 0
+  );
+  const hydratedVoiceOwner = reactStatewire.useStatewireState(
+    (s) => statewireState.isDeepAgentStateHydrated(s) ? statewireState.readDeepAgentStreamValues(s).voiceOwner ?? null : void 0
+  );
+  const hydratedWireOwnerId = reactStatewire.useStatewireState((s) => {
+    if (!statewireState.isDeepAgentStateHydrated(s)) return void 0;
+    const wire = statewireState.readDeepAgentStreamValues(s).voice;
+    return typeof (wire == null ? void 0 : wire.clientId) === "string" && wire.clientId !== "" ? wire.clientId : null;
+  });
+  const hydratedWireLive = reactStatewire.useStatewireState((s) => {
+    if (!statewireState.isDeepAgentStateHydrated(s)) return void 0;
+    const wire = statewireState.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 = require$$0.useMemo(
+    () => transferCapable ? parseVoiceOwner(wireVoiceOwner) : null,
+    [transferCapable, wireVoiceOwner]
+  );
+  const transferCapableRef = require$$0.useRef(transferCapable);
+  transferCapableRef.current = transferCapable;
+  const voiceOwnerRef = require$$0.useRef(voiceOwner);
+  voiceOwnerRef.current = voiceOwner;
+  const wireOwnerIdRef = require$$0.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 = require$$0.useMemo(
+    () => elsewhereSurface === null || elsewhereSince === null ? null : { surface: elsewhereSurface, since: elsewhereSince },
+    [elsewhereSurface, elsewhereSince]
+  );
+  const liveElsewhereRef = require$$0.useRef(liveElsewhere);
+  liveElsewhereRef.current = liveElsewhere;
+  const report = require$$0.useCallback(
     (event, attempt, data) => {
       const observer = onDiagnosticRef.current;
       if (!observer) return;
@@ -360,13 +493,21 @@ const useDeepAgentVoice = (options = {}) => {
     },
     []
   );
-  const releaseAudioSession = react.useCallback(() => {
+  const releaseAudioSession = require$$0.useCallback(() => {
     const session = activeAudioSessionRef.current;
     if (!session) return;
     activeAudioSessionRef.current = null;
     audioSessionIdleRef.current = audioSessionIdleRef.current.then(() => session.stop()).catch(() => void 0);
   }, []);
-  const teardown = react.useCallback(() => {
+  const notifyCallMoved = require$$0.useCallback((move) => {
+    const observer = onCallMovedRef.current;
+    if (!observer) return;
+    try {
+      void Promise.resolve(observer(move)).catch(() => void 0);
+    } catch {
+    }
+  }, []);
+  const teardown = require$$0.useCallback((options2) => {
     attemptRef.current += 1;
     const livekitAbort = livekitAbortRef.current;
     livekitAbortRef.current = null;
@@ -375,7 +516,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());
@@ -406,7 +547,7 @@ const useDeepAgentVoice = (options = {}) => {
       return (_a = onRemoteStreamRef.current) == null ? void 0 : _a.call(onRemoteStreamRef, null);
     });
   }, [releaseAudioSession]);
-  const fail = react.useCallback(
+  const fail = require$$0.useCallback(
     (nextFailure) => {
       report("error", attemptRef.current, {
         kind: nextFailure.kind,
@@ -423,10 +564,105 @@ const useDeepAgentVoice = (options = {}) => {
     },
     [report, teardown]
   );
-  const handleMediaLossRef = react.useRef(
+  const handleMovedAway = require$$0.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 = require$$0.useCallback(() => {
+    const own = ownClientIdRef.current;
+    const current = wireOwnerIdRef.current;
+    return transferCapableRef.current && own !== null && current !== null && current !== own;
+  }, []);
+  const acquireAudioSession = require$$0.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 = require$$0.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 = require$$0.useRef(
     async () => void 0
   );
-  const watchConnection = react.useCallback((pc, attempt) => {
+  const watchConnection = require$$0.useCallback((pc, attempt) => {
     let disconnectTimer = null;
     const clearDisconnectTimer = () => {
       if (disconnectTimer === null) return;
@@ -467,7 +703,7 @@ const useDeepAgentVoice = (options = {}) => {
       releaseSafely(() => pc.removeEventListener("iceconnectionstatechange", onChange));
     };
   }, [report]);
-  const playRelayChunk = react.useCallback((audio, data) => {
+  const playRelayChunk = require$$0.useCallback((audio, data) => {
     const pcm = new Int16Array(data);
     if (pcm.length === 0) return;
     const samples = float32FromPcm16(pcm);
@@ -480,12 +716,15 @@ const useDeepAgentVoice = (options = {}) => {
     node.start(startAt);
     playheadRef.current = startAt + buffer.duration;
   }, []);
-  const runStartSession = react.useCallback(async () => {
+  const runStartSession = require$$0.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);
@@ -499,7 +738,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;
@@ -521,23 +763,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;
@@ -547,7 +773,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";
@@ -592,34 +819,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);
@@ -781,10 +990,19 @@ const useDeepAgentVoice = (options = {}) => {
     } finally {
       startingRef.current = false;
     }
-  }, [fail, playRelayChunk, releaseAudioSession, report, sendCommand, watchConnection]);
-  const startSession = react.useCallback(async () => {
+  }, [
+    acquireAudioSession,
+    fail,
+    joinVoiceRoom,
+    playRelayChunk,
+    releaseAudioSession,
+    report,
+    sendCommand,
+    watchConnection
+  ]);
+  const startSession = require$$0.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;
@@ -792,18 +1010,23 @@ const useDeepAgentVoice = (options = {}) => {
       if (startPromiseRef.current === run) startPromiseRef.current = null;
     }
   }, [runStartSession]);
-  const startRef = react.useRef(startSession);
+  const startRef = require$$0.useRef(startSession);
   startRef.current = startSession;
-  const handleMediaLoss = react.useCallback(
+  const handleMediaLoss = require$$0.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;
@@ -820,6 +1043,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 });
@@ -842,69 +1069,284 @@ const useDeepAgentVoice = (options = {}) => {
       setFailure(lost);
       setPhase("error");
     },
-    [report, sendCommand, teardown]
+    [handleMovedAway, ownerMovedAway, report, sendCommand, teardown]
   );
   handleMediaLossRef.current = handleMediaLoss;
-  const start = react.useCallback(async () => {
+  const start = require$$0.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 end = react.useCallback(() => {
+  const runTransferHere = require$$0.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 = require$$0.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 = require$$0.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 = require$$0.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]);
-  const setMicMuted = react.useCallback(
+  }, [phase, releaseCall, report, teardown]);
+  const setMicMuted = require$$0.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 = reactStatewire.useStatewireState(
     (s) => statewireState.isDeepAgentStateHydrated(s) && (statewireState.readDeepAgentStreamValues(s).voice ?? null) === null
   );
-  react.useEffect(() => {
+  require$$0.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]);
-  react.useEffect(
+  require$$0.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]);
+  require$$0.useEffect(
     () => () => {
       const phaseAtUnmount = phaseRef.current;
       if (phaseAtUnmount === "connecting" || phaseAtUnmount === "live") {
@@ -912,14 +1354,15 @@ 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;
-  react.useEffect(() => {
+  require$$0.useEffect(() => {
     if (phase === "live") lastActiveTaskRef.current = activeTask;
     else if (phase === "idle" || phase === "error") lastActiveTaskRef.current = null;
   }, [phase, activeTask]);
@@ -928,7 +1371,7 @@ const useDeepAgentVoice = (options = {}) => {
     const status = statewireState.readDeepAgentStreamValues(s).status;
     return status === "running" || status === "stopping" || status === "input-required";
   });
-  react.useEffect(() => {
+  require$$0.useEffect(() => {
     if (handoffTask !== null && !handoffRunActive) setHandoffTask(null);
   }, [handoffTask, handoffRunActive]);
   const wireError = reactStatewire.useStatewireState(
@@ -943,19 +1386,19 @@ const useDeepAgentVoice = (options = {}) => {
   const wireModelOptions = reactStatewire.useStatewireState(
     (s) => statewireState.isDeepAgentStateHydrated(s) ? statewireState.readDeepAgentStreamValues(s).voiceModelOptions ?? null : null
   );
-  const modelOptionsRef = react.useRef(null);
-  const modelOptions = react.useMemo(() => {
+  const modelOptionsRef = require$$0.useRef(null);
+  const modelOptions = require$$0.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 = react.useCallback(() => {
+  const syncProfile = require$$0.useCallback(() => {
     if (phase !== "connecting" && phase !== "live") return;
     void sendCommand({ type: "voice/profile-sync", attemptId: callAttemptIdRef.current }).catch(() => void 0);
   }, [phase, sendCommand]);
-  const sendContext = react.useCallback(
+  const sendContext = require$$0.useCallback(
     (text) => {
       const trimmed = text.trim();
       if (phase !== "live" || !trimmed) return;
@@ -963,7 +1406,7 @@ const useDeepAgentVoice = (options = {}) => {
     },
     [phase, sendCommand]
   );
-  const sendUserText = react.useCallback(
+  const sendUserText = require$$0.useCallback(
     async (text) => {
       if (phase !== "live" || !text.trim()) return false;
       const messageId = mintVoiceId({ kind: "text" });
@@ -976,7 +1419,7 @@ const useDeepAgentVoice = (options = {}) => {
     },
     [phase, sendCommand]
   );
-  return react.useMemo(
+  return require$$0.useMemo(
     () => ({
       phase,
       error,
@@ -993,7 +1436,10 @@ const useDeepAgentVoice = (options = {}) => {
       notice,
       sendContext,
       model,
-      modelOptions
+      modelOptions,
+      liveElsewhere,
+      transferHere,
+      movedTo
     }),
     [
       phase,
@@ -1011,24 +1457,36 @@ const useDeepAgentVoice = (options = {}) => {
       notice,
       sendContext,
       model,
-      modelOptions
+      modelOptions,
+      liveElsewhere,
+      transferHere,
+      movedTo
     ]
   );
 };
+exports.VOICE_CONTINUE_BY_VOICE_LABEL = VOICE_CONTINUE_BY_VOICE_LABEL;
 exports.VOICE_LIVEKIT_ANSWER_PREFIX = VOICE_LIVEKIT_ANSWER_PREFIX;
 exports.VOICE_LIVEKIT_OFFER = VOICE_LIVEKIT_OFFER;
+exports.VOICE_MOVED_NOTICE_MS = VOICE_MOVED_NOTICE_MS;
+exports.VOICE_MOVE_CALL_HERE_LABEL = VOICE_MOVE_CALL_HERE_LABEL;
+exports.VOICE_MOVE_HERE_ACTION = VOICE_MOVE_HERE_ACTION;
 exports.VOICE_RELAY_ANSWER_PREFIX = VOICE_RELAY_ANSWER_PREFIX;
 exports.VOICE_RELAY_SAMPLE_RATE = VOICE_RELAY_SAMPLE_RATE;
 exports.VOICE_WEBSOCKET_OFFER = VOICE_WEBSOCKET_OFFER;
 exports.classifyVoiceStartError = classifyVoiceStartError;
 exports.describeVoiceFailure = describeVoiceFailure;
+exports.describeVoiceLiveElsewhere = describeVoiceLiveElsewhere;
+exports.describeVoiceMovedTo = describeVoiceMovedTo;
 exports.describeVoiceWireError = describeVoiceWireError;
 exports.float32FromPcm16 = float32FromPcm16;
 exports.formatVoiceElapsed = formatVoiceElapsed;
 exports.parseVoiceLiveKitAnswer = parseVoiceLiveKitAnswer;
 exports.parseVoiceModelOptions = parseVoiceModelOptions;
+exports.parseVoiceOwner = parseVoiceOwner;
 exports.pcm16FromFloat32 = pcm16FromFloat32;
 exports.useDeepAgentVoice = useDeepAgentVoice;
 exports.useVoiceElapsed = useVoiceElapsed;
+exports.useVoiceMovedNotice = useVoiceMovedNotice;
 exports.voiceRelayUrl = voiceRelayUrl;
+exports.voiceSurfaceLabel = voiceSurfaceLabel;
 //# sourceMappingURL=use-deep-agent-voice.cjs.map