@alexkroman1/aai 0.9.3 → 0.10.1

package/dist/types.d.ts

@@ -5,12 +5,152 @@ import { z } from "zod";
 import type { Kv } from "./kv.ts";
 import type { VectorStore } from "./vector.ts";
 /**
- * Result of the {@link AgentOptions.onBeforeStep} hook.
+ * Result returned by a `beforeTurn` middleware to block a turn.
  * @public
  */
-export type BeforeStepResult = {
-    activeTools?: string[];
+export type MiddlewareBlockResult = {
+    block: true;
+    reason: string;
+};
+/**
+ * Result returned by a `beforeToolCall` middleware hook to short-circuit tool execution.
+ *
+ * Return `{ result: string }` to skip execution and use a cached/synthetic result.
+ * Return `{ block: true; reason: string }` to deny the tool call.
+ * Return `{ args: Record<string, unknown> }` to transform the arguments.
+ * Return `undefined` to proceed normally.
+ *
+ * @public
+ */
+export type ToolCallInterceptResult = {
+    result: string;
+} | {
+    block: true;
+    reason: string;
+} | {
+    args: Record<string, unknown>;
 } | undefined;
+/**
+ * Composable middleware for the agent lifecycle.
+ *
+ * Middleware can intercept turns, tool calls, and output at well-defined
+ * points. Multiple middleware compose in array order: the first middleware
+ * in the array runs first for "before" hooks and last for "after" hooks.
+ *
+ * ## Middleware Composition Order
+ *
+ * **"Before" hooks** run in array order (first middleware → last):
+ * `beforeInput` → `beforeTurn` → `beforeToolCall` → `beforeOutput`
+ *
+ * **"After" hooks** run in reverse array order (last middleware → first):
+ * `afterToolCall` → `afterTurn`
+ *
+ * ### Execution flow for a user turn
+ *
+ * ```
+ * User text arrives
+ *   │
+ *   ▼
+ * beforeInput  — transform/redact input text (piped through each middleware)
+ *   │
+ *   ▼
+ * beforeTurn   — block or allow the turn (short-circuits on first block)
+ *   │
+ *   ▼  (if not blocked)
+ * LLM reasoning + tool calls
+ *   │  ┌─ beforeToolCall (per call, short-circuits on block/result)
+ *   │  └─ afterToolCall  (per call, reverse order)
+ *   │
+ *   ▼
+ * beforeOutput — transform/redact LLM output text (piped through each middleware)
+ *   │
+ *   ▼
+ * afterTurn    — cleanup/logging (reverse order)
+ * ```
+ *
+ * ### Short-circuit behavior
+ *
+ * - **`beforeTurn`**: If *any* middleware returns `{ block: true, reason }`,
+ *   the turn is blocked and subsequent `beforeTurn` hooks do **not** run.
+ *   When a turn is blocked, `afterTurn` hooks do **not** fire (the turn
+ *   never started).
+ * - **`beforeToolCall`**: If *any* middleware blocks or returns a cached
+ *   result, subsequent `beforeToolCall` hooks do **not** run. Arg transforms
+ *   accumulate across middleware.
+ * - **`beforeInput`** / **`beforeOutput`**: These *always* run all middleware
+ *   in sequence (no short-circuit). Each receives the output of the previous.
+ *
+ * ### Ordering example
+ *
+ * ```ts
+ * middleware: [auditTrail, hipaaGuardrails]
+ * ```
+ * - `beforeInput`: auditTrail runs first, then hipaaGuardrails
+ * - `beforeTurn`: auditTrail runs first; if it blocks, hipaaGuardrails is skipped
+ * - `afterTurn`: hipaaGuardrails runs first (reverse), then auditTrail
+ *
+ * If you want the guardrail to run *before* the audit trail logs, place it
+ * first in the array: `[hipaaGuardrails, auditTrail]`.
+ *
+ * @typeParam S - The shape of per-session state. Defaults to `any` so that
+ *   reusable, state-agnostic middleware (e.g. loggers, rate-limiters) can be
+ *   authored without threading a state generic. Use an explicit generic
+ *   (`Middleware<MyState>`) when the middleware reads or writes session state.
+ *
+ * @public
+ */
+export type Middleware<S = any> = {
+    /** Human-readable name for logging and debugging. */
+    name: string;
+    /**
+     * Filters user input text before it reaches the LLM. Return the
+     * (possibly modified) text. Runs on every user transcript, before
+     * `beforeTurn`.
+     *
+     * Use this to redact PII (SSNs, emails, patient IDs) from speech
+     * transcripts so the LLM never sees sensitive data.
+     *
+     * Middleware is piped in array order: the output of one filter becomes
+     * the input of the next.
+     *
+     * @example
+     * ```ts
+     * beforeInput: (text) =>
+     *   text.replace(/\b\d{3}[-.]?\d{2}[-.]?\d{4}\b/g, "[SSN REDACTED]")
+     * ```
+     */
+    beforeInput?: (text: string, ctx: HookContext<S>) => string | Promise<string>;
+    /**
+     * Runs before each user turn. Can block the turn by returning
+     * `{ block: true, reason: "..." }`. Return `undefined` to proceed.
+     *
+     * Receives the text *after* `beforeInput` filtering has been applied.
+     *
+     * When a turn is blocked, subsequent `beforeTurn` middleware is skipped,
+     * and `afterTurn` hooks do **not** fire.
+     */
+    beforeTurn?: (text: string, ctx: HookContext<S>) => MiddlewareBlockResult | void | undefined | Promise<MiddlewareBlockResult | void | undefined>;
+    /**
+     * Runs after each user turn completes (after all steps finish).
+     * Runs in reverse array order.
+     */
+    afterTurn?: (text: string, ctx: HookContext<S>) => void | Promise<void>;
+    /**
+     * Runs before each tool call. Can approve, deny, transform args, or
+     * return a cached result.
+     */
+    beforeToolCall?: (toolName: string, args: Readonly<Record<string, unknown>>, ctx: HookContext<S>) => ToolCallInterceptResult | undefined | Promise<ToolCallInterceptResult | undefined>;
+    /**
+     * Runs after each tool call completes. Useful for caching results,
+     * logging, or analytics. Runs in reverse array order.
+     */
+    afterToolCall?: (toolName: string, args: Readonly<Record<string, unknown>>, result: string, ctx: HookContext<S>) => void | Promise<void>;
+    /**
+     * Filters agent text output before it is sent to TTS. Return the
+     * (possibly modified) text. Runs on every agent transcript chunk.
+     */
+    beforeOutput?: (text: string, ctx: HookContext<S>) => string | Promise<string>;
+};
 /**
  * Identifier for a built-in server-side tool.
  *
@@ -18,7 +158,7 @@ export type BeforeStepResult = {
  * 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 Markdown.
+ * - `"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.
  * - `"vector_search"` — Search the agent's RAG knowledge base for relevant documents.
@@ -34,6 +174,8 @@ export type BuiltinTool = "web_search" | "visit_webpage" | "fetch_json" | "run_c
  * - `"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";
@@ -90,6 +232,30 @@ export type ToolContext<S = Record<string, unknown>> = {
     vector: VectorStore;
     /** Read-only snapshot of conversation messages so far. */
     messages: readonly Message[];
+    /**
+     * Push an intermediate update to the client UI before the tool finishes.
+     *
+     * Use this to send progressive data so the UI can render partial results
+     * immediately (e.g. a loading card, preview, or streaming data) instead
+     * of waiting for the full tool result.
+     *
+     * The data is serialized to JSON and delivered as a `tool_call_update`
+     * event on the client. Use `useToolCallUpdate` in the UI to consume it.
+     *
+     * No-op in sandbox (platform) mode.
+     */
+    sendUpdate(data: unknown): void;
+    /**
+     * 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 (`onConnect`, `onTurn`, etc.).
@@ -102,7 +268,7 @@ export type ToolContext<S = Record<string, unknown>> = {
  *
  * @public
  */
-export type HookContext<S = Record<string, unknown>> = Omit<ToolContext<S>, "messages">;
+export type HookContext<S = Record<string, unknown>> = Omit<ToolContext<S>, "messages" | "sendUpdate">;
 /**
  * Definition of a custom tool that the agent can invoke.
  *
@@ -139,7 +305,7 @@ export type ToolDef<P extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawS
     /** Human-readable description shown to the LLM. */
     description: string;
     /** Zod schema for the tool's parameters. */
-    parameters?: P | undefined;
+    parameters?: P;
     /** Function that executes the tool and returns a result. */
     execute(args: z.infer<P>, ctx: ToolContext<S>): Promise<unknown> | unknown;
 };
