@alexkroman1/aai 0.9.3 → 0.10.0

package/dist/_internal-types.d.ts

@@ -5,46 +5,73 @@
  */
 import type { JSONSchema7 } from "json-schema";
 import { z } from "zod";
-import type { BuiltinTool, ToolChoice, ToolDef } from "./types.ts";
+import { type ToolDef } from "./types.ts";
 /**
- * Serializable agent configuration sent over the wire.
+ * 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.
  */
-export type AgentConfig = {
+export declare const AgentConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    instructions: z.ZodString;
+    greeting: z.ZodString;
+    sttPrompt: z.ZodOptional<z.ZodString>;
+    maxSteps: z.ZodOptional<z.ZodNumber>;
+    toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        required: "required";
+        none: "none";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"tool">;
+        toolName: z.ZodString;
+    }, z.core.$strip>]>>;
+    builtinTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+        web_search: "web_search";
+        visit_webpage: "visit_webpage";
+        fetch_json: "fetch_json";
+        run_code: "run_code";
+        vector_search: "vector_search";
+        memory: "memory";
+    }>>>>;
+    idleTimeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Serializable agent configuration — derived from {@link AgentConfigSchema}. */
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+/**
+ * Input shape accepted by {@link toAgentConfig}. Covers both `AgentDef`
+ * (where `maxSteps` may be a function) and `IsolateConfig` (where it is
+ * always a number).
+ */
+export interface AgentConfigSource {
     name: string;
     instructions: string;
     greeting: string;
     sttPrompt?: string | undefined;
-    maxSteps?: number | undefined;
-    toolChoice?: ToolChoice | undefined;
-    builtinTools?: readonly BuiltinTool[] | undefined;
-    /** Default set of active tools. Can be overridden per-turn via `onBeforeStep`. */
-    activeTools?: readonly string[] | undefined;
-};
+    maxSteps?: number | ((...args: never[]) => number) | undefined;
+    toolChoice?: AgentConfig["toolChoice"] | undefined;
+    builtinTools?: Readonly<AgentConfig["builtinTools"]> | undefined;
+    idleTimeoutMs?: number | undefined;
+}
+/** Extract the serializable {@link AgentConfig} subset from a source object. */
+export declare function toAgentConfig(src: AgentConfigSource): AgentConfig;
 /**
- * Serialized tool schema sent over the wire.
+ * 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()`.
  */
+export declare const ToolSchemaSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/** Serialized tool schema — derived from {@link ToolSchemaSchema}. */
 export type ToolSchema = {
     name: string;
     description: string;
     parameters: JSONSchema7;
 };
-/**
- * Request body for the deploy endpoint.
- *
- * Sent by the CLI to the server when deploying a bundled agent.
- */
-export type DeployBody = {
-    /** Env vars are optional at deploy time — set separately via `aai env add`. */
-    env?: Readonly<Record<string, string>> | undefined;
-    worker: string;
-    /** Client build files keyed by relative path (e.g. "index.html", "assets/index-abc.js"). */
-    clientFiles: Readonly<Record<string, string>>;
-};
 /** Empty Zod object schema used as default when tools have no parameters. */
 export declare const EMPTY_PARAMS: z.ZodObject<{}, z.core.$strip>;
 /**

package/dist/_internal-types.js

@@ -1,5 +1,47 @@
+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({});
 /**
@@ -16,4 +58,4 @@ function agentToolsToSchemas(tools) {
 	}));
 }
 //#endregion
-export { EMPTY_PARAMS, agentToolsToSchemas };
+export { AgentConfigSchema, EMPTY_PARAMS, ToolSchemaSchema, agentToolsToSchemas, toAgentConfig };

package/dist/_mock-ws.d.ts

@@ -34,11 +34,10 @@ export declare class MockWebSocket extends EventTarget {
      * @param _protocols - Ignored; accepted for API compatibility.
      */
     constructor(url: string | URL, _protocols?: string | string[] | Record<string, unknown>);
