gdharness 0.11.0 → 0.12.0

package/README.md

@@ -61,6 +61,29 @@ parts connect, and every tool, op and argument.
 [SECURITY.md](.github/SECURITY.md) is how to report something.
 [CONTRIBUTING.md](.github/CONTRIBUTING.md) is what a change has to clear.
 
+## Versions
+
+0.x, and the number is telling the truth: the tools, their arguments and the shape of their
+answers are still moving, because the projects using this keep finding answers that were wrong or
+missing. Pin an exact version and upgrade deliberately.
+
+Built and measured against Godot 4.7.2 on Windows, Linux and macOS. The editor, engine, runtime
+and integration suites run against a real engine on all three before anything is tagged. Older
+4.x is likely to work and is not tested.
+
+What each kind of release means here:
+
+- **Patch**: an answer that was wrong is now right. The output can change, because a wrong answer
+  corrected is a fix rather than a feature, and leaving one wrong to protect whoever parsed it is
+  how a tool stops being worth asking.
+- **Minor**: a tool, an op, an argument or a field was added, or behaviour a caller can see
+  changed.
+- **Major**: a tool, an op, an argument or a field was renamed or taken away. Nothing else earns
+  one.
+
+1.0 is not a date, it is a condition: the tool surface holding still for a fortnight, and the
+issues arriving being things it cannot do yet rather than things it answers wrongly.
+
 ## Project
 
 Fork of [GoPeak](https://github.com/HaD0Yun/Doyunha-Gopeak) v2.3.9, September 2026, MIT: the

package/build/cli.js

@@ -15725,8 +15725,14 @@ var init_tool_definitions = __esm(() => {
           type: "boolean",
           description: "Only entries printed since the previous editor_output. Default false."
         },
-        contains: { type: "string", description: "Only entries mentioning this text." },
-        limit: { type: "number", description: "The most entries to answer with, newest kept. Default 200." }
+        contains: {
+          type: "string",
+          description: "Only entries mentioning this text, matched against everything the run has printed rather than against the entries this answer would otherwise carry: a line is found however much was printed after it."
+        },
+        limit: {
+          type: "number",
+          description: "The most entries to answer with, newest kept. Default 200, and omitted says how many matching entries that left out. A run long enough to pass it needs this raised, not just filtered: filtering narrows what counts as matching, and the newest of those is still all one answer carries."
+        }
       },
       requires: []
     },
