@memlab/mcp-server 2.3.0 → 2.52.0

package/dist/tools/sliced-strings.js.map

@@ -1 +1 @@
-{"version":3,"file":"sliced-strings.js","sourceRoot":"","sources":["../../src/tools/sliced-strings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sliced-strings.js","sourceRoot":"","sources":["../../src/tools/sliced-strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,UAAU,GACX,MAAM,aAAa,CAAC;AAWrB,MAAM,UAAU,qBAAqB,CAAC,MAAiB;IACrD,MAAM,CAAC,IAAI,CACT,uBAAuB,EACvB,qaAAqa,EACra;QACE,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,yDAAyD,CAAC;QACtE,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,8GAA8G,CAC/G;KACJ,EACD,KAAK,EAAE,EAAC,KAAK,EAAE,eAAe,EAAC,EAAE,EAAE;QACjC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAE/B,IAAI,WAAW,GAAG,CAAC,CAAC;YACpB,IAAI,WAAW,GAAG,CAAC,CAAC;YACpB,IAAI,eAAe,GAAG,CAAC,CAAC;YACxB,IAAI,eAAe,GAAG,CAAC,CAAC;YAExB,mCAAmC;YACnC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;YAEjD,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;gBAC5B,gEAAgE;gBAChE,gEAAgE;gBAChE,iEAAiE;gBACjE,+BAA+B;gBAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,KAAK,eAAe,CAAC;gBAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,KAAK,qBAAqB,CAAC;gBAErD,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ;oBAAE,OAAO;gBAEnC,IAAI,QAAQ,EAAE,CAAC;oBACb,WAAW,EAAE,CAAC;oBACd,eAAe,IAAI,IAAI,CAAC,SAAS,CAAC;gBACpC,CAAC;qBAAM,CAAC;oBACN,WAAW,EAAE,CAAC;oBACd,eAAe,IAAI,IAAI,CAAC,SAAS,CAAC;gBACpC,CAAC;gBAED,mEAAmE;gBACnE,kEAAkE;gBAClE,+DAA+D;gBAC/D,gCAAgC;gBAChC,IAAI,CAAC,QAAQ;oBAAE,OAAO;gBACtB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;oBACnC,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,QAAQ;wBAAE,SAAS;oBACtD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;oBAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ;wBAAE,SAAS;oBAE/B,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBAC1C,IAAI,QAAQ,EAAE,CAAC;wBACb,QAAQ,CAAC,gBAAgB,EAAE,CAAC;wBAC5B,QAAQ,CAAC,iBAAiB,IAAI,IAAI,CAAC,SAAS,CAAC;oBAC/C,CAAC;yBAAM,CAAC;wBACN,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE;4BACvB,EAAE,EAAE,MAAM,CAAC,EAAE;4BACb,IAAI,EAAE,MAAM,CAAC,IAAI;4BACjB,SAAS,EAAE,MAAM,CAAC,SAAS;4BAC3B,aAAa,EAAE,MAAM,CAAC,YAAY;4BAClC,gBAAgB,EAAE,CAAC;4BACnB,iBAAiB,EAAE,IAAI,CAAC,SAAS;yBAClC,CAAC,CAAC;oBACL,CAAC;oBACD,MAAM;gBACR,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,IAAI,WAAW,KAAK,CAAC,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;gBAC3C,OAAO,UAAU,CACf,0DAA0D,CAC3D,CAAC;YACJ,CAAC;YAED,MAAM,UAAU,GAAG,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;YAC3C,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAM,CACxC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,EAC7B,CAAC,CACF,CAAC;YAEF,wEAAwE;YACxE,yEAAyE;YACzE,yEAAyE;YACzE,yEAAyE;YACzE,yEAAyE;YACzE,4DAA4D;YAC5D,IAAI,OAAO,GAAG,UAAU,CAAC;YACzB,IAAI,YAAY,GAAG,EAAE,CAAC;YACtB,IAAI,eAAe,IAAI,IAAI,EAAE,CAAC;gBAC5B,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAChC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,eAAe,CACpC,CAAC;gBACF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,OAAO,GAAG,QAAQ,CAAC;gBACrB,CAAC;qBAAM,CAAC;oBACN,YAAY,GAAG,iBAAiB,WAAW,CAAC,eAAe,CAAC,gCAAgC,CAAC;gBAC/F,CAAC;YACH,CAAC;YACD,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;YACjE,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAE3C,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CACR,uBAAuB,YAAY,CAAC,WAAW,CAAC,WAAW,WAAW,CAAC,eAAe,CAAC,aAAa,CACrG,CAAC;YACF,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;gBACpB,KAAK,CAAC,IAAI,CACR,6BAA6B,YAAY,CAAC,WAAW,CAAC,WAAW,WAAW,CAAC,eAAe,CAAC,aAAa,CAC3G,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,IAAI,CACR,yCAAyC,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACxE,CAAC;YACF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,KAAK,CAAC,IAAI,CACR,4CAA4C,WAAW,CAAC,gBAAgB,CAAC,WAAW,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,4FAA4F,CAChN,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAEf,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,OAAO,GAAG;oBACd,WAAW;oBACX,SAAS;oBACT,aAAa;oBACb,UAAU;oBACV,aAAa;oBACb,aAAa;iBACd,CAAC;gBACF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBACxC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC/B,IAAI,CAAC,CAAC,EAAE,EAAE;oBACV,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC;oBACnD,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;oBACxB,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC;oBAC5B,YAAY,CAAC,CAAC,CAAC,gBAAgB,CAAC;oBAChC,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC;iBACjC,CAAC,CAAC;gBACH,KAAK,CAAC,IAAI,CACR,gDAAgD,YAAY,EAAE,CAC/D,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACf,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;gBAEpD,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,IAAI,GAAG,IAAI,CAAC,CAAC;gBACnE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvB,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;oBAChE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACf,KAAK,CAAC,IAAI,CACR,OAAO,OAAO,CAAC,MAAM,6BAA6B,WAAW,CAAC,UAAU,CAAC,iMAAiM,CAC3Q,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,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"}

package/dist/tools/snapshot-header.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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';
+/**
+ * memlab_snapshot_header — peek a snapshot's header WITHOUT the dominator pass.
+ *
+ * The expensive/risky part of memlab_load_snapshot is the dominator-tree
+ * computation (uninterruptible, super-linear, can wedge/OOM the server). This
+ * tool skips it entirely: it resolves + fetches the file (reusing any cached
+ * download, so a follow-up real load doesn't re-download), reads the node/edge
+ * counts and capture time from the file header, and reports whether the capture
+ * fits under the current auto-scaled load ceiling.
+ *
+ * The point is to end the "attempt load → refused on counts → hand-compute
+ * density → re-query Scuba for a smaller file → retry" loop that dominated a
+ * server-snapshot sweep (feedback round 7 §1/§2): peek a candidate, read its
+ * exact counts + this-app density + the estimated max-loadable file size, then
+ * pick the right capture in one step.
+ */
+export declare function registerSnapshotHeader(server: McpServer): void;
+//# sourceMappingURL=snapshot-header.d.ts.map

package/dist/tools/snapshot-header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-header.d.ts","sourceRoot":"","sources":["../../src/tools/snapshot-header.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAcvE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwH9D"}

package/dist/tools/snapshot-header.js

@@ -0,0 +1,111 @@
+/**
+ * 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 fs from 'fs';
+import path from 'path';
+import { z } from 'zod';
+import { resolveSnapshotPath, peekSnapshotCounts, computeDefaultCeilings, estimateMaxLoadableMB, extractCaptureTime, DEFAULT_MANIFOLD_BUCKET, } from './load-snapshot.js';
+import { formatBytes, formatNumber, errorResult, textResult } from '../utils.js';
+/**
+ * memlab_snapshot_header — peek a snapshot's header WITHOUT the dominator pass.
+ *
+ * The expensive/risky part of memlab_load_snapshot is the dominator-tree
+ * computation (uninterruptible, super-linear, can wedge/OOM the server). This
+ * tool skips it entirely: it resolves + fetches the file (reusing any cached
+ * download, so a follow-up real load doesn't re-download), reads the node/edge
+ * counts and capture time from the file header, and reports whether the capture
+ * fits under the current auto-scaled load ceiling.
+ *
+ * The point is to end the "attempt load → refused on counts → hand-compute
+ * density → re-query Scuba for a smaller file → retry" loop that dominated a
+ * server-snapshot sweep (feedback round 7 §1/§2): peek a candidate, read its
+ * exact counts + this-app density + the estimated max-loadable file size, then
+ * pick the right capture in one step.
+ */
+export function registerSnapshotHeader(server) {
+    server.tool('memlab_snapshot_header', "Peek a .heapsnapshot's header (node/edge counts, capture time, file size) WITHOUT loading it — no dominator pass, so it can never wedge or OOM the server the way a full memlab_load_snapshot can. Reports whether the capture fits under the current auto-scaled load ceiling, this app's node/edge density, and — when it doesn't fit — the estimated largest same-app capture that WOULD fit, so you can select a loadable snapshot in one step instead of attempting an oversized load. Accepts a local absolute path, a manifold:// URL, or a bare snapshot filename (resolved against the nest_server_nodejs_heap_snapshots bucket and fetched automatically; the download is reused by a subsequent memlab_load_snapshot). Use this to triage which capture in a size band to load before committing to the expensive load.", {
+        file_path: z
+            .string()
+            .describe('A local absolute path to a .heapsnapshot file, a manifold:// URL (manifold://bucket/key), or a bare snapshot filename to fetch from the nest_server_nodejs_heap_snapshots bucket.'),
+    }, async ({ file_path }) => {
+        try {
+            let resolved;
+            let fetchedFrom = null;
+            try {
+                const r = resolveSnapshotPath(file_path);
+                resolved = r.localPath;
+                fetchedFrom = r.fetchedFrom;
+            }
+            catch (fetchErr) {
+                const msg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
+                return errorResult(new Error(`Failed to fetch "${file_path}" from Manifold: ${msg}\n` +
+                    `Ensure the 'manifold' CLI is installed and you have access to the bucket, ` +
+                    `or pass a local absolute path instead.`));
+            }
+            if (!fs.existsSync(resolved)) {
+                return errorResult(new Error(`File not found: ${resolved}` +
+                    (file_path.includes('/')
+                        ? ''
+                        : ` (also tried fetching "${file_path}" from the ${DEFAULT_MANIFOLD_BUCKET} bucket)`)));
+            }
+            const fileStat = fs.statSync(resolved);
+            const fileSizeMB = fileStat.size / (1024 * 1024);
+            const fileName = path.basename(fetchedFrom ?? file_path.replace(/^manifold:\/\//, ''));
+            const counts = peekSnapshotCounts(resolved);
+            const ceilings = computeDefaultCeilings();
+            const lines = [];
+            lines.push(`Snapshot header: ${fileName}`);
+            if (fetchedFrom)
+                lines.push(`Fetched from Manifold: ${fetchedFrom}`);
+            lines.push(`File size: ${formatBytes(fileStat.size)}`);
+            if (!counts) {
+                lines.push(`Node/edge counts: not found in the header prefix — cannot assess loadability without a full load.`);
+                return textResult(lines.join('\n'));
+            }
+            lines.push(`Nodes: ${formatNumber(counts.nodeCount)}   Edges: ${formatNumber(counts.edgeCount)}`);
+            const captured = extractCaptureTime(fileName);
+            if (captured) {
+                const iso = captured.toISOString().slice(0, 10);
+                const ageDays = Math.max(0, Math.floor((Date.now() - captured.getTime()) / 86_400_000));
+                lines.push(`Captured ${iso} (${ageDays} day(s) ago) — if you find a candidate, verify the fix wasn't already deployed since then before writing one.`);
+            }
+            const heapNote = ceilings.heapLimitMB > 0
+                ? ` (server heap ~${formatNumber(ceilings.heapLimitMB)} MB via --max-old-space-size)`
+                : '';
+            lines.push(`Current load ceiling: ${formatNumber(ceilings.maxNodes)} nodes / ${formatNumber(ceilings.maxEdges)} edges${heapNote}.`);
+            const nodesPerMB = Math.round(counts.nodeCount / fileSizeMB);
+            const edgesPerMB = Math.round(counts.edgeCount / fileSizeMB);
+            const fitsNodes = counts.nodeCount <= ceilings.maxNodes;
+            const fitsEdges = counts.edgeCount <= ceilings.maxEdges;
+            if (fitsNodes && fitsEdges) {
+                lines.push(`✓ Loadable — under the ceiling on both nodes and edges. Load it with memlab_load_snapshot({file_path: "${file_path}"}); the fetched file is cached so it won't re-download.`);
+            }
+            else {
+                const over = !fitsNodes && !fitsEdges
+                    ? 'nodes and edges'
+                    : !fitsEdges
+                        ? 'edges'
+                        : 'nodes';
+                const estMB = estimateMaxLoadableMB(counts, fileSizeMB, {
+                    maxNodes: ceilings.maxNodes,
+                    maxEdges: ceilings.maxEdges,
+                });
+                lines.push(`✗ Over the ceiling on ${over}. Density: ${formatNumber(nodesPerMB)} nodes/MB, ${formatNumber(edgesPerMB)} edges/MB.` +
+                    (estMB != null
+                        ? ` For this app the ceiling corresponds to roughly a ≤${formatNumber(estMB)} MB capture — select a smaller snapshot below that size (then memlab_snapshot_header it to confirm), or force the load with memlab_load_snapshot({force: true}) accepting a long, uninterruptible dominator pass.`
+                        : ` Select a smaller snapshot, or force the load with memlab_load_snapshot({force: true}).`));
+            }
+            return textResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=snapshot-header.js.map

package/dist/tools/snapshot-header.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"string-patterns.d.ts","sourceRoot":"","sources":["../../src/tools/string-patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAiBvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+H9D"}
+{"version":3,"file":"string-patterns.d.ts","sourceRoot":"","sources":["../../src/tools/string-patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAiBvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAgI9D"}

package/dist/tools/string-patterns.js

@@ -8,7 +8,7 @@
  * @oncall memory_lab
  */
 import { z } from 'zod';
-import { getSnapshot } from '../heap-state.js';
+import { getSnapshot, isLightSnapshot } from '../heap-state.js';
 import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
 function extractPrefix(value, prefixLen) {
     if (value.length <= prefixLen)
@@ -38,7 +38,8 @@ export function registerStringPatterns(server) {
             .describe('Maximum number of groups to return (default 20)'),
     }, async ({ prefix_length, min_count, min_total_size, limit }) => {
         try {
-            const snapshot = getSnapshot();
+            const snapshot = getSnapshot({ allowLight: true });
+            const light = isLightSnapshot();
             const groups = new Map();
             snapshot.nodes.forEach(node => {
                 if (node.type !== 'string')
@@ -86,7 +87,7 @@ export function registerStringPatterns(server) {
                 'Prefix',
                 'Count',
                 'Total Size',
-                'Retained',
+                light ? 'Retained (n/a)' : 'Retained',
                 'Len Range',
                 'Examples',
             ];
@@ -100,7 +101,7 @@ export function registerStringPatterns(server) {
                     displayPrefix,
                     formatNumber(g.count),
                     formatBytes(g.total_self_size),
-                    formatBytes(g.total_retained_size),
+                    light ? 'n/a (light)' : formatBytes(g.total_retained_size),
                     lenRange,
                     g.example_ids.map(id => `@${id}`).join(', '),
                 ];

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

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

package/dist/tools/tools-index.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 registerToolsIndex(server: McpServer): void;
+//# sourceMappingURL=tools-index.d.ts.map

package/dist/tools/tools-index.d.ts.map

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

package/dist/tools/tools-index.js

@@ -0,0 +1,342 @@
+/**
+ * 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 { listToolNames } from '../tool-registry.js';
+import { errorResult, makeNamePatternTest, textResult } from '../utils.js';
+const GROUPS = [
+    {
+        question: 'What is this heap actually made of?',
+        tools: [
+            [
+                'memlab_app_heap',
+                'START HERE on an unfamiliar app: splits the heap into application data vs bundle source vs V8 machinery. On one app this showed ~55% of the heap was JS bundle source, which reframed every number that followed.',
+            ],
+            [
+                'memlab_quick_diagnosis',
+                'One call for summary + biggest objects + class histogram + duplicated strings.',
+            ],
+            [
+                'memlab_snapshot_summary',
+                'Node/edge counts and totals, when you only need the shape of the capture.',
+            ],
+            [
+                'memlab_class_histogram',
+                'Counts and sizes per class; `name_pattern` answers "is class X present?" in one row.',
+            ],
+            ['memlab_largest_objects', 'The single biggest retainers, ranked.'],
+            [
+                'memlab_shape_histogram',
+                'Groups plain objects by their property set — finds record types the class name hides behind `Object`.',
+            ],
+            [
+                'memlab_object_cost_breakdown',
+                'Where one class’s bytes actually go (self vs properties vs elements).',
+            ],
+        ],
+    },
+    {
+        question: 'Is anything growing — and is it a leak?',
+        tools: [
+            [
+                'memlab_leak_report',
+                'The ladder verdict: per-class growth across an ordered set of snapshots.',
+            ],
+            [
+                'memlab_sequence_analysis',
+                'Per-class trend across a ladder, with artifact families flagged.',
+            ],
+            [
+                'memlab_collection_trend',
+                'Entry counts of NAMED collections across a ladder, with growth per interaction cycle.',
+            ],
+            [
+                'memlab_population_diff',
+                'Whether two snapshots hold the same POPULATION or just the same count — equal totals are not identity.',
+            ],
+            [
+                'memlab_growth_signals',
+                'Single-snapshot signals that something is accumulating.',
+            ],
+            [
+                'memlab_diff_snapshots',
+                'Raw per-class deltas between two resident snapshots.',
+            ],
+            [
+                'memlab_hypothesis',
+                'State a leak hypothesis and have it checked against the ladder instead of arguing it.',
+            ],
+            [
+                'memlab_verify_fix',
+                'Did the fix work? Compares per-cycle growth RATES between a before ladder and an after ladder.',
+            ],
+            [
+                'memlab_ladder',
+                'Name a ladder once and reference it as `ladder:<name>` from every trend tool.',
+            ],
+        ],
+    },
+    {
+        question: 'Who owns the growth / why is X retained?',
+        tools: [
+            [
+                'memlab_explain_delta',
+                'WHERE a heap grew, attributed to the object that owns the new bytes rather than to what they are.',
+            ],
+            [
+                'memlab_dominator_chain',
+                'From one node up to the accountable application object.',
+            ],
+            [
+                'memlab_dominator_attribution',
+                'Given several candidate retainers, how much each one actually dominates — a zero refutes a hypothesis.',
+            ],
+            ['memlab_retainer_trace', 'The shortest retainer path for one node.'],
+            [
+                'memlab_retainer_summary',
+                'Retainer paths across many instances, clustered by shape.',
+            ],
+            ['memlab_referrer_summary', 'Who points at this, grouped by edge.'],
+            [
+                'memlab_pinch_points',
+                'Single objects whose release would free the most.',
+            ],
+            ['memlab_dominator_subtree', 'What one object holds, expanded downward.'],
+            [
+                'memlab_retainer_layers',
+                'The retention structure around a node, layer by layer.',
+            ],
+            ['memlab_trace_dominators', 'Dominator path for a set of nodes at once.'],
+        ],
+    },
+    {
+        question: 'Is it real, or a measurement artifact?',
+        tools: [
+            [
+                'memlab_dev_artifacts',
+                'Memory retained ONLY by dev/automation roots — DevTools, extensions, React Fast Refresh, the a11y cache. Run before calling anything a production leak.',
+            ],
+            [
+                'memlab_explain_delta',
+                'Counts the OTHER artifact family — V8 JIT warmup — which dev_artifacts does not. Read both.',
+            ],
+            [
+                'memlab_check_health',
+                'Prioritized triage that separates likely-real from likely-noise.',
+            ],
+        ],
+    },
+    {
+        question: 'Detached DOM and event listeners',
+        tools: [
+            [
+                'memlab_detached_dom',
+                'Detached nodes, with a pinned-vs-GC-eligible split; `group_by:"dominator"` groups by what a fix would actually free.',
+            ],
+            ['memlab_event_listener_leaks', 'Listeners that outlived their target.'],
+            ['memlab_event_registry', 'What is registered on what.'],
+        ],
+    },
+    {
+        question: 'Collections and caches',
+        tools: [
+            [
+                'memlab_cache_analysis',
+                'Unbounded or oversized caches in one snapshot.',
+            ],
+            [
+                'memlab_stale_collections',
+                'Collections holding entries nothing else references.',
+            ],
+            [
+                'memlab_collection_trend',
+                'The same collections tracked ACROSS a ladder.',
+            ],
+            [
+                'memlab_map_entries',
+                'Enumerate a Map/Set correctly (SMI gaps and browser slot typing handled).',
+            ],
+            ['memlab_weakmap_entries', 'Enumerate a WeakMap.'],
+            [
+                'memlab_array_group_by',
+                'Group an array’s elements by a property to see what is piling up.',
+            ],
+            [
+                'memlab_property_distribution',
+                'Cardinality and top values of one property across instances.',
+            ],
+        ],
+    },
+    {
+        question: 'Strings and duplication',
+        tools: [
+            [
+                'memlab_intern_opportunities',
+                'What an intern pool would actually reclaim, grouped by property x parent shape. Start here for an interning decision.',
+            ],
+            ['memlab_duplicated_strings', 'The raw per-value duplication table.'],
+            [
+                'memlab_string_patterns',
+                'Group strings by prefix to find families (URLs, ids, payloads).',
+            ],
+            ['memlab_sliced_strings', 'Substrings pinning huge parents.'],
+            [
+                'memlab_duplicate_objects',
+                'The same question for objects rather than strings.',
+            ],
+            ['memlab_search_strings', 'Find a string value in the heap.'],
+            ['memlab_get_string', 'Read one string node’s value.'],
+        ],
+    },
+    {
+        question: 'Inspect or find specific objects',
+        tools: [
+            [
+                'memlab_find_nodes_by_class',
+                'By exact class name, or by `name_pattern` regex/substring.',
+            ],
+            ['memlab_search_nodes', 'By name/type/size predicates.'],
+            ['memlab_find_by_property', 'By a property name/value.'],
+            ['memlab_find_by_shape', 'By property set.'],
+            ['memlab_match_object', 'By a structural pattern.'],
+            ['memlab_get_node', 'One node’s details.'],
+            ['memlab_object_shape', 'One object’s properties and their sizes.'],
+            ['memlab_get_references', 'Outgoing edges.'],
+            ['memlab_get_referrers', 'Incoming edges.'],
+            ['memlab_get_property', 'One property of one object.'],
+            ['memlab_get_value', 'A scalar value, where the format allows it.'],
+            [
+                'memlab_closure_inspection',
+                'What a closure captured, and what that costs.',
+            ],
+            ['memlab_global_variables', 'What is hanging off the global object.'],
+            ['memlab_aggregate', 'Sum/count over a node set.'],
+            ['memlab_for_each', 'Run one tool over many nodes.'],
+        ],
+    },
+    {
+        question: 'None of the above — ask the heap directly',
+        tools: [
+            [
+                'memlab_eval',
+                'Arbitrary JS over the snapshot, with indexed helpers (`byClass`, `iterByType`, `classCounts`, `entries`, `dominates`, `pathBetween`). Use `mode:"describe_env"` for the calling convention. This is the escape hatch when no fixed-shape tool matches the question.',
+            ],
+            [
+                'memlab_auto_investigate',
+                'When you do not yet have a question: runs the standard deep-dive and reports what it found.',
+            ],
+            [
+                'memlab_tools',
+                'This index. Filter it with `question` or look a tool up with `tool`.',
+            ],
+        ],
+    },
+    {
+        question: 'Session, batching and write-ups',
+        tools: [
+            [
+                'memlab_load_snapshot',
+                'Load a local path, a manifold:// URL, or a bare Nest filename.',
+            ],
+            [
+                'memlab_snapshots',
+                'List / switch / unload resident snapshots; set session output controls.',
+            ],
+            [
+                'memlab_batch',
+                'Several tools against ONE load — the load is the expensive part.',
+            ],
+            [
+                'memlab_snapshot_header',
+                'Node/edge counts WITHOUT loading the snapshot.',
+            ],
+            [
+                'memlab_server_status',
+                'Confirm the server is alive; returns instantly.',
+            ],
+            [
+                'memlab_finding_index',
+                'Record findings as you go so the write-up is not reconstructed from memory.',
+            ],
+            ['memlab_reports', 'Render the findings.'],
+            ['memlab_hunt_report', 'Render a leak-hunt run.'],
+            [
+                'memlab_analyze_run',
+                'Point at a run.json and get the WHOLE analysis protocol — trend, owner attribution, population diff, artifact classification, caveats — in one call.',
+            ],
+        ],
+    },
+];
+export function registerToolsIndex(server) {
+    server.tool('memlab_tools', 'Index of every memlab tool, grouped by the QUESTION it answers ("what is this heap made of", "is anything growing", "why is X retained", "is it real or an artifact", …). Call this first when you are not sure which tool fits, or when you suspect the server has something better than the one you were about to use — it costs one call and lists tools whose schemas have not been fetched yet, which is otherwise impossible to discover under deferred tool loading. Pass `question` to filter to matching groups, or `tool` to find which group a tool belongs to.', {
+        question: z
+            .string()
+            .optional()
+            .describe('Filter to groups matching this text (case-insensitive regex, substring fallback) — e.g. "growing", "retained", "artifact", "string".'),
+        tool: z
+            .string()
+            .optional()
+            .describe('Show the group(s) containing this tool name (with or without the memlab_ prefix).'),
+    }, async ({ question, tool }) => {
+        try {
+            const registered = new Set(listToolNames());
+            const wanted = tool
+                ? tool.startsWith('memlab_')
+                    ? tool
+                    : `memlab_${tool}`
+                : null;
+            const matchesQuestion = makeNamePatternTest(question);
+            let groups = GROUPS;
+            if (wanted != null) {
+                groups = groups.filter(g => g.tools.some(([n]) => n === wanted));
+                if (groups.length === 0) {
+                    return textResult(`\`${wanted}\` is not in the index${registered.has(wanted) ? ' (but it IS registered — the index is missing an entry; see the uncategorized list below)' : ' and is not a registered tool'}.\n\nRegistered tools: ${[...registered].join(', ')}`);
+                }
+            }
+            if (question != null) {
+                groups = groups.filter(g => matchesQuestion(g.question) ||
+                    g.tools.some(([n, w]) => matchesQuestion(n) || matchesQuestion(w)));
+            }
+            const lines = [
+                `# memlab tools by question (${registered.size} registered)`,
+                '',
+            ];
+            if (groups.length === 0) {
+                lines.push(`No group matches ${question != null ? `"${question}"` : 'that filter'}. Call \`memlab_tools\` with no arguments for the full index.`);
+                return textResult(lines.join('\n'));
+            }
+            for (const g of groups) {
+                lines.push(`## ${g.question}`, '');
+                for (const [name, when] of g.tools) {
+                    // A name in the index that is no longer registered is worse than a
+                    // missing one: it sends the caller after a tool that will fail.
+                    const missing = registered.has(name) ? '' : ' _(not registered)_';
+                    lines.push(`- \`${name}\`${missing} — ${when}`);
+                }
+                lines.push('');
+            }
+            // Drift guard. The index is hand-written for usefulness, so a newly
+            // added tool would otherwise be invisible here — which is the exact
+            // failure this tool exists to fix, reproduced one level up.
+            if (question == null && wanted == null) {
+                const indexed = new Set(GROUPS.flatMap(g => g.tools.map(([n]) => n)));
+                const uncategorized = [...registered].filter(n => !indexed.has(n));
+                if (uncategorized.length > 0) {
+                    lines.push('## Not yet categorized', '', `These are registered but missing from the index above: ${uncategorized.map(n => `\`${n}\``).join(', ')}. Their own descriptions are the only documentation.`, '');
+                }
+            }
+            lines.push('_A tool listed under several questions is genuinely useful for each. Where a group is ordered, the first entry is the one to try first._');
+            return textResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=tools-index.js.map

package/dist/tools/tools-index.js.map

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

package/dist/tools/verify-fix.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { IHeapSnapshot } from '@memlab/core';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+type MetricKind = 'collection_length' | 'class_count' | 'pending_chain';
+/**
+ * Measure the metric on one parsed snapshot. One scalar per snapshot is the
+ * whole point: the arms are compared on a rate, and a rate needs a number per
+ * rung, not a report.
+ */
+export declare function measureMetric(snapshot: IHeapSnapshot, kind: MetricKind, locator: string, chainEdge: string): number;
+/** Growth per interaction cycle across an arm's ladder. */
+export declare function perCycleRate(values: number[], cycles: number): number;
+export declare function registerVerifyFix(server: McpServer): void;
+export {};
+//# sourceMappingURL=verify-fix.d.ts.map

package/dist/tools/verify-fix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-fix.d.ts","sourceRoot":"","sources":["../../src/tools/verify-fix.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAY,aAAa,EAAC,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAgBvE,KAAK,UAAU,GAAG,mBAAmB,GAAG,aAAa,GAAG,eAAe,CAAC;AAOxE;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,MAAM,CAuCR;AA4CD,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4JzD"}