@alexkroman1/aai 0.12.3 → 1.0.3

package/sdk/constants.ts

@@ -0,0 +1,77 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Centralised numeric constants — timeouts, size limits, sample rates.
+ *
+ * Every magic number that controls a timeout, buffer size, or threshold
+ * lives here so the values are discoverable in one place.
+ */
+
+// ─── Audio ────────────────────────────────────────────────────────────────
+
+/** Default sample rate for speech-to-text audio in Hz (AssemblyAI). */
+export const DEFAULT_STT_SAMPLE_RATE = 16_000;
+
+/** Default sample rate for text-to-speech audio in Hz. */
+export const DEFAULT_TTS_SAMPLE_RATE = 24_000;
+
+// ─── Timeouts (ms) ───────────────────────────────────────────────────────
+
+/** Default timeout for tool execution in the worker. */
+export const TOOL_EXECUTION_TIMEOUT_MS = 30_000;
+
+/** Timeout for session.start() (S2S connection setup). */
+export const DEFAULT_SESSION_START_TIMEOUT_MS = 10_000;
+
+/** S2S session idle timeout before auto-close. */
+export const DEFAULT_IDLE_TIMEOUT_MS = 300_000; // 5 minutes
+
+/** Per-fetch timeout for network tools (web_search, visit_webpage, fetch_json). */
+export const FETCH_TIMEOUT_MS = 15_000;
+
+/** Timeout for sandboxed run_code execution. */
+export const RUN_CODE_TIMEOUT_MS = 5000;
+
+/** Maximum time to wait for sessions to stop during graceful shutdown. */
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+
+// ─── Size / length limits ────────────────────────────────────────────────
+
+/** Maximum length for tool result strings sent to clients. */
+export const MAX_TOOL_RESULT_CHARS = 4000;
+
+/** Maximum chars for webpage text after HTML-to-text conversion. */
+export const MAX_PAGE_CHARS = 10_000;
+
+/** Maximum bytes to fetch from an HTML page before conversion. */
+export const MAX_HTML_BYTES = 200_000;
+
+/** Maximum value size for KV store entries (bytes). */
+export const MAX_VALUE_SIZE = 65_536;
+
+/** Maximum conversation messages to retain (sliding window). */
+export const DEFAULT_MAX_HISTORY = 200;
+
+/** Maximum WebSocket message payload size (bytes, 1 MiB). */
+export const MAX_WS_PAYLOAD_BYTES = 1 * 1024 * 1024;
+
+/** Maximum messages buffered while session.start() is pending. */
+export const MAX_MESSAGE_BUFFER_SIZE = 100;
+
+// ─── WebSocket ──────────────────────────────────────────────────────────
+
+/** WebSocket readyState value indicating the connection is open. */
+export const WS_OPEN = 1;
+
+// ─── Security ───────────────────────────────────────────────────────────
+
+/**
+ * Content-Security-Policy applied to agent UI pages (both self-hosted and
+ * platform). Single source of truth — used by `secureHeaders` middleware
+ * and per-response CSP headers.
+ */
+export const AGENT_CSP =
+  "default-src 'self'; script-src 'self' 'unsafe-eval' blob:; " +
+  "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
+  "connect-src 'self' wss: ws:; img-src 'self' data:; " +
+  "font-src 'self' https://fonts.gstatic.com; " +
+  "object-src 'none'; base-uri 'self'";

package/sdk/define.test.ts

