@memlab/mcp-server 2.1.1 → 2.18.1

package/dist/tools/weakmap-entries.js

@@ -0,0 +1,156 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import { z } from 'zod';
+import { getSnapshot } from '../heap-state.js';
+import { formatBytes, formatNumber, markdownTable, truncateNodeName, errorResult, toolResult, } from '../utils.js';
+export function registerWeakMapEntries(server) {
+    server.tool('memlab_weakmap_entries', 'Enumerate the key-value pairs of ONE WeakMap (node_id is REQUIRED — this is not a global scan). WeakMaps back DataStore, private fields, and metadata caches; since keys are weakly held, their entries reveal which objects are associated and what metadata is stored. First locate a WeakMap with memlab_find_nodes_by_class("WeakMap") (or memlab_largest_objects), then pass its node id here.', {
+        node_id: z
+            .number()
+            .describe('REQUIRED. The numeric ID of a single WeakMap node. Find candidates with memlab_find_nodes_by_class("WeakMap"); there is no scan-all-WeakMaps mode.'),
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Maximum number of entries to return (default 20)'),
+        sort_by: z
+            .enum(['retained_size', 'retained', 'key_name'])
+            .optional()
+            .default('retained_size')
+            .describe('Sort entries by key retained size ("retained_size", alias "retained") or key name ("key_name"). Default: retained_size.'),
+    }, async ({ node_id, limit, sort_by }) => {
+        try {
+            const snapshot = getSnapshot();
+            const node = snapshot.getNodeById(node_id);
+            if (!node) {
+                return errorResult(`Node with id ${node_id} not found`);
+            }
+            if (node.name !== 'WeakMap') {
+                return errorResult(`@${node_id} is a ${node.name} (${node.type}), not a WeakMap. ` +
+                    `Use \`memlab_find_nodes_by_class("WeakMap")\` to find WeakMap instances.`);
+            }
+            const entries = [];
+            for (const edge of node.references) {
+                const eName = String(edge.name_or_index);
+                if (eName !== 'table' && eName !== 'backing_store')
+                    continue;
+                const table = edge.toNode;
+                const tableRefs = [];
+                for (const te of table.references) {
+                    if (te.type === 'internal' || te.type === 'hidden')
+                        continue;
+                    tableRefs.push(te.toNode);
+                }
+                // WeakMap tables store key-value pairs: [key1, val1, key2, val2, ...]
+                for (let i = 0; i < tableRefs.length - 1; i += 2) {
+                    const key = tableRefs[i];
+                    const value = tableRefs[i + 1];
+                    if (key.id <= 3)
+                        continue;
+                    if (key.name === 'undefined' || key.name === 'the_hole')
+                        continue;
+                    entries.push({
+                        key,
+                        value,
+                        keyRetained: key.retainedSize,
+                        valueRetained: value.retainedSize,
+                    });
+                }
+                break;
+            }
+            // Fallback: try to read entries from ephemeron edges (some V8 versions)
+            if (entries.length === 0) {
+                for (const edge of node.references) {
+                    if (edge.type !== 'weak' &&
+                        edge.type !== 'property' &&
+                        edge.type !== 'element')
+                        continue;
+                    const target = edge.toNode;
+                    if (target.id <= 3)
+                        continue;
+                    if (target.name === 'undefined' || target.name === 'the_hole')
+                        continue;
+                    // Each weak edge points to a key; the corresponding value
+                    // is the next non-weak edge or accessible through the key's references
+                    entries.push({
+                        key: target,
+                        value: target,
+                        keyRetained: target.retainedSize,
+                        valueRetained: 0,
+                    });
+                }
+            }
+            if (entries.length === 0) {
+                return toolResult(`WeakMap @${node_id} has no enumerable entries.\n\n` +
+                    `**Note:** V8's WeakMap implementation uses an EphemeronHashTable ` +
+                    `whose entries may not be fully exposed in the heap snapshot. ` +
+                    `Try \`memlab_get_references(${node_id})\` to inspect the raw structure.`);
+            }
+            if (sort_by === 'retained_size' || sort_by === 'retained') {
+                entries.sort((a, b) => b.keyRetained +
+                    b.valueRetained -
+                    (a.keyRetained + a.valueRetained));
+            }
+            else {
+                entries.sort((a, b) => a.key.name.localeCompare(b.key.name));
+            }
+            const shown = entries.slice(0, limit);
+            const totalEntries = entries.length;
+            const totalKeyRetained = entries.reduce((s, e) => s + e.keyRetained, 0);
+            const totalValueRetained = entries.reduce((s, e) => s + e.valueRetained, 0);
+            const headers = [
+                'Key ID',
+                'Key',
+                'Key Retained',
+                'Value ID',
+                'Value',
+                'Value Retained',
+            ];
+            const rightCols = new Set([2, 5]);
+            const rows = shown.map(e => {
+                const keyName = truncateNodeName(e.key.name, e.key.type, e.key.self_size, 40);
+                let valueName;
+                if (e.value === e.key) {
+                    valueName = '(see key)';
+                }
+                else {
+                    valueName = truncateNodeName(e.value.name, e.value.type, e.value.self_size, 40);
+                    if (e.value.isString) {
+                        const strNode = e.value.toStringNode();
+                        if (strNode) {
+                            const val = strNode.stringValue;
+                            valueName = `"${val.length > 35 ? val.slice(0, 35) + '...' : val}"`;
+                        }
+                    }
+                }
+                return [
+                    `@${e.key.id}`,
+                    `${keyName} (${e.key.type})`,
+                    formatBytes(e.keyRetained),
+                    `@${e.value.id}`,
+                    `${valueName} (${e.value.type})`,
+                    formatBytes(e.valueRetained),
+                ];
+            });
+            const lines = [
+                `WeakMap @${node_id}: ${formatNumber(totalEntries)} entries` +
+                    (totalEntries > limit ? ` (showing top ${limit})` : ''),
+                `Total key retained: ${formatBytes(totalKeyRetained)}, total value retained: ${formatBytes(totalValueRetained)}`,
+                '',
+                markdownTable(headers, rows, rightCols),
+            ];
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=weakmap-entries.js.map

package/dist/tools/weakmap-entries.js.map

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

package/dist/utils.d.ts

@@ -7,7 +7,9 @@
  * @format
  * @oncall memory_lab
  */
-import type { IHeapNode, IHeapEdge, IHeapSnapshot } from '@memlab/core';
+import type { IHeapNode, IHeapEdge, IHeapSnapshot, HeapNodeIdSet } from '@memlab/core';
+import { ScanTimeoutError, makeScanBudget } from './analysis-budget.js';
+export { ScanTimeoutError, makeScanBudget };
 export interface NodeSummary {
     id: number;
     name: string;
@@ -37,28 +39,157 @@ export interface OutgoingEdge extends EdgeSummary {
 export interface IncomingEdge extends EdgeSummary {
     from_node: NodeSummary;
 }
-export declare function truncateNodeName(name: string, type: string, selfSize: number, maxLen?: number): string;
+export declare function truncateDomToTag(name: string): string;
+export declare function truncateNodeName(name: string, type: string, selfSize: number, maxLen?: number, aggressiveDom?: boolean): string;
 export declare function serializeNodeSummary(node: IHeapNode): NodeSummary;
 export declare function serializeNodeDetail(node: IHeapNode): NodeDetail;
 export declare function serializeOutgoingEdge(edge: IHeapEdge): OutgoingEdge;
 export declare function serializeIncomingEdge(edge: IHeapEdge): IncomingEdge;
 export declare function isNodeWorthInspecting(node: IHeapNode): boolean;
+/**
+ * Property names that mark a "freshness" timestamp on a TTL/warm cache wrapper
+ * object (e.g. `{entries, loadedAt}`, `{items, timestamp}`). Their presence next
+ * to a large array/Map means the collection was loaded as a point-in-time
+ * snapshot, not appended to over time. Shared by cache-analysis (to recognize
+ * the cache shape) and growth-signals (to suppress the append-only
+ * false-positive on load-once caches). Feedback round 4 §B/§C.
+ */
+export declare const FRESHNESS_TIMESTAMP_PROPS: ReadonlySet<string>;
+/**
+ * True when `node` (typically a large Array/Map) is held by a wrapper object
+ * that also carries a freshness-timestamp sibling property — i.e. it is the data
+ * side of a `{entries, loadedAt}`-style TTL/warm cache, loaded once rather than
+ * grown unboundedly.
+ */
+export declare function hasFreshnessTimestampSibling(node: IHeapNode): boolean;
+/**
+ * Heuristic: does a (JSON-ish) string look like a cached *failure* response?
+ * Cached error payloads are both wasted memory and a signal that an upstream
+ * dependency is failing — surfacing them links a memory finding to a likely
+ * correctness bug. Conservative: requires a JSON-object/array head plus an
+ * explicit failure marker. Feedback round 4 §D.
+ */
+export declare function looksLikeFailurePayload(value: string): boolean;
 export declare function filterLargestObjects(snapshot: IHeapSnapshot, filter: (node: IHeapNode) => boolean, limit: number): IHeapNode[];
+/**
+ * Collapse heap nodes that are merely different VIEWS of the same dominator
+ * subtree (e.g. on a single in-flight request: Client → Request → closure →
+ * Promise → Context → Map all reporting the SAME retained size). Without this,
+ * `largest_objects` returns ~20 rows that are all one subtree — pure noise and
+ * wasted tokens (feedback §A.2).
+ *
+ * Two nodes are treated as the same subtree ONLY when (a) their retained sizes
+ * are within `epsilon` of each other AND (b) one dominates the other within a
+ * bounded dominator walk — so unrelated objects that merely share a byte count
+ * are never collapsed. `candidates` must be pre-sorted by retained size desc;
+ * the highest dominator (ancestor) is kept as the representative, annotated with
+ * `mergedCount` = how many views were folded into it.
+ */
+export declare function collapseDominatorSubtrees(candidates: IHeapNode[], limit: number, opts?: {
+    epsilon?: number;
+    maxWalk?: number;
+}): Array<{
+    node: IHeapNode;
+    mergedCount: number;
+}>;
 export type OutputMode = 'full' | 'count' | 'ids';
 export interface QueryNodesResult {
     total_count: number;
     nodes?: NodeSummary[];
     ids?: number[];
+    timed_out?: boolean;
 }
 export declare function queryNodes(snapshot: IHeapSnapshot, filter: (node: IHeapNode) => boolean, opts: {
     limit: number;
     offset: number;
     outputMode: OutputMode;
+    budget?: {
+        tick: () => void;
+    };
 }): QueryNodesResult;
+/**
+ * Dominator-deduped retained size for a set of nodes, with a BOUNDED upward
+ * dominator walk (default 500 steps, mirroring auto-investigate's
+ * `isDominatorAncestor` maxWalk). For each node we walk up its dominator chain
+ * looking for another in-set ancestor; if one is found the node is dominated
+ * (its bytes are already counted by that ancestor) so we skip it, otherwise we
+ * add its retained size.
+ *
+ * Unlike `@memlab/core`'s `aggregateDominatorMetrics`, the walk is capped and
+ * allocates no per-node Set, so a pathological deep dominator chain (e.g. a long
+ * PromiseReaction linked list) cannot make this blow up. Trade-off: if a node's
+ * nearest in-set dominator is deeper than `maxWalk`, we conservatively KEEP it
+ * (treat it as maximal), which can OVER-count — so `exact` is returned `false`
+ * whenever any node's walk was truncated, letting callers mark the figure as an
+ * upper bound. Calls `tickAnalysis()` per node so it also honors the wall-clock
+ * guardrail.
+ */
+export declare function boundedDominatorRetainedSize(ids: HeapNodeIdSet, snapshot: IHeapSnapshot, maxWalk?: number): {
+    retained: number;
+    exact: boolean;
+};
+/**
+ * Best-effort detection of which app a Node snapshot came from, by tallying the
+ * `/app(s)/<name>/` segment in bundle paths embedded throughout the heap (string
+ * node values, function/script names). Returns the most common segment, or null
+ * if nothing decisive is found (Feedback round 3 §3d).
+ */
+export declare function detectAppName(snapshot: IHeapSnapshot): string | null;
+/**
+ * Recognize retainer paths that route through runtime instrumentation — a
+ * patched global `console`, OpenTelemetry context chains, structured loggers,
+ * etc. Such paths are frequently reported as the GC owner even though the
+ * *logical* owner (a module cache, an OTel logger, a source-map cache) lives
+ * elsewhere and is only incidentally reachable via the instrumentation's
+ * captured-closure → `context` → `previous` → `Context` chain. Returns a short
+ * annotation when the path looks instrumentation-routed, else null
+ * (Feedback round 3 §3a).
+ */
+export declare function instrumentationRetainerNote(steps: Array<{
+    name: string;
+    edgeName?: string;
+}>): string | null;
 export declare function formatBytes(bytes: number): string;
 export declare function formatNumber(n: number): string;
 export declare function markdownTable(headers: string[], rows: string[][], alignRight?: Set<number>): string;
 export declare function formatNodeInline(id: number, name: string, type: string, selfSize?: number): string;
+/**
+ * One step of a retainer path, root-first. `edgeName` is the name of the edge
+ * that points INTO this node from its retainer (i.e. parent → this node, the
+ * property / element / context slot through which the parent holds this node).
+ * The GC root (first step) has no incoming edge. `collapsedBefore` records how
+ * many uninteresting internal nodes were elided immediately above this node.
+ */
+export interface RetainerTreeStep {
+    id: number;
+    name: string;
+    type: string;
+    retainedSize?: number;
+    selfSize?: number;
+    edgeName?: string;
+    collapsedBefore?: number;
+    collapsedNote?: string;
+}
+/**
+ * Render a retainer path so it reads in a single, unambiguous direction: the GC
+ * root is at the top, and **every node is retained by the one above it**. The
+ * edge that connects a parent to its child is embedded in the connector
+ * (`└─ .prop →` / `└─ [2] →`, ladder: `↓ .prop`), and sizes as `— <bytes>`.
+ *
+ * Shallow chains use a nested indented tree (one indent level = one hop).
+ * **Deep chains automatically switch to a flat `↓` ladder** (controlled by
+ * `maxTreeDepth`, default 8) so growing indentation never pushes the leaf node
+ * off the right edge of a narrow terminal.
+ *
+ * This deliberately avoids the older inline style that mixed `←` (retained-by)
+ * and `→` (references) arrows on the same line, which made the direction of a
+ * trace genuinely hard to read in analysis output and diff summaries. Always
+ * prefer this renderer when presenting a retainer chain to a human.
+ */
+export declare function formatRetainerTree(steps: RetainerTreeStep[], opts?: {
+    showSizes?: boolean;
+    maxTreeDepth?: number;
+}): string;
 export declare function formatNodeSummaryTable(nodes: NodeSummary[]): string;
 export declare function formatQueryNodesResult(result: QueryNodesResult, offset?: number): string;
 export declare function snapshotHeader(): string;
@@ -74,6 +205,12 @@ export declare function toolResult(text: string): {
         text: string;
     }[];
 };
+/**
+ * Whether tools should omit "Suggested next steps" / "How to fix" trailers.
+ * Honors the session-level `suppressSuggestions` config so callers can trim
+ * repeated boilerplate tokens across a long investigation.
+ */
+export declare function suggestionsSuppressed(): boolean;
 export declare function jsonResult(data: unknown): {
     content: {
         type: "text";

package/dist/utils.d.ts.map

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