devtools-fleet-mcp 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "devtools-fleet-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "chrome-devtools-mcp for ten agents at once: one isolated Chrome per agent, saved login states, origin allowlists, and a CLI to see and reap them all",
+  "main": "src/index.js",
+  "bin": {
+    "devtools-fleet-mcp": "src/index.js",
+    "devtools-fleet": "bin/cli.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "skills/",
+    ".claude-plugin/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test --test-concurrency=1 test/unit/*.test.js",
+    "test:integration": "node --test --test-concurrency=1 --test-timeout=900000 test/integration/*.test.js",
+    "test:all": "npm test && npm run test:integration",
+    "lint": "eslint src/ bin/"
+  },
+  "keywords": [
+    "chrome",
+    "devtools",
+    "chrome-devtools-mcp",
+    "mcp",
+    "model-context-protocol",
+    "browser",
+    "multi-agent",
+    "claude-code"
+  ],
+  "author": "Marcel Schmitz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pluginslab/devtools-fleet-mcp.git"
+  },
+  "homepage": "https://github.com/pluginslab/devtools-fleet-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/pluginslab/devtools-fleet-mcp/issues"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "@puppeteer/browsers": "^3.2.3",
+    "chrome-devtools-mcp": "^1.10.1",
+    "commander": "^15.0.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.11.0"
+  }
+}

package/skills/devtools-fleet/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: devtools-fleet
+description: Open, test, debug or profile a web page in this session's own isolated Chrome (devtools-fleet, which runs Google's chrome-devtools-mcp tools), optionally already logged in from a saved state. Use for any browser task when the devtools-fleet MCP server is connected, especially when the page needs a login or other agents are using browsers at the same time.
+---
+
+# devtools-fleet
+
+You have your own Chrome. Other agents have theirs; nothing you do in yours affects them. All of chrome-devtools-mcp's tools (`new_page`, `navigate_page`, `take_snapshot`, `click`, `fill`, `evaluate_script`, `list_console_messages`, `list_network_requests`, `performance_start_trace`, `lighthouse_audit`, ...) work as usual.
+
+## Starting
+
+- Any browser tool starts the browser on first use. You only need `browser_start` to choose options.
+- **Needs a login?** Call `state_list` first. If a matching state exists, call `browser_start({ state: "<name>", url: "<page>" })`. You start logged in.
+- **No matching state?** Don't try to log in with credentials you were not given. Ask the person to run `devtools-fleet login <name> <url>` in a terminal, then use the state they create.
+- A browser can't switch to a different state while running. `browser_stop`, then `browser_start` with the new one.
+
+## The allowlist
+
+A browser started from a state only reaches that state's origins. When something is blocked, the tool result says so (`is blocked` / `devtools-fleet blocked N request(s)`).
+
+- This is deliberate. Don't look for another way to reach the blocked origin.
+- If the task genuinely needs that origin, tell the person which one, so they can re-save the state with `--allow <origin>`.
+- A blocked link click leaves the tab on an error page. Navigate it back with `navigate_page`.
+
+## When things go wrong
+
+- A tool result starting with `devtools-fleet:` means the browser or the tooling was recovered. Read it: after a browser restart, tabs are gone and page ids are new, so call `list_pages` again.
+- `devtools-fleet is at its limit of N browsers`: tell the person. Don't stop other sessions' browsers; you can't see or reach them anyway.
+
+## Showing the person something
+
+- `browser_restart({ headless: false })` relaunches with a visible window (same cookies and tabs, pages reload). Use it when the person needs to watch, solve a captcha or pass 2FA. `browser_restart({ headless: true })` hides it again.
+- The person can also watch without interrupting you: `devtools-fleet ls`, then `devtools-fleet show <id>`. `browser_status` tells you your id.
+
+## Saving a login
+
+After the person has logged in inside your visible browser, `state_save({ name })` stores it for other sessions. It keeps only cookies for the open allowed origins, can't widen your allowlist, and can't overwrite states a person created.
+
+## Cleaning up
+
+Call `browser_stop` when the task is done and the browser isn't needed any more. If you forget, the reaper closes it after your session ends.

package/src/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { startServer } from './server.js';
+
+startServer().catch((err) => {
+  console.error(`[devtools-fleet-mcp] failed to start: ${err.message}`);
+  process.exit(1);
+});

package/src/lib/cdp.js

