@alexkroman1/aai 0.4.0 → 0.6.0

package/dist/sdk/define_agent.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent definition factory.
+ *
+ * @module
+ */
+import { type AgentDef, type AgentOptions } from "./types.ts";
+/**
+ * Create an agent definition from the given options, applying sensible defaults.
+ *
+ * This is the main entry point for defining a voice agent. The returned
+ * {@linkcode AgentDef} is consumed by the AAI server at deploy time.
+ *
+ * @param options Configuration for the agent including name, instructions,
+ *   tools, hooks, and transport settings.
+ * @returns A fully resolved agent definition with all defaults applied.
+ *
+ * @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>(options: AgentOptions<S>): AgentDef;
+//# sourceMappingURL=define_agent.d.ts.map

package/dist/sdk/define_agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_agent.d.ts","sourceRoot":"","sources":["../../sdk/define_agent.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAEH,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,YAAY,EAIlB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,QAAQ,CA0BjE"}

package/dist/sdk/define_agent.js

@@ -0,0 +1,63 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Agent definition factory.
+ *
+ * @module
+ */
+import { DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, normalizeTransport, } from "./types.js";
+/**
+ * Create an agent definition from the given options, applying sensible defaults.
+ *
+ * This is the main entry point for defining a voice agent. The returned
+ * {@linkcode AgentDef} is consumed by the AAI server at deploy time.
+ *
+ * @param options Configuration for the agent including name, instructions,
+ *   tools, hooks, and transport settings.
+ * @returns A fully resolved agent definition with all defaults applied.
+ *
+ * @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 function defineAgent(options) {
+    // AgentDef erases the S generic (it's a runtime artifact consumed by the
+    // server which doesn't need the compile-time state type). The cast is safe
+    // because AgentDef's hooks/tools use the same shapes with `any`/`unknown`.
+    return {
+        name: options.name,
+        env: options.env ?? ["ASSEMBLYAI_API_KEY"],
+        transport: normalizeTransport(options.transport),
+        mode: options.mode ?? "s2s",
+        instructions: options.instructions ?? DEFAULT_INSTRUCTIONS,
+        greeting: options.greeting ?? DEFAULT_GREETING,
+        voice: options.voice ?? "",
+        ...(options.sttPrompt !== undefined && { sttPrompt: options.sttPrompt }),
+        maxSteps: options.maxSteps ?? 5,
+        ...(options.toolChoice !== undefined && { toolChoice: options.toolChoice }),
+        ...(options.builtinTools !== undefined && { builtinTools: options.builtinTools }),
+        ...(options.activeTools !== undefined && { activeTools: options.activeTools }),
+        tools: options.tools ?? {},
+        ...(options.state !== undefined && { state: options.state }),
+        ...(options.onConnect !== undefined && { onConnect: options.onConnect }),
+        ...(options.onDisconnect !== undefined && { onDisconnect: options.onDisconnect }),
+        ...(options.onError !== undefined && { onError: options.onError }),
+        ...(options.onTurn !== undefined && { onTurn: options.onTurn }),
+        ...(options.onStep !== undefined && { onStep: options.onStep }),
+        ...(options.onBeforeStep !== undefined && { onBeforeStep: options.onBeforeStep }),
+    };
+}
+//# sourceMappingURL=define_agent.js.map

package/dist/sdk/define_agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_agent.js","sourceRoot":"","sources":["../../sdk/define_agent.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C;;;;GAIG;AAEH,OAAO,EAGL,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,WAAW,CAAI,OAAwB;IACrD,yEAAyE;IACzE,2EAA2E;IAC3E,2EAA2E;IAC3E,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,oBAAoB,CAAC;QAC1C,SAAS,EAAE,kBAAkB,CAAC,OAAO,CAAC,SAAS,CAAC;QAChD,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK;QAC3B,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,oBAAoB;QAC1D,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,gBAAgB;QAC9C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;QAC1B,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;QACxE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC;QAC/B,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3E,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;QACjF,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAC9E,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;QAC1B,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAC5D,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;QACxE,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;QACjF,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QAClE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC/D,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QAC/D,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;KACtE,CAAC;AAChB,CAAC"}

package/dist/sdk/direct_executor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ *
+ * @module
+ */
+import { type AgentConfig, type ToolSchema } from "./_internal_types.ts";
+import type { Kv } from "./kv.ts";
+import type { ClientSink } from "./protocol.ts";
+import type { Logger, Metrics, S2SConfig } from "./runtime.ts";
+import type { CreateS2sWebSocket } from "./s2s.ts";
+import { type HookInvoker, type Session } from "./session.ts";
+import type { AgentDef } from "./types.ts";
+import type { ExecuteTool } from "./worker_entry.ts";
+export type DirectExecutorOptions = {
+    agent: AgentDef;
+    env: Record<string, string>;
+    kv?: Kv | undefined;
+    vectorSearch?: ((query: string, topK: number) => Promise<string>) | undefined;
+    createWebSocket?: CreateS2sWebSocket | undefined;
+    logger?: Logger | undefined;
+    metrics?: Metrics | undefined;
+    s2sConfig?: S2SConfig | undefined;
+};
+export type DirectExecutor = {
+    executeTool: ExecuteTool;
+    hookInvoker: HookInvoker;
+    toolSchemas: ToolSchema[];
+    createSession(opts: {
+        id: string;
+        agent: string;
+        client: ClientSink;
+        skipGreeting?: boolean;
+    }): 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. */
+export declare function createDirectExecutor(opts: DirectExecutorOptions): DirectExecutor;
+//# sourceMappingURL=direct_executor.d.ts.map

package/dist/sdk/direct_executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct_executor.d.ts","sourceRoot":"","sources":["../../sdk/direct_executor.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAuB,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAE9F,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,EAAE,CAAC,EAAE,EAAE,GAAG,SAAS,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAC9E,eAAe,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,aAAa,CAAC,IAAI,EAAE;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,UAAU,CAAC;QACnB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,GAAG,OAAO,CAAC;CACb,CAAC;AAEF,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAa7D;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,cAAc,CAmIhF"}

package/dist/sdk/direct_executor.js

@@ -0,0 +1,143 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * 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.
+ *
+ * @module
+ */
+import { agentToolsToSchemas } from "./_internal_types.js";
+import { getBuiltinToolDefs, getBuiltinToolSchemas } from "./builtin_tools.js";
+import { createMemoryKv } from "./kv.js";
+import { consoleLogger, DEFAULT_S2S_CONFIG, noopMetrics } from "./runtime.js";
+import { createS2sSession } from "./session.js";
+import { executeToolCall } from "./worker_entry.js";
+/** Build a serializable AgentConfig from an AgentDef. */
+export function buildAgentConfig(agent) {
+    const config = {
+        name: agent.name,
+        instructions: agent.instructions,
+        greeting: agent.greeting,
+        voice: agent.voice,
+    };
+    if (agent.sttPrompt !== undefined)
+        config.sttPrompt = agent.sttPrompt;
+    if (typeof agent.maxSteps !== "function")
+        config.maxSteps = agent.maxSteps;
+    if (agent.toolChoice !== undefined)
+        config.toolChoice = agent.toolChoice;
+    if (agent.builtinTools)
+        config.builtinTools = [...agent.builtinTools];
+    if (agent.activeTools)
+        config.activeTools = [...agent.activeTools];
+    return config;
+}
+/** Create a direct (in-process) tool executor and hook invoker for an agent. */
+export function createDirectExecutor(opts) {
+    const { agent, env, kv = createMemoryKv(), vectorSearch, createWebSocket, logger = consoleLogger, metrics = noopMetrics, s2sConfig = DEFAULT_S2S_CONFIG, } = opts;
+    const agentConfig = buildAgentConfig(agent);
+    // Merge custom + builtin tool definitions
+    const builtinDefs = getBuiltinToolDefs(agent.builtinTools ?? [], vectorSearch ? { vectorSearch } : undefined);
+    const allTools = {
+        ...builtinDefs,
+        ...agent.tools,
+    };
+    // Build tool schemas for the S2S API
+    const customSchemas = agentToolsToSchemas(agent.tools ?? {});
+    const builtinSchemas = getBuiltinToolSchemas(agent.builtinTools ?? []);
+    const toolSchemas = [...customSchemas, ...builtinSchemas];
+    // Per-session mutable state
+    const sessionState = new Map();
+    const frozenEnv = Object.freeze({ ...env });
+    function getState(sessionId) {
+        if (!sessionState.has(sessionId) && agent.state) {
+            sessionState.set(sessionId, agent.state());
+        }
+        return sessionState.get(sessionId) ?? {};
+    }
+    function makeHookContext(sessionId) {
+        return {
+            sessionId,
+            env: frozenEnv,
+            state: getState(sessionId),
+            get kv() {
+                return kv;
+            },
+        };
+    }
+    const executeTool = async (name, args, sessionId, messages) => {
+        const tool = allTools[name];
+        if (!tool)
+            return JSON.stringify({ error: `Unknown tool: ${name}` });
+        return executeToolCall(name, args, {
+            tool,
+            env: frozenEnv,
+            sessionId,
+            state: getState(sessionId ?? ""),
+            kv,
+            messages,
+        });
+    };
+    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);
+            let maxSteps;
+            let activeTools;
+            if (typeof agent.maxSteps === "function") {
+                maxSteps = (await agent.maxSteps(ctx)) ?? undefined;
+            }
+            if (agent.onBeforeStep) {
+                const result = await agent.onBeforeStep(0, ctx);
+                activeTools = result?.activeTools;
+            }
+            if (maxSteps === undefined && activeTools === undefined)
+                return null;
+            const config = {};
+            if (maxSteps !== undefined)
+                config.maxSteps = maxSteps;
+            if (activeTools !== undefined)
+                config.activeTools = activeTools;
+            return config;
+        },
+    };
+    function createSession(sessionOpts) {
+        if (!createWebSocket) {
+            throw new Error("createWebSocket not provided — pass it in DirectExecutorOptions");
+        }
+        const apiKey = frozenEnv.ASSEMBLYAI_API_KEY ?? "";
+        return createS2sSession({
+            id: sessionOpts.id,
+            agent: sessionOpts.agent,
+            client: sessionOpts.client,
+            agentConfig,
+            toolSchemas,
+            apiKey,
+            s2sConfig,
+            executeTool,
+            createWebSocket,
+            hookInvoker,
+            skipGreeting: sessionOpts.skipGreeting ?? false,
+            logger,
+            metrics,
+        });
+    }
+    return { executeTool, hookInvoker, toolSchemas, createSession };
+}
+//# sourceMappingURL=direct_executor.js.map

