breakpoint-mcp 1.14.0 → 1.19.0

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -22,7 +22,7 @@ var sink: Callable
 func _log_message(message: String, error: bool) -> void:
 	if sink.is_valid():
 		sink.call("error" if error else "info", message)
-func _log_error(function: String, file: String, line: int, code: String, rationale: String, editor_notify: bool, error_type: int, script_backtraces: Array) -> void:
+func _log_error(_function: String, file: String, line: int, code: String, rationale: String, _editor_notify: bool, error_type: int, _script_backtraces: Array) -> void:
 	if sink.is_valid():
 		var lvl := "warning" if error_type == 1 else "error"
 		var detail := rationale if rationale != "" else code
@@ -45,9 +45,17 @@ const MONITORS := {
 	"audio/output_latency": Performance.AUDIO_OUTPUT_LATENCY,
 }
 
+const BridgeSecret := preload("res://addons/breakpoint_mcp/bridge_secret.gd")
+const PauseLatch := preload("res://addons/breakpoint_mcp/pause_latch.gd")
+
 var _server: TCPServer
 var _clients: Array = [] # Array of {peer, buf}
 var _port: int = DEFAULT_PORT
+## Loopback-auth handshake state (default-on; see bridge_secret.gd), mirroring the
+## editor bridge_server. `_auth_required` is false only when auth is explicitly
+## disabled (BREAKPOINT_BRIDGE_INSECURE) or the secret can't be minted.
+var _secret: String = ""
+var _auth_required: bool = false
 var _log: Array = []     # ring buffer of {seq, level, message}
 var _log_seq: int = 0
 var _tree_dirty: bool = false
@@ -62,6 +70,7 @@ func _ready() -> void:
 	var env_port := OS.get_environment("BREAKPOINT_RUNTIME_PORT")
 	if env_port != "" and env_port.is_valid_int():
 		_port = int(env_port)
+	_setup_auth()
 	_server = TCPServer.new()
 	var err := _server.listen(_port, "127.0.0.1")
 	if err != OK:
@@ -79,6 +88,22 @@ func _ready() -> void:
 	_install_log_capture()
 
 
+## Establish the loopback-auth secret unless explicitly disabled. Default-on:
+## BREAKPOINT_BRIDGE_INSECURE=1 (or =true) turns auth OFF (documented escape
+## hatch). If the secret can't be persisted, run WITHOUT auth rather than
+## bricking the bridge (a broken mint must not lock out the host).
+func _setup_auth() -> void:
+	var insecure := OS.get_environment("BREAKPOINT_BRIDGE_INSECURE").to_lower()
+	if insecure == "1" or insecure == "true":
+		_auth_required = false
+		push_warning("[breakpoint_runtime] BREAKPOINT_BRIDGE_INSECURE set — loopback bridge auth DISABLED")
+		return
+	_secret = BridgeSecret.load_or_mint()
+	_auth_required = _secret != ""
+	if not _auth_required:
+		push_error("[breakpoint_runtime] could not establish bridge secret — running WITHOUT auth")
+
+
 ## Public API: game code can route its own logs here for runtime.get_log to read.
 func push_log(level: String, message: String) -> void:
 	_log_seq += 1
@@ -119,7 +144,7 @@ func _process(_delta: float) -> void:
 	while _server.is_connection_available():
 		var peer := _server.take_connection()
 		if peer:
-			_clients.append({"peer": peer, "buf": ""})
+			_clients.append({"peer": peer, "buf": "", "authed": not _auth_required})
 	var alive: Array = []
 	for c in _clients:
 		var peer: StreamPeerTCP = c["peer"]
@@ -134,6 +159,10 @@ func _process(_delta: float) -> void:
 				var bytes: PackedByteArray = chunk[1]
 				c["buf"] += bytes.get_string_from_utf8()
 		_drain_lines(c)
+		if c.get("close", false):
+			peer.poll()
+			peer.disconnect_from_host()
+			continue
 		alive.append(c)
 	_clients = alive
 	# D3 follow-up: one runtime-tree push per frame if the SceneTree changed.
