@alexkroman1/aai 0.8.8 → 0.9.0

package/dist/{sdk/_internal_types.d.ts → _internal-types.d.ts}

@@ -2,8 +2,6 @@
  * 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";
@@ -56,4 +54,3 @@ export declare const EMPTY_PARAMS: z.ZodObject<{}, z.core.$strip>;
  * object suitable for structured clone / JSON serialization.
  */
 export declare function agentToolsToSchemas(tools: Readonly<Record<string, ToolDef>>): ToolSchema[];
-//# sourceMappingURL=_internal_types.d.ts.map

package/dist/_internal-types.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+//#region _internal-types.ts
+/** Empty Zod object schema used as default when tools have no parameters. */
+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.
+*/
+function agentToolsToSchemas(tools) {
+	return Object.entries(tools).map(([name, def]) => ({
+		name,
+		description: def.description,
+		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
+	}));
+}
+//#endregion
+export { EMPTY_PARAMS, agentToolsToSchemas };

package/dist/{sdk/_mock_ws.d.ts → _mock-ws.d.ts}

@@ -2,7 +2,7 @@
  * 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}
+ * network connection. Records all sent messages in the {@link sent}
  * array and provides helper methods to simulate incoming messages,
  * connection events, and errors.
  *
@@ -21,7 +21,7 @@ export declare class MockWebSocket extends EventTarget {
     static readonly CLOSED = 3;
     readyState: number;
     binaryType: string;
-    /** All messages passed to {@linkcode send}, in order. */
+    /** All messages passed to {@link send}, in order. */
     sent: (string | ArrayBuffer | Uint8Array)[];
     url: string;
     /**
@@ -34,6 +34,18 @@ export declare class MockWebSocket extends EventTarget {
      * @param _protocols - Ignored; accepted for API compatibility.
      */
     constructor(url: string | URL, _protocols?: string | string[] | Record<string, unknown>);
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: () => void): void;
+    addEventListener(type: "close", listener: (event: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: {
+        message?: string;
+    }) => void): void;
     /**
      * Record a sent message without transmitting it.
      *
@@ -56,7 +68,7 @@ export declare class MockWebSocket extends EventTarget {
     /** Transition to `OPEN` state and dispatch an `"open"` event. */
     open(): void;
     /**
-     * Shorthand for {@linkcode simulateMessage}.
+     * Shorthand for {@link simulateMessage}.
      *
      * @param data - The message data to dispatch.
      */
