@voxevolv/client 0.3.7 → 0.3.9

package/dist/index.js

@@ -1,20 +1,20 @@
-import { ConnectionState as LiveKitConnectionState, DataPacket_Kind, DisconnectReason, Room, RoomEvent, RpcError, Track, } from "livekit-client";
+import { ConnectionState as LiveKitConnectionState, DataPacket_Kind, DisconnectReason, LocalAudioTrack, 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 { ContextDeliveryError, contextRetryDelay, ReplacementContextQueue } from "./context-queue.js";
+import { ClientDiagnosticBuffer, DiagnosticDeliveryError, } 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.7";
+export const SDK_VERSION = "0.3.9";
 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 },
+    { delayBeforeMs: 3_000, readyTimeoutMs: 50_000 },
 ];
-const DEFAULT_STARTUP_TIMEOUT_MS = 65_000;
+const DEFAULT_STARTUP_TIMEOUT_MS = 90_000;
 export class RealtimeSessionHttpError extends Error {
     status;
     code;
@@ -99,9 +99,12 @@ export class RealtimeSession {
     startupConnectController = null;
     startupAttemptController = null;
     useManagedMicrophone = true;
-    managedMicrophoneEnabled = true;
+    microphoneEnabled = true;
     applicationAudioTrack = null;
+    localApplicationAudioTrack = null;
     connectDefaults;
+    recoveryReadiness;
+    credentialRefreshGeneration = 0;
     fetcher;
     endEndpoint;
     refreshCredentialsCallback;
@@ -110,6 +113,10 @@ export class RealtimeSession {
     lifecycleCredentials;
     diagnostics = new ClientDiagnosticBuffer({ sdkVersion: SDK_VERSION });
     diagnosticReportTimeoutMs = DIAGNOSTIC_REPORT_TIMEOUT_MS;
+    onDiagnosticVisibilityChange = () => {
+        if (globalThis.document?.visibilityState === "hidden")
+            this.flushDiagnostics("page_hidden");
+    };
     constructor(credentials, options = {}) {
         validateSessionCredentials(credentials);
         this.id = credentials.id;
@@ -119,6 +126,10 @@ export class RealtimeSession {
             ? (options.connect ?? {})
             : { ...options.connect, apiBase: normalizeApiBase(options.connect.apiBase) };
         this.apiBase = this.connectDefaults.apiBase ?? this.apiBase;
+        this.recoveryReadiness = {
+            readyTimeoutMs: this.connectDefaults.readyTimeoutMs ?? 15_000,
+            waitForRemoteAudio: this.connectDefaults.waitForRemoteAudio ?? true,
+        };
         this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.endEndpoint = options.endEndpoint ?? null;
         this.refreshCredentialsCallback = options.refreshCredentials ?? null;
@@ -330,6 +341,9 @@ export class RealtimeSession {
         };
     }
     async connect(options = {}) {
+        if (this.startupConnectController || this.manualRejoinController) {
+            throw new Error("A session connection attempt is already in progress");
+        }
         if (["connecting", "connected_not_ready", "connected", "reconnecting", "resuming"]
             .includes(this.stateValue)) {
             throw new Error(`Cannot connect while session is ${this.stateValue}`);
@@ -337,6 +351,17 @@ export class RealtimeSession {
         this.cancelRecovery();
         const controller = new AbortController();
         this.startupConnectController = controller;
+        this.credentialRefreshGeneration += 1;
+        const resolved = { ...this.connectDefaults, ...options };
+        // Keep caller preferences separate from temporary startup-attempt budgets.
+        this.recoveryReadiness = {
+            readyTimeoutMs: resolved.readyTimeoutMs ?? 15_000,
+            waitForRemoteAudio: resolved.waitForRemoteAudio ?? true,
+        };
+        this.microphoneEnabled = resolved.audioTrack
+            ? resolved.audioTrack.enabled !== false
+            : resolved.microphone ?? true;
+        this.setState("connecting");
         try {
             if (this.startupRetryOptions) {
                 await this.connectWithStartupRetry(options, controller);
@@ -369,10 +394,13 @@ export class RealtimeSession {
         const startupOptions = this.startupRetryOptions;
         if (!startupOptions)
             return;
+        const startupStartedAt = performance.now();
         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");
+        let startupRegistered = this.hasConnectedValue;
+        this.apiBase = normalizeApiBase(options.apiBase ?? this.connectDefaults.apiBase ?? this.apiBase);
         try {
             for (const [index, attempt] of startupOptions.attempts.entries()) {
                 const attemptNumber = index + 1;
@@ -385,6 +413,12 @@ export class RealtimeSession {
                 this.startupAttemptController = attemptController;
                 this.notifyStartupAttempt("started", attemptNumber, attempt.readyTimeoutMs);
                 try {
+                    if (!startupRegistered) {
+                        const remainingMs = startupOptions.timeoutMs - (performance.now() - startupStartedAt);
+                        await this.registerStartupRecovery(remainingMs, attemptController.signal);
+                        startupRegistered = true;
+                    }
+                    throwIfAborted(attemptController.signal);
                     if (index === 0) {
                         await this.connectWithMode({ ...options, readyTimeoutMs: attempt.readyTimeoutMs }, false, attemptController.signal, false);
                     }
@@ -422,6 +456,38 @@ export class RealtimeSession {
             globalThis.clearTimeout(timeout);
         }
     }
+    async registerStartupRecovery(timeoutMs, signal) {
+        const reserveMs = Math.min(5_000, timeoutMs / 10);
+        const controller = createLinkedAbortController(signal);
+        const requestTimeout = globalThis.setTimeout(() => {
+            controller.abort(new Error("Startup registration timed out"));
+        }, Math.max(1, reserveMs));
+        try {
+            // Leave room for registration latency and final readiness before the
+            // browser's existing overall deadline. Rejoins never renew this window.
+            const send = () => raceWithAbort(this.fetcher(`${this.apiBase}/sessions/${this.id}/startup`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${this.accessToken}`, "Content-Type": "application/json" },
+                credentials: this.lifecycleCredentials,
+                body: JSON.stringify({ timeout_ms: Math.max(1, Math.floor(Math.min(timeoutMs - reserveMs, 85_000))) }),
+                signal: controller.signal,
+            }), controller.signal);
+            let response = await send();
+            if (response.status === 401 && this.refreshCredentialsCallback) {
+                await this.refreshCredentials(controller.signal);
+                response = await send();
+            }
+            if (!response.ok)
+                throw await httpError(response, "Could not register session startup");
+            const body = await raceWithAbort(response.json(), controller.signal);
+            if (typeof body.remaining_ms !== "number" || body.remaining_ms <= 0) {
+                throw new Error("Session startup window has expired");
+            }
+        }
+        finally {
+            globalThis.clearTimeout(requestTimeout);
+        }
+    }
     notifyStartupAttempt(status, attempt, readyTimeoutMs, error) {
         const maxAttempts = this.startupRetryOptions?.attempts.length ?? 1;
         this.notifyListeners(this.startupAttemptListeners, {
@@ -433,6 +499,7 @@ export class RealtimeSession {
         });
     }
     async connectWithMode(options, recovering, signal, markFailureTerminal = true) {
+        throwIfAborted(signal);
         const blockedStates = recovering
             ? ["connecting", "connected_not_ready", "connected", "reconnecting"]
             : ["connecting", "connected_not_ready", "connected", "reconnecting", "resuming"];
@@ -451,8 +518,6 @@ export class RealtimeSession {
         const apiBase = normalizeApiBase(resolved.apiBase ?? this.apiBase);
         this.validateAudioOptions(microphone, audioTrack);
         this.useManagedMicrophone = microphone;
-        if (!recovering)
-            this.managedMicrophoneEnabled = microphone;
         this.applicationAudioTrack = audioTrack;
         if (!recovering) {
             this.sessionEnded = false;
@@ -476,7 +541,7 @@ export class RealtimeSession {
                 await raceWithAbort(this.publishApplicationAudioTrack(audioTrack), signal);
             }
             else if (microphone) {
-                await raceWithAbort(this.room.localParticipant.setMicrophoneEnabled(this.managedMicrophoneEnabled), signal);
+                await raceWithAbort(this.room.localParticipant.setMicrophoneEnabled(this.microphoneEnabled), signal);
             }
             throwIfAborted(signal);
             this.setState(recovering ? "resuming" : "connected_not_ready");
@@ -489,7 +554,7 @@ export class RealtimeSession {
             if (this.sessionEnded || generation !== this.contextGeneration) {
                 throw new Error("Connection restoration interrupted");
             }
-            await raceWithAbort(this.replacementContext.resume(recovering), signal);
+            this.resumeContextDelivery(recovering);
             throwIfAborted(signal);
             if (this.sessionEnded || generation !== this.contextGeneration) {
                 throw new Error("Connection restoration interrupted");
@@ -551,10 +616,13 @@ export class RealtimeSession {
         });
     }
     async rejoin(apiBase = this.apiBase) {
+        if (this.startupConnectController || this.manualRejoinController) {
+            throw new Error("A session connection attempt is already in progress");
+        }
         if (this.sessionEnded) {
             throw this.terminalSessionError ?? new Error("Cannot rejoin a session that has ended");
         }
-        if (["connecting", "reconnecting", "resuming"].includes(this.stateValue)) {
+        if (["connecting", "connected_not_ready", "reconnecting", "resuming"].includes(this.stateValue)) {
             throw new Error(`Cannot rejoin while session is ${this.stateValue}`);
         }
         this.cancelRecovery();
@@ -589,13 +657,13 @@ export class RealtimeSession {
         }
     }
     async performRejoin(apiBase, options = {}) {
-        const { signal, recovering = true, connect = {}, markFailureTerminal = true, } = 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 raceWithAbort(this.refreshCredentials(), signal);
+            await this.refreshCredentials(signal);
             throwIfAborted(signal);
             response = await this.fetchRoomToken(apiBase, signal);
         }
@@ -611,6 +679,7 @@ export class RealtimeSession {
             throw await raceWithAbort(httpError(response, "Could not renew room token"), signal);
         }
         const payload = (await raceWithAbort(response.json(), signal));
+        throwIfAborted(signal);
         this.credentials = payload.connection;
         if (this.room.state !== LiveKitConnectionState.Disconnected) {
             this.disconnectMode = "rejoin";
@@ -629,16 +698,28 @@ export class RealtimeSession {
                 duration_ms: Date.now() - this.reconnectStartedAt,
             };
         }
-        await this.connectWithMode({
-            ...connect,
-            apiBase,
+        // Startup retries resolve the original caller options with constructor defaults.
+        // A later rejoin restores the audio settings saved by the previous connection.
+        const connectionOptions = connect ?? {
+            ...this.recoveryReadiness,
             microphone: this.useManagedMicrophone,
             ...(this.applicationAudioTrack ? { audioTrack: this.applicationAudioTrack } : {}),
-        }, recovering, signal, markFailureTerminal);
+        };
+        await this.connectWithMode({ ...connectionOptions, apiBase }, recovering, signal, markFailureTerminal);
     }
     async setMicrophoneEnabled(enabled) {
+        // Recovery must see the user's latest intent while the media operation waits.
+        this.microphoneEnabled = enabled;
+        if (this.applicationAudioTrack) {
+            // The room may not know this track yet while publication is pending.
+            const track = this.localApplicationAudioTrack;
+            if (enabled)
+                await track?.unmute();
+            else
+                await track?.mute();
+            return;
+        }
         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);
@@ -665,11 +746,15 @@ export class RealtimeSession {
             context_key: update.key,
             payload_bytes: payloadBytes,
         });
+        const uploading = "image" in update ? this.uploadImageContext(update) : this.uploadTextContext(update);
+        const transferSettled = uploading.then(() => { }, () => { });
         let transferTimeout;
         const transferExpired = new Promise((_resolve, reject) => {
             transferTimeout = globalThis.setTimeout(() => {
                 transferTimedOut = true;
-                const error = new Error(`Context transfer timed out after ${timeoutMs}ms`);
+                const error = new ContextDeliveryError(`Context transfer timed out after ${timeoutMs}ms`, {
+                    retryAfter: transferSettled,
+                });
                 this.recordDiagnostic({
                     operation: "context_transfer",
                     status: "timed_out",
@@ -680,19 +765,13 @@ export class RealtimeSession {
                     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);
         });
         let transfer;
         try {
             transfer = await Promise.race([
-                "image" in update ? this.uploadImageContext(update) : this.uploadTextContext(update),
+                uploading,
                 transferExpired,
             ]);
         }
@@ -708,7 +787,9 @@ export class RealtimeSession {
                 });
                 this.flushDiagnostics("command_failed");
             }
-            throw error;
+            if (error instanceof TypeError || error instanceof ContextDeliveryError)
+                throw error;
+            throw new ContextDeliveryError(toError(error).message, { cause: error });
         }
         finally {
             globalThis.clearTimeout(transferTimeout);
@@ -732,6 +813,11 @@ export class RealtimeSession {
         const message = createClientMessage(this.connectionId, ++this.clientSeq, "context.update", { ...payload });
         return this.sendTrackedCommand(message, timeoutMs, transfer.resend);
     }
+    resumeContextDelivery(restore) {
+        // Audio readiness owns connection recovery. Context delivery has its own
+        // deadlines and retries, and may be interrupted by a later disconnect.
+        void this.replacementContext.resume(restore).catch(() => { });
+    }
     async uploadTextContext(update) {
         const data = new TextEncoder().encode(update.text);
         if (data.byteLength === 0)
@@ -817,6 +903,7 @@ export class RealtimeSession {
         this.failRecovery(new Error("Session disconnected during recovery"));
         this.cancelRecovery();
         this.contextGeneration += 1;
+        this.localApplicationAudioTrack = null;
         this.replacementContext.clear(new Error("Session disconnected"));
         if (this.stateValue === "disconnected")
             return;
@@ -832,6 +919,7 @@ export class RealtimeSession {
         }
     }
     async end(options = {}) {
+        this.credentialRefreshGeneration += 1;
         this.abortStartupConnect(new Error("Session ended"));
         this.startupConnectController = null;
         this.failRecovery(new Error("Session ended during recovery"));
@@ -851,7 +939,7 @@ export class RealtimeSession {
             credentials: request.credentials ?? this.lifecycleCredentials,
         });
         if (response.status === 401 && usesScopedSessionEndpoint && this.refreshCredentialsCallback) {
-            await this.refreshCredentials();
+            await this.refreshCredentials(request.signal ?? undefined);
             headers.set("Authorization", `Bearer ${this.accessToken}`);
             response = await this.fetcher(endpoint, {
                 ...request,
@@ -878,6 +966,17 @@ export class RealtimeSession {
         if (this.stateValue === state)
             return;
         this.stateValue = state;
+        if (state === "connecting" || state === "resuming") {
+            globalThis.document?.addEventListener?.("visibilitychange", this.onDiagnosticVisibilityChange);
+        }
+        if (state === "disconnected" || state === "failed") {
+            globalThis.document?.removeEventListener?.("visibilitychange", this.onDiagnosticVisibilityChange);
+            this.flushDiagnostics("session_finished");
+            const error = new Error(`Session ${state}`);
+            this.contextGeneration += 1;
+            this.replacementContext.clear(error);
+            this.rejectPendingCommands(error);
+        }
         this.notifyListeners(this.stateListeners, state);
     }
     bindRoomEvents() {
@@ -1026,13 +1125,13 @@ export class RealtimeSession {
         this.setState(this.hasConnectedValue ? "resuming" : "connected_not_ready");
         try {
             await this.sendHello();
-            const deadline = Date.now() + (this.connectDefaults.readyTimeoutMs ?? 15_000);
+            const deadline = Date.now() + this.recoveryReadiness.readyTimeoutMs;
             await this.waitForAgentReady(Math.max(deadline - Date.now(), 0));
-            if (this.connectDefaults.waitForRemoteAudio !== false)
+            if (this.recoveryReadiness.waitForRemoteAudio)
                 await this.waitForRemoteAudioTrack(deadline);
             if (this.sessionEnded || generation !== this.contextGeneration)
                 return;
-            await this.replacementContext.resume(true);
+            this.resumeContextDelivery(true);
             if (this.sessionEnded || generation !== this.contextGeneration)
                 return;
             this.setState("connected");
@@ -1311,10 +1410,18 @@ export class RealtimeSession {
             signal?.removeEventListener("abort", cancel);
         }
     }
-    async refreshCredentials() {
+    async refreshCredentials(signal) {
         if (!this.refreshCredentialsCallback)
             return;
-        const refreshed = await this.refreshCredentialsCallback();
+        throwIfAborted(signal);
+        const connectionGeneration = this.contextGeneration;
+        const refreshGeneration = ++this.credentialRefreshGeneration;
+        const refreshed = await raceWithAbort(this.refreshCredentialsCallback(), signal);
+        throwIfAborted(signal);
+        if (connectionGeneration !== this.contextGeneration
+            || refreshGeneration !== this.credentialRefreshGeneration) {
+            throw new Error("Credential refresh was superseded");
+        }
         validateSessionCredentials(refreshed);
         if (refreshed.id !== this.id) {
             throw new Error("Refreshed credentials belong to a different session");
@@ -1409,15 +1516,26 @@ export class RealtimeSession {
         }
     }
     async publishApplicationAudioTrack(audioTrack) {
-        const publishedTrack = audioTrack.clone();
+        const clonedTrack = audioTrack.clone();
+        let publishedTrack = null;
         try {
+            publishedTrack = new LocalAudioTrack(clonedTrack, undefined, true);
+            this.localApplicationAudioTrack = publishedTrack;
+            if (!this.microphoneEnabled) {
+                // LiveKit can re-enable a raw track when wrapping it. Mute the wrapper
+                // before publication so recovery cannot briefly transmit muted input.
+                await publishedTrack.mute();
+            }
             await this.room.localParticipant.publishTrack(publishedTrack, {
                 source: Track.Source.Microphone,
                 name: "voxevolv-application-audio",
             });
         }
         catch (error) {
-            publishedTrack.stop();
+            if (this.localApplicationAudioTrack === publishedTrack) {
+                this.localApplicationAudioTrack = null;
+            }
+            clonedTrack.stop();
             throw error;
         }
     }
@@ -1456,10 +1574,13 @@ export class RealtimeSession {
             const timeout = globalThis.setTimeout(() => {
                 const pending = this.pendingCommands.get(message.message_id);
                 if (pending)
-                    globalThis.clearInterval(pending.retry);
+                    globalThis.clearTimeout(pending.retry);
                 pending?.markSettled();
                 this.pendingCommands.delete(message.message_id);
-                const error = new Error(`Command ${message.type} timed out after ${timeoutMs}ms`);
+                const detail = `Command ${message.type} timed out after ${timeoutMs}ms`;
+                const error = message.type === "context.update"
+                    ? new ContextDeliveryError(detail, { retryAfter: pending?.transferSettled })
+                    : new Error(detail);
                 this.recordDiagnostic({
                     operation: "command_send",
                     status: "timed_out",
@@ -1478,21 +1599,7 @@ export class RealtimeSession {
                 });
                 this.flushDiagnostics("command_timeout");
                 reject(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.publishCommandAttempt(message, true).catch(() => {
-                    // A reconnect may temporarily reject writes; retry until timeout.
-                });
-            }, 500);
             this.pendingCommands.set(message.message_id, {
                 commandType: message.type,
                 message,
@@ -1504,25 +1611,58 @@ export class RealtimeSession {
                 resolve,
                 reject,
                 timeout,
-                retry,
                 settled,
                 markSettled,
-                retryTransfer: retryTransfer
-                    ? async () => {
-                        await retryTransfer();
-                        await this.publishCommandAttempt(message, true);
-                    }
-                    : undefined,
+                retryTransfer,
                 transferRetrying: false,
+                transferRetryRequested: false,
             });
+            this.scheduleCommandRetry(message);
         });
         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
+            // reconnect. Keep the command pending so the retry timer can publish
             // it once the transport accepts writes, or reject at the normal timeout.
         });
         return response;
     }
+    scheduleCommandRetry(message) {
+        const pending = this.pendingCommands.get(message.message_id);
+        if (!pending)
+            return;
+        const delayMs = message.type === "context.update"
+            ? contextRetryDelay(pending.retryCount + 1)
+            : 500;
+        pending.retry = globalThis.setTimeout(() => {
+            void this.retryCommand(message).finally(() => this.scheduleCommandRetry(message));
+        }, delayMs);
+    }
+    async retryCommand(message) {
+        const pending = this.pendingCommands.get(message.message_id);
+        if (!pending)
+            return;
+        if (message.type === "context.update" && (this.sessionEnded || ["reconnecting", "resuming", "disconnected", "failed"].includes(this.stateValue)))
+            return;
+        try {
+            if (pending.transferRetryRequested && pending.retryTransfer) {
+                pending.transferRetryRequested = false;
+                pending.transferRetrying = true;
+                const transfer = pending.retryTransfer();
+                pending.transferSettled = transfer.then(() => { }, () => { });
+                if (pending.contextKey) {
+                    this.replacementContext.blockUntilTransferSettles(pending.contextKey, pending.transferSettled);
+                }
+                await Promise.race([transfer, pending.settled]);
+            }
+            await this.publishCommandAttempt(message, true);
+        }
+        catch {
+            // Failed writes retain their original deadline and retry with backoff.
+        }
+        finally {
+            pending.transferRetrying = false;
+        }
+    }
     publishCommandAttempt(message, retrying) {
         const pending = this.pendingCommands.get(message.message_id);
         if (!pending || pending.publishQueued)
@@ -1632,8 +1772,8 @@ export class RealtimeSession {
             }, this.diagnosticReportTimeoutMs);
         });
         try {
-            const response = await Promise.race([
-                this.fetcher(`${this.apiBase}/sessions/${this.id}/diagnostics`, {
+            const upload = async () => {
+                const response = await this.fetcher(`${this.apiBase}/sessions/${this.id}/diagnostics`, {
                     method: "POST",
                     headers: {
                         Authorization: `Bearer ${this.accessToken}`,
@@ -1642,11 +1782,22 @@ export class RealtimeSession {
                     credentials: this.lifecycleCredentials,
                     body: JSON.stringify(report),
                     signal: controller.signal,
-                }),
-                timeoutExpired,
-            ]);
-            if (!response.ok)
-                throw new Error(`Diagnostic report failed (${response.status})`);
+                    keepalive: true,
+                });
+                const body = await response.json().catch(() => null);
+                if (!response.ok) {
+                    const retryable = response.status === 408 || response.status === 429 || response.status >= 500;
+                    const headerDelay = Number(response.headers.get("Retry-After")) * 1000;
+                    const retryAfterMs = typeof body?.retry_after_ms === "number"
+                        ? body.retry_after_ms : headerDelay;
+                    throw new DiagnosticDeliveryError(`Diagnostic report failed (${response.status})`, retryable, Number.isFinite(retryAfterMs) ? Math.max(retryAfterMs, 0) : 0);
+                }
+                if (body?.report_id !== report.report_id) {
+                    throw new DiagnosticDeliveryError("Diagnostic report was not acknowledged");
+                }
+            };
+            // The receipt body is part of the timeout too, not just the response headers.
+            await Promise.race([upload(), timeoutExpired]);
         }
         finally {
             if (timeout !== undefined)
@@ -1723,8 +1874,8 @@ export class RealtimeSession {
         this.agentDisconnected = false;
         const wasReady = this.agentReady;
         this.agentReady = true;
-        // connect/reconnect owns the transition after hello, audio and context
-        // restoration all finish. Readiness alone is not successful recovery.
+        // connect/reconnect owns the transition after hello and audio are ready.
+        // Context restoration proceeds independently in the background.
         this.readyResolve?.();
         if (!wasReady)
             this.notifyListeners(this.readyListeners, event);
@@ -1741,7 +1892,7 @@ export class RealtimeSession {
         if (event.type === "command.ack" && isCommandAckPayload(event.payload)) {
             this.recordCommandResult(pending, event.type, "acknowledged");
             globalThis.clearTimeout(pending.timeout);
-            globalThis.clearInterval(pending.retry);
+            globalThis.clearTimeout(pending.retry);
             pending.markSettled();
             this.pendingCommands.delete(event.payload.message_id);
             pending.resolve(event.payload);
@@ -1750,7 +1901,7 @@ export class RealtimeSession {
         if (event.type === "context.updated" && isContextUpdatedPayload(event.payload)) {
             this.recordCommandResult(pending, event.type, "acknowledged");
             globalThis.clearTimeout(pending.timeout);
-            globalThis.clearInterval(pending.retry);
+            globalThis.clearTimeout(pending.retry);
             pending.markSettled();
             this.pendingCommands.delete(event.payload.message_id);
             pending.resolve(event.payload);
@@ -1761,18 +1912,13 @@ export class RealtimeSession {
             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;
-                    void pending.retryTransfer()
-                        .catch(() => {
-                        // The command timeout remains authoritative while reconnecting.
-                    })
-                        .finally(() => { pending.transferRetrying = false; });
+                if (event.payload.code === "stream_unavailable" && pending.retryTransfer && !pending.transferRetrying) {
+                    pending.transferRetryRequested = true;
                 }
                 return;
             }
             globalThis.clearTimeout(pending.timeout);
-            globalThis.clearInterval(pending.retry);
+            globalThis.clearTimeout(pending.retry);
             pending.markSettled();
             this.pendingCommands.delete(event.payload.message_id);
             pending.reject(new CommandError(event.payload));
@@ -1784,9 +1930,11 @@ export class RealtimeSession {
                 continue;
             this.recordCommandResult(pending, pending.commandType === "context.update" ? "context.rejected" : "command.error", "failed", "pending_command_cancelled");
             globalThis.clearTimeout(pending.timeout);
-            globalThis.clearInterval(pending.retry);
+            globalThis.clearTimeout(pending.retry);
             pending.markSettled();
-            pending.reject(error);
+            pending.reject(pending.commandType === "context.update"
+                ? new ContextDeliveryError(error.message, { cause: error, retryAfter: pending.transferSettled })
+                : error);
             this.pendingCommands.delete(messageId);
         }
     }
@@ -1821,7 +1969,7 @@ export class RealtimeSession {
                 signal,
             }), signal);
             if (response.status === 401 && this.refreshCredentialsCallback) {
-                await raceWithAbort(this.refreshCredentials(), signal);
+                await this.refreshCredentials(signal);
                 response = await raceWithAbort(this.fetcher(url, {
                     headers: { Authorization: `Bearer ${this.accessToken}` },
                     credentials: this.lifecycleCredentials,