@alexkroman1/aai 1.7.1 → 1.8.0

package/host/builtin-tools.test.ts

@@ -4,6 +4,11 @@ import { describe, expect, test, vi } from "vitest";
 import { createMockToolContext } from "./_test-utils.ts";
 import { executeInIsolate, resolveAllBuiltins } from "./builtin-tools.ts";
 
+function runCode(code: string): Promise<unknown> {
+  const { defs } = resolveAllBuiltins(["run_code"]);
+  return defs.run_code?.execute({ code }, createMockToolContext()) as Promise<unknown>;
+}
+
 describe("resolveAllBuiltins schemas", () => {
   test("returns requested tools", () => {
     const { schemas } = resolveAllBuiltins([
@@ -47,34 +52,23 @@ describe("resolveAllBuiltins defs", () => {
   // ─── run_code ──────────────────────────────────────────────────────────
 
   test("run_code executes and returns stdout", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute({ code: 'console.log("hello")' }, ctx);
+    const result = await runCode('console.log("hello")');
     expect(result).toBe("hello");
   });
 
   test("run_code returns error for syntax errors", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute({ code: "%%%" }, ctx);
+    const result = await runCode("%%%");
     expect(result).toHaveProperty("error");
   });
 
   test("run_code returns no-output message for silent code", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute({ code: "const x = 1 + 1;" }, ctx);
+    const result = await runCode("const x = 1 + 1;");
     expect(result).toBe("Code ran successfully (no output)");
   });
 
   test("run_code captures console.warn and console.error", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: 'console.warn("w"); console.error("e"); console.debug("d"); console.info("i")',
-      },
-      ctx,
+    const result = await runCode(
+      'console.warn("w"); console.error("e"); console.debug("d"); console.info("i")',
     );
     expect(result).toBe("w\ne\nd\ni");
   });
@@ -82,276 +76,187 @@ describe("resolveAllBuiltins defs", () => {
   // ─── run_code security: vm sandbox prevents host access ──────────────
 
   test("run_code sandbox blocks network access", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const res = await fetch("https://example.com");
-            console.log("ESCAPED:" + res.status);
-          } catch(e) {
-            console.log("BLOCKED:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const res = await fetch("https://example.com");
+        console.log("ESCAPED:" + res.status);
+      } catch(e) {
+        console.log("BLOCKED:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).toMatch(/BLOCKED/);
   });
 
   test("run_code sandbox blocks filesystem writes", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const fs = await import("node:fs");
-            fs.writeFileSync("/tmp/pwned.txt", "owned");
-            console.log("ESCAPED");
-          } catch(e) {
-            console.log("BLOCKED:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const fs = await import("node:fs");
+        fs.writeFileSync("/tmp/pwned.txt", "owned");
+        console.log("ESCAPED");
+      } catch(e) {
+        console.log("BLOCKED:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).toMatch(/BLOCKED/);
   });
 
   test("run_code sandbox blocks child process spawning", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const cp = await import("node:child_process");
-            const out = cp.execSync("id").toString();
-            console.log("ESCAPED:" + out);
-          } catch(e) {
-            console.log("BLOCKED:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const cp = await import("node:child_process");
+        const out = cp.execSync("id").toString();
+        console.log("ESCAPED:" + out);
+      } catch(e) {
+        console.log("BLOCKED:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).toMatch(/BLOCKED/);
   });
 
   test("run_code sandbox blocks env var access", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const keys = process.env ? Object.keys(process.env) : [];
-            const hasPath = keys.includes("PATH");
-            const hasHome = keys.includes("HOME");
-            console.log(hasPath || hasHome ? "LEAKED_ENV" : "SAFE:" + keys.length);
-          } catch(e) {
-            console.log("SAFE:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const keys = process.env ? Object.keys(process.env) : [];
+        const hasPath = keys.includes("PATH");
+        const hasHome = keys.includes("HOME");
+        console.log(hasPath || hasHome ? "LEAKED_ENV" : "SAFE:" + keys.length);
+      } catch(e) {
+        console.log("SAFE:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).not.toMatch(/LEAKED_ENV/);
   });
 
   test("run_code sandbox prevents constructor chain escape", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
     // This was the critical bypass in the old regex approach — the VM context
     // doesn't expose `process` so host secrets can't be exfiltrated.
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          const c = "con" + "stru" + "ctor";
-          const F = ""[c][c];
-          try {
-            const p = F("return process")();
-            const keys = p && p.env ? Object.keys(p.env) : [];
-            const hasPath = keys.includes("PATH");
-            console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length);
-          } catch(e) {
-            console.log("SAFE:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      const c = "con" + "stru" + "ctor";
+      const F = ""[c][c];
+      try {
+        const p = F("return process")();
+        const keys = p && p.env ? Object.keys(p.env) : [];
+        const hasPath = keys.includes("PATH");
+        console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length);
+      } catch(e) {
+        console.log("SAFE:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).not.toMatch(/LEAKED_ENV/);
   });
 
   test("run_code allows normal .constructor property check", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      { code: 'console.log("hello".constructor.name)' },
-      ctx,
-    );
+    const result = await runCode('console.log("hello".constructor.name)');
     expect(result).toBe("String");
   });
 
   test("run_code sandbox blocks console.log.constructor code generation", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const fn = console.log.constructor('return 1')();
-            console.log("ESCAPED:" + fn);
-          } catch(e) {
-            console.log("BLOCKED:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const fn = console.log.constructor('return 1')();
+        console.log("ESCAPED:" + fn);
+      } catch(e) {
+        console.log("BLOCKED:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).toMatch(/BLOCKED/);
     expect(result as string).not.toMatch(/ESCAPED/);
   });
 
   test("run_code sandbox blocks URL.constructor.constructor code generation", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const fn = URL.constructor.constructor('return 1')();
-            console.log("ESCAPED:" + fn);
-          } catch(e) {
-            console.log("BLOCKED:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const fn = URL.constructor.constructor('return 1')();
+        console.log("ESCAPED:" + fn);
+      } catch(e) {
+        console.log("BLOCKED:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).toMatch(/BLOCKED/);
     expect(result as string).not.toMatch(/ESCAPED/);
   });
 
   test("run_code sandbox blocks template literal constructor bypass", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          const c = \`\${"con"}\${"stru"}\${"ctor"}\`;
-          const F = ""[c][c];
-          try {
-            const p = F("return process")();
-            const keys = p && p.env ? Object.keys(p.env) : [];
-            const hasPath = keys.includes("PATH");
-            console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length + " keys");
-          } catch(e) {
-            console.log("SAFE:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      const c = \`\${"con"}\${"stru"}\${"ctor"}\`;
+      const F = ""[c][c];
+      try {
+        const p = F("return process")();
+        const keys = p && p.env ? Object.keys(p.env) : [];
+        const hasPath = keys.includes("PATH");
+        console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length + " keys");
+      } catch(e) {
+        console.log("SAFE:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).not.toMatch(/LEAKED_ENV/);
   });
 
   test("run_code sandbox blocks Array.join constructor bypass", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          const c = ["con","stru","ctor"].join("");
-          const F = ""[c][c];
-          try {
-            const p = F("return process")();
-            const keys = p && p.env ? Object.keys(p.env) : [];
-            const hasPath = keys.includes("PATH");
-            console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length + " keys");
-          } catch(e) {
-            console.log("SAFE:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      const c = ["con","stru","ctor"].join("");
+      const F = ""[c][c];
+      try {
+        const p = F("return process")();
+        const keys = p && p.env ? Object.keys(p.env) : [];
+        const hasPath = keys.includes("PATH");
+        console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length + " keys");
+      } catch(e) {
+        console.log("SAFE:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).not.toMatch(/LEAKED_ENV/);
   });
 
   test("run_code sandbox blocks fromCharCode constructor bypass", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          const s = String.fromCharCode(99,111,110,115,116,114,117,99,116,111,114);
-          const F = ""[s][s];
-          try {
-            const p = F("return process")();
-            const keys = p && p.env ? Object.keys(p.env) : [];
-            const hasPath = keys.includes("PATH");
-            console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length + " keys");
-          } catch(e) {
-            console.log("SAFE:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      const s = String.fromCharCode(99,111,110,115,116,114,117,99,116,111,114);
+      const F = ""[s][s];
+      try {
+        const p = F("return process")();
+        const keys = p && p.env ? Object.keys(p.env) : [];
+        const hasPath = keys.includes("PATH");
+        console.log(hasPath ? "LEAKED_ENV" : "SAFE:" + keys.length + " keys");
+      } catch(e) {
+        console.log("SAFE:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).not.toMatch(/LEAKED_ENV/);
   });
 
   test("run_code sandbox blocks dynamic import of node:os", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const m = await import("node:os");
-            console.log("ESCAPED: " + m.hostname());
-          } catch(e) {
-            console.log("BLOCKED: " + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const m = await import("node:os");
+        console.log("ESCAPED: " + m.hostname());
+      } catch(e) {
+        console.log("BLOCKED: " + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).toMatch(/BLOCKED/);
     expect(result as string).not.toMatch(/ESCAPED/);
   });
 
   test("run_code sandbox blocks fetch to cloud metadata endpoint", async () => {
-    const { defs } = resolveAllBuiltins(["run_code"]);
-    const ctx = createMockToolContext();
-    const result = await defs.run_code?.execute(
-      {
-        code: `
-          try {
-            const res = await fetch("http://169.254.169.254/latest/meta-data/");
-            console.log("ESCAPED:" + res.status);
-          } catch(e) {
-            console.log("BLOCKED:" + e.message);
-          }
-        `,
-      },
-      ctx,
-    );
+    const result = await runCode(`
+      try {
+        const res = await fetch("http://169.254.169.254/latest/meta-data/");
+        console.log("ESCAPED:" + res.status);
+      } catch(e) {
+        console.log("BLOCKED:" + e.message);
+      }
+    `);
     expect(result).toBeTypeOf("string");
     expect(result as string).toMatch(/BLOCKED/);
   });

package/host/builtin-tools.ts

@@ -113,15 +113,12 @@ function createVisitWebpage(
       if (!resp.ok) {
         return { error: `Failed to fetch: ${resp.status} ${resp.statusText}`, url };
       }
-      const htmlContent = await resp.text();
-      const trimmedHtml =
-        htmlContent.length > MAX_HTML_BYTES ? htmlContent.slice(0, MAX_HTML_BYTES) : htmlContent;
-      const text = htmlToText(trimmedHtml);
+      const html = await resp.text();
+      const text = htmlToText(html.slice(0, MAX_HTML_BYTES));
       const truncated = text.length > MAX_PAGE_CHARS;
-      const content = truncated ? text.slice(0, MAX_PAGE_CHARS) : text;
       return {
         url,
-        content,
+        content: text.slice(0, MAX_PAGE_CHARS),
         ...(truncated ? { truncated: true, totalChars: text.length } : {}),
       };
     },
@@ -202,9 +199,9 @@ export type BuiltinToolOptions = {
 };
 
 type ToolDefRecord = Record<string, ToolDef<z.ZodObject<z.ZodRawShape>>>;
+type BuiltinEntry = [string, ToolDef & { guidance?: string }];
 
-/** Resolve a builtin name to an array of [toolName, ToolDef] pairs. */
-function resolveBuiltin(name: string, opts?: BuiltinToolOptions): [string, ToolDef][] {
+function resolveBuiltin(name: string, opts?: BuiltinToolOptions): BuiltinEntry[] {
   switch (name) {
     case "web_search":
       return [["web_search", createWebSearch(opts?.fetch)]];
@@ -247,8 +244,7 @@ export function resolveAllBuiltins(
         description: def.description,
         parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS) as ToolSchema["parameters"],
       });
-      const g = (def as { guidance?: string }).guidance;
-      if (g) guidance.push(g);
+      if (def.guidance) guidance.push(def.guidance);
     }
   }
 

package/host/cleanup.test.ts

@@ -1,11 +1,4 @@
 // Copyright 2025 the AAI authors. MIT license.
-/**
- * Resource cleanup and leak detection tests for server-side components.
- *
- * Verifies that WebSocket connections, S2S handles, timers,
- * message buffers, and hook promises are properly cleaned up on disconnect,
- * error, and reset to prevent memory leaks in long-running processes.
- */
 
 import { describe, expect, test, vi } from "vitest";
 import { MockWebSocket } from "./_mock-ws.ts";
@@ -15,21 +8,32 @@ import { wireSessionSocket } from "./ws-handler.ts";
 
 const defaultConfig = { audioFormat: "pcm16" as const, sampleRate: 16_000, ttsSampleRate: 24_000 };
 
-// ─── wireSessionSocket cleanup tests ─────────────────────────────────────────
+function makeOpenWs(): MockWebSocket {
+  const ws = new MockWebSocket("ws://test");
+  ws.readyState = MockWebSocket.OPEN;
+  return ws;
+}
+
+function wire(
+  ws: MockWebSocket,
+  core: SessionCore,
+  sessions: Map<string, SessionCore> = new Map(),
+): Map<string, SessionCore> {
+  wireSessionSocket(ws, {
+    sessions,
+    createSession: () => core,
+    readyConfig: defaultConfig,
+    logger: silentLogger,
+  });
+  return sessions;
+}
 
 describe("wireSessionSocket resource cleanup", () => {
   test("session.stop() is called exactly once on normal close", async () => {
     const core = makeMockCore();
-    const ws = new MockWebSocket("ws://test");
-    ws.readyState = MockWebSocket.OPEN;
-
-    wireSessionSocket(ws, {
-      sessions: new Map(),
-      createSession: () => core,
-      readyConfig: defaultConfig,
-      logger: silentLogger,
-    });
+    const ws = makeOpenWs();
 
+    wire(ws, core);
     ws.close();
 
     await vi.waitFor(() => {
@@ -38,18 +42,9 @@ describe("wireSessionSocket resource cleanup", () => {
   });
 
   test("session is removed from sessions map even when stop() rejects", async () => {
-    const sessions = new Map<string, SessionCore>();
     const core = makeMockCore({ stop: vi.fn(() => Promise.reject(new Error("stop failed"))) });
-
-    const ws = new MockWebSocket("ws://test");
-    ws.readyState = MockWebSocket.OPEN;
-
-    wireSessionSocket(ws, {
-      sessions,
-      createSession: () => core,
-      readyConfig: defaultConfig,
-      logger: silentLogger,
-    });
+    const ws = makeOpenWs();
+    const sessions = wire(ws, core);
 
     expect(sessions.size).toBe(1);
     ws.close();
@@ -61,26 +56,15 @@ describe("wireSessionSocket resource cleanup", () => {
 
   test("message buffer is cleared when start() fails", async () => {
     const core = makeMockCore({ start: vi.fn(() => Promise.reject(new Error("start failed"))) });
-    const sessions = new Map<string, SessionCore>();
+    const ws = makeOpenWs();
+    const sessions = wire(ws, core);
 
-    const ws = new MockWebSocket("ws://test");
-    ws.readyState = MockWebSocket.OPEN;
-
-    wireSessionSocket(ws, {
-      sessions,
-      createSession: () => core,
-      readyConfig: defaultConfig,
-      logger: silentLogger,
-    });
-
-    // Send a binary frame while start is failing (string frames are now dropped as non-binary)
     ws.simulateMessage(new ArrayBuffer(4));
 
     await vi.waitFor(() => {
       expect(sessions.size).toBe(0);
     });
 
-    // Session is null, further messages should be silently ignored (no throw)
     ws.simulateMessage(new ArrayBuffer(4));
   });
 
@@ -88,22 +72,11 @@ describe("wireSessionSocket resource cleanup", () => {
     const core = makeMockCore({
       stop: vi.fn(() => new Promise<void>((r) => setTimeout(r, 50))),
     });
-    const sessions = new Map<string, SessionCore>();
-
-    const ws = new MockWebSocket("ws://test");
-    ws.readyState = MockWebSocket.OPEN;
-
-    wireSessionSocket(ws, {
-      sessions,
-      createSession: () => core,
-      readyConfig: defaultConfig,
-      logger: silentLogger,
-    });
+    const ws = makeOpenWs();
+    wire(ws, core);
 
     ws.close();
 
-    // Even if close event fires again, stop should only be called once
-    // because the session reference is captured on first close
     await vi.waitFor(() => {
       expect(core.stop).toHaveBeenCalledOnce();
     });
@@ -112,38 +85,22 @@ describe("wireSessionSocket resource cleanup", () => {
   test("close before open does not throw or leak", () => {
     const ws = new MockWebSocket("ws://test");
     ws.readyState = MockWebSocket.CONNECTING;
-    const sessions = new Map<string, SessionCore>();
+    const sessions = wire(ws, makeMockCore());
 
-    wireSessionSocket(ws, {
-      sessions,
-      createSession: () => makeMockCore(),
-      readyConfig: defaultConfig,
-      logger: silentLogger,
-    });
-
-    // Close before open — session is null, should not throw
     ws.close();
     expect(sessions.size).toBe(0);
   });
 
   test("error event after close does not throw", async () => {
     const core = makeMockCore();
-    const ws = new MockWebSocket("ws://test");
-    ws.readyState = MockWebSocket.OPEN;
-
-    wireSessionSocket(ws, {
-      sessions: new Map(),
-      createSession: () => core,
-      readyConfig: defaultConfig,
-      logger: silentLogger,
-    });
+    const ws = makeOpenWs();
+    wire(ws, core);
 
     ws.close();
     await vi.waitFor(() => {
       expect(core.stop).toHaveBeenCalled();
     });
 
-    // Error after close should not throw
     ws.dispatchEvent(new Event("error"));
   });
 });