@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/exec/runner.js

@@ -17,17 +17,24 @@
 import { formatStreamError } from '../agent/reducer.js';
 import { setSignalTerminator } from '../logging/install.js';
 import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
-import { EXEC_SCHEMA_VERSION } from './events.js';
+import { EXEC_SCHEMA_VERSION, buildRequestEndEvent } from './events.js';
 import { ExecProgressReporter } from './progress-reporter.js';
+import { REQUEST_LIMITS } from './request/limits.js';
+import { createRequestScope } from './request/scope.js';
+import { RESULT_LIMITS } from './result/limits.js';
+import { buildResultRepairMessage } from './result/prompt.js';
 export function singlePrompt(text) {
     let served = false;
+    let last;
     return {
         next: async () => {
             if (served)
                 return null;
             served = true;
+            last = { text };
             return text;
         },
+        lastPrompt: () => last,
     };
 }
 const DEFAULT_SIGNAL_PORT = {
@@ -44,6 +51,11 @@ export class ExecRunner {
     now;
     progress;
     controller = null;
+    /** Set by `attachBridge`; absent in every non-bridge run (I-1). */
+    bridge = null;
+    bridgeSource = null;
+    /** The caller's id for the turn currently running, if there is one. */
+    requestId;
     unsubscribers = [];
     /** Per-job progress throttle state: the last text emitted, and when. */
     jobProgressAt = new Map();
@@ -60,10 +72,45 @@ export class ExecRunner {
     errorMessage = null;
     signalNumber = null;
     thinkingBuffer = '';
+    /**
+     * An injection that has been queued but whose acceptance has not been observed.
+     *
+     * ITS ONLY JOB IS TO MAKE I-H12 TRUE: a `turn_start` injection queued for a request that
+     * then fails to start must be REPORTED, not silently left in the steering queue where the
+     * next request's loop top would push it into history.
+     */
+    pendingInjection = null;
+    /**
+     * How many `steering_accepted` receipts have arrived.
+     *
+     * IT EXISTS TO CLOSE A ONE-TURN RACE: a stub (or a very fast engine) can confirm the
+     * injection INSIDE `queueUserMessage`, in which case setting the pending marker afterwards
+     * would leave a stale one and report a healthy injection as stranded.
+     */
+    steeringReceipts = 0;
     budgetTimer = null;
     timerStarted = false;
     detached = false;
     lastSignalAt = 0;
+    /**
+     * The one owner of every request-level fact (section 2.4.3).
+     *
+     * CREATED UNCONDITIONALLY, even outside bridge mode, and that is a deliberate
+     * departure from the design's "only in bridge mode" (implementation note): the
+     * acceptance latch and the per-request reset have to exist for a single-request run
+     * too, or `checkResultComplete` would need a second latch of its own - and two
+     * latches for one fact is how "the second request never stops" happens. It emits
+     * nothing and starts no timer unless a request budget was configured, so a
+     * non-bridge run is byte-identical.
+     */
+    requestScope;
+    /** True between the request's `ack` and its `request_end`. */
+    requestInFlight = false;
+    /** Repair continuations used by the request in flight. */
+    repairsUsed = 0;
+    resultUnsatisfied = false;
+    /** The last value any request accepted, for the process-level `result` event. */
+    lastStructured;
     constructor(options) {
         this.emitter = options.emitter;
         this.sessionId = options.sessionId;
@@ -71,6 +118,30 @@ export class ExecRunner {
         this.signals = options.signals ?? DEFAULT_SIGNAL_PORT;
         this.now = options.now ?? Date.now;
         this.progress = new ExecProgressReporter(this.sessionId, (event) => this.emit(event));
+        this.requestScope = createRequestScope({
+            ...(options.requestMaxTurns !== undefined ? { maxTurns: options.requestMaxTurns } : {}),
+            ...(options.requestMaxDurationMs !== undefined
+                ? { maxDurationMs: options.requestMaxDurationMs }
+                : {}),
+            now: this.now,
+            // THE TIMER'S ONLY ACTION. It arrives with the generation it was armed under, so
+            // a callback that lost the race with `end()` cannot reach this line at all.
+            onDurationExpired: () => {
+                this.requestScope.cancel('timeout');
+                this.bridge?.abortInFlight();
+                this.controller?.abort();
+            },
+            totals: () => ({
+                usage: { inputTokens: this.usage.inputTokens, outputTokens: this.usage.outputTokens },
+                cost: this.costOf(this.usage, this.compactionBilling),
+            }),
+        });
+    }
+    /** `buildCost` when the composition root supplied it; zero-and-unknown otherwise. */
+    costOf(usage, compaction) {
+        if (this.opts.cost)
+            return this.opts.cost(usage, compaction);
+        return { amount: 0, currency: 'USD', known: false };
     }
     // -----------------------------------------------------------------------
     // Attach / detach
@@ -245,7 +316,186 @@ export class ExecRunner {
         const proc = controller.subscribeProc?.((event) => this.onProcEvent(event));
         if (proc)
             this.unsubscribers.push(proc);
-        this.installTerminator();
+        // THREAD MODE INSTALLS ITS OWN (section 2.3.8a). One terminator per PROCESS, owned by
+        // `exec/threads/interrupt.ts`; a runner that installed a second one would silently
+        // replace it and Ctrl-C would stop exactly one tenant.
+        if (this.opts.installSignalTerminator !== false)
+            this.installTerminator();
+    }
+    /**
+     * Wire the protocol channel. Called AFTER `attach(controller)`, never before:
+     * the turn ports below reach the controller.
+     *
+     * THREE LINES OF STATE AND ONE INSTALLATION, so that everything bridge-shaped in
+     * this file is reachable from one place. `steer` and `interrupt` belong here
+     * rather than in the server because they need the RUNNER's idea of what is in
+     * flight - and routing them through the server keeps the source's frame router
+     * a pure demultiplexer.
+     */
+    attachBridge(server, source) {
+        this.bridge = server;
+        this.bridgeSource = source ?? null;
+        server.attachTurnPorts({
+            steer: (text, id) => this.onSteerFrame(text, id),
+            interrupt: (requestId, id) => this.onInterruptFrame(requestId, id),
+            // EXACTLY THE SHAPE OF `interrupt`, AND DELIBERATELY NOT THE SAME MEANING:
+            // `interrupt` stops the RUN, `cancelRequest` stops ONE REQUEST and leaves the
+            // process serving the next one (section 2.4.7).
+            cancelRequest: (requestId, id) => this.cancelRequest(requestId, id),
+        });
+    }
+    /**
+     * `steer` over the wire.
+     *
+     * THE CHECK AND THE CALL ARE SEPARATE, AND BOTH ARE NEEDED: `queueUserMessage()`
+     * throws when the agent is not running, and "it was running when I looked" is
+     * not the same claim as "it accepted the message". Both failures map to the same
+     * receipt, because a caller cannot act on the difference and a lie ("accepted")
+     * would make it wait for text that never enters the conversation.
+     */
+    onSteerFrame(text, id) {
+        const receipt = (extra) => {
+            this.writeToBridge({ type: 'ack', ...(id ? { id } : {}), ...extra });
+        };
+        if (this.controller?.isRunning?.() !== true) {
+            receipt({ accepted: false, code: 'not_running' });
+            return;
+        }
+        try {
+            const queueUserMessage = this.controller.queueUserMessage;
+            if (!queueUserMessage) {
+                receipt({ accepted: false, code: 'not_running' });
+                return;
+            }
+            const steeringId = queueUserMessage.call(this.controller, text);
+            receipt({ accepted: true, ...(steeringId ? { steeringId } : {}) });
+        }
+        catch {
+            receipt({ accepted: false, code: 'not_running' });
+        }
+    }
+    /**
+     * `interrupt` over the wire, and the three things it can mean.
+     *
+     * A NAMED QUEUED TURN IS DELETED, NOT ABORTED: the user removed a message that
+     * had not started, and aborting the run in flight would cancel somebody else's
+     * work. An unnamed (or in-flight) request is the ordinary signal path, which
+     * already settles, persists and reports - the runner's own `requestInterrupt`.
+     */
+    onInterruptFrame(requestId, id) {
+        const receipt = (extra) => {
+            this.writeToBridge({ type: 'ack', ...(id ? { id } : {}), ...extra });
+        };
+        if (requestId && this.bridgeSource) {
+            const verdict = this.bridgeSource.cancelQueued(requestId);
+            if (verdict === 'cancelled') {
+                receipt({ accepted: true, cancelled: 'queued' });
+                return;
+            }
+            if (verdict === 'unknown') {
+                receipt({ accepted: false, code: 'unknown_turn' });
+                return;
+            }
+        }
+        this.requestInterrupt();
+    }
+    /**
+     * `cancel_request` over the wire: stop ONE request, never the process.
+     *
+     * THREE OUTCOMES, and the third one is the important one (section 2.4.7):
+     *
+     *   QUEUED       the source deletes it and THIS method writes its `request_end`,
+     *                because `run()`'s loop never saw that prompt and never will.
+     *                The `ack` echoes the requestId, since a queued prompt has no
+     *                `ack` of its own before it is served.
+     *   IN FLIGHT    cancel the scope and abort. The request's own `finally` writes the
+     *                `request_end`, so there is still exactly one writer per fact.
+     *   UNKNOWN      `ack{accepted:false}` and a non-fatal error. A FINISHED REQUEST IS
+     *                `unknown`, NEVER "in flight" - aborting a healthy run because a
+     *                caller cancelled something it already got an answer for is the
+     *                exact defect the source's `cancelQueued` comment records.
+     */
+    cancelRequest(requestId, frameId) {
+        const receipt = (extra) => {
+            this.writeToBridge({ type: 'ack', ...(frameId ? { id: frameId } : {}), ...extra });
+        };
+        // THE SOURCE IS ASKED FIRST, because it is the only object that can tell a QUEUED
+        // prompt from a SERVED one. Its three-way verdict is exactly the three outcomes
+        // this frame has, which is why it was written that way in the first round.
+        if (requestId && this.bridgeSource) {
+            const verdict = this.bridgeSource.cancelQueued(requestId);
+            if (verdict === 'cancelled') {
+                receipt({ accepted: true, requestId, code: 'queued_cancelled' });
+                this.writeCancelledRequestEnd(requestId);
+                return;
+            }
+            if (verdict === 'unknown') {
+                // A FINISHED REQUEST IS `unknown`, NEVER "in flight": answering anything else
+                // would make a late cancel abort a healthy run.
+                this.reportUnknownRequest(requestId, frameId);
+                return;
+            }
+            // `in_flight` falls through: the named request is the one running.
+        }
+        const target = requestId ?? this.requestScope.requestId();
+        if (this.requestInFlight && target !== undefined && target === this.requestScope.requestId()) {
+            this.requestScope.cancel('cancelled');
+            receipt({ accepted: true, requestId: target });
+            this.bridge?.abortInFlight();
+            this.controller?.abort();
+            return;
+        }
+        this.reportUnknownRequest(requestId, frameId);
+    }
+    /**
+     * The refusal, written where the caller can act on it.
+     *
+     * TWO FRAMES, DELIBERATELY: the `ack` says "not accepted" and the non-fatal `error`
+     * says why. A caller that only watches `ack` is not left guessing, and one that only
+     * watches `error` is not left without a receipt.
+     */
+    reportUnknownRequest(requestId, frameId) {
+        this.writeToBridge({
+            type: 'ack',
+            ...(frameId ? { id: frameId } : {}),
+            accepted: false,
+            code: 'unknown_turn',
+            ...(requestId ? { requestId } : {}),
+        });
+        this.writeToBridge({
+            type: 'error',
+            sessionId: this.sessionId,
+            fatal: false,
+            code: 'bridge_unknown_request',
+            message: `cancel_request named "${requestId ?? 'the in-flight request'}", which is not running.`,
+        });
+    }
+    /**
+     * The `request_end` for a request that was cancelled BEFORE it was served.
+     *
+     * `requestSeq` IS ABSENT, NOT ZERO: the number is minted when a prompt is served,
+     * this one never was, and inventing one would collide with a later real request.
+     * Everything else is honestly zero, including `cost` - which is `known: true` with
+     * `amount: 0` because nothing was spent and that is a fact, not a missing price.
+     */
+    writeCancelledRequestEnd(requestId) {
+        if (!this.bridge)
+            return;
+        if (!this.requestScope.remember(requestId))
+            return;
+        this.writeToBridge(buildRequestEndEvent({
+            sessionId: this.sessionId,
+            requestId,
+            stopReason: 'cancelled',
+            isError: false,
+            turns: 0,
+            durationMs: 0,
+            usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+            cost: { amount: 0, currency: 'USD', known: true },
+            result: '',
+            ...(this.opts.resultSink ? { structured: null } : {}),
+            error: null,
+        }));
     }
     /**
      * Map a supervisor event onto the `job` channel.
@@ -335,6 +585,10 @@ export class ExecRunner {
             clearTimeout(this.budgetTimer);
             this.budgetTimer = null;
         }
+        // THE REQUEST TIMER TOO (R-13). `detach()` runs after the last request, so a
+        // surviving request timer could only ever fire against a disposed controller - the
+        // same class of late callback the scope's own generation latch exists for.
+        this.requestScope.detach();
     }
     stats() {
         return {
@@ -344,6 +598,8 @@ export class ExecRunner {
                     ...this.compactionBilling, usage: { ...this.compactionBilling.usage },
                 } } : {}),
             lastAssistantText: this.lastAssistantText,
+            ...(this.lastStructured ? { lastStructured: { ...this.lastStructured } } : {}),
+            resultUnsatisfied: this.resultUnsatisfied,
             errored: this.errored,
             stopReason: this.stopReason,
             errorCode: this.errorCode,
@@ -389,10 +645,75 @@ export class ExecRunner {
             // nothing more to say exits 0 with `end_turn`, not 3 with `max_turns`.
             if (next === null)
                 break;
+            const prompt = source.lastPrompt?.();
+            this.requestId = prompt?.requestId;
             const requestSeq = ++this.requestSeq;
             this.requestHadError = false;
+            this.resultUnsatisfied = false;
+            this.repairsUsed = 0;
+            // THE REQUEST BEGINS HERE, BEFORE THE ACK, because `requestSeq` is part of the
+            // request's identity and the ack promises it.
+            this.requestScope.begin({
+                requestSeq,
+                ...(prompt?.requestId !== undefined ? { requestId: prompt.requestId } : {}),
+            });
+            this.requestInFlight = true;
+            // THE ONE RESET POINT (P1-11). AFTER `begin()`, BEFORE `prompt()`: the previous
+            // request's tool calls have all settled by now (its `finally` is on the await
+            // chain), and this request's first turn has not been sent. Resetting at the END
+            // of a request instead would let a late tool result be judged as the next
+            // request's answer.
+            this.opts.resultSink?.reset();
             this.progress.begin(requestSeq);
-            this.emit({ type: 'turn_state', sessionId: this.sessionId, requestSeq, phase: 'started' });
+            // `prompt_pre`, BETWEEN `begin()` AND THE ACK (section 2.4.7, review P1-11).
+            //
+            // THE POSITION IS THE CONTRACT. Before `begin()` there is no `requestId` to put on
+            // the `hook_request`; after the ack a denial would arrive as `ack{accepted:true}`
+            // followed by `request_end{cancelled}` - one frame saying "I took it" and one saying
+            // "I did not". Here both facts are honest, and the denial reuses the shape
+            // `writeCancelledRequestEnd` already established.
+            // CONDITIONAL, NOT AN UNCONDITIONAL AWAIT (I-C1). A run with no hook channel must
+            // reach `prompt()` after EXACTLY as many microtasks as it did before this feature
+            // existed: an extra `await` here reorders observable timing for callers that drive
+            // `run()` a tick at a time (this package's own progress tests found it).
+            const hookVerdict = this.opts.hookPort
+                ? await this.applyPromptPre(next, prompt, requestSeq)
+                : next;
+            if (hookVerdict === null)
+                continue;
+            // THE ACK IS EMITTED HERE, NOT BY THE SOURCE, because `requestSeq` is the
+            // runner's own counter and a receipt that guessed at it would be worse than
+            // one that omitted it. `queued` was captured at arrival, where it means
+            // something; the order of these acks is the order the source served, which
+            // is the order the caller wrote.
+            if (this.bridge && prompt?.requestId) {
+                this.writeToBridge({
+                    type: 'ack',
+                    id: prompt.requestId,
+                    accepted: true,
+                    queued: prompt.queued === true,
+                    requestSeq,
+                });
+            }
+            // THE TURN BOUNDARY, WHICH IS THE ONLY PLACE A DEFERRED `tool_register` MAY
+            // BE APPLIED (I-8): the engine is idle here and `prompt()` is about to be
+            // called, so the new definition reaches the very next LLM request.
+            this.bridge?.beginTurn(this.turns + 1);
+            // CONDITIONAL AWAIT, NOT `await this.drainBridge()`. With no bridge there is
+            // no promise to await, and an unconditional `await` would still cost a
+            // microtask per turn - enough to change the observable ordering for callers
+            // that drive `run()` a tick at a time (and for this package's own runner
+            // tests, which is how this was found).
+            const drain = this.bridge?.drainIfNeeded();
+            if (drain)
+                await drain;
+            this.emit({
+                type: 'turn_state',
+                sessionId: this.sessionId,
+                requestSeq,
+                phase: 'started',
+                ...this.correlation(),
+            });
             this.progress.started(requestSeq);
             try {
                 if (this.isRequestCancelled())
@@ -401,7 +722,7 @@ export class ExecRunner {
                     this.stopReason = 'max_turns';
                     break;
                 }
-                const finished = await this.runFollowThroughChain(controller, next, followThrough);
+                const finished = await this.runFollowThroughChain(controller, hookVerdict, followThrough);
                 if (finished)
                     break;
             }
@@ -412,13 +733,242 @@ export class ExecRunner {
             }
             finally {
                 this.progress.finish(requestSeq);
-                const phase = this.isRequestCancelled()
+                const phase = this.isRequestCancelled() || this.requestScope.cancelledReason() !== null
                     ? 'cancelled'
                     : this.requestHadError ? 'failed' : 'completed';
-                this.emit({ type: 'turn_state', sessionId: this.sessionId, requestSeq, phase });
+                // THE `turn_state` GOES FIRST, AND THE `request_end` RIGHT AFTER IT: same
+                // `finally`, same writer, so "the request's last state precedes its account"
+                // is structural rather than remembered (I-R3).
+                this.emit({
+                    type: 'turn_state',
+                    sessionId: this.sessionId,
+                    requestSeq,
+                    phase,
+                    ...this.correlation(),
+                });
+                this.requestInFlight = false;
+                // BEFORE `settleRequest`, so the account it writes can carry `injection_stranded`
+                // in `error.code` (I-H12). Reporting it after would mean the caller reads a clean
+                // `request_end` and never learns the injected context was dropped.
+                this.reportStrandedInjection();
+                this.settleRequest(requestSeq);
+                // THE GATE'S RELEASE POINT: after the account is written, in the request's own
+                // `finally`, so a slot is never freed before the request it was holding is over.
+                this.opts.onRequestSettled?.(requestSeq);
             }
         }
     }
+    /**
+     * Run `prompt_pre` for the request that just began, and settle it if a hook refuses.
+     *
+     * RETURNS THE TEXT TO SEND, or `null` when the request has already been settled and the
+     * caller's loop must continue with the next one. A caller hook's denial is a FAILED
+     * request - the caller did not get what it asked for - which is why `isError` is true
+     * here and false for a caller's own `cancel_request`.
+     */
+    async applyPromptPre(text, prompt, requestSeq) {
+        const port = this.opts.hookPort;
+        if (!port)
+            return text;
+        // A REQUEST ID ALWAYS EXISTS BY THIS POINT, and if the caller did not supply one the
+        // runner's own `request_<n>` stands in: `scope.begin()` has already run, so a hook request
+        // without an id would be the one case the caller could not correlate.
+        const requestId = prompt?.requestId ?? `request_${requestSeq}`;
+        const decision = await port.promptPre({
+            text,
+            queued: prompt?.queued === true,
+            requestId,
+        });
+        if (decision.action === 'deny') {
+            this.writeDeniedRequestEnd(requestId, requestSeq, decision);
+            return null;
+        }
+        return decision.action === 'rewrite' && decision.text !== undefined ? decision.text : text;
+    }
+    /**
+     * The `request_end` for a request a hook refused.
+     *
+     * ONE DELIBERATE DIFFERENCE FROM `writeCancelledRequestEnd`: `requestSeq` IS PRESENT.
+     * That method serves a prompt that was withdrawn while queued, before `begin()` ever ran,
+     * so it has no number to give; this one HAS begun, and inventing a denial without the
+     * number would make "which request was refused" a guessing game.
+     */
+    writeDeniedRequestEnd(requestId, requestSeq, decision) {
+        const code = decision.code ?? 'hook_denied';
+        const message = decision.message ?? 'A caller hook refused this prompt.';
+        this.writeToBridge({
+            type: 'ack',
+            id: requestId,
+            accepted: false,
+            code,
+            requestSeq,
+        });
+        this.writeToBridge({
+            type: 'error',
+            sessionId: this.sessionId,
+            fatal: false,
+            code,
+            message,
+        });
+        if (!this.requestScope.remember(requestId))
+            return;
+        this.requestInFlight = false;
+        this.requestScope.cancel('cancelled');
+        this.requestScope.end({ now: this.now(), error: { code, message } });
+        this.writeToBridge(buildRequestEndEvent({
+            sessionId: this.sessionId,
+            requestId,
+            requestSeq,
+            stopReason: 'cancelled',
+            isError: decision.isError !== false,
+            turns: 0,
+            durationMs: 0,
+            usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+            cost: { amount: 0, currency: 'USD', known: true },
+            result: '',
+            ...(this.opts.resultSink ? { structured: null } : {}),
+            error: { code, message },
+        }));
+    }
+    /**
+     * Record a hook-caused request failure (section 2.4.8's `error` policy).
+     *
+     * ALL THREE FIELDS, because three different readers need them: `errorCode` and
+     * `errorMessage` become `request_end.error`, and `requestHadError` is what makes
+     * `requestError()` return anything at all - setting the first two alone leaves the frame
+     * looking clean, which is exactly the failure `--on-hook-timeout error` exists to prevent.
+     */
+    markHookError(code) {
+        if (this.errorCode === null) {
+            this.errorCode = code ?? 'hook_timeout';
+            this.errorMessage = 'A caller lifecycle hook did not answer; --on-hook-timeout error.';
+        }
+        this.requestHadError = true;
+    }
+    /**
+     * Report an injection that was queued for a request that never accepted it (I-H12).
+     *
+     * TWO FRAMES, because there are two facts: the hook round trip ended as `aborted` with
+     * `injection_stranded` (visible in the hook channel), and this request's `error.code`
+     * carries the same string so a caller reading only `request_end` learns it too.
+     */
+    reportStrandedInjection(hookId) {
+        const stranded = this.pendingInjection;
+        if (!stranded && hookId === undefined)
+            return;
+        this.pendingInjection = null;
+        this.writeToBridge({
+            type: 'hook_resolved',
+            sessionId: this.sessionId,
+            requestId: this.requestScope.requestId() ?? 'unknown',
+            hookId: stranded?.hookId ?? hookId ?? 'h?',
+            point: 'turn_start',
+            outcome: 'aborted',
+            code: 'injection_stranded',
+        });
+        if (this.errorCode === null) {
+            this.errorCode = 'injection_stranded';
+            this.errorMessage =
+                'A caller hook injected context for a turn that never started, so it was not added.';
+        }
+        // `requestHadError` TOO, not just `errorCode`: `requestError()` is what `request_end.error`
+        // reads, and it returns null unless the request is marked as failed - so setting only the
+        // code would leave the frame clean and the fact invisible.
+        this.requestHadError = true;
+    }
+    /**
+     * Write this request's `request_end` - the FIRST of the two writers (I-R9).
+     *
+     * The second is `cancelRequest`, for a prompt that was cancelled while queued and
+     * therefore never reached this method at all. Both go through
+     * `RequestScope.remember()`, which is what makes "exactly one per request" true
+     * instead of merely intended.
+     */
+    settleRequest(requestSeq) {
+        const requestId = this.requestScope.requestId();
+        if (!this.requestScope.remember(requestId ?? `request_${requestSeq}`))
+            return;
+        const sink = this.opts.resultSink;
+        const accepted = sink?.accepted() ?? null;
+        if (accepted) {
+            // PROCESS-LEVEL MEMORY FOR A PROCESS-LEVEL EVENT. `result` is one event for the
+            // whole run; a later request that submits nothing must not erase the fact that
+            // an answer WAS produced.
+            this.lastStructured = { value: accepted.value, attempts: accepted.attempts };
+        }
+        if (!this.bridge) {
+            this.requestScope.end(this.settlementInput());
+            return;
+        }
+        const settlement = this.requestScope.end(this.settlementInput());
+        this.writeToBridge(buildRequestEndEvent({
+            sessionId: this.sessionId,
+            requestId: settlement.requestId,
+            ...(settlement.requestSeq !== undefined ? { requestSeq: settlement.requestSeq } : {}),
+            stopReason: settlement.stopReason,
+            isError: settlement.isError,
+            turns: settlement.turns,
+            durationMs: settlement.durationMs,
+            usage: settlement.usage,
+            cost: settlement.cost,
+            result: clipText(this.lastAssistantText, REQUEST_LIMITS.maxResultChars),
+            ...(sink
+                ? { structured: accepted
+                        ? { value: accepted.value, schemaName: this.opts.resultSchemaName ?? 'result', attempts: accepted.attempts }
+                        : null }
+                : {}),
+            error: settlement.error,
+        }));
+    }
+    /**
+     * What `RequestScope.end()` needs: the clock, the failure, and - when the PROCESS
+     * stopped underneath this request - the process reason (section 2.4.2).
+     *
+     * SEPARATE FROM `requestError()` BECAUSE THE TWO ANSWER DIFFERENT QUESTIONS: the
+     * error says "you did not get what you asked for", the reason says "why this request
+     * ended". A process `interrupt` sets the second and not the first, which is exactly
+     * the case a caller reading only `stopReason` has to see as `cancelled` rather than
+     * as a finished answer.
+     */
+    settlementInput() {
+        const processReason = this.processStopForRequest();
+        return {
+            now: this.now(),
+            error: this.requestError(),
+            ...(processReason ? { stopReason: processReason } : {}),
+        };
+    }
+    /**
+     * The process-level stop, translated into the REQUEST vocabulary (section 2.4.2).
+     *
+     * `undefined` for `end_turn` and for everything a request already speaks for itself.
+     * Only the three cases where the RUN ended underneath a live request are mapped, and
+     * the mapping is one-way on purpose: `ExecStopReason` and `ExecRequestStopReason` are
+     * different unions over different questions and must stay different.
+     */
+    processStopForRequest() {
+        switch (this.stopReason) {
+            case 'max_turns':
+                return 'max_turns';
+            case 'timeout':
+                return 'timeout';
+            case 'interrupted':
+                return 'cancelled';
+            case 'error':
+                return 'error';
+            default:
+                return undefined;
+        }
+    }
+    /** The request-level error, or `null`. One place so `result` and `request_end` agree. */
+    requestError() {
+        if (!this.requestHadError && !this.resultUnsatisfied)
+            return null;
+        return {
+            code: this.errorCode ?? 'agent_error',
+            message: this.errorMessage ?? 'The run failed.',
+        };
+    }
     onCompactionUsage(event) {
         const usage = event.usage;
         this.usage.inputTokens += usage.inputTokens;
@@ -461,11 +1011,114 @@ export class ExecRunner {
                 turn: this.turns + 1,
                 text: message,
                 source,
+                // AN AUTO-CONTINUATION HAS NO `requestId`: it is the CLI's own message,
+                // not the caller's request, and `source: 'todo_continue'` already says so.
+                ...(source === 'caller' ? this.correlation() : {}),
             });
+            // THE FOLLOW-THROUGH CHAIN'S LATER ITERATIONS ARE NEW TURNS, so the registry
+            // boundary is re-announced: a `tool_register` that arrived during iteration N
+            // must be live for iteration N+1, and `prompt()` below is where that matters.
+            this.bridge?.beginTurn(this.turns + 1);
             this.startBudgetTimer();
+            // THE SAME JUDGEMENT THE POST-TURN CHECK MAKES, ASKED BEFORE THE TURN STARTS:
+            // `stopRequestOnBudget()` is the ONE place a request budget is decided, and it is
+            // asked here as well as after each turn (a `--request-max-duration` that expires
+            // between two continuations must not be given another turn). Prompting an already
+            // aborted controller would also emit an `agent_end` with no assistant turn, which
+            // the silent-failure detector below would report as an `agent_error` - a request
+            // budget must never make the process look broken (I-R1).
+            // `turn_start`, AND ITS POSITION IS NOT NEGOTIABLE (section 2.4.6, review P1-9):
+            // the hook is ASKED here, but the injection is QUEUED only after the budget check
+            // below. `Agent.steer()` does not throw when the engine is idle - it queues the text
+            // for the next `acceptSteering`, which is the NEXT request's loop top - so an
+            // injection made before a budget stop would surface in somebody else's conversation.
+            // CONDITIONAL, FOR THE SAME REASON `prompt_pre` IS (I-C1): `await undefined` still costs
+            // a microtask, and a runner with no hook channel must reach `prompt()` on exactly the
+            // turn count it did before this feature existed.
+            const injection = this.opts.beforeTurn
+                ? ((await this.opts.beforeTurn({
+                    turn: this.turns + 1,
+                    source,
+                    // `requestScope.requestId()` IS the id by now: `scope.begin()` runs before the
+                    // first turn, and a request without a caller-supplied id gets `request_<n>` from
+                    // the scope itself, so the fallback here never fires (it satisfies the type).
+                    requestId: this.requestScope.requestId() ?? 'unknown',
+                })) ?? undefined)
+                : undefined;
+            if (this.haltRequestOnBudget()) {
+                // NOTHING WAS QUEUED, SO NOTHING IS STRANDED (section 2.4.6). `beforeTurn` produced
+                // text that never reached the steering queue, and the hook round trip already wrote
+                // its own `hook_resolved` - so there is no missing frame to close. Reporting
+                // `injection_stranded` here would invent a frame for an injection that never
+                // existed AND mark a request budget stop as a hook failure, which is the one thing
+                // I-R1 forbids (`--request-max-turns` must never make the process look broken).
+                return false;
+            }
+            if (injection?.injected) {
+                const receiptsBefore = this.steeringReceipts;
+                const queued = controller.queueUserMessage?.(injection.injected);
+                // RECORDED BEFORE `prompt()` SO A FAILED START CAN STILL REPORT IT; the
+                // `steering_accepted` receipt is the only thing that clears it - including one that
+                // arrives synchronously, which the counter detects.
+                const confirmed = this.steeringReceipts > receiptsBefore;
+                this.pendingInjection =
+                    queued === undefined || confirmed ? null : { hookId: injection.hookId ?? 'h?' };
+            }
             await controller.prompt(message);
+            if (injection?.isError === true)
+                this.markHookError(injection.code);
             if (this.stopReason !== 'end_turn')
                 return true;
+            // A REQUEST-LEVEL STOP ENDS *THIS REQUEST*, NEVER THE PROCESS (I-R1).
+            const cancelled = this.requestScope.cancelledReason();
+            if (cancelled !== null) {
+                // A CALLER'S OWN CANCELLATION IS NOT A CONTRACT FAILURE. A BUDGET STOP IS, and
+                // the caller has to learn both facts (AC-51): `stopReason` answers "why did
+                // this stop", `error.code` answers "did I get what I asked for".
+                if (cancelled !== 'cancelled' && this.opts.resultSink && !this.opts.resultSink.accepted()) {
+                    this.markResultUnsatisfied();
+                }
+                return false;
+            }
+            // BUDGET BEFORE REWORK (P1-9). A repair attempt that the budget cannot pay for
+            // would report `max_turns` while the real problem is an unsubmitted result.
+            if (this.haltRequestOnBudget())
+                return false;
+            const contract = this.resultContractOutcome();
+            // "ACCEPT THEN STOP" (I-S4): the abort in `checkResultComplete` already ended the
+            // model's loop; this is what refuses a follow-through continuation on the far
+            // side of it.
+            if (contract === 'accepted')
+                return false;
+            // THE PROCESS BUDGET IS JUDGED BEFORE THE CONTRACT'S REMAINING BRANCHES, AND ONLY
+            // WHEN A SCHEMA FAILED (section 2.3.5). A repair is an ordinary turn, so a repair
+            // the caller's `--max-turns` cannot pay for must report `max_turns` rather than be
+            // started and immediately aborted. The `contract === 'none'` case never reaches
+            // here, which is what keeps a successful non-schema run ending on `end_turn` even
+            // when it used exactly its whole budget (IF-3).
+            // `contract === 'none'` IS EXCLUDED ON PURPOSE (implementation note I-6): a run with
+            // no schema that uses exactly its whole budget must still report `end_turn`, which is
+            // the IF-3 defect the block budget's own comment records. Only a run whose contract
+            // already failed can be said to have "run out of budget for the repair".
+            if (contract !== 'none' && this.turnBudgetExhausted()) {
+                this.stopReason = 'max_turns';
+                return true;
+            }
+            if (contract === 'repair') {
+                const sink = this.opts.resultSink;
+                this.repairsUsed += 1;
+                // THE CLI SPEAKS FOR THE CALLER HERE, exactly as `todo_continue` does, and says
+                // so through `source` so a replayed transcript can tell them apart.
+                source = 'result_repair';
+                message = buildResultRepairMessage(sink?.lastViolations() ?? [], sink?.attempts() ?? 0);
+                continue;
+            }
+            if (contract === 'unsatisfied') {
+                this.markResultUnsatisfied();
+                // `error` ends the run (the single-call default); `continue` leaves the process
+                // serving the next request with `result.isError` still true.
+                return this.opts.onResultUnsatisfied !== 'continue';
+            }
             const snapshot = controller.getTodoSnapshot?.() ?? null;
             budget = advanceBudget(budget, snapshot, wasAutoContinuation);
             wasAutoContinuation = false;
@@ -491,6 +1144,8 @@ export class ExecRunner {
                 this.stopReason = 'max_turns';
                 return true;
             }
+            if (this.haltRequestOnBudget())
+                return false;
             // CHARGED BEFORE THE RE-PROMPT. Headless has no grace timer, so without
             // this line `maxAutoContinuesPerList` would never bind in the one
             // environment with no human to press Esc.
@@ -501,6 +1156,115 @@ export class ExecRunner {
             source = 'todo_continue';
         }
     }
+    /**
+     * What the structured-result contract says about the request that just ended.
+     *
+     * FOUR ANSWERS, and `none` is the important one: with no `--result-schema` this
+     * method reads nothing and the caller's behaviour is exactly what it was before the
+     * feature existed (I-S2).
+     */
+    resultContractOutcome() {
+        const sink = this.opts.resultSink;
+        if (!sink)
+            return 'none';
+        if (sink.accepted())
+            return 'accepted';
+        const repairTurns = this.opts.resultRepairTurns ?? RESULT_LIMITS.defaultRepairTurns;
+        return this.repairsUsed < repairTurns ? 'repair' : 'unsatisfied';
+    }
+    /**
+     * Record that this request ended without the answer the caller asked for.
+     *
+     * TWO FACTS, TWO FIELDS, NEVER ONE NAME FOR BOTH (P1-9): `error.code` says the
+     * contract failed, and the process-level `stopReason` moves to `error` ONLY when
+     * `--on-result-unsatisfied error` (the default) and nothing else already decided why
+     * the request stopped.
+     */
+    markResultUnsatisfied() {
+        this.resultUnsatisfied = true;
+        this.requestScope.cancel('error');
+        if (this.errorCode === null) {
+            this.errorCode = 'result_schema_unsatisfied';
+            this.errorMessage = `No result matching ${this.opts.resultSchemaName ?? 'the schema'} was submitted.`;
+        }
+        const contractIsTheCause = this.requestScope.cancelledReason() === 'error';
+        if (contractIsTheCause && this.stopReason === 'end_turn'
+            && this.opts.onResultUnsatisfied !== 'continue') {
+            // THE PROCESS STOP REASON *AND* THE FLAG THE EXIT CODE READS. `exitCode()` is
+            // `errored ? 1 : 0` for everything that is not a signal or a budget, so setting
+            // only `stopReason` would report the failure in `result` while exiting 0 - the
+            // one combination a shell script cannot defend against.
+            this.stopReason = 'error';
+            this.errored = true;
+        }
+    }
+    /**
+     * Stop the request for a budget reason, and record the contract failure it implies.
+     *
+     * THE CANCELLATION GUARD IS THE POINT. A caller that withdrew this request has not
+     * failed to deliver a result, so `cancel_request` must not leave a
+     * `result_schema_unsatisfied` behind - "the work was called off" and "the answer
+     * never arrived" are different facts and only the second is a contract failure
+     * (section 2.3.7). One helper rather than three copies, because the copy that
+     * forgets this line is a defect nobody notices for a release.
+     */
+    haltRequestOnBudget() {
+        if (!this.stopRequestOnBudget())
+            return false;
+        if (this.opts.resultSink &&
+            !this.opts.resultSink.accepted() &&
+            this.requestScope.cancelledReason() !== 'cancelled') {
+            this.markResultUnsatisfied();
+        }
+        return true;
+    }
+    /**
+     * The request-level budgets, at a boundary the engine can survive.
+     *
+     * RETURNS TRUE WHEN IT STOPPED THE REQUEST. The process is never touched: calling
+     * `controller.abort()` ends the model's current loop, and the next `prompt()` starts
+     * a fresh one - which is the whole of I-R1.
+     */
+    stopRequestOnBudget() {
+        if (this.requestScope.cancelledReason() !== null)
+            return true;
+        if (this.requestScope.turnsExhausted()) {
+            this.requestScope.cancel('max_turns');
+        }
+        else if (this.requestScope.isOverDurationBudget(this.now())) {
+            // THE LAZY HALF OF THE TIMER. A `setTimeout` can be late by an arbitrary amount
+            // when the loop is busy, and a budget that only exists in a timer is a budget
+            // that sometimes does not exist.
+            this.requestScope.cancel('timeout');
+        }
+        else {
+            return false;
+        }
+        this.bridge?.abortInFlight();
+        this.controller?.abort();
+        return true;
+    }
+    /**
+     * "ACCEPTED MEANS FINISHED", enforced at the one event that follows a tool result
+     * (section 2.3.6).
+     *
+     * `turn_end` fires BEFORE `tool_execution_start`, so by the time this runs the turn
+     * has already been counted and `agent_end` cannot mistake the abort for a run that
+     * produced nothing.
+     */
+    checkResultComplete() {
+        if (!this.opts.resultSink?.accepted())
+            return;
+        // PER REQUEST, NOT PER PROCESS (P1-5): the latch lives in the scope, so the second
+        // request of a long-lived process aborts itself exactly as the first one did - and
+        // a request that never submitted anything is never aborted by a stale value.
+        if (this.requestScope.acceptanceAborted())
+            return;
+        this.requestScope.markAcceptanceAborted();
+        // THE SAME ABORT PATH AS THE BUDGET AND Esc, so subagents are torn down and the
+        // engine settles normally instead of being abandoned mid-turn.
+        this.controller?.abort();
+    }
     // -----------------------------------------------------------------------
     // Budgets (section 3.5)
     // -----------------------------------------------------------------------
@@ -588,6 +1352,12 @@ export class ExecRunner {
      * this and add the getter.
      */
     installTerminator() {
+        // THE OPTION IS CHECKED HERE AS WELL AS AT THE CALL SITE (section 2.3.8a, R-13).
+        // Two guards for one rule is not redundancy when the rule is "a second install
+        // silently disables the first": a future `attach()` that forgets the call-site guard
+        // still cannot take the terminator away from the thread owner.
+        if (this.opts.installSignalTerminator === false)
+            return;
         this.signals.setTerminator((signo) => this.onSignal(signo));
     }
     /**
@@ -620,13 +1390,50 @@ export class ExecRunner {
         this.lastSignalAt = at;
         this.signalNumber = signo;
         this.stopReason = 'interrupted';
+        // BEFORE THE ABORT, AND SYNCHRONOUSLY. A decision wait is inside a tool
+        // execution, and the executor abandons a tool 5 seconds after the abort; a
+        // bridge that only learned about the interrupt from a later event would hand
+        // the model "did not stop within 5000ms of abort" instead of "the turn was
+        // interrupted" (AC-49). Settling first also means the tool's own promise has
+        // already resolved when `abort()` reaches the executor.
+        this.bridge?.abortInFlight();
         this.controller?.abort();
     }
     // -----------------------------------------------------------------------
     // Event translation
     // -----------------------------------------------------------------------
+    /**
+     * THE ONE STAMPING POINT (section 2.3.10, I-T10; review P1-1).
+     *
+     * NOT `correlation()`, which returns only `{requestId}` and is spread into a handful of
+     * events: the thread id has to be on EVERY line this runner produces, including the ones
+     * that carry no request (a `todo` snapshot, a `job` update). Stamping here and in
+     * `writeToBridge` covers the whole file - and AC-54 turns the claim into a single
+     * universal assertion ("every line with a sessionId has a threadId") rather than a
+     * per-event checklist that a new event can quietly escape.
+     */
     emit(event) {
-        this.emitter.emit(event);
+        this.emitter.emit(this.opts.threadId !== undefined
+            ? { ...event, threadId: this.opts.threadId }
+            : event);
+    }
+    /**
+     * The same stamp for the frames that bypass `emit()`.
+     *
+     * SIX SITES USE THIS AND THEY ARE ALL ACKS AND CONTROL FRAMES: steer ack, interrupt ack,
+     * the cancelled `request_end`, the request ack, the settled `request_end` and the
+     * `steering` receipt. A seventh added later that writes to `bridge` directly would lose
+     * the stamp - which is why the method exists rather than six copies of a conditional
+     * spread.
+     */
+    writeToBridge(event) {
+        if (!this.bridge)
+            return;
+        this.bridge.write(this.opts.threadId !== undefined ? { ...event, threadId: this.opts.threadId } : event);
+    }
+    /** The correlation fields every attributable event carries in bridge mode. */
+    correlation() {
+        return this.bridge && this.requestId ? { requestId: this.requestId } : {};
     }
     /** Caller-facing prose. STDERR ALWAYS - stdout carries nothing but the schema. */
     note(text) {
@@ -654,6 +1461,7 @@ export class ExecRunner {
                     id: event.toolCallId,
                     name: event.toolName,
                     input: (event.args ?? {}),
+                    ...this.correlation(),
                 });
                 break;
             case 'tool_execution_end':
@@ -667,6 +1475,29 @@ export class ExecRunner {
                     isError: event.isError,
                     durationMs: event.duration,
                     output: toolResultText(event.result),
+                    ...this.correlation(),
+                });
+                // AFTER THE `tool_result`, SO THE CALLER SEES THE ACCEPTANCE BEFORE THE ABORT
+                // THAT FOLLOWS IT. `turn_end` has already fired (it precedes the tool call), so
+                // the abort cannot be mistaken for a turn that produced nothing.
+                this.checkResultComplete();
+                break;
+            case 'steering_accepted':
+                // ONE EVENT, THE WHOLE BATCH (review P1-7). Core's receipt carries every
+                // id a single drain accepted; reporting only the first would leave the rest
+                // permanently unconfirmed on the caller's side, which is the exact failure
+                // the receipt exists to prevent.
+                //
+                // IT ALSO CONFIRMS THE `turn_start` INJECTION (section 2.4.6): this is the only
+                // signal that the text actually entered history, and clearing the pending marker
+                // here is what keeps that fact from being misreported as stranded.
+                this.pendingInjection = null;
+                this.steeringReceipts += 1;
+                this.writeToBridge({
+                    type: 'steering',
+                    sessionId: this.sessionId,
+                    steeringIds: [...event.ids],
+                    ...this.correlation(),
                 });
                 break;
             case 'turn_end':
@@ -737,13 +1568,23 @@ export class ExecRunner {
     onTurnEnd(message, usage) {
         this.sawTurnEnd = true;
         this.turns += 1;
+        // THE SAME MOMENT AS THE PROCESS COUNTER, DELIBERATELY: two counters over one
+        // event is one fact seen twice; two counters over two events is two facts that can
+        // disagree, and the budget would be enforced against the wrong one.
+        this.requestScope.countTurn();
         this.usage.inputTokens += usage.inputTokens;
         this.usage.outputTokens += usage.outputTokens;
         this.flushThinking();
         const text = assistantText(message);
         if (text.length > 0) {
             this.lastAssistantText = text;
-            this.emit({ type: 'assistant', sessionId: this.sessionId, turn: this.turns, text });
+            this.emit({
+                type: 'assistant',
+                sessionId: this.sessionId,
+                turn: this.turns,
+                text,
+                ...this.correlation(),
+            });
         }
     }
     flushThinking() {
@@ -823,6 +1664,17 @@ function assistantText(message) {
     }
     return parts.join('').trim();
 }
+/**
+ * Clip one model-visible string to a bound the frame can carry.
+ *
+ * `request_end.result` is the ONLY place in this file where the full answer is
+ * truncated, and the bound comes from `REQUEST_LIMITS` rather than from a literal: the
+ * complete text is still on the `assistant` events, so this is a frame decision, not a
+ * data-loss decision.
+ */
+function clipText(text, max) {
+    return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 3))}...`;
+}
 /**
  * Flatten a `ToolResult` to the text the MODEL saw.
  *