feat: include stack trace in 'get_console_message' tool (#740)

This is the stack trace of the console message itself. If the argument
is an Error object or an "Error.stack" like string we don't do anything
special (yet).

The stack trace is source mapped if source maps are available.

The function matches the target ID of the console message to the
`SDK.Target` of DevTools. The only oddity is that DevTools works in a
lazy manor: It creates stack traces upfront and as source maps come in,
stack traces get updated. This does not work for the MCP server.
Instead, we wait for script parsed events and source maps to attach
before creating the stack trace. Since this could take potentially a
while, we guard it with a time out.

Author: szuend

src/DevtoolsUtils.ts

@@ -9,7 +9,9 @@ import {Mutex} from './Mutex.js';
 import {DevTools} from './third_party/index.js';
 import type {
   Browser,
+  ConsoleMessage,
   Page,
+  Protocol,
   Target as PuppeteerTarget,
 } from './third_party/index.js';
 
@@ -224,3 +226,94 @@ const SKIP_ALL_PAUSES = {
     // Do nothing.
   },
 };
+
+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 undefined;
+  }
+
+  const targetManager = devTools.universe.context.get(DevTools.TargetManager);
+  const messageTargetId = message._targetId();
+  const target = messageTargetId
+    ? targetManager.targetById(messageTargetId) || 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<Protocol.Runtime.ScriptId>();
+  for (const frame of rawStackTrace.callFrames) {
+    scriptIds.add(frame.scriptId);
+  }
+  for (
+    let asyncStack = rawStackTrace.parent;
+    asyncStack;
+    asyncStack = asyncStack.parent
+  ) {
+    for (const frame of asyncStack.callFrames) {
+      scriptIds.add(frame.scriptId);
+    }
+  }
+
+  const signal = AbortSignal.timeout(1_000);
+  await Promise.all(
+    [...scriptIds].map(id =>
+      waitForScript(model, id, signal)
+        .then(script =>
+          model.sourceMapManager().sourceMapForClientPromise(script),
+        )
+        .catch(),
+    ),
+  );
+
+  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 binding.createStackTraceFromProtocolRuntime(
+    rawStackTrace as Parameters<
+      DevTools.DebuggerWorkspaceBinding['createStackTraceFromProtocolRuntime']
+    >[0],
+    target,
+  );
+}
+
+// Waits indefinitely for the script so pair it with Promise.race.
+async function waitForScript(
+  model: DevTools.DebuggerModel,
+  scriptId: Protocol.Runtime.ScriptId,
+  signal: AbortSignal,
+) {
+  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);
+    });
+  }
+}

src/McpContext.ts

@@ -8,7 +8,12 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-import {extractUrlLikeFromDevToolsTitle, urlsEqual} from './DevtoolsUtils.js';
+import type {TargetUniverse} from './DevtoolsUtils.js';
+import {
+  extractUrlLikeFromDevToolsTitle,
+  UniverseManager,
+  urlsEqual,
+} from './DevtoolsUtils.js';
 import type {ListenerMap} from './PageCollector.js';
 import {NetworkCollector, ConsoleCollector} from './PageCollector.js';
 import {Locator} from './third_party/index.js';
@@ -104,6 +109,7 @@ export class McpContext implements Context {
   #textSnapshot: TextSnapshot | null = null;
   #networkCollector: NetworkCollector;
   #consoleCollector: ConsoleCollector;
+  #devtoolsUniverseManager: UniverseManager;
 
   #isRunningTrace = false;
   #networkConditionsMap = new WeakMap<Page, string>();
@@ -152,17 +158,20 @@ export class McpContext implements Context {
         },
       } as ListenerMap;
     });
+    this.#devtoolsUniverseManager = new UniverseManager(this.browser);
   }
 
   async #init() {
     const pages = await this.createPagesSnapshot();
     await this.#networkCollector.init(pages);
     await this.#consoleCollector.init(pages);