@@ -0,0 +1,57 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { agent, tool } from "./define.ts";
+
+describe("tool()", () => {
+  test("returns the definition unchanged", () => {
+    const def = tool({
+      description: "Greet someone",
+      parameters: z.object({ name: z.string() }),
+      execute: ({ name }) => `Hello, ${name}!`,
+    });
+    expect(def.description).toBe("Greet someone");
+    expect(def.execute({ name: "Alice" }, {} as never)).toBe("Hello, Alice!");
+  });
+
+  test("works without parameters", () => {
+    const def = tool({
+      description: "No-param tool",
+      execute: () => "done",
+    });
+    expect(def.description).toBe("No-param tool");
+    expect(def.parameters).toBeUndefined();
+  });
+});
+
+describe("agent()", () => {
+  test("applies defaults", () => {
+    const def = agent({ name: "Test Agent" });
+    expect(def.name).toBe("Test Agent");
+    expect(def.systemPrompt).toContain("You are AAI");
+    expect(def.greeting).toContain("Hey there");
+    expect(def.maxSteps).toBe(5);
+    expect(def.tools).toEqual({});
+  });
+
+  test("preserves explicit values", () => {
+    const greetTool = tool({
+      description: "Greet",
+      parameters: z.object({ name: z.string() }),
+      execute: ({ name }) => `Hi ${name}`,
+    });
+    const def = agent({
+      name: "Custom",
+      systemPrompt: "Be nice.",
+      greeting: "Hello!",
+      maxSteps: 10,
+      tools: { greet: greetTool },
+      builtinTools: ["web_search"],
+    });
+    expect(def.systemPrompt).toBe("Be nice.");
+    expect(def.greeting).toBe("Hello!");
+    expect(def.maxSteps).toBe(10);
+    expect(def.tools.greet).toBe(greetTool);
+    expect(def.builtinTools).toEqual(["web_search"]);
+  });
+});

package/sdk/define.ts

@@ -0,0 +1,88 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Helper functions for defining agents and tools with full type inference.
+ */
+
+import type { z } from "zod";
+import {
+  type AgentDef,
+  type BuiltinTool,
+  DEFAULT_GREETING,
+  DEFAULT_SYSTEM_PROMPT,
+  type ToolChoice,
+  type ToolContext,
+  type ToolDef,
+} from "./types.ts";
+
+/**
+ * Define a tool with typed parameters and execute function.
+ *
+ * Identity function for type inference — returns the input unchanged.
+ * Follows the Vercel AI SDK `tool()` pattern.
+ *
+ * @example
+ * ```ts
+ * import { tool } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * const greet = tool({
+ *   description: "Greet someone by name",
+ *   parameters: z.object({ name: z.string() }),
+ *   execute: ({ name }) => `Hello, ${name}!`,
+ * });
+ * ```
+ *
+ * @public
+ */
+export function tool<P extends z.ZodObject<z.ZodRawShape>>(def: {
+  description: string;
+  parameters?: P;
+  execute(args: z.infer<P>, ctx: ToolContext): Promise<unknown> | unknown;
+}): ToolDef<P> {
+  return def;
+}
+
+/**
+ * Define an agent with tools, system prompt, and configuration.
+ *
+ * Applies sensible defaults for omitted fields. Export as the default
+ * export of your `agent.ts` file.
+ *
+ * @example
+ * ```ts
+ * import { agent, tool } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * const myTool = tool({
+ *   description: "Echo a message",
+ *   parameters: z.object({ message: z.string() }),
+ *   execute: ({ message }) => message,
+ * });
+ *
+ * export default agent({
+ *   name: "Echo Agent",
+ *   tools: { echo: myTool },
+ * });
+ * ```
+ *
+ * @public
+ */
+export function agent(def: {
+  name: string;
+  systemPrompt?: string;
+  greeting?: string;
+  tools?: Record<string, ToolDef>;
+  builtinTools?: BuiltinTool[];
+  maxSteps?: number;
+  toolChoice?: ToolChoice;
+  sttPrompt?: string;
+  idleTimeoutMs?: number;
+}): AgentDef {
+  return {
+    systemPrompt: DEFAULT_SYSTEM_PROMPT,
+    greeting: DEFAULT_GREETING,
+    maxSteps: 5,
+    tools: {},
+    ...def,
+  };
+}

package/sdk/kv.ts

