Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import {
DevTools,
type CDPSession,
type ConsoleMessage,
type Protocol,
} from '../third_party/index.js';
import {McpHostBindingAdapter} from './McpHostBindingAdapter.js';
/**
* A mock implementation of an issues manager that only implements the methods
* that are actually used by the IssuesAggregator
*/
export class FakeIssuesManager extends DevTools.Common.ObjectWrapper
.ObjectWrapper<DevTools.IssuesManagerEventTypes> {
issues(): DevTools.Issue[] {
return [];
}
}
export function overrideDevToolsGlobals({
loadResource,
}: {
loadResource: (url: string) => Promise<string>;
}): void {
DevTools.Host.InspectorFrontendHost.installInspectorFrontendHost(
new McpHostBindingAdapter(loadResource),
);
// DevTools CDP errors can get noisy.
DevTools.ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
const noopAgentCommand = (): Promise<{getError: () => undefined}> => {
return Promise.resolve({
getError: () => undefined,
});
};
// Stub out Network emulation commands on the DevTools Agent prototype globally.
// This prevents the DevTools Frontend from ever resetting/clearing Puppeteer's
// active network blocking/throttling rules during target setup or session lifetime.
const networkAgentPrototype =
DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get(
'Network',
);
if (networkAgentPrototype) {
Object.defineProperty(
networkAgentPrototype,
'invoke_emulateNetworkConditionsByRule',
{
value: () => {
return Promise.resolve({
ruleIds: [],
getError: () => undefined,
});
},
writable: true,
configurable: true,
enumerable: true,
},
);
Object.defineProperty(
networkAgentPrototype,
'invoke_overrideNetworkState',
{
value: noopAgentCommand,
writable: true,
configurable: true,
enumerable: true,
},
);
Object.defineProperty(networkAgentPrototype, 'invoke_enable', {
value: noopAgentCommand,
writable: true,
configurable: true,
enumerable: true,
});
Object.defineProperty(networkAgentPrototype, 'invoke_disable', {
value: noopAgentCommand,
writable: true,
configurable: true,
enumerable: true,
});
Object.defineProperty(networkAgentPrototype, 'invoke_setBlockedURLs', {
value: noopAgentCommand,
writable: true,
configurable: true,
enumerable: true,
});
}
// Puppeteer already collects issues from its own Audits subscription. Avoid
// enabling the DevTools Frontend's redundant subscription, which can replay
// a large retained issue backlog and delay unrelated page work.
const auditsAgentPrototype =
DevTools.ProtocolClient.InspectorBackend.inspectorBackend.agentPrototypes.get(
'Audits',
);
if (auditsAgentPrototype) {
Object.defineProperty(auditsAgentPrototype, 'invoke_enable', {
value: noopAgentCommand,
writable: true,
configurable: true,
enumerable: true,
});
}
DevTools.I18n.DevToolsLocale.DevToolsLocale.instance({
create: true,
data: {
navigatorLanguage: 'en-US',
settingLanguage: 'en-US',
lookupClosestDevToolsLocale: l => l,
},
});
DevTools.I18n.i18n.registerLocaleDataForTest('en-US', {});
DevTools.Formatter.FormatterWorkerPool.FormatterWorkerPool.instance({
forceNew: true,
entrypointURL: import.meta
.resolve('../third_party/devtools-formatter-worker.js'),
});
}
export interface TargetUniverse {
/** The DevTools target corresponding to the puppeteer Page */
target: DevTools.Target;
universe: DevTools.Foundation.Universe.Universe;
/** The secondary session created for this page */
session: CDPSession;
}
export interface CreateTargetUniverseOptions {
sourceMaps?: boolean;
}
export async function createTargetUniverse(
session: CDPSession,
options?: CreateTargetUniverseOptions,
): Promise<TargetUniverse> {
const settingStorage = new DevTools.Common.Settings.SettingsStorage({});
const universe = new DevTools.Foundation.Universe.Universe({
settingsCreationOptions: {
syncedStorage: settingStorage,
globalStorage: settingStorage,
localStorage: settingStorage,
settingRegistrations:
DevTools.Common.SettingRegistration.getRegisteredSettings(),
},
overrideAutoStartModels: new Set([DevTools.DebuggerModel]),
hostConfig: {},
inspectorFrontendHost:
DevTools.Host.InspectorFrontendHost.InspectorFrontendHostInstance,
supportsEmulation: false,
});
const sourceMaps = options?.sourceMaps ?? true;
const jsSourceMapsSetting = universe.settings.resolve(
DevTools.SDKSettings.jsSourceMapsEnabledSettingDescriptor,
);
jsSourceMapsSetting.set(sourceMaps);
const cssSourceMapsSetting = universe.settings.resolve(
DevTools.SDKSettings.cssSourceMapsEnabledSettingDescriptor,
);
cssSourceMapsSetting.set(sourceMaps);
const setting = universe.settings.resolve(
DevTools.SourceMapManager.lazyLoadingSettingDescriptor,
);
setting.set(true);
const skipAllPausesSetting = universe.settings.resolve(
DevTools.skipAllPausesSettingDescriptor,
);
skipAllPausesSetting.set(true);
// @ts-expect-error devtools-frontend has diffrent types.
const connection = new DevTools.PuppeteerDevToolsConnection(session);
const targetManager = universe.context.get(DevTools.TargetManager);
targetManager.observeModels(
DevTools.NetworkManager.NetworkManager,
DISABLE_NETWORK,
);
const target = targetManager.createTarget(
'main',
'',
'frame' as any, // eslint-disable-line @typescript-eslint/no-explicit-any
/* parentTarget */ null,
session.id(),
undefined,
connection,
);
return {target, universe, session};
}
// Not recording network requests in the DevTools universe.
//
// The network requests are collected through pptr and there isn't a use case for
// enabling devtools SDK's network domain.
const DISABLE_NETWORK = {
modelAdded(model: DevTools.NetworkManager.NetworkManager): void {
void model.target().networkAgent().invoke_disable();
},
modelRemoved(): void {
// Do nothing.
},
};
export type RemoteObjectLike =
Protocol.Runtime.RemoteObject | DevTools.Protocol.Runtime.RemoteObject;
export type ExceptionDetailsLike =
| Protocol.Runtime.ExceptionDetails
| DevTools.Protocol.Runtime.ExceptionDetails;
export type StackTraceLike =
Protocol.Runtime.StackTrace | DevTools.Protocol.Runtime.StackTrace;
/**
* Maximum number of `cause` links resolved for one error. A page can create a
* cyclic chain (`error.cause = error`), and CDP returns a new object id on
* every lookup of the same object, so a cycle cannot be detected by id.
*/
const MAX_CAUSE_DEPTH = 10;
/**
* Constructed from Runtime.ExceptionDetails of an uncaught error.
*
* TODO: Also construct from a RemoteObject of subtype 'error'.
*
* Consists of the message, a fully resolved stack trace and a fully resolved 'cause' chain.
*/
export class SymbolizedError {
readonly message: string;
readonly stackTrace?: DevTools.StackTrace.StackTrace.StackTrace;
readonly cause?: SymbolizedError;
private constructor(
message: string,
stackTrace?: DevTools.StackTrace.StackTrace.StackTrace,
cause?: SymbolizedError,
) {
this.message = message;
this.stackTrace = stackTrace;
this.cause = cause;
}
static async fromDetails(opts: {
details: ExceptionDetailsLike;
targetId: string;
devTools?: TargetUniverse;
// The session that reported `details`. Remote object ids are scoped to
// the session that issued them, so the cause has to be resolved there.
session?: CDPSession;
includeStackAndCause?: boolean;
resolvedStackTraceForTesting?: DevTools.StackTrace.StackTrace.StackTrace;
resolvedCauseForTesting?: SymbolizedError;
}): Promise<SymbolizedError> {
return await SymbolizedError.#fromDetails(opts, 0);
}
static async #fromDetails(
opts: Parameters<typeof SymbolizedError.fromDetails>[0],
causeDepth: number,
): Promise<SymbolizedError> {
const message = SymbolizedError.#getMessage(opts.details);
if (!opts.includeStackAndCause || (!opts.devTools && !opts.session)) {
return new SymbolizedError(
message,
opts.resolvedStackTraceForTesting,
opts.resolvedCauseForTesting,
);
}
let stackTrace: DevTools.StackTrace.StackTrace.StackTrace | undefined;
if (opts.resolvedStackTraceForTesting) {
stackTrace = opts.resolvedStackTraceForTesting;
} else if (opts.devTools && opts.details.stackTrace) {
try {
stackTrace = await createStackTrace(
opts.devTools,
opts.details.stackTrace,
opts.targetId,
);
} catch {
// ignore
}
}
// TODO: Turn opts.details.exception into a JSHandle and retrieve the 'cause' property.
// If its an Error, recursively create a SymbolizedError.
let cause: SymbolizedError | undefined;
if (opts.resolvedCauseForTesting) {
cause = opts.resolvedCauseForTesting;
} else if (opts.details.exception && causeDepth < MAX_CAUSE_DEPTH) {
try {
const causeRemoteObj = await SymbolizedError.#lookupCause(
opts.devTools,
opts.details.exception,
opts.targetId,
opts.session,
);
if (causeRemoteObj) {
cause = await SymbolizedError.#fromError(
{
devTools: opts.devTools,
error: causeRemoteObj,
targetId: opts.targetId,
session: opts.session,
},
causeDepth + 1,
);
}
} catch {
// Ignore
}
}
return new SymbolizedError(message, stackTrace, cause);
}
static async fromError(opts: {
error: RemoteObjectLike;
targetId: string;
devTools?: TargetUniverse;
session?: CDPSession;
}): Promise<SymbolizedError> {
return await SymbolizedError.#fromError(opts, 0);
}
static async #fromError(
opts: Parameters<typeof SymbolizedError.fromError>[0],
causeDepth: number,
): Promise<SymbolizedError> {
const details = await SymbolizedError.#getExceptionDetails(
opts.devTools,
opts.error,
opts.targetId,
opts.session,
);
if (details) {
return await SymbolizedError.#fromDetails(
{
details,
devTools: opts.devTools,
targetId: opts.targetId,
session: opts.session,
includeStackAndCause: true,
},
causeDepth,
);
}
return new SymbolizedError(
SymbolizedError.#getMessageFromException(opts.error),
);
}
static #getMessage(details: ExceptionDetailsLike): string {
// For Runtime.exceptionThrown with a present exception object, `details.text` will be "Uncaught" and
// we have to manually parse out the error text from the exception description.
// In the case of Runtime.getExceptionDetails, `details.text` has the Error.message.
// Unhandled promise rejections work the same way, with
// "Uncaught (in promise)" as `details.text` and the rejection reason as
// the exception.
if (
(details.text === 'Uncaught' ||
details.text === 'Uncaught (in promise)') &&
details.exception
) {
return (
details.text +
' ' +
SymbolizedError.#getMessageFromException(details.exception)
);
}
return details.text;
}
static #getMessageFromException(error: RemoteObjectLike): string {
if (error.description === undefined) {
// Primitive values, e.g. `Promise.reject('reason')`, have no description.
if (error.unserializableValue !== undefined) {
return error.unserializableValue;
}
return error.value === undefined ? '' : String(error.value);
}
const messageWithRest = error.description.split('\n at ', 2);
return messageWithRest[0] ?? '';
}
static async #getExceptionDetails(
devTools: TargetUniverse | undefined,
error: RemoteObjectLike,
targetId: string,
session?: CDPSession,
): Promise<ExceptionDetailsLike | null> {
if (error.type !== 'object' && error.subtype !== 'error') {
return null;
}
if (session) {
if (!error.objectId) {
return null;
}
const {exceptionDetails} = await session.send(
'Runtime.getExceptionDetails',
{errorObjectId: error.objectId},
);
return exceptionDetails ?? null;
}
if (!devTools) {
return null;
}
const targetManager = devTools.universe.context.get(DevTools.TargetManager);
const target = targetId
? targetManager.targetById(targetId) || devTools.target
: devTools.target;
const model = target.model(DevTools.RuntimeModel) as DevTools.RuntimeModel;
return (
(await model.getExceptionDetails(
error.objectId as DevTools.Protocol.Runtime.RemoteObjectId,
)) ?? null
);
}
static async #lookupCause(
devTools: TargetUniverse | undefined,
error: RemoteObjectLike,
targetId: string,
session?: CDPSession,
): Promise<RemoteObjectLike | null> {
if (error.type !== 'object' && error.subtype !== 'error') {
return null;
}
if (session) {
if (!error.objectId) {
return null;
}
const {result} = await session.send('Runtime.getProperties', {
objectId: error.objectId,
});
return result.find(prop => prop.name === 'cause')?.value ?? null;
}
if (!devTools) {
return null;
}
const targetManager = devTools.universe.context.get(DevTools.TargetManager);
const target = targetId
? targetManager.targetById(targetId) || devTools.target
: devTools.target;
const properties = await target.runtimeAgent().invoke_getProperties({
objectId: error.objectId as DevTools.Protocol.Runtime.RemoteObjectId,
});
if (properties.getError()) {
return null;
}
return properties.result.find(prop => prop.name === 'cause')?.value ?? null;
}
static createForTesting(
message: string,
stackTrace?: DevTools.StackTrace.StackTrace.StackTrace,
cause?: SymbolizedError,
): SymbolizedError {
return new SymbolizedError(message, stackTrace, cause);
}
}
export async function createStackTraceForConsoleMessage(
devTools: TargetUniverse,
consoleMessage: ConsoleMessage,
): Promise<DevTools.StackTrace.StackTrace.StackTrace | undefined> {
const message = consoleMessage as ConsoleMessage & {
_rawStackTrace(): Protocol.Runtime.StackTrace | undefined;
_targetId(): string | undefined;
};
const rawStackTrace = message._rawStackTrace();
if (rawStackTrace) {
return await createStackTrace(devTools, rawStackTrace, message._targetId());
}
return undefined;
}
export async function createStackTrace(
devTools: TargetUniverse,
rawStackTrace: StackTraceLike,
targetId: string | undefined,
): Promise<DevTools.StackTrace.StackTrace.StackTrace> {
const targetManager = devTools.universe.context.get(DevTools.TargetManager);
const target = targetId
? targetManager.targetById(targetId) || devTools.target
: devTools.target;
const model = target.model(DevTools.DebuggerModel) as DevTools.DebuggerModel;
// DevTools doesn't wait for source maps to attach before building a stack trace, rather it'll send
// an update event once a source map was attached and the stack trace retranslated. This doesn't
// work in the MCP case, so we'll collect all script IDs upfront and wait for any pending source map
// loads before creating the stack trace. We might also have to wait for Debugger.ScriptParsed events if
// the stack trace is created particularly early.
const scriptIds = new Set<string>();
for (const frame of rawStackTrace.callFrames) {
scriptIds.add(frame.scriptId);
}
for (
let asyncStack: StackTraceLike | undefined = rawStackTrace.parent;
asyncStack;
asyncStack = asyncStack.parent
) {
for (const frame of asyncStack.callFrames) {
scriptIds.add(frame.scriptId);
}
}
const signal = AbortSignal.timeout(1_000);
const scripts = await Promise.all(
[...scriptIds].map(id => waitForScript(model, id, signal)),
);
await waitForSourceMaps(model, scripts, signal);
const binding = devTools.universe.context.get(
DevTools.DebuggerWorkspaceBinding,
);
// DevTools uses branded types for ScriptId and others. Casting the puppeteer protocol type to the DevTools protocol type is safe.
return await binding.createStackTraceFromProtocolRuntime(
rawStackTrace as Parameters<
DevTools.DebuggerWorkspaceBinding['createStackTraceFromProtocolRuntime']
>[0],
target,
);
}
/**
* Waits for the source maps of `scripts` to load, so that their original
* sources are in the workspace. Scripts without a source map are skipped.
* Non-trivial pages have hundreds of source maps, so the wait ends when
* `signal` aborts; loads still pending then continue in the background and
* resolve later.
*/
export async function waitForSourceMaps(
model: DevTools.DebuggerModel,
scripts: Iterable<DevToolsScript>,
signal: AbortSignal,
): Promise<void> {
const manager = model.sourceMapManager();
const aborted = new Promise<void>(resolve => {
if (signal.aborted) {
resolve();
return;
}
signal.addEventListener('abort', () => resolve(), {once: true});
});
await Promise.all(
[...scripts].map(script => {
if (!script.sourceMapURL) {
return undefined;
}
return Promise.race([
manager.sourceMapForClientPromise(script).then(() => undefined),
aborted,
]);
}),
);
}
type DevToolsScript = NonNullable<
ReturnType<DevTools.DebuggerModel['scriptForId']>
>;
// Waits indefinitely for the script so pair it with Promise.race.
async function waitForScript(
model: DevTools.DebuggerModel,
scriptId: string,
signal: AbortSignal,
): Promise<DevToolsScript> {
while (true) {
if (signal.aborted) {
throw signal.reason;
}
const script = model.scriptForId(scriptId);
if (script) {
return script;
}
await new Promise((resolve, reject) => {
signal.addEventListener('abort', () => reject(signal.reason), {
once: true,
});
void model
.once(
'ParsedScriptSource' as Parameters<DevTools.DebuggerModel['once']>[0],
)
.then(resolve);
});
}
}