@satelliteoflove/godot-mcp 3.12.0 → 3.14.0

package/addon/commands/debug_commands.gd

@@ -125,6 +125,15 @@ func get_log_messages(params: Dictionary) -> Dictionary:
 	if clear:
 		MCPLogger.clear_errors()
 
+	# The phantom "Identifier not found: <autoload>" errors that mislead agents
+	# come from the editor running stale after project.godot was edited on disk
+	# (#245). When that divergence is present, attach it here so the caller reads
+	# the log and the "your editor is stale, restart it" advisory in one shot,
+	# instead of chasing compile errors that do not exist at runtime.
+	var staleness := MCPUtils.detect_project_staleness()
+	if staleness.get("stale", false):
+		result["staleness"] = staleness
+
 	return _success(result)
 
 

package/addon/commands/game_time_commands.gd

@@ -4,10 +4,11 @@ class_name MCPGameTimeCommands
 
 # Game-time control relay: freeze / step / step_until / thaw / status execute in
 # the game bridge (see mcp_game_bridge.gd); this side only forwards over the
-# debugger channel and waits. Timeout cascade: a step/step_until request is
-# capped at 20s of game time and the bridge's wall budget returns by 25s, so the
-# 28s relay timeout below fires only if the bridge is gone — and stays under the
-# server's 30s command timeout so errors surface typed instead of generic.
+# debugger channel and waits. Timeout cascade (#276): the server derives the
+# whole stagger from the call's in-game budget and pushes relay_timeout_ms down
+# in params; we wait exactly that long, so the bridge (which returns by its
+# pushed wall budget) answers first and errors surface typed. BASE_TIMEOUT and
+# STEP_TIMEOUT are fallbacks only — for an older server that pushes no budget.
 const BASE_TIMEOUT := 10.0
 const STEP_TIMEOUT := 28.0
 
@@ -29,11 +30,11 @@ func game_time_freeze(params: Dictionary) -> Dictionary:
 
 
 func game_time_step(params: Dictionary) -> Dictionary:
-	return await _relay("game_time_step", [params], STEP_TIMEOUT)
+	return await _relay("game_time_step", [params], _relay_timeout(params, STEP_TIMEOUT))
 
 
 func game_time_step_until(params: Dictionary) -> Dictionary:
-	return await _relay("game_time_step_until", [params], STEP_TIMEOUT)
+	return await _relay("game_time_step_until", [params], _relay_timeout(params, STEP_TIMEOUT))
 
 
 func game_time_thaw(params: Dictionary) -> Dictionary:
@@ -44,6 +45,13 @@ func game_time_status(params: Dictionary) -> Dictionary:
 	return await _relay("game_time_status", [params], BASE_TIMEOUT)
 
 
+func _relay_timeout(params: Dictionary, fallback: float) -> float:
+	# Use the server-pushed relay budget when present (#276); the local constant
+	# is only a fallback for an older server that does not derive the cascade.
+	var ms: float = float(params.get("relay_timeout_ms", fallback * 1000.0))
+	return ms / 1000.0
+
+
 func _relay(msg_type: String, args: Array, timeout: float) -> Dictionary:
 	var response = await _send_and_wait(msg_type, args, timeout)
 	if response == null:

package/addon/commands/input_commands.gd

@@ -34,19 +34,30 @@ func get_commands() -> Dictionary:
 	}
 
 
+# Total wall budget for a long-running input command. The server derives the
+# whole cascade and pushes relay_timeout_ms down in params (#276); the local
+# fallback is used only for an older server that pushes no budget.
+func _pushed_budget(params: Dictionary, fallback: float) -> float:
+	if params.has("relay_timeout_ms"):
+		return float(params["relay_timeout_ms"]) / 1000.0
+	return fallback
+
+
 # Block until the running game's bridge reports it can consume input, bounded by
