breakpoint-mcp 1.78.3 → 1.80.0

package/dist/bridge.js

@@ -65,6 +65,68 @@ export function remedyClause(err) {
     const r = err?.remedy;
     return typeof r === "string" && r !== "" ? ` — ${r}` : "";
 }
+/** The code this class raises when a bridge request outlives its own deadline. */
+export const BRIDGE_TIMEOUT_CODE = "timeout";
+/**
+ * The label `tools/editor/common.ts`'s `fail()` puts in front of a bridge failure.
+ *
+ * 🔴 **ONE BUILDER, TWO READERS, AND THE SECOND ONE WAS A STRING LITERAL UNTIL 268.**
+ * `timeout-caveat.ts` decides whether a mutating tool gets its retry caveat by
+ * looking for `Bridge error [timeout]` inside the rendered envelope — a substring it
+ * spelled out itself, one file away from the template that produces it. That is
+ * `dap-timeout-predicate-reads-prose` again with a far wider blast radius: a reword of
+ * `fail()` would silently stop every non-idempotent tool from warning that a timed-out
+ * mutation may already have landed, and nothing compares the two spellings. Derived here
+ * so the two move together, and check 32 refuses a fresh literal.
+ */
+export function bridgeErrorLabel(code) {
+    return `Bridge error [${code}]`;
+}
+/**
+ * The code raised when the request could not be handed to the socket at all.
+ *
+ * 🔴 **ONE WORD, TWO PRODUCERS, AND ONLY ONE OF THEM HAS A REMEDY THAT FITS (268).** The
+ * ADDON raises `write_failed` too, from `operations.gd`, for a FILE it could not open for
+ * writing — and `error_remedies.gd` answers it with *"Check the target path is inside the
+ * project and not read-only; the number is a Godot Error code."* That sentence is correct
+ * for the addon and nonsense for this site, which has no path, no file and no Godot error
+ * code: it is a TCP socket that went away. The collision was invisible while this branch
+ * was believed unreachable; 268 measured it reachable 200/200 and it became live.
+ *
+ * The CODE is kept and the message and remedy are made to fit — 262's disposition for an
+ * overloaded shipped code, for the same reason: fix what the reader acts on, and leave a
+ * wire vocabulary that callers may already branch on alone. Whether the two producers
+ * should share a word at all is a wire question, and it is enqueued as one rather than
+ * decided here.
+ */
+export const BRIDGE_WRITE_FAILED = "write_failed";
+/**
+ * The next action for a request that never reached the socket.
+ *
+ * 🔴 IT IS THE ONE FAILURE IN THIS CLASS THAT CAN SAY *RETRY* WITHOUT QUALIFICATION, and
+ * that is the whole value of separating it. `timeout-caveat.ts` exists because a bridge
+ * TIMEOUT may already have been applied by the editor; `closeRemedy` cannot promise
+ * otherwise either, since a request in flight when the socket dropped may have landed.
+ * This one is different in a way the host actually knows: the frame was never handed to
+ * the kernel, so nothing can have been applied, so a retry is a first attempt and not a
+ * second. 264's rule — measure N families, speak for N — read in the direction that
+ * licenses a stronger sentence rather than a weaker one.
+ */
+export const WRITE_FAILED_REMEDY = "Retry the call — the request was never sent, so nothing was applied and this is a " +
+    "first attempt rather than a second. A recurrence means the host is tearing the " +
+    "connection down mid-request.";
+/**
+ * The sentence for a request that never reached the socket.
+ *
+ * `cause` is node's own error, kept in a parenthetical rather than used as the whole
+ * message: `Cannot call write after a stream was destroyed` is a true statement about a
+ * Node stream and tells a caller of `node_add` nothing about their call, which is what
+ * this site shipped until 268.
+ */
+export function writeFailedMessage(method, cause) {
+    return (`Bridge request '${method}' was never sent — the connection was torn down between ` +
+        `preparing the request and writing it, so the editor did not receive it (${cause.message}).`);
+}
 /**
  * TCP client for the in-editor Breakpoint MCP addon. Speaks newline-delimited
  * JSON. Requests are correlated to responses by `id`. Connects lazily and
@@ -396,9 +458,15 @@ export class BridgeClient {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
                 // Remember the id BEFORE rejecting, so a reply already in flight is
-                // reconciled rather than dropped as anonymous. The message keeps the
-                // exact `timed out after <n>ms` phrasing — tools/dap.ts:29 and
-                // tools/csdap.ts:31 branch on that substring.
+                // reconciled rather than dropped as anonymous.
+                //
+                // 🔴 THIS COMMENT USED TO SAY THE `timed out after <n>ms` PHRASING WAS
+                // LOAD-BEARING, NAMING `tools/dap.ts:29` AND `tools/csdap.ts:31`. Both line
+                // numbers had drifted by more than a hundred lines, and as of 268 the claim is
+                // false as well: those predicates read `DapError.code`, and this class's own
+                // caveat reader derives its marker from `bridgeErrorLabel`. A comment naming a
+                // line number is a claim that goes stale in silence — which is the whole reason
+                // the join is structural now.
                 this.ledger.note(id, method, timeoutMs);
                 // 🔴 262 §2 CALLED THIS "THE ONE HOST-RAISED FAILURE THAT HAS A KNOWABLE CAUSE",
                 // and said everything else this class raises — "a closed socket, a peer that never
@@ -408,14 +476,30 @@ export class BridgeClient {
                 // line — a peer that never answered really does leave nothing behind — which is
                 // why the one cause the host can supply comes from outside the socket: its own
                 // debugger holding the game. See `setHoldProbe`, and 264's census for the rest.
-                reject(new BridgeError("timeout", `Bridge request '${method}' timed out after ${timeoutMs}ms`, this.holdProbe?.() ?? undefined));
+                reject(new BridgeError(BRIDGE_TIMEOUT_CODE, `Bridge request '${method}' timed out after ${timeoutMs}ms`, this.holdProbe?.() ?? undefined));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer, method });
             socket.write(payload, (err) => {
                 if (err) {
                     clearTimeout(timer);
                     this.pending.delete(id);
-                    reject(new BridgeError("write_failed", err.message));
+                    // 🔴 REACHABLE, AND 265 CONCLUDED THE OPPOSITE FROM THE SAME TECHNIQUE (268).
+                    // 265 broke a live socket four ways and read `bridge_closed` every time, and
+                    // reasoned that `onClose()` always rejects the pending map first. Measured here
+                    // 300/300 at the node level, that ordering is BACKWARDS: on a destroyed socket
+                    // the write callback fires with ERR_STREAM_DESTROYED **before** the `close`
+                    // event, so this line wins whenever the socket dies inside the await gap
+                    // `request()` leaves between `connect()` and here. Driven through the real
+                    // client — `request()` not awaited, `close()` on the next statement — the caller
+                    // received THIS rejection 200 times out of 200. 265's drives all broke the
+                    // socket and then WAITED, which is the one window in which they could not win.
+                    //
+                    // The sentence is worth having because this case knows something the other two
+                    // do not: the payload never left. A `timeout` may have been applied by the
+                    // editor and `bridge_closed` may have been too, so neither can tell a caller to
+                    // retry; this one can, and 267's rule is that a next action rides in the field
+                    // rather than inside the message.
+                    reject(new BridgeError(BRIDGE_WRITE_FAILED, writeFailedMessage(method, err), WRITE_FAILED_REMEDY));
                 }
             });
         });

package/dist/config.js

@@ -111,6 +111,18 @@ function positiveInt(raw, fallback) {
     const n = Number(t);
     return Number.isSafeInteger(n) && n > 0 && n <= 2_147_483_647 ? n : fallback;
 }
+/**
+ * An opt-OUT flag: true unless the operator spelled a recognised falsehood.
+ *
+ * 🔴 THE UNRECOGNISED VALUE KEEPS THE SAFE DEFAULT, AND THAT IS THE OPPOSITE OF
+ * `positiveInt`'s reasoning ON PURPOSE. A malformed deadline falls back because both
+ * outcomes are ordinary; a malformed *guard* setting must not disable the guard, or a
+ * typo — `GODOT_DAP_REQUIRE_INITIALIZED=no thanks` — turns a refusal off silently. Only
+ * `0`, `false`, `off` and `no` are read as intent, case-insensitively.
+ */
+function optOut(raw) {
+    return !/^(0|false|off|no)$/i.test((raw ?? "").trim());
+}
 export function loadConfig() {
     const projectPath = process.env.GODOT_PROJECT ?? process.cwd();
     // The C# project defaults to the main project, but is usually pointed at a
@@ -136,6 +148,7 @@ export function loadConfig() {
         dapTimeoutMs: positiveInt(process.env.GODOT_DAP_TIMEOUT_MS, 20000),
         dapSetVarTimeoutMs: positiveInt(process.env.GODOT_DAP_SETVAR_TIMEOUT_MS, 8000),
         dapEvaluateTimeoutMs: positiveInt(process.env.GODOT_DAP_EVALUATE_TIMEOUT_MS, 8000),
+        dapRequireInitialized: optOut(process.env.GODOT_DAP_REQUIRE_INITIALIZED),
         csDapCmd: process.env.GODOT_CSDAP_CMD ?? "netcoredbg",
         csDapArgs: (process.env.GODOT_CSDAP_ARGS ?? "--interpreter=vscode").split(/\s+/).filter(Boolean),
         // The default program cs_dbg_launch launches is the Mono/.NET Godot binary. GODOT_CSHARP_BIN

package/dist/csdap.js

@@ -1,16 +1,32 @@
 import { EventEmitter } from "node:events";
-import { DapError } from "./dap.js";
+import { DapError, DAP_TIMEOUT_CODE, DAP_UNANNOUNCED_CODE, INITIALIZED_WAIT_CEILING_MS, unannouncedMessage, } from "./dap.js";
 import { OverdueLedger } from "./late-reply.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
+import { timeoutRemedy, unannouncedRemedy } from "./timeout-cause.js";
 /**
  * Who answers this plane, in the words its late-reply ledger already uses.
  *
- * 🔴 ONE CONSTANT, TWO READERS (264). The ledger names this peer when a reply arrives
- * late and `closeRemedy` names it when the connection drops. Two literals would let the
- * same peer acquire two names on the same run, which is the class of drift 257's
- * per-instance deadline noun was written to stop.
+ * 🔴 ONE CONSTANT, THREE READERS (264, 267). The ledger names this peer when a reply
+ * arrives late, `closeRemedy` names it when the connection drops, and `timeoutRemedy`
+ * names it when a deadline fires. Two literals would let the same peer acquire two names
+ * on the same run, which is the class of drift 257's per-instance deadline noun was
+ * written to stop.
  */
 const CSDAP_PEER = "the debug adapter";
+/** The environment variable this plane's deadline comes from — see `dap.ts`'s twin. */
+const CSDAP_TIMEOUT_KNOB = "GODOT_CSDAP_TIMEOUT_MS";
+/**
+ * The next action when the adapter refuses to start a session.
+ *
+ * 🔴 THE LAST OF 264's SEVENTEEN, and the one that most looked like it already had an
+ * answer. The message names the mode and the arguments, which is a description of what
+ * was asked, not of what to do next — measured against a real netcoredbg, the two live
+ * causes are a `program` that is not a built assembly and a project that has not been
+ * compiled, and neither is visible in the argument dump the message already prints.
+ */
+export const CS_START_REMEDY = "Check that the program names a built .NET assembly and that the project compiles — the C# debug adapter refused the session, so nothing is under the debugger and no process was left running.";
+/** The next action when `cs_dbg_restart` is called with no launch behind it. */
+export const CS_RESTART_REMEDY = "Call `cs_dbg_launch` or `cs_dbg_attach` first — a restart reuses the parameters of a launch that already happened, and none has.";
 /**
  * How long `start()` waits for the entry `stopped` event when `stopAtEntry` was
  * requested. Bounded so an adapter that ignores stop-on-entry reports `running`
@@ -51,7 +67,7 @@ export class CsDapClient extends EventEmitter {
      * dropped. `seq` is monotonic and is never reset, so a seq is never reused and
      * a late response can only be its own request's.
      */
-    ledger = new OverdueLedger("C# DAP", CSDAP_PEER, "GODOT_CSDAP_TIMEOUT_MS");
+    ledger = new OverdueLedger("C# DAP", CSDAP_PEER, CSDAP_TIMEOUT_KNOB);
     configured = false;
     /** Persistent watch expressions, re-evaluated at each stop (see evaluateWatches). */
     watches = [];
@@ -128,15 +144,12 @@ export class CsDapClient extends EventEmitter {
             this.configured = false;
             this.sessionStarted = false;
             const detail = closeDetail(cause);
-            // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), IN THE MESSAGE BECAUSE THIS CLASS
-            // HAS NOWHERE ELSE TO PUT IT. `DapError` carries no `remedy` field, and the plane's
-            // `fail()` renders no `remedyClause`, so the next action goes where the caller will
-            // actually read it. 264's census records the asymmetry rather than hiding it: of 25
-            // host-raised failures about the world, 13 are on classes that cannot carry an answer.
+            // 🔴 ON THE FIELD, NOT IN THE MESSAGE (267) — see `dap.ts`'s twin for the whole
+            // argument. What a caller receives is byte-identical; the channel is what changed.
             const remedy = closeRemedy(cause, CSDAP_PEER);
             for (const [, p] of this.pending) {
                 clearTimeout(p.timer);
-                p.reject(new DapError(p.command, `C# DAP connection closed${detail}${remedy ? ` — ${remedy}` : ""}`));
+                p.reject(new DapError(p.command, `C# DAP connection closed${detail}`, remedy));
             }
             this.pending.clear();
             this.emit("closed");
@@ -217,7 +230,9 @@ export class CsDapClient extends EventEmitter {
                 // Remember the seq BEFORE rejecting, so a response already in flight is
                 // reconciled rather than dropped as anonymous.
                 this.ledger.note(seq, command, timeoutMs);
-                reject(new DapError(command, `C# DAP '${command}' timed out after ${timeoutMs}ms`));
+                // 🔴 THE WORDING IS NO LONGER LOAD-BEARING (268) — see `dap.ts`'s twin. The code
+                // is what `tools/csdap.ts`'s `isDapTimeout` reads; the sentence is free.
+                reject(new DapError(command, `C# DAP '${command}' timed out after ${timeoutMs}ms`, timeoutRemedy(CSDAP_PEER, CSDAP_TIMEOUT_KNOB), DAP_TIMEOUT_CODE));
             }, timeoutMs);
             this.pending.set(seq, { command, resolve: resolve, reject, timer });
             this.channel.send({ seq, type: "request", command, arguments: args }).catch((err) => {
@@ -227,15 +242,23 @@ export class CsDapClient extends EventEmitter {
             });
         });
     }
