@alexkroman1/aai-ui 6.11.0 → 7.0.0

package/dist/{session-core-CAfYmUbg.js → session-core-C2JtLArh.js}

@@ -1,98 +1,11 @@
+import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-B4nznRvH.js";
 import { MIC_SEND_MAX_BUFFERED_BYTES } from "./types.js";
-import { CLIENT_CONFIG_PATH, ClientConfigResponseSchema, ServerMessageSchema, lenientParse } from "@alexkroman1/aai/protocol";
-import { DEFAULT_MAX_HISTORY, errorMessage, safeJsonParse } from "@alexkroman1/aai";
-import { omitUndefined, toArgsRecord } from "@alexkroman1/aai/utils";
-import { WS_OPEN, createEpoch } from "@alexkroman1/aai/internal";
+import { ServerMessageSchema, lenientParse } from "@alexkroman1/aai/protocol";
+import { errorMessage, safeJsonParse } from "@alexkroman1/aai";
+import { omitUndefined } from "@alexkroman1/aai/utils";
+import { DEFAULT_MAX_HISTORY, WS_OPEN, createEpoch, toArgsRecord } from "@alexkroman1/aai/internal";
 import ReconnectingWebSocket from "partysocket/ws";
-//#region client-config.ts
-/**
-* Pre-connection client-config lookup.
-*
-* `GET client-config` (relative to the agent's base URL — see
-* `sdk/client-config.ts` in `@alexkroman1/aai`) gives the default client the
-* agent's display name and greeting before any connection exists. For that
-* use every failure path — network error, 404 from an older server,
-* malformed body — degrades to the empty default (`fetchClientConfig`), so
-* the lookup can never break an existing agent.
-*
-* The session's broker decision needs the opposite: `loadClientConfig`
-* keeps "the lookup failed" (`null`) distinct from "the server answered and
-* named no sessionUrl" (`{}`). See its doc comment.
-*/
-/**
-* Resolve a relative endpoint path against the agent's base URL.
-*
-* @internal
-*/
-function buildAgentUrl(platformUrl, endpointPath) {
-	return new URL(endpointPath, platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`);
-}
-const AGENT_DEFAULT = {};
-/**
-* Per-attempt deadline for the `client-config` lookup.
-*
-* A request issued while the platform is restarting or saturated can HANG
-* rather than fail — the proxy holds the socket open — and a browser fetch
-* has no timeout of its own. Every other failure here is already handled
-* (`null`, then the same-origin fallback), but a hang is not a failure: the
-* promise simply never settles.
-*
-* That is unrecoverable rather than merely slow, because this lookup runs
-* inside the session's WebSocket URL *provider*. partysocket awaits the
-* provider under `_connectLock` and arms its own `connectionTimeout` only
-* AFTER the URL resolves, so a hung lookup means no socket is ever
-* constructed, no `error`/`close` ever fires, and none of the 10 reconnect
-* attempts ever happen — the session sits on "connecting" forever, and stays
-* there long after the server is back. Reproduced: zero sockets opened.
-*
-* A timed-out attempt therefore degrades exactly like any other failed one —
-* `null`, so `serverIsBroker` stays unlatched and the attempt falls through
-* to the same-origin `websocket` path, whose failure re-enters the normal
-* backoff and re-fetches this on the next attempt.
-*
-* Sized well above the real work (one same-origin JSON GET that reads the
-* agent's row) and well under a user's patience — the same 10s the studio's
-* gating reads use for the identical hazard.
-*
-* @internal
-*/
-const CLIENT_CONFIG_ATTEMPT_TIMEOUT_MS = 1e4;
-/**
-* Fetch the agent's client config, reporting `null` when the lookup did not
-* produce an answer (network error, non-2xx, unparsable body).
-*
-* The distinction from `fetchClientConfig` matters for exactly one caller:
-* the session's per-attempt broker decision. A config that ARRIVED and named
-* no `sessionUrl` means "this server is not a broker" (`aai dev`, an older
-* server) — a durable fact worth latching. A lookup that FAILED means
-* nothing about the server, and treating the two alike is how a single 503
-* (a sandbox mid-boot, or one that failed to start) pinned a session to the
-* platform's `/:slug/websocket` — a WebSocket redirect browsers don't
-* follow, so every retry failed with no re-brokering even after the agent
-* recovered.
-*
-* @internal
-*/
-async function loadClientConfig(platformUrl, fetchFn) {
-	const doFetch = fetchFn ?? ((input, init) => globalThis.fetch(input, init));
-	try {
-		const resp = await doFetch(buildAgentUrl(platformUrl, CLIENT_CONFIG_PATH).href, { signal: AbortSignal.timeout(CLIENT_CONFIG_ATTEMPT_TIMEOUT_MS) });
-		if (!resp.ok) return null;
-		const parsed = ClientConfigResponseSchema.safeParse(await resp.json());
-		return parsed.success ? parsed.data : null;
-	} catch {
-		return null;
-	}
-}
-/**
-* Fetch the agent's client config; any failure yields the agent default.
-*
-* @internal
-*/
-async function fetchClientConfig(platformUrl, fetchFn) {
-	return await loadClientConfig(platformUrl, fetchFn) ?? AGENT_DEFAULT;
-}
-//#endregion
+import { and, assign, createActor, not, setup, stateIn } from "xstate";
 //#region session-core-audio-setup.ts
 /**
 * Audio-path initialization for the voice session core.
@@ -143,11 +56,13 @@ async function initAudioCapture(conn, msg, deps) {
 	const reportAudioFailure = (message) => {
 		deps.cleanupAudio();
 		deps.updateState({
-			state: "error",
-			error: {
-				code: "audio",
-				message
-			},
+			...deps.agentState.apply({
+				type: "FAILED",
+				error: {
+					code: "audio",
+					message
+				}
+			}),
 			running: false,
 			recording: false
 		});
@@ -195,7 +110,7 @@ async function initAudioCapture(conn, msg, deps) {
 		if (conn.preInitDone) {
 			conn.preInitDone = false;
 			deps.settleWhenAudioDrained(io);
-		} else deps.updateState({ state: "listening" });
+		} else deps.updateState(deps.agentState.apply({ type: "LISTEN" }));
 	} catch (err) {
 		if (stale()) return;
 		reportAudioFailure(`Microphone access failed: ${errorMessage(err)}`);
@@ -556,7 +471,7 @@ function appendCapped(list, item, cap) {
 * `ConnState.turn`).
 */
 function createMessageHandlers(deps) {
-	const { getSnapshot, updateState, conn, cleanupAudio } = deps;
+	const { getSnapshot, updateState, conn, agentState, cleanupAudio } = deps;
 	/** Monotonically increasing counter for custom events -- used by useEvent to deduplicate. */
 	let customEventSeq = 0;
 	/** Monotonically increasing counter for chat messages -- stable render keys
@@ -581,7 +496,7 @@ function createMessageHandlers(deps) {
 				role: "user",
 				content: text
 			}, MAX_MESSAGES),
-			state: "thinking"
+			...agentState.apply({ type: "THINK" })
 		});
 	}
 	/**
@@ -622,54 +537,53 @@ function createMessageHandlers(deps) {
 	/** 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 error is exempt, and that exemption is the whole reason the flag
-	*  exists (see `ConnState.fatalError`): 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. */
+	*  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() {
-		if (conn.fatalError) return;
-		const snap = getSnapshot();
-		if (snap.state === "error") updateState({
-			state: "listening",
-			error: null
-		});
-		else if (snap.error !== null) updateState({ error: null });
+		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`'s latch covers: the host's fatal paths all call
+	* `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(conn.fatalError ? extra : {
+		updateState({
 			...extra,
-			state: "listening"
+			...agentState.apply({ type: "LISTEN" })
 		});
 	}
 	function handleErrorEvent(e) {
 		console.error("Agent error:", e.message);
-		if (e.fatal === false) updateState({ error: {
+		const error = {
 			code: e.code,
 			message: e.message
-		} });
+		};
+		if (e.fatal === false) updateState(agentState.apply({
+			type: "TURN_ERROR",
+			error
+		}));
 		else {
 			cleanupAudio();
 			conn.generation.bump();
-			conn.fatalError = true;
 			updateState({
-				state: "error",
-				error: {
-					code: e.code,
-					message: e.message
-				},
+				...agentState.apply({
+					type: "FATAL",
+					error
+				}),
 				running: false,
 				recording: false
 			});
@@ -727,11 +641,16 @@ function createMessageHandlers(deps) {
 				commitAgentTranscript();
 				toListening({ userTranscript: null });
 				break;
-			case "session.reset":
+			case "session.reset": {
 				conn.turn.bump();
 				conn.voiceIO?.flush();
-				toListening(conn.fatalError ? {} : CLEARED_SESSION_STATE);
+				const next = agentState.apply({ type: "RESET" });
+				updateState(agentState.fatal() ? next : {
+					...CLEARED_SESSION_STATE,
+					...next
+				});
 				break;
+			}
 			case "custom.emitted":
 				appendCustomEvent(e.event, e.data);
 				break;
@@ -771,9 +690,7 @@ function createMessageHandlers(deps) {
 	}
 	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
 	function playAudioChunk(chunk) {
-		const snap = getSnapshot();
-		if (snap.state === "error" || snap.state === "disconnected" && snap.error !== null) return;
-		if (snap.state !== "speaking") updateState({ state: "speaking" });
+		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);
 	}
@@ -785,7 +702,7 @@ function createMessageHandlers(deps) {
 		const gen = conn.turn.current();
 		io.done().then(() => {
 			if (!conn.turn.isCurrent(gen)) return;
-			updateState({ state: "listening" });
+			updateState(agentState.apply({ type: "LISTEN" }));
 		}).catch((err) => {
 			console.warn("Audio playback done failed:", err);
 		});
@@ -800,7 +717,7 @@ function createMessageHandlers(deps) {
 		if (io) settleWhenAudioDrained(io);
 		else {
 			conn.preInitDone = true;
-			updateState({ state: "listening" });
+			updateState(agentState.apply({ type: "LISTEN" }));
 		}
 	}
 	function handleMessage(data) {
@@ -824,7 +741,7 @@ function createMessageHandlers(deps) {
 		}
 		const msg = parsed.data;
 		if (msg.type === "session.configured") {
-			conn.fatalError = false;
+			agentState.apply({ type: "HANDSHAKE_COMPLETE" });
 			return {
 				sampleRate: msg.sampleRate,
 				ttsSampleRate: msg.ttsSampleRate,
@@ -843,6 +760,188 @@ function createMessageHandlers(deps) {
 	};
 }
 //#endregion
+//#region session-core-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-core.ts`, `session-core-messages.ts` and
+* `session-core-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 `user-transcript.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 session-core.ts
 /**
 * Framework-agnostic voice session core.
@@ -904,7 +1003,12 @@ function createSessionCore(options) {
 		"userTranscript",
 		"agentTranscript"
 	];
+	/** Does `partial` leave this field exactly as it already is? */
+	function isUnchanged(key, partial) {
+		return partial[key] === currentSnapshot[key];
+	}
 	function updateState(partial) {
+		if (Object.keys(partial).every((key) => isUnchanged(key, partial))) return;
 		currentSnapshot = contentKeys.some((key) => key in partial && partial[key] !== currentSnapshot[key]) ? {
 			...currentSnapshot,
 			...partial,
@@ -924,10 +1028,15 @@ function createSessionCore(options) {
 			subscribers.delete(callback);
 		};
 	}
+	/**
+	* The session's `state` and `error`, as one fact rather than two fields
+	* thirteen call sites wrote independently — see `session-core-state.ts`,
+	* which carries the three shipped bugs that arrangement produced.
+	*/
+	const agentState = createSessionStateMachine();
 	const conn = {
 		ws: null,
 		retiredByServer: false,
-		fatalError: false,
 		voiceIO: null,
 		audioSetupInFlight: false,
 		generation: createEpoch(),
@@ -971,12 +1080,14 @@ function createSessionCore(options) {
 		getSnapshot,
 		updateState,
 		conn,
+		agentState,
 		cleanupAudio
 	});
 	const audioDeps = {
 		sendJson,
 		sendAudio,
 		updateState,
+		agentState,
 		settleWhenAudioDrained,
 		cleanupAudio
 	};
@@ -1009,10 +1120,7 @@ function createSessionCore(options) {
 			disconnect();
 			return;
 		}
-		updateState({
-			state: "connecting",
-			error: null
-		});
+		updateState(agentState.apply({ type: "CONNECT" }));
 		loadAudioModules().catch(() => {});
 		teardownConnection();
 		conn.generation.bump();
@@ -1032,7 +1140,7 @@ function createSessionCore(options) {
 				cleanupAudio();
 				conn.generation.bump();
 				updateState({
-					state: "connecting",
+					...agentState.apply({ type: "CONNECT" }),
 					recording: false
 				});
 			},
@@ -1042,15 +1150,17 @@ function createSessionCore(options) {
 				socket.close();
 				conn.ws = null;
 				updateState({
-					state: "error",
-					error: HANDSHAKE_ERROR,
+					...agentState.apply({
+						type: "FAILED",
+						error: HANDSHAKE_ERROR
+					}),
 					running: false,
 					recording: false
 				});
 			}
 		});
 		socket.addEventListener("open", () => {
-			updateState({ state: "ready" });
+			updateState(agentState.apply({ type: "SOCKET_OPEN" }));
 			handshake.arm();
 		}, { signal: sig });
 		socket.addEventListener("message", (event) => {
@@ -1070,7 +1180,7 @@ function createSessionCore(options) {
 				conn.generation.bump();
 				socketErrored = false;
 				updateState({
-					state: "connecting",
+					...agentState.apply({ type: "CONNECT" }),
 					recording: false
 				});
 				return;
@@ -1078,22 +1188,14 @@ function createSessionCore(options) {
 			controller.abort();
 			socket.close();
 			conn.ws = null;
-			if (socketErrored) updateState({
-				state: "error",
-				error: {
-					code: "connection",
-					message: "WebSocket connection error"
-				},
-				running: false,
-				recording: false
-			});
-			else if (currentSnapshot.state === "error") updateState({
-				running: false,
-				recording: false
-			});
-			else updateState({
-				state: "disconnected",
-				error: null,
+			updateState({
+				...socketErrored ? agentState.apply({
+					type: "FAILED",
+					error: {
+						code: "connection",
+						message: "WebSocket connection error"
+					}
+				}) : agentState.apply({ type: "CLOSED" }),
 				running: false,
 				recording: false
 			});
@@ -1103,7 +1205,7 @@ function createSessionCore(options) {
 		if (!openSocket()) return;
 		conn.turn.bump();
 		conn.voiceIO?.flush();
-		updateState({ state: "listening" });
+		updateState(agentState.apply({ type: "LISTEN" }));
 		sendJson({ type: "cancel" });
 	}
 	function reset() {
@@ -1119,7 +1221,7 @@ function createSessionCore(options) {
 	function disconnect() {
 		teardownConnection();
 		updateState({
-			state: "disconnected",
+			...agentState.apply({ type: "DISCONNECT" }),
 			running: false,
 			recording: false
 		});
@@ -1143,7 +1245,7 @@ function createSessionCore(options) {
 		dialer.forget();
 		updateState({
 			...CLEARED_SESSION_STATE,
-			state: "disconnected",
+			...agentState.apply({ type: "END" }),
 			started: false,
 			running: false,
 			recording: false
@@ -1166,4 +1268,4 @@ function createSessionCore(options) {
 	};
 }
 //#endregion
-export { loadClientConfig as i, buildAgentUrl as n, fetchClientConfig as r, createSessionCore as t };
+export { createSessionCore as t };

package/dist/session-core-audio-setup.d.ts

@@ -1,11 +1,14 @@
 import type { ClientMessage } from "@alexkroman1/aai/protocol";
 import type { VoiceIO } from "./audio.ts";
+import type { SessionStateMachine } from "./session-core-state.ts";
 import type { ConnState, SessionSnapshot } from "./session-core-types.ts";
 /** Dependencies `initAudioCapture` needs from the owning session core. */
 export type AudioSetupDeps = {
     sendJson: (msg: ClientMessage) => void;
     sendAudio: (bytes: ArrayBuffer) => void;
     updateState: (partial: Partial<SessionSnapshot>) => void;
+    /** The session's state and error, as one fact — see `session-core-state.ts`. */
+    agentState: SessionStateMachine;
     /** Turn-boundary-guarded drain from the message handlers — replays a
      *  buffered `audio_done` without stomping a barge-in's state. */
     settleWhenAudioDrained: (io: VoiceIO) => void;

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

@@ -1,3 +1,4 @@
+import type { SessionStateMachine } from "./session-core-state.ts";
 import type { ConnState, SessionSnapshot } from "./session-core-types.ts";
 /**
  * Snapshot fields cleared when a session's conversation state is wiped —
@@ -25,6 +26,8 @@ type MessageHandlerDeps = {
     getSnapshot: () => SessionSnapshot;
     updateState: (partial: Partial<SessionSnapshot>) => void;
     conn: ConnState;
+    /** The session's state and error, as one fact — see `session-core-state.ts`. */
+    agentState: SessionStateMachine;
     /** Release the microphone/VoiceIO (the session core's `cleanupAudio`). */
     cleanupAudio: () => void;
 };