@alexkroman1/aai 0.3.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@alexkroman1/aai",
+  "version": "0.3.0",
+  "type": "module",
+  "bin": {
+    "aai": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./sdk/mod.ts",
+    "./types": "./sdk/types.ts",
+    "./define-agent": "./sdk/define_agent.ts",
+    "./kv": "./sdk/kv.ts",
+    "./vector": "./sdk/vector.ts",
+    "./testing": "./sdk/_mock_ws.ts",
+    "./server": "./sdk/server.ts",
+    "./runtime": "./sdk/runtime.ts",
+    "./ui": "./ui/mod.ts",
+    "./ui/session": "./ui/session_mod.ts",
+    "./ui/components": "./ui/components_mod.ts",
+    "./internal-types": "./sdk/_internal_types.ts",
+    "./protocol": "./sdk/protocol.ts",
+    "./worker-entry": "./sdk/worker_entry.ts",
+    "./timeout": "./sdk/_timeout.ts",
+    "./builtin-tools": "./sdk/builtin_tools.ts",
+    "./s2s": "./sdk/s2s.ts",
+    "./session": "./sdk/session.ts",
+    "./system-prompt": "./sdk/system_prompt.ts",
+    "./ws-handler": "./sdk/ws_handler.ts",
+    "./direct-executor": "./sdk/direct_executor.ts",
+    "./capnweb": "./sdk/capnweb.ts",
+    "./winterc-server": "./sdk/winterc_server.ts",
+    "./worker-shim": "./sdk/worker_shim.ts"
+  },
+  "dependencies": {
+    "@chonkiejs/core": "^0",
+    "@inkjs/ui": "^2",
+    "@preact/preset-vite": "~2.9",
+    "@preact/signals": "^2.8.2",
+    "@tailwindcss/vite": "^4",
+    "@types/json-schema": "^7.0.15",
+    "chalk": "^5.4",
+    "fast-glob": "^3.3",
+    "fs-extra": "^11.3",
+    "human-id": "^4.1",
+    "ink": "^5",
+    "minimist": "^1.2",
+    "p-limit": "^7.3.0",
+    "p-timeout": "^7.0.1",
+    "preact": "^10.29.0",
+    "react": "^18",
+    "ts-morph": "^25",
+    "vite": "^6",
+    "vite-plugin-singlefile": "^2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.7",
+    "@types/fs-extra": "^11",
+    "@types/minimist": "^1.2",
+    "@types/node": "^22",
+    "@types/react": "^18",
+    "ink-testing-library": "^4",
+    "linkedom": "^0.18.10",
+    "typescript": "^5.7",
+    "vitest": "^3.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "setup": "git config core.hooksPath .githooks",
+    "build:cli": "node scripts/build-cli.mjs",
+    "test": "vitest run",
+    "lint": "biome check sdk/ ui/ cli/",
+    "lint:fix": "biome check --write sdk/ ui/ cli/",
+    "check": "biome check sdk/ ui/ cli/ && vitest run"
+  }
+}

package/sdk/_internal_types.ts

@@ -0,0 +1,89 @@
+// 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.
+ *
+ * @module
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import { z } from "zod";
+import type { BuiltinTool, ToolChoice, ToolDef, Transport } from "./types.ts";
+
+/**
+ * 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 type AgentConfig = {
+  name: string;
+  instructions: string;
+  greeting: string;
+  voice: string;
+  mode?: "s2s" | undefined;
+  sttPrompt?: string | undefined;
+  maxSteps?: number | undefined;
+  toolChoice?: ToolChoice | undefined;
+  transport?: readonly Transport[] | undefined;
+  builtinTools?: readonly BuiltinTool[] | undefined;
+  /** Default set of active tools. Can be overridden per-turn via `onBeforeStep`. */
+  activeTools?: readonly string[] | undefined;
+};
+
+/**
+ * Serialized tool schema 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 type ToolSchema = {
+  name: string;
+  description: string;
+  parameters: JSONSchema7;
+};
+
+/**
+ * Request body for the deploy endpoint.
+ *
+ * Sent by the CLI to the server when deploying a bundled agent.
+ */
+export type DeployBody = {
+  /** Env vars are optional at deploy time — set separately via `aai env add`. */
+  env?: Readonly<Record<string, string>> | undefined;
+  worker: string;
+  html: string;
+  transport?: readonly Transport[] | undefined;
+  /** Agent configuration extracted at build time. */
+  config: AgentConfig;
+  /** Tool schemas extracted at build time. */
+  toolSchemas: ToolSchema[];
+};
+
+/** Environment variables required by the agent runtime. */
+export type AgentEnv = {
+  ASSEMBLYAI_API_KEY: string;
+  [key: string]: string | undefined;
+};
+
+/** Configuration + tool schemas bundle returned by the worker's getConfig RPC. */
+export type WorkerConfig = {
+  config: AgentConfig;
+  toolSchemas: ToolSchema[];
+};
+
+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/_mock_ws.ts

