gdharness 0.8.0 → 0.9.1

package/build/cli.js

@@ -15066,7 +15066,7 @@ function buildToolDefinitions() {
       };
     }
     for (const [name, schema] of Object.entries(spec.parameters)) {
-      const { ops: _ops, ...carried } = schema;
+      const { ops: _ops, blank: _blank, ...carried } = schema;
       properties[name] = carried;
     }
     const required = [...spec.requires];
@@ -15258,7 +15258,8 @@ var init_tool_definitions = __esm(() => {
         projectPath: PROJECT_PATH,
         setting: { type: "string", description: 'Setting path, such as "display/window/size/viewport_width".' },
         value: {
-          description: 'The value to write. Engine types may be tagged, {"_type": "Vector2", "x": 1, "y": 2}.'
+          blank: true,
+          description: 'The value to write. Engine types may be tagged, {"_type": "Vector2", "x": 1, "y": 2}. "" writes an empty string.'
         },
         name: { type: "string", description: "Autoload name." },
         path: { type: "string", description: "Autoload script or scene inside the project." },
@@ -15763,7 +15764,7 @@ var init_tool_definitions = __esm(() => {
         property: {
           type: "string",
           ops: ["property", "find"],
-          description: "property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label."
+          description: 'property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label. Colons read through the objects a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about; a step that is not there is named.'
         },
         depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
         includeProperties: {
@@ -15780,7 +15781,7 @@ var init_tool_definitions = __esm(() => {
         namePattern: {
           type: "string",
           ops: ["find"],
-          description: 'find: a case-insensitive glob on the node name, such as "Enemy*".'
+          description: 'find: a case-insensitive glob on the node name, such as "Enemy*". Matched against the whole name, so a bare word finds only a node called exactly that; an answer of none says how many names contain it and what glob would have found them.'
         },
         group: { type: "string", ops: ["find"], description: "find: a group the node is in." },
         says: {
@@ -15821,7 +15822,7 @@ var init_tool_definitions = __esm(() => {
           requires: ["nodePath"]
         },
         property: {
-          summary: "what one property reads on a node, refusing a property the node does not have",
+          summary: "what one property reads on a node, or through the objects it holds, refusing a name nothing along the way has",
           requires: ["nodePath", "property"]
         },
         metrics: { summary: "frame time, memory, draw calls and the rest", requires: [] }
@@ -15834,8 +15835,16 @@ var init_tool_definitions = __esm(() => {
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
         nodePath: { type: "string", description: 'Absolute node path, such as "/root/Main/Player".' },
-        property: { type: "string", ops: ["set"] },
-        value: { ops: ["set"], description: "set: the value, fitted to the property's type." },
+        property: {
+          type: "string",
+          ops: ["set"],
+          description: 'set: which one to write. Colons write through the objects a node holds, "_game:run:day", and the answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
+        },
+        value: {
+          ops: ["set"],
+          blank: true,
+          description: `set: the value, fitted to the property's type. "" writes an empty string.`
+        },
         method: { type: "string", ops: ["call"] },
         args: {
           type: "array",
@@ -15845,7 +15854,10 @@ var init_tool_definitions = __esm(() => {
       },
       requires: ["nodePath"],
       operations: {
-        set: { summary: "set a property", requires: ["property", "value"] },
+        set: {
+          summary: "set a property, on a node or on an object it holds",
+          requires: ["property", "value"]
+        },
         call: { summary: "call a method and return its result", requires: ["method"] }
       }
     },
@@ -15898,7 +15910,8 @@ var init_tool_definitions = __esm(() => {
         text: {
           type: "string",
           ops: ["text", "choose"],
-          description: "text: what to type. A newline is Enter and a tab is Tab. choose: the item to take, by what it says."
+          blank: true,
+          description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says.'
         },
         replace: {
           type: "boolean",
@@ -15966,7 +15979,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: {
@@ -15978,6 +15991,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"],
@@ -15992,8 +16010,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"]
         }
       }
     },
@@ -36355,7 +36373,11 @@ class GodotServer {
     const required = [...spec.requires, ...op !== null ? spec.operations?.[op]?.requires ?? [] : []];
     const missing = required.filter((field) => {
       const value = Object.hasOwn(args, field) ? args[field] : undefined;
-      return value === undefined || value === null || typeof value === "string" && value.trim() === "";
+      if (value === undefined || value === null) {
+        return true;
+      }
+      const blank = typeof value === "string" && value.trim() === "";
+      return blank && spec.parameters[field]?.blank !== true;
     });
     if (missing.length > 0) {
       const where = op !== null ? `${spec.name} ${op}` : spec.name;
@@ -37542,6 +37564,7 @@ class GodotServer {
       path: nodePath,
       property: readString(args, "property") ?? "",
       value: args["value"],
+      ...readNonEmptyString(args, "says") === undefined ? {} : { says: readNonEmptyString(args, "says") },
       timeout_ms: timeoutMs
     }, patience);
   }
@@ -38920,6 +38943,7 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | 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\` |
+| What a property on an object a node holds reads | the same two, with colons: \`_game:clock:speed\` |
 | 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 |
@@ -38927,7 +38951,7 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | 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_input.gd

@@ -162,8 +162,9 @@ func inject_key(params: Dictionary) -> Dictionary:
 ## back now rather than echoed from the request, so a call that typed somewhere unhelpful says so.
 func inject_text(params: Dictionary) -> Dictionary:
 	var text: String = String(params.get("text", ""))
-	if text.is_empty():
-		return {"type": "error", "message": "text required"}
+	var over: bool = bool(params.get("replace", false))
+	if text.is_empty() and not over:
+		return {"type": "error", "message": "text needs something to type, or replace to empty a field"}
 
 	var viewport: Viewport = _host.get_tree().root
 	var focused: Control = viewport.gui_get_focus_owner()
@@ -171,14 +172,13 @@ func inject_text(params: Dictionary) -> Dictionary:
 	if not shut.is_empty():
 		return {"type": "error", "message": shut}
 
-	var replaced: bool = bool(params.get("replace", false)) and _select_everything(focused)
+	var replaced: bool = over and _select_everything(focused)
+	# Emptying a field is a real thing to ask for and the one shape of filling one in that types no
+	# characters. The selection is standing, so the key a player presses over one is what clears it.
+	if replaced and text.is_empty():
+		_press(viewport, _held_down(KEY_DELETE))
 	for index: int in text.length():
-		var down: InputEventKey = _typed(text.unicode_at(index))
-		viewport.push_input(down)
-		# The release as well, so nothing is left held down behind the caller.
-		var up: InputEventKey = down.duplicate()
-		up.pressed = false
-		viewport.push_input(up)
+		_press(viewport, _typed(text.unicode_at(index)))
 
 	# Where it went, which is the one thing a caller cannot see from here. Null is a game reading
 	# keys for itself with nothing focused, which is a real thing to be typing at.
@@ -253,6 +253,24 @@ static func _shut_to_typing(focused: Control) -> String:
 
 
 ## The key press that produces [param glyph], as a keyboard would send it.
+## A whole press: down, then the release, so nothing is left held down behind the caller.
+static func _press(viewport: Viewport, down: InputEventKey) -> void:
+	viewport.push_input(down)
+	var up: InputEventKey = down.duplicate()
+	up.pressed = false
+	viewport.push_input(up)
+
+
+## A key held down by its keycode, for the ones that stand for an edit rather than a character.
+static func _held_down(code: Key) -> InputEventKey:
+	var event: InputEventKey = InputEventKey.new()
+	event.pressed = true
+	event.keycode = code
+	event.physical_keycode = code
+	event.key_label = code
+	return event
+
+
 func _typed(glyph: int) -> InputEventKey:
 	var event: InputEventKey = InputEventKey.new()
 	event.pressed = true

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

@@ -71,13 +71,20 @@ func find_nodes(params: Dictionary) -> Dictionary:
 	var found: Array[Dictionary] = []
 	var pending: Array[Node] = [root]
 	var truncated: bool = false
+	# Counted while the tree is already being walked, for the answer below: how many nodes this
+	# find would have matched if the name had been read the way it was probably meant.
+	var literal: bool = _is_literal(wanted["name"])
+	var nearly: int = 0
 	while not pending.is_empty():
 		var node: Node = pending.pop_front()
-		if _matches(node, wanted):
+		var rest: bool = _matches_apart_from_name(node, wanted)
+		if rest and _named(node, wanted["name"]):
 			if found.size() >= limit:
 				truncated = true
 				break
 			found.append(_found(node, wanted_property))
+		elif rest and literal and str(node.name).containsn(wanted["name"]):
+			nearly += 1
 		# Internal children included, which they were not. A ConfirmationDialog builds its Yes and
 		# its No as internal nodes, and a ScrollContainer its bars, so a find over a screen for
 		# every Button came back without the two buttons the player is being asked to press:
@@ -88,7 +95,17 @@ func find_nodes(params: Dictionary) -> Dictionary:
 		for index: int in range(children.size() - 1, -1, -1):
 			pending.push_front(children[index])
 
-	return {"type": "nodes", "count": found.size(), "truncated": truncated, "nodes": found}
+	var answer: Dictionary = {"type": "nodes", "count": found.size(), "truncated": truncated, "nodes": found}
+	# Nothing found is the one answer that cannot be told apart from having asked the wrong
+	# question, and a name written without a wildcard is the way an agent writes "contains".
+	# Said only when it changes the answer, so a genuine nothing stays a plain nothing.
+	if found.is_empty() and nearly > 0:
+		var holding: String = "names contain" if nearly > 1 else "name contains"
+		answer["note"] = (
+			'name is matched as a glob against the whole name; %d node %s "%s", which "*%s*" would find'
+			% [nearly, holding, wanted["name"], wanted["name"]]
+		)
+	return answer
 
 
 ## One match, with the named property on it when one was named.
@@ -102,15 +119,20 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	var entry: Dictionary = _serialize_node(node, false)
 	if wanted_property.is_empty():
 		return entry
-	var has: bool = false
-	for prop: Dictionary in node.get_property_list():
-		if str(prop["name"]) == wanted_property:
-			has = true
-			break
 	entry["property"] = wanted_property
+	# Through a path as well, for the reason [method _reached] gives. A step that is not there on
+	# this node reads as not having the property rather than as a refusal, which is the rule this
+	# whole function is written to: a find matches nodes of several classes on purpose.
+	var reached: Dictionary = _reached(node, str(entry["path"]), wanted_property)
+	if reached.has("message"):
+		entry["has_property"] = false
+		return entry
+	var holder: Object = reached["holder"]
+	var named: String = reached["property"]
+	var has: bool = _has_property(holder, named)
 	entry["has_property"] = has
 	if has:
-		entry["value"] = _values.serialize(node.get(wanted_property))
+		entry["value"] = _values.serialize(holder.get(named))
 	return entry
 
 
@@ -123,15 +145,28 @@ static func _anything_asked(wanted: Dictionary[String, String]) -> bool:
 	return false
 
 
-func _matches(node: Node, wanted: Dictionary[String, String]) -> bool:
+## Whether [param node] carries the name a find asked for. Empty matches everything, which is what
+## makes leaving a filter out the same as not having one.
+static func _named(node: Node, pattern: String) -> bool:
+	return pattern.is_empty() or str(node.name).matchn(pattern)
+
+
+## Whether [param pattern] is a name written as a whole word rather than as a glob, which is how a
+## caller writes one when they mean "contains". [method String.matchn] answers nothing to it, and
+## nothing is also what a name that is simply not there answers.
+static func _is_literal(pattern: String) -> bool:
+	return not pattern.is_empty() and not pattern.contains("*") and not pattern.contains("?")
+
+
+## Every filter but the name, so a find that came back empty can say how many nodes the name was
+## the only thing standing between it and.
+func _matches_apart_from_name(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"]):
-		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"]):
+	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():
@@ -206,7 +241,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):
@@ -224,7 +259,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()
@@ -391,24 +430,63 @@ func get_property(params: Dictionary) -> Dictionary:
 	if node == null:
 		return {"type": "error", "message": "Node not found: " + node_path}
 
+	var reached: Dictionary = _reached(node, node_path, property)
+	if reached.has("message"):
+		return reached
+
+	var holder: Object = reached["holder"]
+	var named: String = reached["property"]
 	# Asked of the property list rather than read and compared to null, because a property the
-	# node does not have and a property that is null both read as null.
-	var known: bool = false
-	for entry: Dictionary in node.get_property_list():
-		if str(entry["name"]) == property:
-			known = true
-			break
-	if not known:
-		return {"type": "error", "message": "%s has no property %s" % [node_path, property]}
+	# holder does not have and a property that is null both read as null.
+	if not _has_property(holder, named):
+		return {"type": "error", "message": "%s has no property %s" % [reached["called"], named]}
 
 	return {
 		"type": "property",
 		"path": node_path,
 		"property": property,
-		"value": _values.serialize(node.get(property)),
+		"value": _values.serialize(holder.get(named)),
 	}
 
 
+## What [param property] is a property of, which is the node itself until the name has a colon in
+## it, and the last name along that path.
+##
+## A game's state does not sit on nodes, it hangs off them: the speed of the clock is a property of
+## a [RefCounted] held by a [RefCounted] held by the root, and that is what an agent asks about.
+## Colons, because that is the separator [method Object.get_indexed] already takes. Walked a step
+## at a time rather than handed to that method, which answers null for a path that goes wrong
+## halfway along and for one that ends on null.
+##
+## Answers with a `message` instead when a step along the way is not there or holds something that
+## is not an object, naming the step rather than the whole path: "/root/Main:_game has no property
+## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
+func _reached(node: Node, node_path: String, property: String) -> Dictionary:
+	var parts: PackedStringArray = property.split(":")
+	var holder: Object = node
+	var called: String = node_path
+	for step: int in parts.size() - 1:
+		var named: String = parts[step]
+		if not _has_property(holder, named):
+			return {"type": "error", "message": "%s has no property %s" % [called, named]}
+		var next: Variant = holder.get(named)
+		called = "%s:%s" % [called, named]
+		if not next is Object:
+			var wanted: String = parts[step + 1]
+			return {"type": "error", "message": "%s holds no object to read %s off" % [called, wanted]}
+		holder = next
+	return {"holder": holder, "property": parts[parts.size() - 1], "called": called}
+
+
+## Whether [param holder] declares [param named]. Its own function because three ops ask it and a
+## property read back as null answers it wrongly.
+static func _has_property(holder: Object, named: String) -> bool:
+	for entry: Dictionary in holder.get_property_list():
+		if str(entry["name"]) == named:
+			return true
+	return false
+
+
 func set_property(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var property: String = str(params.get("property", ""))
@@ -421,15 +499,24 @@ func set_property(params: Dictionary) -> Dictionary:
 	if node == null:
 		return {"type": "error", "message": "Node not found: " + node_path}
 
-	var old_value: Variant = node.get(property)
-	node.set(property, _values.fitted(value, typeof(old_value)))
+	# Through a path as well, for the reason [method _reached] gives, and read back off the same
+	# holder afterwards: a set that does not take says so by answering with the old value, which is
+	# how a typed container refusing a write is told from one accepting it.
+	var reached: Dictionary = _reached(node, node_path, property)
+	if reached.has("message"):
+		return reached
+
+	var holder: Object = reached["holder"]
+	var named: String = reached["property"]
+	var old_value: Variant = holder.get(named)
+	holder.set(named, _values.fitted(value, typeof(old_value)))
 
 	return {
 		"type": "property_set",
 		"path": node_path,
 		"property": property,
 		"old_value": _values.serialize(old_value),
-		"new_value": _values.serialize(node.get(property))
+		"new_value": _values.serialize(holder.get(named))
 	}
 
 

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

@@ -27811,7 +27811,8 @@ var TOOL_SPECS = [
       projectPath: PROJECT_PATH,
       setting: { type: "string", description: 'Setting path, such as "display/window/size/viewport_width".' },
       value: {
-        description: 'The value to write. Engine types may be tagged, {"_type": "Vector2", "x": 1, "y": 2}.'
+        blank: true,
+        description: 'The value to write. Engine types may be tagged, {"_type": "Vector2", "x": 1, "y": 2}. "" writes an empty string.'
       },
       name: { type: "string", description: "Autoload name." },
       path: { type: "string", description: "Autoload script or scene inside the project." },
@@ -28316,7 +28317,7 @@ var TOOL_SPECS = [
       property: {
         type: "string",
         ops: ["property", "find"],
-        description: "property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label."
+        description: 'property: which one to read. find: read this one off every node matched, so a panel of labels is one call rather than one per label. Colons read through the objects a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about; a step that is not there is named.'
       },
       depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
       includeProperties: {
@@ -28333,7 +28334,7 @@ var TOOL_SPECS = [
       namePattern: {
         type: "string",
         ops: ["find"],
-        description: 'find: a case-insensitive glob on the node name, such as "Enemy*".'
+        description: 'find: a case-insensitive glob on the node name, such as "Enemy*". Matched against the whole name, so a bare word finds only a node called exactly that; an answer of none says how many names contain it and what glob would have found them.'
       },
       group: { type: "string", ops: ["find"], description: "find: a group the node is in." },
       says: {
@@ -28374,7 +28375,7 @@ var TOOL_SPECS = [
         requires: ["nodePath"]
       },
       property: {
-        summary: "what one property reads on a node, refusing a property the node does not have",
+        summary: "what one property reads on a node, or through the objects it holds, refusing a name nothing along the way has",
         requires: ["nodePath", "property"]
       },
       metrics: { summary: "frame time, memory, draw calls and the rest", requires: [] }
@@ -28387,8 +28388,16 @@ var TOOL_SPECS = [
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       nodePath: { type: "string", description: 'Absolute node path, such as "/root/Main/Player".' },
-      property: { type: "string", ops: ["set"] },
-      value: { ops: ["set"], description: "set: the value, fitted to the property's type." },
+      property: {
+        type: "string",
+        ops: ["set"],
+        description: 'set: which one to write. Colons write through the objects a node holds, "_game:run:day", and the answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
+      },
+      value: {
+        ops: ["set"],
+        blank: true,
+        description: `set: the value, fitted to the property's type. "" writes an empty string.`
+      },
       method: { type: "string", ops: ["call"] },
       args: {
         type: "array",
@@ -28398,7 +28407,10 @@ var TOOL_SPECS = [
     },
     requires: ["nodePath"],
     operations: {
-      set: { summary: "set a property", requires: ["property", "value"] },
+      set: {
+        summary: "set a property, on a node or on an object it holds",
+        requires: ["property", "value"]
+      },
       call: { summary: "call a method and return its result", requires: ["method"] }
     }
   },
@@ -28451,7 +28463,8 @@ var TOOL_SPECS = [
       text: {
         type: "string",
         ops: ["text", "choose"],
-        description: "text: what to type. A newline is Enter and a tab is Tab. choose: the item to take, by what it says."
+        blank: true,
+        description: 'text: what to type. A newline is Enter and a tab is Tab, a space is a space, and "" with replace empties the field. choose: the item to take, by what it says.'
       },
       replace: {
         type: "boolean",
@@ -28519,7 +28532,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: {
@@ -28531,6 +28544,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"],
@@ -28545,8 +28563,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"]
       }
     }
   },
@@ -28620,7 +28638,7 @@ function buildToolDefinitions() {
       };
     }
     for (const [name, schema] of Object.entries(spec.parameters)) {
-      const { ops: _ops, ...carried } = schema;
+      const { ops: _ops, blank: _blank, ...carried } = schema;
       properties[name] = carried;
     }
     const required = [...spec.requires];
@@ -29136,7 +29154,11 @@ class GodotServer {
     const required = [...spec.requires, ...op !== null ? spec.operations?.[op]?.requires ?? [] : []];
     const missing = required.filter((field) => {
       const value = Object.hasOwn(args, field) ? args[field] : undefined;
-      return value === undefined || value === null || typeof value === "string" && value.trim() === "";
+      if (value === undefined || value === null) {
+        return true;
+      }
+      const blank = typeof value === "string" && value.trim() === "";
+      return blank && spec.parameters[field]?.blank !== true;
     });
     if (missing.length > 0) {
       const where = op !== null ? `${spec.name} ${op}` : spec.name;
@@ -30323,6 +30345,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.8.0",
+  "version": "0.9.1",
   "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",