@alexkroman1/aai-ui 0.12.3 → 0.14.0

package/dist/session-D9jM5-TF.js

@@ -0,0 +1,2140 @@
+import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
+import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-C7fQrioM.js";
+import { MIC_SEND_MAX_BUFFERED_BYTES } from "./types.js";
+import { SessionEventSchema, errorMessage, safeJsonParse } from "@alexkroman1/aai";
+import { SESSION_AUTH_PROTOCOL_PREFIX, SESSION_PROTOCOL, lenientParse } from "@alexkroman1/aai/protocol";
+import { CLIENT_ID_RE, MAX_CLIENT_MESSAGES, RESUME_ID_RE, WS_OPEN, createEpoch, toArgsRecord } from "@alexkroman1/aai/internal";
+import { omitUndefined } from "@alexkroman1/aai/utils";
+import { and, assign, createActor, fromPromise, not, setup, stateIn } from "xstate";
+import ReconnectingWebSocket from "partysocket/ws";
+//#region src/_web-storage.ts
+/**
+* The store, or nothing.
+*
+* Not exported: a caller that reaches for the store itself has stepped outside
+* the guard, which is the whole point of this module.
+*/
+function storeFor(kind) {
+	return kind === "local" ? globalThis.localStorage : globalThis.sessionStorage;
+}
+/** The stored value, or undefined — for a missing entry and an absent store alike. */
+function storageGet(kind, key) {
+	try {
+		return storeFor(kind)?.getItem(key) ?? void 0;
+	} catch {
+		return;
+	}
+}
+/** Remember a value. A store that refuses is a no-op, never a throw. */
+function storageSet(kind, key, value) {
+	try {
+		storeFor(kind)?.setItem(key, value);
+	} catch {}
+}
+/** Forget a value. Nothing stored and no store are the same outcome. */
+function storageRemove(kind, key) {
+	try {
+		storeFor(kind)?.removeItem(key);
+	} catch {}
+}
+/**
+* A storage key namespaced by a URL.
+*
+* `target` is resolved against the document, so a relative path ("./", the
+* default-client case) and the absolute form of the same agent agree on one
+* key.
+*
+* @param prefix - The owning module's namespace, e.g. `"aai:session:"`.
+* @param target - What to resolve — an agent's `platformUrl`, or `"./"` for the
+*   page's own directory.
+*/
+function urlSlot(prefix, target) {
+	try {
+		return `${prefix}${new URL(target, globalThis.location?.href).href}`;
+	} catch {
+		return `${prefix}${target}`;
+	}
+}
+//#endregion
+//#region src/client-identity.ts
+/**
+* Who this browser is to an agent: the id `mountClient({ client: "auto" })`
+* sends as `?client=`, the inbox HOLDER id of this tab, and the
+* `session.identity` handle both are read from.
+*
+* ## Why the SDK mints the client id
+*
+* A client id is what a tool hands a workflow run (`sessionClientId(ctx)`) so
+* the run's `stepNotifyClient` can reach this browser AFTER the session that
+* started it has closed — a reminder due tomorrow is delivered to whoever holds
+* the id tomorrow. So it must be the SAME id on the session socket and on the
+* inbox socket, and it must outlive the tab. Every app that wanted a reminder in
+* a browser wrote the same thirty lines (a `localStorage` read, a validity
+* check, a fallback for private mode) and got the second half of this module
+* wrong: see the holder below.
+*
+* - **`localStorage`, keyed by the agent's URL** (`_web-storage.ts`'s rule). Two
+*   agents served from one origin — every deployed agent, at `/:slug/` — must
+*   not share one: the id is the ONLY credential for a client's durable
+*   conversation (`VoiceSessionOptions.client`), so agent A's server, which
+*   receives it, could otherwise present it to agent B and read B's history.
+* - **Unguessable**: 128 random bits, from `crypto.getRandomValues` — which,
+*   unlike `crypto.randomUUID`, exists outside a secure context, and `aai dev`
+*   on a LAN address is plain `http:`.
+* - **Private mode** (storage throws or is absent) degrades to an id for THIS
+*   TAB, held in memory: the session and inbox still agree, a reminder set in
+*   the tab reaches the tab, and nothing outlives it.
+*
+* ## Why the holder is per TAB, not per browser
+*
+* The inbox keeps one socket per (client, holder) pair, and the same pair again
+* REPLACES the old socket — right for a device back from a Wi-Fi drop, whose old
+* socket is half-dead. Every tab of a browser shares `localStorage`, so an app
+* that used the browser-wide id as the holder had two tabs presenting the same
+* pair: each connect knocked the other tab off, the other reconnected on its
+* backoff and knocked this one off, about once a second, forever. The holder is
+* the browser id plus a suffix minted once per PAGE LOAD, so tabs coexist as
+* holders of one client and every one of them is offered the notice.
+*
+* @module
+*/
+const PREFIX$1 = "aai:client:";
+/** Lowercase hex of `bytes` random bytes. */
+function randomHex(bytes) {
+	const buf = crypto.getRandomValues(new Uint8Array(bytes));
+	return Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+* This page load's suffix: minted once per JS realm, which is once per tab per
+* load. Not stored anywhere — that is the point (see the module doc).
+*/
+const TAB = randomHex(4);
+/**
+* Ids already resolved in this realm, per storage slot. It is what makes a
+* private-mode id stable for the tab (nothing else remembers it) and saves a
+* storage read on every connection attempt otherwise.
+*/
+const minted = /* @__PURE__ */ new Map();
+/**
+* This browser's stable client id for the agent at `platformUrl` —
+* `browser-<32 hex>`, minted once and kept in `localStorage`. The id
+* `mountClient({ client: "auto" })` sends; call it yourself to compose it, e.g.
+* a page joined to a speaker that sends the speaker's id instead:
+*
+* @example
+* ```ts
+* import { browserClientId, mountClient } from "@alexkroman1/aai-ui";
+*
+* declare function linkedSpeaker(): string | undefined;
+*
+* mountClient({ client: () => linkedSpeaker() ?? browserClientId() });
+* ```
+*
+* A stored value that is not a valid client id (letters, digits, `-`, `_`, at
+* most 64) is replaced. Where storage is unavailable the id lasts for this tab.
+*
+* @param platformUrl - The agent's base URL; the id is per agent. Defaults to
+*   the page's own, which is `mountClient()`'s default too.
+* @returns The id — the same one on every call for the same agent.
+*
+* @public
+*/
+function browserClientId(platformUrl = pageBaseUrl()) {
+	const key = urlSlot(PREFIX$1, platformUrl);
+	const known = minted.get(key);
+	if (known) return known;
+	const stored = storageGet("local", key);
+	const id = stored && CLIENT_ID_RE.test(stored) ? stored : `browser-${randomHex(16)}`;
+	if (id !== stored) storageSet("local", key, id);
+	minted.set(key, id);
+	return id;
+}
+/**
+* This TAB's inbox holder id for the agent at `platformUrl`: the browser id
+* plus a per-page-load suffix. Never the browser id alone — see the module doc
+* for the two tabs that knocked each other off once a second.
+*
+* @internal
+*/
+function inboxHolderId(platformUrl) {
+	return `${browserClientId(platformUrl)}-${TAB}`;
+}
+/** The client option as the dialer reads it: `"auto"` resolved, everything else as given. */
+function resolveClientOption(client, platformUrl) {
+	return client === "auto" ? () => browserClientId(platformUrl) : client;
+}
+/** A string-or-getter option resolved NOW, trimmed; an empty answer is none. */
+function resolveReported(value) {
+	const trimmed = (typeof value === "function" ? value() : value)?.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+/**
+* Build a session's {@link SessionIdentity}. `sessionId` and `ticket` are the
+* dialer's (read through `source`, which may answer nothing): it owns the id
+* because it sees every `config` frame, `end()` and `resume()`, and the ticket
+* because it holds the `token` option and the server's `client-config` latch.
+*/
+function createSessionIdentity(options, source) {
+	const client = resolveClientOption(options.client, options.platformUrl);
+	return Object.freeze({
+		platformUrl: options.platformUrl,
+		clientId: () => resolveReported(client),
+		holderId: () => inboxHolderId(options.platformUrl),
+		sessionId: () => source()?.sessionId(),
+		ticket: () => source()?.ticket()
+	});
+}
+//#endregion
+//#region src/session/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/index.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, preConnect) {
+	const pre = await preConnect ?? void 0;
+	try {
+		return await openVoiceIO(config, callbacks, pre);
+	} catch (err) {
+		pre?.close();
+		throw err;
+	}
+}
+async function openVoiceIO(config, callbacks, pre) {
+	const [{ createVoiceIO }, captureWorklet, playbackWorklet] = await loadAudioModules();
+	return createVoiceIO({
+		preConnect: pre,
+		onPreConnectAudio: callbacks.onPreConnectAudio,
+		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/types.ts
+/**
+* The two liveness fields at rest.
+*
+* `running` and `recording` ride with almost every state transition and were
+* spread as a pair of literals at seven sites across three modules — the same
+* shape `session/state.ts` folded `state` and `error` out of, one field
+* short. Naming it relates them: a transition that ends the call says so once,
+* and a reader looking for "what stops the mic" finds one symbol rather than a
+* grep.
+*
+* It is deliberately NOT the whole snapshot patch — a transition still supplies
+* its own `agentState.apply(...)` projection beside this.
+*/
+const STOPPED = {
+	running: false,
+	recording: false
+};
+/**
+* A turn boundary: end the current turn and settle whatever it was playing.
+*
+* The two calls are one fact and were written out at four sites — `cancel()`
+* and `reset()` here, `reply.cancelled` and `session.reset` on the server side
+* — where the pair is load-bearing in both halves. The bump stops a stale drain
+* continuation from stamping `"listening"` over a state the session has since
+* moved to; the flush settles the interrupted turn's `done()` so it cannot
+* strand.
+*
+* Two further sites bump WITHOUT flushing (`cleanupAudio`, a committed user
+* transcript) and stay spelled out, which is the point of naming this one: a
+* bump on its own now reads as a deliberate choice rather than a forgotten
+* flush.
+*/
+function bargeIn(conn, audio) {
+	conn.turn.bump();
+	audio.flush();
+}
+//#endregion
+//#region src/session/audio-effects.ts
+/** Build the effects for one session's audio path. */
+function createAudioEffects(deps) {
+	const { conn, updateState, agentState, sendJson, mic, preConnect } = 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: (config, callbacks) => (deps.openAudioPath ?? openAudioPath)(config, callbacks, preConnect.take()),
+		sendMicAudio: (pcm16) => {
+			try {
+				mic.sendAudio(pcm16);
+			} catch {
+				console.debug("[aai-ui] sendAudio dropped: connection closed");
+			}
+		},
+		sendPreConnectAudio: (chunks) => {
+			try {
+				mic.sendBuffered(chunks);
+			} catch {
+				console.debug("[aai-ui] pre-connect audio 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/audio-state.ts
+/**
+* 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
+*
+* 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.
+*/
+/**
+* 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).
+*/
+const MAX_BUFFERED_CHUNKS = 100;
+/**
+* The rejection a bring-up abandons itself with.
+*
+* 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".
+*/
+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),
+			onPreConnectAudio: (chunks) => input.effects.sendPreConnectAudio(chunks),
+			onProgress: (bufferedMs) => {
+				if (mine) input.send({
+					type: "PROGRESS",
+					io: mine,
+					bufferedMs
+				});
+			},
+			onFailure: (message) => {
+				if (mine) input.send({
+					type: "IO_FAILED",
+					io: mine,
+					message
+				});
+			}
+		});
+		if (signal.aborted) {
+			input.effects.release(io);
+			throw ABANDONED;
+		}
+		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)
+				}
+			}
+		}
+	}
+});
+/** 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/close.ts
+/**
+* What a socket's CLOSE means to the caller.
+*
+* One decision, in its own module because `session/browser-session.ts` is at its length cap
+* and because the decision is worth reading on its own: which endings are
+* ordinary, and which carry something the user has to be told.
+*
+* @module
+*/
+/**
+* The one close code whose reason is never worth showing.
+*
+* `1000` is a deliberate, successful close — the caller hanging up, or the
+* server retiring a session it finished with. A browser reports a socket that
+* closed with no status as `1005`, which carries no reason either, so testing
+* for text is enough to exclude it.
+*/
+const NORMAL_CLOSE = 1e3;
+/**
+* What to REPORT for a socket that closed for good, or null for an ordinary end.
+*
+* A sentence the peer wrote beats one this file invented. A guest that cannot
+* build its runtime closes 1011 with the remedy already in it — "Anthropic LLM:
+* missing API key. Set ANTHROPIC_API_KEY in the agent env." — and this handler
+* used to discard `event.reason` entirely, so the one thing a misconfigured
+* deployment needed to be told surfaced as "WebSocket connection error", or as a
+* plain disconnect with nothing at all. Measured against a deployed agent with no
+* provider key.
+*
+* A NORMAL close carries no reason worth showing (1000 is the caller hanging up
+* or the server retiring a finished session; a browser reports a status-less
+* close as 1005, which has no reason either), so the two ordinary endings are
+* untouched.
+*/
+function closeFailure(event, socketErrored) {
+	const refusal = event.reason.trim();
+	if (refusal !== "" && event.code !== NORMAL_CLOSE) return refusal;
+	return socketErrored ? "WebSocket connection error" : null;
+}
+//#endregion
+//#region src/session/reconnect.ts
+/**
+* Automatic reconnection for the browser session socket, built on
+* partysocket's `ReconnectingWebSocket`. Kept out of `session/browser-session.ts` so
+* the state machine there reads as protocol logic, not socket plumbing.
+*/
+/**
+* Backoff for automatic reconnects after an unexpected close (partysocket):
+* exponential from 1s, capped at 15s, giving up after 10 attempts. Applies
+* only to the default socket implementation — an injected
+* `options.WebSocket` (tests) never reconnects on its own.
+*/
+const RECONNECT_OPTIONS = {
+	minReconnectionDelay: 1e3,
+	maxReconnectionDelay: 15e3,
+	reconnectionDelayGrowFactor: 2,
+	maxRetries: 10
+};
+/**
+* Open partysocket's reconnecting WebSocket. The URL and the subprotocols are
+* *providers*, re-evaluated on every attempt (async supported), so each retry
+* picks up the current broker-named endpoint, resume URL and session ticket
+* rather than the ones the session started with. partysocket calls the URL
+* provider first and the protocols provider straight after it, in the same
+* tick, for each attempt.
+*/
+function openReconnectingSocket(urlProvider, protocolsProvider) {
+	return new ReconnectingWebSocket(urlProvider, protocolsProvider, RECONNECT_OPTIONS);
+}
+/**
+* Force a fresh connection attempt on a reconnecting socket, reporting
+* whether it was one. Used for a failure partysocket cannot see: a socket it
+* considers open and healthy, whose peer never completed OUR handshake.
+* Returns false for an injected `options.WebSocket` (tests), which has no
+* reconnect machinery — the caller then treats the failure as terminal.
+*/
+function forceReconnect(socket) {
+	if (!(socket instanceof ReconnectingWebSocket)) return false;
+	socket.reconnect();
+	return true;
+}
+/**
+* True while `socket` is a reconnecting socket that will retry after the
+* close event currently being handled. partysocket schedules the retry
+* *before* dispatching `close`, so `retryCount` already names the attempt
+* just scheduled — at `maxRetries` it has given up.
+*/
+function reconnectPending(socket) {
+	return socket instanceof ReconnectingWebSocket && socket.shouldReconnect && socket.retryCount < RECONNECT_OPTIONS.maxRetries;
+}
+//#endregion
+//#region src/session/resume-store.ts
+/**
+* Where a session id survives a page RELOAD.
+*
+* The id is what `?sessionId=` presents on reconnect, and it is the key the
+* agent's slot state and event log live under — so a reload that cannot produce
+* it starts a brand-new session, and a UI driven by `useAgentState` comes back
+* empty even though the agent still holds the cart. The server side of the
+* reconstitution was already built (`pushStateSnapshot` force-pushes the
+* projection after hydration on every start, `state.updated` lands in
+* `agentState`); what was missing is that nothing in the browser remembered the
+* id across a reload. `onSessionId`/`resumeSessionId` let a client wire it by
+* hand and exactly one of fourteen templates did, which is the shape of a
+* default in the wrong place.
+*
+* **`sessionStorage`, deliberately, and this is the opposite call from the
+* studio's session token.** A reload and a same-tab navigation survive it; a new
+* tab and a visit tomorrow do not, which is what we want here rather than a
+* limitation: presenting a day-old id suppresses the greeting
+* (`parseWsUpgradeParams` keys that off the id's mere presence) and rejoins a
+* conversation whose context is long gone. The studio token is a credential
+* whose value is not being asked to sign out; this is a pointer into a live call.
+*
+* Keyed by the agent's own URL, so two agents served from one origin — which is
+* every deployed agent, at `/:slug/` — cannot inherit each other's session.
+*
+* Every access is guarded, and the guard lives in `_web-storage.ts`: a session
+* that cannot be remembered must degrade to today's behaviour rather than
+* failing to start.
+*/
+const PREFIX = "aai:session:";
+/** One agent's slot in storage. */
+function keyFor(platformUrl) {
+	return urlSlot(PREFIX, platformUrl);
+}
+/** The stored session id for this agent, or undefined. @internal */
+function readStoredSessionId(platformUrl) {
+	return storageGet("session", keyFor(platformUrl));
+}
+/** Remember this agent's session id for the next load. @internal */
+function writeStoredSessionId(platformUrl, sessionId) {
+	storageSet("session", keyFor(platformUrl), sessionId);
+}
+/**
+* Forget it, so the next load is a NEW session.
+*
+* Called from `end()`, which is the clear-and-forget the "New Conversation"
+* button runs: leaving the id behind there would have the next load rejoin the
+* conversation the user just discarded, greeting suppressed.
+*
+* @internal
+*/
+function clearStoredSessionId(platformUrl) {
+	storageRemove("session", keyFor(platformUrl));
+}
+const TICKET_PREFIX = "aai:session-ticket:";
+/**
+* The last session ticket this agent's `client-config` issued — beside the id
+* and for its reason: on the managed platform a ticket is BOUND to its session,
+* and presenting it (`SESSION_TICKET_HEADER`) is what makes the broker re-mint
+* for that session rather than a new one, so a reload that lost it cannot
+* resume. As sensitive as the id it stands beside, and stored the same way.
+*
+* @internal
+*/
+function readStoredTicket(platformUrl) {
+	return storageGet("session", urlSlot(TICKET_PREFIX, platformUrl));
+}
+/** Remember the last server-issued ticket. @internal */
+function writeStoredTicket(platformUrl, ticket) {
+	storageSet("session", urlSlot(TICKET_PREFIX, platformUrl), ticket);
+}
+/** Forget it, with the session it was for. @internal */
+function clearStoredTicket(platformUrl) {
+	storageRemove("session", urlSlot(TICKET_PREFIX, platformUrl));
+}
+//#endregion
+//#region src/session/ticket.ts
+/**
+* The session ticket one connection attempt presents — `VoiceSessionOptions.token`,
+* else the `sessionToken` a server's `client-config` issued.
+*
+* A browser cannot set headers on a WebSocket, so the ticket rides the
+* `Sec-WebSocket-Protocol` list as `aai.auth.<ticket>`, offered AFTER the plain
+* `aai.session` protocol: a browser fails any handshake whose response selects
+* none of its offers, and the server (`selectSessionProtocol` in
+* `@alexkroman1/aai-runtime/auth`) selects the plain one so the ticket is never
+* echoed back. A server older than tickets selects the first offer, which is
+* the plain one too, so offering a ticket never fails a handshake.
+*
+* A value that is not a valid subprotocol token (RFC 6455 §4.1 — an HTTP
+* token) would make `new WebSocket` throw, so it travels as `?token=` instead,
+* the server's fallback. A minted ticket is base64url with one dot, and so is a
+* JWT: neither takes that path.
+*/
+const HTTP_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function trimmed(value) {
+	const t = value?.trim();
+	return t === "" ? void 0 : t;
+}
+/**
+* Ask the `token` option for THIS attempt's ticket. A getter that throws or
+* rejects yields none — the attempt still dials, and a server that requires a
+* ticket refuses it with a reason the session reports, rather than the attempt
+* failing before a socket exists (partysocket reports a provider failure as an
+* `error` with no `close`, which would leave the session on "connecting").
+*/
+async function resolveSessionToken(option, attempt) {
+	if (typeof option !== "function") return trimmed(option);
+	try {
+		return trimmed(await option(attempt));
+	} catch (err) {
+		console.warn("session-core: the `token` getter failed; dialing without a ticket", err);
+		return;
+	}
+}
+/**
+* The same, for an injected `WebSocket` constructor: that path opens its socket
+* synchronously, so an asynchronous getter cannot be awaited there.
+*/
+function resolveSessionTokenSync(option, attempt) {
+	if (typeof option !== "function") return trimmed(option);
+	const value = option(attempt);
+	if (typeof value !== "string" && value !== void 0) throw new TypeError("VoiceSessionOptions.token: an injected `WebSocket` opens synchronously, so its `token` getter must return a string, not a Promise");
+	return trimmed(value);
+}
+/** How `token` travels on one attempt; nothing at all when there is no ticket. */
+function ticketCarriage(token) {
+	if (token === void 0) return {};
+	const protocol = `${SESSION_AUTH_PROTOCOL_PREFIX}${token}`;
+	if (!HTTP_TOKEN.test(protocol)) return { queryToken: token };
+	return { protocols: [SESSION_PROTOCOL, protocol] };
+}
+//#endregion
+//#region src/session/url.ts
+/** Build the session WebSocket URL from the platform URL and resume state. */
+function buildWsUrl(platformUrl, sessionId, report = {}) {
+	return applyResumeParams(buildAgentUrl(platformUrl, "websocket"), sessionId, report);
+}
+/**
+* Turn a broker-provided session URL (`sessionUrl` from `GET client-config`
+* — the agent's live sandbox endpoint) into this attempt's connect URL.
+*/
+function buildBrokeredWsUrl(sessionUrl, sessionId, report = {}) {
+	return applyResumeParams(new URL(sessionUrl), sessionId, report);
+}
+const WS_PROTOCOLS = {
+	"https:": "wss:",
+	"http:": "ws:"
+};
+function applyResumeParams(wsUrl, sessionId, report) {
+	wsUrl.protocol = WS_PROTOCOLS[wsUrl.protocol] ?? wsUrl.protocol;
+	if (sessionId) wsUrl.searchParams.set("sessionId", sessionId);
+	if (report.location) wsUrl.searchParams.set("location", report.location);
+	if (report.phone) wsUrl.searchParams.set("phone", report.phone);
+	if (report.client) wsUrl.searchParams.set("client", report.client);
+	return wsUrl;
+}
+//#endregion
+//#region src/session/dial.ts
+/**
+* How the next connection attempt is DIALLED, and the resume identity it dials
+* with.
+*
+* Split out of `session/browser-session.ts` at the 500-line cap, along the seam that file
+* already established when it moved socket plumbing into
+* `session/reconnect.ts`: the state machine there reads as protocol logic,
+* and this is the address it sends it to. What makes it one module rather than
+* three extracted functions is that the three pieces of mutable state involved —
+* the session id, whether this connection has ever completed a handshake, and
+* whether the server is a broker — are read by nothing else in the core, and
+* every one of them is only meaningful in the sentence "the URL for the next
+* attempt".
+*/
+/** `url` with the `?token=` fallback applied when the ticket rides the URL. */
+function withQueryToken(url, carriage) {
+	if (carriage.queryToken !== void 0) url.searchParams.set("token", carriage.queryToken);
+	return url.toString();
+}
+/**
+* @param onSessionId - Told whenever the CONFIRMED id changes (a `config` frame
+*   with a new id, `forget()`), so the session can notify `useSessionId()`
+*   even when no snapshot field moved with it.
+* @internal
+*/
+function createDialer(options, onSessionId) {
+	/**
+	* The session ID to resume: seeded from `options.resumeSessionId`, else from
+	* what a previous LOAD of this page stored, then kept current from every
+	* `config` frame. Reconnect URLs carry it as `?sessionId=<id>` so the server
+	* re-registers the SAME session id — that key is what the session's slot state
+	* and event log live under, so an attempt that omits it gets a fresh session
+	* with none of the agent's context.
+	*
+	* Reading it from storage is what makes a page RELOAD resume, and so what makes
+	* the server's `syncState` push reach a UI that would otherwise come back
+	* empty. See `session/resume-store.ts`.
+	*/
+	let sessionId = options.resumeSessionId ?? readStoredSessionId(options.platformUrl);
+	/**
+	* Whether `platformUrl`'s `client-config` says anything per ATTEMPT: a
+	* `sessionUrl` (a broker) or a `sessionToken` (a server minting its own
+	* client's tickets — `aai dev` with `AAI_SESSION_SECRET`). A server does or it
+	* doesn't — it never flips mid-session — so once one that says neither is
+	* observed, later reconnects skip the `client-config` re-fetch that would only
+	* fall through to `buildWsUrl` (every reconnect on `aai dev` / self-hosted
+	* otherwise pays a wasted GET). `undefined` until the first fetch settles.
+	*/
+	let configPerAttempt;
+	/**
+	* The last ticket this server's `client-config` issued, presented on the next
+	* lookup that RESUMES (`SESSION_TICKET_HEADER`). On the managed platform a
+	* ticket is bound to its session and possession is the resume credential, so
+	* it is stored beside the id: a reload that lost it would start over.
+	*/
+	let serverTicket = readStoredTicket(options.platformUrl);
+	/** What the last `config` frame said — see `Dialer.sessionId`. */
+	let confirmed;
+	function confirm(sid) {
+		if (sid === confirmed) return;
+		confirmed = sid;
+		onSessionId?.();
+	}
+	/**
+	* This attempt's `?location=`, `?phone=` and `?client=`, resolved NOW: a
+	* getter is asked on every attempt so a UI that changes one (a settings
+	* field) is heard on the next reconnect without a remount. Trimmed; an empty
+	* answer is none.
+	*/
+	function report() {
+		return {
+			location: resolveReported(options.location),
+			phone: resolveReported(options.phone),
+			client: resolveReported(options.client)
+		};
+	}
+	/**
+	* The WebSocket URL and subprotocols for the *next* connection attempt.
+	* Evaluated per attempt (partysocket takes async URL and protocol providers):
+	*
+	* - `GET client-config` is re-fetched every attempt. When it names a
+	*   `sessionUrl` — the platform's broker pointing at the agent's live sandbox
+	*   — the session connects DIRECTLY there. The URL changes when the sandbox is
+	*   replaced (idle eviction, redeploy), which is exactly when a reconnect
+	*   happens, so per-attempt brokering is what makes reconnects land on the
+	*   replacement. Without one (`aai dev`, older servers), the same-origin
+	*   `websocket` path is used.
+	* - Once the first `config` arrives, every reconnect carries `?sessionId=<id>`
+	*   and the server resumes the SAME session (id, tool state) instead of minting
+	*   a new one.
+	* - The session ticket (`session/ticket.ts`) is the `token` option's,
+	*   asked for THIS attempt, else the `sessionToken` this attempt's
+	*   `client-config` issued — to a lookup that presented the last one when
+	*   the attempt resumes, so a broker binding tickets to sessions re-mints for
+	*   the same session. A ticket bound to a session opens THAT session, so if
+	*   the broker could not re-mint, the server starts a new one and its
+	*   `config` frame says which.
+	*/
+	async function resolveAttempt() {
+		const ownToken = resolveSessionToken(options.token, { sessionId });
+		const presented = sessionId === void 0 ? void 0 : serverTicket;
+		const cfg = configPerAttempt === false ? null : await loadClientConfig(options.platformUrl, void 0, presented);
+		if (cfg) configPerAttempt = cfg.sessionUrl !== void 0 || cfg.sessionToken !== void 0;
+		const own = await ownToken;
+		if (own === void 0 && cfg?.sessionToken !== void 0) {
+			serverTicket = cfg.sessionToken;
+			writeStoredTicket(options.platformUrl, serverTicket);
+		}
+		const carriage = ticketCarriage(own ?? cfg?.sessionToken);
+		return {
+			url: withQueryToken(cfg?.sessionUrl ? buildBrokeredWsUrl(cfg.sessionUrl, sessionId, report()) : buildWsUrl(options.platformUrl, sessionId, report()), carriage),
+			protocols: carriage.protocols
+		};
+	}
+	/**
+	* The attempt partysocket is dialling. It calls its URL and protocol providers
+	* back to back for each attempt and awaits them together, so the URL provider
+	* STARTS the attempt and the protocol provider reads that same one: a ticket
+	* and the address it was fetched beside belong to one attempt.
+	*/
+	let current;
+	return {
+		open: () => {
+			if (options.WebSocket) {
+				const carriage = ticketCarriage(resolveSessionTokenSync(options.token, { sessionId }));
+				const target = withQueryToken(buildWsUrl(options.platformUrl, sessionId, report()), carriage);
+				return carriage.protocols ? new options.WebSocket(target, carriage.protocols) : new options.WebSocket(target);
+			}
+			return openReconnectingSocket(async () => {
+				current = resolveAttempt();
+				return (await current).url;
+			}, async () => (await (current ?? resolveAttempt())).protocols ?? null);
+		},
+		configured: (sid) => {
+			sessionId = sid;
+			writeStoredSessionId(options.platformUrl, sid);
+			confirm(sid);
+		},
+		adopt: (sid) => {
+			sessionId = sid;
+			writeStoredSessionId(options.platformUrl, sid);
+		},
+		forget: () => {
+			sessionId = void 0;
+			clearStoredSessionId(options.platformUrl);
+			serverTicket = void 0;
+			clearStoredTicket(options.platformUrl);
+			confirm(void 0);
+		},
+		sessionId: () => confirmed,
+		ticket: () => {
+			if (options.token !== void 0) return typeof options.token === "function" ? resolveSessionToken(options.token, { sessionId: void 0 }) : resolveSessionTokenSync(options.token, { sessionId: void 0 });
+			if (configPerAttempt === false) return;
+			return loadClientConfig(options.platformUrl).then((cfg) => {
+				if (cfg) configPerAttempt = cfg.sessionUrl !== void 0 || cfg.sessionToken !== void 0;
+				return cfg?.sessionToken;
+			});
+		}
+	};
+}
+//#endregion
+//#region src/session/handshake.ts
+/** What the session reports once the budget below is spent. */
+const HANDSHAKE_ERROR = {
+	code: "connection",
+	message: "Agent did not complete the session handshake",
+	fatal: false
+};
+/** How long an OPEN socket may go without a `config` frame. */
+const HANDSHAKE_TIMEOUT_MS = 1e4;
+/**
+* How many consecutive handshake timeouts to ride out before giving up.
+*
+* `forceReconnect` restarts partysocket's own retry budget, so this is the
+* budget for this failure mode — without one, a permanently wedged peer would
+* be re-dialed every ~10s forever, which is the unbounded retry loop
+* `RECONNECT_OPTIONS.maxRetries` exists to prevent.
+*
+* CONSECUTIVE is the whole of it, and only `succeeded()` says so — see its doc.
+*/
+const MAX_HANDSHAKE_TIMEOUTS = 3;
+/**
+* Watch one connection's handshake.
+*
+* `onRetry` fires when a timed-out attempt has been re-dialed (the sandbox
+* behind the endpoint may have been replaced, and the URL provider re-brokers
+* on the next attempt); `onExhausted` when the budget is spent, or when the
+* socket has no reconnect machinery at all (an injected `options.WebSocket`).
+*
+* @internal
+*/
+function createHandshakeGuard(opts) {
+	let timer;
+	let timeouts = 0;
+	function disarm() {
+		if (timer === void 0) return;
+		clearTimeout(timer);
+		timer = void 0;
+	}
+	function fire() {
+		timer = void 0;
+		timeouts += 1;
+		if (timeouts < MAX_HANDSHAKE_TIMEOUTS && forceReconnect(opts.socket)) {
+			opts.onRetry();
+			return;
+		}
+		opts.onExhausted();
+	}
+	opts.signal.addEventListener("abort", disarm);
+	return {
+		arm() {
+			disarm();
+			timer = setTimeout(fire, HANDSHAKE_TIMEOUT_MS);
+		},
+		disarm,
+		succeeded() {
+			disarm();
+			timeouts = 0;
+		}
+	};
+}
+//#endregion
+//#region src/session/messages.ts
+/**
+* Incoming-message handling for the voice session core.
+*
+* Split out of `session/browser-session.ts`: this module owns the interpretation of
+* server→client frames (audio chunks + JSON {@link SessionEvent}s) and the
+* turn-boundary epoch, while `session/browser-session.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; the `history.restored` frame's own. */
+const MAX_MESSAGES = MAX_CLIENT_MESSAGES;
+/**
+* Snapshot fields cleared when a session's conversation state is wiped —
+* shared by the initial snapshot, `resetState()`, and `session.reset`.
+* The empty arrays are safe to share: snapshot collections are never mutated
+* in place, only replaced.
+*/
+const CLEARED_SESSION_STATE = {
+	messages: [],
+	toolCalls: [],
+	customEvents: [],
+	agentState: null,
+	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 per-session dedup counters (`customEventSeq`,
+* `messageSeq`, `toolCallSeq`) that previously lived as closure locals in
+* `createBrowserSession`. The turn-boundary epoch is NOT one of them: it lives
+* on `conn` because the session core bumps it on teardown too (see
+* `ConnState.turn`).
+*/
+function createMessageHandlers(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
+	*  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) {
+		conn.turn.bump();
+		updateState({
+			userTranscript: null,
+			messages: appendCapped(getSnapshot().messages, {
+				id: ++messageSeq,
+				role: "user",
+				content: text
+			}, MAX_MESSAGES),
+			...agentState.apply({ type: "THINK" })
+		});
+	}
+	/**
+	* The `agentTranscript.*` events carry the reply's text so far as a full-replacement
+	* snapshot (see the protocol schema), so it renders as the live assistant
+	* bubble and only becomes a message when the reply closes. Pipeline mode sends
+	* one per piece of speech, so appending each would break a single reply into a
+	* message per sentence.
+	*
+	* Replace rather than merge: a snapshot is not append-only. A pipeline reply's
+	* closing snapshot drops the dead-air filler the interim ones carried, so it
+	* can be shorter than its predecessor and differ mid-string.
+	*/
+	function handleAgentTranscriptEvent(text) {
+		updateState({ agentTranscript: text });
+	}
+	/**
+	* The reply is over (`reply.completed`, or `reply.cancelled` for a barge-in): move
+	* whatever was spoken into the conversation. A cancelled reply still keeps its
+	* text — the caller heard that much, and dropping it would leave the
+	* transcript claiming the agent never spoke.
+	*/
+	function commitAgentTranscript() {
+		const text = getSnapshot().agentTranscript;
+		if (text === null || text.length === 0) {
+			updateState({ agentTranscript: null });
+			return;
+		}
+		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).
+	*
+	*  A FATAL session is exempt, and that exemption is the whole reason the
+	*  `fatal` region exists: the host's teardown emits, so the frames that
+	*  follow a fatal error are a consequence of it rather than evidence
+	*  against it. Recovering on them left the one message that says what to
+	*  fix — a missing provider key — on screen for a fraction of a second,
+	*  over a session that could no longer hear anyone. */
+	function clearRecoveredError() {
+		updateState(agentState.apply({ type: "ACTIVITY" }));
+	}
+	/**
+	* Return to "listening" at a turn boundary — unless the session is over.
+	*
+	* `reply.completed`, `reply.cancelled` and `session.reset` each wrote
+	* `state: "listening"` unconditionally, which is the second half of the same
+	* bug `clearRecoveredError` covers: the host's fatal paths all call
+	* `terminate()`, and terminating emits `onCancelled()`. So the frame that
+	* ANNOUNCES the session's death was also the frame that painted a live-mic
+	* state over the error it had just reported.
+	*
+	* The exemption is not restated here: `LISTEN` is declined while the `fatal`
+	* region says so, which is what makes this the whole of the rule rather than
+	* one of four sites that had to remember it.
+	*/
+	function toListening(extra = {}) {
+		updateState({
+			...extra,
+			...agentState.apply({ type: "LISTEN" })
+		});
+	}
+	function handleErrorEvent(e) {
+		console.error("Agent error:", e.message);
+		const error = {
+			code: e.code,
+			message: e.message,
+			fatal: e.fatal
+		};
+		if (!e.fatal) updateState(agentState.apply({
+			type: "TURN_ERROR",
+			error
+		}));
+		else {
+			audio.teardown();
+			updateState({
+				...agentState.apply({
+					type: "FATAL",
+					error
+				}),
+				...STOPPED
+			});
+		}
+	}
+	/** Single entry point for all server->client session events. */
+	function handleEvent(e) {
+		if (e.type !== "error.reported") clearRecoveredError();
+		switch (e.type) {
+			case "speech.started":
+				updateState({ userTranscript: "" });
+				break;
+			case "speech.stopped": break;
+			case "userTranscript.committed":
+				handleUserTranscriptEvent(e.text);
+				break;
+			case "userTranscript.updated":
+				updateState({ userTranscript: e.text });
+				break;
+			case "agentTranscript.updated":
+			case "agentTranscript.committed":
+				handleAgentTranscriptEvent(e.text);
+				break;
+			case "tool.called":
+				updateState({ toolCalls: appendCapped(getSnapshot().toolCalls, {
+					callId: e.toolCallId,
+					name: e.toolName,
+					args: toArgsRecord(e.args),
+					status: "pending",
+					seq: ++toolCallSeq,
+					afterMessageId: getSnapshot().messages.at(-1)?.id ?? -1
+				}, MAX_MESSAGES) });
+				break;
+			case "tool.completed": {
+				const tcs = getSnapshot().toolCalls;
+				const idx = tcs.findIndex((tc) => tc.callId === e.toolCallId);
+				const existing = tcs[idx];
+				if (!existing) break;
+				const updated = [...tcs];
+				updated[idx] = {
+					...existing,
+					status: "done",
+					result: e.result
+				};
+				updateState({ toolCalls: updated });
+				break;
+			}
+			case "reply.completed":
+				commitAgentTranscript();
+				toListening();
+				break;
+			case "reply.cancelled":
+				bargeIn(conn, audio);
+				commitAgentTranscript();
+				toListening({ userTranscript: null });
+				break;
+			case "session.reset": {
+				bargeIn(conn, audio);
+				const next = agentState.apply({ type: "RESET" });
+				updateState(agentState.fatal() ? next : {
+					...CLEARED_SESSION_STATE,
+					...next
+				});
+				break;
+			}
+			case "custom.emitted":
+				appendCustomEvent(e.event, e.data);
+				break;
+			case "state.updated":
+				updateState({ agentState: shareUnchangedSlots(getSnapshot().agentState, e.state) });
+				break;
+			case "history.restored": {
+				messageSeq = 0;
+				toolCallSeq = 0;
+				const restored = e.messages.slice(-MAX_MESSAGES).map((m) => ({
+					id: ++messageSeq,
+					role: m.role,
+					content: m.content
+				}));
+				updateState({
+					messages: restored,
+					toolCalls: e.toolCalls.slice(-MAX_MESSAGES).map((tc) => ({
+						callId: tc.callId,
+						name: tc.name,
+						args: toArgsRecord(tc.args),
+						status: tc.status,
+						...omitUndefined({ result: tc.result }),
+						seq: ++toolCallSeq,
+						afterMessageId: restored[tc.afterMessageIndex]?.id ?? -1
+					}))
+				});
+				break;
+			}
+			case "error.reported":
+				handleErrorEvent(e);
+				break;
+			case "session.timedOut": conn.retiredByServer = true;
+		}
+	}
+	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
+	function playAudioChunk(chunk) {
+		updateState(agentState.apply({ type: "SPEAK" }));
+		audio.enqueue(chunk);
+	}
+	/**
+	* Signal that the server has finished sending audio for this turn.
+	*
+	* 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/audio-state.ts`.
+	*/
+	function playAudioDone() {
+		audio.done();
+	}
+	function handleMessage(data) {
+		if (data instanceof ArrayBuffer) {
+			playAudioChunk(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(SessionEventSchema, raw);
+		if (!parsed.ok) {
+			if (parsed.malformed) console.warn("session-core: malformed server message", parsed.error);
+			return;
+		}
+		const msg = parsed.data;
+		if (msg.type === "session.configured") {
+			agentState.apply({ type: "HANDSHAKE_COMPLETE" });
+			return {
+				sampleRate: msg.sampleRate,
+				ttsSampleRate: msg.ttsSampleRate,
+				sid: msg.sessionId
+			};
+		}
+		if (msg.type === "audio.completed") {
+			playAudioDone();
+			return;
+		}
+		handleEvent(msg);
+	}
+	return { handleMessage };
+}
+/**
+* The new frame, with every slot whose view did not change keeping the OLD
+* value object — so `useAgentState(slot)` re-renders only for its own slot.
+* Compared by serialization, which is how the server decided to push at all.
+*/
+function shareUnchangedSlots(previous, next) {
+	if (previous === null) return next;
+	const frame = {};
+	for (const [slot, value] of Object.entries(next)) {
+		const before = previous[slot];
+		frame[slot] = slot in previous && JSON.stringify(before) === JSON.stringify(value) ? before : value;
+	}
+	return frame;
+}
+//#endregion
+//#region src/session/mic.ts
+/**
+* The microphone's way onto the wire — backpressure, and the caller's MUTE.
+*
+* Split out of `session/browser-session.ts` at the source-length cap, along the seam the
+* two share: both decide what a captured frame becomes on the socket, and
+* nothing else in the core reads either.
+*
+* ## A muted frame is SILENCE, not an absent frame
+*
+* `setMicMuted(true)` keeps sending every frame the capture worklet produces,
+* at the same length and cadence, zero-filled. Sending nothing would look
+* cheaper and is wrong on three counts:
+*
+* - **Endpointing.** Hold-to-talk over an agent with AUTOMATIC turn detection
+*   is mute-until-pressed, unmute, speak, mute on release. The transcriber
+*   ends the turn on a stretch of silence; a stream that simply stops gives it
+*   no silence to measure, so the last utterance is answered late or not at
+*   all.
+* - **The stream clock.** The transcriber timestamps by samples received. The
+*   runtime's own push-to-talk silences the mic the same way, for the same
+*   reason (`aai-runtime/src/transports/pipeline/commands.ts`, "sent as SILENCE rather than
+*   withheld").
+* - **Idle.** Nothing is gained on the server side by going quiet: the session
+*   idle deadline deliberately does not count user audio (`ServerSession.onAudio`
+*   in the runtime), so a muted caller is retired exactly as a silent one is —
+*   while a provider that closes a socket fed no audio at all would see a gap.
+*
+* ## It is UI state, not connection state
+*
+* The flag lives on the snapshot (`micMuted`) and nothing that tears a
+* connection down touches it — not a reconnect, a resume, `disconnect()`,
+* `reset()` or `end()` — and it can be set before the first `connect()`, so a
+* UI can open a typed-only session already muted. Muting sends no command and
+* interrupts nothing; it only changes what the next frame carries.
+*
+* It sits AFTER the capture worklet, so the worklet's own digital-silence
+* probe (`onMicSilent`, `MIC_SILENCE_PROBE_MS` in `audio/voice-io.ts`) still measures
+* the real input: zeros this module writes can never read as a dead mic.
+*
+* @module
+*/
+/** Build one session's mic sender. @internal */
+function createMicSender(deps) {
+	let silence = /* @__PURE__ */ new ArrayBuffer(0);
+	const silent = (length) => {
+		if (silence.byteLength !== length) silence = new ArrayBuffer(length);
+		return silence;
+	};
+	return {
+		sendAudio(bytes) {
+			const ws = deps.conn.ws;
+			if (ws?.readyState !== WS_OPEN) return;
+			if (ws.bufferedAmount > MIC_SEND_MAX_BUFFERED_BYTES) return;
+			ws.send(deps.snapshot().micMuted ? silent(bytes.byteLength) : bytes);
+		},
+		sendBuffered(chunks) {
+			const ws = deps.conn.ws;
+			if (ws?.readyState !== WS_OPEN) return;
+			const muted = deps.snapshot().micMuted;
+			for (const bytes of chunks) ws.send(muted ? silent(bytes.byteLength) : bytes);
+		},
+		setMicMuted(muted) {
+			deps.updateState({ micMuted: muted });
+		}
+	};
+}
+//#endregion
+//#region src/session/preconnect.ts
+/**
+* The rate the capture guesses: the SDK's default STT rate
+* (`DEFAULT_STT_SAMPLE_RATE`), which is also the only rate an AssemblyAI S2S
+* agent accepts. A miss costs a resample of the buffer, not the audio.
+*/
+const PRE_CONNECT_SAMPLE_RATE = 16e3;
+/** Build one session's pre-connect capture holder. @internal */
+function createPreConnectAudio(enabled) {
+	let held = null;
+	return {
+		begin() {
+			loadAudioModules().catch(() => {});
+			if (!enabled || held !== null) return;
+			held = Promise.all([import("./audio/index.js"), loadAudioModules()]).then(([{ openPreConnectCapture }, [, captureWorklet]]) => openPreConnectCapture({
+				sampleRate: PRE_CONNECT_SAMPLE_RATE,
+				captureWorkletSrc: captureWorklet,
+				maxSeconds: 10
+			})).catch(() => null);
+		},
+		take() {
+			const taken = held;
+			held = null;
+			return taken;
+		},
+		release() {
+			const taken = held;
+			held = null;
+			taken?.then((capture) => capture?.close());
+		}
+	};
+}
+//#endregion
+//#region src/session/state.ts
+/**
+* The browser session's {@link AgentState}, and the error beside it, as a
+* statechart.
+*
+* These two were written independently from thirteen sites across
+* `session/browser-session.ts`, `session/messages.ts` and
+* `session/audio-setup.ts`, each one deciding for itself whether its write
+* was legal by reading the snapshot back first. Three shipped bugs came out of
+* that, and all three are the same shape — a transition nothing forbade:
+*
+* - **A straggler audio chunk flipped an errored session to `"speaking"`.**
+*   Guarded by hand at the call site
+*   (`if (snap.state === "error" || (snap.state === "disconnected" && …))`).
+*   Here `error` simply does not handle `SPEAK`.
+* - **The frame that announced a session's death also wiped the banner
+*   reporting it.** Every fatal path in the host tears the transport down, and
+*   tearing down EMITS — so `reply.cancelled` arrived right behind the error and
+*   `toListening()` painted a live-mic state over it. A missing provider key is
+*   the case that made it visible: the one message that says exactly what to fix
+*   was on screen for a few hundred milliseconds and left a session that looked
+*   live and was deaf.
+* - **A later frame RECOVERED the state.** `clearRecoveredError` reads a
+*   non-error frame as proof the session works, which is right for a
+*   turn-level failure and wrong for a server error that ended the call.
+*
+* The second and third were fixed with a `conn.fatalError` boolean that every
+* writer had to remember to consult. It is the `fatal` region here, so
+* forgetting is not available: `LISTEN` and `ACTIVITY` are declined in one
+* place rather than at each of their five call sites.
+*
+* ## Two regions, because the fatal latch OUTLIVES the error state
+*
+* `fatal` is not a substate of `error`, tempting as that looks. It is cleared by
+* exactly one thing — the next `config` frame, i.e. a completed handshake — and
+* that is per CONNECTION rather than per session, so a reconnect that really
+* works is not pinned to a dead session's banner. Between the error and that
+* frame the phase runs `error → connecting → ready` while the latch stays set,
+* which a substate cannot express.
+*
+* ## The published surface is unchanged
+*
+* {@link AgentState} is a public type in the versioned `aai-ui:session`
+* capability, so {@link AgentStateSnapshot.state} is one of its seven names and
+* nothing here widens it. The internal distinctions live in the second region
+* and in context, not in the projection.
+*/
+/**
+* Not fatally over — so a working state may be painted.
+*
+* `stateIn` reads the sibling REGION rather than a mirror of it in context,
+* which is what keeps `fatal` the one place the latch lives. The three events
+* this guards are the three that used to consult `conn.fatalError` by hand at
+* five call sites; `THINK` is a fourth that did not, and should have — the doc
+* on that flag says outright that "no later frame may take its banner off the
+* screen", and a `userTranscript.committed` arriving behind a fatal error
+* painted `"thinking"` over it.
+*/
+const NOT_FATAL = not(stateIn({ fatal: "yes" }));
+const sessionStateMachine = setup({
+	types: {},
+	guards: { 
+	/** A banner is still up from a failure the session survived. */
+hasError: ({ context }) => context.error !== null },
+	actions: {
+		clearError: assign({ error: null }),
+		setError: assign({ error: ({ context, event }) => event.type === "TURN_ERROR" || event.type === "FATAL" || event.type === "FAILED" ? event.error : context.error })
+	}
+}).createMachine({
+	id: "sessionState",
+	type: "parallel",
+	context: { error: null },
+	states: {
+		/** The seven names {@link AgentState} publishes. */
+		phase: {
+			initial: "disconnected",
+			on: {
+				CONNECT: {
+					target: ".connecting",
+					actions: "clearError"
+				},
+				CLOSED: {
+					target: ".disconnected",
+					actions: "clearError"
+				},
+				DISCONNECT: ".disconnected",
+				END: {
+					target: ".disconnected",
+					actions: "clearError"
+				},
+				TURN_ERROR: { actions: "setError" },
+				FATAL: {
+					target: ".error",
+					actions: "setError"
+				},
+				FAILED: {
+					target: ".error",
+					actions: "setError"
+				},
+				LISTEN: {
+					guard: NOT_FATAL,
+					target: ".listening"
+				},
+				RESET: {
+					guard: NOT_FATAL,
+					target: ".listening",
+					actions: "clearError"
+				},
+				THINK: {
+					guard: NOT_FATAL,
+					target: ".thinking"
+				},
+				ACTIVITY: {
+					guard: and([NOT_FATAL, "hasError"]),
+					actions: "clearError"
+				}
+			},
+			states: {
+				disconnected: { on: { SPEAK: {
+					guard: not("hasError"),
+					target: "speaking"
+				} } },
+				connecting: { on: { SOCKET_OPEN: "ready" } },
+				ready: { on: { SPEAK: "speaking" } },
+				listening: { on: { SPEAK: "speaking" } },
+				thinking: { on: { SPEAK: "speaking" } },
+				speaking: {},
+				/**
+				* A failure is on screen.
+				*
+				* `SPEAK` is absent deliberately — that is half the guard
+				* `playAudioChunk` used to spell, and the other half is `disconnected`'s
+				* above. `ACTIVITY` recovers to `listening` rather than merely clearing
+				* the banner: the socket is demonstrably open (we are handling a server
+				* event), so `disconnected` would misreport a live session.
+				*/
+				error: { on: {
+					ACTIVITY: {
+						guard: NOT_FATAL,
+						target: "listening",
+						actions: "clearError"
+					},
+					CLOSED: {}
+				} }
+			}
+		},
+		/**
+		* Whether the session is fatally over.
+		*
+		* Separate from `phase` because it OUTLIVES the `error` state: only a
+		* completed handshake clears it, and the phase moves through `connecting`
+		* and `ready` on the way to one. A substate of `error` could not say that.
+		*/
+		fatal: {
+			initial: "no",
+			states: {
+				no: { on: { FATAL: "yes" } },
+				yes: { on: { HANDSHAKE_COMPLETE: "no" } }
+			}
+		}
+	}
+});
+/** Create the state machine for one browser session. */
+function createSessionStateMachine() {
+	const actor = createActor(sessionStateMachine).start();
+	function snapshot() {
+		const at = actor.getSnapshot();
+		return {
+			state: at.value.phase,
+			error: at.context.error
+		};
+	}
+	return {
+		snapshot,
+		apply(event) {
+			actor.send(event);
+			return snapshot();
+		},
+		fatal: () => actor.getSnapshot().matches({ fatal: "yes" })
+	};
+}
+//#endregion
+//#region src/session/user-turn.ts
+/**
+* The local half of an interruption: the agent stops here at once, the same
+* barge-in `cancel()` makes — only when there is something to stop, so a
+* press or a message into silence leaves a "listening" state alone. The
+* server's `reply.cancelled` follows and finds nothing left to flush.
+*/
+function interruptLocally(deps) {
+	const { state } = deps.snapshot();
+	if (state === "speaking" || state === "thinking") {
+		deps.bargeIn();
+		deps.updateState(deps.agentState.apply({ type: "LISTEN" }));
+	}
+}
+/**
+* Everything a caller's turn can be started by: push-to-talk's three edges
+* and a TYPED turn — `session.userTurn` and `session.sendText`. One builder
+* over one set of deps, because both are the same kind of thing (a user turn
+* the client, not the transcriber, delimits) and both interrupt the same way.
+*
+* @internal
+*/
+function createUserInput(deps) {
+	function send(trimmed) {
+		interruptLocally(deps);
+		deps.sendJson({
+			type: "user_text",
+			text: trimmed
+		});
+	}
+	return {
+		userTurn: createUserTurnActions(deps),
+		sendText(text, options) {
+			const trimmed = text.trim();
+			if (trimmed === "") return;
+			if (deps.connected() && deps.queued.length === 0) {
+				send(trimmed);
+				return;
+			}
+			if (deps.queued.length === 0 && options?.connect !== true) return;
+			deps.queued.push(trimmed);
+			deps.open();
+		},
+		flushQueued() {
+			if (!deps.connected()) return;
+			for (const text of deps.queued.splice(0)) send(text);
+		},
+		sendToolResult(toolCallId, outcome) {
+			if (!deps.connected()) return;
+			deps.sendJson({
+				type: "tool_result",
+				toolCallId,
+				...encodeOutcome(outcome)
+			});
+		}
+	};
+}
+/**
+* The frame's two fields. A result `JSON.stringify` cannot encode (a cycle, a
+* `BigInt`, a bare function) fails the call naming why, rather than throwing
+* into the handler that produced it or leaving the server waiting.
+*/
+function encodeOutcome(outcome) {
+	if ("error" in outcome) return {
+		result: "",
+		error: outcome.error
+	};
+	try {
+		return { result: JSON.stringify(outcome.result ?? null) ?? "null" };
+	} catch (err) {
+		return {
+			result: "",
+			error: `Tool result is not JSON-serializable: ${String(err)}`
+		};
+	}
+}
+/** Build the three push-to-talk edges. @internal */
+function createUserTurnActions(deps) {
+	return {
+		start() {
+			if (!deps.connected()) return;
+			interruptLocally(deps);
+			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/browser-session.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/messages.ts`;
+* the public/internal type declarations live in `session/types.ts`.
+*
+* No dependency on React, Preact, or any UI framework.
+*/
+/**
+* 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.
+*
+* Most clients never call this: `mountClient()` creates a core and installs it in
+* React context for the hooks. Reach for it directly when building a
+* non-React UI (or wiring the session into another framework's store).
+*
+* @example
+* ```ts
+* import { createBrowserSession, type SessionSnapshot } from "@alexkroman1/aai-ui";
+*
+* declare function render(snapshot: SessionSnapshot): void;
+*
+* const session = createBrowserSession({ platformUrl: "https://host/my-agent/" });
+* session.subscribe(() => render(session.getSnapshot()));
+* session.start();
+* ```
+*
+* @param options - Session configuration including the platform server URL.
+* @returns A {@link BrowserSession} handle for controlling the session.
+*
+* @public
+*/
+function createBrowserSession(options) {
+	return createBrowserSessionWith(options, {});
+}
+/**
+* {@link createBrowserSession} with its audio bring-up injectable. Not on the
+* barrel: it is the seam a spec uses to hold an audio path open by hand rather
+* than replacing the audio module.
+*
+* @internal
+*/
+function createBrowserSessionWith(options, internals) {
+	let currentSnapshot = {
+		...CLEARED_SESSION_STATE,
+		state: "disconnected",
+		contentVersion: 0,
+		started: false,
+		running: false,
+		recording: false,
+		micMuted: false,
+		apiUrl: buildWsUrl(options.platformUrl).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"
+	];
+	/** Does `partial` leave this field exactly as it already is? */
+	function isUnchanged(key, partial) {
+		return partial[key] === currentSnapshot[key];
+	}
+	/** `sendText(…, { connect: true })` waiting for a session — see `UserTurnDeps.queued`. */
+	const queuedText = [];
+	function updateState(partial) {
+		if (partial.running === false) queuedText.length = 0;
+		if (Object.keys(partial).every((key) => isUnchanged(key, partial))) return;
+		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);
+		};
+	}
+	/**
+	* The session's `state` and `error`, as one fact rather than two fields
+	* thirteen call sites wrote independently — see `session/state.ts`,
+	* which carries the three shipped bugs that arrangement produced.
+	*/
+	const agentState = createSessionStateMachine();
+	const conn = {
+		ws: null,
+		retiredByServer: false,
+		turn: createEpoch()
+	};
+	let connectionController = null;
+	const identity = createSessionIdentity(options, () => dialer);
+	const dialer = createDialer({
+		...options,
+		client: identity.clientId
+	}, notify);
+	function resetState() {
+		updateState(CLEARED_SESSION_STATE);
+	}
+	/** The socket if it can carry a frame — a socket, not a boolean, so it narrows `conn.ws`. */
+	function openSocket() {
+		return conn.ws?.readyState === WS_OPEN ? conn.ws : null;
+	}
+	function sendJson(msg) {
+		openSocket()?.send(JSON.stringify(msg));
+	}
+	const mic = createMicSender({
+		conn,
+		snapshot: () => currentSnapshot,
+		updateState
+	});
+	/**
+	* The microphone, the worklets and the buffer in front of them, as a
+	* statechart — see `session/audio-state.ts`, which carries what the
+	* in-flight latch, the generation epoch and the two pre-init fields on
+	* `ConnState` cost. `session/audio-effects.ts` is the other half: every
+	* frame and snapshot write the machine decides on but cannot make.
+	*/
+	const preConnect = createPreConnectAudio(options.preConnectAudio !== false);
+	const audio = createAudioPath(createAudioEffects({
+		conn,
+		updateState,
+		agentState,
+		sendJson,
+		mic,
+		preConnect,
+		openAudioPath: internals.openAudioPath
+	}));
+	const { handleMessage } = createMessageHandlers({
+		getSnapshot,
+		updateState,
+		conn,
+		agentState,
+		audio
+	});
+	/** Abort the in-flight connection and release audio + WebSocket resources. */
+	function teardownConnection() {
+		connectionController?.abort();
+		connectionController = null;
+		preConnect.release();
+		audio.teardown();
+		conn.ws?.close();
+		conn.ws = null;
+	}
+	/**
+	* React to the server's `session.configured` frame: record it and set up the
+	* session's audio path. **It no longer replays history, and that is the
+	* point**: a reconnect used to push `messages` back, making the CLIENT the
+	* authority on the agent's memory; the server restores the conversation from
+	* its own event stream now, covering what a client cannot (a second tab, a
+	* replacement sandbox, a reopened tab). The transcript on screen is untouched.
+	*/
+	function onServerConfig(config) {
+		dialer.configured(config.sid);
+		options.onSessionId?.(config.sid);
+		flushQueued();
+		audio.start(config);
+	}
+	function connect(opts) {
+		if (opts?.signal?.aborted) {
+			disconnect();
+			return;
+		}
+		updateState(agentState.apply({ type: "CONNECT" }));
+		teardownConnection();
+		preConnect.begin();
+		conn.retiredByServer = false;
+		const controller = new AbortController();
+		connectionController = controller;
+		const { signal: sig } = controller;
+		if (opts?.signal) opts.signal.addEventListener("abort", () => disconnect(), { signal: sig });
+		const socket = dialer.open();
+		socket.binaryType = "arraybuffer";
+		conn.ws = socket;
+		let socketErrored = false;
+		const handshake = createHandshakeGuard({
+			socket,
+			signal: sig,
+			onRetry: () => {
+				audio.teardown();
+				updateState({
+					...agentState.apply({ type: "CONNECT" }),
+					recording: false
+				});
+			},
+			onExhausted: () => {
+				preConnect.release();
+				audio.teardown();
+				controller.abort();
+				socket.close();
+				conn.ws = null;
+				updateState({
+					...agentState.apply({
+						type: "FAILED",
+						error: HANDSHAKE_ERROR
+					}),
+					...STOPPED
+				});
+			}
+		});
+		socket.addEventListener("open", () => {
+			updateState(agentState.apply({ type: "SOCKET_OPEN" }));
+			handshake.arm();
+		}, { signal: sig });
+		socket.addEventListener("message", (event) => {
+			const config = handleMessage(event.data);
+			if (!config) return;
+			handshake.succeeded();
+			onServerConfig(config);
+		}, { signal: sig });
+		socket.addEventListener("error", () => {
+			socketErrored = true;
+		}, { signal: sig });
+		socket.addEventListener("close", (event) => {
+			if (sig.aborted) return;
+			handshake.disarm();
+			audio.teardown();
+			if (!(conn.retiredByServer || agentState.fatal()) && reconnectPending(socket)) {
+				socketErrored = false;
+				updateState({
+					...agentState.apply({ type: "CONNECT" }),
+					recording: false
+				});
+				return;
+			}
+			preConnect.release();
+			controller.abort();
+			socket.close();
+			conn.ws = null;
+			const failure = closeFailure(event, socketErrored);
+			updateState({
+				...failure === null ? agentState.apply({ type: "CLOSED" }) : agentState.apply({
+					type: "FAILED",
+					error: {
+						code: "connection",
+						message: failure,
+						fatal: false
+					}
+				}),
+				...STOPPED
+			});
+		}, { signal: sig });
+	}
+	function cancel() {
+		if (!openSocket()) return;
+		bargeIn(conn, audio);
+		updateState(agentState.apply({ type: "LISTEN" }));
+		sendJson({ type: "cancel" });
+	}
+	const { userTurn, sendText, flushQueued, sendToolResult } = createUserInput({
+		snapshot: () => currentSnapshot,
+		connected: () => openSocket() !== null,
+		queued: queuedText,
+		open: () => {
+			if (!currentSnapshot.running) (currentSnapshot.started ? toggle : start)();
+		},
+		bargeIn: () => bargeIn(conn, audio),
+		agentState,
+		updateState,
+		sendJson
+	});
+	function reset() {
+		bargeIn(conn, audio);
+		if (openSocket()) {
+			sendJson({ type: "reset" });
+			return;
+		}
+		end();
+		start();
+	}
+	function disconnect() {
+		teardownConnection();
+		updateState({
+			...agentState.apply({ type: "DISCONNECT" }),
+			...STOPPED
+		});
+	}
+	function start() {
+		updateState({
+			started: true,
+			running: true
+		});
+		connect();
+	}
+	function toggle() {
+		if (currentSnapshot.running) disconnect();
+		else {
+			updateState({ running: true });
+			connect();
+		}
+	}
+	function end() {
+		teardownConnection();
+		dialer.forget();
+		updateState({
+			...CLEARED_SESSION_STATE,
+			...agentState.apply({ type: "END" }),
+			started: false,
+			...STOPPED
+		});
+	}
+	function restart() {
+		end();
+		start();
+	}
+	function resume(sessionId) {
+		if (!RESUME_ID_RE.test(sessionId)) throw new RangeError(`resume: "${sessionId}" is not a session id (${RESUME_ID_RE})`);
+		end();
+		dialer.adopt(sessionId);
+		start();
+	}
+	return {
+		getSnapshot,
+		subscribe,
+		connect,
+		cancel,
+		userTurn: Object.freeze(userTurn),
+		identity,
+		sendText,
+		sendToolResult,
+		setMicMuted: mic.setMicMuted,
+		resetState,
+		reset,
+		disconnect,
+		start,
+		toggle,
+		end,
+		restart,
+		resume,
+		[Symbol.dispose]() {
+			disconnect();
+		}
+	};
+}
+//#endregion
+export { ticketCarriage as a, resolveReported as c, storageSet as d, urlSlot as f, resolveSessionTokenSync as i, storageGet as l, CLEARED_SESSION_STATE as n, loadAudioModules as o, resolveSessionToken as r, browserClientId as s, createBrowserSession as t, storageRemove as u };