@@ -0,0 +1,105 @@
+// Minimal Chrome DevTools Protocol client over the built-in WebSocket.
+//
+// Fleet keeps its own CDP connection next to chrome-devtools-mcp's, for the
+// few things upstream doesn't do: cookie and storage transfer, and the
+// navigation allowlist. Flat sessions only (Target.setAutoAttach flatten).
+
+export class CdpConnection {
+  #ws;
+  #nextId = 1;
+  #pending = new Map();
+  #listeners = new Map();
+  #closed = false;
+
+  static async connect(wsUrl, { timeoutMs = 10_000 } = {}) {
+    const ws = new WebSocket(wsUrl);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`CDP connect timed out: ${wsUrl}`)), timeoutMs);
+      ws.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+      ws.addEventListener('error', () => { clearTimeout(timer); reject(new Error(`CDP connect failed: ${wsUrl}`)); }, { once: true });
+    });
+    return new CdpConnection(ws);
+  }
+
+  constructor(ws) {
+    this.#ws = ws;
+    ws.addEventListener('message', (event) => this.#onMessage(event.data));
+    ws.addEventListener('close', () => this.#onClose());
+  }
+
+  get closed() {
+    return this.#closed;
+  }
+
+  send(method, params = {}, sessionId = undefined) {
+    if (this.#closed) return Promise.reject(new Error(`CDP connection closed (${method})`));
+    const id = this.#nextId++;
+    const message = { id, method, params };
+    if (sessionId) message.sessionId = sessionId;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject, method });
+      this.#ws.send(JSON.stringify(message));
+    });
+  }
+
+  /** Listen for an event. Handler gets (params, sessionId). Returns an unsubscribe function. */
+  on(method, handler) {
+    if (!this.#listeners.has(method)) this.#listeners.set(method, new Set());
+    this.#listeners.get(method).add(handler);
+    return () => this.#listeners.get(method)?.delete(handler);
+  }
+
+  waitFor(method, predicate = () => true, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { off(); reject(new Error(`Timed out waiting for ${method}`)); }, timeoutMs);
+      const off = this.on(method, (params, sessionId) => {
+        if (!predicate(params, sessionId)) return;
+        clearTimeout(timer);
+        off();
+        resolve({ params, sessionId });
+      });
+    });
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#ws.close();
+    this.#onClose();
+  }
+
+  #onMessage(data) {
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (message.id !== undefined) {
+      const pending = this.#pending.get(message.id);
+      if (!pending) return;
+      this.#pending.delete(message.id);
+      if (message.error) pending.reject(new Error(`${pending.method}: ${message.error.message}`));
+      else pending.resolve(message.result);
+      return;
+    }
+    const handlers = this.#listeners.get(message.method);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        handler(message.params, message.sessionId);
+      } catch (err) {
+        console.error(`[devtools-fleet] CDP handler for ${message.method} threw:`, err);
+      }
+    }
+  }
+
+  #onClose() {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const { reject, method } of this.#pending.values()) {
+      reject(new Error(`CDP connection closed (${method})`));
+    }
+    this.#pending.clear();
+    for (const handler of this.#listeners.get('__close') ?? []) handler();
+  }
+}

package/src/lib/chrome.js

