breakpoint-mcp 1.29.0 → 1.73.1

package/README.md

@@ -3,7 +3,7 @@
 The MCP **host** for [Breakpoint MCP](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp) —
 a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
 Godot game engine to AI coding assistants across four planes: headless CLI, the live
-editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **289 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **291 tools
 + 6 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
 Developed and tested with **Claude**; because MCP is an open protocol, other clients can
 connect too (currently untested — reports welcome).

package/addon/breakpoint_mcp/operations.gd

@@ -7,7 +7,7 @@ extends RefCounted
 ## wrapped in the EditorUndoRedoManager so a human can Ctrl-Z anything the assistant did.
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
-const ADDON_VERSION := "1.9.2"
+const ADDON_VERSION := "1.9.8"
 
 var _plugin: EditorPlugin
 
@@ -317,6 +317,10 @@ func dispatch(method: String, params: Dictionary) -> Dictionary:
 			return _ok(_selection_get())
 		"selection.set":
 			return _selection_set(params)
+		"main_screen.get":
+			return _main_screen_get()
+		"main_screen.set":
+			return _main_screen_set(params)
 		"classdb.get_class":
 			return _classdb_get_class(params)
 		"classdb.reference":
@@ -683,6 +687,119 @@ func _selection_set(params: Dictionary) -> Dictionary:
 	return _ok({"selection": applied})
 
 
+# ------------------------------------------------- main-screen tab ----------
+# Godot keeps the INACTIVE main-screen tab's viewport alive at its minimum size,
+# so screenshot_editor on the wrong tab "succeeds" and returns a 2x2 placeholder.
+# The host has guarded that since #139 by rejecting anything under 8px, but the
+# error could only tell the caller to switch tabs by hand -- there was no tool to
+# do it with, which is a dead end for the assistant this addon exists to serve.
+#
+# Tab names are NOT hardcoded anywhere here. The engine reports them, they differ
+# between versions (Godot 4.6 added "Game"), and a caller that asks for one that
+# does not exist gets the live list back in the error. `_main_screen_set` matches
+# case-insensitively so "2d" works as well as the engine's own "2D".
+#
+# Both EditorInterface methods are reached through call()/has_method rather than
+# literally, for the reason spelled out on _scene_close: a literal call to a
+# method the running engine lacks fails at PARSE time and takes the WHOLE addon
+# down on that version, not just this tool. get_editor_main_screen is 4.1+ and
+# set_main_screen_editor is 4.0+, so both should be present across this repo's
+# 4.3/4.5/4.7 matrix -- the guard is here so that being wrong about that degrades
+# to one tool reporting `unsupported` instead of the plugin failing to load.
+func _main_screen_root() -> Node:
+	if not EditorInterface.has_method("get_editor_main_screen"):
+		return null
+	return EditorInterface.call("get_editor_main_screen")
+
+
+# The container's children do NOT carry the tab names. Measured on 4.7, the five
+# children are named @CanvasItemEditor@10149, @Node3DEditor@10909, two
+# @WindowWrapper@... and @EditorAssetLibrary@... -- Godot's auto-generated node
+# names, which `set_main_screen_editor` does not accept. The tab name it DOES
+# accept ("2D", "3D", "Script", "Game", "AssetLib") is the EditorPlugin's name,
+# which is not on the control. So the label is derived from the control's class:
+const _MAIN_SCREEN_LABELS := {
+	"CanvasItemEditor": "2D",
+	"Node3DEditor": "3D",
+	"ScriptEditor": "Script",
+	"GameView": "Game",
+	"EditorAssetLibrary": "AssetLib",
+}
+
+
+func _main_screen_label(c: Node) -> String:
+	var cls := c.get_class()
+	if _MAIN_SCREEN_LABELS.has(cls):
+		return String(_MAIN_SCREEN_LABELS[cls])
+	# Script and Game are wrapped in a WindowWrapper (the "make floating" feature),
+	# so the identifying class is one level down. Measured: ['Window','ScriptEditor']
+	# and ['Window','GameView'].
+	for k in c.get_children():
+		var kcls := k.get_class()
+		if _MAIN_SCREEN_LABELS.has(kcls):
+			return String(_MAIN_SCREEN_LABELS[kcls])
+	# A third-party EditorPlugin main screen, or a future built-in this map predates.
+	# Its real tab name is the plugin's get_plugin_name(), which is not reachable from
+	# here -- so report something honest rather than inventing one. set_main_screen_editor
+	# is still given the caller's string verbatim, so such a tab remains switchable by
+	# name even though this list cannot spell it.
+	var nm := String(c.name)
+	return cls if nm.begins_with("@") else nm
+
+
+func _main_screen_state() -> Dictionary:
+	# The active tab is the one visible child; the editor shows exactly one at a time.
+	# Reported as null rather than guessed if somehow none is visible.
+	var mains := _main_screen_root()
+	var available: Array = []
+	var active: Variant = null
+	if mains == null:
+		return {"active": null, "available": available}
+	for c in mains.get_children():
+		var label := _main_screen_label(c)
+		available.append(label)
+		if c is Control and (c as Control).visible:
+			active = label
+	return {"active": active, "available": available}
+
+
+func _main_screen_get() -> Dictionary:
+	if _main_screen_root() == null:
+		return _err("unsupported", "main_screen_get requires EditorInterface.get_editor_main_screen (Godot 4.1+)")
+	return _ok(_main_screen_state())
+
+
+func _main_screen_set(params: Dictionary) -> Dictionary:
+	if not EditorInterface.has_method("set_main_screen_editor"):
+		return _err("unsupported", "main_screen_set requires EditorInterface.set_main_screen_editor")
+	var state := _main_screen_state()
+	var available: Array = state.get("available", [])
+	var want := String(params.get("name", ""))
+	if want == "":
+		return _err("bad_params", "name is required (one of: %s)" % ", ".join(PackedStringArray(available)))
+	# Resolve case-insensitively against the derived labels so "2d" works, but fall
+	# back to the caller's string verbatim when nothing matches. The label map cannot
+	# spell a third-party plugin's main screen (see _main_screen_label), and the
+	# engine's own lookup can -- so a name this addon does not recognise is still
+	# WORTH TRYING rather than rejected here.
+	var target := want
+	for nm in available:
+		if String(nm).to_lower() == want.to_lower():
+			target = String(nm)
+			break
+	EditorInterface.call("set_main_screen_editor", target)
+	# Verify by READ-BACK, not by trusting the call. set_main_screen_editor returns
+	# nothing and silently does nothing for a name it does not know, so this is the
+	# only way to tell a successful switch from a typo -- and it is what makes the
+	# verbatim fallback above safe. It also means the caller's next move (usually a
+	# screenshot) acts on what the editor actually did.
+	var after := _main_screen_state()
+	var now := String(after.get("active", ""))
+	if now.to_lower() != target.to_lower():
+		return _err("not_found", "No main-screen tab named \"%s\" — the editor is still on \"%s\". Available: %s" % [want, now, ", ".join(PackedStringArray(available))])
+	return _ok({"active": after.get("active"), "available": after.get("available"), "requested": target})
+
+
 func _classdb_get_class(params: Dictionary) -> Dictionary:
 	var cls := String(params.get("class_name", ""))
 	if cls == "" or not ClassDB.class_exists(cls):
