@athenaintel/react 0.48.0 → 0.52.1

package/dist/agent-runtime/src/use-deep-agent-voice.d.ts

@@ -1,5 +1,7 @@
+import type { VoiceMediaEvent } from './voice-media';
 import type { DeepAgentVoiceOwnerWireState, DeepAgentVoiceSurface, DeepAgentVoiceWireError } from './voice-wire-types';
 export type { DeepAgentVoiceOwnerWireState, DeepAgentVoiceSurface, DeepAgentVoiceTransferWireState, } from './voice-wire-types';
+export { playVoiceMoveEarcon, VOICE_MOVE_EARCON_MS, VOICE_MOVE_EARCON_PEAK, VOICE_MOVE_EARCON_SAMPLE_RATE, voiceMoveEarconDataUri, voiceMoveEarconSamples, voiceMoveEarconWav, } from './voice-earcon';
 declare module '@assistant-ui/core' {
     namespace Assistant {
         interface Commands {
@@ -180,7 +182,13 @@ export interface DeepAgentVoiceFailure {
  */
 export type DeepAgentVoiceDiagnosticEvent = 'start-requested' | 'audio-session-ready' | 'microphone-captured' | 'offer-ready' | 'ice-gathering-timeout' | 'answer-received' | 'room-joined' | 'live' | 'media-state' | 'media-loss' | 'auto-restart' | 'server-ended' | 'end' | 'error' | 'stale-attempt'
 /** The live call moved to another of the person's devices; this client let go of it. */
- | 'moved';
+ | 'moved'
+/**
+ * The platform's room reported something about the call's media (the
+ * adapter's `onEvent`): `data.type` names it — a reconnect, the agent
+ * leaving, connection quality, an audio-quality sample or summary.
+ */
+ | 'media-event';
 export interface DeepAgentVoiceDiagnostic {
     event: DeepAgentVoiceDiagnosticEvent;
     attempt: number;
@@ -277,6 +285,11 @@ export interface DeepAgentVoiceLiveKitAdapter {
         /** Abort a pending join and release media when this attempt ends. */
         signal?: AbortSignal;
         onDisconnected: (reason: string) => void;
+        /**
+         * Media telemetry while the room lasts (reconnects, the agent leaving,
+         * audio quality); reported as `media-event` diagnostics. Optional.
+         */
+        onEvent?: (event: VoiceMediaEvent) => void;
     }): Promise<DeepAgentVoiceLiveKitSession>;
 }
 /** One realtime model the host offers for voice sessions (`state.voiceModelOptions`). */
@@ -355,6 +368,13 @@ export declare const voiceRelayUrl: (relayUrl: string, ticket: string) => string
 export declare const pcm16FromFloat32: (samples: Float32Array) => Int16Array;
 /** PCM16 → Float32 samples in [-1, 1] for Web Audio playback. */
 export declare const float32FromPcm16: (pcm: Int16Array) => Float32Array;
+/** A call this device held or took moving between the person's own devices; see `onCallMoved`. */
+export interface DeepAgentVoiceCallMove {
+    /** `here`: this device now holds the call. `away`: the call left this device. */
+    direction: 'here' | 'away';
+    /** The other device: where the call came from (`here`) or went (`away`). */
+    surface: DeepAgentVoiceSurface;
+}
 export interface UseDeepAgentVoiceOptions {
     /**
      * Remote-audio sink: called with the remote stream when the session answers
@@ -405,6 +425,19 @@ export interface UseDeepAgentVoiceOptions {
      * fresh closure never restarts anything. Must not throw.
      */
     onDiagnostic?: (entry: DeepAgentVoiceDiagnostic) => void;
+    /**
+     * Called when this device's call moves between the person's own devices:
+     * `here` once {@link UseDeepAgentVoiceReturn.transferHere} took the call
+     * (it is live here), `away` when the host moved it to another device
+     * (alongside `movedTo`). Hosts play the move earcon from it
+     * ({@link playVoiceMoveEarcon} on the web). For `away` it runs before the
+     * hook lets go of the call's platform audio session, which it then releases
+     * at once (`audioSession.stop`): a host that plays the cue inside that
+     * session holds the session's stop itself, in its shared session queue, so
+     * a chat started meanwhile waits rather than finds the session taken. Read
+     * through a per-render ref; a throw or a rejected promise is ignored.
+     */
+    onCallMoved?: (move: DeepAgentVoiceCallMove) => void | Promise<void>;
     /** Per-surface overrides of the negotiation deadlines (ms). */
     timeouts?: {
         /** How long to wait for ICE gathering to complete before sending the offer with the candidates so far. */

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

@@ -419,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");
@@ -495,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;
@@ -504,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());
@@ -556,6 +566,7 @@ const useDeepAgentVoice = (options = {}) => {
     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;
@@ -564,7 +575,7 @@ const useDeepAgentVoice = (options = {}) => {
     setFailure(null);
     setPhase("idle");
     setMovedTo({ surface });
-  }, [report, teardown]);
+  }, [notifyCallMoved, report, teardown]);
   const ownerMovedAway = useCallback(() => {
     const own = ownClientIdRef.current;
     const current = wireOwnerIdRef.current;
@@ -575,11 +586,17 @@ const useDeepAgentVoice = (options = {}) => {
       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();
@@ -618,6 +635,11 @@ const useDeepAgentVoice = (options = {}) => {
             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) {
@@ -995,13 +1017,14 @@ const useDeepAgentVoice = (options = {}) => {
         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;
@@ -1057,6 +1080,8 @@ const useDeepAgentVoice = (options = {}) => {
     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;
@@ -1183,6 +1208,7 @@ const useDeepAgentVoice = (options = {}) => {
       report("live", attempt, { transport: "livekit", transfer: true });
       setPhase("live");
       setLiveSince(Date.now());
+      notifyCallMoved({ direction: "here", surface: fromSurface });
     } catch (transferError) {
       if (attemptRef.current !== attempt) {
         stale();
@@ -1197,7 +1223,15 @@ const useDeepAgentVoice = (options = {}) => {
     } finally {
       startingRef.current = false;
     }
-  }, [acquireAudioSession, fail, joinVoiceRoom, releaseAudioSession, report, sendCommand]);
+  }, [
+    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;
@@ -1285,13 +1319,14 @@ 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));