@alexkroman1/aai 0.10.3 → 0.10.4

package/dist/types.js

@@ -1,2 +1,176 @@
-import { a as createToolFactory, i as ToolChoiceSchema, n as DEFAULT_GREETING, o as defineAgent, r as DEFAULT_INSTRUCTIONS, s as defineTool, t as BuiltinToolSchema } from "./types-D8ZBxTL_.js";
-export { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, createToolFactory, defineAgent, defineTool, defineTool as tool };
+import { z } from "zod";
+//#region types.ts
+/**
+* Core type definitions for the AAI agent SDK.
+*/
+/**
+* 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
+*/
+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. `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
+*/
+function defineToolFactory() {
+	return (def) => def;
+}
+/**
+* Default system prompt used when `instructions` is not provided.
+*
+* Optimized for voice-first interactions: short sentences, no visual
+* formatting, confident tone, and concise answers.
+*/
+const DEFAULT_INSTRUCTIONS = `\
+You are AAI, a helpful AI assistant.
+
+Voice-First Rules:
+- Optimize for natural speech. Avoid jargon unless central to the answer. \
+Use short, punchy sentences.
+- Never mention "search results," "sources," or "the provided text." \
+Speak as if the knowledge is your own.
+- No visual formatting. Do not say "bullet point," "bold," or "bracketed one." \
+If you need to list items, say "First," "Next," and "Finally."
+- Start with the most important information. No introductory filler.
+- Be concise. Keep answers to 1-3 sentences. For complex topics, provide a high-level summary.
+- Be confident. Avoid hedging phrases like "It seems that" or "I believe."
+- If you don't have enough information, say so directly rather than guessing.
+- 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",
+	"fetch_json",
+	"run_code",
+	"memory"
+]);
+/** @internal Zod schema for {@link ToolChoice}. Exported for reuse in internal schemas. */
+const ToolChoiceSchema = z.union([z.enum([
+	"auto",
+	"required",
+	"none"
+]), z.object({
+	type: z.literal("tool"),
+	toolName: z.string().min(1)
+})]);
+const ToolDefSchema = z.object({
+	description: z.string().min(1, "Tool description must be non-empty"),
+	parameters: z.custom((val) => val === void 0 || val instanceof z.ZodType, "Expected a Zod schema").optional(),
+	execute: z.function()
+});
+const AgentOptionsSchema = z.object({
+	name: z.string().min(1, "Agent name must be non-empty"),
+	instructions: z.string().optional(),
+	greeting: z.string().optional(),
+	sttPrompt: z.string().optional(),
+	maxSteps: z.union([z.number().int().positive(), z.function()]).optional(),
+	toolChoice: ToolChoiceSchema.optional(),
+	builtinTools: z.array(BuiltinToolSchema).optional(),
+	tools: z.record(z.string(), ToolDefSchema).optional(),
+	state: z.function().optional(),
+	onConnect: z.function().optional(),
+	onDisconnect: z.function().optional(),
+	onError: z.function().optional(),
+	onTurn: z.function().optional(),
+	idleTimeoutMs: z.number().nonnegative().optional()
+});
+/**
+* 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}!`,
+*     },
+*   },
+* });
+* ```
+*/
+function defineAgent(options) {
+	AgentOptionsSchema.parse(options);
+	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 ?? {}
+	};
+}
+//#endregion
+export { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, defineAgent, defineTool, defineTool as tool, defineToolFactory };

package/dist/types.test-d.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type-level tests for the public API surface of @alexkroman1/aai.
+ *
+ * These are checked by tsc (via vitest typecheck) but never executed.
+ * A failure here means a public type contract has regressed.
+ */
+export {};

package/dist/vite-plugin.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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/vite-plugin.js

@@ -0,0 +1,82 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+//#region 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
+			});
+			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/ws-handler.d.ts