-# READY_TIMEOUT. Returns true once ready, false if the game stops or never comes
-# up in time. In the common case (game already running) this returns immediately
-# without waiting a frame. Gating input on this is the fix for #241: the debug
-# session connects before the main scene loads, so input dispatched on
-# has_active_session() alone lands in a game with nothing to receive it.
-func _await_bridge_ready(debugger_plugin) -> bool:
-	var start_time := Time.get_ticks_msec()
+# READY_TIMEOUT and the shared call deadline (op_start + total_budget) so the
+# ready-wait can never eat the budget the command itself needs (#276). Returns
+# true once ready, false if the game stops or never comes up in time. In the
+# common case (game already running) this returns immediately without waiting a
+# frame. Gating input on this is the fix for #241: the debug session connects
+# before the main scene loads, so input dispatched on has_active_session() alone
+# lands in a game with nothing to receive it.
+func _await_bridge_ready(debugger_plugin, op_start: int, total_budget: float) -> bool:
 	while not debugger_plugin.is_bridge_ready():
 		if not EditorInterface.is_playing_scene():
 			return false  # game stopped or crashed while we waited
 		await Engine.get_main_loop().process_frame
-		if (Time.get_ticks_msec() - start_time) / 1000.0 > READY_TIMEOUT:
+		var elapsed := (Time.get_ticks_msec() - op_start) / 1000.0
+		if elapsed > READY_TIMEOUT or elapsed > total_budget:
 			return false
 	return true
 
@@ -90,7 +101,16 @@ func _get_editor_input_map() -> Dictionary:
 			"name": action_name,
 			"events": event_strings,
 		})
-	return _success({"actions": actions, "source": "editor"})
+	# This map is read from the editor's in-memory InputMap, which is loaded at
+	# startup and goes stale if project.godot's [input] section is edited on disk
+	# (#245). Flag that so the caller knows the map may be incomplete and can
+	# recover with `godot_editor restart`. The game-running path above reads fresh
+	# from the bridge, so it never carries this.
+	var result := {"actions": actions, "source": "editor"}
+	var staleness := MCPUtils.detect_project_staleness()
+	if staleness.get("stale", false):
+		result["staleness"] = staleness
+	return _success(result)
 
 
 func _event_to_string(event: InputEvent) -> String:
@@ -146,11 +166,12 @@ func execute_input_sequence(params: Dictionary) -> Dictionary:
 	var debugger_plugin = _plugin.get_debugger_plugin() if _plugin else null
 	if debugger_plugin == null:
 		return _error("NO_SESSION", "No active debug session")
-	if not await _await_bridge_ready(debugger_plugin):
-		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
-
-	# The window can extend past the last input if a frame capture is requested
-	# at a later offset, so factor capture offsets into the timeout too.
+	# One deadline for the whole call, stamped BEFORE the ready-wait so the
+	# bridge-ready gap is folded into the budget instead of stacking on top of
+	# it (#276). Prefer the server-pushed budget; the fallback (older server) is
+	# the longest input/capture offset plus headroom, floored at INPUT_TIMEOUT,
+	# plus the ready-wait that now counts against the same deadline.
+	var op_start := Time.get_ticks_msec()
 	var max_end_time: float = 0.0
 	for input in inputs:
 		var start_ms: float = input.get("start_ms", 0.0)
@@ -158,8 +179,11 @@ func execute_input_sequence(params: Dictionary) -> Dictionary:
 		max_end_time = max(max_end_time, start_ms + duration_ms)
 	for shot_ms in screenshots:
 		max_end_time = max(max_end_time, float(shot_ms))
+	var fallback: float = max(INPUT_TIMEOUT, (max_end_time / 1000.0) + 5.0) + READY_TIMEOUT
+	var timeout := _pushed_budget(params, fallback)
 
-	var timeout := max(INPUT_TIMEOUT, (max_end_time / 1000.0) + 5.0)
+	if not await _await_bridge_ready(debugger_plugin, op_start, timeout):
+		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
 
 	_sequence_pending = true
 	_sequence_result = {}
@@ -171,10 +195,9 @@ func execute_input_sequence(params: Dictionary) -> Dictionary:
 	debugger_plugin.input_sequence_completed.connect(_on_sequence_completed, CONNECT_ONE_SHOT)
 	debugger_plugin.request_input_sequence(inputs, report, screenshots, screenshot_max_width)
 
