@sema-agent/core 5.60.1 → 5.62.0

package/dist/core/usage-window-store.js

@@ -24,6 +24,9 @@ export function resolveUsageWindows(windows) {
         if (typeof w.maxTokens !== "number" || !Number.isFinite(w.maxTokens) || w.maxTokens < 0) {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxTokens must be a finite, non-negative number (got ${String(w.maxTokens)})`);
         }
+        if (w.maxCostUsd !== undefined && (typeof w.maxCostUsd !== "number" || !Number.isFinite(w.maxCostUsd) || w.maxCostUsd < 0)) {
+            throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxCostUsd must be a finite, non-negative number of USD when present (got ${String(w.maxCostUsd)})`);
+        }
         if (w.anchor !== "first-use" && w.anchor !== "rolling") {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].anchor must be "first-use" or "rolling" (got ${String(w.anchor)})`);
         }
@@ -40,11 +43,34 @@ function rollingHorizonMs(windows) {
     }
     return widest;
 }
-export function chargeUsageRecord(record, tokens, at, windows) {
+export function windowsGovernCost(windows) {
+    return windows.some((w) => w.maxCostUsd !== undefined);
+}
+function maxCostMicroUsdOf(w) {
+    return w.maxCostUsd === undefined ? undefined : Math.ceil(Number((w.maxCostUsd * 1e6).toPrecision(12)));
+}
+export function chargeUsageRecord(record, tokens, at, windows, costMicroUsd) {
     const horizon = rollingHorizonMs(windows);
-    const keptSlots = horizon === undefined ? [] : record.slots.filter((s) => s.at > at - horizon).map((s) => ({ at: s.at, tokens: s.tokens }));
-    if (horizon !== undefined && tokens > 0)
-        keptSlots.push({ at, tokens });
+    const governsCost = windowsGovernCost(windows);
+    if (governsCost && costMicroUsd === undefined) {
+        throw usageConfigError("usage_window.store_cost_unanswered", "a usage-window CHARGE for a deployment that governs maxCostUsd arrived with no cost figure at all. Core supplies one (a number, or an explicit null for spend nothing could price) on every such charge, so an absent one means a store in the chain does not carry the cost argument — folding it to 0 would leave the money ceiling open forever with nothing able to notice. Forward `costMicroUsd` from `UsageWindowStore.charge` into `chargeUsageRecord`.");
+    }
+    const cost = governsCost && costMicroUsd !== null ? costMicroUsd : undefined;
+    const unknown = governsCost && costMicroUsd === null;
+    const moves = tokens > 0 || (cost !== undefined && cost > 0) || unknown;
+    const keptSlots = horizon === undefined
+        ? []
+        : record.slots
+            .filter((s) => s.at > at - horizon)
+            .map((s) => ({
+            at: s.at,
+            tokens: s.tokens,
+            ...(s.costMicroUsd === undefined ? {} : { costMicroUsd: s.costMicroUsd }),
+            ...(s.costUnknown === true ? { costUnknown: true } : {}),
+        }));
+    if (horizon !== undefined && moves) {
+        keptSlots.push({ at, tokens, ...(cost === undefined ? {} : { costMicroUsd: cost }), ...(unknown ? { costUnknown: true } : {}) });
+    }
     const buckets = [];
     for (const w of windows) {
         if (w.anchor !== "first-use")
@@ -54,11 +80,21 @@ export function chargeUsageRecord(record, tokens, at, windows) {
         const prior = record.buckets.find((b) => b.windowMs === w.windowMs);
         const lapsed = prior === undefined || at >= prior.openedAt + w.windowMs;
         if (lapsed) {
-            if (tokens > 0)
-                buckets.push({ windowMs: w.windowMs, openedAt: at, tokens });
+            if (moves) {
+                buckets.push({ windowMs: w.windowMs, openedAt: at, tokens, ...(cost === undefined ? {} : { costMicroUsd: cost }), ...(unknown ? { costUnknown: true } : {}) });
+            }
             continue;
         }
-        buckets.push({ windowMs: w.windowMs, openedAt: prior.openedAt, tokens: prior.tokens + tokens });
+        const priorCost = prior.costMicroUsd;
+        const nextCost = cost === undefined ? priorCost : (priorCost ?? 0) + cost;
+        const nextUnknown = unknown || prior.costUnknown === true;
+        buckets.push({
+            windowMs: w.windowMs,
+            openedAt: prior.openedAt,
+            tokens: prior.tokens + tokens,
+            ...(nextCost === undefined ? {} : { costMicroUsd: nextCost }),
+            ...(nextUnknown ? { costUnknown: true } : {}),
+        });
     }
     return { slots: keptSlots, buckets };
 }
@@ -66,6 +102,8 @@ export function readUsageRecord(record, windows, now) {
     const readings = [];
     for (const w of windows) {
         let tokens = 0;
+        let costMicroUsd = 0;
+        let costUnknown = false;
         let freesAt;
         if (w.anchor === "rolling") {
             const floor = now - w.windowMs;
@@ -74,6 +112,9 @@ export function readUsageRecord(record, windows, now) {
                 if (s.at <= floor)
                     continue;
                 tokens += s.tokens;
+                costMicroUsd += s.costMicroUsd ?? 0;
+                if (s.costUnknown === true)
+                    costUnknown = true;
                 if (oldest === undefined || s.at < oldest)
                     oldest = s.at;
             }
@@ -84,18 +125,44 @@ export function readUsageRecord(record, windows, now) {
             const row = record.buckets.find((b) => b.windowMs === w.windowMs);
             if (row !== undefined && now < row.openedAt + w.windowMs) {
                 tokens = row.tokens;
+                costMicroUsd = row.costMicroUsd ?? 0;
+                if (row.costUnknown === true)
+                    costUnknown = true;
                 freesAt = row.openedAt + w.windowMs;
             }
         }
-        const exhausted = tokens >= w.maxTokens;
+        const maxCostMicroUsd = maxCostMicroUsdOf(w);
+        const exhausted = tokens >= w.maxTokens || (maxCostMicroUsd !== undefined && costMicroUsd >= maxCostMicroUsd);
         const retryAfterMs = exhausted ? Math.max(1, freesAt === undefined ? w.windowMs : freesAt - now) : 0;
-        readings.push({ window: w, tokens, exhausted, retryAfterMs });
+        readings.push({
+            window: w,
+            tokens,
+            ...(maxCostMicroUsd !== undefined ? { costMicroUsd } : {}),
+            ...(maxCostMicroUsd !== undefined && costUnknown ? { costUnknown: true } : {}),
+            exhausted,
+            retryAfterMs,
+        });
     }
     return readings;
 }
-export function usageRetryAfterMs(readings) {
+export function usageRetryAfterMs(readings, windows) {
+    if (windows !== undefined) {
+        if (readings.length !== windows.length) {
+            throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger answered ${String(readings.length)} reading(s) for ${String(windows.length)} declared window(s) — the read contract is one reading per window, in the order given. A window with no reading was never evaluated: refused rather than treated as open.`);
+        }
+        for (let i = 0; i < windows.length; i++) {
+            const w = windows[i];
+            const echoed = readings[i].window;
+            if (echoed === undefined || echoed.windowMs !== w.windowMs || echoed.anchor !== w.anchor || echoed.maxTokens !== w.maxTokens || echoed.maxCostUsd !== w.maxCostUsd) {
+                throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger's reading #${String(i)} does not echo declared window #${String(i)} verbatim (declared: windowMs ${String(w.windowMs)}, ${String(w.anchor)}, maxTokens ${String(w.maxTokens)}, maxCostUsd ${String(w.maxCostUsd)}) — the read contract requires the window back verbatim, in order, so its ceilings are provably the ones evaluated. Refused rather than re-attributed.`);
+            }
+        }
+    }
     let worst;
     for (const r of readings) {
+        if (r.window?.maxCostUsd !== undefined && r.costMicroUsd === undefined) {
+            throw usageConfigError("usage_window.store_cost_unanswered", `the usage-window ledger answered a window that declares maxCostUsd ${String(r.window.maxCostUsd)} (windowMs ${String(r.window.windowMs)}, ${String(r.window.anchor)}) with NO costMicroUsd — the money ceiling was never evaluated. Refused rather than treated as open: the store must persist the cost charged to it and report what the window holds.`);
+        }
         if (!r.exhausted)
             continue;
         if (worst === undefined || r.retryAfterMs > worst)
@@ -105,9 +172,9 @@ export function usageRetryAfterMs(readings) {
 }
 export class InMemoryUsageWindowStore {
     records = new Map();
-    async charge(key, tokens, at, windows) {
+    async charge(key, tokens, at, windows, costMicroUsd) {
         const prior = this.records.get(key) ?? EMPTY_USAGE_WINDOW_RECORD;
-        this.records.set(key, chargeUsageRecord(prior, tokens, at, windows));
+        this.records.set(key, chargeUsageRecord(prior, tokens, at, windows, costMicroUsd));
     }
     async read(key, windows, now) {
         return readUsageRecord(this.records.get(key) ?? EMPTY_USAGE_WINDOW_RECORD, windows, now);

package/dist/engine/harness/agent-harness.d.ts

@@ -1,4 +1,4 @@
-import type { ActorAssertion, AssistantMessage, ImageContent, Model } from "../llm/index.js";
+import type { ActorAssertion, AssistantMessage, ImageContent, Model, UserMessage } from "../llm/index.js";
 import type { AgentMessage, AgentTool, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
 import { type EngineSegment } from "../../core/untrusted-text.js";
 import type { AbortResult, AgentHarnessEvent, AgentHarnessEventResultMap, AgentHarnessOptions, AgentHarnessOwnEvent, AgentHarnessResources, AgentHarnessStreamOptions, ExecutionEnv, PromptTemplate, Skill } from "./types.js";
@@ -47,6 +47,22 @@ export interface UserMessageProvenance {
      *  the parked-steer queue needs (pre-framing text + trust + inputId), which only the minting seam
      *  knows — hence opaque. */
     parkRecord?: unknown;
+    /** design/373 — an IMMEDIATE-class ("now") frame: the steer-lane enqueue inserts it ahead of the
+     *  first non-immediate frame (FIFO among immediates — the dequeue-priority form), the loop's
+     *  pre-request re-check sweeps it into the imminent turn, and {@link AgentHarness.interruptTurn}
+     *  may force the boundary for it. Class metadata only (a sidecar, judged at the mint) — it never
+     *  rides the message or the wire, and it grants NOTHING by itself: the interrupt is a separate,
+     *  caller-provenance verb. */
+    immediate?: true;
+    /** design/373 (#445 saturation prerequisite) — terminal-preference at the engine-note backlog
+     *  cap: when the target queue's engine-note count is AT the cap, a frame carrying this mark
+     *  displaces the OLDEST non-preferred engine-note frame instead of being refused — the displaced
+     *  payload is handed to the undrained sink (the runner's lossless per-session park lane), so a
+     *  watcher's event storm can delay its own batches but never crowd a terminal completion out of
+     *  the run that is waiting on it (the pend store's terminal-preferred eviction, mirrored at the
+     *  queue mouth). Only meaningful WITH `enginePayload`; a preferred frame among only preferred
+     *  frames still gets the cap refusal (nothing displaceable). */
+    capPreferred?: true;
 }
 /**
  * Harness-level recovery wiring (design/118 ④b/⑤). The loop's prompt-too-long seam wants a
@@ -190,6 +206,9 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private loopRecovery?;
     /** roadmap #5 (CC Stop hook): the runner-wired stop gate — see {@link setStopGate}. */
     private stopGate?;
+    /** design/373 — the loop-published turn-scoped AbortController (live exactly while a main turn's
+     *  work phase is in flight; `undefined` between turns). Read by {@link interruptTurn} only. */
+    private turnInterruptSeat?;
     private handlers;
     constructor(options: AgentHarnessOptions<TSkill, TPromptTemplate, TTool>);
     private getHandlers;
@@ -264,12 +283,49 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  engine lanes each check the halt fact before injecting, so this arm exists for the lane that
      *  does not — including the one not written yet. */
     private refuseHeldEngineInjection;
+    /** design/373 — returns the minted queue frame (or `undefined` on the empty-injection no-op), so
+     *  a caller-provenance immediate steer can hand the SAME frame to {@link interruptTurn} (the
+     *  consumption guard is identity-keyed). Additive: every existing caller awaited `void`. */
     steer(text: string, options?: {
         images?: ImageContent[];
-    } & UserMessageProvenance): Promise<void>;
+    } & UserMessageProvenance): Promise<UserMessage | undefined>;
     followUp(text: string, options?: {
         images?: ImageContent[];
     } & UserMessageProvenance): Promise<void>;
+    /**
+     * design/373 §3.4 — force the running turn's boundary FOR a queued immediate-class frame:
+     * abort the CURRENT main turn (provider stream + tool batch — never the run, never boundary
+     * housekeeping), whose loop-side settlement reconciles the cut and continues the run with the
+     * frame at the queue head. Best-effort accelerator by contract: `false` means no interruption
+     * happened AND none was needed — the frame is already consumed or already rides the imminent
+     * boundary — so delivery semantics are exactly the non-interrupting ones either way.
+     *
+     * Guards, in order:
+     *  - an unwinding run (`abort()` latched) owns its ending — never contest it;
+     *  - CONSUMPTION guard (r4/R3-1): the frame must still sit in the steer queue. Drained/consumed ⇒
+     *    it is already part of a turn's input — aborting THAT turn would cut the very delivery this
+     *    verb exists to speed up. Same-tick check-then-abort (single-threaded: no window);
+     *  - seat liveness: no published turn (idle tail / between turns / boundary housekeeping) ⇒ no-op,
+     *    the frame rides the next boundary; an already-fired seat ⇒ idempotent no-op (one boundary per
+     *    turn — later immediates join the same boundary batch).
+     */
+    interruptTurn(frame: AgentMessage): boolean;
+    /**
+     * design/373 §3.3 (the final-commit-point double check) — how many queued injection frames a
+     * boundary drain could deliver RIGHT NOW: both lanes, minus frames the current state refuses to
+     * drain (an unwinding run drains nothing — those frames belong to the terminal account; a live
+     * human-halt hold skips engine-authored frames). Synchronous and side-effect-free by contract:
+     * the loop reads it between its last drain and the terminal commit, with zero awaits.
+     */
+    pendingInjectionCount(): number;
+    /** design/373 §3.4-3 — the pre-request re-check's drain half (see the loop-config seam): sweep
+     *  queued immediate-class frames into the imminent turn's batch, merged at the class position
+     *  (after immediates already pending, ahead of everything else — FIFO within the class holds
+     *  across the drain/re-check split). Same booking discipline as {@link drainQueuedMessages}
+     *  (in-flight account, queue_update broadcast, consumption sink, throw-rollback); the hold skips
+     *  engine-authored immediates exactly as the boundary drain would (a theoretical lane today —
+     *  no engine mint issues immediates — held by construction rather than by remembering). */
+    private absorbImmediateSteering;
     nextTurn(text: string, options?: {
         images?: ImageContent[];
     } & UserMessageProvenance): Promise<void>;

package/dist/engine/harness/agent-harness.js

@@ -38,6 +38,8 @@ const engineNotePayloads = new WeakMap();
 const engineAuthoredInjections = new WeakSet();
 const userInputParkRecords = new WeakMap();
 const drainedFromLane = new WeakMap();
+const immediateClassInjections = new WeakSet();
+const capPreferredInjections = new WeakSet();
 function isEngineAuthoredInjection(options) {
     if (options === undefined)
         return false;
@@ -257,6 +259,7 @@ export class AgentHarness {
     nextTurnQueue = [];
     loopRecovery;
     stopGate;
+    turnInterruptSeat;
     handlers = new Map();
     constructor(options) {
         this.env = options.env;
@@ -598,6 +601,11 @@ export class AgentHarness {
                 };
             },
             getSteeringMessages: async () => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode),
+            publishTurnInterruptSeat: (seat) => {
+                this.turnInterruptSeat = seat;
+            },
+            recheckImmediateInjections: async (pending) => this.absorbImmediateSteering(pending),
+            pendingInjectionCount: () => this.pendingInjectionCount(),
             getFollowUpMessages: async () => {
                 const queued = await this.drainQueuedMessages(this.followUpQueue, this.followUpQueueMode);
                 if (queued.length > 0)
@@ -841,9 +849,16 @@ export class AgentHarness {
     }
     async enqueueInjection(queue, text, options) {
         if (AgentHarness.emptyInjection(text, options))
-            return;
+            return undefined;
+        let displaced;
         if (options?.enginePayload !== undefined && queue.filter((q) => engineNotePayloads.has(q)).length >= ENGINE_NOTE_STEER_BACKLOG_CAP) {
-            throw new AgentHarnessError("invalid_state", `engine-note backlog at cap (${ENGINE_NOTE_STEER_BACKLOG_CAP}) — park the payload for the session's next run`);
+            const victimIdx = options.capPreferred === true
+                ? queue.findIndex((q) => engineNotePayloads.has(q) && !capPreferredInjections.has(q))
+                : -1;
+            if (victimIdx === -1) {
+                throw new AgentHarnessError("invalid_state", `engine-note backlog at cap (${ENGINE_NOTE_STEER_BACKLOG_CAP}) — park the payload for the session's next run`);
+            }
+            displaced = { frame: queue.splice(victimIdx, 1)[0], at: victimIdx };
         }
         const m = createUserMessage(text, options?.images, options);
         if (options?.enginePayload !== undefined)
@@ -852,8 +867,43 @@ export class AgentHarness {
             engineAuthoredInjections.add(m);
         if (options?.parkRecord !== undefined)
             userInputParkRecords.set(m, options.parkRecord);
-        queue.push(m);
-        await this.emitQueueUpdate();
+        if (options?.immediate === true)
+            immediateClassInjections.add(m);
+        if (options?.capPreferred === true && options?.enginePayload !== undefined)
+            capPreferredInjections.add(m);
+        if (options?.immediate === true && queue === this.steerQueue) {
+            let at = 0;
+            while (at < queue.length && immediateClassInjections.has(queue[at]))
+                at++;
+            queue.splice(at, 0, m);
+        }
+        else {
+            queue.push(m);
+        }
+        try {
+            await this.emitQueueUpdate();
+        }
+        catch (error) {
+            const at = queue.indexOf(m);
+            if (at !== -1) {
+                queue.splice(at, 1);
+                if (displaced !== undefined)
+                    queue.splice(Math.min(displaced.at, queue.length), 0, displaced.frame);
+                throw error;
+            }
+        }
+        if (displaced !== undefined) {
+            const victimPayload = engineNotePayloads.get(displaced.frame);
+            engineNotePayloads.delete(displaced.frame);
+            if (victimPayload !== undefined && this.onUndrainedEngineNotes) {
+                try {
+                    this.onUndrainedEngineNotes([victimPayload]);
+                }
+                catch {
+                }
+            }
+        }
+        return m;
     }
     refuseHeldEngineInjection(options) {
         if (isEngineAuthoredInjection(options) && this.engineInjectionsHeld?.() === true) {
@@ -865,7 +915,7 @@ export class AgentHarness {
             throw new AgentHarnessError("invalid_state", "Cannot steer while idle");
         }
         this.refuseHeldEngineInjection(options);
-        await this.enqueueInjection(this.steerQueue, text, options);
+        return await this.enqueueInjection(this.steerQueue, text, options);
     }
     async followUp(text, options) {
         if (this.phase === "idle") {
@@ -874,6 +924,66 @@ export class AgentHarness {
         this.refuseHeldEngineInjection(options);
         await this.enqueueInjection(this.followUpQueue, text, options);
     }
+    interruptTurn(frame) {
+        if (this.aborting)
+            return false;
+        if (!this.steerQueue.includes(frame))
+            return false;
+        const seat = this.turnInterruptSeat;
+        if (seat === undefined || seat.signal.aborted)
+            return false;
+        seat.abort();
+        return true;
+    }
+    pendingInjectionCount() {
+        if (this.aborting)
+            return 0;
+        const held = this.engineInjectionsHeld?.() === true;
+        const drainable = (q) => held ? q.filter((m) => !engineAuthoredInjections.has(m)).length : q.length;
+        return drainable(this.steerQueue) + drainable(this.followUpQueue);
+    }
+    async absorbImmediateSteering(pending) {
+        if (this.aborting)
+            return pending;
+        const held = this.engineInjectionsHeld?.() === true;
+        const taken = [];
+        for (let i = 0; i < this.steerQueue.length; i++) {
+            const m = this.steerQueue[i];
+            if (!immediateClassInjections.has(m))
+                break;
+            if (held && engineAuthoredInjections.has(m))
+                continue;
+            taken.push(...this.steerQueue.splice(i, 1));
+            i--;
+        }
+        if (taken.length === 0)
+            return pending;
+        for (const m of taken)
+            drainedFromLane.set(m, "steer");
+        this.drainedPendingInjection.push(...taken);
+        try {
+            await this.emitQueueUpdate();
+            for (const m of taken) {
+                const payload = engineNotePayloads.get(m);
+                if (payload !== undefined) {
+                    try {
+                        this.onEngineNoteConsumed?.(payload);
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
+        catch (error) {
+            this.steerQueue.unshift(...taken);
+            this.unbookInFlight(taken);
+            throw normalizeHookError(error);
+        }
+        let at = 0;
+        while (at < pending.length && immediateClassInjections.has(pending[at]))
+            at++;
+        return [...pending.slice(0, at), ...taken, ...pending.slice(at)];
+    }
     async nextTurn(text, options) {
         await this.enqueueInjection(this.nextTurnQueue, text, options);
     }

package/dist/engine/loop/agent-loop.js

@@ -1,5 +1,6 @@
 import { findToolByName, validateToolArguments } from "../llm/index.js";
 import { truncateError } from "../../core/tool-errors.js";
+import { INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER, INTERRUPTED_BY_USER_MARKER, } from "../../core/session-reconcile.js";
 import { resolveAgentCoreStreamFn } from "./runtime-deps.js";
 function appendTextDeltaToAssistantMessage(message, contentIndex, delta) {
     const content = [...message.content];
@@ -158,6 +159,13 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
         if (!state.hasMoreToolCalls && state.pendingMessages.length === 0) {
             const followUpMessages = (await state.config.getFollowUpMessages?.()) || [];
             if (followUpMessages.length === 0) {
+                if ((state.config.pendingInjectionCount?.() ?? 0) > 0) {
+                    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+                    if (state.pendingMessages.length > 0) {
+                        trace?.({ kind: "continue", reason: "steer_injected" });
+                    }
+                    continue;
+                }
                 trace?.({ kind: "terminal", reason: "completed" });
                 break;
             }
@@ -193,6 +201,38 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
     else {
         state.firstTurn = false;
     }
+    const turnController = new AbortController();
+    const onRunAbort = () => turnController.abort();
+    if (signal !== undefined) {
+        if (signal.aborted)
+            turnController.abort();
+        else
+            signal.addEventListener("abort", onRunAbort, { once: true });
+    }
+    let seatLive = false;
+    const publishSeat = () => {
+        seatLive = true;
+        state.config.publishTurnInterruptSeat?.(turnController);
+    };
+    const retractSeat = () => {
+        if (!seatLive)
+            return;
+        seatLive = false;
+        state.config.publishTurnInterruptSeat?.(undefined);
+    };
+    try {
+        return await runTurnPhases(state, signal, turnController, publishSeat, retractSeat, emit, streamFn, runtime, trace);
+    }
+    finally {
+        retractSeat();
+        signal?.removeEventListener("abort", onRunAbort);
+    }
+}
+async function runTurnPhases(state, signal, turnController, publishSeat, retractSeat, emit, streamFn, runtime, trace) {
+    publishSeat();
+    if (state.config.recheckImmediateInjections) {
+        state.pendingMessages = await state.config.recheckImmediateInjections(state.pendingMessages);
+    }
     if (state.pendingMessages.length > 0) {
         for (const message of state.pendingMessages) {
             await emit({ type: "message_start", message });
@@ -201,7 +241,7 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
             state.newMessages.push(message);
         }
     }
-    let executor = new StreamToolExecutor(state.context, state.config, signal, emit);
+    let executor = new StreamToolExecutor(state.context, state.config, turnController.signal, emit);
     const staticReasoningCutDowngrade = state.config.recovery?.truncatedOutput !== undefined &&
         state.staticReasoningCutRecoveries < MAX_STATIC_REASONING_CUT_RECOVERIES;
     const ptl = state.config.recovery?.promptTooLong;
@@ -210,7 +250,7 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
     let withhold = withholdEnabled ? createPtlWithholdBuffer(emit, ptlDetect) : undefined;
     let message;
     try {
-        message = await streamAssistantResponse(state.context, state.config, signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
+        message = await streamAssistantResponse(state.context, state.config, turnController.signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
     }
     finally {
         await executor.settle();
@@ -246,9 +286,9 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
                 withhold = withholdEnabled ? createPtlWithholdBuffer(emit, ptlDetect) : undefined;
                 state.context.messages = replaced;
                 trace?.({ kind: "continue", reason: "reactive_compact_retry" });
-                executor = new StreamToolExecutor(state.context, state.config, signal, emit);
+                executor = new StreamToolExecutor(state.context, state.config, turnController.signal, emit);
                 try {
-                    message = await streamAssistantResponse(state.context, state.config, signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
+                    message = await streamAssistantResponse(state.context, state.config, turnController.signal, withhold?.sink ?? emit, streamFn, runtime, executor, staticReasoningCutDowngrade);
                 }
                 finally {
                     await executor.settle();
@@ -261,6 +301,10 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
     state.newMessages.push(message);
     if (message.staticReasoningCut === true)
         state.staticReasoningCutRecoveries++;
+    if (message.stopReason === "aborted" && turnController.signal.aborted && !signal?.aborted) {
+        retractSeat();
+        return await settleInterruptedTurn(state, message, executor, [], signal, emit);
+    }
     {
         const degen = state.config.recovery?.degenerateOutput;
         if (degen &&
@@ -270,6 +314,7 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
             executor.admittedCount === 0 &&
             message.content.every((b) => b.type !== "toolCall") &&
             state.degenerateContinues < (degen.maxContinues ?? 2)) {
+            retractSeat();
             state.degenerateContinues++;
             await emit({ type: "turn_end", message, toolResults: [] });
             const drained = (await state.config.getSteeringMessages?.()) || [];
@@ -280,7 +325,8 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
             state.degenerateContinues = 0;
     }
     if (message.stopReason === "error" || message.stopReason === "aborted") {
-        const errorFinalResults = await harvestExecutorOnErrorFinal(executor, state, message, signal, emit);
+        retractSeat();
+        const errorFinalResults = await harvestExecutorOnErrorFinal(executor, state, message, turnController.signal, emit);
         await emit({ type: "turn_end", message, toolResults: errorFinalResults });
         await emit({ type: "agent_end", messages: state.newMessages });
         return { kind: "terminal", reason: "assistant_error" };
@@ -289,7 +335,7 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
     const toolResults = [];
     state.hasMoreToolCalls = false;
     if (toolCalls.length > 0) {
-        const executedToolBatch = await executeToolCalls(state.context, message, state.config, signal, emit, executor);
+        const executedToolBatch = await executeToolCalls(state.context, message, state.config, turnController.signal, emit, executor);
         toolResults.push(...executedToolBatch.messages);
         state.hasMoreToolCalls = !executedToolBatch.terminate;
         for (const result of toolResults) {
@@ -303,6 +349,10 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
             await closeOrphanedStreamEntry(orphan, emit);
         }
     }
+    retractSeat();
+    if (toolCalls.length > 0 && turnController.signal.aborted && !signal?.aborted) {
+        return await settleInterruptedTurn(state, message, executor, toolResults, signal, emit);
+    }
     await emit({ type: "turn_end", message, toolResults });
     const nextTurnContext = {
         message,
@@ -311,15 +361,7 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
         newMessages: state.newMessages,
     };
     const nextTurnSnapshot = await state.config.prepareNextTurn?.(nextTurnContext);
-    if (nextTurnSnapshot) {
-        state.context = nextTurnSnapshot.context ?? state.context;
-        state.config = Object.assign({}, state.config, {
-            model: nextTurnSnapshot.model ?? state.config.model,
-            reasoning: nextTurnSnapshot.thinkingLevel === undefined
-                ? state.config.reasoning
-                : nextTurnSnapshot.thinkingLevel,
-        });
-    }
+    adoptNextTurnSnapshot(state, nextTurnSnapshot);
     if (await state.config.shouldStopAfterTurn?.({
         message,
         toolResults,
@@ -383,6 +425,102 @@ async function runSingleTurn(state, signal, emit, streamFn, runtime, trace) {
     }
     return { kind: "ran" };
 }
+function adoptNextTurnSnapshot(state, nextTurnSnapshot) {
+    if (!nextTurnSnapshot)
+        return;
+    state.context = nextTurnSnapshot.context ?? state.context;
+    state.config = Object.assign({}, state.config, {
+        model: nextTurnSnapshot.model ?? state.config.model,
+        reasoning: nextTurnSnapshot.thinkingLevel === undefined
+            ? state.config.reasoning
+            : nextTurnSnapshot.thinkingLevel,
+    });
+}
+const TURN_INTERRUPTED_TOOL_TEXT = "[INTERRUPTED] The user interrupted this turn before this tool call started. It was never executed and " +
+    "had no side effects. Address the user's interjection first; re-issue the call afterwards if it is still needed.";
+async function settleInterruptedTurn(state, message, executor, committedResults, signal, emit) {
+    const toolResults = [...committedResults];
+    toolResults.push(...(await harvestExecutorOnErrorFinal(executor, state, message, signal, emit)));
+    const turnCalls = message.content.filter((c) => c.type === "toolCall");
+    const answered = new Set(toolResults.map((r) => r.toolCallId));
+    for (const call of turnCalls) {
+        if (answered.has(call.id))
+            continue;
+        await emit({
+            type: "tool_execution_start",
+            toolCallId: call.id,
+            toolName: call.name,
+            args: call.arguments,
+        });
+        const finalized = {
+            toolCall: call,
+            result: {
+                content: [{ type: "text", text: TURN_INTERRUPTED_TOOL_TEXT }],
+                details: { errorKind: "interrupted_never_started" },
+            },
+            isError: true,
+        };
+        await emit({
+            type: "tool_execution_end",
+            toolCallId: call.id,
+            toolName: call.name,
+            result: finalized.result,
+            isError: true,
+            notExecuted: true,
+        });
+        const toolResultMessage = createToolResultMessage(finalized);
+        await emitToolResultMessage(toolResultMessage, emit);
+        state.context.messages.push(toolResultMessage);
+        state.newMessages.push(toolResultMessage);
+        toolResults.push(toolResultMessage);
+    }
+    if (turnCalls.length === 0 &&
+        isBlankFailureContent(message) &&
+        state.context.messages[state.context.messages.length - 1] === message) {
+        state.context.messages.pop();
+        if (state.newMessages[state.newMessages.length - 1] === message)
+            state.newMessages.pop();
+    }
+    const marker = {
+        role: "user",
+        content: [
+            {
+                type: "text",
+                text: turnCalls.length > 0 ? INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER : INTERRUPTED_BY_USER_MARKER,
+            },
+        ],
+        provenance: "engine-note",
+        timestamp: Date.now(),
+    };
+    await emit({ type: "message_start", message: marker });
+    await emit({ type: "message_end", message: marker });
+    state.context.messages.push(marker);
+    state.newMessages.push(marker);
+    state.hasMoreToolCalls = false;
+    await emit({ type: "turn_end", message, toolResults });
+    if (signal?.aborted) {
+        await emit({ type: "agent_end", messages: state.newMessages });
+        return { kind: "terminal", reason: "aborted_before_stream" };
+    }
+    const nextTurnSnapshot = await state.config.prepareNextTurn?.({
+        message,
+        toolResults,
+        context: state.context,
+        newMessages: state.newMessages,
+    });
+    adoptNextTurnSnapshot(state, nextTurnSnapshot);
+    if (await state.config.shouldStopAfterTurn?.({
+        message,
+        toolResults,
+        context: state.context,
+        newMessages: state.newMessages,
+    })) {
+        await emit({ type: "agent_end", messages: state.newMessages });
+        return { kind: "terminal", reason: "stop_requested" };
+    }
+    state.pendingMessages = (await state.config.getSteeringMessages?.()) || [];
+    return { kind: "ran" };
+}
 async function streamAssistantResponse(context, config, signal, emit, streamFn, runtime, executor, staticReasoningCutDowngrade) {
     let messages = context.messages;
     if (config.transformContext) {