@alexkroman1/aai-ui 0.9.3 → 0.10.0

package/dist/session.js

@@ -1,359 +1,2 @@
-import { ServerMessageSchema } from "@alexkroman1/aai/protocol";
-import { errorMessage } from "@alexkroman1/aai/utils";
-//#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();
-}
-/**
-* 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;
-	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.#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.#agentUtterance.value = this.#agentUtterance.value ? `${this.#agentUtterance.value} ${e.text}` : e.text;
-				break;
-			case "chat":
-				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",
-					afterMessageIndex: this.#messages.value.length - 1
-				}];
-				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;
-		}
-	}
-	playAudioChunk(chunk) {
-		if (this.#state.value === "error") return;
-		if (this.#state.value !== "speaking") this.#state.value = "speaking";
-		this.#voiceIO()?.enqueue(chunk.buffer);
-	}
-	playAudioDone() {
-		const gen = this.#generation;
-		const io = this.#voiceIO();
-		if (io) io.done().then(() => {
-			if (this.#generation !== gen) return;
-			this.#state.value = "listening";
-		}).catch(() => {});
-		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) return null;
-			msg = parsed.data;
-		} catch {
-			return null;
-		}
-		if (msg.type === "config") {
-			const { type: _, ...config } = msg;
-			return config;
-		}
-		if (msg.type === "audio_done") {
-			this.playAudioDone();
-			return null;
-		}
-		this.event(msg);
-		return null;
-	}
-};
-/**
-* 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.signal ?? 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);
-	let ws = null;
-	let voiceIO = null;
-	let connectionController = null;
-	let hasConnected = false;
-	let audioSetupInFlight = false;
-	function cleanupAudio() {
-		audioSetupInFlight = false;
-		voiceIO?.close();
-		voiceIO = null;
-	}
-	function resetState() {
-		batchFn(() => {
-			messages.value = [];
-			toolCalls.value = [];
-			userUtterance.value = null;
-			agentUtterance.value = null;
-			error.value = null;
-		});
-	}
-	function send(msg) {
-		if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
-	}
-	function sendBinary(data) {
-		if (ws && ws.readyState === WebSocket.OPEN) ws.send(data);
-	}
-	async function handleReady(msg) {
-		if (audioSetupInFlight) return;
-		audioSetupInFlight = true;
-		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 {
-						sendBinary(pcm16);
-					} catch {}
-				}
-			});
-			if (!ws || ws.readyState !== WebSocket.OPEN) {
-				io.close();
-				return;
-			}
-			voiceIO = io;
-			send({ type: "audio_ready" });
-			state.value = "listening";
-		} catch (err) {
-			if (!ws || ws.readyState !== WebSocket.OPEN) return;
-			batchFn(() => {
-				error.value = {
-					code: "audio",
-					message: `Microphone access failed: ${errorMessage(err)}`
-				};
-				state.value = "error";
-			});
-		} finally {
-			audioSetupInFlight = false;
-		}
-	}
-	function connect(opts) {
-		disconnected.value = null;
-		state.value = "connecting";
-		connectionController?.abort();
-		cleanupAudio();
-		ws?.close();
-		ws = null;
-		const controller = new AbortController();
-		connectionController = controller;
-		const { signal: sig } = controller;
-		if (opts?.signal) opts.signal.addEventListener("abort", () => disconnect(), { signal: sig });
-		const base = options.platformUrl;
-		const wsUrl = new URL("websocket", base.endsWith("/") ? base : `${base}/`);
-		wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
-		if (hasConnected) wsUrl.searchParams.set("resume", "1");
-		const socket = new WebSocket(wsUrl.toString());
-		socket.binaryType = "arraybuffer";
-		ws = socket;
-		const handler = new ClientHandler({
-			state,
-			messages,
-			toolCalls,
-			userUtterance,
-			agentUtterance,
-			error,
-			voiceIO: () => voiceIO,
-			batch: batchFn
-		});
-		socket.addEventListener("open", () => {
-			state.value = "ready";
-		}, { signal: sig });
-		socket.addEventListener("message", (event) => {
-			const msgEvent = event;
-			const config = handler.handleMessage(msgEvent.data);
-			if (config) {
-				const isReconnect = hasConnected;
-				hasConnected = true;
-				handleReady(config);
-				if (isReconnect && messages.value.length > 0) send({
-					type: "history",
-					messages: messages.value.map((m) => ({
-						role: m.role,
-						text: 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() {
-		voiceIO?.flush();
-		state.value = "listening";
-		send({ type: "cancel" });
-	}
-	function reset() {
-		voiceIO?.flush();
-		if (ws && ws.readyState === WebSocket.OPEN) {
-			send({ type: "reset" });
-			return;
-		}
-		resetState();
-		disconnect();
-		connect();
-	}
-	function disconnect() {
-		connectionController?.abort();
-		connectionController = null;
-		cleanupAudio();
-		ws?.close();
-		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
+import { n as ClientHandler, t as createVoiceSession } from "./session-D0RdWlWH.js";
 export { ClientHandler, createVoiceSession };

package/dist/signals.d.ts

@@ -73,12 +73,60 @@ export declare function useSession(): SessionSignals;
  *
  * Automatically resets tracking when the session is reset (toolCalls cleared).
  *
+ * @example
+ * ```tsx
+ * // Filter by tool name with a typed result:
+ * useToolResult<Recipe>("get_recipe", (result, toolCall) => {
+ *   setRecipe(result);
+ * });
+ *
+ * // Receive all tool results (untyped):
+ * useToolResult((toolName, result, toolCall) => {
+ *   console.log(toolName, result);
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function useToolResult<R = unknown>(toolName: string, callback: (result: R, toolCall: ToolCallInfo) => void): void;
+/**
+ * Hook that fires a callback exactly once for each newly completed tool call.
+ *
  * @param callback - Called once per completed tool call with the tool name,
  *   parsed result, and full {@link ToolCallInfo}.
  *
  * @public
  */
 export declare function useToolResult(callback: (toolName: string, result: unknown, toolCall: ToolCallInfo) => void): void;
