@alexkroman1/aai 0.10.2 → 0.10.3

package/dist/server.js

@@ -1,14 +1,17 @@
-import { filterEnv } from "./_utils.js";
-import { t as createDirectExecutor } from "./direct-executor-Ca0wt5H0.js";
-import { buildReadyConfig } from "./protocol.js";
-import { DEFAULT_S2S_CONFIG, consoleLogger } from "./runtime.js";
-import { createSqliteKv } from "./sqlite-kv.js";
-import { wireSessionSocket } from "./ws-handler.js";
-import { mkdirSync } from "node:fs";
-import { WebSocketServer } from "ws";
+import { t as createUnstorageVectorStore } from "./unstorage-vector-Cj5llNhg.js";
+import { i as filterEnv } from "./_utils-DgzpOMSV.js";
+import { t as createDirectExecutor } from "./direct-executor-B-5mq3cu.js";
+import { m as buildReadyConfig } from "./protocol-B-H2Q4ox.js";
+import { n as consoleLogger, t as DEFAULT_S2S_CONFIG } from "./runtime-CxcwaK68.js";
+import { t as createUnstorageKv } from "./unstorage-kv-CDgP-frt.js";
+import { t as wireSessionSocket } from "./ws-handler-C0Q6eSay.js";
+import { createStorage } from "unstorage";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
+import { createNodeWebSocket } from "@hono/node-ws";
 import { Hono } from "hono";
+import { html } from "hono/html";
+import { secureHeaders } from "hono/secure-headers";
 //#region server.ts
 /**
 * Self-hostable agent server.
@@ -17,16 +20,6 @@ import { Hono } from "hono";
 * Calls `createDirectExecutor` + `wireSessionSocket` directly — no
 * intermediary needed.
 */
-/** Escape HTML special characters to prevent XSS. */
-function escapeHtml(s) {
-	return s.replace(/[&<>"']/g, (ch) => ({
-		"&": "&amp;",
-		"<": "&lt;",
-		">": "&gt;",
-		"\"": "&quot;",
-		"'": "&#39;"
-	})[ch]);
-}
 /**
 * Create an HTTP + WebSocket server for self-hosted agent deployments.
 *
@@ -66,23 +59,20 @@ async function drainSessions(sessions, shutdownTimeoutMs, logger) {
 }
 function createServer(options) {
 	if (options.clientHtml && options.clientDir) throw new Error("ServerOptions: clientHtml and clientDir are mutually exclusive — provide one or the other, not both.");
-	const { agent, kv, vector, clientHtml, clientDir, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG, shutdownTimeoutMs = 3e4 } = options;
+	const { agent, clientHtml, clientDir, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG, shutdownTimeoutMs = 3e4 } = options;
 	const env = filterEnv(options.env ?? (typeof process !== "undefined" ? process.env : {}));
-	const resolvedKv = kv ?? (() => {
-		mkdirSync(".aai", { recursive: true });
-		return createSqliteKv();
-	})();
+	const storage = options.storage ?? createStorage();
+	const kv = createUnstorageKv({ storage });
 	const executor = createDirectExecutor({
 		agent,
 		env,
-		kv: resolvedKv,
-		...vector ? { vector } : {},
+		kv,
+		vector: createUnstorageVectorStore({ storage }),
 		logger,
 		s2sConfig
 	});
 	const sessions = /* @__PURE__ */ new Map();
 	const readyConfig = buildReadyConfig(s2sConfig);
