@alexkroman1/aai 0.10.3 → 0.11.0

package/dist/_internal-types.d.ts

@@ -5,7 +5,15 @@
  */
 import type { JSONSchema7 } from "json-schema";
 import { z } from "zod";
+import type { Message } from "./types.ts";
 import { type ToolDef } from "./types.ts";
+/**
+ * Function signature for executing a tool by name.
+ *
+ * Used by session.ts to invoke tools, by direct-executor.ts and
+ * _harness-runtime.ts to implement the execution.
+ */
+export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>, sessionId?: string, messages?: readonly Message[]) => Promise<string>;
 /**
  * Zod schema for serializable agent configuration sent over the wire.
  *
@@ -31,7 +39,6 @@ export declare const AgentConfigSchema: z.ZodObject<{
         visit_webpage: "visit_webpage";
         fetch_json: "fetch_json";
         run_code: "run_code";
-        vector_search: "vector_search";
         memory: "memory";
     }>>>>;
     idleTimeoutMs: z.ZodOptional<z.ZodNumber>;

package/dist/_run-code.d.ts

@@ -1,6 +1,6 @@
 /**
- * run_code built-in tool — executes user JavaScript in a fresh secure-exec
- * V8 isolate with no network, filesystem writes, or env access.
+ * run_code built-in tool — executes user JavaScript in a fresh `node:vm`
+ * context with no network, filesystem, or process access.
  */
 import { z } from "zod";
 import type { ToolDef } from "./types.ts";
