@voxevolv/client 0.1.0

package/dist/index.js

@@ -0,0 +1,796 @@
+import { ConnectionState as LiveKitConnectionState, DataPacket_Kind, Room, RoomEvent, RpcError, Track, } from "livekit-client";
+import { createClientMessage, CommandError, EventCursor, isCommandAckPayload, isCommandErrorPayload, isContextRejectedPayload, isContextUpdatePayload, isContextUpdatedPayload, isRealtimeEvent, } from "./protocol.js";
+export { CommandError, EventCursor, createClientMessage, isCommandAckPayload, isCommandErrorPayload, isContextRejectedPayload, isContextUpdatePayload, isContextUpdatedPayload, isRealtimeEvent, } from "./protocol.js";
+export { decodeAgentSnapshotPayload, decodeClientHelloPayload, decodeClientMessage, decodeCommandAckPayload, decodeCommandErrorPayload, decodeContextRejectedPayload, decodeContextUpdatePayload, decodeContextUpdatedPayload, decodeRealtimeEvent, } from "./generated/protocol-codecs.js";
+export const SDK_VERSION = "0.1.0";
+export class RealtimeSessionHttpError extends Error {
+    status;
+    code;
+    requestId;
+    details;
+    constructor(message, options) {
+        super(message);
+        this.name = "RealtimeSessionHttpError";
+        this.status = options.status;
+        this.code = options.code ?? null;
+        this.requestId = options.requestId ?? null;
+        this.details = options.details ?? [];
+    }
+}
+export class RealtimeSession {
+    id;
+    room;
+    accessToken;
+    credentials;
+    stateValue = "idle";
+    listeners = new Set();
+    stateListeners = new Set();
+    gapListeners = new Set();
+    remoteAudioTrackListeners = new Set();
+    remoteAudioTrackUnsubscribedListeners = new Set();
+    readyListeners = new Set();
+    userTranscriptListeners = new Set();
+    agentTranscriptListeners = new Set();
+    errorListeners = new Set();
+    endedListeners = new Set();
+    toolCallListeners = new Set();
+    audioPlaybackBlockedListeners = new Set();
+    remoteAudioStreams = new WeakMap();
+    cursor = new EventCursor();
+    connectionId = `conn_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
+    clientSeq = 0;
+    lastHelloMessageId = null;
+    agentReady = false;
+    readyResolve = null;
+    replayPromise = null;
+    pendingCommands = new Map();
+    toolHandlers = new Map();
+    apiBase = "/v1";
+    useManagedMicrophone = true;
+    applicationAudioTrack = null;
+    connectDefaults;
+    fetcher;
+    endEndpoint;
+    refreshCredentialsCallback;
+    constructor(credentials, options = {}) {
+        validateSessionCredentials(credentials);
+        this.id = credentials.id;
+        this.accessToken = credentials.access_token;
+        this.credentials = credentials.connection;
+        this.connectDefaults = options.connect?.apiBase === undefined
+            ? (options.connect ?? {})
+            : { ...options.connect, apiBase: normalizeApiBase(options.connect.apiBase) };
+        this.apiBase = this.connectDefaults.apiBase ?? this.apiBase;
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.endEndpoint = options.endEndpoint ?? null;
+        this.refreshCredentialsCallback = options.refreshCredentials ?? null;
+        this.room = new Room({ adaptiveStream: true, dynacast: true });
+        for (const [name, handler] of Object.entries(options.tools ?? {})) {
+            this.registerTool(name, handler);
+        }
+        this.room.registerRpcMethod("voxevolv.tool.invoke", async (invocation) => {
+            let payload;
+            try {
+                payload = JSON.parse(invocation.payload);
+            }
+            catch (error) {
+                throw new RpcError(1500, "Tool invocation payload was not valid JSON", undefined, { cause: error });
+            }
+            if (typeof payload.name !== "string") {
+                throw new RpcError(1500, "Tool invocation did not include a valid name");
+            }
+            const handler = this.toolHandlers.get(payload.name);
+            if (!handler)
+                throw new RpcError(1500, `No browser handler is registered for ${payload.name}`);
+            if (!payload.arguments || typeof payload.arguments !== "object" || Array.isArray(payload.arguments)) {
+                throw new RpcError(1500, "Tool invocation arguments must be an object");
+            }
+            const callId = typeof payload.call_id === "string" ? payload.call_id : invocation.requestId;
+            const arguments_ = payload.arguments;
+            this.notifyListeners(this.toolCallListeners, {
+                name: payload.name,
+                callId,
+                arguments: arguments_,
+            });
+            try {
+                const result = await handler(arguments_, { callId });
+                return JSON.stringify(result ?? null);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Browser tool handler failed";
+                throw new RpcError(1500, message, undefined, { cause: error });
+            }
+        });
+        this.bindRoomEvents();
+    }
+    static async create(options) {
+        if ("connect" in options) {
+            throw new TypeError("RealtimeSession.create() accepts apiBase and media options at the top level, not in connect");
+        }
+        const { endpoint, request, microphone, audioTrack, readyTimeoutMs, apiBase, ...sessionOptions } = options;
+        if (!endpoint)
+            throw new TypeError("endpoint is required");
+        if (!apiBase) {
+            throw new TypeError("apiBase is required so rejoin, replay, and end use the intended VoxEvolv API or application proxy");
+        }
+        const normalizedApiBase = normalizeApiBase(apiBase);
+        const fetcher = sessionOptions.fetch ?? globalThis.fetch.bind(globalThis);
+        const response = await fetcher(endpoint, { ...request, method: "POST" });
+        if (!response.ok)
+            throw await httpError(response, "Could not create realtime session");
+        const credentials = await response.json();
+        return new RealtimeSession(credentials, {
+            ...sessionOptions,
+            fetch: fetcher,
+            connect: { microphone, audioTrack, readyTimeoutMs, apiBase: normalizedApiBase },
+        });
+    }
+    get state() {
+        return this.stateValue;
+    }
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    onStateChange(listener) {
+        this.stateListeners.add(listener);
+        this.notifyListeners(new Set([listener]), this.stateValue);
+        return () => this.stateListeners.delete(listener);
+    }
+    onProtocolGap(listener) {
+        this.gapListeners.add(listener);
+        return () => this.gapListeners.delete(listener);
+    }
+    onRemoteAudioTrack(listener) {
+        this.remoteAudioTrackListeners.add(listener);
+        return () => this.remoteAudioTrackListeners.delete(listener);
+    }
+    onRemoteAudioTrackUnsubscribed(listener) {
+        this.remoteAudioTrackUnsubscribedListeners.add(listener);
+        return () => this.remoteAudioTrackUnsubscribedListeners.delete(listener);
+    }
+    onReady(listener) {
+        this.readyListeners.add(listener);
+        return () => this.readyListeners.delete(listener);
+    }
+    onUserTranscript(listener) {
+        this.userTranscriptListeners.add(listener);
+        return () => this.userTranscriptListeners.delete(listener);
+    }
+    onAgentTranscript(listener) {
+        this.agentTranscriptListeners.add(listener);
+        return () => this.agentTranscriptListeners.delete(listener);
+    }
+    onError(listener) {
+        this.errorListeners.add(listener);
+        return () => this.errorListeners.delete(listener);
+    }
+    onEnded(listener) {
+        this.endedListeners.add(listener);
+        return () => this.endedListeners.delete(listener);
+    }
+    onToolCall(listener) {
+        this.toolCallListeners.add(listener);
+        return () => this.toolCallListeners.delete(listener);
+    }
+    onAudioPlaybackBlocked(listener) {
+        this.audioPlaybackBlockedListeners.add(listener);
+        return () => this.audioPlaybackBlockedListeners.delete(listener);
+    }
+    registerTool(name, handler) {
+        if (["connecting", "connected_not_ready", "connected", "reconnecting"].includes(this.stateValue)) {
+            throw new Error("Browser tools must be registered before connect()");
+        }
+        if (!/^[a-z][a-z0-9_]{0,79}$/.test(name)) {
+            throw new TypeError("Tool name must be lowercase letters, numbers, and underscores");
+        }
+        if (this.toolHandlers.has(name))
+            throw new TypeError(`Tool ${name} is already registered`);
+        this.toolHandlers.set(name, handler);
+        return () => {
+            if (this.toolHandlers.get(name) === handler)
+                this.toolHandlers.delete(name);
+        };
+    }
+    async connect(options = {}) {
+        if (["connecting", "connected_not_ready", "connected", "reconnecting"].includes(this.stateValue)) {
+            throw new Error(`Cannot connect while session is ${this.stateValue}`);
+        }
+        const resolved = { ...this.connectDefaults, ...options };
+        const audioTrack = resolved.audioTrack ?? null;
+        const microphone = resolved.microphone ?? audioTrack === null;
+        const readyTimeoutMs = resolved.readyTimeoutMs ?? 15_000;
+        const apiBase = normalizeApiBase(resolved.apiBase ?? this.apiBase);
+        this.validateAudioOptions(microphone, audioTrack);
+        this.useManagedMicrophone = microphone;
+        this.applicationAudioTrack = audioTrack;
+        this.setState("connecting");
+        this.apiBase = apiBase;
+        this.agentReady = false;
+        try {
+            await this.room.connect(this.credentials.url, this.credentials.token);
+            if (audioTrack) {
+                await this.publishApplicationAudioTrack(audioTrack);
+            }
+            else if (microphone) {
+                await this.room.localParticipant.setMicrophoneEnabled(true);
+            }
+            this.setState("connected_not_ready");
+            await this.sendHello();
+            await this.waitForAgentReady(readyTimeoutMs);
+            this.setState("connected");
+        }
+        catch (error) {
+            try {
+                await this.room.disconnect();
+            }
+            catch {
+                // Preserve the original connection/readiness failure.
+            }
+            this.setState("failed");
+            throw error;
+        }
+    }
+    async rejoin(apiBase = this.apiBase) {
+        if (["connecting", "reconnecting"].includes(this.stateValue)) {
+            throw new Error(`Cannot rejoin while session is ${this.stateValue}`);
+        }
+        const normalizedApiBase = normalizeApiBase(apiBase);
+        let response = await this.fetchRoomToken(normalizedApiBase);
+        if (response.status === 401 && this.refreshCredentialsCallback) {
+            await this.refreshCredentials();
+            response = await this.fetchRoomToken(normalizedApiBase);
+        }
+        if (!response.ok)
+            throw await httpError(response, "Could not renew room token");
+        const payload = (await response.json());
+        this.credentials = payload.connection;
+        if (["connected", "connected_not_ready"].includes(this.stateValue)) {
+            await this.disconnect();
+        }
+        await this.connect({
+            apiBase: normalizedApiBase,
+            microphone: this.useManagedMicrophone,
+            ...(this.applicationAudioTrack ? { audioTrack: this.applicationAudioTrack } : {}),
+        });
+    }
+    async setMicrophoneEnabled(enabled) {
+        await this.room.localParticipant.setMicrophoneEnabled(enabled);
+    }
+    async sendCommand(type, payload, timeoutMs = 10_000) {
+        const message = createClientMessage(this.connectionId, ++this.clientSeq, type, payload);
+        return this.sendTrackedCommand(message, timeoutMs);
+    }
+    async updateContext(update, timeoutMs = 20_000) {
+        const transfer = "image" in update
+            ? await this.uploadImageContext(update)
+            : await this.uploadTextContext(update);
+        const { payload } = transfer;
+        if (!isContextUpdatePayload(payload)) {
+            throw new TypeError("Invalid context update payload");
+        }
+        const message = createClientMessage(this.connectionId, ++this.clientSeq, "context.update", { ...payload });
+        return this.sendTrackedCommand(message, timeoutMs, transfer.resend);
+    }
+    async uploadTextContext(update) {
+        const data = new TextEncoder().encode(update.text);
+        if (data.byteLength === 0)
+            throw new TypeError("Context text cannot be empty");
+        if (data.byteLength > 262_144) {
+            throw new TypeError("Context text must be at most 262144 UTF-8 bytes");
+        }
+        const base = {
+            key: update.key,
+            mode: update.mode,
+            label: update.label ?? "",
+            respond: update.respond ?? false,
+        };
+        if (data.byteLength <= 32_768)
+            return { payload: { ...base, text: update.text } };
+        const sha256 = await sha256Hex(data);
+        const streamId = contextStreamId();
+        const send = async () => {
+            const writer = await this.room.localParticipant.streamText({
+                streamId,
+                topic: "voxevolv.context.text",
+                totalSize: data.byteLength,
+                attributes: { sha256 },
+            });
+            await writer.write(update.text);
+            await writer.close();
+        };
+        await send();
+        return {
+            payload: {
+                ...base,
+                text_stream: { stream_id: streamId, bytes: data.byteLength, sha256 },
+            },
+            resend: send,
+        };
+    }
+    async uploadImageContext(update) {
+        const allowed = new Set(["image/jpeg", "image/png", "image/webp"]);
+        if (!allowed.has(update.image.type)) {
+            throw new TypeError("Image context must be JPEG, PNG, or WebP");
+        }
+        const data = new Uint8Array(await update.image.arrayBuffer());
+        if (data.byteLength === 0 || data.byteLength > 5_242_880) {
+            throw new TypeError("Image context must be between 1 byte and 5 MiB");
+        }
+        const sha256 = await sha256Hex(data);
+        const streamId = contextStreamId();
+        const send = async () => {
+            const writer = await this.room.localParticipant.streamBytes({
+                streamId,
+                topic: "voxevolv.context.image",
+                name: "context-image",
+                mimeType: update.image.type,
+                totalSize: data.byteLength,
+                attributes: { sha256 },
+            });
+            await writer.write(data);
+            await writer.close();
+        };
+        await send();
+        return {
+            payload: {
+                key: update.key,
+                mode: "replace",
+                label: update.label ?? "",
+                image: {
+                    stream_id: streamId,
+                    mime: update.image.type,
+                    bytes: data.byteLength,
+                    sha256,
+                    ...(update.width === undefined ? {} : { width: update.width }),
+                    ...(update.height === undefined ? {} : { height: update.height }),
+                    detail: update.detail ?? "low",
+                },
+                respond: update.respond ?? false,
+            },
+            resend: send,
+        };
+    }
+    async disconnect() {
+        if (this.stateValue === "disconnected")
+            return;
+        this.rejectPendingCommands(new Error("Session disconnected before command completion"));
+        await this.room.disconnect();
+        this.setState("disconnected");
+    }
+    async end(options = {}) {
+        const endpoint = options.endpoint ?? this.endEndpoint ?? `${this.apiBase}/sessions/${this.id}`;
+        const request = options.request ?? {};
+        const headers = new Headers(request.headers);
+        const usesScopedSessionEndpoint = !options.endpoint && !this.endEndpoint;
+        if (!headers.has("Authorization") && usesScopedSessionEndpoint) {
+            headers.set("Authorization", `Bearer ${this.accessToken}`);
+        }
+        let response = await this.fetcher(endpoint, {
+            ...request,
+            method: request.method ?? "DELETE",
+            headers,
+        });
+        if (response.status === 401 && usesScopedSessionEndpoint && this.refreshCredentialsCallback) {
+            await this.refreshCredentials();
+            headers.set("Authorization", `Bearer ${this.accessToken}`);
+            response = await this.fetcher(endpoint, {
+                ...request,
+                method: request.method ?? "DELETE",
+                headers,
+            });
+        }
+        if (!response.ok)
+            throw await httpError(response, "Could not end realtime session");
+        if (options.disconnect ?? true)
+            await this.disconnect();
+    }
+    async replay(apiBase = this.apiBase, afterSeq = this.cursor.lastServerSeq) {
+        if (this.replayPromise)
+            return this.replayPromise;
+        const normalizedApiBase = normalizeApiBase(apiBase);
+        this.replayPromise = this.fetchReplay(normalizedApiBase, afterSeq).finally(() => {
+            this.replayPromise = null;
+        });
+        return this.replayPromise;
+    }
+    setState(state) {
+        if (this.stateValue === state)
+            return;
+        this.stateValue = state;
+        this.notifyListeners(this.stateListeners, state);
+    }
+    bindRoomEvents() {
+        this.room.on(RoomEvent.Reconnecting, () => {
+            this.agentReady = false;
+            this.rejectPendingCommands(new Error("Connection interrupted before command completion"), true);
+            this.setState("reconnecting");
+        });
+        this.room.on(RoomEvent.Reconnected, () => {
+            this.connectionId = `conn_${Math.random().toString(36).slice(2)}_${Date.now().toString(36)}`;
+            this.clientSeq = 0;
+            void this.sendHello().catch(() => this.setState("failed"));
+            this.setState("connected_not_ready");
+        });
+        this.room.on(RoomEvent.Disconnected, () => {
+            this.agentReady = false;
+            this.rejectPendingCommands(new Error("Session disconnected before command completion"));
+            this.setState("disconnected");
+        });
+        this.room.on(RoomEvent.ConnectionStateChanged, (state) => {
+            if (state === LiveKitConnectionState.Connected) {
+                this.setState(this.agentReady ? "connected" : "connected_not_ready");
+            }
+        });
+        this.room.on(RoomEvent.TrackSubscribed, (track) => {
+            if (track.kind !== Track.Kind.Audio)
+                return;
+            const element = track.attach();
+            element.dataset.voxevolvRemoteAudio = "true";
+            element.style.display = "none";
+            document.body.appendChild(element);
+            try {
+                const playback = element.play();
+                void playback.catch((error) => {
+                    this.notifyListeners(this.audioPlaybackBlockedListeners, {
+                        error,
+                        element,
+                        track: track.mediaStreamTrack,
+                    });
+                });
+            }
+            catch (error) {
+                this.notifyListeners(this.audioPlaybackBlockedListeners, {
+                    error,
+                    element,
+                    track: track.mediaStreamTrack,
+                });
+            }
+            const stream = new MediaStream([track.mediaStreamTrack]);
+            this.remoteAudioStreams.set(track, stream);
+            this.notifyRemoteAudioListeners(this.remoteAudioTrackListeners, track.mediaStreamTrack, stream);
+        });
+        this.room.on(RoomEvent.TrackUnsubscribed, (track) => {
+            if (track.kind !== Track.Kind.Audio)
+                return;
+            const stream = this.remoteAudioStreams.get(track) ?? new MediaStream([track.mediaStreamTrack]);
+            this.notifyRemoteAudioListeners(this.remoteAudioTrackUnsubscribedListeners, track.mediaStreamTrack, stream);
+            this.remoteAudioStreams.delete(track);
+            track.detach().forEach((element) => element.remove());
+        });
+        this.room.on(RoomEvent.DataReceived, (data, _participant, kind, topic) => {
+            if (topic !== "voxevolv.events" || kind !== DataPacket_Kind.RELIABLE)
+                return;
+            let value;
+            try {
+                value = JSON.parse(new TextDecoder().decode(data));
+            }
+            catch {
+                // Ignore data from other room participants that is not a VoxEvolv envelope.
+                return;
+            }
+            if (!isRealtimeEvent(value))
+                return;
+            const result = this.cursor.accept(value);
+            if (result.gap) {
+                this.notifyListeners(this.gapListeners, result.gap);
+                void this.replay(this.apiBase, result.gap.after_server_seq);
+            }
+            if (!result.deliver)
+                return;
+            this.observeReadiness(value);
+            this.observeCommandResult(value);
+            this.observeConvenienceEvents(value);
+            this.notifyListeners(this.listeners, value);
+        });
+    }
+    notifyListeners(listeners, value) {
+        for (const listener of listeners) {
+            try {
+                listener(value);
+            }
+            catch (error) {
+                console.error("VoxEvolv event listener failed", error);
+            }
+        }
+    }
+    notifyRemoteAudioListeners(listeners, track, stream) {
+        for (const listener of listeners) {
+            try {
+                listener(track, stream);
+            }
+            catch (error) {
+                console.error("VoxEvolv remote audio listener failed", error);
+            }
+        }
+    }
+    validateAudioOptions(microphone, audioTrack) {
+        if (microphone && audioTrack) {
+            throw new TypeError("microphone and audioTrack cannot both be enabled");
+        }
+        if (!audioTrack)
+            return;
+        if (audioTrack.kind !== "audio") {
+            throw new TypeError("audioTrack must be an audio MediaStreamTrack");
+        }
+        if (audioTrack.readyState === "ended") {
+            throw new TypeError("audioTrack has already ended");
+        }
+    }
+    async fetchRoomToken(apiBase) {
+        return this.fetcher(`${apiBase}/sessions/${this.id}/room-tokens`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.accessToken}` },
+        });
+    }
+    async refreshCredentials() {
+        if (!this.refreshCredentialsCallback)
+            return;
+        const refreshed = await this.refreshCredentialsCallback();
+        validateSessionCredentials(refreshed);
+        if (refreshed.id !== this.id) {
+            throw new Error("Refreshed credentials belong to a different session");
+        }
+        this.accessToken = refreshed.access_token;
+        this.credentials = refreshed.connection;
+    }
+    observeConvenienceEvents(event) {
+        if (event.type === "session.ended")
+            this.notifyListeners(this.endedListeners, event);
+        if (event.type.endsWith(".error"))
+            this.notifyListeners(this.errorListeners, event);
+        const transcript = transcriptEvent(event);
+        if (!transcript)
+            return;
+        this.notifyListeners(transcript.role === "user" ? this.userTranscriptListeners : this.agentTranscriptListeners, transcript);
+    }
+    async publishApplicationAudioTrack(audioTrack) {
+        const publishedTrack = audioTrack.clone();
+        try {
+            await this.room.localParticipant.publishTrack(publishedTrack, {
+                source: Track.Source.Microphone,
+                name: "voxevolv-application-audio",
+            });
+        }
+        catch (error) {
+            publishedTrack.stop();
+            throw error;
+        }
+    }
+    async sendHello() {
+        const message = createClientMessage(this.connectionId, ++this.clientSeq, "client.hello", {
+            last_server_seq: this.cursor.lastServerSeq,
+            sdk: `@voxevolv/client@${SDK_VERSION}`,
+            tool_handlers: [...this.toolHandlers.keys()].sort(),
+        });
+        this.lastHelloMessageId = message.message_id;
+        await this.sendTrackedCommand(message, 10_000);
+    }
+    async sendTrackedCommand(message, timeoutMs, retryTransfer) {
+        const response = new Promise((resolve, reject) => {
+            const timeout = globalThis.setTimeout(() => {
+                const pending = this.pendingCommands.get(message.message_id);
+                if (pending)
+                    globalThis.clearInterval(pending.retry);
+                this.pendingCommands.delete(message.message_id);
+                reject(new Error(`Command ${message.type} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const retry = globalThis.setInterval(() => {
+                void this.publishCommand(message).catch(() => {
+                    // A reconnect may temporarily reject writes; retry until timeout.
+                });
+            }, 500);
+            this.pendingCommands.set(message.message_id, {
+                commandType: message.type,
+                resolve,
+                reject,
+                timeout,
+                retry,
+                retryTransfer: retryTransfer
+                    ? async () => {
+                        await retryTransfer();
+                        await this.publishCommand(message);
+                    }
+                    : undefined,
+                transferRetrying: false,
+            });
+        });
+        try {
+            await this.publishCommand(message);
+        }
+        catch (error) {
+            const pending = this.pendingCommands.get(message.message_id);
+            if (pending) {
+                globalThis.clearTimeout(pending.timeout);
+                globalThis.clearInterval(pending.retry);
+                this.pendingCommands.delete(message.message_id);
+                pending.reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        }
+        return response;
+    }
+    async publishCommand(message) {
+        await this.room.localParticipant.publishData(new TextEncoder().encode(JSON.stringify(message)), { reliable: true, topic: "voxevolv.commands" });
+    }
+    waitForAgentReady(timeoutMs) {
+        if (this.agentReady)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const timeout = globalThis.setTimeout(() => {
+                this.readyResolve = null;
+                reject(new Error(`Agent did not become ready within ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.readyResolve = () => {
+                globalThis.clearTimeout(timeout);
+                this.readyResolve = null;
+                resolve();
+            };
+        });
+    }
+    observeReadiness(event) {
+        const payload = event.payload;
+        const snapshotReady = event.type === "agent.snapshot"
+            && payload.status === "ready"
+            && payload.connection_id === this.connectionId
+            && payload.ack_message_id === this.lastHelloMessageId;
+        if (event.type !== "agent.ready" && !snapshotReady)
+            return;
+        const wasReady = this.agentReady;
+        this.agentReady = true;
+        if (this.room.state === LiveKitConnectionState.Connected)
+            this.setState("connected");
+        this.readyResolve?.();
+        if (!wasReady)
+            this.notifyListeners(this.readyListeners, event);
+    }
+    observeCommandResult(event) {
+        if (event.type !== "command.ack"
+            && event.type !== "command.error"
+            && event.type !== "context.updated"
+            && event.type !== "context.rejected")
+            return;
+        const pending = this.pendingCommands.get(String(event.payload.message_id ?? ""));
+        if (!pending)
+            return;
+        if (event.type === "command.ack" && isCommandAckPayload(event.payload)) {
+            globalThis.clearTimeout(pending.timeout);
+            globalThis.clearInterval(pending.retry);
+            this.pendingCommands.delete(event.payload.message_id);
+            pending.resolve(event.payload);
+            return;
+        }
+        if (event.type === "context.updated" && isContextUpdatedPayload(event.payload)) {
+            globalThis.clearTimeout(pending.timeout);
+            globalThis.clearInterval(pending.retry);
+            this.pendingCommands.delete(event.payload.message_id);
+            pending.resolve(event.payload);
+            return;
+        }
+        if ((event.type === "command.error" && isCommandErrorPayload(event.payload))
+            || (event.type === "context.rejected" && isContextRejectedPayload(event.payload))) {
+            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; });
+                }
+                return;
+            }
+            globalThis.clearTimeout(pending.timeout);
+            globalThis.clearInterval(pending.retry);
+            this.pendingCommands.delete(event.payload.message_id);
+            pending.reject(new CommandError(event.payload));
+        }
+    }
+    rejectPendingCommands(error, preserveContext = false) {
+        for (const [messageId, pending] of this.pendingCommands) {
+            if (preserveContext && pending.commandType === "context.update")
+                continue;
+            globalThis.clearTimeout(pending.timeout);
+            globalThis.clearInterval(pending.retry);
+            pending.reject(error);
+            this.pendingCommands.delete(messageId);
+        }
+    }
+    async fetchReplay(apiBase, afterSeq) {
+        let nextAfter = afterSeq;
+        while (true) {
+            let response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, { headers: { Authorization: `Bearer ${this.accessToken}` } });
+            if (response.status === 401 && this.refreshCredentialsCallback) {
+                await this.refreshCredentials();
+                response = await this.fetcher(`${apiBase}/sessions/${this.id}/events?after_seq=${nextAfter}&limit=200`, { headers: { Authorization: `Bearer ${this.accessToken}` } });
+            }
+            if (!response.ok)
+                throw await httpError(response, "Could not replay session events");
+            const page = (await response.json());
+            for (const stored of page.items) {
+                nextAfter = Math.max(nextAfter, stored.server_seq);
+                const event = {
+                    protocol_version: 1,
+                    event_id: stored.event_id,
+                    stream_id: "durable-replay",
+                    stream_seq: Math.max(this.cursor.lastStreamSeq, 1),
+                    server_seq: stored.server_seq,
+                    ts: stored.created_at,
+                    type: stored.type,
+                    payload: stored.payload,
+                };
+                if (!this.cursor.acceptReplay(event))
+                    continue;
+                this.observeReadiness(event);
+                this.observeConvenienceEvents(event);
+                this.notifyListeners(this.listeners, event);
+            }
+            nextAfter = Math.max(nextAfter, page.next_after_seq);
+            if (!page.has_more)
+                return;
+        }
+    }
+}
+async function sha256Hex(data) {
+    if (!globalThis.crypto?.subtle)
+        throw new Error("Web Crypto SHA-256 is unavailable");
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", Uint8Array.from(data).buffer);
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+function contextStreamId() {
+    if (globalThis.crypto?.randomUUID)
+        return globalThis.crypto.randomUUID();
+    return `ctx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+function validateSessionCredentials(value) {
+    if (!value || typeof value !== "object") {
+        throw new TypeError("Session credentials must be an object");
+    }
+    if (!value.id || !value.access_token || !value.access_token_expires_at) {
+        throw new TypeError("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");
+    }
+}
+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");
+    }
+    return normalized;
+}
+function transcriptEvent(event) {
+    const match = /^transcript\.(user|agent)\.(interim|final)$/.exec(event.type);
+    if (!match)
+        return null;
+    const text = event.payload.text;
+    if (typeof text !== "string")
+        return null;
+    return {
+        role: match[1],
+        text,
+        final: match[2] === "final",
+        event,
+    };
+}
+async function httpError(response, fallback) {
+    let payload = {};
+    try {
+        payload = await response.json();
+    }
+    catch {
+        // The HTTP status and fallback message remain actionable without a JSON body.
+    }
+    return new RealtimeSessionHttpError(typeof payload.message === "string" ? payload.message : `${fallback} (${response.status})`, {
+        status: response.status,
+        code: typeof payload.error === "string" ? payload.error : null,
+        requestId: typeof payload.request_id === "string" ? payload.request_id : null,
+        details: Array.isArray(payload.details) ? payload.details : [],
+    });
+}
+//# sourceMappingURL=index.js.map