breakpoint-mcp 1.19.1 → 1.23.0

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. **276 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **289 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.7.0"
+const ADDON_VERSION := "1.9.1"
 
 var _plugin: EditorPlugin
 

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.7.0"
+version="1.9.1"
 script="plugin.gd"

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -47,6 +47,10 @@ const MONITORS := {
 
 const BridgeSecret := preload("res://addons/breakpoint_mcp/bridge_secret.gd")
 const PauseLatch := preload("res://addons/breakpoint_mcp/pause_latch.gd")
+# F4: methods dispatched on the async lane (they await frames); see _handle_line / _dispatch_async.
+const ASYNC_METHODS := ["runtime.step_frames"]
+# F4: default salient fields captured by runtime.state_digest when no explicit list is given.
+const _DIGEST_DEFAULT_FIELDS := ["position", "global_position", "rotation", "scale", "visible", "modulate"]
 
 var _server: TCPServer
 var _clients: Array = [] # Array of {peer, buf}
@@ -219,6 +223,12 @@ func _handle_line(c: Dictionary, line: String) -> void:
 		held.merge(PauseLatch.held_response(method))
 		_send(peer, held)
 		return
+	# F4: async lane — methods that await frames can't use the synchronous dispatch (which sends
+	# its response immediately). Start a coroutine that sends the id'd response when done; the host
+	# correlates responses by id, so an out-of-order async response is fine.
+	if method in ASYNC_METHODS:
+		_dispatch_async(c, id, method, params)
+		return
 	var result := _dispatch(method, params)
 	var response := {"id": id}
 	response.merge(result)
@@ -324,6 +334,27 @@ func _dispatch(method: String, params: Dictionary) -> Dictionary:
 			return _assert_screen_text(params)
 		"runtime.screenshot_diff":
 			return _screenshot_diff(params)
+		"runtime.anim_play":
+			return _anim_play(params)
+		"runtime.anim_stop":
+			return _anim_stop(params)
+		"runtime.anim_get_state":
+			return _anim_get_state(params)
+		"runtime.node_add":
+			return _node_add(params)
+		"runtime.node_remove":
+			return _node_remove(params)
+		"runtime.time_scale":
+			return _time_scale(params)
+		"runtime.state_digest":
+			return _state_digest(params)
+		"runtime.seed_rng":
+			return _seed_rng(params)
+		"runtime.step_frames":
+			# Dispatched on the async lane (see _handle_line / _dispatch_async); this placeholder
+			# keeps the static contract check (which scans _dispatch case labels) aware of the
+			# method. It is not reached in normal operation.
+			return _err("async_only", "runtime.step_frames is dispatched on the async lane")
 		_:
 			return _err("unknown_method", "No such method: %s" % method)
 
@@ -767,3 +798,215 @@ func _compare_images(frame: Image, reference_img: Image, params: Dictionary, ref
 		"height": h,
 		"reference": reference,
 	})