@@ -8,22 +8,26 @@ declare const runCodeParams: z.ZodObject<{
     code: z.ZodString;
 }, z.core.$strip>;
 /**
- * Execute JavaScript code inside a fresh secure-exec V8 isolate.
+ * Execute JavaScript code inside a fresh `node:vm` context.
  *
- * Each invocation spins up a disposable isolate with:
- * - No filesystem writes
- * - No network access
+ * Each invocation creates a disposable VM context with:
+ * - No filesystem access (`node:fs` and other built-ins unavailable)
+ * - No network access (`fetch`, `http` unavailable)
  * - No child process spawning
- * - No environment variable access
- * - 32 MB memory limit
- * - 5 second execution timeout
+ * - No environment variable access (`process` unavailable)
+ * - Execution timeout (default 5 s)
  *
- * The isolate is disposed immediately after execution, so no state
- * leaks between invocations or across sessions.
+ * The context is discarded after execution, so no state leaks between
+ * invocations or across sessions.
  */
 export declare function createRunCode(): ToolDef<typeof runCodeParams>;
 /**
- * Exported for testing — execute user code in a fresh secure-exec V8 isolate.
+ * Execute user code in a fresh `node:vm` context.
+ *
+ * @remarks
+ * The VM context only exposes standard ECMAScript globals and a console
+ * object that captures output. Node.js APIs (`process`, `require`,
+ * `import()`) are not available inside the sandbox.
  */
 export declare function executeInIsolate(code: string): Promise<string | {
     error: string;

package/dist/_runtime-conformance.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared runtime conformance tests.
+ *
+ * Both the self-hosted direct executor and the platform sandbox must satisfy
+ * the same behavioral contract. This module defines that contract as a
+ * reusable test suite that can be wired to either runtime.
+ *
+ * Inspired by Nitro's `testNitro()` pattern: one test fixture, many runtimes.
+ *
+ * @example Direct executor (unit test)
+ * ```ts
+ * import { testRuntime } from "./_runtime-conformance.ts";
+ *
+ * testRuntime("direct", () => {
+ *   const exec = createRuntime({ agent: CONFORMANCE_AGENT, env: { MY_VAR: "test-value" } });
+ *   return { executeTool: exec.executeTool, hooks: exec.hooks };
+ * });
+ * ```
+ *
+ * @example Sandbox (integration test in aai-server)
+ * ```ts
+ * import { testRuntime } from "@alexkroman1/aai/internal";
+ *
+ * testRuntime("sandbox", async () => {
+ *   // ... start isolate with a bundled agent
+ *   return { executeTool: buildExecuteTool(...), hooks: buildHookInvoker(...) };
+ * });
+ * ```
+ */
+import type { ExecuteTool } from "./_internal-types.ts";
+import type { AgentHooks } from "./hooks.ts";
+import { type AgentDef } from "./types.ts";
+/**
+ * Minimal runtime surface needed for conformance tests.
+ *
+ * Both `Runtime` and `buildExecuteTool`/`buildHookInvoker` from the
+ * sandbox produce objects that satisfy this interface.
+ */
+export type RuntimeTestContext = {
+    executeTool: ExecuteTool;
+    hooks: AgentHooks;
+};
+/** Agent definition used by the conformance suite (direct executor path). */
+export declare const CONFORMANCE_AGENT: AgentDef;
+/**
+ * Run the runtime conformance test suite against a given runtime context.
+ *
+ * The `getContext` callback is invoked once per test to retrieve the
+ * current {@link RuntimeTestContext}. This allows the caller to set up
+ * the runtime in a `beforeAll` and return it lazily.
+ *
+ * All tests assume the runtime was created with {@link CONFORMANCE_AGENT}
+ * (or its bundle equivalent) and `env: { MY_VAR: "test-value" }`.
+ */
+export declare function testRuntime(label: string, getContext: () => RuntimeTestContext): void;

package/dist/_test-utils.d.ts

@@ -0,0 +1,73 @@
+import type { AgentConfig } from "./_internal-types.ts";
+import type { ClientSink } from "./protocol.ts";
+import type { S2sEvents, S2sHandle } from "./s2s.ts";
+import type { Session } from "./session.ts";
+import { type S2sSessionOptions } from "./session.ts";
+import type { AgentDef, ToolContext, ToolDef } from "./types.ts";
+/** Yield to the microtask queue so pending promises settle. */
+export declare function flush(): Promise<void>;
+export declare function createMockToolContext(overrides?: Partial<ToolContext>): ToolContext;
+export declare function makeTool(overrides?: Partial<ToolDef>): ToolDef;
+export declare function makeAgent(overrides?: Partial<AgentDef>): AgentDef;
+export declare function makeConfig(overrides?: Partial<AgentConfig>): AgentConfig;
+/** Create a stub Session with all methods as vi.fn() spies. */
+export declare function makeStubSession(overrides?: Partial<Session>): Session;
+export type MockS2sHandle = S2sHandle & {
+    _fire: <K extends keyof S2sEvents>(type: K, ...args: Parameters<S2sEvents[K]>) => void;
+};
+/** Create a mock S2sHandle backed by nanoevents. */
+export declare function makeMockHandle(): MockS2sHandle;
+/** Minimal client that tracks events and audio. All methods are vi.fn() spies. */
+export declare function makeClient(): ClientSink & {
+    events: unknown[];
+    audioChunks: Uint8Array[];
+    audioDoneCount: number;
+};
+export declare const silentLogger: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+};
+export declare function makeSessionOpts(overrides?: Partial<S2sSessionOptions>): S2sSessionOptions;
+/** Load a JSON fixture from __fixtures__/. */
+export declare function loadFixture<T = Record<string, unknown>[]>(name: string): T;
+/**
+ * Replay recorded S2S API messages through a MockS2sHandle.
+ *
+ * Converts raw wire-format JSON (from __fixtures__/) into typed `_fire()` calls.
+ * This is the inverse of `dispatchS2sMessage` in s2s.ts — it translates
+ * snake_case API fields to camelCase event payloads.
+ *
+ * Messages that don't map to an event (audio, `reply.content_part.*`) are skipped.
+ */
+export declare function replayFixtureMessages(handle: MockS2sHandle, messages: Record<string, unknown>[]): void;
+/**
+ * Create a real Runtime-backed session for fixture replay testing.
+ *
+ * Uses a real `Runtime` (real tool execution, real hooks) but replaces the
+ * S2S WebSocket with a mock handle so fixture messages can be replayed
+ * through the full orchestration layer.
+ *
+ * Exercises: defineAgent → toAgentConfig → tool schemas → Zod arg validation
+ * → executeToolCall → session orchestration (reply guards, tool buffering,
+ * turnPromise chaining).
+ *
+ * Call `cleanup()` when done to restore the connectS2s spy.
+ */
+export declare function createFixtureSession(agent: AgentDef<any>, opts?: {
+    env?: Record<string, string>;
+}): {
+    session: Session;
+    client: ClientSink & {
+        events: unknown[];
+        audioChunks: Uint8Array[];
+        audioDoneCount: number;
+    };
+    mockHandle: MockS2sHandle;
+    executor: import("./direct-executor.ts").Runtime;
+    /** Replay a fixture file through the session's S2S handle. */
+    replay(fixtureName: string): void;
+    /** Restore the connectS2s spy. Call in afterEach. */
+    cleanup(): void;
+};

package/dist/_utils.d.ts

@@ -3,26 +3,7 @@
 export declare function errorMessage(err: unknown): string;
 /** Extract a detailed error string (message + stack) for diagnostic logging. */
 export declare function errorDetail(err: unknown): string;
-/** Filter out undefined values from an env record. */
-export declare function filterEnv(env: Record<string, string | undefined>): Record<string, string>;
 /** Check whether a filesystem operation is a read-only operation. */
 export declare function isReadOnlyFsOp(op: string): boolean;
