breakpoint-mcp 1.74.1 → 1.76.0

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 { waitForRuntimeBridge, notReadyRemedy } from "../readiness.js";
 const LINE_CAP = 5000;
 /**
  * Runs Godot as a MANAGED child (piped stdio) so the host captures ALL stdout/
@@ -86,6 +87,8 @@ export function registerProcessTools(server, cfg) {
         title: "Run project (managed, captured output)",
         description: "Run the project as a managed child process with captured stdout/stderr, so godot_output can read ALL print()/error output. " +
             "Returns a process id. Use this instead of godot_run_project when you want the game's console log. " +
+            "WAITS until the game's runtime bridge answers ping and reports bridge_ready, exactly as godot_run_project " +
+            "does — no runtime_* tool is reachable before it does. " +
             "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
             "runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
             "than one game at once.",
@@ -97,12 +100,24 @@ export function registerProcessTools(server, cfg) {
                 .describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
                 "bridge will NOT be reachable — use only when you want the process for its console output or side " +
                 "effects and will not call any runtime_* tool against it."),
+            wait_timeout_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("How long to wait for the runtime bridge to answer ping, in ms (default 15000, the runtime bridge's own " +
+                "deadline). 0 returns as soon as the process is spawned, reporting bridge_ready false and " +
+                "bridge_wait_ms 0 — waited-not-at-all, which a caller can tell apart from waited-and-lost."),
         },
     }, 
     // 🔴 `godot_run_project`'s TWIN, in a different file, with the same defect —
     // measured the same way and launching the same escaping argv. 1.42.0's lesson
     // ("the second call site is the interesting one") applied before the fact.
-    async ({ scene, allow_port_conflict }) => {
+    //
+    // 🔴 AND THE SAME LESSON AGAIN AT 257 FOR THE READINESS RACE. The queue row
+    // `run-project-returns-before-bridge` names only `godot_run_project`; this
+    // returned `running: true` at the same false moment and no row said so.
+    async ({ scene, allow_port_conflict, wait_timeout_ms }) => {
         try {
             if (scene !== undefined)
                 resolveInsideProject(scene, cfg.projectPath, "scene");
@@ -114,7 +129,16 @@ export function registerProcessTools(server, cfg) {
             return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
         }
         const m = registry.run(cfg, scene ? [scene] : []);
-        return ok({ id: m.id, pid: m.child.pid ?? null, running: true, scene: scene ?? null });
+        const readiness = await waitForRuntimeBridge(cfg, wait_timeout_ms ?? cfg.runtimeTimeoutMs);
+        return ok({
+            id: m.id,
+            pid: m.child.pid ?? null,
+            running: true,
+            scene: scene ?? null,
+            bridge_ready: readiness.ready,
+            bridge_wait_ms: readiness.waited_ms,
+            bridge_note: readiness.ready ? null : notReadyRemedy(cfg, readiness.waited_ms),
+        });
     });
     server.registerTool("godot_output", {
         title: "Read managed process output",

package/dist/tools/runtime.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { isTransportUnavailable, remedyClause } from "../bridge.js";
 import { MAX_PEERS } from "../peers.js";
 import { gate } from "../confirm.js";
 import { ok, failPath } from "./lsp-common.js";
@@ -26,7 +27,7 @@ function fail(err) {
     const be = err;
     return {
         isError: true,
-        content: [{ type: "text", text: `Runtime error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}` }],
+        content: [{ type: "text", text: `Runtime error [${be?.code ?? "error"}]: ${be?.message ?? String(err)}${remedyClause(err)}` }],
     };
 }
 /**
@@ -259,14 +260,21 @@ export function registerRuntimeTools(server, runtime, peers, config) {
             "Capture the baseline earlier with runtime_get_monitors and pass it back inline. Pass direction is inferred " +
             "(time/fps is higher-better; every other monitor is lower-better) unless overridden per key.",
         inputSchema: {
-            // 🔴 226 §2 — `.finite()` REFUSES `1e999` AT THE DOOR AND MOVES NO BYTE ON THE
-            // WIRE. `zodToJsonSchema` emits `{"type":"number"}` for both forms, measured, so
-            // this narrows what the host accepts without changing what it advertises. Before
-            // it, a well-formed call carrying `1e999` reached `float(baseline[key])` in
-            // runtime_bridge.gd as `inf` and came back as `1e99999` — the one non-finite path
-            // in this tree that needed no engine edge case at all.
+            // 🔴 226 §2 — `1e999` MUST NOT REACH `float(baseline[key])` IN runtime_bridge.gd,
+            // where it arrives as `inf` and comes back as `1e99999`: the one non-finite path in
+            // this tree that needs no engine edge case at all, only a well-formed call.
+            //
+            // 🆕 255 — AND THE `.finite()` THAT CLOSED IT IS GONE, BECAUSE THE BASE TYPE CLOSED
+            // IT. Under the major this tree left, `z.number()` accepted ±Infinity and the
+            // refinement was the whole guard; under the installed one `z.number()` refuses it
+            // and `.finite()` contributes NO check and NO bag entry — measured, not assumed:
+            // `wire_invisible_gate.mjs` found the roster row it had been pinned by standing over
+            // nothing. A call that adds no rule is a sentence wearing a rule's clothes, and this
+            // repository has spent three sessions deleting those. What holds the door now is
+            // asserted in `finiteness.test.ts` against the INSTALLED zod, so a future major that
+            // relaxes `z.number()` reddens there rather than silently re-opening this line.
             baseline: z
-                .record(z.string(), z.number().finite())
+                .record(z.string(), z.number())
                 .describe("Monitor key -> baseline value (capture earlier via runtime_get_monitors)"),
             tolerance: z
                 .number()
@@ -357,7 +365,9 @@ export function registerRuntimeTools(server, runtime, peers, config) {
         title: "Runtime await condition",
         description: "Poll a property on a LIVE node until it satisfies a comparison, or a timeout elapses (read-only verification). " +
             "op is eq | ne | gt | ge | lt | le (the ordered operators require numeric values). Use this to wait for the " +
-            "running game to reach a state before asserting on it — e.g. wait for hp le 0, then runtime_assert_screen_text.",
+            "running game to reach a state before asserting on it — e.g. wait for hp le 0, then runtime_assert_screen_text. " +
+            "An unreachable runtime bridge is retried until the timeout rather than failing on the first poll, so this " +
+            "tool can also be used to wait for a game that is still booting.",
         inputSchema: {
             path: z.string().describe("Node path (relative to the current scene; '/root/...' absolute allowed)"),
             property: z.string().describe("Property to read on each poll"),
@@ -388,7 +398,21 @@ export function registerRuntimeTools(server, runtime, peers, config) {
                 res = (await client.request("runtime.get_property", { path, property }));
             }
             catch (err) {
-                return fail(err);
+                // 🔴 THE ONE WAITING TOOL DID NOT WAIT FOR THE ONE THING WORTH WAITING
+                // FOR (249, closed 257). Every error ended the loop here, so a caller
+                // that set timeout_ms 15000 against a game that was still booting got
+                // an answer in 2 ms with polls 1 — `deadline` and `sleep(interval)`
+                // are both downstream of this catch and were never reached.
+                //
+                // `bridge_unavailable` is the transport saying *not yet*; every other
+                // code is the game saying *no* — a missing node, an unknown property,
+                // a refused method — and retrying those would turn a precise failure
+                // into a slow one. So the retry is scoped to the one code, and it is
+                // still bounded by the caller's own deadline rather than by a new one.
+                if (!isTransportUnavailable(err) || Date.now() >= deadline)
+                    return fail(err);
+                await sleep(interval);
+                continue;
             }
             last = res?.value ?? null;
             if (compareValues(last, value, operator)) {

package/dist/tools/tabletop.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { z } from "zod";
+import { remedyClause } from "../bridge.js";
 import { gate } from "../confirm.js";
 import { readFileText, resolveExistingFile, resolveInsideProject, resolveWriteTarget } from "../paths.js";
 /**
@@ -36,7 +37,7 @@ function fail(err) {
     const message = be?.message ?? String(err);
     return {
         isError: true,
-        content: [{ type: "text", text: `Tabletop compose error [${code}]: ${message}` }],
+        content: [{ type: "text", text: `Tabletop compose error [${code}]: ${message}${remedyClause(err)}` }],
     };
 }
 /** A bad-input failure that reads like a bridge error but never reaches the bridge. */

