@alexkroman1/aai 0.4.0 → 0.6.0

package/{ui/mod.ts → dist/ui/mod.js}

@@ -17,32 +17,6 @@
  *
  * @module
  */
-
-export {
-  App,
-  ChatView,
-  createSessionControls,
-  ErrorBanner,
-  MessageBubble,
-  type MountConfig,
-  type MountHandle,
-  type MountOptions,
-  type MountTheme,
-  mount,
-  SessionProvider,
-  type SessionSignals,
-  StateIndicator,
-  ThinkingIndicator,
-  Transcript,
-  useMountConfig,
-  useSession,
-} from "./components_mod.ts";
-export {
-  type AgentState,
-  createVoiceSession,
-  type Message,
-  type SessionError,
-  type SessionErrorCode,
-  type SessionOptions,
-  type VoiceSession,
-} from "./session_mod.ts";
+export { App, ChatView, createSessionControls, ErrorBanner, MessageBubble, mount, SessionProvider, StateIndicator, ThinkingIndicator, Transcript, useMountConfig, useSession, } from "./components_mod.js";
+export { createVoiceSession, } from "./session_mod.js";
+//# sourceMappingURL=mod.js.map

package/dist/ui/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../ui/mod.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,GAAG,EACH,QAAQ,EACR,qBAAqB,EACrB,WAAW,EACX,aAAa,EAKb,KAAK,EACL,eAAe,EAEf,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,UAAU,GACX,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,kBAAkB,GAMnB,MAAM,kBAAkB,CAAC"}

package/dist/ui/mount.d.ts

@@ -0,0 +1,56 @@
+import type { ComponentType } from "preact";
+import { type VoiceSession } from "./session.ts";
+import { type SessionSignals } from "./signals.ts";
+/** Theme overrides for the default UI. Applied as CSS custom properties. */
+export type MountTheme = {
+    /** Background color. Default: `#101010`. */
+    bg?: string;
+    /** Primary accent color. Default: `#fab283`. */
+    primary?: string;
+    /** Main text color. */
+    text?: string;
+    /** Surface/card color. */
+    surface?: string;
+    /** Border color. */
+    border?: string;
+};
+/** Options for {@linkcode mount}. */
+export type MountOptions = {
+    /** CSS selector or DOM element to render into. Defaults to `"#app"`. */
+    target?: string | HTMLElement;
+    /** Base URL of the AAI platform server. Derived from `location.href` by default. */
+    platformUrl?: string;
+    /** Agent title shown in the header and start screen. */
+    title?: string;
+    /** Theme color overrides. */
+    theme?: MountTheme;
+};
+/**
+ * Handle returned by {@linkcode mount} for cleanup.
+ *
+ * Implements {@linkcode Disposable} so it can be used with `using`.
+ */
+export type MountHandle = {
+    /** The underlying voice session. */
+    session: VoiceSession;
+    /** Reactive session controls for the mounted UI. */
+    signals: SessionSignals;
+    /** Unmount the UI, remove injected styles, and disconnect the session. */
+    dispose(): void;
+    /** Alias for {@linkcode dispose} for use with `using`. */
+    [Symbol.dispose](): void;
+};
+/**
+ * Mount a Preact component with voice session wiring.
+ *
+ * Creates a {@linkcode VoiceSession}, wraps it in
+ * {@linkcode SessionSignals}, and renders the component
+ * inside a {@linkcode SessionProvider}.
+ *
+ * @param Component - The Preact component to render.
+ * @param options - Mount options (target element, platform URL).
+ * @returns A {@linkcode MountHandle} for cleanup.
+ * @throws {Error} If the target element is not found in the DOM.
+ */
+export declare function mount(Component: ComponentType, options?: MountOptions): MountHandle;
+//# sourceMappingURL=mount.d.ts.map

