@voxevolv/client 0.3.3 → 0.3.5

package/dist/index.js

@@ -1,12 +1,20 @@
 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";
 import { ReplacementContextQueue } from "./context-queue.js";
+import { ClientDiagnosticBuffer, } from "./diagnostics.js";
 import { TranscriptStore } from "./transcripts.js";
 export { TranscriptStore } from "./transcripts.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.3.3";
+export const SDK_VERSION = "0.3.5";
 const CLIENT_HELLO_TIMEOUT_MS = 30_000;
+const DIAGNOSTIC_REPORT_TIMEOUT_MS = 5_000;
+const DEFAULT_STARTUP_ATTEMPTS = [
+    { delayBeforeMs: 0, readyTimeoutMs: 15_000 },
+    { delayBeforeMs: 1_000, readyTimeoutMs: 20_000 },
+    { delayBeforeMs: 3_000, readyTimeoutMs: 25_000 },
+];
+const DEFAULT_STARTUP_TIMEOUT_MS = 65_000;
 export class RealtimeSessionHttpError extends Error {
     status;
     code;
@@ -21,6 +29,20 @@ export class RealtimeSessionHttpError extends Error {
         this.details = options.details ?? [];
     }
 }
+class SessionConfigurationError extends TypeError {
+}
+class SessionErrorEventError extends Error {
+    retryable;
+    constructor(event) {
+        const payload = event.payload;
+        const message = typeof payload.message === "string"
+            ? payload.message
+            : "VoxEvolv reported a session error";
+        super(message);
+        this.name = "SessionErrorEventError";
+        this.retryable = payload.retryable === true;
+    }
+}
 export class RealtimeSession {
     id;
     room;
@@ -32,6 +54,7 @@ export class RealtimeSession {
     gapListeners = new Set();
     connectionQualityListeners = new Set();
     recoveryListeners = new Set();
+    startupAttemptListeners = new Set();
     remoteAudioTrackListeners = new Set();
     remoteAudioTrackUnsubscribedListeners = new Set();
     readyListeners = new Set();
@@ -59,6 +82,7 @@ export class RealtimeSession {
     readyResolve = null;
     replayPromise = null;
     pendingCommands = new Map();
+    commandPublishTail = Promise.resolve();
     toolHandlers = new Map();
     apiBase = "/v1";
     hasConnectedValue = false;
@@ -69,6 +93,8 @@ export class RealtimeSession {
     activeRecovery = null;
     autoRejoinPromise = null;
     autoRejoinController = null;
+    startupConnectController = null;
+    startupAttemptController = null;
     useManagedMicrophone = true;
     managedMicrophoneEnabled = true;
     applicationAudioTrack = null;
@@ -77,7 +103,10 @@ export class RealtimeSession {
     endEndpoint;
     refreshCredentialsCallback;
     autoRejoinOptions;
+    startupRetryOptions;
     lifecycleCredentials;
+    diagnostics = new ClientDiagnosticBuffer({ sdkVersion: SDK_VERSION });
+    diagnosticReportTimeoutMs = DIAGNOSTIC_REPORT_TIMEOUT_MS;
     constructor(credentials, options = {}) {
         validateSessionCredentials(credentials);
         this.id = credentials.id;
@@ -91,6 +120,7 @@ export class RealtimeSession {
         this.endEndpoint = options.endEndpoint ?? null;
         this.refreshCredentialsCallback = options.refreshCredentials ?? null;
         this.autoRejoinOptions = resolveAutoRejoinOptions(options.autoRejoin);
+        this.startupRetryOptions = resolveStartupRetryOptions(options.startupRetry);
         this.lifecycleCredentials = options.lifecycleCredentials ?? "same-origin";
         this.room = new Room({ adaptiveStream: true, dynacast: true });
         for (const [name, handler] of Object.entries(options.tools ?? {})) {
@@ -190,6 +220,10 @@ export class RealtimeSession {
         this.recoveryListeners.add(listener);
         return () => this.recoveryListeners.delete(listener);
     }
+    onStartupAttempt(listener) {
+        this.startupAttemptListeners.add(listener);
+        return () => this.startupAttemptListeners.delete(listener);
+    }
     waitForState(states, timeoutMs, options = {}) {
         if (!states.length)
             throw new TypeError("states must contain at least one connection state");
@@ -298,13 +332,106 @@ export class RealtimeSession {
             throw new Error(`Cannot connect while session is ${this.stateValue}`);
         }
         this.cancelAutoRejoin();
-        await this.connectWithMode(options, false);
+        const controller = new AbortController();
+        this.startupConnectController = controller;
+        try {
+            if (this.startupRetryOptions) {
+                await this.connectWithStartupRetry(options, controller);
+            }
+            else {
+                this.startupAttemptController = controller;
+                await this.connectWithMode(options, false, controller.signal, false);
+            }
+        }
+        catch (error) {
+            if (this.startupConnectController === controller && !this.sessionEnded) {
+                this.setState("failed");
+            }
+            throw error;
+        }
+        finally {
+            if (this.startupAttemptController === controller) {
+                this.startupAttemptController = null;
+            }
+            if (this.startupConnectController === controller) {
+                this.startupConnectController = null;
+            }
+        }
     }
-    async connectWithMode(options, recovering, signal) {
+    async connectWithStartupRetry(options, controller) {
+        const startupOptions = this.startupRetryOptions;
+        if (!startupOptions)
+            return;
+        const timeout = globalThis.setTimeout(() => {
+            controller.abort(new Error(`Session startup did not complete within ${startupOptions.timeoutMs}ms`));
+        }, startupOptions.timeoutMs);
+        let lastError = new Error("Session startup failed");
+        try {
+            for (const [index, attempt] of startupOptions.attempts.entries()) {
+                const attemptNumber = index + 1;
+                if (attempt.delayBeforeMs > 0) {
+                    this.setState("connecting");
+                    await abortableDelay(attempt.delayBeforeMs, controller.signal);
+                }
+                throwIfAborted(controller.signal);
+                const attemptController = createLinkedAbortController(controller.signal);
+                this.startupAttemptController = attemptController;
+                this.notifyStartupAttempt("started", attemptNumber, attempt.readyTimeoutMs);
+                try {
+                    if (index === 0) {
+                        await this.connectWithMode({ ...options, readyTimeoutMs: attempt.readyTimeoutMs }, false, attemptController.signal, false);
+                    }
+                    else {
+                        await this.performRejoin(this.apiBase, {
+                            signal: attemptController.signal,
+                            recovering: false,
+                            connect: { ...options, readyTimeoutMs: attempt.readyTimeoutMs },
+                            markFailureTerminal: false,
+                        });
+                    }
+                    this.notifyStartupAttempt("succeeded", attemptNumber, attempt.readyTimeoutMs);
+                    return;
+                }
+                catch (error) {
+                    lastError = toError(error);
+                    this.notifyStartupAttempt("failed", attemptNumber, attempt.readyTimeoutMs, lastError);
+                    if (controller.signal.aborted)
+                        throw abortError(controller.signal);
+                    if (isTerminalStartupError(error) || attemptNumber === startupOptions.attempts.length) {
+                        throw error;
+                    }
+                    this.setState("connecting");
+                }
+                finally {
+                    if (this.startupAttemptController === attemptController) {
+                        this.startupAttemptController = null;
+                    }
+                }
+            }
+            throw lastError;
+        }
+        finally {
+            globalThis.clearTimeout(timeout);
+        }
+    }
+    notifyStartupAttempt(status, attempt, readyTimeoutMs, error) {
+        const maxAttempts = this.startupRetryOptions?.attempts.length ?? 1;
+        this.notifyListeners(this.startupAttemptListeners, {
+            status,
+            attempt,
+            maxAttempts,
+            readyTimeoutMs,
+            ...(error ? { error } : {}),
+        });
+    }
+    async connectWithMode(options, recovering, signal, markFailureTerminal = true) {
         const blockedStates = recovering
             ? ["connecting", "connected_not_ready", "connected", "reconnecting"]
             : ["connecting", "connected_not_ready", "connected", "reconnecting", "resuming"];
-        if (blockedStates.includes(this.stateValue)) {
+        const continuingStartupRetry = (!recovering
+            && !markFailureTerminal
+            && this.stateValue === "connecting");
+        if (blockedStates.includes(this.stateValue) && !continuingStartupRetry) {
             throw new Error(`Cannot connect while session is ${this.stateValue}`);
         }
         const generation = this.contextGeneration;
@@ -333,17 +460,17 @@ export class RealtimeSession {
         this.apiBase = apiBase;
         this.agentReady = false;
         try {
-            await this.room.connect(this.credentials.url, this.credentials.token);
+            await this.connectRoom(signal, recovering);
             throwIfAborted(signal);
             if (audioTrack) {
-                await this.publishApplicationAudioTrack(audioTrack);
+                await raceWithAbort(this.publishApplicationAudioTrack(audioTrack), signal);
             }
             else if (microphone) {
-                await this.room.localParticipant.setMicrophoneEnabled(this.managedMicrophoneEnabled);
+                await raceWithAbort(this.room.localParticipant.setMicrophoneEnabled(this.managedMicrophoneEnabled), signal);
             }
             throwIfAborted(signal);
             this.setState(recovering ? "resuming" : "connected_not_ready");
-            await this.sendHello();
+            await raceWithAbort(this.sendHello(), signal);
             const readyDeadline = Date.now() + readyTimeoutMs;
             await this.waitForAgentReady(readyTimeoutMs, signal);
             if (waitForRemoteAudio)
@@ -352,7 +479,7 @@ export class RealtimeSession {
             if (this.sessionEnded || generation !== this.contextGeneration) {
                 throw new Error("Connection restoration interrupted");
             }
-            await this.replacementContext.resume(recovering);
+            await raceWithAbort(this.replacementContext.resume(recovering), signal);
             throwIfAborted(signal);
             if (this.sessionEnded || generation !== this.contextGeneration) {
                 throw new Error("Connection restoration interrupted");
@@ -361,6 +488,8 @@ export class RealtimeSession {
             this.setState("connected");
         }
         catch (error) {
+            if (signal?.aborted)
+                this.rejectPendingCommands(toError(abortError(signal)));
             this.disconnectMode = recovering ? "rejoin" : "connect_failure";
             try {
                 await this.room.disconnect();
@@ -371,11 +500,46 @@ export class RealtimeSession {
             finally {
                 this.disconnectMode = null;
             }
-            if (!recovering)
+            if (!recovering && markFailureTerminal)
                 this.setState("failed");
             throw error;
         }
     }
+    connectRoom(signal, recovering) {
+        throwIfAborted(signal);
+        const connection = this.room.connect(this.credentials.url, this.credentials.token);
+        if (!signal)
+            return connection;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const resolveOnce = () => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener("abort", onAbort);
+                resolve();
+            };
+            const rejectOnce = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener("abort", onAbort);
+                reject(error);
+            };
+            const onAbort = () => {
+                this.disconnectMode = recovering ? "rejoin" : "connect_failure";
+                void this.room.disconnect().catch(() => { });
+                rejectOnce(abortError(signal));
+            };
+            if (signal.aborted) {
+                onAbort();
+            }
+            else {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            connection.then(resolveOnce, rejectOnce);
+        });
+    }
     async rejoin(apiBase = this.apiBase) {
         if (["connecting", "reconnecting", "resuming"].includes(this.stateValue)) {
             throw new Error(`Cannot rejoin while session is ${this.stateValue}`);
@@ -384,11 +548,11 @@ export class RealtimeSession {
         const normalizedApiBase = normalizeApiBase(apiBase);
         const recovering = this.hasConnectedValue;
         if (recovering) {
-            this.beginRecovery("rejoin", 1);
+            this.beginRecovery("rejoin", 1, { trigger: "manual_rejoin" });
             this.setState("resuming");
         }
         try {
-            await this.performRejoin(normalizedApiBase, undefined, recovering);
+            await this.performRejoin(normalizedApiBase, { recovering });
             if (recovering)
                 this.completeRecovery();
         }
@@ -400,19 +564,21 @@ export class RealtimeSession {
             throw error;
         }
     }
-    async performRejoin(apiBase, signal, recovering = true) {
+    async performRejoin(apiBase, options = {}) {
+        const { signal, recovering = true, connect = {}, markFailureTerminal = true, } = options;
         this.contextGeneration += 1;
         this.replacementContext.pause();
         this.rejectPendingCommands(new Error("Restoring the session"));
         let response = await this.fetchRoomToken(apiBase, signal);
         if (response.status === 401 && this.refreshCredentialsCallback) {
-            await this.refreshCredentials();
+            await raceWithAbort(this.refreshCredentials(), signal);
             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());
+        if (!response.ok) {
+            throw await raceWithAbort(httpError(response, "Could not renew room token"), signal);
+        }
+        const payload = (await raceWithAbort(response.json(), signal));
         this.credentials = payload.connection;
         if (this.room.state !== LiveKitConnectionState.Disconnected) {
             this.disconnectMode = "rejoin";
@@ -432,10 +598,11 @@ export class RealtimeSession {
             };
         }
         await this.connectWithMode({
+            ...connect,
             apiBase,
             microphone: this.useManagedMicrophone,
             ...(this.applicationAudioTrack ? { audioTrack: this.applicationAudioTrack } : {}),
-        }, recovering, signal);
+        }, recovering, signal, markFailureTerminal);
     }
     async setMicrophoneEnabled(enabled) {
         await this.room.localParticipant.setMicrophoneEnabled(enabled);
@@ -457,18 +624,73 @@ export class RealtimeSession {
     }
     async sendContextUpdate(update, timeoutMs) {
         const generation = this.contextGeneration;
+        const payloadBytes = contextUpdateBytes(update);
+        const transferStartedAt = Date.now();
+        let transferTimedOut = false;
+        this.recordDiagnostic({
+            operation: "context_transfer",
+            status: "started",
+            context_key: update.key,
+            payload_bytes: payloadBytes,
+        });
         let transferTimeout;
         const transferExpired = new Promise((_resolve, reject) => {
             transferTimeout = globalThis.setTimeout(() => {
+                transferTimedOut = true;
                 const error = new Error(`Context transfer timed out after ${timeoutMs}ms`);
-                this.startAutoRejoin(error);
+                this.recordDiagnostic({
+                    operation: "context_transfer",
+                    status: "timed_out",
+                    reason: "context_transfer_timeout",
+                    context_key: update.key,
+                    payload_bytes: payloadBytes,
+                    duration_ms: Date.now() - transferStartedAt,
+                    timeout_ms: timeoutMs,
+                });
+                this.flushDiagnostics("context_transfer_timeout");
+                this.startAutoRejoin(error, {
+                    trigger: "context_transfer_timeout",
+                    operation: "context_transfer",
+                    contextKey: update.key,
+                    timeoutMs,
+                });
                 reject(error);
             }, timeoutMs);
         });
-        const transfer = await Promise.race([
-            "image" in update ? this.uploadImageContext(update) : this.uploadTextContext(update),
-            transferExpired,
-        ]).finally(() => globalThis.clearTimeout(transferTimeout));
+        let transfer;
+        try {
+            transfer = await Promise.race([
+                "image" in update ? this.uploadImageContext(update) : this.uploadTextContext(update),
+                transferExpired,
+            ]);
+        }
+        catch (error) {
+            if (!transferTimedOut) {
+                this.recordDiagnostic({
+                    operation: "context_transfer",
+                    status: "failed",
+                    reason: "context_transfer_failed",
+                    context_key: update.key,
+                    payload_bytes: payloadBytes,
+                    duration_ms: Date.now() - transferStartedAt,
+                });
+                this.flushDiagnostics("command_failed");
+            }
+            throw error;
+        }
+        finally {
+            globalThis.clearTimeout(transferTimeout);
+        }
+        const transferDurationMs = Date.now() - transferStartedAt;
+        this.recordDiagnostic({
+            operation: "context_transfer",
+            status: "succeeded",
+            context_key: update.key,
+            payload_bytes: payloadBytes,
+            duration_ms: transferDurationMs,
+        });
+        if (transferDurationMs > 2_000)
+            this.flushDiagnostics("slow_operation");
         if (generation !== this.contextGeneration)
             throw new Error("Context transfer interrupted by recovery");
         const { payload } = transfer;
@@ -558,6 +780,8 @@ export class RealtimeSession {
         };
     }
     async disconnect() {
+        this.abortStartupConnect(new Error("Session disconnected"));
+        this.startupConnectController = null;
         this.cancelAutoRejoin();
         this.contextGeneration += 1;
         this.replacementContext.clear(new Error("Session disconnected"));
@@ -575,6 +799,8 @@ export class RealtimeSession {
         }
     }
     async end(options = {}) {
+        this.abortStartupConnect(new Error("Session ended"));
+        this.startupConnectController = null;
         this.cancelAutoRejoin();
         this.sessionEnded = true;
         const endpoint = options.endpoint ?? this.endEndpoint ?? `${this.apiBase}/sessions/${this.id}`;
@@ -623,7 +849,7 @@ export class RealtimeSession {
     bindRoomEvents() {
         this.room.on(RoomEvent.ParticipantDisconnected, (participant) => {
             if (participant.isAgent && !this.disconnectMode) {
-                this.startAutoRejoin(new Error("Agent disconnected from the room"));
+                this.startAutoRejoin(new Error("Agent disconnected from the room"), { trigger: "agent_disconnected" });
             }
         });
         this.room.on(RoomEvent.SignalReconnecting, () => this.handleLiveKitReconnecting());
@@ -732,7 +958,7 @@ export class RealtimeSession {
         this.reconnectStartedAt ??= Date.now();
         this.rejectPendingCommands(new Error("Connection interrupted before command completion"), true);
         if (this.activeRecovery === null) {
-            this.beginRecovery("livekit", 1);
+            this.beginRecovery("livekit", 1, { trigger: "livekit_reconnecting" });
         }
         this.setState("reconnecting");
     }
@@ -750,7 +976,7 @@ export class RealtimeSession {
             this.reconnectStartedAt = null;
         }
         if (this.hasConnectedValue && this.activeRecovery === null) {
-            this.beginRecovery("livekit", 1);
+            this.beginRecovery("livekit", 1, { trigger: "livekit_reconnecting" });
         }
         this.connectionId = `conn_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
         this.clientSeq = 0;
@@ -774,7 +1000,7 @@ export class RealtimeSession {
                 return;
             const normalizedError = toError(error);
             if (this.shouldAutoRejoin()) {
-                this.startAutoRejoin(normalizedError);
+                this.startAutoRejoin(normalizedError, { trigger: "livekit_resume_failed" });
             }
             else {
                 this.failRecovery(normalizedError);
@@ -804,7 +1030,7 @@ export class RealtimeSession {
             return;
         }
         if (this.shouldAutoRejoin(reason)) {
-            this.startAutoRejoin(new Error(`LiveKit disconnected (${disconnectReasonName(reason)})`));
+            this.startAutoRejoin(new Error(`LiveKit disconnected (${disconnectReasonName(reason)})`), { trigger: "livekit_disconnected" });
             return;
         }
         if (this.activeRecovery !== null) {
@@ -828,12 +1054,22 @@ export class RealtimeSession {
         this.endNotificationDelivered = true;
         this.notifyListeners(this.endedListeners, event);
     }
-    beginRecovery(strategy, attempt) {
-        this.activeRecovery = { strategy, attempt };
+    beginRecovery(strategy, attempt, details) {
+        this.activeRecovery = { strategy, attempt, details };
+        this.recordDiagnostic({
+            operation: "connection_recovery",
+            status: "started",
+            reason: details.trigger,
+            message_id: details.messageId,
+            context_key: details.contextKey,
+            timeout_ms: details.timeoutMs,
+        });
+        this.flushDiagnostics("recovery_started");
         this.notifyListeners(this.recoveryListeners, {
             status: "started",
             strategy,
             attempt,
+            ...details,
         });
     }
     completeRecovery() {
@@ -845,6 +1081,7 @@ export class RealtimeSession {
             status: "succeeded",
             strategy: recovery.strategy,
             attempt: recovery.attempt,
+            ...recovery.details,
         });
     }
     failRecovery(error) {
@@ -856,6 +1093,7 @@ export class RealtimeSession {
             status: "failed",
             strategy: recovery.strategy,
             attempt: recovery.attempt,
+            ...recovery.details,
             error,
         });
     }
@@ -866,7 +1104,7 @@ export class RealtimeSession {
             && !["disconnected", "failed"].includes(this.stateValue)
             && !isTerminalDisconnectReason(reason));
     }
-    startAutoRejoin(initialError) {
+    startAutoRejoin(initialError, details) {
         if (this.autoRejoinPromise || !this.shouldAutoRejoin())
             return;
         this.agentReady = false;
@@ -887,7 +1125,7 @@ export class RealtimeSession {
             this.failRecovery(error);
             this.setState("failed");
         }, this.autoRejoinOptions.timeoutMs);
-        const promise = this.runAutoRejoin(initialError, controller.signal)
+        const promise = this.runAutoRejoin(initialError, controller.signal, details)
             .finally(() => {
             globalThis.clearTimeout(timeout);
             if (this.autoRejoinController === controller) {
@@ -898,7 +1136,7 @@ export class RealtimeSession {
         this.autoRejoinPromise = promise;
         void promise;
     }
-    async runAutoRejoin(initialError, signal) {
+    async runAutoRejoin(initialError, signal, details) {
         const options = this.autoRejoinOptions;
         if (!options)
             return;
@@ -916,8 +1154,8 @@ export class RealtimeSession {
                     await abortableDelay(delayMs + Math.random() * Math.min(delayMs, 500), signal);
                 }
                 throwIfAborted(signal);
-                this.beginRecovery("rejoin", attempt);
-                await this.performRejoin(this.apiBase, signal);
+                this.beginRecovery("rejoin", attempt, details);
+                await this.performRejoin(this.apiBase, { signal });
                 throwIfAborted(signal);
                 this.reconnectStartedAt = null;
                 this.completeRecovery();
@@ -963,15 +1201,15 @@ export class RealtimeSession {
     }
     validateAudioOptions(microphone, audioTrack) {
         if (microphone && audioTrack) {
-            throw new TypeError("microphone and audioTrack cannot both be enabled");
+            throw new SessionConfigurationError("microphone and audioTrack cannot both be enabled");
         }
         if (!audioTrack)
             return;
         if (audioTrack.kind !== "audio") {
-            throw new TypeError("audioTrack must be an audio MediaStreamTrack");
+            throw new SessionConfigurationError("audioTrack must be an audio MediaStreamTrack");
         }
         if (audioTrack.readyState === "ended") {
-            throw new TypeError("audioTrack has already ended");
+            throw new SessionConfigurationError("audioTrack has already ended");
         }
     }
     async fetchRoomToken(apiBase, signal) {
@@ -981,12 +1219,12 @@ export class RealtimeSession {
         const timeout = globalThis.setTimeout(() => controller.abort(), 10_000);
         try {
             throwIfAborted(signal);
-            return await this.fetcher(`${apiBase}/sessions/${this.id}/room-tokens`, {
+            return await raceWithAbort(this.fetcher(`${apiBase}/sessions/${this.id}/room-tokens`, {
                 method: "POST",
                 headers: { Authorization: `Bearer ${this.accessToken}` },
                 credentials: this.lifecycleCredentials,
                 signal: controller.signal,
-            });
+            }), controller.signal);
         }
         finally {
             globalThis.clearTimeout(timeout);
@@ -1005,7 +1243,17 @@ export class RealtimeSession {
         this.credentials = refreshed.connection;
     }
     observeConvenienceEvents(event) {
+        if (event.type === "session.error") {
+            const error = new SessionErrorEventError(event);
+            if (error.retryable) {
+                this.startupAttemptController?.abort(error);
+            }
+            else {
+                this.abortStartupConnect(error);
+            }
+        }
         if (event.type === "session.ending" || event.type === "session.ended") {
+            this.abortStartupConnect(new Error("Session ended during startup"));
             this.contextGeneration += 1;
             this.rejectPendingCommands(new Error("Session ended"));
         }
@@ -1043,6 +1291,11 @@ export class RealtimeSession {
             return;
         this.notifyListeners(transcript.role === "user" ? this.userTranscriptListeners : this.agentTranscriptListeners, transcript);
     }
+    abortStartupConnect(error) {
+        if (!this.startupConnectController?.signal.aborted) {
+            this.startupConnectController?.abort(error);
+        }
+    }
     async publishApplicationAudioTrack(audioTrack) {
         const publishedTrack = audioTrack.clone();
         try {
@@ -1070,50 +1323,224 @@ export class RealtimeSession {
             this.pendingReconnect = null;
     }
     async sendTrackedCommand(message, timeoutMs, retryTransfer) {
+        const contextKey = contextKeyFromMessage(message);
+        const payloadBytes = contextPayloadBytes(message.payload);
+        const startedAt = Date.now();
+        this.recordDiagnostic({
+            operation: "command_send",
+            status: "started",
+            message_id: message.message_id,
+            connection_id: message.connection_id,
+            client_seq: message.client_seq,
+            context_key: contextKey,
+            payload_bytes: payloadBytes,
+            retry_count: 0,
+            timeout_ms: timeoutMs,
+            event_type: diagnosticEventType(message.type),
+        });
+        let markSettled = () => { };
+        const settled = new Promise((resolve) => { markSettled = resolve; });
         const response = new Promise((resolve, reject) => {
             const timeout = globalThis.setTimeout(() => {
                 const pending = this.pendingCommands.get(message.message_id);
                 if (pending)
                     globalThis.clearInterval(pending.retry);
+                pending?.markSettled();
                 this.pendingCommands.delete(message.message_id);
                 const error = new Error(`Command ${message.type} timed out after ${timeoutMs}ms`);
+                this.recordDiagnostic({
+                    operation: "command_send",
+                    status: "timed_out",
+                    reason: message.type === "context.update"
+                        ? "context_command_timeout"
+                        : "command_timeout",
+                    message_id: message.message_id,
+                    connection_id: message.connection_id,
+                    client_seq: message.client_seq,
+                    context_key: contextKey,
+                    payload_bytes: payloadBytes,
+                    duration_ms: Date.now() - startedAt,
+                    retry_count: pending?.retryCount ?? 0,
+                    timeout_ms: timeoutMs,
+                    event_type: diagnosticEventType(message.type),
+                });
+                this.flushDiagnostics("command_timeout");
                 reject(error);
-                if (message.type === "context.update")
-                    this.startAutoRejoin(error);
+                if (message.type === "context.update") {
+                    this.startAutoRejoin(error, {
+                        trigger: "context_command_timeout",
+                        operation: "command_send",
+                        messageId: message.message_id,
+                        contextKey: contextKeyFromMessage(message),
+                        timeoutMs,
+                    });
+                }
             }, timeoutMs);
             const retry = globalThis.setInterval(() => {
-                void this.publishCommand(message).catch(() => {
+                void this.publishCommandAttempt(message, true).catch(() => {
                     // A reconnect may temporarily reject writes; retry until timeout.
                 });
             }, 500);
             this.pendingCommands.set(message.message_id, {
                 commandType: message.type,
+                message,
+                startedAt,
+                contextKey,
+                payloadBytes,
+                retryCount: 0,
+                publishQueued: false,
                 resolve,
                 reject,
                 timeout,
                 retry,
+                settled,
+                markSettled,
                 retryTransfer: retryTransfer
                     ? async () => {
                         await retryTransfer();
-                        await this.publishCommand(message);
+                        await this.publishCommandAttempt(message, true);
                     }
                     : undefined,
                 transferRetrying: false,
             });
         });
-        try {
-            await this.publishCommand(message);
-        }
-        catch {
+        void this.publishCommandAttempt(message, false).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;
     }
+    publishCommandAttempt(message, retrying) {
+        const pending = this.pendingCommands.get(message.message_id);
+        if (!pending || pending.publishQueued)
+            return Promise.resolve();
+        pending.publishQueued = true;
+        // Context keys drain independently, but client_seq is global. Serialize the
+        // asynchronous LiveKit publish boundary so a later sequence cannot overtake
+        // an earlier one before the reliable data channel receives it.
+        const attempt = this.commandPublishTail
+            .then(() => this.publishCommandAttemptNow(message, retrying))
+            .finally(() => {
+            const current = this.pendingCommands.get(message.message_id);
+            if (current === pending)
+                current.publishQueued = false;
+        });
+        this.commandPublishTail = attempt.catch(() => { });
+        return attempt;
+    }
+    async publishCommandAttemptNow(message, retrying) {
+        const pending = this.pendingCommands.get(message.message_id);
+        if (!pending)
+            return;
+        if (retrying) {
+            pending.retryCount += 1;
+            this.recordDiagnostic({
+                operation: "command_send",
+                status: "retrying",
+                message_id: message.message_id,
+                connection_id: message.connection_id,
+                client_seq: message.client_seq,
+                context_key: pending.contextKey,
+                payload_bytes: pending.payloadBytes,
+                retry_count: pending.retryCount,
+                event_type: diagnosticEventType(message.type),
+            });
+        }
+        const attemptStartedAt = Date.now();
+        try {
+            let publishFinished = false;
+            const publish = this.publishCommand(message).then(() => { publishFinished = true; });
+            await Promise.race([publish, pending.settled]);
+            if (!publishFinished)
+                return;
+        }
+        catch (error) {
+            this.recordDiagnostic({
+                operation: "command_send",
+                status: "failed",
+                reason: "command_publish_failed",
+                message_id: message.message_id,
+                connection_id: message.connection_id,
+                client_seq: message.client_seq,
+                context_key: pending.contextKey,
+                payload_bytes: pending.payloadBytes,
+                duration_ms: Date.now() - attemptStartedAt,
+                retry_count: pending.retryCount,
+                event_type: diagnosticEventType(message.type),
+            });
+            this.flushDiagnostics("command_failed");
+            throw error;
+        }
+        const durationMs = Date.now() - attemptStartedAt;
+        this.recordDiagnostic({
+            operation: "command_send",
+            status: "succeeded",
+            message_id: message.message_id,
+            connection_id: message.connection_id,
+            client_seq: message.client_seq,
+            context_key: pending.contextKey,
+            payload_bytes: pending.payloadBytes,
+            duration_ms: durationMs,
+            retry_count: pending.retryCount,
+            event_type: diagnosticEventType(message.type),
+        });
+        if (durationMs > 2_000)
+            this.flushDiagnostics("slow_operation");
+    }
     async publishCommand(message) {
         await this.room.localParticipant.publishData(new TextEncoder().encode(JSON.stringify(message)), { reliable: true, topic: "voxevolv.commands" });
     }
+    recordDiagnostic(entry) {
+        this.diagnostics.record({
+            ...entry,
+            connection_state: this.stateValue,
+            buffered_bytes: this.reliableDataChannelBufferedBytes(),
+        });
+    }
+    reliableDataChannelBufferedBytes() {
+        try {
+            const bufferedAmount = this.room.engine.dataChannelForKind(0)?.bufferedAmount;
+            return typeof bufferedAmount === "number" ? bufferedAmount : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    flushDiagnostics(trigger) {
+        void this.diagnostics.flush(trigger, (report) => this.postDiagnostics(report));
+    }
+    async postDiagnostics(report) {
+        const controller = new AbortController();
+        let timeout;
+        const timeoutExpired = new Promise((_resolve, reject) => {
+            timeout = globalThis.setTimeout(() => {
+                controller.abort();
+                reject(new Error(`Diagnostic report timed out after ${this.diagnosticReportTimeoutMs}ms`));
+            }, this.diagnosticReportTimeoutMs);
+        });
+        try {
+            const response = await Promise.race([
+                this.fetcher(`${this.apiBase}/sessions/${this.id}/diagnostics`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${this.accessToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    credentials: this.lifecycleCredentials,
+                    body: JSON.stringify(report),
+                    signal: controller.signal,
+                }),
+                timeoutExpired,
+            ]);
+            if (!response.ok)
+                throw new Error(`Diagnostic report failed (${response.status})`);
+        }
+        finally {
+            if (timeout !== undefined)
+                globalThis.clearTimeout(timeout);
+        }
+    }
     waitForRemoteAudioTrack(deadline, signal) {
         if ((this.outputMediaStream?.getAudioTracks().length ?? 0) > 0)
             return Promise.resolve();
@@ -1177,7 +1604,7 @@ export class RealtimeSession {
         if (event.type !== "agent.ready" && !snapshotReady)
             return;
         if (this.agentStreamId && this.agentStreamId !== event.stream_id && !this.activeRecovery) {
-            this.startAutoRejoin(new Error("Agent worker was replaced"));
+            this.startAutoRejoin(new Error("Agent worker was replaced"), { trigger: "worker_replaced" });
             return;
         }
         this.agentStreamId = event.stream_id;
@@ -1199,21 +1626,27 @@ export class RealtimeSession {
         if (!pending)
             return;
         if (event.type === "command.ack" && isCommandAckPayload(event.payload)) {
+            this.recordCommandResult(pending, event.type, "acknowledged");
             globalThis.clearTimeout(pending.timeout);
             globalThis.clearInterval(pending.retry);
+            pending.markSettled();
             this.pendingCommands.delete(event.payload.message_id);
             pending.resolve(event.payload);
             return;
         }
         if (event.type === "context.updated" && isContextUpdatedPayload(event.payload)) {
+            this.recordCommandResult(pending, event.type, "acknowledged");
             globalThis.clearTimeout(pending.timeout);
             globalThis.clearInterval(pending.retry);
+            pending.markSettled();
             this.pendingCommands.delete(event.payload.message_id);
             pending.resolve(event.payload);
             return;
         }
         if ((event.type === "command.error" && isCommandErrorPayload(event.payload))
             || (event.type === "context.rejected" && isContextRejectedPayload(event.payload))) {
+            this.recordCommandResult(pending, event.type, "rejected", event.payload.code);
+            this.flushDiagnostics("command_rejected");
             if (event.type === "context.rejected" && event.payload.retryable) {
                 if (pending.retryTransfer && !pending.transferRetrying) {
                     pending.transferRetrying = true;
@@ -1227,6 +1660,7 @@ export class RealtimeSession {
             }
             globalThis.clearTimeout(pending.timeout);
             globalThis.clearInterval(pending.retry);
+            pending.markSettled();
             this.pendingCommands.delete(event.payload.message_id);
             pending.reject(new CommandError(event.payload));
         }
@@ -1235,12 +1669,32 @@ export class RealtimeSession {
         for (const [messageId, pending] of this.pendingCommands) {
             if (preserveContext && pending.commandType === "context.update")
                 continue;
+            this.recordCommandResult(pending, pending.commandType === "context.update" ? "context.rejected" : "command.error", "failed", "pending_command_cancelled");
             globalThis.clearTimeout(pending.timeout);
             globalThis.clearInterval(pending.retry);
+            pending.markSettled();
             pending.reject(error);
             this.pendingCommands.delete(messageId);
         }
     }
+    recordCommandResult(pending, eventType, status, reason) {
+        const durationMs = Date.now() - pending.startedAt;
+        this.recordDiagnostic({
+            operation: "command_result",
+            status,
+            reason,
+            message_id: pending.message.message_id,
+            connection_id: pending.message.connection_id,
+            client_seq: pending.message.client_seq,
+            context_key: pending.contextKey,
+            payload_bytes: pending.payloadBytes,
+            duration_ms: durationMs,
+            retry_count: pending.retryCount,
+            event_type: eventType,
+        });
+        if (durationMs > 2_000)
+            this.flushDiagnostics("slow_operation");
+    }
     async fetchReplay(apiBase, afterSeq) {
         let nextAfter = afterSeq;
         while (true) {
@@ -1306,6 +1760,31 @@ function resolveAutoRejoinOptions(value) {
     }
     return resolved;
 }
+function resolveStartupRetryOptions(value) {
+    if (!value)
+        return null;
+    const options = value === true ? {} : value;
+    const attempts = (options.attempts ?? DEFAULT_STARTUP_ATTEMPTS).map((attempt) => ({
+        readyTimeoutMs: attempt.readyTimeoutMs,
+        delayBeforeMs: attempt.delayBeforeMs ?? 0,
+    }));
+    const timeoutMs = options.timeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+    if (attempts.length === 0) {
+        throw new TypeError("startupRetry.attempts must contain at least one attempt");
+    }
+    for (const attempt of attempts) {
+        if (!Number.isFinite(attempt.readyTimeoutMs) || attempt.readyTimeoutMs <= 0) {
+            throw new TypeError("startupRetry.attempts readyTimeoutMs must be a positive finite number");
+        }
+        if (!Number.isFinite(attempt.delayBeforeMs) || attempt.delayBeforeMs < 0) {
+            throw new TypeError("startupRetry.attempts delayBeforeMs must be a non-negative finite number");
+        }
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new TypeError("startupRetry.timeoutMs must be a positive finite number");
+    }
+    return { attempts, timeoutMs };
+}
 function isTerminalDisconnectReason(reason) {
     return reason !== undefined && [
         DisconnectReason.CLIENT_INITIATED,
@@ -1326,16 +1805,82 @@ function isTerminalRejoinError(error) {
     return error instanceof RealtimeSessionHttpError
         && [401, 403, 409].includes(error.status);
 }
+function isTerminalStartupError(error) {
+    if (error instanceof SessionErrorEventError)
+        return !error.retryable;
+    if (error instanceof RealtimeSessionHttpError) {
+        return error.status >= 400
+            && error.status < 500
+            && ![408, 425, 429].includes(error.status);
+    }
+    // Browser fetch also rejects network failures with TypeError. Only our
+    // explicit configuration errors are terminal before transport is established.
+    if (error instanceof SessionConfigurationError)
+        return true;
+    return error instanceof Error && [
+        "ConstraintNotSatisfiedError",
+        "DevicesNotFoundError",
+        "InvalidStateError",
+        "NotAllowedError",
+        "NotFoundError",
+        "NotReadableError",
+        "NotSupportedError",
+        "OverconstrainedError",
+        "SecurityError",
+        "TrackStartError",
+    ].includes(error.name);
+}
 function toError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
 function abortError(signal) {
     return signal.reason ?? new DOMException("Aborted", "AbortError");
 }
+function createLinkedAbortController(parentSignal) {
+    const controller = new AbortController();
+    if (parentSignal.aborted) {
+        controller.abort(abortError(parentSignal));
+    }
+    else {
+        parentSignal.addEventListener("abort", () => controller.abort(abortError(parentSignal)), { once: true });
+    }
+    return controller;
+}
 function throwIfAborted(signal) {
     if (signal?.aborted)
         throw abortError(signal);
 }
+function raceWithAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const resolveOnce = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        };
+        const rejectOnce = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        };
+        const onAbort = () => rejectOnce(abortError(signal));
+        if (signal.aborted) {
+            onAbort();
+        }
+        else {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        // Always observe the operation, including when it aborted the signal before
+        // returning its promise, so a later rejection cannot escape to the caller.
+        promise.then(resolveOnce, rejectOnce);
+    });
+}
 function abortableDelay(delayMs, signal) {
     throwIfAborted(signal);
     if (delayMs <= 0)
@@ -1389,24 +1934,61 @@ function contextStreamId() {
         return globalThis.crypto.randomUUID();
     return `ctx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
 }
+function contextUpdateBytes(update) {
+    return "image" in update
+        ? update.image.size
+        : new TextEncoder().encode(update.text).byteLength;
+}
+function contextPayloadBytes(payload) {
+    const image = payload.image;
+    if (image && typeof image === "object" && "bytes" in image) {
+        const bytes = image.bytes;
+        if (typeof bytes === "number")
+            return bytes;
+    }
+    const textStream = payload.text_stream;
+    if (textStream && typeof textStream === "object" && "bytes" in textStream) {
+        const bytes = textStream.bytes;
+        if (typeof bytes === "number")
+            return bytes;
+    }
+    if (typeof payload.text === "string") {
+        return new TextEncoder().encode(payload.text).byteLength;
+    }
+    try {
+        return new TextEncoder().encode(JSON.stringify(payload)).byteLength;
+    }
+    catch {
+        return undefined;
+    }
+}
+function contextKeyFromMessage(message) {
+    if (message.type !== "context.update")
+        return undefined;
+    const key = message.payload.key;
+    return typeof key === "string" ? key : undefined;
+}
+function diagnosticEventType(type) {
+    return type === "client.hello" || type === "context.update" ? type : undefined;
+}
 function validateSessionCredentials(value) {
     if (!value || typeof value !== "object") {
-        throw new TypeError("Session credentials must be an object");
+        throw new SessionConfigurationError("Session credentials must be an object");
     }
     if (!value.id || !value.access_token || !value.access_token_expires_at) {
-        throw new TypeError("Session credentials are incomplete");
+        throw new SessionConfigurationError("Session credentials are incomplete");
     }
     if (!value.connection
         || !value.connection.url
         || !value.connection.token
         || !value.connection.room_name) {
-        throw new TypeError("Session connection credentials are incomplete");
+        throw new SessionConfigurationError("Session connection credentials are incomplete");
     }
 }
 function normalizeApiBase(value) {
     const normalized = value.trim().replace(/\/+$/, "");
     if (!normalized) {
-        throw new TypeError("apiBase must be a non-root relative path or an absolute URL");
+        throw new SessionConfigurationError("apiBase must be a non-root relative path or an absolute URL");
     }
     return normalized;
 }