@@ -79,7 +91,7 @@ export declare class MockWebSocket extends EventTarget {
     sentJson(): Record<string, unknown>[];
 }
 /**
- * Replace `globalThis.WebSocket` with {@linkcode MockWebSocket} for testing.
+ * 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
@@ -102,4 +114,3 @@ export declare function installMockWebSocket(): {
     get lastWs(): MockWebSocket | null;
     [Symbol.dispose]: () => void;
 };
-//# sourceMappingURL=_mock_ws.d.ts.map

package/dist/_mock-ws.js

@@ -0,0 +1,158 @@
+//#region _mock-ws.ts
+/**
+* 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" }]);
+* ```
+*/
+var MockWebSocket = class MockWebSocket extends EventTarget {
+	static CONNECTING = 0;
+	static OPEN = 1;
+	static CLOSING = 2;
+	static CLOSED = 3;
+	readyState = MockWebSocket.CONNECTING;
+	binaryType = "arraybuffer";
+	/** All messages passed to {@link send}, in order. */
+	sent = [];
+	url;
+	/**
+	* 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, _protocols) {
+		super();
+		this.url = typeof url === "string" ? url : url.toString();
+		queueMicrotask(() => {
+			if (this.readyState === MockWebSocket.CONNECTING) {
+				this.readyState = MockWebSocket.OPEN;
+				this.dispatchEvent(new Event("open"));
+			}
+		});
+	}
+	addEventListener(type, listener) {
+		super.addEventListener(type, listener);
+	}
+	/**
+	* Record a sent message without transmitting it.
+	*
+	* @param data - The message data to record.
+	*/
+	send(data) {
+		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, _reason) {
+		this.readyState = MockWebSocket.CLOSED;
+		const ev = new Event("close");
+		ev.code = code ?? 1e3;
+		this.dispatchEvent(ev);
+	}
+	/**
+	* Simulate receiving a message from the server.
+	*
+	* @param data - The message data (string or binary).
+	*/
+	simulateMessage(data) {
+		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) {
+		this.simulateMessage(data);
+	}
+	/**
+	* Simulate a connection close from the server.
+	*
+	* @param code - The close code (defaults to 1000).
+	*/
+	disconnect(code = 1e3) {
+		const ev = new Event("close");
+		ev.code = code;
+		this.dispatchEvent(ev);
+	}
+	/** 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() {
+		return this.sent.filter((d) => typeof d === "string").map((s) => JSON.parse(s));
+	}
+};
+const g = 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
+* ```
+*/
+function installMockWebSocket() {
+	const saved = globalThis.WebSocket;
+	const created = [];
+	g.WebSocket = class extends MockWebSocket {
+		constructor(url, protocols) {
+			super(url, protocols);
+			created.push(this);
+		}
+	};
+	return {
+		created,
+		get lastWs() {
+			return created.at(-1) ?? null;
+		},
+		restore() {
+			globalThis.WebSocket = saved;
+		},
+		[Symbol.dispose]() {
+			this.restore();
+		}
+	};
+}
+//#endregion
+export { MockWebSocket, installMockWebSocket };

package/dist/{sdk/_utils.d.ts → _utils.d.ts}

@@ -1,4 +1,3 @@
-/** Shared utility functions. @module */
+/** Shared utility functions. */
 /** Extract an error message from an unknown thrown value. */
 export declare function errorMessage(err: unknown): string;
-//# sourceMappingURL=_utils.d.ts.map

package/dist/_utils.js

@@ -0,0 +1,8 @@
+//#region _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);
+}
+//#endregion
+export { errorMessage };

package/dist/{sdk/builtin_tools.d.ts → builtin-tools.d.ts}

@@ -3,11 +3,9 @@
  *
  * 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 ToolSchema } from "./_internal-types.ts";
 import { type ToolDef } from "./types.ts";
 /** Callback for proxying vector search through the host RPC. */
 export type VectorSearchFn = (query: string, topK: number) => Promise<string>;
@@ -46,16 +44,15 @@ export declare function memoryTools(): {
     save_memory: ToolDef<z.ZodObject<{
         key: z.ZodString;
         value: z.ZodString;
-    }, z.core.$strip>, any>;
+    }, z.core.$strip>, Record<string, unknown>>;
     recall_memory: ToolDef<z.ZodObject<{
         key: z.ZodString;
-    }, z.core.$strip>, any>;
+    }, z.core.$strip>, Record<string, unknown>>;
     list_memories: ToolDef<z.ZodObject<{
         prefix: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, any>;
+    }, z.core.$strip>, Record<string, unknown>>;
     forget_memory: ToolDef<z.ZodObject<{
         key: z.ZodString;
-    }, z.core.$strip>, any>;
+    }, z.core.$strip>, Record<string, unknown>>;
 };
 export {};
-//# sourceMappingURL=builtin_tools.d.ts.map

package/dist/builtin-tools.js

