@proagentstore/cli 0.4.50 → 0.4.51

package/dist/browser-runner/coding/engine-turn.js

@@ -0,0 +1,55 @@
+/**
+ * How the LAST completed engine turn ended (#545).
+ *
+ * The exit code was already known on this side and spent entirely on prose: `runOneShot`'s close
+ * handler pushed `[codex exited with code 1]` into the transcript and set no field, so a production
+ * Codex session whose every turn exited 1 — three times, the reason printed each time — reported
+ * `alive: true, ready: true, runState: "idle"`, and the Pilot spent fifteen minutes and three BYOK
+ * decisions rediscovering it from the pane.
+ *
+ * OUTCOME AND LIVENESS ARE TWO FACTS, and this module owns only the first. Nothing here touches
+ * `alive`: a one-shot session has no process between turns, a failing turn does not make the
+ * session unable to take another, and conflating the two once killed every delegated goal on
+ * codex/grok/gemini at iteration 0 (see `HeadlessSession.alive`). The failure is REPORTED here;
+ * what to make of one is the cloud's judgement, in `workers/api/src/lib/coding-turn-outcome.ts`.
+ *
+ * Its own module, beside `engine-usage.ts` / `engine-acts.ts` / `engine-auth.ts`, for the reason
+ * they are: the RULE that turns a process exit into a verdict is worth testing without spawning a
+ * process, and it is the part someone will later be tempted to change.
+ */
+/** Longest engine line carried as {@link EngineTurnReport.detail}. The pane holds the rest. */
+export const MAX_TURN_DETAIL = 240;
+/**
+ * A one-shot turn's process has exited — say what that means, and nothing more.
+ *
+ * A SIGNAL outranks the code because a signalled process's code is null and the kill is ours: the
+ * 15-minute wedge ceiling and `interrupt()` both land here, and counting either as an engine
+ * failure would let three slow builds read as a broken CLI.
+ */
+export function turnReportFromExit(code, signal, lastLine = "", now = Date.now()) {
+    const detail = lastLine.trim().slice(0, MAX_TURN_DETAIL);
+    return {
+        verdict: signal !== null ? "killed" : code === 0 ? "ok" : "failed",
+        exitCode: code,
+        signal,
+        at: now,
+        ...(detail ? { detail } : {}),
+    };
+}
+/**
+ * A stream-json turn ended with a `result` event — the structured path's analogue of an exit code.
+ *
+ * Without it the field would exist for three engines and silently not for the flagship, which is
+ * the shape of gap that makes a platform-wide claim ("we notice a failed turn") false in the one
+ * case that runs most.
+ */
+export function turnReportFromResult(isError, detail = "", now = Date.now()) {
+    const text = detail.trim().slice(0, MAX_TURN_DETAIL);
+    return {
+        verdict: isError ? "failed" : "ok",
+        exitCode: null,
+        signal: null,
+        at: now,
+        ...(text ? { detail: text } : {}),
+    };
+}

package/dist/browser-runner/coding/headless.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { classifyCommand, commandFromToolInput, fillTargetFromResult } from "./engine-acts.js";
 import { parseEngineUsage } from "./engine-usage.js";
+import { turnReportFromExit, turnReportFromResult } from "./engine-turn.js";
 /**
  * Merge the platform's resolved engine env over the machine's, where an EMPTY value means
  * REMOVE rather than "set to empty".
@@ -88,6 +89,16 @@ export class HeadlessSession {
     turnStartedAt = 0;
     /** Set by stop() — the only thing that ends a one-shot session (see `alive`). */
     stopped = false;