-/**
- * Safely extract the port from `server.address()`, guarding against the
- * string (pipe/socket) and null return types.
- */
-export declare function getServerPort(addr: unknown): number;
-/**
- * Lazily initialized per-session state manager.
- *
- * On first access for a given session, calls `initState()` (if provided) to
- * create the initial state. Returns `{}` if no initializer and no prior state.
- */
-export declare function createSessionStateMap(initState?: () => Record<string, unknown>): {
-    get(sessionId: string): Record<string, unknown>;
-    /** Explicitly set the state for a session (used by persistence restore). */
-    set(sessionId: string, state: Record<string, unknown>): void;
-    delete(sessionId: string): boolean;
-};
 /** Return a JSON error string for the LLM: `'{"error":"<message>"}'`. */
 export declare function toolError(message: string): string;

package/dist/_utils.js

@@ -1,2 +1,28 @@
-import { a as getServerPort, i as filterEnv, n as errorDetail, o as isReadOnlyFsOp, r as errorMessage, s as toolError, t as createSessionStateMap } from "./_utils-DgzpOMSV.js";
-export { createSessionStateMap, errorDetail, errorMessage, filterEnv, getServerPort, isReadOnlyFsOp, toolError };
+//#region _utils.ts
+/** Shared utility functions. */
+/** Extract an error message from an unknown thrown value. */
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** Extract a detailed error string (message + stack) for diagnostic logging. */
+function errorDetail(err) {
+	if (err instanceof Error) return err.stack ?? err.message;
+	return String(err);
+}
+/** Set of filesystem operations that are safe for read-only access. */
+const READ_ONLY_FS_OPS = new Set([
+	"read",
+	"stat",
+	"readdir",
+	"exists"
+]);
+/** Check whether a filesystem operation is a read-only operation. */
+function isReadOnlyFsOp(op) {
+	return READ_ONLY_FS_OPS.has(op);
+}
+/** Return a JSON error string for the LLM: `'{"error":"<message>"}'`. */
+function toolError(message) {
+	return JSON.stringify({ error: message });
+}
+//#endregion
+export { errorDetail, errorMessage, isReadOnlyFsOp, toolError };

package/dist/builtin-tools.d.ts

@@ -10,19 +10,15 @@ import { type ToolSchema } from "./_internal-types.ts";
 import type { ToolDef } from "./types.ts";
 export { executeInIsolate } from "./_run-code.ts";
 export { memoryTools } from "./memory-tools.ts";
-/** Callback for proxying vector search through the host RPC. */
-export type VectorSearchFn = (query: string, topK: number) => Promise<string>;
 /** Options for creating built-in tool definitions. */
 export type BuiltinToolOptions = {
-    /** RPC callback for vector_search (proxied through host). */
-    vectorSearch?: VectorSearchFn;
     /** Override fetch implementation (defaults to globalThis.fetch). For testing. */
     fetch?: typeof globalThis.fetch;
 };
 type ToolDefRecord = Record<string, ToolDef<z.ZodObject<z.ZodRawShape>>>;
 /**
  * Create built-in tool definitions for the given tool names.
- * For runtime use — vector_search requires opts.vectorSearch to be included.
+ * For runtime use.
  */
 export declare function getBuiltinToolDefs(names: readonly string[], opts?: BuiltinToolOptions): ToolDefRecord;
 /** Returns JSON tool schemas for the specified builtin tools. */

package/dist/constants-CwotjpJR.js

