breakpoint-mcp 1.78.1 → 1.78.2

package/dist/bridge.js

@@ -5,6 +5,7 @@ import { OverdueLedger } from "./late-reply.js";
 import { findNonFinite, describeNonFinite, tolerate, TOLERANT_METHODS } from "./finiteness.js";
 import { remedyForWireError } from "./remedies.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
+import { connectHint, connectRemedy } from "./connect-cause.js";
 export class BridgeError extends Error {
     code;
     /**
@@ -121,7 +122,17 @@ export class BridgeClient {
      * which is worse than saying nothing. Defaults keep the editor bridge's
      * wording byte-identical to what shipped.
      */
-    deadlineKnob = "BREAKPOINT_BRIDGE_TIMEOUT_MS", peerNoun = "the editor") {
+    deadlineKnob = "BREAKPOINT_BRIDGE_TIMEOUT_MS", peerNoun = "the editor", 
+    /**
+     * The env var that names THIS instance's HOST, for the same per-INSTANCE reason
+     * `deadlineKnob` exists (265). The editor bridge takes its address from
+     * BREAKPOINT_BRIDGE_HOST and the runtime bridge and its peers from
+     * BREAKPOINT_RUNTIME_HOST; an unresolved-host remedy naming the wrong one sends the
+     * operator to a knob that cannot move the address they just failed to reach — the
+     * identical defect the late-reply line was given its own knob to avoid. Defaults keep
+     * the editor bridge's wording byte-identical to what shipped.
+     */
+    hostKnob = "BREAKPOINT_BRIDGE_HOST") {
         this.host = host;
         this.port = port;
         this.defaultTimeoutMs = defaultTimeoutMs;
@@ -133,9 +144,12 @@ export class BridgeClient {
         // peer a late reply does, and the two sentences drifting apart would be a bug nobody
         // could see from either side.
         this.peerNoun = peerNoun;
+        this.hostKnob = hostKnob;
     }
     /** Who answers this client — read by the close path and the late-reply ledger alike. */
     peerNoun;
+    /** The env var that moves this client's host — read by the connect path (265). */
+    hostKnob;
     /**
      * A cause this client cannot see, supplied by whoever CAN, as the remedy on a timeout.
      *
@@ -215,7 +229,16 @@ export class BridgeClient {
                 // Recorded for onClose(): if the connection was already up, this reject()
                 // is a no-op on a settled promise and the errno would otherwise be lost.
                 this.lastSocketError = err;
-                reject(new BridgeError(BRIDGE_UNAVAILABLE, `Cannot reach the Godot ${this.label} at ${this.host}:${this.port}. ${this.hint} (${err.message})`));
+                // 🔴 THE ERRNO WAS ALREADY HERE AND ONLY ITS `message` WAS READ (265), which is
+                // 264's close-family finding one step earlier in the same file. `err.code`
+                // separates a port nothing is listening on from a host name that never resolved,
+                // and the hint below was appended to BOTH — telling a caller whose
+                // BREAKPOINT_*_HOST is a typo to go and look at Godot, for a connect where no
+                // packet ever left this machine. `connectHint` suppresses the hint in exactly
+                // that case and returns it untouched otherwise, so every other message a caller
+                // reads is byte-identical to what shipped. See connect-cause.ts.
+                const hint = connectHint(err, this.hint);
+                reject(new BridgeError(BRIDGE_UNAVAILABLE, `Cannot reach the Godot ${this.label} at ${this.host}:${this.port}.${hint ? ` ${hint}` : ""} (${err.message})`, connectRemedy(err, this.peerNoun, this.hostKnob)));
             });
             socket.on("data", (chunk) => this.onData(chunk));
             socket.on("close", () => this.onClose());

package/dist/connect-cause.js

@@ -0,0 +1,124 @@
+/**
+ * What a FAILED CONNECT's errno discriminates, and the next action for each.
+ *
+ * 🔴 WHY THIS EXISTS — 264 answered the CLOSE family and left the CONNECT site in the
+ * census's silent bucket. They are the same shape one step apart: `close-cause.ts` was
+ * written because five close handlers read `cause.message` and threw `cause.code` away,
+ * and `bridge.ts`'s connect handler does exactly that too. Measured at 265 against real
+ * sockets, two families:
+ *
+ * ```
+ * nothing bound the port       code=ECONNREFUSED  syscall=connect      "connect ECONNREFUSED 127.0.0.1:43305"
+ * host name does not resolve   code=ENOTFOUND     syscall=getaddrinfo  "getaddrinfo ENOTFOUND not-a-real-host.invalid"
+ * ```
+ *
+ * and what a caller received for BOTH was one code and one hint:
+ *
+ * ```
+ * [bridge_unavailable] Cannot reach the Godot editor bridge at 127.0.0.1:43305.
+ *                      Is the editor open with the "Breakpoint MCP" plugin enabled? (connect ECONNREFUSED …)
+ * [bridge_unavailable] Cannot reach the Godot editor bridge at not-a-real-host.invalid:6010.
+ *                      Is the editor open with the "Breakpoint MCP" plugin enabled? (getaddrinfo ENOTFOUND …)
+ * ```
+ *
+ * 🔴 AND THE SECOND ONE IS NOT MERELY UNHELPFUL, IT IS WRONG ABOUT WHAT HAPPENED. On
+ * ENOTFOUND the name never resolved, so nothing was contacted: no packet left this
+ * machine, and whether the editor is open and its plugin enabled had no bearing on the
+ * failure. The caller with a typo in `BREAKPOINT_BRIDGE_HOST` is sent to look at Godot.
+ * That is 263 §3.2's rule — a capability read is a question for somebody, and there may be
+ * nobody — arriving at the transport: the hint answers "why can this peer not serve me",
+ * and in the unresolved case there is no peer on the other end of the question.
+ *
+ * 🔴 THE HINT IS SUPPRESSED RATHER THAN REPLACED. `connectHint` returns `""` for the
+ * unresolved family and the instance's own hint for everything else, so the message a
+ * caller reads is BYTE-IDENTICAL to what shipped in every case except the one that was
+ * making a false claim. The next action goes in the `remedy` FIELD, which is the channel
+ * `remedyClause` reads and 264 §1.2 found seven other sites answering around.
+ *
+ * 🔴 AND WHAT IT DELIBERATELY DOES NOT DO — 264 §3.3's rule, kept. An errno outside the
+ * two measured families gets NO remedy and NO hint change: `classifyConnect` returns
+ * `"unclassified"` and `connectRemedy` returns `undefined`, with a test asserting it.
+ * EHOSTUNREACH, ETIMEDOUT, EACCES and EAI_AGAIN are all plausible here and NONE of them
+ * was driven — this container's egress answers an unroutable address with ECONNREFUSED,
+ * so the case could not be produced honestly and is therefore not spoken for. A third
+ * family inheriting one of these sentences by default would be a claim nobody made
+ * wearing the authority of one that was measured.
+ */
+/**
+ * Errnos that mean the address was reached and the connection was REFUSED.
+ *
+ * ECONNREFUSED: the host's stack answered with RST — the machine is there, and nothing is
+ * listening on that port. It is the ordinary "the editor is not running" case, and it is
+ * the one case where the instance hint is exactly right.
+ */
+export const REFUSED_CONNECT_CODES = new Set(["ECONNREFUSED"]);
+/**
+ * Errnos that mean the host NAME never became an address, so nothing was contacted.
+ *
+ * ENOTFOUND: `getaddrinfo` found no record. Note the syscall — this failure happens
+ * before any packet is sent, which is why the peer's own state cannot be the cause and
+ * the hint that names it has to go.
+ *
+ * EAI_AGAIN is deliberately ABSENT: it is a TEMPORARY resolver failure, its next action
+ * is "retry" rather than "fix the name", and 265 did not drive it.
+ */
+export const UNRESOLVED_HOST_CODES = new Set(["ENOTFOUND"]);
+/**
+ * Which of the three a failed connect was.
+ *
+ * Unlike `classifyClose`, a missing `cause` is NOT a meaningful state here: a connect
+ * that fails always fails with an error, and this handler is only ever reached from
+ * `socket.once("error")`. An absent cause is therefore `"unclassified"`, not a fourth
+ * family invented to fill the slot.
+ */
+export function classifyConnect(cause) {
+    if (!cause)
+        return "unclassified";
+    const code = cause.code;
+    if (typeof code !== "string")
+        return "unclassified";
+    if (REFUSED_CONNECT_CODES.has(code))
+        return "refused";
+    if (UNRESOLVED_HOST_CODES.has(code))
+        return "unresolved";
+    return "unclassified";
+}
+/**
+ * The hint that belongs in the MESSAGE, given what actually failed.
+ *
+ * Returns the instance's own hint unchanged for every family except `"unresolved"`,
+ * where the hint is a statement about a peer that was never contacted. Suppressing is
+ * the whole change: nothing is reworded, so every existing caller and test reading the
+ * refused case reads the same bytes.
+ */
+export function connectHint(cause, hint) {
+    return classifyConnect(cause) === "unresolved" ? "" : hint;
+}
+/**
+ * The next action, given who the peer was and which env var names this client's host —
+ * or `undefined` when the errno does not determine one.
+ *
+ * `hostKnob` is per-INSTANCE for the same reason `deadlineKnob` is (see `BridgeClient`'s
+ * constructor): the editor bridge is configured by `BREAKPOINT_BRIDGE_HOST` and the
+ * runtime bridge and its peers by `BREAKPOINT_RUNTIME_HOST`, and a sentence naming the
+ * wrong one sends the operator to a knob that cannot move the address they just failed
+ * to reach.
+ *
+ * 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 connectRemedy(cause, peer, hostKnob) {
+    switch (classifyConnect(cause)) {
+        case "refused":
+            // The errno is NOT repeated: `bridge.ts` already puts `(connect ECONNREFUSED …)` in
+            // the sentence immediately to the left, and a second copy teaches nobody anything.
+            return (`Start ${peer} and retry — the machine answered and refused the connection, ` +
+                `so the address is right and nothing is listening on that port.`);
+        case "unresolved":
+            return (`Check ${hostKnob} — the host name did not resolve, so nothing was contacted ` +
+                `and the state of ${peer} is not what failed here.`);
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=connect-cause.js.map

package/dist/index.js

@@ -30,7 +30,9 @@ async function main() {
     // This instance's deadline comes from BREAKPOINT_RUNTIME_TIMEOUT_MS, not the
     // editor bridge's variable — a late reply here must name the knob that can
     // actually move it, and the peer that answered is the running game.
-    "BREAKPOINT_RUNTIME_TIMEOUT_MS", "the running game");
+    "BREAKPOINT_RUNTIME_TIMEOUT_MS", "the running game", 
+    // And its ADDRESS comes from BREAKPOINT_RUNTIME_HOST, for the same reason (265).
+    "BREAKPOINT_RUNTIME_HOST");
     const lsp = new LspClient(config.lspHost, config.lspPort, config.projectUri, config.lspTimeoutMs);
     // D4 C2: the C# semantic plane. OmniSharp is spawned over stdio (lazily, on the
     // first cs_* call) against the C# project root — so a host without OmniSharp
@@ -50,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.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.78.2" }, { 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

@@ -44,6 +44,35 @@ export class PeerRegistry {
     all() {
         return [...this.peers.values()].map((e) => e.info);
     }
+    /**
+     * The one `unknown_peer` refusal, raised from both the read path and the write path.
+     *
+     * 🔴 WHY THIS IS A FUNCTION (265). `clientFor` and `stop` both refused an unknown id
+     * with the code `unknown_peer`, off the SAME registry, in two sentences that had drifted:
+     *
+     * ```
+     * clientFor("peer-9")   No peer with id "peer-9". Live peers: (none). Spawn peers with runtime_spawn_peers, or omit `peer`…
+     * stop("peer-9")        No peer with id "peer-9". Live peers: (none).
+     * ```
+     *
+     * One named a next action and the other stopped dead after the ids, and nothing in this
+     * repository could see the difference — 264 §1.2 measured why: a next action written
+     * into a message BODY reaches no reader, so `remedyClause()` returned `""` for both and
+     * check 28's grammar arm judged neither. The answer moves into the `remedy` FIELD, which
+     * is the channel that IS read, and the two paths stop being two sentences.
+     *
+     * 🔴 AND THE REMEDY IS BRANCHED ON THE REGISTRY, which is the point of 264's "silent,
+     * but the host holds something that discriminates" column. Telling a caller with three
+     * live peers to spawn some is the wrong next action; telling a caller with none to use
+     * one of the ids above names nothing. The registry answers which sentence is true, and
+     * it was in hand at both sites the whole time.
+     */
+    unknownPeer(id) {
+        const ids = this.live().map((p) => p.id);
+        return new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}.`, ids.length
+            ? `Address one of the live peer ids above, or omit \`peer\` to address the default running game.`
+            : `Spawn peers with runtime_spawn_peers, or omit \`peer\` to address the default running game.`);
+    }
     /**
      * The bridge client addressing one peer. Throws a BridgeError the runtime
      * tools' `fail()` renders — an unknown or dead peer must read as a clear
@@ -51,11 +80,8 @@ export class PeerRegistry {
      */
     clientFor(id) {
         const e = this.peers.get(id);
-        if (!e) {
-            const ids = this.live().map((p) => p.id);
-            throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}. ` +
-                `Spawn peers with runtime_spawn_peers, or omit \`peer\` to address the default running game.`);
-        }
+        if (!e)
+            throw this.unknownPeer(id);
         if (e.stopped)
             throw new BridgeError("peer_stopped", `Peer "${id}" was stopped by runtime_peer_stop.`);
         const m = this.procs.get(e.managedId);
