gdharness 0.6.7 → 0.6.9

package/build/cli.js

@@ -15034,6 +15034,13 @@ function readParams(params, key) {
 }
 
 // src/tool-definitions.ts
+function opTakes(spec, op, name) {
+  const ops = spec.parameters[name]?.ops;
+  return ops === undefined || ops.includes(op);
+}
+function argumentsOf(spec, op) {
+  return Object.keys(spec.parameters).filter((name) => opTakes(spec, op, name));
+}
 function toolSpec(name) {
   return SPECS_BY_NAME[name];
 }
@@ -15059,7 +15066,8 @@ function buildToolDefinitions() {
       };
     }
     for (const [name, schema] of Object.entries(spec.parameters)) {
-      properties[name] = schema;
+      const { ops: _ops, ...carried } = schema;
+      properties[name] = carried;
     }
     const required = [...spec.requires];
     if (spec.operations && !spec.defaultOperation) {
@@ -15749,35 +15757,46 @@ var init_tool_definitions = __esm(() => {
         projectPath: RUNNING_PROJECT_PATH,
         nodePath: {
           type: "string",
+          ops: ["tree", "text", "find", "rect", "property"],
           description: "tree, find, text: where to start, default /root. rect: the node to place. property: the node to read."
         },
         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."
         },
-        depth: { type: "number", description: "tree: levels to descend. Default 3." },
+        depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
         includeProperties: {
           type: "boolean",
+          ops: ["tree"],
           description: "tree: include each node's properties. Default false."
         },
         className: {
           type: "string",
+          ops: ["find"],
           description: "find: a native class, matching its subclasses too, or a class_name."
         },
-        script: { type: "string", description: "find: the script file the node carries." },
+        script: { type: "string", ops: ["find"], description: "find: the script file the node carries." },
         namePattern: {
           type: "string",
+          ops: ["find"],
           description: 'find: a case-insensitive glob on the node name, such as "Enemy*".'
         },
-        group: { type: "string", description: "find: a group the node is in." },
-        limit: { type: "number", description: "find: the most nodes to answer with. Default 100." },
+        group: { type: "string", ops: ["find"], description: "find: a group the node is in." },
+        limit: {
+          type: "number",
+          ops: ["find", "text"],
+          description: "find: the most nodes to answer with, default 100. text: the most lines, default 500, with truncated saying whether there were more."
+        },
         includeHidden: {
           type: "boolean",
+          ops: ["text"],
           description: "text: read hidden nodes as well, for checking that something is not showing. Default false."
         },
         metrics: {
           type: "array",
           items: { type: "string" },
+          ops: ["metrics"],
           description: "metrics: which to read. Default all."
         }
       },
@@ -15785,7 +15804,7 @@ var init_tool_definitions = __esm(() => {
       operations: {
         tree: { summary: "the live scene tree", requires: [] },
         text: {
-          summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+          summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it",
           requires: []
         },
         find: {
@@ -15810,10 +15829,14 @@ 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" },
-        value: { description: "set: the value, fitted to the property's type." },
-        method: { type: "string" },
-        args: { type: "array", description: "call: the arguments, fitted to the method's parameter types." }
+        property: { type: "string", ops: ["set"] },
+        value: { ops: ["set"], description: "set: the value, fitted to the property's type." },
+        method: { type: "string", ops: ["call"] },
+        args: {
+          type: "array",
+          ops: ["call"],
+          description: "call: the arguments, fitted to the method's parameter types."
+        }
       },
       requires: ["nodePath"],
       operations: {
@@ -15828,6 +15851,7 @@ var init_tool_definitions = __esm(() => {
         projectPath: RUNNING_PROJECT_PATH,
         viewportPath: {
           type: "string",
+          ops: ["viewport"],
           description: "viewport: the Viewport node. Default the root viewport."
         },
         width: { type: "number", description: "Scale the image to this width." },
@@ -15847,38 +15871,64 @@ var init_tool_definitions = __esm(() => {
         projectPath: RUNNING_PROJECT_PATH,
         nodePath: {
           type: "string",
+          ops: ["click", "choose"],
           description: "click: the Control to click, at its centre, or the 3D node to click, where it is drawn. choose: the PopupMenu, or the OptionButton or MenuButton in front of one."
         },
-        action: { type: "string", description: "action: the InputMap action name." },
+        action: { type: "string", ops: ["action"], description: "action: the InputMap action name." },
         pressed: {
           type: "boolean",
-          description: "action, key: leave it out and the press is a whole one, down and up a frame apart. true holds it down, false lets go of one being held."
+          ops: ["action", "key", "mouse_click"],
+          description: "action, key: leave it out and the press is a whole one, down and up a frame apart. true holds it down, false lets go of one being held. mouse_click is one raw event, so it is down unless you say false."
         },
-        strength: { type: "number", description: "action: 0 to 1. Default 1." },
+        strength: { type: "number", ops: ["action"], description: "action: 0 to 1. Default 1." },
         keycode: {
           type: ["string", "number"],
+          ops: ["key"],
           description: 'key: the key name, such as "Space" or "A", or its Godot keycode.'
         },
         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."
         },
         index: {
           type: "number",
+          ops: ["choose"],
           description: "choose: the item to take, by where it is in the list, when text will not do."
         },
-        shift: { type: "boolean" },
-        ctrl: { type: "boolean" },
-        alt: { type: "boolean" },
-        x: { type: "number", description: "mouse_click, mouse_motion: window pixels." },
-        y: { type: "number", description: "mouse_click, mouse_motion: window pixels." },
+        shift: { type: "boolean", ops: ["key"] },
+        ctrl: { type: "boolean", ops: ["key"] },
+        alt: { type: "boolean", ops: ["key"] },
+        x: {
+          type: "number",
+          ops: ["mouse_click", "mouse_motion"],
+          description: "mouse_click, mouse_motion: window pixels."
+        },
+        y: {
+          type: "number",
+          ops: ["mouse_click", "mouse_motion"],
+          description: "mouse_click, mouse_motion: window pixels."
+        },
         button: {
           type: ["string", "number"],
+          ops: ["click", "mouse_click"],
           description: "click, mouse_click: left, right, middle, wheel_up or wheel_down, or a button number. Default left."
         },
-        doubleClick: { type: "boolean", description: "click, mouse_click: default false." },
-        relativeX: { type: "number", description: "mouse_motion: movement since the last event." },
-        relativeY: { type: "number", description: "mouse_motion: movement since the last event." }
+        doubleClick: {
+          type: "boolean",
+          ops: ["click", "mouse_click"],
+          description: "click, mouse_click: default false."
+        },
+        relativeX: {
+          type: "number",
+          ops: ["mouse_motion"],
+          description: "mouse_motion: movement since the last event."
+        },
+        relativeY: {
+          type: "number",
+          ops: ["mouse_motion"],
+          description: "mouse_motion: movement since the last event."
+        }
       },
       requires: [],
       operations: {
@@ -15893,7 +15943,7 @@ var init_tool_definitions = __esm(() => {
         action: { summary: "press an action, or hold it", requires: ["action"] },
         key: { summary: "press a key, or hold it", requires: ["keycode"] },
         text: {
-          summary: "type a string wherever the focus is, a character at a time",
+          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"] },
@@ -15905,14 +15955,19 @@ var init_tool_definitions = __esm(() => {
       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.",
       parameters: {
         projectPath: RUNNING_PROJECT_PATH,
-        frames: { type: "number", description: "frames: how many to let pass, 1 to 600." },
-        nodePath: { type: "string", description: "signal, until: the node." },
-        signal: { type: "string", description: "signal: the signal name." },
-        property: { type: "string", description: "until: the property name." },
-        value: { description: "until: the value to wait for, fitted to the property's type." },
+        frames: {
+          type: "number",
+          ops: ["frames"],
+          description: "frames: how many to let pass, 1 to 600. More than that is refused."
+        },
+        nodePath: { type: "string", ops: ["signal", "until"], description: "signal, until: the node." },
+        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." },
         timeoutMs: {
           type: "number",
-          description: "signal, until: how long to wait before answering anyway. Default 5000."
+          ops: ["signal", "until"],
+          description: "signal, until: how long to wait before answering anyway, 1 to 120000. Default 5000."
         }
       },
       requires: [],
@@ -15959,6 +16014,7 @@ var init_tool_definitions = __esm(() => {
       parameters: {
         frameId: {
           type: "number",
+          ops: ["variables"],
           description: "variables: which frame, from a stack answer. Default the innermost."
         }
       },
@@ -36262,6 +36318,15 @@ class GodotServer {
         };
       }
     }
+    if (op !== null) {
+      const elsewhere = Object.keys(args).filter((key) => key !== "op" && !opTakes(spec, op, key));
+      if (elsewhere.length > 0) {
+        return {
+          ok: false,
+          response: this.createErrorResponse(`${spec.name} ${op} does not take ${elsewhere.join(", ")}. ${op} takes: ${argumentsOf(spec, op).join(", ")}.`)
+        };
+      }
+    }
     const required = [...spec.requires, ...op !== null ? spec.operations?.[op]?.requires ?? [] : []];
     const missing = required.filter((field) => {
       const value = Object.hasOwn(args, field) ? args[field] : undefined;
@@ -36386,7 +36451,8 @@ class GodotServer {
             return await this.handleRuntimeCommand("read_text", {
               projectPath: args["projectPath"],
               root: readNonEmptyString(args, "nodePath") ?? "/root",
-              include_hidden: readBoolean(args, "includeHidden") ?? false
+              include_hidden: readBoolean(args, "includeHidden") ?? false,
+              limit: readPositiveNumber(args, "limit") ?? 500
             });
           case "rect":
             return await this.handleRuntimeCommand("get_rect", {
@@ -37428,31 +37494,26 @@ class GodotServer {
     });
   }
   async handleRuntimeWait(op, args) {
+    if (op === "frames") {
+      const frames = readPositiveNumber(args, "frames") ?? 1;
+      const waited = patienceForFrames(frames, this.runtimeTimeoutMs());
+      return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
+    }
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 5000;
     const nodePath = readNonEmptyString(args, "nodePath") ?? "";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
-    switch (op) {
-      case "frames": {
-        const frames = readPositiveNumber(args, "frames") ?? 1;
-        const waited = patienceForFrames(frames, patience);
-        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
-      }
-      case "signal":
-        return await this.handleRuntimeCommand("wait_signal", {
-          projectPath: args["projectPath"],
-          path: nodePath,
-          signal: readString(args, "signal") ?? "",
-          timeout_ms: timeoutMs
-        }, patience);
-      default:
-        return await this.handleRuntimeCommand("wait_until", {
-          projectPath: args["projectPath"],
-          path: nodePath,
-          property: readString(args, "property") ?? "",
-          value: args["value"],
-          timeout_ms: timeoutMs
-        }, patience);
-    }
+    return op === "signal" ? await this.handleRuntimeCommand("wait_signal", {
+      projectPath: args["projectPath"],
+      path: nodePath,
+      signal: readString(args, "signal") ?? "",
+      timeout_ms: timeoutMs
+    }, patience) : await this.handleRuntimeCommand("wait_until", {
+      projectPath: args["projectPath"],
+      path: nodePath,
+      property: readString(args, "property") ?? "",
+      value: args["value"],
+      timeout_ms: timeoutMs
+    }, patience);
   }
 }
 async function runGodotServer() {
@@ -38763,7 +38824,9 @@ function renderToolsMarkdown() {
         const needs = [...tool.requires, ...spec.requires];
         const isDefault = tool.defaultOperation === op ? " (default)" : "";
         const wants = needs.length > 0 ? ` Needs: ${needs.map((name) => `\`${name}\``).join(", ")}.` : "";
-        lines.push(`- \`op: ${op}\`${isDefault}: ${spec.summary}.${wants}`);
+        const spare = argumentsOf(tool, op).filter((name) => !needs.includes(name) && name !== "projectPath");
+        const takes = spare.length > 0 ? ` Takes: ${spare.map((name) => `\`${name}\``).join(", ")}.` : "";
+        lines.push(`- \`op: ${op}\`${isDefault}: ${spec.summary}.${wants}${takes}`);
       }
       lines.push("");
     } else if (tool.requires.length > 0) {
@@ -38827,7 +38890,7 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | Where a control is, and whether it is visible | \`runtime_inspect\` \`find\`, \`rect\` |
 | What a property reads right now | \`runtime_inspect\` \`property\`, \`runtime_invoke\` |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |
-| Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\` |
+| Fill in a field | \`runtime_input click\` on it, then \`runtime_input text\`; a submitted field has to be clicked again |
 | Click somebody standing in a 3D room | \`runtime_input click\` on the Node3D, which aims at what it draws |
 | Pick something out of a dropdown | \`runtime_input choose\` on it, by what the item says |
 | Answer a dialog, or press a bound key | \`runtime_input action\` or \`key\`, a whole press unless you hold it |

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

@@ -161,6 +161,11 @@ func inject_text(params: Dictionary) -> Dictionary:
 		return {"type": "error", "message": "text required"}
 
 	var viewport: Viewport = _host.get_tree().root
+	var focused: Control = viewport.gui_get_focus_owner()
+	var shut: String = _shut_to_typing(focused)
+	if not shut.is_empty():
+		return {"type": "error", "message": shut}
+
 	for index: int in text.length():
 		var down: InputEventKey = _typed(text.unicode_at(index))
 		viewport.push_input(down)
@@ -169,7 +174,41 @@ func inject_text(params: Dictionary) -> Dictionary:
 		up.pressed = false
 		viewport.push_input(up)
 
-	return {"type": "input_injected", "input_type": "text", "text": text, "characters": text.length()}
+	# 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.
+	var into: Variant = null
+	if focused != null:
+		into = str(focused.get_path())
+
+	return {
+		"type": "input_injected",
+		"input_type": "text",
+		"text": text,
+		"characters": text.length(),
+		"into": into,
+	}
+
+
+## Why nothing typed would reach [param focused], or "" when it would.
+##
+## Having the focus is not the same as being edited. Since Godot 4.4 a field is focused and shut
+## until something opens it, which is what a click does and what submitting undoes: press Enter in
+## a box and it keeps the focus and drops every key that arrives afterwards. Typing into one
+## answered that the characters had gone in and put nothing anywhere, which is the shape a refusal
+## exists to prevent. Measured on a spin box in a real game: `has_focus` true, `is_editing` false,
+## three characters reported and the field unchanged.
+##
+## Only a [LineEdit] is refused: it is the one control the engine will say this about, since
+## [TextEdit] has no editing state of its own. A game reading keys for itself is typed at with
+## nothing focused at all, and that is not this tool's business to judge.
+static func _shut_to_typing(focused: Control) -> String:
+	var field: LineEdit = focused as LineEdit
+	if field == null or field.is_editing():
+		return ""
+	return (
+		"%s has the focus and is not being edited, so nothing typed lands in it. Click it first."
+		% focused.get_path()
+	)
 
 
 ## The key press that produces [param glyph], as a keyboard would send it.

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

@@ -10,8 +10,8 @@ const Values = preload("runtime_values.gd")
 const FIND_LIMIT: int = 100
 const FIND_LIMIT_CEILING: int = 1000
 
-## The most lines one read answers with. A screen is a few dozen; a thousand is a tree somebody
-## pointed this at by mistake.
+## The most lines one read answers with, unless asked for fewer. A screen is a few dozen; a
+## thousand is a tree somebody pointed this at by mistake.
 const READ_LIMIT: int = 500
 
 var _host: Node
@@ -153,38 +153,62 @@ func _matches(
 ## A hidden node is left out and so is everything under it, because what a player reads is what is
 ## drawn. [param include_hidden] asks for the lot instead, which is what a caller checking that
 ## something is not showing wants.
+##
+## [param limit] is the first few lines rather than all of them, which is how the top of a screen
+## is read without the hall under it: the bar along the top of a guild is eleven lines and the
+## panel it sits on is two hundred.
 func read_text(params: Dictionary) -> Dictionary:
 	var root_path: String = str(params.get("root", "/root"))
 	var include_hidden: bool = bool(params.get("include_hidden", false))
+	var limit: int = clampi(int(params.get("limit", READ_LIMIT)), 1, READ_LIMIT)
 
 	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
 	if root == null:
 		return {"type": "error", "message": "Node not found: " + root_path}
 
-	var lines: PackedStringArray = PackedStringArray()
-	_read_into(root, include_hidden, lines)
+	# One line further than asked for, so that whether anything was left behind is read off the
+	# walk rather than guessed at from the count: a panel of exactly as many lines as the caller
+	# asked for is one they have read all of, and saying otherwise sends them back for nothing.
+	var read: PackedStringArray = PackedStringArray()
+	_read_into(root, include_hidden, limit + 1, read)
+	var more: bool = read.size() > limit
+	var lines: PackedStringArray = read.slice(0, limit) if more else read
 	return {
 		"type": "text",
 		"root": root_path,
 		"lines": lines,
 		"count": lines.size(),
-		"truncated": lines.size() >= READ_LIMIT,
+		"truncated": more,
 	}
 
 
 ## Walks [param node] depth first, which is the order the screen is laid out in and the order a
 ## person reads it.
-func _read_into(node: Node, include_hidden: bool, into: PackedStringArray) -> void:
-	if into.size() >= READ_LIMIT:
+##
+## Internal children as well, because the number in a SpinBox is one: the field a player reads it
+## in is a LineEdit the engine builds inside the box and leaves out of `get_children()`, so a
+## screen full of forms answered with every label on it and none of the values in it. The hidden
+## check covers a [Window] for the same walk: a dropdown's popup is a child that is not drawn
+## until it is opened, and reading a closed menu would put every item on the screen.
+func _read_into(node: Node, include_hidden: bool, most: int, into: PackedStringArray) -> void:
+	if into.size() >= most:
 		return
-	var control: CanvasItem = node as CanvasItem
-	if not include_hidden and control != null and not control.visible:
+	if not include_hidden and not _drawn(node):
 		return
 	var said: String = _said_by(node)
 	if not said.is_empty():
 		into.append(said)
-	for child: Node in node.get_children():
-		_read_into(child, include_hidden, into)
+	for child: Node in node.get_children(true):
+		_read_into(child, include_hidden, most, into)
+
+
+## Whether [param node] is on the screen at all, for the two kinds of thing that can be hidden.
+static func _drawn(node: Node) -> bool:
+	var control: CanvasItem = node as CanvasItem
+	if control != null:
+		return control.visible
+	var window: Window = node as Window
+	return window == null or window.visible
 
 
 ## What one node says, or "" for a node that says nothing. Anything with a `text` property, which

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

@@ -9,6 +9,9 @@ const Values = preload("runtime_values.gd")
 ## since given up on the reply.
 const CEILING_MSEC: int = 120000
 
+## The most frames one wait may cover, which is about half a minute of a game drawing slowly.
+const MOST_FRAMES: int = 600
+
 var _host: Node
 var _values: Values
 
@@ -18,8 +21,21 @@ func _init(host: Node, values: Values) -> void:
 	_values = values
 
 
+## Refuses [param asked] rather than bringing it inside [param least] to [param most].
+##
+## A number quietly brought inside the range is a wait that did not last as long as the caller
+## believes and a timeout that gave up sooner: asking for 900 frames and waiting 600 reads as 900
+## frames of the game having passed, and everything measured off it is out by that much.
+static func _out_of_range(named: String, asked: int, least: int, most: int) -> Dictionary:
+	return {
+		"type": "error", "message": "%s is %d, and %s takes %d to %d." % [named, asked, named, least, most]
+	}
+
+
 func wait_frames(params: Dictionary) -> Dictionary:
-	var frames: int = clampi(int(params.get("frames", 1)), 1, 600)
+	var frames: int = int(params.get("frames", 1))
+	if frames < 1 or frames > MOST_FRAMES:
+		return _out_of_range("frames", frames, 1, MOST_FRAMES)
 	var started: int = Time.get_ticks_msec()
 	for _frame: int in frames:
 		await _host.get_tree().process_frame
@@ -30,7 +46,9 @@ func wait_frames(params: Dictionary) -> Dictionary:
 func wait_signal(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var signal_name: String = str(params.get("signal", ""))
-	var timeout_ms: int = clampi(int(params.get("timeout_ms", 5000)), 1, CEILING_MSEC)
+	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 signal_name.is_empty():
 		return {"type": "error", "message": "Node path and signal name required"}
 
@@ -65,7 +83,9 @@ func wait_signal(params: Dictionary) -> Dictionary:
 func wait_until(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var property: String = str(params.get("property", ""))
-	var timeout_ms: int = clampi(int(params.get("timeout_ms", 5000)), 1, CEILING_MSEC)
+	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 not params.has("value"):

package/build/index.js

@@ -27633,6 +27633,13 @@ function installedAddonVersion(projectPath) {
 }
 
 // src/tool-definitions.ts
+function opTakes(spec, op, name) {
+  const ops = spec.parameters[name]?.ops;
+  return ops === undefined || ops.includes(op);
+}
+function argumentsOf(spec, op) {
+  return Object.keys(spec.parameters).filter((name) => opTakes(spec, op, name));
+}
 var PROJECT_PATH = {
   type: "string",
   description: "Absolute path to the project directory, the one holding project.godot."
@@ -28303,35 +28310,46 @@ var TOOL_SPECS = [
       projectPath: RUNNING_PROJECT_PATH,
       nodePath: {
         type: "string",
+        ops: ["tree", "text", "find", "rect", "property"],
         description: "tree, find, text: where to start, default /root. rect: the node to place. property: the node to read."
       },
       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."
       },
-      depth: { type: "number", description: "tree: levels to descend. Default 3." },
+      depth: { type: "number", ops: ["tree"], description: "tree: levels to descend. Default 3." },
       includeProperties: {
         type: "boolean",
+        ops: ["tree"],
         description: "tree: include each node's properties. Default false."
       },
       className: {
         type: "string",
+        ops: ["find"],
         description: "find: a native class, matching its subclasses too, or a class_name."
       },
-      script: { type: "string", description: "find: the script file the node carries." },
+      script: { type: "string", ops: ["find"], description: "find: the script file the node carries." },
       namePattern: {
         type: "string",
+        ops: ["find"],
         description: 'find: a case-insensitive glob on the node name, such as "Enemy*".'
       },
-      group: { type: "string", description: "find: a group the node is in." },
-      limit: { type: "number", description: "find: the most nodes to answer with. Default 100." },
+      group: { type: "string", ops: ["find"], description: "find: a group the node is in." },
+      limit: {
+        type: "number",
+        ops: ["find", "text"],
+        description: "find: the most nodes to answer with, default 100. text: the most lines, default 500, with truncated saying whether there were more."
+      },
       includeHidden: {
         type: "boolean",
+        ops: ["text"],
         description: "text: read hidden nodes as well, for checking that something is not showing. Default false."
       },
       metrics: {
         type: "array",
         items: { type: "string" },
+        ops: ["metrics"],
         description: "metrics: which to read. Default all."
       }
     },
@@ -28339,7 +28357,7 @@ var TOOL_SPECS = [
     operations: {
       tree: { summary: "the live scene tree", requires: [] },
       text: {
-        summary: "every line of text under nodePath, in the order somebody reads the screen, leaving out what is hidden and everything under it",
+        summary: "every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it",
         requires: []
       },
       find: {
@@ -28364,10 +28382,14 @@ var TOOL_SPECS = [
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
       nodePath: { type: "string", description: 'Absolute node path, such as "/root/Main/Player".' },
-      property: { type: "string" },
-      value: { description: "set: the value, fitted to the property's type." },
-      method: { type: "string" },
-      args: { type: "array", description: "call: the arguments, fitted to the method's parameter types." }
+      property: { type: "string", ops: ["set"] },
+      value: { ops: ["set"], description: "set: the value, fitted to the property's type." },
+      method: { type: "string", ops: ["call"] },
+      args: {
+        type: "array",
+        ops: ["call"],
+        description: "call: the arguments, fitted to the method's parameter types."
+      }
     },
     requires: ["nodePath"],
     operations: {
@@ -28382,6 +28404,7 @@ var TOOL_SPECS = [
       projectPath: RUNNING_PROJECT_PATH,
       viewportPath: {
         type: "string",
+        ops: ["viewport"],
         description: "viewport: the Viewport node. Default the root viewport."
       },
       width: { type: "number", description: "Scale the image to this width." },
@@ -28401,38 +28424,64 @@ var TOOL_SPECS = [
       projectPath: RUNNING_PROJECT_PATH,
       nodePath: {
         type: "string",
+        ops: ["click", "choose"],
         description: "click: the Control to click, at its centre, or the 3D node to click, where it is drawn. choose: the PopupMenu, or the OptionButton or MenuButton in front of one."
       },
-      action: { type: "string", description: "action: the InputMap action name." },
+      action: { type: "string", ops: ["action"], description: "action: the InputMap action name." },
       pressed: {
         type: "boolean",
-        description: "action, key: leave it out and the press is a whole one, down and up a frame apart. true holds it down, false lets go of one being held."
+        ops: ["action", "key", "mouse_click"],
+        description: "action, key: leave it out and the press is a whole one, down and up a frame apart. true holds it down, false lets go of one being held. mouse_click is one raw event, so it is down unless you say false."
       },
-      strength: { type: "number", description: "action: 0 to 1. Default 1." },
+      strength: { type: "number", ops: ["action"], description: "action: 0 to 1. Default 1." },
       keycode: {
         type: ["string", "number"],
+        ops: ["key"],
         description: 'key: the key name, such as "Space" or "A", or its Godot keycode.'
       },
       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."
       },
       index: {
         type: "number",
+        ops: ["choose"],
         description: "choose: the item to take, by where it is in the list, when text will not do."
       },
-      shift: { type: "boolean" },
-      ctrl: { type: "boolean" },
-      alt: { type: "boolean" },
-      x: { type: "number", description: "mouse_click, mouse_motion: window pixels." },
-      y: { type: "number", description: "mouse_click, mouse_motion: window pixels." },
+      shift: { type: "boolean", ops: ["key"] },
+      ctrl: { type: "boolean", ops: ["key"] },
+      alt: { type: "boolean", ops: ["key"] },
+      x: {
+        type: "number",
+        ops: ["mouse_click", "mouse_motion"],
+        description: "mouse_click, mouse_motion: window pixels."
+      },
+      y: {
+        type: "number",
+        ops: ["mouse_click", "mouse_motion"],
+        description: "mouse_click, mouse_motion: window pixels."
+      },
       button: {
         type: ["string", "number"],
+        ops: ["click", "mouse_click"],
         description: "click, mouse_click: left, right, middle, wheel_up or wheel_down, or a button number. Default left."
       },
-      doubleClick: { type: "boolean", description: "click, mouse_click: default false." },
-      relativeX: { type: "number", description: "mouse_motion: movement since the last event." },
-      relativeY: { type: "number", description: "mouse_motion: movement since the last event." }
+      doubleClick: {
+        type: "boolean",
+        ops: ["click", "mouse_click"],
+        description: "click, mouse_click: default false."
+      },
+      relativeX: {
+        type: "number",
+        ops: ["mouse_motion"],
+        description: "mouse_motion: movement since the last event."
+      },
+      relativeY: {
+        type: "number",
+        ops: ["mouse_motion"],
+        description: "mouse_motion: movement since the last event."
+      }
     },
     requires: [],
     operations: {
@@ -28447,7 +28496,7 @@ var TOOL_SPECS = [
       action: { summary: "press an action, or hold it", requires: ["action"] },
       key: { summary: "press a key, or hold it", requires: ["keycode"] },
       text: {
-        summary: "type a string wherever the focus is, a character at a time",
+        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"] },
@@ -28459,14 +28508,19 @@ var TOOL_SPECS = [
     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.",
     parameters: {
       projectPath: RUNNING_PROJECT_PATH,
-      frames: { type: "number", description: "frames: how many to let pass, 1 to 600." },
-      nodePath: { type: "string", description: "signal, until: the node." },
-      signal: { type: "string", description: "signal: the signal name." },
-      property: { type: "string", description: "until: the property name." },
-      value: { description: "until: the value to wait for, fitted to the property's type." },
+      frames: {
+        type: "number",
+        ops: ["frames"],
+        description: "frames: how many to let pass, 1 to 600. More than that is refused."
+      },
+      nodePath: { type: "string", ops: ["signal", "until"], description: "signal, until: the node." },
+      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." },
       timeoutMs: {
         type: "number",
-        description: "signal, until: how long to wait before answering anyway. Default 5000."
+        ops: ["signal", "until"],
+        description: "signal, until: how long to wait before answering anyway, 1 to 120000. Default 5000."
       }
     },
     requires: [],
@@ -28513,6 +28567,7 @@ var TOOL_SPECS = [
     parameters: {
       frameId: {
         type: "number",
+        ops: ["variables"],
         description: "variables: which frame, from a stack answer. Default the innermost."
       }
     },
@@ -28551,7 +28606,8 @@ function buildToolDefinitions() {
       };
     }
     for (const [name, schema] of Object.entries(spec.parameters)) {
-      properties[name] = schema;
+      const { ops: _ops, ...carried } = schema;
+      properties[name] = carried;
     }
     const required = [...spec.requires];
     if (spec.operations && !spec.defaultOperation) {
@@ -29042,6 +29098,15 @@ class GodotServer {
         };
       }
     }
+    if (op !== null) {
+      const elsewhere = Object.keys(args).filter((key) => key !== "op" && !opTakes(spec, op, key));
+      if (elsewhere.length > 0) {
+        return {
+          ok: false,
+          response: this.createErrorResponse(`${spec.name} ${op} does not take ${elsewhere.join(", ")}. ${op} takes: ${argumentsOf(spec, op).join(", ")}.`)
+        };
+      }
+    }
     const required = [...spec.requires, ...op !== null ? spec.operations?.[op]?.requires ?? [] : []];
     const missing = required.filter((field) => {
       const value = Object.hasOwn(args, field) ? args[field] : undefined;
@@ -29166,7 +29231,8 @@ class GodotServer {
             return await this.handleRuntimeCommand("read_text", {
               projectPath: args["projectPath"],
               root: readNonEmptyString(args, "nodePath") ?? "/root",
-              include_hidden: readBoolean(args, "includeHidden") ?? false
+              include_hidden: readBoolean(args, "includeHidden") ?? false,
+              limit: readPositiveNumber(args, "limit") ?? 500
             });
           case "rect":
             return await this.handleRuntimeCommand("get_rect", {
@@ -30208,31 +30274,26 @@ class GodotServer {
     });
   }
   async handleRuntimeWait(op, args) {
+    if (op === "frames") {
+      const frames = readPositiveNumber(args, "frames") ?? 1;
+      const waited = patienceForFrames(frames, this.runtimeTimeoutMs());
+      return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
+    }
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 5000;
     const nodePath = readNonEmptyString(args, "nodePath") ?? "";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
-    switch (op) {
-      case "frames": {
-        const frames = readPositiveNumber(args, "frames") ?? 1;
-        const waited = patienceForFrames(frames, patience);
-        return await this.handleRuntimeCommand("wait_frames", { projectPath: args["projectPath"], frames }, waited);
-      }
-      case "signal":
-        return await this.handleRuntimeCommand("wait_signal", {
-          projectPath: args["projectPath"],
-          path: nodePath,
-          signal: readString(args, "signal") ?? "",
-          timeout_ms: timeoutMs
-        }, patience);
-      default:
-        return await this.handleRuntimeCommand("wait_until", {
-          projectPath: args["projectPath"],
-          path: nodePath,
-          property: readString(args, "property") ?? "",
-          value: args["value"],
-          timeout_ms: timeoutMs
-        }, patience);
-    }
+    return op === "signal" ? await this.handleRuntimeCommand("wait_signal", {
+      projectPath: args["projectPath"],
+      path: nodePath,
+      signal: readString(args, "signal") ?? "",
+      timeout_ms: timeoutMs
+    }, patience) : await this.handleRuntimeCommand("wait_until", {
+      projectPath: args["projectPath"],
+      path: nodePath,
+      property: readString(args, "property") ?? "",
+      value: args["value"],
+      timeout_ms: timeoutMs
+    }, patience);
   }
 }
 async function runGodotServer() {

package/package.json

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