@@ -1294,10 +1411,71 @@ func _scene_get_dependencies(params: Dictionary) -> Dictionary:
 		return _err("bad_params", "Current scene has no saved path yet")
 	if not ResourceLoader.exists(target):
 		return _err("not_found", "Scene not found: %s" % target)
+	# 🔴 THE ENTRY GODOT HANDS BACK IS NOT A PATH, AND FOR SOME DEPENDENCIES IT IS THE
+	# ONLY SPELLING THAT DOES NOT LOAD (session 169 §5). Measured on 4.7 against the
+	# example project, with controls:
+	#
+	#   res://main.tscn            -> "uid://ccgi4n26nbyku::::res://player.gd"   (2 segments)
+	#   res://demo/demo.tscn       -> "res://demo/demo_snowman.gd"               (1 segment)
+	#
+	# The shape is HETEROGENEOUS — it depends on whether the dependency has a `.uid`
+	# sidecar — so `dependencies` was an array a caller could not parse without already
+	# knowing the rule. Fed to resource_load verbatim, the two-segment form answers
+	# `not_found`, while BOTH of its halves load fine on their own. The tool was handing
+	# out the one spelling that works with nothing.
+	#
+	# This is #181's defect in a read-only tool: a value echoed from the engine and
+	# presented as an answer nobody had measured. Same fix as #181 — the field is made to
+	# mean what its description says, and nothing is destroyed: the engine's own encoding
+	# is preserved verbatim under `dependencies_raw`.
+	#
+	# 🔴 THE FALLBACK NEVER DROPS AN ENTRY. An unrecognised shape (no res:// or user://
+	# segment) is passed through whole rather than skipped: a splitter that silently
+	# discards what it does not understand would shrink the dependency list and look
+	# cleaner for it, which is this session's entire subject.
 	var deps: Array = []
