@alexkroman1/aai 0.9.2 → 0.10.0

package/dist/kv.d.ts

@@ -1,10 +1,12 @@
 /**
- * Key-value storage interface and in-memory implementation.
+ * Key-value storage interface and shared utilities.
  */
 /**
  * A single key-value entry returned by {@link Kv.list}.
  *
  * @typeParam T - The type of the stored value. Defaults to `unknown`.
+ *
+ * @public
  */
 export type KvEntry<T = unknown> = {
     /** The key under which the value is stored. */
@@ -15,7 +17,10 @@ export type KvEntry<T = unknown> = {
 /**
  * Options for listing keys from the KV store.
  *
- * Used with {@link Kv.list} to control result ordering and pagination.
+ * Used with {@link Kv.list} and {@link Kv.keys} to control filtering,
+ * ordering, and pagination.
+ *
+ * @public
  */
 export type KvListOptions = {
     /** Maximum number of entries to return. */
@@ -26,8 +31,8 @@ export type KvListOptions = {
 /**
  * Async key-value store interface used by agents.
  *
- * Agents access the KV store via {@link ToolContext.kv} or
- * {@link HookContext.kv}. Values are JSON-serialized and stored as
+ * Agents access the KV store via `ToolContext.kv` or
+ * `HookContext.kv`. Values are JSON-serialized and stored as
  * strings with an optional TTL.
  *
  * @example
@@ -42,6 +47,8 @@ export type KvListOptions = {
  *   },
  * };
  * ```
+ *
+ * @public
  */
 export type Kv = {
     /**
@@ -58,19 +65,19 @@ export type Kv = {
      *
      * @param key - The key to store the value under.
      * @param value - The value to store. Must be JSON-serializable.
-     * @param options - Optional settings. `expireIn` sets the time-to-live in milliseconds. The entry is
-     *   automatically removed after this duration.
-     * @throws {Error} If the serialized value exceeds 65,536 bytes.
+     * @param options - Optional settings. `expireIn` sets the time-to-live in **milliseconds**
+     *   (e.g. `60_000` for 1 minute). The entry is automatically removed after this duration.
+     * @throws Throws an Error if the serialized value exceeds 65,536 bytes.
      */
     set(key: string, value: unknown, options?: {
         expireIn?: number;
     }): Promise<void>;
     /**
-     * Delete a key.
+     * Delete one or more keys.
      *
-     * @param key - The key to remove. No-op if the key does not exist.
+     * @param keys - A single key or array of keys to delete. No-op for keys that do not exist.
      */
-    delete(key: string): Promise<void>;
+    delete(keys: string | string[]): Promise<void>;
     /**
      * List entries whose keys start with the given prefix.
      *
@@ -83,12 +90,21 @@ export type Kv = {
      */
     list<T = unknown>(prefix: string, options?: KvListOptions): Promise<KvEntry<T>[]>;
     /**
-     * List all keys, optionally filtered by a glob-style pattern.
+     * List all keys, optionally filtered by a prefix or glob-style pattern.
      *
-     * @param pattern - Optional glob pattern (e.g. `"user:*"`). If omitted, all keys are returned.
+     * @param pattern - Optional prefix string or glob pattern (e.g. `"user:*"`).
+     *   A pattern without wildcards (`*`) is treated as a prefix match.
+     *   If omitted, all keys are returned.
      * @returns An array of matching key strings.
      */
     keys(pattern?: string): Promise<string[]>;
+    /**
+     * Close the KV store, releasing any resources (intervals, database handles).
+     *
+     * After calling `close()`, the store must not be used. This is a no-op
+     * for implementations that hold no resources (e.g. in-memory stores).
+     */
+    close?(): void;
 };
 export declare const MAX_VALUE_SIZE = 65536;
 /** Sort entries by key and apply reverse/limit options. Mutates the array. */
@@ -98,29 +114,5 @@ export declare function sortAndPaginate<T extends {
     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 {@link 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;
+/** Simple glob matcher — supports `*` as a wildcard for any characters. */
+export declare function matchGlob(key: string, pattern: string): boolean;

package/dist/kv.js

@@ -2,98 +2,31 @@
 const MAX_VALUE_SIZE = 65536;
 /** Sort entries by key and apply reverse/limit options. Mutates the array. */
 function sortAndPaginate(entries, options) {
-	entries.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+	entries.sort((a, b) => a.key.localeCompare(b.key));
 	if (options?.reverse) entries.reverse();
 	if (options?.limit && options.limit > 0) entries.length = Math.min(entries.length, options.limit);
 	return entries;
 }
+/** Maximum allowed glob pattern length to prevent ReDoS. */
+const MAX_GLOB_PATTERN_LENGTH = 1024;
 /** Simple glob matcher — supports `*` as a wildcard for any characters. */
 function matchGlob(key, pattern) {
-	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
-	return new RegExp(`^${escaped}$`).test(key);
-}
-/**
-* 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 {@link 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 });
-* ```
-*/
-function createMemoryKv() {
-	const store = /* @__PURE__ */ new Map();
-	function isExpired(entry) {
-		return entry.expiresAt !== void 0 && entry.expiresAt <= Date.now();
+	if (pattern.length > MAX_GLOB_PATTERN_LENGTH) throw new Error(`Glob pattern exceeds maximum length of ${MAX_GLOB_PATTERN_LENGTH}`);
+	const parts = pattern.split("*");
+	if (parts.length === 1) return key === pattern;
+	const first = parts[0];
+	if (!key.startsWith(first)) return false;
+	const last = parts.at(-1);
+	if (key.length < first.length + last.length) return false;
+	if (!key.endsWith(last)) return false;
+	let pos = first.length;
+	const end = key.length - last.length;
+	for (const part of parts.slice(1, -1)) {
+		const idx = key.indexOf(part, pos);
+		if (idx === -1 || idx > end) return false;
+		pos = idx + part.length;
 	}
-	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 > 65536) 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();
-		},
-		async list(prefix, options) {
-			const now = Date.now();
-			const entries = [];
-			let i = 0;
-			for (const [key, entry] of store) {
-				if (++i % 500 === 0) await new Promise((r) => setTimeout(r, 0));
-				if (entry.expiresAt && entry.expiresAt <= now) {
-					store.delete(key);
-					continue;
-				}
-				if (key.startsWith(prefix)) entries.push({
-					key,
-					value: JSON.parse(entry.raw)
-				});
-			}
-			return sortAndPaginate(entries, options);
-		},
-		async keys(pattern) {
-			const now = Date.now();
-			const result = [];
-			for (const [key, entry] of store) {
-				if (entry.expiresAt && entry.expiresAt <= now) {
-					store.delete(key);
-					continue;
-				}
-				if (!pattern || matchGlob(key, pattern)) result.push(key);
-			}
-			return result.sort();
-		}
-	};
+	return pos <= end;
 }
 //#endregion
-export { MAX_VALUE_SIZE, createMemoryKv, sortAndPaginate };
+export { MAX_VALUE_SIZE, matchGlob, sortAndPaginate };

package/dist/matchers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Vitest custom matchers for AAI testing.
+ *
+ * Add this to your Vitest setup file to enable `expect(turn).toHaveCalledTool()`:
+ *
+ * ```ts
+ * // vitest.config.ts
+ * export default defineConfig({
+ *   test: { setupFiles: ["@alexkroman1/aai/testing/matchers"] },
+ * });
+ * ```
+ *
+ * Or import directly in your test file:
+ * ```ts
+ * import "@alexkroman1/aai/testing/matchers";
+ * ```
+ *
+ * @packageDocumentation
+ */
+export {};

package/dist/matchers.js

@@ -0,0 +1,41 @@
+import { n as TurnResult } from "./testing-MRl3SXsI.js";
+import { expect } from "vitest";
+//#region matchers.ts
+/**
+* Vitest custom matchers for AAI testing.
+*
+* Add this to your Vitest setup file to enable `expect(turn).toHaveCalledTool()`:
+*
+* ```ts
+* // vitest.config.ts
+* export default defineConfig({
+*   test: { setupFiles: ["@alexkroman1/aai/testing/matchers"] },
+* });
+* ```
+*
+* Or import directly in your test file:
+* ```ts
+* import "@alexkroman1/aai/testing/matchers";
+* ```
+*
+* @packageDocumentation
+*/
+expect.extend({ toHaveCalledTool(received, toolName, args) {
+	if (!(received instanceof TurnResult)) return {
+		pass: false,
+		message: () => `expected a TurnResult, got ${typeof received}`,
+		actual: received,
+		expected: "TurnResult"
+	};
+	const pass = received.toHaveCalledTool(toolName, args);
+	const calledTools = received.toolCalls.map((tc) => tc.toolName);
+	const argsHint = args ? ` with args ${JSON.stringify(args)}` : "";
+	return {
+		pass,
+		message: () => pass ? `expected turn NOT to have called tool "${toolName}"${argsHint}, but it was called.\nCalled tools: ${JSON.stringify(calledTools)}` : `expected turn to have called tool "${toolName}"${argsHint}, but it was not.\nCalled tools: ${JSON.stringify(calledTools)}`,
+		actual: calledTools,
+		expected: toolName
+	};
+} });
+//#endregion
+export {};

package/dist/memory-tools.d.ts

@@ -0,0 +1,39 @@
+/**
+ * KV-backed memory tools for agent persistent state.
+ */
+import { z } from "zod";
+/**
+ * Returns a standard set of KV-backed memory tools: `save_memory`,
+ * `recall_memory`, `list_memories`, and `forget_memory`.
+ *
+ * Spread the result into your agent's `tools` record.
+ *
+ * @example
+ * ```ts
+ * import { defineAgent, memoryTools } from "aai";
+ *
+ * export default defineAgent({
+ *   name: "My Agent",
+ *   tools: { ...memoryTools() },
+ * });
+ * ```
+ *
+ * @returns A record with four tool definitions: `save_memory`, `recall_memory`,
+ *   `list_memories`, and `forget_memory`.
+ * @public
+ */
+export declare function memoryTools(): {
+    save_memory: import("./types.ts").ToolDef<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>, Record<string, unknown>>;
+    recall_memory: import("./types.ts").ToolDef<z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strip>, Record<string, unknown>>;
+    list_memories: import("./types.ts").ToolDef<z.ZodObject<{
+        prefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, Record<string, unknown>>;
+    forget_memory: import("./types.ts").ToolDef<z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strip>, Record<string, unknown>>;
+};

package/dist/middleware-core.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure middleware runner functions — zero runtime dependencies.
+ *
+ * This module is intentionally dependency-free so it can be bundled into
+ * the secure-exec isolate harness (which has no access to node_modules).
+ * Only `import type` statements are allowed here.
+ */
+import type { HookContext, Middleware, MiddlewareBlockResult } from "./types.ts";
+/** Result from a middleware tool call interceptor. */
+export type ToolInterceptResult = {
+    type: "block";
+    reason: string;
+} | {
+    type: "result";
+    result: string;
+} | {
+    type: "args";
+    args: Record<string, unknown>;
+} | undefined;
+/**
+ * Run all `beforeInput` middleware in order, piping the text through each.
+ * Symmetric to {@link runOutputFilters} but for user input.
+ */
+export declare function runInputFilters(middleware: readonly Middleware[], text: string, ctx: HookContext): Promise<string>;
+/**
+ * Run all `beforeTurn` middleware in order. Returns a block result if any
+ * middleware blocks the turn, or `undefined` to proceed.
+ */
+export declare function runBeforeTurnMiddleware(middleware: readonly Middleware[], text: string, ctx: HookContext): Promise<MiddlewareBlockResult | undefined>;
+/**
+ * Run all `afterTurn` middleware in reverse order.
+ */
+export declare function runAfterTurnMiddleware(middleware: readonly Middleware[], text: string, ctx: HookContext): Promise<void>;
+/**
+ * Run all `beforeToolCall` middleware in order. Returns a result that
+ * may block execution, provide a cached result, or transform args.
+ * Returns `undefined` to proceed with normal execution.
+ */
+export declare function runToolCallInterceptors(middleware: readonly Middleware[], toolName: string, args: Readonly<Record<string, unknown>>, ctx: HookContext): Promise<ToolInterceptResult>;
+/**
+ * Run all `afterToolCall` middleware in reverse order.
+ */
+export declare function runAfterToolCallMiddleware(middleware: readonly Middleware[], toolName: string, args: Readonly<Record<string, unknown>>, result: string, ctx: HookContext): Promise<void>;
+/**
+ * Run all `beforeOutput` middleware in order, piping the text through each.
+ */
+export declare function runOutputFilters(middleware: readonly Middleware[], text: string, ctx: HookContext): Promise<string>;

package/dist/middleware-core.js

@@ -0,0 +1,107 @@
+//#region middleware-core.ts
+/**
+* Run all `beforeInput` middleware in order, piping the text through each.
+* Symmetric to {@link runOutputFilters} but for user input.
+*/
+async function runInputFilters(middleware, text, ctx) {
+	let filtered = text;
+	for (const mw of middleware) {
+		if (!mw.beforeInput) continue;
+		try {
+			filtered = await mw.beforeInput(filtered, ctx);
+		} catch (err) {
+			console.warn("Middleware beforeInput failed:", err);
+		}
+	}
+	return filtered;
+}
+/**
+* Run all `beforeTurn` middleware in order. Returns a block result if any
+* middleware blocks the turn, or `undefined` to proceed.
+*/
+async function runBeforeTurnMiddleware(middleware, text, ctx) {
+	for (const mw of middleware) {
+		if (!mw.beforeTurn) continue;
+		try {
+			const result = await mw.beforeTurn(text, ctx);
+			if (result && "block" in result && result.block) return result;
+		} catch (err) {
+			console.warn("Middleware beforeTurn failed:", err);
+		}
+	}
+}
+/**
+* Run all `afterTurn` middleware in reverse order.
+*/
+async function runAfterTurnMiddleware(middleware, text, ctx) {
+	for (let i = middleware.length - 1; i >= 0; i--) {
+		const mw = middleware[i];
+		if (!mw?.afterTurn) continue;
+		try {
+			await mw.afterTurn(text, ctx);
+		} catch (err) {
+			console.warn("Middleware afterTurn failed:", err);
+		}
+	}
+}
+/**
+* Run all `beforeToolCall` middleware in order. Returns a result that
+* may block execution, provide a cached result, or transform args.
+* Returns `undefined` to proceed with normal execution.
+*/
+async function runToolCallInterceptors(middleware, toolName, args, ctx) {
+	let currentArgs = args;
+	for (const mw of middleware) {
+		if (!mw.beforeToolCall) continue;
+		try {
+			const result = await mw.beforeToolCall(toolName, currentArgs, ctx);
+			if (!result) continue;
+			if ("block" in result && result.block) return {
+				type: "block",
+				reason: result.reason
+			};
+			if ("result" in result) return {
+				type: "result",
+				result: result.result
+			};
+			if ("args" in result) currentArgs = result.args;
+		} catch (err) {
+			console.warn("Middleware beforeToolCall failed:", err);
+		}
+	}
+	if (currentArgs !== args) return {
+		type: "args",
+		args: currentArgs
+	};
+}
+/**
+* Run all `afterToolCall` middleware in reverse order.
+*/
+async function runAfterToolCallMiddleware(middleware, toolName, args, result, ctx) {
+	for (let i = middleware.length - 1; i >= 0; i--) {
+		const mw = middleware[i];
+		if (!mw?.afterToolCall) continue;
+		try {
+			await mw.afterToolCall(toolName, args, result, ctx);
+		} catch (err) {
+			console.warn("Middleware afterToolCall failed:", err);
+		}
+	}
+}
+/**
+* Run all `beforeOutput` middleware in order, piping the text through each.
+*/
+async function runOutputFilters(middleware, text, ctx) {
+	let filtered = text;
+	for (const mw of middleware) {
+		if (!mw.beforeOutput) continue;
+		try {
+			filtered = await mw.beforeOutput(filtered, ctx);
+		} catch (err) {
+			console.warn("Middleware beforeOutput failed:", err);
+		}
+	}
+	return filtered;
+}
+//#endregion
+export { runAfterToolCallMiddleware, runAfterTurnMiddleware, runBeforeTurnMiddleware, runInputFilters, runOutputFilters, runToolCallInterceptors };

package/dist/middleware.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Middleware runner — executes middleware chains for turns, tool calls,
+ * and output filtering.
+ *
+ * Pure runner logic lives in middleware-core.ts (isolate-safe, zero deps).
+ * This module re-exports it and adds the HookInvoker interface.
+ */
+import type { StepInfo } from "./types.ts";
+export { runAfterToolCallMiddleware, runAfterTurnMiddleware, runBeforeTurnMiddleware, runInputFilters, runOutputFilters, runToolCallInterceptors, type ToolInterceptResult, } from "./middleware-core.ts";
+/** Generic interface for invoking agent lifecycle hooks, including middleware. */
+export type HookInvoker = {
+    onConnect(sessionId: string, timeoutMs?: number): Promise<void>;
+    onDisconnect(sessionId: string, timeoutMs?: number): Promise<void>;
+    onTurn(sessionId: string, text: string, timeoutMs?: number): Promise<void>;
+    onError(sessionId: string, error: {
+        message: string;
+    }, timeoutMs?: number): Promise<void>;
+    onStep(sessionId: string, step: StepInfo, timeoutMs?: number): Promise<void>;
+    resolveTurnConfig(sid: string, ms?: number): Promise<{
+        maxSteps?: number;
+    } | null>;
+    filterInput?(sid: string, text: string, ms?: number): Promise<string>;
+    beforeTurn?(sid: string, text: string, ms?: number): Promise<string | undefined>;
+    afterTurn?(sid: string, text: string, ms?: number): Promise<void>;
+    interceptToolCall?(sid: string, tool: string, args: Readonly<Record<string, unknown>>, ms?: number): Promise<{
+        type: "block";
+        reason: string;
+    } | {
+        type: "result";
+        result: string;
+    } | {
+        type: "args";
+        args: Record<string, unknown>;
+    } | undefined>;
+    afterToolCall?(sid: string, tool: string, args: Readonly<Record<string, unknown>>, result: string, ms?: number): Promise<void>;
+    filterOutput?(sid: string, text: string, ms?: number): Promise<string>;
+};