@memlab/mcp-server 2.52.0 → 2.86.0

package/dist/tools/eval-across.js

@@ -0,0 +1,135 @@
+/**
+ * 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 { getCurrentHandle, getMetadataByHandle, listSnapshots, setCurrentSnapshot, } from '../heap-state.js';
+import { errorResult, toolResult } from '../utils.js';
+import { runEval } from './eval.js';
+function textOf(result) {
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return '(no output)';
+    return content
+        .map(c => (typeof c?.text === 'string' ? c.text : ''))
+        .join('\n')
+        .trim();
+}
+export function registerEvalAcross(server) {
+    server.tool('memlab_eval_across', 'Run ONE `memlab_eval` program against SEVERAL resident snapshots and return the results side by side. ' +
+        'Exists because the interesting questions in a leak hunt are comparative — "how many of these were there at each rung?", ' +
+        '"did this collection grow?", "is the new population retained the same way as the old one?" — and answering them with ' +
+        '`memlab_eval` alone costs one switch + one paste + one manual diff per rung, which is enough friction that the question ' +
+        'often just does not get asked. The code, the sandbox and the helper surface are identical to `memlab_eval` (this calls the ' +
+        'same implementation, not a copy), so anything that runs there runs here.\n\n' +
+        'Node ids are per-capture, so write code that computes COMPARABLE values (counts, sizes, shapes, string values) rather than ' +
+        'code that hardcodes ids from one rung. `helpers.load(name)` still refuses cross-snapshot reads unless you pass ' +
+        '`{allowCrossSnapshot: true}`.\n\n' +
+        'The active snapshot is restored when the run finishes, including on failure, so this does not disturb an in-progress investigation.', {
+        code: z
+            .string()
+            .describe('JavaScript to run against each snapshot. Same conventions as memlab_eval: assign to `result`, iterate with `snapshot.nodes.forEach`, use `helpers.*`. Run `memlab_eval({mode:"describe_env"})` for the full surface.'),
+        handles: z
+            .array(z.string())
+            .optional()
+            .describe('Snapshot handles to run against, in the order you want them reported (oldest rung first reads best). Defaults to every resident snapshot in load order.'),
+        timeout_ms: z
+            .number()
+            .optional()
+            .default(60000)
+            .describe('Execution timeout in milliseconds, applied PER snapshot (default 60000).'),
+        max_nodes: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe('Per-snapshot node-visit budget for full-heap walks. Defaults to a budget SCALED from each loaded graph (6 full passes, floored at 20,000,000). On overrun that rung reports a partial result instead of failing the whole run.'),
+        stop_on_error: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Stop at the first snapshot whose code throws (default false: record the error for that rung and continue, so one bad rung does not discard the others).'),
+    }, async ({ code, handles, timeout_ms, max_nodes, stop_on_error }) => {
+        const originalHandle = getCurrentHandle();
+        try {
+            const resident = listSnapshots().map(m => m.handle);
+            if (resident.length === 0) {
+                return errorResult(new Error('No snapshots are loaded. Load them with memlab_load_snapshot({keep_previous: true}) first — this tool compares snapshots that are already resident, it does not open files.'));
+            }
+            const targets = handles != null && handles.length > 0 ? handles : resident;
+            const unknown = targets.filter(h => getMetadataByHandle(h) == null);
+            if (unknown.length > 0) {
+                return errorResult(new Error(`Unknown snapshot handle(s): ${unknown.join(', ')}. Resident: ${resident.join(', ')}. ` +
+                    'Handles come from memlab_snapshots or the alias passed to memlab_load_snapshot.'));
+            }
+            if (targets.length < 2) {
+                // Not an error — a single-handle run is a legitimate way to script
+                // one rung — but the whole point of the tool is the comparison.
+                // Saying so beats silently returning a one-row report.
+                // (falls through and runs)
+            }
+            const sections = [];
+            let failures = 0;
+            for (const handle of targets) {
+                if (!setCurrentSnapshot(handle)) {
+                    sections.push(`### ${handle}\n\n(could not switch to this snapshot)`);
+                    failures++;
+                    continue;
+                }
+                const meta = getMetadataByHandle(handle);
+                const header = `### ${handle}${meta ? ` — ${meta.fileName}` : ''}`;
+                try {
+                    const res = await runEval({ code, timeout_ms, max_nodes });
+                    const body = textOf(res);
+                    if (/^Error:/m.test(body))
+                        failures++;
+                    sections.push(`${header}\n\n${body}`);
+                    if (stop_on_error && /^Error:/m.test(body)) {
+                        sections.push('_Stopped here: stop_on_error is set and this rung failed._');
+                        break;
+                    }
+                }
+                catch (err) {
+                    failures++;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    sections.push(`${header}\n\nError: ${msg}`);
+                    if (stop_on_error) {
+                        sections.push('_Stopped here: stop_on_error is set and this rung failed._');
+                        break;
+                    }
+                }
+            }
+            const lines = [
+                `## eval across ${targets.length} snapshot(s)`,
+                '',
+                `Order: ${targets.join(' → ')}${failures > 0 ? ` · ${failures} rung(s) reported an error` : ''}`,
+                '',
+                ...(targets.length < 2
+                    ? [
+                        '_Only one snapshot targeted — this tool exists for the comparison; load a second rung with `keep_previous: true` to get one._',
+                        '',
+                    ]
+                    : []),
+                sections.join('\n\n'),
+                '',
+                '_Values are comparable across rungs; node IDS are not — they are assigned per capture. Compare counts, sizes, shapes and string values, never ids._',
+            ];
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+        finally {
+            // Restore whatever the caller had active, so a comparison run is not a
+            // hidden state change for every tool that follows it.
+            if (originalHandle != null)
+                setCurrentSnapshot(originalHandle);
+        }
+    });
+}
+//# sourceMappingURL=eval-across.js.map

package/dist/tools/eval-across.js.map

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

package/dist/tools/eval.d.ts

@@ -8,6 +8,84 @@
  * @oncall memory_lab
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { toolResult } from '../utils.js';
+/**
+ * Wall-clock budget for one eval, scaled from the loaded graph.
+ *
+ * A fixed 60 s default is right for an indexed lookup and wrong for everything
+ * else: a full-heap walk on a 6M-node graph takes two to four minutes, so every
+ * large-snapshot eval aborted on its first attempt and had to be re-issued with
+ * an explicit `timeout_ms`. That is a guaranteed wasted call per question, and
+ * the node count needed to avoid it is already known.
+ *
+ * The floor stays at 60 s so small heaps behave exactly as before.
+ */
+export declare function scaledEvalTimeoutMs(): number;
+/**
+ * Default `max_nodes`, scaled to the loaded graph.
+ *
+ * A probe that makes several passes over the heap is the normal shape — one
+ * pass to census classes, one to match shapes, one to size things — so the
+ * budget has to be a MULTIPLE of the node count, not a constant. At the old
+ * flat 20,000,000 a routine two-pass probe on an 8.24M-node capture aborted
+ * mid-walk and returned a partial value; because the result was assigned after
+ * the loops, what came back was `undefined` with a note, which reads as a
+ * legitimate empty answer.
+ *
+ * Six passes is generous on purpose: the wall-clock timeout above is the real
+ * guard against a runaway eval, and this budget exists to stop pathological
+ * traversals, not ordinary multi-pass analysis.
+ */
+export declare function scaledWalkBudget(): number;
+/**
+ * Shorten a heap result STRUCTURALLY rather than mid-string.
+ *
+ * A census result is an array of rows or a `{key: count}` map, and cutting the
+ * JSON at a byte offset yields unparseable output plus a re-run with a
+ * hand-written limit — which is what actually happened to a detached-class
+ * census whose `blink::HeapVectorBacking<…>` keys blew the cap. Dropping whole
+ * entries keeps the value valid JSON and keeps the largest rows, which are the
+ * ones the question was about.
+ *
+ * Blink's C++ template names are elided first: they are frequently most of the
+ * payload and none of the information, and `abbreviateBlinkTypeName` is the same
+ * elision the table renderers already use.
+ */
+export declare function shrinkResult(value: unknown, maxBytes: number): {
+    value: unknown;
+    truncated: boolean;
+    droppedEntries: number;
+    keptEntries: number;
+};
 export declare function unwrapNode<T>(node: T): T;
 export declare function registerEval(server: McpServer): void;