@@ -0,0 +1,60 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Key-value storage interface and shared utilities.
+ */
+
+/**
+ * Async key-value store interface used by agents.
+ *
+ * Agents access the KV store via `ToolContext.kv`. Values are JSON-serialized and stored as
+ * strings with an optional TTL.
+ *
+ * @example
+ * ```ts
+ * // Inside a tool execute function:
+ * const myTool = {
+ *   description: "Save and retrieve data",
+ *   execute: async (_args: unknown, ctx: { kv: Kv }) => {
+ *     await ctx.kv.set("user:name", "Alice", { expireIn: 60_000 });
+ *     const name = await ctx.kv.get<string>("user:name");
+ *     return name; // "Alice"
+ *   },
+ * };
+ * ```
+ *
+ * @public
+ */
+export type Kv = {
+  /**
+   * Get a value by key, or `null` if not found.
+   *
+   * @typeParam T - The expected type of the stored value.
+   * @param key - The key to look up.
+   * @returns The deserialized value, or `null` if the key does not exist
+   *   or has expired.
+   */
+  get<T = unknown>(key: string): Promise<T | null>;
+  /**
+   * Set a value, optionally with a TTL in milliseconds.
+   *
+   * @param key - The key to store the value under.
+   * @param value - The value to store. Must be JSON-serializable.
+   * @param options - Optional settings. `expireIn` sets the time-to-live in **milliseconds**
+   *   (e.g. `60_000` for 1 minute). The entry is automatically removed after this duration.
+   * @throws Throws an Error if the serialized value exceeds 65,536 bytes.
+   */
+  set(key: string, value: unknown, options?: { expireIn?: number }): Promise<void>;
+  /**
+   * Delete one or more keys.
+   *
+   * @param keys - A single key or array of keys to delete. No-op for keys that do not exist.
+   */
+  delete(keys: string | string[]): Promise<void>;
+  /**
+   * Close the KV store, releasing any resources (intervals, database handles).
+   *
+   * After calling `close()`, the store must not be used. This is a no-op
+   * for implementations that hold no resources (e.g. in-memory stores).
+   */
+  close?(): void;
+};

package/sdk/manifest-barrel.ts

@@ -0,0 +1,12 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Manifest barrel — agent manifest parsing and tool schema conversion.
+ *
+ * Used by aai-cli (scanner, bundler) and aai-server (tests).
+ */
+
+// biome-ignore-all lint/performance/noReExportAll: barrel file by design
+
+export * from "./_internal-types.ts";
+export * from "./manifest.ts";
+export * from "./system-prompt.ts";

package/sdk/manifest.test.ts

@@ -0,0 +1,56 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { describe, expect, test } from "vitest";
+import { parseManifest } from "./manifest.ts";
+
+describe("parseManifest", () => {
+  test("minimal manifest requires only name", () => {
+    const result = parseManifest({ name: "Simple Agent" });
+    expect(result).toEqual({
+      name: "Simple Agent",
+      systemPrompt: expect.any(String),
+      greeting: expect.any(String),
+      maxSteps: 5,
+      toolChoice: "auto",
+      builtinTools: [],
+      tools: {},
+    });
+  });
+
+  test("full manifest passes through all fields", () => {
+    const input = {
+      name: "Weather Agent",
+      systemPrompt: "You are a weather bot.",
+      greeting: "What city?",
+      sttPrompt: "Celsius, Fahrenheit",
+      builtinTools: ["web_search"],
+      maxSteps: 10,
+      toolChoice: "required" as const,
+      idleTimeoutMs: 60_000,
+      theme: { bg: "#000", primary: "#fff" },
+      tools: {
+        get_weather: {
+          description: "Get weather",
+          parameters: {
+            type: "object",
+            properties: { city: { type: "string" } },
+            required: ["city"],
+          },
+        },
+      },
+    };
+    const result = parseManifest(input);
+    expect(result.name).toBe("Weather Agent");
+    expect(result.systemPrompt).toBe("You are a weather bot.");
+    expect(result.tools.get_weather?.description).toBe("Get weather");
+    expect(result.maxSteps).toBe(10);
+    expect(result.toolChoice).toBe("required");
+  });
+
+  test("rejects manifest without name", () => {
+    expect(() => parseManifest({})).toThrow();
+  });
+
+  test("rejects unknown builtinTools", () => {
+    expect(() => parseManifest({ name: "X", builtinTools: ["not_a_tool"] })).toThrow();
+  });
+});