-	var start_time := Time.get_ticks_msec()
 	while _sequence_pending:
 		await Engine.get_main_loop().process_frame
-		if (Time.get_ticks_msec() - start_time) / 1000.0 > timeout:
+		if (Time.get_ticks_msec() - op_start) / 1000.0 > timeout:
 			_sequence_pending = false
 			if debugger_plugin.input_sequence_completed.is_connected(_on_sequence_completed):
 				debugger_plugin.input_sequence_completed.disconnect(_on_sequence_completed)
@@ -225,10 +248,14 @@ func type_text(params: Dictionary) -> Dictionary:
 	var debugger_plugin = _plugin.get_debugger_plugin() if _plugin else null
 	if debugger_plugin == null:
 		return _error("NO_SESSION", "No active debug session")
-	if not await _await_bridge_ready(debugger_plugin):
-		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
+	# Shared deadline (ready-wait + typing), stamped before the ready-wait so the
+	# gap is folded into the budget (#276); server-pushed budget or local fallback.
+	var op_start := Time.get_ticks_msec()
+	var fallback: float = max(INPUT_TIMEOUT, (text.length() * delay_ms / 1000.0) + 5.0) + READY_TIMEOUT
+	var timeout := _pushed_budget(params, fallback)
 
-	var timeout := max(INPUT_TIMEOUT, (text.length() * delay_ms / 1000.0) + 5.0)
+	if not await _await_bridge_ready(debugger_plugin, op_start, timeout):
+		return _error("BRIDGE_NOT_READY", _BRIDGE_NOT_READY_MSG)
 
 	_type_text_pending = true
 	_type_text_result = {}
@@ -236,10 +263,9 @@ func type_text(params: Dictionary) -> Dictionary:
 	debugger_plugin.type_text_completed.connect(_on_type_text_completed, CONNECT_ONE_SHOT)
 	debugger_plugin.request_type_text(text, delay_ms, submit)
 
-	var start_time := Time.get_ticks_msec()
 	while _type_text_pending:
 		await Engine.get_main_loop().process_frame
-		if (Time.get_ticks_msec() - start_time) / 1000.0 > timeout:
+		if (Time.get_ticks_msec() - op_start) / 1000.0 > timeout:
 			_type_text_pending = false
 			if debugger_plugin.type_text_completed.is_connected(_on_type_text_completed):
 				debugger_plugin.type_text_completed.disconnect(_on_type_text_completed)

package/addon/commands/project_commands.gd

@@ -6,10 +6,18 @@ class_name MCPProjectCommands
 func get_commands() -> Dictionary:
 	return {
 		"get_project_info": get_project_info,
-		"get_project_settings": get_project_settings
+		"get_project_settings": get_project_settings,
+		"get_project_staleness": get_project_staleness,
 	}
 
 
