@alexkroman1/aai 0.9.2 → 0.10.0

package/dist/vector.js

@@ -1,56 +1,49 @@
 //#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.
+* Vector store interface.
+*/
+/**
+* Maximum allowed length for a vector filter expression.
+* @internal
+*/
+const MAX_FILTER_LENGTH = 1e3;
+/**
+* SQL/query keywords that must not appear in filter expressions.
+* Checked case-insensitively as whole words (word-boundary match).
+* @internal
+*/
+const DANGEROUS_KEYWORDS = /\b(SELECT|INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|EXEC|EXECUTE|UNION|INTO|TRUNCATE|GRANT|REVOKE|CALL)\b/i;
+/**
+* Patterns that indicate injection attempts in filter strings.
+* @internal
+*/
+const DANGEROUS_PATTERNS = [
+	/;/,
+	/--/,
+	/\/\*/,
+	/\*\//,
+	/\0/
+];
+/**
+* Validate a vector filter expression to prevent injection attacks.
 *
-* @returns A {@link VectorStore} instance backed by in-memory storage.
+* Rejects filters containing SQL keywords (SELECT, DROP, etc.),
+* statement terminators, comments, and null bytes. Enforces a
+* maximum length of 1000 characters.
 *
-* @example
-* ```ts
-* import { createMemoryVectorStore } from "aai";
+* @param filter - The raw filter string from user input.
+* @returns The validated filter string (trimmed).
+* @throws Error if the filter contains dangerous patterns.
 *
-* const vector = createMemoryVectorStore();
-* await vector.upsert("doc-1", "The capital of France is Paris.");
-* const results = await vector.query("France capital");
-* ```
+* @public
 */
-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();
-		}
-	};
+function validateVectorFilter(filter) {
+	const trimmed = filter.trim();
+	if (trimmed.length === 0) throw new Error("Vector filter must not be empty");
+	if (trimmed.length > MAX_FILTER_LENGTH) throw new Error(`Vector filter exceeds maximum length of ${MAX_FILTER_LENGTH} characters`);
+	if (DANGEROUS_KEYWORDS.test(trimmed)) throw new Error("Vector filter contains disallowed SQL keyword");
+	for (const pattern of DANGEROUS_PATTERNS) if (pattern.test(trimmed)) throw new Error("Vector filter contains disallowed characters");
+	return trimmed;
 }
 //#endregion
-export { createMemoryVectorStore };
+export { validateVectorFilter };

package/dist/worker-entry.d.ts

@@ -2,6 +2,7 @@
  * Worker entry point — shared tool execution logic.
  */
 import type { Kv } from "./kv.ts";
+import type { Logger } from "./runtime.ts";
 import type { Message, ToolDef } from "./types.ts";
 import type { VectorStore } from "./vector.ts";
 /**
@@ -13,23 +14,30 @@ import type { VectorStore } from "./vector.ts";
  * @param messages - Optional conversation history for context-aware tools.
  * @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>;
+export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>, sessionId?: string, messages?: readonly Message[], onUpdate?: (data: unknown) => void) => Promise<string>;
 /** Options for {@link executeToolCall}. */
 export type ExecuteToolCallOptions = {
     tool: ToolDef;
     env: Readonly<Record<string, string>>;
     state?: Record<string, unknown>;
+    sessionId?: string | undefined;
     kv?: Kv | undefined;
     vector?: VectorStore | undefined;
     messages?: readonly Message[] | undefined;
+    logger?: Logger | undefined;
+    /** Callback for intermediate UI updates from `ctx.sendUpdate()`. */
+    onUpdate?: ((data: unknown) => void) | undefined;
+    /** Override fetch implementation for the tool context. */
+    fetch?: typeof globalThis.fetch | undefined;
 };
 /**
  * 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.
+ * and serializes the result to a string. Errors (validation failures,
+ * execution throws, timeouts) are caught and returned as JSON strings
+ * via {@link toolError} (`'{"error":"<message>"}'`) 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.

package/dist/worker-entry.js

@@ -1,11 +1,11 @@
 import { EMPTY_PARAMS } from "./_internal-types.js";
-import { errorMessage } from "./_utils.js";
+import { errorDetail, errorMessage, toolError } 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;
+	const { env, state, kv, vector, messages, onUpdate, fetch: fetchFn, sessionId } = opts;
 	return {
 		env: { ...env },
 		state: state ?? {},
@@ -17,7 +17,12 @@ function buildToolContext(opts) {
 			if (!vector) throw new Error("Vector store not available");
 			return vector;
 		},
-		messages: messages ?? []
+		messages: messages ?? [],
+		sendUpdate(data) {
+			onUpdate?.(data);
+		},
+		fetch: fetchFn ?? globalThis.fetch,
+		sessionId: sessionId ?? ""
 	};
 }
 /**
@@ -25,8 +30,9 @@ function buildToolContext(opts) {
 *
 * 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.
+* and serializes the result to a string. Errors (validation failures,
+* execution throws, timeouts) are caught and returned as JSON strings
+* via {@link toolError} (`'{"error":"<message>"}'`) 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.
@@ -36,7 +42,7 @@ function buildToolContext(opts) {
 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(", ")}`;
+	if (!parsed.success) return toolError(`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);
@@ -49,8 +55,13 @@ async function executeToolCall(name, args, options) {
 		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)}`;
+		const log = options.logger;
+		if (log) log.warn("Tool execution failed", {
+			tool: name,
+			error: errorDetail(err)
+		});
+		else console.warn(`[tool-executor] Tool execution failed: ${name}`, err);
+		return toolError(errorMessage(err));
 	} finally {
 		clearTimeout(timer);
 	}

package/dist/ws-handler.d.ts

@@ -1,7 +1,7 @@
 /**
  * WebSocket session lifecycle handler.
  *
- * Audio validation is handled at the host transport layer (see host.ts).
+ * Audio validation is handled at the host transport layer (see server.ts).
  */
 import type { ClientSink, ReadyConfig } from "./protocol.ts";
 import type { Logger } from "./runtime.ts";