+    /**
+     * Wait for `name`, bounded — resolving **`true` when the event arrived and `false` when
+     * the timer fired**. The twin of `dap.ts`'s, changed for the same measured reason (267):
+     * a `Promise<void>` made a five-second silence and a prompt event the same observable,
+     * so `start()` sent `setBreakpoints` ahead of the event that licenses it and said
+     * nothing. Driven against a stub adapter that never emits `initialized`, `start()`
+     * returned after 5,003 ms having sent the handshake in the conformant order.
+     */
     waitEvent(name, timeoutMs) {
         return new Promise((resolve) => {
             const timer = setTimeout(() => {
                 this.removeListener(name, onEvent);
-                resolve();
+                resolve(false);
             }, timeoutMs);
             const onEvent = () => {
                 clearTimeout(timer);
-                resolve();
+                resolve(true);
             };
             this.once(name, onEvent);
         });
@@ -327,12 +350,18 @@ export class CsDapClient extends EventEmitter {
      * afterwards failed with a bare hex code against a phantom session. The same held
      * for `program: ""` and for `cs_dbg_attach` on a process id that does not exist.
      */
-    async start(mode, args) {
+    async start(mode, args, requireInitialized = true) {
         this.lastStartMode = mode;
         this.lastStartArgs = args;
         this.sessionStarted = false;
-        // Listen for `initialized` before we ask, so we cannot miss it.
-        const onInit = this.waitEvent("initialized", Math.min(this.timeoutMs, 5000));
+        // Listen for `initialized` before we ask, so we cannot miss it. Two windows since
+        // 268 — see `dap.ts`'s twin for the argument. Refusing is the default, so the wait
+        // runs to the caller's own deadline; the five-second ceiling survives on the opt-out
+        // path alone, which exists to reproduce 267's behaviour including its numbers.
+        const initializedWaitMs = requireInitialized
+            ? this.timeoutMs
+            : Math.min(this.timeoutMs, INITIALIZED_WAIT_CEILING_MS);
+        const onInit = this.waitEvent("initialized", initializedWaitMs);
         this.capabilities = await this.request("initialize", {
             clientID: "breakpoint-mcp",
             clientName: "Godot Breakpoint MCP",
@@ -364,7 +393,16 @@ export class CsDapClient extends EventEmitter {
             // EventEmitter and throws when unlistened. This one is safe to ignore.
             this.emit("start_failed", err);
         });
-        await onInit;
+        // 🔴 CAPTURED, NOT DISCARDED (267) — see `dap.ts`'s twin.
+        const initializedSeen = await onInit;
+        // 🔴 REFUSED, NOT REPORTED (268) — and BEFORE `applyAllBreakpoints()`, because that
+        // call is the defect itself. See `dap.ts`'s twin.
+        if (!initializedSeen && requireInitialized) {
+            this.state = "terminated";
+            this.sessionStarted = false;
+            this.configured = false;
+            throw new DapError(mode, unannouncedMessage("The C# debug adapter", mode, initializedWaitMs), unannouncedRemedy(CSDAP_PEER, CSDAP_TIMEOUT_KNOB), DAP_UNANNOUNCED_CODE);
+        }
         await this.applyAllBreakpoints();
         // Arm the entry-stop wait BEFORE configurationDone is sent: netcoredbg can emit
         // `stopped` before its configurationDone response lands, and a listener attached
@@ -389,9 +427,13 @@ export class CsDapClient extends EventEmitter {
             this.state = "terminated";
             void startReq;
             const detail = fatal?.message ?? String(fatal);
+            // 🔴 THE NEXT ACTION MOVED OUT OF THE MESSAGE (267). It read *check that the program
+            // exists and is a .NET assembly* mid-sentence, between a state report and an
+            // argument dump — 264's census counted exactly this shape among the SEVEN that
+            // named an action nothing structural could read. The message now reports state; the
+            // field carries the instruction, and check 28's grammar reader can see it.
             throw new DapError(mode, `the C# debug adapter did not start the session: ${detail}. No debug session is ` +
-                `running — check that the program exists and is a .NET assembly (${mode} args: ` +
-                `${JSON.stringify(args).slice(0, 200)}).`);
+                `running (${mode} args: ${JSON.stringify(args).slice(0, 200)}).`, CS_START_REMEDY);
         }
         this.configured = true;
         this.sessionStarted = true;
@@ -411,6 +453,7 @@ export class CsDapClient extends EventEmitter {
         // simply reports `running`, as before.
         if (entryStop)
             await entryStop;
+        return { initializedSeen, initializedWaitMs };
     }
     threadId() {
         return this.lastStoppedThreadId ?? 1;
@@ -482,7 +525,7 @@ export class CsDapClient extends EventEmitter {
      */
     async restart(overrideArgs = {}, waitMs = 15000) {
         if (!this.lastStartMode || !this.lastStartArgs) {
-            throw new DapError("restart", "no C# debug session to restart — call cs_dbg_launch or cs_dbg_attach first");
+            throw new DapError("restart", "no C# debug session to restart", CS_RESTART_REMEDY);
         }
         const args = { ...this.lastStartArgs, ...overrideArgs };
         if (this.capabilities?.["supportsRestartRequest"] === true) {

package/dist/cslsp.js

@@ -2,6 +2,7 @@ import { fileURLToPath } from "node:url";
 import { LspError } from "./lsp.js";
 import { OverdueLedger } from "./late-reply.js";
 import { closeDetail, closeRemedy } from "./close-cause.js";
+import { timeoutRemedy } from "./timeout-cause.js";
 import { packageVersion } from "./version.js";
 /**
  * Who answers this plane, in the words its late-reply ledger already uses.
@@ -12,6 +13,8 @@ import { packageVersion } from "./version.js";
  * per-instance deadline noun was written to stop.
  */
 const CSLSP_PEER = "the language server";
+/** The environment variable this plane's deadline comes from — see `dap.ts`'s twin. */
+const CSLSP_TIMEOUT_KNOB = "GODOT_CSLSP_TIMEOUT_MS";
 /**
  * Minimal LSP client for the C#/.NET semantic plane (D4 C2). Transport-agnostic:
  * it drives any `JsonRpcChannel`, so production spawns OmniSharp over stdio
@@ -41,7 +44,7 @@ export class CsLspClient {
      * dropped. `nextId` is monotonic and is deliberately NOT reset by onClose(),
      * so an id is never reused and a late reply can only be its own request's.
      */
-    ledger = new OverdueLedger("C# LSP", CSLSP_PEER, "GODOT_CSLSP_TIMEOUT_MS");
+    ledger = new OverdueLedger("C# LSP", CSLSP_PEER, CSLSP_TIMEOUT_KNOB);
     /** Absolute project root path (no trailing slash), used to canonicalize URIs. */
     rootFsPath;
     constructor(channel, rootUri, timeoutMs) {
@@ -139,15 +142,17 @@ export class CsLspClient {
     }
     onClose(cause) {
         const detail = closeDetail(cause);
-        // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), IN THE MESSAGE BECAUSE THIS CLASS
-        // HAS NOWHERE ELSE TO PUT IT. `LspError` carries no `remedy` field, and the plane's
-        // `fail()` renders no `remedyClause`, so the next action goes where the caller will
-        // actually read it. 264's census records the asymmetry rather than hiding it: of 25
-        // host-raised failures about the world, 13 are on classes that cannot carry an answer.
+        // 🔴 THE SAME ERRNO SPLIT `bridge.ts` GOT (264 §3), ON THE FIELD RATHER THAN IN THE
+        // MESSAGE (267). The comment that stood here said `LspError` "carries no `remedy`
+        // field, and the plane's `fail()` renders no `remedyClause`" — true when written, and
+        // the reason 264's census counted this site among the SEVEN that named an action
+        // nothing structural could read. Both halves are gone. **What a caller receives is
+        // byte-identical** and is asserted so: the message ended in ` — ${remedy}` and the
+        // renderer appends exactly that. A change of channel, not of wording.
         const remedy = closeRemedy(cause, CSLSP_PEER);
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new LspError("closed", `C# LSP connection closed${detail}${remedy ? ` — ${remedy}` : ""}`));
+            p.reject(new LspError("closed", `C# LSP connection closed${detail}`, remedy));
         }
         this.pending.clear();
         this.initialized = null;
@@ -169,7 +174,7 @@ export class CsLspClient {
                 // Remember the id BEFORE rejecting, so a reply already in flight is
                 // reconciled rather than dropped as anonymous.
                 this.ledger.note(id, method, timeoutMs);
-                reject(new LspError("timeout", `C# LSP '${method}' timed out after ${timeoutMs}ms`));
+                reject(new LspError("timeout", `C# LSP '${method}' timed out after ${timeoutMs}ms`, timeoutRemedy(CSLSP_PEER, CSLSP_TIMEOUT_KNOB)));
             }, timeoutMs);
             this.pending.set(id, { resolve: resolve, reject, timer });
             this.channel.send({ jsonrpc: "2.0", id, method, params }).catch((err) => {