package/dist/sdk/direct_executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct_executor.js","sourceRoot":"","sources":["../../sdk/direct_executor.ts"],"names":[],"mappings":"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"}

package/dist/sdk/kv.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Key-value storage interface and in-memory implementation.
+ *
+ * @module
+ */
+/**
+ * A single key-value entry returned by {@linkcode Kv.list}.
+ *
+ * @typeParam T The type of the stored value. Defaults to `unknown`.
+ */
+export type KvEntry<T = unknown> = {
+    /** The key under which the value is stored. */
+    key: string;
+    /** The deserialized value. */
+    value: T;
+};
+/**
+ * Options for listing keys from the KV store.
+ *
+ * Used with {@linkcode Kv.list} to control result ordering and pagination.
+ */
+export type KvListOptions = {
+    /** Maximum number of entries to return. */
+    limit?: number;
+    /** Return entries in reverse key order. */
+    reverse?: boolean;
+};
+/**
+ * Async key-value store interface used by agents.
+ *
+ * Agents access the KV store via {@linkcode ToolContext.kv} or
+ * {@linkcode HookContext.kv}. Values are JSON-serialized and stored as
+ * strings with an optional TTL.
+ *
+ * @example
+ * ```ts
+ * // Inside a tool execute function:
+ * const myTool = {
+ *   description: "Save and retrieve data",
+ *   execute: async (_args: unknown, ctx: { kv: Kv }) => {
+ *     await ctx.kv.set("user:name", "Alice", { expireIn: 60_000 });
+ *     const name = await ctx.kv.get<string>("user:name");
+ *     return name; // "Alice"
+ *   },
+ * };
+ * ```
+ */
+export type Kv = {
+    /**
+     * Get a value by key, or `null` if not found.
+     *
+     * @typeParam T The expected type of the stored value.
+     * @param key The key to look up.
+     * @returns The deserialized value, or `null` if the key does not exist
+     *   or has expired.
+     */
+    get<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Set a value, optionally with a TTL in milliseconds.
+     *
+     * @param key The key to store the value under.
+     * @param value The value to store. Must be JSON-serializable.
+     * @param options Optional settings.
+     * @param options.expireIn Time-to-live in milliseconds. The entry is
+     *   automatically removed after this duration.
+     * @throws {Error} If the serialized value exceeds 65,536 bytes.
+     */
+    set(key: string, value: unknown, options?: {
+        expireIn?: number;
+    }): Promise<void>;
+    /**
+     * Delete a key.
+     *
+     * @param key The key to remove. No-op if the key does not exist.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * List entries whose keys start with the given prefix.
+     *
+     * Results are sorted by key in ascending lexicographic order by default.
+     *
+     * @typeParam T The expected type of the stored values.
+     * @param prefix Key prefix to filter by. Use `""` to list all entries.
+     * @param options Optional pagination and ordering settings.
+     * @returns An array of matching {@linkcode KvEntry} objects.
+     */
+    list<T = unknown>(prefix: string, options?: KvListOptions): Promise<KvEntry<T>[]>;
+};
+export declare const MAX_VALUE_SIZE = 65536;
+/** 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[];
+/**
+ * Create an in-memory KV store (useful for testing and local development).
+ *
+ * Data is stored in a plain `Map` and does not persist across restarts.
+ * TTL expiration is checked lazily on reads and list operations.
+ *
+ * @returns A {@linkcode Kv} instance backed by in-memory storage.
+ *
+ * @example
+ * ```ts
+ * import { createMemoryKv } from "./kv.ts";
+ *
+ * const kv = createMemoryKv();
+ * await kv.set("greeting", "hello");
+ * const value = await kv.get<string>("greeting"); // "hello"
+ * ```
+ *
+ * @example With TTL
+ * ```ts
+ * import { createMemoryKv } from "./kv.ts";
+ *
+ * const kv = createMemoryKv();
+ * await kv.set("temp", "expires soon", { expireIn: 5000 });
+ * ```
+ */
+export declare function createMemoryKv(): Kv;
+//# sourceMappingURL=kv.d.ts.map

