@alexkroman1/aai-ui 16.1.0 → 18.0.0

package/dist/{session-core-gwePM95B.js → session-core-TOdm_Con.js}

@@ -1,11 +1,52 @@
-import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-DJQHnYjm.js";
+import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-CFhkMkmv.js";
 import { MIC_SEND_MAX_BUFFERED_BYTES } from "./types.js";
-import { SessionEventSchema, lenientParse } from "@alexkroman1/aai/protocol";
-import { errorMessage, safeJsonParse } from "@alexkroman1/aai";
+import { lenientParse } from "@alexkroman1/aai/protocol";
+import { SessionEventSchema, errorMessage, safeJsonParse } from "@alexkroman1/aai";
 import { omitUndefined } from "@alexkroman1/aai/utils";
 import { DEFAULT_MAX_HISTORY, WS_OPEN, createEpoch, toArgsRecord } from "@alexkroman1/aai/internal";
+import { and, assign, createActor, fromPromise, not, setup, stateIn } from "xstate";
 import ReconnectingWebSocket from "partysocket/ws";
-import { and, assign, createActor, not, setup, stateIn } from "xstate";
+//#region src/session-core-audio-setup.ts
+let audioModulesPromise = null;
+/**
+* Load the audio module and worklet sources, memoized so a prefetch at
+* `connect()` time overlaps the chunk fetch with the WebSocket handshake
+* instead of serializing it behind the server's `config` frame. A failed
+* load clears the memo so the next attempt retries the import.
+*/
+function loadAudioModules() {
+	audioModulesPromise ??= Promise.all([
+		import("./audio.js"),
+		import("./worklets/capture-processor.js").then((m) => m.default),
+		import("./worklets/playback-processor.js").then((m) => m.default)
+	]).catch((err) => {
+		audioModulesPromise = null;
+		throw err;
+	});
+	return audioModulesPromise;
+}
+/**
+* Open one audio path: load the worklets, ask for the microphone, and build
+* the {@link VoiceIO} wired to `callbacks`.
+*
+* Rejects when any of the three refuses — a denied mic prompt being the
+* ordinary case. The caller owns closing what this resolves: a path that comes
+* up for a connection nobody wants any more is a live microphone, and no
+* amount of cancellation upstream releases the device.
+*/
+async function openAudioPath(config, callbacks) {
+	const [{ createVoiceIO }, captureWorklet, playbackWorklet] = await loadAudioModules();
+	return createVoiceIO({
+		sttSampleRate: config.sampleRate,
+		ttsSampleRate: config.ttsSampleRate,
+		captureWorkletSrc: captureWorklet,
+		playbackWorkletSrc: playbackWorklet,
+		onMicData: callbacks.onMicData,
+		onPlaybackProgress: callbacks.onProgress,
+		onError: (err) => callbacks.onFailure(err.message)
+	});
+}
+//#endregion
 //#region src/session-core-types.ts
 /**
 * The two liveness fields at rest.
@@ -39,122 +80,331 @@ const STOPPED = {
 * bump on its own now reads as a deliberate choice rather than a forgotten
 * flush.
 */