+	var raw: Array = []
+	var uids: Array = []
 	for d in ResourceLoader.get_dependencies(target):
-		deps.append(String(d))
-	return _ok({"path": target, "dependencies": deps})
+		var entry := String(d)
+		var split := split_dependency_entry(entry)
+		raw.append(entry)
+		deps.append(split["path"])
+		uids.append(split["uid"])
+	return _ok({
+		"path": target,
+		"dependencies": deps,
+		"dependencies_raw": raw,
+		"dependency_uids": uids,
+	})
+
+
+## Split one ResourceLoader.get_dependencies entry into its loadable path and its UID.
+##
+## 🔴 A SEPARATE, PUBLIC FUNCTION ON PURPOSE. Inlined in the loop, two of its branches
+## were unreachable from any scene the example project contains — a mutation sweep proved
+## it (169 §7): making the splitter DROP unrecognised entries, and matching the UID prefix
+## as loosely as `begins_with("u")`, both SURVIVED with the suite fully green, because no
+## fixture produces an entry that exercises either path. The comment claiming "the
+## fallback never drops an entry" was itself an unasserted claim, which is this session's
+## whole subject. Pulled out here, every branch takes a synthetic input in one cheap
+## hermetic test.
+##
+## Returns {"path": String, "uid": String}. `uid` is "" when the entry carries none.
+## An entry with no recognisable path segment is returned WHOLE as the path: dropping it
+## would shrink the dependency list and look tidier for it.
+static func split_dependency_entry(entry: String) -> Dictionary:
+	var found_path := ""
+	var found_uid := ""
+	for s in entry.split("::::"):
+		var seg := String(s)
+		if seg.begins_with("res://") or seg.begins_with("user://"):
+			if found_path == "":
+				found_path = seg
+		elif seg.begins_with("uid://"):
+			if found_uid == "":
+				found_uid = seg
+	return {"path": found_path if found_path != "" else entry, "uid": found_uid}
 
 
 func _scene_pack(params: Dictionary) -> Dictionary:
@@ -1624,6 +1802,18 @@ func _resource_get_import_settings(params: Dictionary) -> Dictionary:
 	var path := String(params.get("path", ""))
 	if path == "":
 		return _err("bad_params", "Missing 'path'")
+	# 🔴 168 (166 §5 D3), MEASURED against a live 4.7 editor: this used to test ONLY for
+	# the sidecar, so `res://player.gd` (a real file with no .import) and
+	# `res://no_such_file.png` (nothing at all) returned BYTE-IDENTICAL replies —
+	# {"imported": false, "importer": "", "settings": {}} — and a caller had no channel
+	# to tell "not imported" from "not there". A directory answered the same way.
+	# The vocabulary here is NOT invented: resource_load and resource_get_property were
+	# both probed for a missing path AND for a directory, and both already answer
+	# `not_found` / "Resource not found: %s" for each. This joins that convention rather
+	# than adding a third one. `imported: false` now means what it says — the file is
+	# really there and really has no .import sidecar.
+	if not FileAccess.file_exists(path):
+		return _err("not_found", "Resource not found: %s" % path)
 	var import_path := path + ".import"
 	if not FileAccess.file_exists(import_path):
 		return _ok({"path": path, "imported": false, "importer": "", "settings": {}})
@@ -1645,6 +1835,12 @@ func _resource_set_import_settings(params: Dictionary) -> Dictionary:
 	var path := String(params.get("path", ""))
 	if path == "":
 		return _err("bad_params", "Missing 'path'")
+	# 🔴 168: the same lie as D3, one tool over. A path that does not exist was refused
+	# with "No .import metadata for X (not an imported asset)" — a sentence that
+	# describes a file which EXISTS and is not imported. Measured: a directory got that
+	# message too. `not_imported` is now reserved for what it names.
+	if not FileAccess.file_exists(path):
+		return _err("not_found", "Resource not found: %s" % path)
 	var import_path := path + ".import"
 	if not FileAccess.file_exists(import_path):
 		return _err("not_imported", "No .import metadata for %s (not an imported asset)" % path)
@@ -1652,10 +1848,28 @@ func _resource_set_import_settings(params: Dictionary) -> Dictionary:
 	var e := cfg.load(import_path)
 	if e != OK:
 		return _err("load_failed", "Could not read import metadata: %s (%d)" % [import_path, e])