package/sdk/manifest.ts

@@ -0,0 +1,89 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Canonical manifest format for directory-based agents.
+ *
+ * Flows from build → host → sdk. Validated via Zod at the boundary,
+ * then used as a plain typed object throughout the runtime.
+ */
+
+import { z } from "zod";
+import { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_SYSTEM_PROMPT } from "./types.ts";
+
+/**
+ * Tool definition as it appears in the serialized manifest JSON.
+ *
+ * This is the JSON-safe representation. Compare with `ToolDef` (in types.ts)
+ * which uses Zod schemas for parameters — `agentToolsToSchemas()` in
+ * `_internal-types.ts` converts ToolDef → ToolSchema (JSON Schema) for transport.
+ */
+export type ToolManifest = {
+  description: string;
+  parameters?: Record<string, unknown> | undefined;
+};
+
+/** Normalized agent manifest — all optional fields resolved to defaults. */
+export type Manifest = {
+  /** Agent display name (from `agent({ name: "..." })`). */
+  name: string;
+  /** System prompt sent to the LLM. Defaults to {@link DEFAULT_SYSTEM_PROMPT}. */
+  systemPrompt: string;
+  /** Initial greeting spoken to the user on connect. Defaults to {@link DEFAULT_GREETING}. */
+  greeting: string;
+  /** Optional prompt hint for the STT engine (improves transcription of domain terms). */
+  sttPrompt?: string | undefined;
+  /** Enabled built-in tools: `web_search`, `visit_webpage`, `fetch_json`, `run_code`. */
+  builtinTools: string[];
+  /** Max tool calls per LLM reply. Prevents runaway loops. Default: 5. */
+  maxSteps: number;
+  /** `"auto"` = LLM decides when to use tools; `"required"` = always call a tool. */
+  toolChoice: "auto" | "required";
+  /** Idle timeout in ms before auto-closing the session. `undefined` = use default (5 min). */
+  idleTimeoutMs?: number | undefined;
+  /** CSS custom properties for agent UI theming. */
+  theme?: Record<string, string> | undefined;
+  /** Custom tool definitions keyed by tool name. */
+  tools: Record<string, ToolManifest>;
+};
+
+const ToolManifestSchema = z.object({
+  description: z.string(),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+});
+
+const ManifestSchema = z.object({
+  name: z.string().min(1),
+  systemPrompt: z.string().optional(),
+  greeting: z.string().optional(),
+  sttPrompt: z.string().optional(),
+  builtinTools: z.array(BuiltinToolSchema).optional(),
+  maxSteps: z.number().int().positive().optional(),
+  toolChoice: z.enum(["auto", "required"]).optional(),
+  idleTimeoutMs: z.number().int().positive().optional(),
+  theme: z.record(z.string(), z.string()).optional(),
+  tools: z.record(z.string(), ToolManifestSchema).optional(),
+});
+
+/**
+ * Parse and normalize a raw agent manifest, applying defaults for all
+ * optional fields. Input is typically the JSON from a bundled agent.ts.
+ *
+ * Key defaults:
+ * - `maxSteps`: 5 — prevents runaway tool-call loops in a single reply
+ * - `toolChoice`: "auto" — LLM decides when to use tools vs respond directly
+ * - `builtinTools`: [] — no built-in tools unless explicitly opted in
+ */
+export function parseManifest(input: unknown): Manifest {
+  const parsed = ManifestSchema.parse(input);
+  return {
+    name: parsed.name,
+    systemPrompt: parsed.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
+    greeting: parsed.greeting ?? DEFAULT_GREETING,
+    sttPrompt: parsed.sttPrompt,
+    builtinTools: parsed.builtinTools ?? [],
+    maxSteps: parsed.maxSteps ?? 5,
+    toolChoice: parsed.toolChoice ?? "auto",
+    idleTimeoutMs: parsed.idleTimeoutMs,
+    theme: parsed.theme,
+    tools: parsed.tools ?? {},
+  };
+}

