@memlab/mcp-server 2.1.0 → 2.3.0

package/dist/tools/find-by-shape.js

@@ -0,0 +1,178 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import memlabCore from '@memlab/core';
+const { utils, NumericSet } = memlabCore;
+import { z } from 'zod';
+import { getSnapshot } from '../heap-state.js';
+import { isNodeWorthInspecting, serializeNodeSummary, formatNodeSummaryTable, formatNumber, formatBytes, errorResult, toolResult, } from '../utils.js';
+export function registerFindByShape(server) {
+    server.tool('memlab_find_by_shape', 'Find all objects that have a specific set of property names (multi-property intersection search). Unlike find_by_property which searches for a single property, this finds objects matching a "shape" — objects that have ALL of the specified properties. Useful for finding instances of a specific record type, data structure, or component when you know its property names but not its constructor.', {
+        properties: z
+            .array(z.string())
+            .min(1)
+            .describe('Property names that must ALL be present on matching objects (e.g., ["callback", "context", "priority"])'),
+        exclude_properties: z
+            .array(z.string())
+            .optional()
+            .describe('Property names that must NOT be present. Use to distinguish between similar shapes.'),
+        class_name: z
+            .string()
+            .optional()
+            .describe('Optional constructor name filter to narrow results (e.g., "Object", "EventHandlerRefInternal")'),
+        output_mode: z
+            .enum(['full', 'count', 'ids'])
+            .optional()
+            .default('full')
+            .describe('Output verbosity: "full" returns node summaries (default), "count" returns only count and aggregate size, "ids" returns node IDs'),
+        follow_property: z
+            .string()
+            .optional()
+            .describe("For each matched object, resolve this property edge and include the target's " +
+            'name, type, and ID in the output. Enables "find objects with shape X and tell ' +
+            'me the distribution of property Y" in a single call.'),
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Maximum number of results (default 20)'),
+    }, async ({ properties, exclude_properties, class_name, output_mode, follow_property, limit, }) => {
+        try {
+            const snapshot = getSnapshot();
+            const requiredSet = new Set(properties);
+            const excludeSet = new Set(exclude_properties ?? []);
+            const matchesShape = (node) => {
+                if (!isNodeWorthInspecting(node))
+                    return false;
+                if (class_name && node.name !== class_name)
+                    return false;
+                const foundProps = new Set();
+                for (const edge of node.references) {
+                    if (edge.type !== 'property' && edge.type !== 'element')
+                        continue;
+                    const name = String(edge.name_or_index);
+                    if (excludeSet.has(name))
+                        return false;
+                    if (requiredSet.has(name))
+                        foundProps.add(name);
+                }
+                return foundProps.size === requiredSet.size;
+            };
+            const shapeDesc = `{${properties.join(', ')}}` +
+                (exclude_properties?.length
+                    ? ` without {${exclude_properties.join(', ')}}`
+                    : '') +
+                (class_name ? ` (class: ${class_name})` : '');
+            if (output_mode === 'count') {
+                let totalCount = 0;
+                let totalSelf = 0;
+                const nodeIds = new NumericSet();
+                snapshot.nodes.forEach(node => {
+                    if (!matchesShape(node))
+                        return;
+                    totalCount++;
+                    totalSelf += node.self_size;
+                    nodeIds.add(node.id);
+                });
+                if (totalCount === 0) {
+                    return toolResult(`No objects found matching shape ${shapeDesc}`);
+                }
+                // Dominator-aware aggregate: shape-matching objects can nest on the
+                // dominator tree, so a raw sum of retainedSize would double-count and
+                // can exceed 100% of heap.
+                const totalRetained = utils.aggregateDominatorMetrics(nodeIds, snapshot, () => true, (node) => node.retainedSize);
+                return toolResult(`Objects matching shape ${shapeDesc}: ${formatNumber(totalCount)} total, ${formatBytes(totalSelf)} self size, ${formatBytes(totalRetained)} aggregate retained size (dominator-deduplicated)`);
+            }
+            const results = [];
+            let totalCount = 0;
+            snapshot.nodes.forEach(node => {
+                if (!matchesShape(node))
+                    return;
+                totalCount++;
+                const size = node.retainedSize;
+                let inserted = false;
+                for (let i = 0; i < results.length; i++) {
+                    if (size > results[i].retainedSize) {
+                        results.splice(i, 0, node);
+                        inserted = true;
+                        break;
+                    }
+                }
+                if (!inserted) {
+                    results.push(node);
+                }
+                if (results.length > limit) {
+                    results.length = limit;
+                }
+            });
+            if (totalCount === 0) {
+                return toolResult(`No objects found matching shape ${shapeDesc}\n\n` +
+                    `**Tips:**\n` +
+                    `- Check property names with \`memlab_object_shape\` on a known instance\n` +
+                    `- Try fewer required properties to broaden the search\n` +
+                    `- Use \`memlab_find_by_property\` with a single distinctive property first`);
+            }
+            if (output_mode === 'ids') {
+                return toolResult(`Found ${formatNumber(totalCount)} objects matching shape ${shapeDesc} (showing ${results.length} IDs)\n\nIDs: ${results.map(n => n.id).join(', ')}`);
+            }
+            const summaries = results.map(serializeNodeSummary);
+            const countNote = totalCount > results.length
+                ? ` (${formatNumber(totalCount)} total, showing top ${results.length})`
+                : '';
+            const outputLines = [
+                `Found ${formatNumber(totalCount)} objects matching shape ${shapeDesc}${countNote}`,
+                '',
+                formatNodeSummaryTable(summaries),
+            ];
+            if (follow_property && results.length > 0) {
+                const followDistribution = new Map();
+                let missingCount = 0;
+                for (const node of results) {
+                    let found = false;
+                    for (const edge of node.references) {
+                        if (String(edge.name_or_index) === follow_property) {
+                            const target = edge.toNode;
+                            const key = `${target.name} (${target.type})`;
+                            const existing = followDistribution.get(key);
+                            if (existing) {
+                                existing.count++;
+                            }
+                            else {
+                                followDistribution.set(key, {
+                                    count: 1,
+                                    exampleId: target.id,
+                                });
+                            }
+                            found = true;
+                            break;
+                        }
+                    }
+                    if (!found)
+                        missingCount++;
+                }
+                const sorted = [...followDistribution.entries()].sort((a, b) => b[1].count - a[1].count);
+                outputLines.push('', `**Property \`${follow_property}\` distribution across ${results.length} matches:**`);
+                for (const [key, info] of sorted.slice(0, 15)) {
+                    outputLines.push(`  - ${formatNumber(info.count)}× ${key} (example: @${info.exampleId})`);
+                }
+                if (sorted.length > 15) {
+                    outputLines.push(`  - … and ${sorted.length - 15} more types`);
+                }
+                if (missingCount > 0) {
+                    outputLines.push(`  - ${formatNumber(missingCount)} object(s) missing property \`${follow_property}\``);
+                }
+            }
+            return toolResult(outputLines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=find-by-shape.js.map

package/dist/tools/find-by-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-by-shape.js","sourceRoot":"","sources":["../../src/tools/find-by-shape.ts"],"names":[],"mappings":"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"}

package/dist/tools/find-nodes-by-class.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find-nodes-by-class.d.ts","sourceRoot":"","sources":["../../src/tools/find-nodes-by-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAYvE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAkChE"}
+{"version":3,"file":"find-nodes-by-class.d.ts","sourceRoot":"","sources":["../../src/tools/find-nodes-by-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAgBvE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwFhE"}

package/dist/tools/find-nodes-by-class.js

@@ -7,28 +7,72 @@
  * @format
  * @oncall memory_lab
  */
+import memlabCore from '@memlab/core';
+const { utils, NumericSet } = memlabCore;
 import { z } from 'zod';
 import { getSnapshot } from '../heap-state.js';
-import { filterLargestObjects, serializeNodeSummary, formatNodeSummaryTable, errorResult, toolResult, } from '../utils.js';
+import { filterLargestObjects, serializeNodeSummary, formatNodeSummaryTable, formatNumber, formatBytes, errorResult, toolResult, } from '../utils.js';
 export function registerFindNodesByClass(server) {
     server.tool('memlab_find_nodes_by_class', 'Find heap objects by constructor/class name. Returns matching objects sorted by retained size. Follow up with memlab_retainer_trace on a result node to see why it is retained, memlab_get_references to inspect its properties, or memlab_retainer_summary to find common retainer patterns across all instances.', {
         class_name: z
             .string()
             .describe('The constructor or class name to search for'),
+        output_mode: z
+            .enum(['full', 'count', 'ids'])
+            .optional()
+            .default('full')
+            .describe('Output verbosity: "full" returns node summaries sorted by retained size (default), "count" returns only total count and aggregate retained size, "ids" returns only node IDs sorted by retained size'),
         limit: z
             .number()
             .optional()
             .default(20)
             .describe('Maximum number of results (default 20)'),
-    }, async ({ class_name, limit }) => {
+    }, async ({ class_name, output_mode, limit }) => {
         try {
             const snapshot = getSnapshot();
-            const nodes = filterLargestObjects(snapshot, node => node.name === class_name && node.type === 'object', limit);
-            const summaries = nodes.map(serializeNodeSummary);
-            if (summaries.length === 0) {
+            const classFilter = (node) => node.name === class_name && node.type === 'object';
+            if (output_mode === 'count') {
+                let totalCount = 0;
+                let totalSelf = 0;
+                const nodeIds = new NumericSet();
+                snapshot.nodes.forEach(node => {
+                    if (!classFilter(node))
+                        return;
+                    totalCount++;
+                    totalSelf += node.self_size;
+                    nodeIds.add(node.id);
+                });
+                if (totalCount === 0) {
+                    return toolResult(`No objects found with class "${class_name}"`);
+                }
+                // Dominator-aware aggregate: instances of a class often nest on the
+                // dominator tree (e.g. a Foo retaining another Foo), so a raw sum of
+                // retainedSize would double-count and can exceed 100% of heap.
+                const totalRetained = utils.aggregateDominatorMetrics(nodeIds, snapshot, () => true, (node) => node.retainedSize);
+                return toolResult(`"${class_name}": ${formatNumber(totalCount)} instances, ${formatBytes(totalSelf)} total self size, ${formatBytes(totalRetained)} aggregate retained size (dominator-deduplicated)`);
+            }
+            const nodes = filterLargestObjects(snapshot, classFilter, limit);
+            let totalCount = 0;
+            if (nodes.length === limit) {
+                snapshot.nodes.forEach(node => {
+                    if (classFilter(node))
+                        totalCount++;
+                });
+            }
+            else {
+                totalCount = nodes.length;
+            }
+            if (nodes.length === 0) {
                 return toolResult(`No objects found with class "${class_name}"`);
             }
-            return toolResult(`Found ${summaries.length} "${class_name}" objects\n\n${formatNodeSummaryTable(summaries)}`);
+            if (output_mode === 'ids') {
+                return toolResult(`"${class_name}": ${formatNumber(totalCount)} total instances (showing ${nodes.length} IDs by retained size)\n\nIDs: ${nodes.map(n => n.id).join(', ')}`);
+            }
+            const summaries = nodes.map(serializeNodeSummary);
+            const countNote = totalCount > nodes.length
+                ? ` (${formatNumber(totalCount)} total, showing top ${nodes.length})`
+                : '';
+            return toolResult(`Found ${formatNumber(totalCount)} "${class_name}" objects${countNote}\n\n${formatNodeSummaryTable(summaries)}`);
         }
         catch (err) {
             return errorResult(err);

package/dist/tools/find-nodes-by-class.js.map

@@ -1 +1 @@
-{"version":3,"file":"find-nodes-by-class.js","sourceRoot":"","sources":["../../src/tools/find-nodes-by-class.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EAEX,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,MAAM,UAAU,wBAAwB,CAAC,MAAiB;IACxD,MAAM,CAAC,IAAI,CACT,4BAA4B,EAC5B,oTAAoT,EACpT;QACE,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,QAAQ,CAAC,6CAA6C,CAAC;QAC1D,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,wCAAwC,CAAC;KACtD,EACD,KAAK,EAAE,EAAC,UAAU,EAAE,KAAK,EAAC,EAAE,EAAE;QAC5B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,oBAAoB,CAChC,QAAQ,EACR,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAC1D,KAAK,CACN,CAAC;YACF,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;YAClD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC3B,OAAO,UAAU,CAAC,gCAAgC,UAAU,GAAG,CAAC,CAAC;YACnE,CAAC;YACD,OAAO,UAAU,CACf,SAAS,SAAS,CAAC,MAAM,KAAK,UAAU,gBAAgB,sBAAsB,CAAC,SAAS,CAAC,EAAE,CAC5F,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"find-nodes-by-class.js","sourceRoot":"","sources":["../../src/tools/find-nodes-by-class.ts"],"names":[],"mappings":"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"}

package/dist/tools/for-each.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"for-each.d.ts","sourceRoot":"","sources":["../../src/tools/for-each.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA2BvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6MvD"}
+{"version":3,"file":"for-each.d.ts","sourceRoot":"","sources":["../../src/tools/for-each.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA2BvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+MvD"}

package/dist/tools/for-each.js

@@ -176,7 +176,7 @@ export function registerForEach(server) {
         catch (err) {
             if (err instanceof Error &&
                 err.message.includes('Script execution timed out')) {
-                return errorResult(new Error(`Execution timed out after ${timeout_ms}ms`));
+                return errorResult(new Error(`Execution timed out after ${timeout_ms}ms. Increase timeout_ms, or use a dedicated indexed tool (memlab_find_by_property, memlab_property_distribution, memlab_class_histogram) instead of a full-snapshot walk on a large heap.`));
             }
             return errorResult(err);
         }

package/dist/tools/for-each.js.map

@@ -1 +1 @@
-{"version":3,"file":"for-each.js","sourceRoot":"","sources":["../../src/tools/for-each.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"for-each.js","sourceRoot":"","sources":["../../src/tools/for-each.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-node.d.ts","sourceRoot":"","sources":["../../src/tools/get-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAYvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4CvD"}
+{"version":3,"file":"get-node.d.ts","sourceRoot":"","sources":["../../src/tools/get-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAYvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmDvD"}

package/dist/tools/get-node.js

@@ -41,6 +41,12 @@ export function registerGetNode(server) {
                     : d.string_value;
                 lines.push(`**String Value:** "${val}"`);
             }
+            if (node.name === 'smi number' && node.self_size === 0) {
+                lines.push(`**Decoded SMI Value:** ${node.id >> 1}`);
+            }
+            else if (node.name === 'heap number') {
+                lines.push(`**Type:** Heap Number (boxed double — value not stored in snapshot format)`);
+            }
             return toolResult(lines.join('\n'));
         }
         catch (err) {

package/dist/tools/get-node.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-node.js","sourceRoot":"","sources":["../../src/tools/get-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,WAAW,EAEX,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,2JAA2J,EAC3J;QACE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;KAChE,EACD,KAAK,EAAE,EAAC,OAAO,EAAC,EAAE,EAAE;QAClB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,WAAW,CAAC,gBAAgB,OAAO,YAAY,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,KAAK,GAAG;gBACZ,YAAY,CAAC,CAAC,EAAE,EAAE;gBAClB,aAAa,CAAC,CAAC,IAAI,EAAE;gBACrB,aAAa,CAAC,CAAC,IAAI,EAAE;gBACrB,kBAAkB,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE;gBAC5C,sBAAsB,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE;gBACpD,kBAAkB,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE;gBAC9C,kBAAkB,YAAY,CAAC,CAAC,CAAC,cAAc,CAAC,EAAE;gBAClD,iBAAiB,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;gBAC/C,kBAAkB,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE;aAC3E,CAAC;YACF,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;gBACf,KAAK,CAAC,IAAI,CACR,wBAAwB,CAAC,CAAC,QAAQ,CAAC,SAAS,UAAU,CAAC,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,CAClG,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;gBACjC,MAAM,GAAG,GACP,CAAC,CAAC,YAAY,CAAC,MAAM,GAAG,GAAG;oBACzB,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK;oBACtC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;gBACrB,KAAK,CAAC,IAAI,CAAC,sBAAsB,GAAG,GAAG,CAAC,CAAC;YAC3C,CAAC;YACD,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"get-node.js","sourceRoot":"","sources":["../../src/tools/get-node.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-string.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetString(server: McpServer): void;
+//# sourceMappingURL=get-string.d.ts.map

package/dist/tools/get-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-string.d.ts","sourceRoot":"","sources":["../../src/tools/get-string.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAsLvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsGzD"}

package/dist/tools/get-string.js

@@ -0,0 +1,223 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import { z } from 'zod';
+import { getSnapshot } from '../heap-state.js';
+import { formatBytes, formatNodeInline, errorResult, toolResult, } from '../utils.js';
+function resolveStringValue(node, maxLen) {
+    // Try the standard stringValue API first
+    if (node.isString) {
+        const strNode = node.toStringNode();
+        if (strNode) {
+            const val = strNode.stringValue;
+            if (val.length > maxLen) {
+                return {
+                    value: val.slice(0, maxLen),
+                    truncated: true,
+                    encoding: 'direct',
+                };
+            }
+            return { value: val, truncated: false, encoding: 'direct' };
+        }
+    }
+    // For concatenated strings, walk the first/second tree
+    if (node.name === '(concatenated string)' ||
+        node.type === 'concatenated string') {
+        return resolveConcatenatedString(node, maxLen);
+    }
+    // For sliced strings, resolve the parent and extract the slice
+    if (node.name === '(sliced string)' || node.type === 'sliced string') {
+        return resolveSlicedString(node, maxLen);
+    }
+    // For cons strings (another name for concatenated)
+    if (node.name === '(cons string)') {
+        return resolveConcatenatedString(node, maxLen);
+    }
+    return { value: '', truncated: false, encoding: 'unknown' };
+}
+function resolveConcatenatedString(node, maxLen) {
+    const parts = [];
+    let totalLen = 0;
+    let truncated = false;
+    function walk(n) {
+        if (truncated)
+            return;
+        // If this node is a flat string, get its value directly
+        if (n.isString) {
+            const strNode = n.toStringNode();
+            if (strNode) {
+                const val = strNode.stringValue;
+                if (totalLen + val.length > maxLen) {
+                    parts.push(val.slice(0, maxLen - totalLen));
+                    totalLen = maxLen;
+                    truncated = true;
+                    return;
+                }
+                parts.push(val);
+                totalLen += val.length;
+                return;
+            }
+        }
+        // Walk first and second edges for concatenated/cons strings
+        let first = null;
+        let second = null;
+        for (const edge of n.references) {
+            const name = String(edge.name_or_index);
+            if (name === 'first')
+                first = edge.toNode;
+            else if (name === 'second')
+                second = edge.toNode;
+        }
+        if (first)
+            walk(first);
+        if (second)
+            walk(second);
+    }
+    walk(node);
+    return { value: parts.join(''), truncated, encoding: 'concatenated' };
+}
+function resolveSlicedString(node, maxLen) {
+    // Sliced strings have a "parent" edge pointing to the original string
+    for (const edge of node.references) {
+        const name = String(edge.name_or_index);
+        if (name === 'parent') {
+            const parent = edge.toNode;
+            const resolved = resolveStringValue(parent, maxLen * 2);
+            // The sliced string is a substring of the parent.
+            // V8 stores offset and length internally, but the snapshot API
+            // exposes the stringValue directly via toStringNode() which should
+            // already handle this. If we got here, toStringNode() didn't work,
+            // so return the parent's full value as context.
+            return {
+                value: resolved.value,
+                truncated: resolved.truncated,
+                encoding: `sliced (from parent @${parent.id}, ${formatBytes(parent.self_size)})`,
+            };
+        }
+    }
+    return { value: '', truncated: false, encoding: 'sliced (parent not found)' };
+}
+function getStringStructure(node, depth = 0, maxDepth = 5) {
+    const lines = [];
+    const indent = '  '.repeat(depth);
+    if (depth > maxDepth) {
+        lines.push(`${indent}… (max depth reached)`);
+        return lines;
+    }
+    const typeLabel = node.type === 'concatenated string'
+        ? 'concat'
+        : node.name === '(concatenated string)'
+            ? 'concat'
+            : node.name === '(cons string)'
+                ? 'cons'
+                : node.name === '(sliced string)'
+                    ? 'sliced'
+                    : node.isString
+                        ? 'flat'
+                        : node.type;
+    if (node.isString &&
+        node.type !== 'concatenated string' &&
+        node.name !== '(concatenated string)' &&
+        node.name !== '(cons string)') {
+        const strNode = node.toStringNode();
+        if (strNode) {
+            const val = strNode.stringValue;
+            const preview = val.length > 60 ? val.slice(0, 60) + '…' : val;
+            lines.push(`${indent}@${node.id} [${typeLabel}] "${preview}" (${formatBytes(node.self_size)})`);
+            return lines;
+        }
+    }
+    lines.push(`${indent}@${node.id} [${typeLabel}] (${formatBytes(node.self_size)})`);
+    for (const edge of node.references) {
+        const name = String(edge.name_or_index);
+        if (name === 'first' || name === 'second' || name === 'parent') {
+            lines.push(`${indent}  ${name}:`);
+            lines.push(...getStringStructure(edge.toNode, depth + 2, maxDepth));
+        }
+    }
+    return lines;
+}
+export function registerGetString(server) {
+    server.tool('memlab_get_string', 'Resolve any V8 string node to its full text value. Handles all V8 string encodings: ' +
+        'flat strings, concatenated strings (ConsString with first/second tree), sliced strings ' +
+        '(substring of a parent), and cons strings. Returns the resolved text value and optionally ' +
+        'shows the internal string tree structure. Essential when investigating event names, log ' +
+        'messages, or error strings that V8 stores as concatenated string trees rather than flat strings.', {
+        node_id: z.number().describe('The numeric ID of the string node'),
+        max_length: z
+            .number()
+            .optional()
+            .default(10000)
+            .describe('Maximum characters to return (default 10000). Use higher values for full log messages.'),
+        show_structure: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Show the internal string tree structure (concatenation tree, parent references). Useful for understanding why a large parent string is kept alive by a small sliced substring.'),
+    }, async ({ node_id, max_length, show_structure }) => {
+        try {
+            const snapshot = getSnapshot();
+            const node = snapshot.getNodeById(node_id);
+            if (!node) {
+                return errorResult(`Node with id ${node_id} not found`);
+            }
+            const isStringType = node.isString ||
+                node.type === 'concatenated string' ||
+                node.type === 'sliced string' ||
+                node.name === '(concatenated string)' ||
+                node.name === '(cons string)' ||
+                node.name === '(sliced string)' ||
+                node.type === 'string';
+            if (!isStringType) {
+                return toolResult(`Node @${node_id} is not a string node (type: "${node.type}", name: "${node.name}"). ` +
+                    'This tool is designed for string, concatenated string, sliced string, and cons string nodes.\n\n' +
+                    'If you need to read a string property of an object, use `memlab_get_property` to navigate to the string node first.');
+            }
+            const resolved = resolveStringValue(node, max_length);
+            const lines = [];
+            lines.push(`**Node:** ${formatNodeInline(node.id, node.name, node.type, node.self_size)}`);
+            lines.push(`**Self Size:** ${formatBytes(node.self_size)} | **Retained Size:** ${formatBytes(node.retainedSize)}`);
+            lines.push(`**Encoding:** ${resolved.encoding}`);
+            lines.push(`**Length:** ${resolved.value.length}${resolved.truncated ? ` (truncated from longer value, use max_length to see more)` : ''} characters`);
+            lines.push('');
+            lines.push('**Value:**');
+            lines.push('```');
+            lines.push(resolved.value);
+            lines.push('```');
+            if (show_structure) {
+                lines.push('');
+                lines.push('**String Tree Structure:**');
+                lines.push('```');
+                lines.push(...getStringStructure(node));
+                lines.push('```');
+            }
+            // Show referrers for context
+            const referrerContexts = [];
+            let refCount = 0;
+            for (const edge of node.referrers) {
+                if (refCount >= 5)
+                    break;
+                if (edge.fromNode.id <= 3)
+                    continue;
+                referrerContexts.push(`- \`${String(edge.name_or_index)}\` on @${edge.fromNode.id} \`${edge.fromNode.name}\` (${edge.fromNode.type})`);
+                refCount++;
+            }
+            if (referrerContexts.length > 0) {
+                lines.push('');
+                lines.push('**Referenced by:**');
+                lines.push(...referrerContexts);
+            }
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=get-string.js.map

package/dist/tools/get-string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-string.js","sourceRoot":"","sources":["../../src/tools/get-string.ts"],"names":[],"mappings":"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"}

package/dist/tools/get-value.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGetValue(server: McpServer): void;
+//# sourceMappingURL=get-value.d.ts.map

package/dist/tools/get-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-value.d.ts","sourceRoot":"","sources":["../../src/tools/get-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA4EvE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmIxD"}