Skip to content

Chrome DevTools for coding agents

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

import {zod} from '../third_party/index.js';

import type {CD4ACommentThread, CD4ARevealTarget} from '../types.js';

import {ToolCategory} from './categories.js';
import {definePageTool, type PageToolFactory} from './ToolDefinition.js';

export type CommentThreadPayload = CD4ACommentThread;
export type RevealTargetPayload = CD4ARevealTarget;

const DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE =
  'DevTools comments are not working right now. Possible reasons: the connected Chrome version does not support DevTools comments, the feature is disabled, or the DevTools window has not finished loading. Try again later, or continue without DevTools comments.';

export const openDevtools: PageToolFactory = definePageTool(() => ({
  name: 'open_devtools',
  description: 'Open a DevTools window for the selected page.',
  annotations: {
    category: ToolCategory.DEBUGGING,
    readOnlyHint: true,
    conditions: ['devtoolsComments'],
  },
  schema: {},
  blockedByDialog: false,
  concurrency: 'exclusive',
  verifyFilesSchema: [],
  handler: async (request, response) => {
    const page = request.page;
    try {
      const devtoolsPage = await page.openDevTools();
      if (devtoolsPage) {
        await page.ensureDevToolsCommentBridge(devtoolsPage);
      }
      response.appendResponseLine('DevTools window opened successfully.');
    } catch (e) {
      const message = e instanceof Error ? e.message : String(e);
      response.appendResponseLine(`Failed to open DevTools: ${message}`);
    }
    response.setIncludePages(true);
  },
}));

const DEFAULT_COMMENT_WAIT_MS = 10_000;
const MAX_COMMENT_WAIT_MS = 30_000;

export const getDevtoolsComments: PageToolFactory = definePageTool(() => ({
  name: 'get_devtools_comments',
  description:
    'Retrieve user comments from the DevTools window for the page. ' +
    'If no comment is pending, waits up to `timeout` ms for the user to send one, then returns. ' +
    'Call it again to keep waiting.',
  annotations: {
    category: ToolCategory.DEBUGGING,
    readOnlyHint: true,
    conditions: ['devtoolsComments'],
  },
  schema: {
    timeout: zod
      .number()
      .int()
      .min(0)
      .max(MAX_COMMENT_WAIT_MS)
      .optional()
      .describe(
        `Maximum time in milliseconds to wait for a new comment when none is pending. ` +
          `Defaults to ${DEFAULT_COMMENT_WAIT_MS}, maximum ${MAX_COMMENT_WAIT_MS}. ` +
          `Set to 0 to return immediately without waiting.`,
      ),
  },
  blockedByDialog: false,
  // The handler only reads page state and waits for comment events, so it
  // runs outside the task runner and other tools run during the wait.
  concurrency: 'none',
  verifyFilesSchema: {},
  handler: async (request, response) => {
    const page = request.page;
    const devtoolsPage = await page.getDevToolsPage();
    if (!devtoolsPage) {
      response.appendResponseLine(
        'DevTools window is not open for this page. Call open_devtools first to open DevTools.',
      );
      return;
    }

    const bridge = await page.ensureDevToolsCommentBridge(devtoolsPage);
    if (!bridge) {
      response.appendResponseLine(DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE);
      return;
    }

    const timeout = request.params.timeout ?? DEFAULT_COMMENT_WAIT_MS;
    const start = Date.now();
    const deadline = start + timeout;
    let threads = await bridge.getComments(devtoolsPage);
    while (threads.length === 0) {
      const remaining = deadline - Date.now();
      if (remaining <= 0) {
        break;
      }
      const changed = await bridge.waitForCommentEvent(remaining);
      if (!changed) {
        break;
      }
      // Another tool may have changed state during the wait, so fetch again.
      threads = await bridge.getComments(devtoolsPage);
    }

    if (threads.length === 0 && timeout > 0) {
      response.appendResponseLine(
        `Waited ${Date.now() - start}ms for new DevTools comments. Call get_devtools_comments again to keep waiting.`,
      );
      return;
    }
    response.setDevToolsComments(threads);
  },
}));