+
+
+# ----------------------------------------------------- F8: animation ---------
+
+## Resolve a node and require it to be an AnimationPlayer.
+func _resolve_anim_player(path: String):
+	var node := _resolve(path)
+	if node == null:
+		return _err("bad_path", "Node not found: %s" % path)
+	if not (node is AnimationPlayer):
+		return _err("not_animation_player", "%s is not an AnimationPlayer" % node.get_class())
+	return node as AnimationPlayer
+
+
+func _anim_state(ap: AnimationPlayer) -> Dictionary:
+	var anims: Array = []
+	for a in ap.get_animation_list():
+		anims.append(String(a))
+	return {
+		"playing": ap.is_playing(),
+		"current_animation": ap.current_animation,
+		"position": ap.current_animation_position,
+		"length": ap.current_animation_length,
+		"speed_scale": ap.speed_scale,
+		"animations": anims,
+	}
+
+
+func _anim_play(params: Dictionary) -> Dictionary:
+	var res = _resolve_anim_player(String(params.get("path", "")))
+	if res is Dictionary:
+		return res
+	var ap: AnimationPlayer = res
+	var anim := String(params.get("animation", ""))
+	if anim != "" and not ap.has_animation(anim):
+		return _err("no_animation", "AnimationPlayer has no animation '%s'" % anim)
+	var speed := float(params.get("custom_speed", 1.0))
+	var from_end := bool(params.get("from_end", false))
+	ap.play(anim, -1.0, speed, from_end)
+	return _ok({
+		"playing": ap.is_playing(),
+		"current_animation": ap.current_animation,
+		"speed_scale": ap.speed_scale,
+	})
+
+
+func _anim_stop(params: Dictionary) -> Dictionary:
+	var res = _resolve_anim_player(String(params.get("path", "")))
+	if res is Dictionary:
+		return res
+	var ap: AnimationPlayer = res
+	# keep_state:true pauses in place; default stops. pause()/stop() with no args are
+	# stable across Godot 4.2–4.5 (unlike stop()'s changing keep_state parameter).
+	if bool(params.get("keep_state", false)):
+		ap.pause()
+	else:
+		ap.stop()
+	return _ok({
+		"playing": ap.is_playing(),
+		"current_animation": ap.current_animation,
+		"position": ap.current_animation_position,
+	})
+
+
+func _anim_get_state(params: Dictionary) -> Dictionary:
+	var res = _resolve_anim_player(String(params.get("path", "")))
+	if res is Dictionary:
+		return res
+	var ap: AnimationPlayer = res
+	return _ok(_anim_state(ap))
+
+
+# ----------------------------------------------------- F8: node lifecycle ----
+
+func _node_add(params: Dictionary) -> Dictionary:
+	var parent := _resolve(String(params.get("parent", "")))
+	if parent == null:
+		return _err("bad_path", "Parent not found: %s" % params.get("parent", ""))
+	var child: Node = null
+	var scene_path := String(params.get("scene", ""))
+	if scene_path != "":
+		var ps: Variant = load(scene_path)
+		if ps == null or not (ps is PackedScene):
+			return _err("bad_scene", "Could not load PackedScene: %s" % scene_path)
+		child = (ps as PackedScene).instantiate()
+	else:
+		var type_name := String(params.get("type", ""))
+		if type_name == "":
+			return _err("bad_args", "Provide either 'scene' or 'type'")
+		if not ClassDB.class_exists(type_name) or not ClassDB.can_instantiate(type_name):
+			return _err("bad_type", "Cannot instantiate class: %s" % type_name)
+		var obj: Variant = ClassDB.instantiate(type_name)
+		if not (obj is Node):
+			return _err("not_a_node", "%s is not a Node" % type_name)
+		child = obj
+	if child == null:
+		return _err("instantiate_failed", "Failed to instantiate node")
+	var nm := String(params.get("name", ""))
+	if nm != "":
+		child.name = nm
+	parent.add_child(child)
+	return _ok({"added": true, "path": _path_of(child), "type": child.get_class()})
+
+
+func _node_remove(params: Dictionary) -> Dictionary:
+	var node := _resolve(String(params.get("path", "")))
+	if node == null:
+		return _err("bad_path", "Node not found: %s" % params.get("path", ""))
+	if node == _base():
+		return _err("cannot_remove_root", "Refusing to remove the current scene root")
+	var p := _path_of(node)
+	node.queue_free()
+	return _ok({"removed": true, "path": p})
+
+
+# ----------------------------------------------- F4: deterministic playtesting ----
+
+## Async dispatch lane: run a coroutine that awaits frames, then send the id'd response. Started
+## 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:
+	var result: Dictionary
+	match method:
+		"runtime.step_frames":
+			result = await _step_frames(params)
+		_:
+			result = _err("async_only", "not an async method: %s" % method)
+	var peer: StreamPeerTCP = c.get("peer")
+	if peer != null and peer.get_status() == StreamPeerTCP.STATUS_CONNECTED:
+		var response := {"id": id}
+		response.merge(result)
+		_send(peer, response)
+
+
+## Advance the game by an exact number of frames while otherwise frozen. Toggles
+## get_tree().paused false -> (await one frame) -> true per step (the standard Godot frame-step
+## idiom); the bridge keeps servicing the socket throughout because it is PROCESS_MODE_ALWAYS.
+## Restores the caller's prior pause state when done.
+func _step_frames(params: Dictionary) -> Dictionary:
+	var tree := get_tree()
+	if tree == null:
+		return _err("no_tree", "No scene tree")
+	var frames := clampi(int(params.get("frames", 1)), 1, 100000)
+	var kind := String(params.get("kind", "idle"))
+	var prev_scale := Engine.time_scale
+	# Advance by exactly `frames`: restore a normal time scale for the step (the caller froze via
+	# runtime_time_scale{scale:0}, which zeroes delta), and count real frames off the ENGINE frame
+	# counters. Freeze/step are driven by time_scale (delta), NOT get_tree().paused: pause is a
+	# per-node processing gate that desyncs from the frame counter by one frame at the step boundary
+	# (a node advances N-1 for N counted frames), whereas with time_scale the node processes every
+	# frame and the counter matches its work 1:1. time_scale is restored after.
+	Engine.time_scale = 1.0
+	if kind == "physics" or kind == "both":
+		var target_p := Engine.get_physics_frames() + frames
+		while Engine.get_physics_frames() < target_p:
+			await tree.physics_frame
+	else:
+		var target_i := Engine.get_process_frames() + frames
+		while Engine.get_process_frames() < target_i:
+			await tree.process_frame
+	Engine.time_scale = prev_scale
+	return _ok({"frames_advanced": frames, "frame_index": Engine.get_process_frames()})
+
+
+func _time_scale(params: Dictionary) -> Dictionary:
+	var previous := Engine.time_scale
+	var scale := maxf(0.0, float(params.get("scale", 1.0)))
+	Engine.time_scale = scale
+	# scale 0 freezes the game clock (delta -> 0): delta-based motion, tweens, timers and
+	# animations halt. runtime_step_frames temporarily restores a normal scale to advance an exact
+	# number of frames. Deliberately time_scale, not get_tree().paused — pause is a per-node
+	# processing gate that desyncs from the frame counter by one frame at the step boundary.
+	return _ok({"previous": previous, "current": Engine.time_scale})
+
+
+func _seed_rng(params: Dictionary) -> Dictionary:
+	var s := int(params.get("seed", 0))
+	seed(s)
+	return _ok({"seed": s})
+
+
+## Read a compact, stable-ordered snapshot of a subtree's salient state (read-only). Default
+## fields are the common transform/visibility properties; a caller may pass an explicit list.
+func _state_digest(params: Dictionary) -> Dictionary:
+	var root := _resolve(String(params.get("root", "")))
+	if root == null:
+		return _err("bad_path", "Node not found: %s" % params.get("root", ""))
+	var raw_fields: Variant = params.get("fields", [])
+	var fields: Array = raw_fields if typeof(raw_fields) == TYPE_ARRAY else []
+	var max_depth := int(params.get("max_depth", 8))
+	var digest := {}
+	var count := _digest_walk(root, 0, max_depth, fields, digest)
+	return _ok({"digest": digest, "node_count": count})
+
+
+func _digest_walk(node: Node, depth: int, max_depth: int, fields: Array, digest: Dictionary) -> int:
+	var entry := {}
+	if fields.is_empty():
+		for f in _DIGEST_DEFAULT_FIELDS:
+			var dv: Variant = node.get(f)
+			if dv != null:
+				entry[f] = Codec.encode(dv)
+	else:
+		for f in fields:
+			var fn := String(f)
+			entry[fn] = Codec.encode(node.get(fn))
+	digest[_path_of(node)] = entry
+	var count := 1
+	if depth < max_depth:
+		for ch in node.get_children():
+			count += _digest_walk(ch, depth + 1, max_depth, fields, digest)
+	return count

