@kuralle-syrinx/server-websocket 4.4.1 → 4.5.0

package/dist/index.js

@@ -0,0 +1,718 @@
+// SPDX-License-Identifier: MIT
+import { createServer } from "node:http";
+import { WebSocket } from "ws";
+import { Route, SYRINX_AUDIO_ENVELOPE_NAME, encodeSyrinxAudioEnvelope, } from "@kuralle-syrinx/core";
+import { pcm16BytesToSamples, resamplePcm16Streaming, } from "@kuralle-syrinx/core/audio";
+import { BROWSER_OPUS_FRAME_DURATION_MS, BROWSER_OPUS_SAMPLE_RATE_HZ, createBrowserOpusCodec, decodeBrowserOpusToPcm16Bytes, } from "./browser-opus.js";
+import { closeWebSocketWithFallback, waitForWebSocketClose } from "./websocket-close.js";
+import { isRecord, parseJsonRecord, optionalString, requiredString } from "./json-message.js";
+import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
+import { runWebSocketConnection, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
+import { BackgroundAudioMixer } from "./background-audio.js";
+import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { TurnMetricsTracker } from "./turn-metrics.js";
+import { InMemorySessionStore, } from "./session-store.js";
+import { decodeStrictBase64, nonNegativeInteger, positiveInteger, rawDataToText, } from "./transport-helpers.js";
+import { decodeInboundBinaryAudio, rememberContextSampleRate, resampleAudioBytes, } from "./inbound-audio.js";
+export * from "./twilio.js";
+export * from "./telnyx.js";
+export * from "./smartpbx.js";
+export * from "./session-store.js";
+export { validateTwilioSignature } from "./twilio-auth.js";
+export { buildTwilioSendDigits, buildTelnyxSendDtmf, buildTwilioTransfer, buildTelnyxTransfer, dispatchTwilioCommand, dispatchTelnyxCommand, resolveTransferSummary, } from "./carrier-commands.js";
+export { wireCarrierControl } from "./wire-carrier-control.js";
+export { BackgroundAudioMixer, wireBackgroundThinking, wireBackgroundBackchannel, wireBackgroundAudio, } from "./background-audio.js";
+export { buildPlaceholderBackchannelCues } from "./backchannel-cue-fixtures.js";
+export { installGracefulShutdown } from "./websocket-lifecycle.js";
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+const DEFAULT_MAX_SESSION_DURATION_MS = 30 * 60_000;
+const DEFAULT_MAX_BUFFERED_AMOUNT_BYTES = 8 * 1024 * 1024;
+const DEFAULT_MAX_INBOUND_MESSAGE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_RESUME_WINDOW_MS = 15_000;
+const DEFAULT_OUTBOUND_FRAME_DURATION_MS = 20;
+// Bounds queue memory + sanity only — interrupt/clear keeps barge-in instant
+// regardless of queue depth, and TTS providers burst whole replies ahead of
+// realtime. A tiny cap silently drops the tail of every long reply.
+const DEFAULT_MAX_QUEUED_OUTPUT_AUDIO_MS = 60_000;
+export async function createVoiceWebSocketServer(options) {
+    const ownsHttpServer = !options.server;
+    const httpServer = options.server ?? createServer();
+    const routedWebSocket = createRoutedWebSocketServer(httpServer, options.path ?? "/ws", {
+        maxConcurrentSessions: positiveInteger(options.maxConcurrentSessions) ?? undefined,
+        maxConcurrentSessionsScope: options.maxConcurrentSessionsScope,
+        onAdmissionRejected: () => options.onTransportMetric?.(TRANSPORT_ADMISSION_REJECTED_METRIC),
+        authorize: options.authorize,
+    });
+    const wsServer = routedWebSocket.wsServer;
+    const sessionStore = options.sessionStore ?? new InMemorySessionStore();
+    const contextIdFn = options.contextId ?? defaultContextId;
+    const inputSampleRateHz = positiveInteger(options.inputSampleRateHz) ?? 16000;
+    const outputSampleRateHz = positiveInteger(options.outputSampleRateHz) ?? 16000;
+    const rawBinaryInput = options.rawBinaryInput ?? false;
+    const binaryAudioEnvelope = options.binaryAudioEnvelope ?? true;
+    const browserOpusDownlink = options.browserOpusDownlink ?? true;
+    const resumeWindowMs = nonNegativeInteger(options.resumeWindowMs) ?? DEFAULT_RESUME_WINDOW_MS;
+    const outboundFrameDurationMs = positiveInteger(options.outboundFrameDurationMs) ?? DEFAULT_OUTBOUND_FRAME_DURATION_MS;
+    const maxQueuedOutputAudioMs = positiveInteger(options.maxQueuedOutputAudioMs) ?? DEFAULT_MAX_QUEUED_OUTPUT_AUDIO_MS;
+    const hostConfig = {
+        heartbeatIntervalMs: nonNegativeInteger(options.heartbeatIntervalMs) ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+        startupTimeoutMs: nonNegativeInteger(options.startupTimeoutMs) ?? DEFAULT_STARTUP_TIMEOUT_MS,
+        maxSessionDurationMs: nonNegativeInteger(options.maxSessionDurationMs) ?? DEFAULT_MAX_SESSION_DURATION_MS,
+        maxBufferedAmountBytes: positiveInteger(options.maxBufferedAmountBytes) ?? DEFAULT_MAX_BUFFERED_AMOUNT_BYTES,
+        maxInboundMessageBytes: positiveInteger(options.maxInboundMessageBytes) ?? DEFAULT_MAX_INBOUND_MESSAGE_BYTES,
+    };
+    const gracefulCloseRegistry = new Map();
+    const adapter = {
+        createState: () => ({
+            managed: null,
+            initialContextId: contextIdFn(),
+            outboundHandle: null,
+            opusCodec: null,
+            browserOpusDownlink: browserOpusDownlink,
+            streamingResamplers: new Map(),
+        }),
+        async acquireSession({ request, state, shouldAbort, onSessionCreated }) {
+            // An explicit resolver is authoritative. Hosts such as cf-agents resolve the
+            // id before creating the session so the reasoner, session store, and transport
+            // all use the same identity even when the request carries a different wire id.
+            const requestedSessionId = sanitizeSessionId(options.sessionId?.(request) ?? sessionIdFromRequest(request) ?? defaultSessionId());
+            const leased = await sessionStore.lease(requestedSessionId, async () => {
+                const sess = await options.createSession(request);
+                onSessionCreated(sess);
+                if (shouldAbort()) {
+                    await sess.close().catch(() => undefined);
+                    throw new Error("websocket session startup aborted");
+                }
+                await sess.start();
+                if (shouldAbort()) {
+                    await sess.close().catch(() => undefined);
+                    throw new Error("websocket session startup aborted");
+                }
+                return {
+                    id: requestedSessionId,
+                    session: sess,
+                    currentContextId: state.initialContextId,
+                    contextSampleRates: new Map(),
+                    inputSequence: { lastSequence: null },
+                    turnMetricsTurns: new Map(),
+                    closeTimer: null,
+                    connectionCount: 1,
+                };
+            });
+            state.managed = leased.managed;
+            return { session: leased.managed.session, resumed: leased.resumed };
+        },
+        wireSession(session, socket, state, disposers) {
+            const managed = state.managed;
+            if (!managed)
+                throw new Error("websocket session missing managed state");
+            state.opusCodec = createBrowserOpusCodec(BROWSER_OPUS_SAMPLE_RATE_HZ);
+            state.outboundHandle = wireBrowserSessionEvents(session, socket, disposers, outputSampleRateHz, binaryAudioEnvelope, hostConfig.maxBufferedAmountBytes, outboundFrameDurationMs, maxQueuedOutputAudioMs, state.opusCodec, inputSampleRateHz, () => state.browserOpusDownlink, managed.turnMetricsTurns, state.streamingResamplers, options.backgroundAudio ? new BackgroundAudioMixer(options.backgroundAudio) : undefined);
+            gracefulCloseRegistry.set(socket, (deadlineMs) => {
+                if (socket.readyState === WebSocket.CLOSED || socket.readyState === WebSocket.CLOSING) {
+                    return Promise.resolve();
+                }
+                if (state.outboundHandle) {
+                    return state.outboundHandle.drainAndClose(socket, deadlineMs);
+                }
+                return new Promise((resolve) => {
+                    let settled = false;
+                    const settle = () => { if (!settled) {
+                        settled = true;
+                        resolve();
+                    } };
+                    const deadlineTimer = setTimeout(() => {
+                        if (socket.readyState !== WebSocket.CLOSED && socket.readyState !== WebSocket.CLOSING) {
+                            socket.terminate();
+                        }
+                        settle();
+                    }, Math.max(0, deadlineMs - Date.now()));
+                    deadlineTimer.unref?.();
+                    socket.once("close", () => { clearTimeout(deadlineTimer); settle(); });
+                    closeWebSocketWithFallback(socket, 1001, "server going away");
+                });
+            });
+            disposers.push(() => gracefulCloseRegistry.delete(socket));
+            return () => undefined;
+        },
+        processMessage(data, isBinary, session, state) {
+            if (!state.managed)
+                return;
+            const managed = state.managed;
+            sessionStore.update(managed.id, (stored) => {
+                stored.currentContextId = handleClientMessage(session, data, isBinary, stored.currentContextId, contextIdFn, inputSampleRateHz, rawBinaryInput, stored.contextSampleRates, stored.inputSequence, state.opusCodec, inputSampleRateHz, state, state.streamingResamplers);
+            });
+        },
+        onDisconnect(_session, state, { maxSessionTimedOut }) {
+            if (state.managed) {
+                state.managed.connectionCount = Math.max(0, state.managed.connectionCount - 1);
+                void sessionStore.release(state.managed.id, maxSessionTimedOut ? 0 : resumeWindowMs);
+            }
+        },
+        onStartupTimeout(_state, session) {
+            void session.close().catch(() => undefined);
+        },
+        sendReady(session, socket, state, resumed, config) {
+            const managed = state.managed;
+            if (!managed)
+                return;
+            sendJson(socket, {
+                type: "ready",
+                sessionId: managed.id,
+                turnId: managed.currentContextId,
+                resumed,
+                resumeWindowMs,
+                maxSessionDurationMs: config.maxSessionDurationMs,
+                audio: {
+                    inputSampleRateHz,
+                    outputSampleRateHz,
+                    encoding: "opus",
+                    supportedInputCodecs: ["pcm_s16le", "opus"],
+                    channels: 1,
+                    targetFrameDurationMs: outboundFrameDurationMs,
+                    binaryEnvelope: binaryAudioEnvelope ? SYRINX_AUDIO_ENVELOPE_NAME : undefined,
+                    rawBinaryInput,
+                    maxInboundMessageBytes: config.maxInboundMessageBytes,
+                },
+            }, config.maxBufferedAmountBytes);
+        },
+        sendError(socket, _state, message) {
+            sendJson(socket, {
+                type: "error",
+                component: "transport",
+                category: "invalid_input",
+                message,
+            }, hostConfig.maxBufferedAmountBytes);
+        },
+        sendStartupError(socket, _state, err, isTimeout) {
+            sendJson(socket, {
+                type: "error",
+                component: "session",
+                category: isTimeout ? "startup_timeout" : "initialization",
+                message: err instanceof Error ? err.message : String(err),
+            }, hostConfig.maxBufferedAmountBytes);
+        },
+        onMaxSessionTimeout(socket, _state) {
+            sendJson(socket, {
+                type: "error",
+                component: "transport",
+                category: "session_timeout",
+                message: "Websocket max session duration exceeded",
+            }, hostConfig.maxBufferedAmountBytes);
+        },
+    };
+    wsServer.on("connection", (socket, request) => {
+        void runWebSocketConnection(socket, request, hostConfig, adapter);
+    });
+    if (ownsHttpServer || typeof options.port === "number") {
+        await new Promise((resolveListen, reject) => {
+            httpServer.once("error", reject);
+            httpServer.listen(options.port ?? 0, options.host, () => {
+                httpServer.off("error", reject);
+                resolveListen();
+            });
+        });
+    }
+    let closing = false;
+    return {
+        httpServer,
+        wsServer,
+        address: () => httpServer.address(),
+        close: async (opts) => {
+            if (closing)
+                return;
+            closing = true;
+            if (opts?.graceful === true && gracefulCloseRegistry.size > 0) {
+                const deadline = Date.now() + (opts.drainDeadlineMs ?? 10_000);
+                await Promise.allSettled([...gracefulCloseRegistry.values()].map((fn) => fn(deadline)));
+                await Promise.allSettled([...wsServer.clients].map((client) => waitForWebSocketClose(client, 250)));
+            }
+            else {
+                for (const client of wsServer.clients)
+                    client.terminate();
+            }
+            gracefulCloseRegistry.clear();
+            for (const managed of await sessionStore.listAll()) {
+                if (managed.closeTimer)
+                    clearTimeout(managed.closeTimer);
+                await managed.session.close().catch(() => undefined);
+            }
+            await sessionStore.clear();
+            // Force-terminate any remaining sockets before wsServer.close() so the
+            // close event fires promptly even if a graceful handshake stalled.
+            for (const client of wsServer.clients)
+                client.terminate();
+            // Yield one macrotask tick so pending net.Socket close events (from terminate()
+            // or WS close handshake) are processed before wsServer.close() checks clients.
+            await new Promise((res) => setTimeout(res, 0));
+            await new Promise((resolveClose) => { wsServer.close(() => resolveClose()); });
+            routedWebSocket.detach();
+            if (ownsHttpServer || typeof options.port === "number") {
+                await new Promise((resolveClose) => { httpServer.close(() => resolveClose()); });
+            }
+        },
+    };
+}
+function wireBrowserSessionEvents(session, socket, disposers, outputSampleRateHz, binaryAudioEnvelope, maxBufferedAmountBytes, outboundFrameDurationMs, maxQueuedOutputAudioMs, opusCodec, engineInputSampleRateHz, getBrowserOpusDownlink, turnMetricsTurns, streamingResamplers, backgroundAudio) {
+    const ttsSequences = new Map();
+    const speechEndedSent = new Set();
+    let currentContextId = "";
+    const onSession = (event, handler) => {
+        session.on(event, handler);
+        disposers.push(() => session.off(event, handler));
+    };
+    onSession("user_started_speaking", (event) => {
+        sendJson(socket, { type: "speech_started", turnId: event.turnId }, maxBufferedAmountBytes);
+    });
+    onSession("user_stopped_speaking", (event) => {
+        speechEndedSent.add(event.turnId);
+        sendJson(socket, { type: "speech_ended", turnId: event.turnId }, maxBufferedAmountBytes);
+    });
+    onSession("user_input_partial", (event) => {
+        sendJson(socket, { type: "stt_chunk", turnId: event.turnId, transcript: event.text }, maxBufferedAmountBytes);
+    });
+    onSession("user_input_final", (event) => {
+        if (!speechEndedSent.has(event.turnId)) {
+            speechEndedSent.add(event.turnId);
+            sendJson(socket, { type: "speech_ended", turnId: event.turnId }, maxBufferedAmountBytes);
+        }
+        sendJson(socket, { type: "stt_output", turnId: event.turnId, transcript: event.text, confidence: event.confidence }, maxBufferedAmountBytes);
+    });
+    disposers.push(session.bus.on("eos.turn_complete", (pkt) => {
+        const turn = pkt;
+        sendJson(socket, { type: "turn_complete", turnId: turn.contextId, transcript: turn.text ?? "" }, maxBufferedAmountBytes);
+    }));
+    onSession("agent_text_delta", (event) => {
+        sendJson(socket, { type: "agent_chunk", turnId: event.turnId, text: event.delta }, maxBufferedAmountBytes);
+    });
+    onSession("agent_tool_call", (event) => {
+        sendJson(socket, { type: "agent_tool_call", turnId: event.turnId, id: event.id, name: event.name, args: event.args }, maxBufferedAmountBytes);
+    });
+    onSession("agent_tool_result", (event) => {
+        sendJson(socket, { type: "agent_tool_result", turnId: event.turnId, id: event.id, result: event.result }, maxBufferedAmountBytes);
+    });
+    // G3: typed preamble/filler lifecycle — same wire shape as the edge transport.
+    onSession("tool_call_cue", (event) => {
+        sendJson(socket, {
+            type: `tool_call_${event.phase}`,
+            turnId: event.turnId,
+            toolId: event.toolId,
+            toolName: event.toolName,
+            ...(event.afterMs !== undefined ? { afterMs: event.afterMs } : {}),
+        }, maxBufferedAmountBytes);
+    });
+    onSession("agent_finished", (event) => {
+        sendJson(socket, { type: "agent_end", turnId: event.turnId }, maxBufferedAmountBytes);
+    });
+    onSession("error", (event) => {
+        sendJson(socket, {
+            type: "error",
+            component: event.stage,
+            category: event.category,
+            message: event.message,
+        }, maxBufferedAmountBytes);
+    });
+    const callbacks = {
+        carrierLabel: "browser",
+        getContextId: () => currentContextId,
+        isActive: () => true, // Always active for metrics and processing, socket state is checked in encodeFrames
+        encodeFrames: (audio, sourceSampleRateHz, contextId) => {
+            const resampled = resampleAudioBytes(audio, sourceSampleRateHz, outputSampleRateHz, streamingResamplers);
+            const frames = [];
+            const frameSampleCount = Math.max(1, Math.round((outputSampleRateHz * outboundFrameDurationMs) / 1000));
+            const frameBytesCount = frameSampleCount * 2;
+            const pushWireFrame = (wireAudio, wireEncoding, durationMs, 
+            // The sample rate of THIS frame's payload. Opus frames are encoded at the
+            // codec rate (48 kHz), not outputSampleRateHz — mislabeling them 16 kHz made
+            // the client skip its 48→16 kHz downsample and play assistant audio ~3× slow.
+            wireSampleRateHz) => {
+                const sequence = (ttsSequences.get(contextId) ?? 0) + 1;
+                ttsSequences.set(contextId, sequence);
+                frames.push({
+                    contextId,
+                    send: () => {
+                        if (socket.readyState !== WebSocket.OPEN)
+                            return false;
+                        const jsonSuccess = sendJsonWithResult(socket, {
+                            type: "tts_chunk",
+                            turnId: contextId,
+                            sequence,
+                            sampleRateHz: wireSampleRateHz,
+                            encoding: wireEncoding,
+                            channels: 1,
+                            byteLength: wireAudio.byteLength,
+                            durationMs,
+                        }, maxBufferedAmountBytes);
+                        if (!jsonSuccess)
+                            return false;
+                        const binaryData = binaryAudioEnvelope
+                            ? Buffer.from(encodeSyrinxAudioEnvelope({
+                                type: "audio",
+                                contextId,
+                                sequence,
+                                sampleRateHz: wireSampleRateHz,
+                                encoding: wireEncoding,
+                                channels: 1,
+                                byteLength: wireAudio.byteLength,
+                                durationMs,
+                            }, wireAudio))
+                            : Buffer.from(wireAudio);
+                        return sendSocketDataWithResult(socket, binaryData, maxBufferedAmountBytes);
+                    },
+                });
+            };
+            if (binaryAudioEnvelope && opusCodec && getBrowserOpusDownlink()) {
+                for (let offset = 0; offset < resampled.byteLength; offset += frameBytesCount) {
+                    const framePcm = resampled.subarray(offset, Math.min(resampled.byteLength, offset + frameBytesCount));
+                    let samples = pcm16BytesToSamples(framePcm);
+                    if (outputSampleRateHz !== opusCodec.sampleRateHz) {
+                        samples = resamplePcm16Streaming(streamingResamplers, samples, outputSampleRateHz, opusCodec.sampleRateHz);
+                    }
+                    for (const opus of opusCodec.encodePcm16Frame(samples, false)) {
+                        pushWireFrame(opus, "opus", BROWSER_OPUS_FRAME_DURATION_MS, opusCodec.sampleRateHz);
+                    }
+                }
+                return frames;
+            }
+            for (let offset = 0; offset < resampled.byteLength; offset += frameBytesCount) {
+                const frameAudio = resampled.subarray(offset, Math.min(resampled.byteLength, offset + frameBytesCount));
+                pushWireFrame(frameAudio, "pcm_s16le", pcm16DurationMs(frameAudio, outputSampleRateHz), outputSampleRateHz);
+            }
+            return frames;
+        },
+        onInterrupt: (contextId) => {
+            ttsSequences.delete(contextId);
+            opusCodec?.reset();
+            sendJson(socket, { type: "audio_clear", turnId: contextId, reason: "barge_in" }, maxBufferedAmountBytes);
+            sendJson(socket, { type: "agent_interrupted", turnId: contextId, reason: "barge_in" }, maxBufferedAmountBytes);
+        },
+        onDrain: (contextId, playout, progress) => {
+            if (binaryAudioEnvelope && opusCodec && getBrowserOpusDownlink()) {
+                const pendingFrames = opusCodec.encodePcm16Frame(new Int16Array(0), true).map((opus) => ({
+                    contextId,
+                    send: () => {
+                        if (socket.readyState !== WebSocket.OPEN)
+                            return false;
+                        const sequence = (ttsSequences.get(contextId) ?? 0) + 1;
+                        ttsSequences.set(contextId, sequence);
+                        const jsonSuccess = sendJsonWithResult(socket, {
+                            type: "tts_chunk",
+                            turnId: contextId,
+                            sequence,
+                            sampleRateHz: opusCodec.sampleRateHz,
+                            encoding: "opus",
+                            channels: 1,
+                            byteLength: opus.byteLength,
+                            durationMs: BROWSER_OPUS_FRAME_DURATION_MS,
+                        }, maxBufferedAmountBytes);
+                        if (!jsonSuccess)
+                            return false;
+                        const binaryData = Buffer.from(encodeSyrinxAudioEnvelope({
+                            type: "audio",
+                            contextId,
+                            sequence,
+                            sampleRateHz: opusCodec.sampleRateHz,
+                            encoding: "opus",
+                            channels: 1,
+                            byteLength: opus.byteLength,
+                            durationMs: BROWSER_OPUS_FRAME_DURATION_MS,
+                        }, opus));
+                        return sendSocketDataWithResult(socket, binaryData, maxBufferedAmountBytes);
+                    },
+                }));
+                playout.enqueue(pendingFrames);
+            }
+            playout.enqueueControl(() => {
+                ttsSequences.delete(contextId);
+                progress.complete(contextId);
+                sendJson(socket, { type: "tts_end", ...(contextId ? { turnId: contextId } : {}) }, maxBufferedAmountBytes);
+            });
+        },
+        onStop: (reason) => {
+            session.bus.push(Route.Background, {
+                kind: "metric.conversation",
+                contextId: currentContextId,
+                timestampMs: Date.now(),
+                name: `browser.${reason}_playout_stopped`,
+                value: "1",
+            });
+        },
+        onClear: () => {
+            ttsSequences.clear();
+            opusCodec?.reset();
+        },
+    };
+    disposers.push(session.bus.on("turn.change", (pkt) => {
+        currentContextId = pkt.contextId;
+    }));
+    const turnMetrics = new TurnMetricsTracker(session.bus, (message) => {
+        sendJson(socket, message, maxBufferedAmountBytes);
+    }, turnMetricsTurns);
+    turnMetrics.wire(disposers);
+    return wireTelephonyOutboundPipeline({
+        session,
+        socket,
+        disposers,
+        outboundFrameDurationMs,
+        maxQueuedOutputAudioMs,
+        callbacks,
+        ...(backgroundAudio ? { backgroundAudio } : {}),
+    });
+}
+function handleClientMessage(session, data, isBinary, currentContextId, contextId, inputSampleRateHz, rawBinaryInput, contextSampleRates, inputSequence, opusCodec, engineInputSampleRateHz, state, streamingResamplers) {
+    if (isBinary) {
+        const binaryAudio = decodeInboundBinaryAudio(rawDataToBytes(data), inputSampleRateHz, rawBinaryInput, engineInputSampleRateHz, streamingResamplers, createOpusIngressDecoder(opusCodec));
+        const nextContextId = binaryAudio.contextId ?? currentContextId;
+        if (nextContextId !== currentContextId) {
+            pushTurnChange(session, nextContextId, currentContextId, "websocket_binary_audio_turn");
+        }
+        rememberContextSampleRate(contextSampleRates, nextContextId, binaryAudio.sampleRateHz);
+        rememberInputSequence(session, inputSequence, nextContextId, binaryAudio.sequence);
+        const audio = resampleAudioBytes(binaryAudio.audio, binaryAudio.sampleRateHz, inputSampleRateHz, streamingResamplers);
+        session.bus.push(Route.Main, {
+            kind: "user.audio_received",
+            contextId: nextContextId,
+            timestampMs: Date.now(),
+            audio,
+            sampleRateHz: inputSampleRateHz,
+        });
+        return nextContextId;
+    }
+    const message = parseClientMessage(parseJsonRecord(rawDataToText(data), "Websocket JSON message"));
+    if (message.type === "ping")
+        return currentContextId;
+    if (message.type === "codec_capability") {
+        state.browserOpusDownlink = message.downlinkEncoding === "opus";
+        return currentContextId;
+    }
+    if (message.type === "client_interrupt") {
+        const interruptedContextId = message.assistantContextId ?? message.contextId ?? currentContextId;
+        if (interruptedContextId) {
+            session.requestClientInterrupt(interruptedContextId);
+        }
+        return currentContextId;
+    }
+    if (message.type === "playout_progress") {
+        // The browser reports how much assistant audio it has actually played out. This
+        // is a more accurate "heard" clock than the server pacer (which leads the ear by
+        // the client jitter buffer), so barge-in truncates history to what was heard (B2).
+        const progressContextId = message.contextId ?? currentContextId;
+        if (progressContextId) {
+            session.bus.push(Route.Main, {
+                kind: "tts.playout_progress",
+                contextId: progressContextId,
+                timestampMs: Date.now(),
+                playedOutMs: message.playedOutMs,
+                complete: message.complete ?? false,
+            });
+        }
+        return currentContextId;
+    }
+    if (message.type === "text") {
+        const nextContextId = message.contextId ?? contextId();
+        if (nextContextId !== currentContextId) {
+            pushTurnChange(session, nextContextId, currentContextId, "websocket_text_turn");
+        }
+        session.bus.push(Route.Main, {
+            kind: "user.text_received",
+            contextId: nextContextId,
+            timestampMs: Date.now(),
+            text: message.text,
+        });
+        return nextContextId;
+    }
+    if (message.type === "audio") {
+        const nextContextId = message.contextId ?? currentContextId;
+        if (nextContextId !== currentContextId) {
+            pushTurnChange(session, nextContextId, currentContextId, "websocket_audio_turn");
+        }
+        const sourceSampleRateHz = requiredJsonAudioSampleRate(message.sampleRateHz);
+        rememberContextSampleRate(contextSampleRates, nextContextId, sourceSampleRateHz);
+        rememberInputSequence(session, inputSequence, nextContextId, optionalSequence(message.sequence));
+        session.bus.push(Route.Main, {
+            kind: "user.audio_received",
+            contextId: nextContextId,
+            timestampMs: Date.now(),
+            audio: resampleAudioBytes(decodeStrictBase64(message.audio, "audio"), sourceSampleRateHz, inputSampleRateHz, streamingResamplers),
+            sampleRateHz: inputSampleRateHz,
+        });
+        return nextContextId;
+    }
+    throw new Error("Unsupported client message type");
+}
+function parseClientMessage(value) {
+    if (!isRecord(value))
+        throw new Error("Websocket JSON message must be an object");
+    const type = value.type;
+    if (type === "ping")
+        return { type };
+    if (type === "text") {
+        return {
+            type,
+            text: requiredString(value.text, "Websocket JSON text"),
+            contextId: optionalContextId(value.contextId),
+        };
+    }
+    if (type === "client_interrupt") {
+        return {
+            type,
+            assistantContextId: optionalContextId(value.assistantContextId),
+            contextId: optionalContextId(value.contextId),
+            reason: optionalString(value.reason, "client_interrupt.reason"),
+        };
+    }
+    if (type === "audio") {
+        return {
+            type,
+            audio: requiredString(value.audio, "Websocket JSON audio"),
+            contextId: optionalContextId(value.contextId),
+            sampleRateHz: requiredJsonAudioSampleRate(value.sampleRateHz),
+            sequence: optionalSequence(value.sequence),
+        };
+    }
+    if (type === "codec_capability") {
+        const downlinkEncoding = value.downlinkEncoding;
+        if (downlinkEncoding !== "pcm_s16le" && downlinkEncoding !== "opus") {
+            throw new Error("codec_capability.downlinkEncoding must be pcm_s16le or opus");
+        }
+        return { type, downlinkEncoding };
+    }
+    if (type === "playout_progress") {
+        const playedOutMs = value.playedOutMs;
+        if (typeof playedOutMs !== "number" || !Number.isFinite(playedOutMs) || playedOutMs < 0) {
+            throw new Error("playout_progress.playedOutMs must be a non-negative number");
+        }
+        return {
+            type,
+            contextId: optionalContextId(value.contextId),
+            playedOutMs,
+            complete: value.complete === true ? true : undefined,
+        };
+    }
+    throw new Error("Unsupported client message type");
+}
+function optionalContextId(value) {
+    return optionalString(value, "Websocket JSON contextId");
+}
+function rememberInputSequence(session, state, contextId, sequence) {
+    if (sequence === undefined)
+        return;
+    const previous = state.lastSequence;
+    if (previous !== null && sequence <= previous) {
+        throw new Error(`Websocket audio sequence must increase monotonically: ${String(previous)} -> ${String(sequence)}`);
+    }
+    if (previous !== null && sequence > previous + 1) {
+        session.bus.push(Route.Background, {
+            kind: "metric.conversation",
+            contextId,
+            timestampMs: Date.now(),
+            name: "websocket.audio_sequence_gap",
+            value: JSON.stringify({ expected: previous + 1, actual: sequence, missed: sequence - previous - 1 }),
+        });
+    }
+    state.lastSequence = sequence;
+}
+function pushTurnChange(session, contextId, previousContextId, reason) {
+    session.bus.push(Route.Main, {
+        kind: "turn.change",
+        contextId,
+        previousContextId,
+        reason,
+        timestampMs: Date.now(),
+    });
+}
+function rawDataToBytes(data) {
+    if (Buffer.isBuffer(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (Array.isArray(data))
+        return Uint8Array.from(Buffer.concat(data));
+    throw new Error("Unsupported binary message payload");
+}
+function createOpusIngressDecoder(opusCodec) {
+    if (!opusCodec)
+        return null;
+    return (wire, sampleRateHz) => {
+        if (opusCodec.sampleRateHz !== sampleRateHz) {
+            throw new Error(`Browser websocket opus sample rate mismatch: ${sampleRateHz} != ${opusCodec.sampleRateHz}`);
+        }
+        return decodeBrowserOpusToPcm16Bytes(wire, opusCodec);
+    };
+}
+function pcm16DurationMs(audio, sampleRateHz) {
+    if (sampleRateHz <= 0)
+        return 0;
+    return Math.round((audio.byteLength / 2 / sampleRateHz) * 1000);
+}
+function requireTtsAudioSampleRate(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error("tts.audio sampleRateHz must be a positive integer");
+    }
+    return value;
+}
+function optionalSequence(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error("Websocket audio sequence must be a non-negative integer");
+    }
+    return value;
+}
+function requiredJsonAudioSampleRate(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error("JSON websocket audio sampleRateHz must be a positive integer");
+    }
+    return value;
+}
+function sessionIdFromRequest(request) {
+    const url = request.url;
+    if (!url)
+        return null;
+    try {
+        const parsed = new URL(url, "http://localhost");
+        return parsed.searchParams.get("sessionId") ?? parsed.searchParams.get("session_id");
+    }
+    catch {
+        return null;
+    }
+}
+function sanitizeSessionId(value) {
+    const trimmed = value.trim();
+    if (/^[A-Za-z0-9_.:-]{1,128}$/.test(trimmed))
+        return trimmed;
+    return defaultSessionId();
+}
+function sendJson(socket, value, maxBufferedAmountBytes) {
+    sendSocketData(socket, JSON.stringify(value), maxBufferedAmountBytes);
+}
+function sendJsonWithResult(socket, value, maxBufferedAmountBytes) {
+    return sendSocketDataWithResult(socket, JSON.stringify(value), maxBufferedAmountBytes);
+}
+function sendSocketData(socket, data, maxBufferedAmountBytes) {
+    sendSocketDataWithResult(socket, data, maxBufferedAmountBytes);
+}
+function sendSocketDataWithResult(socket, data, maxBufferedAmountBytes) {
+    if (socket.readyState !== WebSocket.OPEN)
+        return false;
+    if (socket.bufferedAmount + outboundMessageByteLength(data) > maxBufferedAmountBytes) {
+        closeWebSocketWithFallback(socket, 1013, "websocket send buffer exceeded");
+        return false;
+    }
+    socket.send(data);
+    return true;
+}
+function outboundMessageByteLength(data) {
+    return typeof data === "string" ? Buffer.byteLength(data, "utf8") : data.byteLength;
+}
+function defaultContextId() {
+    // crypto-random, not Math.random: ids are guessable resource handles. V8's PRNG
+    // is state-recoverable from a few observed outputs, which would let a client
+    // predict other sessions' turn/session ids and attach to a live conversation.
+    return `turn-${globalThis.crypto.randomUUID()}`;
+}
+function defaultSessionId() {
+    return `session-${globalThis.crypto.randomUUID()}`;
+}
+//# sourceMappingURL=index.js.map