@pensar/apex 2.5.0 → 2.6.1-canary.0cc77dcc

package/src/core/agents/offSecAgent/tools/playwrightMcp.test.ts

@@ -0,0 +1,778 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  collectDescendantPids,
+  collectPidsByEnvMarker,
+  createBrowserTools,
+  PlaywrightMcpSession,
+  parseStorageStateResult,
+  setViewportSize,
+  transformScriptToFunction,
+} from "./playwrightMcp";
+
+describe("transformScriptToFunction", () => {
+  describe("plain expressions", () => {
+    it("wraps simple expression in arrow function", () => {
+      expect(transformScriptToFunction("document.cookie")).toBe(
+        "() => (document.cookie)",
+      );
+    });
+
+    it("wraps complex expression", () => {
+      expect(transformScriptToFunction("localStorage.getItem('token')")).toBe(
+        "() => (localStorage.getItem('token'))",
+      );
+    });
+
+    it("handles expression with whitespace", () => {
+      expect(transformScriptToFunction("  document.title  ")).toBe(
+        "() => (  document.title  )",
+      );
+    });
+  });
+
+  describe("function expressions", () => {
+    it("passes through arrow function", () => {
+      const fn = "() => document.cookie";
+      expect(transformScriptToFunction(fn)).toBe(fn);
+    });
+
+    it("passes through arrow function with body", () => {
+      const fn = "() => { return document.cookie; }";
+      expect(transformScriptToFunction(fn)).toBe(fn);
+    });
+
+    it("passes through async arrow function", () => {
+      const fn = "async () => fetch('/api')";
+      expect(transformScriptToFunction(fn)).toBe(fn);
+    });
+
+    it("passes through function expression", () => {
+      const fn = "function() { return document.cookie; }";
+      expect(transformScriptToFunction(fn)).toBe(fn);
+    });
+
+    it("passes through async function expression", () => {
+      const fn = "async function() { return await fetch('/api'); }";
+      expect(transformScriptToFunction(fn)).toBe(fn);
+    });
+
+    it("handles arrow function with parameters", () => {
+      const fn = "(a, b) => a + b";
+      expect(transformScriptToFunction(fn)).toBe(fn);
+    });
+  });
+
+  describe("IIFEs", () => {
+    it("extracts function from simple arrow IIFE", () => {
+      const iife = "(() => document.cookie)()";
+      expect(transformScriptToFunction(iife)).toBe("() => document.cookie");
+    });
+
+    it("extracts function from arrow IIFE with body", () => {
+      const iife = `(() => {
+  const tokens = {};
+  return tokens;
+})()`;
+      const expected = `() => {
+  const tokens = {};
+  return tokens;
+}`;
+      expect(transformScriptToFunction(iife)).toBe(expected);
+    });
+
+    it("extracts function from complex arrow IIFE (from bug report)", () => {
+      const iife = `(() => {
+  const tokens = {};
+  const keys = ['token', 'access_token', 'accessToken', 'auth_token', 'jwt', 'id_token'];
+  keys.forEach(key => {
+    const lsVal = localStorage.getItem(key);
+    const ssVal = sessionStorage.getItem(key);
+    if (lsVal) tokens[key + '_localStorage'] = lsVal;
+    if (ssVal) tokens[key + '_sessionStorage'] = ssVal;
+  });
+  return JSON.stringify(tokens, null, 2);
+})()
+`;
+      const result = transformScriptToFunction(iife);
+      expect(result).toContain("() => {");
+      expect(result).toContain("const tokens = {};");
+      expect(result).toContain("return JSON.stringify(tokens, null, 2);");
+      expect(result).not.toContain(")()");
+    });
+
+    it("extracts function from async arrow IIFE", () => {
+      const iife = "(async () => await fetch('/api'))()";
+      expect(transformScriptToFunction(iife)).toBe(
+        "async () => await fetch('/api')",
+      );
+    });
+
+    it("extracts function from function IIFE", () => {
+      const iife = "(function() { return document.cookie; })()";
+      expect(transformScriptToFunction(iife)).toBe(
+        "function() { return document.cookie; }",
+      );
+    });
+
+    it("extracts function from async function IIFE", () => {
+      const iife = "(async function() { return await fetch('/api'); })()";
+      expect(transformScriptToFunction(iife)).toBe(
+        "async function() { return await fetch('/api'); }",
+      );
+    });
+
+    it("handles IIFE with trailing semicolon", () => {
+      const iife = "(() => document.cookie)();";
+      expect(transformScriptToFunction(iife)).toBe("() => document.cookie");
+    });
+
+    it("handles IIFE with whitespace in invocation", () => {
+      const iife = "(() => document.cookie)(  )";
+      expect(transformScriptToFunction(iife)).toBe("() => document.cookie");
+    });
+
+    it("handles IIFE with trailing whitespace", () => {
+      const iife = "(() => document.cookie)()   ";
+      expect(transformScriptToFunction(iife)).toBe("() => document.cookie");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles function that returns a function call", () => {
+      const fn = "() => doSomething()";
+      expect(transformScriptToFunction(fn)).toBe(fn);
+    });
+
+    it("does not mis-identify function call as IIFE", () => {
+      const expr = "myFunction()";
+      expect(transformScriptToFunction(expr)).toBe("() => (myFunction())");
+    });
+
+    it("handles JSON stringify in expression", () => {
+      const expr = "JSON.stringify({a: 1})";
+      expect(transformScriptToFunction(expr)).toBe(
+        "() => (JSON.stringify({a: 1}))",
+      );
+    });
+
+    it("handles empty parentheses expression", () => {
+      const expr = "()";
+      expect(transformScriptToFunction(expr)).toBe("()");
+    });
+  });
+});
+
+describe("PlaywrightMcpSession — constructor defaults", () => {
+  // Internal field accessor — we don't want to expose getters publicly,
+  // but the defaults invariant is important enough to assert directly.
+  type InternalShape = {
+    headless: boolean;
+    userAgent: string | undefined;
+    viewportSize: string | undefined;
+    display: string | undefined;
+    engine: string;
+  };
+
+  it("defaults to headless + desktop UA + 1920x1080 when constructed with no args and no display (regression: don't fall back to Chromium's tiny default viewport)", () => {
+    // The headless default is DISPLAY-aware (headed when a virtual display is
+    // present), so pin DISPLAY off to assert the no-display contract
+    // deterministically regardless of the host environment.
+    const originalDisplay = process.env.DISPLAY;
+    delete process.env.DISPLAY;
+    try {
+      const session = new PlaywrightMcpSession() as unknown as InternalShape;
+      expect(session.headless).toBe(true);
+      expect(session.viewportSize).toBe("1920,1080");
+      expect(session.userAgent).toContain("Chrome/");
+      expect(session.engine).toBe("camoufox");
+    } finally {
+      if (originalDisplay === undefined) delete process.env.DISPLAY;
+      else process.env.DISPLAY = originalDisplay;
+    }
+  });
+
+  it("uses explicit values when provided", () => {
+    const session = new PlaywrightMcpSession({
+      headless: false,
+      userAgent: "MyAgent/1.0",
+      viewportSize: "800,600",
+      engine: "chrome",
+    }) as unknown as InternalShape;
+    expect(session.headless).toBe(false);
+    expect(session.userAgent).toBe("MyAgent/1.0");
+    expect(session.viewportSize).toBe("800,600");
+    expect(session.engine).toBe("chrome");
+  });
+
+  it("launches Chrome without the Chromium sandbox so it starts as root", async () => {
+    const session = new PlaywrightMcpSession({
+      headless: true,
+      engine: "chrome",
+    }) as unknown as {
+      buildMcpLaunch(id: string): Promise<{
+        cfg: { browser: { launchOptions: Record<string, unknown> } };
+      }>;
+    };
+    const { cfg } = await session.buildMcpLaunch("test");
+    expect(cfg.browser.launchOptions.channel).toBe("chrome");
+    expect(cfg.browser.launchOptions.chromiumSandbox).toBe(false);
+  });
+
+  it("keeps scoped credentials out of global context options", async () => {
+    const session = new PlaywrightMcpSession({
+      engine: "chrome",
+      headerPolicy: {
+        allowedHosts: ["example.com"],
+        headers: { "X-Scoped-Secret": "secret" },
+      },
+    }) as unknown as {
+      buildMcpLaunch(id: string): Promise<{ cfg: unknown }>;
+    };
+
+    const { cfg } = await session.buildMcpLaunch("test");
+    expect(JSON.stringify(cfg)).not.toContain("extraHTTPHeaders");
+    expect(JSON.stringify(cfg)).not.toContain("X-Scoped-Secret");
+  });
+
+  it("installs scoped header routing through browser_run_code", async () => {
+    const session = new PlaywrightMcpSession({
+      headerPolicy: {
+        allowedHosts: ["example.com"],
+        headers: { "X-Scoped-Secret": "secret" },
+      },
+    });
+    const callTool = vi.fn(async (_request: unknown) => ({}));
+    const internal = session as unknown as {
+      installHeaderRoute(client: { callTool: typeof callTool }): Promise<void>;
+    };
+
+    await internal.installHeaderRoute({ callTool });
+
+    expect(callTool).toHaveBeenCalledTimes(1);
+    const request = callTool.mock.calls[0]?.[0] as unknown as {
+      name: string;
+      arguments: { code: string };
+    };
+    expect(request.name).toBe("browser_run_code");
+    expect(request.arguments.code).toContain("context.route('**/*'");
+    expect(request.arguments.code).toContain("X-Scoped-Secret");
+    expect(request.arguments.code).not.toContain("extraHTTPHeaders");
+  });
+
+  it("treats explicit null as 'opt out of the default' (let Chromium pick its built-in)", () => {
+    const session = new PlaywrightMcpSession({
+      headless: true,
+      userAgent: null,
+      viewportSize: null,
+    }) as unknown as InternalShape;
+    expect(session.userAgent).toBeUndefined();
+    expect(session.viewportSize).toBeUndefined();
+  });
+
+  describe("DISPLAY-aware headless default", () => {
+    const originalDisplay = process.env.DISPLAY;
+    afterEach(() => {
+      if (originalDisplay === undefined) delete process.env.DISPLAY;
+      else process.env.DISPLAY = originalDisplay;
+    });
+
+    it("defaults to headed when a virtual display is present and no explicit headless is given", () => {
+      process.env.DISPLAY = ":1";
+      const session = new PlaywrightMcpSession() as unknown as InternalShape;
+      expect(session.headless).toBe(false);
+    });
+
+    it("defaults to headless when no display is present", () => {
+      delete process.env.DISPLAY;
+      const session = new PlaywrightMcpSession() as unknown as InternalShape;
+      expect(session.headless).toBe(true);
+    });
+
+    it("respects an explicit headless=true even when a display is present", () => {
+      process.env.DISPLAY = ":1";
+      const session = new PlaywrightMcpSession({
+        headless: true,
+      }) as unknown as InternalShape;
+      expect(session.headless).toBe(true);
+    });
+
+    it("an explicit display option defaults to headed and overrides process.env.DISPLAY", () => {
+      // Pin the process-wide display to a different value (or absent) to prove
+      // the per-session option wins — this is what lets concurrent headed
+      // sessions in one process each target their own virtual desktop.
+      process.env.DISPLAY = ":1";
+      const session = new PlaywrightMcpSession({
+        display: ":11",
+      }) as unknown as InternalShape;
+      expect(session.display).toBe(":11");
+      expect(session.headless).toBe(false);
+    });
+
+    it("falls back to process.env.DISPLAY when no explicit display is given", () => {
+      process.env.DISPLAY = ":7";
+      const session = new PlaywrightMcpSession() as unknown as InternalShape;
+      expect(session.display).toBe(":7");
+    });
+
+    it("an explicit display still yields headed even with no process-wide display", () => {
+      delete process.env.DISPLAY;
+      const session = new PlaywrightMcpSession({
+        display: ":12",
+      }) as unknown as InternalShape;
+      expect(session.display).toBe(":12");
+      expect(session.headless).toBe(false);
+    });
+  });
+
+  describe("display-tier viewport defaults", () => {
+    const originalDisplay = process.env.DISPLAY;
+    afterEach(() => {
+      if (originalDisplay === undefined) delete process.env.DISPLAY;
+      else process.env.DISPLAY = originalDisplay;
+      setViewportSize("1920,1080");
+    });
+
+    it("defaults endpoint-tier displays (:10+) to 1280x720", () => {
+      delete process.env.DISPLAY;
+      const session = new PlaywrightMcpSession({
+        display: ":11",
+      }) as unknown as InternalShape;
+      expect(session.viewportSize).toBe("1280,720");
+    });
+
+    it("defaults computer-use displays (:0–:9) to 1920x1080", () => {
+      delete process.env.DISPLAY;
+      const session = new PlaywrightMcpSession({
+        display: ":0",
+      }) as unknown as InternalShape;
+      expect(session.viewportSize).toBe("1920,1080");
+    });
+
+    it("uses process.env.DISPLAY for the tier when no explicit display is given", () => {
+      process.env.DISPLAY = ":12";
+      const session = new PlaywrightMcpSession() as unknown as InternalShape;
+      expect(session.viewportSize).toBe("1280,720");
+    });
+
+    it("lets an explicit viewportSize win over the display-tier default", () => {
+      const session = new PlaywrightMcpSession({
+        display: ":11",
+        viewportSize: "800,600",
+      }) as unknown as InternalShape;
+      expect(session.viewportSize).toBe("800,600");
+    });
+  });
+
+  it("falls back to a hardcoded 1920x1080 floor for viewport even if the module default was cleared (regression: don't ship a Chromium-tiny viewport just because someone called setViewportSize(undefined))", () => {
+    const original = "1920,1080";
+    try {
+      setViewportSize(undefined);
+      const session = new PlaywrightMcpSession() as unknown as InternalShape;
+      expect(session.viewportSize).toBe("1920,1080");
+    } finally {
+      // Restore the module default for any subsequent test.
+      setViewportSize(original);
+    }
+  });
+});
+
+describe("PlaywrightMcpSession.disconnect()", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  // Regression: disconnect() used to run forceKillProcess() AFTER resetState()
+  // had nulled this.mcpProcess (so the kill was a no-op) and AFTER awaiting
+  // client/transport.close(). A wedged MCP child made transport.close() hang
+  // forever, so disconnect() — and any caller awaiting it (the agent's
+  // consume() teardown) — hung, stranding an endpoint that had already
+  // finished. disconnect() must kill the child up front and never hang.
+  it("force-kills the child and resolves even when close() hangs forever", async () => {
+    const session = new PlaywrightMcpSession();
+    const kill = vi.fn();
+    const neverResolves = () => new Promise<void>(() => {});
+    // Inject wedged internals (no pid → forceKillProcess uses proc.kill()).
+    Object.assign(session as unknown as Record<string, unknown>, {
+      mcpProcess: { exitCode: null, kill },
+      mcpClient: { close: neverResolves },
+      mcpTransport: { close: neverResolves },
+    });
+
+    let settled = false;
+    const done = session.disconnect().then(() => {
+      settled = true;
+    });
+
+    // The child is SIGKILLed synchronously, before any await.
+    expect(kill).toHaveBeenCalledWith("SIGKILL");
+
+    // close() never resolves; the bounded race resolves disconnect() anyway.
+    await vi.advanceTimersByTimeAsync(5_000);
+    await done;
+    expect(settled).toBe(true);
+  });
+});
+
+// Regression: forceKillProcess() only group-killed the MCP node, which isn't a
+// process-group leader — so the kill fell back to killing just the node and
+// orphaned the Chromium it launched (reparented to init), leaking ~0.5GB per
+// completed endpoint until the sandbox OOM'd. collectDescendantPids enumerates
+// the browser tree so it can be SIGKILLed explicitly.
+describe("collectDescendantPids", () => {
+  const hasProc = existsSync("/proc/self");
+
+  (hasProc ? it : it.skip)(
+    "enumerates descendant processes spawned under a parent",
+    async () => {
+      // sh forks two background `sleep` children we can discover + reap.
+      const parent = spawn("sh", ["-c", "sleep 30 & sleep 30 & wait"], {
+        stdio: "ignore",
+      });
+      const cleanup = (pids: number[]) => {
+        for (const pid of pids) {
+          try {
+            process.kill(pid, "SIGKILL");
+          } catch {
+            /* already gone */
+          }
+        }
+      };
+      try {
+        // Give sh a moment to fork its children.
+        await new Promise((r) => setTimeout(r, 400));
+        const descendants = collectDescendantPids(parent.pid!);
+        expect(descendants.length).toBeGreaterThanOrEqual(2);
+        cleanup([...descendants, parent.pid!]);
+      } finally {
+        cleanup([parent.pid!]);
+      }
+    },
+  );
+
+  (hasProc ? it : it.skip)("returns [] for a leaf pid with no children", () => {
+    // A made-up high pid that almost certainly has no children.
+    expect(collectDescendantPids(2_147_483_646)).toEqual([]);
+  });
+});
+
+// Regression: when the MCP node exits unexpectedly its Camoufox reparents to
+// init, so no ancestry lookup can reach it — ~1.5 GiB stranded per occurrence
+// until the sandbox OOM'd. The env marker survives reparenting.
+describe("collectPidsByEnvMarker — orphan reaping", () => {
+  const hasProc = existsSync("/proc/self");
+  const ENV_KEY = "PENSAR_BROWSER_LAUNCH_ID";
+
+  const killPids = (pids: number[]) => {
+    for (const pid of pids) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        /* already gone */
+      }
+    }
+  };
+
+  /** `sh` backgrounds a sleep then exits, orphaning it as a dying node orphans
+   *  Camoufox. Returns the (now dead) parent pid. */
+  const spawnOrphan = async (marker: string): Promise<number> => {
+    const parent = spawn("sh", ["-c", "sleep 30 &"], {
+      stdio: "ignore",
+      env: { ...process.env, [ENV_KEY]: marker },
+    });
+    await new Promise((r) => setTimeout(r, 500));
+    return parent.pid!;
+  };
+
+  (hasProc ? it : it.skip)(
+    "finds an orphan by marker after its parent is gone, where ancestry finds nothing",
+    async () => {
+      const marker = `test-${process.pid}-${Date.now()}`;
+      const parentPid = await spawnOrphan(marker);
+      try {
+        // The parent exited, so the ancestry walk is blind to the orphan...
+        expect(collectDescendantPids(parentPid)).toEqual([]);
+        // ...but it still carries the launch marker.
+        expect(
+          collectPidsByEnvMarker(ENV_KEY, marker).length,
+        ).toBeGreaterThanOrEqual(1);
+      } finally {
+        killPids([parentPid, ...collectPidsByEnvMarker(ENV_KEY, marker)]);
+      }
+    },
+  );
+
+  (hasProc ? it : it.skip)(
+    "forceKillProcess still reaps when the child handle is already dead (the early-return bug)",
+    async () => {
+      const marker = `test-dead-handle-${process.pid}-${Date.now()}`;
+      const parentPid = await spawnOrphan(marker);
+      try {
+        expect(
+          collectPidsByEnvMarker(ENV_KEY, marker).length,
+        ).toBeGreaterThanOrEqual(1);
+
+        const session = new PlaywrightMcpSession();
+        Object.assign(session as unknown as Record<string, unknown>, {
+          // A non-null exitCode used to short-circuit the whole method.
+          mcpProcess: { exitCode: 0, pid: parentPid, kill: () => {} },
+          currentLaunchId: marker,
+        });
+        (
+          session as unknown as { forceKillProcess: () => void }
+        ).forceKillProcess();
+
+        await new Promise((r) => setTimeout(r, 400));
+        expect(collectPidsByEnvMarker(ENV_KEY, marker)).toEqual([]);
+      } finally {
+        killPids([parentPid, ...collectPidsByEnvMarker(ENV_KEY, marker)]);
+      }
+    },
+  );
+
+  // A relaunch overwrites currentLaunchId. If teardown swept "whatever is
+  // current" rather than its own generation, a late onclose from the previous
+  // generation would kill the freshly launched browser.
+  (hasProc ? it : it.skip)(
+    "sweeps only the generation it was given, leaving a newer launch alone",
+    async () => {
+      const oldMarker = `gen1-${process.pid}-${Date.now()}`;
+      const newMarker = `gen2-${process.pid}-${Date.now()}`;
+      const oldPid = await spawnOrphan(oldMarker);
+      const newPid = await spawnOrphan(newMarker);
+      try {
+        const session = new PlaywrightMcpSession();
+        Object.assign(session as unknown as Record<string, unknown>, {
+          mcpProcess: null,
+          currentLaunchId: newMarker, // a relaunch already moved this on
+        });
+        (
+          session as unknown as {
+            forceKillProcess: (p: unknown, l: string) => void;
+          }
+        ).forceKillProcess(null, oldMarker);
+
+        await new Promise((r) => setTimeout(r, 400));
+        expect(collectPidsByEnvMarker(ENV_KEY, oldMarker)).toEqual([]);
+        expect(
+          collectPidsByEnvMarker(ENV_KEY, newMarker).length,
+        ).toBeGreaterThanOrEqual(1);
+      } finally {
+        killPids([
+          oldPid,
+          newPid,
+          ...collectPidsByEnvMarker(ENV_KEY, oldMarker),
+          ...collectPidsByEnvMarker(ENV_KEY, newMarker),
+        ]);
+      }
+    },
+  );
+
+  (hasProc ? it : it.skip)("does not match an unrelated marker value", () => {
+    expect(collectPidsByEnvMarker(ENV_KEY, `absent-${Date.now()}`)).toEqual([]);
+  });
+
+  it("is a no-op when the session has no launch marker yet", () => {
+    const session = new PlaywrightMcpSession();
+    expect(() =>
+      (
+        session as unknown as { forceKillProcess: () => void }
+      ).forceKillProcess(),
+    ).not.toThrow();
+  });
+});
+
+describe("parseStorageStateResult", () => {
+  it("returns null for null/undefined input", () => {
+    expect(parseStorageStateResult(null)).toBeNull();
+    expect(parseStorageStateResult(undefined)).toBeNull();
+  });
+
+  it("parses the Playwright-MCP wrapped string format", () => {
+    const wrapped = `### Result\n{"cookies":[{"name":"a","value":"b","domain":"x","path":"/"}],"origins":[]}\n\n### Ran Playwright code\nfoo`;
+    const out = parseStorageStateResult(wrapped);
+    expect(out).not.toBeNull();
+    expect(out?.cookies[0].name).toBe("a");
+    expect(out?.origins).toEqual([]);
+  });
+
+  it("falls back to a regex JSON extract for unwrapped strings", () => {
+    const raw = `garbage prefix {"cookies":[],"origins":[{"origin":"https://x","localStorage":[]}]} trailing`;
+    const out = parseStorageStateResult(raw);
+    expect(out).not.toBeNull();
+    expect(out?.origins[0].origin).toBe("https://x");
+  });
+
+  it("accepts a pre-parsed object directly", () => {
+    const obj = { cookies: [], origins: [] };
+    expect(parseStorageStateResult(obj)).toEqual(obj);
+  });
+
+  it("rejects objects without a cookies field", () => {
+    expect(parseStorageStateResult({ foo: 1 })).toBeNull();
+  });
+
+  it("rejects strings that are not valid JSON storageState payloads", () => {
+    expect(parseStorageStateResult("totally not json")).toBeNull();
+  });
+});
+
+describe("createBrowserTools — shared session reuse", () => {
+  let evidenceDir: string;
+
+  beforeEach(() => {
+    evidenceDir = mkdtempSync(join(tmpdir(), "apex-pw-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(evidenceDir, { recursive: true, force: true });
+  });
+
+  it("reuses an existing PlaywrightMcpSession when one is provided", async () => {
+    const sharedSession = new PlaywrightMcpSession();
+    const callTool = vi
+      .spyOn(sharedSession, "callTool")
+      // biome-ignore lint/suspicious/noExplicitAny: stubbing a private MCP transport for the test.
+      .mockResolvedValue({ ok: true } as any);
+
+    const tools = createBrowserTools(
+      "https://example.com",
+      evidenceDir,
+      "operator",
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      sharedSession,
+    );
+
+    // Invoke a browser tool; it should call through to the SHARED session.
+    await tools.browser_navigate.execute?.(
+      { url: "https://example.com/login", toolCallDescription: "test" },
+      // biome-ignore lint/suspicious/noExplicitAny: ai-sdk ToolCallOptions is opaque and irrelevant for this test.
+      { toolCallId: "tc1", messages: [], abortSignal: undefined } as any,
+    );
+
+    expect(callTool).toHaveBeenCalledTimes(1);
+    expect(callTool).toHaveBeenCalledWith(
+      "browser_navigate",
+      { url: "https://example.com/login" },
+      undefined,
+    );
+  });
+
+  it("captureStorageState returns null when the session has never connected", async () => {
+    const session = new PlaywrightMcpSession();
+    expect(session.isConnected()).toBe(false);
+    const state = await session.captureStorageState();
+    expect(state).toBeNull();
+  });
+
+  it("captureStorageState parses a Playwright-MCP wrapped storageState response", async () => {
+    const session = new PlaywrightMcpSession();
+    vi.spyOn(session, "isConnected").mockReturnValue(true);
+
+    const wrapped = `### Result\n${JSON.stringify({
+      cookies: [
+        {
+          name: "session",
+          value: "abc123",
+          domain: "example.com",
+          path: "/",
+          httpOnly: true,
+          secure: true,
+          sameSite: "Lax" as const,
+        },
+      ],
+      origins: [
+        {
+          origin: "https://example.com",
+          localStorage: [{ name: "uid", value: "alice" }],
+        },
+      ],
+    })}\n\n### Ran Playwright code\nawait page.context().storageState()`;
+
+    vi.spyOn(session, "callTool").mockResolvedValue(wrapped);
+
+    const state = await session.captureStorageState();
+    expect(state).not.toBeNull();
+    expect(state?.cookies).toHaveLength(1);
+    expect(state?.cookies[0].name).toBe("session");
+    expect(state?.origins).toHaveLength(1);
+    expect(state?.origins[0].localStorage[0].value).toBe("alice");
+  });
+
+  it("seedStorageState forwards cookies + origins into a browser_run_code call", async () => {
+    const session = new PlaywrightMcpSession();
+    // Skip the real MCP spawn — seedStorageState calls initialize first.
+    vi.spyOn(session, "initialize").mockResolvedValue({} as never);
+    const callSpy = vi.spyOn(session, "callTool").mockResolvedValue({});
+
+    const state = {
+      cookies: [
+        {
+          name: "session",
+          value: "tok",
+          domain: "example.com",
+          path: "/",
+          httpOnly: false,
+          secure: true,
+          sameSite: "Lax" as const,
+        },
+      ],
+      origins: [
+        {
+          origin: "https://example.com",
+          localStorage: [{ name: "uid", value: "alice" }],
+        },
+      ],
+    };
+
+    await session.seedStorageState(state);
+
+    expect(callSpy).toHaveBeenCalledTimes(1);
+    const [toolName, args] = callSpy.mock.calls[0] as [
+      string,
+      { code: string },
+    ];
+    expect(toolName).toBe("browser_run_code");
+    // The injected code carries the cookies + localStorage payload verbatim.
+    expect(args.code).toContain('"name":"session"');
+    expect(args.code).toContain('"uid"');
+    expect(args.code).toContain("addCookies");
+    expect(args.code).toContain("addInitScript");
+  });
+
+  it("does not register an abort handler that would tear down a borrowed session", async () => {
+    const sharedSession = new PlaywrightMcpSession();
+    const disconnectSpy = vi
+      .spyOn(sharedSession, "disconnect")
+      .mockResolvedValue(undefined);
+
+    const controller = new AbortController();
+
+    createBrowserTools(
+      "https://example.com",
+      evidenceDir,
+      "operator",
+      undefined,
+      controller.signal,
+      undefined,
+      undefined,
+      undefined,
+      sharedSession,
+    );
+
+    // Aborting the SUB-AGENT's signal must NOT disconnect the parent's
+    // shared browser session — only the original owner is allowed to
+    // tear it down.
+    controller.abort();
+    // Give the (non-)abort listener a chance to fire.
+    await new Promise((r) => setTimeout(r, 5));
+
+    expect(disconnectSpy).not.toHaveBeenCalled();
+  });
+});