Skip to content

Chrome DevTools for coding agents

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

import type {Page} from '../third_party/index.js';
import type {CD4ACommentThread} from '../types.js';
import {logger} from '../utils/logger.js';

export interface DevToolsCommentBridgeOptions {
  debounceMs?: number;
}

const DEFAULT_DEBOUNCE_MS = 200;

/**
 * Manages the bridge between DevTools frontend comments and the MCP server.
 * Comment events are debounced and delivered to callers that wait for them
 * through `waitForCommentEvent`.
 */
export class DevToolsCommentBridge {
  readonly #debounceMs: number;
  #commentDebounceTimer?: NodeJS.Timeout;
  readonly #attachedPages = new Set<Page>();
  readonly #commentWaiters = new Set<(changed: boolean) => void>();

  constructor(options?: DevToolsCommentBridgeOptions) {
    this.#debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
  }

  isAttached(devtoolsPage: Page): boolean {
    return this.#attachedPages.has(devtoolsPage);
  }

  /**
   * Attaches to the DevTools page if it exposes the CD4A bridge.
   *
   * Returns false if the bridge does not exist, e.g., because the connected
   * Chrome version does not support DevTools comments or the feature is
   * disabled, or if the comment event binding could not be installed.
   * Negative results are not cached so that a DevTools window that has not
   * finished loading yet is checked again on the next call.
   */
  async attach(devtoolsPage: Page): Promise<boolean> {
    if (this.#attachedPages.has(devtoolsPage)) {
      return true;
    }

    try {
      const hasBridge = await devtoolsPage.evaluate(() => {
        return Boolean(window.universe?.cd4aBridge);
      });
      if (!hasBridge) {
        return false;
      }
    } catch (e) {
      logger?.('DevToolsCommentBridge: evaluate failed', e);
      return false;
    }

    try {
      await devtoolsPage.exposeFunction('__onDevToolsCommentEvent', () => {
        this.#handleCommentEvent();
      });
    } catch (e) {
      // The binding may already exist, e.g., exposed by a previous bridge.
      // Whether it is usable is checked in the page below.
      logger?.(
        'DevToolsCommentBridge: exposeFunction already bound or failed',
        e,
      );
    }

    let attached = false;
    try {
      attached = await devtoolsPage.evaluate(() => {
        const cd4aBridge = window.universe?.cd4aBridge;
        if (
          !cd4aBridge ||
          typeof window.__onDevToolsCommentEvent !== 'function'
        ) {
          return false;
        }
        if (window.__onDevToolsCommentListener) {
          cd4aBridge.removeEventListener(
            'CommentThreadsChanged',
            window.__onDevToolsCommentListener,
          );
        }
        window.__onDevToolsCommentListener = () => {
          window.__onDevToolsCommentEvent?.();
        };
        cd4aBridge.addEventListener(
          'CommentThreadsChanged',
          window.__onDevToolsCommentListener,
        );
        cd4aBridge.setAgentAttached(true);
        return true;
      });
    } catch (e) {
      logger?.('DevToolsCommentBridge: evaluate failed', e);
    }
    if (!attached) {
      return false;
    }
    this.#attachedPages.add(devtoolsPage);
    return true;
  }

  async getComments(devtoolsPage: Page): Promise<CD4ACommentThread[]> {
    return await devtoolsPage.evaluate(() => {
      window.universe?.cd4aBridge?.setAgentAttached(true);
      return window.universe?.cd4aBridge?.getCommentThreads() ?? [];
    });
  }

  /**
   * Resolves `true` on the next debounced comment event, or `false` when
   * `timeoutMs` elapses or the bridge is disposed first.
   */
  waitForCommentEvent(timeoutMs: number): Promise<boolean> {
    return new Promise<boolean>(resolve => {
      const settle = (changed: boolean): void => {
        clearTimeout(timer);
        this.#commentWaiters.delete(settle);
        resolve(changed);
      };
      const timer = setTimeout(() => {
        settle(false);
      }, timeoutMs);
      this.#commentWaiters.add(settle);
    });
  }

  #handleCommentEvent(): void {
    if (this.#commentDebounceTimer) {
      clearTimeout(this.#commentDebounceTimer);
    }
    this.#commentDebounceTimer = setTimeout(() => {
      this.#notifyCommentWaiters(true);
    }, this.#debounceMs);
  }

  #notifyCommentWaiters(changed: boolean): void {
    for (const waiter of [...this.#commentWaiters]) {
      waiter(changed);
    }
  }

  dispose(): void {
    if (this.#commentDebounceTimer) {
      clearTimeout(this.#commentDebounceTimer);
      this.#commentDebounceTimer = undefined;
    }
    this.#notifyCommentWaiters(false);
    for (const page of this.#attachedPages) {
      try {
        const result = page.evaluate(() => {
          if (window.__onDevToolsCommentListener) {
            window.universe?.cd4aBridge?.removeEventListener(
              'CommentThreadsChanged',
              window.__onDevToolsCommentListener,
            );
            delete window.__onDevToolsCommentListener;
          }
          window.universe?.cd4aBridge?.setAgentAttached(false);
        });
        if (result && typeof result.catch === 'function') {
          void result.catch(e => {
            logger?.(
              'DevToolsCommentBridge: failed to remove event listener',
              e,
            );
          });
        }
      } catch (e) {
        logger?.('DevToolsCommentBridge: failed to remove event listener', e);
      }
    }
    this.#attachedPages.clear();
  }
}