@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/exec/result/tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `submit_result`: the model's only way to hand an answer over as data
+ * (headless-request-scope-and-typed-result section 2.3.2 / 2.3.5).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * WHY A TOOL AND NOT A PROVIDER FEATURE. `response_format` / forced `tool_choice`
+ * would need three adapter changes inside Core, whose public surface
+ * (`public-api.test.ts`) and host-coupling ban (`no-host-coupling.test.ts`) are both
+ * frozen. A tool costs one extra round trip and buys three things Core cannot give
+ * here: the caller's schema travels to the model as a REAL JSON Schema (every
+ * adapter serializes `parameters` verbatim), a violation comes back as a readable
+ * field-level message the model can act on inside the same prompt, and the whole
+ * mechanism is provable without a network.
+ *
+ * NOTHING IN HERE KNOWS WHAT A REQUEST OR A PROCESS IS. It validates and it writes
+ * one box. Ending the request is the runner's job (`checkResultComplete`), which is
+ * what keeps "accepted" and "finished" from becoming two different opinions.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import { type ResultSchemaSpec } from './schema.js';
+import type { ResultSink } from './sink.js';
+/** The one tool name this feature registers. */
+export declare const SUBMIT_RESULT_TOOL = "submit_result";
+export interface SubmitResultToolOptions {
+    spec: ResultSchemaSpec;
+    sink: ResultSink;
+}
+/**
+ * The tool the model sees.
+ *
+ * THE SCHEMA IS INLINED INTO `parameters.properties.result`, NOT WRITTEN INTO THE
+ * DESCRIPTION, and that is not a style choice: `buildSystemPrompt` renders a tool as
+ * `description.split('\n')[0]` - one line - so a schema in the description never
+ * reaches the model at all, while `parameters` is serialized verbatim.
+ */
+export declare function createSubmitResultTool(options: SubmitResultToolOptions): AgentTool;

package/dist/exec/result/tool.js

