Skip to content

Chrome DevTools for coding agents

38.8 KB
Raw Blame
/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {isDeepStrictEqual} from 'node:util';

import {overrideDevToolsGlobals} from './devtools/DevtoolsUtils.js';
import type {
  HeapSnapshotManager,
  HeapSnapshotAggregateData,
  HeapSnapshotDiff,
  HeapSnapshotDetailedClassDiff,
  DuplicateStringGroup,
  HeapEdgesQueryOptions,
  HeapQueryOptions,
} from './processors/HeapSnapshotManager.js';
import {McpPage} from './McpPage.js';
import type {UncaughtError} from './collectors/PageCollector.js';
import {ServiceWorkerConsoleCollector} from './collectors/ServiceWorkerCollector.js';
import {
  Locator,
  Mutex,
  type Browser,
  type BrowserContext,
  type Connection,
  type ConsoleMessage,
  type GetPWAStateOptions,
  type InstallPWAOptions,
  type LaunchPWAOptions,
  type Page,
  type Protocol,
  type PWAState,
  type Target,
  type UninstallPWAOptions,
  type Extension,
  type Root,
  type DevTools,
} from './third_party/index.js';
import type {ParsedArguments} from './config/mcp-options.js';
import type {ReadonlyServerConfig} from './config/ServerConfig.js';
import {ToolCategory} from './tools/categories.js';
import {
  CLOSE_PAGE_ERROR,
  isCapabilityEnabled,
  type BrowserlessContext,
  type CapabilityGate,
  type Context,
  type DevToolsData,
  type SupportedExtensions,
} from './tools/ToolDefinition.js';
import type {TraceResult} from './processors/PerformanceTrace.js';
import type {Logger} from './types.js';
import {McpWorker} from './McpWorker.js';
import {getTempFilePath, resolveCanonicalPath} from './utils/files.js';
import {escapeForLog, redactUrlForLogging} from './utils/logger.js';
import {
  fetchWithValidatedRedirects,
  validateUrlNotBlocked,
} from './utils/network.js';
import type {TaskQueue, TaskRunner} from './utils/TaskRunner.js';
import {isAllowedUrl} from './utils/url.js';

export interface McpContextOptions {
  config: ReadonlyServerConfig;
  // Custom navigation timeout in milliseconds to override default.
  navigationTimeout?: number;
  // Shared heap snapshot manager to preserve loaded snapshots across browser reconnects.
  heapSnapshotManager: HeapSnapshotManager;
  // Creates the context queue and the page queues.
  taskRunner: TaskRunner;
  // Returns the browser to use. Called by ensureBrowser(), so the browser
  // connection is only established once a tool needs it.
  getBrowser: () => Promise<Browser>;
}

interface OptionGate {
  options: ReadonlyArray<keyof ParsedArguments>;
}

type FeatureController =
  | {
      gate: OptionGate;
      onChange(context: McpContext): Promise<unknown> | void;
    }
  | {
      gate: CapabilityGate;
      onDisable(context: McpContext): Promise<void> | void;
    };

function hasOptionChanged(
  gate: OptionGate,
  previousArgs: ParsedArguments,
  nextArgs: ParsedArguments,
): boolean {
  return gate.options.some(
    option => !isDeepStrictEqual(nextArgs[option], previousArgs[option]),
  );
}

const FEATURE_CONTROLLERS: readonly FeatureController[] = [
  {
    gate: {options: ['blockedUrlPattern', 'allowedUrlPattern']},
    onChange: context => context.syncNetworkRestrictions(),
  },
  {
    gate: {options: ['sourceMaps']},
    onChange: context => context.syncSourceMaps(),
  },
  {
    gate: {options: ['experimentalIncludeAllPages']},
    onChange: context => context.createPagesSnapshot(),
  },
  {
    gate: {category: ToolCategory.DEBUGGING},
    onDisable: context => context.releaseScreencasts(),
  },
  {
    gate: {category: ToolCategory.MEMORY, conditions: ['memoryDebugging']},
    onDisable: context => context.releaseHeapSnapshots(),
  },
  {
    gate: {category: ToolCategory.PERFORMANCE},
    onDisable: context => context.releasePerformanceTrace(),
  },
  {
    gate: {category: ToolCategory.DEBUGGING, conditions: ['devtoolsComments']},
    onDisable: context => context.releaseDevToolsComments(),
  },
];

// Page ids are handed out from a process-wide counter so they stay unique
// across all contexts, in particular across browser reconnects. An id issued
// before a reconnect then fails to resolve instead of hitting an unrelated
// page of the reconnected browser.
let nextPageId = 1;

export class McpContext implements Context, BrowserlessContext {
  logger: Logger;

  #browser?: Browser;
  // Initialization of #browser, settles once its browser-dependent state is
  // ready.
  #browserReady?: Promise<void>;
  // Whether a browser connection was established before, so that switching to
  // a new browser surfaces a reconnect notice.
  #hasConnected = false;