+	# 🔴 168 (166 §5 D4), MEASURED: `applied` lists every key the CALLER SENT, and
+	# `reimported` echoes the REQUEST parameter. Setting a key to the value it already
+	# held reported {"reimported": true, "settings": ["compress/mode"]} with the
+	# sidecar's bytes provably unmoved (sha256 before == after). A caller reading that
+	# reply cannot tell a real edit from a ceremonial one.
+	#
+	# `changed` is the missing channel, and it is deliberately a channel rather than a
+	# behaviour change: `settings: {}` with `reimport: true` is a legitimate FORCE-REIMPORT
+	# idiom (the source file moved under Godot's feet), so the reimport still runs and
+	# `reimported` still reports it honestly. What was missing was the ability to say
+	# "and nothing in the metadata actually moved" — which is now `changed: []`.
 	var applied: Array = []
+	var changed: Array = []
 	for key in params.get("settings", {}):
-		cfg.set_value("params", String(key), Codec.decode(params["settings"][key]))
-		applied.append(String(key))
+		var k := String(key)
+		var new_value = Codec.decode(params["settings"][key])
+		var had := cfg.has_section_key("params", k)
+		var old_value = cfg.get_value("params", k) if had else null
+		cfg.set_value("params", k, new_value)
+		applied.append(k)
+		if not had or old_value != new_value:
+			changed.append(k)
 	e = cfg.save(import_path)
 	if e != OK:
 		return _err("save_failed", "Could not write import metadata (%d)" % e)
@@ -1663,7 +1877,7 @@ func _resource_set_import_settings(params: Dictionary) -> Dictionary:
 	if reimport:
 		var efs := EditorInterface.get_resource_filesystem()
 		efs.reimport_files(PackedStringArray([path]))
-	return _ok({"path": path, "reimported": reimport, "settings": applied})
+	return _ok({"path": path, "reimported": reimport, "settings": applied, "changed": changed})
 
 
 # ----------------------------------------------- Group B: filesystem --------
@@ -1706,12 +1920,28 @@ func _filesystem_move(params: Dictionary) -> Dictionary:
 	var e := dir.rename(from_path, to_path)
 	if e != OK:
 		return _err("move_failed", "rename() returned %d" % e)
+	# 🔴 173 §10.3 — THE THIRD CONFIRMED MEMBER OF THE ECHO-MISTAKEN-FOR-A-REPORT
+	# FAMILY (#181, #183, 172 D5). `dir.rename()`'s RETURN WAS DISCARDED HERE and
+	# `moved_import` was set to true whenever a sidecar merely EXISTED — so the field
+	# described the REQUEST ("there was an .import and I called rename") rather than the
+	# outcome. A sidecar rename that failed (destination taken, permissions, a
+	# case-only rename on a case-insensitive filesystem) left an ORPHANED .import beside
+	# a file that had moved, stripping the moved asset of its import settings on the next
+	# scan — and the report said `moved_import: true`.
+	#
+	# THREE OUTCOMES, TWO BOOLEANS, BOTH DERIVED FROM THE RETURN CODE. "No sidecar" and
+	# "a sidecar that would not move" are different events and the caller has to be able
+	# to tell them apart; one boolean can only say "not moved" for both. The move itself
+	# already succeeded, so a stranded sidecar is a PARTIAL, not a failure — returning
+	# _err here would say nothing happened, which is the same lie in the other direction.
 	var moved_import := false
+	var import_stranded := false
 	if is_file and FileAccess.file_exists(from_path + ".import"):
-		dir.rename(from_path + ".import", to_path + ".import")
-		moved_import = true
+		var ie := dir.rename(from_path + ".import", to_path + ".import")
+		moved_import = ie == OK
+		import_stranded = ie != OK
 	EditorInterface.get_resource_filesystem().scan()
-	return _ok({"moved": to_path, "from": from_path, "moved_import": moved_import})
+	return _ok({"moved": to_path, "from": from_path, "moved_import": moved_import, "import_stranded": import_stranded})
 
 
 func _filesystem_create_dir(params: Dictionary) -> Dictionary:
@@ -1723,6 +1953,11 @@ func _filesystem_create_dir(params: Dictionary) -> Dictionary:
 	var e := DirAccess.make_dir_recursive_absolute(path)
 	if e != OK:
 		return _err("mkdir_failed", "make_dir_recursive_absolute() returned %d" % e)
