@athenaintel/react 0.43.0 → 0.50.0

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

@@ -1,4 +1,7 @@
-import type { DeepAgentVoiceWireError } from './voice-wire-types';
+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 {
@@ -9,6 +12,10 @@ declare module '@assistant-ui/core' {
              * {@link VOICE_LIVEKIT_OFFER} to request a LiveKit room (the answer is
              * then the room's join credentials). `model` picks the realtime model
              * (`gpt-live-1`, `gemini-3.8-live`, …); omitted → the host's default.
+             * `opening: 'recap'` asks the model to open by saying where the
+             * conversation stands (a call continued from another device); the host
+             * applies it only to a thread with history and a profile that speaks
+             * first.
              */
             voiceStart: {
                 type: 'voice/start';
@@ -17,6 +24,7 @@ declare module '@assistant-ui/core' {
                 /** Correlates commands with this call, including delayed cleanup. */
                 attemptId?: string;
                 previousAttemptId?: string;
+                opening?: DeepAgentVoiceOpening;
             };
             /** Ends the live voice session (`DeepAgentThread.voice_end`). */
             voiceEnd: {
@@ -67,6 +75,32 @@ declare module '@assistant-ui/core' {
                 attemptId?: string;
                 text: string;
             };
+            /**
+             * Ask to take the conversation's live call from another of the caller's
+             * own devices (`DeepAgentThread.voice_transfer_offer`, LiveKit sessions
+             * only). `attemptId` is a fresh call attempt id, minted like
+             * `voice/start`'s; the result is `{ answer, transferId }`, `answer` in
+             * `voice/start`'s LiveKit format with a join token for this client.
+             */
+            voiceTransferOffer: {
+                type: 'voice/transfer-offer';
+                attemptId: string;
+            };
+            /**
+             * Sent once this client has joined the room and published its
+             * microphone: the host moves the call's owner, media input and attempt
+             * fence to this client (`DeepAgentThread.voice_transfer_commit`).
+             */
+            voiceTransferCommit: {
+                type: 'voice/transfer-commit';
+                transferId: string;
+                attemptId: string;
+            };
+            /** Withdraw a pending transfer; idempotent (`DeepAgentThread.voice_transfer_cancel`). */
+            voiceTransferCancel: {
+                type: 'voice/transfer-cancel';
+                transferId: string;
+            };
         }
     }
 }
@@ -90,17 +124,38 @@ export interface DeepAgentVoiceWireState {
     } | null;
 }
 export type DeepAgentVoicePhase = 'idle' | 'connecting' | 'live' | 'error';
+/**
+ * How the realtime model opens a call: `recap` says where the conversation
+ * stands first (mirrors agora's `VOICE_RECAP_OPENING`).
+ */
+export type DeepAgentVoiceOpening = 'recap';
+/** Options of a user start (`useDeepAgentVoice().start`). */
+export interface DeepAgentVoiceStartOptions {
+    /**
+     * Ask the model to open with a recap: the one-tap "Continue by voice" after
+     * a handover the person sent in voice mode. Sent on this start's
+     * `voice/start` only, never on the automatic restart or a transfer.
+     */
+    opening?: DeepAgentVoiceOpening;
+}
 /**
  * Why a voice session failed, classified where the failure happened rather
  * than by parsing the message afterwards. `server_rejected` carries the
  * host's structured code (`voice-active`, `voice-not-enabled`,
  * `voice-unavailable`, `checkpointer_unavailable`, …); `media_lost` carries the
- * transport state that ended the session. Every surface reports and words the
- * same kinds, so telemetry across Olympus, Chrome, and mobile joins on them.
+ * transport state that ended the session. `transfer_failed` is a move of a
+ * call live on another of the person's devices that did not complete (the
+ * call stays there): `reason` names the underlying kind (`server_rejected`,
+ * `room_failed`, `microphone_denied`, `answer_timeout`, …) and `code` the
+ * host's rejection reason (`voice-transfer-busy`, `voice-transfer-media`, …).
+ * Every surface reports and words the same kinds, so telemetry across
+ * Olympus, Chrome, and mobile joins on them.
  */
-export type DeepAgentVoiceFailureKind = 'unsupported' | 'audio_session' | 'microphone_denied' | 'capture_failed' | 'offer_failed' | 'answer_timeout' | 'server_rejected' | 'command_failed' | 'no_answer' | 'answer_failed' | 'relay_failed' | 'room_failed' | 'playback_failed' | 'media_lost' | 'unknown';
+export type DeepAgentVoiceFailureKind = 'unsupported' | 'audio_session' | 'microphone_denied' | 'capture_failed' | 'offer_failed' | 'answer_timeout' | 'server_rejected' | 'command_failed' | 'no_answer' | 'answer_failed' | 'relay_failed' | 'room_failed' | 'playback_failed' | 'media_lost' | 'transfer_failed' | 'unknown';
 /** Where in the session's lifecycle a failure happened. */
-export type DeepAgentVoiceFailureStage = 'preflight' | 'audio-session' | 'capture' | 'offer' | 'negotiate' | 'answer' | 'relay' | 'room' | 'media' | 'playback';
+export type DeepAgentVoiceFailureStage = 'preflight' | 'audio-session' | 'capture' | 'offer' | 'negotiate' | 'answer' | 'relay' | 'room' | 'media' | 'playback'
+/** `voice/transfer-commit`: the host moving a call to this client. */
+ | 'commit';
 export interface DeepAgentVoiceFailure {
     kind: DeepAgentVoiceFailureKind;
     stage: DeepAgentVoiceFailureStage;
@@ -114,9 +169,9 @@ export interface DeepAgentVoiceFailure {
     fate?: string;
     /**
      * The lower-level reason: the media state that ended the session
-     * (`failed` / `closed` / `disconnected` / `relay-closed` / `relay-error`), or
+     * (`failed` / `closed` / `disconnected` / `relay-closed` / `relay-error`),
      * the channel death that settled the command (`unmount` / `stream-gone` /
-     * `session-lost`).
+     * `session-lost`), or, for `transfer_failed`, the underlying failure kind.
      */
     reason?: string;
 }
@@ -125,7 +180,15 @@ export interface DeepAgentVoiceFailure {
  * (crash breadcrumbs, latency telemetry). `attempt` groups one start's
  * events; `sinceStartMs` is measured from that attempt's `start-requested`.
  */
-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';
+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'
+/**
+ * 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;
@@ -222,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`). */
@@ -257,6 +325,38 @@ export declare const formatVoiceElapsed: (sinceMs: number, nowMs?: number) => st
  * Returns `null` when there is no live session. Callers isolate it in a
  * leaf component so only that leaf re-renders per second. */
 export declare const useVoiceElapsed: (since: number | null) => string | null;
+/** How the person's own device of a kind is named in voice copy ("your phone"). */
+export declare const voiceSurfaceLabel: (surface: DeepAgentVoiceSurface) => string;
+/** The mic control's label while the call is live on another of the person's devices. */
+export declare const VOICE_MOVE_CALL_HERE_LABEL = "Move call here";
+/** The action on the live-elsewhere banner. */
+export declare const VOICE_MOVE_HERE_ACTION = "Move here";
+/**
+ * The one-tap offer a destination shows after a handover the person sent in
+ * voice mode; it starts a call with the recap opening (`start({ opening:
+ * 'recap' })`), never on its own.
+ */
+export declare const VOICE_CONTINUE_BY_VOICE_LABEL = "Continue by voice";
+/** The live-elsewhere banner's text, before its {@link VOICE_MOVE_HERE_ACTION}. */
+export declare const describeVoiceLiveElsewhere: (surface: DeepAgentVoiceSurface) => string;
+/** The notice on the device a call just moved away from. */
+export declare const describeVoiceMovedTo: (surface: DeepAgentVoiceSurface) => string;
+/** How long the moved notice stays up. */
+export declare const VOICE_MOVED_NOTICE_MS = 6000;
+/**
+ * The transient "Call moved to your …" notice for a hook's `movedTo`: the
+ * words for {@link VOICE_MOVED_NOTICE_MS} after each move, then `null`. One
+ * implementation so every surface keeps it up equally long.
+ */
+export declare const useVoiceMovedNotice: (movedTo: {
+    surface: DeepAgentVoiceSurface;
+} | null) => string | null;
+/**
+ * Validate the host's `state.voiceOwner`: `null` when absent or malformed. An
+ * unknown surface reads as `web`, as the host labels any client it does not
+ * recognize; anything but `transferable: true` cannot move.
+ */
+export declare const parseVoiceOwner: (value: unknown) => DeepAgentVoiceOwnerWireState | null;
 /**
  * One-line, user-facing rendering of a Live API rejection the host projected
  * (`state.voiceLastError`). Shared so every surface words the notice alike.
@@ -268,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
@@ -318,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. */
@@ -326,6 +446,8 @@ export interface UseDeepAgentVoiceOptions {
         answerMs?: number;
         /** How long the relay WebSocket may take to open (`websocket` transport). */
         relayOpenMs?: number;
+        /** How long `voice/transfer-commit` may take to move a call here (default 15 s). */
+        transferCommitMs?: number;
     };
 }
 export interface UseDeepAgentVoiceReturn {
@@ -338,7 +460,8 @@ export interface UseDeepAgentVoiceReturn {
      * rejection, the host's reason code — the key telemetry and support join on.
      */
     failure: DeepAgentVoiceFailure | null;
-    start: () => Promise<void>;
+    /** Start a call: a user action (it re-arms the one-shot restart); see {@link DeepAgentVoiceStartOptions}. */
+    start: (options?: DeepAgentVoiceStartOptions) => Promise<void>;
     end: () => void;
     /** The delegated voice task currently running server-side, if any. */
     activeTask: {
@@ -406,6 +529,36 @@ export interface UseDeepAgentVoiceReturn {
      * not publish them — surfaces fall back to their static list.
      */
     modelOptions: DeepAgentVoiceModelOption[] | null;
+    /**
+     * The call live on another of the person's own devices that this one can
+     * take: set while the thread's session is live, the host projects its owner
+     * as transferable (`state.voiceOwner`), this hook holds no media (`idle` or
+     * `error`) and its transport is `livekit`. `null` otherwise, and always on a
+     * host that cannot move calls (it never projects `voiceOwner`). Surfaces
+     * turn the mic into "Move call here" and show a banner from it.
+     */
+    liveElsewhere: {
+        surface: DeepAgentVoiceSurface;
+        since: number;
+    } | null;
+    /**
+     * Move the call named by `liveElsewhere` to this device: offer, join the
+     * room, commit, then `live`. A move that does not complete withdraws the
+     * offer, releases the room and settles to `error` with
+     * `failure.kind === 'transfer_failed'` while the call stays on the other
+     * device. A user action, like `start`: re-arms the one-shot restart. A
+     * no-op without `liveElsewhere`.
+     */
+    transferHere: () => Promise<void>;
+    /**
+     * Where this device's live call just moved: set when the host moves the
+     * session's owner to another client (this hook let go of its media without
+     * ending the call), cleared by the next `start` or `transferHere`. Surfaces
+     * show a transient notice ({@link useVoiceMovedNotice}).
+     */
+    movedTo: {
+        surface: DeepAgentVoiceSurface;
+    } | null;
 }
 /**
  * The experimental voice-mode session against the thread's `voice/start` /
@@ -414,4 +567,3 @@ export interface UseDeepAgentVoiceReturn {
  * log as `ephemeral: true` entries in `state.messages`.
  */
 export declare const useDeepAgentVoice: (options?: UseDeepAgentVoiceOptions) => UseDeepAgentVoiceReturn;
-export {};