@@ -0,0 +1,118 @@
+/**
+ * `submit_result`: the model's only way to hand an answer over as data
+ * (headless-request-scope-and-typed-result section 2.3.2 / 2.3.5).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * WHY A TOOL AND NOT A PROVIDER FEATURE. `response_format` / forced `tool_choice`
+ * would need three adapter changes inside Core, whose public surface
+ * (`public-api.test.ts`) and host-coupling ban (`no-host-coupling.test.ts`) are both
+ * frozen. A tool costs one extra round trip and buys three things Core cannot give
+ * here: the caller's schema travels to the model as a REAL JSON Schema (every
+ * adapter serializes `parameters` verbatim), a violation comes back as a readable
+ * field-level message the model can act on inside the same prompt, and the whole
+ * mechanism is provable without a network.
+ *
+ * NOTHING IN HERE KNOWS WHAT A REQUEST OR A PROCESS IS. It validates and it writes
+ * one box. Ending the request is the runner's job (`checkResultComplete`), which is
+ * what keeps "accepted" and "finished" from becoming two different opinions.
+ */
+import { errorResult, textResult, } from '@aragon-agent/core';
+import { RESULT_LIMITS } from './limits.js';
+import { canonicalizeResult, checkResultValue, coerceStringifiedObject, formatResultViolations, resultValueBytes, } from './schema.js';
+/** The one tool name this feature registers. */
+export const SUBMIT_RESULT_TOOL = 'submit_result';
+/**
+ * The tool the model sees.
+ *
+ * THE SCHEMA IS INLINED INTO `parameters.properties.result`, NOT WRITTEN INTO THE
+ * DESCRIPTION, and that is not a style choice: `buildSystemPrompt` renders a tool as
+ * `description.split('\n')[0]` - one line - so a schema in the description never
+ * reaches the model at all, while `parameters` is serialized verbatim.
+ */
+export function createSubmitResultTool(options) {
+    const { spec, sink } = options;
+    return {
+        name: SUBMIT_RESULT_TOOL,
+        label: 'Submit result',
+        description: 'Submit the FINAL answer as an object that conforms to the required schema. ' +
+            'Call this exactly once, when you are done. Do not also print the answer as prose. ' +
+            'If it returns a validation error, fix the fields it names and call it again.',
+        // The wrapper is raw JSON from the caller's file; the index signature on
+        // `JSONSchema7` is what lets it through without a second schema type of our own.
+        parameters: spec.wrapper,
+        async execute(id, params) {
+            const attempts = sink.noteAttempt();
+            const submitted = coerceStringifiedObject(spec.schema, params.result);
+            // STEP 1 - THE WRAPPER'S OWN REQUIREMENT, IN THE CALLER'S VOCABULARY.
+            // "the key was absent" and "the value was undefined" are the same thing after
+            // JSON decoding, and the field name is what the model has to be told.
+            if (submitted === undefined)
+                return fail(sink, ['result: required']);
+            // STEP 1b - THE WRAPPER'S `additionalProperties: false`, ENFORCED HERE AND NOT
+            // ONLY BY Core (section 2.3.2, point 3). Core runs that keyword ONLY when `ajv`
+            // is importable; its fallback never reads the keyword at all, so on a machine
+            // without `ajv` a wrapper rule left to Core is a comment. A stray top-level key
+            // is refused rather than ignored: "it was silently dropped" and "it was part of
+            // the contract" are indistinguishable from the caller's side of the pipe.
+            const extraKeys = wrapperExtraKeys(params);
+            if (extraKeys.length > 0)
+                return fail(sink, extraKeys.map(describeExtraKey));
+            // STEP 2/3 - THE BELT (section 2.3.4). Runs on EVERY machine, including the one
+            // with no `ajv`, which is why it implements the keywords Core's fallback skips.
+            const violations = checkResultValue(spec.schema, submitted);
+            if (violations.length > 0)
+                return fail(sink, violations);
+            // STEP 4/5 - CANONICAL, THEN SIZED. Canonical first, so the number checked is
+            // the size of what a consumer will read back rather than of what was typed.
+            const canonical = canonicalizeResult(submitted);
+            const bytes = resultValueBytes(canonical);
+            if (bytes > RESULT_LIMITS.maxResultValueBytes) {
+                return fail(sink, [
+                    `result: ${bytes} bytes is above the ${RESULT_LIMITS.maxResultValueBytes}-byte limit`,
+                ]);
+            }
+            // STEP 6 - SINGLE ASSIGNMENT. A second accepted call is a no-op by design, and
+            // the value a caller is entitled to is the FIRST one.
+            if (!sink.accepted())
+                sink.accept(canonical, { attempts, callId: id });
+            sink.noteViolations([]);
+            // STEP 7 - A SUCCESS RESULT EVEN ON THE SECOND CALL (I-S3). An error here would
+            // tell the model its answer was not taken, and it would keep trying.
+            return textResult('Result accepted. Do not call submit_result again; stop here.');
+        },
+    };
+}
+/**
+ * Record the rejection where the repair loop can quote it, and answer the model.
+ *
+ * `errorResult` RATHER THAN THROWING: the engine pushes whatever a tool returns into
+ * history, and an error RESULT is what keeps the `tool_use` from hanging into the
+ * next provider request. A thrown error would be converted by the executor into
+ * wording that says nothing about which fields were wrong.
+ */
+function fail(sink, violations) {
+    sink.noteViolations(violations);
+    const shown = formatResultViolations(violations);
+    return errorResult(`submit_result was not accepted (attempt ${sink.attempts()}):\n${shown}\n` +
+        'Fix the fields named above and call submit_result again with the whole object.');
+}
+/**
+ * The top-level keys the model sent that the wrapper does not accept.
+ *
+ * `result` IS THE WHOLE CONTRACT (section 2.3.2): the wrapper is
+ * `{ required: ['result'], additionalProperties: false }` and nothing else, so every
+ * other key is a stray. Returns `[]` for a non-object payload, which the missing-result
+ * check above has already answered with a better message.
+ */
+function wrapperExtraKeys(params) {
+    if (typeof params !== 'object' || params === null)
+        return [];
+    return Object.keys(params)
+        .filter((key) => key !== 'result')
+        .slice(0, RESULT_LIMITS.maxViolations);
+}
+/** One stray key, in the same `path: what is wrong` shape as every other violation. */
+function describeExtraKey(key) {
+    return `${key}: not allowed (this tool takes only "result")`;
+}

package/dist/exec/runner.d.ts

@@ -19,8 +19,11 @@ import type { HeadlessController } from '../agent/headless.js';
 import { type FollowThroughMode } from '../todo/follow-through.js';
 import type { ExecEmitter } from './emitter.js';
 import type { FastSnapshot } from '../fast/types.js';
