@alexkroman1/aai 0.12.3 → 1.0.3

package/dist/host/vite-plugin.d.ts

@@ -1,15 +0,0 @@
-/**
- * Vite plugin for AAI agent development.
- *
- * In dev mode: boots the agent backend server and configures proxy.
- * Handles .env loading, runtime creation, and WebSocket proxying
- * so `vite` alone gives you a working dev server.
- */
-import type { Plugin } from "vite";
-export type AaiPluginOptions = {
-    /** Path to agent entry (default: "agent.ts") */
-    agent?: string;
-    /** Backend port (default: Vite port + 1) */
-    backendPort?: number;
-};
-export declare function aai(options?: AaiPluginOptions): Plugin;

package/dist/host/vite-plugin.js

@@ -1,83 +0,0 @@
-import path from "node:path";
-import fs from "node:fs/promises";
-//#region host/vite-plugin.ts
-/**
-* Vite plugin for AAI agent development.
-*
-* In dev mode: boots the agent backend server and configures proxy.
-* Handles .env loading, runtime creation, and WebSocket proxying
-* so `vite` alone gives you a working dev server.
-*/
-function parseEnvFile(content) {
-	const entries = {};
-	for (const raw of content.split("\n")) {
-		const line = raw.trim();
-		if (!line || line.startsWith("#")) continue;
-		const eq = line.indexOf("=");
-		if (eq === -1) continue;
-		const key = line.slice(0, eq).trim();
-		if (key) entries[key] = line.slice(eq + 1);
-	}
-	return entries;
-}
-async function resolveAgentEnv(root) {
-	let fileEntries = {};
-	try {
-		fileEntries = parseEnvFile(await fs.readFile(path.join(root, ".env"), "utf-8"));
-	} catch {}
-	const env = {};
-	for (const [key, fileVal] of Object.entries(fileEntries)) env[key] = process.env[key] ?? fileVal;
-	if (!env.ASSEMBLYAI_API_KEY && process.env.ASSEMBLYAI_API_KEY) env.ASSEMBLYAI_API_KEY = process.env.ASSEMBLYAI_API_KEY;
-	return env;
-}
-function aai(options) {
-	const agentEntry = options?.agent ?? "agent.ts";
-	let backendPort = options?.backendPort;
-	let server = null;
-	return {
-		name: "aai",
-		apply: "serve",
-		config(config) {
-			const vitePort = config.server?.port ?? 3e3;
-			const envPort = Number(process.env.AAI_BACKEND_PORT);
-			backendPort = backendPort ?? (envPort > 0 ? envPort : vitePort + 1);
-			const target = `http://localhost:${backendPort}`;
-			return { server: { proxy: {
-				"/health": target,
-				"/websocket": {
-					target,
-					ws: true
-				}
-			} } };
-		},
-		async configureServer(viteServer) {
-			const root = viteServer.config.root;
-			const agentPath = path.resolve(root, agentEntry);
-			const { createRuntime, createServer } = await import("./server.js");
-			const agentDef = (await viteServer.ssrLoadModule(agentPath)).default;
-			if (!agentDef?.name) {
-				viteServer.config.logger.error("agent.ts must export a default defineAgent() call");
-				return;
-			}
-			const agentServer = createServer({
-				runtime: createRuntime({
-					agent: agentDef,
-					env: await resolveAgentEnv(root)
-				}),
-				name: agentDef.name
-			});
-			if (backendPort == null) throw new Error("backendPort was not resolved during config phase");
-			await agentServer.listen(backendPort);
-			server = agentServer;
-			viteServer.config.logger.info(`Agent backend on port ${backendPort}`);
-		},
-		async buildEnd() {
-			if (server) {
-				await server.close();
-				server = null;
-			}
-		}
-	};
-}
-//#endregion
-export { aai };

package/dist/isolate/_kv-utils.d.ts

@@ -1,10 +0,0 @@
-/** Internal KV helpers shared by kv.ts and unstorage-kv.ts. */
-/** Sort entries by key and apply reverse/limit options. Mutates the array. */
-export declare function sortAndPaginate<T extends {
-    key: string;
-}>(entries: T[], options?: {
-    limit?: number;
-    reverse?: boolean;
-}): T[];
-/** Simple glob matcher — supports `*` as a wildcard for any characters. */
-export declare function matchGlob(key: string, pattern: string): boolean;

package/dist/isolate/_utils.js

