Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import {FakeIssuesManager} from '../devtools/DevtoolsUtils.js';
import {
DevTools,
FrameEvent,
type CDPSession,
type ConsoleMessage,
type Protocol,
type Issue,
type Frame,
type Handler,
type HTTPRequest,
type Page,
type PageEvents as PuppeteerPageEvents,
} from '../third_party/index.js';
import {
createIdGenerator,
stableIdSymbol,
type WithSymbolId,
} from '../utils/id.js';
import {logger} from '../utils/logger.js';
import {DEFAULT_MAX_NAVIGATION_SAVED} from './constants.js';
export class UncaughtError {
readonly details: Protocol.Runtime.ExceptionDetails;
readonly targetId: string;
readonly session?: CDPSession;
constructor(
details: Protocol.Runtime.ExceptionDetails,
targetId: string,
session?: CDPSession,
) {
this.details = details;
this.targetId = targetId;
this.session = session;
}
}
interface PageEvents extends PuppeteerPageEvents {
devtoolsAggregatedIssue: DevTools.AggregatedIssue;
uncaughtError: UncaughtError;
}
export type ListenerMap<EventMap extends PageEvents = PageEvents> = {
[
K in keyof EventMap as string extends K
? never
: number extends K
? never
: symbol extends K
? never
: K
]?: (event: EventMap[K]) => void;
};
export interface PageCollectorOptions {
maxResourcesPerNavigation?: number;
maxNavigationSaved?: number;
}
export class PageCollector<T> {
protected pptrPage: Page;
#listeners?: ListenerMap<PageEvents>;
#pendingSameDocumentNavigation = false;
#frameNavigatedWithinDocumentTarget?: Frame;
protected readonly maxNavigationSaved: number;
/**
* This maps a Page to a list of navigations with a sub-list
* of all collected resources.
* The newer navigations come first.
*/
protected storage: Array<Array<WithSymbolId<T>>> = [[]];
constructor(
page: Page,
listeners: (collector: (item: T) => void) => ListenerMap<PageEvents>,
{
maxResourcesPerNavigation,
maxNavigationSaved = DEFAULT_MAX_NAVIGATION_SAVED,
}: PageCollectorOptions = {},
) {
this.pptrPage = page;
this.maxNavigationSaved = maxNavigationSaved;
this.#attachFrameNavigatedWithinDocumentListener();
const idGenerator = createIdGenerator();
const listenerMap = listeners(value => {
const withId = value as WithSymbolId<T>;
withId[stableIdSymbol] = idGenerator();
this.storage[0].push(withId);
if (
maxResourcesPerNavigation !== undefined &&
this.storage[0].length > maxResourcesPerNavigation
) {
this.storage[0].splice(
0,
this.storage[0].length - maxResourcesPerNavigation,
);
}
});
listenerMap['framenavigated'] = (frame: Frame) => {
// Only split the storage on main frame navigation
if (frame !== this.pptrPage.mainFrame()) {
return;
}
// Re-attach the listener to the current main frame: a cross-document
// navigation may have replaced the frame object, so the reference
// captured at construction time would be stale.
this.#attachFrameNavigatedWithinDocumentListener();
// Same-document (SPA) navigations also emit `framenavigated`, but they
// must not rotate the retained history. Puppeteer emits
// `FrameNavigatedWithinDocument` right before `FrameNavigated` for such
// navigations, so consume the flag here to skip the split.
if (this.#pendingSameDocumentNavigation) {
this.#pendingSameDocumentNavigation = false;
return;
}
this.splitAfterNavigation();
};
for (const [name, listener] of Object.entries(listenerMap)) {
this.pptrPage.on(name, listener as Handler<unknown>);
}
this.#listeners = listenerMap;
}
dispose(): void {
this.#detachFrameNavigatedWithinDocumentListener();
if (this.#listeners) {
for (const [name, listener] of Object.entries(this.#listeners)) {
this.pptrPage.off(name, listener as Handler<unknown>);
}
}
}
// Puppeteer emits this right before the page-level navigation event for
// same-document (SPA) navigations, which lets `framenavigated` skip the
// history rotation for those navigations.
#onFrameNavigatedWithinDocument = (): void => {
this.#pendingSameDocumentNavigation = true;
};
#attachFrameNavigatedWithinDocumentListener(): void {
this.#detachFrameNavigatedWithinDocumentListener();
this.#frameNavigatedWithinDocumentTarget = this.pptrPage.mainFrame();
this.#frameNavigatedWithinDocumentTarget.on(
FrameEvent.FrameNavigatedWithinDocument,
this.#onFrameNavigatedWithinDocument,
);
}
#detachFrameNavigatedWithinDocumentListener(): void {
if (this.#frameNavigatedWithinDocumentTarget) {
this.#frameNavigatedWithinDocumentTarget.off(
FrameEvent.FrameNavigatedWithinDocument,
this.#onFrameNavigatedWithinDocument,
);
this.#frameNavigatedWithinDocumentTarget = undefined;
}
}
protected splitAfterNavigation(): void {
// Add the latest navigation first
this.storage.unshift([]);
this.storage.splice(this.maxNavigationSaved);
}
getData(includePreservedData?: boolean): T[] {
if (!includePreservedData) {
return this.storage[0];
}
const data: T[] = [];
for (let index = this.maxNavigationSaved; index >= 0; index--) {
if (this.storage[index]) {
data.push(...this.storage[index]);
}
}
return data;
}
getIdForResource(resource: WithSymbolId<T>): number {
return resource[stableIdSymbol] ?? -1;
}
getById(stableId: number): T {
const item = this.find(item => item[stableIdSymbol] === stableId);
if (!item) {
throw new Error('Request not found for selected page');
}
return item;
}
find(
filter: (item: WithSymbolId<T>) => boolean,
): WithSymbolId<T> | undefined {
for (const navigation of this.storage) {
const item = navigation.find(filter);
if (item) {
return item;
}
}
return;
}
}
export class ConsoleCollector extends PageCollector<
ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError
> {
static readonly MAX_MESSAGES_PER_NAVIGATION = 10_000;
#subscriber?: PageEventSubscriber;
constructor(
page: Page,
listeners: (
collector: (
item: ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError,
) => void,
) => ListenerMap<PageEvents>,
{
maxResourcesPerNavigation = ConsoleCollector.MAX_MESSAGES_PER_NAVIGATION,
maxNavigationSaved,
}: PageCollectorOptions = {},
) {
super(page, listeners, {maxResourcesPerNavigation, maxNavigationSaved});
this.#subscriber = new PageEventSubscriber(this.pptrPage);
this.#subscriber.subscribe();
}
override dispose(): void {
super.dispose();
this.#subscriber?.unsubscribe();
}
}
class PageEventSubscriber {
#issueManager = new FakeIssuesManager();
#issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
#seenKeys = new Set<string>();
#seenIssues = new Set<DevTools.AggregatedIssue>();
#page: Page;
#session: CDPSession;
#targetId: string;
#pendingSameDocumentNavigation = false;
#frameNavigatedWithinDocumentTarget?: Frame;
constructor(page: Page) {
this.#page = page;
// @ts-expect-error use existing CDP client (internal Puppeteer API).
this.#session = this.#page._client() as CDPSession;
// @ts-expect-error use internal Puppeteer API to get target ID
this.#targetId = this.#session.target()._targetId;
}
#resetIssueAggregator(): void {
this.#issueManager = new FakeIssuesManager();
if (this.#issueAggregator) {
this.#issueAggregator.removeEventListener(
DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED,
this.#onAggregatedIssue,
);
}
this.#issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
this.#issueAggregator.addEventListener(
DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED,
this.#onAggregatedIssue,
);
}
subscribe(): void {
this.#resetIssueAggregator();
this.#page.on('framenavigated', this.#onFrameNavigated);
this.#page.on('issue', this.#onIssueAdded);
this.#session.on('Runtime.exceptionThrown', this.#onExceptionThrown);
this.#attachFrameNavigatedWithinDocumentListener();
}
unsubscribe(): void {
this.#seenKeys.clear();
this.#seenIssues.clear();
this.#detachFrameNavigatedWithinDocumentListener();
this.#page.off('framenavigated', this.#onFrameNavigated);
this.#page.off('issue', this.#onIssueAdded);
this.#session.off('Runtime.exceptionThrown', this.#onExceptionThrown);
if (this.#issueAggregator) {
this.#issueAggregator.removeEventListener(
DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED,
this.#onAggregatedIssue,
);
}
}
#onAggregatedIssue = (
event: DevTools.Common.EventTarget.EventTargetEvent<DevTools.AggregatedIssue>,
): void => {
if (this.#seenIssues.has(event.data)) {
return;
}
this.#seenIssues.add(event.data);
this.#page.emit('devtoolsAggregatedIssue', event.data);
};
#onExceptionThrown = (event: Protocol.Runtime.ExceptionThrownEvent): void => {
this.#page.emit(
'uncaughtError',
new UncaughtError(event.exceptionDetails, this.#targetId, this.#session),
);
};
// On navigation, we reset issue aggregation.
#onFrameNavigated = (frame: Frame): void => {
// Only split the storage on main frame navigation
if (frame !== frame.page().mainFrame()) {
return;
}
// Re-attach the listener to the current main frame: a cross-document
// navigation may have replaced the frame object, so the reference
// captured at construction time would be stale.
this.#attachFrameNavigatedWithinDocumentListener();
if (this.#pendingSameDocumentNavigation) {
this.#pendingSameDocumentNavigation = false;
return;
}
this.#seenKeys.clear();
this.#seenIssues.clear();
this.#resetIssueAggregator();
};
// Puppeteer emits this right before the page-level navigation event for
// same-document (SPA) navigations, which lets `framenavigated` skip the
// issue aggregation reset for those navigations.
#onFrameNavigatedWithinDocument = (): void => {
this.#pendingSameDocumentNavigation = true;
};
#attachFrameNavigatedWithinDocumentListener(): void {
this.#detachFrameNavigatedWithinDocumentListener();
this.#frameNavigatedWithinDocumentTarget = this.#page.mainFrame();
this.#frameNavigatedWithinDocumentTarget.on(
FrameEvent.FrameNavigatedWithinDocument,
this.#onFrameNavigatedWithinDocument,
);
}
#detachFrameNavigatedWithinDocumentListener(): void {
if (this.#frameNavigatedWithinDocumentTarget) {
this.#frameNavigatedWithinDocumentTarget.off(
FrameEvent.FrameNavigatedWithinDocument,
this.#onFrameNavigatedWithinDocument,
);
this.#frameNavigatedWithinDocumentTarget = undefined;
}
}
#onIssueAdded = (inspectorIssue: Issue): void => {
try {
// @ts-expect-error The types are missmatched but they
// are coming from CDP
if (!DevTools.isIssueCodeSupported(inspectorIssue.code)) {
return;
}
const issue = DevTools.createIssuesFromProtocolIssue(
null,
// @ts-expect-error Protocol types diverge.
inspectorIssue,
)[0];
if (!issue) {
logger?.('No issue mapping for for the issue: ', inspectorIssue.code);
return;
}
const primaryKey = issue.primaryKey();
if (this.#seenKeys.has(primaryKey)) {
return;
}
this.#seenKeys.add(primaryKey);
this.#issueManager.dispatchEventToListeners(
DevTools.IssuesManagerEvents.ISSUE_ADDED,
{
issue,
// @ts-expect-error We don't care that issues model is null
issuesModel: null,
},
);
} catch (error) {
logger?.('Error creating a new issue', error);
}
};
}
export class NetworkCollector extends PageCollector<HTTPRequest> {
static readonly MAX_REQUESTS_PER_NAVIGATION = 1_000;
/** The navigation request that started the latest navigation, if any. */
#navigationRequest?: HTTPRequest;
constructor(
page: Page,
{
maxResourcesPerNavigation = NetworkCollector.MAX_REQUESTS_PER_NAVIGATION,
maxNavigationSaved,
}: PageCollectorOptions = {},
listeners: (
collector: (item: HTTPRequest) => void,
) => ListenerMap<PageEvents> = collect => {
return {
request: req => {
// With the debugger `createTargetUniverse()` starts, initiator stacks
// carry up to 32 async parents, which no tool reads.
const stack = req.initiator()?.stack;
if (stack) {
delete stack.parent;
}
collect(req);
},
} as ListenerMap;
},
) {
super(page, listeners, {maxResourcesPerNavigation, maxNavigationSaved});
}
override splitAfterNavigation(): void {
const requests = this.storage[0];
// A navigation without a request, such as a back/forward cache restore or
// about:blank, must not claim the request of the previous navigation.
const lastRequestIdx = requests.findLastIndex(request => {
return (
request !== this.#navigationRequest &&
request.frame() === this.pptrPage.mainFrame() &&
request.isNavigationRequest()
);
});
// Keep all requests since the last navigation request including that
// navigation request itself.
// Keep the reference
if (lastRequestIdx !== -1) {
this.#navigationRequest = requests[lastRequestIdx];
const fromCurrentNavigation = requests.splice(lastRequestIdx);
this.storage.unshift(fromCurrentNavigation);
} else {
this.#navigationRequest = undefined;
this.storage.unshift([]);
}
this.storage.splice(this.maxNavigationSaved);
}
}