+	# 🔴 173 §10.3, same family, one step milder: `created` was the REQUESTED path echoed
+	# back, and an OK return was never once confirmed against the filesystem. Re-read it,
+	# so `created` names a directory that is THERE rather than one that was asked for.
+	if not DirAccess.dir_exists_absolute(path):
+		return _err("mkdir_failed", "make_dir_recursive_absolute() returned OK but %s does not exist" % path)
 	EditorInterface.get_resource_filesystem().scan()
 	return _ok({"created": path, "existed": false})
 
@@ -3275,7 +3510,7 @@ func _particles_set_texture(params: Dictionary) -> Dictionary:
 	if node == null:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	if not (node is GPUParticles2D):
-		return _err("unsupported", "%s has no texture (GPUParticles3D draws meshes; texture is GPUParticles2D-only)" % node.name)
+		return _err("unsupported", "%s has no texture: only GPUParticles2D has one, and GPUParticles3D draws meshes instead. Pass the path of a GPUParticles2D node." % node.name)
 	var tex_path := String(params.get("texture_path", ""))
 	if tex_path == "" or not ResourceLoader.exists(tex_path):
 		return _err("not_found", "Texture not found: %s" % tex_path)
@@ -3347,7 +3582,7 @@ func _shadermaterial_create(params: Dictionary) -> Dictionary:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := _material_prop(node)
 	if prop == "":
-		return _err("unsupported", "%s has no material slot (needs CanvasItem.material or GeometryInstance3D.material_override)" % node.name)
+		return _err("unsupported", "%s has no material slot. Pass a node that has one: any CanvasItem exposes CanvasItem.material, any GeometryInstance3D exposes GeometryInstance3D.material_override." % node.name)
 	var mat := ShaderMaterial.new()
 	var shader_path := String(params.get("shader_path", ""))
 	if shader_path != "":
@@ -3375,7 +3610,7 @@ func _shadermaterial_set_shader(params: Dictionary) -> Dictionary:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := _material_prop(node)
 	if prop == "":
-		return _err("unsupported", "%s has no material slot" % node.name)
+		return _err("unsupported", "%s has no material slot. Pass a node that has one: any CanvasItem exposes CanvasItem.material, any GeometryInstance3D exposes GeometryInstance3D.material_override." % node.name)
 	var cur = node.get(prop)
 	if not (cur is ShaderMaterial):
 		return _err("bad_type", "%s has no ShaderMaterial (create one first)" % node.name)
@@ -3403,7 +3638,7 @@ func _shadermaterial_set_param(params: Dictionary) -> Dictionary:
 		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
 	var prop := _material_prop(node)
 	if prop == "":
-		return _err("unsupported", "%s has no material slot" % node.name)
+		return _err("unsupported", "%s has no material slot. Pass a node that has one: any CanvasItem exposes CanvasItem.material, any GeometryInstance3D exposes GeometryInstance3D.material_override." % node.name)
 	var cur = node.get(prop)
 	if not (cur is ShaderMaterial):
 		return _err("bad_type", "%s has no ShaderMaterial (create one first)" % node.name)

package/addon/breakpoint_mcp/plugin.cfg

@@ -3,5 +3,5 @@
 name="Breakpoint MCP"
 description="Exposes the live Godot editor and the running game to an MCP host so an AI assistant can drive them: scene/node/resource CRUD with full undo/redo, project settings, ClassDB, editor + in-game screenshots, and an in-game runtime bridge (live SceneTree, property get/set, method calls, signals, input injection, Performance monitors). Pairs with the breakpoint-mcp MCP host."
 author="James Livingston"
-version="1.9.2"
+version="1.9.8"
 script="plugin.gd"

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -14,6 +14,11 @@ extends Node
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
 const DEFAULT_PORT := 9081
 const LOG_CAP := 1000
+# D1a: how many error/warning entries one response may carry. A cap and not the
+# whole ring: a call that provokes a thousand warnings must not turn a 200-byte
+# reply into a 100 KB one. The `total` beside the list is what stops the cap
+# lying about how many there were.
+const ENGINE_LOG_CAP := 20
 # D6: source for the runtime-compiled Logger subclass (Godot 4.5+). Kept as a
 # string so `extends Logger` is only ever compiled where the class exists — the
 # addon stays parse-clean on Godot 4.3/4.4 (no Logger class).
