@alexkroman1/aai 0.12.2 → 1.0.2

package/host/ws-handler.ts

@@ -0,0 +1,255 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * WebSocket session lifecycle handler.
+ *
+ * Audio validation is handled at the host transport layer (see server.ts).
+ */
+
+import pTimeout from "p-timeout";
+import {
+  DEFAULT_SESSION_START_TIMEOUT_MS,
+  MAX_MESSAGE_BUFFER_SIZE,
+  WS_OPEN,
+} from "../sdk/constants.ts";
+import type { ClientMessage, ClientSink, ReadyConfig } from "../sdk/protocol.ts";
+import { ClientMessageSchema, lenientParse } from "../sdk/protocol.ts";
+import { errorDetail, errorMessage } from "../sdk/utils.ts";
+import type { Logger } from "./runtime-config.ts";
+import { consoleLogger } from "./runtime-config.ts";
+import type { Session } from "./session.ts";
+
+/**
+ * Minimal WebSocket interface accepted by {@link wireSessionSocket}.
+ *
+ * Satisfied by the standard `WebSocket` and the `ws` npm package's WebSocket.
+ */
+export type SessionWebSocket = {
+  readonly readyState: number;
+  send(data: string | ArrayBuffer | Uint8Array): void;
+  addEventListener(type: "close" | "open", listener: () => void): void;
+  addEventListener(type: "message", listener: (event: { data: unknown }) => void): void;
+  addEventListener(type: "error", listener: (event: { message?: string }) => void): void;
+};
+
+/** Options for wiring a WebSocket to a session. */
+export type WsSessionOptions = {
+  /** Map of active sessions (session is added on open, removed on close). */
+  sessions: Map<string, Session>;
+  /** Factory function to create a session for a given ID and client sink. */
+  createSession: (sessionId: string, client: ClientSink) => Session;
+  /** Protocol config sent to the client immediately on connect. */
+  readyConfig: ReadyConfig;
+  /** Additional key-value pairs included in log messages. */
+  logContext?: Record<string, string>;
+  /** Callback invoked when the WebSocket connection opens. */
+  onOpen?: () => void;
+  /** Callback invoked when the WebSocket connection closes. */
+  onClose?: () => void;
+  /** Callback invoked with the session ID after session cleanup. */
+  onSessionEnd?: (sessionId: string) => void;
+  /** Logger instance. Defaults to console. */
+  logger?: Logger;
+  /** Timeout in ms for session.start(). Defaults to 10 000 (10s). */
+  sessionStartTimeoutMs?: number;
+  /** Old session ID to resume. When set, reuses this ID instead of generating a new UUID. */
+  resumeFrom?: string;
+};
+
+/**
+ * Creates a {@link ClientSink} backed by a plain WebSocket.
+ *
+ * Text events are sent as JSON text frames; audio chunks are sent as
+ * binary frames (zero-copy).
+ */
+function createClientSink(ws: SessionWebSocket, log: Logger): ClientSink {
+  /** Send data over ws, silently dropping if the socket is not open. */
+  function safeSend(data: string | ArrayBuffer | Uint8Array): void {
+    try {
+      if (ws.readyState !== WS_OPEN) return;
+      ws.send(data);
+    } catch (err) {
+      log.debug?.("safeSend: socket closed between readyState check and send", {
+        error: errorMessage(err),
+      });
+    }
+  }
+
+  return {
+    get open() {
+      return ws.readyState === WS_OPEN;
+    },
+    event(e) {
+      safeSend(JSON.stringify(e));
+    },
+    playAudioChunk(chunk) {
+      safeSend(chunk);
+    },
+    playAudioDone() {
+      safeSend(JSON.stringify({ type: "audio_done" }));
+    },
+  };
+}
+
+function handleBinaryAudio(data: unknown, session: Session): boolean {
+  // Buffer extends Uint8Array in Node, so this catches Buffer too.
+  if (data instanceof Uint8Array) {
+    session.onAudio(data);
+    return true;
+  }
+  if (data instanceof ArrayBuffer) {
+    session.onAudio(new Uint8Array(data));
+    return true;
+  }
+  return false;
+}
+
+function handleTextMessage(
+  data: unknown,
+  session: Session,
+  log: Logger,
+  ctx: Record<string, string>,
+  sid: string,
+): void {
+  if (typeof data !== "string") return;
+  let json: unknown;
+  try {
+    json = JSON.parse(data);
+  } catch {
+    log.warn("Invalid JSON from client", { ...ctx, sid });
+    return;
+  }
+
+  const parsed = lenientParse(ClientMessageSchema, json);
+  if (!parsed.ok) {
+    if (parsed.malformed) log.warn("Invalid client message", { ...ctx, sid, error: parsed.error });
+    return;
+  }
+
+  const msg: ClientMessage = parsed.data;
+  switch (msg.type) {
+    case "audio_ready":
+      session.onAudioReady();
+      break;
+    case "cancel":
+      session.onCancel();
+      break;
+    case "reset":
+      session.onReset();
+      break;
+    case "history":
+      session.onHistory(msg.messages);
+      break;
+    default:
+      break;
+  }
+}
+
+/**
+ * Attaches session lifecycle handlers to a native WebSocket using
+ * plain JSON text frames and binary audio frames.
+ *
+ * Connection flow:
+ * 1. WebSocket opens → server sends `{ type: "config", ...ReadyConfig }`
+ * 2. Client sets up audio → sends `{ type: "audio_ready" }`
+ * 3. If reconnecting → client sends `{ type: "history", messages: [...] }`
+ */
+export function wireSessionSocket(ws: SessionWebSocket, opts: WsSessionOptions): void {
+  const { sessions, logger: log = consoleLogger } = opts;
+  const sessionId = opts.resumeFrom ?? crypto.randomUUID();
+  const sid = sessionId.slice(0, 8);
+  const ctx = opts.logContext ?? {};
+
+  let session: Session | null = null;
+  /** Set to true once session.start() resolves. Messages arriving before
+   *  this flag is set are buffered and replayed once the session is ready,
+   *  preventing audio/text from being dispatched to a half-initialized session. */
+  let sessionReady = false;
+  let messageBuffer: { data: unknown }[] | null = [];
+
+  function drainBuffer(): void {
+    if (!(session && messageBuffer)) return;
+    const buf = messageBuffer;
+    messageBuffer = null;
+    for (const event of buf) {
+      const { data } = event;
+      if (handleBinaryAudio(data, session)) continue;
+      handleTextMessage(data, session, log, ctx, sid);
+    }
+  }
+
+  function onOpen(): void {
+    opts.onOpen?.();
+    log.info("Session connected", { ...ctx, sid });
+
+    const client = createClientSink(ws, log);
+    session = opts.createSession(sessionId, client);
+    sessions.set(sessionId, session);
+
+    // Send config immediately — zero RTT. Include sessionId so the client
+    // can reconnect with ?sessionId=<id> to resume a persisted session.
+    ws.send(JSON.stringify({ type: "config", ...opts.readyConfig, sessionId }));
+
+    const timeoutMs = opts.sessionStartTimeoutMs ?? DEFAULT_SESSION_START_TIMEOUT_MS;
+    const startWithTimeout = pTimeout(session.start(), {
+      milliseconds: timeoutMs,
+      message: `session.start() timed out after ${timeoutMs}ms`,
+    });
+
+    startWithTimeout
+      .then(() => {
+        log.info("Session ready", { ...ctx, sid });
+        sessionReady = true;
+        drainBuffer();
+      })
+      .catch((err: unknown) => {
+        log.error("Session start failed", { ...ctx, sid, error: errorDetail(err) });
+        sessions.delete(sessionId);
+        session = null;
+        messageBuffer = null;
+      });
+  }
+
+  // readyState OPEN — socket already open (e.g. from ws handleUpgrade)
+  if (ws.readyState === WS_OPEN) {
+    onOpen();
+  } else {
+    ws.addEventListener("open", onOpen);
+  }
+
+  ws.addEventListener("message", (event) => {
+    if (!session) return;
+    // Buffer messages until session.start() completes to avoid dispatching
+    // to a session whose S2S connection isn't established yet.
+    if (!sessionReady) {
+      if (messageBuffer && messageBuffer.length < MAX_MESSAGE_BUFFER_SIZE) {
+        messageBuffer.push(event);
+      }
+      return;
+    }
+    const { data } = event;
+
+    if (handleBinaryAudio(data, session)) return;
+    handleTextMessage(data, session, log, ctx, sid);
+  });
+
+  ws.addEventListener("close", () => {
+    log.info("Session disconnected", { ...ctx, sid });
+    if (session) {
+      void session
+        .stop()
+        .catch((err: unknown) => {
+          log.error("Session stop failed", { ...ctx, sid, error: errorDetail(err) });
+        })
+        .finally(() => {
+          sessions.delete(sessionId);
+          opts.onSessionEnd?.(sessionId);
+        });
+    }
+    opts.onClose?.();
+  });
+
+  ws.addEventListener("error", (ev) => {
+    const msg = typeof ev.message === "string" ? ev.message : "WebSocket error";
+    log.error("WebSocket error", { ...ctx, sid, error: msg });
+  });
+}

