@gaunt-sloth/core 2.0.0-beta.3 → 2.0.0-beta.4

package/dist/core/GthAgentRunner.js

@@ -7,6 +7,8 @@ import { classifyCommand } from '#src/core/shell/arity.js';
 import { describeAbstention } from '#src/core/shell/abstention.js';
 import { normalizeCommand } from '#src/core/shell/normalize.js';
 import { ApprovalStopError, AttackHaltError, NonInteractiveEscalationError, } from '#src/core/shell/approvalStop.js';
+import { attachTerminationReason, classifyThrownTermination, terminationReason, terminationReasonOf, } from '#src/core/terminationReason.js';
+import { terminationLogLine } from '#src/core/terminationNotice.js';
 import { applyDestructiveFloor, effectivePreflightFloorFinding, isBelowDestructiveFloor, isNegotiableCall, isRaterTimeout, mapAllowMatchedVerdictToAction, mapVerdictToAction, openWorldToolFloorReason, preflightFloorFinding, RATER_DEFAULT_TIMEOUT_MS, rateShellCommand, } from '#src/core/shell/rater.js';
 import { RaterHealth } from '#src/core/shell/raterHealth.js';
 import { alignmentApprovalNotice, isAlignmentFailClosed, runAlignmentCheck, } from '#src/core/shell/alignment.js';