package/dist/ui/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../ui/mount.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EAA0C,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3F,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG;IACvB,4CAA4C;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qCAAqC;AACrC,MAAM,MAAM,YAAY,GAAG;IACzB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,oCAAoC;IACpC,OAAO,EAAE,YAAY,CAAC;IACtB,oDAAoD;IACpD,OAAO,EAAE,cAAc,CAAC;IACxB,0EAA0E;IAC1E,OAAO,IAAI,IAAI,CAAC;IAChB,0DAA0D;IAC1D,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAQF;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CA2CnF"}

package/dist/ui/mount.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "preact/jsx-runtime";
+import { render } from "preact";
+import { MountConfigProvider } from "./mount_context.js";
+import { createVoiceSession } from "./session.js";
+import { createSessionControls, SessionProvider } from "./signals.js";
+function resolveContainer(target = "#app") {
+    const el = typeof target === "string" ? document.querySelector(target) : target;
+    if (!el)
+        throw new Error(`Element not found: ${target}`);
+    return el;
+}
+/**
+ * Mount a Preact component with voice session wiring.
+ *
+ * Creates a {@linkcode VoiceSession}, wraps it in
+ * {@linkcode SessionSignals}, and renders the component
+ * inside a {@linkcode SessionProvider}.
+ *
+ * @param Component - The Preact component to render.
+ * @param options - Mount options (target element, platform URL).
+ * @returns A {@linkcode MountHandle} for cleanup.
+ * @throws {Error} If the target element is not found in the DOM.
+ */
+export function mount(Component, options) {
+    const container = resolveContainer(options?.target);
+    const platformUrl = options?.platformUrl ?? globalThis.location.origin + globalThis.location.pathname;
+    const session = createVoiceSession({ platformUrl });
+    const signals = createSessionControls(session);
+    const mountConfig = { title: options?.title, theme: options?.theme };
+    // Apply theme overrides as CSS custom properties on the container.
+    if (options?.theme) {
+        const t = options.theme;
+        const el = container;
+        if (t.bg)
+            el.style.setProperty("--color-aai-bg", t.bg);
+        if (t.primary)
+            el.style.setProperty("--color-aai-primary", t.primary);
+        if (t.text)
+            el.style.setProperty("--color-aai-text", t.text);
+        if (t.surface)
+            el.style.setProperty("--color-aai-surface", t.surface);
+        if (t.border)
+            el.style.setProperty("--color-aai-border", t.border);
+    }
+    render(_jsx(MountConfigProvider, { value: mountConfig, children: _jsx(SessionProvider, { value: signals, children: _jsx(Component, {}) }) }), container);
+    const handle = {
+        session,
+        signals,
+        dispose() {
+            render(null, container);
+            signals.dispose();
+            session.disconnect();
+        },
+        [Symbol.dispose]() {
+            handle.dispose();
+        },
+    };
+    return handle;
+}
+//# sourceMappingURL=mount.js.map

package/dist/ui/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../ui/mount.tsx"],"names":[],"mappings":";AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAqB,MAAM,cAAc,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAuB,MAAM,cAAc,CAAC;AA4C3F,SAAS,gBAAgB,CAAC,SAA+B,MAAM;IAC7D,MAAM,EAAE,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAChF,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,EAAE,CAAC,CAAC;IACzD,OAAO,EAAiB,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,SAAwB,EAAE,OAAsB;IACpE,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEpD,MAAM,WAAW,GACf,OAAO,EAAE,WAAW,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;IACpF,MAAM,OAAO,GAAG,kBAAkB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/C,MAAM,WAAW,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAErE,mEAAmE;IACnE,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC;QACxB,MAAM,EAAE,GAAG,SAAwB,CAAC;QACpC,IAAI,CAAC,CAAC,EAAE;YAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,gBAAgB,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,CAAC,OAAO;YAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;QACtE,IAAI,CAAC,CAAC,IAAI;YAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7D,IAAI,CAAC,CAAC,OAAO;YAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;QACtE,IAAI,CAAC,CAAC,MAAM;YAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,CACJ,KAAC,mBAAmB,IAAC,KAAK,EAAE,WAAW,YACrC,KAAC,eAAe,IAAC,KAAK,EAAE,OAAO,YAC7B,KAAC,SAAS,KAAG,GACG,GACE,EACtB,SAAS,CACV,CAAC;IAEF,MAAM,MAAM,GAAgB;QAC1B,OAAO;QACP,OAAO;QACP,OAAO;YACL,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACxB,OAAO,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC;QACD,CAAC,MAAM,CAAC,OAAO,CAAC;YACd,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/ui/mount_context.d.ts