+export declare function runEval({ mode, code, section, timeout_ms, save_as, max_nodes, sample, restrict_to_ids, dry_run, max_result_bytes, ownsScanBudget, }: {
+    mode?: 'eval' | 'describe_env' | 'list_saved' | 'lint';
+    code?: string;
+    section?: string;
+    timeout_ms?: number;
+    save_as?: string;
+    max_nodes?: number;
+    /** Visit every Nth node in a full-heap walk. 1/undefined = every node. */
+    sample?: number;
+    /** Restrict `snapshot.nodes.forEach` to these node ids. */
+    restrict_to_ids?: number[];
+    dry_run?: boolean;
+    max_result_bytes?: number;
+    /**
+     * True only for a direct `memlab_eval` MCP call, which owns the scan budget
+     * the guardrail armed for it and may therefore re-arm it to a scaled value.
+     * Left false by every in-process caller — `memlab_eval_across`,
+     * `memlab_ladder_probe`, `memlab_batch` — because those run MANY evals inside
+     * ONE MCP call and each re-arm would reset the shared wall clock.
+     */
+    ownsScanBudget?: boolean;
+}): Promise<ReturnType<typeof toolResult>>;
+/**
+ * A result that says "none of them" — 0, `[]`, `{}`, or an empty Map/Set.
+ *
+ * `undefined`/`null` are deliberately NOT included: those mean "the code
+ * assigned nothing", which is a different failure and is already handled.
+ */
+export declare function isEmptyCensusResult(v: unknown): boolean;
 //# sourceMappingURL=eval.d.ts.map

package/dist/tools/eval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../src/tools/eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA4EvE,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAMxC;AA0ID,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAy7BpD"}
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../src/tools/eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAuBvE,OAAO,EAGL,UAAU,EAgBX,MAAM,aAAa,CAAC;AAYrB;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAGzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GACf;IACD,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAkFA;AAwCD,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAMxC;AAiZD,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAwIpD;AAqCD,wBAAsB,OAAO,CAAC,EAC5B,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,SAAS,EACT,MAAM,EACN,eAAe,EACf,OAAO,EACP,gBAAgB,EAChB,cAAc,GACf,EAAE;IACD,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,YAAY,GAAG,MAAM,CAAC;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAywDzC;AA2HD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAQvD"}