@sema-agent/core 5.60.0 → 5.61.0

package/dist/core/types.d.ts

@@ -4177,6 +4177,12 @@ export type TaskEvent = ({
      */
     type: "task_notification";
     notification: TaskNotificationPayload;
+    /** design/373 §3.6 — the frame's injection tier as DELIVERED (additive; consumers tolerate
+     *  absence): on the live lane, the tier the routing used (`next`/`now` → steer lane, `later`
+     *  → followUp lane); on the turn-open redelivery lane, the tier the park CARRIED. ABSENT is a
+     *  fact, not a default: a pre-373 producer event, or a parked record whose tier was not
+     *  carried (the terminal sweep's re-pend) — never read absence as `"later"`. */
+    priority?: import("./task-notification.js").SystemInjectionPriority;
 } & TaskEventIdentity) | ({
     /**
      * design/99 MF-10 — a SUBAGENT PROGRESS TICK: the delegated sub-run's usage ACCRUING
@@ -4380,11 +4386,43 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      *    into this run's resume prompt) is NOT in it and WOULD inject again. A deployment that needs
      *    cross-leg or cross-process idempotency owns that half (its own key ledger), the same division
      *    of labor `notify`'s park-window dedup states.
+     *
+     * design/373 (additive) — `priority` is the steer face's injection tier, default `"next"`
+     * (= the pre-373 behavior, byte-identical):
+     *  - `"next"` — the running turn's next boundary (unchanged);
+     *  - `"later"` — never folded into work in progress: delivered at the run's natural
+     *    would-otherwise-stop seat (its own closing turn); a run that ends before that seat re-parks
+     *    the input via the existing durable/undrained lanes (receipt semantics unchanged — "queued"
+     *    still means accepted-at-this-moment, never "consumed"); a `"later"` steer rides the followUp
+     *    lane, so its stranded account is `task.user_followup_undrained` (the accounts are LANE-keyed
+     *    — same two-key split the settled frame uses);
+     *  - `"now"` — `"next"`'s delivery guarantee PLUS the boundary is manufactured early: the frame
+     *    takes the queue's class head and, when a turn is in flight, the engine CUTS that turn at a
+     *    reconciled boundary (finished tool calls keep their real results; never-started ones settle
+     *    as paired interrupted results; the CC-verbatim interruption marker lands) and the run
+     *    CONTINUES with this input — never the run-level `interrupt()`. Best-effort accelerator:
+     *    with nothing in flight (idle tail, between turns) delivery is exactly `"next"`'s. Every
+     *    real cut is announced (`task.turn_interrupted` notice) and counts toward `maxTurns` —
+     *    deliberately (the hard cap IS the interrupt storm's bound), which means a `now` issued at
+     *    the run's FINAL allowed turn spends the remaining budget on the cut and the run then ends
+     *    at the limit before the steer's own turn: the input takes the terminal lanes like any
+     *    accepted-but-undelivered steer (durable park when a resource-suspend seat is eligible —
+     *    redeemed on resume; otherwise the loud `task.user_steer_undrained` account). Same for the
+     *    other terminal gates (budget/walltime) firing at the cut's own `turn_end`. The receipt
+     *    never promised consumption; no budget is reserved for the interruptor.
+     *  ⚠️ POWER FACE (§5-4b): passing `priority` through to a third-party caller GRANTS it the power
+     *    to cut this run's in-flight turns (cancelling that turn's in-flight tool work). A deployment
+     *    relaying steer must gate this option at its own face — relay IS authorization.
+     *  An unknown value throws typed `steering.invalid_content` (bad-value loudness). The replay
+     *  identity (`inputId` idempotency) includes the NORMALIZED tier: the same text replayed under
+     *  the same id at a different tier refuses `steering.duplicate_input_id` — an "idempotent
+     *  success" that silently skipped the interrupt would be a disposition lie.
      */
     steer(text: string, options?: {
         trusted?: boolean;
         actor?: ActorAssertion;
         inputId?: string;
+        priority?: import("./task-notification.js").SystemInjectionPriority;
     }): Promise<void>;
     /**
      * design/144 §2 — inject an EXTERNAL structured event into this run's task-notification lane, as a
@@ -4392,19 +4430,37 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      * the payload (`task_type` is cast to `"external"` — a caller can never impersonate an internal lane)
      * and every field is sanitized as UNTRUSTED data on the model face. Delivery rides the EXISTING
      * notification machinery, so the semantics are identical to internal producers:
-     *  - every priority is injected at the NEXT turn boundary (steer lane, mid-work included; ruled
-     *    2026-08-05 — the retired `"later"`→followUp mapping starved a busy run of its completions).
-     *    Delivery order is ARRIVAL order; consecutive buffered notifications drain as one boundary
-     *    batch. `priority` still rides the park/uplink path for torn-down lanes;
+     *  - design/373 — the injection LADDER is live on this lane (BREAKING vs the flat era, named):
+     *    `"next"` = the running turn's next boundary (mid-work included — the previous behavior of
+     *    every frame, now this tier's); `"later"` = never folded into work in progress — delivered at
+     *    the run's natural would-otherwise-stop seat (its own closing turn), and a run that ends
+     *    before that seat parks the frame per session for the NEXT run's turn-open (delivery then
+     *    depends on a next run happening — a recorded structural honesty note, this engine owns no
+     *    idle process); `"now"` is REFUSED typed (`notify.invalid_priority`) — turn-interrupt
+     *    authority belongs to the caller-provenance steer face, never to the notification lane
+     *    (callers wanting earliest-boundary delivery say `"next"`). ⚠️ The parameterless DEFAULT is
+     *    `"later"` (the CC pending-notification default): an omitted priority moved from
+     *    next-boundary to the closing seat with this design — callers that need boundary delivery
+     *    must say `"next"` explicitly. NOTE for the flat era's callers: `"later"` was silently inert
+     *    then (delivered at the boundary with no runtime signal saying otherwise) — the version is
+     *    the ONLY discriminator of which behavior a build has. Delivery order within a tier is
+     *    ARRIVAL order; consecutive buffered notifications drain as one boundary batch. `priority`
+     *    rides the park path (pend records carry it; the turn-open batch is priority-major) and the
+     *    uplink path;
      *  - duplicate events dedup on `task_id:status[:seq]` — pass a fresh `seq` per repeat event. The
      *    external lane keys in its OWN dedup domain (design/144 X1): an external event can never collide
-     *    with (or pre-occupy) an internal lane's key, and vice versa;
+     *    with (or pre-occupy) an internal lane's key, and vice versa. The key deliberately excludes
+     *    `priority` (tier = delivery metadata, not event identity): a repeat under an in-flight key
+     *    folds WHATEVER tier it names — the standing entry keeps the FIRST accept's tier — so
+     *    re-tiering requires a fresh `seq` (a new occurrence), never a same-key resend;
      *  - a notify landing AFTER the run ended PARKS per session and the session's NEXT run delivers it
      *    (unlike {@link steer}, a finished task does not reject — the park lane is the contract). The park
      *    leg dedups on the same key (design/144 X4) with an HONEST WINDOW LIMIT: the dedup set spans ONE
      *    parked batch — it does not reach back across the live-queue/park boundary, and it resets when the
      *    next run drains the batch (a repeat sent after that drain is deliverable again);
-     * Throws typed `notify.invalid_payload` on a malformed input and `notify.not_running` when the run
+     * Throws typed `notify.invalid_payload` on a malformed input, `notify.invalid_priority` on
+     * `priority: "now"` (see above — a KNOWN value this lane refuses, distinct from an unknown one),
+     * and `notify.not_running` when the run
      * never built its notification lane (prepare failed). Everything upstream of the event reaching this
      * process — transport, webhook/daemon wiring, inbound authn, durable parking for idle sessions — is
      * the DEPLOYMENT half (design/43: zero daemon semantics in core).
@@ -4992,19 +5048,20 @@ export interface EngineNotice {
      *    — what is announced is the remainder that could NOT be carried, so a fully-migrated park says
      *    nothing at all and a queue-full / no-longer-pending row still says exactly what was lost.
      *
-     *  - `"task.injection_priority_unimplemented"` (#389 伴生, D-3) — a notification was injected with
-     *    `priority: "now"`. The three values are CC's names (`now`/`next`/`later`) but this engine
-     *    delivers all three identically at the next turn boundary: there is no arm that aborts the
-     *    running turn, so a caller writing `"now"` and expecting an interruption gets a plain queued
-     *    delivery. The frame IS delivered (this is disclosure, not a refusal — dropping an accepted
-     *    notification would be the worse error); what is announced is that the knob's promise is not
-     *    honored, so an operator can stop building on it. Once per run (the injection funnel is a
-     *    single site, and a busy lane must not narrate the same gap once per frame);
-     *    `detail: { priority, taskId?, sessionId }` — `sessionId` (#433, ALWAYS present: the funnel
-     *    sits past prepare, which owns a session unconditionally) is a correlation key only, the
-     *    audience stays `"operator"` (the party building on the unhonored knob is whoever called
-     *    notify, not the end user). An UNKNOWN priority value is a different fact with a
-     *    different posture — `TaskStream.notify` refuses it typed (`notify.invalid_payload`).
+     *  - `"task.turn_interrupted"` (design/373) — a caller-provenance steer with `priority: "now"`
+     *    ACTUALLY CUT the running turn: the in-flight provider stream / tool batch was aborted at a
+     *    manufactured boundary (finished tool calls keep their real results, never-started ones
+     *    settle as paired interrupted results, the interruption marker lands) and the run CONTINUES
+     *    with the steer at the queue head. One notice per REAL cut (a `now` that found nothing in
+     *    flight, or whose frame already rode the imminent boundary, announces nothing — no false
+     *    interrupt claims); every cut turn counts toward `maxTurns`, so an interrupt storm's cost is
+     *    bounded and each of its cuts is on the record. `detail: { inputId, sessionId, actorId?,
+     *    taskId? }` — `inputId` is the steer's own correlation key (the `human_input` frame's id),
+     *    `actorId` the caller's asserted identity when one rode the steer. Audience `"user"`: the
+     *    person whose input forced the boundary is the one entitled to see that it landed.
+     *    RETIRED here (BREAKING, named): `"task.injection_priority_unimplemented"` — the ladder is
+     *    implemented, so the unhonored-knob disclosure it carried has no referent; consumers must
+     *    judge ladder support by VERSION, never by that code's absence.
      *
      *  - `"memory.session_polluted"` (design/178 §3, #324a; message mode-aware since design/336) —
      *    this session's memory crossed into the one-way externally-exposed state (a tool classified

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) {