gdharness 1.0.14 → 1.0.15

package/build/cli.js

@@ -16398,7 +16398,11 @@ var init_tool_definitions = __esm(() => {
           description: "viewport: the Viewport node. Default the root viewport."
         },
         width: { type: "number", description: "Scale the image to this width." },
-        height: { type: "number", description: "Scale the image to this height." }
+        height: { type: "number", description: "Scale the image to this height." },
+        outputPath: {
+          type: "string",
+          description: "Also save the picture as a PNG at this absolute path, for somebody to open later; the answer says where. Refused unless it ends in .png, its directory exists, it is outside the project, and no file is there already."
+        }
       },
       requires: [],
       operations: {
@@ -16421,7 +16425,7 @@ var init_tool_definitions = __esm(() => {
         action: {
           type: "string",
           ops: ["action"],
-          description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with key Escape, or click its button."
+          description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with the key op and keycode Escape, or click its button."
         },
         pressed: {
           type: "boolean",
@@ -16524,7 +16528,11 @@ var init_tool_definitions = __esm(() => {
           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." },
+        nodePath: {
+          type: "string",
+          ops: ["signal", "until"],
+          description: "signal, until: the node. Needed for a signal and for a property; for says it defaults to /root, the whole screen."
+        },
         signal: { type: "string", ops: ["signal"], description: "signal: the signal name." },
         property: {
           type: "string",
@@ -16535,7 +16543,7 @@ var init_tool_definitions = __esm(() => {
         says: {
           type: "string",
           ops: ["until"],
-          description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+          description: "until: wait for these words to appear anywhere under nodePath, or anywhere in the game when no nodePath is given, instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
         },
         includeHidden: {
           type: "boolean",
@@ -16557,7 +16565,7 @@ var init_tool_definitions = __esm(() => {
         },
         until: {
           summary: "wait for a property to read as a value, or for words to appear under a node, and answer with what it found",
-          requires: ["nodePath"]
+          requires: []
         }
       }
     },
@@ -38025,6 +38033,8 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import {
   appendFileSync,
   closeSync as closeSync2,
+  constants,
+  copyFileSync,
   existsSync as existsSync15,
   fstatSync,
   mkdirSync as mkdirSync13,
@@ -38037,10 +38047,34 @@ import {
   statSync as statSync8
 } from "node:fs";
 import { tmpdir as tmpdir5 } from "node:os";
-import { basename as basename4, dirname as dirname15, isAbsolute as isAbsolute3, join as join22, normalize as normalize3, relative as relative3 } from "node:path";
+import { basename as basename4, dirname as dirname15, extname as extname2, isAbsolute as isAbsolute3, join as join22, normalize as normalize3, relative as relative3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { promisify as promisify7 } from "node:util";
+function captureDestinationRefusal(outputPath, projects) {
+  if (/^(res|user):\/\//.test(outputPath)) {
+    return `outputPath ${outputPath} is a Godot path; a capture is saved outside the project, at an absolute path on this machine.`;
+  }
+  if (!isAbsolute3(outputPath)) {
+    return `outputPath ${outputPath} is not absolute; name the whole path, so where it is written does not depend on this server's directory.`;
+  }
+  if (extname2(outputPath).toLowerCase() !== ".png") {
+    return `outputPath ${outputPath} does not end in .png, which is what a capture is.`;
+  }
+  const directory = realPathOr(dirname15(outputPath));
+  if (!existsSync15(directory)) {
+    return `outputPath's directory ${dirname15(outputPath)} does not exist; a capture creates no directories.`;
+  }
+  const where = join22(directory, basename4(outputPath));
+  const inside = projects.find((project) => project !== "" && isWithinRoot(realPathOr(project), where));
+  if (inside !== undefined) {
+    return `outputPath ${outputPath} is inside the project at ${inside}; a capture is saved outside it, so it never becomes part of the game.`;
+  }
+  if (existsSync15(where)) {
+    return `outputPath ${outputPath} already exists; a capture is not written over a file. Name a new one.`;
+  }
+  return null;
+}
 function patienceForFrames(frames, atLeast) {
   return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
 }
@@ -41333,7 +41367,7 @@ class GodotServer {
     return `The game this server started (${which}) is still coming up and has not announced its runtime after a wait of ${Math.min(budgetMs, remaining)}ms, so there is nothing to talk to yet. It is still running: ask again in a moment rather than starting another.`;
   }
   async handleRuntimeCommand(command, args, timeoutMs = this.runtimeTimeoutMs()) {
-    const { op: _op, projectPath, pid, ...params } = asParams(args);
+    const { op: _op, projectPath, pid, outputPath, ...params } = asParams(args);
     const waited = typeof pid === "number" ? null : await this.ownRunOnItsWay(typeof projectPath === "string" ? projectPath : this.ownProject, timeoutMs);
     if (waited !== null) {
       return this.createErrorResponse(waited, [
@@ -41360,6 +41394,16 @@ class GodotServer {
       ]);
     }
     const expectsScreenshot = command === "capture_screenshot" || command === "capture_viewport";
+    const saveTo = expectsScreenshot && typeof outputPath === "string" ? outputPath : null;
+    if (saveTo !== null) {
+      const refusal = captureDestinationRefusal(saveTo, [
+        choice.endpoint.project.path,
+        ...this.ownProject === null ? [] : [this.ownProject]
+      ]);
+      if (refusal !== null) {
+        return this.createErrorResponse(refusal);
+      }
+    }
     const screenshotDir = expectsScreenshot ? mkdtempSync3(join22(tmpdir5(), "gdharness-runtime-screenshot-")) : null;
     const screenshotPath = screenshotDir ? join22(screenshotDir, "capture.png") : null;
     try {
@@ -41379,11 +41423,18 @@ class GodotServer {
         return this.createErrorResponse(`Rejected screenshot file path outside the managed capture path: '${returnedPath}'`);
       }
       const dimensions = `${readNumber(payload, "width") ?? 0}x${readNumber(payload, "height") ?? 0} ${readString(payload, "format") ?? "unknown"}`;
+      if (saveTo !== null) {
+        try {
+          copyFileSync(screenshotPath, saveTo, constants.COPYFILE_EXCL);
+        } catch (error) {
+          return this.createErrorResponse(`The capture was taken and could not be saved at ${saveTo}: ${errorMessage(error)}`);
+        }
+      }
       return {
         content: [
           {
             type: "text",
-            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}`
+            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${saveTo === null ? "" : `. Saved to ${saveTo}`}`
           },
           { type: "image", data: readFileSync20(screenshotPath).toString("base64"), mimeType: "image/png" }
         ]
@@ -41430,7 +41481,11 @@ class GodotServer {
       return await this.handleRuntimeCommand("wait_frames", { ...whichGame(args), frames }, waited);
     }
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 5000;
-    const nodePath = readNonEmptyString(args, "nodePath") ?? "";
+    const asked = readNonEmptyString(args, "nodePath");
+    if (asked === undefined && op === "until" && readNonEmptyString(args, "says") === undefined) {
+      return this.createErrorResponse("runtime_wait until needs nodePath to wait for a property: the property belongs to that node.", ["With says instead of property, nodePath can be left out and the whole game is searched"]);
+    }
+    const nodePath = asked ?? "/root";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     return op === "signal" ? await this.handleRuntimeCommand("wait_signal", {
       ...whichGame(args),
@@ -43098,12 +43153,12 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
 | What a property on an object a node holds reads | the same two, with colons: \`_game:clock:speed\` |
 | Which control holds the focus, or anything only a method answers | the same path with a step written as a call, \`get_viewport():gui_get_focus_owner\`, which calls a method taking no arguments and walks into what it returned |
 | Press a button | \`runtime_input click\`, which says what was under the pointer |
-| 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 |
+| Press the next thing after a click that changed screen | \`runtime_wait until\` with \`says\` and a word the new screen shows (no \`nodePath\` needed: without one the whole game is searched), 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, 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 |
+| Answer a dialog | \`runtime_input click\` on its button, or \`runtime_input key\` with \`keycode\` \`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\` with the action's name, or \`runtime_input key\` with \`keycode\`, a whole press unless you hold it |
 | Where a 3D node is on screen | \`runtime_inspect\` \`rect\`, rather than unprojecting by hand |
 | Wait for something in a running game | \`runtime_wait\`, never a sleep; \`until\` with \`says\` for a panel that rebuilds its own labels. The words have to be shown: a button that exists hidden through an animation does not satisfy it until it appears, unless \`includeHidden\` says otherwise |
 | What every label on a screen says | \`runtime_inspect tree\` with \`properties\` naming \`text\`, which reads it off every node that has one; \`includeProperties\` is every stored property of every node and ran to seventy-six thousand characters for one row |

package/build/index.js

@@ -10182,6 +10182,8 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import {
   appendFileSync,
   closeSync as closeSync2,
+  constants,
+  copyFileSync,
   existsSync as existsSync10,
   fstatSync,
   mkdirSync as mkdirSync10,
@@ -10194,7 +10196,7 @@ import {
   statSync as statSync7
 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename as basename3, dirname as dirname10, isAbsolute as isAbsolute3, join as join16, normalize as normalize2, relative as relative3 } from "node:path";
+import { basename as basename3, dirname as dirname10, extname as extname2, isAbsolute as isAbsolute3, join as join16, normalize as normalize2, relative as relative3 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { promisify as promisify5 } from "node:util";
@@ -30472,7 +30474,11 @@ var TOOL_SPECS = [
         description: "viewport: the Viewport node. Default the root viewport."
       },
       width: { type: "number", description: "Scale the image to this width." },
-      height: { type: "number", description: "Scale the image to this height." }
+      height: { type: "number", description: "Scale the image to this height." },
+      outputPath: {
+        type: "string",
+        description: "Also save the picture as a PNG at this absolute path, for somebody to open later; the answer says where. Refused unless it ends in .png, its directory exists, it is outside the project, and no file is there already."
+      }
     },
     requires: [],
     operations: {
@@ -30495,7 +30501,7 @@ var TOOL_SPECS = [
       action: {
         type: "string",
         ops: ["action"],
-        description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with key Escape, or click its button."
+        description: "action: the InputMap action name. An engine dialog is not answered this way: AcceptDialog reads the Escape key itself and never asks the InputMap, so ui_cancel goes in and the question stays up. Dismiss one with the key op and keycode Escape, or click its button."
       },
       pressed: {
         type: "boolean",
@@ -30598,7 +30604,11 @@ var TOOL_SPECS = [
         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." },
+      nodePath: {
+        type: "string",
+        ops: ["signal", "until"],
+        description: "signal, until: the node. Needed for a signal and for a property; for says it defaults to /root, the whole screen."
+      },
       signal: { type: "string", ops: ["signal"], description: "signal: the signal name." },
       property: {
         type: "string",
@@ -30609,7 +30619,7 @@ var TOOL_SPECS = [
       says: {
         type: "string",
         ops: ["until"],
-        description: "until: wait for these words to appear anywhere under nodePath instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
+        description: "until: wait for these words to appear anywhere under nodePath, or anywhere in the game when no nodePath is given, instead of for a property, which is how a panel that rebuilds its labels is waited on at all: the labels are named afresh each redraw and the panel is what stays put. Case-insensitive, part of a line, on a node the player can see unless includeHidden says otherwise; a label with a line break is matched with the break in the words, and a backslash followed by n counts as one. Instead of, not as well as: a call carrying this and a property is refused, because they ask about different things and answering one of them silently is how a caller watches a screen believing they are watching a property."
       },
       includeHidden: {
         type: "boolean",
@@ -30631,7 +30641,7 @@ var TOOL_SPECS = [
       },
       until: {
         summary: "wait for a property to read as a value, or for words to appear under a node, and answer with what it found",
-        requires: ["nodePath"]
+        requires: []
       }
     }
   },
@@ -30733,6 +30743,30 @@ var __dirname2 = dirname10(fileURLToPath3(import.meta.url));
 var EDITOR_RESTART_TIMEOUT_MS = 90000;
 var HOLD_PING_MS = 2000;
 var SLOWEST_FRAME_RATE = 20;
+function captureDestinationRefusal(outputPath, projects) {
+  if (/^(res|user):\/\//.test(outputPath)) {
+    return `outputPath ${outputPath} is a Godot path; a capture is saved outside the project, at an absolute path on this machine.`;
+  }
+  if (!isAbsolute3(outputPath)) {
+    return `outputPath ${outputPath} is not absolute; name the whole path, so where it is written does not depend on this server's directory.`;
+  }
+  if (extname2(outputPath).toLowerCase() !== ".png") {
+    return `outputPath ${outputPath} does not end in .png, which is what a capture is.`;
+  }
+  const directory = realPathOr(dirname10(outputPath));
+  if (!existsSync10(directory)) {
+    return `outputPath's directory ${dirname10(outputPath)} does not exist; a capture creates no directories.`;
+  }
+  const where = join16(directory, basename3(outputPath));
+  const inside = projects.find((project) => project !== "" && isWithinRoot(realPathOr(project), where));
+  if (inside !== undefined) {
+    return `outputPath ${outputPath} is inside the project at ${inside}; a capture is saved outside it, so it never becomes part of the game.`;
+  }
+  if (existsSync10(where)) {
+    return `outputPath ${outputPath} already exists; a capture is not written over a file. Name a new one.`;
+  }
+  return null;
+}
 function patienceForFrames(frames, atLeast) {
   return Math.max(atLeast, frames / SLOWEST_FRAME_RATE * 1000 + atLeast);
 }
@@ -34071,7 +34105,7 @@ class GodotServer {
     return `The game this server started (${which}) is still coming up and has not announced its runtime after a wait of ${Math.min(budgetMs, remaining)}ms, so there is nothing to talk to yet. It is still running: ask again in a moment rather than starting another.`;
   }
   async handleRuntimeCommand(command, args, timeoutMs = this.runtimeTimeoutMs()) {
-    const { op: _op, projectPath, pid, ...params } = asParams(args);
+    const { op: _op, projectPath, pid, outputPath, ...params } = asParams(args);
     const waited = typeof pid === "number" ? null : await this.ownRunOnItsWay(typeof projectPath === "string" ? projectPath : this.ownProject, timeoutMs);
     if (waited !== null) {
       return this.createErrorResponse(waited, [
@@ -34098,6 +34132,16 @@ class GodotServer {
       ]);
     }
     const expectsScreenshot = command === "capture_screenshot" || command === "capture_viewport";
+    const saveTo = expectsScreenshot && typeof outputPath === "string" ? outputPath : null;
+    if (saveTo !== null) {
+      const refusal = captureDestinationRefusal(saveTo, [
+        choice.endpoint.project.path,
+        ...this.ownProject === null ? [] : [this.ownProject]
+      ]);
+      if (refusal !== null) {
+        return this.createErrorResponse(refusal);
+      }
+    }
     const screenshotDir = expectsScreenshot ? mkdtempSync2(join16(tmpdir4(), "gdharness-runtime-screenshot-")) : null;
     const screenshotPath = screenshotDir ? join16(screenshotDir, "capture.png") : null;
     try {
@@ -34117,11 +34161,18 @@ class GodotServer {
         return this.createErrorResponse(`Rejected screenshot file path outside the managed capture path: '${returnedPath}'`);
       }
       const dimensions = `${readNumber(payload, "width") ?? 0}x${readNumber(payload, "height") ?? 0} ${readString(payload, "format") ?? "unknown"}`;
+      if (saveTo !== null) {
+        try {
+          copyFileSync(screenshotPath, saveTo, constants.COPYFILE_EXCL);
+        } catch (error) {
+          return this.createErrorResponse(`The capture was taken and could not be saved at ${saveTo}: ${errorMessage(error)}`);
+        }
+      }
       return {
         content: [
           {
             type: "text",
-            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}`
+            text: `Screenshot captured: ${dimensions}${chosenAmongSeveral ? ` from pid ${own}, the game this server holds` : ""}${saveTo === null ? "" : `. Saved to ${saveTo}`}`
           },
           { type: "image", data: readFileSync16(screenshotPath).toString("base64"), mimeType: "image/png" }
         ]
@@ -34168,7 +34219,11 @@ class GodotServer {
       return await this.handleRuntimeCommand("wait_frames", { ...whichGame(args), frames }, waited);
     }
     const timeoutMs = readPositiveNumber(args, "timeoutMs") ?? 5000;
-    const nodePath = readNonEmptyString(args, "nodePath") ?? "";
+    const asked = readNonEmptyString(args, "nodePath");
+    if (asked === undefined && op === "until" && readNonEmptyString(args, "says") === undefined) {
+      return this.createErrorResponse("runtime_wait until needs nodePath to wait for a property: the property belongs to that node.", ["With says instead of property, nodePath can be left out and the whole game is searched"]);
+    }
+    const nodePath = asked ?? "/root";
     const patience = Math.max(this.runtimeTimeoutMs(), timeoutMs + 5000);
     return op === "signal" ? await this.handleRuntimeCommand("wait_signal", {
       ...whichGame(args),

package/package.json

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