@alexkroman1/aai 0.12.3 → 1.0.2

package/dist/host/index.js

@@ -1,165 +0,0 @@
-import { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, defineAgent, defineTool, defineToolFactory } from "../isolate/types.js";
-import { a as agentToolsToSchemas, i as ToolSchemaSchema, n as AgentConfigSchema, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-DYAYFW99.js";
-import { errorDetail, errorMessage, toolError } from "../isolate/_utils.js";
-import { C as MAX_VALUE_SIZE, S as MAX_TOOL_RESULT_CHARS, T as TOOL_EXECUTION_TIMEOUT_MS, _ as FETCH_TIMEOUT_MS, a as ReadyConfigSchema, b as MAX_HTML_BYTES, c as TurnConfigSchema, d as DEFAULT_IDLE_TIMEOUT_MS, f as DEFAULT_MAX_HISTORY, g as DEFAULT_TTS_SAMPLE_RATE, h as DEFAULT_STT_SAMPLE_RATE, i as KvRequestSchema, l as buildReadyConfig, m as DEFAULT_SHUTDOWN_TIMEOUT_MS, n as ClientEventSchema, o as ServerMessageSchema, p as DEFAULT_SESSION_START_TIMEOUT_MS, r as ClientMessageSchema, s as SessionErrorCodeSchema, t as AUDIO_FORMAT, u as AGENT_CSP, v as HOOK_TIMEOUT_MS, w as RUN_CODE_TIMEOUT_MS, x as MAX_PAGE_CHARS, y as MAX_GLOB_PATTERN_LENGTH } from "../protocol-rcOrz7T3.js";
-import { callResolveTurnConfig, createAgentHooks } from "../isolate/hooks.js";
-import "../isolate/index.js";
-import { a as _internals, c as connectS2s, d as consoleLogger, f as jsonLogger, g as executeInIsolate, h as getBuiltinToolSchemas, i as createUnstorageKv, l as defaultCreateS2sWebSocket, m as getBuiltinToolGuidance, n as executeToolCall, o as buildCtx, p as getBuiltinToolDefs, r as wireSessionSocket, s as createS2sSession, t as createRuntime, u as DEFAULT_S2S_CONFIG } from "../direct-executor-DRRrZUp0.js";
-import { z } from "zod";
-import { describe, expect, test } from "vitest";
-//#region host/_runtime-conformance.ts
-/**
-* Shared runtime conformance tests.
-*
-* Both the self-hosted direct executor and the platform sandbox must satisfy
-* the same behavioral contract. This module defines that contract as a
-* reusable test suite that can be wired to either runtime.
-*
-* Inspired by Nitro's `testNitro()` pattern: one test fixture, many runtimes.
-*
-* @example Direct executor (unit test)
-* ```ts
-* import { testRuntime } from "./_runtime-conformance.ts";
-*
-* testRuntime("direct", () => {
-*   const exec = createRuntime({ agent: CONFORMANCE_AGENT, env: { MY_VAR: "test-value" } });
-*   return { executeTool: exec.executeTool, hooks: exec.hooks };
-* });
-* ```
-*
-* @example Sandbox (integration test in aai-server)
-* ```ts
-* import { testRuntime } from "@alexkroman1/aai/host";
-*
-* testRuntime("sandbox", async () => {
-*   // ... start isolate with a bundled agent
-*   return { executeTool: buildExecuteTool(...), hooks: buildHookInvoker(...) };
-* });
-* ```
-*/
-/** Agent definition used by the conformance suite (direct executor path). */
-const CONFORMANCE_AGENT = {
-	name: "conformance-test",
-	instructions: "Conformance test agent.",
-	greeting: "Hello!",
-	maxSteps: 5,
-	state: () => ({
-		count: 0,
-		lastTurn: ""
-	}),
-	tools: {
-		echo: defineTool({
-			description: "Echo input",
-			parameters: z.object({ text: z.string() }),
-			execute: ({ text }) => `echo:${text}`
-		}),
-		get_env: {
-			description: "Get MY_VAR from env",
-			execute: (_args, ctx) => ctx.env.MY_VAR ?? "missing"
-		},
-		get_state: {
-			description: "Get session state",
-			execute: (_args, ctx) => JSON.stringify(ctx.state)
-		},
-		echo_messages: {
-			description: "Return messages as JSON",
-			execute: (_args, ctx) => JSON.stringify(ctx.messages)
-		},
-		kv_roundtrip: defineTool({
-			description: "KV set then get",
-			parameters: z.object({ value: z.string() }),
-			execute: async ({ value }, ctx) => {
-				await ctx.kv.set("test-key", value);
-				const result = await ctx.kv.get("test-key");
-				return `stored:${JSON.stringify(result)}`;
-			}
-		})
-	},
-	onConnect: (ctx) => {
-		ctx.state.count = 1;
-	},
-	onTurn: (text, ctx) => {
-		ctx.state.lastTurn = text;
-	}
-};
-/**
-* Run the runtime conformance test suite against a given runtime context.
-*
-* The `getContext` callback is invoked once per test to retrieve the
-* current {@link RuntimeTestContext}. This allows the caller to set up
-* the runtime in a `beforeAll` and return it lazily.
-*
-* All tests assume the runtime was created with {@link CONFORMANCE_AGENT}
-* (or its bundle equivalent) and `env: { MY_VAR: "test-value" }`.
-*/
-function testRuntime(label, getContext) {
-	describe(`runtime conformance: ${label}`, () => {
-		test("executes tool and returns result", async () => {
-			const { executeTool } = getContext();
-			expect(await executeTool("echo", { text: "hello" }, "s1", [])).toBe("echo:hello");
-		});
-		test("tool receives env variables", async () => {
-			const { executeTool } = getContext();
-			expect(await executeTool("get_env", {}, "s1", [])).toBe("test-value");
-		});
-		test("tool receives conversation messages", async () => {
-			const { executeTool } = getContext();
-			const msgs = [{
-				role: "user",
-				content: "hi"
-			}, {
-				role: "assistant",
-				content: "hello"
-			}];
-			const result = await executeTool("echo_messages", {}, "s1", msgs);
-			expect(JSON.parse(result)).toEqual(msgs);
-		});
-		test("KV round-trip through tool context", async () => {
-			const { executeTool } = getContext();
-			expect(await executeTool("kv_roundtrip", { value: "abc" }, "s1", [])).toBe("stored:\"abc\"");
-		});
-		test("session state is initialized from factory", async () => {
-			const { executeTool } = getContext();
-			const result = await executeTool("get_state", {}, "state-init", []);
-			const state = JSON.parse(result);
-			expect(state).toHaveProperty("count", 0);
-			expect(state).toHaveProperty("lastTurn", "");
-		});
-		test("onConnect hook updates session state", async () => {
-			const { executeTool, hooks } = getContext();
-			const sid = "state-connect";
-			await hooks.callHook("connect", sid);
-			const result = await executeTool("get_state", {}, sid, []);
-			expect(JSON.parse(result).count).toBe(1);
-		});
-		test("onTurn hook updates session state", async () => {
-			const { executeTool, hooks } = getContext();
-			const sid = "state-turn";
-			await hooks.callHook("turn", sid, "user said something");
-			const result = await executeTool("get_state", {}, sid, []);
-			expect(JSON.parse(result).lastTurn).toBe("user said something");
-		});
-		test("onConnect resolves without error", async () => {
-			const { hooks } = getContext();
-			await expect(hooks.callHook("connect", "hook-1")).resolves.toBeUndefined();
-		});
-		test("onDisconnect resolves without error", async () => {
-			const { hooks } = getContext();
-			await expect(hooks.callHook("disconnect", "hook-2")).resolves.toBeUndefined();
-		});
-		test("onTurn resolves without error", async () => {
-			const { hooks } = getContext();
-			await expect(hooks.callHook("turn", "hook-3", "test")).resolves.toBeUndefined();
-		});
-		test("onError resolves without error", async () => {
-			const { hooks } = getContext();
-			await expect(hooks.callHook("error", "hook-4", { message: "boom" })).resolves.toBeUndefined();
-		});
-		test("resolveTurnConfig returns null for static maxSteps", async () => {
-			const { hooks } = getContext();
-			expect(await callResolveTurnConfig(hooks, "hook-5")).toBeNull();
-		});
-	});
-}
-//#endregion
-export { AGENT_CSP, AUDIO_FORMAT, AgentConfigSchema, BuiltinToolSchema, CONFORMANCE_AGENT, ClientEventSchema, ClientMessageSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_INSTRUCTIONS, DEFAULT_MAX_HISTORY, DEFAULT_S2S_CONFIG, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE, EMPTY_PARAMS, FETCH_TIMEOUT_MS, HOOK_TIMEOUT_MS, KvRequestSchema, MAX_GLOB_PATTERN_LENGTH, MAX_HTML_BYTES, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, RUN_CODE_TIMEOUT_MS, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, ToolSchemaSchema, TurnConfigSchema, _internals, agentToolsToSchemas, buildCtx, buildReadyConfig, buildSystemPrompt, callResolveTurnConfig, connectS2s, consoleLogger, createAgentHooks, createRuntime, createS2sSession, createUnstorageKv, defaultCreateS2sWebSocket, defineAgent, defineTool, defineTool as tool, defineToolFactory, errorDetail, errorMessage, executeInIsolate, executeToolCall, getBuiltinToolDefs, getBuiltinToolGuidance, getBuiltinToolSchemas, jsonLogger, testRuntime, toAgentConfig, toolError, wireSessionSocket };

package/dist/host/matchers.d.ts

@@ -1,20 +0,0 @@
-/**
- * Vitest custom matchers for AAI testing.
- *
- * Add this to your Vitest setup file to enable `expect(turn).toHaveCalledTool()`:
- *
- * ```ts
- * // vitest.config.ts
- * export default defineConfig({
- *   test: { setupFiles: ["@alexkroman1/aai/testing/matchers"] },
- * });
- * ```
- *
- * Or import directly in your test file:
- * ```ts
- * import "@alexkroman1/aai/testing/matchers";
- * ```
- *
- * @packageDocumentation
- */
-export {};

package/dist/host/matchers.js

@@ -1,41 +0,0 @@
-import { n as TurnResult } from "../testing-BreLdpq-.js";
-import { expect } from "vitest";
-//#region host/matchers.ts
-/**
-* Vitest custom matchers for AAI testing.
-*
-* Add this to your Vitest setup file to enable `expect(turn).toHaveCalledTool()`:
-*
-* ```ts
-* // vitest.config.ts
-* export default defineConfig({
-*   test: { setupFiles: ["@alexkroman1/aai/testing/matchers"] },
-* });
-* ```
-*
-* Or import directly in your test file:
-* ```ts
-* import "@alexkroman1/aai/testing/matchers";
-* ```
-*
-* @packageDocumentation
-*/
-expect.extend({ toHaveCalledTool(received, toolName, args) {
-	if (!(received instanceof TurnResult)) return {
-		pass: false,
-		message: () => `expected a TurnResult, got ${typeof received}`,
-		actual: received,
-		expected: "TurnResult"
-	};
-	const pass = received.toHaveCalledTool(toolName, args);
-	const calledTools = received.toolCalls.map((tc) => tc.toolName);
-	const argsHint = args ? ` with args ${JSON.stringify(args)}` : "";
-	return {
-		pass,
-		message: () => pass ? `expected turn NOT to have called tool "${toolName}"${argsHint}, but it was called.\nCalled tools: ${JSON.stringify(calledTools)}` : `expected turn to have called tool "${toolName}"${argsHint}, but it was not.\nCalled tools: ${JSON.stringify(calledTools)}`,
-		actual: calledTools,
-		expected: toolName
-	};
-} });
-//#endregion
-export {};

package/dist/host/server.js

@@ -1,164 +0,0 @@
-import { u as AGENT_CSP } from "../protocol-rcOrz7T3.js";
-import { d as consoleLogger, t as createRuntime } from "../direct-executor-DRRrZUp0.js";
-import { WebSocketServer } from "ws";
-import fs from "node:fs";
-import http from "node:http";
-import path from "node:path";
-//#region host/server.ts
-/**
-* Self-hostable agent server.
-*
-* {@link createServer} wraps a {@link Runtime} with an HTTP + WebSocket
-* server using only `node:http` and `ws` (no framework dependencies).
-*/
-const MIME_TYPES = {
-	".html": "text/html",
-	".js": "application/javascript",
-	".mjs": "application/javascript",
-	".css": "text/css",
-	".json": "application/json",
-	".svg": "image/svg+xml",
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".ico": "image/x-icon",
-	".woff2": "font/woff2",
-	".woff": "font/woff",
-	".map": "application/json"
-};
-function serveStatic(dir, req, res) {
-	const url = req.url?.split("?")[0] ?? "/";
-	const filePath = path.join(dir, url === "/" ? "index.html" : url);
-	if (!filePath.startsWith(dir)) return false;
-	try {
-		const stat = fs.statSync(filePath);
-		if (!stat.isFile()) return false;
-		const mime = MIME_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
-		res.writeHead(200, {
-			"Content-Type": mime,
-			"Content-Length": stat.size
-		});
-		fs.createReadStream(filePath).pipe(res);
-		return true;
-	} catch {
-		return false;
-	}
-}
-/**
-* Create an HTTP + WebSocket server for self-hosted agent deployments.
-*
-* @example
-* ```ts
-* import { defineAgent } from "@alexkroman1/aai";
-* import { createRuntime, createServer } from "@alexkroman1/aai/server";
-*
-* const agent = defineAgent({ name: "my-agent" });
-* const runtime = createRuntime({ agent, env: process.env });
-* const server = createServer({ runtime, name: agent.name });
-* await server.listen(3000);
-* ```
-*
-* @public
-*/
-function handleKvGet(kv, req, res) {
-	const key = new URL(req.url ?? "/", "http://localhost").searchParams.get("key");
-	if (!key) {
-		res.writeHead(400, { "Content-Type": "application/json" });
-		res.end(JSON.stringify({ error: "Missing key query parameter" }));
-		return;
-	}
-	kv.get(key).then((value) => {
-		if (value === null) {
-			res.writeHead(404, { "Content-Type": "application/json" });
-			res.end("null");
-		} else {
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify(value));
-		}
-	}).catch(() => {
-		res.writeHead(500, { "Content-Type": "application/json" });
-		res.end(JSON.stringify({ error: "KV error" }));
-	});
-}
-function createServer(options) {
-	const { runtime, clientHtml, clientDir, logger = consoleLogger, kv } = options;
-	const name = options.name ?? "agent";
-	if (clientHtml && clientDir) throw new Error("clientHtml and clientDir are mutually exclusive");
-	const httpServer = http.createServer((req, res) => {
-		const url = req.url?.split("?")[0] ?? "/";
-		const method = req.method ?? "GET";
-		res.setHeader("Content-Security-Policy", AGENT_CSP);
-		res.setHeader("X-Content-Type-Options", "nosniff");
-		res.setHeader("X-Frame-Options", "SAMEORIGIN");
-		if (method === "GET" && url === "/health") {
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify({
-				status: "ok",
-				name
-			}));
-			return;
-		}
-		if (kv && method === "GET" && url === "/kv") {
-			handleKvGet(kv, req, res);
-			return;
-		}
-		if (clientDir && serveStatic(clientDir, req, res)) return;
-		if (method === "GET" && url === "/") {
-			const escaped = name.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-			const body = clientHtml ?? `<!DOCTYPE html><html><body><h1>${escaped}</h1><p>Agent server running.</p></body></html>`;
-			res.writeHead(200, { "Content-Type": "text/html" });
-			res.end(body);
-			return;
-		}
-		logger.error(`${method} ${url} 404`);
-		res.writeHead(404, { "Content-Type": "application/json" });
-		res.end(JSON.stringify({ error: "Not found" }));
-	});
-	const wss = new WebSocketServer({ noServer: true });
-	httpServer.on("upgrade", (req, socket, head) => {
-		const url = req.url?.split("?")[0] ?? "";
-		if (!url.startsWith("/websocket")) return;
-		wss.handleUpgrade(req, socket, head, (ws) => {
-			const search = req.url?.includes("?") ? req.url.split("?")[1] ?? "" : "";
-			const params = new URLSearchParams(search);
-			const resumeFrom = params.get("sessionId") ?? void 0;
-			const skipGreeting = params.has("resume") || resumeFrom !== void 0;
-			logger.info(`WS upgrade ${url}${skipGreeting ? " (resume)" : ""}`);
-			runtime.startSession(ws, {
-				skipGreeting,
-				...resumeFrom ? { resumeFrom } : {}
-			});
-		});
-	});
-	let listenPort;
-	return {
-		get port() {
-			return listenPort;
-		},
-		async listen(port = 3e3) {
-			await new Promise((resolve, reject) => {
-				httpServer.on("error", reject);
-				httpServer.listen(port, () => {
-					const addr = httpServer.address();
-					listenPort = typeof addr === "object" && addr ? addr.port : port;
-					resolve();
-				});
-			});
-		},
-		async close() {
-			try {
-				await runtime.shutdown();
-			} finally {
-				try {
-					wss.close();
-				} finally {
-					if (listenPort !== void 0) await new Promise((resolve, reject) => {
-						httpServer.close((err) => err ? reject(err) : resolve());
-					});
-					listenPort = void 0;
-				}
-			}
-		}
-	};
-}
-//#endregion
-export { createRuntime, createServer };

