gdharness 0.9.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",
@@ -36360,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;
@@ -38926,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 |

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,11 +145,24 @@ 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.
@@ -395,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", ""))
@@ -425,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/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",
@@ -28625,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];
@@ -29141,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdharness",
-  "version": "0.9.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",