@@ -148,18 +314,19 @@ export type ToolDef<P extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawS
  *
  * 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 `tool()`
- * lets TypeScript infer `P` from `parameters` and type `args` correctly.
+ * `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, tool } from "aai";
+ * import { defineAgent, defineTool } from "aai";
  * import { z } from "zod";
  *
  * export default defineAgent({
  *   name: "my-agent",
  *   tools: {
- *     greet: tool({
+ *     greet: defineTool({
  *       description: "Greet the user",
  *       parameters: z.object({ name: z.string() }),
  *       execute: ({ name }) => `Hello, ${name}!`, // name is string
@@ -170,7 +337,82 @@ export type ToolDef<P extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawS
  *
  * @public
  */
-export declare function tool<P extends z.ZodObject<z.ZodRawShape>, S = Record<string, unknown>>(def: ToolDef<P, S>): ToolDef<P, S>;
+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. `createToolFactory` eliminates
+ * that boilerplate by returning a `defineTool` variant that already knows `S`.
+ *
+ * @example
+ * ```ts
+ * import { createToolFactory, defineAgent } from "aai";
+ * import { z } from "zod";
+ *
+ * interface PortfolioState { holdings: Map<string, number> }
+ *
+ * const tool = createToolFactory<PortfolioState>();
+ *
+ * export default defineAgent<PortfolioState>({
+ *   name: "portfolio",
+ *   state: () => ({ holdings: new Map() }),
+ *   tools: {
+ *     buy: tool({
+ *       description: "Buy shares",
+ *       parameters: z.object({ symbol: z.string(), qty: z.number() }),
+ *       execute: (args, ctx) => {
+ *         // args.symbol is string, ctx.state is PortfolioState
+ *         ctx.state.holdings.set(args.symbol, args.qty);
+ *       },
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function createToolFactory<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;
 /**
  * Information about a completed agentic step, passed to the `onStep` hook.
  *
@@ -206,7 +448,6 @@ export type StepInfo = {
  * export default defineAgent({
  *   name: "research-bot",
  *   instructions: "You help users research topics.",
- *   voice: "orion",
  *   builtinTools: ["web_search"],
  *   tools: {
  *     summarize: {
@@ -240,17 +481,25 @@ export type AgentOptions<S = Record<string, unknown>> = {
     toolChoice?: ToolChoice;
     /** Built-in tools to enable (e.g. `"web_search"`, `"run_code"`). */
     builtinTools?: readonly BuiltinTool[];
-    /**
-     * Default set of active tools per turn.
-     *
-     * When set, only these tools are available to the LLM each turn.
-     * Can be overridden dynamically per-turn via `onBeforeStep`.
-     */
-    activeTools?: readonly string[];
     /** 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;
+    /**
+     * Enable automatic session state persistence across reconnects.
+     *
+     * When enabled, session state, conversation history, and the S2S session ID
+     * are saved to KV on disconnect and restored when the client reconnects with
+     * `?sessionId=<old-session-id>` in the WebSocket URL.
+     *
+     * - `true` — enable with default TTL (1 hour)
+     * - `{ ttl: number }` — enable with custom TTL in milliseconds
+     *
+     * Requires the agent's `state` return value to be JSON-serializable.
+     */
+    persistence?: boolean | {
+        ttl?: number;
+    };
     /** Called when a new session connects. */
     onConnect?: (ctx: HookContext<S>) => void | Promise<void>;
     /** Called when a session disconnects. */
@@ -262,12 +511,23 @@ export type AgentOptions<S = Record<string, unknown>> = {
     /** Called after each agentic step completes. */
     onStep?: (step: StepInfo, ctx: HookContext<S>) => void | Promise<void>;
     /**
-     * Called before each step; can restrict which tools are active.
+     * Composable middleware that intercepts turns, tool calls, and output.
      *
-     * Return `{ activeTools: [...] }` to limit available tools for the
-     * upcoming step, or `void` to keep all tools active.
+     * Middleware runs in array order for "before" hooks (first to last)
+     * and reverse order for "after" hooks (last to first).
      */
-    onBeforeStep?: (stepNumber: number, ctx: HookContext<S>) => BeforeStepResult | Promise<BeforeStepResult>;
+    middleware?: readonly Middleware<S>[];
+    /**
+     * 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.
@@ -279,30 +539,55 @@ export declare const DEFAULT_INSTRUCTIONS: string;
 /** Default greeting spoken when a session starts. */
 export declare const DEFAULT_GREETING: string;
 /**
- * Agent definition with all defaults applied, returned by
- * {@link defineAgent}.
+ * 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, middleware, `sttPrompt`, etc.) remain
+ * optional — `undefined` means "not configured."
  *
- * Unlike {@link AgentOptions}, every field here is resolved to its
- * final value — no optional fields with implicit defaults remain.
+ * @public
  */
-export type AgentDef = {
+export type AgentDef<S = Record<string, unknown>> = {
     name: string;
     instructions: string;
     greeting: string;
     sttPrompt?: string;
-    maxSteps: number | ((ctx: HookContext) => number);
+    maxSteps: number | ((ctx: HookContext<S>) => number);
     toolChoice?: ToolChoice;
     builtinTools?: readonly BuiltinTool[];
-    activeTools?: readonly string[];
-    tools: Readonly<Record<string, ToolDef>>;
-    state?: () => Record<string, unknown>;
-    onConnect?: AgentOptions["onConnect"];
-    onDisconnect?: AgentOptions["onDisconnect"];
-    onError?: AgentOptions["onError"];
-    onTurn?: AgentOptions["onTurn"];
-    onStep?: AgentOptions["onStep"];
-    onBeforeStep?: AgentOptions["onBeforeStep"];
+    tools: Readonly<Record<string, ToolDef<z.ZodObject<z.ZodRawShape>, S>>>;
+    state?: () => S;
+    /** Resolved persistence config, or `undefined` if disabled. */
+    persistence?: {
+        ttl: number;
+    };
+    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>;
+    onStep?: (step: StepInfo, ctx: HookContext<S>) => void | Promise<void>;
+    middleware?: readonly Middleware<S>[];
+    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";
+    vector_search: "vector_search";
+    memory: "memory";
+}>;
+/** @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.
  *
@@ -333,4 +618,4 @@ export type AgentDef = {
  * });
  * ```
  */
-export declare function defineAgent<S>(options: AgentOptions<S>): AgentDef;
+export declare function defineAgent<S = Record<string, unknown>>(options: AgentOptions<S>): AgentDef<S>;

package/dist/types.js

@@ -8,18 +8,19 @@ import { z } from "zod";
 *
 * 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 `tool()`
-* lets TypeScript infer `P` from `parameters` and type `args` correctly.
+* `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, tool } from "aai";
+* import { defineAgent, defineTool } from "aai";
 * import { z } from "zod";
 *
 * export default defineAgent({
 *   name: "my-agent",
 *   tools: {
-*     greet: tool({
+*     greet: defineTool({
 *       description: "Greet the user",
 *       parameters: z.object({ name: z.string() }),
 *       execute: ({ name }) => `Hello, ${name}!`, // name is string
@@ -30,10 +31,47 @@ import { z } from "zod";
 *
 * @public
 */
-function tool(def) {
+function defineTool(def) {
 	return def;
 }
 /**
+* Create a typed `defineTool` helper with the session state type baked in.
+*
+* When tools need access to typed session state, you'd normally have to write
+* verbose generics on every `defineTool` call. `createToolFactory` eliminates
+* that boilerplate by returning a `defineTool` variant that already knows `S`.
+*
+* @example
+* ```ts
+* import { createToolFactory, defineAgent } from "aai";
+* import { z } from "zod";
+*
+* interface PortfolioState { holdings: Map<string, number> }
+*
+* const tool = createToolFactory<PortfolioState>();
+*
+* export default defineAgent<PortfolioState>({
+*   name: "portfolio",
+*   state: () => ({ holdings: new Map() }),
+*   tools: {
+*     buy: tool({
+*       description: "Buy shares",
+*       parameters: z.object({ symbol: z.string(), qty: z.number() }),
+*       execute: (args, ctx) => {
+*         // args.symbol is string, ctx.state is PortfolioState
+*         ctx.state.holdings.set(args.symbol, args.qty);
+*       },
+*     }),
+*   },
+* });
+* ```
+*
+* @public
+*/
+function createToolFactory() {
+	return (def) => def;
+}
+/**
 * Default system prompt used when `instructions` is not provided.
 *
 * Optimized for voice-first interactions: short sentences, no visual
@@ -56,6 +94,7 @@ If you need to list items, say "First," "Next," and "Finally."
 - Never use exclamation points. Keep your tone calm and conversational.`;
 /** Default greeting spoken when a session starts. */
 const DEFAULT_GREETING = "Hey there. I'm a voice assistant. What can I help you with?";
+/** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
 const BuiltinToolSchema = z.enum([
 	"web_search",
 	"visit_webpage",
@@ -64,6 +103,7 @@ const BuiltinToolSchema = z.enum([
 	"vector_search",
 	"memory"
 ]);
+/** @internal Zod schema for {@link ToolChoice}. Exported for reuse in internal schemas. */
 const ToolChoiceSchema = z.union([z.enum([
 	"auto",
 	"required",
@@ -77,6 +117,8 @@ const ToolDefSchema = z.object({
 	parameters: z.custom((val) => val === void 0 || val instanceof z.ZodType, "Expected a Zod schema").optional(),
 	execute: z.function()
 });
+/** Default TTL for persisted session data: 1 hour. */
+const DEFAULT_PERSIST_TTL = 36e5;
 const AgentOptionsSchema = z.object({
 	name: z.string().min(1, "Agent name must be non-empty"),
 	instructions: z.string().optional(),
@@ -85,15 +127,24 @@ const AgentOptionsSchema = z.object({
 	maxSteps: z.union([z.number().int().positive(), z.function()]).optional(),
 	toolChoice: ToolChoiceSchema.optional(),
 	builtinTools: z.array(BuiltinToolSchema).optional(),
-	activeTools: z.array(z.string().min(1)).optional(),
 	tools: z.record(z.string(), ToolDefSchema).optional(),
 	state: z.function().optional(),
+	persistence: z.union([z.literal(true), z.object({ ttl: z.number().int().positive().optional() })]).optional(),
 	onConnect: z.function().optional(),
 	onDisconnect: z.function().optional(),
 	onError: z.function().optional(),
 	onTurn: z.function().optional(),
 	onStep: z.function().optional(),
-	onBeforeStep: z.function().optional()
+	middleware: z.array(z.object({
+		name: z.string().min(1, "Middleware name must be non-empty"),
+		beforeInput: z.function().optional(),
+		beforeTurn: z.function().optional(),
+		afterTurn: z.function().optional(),
+		beforeToolCall: z.function().optional(),
+		afterToolCall: z.function().optional(),
+		beforeOutput: z.function().optional()
+	})).optional(),
+	idleTimeoutMs: z.number().nonnegative().optional()
 });
 /**
 * Create an agent definition from the given options, applying sensible defaults.
@@ -127,13 +178,15 @@ const AgentOptionsSchema = z.object({
 */
 function defineAgent(options) {
 	AgentOptionsSchema.parse(options);
+	const persistence = options.persistence ? { ttl: typeof options.persistence === "object" ? options.persistence.ttl ?? DEFAULT_PERSIST_TTL : DEFAULT_PERSIST_TTL } : void 0;
 	return {
 		...options,
 		instructions: options.instructions ?? DEFAULT_INSTRUCTIONS,
 		greeting: options.greeting ?? "Hey there. I'm a voice assistant. What can I help you with?",
 		maxSteps: options.maxSteps ?? 5,
-		tools: options.tools ?? {}
+		tools: options.tools ?? {},
+		persistence
 	};
 }
 //#endregion
-export { DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, defineAgent, tool };
+export { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, createToolFactory, defineAgent, defineTool, defineTool as tool };

package/dist/vector.d.ts

@@ -1,6 +1,20 @@
 /**
- * Vector store interface and in-memory implementation.
+ * Vector store interface.
  */
+/**
+ * Validate a vector filter expression to prevent injection attacks.
+ *
+ * Rejects filters containing SQL keywords (SELECT, DROP, etc.),
+ * statement terminators, comments, and null bytes. Enforces a
+ * maximum length of 1000 characters.
+ *
+ * @param filter - The raw filter string from user input.
+ * @returns The validated filter string (trimmed).
+ * @throws Error if the filter contains dangerous patterns.
+ *
+ * @public
+ */
+export declare function validateVectorFilter(filter: string): string;
 /**
  * A single vector search result entry.
  *
@@ -63,27 +77,9 @@ export type VectorStore = {
         filter?: string;
     }): Promise<VectorEntry[]>;
     /**
-     * Remove entries by ID.
+     * Delete entries by ID.
      *
-     * @param ids - A single ID or array of IDs to remove.
+     * @param ids - A single ID or array of IDs to delete.
      */
-    remove(ids: string | string[]): Promise<void>;
+    delete(ids: string | string[]): Promise<void>;
 };
-/**
- * Create an in-memory vector store for testing and local development.
- *
- * Uses brute-force substring matching instead of real vector similarity.
- * Good enough for testing the plumbing but not for production use.
- *
- * @returns A {@link VectorStore} instance backed by in-memory storage.
- *
- * @example
- * ```ts
- * import { createMemoryVectorStore } from "aai";
- *
- * const vector = createMemoryVectorStore();
- * await vector.upsert("doc-1", "The capital of France is Paris.");
- * const results = await vector.query("France capital");
- * ```
- */
-export declare function createMemoryVectorStore(): VectorStore;