@@ -0,0 +1,270 @@
+import { tool } from "./types.js";
+import { EMPTY_PARAMS } from "./_internal-types.js";
+import { errorMessage } from "./_utils.js";
+import { z } from "zod";
+import { convert } from "html-to-text";
+//#region builtin-tools.ts
+/**
+* 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).
+*/
+/** Per-fetch timeout for network tools — tighter than the overall tool timeout. */
+const FETCH_TIMEOUT_MS = 15e3;
+/** Timeout for sandboxed code execution. */
+const RUN_CODE_TIMEOUT = 5e3;
+/** Create a fetch timeout signal. */
+function fetchSignal() {
+	return AbortSignal.timeout(FETCH_TIMEOUT_MS);
+}
+function htmlToText(html) {
+	return convert(html, { wordwrap: false });
+}
+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(fetchFn = globalThis.fetch) {
+	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 resp = await fetchFn(`${BRAVE_SEARCH_URL}?${new URLSearchParams({
+				q: query,
+				count: String(maxResults),
+				text_decorations: "false"
+			})}`, {
+				headers: { "X-Subscription-Token": apiKey },
+				signal: fetchSignal()
+			});
+			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
+			}));
+		}
+	};
+}
+const MAX_PAGE_CHARS = 1e4;
+const MAX_HTML_BYTES = 2e5;
+const visitWebpageParams = z.object({ url: z.string().describe("The full URL to fetch (e.g., 'https://example.com/page')") });
+function createVisitWebpage(fetchFn = globalThis.fetch) {
+	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 fetchFn(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: fetchSignal()
+			});
+			if (!resp.ok) return {
+				error: `Failed to fetch: ${resp.status} ${resp.statusText}`,
+				url
+			};
+			const htmlContent = await resp.text();
+			const text = htmlToText(htmlContent.length > MAX_HTML_BYTES ? htmlContent.slice(0, MAX_HTML_BYTES) : htmlContent);
+			const truncated = text.length > MAX_PAGE_CHARS;
+			return {
+				url,
+				content: truncated ? text.slice(0, MAX_PAGE_CHARS) : text,
+				...truncated ? {
+					truncated: true,
+					totalChars: text.length
+				} : {}
+			};
+		}
+	};
+}
+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(fetchFn = globalThis.fetch) {
+	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 fetchFn(url, {
+				...headers && { headers },
+				signal: fetchSignal()
+			});
+			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
+				};
+			}
+		}
+	};
+}
+const runCodeParams = z.object({ code: z.string().describe("JavaScript code to execute. Use console.log() for output.") });
+function createRunCode() {
+	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 = [];
+			function capture(...captureArgs) {
+				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 Promise.race([fn(fakeConsole), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("Code execution timed out")), RUN_CODE_TIMEOUT))]);
+				return output.join("\n").trim() || "Code ran successfully (no output)";
+			} catch (err) {
+				return { error: errorMessage(err) };
+			}
+		}
+	};
+}
+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()
+});
+function createVectorSearch(vectorSearchFn) {
+	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);
+		}
+	};
+}
+/** Single-tool creators and multi-tool expanders in one registry. */
+const TOOL_REGISTRY = {
+	web_search: { create: (opts) => createWebSearch(opts?.fetch) },
+	visit_webpage: { create: (opts) => createVisitWebpage(opts?.fetch) },
+	fetch_json: { create: (opts) => createFetchJson(opts?.fetch) },
+	run_code: { create: createRunCode },
+	vector_search: { create: (opts) => createVectorSearch(opts?.vectorSearch ?? (async () => "")) },
+	memory: { multi: memoryTools }
+};
+/** Resolve a builtin name to an array of [toolName, ToolDef] pairs. */
+function resolveBuiltin(name, opts) {
+	const entry = TOOL_REGISTRY[name];
+	if (!entry) return [];
+	if ("multi" in entry) return Object.entries(entry.multi());
+	if (name === "vector_search" && !opts?.vectorSearch) return [];
+	return [[name, entry.create(opts)]];
+}
+/**
+* Create built-in tool definitions for the given tool names.
+* For runtime use — vector_search requires opts.vectorSearch to be included.
+*/
+function getBuiltinToolDefs(names, opts) {
+	const defs = {};
+	for (const name of names) for (const [k, v] of resolveBuiltin(name, opts)) defs[k] = v;
+	return defs;
+}
+/** Returns JSON tool schemas for the specified builtin tools. */
+function getBuiltinToolSchemas(names) {
+	return names.flatMap((name) => resolveBuiltin(name, { vectorSearch: async () => "" }).map(([toolName, def]) => ({
+		name: toolName,
+		description: def.description,
+		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
+	})));
+}
+/**
+* Returns a standard set of KV-backed memory tools: `save_memory`,
+* `recall_memory`, `list_memories`, and `forget_memory`.
+*
+* Spread the result into your agent's `tools` record.
+*
+* @example
+* ```ts
+* import { defineAgent, memoryTools } from "aai";
+*
+* export default defineAgent({
+*   name: "My Agent",
+*   tools: { ...memoryTools() },
+* });
+* ```
+*/
+function memoryTools() {
+	return {
+		save_memory: tool({
+			description: "Save a piece of information to persistent memory. Use a descriptive key like 'user:name' or 'project:status'.",
+			parameters: z.object({
+				key: z.string().describe("A descriptive key for this memory (e.g. 'user:name', 'preference:color')"),
+				value: z.string().describe("The information to remember")
+			}),
+			execute: async ({ key, value }, ctx) => {
+				await ctx.kv.set(key, value);
+				return { saved: key };
+			}
+		}),
+		recall_memory: tool({
+			description: "Retrieve a previously saved memory by its key.",
+			parameters: z.object({ key: z.string().describe("The key to look up") }),
+			execute: async ({ key }, ctx) => {
+				const value = await ctx.kv.get(key);
+				if (value === null) return {
+					found: false,
+					key
+				};
+				return {
+					found: true,
+					key,
+					value
+				};
+			}
+		}),
+		list_memories: tool({
+			description: "List all saved memory keys, optionally filtered by a prefix (e.g. 'user:').",
+			parameters: z.object({ prefix: z.string().describe("Prefix to filter keys (e.g. 'user:'). Use empty string for all.").optional() }),
+			execute: async ({ prefix }, ctx) => {
+				const entries = await ctx.kv.list(prefix ?? "");
+				return {
+					count: entries.length,
+					keys: entries.map((e) => e.key)
+				};
+			}
+		}),
+		forget_memory: tool({
+			description: "Delete a previously saved memory by its key.",
+			parameters: z.object({ key: z.string().describe("The key to delete") }),
+			execute: async ({ key }, ctx) => {
+				await ctx.kv.delete(key);
+				return { deleted: key };
+			}
+		})
+	};
+}
+//#endregion
+export { getBuiltinToolDefs, getBuiltinToolSchemas, memoryTools };

