@alexkroman1/aai-ui 0.9.3 → 0.10.0

package/dist/session-D0RdWlWH.js

@@ -0,0 +1,451 @@
+import { errorMessage } from "@alexkroman1/aai/utils";
+import { ReadyConfigSchema, ServerMessageSchema } from "@alexkroman1/aai/protocol";
+//#region client-handler.ts
+/**
+* Handles server→client messages and updates reactive Preact signals
+* accordingly (state transitions, transcripts, messages, audio playback).
+*
+* @internal Exported for testing only.
+*/
+var ClientHandler = class {
+	#state;
+	#messages;
+	#toolCalls;
+	#userUtterance;
+	#agentUtterance;
+	#error;
+	#voiceIO;
+	#batch;
+	/** Incremented on each turn boundary — stale async callbacks compare against this. */
+	#generation = 0;
+	/** Accumulated chat_delta text for real-time display. */
+	#deltaAccum = "";
+	constructor(opts) {
+		this.#state = opts.state;
+		this.#messages = opts.messages;
+		this.#toolCalls = opts.toolCalls;
+		this.#userUtterance = opts.userUtterance;
+		this.#agentUtterance = opts.agentUtterance;
+		this.#error = opts.error;
+		this.#voiceIO = opts.voiceIO;
+		this.#batch = opts.batch;
+	}
+	/** Single entry point for all server→client session events. */
+	event(e) {
+		switch (e.type) {
+			case "speech_started":
+				this.#userUtterance.value = "";
+				break;
+			case "speech_stopped": break;
+			case "transcript":
+				this.#userUtterance.value = e.text;
+				break;
+			case "turn":
+				this.#generation++;
+				this.#deltaAccum = "";
+				this.#batch(() => {
+					this.#userUtterance.value = null;
+					this.#messages.value = [...this.#messages.value, {
+						role: "user",
+						content: e.text
+					}];
+					this.#state.value = "thinking";
+				});
+				break;
+			case "chat_delta":
+				this.#deltaAccum += (this.#deltaAccum ? " " : "") + e.text;
+				this.#agentUtterance.value = this.#deltaAccum;
+				break;
+			case "chat":
+				this.#deltaAccum = "";
+				this.#batch(() => {
+					this.#agentUtterance.value = null;
+					this.#messages.value = [...this.#messages.value, {
+						role: "assistant",
+						content: e.text
+					}];
+				});
+				break;
+			case "tool_call_start":
+				this.#toolCalls.value = [...this.#toolCalls.value, {
+					toolCallId: e.toolCallId,
+					toolName: e.toolName,
+					args: e.args,
+					status: "pending",
+					updates: [],
+					afterMessageIndex: this.#messages.value.length - 1
+				}];
+				break;
+			case "tool_call_update": {
+				const tcs = this.#toolCalls.value;
+				const idx = tcs.findIndex((tc) => tc.toolCallId === e.toolCallId);
+				if (idx !== -1) {
+					const updated = [...tcs];
+					const existing = updated[idx];
+					if (existing) updated[idx] = {
+						...existing,
+						updates: [...existing.updates, e.data]
+					};
+					this.#toolCalls.value = updated;
+				}
+				break;
+			}
+			case "tool_call_done": {
+				const tcs = this.#toolCalls.value;
+				const idx = tcs.findIndex((tc) => tc.toolCallId === e.toolCallId);
+				if (idx !== -1) {
+					const updated = [...tcs];
+					const existing = updated[idx];
+					if (existing) updated[idx] = {
+						...existing,
+						status: "done",
+						result: e.result
+					};
+					this.#toolCalls.value = updated;
+				}
+				break;
+			}
+			case "tts_done":
+				this.#state.value = "listening";
+				break;
+			case "cancelled":
+				this.#generation++;
+				this.#voiceIO()?.flush();
+				this.#batch(() => {
+					this.#userUtterance.value = null;
+					this.#agentUtterance.value = null;
+					this.#state.value = "listening";
+				});
+				break;
+			case "reset":
+				this.#generation++;
+				this.#voiceIO()?.flush();
+				this.#batch(() => {
+					this.#messages.value = [];
+					this.#toolCalls.value = [];
+					this.#userUtterance.value = null;
+					this.#agentUtterance.value = null;
+					this.#error.value = null;
+					this.#state.value = "listening";
+				});
+				break;
+			case "error":
+				console.error("Agent error:", e.message);
+				this.#batch(() => {
+					this.#error.value = {
+						code: e.code,
+						message: e.message
+					};
+					this.#state.value = "error";
+				});
+				break;
+			default: break;
+		}
+	}
+	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
+	playAudioChunk(chunk) {
+		if (this.#state.value === "error") return;
+		if (this.#state.value !== "speaking") this.#state.value = "speaking";
+		if (chunk.buffer instanceof ArrayBuffer) this.#voiceIO()?.enqueue(chunk.buffer);
+	}
+	/**
+	* Signal that the server has finished sending audio for this turn.
+	* Waits for the audio queue to drain, then transitions state to `"listening"`.
+	* Uses the `#generation` counter to discard stale completions from interrupted turns.
+	*/
+	playAudioDone() {
+		const gen = this.#generation;
+		const io = this.#voiceIO();
+		if (io) io.done().then(() => {
+			if (this.#generation !== gen) return;
+			this.#state.value = "listening";
+		}).catch((err) => {
+			console.warn("Audio playback done failed:", err);
+		});
+		else this.#state.value = "listening";
+	}
+	/**
+	* Dispatch an incoming WebSocket message (text or binary).
+	*
+	* Returns the parsed config if the message is a `config` message,
+	* otherwise `null`.
+	*/
+	handleMessage(data) {
+		if (data instanceof ArrayBuffer) {
+			this.playAudioChunk(new Uint8Array(data));
+			return null;
+		}
+		let msg;
+		try {
+			const parsed = ServerMessageSchema.safeParse(JSON.parse(data));
+			if (!parsed.success) {
+				console.warn("Ignoring invalid server message:", parsed.error.message);
+				return null;
+			}
+			msg = parsed.data;
+		} catch {
+			return null;
+		}
+		if (msg.type === "config") {
+			const { type: _, sessionId, ...config } = msg;
+			const parsed = ReadyConfigSchema.safeParse(config);
+			if (!parsed.success) {
+				console.warn("Unsupported server config:", parsed.error.message);
+				return null;
+			}
+			return sessionId ? {
+				...parsed.data,
+				sessionId
+			} : parsed.data;
+		}
+		if (msg.type === "audio_done") {
+			this.playAudioDone();
+			return null;
+		}
+		this.event(msg);
+		return null;
+	}
+};
+//#endregion
+//#region session.ts
+/** Built-in non-reactive container (plain mutable wrapper). */
+function plainReactive(initial) {
+	return { value: initial };
+}
+/** No-op batch — just calls the function. */
+function plainBatch(fn) {
+	fn();
+}
+/**
+* Initialize audio capture and playback after the server sends a ready config.
+*
+* Lifecycle: dynamically import audio modules → request microphone access →
+* register AudioWorklet processors → create a `VoiceIO` instance → send
+* `audio_ready` to the server → transition state to `"listening"`.
+*
+* Uses the connection `generation` counter to detect if `connect()` was called
+* while awaiting async operations; if so, the stale VoiceIO is closed immediately
+* to prevent it from being assigned to a newer connection.
+*
+* On failure (e.g. microphone permission denied, WebSocket closed mid-setup),
+* sets the error state and transitions to `"error"`.
+*
+* @param conn - The shared mutable connection state (WebSocket, VoiceIO, generation).
+* @param msg - The `ReadyConfig` from the server containing audio sample rates.
+* @param deps.send - Send a typed client message over the WebSocket.
+* @param deps.sendBinary - Send raw binary audio data over the WebSocket.
+* @param deps.state - Reactive state signal for the agent's current state.
+* @param deps.error - Reactive signal for session errors.
+* @param deps.batch - Batching function for grouping reactive updates.
+*/
+async function initAudioCapture(conn, msg, deps) {
+	if (conn.audioSetupInFlight) return;
+	conn.audioSetupInFlight = true;
+	const gen = conn.generation;
+	try {
+		const [{ createVoiceIO }, captureWorklet, playbackWorklet] = await Promise.all([
+			import("./audio.js"),
+			import("./worklets/capture-processor.js").then((m) => m.default),
+			import("./worklets/playback-processor.js").then((m) => m.default)
+		]);
+		const io = await createVoiceIO({
+			sttSampleRate: msg.sampleRate,
+			ttsSampleRate: msg.ttsSampleRate,
+			captureWorkletSrc: captureWorklet,
+			playbackWorkletSrc: playbackWorklet,
+			onMicData: (pcm16) => {
+				try {
+					deps.sendBinary(pcm16);
+				} catch {
+					console.debug("[aai-ui] sendBinary dropped: connection closed");
+				}
+			}
+		});
+		if (conn.generation !== gen || !conn.ws || conn.ws.readyState !== WebSocket.OPEN) {
+			io.close();
+			return;
+		}
+		conn.voiceIO = io;
+		deps.send({ type: "audio_ready" });
+		deps.state.value = "listening";
+	} catch (err) {
+		if (conn.generation !== gen || !conn.ws || conn.ws.readyState !== WebSocket.OPEN) return;
+		deps.batch(() => {
+			deps.error.value = {
+				code: "audio",
+				message: `Microphone access failed: ${errorMessage(err)}`
+			};
+			deps.state.value = "error";
+		});
+	} finally {
+		conn.audioSetupInFlight = false;
+	}
+}
+function buildWsUrl(platformUrl, resume, sessionId) {
+	const wsUrl = new URL("websocket", platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`);
+	wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+	if (sessionId) wsUrl.searchParams.set("sessionId", sessionId);
+	else if (resume) wsUrl.searchParams.set("resume", "1");
+	return wsUrl;
+}
+/**
+* Create a voice session that connects to an AAI server via WebSocket.
+*
+* Uses plain JSON text frames and binary audio frames for communication.
+*
+* @param options - Session configuration including the platform server URL.
+* @returns A {@link VoiceSession} handle for controlling the session.
+*
+* @public
+*/
+function createVoiceSession(options) {
+	const reactive = options.reactiveFactory ?? plainReactive;
+	const batchFn = options.batch ?? plainBatch;
+	const state = reactive("disconnected");
+	const messages = reactive([]);
+	const toolCalls = reactive([]);
+	const userUtterance = reactive(null);
+	const agentUtterance = reactive(null);
+	const error = reactive(null);
+	const disconnected = reactive(null);
+	const conn = {
+		ws: null,
+		voiceIO: null,
+		audioSetupInFlight: false,
+		generation: 0
+	};
+	let connectionController = null;
+	let hasConnected = false;
+	function cleanupAudio() {
+		conn.audioSetupInFlight = false;
+		conn.voiceIO?.close();
+		conn.voiceIO = null;
+	}
+	function resetState() {
+		batchFn(() => {
+			messages.value = [];
+			toolCalls.value = [];
+			userUtterance.value = null;
+			agentUtterance.value = null;
+			error.value = null;
+		});
+	}
+	function send(msg) {
+		if (conn.ws && conn.ws.readyState === WebSocket.OPEN) conn.ws.send(JSON.stringify(msg));
+	}
+	function sendBinary(data) {
+		if (conn.ws && conn.ws.readyState === WebSocket.OPEN) conn.ws.send(data);
+	}
+	const audioDeps = {
+		send,
+		sendBinary,
+		state,
+		error,
+		batch: batchFn
+	};
+	function connect(opts) {
+		disconnected.value = null;
+		state.value = "connecting";
+		connectionController?.abort();
+		cleanupAudio();
+		conn.ws?.close();
+		conn.ws = null;
+		conn.generation++;
+		const controller = new AbortController();
+		connectionController = controller;
+		const { signal: sig } = controller;
+		if (opts?.signal) opts.signal.addEventListener("abort", () => disconnect(), { signal: sig });
+		const resumeId = !hasConnected ? options.resumeSessionId : void 0;
+		const wsUrl = buildWsUrl(options.platformUrl, hasConnected, resumeId);
+		const socket = new WebSocket(wsUrl.toString());
+		socket.binaryType = "arraybuffer";
+		conn.ws = socket;
+		const handler = new ClientHandler({
+			state,
+			messages,
+			toolCalls,
+			userUtterance,
+			agentUtterance,
+			error,
+			voiceIO: () => conn.voiceIO,
+			batch: batchFn
+		});
+		socket.addEventListener("open", () => {
+			state.value = "ready";
+		}, { signal: sig });
+		socket.addEventListener("message", (event) => {
+			const config = handler.handleMessage(event.data);
+			if (config) {
+				if (config.sessionId) options.onSessionId?.(config.sessionId);
+				const isReconnect = hasConnected;
+				hasConnected = true;
+				initAudioCapture(conn, config, audioDeps).catch((err) => {
+					audioDeps.batch(() => {
+						audioDeps.error.value = {
+							code: "audio",
+							message: `Audio capture failed: ${errorMessage(err)}`
+						};
+						audioDeps.state.value = "error";
+					});
+				});
+				if (isReconnect && messages.value.length > 0) send({
+					type: "history",
+					messages: messages.value.map((m) => ({
+						role: m.role,
+						content: m.content
+					}))
+				});
+			}
+		}, { signal: sig });
+		socket.addEventListener("close", () => {
+			if (sig.aborted) return;
+			controller.abort();
+			disconnected.value = { intentional: false };
+			cleanupAudio();
+			state.value = "disconnected";
+		}, { signal: sig });
+	}
+	function cancel() {
+		conn.voiceIO?.flush();
+		state.value = "listening";
+		send({ type: "cancel" });
+	}
+	function reset() {
+		conn.voiceIO?.flush();
+		if (conn.ws && conn.ws.readyState === WebSocket.OPEN) {
+			send({ type: "reset" });
+			return;
+		}
+		resetState();
+		disconnect();
+		connect();
+	}
+	function disconnect() {
+		connectionController?.abort();
+		connectionController = null;
+		cleanupAudio();
+		conn.ws?.close();
+		conn.ws = null;
+		state.value = "disconnected";
+		disconnected.value = { intentional: true };
+	}
+	return {
+		state,
+		messages,
+		toolCalls,
+		userUtterance,
+		agentUtterance,
+		error,
+		disconnected,
+		connect,
+		cancel,
+		resetState,
+		reset,
+		disconnect,
+		[Symbol.dispose]() {
+			disconnect();
+		}
+	};
+}
+//#endregion
+export { ClientHandler as n, createVoiceSession as t };

package/dist/session.d.ts

@@ -1,8 +1,6 @@
-import type { ClientEvent, ReadyConfig } from "@alexkroman1/aai/protocol";
-import type { VoiceIO } from "./audio.ts";
-import type { AgentState, Message, Reactive, SessionError, SessionErrorCode, SessionOptions, ToolCallInfo } from "./types.ts";
-export type { AgentState, Message, Reactive, SessionError, SessionErrorCode, SessionOptions, ToolCallInfo, };
-type BatchFn = (fn: () => void) => void;
+import type { AgentState, ChatMessage, Reactive, SessionError, ToolCallInfo, VoiceSessionOptions } from "./types.ts";
+export { ClientHandler } from "./client-handler.ts";
+export type { AgentState, ChatMessage, Reactive, SessionError, SessionErrorCode, ToolCallInfo, VoiceSessionOptions, } from "./types.ts";
 /**
  * A reactive voice session that manages WebSocket communication,
  * audio capture/playback, and agent state transitions.
@@ -18,7 +16,7 @@ export type VoiceSession = {
     /** Current agent state (connecting, listening, thinking, etc.). */
     readonly state: Reactive<AgentState>;
     /** Chat message history for the session. */
-    readonly messages: Reactive<Message[]>;
+    readonly messages: Reactive<ChatMessage[]>;
     /** Active tool calls for the current turn. */
     readonly toolCalls: Reactive<ToolCallInfo[]>;
     /**
@@ -58,35 +56,6 @@ export type VoiceSession = {
     /** Alias for `disconnect` for use with `using`. */
     [Symbol.dispose](): void;
 };
-/**
- * Handles server→client messages and updates reactive Preact signals
- * accordingly (state transitions, transcripts, messages, audio playback).
- */
-/** @internal Exported for testing only. */
-export declare class ClientHandler {
-    #private;
-    constructor(opts: {
-        state: Reactive<AgentState>;
-        messages: Reactive<Message[]>;
-        toolCalls: Reactive<ToolCallInfo[]>;
-        userUtterance: Reactive<string | null>;
-        agentUtterance: Reactive<string | null>;
-        error: Reactive<SessionError | null>;
-        voiceIO: () => VoiceIO | null;
-        batch: BatchFn;
-    });
-    /** Single entry point for all server→client session events. */
-    event(e: ClientEvent): void;
-    playAudioChunk(chunk: Uint8Array): void;
-    playAudioDone(): void;
-    /**
-     * Dispatch an incoming WebSocket message (text or binary).
-     *
-     * Returns the parsed config if the message is a `config` message,
-     * otherwise `null`.
-     */
-    handleMessage(data: string | ArrayBuffer): ReadyConfig | null;
-}
 /**
  * Create a voice session that connects to an AAI server via WebSocket.
  *
@@ -97,4 +66,4 @@ export declare class ClientHandler {
  *
  * @public
  */
-export declare function createVoiceSession(options: SessionOptions): VoiceSession;
+export declare function createVoiceSession(options: VoiceSessionOptions): VoiceSession;