package/dist/annotations.js

@@ -0,0 +1,225 @@
+/** Tools that mutate nothing. */
+const READ_ONLY = [
+    "anim_get_track_keys", "anim_list", "backend_detect", "class_reference", "classdb_get_class", "cs_code_action",
+    "cs_completion", "cs_dbg_scopes", "cs_dbg_stack_trace", "cs_dbg_variables", "cs_definition", "cs_diagnostics",
+    "cs_document_symbols", "cs_hover", "cs_references", "cs_signature_help", "cs_workspace_symbols", "dbg_scopes",
+    "dbg_stack_trace", "dbg_variables", "docs_search", "editor_get_state", "editor_ping", "example_snippet",
+    "filesystem_list", "find_symbol", "find_usages", "gd_call_hierarchy", "gd_code_action", "gd_completion",
+    "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",
+    "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",
+    "runtime_assert_scene_structure", "runtime_assert_screen_text", "runtime_await_condition", "runtime_get_log",
+    "runtime_get_monitors", "runtime_get_property", "runtime_get_tree", "runtime_screenshot",
+    "runtime_peers_digest", "runtime_screenshot_diff", "runtime_state_digest", "scene_get_dependencies",
+    "scene_get_tree", "scene_list_open", "screenshot_editor", "selection_get", "signal_list",
+    "signal_list_connections", "test_detect", "test_list", "tilemap_get_cell", "vcs_blame", "vcs_branch_list",
+    "vcs_diff", "vcs_log", "vcs_show", "vcs_status",
+];
+/** Tools that may overwrite or discard state the caller did not supply. */
+const DESTRUCTIVE = [
+    "anim_delete", "anim_remove_key", "asset_gen_audio_sfx", "asset_gen_icon", "asset_gen_model",
+    "asset_gen_placeholder", "asset_gen_sprite", "asset_gen_texture", "audio_bus_set_volume", "audio_set_bus_layout",
+    "auth_scaffold", "backend_configure", "board_create", "board_tile_create", "card_template_create",
+    "cloudsave_scaffold", "cs_dbg_evaluate", "cs_dbg_set_variable", "cs_rename", "dbg_evaluate", "dbg_goto",
+    "dbg_set_variable", "editorsettings_get_set", "environment_create", "environment_set_sky", "filesystem_move",
+    "gd_rename", "godot_run_headless_script", "godot_stop", "inputmap_add_action", "inputmap_erase_action",
+    "interact_add_drop_zone", "interact_make_draggable", "leaderboard_scaffold", "mp_scaffold_lobby",
+    "mp_setup_enet_peer", "mp_setup_webrtc_peer", "mp_wire_rpc", "node_call_method", "node_change_type",
+    "node_delete", "node_remove_from_group", "physics_set_gravity", "piece_template_create", "primitive_mesh_create",
+    "project_add_autoload", "project_remove_autoload", "project_set_main_scene", "project_set_setting",
+    "resource_create", "resource_duplicate", "resource_save", "resource_set_import_settings",
+    "resource_set_property", "runtime_anim_play", "runtime_anim_stop", "runtime_call_method", "runtime_emit_signal",
+    "runtime_inject_input", "runtime_node_remove", "runtime_peer_stop", "runtime_seed_rng", "runtime_set_property",
+    "runtime_step_frames", "runtime_time_scale", "scene_close", "scene_new", "scene_pack", "scene_reload", "scene_save_as", "shader_create",
+    "shader_set_code", "shadermaterial_create", "shadermaterial_set_param", "shadermaterial_set_shader",
+    "signal_disconnect", "signal_emit", "theme_create", "theme_set_color", "theme_set_constant", "theme_set_font",
+    "theme_set_stylebox", "tilemap_clear", "tilemap_set_cell", "tilemap_set_cells_rect", "tileset_create",
+    "vcs_restore", "vcs_stash",
+];
+/** Tools where a repeat call with identical arguments adds no further effect. */
+const IDEMPOTENT = [
+    "anim_create", "anim_delete", "anim_get_track_keys", "anim_insert_key", "anim_list", "anim_set_length",
+    "anim_set_loop", "anim_statemachine_add_state", "anim_statemachine_add_transition", "anim_tree_add_node",
+    "area_set_gravity", "area_set_monitoring", "asset_gen_configure", "asset_gen_placeholder",
+    "audio_bus_set_volume", "audio_set_bus_layout", "audio_set_stream", "auth_scaffold", "backend_configure",
+    "backend_detect", "board_create", "board_place", "board_tile_create", "board_tile_place",
+    "body_set_collision_layer", "body_set_collision_mask", "body_set_physics_material", "card_template_create",
+    "class_reference", "classdb_get_class", "cloudsave_scaffold", "control_set_anchors", "control_set_layout_preset",
+    "control_set_size_flags", "control_set_theme", "cs_code_action", "cs_completion", "cs_dbg_attach",
+    "cs_dbg_scopes", "cs_dbg_set_breakpoints", "cs_dbg_set_exception_breakpoints", "cs_dbg_set_variable",
+    "cs_dbg_stack_trace", "cs_dbg_variables", "cs_dbg_watch", "cs_definition", "cs_diagnostics",
+    "cs_document_symbols", "cs_hover", "cs_references", "cs_rename", "cs_signature_help", "cs_workspace_symbols",
+    "dbg_attach", "dbg_data_breakpoints", "dbg_goto", "dbg_scopes", "dbg_set_breakpoints",
+    "dbg_set_exception_breakpoints", "dbg_set_variable", "dbg_stack_trace", "dbg_variables", "dbg_watch",
+    "docs_search", "editor_get_state", "editor_ping", "editorsettings_get_set", "environment_create",
+    "environment_set_sky", "example_snippet", "filesystem_create_dir", "filesystem_list", "filesystem_move",
+    "filesystem_scan", "find_symbol", "find_usages", "gd_call_hierarchy", "gd_code_action", "gd_completion",
+    "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_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",
+    "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",
+    "node_set_owner", "node_set_property", "particles_set_amount", "particles_set_emitting",
+    "particles_set_lifetime", "particles_set_process_material", "particles_set_texture", "physics_set_gravity",
+    "piece_template_create", "primitive_mesh_create", "project_add_autoload", "project_get_info",
+    "project_get_setting", "project_list_settings", "project_remove_autoload", "project_search",
+    "project_set_main_scene", "project_set_setting", "resource_create", "resource_duplicate",
+    "resource_get_import_settings", "resource_get_property", "resource_load", "resource_save",
+    "resource_set_import_settings", "resource_set_property", "rigidbody_set_properties", "runtime_anim_get_state",
+    "runtime_anim_stop", "runtime_assert_node_state", "runtime_assert_perf", "runtime_assert_scene_structure",
+    "runtime_assert_screen_text", "runtime_await_condition", "runtime_get_log", "runtime_get_monitors",
+    "runtime_get_property", "runtime_get_tree", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest",
+    "runtime_screenshot", "runtime_screenshot_diff", "runtime_seed_rng", "runtime_set_property",
+    "runtime_state_digest", "runtime_time_scale", "scene_get_dependencies", "scene_get_tree", "scene_list_open", "scene_new", "scene_open",
+    "scene_pack", "scene_reload", "scene_save", "scene_save_as", "screenshot_editor", "selection_get",
+    "selection_set", "shader_create", "shader_set_code", "shadermaterial_create", "shadermaterial_set_param",
+    "shadermaterial_set_shader", "signal_add_user_signal", "signal_connect", "signal_disconnect", "signal_list",
+    "signal_list_connections", "test_detect", "test_list", "theme_create", "theme_set_color", "theme_set_constant",
+    "theme_set_font", "theme_set_stylebox", "tilemap_clear", "tilemap_get_cell", "tilemap_set_cell",
+    "tilemap_set_cells_rect", "tileset_add_tile", "tileset_create", "vcs_add", "vcs_blame", "vcs_branch_list",
+    "vcs_diff", "vcs_log", "vcs_restore", "vcs_show", "vcs_status", "vcs_switch",
+];
+/**
+ * Tools that reach outside this machine + this project. Empty by design — every
+ * bridge is loopback-only. A future networked tool must be listed here.
+ */
+const OPEN_WORLD = [];
+/**
+ * The complete annotated roster — every registered tool, listed explicitly.
+ *
+ * This CANNOT be derived as the union of the four lists above: 52 tools are
+ * all-false (mutating, non-destructive, non-idempotent, local — e.g. `node_add`,
+ * `dbg_step`, `vcs_commit`), so a derived union would silently omit them and the
+ * totality check below would pass while they shipped unannotated. Listing the
+ * roster explicitly is what makes "every tool is annotated" an assertion rather
+ * than a tautology.
+ */
+export const ALL_ANNOTATED = [
+    "anim_add_track", "anim_create", "anim_delete", "anim_get_track_keys", "anim_insert_key", "anim_list",
+    "anim_player_create", "anim_remove_key", "anim_set_length", "anim_set_loop", "anim_statemachine_add_state",
+    "anim_statemachine_add_transition", "anim_tree_add_node", "anim_tree_create", "area_set_gravity",
+    "area_set_monitoring", "asset_gen_audio_sfx", "asset_gen_configure", "asset_gen_icon", "asset_gen_model",
+    "asset_gen_placeholder", "asset_gen_sprite", "asset_gen_texture", "audio_bus_add", "audio_bus_add_effect",
+    "audio_bus_set_volume", "audio_player_create", "audio_set_bus_layout", "audio_set_stream", "auth_scaffold",
+    "backend_configure", "backend_detect", "board_create", "board_place", "board_tile_create", "board_tile_place",
+    "body_create", "body_set_collision_layer", "body_set_collision_mask", "body_set_physics_material",
+    "camera_create", "card_deck_from_table", "card_hand_layout", "card_instance", "card_set_face",
+    "card_template_create", "class_reference", "classdb_get_class", "cloudsave_scaffold", "collisionpolygon_add",
+    "collisionshape_add", "container_add_child", "control_create", "control_set_anchors",
+    "control_set_layout_preset", "control_set_size_flags", "control_set_theme", "cs_code_action", "cs_completion",
+    "cs_dbg_attach", "cs_dbg_continue", "cs_dbg_evaluate", "cs_dbg_launch", "cs_dbg_restart", "cs_dbg_scopes",
+    "cs_dbg_set_breakpoints", "cs_dbg_set_exception_breakpoints", "cs_dbg_set_variable", "cs_dbg_stack_trace",
+    "cs_dbg_step", "cs_dbg_variables", "cs_dbg_watch", "cs_definition", "cs_diagnostics", "cs_document_symbols",
+    "cs_hover", "cs_references", "cs_rename", "cs_signature_help", "cs_workspace_symbols", "csg_create",
+    "dbg_attach", "dbg_continue", "dbg_data_breakpoints", "dbg_evaluate", "dbg_goto", "dbg_launch", "dbg_restart",
+    "dbg_scopes", "dbg_set_breakpoints", "dbg_set_exception_breakpoints", "dbg_set_variable", "dbg_stack_trace",
+    "dbg_step", "dbg_variables", "dbg_watch", "docs_search", "editor_get_state", "editor_ping", "editor_redo",
+    "editor_undo", "editorsettings_get_set", "environment_create", "environment_set_sky", "example_snippet",
+    "filesystem_create_dir", "filesystem_list", "filesystem_move", "filesystem_scan", "find_symbol", "find_usages",
+    "gd_call_hierarchy", "gd_code_action", "gd_completion", "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_rename", "gd_semantic_tokens",
+    "gd_signature_help", "gd_type_definition", "gd_workspace_symbols", "godot_export", "godot_import",
+    "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",
+    "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",
+    "node_get_property", "node_instantiate_scene", "node_list_groups", "node_list_properties", "node_move_child",
+    "node_remove_from_group", "node_rename", "node_reparent", "node_set_editable_instance", "node_set_owner",
+    "node_set_property", "particles_create", "particles_set_amount", "particles_set_emitting",
+    "particles_set_lifetime", "particles_set_process_material", "particles_set_texture", "physics_set_gravity",
+    "piece_instance", "piece_move", "piece_template_create", "primitive_mesh_create", "project_add_autoload",
+    "project_add_export_preset", "project_get_info", "project_get_setting", "project_list_settings",
+    "project_remove_autoload", "project_search", "project_set_main_scene", "project_set_setting", "resource_create",
+    "resource_duplicate", "resource_get_import_settings", "resource_get_property", "resource_load", "resource_save",
+    "resource_set_import_settings", "resource_set_property", "rigidbody_set_properties", "runtime_anim_get_state",
+    "runtime_anim_play", "runtime_anim_stop", "runtime_assert_node_state", "runtime_assert_perf",
+    "runtime_assert_scene_structure", "runtime_assert_screen_text", "runtime_await_condition", "runtime_call_method",
+    "runtime_emit_signal", "runtime_get_log", "runtime_get_monitors", "runtime_get_property", "runtime_get_tree",
+    "runtime_inject_input", "runtime_node_add", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest",
+    "runtime_screenshot", "runtime_screenshot_diff", "runtime_seed_rng", "runtime_set_property",
+    "runtime_spawn_peers", "runtime_state_digest", "runtime_step_frames", "runtime_time_scale", "scene_close",
+    "scene_get_dependencies", "scene_get_tree",
+    "scene_list_open", "scene_new", "scene_open", "scene_pack", "scene_reload", "scene_save", "scene_save_as",
+    "screenshot_editor", "selection_get", "selection_set", "shader_create", "shader_set_code",
+    "shadermaterial_create", "shadermaterial_set_param", "shadermaterial_set_shader", "signal_add_user_signal",
+    "signal_connect", "signal_disconnect", "signal_emit", "signal_list", "signal_list_connections", "test_detect",
+    "test_list", "theme_create", "theme_set_color", "theme_set_constant", "theme_set_font", "theme_set_stylebox",
+    "tilemap_clear", "tilemap_get_cell", "tilemap_set_cell", "tilemap_set_cells_rect", "tilemaplayer_create",
+    "tileset_add_source", "tileset_add_tile", "tileset_create", "tileset_set_tile_collision", "vcs_add", "vcs_blame",
+    "vcs_branch_create", "vcs_branch_list", "vcs_commit", "vcs_diff", "vcs_log", "vcs_restore", "vcs_show",
+    "vcs_stash", "vcs_status", "vcs_switch",
+];
+const readOnly = new Set(READ_ONLY);
+const destructive = new Set(DESTRUCTIVE);
+const idempotent = new Set(IDEMPOTENT);
+const openWorld = new Set(OPEN_WORLD);
+/**
+ * Guard the one way this table can rot silently: a name typo'd into READ_ONLY /
+ * DESTRUCTIVE / IDEMPOTENT that is not on the roster would otherwise annotate
+ * nothing and fail no test. Throwing at module load turns that into an
+ * immediate, obvious failure in every consumer, tests included.
+ */
+{
+    const roster = new Set(ALL_ANNOTATED);
+    const orphans = [...new Set([...READ_ONLY, ...DESTRUCTIVE, ...IDEMPOTENT, ...OPEN_WORLD])]
+        .filter((n) => !roster.has(n))
+        .sort();
+    if (orphans.length) {
+        throw new Error(`annotations.ts: name(s) in a hint list but absent from ALL_ANNOTATED: ${orphans.join(", ")}`);
+    }
+}
+/** Every tool name carrying an annotation entry — the totality set for the tests. */
+export const ANNOTATED_TOOLS = Object.freeze([...ALL_ANNOTATED].sort());
+/**
+ * The four hints for one tool. Every registered tool resolves to a complete
+ * block: absence from a list is a positive "false", never "unknown", so a
+ * consumer never has to fall back to guessing from the name.
+ */
+export function annotationsFor(name) {
+    return {
+        readOnlyHint: readOnly.has(name),
+        destructiveHint: destructive.has(name),
+        idempotentHint: idempotent.has(name),
+        openWorldHint: openWorld.has(name),
+    };
+}
+/**
+ * Wrap `server.registerTool` to inject the annotations block at registration.
+ * Mirrors `applyOutputSchemas` / `applyCapabilities`; call once, after
+ * `applyOutputSchemas` and before any `register*Tools()`. An explicit
+ * `annotations` already on the config wins, so a call site can override.
+ *
+ * `title` is left alone — the SDK already promotes the top-level `title` to the
+ * annotation of the same name, and duplicating it here would fight that.
+ */
+export function applyAnnotations(server) {
+    const inject = (raw) => (name, config, handler) => {
+        const cfg = config;
+        if (cfg && cfg.annotations === undefined) {
+            config = { ...cfg, annotations: annotationsFor(name) };
+        }
+        return raw(name, config, handler);
+    };
+    const s = server;
+    s.registerTool = inject(s.registerTool.bind(server));
+    // D2 task-model tools (godot_export / godot_import / godot_run_headless_script)
+    // register through experimental.tasks.registerToolTask, not registerTool —
+    // annotate that path too or three tools ship hint-less.
+    const tasks = s.experimental?.tasks;
+    if (tasks?.registerToolTask) {
+        tasks.registerToolTask = inject(tasks.registerToolTask.bind(tasks));
+    }
+}
+//# sourceMappingURL=annotations.js.map