+    /** How the last COMPLETED turn ended (#545). Null until one has. See {@link EngineTurnReport}. */
+    turnReport = null;
+    /**
+     * The engine's own last output line of the turn in flight (#545).
+     *
+     * Recorded as it is written, so the failure detail is the engine's sentence rather than
+     * something parsed back out of a rendered pane. Reset when a turn starts, so a report can never
+     * carry a previous turn's line.
+     */
+    turnLastLine = "";
     /** Measured engine spend not yet handed to the cloud (#267). Drained by {@link takeUsage}. */
     pendingUsage = [];
     /**
@@ -216,6 +227,15 @@ export class HeadlessSession {
             return !this.stopped && !this.spawnFailed;
         return this.procAlive;
     }
+    /**
+     * How the last completed turn ended (#545) — NOT whether the session can take another.
+     *
+     * Read by the snapshot and carried to the cloud. Null means no turn has completed on this
+     * session; it is never a claim that a turn went well.
+     */
+    get lastTurn() {
+        return this.turnReport;
+    }
     /** Is a process running THIS instant? The persistent engine's liveness, and the spawn guard. */
     get procAlive() {
         return this.proc !== null && this.proc.exitCode === null && this.proc.signalCode === null;
@@ -397,6 +417,9 @@ export class HeadlessSession {
      * preset decides what runs and what it costs; the platform does not need to know the engine.
      */
     runOneShot(text) {
+        // Arm the per-turn line capture BEFORE the spawn, so a report can only ever carry a line
+        // this turn produced (#545).
+        this.turnLastLine = "";
         const proc = spawn(this.cmdBin, [...this.cmdArgs, text], {
             cwd: this.config.workDir,
             env: mergeEnv(process.env, this.config.env),
@@ -450,7 +473,7 @@ export class HeadlessSession {
             }
         }, maxTurnMs);
         ceiling.unref();
-        proc.on("close", (code) => {
+        proc.on("close", (code, signal) => {
             clearTimeout(ceiling); // cleared before the staleness guard: the timer belongs to THIS process
             // A non-zero exit is the engine's own failure (bad flags, not signed in) and the
             // operator needs to see it — silently going idle is how "stdin is not a terminal"
@@ -465,6 +488,14 @@ export class HeadlessSession {
             // kill-tmux.
             if (this.proc !== proc)
                 return;
+            // THE EXIT CODE STOPS BEING ONLY PROSE HERE (#545). Recorded after the staleness guard
+            // on purpose: a turn aborted by its successor (see the kill above) must not overwrite
+            // the report of the turn that replaced it — the loser's outcome is about a turn nobody
+            // is waiting on any more.
+            //
+            // A signal means WE ended it (the wedge ceiling, an interrupt), which is the `killed`
+            // verdict: evidence about this platform's timers, not about the engine's health.
+            this.turnReport = turnReportFromExit(code, signal, this.turnLastLine);
             this.run = "idle";
             this.proc = null;
         });
@@ -536,8 +567,12 @@ export class HeadlessSession {
     /** Raw-engine stdout: strip ANSI control codes and append to the transcript. */
     pushRaw(line) {
         const clean = stripAnsi(line);
-        if (clean.trim())
+        if (clean.trim()) {
             this.push(clean);
+            // The engine's own words, kept for the turn's report (#545) — captured on the way in,
+            // never scraped back out of the rendered pane.
+            this.turnLastLine = clean.trim();
+        }
         if (this.transcript.length > 4000)
             this.transcript = this.transcript.slice(-3000);
     }
@@ -576,8 +611,14 @@ export class HeadlessSession {
                 }
                 break;
             case "result": {
-                if (ev.is_error)
-                    this.push(`[error] ${ev.result ?? ev.subtype ?? "failed"}`);
+                const failure = ev.is_error ? String(ev.result ?? ev.subtype ?? "failed") : "";
+                if (failure)
+                    this.push(`[error] ${failure}`);
+                // The structured path's ANALOGUE of a non-zero exit (#545). Claude has no process
+                // per turn, so `exitCode` is honestly null and the verdict comes from the protocol's
+                // own `is_error` — the same claim, in the words the engine states it in. Without
+                // this the field would exist for three engines and silently not for the flagship.
+                this.turnReport = turnReportFromResult(ev.is_error === true, failure);
                 // The same event that ends the turn also reports what the turn COST (#267). It was
                 // parsed and thrown away, which is why Engine spend was absent from the ledger.
                 // An errored turn still burned tokens, so this is recorded regardless of is_error.

package/dist/browser-runner/coding/runtime.js

@@ -151,6 +151,10 @@ export class CodingRuntime {
             // exactly the question asked about a session that just stopped.
             authResolved: session.authResolved,
             engineRuntime: session.engineRuntime,
+            // Reported on EVERY capture, including one where the session is not alive: "how did the
+            // last turn end" is exactly the question asked about a session that just stopped, and
+            // the omitted-when-null shape keeps "not measured" distinguishable from a verdict.
+            ...(session.lastTurn ? { lastTurn: session.lastTurn } : {}),
             ...(opts.drainUsage ? { usage: session.takeUsage(), acts: session.takeActs() } : {}),
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proagentstore/cli",
-  "version": "0.4.50",
+  "version": "0.4.51",
   "description": "CLI for creating, publishing, and running ProAgentStore agents",
   "license": "MIT",
   "type": "module",