Chrome DevTools for coding agents
chore: refactor the profiler into scenarios. (#2488)
yulunz884c8dee7cda
diff --git a/scripts/profile/inspector.ts b/scripts/profile/inspector.tsnew file mode 100644index 00000000..9dcd7e98--- /dev/null+++ b/scripts/profile/inspector.ts@@ -0,0 +1,163 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import fs from 'node:fs';++import type {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';++import {isObject} from './utils.ts';++export interface HeapUsage {+ usedSize: number;+ totalSize: number;+}++export interface Measurement extends HeapUsage {+ label: string;+ timestamp: string;+}++interface PendingRequest {+ reject(error: Error): void;+ resolve(result: unknown): void;+}++export class InspectorClient {+ readonly #pending = new Map<number, PendingRequest>();+ #nextId = 1;+ #snapshotStream: fs.WriteStream | undefined;+ readonly #webSocket: WebSocket;++ private constructor(webSocket: WebSocket) {+ this.#webSocket = webSocket;+ webSocket.addEventListener('message', event => {+ this.#handleMessage(event.data);+ });+ }++ static connect(url: string): Promise<InspectorClient> {+ return new Promise((resolve, reject) => {+ const webSocket = new WebSocket(url);+ webSocket.addEventListener('open', () => {+ resolve(new InspectorClient(webSocket));+ });+ webSocket.addEventListener('error', () => {+ reject(new Error(`Failed to connect to Node inspector at ${url}`));+ });+ });+ }++ #handleMessage(data: unknown): void {+ if (typeof data !== 'string') {+ return;+ }+ const message: unknown = JSON.parse(data);+ if (!isObject(message)) {+ return;+ }++ if (message.method === 'HeapProfiler.addHeapSnapshotChunk') {+ const params = message.params;+ if (+ this.#snapshotStream &&+ isObject(params) &&+ typeof params.chunk === 'string'+ ) {+ this.#snapshotStream.write(params.chunk);+ }+ return;+ }++ if (typeof message.id !== 'number') {+ return;+ }+ const pending = this.#pending.get(message.id);+ if (!pending) {+ return;+ }+ this.#pending.delete(message.id);+ if (isObject(message.error)) {+ const errorMessage =+ typeof message.error.message === 'string'+ ? message.error.message+ : 'Unknown inspector error';+ pending.reject(new Error(errorMessage));+ return;+ }+ pending.resolve(message.result);+ }++ send(method: string, params?: Record<string, unknown>): Promise<unknown> {+ const id = this.#nextId++;+ return new Promise((resolve, reject) => {+ this.#pending.set(id, {resolve, reject});+ this.#webSocket.send(JSON.stringify({id, method, params}));+ });+ }++ async getHeapUsage(): Promise<HeapUsage> {+ await this.send('HeapProfiler.collectGarbage');+ const result = await this.send('Runtime.getHeapUsage');+ if (+ !isObject(result) ||+ typeof result.usedSize !== 'number' ||+ typeof result.totalSize !== 'number'+ ) {+ throw new Error('Node inspector returned invalid heap usage data');+ }+ return {usedSize: result.usedSize, totalSize: result.totalSize};+ }++ async takeHeapSnapshot(filePath: string): Promise<void> {+ const stream = fs.createWriteStream(filePath, {encoding: 'utf8'});+ this.#snapshotStream = stream;+ try {+ await this.send('HeapProfiler.takeHeapSnapshot', {reportProgress: false});+ } finally {+ this.#snapshotStream = undefined;+ await new Promise<void>((resolve, reject) => {+ stream.end(resolve);+ stream.on('error', reject);+ });+ }+ }++ close(): void {+ this.#webSocket.close();+ }+}++export function inspectorUrlFrom(+ transport: StdioClientTransport,+): Promise<string> {+ const stderr = transport.stderr;+ if (!stderr) {+ throw new Error('MCP server stderr is unavailable');+ }+ return new Promise((resolve, reject) => {+ let buffered = '';+ const timeout = setTimeout(() => {+ reject(+ new Error(+ `Timed out waiting for the Node inspector URL. Server stderr: ${buffered}`,+ ),+ );+ }, 10_000);+ stderr.setEncoding('utf8');+ stderr.on('data', chunk => {+ if (typeof chunk !== 'string') {+ return;+ }+ buffered += chunk;+ const match = /Debugger listening on (ws:\/\/\S+)/.exec(buffered);+ const url = match?.[1];+ if (url) {+ clearTimeout(timeout);+ resolve(url);+ }+ });+ });+}diff --git a/scripts/profile/profile_mcp.ts b/scripts/profile/profile_mcp.tsnew file mode 100644index 00000000..132340d7--- /dev/null+++ b/scripts/profile/profile_mcp.ts@@ -0,0 +1,321 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import fs from 'node:fs';+import path from 'node:path';+import {pathToFileURL} from 'node:url';+import {parseArgs} from 'node:util';++import {Client} from '@modelcontextprotocol/sdk/client/index.js';+import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';++import {+ InspectorClient,+ inspectorUrlFrom,+ type Measurement,+} from './inspector.ts';+import {startSourceMapTestServer} from './source_map_server.ts';+import type {ProfileScenario, ScenarioArgs} from './types.ts';+import {formatBytes, isScenarioModule, parsePositiveInteger} from './utils.ts';++interface ProfileOptions {+ iterations: number;+ warmupIterations: number;+}++interface ScenarioEntry {+ name: string;+ scenario: ProfileScenario;+}++async function loadScenario(filePath: string): Promise<ProfileScenario> {+ const fileUrl = pathToFileURL(filePath).href;+ const importedModule: unknown = await import(fileUrl);+ if (!isScenarioModule(importedModule)) {+ throw new Error(+ `Scenario file ${filePath} does not export a 'get' function.`,+ );+ }+ return importedModule;+}++async function discoverScenarios(+ scenariosDir: string,+ scenarioFilter?: string,+): Promise<ScenarioEntry[]> {+ const entries = fs.readdirSync(scenariosDir);+ const scenarioFiles: string[] = [];++ for (const entry of entries) {+ if (entry.endsWith('.ts') || entry.endsWith('.js')) {+ scenarioFiles.push(entry);+ }+ }++ if (scenarioFilter !== undefined && scenarioFilter.length > 0) {+ const normalizedFilter =+ scenarioFilter.endsWith('.ts') || scenarioFilter.endsWith('.js')+ ? scenarioFilter+ : `${scenarioFilter}.ts`;+ const targetFile = scenarioFiles.find(+ file => file === scenarioFilter || file === normalizedFilter,+ );+ if (!targetFile) {+ throw new Error(+ `Scenario "${scenarioFilter}" not found in ${scenariosDir}. Available scenarios: ${scenarioFiles.map(f => path.basename(f, path.extname(f))).join(', ')}`,+ );+ }+ const scenario = await loadScenario(path.join(scenariosDir, targetFile));+ return [+ {name: path.basename(targetFile, path.extname(targetFile)), scenario},+ ];+ }++ const results: ScenarioEntry[] = [];+ for (const file of scenarioFiles) {+ const scenario = await loadScenario(path.join(scenariosDir, file));+ results.push({name: path.basename(file, path.extname(file)), scenario});+ }+ return results;+}++interface ScenarioResult {+ name: string;+ summary: string;+ isGrowth: boolean;+}++async function profileScenario(+ scenarioEntry: ScenarioEntry,+ scenarioArgs: ScenarioArgs,+ options: ProfileOptions,+ rootDir: string,+): Promise<ScenarioResult> {+ const {name: scenarioName, scenario} = scenarioEntry;+ const {outputDir} = scenarioArgs;+ fs.mkdirSync(outputDir, {recursive: true});++ const env: Record<string, string> = {};+ for (const [key, value] of Object.entries(process.env)) {+ if (value !== undefined) {+ env[key] = value;+ }+ }+ env.CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS = 'true';++ const transport = new StdioClientTransport({+ command: process.execPath,+ args: [+ '--inspect=127.0.0.1:0',+ path.join(rootDir, 'build/src/bin/chrome-devtools-mcp.js'),+ '--headless',+ '--isolated',+ ],+ env,+ stderr: 'pipe',+ });+ const inspectorUrlPromise = inspectorUrlFrom(transport);+ const client = new Client(+ {name: 'mcp-heap-profiler', version: '1.0.0'},+ {capabilities: {}},+ );+ let inspector: InspectorClient | undefined;+ const measurements: Measurement[] = [];++ const toolCalls = await scenario.get(scenarioArgs);++ const runIteration = async (): Promise<void> => {+ const results: unknown[] = [];+ for (const call of toolCalls) {+ let args: Record<string, unknown> | undefined;+ if (typeof call.arguments === 'function') {+ const resolved = await call.arguments({results});+ args = resolved;+ } else {+ args = call.arguments;+ }+ const result = await client.callTool({+ name: call.name,+ arguments: args,+ });+ results.push(result);+ }+ };++ const record = async (+ label: string,+ takeSnapshot: boolean,+ ): Promise<void> => {+ if (!inspector) {+ throw new Error('Inspector is not connected');+ }+ const usage = await inspector.getHeapUsage();+ const measurement: Measurement = {+ label,+ timestamp: new Date().toISOString(),+ ...usage,+ };+ measurements.push(measurement);+ console.log(+ `[${scenarioName}] ${label}: used ${formatBytes(usage.usedSize)}, total ${formatBytes(usage.totalSize)}`,+ );+ if (!takeSnapshot) {+ return;+ }+ const snapshotPath = path.join(outputDir, `${label}.heapsnapshot`);+ await inspector.takeHeapSnapshot(snapshotPath);+ console.log(` snapshot: ${snapshotPath}`);+ };++ try {+ await client.connect(transport);+ inspector = await InspectorClient.connect(await inspectorUrlPromise);+ console.log(`\n=== Scenario: ${scenarioName} ===`);+ console.log(`MCP server PID: ${transport.pid}`);+ console.log(`Target URL: ${scenarioArgs.targetUrl}`);+ console.log(`Output directory: ${outputDir}`);++ await record('connected', false);+ for (+ let iteration = 1;+ iteration <= options.warmupIterations;+ iteration+++ ) {+ console.log(+ `[${scenarioName}] Warm-up ${iteration}/${options.warmupIterations}`,+ );+ await runIteration();+ }++ // Taking a heap snapshot exercises Node inspector and serialization paths.+ // Prime those paths before capturing the baseline so their JIT-compiled code+ // is not mistaken for workload growth in the final comparison.+ await record('snapshot-primer', true);+ await record('baseline', true);++ for (let iteration = 1; iteration <= options.iterations; iteration++) {+ console.log(+ `[${scenarioName}] Measured iteration ${iteration}/${options.iterations}`,+ );+ await runIteration();+ await record(`iteration-${iteration}`, false);+ }+ await record('final', true);++ let summary = `[${scenarioName}] Unable to compute heap comparison.`;+ let isGrowth = false;+ const baseline = measurements.find(+ measurement => measurement.label === 'baseline',+ );+ const final = measurements.find(+ measurement => measurement.label === 'final',+ );+ if (baseline && final) {+ const growth = final.usedSize - baseline.usedSize;+ if (growth > 0) {+ isGrowth = true;+ const percentage = (growth / baseline.usedSize) * 100;+ summary = `[${scenarioName}] The MCP heap grew by ${formatBytes(growth)} (${percentage.toFixed(2)}%) across ${options.iterations} measured iterations. Compare baseline.heapsnapshot with final.heapsnapshot to determine whether retained workload objects accumulated.`;+ console.warn(summary);+ } else {+ summary = `[${scenarioName}] The MCP heap did not grow across the measured iterations (${formatBytes(growth)}).`;+ console.log(summary);+ }+ }++ const reportPath = path.join(outputDir, 'heap-usage.json');+ fs.writeFileSync(+ reportPath,+ `${JSON.stringify({scenario: scenarioName, pid: transport.pid, url: scenarioArgs.targetUrl, options, measurements}, null, 2)}\n`,+ );+ console.log(`Report: ${reportPath}`);++ return {name: scenarioName, summary, isGrowth};+ } finally {+ inspector?.close();+ await client.close();+ }+}++async function main(): Promise<void> {+ const {values} = parseArgs({+ options: {+ 'output-dir': {type: 'string'},+ iterations: {type: 'string', default: '10'},+ 'warmup-iterations': {type: 'string', default: '10'},+ scenario: {type: 'string'},+ url: {type: 'string'},+ },+ });++ const options: ProfileOptions = {+ iterations: parsePositiveInteger(values.iterations, '--iterations'),+ warmupIterations: parsePositiveInteger(+ values['warmup-iterations'],+ '--warmup-iterations',+ ),+ };++ const rootDir = path.resolve(import.meta.dirname, '../..');+ const scenariosDir = path.join(import.meta.dirname, 'scenarios');+ const scenarios = await discoverScenarios(scenariosDir, values.scenario);++ const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-');+ const baseOutputDir = path.resolve(+ values['output-dir'] ?? path.join(rootDir, 'mcp-heap-profiles', timestamp),+ );+ fs.mkdirSync(baseOutputDir, {recursive: true});++ const sourceMapTestServer = await startSourceMapTestServer();+ const targetUrl = values.url ?? sourceMapTestServer.url;++ try {+ console.log(+ `Source map test server listening at: ${sourceMapTestServer.url}`,+ );+ if (values.url !== undefined) {+ console.log(`Using custom target URL: ${targetUrl}`);+ }+ console.log(`Scenarios to run: ${scenarios.map(s => s.name).join(', ')}`);++ const results: ScenarioResult[] = [];+ for (const scenarioEntry of scenarios) {+ const scenarioOutputDir =+ scenarios.length === 1 && values['output-dir'] !== undefined+ ? baseOutputDir+ : path.join(baseOutputDir, scenarioEntry.name);++ const scenarioArgs: ScenarioArgs = {+ targetUrl,+ outputDir: scenarioOutputDir,+ };++ const result = await profileScenario(+ scenarioEntry,+ scenarioArgs,+ options,+ rootDir,+ );+ results.push(result);+ }++ console.log('\n=== Summary ===');+ for (const result of results) {+ if (result.isGrowth) {+ console.warn(result.summary);+ } else {+ console.log(result.summary);+ }+ }+ } finally {+ await sourceMapTestServer.close();+ }+}++main().catch(error => {+ console.error(error);+ process.exitCode = 1;+});diff --git a/scripts/profile/scenarios/navigation.ts b/scripts/profile/scenarios/navigation.tsnew file mode 100644index 00000000..51963b92--- /dev/null+++ b/scripts/profile/scenarios/navigation.ts@@ -0,0 +1,44 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import path from 'node:path';++import type {ScenarioArgs, ToolCall} from '../types.ts';++export function get(args: ScenarioArgs): ToolCall[] {+ return [+ {+ name: 'navigate_page',+ arguments: {type: 'url', url: args.targetUrl},+ },+ {+ name: 'navigate_page',+ arguments: {type: 'url', url: args.targetUrl},+ },+ {+ name: 'navigate_page',+ arguments: {type: 'url', url: args.targetUrl},+ },+ {+ name: 'navigate_page',+ arguments: {type: 'url', url: args.targetUrl},+ },+ {+ name: 'take_snapshot',+ arguments: {},+ },+ {+ name: 'take_screenshot',+ arguments: {+ filePath: path.join(args.outputDir, 'page.png'),+ },+ },+ {+ name: 'list_network_requests',+ arguments: {},+ },+ ];+}diff --git a/scripts/profile/scenarios/page_churn.ts b/scripts/profile/scenarios/page_churn.tsnew file mode 100644index 00000000..16117139--- /dev/null+++ b/scripts/profile/scenarios/page_churn.ts@@ -0,0 +1,41 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import type {ScenarioArgs, ToolCall} from '../types.ts';+import {selectedPageIdFromToolResult} from '../utils.ts';++export function get(args: ScenarioArgs): ToolCall[] {+ return [+ {+ name: 'new_page',+ arguments: {url: args.targetUrl},+ },+ // Exercise the per-page collectors after its DevTools Universe has loaded+ // all scripts and source maps.+ {+ name: 'take_snapshot',+ arguments: {},+ },+ {+ name: 'list_network_requests',+ arguments: {},+ },+ {+ name: 'close_page',+ arguments: context => {+ const newPageResult = context.results[0];+ const pageId = selectedPageIdFromToolResult(newPageResult);+ return {pageId};+ },+ },+ // Force the MCP context to reconcile its page list before measuring. This+ // prevents target-destruction event latency from looking like retention.+ {+ name: 'list_pages',+ arguments: {},+ },+ ];+}diff --git a/scripts/profile/source_map_server.ts b/scripts/profile/source_map_server.tsnew file mode 100644index 00000000..5302b57f--- /dev/null+++ b/scripts/profile/source_map_server.ts@@ -0,0 +1,124 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import http from 'node:http';++export interface SourceMapTestServer {+ close(): Promise<void>;+ url: string;+}++export function sourceMapFor(index: number): string {+ return JSON.stringify({+ version: 3,+ file: `script-${index}.js`,+ sources: [`source-${index}.ts`],+ sourcesContent: [+ `export function profileFunction${index}(value: number): number {\n return value + ${index};\n}\n`,+ ],+ names: [],+ mappings: 'AAAA;AACA;AACA',+ });+}++export function scriptFor(index: number): string {+ return [+ `function profileFunction${index}(value) {`,+ ` return value + ${index};`,+ '}',+ 'globalThis.profileScriptResults ??= [];',+ `globalThis.profileScriptResults.push(profileFunction${index}(${index}));`,+ `//# sourceMappingURL=/maps/script-${index}.js.map`,+ '',+ ].join('\n');+}++export async function startSourceMapTestServer(+ scriptCount = 100,+): Promise<SourceMapTestServer> {+ const scriptTags = Array.from(+ {length: scriptCount},+ (_, index) => `<script src="/scripts/script-${index}.js"></script>`,+ ).join('\n');+ const html = `<!doctype html>+<html>+ <head>+ <meta charset="utf-8">+ <title>Source map profiler fixture</title>+ </head>+ <body>+ <h1>Source map profiler fixture</h1>+ <p>${scriptCount} scripts, each with a distinct source map.</p>+ ${scriptTags}+ </body>+</html>`;++ const server = http.createServer((request, response) => {+ const requestUrl = new URL(request.url ?? '/', 'http://127.0.0.1');+ if (requestUrl.pathname === '/') {+ response.writeHead(200, {+ 'cache-control': 'no-store',+ 'content-type': 'text/html; charset=utf-8',+ });+ response.end(html);+ return;+ }++ const scriptMatch = /^\/scripts\/script-(\d+)\.js$/.exec(+ requestUrl.pathname,+ );+ const mapMatch = /^\/maps\/script-(\d+)\.js\.map$/.exec(+ requestUrl.pathname,+ );+ const match = scriptMatch ?? mapMatch;+ const indexText = match?.[1];+ const index = indexText === undefined ? -1 : Number(indexText);+ if (!Number.isInteger(index) || index < 0 || index >= scriptCount) {+ response.writeHead(404);+ response.end('Not found');+ return;+ }++ if (scriptMatch) {+ response.writeHead(200, {+ 'cache-control': 'no-store',+ 'content-type': 'text/javascript; charset=utf-8',+ });+ response.end(scriptFor(index));+ return;+ }++ response.writeHead(200, {+ 'cache-control': 'no-store',+ 'content-type': 'application/json; charset=utf-8',+ });+ response.end(sourceMapFor(index));+ });++ await new Promise<void>((resolve, reject) => {+ server.once('error', reject);+ server.listen(0, '127.0.0.1', resolve);+ });+ const address = server.address();+ if (address === null || typeof address === 'string') {+ server.close();+ throw new Error('Source map test server did not expose a TCP port');+ }++ return {+ url: `http://127.0.0.1:${address.port}`,+ close: () =>+ new Promise<void>((resolve, reject) => {+ server.close(error => {+ if (error) {+ reject(error);+ } else {+ resolve();+ }+ });+ }),+ };+}diff --git a/scripts/profile/types.ts b/scripts/profile/types.tsnew file mode 100644index 00000000..83b8541b--- /dev/null+++ b/scripts/profile/types.ts@@ -0,0 +1,32 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++export interface ScenarioArgs {+ targetUrl: string;+ outputDir: string;+ [key: string]: unknown;+}++export interface ToolCallContext {+ results: unknown[];+}++export type ToolArguments =+ | Record<string, unknown>+ | ((+ context: ToolCallContext,+ ) => Record<string, unknown> | Promise<Record<string, unknown>>);++export interface ToolCall {+ name: string;+ arguments?: ToolArguments;+}++export interface ProfileScenario {+ name?: string;+ description?: string;+ get: (args: ScenarioArgs) => ToolCall[] | Promise<ToolCall[]>;+}diff --git a/scripts/profile/utils.ts b/scripts/profile/utils.tsnew file mode 100644index 00000000..1ca33e32--- /dev/null+++ b/scripts/profile/utils.ts@@ -0,0 +1,67 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import type {ProfileScenario} from './types.ts';++export function isObject(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null;+}++export function formatBytes(bytes: number): string {+ return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;+}++export function parsePositiveInteger(+ value: string | undefined,+ name: string,+): number {+ if (value === undefined || !/^\d+$/.test(value)) {+ throw new Error(`${name} must be a positive integer`);+ }+ const parsed = Number(value);+ if (!Number.isSafeInteger(parsed) || parsed < 1) {+ throw new Error(`${name} must be a positive integer`);+ }+ return parsed;+}++export function selectedPageIdFromToolResult(result: unknown): number {+ if (isObject(result) && isObject(result.structuredContent)) {+ const pages = result.structuredContent.pages;+ if (Array.isArray(pages)) {+ for (const page of pages) {+ if (+ isObject(page) &&+ page.selected === true &&+ typeof page.id === 'number'+ ) {+ return page.id;+ }+ }+ }+ }++ if (isObject(result) && Array.isArray(result.content)) {+ for (const content of result.content) {+ if (!isObject(content) || typeof content.text !== 'string') {+ continue;+ }+ const match = /^(\d+): .*\[selected\](?:\s|$)/m.exec(content.text);+ const pageId = match?.[1];+ if (pageId !== undefined) {+ return Number(pageId);+ }+ }+ }++ throw new Error(+ 'new_page did not identify the selected page in its response',+ );+}++export function isScenarioModule(value: unknown): value is ProfileScenario {+ return isObject(value) && typeof value.get === 'function';+}diff --git a/scripts/profile_mcp.ts b/scripts/profile_mcp.tsdeleted file mode 100644index c5a90a8b..00000000--- a/scripts/profile_mcp.ts+++ /dev/null@@ -1,557 +0,0 @@-/**- * @license- * Copyright 2026 Google LLC- * SPDX-License-Identifier: Apache-2.0- */--import fs from 'node:fs';-import http from 'node:http';-import path from 'node:path';-import {parseArgs} from 'node:util';--import {Client} from '@modelcontextprotocol/sdk/client/index.js';-import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';--interface HeapUsage {- usedSize: number;- totalSize: number;-}--interface Measurement extends HeapUsage {- label: string;- timestamp: string;-}--interface ProfileOptions {- iterations: number;- pageChurn: boolean;- sourceMapScriptCount: number;- warmupIterations: number;-}--interface SourceMapTestServer {- close(): Promise<void>;- url: string;-}--interface PendingRequest {- reject(error: Error): void;- resolve(result: unknown): void;-}--function isObject(value: unknown): value is Record<string, unknown> {- return typeof value === 'object' && value !== null;-}--function formatBytes(bytes: number): string {- return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;-}--function parsePositiveInteger(value: string | undefined, name: string): number {- if (value === undefined || !/^\d+$/.test(value)) {- throw new Error(`${name} must be a positive integer`);- }- const parsed = Number(value);- if (!Number.isSafeInteger(parsed) || parsed < 1) {- throw new Error(`${name} must be a positive integer`);- }- return parsed;-}--function selectedPageIdFromToolResult(result: unknown): number {- if (isObject(result) && isObject(result.structuredContent)) {- const pages = result.structuredContent.pages;- if (Array.isArray(pages)) {- for (const page of pages) {- if (- isObject(page) &&- page.selected === true &&- typeof page.id === 'number'- ) {- return page.id;- }- }- }- }-- if (isObject(result) && Array.isArray(result.content)) {- for (const content of result.content) {- if (!isObject(content) || typeof content.text !== 'string') {- continue;- }- const match = /^(\d+): .*\[selected\](?:\s|$)/m.exec(content.text);- const pageId = match?.[1];- if (pageId !== undefined) {- return Number(pageId);- }- }- }-- throw new Error(- 'new_page did not identify the selected page in its response',- );-}--function sourceMapFor(index: number): string {- return JSON.stringify({- version: 3,- file: `script-${index}.js`,- sources: [`source-${index}.ts`],- sourcesContent: [- `export function profileFunction${index}(value: number): number {\n return value + ${index};\n}\n`,- ],- names: [],- mappings: 'AAAA;AACA;AACA',- });-}--function scriptFor(index: number): string {- return [- `function profileFunction${index}(value) {`,- ` return value + ${index};`,- '}',- 'globalThis.profileScriptResults ??= [];',- `globalThis.profileScriptResults.push(profileFunction${index}(${index}));`,- `//# sourceMappingURL=/maps/script-${index}.js.map`,- '',- ].join('\n');-}--async function startSourceMapTestServer(- scriptCount: number,-): Promise<SourceMapTestServer> {- const scriptTags = Array.from(- {length: scriptCount},- (_, index) => `<script src="/scripts/script-${index}.js"></script>`,- ).join('\n');- const html = `<!doctype html>-<html>- <head>- <meta charset="utf-8">- <title>Source map profiler fixture</title>- </head>- <body>- <h1>Source map profiler fixture</h1>- <p>${scriptCount} scripts, each with a distinct source map.</p>- ${scriptTags}- </body>-</html>`;-- const server = http.createServer((request, response) => {- const requestUrl = new URL(request.url ?? '/', 'http://127.0.0.1');- if (requestUrl.pathname === '/') {- response.writeHead(200, {- 'cache-control': 'no-store',- 'content-type': 'text/html; charset=utf-8',- });- response.end(html);- return;- }-- const scriptMatch = /^\/scripts\/script-(\d+)\.js$/.exec(- requestUrl.pathname,- );- const mapMatch = /^\/maps\/script-(\d+)\.js\.map$/.exec(- requestUrl.pathname,- );- const match = scriptMatch ?? mapMatch;- const indexText = match?.[1];- const index = indexText === undefined ? -1 : Number(indexText);- if (!Number.isInteger(index) || index < 0 || index >= scriptCount) {- response.writeHead(404);- response.end('Not found');- return;- }-- if (scriptMatch) {- response.writeHead(200, {- 'cache-control': 'no-store',- 'content-type': 'text/javascript; charset=utf-8',- });- response.end(scriptFor(index));- return;- }-- response.writeHead(200, {- 'cache-control': 'no-store',- 'content-type': 'application/json; charset=utf-8',- });- response.end(sourceMapFor(index));- });-- await new Promise<void>((resolve, reject) => {- server.once('error', reject);- server.listen(0, '127.0.0.1', resolve);- });- const address = server.address();- if (address === null || typeof address === 'string') {- server.close();- throw new Error('Source map test server did not expose a TCP port');- }-- return {- url: `http://127.0.0.1:${address.port}`,- close: () =>- new Promise<void>((resolve, reject) => {- server.close(error => {- if (error) {- reject(error);- } else {- resolve();- }- });- }),- };-}--class InspectorClient {- readonly #pending = new Map<number, PendingRequest>();- #nextId = 1;- #snapshotStream: fs.WriteStream | undefined;- readonly #webSocket: WebSocket;-- private constructor(webSocket: WebSocket) {- this.#webSocket = webSocket;- webSocket.addEventListener('message', event => {- this.#handleMessage(event.data);- });- }-- static connect(url: string): Promise<InspectorClient> {- return new Promise((resolve, reject) => {- const webSocket = new WebSocket(url);- webSocket.addEventListener('open', () => {- resolve(new InspectorClient(webSocket));- });- webSocket.addEventListener('error', () => {- reject(new Error(`Failed to connect to Node inspector at ${url}`));- });- });- }-- #handleMessage(data: unknown): void {- if (typeof data !== 'string') {- return;- }- const message: unknown = JSON.parse(data);- if (!isObject(message)) {- return;- }-- if (message.method === 'HeapProfiler.addHeapSnapshotChunk') {- const params = message.params;- if (- this.#snapshotStream &&- isObject(params) &&- typeof params.chunk === 'string'- ) {- this.#snapshotStream.write(params.chunk);- }- return;- }-- if (typeof message.id !== 'number') {- return;- }- const pending = this.#pending.get(message.id);- if (!pending) {- return;- }- this.#pending.delete(message.id);- if (isObject(message.error)) {- const errorMessage =- typeof message.error.message === 'string'- ? message.error.message- : 'Unknown inspector error';- pending.reject(new Error(errorMessage));- return;- }- pending.resolve(message.result);- }-- send(method: string, params?: Record<string, unknown>): Promise<unknown> {- const id = this.#nextId++;- return new Promise((resolve, reject) => {- this.#pending.set(id, {resolve, reject});- this.#webSocket.send(JSON.stringify({id, method, params}));- });- }-- async getHeapUsage(): Promise<HeapUsage> {- await this.send('HeapProfiler.collectGarbage');- const result = await this.send('Runtime.getHeapUsage');- if (- !isObject(result) ||- typeof result.usedSize !== 'number' ||- typeof result.totalSize !== 'number'- ) {- throw new Error('Node inspector returned invalid heap usage data');- }- return {usedSize: result.usedSize, totalSize: result.totalSize};- }-- async takeHeapSnapshot(filePath: string): Promise<void> {- const stream = fs.createWriteStream(filePath, {encoding: 'utf8'});- this.#snapshotStream = stream;- try {- await this.send('HeapProfiler.takeHeapSnapshot', {reportProgress: false});- } finally {- this.#snapshotStream = undefined;- await new Promise<void>((resolve, reject) => {- stream.end(resolve);- stream.on('error', reject);- });- }- }-- close(): void {- this.#webSocket.close();- }-}--function inspectorUrlFrom(transport: StdioClientTransport): Promise<string> {- const stderr = transport.stderr;- if (!stderr) {- throw new Error('MCP server stderr is unavailable');- }- return new Promise((resolve, reject) => {- let buffered = '';- const timeout = setTimeout(() => {- reject(- new Error(- `Timed out waiting for the Node inspector URL. Server stderr: ${buffered}`,- ),- );- }, 10_000);- stderr.setEncoding('utf8');- stderr.on('data', chunk => {- if (typeof chunk !== 'string') {- return;- }- buffered += chunk;- const match = /Debugger listening on (ws:\/\/\S+)/.exec(buffered);- const url = match?.[1];- if (url) {- clearTimeout(timeout);- resolve(url);- }- });- });-}--async function main(): Promise<void> {- const {values} = parseArgs({- options: {- url: {type: 'string', default: 'https://developers.google.com'},- 'output-dir': {type: 'string'},- iterations: {type: 'string', default: '10'},- 'page-churn': {type: 'boolean', default: false},- 'source-map-test-page': {type: 'boolean', default: false},- 'source-map-script-count': {type: 'string', default: '100'},- 'warmup-iterations': {type: 'string', default: '10'},- },- });- const options: ProfileOptions = {- iterations: parsePositiveInteger(values.iterations, '--iterations'),- pageChurn: values['page-churn'],- sourceMapScriptCount: parsePositiveInteger(- values['source-map-script-count'],- '--source-map-script-count',- ),- warmupIterations: parsePositiveInteger(- values['warmup-iterations'],- '--warmup-iterations',- ),- };- const rootDir = path.resolve(import.meta.dirname, '..');- const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-');- const outputDir = path.resolve(- values['output-dir'] ?? path.join(rootDir, 'mcp-heap-profiles', timestamp),- );- fs.mkdirSync(outputDir, {recursive: true});-- const sourceMapTestServer =- values['source-map-test-page'] || options.pageChurn- ? await startSourceMapTestServer(options.sourceMapScriptCount)- : undefined;- const targetUrl = sourceMapTestServer?.url ?? values.url;-- const env: Record<string, string> = {};- for (const [key, value] of Object.entries(process.env)) {- if (value !== undefined) {- env[key] = value;- }- }- env.CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS = 'true';-- const transport = new StdioClientTransport({- command: process.execPath,- args: [- '--inspect=127.0.0.1:0',- path.join(rootDir, 'build/src/bin/chrome-devtools-mcp.js'),- '--headless',- '--isolated',- ],- env,- stderr: 'pipe',- });- const inspectorUrlPromise = inspectorUrlFrom(transport);- const client = new Client(- {name: 'mcp-heap-profiler', version: '1.0.0'},- {capabilities: {}},- );- let inspector: InspectorClient | undefined;- const measurements: Measurement[] = [];-- const runNavigationIteration = async (): Promise<void> => {- await client.callTool({- name: 'navigate_page',- arguments: {type: 'url', url: targetUrl},- });- await client.callTool({- name: 'navigate_page',- arguments: {type: 'url', url: targetUrl},- });- await client.callTool({- name: 'navigate_page',- arguments: {type: 'url', url: targetUrl},- });- await client.callTool({- name: 'navigate_page',- arguments: {type: 'url', url: targetUrl},- });- await client.callTool({name: 'take_snapshot', arguments: {}});- await client.callTool({- name: 'take_screenshot',- arguments: {- filePath: path.join(outputDir, 'page.png'),- },- });- await client.callTool({name: 'list_network_requests', arguments: {}});- };-- const runPageChurnIteration = async (): Promise<void> => {- const result = await client.callTool({- name: 'new_page',- arguments: {url: targetUrl},- });- const pageId = selectedPageIdFromToolResult(result);-- // Exercise the per-page collectors after its DevTools Universe has loaded- // all scripts and source maps.- await client.callTool({name: 'take_snapshot', arguments: {}});- await client.callTool({name: 'list_network_requests', arguments: {}});-- await client.callTool({- name: 'close_page',- arguments: {pageId},- });- // Force the MCP context to reconcile its page list before measuring. This- // prevents target-destruction event latency from looking like retention.- await client.callTool({name: 'list_pages', arguments: {}});- };-- const runIteration = options.pageChurn- ? runPageChurnIteration- : runNavigationIteration;-- const record = async (- label: string,- takeSnapshot: boolean,- ): Promise<void> => {- if (!inspector) {- throw new Error('Inspector is not connected');- }- const usage = await inspector.getHeapUsage();- const measurement = {- label,- timestamp: new Date().toISOString(),- ...usage,- };- measurements.push(measurement);- console.log(- `${label}: used ${formatBytes(usage.usedSize)}, total ${formatBytes(usage.totalSize)}`,- );- if (!takeSnapshot) {- return;- }- const snapshotPath = path.join(outputDir, `${label}.heapsnapshot`);- await inspector.takeHeapSnapshot(snapshotPath);- console.log(` snapshot: ${snapshotPath}`);- };-- try {- await client.connect(transport);- inspector = await InspectorClient.connect(await inspectorUrlPromise);- console.log(`MCP server PID: ${transport.pid}`);- console.log(`Target URL: ${targetUrl}`);- if (sourceMapTestServer) {- console.log(- `Source map test page: ${options.sourceMapScriptCount} scripts`,- );- }- console.log(- `Workload: ${options.pageChurn ? 'create and close mapped-script pages' : 'repeated navigation'}`,- );- console.log(`Output directory: ${outputDir}`);-- await record('connected', false);- for (- let iteration = 1;- iteration <= options.warmupIterations;- iteration++- ) {- console.log(`Warm-up ${iteration}/${options.warmupIterations}`);- await runIteration();- }-- // Taking a heap snapshot exercises Node inspector and serialization paths.- // Prime those paths before capturing the baseline so their JIT-compiled code- // is not mistaken for workload growth in the final comparison.- await record('snapshot-primer', true);- await record('baseline', true);-- for (let iteration = 1; iteration <= options.iterations; iteration++) {- console.log(`Measured iteration ${iteration}/${options.iterations}`);- await runIteration();- await record(`iteration-${iteration}`, false);- }- await record('final', true);-- const baseline = measurements.find(- measurement => measurement.label === 'baseline',- );- const final = measurements.find(- measurement => measurement.label === 'final',- );- if (baseline && final) {- const growth = final.usedSize - baseline.usedSize;- if (growth > 0) {- const percentage = (growth / baseline.usedSize) * 100;- console.warn(- `The MCP heap grew by ${formatBytes(growth)} (${percentage.toFixed(2)}%) across ${options.iterations} measured iterations. Compare baseline.heapsnapshot with final.heapsnapshot to determine whether retained workload objects accumulated.`,- );- } else {- console.log(- `The MCP heap did not grow across the measured iterations (${formatBytes(growth)}).`,- );- }- }-- const reportPath = path.join(outputDir, 'heap-usage.json');- fs.writeFileSync(- reportPath,- `${JSON.stringify({pid: transport.pid, url: targetUrl, options, measurements}, null, 2)}\n`,- );- console.log(`Report: ${reportPath}`);- } finally {- inspector?.close();- await client.close();- await sourceMapTestServer?.close();- }-}--main().catch(error => {- console.error(error);- process.exitCode = 1;-});