Chrome DevTools for coding agents
/**
* @license
* Copyright 2026 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import {Script} from 'node:vm';
import {
type TargetUniverse,
waitForSourceMaps,
} from './devtools/DevtoolsUtils.js';
import {DevTools} from './third_party/index.js';
export interface LogpointOptions {
/**
* The URL of a script as served to the browser, or the URL of an original
* source file from a source map. Matched exactly or as a path suffix.
*/
url: string;
/** 1-based line number in the coordinates of `url`. */
lineNumber: number;
/** Optional 1-based column number. */
columnNumber?: number;
/** Logged like the arguments of `console.log()`. */
expression: string;
}
/**
* A location in a script as served to the browser, 1-based like the
* locations reported by the tools.
*/
export interface GeneratedLocation {
url: string;
lineNumber: number;
columnNumber: number;
}
export interface Logpoint {
/**
* The full URL of the script or original source the logpoint was set in.
* DevTools normalizes locations, so this can be the original source file
* of a location that was given in a generated script.
*/
url: string;
lineNumber: number;
columnNumber?: number;
expression: string;
/**
* Whether `url` is an original source file from a source map rather than
* a script as served to the browser.
*/
sourceMapped: boolean;
/**
* The locations in the scripts served to the browser the logpoint is
* currently set at. Empty while no parsed script contains the location,
* for example right after a reload before the script was parsed again.
*/
generatedLocations: GeneratedLocation[];
}
/**
* Thrown by {@link LogpointManager.setLogpoints} when some locations could
* not be bound. The other logpoints were applied; `logpoints` holds the
* resulting state.
*/
export class LogpointError extends Error {
readonly logpoints: Logpoint[];
constructor(message: string, logpoints: Logpoint[]) {
super(message);
this.name = 'LogpointError';
this.logpoints = logpoints;
}
}
type Universe = DevTools.Foundation.Universe.Universe;
type Breakpoint = DevTools.BreakpointManager.Breakpoint;
type UserCondition = DevTools.BreakpointManager.UserCondition;
type UISourceCode = DevTools.Workspace.UISourceCode.UISourceCode;
interface ResolvedLogpoint {
options: LogpointOptions;
uiSourceCode: UISourceCode;
key: string;
}
export const LOGPOINT_FORMAT =
'<url>:<lineNumber>[:<columnNumber>] <expression>';
/**
* Parses a logpoint given as `<url>:<lineNumber>[:<columnNumber>] <expression>`.
* The url may itself contain colons (for example a port), so the location is
* the shortest prefix that ends in one or two numbers followed by whitespace.
*/
export function parseLogpoint(text: string): LogpointOptions {
const match = /^(\S+?):(\d+)(?::(\d+))?\s+(\S.*)$/s.exec(text.trim());
if (!match) {
throw new Error(
`Invalid logpoint "${text}". Expected the format ${LOGPOINT_FORMAT}, for example "src/app.ts:42 'total', cart.total".`,
);
}
const [, url, lineNumber, columnNumber, expression] = match;
const logpoint: LogpointOptions = {
url,
lineNumber: Number(lineNumber),
expression,
};
if (columnNumber !== undefined) {
logpoint.columnNumber = Number(columnNumber);
}
if (logpoint.lineNumber < 1 || logpoint.columnNumber === 0) {
throw new Error(
`Invalid logpoint "${text}": line and column numbers are 1-based.`,
);
}
return logpoint;
}
/**
* Checks that the expression parses as `console.log()` arguments. V8 is used
* for parsing both here and in the browser, so an expression that is rejected
* here would also be rejected as a breakpoint condition. The script is only
* compiled, never run.
*/
export function validateExpression(expression: string): void {
try {
new Script(`console.log(${expression})`);
} catch (error) {
throw new Error(
`The logpoint expression \`${expression}\` does not compile: ${error instanceof Error ? error.message : String(error)}. Provide the expression like arguments to console.log(...).`,
);
}
}
/**
* DevTools brands breakpoint conditions nominally; any string is a valid
* user condition.
*/
function toUserCondition(expression: string): UserCondition;
function toUserCondition(expression: string): string {
return expression;
}
function isFromSourceMap(uiSourceCode: UISourceCode): boolean {
return uiSourceCode.contentType().isFromSourceMap();
}
function locationKey(
url: string,
lineNumber: number,
columnNumber: number | undefined,
): string {
return `${url}:${lineNumber}${columnNumber === undefined ? '' : `:${columnNumber}`}`;
}
function baseName(url: string): string {
return url.slice(url.lastIndexOf('/') + 1).toLowerCase();
}
/**
* How long to wait for the source maps of the page to load before an original
* source URL is reported as unknown. Loads still pending then continue in the
* background, so a retry finds the source.
*/
const SOURCE_MAP_LOAD_TIMEOUT_MS = 5_000;
/**
* Manages logpoints for a single page on top of the `BreakpointManager` of
* the page's DevTools universe.
*
* A logpoint is a DevTools breakpoint with `isLogpoint` set: its condition
* logs the expression and never pauses. The breakpoint manager resolves the
* location through source maps, substitutes minified variable names in the
* expression and keeps the breakpoint bound across reloads and rebuilt
* bundles. This class only maps the tool API (URLs and 1-based positions)
* onto workspace source codes.
*/
export class LogpointManager {
readonly #universe: Universe;
readonly #target: DevTools.Target;
/**
* The breakpoints that are logpoints of this page. The breakpoint manager
* keeps one `Breakpoint` per normalized location, so two requested
* locations can share one entry.
*/
readonly #records = new Set<Breakpoint>();
constructor(devTools: TargetUniverse) {
this.#universe = devTools.universe;
this.#target = devTools.target;
}
get #debuggerModel(): DevTools.DebuggerModel {
const model = this.#target.model(DevTools.DebuggerModel);
if (!model) {
throw new Error('The DevTools debugger model is not available.');
}
return model;
}
/**
* Makes the given logpoints the complete set of logpoints on the page:
* logpoints not in the list are removed, new ones are added and the
* expression of an existing logpoint at the same location is replaced.
* Expressions and locations are validated before anything is changed.
* Throws a {@link LogpointError} when a location has no executable code;
* the other logpoints are applied regardless.
*/
async setLogpoints(desired: LogpointOptions[]): Promise<Logpoint[]> {
for (const options of desired) {
validateExpression(options.expression);
}
const resolved = new Map<string, ResolvedLogpoint>();
for (const options of desired) {
const uiSourceCode = await this.#findUISourceCode(options.url);
const key = locationKey(
uiSourceCode.url(),
options.lineNumber,
options.columnNumber,
);
// The last entry for a location wins, like setting it twice would.
resolved.set(key, {options, uiSourceCode, key});
}
const kept = new Set<Breakpoint>();
const unbound: string[] = [];
for (const {options, uiSourceCode, key} of resolved.values()) {
const breakpoint = await this.#universe.breakpointManager.setBreakpoint(
uiSourceCode,
// The tool API is 1-based like the DevTools UI; the model is 0-based.
options.lineNumber - 1,
options.columnNumber === undefined
? undefined
: options.columnNumber - 1,
toUserCondition(options.expression),
/* enabled */ true,
/* isLogpoint */ true,
DevTools.BreakpointManager.BreakpointOrigin.USER_ACTION,
);
if (!breakpoint) {
unbound.push(key);
continue;
}
// Wait for the breakpoint to be set in the backend so that the result
// reports whether the location resolved.
await breakpoint.updateBreakpoint();
if (!this.#records.has(breakpoint) && !breakpoint.bound()) {
await breakpoint.remove(/* keepInStorage */ false);
unbound.push(key);
continue;
}
this.#records.add(breakpoint);
kept.add(breakpoint);
}
for (const breakpoint of [...this.#records]) {
if (!kept.has(breakpoint)) {
this.#records.delete(breakpoint);
await breakpoint.remove(/* keepInStorage */ false);
}
}
this.#setLazySourceMapLoading(this.#records.size === 0);
const logpoints = this.#currentLogpoints();
if (unbound.length) {
throw new LogpointError(
`No executable code at ${unbound.join(', ')} (for example a comment, type annotation or empty line, or a line not mapped to the generated script). Pick lines containing executable code. The other logpoints were applied.`,
logpoints,
);
}
return logpoints;
}
/**
* Releases the records. The breakpoints are not removed from the backend:
* the universe is being disposed and its session detaches, which removes
* them along with the page.
*/
dispose(): void {
this.#records.clear();
}
#currentLogpoints(): Logpoint[] {
return [...this.#records].map(breakpoint => this.#snapshot(breakpoint));
}
/**
* Reads the current state of a breakpoint, so that the result reflects
* the normalized location and the re-binding done by the breakpoint
* manager after reloads. The breakpoint manager may have moved a
* generated location to its original source, so whether the logpoint is
* source-mapped follows from the breakpoint, not from the request.
*/
#snapshot(breakpoint: Breakpoint): Logpoint {
const sourceMapped = [...breakpoint.getUiSourceCodes()].some(
isFromSourceMap,
);
const modelBreakpoint = breakpoint.modelBreakpoint(this.#debuggerModel);
const generatedLocations: GeneratedLocation[] = [];
if (breakpoint.bound()) {
for (const position of modelBreakpoint?.currentState ?? []) {
generatedLocations.push({
url: position.url,
lineNumber: position.lineNumber + 1,
columnNumber: (position.columnNumber ?? 0) + 1,
});
}
}
const columnNumber = breakpoint.columnNumber();
return {
url: breakpoint.url(),
lineNumber: breakpoint.lineNumber() + 1,
columnNumber: columnNumber === undefined ? undefined : columnNumber + 1,
expression: breakpoint.condition(),
sourceMapped,
generatedLocations,
};
}
/**
* Source maps load lazily by default, so after a reload the original
* sources of a rebuilt bundle would not re-appear in the workspace and a
* logpoint on an original source file could not be re-bound to the new
* generated location. While logpoints exist, source maps are loaded
* eagerly instead, like DevTools does with the Sources panel open.
*/
#setLazySourceMapLoading(lazy: boolean): void {
this.#universe.settings
.resolve(DevTools.SourceMapManager.lazyLoadingSettingDescriptor)
.set(lazy);
}
/**
* Finds the workspace source code for a script or original source URL,
* loading source maps if needed. Throws a descriptive error, including
* sources with the same file name, when nothing matches.
*/
async #findUISourceCode(url: string): Promise<UISourceCode> {
// Source maps are loaded lazily in the DevTools universe and original
// sources only appear in the workspace once their source map has loaded.
let match = this.#matchUISourceCode(url);
let timedOut = false;
if (match && !isFromSourceMap(match)) {
// The script may be a transpiled file served at the URL of its original
// source (see #matchUISourceCode); its source map decides.
const matchedUrl = match.url();
const scripts = this.#debuggerModel
.scripts()
.filter(script => script.sourceURL === matchedUrl);
if (scripts.some(script => script.sourceMapURL)) {
const signal = AbortSignal.timeout(SOURCE_MAP_LOAD_TIMEOUT_MS);
await waitForSourceMaps(this.#debuggerModel, scripts, signal);
match = this.#matchUISourceCode(url);
if (signal.aborted && (!match || !isFromSourceMap(match))) {
// Setting the logpoint on the served script would use its line
// numbers instead of those of the original source.
throw new Error(
`The source map of ${matchedUrl} was still loading after ${SOURCE_MAP_LOAD_TIMEOUT_MS / 1000} seconds; retry.`,
);
}
}
} else if (!match) {
const signal = AbortSignal.timeout(SOURCE_MAP_LOAD_TIMEOUT_MS);
await waitForSourceMaps(
this.#debuggerModel,
this.#debuggerModel.scripts(),
signal,
);
timedOut = signal.aborted;
match = this.#matchUISourceCode(url);
}
if (match) {
return match;
}
const name = baseName(url);
const similar = [...this.#pageSourceCodes()]
.map(uiSourceCode => uiSourceCode.url())
.filter(candidate => baseName(candidate) === name)
.slice(0, 5);
throw new Error(
`No parsed script or original source file matches "${url}". The url must match the URL of a script as served to the browser or an original source file from a source map, exactly or as a path suffix.${timedOut ? ` Some source maps were still loading after ${SOURCE_MAP_LOAD_TIMEOUT_MS / 1000} seconds; retry if the file comes from a source map.` : ''}${similar.length ? ` Sources with the same file name: ${similar.join(', ')}.` : ''}`,
);
}
/** The scripts and source-map sources of the page in the workspace. */
*#pageSourceCodes(): Iterable<UISourceCode> {
for (const uiSourceCode of this.#universe.workspace.uiSourceCodes()) {
const projectType = uiSourceCode.project().type();
// Content scripts of extensions are left out: they are not part of the
// page under development and would make path-suffix matches ambiguous.
if (projectType === DevTools.Workspace.Workspace.projectTypes.Network) {
yield uiSourceCode;
}
}
}
/**
* Finds the workspace source code for a script or original source URL.
* An exact URL match wins; otherwise the URL is matched as a path suffix so
* that users can pass "src/app.ts" without knowing the bundler's URL
* scheme. An ambiguous suffix match is reported as an error.
*/
#matchUISourceCode(url: string): UISourceCode | null {
const candidates = new Map<string, UISourceCode>();
for (const uiSourceCode of this.#pageSourceCodes()) {
const candidateUrl = uiSourceCode.url();
if (candidateUrl !== url && !candidateUrl.endsWith('/' + url)) {
continue;
}
// Dev servers like Vite serve a transpiled file at the URL of its
// original source, with a source map pointing back at that same URL.
// The original source then has the line numbers of the file on disk,
// so it wins over the script served at the same URL.
const existing = candidates.get(candidateUrl);
if (!existing || isFromSourceMap(uiSourceCode)) {
candidates.set(candidateUrl, uiSourceCode);
}
}
const exact = candidates.get(url);
if (exact) {
return exact;
}
if (candidates.size > 1) {
throw new Error(
`"${url}" matches multiple sources: ${[...candidates.keys()].join(', ')}. Specify a longer path.`,
);
}
return candidates.values().next().value ?? null;
}
}