breakpoint-mcp 1.78.2 → 1.78.3

package/dist/bridge.js

@@ -2,7 +2,7 @@ import net from "node:net";
 import { randomUUID } from "node:crypto";
 import { log } from "./logger.js";
 import { OverdueLedger } from "./late-reply.js";
-import { findNonFinite, describeNonFinite, tolerate, TOLERANT_METHODS } from "./finiteness.js";
+import { findNonFinite, describeNonFinite, tolerate, TOLERANT_METHODS, nonFiniteRemedy } from "./finiteness.js";
 import { remedyForWireError } from "./remedies.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
 import { connectHint, connectRemedy } from "./connect-cause.js";
@@ -342,7 +342,7 @@ export class BridgeClient {
             else {
                 const hits = findNonFinite(result);
                 if (hits.length)
-                    p.reject(new BridgeError("non_finite", describeNonFinite(hits)));
+                    p.reject(new BridgeError("non_finite", describeNonFinite(hits), nonFiniteRemedy(hits)));
                 else
                     p.resolve(result);
             }

package/dist/exit-cause.js

@@ -0,0 +1,110 @@
+/**
+ * What a MANAGED CHILD'S termination discriminates, and the next action for each.
+ *
+ * 🔴 WHY THIS EXISTS — 265 answered the connect family and left the two peer sites in
+ * the census's silent bucket. Driven at 266 against real spawned children, they are the
+ * same shape one file over, and one of them was making a claim that is FALSE rather than
+ * merely absent:
+ *
+ * ```
+ *                          what the caller read
+ * child exited (code 1)    1 of 1 peer(s) did not become ready. peer-1 on 21101: exited (code 1)
+ *                          — SCRIPT ERROR: could not load main scene. Is the Breakpoint MCP
+ *                          addon enabled in this project (it registers the runtime autoload)?
+ *
+ * child alive, no ping     1 of 1 peer(s) did not become ready. peer-1 on 21121: never answered
+ *                          ping. Is the Breakpoint MCP addon enabled in this project (it
+ *                          registers the runtime autoload)?
+ *
+ * two measured causes -> one question -> ZERO next actions
+ * ```
+ *
+ * 🔴 READ THE FIRST ROW. The child EXITED, on its own, with a code and a stderr line
+ * naming what stopped it. Whether the addon is enabled had no bearing on that: an absent
+ * runtime autoload does not stop a process, it stops a process from ANSWERING. The
+ * operator whose scene fails to load is sent to go and look at the plugin list. That is
+ * 265 §1's ENOTFOUND finding at the process boundary — and `m?.exited`, the thing that
+ * says which sentence is true, is computed on the line directly above the one that pastes
+ * the question over both.
+ *
+ * 🔴 THE QUESTION IS SUPPRESSED, NOT REWORDED. `readinessHint` returns the shipped
+ * sentence unchanged when NO not-ready peer exited — the family it was always true of —
+ * and `""` the moment one did. Every caller that reads the silent case reads the same
+ * bytes, and there is a test asserting that direction specifically, because a build that
+ * dropped the question unconditionally would be a worse defect than the one being fixed
+ * and would pass a one-sided test.
+ *
+ * 🔴 AND THE SECOND SITE NAMED A CODE THAT IS NOT A CODE. `peer_exited` rendered
+ * `Peer "peer-1" exited (code null)` for a SIGKILLed child, because
+ * `ProcessRegistry.run` registered `child.on("exit", (code) => …)` and dropped node's
+ * SECOND argument. The signal was handed to that callback on every kill since the
+ * registry was written and assigned to nothing — 265's "a default that compiles asks no
+ * question", spelled here as a parameter nobody declared. `exitSignal` is captured now
+ * and `describeExit` says `killed by SIGKILL` where the sentence used to print a null.
+ *
+ * 🔵 WHAT THIS DELIBERATELY DOES NOT DO. `godot_process_output` still answers
+ * `exit_code: null` for a signal-killed child and carries no `signal` key: that is a wire
+ * addition to a shipped tool, it would make this cut a MINOR, and it is enqueued rather
+ * than folded in. The capture is internal; only the two peer sentences read it today.
+ */
+/** How a managed child ended, in the words a person would use. */
+export function describeExit(code, signal) {
+    // The signal is checked FIRST because both can be non-null in no case node produces,
+    // and because `code` is the one that is null exactly when the signal is the answer.
+    if (signal)
+        return `killed by ${signal}`;
+    if (code === null)
+        return "exited without reporting a code";
+    return `exited (code ${code})`;
+}
+/**
+ * The hint that belongs in the MESSAGE, given what actually happened to the children.
+ *
+ * Returns the shipped sentence unchanged while every not-ready peer is merely SILENT —
+ * the family it describes correctly — and suppresses it as soon as one has exited, where
+ * it is a statement about a plugin that could not have stopped a process.
+ */
+export function readinessHint(causes, hint) {
+    return causes.some((c) => c === "exited") ? "" : hint;
+}
+/**
+ * The next action for a peer that did not become ready, branched on the causes in hand.
+ *
+ * Three populations, because the registry really does produce three: every child gone,
+ * every child alive and mute, and a mixture. A mixture gets both actions named rather
+ * than the first one that matched, because telling an operator with one dead peer and one
+ * mute peer to do only half the work is the same error as the sentence this replaces.
+ *
+ * Written to the grammar check 28 enforces on `error_remedies.gd`: one imperative at the
+ * head, a full stop at the end, and nothing named that does not resolve.
+ */
+export function readinessRemedy(causes) {
+    if (causes.length === 0)
+        return undefined;
+    const exited = causes.some((c) => c === "exited");
+    const silent = causes.some((c) => c === "silent");
+    if (exited && silent) {
+        return (`Read the output quoted above for the peer(s) that exited and fix what stopped them, ` +
+            `then check the Breakpoint MCP plugin is enabled for the one(s) that stayed up and never ` +
+            `answered — two different things failed here and only the second is about the addon.`);
+    }
+    if (exited) {
+        return (`Read the output quoted above and fix what stopped the child — it exited on its own, ` +
+            `so the state of the Breakpoint MCP plugin is not what failed here.`);
+    }
+    return (`Enable the "Breakpoint MCP" plugin in this project and retry — the peer is still running ` +
+        `and answered nothing on its port, which is what a missing runtime autoload looks like.`);
+}
+/**
+ * The next action for a request addressed to a peer whose process is already gone.
+ *
+ * Branched on whether the host CAPTURED any output from it: a child that said something
+ * before it died has a cause the caller can read, and one that said nothing has only the
+ * fact of its death, which makes re-spawning the next action rather than reading.
+ */
+export function peerExitRemedy(hasTail) {
+    return hasTail
+        ? `Read the last output quoted above to see what stopped this peer, then spawn a replacement with runtime_spawn_peers.`
+        : `Spawn a replacement with runtime_spawn_peers — this peer captured no output before it went, so there is nothing here to read.`;
+}
+//# sourceMappingURL=exit-cause.js.map

package/dist/finiteness.js

@@ -117,6 +117,42 @@ export function describeNonFinite(hits) {
         `JSON cannot carry them — Godot stringifies INF as 1e99999 and NAN as null — so the ` +
         `call is refused rather than reported as a success with the value silently missing.`);
 }