@@ -154,25 +183,55 @@ func _drain_lines(c: Dictionary) -> void:
 		var line := buf.substr(0, nl).strip_edges()
 		buf = buf.substr(nl + 1)
 		if line != "":
-			_handle_line(c["peer"], line)
+			_handle_line(c, line)
+			if c.get("close", false):
+				break
 	c["buf"] = buf
 
 
-func _handle_line(peer: StreamPeerTCP, line: String) -> void:
+func _handle_line(c: Dictionary, line: String) -> void:
+	var peer: StreamPeerTCP = c["peer"]
 	var parsed: Variant = JSON.parse_string(line)
 	if typeof(parsed) != TYPE_DICTIONARY:
+		if not c.get("authed", false):
+			_deny_unauth(c)
+			return
 		_send(peer, {"id": null, "ok": false, "error": {"code": "bad_json", "message": "Bad request"}})
 		return
 	var req: Dictionary = parsed
 	var id: Variant = req.get("id", null)
 	var method := String(req.get("method", ""))
 	var params: Dictionary = req.get("params", {}) if typeof(req.get("params")) == TYPE_DICTIONARY else {}
+	# Handshake gate: an unauthenticated peer may ONLY authenticate.
+	if not c.get("authed", false):
+		if method == "auth" and BridgeSecret.const_time_eq(String(params.get("secret", "")), _secret):
+			c["authed"] = true
+			_send(peer, {"id": id, "ok": true})
+		else:
+			_deny_unauth(c)
+		return
+	# Pause latch (addon "Pause Agent" control): honor the same editor-set latch the
+	# editor bridge does. While paused, HOLD every new command except a liveness
+	# `ping` — reject without dispatching; the running game is otherwise untouched.
+	# Read cross-process from res://.godot/ (the editor writes it; see pause_latch.gd).
+	if method != "ping" and PauseLatch.is_paused():
+		var held := {"id": id}
+		held.merge(PauseLatch.held_response(method))
+		_send(peer, held)
+		return
 	var result := _dispatch(method, params)
 	var response := {"id": id}
 	response.merge(result)
 	_send(peer, response)
 
 
+## Generic, no-echo denial for an unauthenticated peer; marks the connection for
+## closing. Never reveals the expected secret, the received value, or any detail.
+func _deny_unauth(c: Dictionary) -> void:
+	_send(c["peer"], {"id": null, "ok": false, "error": {"code": "unauthorized"}})
+	c["close"] = true
+
+
 func _send(peer: StreamPeerTCP, obj: Dictionary) -> void:
 	peer.put_data((JSON.stringify(obj) + "\n").to_utf8_buffer())
 
@@ -184,7 +243,7 @@ func _send(peer: StreamPeerTCP, obj: Dictionary) -> void:
 func broadcast_event(uri: String) -> void:
 	for c in _clients:
 		var peer: StreamPeerTCP = c["peer"]
-		if peer and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
+		if peer and c.get("authed", false) and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
 			_send(peer, {"event": "resource.changed", "uri": uri})
 
 
@@ -255,6 +314,16 @@ func _dispatch(method: String, params: Dictionary) -> Dictionary:
 			return _screenshot()
 		"runtime.get_log":
 			return _get_log(params)
+		"runtime.assert_node_state":
+			return _assert_node_state(params)
+		"runtime.assert_scene_structure":
+			return _assert_scene_structure(params)
+		"runtime.assert_perf":
+			return _assert_perf(params)
+		"runtime.assert_screen_text":
+			return _assert_screen_text(params)
+		"runtime.screenshot_diff":
+			return _screenshot_diff(params)
 		_:
 			return _err("unknown_method", "No such method: %s" % method)
 
@@ -438,3 +507,263 @@ func _get_log(params: Dictionary) -> Dictionary:
 		if int(e["seq"]) > since and (levels.is_empty() or levels.has(e["level"])):
 			entries.append(e)
 	return _ok({"entries": entries, "latest_seq": _log_seq, "capture": _log_capture != null})