@@ -0,0 +1,172 @@
+// 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 {@linkcode 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 {@linkcode 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();
+    queueMicrotask(() => {
+      if (this.readyState === MockWebSocket.CONNECTING) {
+        this.readyState = MockWebSocket.OPEN;
+        this.dispatchEvent(new Event("open"));
+      }
+    });
+  }
+
+  /**
+   * 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(new CloseEvent("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 {@linkcode simulateMessage}.
+   *
+   * @param data - The message data to dispatch.
+   */
+  msg(data: string | ArrayBuffer) {
+    this.dispatchEvent(new MessageEvent("message", { data }));
+  }
+
+  /**
+   * Simulate a connection close from the server.
+   *
+   * @param code - The close code (defaults to 1000).
+   */
+  disconnect(code = 1000) {
+    this.dispatchEvent(new CloseEvent("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));
+  }
+}
+
+const g: { WebSocket: unknown } = globalThis;
+
+/**
+ * Replace `globalThis.WebSocket` with {@linkcode MockWebSocket} for testing.
+ *
+ * Returns a handle that tracks all created mock sockets and can restore the
+ * original `WebSocket` constructor. Supports the `using` declaration via
+ * `Symbol.dispose` for automatic cleanup.
+ *
+ * @returns An object with `created` array, `lastWs` getter, `restore()`, and `[Symbol.dispose]()`.
+ *
+ * @example
+ * ```ts
+ * using mock = installMockWebSocket();
+ * const session = new Session("wss://example.com");
+ * const ws = mock.lastWs!;
+ * ws.simulateMessage(JSON.stringify({ type: "ready" }));
+ * // mock automatically restores WebSocket when disposed
+ * ```
+ */
+export function installMockWebSocket(): {
+  restore: () => void;
+  created: MockWebSocket[];
+  get lastWs(): MockWebSocket | null;
+  [Symbol.dispose]: () => void;
+} {
+  const saved = globalThis.WebSocket;
+  const created: MockWebSocket[] = [];
+
+  g.WebSocket = class extends MockWebSocket {
+    constructor(url: string | URL, protocols?: string | string[] | Record<string, unknown>) {
+      super(url, protocols);
+      created.push(this);
+    }
+  };
+
+  return {
+    created,
+    get lastWs() {
+      return created.length > 0 ? created[created.length - 1]! : null;
+    },
+    restore() {
+      globalThis.WebSocket = saved;
+    },
+    [Symbol.dispose]() {
+      globalThis.WebSocket = saved;
+    },
+  };
+}

package/sdk/_timeout.ts

@@ -0,0 +1,24 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Timeout wrapper for promises, used by both worker-side and host-side RPC.
+ *
+ * @module
+ */
+
+import pTimeout from "p-timeout";
+
+/**
+ * Wrap a promise with a timeout. Rejects with `Error` if the promise
+ * does not settle within `timeoutMs` milliseconds.
+ *
+ * If `timeoutMs` is `undefined` or `0`, the original promise is returned
+ * unchanged.
+ */
+export function withTimeout<T>(promise: Promise<T>, timeoutMs?: number): Promise<T> {
+  const normalized = Promise.resolve(promise);
+  if (!timeoutMs) return normalized;
+  return pTimeout(normalized, {
+    milliseconds: timeoutMs,
+    message: `RPC timed out after ${timeoutMs}ms`,
+  });
+}

package/sdk/builtin_tools.ts

@@ -0,0 +1,309 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Built-in tool definitions for the AAI agent SDK.
+ *
+ * These tools run inside the sandboxed worker alongside custom tools.
+ * Network requests go through the host's fetch proxy (with SSRF protection).
+ *
+ * @module
+ */
+
+import { z } from "zod";
+import type { ToolSchema } from "./_internal_types.ts";
+import type { ToolDef } from "./types.ts";
+
+const EMPTY_PARAMS = z.object({});
+
+// ─── HTML to text ──────────────────────────────────────────────────────────
+
+function htmlToText(html: string): string {
+  return html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/<(br|hr)\s*\/?>/gi, "\n")
+    .replace(/<\/(p|div|li|h[1-6]|tr|blockquote)>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#0?39;/g, "'")
+    .replace(/[ \t]+/g, " ")
+    .replace(/\n /g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+// ─── web_search ────────────────────────────────────────────────────────────
+
+const webSearchParams = z.object({
+  query: z.string().describe("The search query"),
+  max_results: z.number().describe("Maximum number of results to return (default 5)").optional(),
+});
+
+const BRAVE_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search";
+
+const BraveSearchResponseSchema = z.object({
+  web: z
+    .object({
+      results: z.array(
+        z.object({
+          title: z.string(),
+          url: z.string(),
+          description: z.string(),
+        }),
+      ),
+    })
+    .optional(),
+});
+
+function createWebSearch(): ToolDef {
+  return {
+    description:
+      "Search the web for current information, facts, news, or answers to questions. Returns a list of results with title, URL, and description. Use this when the user asks about something you don't know, need up-to-date information, or want to verify facts.",
+    parameters: webSearchParams,
+    async execute(args, ctx) {
+      const { query, max_results: maxResults = 5 } = args;
+      const apiKey = ctx.env.BRAVE_API_KEY ?? "";
+      if (!apiKey) {
+        return { error: "BRAVE_API_KEY is not set — web search unavailable" };
+      }
+      const url = `${BRAVE_SEARCH_URL}?${new URLSearchParams({
+        q: query,
+        count: String(maxResults),
+        text_decorations: "false",
+      })}`;
+      const resp = await fetch(url, {
+        headers: { "X-Subscription-Token": apiKey },
+        signal: ctx.abortSignal ?? AbortSignal.timeout(15_000),
+      });
+      if (!resp.ok) return [];
+      const raw = await resp.json();
+      const data = BraveSearchResponseSchema.safeParse(raw);
+      if (!data.success) return [];
+      return (data.data.web?.results ?? []).slice(0, maxResults).map((r) => ({
+        title: r.title,
+        url: r.url,
+        description: r.description,
+      }));
+    },
+  };
+}
+
+// ─── visit_webpage ─────────────────────────────────────────────────────────
+
+const MAX_PAGE_CHARS = 10_000;
+const MAX_HTML_BYTES = 200_000;
+
+const visitWebpageParams = z.object({
+  url: z.string().describe("The full URL to fetch (e.g., 'https://example.com/page')"),
+});
+
+function createVisitWebpage(): ToolDef {
+  return {
+    description:
+      "Fetch a webpage and return its content as clean text. Use this to read the full content of a URL found via web_search, or any link the user shares. Good for reading articles, documentation, blog posts, or product pages.",
+    parameters: visitWebpageParams,
+    async execute(args, ctx) {
+      const { url } = args;
+      const resp = await fetch(url, {
+        headers: {
+          "User-Agent":
+            "Mozilla/5.0 (compatible; VoiceAgent/1.0; +https://github.com/AssemblyAI/aai)",
+          Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        },
+        redirect: "follow",
+        signal: ctx.abortSignal ?? AbortSignal.timeout(15_000),
+      });
+      if (!resp.ok) {
+        return { error: `Failed to fetch: ${resp.status} ${resp.statusText}`, url };
+      }
+      const htmlContent = await resp.text();
+      const trimmedHtml =
+        htmlContent.length > MAX_HTML_BYTES ? htmlContent.slice(0, MAX_HTML_BYTES) : htmlContent;
+      const text = htmlToText(trimmedHtml);
+      const truncated = text.length > MAX_PAGE_CHARS;
+      const content = truncated ? text.slice(0, MAX_PAGE_CHARS) : text;
+      return {
+        url,
+        content,
+        ...(truncated ? { truncated: true, totalChars: text.length } : {}),
+      };
+    },
+  };
+}
+
+// ─── fetch_json ────────────────────────────────────────────────────────────
+
+const fetchJsonParams = z.object({
+  url: z.string().describe("The URL to fetch JSON from"),
+  headers: z
+    .record(z.string(), z.string())
+    .describe("Optional HTTP headers to include in the request")
+    .optional(),
+});
+
+function createFetchJson(): ToolDef {
+  return {
+    description:
+      "Call a REST API endpoint via HTTP GET and return the JSON response. Use this to fetch structured data from APIs — for example, weather data, stock prices, exchange rates, or any public JSON API. Supports custom headers for authenticated APIs.",
+    parameters: fetchJsonParams,
+    async execute(args, ctx) {
+      const { url, headers } = args;
+      const resp = await fetch(url, {
+        ...(headers && { headers }),
+        signal: ctx.abortSignal ?? AbortSignal.timeout(15_000),
+      });
+      if (!resp.ok) {
+        return { error: `HTTP ${resp.status} ${resp.statusText}`, url };
+      }
+      try {
+        return await resp.json();
+      } catch {
+        return { error: "Response was not valid JSON", url };
+      }
+    },
+  };
+}
+
+// ─── run_code ──────────────────────────────────────────────────────────────
+
+const runCodeParams = z.object({
+  code: z.string().describe("JavaScript code to execute. Use console.log() for output."),
+});
+
+function createRunCode(): ToolDef {
+  return {
+    description:
+      "Execute JavaScript code in a secure sandbox and return the output. Use this for calculations, data transformations, string manipulation, or any task that benefits from running code. Output is captured from console.log(). No network or filesystem access.",
+    parameters: runCodeParams,
+    async execute(args) {
+      const { code } = args;
+      const output: string[] = [];
+      function capture(...captureArgs: unknown[]) {
+        output.push(captureArgs.map(String).join(" "));
+      }
+      const fakeConsole = {
+        log: capture,
+        info: capture,
+        warn: capture,
+        error: capture,
+        debug: capture,
+      };
+      const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor;
+      try {
+        const fn = new AsyncFunction("console", code);
+        await fn(fakeConsole);
+        const result = output.join("\n").trim();
+        return result || "Code ran successfully (no output)";
+      } catch (err: unknown) {
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}
+
+// ─── vector_search ─────────────────────────────────────────────────────────
+
+const vectorSearchParams = z.object({
+  query: z
+    .string()
+    .describe(
+      "Short keyword query to search the knowledge base. Use specific topic " +
+        "terms, not full sentences. Do NOT include the company or product name " +
+        "since all documents are from the same source. For example, if the user " +
+        'asks "how much does Acme cost", search for "pricing plans rates".',
+    ),
+  topK: z.number().describe("Maximum results to return (default: 5)").optional(),
+});
+
+/** Callback for proxying vector search through the host RPC. */
+export type VectorSearchFn = (query: string, topK: number) => Promise<string>;
+
+function createVectorSearch(vectorSearchFn: VectorSearchFn): ToolDef {
+  return {
+    description:
+      "Search the agent's knowledge base for relevant information. Use this when the user asks a question that might be answered by previously ingested documents or data. Returns the most relevant matches ranked by similarity.",
+    parameters: vectorSearchParams,
+    async execute(args) {
+      const { query, topK = 5 } = args;
+      return vectorSearchFn(query, topK);
+    },
+  };
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+/** Options for creating built-in tool definitions. */
+export type BuiltinToolOptions = {
+  /** RPC callback for vector_search (proxied through host). */
+  vectorSearch?: VectorSearchFn;
+};
+
+/**
+ * Create built-in tool definitions for the given tool names.
+ *
+ * @param names - Built-in tool names from the agent config.
+ * @param opts - Options including RPC callbacks for host-proxied tools.
+ * @returns A record of tool name → ToolDef.
+ */
+export function getBuiltinToolDefs(
+  names: readonly string[],
+  opts?: BuiltinToolOptions,
+): Record<string, ToolDef> {
+  const defs: Record<string, ToolDef> = {};
+  for (const name of names) {
+    switch (name) {
+      case "web_search":
+        defs[name] = createWebSearch();
+        break;
+      case "visit_webpage":
+        defs[name] = createVisitWebpage();
+        break;
+      case "fetch_json":
+        defs[name] = createFetchJson();
+        break;
+      case "run_code":
+        defs[name] = createRunCode();
+        break;
+      case "vector_search":
+        if (opts?.vectorSearch) {
+          defs[name] = createVectorSearch(opts.vectorSearch);
+        }
+        break;
+    }
+  }
+  return defs;
+}
+
+/** All available tool creators, keyed by builtin tool name. */
+const TOOL_CREATORS: Record<string, () => ToolDef> = {
+  web_search: createWebSearch,
+  visit_webpage: createVisitWebpage,
+  fetch_json: createFetchJson,
+  run_code: createRunCode,
+  // vector_search uses a stub for schema generation
+  vector_search: () => createVectorSearch(async () => ""),
+};
+
+/**
+ * Returns JSON tool schemas for the specified builtin tools.
+ *
+ * Used by both the worker (to report schemas) and the server (to
+ * assemble tool lists for the LLM).
+ */
+export function getBuiltinToolSchemas(names: readonly string[]): ToolSchema[] {
+  return names.flatMap((name) => {
+    const creator = TOOL_CREATORS[name];
+    if (!creator) return [];
+    const def = creator();
+    return [
+      {
+        name,
+        description: def.description,
+        parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS) as ToolSchema["parameters"],
+      },
+    ];
+  });
+}