package/dist/sdk/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../sdk/kv.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,OAAO,IAAI;IACjC,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,KAAK,EAAE,CAAC,CAAC;CACV,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,EAAE,GAAG;IACf;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACjD;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;;;;;;;OASG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;CACnF,CAAC;AAEF,eAAO,MAAM,cAAc,QAAS,CAAC;AAErC,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EACvD,OAAO,EAAE,CAAC,EAAE,EACZ,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,CAAC,EAAE,CAOL;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,IAAI,EAAE,CAmDnC"}

package/dist/sdk/kv.js

@@ -0,0 +1,91 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Key-value storage interface and in-memory implementation.
+ *
+ * @module
+ */
+export const MAX_VALUE_SIZE = 65_536;
+/** Sort entries by key and apply reverse/limit options. Mutates the array. */
+export function sortAndPaginate(entries, options) {
+    entries.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    if (options?.reverse)
+        entries.reverse();
+    if (options?.limit && options.limit > 0) {
+        entries.length = Math.min(entries.length, options.limit);
+    }
+    return entries;
+}
+/**
+ * Create an in-memory KV store (useful for testing and local development).
+ *
+ * Data is stored in a plain `Map` and does not persist across restarts.
+ * TTL expiration is checked lazily on reads and list operations.
+ *
+ * @returns A {@linkcode Kv} instance backed by in-memory storage.
+ *
+ * @example
+ * ```ts
+ * import { createMemoryKv } from "./kv.ts";
+ *
+ * const kv = createMemoryKv();
+ * await kv.set("greeting", "hello");
+ * const value = await kv.get<string>("greeting"); // "hello"
+ * ```
+ *
+ * @example With TTL
+ * ```ts
+ * import { createMemoryKv } from "./kv.ts";
+ *
+ * const kv = createMemoryKv();
+ * await kv.set("temp", "expires soon", { expireIn: 5000 });
+ * ```
+ */
+export function createMemoryKv() {
+    const store = new Map();
+    function isExpired(entry) {
+        return entry.expiresAt !== undefined && entry.expiresAt <= Date.now();
+    }
+    return {
+        get(key) {
+            const entry = store.get(key);
+            if (!entry || isExpired(entry)) {
+                if (entry)
+                    store.delete(key);
+                return Promise.resolve(null);
+            }
+            return Promise.resolve(JSON.parse(entry.raw));
+        },
+        set(key, value, options) {
+            const raw = JSON.stringify(value);
+            if (raw.length > MAX_VALUE_SIZE) {
+                throw new Error(`Value exceeds max size of ${MAX_VALUE_SIZE} bytes`);
+            }
+            const expireIn = options?.expireIn;
+            const entry = { raw };
+            if (expireIn && expireIn > 0) {
+                entry.expiresAt = Date.now() + expireIn;
+            }
+            store.set(key, entry);
+            return Promise.resolve();
+        },
+        delete(key) {
+            store.delete(key);
+            return Promise.resolve();
+        },
+        list(prefix, options) {
+            const now = Date.now();
+            const entries = [];
+            for (const [key, entry] of store) {
+                if (entry.expiresAt && entry.expiresAt <= now) {
+                    store.delete(key);
+                    continue;
+                }
+                if (key.startsWith(prefix)) {
+                    entries.push({ key, value: JSON.parse(entry.raw) });
+                }
+            }
+            return Promise.resolve(sortAndPaginate(entries, options));
+        },
+    };
+}
+//# sourceMappingURL=kv.js.map