@@ -0,0 +1,222 @@
+import { spawn, execFileSync } from 'node:child_process';
+import { createServer } from 'node:net';
+import { existsSync } from 'node:fs';
+import { Browser, computeSystemExecutablePath, detectBrowserPlatform } from '@puppeteer/browsers';
+import { parseViewport } from './config.js';
+import { ensurePrivateDir, isPidAlive, sleep } from './fs-utils.js';
+
+// Flags close to what puppeteer/chrome-devtools-mcp use: quiet, no first-run
+// UI, no background noise that would show up in the agent's network panel.
+const BASE_ARGS = [
+  '--no-first-run',
+  '--no-default-browser-check',
+  '--disable-background-networking',
+  '--disable-background-timer-throttling',
+  '--disable-backgrounding-occluded-windows',
+  '--disable-renderer-backgrounding',
+  '--disable-breakpad',
+  '--disable-client-side-phishing-detection',
+  '--disable-component-update',
+  '--disable-default-apps',
+  '--disable-sync',
+  '--disable-hang-monitor',
+  '--disable-popup-blocking',
+  '--disable-prompt-on-repost',
+  '--metrics-recording-only',
+  '--password-store=basic',
+  '--use-mock-keychain',
+  '--export-tagged-pdf',
+];
+
+export function resolveChromePath({ chromePath, channel = 'stable' }) {
+  if (chromePath) {
+    if (!existsSync(chromePath)) throw new Error(`chromePath does not exist: ${chromePath}`);
+    return chromePath;
+  }
+  try {
+    return computeSystemExecutablePath({ browser: Browser.CHROME, channel, platform: detectBrowserPlatform() });
+  } catch (err) {
+    throw new Error(
+      `Could not find Chrome (${channel} channel). Install it, or set chromePath / DEVTOOLS_FLEET_CHROME_PATH.\n${err.message}`,
+      { cause: err },
+    );
+  }
+}
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * Launch Chrome detached, in its own process group, so it survives the fleet
+ * process (that is what makes re-adoption possible).
+ *
+ * The port is picked here rather than by Chrome (port 0) so that
+ * --remote-allow-origins can name exactly the debugging server's own origin.
+ * That lets the DevTools inspector Chrome serves on that port connect (what
+ * `devtools-fleet show` opens), while no web page can.
+ * @returns {Promise<{ pid: number, port: number, wsPath: string }>}
+ */
+export async function launchChrome(opts) {
+  let lastError;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const port = await getFreePort();
+    try {
+      return await launchOnPort({ ...opts, port });
+    } catch (err) {
+      lastError = err;
+      // Someone grabbed the port between probe and launch: Chrome can't bind and exits. Try another.
+      if (!/exited during startup|did not open/.test(err.message)) throw err;
+    }
+  }
+  throw lastError;
+}
+
+async function launchOnPort({ executablePath, profileDir, headless, viewport, extraArgs = [], url = 'about:blank', timeoutMs = 30_000, port, onSpawn = () => {} }) {
+  ensurePrivateDir(profileDir);
+
+  const args = [
+    ...BASE_ARGS,
+    `--remote-debugging-port=${port}`,
+    `--remote-allow-origins=http://127.0.0.1:${port}`,
+    `--user-data-dir=${profileDir}`,
+  ];
+  if (headless) args.push('--headless=new', '--hide-scrollbars', '--mute-audio');
+  if (viewport) {
+    const { width, height } = parseViewport(viewport);
+    args.push(`--window-size=${width},${height}`);
+  }
+  args.push(...extraArgs, url);
+
+  const child = spawn(executablePath, args, { detached: true, stdio: 'ignore' });
+  let spawnError = null;
+  child.once('error', (err) => { spawnError = err; });
+  let exitCode = null;
+  child.once('exit', (code, signal) => { exitCode = code ?? signal; });
+  child.unref();
+  // Record the pid before waiting, so a launch that hangs or crashes is still cleaned up.
+  if (child.pid) onSpawn(child.pid);
+
+  // With a fixed port Chrome doesn't write DevToolsActivePort; ask the
+  // debugging server itself for the browser endpoint.
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (spawnError) throw new Error(`Failed to start Chrome at ${executablePath}: ${spawnError.message}`);
+    if (exitCode !== null) throw new Error(`Chrome exited during startup (${exitCode}). Profile: ${profileDir}`);
+    const wsPath = await browserEndpoint(port);
+    if (wsPath && exitCode === null) return { pid: child.pid, port, wsPath };
+    await sleep(100);
+  }
+  await terminate(child.pid);
+  throw new Error(`Chrome did not open its debugging port within ${timeoutMs / 1000}s`);
+}
+
+async function browserEndpoint(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(1000) });
+    if (!res.ok) return null;
+    const info = await res.json();
+    if (!/Chrome/i.test(info.Browser ?? '')) return null;
+    return new URL(info.webSocketDebuggerUrl).pathname;
+  } catch {
+    return null;
+  }
+}
+
+export function browserWsUrl({ port, wsPath }) {
+  return `ws://127.0.0.1:${port}${wsPath}`;
+}
+
+/** Page targets as the debugging server lists them (no CDP connection needed). */
+export async function listPages({ port }, timeoutMs = 2000) {
+  const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(timeoutMs) });
+  const targets = await res.json();
+  return targets.filter((t) => t.type === 'page').map((t) => ({ id: t.id, url: t.url, title: t.title }));
+}
+
+/**
+ * The DevTools inspector Chrome serves itself, with a live screencast of the
+ * page. Watching this way doesn't disturb the agent's own connection.
+ */
+export function inspectorUrl({ port }, targetId) {
+  return `http://127.0.0.1:${port}/devtools/inspector.html?ws=127.0.0.1:${port}/devtools/page/${targetId}&remoteFrontend=true`;
+}
+
+/** True when a Chrome answers on the port with the expected browser endpoint. */
+export async function isChromeAlive({ port, wsPath, chromePid }, timeoutMs = 2000) {
+  if (!port || (chromePid && !isPidAlive(chromePid))) return false;
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return false;
+    const info = await res.json();
+    return !wsPath || String(info.webSocketDebuggerUrl || '').endsWith(wsPath);
+  } catch {
+    return false;
+  }
+}
+
+/** True when pid is a Chrome started on this profile dir (guards against pid reuse). */
+export function pidOwnsProfile(pid, profileDir) {
+  if (!pid || !isPidAlive(pid)) return false;
+  if (process.platform === 'win32') return true;
+  try {
+    const args = execFileSync('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 });
+    return args.includes(`--user-data-dir=${profileDir}`);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Close a fleet browser: politely over CDP, then by signal. Only signals a pid
+ * that is still a Chrome on this profile, so a recycled pid is never hit.
+ */
+export async function closeChrome({ port, wsPath, chromePid, profileDir }, { cdp = null, timeoutMs = 5000 } = {}) {
+  const ours = pidOwnsProfile(chromePid, profileDir);
+  if (ours && await isChromeAlive({ port, wsPath, chromePid })) {
+    try {
+      if (cdp && !cdp.closed) {
+        await Promise.race([cdp.send('Browser.close'), sleep(2000)]);
+      } else {
+        const { CdpConnection } = await import('./cdp.js');
+        const conn = await CdpConnection.connect(browserWsUrl({ port, wsPath }), { timeoutMs: 2000 });
+        await Promise.race([conn.send('Browser.close').catch(() => {}), sleep(2000)]);
+        conn.close();
+      }
+    } catch {
+      // fall through to signals
+    }
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (chromePid && isPidAlive(chromePid) && Date.now() < deadline) await sleep(100);
+  if (chromePid && isPidAlive(chromePid) && ours) await terminate(chromePid);
+}
+
+/** SIGTERM, then SIGKILL if Chrome is still there after a grace period. */
+async function terminate(pid, graceMs = 3000) {
+  killPid(pid, 'SIGTERM');
+  const deadline = Date.now() + graceMs;
+  while (isPidAlive(pid) && Date.now() < deadline) await sleep(100);
+  if (isPidAlive(pid)) killPid(pid, 'SIGKILL');
+}
+
+function killPid(pid, signal = 'SIGTERM') {
+  try {
+    // Negative pid: the whole process group (Chrome's helpers included).
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      // already gone
+    }
+  }
+}

package/src/lib/config.js

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const FLEET_HOME = process.env.DEVTOOLS_FLEET_HOME || join(homedir(), '.devtools-fleet');
+
+export const PATHS = {
+  home: FLEET_HOME,
+  browsers: join(FLEET_HOME, 'browsers'),
+  profiles: join(FLEET_HOME, 'profiles'),
+  states: join(FLEET_HOME, 'states'),
+  locks: join(FLEET_HOME, 'locks'),
+  config: join(FLEET_HOME, 'config.json'),
+  reaperPid: join(FLEET_HOME, 'reaper.pid'),
+  reaperLog: join(FLEET_HOME, 'reaper.log'),
+};
+
+export const DEFAULTS = {
+  headless: true,
+  viewport: null,
+  channel: 'stable',
+  chromePath: null,
+  maxBrowsers: 10,
+  orphanTimeoutMinutes: 15,
+  launchTimeoutSeconds: 30,
+  // Extra flags for chrome-devtools-mcp, e.g. ["--no-usage-statistics"].
+  upstreamArgs: [],
+  // Extra flags for Chrome itself.
+  chromeArgs: [],
+};
+
+// Flags fleet owns. Passing them through would hand browser lifecycle back to
+// chrome-devtools-mcp and defeat the point.
+const RESERVED_UPSTREAM_FLAGS = [
+  'browserUrl', 'browser-url', 'u', 'wsEndpoint', 'ws-endpoint', 'w', 'wsHeaders', 'ws-headers',
+  'autoConnect', 'auto-connect', 'isolated', 'userDataDir', 'user-data-dir', 'headless',
+  'channel', 'executablePath', 'executable-path', 'e', 'viewport', 'chromeArg', 'chrome-arg',
+];
+
+const ENV = {
+  headless: ['DEVTOOLS_FLEET_HEADLESS', parseBool],
+  viewport: ['DEVTOOLS_FLEET_VIEWPORT', String],
+  channel: ['DEVTOOLS_FLEET_CHANNEL', String],
+  chromePath: ['DEVTOOLS_FLEET_CHROME_PATH', String],
+  maxBrowsers: ['DEVTOOLS_FLEET_MAX_BROWSERS', parsePositiveInt],
+  orphanTimeoutMinutes: ['DEVTOOLS_FLEET_ORPHAN_TIMEOUT_MINUTES', parsePositiveInt],
+  launchTimeoutSeconds: ['DEVTOOLS_FLEET_LAUNCH_TIMEOUT_SECONDS', parsePositiveInt],
+};
+
+export function loadConfig() {
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(PATHS.config, 'utf8'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw new Error(`Invalid ${PATHS.config}: ${err.message}`, { cause: err });
+  }
+  const config = { ...DEFAULTS, ...file };
+  for (const [key, [name, parse]] of Object.entries(ENV)) {
+    if (process.env[name] !== undefined && process.env[name] !== '') config[key] = parse(process.env[name], name);
+  }
+  validateConfig(config);
+  return config;
+}
+
+export function validateConfig(config) {
+  if (!['stable', 'beta', 'dev', 'canary'].includes(config.channel)) {
+    throw new Error(`channel must be stable, beta, dev or canary (got "${config.channel}")`);
+  }
+  if (config.viewport !== null) parseViewport(config.viewport);
+  for (const key of ['maxBrowsers', 'orphanTimeoutMinutes', 'launchTimeoutSeconds']) {
+    if (!Number.isInteger(config[key]) || config[key] < 1) throw new Error(`${key} must be a positive integer`);
+  }
+  for (const key of ['upstreamArgs', 'chromeArgs']) {
+    if (!Array.isArray(config[key]) || !config[key].every((a) => typeof a === 'string')) {
+      throw new Error(`${key} must be an array of strings`);
+    }
+  }
+  for (const arg of config.upstreamArgs) {
+    const flag = arg.replace(/^--?(no-)?/, '').split('=')[0];
+    if (RESERVED_UPSTREAM_FLAGS.includes(flag)) {
+      throw new Error(`upstreamArgs may not include "${arg}": devtools-fleet manages the browser itself`);
+    }
+  }
+}
+
+/** "1280x720" → { width: 1280, height: 720 } */
+export function parseViewport(value) {
+  const match = /^(\d{2,5})x(\d{2,5})$/.exec(String(value));
+  if (!match) throw new Error(`viewport must look like 1280x720 (got "${value}")`);
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+function parseBool(value, name) {
+  if (/^(1|true|yes|on)$/i.test(value)) return true;
+  if (/^(0|false|no|off)$/i.test(value)) return false;
+  throw new Error(`${name} must be true or false`);
+}
+
+function parsePositiveInt(value, name) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`${name} must be a positive integer`);
+  return n;
+}

package/src/lib/fs-utils.js

@@ -0,0 +1,31 @@
+import { mkdirSync, writeFileSync, renameSync, chmodSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+/** Create a directory readable only by the current user. */
+export function ensurePrivateDir(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // mkdir's mode is masked by umask and ignored for existing dirs.
+  chmodSync(dir, 0o700);
+}
+
+/** Write JSON atomically (temp file + rename), mode 0600. */
+export function writeJsonAtomic(file, data) {
+  ensurePrivateDir(dirname(file));
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+export function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: exists but owned by someone else. Still alive.
+    return err.code === 'EPERM';
+  }
+}
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/src/lib/guard.js

@@ -0,0 +1,93 @@
+import { checkUrl } from './origins.js';
+import { PLACEHOLDER_PATH, fulfillPlaceholder } from './storage.js';
+
+// The allowlist's second layer: fleet's own CDP connection auto-attaches to
+// every target (tabs, popups, out-of-process iframes, workers) and fails
+// requests to origins that aren't allowed. waitForDebuggerOnStart means a new
+// tab is held until interception is on, so a popup can't slip its first
+// navigation through.
+//
+// Non-strict: only Document requests (navigations). Strict: every request,
+// which also stops fetch()/XHR/beacon exfiltration from evaluate_script.
+//
+// Fails closed: a tab or frame whose interception can't be switched on is
+// closed, and so is any page in a browser context other than the default one
+// (the browser-level auto-attach doesn't reach new contexts).
+
+const PAGE_LIKE = new Set(['page', 'iframe']);
+const WORKERS = new Set(['worker', 'service_worker', 'shared_worker']);
+
+export async function installGuard(cdp, { allowlist, strict = false, onBlock = () => {} }) {
+  if (!allowlist) return () => {};
+  const pattern = { urlPattern: '*', requestStage: 'Request', ...(strict ? {} : { resourceType: 'Document' }) };
+
+  // Only sessions this guard enabled interception on. Other code on the same
+  // connection (storage.js) runs its own Fetch sessions and answers those itself.
+  const guarded = new Set();
+
+  const offPaused = cdp.on('Fetch.requestPaused', (params, sessionId) => {
+    if (!guarded.has(sessionId)) return;
+    const { allowed, origin } = checkUrl(allowlist, params.request.url);
+    // Fleet's own storage tab (see storage.js). When two interceptors see the
+    // same request, whichever gets it must answer it the same way, or a
+    // "continue" from here would send it to the real site.
+    if (allowed && params.resourceType === 'Document' && new URL(params.request.url).pathname === PLACEHOLDER_PATH) {
+      fulfillPlaceholder(cdp, params.requestId, sessionId);
+      return;
+    }
+    if (allowed) {
+      cdp.send('Fetch.continueRequest', { requestId: params.requestId }, sessionId).catch(() => {});
+    } else {
+      onBlock({ url: params.request.url, origin, resourceType: params.resourceType });
+      cdp.send('Fetch.failRequest', { requestId: params.requestId, errorReason: 'BlockedByClient' }, sessionId).catch(() => {});
+    }
+  });
+
+  const offAttached = cdp.on('Target.attachedToTarget', async ({ sessionId, targetInfo, waitingForDebugger }) => {
+    const pageLike = PAGE_LIKE.has(targetInfo.type);
+    if (pageLike || (strict && WORKERS.has(targetInfo.type))) {
+      guarded.add(sessionId);
+      try {
+        await cdp.send('Fetch.enable', { patterns: [pattern] }, sessionId);
+        if (pageLike) await cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true }, sessionId);
+      } catch {
+        guarded.delete(sessionId);
+        if (pageLike) {
+          // Can't guard it, so it doesn't get to run.
+          onBlock({ url: targetInfo.url, origin: null, resourceType: `${targetInfo.type} that could not be guarded (closed)` });
+          await cdp.send('Target.closeTarget', { targetId: targetInfo.targetId }).catch(() => {});
+          return;
+        }
+      }
+    }
+    if (waitingForDebugger) await cdp.send('Runtime.runIfWaitingForDebugger', {}, sessionId).catch(() => {});
+  });
+
+  const offDetached = cdp.on('Target.detachedFromTarget', ({ sessionId }) => guarded.delete(sessionId));
+
+  // Pages in a browser context other than the default one are closed on sight.
+  // Defence in depth: fleet already refuses isolatedContext, the only way
+  // upstream creates one, so this catches only direct CDP clients, which could
+  // do anything anyway. It closes such a page, it can't stop its first load.
+  const { defaultBrowserContextId: defaultContext } = await cdp.send('Target.getBrowserContexts');
+  const { targetInfos } = await cdp.send('Target.getTargets');
+  const closeForeign = ({ targetInfo }) => {
+    if (targetInfo.type !== 'page' || !defaultContext || targetInfo.browserContextId === defaultContext) return;
+    onBlock({ url: targetInfo.url || 'about:blank', origin: null, resourceType: 'page in a separate browser context (closed)' });
+    cdp.send('Target.closeTarget', { targetId: targetInfo.targetId }).catch(() => {});
+  };
+  const offCreated = cdp.on('Target.targetCreated', closeForeign);
+  await cdp.send('Target.setDiscoverTargets', { discover: true });
+  for (const targetInfo of targetInfos) closeForeign({ targetInfo });
+
+  await cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true });
+
+  return () => {
+    offCreated();
+    offDetached();
+    offPaused();
+    offAttached();
+    cdp.send('Target.setAutoAttach', { autoAttach: false, waitForDebuggerOnStart: false }).catch(() => {});
+    cdp.send('Target.setDiscoverTargets', { discover: false }).catch(() => {});
+  };
+}