package/dist/host/testing.d.ts

@@ -1,294 +0,0 @@
-/**
- * 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
- */
-import type { Kv } from "../isolate/kv.ts";
-import type { AgentDef, Message } from "../isolate/types.ts";
-import { type Runtime } from "./direct-executor.ts";
-export { installMockWebSocket, MockWebSocket } from "./_mock-ws.ts";
-export { flush, makeStubSession } from "./_test-utils.ts";
-/**
- * A single tool call recorded during a turn.
- *
- * @public
- */
-export type RecordedToolCall = {
-    /** The name of the tool that was called. */
-    toolName: string;
-    /** The arguments passed to the tool. */
-    args: Readonly<Record<string, unknown>>;
-    /** The string result returned by the tool. */
-    result: string;
-};
-/**
- * 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
- */
-export declare class TurnResult {
-    /** The user text that initiated this turn. */
-    readonly text: string;
-    /** All tool calls executed during this turn, in order. */
-    readonly toolCalls: readonly RecordedToolCall[];
-    /** Convenience accessor: just the result strings from each tool call. */
-    readonly toolResults: readonly string[];
-    /** @internal */
-    constructor(text: string, toolCalls: RecordedToolCall[]);
-    /**
-     * 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: string, args?: Record<string, unknown>): boolean;
-    /**
-     * 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: string): readonly RecordedToolCall[];
-    /**
-     * 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<T = unknown>(toolName: string): T;
-}
-/**
- * Options for creating a {@link TestHarness}.
- *
- * @public
- */
-export type TestHarnessOptions = {
-    /** Environment variables available to tools via `ctx.env`. */
-    env?: Record<string, string>;
-    /** KV store instance. Defaults to an in-memory SQLite store. */
-    kv?: Kv;
-};
-/**
- * A tool call to execute during a simulated turn.
- *
- * @public
- */
-export type TurnToolCall = {
-    /** The tool name to invoke. */
-    tool: string;
-    /** Arguments to pass to the tool. */
-    args: Record<string, unknown>;
-};
-/**
- * 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
- */
-export declare class TestHarness {
-    /** @internal */
-    readonly _executor: Runtime;
-    /** @internal */
-    readonly _sessionId: string;
-    private _messages;
-    private _onTurnCalls;
-    private _connected;
-    /** @internal */
-    constructor(executor: Runtime, sessionId: string);
-    /** Conversation messages accumulated across turns. */
-    get messages(): readonly Message[];
-    /** All `onTurn` hook invocations (the text argument) recorded so far. */
-    get turns(): readonly string[];
-    /**
-     * Fire the `onConnect` lifecycle hook.
-     *
-     * Called automatically on the first {@link turn} call if not called manually.
-     */
-    connect(): Promise<void>;
-    /**
-     * Fire the `onDisconnect` lifecycle hook and clean up session state.
-     */
-    disconnect(): Promise<void>;
-    /**
-     * Execute a single tool by name with the given arguments.
-     *
-     * The tool runs with full agent context (env, state, kv, 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();
-     * ```
-     */
-    executeTool(toolName: string, args?: Record<string, unknown>): Promise<string>;
-    /**
-     * 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
-     * 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");
-     * ```
-     */
-    turn(text: string, toolCalls?: TurnToolCall[]): Promise<TurnResult>;
-    /**
-     * Add a user message to conversation history without executing tools.
-     *
-     * Useful for setting up conversation context before a turn.
-     */
-    addUserMessage(text: string): void;
-    /**
-     * Add an assistant message to conversation history.
-     *
-     * Useful for simulating prior assistant responses in multi-turn tests.
-     */
-    addAssistantMessage(text: string): void;
-    /**
-     * Reset conversation state: clears messages, step/turn history.
-     *
-     * Does **not** reset KV store — create a new harness for that.
-     */
-    reset(): void;
-}
-/**
- * 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 and KV 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
- */
-export declare function createTestHarness(agent: AgentDef<any>, options?: TestHarnessOptions): TestHarness;

package/dist/host/testing.js

@@ -1,2 +0,0 @@
-import { a as makeStubSession, i as flush, n as TurnResult, o as MockWebSocket, r as createTestHarness, s as installMockWebSocket, t as TestHarness } from "../testing-BreLdpq-.js";
-export { MockWebSocket, TestHarness, TurnResult, createTestHarness, flush, installMockWebSocket, makeStubSession };