-function bargeIn(conn) {
+function bargeIn(conn, audio) {
 	conn.turn.bump();
-	conn.voiceIO?.flush();
+	audio.flush();
 }
 //#endregion
-//#region src/session-core-audio-setup.ts
+//#region src/session-core-audio-effects.ts
+/** Build the effects for one session's audio path. */
+function createAudioEffects(deps) {
+	const { conn, updateState, agentState, sendJson, sendAudio } = deps;
+	/**
+	* Wait for `io`'s playback queue to drain, then go back to listening.
+	*
+	* Captures `conn.turn` so a completion (or failure) landing after a turn
+	* boundary — a barge-in, a committed user turn, an audio-path teardown — is
+	* discarded instead of overwriting the newer turn's, or a dead session's,
+	* state.
+	*/
+	function settleWhenDrained(io) {
+		const at = conn.turn.current();
+		io.done().then(() => {
+			if (!conn.turn.isCurrent(at)) return;
+			updateState(agentState.apply({ type: "LISTEN" }));
+		}).catch((err) => {
+			console.warn("Audio playback done failed:", err);
+		});
+	}
+	return {
+		open: openAudioPath,
+		sendMicAudio: (pcm16) => {
+			try {
+				sendAudio(pcm16);
+			} catch {
+				console.debug("[aai-ui] sendAudio dropped: connection closed");
+			}
+		},
+		reportProgress: (bufferedMs) => {
+			try {
+				sendJson({
+					type: "playback_progress",
+					bufferedMs
+				});
+			} catch {}
+		},
+		announceReady: () => sendJson({ type: "audio_ready" }),
+		micLive: () => updateState({ recording: true }),
+		listen: () => updateState(agentState.apply({ type: "LISTEN" })),
+		settleWhenDrained,
+		reportFailure: (message) => {
+			updateState({
+				...agentState.apply({
+					type: "FAILED",
+					error: {
+						code: "audio",
+						message,
+						fatal: false
+					}
+				}),
+				...STOPPED
+			});
+		},
+		endTurn: () => conn.turn.bump(),
+		release: (io) => {
+			io.close().catch(() => {});
+		}
+	};
+}
+//#endregion
+//#region src/session-core-audio-state.ts
 /**
-* Audio-path initialization for the voice session core.
+* The browser session's AUDIO PATH — the mic grant, the worklets, and the
+* {@link VoiceIO} they produce — as a statechart.
+*
+* It was a latch, an epoch counter and three buffers spread across
+* `ConnState`, and every one of them was a question the position already
+* answers:
+*
+* - **`audioSetupInFlight` was a dedup, and dedup is a state.**
+*   `initAudioCapture` opened with `if (conn.audioSetupInFlight) return` and
+*   closed with "only the init that still owns the flag may clear it", which is
+*   an ownership problem a boolean cannot express and a position does not have.
+*   Here `starting` simply does not handle `START`, and there is no flag to
+*   hand back.
+* - **`conn.generation` existed for this module and nothing else.** Four
+*   `bump()` sites, four `isCurrent(gen)` reads, and its own field on
+*   `ConnState`. All four bumps sat immediately after a `cleanupAudio()` that
+*   had *just* cleared the in-flight flag — the reconnect close handler said so
+*   outright ("cleanupAudio just cleared the in-flight flag, so a survivor
+*   would otherwise pass the same-generation guard and double-run"). Two
+*   mechanisms for one question, the second one layered on because the first
+*   could not stop the work already running. A stopped `invoke` can, so the
+*   counter is gone.
+* - **A counter cannot tell two bring-ups in ONE generation apart, and they
+*   happen.** A repeated `config` frame on a live connection re-opened the path
+*   without bumping anything, so the outgoing `VoiceIO`'s `onError` still
+*   passed `isCurrent(gen)` and could tear down the replacement that had just
+*   taken its slot. `PROGRESS` and `IO_FAILED` carry the instance that fired
+*   them now, and identity is exact where a counter was approximate.
+* - **`preInitAudio` / `preInitDone` are only meaningful while the path is
+*   down.** As connection fields they were readable — and writable — from
+*   anywhere; as context of `down`/`starting` they are cleared by entering
+*   `down` rather than by three call sites remembering to.
+*
+* ## What cancellation does NOT do, and the one guard that had to survive
 *
-* Split out of `session-core.ts`: this module owns the async
-* mic-permission → worklet-registration → `VoiceIO` bring-up (and its
-* staleness/failure handling), while `session-core.ts` owns the state store
-* and connection lifecycle.
+* Stopping the `bringUp` actor hides its resolution; it does not close a
+* microphone the browser has already granted. So `bringUp` checks its own
+* `signal` after `openAudioPath` settles and releases what it built. That is
+* the single remaining "is this still wanted?" test, and it lives in the
+* producer — which owns the value nobody adopted — rather than at the four
+* consumer sites that used to re-ask.
+*
+* ## Effects stay in the session core
+*
+* The machine owns WHEN. Every HOW — the socket frame, the snapshot write, the
+* turn-boundary drain — arrives as an injected {@link AudioPathEffects} call,
+* the same shape `s2s-lifecycle.ts` uses. So this module touches no socket and
+* no snapshot.
 */
-let audioModulesPromise = null;
 /**
-* Load the audio module and worklet sources, memoized so a prefetch at
-* `connect()` time overlaps the chunk fetch with the WebSocket handshake
-* instead of serializing it behind the server's `config` frame. A failed
-* load clears the memo so the next attempt retries the import.
+* Cap on audio chunks buffered while the path is coming up. ~100 chunks at
+* typical S2S chunk sizes is well over a second of audio — far longer than a
+* bring-up takes in practice, but bounded against pathological cases
+* (mic-permission stalls).
 */
-function loadAudioModules() {
-	audioModulesPromise ??= Promise.all([
-		import("./audio.js"),
-		import("./worklets/capture-processor.js").then((m) => m.default),
-		import("./worklets/playback-processor.js").then((m) => m.default)
-	]).catch((err) => {
-		audioModulesPromise = null;
-		throw err;
-	});
-	return audioModulesPromise;
-}
+const MAX_BUFFERED_CHUNKS = 100;
 /**
-* 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"`.
+* The rejection a bring-up abandons itself with.
 *
-* Uses the connection `generation` counter to detect if `connect()` was called
-* (or a reconnect happened) while awaiting async operations; if so, the stale
-* VoiceIO is closed immediately to prevent it from being assigned to a newer
-* connection.
-*
-* A failure is fatal: a voice session can't function without the mic, so it
-* sets the error state and ends the session.
+* Never observed: the actor is already stopped when it is thrown, and XState
+* drops a settlement from a stopped actor. It exists so the `async` function
+* has a way to end that is not "resolve with a VoiceIO I have just closed".
 */
-async function initAudioCapture(conn, msg, deps) {
-	if (conn.audioSetupInFlight) return;
-	conn.audioSetupInFlight = true;
-	const gen = conn.generation.current();
-	const stale = () => !(conn.generation.isCurrent(gen) && conn.ws) || conn.ws.readyState !== WS_OPEN;
-	const reportAudioFailure = (message) => {
-		deps.cleanupAudio();
-		deps.updateState({
-			...deps.agentState.apply({
-				type: "FAILED",
-				error: {
-					code: "audio",
-					message,
-					fatal: false
-				}
-			}),
-			...STOPPED
-		});
-	};
-	try {
-		const [{ createVoiceIO }, captureWorklet, playbackWorklet] = await loadAudioModules();
-		const io = await createVoiceIO({
-			sttSampleRate: msg.sampleRate,
-			ttsSampleRate: msg.ttsSampleRate,
-			captureWorkletSrc: captureWorklet,
-			playbackWorkletSrc: playbackWorklet,
-			onMicData: (pcm16) => {
-				try {
-					deps.sendAudio(pcm16);
-				} catch {
-					console.debug("[aai-ui] sendAudio dropped: connection closed");
-				}
-			},
-			onPlaybackProgress: (bufferedMs) => {
-				if (!conn.generation.isCurrent(gen)) return;
-				try {
-					deps.sendJson({
-						type: "playback_progress",
-						bufferedMs
-					});
-				} catch {}
+const ABANDONED = /* @__PURE__ */ new Error("audio path abandoned");
+const audioPathMachine = setup({
+	types: {},
+	actors: { 
+	/**
+	* One bring-up. An actor rather than a fire-and-forget `void init(...)`
+	* precisely so that leaving `starting` — a hang-up, a reconnect, a fatal
+	* frame — stops it, instead of letting it settle into a connection that is
+	* already over.
+	*/
+bringUp: fromPromise(async ({ input, signal }) => {
+		let mine = null;
+		const io = await input.effects.open(input.config, {
+			onMicData: (pcm16) => input.effects.sendMicAudio(pcm16),
+			onProgress: (bufferedMs) => {
+				if (mine) input.send({
+					type: "PROGRESS",
+					io: mine,
+					bufferedMs
+				});
 			},
-			onError: (err) => {
-				if (!conn.generation.isCurrent(gen)) return;
-				reportAudioFailure(err.message);
+			onFailure: (message) => {
+				if (mine) input.send({
+					type: "IO_FAILED",
+					io: mine,
+					message
+				});
 			}
 		});
-		if (stale()) {
-			io.close().catch(() => {});
-			return;
+		if (signal.aborted) {
+			input.effects.release(io);
+			throw ABANDONED;
 		}
-		conn.voiceIO?.close().catch(() => {});
-		conn.voiceIO = io;
-		if (conn.preInitAudio.length > 0) {
-			for (const chunk of conn.preInitAudio) io.enqueue(chunk);
-			conn.preInitAudio = [];
+		mine = io;
+		return io;
+	}) },
+	guards: { 
+	/**
+	* Did the live path report this, or one it replaced?
+	*
+	* Identity rather than `generation.isCurrent(gen)`: two bring-ups inside a
+	* single connection share a generation, and the counter passed for the
+	* instance that had just been closed.
+	*/
+fromLiveIo: ({ context, event }) => (event.type === "PROGRESS" || event.type === "IO_FAILED") && context.io === event.io },
+	actions: {
+		rememberConfig: assign({ config: ({ context, event }) => event.type === "START" ? event.config : context.config }),
+		/** Hold a chunk that arrived too early, up to the cap. */
+		buffer: assign({ pending: ({ context, event }) => event.type === "CHUNK" && context.pending.length < MAX_BUFFERED_CHUNKS ? [...context.pending, event.chunk] : context.pending }),
+		/** Record a done that arrived too early. */
+		rememberDone: assign({ pendingDone: true }),
+		/** Answer it optimistically: with no audio pipeline there is nothing to wait for. */
+		listenNow: ({ context }) => context.effects.listen(),
+		/** Nothing buffered belongs to the next path. */
+		forgetBuffered: assign({
+			io: null,
+			pending: [],
+			pendingDone: false
+		}),
+		/** Releasing the path ends the turn it was playing — see `endTurn`. */
+		endTurn: ({ context }) => context.effects.endTurn(),
+		releaseIo: ({ context }) => {
+			if (context.io) context.effects.release(context.io);
+		}
+	}
+}).createMachine({
+	id: "audioPath",
+	context: ({ input }) => ({
+		effects: input,
+		io: null,
+		pending: [],
+		pendingDone: false,
+		config: null
+	}),
+	initial: "down",
+	on: {
+		CHUNK: { actions: "buffer" },
+		DONE: { actions: ["rememberDone", "listenNow"] },
+		TEARDOWN: ".down"
+	},
+	states: {
+		/**
+		* No audio path. Entered on every release, so its entry is the one place
+		* that ends the turn and drops what was buffered for a path that is gone.
+		*/
+		down: {
+			entry: ["endTurn", "forgetBuffered"],
+			on: { START: {
+				target: "starting",
+				actions: "rememberConfig"
+			} }
+		},
+		/**
+		* A bring-up is in flight.
+		*
+		* `START` is absent deliberately: that is the whole of what
+		* `audioSetupInFlight` said, and a second `config` frame arriving mid-grant
+		* is now declined by the position rather than by a flag whose owner had to
+		* be tracked.
+		*/
+		starting: { invoke: {
+			src: "bringUp",
+			input: ({ context, self }) => ({
+				effects: context.effects,
+				config: context.config ?? {
+					sampleRate: 0,
+					ttsSampleRate: 0
+				},
+				send: (event) => {
+					self.send(event);
+				}
+			}),
+			onDone: {
+				target: "up",
+				actions: [
+					({ context, event }) => {
+						for (const chunk of context.pending) event.output.enqueue(chunk);
+					},
+					assign({
+						io: ({ event }) => event.output,
+						pending: []
+					}),
+					({ context, event }) => {
+						context.effects.announceReady();
+						context.effects.micLive();
+						if (context.pendingDone) context.effects.settleWhenDrained(event.output);
+						else context.effects.listen();
+					},
+					assign({ pendingDone: false })
+				]
+			},
+			onError: {
+				target: "down",
+				actions: ({ context, event }) => {
+					context.effects.reportFailure(`Microphone access failed: ${errorMessage(event.error)}`);
+				}
+			}
+		} },
+		/**
+		* A live path. Its exit releases it, which covers all three ways out —
+		* teardown, a worklet death, and the repeated `config` frame that opens a
+		* replacement (the "defensive" close that used to sit inside the bring-up,
+		* where it could only run if the bring-up got that far).
+		*/
+		up: {
+			exit: "releaseIo",
+			on: {
+				START: {
+					target: "starting",
+					actions: "rememberConfig"
+				},
+				CHUNK: { actions: ({ context, event }) => context.io?.enqueue(event.chunk) },
+				DONE: { actions: ({ context }) => {
+					if (context.io) context.effects.settleWhenDrained(context.io);
+				} },
+				PROGRESS: {
+					guard: "fromLiveIo",
+					actions: ({ context, event }) => context.effects.reportProgress(event.bufferedMs)
+				},
+				IO_FAILED: {
+					guard: "fromLiveIo",
+					target: "down",
+					actions: ({ context, event }) => context.effects.reportFailure(event.message)
+				}
+			}
 		}
-		deps.sendJson({ type: "audio_ready" });
-		deps.updateState({ recording: true });
-		if (conn.preInitDone) {
-			conn.preInitDone = false;
-			deps.settleWhenAudioDrained(io);
-		} else deps.updateState(deps.agentState.apply({ type: "LISTEN" }));
-	} catch (err) {
-		if (stale()) return;
-		reportAudioFailure(`Microphone access failed: ${errorMessage(err)}`);
-	} finally {
-		if (conn.generation.isCurrent(gen)) conn.audioSetupInFlight = false;
 	}
+});
+/** Create the audio path for one browser session. */
+function createAudioPath(effects) {
+	const actor = createActor(audioPathMachine, { input: effects }).start();
+	return {
+		phase: () => actor.getSnapshot().value,
+		start: (config) => {
+			actor.send({
+				type: "START",
+				config
+			});
+		},
+		enqueue: (chunk) => {
+			actor.send({
+				type: "CHUNK",
+				chunk
+			});
+		},
+		done: () => {
+			actor.send({ type: "DONE" });
+		},
+		flush: () => actor.getSnapshot().context.io?.flush(),
+		teardown: () => {
+			actor.send({ type: "TEARDOWN" });
+		}
+	};
 }
 //#endregion
 //#region src/session-core-close.ts
@@ -544,7 +794,7 @@ function createHandshakeGuard(opts) {
 *
 * Split out of `session-core.ts`: this module owns the interpretation of
 * server→client frames (audio chunks + JSON {@link SessionEvent}s) and the
-* turn-boundary generation counters, while `session-core.ts` owns the state
+* turn-boundary epoch, 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.
 */
@@ -552,10 +802,6 @@ function createHandshakeGuard(opts) {
 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 `session.reset`.
@@ -587,7 +833,7 @@ function appendCapped(list, item, cap) {
 * `ConnState.turn`).
 */
 function createMessageHandlers(deps) {
-	const { getSnapshot, updateState, conn, agentState, cleanupAudio } = deps;
+	const { getSnapshot, updateState, conn, agentState, audio } = deps;
 	/** Monotonically increasing counter for custom events -- used by useEvent to deduplicate. */
 	let customEventSeq = 0;
 	/** Monotonically increasing counter for chat messages -- stable render keys
@@ -694,8 +940,7 @@ function createMessageHandlers(deps) {
 			error
 		}));
 		else {
-			cleanupAudio();
-			conn.generation.bump();
+			audio.teardown();
 			updateState({
 				...agentState.apply({
 					type: "FATAL",
@@ -752,12 +997,12 @@ function createMessageHandlers(deps) {
 				toListening();
 				break;
 			case "reply.cancelled":
-				bargeIn(conn);
+				bargeIn(conn, audio);
 				commitAgentTranscript();
 				toListening({ userTranscript: null });
 				break;
 			case "session.reset": {
-				bargeIn(conn);
+				bargeIn(conn, audio);
 				const next = agentState.apply({ type: "RESET" });
 				updateState(agentState.fatal() ? next : {
 					...CLEARED_SESSION_STATE,
@@ -802,34 +1047,18 @@ function createMessageHandlers(deps) {
 	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
 	function playAudioChunk(chunk) {
 		updateState(agentState.apply({ type: "SPEAK" }));
-		if (conn.voiceIO) conn.voiceIO.enqueue(chunk);
-		else if (conn.preInitAudio.length < MAX_PREINIT_AUDIO_CHUNKS) conn.preInitAudio.push(chunk);
-	}
-	/** See {@link MessageHandlers.settleWhenAudioDrained}. Captures
-	*  `conn.turn` so a completion (or failure) that lands after a turn
-	*  boundary — including an audio-path teardown — is discarded instead of
-	*  overwriting the newer turn's (or the dead session's) state. */
-	function settleWhenAudioDrained(io) {
-		const gen = conn.turn.current();
-		io.done().then(() => {
-			if (!conn.turn.isCurrent(gen)) return;
-			updateState(agentState.apply({ type: "LISTEN" }));
-		}).catch((err) => {
-			console.warn("Audio playback done failed:", err);
-		});
+		audio.enqueue(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 `conn.turn` to discard stale completions from interrupted turns.
+	*
+	* A path that is up waits for its queue to drain before going back to
+	* listening; one still coming up records the done and answers optimistically,
+	* then replays it once the buffered greeting has somewhere to go. Both arms
+	* live in `session-core-audio-state.ts`.
 	*/
 	function playAudioDone() {
-		const io = conn.voiceIO;
-		if (io) settleWhenAudioDrained(io);
-		else {
-			conn.preInitDone = true;
-			updateState(agentState.apply({ type: "LISTEN" }));
-		}
+		audio.done();
 	}
 	function handleMessage(data) {
 		if (data instanceof ArrayBuffer) {
@@ -865,10 +1094,7 @@ function createMessageHandlers(deps) {
 		}
 		handleEvent(msg);
 	}
-	return {
-		handleMessage,
-		settleWhenAudioDrained
-	};
+	return { handleMessage };
 }
 //#endregion
 //#region src/session-core-state.ts
@@ -1053,6 +1279,31 @@ function createSessionStateMachine() {
 	};
 }
 //#endregion
+//#region src/session-core-user-turn.ts
+/** Build the three push-to-talk edges. @internal */
+function createUserTurnActions(deps) {
+	return {
+		start() {
+			if (!deps.connected()) return;
+			const { state } = deps.snapshot();
+			if (state === "speaking" || state === "thinking") {
+				deps.bargeIn();
+				deps.updateState(deps.agentState.apply({ type: "LISTEN" }));
+			}
+			deps.sendJson({ type: "user_turn_start" });
+		},
+		commit() {
+			if (!deps.connected()) return;
+			deps.sendJson({ type: "user_turn_commit" });
+		},
+		clear() {
+			if (!deps.connected()) return;
+			deps.updateState({ userTranscript: null });
+			deps.sendJson({ type: "user_turn_clear" });
+		}
+	};
+}
+//#endregion
 //#region src/session-core.ts
 /**
 * Framework-agnostic voice session core.
@@ -1148,23 +1399,10 @@ function createBrowserSession(options) {
 	const conn = {
 		ws: null,
 		retiredByServer: false,
-		voiceIO: null,
-		audioSetupInFlight: false,
-		generation: createEpoch(),
-		turn: createEpoch(),
-		preInitAudio: [],
-		preInitDone: false
+		turn: createEpoch()
 	};
 	let connectionController = null;
 	const dialer = createDialer(options);
-	function cleanupAudio() {
-		conn.audioSetupInFlight = false;
-		conn.turn.bump();
-		conn.voiceIO?.close().catch(() => {});
-		conn.voiceIO = null;
-		conn.preInitAudio = [];
-		conn.preInitDone = false;
-	}
 	function resetState() {
 		updateState(CLEARED_SESSION_STATE);
 	}
@@ -1187,26 +1425,32 @@ function createBrowserSession(options) {
 		if (ws.bufferedAmount > MIC_SEND_MAX_BUFFERED_BYTES) return;
 		ws.send(bytes);
 	}
-	const { handleMessage, settleWhenAudioDrained } = createMessageHandlers({
-		getSnapshot,
-		updateState,
+	/**
+	* The microphone, the worklets and the buffer in front of them, as a
+	* statechart — see `session-core-audio-state.ts`, which carries what the
+	* in-flight latch, the generation epoch and the two pre-init fields on
+	* `ConnState` cost. `session-core-audio-effects.ts` is the other half: every
+	* frame and snapshot write the machine decides on but cannot make.
+	*/
+	const audio = createAudioPath(createAudioEffects({
 		conn,
+		updateState,
 		agentState,
-		cleanupAudio
-	});
-	const audioDeps = {
 		sendJson,
-		sendAudio,
+		sendAudio
+	}));
+	const { handleMessage } = createMessageHandlers({
+		getSnapshot,
 		updateState,
+		conn,
 		agentState,
-		settleWhenAudioDrained,
-		cleanupAudio
-	};
+		audio
+	});
 	/** Abort the in-flight connection and release audio + WebSocket resources. */
 	function teardownConnection() {
 		connectionController?.abort();
 		connectionController = null;
-		cleanupAudio();
+		audio.teardown();
 		conn.ws?.close();
 		conn.ws = null;
 	}
@@ -1224,7 +1468,7 @@ function createBrowserSession(options) {
 	function onServerConfig(config) {
 		dialer.configured(config.sid);
 		if (config.sid) options.onSessionId?.(config.sid);
-		initAudioCapture(conn, config, audioDeps);
+		audio.start(config);
 	}
 	function connect(opts) {
 		if (opts?.signal?.aborted) {
@@ -1234,7 +1478,6 @@ function createBrowserSession(options) {
 		updateState(agentState.apply({ type: "CONNECT" }));
 		loadAudioModules().catch(() => {});
 		teardownConnection();
-		conn.generation.bump();
 		conn.retiredByServer = false;
 		const controller = new AbortController();
 		connectionController = controller;
@@ -1248,15 +1491,14 @@ function createBrowserSession(options) {
 			socket,
 			signal: sig,
 			onRetry: () => {
-				cleanupAudio();
-				conn.generation.bump();
+				audio.teardown();
 				updateState({
 					...agentState.apply({ type: "CONNECT" }),
 					recording: false
 				});
 			},
 			onExhausted: () => {
-				cleanupAudio();
+				audio.teardown();
 				controller.abort();
 				socket.close();
 				conn.ws = null;
@@ -1285,9 +1527,8 @@ function createBrowserSession(options) {
 		socket.addEventListener("close", (event) => {
 			if (sig.aborted) return;
 			handshake.disarm();
-			cleanupAudio();
+			audio.teardown();
 			if (!(conn.retiredByServer || agentState.fatal()) && reconnectPending(socket)) {
-				conn.generation.bump();
 				socketErrored = false;
 				updateState({
 					...agentState.apply({ type: "CONNECT" }),
@@ -1314,12 +1555,20 @@ function createBrowserSession(options) {
 	}
 	function cancel() {
 		if (!openSocket()) return;
-		bargeIn(conn);
+		bargeIn(conn, audio);
 		updateState(agentState.apply({ type: "LISTEN" }));
 		sendJson({ type: "cancel" });
 	}
+	const userTurn = createUserTurnActions({
+		snapshot: () => currentSnapshot,
+		connected: () => openSocket() !== null,
+		bargeIn: () => bargeIn(conn, audio),
+		agentState,
+		updateState,
+		sendJson
+	});
 	function reset() {
-		bargeIn(conn);
+		bargeIn(conn, audio);
 		if (openSocket()) {
 			sendJson({ type: "reset" });
 			return;
@@ -1367,6 +1616,7 @@ function createBrowserSession(options) {
 		subscribe,
 		connect,
 		cancel,
+		userTurn: Object.freeze(userTurn),
 		resetState,
 		reset,
 		disconnect,