@alexkroman1/aai 0.10.3 → 0.10.4

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/_runtime-conformance.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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)
+ * ```ts
+ * import { testRuntime, CONFORMANCE_AGENT_BUNDLE } from "@alexkroman1/aai/runtime-conformance";
+ *
+ * testRuntime("sandbox", async () => {
+ *   // ... start isolate with CONFORMANCE_AGENT_BUNDLE
+ *   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).
+ *
+ * Must be kept in sync with {@link CONFORMANCE_AGENT_BUNDLE}.
+ */
+export declare const CONFORMANCE_AGENT: AgentDef;
+/**
+ * JavaScript bundle equivalent of {@link CONFORMANCE_AGENT} for the sandbox
+ * isolate path. Must be kept in sync with the AgentDef above.
+ */
+export declare const CONFORMANCE_AGENT_BUNDLE = "\nexport default {\n  name: \"conformance-test\",\n  instructions: \"Conformance test agent.\",\n  greeting: \"Hello!\",\n  maxSteps: 5,\n  state: () => ({ count: 0, lastTurn: \"\" }),\n  tools: {\n    echo: {\n      description: \"Echo input\",\n      execute(args) { return \"echo:\" + args.text; },\n    },\n    get_env: {\n      description: \"Get MY_VAR from env\",\n      execute(_args, ctx) { return ctx.env.MY_VAR ?? \"missing\"; },\n    },\n    get_state: {\n      description: \"Get session state\",\n      execute(_args, ctx) { return JSON.stringify(ctx.state); },\n    },\n    echo_messages: {\n      description: \"Return messages as JSON\",\n      execute(_args, ctx) { return JSON.stringify(ctx.messages); },\n    },\n    kv_roundtrip: {\n      description: \"KV set then get\",\n      async execute(args, ctx) {\n        await ctx.kv.set(\"test-key\", args.value);\n        const result = await ctx.kv.get(\"test-key\");\n        return \"stored:\" + JSON.stringify(result);\n      },\n    },\n  },\n  onConnect: (ctx) => { ctx.state.count = 1; },\n  onTurn: (text, ctx) => { ctx.state.lastTurn = text; },\n};\n";
+/**
+ * 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,70 @@
+import type { AgentConfig } from "./_internal-types.ts";
+import type { ClientSink } from "./protocol.ts";
+import type { S2sEvents, S2sHandle } from "./s2s.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;
+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: import("./session.ts").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,15 +3,8 @@
 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.
  *
@@ -20,7 +13,7 @@ export declare function getServerPort(addr: unknown): number;
  */
 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). */
+    /** Explicitly set the state for a session. */
     set(sessionId: string, state: Record<string, unknown>): void;
     delete(sessionId: string): boolean;
 };

package/dist/_utils.js

@@ -1,2 +1,49 @@
-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);
+}
+/**
+* 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.
+*/
+function createSessionStateMap(initState) {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		get(sessionId) {
+			if (!map.has(sessionId) && initState) map.set(sessionId, initState());
+			return map.get(sessionId) ?? {};
+		},
+		set(sessionId, state) {
+			map.set(sessionId, state);
+		},
+		delete(sessionId) {
+			return map.delete(sessionId);
+		}
+	};
+}
+/** Return a JSON error string for the LLM: `'{"error":"<message>"}'`. */
+function toolError(message) {
+	return JSON.stringify({ error: message });
+}
+//#endregion
+export { createSessionStateMap, 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-BbAOvKl_.js

@@ -0,0 +1,47 @@
+//#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;
+/** Memory limit for run_code isolates (MB). */
+const RUN_CODE_MEMORY_MB = 32;
+/**
+* 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 { TOOL_EXECUTION_TIMEOUT_MS as _, DEFAULT_SHUTDOWN_TIMEOUT_MS as a, FETCH_TIMEOUT_MS as c, MAX_HTML_BYTES as d, MAX_PAGE_CHARS as f, RUN_CODE_TIMEOUT_MS as g, RUN_CODE_MEMORY_MB 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,44 @@
+/**
+ * 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;
+/** Memory limit for run_code isolates (MB). */
+export declare const RUN_CODE_MEMORY_MB = 32;
+/**
+ * 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;