export const resolveDevtoolsComment: PageToolFactory = definePageTool(() => ({
  name: 'resolve_devtools_comment',
  description:
    'Append an agent reply to a DevTools comment thread and mark it as resolved.',
  annotations: {
    category: ToolCategory.DEBUGGING,
    readOnlyHint: false,
    conditions: ['devtoolsComments'],
  },
  schema: {
    threadId: zod
      .string()
      .describe(
        'The unique identifier of the comment thread to resolve (e.g. "comment-1").',
      ),
    replyText: zod
      .string()
      .optional()
      .describe(
        'Optional reply explanation from the AI agent to append to the resolved comment thread.',
      ),
  },
  blockedByDialog: false,
  concurrency: 'exclusive',
  verifyFilesSchema: {},
  handler: async (request, response) => {
    const page = request.page;
    const devtoolsPage = await page.getDevToolsPage();
    if (!devtoolsPage) {
      response.appendResponseLine(
        'DevTools window is not open for this page. Call open_devtools first to open DevTools.',
      );
      return;
    }

    if (!(await page.ensureDevToolsCommentBridge(devtoolsPage))) {
      response.appendResponseLine(DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE);
      return;
    }

    const {threadId, replyText} = request.params;
    const success = await devtoolsPage.evaluate(
      (id: string, reply: string | undefined) => {
        return (
          window.universe?.cd4aBridge?.resolveCommentThread(id, reply) ?? false
        );
      },
      threadId,
      replyText,
    );

    if (success) {
      response.appendResponseLine(
        `Comment thread ${threadId} resolved successfully.`,
      );
      if (replyText) {
        response.appendResponseLine(`Agent reply added: "${replyText}"`);
      }
    } else {
      response.appendResponseLine(
        `Failed to resolve comment thread "${threadId}". Thread not found.`,
      );
    }
  },
}));

export const revealInDevtools: PageToolFactory = definePageTool(() => ({
  name: 'reveal_in_devtools',
  description:
    'Navigate DevTools to a specified panel and highlight a target DOM node or network request. The parameters uid and reqid are mutually exclusive.',
  annotations: {
    category: ToolCategory.DEBUGGING,
    readOnlyHint: true,
    conditions: ['devtoolsComments'],
  },
  schema: {
    panelName: zod
      .string()
      .optional()
      .describe(
        'The target DevTools panel (e.g. "elements", "network", "sources", "console").',
      ),
    uid: zod
      .string()
      .optional()
      .describe(
        'Optional snapshot element UID to reveal in the Elements panel.',
      ),
    reqid: zod
      .number()
      .optional()
      .describe('Optional network request ID to reveal in the Network panel.'),
  },
  blockedByDialog: false,
  concurrency: 'exclusive',
  verifyFilesSchema: {},
  handler: async (request, response) => {
    const page = request.page;
    const devtoolsPage = await page.getDevToolsPage();
    if (!devtoolsPage) {
      response.appendResponseLine(
        'DevTools window is not open for this page. Call open_devtools first to open DevTools.',
      );
      return;
    }

    if (!(await page.ensureDevToolsCommentBridge(devtoolsPage))) {
      response.appendResponseLine(DEVTOOLS_COMMENTS_UNAVAILABLE_MESSAGE);
      return;
    }

    const {panelName, uid, reqid} = request.params;
    let backendNodeId: number | undefined;
    let targetId: string | undefined;
    let networkRequestId: string | undefined;

    if (uid) {
      const resolved = await page.resolveUidToBackendNodeId(uid);
      if (resolved) {
        backendNodeId = resolved.backendNodeId;
        targetId = resolved.targetId;
      } else {
        response.appendResponseLine(
          `Warning: Could not resolve snapshot UID "${uid}" to a backend DOM node ID.`,
        );
      }
    }

    if (reqid !== undefined) {
      const resolvedCdpRequestId = page.resolveReqidToCdpRequestId(reqid);
      if (resolvedCdpRequestId !== undefined) {
        networkRequestId = resolvedCdpRequestId;
      } else {
        response.appendResponseLine(
          `Warning: Could not resolve network request ID ${reqid} to a CDP request ID.`,
        );
      }
    }

    const revealTarget: CD4ARevealTarget = {
      networkRequestId,
      ...(backendNodeId !== undefined
        ? {node: {backendNodeId, targetId: targetId ?? ''}}
        : {}),
    };

    await devtoolsPage.evaluate(
      async (panel: string, target: CD4ARevealTarget) => {
        await window.universe?.cd4aBridge?.reveal(panel, target);
      },
      panelName ?? '',
      revealTarget,
    );

    let targetDesc = '';
    if (uid && backendNodeId !== undefined) {
      targetDesc = ` (revealing element ${uid} [backend node ${backendNodeId}])`;
    } else if (reqid !== undefined && networkRequestId) {
      targetDesc = ` (revealing network request ${reqid} [${networkRequestId}])`;
    }

    if (panelName) {
      response.appendResponseLine(
        `Navigated to ${panelName} panel${targetDesc} in DevTools.`,
      );
    } else {
      response.appendResponseLine(`Revealed target${targetDesc} in DevTools.`);
    }
  },
}));