@alexkroman1/aai 0.12.3 → 1.0.2

package/dist/sdk/types.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Core type definitions for the AAI agent SDK.
+ */
+import { z } from "zod";
+import type { Kv } from "./kv.ts";
+/**
+ * Identifier for a built-in server-side tool.
+ *
+ * Built-in tools run on the host process (not inside the sandboxed worker)
+ * and provide capabilities like web search, code execution, and API access.
+ *
+ * - `"web_search"` — Search the web for current information, facts, or news.
+ * - `"visit_webpage"` — Fetch a URL and return its content as clean text.
+ * - `"fetch_json"` — Call a REST API endpoint and return the JSON response.
+ * - `"run_code"` — Execute JavaScript in a sandbox for calculations and data processing.
+ *
+ * @public
+ */
+export type BuiltinTool = "web_search" | "visit_webpage" | "fetch_json" | "run_code";
+/**
+ * How the LLM should select tools during a turn.
+ *
+ * - `"auto"` — The model decides whether to call a tool (default).
+ * - `"required"` — The model must call at least one tool each step.
+ *
+ * @public
+ */
+export type ToolChoice = "auto" | "required";
+/**
+ * A single message in the conversation history.
+ *
+ * Messages are passed to tool `execute` functions via
+ * {@link ToolContext.messages} to provide conversation context.
+ *
+ * @public
+ */
+export type Message = {
+    /** The role of the message sender. */
+    role: "user" | "assistant" | "tool";
+    /** The text content of the message. */
+    content: string;
+};
+/**
+ * Context passed to tool `execute` functions.
+ *
+ * Provides access to the session environment, state, KV store, and
+ * conversation history from within a tool's execute handler.
+ *
+ * @typeParam S - The shape of per-session state created by the agent's
+ *   `state` factory. Defaults to `Record<string, unknown>`.
+ *
+ * @example
+ * ```ts
+ * import { type ToolDef } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * const myTool: ToolDef = {
+ *   description: "Look up a value from the KV store",
+ *   parameters: z.object({ key: z.string() }),
+ *   execute: async ({ key }, ctx) => {
+ *     const value = await ctx.kv.get(key);
+ *     return { key, value };
+ *   },
+ * };
+ * ```
+ *
+ * @public
+ */
+export type ToolContext<S = Record<string, unknown>> = {
+    /** Environment variables declared in the agent config. */
+    env: Readonly<Record<string, string>>;
+    /** Mutable per-session state created by the agent's `state` factory. */
+    state: S;
+    /** Key-value store scoped to this agent deployment. */
+    kv: Kv;
+    /** Read-only snapshot of conversation messages so far. */
+    messages: readonly Message[];
+    /** Unique identifier for the current session. Useful for correlating logs across concurrent sessions. */
+    sessionId: string;
+};
+/**
+ * Definition of a custom tool that the agent can invoke.
+ *
+ * Tools are the primary way to extend agent capabilities. Each tool has a
+ * description (shown to the LLM), optional Zod parameters schema, and an
+ * `execute` function that runs inside the sandboxed worker.
+ *
+ * @typeParam P - A Zod object schema describing the tool's parameters.
+ *   Defaults to `ZodObject<ZodRawShape>` so tools without parameters don't need an explicit
+ *   type argument.
+ *
+ * @example
+ * ```ts
+ * import { type ToolDef } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * const weatherTool: ToolDef<typeof params> = {
+ *   description: "Get current weather for a city",
+ *   parameters: z.object({
+ *     city: z.string().describe("City name"),
+ *   }),
+ *   execute: async ({ city }) => {
+ *     const res = await fetch(`https://wttr.in/${city}?format=j1`);
+ *     return await res.json();
+ *   },
+ * };
+ *
+ * const params = z.object({ city: z.string() });
+ * ```
+ *
+ * @public
+ */
+export type ToolDef<P extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, S = Record<string, unknown>> = {
+    /** Human-readable description shown to the LLM. */
+    description: string;
+    /** Zod schema for the tool's parameters. */
+    parameters?: P;
+    /** Function that executes the tool and returns a result. */
+    execute(args: z.infer<P>, ctx: ToolContext<S>): Promise<unknown> | unknown;
+};
+/**
+ * A mapping of tool names to their result types.
+ *
+ * Define this in a shared file (e.g. `shared.ts`) that both `agent.ts` and
+ * `client.tsx` can import, so tool result types stay in sync without
+ * duplication.
+ *
+ * @example
+ * ```ts
+ * // shared.ts
+ * import type { ToolResultMap } from "@alexkroman1/aai-cli/types";
+ *
+ * export interface Pizza {
+ *   id: number;
+ *   size: "small" | "medium" | "large";
+ *   toppings: string[];
+ * }
+ *
+ * export type MyToolResults = ToolResultMap<{
+ *   add_pizza: { added: Pizza; orderTotal: string };
+ *   place_order: { orderNumber: number; total: string };
+ * }>;
+ * ```
+ *
+ * Then use with {@link aai-ui#useToolResult | useToolResult}:
+ *
+ * ```tsx
+ * // client.tsx
+ * import type { MyToolResults } from "./shared.ts";
+ *
+ * useToolResult<MyToolResults["add_pizza"]>("add_pizza", (result) => {
+ *   console.log(result.added); // fully typed
+ * });
+ * ```
+ *
+ * @public
+ */
+export type ToolResultMap<T extends Record<string, unknown> = Record<string, unknown>> = T;
+/**
+ * Default system prompt used when `systemPrompt` is not provided.
+ *
+ * Optimized for voice-first interactions: short sentences, no visual
+ * formatting, confident tone, and concise answers.
+ */
+export declare const DEFAULT_SYSTEM_PROMPT: string;
+/** Default greeting spoken when a session starts. */
+export declare const DEFAULT_GREETING: string;
+/**
+ * Fully resolved agent definition.
+ *
+ * Core fields (`name`, `systemPrompt`, `greeting`, `maxSteps`, `tools`)
+ * are resolved to their final values with defaults applied. Optional
+ * behavioral fields (hooks, `sttPrompt`, etc.) remain optional —
+ * `undefined` means "not configured."
+ *
+ * @public
+ */
+export type AgentDef<S = Record<string, unknown>> = {
+    name: string;
+    systemPrompt: string;
+    greeting: string;
+    sttPrompt?: string;
+    maxSteps: number;
+    toolChoice?: ToolChoice;
+    builtinTools?: readonly BuiltinTool[];
+    tools: Readonly<Record<string, ToolDef<z.ZodObject<z.ZodRawShape>, S>>>;
+    state?: () => S;
+    idleTimeoutMs?: number;
+};
+/** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
+export declare const BuiltinToolSchema: z.ZodEnum<{
+    web_search: "web_search";
+    visit_webpage: "visit_webpage";
+    fetch_json: "fetch_json";
+    run_code: "run_code";
+}>;
+/** @internal Zod schema for {@link ToolChoice}. Exported for reuse in internal schemas. */
+export declare const ToolChoiceSchema: z.ZodEnum<{
+    auto: "auto";
+    required: "required";
+}>;

