@alexkroman1/aai 1.7.0 → 1.8.0

package/dist/{ws-upgrade-BeOQ7fXL.js → ws-upgrade-CG8-by1n.js}

@@ -17,10 +17,9 @@ function toolError(message) {
 //#region sdk/ws-upgrade.ts
 /** Parse WebSocket upgrade query params into session start options. */
 function parseWsUpgradeParams(rawUrl) {
-	const search = rawUrl.includes("?") ? rawUrl.split("?")[1] ?? "" : "";
-	const params = new URLSearchParams(search);
+	const params = new URLSearchParams(rawUrl.split("?")[1] ?? "");
 	const resumeFrom = params.get("sessionId") ?? void 0;
-	const skipGreeting = params.has("resume") || resumeFrom !== void 0;
+	const skipGreeting = resumeFrom !== void 0 || params.has("resume");
 	return resumeFrom !== void 0 ? {
 		resumeFrom,
 		skipGreeting

package/host/_base64.ts

@@ -0,0 +1,9 @@
+// Copyright 2025 the AAI authors. MIT license.
+
+export function uint8ToBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64");
+}
+
+export function base64ToUint8(base64: string): Uint8Array {
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}

package/host/_mock-ws.ts

@@ -1,46 +1,16 @@
 // Copyright 2025 the AAI authors. MIT license.
 
-/**
- * A mock WebSocket implementation for testing.
- *
- * Extends `EventTarget` to simulate WebSocket behavior without a real
- * network connection. Records all sent messages in the {@link sent}
- * array and provides helper methods to simulate incoming messages,
- * connection events, and errors.
- *
- * @example
- * ```ts
- * const ws = new MockWebSocket("wss://example.com");
- * ws.send(JSON.stringify({ type: "ping" }));
- * ws.simulateMessage(JSON.stringify({ type: "pong" }));
- * assertEquals(ws.sentJson(), [{ type: "ping" }]);
- * ```
- */
 export class MockWebSocket extends EventTarget {
-  // mirrors the WebSocket API
   static readonly CONNECTING = 0;
-  // mirrors the WebSocket API
   static readonly OPEN = 1;
-  // mirrors the WebSocket API
   static readonly CLOSING = 2;
-  // mirrors the WebSocket API
   static readonly CLOSED = 3;
 
   readyState = MockWebSocket.CONNECTING;
   binaryType = "arraybuffer";
-  /** All messages passed to {@link send}, in order. */
   sent: (string | ArrayBuffer | Uint8Array)[] = [];
   url: string;
 
-  /**
-   * Create a new MockWebSocket.
-   *
-   * Automatically transitions to `OPEN` state on the next microtask,
-   * dispatching an `"open"` event.
-   *
-   * @param url - The WebSocket URL.
-   * @param _protocols - Ignored; accepted for API compatibility.
-   */
   constructor(url: string | URL, _protocols?: string | string[] | Record<string, unknown>) {
     super();
     this.url = typeof url === "string" ? url : url.toString();
@@ -64,71 +34,36 @@ export class MockWebSocket extends EventTarget {
     super.addEventListener(type, listener);
   }
 
-  /**
-   * Record a sent message without transmitting it.
-   *
-   * @param data - The message data to record.
-   */
   send(data: string | ArrayBuffer | Uint8Array) {
     this.sent.push(data);
   }
 
-  /**
-   * Transition to `CLOSED` state and dispatch a `"close"` event.
-   *
-   * @param code - The close code (defaults to 1000).
-   * @param _reason - Ignored; accepted for API compatibility.
-   */
   close(code?: number, _reason?: string) {
     this.readyState = MockWebSocket.CLOSED;
     this.dispatchEvent(Object.assign(new Event("close"), { code: code ?? 1000 }));
   }
 
-  /**
-   * Simulate receiving a message from the server.
-   *
-   * @param data - The message data (string or binary).
-   */
   simulateMessage(data: string | ArrayBuffer) {
     this.dispatchEvent(new MessageEvent("message", { data }));
   }
 
-  /** Transition to `OPEN` state and dispatch an `"open"` event. */
   open() {
     this.readyState = MockWebSocket.OPEN;
     this.dispatchEvent(new Event("open"));
   }
 
-  /**
-   * Shorthand for {@link simulateMessage}.
-   *
-   * @param data - The message data to dispatch.
-   */
   msg(data: string | ArrayBuffer) {
     this.simulateMessage(data);
   }
 
-  /**
-   * Simulate a connection close from the server.
-   *
-   * @param code - The close code (defaults to 1000).
-   */
   disconnect(code = 1000) {
     this.dispatchEvent(Object.assign(new Event("close"), { code }));
   }
 
-  /** Dispatch an `"error"` event on this socket. */
   error() {
     this.dispatchEvent(new Event("error"));
   }
 
-  /**
-   * Return all sent string messages parsed as JSON objects.
-   *
-   * Binary messages are filtered out.
-   *
-   * @returns An array of parsed JSON objects from sent string messages.
-   */
   sentJson(): Record<string, unknown>[] {
     return this.sent.filter((d): d is string => typeof d === "string").map((s) => JSON.parse(s));
   }

package/host/_pipeline-test-fakes.ts

@@ -28,8 +28,14 @@ import type {
   TtsSession,
 } from "../sdk/providers.ts";
 
+function makeCodedError<C extends string>(code: C, message: string): Error & { code: C } {
+  return Object.assign(new Error(message), { code });
+}
+
 // ─── Fake STT ───────────────────────────────────────────────────────────────
 
+type SttErrorCode = "stt_stream_error" | "stt_connect_failed" | "stt_auth_failed";
+
 export type FakeSttSession = SttSession & {
   readonly emitter: Emitter<SttEvents>;
   readonly opts: SttOpenOptions;
@@ -37,10 +43,7 @@ export type FakeSttSession = SttSession & {
   readonly closed: { value: boolean };
   firePartial(text: string): void;
   fireFinal(text: string): void;
-  fireError(
-    code: "stt_stream_error" | "stt_connect_failed" | "stt_auth_failed",
-    message: string,
-  ): void;
+  fireError(code: SttErrorCode, message: string): void;
 };
 
 export type FakeSttProvider = SttOpener & {
@@ -71,17 +74,14 @@ export function createFakeSttProvider(): FakeSttProvider {
         close: vi.fn(async () => {
           closed.value = true;
         }),
-        firePartial(text: string) {
+        firePartial(text) {
           emitter.emit("partial", text);
         },
-        fireFinal(text: string) {
+        fireFinal(text) {
           emitter.emit("final", text);
         },
         fireError(code, message) {
-          const err = Object.assign(new Error(message), { code }) as Parameters<
-            SttEvents["error"]
-          >[0];
-          emitter.emit("error", err);
+          emitter.emit("error", makeCodedError(code, message) as Parameters<SttEvents["error"]>[0]);
         },
       };
       sessions.push(session);
@@ -92,6 +92,8 @@ export function createFakeSttProvider(): FakeSttProvider {
 
 // ─── Fake TTS ───────────────────────────────────────────────────────────────
 
+type TtsErrorCode = "tts_stream_error" | "tts_connect_failed" | "tts_auth_failed";
+
 export type FakeTtsSession = TtsSession & {
   readonly emitter: Emitter<TtsEvents>;
   readonly opts: TtsOpenOptions;
@@ -101,10 +103,7 @@ export type FakeTtsSession = TtsSession & {
   readonly flush: ReturnType<typeof vi.fn<() => void>>;
   readonly cancel: ReturnType<typeof vi.fn<() => void>>;
   fireAudio(pcm: Int16Array): void;
-  fireError(
-    code: "tts_stream_error" | "tts_connect_failed" | "tts_auth_failed",
-    message: string,
-  ): void;
+  fireError(code: TtsErrorCode, message: string): void;
 };
 
 export type FakeTtsProvider = TtsOpener & {
@@ -152,14 +151,11 @@ export function createFakeTtsProvider(
         close: vi.fn(async () => {
           closed.value = true;
         }),
-        fireAudio(pcm: Int16Array) {
+        fireAudio(pcm) {
           emitter.emit("audio", pcm);
         },
         fireError(code, message) {
-          const err = Object.assign(new Error(message), { code }) as Parameters<
-            TtsEvents["error"]
-          >[0];
-          emitter.emit("error", err);
+          emitter.emit("error", makeCodedError(code, message) as Parameters<TtsEvents["error"]>[0]);
         },
       };
       sessions.push(session);
@@ -172,15 +168,11 @@ export function createFakeTtsProvider(
  * Fake STT provider that throws on `open()` with a given error code. Used to
  * test atomic provider open — TTS should not be opened at all when STT fails.
  */
-export function createFailingSttProvider(
-  code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error",
-  message: string,
-): SttOpener {
+export function createFailingSttProvider(code: SttErrorCode, message: string): SttOpener {
   return {
     name: "failing-stt",
     async open(): Promise<SttSession> {
-      const err = Object.assign(new Error(message), { code }) as Error & { code: typeof code };
-      throw err;
+      throw makeCodedError(code, message);
     },
   };
 }
@@ -189,15 +181,11 @@ export function createFailingSttProvider(
  * Fake TTS provider that throws on `open()` with a given error code. Used to
  * test atomic provider open — STT should be closed when TTS fails.
  */
-export function createFailingTtsProvider(
-  code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error",
-  message: string,
-): TtsOpener {
+export function createFailingTtsProvider(code: TtsErrorCode, message: string): TtsOpener {
   return {
     name: "failing-tts",
     async open(): Promise<TtsSession> {
-      const err = Object.assign(new Error(message), { code }) as Error & { code: typeof code };
-      throw err;
+      throw makeCodedError(code, message);
     },
   };
 }

package/host/_run-code.ts

@@ -1,8 +1,4 @@
 // Copyright 2025 the AAI authors. MIT license.
-/**
- * run_code built-in tool — executes user JavaScript in a fresh `node:vm`
- * context with no network, filesystem, or process access.
- */
 
 import vm from "node:vm";
 import { z } from "zod";
@@ -12,10 +8,6 @@ import { errorMessage } from "../sdk/utils.ts";
 
 const SKIPPED_CLASS_KEYS = new Set(["constructor", "prototype", "length", "name"]);
 
-/**
- * Copy static members from a class constructor to a wrapper function,
- * skipping built-in keys that must not be forwarded.
- */
 // biome-ignore lint/complexity/noBannedTypes: copying descriptors from arbitrary class constructors
 function copyStaticMembers(src: Function, dst: Function): void {
   for (const key of Object.getOwnPropertyNames(src)) {
@@ -24,22 +16,16 @@ function copyStaticMembers(src: Function, dst: Function): void {
       const desc = Object.getOwnPropertyDescriptor(src, key);
       if (desc) Object.defineProperty(dst, key, desc);
     } catch {
-      // Skip non-configurable properties
+      // Skip non-configurable properties.
     }
   }
 }
 
 /**
- * Neuter the `.constructor` chain on a host function or class constructor.
- *
- * For plain functions: wraps the function so calling `.constructor` or
- * `.constructor.constructor` no longer exposes the host `Function`.
- *
- * For class constructors: additionally copies static methods and neutralizes
- * `prototype.constructor` so instances created via `new` also cannot escape.
- *
- * This prevents sandbox code from reaching the host `Function` constructor
- * via patterns like `fn.constructor.constructor('return process')()`.
+ * Prevents sandbox code from reaching the host `Function` constructor via
+ * `fn.constructor.constructor('return process')()`. For class constructors
+ * we also copy static members and neuter `prototype.constructor` so
+ * instances created via `new` cannot escape either.
  */
 // biome-ignore lint/complexity/noBannedTypes: wrapping arbitrary functions and class constructors
 function neutralizeConstructor<T extends Function>(fn: T): T {
@@ -54,7 +40,6 @@ function neutralizeConstructor<T extends Function>(fn: T): T {
 
   if (hasPrototype) {
     copyStaticMembers(fn, Wrapper);
-    // Neuter prototype.constructor so instances can't escape either.
     if (Wrapper.prototype) {
       Object.defineProperty(Wrapper.prototype, "constructor", {
         value: undefined,
@@ -77,19 +62,6 @@ const runCodeParams = z.object({
   code: z.string().describe("JavaScript code to execute. Use console.log() for output."),
 });
 
-/**
- * Execute JavaScript code inside a fresh `node:vm` context.
- *
- * Each invocation creates a disposable VM context with:
- * - No filesystem access (`node:fs` and other built-ins unavailable)
- * - No network access (`fetch`, `http` unavailable)
- * - No child process spawning
- * - No environment variable access (`process` unavailable)
- * - Execution timeout (default 5 s)
- *
- * The context is discarded after execution, so no state leaks between
- * invocations or across sessions.
- */
 export function createRunCode(): ToolDef<typeof runCodeParams> & { guidance: string } {
   return {
     guidance:
@@ -105,19 +77,11 @@ export function createRunCode(): ToolDef<typeof runCodeParams> & { guidance: str
   };
 }
 
-/**
- * Execute user code in a fresh `node:vm` context.
- *
- * @remarks
- * The VM context only exposes standard ECMAScript globals and a console
- * object that captures output. Node.js APIs (`process`, `require`,
- * `import()`) are not available inside the sandbox.
- */
 export async function executeInIsolate(code: string): Promise<string | { error: string }> {
   const output: string[] = [];
   const capture = (...args: unknown[]) => output.push(args.map(String).join(" "));
 
-  // Prevent timer callbacks from leaking into host event loop after execution.
+  // Tracked so timers can't fire into the host loop after execution ends.
   const activeTimers = new Set<ReturnType<typeof setTimeout>>();
 
   const sandboxSetTimeout = (
@@ -161,9 +125,10 @@ export async function executeInIsolate(code: string): Promise<string | { error:
     }
   };
 
+  // Every host function/class is wrapped with neutralizeConstructor to block
+  // the `fn.constructor.constructor('return process')()` escape to host Function.
   const context = vm.createContext(
     {
-      // Console methods wrapped to prevent .constructor escape to host Function.
       console: Object.freeze({
         log: neutralizeConstructor(capture),
         info: neutralizeConstructor(capture),
@@ -171,12 +136,10 @@ export async function executeInIsolate(code: string): Promise<string | { error:
         error: neutralizeConstructor(capture),
         debug: neutralizeConstructor(capture),
       }),
-      // Wrapped timers — neutralized to prevent .constructor escape.
       setTimeout: neutralizeConstructor(sandboxSetTimeout),
       clearTimeout: neutralizeConstructor(sandboxClearTimeout),
       setInterval: neutralizeConstructor(sandboxSetInterval),
       clearInterval: neutralizeConstructor(sandboxClearInterval),
-      // Standard web-compat globals — constructor chain neutered.
       URL: neutralizeConstructor(URL),
       URLSearchParams: neutralizeConstructor(URLSearchParams),
       TextEncoder: neutralizeConstructor(TextEncoder),
@@ -186,28 +149,22 @@ export async function executeInIsolate(code: string): Promise<string | { error:
       structuredClone: neutralizeConstructor(structuredClone),
     },
     {
-      // Block string-based code generation within the sandbox realm.
       codeGeneration: { strings: false, wasm: false },
     },
   );
 
   try {
-    // Wrap user code in an async IIFE so top-level `await` works.
+    // Async IIFE so user code can use top-level `await`.
     const wrapped = `(async () => {\n${code}\n})()`;
     const script = new vm.Script(wrapped, { filename: "run_code.js" });
 
-    // runInContext's `timeout` enforces the execution limit.
-    const result = await script.runInContext(context, { timeout: RUN_CODE_TIMEOUT_MS });
-    void result;
+    await script.runInContext(context, { timeout: RUN_CODE_TIMEOUT_MS });
 
     const text = output.join("\n").trim();
     return text || "Code ran successfully (no output)";
   } catch (err: unknown) {
     return { error: errorMessage(err) };
   } finally {
-    // Cancel all sandbox timers that are still pending. This prevents
-    // setInterval/setTimeout callbacks from running in the host event loop
-    // after the sandbox execution has completed or timed out.
     for (const id of activeTimers) {
       clearTimeout(id);
       clearInterval(id);

package/host/_runtime-conformance.ts

@@ -7,27 +7,6 @@
  * reusable test suite that can be wired to either runtime.
  *
  * Inspired by Nitro's `testNitro()` pattern: one test fixture, many runtimes.
- *
- * @example Direct executor (unit test)
- * ```ts
- * import { testRuntime } from "./_runtime-conformance.ts";
- *
- * testRuntime("direct", () => {
- *   const exec = createRuntime({ agent: CONFORMANCE_AGENT, env: { MY_VAR: "test-value" } });
- *   return { executeTool: exec.executeTool, hooks: exec.hooks };
- * });
- * ```
- *
- * @example Sandbox (integration test in aai-server)
- * ```ts
- * // Internal module — import the .ts source directly from this package.
- * import { testRuntime } from "../../aai/host/_runtime-conformance.ts";
- *
- * testRuntime("sandbox", async () => {
- *   // ... start isolate with a bundled agent
- *   return { executeTool: buildExecuteTool(...), hooks: buildHookInvoker(...) };
- * });
- * ```
  */
 
 import { describe, expect, test } from "vitest";
@@ -35,21 +14,10 @@ import { z } from "zod";
 import type { ExecuteTool } from "../sdk/_internal-types.ts";
 import type { AgentDef } from "../sdk/types.ts";
 
-// ── Shared context type ────────────────────────────────────────────────────
-
-/**
- * Minimal runtime surface needed for conformance tests.
- *
- * Both `Runtime` and `buildExecuteTool`/`buildHookInvoker` from the
- * sandbox produce objects that satisfy this interface.
- */
 export type RuntimeTestContext = {
   executeTool: ExecuteTool;
 };
 
-// ── Conformance agent ──────────────────────────────────────────────────────
-
-/** Agent definition used by the conformance suite (direct executor path). */
 export const CONFORMANCE_AGENT: AgentDef = {
   name: "conformance-test",
   systemPrompt: "Conformance test agent.",
@@ -96,22 +64,15 @@ export const CONFORMANCE_AGENT: AgentDef = {
   },
 };
 
-// ── Shared conformance suite ───────────────────────────────────────────────
-
 /**
  * Run the runtime conformance test suite against a given runtime context.
  *
- * The `getContext` callback is invoked once per test to retrieve the
- * current {@link RuntimeTestContext}. This allows the caller to set up
- * the runtime in a `beforeAll` and return it lazily.
- *
- * All tests assume the runtime was created with {@link CONFORMANCE_AGENT}
- * (or its bundle equivalent) and `env: { MY_VAR: "test-value" }`.
+ * `getContext` is invoked once per test so callers can lazily set up the
+ * runtime in a `beforeAll`. All tests assume the runtime was created with
+ * {@link CONFORMANCE_AGENT} and `env: { MY_VAR: "test-value" }`.
  */
 export function testRuntime(label: string, getContext: () => RuntimeTestContext): void {
   describe(`runtime conformance: ${label}`, () => {
-    // ── Tool execution ───────────────────────────────────────────────
-
     test("executes tool and returns result", async () => {
       const { executeTool } = getContext();
       const result = await executeTool("echo", { text: "hello" }, "s1", []);
@@ -151,8 +112,6 @@ export function testRuntime(label: string, getContext: () => RuntimeTestContext)
       expect(vectorResult).toBe("conformance-input");
     });
 
-    // ── Session state ────────────────────────────────────────────────
-
     test("session state is initialized from factory", async () => {
       const { executeTool } = getContext();
       const result = await executeTool("get_state", {}, "state-init", []);

package/host/_test-utils.ts

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { vi } from "vitest";
 import type { AgentConfig } from "../sdk/_internal-types.ts";
-import type { ClientSink } from "../sdk/protocol.ts";
+import type { ClientEvent, ClientSink } from "../sdk/protocol.ts";
 import type { AgentDef, ToolContext, ToolDef } from "../sdk/types.ts";
 import { DEFAULT_SYSTEM_PROMPT } from "../sdk/types.ts";
 import { createRuntime } from "./runtime.ts";
@@ -111,12 +111,7 @@ export function makeClientSink(overrides?: Partial<ClientSink>): ClientSink {
   };
 }
 
-export const silentLogger: {
-  info: (...args: unknown[]) => void;
-  warn: (...args: unknown[]) => void;
-  error: (...args: unknown[]) => void;
-  debug: (...args: unknown[]) => void;
-} = {
+export const silentLogger = {
   info: vi.fn(),
   warn: vi.fn(),
   error: vi.fn(),
@@ -153,11 +148,11 @@ export type TrackingClientSink = ClientSink & {
   userTranscripts: string[];
   toolCallEvents: { callId: string; name: string; args: unknown }[];
   audioChunks: Uint8Array[];
-  replyDoneCount: number;
-  cancelledCount: number;
-  speechStartedCount: number;
-  speechStoppedCount: number;
-  events: import("../sdk/protocol.ts").ClientEvent[];
+  readonly replyDoneCount: number;
+  readonly cancelledCount: number;
+  readonly speechStartedCount: number;
+  readonly speechStoppedCount: number;
+  events: ClientEvent[];
 };
 
 export function makeTrackingClient(): TrackingClientSink {
@@ -165,11 +160,13 @@ export function makeTrackingClient(): TrackingClientSink {
   const userTranscripts: string[] = [];
   const toolCallEvents: { callId: string; name: string; args: unknown }[] = [];
   const audioChunks: Uint8Array[] = [];
-  const events: import("../sdk/protocol.ts").ClientEvent[] = [];
-  let replyDoneCount = 0;
-  let cancelledCount = 0;
-  let speechStartedCount = 0;
-  let speechStoppedCount = 0;
+  const events: ClientEvent[] = [];
+
+  function countByType(type: ClientEvent["type"]): number {
+    let n = 0;
+    for (const e of events) if (e.type === type) n++;
+    return n;
+  }
 
   return {
     open: true,
@@ -179,18 +176,18 @@ export function makeTrackingClient(): TrackingClientSink {
     audioChunks,
     events,
     get replyDoneCount() {
-      return replyDoneCount;
+      return countByType("reply_done");
     },
     get cancelledCount() {
-      return cancelledCount;
+      return countByType("cancelled");
     },
     get speechStartedCount() {
-      return speechStartedCount;
+      return countByType("speech_started");
     },
     get speechStoppedCount() {
-      return speechStoppedCount;
+      return countByType("speech_stopped");
     },
-    event: vi.fn((e: import("../sdk/protocol.ts").ClientEvent) => {
+    event: vi.fn((e: ClientEvent) => {
       events.push(e);
       switch (e.type) {
         case "agent_transcript":
@@ -202,18 +199,6 @@ export function makeTrackingClient(): TrackingClientSink {
         case "tool_call":
           toolCallEvents.push({ callId: e.toolCallId, name: e.toolName, args: e.args });
           break;
-        case "reply_done":
-          replyDoneCount++;
-          break;
-        case "cancelled":
-          cancelledCount++;
-          break;
-        case "speech_started":
-          speechStartedCount++;
-          break;
-        case "speech_stopped":
-          speechStoppedCount++;
-          break;
         default:
           break;
       }
@@ -297,14 +282,7 @@ export function createFixtureSession(
   opts?: { env?: Record<string, string> },
 ) {
   let capturedCallbacks: S2sCallbacks | null = null;
-  const fakeHandle: S2sHandle = {
-    sendAudio: vi.fn(),
-    sendAudioRaw: vi.fn(),
-    sendToolResult: vi.fn(),
-    updateSession: vi.fn(),
-    resumeSession: vi.fn(),
-    close: vi.fn(),
-  };
+  const fakeHandle = makeMockHandle();
 
   const connectSpy = vi
     .spyOn(s2sTransportInternals, "connectS2s")