+/**
+ * The next action for a refused non-finite reply.
+ *
+ * 🔴 ONE FAMILY IS MEASURED AND ONE IS SPOKEN FOR (266). Driven against a raw-bytes fake
+ * addon writing what Godot writes, every value that reaches this refusal is `Infinity` or
+ * `-Infinity` from a literal `1e99999`, flat or nested, one hit or many. **NAN is NOT this
+ * refusal's population**, which the message's own aside makes easy to assume it is:
+ * measured, Godot's `null` for NAN parses to `null`, `findNonFinite({current: null})`
+ * returns `[]`, and the reply RESOLVES and reaches the client's schema as a null. So the
+ * remedy speaks about an infinity and about nothing else, per 265's refusal to invent.
+ *
+ * 🔴 AND IT DOES NOT SAY "RETRY". This is the one host-raised failure in the census whose
+ * cause is neither the transport nor the host's own state but the PROJECT'S DATA — the
+ * engine really does hold that value, and it will hold it again on the next call. A
+ * sentence offering a retry would be the shape 262 §2 found on `dbg_set_variable`: fluent,
+ * addressed to the wrong party, and wrong every time it is read.
+ *
+ * Branched on the one discriminator in hand: how many paths carry it. Naming a single
+ * path is a place to go and look; naming six is almost always one upstream value, and
+ * sending someone to inspect six properties one at a time is the wrong next action.
+ *
+ * Written to the grammar check 28 enforces on `error_remedies.gd`: one imperative at the
+ * head, a full stop at the end, and nothing named that does not resolve.
+ */
+export function nonFiniteRemedy(hits) {
+    if (hits.length === 0)
+        return undefined;
+    if (hits.length === 1) {
+        return (`Inspect ${hits[0].path} in the project — the engine's own value there is infinite ` +
+            `(a division by zero and an unset scale are the usual sources), so this is data to fix ` +
+            `rather than a call to repeat.`);
+    }
+    return (`Look for the one value feeding all ${hits.length} of the paths named above — an infinity ` +
+        `this wide is almost always a single division by zero propagated by the engine, so this is ` +
+        `data to fix rather than a call to repeat.`);
+}
 /**
  * Drop every non-finite value from a flat monitor record, returning what survived and the
  * keys that did not. The declared type of the record does not move: a reading that is not

package/dist/index.js

@@ -52,7 +52,7 @@ async function main() {
     // so long jobs (export/import/headless script) support poll/await/cancel.
     // D3: also advertise resources.subscribe so clients can subscribe to
     // godot://… resources and receive notifications/resources/updated.
-    const server = new McpServer({ name: "breakpoint-mcp", version: "1.78.2" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.78.3" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // 208 §7.1 — delete from the wire what the protocol already says: the SDK's
     // draft-07 `$schema` inside every input/output schema (MCP's default dialect is
     // 2020-12, and declaring another is an explicit switch a peer may reject), and

package/dist/peers.js

@@ -4,6 +4,7 @@ import { ensureProjectSecret, readProjectSecret } from "./secret.js";
 import { log } from "./logger.js";
 import { portFree } from "./ports.js";
 import { waitForBridge } from "./readiness.js";
+import { describeExit, peerExitRemedy, readinessHint, readinessRemedy } from "./exit-cause.js";
 /**
  * Hard ceiling on simultaneously live peers.
  *
@@ -87,7 +88,10 @@ export class PeerRegistry {
         const m = this.procs.get(e.managedId);
         if (m?.exited) {
             const tail = this.procs.tail(e.managedId, 6).join(" | ");
-            throw new BridgeError("peer_exited", `Peer "${id}" exited (code ${m.exitCode})${tail ? `; last output: ${tail}` : ""}.`);
+            // 🔴 `describeExit` RATHER THAN `exitCode` ALONE (266). A SIGKILLed child has a null
+            // code and a signal, and this sentence used to render the null: `exited (code null)`.
+            // See exit-cause.ts for the argument node was handing us and nobody declared.
+            throw new BridgeError("peer_exited", `Peer "${id}" ${describeExit(m.exitCode, m.exitSignal)}${tail ? `; last output: ${tail}` : ""}.`, peerExitRemedy(tail.length > 0));
         }
         return e.client;
     }
@@ -194,10 +198,16 @@ export class PeerRegistry {
         }));
         const notReady = spawned.filter((e) => !e.info.ready);
         if (notReady.length) {
+            // 🔴 THE CAUSE IS COLLECTED, NOT JUST RENDERED (266). `m?.exited` decided one word
+            // of the sentence and was then thrown away, so the hint below was pasted over both
+            // measured causes and was FALSE on one of them — an absent runtime autoload does
+            // not stop a process, it stops a process from ANSWERING. See exit-cause.ts.
+            const causes = [];
             const detail = notReady
                 .map((e) => {
                 const m = this.procs.get(e.managedId);
-                const why = m?.exited ? `exited (code ${m.exitCode})` : "never answered ping";
+                causes.push(m?.exited ? "exited" : "silent");
+                const why = m?.exited ? describeExit(m.exitCode, m.exitSignal) : "never answered ping";
                 const tail = this.procs.tail(e.managedId, 6).join(" | ");
                 return `${e.info.id} on ${e.info.port}: ${why}${tail ? ` — ${tail}` : ""}`;
             })
@@ -206,8 +216,9 @@ export class PeerRegistry {
             // can still runtime_peer_stop{all:true}, and a half-started peer that
             // vanished from the registry is harder to reason about than one that
             // reports why it is not ready.
-            throw new BridgeError("peer_not_ready", `${notReady.length} of ${spawned.length} peer(s) did not become ready. ${detail}. ` +
-                `Is the Breakpoint MCP addon enabled in this project (it registers the runtime autoload)?`);
+            const hint = readinessHint(causes, `Is the Breakpoint MCP addon enabled in this project (it registers the runtime autoload)?`);
+            throw new BridgeError("peer_not_ready", `${notReady.length} of ${spawned.length} peer(s) did not become ready. ${detail}.` +
+                (hint ? ` ${hint}` : ""), readinessRemedy(causes));
         }
         return spawned.map((e) => e.info);
     }

package/dist/tools/processes.js

@@ -4,6 +4,7 @@ import { log } from "../logger.js";
 import { ok, failPath } from "./lsp-common.js";
 import { resolveInsideProject } from "../paths.js";
 import { portFree, portConflictMessage } from "../ports.js";
+import { describeExit } from "../exit-cause.js";
 import { waitForRuntimeBridge, notReadyRemedy } from "../readiness.js";
 const LINE_CAP = 5000;
 /**
@@ -33,7 +34,7 @@ export class ProcessRegistry {
             stdio: ["ignore", "pipe", "pipe"],
             ...(env ? { env: { ...process.env, ...env } } : {}),
         });
-        const m = { id, child, lines: [], seq: 0, exited: false, exitCode: null };
+        const m = { id, child, lines: [], seq: 0, exited: false, exitCode: null, exitSignal: null };
         const ingest = (stream) => (buf) => {
             const text = typeof buf === "string" ? buf : buf.toString("utf8");
             for (const line of text.split(/\r?\n/)) {
@@ -47,10 +48,11 @@ export class ProcessRegistry {
         };
         child.stdout?.on("data", ingest("stdout"));
         child.stderr?.on("data", ingest("stderr"));
-        child.on("exit", (code) => {
+        child.on("exit", (code, signal) => {
             m.exited = true;
             m.exitCode = code;
-            log(`managed process ${id} exited (${code})`);
+            m.exitSignal = signal;
+            log(`managed process ${id} ${describeExit(code, signal)}`);
         });
         this.procs.set(id, m);
         return m;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.78.2",
+  "version": "1.78.3",
   "description": "MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model, captured console output, and MCP resources.",
   "type": "module",
   "license": "MIT",