package/index.ts

@@ -0,0 +1,16 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * aai — shared fundamentals with no Node.js dependencies.
+ *
+ * Types, KV interface, utils, and constants used across
+ * aai-cli, aai-server, and aai-ui.
+ */
+
+// biome-ignore-all lint/performance/noReExportAll: barrel file by design
+
+export * from "./sdk/constants.ts";
+export * from "./sdk/define.ts";
+export * from "./sdk/kv.ts";
+export * from "./sdk/types.ts";
+export * from "./sdk/utils.ts";
+export * from "./sdk/ws-upgrade.ts";

package/package.json

@@ -1,97 +1,51 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "0.12.2",
+  "version": "1.0.2",
   "type": "module",
-  "files": [
-    "dist"
-  ],
   "exports": {
     ".": {
       "@dev/source": "./index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./isolate": {
-      "@dev/source": "./isolate/index.ts",
-      "types": "./dist/isolate/index.d.ts",
-      "import": "./dist/isolate/index.js"
-    },
-    "./host": {
-      "@dev/source": "./host/index.ts",
-      "types": "./dist/host/index.d.ts",
-      "import": "./dist/host/index.js"
-    },
-    "./server": {
-      "@dev/source": "./host/server.ts",
-      "types": "./dist/host/server.d.ts",
-      "import": "./dist/host/server.js"
-    },
-    "./types": {
-      "@dev/source": "./isolate/types.ts",
-      "types": "./dist/isolate/types.d.ts",
-      "import": "./dist/isolate/types.js"
-    },
-    "./kv": {
-      "@dev/source": "./isolate/kv.ts",
-      "types": "./dist/isolate/kv.d.ts",
-      "import": "./dist/isolate/kv.js"
-    },
     "./protocol": {
-      "@dev/source": "./isolate/protocol.ts",
-      "types": "./dist/isolate/protocol.d.ts",
-      "import": "./dist/isolate/protocol.js"
-    },
-    "./testing": {
-      "@dev/source": "./host/testing.ts",
-      "types": "./dist/host/testing.d.ts",
-      "import": "./dist/host/testing.js"
+      "@dev/source": "./sdk/protocol.ts",
+      "types": "./dist/sdk/protocol.d.ts",
+      "import": "./dist/sdk/protocol.js"
     },
-    "./testing/matchers": {
-      "@dev/source": "./host/matchers.ts",
-      "types": "./dist/host/matchers.d.ts",
-      "import": "./dist/host/matchers.js"
+    "./runtime": {
+      "@dev/source": "./host/runtime-barrel.ts",
+      "types": "./dist/host/runtime-barrel.d.ts",
+      "import": "./dist/host/runtime-barrel.js"
     },
-    "./hooks": {
-      "@dev/source": "./isolate/hooks.ts",
-      "types": "./dist/isolate/hooks.d.ts",
-      "import": "./dist/isolate/hooks.js"
-    },
-    "./utils": {
-      "@dev/source": "./isolate/_utils.ts",
-      "types": "./dist/isolate/_utils.d.ts",
-      "import": "./dist/isolate/_utils.js"
-    },
-    "./vite-plugin": {
-      "@dev/source": "./host/vite-plugin.ts",
-      "types": "./dist/host/vite-plugin.d.ts",
-      "import": "./dist/host/vite-plugin.js"
+    "./manifest": {
+      "@dev/source": "./sdk/manifest-barrel.ts",
+      "types": "./dist/sdk/manifest-barrel.d.ts",
+      "import": "./dist/sdk/manifest-barrel.js"
     }
   },
   "dependencies": {
-    "hookable": "^6.1.0",
+    "escape-html": "^1.0.3",
+    "html-to-text": "^9.0.5",
+    "mime-types": "^3.0.2",
     "nanoevents": "^9.1.0",
     "p-timeout": "^7.0.1",
     "unstorage": "^1.17.5",
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
-  "peerDependencies": {
-    "vitest": "^4.1.1"
-  },
-  "peerDependenciesMeta": {
-    "vitest": {
-      "optional": true
-    }
-  },
   "devDependencies": {
+    "@types/escape-html": "^1.0.4",
+    "@types/html-to-text": "^9.0.4",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^25.5.0",
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^25.5.2",
     "@types/ws": "^8.18.1",
-    "tsdown": "^0.21.5",
-    "vite": "^8.0.3"
+    "tsdown": "^0.21.7",
+    "vitest": "^4.1.3"
   },
   "engines": {
-    "node": ">=22.6"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",
@@ -99,10 +53,12 @@
     "directory": "packages/aai"
   },
   "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "VITEST_INCLUDE=host/integration.test.ts,host/pentest.test.ts,host/run-code-sandbox.test.ts vitest run -c ../../vitest.slow.config.ts",
+    "check:integration": "pnpm run test:integration",
     "build": "tsdown && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit && tsc -p isolate/tsconfig.json",
-    "lint": "biome check .",
-    "check:publint": "publint",
-    "check:attw": "attw --pack --profile esm-only"
+    "typecheck": "tsc --noEmit && tsc -p sdk/tsconfig.json",
+    "lint": "biome check ."
   }
 }

package/sdk/_internal-types.test.ts

@@ -0,0 +1,34 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { expect, test } from "vitest";
+import { z } from "zod";
+import { agentToolsToSchemas } from "./_internal-types.ts";
+import type { ToolDef } from "./types.ts";
+
+test("agentToolsToSchemas - converts tool definitions to OpenAI schema", () => {
+  const tools: Record<string, ToolDef> = {
+    get_weather: {
+      description: "Get weather",
+      parameters: z.object({
+        city: z.string().describe("City"),
+      }),
+      execute: async () => {
+        /* noop */
+      },
+    },
+    set_alarm: {
+      description: "Set alarm",
+      parameters: z.object({
+        time: z.string(),
+        label: z.string().optional(),
+      }),
+      execute: async () => {
+        /* noop */
+      },
+    },
+  };
+  const schemas = agentToolsToSchemas(tools);
+  expect(schemas.length).toBe(2);
+  expect(schemas[0]?.name).toBe("get_weather");
+  expect(schemas[0]?.description).toBe("Get weather");
+  expect(schemas[1]?.name).toBe("set_alarm");
+});

package/sdk/_internal-types.ts

@@ -0,0 +1,115 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Internal type definitions shared by server and CLI.
+ *
+ * Note: this module is for internal use only and should not be used directly.
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import { z } from "zod";
+import type { Message } from "./types.ts";
+import { BuiltinToolSchema, ToolChoiceSchema, type ToolDef } from "./types.ts";
+
+/**
+ * Function signature for executing a tool by name.
+ *
+ * Used by session.ts to invoke tools, by direct-executor.ts and
+ * harness-runtime.ts to implement the execution.
+ */
+export type ExecuteTool = (
+  name: string,
+  args: Readonly<Record<string, unknown>>,
+  sessionId?: string,
+  messages?: readonly Message[],
+) => Promise<string>;
+
+// ─── AgentConfig ────────────────────────────────────────────────────────────
+
+/**
+ * Zod schema for serializable agent configuration sent over the wire.
+ *
+ * This is the JSON-safe subset of the agent definition that can be
+ * transmitted between the worker and the host process via structured clone.
+ */
+export const AgentConfigSchema = z.object({
+  name: z.string().min(1),
+  systemPrompt: z.string(),
+  greeting: z.string(),
+  sttPrompt: z.string().optional(),
+  maxSteps: z.number().int().positive().optional(),
+  toolChoice: ToolChoiceSchema.optional(),
+  builtinTools: z.array(BuiltinToolSchema).readonly().optional(),
+  idleTimeoutMs: z.number().nonnegative().optional(),
+});
+
+/** Serializable agent configuration — derived from {@link AgentConfigSchema}. */
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+
+/**
+ * Input shape accepted by {@link toAgentConfig}. Covers both `AgentDef`
+ * (where `maxSteps` may be a function) and `IsolateConfig` (where it is
+ * always a number).
+ */
+export interface AgentConfigSource {
+  name: string;
+  systemPrompt: string;
+  greeting: string;
+  sttPrompt?: string | undefined;
+  maxSteps?: number | undefined;
+  toolChoice?: AgentConfig["toolChoice"] | undefined;
+  builtinTools?: Readonly<AgentConfig["builtinTools"]> | undefined;
+  idleTimeoutMs?: number | undefined;
+}
+
+/** Extract the serializable {@link AgentConfig} subset from a source object. */
+export function toAgentConfig(src: AgentConfigSource): AgentConfig {
+  const config: AgentConfig = {
+    name: src.name,
+    systemPrompt: src.systemPrompt,
+    greeting: src.greeting,
+  };
+  if (src.sttPrompt !== undefined) config.sttPrompt = src.sttPrompt;
+  if (src.maxSteps !== undefined) config.maxSteps = src.maxSteps;
+  if (src.toolChoice !== undefined) config.toolChoice = src.toolChoice;
+  if (src.builtinTools) config.builtinTools = [...src.builtinTools];
+  if (src.idleTimeoutMs !== undefined) config.idleTimeoutMs = src.idleTimeoutMs;
+  return config;
+}
+
+// ─── ToolSchema ─────────────────────────────────────────────────────────────
+
+/**
+ * Zod schema for serialized tool definitions sent over the wire.
+ *
+ * `parameters` must be a valid JSON Schema object (with `type`, `properties`,
+ * etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
+ */
+export const ToolSchemaSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  parameters: z.record(z.string(), z.unknown()),
+});
+
+/** Serialized tool schema — derived from {@link ToolSchemaSchema}. */
+export type ToolSchema = {
+  name: string;
+  description: string;
+  parameters: JSONSchema7;
+};
+
+/** Empty Zod object schema used as default when tools have no parameters. */
+export const EMPTY_PARAMS = z.object({});
+
+/**
+ * Convert agent tool definitions to JSON Schema format for wire transport.
+ *
+ * Transforms the Zod-based `parameters` of each tool into a plain JSON Schema
+ * object suitable for structured clone / JSON serialization.
+ */
+export function agentToolsToSchemas(tools: Readonly<Record<string, ToolDef>>): ToolSchema[] {
+  return Object.entries(tools).map(([name, def]) => ({
+    name,
+    description: def.description,
+    parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS) as JSONSchema7,
+  }));
+}