-import type { ExecStopReason } from './events.js';
+import type { ExecCost, ExecStopReason } from './events.js';
 import type { ProcEvent } from '../proc/types.js';
+import type { BridgeServer } from './bridge/server.js';
+import type { BridgePromptSource } from './bridge/source.js';
+import type { ResultSink } from './result/sink.js';
 /**
  * The controller surface the runner needs.
  *
@@ -54,11 +57,47 @@ export interface ExecRunnerController extends HeadlessController {
      * literal, and a host with no supervisor has nothing to report.
      */
     subscribeProc?(listener: (event: ProcEvent) => void): () => void;
+    /**
+     * Whether a turn is in flight, and the enqueue path for `steer`.
+     *
+     * OPTIONAL, FOR THE SAME REASON THE SIX ABOVE ARE: this interface is minimal so
+     * a test can satisfy it with an object literal. `steer` over the bridge is their
+     * only consumer, and a stub without them answers `not_running`, which is the
+     * honest reading of "this controller cannot accept guidance".
+     */
+    isRunning?(): boolean;
+    queueUserMessage?(text: string): string;
+}
+/**
+ * One caller message plus the metadata a bridge turn needs.
+ *
+ * `requestId` is the caller's own frame id, echoed onto `user`, `turn_state`,
+ * `assistant`, `tool_call` and `tool_result` so a wrapper can attribute events to
+ * the request that caused them. `queued` says whether this message had to wait
+ * behind another one - see `bridge/source.ts`, where it is captured at ARRIVAL,
+ * the only moment the question has a meaningful answer.
+ */
+export interface ExecPrompt {
+    text: string;
+    requestId?: string;
+    queued?: boolean;
 }
 /** Where the caller's messages come from. One turn, or an NDJSON stdin stream. */
 export interface ExecPromptSource {
     /** The next caller message, or `null` when the caller is done. */
     next(): Promise<string | null>;
+    /**
+     * METADATA FOR THE MESSAGE `next()` JUST RETURNED, read once and synchronously.
+     *
+     * A SIDE CHANNEL RATHER THAN A WIDER RETURN TYPE, and that is a deliberate
+     * departure from the design (`§2.4.6` proposed `next(): Promise<ExecPrompt | null>`).
+     * Widening `next()` would have rewritten `stdin-stream.ts`'s contract and every
+     * caller of it - including `exec-stdin-stream.test.ts`, which AC-3 requires to
+     * pass VERBATIM as the proof that the v1 input format did not move. Keeping the
+     * return type and adding an optional reader gives the bridge what it needs while
+     * leaving that file byte-identical, and it costs exactly one call site: `run()`.
+     */
+    lastPrompt?(): ExecPrompt | undefined;
 }
 export declare function singlePrompt(text: string): ExecPromptSource;
 /** Replaceable so a unit test can assert the mechanism, not just the outcome. */