@@ -1,17 +0,0 @@
-//#region isolate/_utils.ts
-/** Shared utility functions. */
-/** Extract an error message from an unknown thrown value. */
-function errorMessage(err) {
-	return err instanceof Error ? err.message : String(err);
-}
-/** Extract a detailed error string (message + stack) for diagnostic logging. */
-function errorDetail(err) {
-	if (err instanceof Error) return err.stack ?? err.message;
-	return String(err);
-}
-/** Return a JSON error string for the LLM: `'{"error":"<message>"}'`. */
-function toolError(message) {
-	return JSON.stringify({ error: message });
-}
-//#endregion
-export { errorDetail, errorMessage, toolError };

package/dist/isolate/hooks.d.ts

@@ -1,44 +0,0 @@
-/**
- * Hookable-based lifecycle hook system.
- *
- * Provides a unified hook registry built on {@link https://github.com/unjs/hookable | hookable}.
- * Lifecycle hooks (connect, disconnect, turn, error, resolveTurnConfig) are
- * registered on a single `Hookable<AgentHookMap>` instance.
- */
-import { type Hookable } from "hookable";
-import type { AgentDef, HookContext } from "./types.ts";
-/**
- * Map of all agent hook names to their function signatures.
- *
- * All hooks are typed as void-returning for hookable compatibility.
- * Value-returning hooks (resolveTurnConfig) are invoked via
- * {@link callHookWith} with a custom caller that extracts the return value.
- */
-export interface AgentHookMap {
-    connect: (sessionId: string, timeoutMs?: number) => void | Promise<void>;
-    disconnect: (sessionId: string, timeoutMs?: number) => void | Promise<void>;
-    turn: (sessionId: string, text: string, timeoutMs?: number) => void | Promise<void>;
-    error: (sessionId: string, error: {
-        message: string;
-    }, timeoutMs?: number) => void | Promise<void>;
-    resolveTurnConfig: (sessionId: string, timeoutMs?: number) => void | Promise<void>;
-}
-/** A hookable instance typed to the agent hook map. */
-export type AgentHooks = Hookable<AgentHookMap>;
-/**
- * Call the resolveTurnConfig hook.
- * Returns null when no handler is registered.
- */
-export declare function callResolveTurnConfig(hooks: AgentHooks | undefined, sessionId: string, timeoutMs?: number): Promise<{
-    maxSteps?: number;
-} | null>;
-/**
- * Create an {@link AgentHooks} instance from an agent definition.
- *
- * Registers lifecycle hooks from the agent's `onConnect`, `onDisconnect`,
- * `onTurn`, `onError` callbacks.
- */
-export declare function createAgentHooks(opts: {
-    agent: AgentDef<any>;
-    makeCtx: (sessionId: string) => HookContext;
-}): AgentHooks;

package/dist/isolate/hooks.js

@@ -1,58 +0,0 @@
-import { createHooks } from "hookable";
-//#region isolate/hooks.ts
-/**
-* Hookable-based lifecycle hook system.
-*
-* Provides a unified hook registry built on {@link https://github.com/unjs/hookable | hookable}.
-* Lifecycle hooks (connect, disconnect, turn, error, resolveTurnConfig) are
-* registered on a single `Hookable<AgentHookMap>` instance.
-*/
-/**
-* Caller that invokes the first registered handler and returns its result.
-* Returns `fallback` when no handlers are registered.
-*/
-function firstResultCaller(fallback) {
-	return async (fns, args) => {
-		if (fns.length === 0) return fallback;
-		return await fns[0](...args) ?? fallback;
-	};
-}
-/**
-* Call the resolveTurnConfig hook.
-* Returns null when no handler is registered.
-*/
-async function callResolveTurnConfig(hooks, sessionId, timeoutMs) {
-	if (!hooks) return null;
-	return hooks.callHookWith(firstResultCaller(null), "resolveTurnConfig", [sessionId, timeoutMs]);
-}
-/**
-* Create an {@link AgentHooks} instance from an agent definition.
-*
-* Registers lifecycle hooks from the agent's `onConnect`, `onDisconnect`,
-* `onTurn`, `onError` callbacks.
-*/
-function createAgentHooks(opts) {
-	const { agent, makeCtx } = opts;
-	const hooks = createHooks();
-	hooks.hook("connect", async (sessionId) => {
-		await agent.onConnect?.(makeCtx(sessionId));
-	});
-	hooks.hook("disconnect", async (sessionId) => {
-		await agent.onDisconnect?.(makeCtx(sessionId));
-	});
-	hooks.hook("turn", async (sessionId, text) => {
-		await agent.onTurn?.(text, makeCtx(sessionId));
-	});
-	hooks.hook("error", async (sessionId, error) => {
-		await agent.onError?.(new Error(error.message), makeCtx(sessionId));
-	});
-	hooks.hook("resolveTurnConfig", (async (sessionId) => {
-		const ctx = makeCtx(sessionId);
-		const maxSteps = typeof agent.maxSteps === "function" ? await agent.maxSteps(ctx) ?? void 0 : void 0;
-		if (maxSteps === void 0) return null;
-		return { maxSteps };
-	}));
-	return hooks;
-}
-//#endregion
-export { callResolveTurnConfig, createAgentHooks };