@@ -14,11 +14,10 @@ import type { Session } from "./session.ts";
 export type SessionWebSocket = {
     readonly readyState: number;
     send(data: string | ArrayBuffer | Uint8Array): void;
-    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "close" | "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;
@@ -39,6 +38,11 @@ export type WsSessionOptions = {
     onClose?: () => void;
     /** Logger instance. Defaults to console. */
     logger?: Logger;
+    /** Timeout in ms for session.start(). Defaults to 10 000 (10s). */
+    sessionStartTimeoutMs?: number;
+    /** Old session ID to resume from. When set, the persisted session data
+     *  (state, messages, S2S session ID) is restored from KV. */
+    resumeFrom?: string;
 };
 /**
  * Attaches session lifecycle handlers to a native WebSocket using

package/dist/ws-handler.js

@@ -1,24 +1,31 @@
-import { errorMessage } from "./_utils.js";
+import { errorDetail, errorMessage } from "./_utils.js";
 import { ClientMessageSchema } from "./protocol.js";
 import { consoleLogger } from "./runtime.js";
+import { tracer, wsSendDroppedCounter } from "./telemetry.js";
 //#region ws-handler.ts
 /**
 * WebSocket session lifecycle handler.
 *
-* Audio validation is handled at the host transport layer (see host.ts).
+* Audio validation is handled at the host transport layer (see server.ts).
 */
+/** Default timeout for session.start() in milliseconds. */
+const DEFAULT_SESSION_START_TIMEOUT_MS = 1e4;
 /**
 * 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 createClientSink(ws, log) {
+	/** Send data over ws, silently dropping if the socket is not open. */
 	function safeSend(data) {
 		try {
-			if (ws.readyState === 1) ws.send(data);
-		} catch {}
+			if (ws.readyState !== 1) return;
+			ws.send(data);
+		} catch (err) {
+			log.debug?.("safeSend: socket closed between readyState check and send", { error: err instanceof Error ? err.message : String(err) });
+			wsSendDroppedCounter.add(1);
+		}
 	}
 	return {
 		get open() {
@@ -81,6 +88,7 @@ function handleTextMessage(data, session, log, ctx, sid) {
 		case "history":
 			session.onHistory(msg.messages);
 			break;
+		default: break;
 	}
 }
 /**
@@ -94,40 +102,75 @@ function handleTextMessage(data, session, log, ctx, sid) {
 */
 function wireSessionSocket(ws, opts) {
 	const { sessions, logger: log = consoleLogger } = opts;
-	const sessionId = crypto.randomUUID();
+	const sessionId = opts.resumeFrom ?? crypto.randomUUID();
 	const sid = sessionId.slice(0, 8);
 	const ctx = opts.logContext ?? {};
 	let session = null;
+	/** Set to true once session.start() resolves. Messages arriving before
+	*  this flag is set are buffered and replayed once the session is ready,
+	*  preventing audio/text from being dispatched to a half-initialized session. */
+	let sessionReady = false;
+	let messageBuffer = [];
+	const sessionSpan = tracer.startSpan("ws.session", { attributes: { "aai.session.id": sessionId } });
+	function drainBuffer() {
+		if (!(session && messageBuffer)) return;
+		const buf = messageBuffer;
+		messageBuffer = null;
+		for (const event of buf) {
+			const { data } = event;
+			if (handleBinaryAudio(data, session)) continue;
+			handleTextMessage(data, session, log, ctx, sid);
+		}
+	}
 	function onOpen() {
 		opts.onOpen?.();
 		log.info("Session connected", {
 			...ctx,
 			sid
 		});
-		const client = createClientSink(ws);
+		sessionSpan.addEvent("ws.open");
+		const client = createClientSink(ws, log);
 		session = opts.createSession(sessionId, client);
 		sessions.set(sessionId, session);
 		ws.send(JSON.stringify({
 			type: "config",
-			...opts.readyConfig
+			...opts.readyConfig,
+			sessionId
 		}));
-		session.start().then(() => {
+		const timeoutMs = opts.sessionStartTimeoutMs ?? DEFAULT_SESSION_START_TIMEOUT_MS;
+		Promise.race([session.start(), new Promise((_resolve, reject) => {
+			setTimeout(() => reject(/* @__PURE__ */ new Error(`session.start() timed out after ${timeoutMs}ms`)), timeoutMs);
+		})]).then(() => {
 			log.info("Session ready", {
 				...ctx,
 				sid
 			});
+			sessionSpan.addEvent("session.ready");
+			sessionReady = true;
+			drainBuffer();
 		}).catch((err) => {
 			log.error("Session start failed", {
 				...ctx,
 				sid,
-				error: errorMessage(err)
+				error: errorDetail(err)
 			});
+			sessionSpan.setStatus({
+				code: 2,
+				message: errorMessage(err)
+			});
+			sessions.delete(sessionId);
+			session = null;
+			messageBuffer = null;
 		});
 	}
 	if (ws.readyState === 1) onOpen();
 	else ws.addEventListener("open", onOpen);
 	ws.addEventListener("message", (event) => {
 		if (!session) return;
+		if (!sessionReady) {
+			messageBuffer?.push(event);
+			return;
+		}
 		const { data } = event;
 		if (handleBinaryAudio(data, session)) return;
 		handleTextMessage(data, session, log, ctx, sid);
@@ -137,7 +180,15 @@ function wireSessionSocket(ws, opts) {
 			...ctx,
 			sid
 		});
-		if (session) session.stop().finally(() => {
+		sessionSpan.addEvent("ws.close");
+		sessionSpan.end();
+		if (session) session.stop().catch((err) => {
+			log.error("Session stop failed", {
+				...ctx,
+				sid,
+				error: errorDetail(err)
+			});
+		}).finally(() => {
 			sessions.delete(sessionId);
 		});
 		opts.onClose?.();
@@ -149,6 +200,7 @@ function wireSessionSocket(ws, opts) {
 			sid,
 			error: msg
 		});
+		sessionSpan.recordException(new Error(msg));
 	});
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "type": "module",
   "files": [
     "dist"
@@ -27,9 +27,14 @@
       "import": "./dist/vector.js"
     },
     "./testing": {
-      "source": "./_mock-ws.ts",
-      "types": "./dist/_mock-ws.d.ts",
-      "import": "./dist/_mock-ws.js"
+      "source": "./testing.ts",
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./testing/matchers": {
+      "source": "./matchers.ts",
+      "types": "./dist/matchers.d.ts",
+      "import": "./dist/matchers.js"
     },
     "./server": {
       "source": "./server.ts",
@@ -71,42 +76,84 @@
       "types": "./dist/ws-handler.d.ts",
       "import": "./dist/ws-handler.js"
     },
+    "./telemetry": {
+      "source": "./telemetry.ts",
+      "types": "./dist/telemetry.d.ts",
+      "import": "./dist/telemetry.js"
+    },
     "./utils": {
       "source": "./_utils.ts",
       "types": "./dist/_utils.d.ts",
       "import": "./dist/_utils.js"
+    },
+    "./ssrf": {
+      "source": "./_ssrf.ts",
+      "types": "./dist/_ssrf.d.ts",
+      "import": "./dist/_ssrf.js"
+    },
+    "./middleware-core": {
+      "source": "./middleware-core.ts",
+      "types": "./dist/middleware-core.d.ts",
+      "import": "./dist/middleware-core.js"
+    },
+    "./sqlite-kv": {
+      "source": "./sqlite-kv.ts",
+      "types": "./dist/sqlite-kv.d.ts",
+      "import": "./dist/sqlite-kv.js"
+    },
+    "./sqlite-vector": {
+      "source": "./sqlite-vector.ts",
+      "types": "./dist/sqlite-vector.d.ts",
+      "import": "./dist/sqlite-vector.js"
     }
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
     "html-to-text": "^9.0.5",
     "nanoevents": "^9.1.0",
+    "secure-exec": "^0.1.0",
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@hono/node-server": "^1.19.11",
-    "hono": "^4.12.9"
+    "@opentelemetry/api": "^1.9.1",
+    "hono": "^4.12.9",
+    "vitest": "^4.1.1"
   },
   "peerDependenciesMeta": {
     "@hono/node-server": {
       "optional": true
     },
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "hono": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/html-to-text": "^9.0.4",
     "@types/json-schema": "^7.0.15",
     "@types/ws": "^8.18.1",
-    "tsdown": "^0.21.4"
+    "tsdown": "^0.21.5"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexkroman/agent.git",
+    "directory": "packages/aai"
   },
   "scripts": {
     "build": "tsdown && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "lint": "biome check ."
+    "lint": "biome check .",
+    "check:api": "api-extractor run -c api-extractor.json",
+    "check:attw": "attw --pack --profile esm-only"
   }
 }

package/dist/_mock-ws.js

@@ -1,158 +0,0 @@
-//#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 };