gdharness 0.12.4 → 0.12.6

package/README.md

@@ -15,10 +15,15 @@
 [![Bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FAureliolo%2Fgdharness%2Fmain%2Fpackage.json&query=%24.engines.bun&label=bun&color=f9f1e1&logo=bun&logoColor=black)](https://bun.sh/)
 [![Licence](https://img.shields.io/github/license/Aureliolo/gdharness)](LICENSE)
 
-Drive a Godot 4 project from an agent: the editor that is open, the game that is running, and the
-project on disk.
+**An agent cannot see a running game.** It reads your scripts and guesses at the rest: whether the
+button is on screen, whether the panel updated, whether that error mattered.
 
-**Hand this to your agent:**
+gdharness makes the engine answerable instead. What the screen says, where a control is, what a
+property reads right now, what the console printed, what broke and on which line.
+
+## Install
+
+Hand this to your agent:
 
 ```text
 Install gdharness into this project by following
@@ -27,31 +32,39 @@ recommend back to me.
 ```
 
 Or do it yourself, and pick your harness:
-[aureliolo.github.io/gdharness](https://aureliolo.github.io/gdharness)
+[aureliolo.github.io/gdharness](https://aureliolo.github.io/gdharness).
 
-## What it is for
-
-An agent cannot see a running game. This makes one answerable: where a control is, what a property
-reads, what the console printed, what broke and on which line.
+## The loop it exists for
 
 ```jsonc
-runtime_inspect { "op": "rect", "nodePath": "/root/Hall/Ledger/BuyButton" }
-
-{ "canvas": { "position": { "x": 812, "y": 418 }, "size": { "x": 180, "y": 34 } },
-  "visible": true }
+editor_run      { "op": "start", "projectPath": "C:/games/hall" }
+runtime_inspect { "op": "find", "says": "Buy" }              // the button, by the word on it
+runtime_input   { "op": "click", "nodePath": "/root/Hall/Ledger/BuyButton" }
+runtime_inspect { "op": "text", "nodePath": "/root/Hall/Ledger" }   // what the panel says now
+editor_output   { "projectPath": "C:/games/hall" }           // errors and warnings, with backtraces
 ```
 
+The open editor plays the game, so its debugger holds it, which is what lets you set a breakpoint
+and read the variables in scope when it stops.
+
+Every answer is read back out of the engine after the fact, never echoed from the request. A tool
+that cannot answer says which state it is in and what would change it, rather than answering
+emptily, so a call that succeeded is a call that was understood.
+
 ## At a glance
 
-|           |                                                                          |
-| --------- | ------------------------------------------------------------------------ |
-| Needs     | Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.            |
-| Surface   | 30 tools named `domain_verb`, and 4 `godot://` resources                 |
-| Reaches   | The editor that is open, a game it is playing, and the project on disk   |
-| Harnesses | 35, written inside the project wherever the harness has a project config |
-| Skill     | Written to `.agents/skills`, which every major harness reads             |
-| Install   | npm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3       |
-| Proven    | Every tool driven against a pinned Godot in CI, on three platforms       |
+|           |                                                                                  |
+| --------- | -------------------------------------------------------------------------------- |
+| Needs     | Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.                    |
+| Surface   | 30 tools named `domain_verb`, and 4 `godot://` resources                         |
+| Reaches   | The editor that is open, a game it is playing, and the project on disk           |
+| Harnesses | 35, written inside the project wherever the harness has a project config         |
+| Skill     | Written to `.agents/skills`, which every major harness reads                     |
+| Install   | npm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3               |
+| Proven    | Every tool driven against Godot 4.7.2 in CI, on Windows, Linux and macOS         |
+| Status    | 0.x: pin an exact version. [What a bump means](.github/CONTRIBUTING.md#versions) |
+
+Older 4.x is likely to work and is not tested.
 
 ## Documentation
 
@@ -61,30 +74,6 @@ parts connect, and every tool, op and argument.
 [SECURITY.md](.github/SECURITY.md) is how to report something.
 [CONTRIBUTING.md](.github/CONTRIBUTING.md) is what a change has to clear.
 
-## Versions
-
-0.x, and the number is telling the truth: the tools, their arguments and the shape of their
-answers are still moving, because the projects using this keep finding answers that were wrong or
-missing. Pin an exact version and upgrade deliberately.
-
-Built and measured against Godot 4.7.2 on Windows, Linux and macOS. The editor, engine, runtime
-and integration suites run against a real engine on all three before anything is tagged. Older
-4.x is likely to work and is not tested.
-
-What each kind of release means here:
-
-- **Patch**: nearly everything. An answer that was wrong is now right, and the output may change
-  shape for it, because a wrong answer corrected is a fix rather than a feature and leaving one
-  wrong to protect whoever parsed it is how a tool stops being worth asking. An addition nothing
-  has to adapt to is a patch too: a new argument, a new field, an argument reaching further than it
-  did. Ignore all of it and your calls still work.
-- **Minor**: a new tool or a new op, meaning this does something it could not do before.
-- **Major**: a tool, an op, an argument or a field was renamed or taken away. Nothing else earns
-  one.
-
-1.0 is not a date, it is a condition: the tool surface holding still for a fortnight, and the
-issues arriving being things it cannot do yet rather than things it answers wrongly.
-
 ## Project
 
 Fork of [GoPeak](https://github.com/HaD0Yun/Doyunha-Gopeak) v2.3.9, September 2026, MIT: the

package/build/cli.js

@@ -15729,7 +15729,7 @@ var init_tool_definitions = __esm(() => {
     },
     {
       name: "editor_output",
-      description: "What the project started by editor_run has printed, as entries with a severity: the errors and warnings the engine reported, each with where it happened, and everything else as info. Answers with the counts and the verdict as well as the entries. A run that has quit still answers here, with running false and its exit code, until the next one starts. A run this server started also answers with transcript, the file both its streams are written to: uncapped, written while the run is going, and the thing to read or tail for a long run rather than the engine's own log, which every engine start rotates away.",
+      description: "What the project started by editor_run has printed, as entries with a severity: the errors and warnings the engine reported, each with where it happened, and everything else as info. Answers with the counts and the verdict as well as the entries. A run that has quit still answers here, with running false and its exit code, until the next one starts. A run this server started also answers with transcript, the file both its streams are written to: uncapped, written while the run is going, and the thing to read or tail for a long run rather than the engine's own log, which every engine start rotates away. Read the file for output and this answer for state: running is asked of the operating system, endedBy says whether gdharness ended the run, and a transcript that has stopped growing is a run between prints rather than a run that is over.",
       parameters: {
         severity: {
           type: "string",
@@ -38152,7 +38152,7 @@ class GodotServer {
       notes.push("Nothing here ended this run: it stopped on its own or something outside this server stopped it.");
     }
     if (run.transcript !== null && selected.omitted > 0) {
-      notes.push(`Everything this run has printed is in ${run.transcript}, uncapped and still being written.`);
+      notes.push(`Everything this run has printed is in ${run.transcript}, uncapped and still being written. Read it for output, not for whether the run is alive: running above is asked of the operating system, and a transcript that stops growing is a run between prints.`);
     }
     return this.jsonTextResponse({
       running: stillRunning(run),
@@ -39829,7 +39829,10 @@ that is running, and the project on disk. ${TOOL_SPECS.length} tools, named \`do
   false is a runtime that is not coming and true is a game still on its way up.
 - Read \`editor_output\` after every run. It returns the engine's errors and warnings as entries
   with their backtraces, and a \`clean\` verdict, so a run that printed an error is one call away
-  from being known.
+  from being known. For a long run it also names a transcript file: read that for output and this
+  answer for state. Never decide a run has ended by watching the file stop growing, or a process
+  list, or a timeout. \`running\` is asked of the operating system and \`endedBy\` says whether
+  gdharness ended it; a bench between prints looks exactly like a bench that died to everything else.
 - One server, one editor. A second project is a second harness session with its own server, and
   that works: each editor is opened on its own language server and debug adapter ports, and says
   where it serves. Two editors on one project is the thing to refuse.

package/build/index.js

@@ -28600,7 +28600,7 @@ var TOOL_SPECS = [
   },
   {
     name: "editor_output",
-    description: "What the project started by editor_run has printed, as entries with a severity: the errors and warnings the engine reported, each with where it happened, and everything else as info. Answers with the counts and the verdict as well as the entries. A run that has quit still answers here, with running false and its exit code, until the next one starts. A run this server started also answers with transcript, the file both its streams are written to: uncapped, written while the run is going, and the thing to read or tail for a long run rather than the engine's own log, which every engine start rotates away.",
+    description: "What the project started by editor_run has printed, as entries with a severity: the errors and warnings the engine reported, each with where it happened, and everything else as info. Answers with the counts and the verdict as well as the entries. A run that has quit still answers here, with running false and its exit code, until the next one starts. A run this server started also answers with transcript, the file both its streams are written to: uncapped, written while the run is going, and the thing to read or tail for a long run rather than the engine's own log, which every engine start rotates away. Read the file for output and this answer for state: running is asked of the operating system, endedBy says whether gdharness ended the run, and a transcript that has stopped growing is a run between prints rather than a run that is over.",
     parameters: {
       severity: {
         type: "string",
@@ -30934,7 +30934,7 @@ class GodotServer {
       notes.push("Nothing here ended this run: it stopped on its own or something outside this server stopped it.");
     }
     if (run.transcript !== null && selected.omitted > 0) {
-      notes.push(`Everything this run has printed is in ${run.transcript}, uncapped and still being written.`);
+      notes.push(`Everything this run has printed is in ${run.transcript}, uncapped and still being written. Read it for output, not for whether the run is alive: running above is asked of the operating system, and a transcript that stops growing is a run between prints.`);
     }
     return this.jsonTextResponse({
       running: stillRunning(run),

package/package.json

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