@@ -207,6 +209,25 @@ export class GthAgentRunner {
      * {@link getRunStats} before cleanup. Defaults to an empty tally.
      */
     lastRunStats = { tools: [] };
+    /**
+     * [[EXT-159]] — why the current turn ended, as classified by the sites the RUNNER owns (the two
+     * exception wrappers, the approvals re-throws, the empty-response throws, the ordinary end of a
+     * turn). The agent owns the sites inside it and its answer outranks this one; see
+     * {@link getTerminationReason}.
+     */
+    terminationReason = null;
+    /**
+     * [[EXT-159]] — snapshot of the agent's own termination reason, for the same reason
+     * {@link lastRunStats} exists: {@link cleanup} nulls the agent, and the single-shot path reads
+     * the reason afterwards.
+     */
+    agentTerminationReason = null;
+    /**
+     * [[EXT-159]] — snapshot of the agent's per-message `finish_reason` observations, kept for the
+     * same reason {@link agentTerminationReason} is: `/debug-dump` and the non-interactive verbs ask
+     * after {@link cleanup} has already dropped the agent.
+     */
+    agentFinishReasons = [];
     /**
      * CFG-27 — the runtime, session-scoped approvals posture, seeded at {@link init} from
      * {@link resolveApprovals} and thereafter switchable for the session by `/approvals <rung>`.
@@ -813,6 +834,8 @@ export class GthAgentRunner {
         }
         // GS2-16: start this turn's analytics tally from zero (the runner is reused across turns).
         this.resetRunStats();
+        // [[EXT-159]] — the previous turn's termination reason goes with the previous turn's tally.
+        this.resetTerminationReason();
         // GS2-48 — record this turn's transcript tail for the crash handler.
         updateCrashContext({ transcriptTail: messages.slice(-CRASH_TRANSCRIPT_TAIL_MESSAGES) });
         // [[EXT-29]] §5 — a new user turn is the human being reached, so it ends any negotiation still
@@ -845,11 +868,17 @@ export class GthAgentRunner {
                     // CFG-27 — an approvals STOP is not a stream failure: it is the gate deliberately
                     // ending the run, and its message IS the explanation the spec requires it to carry.
                     // Re-thrown unchanged (the outer catch does the same) so nothing buries it.
-                    if (streamError instanceof ApprovalStopError)
+                    if (streamError instanceof ApprovalStopError) {
+                        this.noteApprovalStop('runner.stream-approval-stop', streamError);
                         throw streamError;
+                    }
                     // Handle streaming-specific errors
                     debugLogError('Stream processing', streamError);
-                    throw new Error(`Stream processing failed: ${streamError instanceof Error ? streamError.message : String(streamError)}`);
+                    // [[EXT-159]] — classify the ORIGINAL error, not the wrapper built from it: the wrapper's
+                    // message is where the diagnosis was being thrown away. The one reason is attached to the
+                    // wrapper as well, so a catcher that only ever sees the re-thrown error still reads it.
+                    const reason = this.classifyThrownAt('runner.stream-error', streamError);
+                    throw attachTerminationReason(new Error(`Stream processing failed: ${streamError instanceof Error ? streamError.message : String(streamError)}`), reason);
                 }
                 debugLog(`Stream completed. Total response length: ${result.length}`);
                 // EXT-37: a content-policy refusal (OpenAI content_filter / Anthropic stop_reason=refusal /
@@ -877,10 +906,16 @@ export class GthAgentRunner {
                     const fallback = await this.agent.invoke(messages, this.runConfig);
                     debugLog(`Fallback non-stream response length: ${fallback.length}`);
                     if (fallback.trim().length === 0) {
-                        throw new Error('Model returned an empty response after tool execution. Try again or switch to a more stable model.');
+                        // [[EXT-159]] — the retry has already been spent here, so this is the terminal empty
+                        // turn rather than the first one.
+                        const reason = terminationReason('runner.empty-after-fallback', 'control', 'empty_response');
+                        this.noteTermination(reason);
+                        throw attachTerminationReason(new Error('Model returned an empty response after tool execution. Try again or switch to a more stable model.'), reason);
                     }
+                    this.noteCompleted('runner.completed');
                     return fallback;
                 }
+                this.noteCompleted('runner.completed');
                 return result;
             }
             else {
@@ -897,8 +932,13 @@ export class GthAgentRunner {
                 result += await this.resolveToolInterrupts();
                 debugLog(`Non-stream response length: ${result.length}`);
                 if (result.trim().length === 0) {
-                    throw new Error('Model returned an empty response. Try again or switch to a more stable model.');
+                    // [[EXT-159]] — the non-streaming path has no retry to spend, so an empty turn is
+                    // terminal here at once.
+                    const reason = terminationReason('runner.empty-invoke', 'control', 'empty_response');
+                    this.noteTermination(reason);
+                    throw attachTerminationReason(new Error('Model returned an empty response. Try again or switch to a more stable model.'), reason);
                 }
+                this.noteCompleted('runner.completed');
                 return result;
             }
         }
@@ -907,13 +947,20 @@ export class GthAgentRunner {
             // its own words: the command, the rating and its reason are the whole point of it. Wrapping
             // it as "Agent processing failed: …" would bury the explanation the spec requires it to
             // carry, so it is re-thrown unchanged.
-            if (error instanceof ApprovalStopError)
+            if (error instanceof ApprovalStopError) {
+                this.noteApprovalStop('runner.turn-approval-stop', error);
                 throw error;
+            }
             // Handle agent invocation errors
             debugLogError('Agent processing', error);
+            // [[EXT-159]] — the OUTER of two nested wrappers. On the streaming path the inner one has
+            // already classified this same failure and re-thrown, so `noteTermination`'s first-write-wins
+            // keeps the inner, truer site; on the non-streaming path this is the only classification
+            // there is. Both are reachable, so both classify.
+            const reason = this.classifyThrownAt('runner.turn-error', error);
             const originalMessage = error instanceof Error ? error.message : String(error);
             const enhancedMessage = enhanceVertexUnauthorizedMessage(originalMessage, this.config?.llm);
-            throw new Error(`Agent processing failed: ${enhancedMessage}`, error instanceof Error ? { cause: error } : undefined);
+            throw attachTerminationReason(new Error(`Agent processing failed: ${enhancedMessage}`, error instanceof Error ? { cause: error } : undefined), reason);
         }
         finally {
             // [[TUI-C69]] §5.4 — the turn is over, so the argument is over. The reasoning is the same as
@@ -959,11 +1006,17 @@ export class GthAgentRunner {
         if (!agent.getPendingToolInterrupts || !agent.streamResume)
             return '';
         let resumedText = '';
+        // [[EXT-159]] — which way the loop left decides what ended the turn, and only the loop knows.
+        // Falling out of the bound and draining cleanly are different endings; a caller sees the same
+        // returned string either way, so a caller cannot tell them apart.
+        let drained = false;
         // Bound the loop defensively so a misbehaving graph that re-suspends forever cannot spin.
         for (let guard = 0; guard < 100; guard++) {
             const pending = await agent.getPendingToolInterrupts(runConfig);
-            if (pending.length === 0)
+            if (pending.length === 0) {
+                drained = true;
                 break;
+            }
             const decisions = [];
             for (const tool of pending) {
                 decisions.push(await this.decideToolApproval(tool));
@@ -971,6 +1024,14 @@ export class GthAgentRunner {
             const stream = await agent.streamResume({ decisions }, runConfig);
             resumedText += await this.drainTextStream(stream);
         }
+        // [[EXT-159]] — the runtime gave up, and the turn ends here because of that. It still returns
+        // into `processMessages`, which then reports an ordinary completion (or an empty turn) at its
+        // own site — so routing to an enumerated site is no defence: that site would state a category
+        // that is affirmatively false. Noting it HERE, before those sites run, is what makes
+        // first-write-wins keep the one fact they cannot see.
+        if (!drained) {
+            this.noteTermination(terminationReason('runner.interrupt-guard-exhausted', 'control', 'interrupt_drain_guard'));
+        }
         return resumedText;
     }
     /**
@@ -2629,6 +2690,8 @@ export class GthAgentRunner {
         }
         // GS2-16: start this turn's analytics tally from zero (the runner is reused across turns).
         this.resetRunStats();
+        // [[EXT-159]] — the previous turn's termination reason goes with the previous turn's tally.
+        this.resetTerminationReason();
         // GS2-48 — record this turn's transcript tail for the crash handler.
         updateCrashContext({ transcriptTail: messages.slice(-CRASH_TRANSCRIPT_TAIL_MESSAGES) });
         // [[EXT-29]] §5 — a new user turn is the human being reached, so it ends any negotiation still
@@ -2663,12 +2726,30 @@ export class GthAgentRunner {
             // error result says, and never with the tick and the word `done`, which no arm of this loop
             // could make true.
             const unendedToolCalls = new Set();
+            // [[EXT-159]] — did this turn produce an ANSWER? Grammar member (2), "the model produced
+            // nothing", had two sites on the string path and none here, so an empty typed-event turn —
+            // the node's own motivating symptom, on the surface users actually watch — reported
+            // `completed`, i.e. a legitimate hand-back.
+            //
+            // `text` is the exact analogue of the string path's `result.trim().length === 0`: that path
+            // enqueues only `answerTextOf(chunk.content)`, which drops reasoning segments, and this path
+            // splits the same segments into `text` (answer) and `reasoning_delta` (not the answer). So a
+            // reasoning-only turn is empty on BOTH surfaces, and they cannot disagree about one turn.
+            // Testing each delta rather than the concatenation is equivalent: if every delta is blank
+            // their join is blank, and one non-blank delta makes the join non-blank.
+            //
+            // This is CLASSIFICATION only. The string path's empty-stream retry / `invoke` fallback is
+            // still deliberately not duplicated here (see this method's docblock) — naming what happened
+            // is not fixing it.
+            let sawAnswerText = false;
             const tracking = async function* (source) {
                 for await (const event of source) {
                     if (event.type === 'tool_start')
                         unendedToolCalls.add(event.id);
                     else if (event.type === 'tool_end' || event.type === 'tool_result')
                         unendedToolCalls.delete(event.id);
+                    else if (event.type === 'text' && event.delta.trim().length > 0)
+                        sawAnswerText = true;
                     yield event;
                 }
             };
@@ -2695,6 +2776,33 @@ export class GthAgentRunner {
             for (const id of unendedToolCalls) {
                 yield { type: 'tool_result', id, content: noResult, isError: true };
             }
+            // [[EXT-159]] — the typed-event turn reached its own end. `signal?.aborted` is read again
+            // rather than reused from `noResult` above because a turn can be cancelled with no tool call
+            // outstanding, and that turn owes a reason just as much. First-write-wins keeps whatever the
+            // agent's own sites already said (a refusal, a suspend, an earlier abort).
+            if (signal?.aborted) {
+                this.noteTermination(terminationReason('runner.events-cancelled', 'control', {
+                    category: 'cancelled',
+                    detail: 'signal',
+                }));
+            }
+            else if (!sawAnswerText) {
+                // A turn that ended having said nothing did NOT complete, and saying it did is worse than
+                // saying nothing: this design defines an ABSENT reason as "a site we missed", and a
+                // present-but-false one silences that detector at the one case it was built for.
+                this.noteTermination(terminationReason('runner.events-empty', 'control', 'empty_response'));
+            }
+            else {
+                this.noteCompleted('runner.events-completed');
+            }
+        }
+        catch (error) {
+            // [[EXT-159]] — the typed-event path had NO catch at all, so a provider fault on the surface
+            // most users are looking at was the one termination nothing classified. Re-thrown UNCHANGED:
+            // this site adds a reason and takes nothing away, and the consumer's own error rendering is
+            // not this node's business.
+            this.classifyThrownAt('runner.events-error', error);
+            throw error;
         }
         finally {
             // [[TUI-C69]] §5.4 — **the turn is over, so the argument is over.** Until this existed the
@@ -2709,6 +2817,12 @@ export class GthAgentRunner {
             // In `finally` because an abort and a thrown stream end the turn just as much as a return
             // does, and those are the paths where rows left standing are least likely to be noticed.
             this.clearNegotiationDisplay();
+            // [[EXT-159]] — the one ending that reaches NEITHER the end of the try NOR the catch: a
+            // consumer that stops consuming (breaking out of its `for await`, or calling `return()` on
+            // this generator). Nothing was wrong with the run and nothing failed, so no other site can
+            // speak for it, and without this the turn would end with no reason at all — the state that
+            // must mean "a site we missed".
+            this.noteTermination(terminationReason('runner.events-abandoned', 'control', 'abandoned'));
         }
     }
     /**
@@ -2736,19 +2850,29 @@ export class GthAgentRunner {
             return;
         if (!agent.getPendingToolInterrupts || !agent.streamWithEventsResume)
             return;
+        // [[EXT-159]] — see {@link resolveToolInterrupts}: which way the loop left is the fact that
+        // distinguishes this ending, and it is discarded unless the loop itself records it. An abort
+        // `return`s below and never reaches the note, which is right — a cancelled turn was stopped by
+        // the user, not by this bound.
+        let drained = false;
         // Bound the loop defensively so a misbehaving graph that re-suspends forever cannot spin.
         for (let guard = 0; guard < 100; guard++) {
             if (signal?.aborted)
                 return;
             const pending = await agent.getPendingToolInterrupts(runConfig);
-            if (pending.length === 0)
+            if (pending.length === 0) {
+                drained = true;
                 break;
+            }
             const decisions = [];
             for (const tool of pending) {
                 decisions.push(await this.decideToolApproval(tool));
             }
             yield* agent.streamWithEventsResume({ decisions }, runConfig, [], signal);
         }
+        if (!drained) {
+            this.noteTermination(terminationReason('runner.events-interrupt-guard-exhausted', 'control', 'interrupt_drain_guard'));
+        }
     }
     // noinspection JSUnusedGlobalSymbols
     getAgent() {
@@ -2768,6 +2892,133 @@ export class GthAgentRunner {
             /* fail-soft: analytics must never affect a run */
         }
     }
