@voxevolv/client 0.3.6 → 0.3.8

package/dist/index.js

@@ -1,20 +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 { 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.6";
+export const SDK_VERSION = "0.3.8";
 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;
@@ -88,11 +88,14 @@ export class RealtimeSession {
     hasConnectedValue = false;
     sessionEnded = false;
     pendingEndEvent = null;
+    agentDisconnected = false;
+    terminalSessionError = null;
     endNotificationDelivered = false;
     disconnectMode = null;
     activeRecovery = null;
     autoRejoinPromise = null;
     autoRejoinController = null;
+    manualRejoinController = null;
     startupConnectController = null;
     startupAttemptController = null;
     useManagedMicrophone = true;
@@ -107,6 +110,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;
@@ -331,7 +338,7 @@ export class RealtimeSession {
             .includes(this.stateValue)) {
             throw new Error(`Cannot connect while session is ${this.stateValue}`);
         }
-        this.cancelAutoRejoin();
+        this.cancelRecovery();
         const controller = new AbortController();
         this.startupConnectController = controller;
         try {
@@ -344,7 +351,11 @@ export class RealtimeSession {
             }
         }
         catch (error) {
-            if (this.startupConnectController === controller && !this.sessionEnded) {
+            if (this.startupConnectController === controller && this.terminalSessionError) {
+                this.sessionEnded = true;
+                this.setState("failed");
+            }
+            else if (this.startupConnectController === controller && !this.sessionEnded) {
                 this.setState("failed");
             }
             throw error;
@@ -362,10 +373,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;
@@ -378,6 +392,11 @@ 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;
+                    }
                     if (index === 0) {
                         await this.connectWithMode({ ...options, readyTimeoutMs: attempt.readyTimeoutMs }, false, attemptController.signal, false);
                     }
@@ -389,6 +408,7 @@ export class RealtimeSession {
                             markFailureTerminal: false,
                         });
                     }
+                    throwIfAborted(controller.signal);
                     this.notifyStartupAttempt("succeeded", attemptNumber, attempt.readyTimeoutMs);
                     return;
                 }
