@sagentlab/navarch-runtime 0.1.131 → 0.1.132

package/dist/adapters/claude.cjs

@@ -247,12 +247,25 @@ function attachSession(result, options) {
         ...(rejected ? { resumeRejected: true } : {}),
     };
 }
-/** Parses the final `claude -p --output-format stream-json` result record for usage and folds it onto the raw result (best-effort; leaves tokensIn/tokensOut/costUsd unset when parsing fails). */
+/**
+ * Parses the `claude -p --output-format stream-json` result records for usage
+ * and folds them onto the raw result (best-effort; leaves
+ * tokensIn/tokensOut/costUsd unset when parsing fails). A streaming launch runs
+ * one turn per interrupt or late message, each ending in its own `result`:
+ * `usage` covers that turn alone, so the tokens are summed, while
+ * `total_cost_usd` is already the process's running total, so the last one counts.
+ */
 function attachUsage(result) {
     const parsed = (0, exit_conditions_cjs_1.parseClaudeJsonResult)(result.stdout);
     if (!parsed)
         return result;
     const usage = (0, exit_conditions_cjs_1.extractUsageFromClaudeJson)(parsed);
+    const turns = streamResultRecords(result.stdout).map(exit_conditions_cjs_1.extractUsageFromClaudeJson);
+    if (turns.length > 1) {
+        usage.tokensIn = turns.reduce((sum, turn) => sum + turn.tokensIn, 0);
+        usage.tokensOut = turns.reduce((sum, turn) => sum + turn.tokensOut, 0);
+        usage.cacheHitTokensIn = turns.reduce((sum, turn) => sum + turn.cacheHitTokensIn, 0);
+    }
     return {
         ...result,
         tokensIn: usage.tokensIn,
@@ -261,6 +274,26 @@ function attachUsage(result) {
         costUsd: usage.costUsd,
     };
 }
+/** Every stream-json `type: "result"` record, one per turn the process ran. */
+function streamResultRecords(stdout) {
+    const records = [];
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        try {
+            const record = JSON.parse(trimmed);
+            if (typeof record === "object" && record !== null && !Array.isArray(record) &&
+                record.type === "result") {
+                records.push(record);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return records;
+}
 async function runOnHost(options, args) {
     return new Promise((resolve) => {
         let stdout = "";
@@ -316,6 +349,12 @@ async function runOnHost(options, args) {
 }
 /** How long the process may stay open for a written message the agent has not echoed after its turn ended. */
 const UNECHOED_INPUT_GRACE_MS = 30_000;
+/**
+ * How long an interrupt waits for the stopped turn's `result` before its input
+ * is written anyway. Spike S1 saw the result at once; a CLI that ignores the
+ * request then reads the message at its next step, which the ack reports as a steer.
+ */
+const INTERRUPT_RESULT_TIMEOUT_MS = 15_000;
 /**
  * `claude -p --input-format stream-json --replay-user-messages`: the prompt is
  * the first user message, and stdin stays open so a steering message written
@@ -329,6 +368,14 @@ const UNECHOED_INPUT_GRACE_MS = 30_000;
  * in the pipe even after stdin ends and runs it as a further turn, but a
  * message written after the process has finished is silently dropped, which is
  * why `send` refuses once input is closed.
+ *
+ * Native interrupt (spike S1, claude 2.1.284 and 2.1.304): the control request
+ * `{"type":"control_request","request":{"subtype":"interrupt"}}` stops the
+ * running tool and ends the turn with a `result` of subtype
+ * `error_during_execution`, and the process and conversation stay. The
+ * interrupt's message is written only after that `result`, so it starts the
+ * next turn instead of joining the stopped one, and every message sent while
+ * the interrupt is pending waits behind it, in order (as the hosted relay does).
  */
 async function runOnHostStreaming(options, args, live) {
     return new Promise((resolve) => {
@@ -339,8 +386,14 @@ async function runOnHostStreaming(options, args, live) {
         let inputOpen = true;
         let lineBuffer = "";
         let graceTimer;
+        let interruptTimer;
+        let interruptRequests = 0;
+        // A turn is running: the prompt starts one, and a `result` ends it.
+        let turnRunning = true;
         // Written steering messages the agent has not echoed yet.
         const pending = new Map();
+        // Inputs waiting for the turn an interrupt is stopping, in the order they were sent.
+        const held = [];
         const child = (0, node_child_process_1.spawn)(options.bin, args, {
             detached: process.platform !== "win32",
             cwd: options.cwd,
@@ -374,20 +427,78 @@ async function runOnHostStreaming(options, args, live) {
             detach();
             child.stdin?.end();
         };
+        const canWrite = () => inputOpen && child.exitCode === null && !child.killed;
+        /** Writes one steering input. A message written while no turn runs starts the next one. */
+        const writeInput = (input, state) => {
+            try {
+                writeUser(input.id, input.text);
+            }
+            catch {
+                return false;
+            }
+            pending.set(input.id, state);
+            return true;
+        };
+        /**
+         * Writes what waited for the interrupted turn. `stopped` is null when the
+         * turn has not ended (no `result` came in time), so the inputs join it.
+         */
+        const releaseHeld = (stopped) => {
+            clearTimeout(interruptTimer);
+            interruptTimer = undefined;
+            // Input closed meanwhile: nothing is written, and the session takes them back.
+            if (!canWrite()) {
+                held.length = 0;
+                return;
+            }
+            // The first input (the interrupt that sent the request) starts the next
+            // turn and owns the stop; the rest join that turn.
+            let first = true;
+            for (const { input } of held.splice(0)) {
+                writeInput(input, {
+                    afterTurnEnd: first && stopped !== null,
+                    stoppedTurn: first && stopped === true,
+                });
+                first = false;
+            }
+            turnRunning = true;
+        };
         const promptId = (0, node_crypto_1.randomUUID)();
         writeUser(promptId, options.prompt);
         attached = true;
         live.attach({
             send: (input) => {
-                if (!inputOpen || child.exitCode !== null || child.killed)
+                if (!canWrite())
                     return false;
+                // Behind a pending interrupt, so the interrupt stays the next input.
+                if (held.length > 0) {
+                    held.push({ input, interrupt: false });
+                    return true;
+                }
+                return writeInput(input, { afterTurnEnd: !turnRunning, stoppedTurn: false });
+            },
+            interrupt: (input) => {
+                if (!canWrite())
+                    return false;
+                // Nothing to stop: the message starts the next turn, a boundary delivery.
+                if (!turnRunning)
+                    return writeInput(input, { afterTurnEnd: true, stoppedTurn: false });
+                held.push({ input, interrupt: true });
+                if (held.length > 1)
+                    return true;
                 try {
-                    writeUser(input.id, input.text);
+                    interruptRequests += 1;
+                    child.stdin?.write(`${JSON.stringify({
+                        type: "control_request",
+                        request_id: `navarch-interrupt-${interruptRequests}`,
+                        request: { subtype: "interrupt" },
+                    })}\n`);
                 }
                 catch {
+                    held.length = 0;
                     return false;
                 }
-                pending.set(input.id, { afterTurnEnd: false });
+                interruptTimer = setTimeout(() => releaseHeld(null), INTERRUPT_RESULT_TIMEOUT_MS);
                 return true;
             },
         });
@@ -405,7 +516,7 @@ async function runOnHostStreaming(options, args, live) {
             }
             if (typeof record !== "object" || record === null || Array.isArray(record))
                 return true;
-            const { type, uuid, isReplay } = record;
+            const { type, subtype, uuid, isReplay } = record;
             if (type === "user" && isReplay === true && typeof uuid === "string") {
                 // The echo of the task brief would copy the whole prompt into every
                 // transcript; a one-shot launch never prints it. Steering messages are
@@ -416,13 +527,33 @@ async function runOnHostStreaming(options, args, live) {
                 if (!entry)
                     return true;
                 pending.delete(uuid);
-                live.consumed(uuid, entry.afterTurnEnd);
+                // The agent took it in, so a turn is running again; its `result`
+                // decides whether input can close.
+                turnRunning = true;
+                clearTimeout(graceTimer);
+                live.consumed(uuid, entry.afterTurnEnd, entry.stoppedTurn);
+            }
+            else if (type === "control_response" && held.length > 0) {
+                // A CLI that refuses the interrupt stops nothing: the waiting inputs
+                // join the running turn now instead of after the 15 s fallback.
+                const response = record.response;
+                if (response?.subtype === "error" && response.request_id === `navarch-interrupt-${interruptRequests}`) {
+                    releaseHeld(null);
+                }
             }
             else if (type === "result") {
                 // A turn ended. A message written during it that was not echoed will
-                // start the next turn, so it now counts as consumed after the boundary.
+                // start the next turn, so it now counts as consumed after the boundary,
+                // and that next turn counts as running before its echo arrives: an
+                // interrupt in that gap must still stop it.
+                turnRunning = pending.size > 0;
                 for (const entry of pending.values())
                     entry.afterTurnEnd = true;
+                // An interrupt was waiting for this turn to end. Only a turn the request
+                // cut short ends in `error_during_execution`; one that finished first
+                // was not stopped, and its message is a boundary delivery.
+                if (held.length > 0)
+                    releaseHeld(subtype === "error_during_execution");
                 if (pending.size === 0)
                     closeInput();
                 else {
@@ -468,7 +599,9 @@ async function runOnHostStreaming(options, args, live) {
         });
         const finish = (exitCode) => {
             clearTimeout(timer);
-            clearTimeout(graceTimer);
+            // An input still waiting for an interrupted turn was never written: the
+            // session takes it back with every message the agent did not echo.
+            held.length = 0;
             inputOpen = false;
             detach();
             if (lineBuffer) {
@@ -480,6 +613,9 @@ async function runOnHostStreaming(options, args, live) {
                     options.onOutput?.("stdout", rest);
                 }
             }
+            // After the last line: a trailing `result` there can arm the grace timer.
+            clearTimeout(graceTimer);
+            clearTimeout(interruptTimer);
             options.signal?.removeEventListener("abort", onAbort);
             resolve({ exitCode, timedOut, killedByLeaseLoss, stdout, stderr });
         };
@@ -524,7 +660,9 @@ function readClaudeHelp(bin, env) {
 /**
  * Native steering needs `--input-format stream-json` and
  * `--replay-user-messages`, the host path (Docker `exec -i` has no streaming
- * runner here), and the stream formats left to Navarch.
+ * runner here), and the stream formats left to Navarch. The same streaming
+ * process takes the interrupt control request (spike S1), so native steering
+ * also brings native interrupt; without it, interrupt stays `restart`.
  */
 async function probeClaudeSteering(context) {
     if (context.sandboxMode !== "host")
@@ -534,7 +672,7 @@ async function probeClaudeSteering(context) {
     const help = await readClaudeHelp(context.bin, context.env);
     if (!/--input-format\b/.test(help) || !/--replay-user-messages\b/.test(help))
         return null;
-    return { steer: "native", queue: "boundary", interrupt: "restart" };
+    return { steer: "native", queue: "boundary", interrupt: "native" };
 }
 async function runViaDocker(options, args) {
     const { containerName, runner } = options.dockerExec;

package/dist/prompt.cjs

@@ -4,6 +4,7 @@ exports.renderPrompt = renderPrompt;
 exports.renderGuidanceCorrectionPrompt = renderGuidanceCorrectionPrompt;
 exports.renderMidFlightGuidanceSection = renderMidFlightGuidanceSection;
 exports.renderSteerInjection = renderSteerInjection;
+exports.renderInterruptInjection = renderInterruptInjection;
 exports.steeringPromptNote = steeringPromptNote;
 exports.renderResumedTurnPreamble = renderResumedTurnPreamble;
 exports.renderResumedGuidancePrompt = renderResumedGuidancePrompt;
@@ -133,6 +134,20 @@ function renderSteerInjection(entry) {
         block,
     ].join("\n");
 }
+/**
+ * The input a native interrupt hands the agent once its turn has stopped: the
+ * interrupt and every earlier message it carries, in `seq` order (section 6.4).
+ * The text is written before the outcome is known (the turn may have finished
+ * first), so it does not claim that a step was cut short.
+ */
+function renderInterruptInjection(entries) {
+    const blocks = entries.map((entry) => entry.steering ? steeringBlock(entry, entry.steering).trimEnd() : entry.content);
+    return [
+        "A teammate sent an interrupt: stop what you were doing and follow the messages below. They take precedence over earlier context. Continue in the same worktree. If your last step was cut short, it may have left half-finished edits, so run `git status` and review the recent changes first. If you already received a message with the same id, ignore this repeat.",
+        "",
+        blocks.join("\n\n"),
+    ].join("\n");
+}
 /**
  * The brief section that makes live messages credible and spoof-resistant. The
  * token is generated per lease and appears nowhere an attacker's content could

package/dist/steering.cjs

@@ -12,7 +12,10 @@
 // Most adapters take no input during a turn, so their messages are delivered
 // at the turn boundary or by restarting the turn. An adapter that reports
 // `steer: native` (Claude Code over streaming input) also takes a message into
-// the running turn, and confirms it when the agent has read it.
+// the running turn, and confirms it when the agent has read it. One that also
+// reports `interrupt: native` stops the running turn in the same process and
+// hands the agent an `interrupt_native` message as the next turn, with every
+// earlier message that was still waiting (section 6.4).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SteeringSession = void 0;
 exports.liveSteeringCapabilities = liveSteeringCapabilities;
@@ -95,7 +98,7 @@ class SteeringSession {
     /** What the adapter calls while it runs a turn that takes input (native steering). */
     liveInput = {
         attach: (channel) => this.attachChannel(channel),
-        consumed: (id, afterTurnEnd) => this.steerConsumed(id, afterTurnEnd),
+        consumed: (id, afterTurnEnd, stoppedTurn) => this.steerConsumed(id, afterTurnEnd, stoppedTurn ?? false),
     };
     constructor(options) {
         this.options = options;
@@ -203,9 +206,12 @@ class SteeringSession {
      */
     turnEnded() {
         this.channel = null;
-        for (const entry of this.entries.values())
-            if (entry.phase === "sent")
-                entry.phase = "held";
+        for (const entry of this.entries.values()) {
+            if (entry.phase !== "sent")
+                continue;
+            entry.phase = "held";
+            entry.carriedBy = null;
+        }
     }
     /** The agent process for the turn started, so it holds the messages: report them delivered. */
     markInjected(taken) {
@@ -268,10 +274,43 @@ class SteeringSession {
         this.channel = channel;
         if (!channel)
             return;
-        // A steer that arrived after this turn's prompt was built has no other way in.
-        for (const entry of this.entries.values())
+        // A message that arrived after this turn's prompt was built has no other way
+        // in. The latest waiting interrupt carries everything before it, so a steer
+        // written first cannot overtake it; later steers follow it.
+        const interrupt = this.bySeq().filter((entry) => entry.phase === "held" &&
+            entry.message.effective_mode === "interrupt_native").at(-1);
+        if (interrupt)
+            this.tryInterrupt(interrupt);
+        for (const entry of this.bySeq())
             this.trySteer(entry);
     }
+    bySeq() {
+        return [...this.entries.values()].sort((a, b) => a.message.seq - b.message.seq);
+    }
+    /**
+     * Stops the running turn natively and hands the agent the interrupt, with
+     * every earlier message still waiting, as one input in `seq` order (section
+     * 6.4). Left held when there is no channel that can interrupt: the next turn
+     * then carries it, and the ack reports a boundary delivery.
+     */
+    tryInterrupt(entry) {
+        if (entry.phase !== "held" || entry.message.effective_mode !== "interrupt_native" || !this.channel?.interrupt)
+            return;
+        const carried = this.bySeq().filter((other) => other.phase === "held" && other.message.seq <= entry.message.seq);
+        const sent = this.channel.interrupt({
+            id: entry.message.id,
+            text: (0, prompt_cjs_1.renderInterruptInjection)(carried.map((other) => this.guidanceFor(other.message, other === entry))),
+        });
+        if (!sent)
+            return;
+        for (const other of carried) {
+            other.phase = "sent";
+            other.carriedBy = entry.message.id;
+        }
+        const earlier = carried.slice(0, -1).map((other) => other.message.seq);
+        log.info(`interrupt message ${entry.message.id} (seq ${entry.message.seq}) is stopping the running turn` +
+            `${earlier.length > 0 ? `, carrying seq ${earlier.join(", ")}` : ""}.`);
+    }
     /** Writes a held `steer` message to the running agent. Left held when there is no open input. */
     trySteer(entry) {
         if (entry.phase !== "held" || entry.message.effective_mode !== "steer" || !this.channel)
@@ -285,30 +324,42 @@ class SteeringSession {
         entry.phase = "sent";
         log.info(`steer message ${entry.message.id} (seq ${entry.message.seq}) written to the running agent.`);
     }
-    /** The agent read a steered message: only now is it delivered. */
-    steerConsumed(id, afterTurnEnd) {
+    /**
+     * The agent read a message written to its input: only now is it delivered.
+     * For a native interrupt, that is every message its input carried.
+     */
+    steerConsumed(id, afterTurnEnd, stoppedTurn) {
         const entry = this.entries.get(id);
         if (!entry || entry.phase !== "sent")
             return;
-        entry.phase = "done";
-        this.options.onSteerConsumed?.(this.guidanceFor(entry.message, false));
-        // A message the agent read only after its turn ended began the next turn:
-        // that is a boundary delivery, whatever it was sent as.
-        const mode = afterTurnEnd ? "queue" : "steer";
-        void this.sendAck(id, entry.cancelRequested
-            ? {
-                state: "too_late",
-                effective_mode: mode,
-                detail: "The cancel arrived after the message was handed to the agent.",
-            }
-            : { state: "delivered", effective_mode: mode });
+        const batch = entry.carriedBy
+            ? this.bySeq().filter((other) => other.phase === "sent" && other.carriedBy === entry.carriedBy)
+            : [entry];
+        for (const item of batch) {
+            item.phase = "done";
+            item.carriedBy = null;
+            // `interrupt_native` only for the interrupt whose input really stopped the
+            // running turn; what it carried is acked `queue`. Anything else the agent
+            // read only after its turn ended began the next turn: that is a boundary
+            // delivery, whatever it was sent as.
+            const interrupted = stoppedTurn && item.message.id === id;
+            this.options.onSteerConsumed?.(this.guidanceFor(item.message, interrupted));
+            const mode = interrupted ? "interrupt_native" : afterTurnEnd || stoppedTurn ? "queue" : "steer";
+            void this.sendAck(item.message.id, item.cancelRequested
+                ? {
+                    state: "too_late",
+                    effective_mode: mode,
+                    detail: "The cancel arrived after the message was handed to the agent.",
+                }
+                : { state: "delivered", effective_mode: mode });
+        }
     }
     ingestOne(message) {
         const known = this.entries.get(message.id);
         if (message.cancel_requested) {
             if (!known) {
                 // Never seen, so never delivered: honor the cancel.
-                this.entries.set(message.id, { message, phase: "done", stoppedTurn: false, cancelRequested: true });
+                this.entries.set(message.id, { message, phase: "done", stoppedTurn: false, carriedBy: null, cancelRequested: true });
                 void this.sendAck(message.id, { state: "canceled", detail: "Canceled before the runtime read it." });
             }
             else if (known.phase === "held") {
@@ -329,10 +380,12 @@ class SteeringSession {
             if (known.phase === "held" && known.message.effective_mode !== message.effective_mode) {
                 known.message = message;
                 this.stopTurnForInterrupt(known);
+                this.tryInterrupt(known);
+                this.trySteer(known);
             }
             return;
         }
-        const entry = { message, phase: "held", stoppedTurn: false, cancelRequested: false };
+        const entry = { message, phase: "held", stoppedTurn: false, carriedBy: null, cancelRequested: false };
         this.entries.set(message.id, entry);
         const refusal = this.refusal(message);
         if (refusal) {
@@ -342,6 +395,7 @@ class SteeringSession {
             return;
         }
         this.stopTurnForInterrupt(entry);
+        this.tryInterrupt(entry);
         this.trySteer(entry);
     }
     /** Why this runtime cannot deliver `message` as the control plane resolved it, or null. */
@@ -351,11 +405,14 @@ class SteeringSession {
             case "queue":
                 return capabilities.queue === "none" ? "This runtime does not queue messages." : null;
             case "interrupt_restart":
-                return capabilities.interrupt === "restart" ? null : "This runtime cannot restart a turn for an interrupt.";
+                // A runtime that interrupts natively can still restart a turn: a message
+                // resolved against the claim's baseline record, before the probe's
+                // upgrade reached the control plane, is delivered as it was resolved.
+                return capabilities.interrupt === "none" ? "This runtime cannot restart a turn for an interrupt." : null;
             case "steer":
                 return capabilities.steer === "native" ? null : "This runtime cannot inject a message into a running turn.";
             case "interrupt_native":
-                return "This runtime cannot interrupt a running turn without restarting it.";
+                return capabilities.interrupt === "native" ? null : "This runtime cannot interrupt a running turn without restarting it.";
             default:
                 return `This runtime cannot deliver a message resolved as ${String(message.effective_mode)}.`;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.131",
+  "version": "0.1.132",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",