gdharness 0.7.0 → 0.9.0

package/build/cli.js

@@ -15783,6 +15783,11 @@ var init_tool_definitions = __esm(() => {
           description: 'find: a case-insensitive glob on the node name, such as "Enemy*".'
         },
         group: { type: "string", ops: ["find"], description: "find: a group the node is in." },
+        says: {
+          type: "string",
+          ops: ["find"],
+          description: "find: part of what the node has written on it, case-insensitively, which is how a button is reached by the word on it rather than by a generated path. Its own text, so a row is found by the label in it, and hidden nodes match."
+        },
         limit: {
           type: "number",
           ops: ["find", "text"],
@@ -15808,7 +15813,7 @@ var init_tool_definitions = __esm(() => {
           requires: []
         },
         find: {
-          summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
+          summary: "the paths of every node matching className, script, namePattern, group or says, with property read off each",
           requires: []
         },
         rect: {
@@ -15874,7 +15879,11 @@ var init_tool_definitions = __esm(() => {
           ops: ["click", "choose"],
           description: "click: the Control to click, at its centre, or the 3D node to click, where it is drawn. choose: the PopupMenu, or the OptionButton or MenuButton in front of one."
         },
-        action: { type: "string", ops: ["action"], description: "action: the InputMap action name." },
+        action: {
+          type: "string",
+          ops: ["action"],
+          description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with key Escape, or click its button."
+        },
         pressed: {
           type: "boolean",
           ops: ["action", "key", "mouse_click"],
@@ -15957,7 +15966,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "runtime_wait",
-      description: "Lets the running game get on with it and answers when something has happened: a number of frames, a signal, or a property reaching a value. Needs the game running with the runtime addon.",
+      description: "Lets the running game get on with it and answers when something has happened: a number of frames, a signal, a property reaching a value, or words appearing on a screen. Needs the game running with the runtime addon.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
         frames: {
@@ -15969,6 +15978,11 @@ var init_tool_definitions = __esm(() => {
         signal: { type: "string", ops: ["signal"], description: "signal: the signal name." },
         property: { type: "string", ops: ["until"], description: "until: the property name." },
         value: { ops: ["until"], description: "until: the value to wait for, fitted to the property's type." },
+        says: {
+          type: "string",
+          ops: ["until"],
+          description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, hidden nodes included."
+        },
         timeoutMs: {
           type: "number",
           ops: ["signal", "until"],
@@ -15983,8 +15997,8 @@ var init_tool_definitions = __esm(() => {
           requires: ["nodePath", "signal"]
         },
         until: {
-          summary: "wait for a property to read as a value and answer with what it read",
-          requires: ["nodePath", "property", "value"]
+          summary: "wait for a property to read as a value, or for words to appear under a node, and answer with what it found",
+          requires: ["nodePath"]
         }
       }
     },
@@ -37491,6 +37505,7 @@ class GodotServer {
     const script = readNonEmptyString(args, "script");
     const namePattern = readNonEmptyString(args, "namePattern");
     const group = readNonEmptyString(args, "group");
+    const says = readNonEmptyString(args, "says");
     if (className !== undefined)
       filters["class"] = className;
     if (script !== undefined)
@@ -37499,8 +37514,10 @@ class GodotServer {
       filters["name"] = namePattern;
     if (group !== undefined)
       filters["group"] = group;
+    if (says !== undefined)
+      filters["says"] = says;
     if (Object.keys(filters).length === 0) {
-      return this.createErrorResponse("runtime_inspect find needs at least one of className, script, namePattern, group.");
+      return this.createErrorResponse("runtime_inspect find needs at least one of className, script, namePattern, group, says.");
     }
     const property = readNonEmptyString(args, "property");
     return await this.handleRuntimeCommand("find_nodes", {
@@ -37530,6 +37547,7 @@ class GodotServer {
       path: nodePath,
       property: readString(args, "property") ?? "",
       value: args["value"],
+      ...readNonEmptyString(args, "says") === undefined ? {} : { says: readNonEmptyString(args, "says") },
       timeout_ms: timeoutMs
     }, patience);
   }
@@ -38905,15 +38923,17 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | Ask | Tool |
 | --- | --- |
 | What a screen says | \`runtime_inspect text\`, which reads what is drawn and leaves out what is hidden |
+| Find a control by the word on it | \`runtime_inspect find\` with \`says\`, rather than listing a screen and reading each one |
 | Where a control is, and whether it is visible | \`runtime_inspect\` \`find\`, \`rect\` |
 | What a property reads right now | \`runtime_inspect\` \`property\`, \`runtime_invoke\` |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |
 | Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\` with \`replace\`; a submitted field has to be clicked again |
 | Click somebody standing in a 3D room | \`runtime_input click\` on the Node3D, which aims at what it draws |
 | Pick something out of a dropdown | \`runtime_input choose\` on it, by what the item says |
-| Answer a dialog, or press a bound key | \`runtime_input action\` or \`key\`, a whole press unless you hold it |
+| Answer a dialog | \`runtime_input click\` on its button, or \`key\` Escape to dismiss it: an [AcceptDialog] reads that key itself and never asks the InputMap, so \`ui_cancel\` leaves it standing |
+| Press a bound key | \`runtime_input action\` or \`key\`, a whole press unless you hold it |
 | Where a 3D node is on screen | \`runtime_inspect\` \`rect\`, rather than unprojecting by hand |
-| Wait for something | \`runtime_wait\`, never a sleep |
+| Wait for something | \`runtime_wait\`, never a sleep; \`until\` with \`says\` for a panel that rebuilds its own labels |
 | A picture, for a person who asked to see one | \`runtime_capture\` |
 
 These need the runtime autoload, which \`gdharness setup\` registers. \`runtime_capture\` needs a

package/build/godot/addons/gdharness_runtime/runtime_queries.gd

@@ -10,6 +10,10 @@ const Values = preload("runtime_values.gd")
 const FIND_LIMIT: int = 100
 const FIND_LIMIT_CEILING: int = 1000
 
+## What a find can be narrowed by, which is also what it refuses to answer without. Named once so
+## the refusal lists the same set the walk reads.
+const FILTERS: PackedStringArray = ["class", "script", "name", "group", "says"]
+
 ## The most lines one read answers with, unless asked for fewer. A screen is a few dozen; a
 ## thousand is a tree somebody pointed this at by mistake.
 const READ_LIMIT: int = 500
@@ -39,7 +43,8 @@ func get_tree(params: Dictionary) -> Dictionary:
 
 ## Nodes matching every filter given, as paths, so a caller can name what it wants without
 ## reading the whole tree to find it. `class` matches native classes and their subclasses, and
-## the global name of a script class; `name` is a case-insensitive glob; `script` is a path.
+## the global name of a script class; `name` is a case-insensitive glob; `script` is a path;
+## `says` is what the node has written on it.
 ##
 ## `property` names one to read off each of them, which is the difference between one question and
 ## one call per answer. A panel of a dozen labels took thirteen calls to read, and a tree that
@@ -48,22 +53,16 @@ func get_tree(params: Dictionary) -> Dictionary:
 ## because null is what a node holding null answers.
 func find_nodes(params: Dictionary) -> Dictionary:
 	var root_path: String = str(params.get("root", "/root"))
-	var wanted_class: String = str(params.get("class", ""))
-	var wanted_script: String = str(params.get("script", ""))
-	var wanted_name: String = str(params.get("name", ""))
-	var wanted_group: String = str(params.get("group", ""))
+	var wanted: Dictionary[String, String] = {}
+	for filter: String in FILTERS:
+		wanted[filter] = str(params.get(filter, ""))
 	var wanted_property: String = str(params.get("property", ""))
 	var limit: int = clampi(int(params.get("limit", FIND_LIMIT)), 1, FIND_LIMIT_CEILING)
 
-	if (
-		wanted_class.is_empty()
-		and wanted_script.is_empty()
-		and wanted_name.is_empty()
-		and wanted_group.is_empty()
-	):
-		return {"type": "error", "message": "find_nodes needs at least one of class, script, name, group"}
-	if not wanted_script.is_empty() and not wanted_script.begins_with("res://"):
-		wanted_script = "res://" + wanted_script
+	if not _anything_asked(wanted):
+		return {"type": "error", "message": "find_nodes needs at least one of " + ", ".join(FILTERS)}
+	if not wanted["script"].is_empty() and not wanted["script"].begins_with("res://"):
+		wanted["script"] = "res://" + wanted["script"]
 
 	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
 	if root == null:
@@ -74,7 +73,7 @@ func find_nodes(params: Dictionary) -> Dictionary:
 	var truncated: bool = false
 	while not pending.is_empty():
 		var node: Node = pending.pop_front()
-		if _matches(node, wanted_class, wanted_script, wanted_name, wanted_group):
+		if _matches(node, wanted):
 			if found.size() >= limit:
 				truncated = true
 				break
@@ -115,25 +114,37 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	return entry
 
 
-func _matches(
-	node: Node, wanted_class: String, wanted_script: String, wanted_name: String, wanted_group: String
-) -> bool:
-	if not wanted_group.is_empty() and not node.is_in_group(wanted_group):
+## Whether the caller named anything to match on, since every filter left out matches everything
+## and a find with none of them is the whole tree by another name.
+static func _anything_asked(wanted: Dictionary[String, String]) -> bool:
+	for filter: String in wanted:
+		if not wanted[filter].is_empty():
+			return true
+	return false
+
+
+func _matches(node: Node, wanted: Dictionary[String, String]) -> bool:
+	if not wanted["group"].is_empty() and not node.is_in_group(wanted["group"]):
 		return false
-	if not wanted_name.is_empty() and not str(node.name).matchn(wanted_name):
+	if not wanted["name"].is_empty() and not str(node.name).matchn(wanted["name"]):
+		return false
+	# What this node says, rather than everything said underneath it. A row is then found by the
+	# label in it, and the path answered is that label's, which is where the words a caller is
+	# looking at actually are: matching every container above it would answer with the screen.
+	if not wanted["says"].is_empty() and not said_by(node).containsn(wanted["says"]):
 		return false
 	var script: Variant = node.get_script()
-	if not wanted_script.is_empty():
+	if not wanted["script"].is_empty():
 		if not script is Script:
 			return false
 		var attached: Script = script
-		if attached.resource_path != wanted_script:
+		if attached.resource_path != wanted["script"]:
 			return false
-	if not wanted_class.is_empty() and not node.is_class(wanted_class):
+	if not wanted["class"].is_empty() and not node.is_class(wanted["class"]):
 		if not script is Script:
 			return false
 		var attached: Script = script
-		if attached.get_global_name() != wanted_class:
+		if attached.get_global_name() != wanted["class"]:
 			return false
 	return true
 
@@ -195,7 +206,7 @@ func _read_into(node: Node, include_hidden: bool, most: int, into: PackedStringA
 		return
 	if not include_hidden and not _drawn(node):
 		return
-	var said: String = _said_by(node)
+	var said: String = said_by(node)
 	if not said.is_empty():
 		into.append(said)
 	for child: Node in node.get_children(true):
@@ -213,7 +224,11 @@ static func _drawn(node: Node) -> bool:
 
 ## What one node says, or "" for a node that says nothing. Anything with a `text` property, which
 ## is every label, button and field the interface is built out of.
-static func _said_by(node: Node) -> String:
+##
+## Public because three questions are the same question: what a screen reads as, which nodes say a
+## given word, and whether anything has come to say it yet. Two copies of what a node says is how
+## the three of them come to disagree about a SpinBox.
+static func said_by(node: Node) -> String:
 	for property: Dictionary in node.get_property_list():
 		if str(property.get("name", "")) == "text" and int(property.get("type", 0)) == TYPE_STRING:
 			return str(node.get("text")).strip_edges()

package/build/godot/addons/gdharness_runtime/runtime_waits.gd

@@ -3,6 +3,7 @@ extends RefCounted
 ## The commands that take time: they let the game run and answer when what was waited for has
 ## happened, or when the time ran out, so the caller never sleeps for a guessed length.
 
+const Queries = preload("runtime_queries.gd")
 const Values = preload("runtime_values.gd")
 
 ## The longest one wait may last, whatever the request says: past this the server has long
@@ -78,22 +79,27 @@ func wait_signal(params: Dictionary) -> Dictionary:
 	}
 
 
-## Waits until a property reads as the value given, or the time runs out, and answers with
-## what it read last either way.
+## Waits until a property reads as the value given, or until something under the path says what
+## was given, or the time runs out, and answers with what it read last either way.
 func wait_until(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var property: String = str(params.get("property", ""))
+	var says: String = str(params.get("says", ""))
 	var timeout_ms: int = int(params.get("timeout_ms", 5000))
 	if timeout_ms < 1 or timeout_ms > CEILING_MSEC:
 		return _out_of_range("timeout_ms", timeout_ms, 1, CEILING_MSEC)
-	if node_path.is_empty() or property.is_empty():
-		return {"type": "error", "message": "Node path and property required"}
+	if node_path.is_empty():
+		return {"type": "error", "message": "Node path required"}
+	if _host.get_tree().root.get_node_or_null(node_path) == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+	if not says.is_empty():
+		return await _wait_until_said(node_path, says, timeout_ms)
+	if property.is_empty():
+		return {"type": "error", "message": "A property and a value, or says, are required"}
 	if not params.has("value"):
 		return {"type": "error", "message": "A value to wait for is required"}
 
 	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
-	if node == null:
-		return {"type": "error", "message": "Node not found: " + node_path}
 
 	var current: Variant = node.get(property)
 	var wanted: Variant = _values.fitted(params["value"], typeof(current))
@@ -114,6 +120,45 @@ func wait_until(params: Dictionary) -> Dictionary:
 	}
 
 
+## Waits until something under [param node_path] has [param said] written on it.
+##
+## A screen rather than one node, because a panel following a clock builds its labels again every
+## time it redraws and the engine names those `@Label@1163`. A wait holding one of them is waiting
+## on a node that was freed a frame later, and that is what it answered: the date along the top of a
+## hall could not be waited on at all. What a caller is watching for is a word arriving on a screen,
+## and the screen is the part that stays put.
+func _wait_until_said(node_path: String, said: String, timeout_ms: int) -> Dictionary:
+	var started: int = Time.get_ticks_msec()
+	var found: bool = _anything_says(node_path, said)
+	while not found and Time.get_ticks_msec() - started < timeout_ms:
+		await _host.get_tree().process_frame
+		found = _anything_says(node_path, said)
+
+	return {
+		"type": "condition",
+		"path": node_path,
+		"says": said,
+		"met": found,
+		"elapsed_ms": Time.get_ticks_msec() - started,
+	}
+
+
+## Whether anything under [param node_path] says [param said], the node itself included. Hidden
+## nodes count, for the reason a find answers off them: a caller may be waiting for a dialog that
+## is built before it is shown.
+func _anything_says(node_path: String, said: String) -> bool:
+	var root: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if root == null:
+		return false
+	var pending: Array[Node] = [root]
+	while not pending.is_empty():
+		var node: Node = pending.pop_back()
+		if Queries.said_by(node).containsn(said):
+			return true
+		pending.append_array(node.get_children(true))
+	return false
+
+
 func _signal_arity(node: Node, signal_name: String) -> int:
 	for entry: Dictionary in node.get_signal_list():
 		if entry.get("name", "") == signal_name:

package/build/index.js

@@ -28336,6 +28336,11 @@ var TOOL_SPECS = [
         description: 'find: a case-insensitive glob on the node name, such as "Enemy*".'
       },
       group: { type: "string", ops: ["find"], description: "find: a group the node is in." },
+      says: {
+        type: "string",
+        ops: ["find"],
+        description: "find: part of what the node has written on it, case-insensitively, which is how a button is reached by the word on it rather than by a generated path. Its own text, so a row is found by the label in it, and hidden nodes match."
+      },
       limit: {
         type: "number",
         ops: ["find", "text"],
@@ -28361,7 +28366,7 @@ var TOOL_SPECS = [
         requires: []
       },
       find: {
-        summary: "the paths of every node matching className, script, namePattern or group, with property read off each",
+        summary: "the paths of every node matching className, script, namePattern, group or says, with property read off each",
         requires: []
       },
       rect: {
@@ -28427,7 +28432,11 @@ var TOOL_SPECS = [
         ops: ["click", "choose"],
         description: "click: the Control to click, at its centre, or the 3D node to click, where it is drawn. choose: the PopupMenu, or the OptionButton or MenuButton in front of one."
       },
-      action: { type: "string", ops: ["action"], description: "action: the InputMap action name." },
+      action: {
+        type: "string",
+        ops: ["action"],
+        description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with key Escape, or click its button."
+      },
       pressed: {
         type: "boolean",
         ops: ["action", "key", "mouse_click"],
@@ -28510,7 +28519,7 @@ var TOOL_SPECS = [
   },
   {
     name: "runtime_wait",
-    description: "Lets the running game get on with it and answers when something has happened: a number of frames, a signal, or a property reaching a value. Needs the game running with the runtime addon.",
+    description: "Lets the running game get on with it and answers when something has happened: a number of frames, a signal, a property reaching a value, or words appearing on a screen. Needs the game running with the runtime addon.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       frames: {
@@ -28522,6 +28531,11 @@ var TOOL_SPECS = [
       signal: { type: "string", ops: ["signal"], description: "signal: the signal name." },
       property: { type: "string", ops: ["until"], description: "until: the property name." },
       value: { ops: ["until"], description: "until: the value to wait for, fitted to the property's type." },
+      says: {
+        type: "string",
+        ops: ["until"],
+        description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, hidden nodes included."
+      },
       timeoutMs: {
         type: "number",
         ops: ["signal", "until"],
@@ -28536,8 +28550,8 @@ var TOOL_SPECS = [
         requires: ["nodePath", "signal"]
       },
       until: {
-        summary: "wait for a property to read as a value and answer with what it read",
-        requires: ["nodePath", "property", "value"]
+        summary: "wait for a property to read as a value, or for words to appear under a node, and answer with what it found",
+        requires: ["nodePath"]
       }
     }
   },
@@ -30272,6 +30286,7 @@ class GodotServer {
     const script = readNonEmptyString(args, "script");
     const namePattern = readNonEmptyString(args, "namePattern");
     const group = readNonEmptyString(args, "group");
+    const says = readNonEmptyString(args, "says");
     if (className !== undefined)
       filters["class"] = className;
     if (script !== undefined)
@@ -30280,8 +30295,10 @@ class GodotServer {
       filters["name"] = namePattern;
     if (group !== undefined)
       filters["group"] = group;
+    if (says !== undefined)
+      filters["says"] = says;
     if (Object.keys(filters).length === 0) {
-      return this.createErrorResponse("runtime_inspect find needs at least one of className, script, namePattern, group.");
+      return this.createErrorResponse("runtime_inspect find needs at least one of className, script, namePattern, group, says.");
     }
     const property = readNonEmptyString(args, "property");
     return await this.handleRuntimeCommand("find_nodes", {
@@ -30311,6 +30328,7 @@ class GodotServer {
       path: nodePath,
       property: readString(args, "property") ?? "",
       value: args["value"],
+      ...readNonEmptyString(args, "says") === undefined ? {} : { says: readNonEmptyString(args, "says") },
       timeout_ms: timeoutMs
     }, patience);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "mcpName": "io.github.Aureliolo/gdharness",
   "description": "A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.",
   "type": "module",