-    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "close" | "open", listener: () => void): void;
     addEventListener(type: "message", listener: (event: {
         data: unknown;
     }) => void): void;
-    addEventListener(type: "close", listener: () => void): void;
     addEventListener(type: "close", listener: (event: {
         code?: number;
         reason?: string;

package/dist/_run-code.d.ts

@@ -0,0 +1,31 @@
+/**
+ * run_code built-in tool — executes user JavaScript in a fresh secure-exec
+ * V8 isolate with no network, filesystem writes, or env access.
+ */
+import { z } from "zod";
+import type { ToolDef } from "./types.ts";
+declare const runCodeParams: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Execute JavaScript code inside a fresh secure-exec V8 isolate.
+ *
+ * Each invocation spins up a disposable isolate with:
+ * - No filesystem writes
+ * - No network access
+ * - No child process spawning
+ * - No environment variable access
+ * - 32 MB memory limit
+ * - 5 second execution timeout
+ *
+ * The isolate is disposed immediately 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.
+ */
+export declare function executeInIsolate(code: string): Promise<string | {
+    error: string;
+}>;
+export {};

package/dist/_session-ctx.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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

@@ -0,0 +1,43 @@
+/**
+ * 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

@@ -0,0 +1,30 @@
+/**
+ * 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

@@ -0,0 +1,30 @@
+/**
+ * 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>;

package/dist/_ssrf.js

@@ -0,0 +1,123 @@
+import { lookup } from "node:dns/promises";
+import { BlockList } from "node:net";
+//#region _ssrf.ts
+/**
+* SSRF protection for AAI network tools.
+*
+* Validates URLs against private/reserved IP ranges and handles redirects
+* safely by re-validating each redirect target. Used by both the SDK
+* (self-hosted built-in tools) and the platform server.
+*/
+const privateBlocks = new BlockList();
+for (const [prefix, bits] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+]) privateBlocks.addSubnet(prefix, bits, "ipv4");
+for (const [prefix, bits] of [
+	["::1", 128],
+	["::", 128],
+	["fc00::", 7],
+	["fe80::", 10],
+	["ff00::", 8]
+]) privateBlocks.addSubnet(prefix, bits, "ipv6");
+/**
+* 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.
+*/
+function isPrivateIp(ip) {
+	const type = ip.includes(":") ? "ipv6" : "ipv4";
+	return privateBlocks.check(ip, type);
+}
+/**
+* Detect IPv4-mapped IPv6 addresses and extract the embedded IPv4.
+* Handles both dotted form (`::ffff:127.0.0.1`) and hex form (`::ffff:7f00:1`).
+*/
+function extractMappedIp(ip) {
+	const mappedDotted = ip.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+	if (mappedDotted) return mappedDotted[1];
+	const mappedHex = ip.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+	if (mappedHex) {
+		const hi = Number.parseInt(mappedHex[1], 16);
+		const lo = Number.parseInt(mappedHex[2], 16);
+		return `${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`;
+	}
+	return ip;
+}
+function isBlockedHostname(hostname) {
+	const lower = hostname.toLowerCase();
+	return lower === "localhost" || lower.endsWith(".local") || lower.endsWith(".internal") || lower === "169.254.169.254";
+}
+function isLiteralIp(hostname) {
+	return /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || hostname.includes(":");
+}
+/** Resolve hostname and block if it points to a private IP (DNS rebinding). */
+async function assertDnsResolvesPublic(hostname) {
+	try {
+		const { address } = await Promise.race([lookup(hostname), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("DNS lookup timed out")), 2e3))]);
+		const resolved = extractMappedIp(address);
+		if (isPrivateIp(address) || isPrivateIp(resolved)) throw new Error(`Blocked request: ${hostname} resolves to private address ${address}`);
+	} catch (err) {
+		if (err instanceof Error && err.message.startsWith("Blocked request")) throw err;
+	}
+}
+/**
+* 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.
+*/
+async function assertPublicUrl(url) {
+	const parsed = new URL(url);
+	const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+	const effective = extractMappedIp(hostname);
+	if (isPrivateIp(hostname) || isPrivateIp(effective)) throw new Error(`Blocked request to private address: ${hostname}`);
+	if (isBlockedHostname(hostname)) throw new Error(`Blocked request to private address: ${hostname}`);
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`Blocked request with disallowed protocol: ${parsed.protocol}`);
+	if (!isLiteralIp(hostname)) await assertDnsResolvesPublic(hostname);
+}
+/** Maximum number of redirects to follow manually. */
+const MAX_REDIRECTS = 5;
+/**
+* Fetch with SSRF-safe redirect handling: validates each redirect URL
+* against private/reserved IP ranges before following.
+*/
+async function ssrfSafeFetch(url, init, fetchFn) {
+	await assertPublicUrl(url);
+	let currentUrl = url;
+	for (let i = 0; i <= MAX_REDIRECTS; i++) {
+		const resp = await fetchFn(currentUrl, {
+			...init,
+			redirect: "manual"
+		});
+		if (resp.status < 300 || resp.status >= 400) return resp;
+		const location = resp.headers.get("location");
+		if (!location) return resp;
+		currentUrl = new URL(location, currentUrl).href;
+		await assertPublicUrl(currentUrl);
+	}
+	throw new Error("Too many redirects");
+}
+//#endregion
+export { assertPublicUrl, isPrivateIp, ssrfSafeFetch };

