chore(memory): expose retainer logic (#2056)

Allows the LLM to query the heapsnapshot further to understand what the
retainer path logic.

Author: Lightning00Blade

README.md

@@ -514,9 +514,10 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
   - [`screencast_start`](docs/tool-reference.md#screencast_start)
   - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
-- **Memory** (4 tools)
+- **Memory** (5 tools)
   - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
   - [`get_memory_snapshot_details`](docs/tool-reference.md#get_memory_snapshot_details)
+  - [`get_node_retainers`](docs/tool-reference.md#get_node_retainers)
   - [`get_nodes_by_class`](docs/tool-reference.md#get_nodes_by_class)
   - [`load_memory_snapshot`](docs/tool-reference.md#load_memory_snapshot)
 - **Extensions** (5 tools)

docs/tool-reference.md

@@ -39,9 +39,10 @@
   - [`take_snapshot`](#take_snapshot)
   - [`screencast_start`](#screencast_start)
   - [`screencast_stop`](#screencast_stop)
-- **[Memory](#memory)** (4 tools)
+- **[Memory](#memory)** (5 tools)
   - [`take_memory_snapshot`](#take_memory_snapshot)
   - [`get_memory_snapshot_details`](#get_memory_snapshot_details)
+  - [`get_node_retainers`](#get_node_retainers)
   - [`get_nodes_by_class`](#get_nodes_by_class)
   - [`load_memory_snapshot`](#load_memory_snapshot)
 - **[Extensions](#extensions)** (5 tools)
@@ -464,6 +465,19 @@ in the DevTools Elements panel (if any).
 
 ---
 
+### `get_node_retainers`
+
+**Description:** Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --experimentalMemory=true)
+
+**Parameters:**
+
+- **filePath** (string) **(required)**: A path to a .heapsnapshot file to read.
+- **nodeId** (number) **(required)**: The stable node ID to get retainers for.
+- **pageIdx** (number) _(optional)_: The page index for pagination.
+- **pageSize** (number) _(optional)_: The page size for pagination.
+
+---
+
 ### `get_nodes_by_class`
 
 **Description:** Loads a memory heapsnapshot and returns instances of a specific class with their stable IDs. (requires flag: --experimentalMemory=true)

src/HeapSnapshotManager.ts

@@ -7,6 +7,7 @@
 import fsSync from 'node:fs';
 import path from 'node:path';
 
+import {isNodeLike} from './formatters/HeapSnapshotFormatter.js';
 import {DevTools} from './third_party/index.js';
 import {
   createIdGenerator,
@@ -112,8 +113,41 @@ export class HeapSnapshotManager {
     }
     const provider = snapshot.createNodesProviderForClass(className, filter);
 
-    const range = await provider.serializeItemsRange(0, 1);
-    return await provider.serializeItemsRange(0, range.totalLength);
+    return await provider.serializeItemsRange(0, Infinity);
+  }
+
+  async findNodeIndexById(
+    filePath: string,
+    nodeId: number,
+  ): Promise<number | undefined> {
+    const snapshot = await this.getSnapshot(filePath);
+    const aggregates = await this.getAggregates(filePath);
+    const filter =
+      new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+
+    for (const classKey of Object.keys(aggregates)) {
+      const provider = snapshot.createNodesProviderForClass(classKey, filter);
+      const range = await provider.serializeItemsRange(0, Infinity);
+      for (const item of range.items) {
+        if (isNodeLike(item) && item.id === nodeId) {
+          return item.nodeIndex;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  async getRetainers(
+    filePath: string,
+    nodeId: number,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
+    const nodeIndex = await this.findNodeIndexById(filePath, nodeId);
+    if (nodeIndex === undefined) {
+      throw new Error(`Node with ID ${nodeId} not found`);
+    }
+    const snapshot = await this.getSnapshot(filePath);
+    const provider = snapshot.createRetainingEdgesProvider(nodeIndex);
+    return await provider.serializeItemsRange(0, Infinity);
   }
 
   #getCachedSnapshot(filePath: string) {

src/McpContext.ts

@@ -830,4 +830,11 @@ export class McpContext implements Context {
     this.validatePath(filePath);
     return await this.#heapSnapshotManager.getNodesByUid(filePath, uid);
   }
+
+  async getHeapSnapshotRetainers(
+    filePath: string,
+    nodeId: number,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange> {
+    return await this.#heapSnapshotManager.getRetainers(filePath, nodeId);
+  }
 }

src/McpResponse.ts

@@ -9,7 +9,7 @@ import type {WebMCPTool} from 'puppeteer-core';
 import type {ParsedArguments} from './bin/chrome-devtools-mcp-cli-options.js';
 import {ConsoleFormatter} from './formatters/ConsoleFormatter.js';
 import {HeapSnapshotFormatter} from './formatters/HeapSnapshotFormatter.js';
-import {isNodeLike} from './formatters/HeapSnapshotFormatter.js';
+import {isEdgeLike, isNodeLike} from './formatters/HeapSnapshotFormatter.js';
 import {IssueFormatter} from './formatters/IssueFormatter.js';
 import {NetworkFormatter} from './formatters/NetworkFormatter.js';
 import {SnapshotFormatter} from './formatters/SnapshotFormatter.js';
@@ -984,12 +984,20 @@ Call ${handleDialog.name} to handle it before continuing.`);
       }
       const nodes = this.#heapSnapshotOptions.nodes;
       if (nodes) {
-        const sortedItems = nodes.items
-          .filter(isNodeLike)
-          .sort((a, b) => b.retainedSize - a.retainedSize);
+        let items = Array.from(nodes.items);
+        const firstItem = nodes.items[0];
+        if (firstItem) {
+          if (isNodeLike(firstItem)) {
+            items = items
+              .filter(isNodeLike)
+              .sort((a, b) => b.retainedSize - a.retainedSize);
+          } else if (isEdgeLike(firstItem)) {
+            items = items.filter(isEdgeLike);
+          }
+        }
 
         const paginationData = this.#dataWithPagination(
-          sortedItems,
+          items,
           this.#heapSnapshotOptions.pagination,
         );
 

src/bin/chrome-devtools-cli-options.ts

@@ -337,6 +337,37 @@ export const commands: Commands = {
       },
     },
   },
+  get_node_retainers: {
+    description:
+      'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --experimentalMemory=true)',
+    category: 'Memory',
+    args: {
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description: 'A path to a .heapsnapshot file to read.',
+        required: true,
+      },
+      nodeId: {
+        name: 'nodeId',
+        type: 'number',
+        description: 'The stable node ID to get retainers for.',
+        required: true,
+      },
+      pageIdx: {
+        name: 'pageIdx',
+        type: 'number',
+        description: 'The page index for pagination.',
+        required: false,
+      },
+      pageSize: {
+        name: 'pageSize',
+        type: 'number',
+        description: 'The page size for pagination.',
+        required: false,
+      },
+    },
+  },
   get_nodes_by_class: {
     description:
       'Loads a memory heapsnapshot and returns instances of a specific class with their stable IDs. (requires flag: --experimentalMemory=true)',

src/formatters/HeapSnapshotFormatter.ts

@@ -5,15 +5,15 @@
  */
 
 import type {AggregatedInfoWithUid} from '../HeapSnapshotManager.js';
-import type {DevTools} from '../third_party/index.js';
+import {DevTools} from '../third_party/index.js';
 import {stableIdSymbol} from '../utils/id.js';
 
 export interface FormattedSnapshotEntry {
   className: string;
   classUid?: number;
   count: number;
-  selfSize: number;
-  retainedSize: number;
+  selfSize: string;
+  retainedSize: string;
 }
 
 export function isNodeLike(
@@ -24,6 +24,22 @@ export function isNodeLike(
   );
 }
 
+export function isEdgeLike(
+  item: unknown,
+): item is DevTools.HeapSnapshotModel.HeapSnapshotModel.Edge {
+  return (
+    typeof item === 'object' &&
+    item !== null &&
+    'name' in item &&
+    'node' in item &&
+    'type' in item &&
+    typeof item.node === 'object' &&
+    item.node !== null &&
+    'id' in item.node &&
+    'name' in item.node
+  );
+}
+
 export class HeapSnapshotFormatter {
   #aggregates: Record<string, AggregatedInfoWithUid>;
 
@@ -39,14 +55,23 @@ export class HeapSnapshotFormatter {
   ): string {
     const lines: string[] = [];
 
-    if (items.length > 0 && isNodeLike(items[0])) {
-      lines.push('id,name,type,distance,selfSize,retainedSize');
+    if (items.length > 0) {
+      const firstItem = items[0];
+      if (isNodeLike(firstItem)) {
+        lines.push('id,name,type,distance,selfSize,retainedSize');
+      } else if (isEdgeLike(firstItem)) {
+        lines.push('edgeIndex,edgeName,edgeType,targetNodeId,targetNodeName');
+      }
     }
 
     for (const item of items) {
       if (isNodeLike(item)) {
         lines.push(
-          `${item.id},"${item.name}",${item.type},${item.distance},${item.selfSize},${item.retainedSize}`,
+          `${item.id},${item.name},${item.type},${item.distance},${DevTools.I18n.ByteUtilities.formatBytesToKb(item.selfSize)},${DevTools.I18n.ByteUtilities.formatBytesToKb(item.retainedSize)}`,
+        );
+      } else if (isEdgeLike(item)) {
+        lines.push(
+          `${item.edgeIndex},${item.name},${item.type},${item.node.id},${item.node.name}`,
         );
       }
     }
@@ -66,7 +91,7 @@ export class HeapSnapshotFormatter {
     for (const info of sorted) {
       const uid = info[stableIdSymbol] ?? '';
       lines.push(
-        `${uid},"${info.name}",${info.count},${info.self},${info.maxRet}`,
+        `${uid},${info.name},${info.count},${DevTools.I18n.ByteUtilities.formatBytesToKb(info.self)},${DevTools.I18n.ByteUtilities.formatBytesToKb(info.maxRet)}`,
       );
     }
 
@@ -79,8 +104,8 @@ export class HeapSnapshotFormatter {
       uid: info[stableIdSymbol],
       className: info.name,
       count: info.count,
-      selfSize: info.self,
-      retainedSize: info.maxRet,
+      selfSize: DevTools.I18n.ByteUtilities.formatBytesToKb(info.self),
+      retainedSize: DevTools.I18n.ByteUtilities.formatBytesToKb(info.maxRet),
     }));
   }
 

src/telemetry/tool_call_metrics.json

@@ -631,5 +631,26 @@
   {
     "name": "list3p_developer_tools",
     "args": []
+  },
+  {
+    "name": "get_node_retainers",
+    "args": [
+      {
+        "name": "file_path_length",
+        "argType": "number"
+      },
+      {
+        "name": "node_id",
+        "argType": "number"
+      },
+      {
+        "name": "page_idx",
+        "argType": "number"
+      },
+      {
+        "name": "page_size",
+        "argType": "number"
+      }
+    ]
   }
 ]

src/tools/ToolDefinition.ts

@@ -246,6 +246,10 @@ export type Context = Readonly<{
     filePath: string,
     uid: number,
   ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange>;
+  getHeapSnapshotRetainers(
+    filePath: string,
+    nodeId: number,
+  ): Promise<DevTools.HeapSnapshotModel.HeapSnapshotModel.ItemsRange>;
 }>;
 
 /**

src/tools/memory.ts

@@ -128,3 +128,34 @@ export const getNodesByClass = defineTool({
     });
   },
 });
+
+export const getNodeRetainers = defineTool({
+  name: 'get_node_retainers',
+  description:
+    'Loads a memory heapsnapshot and returns retainers for a specific node ID.',
+  annotations: {
+    category: ToolCategory.MEMORY,
+    readOnlyHint: true,
+    conditions: ['experimentalMemory'],
+  },
+  blockedByDialog: false,
+  schema: {
+    filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+    nodeId: zod.number().describe('The stable node ID to get retainers for.'),
+    pageIdx: zod.number().optional().describe('The page index for pagination.'),
+    pageSize: zod.number().optional().describe('The page size for pagination.'),
+  },
+  handler: async (request, response, context) => {
+    context.validatePath(request.params.filePath);
+
+    const retainers = await context.getHeapSnapshotRetainers(
+      request.params.filePath,
+      request.params.nodeId,
+    );
+
+    response.setHeapSnapshotNodes(retainers, {
+      pageIdx: request.params.pageIdx,
+      pageSize: request.params.pageSize,
+    });
+  },
+});