package/dist/sdk/ws-upgrade.d.ts

@@ -0,0 +1,5 @@
+/** Parse WebSocket upgrade query params into session start options. */
+export declare function parseWsUpgradeParams(rawUrl: string): {
+    resumeFrom?: string;
+    skipGreeting: boolean;
+};

package/dist/{system-prompt-DYAYFW99.js → system-prompt-nik_iavo.js}

@@ -1,6 +1,6 @@
-import { BuiltinToolSchema, DEFAULT_INSTRUCTIONS, ToolChoiceSchema } from "./isolate/types.js";
+import { i as ToolChoiceSchema, r as DEFAULT_SYSTEM_PROMPT, t as BuiltinToolSchema } from "./types-Cfx_4QDK.js";
 import { z } from "zod";
-//#region isolate/_internal-types.ts
+//#region sdk/_internal-types.ts
 /**
 * Zod schema for serializable agent configuration sent over the wire.
 *
@@ -9,7 +9,7 @@ import { z } from "zod";
 */
 const AgentConfigSchema = z.object({
 	name: z.string().min(1),
-	instructions: z.string(),
+	systemPrompt: z.string(),
 	greeting: z.string(),
 	sttPrompt: z.string().optional(),
 	maxSteps: z.number().int().positive().optional(),
@@ -21,11 +21,11 @@ const AgentConfigSchema = z.object({
 function toAgentConfig(src) {
 	const config = {
 		name: src.name,
-		instructions: src.instructions,
+		systemPrompt: src.systemPrompt,
 		greeting: src.greeting
 	};
 	if (src.sttPrompt !== void 0) config.sttPrompt = src.sttPrompt;
-	if (typeof src.maxSteps !== "function" && src.maxSteps !== void 0) config.maxSteps = src.maxSteps;
+	if (src.maxSteps !== void 0) config.maxSteps = src.maxSteps;
 	if (src.toolChoice !== void 0) config.toolChoice = src.toolChoice;
 	if (src.builtinTools) config.builtinTools = [...src.builtinTools];
 	if (src.idleTimeoutMs !== void 0) config.idleTimeoutMs = src.idleTimeoutMs;
@@ -58,7 +58,7 @@ function agentToolsToSchemas(tools) {
 	}));
 }
 //#endregion
-//#region isolate/system-prompt.ts
+//#region sdk/system-prompt.ts
 function getFormattedDate() {
 	return (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
 		weekday: "long",
@@ -71,10 +71,10 @@ const VOICE_RULES = "\n\nCRITICAL OUTPUT RULES — you MUST follow these for EVE
 /**
 * Build the system prompt sent to the LLM from the agent configuration.
 *
-* Assembles the default instructions, today's date, agent-specific instructions,
+* Assembles the default system prompt, today's date, agent-specific instructions,
 * and optional sections for tool usage preamble and voice output rules.
 *
-* @param config - The serializable agent configuration (name, instructions, etc.).
+* @param config - The serializable agent configuration (name, systemPrompt, etc.).
 * @param opts.hasTools - When `true`, appends a preamble instructing the LLM to
 *   speak a brief phrase before each tool call to fill silence.
 * @param opts.voice - When `true`, appends strict voice-specific output rules
@@ -83,10 +83,10 @@ const VOICE_RULES = "\n\nCRITICAL OUTPUT RULES — you MUST follow these for EVE
 */
 function buildSystemPrompt(config, opts) {
 	const { hasTools } = opts;
-	const agentInstructions = config.instructions && config.instructions !== DEFAULT_INSTRUCTIONS ? `\n\nAgent-Specific Instructions:\n${config.instructions}` : "";
+	const agentInstructions = config.systemPrompt && config.systemPrompt !== DEFAULT_SYSTEM_PROMPT ? `\n\nAgent-Specific Instructions:\n${config.systemPrompt}` : "";
 	const toolPreamble = hasTools ? "\n\nWhen you decide to use a tool, ALWAYS say a brief natural phrase BEFORE the tool call (e.g. \"Let me look that up\" or \"One moment while I check\"). This fills silence while the tool executes. Keep preambles to one short sentence." : "";
 	const guidance = opts.toolGuidance && opts.toolGuidance.length > 0 ? `\n\nBuilt-in Tool Usage:\n${opts.toolGuidance.join("\n")}` : "";
-	return DEFAULT_INSTRUCTIONS + `\n\nToday's date is ${getFormattedDate()}.` + agentInstructions + toolPreamble + guidance + (opts.voice ? VOICE_RULES : "");
+	return DEFAULT_SYSTEM_PROMPT + `\n\nToday's date is ${getFormattedDate()}.` + agentInstructions + toolPreamble + guidance + (opts.voice ? VOICE_RULES : "");
 }
 //#endregion
 export { agentToolsToSchemas as a, ToolSchemaSchema as i, AgentConfigSchema as n, toAgentConfig as o, EMPTY_PARAMS as r, buildSystemPrompt as t };

package/dist/types-Cfx_4QDK.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+//#region sdk/types.ts
+/**
+* Core type definitions for the AAI agent SDK.
+*/
+/**
+* Default system prompt used when `systemPrompt` is not provided.
+*
+* Optimized for voice-first interactions: short sentences, no visual
+* formatting, confident tone, and concise answers.
+*/
+const DEFAULT_SYSTEM_PROMPT = `\
+You are AAI, a helpful AI assistant.
+
+Voice-First Rules:
+- Optimize for natural speech. Avoid jargon unless central to the answer. \
+Use short, punchy sentences.
+- Never mention "search results," "sources," or "the provided text." \
+Speak as if the knowledge is your own.
+- No visual formatting. Do not say "bullet point," "bold," or "bracketed one." \
+If you need to list items, say "First," "Next," and "Finally."
+- Start with the most important information. No introductory filler.
+- Be concise. Keep answers to 1-3 sentences. For complex topics, provide a high-level summary.
+- Be confident. Avoid hedging phrases like "It seems that" or "I believe."
+- If you don't have enough information, say so directly rather than guessing.
+- Never use exclamation points. Keep your tone calm and conversational.`;
+/** Default greeting spoken when a session starts. */
+const DEFAULT_GREETING = "Hey there. I'm a voice assistant. What can I help you with?";
+/** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
+const BuiltinToolSchema = z.enum([
+	"web_search",
+	"visit_webpage",
+	"fetch_json",
+	"run_code"
+]);
+/** @internal Zod schema for {@link ToolChoice}. Exported for reuse in internal schemas. */
+const ToolChoiceSchema = z.enum(["auto", "required"]);
+//#endregion
+export { ToolChoiceSchema as i, DEFAULT_GREETING as n, DEFAULT_SYSTEM_PROMPT as r, BuiltinToolSchema as t };

package/dist/ws-upgrade-BeOQ7fXL.js

@@ -0,0 +1,30 @@
+//#region sdk/utils.ts
+/** Shared utility functions. */
+/** Extract an error message from an unknown thrown value. */
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** Extract a detailed error string (message + stack) for diagnostic logging. */
+function errorDetail(err) {
+	if (err instanceof Error) return err.stack ?? err.message;
+	return String(err);
+}
+/** Return a JSON error string for the LLM: `'{"error":"<message>"}'`. */
+function toolError(message) {
+	return JSON.stringify({ error: message });
+}
+//#endregion
+//#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 resumeFrom = params.get("sessionId") ?? void 0;
+	const skipGreeting = params.has("resume") || resumeFrom !== void 0;
+	return resumeFrom !== void 0 ? {
+		resumeFrom,
+		skipGreeting
+	} : { skipGreeting };
+}
+//#endregion
+export { toolError as i, errorDetail as n, errorMessage as r, parseWsUpgradeParams as t };

package/exports-no-dev-deps.test.ts

@@ -0,0 +1,62 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Regression guard: the published bundle must not import any devDependency.
+ *
+ * `tsdown` is configured with `deps.neverBundle: [/^[^./]/]`, meaning every
+ * bare npm specifier survives as an `import` in the built output. If a
+ * devDependency (e.g. `vitest`) is reachable from any public export, the
+ * production server — which only installs `dependencies` — crashes at
+ * startup with `ERR_MODULE_NOT_FOUND`.
+ *
+ * This test reads the built `dist/` files for each public export and fails
+ * if any bare import specifier is a devDependency.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "vitest";
+
+const PKG_DIR = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(PKG_DIR, "package.json"), "utf-8")) as {
+  exports: Record<string, { "@dev/source"?: string; import?: string }>;
+  devDependencies?: Record<string, string>;
+  dependencies?: Record<string, string>;
+};
+
+const devDeps = new Set(Object.keys(pkg.devDependencies ?? {}));
+
+// Extract bare module specifiers from an ESM source string. Covers:
+//   import ... from "x"      export ... from "x"      import("x")
+const IMPORT_RE =
+  /(?:\bimport\s+(?:[^"'`;]+?\s+from\s+)?|\bexport\s+(?:\*|\{[^}]*\}|[\w$,\s]+)\s+from\s+|\bimport\s*\(\s*)["']([^"']+)["']/g;
+
+function rootSpecifier(spec: string): string {
+  if (spec.startsWith("@")) return spec.split("/").slice(0, 2).join("/");
+  return spec.split("/")[0] ?? spec;
+}
+
+describe("built exports do not import devDependencies", () => {
+  const entries = Object.entries(pkg.exports)
+    .map(([subpath, val]) => ({ subpath, dist: val.import }))
+    .filter((e): e is { subpath: string; dist: string } => typeof e.dist === "string");
+
+  test.each(entries)("$subpath bundle has no devDependency import", ({ dist }) => {
+    const file = resolve(PKG_DIR, dist);
+    if (!existsSync(file)) {
+      throw new Error(
+        `Built artifact missing: ${file}. Run \`pnpm --filter @alexkroman1/aai build\` first.`,
+      );
+    }
+    const src = readFileSync(file, "utf-8");
+    const leaks = new Set<string>();
+    for (const match of src.matchAll(IMPORT_RE)) {
+      const spec = match[1];
+      if (spec === undefined) continue;
+      if (spec.startsWith(".") || spec.startsWith("node:")) continue;
+      const root = rootSpecifier(spec);
+      if (devDeps.has(root)) leaks.add(root);
+    }
+    expect([...leaks], `devDependency imports in ${dist}: ${[...leaks].join(", ")}`).toEqual([]);
+  });
+});

package/host/_mock-ws.ts

@@ -0,0 +1,185 @@
+// 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();
+    queueMicrotask(() => {
+      if (this.readyState === MockWebSocket.CONNECTING) {
+        this.readyState = MockWebSocket.OPEN;
+        this.dispatchEvent(new Event("open"));
+      }
+    });
+  }
+
+  override addEventListener(type: "close" | "open", listener: () => void): void;
+  override addEventListener(type: "message", listener: (event: { data: unknown }) => void): void;
+  override addEventListener(
+    type: "close",
+    listener: (event: { code?: number; reason?: string }) => void,
+  ): void;
+  override addEventListener(type: "error", listener: (event: { message?: string }) => void): void;
+  // biome-ignore lint/suspicious/noExplicitAny: TypeScript requires `any` for overload implementation signatures when overloads have incompatible parameter types (e.g. `() => void` vs `(event: {data: unknown}) => void`)
+  override addEventListener(type: string, listener: any): void {
+    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));
+  }
+}
+
+const g: { WebSocket: unknown } = globalThis;
+
+/**
+ * Replace `globalThis.WebSocket` with {@link 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.at(-1) ?? null;
+    },
+    restore() {
+      globalThis.WebSocket = saved;
+    },
+    [Symbol.dispose]() {
+      this.restore();
+    },
+  };
+}