@alexkroman1/aai 0.9.3 → 0.10.0

package/dist/direct-executor-Ca0wt5H0.js

@@ -0,0 +1,572 @@
+import { defineTool } from "./types.js";
+import { EMPTY_PARAMS, agentToolsToSchemas, toAgentConfig } from "./_internal-types.js";
+import { ssrfSafeFetch } from "./_ssrf.js";
+import { createSessionStateMap, errorMessage, isReadOnlyFsOp, toolError } from "./_utils.js";
+import { runAfterToolCallMiddleware, runAfterTurnMiddleware, runBeforeTurnMiddleware, runInputFilters, runOutputFilters, runToolCallInterceptors } from "./middleware-core.js";
+import { DEFAULT_S2S_CONFIG, consoleLogger } from "./runtime.js";
+import { n as createS2sSession } from "./session-BkN9u0ni.js";
+import { createSqliteKv } from "./sqlite-kv.js";
+import { createSqliteVectorStore } from "./sqlite-vector.js";
+import { executeToolCall } from "./worker-entry.js";
+import { z } from "zod";
+import { mkdirSync } from "node:fs";
+//#region _run-code.ts
+/**
+* run_code built-in tool — executes user JavaScript in a fresh secure-exec
+* V8 isolate with no network, filesystem writes, or env access.
+*/
+const runCodeParams = z.object({ code: z.string().describe("JavaScript code to execute. Use console.log() for output.") });
+/** Timeout for sandboxed code execution. */
+const RUN_CODE_TIMEOUT = 5e3;
+/** Memory limit for run_code isolates (MB). */
+const RUN_CODE_MEMORY_MB = 32;
+/**
+* Execute JavaScript code inside a fresh secure-exec V8 isolate.
+*
+* Each invocation spins up a disposable isolate with:
+* - No filesystem writes
+* - No network access
+* - No child process spawning
+* - No environment variable access
+* - 32 MB memory limit
+* - 5 second execution timeout
+*
+* The isolate is disposed immediately after execution, so no state
+* leaks between invocations or across sessions.
+*/
+function createRunCode() {
+	return {
+		description: "Execute JavaScript code in a secure 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);
+		}
+	};
+}
+/** Lazily import secure-exec to avoid top-level side effects. */
+let _secureExecPromise;
+function getSecureExec() {
+	_secureExecPromise ??= import("secure-exec");
+	return _secureExecPromise;
+}
+const RUN_CODE_HARNESS = `
+import { readFileSync } from "node:fs";
+
+const __output = [];
+const __capture = (...args) => __output.push(args.map(String).join(" "));
+const __console = {
+  log: __capture, info: __capture, warn: __capture,
+  error: __capture, debug: __capture,
+};
+try {
+  const __userCode = readFileSync("/app/user-code.js", "utf8");
+  const __AsyncFn = Object.getPrototypeOf(async function(){}).constructor;
+  const __fn = new __AsyncFn("console", __userCode);
+  await __fn(__console);
+  const result = __output.join("\\n").trim();
+  process.stdout.write(JSON.stringify({ ok: true, result: result || "Code ran successfully (no output)" }));
+} catch (err) {
+  process.stdout.write(JSON.stringify({ ok: false, error: String(err?.message ?? err) }));
+}
+`;
+const IsolateOutputSchema = z.object({
+	ok: z.boolean(),
+	result: z.string().optional(),
+	error: z.string().optional()
+});
+/** Parse stdout from the run_code harness into a result or error. */
+function parseIsolateOutput(stdout, stderr) {
+	if (!stdout) {
+		if (stderr) return { error: stderr.trim() };
+		return { error: "Code execution timed out" };
+	}
+	try {
+		const parsed = IsolateOutputSchema.parse(JSON.parse(stdout));
+		if (parsed.ok) return parsed.result ?? "Code ran successfully (no output)";
+		return { error: parsed.error ?? "Unknown error" };
+	} catch {
+		return stdout.trim() || "Code ran successfully (no output)";
+	}
+}
+/**
+* Exported for testing — execute user code in a fresh secure-exec V8 isolate.
+*/
+async function executeInIsolate(code) {
+	const { createInMemoryFileSystem, createNodeDriver, createNodeRuntimeDriverFactory, NodeRuntime } = await getSecureExec();
+	const fs = createInMemoryFileSystem();
+	await fs.writeFile("/app/harness.js", RUN_CODE_HARNESS);
+	await fs.writeFile("/app/user-code.js", code);
+	const stdoutChunks = [];
+	const stderrChunks = [];
+	let resolveOutput = null;
+	const outputReady = new Promise((r) => {
+		resolveOutput = r;
+	});
+	const runtime = new NodeRuntime({
+		systemDriver: createNodeDriver({
+			filesystem: fs,
+			permissions: {
+				fs: (req) => isReadOnlyFsOp(req.op) ? { allow: true } : {
+					allow: false,
+					reason: "Filesystem is read-only"
+				},
+				network: () => ({
+					allow: false,
+					reason: "Network access is disabled in run_code"
+				}),
+				childProcess: () => ({
+					allow: false,
+					reason: "Subprocess spawning is disabled"
+				}),
+				env: () => ({
+					allow: false,
+					reason: "Env access is disabled in run_code"
+				})
+			}
+		}),
+		runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+		memoryLimit: RUN_CODE_MEMORY_MB,
+		onStdio(event) {
+			if (event.channel === "stdout") stdoutChunks.push(event.message);
+			if (event.channel === "stderr") stderrChunks.push(event.message);
+			resolveOutput?.();
+		}
+	});
+	const execPromise = runtime.exec("import \"/app/harness.js\";", { cwd: "/app" });
+	try {
+		await Promise.race([outputReady, new Promise((r) => setTimeout(r, RUN_CODE_TIMEOUT))]);
+		await Promise.race([execPromise.catch(() => {}), new Promise((r) => setTimeout(r, 200))]);
+		return parseIsolateOutput(stdoutChunks.join(""), stderrChunks.join(""));
+	} catch (err) {
+		return { error: errorMessage(err) };
+	} finally {
+		runtime.dispose();
+	}
+}
+//#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).
+*/
+/** Per-fetch timeout for network tools — tighter than the overall tool timeout. */
+const FETCH_TIMEOUT_MS = 15e3;
+const fetchSignal = () => AbortSignal.timeout(FETCH_TIMEOUT_MS);
+/** Lazily import html-to-text to avoid loading 824KB dep tree at startup. */
+let _htmlToTextPromise;
+function getHtmlToText() {
+	_htmlToTextPromise ??= import("html-to-text");
+	return _htmlToTextPromise;
+}
+async function htmlToText(html) {
+	const { convert } = await getHtmlToText();
+	return convert(html, { wordwrap: false });
+}
+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 MAX_PAGE_CHARS = 1e4;
+const MAX_HTML_BYTES = 2e5;
+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 ssrfSafeFetch(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()
+			}, fetchFn);
+			if (!resp.ok) return {
+				error: `Failed to fetch: ${resp.status} ${resp.statusText}`,
+				url
+			};
+			const htmlContent = await resp.text();
+			const text = await htmlToText(htmlContent.length > MAX_HTML_BYTES ? 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 ssrfSafeFetch(url, {
+				...safeHeaders && { headers: safeHeaders },
+				signal: fetchSignal()
+			}, fetchFn);
+			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
+				};
+			}
+		}
+	};
+}
+const vectorSearchParams = z.object({
+	query: z.string().describe("Short keyword query to search the knowledge base. Use specific topic terms, not full sentences. Do NOT include the company or product name since all documents are from the same source. For example, if the user asks \"how much does Acme cost\", search for \"pricing plans rates\"."),
+	topK: z.number().describe("Maximum results to return (default: 5)").optional()
+});
+function createVectorSearch(vectorSearchFn) {
+	return {
+		description: "Search the agent's knowledge base for relevant information. Use this when the user asks a question that might be answered by previously ingested documents or data. Returns the most relevant matches ranked by similarity.",
+		parameters: vectorSearchParams,
+		async execute(args) {
+			const { query, topK = 5 } = args;
+			return vectorSearchFn(query, topK);
+		}
+	};
+}
+/** 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 "vector_search":
+			if (!opts?.vectorSearch) return [];
+			return [["vector_search", createVectorSearch(opts.vectorSearch)]];
+		case "memory": return Object.entries(memoryTools());
+		default: return [];
+	}
+}
+/**
+* Create built-in tool definitions for the given tool names.
+* For runtime use — vector_search requires opts.vectorSearch to be included.
+*/
+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, { vectorSearch: async () => "" }).map(([toolName, def]) => ({
+		name: toolName,
+		description: def.description,
+		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
+	})));
+}
+//#endregion
+//#region direct-executor.ts
+/**
+* Direct tool execution for self-hosted mode.
+*
+* In self-hosted mode, agent code is trusted (you're running your own code).
+* Tools execute directly in-process — no sandbox, no RPC.
+*/
+/** Create a SQLite-backed KV store in `.aai/local.db`. */
+function createLocalKv() {
+	mkdirSync(".aai", { recursive: true });
+	return createSqliteKv();
+}
+/** Create a SQLite-vec backed vector store in `.aai/vectors.db`. */
+function createLocalVectorStore() {
+	mkdirSync(".aai", { recursive: true });
+	return createSqliteVectorStore({ path: ".aai/vectors.db" });
+}
+/**
+* Create a direct (in-process) tool executor and hook invoker for an agent.
+*
+* Merges built-in and custom tool definitions, builds tool schemas for the
+* S2S API, and wires up middleware and lifecycle hooks.
+*
+* @param opts - Executor configuration. See {@link DirectExecutorOptions}.
+* @returns A {@link DirectExecutor} with tool execution, hook invocation,
+*   schemas, and session creation.
+*/
+function createDirectExecutor(opts) {
+	const { agent, env, kv = createLocalKv(), vector = createLocalVectorStore(), vectorSearch, createWebSocket, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG } = opts;
+	const agentConfig = toAgentConfig(agent);
+	const allTools = {
+		...getBuiltinToolDefs(agent.builtinTools ?? [], vectorSearch ? { vectorSearch } : void 0),
+		...agent.tools
+	};
+	const customSchemas = agentToolsToSchemas(agent.tools ?? {});
+	const builtinSchemas = getBuiltinToolSchemas(agent.builtinTools ?? []);
+	const toolSchemas = [...customSchemas, ...builtinSchemas];
+	const sessionState = createSessionStateMap(agent.state);
+	const frozenEnv = Object.freeze({ ...env });
+	/** SSRF-safe fetch for tool/hook contexts in self-hosted mode. */
+	const safeFetch = (input, init) => {
+		const req = new Request(input, init);
+		return ssrfSafeFetch(req.url, {
+			...init,
+			method: req.method
+		}, globalThis.fetch);
+	};
+	function makeHookContext(sessionId) {
+		return {
+			env: frozenEnv,
+			state: sessionState.get(sessionId),
+			sessionId,
+			get kv() {
+				return kv;
+			},
+			get vector() {
+				return vector;
+			},
+			fetch: safeFetch
+		};
+	}
+	const executeTool = async (name, args, sessionId, messages, onUpdate) => {
+		const tool = allTools[name];
+		if (!tool) return toolError(`Unknown tool: ${name}`);
+		return executeToolCall(name, args, {
+			tool,
+			env: frozenEnv,
+			state: sessionState.get(sessionId ?? ""),
+			sessionId: sessionId ?? "",
+			kv,
+			vector,
+			messages,
+			logger,
+			onUpdate,
+			fetch: safeFetch
+		});
+	};
+	const middleware = agent.middleware ?? [];
+	const hookInvoker = {
+		async onConnect(sessionId) {
+			await agent.onConnect?.(makeHookContext(sessionId));
+		},
+		async onDisconnect(sessionId) {
+			await agent.onDisconnect?.(makeHookContext(sessionId));
+			sessionState.delete(sessionId);
+		},
+		async onTurn(sessionId, text) {
+			await agent.onTurn?.(text, makeHookContext(sessionId));
+		},
+		async onError(sessionId, error) {
+			await agent.onError?.(new Error(error.message), makeHookContext(sessionId));
+		},
+		async onStep(sessionId, step) {
+			await agent.onStep?.(step, makeHookContext(sessionId));
+		},
+		async resolveTurnConfig(sessionId) {
+			const ctx = makeHookContext(sessionId);
+			const maxSteps = typeof agent.maxSteps === "function" ? await agent.maxSteps(ctx) ?? void 0 : void 0;
+			if (maxSteps === void 0) return null;
+			return { maxSteps };
+		},
+		async filterInput(sessionId, text) {
+			if (middleware.length === 0) return text;
+			return runInputFilters(middleware, text, makeHookContext(sessionId));
+		},
+		async beforeTurn(sessionId, text) {
+			if (middleware.length === 0) return;
+			return (await runBeforeTurnMiddleware(middleware, text, makeHookContext(sessionId)))?.reason;
+		},
+		async afterTurn(sessionId, text) {
+			if (middleware.length === 0) return;
+			await runAfterTurnMiddleware(middleware, text, makeHookContext(sessionId));
+		},
+		async interceptToolCall(sessionId, toolName, args) {
+			if (middleware.length === 0) return;
+			return runToolCallInterceptors(middleware, toolName, args, makeHookContext(sessionId));
+		},
+		async afterToolCall(sessionId, toolName, args, result) {
+			if (middleware.length === 0) return;
+			await runAfterToolCallMiddleware(middleware, toolName, args, result, makeHookContext(sessionId));
+		},
+		async filterOutput(sessionId, text) {
+			if (middleware.length === 0) return text;
+			return runOutputFilters(middleware, text, makeHookContext(sessionId));
+		}
+	};
+	function createSession(sessionOpts) {
+		const apiKey = frozenEnv.ASSEMBLYAI_API_KEY ?? "";
+		const persistenceOpts = agent.persistence ? {
+			persistence: {
+				kv,
+				ttl: agent.persistence.ttl,
+				getState: () => sessionState.get(sessionOpts.id),
+				setState: (state) => sessionState.set(sessionOpts.id, state)
+			},
+			...sessionOpts.resumeFrom ? { resumeFrom: sessionOpts.resumeFrom } : {}
+		} : {};
+		return createS2sSession({
+			id: sessionOpts.id,
+			agent: sessionOpts.agent,
+			client: sessionOpts.client,
+			agentConfig,
+			toolSchemas,
+			apiKey,
+			s2sConfig,
+			executeTool,
+			...createWebSocket ? { createWebSocket } : {},
+			hookInvoker,
+			skipGreeting: sessionOpts.skipGreeting ?? false,
+			logger,
+			...persistenceOpts
+		});
+	}
+	return {
+		executeTool,
+		hookInvoker,
+		toolSchemas,
+		createSession
+	};
+}
+//#endregion
+export { createDirectExecutor as t };