@@ -414,6 +434,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, Math.min(3_000, 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 raceWithAbort(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, {
@@ -451,6 +503,8 @@ export class RealtimeSession {
             this.agentStreamId = null;
             this.reconnectStartedAt = null;
             this.pendingEndEvent = null;
+            this.agentDisconnected = false;
+            this.terminalSessionError = null;
             this.endNotificationDelivered = false;
             this.setState("connecting");
         }
@@ -479,7 +533,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");
@@ -541,28 +595,42 @@ export class RealtimeSession {
         });
     }
     async rejoin(apiBase = this.apiBase) {
+        if (this.sessionEnded) {
+            throw this.terminalSessionError ?? new Error("Cannot rejoin a session that has ended");
+        }
         if (["connecting", "reconnecting", "resuming"].includes(this.stateValue)) {
             throw new Error(`Cannot rejoin while session is ${this.stateValue}`);
         }
-        this.cancelAutoRejoin();
+        this.cancelRecovery();
         const normalizedApiBase = normalizeApiBase(apiBase);
         const recovering = this.hasConnectedValue;
+        const controller = new AbortController();
+        this.manualRejoinController = controller;
         if (recovering) {
             this.beginRecovery("rejoin", 1, { trigger: "manual_rejoin" });
             this.setState("resuming");
         }
         try {
-            await this.performRejoin(normalizedApiBase, { recovering });
+            await this.performRejoin(normalizedApiBase, { recovering, signal: controller.signal });
+            if (this.sessionEnded)
+                return;
             if (recovering)
                 this.completeRecovery();
         }
         catch (error) {
+            if (controller.signal.aborted && !this.terminalSessionError)
+                return;
             const normalizedError = toError(error);
             if (recovering)
                 this.failRecovery(normalizedError);
             this.setState("failed");
             throw error;
         }
+        finally {
+            if (this.manualRejoinController === controller) {
+                this.manualRejoinController = null;
+            }
+        }
     }
     async performRejoin(apiBase, options = {}) {
         const { signal, recovering = true, connect = {}, markFailureTerminal = true, } = options;
@@ -575,7 +643,15 @@ export class RealtimeSession {
             throwIfAborted(signal);
             response = await this.fetchRoomToken(apiBase, signal);
         }
+        // A live ending may arrive while token renewal is in flight.
+        if (this.sessionEnded) {
+            if (this.terminalSessionError)
+                throw this.terminalSessionError;
+            return;
+        }
         if (!response.ok) {
+            if (response.status === 409 && await this.recoverSessionEnd(apiBase, signal))
+                return;
             throw await raceWithAbort(httpError(response, "Could not renew room token"), signal);
         }
         const payload = (await raceWithAbort(response.json(), signal));
@@ -583,7 +659,7 @@ export class RealtimeSession {
         if (this.room.state !== LiveKitConnectionState.Disconnected) {
             this.disconnectMode = "rejoin";
             try {
-                await this.room.disconnect();
+                await raceWithAbort(this.room.disconnect(), signal);
             }
             finally {
                 this.disconnectMode = null;
@@ -633,11 +709,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",
@@ -648,19 +728,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,
             ]);
         }
@@ -676,7 +750,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);
@@ -700,6 +776,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)
@@ -782,7 +863,8 @@ export class RealtimeSession {
     async disconnect() {
         this.abortStartupConnect(new Error("Session disconnected"));
         this.startupConnectController = null;
-        this.cancelAutoRejoin();
+        this.failRecovery(new Error("Session disconnected during recovery"));
+        this.cancelRecovery();
         this.contextGeneration += 1;
         this.replacementContext.clear(new Error("Session disconnected"));
         if (this.stateValue === "disconnected")
@@ -801,7 +883,8 @@ export class RealtimeSession {
     async end(options = {}) {
         this.abortStartupConnect(new Error("Session ended"));
         this.startupConnectController = null;
-        this.cancelAutoRejoin();
+        this.failRecovery(new Error("Session ended during recovery"));
+        this.cancelRecovery();
         this.sessionEnded = true;
         const endpoint = options.endpoint ?? this.endEndpoint ?? `${this.apiBase}/sessions/${this.id}`;
         const request = options.request ?? {};
@@ -844,11 +927,29 @@ 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() {
         this.room.on(RoomEvent.ParticipantDisconnected, (participant) => {
             if (participant.isAgent && !this.disconnectMode) {
+                this.agentDisconnected = true;
+                if (this.terminalSessionError)
+                    return;
+                if (this.sessionEnded) {
+                    this.finishPendingEnd();
+                    return;
+                }
                 this.startAutoRejoin(new Error("Agent disconnected from the room"), { trigger: "agent_disconnected" });
             }
         });
@@ -861,6 +962,8 @@ export class RealtimeSession {
             this.handleLiveKitDisconnected(reason);
         });
         this.room.on(RoomEvent.ConnectionStateChanged, (state) => {
+            if (this.sessionEnded || this.terminalSessionError)
+                return;
             if (state === LiveKitConnectionState.Connected) {
                 const recovering = this.activeRecovery !== null || this.stateValue === "resuming";
                 this.setState(this.agentReady
@@ -989,7 +1092,7 @@ export class RealtimeSession {
                 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");
@@ -1029,6 +1132,8 @@ export class RealtimeSession {
             this.setState("disconnected");
             return;
         }
+        if (this.terminalSessionError)
+            return;
         if (this.shouldAutoRejoin(reason)) {
             this.startAutoRejoin(new Error(`LiveKit disconnected (${disconnectReasonName(reason)})`), { trigger: "livekit_disconnected" });
             return;
@@ -1048,6 +1153,37 @@ export class RealtimeSession {
         this.pendingEndEvent = null;
         this.notifyEnded({ ...ending, type: "session.ended" });
     }
+    finishPendingEnd() {
+        this.deliverPendingEndEvent();
+        // The agent can leave while the browser remains in the room. Close that
+        // transport ourselves, after notifying the application of the true reason.
+        void this.disconnect().catch(() => { });
+    }
+    async recoverSessionEnd(apiBase, signal) {
+        const controller = new AbortController();
+        const cancel = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted)
+            cancel();
+        const timeout = globalThis.setTimeout(() => controller.abort(), 5_000);
+        try {
+            // A later live event may have advanced the cursor past a missed ending.
+            // Replay from the start; event IDs suppress already delivered messages.
+            await this.fetchReplay(apiBase, 0, { signal: controller.signal, terminalOnly: true });
+        }
+        catch {
+            // A 409 also covers failed sessions. Without an authoritative ending,
+            // retain the original HTTP failure rather than invent a normal end.
+        }
+        finally {
+            globalThis.clearTimeout(timeout);
+            signal?.removeEventListener("abort", cancel);
+        }
+        if (!this.sessionEnded || this.terminalSessionError)
+            return false;
+        this.finishPendingEnd();
+        return true;
+    }
     notifyEnded(event) {
         if (this.endNotificationDelivered)
             return;
@@ -1156,6 +1292,8 @@ export class RealtimeSession {
                 throwIfAborted(signal);
                 this.beginRecovery("rejoin", attempt, details);
                 await this.performRejoin(this.apiBase, { signal });
+                if (this.sessionEnded)
+                    return;
                 throwIfAborted(signal);
                 this.reconnectStartedAt = null;
                 this.completeRecovery();
@@ -1173,9 +1311,11 @@ export class RealtimeSession {
         this.replacementContext.clear(lastError);
         this.setState("failed");
     }
-    cancelAutoRejoin() {
+    cancelRecovery() {
         this.autoRejoinController?.abort();
         this.autoRejoinController = null;
+        this.manualRejoinController?.abort();
+        this.manualRejoinController = null;
         this.autoRejoinPromise = null;
         this.activeRecovery = null;
     }
@@ -1242,44 +1382,76 @@ export class RealtimeSession {
         this.accessToken = refreshed.access_token;
         this.credentials = refreshed.connection;
     }
+    async finishSessionFailure(error) {
+        this.sessionEnded = true;
+        this.contextGeneration += 1;
+        this.rejectPendingCommands(error);
+        this.replacementContext.clear(error);
+        this.failRecovery(error);
+        this.cancelRecovery();
+        this.disconnectMode = "connect_failure";
+        try {
+            await this.room.disconnect();
+        }
+        finally {
+            this.disconnectMode = null;
+            this.setState("failed");
+        }
+    }
     observeConvenienceEvents(event) {
         if (event.type === "session.error") {
+            // Teardown errors must not overwrite an already announced normal ending.
+            if (this.sessionEnded)
+                return;
             const error = new SessionErrorEventError(event);
-            if (error.retryable) {
-                this.startupAttemptController?.abort(error);
+            // Retryability applies to an active startup attempt. Once connected,
+            // a durable session.error means the server has failed the session.
+            if (error.retryable && this.startupAttemptController) {
+                this.startupAttemptController.abort(error);
             }
             else {
+                this.terminalSessionError = error;
                 this.abortStartupConnect(error);
+                // Startup owns its aborted attempt's cleanup. An established session
+                // needs to release media and settle recovery immediately on failure.
+                if (!this.startupConnectController) {
+                    void this.finishSessionFailure(error).catch(() => { });
+                }
             }
         }
         if (event.type === "session.ending" || event.type === "session.ended") {
+            // A worker shutdown event can follow a durable session.error. The server
+            // retains FAILED in that case, so it must not become a normal completion.
+            if (this.terminalSessionError)
+                return;
             this.abortStartupConnect(new Error("Session ended during startup"));
             this.contextGeneration += 1;
             this.rejectPendingCommands(new Error("Session ended"));
+            this.failRecovery(new Error("Session ended during recovery"));
         }
         if (event.type === "session.ending") {
             // The server announced an intentional hang-up before tearing down the
             // room, so the coming disconnect must not fail recovery or auto-rejoin.
             this.sessionEnded = true;
-            this.cancelAutoRejoin();
+            this.cancelRecovery();
             this.replacementContext.clear(new Error("Session ended"));
-            this.pendingEndEvent = event;
+            // Match the server's first terminal outcome, even if teardown announces
+            // another ending before the agent has left the room.
+            this.pendingEndEvent ??= event;
+            if (!this.hasConnectedValue
+                || this.agentDisconnected
+                || this.room.state === LiveKitConnectionState.Disconnected) {
+                this.finishPendingEnd();
+            }
         }
         if (event.type === "session.ended") {
+            const ending = this.pendingEndEvent;
             this.pendingEndEvent = null;
-            const recoveryWasActive = (this.autoRejoinPromise !== null
-                || this.activeRecovery !== null
-                || this.stateValue === "reconnecting"
-                || this.stateValue === "resuming");
             this.sessionEnded = true;
             this.replacementContext.clear(new Error("Session ended"));
-            if (this.activeRecovery !== null) {
-                this.failRecovery(new Error("Session ended during recovery"));
-            }
-            this.cancelAutoRejoin();
-            this.notifyEnded(event);
-            if (recoveryWasActive)
-                this.setState("disconnected");
+            this.cancelRecovery();
+            this.notifyEnded(ending ? { ...ending, type: "session.ended" } : event);
+            void this.disconnect().catch(() => { });
         }
         if (event.type.endsWith(".error"))
             this.notifyListeners(this.errorListeners, event);
@@ -1344,10 +1516,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",
@@ -1366,21 +1541,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,
@@ -1392,25 +1553,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)
@@ -1520,8 +1714,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}`,
@@ -1530,11 +1724,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)
@@ -1608,10 +1813,11 @@ export class RealtimeSession {
             return;
         }
         this.agentStreamId = event.stream_id;
+        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);
@@ -1628,7 +1834,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);
@@ -1637,7 +1843,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);
@@ -1648,18 +1854,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));
@@ -1671,9 +1872,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);
         }
     }
@@ -1695,23 +1898,31 @@ export class RealtimeSession {
         if (durationMs > 2_000)
             this.flushDiagnostics("slow_operation");
     }
-    async fetchReplay(apiBase, afterSeq) {
+    async fetchReplay(apiBase, afterSeq, options = {}) {
+        const { signal, terminalOnly = false } = options;
         let nextAfter = afterSeq;
         while (true) {
-            let response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, {
+            throwIfAborted(signal);
+            const url = `${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`
+                + (terminalOnly ? "&terminal_only=true" : "");
+            let response = await raceWithAbort(this.fetcher(url, {
                 headers: { Authorization: `Bearer ${this.accessToken}` },
                 credentials: this.lifecycleCredentials,
-            });
+                signal,
+            }), signal);
             if (response.status === 401 && this.refreshCredentialsCallback) {
-                await this.refreshCredentials();
-                response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, {
+                await raceWithAbort(this.refreshCredentials(), signal);
+                response = await raceWithAbort(this.fetcher(url, {
                     headers: { Authorization: `Bearer ${this.accessToken}` },
                     credentials: this.lifecycleCredentials,
-                });
+                    signal,
+                }), signal);
             }
-            if (!response.ok)
-                throw await httpError(response, "Could not replay session events");
-            const page = (await response.json());
+            if (!response.ok) {
+                throw await raceWithAbort(httpError(response, "Could not replay session events"), signal);
+            }
+            const page = (await raceWithAbort(response.json(), signal));
+            throwIfAborted(signal);
             for (const stored of page.items) {
                 nextAfter = Math.max(nextAfter, stored.server_seq);
                 const event = {