+/**
+ * Hook that fires a callback when a new tool call starts (status: "pending").
+ *
+ * Use this to show a loading/skeleton UI immediately when the agent invokes
+ * a tool, rather than waiting for the full result. The callback receives the
+ * tool name, parsed arguments, and the full {@link ToolCallInfo}.
+ *
+ * @param callback - Called once per new tool call at start time.
+ *
+ * @public
+ */
+export declare function useToolCallStart(callback: (toolName: string, args: Record<string, unknown>, toolCall: ToolCallInfo) => void): void;
+/**
+ * Hook that fires a callback for each intermediate update pushed by a tool
+ * via `ctx.sendUpdate()`.
+ *
+ * Use this to render progressive/streaming data from a tool before it
+ * finishes — e.g. showing a recipe preview card while nutrition data is
+ * still loading.
+ *
+ * The callback fires once per update. The `data` argument is the parsed
+ * JSON update (or raw string if parsing fails).
+ *
+ * @param callback - Called once per intermediate update with the tool name,
+ *   parsed data, and full {@link ToolCallInfo}.
+ *
+ * @public
+ */
+export declare function useToolCallUpdate(callback: (toolName: string, data: unknown, toolCall: ToolCallInfo) => void): void;
 /**
  * Auto-scroll a container to the bottom when messages, tool calls,
  * or utterances change. Returns a ref to attach to a sentinel `<div>`

package/dist/signals.js

@@ -80,40 +80,99 @@ function tryParseJSON(str) {
 		return str;
 	}
 }
+function isNewCompletedCall(tc, seen, filterName) {
+	if (tc.status !== "done" || !tc.result) return false;
+	if (seen.has(tc.toolCallId)) return false;
+	if (filterName && tc.toolName !== filterName) return false;
+	return true;
+}
+function useToolResult(toolNameOrCallback, maybeCallback) {
+	const filterName = typeof toolNameOrCallback === "string" ? toolNameOrCallback : void 0;
+	const callback = typeof toolNameOrCallback === "function" ? toolNameOrCallback : (_name, result, tc) => maybeCallback?.(result, tc);
+	const { session } = useSession();
+	const seenRef = useRef(/* @__PURE__ */ new Set());
+	const cbRef = useRef(callback);
+	cbRef.current = callback;
+	useEffect(() => effect(() => {
+		const toolCalls = session.toolCalls.value;
+		if (toolCalls.length === 0) {
+			seenRef.current.clear();
+			return;
+		}
+		for (const tc of toolCalls) {
+			if (!isNewCompletedCall(tc, seenRef.current, filterName)) continue;
+			seenRef.current.add(tc.toolCallId);
+			cbRef.current(tc.toolName, tryParseJSON(tc.result), tc);
+		}
+	}), [session]);
+}
 /**
-* Hook that fires a callback exactly once for each newly completed tool call.
-*
-* Handles deduplication internally — safe to use with `useState` setters
-* without worrying about duplicates. The `result` argument is the parsed
-* JSON result from the tool (or the raw string if parsing fails).
+* Hook that fires a callback when a new tool call starts (status: "pending").
 *
-* Automatically resets tracking when the session is reset (toolCalls cleared).
+* Use this to show a loading/skeleton UI immediately when the agent invokes
+* a tool, rather than waiting for the full result. The callback receives the
+* tool name, parsed arguments, and the full {@link ToolCallInfo}.
 *
-* @param callback - Called once per completed tool call with the tool name,
-*   parsed result, and full {@link ToolCallInfo}.
+* @param callback - Called once per new tool call at start time.
 *
 * @public
 */