+# Detect whether project.godot was edited on disk after the editor loaded it,
+# leaving the editor's in-memory ProjectSettings / InputMap stale (#245). Always
+# returns the full report (stale or not); recovery is `godot_editor restart`.
+func get_project_staleness(_params: Dictionary) -> Dictionary:
+	return _success(MCPUtils.detect_project_staleness())
+
+
 func get_project_info(_params: Dictionary) -> Dictionary:
 	return _success({
 		"name": ProjectSettings.get_setting("application/config/name", "Unknown"),

package/addon/core/mcp_utils.gd

@@ -127,3 +127,174 @@ static func ensure_dir_exists(path: String) -> Error:
 			return ERR_CANT_OPEN
 		return dir.make_dir_recursive(path.trim_prefix("res://"))
 	return DirAccess.make_dir_recursive_absolute(path)
+
+
+# ── project.godot staleness (#245) ────────────────────────────────────────────
+# The editor caches ProjectSettings / InputMap in memory at load. An agent that
+# edits project.godot as a file (batch-writing autoloads / input map) leaves the
+# editor stale: its log fills with phantom "Identifier not found: <autoload>"
+# errors that do not exist at runtime, and its input map is out of date — while
+# spawned games (which read disk fresh at launch) work fine. We detect that by
+# content-diffing the two sections that actually cause the trap, [autoload] and
+# [input], disk vs the editor's in-memory state. Recovery is `godot_editor
+# restart` (#250). A content diff (not an mtime check) is used deliberately: it
+# never false-positives when the editor itself saves project.godot (e.g. the
+# plugin's own startup autoload write), because disk is then written FROM memory.
+
+
+# Pure: diff already-read disk vs in-memory sets. No engine access, so this is
+# unit-testable headless. Autoloads are symmetric (added/removed/value-changed,
+# raw-string compare incl. the "*" singleton prefix). Input is additive-only
+# (actions present on disk but not loaded — the trap); the reverse direction and
+# event values are intentionally ignored (built-in ui_* noise / fragile compares).
+static func diff_project_staleness(
+		disk_autoloads: Dictionary, mem_autoloads: Dictionary,
+		disk_input_keys: Array, mem_input_keys: Array) -> Dictionary:
+	var autoload_added := []
+	var autoload_removed := []
+	var autoload_changed := []
+	for key in disk_autoloads:
+		if not mem_autoloads.has(key):
+			autoload_added.append(key)
+		elif str(disk_autoloads[key]) != str(mem_autoloads[key]):
+			autoload_changed.append(key)
+	for key in mem_autoloads:
+		if not disk_autoloads.has(key):
+			autoload_removed.append(key)
+
+	var mem_input_set := {}
+	for k in mem_input_keys:
+		mem_input_set[k] = true
+	var input_added := []
+	for k in disk_input_keys:
+		if not mem_input_set.has(k):
+			input_added.append(k)
+
+	autoload_added.sort()
+	autoload_removed.sort()
+	autoload_changed.sort()
+	input_added.sort()
+
+	var stale: bool = not (autoload_added.is_empty() and autoload_removed.is_empty()
+		and autoload_changed.is_empty() and input_added.is_empty())
+
+	return {
+		"stale": stale,
+		"autoload": {
+			"added": autoload_added,
+			"removed": autoload_removed,
+			"changed": autoload_changed,
+		},
+		"input": {"added": input_added},
+		"summary": _staleness_summary(autoload_added, autoload_removed, autoload_changed, input_added),
+	}
+
+
+static func _staleness_summary(a_added: Array, a_removed: Array, a_changed: Array, i_added: Array) -> String:
+	var parts := []
+	if not a_added.is_empty():
+		parts.append("%d autoload(s) added on disk (%s)" % [a_added.size(), ", ".join(a_added)])
+	if not a_removed.is_empty():
+		parts.append("%d autoload(s) removed on disk (%s)" % [a_removed.size(), ", ".join(a_removed)])
+	if not a_changed.is_empty():
+		parts.append("%d autoload(s) changed on disk (%s)" % [a_changed.size(), ", ".join(a_changed)])
+	if not i_added.is_empty():
+		parts.append("%d input action(s) added on disk (%s)" % [i_added.size(), ", ".join(i_added)])
+	if parts.is_empty():
+		return "project.godot on disk matches the editor's loaded settings."
+	return ("project.godot was edited on disk after the editor loaded it: %s. The editor's in-memory "
+		+ "settings are stale (its log may show phantom \"Identifier not found\" errors that do not "
+		+ "exist at runtime). Run `godot_editor restart` to reload project.godot (save:false to discard "
+		+ "unsaved editor changes).") % "; ".join(parts)
+
+
+# Editor-context orchestrator. Reads project.godot from disk (a plain text scan,
+# NOT ConfigFile — which would eagerly instantiate the [input] InputEvent
+# sub-objects) and the in-memory ProjectSettings, then diffs. Never throws: any
+# read failure returns {stale=false, note=...} so a transient I/O hiccup can
+# never produce a false "stale" (recovery is disruptive — silence beats crying
+# wolf). The {stale, autoload, input, summary} shape mirrors diff_project_staleness.
+static func detect_project_staleness() -> Dictionary:
+	var disk := _read_disk_project_sections()
+	if disk.is_empty():
+		return {"stale": false, "note": "Could not read res://project.godot to check staleness."}
+
+	var mem := _read_mem_sections()
+	var mem_autoloads: Dictionary = mem["autoload"]
+	var disk_autoloads: Dictionary = disk.get("autoload", {})
+	# A project with autoloads always writes the [autoload] section (the addon
+	# writes its own bridge autoload at startup). If the section is absent, treat
+	# it as "nothing to compare" rather than "everything removed".
+	if not disk.get("has_autoload_section", false):
+		disk_autoloads = mem_autoloads.duplicate()
+
+	return diff_project_staleness(
+		disk_autoloads, mem_autoloads,
+		disk.get("input_keys", []), mem["input_keys"])
+
+
+# Scan project.godot once, section-aware. Returns
+#   { autoload: {Name: "value"}, input_keys: [action,...], has_autoload_section }
+# or {} if the file can't be read. Only [autoload] (name + unquoted value) and
+# [input] (action NAMES only — the InputEvent dicts are never parsed) are read.
+static func _read_disk_project_sections() -> Dictionary:
+	if not FileAccess.file_exists("res://project.godot"):
+		MCPLog.warn("project.godot not found; skipping staleness check")
+		return {}
+	var text := FileAccess.get_file_as_string("res://project.godot")
+	if text.is_empty():
+		MCPLog.warn("Could not read project.godot for staleness check")
+		return {}
+
+	var autoloads := {}
+	var input_keys := []
+	var has_autoload := false
+	var section := ""
+	# A top-level key line: identifier `=` value, at column 0. Dict-body lines of
+	# an [input] action start with `"`/`}`/`]` (or are indented), so they never match.
+	var key_re := RegEx.new()
+	key_re.compile("^([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+
+	for raw in text.split("\n"):
+		var line := raw.strip_edges(false, true)  # trailing only (drops CR / spaces)
+		if line.begins_with("[") and line.ends_with("]"):
+			section = line.substr(1, line.length() - 2)
+			if section == "autoload":
+				has_autoload = true
+			continue
+		if section != "autoload" and section != "input":
+			continue
+		var m := key_re.search(line)
+		if m == null:
+			continue
+		var key := m.get_string(1)
+		if section == "autoload":
+			autoloads[key] = _unquote(m.get_string(2))
+		elif not key.begins_with("ui_"):
+			input_keys.append(key)
+
+	return {"autoload": autoloads, "input_keys": input_keys, "has_autoload_section": has_autoload}
+
+
+# Single pass over ProjectSettings (it carries hundreds of entries) collecting
+# both the in-memory autoloads ({Name: value}) and the non-builtin input action
+# names. Returns { autoload: Dictionary, input_keys: Array }.
+static func _read_mem_sections() -> Dictionary:
+	var autoloads := {}
+	var input_keys := []
+	for prop in ProjectSettings.get_property_list():
+		var pname: String = prop["name"]
+		if pname.begins_with("autoload/"):
+			autoloads[pname.substr(9)] = str(ProjectSettings.get_setting(pname, ""))
+		elif pname.begins_with("input/"):
+			var action := pname.substr(6)
+			if not action.begins_with("ui_"):
+				input_keys.append(action)
+	return {"autoload": autoloads, "input_keys": input_keys}
+
+
+static func _unquote(s: String) -> String:
+	var t := s.strip_edges()
+	if t.length() >= 2 and t.begins_with("\"") and t.ends_with("\""):
+		return t.substr(1, t.length() - 2)
+	return t

package/addon/game_bridge/mcp_game_bridge.gd

@@ -283,11 +283,13 @@ var _sequence_capture_offsets: Array = []
 var _sequence_captures_pending: int = 0
 var _sequence_capture_max_width: int = 640
 const SEQUENCE_MAX_CAPTURES := 8
-# Capped well under the 30s server command timeout: the sequence runs until its
-# last capture offset, so a larger value would let the whole call time out
-# server-side. 20s is already far longer than any transient-visual capture needs.
-# This bound is a placeholder for the global-timeout fix tracked in godot-mcp#276.
-const SEQUENCE_MAX_CAPTURE_OFFSET_MS := 20000
+# Non-binding sanity backstop only (#276). The server derives the per-call
+# timeout from the sequence span and rejects offsets beyond what the ceiling
+# permits before they ever reach here, so this just guards a malformed direct
+# message. Kept far above any server-permitted budget so it never silently
+# clamps a legitimate offset (which would reintroduce the cross-layer drift
+# that #276 removed).
+const SEQUENCE_MAX_CAPTURE_OFFSET_MS := 300000
 # Actions whose press has been injected but whose paired release has not yet
 # fired. Used to guarantee a release even if the queue is cleared mid-flight
 # (new sequence) or the node leaves the tree — otherwise the dropped release
@@ -1332,10 +1334,15 @@ func _type_text_async(text: String, delay_ms: int, submit: bool) -> void:
 # ---------------------------------------------------------------------------
 
 const LAUNCH_FROZEN_ENV := "GODOT_MCP_LAUNCH_FROZEN"
-# Timeout cascade: step request <= 20s game time, wall budget 25s, editor
-# relay 28s, server command timeout 30s. Each layer answers before the one
-# above it gives up.
-const STEP_MAX_MS := 20000
+# Timeout cascade (#276): the server derives the whole stagger from the call's
+# in-game budget and pushes wall_budget_ms down here. The bridge returns by that
+# wall budget, the editor relay waits a margin longer, the server socket a
+# margin longer still — each answers before the one above gives up.
+#   STEP_MAX_MS         non-binding sanity backstop (the server already clamps the request)
+#   STEP_DEFAULT_MS     budget used when a call omits max_ms (older server that sends no default)
+#   STEP_WALL_BUDGET_MS wall-budget fallback when the server pushes no wall_budget_ms
+const STEP_MAX_MS := 300000
+const STEP_DEFAULT_MS := 20000
 const STEP_MAX_FRAMES := 1200
 const STEP_WALL_BUDGET_MS := 25000
 const STEP_MAX_TRANSITIONS := 50
@@ -1358,6 +1365,7 @@ var _step_gameplay_ms := 0.0  # the unpaused portion: what gameplay actually exp
 var _step_frames := 0
 var _step_physics_ticks := 0
 var _step_wall_start := 0
+var _step_wall_budget_ms := STEP_WALL_BUDGET_MS  # set per-call from the server-pushed wall_budget_ms (#276)
 var _step_events: Array = []  # in-step input timeline, scheduled on the game-time clock
 var _step_events_fired := 0
 var _step_transitions: Array = []
@@ -1515,6 +1523,7 @@ func _handle_game_time_step(data: Array) -> void:
 	_step_finish_pending = false
 	_step_wall_exceeded = false
 	_step_wall_start = Time.get_ticks_msec()
+	_step_wall_budget_ms = int(params.get("wall_budget_ms", STEP_WALL_BUDGET_MS))
 	_step_predicate = null
 	_step_response_type = "game_time_step"
 	_step_active = true
@@ -1631,9 +1640,9 @@ func _handle_game_time_step_until(data: Array) -> void:
 		_send_game_time_response("game_time_step_until", {"error": "step_until requires a non-empty `until` expression"})
 		return
 
-	var max_ms: int = int(params.get("max_ms", STEP_MAX_MS))
+	var max_ms: int = int(params.get("max_ms", STEP_DEFAULT_MS))
 	if max_ms <= 0:
-		max_ms = STEP_MAX_MS
+		max_ms = STEP_DEFAULT_MS
 	max_ms = mini(max_ms, STEP_MAX_MS)
 
 	# Compile and validate the predicate against the live tree before committing
@@ -1696,6 +1705,7 @@ func _handle_game_time_step_until(data: Array) -> void:
 	_step_finish_pending = false
 	_step_wall_exceeded = false
 	_step_wall_start = Time.get_ticks_msec()
+	_step_wall_budget_ms = int(params.get("wall_budget_ms", STEP_WALL_BUDGET_MS))
 	_step_predicate = expr
 	_step_predicate_inputs = ctx_inputs
 	_step_predicate_met = false
@@ -1767,7 +1777,7 @@ func _step_process(delta: float) -> void:
 			_step_predicate_met = true
 			done = true
 
-	if Time.get_ticks_msec() - _step_wall_start > STEP_WALL_BUDGET_MS:
+	if Time.get_ticks_msec() - _step_wall_start > _step_wall_budget_ms:
 		# Slow-mo, Engine.time_scale = 0, or a pause-held window can starve
 		# the game-time clock; the wall budget guarantees the call returns
 		# (partial, honestly reported) before the editor relay gives up.

package/addon/plugin.cfg

@@ -3,6 +3,6 @@
 name="Godot MCP"
 description="Model Context Protocol server for AI assistant integration"
 author="godot-mcp"
-version="3.12.0"
+version="3.14.0"
 script="plugin.gd"
 godot_version_min="4.5"

package/dist/__tests__/connection/timeouts.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timeouts.test.d.ts.map

package/dist/__tests__/connection/timeouts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/connection/timeouts.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/connection/timeouts.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { deriveTimeouts, maxInGameBudgetMs, QUICK_TIMEOUT_MS, ABSOLUTE_CEILING_MS, READY_WAIT_MS, BRIDGE_WALL_SLOP_MS, STEP_BUDGET_CAP_MS, INPUT_BUDGET_CAP_MS, } from '../../connection/timeouts.js';
+describe('timeout cascade (#276)', () => {
+    describe('deriveTimeouts stagger invariant', () => {
+        // The whole point: bridge answers before relay answers before the server
+        // gives up, and the server never exceeds the absolute ceiling — for ANY
+        // budget, clamped or not, with or without the ready-wait.
+        const cases = [
+            { label: 'zero budget, no ready', budget: 0, readyWait: false },
+            { label: 'mid budget, no ready', budget: 5_000, readyWait: false },
+            { label: 'at step cap', budget: STEP_BUDGET_CAP_MS, readyWait: false },
+            { label: 'over cap, no ready', budget: 10_000_000, readyWait: false },
+            { label: 'zero budget, ready', budget: 0, readyWait: true },
+            { label: 'at input cap', budget: INPUT_BUDGET_CAP_MS, readyWait: true },
+            { label: 'over cap, ready', budget: 999_999, readyWait: true },
+        ];
+        for (const c of cases) {
+            it(`${c.label}: bridgeWall < relay < server <= ceiling`, () => {
+                const t = deriveTimeouts(c.budget, { readyWait: c.readyWait });
+                expect(t.bridgeWallMs).toBeLessThan(t.relayMs);
+                expect(t.relayMs).toBeLessThan(t.serverMs);
+                expect(t.serverMs).toBeLessThanOrEqual(ABSOLUTE_CEILING_MS);
+                expect(t.clampedBudgetMs).toBeGreaterThanOrEqual(0);
+                expect(t.clampedBudgetMs).toBeLessThanOrEqual(maxInGameBudgetMs({ readyWait: c.readyWait }));
+            });
+        }
+    });
+    it('produces a proportionally small (sub-ceiling) timeout for a small budget', () => {
+        const t = deriveTimeouts(3_000, { readyWait: false });
+        // bridgeWall = 3000 + slop; relay = +2000; server = +2000.
+        expect(t.bridgeWallMs).toBe(3_000 + BRIDGE_WALL_SLOP_MS);
+        expect(t.serverMs).toBeLessThan(ABSOLUTE_CEILING_MS);
+    });
+    it('reserves an extra READY_WAIT_MS of headroom when the ready-wait applies', () => {
+        expect(maxInGameBudgetMs({ readyWait: false }) - maxInGameBudgetMs({ readyWait: true })).toBe(READY_WAIT_MS);
+    });
+    it('clamps an over-budget request to the ceiling, never beyond', () => {
+        expect(deriveTimeouts(Number.MAX_SAFE_INTEGER, { readyWait: true }).serverMs).toBe(ABSOLUTE_CEILING_MS);
+        expect(deriveTimeouts(Number.MAX_SAFE_INTEGER, { readyWait: false }).serverMs).toBe(ABSOLUTE_CEILING_MS);
+    });
+    it('handles a non-finite budget defensively (treats it as zero)', () => {
+        const t = deriveTimeouts(NaN, { readyWait: false });
+        expect(t.clampedBudgetMs).toBe(0);
+        expect(t.serverMs).toBeGreaterThan(0);
+    });
+    describe('published caps stay under the ceiling so they can never time out server-side', () => {
+        it('step cap <= max in-game budget (no ready-wait)', () => {
+            expect(STEP_BUDGET_CAP_MS).toBeLessThanOrEqual(maxInGameBudgetMs({ readyWait: false }));
+        });
+        it('input cap <= max in-game budget (with ready-wait)', () => {
+            expect(INPUT_BUDGET_CAP_MS).toBeLessThanOrEqual(maxInGameBudgetMs({ readyWait: true }));
+        });
+    });
+    it('keeps the quick default unchanged at 30s', () => {
+        expect(QUICK_TIMEOUT_MS).toBe(30_000);
+    });
+});
+//# sourceMappingURL=timeouts.test.js.map

package/dist/__tests__/connection/timeouts.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeouts.test.js","sourceRoot":"","sources":["../../../src/__tests__/connection/timeouts.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/connection/websocket.test.js

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { once } from 'node:events';
 import { WebSocketServer } from 'ws';
 import { GodotConnection } from '../../connection/websocket.js';
+import { getServerVersion } from '../../version.js';
 // Keep diagnostics hermetic (no WSL detection / no child processes) and quiet.
 vi.mock('../../utils/connection-strategy.js', () => ({
     getTargetHost: () => '127.0.0.1',
@@ -105,4 +106,61 @@ describe('GodotConnection contention handling (#237)', () => {
         expect(message).toMatch(/reconnect/i);
     });
 });
+describe('GodotConnection per-request timeout (#276)', () => {
+    let connection = null;
+    let wss = null;
+    afterEach(async () => {
+        connection?.disconnect();
+        connection = null;
+        if (wss) {
+            await new Promise((resolve) => wss.close(() => resolve()));
+            wss = null;
+        }
+    });
+    // Reply to the handshake (so connect() resolves immediately and without a
+    // version-mismatch), then let the supplied handler deal with real commands.
+    async function bridgeAfterHandshake(onCommand) {
+        return startFakeBridge((socket) => {
+            socket.on('message', (raw) => {
+                let msg;
+                try {
+                    msg = JSON.parse(raw.toString());
+                }
+                catch {
+                    return;
+                }
+                if (!msg)
+                    return;
+                if (msg.command === 'mcp_handshake') {
+                    socket.send(JSON.stringify({ id: msg.id, status: 'success', result: { addon_version: getServerVersion() } }));
+                    return;
+                }
+                onCommand(socket, msg);
+            });
+        });
+    }
+    it('rejects after opts.timeoutMs when the bridge never answers the command', async () => {
+        // Drop every non-handshake command on the floor.
+        const bridge = await bridgeAfterHandshake(() => { });
+        wss = bridge.wss;
+        connection = new GodotConnection({ host: '127.0.0.1', port: bridge.port, autoReconnect: false });
+        await connection.connect();
+        const start = Date.now();
+        await expect(connection.sendCommand('get_runtime_state', {}, { timeoutMs: 150 })).rejects.toThrow();
+        const elapsed = Date.now() - start;
+        expect(elapsed).toBeGreaterThanOrEqual(120);
+        expect(elapsed).toBeLessThan(2000);
+    });
+    it('does not fire early when given a generous opts.timeoutMs', async () => {
+        // Answer the command after a short delay; a 1s budget must not trip on it.
+        const bridge = await bridgeAfterHandshake((socket, msg) => {
+            setTimeout(() => socket.send(JSON.stringify({ id: msg.id, status: 'success', result: { ok: true } })), 100);
+        });
+        wss = bridge.wss;
+        connection = new GodotConnection({ host: '127.0.0.1', port: bridge.port, autoReconnect: false });
+        await connection.connect();
+        const result = await connection.sendCommand('get_runtime_state', {}, { timeoutMs: 1000 });
+        expect(result.ok).toBe(true);
+    });
+});
 //# sourceMappingURL=websocket.test.js.map