  // Maps LLM-provided isolatedContext name → Puppeteer BrowserContext.
  #isolatedContexts = new Map<string, BrowserContext>();
  // Auto-generated name counter for when no name is provided.
  #nextIsolatedContextId = 1;

  // Cached McpWorker per target, reused across snapshots (mirrors #mcpPages) so
  // referential identity holds and workers can carry per-worker state later.
  #workers = new Map<Target, McpWorker>();

  #mcpPages = new Map<Target, McpPage>();
  /**
   * Queue for the browser-wide state (page list, selected page, trace
   * state). Every page queue is a child of it, so a task on it waits for
   * every page task and blocks later page tasks.
   */
  readonly taskQueue: TaskQueue;
  #taskRunner: TaskRunner;
  #pageTaskQueues = new Map<number, TaskQueue>();
  /**
   * Serializes `createPagesSnapshot()`. Two tasks on different page queues
   * can call it at the same time.
   */
  #pagesSnapshotMutex = new Mutex();
  #selectedPage?: McpPage;
  #selectedPageFallback?: {wasClosed: boolean};
  #selectedPageFallbackRead = false;

  #serviceWorkerConsoleCollector?: ServiceWorkerConsoleCollector;

  #reconnectNotice = false;

  #traceResults: TraceResult[] = [];

  #locatorClass: typeof Locator;
  #config: ReadonlyServerConfig;
  #options: McpContextOptions;
  #heapSnapshotManager: HeapSnapshotManager;
  #roots: Root[] | undefined = undefined;

  private constructor(
    logger: Logger,
    options: McpContextOptions,
    locatorClass: typeof Locator,
  ) {
    overrideDevToolsGlobals({
      loadResource: (url: string) => {
        return this.loadResource(url);
      },
    });

    this.logger = logger;
    this.#locatorClass = locatorClass;
    this.#taskRunner = options.taskRunner;
    this.taskQueue = options.taskRunner.createQueue();
    this.#config = options.config;
    this.#options = options;
    this.#heapSnapshotManager = options.heapSnapshotManager;
  }

  /**
   * The browser of the current connection. Throws if no browser connection was
   * established yet, see {@link McpContext.ensureBrowser}.
   */
  get browser(): Browser {
    if (!this.#browser) {
      throw new Error('Not connected to a browser.');
    }
    return this.#browser;
  }