@@ -71,6 +110,35 @@ export interface ExecRunnerOptions {
     sessionId: string;
     maxTurns?: number;
     maxDurationMs?: number;
+    /**
+     * The structured-result contract for this run (headless-request-scope-and-typed-
+     * result section 2.4 / 2.3.5). All of these are ABSENT unless `--result-schema`
+     * was given, which is what keeps every other run byte-identical (I-S2).
+     */
+    resultSink?: ResultSink;
+    /** The schema's file name, echoed into `request_end.structured` and into errors. */
+    resultSchemaName?: string;
+    /** `--result-repair-turns`; defaults to `RESULT_LIMITS.defaultRepairTurns`. */
+    resultRepairTurns?: number;
+    /** `--on-result-unsatisfied`; `error` is the default and the only one that exits. */
+    onResultUnsatisfied?: 'error' | 'continue';
+    /**
+     * The per-request budgets (bridge only). ABSENT MEANS NO CEILING, deliberately:
+     * a default ceiling would cut off a legitimate long request with nothing saying
+     * why, and section 9.7 keeps "no default" as the decision.
+     */
+    requestMaxTurns?: number;
+    requestMaxDurationMs?: number;
+    /**
+     * How to price a usage reading.
+     *
+     * A CALLBACK RATHER THAN AN IMPORT: the cost authority (`buildCost`) lives in
+     * `exec/index.ts` because it needs the controller's price table, and importing it
+     * here would be a cycle. The runner passes its own cumulative usage and compaction
+     * billing, so a request's cost is the DIFFERENCE between two readings of the same
+     * function - which is exactly what makes it equal to running that request alone.
+     */
+    cost?: (usage: TokenUsage, compaction?: ExecCompactionBilling) => ExecCost;
     partialMessages?: boolean;
     includeThinking?: boolean;
     followThrough?: FollowThroughMode;
@@ -80,6 +148,79 @@ export interface ExecRunnerOptions {
     signals?: ExecSignalPort;
     /** Turns already spent by earlier invocations of a resumed session. */
     priorTurns?: number;
+    /**
+     * WHICH THREAD THIS RUNNER SERVES (headless-threads-and-lifecycle-hooks section
+     * 2.3.10, I-T10). Absent in every non-thread run, and its absence is what keeps that
+     * stream byte-identical: a field that is not set is not serialized.
+     */
+    threadId?: string;
+    /**
+     * Called once per request, in `run()`'s `finally`, AFTER `settleRequest`.
+     *
+     * THE ADMISSION GATE'S RELEASE POINT, and the reason it is not inside the runner: the
+     * gate must free the slot exactly when the request's account has been written, and the
+     * runner is the only object that knows that moment. Keeping it a callback means the
+     * runner learns nothing about threads.
+     */
+    onRequestSettled?: (requestSeq: number) => void;
+    /**
+     * `turn_start` (section 2.4.6). Awaited at the top of every follow-through iteration,
+     * AFTER the budget check and BEFORE `prompt()`.
+     */
+    beforeTurn?: BeforeTurnHook;
+    /** `prompt_pre` (section 2.4.7). Runs between `scope.begin()` and the ack. */
+    hookPort?: ExecRunnerHookPort;
+    /**
+     * DEFAULT `true`, AND THREAD MODE PASSES `false` (section 2.3.8a, review P0-1).
+     *
+     * `installTerminator()` writes into `logging/install.ts`'s SINGLE process-wide slot, so
+     * two runners that both install it means the last one wins: Ctrl-C would abort one
+     * controller and leave the rest running. Making it an OPTION rather than a convention is
+     * what turns "remember not to install twice" into something the type system carries.
+     */
+    installSignalTerminator?: boolean;
+}
+/** One `turn_start` answer, already validated by the hook runtime. */
+export interface BeforeTurnResult {
+    /** Text to queue through steering. */
+    injected?: string;
+    /** The hook that injected, so a stranded injection can name itself. */
+    hookId?: string;
+    /** `injection_stranded`, `hook_timeout`, ... */
+    code?: string;
+    /** `--on-hook-timeout error`: this request must end as an error. */
+    isError?: boolean;
+}
+export type BeforeTurnHook = (info: {
+    turn: number;
+    source: 'caller' | 'todo_continue' | 'result_repair';
+    /**
+     * The request this turn belongs to. ALWAYS KNOWN HERE - `scope.begin()` has run - and
+     * carried on the `hook_request` so a caller can correlate a `turn_start` round trip
+     * with the request it belongs to; a synthesized `turn_<n>` would collide across two
+     * requests inside one thread.
+     */
+    requestId: string;
+}) => Promise<BeforeTurnResult | void>;
+/** What `prompt_pre` decided about one caller message. */
+export interface PromptPreDecision {
+    action: 'allow' | 'rewrite' | 'deny';
+    /** The text the model will actually receive, on `rewrite`. */
+    text?: string;
+    reason?: string;
+    message?: string;
+    /** A stable code for the `ack` / `request_end.error` when denied. */
+    code?: string;
+    /** Whether the denial makes the REQUEST a failure (a hook deny does). */
+    isError?: boolean;
+}
+export interface ExecRunnerHookPort {
+    /** Never rejects: every failure arrives as a decision. */
+    promptPre(input: {
+        text: string;
+        queued: boolean;
+        requestId: string;
+    }): Promise<PromptPreDecision>;
 }
 export interface ExecCompactionBilling {
     usage: TokenUsage;
@@ -91,6 +232,20 @@ export interface ExecRunStats {
     turns: number;
     usage: TokenUsage;
     lastAssistantText: string;
+    /**
+     * The LAST accepted structured result of this process, or absent.
+     *
+     * PROCESS-LEVEL ON PURPOSE, while the SINK is per request (I-S8): `result` is one
+     * event for the whole run and must not report "nothing was accepted" because the
+     * final request happened to be a follow-up that submitted nothing. A per-request
+     * reader (`request_end.structured`) uses the sink, not this.
+     */
+    lastStructured?: {
+        value: unknown;
+        attempts: number;
+    };
+    /** True when a schema was given and nothing was ever accepted (I-S5). */
+    resultUnsatisfied: boolean;
     errored: boolean;
     stopReason: ExecStopReason;
     errorCode: string | null;
@@ -105,6 +260,11 @@ export declare class ExecRunner {
     private readonly now;
     private readonly progress;
     private controller;
+    /** Set by `attachBridge`; absent in every non-bridge run (I-1). */
+    private bridge;
+    private bridgeSource;
+    /** The caller's id for the turn currently running, if there is one. */
+    private requestId;
     private unsubscribers;
     /** Per-job progress throttle state: the last text emitted, and when. */
     private readonly jobProgressAt;
@@ -121,11 +281,48 @@ export declare class ExecRunner {
     private errorMessage;
     private signalNumber;
     private 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.
+     */
+    private pendingInjection;
+    /**
+     * 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.
+     */
+    private steeringReceipts;
     private budgetTimer;
     private timerStarted;
     private detached;
     private lastSignalAt;
+    /**
+     * 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.
+     */
+    private readonly requestScope;
+    /** True between the request's `ack` and its `request_end`. */
+    private requestInFlight;
+    /** Repair continuations used by the request in flight. */
+    private repairsUsed;
+    private resultUnsatisfied;
+    /** The last value any request accepted, for the process-level `result` event. */
+    private lastStructured;
     constructor(options: ExecRunnerOptions);
+    /** `buildCost` when the composition root supplied it; zero-and-unknown otherwise. */
+    private costOf;
     /**
      * Subscribe to all four streams.
      *
@@ -136,6 +333,70 @@ export declare class ExecRunner {
      * multiple subscribers.
      */
     attach(controller: ExecRunnerController): void;
+    /**
+     * 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: BridgeServer, source?: BridgePromptSource): void;
+    /**
+     * `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.
+     */
+    private onSteerFrame;
+    /**
+     * `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`.
+     */
+    private onInterruptFrame;
+    /**
+     * `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: string | undefined, frameId: string | undefined): void;
+    /**
+     * 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.
+     */
+    private reportUnknownRequest;
+    /**
+     * 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.
+     */
+    private writeCancelledRequestEnd;
     /**
      * Map a supervisor event onto the `job` channel.
      *
@@ -174,12 +435,123 @@ export declare class ExecRunner {
      * the two faces cannot drift about what "unfinished" means.
      */
     run(source: ExecPromptSource): Promise<void>;
+    /**
+     * 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`.
+     */
+    private applyPromptPre;
+    /**
+     * 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.
+     */
+    private writeDeniedRequestEnd;
+    /**
+     * 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.
+     */
+    private markHookError;
+    /**
+     * 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.
+     */
+    private reportStrandedInjection;
+    /**
+     * 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.
+     */
+    private settleRequest;
+    /**
+     * 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.
+     */
+    private settlementInput;
+    /**
+     * 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.
+     */
+    private processStopForRequest;
+    /** The request-level error, or `null`. One place so `result` and `request_end` agree. */
+    private requestError;
     private onCompactionUsage;
     private requestSeq;
     private requestHadError;
     private isRequestCancelled;
     /** One caller message plus every auto-continuation it produces. */
     private runFollowThroughChain;
+    /**
+     * 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).
+     */
+    private resultContractOutcome;
+    /**
+     * 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.
+     */
+    private markResultUnsatisfied;
+    /**
+     * 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.
+     */
+    private haltRequestOnBudget;
+    /**
+     * 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.
+     */
+    private stopRequestOnBudget;
+    /**
+     * "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.
+     */
+    private checkResultComplete;
     /**
      * The wall clock starts at the FIRST `prompt()`, not at process start: the
      * caller is bounding the run, and config resolution plus a skills scan are not
@@ -258,7 +630,29 @@ export declare class ExecRunner {
      */
     requestInterrupt(): void;
     private onSignal;
+    /**
+     * 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.
+     */
     private emit;
+    /**
+     * 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.
+     */
+    private writeToBridge;
+    /** The correlation fields every attributable event carries in bridge mode. */
+    private correlation;
     /** Caller-facing prose. STDERR ALWAYS - stdout carries nothing but the schema. */
     private note;
     private onAgentEvent;