+
+
+func _assert_node_state(params: Dictionary) -> Dictionary:
+	var node := _resolve(String(params.get("path", "")))
+	if node == null:
+		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
+	var raw_expect: Variant = params.get("expect", {})
+	var expect: Dictionary = raw_expect if typeof(raw_expect) == TYPE_DICTIONARY else {}
+	var tol := float(params.get("tolerance", 0.0))
+	var mismatches: Array = []
+	for prop in expect.keys():
+		var key := String(prop)
+		var expected: Variant = expect[key]
+		var actual_encoded: Variant = Codec.encode(node.get(key))
+		if not _values_match(expected, actual_encoded, tol):
+			mismatches.append({"property": key, "expected": expected, "actual": actual_encoded})
+	return _ok({
+		"path": _path_of(node),
+		"ok": mismatches.is_empty(),
+		"checked": expect.size(),
+		"mismatches": mismatches,
+	})
+
+
+func _assert_scene_structure(params: Dictionary) -> Dictionary:
+	var raw: Variant = params.get("expect", [])
+	var expect: Array = raw if typeof(raw) == TYPE_ARRAY else []
+	var failures: Array = []
+	for entry_v in expect:
+		if typeof(entry_v) != TYPE_DICTIONARY:
+			continue
+		var entry: Dictionary = entry_v
+		var path := String(entry.get("path", ""))
+		var absent := bool(entry.get("absent", false))
+		var node := _resolve(path)
+		if absent:
+			if node != null:
+				failures.append({"path": path, "reason": "expected_absent_but_present"})
+			continue
+		if node == null:
+			failures.append({"path": path, "reason": "missing"})
+			continue
+		if entry.has("type"):
+			var want_type := String(entry["type"])
+			if not node.is_class(want_type) and node.get_class() != want_type:
+				failures.append({"path": path, "reason": "type_mismatch", "expected": want_type, "actual": node.get_class()})
+	return _ok({
+		"ok": failures.is_empty(),
+		"checked": expect.size(),
+		"failures": failures,
+	})
+
+
+func _values_match(expected: Variant, actual: Variant, tol: float) -> bool:
+	var te := typeof(expected)
+	var ta := typeof(actual)
+	var expected_num := te == TYPE_INT or te == TYPE_FLOAT
+	var actual_num := ta == TYPE_INT or ta == TYPE_FLOAT
+	if expected_num and actual_num:
+		return absf(float(actual) - float(expected)) <= tol
+	return _deep_equal(expected, actual)
+
+
+func _deep_equal(a: Variant, b: Variant) -> bool:
+	var ta := typeof(a)
+	var tb := typeof(b)
+	if ta != tb:
+		var an := ta == TYPE_INT or ta == TYPE_FLOAT
+		var bn := tb == TYPE_INT or tb == TYPE_FLOAT
+		if an and bn:
+			return float(a) == float(b)
+		return false
+	if ta == TYPE_DICTIONARY:
+		var da: Dictionary = a
+		var db: Dictionary = b
+		if da.size() != db.size():
+			return false
+		for k in da.keys():
+			if not db.has(k):
+				return false
+			if not _deep_equal(da[k], db[k]):
+				return false
+		return true
+	if ta == TYPE_ARRAY:
+		var aa: Array = a
+		var ba: Array = b
+		if aa.size() != ba.size():
+			return false
+		for i in aa.size():
+			if not _deep_equal(aa[i], ba[i]):
+				return false
+		return true
+	return a == b
+
+
+func _assert_perf(params: Dictionary) -> Dictionary:
+	var raw_baseline: Variant = params.get("baseline", {})
+	var baseline: Dictionary = raw_baseline if typeof(raw_baseline) == TYPE_DICTIONARY else {}
+	var tol := float(params.get("tolerance", 0.0))
+	var raw_dir: Variant = params.get("direction", {})
+	var dir_overrides: Dictionary = raw_dir if typeof(raw_dir) == TYPE_DICTIONARY else {}
+	var regressions: Array = []
+	var monitors := {}
+	var checked := 0
+	for key_v in baseline.keys():
+		var key := String(key_v)
+		if not MONITORS.has(key):
+			continue
+		checked += 1
+		var current := float(Performance.get_monitor(MONITORS[key]))
+		var base_val := float(baseline[key])
+		monitors[key] = current
+		var direction := "higher_better" if key == "time/fps" else "lower_better"
+		if dir_overrides.has(key):
+			direction = String(dir_overrides[key])
+		var passed := true
+		if direction == "higher_better":
+			passed = current >= base_val * (1.0 - tol)
+		else:
+			passed = current <= base_val * (1.0 + tol)
+		if not passed:
+			regressions.append({"key": key, "baseline": base_val, "current": current, "direction": direction})
+	return _ok({
+		"ok": regressions.is_empty(),
+		"checked": checked,
+		"regressions": regressions,
+		"monitors": monitors,
+	})
+
+
+func _text_of(node: Node) -> String:
+	# The visible text a Control exposes via its `text` property (Label / Button /
+	# LineEdit / TextEdit / RichTextLabel / CheckBox / LinkButton …). Non-text nodes
+	# return null from get() and are skipped.
+	var v: Variant = node.get("text")
+	if v is String:
+		return String(v)
+	return ""
+
+
+func _assert_screen_text(params: Dictionary) -> Dictionary:
+	var needle := String(params.get("text", ""))
+	var present := bool(params.get("present", true))
+	var use_regex := bool(params.get("regex", false))
+	var case_sensitive := bool(params.get("case_sensitive", false))
+	var has_min := params.has("min_count")
+	var min_count := int(params.get("min_count", 0))
+	var re: RegEx = null
+	if use_regex:
+		re = RegEx.new()
+		var pattern := needle if case_sensitive else "(?i)" + needle
+		if re.compile(pattern) != OK:
+			return _err("bad_regex", "Invalid regex: %s" % needle)
+	var samples: Array = []
+	var count := 0
+	var base := _base()
+	if base != null:
+		var stack: Array = [base]
+		while not stack.is_empty():
+			var node: Node = stack.pop_back()
+			for child in node.get_children():
+				stack.append(child)
+			if not (node is CanvasItem):
+				continue
+			if not (node as CanvasItem).is_visible_in_tree():
+				continue
+			var txt := _text_of(node)
+			if txt == "":
+				continue
+			var matched := false
+			if use_regex:
+				matched = re.search(txt) != null
+			elif case_sensitive:
+				matched = txt.contains(needle)
+			else:
+				matched = txt.to_lower().contains(needle.to_lower())
+			if matched:
+				count += 1
+				if samples.size() < 20:
+					samples.append({"path": _path_of(node), "text": txt})
+	var ok := (count > 0) if present else (count == 0)
+	if present and has_min:
+		ok = count >= min_count
+	return _ok({
+		"ok": ok,
+		"matches": count,
+		"present": present,
+		"samples": samples,
+	})
+
+
+func _screenshot_diff(params: Dictionary) -> Dictionary:
+	var reference := String(params.get("reference", ""))
+	var vp := get_viewport()
+	if vp == null:
+		return _err("no_viewport", "No viewport")
+	var tex := vp.get_texture()
+	if tex == null:
+		return _err("no_texture", "No viewport texture")
+	var img := tex.get_image()
+	if img == null:
+		return _err("no_image", "Could not read frame")
+	var ref_img := Image.new()
+	var err := ref_img.load(reference)
+	if err != OK:
+		return _err("bad_reference", "Could not load reference image: %s (error %d)" % [reference, err])
+	return _compare_images(img, ref_img, params, reference)
+
+
+func _compare_images(frame: Image, reference_img: Image, params: Dictionary, reference: String) -> Dictionary:
+	var tolerance := float(params.get("tolerance", 0.0))
+	var per_channel := int(params.get("per_channel_threshold", 0))
+	# Work on copies normalized to RGBA8 so get_data() is a byte-aligned comparison.
+	var a := Image.new()
+	a.copy_from(frame)
+	var b := Image.new()
+	b.copy_from(reference_img)
+	a.convert(Image.FORMAT_RGBA8)
+	b.convert(Image.FORMAT_RGBA8)
+	var region_v: Variant = params.get("region")
+	if region_v is Dictionary:
+		var rg: Dictionary = region_v
+		var rect := Rect2i(int(rg.get("x", 0)), int(rg.get("y", 0)), int(rg.get("w", 0)), int(rg.get("h", 0)))
+		a = a.get_region(rect)
+		b = b.get_region(rect)
+	var w := a.get_width()
+	var h := a.get_height()
+	if w != b.get_width() or h != b.get_height():
+		return _ok({
+			"ok": false,
+			"reason": "dimension_mismatch",
+			"diff_ratio": 1.0,
+			"differing_pixels": 0,
+			"total_pixels": 0,
+			"width": w,
+			"height": h,
+			"reference": reference,
+		})
+	var total := w * h
+	var da := a.get_data()
+	var db := b.get_data()
+	var differing := 0
+	var n := da.size()
+	var i := 0
+	while i < n:
+		for c in 4:
+			if absi(int(da[i + c]) - int(db[i + c])) > per_channel:
+				differing += 1
+				break
+		i += 4
+	var ratio := (float(differing) / float(total)) if total > 0 else 0.0
+	return _ok({
+		"ok": ratio <= tolerance,
+		"diff_ratio": ratio,
+		"differing_pixels": differing,
+		"total_pixels": total,
+		"width": w,
+		"height": h,
+		"reference": reference,
+	})

