@pensar/apex 2.5.0 → 2.6.1-canary.025b1ecf

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

@@ -0,0 +1,1426 @@
+/**
+ * Playwright MCP Browser Tools
+ *
+ * Provides browser automation via Playwright MCP server.
+ *
+ * Two modes:
+ * - "pentest": Automated pentesting agent - XSS validation, form-based attacks, evidence collection
+ * - "operator": User-driven operator mode - SPA reconnaissance, authenticated flows, attack surface mapping
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { BrowserBackend } from "../../../tools/backends/types";
+import {
+  type BrowserHeaderPolicy,
+  browserHeaderRouteFunction,
+} from "./browserHeaderRouting";
+import {
+  type BrowserToolMode,
+  createBackendBrowserToolFactories,
+} from "./browserToolFactories";
+
+export type { BrowserToolMode } from "./browserToolFactories";
+
+import type { Logger } from "../../../logger";
+import {
+  type CamoufoxLaunchOptions,
+  COMPUTER_USE_VIEWPORT_SIZE,
+  ENDPOINT_DISPLAY_BASE,
+  ENDPOINT_VIEWPORT_SIZE,
+  ensureCamoufox,
+  parseDisplayNumber,
+  parseViewportSize,
+  resolveCamoufoxLaunchOptions,
+} from "./camoufox";
+
+/**
+ * Playwright `BrowserContext.storageState()` shape — the JSON-serialisable
+ * snapshot of cookies + per-origin storage that Playwright uses to round-trip
+ * authentication state between contexts.
+ */
+export interface BrowserStorageState {
+  cookies: Array<{
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+  }>;
+  origins: Array<{
+    origin: string;
+    localStorage: Array<{ name: string; value: string }>;
+  }>;
+}
+
+// Types for tool results
+export interface BrowserNavigateResult {
+  success: boolean;
+  url: string;
+  title?: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface BrowserScreenshotResult {
+  success: boolean;
+  path?: string;
+  message?: string;
+  error?: string;
+}
+
+export interface BrowserClickResult {
+  success: boolean;
+  element?: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface BrowserFillResult {
+  success: boolean;
+  element?: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface BrowserEvaluateResult {
+  success: boolean;
+  script?: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface BrowserConsoleResult {
+  success: boolean;
+  messages?: Array<{ type: string; text: string }>;
+  result?: unknown;
+  error?: string;
+}
+
+const MCP_CONNECT_TIMEOUT_MS = 30_000;
+const MCP_TOOL_CALL_TIMEOUT_MS = 60_000;
+
+/**
+ * Transform a user-provided script into a function expression for Playwright's browser_evaluate.
+ *
+ * Handles three cases:
+ * 1. Plain expressions: `document.cookie` → `() => (document.cookie)`
+ * 2. Function expressions: `() => document.cookie` → unchanged
+ * 3. IIFEs: `(() => { ... })()` → `() => { ... }`
+ *
+ * IIFEs are problematic because they evaluate to a value, not a function,
+ * causing "result is not a function" errors when Playwright tries to call them.
+ *
+ * @internal Exported for testing
+ */
+export function transformScriptToFunction(script: string): string {
+  const trimmed = script.trim();
+
+  // Detect IIFE pattern: (function...)() or (() => ...)() or (async () => ...)()
+  // Must start with ( followed by (async )?(function or () and end with ()
+  const iifeTrailing = /\(\s*\)\s*;?\s*$/.test(trimmed);
+  const iifeLeading = /^\s*\((?:async\s+)?(?:function|\()/.test(trimmed);
+
+  if (iifeLeading && iifeTrailing) {
+    // This is an IIFE - extract the function without the trailing invocation ()
+    let extracted = trimmed.replace(/\(\s*\)\s*;?\s*$/, "").trim();
+    // Remove the outer wrapping parentheses: (fn) -> fn
+    if (extracted.startsWith("(") && extracted.endsWith(")")) {
+      extracted = extracted.slice(1, -1).trim();
+    }
+    return extracted;
+  }
+
+  // Regular function expression or plain expression
+  const isFunction =
+    /^\s*(async\s+)?\(/.test(script) ||
+    /^\s*(async\s+)?function\s*\(/.test(script);
+  return isFunction ? script : `() => (${script})`;
+}
+
+/**
+ * Parse the response payload from `browser_run_code` returning a
+ * `BrowserContext.storageState()` JSON object. Playwright MCP wraps results
+ * as `### Result\n<value>\n\n### Ran Playwright code\n...` strings, so we
+ * strip the prefix/suffix and JSON-parse the middle. Falls back to a JSON
+ * object regex extract for older MCP variants. Returns `null` for any
+ * shape we can't decode rather than throwing.
+ *
+ * @internal Exported for testing.
+ */
+export function parseStorageStateResult(
+  result: unknown,
+): BrowserStorageState | null {
+  if (!result) return null;
+
+  if (typeof result === "string") {
+    const stripped = result
+      .replace(/^###\s*Result\s*\n?/, "")
+      .replace(/\n\n###[\s\S]*$/, "")
+      .trim();
+    try {
+      const parsed = JSON.parse(stripped);
+      if (parsed && typeof parsed === "object" && "cookies" in parsed) {
+        return parsed as BrowserStorageState;
+      }
+      if (typeof parsed === "string") {
+        const inner = JSON.parse(parsed);
+        if (inner && typeof inner === "object" && "cookies" in inner) {
+          return inner as BrowserStorageState;
+        }
+      }
+    } catch {
+      const jsonMatch = stripped.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        try {
+          const inner = JSON.parse(jsonMatch[0]);
+          if (inner && typeof inner === "object" && "cookies" in inner) {
+            return inner as BrowserStorageState;
+          }
+        } catch {
+          /* fall through */
+        }
+      }
+    }
+    return null;
+  }
+
+  if (typeof result === "object" && "cookies" in (result as object)) {
+    return result as BrowserStorageState;
+  }
+
+  return null;
+}
+
+/**
+ * Race a promise against a timeout. Rejects with a descriptive error
+ * if the timeout fires first.
+ */
+function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  message: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Collect every descendant PID of `rootPid` by walking `/proc` parent links
+ * (Linux only). Returns `[]` on platforms without `/proc` (e.g. macOS dev),
+ * where the process-group SIGKILL path is relied on instead.
+ *
+ * Used to reap the Chromium browser tree a Playwright MCP `node` child
+ * launches. `StdioClientTransport` does not spawn that `node` as a
+ * process-group leader, so `process.kill(-pid)` fails and only the `node`
+ * dies — orphaning Chromium (reparented to init) and leaking ~0.5GB per
+ * completed endpoint until the sandbox OOMs. Enumerating descendants lets us
+ * SIGKILL the browser explicitly. Must be called BEFORE the parent is killed:
+ * once it dies its children reparent to init and are no longer reachable via
+ * its pid.
+ */
+/** `/proc/<pid>/stat` starttime (field 22) — used to refuse PID-reuse kills. */
+function readProcStartTime(pid: number): number | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const afterComm = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    const starttime = Number(afterComm[19]);
+    return Number.isFinite(starttime) ? starttime : null;
+  } catch {
+    return null;
+  }
+}
+
+export function collectDescendantPids(rootPid: number): number[] {
+  let entries: string[];
+  try {
+    entries = readdirSync("/proc");
+  } catch {
+    return [];
+  }
+
+  const childrenByPpid = new Map<number, number[]>();
+  for (const name of entries) {
+    if (!/^\d+$/.test(name)) continue;
+    const pid = Number(name);
+    let ppid: number;
+    try {
+      // /proc/<pid>/stat: "pid (comm) state ppid ...". comm can contain spaces
+      // and parens, so parse the ppid from after the final ')'.
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+      const afterComm = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+      ppid = Number(afterComm[1]);
+    } catch {
+      continue; // process exited between readdir and read
+    }
+    if (!Number.isFinite(ppid)) continue;
+    const list = childrenByPpid.get(ppid);
+    if (list) list.push(pid);
+    else childrenByPpid.set(ppid, [pid]);
+  }
+
+  const descendants: number[] = [];
+  const seen = new Set<number>([rootPid]);
+  const stack = [rootPid];
+  while (stack.length > 0) {
+    const pid = stack.pop()!;
+    for (const child of childrenByPpid.get(pid) ?? []) {
+      if (seen.has(child)) continue;
+      seen.add(child);
+      descendants.push(child);
+      stack.push(child);
+    }
+  }
+  return descendants;
+}
+
+/**
+ * Per-launch UUID inherited by the node child, Camoufox, and its content
+ * processes. Lets teardown find the tree by identity rather than ancestry,
+ * which breaks the moment the node dies and its browser reparents to init.
+ */
+const BROWSER_LAUNCH_ENV = "PENSAR_BROWSER_LAUNCH_ID";
+
+/** Live pids stamped with `key=value`; `/proc/<pid>/environ` is fixed at exec. */
+export function collectPidsByEnvMarker(key: string, value: string): number[] {
+  let entries: string[];
+  try {
+    entries = readdirSync("/proc");
+  } catch {
+    return [];
+  }
+
+  const needle = `${key}=${value}`;
+  const pids: number[] = [];
+  for (const name of entries) {
+    if (!/^\d+$/.test(name)) continue;
+    const pid = Number(name);
+    if (pid === process.pid) continue;
+    try {
+      if (
+        readFileSync(`/proc/${pid}/environ`, "utf8")
+          .split("\0")
+          .includes(needle)
+      ) {
+        pids.push(pid);
+      }
+    } catch {
+      // exited, or not ours to inspect
+    }
+  }
+  return pids;
+}
+
+// ---------------------------------------------------------------------------
+// Module-level defaults (used when not explicitly provided)
+// ---------------------------------------------------------------------------
+
+let defaultHeadless = true;
+
+/**
+ * Default User-Agent string for new browser sessions.
+ *
+ * Playwright MCP's Chromium default advertises `HeadlessChrome/…`, which is
+ * the single most common trigger for nginx / Cloudflare / generic-WAF 403s
+ * on targets we're otherwise authorised to test. Override the default to a
+ * real desktop Chrome UA so the browser isn't immediately fingerprinted as
+ * a headless bot at the edge.
+ */
+let defaultUserAgent: string | undefined =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+
+/**
+ * Hard floor for viewport size — used when both the explicit constructor
+ * arg and the module-level default are `undefined`, and the session is not
+ * on an endpoint-tier display. Guarantees that `new PlaywrightMcpSession()`
+ * always launches at a real desktop resolution and never silently falls
+ * back to Chromium's tiny built-in just because someone called
+ * `setViewportSize(undefined)`. Must match computer-use Xvfb (Console shim).
+ *
+ * The only way to opt out is to pass `null` explicitly to the constructor.
+ */
+const HARDCODED_VIEWPORT_FALLBACK = COMPUTER_USE_VIEWPORT_SIZE;
+
+/**
+ * Default viewport size (format: `WIDTH,HEIGHT`) for new browser sessions.
+ * 1920x1080 matches computer-use desktops; endpoint displays (`:10+`) override
+ * to 1280x720 in the constructor so Camoufox fills the streamed Xvfb.
+ */
+let defaultViewportSize: string | undefined = HARDCODED_VIEWPORT_FALLBACK;
+
+/**
+ * Configure the default headless mode for new browser sessions.
+ * Call this BEFORE any browser tools are created.
+ * Default is headless=true for normal operation.
+ */
+export function setHeadlessMode(headless: boolean): void {
+  defaultHeadless = headless;
+}
+
+/**
+ * Configure the default User-Agent for new browser sessions.
+ * Pass `undefined` to fall back to Chromium's built-in UA.
+ */
+export function setUserAgent(userAgent: string | undefined): void {
+  defaultUserAgent = userAgent;
+}
+
+/**
+ * Configure the default viewport size for new browser sessions.
+ * Format is `"WIDTH,HEIGHT"`, e.g. `"1920,1080"`.
+ * Pass `undefined` to fall back to Chromium's default viewport.
+ */
+export function setViewportSize(viewportSize: string | undefined): void {
+  defaultViewportSize = viewportSize;
+}
+
+export type BrowserEngine = "camoufox" | "chrome";
+
+export interface PlaywrightMcpSessionOptions {
+  readonly headless?: boolean;
+  readonly userAgent?: string | null;
+  readonly viewportSize?: string | null;
+  readonly headerPolicy?: BrowserHeaderPolicy;
+  /**
+   * Browser to launch. Camoufox (Firefox) is the default for pentest traffic.
+   * Chrome is required for Sign in with Google — Google blocks Camoufox.
+   */
+  readonly engine?: BrowserEngine;
+  /**
+   * X display for this session's spawned browser (e.g. `":11"`). Overrides
+   * `process.env.DISPLAY` for THIS session only. Required for per-agent display
+   * isolation: when several headed sessions run in one process (e.g. concurrent
+   * per-endpoint pentests), a single process-wide `DISPLAY` env can't separate
+   * them, so each is given its own display explicitly.
+   */
+  readonly display?: string;
+}
+
+/**
+ * Isolated MCP browser session.
+ *
+ * Each instance owns its own Playwright MCP child-process and browser.
+ * Create one per agent so concurrent agents never collide on the same
+ * browser context.
+ *
+ * Incorporates all robustness features: connection timeouts, force-kill
+ * of stuck processes, dead-transport detection, and per-call abort
+ * signal + timeout support.
+ */
+export class PlaywrightMcpSession {
+  private mcpClient: Client | null = null;
+  private mcpTransport: StdioClientTransport | null = null;
+  private mcpProcess: import("child_process").ChildProcess | null = null;
+  private connectionPromise: Promise<Client> | null = null;
+  private disconnecting = false;
+  private readonly headless: boolean;
+  private readonly userAgent: string | undefined;
+  private readonly viewportSize: string | undefined;
+  private readonly headerPolicy: BrowserHeaderPolicy | undefined;
+  /** X display for the spawned browser; overrides `process.env.DISPLAY`. */
+  private readonly display: string | undefined;
+  readonly engine: BrowserEngine;
+  /** Temp config file written for MCP launch — deleted on disconnect. */
+  private mcpConfigPath: string | null = null;
+  /** Cached Camoufox launch options — resolved once, reused on reconnect. */
+  private cachedCamouOptions: CamoufoxLaunchOptions | null = null;
+  /**
+   * Deliberately NOT cleared by `resetState()` — `disconnect()` resets before
+   * it kills, so clearing there would blind the sweep. A new launch overwrites.
+   */
+  private currentLaunchId: string | null = null;
+
+  /**
+   * Each option is three-state: `undefined` → module default, value → use it,
+   * `null` → opt out of the default and let Chromium pick. Viewport has a
+   * hard floor of `HARDCODED_VIEWPORT_FALLBACK` to avoid Chromium's tiny built-in.
+   */
+  constructor(options: PlaywrightMcpSessionOptions = {}) {
+    const { headless, userAgent, viewportSize, headerPolicy, display, engine } =
+      options;
+    this.engine = engine ?? "camoufox";
+
+    // An explicit `display` option wins over the process-wide env (needed when
+    // concurrent headed sessions each need their own display); fall back to
+    // `process.env.DISPLAY`.
+    this.display = display ?? process.env.DISPLAY ?? undefined;
+
+    // An explicit option always wins. Otherwise, if a virtual display is
+    // present (an explicit one, or a Daytona computer-use desktop on
+    // `process.env.DISPLAY`), default to headed — Camoufox is far less
+    // detectable headful and the display lets the session be streamed/observed.
+    // With no display we keep the module default (headless). Mirrors the
+    // `DISPLAY`-aware policy already used on the sandbox-executor path
+    // (`sandboxPlaywright.ts`).
+    this.headless = headless ?? (this.display ? false : defaultHeadless);
+    this.userAgent =
+      userAgent === null ? undefined : (userAgent ?? defaultUserAgent);
+    // Viewport resolution:
+    //   1. explicit `viewportSize` / `null` opt-out
+    //   2. endpoint-tier display (`:10+`) → 1280x720 (matches Console Xvfb)
+    //   3. module default / 1920x1080 floor (matches computer-use `:0`–`:9`)
+    // `ENDPOINT_DISPLAY_BASE` must stay aligned with Console desktopSession.ts
+    // and the agent-image Xvfb shim.
+    if (viewportSize === null) {
+      this.viewportSize = undefined;
+    } else if (viewportSize !== undefined) {
+      this.viewportSize = viewportSize;
+    } else {
+      const displayNum = parseDisplayNumber(this.display);
+      this.viewportSize =
+        displayNum !== undefined && displayNum >= ENDPOINT_DISPLAY_BASE
+          ? ENDPOINT_VIEWPORT_SIZE
+          : (defaultViewportSize ?? HARDCODED_VIEWPORT_FALLBACK);
+    }
+
+    this.headerPolicy =
+      headerPolicy &&
+      headerPolicy.allowedHosts.length > 0 &&
+      Object.keys(headerPolicy.headers).length > 0
+        ? {
+            allowedHosts: [...headerPolicy.allowedHosts],
+            headers: { ...headerPolicy.headers },
+          }
+        : undefined;
+  }
+
+  /**
+   * Immediately reset all instance state and schedule best-effort cleanup
+   * of the temp MCP config file (if one exists). The file unlink is async
+   * but fire-and-forget so this method stays non-blocking.
+   */
+  private resetState(): void {
+    this.cleanupConfigFile();
+    this.mcpClient = null;
+    this.mcpTransport = null;
+    this.mcpProcess = null;
+    this.connectionPromise = null;
+    this.disconnecting = false;
+  }
+
+  /** Best-effort async unlink of the current temp config file. */
+  private cleanupConfigFile(): void {
+    const configPath = this.mcpConfigPath;
+    if (!configPath) return;
+    this.mcpConfigPath = null;
+    void (async () => {
+      try {
+        const fsp = await import("fs/promises");
+        await fsp.unlink(configPath);
+      } catch {
+        // already-deleted or inaccessible — fine
+      }
+    })();
+  }
+
+  /**
+   * Force-kill the MCP child process. Sends SIGKILL directly — no graceful
+   * shutdown, no waiting. Used during disconnect and error recovery so the
+   * agent is never blocked on a hung Playwright process.
+   */
+  private forceKillProcess(
+    proc: import("child_process").ChildProcess | null = this.mcpProcess,
+    // Bind the sweep to a specific launch. `onclose` passes its own generation
+    // so a relaunch that has already overwritten `currentLaunchId` can never
+    // have its fresh browser killed by the previous generation's teardown.
+    launchId: string | null = this.currentLaunchId,
+  ): void {
+    // Was an early `return`, which skipped the sweep below in exactly the case
+    // that needs it — a node that already exited.
+    if (proc && proc.exitCode === null) {
+      // Snapshot descendants BEFORE the node dies; afterwards they reparent to
+      // init. The group-kill misses them because the node isn't a group leader.
+      const rootPid = proc.pid ?? null;
+      const descendants = rootPid != null ? collectDescendantPids(rootPid) : [];
+      // Snapshot starttimes before kill so we refuse PID-reuse kills after reparent.
+      const descendantStarts = new Map<number, number | null>();
+      for (const pid of descendants) {
+        descendantStarts.set(pid, readProcStartTime(pid));
+      }
+
+      try {
+        if (rootPid != null) {
+          try {
+            process.kill(-rootPid, "SIGKILL");
+          } catch {
+            proc.kill("SIGKILL");
+          }
+        } else {
+          proc.kill("SIGKILL");
+        }
+      } catch {
+        // Already dead — fine
+      }
+
+      for (const pid of descendants) {
+        // An unverifiable starttime can't rule out PID reuse, so decline the
+        // kill; the marker sweep below covers anything skipped here.
+        const expected = descendantStarts.get(pid);
+        const now = readProcStartTime(pid);
+        if (expected == null || now == null || now !== expected) continue;
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+          // Already gone — fine
+        }
+      }
+    }
+
+    this.reapLaunchedProcesses(launchId);
+  }
+
+  /**
+   * SIGKILL anything still carrying the given launch's marker. Idempotent, and
+   * can only ever target processes this session launched.
+   */
+  private reapLaunchedProcesses(launchId: string | null): void {
+    if (!launchId) return;
+    for (const pid of collectPidsByEnvMarker(BROWSER_LAUNCH_ENV, launchId)) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // Already gone — fine
+      }
+    }
+  }
+
+  private async buildMcpLaunch(launchId: string): Promise<{
+    cfg: unknown;
+    env: Record<string, string>;
+  }> {
+    const env: Record<string, string> = { [BROWSER_LAUNCH_ENV]: launchId };
+    if (this.display) env.DISPLAY = this.display;
+
+    if (this.engine === "chrome") {
+      const parsed = this.viewportSize
+        ? parseViewportSize(this.viewportSize)
+        : undefined;
+      const viewport = parsed
+        ? { width: parsed[0], height: parsed[1] }
+        : undefined;
+      return {
+        cfg: {
+          browser: {
+            browserName: "chromium",
+            launchOptions: {
+              channel: "chrome",
+              headless: this.headless,
+              // Sandbox images run as root, where Chrome refuses to start sandboxed.
+              chromiumSandbox: false,
+              args: ["--disable-dev-shm-usage"],
+            },
+            contextOptions: {
+              ...(viewport ? { viewport } : {}),
+            },
+          },
+        },
+        env,
+      };
+    }
+
+    // Drive an anti-detect Camoufox (Firefox) instead of vanilla Chromium.
+    // camoufox-js produces the executablePath / args / firefoxUserPrefs / env
+    // that carry the fingerprint; MCP drives that browser through the same
+    // tool API. We pass these via a temp config file rather than CLI flags.
+    // Resolve once per session lifetime so reconnects keep the same fingerprint.
+    await ensureCamoufox();
+    if (!this.cachedCamouOptions) {
+      // Apply viewportSize as Camoufox `window` so the headed browser fills
+      // the bound Xvfb desktop (previously stored but never forwarded —
+      // Camoufox randomised the window and overflowed 720p endpoint streams).
+      const window = this.viewportSize
+        ? parseViewportSize(this.viewportSize)
+        : undefined;
+      this.cachedCamouOptions = await resolveCamoufoxLaunchOptions(
+        this.headless,
+        window ? { window } : undefined,
+      );
+    }
+    const camou = this.cachedCamouOptions;
+    return {
+      cfg: {
+        browser: {
+          browserName: "firefox",
+          launchOptions: {
+            executablePath: camou.executablePath,
+            args: camou.args,
+            firefoxUserPrefs: camou.firefoxUserPrefs,
+            headless: camou.headless,
+          },
+        },
+      },
+      env: {
+        ...Object.fromEntries(
+          Object.entries(camou.env).map(([k, v]) => [k, String(v)]),
+        ),
+        ...env,
+      },
+    };
+  }
+
+  private async installHeaderRoute(client: Client): Promise<void> {
+    if (!this.headerPolicy) return;
+    await withTimeout(
+      client.callTool({
+        name: "browser_run_code",
+        arguments: {
+          code: browserHeaderRouteFunction(this.headerPolicy),
+        },
+      }),
+      MCP_TOOL_CALL_TIMEOUT_MS,
+      "Browser header route installation timed out",
+    );
+  }
+
+  /**
+   * Initialize or return existing MCP client connection for this session.
+   * Handles race conditions when multiple tools within the same agent
+   * try to connect simultaneously. Detects dead transports and
+   * auto-reconnects.
+   */
+  async initialize(): Promise<Client> {
+    if (this.mcpClient) {
+      if ((this.mcpClient as unknown as { transport?: unknown }).transport) {
+        return this.mcpClient;
+      }
+      this.forceKillProcess();
+      this.resetState();
+    }
+
+    if (this.connectionPromise) {
+      return this.connectionPromise;
+    }
+
+    this.connectionPromise = (async () => {
+      try {
+        const require_ = createRequire(import.meta.url);
+        const mcpPkgJsonPath = require_.resolve("@playwright/mcp/package.json");
+        const cliPath = join(dirname(mcpPkgJsonPath), "cli.js");
+
+        const args = [cliPath, "--isolated"];
+
+        const os = await import("node:os");
+        const fsp = await import("node:fs/promises");
+        const launchId = randomUUID();
+        this.currentLaunchId = launchId;
+
+        const { cfg, env } = await this.buildMcpLaunch(launchId);
+        this.mcpConfigPath = join(
+          os.tmpdir(),
+          `pensar-mcp-${process.pid}-${Date.now()}.json`,
+        );
+        await fsp.writeFile(this.mcpConfigPath, JSON.stringify(cfg), {
+          encoding: "utf-8",
+          mode: 0o600,
+        });
+        args.push("--config", this.mcpConfigPath);
+
+        const transport = new StdioClientTransport({
+          command: "node",
+          args,
+          stderr: "pipe",
+          env,
+        });
+
+        const client = new Client({
+          name: "apex-browser-agent",
+          version: "1.0.0",
+        });
+
+        // Hook into transport to capture the child process reference
+        const origStart = transport.start.bind(transport);
+        transport.start = async () => {
+          await origStart();
+          this.mcpProcess =
+            (
+              transport as unknown as {
+                _process?: import("child_process").ChildProcess;
+              }
+            )._process ?? null;
+        };
+
+        await withTimeout(
+          client.connect(transport),
+          MCP_CONNECT_TIMEOUT_MS,
+          "MCP client connection timed out",
+        );
+        await this.installHeaderRoute(client);
+
+        this.mcpClient = client;
+        this.mcpTransport = transport;
+
+        client.onclose = () => {
+          if (this.mcpClient === client) {
+            // Must run before resetState() nulls the handle. This path used to
+            // drop it without killing anything, stranding one Camoufox each time.
+            this.forceKillProcess(this.mcpProcess, launchId);
+            this.resetState();
+          }
+        };
+
+        return client;
+      } catch (error) {
+        this.forceKillProcess();
+        this.resetState();
+        throw error;
+      }
+    })();
+
+    return this.connectionPromise;
+  }
+
+  /**
+   * Disconnect and cleanup this session's MCP client and browser.
+   *
+   * Designed to NEVER hang: resets state synchronously, then kills
+   * the transport and process. Does NOT call browser_close (which
+   * could block for 60 s if the server is hung).
+   */
+  async disconnect(): Promise<void> {
+    if (this.disconnecting) return;
+    this.disconnecting = true;
+
+    const transport = this.mcpTransport;
+    const client = this.mcpClient;
+    // Capture the child BEFORE resetState() nulls it — otherwise the kill
+    // below is a no-op (the original bug).
+    const proc = this.mcpProcess;
+
+    this.resetState();
+    this.disconnecting = true; // re-set because resetState clears it
+
+    // SIGKILL the MCP child FIRST. Previously this ran *after* the awaited
+    // client/transport.close() calls AND read the already-nulled
+    // this.mcpProcess, so it never actually killed anything: disconnect relied
+    // entirely on close() to end the child. When the Playwright MCP child is
+    // wedged, transport.close() blocks indefinitely — so disconnect() (and any
+    // caller awaiting it, e.g. the agent's consume() teardown) hung forever,
+    // stranding an endpoint that had already finished its run. Killing the
+    // child up front makes the stdio transport observe EOF so close() resolves
+    // promptly, and guarantees disconnect() honors its "never hangs" contract.
+    this.forceKillProcess(proc);
+
+    // Graceful close is best-effort cleanup and must never block the caller —
+    // bound it so a stuck client/transport can't re-introduce the hang.
+    const CLOSE_TIMEOUT_MS = 5_000;
+    let closeTimer: ReturnType<typeof setTimeout> | undefined;
+    await Promise.race([
+      (async () => {
+        try {
+          await client?.close();
+        } catch {
+          // Ignore — may already be closed
+        }
+        try {
+          await transport?.close();
+        } catch {
+          // Ignore — may already be closed
+        }
+      })(),
+      new Promise<void>((resolve) => {
+        closeTimer = setTimeout(resolve, CLOSE_TIMEOUT_MS);
+      }),
+    ]);
+    if (closeTimer) clearTimeout(closeTimer);
+
+    this.cleanupConfigFile();
+
+    this.disconnecting = false;
+  }
+
+  /** Check if this session's client is currently connected. */
+  isConnected(): boolean {
+    return this.mcpClient !== null;
+  }
+
+  /**
+   * Snapshot this session's full Playwright storage state (cookies + per-origin
+   * localStorage) by invoking `BrowserContext.storageState()` through the
+   * MCP `browser_run_code` tool.
+   *
+   * Returns `null` when the session has never been initialised (no Chromium
+   * to ask), when no page is open, or when the call / response parse fails.
+   * Callers should treat a `null` result as "no auth state to clone" and
+   * proceed with an unseeded session.
+   *
+   * Cheap to call repeatedly — the underlying MCP call is a few KB of JSON.
+   */
+  async captureStorageState(): Promise<BrowserStorageState | null> {
+    if (!this.isConnected()) return null;
+
+    try {
+      const result = await this.callTool("browser_run_code", {
+        code: `async (page) => { return await page.context().storageState(); }`,
+      });
+
+      return parseStorageStateResult(result);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Seed this session's browser context with a previously-captured
+   * {@link BrowserStorageState}. Initialises the session if it hasn't been
+   * connected yet, then injects:
+   *
+   * - cookies, immediately, via `BrowserContext.addCookies()`
+   * - per-origin localStorage, lazily, via `BrowserContext.addInitScript()`
+   *   so the values are written into `localStorage` whenever a page from
+   *   that origin loads
+   *
+   * The init-script approach means localStorage is restored on the next
+   * `browser_navigate` call — calling `browser_evaluate` on `about:blank`
+   * before navigating won't see the seeded values (those live on the
+   * target origin). Cookies are visible immediately and will be sent on
+   * the first navigation.
+   *
+   * Best-effort: errors are swallowed so a seeding failure never blocks
+   * the worker from running with an unauthenticated session.
+   */
+  async seedStorageState(state: BrowserStorageState): Promise<void> {
+    await this.initialize();
+
+    const code = `async (page) => {
+      const ctx = page.context();
+      const state = ${JSON.stringify(state)};
+      if (state.cookies && state.cookies.length > 0) {
+        try { await ctx.addCookies(state.cookies); } catch (e) {}
+      }
+      if (state.origins && state.origins.length > 0) {
+        const parts = [];
+        for (const o of state.origins) {
+          if (!o.localStorage || o.localStorage.length === 0) continue;
+          const setters = o.localStorage.map(function(it) {
+            return 'try{localStorage.setItem(' + JSON.stringify(it.name) + ',' + JSON.stringify(it.value) + ');}catch(e){}';
+          }).join('');
+          parts.push('if (location.origin === ' + JSON.stringify(o.origin) + ') {' + setters + '}');
+        }
+        if (parts.length > 0) {
+          try { await ctx.addInitScript({ content: parts.join('\\n') }); } catch (e) {}
+        }
+      }
+      return { ok: true, cookies: (state.cookies||[]).length, origins: (state.origins||[]).length };
+    }`;
+
+    try {
+      await this.callTool("browser_run_code", { code });
+    } catch {
+      // Best-effort — proceed even if seeding partially or fully failed.
+    }
+  }
+
+  /**
+   * Call a tool on this session's MCP server and extract the result.
+   *
+   * Each call is guarded by:
+   * 1. The SDK's native abort signal (properly cancels the request)
+   * 2. An outer timeout (in case the SDK's cancellation gets stuck)
+   * 3. Auto-reconnection on transport errors
+   */
+  async callTool(
+    toolName: string,
+    args: Record<string, unknown>,
+    abortSignal?: AbortSignal,
+  ): Promise<unknown> {
+    if (abortSignal?.aborted) {
+      throw new Error("Browser tool call aborted");
+    }
+
+    let client: Client;
+    try {
+      client = await withTimeout(
+        this.initialize(),
+        MCP_CONNECT_TIMEOUT_MS,
+        "MCP client initialization timed out",
+      );
+    } catch (error) {
+      this.forceKillProcess();
+      this.resetState();
+      throw error;
+    }
+
+    const callController = new AbortController();
+    let abortCleanup: (() => void) | undefined;
+
+    if (abortSignal) {
+      const handler = () => callController.abort(abortSignal.reason);
+      if (abortSignal.aborted) {
+        callController.abort(abortSignal.reason);
+      } else {
+        abortSignal.addEventListener("abort", handler, { once: true });
+        abortCleanup = () => abortSignal.removeEventListener("abort", handler);
+      }
+    }
+
+    const timeoutTimer = setTimeout(
+      () =>
+        callController.abort(
+          new Error(
+            `Browser tool "${toolName}" timed out after ${MCP_TOOL_CALL_TIMEOUT_MS / 1000}s`,
+          ),
+        ),
+      MCP_TOOL_CALL_TIMEOUT_MS,
+    );
+
+    try {
+      const result = await client.callTool(
+        { name: toolName, arguments: args },
+        undefined,
+        { signal: callController.signal },
+      );
+
+      if (result && "content" in result && Array.isArray(result.content)) {
+        const imageContent = result.content.find(
+          (c: { type: string }) => c.type === "image",
+        );
+        if (imageContent && "data" in imageContent) {
+          return { type: "image", data: imageContent.data };
+        }
+
+        const textContent = result.content.find(
+          (c: { type: string }) => c.type === "text",
+        );
+        if (textContent && "text" in textContent) {
+          try {
+            return JSON.parse(textContent.text as string);
+          } catch {
+            return textContent.text;
+          }
+        }
+        return result.content;
+      }
+
+      return result;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      const isConnectionDead =
+        msg.includes("Not connected") ||
+        msg.includes("Connection closed") ||
+        msg.includes("EPIPE") ||
+        msg.includes("write after end");
+
+      if (isConnectionDead && this.mcpClient === client) {
+        this.forceKillProcess();
+        this.resetState();
+      }
+
+      throw error;
+    } finally {
+      clearTimeout(timeoutTimer);
+      abortCleanup?.();
+    }
+  }
+}
+
+export function createPlaywrightBrowserBackend(
+  evidenceDir: string,
+  logger?: Logger,
+  abortSignal?: AbortSignal,
+  headless?: boolean,
+  userAgent?: string | null,
+  viewportSize?: string | null,
+  existingSession?: PlaywrightMcpSession,
+  headerPolicy?: BrowserHeaderPolicy,
+): BrowserBackend {
+  let session: PlaywrightMcpSession;
+
+  if (existingSession) {
+    session = existingSession;
+    // Owner manages disconnect — do NOT register an abort handler here,
+    // otherwise an inheriting sub-agent finishing first would tear down
+    // the parent's browser mid-flight.
+  } else {
+    // PlaywrightMcpSession's constructor folds in the module-level
+    // defaults (1920x1080 viewport, desktop Chrome UA, headless=true)
+    // when these options are undefined — pass them through verbatim.
+    session = new PlaywrightMcpSession({
+      headless,
+      userAgent,
+      viewportSize,
+      headerPolicy,
+    });
+
+    if (abortSignal) {
+      const onAbort = () => session.disconnect().catch(() => {});
+      abortSignal.addEventListener("abort", onAbort, { once: true });
+    }
+  }
+
+  // Ensure evidence directory exists
+  if (!existsSync(evidenceDir)) {
+    mkdirSync(evidenceDir, { recursive: true });
+  }
+
+  return {
+    navigate: async (url) => {
+      try {
+        const result = await session.callTool(
+          "browser_navigate",
+          { url },
+          abortSignal,
+        );
+        return {
+          success: true,
+          url,
+          result,
+        };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_navigate failed: ${message}`);
+        return { success: false, url, error: message };
+      }
+    },
+    screenshot: async ({ filename }) => {
+      try {
+        const result = await session.callTool(
+          "browser_take_screenshot",
+          {},
+          abortSignal,
+        );
+
+        // Extract base64 image data from various response formats
+        let base64Data: string | undefined;
+
+        if (result && typeof result === "object") {
+          const r = result as Record<string, unknown>;
+
+          // Format 1: { type: "image", data: "<base64>" } — from callTool's image extraction
+          if ("data" in r && typeof r.data === "string") {
+            base64Data = r.data;
+          }
+
+          // Format 2: Raw MCP content array — [{type:"image", data:"...", mimeType:"..."}]
+          if (!base64Data && Array.isArray(result)) {
+            const imgItem = (result as Array<Record<string, unknown>>).find(
+              (c) => c.type === "image" && typeof c.data === "string",
+            );
+            if (imgItem) {
+              base64Data = imgItem.data as string;
+            }
+          }
+        }
+
+        if (base64Data) {
+          const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+          const screenshotFilename = `${filename}_${timestamp}.png`;
+          const screenshotPath = join(evidenceDir, screenshotFilename);
+          const dir = dirname(screenshotPath);
+          if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+          }
+          writeFileSync(screenshotPath, Buffer.from(base64Data, "base64"));
+          return {
+            success: true,
+            path: screenshotPath,
+            message: `Screenshot saved to ${screenshotPath}`,
+          };
+        }
+
+        // Log the actual response shape to aid debugging
+        const resultShape =
+          result === null
+            ? "null"
+            : Array.isArray(result)
+              ? `array(${(result as unknown[]).length})`
+              : typeof result === "object"
+                ? `object(${Object.keys(result as Record<string, unknown>).join(",")})`
+                : typeof result;
+        return {
+          success: false,
+          error: `No screenshot data returned (response type: ${resultShape})`,
+        };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_screenshot failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+    snapshot: async () => {
+      try {
+        const result = await session.callTool(
+          "browser_snapshot",
+          {},
+          abortSignal,
+        );
+        return {
+          success: true,
+          snapshot:
+            typeof result === "string"
+              ? result
+              : JSON.stringify(result, null, 2),
+        };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_snapshot failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+    click: async ({ element, ref }) => {
+      try {
+        const args: Record<string, unknown> = { element };
+        if (ref) {
+          args.ref = ref;
+        }
+        const result = await session.callTool(
+          "browser_click",
+          args,
+          abortSignal,
+        );
+        return { success: true, element, result };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_click failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+    fill: async ({ element, ref, value }) => {
+      try {
+        // Note: Playwright MCP uses "browser_type" for filling fields
+        const args: Record<string, unknown> = { element, text: value };
+        if (ref) {
+          args.ref = ref;
+        }
+        const result = await session.callTool(
+          "browser_type",
+          args,
+          abortSignal,
+        );
+        return { success: true, element, result };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_fill failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+    evaluate: async ({ script }) => {
+      try {
+        const fnScript = transformScriptToFunction(script);
+
+        const result = await session.callTool(
+          "browser_evaluate",
+          { function: fnScript },
+          abortSignal,
+        );
+        return { success: true, script, result };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_evaluate failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+    console: async () => {
+      try {
+        const result = await session.callTool(
+          "browser_console_messages",
+          {},
+          abortSignal,
+        );
+
+        // Parse console messages if they're in JSON format
+        let messages: Array<{ type: string; text: string }> | undefined;
+        if (typeof result === "string") {
+          try {
+            messages = JSON.parse(result);
+          } catch {
+            messages = [{ type: "log", text: result }];
+          }
+        } else if (Array.isArray(result)) {
+          messages = result as Array<{ type: string; text: string }>;
+        }
+
+        return { success: true, messages, result };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_console failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+    getCookies: async ({ urls } = {}) => {
+      try {
+        // Playwright MCP doesn't expose a dedicated cookie tool, so we use
+        // browser_run_code to call the Playwright context API directly.
+        // This gets ALL cookies including httpOnly ones.
+        const urlFilter =
+          urls && urls.length > 0 ? JSON.stringify(urls) : "undefined";
+        const code = `async (page) => { const cookies = await page.context().cookies(${urlFilter === "undefined" ? "" : urlFilter}); return cookies; }`;
+
+        const result = await session.callTool(
+          "browser_run_code",
+          { code },
+          abortSignal,
+        );
+
+        let cookies: Array<{
+          name: string;
+          value: string;
+          domain: string;
+          path: string;
+          httpOnly: boolean;
+          secure: boolean;
+        }> = [];
+
+        if (typeof result === "string") {
+          // Playwright MCP wraps results as "### Result\n<value>\n\n### Ran Playwright code\n...".
+          // Strip the prefix and any trailing Playwright output sections.
+          const stripped = result
+            .replace(/^###\s*Result\s*\n?/, "")
+            .replace(/\n\n###[\s\S]*$/, "")
+            .trim();
+          try {
+            const parsed = JSON.parse(stripped);
+            if (Array.isArray(parsed)) {
+              cookies = parsed;
+            } else if (typeof parsed === "string") {
+              cookies = JSON.parse(parsed);
+            }
+          } catch {
+            const jsonMatch = stripped.match(/\[[\s\S]*\]/);
+            if (jsonMatch) {
+              try {
+                cookies = JSON.parse(jsonMatch[0]);
+              } catch {
+                // Could not parse
+              }
+            }
+          }
+        } else if (Array.isArray(result)) {
+          cookies = result as typeof cookies;
+        } else if (
+          result &&
+          typeof result === "object" &&
+          "cookies" in result
+        ) {
+          cookies = (result as { cookies: typeof cookies }).cookies;
+        }
+
+        const cookieHeader = cookies
+          .map((c) => `${c.name}=${c.value}`)
+          .join("; ");
+
+        return {
+          success: true,
+          cookies,
+          cookieHeader,
+        };
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger?.error(`browser_get_cookies failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+  };
+}
+
+/**
+ * Create browser automation tools backed by a **dedicated** Playwright MCP
+ * session. Every invocation spins up its own MCP child-process / browser so
+ * that concurrent agents never share a browser context.
+ *
+ * @param targetUrl - Base target URL for context in descriptions
+ * @param evidenceDir - Directory to save screenshots
+ * @param mode - "pentest" for automated pentesting, "operator" for user-driven reconnaissance, "auth" for authentication flows
+ * @param logger - Optional logger for error reporting
+ * @param abortSignal - Optional abort signal for cleanup
+ * @param headless - Override headless mode for this session (defaults to the
+ *   value set by {@link setHeadlessMode}, which itself defaults to `true`)
+ * @param userAgent - Override User-Agent for this session (defaults to the
+ *   value set by {@link setUserAgent}). Passing `null` forces Chromium's
+ *   built-in UA (useful if the default anti-bot UA is counter-productive).
+ * @param viewportSize - Override viewport size (format `"WIDTH,HEIGHT"`) for
+ *   this session (defaults to the value set by {@link setViewportSize}).
+ *   Passing `null` forces Chromium's default viewport.
+ * @param existingSession - When provided, browser tools reuse this
+ *   already-constructed session instead of creating a new MCP child-process
+ *   / Chromium instance. Used by sub-agents (e.g. workers spawned via
+ *   `spawn_pentest_agent`) to inherit a parent's authenticated browser
+ *   context. Headless / userAgent / viewportSize are ignored when an
+ *   existing session is passed — those are baked into the session at
+ *   construction time. Lifecycle: the caller that originally constructed
+ *   the session owns disconnect, so `abortSignal` is NOT wired to disconnect
+ *   when reusing a session.
+ */
+/**
+ * Lazy per-member browser tool factories. Shared state (the MCP session,
+ * evidence dir, mode descriptions) is built once per call; each member's
+ * tool object is constructed only when its factory is invoked, so a
+ * selection of one member never allocates sibling tool schemas.
+ */
+export function createBrowserToolFactories(
+  targetUrl: string,
+  evidenceDir: string,
+  mode: BrowserToolMode = "pentest",
+  logger?: Logger,
+  abortSignal?: AbortSignal,
+  headless?: boolean,
+  userAgent?: string | null,
+  viewportSize?: string | null,
+  existingSession?: PlaywrightMcpSession,
+  headerPolicy?: BrowserHeaderPolicy,
+) {
+  return createBackendBrowserToolFactories(
+    createPlaywrightBrowserBackend(
+      evidenceDir,
+      logger,
+      abortSignal,
+      headless,
+      userAgent,
+      viewportSize,
+      existingSession,
+      headerPolicy,
+    ),
+    { targetUrl, mode },
+  );
+}
+
+export function createBrowserTools(
+  targetUrl: string,
+  evidenceDir: string,
+  mode: BrowserToolMode = "pentest",
+  logger?: Logger,
+  abortSignal?: AbortSignal,
+  headless?: boolean,
+  userAgent?: string | null,
+  viewportSize?: string | null,
+  existingSession?: PlaywrightMcpSession,
+  headerPolicy?: BrowserHeaderPolicy,
+) {
+  const factories = createBrowserToolFactories(
+    targetUrl,
+    evidenceDir,
+    mode,
+    logger,
+    abortSignal,
+    headless,
+    userAgent,
+    viewportSize,
+    existingSession,
+    headerPolicy,
+  );
+  return {
+    browser_navigate: factories.browser_navigate(),
+    browser_snapshot: factories.browser_snapshot(),
+    browser_screenshot: factories.browser_screenshot(),
+    browser_click: factories.browser_click(),
+    browser_fill: factories.browser_fill(),
+    browser_evaluate: factories.browser_evaluate(),
+    browser_console: factories.browser_console(),
+    browser_get_cookies: factories.browser_get_cookies(),
+  };
+}