-function useToolResult(callback) {
+function useToolCallStart(callback) {
 	const { session } = useSession();
 	const seenRef = useRef(/* @__PURE__ */ new Set());
 	const cbRef = useRef(callback);
 	cbRef.current = callback;
-	useEffect(() => {
-		return effect(() => {
-			const toolCalls = session.toolCalls.value;
-			if (toolCalls.length === 0) {
-				seenRef.current.clear();
-				return;
-			}
-			for (const tc of toolCalls) {
-				if (tc.status !== "done" || !tc.result) continue;
-				if (seenRef.current.has(tc.toolCallId)) continue;
-				seenRef.current.add(tc.toolCallId);
-				cbRef.current(tc.toolName, tryParseJSON(tc.result), tc);
-			}
-		});
-	}, [session]);
+	useEffect(() => effect(() => {
+		const toolCalls = session.toolCalls.value;
+		if (toolCalls.length === 0) {
+			seenRef.current.clear();
+			return;
+		}
+		for (const tc of toolCalls) {
+			if (seenRef.current.has(tc.toolCallId)) continue;
+			seenRef.current.add(tc.toolCallId);
+			cbRef.current(tc.toolName, tc.args, tc);
+		}
+	}), [session]);
+}
+/**
+* Hook that fires a callback for each intermediate update pushed by a tool
+* via `ctx.sendUpdate()`.
+*
+* Use this to render progressive/streaming data from a tool before it
+* finishes — e.g. showing a recipe preview card while nutrition data is
+* still loading.
+*
+* The callback fires once per update. The `data` argument is the parsed
+* JSON update (or raw string if parsing fails).
+*
+* @param callback - Called once per intermediate update with the tool name,
+*   parsed data, and full {@link ToolCallInfo}.
+*
+* @public
+*/
+function useToolCallUpdate(callback) {
+	const { session } = useSession();
+	const countRef = useRef(/* @__PURE__ */ new Map());
+	const cbRef = useRef(callback);
+	cbRef.current = callback;
+	useEffect(() => effect(() => {
+		const toolCalls = session.toolCalls.value;
+		if (toolCalls.length === 0) {
+			countRef.current.clear();
+			return;
+		}
+		for (const tc of toolCalls) processNewUpdates(tc, countRef.current, cbRef.current);
+	}), [session]);
+}
+function processNewUpdates(tc, seenCounts, cb) {
+	const seen = seenCounts.get(tc.toolCallId) ?? 0;
+	if (tc.updates.length <= seen) return;
+	for (let i = seen; i < tc.updates.length; i++) {
+		const raw = tc.updates[i];
+		if (raw !== void 0) cb(tc.toolName, tryParseJSON(raw), tc);
+	}
+	seenCounts.set(tc.toolCallId, tc.updates.length);
 }
 /**
 * Auto-scroll a container to the bottom when messages, tool calls,
@@ -135,4 +194,4 @@ function useAutoScroll() {
 	return ref;
 }
 //#endregion
-export { SessionProvider, createSessionControls, useAutoScroll, useSession, useToolResult };
+export { SessionProvider, createSessionControls, useAutoScroll, useSession, useToolCallStart, useToolCallUpdate, useToolResult };

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { SessionErrorCode } from "@alexkroman1/aai/protocol";
 /** Microphone buffer duration in seconds before sending to the server. */
 export declare const MIC_BUFFER_SECONDS = 0.1;
 /**
@@ -11,7 +12,7 @@ export type AgentState = "disconnected" | "connecting" | "ready" | "listening" |
  *
  * @public
  */
-export type Message = {
+export type ChatMessage = {
     /** The sender of the message. */
     role: "user" | "assistant";
     /** The text content of the message. */
@@ -28,11 +29,12 @@ export type ToolCallInfo = {
     args: Record<string, unknown>;
     status: "pending" | "done";
     result?: string | undefined;
+    /** Intermediate updates pushed by the tool via `ctx.sendUpdate()`. */
+    updates: string[];
     /** Index in the messages array where this tool call should appear. */
     afterMessageIndex: number;
 };
-import type { SessionErrorCode } from "@alexkroman1/aai/protocol";
-export type { SessionErrorCode };
+export type { SessionErrorCode } from "@alexkroman1/aai/protocol";
 /**
  * Error reported by the voice session.
  *
@@ -57,7 +59,7 @@ export type Reactive<T> = {
  *
  * @public
  */
-export type SessionOptions = {
+export type VoiceSessionOptions = {
     /** Base URL of the AAI platform server. */
     platformUrl: string;
     /**
@@ -65,11 +67,23 @@ export type SessionOptions = {
      * Defaults to a plain mutable wrapper. Pass `signal` from
      * `@preact/signals` for automatic Preact component re-rendering.
      */
-    signal?: <T>(initial: T) => Reactive<T>;
+    reactiveFactory?: <T>(initial: T) => Reactive<T>;
     /**
      * Function to batch multiple reactive updates.
      * Defaults to calling the function directly. Pass `batch` from
      * `@preact/signals` for optimized batched updates.
      */
     batch?: (fn: () => void) => void;
+    /**
+     * Called when the server sends a session ID in the config message.
+     * Use this to store the ID (e.g. in localStorage) for reconnection
+     * via `resumeSessionId`.
+     */
+    onSessionId?: ((sessionId: string) => void) | undefined;
+    /**
+     * Session ID from a previous connection. When set, the server will
+     * attempt to restore persisted session state (if the agent has
+     * `persistence` enabled).
+     */
+    resumeSessionId?: string | undefined;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "type": "module",
   "files": [
     "dist",
@@ -17,16 +17,11 @@
       "source": "./session.ts",
       "types": "./dist/session.d.ts",
       "import": "./dist/session.js"
-    },
-    "./components": {
-      "source": "./components.ts",
-      "types": "./dist/components.d.ts",
-      "import": "./dist/components.js"
     }
   },
   "dependencies": {
     "clsx": "^2.1.1",
-    "@alexkroman1/aai": "0.9.3"
+    "@alexkroman1/aai": "0.10.0"
   },
   "peerDependencies": {
     "@preact/signals": "^2.8.2",
@@ -43,14 +38,21 @@
     "@testing-library/preact": "^3.2.4",
     "jsdom": "^29.0.1",
     "preact": "^10.29.0",
-    "tsdown": "^0.21.4"
+    "tsdown": "^0.21.5"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexkroman/agent.git",
+    "directory": "packages/aai-ui"
   },
   "scripts": {
     "build": "tsdown && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "lint": "biome check ."
+    "lint": "biome check .",
+    "check:api": "api-extractor run -c api-extractor.json",
+    "check:attw": "attw --pack --profile esm-only --entrypoints . ./session"
   }
 }

package/styles.css

@@ -1,4 +1,3 @@
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap");
 @import "tailwindcss";
 @source "./";
 @source "../dist/ui/";
@@ -24,8 +23,8 @@
   --color-aai-state-speaking: #e06c75;
   --color-aai-state-error: #e06c75;
   --radius-aai: 6px;
-  --font-aai: "Inter", system-ui, -apple-system, sans-serif;
-  --font-aai-mono: "IBM Plex Mono", monospace;
+  --font-aai: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --font-aai-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
 }
 
 @layer base {