@@ -0,0 +1,45 @@
+//#region constants.ts
+/**
+* Centralised numeric constants — timeouts, size limits, sample rates.
+*
+* Every magic number that controls a timeout, buffer size, or threshold
+* lives here so the values are discoverable in one place.
+*/
+/** Default sample rate for speech-to-text audio in Hz (AssemblyAI). */
+const DEFAULT_STT_SAMPLE_RATE = 16e3;
+/** Default sample rate for text-to-speech audio in Hz. */
+const DEFAULT_TTS_SAMPLE_RATE = 24e3;
+/** Default timeout for agent lifecycle hooks (onConnect, onTurn, etc). */
+const HOOK_TIMEOUT_MS = 5e3;
+/** Default timeout for tool execution in the worker. */
+const TOOL_EXECUTION_TIMEOUT_MS = 3e4;
+/** Timeout for session.start() (S2S connection setup). */
+const DEFAULT_SESSION_START_TIMEOUT_MS = 1e4;
+/** S2S session idle timeout before auto-close. */
+const DEFAULT_IDLE_TIMEOUT_MS = 3e5;
+/** Per-fetch timeout for network tools (web_search, visit_webpage, fetch_json). */
+const FETCH_TIMEOUT_MS = 15e3;
+/** Timeout for sandboxed run_code execution. */
+const RUN_CODE_TIMEOUT_MS = 5e3;
+/** Maximum time to wait for sessions to stop during graceful shutdown. */
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 3e4;
+/** Maximum length for tool result strings sent to clients. */
+const MAX_TOOL_RESULT_CHARS = 4e3;
+/** Maximum chars for webpage text after HTML-to-text conversion. */
+const MAX_PAGE_CHARS = 1e4;
+/** Maximum bytes to fetch from an HTML page before conversion. */
+const MAX_HTML_BYTES = 2e5;
+/** Maximum value size for KV store entries (bytes). */
+const MAX_VALUE_SIZE = 65536;
+/** Maximum glob pattern length to prevent ReDoS. */
+const MAX_GLOB_PATTERN_LENGTH = 1024;
+/** Maximum conversation messages to retain (sliding window). */
+const DEFAULT_MAX_HISTORY = 200;
+/**
+* Content-Security-Policy applied to agent UI pages (both self-hosted and
+* platform). Single source of truth — used by `secureHeaders` middleware
+* and per-response CSP headers.
+*/
+const AGENT_CSP = "default-src 'self'; script-src 'self' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; connect-src 'self' wss: ws:; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com; object-src 'none'; base-uri 'self'";
+//#endregion
+export { DEFAULT_SHUTDOWN_TIMEOUT_MS as a, FETCH_TIMEOUT_MS as c, MAX_HTML_BYTES as d, MAX_PAGE_CHARS as f, TOOL_EXECUTION_TIMEOUT_MS as g, RUN_CODE_TIMEOUT_MS as h, DEFAULT_SESSION_START_TIMEOUT_MS as i, HOOK_TIMEOUT_MS as l, MAX_VALUE_SIZE as m, DEFAULT_IDLE_TIMEOUT_MS as n, DEFAULT_STT_SAMPLE_RATE as o, MAX_TOOL_RESULT_CHARS as p, DEFAULT_MAX_HISTORY as r, DEFAULT_TTS_SAMPLE_RATE as s, AGENT_CSP as t, MAX_GLOB_PATTERN_LENGTH as u };

package/dist/constants.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Centralised numeric constants — timeouts, size limits, sample rates.
+ *
+ * Every magic number that controls a timeout, buffer size, or threshold
+ * lives here so the values are discoverable in one place.
+ */
+/** Default sample rate for speech-to-text audio in Hz (AssemblyAI). */
+export declare const DEFAULT_STT_SAMPLE_RATE = 16000;
+/** Default sample rate for text-to-speech audio in Hz. */
+export declare const DEFAULT_TTS_SAMPLE_RATE = 24000;
+/** Default timeout for agent lifecycle hooks (onConnect, onTurn, etc). */
+export declare const HOOK_TIMEOUT_MS = 5000;
+/** Default timeout for tool execution in the worker. */
+export declare const TOOL_EXECUTION_TIMEOUT_MS = 30000;
+/** Timeout for session.start() (S2S connection setup). */
+export declare const DEFAULT_SESSION_START_TIMEOUT_MS = 10000;
+/** S2S session idle timeout before auto-close. */
+export declare const DEFAULT_IDLE_TIMEOUT_MS = 300000;
+/** Per-fetch timeout for network tools (web_search, visit_webpage, fetch_json). */
+export declare const FETCH_TIMEOUT_MS = 15000;
+/** Timeout for sandboxed run_code execution. */
+export declare const RUN_CODE_TIMEOUT_MS = 5000;
+/** Maximum time to wait for sessions to stop during graceful shutdown. */
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
+/** Maximum length for tool result strings sent to clients. */
+export declare const MAX_TOOL_RESULT_CHARS = 4000;
+/** Maximum chars for webpage text after HTML-to-text conversion. */
+export declare const MAX_PAGE_CHARS = 10000;
+/** Maximum bytes to fetch from an HTML page before conversion. */
+export declare const MAX_HTML_BYTES = 200000;
+/** Maximum value size for KV store entries (bytes). */
+export declare const MAX_VALUE_SIZE = 65536;
+/** Maximum glob pattern length to prevent ReDoS. */
+export declare const MAX_GLOB_PATTERN_LENGTH = 1024;
+/** Maximum conversation messages to retain (sliding window). */
+export declare const DEFAULT_MAX_HISTORY = 200;
+/**
+ * Content-Security-Policy applied to agent UI pages (both self-hosted and
+ * platform). Single source of truth — used by `secureHeaders` middleware
+ * and per-response CSP headers.
+ */
+export declare const AGENT_CSP: string;