@@ -149,7 +175,11 @@ export class PeerRegistry {
             // The FILE, not resolveBridgeSecret: the addon's _setup_auth() does not
             // read BREAKPOINT_*_SECRET, so a host-launched child authenticates with
             // whatever is on disk regardless of the host's env overrides.
-            () => readProjectSecret(this.cfg.projectPath));
+            () => readProjectSecret(this.cfg.projectPath), 
+            // A peer's deadline and peer-noun are its own, and so is its ADDRESS: peers are
+            // dialled on `cfg.runtimeHost`, so an unresolved-host remedy here must name
+            // BREAKPOINT_RUNTIME_HOST and not the editor bridge's variable (265).
+            "BREAKPOINT_RUNTIME_TIMEOUT_MS", `peer ${id}`, "BREAKPOINT_RUNTIME_HOST");
             const entry = {
                 info: { id, port, pid: managed.child.pid ?? null, role: opts.role ?? null, ready: false },
                 client,
@@ -184,10 +214,8 @@ export class PeerRegistry {
     /** Stop one peer (or all). Repeating is a no-op, so the tool is idempotent. */
     stop(id, all = false) {
         const targets = all ? [...this.peers.keys()] : id ? [id] : [];
-        if (!all && id && !this.peers.has(id)) {
-            const ids = this.live().map((p) => p.id);
-            throw new BridgeError("unknown_peer", `No peer with id "${id}". Live peers: ${ids.length ? ids.join(", ") : "(none)"}.`);
-        }
+        if (!all && id && !this.peers.has(id))
+            throw this.unknownPeer(id);
         const stopped = [];
         for (const t of targets) {
             const e = this.peers.get(t);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.78.1",
+  "version": "1.78.2",
   "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",