package/dist/capabilities.js

@@ -2,7 +2,7 @@
 export const CAPABILITY_GROUPS = ["code-execution", "network"];
 /** One-line human description per group (shown by `doctor` and the resource). */
 export const GROUP_DESCRIBE = {
-    "code-execution": "Run arbitrary GDScript, invoke arbitrary methods, evaluate an expression in a paused debug frame, or run a local asset-gen command backend.",
+    "code-execution": "Run arbitrary GDScript, invoke arbitrary methods, evaluate an expression in a paused debug frame, spawn headless child processes of the project, or run a local asset-gen command backend.",
     network: "Egress beyond loopback — the Group M backend SDK.",
 };
 /**
@@ -16,6 +16,10 @@ export const TOOL_CAPABILITIES = {
     godot_run_managed: ["code-execution"],
     node_call_method: ["code-execution"],
     runtime_call_method: ["code-execution"],
+    // F6: spawns headless Godot child processes of the project — the same class of
+    // trust as godot_run_managed, which is why it is privileged rather than merely
+    // confirmation-gated.
+    runtime_spawn_peers: ["code-execution"],
     dbg_evaluate: ["code-execution"],
     cs_dbg_evaluate: ["code-execution"],
     // asset generation — the local command backend (code-execution) is the only

package/dist/cli/doctor.js

@@ -193,7 +193,7 @@ export function checkCapabilities(config) {
             status: "ok",
             severity: "info",
             detail: dropped.length === 0
-                ? `${state} — full 276-tool surface`
+                ? `${state} — full 289-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 276-tool surface loads.`);
+        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 289-tool surface loads.`);
     }
     else {
         say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");