@alexkroman1/aai 0.10.3 → 0.11.0

package/dist/direct-executor-DAGCZOAN.js

@@ -0,0 +1,1530 @@
+import { BuiltinToolSchema, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, defineTool } from "./types.js";
+import { a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_HTML_BYTES, f as MAX_PAGE_CHARS, g as TOOL_EXECUTION_TIMEOUT_MS, h as RUN_CODE_TIMEOUT_MS, l as HOOK_TIMEOUT_MS, m as MAX_VALUE_SIZE, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_TOOL_RESULT_CHARS, s as DEFAULT_TTS_SAMPLE_RATE } from "./constants-CwotjpJR.js";
+import { errorDetail, errorMessage, toolError } from "./_utils.js";
+import { callResolveTurnConfig, createAgentHooks } from "./hooks.js";
+import { ClientMessageSchema, buildReadyConfig } from "./protocol.js";
+import { matchGlob, sortAndPaginate } from "./kv.js";
+import { z } from "zod";
+import WsWebSocket from "ws";
+import pTimeout from "p-timeout";
+import { createStorage, prefixStorage } from "unstorage";
+import vm from "node:vm";
+import { createNanoEvents } from "nanoevents";
+//#region runtime.ts
+/**
+* Runtime dependencies injected into the session pipeline.
+*
+* Defines the {@link Logger} interface, a default {@link consoleLogger},
+* and the {@link S2SConfig} for Speech-to-Speech endpoint configuration.
+*/
+/** Default console-backed logger. */
+const consoleLogger = {
+	info: (msg, ctx) => ctx ? console.log(msg, ctx) : console.log(msg),
+	warn: (msg, ctx) => ctx ? console.warn(msg, ctx) : console.warn(msg),
+	error: (msg, ctx) => ctx ? console.error(msg, ctx) : console.error(msg),
+	debug: (msg, ctx) => ctx ? console.debug(msg, ctx) : console.debug(msg)
+};
+/**
+* Structured JSON logger for production diagnostics. Each log entry is a
+* single-line JSON object with `timestamp`, `level`, `msg`, and any
+* caller-provided context fields.
+*/
+function jsonLog(level) {
+	return (msg, ctx) => {
+		const entry = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			level,
+			msg
+		};
+		if (ctx) Object.assign(entry, ctx);
+		(level === "error" || level === "warn" ? process.stderr : process.stdout).write(`${JSON.stringify(entry)}\n`);
+	};
+}
+const jsonLogger = {
+	info: jsonLog("info"),
+	warn: jsonLog("warn"),
+	error: jsonLog("error"),
+	debug: jsonLog("debug")
+};
+/** Default S2S endpoint configuration. */
+const DEFAULT_S2S_CONFIG = {
+	wssUrl: "wss://speech-to-speech.us.assemblyai.com/v1/realtime",
+	inputSampleRate: DEFAULT_STT_SAMPLE_RATE,
+	outputSampleRate: DEFAULT_TTS_SAMPLE_RATE
+};
+//#endregion
+//#region _internal-types.ts
+/**
+* Zod schema for serializable agent configuration sent over the wire.
+*
+* This is the JSON-safe subset of the agent definition that can be
+* transmitted between the worker and the host process via structured clone.
+*/
+const AgentConfigSchema = z.object({
+	name: z.string().min(1),
+	instructions: z.string(),
+	greeting: z.string(),
+	sttPrompt: z.string().optional(),
+	maxSteps: z.number().int().positive().optional(),
+	toolChoice: ToolChoiceSchema.optional(),
+	builtinTools: z.array(BuiltinToolSchema).readonly().optional(),
+	idleTimeoutMs: z.number().nonnegative().optional()
+});
+/** Extract the serializable {@link AgentConfig} subset from a source object. */
+function toAgentConfig(src) {
+	const config = {
+		name: src.name,
+		instructions: src.instructions,
+		greeting: src.greeting
+	};
+	if (src.sttPrompt !== void 0) config.sttPrompt = src.sttPrompt;
+	if (typeof src.maxSteps !== "function" && src.maxSteps !== void 0) config.maxSteps = src.maxSteps;
+	if (src.toolChoice !== void 0) config.toolChoice = src.toolChoice;
+	if (src.builtinTools) config.builtinTools = [...src.builtinTools];
+	if (src.idleTimeoutMs !== void 0) config.idleTimeoutMs = src.idleTimeoutMs;
+	return config;
+}
+/**
+* Zod schema for serialized tool definitions sent over the wire.
+*
+* `parameters` must be a valid JSON Schema object (with `type`, `properties`,
+* etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
+*/
+const ToolSchemaSchema = z.object({
+	name: z.string().min(1),
+	description: z.string().min(1),
+	parameters: z.record(z.string(), z.unknown())
+});
+/** Empty Zod object schema used as default when tools have no parameters. */
+const EMPTY_PARAMS = z.object({});
+/**
+* Convert agent tool definitions to JSON Schema format for wire transport.
+*
+* Transforms the Zod-based `parameters` of each tool into a plain JSON Schema
+* object suitable for structured clone / JSON serialization.
+*/
+function agentToolsToSchemas(tools) {
+	return Object.entries(tools).map(([name, def]) => ({
+		name,
+		description: def.description,
+		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
+	}));
+}
+//#endregion
+//#region _run-code.ts
+/**
+* run_code built-in tool — executes user JavaScript in a fresh `node:vm`
+* context with no network, filesystem, or process access.
+*/
+const runCodeParams = z.object({ code: z.string().describe("JavaScript code to execute. Use console.log() for output.") });
+/**
+* Execute JavaScript code inside a fresh `node:vm` context.
+*
+* Each invocation creates a disposable VM context with:
+* - No filesystem access (`node:fs` and other built-ins unavailable)
+* - No network access (`fetch`, `http` unavailable)
+* - No child process spawning
+* - No environment variable access (`process` unavailable)
+* - Execution timeout (default 5 s)
+*
+* The context is discarded after execution, so no state leaks between
+* invocations or across sessions.
+*/
+function createRunCode() {
+	return {
+		description: "Execute JavaScript code in a sandbox and return the output. Use this for calculations, data transformations, string manipulation, or any task that benefits from running code. Output is captured from console.log(). No network or filesystem access.",
+		parameters: runCodeParams,
+		async execute(args) {
+			return executeInIsolate(args.code);
+		}
+	};
+}
+/**
+* Execute user code in a fresh `node:vm` context.
+*
+* @remarks
+* The VM context only exposes standard ECMAScript globals and a console
+* object that captures output. Node.js APIs (`process`, `require`,
+* `import()`) are not available inside the sandbox.
+*/
+async function executeInIsolate(code) {
+	const output = [];
+	const capture = (...args) => output.push(args.map(String).join(" "));
+	const context = vm.createContext({
+		console: {
+			log: capture,
+			info: capture,
+			warn: capture,
+			error: capture,
+			debug: capture
+		},
+		setTimeout,
+		clearTimeout,
+		setInterval,
+		clearInterval,
+		URL,
+		URLSearchParams,
+		TextEncoder,
+		TextDecoder,
+		atob,
+		btoa,
+		structuredClone,
+		queueMicrotask
+	});
+	try {
+		const wrapped = `(async () => {\n${code}\n})()`;
+		const promise = new vm.Script(wrapped, { filename: "run_code.js" }).runInContext(context, { timeout: RUN_CODE_TIMEOUT_MS });
+		await Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("Code execution timed out")), RUN_CODE_TIMEOUT_MS))]);
+		return output.join("\n").trim() || "Code ran successfully (no output)";
+	} catch (err) {
+		return { error: errorMessage(err) };
+	}
+}
+//#endregion
+//#region memory-tools.ts
+/**
+* KV-backed memory tools for agent persistent state.
+*/
+/**
+* Returns a standard set of KV-backed memory tools: `save_memory`,
+* `recall_memory`, `list_memories`, and `forget_memory`.
+*
+* Spread the result into your agent's `tools` record.
+*
+* @example
+* ```ts
+* import { defineAgent, memoryTools } from "aai";
+*
+* export default defineAgent({
+*   name: "My Agent",
+*   tools: { ...memoryTools() },
+* });
+* ```
+*
+* @returns A record with four tool definitions: `save_memory`, `recall_memory`,
+*   `list_memories`, and `forget_memory`.
+* @public
+*/
+function memoryTools() {
+	return {
+		save_memory: defineTool({
+			description: "Save a piece of information to persistent memory. Use a descriptive key like 'user:name' or 'project:status'.",
+			parameters: z.object({
+				key: z.string().describe("A descriptive key for this memory (e.g. 'user:name', 'preference:color')"),
+				value: z.string().describe("The information to remember")
+			}),
+			execute: async ({ key, value }, ctx) => {
+				await ctx.kv.set(key, value);
+				return { saved: key };
+			}
+		}),
+		recall_memory: defineTool({
+			description: "Retrieve a previously saved memory by its key.",
+			parameters: z.object({ key: z.string().describe("The key to look up") }),
+			execute: async ({ key }, ctx) => {
+				const value = await ctx.kv.get(key);
+				if (value === null) return {
+					found: false,
+					key
+				};
+				return {
+					found: true,
+					key,
+					value
+				};
+			}
+		}),
+		list_memories: defineTool({
+			description: "List all saved memory keys, optionally filtered by a prefix (e.g. 'user:').",
+			parameters: z.object({ prefix: z.string().describe("Prefix to filter keys (e.g. 'user:'). Use empty string for all.").optional() }),
+			execute: async ({ prefix }, ctx) => {
+				const entries = await ctx.kv.list(prefix ?? "");
+				return {
+					count: entries.length,
+					keys: entries.map((e) => e.key)
+				};
+			}
+		}),
+		forget_memory: defineTool({
+			description: "Delete a previously saved memory by its key.",
+			parameters: z.object({ key: z.string().describe("The key to delete") }),
+			execute: async ({ key }, ctx) => {
+				await ctx.kv.delete(key);
+				return { deleted: key };
+			}
+		})
+	};
+}
+//#endregion
+//#region builtin-tools.ts
+/**
+* Built-in tool definitions for the AAI agent SDK.
+*
+* In self-hosted mode, these run in-process alongside custom tools.
+* In platform mode, they run on the host process outside the sandbox.
+* Network requests go through the host's fetch proxy (with SSRF protection).
+*/
+const fetchSignal = () => AbortSignal.timeout(FETCH_TIMEOUT_MS);
+/** Strip HTML tags and decode common entities. */
+function htmlToText(html) {
+	return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").replace(/\s{2,}/g, " ").trim();
+}
+const webSearchParams = z.object({
+	query: z.string().describe("The search query"),
+	max_results: z.number().describe("Maximum number of results to return (default 5)").optional()
+});
+const BRAVE_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search";
+const BraveSearchResponseSchema = z.object({ web: z.object({ results: z.array(z.object({
+	title: z.string(),
+	url: z.string(),
+	description: z.string()
+})) }).optional() });
+function createWebSearch(fetchFn = globalThis.fetch) {
+	return {
+		description: "Search the web for current information, facts, news, or answers to questions. Returns a list of results with title, URL, and description. Use this when the user asks about something you don't know, need up-to-date information, or want to verify facts.",
+		parameters: webSearchParams,
+		async execute(args, ctx) {
+			const { query, max_results: maxResults = 5 } = args;
+			const apiKey = ctx.env.BRAVE_API_KEY ?? "";
+			if (!apiKey) return { error: "BRAVE_API_KEY is not set — web search unavailable" };
+			const resp = await fetchFn(`${BRAVE_SEARCH_URL}?${new URLSearchParams({
+				q: query,
+				count: String(maxResults),
+				text_decorations: "false"
+			})}`, {
+				headers: { "X-Subscription-Token": apiKey },
+				signal: fetchSignal()
+			});
+			if (!resp.ok) return { error: `Search request failed: ${resp.status} ${resp.statusText}` };
+			const raw = await resp.json();
+			const data = BraveSearchResponseSchema.safeParse(raw);
+			if (!data.success) return { error: "Unexpected search response format" };
+			return (data.data.web?.results ?? []).slice(0, maxResults).map((r) => ({
+				title: r.title,
+				url: r.url,
+				description: r.description
+			}));
+		}
+	};
+}
+const visitWebpageParams = z.object({ url: z.string().describe("The full URL to fetch (e.g., 'https://example.com/page')") });
+function createVisitWebpage(fetchFn = globalThis.fetch) {
+	return {
+		description: "Fetch a webpage and return its content as clean text. Use this to read the full content of a URL found via web_search, or any link the user shares. Good for reading articles, documentation, blog posts, or product pages.",
+		parameters: visitWebpageParams,
+		async execute(args, _ctx) {
+			const { url } = args;
+			const resp = await fetchFn(url, {
+				headers: {
+					"User-Agent": "Mozilla/5.0 (compatible; VoiceAgent/1.0; +https://github.com/AssemblyAI/aai)",
+					Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
+				},
+				signal: fetchSignal()
+			});
+			if (!resp.ok) return {
+				error: `Failed to fetch: ${resp.status} ${resp.statusText}`,
+				url
+			};
+			const htmlContent = await resp.text();
+			const text = htmlToText(htmlContent.length > 2e5 ? htmlContent.slice(0, MAX_HTML_BYTES) : htmlContent);
+			const truncated = text.length > MAX_PAGE_CHARS;
+			return {
+				url,
+				content: truncated ? text.slice(0, MAX_PAGE_CHARS) : text,
+				...truncated ? {
+					truncated: true,
+					totalChars: text.length
+				} : {}
+			};
+		}
+	};
+}
+const fetchJsonParams = z.object({
+	url: z.string().describe("The URL to fetch JSON from"),
+	headers: z.record(z.string(), z.string()).describe("Optional HTTP headers to include in the request (only safe headers like Accept, Content-Type are allowed)").optional()
+});
+/** Headers the LLM must never control — could exfiltrate credentials or manipulate routing. */
+const BLOCKED_FETCH_HEADERS = new Set([
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"host",
+	"proxy-authorization",
+	"x-forwarded-for",
+	"x-forwarded-host",
+	"x-forwarded-proto",
+	"x-real-ip",
+	"cf-connecting-ip",
+	"fly-client-ip"
+]);
+function sanitizeHeaders(raw) {
+	if (!raw) return;
+	const safe = {};
+	for (const [key, value] of Object.entries(raw)) if (!BLOCKED_FETCH_HEADERS.has(key.toLowerCase())) safe[key] = value;
+	return Object.keys(safe).length > 0 ? safe : void 0;
+}
+function createFetchJson(fetchFn = globalThis.fetch) {
+	return {
+		description: "Call a REST API endpoint via HTTP GET and return the JSON response. Use this to fetch structured data from APIs — for example, weather data, stock prices, exchange rates, or any public JSON API. Supports custom headers for authenticated APIs.",
+		parameters: fetchJsonParams,
+		async execute(args, _ctx) {
+			const { url, headers } = args;
+			const safeHeaders = sanitizeHeaders(headers);
+			const resp = await fetchFn(url, {
+				...safeHeaders && { headers: safeHeaders },
+				signal: fetchSignal()
+			});
+			if (!resp.ok) return {
+				error: `HTTP ${resp.status} ${resp.statusText}`,
+				url
+			};
+			try {
+				return await resp.json();
+			} catch {
+				return {
+					error: "Response was not valid JSON",
+					url
+				};
+			}
+		}
+	};
+}
+/** Resolve a builtin name to an array of [toolName, ToolDef] pairs. */
+function resolveBuiltin(name, opts) {
+	switch (name) {
+		case "web_search": return [["web_search", createWebSearch(opts?.fetch)]];
+		case "visit_webpage": return [["visit_webpage", createVisitWebpage(opts?.fetch)]];
+		case "fetch_json": return [["fetch_json", createFetchJson(opts?.fetch)]];
+		case "run_code": return [["run_code", createRunCode()]];
+		case "memory": return Object.entries(memoryTools());
+		default: return [];
+	}
+}
+/**
+* Create built-in tool definitions for the given tool names.
+* For runtime use.
+*/
+function getBuiltinToolDefs(names, opts) {
+	const defs = {};
+	for (const name of names) for (const [k, v] of resolveBuiltin(name, opts)) defs[k] = v;
+	return defs;
+}
+/** Returns JSON tool schemas for the specified builtin tools. */
+function getBuiltinToolSchemas(names) {
+	return names.flatMap((name) => resolveBuiltin(name).map(([toolName, def]) => ({
+		name: toolName,
+		description: def.description,
+		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
+	})));
+}
+//#endregion
+//#region s2s.ts
+const uint8ToBase64 = (bytes) => Buffer.from(bytes).toString("base64");
+const base64ToUint8 = (base64) => new Uint8Array(Buffer.from(base64, "base64"));
+const WS_OPEN = 1;
+const defaultCreateS2sWebSocket = (url, opts) => new WsWebSocket(url, { headers: opts.headers });
+function hasStringFields(obj, ...keys) {
+	for (const k of keys) if (typeof obj[k] !== "string") return false;
+	return true;
+}
+function parseAgentTranscript(obj) {
+	if (typeof obj.text !== "string") return;
+	return {
+		type: "transcript.agent",
+		text: obj.text,
+		reply_id: typeof obj.reply_id === "string" ? obj.reply_id : "",
+		item_id: typeof obj.item_id === "string" ? obj.item_id : "",
+		interrupted: obj.interrupted === true
+	};
+}
+function parseToolCall(obj) {
+	if (typeof obj.call_id !== "string" || typeof obj.name !== "string") return;
+	const args = obj.args != null && typeof obj.args === "object" && !Array.isArray(obj.args) ? obj.args : {};
+	return {
+		type: "tool.call",
+		call_id: obj.call_id,
+		name: obj.name,
+		args
+	};
+}
+function passthrough(obj) {
+	return obj;
+}
+function requireFields(...keys) {
+	return (obj) => hasStringFields(obj, ...keys) ? obj : void 0;
+}
+const MESSAGE_VALIDATORS = new Map([
+	["session.ready", requireFields("session_id")],
+	["session.updated", passthrough],
+	["input.speech.started", passthrough],
+	["input.speech.stopped", passthrough],
+	["reply.content_part.started", passthrough],
+	["reply.content_part.done", passthrough],
+	["transcript.user.delta", requireFields("text")],
+	["transcript.user", requireFields("item_id", "text")],
+	["reply.started", requireFields("reply_id")],
+	["transcript.agent.delta", requireFields("delta")],
+	["transcript.agent", parseAgentTranscript],
+	["tool.call", parseToolCall],
+	["reply.done", (obj) => ({
+		type: "reply.done",
+		...typeof obj.status === "string" ? { status: obj.status } : {}
+	})],
+	["session.error", requireFields("code", "message")],
+	["error", requireFields("message")]
+]);
+function parseS2sMessage(obj) {
+	const type = obj.type;
+	if (typeof type !== "string") return;
+	return MESSAGE_VALIDATORS.get(type)?.(obj);
+}
+function dispatchS2sMessage(emitter, msg) {
+	switch (msg.type) {
+		case "session.ready":
+			emitter.emit("ready", { sessionId: msg.session_id });
+			break;
+		case "session.updated":
+			emitter.emit("sessionUpdated", msg);
+			break;
+		case "input.speech.started":
+			emitter.emit("speechStarted");
+			break;
+		case "input.speech.stopped":
+			emitter.emit("speechStopped");
+			break;
+		case "transcript.user.delta":
+			emitter.emit("userTranscriptDelta", { text: msg.text });
+			break;
+		case "transcript.user":
+			emitter.emit("userTranscript", {
+				itemId: msg.item_id,
+				text: msg.text
+			});
+			break;
+		case "reply.started":
+			emitter.emit("replyStarted", { replyId: msg.reply_id });
+			break;
+		case "transcript.agent.delta":
+			emitter.emit("agentTranscriptDelta", { text: msg.delta });
+			break;
+		case "transcript.agent":
+			emitter.emit("agentTranscript", {
+				text: msg.text,
+				replyId: msg.reply_id,
+				itemId: msg.item_id,
+				interrupted: msg.interrupted
+			});
+			break;
+		case "tool.call":
+			emitter.emit("toolCall", {
+				callId: msg.call_id,
+				name: msg.name,
+				args: msg.args
+			});
+			break;
+		case "reply.done":
+			emitter.emit("replyDone", msg.status ? { status: msg.status } : {});
+			break;
+		case "session.error":
+			if (msg.code === "session_not_found" || msg.code === "session_forbidden") emitter.emit("sessionExpired", {
+				code: msg.code,
+				message: msg.message
+			});
+			else emitter.emit("error", {
+				code: msg.code,
+				message: msg.message
+			});
+			break;
+		case "error":
+			emitter.emit("error", {
+				code: "connection",
+				message: msg.message
+			});
+			break;
+		case "reply.content_part.started":
+		case "reply.content_part.done": break;
+		default: break;
+	}
+}
+function connectS2s(opts) {
+	const { apiKey, config, createWebSocket, logger: log = consoleLogger } = opts;
+	return new Promise((resolve, reject) => {
+		log.info("S2S connecting", { url: config.wssUrl });
+		const ws = createWebSocket(config.wssUrl, { headers: { Authorization: `Bearer ${apiKey}` } });
+		const emitter = createNanoEvents();
+		let opened = false;
+		function send(msg) {
+			if (ws.readyState !== WS_OPEN) {
+				log.debug("S2S send dropped: socket not open", { type: msg.type });
+				return;
+			}
+			const json = JSON.stringify(msg);
+			if (msg.type !== "input.audio") log.info(`S2S >> ${msg.type}`, msg.type === "session.update" ? { payload: json } : void 0);
+			ws.send(json);
+		}
+		const handle = {
+			on: emitter.on.bind(emitter),
+			sendAudio(audio) {
+				if (ws.readyState !== WS_OPEN) {
+					log.debug("S2S sendAudio dropped: socket not open");
+					return;
+				}
+				ws.send(`{"type":"input.audio","audio":"${uint8ToBase64(audio)}"}`);
+			},
+			sendToolResult(callId, result) {
+				const msg = {
+					type: "tool.result",
+					call_id: callId,
+					result
+				};
+				log.info("S2S >> tool.result", {
+					call_id: callId,
+					resultLength: result.length
+				});
+				send(msg);
+			},
+			updateSession(sessionConfig) {
+				const { systemPrompt, ...rest } = sessionConfig;
+				send({
+					type: "session.update",
+					session: {
+						system_prompt: systemPrompt,
+						...rest
+					}
+				});
+			},
+			resumeSession(sessionId) {
+				send({
+					type: "session.resume",
+					session_id: sessionId
+				});
+			},
+			close() {
+				log.info("S2S closing");
+				ws.close();
+			}
+		};
+		ws.addEventListener("open", () => {
+			opened = true;
+			log.info("S2S WebSocket open");
+			resolve(handle);
+		});
+		function tryParseJson(data) {
+			try {
+				return JSON.parse(String(data));
+			} catch {
+				log.warn("S2S << invalid JSON", { data: String(data).slice(0, 200) });
+			}
+		}
+		function handleAudioFastPath(obj) {
+			if (obj.type === "reply.audio" && typeof obj.data === "string") {
+				const audioBytes = base64ToUint8(obj.data);
+				emitter.emit("audio", { audio: audioBytes });
+				return true;
+			}
+			return false;
+		}
+		function logIncoming(obj) {
+			if (obj.type === "reply.audio" || obj.type === "input.audio") return;
+			log.info(`S2S << ${obj.type}`, obj.type === "transcript.agent.delta" ? { delta: obj.delta } : void 0);
+		}
+		function handleS2sMessage(ev) {
+			const raw = tryParseJson(ev.data);
+			if (raw === void 0) return;
+			if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+				log.warn("S2S << non-object JSON message", { type: typeof raw });
+				return;
+			}
+			const obj = raw;
+			logIncoming(obj);
+			if (handleAudioFastPath(obj)) return;
+			const parsed = parseS2sMessage(obj);
+			if (!parsed) {
+				log.warn(`S2S << unrecognised message type: ${obj.type ?? JSON.stringify(raw).slice(0, 200)}`);
+				return;
+			}
+			dispatchS2sMessage(emitter, parsed);
+		}
+		ws.addEventListener("message", handleS2sMessage);
+		ws.addEventListener("close", (ev) => {
+			log.info("S2S WebSocket closed", {
+				code: ev.code ?? 0,
+				reason: ev.reason ?? ""
+			});
+			if (!opened) reject(/* @__PURE__ */ new Error(`WebSocket closed before open (code: ${ev.code ?? 0})`));
+			emitter.emit("close");
+		});
+		ws.addEventListener("error", (ev) => {
+			const message = typeof ev.message === "string" ? ev.message : "WebSocket error";
+			const errObj = new Error(message);
+			log.error("S2S WebSocket error", { error: errObj.message });
+			if (!opened) reject(errObj);
+			else emitter.emit("error", {
+				code: "ws_error",
+				message: errObj.message
+			});
+		});
+	});
+}
+//#endregion
+//#region system-prompt.ts
+function getFormattedDate() {
+	return (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
+		weekday: "long",
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	});
+}
+const VOICE_RULES = "\n\nCRITICAL OUTPUT RULES — you MUST follow these for EVERY response:\nYour response will be spoken aloud by a TTS system and displayed as plain text.\n- NEVER use markdown: no **, no *, no _, no #, no `, no [](), no ---\n- NEVER use bullet points (-, *, •) or numbered lists (1., 2.)\n- NEVER use code blocks or inline code\n- NEVER mention tools, search, APIs, or technical failures to the user. If a tool returns no results, just answer naturally without explaining why.\n- Write exactly as you would say it out loud to a friend\n- Use short conversational sentences. To list things, say \"First,\" \"Next,\" \"Finally,\"\n- Keep responses concise — 1 to 3 sentences max";
+/**
+* Build the system prompt sent to the LLM from the agent configuration.
+*
+* Assembles the default instructions, today's date, agent-specific instructions,
+* and optional sections for tool usage preamble and voice output rules.
+*
+* @param config - The serializable agent configuration (name, instructions, etc.).
+* @param opts.hasTools - When `true`, appends a preamble instructing the LLM to
+*   speak a brief phrase before each tool call to fill silence.
+* @param opts.voice - When `true`, appends strict voice-specific output rules
+*   (no markdown, no bullet points, conversational tone, concise responses).
+* @returns The assembled system prompt string.
+*/
+function buildSystemPrompt(config, opts) {
+	const { hasTools } = opts;
+	const agentInstructions = config.instructions && config.instructions !== DEFAULT_INSTRUCTIONS ? `\n\nAgent-Specific Instructions:\n${config.instructions}` : "";
+	const toolPreamble = hasTools ? "\n\nWhen you decide to use a tool, ALWAYS say a brief natural phrase BEFORE the tool call (e.g. \"Let me look that up\" or \"One moment while I check\"). This fills silence while the tool executes. Keep preambles to one short sentence." : "";
+	return DEFAULT_INSTRUCTIONS + `\n\nToday's date is ${getFormattedDate()}.` + agentInstructions + toolPreamble + (opts.voice ? VOICE_RULES : "");
+}
+//#endregion
+//#region session.ts
+function buildCtx(opts) {
+	const { id, agentConfig, hooks, log } = opts;
+	const maxHistory = opts.maxHistory ?? 200;
+	/** Track in-flight hook promises so they can be awaited during shutdown. */
+	const pendingHooks = /* @__PURE__ */ new Set();
+	const ctx = {
+		...opts,
+		s2s: null,
+		reply: {
+			pendingTools: [],
+			toolCallCount: 0,
+			currentReplyId: null
+		},
+		turnPromise: null,
+		conversationMessages: [],
+		maxHistory,
+		resolveTurnConfig() {
+			return callResolveTurnConfig(hooks, id, HOOK_TIMEOUT_MS);
+		},
+		consumeToolCallStep(turnConfig, _name, replyId) {
+			if (replyId === null || replyId !== ctx.reply.currentReplyId) return toolError("Reply was interrupted. Discarding stale tool call.");
+			const maxSteps = turnConfig?.maxSteps ?? agentConfig.maxSteps;
+			ctx.reply.toolCallCount++;
+			if (maxSteps !== void 0 && ctx.reply.toolCallCount > maxSteps) {
+				log.info("maxSteps exceeded, refusing tool call", {
+					toolCallCount: ctx.reply.toolCallCount,
+					maxSteps
+				});
+				return toolError("Maximum tool steps reached. Please respond to the user now.");
+			}
+			return null;
+		},
+		fireHook(name, ...args) {
+			if (!hooks) return;
+			const notifyOnError = (err) => {
+				log.warn(`${name} hook failed`, { err: errorMessage(err) });
+				if (name !== "error") {
+					const ep = hooks.callHook("error", id, { message: errorMessage(err) });
+					if (ep && typeof ep.catch === "function") ep.catch((e) => {
+						log.warn("error hook failed", { err: errorMessage(e) });
+					});
+				}
+			};
+			try {
+				const result = hooks.callHook(name, ...args);
+				if (result == null) return;
+				const p = result.catch(notifyOnError).finally(() => pendingHooks.delete(p));
+				pendingHooks.add(p);
+			} catch (err) {
+				notifyOnError(err);
+			}
+		},
+		async drainHooks() {
+			if (pendingHooks.size > 0) await Promise.all([...pendingHooks]);
+		},
+		pushMessages(...msgs) {
+			ctx.conversationMessages.push(...msgs);
+			if (maxHistory > 0 && ctx.conversationMessages.length > maxHistory) ctx.conversationMessages = ctx.conversationMessages.slice(-maxHistory);
+		},
+		beginReply(replyId) {
+			ctx.reply = {
+				pendingTools: [],
+				toolCallCount: 0,
+				currentReplyId: replyId
+			};
+			ctx.turnPromise = null;
+		},
+		cancelReply() {
+			ctx.reply = {
+				pendingTools: [],
+				toolCallCount: 0,
+				currentReplyId: null
+			};
+		},
+		chainTurn(p) {
+			ctx.turnPromise = (ctx.turnPromise ?? Promise.resolve()).then(() => p);
+		}
+	};
+	return ctx;
+}
+/** @internal Not part of the public API. Exposed for testing only. */
+const _internals = { connectS2s };
+function createIdleTimer(opts) {
+	if (opts.timeoutMs <= 0) return {
+		reset() {},
+		clear() {}
+	};
+	let timer = null;
+	return {
+		reset() {
+			if (timer !== null) clearTimeout(timer);
+			timer = setTimeout(() => {
+				opts.log.info("S2S idle timeout", {
+					timeoutMs: opts.timeoutMs,
+					agent: opts.agent
+				});
+				opts.client.event({ type: "idle_timeout" });
+				opts.ctx.s2s?.close();
+			}, opts.timeoutMs);
+		},
+		clear() {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		}
+	};
+}
+/**
+* Complete a tool call by truncating the result, emitting a `tool_call_done` event,
+* and accumulating the result in `ctx.reply.pendingTools` — but only if the reply that
+* initiated this call is still active.
+*/
+function finishToolCall(ctx, callId, result, replyId) {
+	const truncatedResult = result.length > 4e3 ? result.slice(0, MAX_TOOL_RESULT_CHARS) : result;
+	ctx.client.event({
+		type: "tool_call_done",
+		toolCallId: callId,
+		result: truncatedResult
+	});
+	if (replyId !== null && replyId === ctx.reply.currentReplyId) {
+		ctx.reply.pendingTools.push({
+			callId,
+			result
+		});
+		if (ctx.maxHistory > 0 && ctx.reply.pendingTools.length > ctx.maxHistory) ctx.reply.pendingTools.shift();
+	}
+}
+async function handleToolCall(ctx, detail) {
+	const { callId, name, args: parsedArgs } = detail;
+	const replyId = ctx.reply.currentReplyId;
+	ctx.client.event({
+		type: "tool_call_start",
+		toolCallId: callId,
+		toolName: name,
+		args: parsedArgs
+	});
+	let turnConfig;
+	try {
+		turnConfig = await ctx.resolveTurnConfig();
+	} catch (err) {
+		const msg = `resolveTurnConfig hook error: ${errorMessage(err)}`;
+		ctx.log.error(msg);
+		finishToolCall(ctx, callId, toolError(msg), replyId);
+		return;
+	}
+	const refused = ctx.consumeToolCallStep(turnConfig, name, replyId);
+	if (refused !== null) {
+		finishToolCall(ctx, callId, refused, replyId);
+		return;
+	}
+	ctx.log.info("S2S tool call", {
+		tool: name,
+		callId,
+		args: parsedArgs,
+		agent: ctx.agent
+	});
+	let result;
+	try {
+		result = await ctx.executeTool(name, parsedArgs, ctx.id, ctx.conversationMessages);
+	} catch (err) {
+		const msg = errorMessage(err);
+		ctx.log.error("Tool execution failed", {
+			tool: name,
+			error: errorDetail(err)
+		});
+		result = toolError(msg);
+	}
+	ctx.log.info("S2S tool result", {
+		tool: name,
+		callId,
+		resultLength: result.length
+	});
+	finishToolCall(ctx, callId, result, replyId);
+}
+function handleUserTranscript(ctx, text) {
+	ctx.log.info("S2S user transcript", { text });
+	ctx.client.event({
+		type: "transcript",
+		text,
+		isFinal: true
+	});
+	ctx.client.event({
+		type: "turn",
+		text
+	});
+	ctx.pushMessages({
+		role: "user",
+		content: text
+	});
+	ctx.fireHook("turn", ctx.id, text, HOOK_TIMEOUT_MS);
+}
+function handleAgentTranscript(ctx, text, interrupted) {
+	ctx.client.event({
+		type: "chat",
+		text
+	});
+	if (!interrupted) ctx.pushMessages({
+		role: "assistant",
+		content: text
+	});
+}
+function handleReplyDone(ctx, status) {
+	if (status === "interrupted") {
+		ctx.log.info("S2S reply interrupted (barge-in)");
+		ctx.cancelReply();
+		ctx.client.event({ type: "cancelled" });
+		return;
+	}
+	const doneReplyId = ctx.reply.currentReplyId;
+	const sendPending = () => {
+		if (ctx.reply.currentReplyId !== doneReplyId) {
+			ctx.reply.pendingTools = [];
+			return;
+		}
+		if (ctx.reply.pendingTools.length > 0) {
+			for (const tool of ctx.reply.pendingTools) ctx.s2s?.sendToolResult(tool.callId, tool.result);
+			ctx.reply.pendingTools = [];
+		} else {
+			const stepsUsed = ctx.reply.toolCallCount;
+			if (stepsUsed > 0) ctx.log.info("Turn complete", {
+				steps: stepsUsed,
+				agent: ctx.agent
+			});
+			ctx.client.playAudioDone();
+			ctx.client.event({ type: "tts_done" });
+		}
+	};
+	if (ctx.turnPromise !== null) ctx.turnPromise.then(sendPending);
+	else sendPending();
+}
+function setupListeners(ctx, handle) {
+	handle.on("ready", ({ sessionId }) => ctx.log.info("S2S session ready", { sessionId }));
+	handle.on("sessionExpired", () => {
+		ctx.log.info("S2S session expired");
+		handle.close();
+	});
+	handle.on("speechStarted", () => ctx.client.event({ type: "speech_started" }));
+	handle.on("speechStopped", () => ctx.client.event({ type: "speech_stopped" }));
+	handle.on("userTranscriptDelta", ({ text }) => ctx.client.event({
+		type: "transcript",
+		text,
+		isFinal: false
+	}));
+	handle.on("userTranscript", ({ text }) => handleUserTranscript(ctx, text));
+	handle.on("replyStarted", ({ replyId }) => {
+		ctx.beginReply(replyId);
+	});
+	handle.on("audio", ({ audio }) => ctx.client.playAudioChunk(audio));
+	handle.on("agentTranscriptDelta", ({ text }) => ctx.client.event({
+		type: "chat_delta",
+		text
+	}));
+	handle.on("agentTranscript", ({ text, interrupted }) => handleAgentTranscript(ctx, text, interrupted));
+	handle.on("toolCall", (detail) => {
+		const p = handleToolCall(ctx, detail).catch((err) => {
+			ctx.log.error("Tool call handler failed", { err: errorMessage(err) });
+		});
+		ctx.chainTurn(p);
+	});
+	handle.on("replyDone", ({ status }) => handleReplyDone(ctx, status));
+	handle.on("error", ({ code, message }) => {
+		ctx.log.error("S2S error", {
+			code,
+			message
+		});
+		ctx.client.event({
+			type: "error",
+			code: "internal",
+			message
+		});
+		handle.close();
+	});
+	handle.on("close", () => {
+		ctx.log.info("S2S closed");
+		ctx.s2s = null;
+		ctx.cancelReply();
+	});
+}
+function createS2sSession(opts) {
+	const { id, agent, client, toolSchemas, apiKey, s2sConfig, executeTool, createWebSocket = defaultCreateS2sWebSocket, hooks, logger: log = consoleLogger } = opts;
+	const agentConfig = opts.skipGreeting ? {
+		...opts.agentConfig,
+		greeting: ""
+	} : opts.agentConfig;
+	const systemPrompt = buildSystemPrompt(agentConfig, {
+		hasTools: toolSchemas.length > 0 || (agentConfig.builtinTools?.length ?? 0) > 0,
+		voice: true
+	});
+	const s2sTools = toolSchemas.map((ts) => ({
+		type: "function",
+		name: ts.name,
+		description: ts.description,
+		parameters: ts.parameters
+	}));
+	const sessionAbort = new AbortController();
+	const ctx = buildCtx({
+		id,
+		agent,
+		client,
+		agentConfig,
+		executeTool,
+		hooks,
+		log,
+		maxHistory: opts.maxHistory
+	});
+	const rawTimeout = agentConfig.idleTimeoutMs ?? 3e5;
+	const idle = createIdleTimer({
+		timeoutMs: rawTimeout === 0 || !Number.isFinite(rawTimeout) ? 0 : rawTimeout,
+		agent,
+		log,
+		client,
+		ctx
+	});
+	let connectGeneration = 0;
+	const sessionUpdatePayload = {
+		systemPrompt,
+		tools: s2sTools,
+		...agentConfig.greeting ? { greeting: agentConfig.greeting } : {}
+	};
+	async function connectAndSetup() {
+		const generation = ++connectGeneration;
+		try {
+			const handle = await _internals.connectS2s({
+				apiKey,
+				config: s2sConfig,
+				createWebSocket,
+				logger: log
+			});
+			if (sessionAbort.signal.aborted || generation !== connectGeneration) {
+				handle.close();
+				return;
+			}
+			setupListeners(ctx, handle);
+			handle.updateSession(sessionUpdatePayload);
+			ctx.s2s = handle;
+			idle.reset();
+		} catch (err) {
+			const msg = errorMessage(err);
+			log.error("S2S connect failed", { error: errorDetail(err) });
+			client.event({
+				type: "error",
+				code: "internal",
+				message: msg
+			});
+		}
+	}
+	return {
+		async start() {
+			ctx.fireHook("connect", id, HOOK_TIMEOUT_MS);
+			await connectAndSetup();
+		},
+		async stop() {
+			if (sessionAbort.signal.aborted) return;
+			sessionAbort.abort();
+			idle.clear();
+			if (ctx.turnPromise !== null) await ctx.turnPromise;
+			await ctx.drainHooks();
+			ctx.s2s?.close();
+			ctx.fireHook("disconnect", id, HOOK_TIMEOUT_MS);
+			await ctx.drainHooks();
+		},
+		onAudio(data) {
+			idle.reset();
+			ctx.s2s?.sendAudio(data);
+		},
+		onAudioReady() {},
+		onCancel() {
+			client.event({ type: "cancelled" });
+		},
+		onReset() {
+			ctx.cancelReply();
+			ctx.conversationMessages = [];
+			ctx.reply.toolCallCount = 0;
+			ctx.turnPromise = null;
+			idle.clear();
+			ctx.s2s?.close();
+			client.event({ type: "reset" });
+			connectAndSetup().catch((err) => log.error("S2S reset reconnect failed", { error: errorMessage(err) }));
+		},
+		onHistory(incoming) {
+			ctx.pushMessages(...incoming.map((m) => ({
+				role: m.role,
+				content: m.content
+			})));
+		},
+		waitForTurn() {
+			return ctx.turnPromise ?? Promise.resolve();
+		}
+	};
+}
+//#endregion
+//#region unstorage-kv.ts
+/**
+* Key-value store backed by unstorage.
+*
+* Works with any unstorage driver (memory, fs, S3/R2, etc.).
+*/
+/**
+* Create a KV store backed by any unstorage driver.
+*
+* @param options - See {@link UnstorageKvOptions}.
+* @returns A {@link Kv} instance.
+*
+* @example
+* ```ts
+* import { createStorage } from "unstorage";
+* import { createUnstorageKv } from "@alexkroman1/aai/unstorage-kv";
+*
+* const kv = createUnstorageKv({ storage: createStorage() });
+* await kv.set("greeting", "hello");
+* const value = await kv.get<string>("greeting"); // "hello"
+* ```
+*/
+function createUnstorageKv(options) {
+	const store = options.prefix ? prefixStorage(options.storage, options.prefix) : options.storage;
+	return {
+		async get(key) {
+			return await store.getItem(key) ?? null;
+		},
+		async set(key, value, setOptions) {
+			if (JSON.stringify(value).length > 65536) throw new Error(`Value exceeds max size of ${MAX_VALUE_SIZE} bytes`);
+			const storable = value;
+			if (setOptions?.expireIn && setOptions.expireIn > 0) await store.setItem(key, storable, { ttl: Math.ceil(setOptions.expireIn / 1e3) });
+			else await store.setItem(key, storable);
+		},
+		async delete(keys) {
+			const keyArray = Array.isArray(keys) ? keys : [keys];
+			await Promise.all(keyArray.map((k) => store.removeItem(k)));
+		},
+		async list(listPrefix, listOptions) {
+			const allKeys = await store.getKeys(listPrefix);
+			const entries = [];
+			for (const key of allKeys) {
+				const value = await store.getItem(key);
+				if (value != null) entries.push({
+					key,
+					value
+				});
+			}
+			return sortAndPaginate(entries, listOptions);
+		},
+		async keys(pattern) {
+			const allKeys = await store.getKeys();
+			if (!pattern) return allKeys.sort((a, b) => a.localeCompare(b));
+			return allKeys.filter((key) => matchGlob(key, pattern)).sort((a, b) => a.localeCompare(b));
+		},
+		close() {
+			store.dispose();
+		}
+	};
+}
+//#endregion
+//#region ws-handler.ts
+/**
+* WebSocket session lifecycle handler.
+*
+* Audio validation is handled at the host transport layer (see server.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, log) {
+	/** Send data over ws, silently dropping if the socket is not open. */
+	function safeSend(data) {
+		try {
+			if (ws.readyState !== 1) return;
+			ws.send(data);
+		} catch (err) {
+			log.debug?.("safeSend: socket closed between readyState check and send", { error: errorMessage(err) });
+		}
+	}
+	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;
+		default: 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 = 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 = [];
+	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, log);
+		session = opts.createSession(sessionId, client);
+		sessions.set(sessionId, session);
+		ws.send(JSON.stringify({
+			type: "config",
+			...opts.readyConfig,
+			sessionId
+		}));
+		const timeoutMs = opts.sessionStartTimeoutMs ?? 1e4;
+		pTimeout(session.start(), {
+			milliseconds: timeoutMs,
+			message: `session.start() timed out after ${timeoutMs}ms`
+		}).then(() => {
+			log.info("Session ready", {
+				...ctx,
+				sid
+			});
+			sessionReady = true;
+			drainBuffer();
+		}).catch((err) => {
+			log.error("Session start failed", {
+				...ctx,
+				sid,
+				error: errorDetail(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);
+	});
+	ws.addEventListener("close", () => {
+		log.info("Session disconnected", {
+			...ctx,
+			sid
+		});
+		if (session) session.stop().catch((err) => {
+			log.error("Session stop failed", {
+				...ctx,
+				sid,
+				error: errorDetail(err)
+			});
+		}).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
+//#region direct-executor.ts
+/**
+* Agent runtime — the execution engine for voice agents.
+*
+* {@link createRuntime} builds the single execution engine used by both
+* self-hosted servers and the platform sandbox. It wires up tool execution,
+* lifecycle hooks, and session management.
+*/
+const yieldTick = () => new Promise((r) => setTimeout(r, 0));
+function buildToolContext(opts) {
+	const { env, state, kv, messages, fetch: fetchFn, sessionId } = opts;
+	return {
+		env: { ...env },
+		state: state ?? {},
+		get kv() {
+			if (!kv) throw new Error("KV not available");
+			return kv;
+		},
+		messages: messages ?? [],
+		fetch: fetchFn ?? globalThis.fetch,
+		sessionId: sessionId ?? ""
+	};
+}
+async function executeToolCall(name, args, options) {
+	const { tool } = options;
+	const parsed = (tool.parameters ?? EMPTY_PARAMS).safeParse(args);
+	if (!parsed.success) return toolError(`Invalid arguments for tool "${name}": ${(parsed.error?.issues ?? []).map((i) => `${i.path.map(String).join(".")}: ${i.message}`).join(", ")}`);
+	try {
+		const ctx = buildToolContext(options);
+		await yieldTick();
+		const result = await pTimeout(Promise.resolve(tool.execute(parsed.data, ctx)), {
+			milliseconds: TOOL_EXECUTION_TIMEOUT_MS,
+			message: `Tool "${name}" timed out after ${TOOL_EXECUTION_TIMEOUT_MS}ms`
+		});
+		await yieldTick();
+		if (result == null) return "null";
+		return typeof result === "string" ? result : JSON.stringify(result);
+	} catch (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));
+	}
+}
+/** Create an in-memory KV store (default for self-hosted). */
+function createLocalKv() {
+	return createUnstorageKv({ storage: createStorage() });
+}
+/**
+* Create an agent runtime — the execution engine for a voice agent.
+*
+* Merges built-in and custom tool definitions, builds tool schemas for the
+* S2S API, and wires up lifecycle hooks.
+*
+* @param opts - Runtime configuration. See {@link RuntimeOptions}.
+* @returns A {@link Runtime} with tool execution, hook invocation,
+*   schemas, and session management.
+*
+* @public
+*/
+function createRuntime(opts) {
+	const { agent, env, kv = createLocalKv(), createWebSocket, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG, sessionStartTimeoutMs, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS } = opts;
+	const agentConfig = toAgentConfig(agent);
+	const sessions = /* @__PURE__ */ new Map();
+	const readyConfig = buildReadyConfig(s2sConfig);
+	let executeTool;
+	let hooks;
+	let toolSchemas;
+	if (opts.executeTool && opts.hooks && opts.toolSchemas) {
+		executeTool = opts.executeTool;
+		hooks = opts.hooks;
+		toolSchemas = opts.toolSchemas;
+	} else {
+		const allTools = {
+			...getBuiltinToolDefs(agent.builtinTools ?? []),
+			...agent.tools
+		};
+		const customSchemas = agentToolsToSchemas(agent.tools ?? {});
+		const builtinSchemas = getBuiltinToolSchemas(agent.builtinTools ?? []);
+		toolSchemas = [...customSchemas, ...builtinSchemas];
+		const stateMap = /* @__PURE__ */ new Map();
+		const getState = (sid) => {
+			if (!stateMap.has(sid) && agent.state) stateMap.set(sid, agent.state());
+			return stateMap.get(sid) ?? {};
+		};
+		const frozenEnv = Object.freeze({ ...env });
+		function makeHookContext(sessionId) {
+			return {
+				env: frozenEnv,
+				state: getState(sessionId),
+				sessionId,
+				get kv() {
+					return kv;
+				},
+				fetch: globalThis.fetch
+			};
+		}
+		executeTool = async (name, args, sessionId, messages) => {
+			const tool = allTools[name];
+			if (!tool) return toolError(`Unknown tool: ${name}`);
+			return executeToolCall(name, args, {
+				tool,
+				env: frozenEnv,
+				state: getState(sessionId ?? ""),
+				sessionId: sessionId ?? "",
+				kv,
+				messages,
+				logger,
+				fetch: globalThis.fetch
+			});
+		};
+		hooks = createAgentHooks({
+			agent,
+			makeCtx: makeHookContext
+		});
+		hooks.hook("disconnect", async (sessionId) => {
+			stateMap.delete(sessionId);
+		});
+	}
+	function createSession(sessionOpts) {
+		const apiKey = env.ASSEMBLYAI_API_KEY ?? "";
+		return createS2sSession({
+			id: sessionOpts.id,
+			agent: sessionOpts.agent,
+			client: sessionOpts.client,
+			agentConfig,
+			toolSchemas,
+			apiKey,
+			s2sConfig,
+			executeTool,
+			...createWebSocket ? { createWebSocket } : {},
+			hooks,
+			skipGreeting: sessionOpts.skipGreeting ?? false,
+			logger,
+			...sessionOpts.resumeFrom ? { resumeFrom: sessionOpts.resumeFrom } : {}
+		});
+	}
+	function startSession(ws, startOpts) {
+		const resumeFrom = startOpts?.resumeFrom;
+		wireSessionSocket(ws, {
+			sessions,
+			createSession: (sid, client) => createSession({
+				id: sid,
+				agent: agent.name,
+				client,
+				skipGreeting: startOpts?.skipGreeting ?? false,
+				...resumeFrom ? { resumeFrom } : {}
+			}),
+			readyConfig,
+			logger,
+			...startOpts?.logContext ? { logContext: startOpts.logContext } : {},
+			...startOpts?.onOpen ? { onOpen: startOpts.onOpen } : {},
+			...startOpts?.onClose ? { onClose: startOpts.onClose } : {},
+			...sessionStartTimeoutMs !== void 0 ? { sessionStartTimeoutMs } : {},
+			...resumeFrom ? { resumeFrom } : {}
+		});
+	}
+	async function shutdown() {
+		if (sessions.size === 0) return;
+		let timer;
+		const timeout = new Promise((resolve) => {
+			timer = setTimeout(resolve, shutdownTimeoutMs, "timeout");
+		});
+		const graceful = Promise.allSettled([...sessions.values()].map((s) => s.stop())).then((results) => {
+			for (const r of results) if (r.status === "rejected") logger.warn(`Session stop failed during shutdown: ${r.reason}`);
+			return "done";
+		});
+		const outcome = await Promise.race([graceful, timeout]);
+		if (timer) clearTimeout(timer);
+		if (outcome === "timeout") logger.warn(`Shutdown timeout (${shutdownTimeoutMs}ms) exceeded — force-closing ${sessions.size} remaining session(s)`);
+		sessions.clear();
+	}
+	return {
+		executeTool,
+		hooks,
+		toolSchemas,
+		createSession,
+		startSession,
+		shutdown,
+		readyConfig
+	};
+}
+//#endregion
+export { consoleLogger as _, _internals as a, buildSystemPrompt as c, AgentConfigSchema as d, EMPTY_PARAMS as f, DEFAULT_S2S_CONFIG as g, toAgentConfig as h, createUnstorageKv as i, connectS2s as l, agentToolsToSchemas as m, executeToolCall as n, buildCtx as o, ToolSchemaSchema as p, wireSessionSocket as r, createS2sSession as s, createRuntime as t, defaultCreateS2sWebSocket as u, jsonLogger as v };