package/dist/{sdk/direct_executor.d.ts → direct-executor.d.ts}

@@ -3,18 +3,16 @@
  *
  * In self-hosted mode, agent code is trusted (you're running your own code).
  * Tools execute directly in-process — no sandbox, no RPC.
- *
- * @module
  */
-import { type AgentConfig, type ToolSchema } from "./_internal_types.ts";
+import { type AgentConfig, type ToolSchema } from "./_internal-types.ts";
 import type { Kv } from "./kv.ts";
 import type { ClientSink } from "./protocol.ts";
-import type { Logger, Metrics, S2SConfig } from "./runtime.ts";
+import type { Logger, S2SConfig } from "./runtime.ts";
 import type { CreateS2sWebSocket } from "./s2s.ts";
 import { type HookInvoker, type Session } from "./session.ts";
 import type { AgentDef } from "./types.ts";
 import type { VectorStore } from "./vector.ts";
-import type { ExecuteTool } from "./worker_entry.ts";
+import type { ExecuteTool } from "./worker-entry.ts";
 export type DirectExecutorOptions = {
     agent: AgentDef;
     env: Record<string, string>;
@@ -23,7 +21,6 @@ export type DirectExecutorOptions = {
     vectorSearch?: ((query: string, topK: number) => Promise<string>) | undefined;
     createWebSocket?: CreateS2sWebSocket | undefined;
     logger?: Logger | undefined;
-    metrics?: Metrics | undefined;
     s2sConfig?: S2SConfig | undefined;
 };
 export type DirectExecutor = {
@@ -41,4 +38,3 @@ export type DirectExecutor = {
 export declare function buildAgentConfig(agent: AgentDef): AgentConfig;
 /** Create a direct (in-process) tool executor and hook invoker for an agent. */
 export declare function createDirectExecutor(opts: DirectExecutorOptions): DirectExecutor;
-//# sourceMappingURL=direct_executor.d.ts.map