-	const safeAgentName = escapeHtml(agent.name);
 	function handleWs(ws, skipGreeting, resumeFrom) {
 		wireSessionSocket(ws, {
 			sessions,
@@ -108,6 +98,7 @@ function createServer(options) {
 		async listen(port = 3e3) {
 			if (serverHandle) throw new Error("Server is already listening");
 			const app = new Hono();
+			const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
 			app.onError((err, c) => {
 				logger.error(`${c.req.method} ${c.req.path} error: ${err.message}`);
 				return c.json({ error: "Internal Server Error" }, 500);
@@ -122,6 +113,24 @@ function createServer(options) {
 				if (status >= 400) logger.error(`${method} ${path} ${status} ${ms}ms`);
 				else logger.info(`${method} ${path} ${status} ${ms}ms`);
 			});
+			app.use("*", secureHeaders({ contentSecurityPolicy: {
+				defaultSrc: ["'self'"],
+				scriptSrc: ["'self'", "blob:"],
+				styleSrc: [
+					"'self'",
+					"'unsafe-inline'",
+					"https://fonts.googleapis.com"
+				],
+				connectSrc: [
+					"'self'",
+					"wss:",
+					"ws:"
+				],
+				imgSrc: ["'self'", "data:"],
+				fontSrc: ["'self'", "https://fonts.gstatic.com"],
+				objectSrc: ["'none'"],
+				baseUri: ["'self'"]
+			} }));
 			app.get("/health", (c) => c.json({
 				status: "ok",
 				name: agent.name
@@ -129,40 +138,35 @@ function createServer(options) {
 			app.get("/kv", async (c) => {
 				const key = c.req.query("key");
 				if (!key) return c.json({ error: "Missing key query parameter" }, 400);
-				const value = await resolvedKv.get(key);
+				const value = await kv.get(key);
 				if (value === null) return c.json(null, 404);
 				return c.json(value);
 			});
 			if (clientDir) app.use("/*", serveStatic({ root: clientDir }));
-			const csp = "default-src 'self'; script-src 'self' blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; connect-src 'self' wss: ws:; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com; object-src 'none'; base-uri 'self'";
 			app.get("/", (c) => {
-				if (clientHtml) return c.html(clientHtml, 200, { "Content-Security-Policy": csp });
-				return c.html(`<!DOCTYPE html><html><body><h1>${safeAgentName}</h1><p>Agent server running.</p></body></html>`, 200, { "Content-Security-Policy": csp });
+				if (clientHtml) return c.html(clientHtml);
+				return c.html(html`<!DOCTYPE html><html><body><h1>${agent.name}</h1><p>Agent server running.</p></body></html>`);
 			});
+			app.get("/websocket", upgradeWebSocket((c) => {
+				const resumeFrom = c.req.query("sessionId") ?? void 0;
+				const skipGreeting = c.req.query("resume") !== void 0 || resumeFrom !== void 0;
+				logger.info(`WS upgrade ${c.req.path}${skipGreeting ? " (resume)" : ""}`);
+				return { onOpen(_evt, ws) {
+					if (ws.raw) handleWs(ws.raw, skipGreeting, resumeFrom);
+				} };
+			}));
 			const nodeServer = serve({
 				fetch: app.fetch,
 				port
 			});
+			injectWebSocket(nodeServer);
 			await new Promise((resolve, reject) => {
 				nodeServer.on("listening", resolve);
 				nodeServer.on("error", reject);
 			});
 			const addr = nodeServer.address();
 			listenPort = typeof addr === "object" && addr ? addr.port : port;
-			const wss = new WebSocketServer({ noServer: true });
-			nodeServer.on("upgrade", (req, socket, head) => {
-				const reqUrl = new URL(req.url ?? "/", `http://localhost:${listenPort}`);
-				const resumeFrom = reqUrl.searchParams.get("sessionId") ?? void 0;
-				const skipGreeting = reqUrl.searchParams.has("resume") || resumeFrom !== void 0;
-				logger.info(`WS upgrade ${reqUrl.pathname}${skipGreeting ? " (resume)" : ""}`);
-				wss.handleUpgrade(req, socket, head, (ws) => {
-					handleWs(ws, skipGreeting, resumeFrom);
-				});
-			});
 			serverHandle = { async shutdown() {
-				await new Promise((resolve, reject) => {
-					wss.close((err) => err ? reject(err) : resolve());
-				});
 				await new Promise((resolve, reject) => {
 					nodeServer.close((err) => err ? reject(err) : resolve());
 				});

package/dist/{session-BkN9u0ni.js → session-BYlwcrya.js}

@@ -1,9 +1,9 @@
-import { DEFAULT_INSTRUCTIONS } from "./types.js";
-import { errorDetail, errorMessage, toolError } from "./_utils.js";
-import { HOOK_TIMEOUT_MS, MAX_TOOL_RESULT_CHARS } from "./protocol.js";
-import { consoleLogger } from "./runtime.js";
-import { activeSessionsUpDown, bargeInCounter, idleTimeoutCounter, sessionCounter, toolCallCounter, toolCallDuration, toolCallErrorCounter, tracer, turnCounter, turnStepsHistogram } from "./telemetry.js";
-import { connectS2s, defaultCreateS2sWebSocket } from "./s2s.js";
+import { r as DEFAULT_INSTRUCTIONS } from "./types-D8ZBxTL_.js";
+import { n as errorDetail, r as errorMessage, s as toolError } from "./_utils-DgzpOMSV.js";
+import { c as MAX_TOOL_RESULT_CHARS, o as HOOK_TIMEOUT_MS } from "./protocol-B-H2Q4ox.js";
+import { n as consoleLogger } from "./runtime-CxcwaK68.js";
+import { _ as turnStepsHistogram, a as idleTimeoutCounter, d as toolCallCounter, f as toolCallDuration, g as turnCounter, h as tracer, n as activeSessionsUpDown, p as toolCallErrorCounter, r as bargeInCounter, u as sessionCounter } from "./telemetry-CJlaDFNc.js";
+import { n as defaultCreateS2sWebSocket, t as connectS2s } from "./s2s-M7JqtgFw.js";
 //#region _session-ctx.ts
 const DEFAULT_MAX_HISTORY = 200;
 function buildCtx(opts) {

package/dist/session.js

@@ -1,2 +1,2 @@
-import { i as persistKey, n as createS2sSession, r as buildSystemPrompt, t as _internals } from "./session-BkN9u0ni.js";
+import { i as persistKey, n as createS2sSession, r as buildSystemPrompt, t as _internals } from "./session-BYlwcrya.js";
 export { _internals, buildSystemPrompt, createS2sSession, persistKey };

package/dist/telemetry-CJlaDFNc.js

@@ -0,0 +1,95 @@
+import { createRequire } from "node:module";
+import { SpanStatusCode, SpanStatusCode as SpanStatusCode$1, context, metrics, metrics as metrics$1, trace, trace as trace$1 } from "@opentelemetry/api";
+//#region telemetry.ts
+/**
+* OpenTelemetry instrumentation helpers for the AAI SDK.
+*
+* Uses `@opentelemetry/api` only — consumers bring their own SDK and
+* exporters.  When no SDK is configured the API returns no-op instances,
+* so the overhead in uninstrumented environments is negligible.
+*
+* Provides:
+* - `tracer`  — a pre-scoped `Tracer` for creating spans
+* - `meter`   — a pre-scoped `Meter` for recording metrics
+* - Pre-built counters, histograms, and up/down counters covering the
+*   STT → LLM → TTS pipeline
+*/
+const SCOPE = "aai";
+const _require = createRequire(import.meta.url);
+let VERSION = "0.0.0";
+try {
+	VERSION = _require("./package.json").version;
+} catch {
+	VERSION = _require("../package.json").version;
+}
+/** Tracer scoped to the AAI SDK. */
+const tracer = trace.getTracer(SCOPE, VERSION);
+/** Meter scoped to the AAI SDK. */
+const meter = metrics.getMeter(SCOPE, VERSION);
+/** Total sessions opened. */
+const sessionCounter = meter.createCounter("aai.session.count", { description: "Total voice sessions opened" });
+/** Currently active sessions. */
+const activeSessionsUpDown = meter.createUpDownCounter("aai.session.active", { description: "Currently active voice sessions" });
+/** Total user turns (speech → transcript). */
+const turnCounter = meter.createCounter("aai.turn.count", { description: "Total user turns" });
+/** Total tool calls executed. */
+const toolCallCounter = meter.createCounter("aai.tool.call.count", { description: "Total tool calls executed" });
+/** Tool call execution duration in seconds. */
+const toolCallDuration = meter.createHistogram("aai.tool.call.duration", {
+	description: "Tool call execution duration in seconds",
+	unit: "s"
+});
+/** Total tool call errors. */
+const toolCallErrorCounter = meter.createCounter("aai.tool.call.error.count", { description: "Total tool call errors" });
+/** S2S WebSocket connection duration in seconds. */
+const s2sConnectionDuration = meter.createHistogram("aai.s2s.connection.duration", {
+	description: "S2S WebSocket connection duration in seconds",
+	unit: "s"
+});
+/** Total S2S errors. */
+const s2sErrorCounter = meter.createCounter("aai.s2s.error.count", { description: "Total S2S errors" });
+/** Number of agentic loop steps (tool calls) per completed turn. */
+const turnStepsHistogram = meter.createHistogram("aai.turn.steps", { description: "Number of agentic loop steps per completed turn" });
+/** Total barge-in (reply interrupted) events. */
+const bargeInCounter = meter.createCounter("aai.turn.bargein.count", { description: "Total barge-in (reply interrupted) events" });
+/** Messages silently dropped because the WebSocket was closed. */
+const wsSendDroppedCounter = meter.createCounter("aai.ws.send_dropped", { description: "Messages silently dropped because the WebSocket was closed" });
+/** Sessions closed due to S2S idle timeout. */
+const idleTimeoutCounter = meter.createCounter("aai.session.idle.timeout.count", { description: "Sessions closed due to S2S idle timeout" });
+/**
+* Run `fn` inside a new span. The span is automatically ended and its
+* status set based on whether `fn` throws.
+*/
+function withSpan(name, fn) {
+	return tracer.startActiveSpan(name, (span) => {
+		try {
+			const result = fn(span);
+			if (result instanceof Promise) return result.then((v) => {
+				span.setStatus({ code: SpanStatusCode.OK });
+				span.end();
+				return v;
+			}).catch((err) => {
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: err instanceof Error ? err.message : String(err)
+				});
+				span.recordException(err instanceof Error ? err : new Error(String(err)));
+				span.end();
+				throw err;
+			});
+			span.setStatus({ code: SpanStatusCode.OK });
+			span.end();
+			return result;
+		} catch (err) {
+			span.setStatus({
+				code: SpanStatusCode.ERROR,
+				message: err instanceof Error ? err.message : String(err)
+			});
+			span.recordException(err instanceof Error ? err : new Error(String(err)));
+			span.end();
+			throw err;
+		}
+	});
+}
+//#endregion
+export { turnStepsHistogram as _, idleTimeoutCounter as a, s2sConnectionDuration as c, toolCallCounter as d, toolCallDuration as f, turnCounter as g, tracer as h, context as i, s2sErrorCounter as l, trace$1 as m, activeSessionsUpDown as n, meter as o, toolCallErrorCounter as p, bargeInCounter as r, metrics$1 as s, SpanStatusCode$1 as t, sessionCounter as u, withSpan as v, wsSendDroppedCounter as y };

package/dist/telemetry.js

@@ -1,95 +1,2 @@
-import { createRequire } from "node:module";
-import { SpanStatusCode, SpanStatusCode as SpanStatusCode$1, context, metrics, metrics as metrics$1, trace, trace as trace$1 } from "@opentelemetry/api";
-//#region telemetry.ts
-/**
-* OpenTelemetry instrumentation helpers for the AAI SDK.
-*
-* Uses `@opentelemetry/api` only — consumers bring their own SDK and
-* exporters.  When no SDK is configured the API returns no-op instances,
-* so the overhead in uninstrumented environments is negligible.
-*
-* Provides:
-* - `tracer`  — a pre-scoped `Tracer` for creating spans
-* - `meter`   — a pre-scoped `Meter` for recording metrics
-* - Pre-built counters, histograms, and up/down counters covering the
-*   STT → LLM → TTS pipeline
-*/
-const SCOPE = "aai";
-const _require = createRequire(import.meta.url);
-let VERSION = "0.0.0";
-try {
-	VERSION = _require("./package.json").version;
-} catch {
-	VERSION = _require("../package.json").version;
-}
-/** Tracer scoped to the AAI SDK. */
-const tracer = trace$1.getTracer(SCOPE, VERSION);
-/** Meter scoped to the AAI SDK. */
-const meter = metrics$1.getMeter(SCOPE, VERSION);
-/** Total sessions opened. */
-const sessionCounter = meter.createCounter("aai.session.count", { description: "Total voice sessions opened" });
-/** Currently active sessions. */
-const activeSessionsUpDown = meter.createUpDownCounter("aai.session.active", { description: "Currently active voice sessions" });
-/** Total user turns (speech → transcript). */
-const turnCounter = meter.createCounter("aai.turn.count", { description: "Total user turns" });
-/** Total tool calls executed. */
-const toolCallCounter = meter.createCounter("aai.tool.call.count", { description: "Total tool calls executed" });
-/** Tool call execution duration in seconds. */
-const toolCallDuration = meter.createHistogram("aai.tool.call.duration", {
-	description: "Tool call execution duration in seconds",
-	unit: "s"
-});
-/** Total tool call errors. */
-const toolCallErrorCounter = meter.createCounter("aai.tool.call.error.count", { description: "Total tool call errors" });
-/** S2S WebSocket connection duration in seconds. */
-const s2sConnectionDuration = meter.createHistogram("aai.s2s.connection.duration", {
-	description: "S2S WebSocket connection duration in seconds",
-	unit: "s"
-});
-/** Total S2S errors. */
-const s2sErrorCounter = meter.createCounter("aai.s2s.error.count", { description: "Total S2S errors" });
-/** Number of agentic loop steps (tool calls) per completed turn. */
-const turnStepsHistogram = meter.createHistogram("aai.turn.steps", { description: "Number of agentic loop steps per completed turn" });
-/** Total barge-in (reply interrupted) events. */
-const bargeInCounter = meter.createCounter("aai.turn.bargein.count", { description: "Total barge-in (reply interrupted) events" });
-/** Messages silently dropped because the WebSocket was closed. */
-const wsSendDroppedCounter = meter.createCounter("aai.ws.send_dropped", { description: "Messages silently dropped because the WebSocket was closed" });
-/** Sessions closed due to S2S idle timeout. */
-const idleTimeoutCounter = meter.createCounter("aai.session.idle.timeout.count", { description: "Sessions closed due to S2S idle timeout" });
-/**
-* Run `fn` inside a new span. The span is automatically ended and its
-* status set based on whether `fn` throws.
-*/
-function withSpan(name, fn) {
-	return tracer.startActiveSpan(name, (span) => {
-		try {
-			const result = fn(span);
-			if (result instanceof Promise) return result.then((v) => {
-				span.setStatus({ code: SpanStatusCode$1.OK });
-				span.end();
-				return v;
-			}).catch((err) => {
-				span.setStatus({
-					code: SpanStatusCode$1.ERROR,
-					message: err instanceof Error ? err.message : String(err)
-				});
-				span.recordException(err instanceof Error ? err : new Error(String(err)));
-				span.end();
-				throw err;
-			});
-			span.setStatus({ code: SpanStatusCode$1.OK });
-			span.end();
-			return result;
-		} catch (err) {
-			span.setStatus({
-				code: SpanStatusCode$1.ERROR,
-				message: err instanceof Error ? err.message : String(err)
-			});
-			span.recordException(err instanceof Error ? err : new Error(String(err)));
-			span.end();
-			throw err;
-		}
-	});
-}
-//#endregion
+import { _ as turnStepsHistogram, a as idleTimeoutCounter, c as s2sConnectionDuration, d as toolCallCounter, f as toolCallDuration, g as turnCounter, h as tracer, i as context, l as s2sErrorCounter, m as trace, n as activeSessionsUpDown, o as meter, p as toolCallErrorCounter, r as bargeInCounter, s as metrics, t as SpanStatusCode, u as sessionCounter, v as withSpan, y as wsSendDroppedCounter } from "./telemetry-CJlaDFNc.js";
 export { SpanStatusCode, activeSessionsUpDown, bargeInCounter, context, idleTimeoutCounter, meter, metrics, s2sConnectionDuration, s2sErrorCounter, sessionCounter, toolCallCounter, toolCallDuration, toolCallErrorCounter, trace, tracer, turnCounter, turnStepsHistogram, withSpan, wsSendDroppedCounter };

package/dist/{testing-MRl3SXsI.js → testing-BbitshLb.js}

@@ -1,9 +1,7 @@
-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";
+import { n as createTestEmbedFn, t as createUnstorageVectorStore } from "./unstorage-vector-Cj5llNhg.js";
+import { t as createDirectExecutor } from "./direct-executor-B-5mq3cu.js";
+import { t as createUnstorageKv } from "./unstorage-kv-CDgP-frt.js";
+import { createStorage } from "unstorage";
 //#region _mock-ws.ts
 /**
 * A mock WebSocket implementation for testing.
@@ -472,8 +470,8 @@ var TestHarness = class {
 * 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"),
+	return createUnstorageVectorStore({
+		storage: createStorage(),
 		embedFn: createTestEmbedFn()
 	});
 }
@@ -507,7 +505,7 @@ function createTestVectorStore() {
 * @public
 */
 function createTestHarness(agent, options = {}) {
-	const { env = {}, kv = createSqliteKv({ path: ":memory:" }), vector = createTestVectorStore() } = options;
+	const { env = {}, kv = createUnstorageKv({ storage: createStorage() }), vector = createTestVectorStore() } = options;
 	return new TestHarness(createDirectExecutor({
 		agent,
 		env,

package/dist/testing.js

@@ -1,2 +1,2 @@
-import { a as installMockWebSocket, i as MockWebSocket, n as TurnResult, r as createTestHarness, t as TestHarness } from "./testing-MRl3SXsI.js";
+import { a as installMockWebSocket, i as MockWebSocket, n as TurnResult, r as createTestHarness, t as TestHarness } from "./testing-BbitshLb.js";
 export { MockWebSocket, TestHarness, TurnResult, createTestHarness, installMockWebSocket };

package/dist/types-D8ZBxTL_.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+//#region types.ts
+/**
+* Core type definitions for the AAI agent SDK.
+*/
+/**
+* Identity helper that preserves the Zod schema generic for type inference.
+*
+* When tools are defined inline in `defineAgent({ tools: { ... } })`, the
+* generic `P` gets widened to the base `ZodObject` type, so `args` in
+* `execute` loses its specific shape. Wrapping a tool definition in
+* `defineTool()` lets TypeScript infer `P` from `parameters` and type
+* `args` correctly.
+*
+* @example
+* ```ts
+* import { defineAgent, defineTool } from "aai";
+* import { z } from "zod";
+*
+* export default defineAgent({
+*   name: "my-agent",
+*   tools: {
+*     greet: defineTool({
+*       description: "Greet the user",
+*       parameters: z.object({ name: z.string() }),
+*       execute: ({ name }) => `Hello, ${name}!`, // name is string
+*     }),
+*   },
+* });
+* ```
+*
+* @public
+*/
+function defineTool(def) {
+	return def;
+}
+/**
+* Create a typed `defineTool` helper with the session state type baked in.
+*
+* When tools need access to typed session state, you'd normally have to write
+* verbose generics on every `defineTool` call. `createToolFactory` eliminates
+* that boilerplate by returning a `defineTool` variant that already knows `S`.
+*
+* @example
+* ```ts
+* import { createToolFactory, defineAgent } from "aai";
+* import { z } from "zod";
+*
+* interface PortfolioState { holdings: Map<string, number> }
+*
+* const tool = createToolFactory<PortfolioState>();
+*
+* export default defineAgent<PortfolioState>({
+*   name: "portfolio",
+*   state: () => ({ holdings: new Map() }),
+*   tools: {
+*     buy: tool({
+*       description: "Buy shares",
+*       parameters: z.object({ symbol: z.string(), qty: z.number() }),
+*       execute: (args, ctx) => {
+*         // args.symbol is string, ctx.state is PortfolioState
+*         ctx.state.holdings.set(args.symbol, args.qty);
+*       },
+*     }),
+*   },
+* });
+* ```
+*
+* @public
+*/
+function createToolFactory() {
+	return (def) => def;
+}
+/**
+* Default system prompt used when `instructions` is not provided.
+*
+* Optimized for voice-first interactions: short sentences, no visual
+* formatting, confident tone, and concise answers.
+*/
+const DEFAULT_INSTRUCTIONS = `\
+You are AAI, a helpful AI assistant.
+
+Voice-First Rules:
+- Optimize for natural speech. Avoid jargon unless central to the answer. \
+Use short, punchy sentences.
+- Never mention "search results," "sources," or "the provided text." \
+Speak as if the knowledge is your own.
+- No visual formatting. Do not say "bullet point," "bold," or "bracketed one." \
+If you need to list items, say "First," "Next," and "Finally."
+- Start with the most important information. No introductory filler.
+- Be concise. Keep answers to 1-3 sentences. For complex topics, provide a high-level summary.
+- Be confident. Avoid hedging phrases like "It seems that" or "I believe."
+- If you don't have enough information, say so directly rather than guessing.
+- Never use exclamation points. Keep your tone calm and conversational.`;
+/** Default greeting spoken when a session starts. */
+const DEFAULT_GREETING = "Hey there. I'm a voice assistant. What can I help you with?";
+/** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
+const BuiltinToolSchema = z.enum([
+	"web_search",
+	"visit_webpage",
+	"fetch_json",
+	"run_code",
+	"vector_search",
+	"memory"
+]);
+/** @internal Zod schema for {@link ToolChoice}. Exported for reuse in internal schemas. */
+const ToolChoiceSchema = z.union([z.enum([
+	"auto",
+	"required",
+	"none"
+]), z.object({
+	type: z.literal("tool"),
+	toolName: z.string().min(1)
+})]);
+const ToolDefSchema = z.object({
+	description: z.string().min(1, "Tool description must be non-empty"),
+	parameters: z.custom((val) => val === void 0 || val instanceof z.ZodType, "Expected a Zod schema").optional(),
+	execute: z.function()
+});
+/** Default TTL for persisted session data: 1 hour. */
+const DEFAULT_PERSIST_TTL = 36e5;
+const AgentOptionsSchema = z.object({
+	name: z.string().min(1, "Agent name must be non-empty"),
+	instructions: z.string().optional(),
+	greeting: z.string().optional(),
+	sttPrompt: z.string().optional(),
+	maxSteps: z.union([z.number().int().positive(), z.function()]).optional(),
+	toolChoice: ToolChoiceSchema.optional(),
+	builtinTools: z.array(BuiltinToolSchema).optional(),
+	tools: z.record(z.string(), ToolDefSchema).optional(),
+	state: z.function().optional(),
+	persistence: z.union([z.literal(true), z.object({ ttl: z.number().int().positive().optional() })]).optional(),
+	onConnect: z.function().optional(),
+	onDisconnect: z.function().optional(),
+	onError: z.function().optional(),
+	onTurn: z.function().optional(),
+	onStep: z.function().optional(),
+	middleware: z.array(z.object({
+		name: z.string().min(1, "Middleware name must be non-empty"),
+		beforeInput: z.function().optional(),
+		beforeTurn: z.function().optional(),
+		afterTurn: z.function().optional(),
+		beforeToolCall: z.function().optional(),
+		afterToolCall: z.function().optional(),
+		beforeOutput: z.function().optional()
+	})).optional(),
+	idleTimeoutMs: z.number().nonnegative().optional()
+});
+/**
+* Create an agent definition from the given options, applying sensible defaults.
+*
+* This is the main entry point for defining a voice agent. The returned
+* `AgentDef` is consumed by the AAI server at deploy time.
+*
+* @param options - Configuration for the agent including name, instructions,
+*   tools, hooks, and other settings.
+* @returns A fully resolved agent definition with all defaults applied.
+*
+* @public
+*
+* @example Basic agent with a custom tool
+* ```ts
+* import { defineAgent } from "aai";
+* import { z } from "zod";
+*
+* export default defineAgent({
+*   name: "greeter",
+*   instructions: "You greet people warmly.",
+*   tools: {
+*     greet: {
+*       description: "Greet a user by name",
+*       parameters: z.object({ name: z.string() }),
+*       execute: ({ name }) => `Hello, ${name}!`,
+*     },
+*   },
+* });
+* ```
+*/
+function defineAgent(options) {
+	AgentOptionsSchema.parse(options);
+	const persistence = options.persistence ? { ttl: typeof options.persistence === "object" ? options.persistence.ttl ?? DEFAULT_PERSIST_TTL : DEFAULT_PERSIST_TTL } : void 0;
+	return {
+		...options,
+		instructions: options.instructions ?? DEFAULT_INSTRUCTIONS,
+		greeting: options.greeting ?? "Hey there. I'm a voice assistant. What can I help you with?",
+		maxSteps: options.maxSteps ?? 5,
+		tools: options.tools ?? {},
+		persistence
+	};
+}
+//#endregion
+export { createToolFactory as a, ToolChoiceSchema as i, DEFAULT_GREETING as n, defineAgent as o, DEFAULT_INSTRUCTIONS as r, defineTool as s, BuiltinToolSchema as t };