querysub 0.451.0 → 0.453.0

package/src/diagnostics/NodeViewer.tsx

@@ -79,10 +79,11 @@ export class NodeViewer extends qreact.Component {
                     let data: NodeData = { nodeId };
                     try {
                         data.table = await controller.getMiscInfo(nodeId);
-                        data.live_isAlive = await controller.live_isAlive(nodeId);
-                        data.live_exposedControllers = await controller.getExposedControllers(nodeId);
-                        data.live_entryPoint = await controller.live_getEntryPoint(nodeId);
-                        data.live_trueTimeOffset = await controller.live_getTrueTimeOffset(nodeId);
+                        let metadata = await controller.live_getMetadata(nodeId);
+                        data.live_isAlive = !!metadata;
+                        data.live_exposedControllers = metadata?.exposedControllers;
+                        data.live_entryPoint = metadata?.entryPoint;
+                        data.live_trueTimeOffset = metadata?.trueTimeOffset;
                         data.live_authorityPaths = await controller.live_getAuthorityPaths(nodeId);
                         data.ip = await controller.getNodeIP(nodeId);
                         if (data.ip === ourExternalIP || data.ip === ourIP) {
@@ -484,27 +485,18 @@ class NodeViewerControllerBase {
         await syncNodesNow();
     }
 
-    public async getExposedControllers(nodeId: string) {
-        return await NodeCapabilitiesController.nodes[nodeId].getExposedControllers();
+    public async live_getMetadata(nodeId: string) {
+        return await errorToUndefinedSilent(NodeCapabilitiesController.nodes[nodeId].getMetadata());
     }
 
     public async getControllerNodeIdList(controller: SocketRegistered<{}>) {
         return await getControllerNodeIdList(controller);
     }
 
-    public async live_isAlive(nodeId: string) {
-        return !!await errorToUndefinedSilent(NodeCapabilitiesController.nodes[nodeId].getEntryPoint());
-    }
     public async live_getAuthorityPaths(nodeId: string) {
         let topo = await NodeMetadataController.nodes[nodeId].debugGetTopologyEntry(nodeId);
         return topo?.authoritySpec;
     }
-    public async live_getEntryPoint(nodeId: string) {
-        return NodeCapabilitiesController.nodes[nodeId].getEntryPoint();
-    }
-    public async live_getTrueTimeOffset(nodeId: string) {
-        return NodeCapabilitiesController.nodes[nodeId].getTrueTimeOffset();
-    }
 
     public async getMiscInfo(nodeId: string): Promise<{
         columns: ColumnsType;
@@ -521,18 +513,19 @@ class NodeViewerControllerBase {
                 row[columnName] = "Error: " + e.stack;
             }
         }
+        let metadataPromise = NodeCapabilitiesController.nodes[nodeId].getMetadata();
         let promises = [
             wrapAddTableValue("paths|paths", {}, async () => {
                 let live_authorityPaths = (await NodeMetadataController.nodes[nodeId].debugGetPathAuthorities(nodeId));
                 return JSON.stringify(live_authorityPaths);
             }),
             wrapAddTableValue("paths|functions", {}, async () => {
-                let live_functionRunnerShards = await NodeCapabilitiesController.nodes[nodeId].getFunctionRunnerShards();
-                return live_functionRunnerShards.map(x => `${x.domainName}[${x.shardRange.startFraction}-${x.shardRange.endFraction}]${x.secondaryShardRange && `+[${x.secondaryShardRange?.startFraction || 0}-${x.secondaryShardRange?.endFraction || 0}]` || ""}`).join(" | ");
+                let metadata = await metadataPromise;
+                return metadata.functionRunnerShards.map(x => `${x.domainName}[${x.shardRange.startFraction}-${x.shardRange.endFraction}]${x.secondaryShardRange && `+[${x.secondaryShardRange?.startFraction || 0}-${x.secondaryShardRange?.endFraction || 0}]` || ""}`).join(" | ");
             }),
             wrapAddTableValue("uptime", { formatter: "timeSpan" }, async () => {
-                let startupTime = await NodeCapabilitiesController.nodes[nodeId].getStartupTime();
-                return Date.now() - startupTime;
+                let metadata = await metadataPromise;
+                return Date.now() - metadata.startupTime;
             }),
             wrapAddTableValue("port", {}, async () => {
                 return nodeId.split(":").at(-1);
@@ -557,8 +550,8 @@ class NodeViewerControllerBase {
                 ].filter(x => x);
             }),
             wrapAddTableValue("capabilities|capabilities", {}, async () => {
-                let live_exposedControllers = await NodeCapabilitiesController.nodes[nodeId].getExposedControllers();
-                return live_exposedControllers.map(x => x.split("-")[0]);
+                let metadata = await metadataPromise;
+                return metadata.exposedControllers.map(x => x.split("-")[0]);
             }),
         ];
         await Promise.allSettled(promises);
@@ -590,12 +583,9 @@ export const NodeViewerController = SocketFunction.register(
         getExternalInspectURL: {},
         verifyAccess: {},
         getAllNodeIds: {},
-        getExposedControllers: {},
         getControllerNodeIdList: {},
-        live_isAlive: {},
+        live_getMetadata: {},
         live_getAuthorityPaths: {},
-        live_getEntryPoint: {},
-        live_getTrueTimeOffset: {},
         getMiscInfo: {},
 
         forceRefreshNodes: {},

package/src/diagnostics/debugger/mcp-server.ts

@@ -3,8 +3,9 @@
  *
  * Exposes the V8 inspector / Chrome DevTools Protocol as MCP tools:
  *
- *   attach       - connect to a debug target, keep the connection open, and
- *                  return a short sessionId used by every other tool.
+ *   attachNode   - connect to a Querysub cluster node by nodeId (deciding
+ *                  local vs remote via getExternalIP), keep the connection
+ *                  open, and return a short sessionId used by every other tool.
  *   detach       - close a session.
  *   listScripts  - list scripts loaded in the target.
  *   getSource    - get a script's source (optionally a line range).
@@ -23,7 +24,6 @@
 module.hotreload = false;
 
 import * as http from "http";
-import * as path from "path";
 import * as dns from "dns";
 
 // Allow callers to point this process at a different project root (so we use
@@ -49,7 +49,6 @@ import { getExternalIP } from "../../misc/networking";
 import { getNodeIdDomain } from "socket-function/src/nodeCache";
 
 const DEFAULT_MCP_PORT = 3001;
-const DEFAULT_PORT_FILE = path.join(process.cwd(), "debugger-port.json");
 const PROTOCOL_VERSION = "2025-06-18";
 // Per-node budget for the getEntryPoint / getInspectURL probes in listNodes;
 // a node that doesn't answer in time is reported with those fields undefined.
@@ -78,10 +77,38 @@ interface ScriptParsed {
     url: string;
 }
 
+interface PausedState {
+    /** Reason CDP reported for the pause (e.g. "other" for breakpoint, "step"). */
+    reason: string;
+    /** CDP breakpointIds that fired this pause, if any. */
+    hitBreakpoints: string[];
+    /** CDP call frames, top-most first. */
+    callFrames: any[];
+}
+
+interface BreakpointEntry {
+    /** CDP breakpointId (also used as the user-facing handle). */
+    breakpointId: string;
+    /** URL the breakpoint was placed on. */
+    url: string;
+    /** Requested line number, 1-based. */
+    requestedLine: number;
+    /** Actual resolved line number, 1-based; undefined if it didn't bind. */
+    actualLine?: number;
+    /** Optional condition expression that gates the pause. */
+    condition?: string;
+}
+
 interface Session {
     id: string;
     remote: DebuggerRemote;
     scripts: ScriptParsed[];
+    /** Active pausing breakpoints, keyed by CDP breakpointId. */
+    breakpoints: Map<string, BreakpointEntry>;
+    /** Set while the target is paused; cleared on resume. */
+    paused?: PausedState;
+    /** Resolvers waiting for the next pause event. */
+    pauseWaiters: Array<() => void>;
 }
 
 const sessions = new Map<string, Session>();
@@ -129,17 +156,60 @@ function resolveScript(session: Session, query: string): ScriptParsed {
  * other tools can find it by sessionId.
  */
 async function openSession(remote: DebuggerRemote): Promise<Session> {
-    const session: Session = { id: newSessionId(), remote, scripts: [] };
+    const session: Session = {
+        id: newSessionId(),
+        remote,
+        scripts: [],
+        breakpoints: new Map(),
+        pauseWaiters: [],
+    };
     // Register before enabling so we capture the initial script dump.
     remote.on("Debugger.scriptParsed", (p: ScriptParsed) =>
         session.scripts.push({ scriptId: p.scriptId, url: p.url }),
     );
+    // Track pause/resume so other tools (evaluate, waitForPause) can see
+    // whether the target is currently stopped at a breakpoint.
+    remote.on("Debugger.paused", (p: any) => {
+        session.paused = {
+            reason: p.reason ?? "other",
+            hitBreakpoints: p.hitBreakpoints ?? [],
+            callFrames: p.callFrames ?? [],
+        };
+        const waiters = session.pauseWaiters.splice(0);
+        for (const w of waiters) w();
+    });
+    remote.on("Debugger.resumed", () => {
+        session.paused = undefined;
+    });
     await remote.send("Runtime.enable");
     await remote.send("Debugger.enable");
     sessions.set(session.id, session);
     return session;
 }
 
+/** Short summary of a paused state, suitable for tool output. */
+function describePaused(session: Session): string {
+    if (!session.paused) return "(not paused)";
+    const { reason, hitBreakpoints, callFrames } = session.paused;
+    const hit = hitBreakpoints.length
+        ? ` (hit ${hitBreakpoints.join(", ")})`
+        : "";
+    const stack = callFrames
+        .slice(0, 8)
+        .map((f: any, i: number) => {
+            const url = f.url || "?";
+            const line = (f.location?.lineNumber ?? 0) + 1;
+            const col = (f.location?.columnNumber ?? 0) + 1;
+            return `  #${i} ${f.functionName || "<anon>"} at ${url}:${line}:${col}`;
+        })
+        .join("\n");
+    return (
+        `Paused (reason=${reason})${hit}\n` +
+        `Top call frame id: ${callFrames[0]?.callFrameId ?? "(none)"}\n` +
+        `Call stack:\n${stack || "  (empty)"}`
+    );
+}
+
 /** Human-readable "Attached. sessionId=… + user scripts" summary for a session. */
 function describeSession(session: Session): string {
     const userScripts = session.scripts.filter((s) => isUserScript(s.url));
@@ -168,17 +238,13 @@ async function getNodeInfos(): Promise<NodeInfo[]> {
     const nodes = await getAllNodeIds();
     return Promise.all(
         nodes.map(async (nodeId): Promise<NodeInfo> => {
-            const [entryPoint, inspectUrl] = await Promise.all([
-                timeoutToUndefinedSilent(
-                    NODE_INFO_TIMEOUT_MS,
-                    NodeCapabilitiesController.nodes[nodeId].getEntryPoint(),
-                ),
+            const [metadata] = await Promise.all([
                 timeoutToUndefinedSilent(
                     NODE_INFO_TIMEOUT_MS,
-                    NodeCapabilitiesController.nodes[nodeId].getInspectURL(),
-                ),
+                    NodeCapabilitiesController.nodes[nodeId].getMetadata(),
+                )
             ]);
-            return { nodeId, entryPoint, inspectUrl };
+            return { nodeId, entryPoint: metadata?.entryPoint };
         }),
     );
 }
@@ -267,9 +333,8 @@ const tools: Record<string, ToolDef> = {
         description:
             "List every node in the Querysub cluster, with each node's process " +
             "entry point and V8 inspector (devtools) URL. Returns an array of " +
-            "{ nodeId, entryPoint, inspectUrl }. A node that does not answer in " +
-            "time has entryPoint / inspectUrl left undefined. Use a node's " +
-            "inspectUrl to point the `attach` tool at it for debugging.",
+            "{ nodeId, entryPoint }. A node that does not answer in " +
+            "time has entryPoint left undefined",
         inputSchema: {
             type: "object",
             properties: {},
@@ -286,8 +351,7 @@ const tools: Record<string, ToolDef> = {
             "and return a sessionId usable by every other tool. Works out " +
             "whether the node is on this machine or remote — a local node is " +
             "debugged directly; a remote node is reached by asking it to open a " +
-            "one-time external debug port locked to this machine's IP. Prefer " +
-            "this over `attach` when working with cluster nodes.",
+            "one-time external debug port locked to this machine's IP.",
         inputSchema: {
             type: "object",
             properties: {
@@ -308,39 +372,6 @@ const tools: Record<string, ToolDef> = {
         },
     },
 
-    attach: {
-        description:
-            "Attach to a running Node.js process over its V8 inspector (debugger) " +
-            "port. Keeps the connection open and returns a short sessionId for use " +
-            "by every other tool. Provide one of portFile / port / wsUrl; defaults " +
-            "to the ./debugger-port.json written by test.ts. Retries for ~10s if " +
-            "the target is not listening yet.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                portFile: {
-                    type: "string",
-                    description: "Path to a debugger-port.json file. Default: ./debugger-port.json",
-                },
-                port: { type: "number", description: "Inspector HTTP port (alternative to portFile)." },
-                wsUrl: { type: "string", description: "Direct CDP WebSocket URL (alternative to portFile/port)." },
-            },
-        },
-        handler: async (args) => {
-            let remote: DebuggerRemote;
-            if (typeof args.wsUrl === "string") {
-                remote = new DebuggerRemote({ wsUrl: args.wsUrl });
-            } else if (typeof args.port === "number") {
-                remote = new DebuggerRemote({ port: args.port });
-            } else {
-                remote = new DebuggerRemote({ portFile: args.portFile ?? DEFAULT_PORT_FILE });
-            }
-            const session = await openSession(remote);
-            log(`attached session ${session.id} (${session.scripts.length} scripts)`);
-            return describeSession(session);
-        },
-    },
-
     detach: {
         description: "Close a debugger session and disconnect from the target.",
         inputSchema: {
@@ -424,8 +455,10 @@ const tools: Record<string, ToolDef> = {
     evaluate: {
         description:
             "Evaluate a JavaScript expression inside the target process and return " +
-            "the result. Runs in the global context and awaits promises. Tip: " +
-            "`process.exit(0)` cleanly terminates the target.",
+            "the result. When the target is paused at a breakpoint, the expression " +
+            "runs in the top call frame's scope so locals and parameters are visible; " +
+            "otherwise it runs in the global context. Awaits promises. Tip: " +
+            "`process.exit(0)` cleanly terminates the target (when not paused).",
         inputSchema: {
             type: "object",
             properties: {
@@ -439,6 +472,21 @@ const tools: Record<string, ToolDef> = {
             if (typeof args.expression !== "string") {
                 throw new Error("expression must be a string");
             }
+            if (session.paused?.callFrames?.length) {
+                const topFrame = session.paused.callFrames[0];
+                const res = await session.remote.send("Debugger.evaluateOnCallFrame", {
+                    callFrameId: topFrame.callFrameId,
+                    expression: args.expression,
+                    returnByValue: true,
+                });
+                if (res.exceptionDetails) {
+                    throw new Error(`Remote threw: ${JSON.stringify(res.exceptionDetails)}`);
+                }
+                const value = res.result?.value;
+                return value === undefined
+                    ? "undefined (or non-serializable result)"
+                    : JSON.stringify(value, null, 2);
+            }
             const value = await session.remote.evaluate(args.expression);
             return value === undefined
                 ? "undefined (or non-serializable result)"
@@ -578,6 +626,232 @@ const tools: Record<string, ToolDef> = {
             return `${header}\n${body}`;
         },
     },
+
+    setBreakpoint: {
+        description:
+            "Install a real breakpoint that PAUSES the target when hit. Unlike " +
+            "logpoint, this stops execution so you can inspect state (via evaluate, " +
+            "which uses the paused call frame's scope) and add more breakpoints " +
+            "before resuming. Returns a breakpointId. Use waitForPause to block " +
+            "until the breakpoint actually fires. IMPORTANT: while paused, the " +
+            "target's entire event loop is stopped (no heartbeats, no I/O) — " +
+            "external watchdogs may kill long-paused processes, so resume promptly.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                script: { type: "string", description: "scriptId or URL substring." },
+                lineNumber: {
+                    type: "number",
+                    description: "1-based line to set the breakpoint on (matches getSource output).",
+                },
+                condition: {
+                    type: "string",
+                    description:
+                        "Optional JS boolean expression. The target only pauses when it is truthy.",
+                },
+            },
+            required: ["sessionId", "script", "lineNumber"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            const script = resolveScript(session, String(args.script));
+            const lineNumber = Math.floor(args.lineNumber);
+            if (!(lineNumber >= 1)) {
+                throw new Error("lineNumber must be a positive integer (1-based).");
+            }
+            if (args.condition !== undefined && typeof args.condition !== "string") {
+                throw new Error("condition must be a string if provided.");
+            }
+
+            const params: any = {
+                url: script.url,
+                lineNumber: lineNumber - 1,
+            };
+            if (typeof args.condition === "string" && args.condition.trim()) {
+                params.condition = args.condition;
+            }
+
+            const res = await session.remote.send("Debugger.setBreakpointByUrl", params);
+            const breakpointId: string = res.breakpointId;
+            const locations: any[] = res.locations ?? [];
+            const bound = locations.length > 0;
+            const actualLine = bound ? locations[0].lineNumber + 1 : undefined;
+
+            session.breakpoints.set(breakpointId, {
+                breakpointId,
+                url: script.url,
+                requestedLine: lineNumber,
+                actualLine,
+                condition: params.condition,
+            });
+
+            if (!bound) {
+                return (
+                    `Breakpoint set but did NOT bind: line ${lineNumber} of ${script.url} ` +
+                    `has no executable code right now. It will bind later if the source is ` +
+                    `(re)loaded. breakpointId=${breakpointId}`
+                );
+            }
+            return (
+                `Breakpoint set. breakpointId=${breakpointId}\n` +
+                `Location: ${script.url}:${actualLine}` +
+                (actualLine !== lineNumber ? ` (requested ${lineNumber})` : "") +
+                (params.condition ? `\nCondition: ${params.condition}` : "")
+            );
+        },
+    },
+
+    removeBreakpoint: {
+        description: "Remove a pausing breakpoint by its breakpointId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                breakpointId: { type: "string" },
+            },
+            required: ["sessionId", "breakpointId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (typeof args.breakpointId !== "string" || !args.breakpointId) {
+                throw new Error("breakpointId must be a non-empty string.");
+            }
+            await session.remote.send("Debugger.removeBreakpoint", {
+                breakpointId: args.breakpointId,
+            });
+            const existed = session.breakpoints.delete(args.breakpointId);
+            return existed
+                ? `Removed breakpoint ${args.breakpointId}.`
+                : `Removed breakpoint ${args.breakpointId} (was not in this session's table).`;
+        },
+    },
+
+    listBreakpoints: {
+        description: "List the pausing breakpoints currently set on this session.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (session.breakpoints.size === 0) return "(no breakpoints set)";
+            const lines: string[] = [];
+            for (const bp of session.breakpoints.values()) {
+                const loc = bp.actualLine !== undefined
+                    ? `${bp.url}:${bp.actualLine}`
+                    : `${bp.url}:${bp.requestedLine} (NOT BOUND)`;
+                const cond = bp.condition ? `  condition=${bp.condition}` : "";
+                lines.push(`${bp.breakpointId}  ${loc}${cond}`);
+            }
+            return lines.join("\n");
+        },
+    },
+
+    waitForPause: {
+        description:
+            "Block until the target is paused at a breakpoint (or already is), and " +
+            "return a summary of the paused state including call stack and the top " +
+            "callFrameId. If the timeout elapses before a pause, returns a not-paused " +
+            "message and does NOT throw.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                timeoutMs: {
+                    type: "number",
+                    description: "How long to wait for a pause, in ms. Default 30000.",
+                },
+            },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (session.paused) {
+                return describePaused(session);
+            }
+            const timeoutMs = Math.max(1, Math.floor(args.timeoutMs ?? 30_000));
+            let timedOut = false;
+            await new Promise<void>((resolve) => {
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    // Drop our waiter so a later pause doesn't double-resolve.
+                    const idx = session.pauseWaiters.indexOf(resolve);
+                    if (idx >= 0) session.pauseWaiters.splice(idx, 1);
+                    resolve();
+                }, timeoutMs);
+                session.pauseWaiters.push(() => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+            if (timedOut && !session.paused) {
+                return `Timed out after ${timeoutMs}ms — target is not paused.`;
+            }
+            return describePaused(session);
+        },
+    },
+
+    resume: {
+        description: "Resume the paused target (Debugger.resume).",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) return "Target is not paused — nothing to resume.";
+            await session.remote.send("Debugger.resume");
+            return "Resumed.";
+        },
+    },
+
+    stepOver: {
+        description: "Step over the next statement (Debugger.stepOver). Target must be paused.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) throw new Error("Target is not paused.");
+            await session.remote.send("Debugger.stepOver");
+            return "Stepped over.";
+        },
+    },
+
+    stepInto: {
+        description: "Step into the next function call (Debugger.stepInto). Target must be paused.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) throw new Error("Target is not paused.");
+            await session.remote.send("Debugger.stepInto");
+            return "Stepped into.";
+        },
+    },
+
+    stepOut: {
+        description: "Step out of the current function (Debugger.stepOut). Target must be paused.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) throw new Error("Target is not paused.");
+            await session.remote.send("Debugger.stepOut");
+            return "Stepped out.";
+        },
+    },
 };
 
 // --------------------------------------------------------------------------

package/src/diagnostics/logs/IndexedLogs/IndexedLogs.ts

@@ -290,8 +290,8 @@ export class IndexedLogs<T> {
                 if (!hasLogger) return false;
                 // NOTE: Prefer to do the searching on the move logs service. However, if it's not available, any service can do searching. It just might lag that server... 
                 if (preferredOnly) {
-                    let entryPoint = await timeoutToUndefinedSilent(2500, NodeCapabilitiesController.nodes[nodeId].getEntryPoint());
-                    if (!entryPoint?.includes("movelogs")) return false;
+                    let metadata = await timeoutToUndefinedSilent(2500, NodeCapabilitiesController.nodes[nodeId].getMetadata());
+                    if (!metadata?.entryPoint.includes("movelogs")) return false;
                 }
                 added = true;