+    await this.#devtoolsUniverseManager.init(pages);
   }
 
   dispose() {
     this.#networkCollector.dispose();
     this.#consoleCollector.dispose();
+    this.#devtoolsUniverseManager.dispose();
   }
 
   static async from(
@@ -229,6 +238,10 @@ export class McpContext implements Context {
     return this.#consoleCollector.getData(page, includePreservedMessages);
   }
 
+  getDevToolsUniverse(): TargetUniverse | null {
+    return this.#devtoolsUniverseManager.get(this.getSelectedPage());
+  }
+
   getConsoleMessageStableId(
     message: ConsoleMessage | Error | DevTools.AggregatedIssue,
   ): number {

src/McpResponse.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import {createStackTraceForConsoleMessage} from './DevtoolsUtils.js';
 import type {ConsoleMessageData} from './formatters/consoleFormatter.js';
 import {
   formatConsoleEventShort,
@@ -242,6 +243,11 @@ export class McpResponse implements Response {
       const consoleMessageStableId = this.#attachedConsoleMessageId;
       if ('args' in message) {
         const consoleMessage = message as ConsoleMessage;
+        const devTools = context.getDevToolsUniverse();
+        const stackTrace = devTools
+          ? await createStackTraceForConsoleMessage(devTools, consoleMessage)
+          : undefined;
+
         consoleData = {
           consoleMessageStableId,
           type: consoleMessage.type(),
@@ -256,6 +262,7 @@ export class McpResponse implements Response {
                 : String(stringArg);
             }),
           ),
+          stackTrace,
         };
       } else if (message instanceof DevTools.AggregatedIssue) {
         const formatter = new IssueFormatter(message, {
@@ -308,6 +315,13 @@ export class McpResponse implements Response {
                 context.getConsoleMessageStableId(item);
               if ('args' in item) {
                 const consoleMessage = item as ConsoleMessage;
+                const devTools = context.getDevToolsUniverse();
+                const stackTrace = devTools
+                  ? await createStackTraceForConsoleMessage(
+                      devTools,
+                      consoleMessage,
+                    )
+                  : undefined;
                 return {
                   consoleMessageStableId,
                   type: consoleMessage.type(),
@@ -322,6 +336,7 @@ export class McpResponse implements Response {
                         : String(stringArg);
                     }),
                   ),
+                  stackTrace,
                 };
               }
               if (item instanceof DevTools.AggregatedIssue) {

src/third_party/index.ts

@@ -5,6 +5,7 @@
  */
 
 import 'core-js/modules/es.promise.with-resolvers.js';
+import 'core-js/modules/es.set.union.v2.js';
 import 'core-js/proposals/iterator-helpers.js';
 
 export type {Options as YargsOptions} from 'yargs';

tests/tools/console.test.js.snapshot

@@ -1,3 +1,16 @@
+exports[`console > get_console_message > applies source maps to stack traces of console messages 1`] = `
+# test response
+ID: 1
+Message: warn> hello world
+### Arguments
+Arg #0: hello world
+### Stack trace
+at bar (main.js:2:10)
+at foo (main.js:6:2)
+at Iife (main.js:10:2)
+at <anonymous> (main.js:9:0)
+`;
+
 exports[`console > get_console_message > issues type > gets issue details with node id parsing 1`] = `
 # test response
 ID: 1

tests/tools/console.test.ts

@@ -120,6 +120,8 @@ describe('console', () => {
   });
 
   describe('get_console_message', () => {
+    const server = serverHooks();
+
     it('gets a specific console message', async () => {
       await withMcpContext(async (response, context) => {
         const page = await context.newPage();
@@ -143,8 +145,6 @@ describe('console', () => {
     });
 
     describe('issues type', () => {
-      const server = serverHooks();
-
       it('gets issue details with node id parsing', async t => {
         await withMcpContext(async (response, context) => {
           const page = await context.newPage();
@@ -228,5 +228,34 @@ describe('console', () => {
         });
       });
     });
+
+    it('applies source maps to stack traces of console messages', async t => {
+      server.addRoute('/main.min.js', (_req, res) => {
+        res.setHeader('Content-Type', 'text/javascript');
+        res.statusCode = 200;
+        res.end(`function n(){console.warn("hello world")}function o(){n()}(function n(){o()})();
+          //# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJiYXIiLCJjb25zb2xlIiwid2FybiIsImZvbyIsIklpZmUiXSwic291cmNlcyI6WyIuL21haW4uanMiXSwic291cmNlc0NvbnRlbnQiOlsiXG5mdW5jdGlvbiBiYXIoKSB7XG4gIGNvbnNvbGUud2FybignaGVsbG8gd29ybGQnKTtcbn1cblxuZnVuY3Rpb24gZm9vKCkge1xuICBiYXIoKTtcbn1cblxuKGZ1bmN0aW9uIElpZmUoKSB7XG4gIGZvbygpO1xufSkoKTtcblxuIl0sIm1hcHBpbmdzIjoiQUFDQSxTQUFTQSxJQUNQQyxRQUFRQyxLQUFLLGNBQ2YsQ0FFQSxTQUFTQyxJQUNQSCxHQUNGLEVBRUEsU0FBVUksSUFDUkQsR0FDRCxFQUZEIiwiaWdub3JlTGlzdCI6W119
+          `);
+      });
+      server.addHtmlRoute(
+        '/index.html',
+        `<script src="${server.getRoute('/main.min.js')}"></script>`,
+      );
+
+      await withMcpContext(async (response, context) => {
+        const page = await context.newPage();
+        await page.goto(server.getRoute('/index.html'));
+
+        await getConsoleMessage.handler(
+          {params: {msgid: 1}},
+          response,
+          context,
+        );
+        const formattedResponse = await response.handle('test', context);
+        const rawText = getTextContent(formattedResponse.content[0]);
+
+        t.assert.snapshot?.(rawText);
+      });
+    });
   });
 });