package/dist/_utils.d.ts

@@ -1,3 +1,28 @@
 /** Shared utility functions. */
 /** Extract an error message from an unknown thrown value. */
 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

@@ -4,5 +4,58 @@
 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);
+}
+/** Filter out undefined values from an env record. */
+function filterEnv(env) {
+	return Object.fromEntries(Object.entries(env).filter((e) => e[1] !== void 0));
+}
+/** 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);
+}
+/**
+* Safely extract the port from `server.address()`, guarding against the
+* string (pipe/socket) and null return types.
+*/
+function getServerPort(addr) {
+	if (addr && typeof addr === "object" && "port" in addr && typeof addr.port === "number") return addr.port;
+	throw new Error(`Expected server address with numeric port, got: ${JSON.stringify(addr)}`);
+}
+/**
+* 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 { errorMessage };
+export { createSessionStateMap, errorDetail, errorMessage, filterEnv, getServerPort, isReadOnlyFsOp, toolError };

package/dist/builtin-tools.d.ts

@@ -1,12 +1,15 @@
 /**
  * Built-in tool definitions for the AAI agent SDK.
  *
- * These tools run inside the sandboxed worker alongside custom tools.
+ * In self-hosted mode, these run in-process alongside custom tools.
+ * In platform mode, they run on the host process outside the sandbox.
  * Network requests go through the host's fetch proxy (with SSRF protection).
  */
 import { z } from "zod";
 import { type ToolSchema } from "./_internal-types.ts";
-import { type ToolDef } from "./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. */
@@ -24,35 +27,3 @@ type ToolDefRecord = Record<string, ToolDef<z.ZodObject<z.ZodRawShape>>>;
 export declare function getBuiltinToolDefs(names: readonly string[], opts?: BuiltinToolOptions): ToolDefRecord;
 /** Returns JSON tool schemas for the specified builtin tools. */
 export declare function getBuiltinToolSchemas(names: readonly string[]): ToolSchema[];
-/**
- * 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() },
- * });
- * ```
- */
-export declare function memoryTools(): {
-    save_memory: ToolDef<z.ZodObject<{
-        key: z.ZodString;
-        value: z.ZodString;
-    }, z.core.$strip>, Record<string, unknown>>;
-    recall_memory: ToolDef<z.ZodObject<{
-        key: z.ZodString;
-    }, z.core.$strip>, Record<string, unknown>>;
-    list_memories: ToolDef<z.ZodObject<{
-        prefix: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, Record<string, unknown>>;
-    forget_memory: ToolDef<z.ZodObject<{
-        key: z.ZodString;
-    }, z.core.$strip>, Record<string, unknown>>;
-};
-export {};