@alexkroman1/aai-ui 1.8.2 → 1.9.0

package/dist/session-core-D3NDaySY.js

@@ -0,0 +1,652 @@
+import "./types.js";
+import { DEFAULT_MAX_HISTORY, FILE_UPLOAD_CHUNK_BYTES, WS_OPEN, errorMessage, safeJsonParse } from "@alexkroman1/aai";
+import { ServerMessageSchema, lenientParse } from "@alexkroman1/aai/protocol";
+import { MAX_SYNC_AUDIO_SECONDS } from "@alexkroman1/aai/stt";
+//#region session-core-messages.ts
+/**
+* Incoming-message handling for the voice session core.
+*
+* Split out of `session-core.ts`: this module owns the interpretation of
+* server→client frames (audio chunks + JSON {@link ServerMessage}s) and the
+* turn-boundary generation counters, while `session-core.ts` owns the state
+* store and connection lifecycle. The handlers read and mutate session state
+* exclusively through the injected `getSnapshot`/`updateState` deps.
+*/
+/** Cap on `customEvents` retained in the session snapshot to avoid unbounded growth. */
+const MAX_CUSTOM_EVENTS = 200;
+/** Cap on `messages` retained in the session snapshot; matches the host-side history cap. */
+const MAX_MESSAGES = DEFAULT_MAX_HISTORY;
+/** Cap on pre-init audio chunks buffered while `voiceIO` is initializing. ~100 chunks at
+*  typical S2S chunk sizes is well over a second of audio — far longer than init takes
+*  in practice, but bounded against pathological cases (mic-permission stalls). */
+const MAX_PREINIT_AUDIO_CHUNKS = 100;
+/**
+* Snapshot fields cleared when a session's conversation state is wiped —
+* shared by the initial snapshot, `resetState()`, and the server `reset` event.
+* The empty arrays are safe to share: snapshot collections are never mutated
+* in place, only replaced.
+*/
+const CLEARED_SESSION_STATE = {
+	messages: [],
+	toolCalls: [],
+	customEvents: [],
+	userTranscript: null,
+	agentTranscript: null,
+	error: null
+};
+function appendCapped(list, item, cap) {
+	if (list.length < cap) return [...list, item];
+	const next = list.slice(list.length - cap + 1);
+	next.push(item);
+	return next;
+}
+/**
+* Create the server→client message handlers for one session core.
+*
+* Encapsulates the two turn-boundary counters (`handlerGeneration` for
+* discarding stale async audio completions, `customEventSeq` for event
+* dedup) that previously lived as closure locals in `createSessionCore`.
+*/
+function createMessageHandlers(deps) {
+	const { getSnapshot, updateState, conn } = deps;
+	/** Incremented on each turn boundary -- stale async callbacks compare against this. */
+	let handlerGeneration = 0;
+	/** Monotonically increasing counter for custom events -- used by useEvent to deduplicate. */
+	let customEventSeq = 0;
+	/** Monotonically increasing counter for chat messages -- stable render keys
+	*  and tool-call anchoring that survive the sliding message window. */
+	let messageSeq = 0;
+	/** Monotonically increasing counter for tool calls -- used by the tool-call
+	*  hooks to iterate only the unprocessed tail. */
+	let toolCallSeq = 0;
+	function appendCustomEvent(name, data) {
+		updateState({ customEvents: appendCapped(getSnapshot().customEvents, {
+			id: ++customEventSeq,
+			event: name,
+			data
+		}, MAX_CUSTOM_EVENTS) });
+	}
+	function handleUserTranscriptEvent(text) {
+		handlerGeneration++;
+		updateState({
+			userTranscript: null,
+			messages: appendCapped(getSnapshot().messages, {
+				id: ++messageSeq,
+				role: "user",
+				content: text
+			}, MAX_MESSAGES),
+			state: "thinking"
+		});
+	}
+	function handleAgentTranscriptEvent(text) {
+		updateState({
+			agentTranscript: null,
+			messages: appendCapped(getSnapshot().messages, {
+				id: ++messageSeq,
+				role: "assistant",
+				content: text
+			}, MAX_MESSAGES)
+		});
+	}
+	/** Clear error state when a non-error event arrives — proves the session
+	*  is functional (e.g. audio init failed but WebSocket still works). */
+	function clearRecoveredError() {
+		const snap = getSnapshot();
+		if (snap.state === "error") updateState({
+			state: "disconnected",
+			error: null
+		});
+		else if (snap.error !== null) updateState({ error: null });
+	}
+	function handleErrorEvent(e) {
+		console.error("Agent error:", e.message);
+		if (e.fatal === false) updateState({ error: {
+			code: e.code,
+			message: e.message
+		} });
+		else updateState({
+			state: "error",
+			error: {
+				code: e.code,
+				message: e.message
+			},
+			running: false
+		});
+	}
+	/** Single entry point for all server->client session events. */
+	function handleEvent(e) {
+		if (e.type !== "error") clearRecoveredError();
+		switch (e.type) {
+			case "speech_started":
+				updateState({ userTranscript: "" });
+				break;
+			case "speech_stopped": break;
+			case "user_transcript":
+				handleUserTranscriptEvent(e.text);
+				break;
+			case "user_transcript_partial":
+				updateState({ userTranscript: e.text });
+				break;
+			case "agent_transcript":
+				handleAgentTranscriptEvent(e.text);
+				break;
+			case "tool_call":
+				updateState({ toolCalls: appendCapped(getSnapshot().toolCalls, {
+					callId: e.toolCallId,
+					name: e.toolName,
+					args: e.args ?? {},
+					status: "pending",
+					seq: ++toolCallSeq,
+					afterMessageId: getSnapshot().messages.at(-1)?.id ?? -1
+				}, MAX_MESSAGES) });
+				break;
+			case "tool_call_done": {
+				const tcs = getSnapshot().toolCalls;
+				const idx = tcs.findIndex((tc) => tc.callId === e.toolCallId);
+				if (idx !== -1) {
+					const updated = [...tcs];
+					const existing = updated[idx];
+					if (existing) updated[idx] = {
+						...existing,
+						status: "done",
+						result: e.result
+					};
+					updateState({ toolCalls: updated });
+				}
+				break;
+			}
+			case "reply_done":
+				updateState({ state: "listening" });
+				break;
+			case "cancelled":
+				handlerGeneration++;
+				conn.voiceIO?.flush();
+				updateState({
+					userTranscript: null,
+					agentTranscript: null,
+					state: "listening"
+				});
+				break;
+			case "reset":
+				handlerGeneration++;
+				conn.voiceIO?.flush();
+				updateState({
+					...CLEARED_SESSION_STATE,
+					state: "listening"
+				});
+				break;
+			case "custom_event":
+				appendCustomEvent(e.event, e.data);
+				break;
+			case "error":
+				handleErrorEvent(e);
+				break;
+			case "idle_timeout": break;
+			default: break;
+		}
+	}
+	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
+	function playAudioChunk(chunk) {
+		const snap = getSnapshot();
+		if (snap.state === "disconnected" && snap.error !== null) return;
+		if (snap.state !== "speaking") updateState({ state: "speaking" });
+		if (conn.voiceIO) conn.voiceIO.enqueue(chunk.buffer);
+		else if (conn.preInitAudio.length < MAX_PREINIT_AUDIO_CHUNKS) conn.preInitAudio.push(chunk);
+	}
+	/**
+	* Signal that the server has finished sending audio for this turn.
+	* Waits for the audio queue to drain, then transitions state to `"listening"`.
+	* Uses the `handlerGeneration` counter to discard stale completions from interrupted turns.
+	*/
+	function playAudioDone() {
+		const gen = handlerGeneration;
+		const io = conn.voiceIO;
+		if (io) io.done().then(() => {
+			if (handlerGeneration !== gen) return;
+			updateState({ state: "listening" });
+		}).catch((err) => {
+			console.warn("Audio playback done failed:", err);
+		});
+		else {
+			conn.preInitDone = true;
+			updateState({ state: "listening" });
+		}
+	}
+	function handleMessage(data) {
+		if (data instanceof ArrayBuffer) {
+			playAudioChunk(new Uint8Array(data));
+			return;
+		}
+		if (typeof data !== "string") {
+			console.warn("session-core: non-string, non-binary frame received; dropping");
+			return;
+		}
+		const raw = safeJsonParse(data);
+		if (raw === void 0) {
+			console.warn("session-core: invalid JSON; dropping");
+			return;
+		}
+		const parsed = lenientParse(ServerMessageSchema, raw);
+		if (!parsed.ok) {
+			if (parsed.malformed) console.warn("session-core: malformed server message", parsed.error);
+			return;
+		}
+		const msg = parsed.data;
+		if (msg.type === "config") return {
+			sampleRate: msg.sampleRate,
+			ttsSampleRate: msg.ttsSampleRate,
+			audioOut: msg.audioOut,
+			sid: msg.sessionId
+		};
+		if (msg.type === "audio_done") {
+			playAudioDone();
+			return;
+		}
+		handleEvent(msg);
+	}
+	return { handleMessage };
+}
+//#endregion
+//#region session-core-upload.ts
+/**
+* File-upload transcription for the session core (`sendAudioFile`).
+*
+* Split out of `session-core.ts`: this module owns the decode → frame →
+* reliable-send pipeline for uploaded audio, plus the two guards that keep
+* it exclusive — an in-flight lock (no second upload, no mic start
+* mid-upload) and an epoch that in-flight sends compare against so a
+* reset/close/reconnect abandons them instead of streaming a stale clip
+* into the fresh session.
+*/
+function createUploadSender(deps) {
+	const { conn, getSnapshot, sendJson } = deps;
+	/** True while a `sendAudioFile` upload is decoding or streaming. Blocks the
+	*  mic (and a second upload) so file bytes never interleave with live audio. */
+	let uploadInFlight = false;
+	/** Bumped whenever conversation/connection state is discarded (reset, close,
+	*  reconnect). An in-flight upload compares against it between chunks and
+	*  aborts instead of streaming a stale clip into the fresh session. */
+	let uploadEpoch = 0;
+	/** Stream `bytes` to the socket in chunks, waiting out backpressure.
+	*  Unlike live mic frames (dropped under backpressure — stale speech is
+	*  worthless), file audio must arrive completely. Aborts if the connection
+	*  closes or the session is reset (`epoch` moves on) between chunks. */
+	async function sendBytesReliably(bytes, epoch) {
+		for (let i = 0; i < bytes.byteLength; i += FILE_UPLOAD_CHUNK_BYTES) {
+			while (epoch === uploadEpoch && conn.ws && conn.ws.readyState === WS_OPEN && conn.ws.bufferedAmount > 65536) await new Promise((r) => setTimeout(r, 50));
+			if (epoch !== uploadEpoch) throw new Error("sendAudioFile: session was reset mid-send");
+			if (!conn.ws || conn.ws.readyState !== WS_OPEN) throw new Error("sendAudioFile: connection closed mid-send");
+			conn.ws.send(bytes.subarray(i, i + FILE_UPLOAD_CHUNK_BYTES));
+		}
+	}
+	/** Validate that an upload may start; returns the session's ready config. */
+	function assertUploadReady() {
+		const cfg = conn.readyConfig;
+		if (!(cfg && conn.ws) || conn.ws.readyState !== WS_OPEN) throw new Error("sendAudioFile: session is not connected");
+		const snap = getSnapshot();
+		if (snap.audioOut) throw new Error("sendAudioFile is only available in text-only sessions (tts: none()) — voice sessions stream the microphone instead");
+		if (snap.recording) throw new Error("sendAudioFile: stop recording before uploading a file");
+		if (uploadInFlight) throw new Error("sendAudioFile: another upload is already in progress");
+		return cfg;
+	}
+	async function sendAudioFile(file) {
+		const cfg = assertUploadReady();
+		uploadInFlight = true;
+		const epoch = uploadEpoch;
+		try {
+			const { decodeAudioToPcm16 } = await import("./audio.js");
+			const clip = await decodeAudioToPcm16(await file.arrayBuffer(), cfg.sampleRate);
+			if (getSnapshot().recording || conn.audioSetupInFlight) throw new Error("sendAudioFile: stop recording before uploading a file");
+			if (epoch !== uploadEpoch) throw new Error("sendAudioFile: session was reset mid-send");
+			if (clip.length / cfg.sampleRate <= MAX_SYNC_AUDIO_SECONDS) {
+				const bytes = new Uint8Array(clip.buffer, clip.byteOffset, clip.byteLength);
+				sendJson({
+					type: "transcribe_file_start",
+					sampleRate: cfg.sampleRate,
+					byteLength: bytes.byteLength
+				});
+				await sendBytesReliably(bytes, epoch);
+				sendJson({ type: "transcribe_file_end" });
+				return;
+			}
+			const padded = new Int16Array(clip.length + cfg.sampleRate);
+			padded.set(clip);
+			await sendBytesReliably(new Uint8Array(padded.buffer), epoch);
+		} finally {
+			uploadInFlight = false;
+		}
+	}
+	return {
+		sendAudioFile,
+		inFlight: () => uploadInFlight,
+		discard: () => {
+			uploadEpoch++;
+		}
+	};
+}
+//#endregion
+//#region session-core.ts
+/**
+* Framework-agnostic voice session core.
+*
+* Manages WebSocket communication, audio capture/playback, and agent state
+* transitions using a subscribe/getSnapshot pattern compatible with React's
+* `useSyncExternalStore` and other external store consumers.
+*
+* Server→client message interpretation lives in `session-core-messages.ts`;
+* the public/internal type declarations live in `session-core-types.ts`.
+*
+* No dependency on React, Preact, or any UI framework.
+*/
+/**
+* Initialize audio capture and playback after the server sends a ready config.
+*
+* Lifecycle: dynamically import audio modules -> request microphone access ->
+* register AudioWorklet processors -> create a `VoiceIO` instance -> send
+* `audio_ready` to the server -> transition state to `"listening"`.
+*
+* Uses the connection `generation` counter to detect if `connect()` was called
+* while awaiting async operations; if so, the stale VoiceIO is closed immediately
+* to prevent it from being assigned to a newer connection.
+*
+* On failure (e.g. microphone permission denied, WebSocket closed mid-setup),
+* sets the error state and transitions to `"disconnected"`.
+*/
+async function initAudioCapture(conn, msg, deps) {
+	if (conn.audioSetupInFlight) return;
+	conn.audioSetupInFlight = true;
+	const gen = conn.generation;
+	try {
+		const [{ createVoiceIO }, captureWorklet, playbackWorklet] = await Promise.all([
+			import("./audio.js"),
+			import("./worklets/capture-processor.js").then((m) => m.default),
+			import("./worklets/playback-processor.js").then((m) => m.default)
+		]);
+		const io = await createVoiceIO({
+			sttSampleRate: msg.sampleRate,
+			ttsSampleRate: msg.ttsSampleRate,
+			captureWorkletSrc: captureWorklet,
+			playbackWorkletSrc: playbackWorklet,
+			onMicData: (pcm16) => {
+				try {
+					deps.sendAudio(new Uint8Array(pcm16));
+				} catch {
+					console.debug("[aai-ui] sendAudio dropped: connection closed");
+				}
+			}
+		});
+		if (conn.generation !== gen || !conn.ws || conn.ws.readyState !== WS_OPEN) {
+			io.close();
+			return;
+		}
+		conn.voiceIO = io;
+		if (conn.preInitAudio.length > 0) {
+			for (const chunk of conn.preInitAudio) io.enqueue(chunk.buffer);
+			conn.preInitAudio = [];
+		}
+		deps.sendJson({ type: "audio_ready" });
+		deps.updateState({ recording: true });
+		if (conn.preInitDone) {
+			conn.preInitDone = false;
+			io.done().then(() => {
+				if (conn.generation !== gen) return;
+				deps.updateState({ state: "listening" });
+			}).catch(() => deps.updateState({ state: "listening" }));
+		} else deps.updateState({ state: "listening" });
+	} catch (err) {
+		if (conn.generation !== gen || !conn.ws || conn.ws.readyState !== WS_OPEN) return;
+		deps.updateState({
+			state: "error",
+			error: {
+				code: "audio",
+				message: `Microphone access failed: ${errorMessage(err)}`
+			},
+			running: false
+		});
+	} finally {
+		conn.audioSetupInFlight = false;
+	}
+}
+function buildWsUrl(platformUrl, resume, sessionId) {
+	const wsUrl = new URL("websocket", platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`);
+	wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+	if (sessionId) wsUrl.searchParams.set("sessionId", sessionId);
+	else if (resume) wsUrl.searchParams.set("resume", "1");
+	return wsUrl;
+}
+/**
+* Create a framework-agnostic voice session core that connects to an AAI
+* server via WebSocket.
+*
+* Uses a subscribe/getSnapshot pattern for state management, compatible with
+* React's `useSyncExternalStore` and other external store integrations.
+*
+* @param options - Session configuration including the platform server URL.
+* @returns A {@link SessionCore} handle for controlling the session.
+*
+* @public
+*/
+function createSessionCore(options) {
+	const WS = options.WebSocket ?? WebSocket;
+	let currentSnapshot = {
+		...CLEARED_SESSION_STATE,
+		state: "disconnected",
+		contentVersion: 0,
+		started: false,
+		running: false,
+		audioOut: true,
+		recording: false,
+		apiUrl: buildWsUrl(options.platformUrl, false).toString()
+	};
+	const subscribers = /* @__PURE__ */ new Set();
+	function notify() {
+		for (const sub of subscribers) sub();
+	}
+	/** Snapshot fields whose changes bump `contentVersion` (rendered conversation content). */
+	const contentKeys = [
+		"messages",
+		"toolCalls",
+		"userTranscript",
+		"agentTranscript"
+	];
+	function updateState(partial) {
+		currentSnapshot = contentKeys.some((key) => key in partial && partial[key] !== currentSnapshot[key]) ? {
+			...currentSnapshot,
+			...partial,
+			contentVersion: currentSnapshot.contentVersion + 1
+		} : {
+			...currentSnapshot,
+			...partial
+		};
+		notify();
+	}
+	function getSnapshot() {
+		return currentSnapshot;
+	}
+	function subscribe(callback) {
+		subscribers.add(callback);
+		return () => {
+			subscribers.delete(callback);
+		};
+	}
+	const conn = {
+		ws: null,
+		voiceIO: null,
+		audioSetupInFlight: false,
+		generation: 0,
+		preInitAudio: [],
+		preInitDone: false,
+		readyConfig: null
+	};
+	let connectionController = null;
+	let hasConnected = false;
+	function cleanupAudio() {
+		upload.discard();
+		conn.audioSetupInFlight = false;
+		conn.voiceIO?.close();
+		conn.voiceIO = null;
+		conn.preInitAudio = [];
+		conn.preInitDone = false;
+	}
+	function resetState() {
+		updateState(CLEARED_SESSION_STATE);
+	}
+	function sendJson(msg) {
+		if (conn.ws && conn.ws.readyState === WS_OPEN) conn.ws.send(JSON.stringify(msg));
+	}
+	function sendAudio(bytes) {
+		if (!conn.ws || conn.ws.readyState !== WS_OPEN) return;
+		if (conn.ws.bufferedAmount > 65536) return;
+		conn.ws.send(bytes);
+	}
+	const audioDeps = {
+		sendJson,
+		sendAudio,
+		updateState
+	};
+	const upload = createUploadSender({
+		conn,
+		getSnapshot,
+		sendJson
+	});
+	const { handleMessage } = createMessageHandlers({
+		getSnapshot,
+		updateState,
+		conn
+	});
+	/** Abort the in-flight connection and release audio + WebSocket resources. */
+	function teardownConnection() {
+		connectionController?.abort();
+		connectionController = null;
+		cleanupAudio();
+		conn.ws?.close();
+		conn.ws = null;
+	}
+	/** React to the server's `config` message: record it, set up the audio
+	*  path for the session's mode, and replay history on reconnect. */
+	function onServerConfig(config) {
+		if (config.sid) options.onSessionId?.(config.sid);
+		const isReconnect = hasConnected;
+		hasConnected = true;
+		conn.readyConfig = {
+			sampleRate: config.sampleRate,
+			ttsSampleRate: config.ttsSampleRate
+		};
+		const audioOut = config.audioOut !== false;
+		updateState({ audioOut });
+		if (audioOut) initAudioCapture(conn, config, audioDeps);
+		else {
+			sendJson({ type: "audio_ready" });
+			updateState({ state: "listening" });
+		}
+		if (isReconnect && currentSnapshot.messages.length > 0) sendJson({
+			type: "history",
+			messages: currentSnapshot.messages.map((m) => ({
+				role: m.role,
+				content: m.content
+			}))
+		});
+	}
+	function connect(opts) {
+		updateState({
+			state: "connecting",
+			error: null
+		});
+		teardownConnection();
+		conn.generation++;
+		const controller = new AbortController();
+		connectionController = controller;
+		const { signal: sig } = controller;
+		if (opts?.signal) opts.signal.addEventListener("abort", () => disconnect(), { signal: sig });
+		const resumeId = !hasConnected ? options.resumeSessionId : void 0;
+		const wsUrl = buildWsUrl(options.platformUrl, hasConnected, resumeId);
+		const socket = new WS(wsUrl.toString());
+		socket.binaryType = "arraybuffer";
+		conn.ws = socket;
+		socket.addEventListener("open", () => {
+			updateState({ state: "ready" });
+		}, { signal: sig });
+		socket.addEventListener("message", (event) => {
+			const config = handleMessage(event.data);
+			if (config) onServerConfig(config);
+		}, { signal: sig });
+		socket.addEventListener("close", () => {
+			if (sig.aborted) return;
+			controller.abort();
+			cleanupAudio();
+			updateState({
+				state: "disconnected",
+				running: false,
+				recording: false
+			});
+		}, { signal: sig });
+	}
+	function cancel() {
+		conn.voiceIO?.flush();
+		updateState({ state: "listening" });
+		sendJson({ type: "cancel" });
+	}
+	function reset() {
+		upload.discard();
+		conn.voiceIO?.flush();
+		if (conn.ws && conn.ws.readyState === WS_OPEN) {
+			sendJson({ type: "reset" });
+			return;
+		}
+		resetState();
+		disconnect();
+		connect();
+	}
+	function disconnect() {
+		teardownConnection();
+		updateState({
+			state: "disconnected",
+			running: false,
+			recording: false
+		});
+	}
+	function startRecording() {
+		if (currentSnapshot.audioOut || currentSnapshot.recording || conn.audioSetupInFlight || upload.inFlight()) return;
+		const cfg = conn.readyConfig;
+		if (!(cfg && conn.ws) || conn.ws.readyState !== WS_OPEN) return;
+		initAudioCapture(conn, cfg, audioDeps);
+	}
+	function stopRecording() {
+		if (currentSnapshot.audioOut || !currentSnapshot.recording) return;
+		cleanupAudio();
+		updateState({ recording: false });
+	}
+	function start() {
+		updateState({
+			started: true,
+			running: true
+		});
+		connect();
+	}
+	function toggle() {
+		if (currentSnapshot.running) disconnect();
+		else {
+			updateState({ running: true });
+			connect();
+		}
+	}
+	return {
+		getSnapshot,
+		subscribe,
+		connect,
+		cancel,
+		resetState,
+		reset,
+		disconnect,
+		start,
+		toggle,
+		startRecording,
+		stopRecording,
+		sendAudioFile: upload.sendAudioFile,
+		[Symbol.dispose]() {
+			disconnect();
+		}
+	};
+}
+//#endregion
+export { createSessionCore as t };

package/dist/session-core-messages.d.ts

@@ -0,0 +1,50 @@
+import type { ConnState, SessionSnapshot } from "./session-core-types.ts";
+/**
+ * Snapshot fields cleared when a session's conversation state is wiped —
+ * shared by the initial snapshot, `resetState()`, and the server `reset` event.
+ * The empty arrays are safe to share: snapshot collections are never mutated
+ * in place, only replaced.
+ */
+export declare const CLEARED_SESSION_STATE: {
+    messages: never[];
+    toolCalls: never[];
+    customEvents: never[];
+    userTranscript: null;
+    agentTranscript: null;
+    error: null;
+};
+/** Config payload extracted from a `config` server message. */
+export type SessionConfigMessage = {
+    sampleRate: number;
+    ttsSampleRate: number;
+    /** False for text-only agents (`tts: none()`) — see ReadyConfigSchema. */
+    audioOut?: boolean | undefined;
+    sid?: string | undefined;
+};
+/** Dependencies the message handlers need from the owning session core. */
+type MessageHandlerDeps = {
+    getSnapshot: () => SessionSnapshot;
+    updateState: (partial: Partial<SessionSnapshot>) => void;
+    conn: ConnState;
+};
+type MessageHandlers = {
+    /**
+     * Dispatch an incoming WebSocket message.
+     *
+     * Binary frames carry raw PCM16 audio chunks. Text frames are JSON-encoded
+     * {@link ServerMessage} values validated via Zod.
+     *
+     * Returns the parsed config if the message is a `config` message,
+     * otherwise `undefined`.
+     */
+    handleMessage(data: unknown): SessionConfigMessage | undefined;
+};
+/**
+ * Create the server→client message handlers for one session core.
+ *
+ * Encapsulates the two turn-boundary counters (`handlerGeneration` for
+ * discarding stale async audio completions, `customEventSeq` for event
+ * dedup) that previously lived as closure locals in `createSessionCore`.
+ */
+export declare function createMessageHandlers(deps: MessageHandlerDeps): MessageHandlers;
+export {};