@@ -0,0 +1,10 @@
+import type { MountTheme } from "./mount.tsx";
+/** Resolved mount-level configuration available to default UI components. */
+export type MountConfig = {
+    title?: string | undefined;
+    theme?: MountTheme | undefined;
+};
+export declare const MountConfigProvider: import("preact").Provider<MountConfig>;
+/** Read mount config (title, theme) from the nearest provider. */
+export declare function useMountConfig(): MountConfig;
+//# sourceMappingURL=mount_context.d.ts.map

package/dist/ui/mount_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount_context.d.ts","sourceRoot":"","sources":["../../ui/mount_context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAChC,CAAC;AAIF,eAAO,MAAM,mBAAmB,wCAAe,CAAC;AAEhD,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,WAAW,CAE5C"}

package/dist/ui/mount_context.js

@@ -0,0 +1,10 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { createContext } from "preact";
+import { useContext } from "preact/hooks";
+const Ctx = createContext({});
+export const MountConfigProvider = Ctx.Provider;
+/** Read mount config (title, theme) from the nearest provider. */
+export function useMountConfig() {
+    return useContext(Ctx);
+}
+//# sourceMappingURL=mount_context.js.map

package/dist/ui/mount_context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount_context.js","sourceRoot":"","sources":["../../ui/mount_context.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAS1C,MAAM,GAAG,GAAG,aAAa,CAAc,EAAE,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC,QAAQ,CAAC;AAEhD,kEAAkE;AAClE,MAAM,UAAU,cAAc;IAC5B,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/dist/ui/session.d.ts

