@kuralle-syrinx/browser-client 4.4.0 → 4.5.0

package/dist/index.js

@@ -0,0 +1,744 @@
+// SPDX-License-Identifier: MIT
+export { decodeBrowserAssistantAudio, encodeBrowserAudioEnvelopeFrame, encodeBrowserAudioFrame, float32ToPcm16, pcm16FrameSampleCount, resampleFloat32Linear, } from "./audio.js";
+import { createBrowserOpusCodec, encodeBrowserOpusEnvelope, encodeBrowserPcmEnvelope, loadBrowserOpusModule, pickBrowserWireCodec, } from "./browser-opus.js";
+import { BROWSER_OPUS_SAMPLE_RATE_HZ } from "./browser-opus.js";
+import { pcm16BytesToSamples, pcm16SamplesToBytes, resamplePcm16Streaming, } from "@kuralle-syrinx/core/audio";
+import { decodeBrowserAssistantAudio, encodeBrowserAudioEnvelopeFrame, float32ToPcm16, resampleFloat32Linear, AudioJitterBuffer, } from "./audio.js";
+import { WebSocketClientTransport } from "./websocket-transport.js";
+export { WebSocketClientTransport } from "./websocket-transport.js";
+export { BROWSER_OPUS_FRAME_DURATION_MS, BROWSER_OPUS_SAMPLE_RATE_HZ, BROWSER_SUPPORTED_INPUT_CODECS, createBrowserOpusCodec, encodeBrowserOpusEnvelope, encodeBrowserPcmEnvelope, loadBrowserOpusModule, pickBrowserWireCodec, } from "./browser-opus.js";
+const RECONNECT_MAX_ATTEMPTS = 10;
+const RECONNECT_BASE_DELAY_MS = 1_000;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+const RECONNECT_MIN_STABLE_MS = 5_000;
+const RECONNECT_MAX_QUICK_FAILURES = 3;
+const KEEPALIVE_INTERVAL_MS = 10_000;
+// Endpointing decision values carried on the `metrics` message. Forward-compatible:
+// an unknown value (a newer backend) is ignored rather than dropping the message.
+const ENDPOINTING_OWNERS = new Set(["provider_stt", "smart_turn", "timer", "text"]);
+const ENDPOINTING_REASONS = new Set(["end_of_speech", "force_finalized", "typed"]);
+export class SyrinxBrowserClient {
+    options;
+    transport;
+    handlers = new Set();
+    audioSequence = 0;
+    currentSessionId = null;
+    cleanClose = false;
+    reconnectAttempt = 0;
+    quickFailures = 0;
+    openedAt = 0;
+    reconnectTimer = null;
+    keepaliveTimer = null;
+    playoutProgressTimer = null;
+    lastProgressContextId = null;
+    jitterBuffer = null;
+    outputSampleRateHz = 16000;
+    wireCodec = "pcm_s16le";
+    inputSampleRateHz = 16000;
+    opusCodec = null;
+    opusLoadFailed = false;
+    codecNegotiation = null;
+    uplinkCodecDecided = false;
+    pendingUplink = [];
+    streamingResamplers = new Map();
+    bargeInNoiseFloorRms = 0.005;
+    bargeInSpeechMs = 0;
+    bargeInInterruptSent = false;
+    constructor(options) {
+        this.options = options;
+        this.transport = options.transport ?? new WebSocketClientTransport({ protocols: options.protocols });
+        this.transport.setHandlers({
+            onOpen: () => this.handleTransportOpen(),
+            onClose: (code, reason) => this.handleTransportClose(code, reason),
+            onError: (error) => this.emit({ type: "error", error }),
+            onMessage: (data) => this.handleTransportMessage(data),
+            onAudio: (data) => this.handleTransportAudio(data),
+        });
+        if (options.audioContext) {
+            this.jitterBuffer = new AudioJitterBuffer(options.audioContext, {
+                sampleRateHz: this.outputSampleRateHz,
+                ...options.jitterBuffer,
+            });
+        }
+    }
+    get connected() {
+        return this.transport.connected;
+    }
+    /** The sessionId received from the server's last `ready` message. Used to resume on reconnect. */
+    get sessionId() {
+        return this.currentSessionId;
+    }
+    on(handler) {
+        this.handlers.add(handler);
+        return () => {
+            this.handlers.delete(handler);
+        };
+    }
+    connect() {
+        if (this.transport.connected)
+            return;
+        this.cleanClose = false;
+        this.cancelReconnect();
+        void loadBrowserOpusModule().catch(() => undefined);
+        this.openTransport();
+    }
+    close(code, reason) {
+        this.cleanClose = true;
+        this.cancelReconnect();
+        this.stopKeepalive();
+        this.jitterBuffer?.clear();
+        this.transport.disconnect(code, reason);
+    }
+    sendAudioPcm(audio, sampleRateHz, options = {}) {
+        const bytes = ArrayBuffer.isView(audio)
+            ? new Uint8Array(audio.buffer, audio.byteOffset, audio.byteLength)
+            : new Uint8Array(audio);
+        if (bytes.byteLength % 2 !== 0)
+            throw new Error("PCM16 audio payload must contain an even number of bytes");
+        const sampleRate = readPositiveSampleRate(sampleRateHz);
+        if (options.sequence !== undefined) {
+            this.assertAudioSequenceCanAdvance(options.sequence);
+        }
+        this.observeUplinkForBargeIn(rmsFromPcm16Bytes(bytes), (bytes.byteLength / 2 / sampleRate) * 1000);
+        this.scheduleUplink(() => {
+            for (const frame of this.encodeUplinkPcm(bytes, sampleRate, options)) {
+                this.requireOpenTransport().sendAudio(frame);
+            }
+        });
+    }
+    sendAudioBase64(audio, sampleRateHz, options = {}) {
+        this.sendJson({
+            type: "audio",
+            audio,
+            sampleRateHz,
+            contextId: options.contextId,
+            sequence: this.nextAudioSequence(options.sequence),
+        });
+    }
+    sendFloat32Audio(input, options) {
+        if (options.sequence !== undefined) {
+            this.assertAudioSequenceCanAdvance(options.sequence);
+        }
+        this.observeUplinkForBargeIn(rmsFromFloat32(input), (input.length / options.fromSampleRateHz) * 1000);
+        if (this.wireCodec === "opus" && this.opusCodec) {
+            const targetRate = readPositiveSampleRate(options.toSampleRateHz);
+            const resampled = resampleFloat32Linear(input, options);
+            const pcm = float32ToPcm16(resampled);
+            const bytes = new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+            this.scheduleUplink(() => {
+                for (const frame of this.encodeUplinkPcm(bytes, targetRate, options)) {
+                    this.requireOpenTransport().sendAudio(frame);
+                }
+            });
+            return;
+        }
+        const sequence = this.nextAudioSequence(options.sequence);
+        this.scheduleUplink(() => {
+            this.requireOpenTransport().sendAudio(encodeBrowserAudioEnvelopeFrame(input, { ...options, sequence }));
+        });
+    }
+    sendText(text) {
+        this.sendJson({ type: "text", text });
+    }
+    // Local barge-in: pure-energy speech detection on the uplink, gated on the
+    // jitter buffer's playout clock (G12: never the generation clock). One
+    // client_interrupt per assistant playout; the noise floor adapts while the
+    // mic is below threshold so a hot mic doesn't pin the gate open.
+    observeUplinkForBargeIn(rms, durationMs) {
+        const config = this.options.bargeIn;
+        if (config === false)
+            return;
+        const minSpeechMs = config?.minSpeechMs ?? 280;
+        const thresholdFactor = config?.thresholdFactor ?? 3;
+        const minRms = config?.minRms ?? 0.015;
+        const playingOut = this.jitterBuffer?.isPlayingOut ?? false;
+        if (!playingOut) {
+            this.bargeInSpeechMs = 0;
+            this.bargeInInterruptSent = false;
+        }
+        const threshold = Math.max(minRms, this.bargeInNoiseFloorRms * thresholdFactor);
+        if (rms < threshold) {
+            this.bargeInNoiseFloorRms = this.bargeInNoiseFloorRms * 0.95 + rms * 0.05;
+            this.bargeInSpeechMs = 0;
+            return;
+        }
+        if (!playingOut || this.bargeInInterruptSent)
+            return;
+        this.bargeInSpeechMs += durationMs;
+        if (this.bargeInSpeechMs < minSpeechMs)
+            return;
+        this.bargeInInterruptSent = true;
+        const assistantContextId = this.jitterBuffer?.activeContextId ?? undefined;
+        this.sendJson({ type: "client_interrupt", ...(assistantContextId ? { assistantContextId } : {}) });
+    }
+    sendJson(value) {
+        this.transport.sendJson(value);
+    }
+    openTransport() {
+        this.uplinkCodecDecided = false;
+        const url = this.currentSessionId !== null
+            ? buildResumeUrl(this.options.url, this.currentSessionId)
+            : this.options.url;
+        this.transport.connect(url);
+    }
+    handleTransportOpen() {
+        this.openedAt = Date.now();
+        if (this.reconnectAttempt > 0) {
+            const attempt = this.reconnectAttempt;
+            this.reconnectAttempt = 0;
+            this.emit({ type: "reconnected", attempt });
+        }
+        else {
+            this.emit({ type: "open" });
+        }
+        this.startKeepalive();
+        this.startPlayoutProgressReporting();
+    }
+    handleTransportClose(code, reason) {
+        this.stopKeepalive();
+        this.stopPlayoutProgressReporting();
+        if (!this.cleanClose) {
+            this.jitterBuffer?.clear();
+        }
+        if (this.cleanClose) {
+            this.emit({ type: "close", code, reason });
+            return;
+        }
+        this.scheduleReconnect(code, reason);
+    }
+    handleTransportMessage(data) {
+        this.handleJsonMessage(data);
+    }
+    handleTransportAudio(data) {
+        this.handleBinaryMessage(data);
+    }
+    scheduleReconnect(code, reason) {
+        const opts = this.options.reconnect;
+        if (opts === false) {
+            this.emit({ type: "close", code, reason });
+            return;
+        }
+        const maxAttempts = opts?.maxAttempts ?? RECONNECT_MAX_ATTEMPTS;
+        const baseDelayMs = opts?.baseDelayMs ?? RECONNECT_BASE_DELAY_MS;
+        const maxDelayMs = opts?.maxDelayMs ?? RECONNECT_MAX_DELAY_MS;
+        const minStableMs = opts?.minStableMs ?? RECONNECT_MIN_STABLE_MS;
+        const maxQuickFailures = opts?.maxQuickFailures ?? RECONNECT_MAX_QUICK_FAILURES;
+        // Quick-failure guard: a socket that opens then dies within minStableMs,
+        // repeatedly, won't be fixed by backoff (a flapping/half-broken peer mid-deploy,
+        // a bad token accepted-then-rejected). Distinct from a never-opening peer, which
+        // the maxAttempts cap handles. A genuinely stable connection resets the count.
+        const opened = this.openedAt > 0;
+        const stable = opened && Date.now() - this.openedAt >= minStableMs;
+        this.openedAt = 0;
+        if (stable) {
+            this.quickFailures = 0;
+        }
+        else if (opened) {
+            this.quickFailures += 1;
+            if (this.quickFailures >= maxQuickFailures) {
+                this.quickFailures = 0;
+                this.emit({ type: "close", code, reason });
+                return;
+            }
+        }
+        this.reconnectAttempt += 1;
+        if (maxAttempts > 0 && this.reconnectAttempt > maxAttempts) {
+            this.emit({ type: "close", code, reason });
+            return;
+        }
+        const exponential = Math.min(baseDelayMs * Math.pow(2, this.reconnectAttempt - 1), maxDelayMs);
+        const jitter = exponential * 0.2 * Math.random();
+        const delayMs = Math.round(exponential + jitter);
+        this.emit({ type: "reconnecting", attempt: this.reconnectAttempt, delayMs });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.cleanClose)
+                return;
+            this.openTransport();
+        }, delayMs);
+    }
+    cancelReconnect() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.reconnectAttempt = 0;
+        this.quickFailures = 0;
+        this.openedAt = 0;
+    }
+    startKeepalive() {
+        this.stopKeepalive();
+        const intervalMs = this.options.keepaliveIntervalMs;
+        if (intervalMs === false)
+            return;
+        const ms = typeof intervalMs === "number" && intervalMs > 0 ? intervalMs : KEEPALIVE_INTERVAL_MS;
+        this.keepaliveTimer = setInterval(() => {
+            if (this.transport.connected) {
+                try {
+                    this.transport.sendJson({ type: "ping" });
+                }
+                catch (error) {
+                    this.stopKeepalive();
+                    this.emit({
+                        type: "error",
+                        error: error instanceof Error ? error : new Error(String(error)),
+                    });
+                }
+            }
+            else {
+                this.stopKeepalive();
+            }
+        }, ms);
+    }
+    stopKeepalive() {
+        if (this.keepaliveTimer !== null) {
+            clearInterval(this.keepaliveTimer);
+            this.keepaliveTimer = null;
+        }
+    }
+    // The browser is the playout clock on the WebSocket media path: report how many
+    // ms of the current assistant turn have actually reached the speaker, so the
+    // server can truncate conversation history to what the user HEARD on barge-in
+    // (B2) instead of falling back to a stale 0. ~200ms cadence matches the server
+    // emitter's throttle; a final complete:true is sent when a turn finishes playing.
+    startPlayoutProgressReporting() {
+        this.stopPlayoutProgressReporting();
+        if (!this.jitterBuffer)
+            return;
+        this.playoutProgressTimer = setInterval(() => {
+            const jitter = this.jitterBuffer;
+            if (!jitter || !this.transport.connected)
+                return;
+            const contextId = jitter.activeContextId ?? this.lastProgressContextId;
+            if (!contextId)
+                return;
+            const complete = jitter.isPlayoutComplete(contextId);
+            try {
+                this.sendJson({
+                    type: "playout_progress",
+                    contextId,
+                    playedOutMs: Math.round(jitter.playedOutMs(contextId)),
+                    complete,
+                });
+            }
+            catch {
+                this.stopPlayoutProgressReporting();
+                return;
+            }
+            this.lastProgressContextId = complete ? null : contextId;
+        }, 200);
+    }
+    stopPlayoutProgressReporting() {
+        if (this.playoutProgressTimer !== null) {
+            clearInterval(this.playoutProgressTimer);
+            this.playoutProgressTimer = null;
+        }
+        this.lastProgressContextId = null;
+    }
+    handleJsonMessage(data) {
+        if (typeof data !== "string")
+            return;
+        try {
+            const parsed = JSON.parse(data);
+            // Cloudflare Agents SDK control frames (cf_agent_state, cf_agent_mcp_servers, …) are
+            // broadcast by the Agent base class on the same socket a cf-agents `withVoice` worker
+            // uses for voice. They are not part of the Syrinx voice protocol — ignore them rather
+            // than throwing (which surfaced a spurious `error` event → a false "Error" badge).
+            if (isRecord(parsed) && typeof parsed["type"] === "string" && parsed["type"].startsWith("cf_agent")) {
+                return;
+            }
+            const message = parseStudioMessage(parsed);
+            if (message.type === "ready") {
+                if (message.sessionId !== undefined)
+                    this.currentSessionId = message.sessionId;
+                if (message.audio?.outputSampleRateHz && message.audio.outputSampleRateHz !== this.outputSampleRateHz) {
+                    this.outputSampleRateHz = message.audio.outputSampleRateHz;
+                    if (this.options.audioContext) {
+                        this.jitterBuffer = new AudioJitterBuffer(this.options.audioContext, {
+                            sampleRateHz: this.outputSampleRateHz,
+                            ...this.options.jitterBuffer,
+                        });
+                    }
+                }
+                if (message.audio?.supportedInputCodecs?.includes("opus") && !this.opusLoadFailed) {
+                    this.codecNegotiation = this.negotiateWireCodec(message.audio).finally(() => {
+                        this.codecNegotiation = null;
+                        this.flushPendingUplink();
+                    });
+                }
+                else {
+                    void this.negotiateWireCodec(message.audio).finally(() => {
+                        this.flushPendingUplink();
+                    });
+                }
+            }
+            if ((message.type === "audio_clear" || message.type === "agent_interrupted") && this.jitterBuffer) {
+                this.jitterBuffer.clear(message.turnId);
+            }
+            this.emit({ type: "message", message });
+            if (message.type === "ready" && message.resumed === true) {
+                this.emit({ type: "resumed" });
+            }
+        }
+        catch (err) {
+            this.emit({ type: "error", error: err instanceof Error ? err : new Error(String(err)) });
+        }
+    }
+    handleBinaryMessage(data) {
+        try {
+            const audio = decodeBrowserAssistantAudio(data, this.opusCodec);
+            if (audio.data.byteLength === 0)
+                return;
+            let pcmData = audio.data;
+            const wireRate = audio.metadata?.sampleRateHz;
+            if (wireRate !== undefined && wireRate !== this.outputSampleRateHz) {
+                const samples = pcm16BytesToSamples(new Uint8Array(pcmData));
+                const resampled = pcm16SamplesToBytes(resamplePcm16Streaming(this.streamingResamplers, samples, wireRate, this.outputSampleRateHz));
+                const copy = new Uint8Array(resampled.byteLength);
+                copy.set(resampled);
+                pcmData = copy.buffer;
+            }
+            this.handleAudioData(pcmData, audio.metadata);
+        }
+        catch (err) {
+            this.emit({ type: "error", error: err instanceof Error ? err : new Error(String(err)) });
+        }
+    }
+    scheduleUplink(send) {
+        if (!this.uplinkCodecDecided || this.codecNegotiation) {
+            this.pendingUplink.push(send);
+            return;
+        }
+        send();
+    }
+    flushPendingUplink() {
+        this.uplinkCodecDecided = true;
+        const pending = this.pendingUplink;
+        this.pendingUplink = [];
+        for (const run of pending)
+            run();
+    }
+    async negotiateWireCodec(audio) {
+        if (!audio)
+            return;
+        this.inputSampleRateHz = audio.inputSampleRateHz;
+        const supported = audio.supportedInputCodecs;
+        if (!supported?.includes("opus") || this.opusLoadFailed) {
+            this.wireCodec = "pcm_s16le";
+            this.reportDownlinkCodecCapability();
+            return;
+        }
+        try {
+            this.opusCodec = await createBrowserOpusCodec(BROWSER_OPUS_SAMPLE_RATE_HZ);
+            this.wireCodec = pickBrowserWireCodec(supported, true);
+        }
+        catch {
+            this.opusLoadFailed = true;
+            this.opusCodec = null;
+            this.wireCodec = "pcm_s16le";
+        }
+        this.reportDownlinkCodecCapability();
+    }
+    reportDownlinkCodecCapability() {
+        // The socket can drop during async codec negotiation (opus load) — e.g. a forced
+        // reconnect. The capability advert is re-sent on the next `ready` after reconnect,
+        // so skip it on a closed socket rather than throwing (which would crash the
+        // negotiation promise as an unhandled rejection).
+        if (!this.transport.connected)
+            return;
+        const downlinkEncoding = this.opusCodec ? "opus" : "pcm_s16le";
+        this.sendJson({ type: "codec_capability", downlinkEncoding });
+    }
+    encodeUplinkPcm(bytes, sampleRateHz, options) {
+        if (this.wireCodec === "opus" && this.opusCodec) {
+            const frames = [];
+            let seq = options.sequence;
+            const samples = pcm16BytesToSamples(bytes);
+            const wireSamples = sampleRateHz === this.opusCodec.sampleRateHz
+                ? samples
+                : resamplePcm16Streaming(this.streamingResamplers, samples, sampleRateHz, this.opusCodec.sampleRateHz);
+            for (const opus of this.opusCodec.encodePcm16Frame(wireSamples, true)) {
+                const sequence = this.nextAudioSequence(seq);
+                frames.push(encodeBrowserOpusEnvelope(opus, this.opusCodec.sampleRateHz, { ...options, sequence }));
+                seq = sequence;
+            }
+            return frames;
+        }
+        const sequence = this.nextAudioSequence(options.sequence);
+        return [encodeBrowserPcmEnvelope(bytes, sampleRateHz, { ...options, sequence })];
+    }
+    requireOpenTransport() {
+        if (!this.transport.connected) {
+            throw new Error("SyrinxBrowserClient transport is not connected");
+        }
+        return this.transport;
+    }
+    assertAudioSequenceCanAdvance(sequence) {
+        if (!Number.isInteger(sequence) || sequence < 0) {
+            throw new Error("audio sequence must be a non-negative integer");
+        }
+        if (sequence <= this.audioSequence) {
+            throw new Error(`audio sequence must increase monotonically: ${String(this.audioSequence)} -> ${String(sequence)}`);
+        }
+    }
+    nextAudioSequence(sequence) {
+        if (sequence !== undefined) {
+            if (!Number.isInteger(sequence) || sequence < 0)
+                throw new Error("audio sequence must be a non-negative integer");
+            if (sequence <= this.audioSequence) {
+                throw new Error(`audio sequence must increase monotonically: ${String(this.audioSequence)} -> ${String(sequence)}`);
+            }
+            this.audioSequence = Math.max(this.audioSequence, sequence);
+            return sequence;
+        }
+        this.audioSequence += 1;
+        return this.audioSequence;
+    }
+    handleAudioData(data, metadata) {
+        if (this.jitterBuffer) {
+            // Use jitter buffer for scheduled playback
+            this.jitterBuffer.enqueue(data, metadata?.contextId);
+        }
+        // Always emit the audio event for applications that want raw access
+        this.emit({ type: "audio", data, metadata });
+    }
+    emit(event) {
+        for (const handler of this.handlers) {
+            handler(event);
+        }
+    }
+}
+function buildResumeUrl(baseUrl, sessionId) {
+    try {
+        const url = new URL(baseUrl);
+        url.searchParams.set("sessionId", sessionId);
+        return url.toString();
+    }
+    catch {
+        const sep = baseUrl.includes("?") ? "&" : "?";
+        return `${baseUrl}${sep}sessionId=${encodeURIComponent(sessionId)}`;
+    }
+}
+function readPositiveSampleRate(value) {
+    if (!Number.isInteger(value) || value <= 0)
+        throw new Error("sampleRateHz must be a positive integer");
+    return value;
+}
+function parseStudioMessage(value) {
+    if (!isRecord(value))
+        throw new Error("Syrinx websocket message must be an object");
+    const type = requiredString(value.type, "Syrinx websocket message type");
+    if (type === "ready") {
+        return {
+            type,
+            sessionId: optionalString(value.sessionId, "ready.sessionId"),
+            resumed: optionalBoolean(value.resumed, "ready.resumed"),
+            resumeWindowMs: optionalNumber(value.resumeWindowMs, "ready.resumeWindowMs"),
+            audio: parseReadyAudio(value.audio),
+        };
+    }
+    if (type === "speech_started" || type === "speech_ended" || type === "agent_end" || type === "tts_end") {
+        return { type, turnId: optionalString(value.turnId, `${type}.turnId`) };
+    }
+    if (type === "stt_chunk" || type === "stt_output") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, `${type}.turnId`),
+            transcript: requiredString(value.transcript, `${type}.transcript`),
+            ...(type === "stt_output" ? { confidence: optionalNumber(value.confidence, "stt_output.confidence") } : {}),
+        };
+    }
+    if (type === "agent_chunk") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, "agent_chunk.turnId"),
+            text: requiredString(value.text, "agent_chunk.text"),
+        };
+    }
+    if (type === "agent_tool_call") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, "agent_tool_call.turnId"),
+            id: optionalString(value.id, "agent_tool_call.id"),
+            name: requiredString(value.name, "agent_tool_call.name"),
+            args: value.args,
+        };
+    }
+    if (type === "agent_tool_result") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, "agent_tool_result.turnId"),
+            id: optionalString(value.id, "agent_tool_result.id"),
+            result: value.result,
+        };
+    }
+    if (type === "tool_call_started" ||
+        type === "tool_call_delayed" ||
+        type === "tool_call_complete" ||
+        type === "tool_call_failed") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, `${type}.turnId`),
+            toolId: optionalString(value.toolId, `${type}.toolId`),
+            toolName: optionalString(value.toolName, `${type}.toolName`),
+            ...(type === "tool_call_delayed" ? { afterMs: optionalNumber(value.afterMs, "tool_call_delayed.afterMs") } : {}),
+        };
+    }
+    if (type === "agent_interrupted" || type === "audio_clear") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, `${type}.turnId`),
+            reason: optionalString(value.reason, `${type}.reason`),
+        };
+    }
+    if (type === "tts_chunk") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, "tts_chunk.turnId"),
+            sequence: requiredNonNegativeInteger(value.sequence, "tts_chunk.sequence"),
+            sampleRateHz: requiredPositiveInteger(value.sampleRateHz, "tts_chunk.sampleRateHz"),
+            encoding: requiredLiteral(value.encoding, "pcm_s16le", "tts_chunk.encoding"),
+            channels: requiredLiteral(value.channels, 1, "tts_chunk.channels"),
+            byteLength: requiredNonNegativeInteger(value.byteLength, "tts_chunk.byteLength"),
+            durationMs: requiredNonNegativeInteger(value.durationMs, "tts_chunk.durationMs"),
+        };
+    }
+    if (type === "metrics") {
+        const endpointingOwner = optionalEndpointingEnum(value.endpointingOwner, ENDPOINTING_OWNERS);
+        const endpointingReason = optionalEndpointingEnum(value.endpointingReason, ENDPOINTING_REASONS);
+        return {
+            type,
+            turnId: optionalString(value.turnId, "metrics.turnId"),
+            correlationId: optionalString(value.correlationId, "metrics.correlationId"),
+            speechEndMs: optionalNumber(value.speechEndMs, "metrics.speechEndMs"),
+            textReadyMs: optionalNumber(value.textReadyMs, "metrics.textReadyMs"),
+            firstAudioByteMs: optionalNumber(value.firstAudioByteMs, "metrics.firstAudioByteMs"),
+            firstAudioPlayedMs: optionalNumber(value.firstAudioPlayedMs, "metrics.firstAudioPlayedMs"),
+            lastAudioPlayedMs: optionalNumber(value.lastAudioPlayedMs, "metrics.lastAudioPlayedMs"),
+            sttMs: optionalNumber(value.sttMs, "metrics.sttMs"),
+            llmTTFTMs: optionalNumber(value.llmTTFTMs, "metrics.llmTTFTMs"),
+            ttsTTFBMs: optionalNumber(value.ttsTTFBMs, "metrics.ttsTTFBMs"),
+            e2eMs: optionalNumber(value.e2eMs, "metrics.e2eMs"),
+            ...(endpointingOwner !== undefined ? { endpointingOwner } : {}),
+            ...(endpointingReason !== undefined ? { endpointingReason } : {}),
+        };
+    }
+    if (type === "error") {
+        return {
+            type,
+            component: optionalString(value.component, "error.component"),
+            category: optionalString(value.category, "error.category"),
+            message: requiredString(value.message, "error.message"),
+        };
+    }
+    if (type === "turn_complete") {
+        return {
+            type,
+            turnId: optionalString(value.turnId, "turn_complete.turnId"),
+            transcript: typeof value.transcript === "string" ? value.transcript : "",
+        };
+    }
+    throw new Error(`Unsupported Syrinx websocket message type: ${type}`);
+}
+function parseReadyAudio(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        throw new Error("ready.audio must be an object");
+    const encoding = value.encoding;
+    if (encoding !== "pcm_s16le" && encoding !== "opus") {
+        throw new Error("ready.audio.encoding must be pcm_s16le or opus");
+    }
+    return {
+        inputSampleRateHz: requiredPositiveInteger(value.inputSampleRateHz, "ready.audio.inputSampleRateHz"),
+        outputSampleRateHz: requiredPositiveInteger(value.outputSampleRateHz, "ready.audio.outputSampleRateHz"),
+        encoding,
+        supportedInputCodecs: parseSupportedInputCodecs(value.supportedInputCodecs),
+        channels: requiredLiteral(value.channels, 1, "ready.audio.channels"),
+        binaryEnvelope: value.binaryEnvelope === undefined
+            ? undefined
+            : requiredLiteral(value.binaryEnvelope, "syrinx.audio.v1", "ready.audio.binaryEnvelope"),
+        rawBinaryInput: optionalBoolean(value.rawBinaryInput, "ready.audio.rawBinaryInput"),
+    };
+}
+function parseSupportedInputCodecs(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        throw new Error("ready.audio.supportedInputCodecs must be an array of strings");
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`${name} must be a non-empty string`);
+    return value;
+}
+function rmsFromPcm16Bytes(bytes) {
+    const sampleCount = Math.floor(bytes.byteLength / 2);
+    if (sampleCount === 0)
+        return 0;
+    const samples = new Int16Array(bytes.buffer, bytes.byteOffset, sampleCount);
+    let sumSquares = 0;
+    for (const sample of samples) {
+        const normalized = sample / 32768;
+        sumSquares += normalized * normalized;
+    }
+    return Math.sqrt(sumSquares / sampleCount);
+}
+function rmsFromFloat32(samples) {
+    if (samples.length === 0)
+        return 0;
+    let sumSquares = 0;
+    for (const sample of samples) {
+        sumSquares += sample * sample;
+    }
+    return Math.sqrt(sumSquares / samples.length);
+}
+function optionalString(value, name) {
+    // An optional field that arrives empty/null carries no value — treat as absent rather than
+    // throwing. (Servers may emit e.g. `tts_end.turnId: ""` when a turn has no context id.)
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    return requiredString(value, name);
+}
+function requiredPositiveInteger(value, name) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return value;
+}
+function requiredNonNegativeInteger(value, name) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+    return value;
+}
+function optionalNumber(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new Error(`${name} must be a finite number`);
+    return value;
+}
+function optionalBoolean(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new Error(`${name} must be a boolean`);
+    return value;
+}
+function optionalEndpointingEnum(value, allowed) {
+    // Forward-compatible: an unknown value is treated as absent, not an error, so a
+    // newer backend adding an enum member does not break an older client's message.
+    return typeof value === "string" && allowed.has(value) ? value : undefined;
+}
+function requiredLiteral(value, expected, name) {
+    if (value !== expected)
+        throw new Error(`${name} must be ${String(expected)}`);
+    return expected;
+}
+//# sourceMappingURL=index.js.map