+    /**
+     * [[EXT-159]] — forget the previous turn's termination reason, on both this runner and the live
+     * agent, so a new turn starts with none. Called at the top of each `processMessages` /
+     * `processMessagesWithEvents`, alongside {@link resetRunStats}. Fail-soft.
+     */
+    resetTerminationReason() {
+        this.terminationReason = null;
+        this.agentTerminationReason = null;
+        this.agentFinishReasons = [];
+        try {
+            this.agent?.resetTerminationReason?.();
+        }
+        catch {
+            /* fail-soft: classification must never affect a run */
+        }
+    }
+    /**
+     * [[EXT-159]] — record why the turn ended, **first-write-wins**.
+     *
+     * The runner's two exception wrappers are NESTED, not alternatives: a stream fault is classified
+     * at the inner one, re-thrown, and caught again by the outer one. Under last-write-wins the outer
+     * site would overwrite the inner classification on every streamed failure — the funnel this
+     * taxonomy replaces, rebuilt one level up.
+     */
+    noteTermination(reason) {
+        try {
+            if (this.terminationReason)
+                return;
+            this.terminationReason = reason;
+            // [[EXT-159]] — the debug log carried the wrapped error string and never the classification.
+            // Written at the decision so it survives a session whose surface never got to ask, and so a
+            // dump taken after a kill still holds it (the ring buffer behind `debugLog` is always on).
+            debugLog(terminationLogLine(reason));
+        }
+        catch {
+            /* fail-soft */
+        }
+    }
+    /**
+     * [[EXT-159]] — classify a thrown value at a runner site: record it here AND attach it to the
+     * error, then hand the error back so the throw reads as one expression.
+     *
+     * Both carriers matter. The runner's own field serves a caller holding the runner; the attached
+     * value serves every layer above that only ever sees the error — and neither is the message, so
+     * no user-facing string is the only carrier of the classification.
+     */
+    classifyThrownAt(site, error) {
+        // A reason already on the error was attached by an INNER site that saw the failure first, and
+        // that one is the truer classification — so it is inherited rather than replaced, and the two
+        // carriers cannot end up disagreeing about the same failure.
+        const existing = terminationReasonOf(error);
+        const reason = existing ?? terminationReason(site, 'exception', classifyThrownTermination(error));
+        this.noteTermination(reason);
+        if (!existing)
+            attachTerminationReason(error, reason);
+        return reason;
+    }
+    /**
+     * [[EXT-159]] — classify an approvals stop, which the generic classifier cannot see.
+     *
+     * The gate's errors are typed by their own subclass names, and their prose is the explanation
+     * rather than a diagnosis, so nothing in the exception classifier's grammar recognises one. It
+     * does not need to: this site reaches an `instanceof ApprovalStopError` branch, so it *knows*
+     * what ended the run, and stating the category is more honest than pattern-matching for it.
+     */
+    noteApprovalStop(site, error) {
+        const reason = terminationReason(site, 'control', {
+            category: 'approval_stop',
+            detail: error instanceof Error ? error.name : undefined,
+        });
+        this.noteTermination(reason);
+        attachTerminationReason(error, reason);
+    }
+    /**
+     * [[EXT-159]] — record that the turn ended because the model finished.
+     *
+     * An ordinary completion is a termination too, and recording it is what makes "no reason" mean
+     * *a site nobody classified* rather than *nothing went wrong*. First-write-wins keeps a deeper
+     * site's answer — a refusal or a truncation is what really ended a turn that also returned text.
+     */
+    noteCompleted(site) {
+        this.noteTermination(terminationReason(site, 'control', 'completed'));
+    }
+    /**
+     * [[EXT-159]] — why the just-finished turn ended, or `null` when nothing classified it.
+     *
+     * The agent's answer wins when it has one: its sites (the metadata reader, the cancellation and
+     * suspend paths, the run-ending middlewares) sit INSIDE the runner's catches, so the innermost
+     * classification is the true one. Never throws.
+     */
+    getTerminationReason() {
+        return this.captureAgentTerminationReason() ?? this.terminationReason;
+    }
+    /** [[EXT-159]] — read the live agent's reason into the snapshot (fail-soft). */
+    captureAgentTerminationReason() {
+        try {
+            const reason = this.agent?.getTerminationReason?.();
+            if (reason)
+                this.agentTerminationReason = reason;
+        }
+        catch {
+            /* fail-soft */
+        }
+        return this.agentTerminationReason;
+    }
+    /**
+     * [[EXT-159]] — what the provider said about why each model message stopped, this turn.
+     *
+     * Reads live from the agent while one is present and falls back to the {@link cleanup} snapshot
+     * afterwards, the same way {@link getRunStats} does — `/debug-dump` on the readline surface and
+     * the non-interactive verbs both ask once the agent has been dropped.
+     */
+    getFinishReasonObservations() {
+        return this.captureFinishReasonObservations();
+    }
+    /** [[EXT-159]] — read the live agent's finish-reason observations into the snapshot (fail-soft). */
+    captureFinishReasonObservations() {
+        try {
+            const observed = this.agent?.getFinishReasonObservations?.();
+            if (observed)
+                this.agentFinishReasons = observed;
+        }
+        catch {
+            /* fail-soft */
+        }
+        return this.agentFinishReasons;
+    }
     /** GS2-16 — read the live agent's run stats (fail-soft; empty tally if unavailable). */
     captureRunStats() {
         try {
@@ -2819,6 +3070,12 @@ export class GthAgentRunner {
         // GS2-16: snapshot the agent's run stats BEFORE nulling it, so a post-cleanup reader
         // (runSingleShot records history after calling cleanup) still gets this turn's analytics.
         this.lastRunStats = this.captureRunStats();
+        // [[EXT-159]] — and the agent's termination reason with it, for the same reason: the
+        // single-shot path asks why the run ended after the agent has already been nulled.
+        this.captureAgentTerminationReason();
+        // [[EXT-159]] — likewise the provider's per-message finish reasons, which `/debug-dump` and the
+        // non-interactive verbs read post-cleanup.
+        this.captureFinishReasonObservations();
         if (this.agent && 'cleanup' in this.agent && typeof this.agent.cleanup === 'function') {
             await this.agent.cleanup();
         }