@@ -0,0 +1,91 @@
+import { type Signal } from "@preact/signals";
+import type { ClientEvent, ReadyConfig } from "../sdk/protocol.ts";
+import type { VoiceIO } from "./audio.ts";
+import type { AgentState, Message, SessionError, SessionOptions, ToolCallInfo } from "./types.ts";
+/**
+ * A reactive voice session that manages WebSocket communication,
+ * audio capture/playback, and agent state transitions.
+ *
+ * Uses plain JSON text frames and binary audio frames for communication
+ * and native WebSocket for the connection.
+ *
+ * Implements {@linkcode Disposable} for resource cleanup via `using`.
+ */
+export type VoiceSession = {
+    /** Current agent state (connecting, listening, thinking, etc.). */
+    readonly state: Signal<AgentState>;
+    /** Chat message history for the session. */
+    readonly messages: Signal<Message[]>;
+    /** Active tool calls for the current turn. */
+    readonly toolCalls: Signal<ToolCallInfo[]>;
+    /**
+     * Live user utterance from STT/VAD.
+     * `null` = not speaking, `""` = speech detected but no text yet,
+     * non-empty string = partial/final transcript text.
+     */
+    readonly userUtterance: Signal<string | null>;
+    /** Current session error, or `null` if no error. */
+    readonly error: Signal<SessionError | null>;
+    /** Disconnection info, or `null` if connected. */
+    readonly disconnected: Signal<{
+        intentional: boolean;
+    } | null>;
+    /**
+     * Open a WebSocket connection to the server and begin audio capture.
+     *
+     * @param options - Optional connection options.
+     * @param options.signal - An AbortSignal that, when aborted, disconnects the session.
+     */
+    connect(options?: {
+        signal?: AbortSignal;
+    }): void;
+    /** Cancel the current agent turn and discard in-flight TTS audio. */
+    cancel(): void;
+    /** Clear messages, transcript, and error state without disconnecting. */
+    resetState(): void;
+    /** Reset the session: clear state and reconnect. */
+    reset(): void;
+    /** Close the WebSocket and release all audio resources. */
+    disconnect(): void;
+    /** Alias for {@linkcode 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: Signal<AgentState>;
+        messages: Signal<Message[]>;
+        toolCalls: Signal<ToolCallInfo[]>;
+        userUtterance: Signal<string | null>;
+        error: Signal<SessionError | null>;
+        voiceIO: () => VoiceIO | null;
+    });
+    /** Single entry point for all server→client session events. */
+    /** Sentinel value indicating speech detected but no transcript yet. */
+    static readonly speechActive = "\0";
+    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.
+ *
+ * Uses plain JSON text frames and binary audio frames for communication.
+ *
+ * @param options - Session configuration including the platform server URL.
+ * @returns A {@linkcode VoiceSession} handle for controlling the session.
+ */
+export declare function createVoiceSession(options: SessionOptions): VoiceSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/ui/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../ui/session.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,MAAM,EAAU,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAiB,WAAW,EAAiB,MAAM,oBAAoB,CAAC;AAKjG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAElG;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC5C,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC/D;;;;;OAKG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,qEAAqE;IACrE,MAAM,IAAI,IAAI,CAAC;IACf,yEAAyE;IACzE,UAAU,IAAI,IAAI,CAAC;IACnB,oDAAoD;IACpD,KAAK,IAAI,IAAI,CAAC;IACd,2DAA2D;IAC3D,UAAU,IAAI,IAAI,CAAC;IACnB,6DAA6D;IAC7D,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B,CAAC;AAEF;;;GAGG;AACH,2CAA2C;AAC3C,qBAAa,aAAa;;gBASZ,IAAI,EAAE;QAChB,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAC1B,QAAQ,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5B,SAAS,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAClC,aAAa,EAAE,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACrC,KAAK,EAAE,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;QACnC,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;KAC/B;IASD,+DAA+D;IAC/D,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,YAAY,QAAU;IAEtC,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI;IAgF3B,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAQvC,aAAa,IAAI,IAAI;IAarB;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,IAAI;CA6B9D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CA2NxE"}

package/dist/ui/session.js

@@ -0,0 +1,366 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { batch, signal } from "@preact/signals";
+import { PROTOCOL_VERSION } from "../sdk/protocol.js";
+const SUPPORTED_PROTOCOL_VERSION = PROTOCOL_VERSION;
+/**
+ * Handles server→client messages and updates reactive Preact signals
+ * accordingly (state transitions, transcripts, messages, audio playback).
+ */
+/** @internal Exported for testing only. */
+export class ClientHandler {
+    #state;
+    #messages;
+    #toolCalls;
+    #userUtterance;
+    #error;
+    #voiceIO;
+    /** 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.#error = opts.error;
+        this.#voiceIO = opts.voiceIO;
+    }
+    /** Single entry point for all server→client session events. */
+    /** Sentinel value indicating speech detected but no transcript yet. */
+    static speechActive = "\x00";
+    event(e) {
+        switch (e.type) {
+            case "speech_started":
+                this.#userUtterance.value = "";
+                break;
+            case "speech_stopped":
+                // VAD detected end of speech — processing will follow.
+                break;
+            case "transcript":
+                this.#userUtterance.value = e.text;
+                break;
+            case "turn":
+                this.#generation++;
+                batch(() => {
+                    this.#userUtterance.value = null;
+                    this.#messages.value = [...this.#messages.value, { role: "user", text: e.text }];
+                    this.#state.value = "thinking";
+                });
+                break;
+            case "chat":
+                this.#messages.value = [...this.#messages.value, { role: "assistant", text: 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];
+                    updated[idx] = { ...updated[idx], status: "done", result: e.result };
+                    this.#toolCalls.value = updated;
+                }
+                break;
+            }
+            case "tts_done":
+                // No-audio turns (empty LLM result) still use this event
+                // to transition back to listening. Audio turns signal via stream end.
+                this.#state.value = "listening";
+                break;
+            case "cancelled":
+                this.#generation++;
+                this.#voiceIO()?.flush();
+                this.#userUtterance.value = null;
+                this.#state.value = "listening";
+                break;
+            case "reset": {
+                this.#generation++;
+                this.#voiceIO()?.flush();
+                batch(() => {
+                    this.#messages.value = [];
+                    this.#toolCalls.value = [];
+                    this.#userUtterance.value = null;
+                    this.#error.value = null;
+                    this.#state.value = "listening";
+                });
+                break;
+            }
+            case "error":
+                console.error("Agent error:", e.message);
+                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) {
+            void io.done().then(() => {
+                if (this.#generation !== gen)
+                    return;
+                this.#state.value = "listening";
+            });
+        }
+        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) {
+        // Binary frame → raw PCM16 TTS audio
+        if (data instanceof ArrayBuffer) {
+            this.playAudioChunk(new Uint8Array(data));
+            return null;
+        }
+        // Text frame → JSON message
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+        if (msg.type === "config") {
+            const { type: _, ...config } = msg;
+            return config;
+        }
+        if (msg.type === "audio_done") {
+            this.playAudioDone();
+            return null;
+        }
+        // All other messages are ClientEvent
+        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 {@linkcode VoiceSession} handle for controlling the session.
+ */
+export function createVoiceSession(options) {
+    const state = signal("disconnected");
+    const messages = signal([]);
+    const toolCalls = signal([]);
+    const userUtterance = signal(null);
+    const error = signal(null);
+    const disconnected = signal(null);
+    let ws = null;
+    let voiceIO = null;
+    let connectionController = null;
+    let hasConnected = false;
+    let audioSetupInFlight = false;
+    function cleanupAudio() {
+        audioSetupInFlight = false;
+        void voiceIO?.close();
+        voiceIO = null;
+    }
+    function resetState() {
+        batch(() => {
+            messages.value = [];
+            toolCalls.value = [];
+            userUtterance.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;
+        // Protocol version check
+        if (msg.protocolVersion !== SUPPORTED_PROTOCOL_VERSION) {
+            batch(() => {
+                error.value = {
+                    code: "protocol",
+                    message: `Server protocol v${msg.protocolVersion} is not compatible with client v${SUPPORTED_PROTOCOL_VERSION}. Please redeploy your agent.`,
+                };
+                state.value = "error";
+            });
+            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) => {
+                    // Always stream audio — S2S handles VAD natively.
+                    try {
+                        sendBinary(pcm16);
+                    }
+                    catch {
+                        /* connection may be closed */
+                    }
+                },
+            });
+            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;
+            batch(() => {
+                error.value = {
+                    code: "audio",
+                    message: `Microphone access failed: ${err instanceof Error ? err.message : String(err)}`,
+                };
+                state.value = "error";
+            });
+        }
+        finally {
+            audioSetupInFlight = false;
+        }
+    }
+    function connect(opts) {
+        disconnected.value = null;
+        state.value = "connecting";
+        connectionController?.abort();
+        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,
+            error,
+            voiceIO: () => voiceIO,
+        });
+        socket.addEventListener("open", () => {
+            state.value = "ready";
+        }, { signal: sig });
+        socket.addEventListener("message", (event) => {
+            const msgEvent = event;
+            const config = handler.handleMessage(msgEvent.data);
+            if (config) {
+                hasConnected = true;
+                void handleReady(config);
+                // Send history if reconnecting
+                if (hasConnected && messages.value.length > 0) {
+                    send({
+                        type: "history",
+                        messages: messages.value.map((m) => ({
+                            role: m.role,
+                            text: m.text,
+                        })),
+                    });
+                }
+            }
+        }, { 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,
+        error,
+        disconnected,
+        connect,
+        cancel,
+        resetState,
+        reset,
+        disconnect,
+        [Symbol.dispose]() {
+            disconnect();
+        },
+    };
+}
+//# sourceMappingURL=session.js.map