package/dist/isolate/index.d.ts

@@ -1,18 +0,0 @@
-/**
- * Isolate-safe barrel — re-exports all SDK modules that are guaranteed to
- * run inside secure-exec V8 isolates (no `node:*` dependencies).
- *
- * This directory is compiled under a restricted `tsconfig.json` that excludes
- * `@types/node`. Any accidental `node:*` import becomes a type error.
- *
- * Host-only code (server, executor, S2S, etc.) lives at the package root
- * and is re-exported via `./host`.
- */
-export * from "./_internal-types.ts";
-export * from "./_utils.ts";
-export * from "./constants.ts";
-export * from "./hooks.ts";
-export * from "./kv.ts";
-export * from "./protocol.ts";
-export * from "./system-prompt.ts";
-export * from "./types.ts";

package/dist/isolate/index.js

@@ -1,6 +0,0 @@
-import { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, defineAgent, defineTool, defineToolFactory } from "./types.js";
-import { a as agentToolsToSchemas, i as ToolSchemaSchema, n as AgentConfigSchema, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-DYAYFW99.js";
-import { errorDetail, errorMessage, toolError } from "./_utils.js";
-import { C as MAX_VALUE_SIZE, S as MAX_TOOL_RESULT_CHARS, T as TOOL_EXECUTION_TIMEOUT_MS, _ as FETCH_TIMEOUT_MS, a as ReadyConfigSchema, b as MAX_HTML_BYTES, c as TurnConfigSchema, d as DEFAULT_IDLE_TIMEOUT_MS, f as DEFAULT_MAX_HISTORY, g as DEFAULT_TTS_SAMPLE_RATE, h as DEFAULT_STT_SAMPLE_RATE, i as KvRequestSchema, l as buildReadyConfig, m as DEFAULT_SHUTDOWN_TIMEOUT_MS, n as ClientEventSchema, o as ServerMessageSchema, p as DEFAULT_SESSION_START_TIMEOUT_MS, r as ClientMessageSchema, s as SessionErrorCodeSchema, t as AUDIO_FORMAT, u as AGENT_CSP, v as HOOK_TIMEOUT_MS, w as RUN_CODE_TIMEOUT_MS, x as MAX_PAGE_CHARS, y as MAX_GLOB_PATTERN_LENGTH } from "../protocol-rcOrz7T3.js";
-import { callResolveTurnConfig, createAgentHooks } from "./hooks.js";
-export { AGENT_CSP, AUDIO_FORMAT, AgentConfigSchema, BuiltinToolSchema, ClientEventSchema, ClientMessageSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_INSTRUCTIONS, DEFAULT_MAX_HISTORY, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE, EMPTY_PARAMS, FETCH_TIMEOUT_MS, HOOK_TIMEOUT_MS, KvRequestSchema, MAX_GLOB_PATTERN_LENGTH, MAX_HTML_BYTES, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, RUN_CODE_TIMEOUT_MS, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, ToolSchemaSchema, TurnConfigSchema, agentToolsToSchemas, buildReadyConfig, buildSystemPrompt, callResolveTurnConfig, createAgentHooks, defineAgent, defineTool, defineTool as tool, defineToolFactory, errorDetail, errorMessage, toAgentConfig, toolError };

package/dist/isolate/kv.js

@@ -1 +0,0 @@
-export {};

package/dist/isolate/protocol.js

@@ -1,2 +0,0 @@
-import { a as ReadyConfigSchema, c as TurnConfigSchema, i as KvRequestSchema, l as buildReadyConfig, n as ClientEventSchema, o as ServerMessageSchema, r as ClientMessageSchema, s as SessionErrorCodeSchema, t as AUDIO_FORMAT } from "../protocol-rcOrz7T3.js";
-export { AUDIO_FORMAT, ClientEventSchema, ClientMessageSchema, KvRequestSchema, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TurnConfigSchema, buildReadyConfig };

package/dist/isolate/types.d.ts

@@ -1,418 +0,0 @@
-/**
- * Core type definitions for the AAI agent SDK.
- */
-import { z } from "zod";
-import type { Kv } from "./kv.ts";
-/**
- * Identifier for a built-in server-side tool.
- *
- * Built-in tools run on the host process (not inside the sandboxed worker)
- * and provide capabilities like web search, code execution, and API access.
- *
- * - `"web_search"` — Search the web for current information, facts, or news.
- * - `"visit_webpage"` — Fetch a URL and return its content as clean text.
- * - `"fetch_json"` — Call a REST API endpoint and return the JSON response.
- * - `"run_code"` — Execute JavaScript in a sandbox for calculations and data processing.
- * - `"memory"` — Persistent KV memory: save_memory, recall_memory, list_memories, forget_memory.
- *
- * @public
- */
-export type BuiltinTool = "web_search" | "visit_webpage" | "fetch_json" | "run_code";
-/**
- * How the LLM should select tools during a turn.
- *
- * - `"auto"` — The model decides whether to call a tool.
- * - `"required"` — The model must call at least one tool.
- * - `"none"` — Tool calling is disabled.
- * - `{ type: "tool"; toolName: string }` — Force a specific tool.
- *
- * @public
- */
-export type ToolChoice = "auto" | "required" | "none" | {
-    type: "tool";
-    toolName: string;
-};
-/**
- * A single message in the conversation history.
- *
- * Messages are passed to tool `execute` functions via
- * {@link ToolContext.messages} to provide conversation context.
- *
- * @public
- */
-export type Message = {
-    /** The role of the message sender. */
-    role: "user" | "assistant" | "tool";
-    /** The text content of the message. */
-    content: string;
-};
-/**
- * Context passed to tool `execute` functions.
- *
- * Provides access to the session environment, state, KV store, and
- * conversation history from within a tool's execute handler.
- *
- * @typeParam S - The shape of per-session state created by the agent's
- *   `state` factory. Defaults to `Record<string, unknown>`.
- *
- * @example
- * ```ts
- * import { type ToolDef } from "aai";
- * import { z } from "zod";
- *
- * const myTool: ToolDef = {
- *   description: "Look up a value from the KV store",
- *   parameters: z.object({ key: z.string() }),
- *   execute: async ({ key }, ctx) => {
- *     const value = await ctx.kv.get(key);
- *     return { key, value };
- *   },
- * };
- * ```
- *
- * @public
- */
-export type ToolContext<S = Record<string, unknown>> = {
-    /** Environment variables declared in the agent config. */
-    env: Readonly<Record<string, string>>;
-    /** Mutable per-session state created by the agent's `state` factory. */
-    state: S;
-    /** Key-value store scoped to this agent deployment. */
-    kv: Kv;
-    /** Read-only snapshot of conversation messages so far. */
-    messages: readonly Message[];
-    /**
-     * SSRF-safe fetch function.
-     *
-     * In self-hosted mode this calls the network directly (with SSRF protection).
-     * In platform mode this is proxied through the sidecar so it works inside
-     * the sandbox. Always use `ctx.fetch` instead of the global `fetch` in tool
-     * code to ensure portability across both deployment modes.
-     */
-    fetch: typeof globalThis.fetch;
-    /** Unique identifier for the current session. Useful for correlating logs across concurrent sessions. */
-    sessionId: string;
-};
-/**
- * Context passed to lifecycle hooks.
- *
- * @typeParam S - The shape of per-session state created by the agent's
- *   `state` factory. Defaults to `Record<string, unknown>`.
- *
- * @public
- */
-export type HookContext<S = Record<string, unknown>> = {
-    /** Environment variables declared in the agent config. */
-    env: Readonly<Record<string, string>>;
-    /** Mutable per-session state created by the agent's `state` factory. */
-    state: S;
-    /** Key-value store scoped to this agent deployment. */
-    kv: Kv;
-    /**
-     * SSRF-safe fetch function.
-     * In self-hosted mode this calls the network directly (with SSRF protection).
-     * In platform mode this is proxied through the sidecar.
-     */
-    fetch: typeof globalThis.fetch;
-    /** Unique identifier for the current session. */
-    sessionId: string;
-};
-/**
- * Definition of a custom tool that the agent can invoke.
- *
- * Tools are the primary way to extend agent capabilities. Each tool has a
- * description (shown to the LLM), optional Zod parameters schema, and an
- * `execute` function that runs inside the sandboxed worker.
- *
- * @typeParam P - A Zod object schema describing the tool's parameters.
- *   Defaults to `ZodObject<ZodRawShape>` so tools without parameters don't need an explicit
- *   type argument.
- *
- * @example
- * ```ts
- * import { type ToolDef } from "aai";
- * import { z } from "zod";
- *
- * const weatherTool: ToolDef<typeof params> = {
- *   description: "Get current weather for a city",
- *   parameters: z.object({
- *     city: z.string().describe("City name"),
- *   }),
- *   execute: async ({ city }) => {
- *     const res = await fetch(`https://wttr.in/${city}?format=j1`);
- *     return await res.json();
- *   },
- * };
- *
- * const params = z.object({ city: z.string() });
- * ```
- *
- * @public
- */
-export type ToolDef<P extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, S = Record<string, unknown>> = {
-    /** Human-readable description shown to the LLM. */
-    description: string;
-    /** Zod schema for the tool's parameters. */
-    parameters?: P;
-    /** Function that executes the tool and returns a result. */
-    execute(args: z.infer<P>, ctx: ToolContext<S>): Promise<unknown> | unknown;
-};
-/**
- * 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
- */
-export declare function defineTool<P extends z.ZodObject<z.ZodRawShape>, S = Record<string, unknown>>(def: ToolDef<P, S>): ToolDef<P, S>;
-/** Alias for {@link defineTool}. Prefer `defineTool` for clarity. */
-export { defineTool as tool };
-/**
- * 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. `defineToolFactory` eliminates
- * that boilerplate by returning a `defineTool` variant that already knows `S`.
- *
- * @example
- * ```ts
- * import { defineToolFactory, defineAgent } from "aai";
- * import { z } from "zod";
- *
- * interface PortfolioState { holdings: Map<string, number> }
- *
- * const tool = defineToolFactory<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
- */
-export declare function defineToolFactory<S = Record<string, unknown>>(): <P extends z.ZodObject<z.ZodRawShape>>(def: ToolDef<P, S>) => ToolDef<P, S>;
-/**
- * A mapping of tool names to their result types.
- *
- * Define this in a shared file (e.g. `shared.ts`) that both `agent.ts` and
- * `client.tsx` can import, so tool result types stay in sync without
- * duplication.
- *
- * @example
- * ```ts
- * // shared.ts
- * import type { ToolResultMap } from "@alexkroman1/aai";
- *
- * export interface Pizza {
- *   id: number;
- *   size: "small" | "medium" | "large";
- *   toppings: string[];
- * }
- *
- * export type MyToolResults = ToolResultMap<{
- *   add_pizza: { added: Pizza; orderTotal: string };
- *   place_order: { orderNumber: number; total: string };
- * }>;
- * ```
- *
- * Then use with {@link @alexkroman1/aai-ui#useToolResult | useToolResult}:
- *
- * ```tsx
- * // client.tsx
- * import type { MyToolResults } from "./shared.ts";
- *
- * useToolResult<MyToolResults["add_pizza"]>("add_pizza", (result) => {
- *   console.log(result.added); // fully typed
- * });
- * ```
- *
- * @public
- */
-export type ToolResultMap<T extends Record<string, unknown> = Record<string, unknown>> = T;
-/**
- * Options passed to {@link defineAgent} to configure an agent.
- *
- * Only `name` is required; all other fields have sensible defaults.
- *
- * @typeParam S - The shape of per-session state returned by the `state`
- *   factory. Defaults to `Record<string, unknown>`.
- *
- * @example
- * ```ts
- * import { defineAgent } from "aai";
- * import { z } from "zod";
- *
- * export default defineAgent({
- *   name: "research-bot",
- *   instructions: "You help users research topics.",
- *   builtinTools: ["web_search"],
- *   tools: {
- *     summarize: {
- *       description: "Summarize text",
- *       parameters: z.object({ text: z.string() }),
- *       execute: ({ text }) => text.slice(0, 200) + "...",
- *     },
- *   },
- * });
- * ```
- *
- * @public
- */
-export type AgentOptions<S = Record<string, unknown>> = {
-    /** Display name for the agent. */
-    name: string;
-    /** System prompt for the LLM. Defaults to a built-in voice-optimized prompt. */
-    instructions?: string;
-    /** Initial spoken greeting when a session starts. */
-    greeting?: string;
-    /** Prompt hint for the STT model to improve transcription accuracy. */
-    sttPrompt?: string;
-    /**
-     * Maximum agentic loop iterations per turn. Can be a static number or
-     * a function that receives the hook context and returns a number.
-     *
-     * @defaultValue 5
-     */
-    maxSteps?: number | ((ctx: HookContext<S>) => number);
-    /** How the LLM should choose tools. */
-    toolChoice?: ToolChoice;
-    /** Built-in tools to enable (e.g. `"web_search"`, `"run_code"`). */
-    builtinTools?: readonly BuiltinTool[];
-    /** Custom tools the agent can invoke. */
-    tools?: Readonly<Record<string, ToolDef<z.ZodObject<z.ZodRawShape>, NoInfer<S>>>>;
-    /** Factory that creates fresh per-session state. Called once per connection. */
-    state?: () => S;
-    /** Called when a new session connects. */
-    onConnect?: (ctx: HookContext<S>) => void | Promise<void>;
-    /** Called when a session disconnects. */
-    onDisconnect?: (ctx: HookContext<S>) => void | Promise<void>;
-    /** Called when an unhandled error occurs. */
-    onError?: (error: Error, ctx?: HookContext<S>) => void;
-    /** Called after a complete turn (all steps finished). */
-    onTurn?: (text: string, ctx: HookContext<S>) => void | Promise<void>;
-    /**
-     * Close the S2S connection after this many milliseconds of inactivity.
-     * Inactivity means no audio, transcripts, or tool calls in either direction.
-     * When the timeout fires the session is stopped and the client receives an
-     * `idle_timeout` event.
-     *
-     * Set to `0` or `Infinity` to disable.
-     *
-     * @defaultValue 300_000 (5 minutes)
-     */
-    idleTimeoutMs?: number;
-};
-/**
- * Default system prompt used when `instructions` is not provided.
- *
- * Optimized for voice-first interactions: short sentences, no visual
- * formatting, confident tone, and concise answers.
- */
-export declare const DEFAULT_INSTRUCTIONS: string;
-/** Default greeting spoken when a session starts. */
-export declare const DEFAULT_GREETING: string;
-/**
- * Agent definition returned by {@link defineAgent}.
- *
- * Core fields (`name`, `instructions`, `greeting`, `maxSteps`, `tools`)
- * are resolved to their final values with defaults applied. Optional
- * behavioral fields (hooks, `sttPrompt`, etc.) remain optional —
- * `undefined` means "not configured."
- *
- * @public
- */
-export type AgentDef<S = Record<string, unknown>> = {
-    name: string;
-    instructions: string;
-    greeting: string;
-    sttPrompt?: string;
-    maxSteps: number | ((ctx: HookContext<S>) => number);
-    toolChoice?: ToolChoice;
-    builtinTools?: readonly BuiltinTool[];
-    tools: Readonly<Record<string, ToolDef<z.ZodObject<z.ZodRawShape>, S>>>;
-    state?: () => S;
-    onConnect?: (ctx: HookContext<S>) => void | Promise<void>;
-    onDisconnect?: (ctx: HookContext<S>) => void | Promise<void>;
-    onError?: (error: Error, ctx?: HookContext<S>) => void;
-    onTurn?: (text: string, ctx: HookContext<S>) => void | Promise<void>;
-    idleTimeoutMs?: number;
-};
-/** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
-export declare const BuiltinToolSchema: z.ZodEnum<{
-    web_search: "web_search";
-    visit_webpage: "visit_webpage";
-    fetch_json: "fetch_json";
-    run_code: "run_code";
-}>;
-/** @internal Zod schema for {@link ToolChoice}. Exported for reuse in internal schemas. */
-export declare const ToolChoiceSchema: z.ZodUnion<readonly [z.ZodEnum<{
-    auto: "auto";
-    required: "required";
-    none: "none";
-}>, z.ZodObject<{
-    type: z.ZodLiteral<"tool">;
-    toolName: z.ZodString;
-}, z.core.$strip>]>;
-/**
- * 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}!`,
- *     },
- *   },
- * });
- * ```
- */
-export declare function defineAgent<S = Record<string, unknown>>(options: AgentOptions<S>): AgentDef<S>;