@voxevolv/client 0.3.4 → 0.3.5

package/dist/index.js

@@ -6,9 +6,15 @@ 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.4";
+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;
@@ -23,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;
@@ -34,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();
@@ -61,6 +82,7 @@ export class RealtimeSession {
     readyResolve = null;
     replayPromise = null;
     pendingCommands = new Map();
+    commandPublishTail = Promise.resolve();
     toolHandlers = new Map();
     apiBase = "/v1";
     hasConnectedValue = false;
@@ -71,6 +93,8 @@ export class RealtimeSession {
     activeRecovery = null;
     autoRejoinPromise = null;
     autoRejoinController = null;
+    startupConnectController = null;
+    startupAttemptController = null;
     useManagedMicrophone = true;
     managedMicrophoneEnabled = true;
     applicationAudioTrack = null;
@@ -79,6 +103,7 @@ export class RealtimeSession {
     endEndpoint;
     refreshCredentialsCallback;
     autoRejoinOptions;
+    startupRetryOptions;
     lifecycleCredentials;
     diagnostics = new ClientDiagnosticBuffer({ sdkVersion: SDK_VERSION });
     diagnosticReportTimeoutMs = DIAGNOSTIC_REPORT_TIMEOUT_MS;
@@ -95,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 ?? {})) {
@@ -194,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");
@@ -302,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;
@@ -337,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)
@@ -356,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");
@@ -365,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();
@@ -375,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}`);
@@ -392,7 +552,7 @@ export class RealtimeSession {
             this.setState("resuming");
         }
         try {
-            await this.performRejoin(normalizedApiBase, undefined, recovering);
+            await this.performRejoin(normalizedApiBase, { recovering });
             if (recovering)
                 this.completeRecovery();
         }
@@ -404,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";
@@ -436,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);
@@ -617,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"));
@@ -634,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}`;
@@ -988,7 +1155,7 @@ export class RealtimeSession {
                 }
                 throwIfAborted(signal);
                 this.beginRecovery("rejoin", attempt, details);
-                await this.performRejoin(this.apiBase, signal);
+                await this.performRejoin(this.apiBase, { signal });
                 throwIfAborted(signal);
                 this.reconnectStartedAt = null;
                 this.completeRecovery();
@@ -1034,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) {
@@ -1052,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);
@@ -1076,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"));
         }
@@ -1114,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 {
@@ -1156,11 +1338,14 @@ export class RealtimeSession {
             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({
@@ -1203,10 +1388,13 @@ export class RealtimeSession {
                 contextKey,
                 payloadBytes,
                 retryCount: 0,
+                publishQueued: false,
                 resolve,
                 reject,
                 timeout,
                 retry,
+                settled,
+                markSettled,
                 retryTransfer: retryTransfer
                     ? async () => {
                         await retryTransfer();
@@ -1216,17 +1404,32 @@ export class RealtimeSession {
                 transferRetrying: false,
             });
         });
-        try {
-            await this.publishCommandAttempt(message, false);
-        }
-        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;
     }
-    async publishCommandAttempt(message, retrying) {
+    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;
@@ -1246,7 +1449,11 @@ export class RealtimeSession {
         }
         const attemptStartedAt = Date.now();
         try {
-            await this.publishCommand(message);
+            let publishFinished = false;
+            const publish = this.publishCommand(message).then(() => { publishFinished = true; });
+            await Promise.race([publish, pending.settled]);
+            if (!publishFinished)
+                return;
         }
         catch (error) {
             this.recordDiagnostic({
@@ -1422,6 +1629,7 @@ export class RealtimeSession {
             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;
@@ -1430,6 +1638,7 @@ export class RealtimeSession {
             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;
@@ -1451,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));
         }
@@ -1462,6 +1672,7 @@ export class RealtimeSession {
             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);
         }
@@ -1549,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,
@@ -1569,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)
@@ -1671,22 +1973,22 @@ function diagnosticEventType(type) {
 }
 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;
 }