  #allMcpPages(): Set<McpPage> {
    const pages = new Set(this.#mcpPages.values());
    if (this.#selectedPage) {
      pages.add(this.#selectedPage);
    }
    return pages;
  }

  /**
   * Synchronizes browser/page state and releases state of capabilities that
   * transitioned from enabled to disabled after a config reload.
   */
  async onConfigChanged(previousArgs: ParsedArguments): Promise<void> {
    const nextArgs = this.#config.resolved;
    for (const controller of FEATURE_CONTROLLERS) {
      if ('onChange' in controller) {
        if (hasOptionChanged(controller.gate, previousArgs, nextArgs)) {
          await controller.onChange(this);
        }
      } else if (
        isCapabilityEnabled(controller.gate, previousArgs) &&
        !isCapabilityEnabled(controller.gate, nextArgs)
      ) {
        await controller.onDisable(this);
      }
    }
  }

  /**
   * Applies updated URL allowlist/blocklist rules to the connected browser and
   * clears incompatible page network throttling state.
   */
  async syncNetworkRestrictions(): Promise<void> {
    const {blockedUrlPattern, allowedUrlPattern} = this.#config.resolved;
    if (blockedUrlPattern || allowedUrlPattern) {
      for (const mcpPage of this.#allMcpPages()) {
        await mcpPage.clearNetworkConditions();
      }
    }
    if (this.#browser) {
      await this.#browser.restrictNetwork({
        blocklist: blockedUrlPattern,
        allowlist: allowedUrlPattern,
      });
    }
  }

  /**
   * Synchronizes the DevTools source maps setting across all pages.
   */
  syncSourceMaps(): void {
    for (const mcpPage of this.#allMcpPages()) {
      mcpPage.syncSourceMaps();
    }
  }

  /**
   * Stops and saves active screencast recordings across all pages when
   * screencast tools are disabled.
   */
  async releaseScreencasts(): Promise<void> {
    for (const mcpPage of this.#allMcpPages()) {
      const screenRecorderData = mcpPage.getScreenRecorder();
      if (!screenRecorderData) {
        continue;
      }
      const {recorder, filePath} = screenRecorderData;
      mcpPage.setScreenRecorder(null);
      try {
        await recorder.stop();
        this.logger?.(
          `The screencast recording was stopped and saved to ${filePath} because screencast tools were disabled.`,
        );
      } catch (err) {
        this.logger?.('Failed to stop the screencast recording', err);
      }
    }
  }

  /**
   * Closes all loaded heap snapshots when memory tools are disabled.
   */
  releaseHeapSnapshots(): void {
    if (this.#heapSnapshotManager.hasSnapshots()) {
      this.#heapSnapshotManager.dispose();
      this.logger?.(
        'Loaded heap snapshots were closed because memory tools were disabled.',
      );
    }
  }

  /**
   * Discards recorded performance traces and stops any running trace when
   * performance tools are disabled.
   */
  async releasePerformanceTrace(): Promise<void> {
    this.#traceResults = [];
    for (const mcpPage of this.#allMcpPages()) {
      if (!mcpPage.isRunningPerformanceTrace()) {
        continue;
      }
      mcpPage.setIsRunningPerformanceTrace(false);
      try {
        await mcpPage.pptrPage.tracing.stop();
      } catch (err) {
        this.logger?.('Failed to stop the performance trace', err);
      }
      this.logger?.(
        'The running performance trace was discarded because performance tools were disabled.',
      );
    }
  }

  /**
   * Disposes DevTools comment bridges across all pages when DevTools comment
   * tools are disabled.
   */
  releaseDevToolsComments(): void {
    for (const mcpPage of this.#allMcpPages()) {
      mcpPage.disposeCommentBridge();
    }
  }

  /**
   * Returns the browser, establishing the connection if needed. If the browser
   * changed since the last call (e.g. after a reconnect), all
   * browser-dependent state is rebuilt for the new browser.
   */
  async ensureBrowser(): Promise<Browser> {
    const browser = await this.#options.getBrowser();
    if (browser === this.#browser && this.#browserReady) {
      // Joins a still pending initialization instead of handing out
      // half-initialized state.
      await this.#browserReady;
      return browser;
    }

    this.#resetBrowserState();
    this.#browser = browser;
    const ready = this.#initBrowserState(browser);
    this.#browserReady = ready;
    try {
      await ready;
      return browser;
    } catch (err) {
      // Leave no half-initialized state behind, the next call starts over. If
      // a later call already installed another browser, its state is left
      // intact.
      if (this.#browserReady === ready) {
        this.#resetBrowserState();
      }
      throw err;
    }
  }

  async #initBrowserState(browser: Browser): Promise<void> {
    const collector = new ServiceWorkerConsoleCollector(browser);
    this.#serviceWorkerConsoleCollector = collector;
    // All listeners are registered synchronously, before the first await. If
    // this call hangs and is abandoned by the tool-call timeout, a later call
    // that installs a different browser removes them in #resetBrowserState().
    browser.on('targetcreated', this.#onTargetCreated);
    browser.on('targetdestroyed', this.#onTargetDestroyed);
    await Promise.all([
      collector.init(this.createWorkersSnapshot()),
      this.createPagesSnapshot(),
    ]);
    // The state now belongs to the browser of a later call, leave it intact.
    if (this.#browser !== browser) {
      throw new Error('Browser was replaced while initializing.');
    }

    if (this.#hasConnected) {
      this.#reconnectNotice = true;
    }
    this.#hasConnected = true;
  }

  #resetBrowserState(): void {
    this.#browser?.off('targetcreated', this.#onTargetCreated);
    this.#browser?.off('targetdestroyed', this.#onTargetDestroyed);

    this.#serviceWorkerConsoleCollector?.dispose();
    for (const mcpPage of this.#allMcpPages()) {
      this.#disposeMcpPage(mcpPage);
    }
    this.#mcpPages.clear();
    this.#workers.clear();
    // Isolated contexts are intentionally not closed here.
    // Either the entire browser will be closed or we disconnect
    // without destroying browser state.
    this.#isolatedContexts.clear();
    this.#nextIsolatedContextId = 1;
    this.#selectedPage = undefined;
    this.#selectedPageFallback = undefined;
    this.#selectedPageFallbackRead = false;
    this.#traceResults = [];
    this.#serviceWorkerConsoleCollector = undefined;
    this.#browser = undefined;
    this.#browserReady = undefined;
  }

  dispose(): void {
    this.#resetBrowserState();
  }

  #onTargetCreated = (target: Target): void => {
    try {
      if (!this.#isPageTarget(target)) {
        return;
      }
      this.#createMcpPage(target);
    } catch (err) {
      this.logger?.('Error handling targetcreated', err);
    }
  };

  #onTargetDestroyed = (target: Target): void => {
    try {
      const mcpPage = this.#mcpPages.get(target);
      if (mcpPage) {
        this.#disposeMcpPage(mcpPage);
        this.#mcpPages.delete(target);
      }
      this.#workers.delete(target);
    } catch (err) {
      this.logger?.('Error handling targetdestroyed', err);
    }
  };

  static create(
    logger: Logger,
    opts: McpContextOptions,
    /* Let tests use unbundled Locator class to avoid overly strict checks within puppeteer that fail when mixing bundled and unbundled class instances */
    locatorClass: typeof Locator = Locator,
  ): McpContext {
    return new McpContext(logger, opts, locatorClass);
  }

  static resetPageIdsForTesting(): void {
    nextPageId = 1;
  }

  static resetWorkerIdsForTesting(): void {
    McpWorker.resetIdsForTesting();
  }

  roots(): Root[] {
    return [
      ...(this.#roots ?? []),
      {
        uri: pathToFileURL(os.tmpdir()).href,
        name: 'temp',
      },
    ];
  }

  setRoots(roots: Root[] | undefined): void {
    this.#roots = roots;
  }

  /**
   * Validates that the filePath is allowed according to the roots configuration.
   * Tolerates if parts of the filePath do not exist yet but the file access to
   * the resolved should only be allowed without following symlinks.
   */
  async validatePath(filePath: string): Promise<string>;
  async validatePath(filePath?: undefined): Promise<undefined>;
  async validatePath(filePath?: string): Promise<string | undefined>;
  async validatePath(filePath?: string): Promise<string | undefined> {
    if (filePath === undefined) {
      return undefined;
    }

    let canonicalPath: string;

    try {
      canonicalPath = await resolveCanonicalPath(filePath);
    } catch (err) {
      const errMsg = err instanceof Error ? err.message : String(err);
      console.error(
        `[MCP Context] Error resolving real path for ${escapeForLog(filePath)}: ${escapeForLog(errMsg)}`,
      );
      throw new Error(
        `Access denied: Cannot resolve base path for ${escapeForLog(filePath)}.`,
      );
    }

    // If the client never negotiated roots and the operator has explicitly
    // opted into unrestricted access via --allow-unrestricted-paths, restore
    // the previous permissive behavior and skip validation.
    if (
      this.#roots === undefined &&
      this.#config.resolved.allowUnrestrictedPaths
    ) {
      // Canonical path might not exist yet so we fallback to
      // path.resolve(filePath). Consumers should not follow symlinks.
      return canonicalPath || path.resolve(filePath);
    }
    // roots() always returns at least the temp directory, even if the
    // connecting client never negotiated the optional `roots` capability.
    // Path validation must not be skipped just because no workspace roots
    // were configured.
    const roots = this.roots();

    let allowed = false;
    const resolvedRoots = await Promise.allSettled(
      roots.map(async root => {
        const rootPathUri = root.uri;
        const rootPath = path.resolve(fileURLToPath(rootPathUri));
        return await fs.realpath(rootPath);
      }),
    );

    for (let i = 0; i < roots.length; i++) {
      const root = roots[i];
      const result = resolvedRoots[i];

      if (result.status === 'fulfilled') {
        const canonicalRoot = result.value;
        // A filesystem root such as `/` or `C:\` already ends with the
        // separator; appending another one would match no path below it.
        const rootPrefix = canonicalRoot.endsWith(path.sep)
          ? canonicalRoot
          : canonicalRoot + path.sep;
        if (
          canonicalPath === canonicalRoot ||
          canonicalPath.startsWith(rootPrefix)
        ) {
          allowed = true;
          break;
        }
      } else {
        const rootErr = result.reason;
        const errMsg =
          rootErr instanceof Error ? rootErr.message : String(rootErr);
        console.warn(
          `[MCP Context] Could not resolve configured root ${escapeForLog(root.uri)}: ${escapeForLog(errMsg)}`,
        );
        // Skip this root if it cannot be resolved.
      }
    }

    if (!allowed) {
      throw new Error(
        `Access denied: path ${escapeForLog(filePath)} (canonical: ${escapeForLog(canonicalPath)}) is not within any of the configured workspace roots.`,
      );
    }

    return canonicalPath || path.resolve(filePath);
  }

  async ensureExtension<Extension extends `.${string}`>(
    filePath: string,
    extension: Extension,
  ): Promise<`${string}${Extension}`> {
    const resolved = await this.validatePath(filePath);
    const currentExtension = path.extname(resolved);
    const outputPath: `${string}${Extension}` = `${resolved.slice(
      0,
      resolved.length - currentExtension.length,
    )}${extension}`;
    return outputPath;
  }

  async newPage(
    background?: boolean,
    isolatedContextName?: string,
  ): Promise<McpPage> {
    let page: Page;
    if (isolatedContextName !== undefined) {
      let ctx = this.#isolatedContexts.get(isolatedContextName);
      if (!ctx) {
        ctx = await this.browser.createBrowserContext();
        this.#isolatedContexts.set(isolatedContextName, ctx);
      }
      page = await ctx.newPage({background});
    } else {
      page = await this.browser.newPage({background});
    }
    const mcpPage = this.#createMcpPage(page.target());
    await mcpPage.init({emulateFocus: true});
    this.selectPage(mcpPage);
    await this.createPagesSnapshot();
    return mcpPage;
  }
  async closePage(pageId: number): Promise<void> {
    const page = this.getPageById(pageId);
    if (this.#mcpPages.size === 1) {
      throw new Error(CLOSE_PAGE_ERROR);
    }
    this.#mcpPages.delete(page.target);
    await page.close();
  }

  async installPWA(options: InstallPWAOptions): Promise<string> {
    try {
      return await this.browser.installPWA(options);
    } catch (error) {
      if (
        error instanceof Error &&
        error.message.includes("Couldn't fetch install info")
      ) {
        return await this.browser.installPWA(options);
      }
      throw error;
    }
  }

  uninstallPWA(options: UninstallPWAOptions): Promise<void> {
    return this.browser.uninstallPWA(options);
  }

  async launchPWA(options: LaunchPWAOptions): Promise<Page> {
    const page = await this.browser.launchPWA(options);
    if (!page.url() || page.url() === 'about:blank') {
      await page
        .waitForNavigation({
          timeout: this.#options.navigationTimeout ?? 10_000,
        })
        .catch(() => {
          // Ignore timeout if navigation already completed or failed.
        });
    }
    return page;
  }

  getPWAState(options: GetPWAStateOptions): Promise<PWAState> {
    return this.browser.getPWAState(options);
  }

  isRunningPerformanceTrace(): boolean {
    for (const mcpPage of this.#allMcpPages()) {
      if (mcpPage.isRunningPerformanceTrace()) {
        return true;
      }
    }
    return false;
  }

  isCruxEnabled(): boolean {
    return this.#config.resolved.performanceCrux;
  }

  getPages(): McpPage[] {
    return Array.from(this.#mcpPages.values());
  }

  /**
   * Fetches current target info for all targets from the browser, keyed by
   * target id. Unlike Puppeteer's cached target info, this reflects title
   * changes, which Chrome does not report via `Target.targetInfoChanged`.
   * Returns an empty map if the browser cannot be queried.
   */
  async getTargetInfos(): Promise<Map<string, Protocol.Target.TargetInfo>> {
    try {
      // @ts-expect-error use existing browser connection (internal Puppeteer API).
      const connection: Connection = this.browser._connection;
      const {targetInfos} = await connection.send('Target.getTargets');
      return new Map(targetInfos.map(info => [info.targetId, info]));
    } catch (err) {
      this.logger?.('Failed to fetch target infos', err);
      return new Map();
    }
  }

  getSelectedMcpPage(): McpPage {
    const page = this.#selectedPage;
    if (!page) {
      throw new Error('No page selected');
    }
    if (page.isClosed()) {
      throw new Error(
        'The selected page has been closed. Call list_pages to see open pages.',
      );
    }
    return page;
  }

  getSelectedMcpPageUrl(page?: McpPage): string | undefined {
    let targetPage = page;
    if (!targetPage) {
      try {
        targetPage = this.getSelectedMcpPage();
      } catch {
        return undefined;
      }
    }
    if (targetPage && !targetPage.isClosed()) {
      return targetPage.url();
    }
    return undefined;
  }

  async getDevToolsData(page?: McpPage): Promise<DevToolsData | undefined> {
    const targetPage = page ?? this.#selectedPage;
    if (!targetPage) {
      return undefined;
    }
    let timeoutId: ReturnType<typeof setTimeout> | undefined;
    const timeoutPromise = new Promise<undefined>(resolve => {
      timeoutId = setTimeout(() => resolve(undefined), 500);
    });
    const dataPromise = targetPage.getDevToolsData();
    try {
      return await Promise.race([dataPromise, timeoutPromise]);
    } catch {
      return undefined;
    } finally {
      clearTimeout(timeoutId);
    }
  }

  /**
   * Returns true once after the browser connection was re-established with a
   * new browser, so the next response can surface a note. Cleared on first
   * call.
   */
  consumeReconnectNotice(): boolean {
    const notice = this.#reconnectNotice;
    this.#reconnectNotice = false;
    return notice;
  }

  getPageById(pageId: number): McpPage {
    const page = this.#mcpPages.values().find(mcpPage => mcpPage.id === pageId);
    if (!page) {
      throw new Error('No page found');
    }
    return page;
  }

  /**
   * The queue for tasks on page `pageId`. The queue exists before the page
   * does, so a tool call can enter it before the browser connects. It is a
   * child of {@link taskQueue}.
   */
  pageTaskQueue(pageId: number): TaskQueue {
    let queue = this.#pageTaskQueues.get(pageId);
    if (!queue) {
      queue = this.#taskRunner.createQueue(this.taskQueue);
      this.#pageTaskQueues.set(pageId, queue);
    }
    return queue;
  }

  #disposeMcpPage(mcpPage: McpPage): void {
    mcpPage.dispose();
    this.#pageTaskQueues
      .get(mcpPage.id)
      ?.dispose(new Error(`Page ${mcpPage.id} is closed.`));
    this.#pageTaskQueues.delete(mcpPage.id);
  }

  isPageSelected(page: McpPage): boolean {
    return this.#selectedPage === page;
  }

  selectPage(newPage: McpPage): void {
    this.#selectedPageFallback = undefined;
    this.#selectedPageFallbackRead = false;
    this.#selectPage(newPage);
  }

  #selectPage(newPage: McpPage): void {
    if (
      this.#selectedPage &&
      this.#selectedPage !== newPage &&
      !this.#mcpPages.has(this.#selectedPage.target)
    ) {
      this.#disposeMcpPage(this.#selectedPage);
    }
    this.#selectedPage = newPage;
    newPage.updateTimeouts();
  }

  /**
   * Returns details about the last page snapshot automatically replacing the
   * selection because the selected page disappeared from the page list, or
   * `undefined` if the snapshot left the selection intact. Cleared on the next
   * createPagesSnapshot() call after it has been read, or when selectPage() is
   * called explicitly.
   */
  getSelectedPageFallback(): {wasClosed: boolean} | undefined {
    this.#selectedPageFallbackRead = true;
    return this.#selectedPageFallback;
  }

  /**
   * Creates a snapshot of the tracked workers. Today this is limited to
   * extension service workers; the McpWorker abstraction lets dedicated and
   * shared workers join the same snapshot later without changing consumers.
   */
  createWorkersSnapshot(): McpWorker[] {
    const serviceWorkers = this.browser.targets().filter(target => {
      return (
        target.type() === 'service_worker' &&
        target.url().includes('chrome-extension://')
      );
    });

    // Reuse the existing McpWorker for a target; only mint one (and an id) for
    // targets seen for the first time.
    for (const target of serviceWorkers) {
      if (!this.#workers.has(target)) {
        this.#workers.set(target, McpWorker.create('service_worker', target));
      }
    }

    // Prune workers whose target is gone (mirrors #mcpPages pruning).
    const currentTargets = new Set(serviceWorkers);
    for (const target of this.#workers.keys()) {
      if (!currentTargets.has(target)) {
        this.#workers.delete(target);
      }
    }

    return Array.from(this.#workers.values());
  }

  getServiceWorkerConsoleData(
    serviceWorkerId: string,
  ): Array<ConsoleMessage | UncaughtError> {
    const worker = this.getWorkerById(serviceWorkerId);
    if (worker?.type !== 'service_worker') {
      throw new Error('Service worker not found.');
    }
    const extensionId = new URL(worker.url).hostname;
    return this.#serviceWorkerConsoleCollector?.getData(extensionId) ?? [];
  }

  #getBrowserContextToNameMap(): Map<BrowserContext, string> {
    // Build a reverse lookup from BrowserContext instance → name.
    const contextToName = new Map<BrowserContext, string>();
    for (const [name, ctx] of this.#isolatedContexts) {
      contextToName.set(ctx, name);
    }
    const defaultCtx = this.browser.defaultBrowserContext();
    // Auto-discover BrowserContexts not in our mapping (e.g., externally
    // created incognito contexts) and assign generated names.
    const knownContexts = new Set(this.#isolatedContexts.values());
    for (const ctx of this.browser.browserContexts()) {
      if (ctx !== defaultCtx && !ctx.closed && !knownContexts.has(ctx)) {
        const name = `isolated-context-${this.#nextIsolatedContextId++}`;
        this.#isolatedContexts.set(name, ctx);
        contextToName.set(ctx, name);
      }
    }
    return contextToName;
  }

  #createMcpPage(target: Target): McpPage {
    let mcpPage =
      this.#mcpPages.get(target) ??
      (this.#selectedPage?.target === target ? this.#selectedPage : undefined);
    if (!mcpPage) {
      mcpPage = new McpPage(target, nextPageId++, {
        config: this.#config,
        locatorClass: this.#locatorClass,
        isolatedContextName: this.#getBrowserContextToNameMap().get(
          target.browserContext(),
        ),
        navigationTimeout: this.#options.navigationTimeout,
      });
    }
    this.#mcpPages.set(target, mcpPage);
    return mcpPage;
  }

  async createPagesSnapshot(): Promise<McpPage[]> {
    if (!this.#browser) {
      return [];
    }
    using guard = await this.#pagesSnapshotMutex.acquire();
    const allTargets = this.#fetchPageTargets();

    for (const target of allTargets) {
      this.#createMcpPage(target);
    }

    // Prune orphaned #mcpPages entries (targets that no longer exist).
    const currentTargets = new Set(allTargets);
    for (const [target, mcpPage] of this.#mcpPages) {
      if (!currentTargets.has(target)) {
        if (mcpPage !== this.#selectedPage || mcpPage.isClosed()) {
          this.#disposeMcpPage(mcpPage);
        }
        this.#mcpPages.delete(target);
      }
    }

    const pages = Array.from(this.#mcpPages.values());

    // Only fall back when the selected page is actually gone or no longer
    // counts as a page, e.g. a background page after
    // experimentalIncludeAllPages was turned off. Gating on `isClosed()`
    // instead of `pages` membership avoids silently swapping a live page that
    // is momentarily missing from the snapshot.
    if (this.#selectedPageFallbackRead) {
      this.#selectedPageFallback = undefined;
      this.#selectedPageFallbackRead = false;
    }
    if (
      !this.#selectedPage ||
      this.#selectedPage.isClosed() ||
      !this.#isPageTarget(this.#selectedPage.target)
    ) {
      if (pages[0]) {
        // Record the automatic change so the response can surface it. Skipped on
        // first connect, when there was no prior selection to replace.
        if (this.#selectedPage) {
          this.#selectedPageFallback = {
            wasClosed: this.#selectedPage.isClosed(),
          };
        }
        this.#selectPage(pages[0]);
      } else if (this.#selectedPage) {
        const wasClosed = Boolean(this.#selectedPage.isClosed());
        if (!wasClosed) {
          this.#disposeMcpPage(this.#selectedPage);
        }
        this.#selectedPage = undefined;
        this.#selectedPageFallback = {wasClosed};
      }
    }

    if (this.#selectedPage && !this.#selectedPage.isClosed()) {
      // Automatic page snapshots must preserve real focus on untouched tabs.
      await this.#selectedPage.init({emulateFocus: false});
    }

    return pages;
  }

  #isPageTarget(target: Target): boolean {
    const existingMcpPage =
      this.#mcpPages.get(target) ??
      (this.#selectedPage?.target === target ? this.#selectedPage : undefined);
    const url = existingMcpPage ? existingMcpPage.url() : target.url();
    if (
      !this.#config.resolved.experimentalDevtools &&
      url.startsWith('devtools://')
    ) {
      return false;
    }
    if (
      !isAllowedUrl(url, {
        categoryExtensions: this.#config.resolved.categoryExtensions,
      })
    ) {
      return false;
    }
    const type = target.type();
    if (type === 'page') {
      return true;
    }
    if (
      this.#config.resolved.experimentalIncludeAllPages &&
      (type === 'background_page' || type === 'webview')
    ) {
      return true;
    }
    if (
      this.#config.resolved.experimentalDevtools &&
      type === 'other' &&
      url.startsWith('devtools://')
    ) {
      return true;
    }
    return false;
  }

  #fetchPageTargets(): Target[] {
    return this.browser.targets().filter(target => this.#isPageTarget(target));
  }

  getWorkers(): McpWorker[] {
    return Array.from(this.#workers.values());
  }

  getWorkerById(id: string): McpWorker | undefined {
    return this.#workers.values().find(worker => worker.id === id);
  }

  async #writeFile(
    filepath: string,
    data: Uint8Array<ArrayBufferLike>,
  ): Promise<void> {
    const resolved = await this.validatePath(filepath);

    try {
      await fs.mkdir(path.dirname(resolved), {recursive: true});
      // Open the file with flags to:
      // - O_WRONLY: Write-only
      // - O_CREAT: Create if it doesn't exist
      // - O_TRUNC: Truncate to zero length if it exists
      // - O_NOFOLLOW: DO NOT follow symlinks.
      // - 0o600: Permissions: read/write for owner, no permissions for others.
      await fs.writeFile(resolved, data, {
        flag:
          fs.constants.O_WRONLY |
          fs.constants.O_CREAT |
          fs.constants.O_TRUNC |
          fs.constants.O_NOFOLLOW,
        mode: 0o600,
      });
    } catch (err) {
      throw new Error(`Could not write ${escapeForLog(filepath)}`, {
        cause: err,
      });
    }
  }

  async saveTemporaryFile(
    data: Uint8Array<ArrayBufferLike>,
    filename: string,
  ): Promise<{filepath: string}> {
    const filepath = await getTempFilePath(filename);
    await this.#writeFile(filepath, data);
    return {filepath};
  }

  async saveFile(
    data: Uint8Array<ArrayBufferLike>,
    clientProvidedFilePath: string,
    extension: SupportedExtensions,
  ): Promise<{filename: string}> {
    const filePath = await this.ensureExtension(
      clientProvidedFilePath,
      extension,
    );
    await this.#writeFile(filePath, data);
    return {filename: filePath};
  }

  storeTraceRecording(result: TraceResult): void {
    // Clear the trace results because we only consume the latest trace currently.
    this.#traceResults = [];
    this.#traceResults.push(result);
  }

  recordedTraces(): TraceResult[] {
    return this.#traceResults;
  }

  async installExtension(extensionPath: string): Promise<string> {
    const id = await Promise.race([
      this.browser.installExtension(extensionPath),
      new Promise<string>((_, rej) =>
        setTimeout(() => rej(new Error('Timeout installing extension')), 30000),
      ),
    ]);
    return id;
  }

  async uninstallExtension(id: string): Promise<void> {
    await Promise.race([
      this.browser.uninstallExtension(id),
      new Promise<void>((_, rej) =>
        setTimeout(
          () => rej(new Error('Timeout uninstalling extension')),
          30000,
        ),
      ),
    ]);
  }

  async triggerExtensionAction(id: string): Promise<void> {
    const extensions = await this.browser.extensions();
    const extension = extensions.get(id);
    if (!extension) {
      throw new Error(`Extension with ID ${id} not found.`);
    }
    const page = this.getSelectedMcpPage().pptrPage;
    await extension.triggerAction(page);
  }

  listExtensions(): Promise<Map<string, Extension>> {
    return this.browser.extensions();
  }

  async getExtension(id: string): Promise<Extension | undefined> {
    const pptrExtensions = await this.browser.extensions();
    return pptrExtensions.get(id);
  }

  async getHeapSnapshotAggregates(
    filePath: string,
    filterName?: string,
    objectId?: number,
  ): Promise<HeapSnapshotAggregateData> {
    return await this.#heapSnapshotManager.getAggregates(
      filePath,
      filterName,
      objectId,
    );
  }

  async getHeapSnapshotDuplicateStrings(
    filePath: string,
  ): Promise<DuplicateStringGroup[]> {
    return await this.#heapSnapshotManager.getDuplicateStrings(filePath);
  }

  async queryHeapSnapshotObjects(
    filePath: string,
    options: HeapQueryOptions,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    return await this.#heapSnapshotManager.queryObjects(filePath, options);
  }

  async getHeapSnapshotStats(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.Statistics> {
    return await this.#heapSnapshotManager.getStats(filePath);
  }

  async getHeapSnapshotStaticData(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.StaticData | null> {
    return await this.#heapSnapshotManager.getStaticData(filePath);
  }

  async getHeapSnapshotNativeContextSizes(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.NativeContextSizes> {
    return await this.#heapSnapshotManager.getNativeContextSizes(filePath);
  }

  async getHeapSnapshotRetainedByContextSummary(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainedByContextSummary> {
    return await this.#heapSnapshotManager.getRetainedByContextSummary(
      filePath,
    );
  }

  async getHeapSnapshotNodesById(
    filePath: string,
    id: number,
    filterName?: string,
    objectId?: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    return await this.#heapSnapshotManager.getNodesById(
      filePath,
      id,
      filterName,
      objectId,
    );
  }

  async getHeapSnapshotRetainers(
    filePath: string,
    nodeId: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    return await this.#heapSnapshotManager.getRetainers(filePath, nodeId);
  }

  async getHeapSnapshotObjectDetails(
    filePath: string,
    nodeId: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ObjectInfo> {
    return await this.#heapSnapshotManager.getObjectInfo(filePath, nodeId);
  }

  async analyzeHeapSnapshotContexts(
    filePath: string,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ContextAnalysisResult> {
    return await this.#heapSnapshotManager.analyzeContexts(filePath);
  }

  async closeHeapSnapshot(filePath: string): Promise<boolean> {
    return await this.#heapSnapshotManager.disposeSnapshot(filePath);
  }

  async getHeapSnapshotRetainingPaths(
    filePath: string,
    nodeId: number,
    maxDepth?: number,
    maxNodes?: number,
    maxSiblings?: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.RetainingPaths> {
    return await this.#heapSnapshotManager.getRetainingPaths(
      filePath,
      nodeId,
      maxDepth,
      maxNodes,
      maxSiblings,
    );
  }

  async getHeapSnapshotDominators(
    filePath: string,
    nodeId: number,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.DominatorChain> {
    return await this.#heapSnapshotManager.getDominatorsOf(filePath, nodeId);
  }

  async #loadNetworkResource(url: URL): Promise<string> {
    const response = await fetchWithValidatedRedirects(url, {
      policy: this.#config.resolved,
    });
    if (!response.ok) {
      throw new Error(
        'Failed to load resource: ' +
          redactUrlForLogging(response.url || url.href),
      );
    }
    return await response.text();
  }

  async loadResource(path: string): Promise<string> {
    const url = new URL(path);

    validateUrlNotBlocked(url, this.#config.resolved.blockedUrlPattern);

    switch (url.protocol) {
      case 'https:':
      case 'http:': {
        return await this.#loadNetworkResource(url);
      }

      case 'file:': {
        const resolved = await this.validatePath(fileURLToPath(url));
        return await fs.readFile(resolved, 'utf-8');
      }

      default:
        throw new Error(`Unsupported protocol for: ${url}`);
    }
  }

  async getHeapSnapshotEdges(
    filePath: string,
    nodeId: number,
    options?: HeapEdgesQueryOptions,
  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
    return await this.#heapSnapshotManager.getEdges(filePath, nodeId, options);
  }

  async getHeapSnapshotClassDiffs(
    baseFilePath: string,
    currentFilePath: string,
  ): Promise<HeapSnapshotDiff> {
    return await this.#heapSnapshotManager.getClassDiffs(
      baseFilePath,
      currentFilePath,
    );
  }

  async getHeapSnapshotDetailedClassDiff(
    baseFilePath: string,
    currentFilePath: string,
    classIndex: number,
  ): Promise<HeapSnapshotDetailedClassDiff> {
    return await this.#heapSnapshotManager.getDetailedClassDiff(
      baseFilePath,
      currentFilePath,
      classIndex,
    );
  }
}