@@ -15793,7 +15799,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. 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.'
+          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 what a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about. A number or a key steps into a list or a map, "_game:run:roster:0:traits", which is how the lists a game keeps its state in are walked: a roster, a board, an in-tray. A negative number counts from the end. A step that is not there is named, and says what was there instead.'
         },
         depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
         includeProperties: {
@@ -15867,7 +15873,7 @@ var init_tool_definitions = __esm(() => {
         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.'
+          description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end. The answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
         },
         value: {
           ops: ["set"],
@@ -15877,7 +15883,7 @@ var init_tool_definitions = __esm(() => {
         method: {
           type: "string",
           ops: ["call"],
-          description: 'call: which one to call. Colons call through the objects a node holds, "_game:run:advance", the same way a property is written through them.'
+          description: 'call: which one to call. Colons call through what a node holds, "_game:run:advance", the same way a property is written through them, and a list or a map is stepped into by index or key, "_game:run:roster:0:retire".'
         },
         args: {
           type: "array",
@@ -36097,6 +36103,9 @@ function runsDirectory() {
 function recordPath() {
   return join14(runsDirectory(), "run.json");
 }
+function recordPaths() {
+  return runtimeDirectories().map((directory) => join14(directory, "runs", "run.json"));
+}
 function openTranscript(startedAt) {
   mkdirSync6(runsDirectory(), { recursive: true });
   const path = join14(runsDirectory(), `run-${startedAt}.log`);
@@ -36107,9 +36116,18 @@ function writeRunRecord(record) {
   writeFileSync8(recordPath(), JSON.stringify(record, null, 2), "utf8");
 }
 function readRunRecord() {
+  for (const path of recordPaths()) {
+    const record = recordAt(path);
+    if (record !== null) {
+      return record;
+    }
+  }
+  return null;
+}
+function recordAt(path) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync12(recordPath(), "utf8"));
+    parsed = JSON.parse(readFileSync12(path, "utf8"));
   } catch {
     return null;
   }
@@ -36132,10 +36150,16 @@ function readRunRecord() {
     arguments: Array.isArray(args) ? args.filter((value) => typeof value === "string") : []
   };
 }
-function clearRunRecord() {
-  try {
-    rmSync7(recordPath());
-  } catch {}
+function clearRunRecord(ours = () => true) {
+  for (const path of recordPaths()) {
+    const record = recordAt(path);
+    if (record === null || !ours(record)) {
+      continue;
+    }
+    try {
+      rmSync7(path);
+    } catch {}
+  }
 }
 function ageMs(path, now) {
   try {
@@ -37764,7 +37788,7 @@ class GodotServer {
   async endActiveGame() {
     const running = this.activeProcess;
     this.activeProcess = null;
-    clearRunRecord();
+    clearRunRecord((record) => this.couldBeOurs(record.projectPath));
     if (!running) {
       return;
     }

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

@@ -172,12 +172,12 @@ func _found(node: Node, wanted_property: String) -> Dictionary:
 	if reached.has("message"):
 		entry["has_property"] = false
 		return entry
-	var holder: Object = reached["holder"]
+	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	var has: bool = _has_property(holder, named)
+	var has: bool = _can_read(holder, named)
 	entry["has_property"] = has
 	if has:
-		entry["value"] = _values.serialize(holder.get(named))
+		entry["value"] = _values.serialize(_read(holder, named))
 	return entry
 
 
@@ -500,18 +500,18 @@ func get_property(params: Dictionary) -> Dictionary:
 	if reached.has("message"):
 		return reached
 
-	var holder: Object = reached["holder"]
+	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	# Asked of the property list rather than read and compared to null, because a property the
-	# 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]}
+	# Asked of the holder rather than read and compared to null, because a property the holder does
+	# not have and a property that is null both read as null.
+	if not _can_read(holder, named):
+		return {"type": "error", "message": _nothing_there(holder, named, str(reached["called"]))}
 
 	return {
 		"type": "property",
 		"path": node_path,
 		"property": property,
-		"value": _values.serialize(holder.get(named)),
+		"value": _values.serialize(_read(holder, named)),
 	}
 
 
@@ -532,21 +532,115 @@ func get_property(params: Dictionary) -> Dictionary:
 ## clocks" is a typo found, and "no property _game:clocks:speed" is a puzzle.
 func _reached(node: Node, node_path: String, reaching: String) -> Dictionary:
 	var parts: PackedStringArray = reaching.split(":")
-	var holder: Object = node
+	var holder: Variant = 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)
+		if not _can_read(holder, named):
+			return {"type": "error", "message": _nothing_there(holder, named, called)}
+		holder = _read(holder, named)
 		called = "%s:%s" % [called, named]
-		if not next is Object:
+		if not _can_hold(holder):
 			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, "name": parts[parts.size() - 1], "called": called}
 
 
+## Whether a step can be taken into [param value] at all: an object, a list or a map can be walked
+## into, and a number or a string is where a path ends whether the caller meant it to or not.
+static func _can_hold(value: Variant) -> bool:
+	return value is Object or value is Array or value is Dictionary
+
+
+## Whether [param named] is something [param holder] has.
+##
+## Three kinds of holder, because the state a game keeps is not all properties of objects: a roster
+## is a list and an in-tray is a map, and a path that could not step into either stopped at the
+## first one. An index reads the way a property does, and a negative one counts from the end the
+## way GDScript's own does, so reading the last of something does not mean asking how many first.
+static func _can_read(holder: Variant, named: String) -> bool:
+	if holder is Array:
+		var items: Array = holder
+		return _index_in(named, items.size()) != -1
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		return map.has(named) or map.has(StringName(named))
+	if holder is Object:
+		return _has_property(holder, named)
+	return false
+
+
+## Put [param value] where [param named] points. Only ever called once [method _can_read] agrees,
+## and lists and maps are reference types, so writing into one reaches the game's own copy.
+static func _write(holder: Variant, named: String, value: Variant) -> void:
+	if holder is Array:
+		var items: Array = holder
+		items[_index_in(named, items.size())] = value
+		return
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		# Written back under the key it was found under, since a map keyed by StringName and one
+		# keyed by String both read the same way and a write to the wrong one adds a second entry.
+		if map.has(named):
+			map[named] = value
+		else:
+			map[StringName(named)] = value
+		return
+	var object: Object = holder
+	object.set(named, value)
+
+
+## What [param holder] holds under [param named]. Only ever called once [method _can_read] agrees.
+static func _read(holder: Variant, named: String) -> Variant:
+	if holder is Array:
+		var items: Array = holder
+		return items[_index_in(named, items.size())]
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		if map.has(named):
+			return map[named]
+		return map[StringName(named)]
+	var object: Object = holder
+	return object.get(named)
+
+
+## Where [param named] lands in a list of [param size], or -1 for a step that is not in it.
+##
+## -1 for "nowhere" is safe because every answer this gives is an index into a list that long, so a
+## real one is never negative by the time it is returned.
+static func _index_in(named: String, size: int) -> int:
+	if not named.is_valid_int():
+		return -1
+	var index: int = int(named)
+	if index < 0:
+		index += size
+	return index if index >= 0 and index < size else -1
+
+
+## Why a step could not be taken, said in the terms of what was actually there.
+##
+## "has no property 0" about a list is a true sentence that sends somebody looking for a property,
+## so a list says how long it is and a map says what it is keyed by. The step is named rather than
+## the whole path, because the step is the typo.
+static func _nothing_there(holder: Variant, named: String, called: String) -> String:
+	if holder is Array:
+		var items: Array = holder
+		return "%s is a list of %d, so there is no %s in it" % [called, items.size(), named]
+	if holder is Dictionary:
+		var map: Dictionary = holder
+		var keys: Array = map.keys()
+		# Eight of them, because a map keyed by something unexpected is told by the first few and a
+		# map of two hundred would bury the sentence saying which key was missing.
+		var some: PackedStringArray = []
+		for key: Variant in keys.slice(0, 8):
+			some.append(str(key))
+		var rest: String = ""
+		if keys.size() > 8:
+			rest = " and %d more" % [keys.size() - 8]
+		return "%s has no key %s; it is keyed by %s%s" % [called, named, ", ".join(some), rest]
+	return "%s has no property %s" % [called, named]
+
+
 ## 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:
@@ -576,17 +670,19 @@ func set_property(params: Dictionary) -> Dictionary:
 	if reached.has("message"):
 		return reached
 
-	var holder: Object = reached["holder"]
+	var holder: Variant = reached["holder"]
 	var named: String = reached["name"]
-	var old_value: Variant = holder.get(named)
-	holder.set(named, _values.fitted(value, typeof(old_value)))
+	if not _can_read(holder, named):
+		return {"type": "error", "message": _nothing_there(holder, named, str(reached["called"]))}
+	var old_value: Variant = _read(holder, named)
+	_write(holder, 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(holder.get(named))
+		"new_value": _values.serialize(_read(holder, named))
 	}
 
 
@@ -610,6 +706,19 @@ func call_method(params: Dictionary) -> Dictionary:
 	if reached.has("message"):
 		return reached
 
+	# A list or a map can be stepped through on the way, and is not a thing with methods when the
+	# path stops on one: said in those terms rather than as "has no method", which reads as a
+	# misspelling of a method that was never going to be there.
+	if not reached["holder"] is Object:
+		var sort: String = "a list" if reached["holder"] is Array else "a map"
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s is %s, which has no methods: name the element to call it on, as in %s:0:%s"
+				% [reached["called"], sort, reached["called"], reached["name"]]
+			)
+		}
 	var holder: Object = reached["holder"]
 	var named: String = reached["name"]
 	if not holder.has_method(named):

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

@@ -136,7 +136,36 @@ func _serialize_object(value: Object) -> Dictionary:
 		var node: Node = value
 		if node.is_inside_tree():
 			return {"_type": "Node", "class": node.get_class(), "path": str(node.get_path())}
-	return {"_type": "Object", "class": value.get_class()}
+	return _describe_object(value)
+
+
+## A plain object, said in enough detail to tell it from the one beside it.
+##
+## `{"class": "RefCounted"}` was all of it, so a roster of twelve people came back as the word
+## RefCounted twelve times: correct, useless, and indistinguishable from a list of twelve of
+## anything else. The state worth looking at in a game is lists of these, so each one carries what
+## it is (the `class_name` its script declares, or the script's path when it has no name), what it
+## says about itself when the game has given it a `_to_string`, and an id that is at least
+## different per object. None of it is invented: every field is left out when there is nothing to
+## put in it, because a key holding "" is a worse answer than a key that is not there.
+func _describe_object(value: Object) -> Dictionary:
+	var described: Dictionary = {"_type": "Object", "class": value.get_class()}
+	# Asked as a Variant and narrowed, because get_script answers one and an object without a
+	# script answers null: casting that to Script is the unsafe cast the engine refuses to compile.
+	var attached: Variant = value.get_script()
+	if attached is Script:
+		var script: Script = attached
+		var declared: String = String(script.get_global_name())
+		if not declared.is_empty():
+			described["script_class"] = declared
+		elif not script.resource_path.is_empty():
+			described["script"] = script.resource_path
+	# Only when the game wrote one. The default is "<RefCounted#31098236>", which is the id again
+	# in a costume and reads as if the object had been asked and had nothing to say.
+	if value.has_method("_to_string"):
+		described["says"] = value.to_string()
+	described["id"] = value.get_instance_id()
+	return described
 
 
 ## Rebuilds a Godot value from the shape serialize gave it.

package/build/index.js

@@ -27798,6 +27798,9 @@ function runsDirectory() {
 function recordPath() {
   return join8(runsDirectory(), "run.json");
 }
+function recordPaths() {
+  return runtimeDirectories().map((directory) => join8(directory, "runs", "run.json"));
+}
 function openTranscript(startedAt) {
   mkdirSync3(runsDirectory(), { recursive: true });
   const path = join8(runsDirectory(), `run-${startedAt}.log`);
@@ -27808,9 +27811,18 @@ function writeRunRecord(record) {
   writeFileSync4(recordPath(), JSON.stringify(record, null, 2), "utf8");
 }
 function readRunRecord() {
+  for (const path of recordPaths()) {
+    const record = recordAt(path);
+    if (record !== null) {
+      return record;
+    }
+  }
+  return null;
+}
+function recordAt(path) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync8(recordPath(), "utf8"));
+    parsed = JSON.parse(readFileSync8(path, "utf8"));
   } catch {
     return null;
   }
@@ -27833,10 +27845,16 @@ function readRunRecord() {
     arguments: Array.isArray(args) ? args.filter((value) => typeof value === "string") : []
   };
 }
-function clearRunRecord() {
-  try {
-    rmSync3(recordPath());
-  } catch {}
+function clearRunRecord(ours = () => true) {
+  for (const path of recordPaths()) {
+    const record = recordAt(path);
+    if (record === null || !ours(record)) {
+      continue;
+    }
+    try {
+      rmSync3(path);
+    } catch {}
+  }
 }
 function ageMs(path, now) {
   try {
@@ -28511,8 +28529,14 @@ var TOOL_SPECS = [
         type: "boolean",
         description: "Only entries printed since the previous editor_output. Default false."
       },
-      contains: { type: "string", description: "Only entries mentioning this text." },
-      limit: { type: "number", description: "The most entries to answer with, newest kept. Default 200." }
+      contains: {
+        type: "string",
+        description: "Only entries mentioning this text, matched against everything the run has printed rather than against the entries this answer would otherwise carry: a line is found however much was printed after it."
+      },
+      limit: {
+        type: "number",
+        description: "The most entries to answer with, newest kept. Default 200, and omitted says how many matching entries that left out. A run long enough to pass it needs this raised, not just filtered: filtering narrows what counts as matching, and the newest of those is still all one answer carries."
+      }
     },
     requires: []
   },
@@ -28579,7 +28603,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. 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.'
+        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 what a node holds, "_game:clock:speed", which is where a game keeps what is worth asking about. A number or a key steps into a list or a map, "_game:run:roster:0:traits", which is how the lists a game keeps its state in are walked: a roster, a board, an in-tray. A negative number counts from the end. A step that is not there is named, and says what was there instead.'
       },
       depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
       includeProperties: {
@@ -28653,7 +28677,7 @@ var TOOL_SPECS = [
       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.'
+        description: 'set: which one to write. Colons write through what a node holds, "_game:run:day", and a number or a key steps into a list or a map on the way, "_game:run:roster:0:name", a negative number counting from the end. The answer reads back off the same holder, so a write a typed container refused shows as an unchanged value.'
       },
       value: {
         ops: ["set"],
@@ -28663,7 +28687,7 @@ var TOOL_SPECS = [
       method: {
         type: "string",
         ops: ["call"],
-        description: 'call: which one to call. Colons call through the objects a node holds, "_game:run:advance", the same way a property is written through them.'
+        description: 'call: which one to call. Colons call through what a node holds, "_game:run:advance", the same way a property is written through them, and a list or a map is stepped into by index or key, "_game:run:roster:0:retire".'
       },
       args: {
         type: "array",
@@ -30546,7 +30570,7 @@ class GodotServer {
   async endActiveGame() {
     const running = this.activeProcess;
     this.activeProcess = null;
-    clearRunRecord();
+    clearRunRecord((record) => this.couldBeOurs(record.projectPath));
     if (!running) {
       return;
     }

package/package.json

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