gdharness 0.13.44 → 1.0.1

package/README.md

@@ -26,9 +26,8 @@ property reads right now, what the console printed, what broke and on which line
 Hand this to your agent:
 
 ```text
-Install gdharness into this project by following
-https://aureliolo.github.io/gdharness/agent.md, then tell me what it asked you to
-recommend back to me.
+Install gdharness here by following https://aureliolo.github.io/gdharness/agent.md,
+then tell me what it asked you to recommend back to me.
 ```
 
 Or do it yourself, and pick your harness:
@@ -53,16 +52,16 @@ emptily, so a call that succeeded is a call that was understood.
 
 ## At a glance
 
-|           |                                                                                  |
-| --------- | -------------------------------------------------------------------------------- |
-| Needs     | Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.                    |
-| Surface   | 30 tools named `domain_verb`, and 4 `godot://` resources                         |
-| Reaches   | The editor that is open, a game it is playing, and the project on disk           |
-| Harnesses | 35, written inside the project wherever the harness has a project config         |
-| Skill     | Written to `.agents/skills`, which every major harness reads                     |
-| Install   | npm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3               |
-| Proven    | Every tool driven against Godot 4.7.2 in CI, on Windows, Linux and macOS         |
-| Status    | 0.x: pin an exact version. [What a bump means](.github/CONTRIBUTING.md#versions) |
+|           |                                                                                      |
+| --------- | ------------------------------------------------------------------------------------ |
+| Needs     | Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.                        |
+| Surface   | 30 tools named `domain_verb`, and 4 `godot://` resources                             |
+| Reaches   | The editor that is open, a game it is playing, and the project on disk               |
+| Harnesses | 35, written inside the project wherever the harness has a project config             |
+| Skill     | Written to `.agents/skills`, which every major harness reads                         |
+| Install   | npm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3                   |
+| Proven    | Every tool driven against Godot 4.7.2 in CI, on Windows, Linux and macOS             |
+| Status    | 1.0: every release is a patch. [What a bump means](.github/CONTRIBUTING.md#versions) |
 
 Older 4.x is likely to work and is not tested.
 

package/build/cli.js

@@ -15319,10 +15319,22 @@ function opTakes(spec, op, name) {
 function argumentsOf(spec, op) {
   return Object.keys(spec.parameters).filter((name) => opTakes(spec, op, name));
 }
-function toolsWithoutProjectPath() {
-  return TOOL_SPECS.filter((spec) => !Object.hasOwn(spec.parameters, "projectPath")).map((spec) => spec.name).sort();
+function callsWithoutProjectPath() {
+  const calls = [];
+  for (const spec of TOOL_SPECS) {
+    if (!Object.hasOwn(spec.parameters, "projectPath")) {
+      calls.push(spec.name);
+      continue;
+    }
+    for (const op of Object.keys(spec.operations ?? {})) {
+      if (!opTakes(spec, op, "projectPath")) {
+        calls.push(`${spec.name} ${op}`);
+      }
+    }
+  }
+  return calls.sort();
 }
-function projectPathSentence(without = toolsWithoutProjectPath()) {
+function projectPathSentence(without = callsWithoutProjectPath()) {
   if (without.length === 0) {
     return "Every call takes `projectPath`";
   }
@@ -16327,12 +16339,12 @@ var init_tool_definitions = __esm(() => {
         relativeX: {
           type: "number",
           ops: ["mouse_motion"],
-          description: "mouse_motion: movement since the last event."
+          description: "mouse_motion: the movement the event carries. Left out, it is the distance from where the pointer last was, which is what a control that drags reads; give it to send a motion the position does not show."
         },
         relativeY: {
           type: "number",
           ops: ["mouse_motion"],
-          description: "mouse_motion: movement since the last event."
+          description: "mouse_motion: as relativeX."
         }
       },
       requires: [],
@@ -16346,13 +16358,22 @@ var init_tool_definitions = __esm(() => {
           requires: ["nodePath"]
         },
         action: { summary: "press an action, or hold it", requires: ["action"] },
-        key: { summary: "press a key, or hold it", requires: ["keycode"] },
+        key: {
+          summary: "press a key, or hold it. Not for a menu a click has opened: an OptionButton or PopupMenu pops up as a window of its own that a key sent to the game never reaches, so an arrow moves nothing in it and Enter closes it with nothing chosen. choose is what selects there",
+          requires: ["keycode"]
+        },
         text: {
           summary: "type a string into the field being edited, a character at a time, and say what it landed in",
           requires: ["text"]
         },
-        mouse_click: { summary: "one mouse button event at a position", requires: ["x", "y"] },
-        mouse_motion: { summary: "move the mouse to a position", requires: ["x", "y"] }
+        mouse_click: {
+          summary: "one mouse button event at a position, carrying the buttons held once it has happened. A drag is a press held with pressed true, motions, and a release with pressed false",
+          requires: ["x", "y"]
+        },
+        mouse_motion: {
+          summary: "move the mouse to a position, carrying the distance from where it last was unless relativeX and relativeY say otherwise, and the buttons held, so a control that drags moves under a run of these between a held mouse_click and its release",
+          requires: ["x", "y"]
+        }
       }
     },
     {
@@ -42068,7 +42089,7 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | Press the next thing after a click that changed screen | \`runtime_wait until\` with \`says\` and a word the new screen shows, then the click. A click sent straight after a screen change lands on a control the new screen is about to free, answers \`landed: true\`, and does nothing; a frame count is a number nobody can pick correctly across a cold start and a warm one, and waiting for the words answered in about 130ms where twenty frames had not been enough |
 | 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 |
+| Pick something out of a dropdown | \`runtime_input choose\` on it, by what the item says, rather than a click and keys: the menu opens as a window of its own that an injected key never reaches, so Enter closes it with nothing chosen |
 | 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 |

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

@@ -341,15 +341,29 @@ func inject_mouse_click(params: Dictionary) -> Dictionary:
 	}
 
 
+## Moves the pointer to a position, with the movement the event carries taken from where the
+## pointer last was unless the caller says otherwise.
+##
+## A real pointer never arrives without a `relative`, and a control that drags reads that field
+## rather than the position, so a motion carrying none leaves a grip where it was however far the
+## position moved. The viewport remembers where the last motion put the pointer, injected or not,
+## so the difference from there is what a real move would have carried. A relative the caller gives
+## is kept, since a game may want to read a motion the position does not show.
 func inject_mouse_motion(params: Dictionary) -> Dictionary:
 	var point: Variant = _read_point(params, "x", "y", "position")
 	if point is String:
 		return {"type": "error", "message": point}
 	var position: Vector2 = point
-	var movement: Variant = _read_point(params, "relativeX", "relativeY", "relative")
-	if movement is String:
-		return {"type": "error", "message": movement}
-	var relative: Vector2 = movement
+	var relative: Vector2 = position - _host.get_viewport().get_mouse_position()
+	if params.has("relativeX") or params.has("relativeY"):
+		relative = Vector2(
+			Read.as_float(params.get("relativeX", 0.0)), Read.as_float(params.get("relativeY", 0.0))
+		)
+	elif params.has("relative"):
+		var movement: Variant = _read_point(params, "relativeX", "relativeY", "relative")
+		if movement is String:
+			return {"type": "error", "message": movement}
+		relative = movement
 
 	Input.parse_input_event(_motion(position, relative))
 
@@ -790,14 +804,21 @@ func _click_in_the_world(node_path: String, item: Node3D, params: Dictionary) ->
 	}
 
 
+## The buttons a real pointer event carries are the ones held as it happens, and Input keeps that
+## from every button event it is given, injected ones included, so a motion between a held click
+## and its release is a drag to a control that reads the mask rather than remembering the click.
 func _motion(position: Vector2, relative: Vector2) -> InputEventMouseMotion:
 	var event: InputEventMouseMotion = InputEventMouseMotion.new()
 	event.position = position
 	event.global_position = position
 	event.relative = relative
+	event.screen_relative = relative
+	event.button_mask = Input.get_mouse_button_mask()
 	return event
 
 
+## A button event carries the buttons held once it has happened: the pressed one among them, the
+## released one out. A wheel step is a button with no mask, as it is from a real mouse.
 func _button(position: Vector2, button: int, pressed: bool, double: bool) -> InputEventMouseButton:
 	var event: InputEventMouseButton = InputEventMouseButton.new()
 	event.position = position
@@ -805,9 +826,20 @@ func _button(position: Vector2, button: int, pressed: bool, double: bool) -> Inp
 	event.button_index = button as MouseButton
 	event.pressed = pressed
 	event.double_click = double
+	var held: int = Input.get_mouse_button_mask()
+	var own: int = _mask_of(button)
+	event.button_mask = (held | own) if pressed else (held & ~own)
 	return event
 
 
+## The mask bit for a button, which is the engine's own mapping: left 1, right 2, middle 4, the
+## two extra buttons 128 and 256. The wheel steps between have none.
+func _mask_of(button: int) -> int:
+	if button >= MOUSE_BUTTON_WHEEL_UP and button <= MOUSE_BUTTON_WHEEL_RIGHT:
+		return 0
+	return 1 << (button - 1)
+
+
 ## What to say about a name that is not a mouse button, with the ones that are.
 func _no_such_button(named: Variant) -> Dictionary:
 	return {

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

@@ -247,11 +247,27 @@ func _matches_apart_from_name(node: Node, wanted: Dictionary[String, String]) ->
 		if not script is Script:
 			return false
 		var attached: Script = script
-		if attached.get_global_name() != wanted["class"]:
+		if not _script_is(attached, wanted["class"]):
 			return false
 	return true
 
 
+## Whether [param attached] is the script class [param wanted], the way a typed `is` reads it: its
+## own class_name, or one it extends at any distance.
+##
+## The class_name alone answered 0 for `Card` over a tree of rows whose scripts extend Card two
+## steps down, IntakeRow extends DocketCard extends Card, while `is_class` reaches every native
+## subclass. A caller naming a class means what extends it, whichever side of the line the class
+## is declared on.
+static func _script_is(attached: Script, wanted: String) -> bool:
+	var walk: Script = attached
+	while walk != null:
+		if walk.get_global_name() == wanted:
+			return true
+		walk = walk.get_base_script()
+	return false
+
+
 ## Where a node is on screen: a Control's rectangle, a Node2D's position, or the place a 3D node
 ## is drawn in, in both the canvas coordinates the node reports and the window pixels input
 ## arrives in. The two differ whenever the project stretches its viewport, which is what made a

package/build/index.js

@@ -29942,12 +29942,12 @@ var TOOL_SPECS = [
       relativeX: {
         type: "number",
         ops: ["mouse_motion"],
-        description: "mouse_motion: movement since the last event."
+        description: "mouse_motion: the movement the event carries. Left out, it is the distance from where the pointer last was, which is what a control that drags reads; give it to send a motion the position does not show."
       },
       relativeY: {
         type: "number",
         ops: ["mouse_motion"],
-        description: "mouse_motion: movement since the last event."
+        description: "mouse_motion: as relativeX."
       }
     },
     requires: [],
@@ -29961,13 +29961,22 @@ var TOOL_SPECS = [
         requires: ["nodePath"]
       },
       action: { summary: "press an action, or hold it", requires: ["action"] },
-      key: { summary: "press a key, or hold it", requires: ["keycode"] },
+      key: {
+        summary: "press a key, or hold it. Not for a menu a click has opened: an OptionButton or PopupMenu pops up as a window of its own that a key sent to the game never reaches, so an arrow moves nothing in it and Enter closes it with nothing chosen. choose is what selects there",
+        requires: ["keycode"]
+      },
       text: {
         summary: "type a string into the field being edited, a character at a time, and say what it landed in",
         requires: ["text"]
       },
-      mouse_click: { summary: "one mouse button event at a position", requires: ["x", "y"] },
-      mouse_motion: { summary: "move the mouse to a position", requires: ["x", "y"] }
+      mouse_click: {
+        summary: "one mouse button event at a position, carrying the buttons held once it has happened. A drag is a press held with pressed true, motions, and a release with pressed false",
+        requires: ["x", "y"]
+      },
+      mouse_motion: {
+        summary: "move the mouse to a position, carrying the distance from where it last was unless relativeX and relativeY say otherwise, and the buttons held, so a control that drags moves under a run of these between a held mouse_click and its release",
+        requires: ["x", "y"]
+      }
     }
   },
   {

package/package.json

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