@alexkroman1/aai 0.8.7 → 0.9.0

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

@@ -1,10 +1,10 @@
 /**
  * Vector store interface and in-memory implementation.
- *
- * @module
  */
 /**
  * A single vector search result entry.
+ *
+ * @public
  */
 export type VectorEntry = {
     /** The unique identifier for this entry. */
@@ -19,8 +19,8 @@ export type VectorEntry = {
 /**
  * Async vector store interface used by agents.
  *
- * Agents access the vector store via {@linkcode ToolContext.vector} or
- * {@linkcode HookContext.vector}. Backed by Upstash Vector with built-in
+ * Agents access the vector store via `ToolContext.vector` or
+ * `HookContext.vector`. Backed by Upstash Vector with built-in
  * embeddings — raw text is sent and vectorized server-side.
  *
  * @example
@@ -35,6 +35,8 @@ export type VectorEntry = {
  *   },
  * };
  * ```
+ *
+ * @public
  */
 export type VectorStore = {
     /**
@@ -42,9 +44,9 @@ export type VectorStore = {
      *
      * The text is automatically embedded by the server's vector database.
      *
-     * @param id Unique identifier for this entry.
-     * @param data The text content to store and embed.
-     * @param metadata Optional metadata to store alongside the vector.
+     * @param id - Unique identifier for this entry.
+     * @param data - The text content to store and embed.
+     * @param metadata - Optional metadata to store alongside the vector.
      */
     upsert(id: string, data: string, metadata?: Record<string, unknown>): Promise<void>;
     /**
@@ -52,11 +54,9 @@ export type VectorStore = {
      *
      * Returns the most similar entries ranked by score.
      *
-     * @param text The query text to search for.
-     * @param options Optional query parameters.
-     * @param options.topK Maximum number of results (default: 10).
-     * @param options.filter Metadata filter expression.
-     * @returns An array of matching {@linkcode VectorEntry} objects.
+     * @param text - The query text to search for.
+     * @param options - Optional query parameters. `topK` sets the maximum number of results (default: 10). `filter` is a metadata filter expression.
+     * @returns An array of matching {@link VectorEntry} objects.
      */
     query(text: string, options?: {
         topK?: number;
@@ -65,7 +65,7 @@ export type VectorStore = {
     /**
      * Remove entries by ID.
      *
-     * @param ids A single ID or array of IDs to remove.
+     * @param ids - A single ID or array of IDs to remove.
      */
     remove(ids: string | string[]): Promise<void>;
 };
@@ -75,7 +75,7 @@ export type VectorStore = {
  * Uses brute-force substring matching instead of real vector similarity.
  * Good enough for testing the plumbing but not for production use.
  *
- * @returns A {@linkcode VectorStore} instance backed by in-memory storage.
+ * @returns A {@link VectorStore} instance backed by in-memory storage.
  *
  * @example
  * ```ts
@@ -87,4 +87,3 @@ export type VectorStore = {
  * ```
  */
 export declare function createMemoryVectorStore(): VectorStore;
-//# sourceMappingURL=vector.d.ts.map

package/dist/vector.js

@@ -0,0 +1,56 @@
+//#region vector.ts
+/**
+* Create an in-memory vector store for testing and local development.
+*
+* Uses brute-force substring matching instead of real vector similarity.
+* Good enough for testing the plumbing but not for production use.
+*
+* @returns A {@link VectorStore} instance backed by in-memory storage.
+*
+* @example
+* ```ts
+* import { createMemoryVectorStore } from "aai";
+*
+* const vector = createMemoryVectorStore();
+* await vector.upsert("doc-1", "The capital of France is Paris.");
+* const results = await vector.query("France capital");
+* ```
+*/
+function createMemoryVectorStore() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		upsert(id, data, metadata) {
+			store.set(id, {
+				data,
+				metadata
+			});
+			return Promise.resolve();
+		},
+		async query(text, options) {
+			const topK = options?.topK ?? 10;
+			const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+			const results = [];
+			let i = 0;
+			for (const [id, entry] of store) {
+				if (++i % 500 === 0) await new Promise((r) => setTimeout(r, 0));
+				const data = entry.data.toLowerCase();
+				const matches = words.filter((w) => data.includes(w)).length;
+				if (matches > 0) results.push({
+					id,
+					score: matches / Math.max(words.length, 1),
+					data: entry.data,
+					metadata: entry.metadata
+				});
+			}
+			results.sort((a, b) => b.score - a.score);
+			return results.slice(0, topK);
+		},
+		remove(ids) {
+			const idArray = Array.isArray(ids) ? ids : [ids];
+			for (const id of idArray) store.delete(id);
+			return Promise.resolve();
+		}
+	};
+}
+//#endregion
+export { createMemoryVectorStore };

package/dist/{sdk/worker_entry.d.ts → worker-entry.d.ts}

@@ -1,7 +1,5 @@
 /**
  * Worker entry point — shared tool execution logic.
- *
- * @module
  */
 import type { Kv } from "./kv.ts";
 import type { Message, ToolDef } from "./types.ts";
@@ -16,7 +14,7 @@ import type { VectorStore } from "./vector.ts";
  * @returns The tool's string result, or an error message string.
  */
 export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>, sessionId?: string, messages?: readonly Message[]) => Promise<string>;
-/** Options for {@linkcode executeToolCall}. */
+/** Options for {@link executeToolCall}. */
 export type ExecuteToolCallOptions = {
     tool: ToolDef;
     env: Readonly<Record<string, string>>;
@@ -29,7 +27,7 @@ export type ExecuteToolCallOptions = {
  * Execute a tool call with argument validation and error handling.
  *
  * Validates the provided arguments against the tool's Zod parameter schema,
- * constructs a {@linkcode ToolContext}, invokes the tool's `execute` function,
+ * constructs a {@link ToolContext}, invokes the tool's `execute` function,
  * and serializes the result to a string. Errors are caught and returned as
  * `"Error: ..."` strings rather than thrown.
  *
@@ -39,4 +37,3 @@ export type ExecuteToolCallOptions = {
  * @returns The tool's result serialized as a string, or an error message.
  */
 export declare function executeToolCall(name: string, args: Readonly<Record<string, unknown>>, options: ExecuteToolCallOptions): Promise<string>;
-//# sourceMappingURL=worker_entry.d.ts.map

package/dist/worker-entry.js

@@ -0,0 +1,59 @@
+import { EMPTY_PARAMS } from "./_internal-types.js";
+import { errorMessage } from "./_utils.js";
+import { TOOL_EXECUTION_TIMEOUT_MS } from "./protocol.js";
+//#region worker-entry.ts
+/** Yield to the event loop so pending I/O (e.g. WebSocket frames) can be processed. */
+const yieldTick = () => new Promise((r) => setTimeout(r, 0));
+function buildToolContext(opts) {
+	const { env, state, kv, vector, messages } = opts;
+	return {
+		env: { ...env },
+		state: state ?? {},
+		get kv() {
+			if (!kv) throw new Error("KV not available");
+			return kv;
+		},
+		get vector() {
+			if (!vector) throw new Error("Vector store not available");
+			return vector;
+		},
+		messages: messages ?? []
+	};
+}
+/**
+* Execute a tool call with argument validation and error handling.
+*
+* Validates the provided arguments against the tool's Zod parameter schema,
+* constructs a {@link ToolContext}, invokes the tool's `execute` function,
+* and serializes the result to a string. Errors are caught and returned as
+* `"Error: ..."` strings rather than thrown.
+*
+* @param name - The name of the tool being invoked.
+* @param args - Raw arguments from the LLM to validate and pass to the tool.
+* @param options - Tool definition, environment, and optional context.
+* @returns The tool's result serialized as a string, or an error message.
+*/
+async function executeToolCall(name, args, options) {
+	const { tool } = options;
+	const parsed = (tool.parameters ?? EMPTY_PARAMS).safeParse(args);
+	if (!parsed.success) return `Error: Invalid arguments for tool "${name}": ${(parsed.error?.issues ?? []).map((i) => `${i.path.map(String).join(".")}: ${i.message}`).join(", ")}`;
+	let timer;
+	try {
+		const ctx = buildToolContext(options);
+		await yieldTick();
+		const timeout = new Promise((_, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Tool "${name}" timed out after ${TOOL_EXECUTION_TIMEOUT_MS}ms`)), TOOL_EXECUTION_TIMEOUT_MS);
+		});
+		const result = await Promise.race([Promise.resolve(tool.execute(parsed.data, ctx)), timeout]);
+		await yieldTick();
+		if (result == null) return "null";
+		return typeof result === "string" ? result : JSON.stringify(result);
+	} catch (err) {
+		console.warn(`[tool-executor] Tool execution failed: ${name}`, err);
+		return `Error: ${errorMessage(err)}`;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+export { executeToolCall };

package/dist/{sdk/ws_handler.d.ts → ws-handler.d.ts}

@@ -1,24 +1,27 @@
 /**
  * WebSocket session lifecycle handler.
  *
- * Cross-runtime: accepts a Logger parameter instead of importing `@std/log`.
  * Audio validation is handled at the host transport layer (see host.ts).
- *
- * @module
  */
 import type { ClientSink, ReadyConfig } from "./protocol.ts";
 import type { Logger } from "./runtime.ts";
 import type { Session } from "./session.ts";
 /**
- * Minimal WebSocket interface accepted by {@linkcode wireSessionSocket}.
+ * Minimal WebSocket interface accepted by {@link wireSessionSocket}.
  *
- * Satisfied by the standard `WebSocket`, `BridgedWebSocket` (capnweb),
- * and the `ws` npm package's WebSocket.
+ * Satisfied by the standard `WebSocket` and the `ws` npm package's WebSocket.
  */
 export type SessionWebSocket = {
     readonly readyState: number;
     send(data: string | ArrayBuffer | Uint8Array): void;
-    addEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: () => void): void;
+    addEventListener(type: "error", listener: (event: {
+        message?: string;
+    }) => void): void;
 };
 /** Options for wiring a WebSocket to a session. */
 export type WsSessionOptions = {
@@ -47,4 +50,3 @@ export type WsSessionOptions = {
  * 3. If reconnecting → client sends `{ type: "history", messages: [...] }`
  */
 export declare function wireSessionSocket(ws: SessionWebSocket, opts: WsSessionOptions): void;
-//# sourceMappingURL=ws_handler.d.ts.map

package/dist/ws-handler.js

@@ -0,0 +1,155 @@
+import { errorMessage } from "./_utils.js";
+import { ClientMessageSchema } from "./protocol.js";
+import { consoleLogger } from "./runtime.js";
+//#region ws-handler.ts
+/**
+* WebSocket session lifecycle handler.
+*
+* Audio validation is handled at the host transport layer (see host.ts).
+*/
+/**
+* Creates a {@link ClientSink} backed by a plain WebSocket.
+*
+* Text events are sent as JSON text frames; audio chunks are sent as
+* binary frames (zero-copy).
+*/
+function createClientSink(ws) {
+	/** Send data over ws, tolerating races where the socket closes between readyState check and send. */
+	function safeSend(data) {
+		try {
+			if (ws.readyState === 1) ws.send(data);
+		} catch {}
+	}
+	return {
+		get open() {
+			return ws.readyState === 1;
+		},
+		event(e) {
+			safeSend(JSON.stringify(e));
+		},
+		playAudioChunk(chunk) {
+			safeSend(chunk);
+		},
+		playAudioDone() {
+			safeSend(JSON.stringify({ type: "audio_done" }));
+		}
+	};
+}
+function handleBinaryAudio(data, session) {
+	if (data instanceof Uint8Array) {
+		session.onAudio(data);
+		return true;
+	}
+	if (data instanceof ArrayBuffer) {
+		session.onAudio(new Uint8Array(data));
+		return true;
+	}
+	return false;
+}
+function handleTextMessage(data, session, log, ctx, sid) {
+	if (typeof data !== "string") return;
+	let json;
+	try {
+		json = JSON.parse(data);
+	} catch {
+		log.warn("Invalid JSON from client", {
+			...ctx,
+			sid
+		});
+		return;
+	}
+	const parsed = ClientMessageSchema.safeParse(json);
+	if (!parsed.success) {
+		log.warn("Invalid client message", {
+			...ctx,
+			sid,
+			error: parsed.error.message
+		});
+		return;
+	}
+	const msg = parsed.data;
+	switch (msg.type) {
+		case "audio_ready":
+			session.onAudioReady();
+			break;
+		case "cancel":
+			session.onCancel();
+			break;
+		case "reset":
+			session.onReset();
+			break;
+		case "history":
+			session.onHistory(msg.messages);
+			break;
+	}
+}
+/**
+* Attaches session lifecycle handlers to a native WebSocket using
+* plain JSON text frames and binary audio frames.
+*
+* Connection flow:
+* 1. WebSocket opens → server sends `{ type: "config", ...ReadyConfig }`
+* 2. Client sets up audio → sends `{ type: "audio_ready" }`
+* 3. If reconnecting → client sends `{ type: "history", messages: [...] }`
+*/
+function wireSessionSocket(ws, opts) {
+	const { sessions, logger: log = consoleLogger } = opts;
+	const sessionId = crypto.randomUUID();
+	const sid = sessionId.slice(0, 8);
+	const ctx = opts.logContext ?? {};
+	let session = null;
+	function onOpen() {
+		opts.onOpen?.();
+		log.info("Session connected", {
+			...ctx,
+			sid
+		});
+		const client = createClientSink(ws);
+		session = opts.createSession(sessionId, client);
+		sessions.set(sessionId, session);
+		ws.send(JSON.stringify({
+			type: "config",
+			...opts.readyConfig
+		}));
+		session.start().then(() => {
+			log.info("Session ready", {
+				...ctx,
+				sid
+			});
+		}).catch((err) => {
+			log.error("Session start failed", {
+				...ctx,
+				sid,
+				error: errorMessage(err)
+			});
+		});
+	}
+	if (ws.readyState === 1) onOpen();
+	else ws.addEventListener("open", onOpen);
+	ws.addEventListener("message", (event) => {
+		if (!session) return;
+		const { data } = event;
+		if (handleBinaryAudio(data, session)) return;
+		handleTextMessage(data, session, log, ctx, sid);
+	});
+	ws.addEventListener("close", () => {
+		log.info("Session disconnected", {
+			...ctx,
+			sid
+		});
+		if (session) session.stop().finally(() => {
+			sessions.delete(sessionId);
+		});
+		opts.onClose?.();
+	});
+	ws.addEventListener("error", (ev) => {
+		const msg = typeof ev.message === "string" ? ev.message : "WebSocket error";
+		log.error("WebSocket error", {
+			...ctx,
+			sid,
+			error: msg
+		});
+	});
+}
+//#endregion
+export { wireSessionSocket };