Chrome DevTools for coding agents
/**
* @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.`);
}
},
}));