package/addon/breakpoint_mcp/status_dock.gd

@@ -14,6 +14,8 @@ extends VBoxContainer
 ## thread never stalls. LSP/DAP ports are read from EditorSettings, so the dock
 ## reflects the user's actual configuration, not just the defaults.
 
+const PauseLatch := preload("res://addons/breakpoint_mcp/pause_latch.gd")
+
 const DEFAULT_BRIDGE_PORT := 9080
 const DEFAULT_RUNTIME_PORT := 9081
 const DEFAULT_LSP_PORT := 6005
@@ -25,6 +27,7 @@ const PROBE_DEADLINE_MSEC := 1500
 const COLOR_OK := Color(0.38, 0.85, 0.45)
 const COLOR_FAIL := Color(0.92, 0.47, 0.40)
 const COLOR_PENDING := Color(0.62, 0.62, 0.62)
+const COLOR_PAUSED := Color(0.95, 0.73, 0.30)
 
 const PLANES := [
 	{"key": "editor", "name": "editor-bridge"},
@@ -75,6 +78,8 @@ var _probes := {}              # plane key -> {peer, deadline, port}
 var _config_label: Label = null
 var _copy_feedback: Label = null
 var _timer: Timer = null
+var _pause_toggle: CheckButton = null
+var _pause_state: Label = null
 
 
 ## plugin.gd injects the live bridge server so the editor-bridge plane is read
@@ -133,6 +138,27 @@ func _build_ui() -> void:
 		_set_plane(p["key"], "pending", "…")
 	add_child(HSeparator.new())
 
+	# Control: a one-click "Pause Agent" latch honored by the editor + runtime
+	# bridges (pause_latch.gd). Engaged, those two planes hold new agent commands
+	# until resumed — the visible companion to the host signal latch (whole-surface).
+	var ctrl_hdr := Label.new()
+	ctrl_hdr.text = "Control"
+	ctrl_hdr.modulate = Color(1, 1, 1, 0.75)
+	add_child(ctrl_hdr)
+
+	_pause_toggle = CheckButton.new()
+	_pause_toggle.text = "Pause Agent"
+	_pause_toggle.tooltip_text = "Hold new agent commands on the editor + runtime bridges. In-flight ops finish and a bare ping still answers; resume to continue."
+	_pause_toggle.toggled.connect(_on_pause_toggled)
+	add_child(_pause_toggle)
+
+	_pause_state = Label.new()
+	_pause_state.add_theme_font_size_override("font_size", 12)
+	_pause_state.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
+	add_child(_pause_state)
+
+	add_child(HSeparator.new())
+
 	var cfg_hdr := Label.new()
 	cfg_hdr.text = "Config"
 	cfg_hdr.modulate = Color(1, 1, 1, 0.75)
@@ -197,6 +223,7 @@ func _refresh() -> void:
 	_start_probe("lsp", _lsp_port())
 	_start_probe("dap", _dap_port())
 	_update_config_line()
+	_update_pause_ui()
 
 
 func _update_editor_plane() -> void:
@@ -227,6 +254,27 @@ func _on_copy_pressed() -> void:
 		_copy_feedback.text = "Copied the mcpServers snippet to the clipboard."
 
 
+func _on_pause_toggled(pressed: bool) -> void:
+	PauseLatch.set_paused(pressed)
+	_update_pause_ui()
+
+
+## Reflect the latch state in the toggle + label. Called on every refresh so an
+## external change (plugin enable/disable clears it, or the host) shows here too;
+## set_pressed_no_signal avoids re-firing `toggled` back into set_paused.
+func _update_pause_ui() -> void:
+	if _pause_toggle == null or _pause_state == null:
+		return
+	var paused := PauseLatch.is_paused()
+	_pause_toggle.set_pressed_no_signal(paused)
+	if paused:
+		_pause_state.text = "PAUSED — editor + runtime bridges are holding new agent commands."
+		_pause_state.add_theme_color_override("font_color", COLOR_PAUSED)
+	else:
+		_pause_state.text = "Running — agent commands flow normally."
+		_pause_state.add_theme_color_override("font_color", COLOR_OK)
+
+
 # --- ports -----------------------------------------------------------------
 
 func _project_path() -> String:

package/dist/bridge.js

@@ -27,6 +27,7 @@ export class BridgeClient {
     defaultTimeoutMs;
     label;
     hint;
+    secretProvider;
     socket = null;
     connecting = null;
     buffer = "";
@@ -34,12 +35,21 @@ export class BridgeClient {
     eventListeners = new Set();
     wantConnected = false;
     reconnectTimer = null;
-    constructor(host, port, defaultTimeoutMs, label = "editor bridge", hint = 'Is the editor open with the "Breakpoint MCP" plugin enabled?') {
+    constructor(host, port, defaultTimeoutMs, label = "editor bridge", hint = 'Is the editor open with the "Breakpoint MCP" plugin enabled?', 
+    /**
+     * Loopback-auth secret provider, read lazily on each connect. When it
+     * returns a non-empty string the client sends it as the FIRST line on the
+     * connection (see connect()); null/undefined → no auth line, matching an
+     * insecure or not-yet-provisioned bridge. Lazy so a secret minted after the
+     * host started (editor launched later) is picked up on the next (re)connect.
+     */
+    secretProvider) {
         this.host = host;
         this.port = port;
         this.defaultTimeoutMs = defaultTimeoutMs;
         this.label = label;
         this.hint = hint;
+        this.secretProvider = secretProvider;
     }
     /** Register a listener for addon-pushed resource-change events. */
     onResourceChanged(cb) {
@@ -57,6 +67,17 @@ export class BridgeClient {
                 this.socket = socket;
                 this.connecting = null;
                 this.clearReconnect();
+                // Loopback-auth handshake: if a secret is available it MUST be the first
+                // line on the connection. TCP preserves order and the addon drains lines
+                // sequentially, so this is guaranteed to be processed before any request
+                // line — no await needed. With no secret we send nothing and behave
+                // exactly as before (backward-compatible with an insecure bridge). The
+                // addon's auth reply carries no id, so onMessage() ignores it; on a
+                // failed handshake the addon closes the socket and onClose() reconnects.
+                const secret = this.secretProvider?.() ?? null;
+                if (secret) {
+                    socket.write(JSON.stringify({ method: "auth", params: { secret } }) + "\n");
+                }
                 log(`bridge connected to ${this.host}:${this.port}`);
                 resolve(socket);
             });