package/dist/sdk/kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../sdk/kv.ts"],"names":[],"mappings":"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"}

package/{sdk/mod.ts → dist/sdk/mod.d.ts}

@@ -1,4 +1,3 @@
-// Copyright 2025 the AAI authors. MIT license.
 /**
  * AAI SDK — build voice agents powered by STT, LLM, and TTS.
  *
@@ -22,14 +21,6 @@
  *
  * @module
  */
-
 export { defineAgent } from "./define_agent.ts";
-export type {
-  AgentOptions,
-  BeforeStepResult,
-  HookContext,
-  Message,
-  PipelineMode,
-  ToolContext,
-  ToolDef,
-} from "./types.ts";
+export type { AgentOptions, BeforeStepResult, HookContext, Message, PipelineMode, ToolContext, ToolDef, } from "./types.ts";
+//# sourceMappingURL=mod.d.ts.map

package/dist/sdk/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../sdk/mod.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,OAAO,EACP,YAAY,EACZ,WAAW,EACX,OAAO,GACR,MAAM,YAAY,CAAC"}

package/dist/sdk/mod.js

@@ -0,0 +1,26 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * AAI SDK — build voice agents powered by STT, LLM, and TTS.
+ *
+ * @example
+ * ```ts
+ * import { defineAgent } from "aai";
+ * import { z } from "zod";
+ *
+ * export default defineAgent({
+ *   name: "my-agent",
+ *   instructions: "You are a helpful voice assistant.",
+ *   tools: {
+ *     greet: {
+ *       description: "Greet the user by name",
+ *       parameters: z.object({ name: z.string() }),
+ *       execute: ({ name }) => `Hello, ${name}!`,
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @module
+ */
+export { defineAgent } from "./define_agent.js";
+//# sourceMappingURL=mod.js.map

package/dist/sdk/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../sdk/mod.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}