@memlab/mcp-server 2.3.0 → 2.52.0

package/dist/tools/finding-index.js

@@ -0,0 +1,247 @@
+/**
+ * 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 crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { z } from 'zod';
+import { formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+/**
+ * A cross-round index of leak findings, keyed by a normalized retainer-path
+ * signature.
+ *
+ * The problem this solves is the most expensive one a hunt hits: rounds
+ * re-discover leaks that are already known or already fixed. One measured round
+ * produced three findings — a listener accumulation, a completion-map grower and
+ * a module-registry grower — all three of which were known, two already fixed
+ * behind gates, and the first only visible because the gated fixes were not
+ * enabled. That is an entire round spent re-deriving history.
+ *
+ * Why a retainer-path signature rather than the class name: the class that grows
+ * is rarely distinctive (`Object`, `Array`, `(object properties)` are the top
+ * growers in almost every heap), while the PATH that retains it is. Node ids,
+ * array indices and per-instance scope ids differ per capture, so they are
+ * stripped; what remains — the ordered edge names and class names — is stable
+ * across captures of the same leak and different between different leaks.
+ *
+ * Deliberately local (a JSON file), not a service: the index is only useful if
+ * it is written by default on every round, and anything requiring a backend
+ * would not be. It is seeded from prior runs' manifests.
+ */
+const INDEX_PATH = path.join(process.env.HOME ?? '/tmp', '.memlab-mcp', 'findings.json');
+function loadIndex() {
+    try {
+        if (fs.existsSync(INDEX_PATH)) {
+            const parsed = JSON.parse(fs.readFileSync(INDEX_PATH, 'utf8'));
+            if (parsed != null && typeof parsed === 'object') {
+                const idx = parsed;
+                return {
+                    version: idx.version ?? 1,
+                    findings: idx.findings ?? {},
+                    combos_driven: idx.combos_driven ?? {},
+                };
+            }
+        }
+    }
+    catch {
+        // A corrupt index must not block a hunt — but it must not be silently
+        // erased either: returning empty here means the next `record` overwrites
+        // the file wholesale and every prior fingerprint is gone, which defeats the
+        // one thing this tool exists to do. Preserve it for recovery first.
+        try {
+            if (fs.existsSync(INDEX_PATH)) {
+                fs.renameSync(INDEX_PATH, `${INDEX_PATH}.corrupt`);
+            }
+        }
+        catch {
+            // Best effort; a failed rename must not block the hunt either.
+        }
+    }
+    return { version: 1, findings: {}, combos_driven: {} };
+}
+function saveIndex(idx) {
+    fs.mkdirSync(path.dirname(INDEX_PATH), { recursive: true });
+    fs.writeFileSync(INDEX_PATH, JSON.stringify(idx, null, 2));
+}
+/**
+ * Normalize a retainer path into a signature that is stable across captures.
+ *
+ * Strips exactly the things that differ per capture and nothing else:
+ *  - `@12345` node ids, including the ` @…`-suffixed Context/scope names;
+ *  - numeric array indices (`[47]`, `.47`), which depend on insertion order;
+ *  - hex/long digit runs inside names (ids embedded in keys, e.g. a chat id).
+ */
+export function normalizeRetainerPath(raw) {
+    return (raw
+        .replace(/@\d+/g, '@')
+        .replace(/\[\d+\]/g, '[i]')
+        // Broad lookahead: retainer paths carry trailing `)`, `]`, `>` and the
+        // separator inserted below, so a `\\s|$|\\.`-only lookahead leaves `.47)` /
+        // `.47>` unnormalized and feeds per-capture noise into the fingerprint.
+        .replace(/\.\d+(?=[^\w]|$)/g, '.i')
+        .replace(/\b\d{4,}\b/g, 'N')
+        .replace(/\s*(-->|--|→|->)\s*/g, ' > ')
+        // `-->` would otherwise match `--` and `->` in turn, doubling the separator.
+        .replace(/(?: > )+/g, ' > ')
+        .replace(/\s+/g, ' ')
+        .trim());
+}
+export function fingerprintOf(signature, classes) {
+    const material = `${signature}||${[...classes].sort().join(',')}`;
+    return crypto.createHash('sha1').update(material).digest('hex').slice(0, 12);
+}
+export function registerFindingIndex(server) {
+    server.tool('memlab_finding_index', 'Fingerprint a leak finding by its retainer path and check it against findings from previous rounds, so a hunt does not spend itself re-discovering a known or already-fixed leak. ' +
+        'This is the highest-cost failure a leak hunt has: a measured round produced three findings that were all already known — two already fixed behind gates — which is an entire round spent re-deriving history. Class names cannot detect that (`Object` and `Array` top every heap); the retainer PATH can, so the fingerprint is a normalized path signature with node ids, array indices and per-capture scope ids stripped. ' +
+        'Actions: "check" fingerprints a candidate and reports NEW / KNOWN / KNOWN-AND-FIXED; "record" adds it; "list" prints the index; "cover" records which combos a round drove, so the "do not repeat covered combos" rule stops depending on someone remembering. Stored in ~/.memlab-mcp/findings.json.', {
+        action: z
+            .enum(['check', 'record', 'list', 'cover'])
+            .describe('"check" (fingerprint + look up, no write), "record" (add/update), "list", "cover" (log combos driven in a round).'),
+        retainer_path: z
+            .string()
+            .optional()
+            .describe("The finding's retainer path, as printed by memlab_retainer_summary / memlab_retainer_trace. Required for check and record."),
+        growing_classes: z
+            .array(z.string())
+            .optional()
+            .default([])
+            .describe('Classes that grew across the ladder for this finding. Folded into the fingerprint so the same path holding a different class set is a different finding.'),
+        round: z
+            .string()
+            .optional()
+            .describe('Round identifier (e.g. "r59"), recorded as first/last seen.'),
+        status: z
+            .enum(['new', 'known', 'fixed'])
+            .optional()
+            .default('known')
+            .describe('Status to record. Use "fixed" together with fixed_behind.'),
+        fixed_behind: z
+            .string()
+            .optional()
+            .describe('Gate/ABProp the fix sits behind, if it is fixed.'),
+        note: z
+            .string()
+            .optional()
+            .describe('Free-text note stored with the finding.'),
+        combos: z
+            .array(z.string())
+            .optional()
+            .default([])
+            .describe('For action "cover": combo names driven in this round.'),
+    }, async ({ action, retainer_path, growing_classes, round, status, fixed_behind, note, combos, }) => {
+        try {
+            const index = loadIndex();
+            if (action === 'list') {
+                const all = Object.values(index.findings);
+                if (all.length === 0) {
+                    return toolResult('The findings index is empty. Record findings as you confirm them ' +
+                        '(`action: "record"`); the value is entirely in future rounds being ' +
+                        'able to recognize them.');
+                }
+                const rows = all
+                    .sort((a, b) => b.seen_count - a.seen_count)
+                    .slice(0, 40)
+                    .map(f => [
+                    f.fingerprint,
+                    f.status === 'fixed'
+                        ? `fixed (${f.fixed_behind ?? '?'})`
+                        : f.status,
+                    f.growing_classes.slice(0, 3).join(', ') || '—',
+                    `${f.first_seen_round}${f.last_seen_round !== f.first_seen_round ? `→${f.last_seen_round}` : ''}`,
+                    String(f.seen_count),
+                    f.signature.length > 60
+                        ? f.signature.slice(0, 57) + '…'
+                        : f.signature,
+                ]);
+                // Sort by round id rather than trusting object insertion order: a
+                // re-recorded round moves in the object and "the last 8" silently
+                // stops meaning the most recent ones.
+                const covered = Object.entries(index.combos_driven)
+                    .sort((a, b) => a[0].localeCompare(b[0], undefined, { numeric: true }))
+                    .slice(-8)
+                    .map(([r, c]) => `${r}: ${c.join(', ')}`);
+                return toolResult([
+                    `## Findings index (${formatNumber(all.length)})`,
+                    '',
+                    markdownTable([
+                        'Fingerprint',
+                        'Status',
+                        'Classes',
+                        'Rounds',
+                        'Seen',
+                        'Signature',
+                    ], rows, new Set([4])),
+                    covered.length > 0 ? '\n### Combo coverage by round\n' : '',
+                    ...covered.map(c => `- ${c}`),
+                ].join('\n'));
+            }
+            if (action === 'cover') {
+                if (!round)
+                    return errorResult('action "cover" requires a round.');
+                index.combos_driven[round] = combos;
+                saveIndex(index);
+                return toolResult(`Recorded ${combos.length} combo(s) driven in ${round}: ${combos.join(', ') || '(none)'}.`);
+            }
+            if (!retainer_path) {
+                return errorResult(`action "${action}" requires a retainer_path.`);
+            }
+            const signature = normalizeRetainerPath(retainer_path);
+            const fingerprint = fingerprintOf(signature, growing_classes);
+            const existing = index.findings[fingerprint];
+            if (action === 'check') {
+                if (!existing) {
+                    return toolResult([
+                        `## NEW finding — fingerprint \`${fingerprint}\``,
+                        '',
+                        `Signature: \`${signature}\``,
+                        '',
+                        'No previous round recorded this retainer path with this class set. ' +
+                            'Confirm it, then `action: "record"` so the next round recognizes it.',
+                    ].join('\n'));
+                }
+                const label = existing.status === 'fixed'
+                    ? `KNOWN-AND-FIXED-BEHIND(${existing.fixed_behind ?? 'unknown gate'})`
+                    : `KNOWN (${existing.first_seen_round})`;
+                return toolResult([
+                    `## ${label} — fingerprint \`${fingerprint}\``,
+                    '',
+                    `Signature: \`${signature}\``,
+                    `First seen: ${existing.first_seen_round}; last seen: ${existing.last_seen_round}; seen ${existing.seen_count}×.`,
+                    existing.note ? `Note: ${existing.note}` : '',
+                    '',
+                    existing.status === 'fixed'
+                        ? `**Stop here.** This leak is already fixed behind \`${existing.fixed_behind}\`. If it is still reproducing, the gate is probably not enabled in this run — verify the gating state before treating it as a finding.`
+                        : '**This is not a new finding.** Check whether the earlier round already root-caused it before spending the rest of this one on it.',
+                ]
+                    .filter(Boolean)
+                    .join('\n'));
+            }
+            // record
+            const roundId = round ?? 'unknown';
+            index.findings[fingerprint] = {
+                fingerprint,
+                signature,
+                growing_classes,
+                first_seen_round: existing?.first_seen_round ?? roundId,
+                last_seen_round: roundId,
+                status,
+                fixed_behind: fixed_behind ?? existing?.fixed_behind,
+                note: note ?? existing?.note,
+                seen_count: (existing?.seen_count ?? 0) + 1,
+            };
+            saveIndex(index);
+            return toolResult(`Recorded \`${fingerprint}\` as **${status}**${fixed_behind ? ` (behind \`${fixed_behind}\`)` : ''} for round ${roundId}. ` +
+                `Signature: \`${signature}\`. The index now holds ${formatNumber(Object.keys(index.findings).length)} finding(s).`);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=finding-index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"finding-index.js","sourceRoot":"","sources":["../../src/tools/finding-index.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,CA+MvD"}
+{"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+NvD"}

package/dist/tools/for-each.js

@@ -45,7 +45,7 @@ export function registerForEach(server) {
         initial_value: z
             .string()
             .optional()
-            .describe('JSON string for the reduce initial accumulator value. ' +
+            .describe('JSON string for the reduce initial accumulator value; parsed with JSON.parse (must be valid JSON, not arbitrary code). ' +
             'Default: "[]" when reduce_code is present, ignored otherwise. ' +
             'Example: "0" or "{}"'),
         limit: z
@@ -105,6 +105,7 @@ export function registerForEach(server) {
                 __map: null,
                 __reduce: null,
                 __result: undefined,
+                __initAcc: undefined,
             };
             const context = vm.createContext(sandbox);
             // Compile filter function
@@ -126,12 +127,23 @@ export function registerForEach(server) {
             }
             // Build and run the iteration logic
             const isReducing = reduce_code != null;
-            const initVal = initial_value ?? (isReducing ? '[]' : undefined);
+            // Parse initial_value as JSON and pass it as a sandbox value rather than
+            // splicing it into the script source — interpolating it verbatim would
+            // let a caller inject executable code into the reduce path.
+            if (isReducing) {
+                try {
+                    sandbox.__initAcc =
+                        initial_value != null ? JSON.parse(initial_value) : [];
+                }
+                catch {
+                    return errorResult(new Error(`initial_value must be a valid JSON string (e.g. "0", "{}", "[]"). Received: ${initial_value}`));
+                }
+            }
             let iterationCode;
             if (isReducing) {
                 iterationCode = `
             (function() {
-              var acc = ${initVal};
+              var acc = __initAcc;
               snapshot.nodes.forEach(function(node) {
                 if (__filter(node)) {
                   var item = __map(node);

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":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,MAAM,EAAC,KAAK,EAAC,GAAG,UAAU,CAAC;AAC3B,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EACL,WAAW,EAEX,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO;AAE1C,SAAS,QAAQ,CAAC,GAAW,EAAE,GAAW;IACxC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,yCAAyC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,oDAAoD;QAClD,iFAAiF;QACjF,+CAA+C;QAC/C,gFAAgF;QAChF,uCAAuC;QACvC,8EAA8E,EAChF;QACE,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,CACP,uFAAuF;YACrF,qEAAqE,CACxE;QACH,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,yFAAyF;YACvF,2CAA2C;YAC3C,4EAA4E,CAC/E;QACH,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,0FAA0F;YACxF,uEAAuE;YACvE,gCAAgC,CACnC;QACH,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,yHAAyH;YACvH,gEAAgE;YAChE,sBAAsB,CACzB;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,GAAG,CAAC;aACZ,QAAQ,CAAC,6CAA6C,CAAC;QAC1D,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,KAAK,CAAC;aACd,QAAQ,CAAC,mDAAmD,CAAC;KACjE,EACD,KAAK,EAAE,EACL,WAAW,EACX,QAAQ,EACR,WAAW,EACX,aAAa,EACb,KAAK,EACL,UAAU,GACX,EAAE,EAAE;QACH,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAE/B,MAAM,OAAO,GAAG;gBACd,oBAAoB;gBACpB,mBAAmB;gBACnB,WAAW;gBACX,YAAY;gBACZ,aAAa;gBACb,qBAAqB;gBACrB,oBAAoB;gBACpB,UAAU;aACX,CAAC;YAEF,MAAM,OAAO,GAAG;gBACd,QAAQ;gBACR,KAAK;gBACL,OAAO;gBACP,sBAAsB;gBACtB,KAAK;gBACL,MAAM;gBACN,GAAG;gBACH,GAAG;gBACH,IAAI;gBACJ,IAAI;gBACJ,MAAM;gBACN,MAAM;gBACN,MAAM;gBACN,OAAO;gBACP,IAAI;gBACJ,KAAK;gBACL,SAAS;gBACT,UAAU;gBACV,OAAO;gBACP,OAAO;gBACP,MAAM;gBACN,QAAQ;gBACR,UAAU;gBACV,KAAK;gBACL,QAAQ;gBACR,QAAQ;gBACR,GAAG;gBACH,SAAS;gBACT,oDAAoD;gBACpD,QAAQ,EAAE,IAAe;gBACzB,KAAK,EAAE,IAAe;gBACtB,QAAQ,EAAE,IAAe;gBACzB,QAAQ,EAAE,SAAoB;gBAC9B,SAAS,EAAE,SAAoB;aAChC,CAAC;YAEF,MAAM,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YAE1C,0BAA0B;YAC1B,MAAM,YAAY,GAAG,IAAI,EAAE,CAAC,MAAM,CAChC,wCAAwC,WAAW,QAAQ,EAC3D,EAAC,QAAQ,EAAE,wBAAwB,EAAC,CACrC,CAAC;YACF,YAAY,CAAC,YAAY,CAAC,OAAO,EAAE,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC,CAAC;YAEpD,uBAAuB;YACvB,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,SAAS,GAAG,IAAI,EAAE,CAAC,MAAM,CAC7B,qCAAqC,QAAQ,QAAQ,EACrD,EAAC,QAAQ,EAAE,qBAAqB,EAAC,CAClC,CAAC;gBACF,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACN,MAAM,gBAAgB,GAAG,IAAI,EAAE,CAAC,MAAM,CACpC,0EAA0E,EAC1E,EAAC,QAAQ,EAAE,6BAA6B,EAAC,CAC1C,CAAC;gBACF,gBAAgB,CAAC,YAAY,CAAC,OAAO,EAAE,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC,CAAC;YAC1D,CAAC;YAED,sCAAsC;YACtC,IAAI,WAAW,EAAE,CAAC;gBAChB,MAAM,YAAY,GAAG,IAAI,EAAE,CAAC,MAAM,CAChC,6CAA6C,WAAW,QAAQ,EAChE,EAAC,QAAQ,EAAE,wBAAwB,EAAC,CACrC,CAAC;gBACF,YAAY,CAAC,YAAY,CAAC,OAAO,EAAE,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC,CAAC;YACtD,CAAC;YAED,oCAAoC;YACpC,MAAM,UAAU,GAAG,WAAW,IAAI,IAAI,CAAC;YAEvC,yEAAyE;YACzE,uEAAuE;YACvE,4DAA4D;YAC5D,IAAI,UAAU,EAAE,CAAC;gBACf,IAAI,CAAC;oBACH,OAAO,CAAC,SAAS;wBACf,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3D,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,WAAW,CAChB,IAAI,KAAK,CACP,+EAA+E,aAAa,EAAE,CAC/F,CACF,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,IAAI,aAAqB,CAAC;YAC1B,IAAI,UAAU,EAAE,CAAC;gBACf,aAAa,GAAG;;;;;;;;;;;WAWf,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,aAAa,GAAG;;;;4BAIE,KAAK;;;;;;;;;;WAUtB,CAAC;YACJ,CAAC;YAED,MAAM,UAAU,GAAG,IAAI,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE;gBAC9C,QAAQ,EAAE,yBAAyB;aACpC,CAAC,CAAC;YACH,UAAU,CAAC,YAAY,CAAC,OAAO,EAAE,EAAC,OAAO,EAAE,UAAU,EAAC,CAAC,CAAC;YAExD,IAAI,MAAc,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,WAAW,CAAC;YACpE,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACpC,CAAC;YAED,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;YAC3C,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IACE,GAAG,YAAY,KAAK;gBACpB,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAC,EAClD,CAAC;gBACD,OAAO,WAAW,CAChB,IAAI,KAAK,CACP,6BAA6B,UAAU,2LAA2L,CACnO,CACF,CAAC;YACJ,CAAC;YACD,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

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

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

package/dist/tools/get-references.js

@@ -11,31 +11,53 @@ import { z } from 'zod';
 import { getSnapshot } from '../heap-state.js';
 import { formatBytes, formatNumber, markdownTable, truncateNodeName, errorResult, toolResult, } from '../utils.js';
 export function registerGetReferences(server) {
-    server.tool('memlab_get_references', 'Get outgoing edges (references) from a heap node, sorted by target retained size. Shows what objects this node points to — its properties, elements, and closure captures. Complements memlab_get_referrers (incoming edges). Use memlab_object_shape for a quick property overview, or memlab_closure_inspection for closure-specific analysis.', {
+    server.tool('memlab_get_references', 'Get outgoing edges (references) from a heap node, sorted by target retained size. Shows what objects this node points to — its properties, elements, and closure captures. Supports edge_filter (match by edge name) and offset (pagination) so a node with thousands of references can be explored beyond the first page. Complements memlab_get_referrers (incoming edges). Use memlab_object_shape for a quick property overview, or memlab_closure_inspection for closure-specific analysis.', {
         node_id: z.number().describe('The numeric ID of the heap node'),
         limit: z
             .number()
             .optional()
             .default(30)
             .describe('Maximum number of references to return (default 30)'),
+        offset: z
+            .number()
+            .optional()
+            .default(0)
+            .describe('Number of (filtered, sorted) references to skip before returning — for paging past the first `limit` on high-degree nodes (default 0).'),
+        edge_filter: z
+            .string()
+            .optional()
+            .describe('Case-insensitive substring; only edges whose name/index contains it are returned (e.g. "context", or a specific property name). Applied before sort + pagination, so you can isolate one edge among thousands instead of scanning the top-N.'),
         compact: z
             .boolean()
             .optional()
             .default(true)
             .describe('Truncate target names to 60 chars to save tokens (default true). Set to false to see full names.'),
-    }, async ({ node_id, limit, compact }) => {
+    }, async ({ node_id, limit, offset, edge_filter, compact }) => {
         try {
             const snapshot = getSnapshot();
             const node = snapshot.getNodeById(node_id);
             if (!node) {
                 return errorResult(`Node with id ${node_id} not found`);
             }
-            const edges = node.references
+            // Treat an empty / whitespace-only filter as "no filter" so the header
+            // doesn't advertise a filter that matches every edge, and clamp a
+            // negative offset to 0 rather than letting slice() read from the tail.
+            const activeFilter = edge_filter != null && edge_filter.trim() !== '' ? edge_filter : null;
+            const filterLc = activeFilter?.toLowerCase();
+            const safeOffset = Math.max(0, offset);
+            const matched = node.references
                 .slice()
-                .sort((a, b) => b.toNode.retainedSize - a.toNode.retainedSize)
-                .slice(0, limit);
+                .filter(e => filterLc == null
+                ? true
+                : String(e.name_or_index).toLowerCase().includes(filterLc))
+                .sort((a, b) => b.toNode.retainedSize - a.toNode.retainedSize);
+            const edges = matched.slice(safeOffset, safeOffset + limit);
+            const filterNote = activeFilter != null
+                ? `, ${formatNumber(matched.length)} match "${activeFilter}"`
+                : '';
+            const offsetNote = safeOffset > 0 ? ` (from offset ${safeOffset})` : '';
             const lines = [
-                `**@${node_id} ${node.name}** — ${formatNumber(node.edge_count)} total references, showing ${edges.length}`,
+                `**@${node_id} ${node.name}** — ${formatNumber(node.edge_count)} total references${filterNote}, showing ${edges.length}${offsetNote}`,
                 '',
             ];
             const headers = [
@@ -57,6 +79,13 @@ export function registerGetReferences(server) {
                 formatBytes(e.toNode.retainedSize),
             ]);
             lines.push(markdownTable(headers, rows, rightCols));
+            const shownEnd = safeOffset + edges.length;
+            if (shownEnd < matched.length) {
+                lines.push('', `_${formatNumber(matched.length - shownEnd)} more — pass offset=${shownEnd} for the next page._`);
+            }
+            else if (edges.length === 0 && safeOffset > 0 && matched.length > 0) {
+                lines.push('', `_offset ${safeOffset} is past the last of ${formatNumber(matched.length)} matched references — use a smaller offset._`);
+            }
             return toolResult(lines.join('\n'));
         }
         catch (err) {

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

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

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

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

package/dist/tools/get-referrers.js

@@ -11,31 +11,53 @@ import { z } from 'zod';
 import { getSnapshot } from '../heap-state.js';
 import { formatBytes, formatNumber, markdownTable, truncateNodeName, errorResult, toolResult, } from '../utils.js';
 export function registerGetReferrers(server) {
-    server.tool('memlab_get_referrers', 'Get incoming edges (referrers) to a heap node, sorted by source retained size. Shows what objects hold references to this node. Complements memlab_get_references (outgoing edges). Use memlab_retainer_trace to see the full GC root path.', {
+    server.tool('memlab_get_referrers', 'Get incoming edges (referrers) to a heap node, sorted by source retained size. Shows what objects hold references to this node. Supports edge_filter (match by edge name) and offset (pagination) so a widely-referenced singleton can be explored beyond the first page — e.g. "which referrers are NOT the dev-only Debug alias?". Complements memlab_get_references (outgoing edges). Use memlab_retainer_trace to see the full GC root path.', {
         node_id: z.number().describe('The numeric ID of the heap node'),
         limit: z
             .number()
             .optional()
             .default(30)
             .describe('Maximum number of referrers to return (default 30)'),
+        offset: z
+            .number()
+            .optional()
+            .default(0)
+            .describe('Number of (filtered, sorted) referrers to skip before returning — for paging past the first `limit` on widely-referenced nodes (default 0).'),
+        edge_filter: z
+            .string()
+            .optional()
+            .describe('Case-insensitive substring; only referrers whose edge name/index contains it are returned. Applied before sort + pagination, so you can isolate one referrer among hundreds instead of scanning the top-N.'),
         compact: z
             .boolean()
             .optional()
             .default(true)
             .describe('Truncate source names to 60 chars to save tokens (default true). Set to false to see full names.'),
-    }, async ({ node_id, limit, compact }) => {
+    }, async ({ node_id, limit, offset, edge_filter, compact }) => {
         try {
             const snapshot = getSnapshot();
             const node = snapshot.getNodeById(node_id);
             if (!node) {
                 return errorResult(`Node with id ${node_id} not found`);
             }
-            const edges = node.referrers
+            // Treat an empty / whitespace-only filter as "no filter" so the header
+            // doesn't advertise a filter that matches every referrer, and clamp a
+            // negative offset to 0 rather than letting slice() read from the tail.
+            const activeFilter = edge_filter != null && edge_filter.trim() !== '' ? edge_filter : null;
+            const filterLc = activeFilter?.toLowerCase();
+            const safeOffset = Math.max(0, offset);
+            const matched = node.referrers
                 .slice()
-                .sort((a, b) => b.fromNode.retainedSize - a.fromNode.retainedSize)
-                .slice(0, limit);
+                .filter(e => filterLc == null
+                ? true
+                : String(e.name_or_index).toLowerCase().includes(filterLc))
+                .sort((a, b) => b.fromNode.retainedSize - a.fromNode.retainedSize);
+            const edges = matched.slice(safeOffset, safeOffset + limit);
+            const filterNote = activeFilter != null
+                ? `, ${formatNumber(matched.length)} match "${activeFilter}"`
+                : '';
+            const offsetNote = safeOffset > 0 ? ` (from offset ${safeOffset})` : '';
             const lines = [
-                `**@${node_id} ${node.name}** — ${formatNumber(node.numOfReferrers)} total referrers, showing ${edges.length}`,
+                `**@${node_id} ${node.name}** — ${formatNumber(node.numOfReferrers)} total referrers${filterNote}, showing ${edges.length}${offsetNote}`,
                 '',
             ];
             const headers = [
@@ -57,6 +79,30 @@ export function registerGetReferrers(server) {
                 formatBytes(e.fromNode.retainedSize),
             ]);
             lines.push(markdownTable(headers, rows, rightCols));
+            // A widely-referenced node often has a long tail of byte-identical
+            // referrers (e.g. hundreds of `(sliced string) / parent` edges into one
+            // big string). Listing them row by row is pure token cost, so summarise
+            // the shape of the whole matched set — including the rows past `limit`.
+            const groups = new Map();
+            for (const e of matched) {
+                const k = `${e.fromNode.name} (${e.fromNode.type}) / ${String(e.name_or_index)} / ${e.type}`;
+                groups.set(k, (groups.get(k) ?? 0) + 1);
+            }
+            if (groups.size > 0 && groups.size < matched.length) {
+                const summary = [...groups.entries()]
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 6)
+                    .map(([k, n]) => `${formatNumber(n)}× ${k}`)
+                    .join(' · ');
+                lines.push('', `_Referrer shapes (all ${formatNumber(matched.length)} matched, not just the rows above): ${summary}${groups.size > 6 ? `, +${formatNumber(groups.size - 6)} more shapes` : ''}._`);
+            }
+            const shownEnd = safeOffset + edges.length;
+            if (shownEnd < matched.length) {
+                lines.push('', `_${formatNumber(matched.length - shownEnd)} more — pass offset=${shownEnd} for the next page._`);
+            }
+            else if (edges.length === 0 && safeOffset > 0 && matched.length > 0) {
+                lines.push('', `_offset ${safeOffset} is past the last of ${formatNumber(matched.length)} matched referrers — use a smaller offset._`);
+            }
             return toolResult(lines.join('\n'));
         }
         catch (err) {

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

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

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

package/dist/tools/hunt-report.d.ts.map

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