@alexkroman1/aai 0.10.2 → 0.10.4

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/unstorage-kv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Key-value store backed by unstorage.
+ *
+ * Works with any unstorage driver (memory, fs, S3/R2, etc.).
+ */
+import { type Storage } from "unstorage";
+import type { Kv } from "./kv.ts";
+/**
+ * Options for creating an unstorage-backed KV store.
+ */
+export type UnstorageKvOptions = {
+    /** Configured unstorage Storage instance. */
+    storage: Storage;
+    /** Key prefix prepended to all operations (e.g. `"agents/my-agent/kv"`). */
+    prefix?: string;
+};
+/**
+ * Create a KV store backed by any unstorage driver.
+ *
+ * @param options - See {@link UnstorageKvOptions}.
+ * @returns A {@link Kv} instance.
+ *
+ * @example
+ * ```ts
+ * import { createStorage } from "unstorage";
+ * import { createUnstorageKv } from "@alexkroman1/aai/unstorage-kv";
+ *
+ * const kv = createUnstorageKv({ storage: createStorage() });
+ * await kv.set("greeting", "hello");
+ * const value = await kv.get<string>("greeting"); // "hello"
+ * ```
+ */
+export declare function createUnstorageKv(options: UnstorageKvOptions): Kv;

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.2",
+  "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,110 +41,50 @@
       "types": "./dist/matchers.d.ts",
       "import": "./dist/matchers.js"
     },