package/dist/wire-defaults.js

@@ -6,10 +6,19 @@ import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
  * conforming peer does not already assume. Both are removed on the way out.
  *
  *  1. 🔴 `"$schema": "http://json-schema.org/draft-07/schema#"`, inside EVERY input and
- *     output schema. Nobody in this repo writes it: the SDK converts our Zod through
- *     `zod-to-json-schema`, which defaults to draft-07, and offers no target knob on the
- *     Zod-v3 path (`server/zod-json-schema-compat.js` — the `target` option is read only
- *     by the Zod-v4 branch). MCP fixes the DEFAULT dialect at JSON Schema 2020-12 and
+ *     output schema. Nobody in this repo writes it: the SDK converts our Zod and asks for
+ *     draft-07 while doing it.
+ *
+ *     🆕 255 — AND MOVING TO THE ZOD-v4 BRANCH DID NOT CHANGE THAT, WHICH THE PARAGRAPH
+ *     THIS REPLACES IMPLIED IT WOULD. The old text read "the `target` option is read only
+ *     by the Zod-v4 branch", which is true and useless: `server/mcp.js` calls
+ *     `toJsonSchemaCompat` with no `target` at either version, and the v4 branch maps an
+ *     absent target to `'draft-7'` before handing it to zod's own converter. So the
+ *     declaration on the wire is the SDK's choice and not the library's, it survived a
+ *     major bump unchanged, and this strip stays necessary — the same conclusion the
+ *     migration spike reached from the outside, now measured from inside the tree.
+ *
+ *     MCP fixes the DEFAULT dialect at JSON Schema 2020-12 and
  *     requires every implementation to support it; a `$schema` field is an EXPLICIT
  *     SWITCH to a dialect nobody is obliged to support and which a peer MUST reject
  *     gracefully if it does not. So this is not decoration and it is not a trim:
