@memlab/mcp-server 2.3.0 → 2.52.0

package/dist/tools/leak-report.js

@@ -0,0 +1,256 @@
+/**
+ * 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 memlabHeapAnalysis from '@memlab/heap-analysis';
+const { getFullHeapFromFile } = memlabHeapAnalysis;
+import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+import { artifactLabel } from '../artifact-classes.js';
+import { computeSequenceTrends, normalizeClassName, } from './sequence-analysis.js';
+import { collectDevRoots, computeReachableWithoutDevRoots, } from './dev-artifacts.js';
+import { getFirstNonFrameworkRetainer } from './detached-dom.js';
+// Nodes kept per candidate class for the retainer sample. Small on purpose: the
+// question is "what shape of thing holds these", and a handful of instances
+// answers it — walking thousands would cost more than the trend pass itself.
+const MAX_SAMPLES_PER_CLASS = 8;
+const RETAINER_SAMPLES = 3;
+// A class whose instances are overwhelmingly dev-root-retained is a measurement
+// artifact in production terms, whatever its growth curve looks like. Matches
+// the majority-not-any threshold intern_opportunities uses, for the same reason:
+// a class can legitimately mix a few console-held instances with real data.
+const DEV_ONLY_SHARE = 0.8;
+// Deliberately NOT a sum of retainedSize across the class: retained sizes
+// overlap wherever instances nest, so summing them reports figures larger than
+// the heap (measured: 5.9 GB of `Object` in a 200 MB heap). Net self-size delta
+// across the ladder is additive and is the growth the report is about anyway.
+function displayName(row) {
+    return row.name.length > 0 ? row.name : `(unnamed ${row.type})`;
+}
+function topRetainerLabel(ev) {
+    const counts = new Map();
+    for (const node of ev.samples.slice(0, RETAINER_SAMPLES)) {
+        const label = getFirstNonFrameworkRetainer(node);
+        counts.set(label, (counts.get(label) ?? 0) + 1);
+    }
+    let best = '(unknown)';
+    let bestCount = 0;
+    for (const [label, c] of counts) {
+        if (c > bestCount) {
+            best = label;
+            bestCount = c;
+        }
+    }
+    return best;
+}
+export function registerLeakReport(server) {
+    server.tool('memlab_leak_report', 'One-call leak triage across an ORDERED ladder of >=2 heap snapshots: runs the growth-trend pass, then gathers per-class EVIDENCE from the final snapshot and returns a single table — class, per-rung counts, Δ and Δ/cycle, how much of it is dev/automation-retained, the dominant retainer, and a verdict hint. ' +
+        'Exists because the trend pass alone cannot tell a leak from an artifact: every hunt then ran memlab_dev_artifacts and a retainer trace by hand on each grower and joined the three outputs mentally, which is the step that gets skipped right before something is reported as a production leak. Composes memlab_sequence_analysis with memlab_dev_artifacts and a retainer sample; costs one extra snapshot load (the last rung) on top of the ladder pass. ' +
+        'The verdict column is a HINT, not a conclusion — confirm a candidate with memlab_retainer_trace on the example node before calling it a leak. Paths may be local, manifold:// URLs, or bare filenames.', {
+        paths: z
+            .array(z.string())
+            .min(1)
+            .describe('Ordered list of >=2 snapshot paths (oldest first): local absolute paths, manifold:// URLs, or bare snapshot filenames. A single ["ladder:<name>"] entry expands to a ladder saved with memlab_ladder.'),
+        cycles: z
+            .number()
+            .optional()
+            .describe('Number of interaction cycles driven between the FIRST and LAST snapshot. When provided, a "Δ/cycle" column is reported — a per-cycle rate is what says whether growth scales with interaction, which a total cannot.'),
+        limit: z
+            .number()
+            .optional()
+            .default(10)
+            .describe('Maximum number of growing classes to gather evidence for (default 10).'),
+        min_growth_count: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Only consider classes whose net instance-count growth is at least this (default 50).'),
+        monotonic_only: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Only consider classes that grew at EVERY step (default false: grew-net classes are included and flagged as noisy).'),
+        include_artifacts: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Include classes that are known measurement artifacts (CDP inspector retention, V8 JIT warmup, Blink a11y caches, captured Error stacks). Default false: they are counted in a one-line summary instead of consuming evidence slots, since none of them is an app leak.'),
+        max_file_size_mb: z
+            .number()
+            .optional()
+            .describe('Per-file size ceiling in MB, matching memlab_load_snapshot / memlab_sequence_analysis defaults. Snapshots are loaded one at a time and dropped before the next.'),
+    }, async ({ paths, cycles, limit, min_growth_count, monotonic_only, include_artifacts, max_file_size_mb, }) => {
+        try {
+            const { steps, rows } = await computeSequenceTrends(paths, {
+                minGrowthCount: min_growth_count,
+                monotonicOnly: monotonic_only,
+                maxFileSizeMB: max_file_size_mb,
+                toolName: 'memlab_leak_report',
+            });
+            const n = steps.length;
+            const artifactRows = rows.filter(r => r.artifact != null);
+            const candidates = (include_artifacts ? rows : rows.filter(r => r.artifact == null)).slice(0, limit);
+            const heapNet = steps[n - 1].totalSize - steps[0].totalSize;
+            const lines = [
+                `## Leak report (${n} snapshots)`,
+                '',
+                `Heap self-size ${heapNet >= 0 ? 'grew' : 'shrank'} by ${formatBytes(Math.abs(heapNet))} across the ladder (${formatNumber(steps[0].nodeCount)} → ${formatNumber(steps[n - 1].nodeCount)} nodes).`,
+                '',
+            ];
+            if (n === 2) {
+                lines.push('> ⚠️ **Only 2 snapshots: "↑ every step" is monotonic by construction** and cannot separate a real trend from a single GC-band sample. Capture at least a third rung before treating anything here as a leak.', '');
+            }
+            if (candidates.length === 0) {
+                lines.push(`No non-artifact class grew by >= ${formatNumber(min_growth_count)} instances across the ladder — no unbounded-growth signal to report.`);
+                if (artifactRows.length > 0) {
+                    lines.push('', `> 🧹 ${formatNumber(artifactRows.length)} growing class(es) were known measurement artifacts (pass \`include_artifacts: true\` to see them).`);
+                }
+                return toolResult(lines.join('\n'));
+            }
+            // Evidence pass. The trend loop drops each graph before loading the
+            // next, so the final rung is re-opened here — one extra load, and the
+            // only way to ask retention questions about the classes the trend pass
+            // just identified.
+            const snapshot = await getFullHeapFromFile(steps[n - 1].localPath);
+            const devRoots = collectDevRoots(snapshot);
+            const reached = devRoots.byId.size > 0
+                ? computeReachableWithoutDevRoots(snapshot, devRoots)
+                : null;
+            const evidence = new Map();
+            for (const c of candidates) {
+                evidence.set(c.key, {
+                    total: 0,
+                    devOnly: 0,
+                    samples: [],
+                    example: null,
+                    exampleRetained: -1,
+                    anyExample: null,
+                });
+            }
+            snapshot.nodes.forEach(node => {
+                if (node.id <= 3)
+                    return;
+                // Must key exactly as buildHistogram does, normalization included, or
+                // per-instance Context/scope classes never match their trend row.
+                const ev = evidence.get(`${node.type}::${normalizeClassName(node.name)}`);
+                if (!ev)
+                    return;
+                ev.total++;
+                if (reached != null && reached[node.nodeIndex] === 0)
+                    ev.devOnly++;
+                if (ev.anyExample == null)
+                    ev.anyExample = node;
+                if (!node.hasPathEdge)
+                    return;
+                if (ev.samples.length < MAX_SAMPLES_PER_CLASS)
+                    ev.samples.push(node);
+                if (node.retainedSize > ev.exampleRetained) {
+                    ev.exampleRetained = node.retainedSize;
+                    ev.example = node;
+                }
+            });
+            // The biggest traceable instance is the most informative one to walk, so
+            // put it at the head of every retainer sample.
+            for (const ev of evidence.values()) {
+                if (ev.example != null) {
+                    ev.samples = [
+                        ev.example,
+                        ...ev.samples.filter(s => s.id !== ev.example.id),
+                    ];
+                }
+            }
+            const perCycle = cycles != null && cycles > 0;
+            const showDevOnly = reached != null;
+            const headers = [
+                'Class',
+                'Type',
+                ...steps.map((_, i) => `#${i + 1}`),
+                'Δ count',
+                ...(perCycle ? ['Δ/cycle'] : []),
+                'Δ size',
+                ...(showDevOnly ? ['Dev-only'] : []),
+                'Top retainer',
+                'Verdict hint',
+            ];
+            const rightCols = new Set();
+            for (let i = 2; i < headers.length - 2; i++)
+                rightCols.add(i);
+            let leakCandidates = 0;
+            let devOnlyClasses = 0;
+            const tableRows = candidates.map(r => {
+                const ev = evidence.get(r.key);
+                const devShare = ev.total > 0 ? ev.devOnly / ev.total : 0;
+                const isDevOnly = showDevOnly && devShare >= DEV_ONLY_SHARE;
+                if (isDevOnly)
+                    devOnlyClasses++;
+                let verdict;
+                if (r.artifact != null) {
+                    verdict = artifactLabel(r.artifact);
+                }
+                else if (isDevOnly) {
+                    verdict = '🛠 dev/automation-retained (not production)';
+                }
+                else if (r.trend === 'monotonic-up') {
+                    verdict = '↑ every step — LEAK candidate';
+                    leakCandidates++;
+                }
+                else {
+                    verdict = 'grew net (noisy)';
+                }
+                const label = displayName(r);
+                return [
+                    label.length > 34 ? label.slice(0, 31) + '…' : label,
+                    r.type,
+                    ...r.counts.map(c => formatNumber(c)),
+                    `+${formatNumber(r.netCount)}`,
+                    ...(perCycle ? [(r.netCount / cycles).toFixed(2)] : []),
+                    `${r.netSize >= 0 ? '+' : ''}${formatBytes(r.netSize)}`,
+                    ...(showDevOnly
+                        ? [
+                            ev.total === 0
+                                ? '—'
+                                : ev.devOnly === 0
+                                    ? '—'
+                                    : `${(devShare * 100).toFixed(0)}%`,
+                        ]
+                        : []),
+                    (label => (label.length > 44 ? label.slice(0, 41) + '…' : label))(topRetainerLabel(ev)),
+                    verdict,
+                ];
+            });
+            lines.push(markdownTable(headers, tableRows, rightCols));
+            lines.push('', `**${formatNumber(leakCandidates)} leak candidate(s)** of ${formatNumber(candidates.length)} growing class(es) examined` +
+                (devOnlyClasses > 0
+                    ? `; ${formatNumber(devOnlyClasses)} ruled out as dev/automation-retained`
+                    : '') +
+                (artifactRows.length > 0 && !include_artifacts
+                    ? `; ${formatNumber(artifactRows.length)} known measurement artifact(s) not shown (\`include_artifacts: true\`)`
+                    : '') +
+                '.');
+            if (!showDevOnly) {
+                lines.push('', '_No dev/automation roots were found in the final snapshot, so the dev-only column is omitted — nothing here is being attributed to the inspector._');
+            }
+            // Point at the single next call for the strongest candidate rather than
+            // a menu: the failure mode this tool exists to fix is a plausible
+            // grower being reported without anyone tracing it.
+            const strongest = candidates.find(r => r.artifact == null &&
+                r.trend === 'monotonic-up' &&
+                evidence.get(r.key)?.example != null);
+            if (strongest) {
+                const ev = evidence.get(strongest.key);
+                const example = ev.example;
+                lines.push('', `**Next:** confirm the top candidate before reporting it — \`memlab_retainer_trace({node_id: ${example.id}})\` on the largest traceable \`${displayName(strongest)}\` instance in the final rung, then \`memlab_dominator_chain\` on whatever owns it. Counts alone cannot distinguish a leak from a cache that grew and will be evicted.`);
+            }
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=leak-report.js.map

package/dist/tools/leak-report.js.map

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

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

@@ -9,6 +9,83 @@
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare const DEFAULT_MANIFOLD_BUCKET = "nest_server_nodejs_heap_snapshots";
+export declare const LOCAL_FILE_SIZE_LIMIT_MB = 900;
+export declare const MANIFOLD_FETCH_SIZE_LIMIT_MB = 2100;
+export declare const DEFAULT_MAX_NODES = 12000000;
+export declare const DEFAULT_MAX_EDGES = 24000000;
+export declare const WARN_NODE_COUNT = 2000000;
+export declare const NODES_PER_HEAP_MB = 1700;
+export declare const EDGES_PER_HEAP_MB = 6800;
+export declare const LOAD_BYTES_PER_NODE = 200;
+export declare const LOAD_BYTES_PER_EDGE = 40;
+export declare const HEADROOM_SAFETY_FRACTION = 0.8;
+/**
+ * Projected additional heap (MB) a full load of this graph will occupy.
+ * Light loads skip the dominator/retained-size arrays; the parsed graph still
+ * dominates, so the discount is modest and intentionally conservative.
+ */
+export declare function estimateLoadHeapMB(counts: {
+    nodeCount: number;
+    edgeCount: number;
+}, light: boolean): number;
+/**
+ * Old-space headroom (MB) left for a new load: the configured limit minus what
+ * is already committed. Returns null when the limit can't be read, in which case
+ * the caller skips the guard rather than guessing.
+ */
+export declare function getHeapHeadroomMB(): number | null;
+/**
+ * Configured V8 old-space limit in MB (reflects --max-old-space-size). Returns 0
+ * when it can't be read, so callers fall back to the fixed floors.
+ */
+export declare function getOldSpaceLimitMB(): number;
+/**
+ * Default node/edge load ceilings, auto-scaled from the configured old-space
+ * limit and floored at the historical fixed defaults so the ceiling never
+ * regresses below what was previously safe. `heapLimitMB` is 0 when the limit
+ * couldn't be read (ceilings then equal the fixed floors).
+ */
+export declare function computeDefaultCeilings(): {
+    maxNodes: number;
+    maxEdges: number;
+    heapLimitMB: number;
+};
+/**
+ * Cheaply read `node_count` / `edge_count` from a .heapsnapshot header without
+ * parsing the whole file. The V8 format begins with
+ * `{"snapshot":{"meta":{…},"node_count":N,"edge_count":M,…},…}`, so both counts
+ * sit within the first few KB. Reads a bounded prefix and regex-extracts them;
+ * returns null when they aren't found in the prefix (caller then skips the count
+ * guard rather than failing the load).
+ */
+export declare function peekSnapshotCounts(localPath: string): {
+    nodeCount: number;
+    edgeCount: number;
+} | null;
+/**
+ * Estimate the largest same-app capture (in MB) that would fit under the load
+ * ceiling, from THIS snapshot's own node/edge density. Server captures of one app
+ * have a roughly stable nodes-per-MB and edges-per-MB, so once a capture is
+ * refused for exceeding the ceiling, `ceiling ÷ density` tells the reader what
+ * file size to look for instead — turning the manual "hit ceiling → compute
+ * density by hand → re-query Scuba for a smaller file" loop into one number
+ * (sweep feedback round 7 §2: the guess-and-retry loop was the dominant friction).
+ * Edge-density usually binds first on edge-dense Nest heaps, so we take the min of
+ * the node-bound and edge-bound estimates. Returns null when it can't be computed.
+ */
+export declare function estimateMaxLoadableMB(counts: {
+    nodeCount: number;
+    edgeCount: number;
+}, fileSizeMB: number, ceilings: {
+    maxNodes: number;
+    maxEdges: number;
+}): number | null;
+/**
+ * Resolve the effective max-file-size limit (MB). An explicit caller value always
+ * wins; otherwise default by source — Manifold-fetched server snapshots get the
+ * higher ceiling, local files keep the tighter guard.
+ */
+export declare function resolveMaxFileSizeMB(explicit: number | undefined, fetchedFromManifold: boolean): number;
 /**
  * Resolve a `file_path` that may be a local path, a `manifold://bucket/key`
  * URL, or a bare snapshot filename to a local path, fetching from Manifold
@@ -18,5 +95,6 @@ export declare function resolveSnapshotPath(filePath: string): {
     localPath: string;
     fetchedFrom: string | null;
 };
+export declare function extractCaptureTime(fileName: string): Date | null;
 export declare function registerLoadSnapshot(server: McpServer): void;
 //# sourceMappingURL=load-snapshot.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"load-snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/load-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA0BvE,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAE3E;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAoCA;AAmID,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+M5D"}
+{"version":3,"file":"load-snapshot.d.ts","sourceRoot":"","sources":["../../src/tools/load-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAuCvE,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAU3E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAmBjD,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAC5C,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAC5C,eAAO,MAAM,eAAe,UAAY,CAAC;AAazC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAStC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAMtC,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,EAC9C,KAAK,EAAE,OAAO,GACb,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAUjD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAoBA;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAgB/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,GAC7C,MAAM,GAAG,IAAI,CASf;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,mBAAmB,EAAE,OAAO,GAC3B,MAAM,CAKR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAsEA;AAmCD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAWhE;AA4HD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmgB5D"}