package/sdk/compat-fixtures/README.md

@@ -0,0 +1,26 @@
+# Protocol Compatibility Fixtures
+
+Pinned JSON snapshots of valid wire-format messages. Unlike inline snapshot
+tests, these files **never auto-update** — they represent what
+already-deployed clients and agents actually send and receive.
+
+## When to create a new version
+
+Create a new `v{N}.json` when you intentionally change the protocol and
+have confirmed all deployed clients/agents have been updated. The old
+fixture stays to protect any stragglers.
+
+## Rules
+
+- **Never modify** an existing fixture file after it's committed.
+- **Never delete** a fixture unless you're certain no deployed code depends
+  on that version.
+- One example per variant, plus examples with/without optional fields.
+
+## What's covered
+
+- `ServerMessage` — all server-to-client WebSocket JSON messages
+- `ClientMessage` — all client-to-server WebSocket JSON messages
+- `KvRequest` — KV operations (also used by the sidecar since it shares
+  the same schema)
+- `constants` — wire-format constants (audio format, sample rates, error codes)

package/sdk/compat-fixtures/v1.json

@@ -0,0 +1,68 @@
+{
+  "version": 1,
+  "created": "2026-04-07",
+  "description": "Initial baseline: all WebSocket message types and KV operations",
+  "ServerMessage": [
+    { "type": "config", "audioFormat": "pcm16", "sampleRate": 16000, "ttsSampleRate": 24000 },
+    {
+      "type": "config",
+      "audioFormat": "pcm16",
+      "sampleRate": 16000,
+      "ttsSampleRate": 24000,
+      "sessionId": "sess_abc"
+    },
+    { "type": "audio_done" },
+    { "type": "speech_started" },
+    { "type": "speech_stopped" },
+    { "type": "user_transcript", "text": "hello" },
+    { "type": "user_transcript", "text": "hello world" },
+    { "type": "user_transcript", "text": "hello", "turnOrder": 1 },
+    { "type": "agent_transcript", "text": "response" },
+    {
+      "type": "tool_call",
+      "toolCallId": "tc1",
+      "toolName": "web_search",
+      "args": { "query": "weather" }
+    },
+    { "type": "tool_call_done", "toolCallId": "tc1", "result": "72F" },
+    { "type": "reply_done" },
+    { "type": "cancelled" },
+    { "type": "reset" },
+    { "type": "idle_timeout" },
+    { "type": "error", "code": "stt", "message": "Speech recognition failed" },
+    { "type": "error", "code": "internal", "message": "something went wrong" }
+  ],
+  "ClientMessage": [
+    { "type": "audio_ready" },
+    { "type": "cancel" },
+    { "type": "reset" },
+    {
+      "type": "history",
+      "messages": [{ "role": "user", "content": "Hello" }, { "role": "assistant", "content": "Hi" }]
+    },
+    { "type": "history", "messages": [] }
+  ],
+  "KvRequest": [
+    { "op": "get", "key": "k1" },
+    { "op": "set", "key": "k1", "value": "v1" },
+    { "op": "set", "key": "k1", "value": { "nested": true } },
+    { "op": "set", "key": "k1", "value": "v1", "expireIn": 60000 },
+    { "op": "del", "key": "k1" }
+  ],
+  "constants": {
+    "AUDIO_FORMAT": "pcm16",
+    "DEFAULT_STT_SAMPLE_RATE": 16000,
+    "DEFAULT_TTS_SAMPLE_RATE": 24000,
+    "MAX_TOOL_RESULT_CHARS": 4000,
+    "SessionErrorCodes": [
+      "stt",
+      "llm",
+      "tts",
+      "tool",
+      "protocol",
+      "connection",
+      "audio",
+      "internal"
+    ]
+  }
+}