@voxevolv/client 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,8 +1,8 @@
-import { ConnectionState as LiveKitConnectionState, DataPacket_Kind, Room, RoomEvent, RpcError, Track, } from "livekit-client";
+import { ConnectionState as LiveKitConnectionState, DataPacket_Kind, DisconnectReason, Room, RoomEvent, RpcError, Track, } from "livekit-client";
 import { createClientMessage, CommandError, EventCursor, isCommandAckPayload, isCommandErrorPayload, isContextRejectedPayload, isContextUpdatePayload, isContextUpdatedPayload, isRealtimeEvent, } from "./protocol.js";
 export { CommandError, EventCursor, createClientMessage, isCommandAckPayload, isCommandErrorPayload, isContextRejectedPayload, isContextUpdatePayload, isContextUpdatedPayload, isRealtimeEvent, } from "./protocol.js";
 export { decodeAgentSnapshotPayload, decodeClientHelloPayload, decodeClientMessage, decodeCommandAckPayload, decodeCommandErrorPayload, decodeContextRejectedPayload, decodeContextUpdatePayload, decodeContextUpdatedPayload, decodeRealtimeEvent, } from "./generated/protocol-codecs.js";
-export const SDK_VERSION = "0.1.0";
+export const SDK_VERSION = "0.3.0";
 export class RealtimeSessionHttpError extends Error {
     status;
     code;
@@ -26,6 +26,8 @@ export class RealtimeSession {
     listeners = new Set();
     stateListeners = new Set();
     gapListeners = new Set();
+    connectionQualityListeners = new Set();
+    recoveryListeners = new Set();
     remoteAudioTrackListeners = new Set();
     remoteAudioTrackUnsubscribedListeners = new Set();
     readyListeners = new Set();
@@ -36,22 +38,35 @@ export class RealtimeSession {
     toolCallListeners = new Set();
     audioPlaybackBlockedListeners = new Set();
     remoteAudioStreams = new WeakMap();
+    outputMediaStream = null;
+    remoteAudioTrackResolve = null;
     cursor = new EventCursor();
     connectionId = `conn_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
     clientSeq = 0;
     lastHelloMessageId = null;
+    reconnectStartedAt = null;
+    pendingReconnect = null;
     agentReady = false;
     readyResolve = null;
     replayPromise = null;
     pendingCommands = new Map();
     toolHandlers = new Map();
     apiBase = "/v1";
+    hasConnectedValue = false;
+    sessionEnded = false;
+    disconnectMode = null;
+    activeRecovery = null;
+    autoRejoinPromise = null;
+    autoRejoinController = null;
     useManagedMicrophone = true;
+    managedMicrophoneEnabled = true;
     applicationAudioTrack = null;
     connectDefaults;
     fetcher;
     endEndpoint;
     refreshCredentialsCallback;
+    autoRejoinOptions;
+    lifecycleCredentials;
     constructor(credentials, options = {}) {
         validateSessionCredentials(credentials);
         this.id = credentials.id;
@@ -64,6 +79,8 @@ export class RealtimeSession {
         this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.endEndpoint = options.endEndpoint ?? null;
         this.refreshCredentialsCallback = options.refreshCredentials ?? null;
+        this.autoRejoinOptions = resolveAutoRejoinOptions(options.autoRejoin);
+        this.lifecycleCredentials = options.lifecycleCredentials ?? "same-origin";
         this.room = new Room({ adaptiveStream: true, dynacast: true });
         for (const [name, handler] of Object.entries(options.tools ?? {})) {
             this.registerTool(name, handler);
@@ -107,7 +124,7 @@ export class RealtimeSession {
         if ("connect" in options) {
             throw new TypeError("RealtimeSession.create() accepts apiBase and media options at the top level, not in connect");
         }
-        const { endpoint, request, microphone, audioTrack, readyTimeoutMs, apiBase, ...sessionOptions } = options;
+        const { endpoint, request, microphone, audioTrack, readyTimeoutMs, waitForRemoteAudio, apiBase, ...sessionOptions } = options;
         if (!endpoint)
             throw new TypeError("endpoint is required");
         if (!apiBase) {
@@ -122,12 +139,24 @@ export class RealtimeSession {
         return new RealtimeSession(credentials, {
             ...sessionOptions,
             fetch: fetcher,
-            connect: { microphone, audioTrack, readyTimeoutMs, apiBase: normalizedApiBase },
+            connect: { microphone, audioTrack, readyTimeoutMs, waitForRemoteAudio, apiBase: normalizedApiBase },
         });
     }
     get state() {
         return this.stateValue;
     }
+    get hasConnectedBefore() {
+        return this.hasConnectedValue;
+    }
+    /**
+     * Stable stream holding the agent's current remote audio tracks. The stream
+     * object never changes across track arrival, reconnects, or rejoin; tracks
+     * are added and removed as the room subscribes and unsubscribes them.
+     */
+    get outputStream() {
+        this.outputMediaStream ??= new MediaStream();
+        return this.outputMediaStream;
+    }
     onEvent(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -141,6 +170,57 @@ export class RealtimeSession {
         this.gapListeners.add(listener);
         return () => this.gapListeners.delete(listener);
     }
+    onConnectionQuality(listener) {
+        this.connectionQualityListeners.add(listener);
+        this.notifyListeners(new Set([listener]), this.room.localParticipant.connectionQuality);
+        return () => this.connectionQualityListeners.delete(listener);
+    }
+    onRecovery(listener) {
+        this.recoveryListeners.add(listener);
+        return () => this.recoveryListeners.delete(listener);
+    }
+    waitForState(states, timeoutMs, options = {}) {
+        if (!states.length)
+            throw new TypeError("states must contain at least one connection state");
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new TypeError("timeoutMs must be a non-negative finite number");
+        }
+        const targets = new Set(states);
+        if (targets.has(this.stateValue))
+            return Promise.resolve(this.stateValue);
+        if (options.signal?.aborted) {
+            return Promise.reject(options.signal.reason ?? new DOMException("Aborted", "AbortError"));
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (state, error) => {
+                if (settled)
+                    return;
+                settled = true;
+                globalThis.clearTimeout(timeout);
+                this.stateListeners.delete(onState);
+                options.signal?.removeEventListener("abort", onAbort);
+                if (error !== undefined) {
+                    reject(error);
+                }
+                else if (state !== null) {
+                    resolve(state);
+                }
+            };
+            const onState = (state) => {
+                if (targets.has(state))
+                    finish(state);
+            };
+            const onAbort = () => {
+                finish(null, options.signal?.reason ?? new DOMException("Aborted", "AbortError"));
+            };
+            const timeout = globalThis.setTimeout(() => {
+                finish(null, new Error(`Session did not reach ${states.join(" or ")} within ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.stateListeners.add(onState);
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
     onRemoteAudioTrack(listener) {
         this.remoteAudioTrackListeners.add(listener);
         return () => this.remoteAudioTrackListeners.delete(listener);
@@ -178,7 +258,8 @@ export class RealtimeSession {
         return () => this.audioPlaybackBlockedListeners.delete(listener);
     }
     registerTool(name, handler) {
-        if (["connecting", "connected_not_ready", "connected", "reconnecting"].includes(this.stateValue)) {
+        if (["connecting", "connected_not_ready", "connected", "reconnecting", "resuming"]
+            .includes(this.stateValue)) {
             throw new Error("Browser tools must be registered before connect()");
         }
         if (!/^[a-z][a-z0-9_]{0,79}$/.test(name)) {
@@ -193,69 +274,130 @@ export class RealtimeSession {
         };
     }
     async connect(options = {}) {
-        if (["connecting", "connected_not_ready", "connected", "reconnecting"].includes(this.stateValue)) {
+        if (["connecting", "connected_not_ready", "connected", "reconnecting", "resuming"]
+            .includes(this.stateValue)) {
+            throw new Error(`Cannot connect while session is ${this.stateValue}`);
+        }
+        this.cancelAutoRejoin();
+        await this.connectWithMode(options, false);
+    }
+    async connectWithMode(options, recovering, signal) {
+        const blockedStates = recovering
+            ? ["connecting", "connected_not_ready", "connected", "reconnecting"]
+            : ["connecting", "connected_not_ready", "connected", "reconnecting", "resuming"];
+        if (blockedStates.includes(this.stateValue)) {
             throw new Error(`Cannot connect while session is ${this.stateValue}`);
         }
         const resolved = { ...this.connectDefaults, ...options };
         const audioTrack = resolved.audioTrack ?? null;
         const microphone = resolved.microphone ?? audioTrack === null;
         const readyTimeoutMs = resolved.readyTimeoutMs ?? 15_000;
+        const waitForRemoteAudio = resolved.waitForRemoteAudio ?? true;
         const apiBase = normalizeApiBase(resolved.apiBase ?? this.apiBase);
         this.validateAudioOptions(microphone, audioTrack);
         this.useManagedMicrophone = microphone;
+        if (!recovering)
+            this.managedMicrophoneEnabled = microphone;
         this.applicationAudioTrack = audioTrack;
-        this.setState("connecting");
+        if (!recovering) {
+            this.sessionEnded = false;
+            this.setState("connecting");
+        }
+        else {
+            this.setState("resuming");
+        }
         this.apiBase = apiBase;
         this.agentReady = false;
         try {
             await this.room.connect(this.credentials.url, this.credentials.token);
+            throwIfAborted(signal);
             if (audioTrack) {
                 await this.publishApplicationAudioTrack(audioTrack);
             }
             else if (microphone) {
-                await this.room.localParticipant.setMicrophoneEnabled(true);
+                await this.room.localParticipant.setMicrophoneEnabled(this.managedMicrophoneEnabled);
             }
-            this.setState("connected_not_ready");
+            throwIfAborted(signal);
+            this.setState(recovering ? "resuming" : "connected_not_ready");
             await this.sendHello();
-            await this.waitForAgentReady(readyTimeoutMs);
+            const readyDeadline = Date.now() + readyTimeoutMs;
+            await this.waitForAgentReady(readyTimeoutMs, signal);
+            if (waitForRemoteAudio)
+                await this.waitForRemoteAudioTrack(readyDeadline, signal);
+            throwIfAborted(signal);
+            this.hasConnectedValue = true;
             this.setState("connected");
         }
         catch (error) {
+            this.disconnectMode = recovering ? "rejoin" : "connect_failure";
             try {
                 await this.room.disconnect();
             }
             catch {
                 // Preserve the original connection/readiness failure.
             }
-            this.setState("failed");
+            finally {
+                this.disconnectMode = null;
+            }
+            if (!recovering)
+                this.setState("failed");
             throw error;
         }
     }
     async rejoin(apiBase = this.apiBase) {
-        if (["connecting", "reconnecting"].includes(this.stateValue)) {
+        if (["connecting", "reconnecting", "resuming"].includes(this.stateValue)) {
             throw new Error(`Cannot rejoin while session is ${this.stateValue}`);
         }
+        this.cancelAutoRejoin();
         const normalizedApiBase = normalizeApiBase(apiBase);
-        let response = await this.fetchRoomToken(normalizedApiBase);
+        const recovering = this.hasConnectedValue;
+        if (recovering) {
+            this.beginRecovery("rejoin", 1);
+            this.setState("resuming");
+        }
+        try {
+            await this.performRejoin(normalizedApiBase, undefined, recovering);
+            if (recovering)
+                this.completeRecovery();
+        }
+        catch (error) {
+            const normalizedError = toError(error);
+            if (recovering)
+                this.failRecovery(normalizedError);
+            this.setState("failed");
+            throw error;
+        }
+    }
+    async performRejoin(apiBase, signal, recovering = true) {
+        let response = await this.fetchRoomToken(apiBase, signal);
         if (response.status === 401 && this.refreshCredentialsCallback) {
             await this.refreshCredentials();
-            response = await this.fetchRoomToken(normalizedApiBase);
+            throwIfAborted(signal);
+            response = await this.fetchRoomToken(apiBase, signal);
         }
         if (!response.ok)
             throw await httpError(response, "Could not renew room token");
         const payload = (await response.json());
         this.credentials = payload.connection;
-        if (["connected", "connected_not_ready"].includes(this.stateValue)) {
-            await this.disconnect();
+        if (this.room.state !== LiveKitConnectionState.Disconnected) {
+            this.disconnectMode = "rejoin";
+            try {
+                await this.room.disconnect();
+            }
+            finally {
+                this.disconnectMode = null;
+            }
         }
-        await this.connect({
-            apiBase: normalizedApiBase,
+        throwIfAborted(signal);
+        await this.connectWithMode({
+            apiBase,
             microphone: this.useManagedMicrophone,
             ...(this.applicationAudioTrack ? { audioTrack: this.applicationAudioTrack } : {}),
-        });
+        }, recovering, signal);
     }
     async setMicrophoneEnabled(enabled) {
         await this.room.localParticipant.setMicrophoneEnabled(enabled);
+        this.managedMicrophoneEnabled = enabled;
     }
     async sendCommand(type, payload, timeoutMs = 10_000) {
         const message = createClientMessage(this.connectionId, ++this.clientSeq, type, payload);
@@ -352,13 +494,23 @@ export class RealtimeSession {
         };
     }
     async disconnect() {
+        this.cancelAutoRejoin();
         if (this.stateValue === "disconnected")
             return;
         this.rejectPendingCommands(new Error("Session disconnected before command completion"));
-        await this.room.disconnect();
-        this.setState("disconnected");
+        this.disconnectMode = "intentional";
+        try {
+            await this.room.disconnect();
+        }
+        finally {
+            this.disconnectMode = null;
+            this.activeRecovery = null;
+            this.setState("disconnected");
+        }
     }
     async end(options = {}) {
+        this.cancelAutoRejoin();
+        this.sessionEnded = true;
         const endpoint = options.endpoint ?? this.endEndpoint ?? `${this.apiBase}/sessions/${this.id}`;
         const request = options.request ?? {};
         const headers = new Headers(request.headers);
@@ -370,6 +522,7 @@ export class RealtimeSession {
             ...request,
             method: request.method ?? "DELETE",
             headers,
+            credentials: request.credentials ?? this.lifecycleCredentials,
         });
         if (response.status === 401 && usesScopedSessionEndpoint && this.refreshCredentialsCallback) {
             await this.refreshCredentials();
@@ -378,6 +531,7 @@ export class RealtimeSession {
                 ...request,
                 method: request.method ?? "DELETE",
                 headers,
+                credentials: request.credentials ?? this.lifecycleCredentials,
             });
         }
         if (!response.ok)
@@ -401,27 +555,29 @@ export class RealtimeSession {
         this.notifyListeners(this.stateListeners, state);
     }
     bindRoomEvents() {
-        this.room.on(RoomEvent.Reconnecting, () => {
-            this.agentReady = false;
-            this.rejectPendingCommands(new Error("Connection interrupted before command completion"), true);
-            this.setState("reconnecting");
-        });
+        this.room.on(RoomEvent.SignalReconnecting, () => this.handleLiveKitReconnecting());
+        this.room.on(RoomEvent.Reconnecting, () => this.handleLiveKitReconnecting());
         this.room.on(RoomEvent.Reconnected, () => {
-            this.connectionId = `conn_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
-            this.clientSeq = 0;
-            void this.sendHello().catch(() => this.setState("failed"));
-            this.setState("connected_not_ready");
+            void this.handleLiveKitReconnected();
         });
-        this.room.on(RoomEvent.Disconnected, () => {
-            this.agentReady = false;
-            this.rejectPendingCommands(new Error("Session disconnected before command completion"));
-            this.setState("disconnected");
+        this.room.on(RoomEvent.Disconnected, (reason) => {
+            this.handleLiveKitDisconnected(reason);
         });
         this.room.on(RoomEvent.ConnectionStateChanged, (state) => {
             if (state === LiveKitConnectionState.Connected) {
-                this.setState(this.agentReady ? "connected" : "connected_not_ready");
+                const recovering = this.activeRecovery !== null || this.stateValue === "resuming";
+                this.setState(this.agentReady
+                    ? "connected"
+                    : recovering
+                        ? "resuming"
+                        : "connected_not_ready");
             }
         });
+        this.room.on(RoomEvent.ConnectionQualityChanged, (quality, participant) => {
+            if (!participant.isLocal)
+                return;
+            this.notifyListeners(this.connectionQualityListeners, quality);
+        });
         this.room.on(RoomEvent.TrackSubscribed, (track) => {
             if (track.kind !== Track.Kind.Audio)
                 return;
@@ -448,7 +604,9 @@ export class RealtimeSession {
             }
             const stream = new MediaStream([track.mediaStreamTrack]);
             this.remoteAudioStreams.set(track, stream);
+            this.outputStream.addTrack(track.mediaStreamTrack);
             this.notifyRemoteAudioListeners(this.remoteAudioTrackListeners, track.mediaStreamTrack, stream);
+            this.remoteAudioTrackResolve?.();
         });
         this.room.on(RoomEvent.TrackUnsubscribed, (track) => {
             if (track.kind !== Track.Kind.Audio)
@@ -456,6 +614,7 @@ export class RealtimeSession {
             const stream = this.remoteAudioStreams.get(track) ?? new MediaStream([track.mediaStreamTrack]);
             this.notifyRemoteAudioListeners(this.remoteAudioTrackUnsubscribedListeners, track.mediaStreamTrack, stream);
             this.remoteAudioStreams.delete(track);
+            this.outputMediaStream?.removeTrack(track.mediaStreamTrack);
             track.detach().forEach((element) => element.remove());
         });
         this.room.on(RoomEvent.DataReceived, (data, _participant, kind, topic) => {
@@ -484,6 +643,175 @@ export class RealtimeSession {
             this.notifyListeners(this.listeners, value);
         });
     }
+    handleLiveKitReconnecting() {
+        this.agentReady = false;
+        // Once full rejoin owns recovery, late LiveKit reconnect notifications
+        // from the old transport must not move the wrapper back to reconnecting.
+        // Doing so makes connectWithMode() reject the replacement connection.
+        if (this.autoRejoinPromise !== null
+            || this.activeRecovery?.strategy === "rejoin"
+            || this.disconnectMode === "rejoin") {
+            this.setState("resuming");
+            return;
+        }
+        this.reconnectStartedAt ??= Date.now();
+        this.rejectPendingCommands(new Error("Connection interrupted before command completion"), true);
+        if (this.activeRecovery === null) {
+            this.beginRecovery("livekit", 1);
+        }
+        this.setState("reconnecting");
+    }
+    async handleLiveKitReconnected() {
+        const recoveredAt = Date.now();
+        if (this.reconnectStartedAt !== null) {
+            this.pendingReconnect = {
+                started_at: new Date(this.reconnectStartedAt).toISOString(),
+                recovered_at: new Date(recoveredAt).toISOString(),
+                duration_ms: Math.max(recoveredAt - this.reconnectStartedAt, 0),
+            };
+            this.reconnectStartedAt = null;
+        }
+        if (this.hasConnectedValue && this.activeRecovery === null) {
+            this.beginRecovery("livekit", 1);
+        }
+        this.connectionId = `conn_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
+        this.clientSeq = 0;
+        this.setState(this.hasConnectedValue ? "resuming" : "connected_not_ready");
+        try {
+            await this.sendHello();
+        }
+        catch (error) {
+            const normalizedError = toError(error);
+            if (this.shouldAutoRejoin()) {
+                this.startAutoRejoin(normalizedError);
+            }
+            else {
+                this.failRecovery(normalizedError);
+                this.setState("failed");
+            }
+        }
+    }
+    handleLiveKitDisconnected(reason) {
+        this.agentReady = false;
+        this.reconnectStartedAt = null;
+        this.pendingReconnect = null;
+        // Drop any remaining remote tracks so a stale, ended track cannot
+        // satisfy the next connect()'s wait for agent audio.
+        this.outputMediaStream?.getTracks().forEach((track) => {
+            this.outputMediaStream?.removeTrack(track);
+        });
+        this.rejectPendingCommands(new Error("Session disconnected before command completion"));
+        if (this.disconnectMode === "rejoin")
+            return;
+        if (this.disconnectMode === "connect_failure")
+            return;
+        if (this.disconnectMode === "intentional") {
+            this.activeRecovery = null;
+            this.setState("disconnected");
+            return;
+        }
+        if (this.shouldAutoRejoin(reason)) {
+            this.startAutoRejoin(new Error(`LiveKit disconnected (${disconnectReasonName(reason)})`));
+            return;
+        }
+        if (this.activeRecovery !== null) {
+            this.failRecovery(new Error(`LiveKit disconnected (${disconnectReasonName(reason)})`));
+        }
+        this.setState("disconnected");
+    }
+    beginRecovery(strategy, attempt) {
+        this.activeRecovery = { strategy, attempt };
+        this.notifyListeners(this.recoveryListeners, {
+            status: "started",
+            strategy,
+            attempt,
+        });
+    }
+    completeRecovery() {
+        const recovery = this.activeRecovery;
+        if (!recovery)
+            return;
+        this.activeRecovery = null;
+        this.notifyListeners(this.recoveryListeners, {
+            status: "succeeded",
+            strategy: recovery.strategy,
+            attempt: recovery.attempt,
+        });
+    }
+    failRecovery(error) {
+        const recovery = this.activeRecovery;
+        if (!recovery)
+            return;
+        this.activeRecovery = null;
+        this.notifyListeners(this.recoveryListeners, {
+            status: "failed",
+            strategy: recovery.strategy,
+            attempt: recovery.attempt,
+            error,
+        });
+    }
+    shouldAutoRejoin(reason) {
+        return (this.autoRejoinOptions !== null
+            && this.hasConnectedValue
+            && !this.sessionEnded
+            && !isTerminalDisconnectReason(reason));
+    }
+    startAutoRejoin(initialError) {
+        if (this.autoRejoinPromise || !this.shouldAutoRejoin())
+            return;
+        const controller = new AbortController();
+        this.autoRejoinController = controller;
+        const promise = this.runAutoRejoin(initialError, controller.signal)
+            .finally(() => {
+            if (this.autoRejoinController === controller) {
+                this.autoRejoinController = null;
+                this.autoRejoinPromise = null;
+            }
+        });
+        this.autoRejoinPromise = promise;
+        void promise;
+    }
+    async runAutoRejoin(initialError, signal) {
+        const options = this.autoRejoinOptions;
+        if (!options)
+            return;
+        let lastError = initialError;
+        if (this.activeRecovery?.strategy === "livekit") {
+            this.failRecovery(initialError);
+        }
+        this.setState("resuming");
+        for (let attempt = 1; attempt <= options.maxAttempts; attempt += 1) {
+            try {
+                await waitUntilOnline(signal);
+                if (attempt > 1) {
+                    const exponentialDelay = options.baseDelayMs * (2 ** (attempt - 2));
+                    const delayMs = Math.min(exponentialDelay, options.maxDelayMs);
+                    await abortableDelay(delayMs + Math.random() * Math.min(delayMs, 500), signal);
+                }
+                throwIfAborted(signal);
+                this.beginRecovery("rejoin", attempt);
+                await this.performRejoin(this.apiBase, signal);
+                throwIfAborted(signal);
+                this.completeRecovery();
+                return;
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                lastError = toError(error);
+                if (isTerminalRejoinError(error))
+                    break;
+            }
+        }
+        this.failRecovery(lastError);
+        this.setState("failed");
+    }
+    cancelAutoRejoin() {
+        this.autoRejoinController?.abort();
+        this.autoRejoinController = null;
+        this.autoRejoinPromise = null;
+        this.activeRecovery = null;
+    }
     notifyListeners(listeners, value) {
         for (const listener of listeners) {
             try {
@@ -517,10 +845,12 @@ export class RealtimeSession {
             throw new TypeError("audioTrack has already ended");
         }
     }
-    async fetchRoomToken(apiBase) {
+    async fetchRoomToken(apiBase, signal) {
         return this.fetcher(`${apiBase}/sessions/${this.id}/room-tokens`, {
             method: "POST",
             headers: { Authorization: `Bearer ${this.accessToken}` },
+            credentials: this.lifecycleCredentials,
+            signal,
         });
     }
     async refreshCredentials() {
@@ -535,8 +865,20 @@ export class RealtimeSession {
         this.credentials = refreshed.connection;
     }
     observeConvenienceEvents(event) {
-        if (event.type === "session.ended")
+        if (event.type === "session.ended") {
+            const recoveryWasActive = (this.autoRejoinPromise !== null
+                || this.activeRecovery !== null
+                || this.stateValue === "reconnecting"
+                || this.stateValue === "resuming");
+            this.sessionEnded = true;
+            if (this.activeRecovery !== null) {
+                this.failRecovery(new Error("Session ended during recovery"));
+            }
+            this.cancelAutoRejoin();
+            if (recoveryWasActive)
+                this.setState("disconnected");
             this.notifyListeners(this.endedListeners, event);
+        }
         if (event.type.endsWith(".error"))
             this.notifyListeners(this.errorListeners, event);
         const transcript = transcriptEvent(event);
@@ -558,13 +900,17 @@ export class RealtimeSession {
         }
     }
     async sendHello() {
+        const reconnect = this.pendingReconnect;
         const message = createClientMessage(this.connectionId, ++this.clientSeq, "client.hello", {
             last_server_seq: this.cursor.lastServerSeq,
             sdk: `@voxevolv/client@${SDK_VERSION}`,
             tool_handlers: [...this.toolHandlers.keys()].sort(),
+            ...(reconnect ? { reconnect } : {}),
         });
         this.lastHelloMessageId = message.message_id;
         await this.sendTrackedCommand(message, 10_000);
+        if (this.pendingReconnect === reconnect)
+            this.pendingReconnect = null;
     }
     async sendTrackedCommand(message, timeoutMs, retryTransfer) {
         const response = new Promise((resolve, reject) => {
@@ -598,33 +944,65 @@ export class RealtimeSession {
         try {
             await this.publishCommand(message);
         }
-        catch (error) {
-            const pending = this.pendingCommands.get(message.message_id);
-            if (pending) {
-                globalThis.clearTimeout(pending.timeout);
-                globalThis.clearInterval(pending.retry);
-                this.pendingCommands.delete(message.message_id);
-                pending.reject(error instanceof Error ? error : new Error(String(error)));
-            }
+        catch {
+            // The reliable data channel may still be warming immediately after a
+            // reconnect. Keep the command pending so the retry interval can publish
+            // it once the transport accepts writes, or reject at the normal timeout.
         }
         return response;
     }
     async publishCommand(message) {
         await this.room.localParticipant.publishData(new TextEncoder().encode(JSON.stringify(message)), { reliable: true, topic: "voxevolv.commands" });
     }
-    waitForAgentReady(timeoutMs) {
-        if (this.agentReady)
+    waitForRemoteAudioTrack(deadline, signal) {
+        if ((this.outputMediaStream?.getAudioTracks().length ?? 0) > 0)
             return Promise.resolve();
+        throwIfAborted(signal);
         return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                globalThis.clearTimeout(timeout);
+                signal?.removeEventListener("abort", onAbort);
+                this.remoteAudioTrackResolve = null;
+            };
             const timeout = globalThis.setTimeout(() => {
+                cleanup();
+                reject(new Error("Agent audio track did not arrive within the ready timeout;"
+                    + " pass waitForRemoteAudio: false to resolve connect() on signaling readiness alone"));
+            }, Math.max(deadline - Date.now(), 0));
+            const onAbort = () => {
+                cleanup();
+                reject(abortError(signal));
+            };
+            this.remoteAudioTrackResolve = () => {
+                cleanup();
+                resolve();
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    waitForAgentReady(timeoutMs, signal) {
+        if (this.agentReady)
+            return Promise.resolve();
+        throwIfAborted(signal);
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                globalThis.clearTimeout(timeout);
+                signal?.removeEventListener("abort", onAbort);
                 this.readyResolve = null;
+            };
+            const timeout = globalThis.setTimeout(() => {
+                cleanup();
                 reject(new Error(`Agent did not become ready within ${timeoutMs}ms`));
             }, timeoutMs);
+            const onAbort = () => {
+                cleanup();
+                reject(abortError(signal));
+            };
             this.readyResolve = () => {
-                globalThis.clearTimeout(timeout);
-                this.readyResolve = null;
+                cleanup();
                 resolve();
             };
+            signal?.addEventListener("abort", onAbort, { once: true });
         });
     }
     observeReadiness(event) {
@@ -637,8 +1015,12 @@ export class RealtimeSession {
             return;
         const wasReady = this.agentReady;
         this.agentReady = true;
-        if (this.room.state === LiveKitConnectionState.Connected)
+        if (this.room.state === LiveKitConnectionState.Connected) {
+            this.hasConnectedValue = true;
             this.setState("connected");
+            if (this.activeRecovery?.strategy === "livekit")
+                this.completeRecovery();
+        }
         this.readyResolve?.();
         if (!wasReady)
             this.notifyListeners(this.readyListeners, event);
@@ -698,10 +1080,16 @@ export class RealtimeSession {
     async fetchReplay(apiBase, afterSeq) {
         let nextAfter = afterSeq;
         while (true) {
-            let response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, { headers: { Authorization: `Bearer ${this.accessToken}` } });
+            let response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, {
+                headers: { Authorization: `Bearer ${this.accessToken}` },
+                credentials: this.lifecycleCredentials,
+            });
             if (response.status === 401 && this.refreshCredentialsCallback) {
                 await this.refreshCredentials();
-                response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, { headers: { Authorization: `Bearer ${this.accessToken}` } });
+                response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, {
+                    headers: { Authorization: `Bearer ${this.accessToken}` },
+                    credentials: this.lifecycleCredentials,
+                });
             }
             if (!response.ok)
                 throw await httpError(response, "Could not replay session events");
@@ -730,6 +1118,96 @@ export class RealtimeSession {
         }
     }
 }
+function resolveAutoRejoinOptions(value) {
+    if (!value)
+        return null;
+    const options = value === true ? {} : value;
+    const resolved = {
+        maxAttempts: options.maxAttempts ?? 3,
+        baseDelayMs: options.baseDelayMs ?? 750,
+        maxDelayMs: options.maxDelayMs ?? 5_000,
+    };
+    if (!Number.isInteger(resolved.maxAttempts) || resolved.maxAttempts < 1) {
+        throw new TypeError("autoRejoin.maxAttempts must be a positive integer");
+    }
+    if (!Number.isFinite(resolved.baseDelayMs) || resolved.baseDelayMs < 0) {
+        throw new TypeError("autoRejoin.baseDelayMs must be a non-negative finite number");
+    }
+    if (!Number.isFinite(resolved.maxDelayMs) || resolved.maxDelayMs < 0) {
+        throw new TypeError("autoRejoin.maxDelayMs must be a non-negative finite number");
+    }
+    return resolved;
+}
+function isTerminalDisconnectReason(reason) {
+    return reason !== undefined && [
+        DisconnectReason.CLIENT_INITIATED,
+        DisconnectReason.DUPLICATE_IDENTITY,
+        DisconnectReason.PARTICIPANT_REMOVED,
+        DisconnectReason.ROOM_DELETED,
+        DisconnectReason.ROOM_CLOSED,
+        DisconnectReason.USER_UNAVAILABLE,
+        DisconnectReason.USER_REJECTED,
+    ].includes(reason);
+}
+function disconnectReasonName(reason) {
+    if (reason === undefined)
+        return "unknown";
+    return DisconnectReason[reason] ?? String(reason);
+}
+function isTerminalRejoinError(error) {
+    return error instanceof RealtimeSessionHttpError
+        && [401, 403, 409].includes(error.status);
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function abortError(signal) {
+    return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError(signal);
+}
+function abortableDelay(delayMs, signal) {
+    throwIfAborted(signal);
+    if (delayMs <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const timeout = globalThis.setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, delayMs);
+        const onAbort = () => {
+            globalThis.clearTimeout(timeout);
+            reject(abortError(signal));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function waitUntilOnline(signal) {
+    throwIfAborted(signal);
+    if (typeof navigator === "undefined" || navigator.onLine !== false) {
+        return Promise.resolve();
+    }
+    if (typeof globalThis.addEventListener !== "function")
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            globalThis.removeEventListener("online", onOnline);
+            signal.removeEventListener("abort", onAbort);
+        };
+        const onOnline = () => {
+            cleanup();
+            resolve();
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(abortError(signal));
+        };
+        globalThis.addEventListener("online", onOnline, { once: true });
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 async function sha256Hex(data) {
     if (!globalThis.crypto?.subtle)
         throw new Error("Web Crypto SHA-256 is unavailable");