@alexkroman1/aai 0.9.3 → 0.10.1

package/dist/testing-MRl3SXsI.js

@@ -0,0 +1,519 @@
+import { t as createDirectExecutor } from "./direct-executor-Ca0wt5H0.js";
+import { createSqliteKv } from "./sqlite-kv.js";
+import { createSqliteVectorStore, createTestEmbedFn } from "./sqlite-vector.js";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+//#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;
+		this.dispatchEvent(Object.assign(new Event("close"), { code: code ?? 1e3 }));
+	}
+	/**
+	* 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) {
+		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() {
+		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
+//#region testing.ts
+/**
+* Testing utilities for AAI agents.
+*
+* Provides a test harness for unit-testing agents without audio, network,
+* or an LLM. Use {@link createTestHarness} to create a harness from a
+* `defineAgent()` result, then drive tool calls and multi-turn conversations.
+*
+* @example
+* ```ts
+* import { describe, expect, test } from "vitest";
+* import { createTestHarness } from "@alexkroman1/aai/testing";
+* import agent from "./agent.ts";
+*
+* describe("my agent", () => {
+*   test("greet tool returns greeting", async () => {
+*     const t = createTestHarness(agent);
+*     const result = await t.executeTool("greet", { name: "Alice" });
+*     expect(result).toBe("Hello, Alice!");
+*   });
+*
+*   test("multi-turn conversation", async () => {
+*     const t = createTestHarness(agent);
+*     const turn1 = await t.turn("Add a pizza", [
+*       { tool: "add_pizza", args: { size: "large", crust: "regular", toppings: ["pepperoni"], quantity: 1 } },
+*     ]);
+*     expect(turn1).toHaveCalledTool("add_pizza");
+*
+*     const turn2 = await t.turn("View my order", [
+*       { tool: "view_order", args: {} },
+*     ]);
+*     expect(turn2).toHaveCalledTool("view_order");
+*   });
+* });
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Result of a simulated turn via {@link TestHarness.turn}.
+*
+* Contains all tool calls that were executed and provides assertion helpers
+* for verifying agent behavior in tests.
+*
+* @example
+* ```ts
+* const result = await t.turn("search for flights", [
+*   { tool: "search_flights", args: { destination: "NYC" } },
+* ]);
+*
+* // Check if a tool was called
+* expect(result).toHaveCalledTool("search_flights");
+*
+* // Check tool was called with specific args
+* expect(result).toHaveCalledTool("search_flights", { destination: "NYC" });
+*
+* // Access raw tool call data
+* expect(result.toolCalls[0].result).toContain("JFK");
+* ```
+*
+* @public
+*/
+var TurnResult = class {
+	/** The user text that initiated this turn. */
+	text;
+	/** All tool calls executed during this turn, in order. */
+	toolCalls;
+	/** Convenience accessor: just the result strings from each tool call. */
+	toolResults;
+	/** @internal */
+	constructor(text, toolCalls) {
+		this.text = text;
+		this.toolCalls = toolCalls;
+		this.toolResults = toolCalls.map((tc) => tc.result);
+	}
+	/**
+	* Check whether a tool was called during this turn.
+	*
+	* When `args` is provided, checks that at least one call to the named tool
+	* contains all specified key-value pairs (partial match).
+	*
+	* @param toolName - The tool name to look for.
+	* @param args - Optional partial args to match against.
+	* @returns `true` if a matching tool call was found.
+	*
+	* @example
+	* ```ts
+	* result.toHaveCalledTool("add_pizza"); // any call
+	* result.toHaveCalledTool("add_pizza", { size: "large" }); // partial match
+	* ```
+	*/
+	toHaveCalledTool(toolName, args) {
+		return this.toolCalls.some((tc) => {
+			if (tc.toolName !== toolName) return false;
+			if (!args) return true;
+			return Object.entries(args).every(([key, value]) => JSON.stringify(tc.args[key]) === JSON.stringify(value));
+		});
+	}
+	/**
+	* Get all calls to a specific tool during this turn.
+	*
+	* @param toolName - The tool name to filter by.
+	* @returns Array of matching tool calls (may be empty).
+	*/
+	getToolCalls(toolName) {
+		return this.toolCalls.filter((tc) => tc.toolName === toolName);
+	}
+	/**
+	* Get the parsed JSON result of the first call to a specific tool.
+	*
+	* Throws if the tool was not called during this turn.
+	*
+	* @typeParam T - The expected shape of the parsed result.
+	* @param toolName - The tool name to look up.
+	* @returns The parsed result, cast to `T`.
+	*
+	* @example
+	* ```ts
+	* const order = turn.toolResult<{ pizzas: Pizza[]; total: string }>("view_order");
+	* expect(order.pizzas).toHaveLength(2);
+	* ```
+	*/
+	toolResult(toolName) {
+		const call = this.toolCalls.find((tc) => tc.toolName === toolName);
+		if (!call) throw new Error(`Tool "${toolName}" was not called during this turn`);
+		return JSON.parse(call.result);
+	}
+};
+/**
+* Test harness for unit-testing AAI agents without audio, network, or LLM.
+*
+* Created via {@link createTestHarness}. Maintains conversation state across
+* turns, executes tools against the real agent code, and records all tool
+* calls for assertions.
+*
+* @example
+* ```ts
+* import { createTestHarness } from "@alexkroman1/aai/testing";
+* import agent from "./agent.ts";
+*
+* const t = createTestHarness(agent);
+*
+* // Execute a single tool
+* const result = await t.executeTool("greet", { name: "Alice" });
+*
+* // Simulate a full turn with tool calls
+* const turn = await t.turn("hello", [
+*   { tool: "greet", args: { name: "Alice" } },
+* ]);
+* expect(turn).toHaveCalledTool("greet");
+* ```
+*
+* @public
+*/
+var TestHarness = class {
+	/** @internal */
+	_executor;
+	/** @internal */
+	_sessionId;
+	_messages = [];
+	_onStepCalls = [];
+	_onTurnCalls = [];
+	_connected = false;
+	/** @internal */
+	constructor(executor, sessionId) {
+		this._executor = executor;
+		this._sessionId = sessionId;
+	}
+	/** Conversation messages accumulated across turns. */
+	get messages() {
+		return this._messages;
+	}
+	/** All `onStep` hook invocations recorded so far. */
+	get steps() {
+		return this._onStepCalls;
+	}
+	/** All `onTurn` hook invocations (the text argument) recorded so far. */
+	get turns() {
+		return this._onTurnCalls;
+	}
+	/**
+	* Fire the `onConnect` lifecycle hook.
+	*
+	* Called automatically on the first {@link turn} call if not called manually.
+	*/
+	async connect() {
+		if (this._connected) return;
+		this._connected = true;
+		await this._executor.hookInvoker.onConnect(this._sessionId);
+	}
+	/**
+	* Fire the `onDisconnect` lifecycle hook and clean up session state.
+	*/
+	async disconnect() {
+		if (!this._connected) return;
+		this._connected = false;
+		await this._executor.hookInvoker.onDisconnect(this._sessionId);
+	}
+	/**
+	* Execute a single tool by name with the given arguments.
+	*
+	* The tool runs with full agent context (env, state, kv, vector, messages).
+	* The call is **not** recorded in conversation history — use {@link turn}
+	* for that.
+	*
+	* @param toolName - The tool to execute.
+	* @param args - Arguments to pass to the tool.
+	* @returns The tool's string result.
+	*
+	* @example
+	* ```ts
+	* const result = await t.executeTool("get_weather", { city: "London" });
+	* const data = JSON.parse(result);
+	* expect(data.temp).toBeDefined();
+	* ```
+	*/
+	async executeTool(toolName, args = {}) {
+		return this._executor.executeTool(toolName, args, this._sessionId, this._messages);
+	}
+	/**
+	* Simulate a user turn: add the user message, execute the given tool calls
+	* in sequence, and record everything.
+	*
+	* This is the primary method for testing agent behavior. It:
+	* 1. Fires `onConnect` if this is the first turn
+	* 2. Adds the user message to conversation history
+	* 3. Fires the `onTurn` hook
+	* 4. Executes each tool call in order, firing `onStep` for each
+	* 5. Returns a {@link TurnResult} with assertion helpers
+	*
+	* @param text - The user's spoken/typed input.
+	* @param toolCalls - Tool calls to execute (simulating what the LLM would invoke).
+	* @returns A {@link TurnResult} with recorded tool calls and assertion methods.
+	*
+	* @example
+	* ```ts
+	* const turn = await t.turn("Add pepperoni pizza", [
+	*   { tool: "add_pizza", args: { size: "large", crust: "regular", toppings: ["pepperoni"], quantity: 1 } },
+	* ]);
+	* expect(turn).toHaveCalledTool("add_pizza", { size: "large" });
+	* expect(turn.toolCalls[0].result).toContain("$14.99");
+	* ```
+	*/
+	async turn(text, toolCalls = []) {
+		await this.connect();
+		this._messages.push({
+			role: "user",
+			content: text
+		});
+		this._onTurnCalls.push(text);
+		await this._executor.hookInvoker.onTurn(this._sessionId, text);
+		const recorded = [];
+		for (let i = 0; i < toolCalls.length; i++) {
+			const tc = toolCalls[i];
+			const result = await this._executor.executeTool(tc.tool, tc.args, this._sessionId, this._messages);
+			recorded.push({
+				toolName: tc.tool,
+				args: tc.args,
+				result
+			});
+			this._messages.push({
+				role: "tool",
+				content: result
+			});
+			const step = {
+				stepNumber: i + 1,
+				toolCalls: [{
+					toolName: tc.tool,
+					args: tc.args
+				}],
+				text: ""
+			};
+			this._onStepCalls.push(step);
+			await this._executor.hookInvoker.onStep(this._sessionId, step);
+		}
+		return new TurnResult(text, recorded);
+	}
+	/**
+	* Add a user message to conversation history without executing tools.
+	*
+	* Useful for setting up conversation context before a turn.
+	*/
+	addUserMessage(text) {
+		this._messages.push({
+			role: "user",
+			content: text
+		});
+	}
+	/**
+	* Add an assistant message to conversation history.
+	*
+	* Useful for simulating prior assistant responses in multi-turn tests.
+	*/
+	addAssistantMessage(text) {
+		this._messages.push({
+			role: "assistant",
+			content: text
+		});
+	}
+	/**
+	* Reset conversation state: clears messages, step/turn history.
+	*
+	* Does **not** reset KV or vector store — create a new harness for that.
+	*/
+	reset() {
+		this._messages = [];
+		this._onStepCalls = [];
+		this._onTurnCalls = [];
+	}
+};
+/**
+* Create a SQLite-vec backed vector store with deterministic test embeddings.
+* Uses a temp directory that is unique per call for test isolation.
+*/
+function createTestVectorStore() {
+	return createSqliteVectorStore({
+		path: join(mkdtempSync(join(tmpdir(), "aai-test-vec-")), "vectors.db"),
+		embedFn: createTestEmbedFn()
+	});
+}
+/**
+* Create a test harness for unit-testing an agent.
+*
+* The harness wraps the agent's tool definitions and lifecycle hooks,
+* providing a simple API for executing tools and simulating multi-turn
+* conversations — all without audio, network, or an LLM.
+*
+* @param agent - The agent definition returned by `defineAgent()`.
+* @param options - Optional environment, KV, and vector store overrides.
+* @returns A {@link TestHarness} instance.
+*
+* @example
+* ```ts
+* import { createTestHarness } from "@alexkroman1/aai/testing";
+* import agent from "./agent.ts";
+*
+* const t = createTestHarness(agent);
+* const result = await t.executeTool("my_tool", { key: "value" });
+* ```
+*
+* @example With environment variables
+* ```ts
+* const t = createTestHarness(agent, {
+*   env: { API_KEY: "test-key" },
+* });
+* ```
+*
+* @public
+*/
+function createTestHarness(agent, options = {}) {
+	const { env = {}, kv = createSqliteKv({ path: ":memory:" }), vector = createTestVectorStore() } = options;
+	return new TestHarness(createDirectExecutor({
+		agent,
+		env,
+		kv,
+		vector
+	}), `test-${Date.now()}`);
+}
+//#endregion
+export { installMockWebSocket as a, MockWebSocket as i, TurnResult as n, createTestHarness as r, TestHarness as t };