-    "./server": {
-      "source": "./server.ts",
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
+    "./internal": {
+      "source": "./internal.ts",
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
     },
-    "./protocol": {
-      "source": "./protocol.ts",
-      "types": "./dist/protocol.d.ts",
-      "import": "./dist/protocol.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"
-    },
-    "./sqlite-kv": {
-      "source": "./sqlite-kv.ts",
-      "types": "./dist/sqlite-kv.d.ts",
-      "import": "./dist/sqlite-kv.js"
-    },
-    "./sqlite-vector": {
-      "source": "./sqlite-vector.ts",
-      "types": "./dist/sqlite-vector.d.ts",
-      "import": "./dist/sqlite-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",
-    "@opentelemetry/api": "^1.9.1",
-    "hono": "^4.12.9",
     "vitest": "^4.1.1"
   },
   "peerDependenciesMeta": {
-    "@hono/node-server": {
-      "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"
@@ -153,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/_internal-types.js

@@ -1,61 +0,0 @@
-import { BuiltinToolSchema, ToolChoiceSchema } from "./types.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 { 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 {};

package/dist/_session-otel.d.ts

@@ -1,43 +0,0 @@
-/**
- * OpenTelemetry-instrumented session helpers.
- *
- * Extracted from session.ts to keep it under the file-length lint limit.
- * These functions add trace spans and metric counters to the S2S session
- * pipeline: tool calls, user turns, barge-ins, and session lifecycle.
- */
-import type { S2sSessionCtx } from "./_session-ctx.ts";
-import type { S2sHandle, S2sToolCall } from "./s2s.ts";
-export { activeSessionsUpDown, sessionCounter } from "./telemetry.ts";
-/**
- * Orchestrate the full tool call pipeline for a single S2S tool invocation.
- *
- * Steps: resolve per-turn config → check step/tool limits → run middleware
- * `interceptToolCall` (which may block, return a cached result, or modify args)
- * → execute the tool → run `afterToolCall` middleware → record metrics and
- * finish via {@link finishToolCall}. Each step is wrapped in an OpenTelemetry
- * span (`tool.call`) with agent/session/tool attributes.
- *
- * @param ctx - The shared mutable session context (see {@link S2sSessionCtx}).
- * @param detail - The tool call details from the S2S API (call ID, name, parsed args).
- */
-export declare function handleToolCall(ctx: S2sSessionCtx, detail: S2sToolCall): Promise<void>;
-/** Options for customizing S2S event listener behavior. */
-export type SetupListenersOptions = {
-    /** Custom handler for session expiration. When provided, replaces the
-     *  default behavior of closing the handle. Used by resume logic to
-     *  fall back to a fresh session when S2S resume fails. */
-    onSessionExpired?: () => void;
-};
-/**
- * Wire all S2S events to the client sink, hooks, and session state.
- *
- * Registers listeners on the S2S handle for: ready, session expiry, speech
- * start/stop, user/agent transcripts, reply lifecycle, tool calls, audio
- * chunks, errors, and close. Each listener delegates to a focused handler
- * function that updates `ctx` and emits client events.
- *
- * @param ctx - The shared mutable session context.
- * @param handle - The S2S WebSocket handle to listen on.
- * @param opts - Optional overrides for listener behavior.
- */
-export declare function setupListeners(ctx: S2sSessionCtx, handle: S2sHandle, opts?: SetupListenersOptions): void;

package/dist/_session-persist.d.ts

@@ -1,30 +0,0 @@
-/**
- * Session persistence helpers.
- *
- * Saves and restores session state, conversation messages, and S2S session ID
- * to/from the KV store for cross-reconnect session recovery.
- */
-import type { Kv } from "./kv.ts";
-import type { Logger } from "./runtime.ts";
-import type { Message } from "./types.ts";
-export declare function persistKey(sessionId: string): string;
-export type PersistedSession = {
-    s2sSessionId: string | null;
-    messages: Message[];
-    state: Record<string, unknown>;
-};
-export type SessionPersistence = {
-    kv: Kv;
-    ttl: number;
-    getState: () => Record<string, unknown>;
-    setState: (state: Record<string, unknown>) => void;
-};
-type PersistCtx = {
-    pushMessages(...msgs: Message[]): void;
-    conversationMessages: Message[];
-};
-export declare function restorePersistedSession(persistence: SessionPersistence, resumeFrom: string, ctx: PersistCtx, log: Logger): Promise<string | null>;
-export declare function saveSessionData(persistence: SessionPersistence, sessionId: string, ctx: PersistCtx, s2sSessionId: string | null, log: Logger, 
-/** Old session key to clean up (from a previous session we resumed from). */
-cleanupKey?: string): Promise<void>;
-export {};

package/dist/_ssrf.d.ts

@@ -1,30 +0,0 @@
-/**
- * Check whether an IP address falls within a private or reserved range.
- *
- * @param ip - An IPv4 or IPv6 address string.
- * @returns `true` if the address is in a private/reserved range.
- */
-export declare function isPrivateIp(ip: string): boolean;
-/**
- * SSRF guard: assert that a URL targets a public internet address.
- *
- * Blocks requests to:
- * - Private IPv4 ranges (RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
- * - Loopback (127.0.0.0/8), link-local (169.254.0.0/16), shared (100.64.0.0/10)
- * - IPv4-mapped IPv6 addresses embedding private IPs (e.g. `::ffff:127.0.0.1`)
- * - IPv6 loopback (`::1`), ULA (`fc00::/7`), link-local (`fe80::/10`)
- * - `localhost`, `.local` (mDNS), `.internal` domains
- * - Cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`)
- * - Non-http(s) schemes (e.g. `file:`, `ftp:`)
- * - Hostnames that resolve to private IPs via DNS (prevents DNS rebinding)
- *
- * @param url - The URL to validate (must be parseable by `new URL()`).
- * @throws {Error} If the URL targets a private/reserved address or uses a
- *   disallowed protocol scheme.
- */
-export declare function assertPublicUrl(url: string): Promise<void>;
-/**
- * Fetch with SSRF-safe redirect handling: validates each redirect URL
- * against private/reserved IP ranges before following.
- */
-export declare function ssrfSafeFetch(url: string, init: RequestInit, fetchFn: typeof globalThis.fetch): Promise<Response>;