@@ -35,6 +40,12 @@ const MONITORS := {
 	"time/process": Performance.TIME_PROCESS,
 	"time/physics_process": Performance.TIME_PHYSICS_PROCESS,
 	"memory/static": Performance.MEMORY_STATIC,
+	# Total live ObjectDB instances — Nodes, Resources and BARE Objects alike, which is
+	# what makes it the only monitor here that can see a leaked non-Node. Added session
+	# 153 so the _node_add `not_a_node` leak fixed in the same commit is REGRESSION-LOCKED
+	# in CI rather than merely proved once on a laptop: node-lifecycle.integration.mjs
+	# drives that branch in bulk and watches this number.
+	"object/count": Performance.OBJECT_COUNT,
 	"object/node_count": Performance.OBJECT_NODE_COUNT,
 	"object/resource_count": Performance.OBJECT_RESOURCE_COUNT,
 	"render/total_objects_drawn": Performance.RENDER_TOTAL_OBJECTS_IN_FRAME,
@@ -229,9 +240,17 @@ func _handle_line(c: Dictionary, line: String) -> void:
 	if method in ASYNC_METHODS:
 		_dispatch_async(c, id, method, params)
 		return
+	# D1a: the engine-error echo. The ring already receives every push_error /
+	# push_warning and every engine message (via the 4.5+ Logger capture), but
+	# nothing tied one to the CALL that provoked it — a caller had to notice
+	# something was wrong, then go and read runtime.get_log, then guess which
+	# entries were its own. Reading _log_seq either side of the dispatch answers
+	# that by construction: everything appended in between belongs to this call.
+	var seq_before := _log_seq
 	var result := _dispatch(method, params)
 	var response := {"id": id}
 	response.merge(result)
+	_attach_engine_log(response, seq_before)
 	_send(peer, response)
 
 
@@ -300,6 +319,51 @@ func _on_captured_log(level: String, message: String) -> void:
 	_in_capture = false
 
 
+## D1a: every `error`/`warning` ring entry appended AFTER `seq_before`, i.e. during
+## the dispatch this response belongs to. Written into `result` and not beside it:
+## the host resolves a reply as `msg.result`, so a sibling key is dropped on the
+## floor — and `structuredContent` must match the tool's `outputSchema` or a
+## conforming client throws, which is why `engine_log` is declared on all 26
+## runtime output schemas rather than smuggled in.
+##
+## `isError` IS DELIBERATELY UNTOUCHED. A push_error during a call that returned
+## what it was asked for is a DIAGNOSTIC, not a failed call; promoting it would
+## make every noisy frame look like a broken tool and would change the meaning of
+## a field callers already branch on.
+##
+## Absent when there is nothing, never `[]`: an optional field that is always
+## present carries no information, and 208 §4's finding is that absent and
+## explicitly-empty are NOT the same value to a client that never materialises
+## defaults.
+func _attach_engine_log(response: Dictionary, seq_before: int) -> void:
+	if not response.get("ok", false):
+		return  # a failed call already carries its own error; see the note above
+	var result: Variant = response.get("result")
+	if typeof(result) != TYPE_DICTIONARY:
+		return
+	var entries: Array = []
+	for e in _log:
+		if entries.size() >= ENGINE_LOG_CAP:
+			break
+		if int(e.get("seq", 0)) <= seq_before:
+			continue
+		var lvl := String(e.get("level", ""))
+		if lvl == "error" or lvl == "warning":
+			entries.append(e)
+	if entries.is_empty():
+		return
+	# 🔴 THE COUNT IS SEPARATE FROM THE LIST, because the list is CAPPED. A caller
+	# reading twenty entries cannot tell "twenty happened" from "hundreds happened
+	# and you are seeing the first twenty", and the second is the case that matters.
+	var total := 0
+	for e in _log:
+		if int(e.get("seq", 0)) > seq_before:
+			var lvl2 := String(e.get("level", ""))
+			if lvl2 == "error" or lvl2 == "warning":
+				total += 1
+	result["engine_log"] = {"entries": entries, "total": total, "since_seq": seq_before}
+
+
 # ----------------------------------------------------------- dispatch --------
 
 func _dispatch(method: String, params: Dictionary) -> Dictionary:
@@ -456,7 +520,36 @@ func _emit_signal(params: Dictionary) -> Dictionary:
 	var call_args: Array = [sig]
 	for a in params.get("args", []):
 		call_args.append(Codec.decode(a))
-	node.callv("emit_signal", call_args)
+	# emit_signal RETURNS an Error, and discarding it made this tool answer
+	# {"emitted": true} for an emission the engine refused. The cause is an `args` count
+	# that does not match a CONNECTED callable's arity: the engine pushes its own
+	# "Method expected N argument(s), but called with M" into the GAME's log — not the
+	# caller's — and that callable never runs, so the caller fails at its NEXT assertion,
+	# arbitrarily far from the cause.
+	#
+	# 🔴 TWO non-OK codes, and only one of them is a failure. Measured identically on
+	# 4.3, 4.5 and 4.7:
+	#
+	#   OK (0)                    a connected callable ran
+	#   ERR_METHOD_NOT_FOUND (37) a callable IS connected and could not be invoked —
+	#                             the arity mismatch. This is the defect worth reporting.
+	#   ERR_UNAVAILABLE (2)       the signal exists but has NO connections at all.
+	#                             Emitting into the void is ordinary and must SUCCEED —
+	#                             rejecting it would break every game that emits a signal
+	#                             nothing happens to be listening to.
+	#
+	# 🔴 The honest consequence: arity is checkable ONLY when something is connected.
+	# With no listener, a wrong count also returns ERR_UNAVAILABLE (there is no callable
+	# whose arity could mismatch), so it is indistinguishable from a correct emission.
+	# That is a limit of what the engine reports, not something this tool can tighten,
+	# and the catalog says so rather than implying a guarantee that does not exist.
+	var err: int = node.callv("emit_signal", call_args)
+	if err != OK and err != ERR_UNAVAILABLE:
+		return _err(
+			"emit_failed",
+			"emit_signal(%s) with %d arg(s) failed: %s (%d). Check the count against the arity of the signal's connected callables."
+				% [sig, call_args.size() - 1, error_string(err), err]
+		)
 	return _ok({"emitted": true})
 
 
@@ -466,6 +559,14 @@ func _inject_input(params: Dictionary) -> Dictionary:
 	match kind:
 		"action":
 			var action := String(ev.get("action", ""))
+			# An action the InputMap does not know is NOT injectable. Input.action_press
+			# pushes its own engine error and returns, so without this guard the reply is
+			# {"injected": true} for a typo'd action name and the caller's NEXT assertion is
+			# where the failure surfaces — as far from the cause as it is possible to get.
+			# Found live, session 153, by the probe that first pointed this tool at a real
+			# InputMap. Covers both operands: an absent "action" key arrives here as "".
+			if not InputMap.has_action(action):
+				return _err("bad_action", "No such InputMap action: %s" % action)
 			if bool(ev.get("pressed", true)):
 				Input.action_press(action, float(ev.get("strength", 1.0)))
 			else:
@@ -891,6 +992,16 @@ func _node_add(params: Dictionary) -> Dictionary:
 			return _err("bad_type", "Cannot instantiate class: %s" % type_name)
 		var obj: Variant = ClassDB.instantiate(type_name)
 		if not (obj is Node):
+			# ClassDB.instantiate hands back an UNOWNED instance. A RefCounted subclass
+			# (Resource, Image, ...) releases itself when this reference goes out of scope;
+			# a bare Object does NOT, so returning here without freeing leaked one instance
+			# per call — which the engine reports only at exit, as "N ObjectDB instances
+			# were leaked". Proved session 152, measured session 153 at 51 leaked over 51
+			# calls and 0 with this branch in place.
+			# The RefCounted arm MUST be excluded: free() on a RefCounted is itself an error,
+			# which is why the safe-looking `Resource` case hid this for so long.
+			if obj is Object and not (obj is RefCounted):
+				(obj as Object).free()
 			return _err("not_a_node", "%s is not a Node" % type_name)
 		child = obj
 	if child == null:
@@ -919,6 +1030,12 @@ func _node_remove(params: Dictionary) -> Dictionary:
 ## as a bare (un-awaited) call from _handle_line so _process never blocks; it resumes on the
 ## engine's frame signals and sends when complete.
 func _dispatch_async(c: Dictionary, id: Variant, method: String, params: Dictionary) -> void:
+	# D1a: the async lane echoes too, and it is the lane that needs it MOST — a
+	# step_frames call runs the game for N frames, so it is the one dispatch here
+	# that can provoke errors from code the caller never named. Handing it the
+	# synchronous version's treatment is not symmetry for its own sake: a caller
+	# stepping frames to reproduce a bug is exactly the caller this feature is for.
+	var seq_before := _log_seq
 	var result: Dictionary
 	match method:
 		"runtime.step_frames":
@@ -929,6 +1046,7 @@ func _dispatch_async(c: Dictionary, id: Variant, method: String, params: Diction
 	if peer != null and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
 		var response := {"id": id}
 		response.merge(result)
+		_attach_engine_log(response, seq_before)
 		_send(peer, response)
 
 

package/dist/annotations.js

@@ -8,7 +8,7 @@ const READ_ONLY = [
     "gd_declaration", "gd_definition", "gd_diagnostics", "gd_document_color", "gd_document_highlight",
     "gd_document_link", "gd_document_symbols", "gd_folding_ranges", "gd_formatting", "gd_hover", "gd_implementation",
     "gd_references", "gd_semantic_tokens", "gd_signature_help", "gd_type_definition", "gd_workspace_symbols",
-    "godot_output", "godot_version", "inputmap_list", "node_find", "node_get_children", "node_get_path",
+    "godot_output", "godot_version", "inputmap_list", "main_screen_get", "node_find", "node_get_children", "node_get_path",
     "node_get_property", "node_list_groups", "node_list_properties", "project_get_info", "project_get_setting",
     "project_list_settings", "project_search", "resource_get_import_settings", "resource_get_property",
     "resource_load", "runtime_anim_get_state", "runtime_assert_node_state", "runtime_assert_perf",
@@ -63,7 +63,7 @@ const IDEMPOTENT = [
     "gd_references", "gd_rename", "gd_semantic_tokens", "gd_signature_help", "gd_type_definition",
     "gd_workspace_symbols", "godot_export", "godot_import", "godot_output", "godot_stop", "godot_version",
     "inputmap_add_action", "inputmap_erase_action", "inputmap_list", "joint_set_bodies", "leaderboard_scaffold",
-    "mesh_set_surface_material", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer",
+    "main_screen_get", "main_screen_set", "mesh_set_surface_material", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer",
     "mp_setup_webrtc_peer", "mp_wire_rpc", "node_add_to_group", "node_change_type", "node_delete", "node_find",
     "node_get_children", "node_get_path", "node_get_property", "node_list_groups", "node_list_properties",
     "node_move_child", "node_remove_from_group", "node_rename", "node_reparent", "node_set_editable_instance",
@@ -131,7 +131,7 @@ export const ALL_ANNOTATED = [
     "godot_launch_editor", "godot_output", "godot_run_headless_script", "godot_run_managed", "godot_run_project",
     "godot_stop", "godot_version", "inputmap_add_action", "inputmap_add_event", "inputmap_erase_action",
     "inputmap_list", "interact_add_drop_zone", "interact_make_draggable", "joint_create", "joint_set_bodies",
-    "leaderboard_scaffold", "light_create", "mesh_set_surface_material", "meshinstance_create", "mp_add_spawner",
+    "leaderboard_scaffold", "light_create", "main_screen_get", "main_screen_set", "mesh_set_surface_material", "meshinstance_create", "mp_add_spawner",
     "mp_add_synchronizer", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer", "mp_setup_webrtc_peer",
     "mp_wire_rpc", "navagent_configure", "navregion_create", "node_add", "node_add_to_group", "node_call_method",
     "node_change_type", "node_delete", "node_duplicate", "node_find", "node_get_children", "node_get_path",

package/dist/cli/doctor.js

@@ -195,7 +195,7 @@ export function checkCapabilities(config) {
             status: "ok",
             severity: "info",
             detail: dropped.length === 0
-                ? `${state} — full 289-tool surface`
+                ? `${state} — full 291-tool surface`
                 : `${state} (secure default) — ${dropped.length} higher-trust tool(s) dropped from the surface`,
             hint: dropped.length === 0
                 ? undefined

package/dist/cli/init.js

@@ -279,7 +279,7 @@ export async function runInit(argv, deps = {}) {
     // Trust groups — surface the secure default so even a bare `init` teaches it.
     say("");
     if (privilegedGroups) {
-        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 289-tool surface loads.`);
+        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 291-tool surface loads.`);
     }
     else {
         say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");

package/dist/cli/tools.js

@@ -17,8 +17,8 @@
  * container, and on a machine with no Godot installed.
  *
  * Two surfaces are reported, because the difference is the security story:
- *   • `full`           — all 289 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
- *   • `secure-default` — 276, what an untouched install actually advertises
+ *   • `full`           — all 291 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
+ *   • `secure-default` — 278, what an untouched install actually advertises
  * `--surface` picks which one populates `tools[]`; both counts are always in the
  * header so a consumer cannot report one as the other by accident.
  */