@@ -40,8 +40,7 @@ export type WsSessionOptions = {
     logger?: Logger;
     /** Timeout in ms for session.start(). Defaults to 10 000 (10s). */
     sessionStartTimeoutMs?: number;
-    /** Old session ID to resume from. When set, the persisted session data
-     *  (state, messages, S2S session ID) is restored from KV. */
+    /** Old session ID to resume. When set, reuses this ID instead of generating a new UUID. */
     resumeFrom?: string;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "type": "module",
   "files": [
     "dist"
@@ -11,6 +11,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./server": {
+      "source": "./server.ts",
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
     "./types": {
       "source": "./types.ts",
       "types": "./dist/types.d.ts",
@@ -21,10 +26,10 @@
       "types": "./dist/kv.d.ts",
       "import": "./dist/kv.js"
     },
-    "./vector": {
-      "source": "./vector.ts",
-      "types": "./dist/vector.d.ts",
-      "import": "./dist/vector.js"
+    "./protocol": {
+      "source": "./protocol.ts",
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
     },
     "./testing": {
       "source": "./testing.ts",
@@ -36,115 +41,50 @@
       "types": "./dist/matchers.d.ts",
       "import": "./dist/matchers.js"
     },
-    "./server": {
-      "source": "./server.ts",
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
-    "./protocol": {
-      "source": "./protocol.ts",
-      "types": "./dist/protocol.d.ts",
-      "import": "./dist/protocol.js"
+    "./internal": {
+      "source": "./internal.ts",
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     },
-    "./s2s": {
-      "source": "./s2s.ts",
-      "types": "./dist/s2s.d.ts",
-      "import": "./dist/s2s.js"
-    },
-    "./session": {
-      "source": "./session.ts",
-      "types": "./dist/session.d.ts",
-      "import": "./dist/session.js"
-    },
-    "./internal-types": {
-      "source": "./_internal-types.ts",
-      "types": "./dist/_internal-types.d.ts",
-      "import": "./dist/_internal-types.js"
-    },
-    "./runtime": {
-      "source": "./runtime.ts",
-      "types": "./dist/runtime.d.ts",
-      "import": "./dist/runtime.js"
-    },
-    "./worker-entry": {
-      "source": "./worker-entry.ts",
-      "types": "./dist/worker-entry.d.ts",
-      "import": "./dist/worker-entry.js"
-    },
-    "./ws-handler": {
-      "source": "./ws-handler.ts",
-      "types": "./dist/ws-handler.d.ts",
-      "import": "./dist/ws-handler.js"
-    },
-    "./telemetry": {
-      "source": "./telemetry.ts",
-      "types": "./dist/telemetry.d.ts",
-      "import": "./dist/telemetry.js"
+    "./hooks": {
+      "source": "./hooks.ts",
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js"
     },
     "./utils": {
       "source": "./_utils.ts",
       "types": "./dist/_utils.d.ts",
       "import": "./dist/_utils.js"
     },
-    "./ssrf": {
-      "source": "./_ssrf.ts",
-      "types": "./dist/_ssrf.d.ts",
-      "import": "./dist/_ssrf.js"
-    },
-    "./middleware-core": {
-      "source": "./middleware-core.ts",
-      "types": "./dist/middleware-core.d.ts",
-      "import": "./dist/middleware-core.js"
-    },
-    "./unstorage-kv": {
-      "source": "./unstorage-kv.ts",
-      "types": "./dist/unstorage-kv.d.ts",
-      "import": "./dist/unstorage-kv.js"
-    },
-    "./unstorage-vector": {
-      "source": "./unstorage-vector.ts",
-      "types": "./dist/unstorage-vector.d.ts",
-      "import": "./dist/unstorage-vector.js"
+    "./vite-plugin": {
+      "source": "./vite-plugin.ts",
+      "types": "./dist/vite-plugin.d.ts",
+      "import": "./dist/vite-plugin.js"
     }
   },
   "dependencies": {
-    "@huggingface/transformers": "^3.8.1",
-    "html-to-text": "^9.0.5",
+    "hookable": "^6.1.0",
     "nanoevents": "^9.1.0",
+    "p-timeout": "^7.0.1",
     "secure-exec": "^0.1.0",
     "unstorage": "^1.17.5",
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@hono/node-server": "^1.19.11",
-    "@hono/node-ws": "^1.3.0",
-    "@opentelemetry/api": "^1.9.1",
-    "hono": "^4.12.9",
     "vitest": "^4.1.1"
   },
   "peerDependenciesMeta": {
-    "@hono/node-server": {
-      "optional": true
-    },
-    "@hono/node-ws": {
-      "optional": true
-    },
-    "@opentelemetry/api": {
-      "optional": true
-    },
-    "hono": {
-      "optional": true
-    },
     "vitest": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@types/html-to-text": "^9.0.4",
     "@types/json-schema": "^7.0.15",
+    "@types/node": "^25.5.0",
     "@types/ws": "^8.18.1",
-    "tsdown": "^0.21.5"
+    "tsdown": "^0.21.5",
+    "vite": "^8.0.3"
   },
   "engines": {
     "node": ">=22.6"
@@ -158,7 +98,7 @@
     "build": "tsdown && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
-    "check:api": "api-extractor run -c api-extractor.json",
+    "check:publint": "publint",
     "check:attw": "attw --pack --profile esm-only"
   }
 }

package/dist/_embeddings.d.ts

@@ -1,31 +0,0 @@
-/**
- * Shared embedding helpers for vector stores.
- *
- * Provides local embedding via `all-MiniLM-L6-v2` (384 dims),
- * a deterministic test embedding function, and cosine similarity.
- */
-/** Function that converts text into an embedding vector. */
-export type EmbedFn = (text: string) => Promise<number[]>;
-export declare const DEFAULT_DIMENSIONS = 384;
-/**
- * Create a local embedding function using `all-MiniLM-L6-v2`.
- *
- * The model is downloaded on first use (~86 MB) and cached locally.
- * Subsequent calls load from cache in ~90ms. Each embedding takes <2ms.
- */
-export declare function createLocalEmbedFn(cacheDir: string): EmbedFn;
-/**
- * Create a deterministic hash-based embedding function for testing.
- *
- * Produces repeatable vectors where similar text yields similar embeddings.
- * Not suitable for production — use the default local model instead.
- *
- * @param dimensions - Vector dimensions (default: 384).
- */
-export declare function createTestEmbedFn(dimensions?: number): EmbedFn;
-/** Cosine similarity between two Float32Array vectors. */
-export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
-/** Encode an embedding as a base64 string. */
-export declare function encodeEmbedding(vec: Float32Array | number[]): string;
-/** Decode a base64 string back to a Float32Array embedding. */
-export declare function decodeEmbedding(b64: string): Float32Array;

package/dist/_internal-types-IfPcaJd5.js

@@ -1,61 +0,0 @@
-import { i as ToolChoiceSchema, t as BuiltinToolSchema } from "./types-D8ZBxTL_.js";
-import { z } from "zod";
-//#region _internal-types.ts
-/**
-* Zod schema for serializable agent configuration sent over the wire.
-*
-* This is the JSON-safe subset of the agent definition that can be
-* transmitted between the worker and the host process via structured clone.
-*/
-const AgentConfigSchema = z.object({
-	name: z.string().min(1),
-	instructions: z.string(),
-	greeting: z.string(),
-	sttPrompt: z.string().optional(),
-	maxSteps: z.number().int().positive().optional(),
-	toolChoice: ToolChoiceSchema.optional(),
-	builtinTools: z.array(BuiltinToolSchema).readonly().optional(),
-	idleTimeoutMs: z.number().nonnegative().optional()
-});
-/** Extract the serializable {@link AgentConfig} subset from a source object. */
-function toAgentConfig(src) {
-	const config = {
-		name: src.name,
-		instructions: src.instructions,
-		greeting: src.greeting
-	};
-	if (src.sttPrompt !== void 0) config.sttPrompt = src.sttPrompt;
-	if (typeof src.maxSteps !== "function" && src.maxSteps !== void 0) config.maxSteps = src.maxSteps;
-	if (src.toolChoice !== void 0) config.toolChoice = src.toolChoice;
-	if (src.builtinTools) config.builtinTools = [...src.builtinTools];
-	if (src.idleTimeoutMs !== void 0) config.idleTimeoutMs = src.idleTimeoutMs;
-	return config;
-}
-/**
-* Zod schema for serialized tool definitions sent over the wire.
-*
-* `parameters` must be a valid JSON Schema object (with `type`, `properties`,
-* etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
-*/
-const ToolSchemaSchema = z.object({
-	name: z.string().min(1),
-	description: z.string().min(1),
-	parameters: z.record(z.string(), z.unknown())
-});
-/** Empty Zod object schema used as default when tools have no parameters. */
-const EMPTY_PARAMS = z.object({});
-/**
-* Convert agent tool definitions to JSON Schema format for wire transport.
-*
-* Transforms the Zod-based `parameters` of each tool into a plain JSON Schema
-* object suitable for structured clone / JSON serialization.
-*/
-function agentToolsToSchemas(tools) {
-	return Object.entries(tools).map(([name, def]) => ({
-		name,
-		description: def.description,
-		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
-	}));
-}
-//#endregion
-export { toAgentConfig as a, agentToolsToSchemas as i, EMPTY_PARAMS as n, ToolSchemaSchema as r, AgentConfigSchema as t };

package/dist/_internal-types.js

@@ -1,2 +0,0 @@
-import { a as toAgentConfig, i as agentToolsToSchemas, n as EMPTY_PARAMS, r as ToolSchemaSchema, t as AgentConfigSchema } from "./_internal-types-IfPcaJd5.js";
-export { AgentConfigSchema, EMPTY_PARAMS, ToolSchemaSchema, agentToolsToSchemas, toAgentConfig };

package/dist/_session-ctx.d.ts

@@ -1,73 +0,0 @@
-/**
- * Session context builder.
- *
- * Extracted from session.ts to keep it under the file-length lint limit.
- * Builds the shared mutable state object threaded through all session helpers.
- */
-import type { AgentConfig } from "./_internal-types.ts";
-import type { HookInvoker } from "./middleware.ts";
-import type { ClientSink } from "./protocol.ts";
-import type { Logger } from "./runtime.ts";
-import type { S2sHandle } from "./s2s.ts";
-import type { Message } from "./types.ts";
-import type { ExecuteTool } from "./worker-entry.ts";
-type PendingTool = {
-    callId: string;
-    result: string;
-};
-/**
- * Mutable state and dependencies shared across session helper functions.
- *
- * Created once per session by `buildCtx` and threaded through `setupListeners`,
- * `handleToolCall`, and other internal helpers. Contains both immutable
- * dependencies (logger, executor) and mutable per-turn state (pending tools,
- * generation counters).
- */
-export type S2sSessionCtx = {
-    readonly id: string;
-    readonly agent: string;
-    readonly client: ClientSink;
-    readonly agentConfig: AgentConfig;
-    readonly executeTool: ExecuteTool;
-    readonly hookInvoker: HookInvoker | undefined;
-    readonly log: Logger;
-    s2s: S2sHandle | null;
-    pendingTools: PendingTool[];
-    toolCallCount: number;
-    turnPromise: Promise<void> | null;
-    conversationMessages: Message[];
-    /** Maximum number of messages to retain in conversationMessages. */
-    readonly maxHistory: number;
-    /** The `reply_id` from the most recent `reply.started` event. Tool calls
-     *  capture this at start; finishToolCall only pushes to pendingTools if the
-     *  reply ID still matches, preventing stale results from interrupted replies
-     *  from leaking into subsequent replies. Set to `null` on close/reset. */
-    currentReplyId: string | null;
-    /** Resolve per-turn configuration (dynamic `maxSteps`). */
-    resolveTurnConfig(): Promise<{
-        maxSteps?: number;
-    } | null>;
-    /** Increment the tool call counter and check whether the call should be refused. */
-    consumeToolCallStep(turnConfig: {
-        maxSteps?: number;
-    } | null, name: string, replyId: string | null): string | null;
-    /** Fire a lifecycle hook asynchronously. Errors are logged but never propagated. */
-    fireHook(name: string, fn: (h: HookInvoker) => Promise<void>): void;
-    /** Await all in-flight hook promises. Used during shutdown. */
-    drainHooks(): Promise<void>;
-    /** Push one or more messages and trim to maxHistory. */
-    pushMessages(...msgs: Message[]): void;
-    /** Sequential promise chain for filterOutput calls, ensuring ordering. */
-    filterChain: Promise<void>;
-};
-export declare function buildCtx(opts: {
-    id: string;
-    agent: string;
-    client: ClientSink;
-    agentConfig: AgentConfig;
-    executeTool: ExecuteTool;
-    hookInvoker: HookInvoker | undefined;
-    log: Logger;
-    maxHistory?: number | undefined;
-}): S2sSessionCtx;
-export {};