package/dist/direct-executor.d.ts

@@ -4,7 +4,7 @@
  * In self-hosted mode, agent code is trusted (you're running your own code).
  * Tools execute directly in-process — no sandbox, no RPC.
  */
-import { type AgentConfig, type ToolSchema } from "./_internal-types.ts";
+import { type ToolSchema } from "./_internal-types.ts";
 import type { Kv } from "./kv.ts";
 import type { ClientSink } from "./protocol.ts";
 import type { Logger, S2SConfig } from "./runtime.ts";
@@ -13,28 +13,57 @@ import { type HookInvoker, type Session } from "./session.ts";
 import type { AgentDef } from "./types.ts";
 import type { VectorStore } from "./vector.ts";
 import type { ExecuteTool } from "./worker-entry.ts";
+/**
+ * Configuration for creating a direct (in-process) tool executor for self-hosted mode.
+ *
+ * In self-hosted mode, agent tools run directly in the Node process — no sandbox or
+ * RPC layer. This type configures the agent, environment, stores, and logging.
+ */
 export type DirectExecutorOptions = {
-    agent: AgentDef;
+    agent: AgentDef<any>;
     env: Record<string, string>;
     kv?: Kv | undefined;
     vector?: VectorStore | undefined;
+    /** Vector search callback. Accepts a query and topK, returns a JSON string.
+     *  Used as an RPC proxy in platform mode; in self-hosted mode the default
+     *  uses the local `vector` store directly. */
     vectorSearch?: ((query: string, topK: number) => Promise<string>) | undefined;
+    /** Custom WebSocket factory for the S2S connection (useful for testing). */
     createWebSocket?: CreateS2sWebSocket | undefined;
     logger?: Logger | undefined;
     s2sConfig?: S2SConfig | undefined;
 };
+/**
+ * The direct (in-process) executor returned by {@link createDirectExecutor}.
+ *
+ * Provides tool execution, hook invocation, tool schemas for the S2S API,
+ * and a factory for creating voice sessions.
+ */
 export type DirectExecutor = {
+    /** Execute a named tool with the given args, returning a JSON result string. */
     executeTool: ExecuteTool;
+    /** Hook invoker wired to the agent's lifecycle hooks and middleware. */
     hookInvoker: HookInvoker;
+    /** Tool schemas registered with the S2S API (custom + built-in). */
     toolSchemas: ToolSchema[];
+    /** Create a new voice session for a connected client. */
     createSession(opts: {
         id: string;
         agent: string;
         client: ClientSink;
         skipGreeting?: boolean;
+        /** Old session ID to resume from (loads persisted state from KV). */
+        resumeFrom?: string;
     }): Session;
 };
-/** Build a serializable AgentConfig from an AgentDef. */
-export declare function buildAgentConfig(agent: AgentDef): AgentConfig;
-/** Create a direct (in-process) tool executor and hook invoker for an agent. */
+/**
+ * Create a direct (in-process) tool executor and hook invoker for an agent.
+ *
+ * Merges built-in and custom tool definitions, builds tool schemas for the
+ * S2S API, and wires up middleware and lifecycle hooks.
+ *
+ * @param opts - Executor configuration. See {@link DirectExecutorOptions}.
+ * @returns A {@link DirectExecutor} with tool execution, hook invocation,
+ *   schemas, and session creation.
+ */
 export declare function createDirectExecutor(opts: DirectExecutorOptions): DirectExecutor;

package/dist/index.d.ts

@@ -19,5 +19,6 @@
  * });
  * ```
  */
-export { type AgentOptions, type BeforeStepResult, type BuiltinTool, defineAgent, type HookContext, type Message, type StepInfo, type ToolContext, type ToolDef, tool, } from "./types.ts";
+export type { Kv, KvEntry, KvListOptions } from "./kv.ts";
+export { type AgentDef, type AgentOptions, type BuiltinTool, createToolFactory, defineAgent, defineTool, type HookContext, type Message, type Middleware, type MiddlewareBlockResult, type StepInfo, type ToolCallInterceptResult, type ToolChoice, type ToolContext, type ToolDef, type ToolResultMap, tool, } from "./types.ts";
 export type { VectorEntry, VectorStore } from "./vector.ts";

package/dist/index.js

@@ -1,2 +1,2 @@
-import { defineAgent, tool } from "./types.js";
-export { defineAgent, tool };
+import { createToolFactory, defineAgent, defineTool } from "./types.js";
+export { createToolFactory, defineAgent, defineTool, defineTool as tool };