gdharness 1.0.14 → 1.0.16

package/build/cli.js

@@ -7187,6 +7187,19 @@ function alongside(execPath, name) {
 }
 var init_runner = () => {};
 
+// src/call-signal.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+function withCallSignal(signal, answer) {
+  return signal === undefined ? answer() : current.run(signal, answer);
+}
+function callSignal() {
+  return current.getStore();
+}
+var current;
+var init_call_signal = __esm(() => {
+  current = new AsyncLocalStorage;
+});
+
 // src/dictionary.ts
 function emptyRecord() {
   return Object.create(null);
@@ -7781,14 +7794,7 @@ function reason2(stdout, stderr) {
 async function runImport(godotPath, projectPath) {
   const logDir = mkdtempSync2(join7(tmpdir3(), "gdharness-import-"));
   try {
-    const { stderr } = await run3(godotPath, [
-      "--headless",
-      "--log-file",
-      join7(logDir, "engine.log"),
-      "--path",
-      projectPath,
-      "--import"
-    ]);
+    const { stderr } = await run3(godotPath, ["--headless", "--log-file", join7(logDir, "engine.log"), "--path", projectPath, "--import"], { signal: callSignal() });
     return { ok: true, messages: problems2(stderr) };
   } catch (error) {
     if (error instanceof Error && "stdout" in error && "stderr" in error) {
@@ -7827,7 +7833,7 @@ async function runOperation2(engine, operation, params, projectPath) {
   let stdout;
   let stderr;
   try {
-    ({ stdout, stderr } = await run3(engine.godotPath, args));
+    ({ stdout, stderr } = await run3(engine.godotPath, args, { signal: callSignal() }));
   } catch (error) {
     if (error instanceof Error && "stdout" in error && "stderr" in error) {
       const failed = error;
@@ -7857,6 +7863,7 @@ async function runOperation2(engine, operation, params, projectPath) {
 }
 var run3;
 var init_headless = __esm(() => {
+  init_call_signal();
   init_game_log();
   init_scratch();
   run3 = promisify3(execFile3);
@@ -16398,7 +16405,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 +16432,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 +16535,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 +16550,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 +16572,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 +38040,8 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import {
   appendFileSync,
   closeSync as closeSync2,
+  constants,
+  copyFileSync,
   existsSync as existsSync15,
   fstatSync,
   mkdirSync as mkdirSync13,
@@ -38037,10 +38054,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);
 }
@@ -38557,7 +38598,7 @@ class GodotServer {
   }
   setupToolHandlers() {
     this.mcp.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: this.tools }));
-    this.mcp.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    this.mcp.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
       this.logDebug(`Handling tool request: ${request.params.name}`);
       const spec = toolSpec(request.params.name);
       if (!spec) {
@@ -38572,7 +38613,7 @@ class GodotServer {
         this.lastProjectPath = args["projectPath"];
       }
       this.updates.refresh();
-      const answer = await this.answered(spec.name, checked.op ?? "", args);
+      const answer = await withCallSignal(extra.signal, () => this.answered(spec.name, checked.op ?? "", args));
       return this.withFeedbackNotice(this.withUpdateNotice(answer));
     });
   }
@@ -39343,7 +39384,10 @@ class GodotServer {
     const log = new GameLog;
     let exitCode = 0;
     try {
-      const { stdout, stderr } = await run7(engine.value, exportArgs, { timeout: 300000 });
+      const { stdout, stderr } = await run7(engine.value, exportArgs, {
+        timeout: 300000,
+        signal: callSignal()
+      });
       log.append("stdout", stdout);
       log.append("stderr", stderr);
     } catch (error) {
@@ -40359,6 +40403,23 @@ class GodotServer {
   }
   spawnGame(godotPath, cmdArgs, env) {
     const child = spawn(godotPath, cmdArgs, { stdio: ["ignore", "pipe", "pipe"], ...env ? { env } : {} });
+    const cancelled = callSignal();
+    if (cancelled !== undefined) {
+      const end = () => {
+        if (child.exitCode === null && child.signalCode === null) {
+          this.logDebug(`The call waiting on pid ${child.pid ?? "unknown"} was cancelled; ending it.`);
+          child.kill();
+        }
+      };
+      if (cancelled.aborted) {
+        end();
+      } else {
+        cancelled.addEventListener("abort", end, { once: true });
+        child.once("exit", () => {
+          cancelled.removeEventListener("abort", end);
+        });
+      }
+    }
     const log = new GameLog;
     const started = {
       process: child,
@@ -41333,7 +41394,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 +41421,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 +41450,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 +41508,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),
@@ -41460,6 +41542,7 @@ var init_server3 = __esm(() => {
   init_boot_note();
   init_breakpoint_note();
   init_bridge_announce();
+  init_call_signal();
   init_class_cache();
   init_class_note();
   init_config_pin();
@@ -42468,6 +42551,7 @@ function taken(harness, path, held, stripped) {
 }
 
 // src/headless.ts
+init_call_signal();
 init_game_log();
 init_scratch();
 import { execFile as execFile2 } from "node:child_process";
@@ -42532,7 +42616,7 @@ async function runOperation(engine, operation, params, projectPath) {
   let stdout;
   let stderr;
   try {
-    ({ stdout, stderr } = await run2(engine.godotPath, args));
+    ({ stdout, stderr } = await run2(engine.godotPath, args, { signal: callSignal() }));
   } catch (error) {
     if (error instanceof Error && "stdout" in error && "stderr" in error) {
       const failed = error;
@@ -43098,12 +43182,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";
@@ -25728,6 +25730,16 @@ function withdrawBridge(path) {
   }
 }
 
+// src/call-signal.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var current = new AsyncLocalStorage;
+function withCallSignal(signal, answer) {
+  return signal === undefined ? answer() : current.run(signal, answer);
+}
+function callSignal() {
+  return current.getStore();
+}
+
 // src/class-cache.ts
 import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync7, statSync as statSync2 } from "node:fs";
 import { join as join6 } from "node:path";
@@ -27752,14 +27764,7 @@ function reason(stdout, stderr) {
 async function runImport(godotPath, projectPath) {
   const logDir = mkdtempSync(join11(tmpdir3(), "gdharness-import-"));
   try {
-    const { stderr } = await run3(godotPath, [
-      "--headless",
-      "--log-file",
-      join11(logDir, "engine.log"),
-      "--path",
-      projectPath,
-      "--import"
-    ]);
+    const { stderr } = await run3(godotPath, ["--headless", "--log-file", join11(logDir, "engine.log"), "--path", projectPath, "--import"], { signal: callSignal() });
     return { ok: true, messages: problems(stderr) };
   } catch (error) {
     if (error instanceof Error && "stdout" in error && "stderr" in error) {
@@ -27798,7 +27803,7 @@ async function runOperation(engine, operation, params, projectPath) {
   let stdout;
   let stderr;
   try {
-    ({ stdout, stderr } = await run3(engine.godotPath, args));
+    ({ stdout, stderr } = await run3(engine.godotPath, args, { signal: callSignal() }));
   } catch (error) {
     if (error instanceof Error && "stdout" in error && "stderr" in error) {
       const failed = error;
@@ -30472,7 +30477,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 +30504,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 +30607,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 +30622,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 +30644,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 +30746,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);
 }
@@ -31295,7 +31332,7 @@ class GodotServer {
   }
   setupToolHandlers() {
     this.mcp.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: this.tools }));
-    this.mcp.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    this.mcp.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
       this.logDebug(`Handling tool request: ${request.params.name}`);
       const spec = toolSpec(request.params.name);
       if (!spec) {
@@ -31310,7 +31347,7 @@ class GodotServer {
         this.lastProjectPath = args["projectPath"];
       }
       this.updates.refresh();
-      const answer = await this.answered(spec.name, checked.op ?? "", args);
+      const answer = await withCallSignal(extra.signal, () => this.answered(spec.name, checked.op ?? "", args));
       return this.withFeedbackNotice(this.withUpdateNotice(answer));
     });
   }
@@ -32081,7 +32118,10 @@ class GodotServer {
     const log = new GameLog;
     let exitCode = 0;
     try {
-      const { stdout, stderr } = await run5(engine.value, exportArgs, { timeout: 300000 });
+      const { stdout, stderr } = await run5(engine.value, exportArgs, {
+        timeout: 300000,
+        signal: callSignal()
+      });
       log.append("stdout", stdout);
       log.append("stderr", stderr);
     } catch (error) {
@@ -33097,6 +33137,23 @@ class GodotServer {
   }
   spawnGame(godotPath, cmdArgs, env) {
     const child = spawn(godotPath, cmdArgs, { stdio: ["ignore", "pipe", "pipe"], ...env ? { env } : {} });
+    const cancelled = callSignal();
+    if (cancelled !== undefined) {
+      const end = () => {
+        if (child.exitCode === null && child.signalCode === null) {
+          this.logDebug(`The call waiting on pid ${child.pid ?? "unknown"} was cancelled; ending it.`);
+          child.kill();
+        }
+      };
+      if (cancelled.aborted) {
+        end();
+      } else {
+        cancelled.addEventListener("abort", end, { once: true });
+        child.once("exit", () => {
+          cancelled.removeEventListener("abort", end);
+        });
+      }
+    }
     const log = new GameLog;
     const started = {
       process: child,
@@ -34071,7 +34128,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 +34155,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 +34184,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 +34242,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.16",
   "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",