package/sdk/protocol-compat.test.ts

@@ -0,0 +1,187 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Protocol compatibility tests.
+ *
+ * These test pinned fixture messages against the current Zod schemas to
+ * catch breaking wire-format changes. Unlike snapshot tests, fixtures
+ * are never auto-updated — a failure here means deployed code would break.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  DEFAULT_STT_SAMPLE_RATE,
+  DEFAULT_TTS_SAMPLE_RATE,
+  MAX_TOOL_RESULT_CHARS,
+} from "./constants.ts";
+import {
+  AUDIO_FORMAT,
+  ClientMessageSchema,
+  KvRequestSchema,
+  ServerMessageSchema,
+  SessionErrorCodeSchema,
+} from "./protocol.ts";
+
+// ── Load fixtures ─────────────────────────────────────────────────────────
+
+const FIXTURE_DIR = join(import.meta.dirname, "compat-fixtures");
+const fixtureFiles = readdirSync(FIXTURE_DIR)
+  .filter((f) => f.endsWith(".json"))
+  .sort();
+
+type Fixture = {
+  version: number;
+  ServerMessage: Record<string, unknown>[];
+  ClientMessage: Record<string, unknown>[];
+  KvRequest: Record<string, unknown>[];
+  constants: {
+    AUDIO_FORMAT: string;
+    DEFAULT_STT_SAMPLE_RATE: number;
+    DEFAULT_TTS_SAMPLE_RATE: number;
+    MAX_TOOL_RESULT_CHARS: number;
+    SessionErrorCodes: string[];
+  };
+};
+
+function loadFixture(filename: string): Fixture {
+  return JSON.parse(readFileSync(join(FIXTURE_DIR, filename), "utf-8"));
+}
+
+function compatError(fixture: string, schema: string, msg: unknown, zodError: string): string {
+  return [
+    `PROTOCOL COMPATIBILITY BREAK (${fixture}, ${schema}):`,
+    "",
+    "A deployed client/server sending this message would fail:",
+    `  ${JSON.stringify(msg)}`,
+    "",
+    `Zod error: ${zodError}`,
+    "",
+    "To resolve:",
+    "  1. If UNINTENTIONAL: revert the schema change.",
+    "  2. If INTENTIONAL: create a new fixture version and document the breaking change.",
+  ].join("\n");
+}
+
+/**
+ * Check if a discriminated union schema accepts a given discriminant value
+ * by testing whether a minimal object with that value passes the first
+ * discriminant check (the full parse may fail, but the type/op is recognized).
+ */
+function schemaAcceptsType(
+  schema: typeof ServerMessageSchema | typeof ClientMessageSchema,
+  type: string,
+): boolean {
+  // Parse a minimal object with just the discriminant. If the discriminant
+  // is unrecognized, the error includes "invalid_union_discriminator" or
+  // similar. Any other failure (missing fields) means the variant exists.
+  const result = schema.safeParse({ type });
+  if (result.success) return true;
+  // Check error messages — the Zod issue code for discriminated union
+  // mismatches varies across versions, so we check the message text.
+  return !result.error.issues.some((i) => i.message.includes("Invalid discriminator"));
+}
+
+function kvSchemaAcceptsOp(op: string): boolean {
+  const result = KvRequestSchema.safeParse({ op });
+  if (result.success) return true;
+  return !result.error.issues.some((i) => i.message.includes("Invalid discriminator"));
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe.each(fixtureFiles)("compat fixture: %s", (filename) => {
+  const fixture = loadFixture(filename);
+
+  // ── Backward compat: every fixture message must still parse ──────
+
+  describe("ServerMessage backward compat", () => {
+    test.each(
+      fixture.ServerMessage.map((m, i) => [`${(m as { type: string }).type}#${i}`, m]),
+    )("%s parses against current schema", (_label, msg) => {
+      const result = ServerMessageSchema.safeParse(msg);
+      if (!result.success) {
+        throw new Error(compatError(filename, "ServerMessage", msg, result.error.message));
+      }
+    });
+  });
+
+  describe("ClientMessage backward compat", () => {
+    test.each(
+      fixture.ClientMessage.map((m, i) => [`${(m as { type: string }).type}#${i}`, m]),
+    )("%s parses against current schema", (_label, msg) => {
+      const result = ClientMessageSchema.safeParse(msg);
+      if (!result.success) {
+        throw new Error(compatError(filename, "ClientMessage", msg, result.error.message));
+      }
+    });
+  });
+
+  describe("KvRequest backward compat", () => {
+    test.each(
+      fixture.KvRequest.map((m, i) => [`${(m as { op: string }).op}#${i}`, m]),
+    )("%s parses against current schema", (_label, msg) => {
+      const result = KvRequestSchema.safeParse(msg);
+      if (!result.success) {
+        throw new Error(compatError(filename, "KvRequest", msg, result.error.message));
+      }
+    });
+  });
+
+  // ── Variant coverage: no types/ops removed ──────────────────────
+
+  describe("variant coverage", () => {
+    test("no ServerMessage types removed", () => {
+      const fixtureTypes = new Set(fixture.ServerMessage.map((m) => (m as { type: string }).type));
+      for (const t of fixtureTypes) {
+        expect(
+          schemaAcceptsType(ServerMessageSchema, t),
+          `ServerMessage variant "${t}" was removed`,
+        ).toBe(true);
+      }
+    });
+
+    test("no ClientMessage types removed", () => {
+      const fixtureTypes = new Set(fixture.ClientMessage.map((m) => (m as { type: string }).type));
+      for (const t of fixtureTypes) {
+        expect(
+          schemaAcceptsType(ClientMessageSchema, t),
+          `ClientMessage variant "${t}" was removed`,
+        ).toBe(true);
+      }
+    });
+
+    test("no KvRequest ops removed", () => {
+      const fixtureOps = new Set(fixture.KvRequest.map((m) => (m as { op: string }).op));
+      for (const op of fixtureOps) {
+        expect(kvSchemaAcceptsOp(op), `KvRequest op "${op}" was removed`).toBe(true);
+      }
+    });
+  });
+
+  // ── Constants stability ─────────────────────────────────────────
+
+  describe("constants stability", () => {
+    test("AUDIO_FORMAT unchanged", () => {
+      expect(AUDIO_FORMAT).toBe(fixture.constants.AUDIO_FORMAT);
+    });
+
+    test("DEFAULT_STT_SAMPLE_RATE unchanged", () => {
+      expect(DEFAULT_STT_SAMPLE_RATE).toBe(fixture.constants.DEFAULT_STT_SAMPLE_RATE);
+    });
+
+    test("DEFAULT_TTS_SAMPLE_RATE unchanged", () => {
+      expect(DEFAULT_TTS_SAMPLE_RATE).toBe(fixture.constants.DEFAULT_TTS_SAMPLE_RATE);
+    });
+
+    test("MAX_TOOL_RESULT_CHARS unchanged", () => {
+      expect(MAX_TOOL_RESULT_CHARS).toBe(fixture.constants.MAX_TOOL_RESULT_CHARS);
+    });
+
+    test("SessionErrorCodes is superset of fixture", () => {
+      const currentCodes = new Set<string>(SessionErrorCodeSchema.options);
+      for (const code of fixture.constants.SessionErrorCodes) {
+        expect(currentCodes.has(code), `SessionErrorCode "${code}" was removed`).toBe(true);
+      }
+    });
+  });
+});