@@ -49,12 +58,65 @@ export const DIALECT_SENSITIVE = [
     ["exclusiveMinimum", (v) => typeof v === "boolean"], // draft-04 form
     ["exclusiveMaximum", (v) => typeof v === "boolean"], // draft-04 form
     ["dependencies", () => true], //                  split into dependentSchemas/dependentRequired
-    ["definitions", () => true], //                   $defs in 2020-12
-    ["$defs", () => true], //                         2020-12 only — the label would be wrong already
     ["prefixItems", () => true], //                   2020-12 only
     ["unevaluatedProperties", () => true], //         2020-12 only
     ["unevaluatedItems", () => true], //              2020-12 only
 ];
+/**
+ * The definition CONTAINERS, which are the one entry above that could not be decided from
+ * its own value.
+ *
+ * 🔴 255 — AND THEY WERE ON THE LIST FOR A SPELLING DIFFERENCE THAT DOES NOT REACH A
+ * REFERENCE. `definitions` is draft-07's container and `$defs` is 2020-12's, so each is an
+ * unknown keyword under the other dialect — and an unknown keyword is one both specs
+ * require a validator to IGNORE. What actually resolves a reference is `$ref`, and
+ * `"#/definitions/X"` is a URI-reference resolved as a JSON Pointer into the same schema
+ * resource under BOTH dialects: the pointer walks the document by key, and it does not
+ * care whether the key it walks through is vocabulary or not.
+ *
+ * So the container is dialect-bound only when something inside it is REACHED BY A NAME
+ * rather than by a path — `$anchor` (2020-12 only) or a nested `$id` (a new base URI in
+ * both, resolved differently) — or when a `$ref` anywhere in the document is not a plain
+ * local pointer. That is the predicate below, and it is a property of the WHOLE document,
+ * which is why it could not live in the table above.
+ *
+ * 🔴 THIS WAS MEASURED BEFORE IT WAS BELIEVED, AND IT IS MEASURED AGAIN ON EVERY RUN.
+ * `wire_defaults.test.ts` compiles the STRIPPED schema under a strict 2020-12 validator
+ * and the declared one under draft-07, and compares their verdicts on probe instances —
+ * Ajv is a second opinion with no stake in this argument. The fail-safe is not weakened:
+ * a container that is reached by name, or a reference that leaves the document, still
+ * keeps its declaration.
+ */
+const CONTAINER_KEYS = ["definitions", "$defs"];
+/** Reached by NAME rather than by path — the two ways a container stops being inert. */
+const NAME_REACHED = new Set(["$id", "$anchor", "$dynamicAnchor", "$dynamicRef", "$recursiveAnchor", "$recursiveRef"]);
+/**
+ * Can a definition container be renamed between dialects without changing meaning?
+ * A property of the whole document: every `$ref` in it must be a plain local pointer, and
+ * nothing anywhere may be reached by name.
+ */
+export function containersInert(doc) {
+    let inert = true;
+    const walk = (node) => {
+        if (!inert || node === null || typeof node !== "object")
+            return;
+        if (Array.isArray(node))
+            return node.forEach(walk);
+        for (const [k, v] of Object.entries(node)) {
+            if (NAME_REACHED.has(k)) {
+                inert = false;
+                return;
+            }
+            if (k === "$ref" && !(typeof v === "string" && v.startsWith("#/"))) {
+                inert = false;
+                return;
+            }
+            walk(v);
+        }
+    };
+    walk(doc);
+    return inert;
+}
 /** Keys under these keywords are AUTHOR-CHOSEN NAMES, not schema vocabulary. */
 const NAME_BEARING = new Set(["properties", "patternProperties", "definitions", "$defs"]);
 /**
@@ -65,12 +127,20 @@ const NAME_BEARING = new Set(["properties", "patternProperties", "definitions",
  * have kept the declaration on the whole surface; the hit was `scene_get_dependencies`'s
  * output field, a property NAMED dependencies. A walker that cannot tell a keyword from a
  * key reads an author's vocabulary as the protocol's.
+ *
+ * 🔴 THE CONTAINER ANSWER IS COMPUTED ONCE, AT THE DOCUMENT, AND CARRIED DOWN. Whether
+ * `definitions` is load-bearing is not readable from `definitions` — see `containersInert`
+ * — so the recursion threads the document's answer rather than re-deriving a different one
+ * at each level, which is how the same schema would get two verdicts from one walk.
  */
 export function dialectSensitive(node, inNamePosition = false) {
+    return walkSensitive(node, inNamePosition, containersInert(node));
+}
+function walkSensitive(node, inNamePosition, inert) {
     if (node === null || typeof node !== "object")
         return false;
     if (Array.isArray(node))
-        return node.some((v) => dialectSensitive(v, false));
+        return node.some((v) => walkSensitive(v, false, inert));
     const obj = node;
     // draft-07 ignores keywords adjacent to $ref; 2020-12 applies them.
     if (obj.$ref !== undefined && Object.keys(obj).length > 1)
@@ -80,8 +150,10 @@ export function dialectSensitive(node, inNamePosition = false) {
             for (const [key, matches] of DIALECT_SENSITIVE)
                 if (k === key && matches(v))
                     return true;
+            if (!inert && CONTAINER_KEYS.includes(k))
+                return true;
         }
-        if (dialectSensitive(v, NAME_BEARING.has(k)))
+        if (walkSensitive(v, NAME_BEARING.has(k), inert))
             return true;
     }
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.74.1",
+  "version": "1.76.0",
   "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",
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.25.76"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",