Skip to content

Chrome DevTools for coding agents

18.3 KB
Raw Blame
/**
 * @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);
    });
  }
}