@sagentlab/navarch-runtime 0.1.130 → 0.1.131

package/dist/steering.cjs

@@ -0,0 +1,458 @@
+"use strict";
+// Runtime half of live steering (docs/navarch/live-steering.md sections 5, 6).
+//
+// The control plane hands a running lease the messages a human sent to its
+// task, through the lease heartbeat and the steering long-poll. This module
+// holds them until session.cts can deliver each one: a `queue` message when
+// the current turn ends, an `interrupt_restart` message by stopping the turn
+// and starting the next one in the same worktree. Every message is then
+// acknowledged, so the sender sees what happened to it and a message that
+// could not be delivered falls back to the next session instead of vanishing.
+//
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SteeringSession = void 0;
+exports.liveSteeringCapabilities = liveSteeringCapabilities;
+exports.canTakeLiveMessages = canTakeLiveMessages;
+exports.steeringPendingMessages = steeringPendingMessages;
+exports.steeringSenderName = steeringSenderName;
+const api_cjs_1 = require("./api.cjs");
+const logger_cjs_1 = require("./logger.cjs");
+const prompt_cjs_1 = require("./prompt.cjs");
+const log = (0, logger_cjs_1.createLogger)("steering");
+/** Seconds the long-poll holds a request open (section 6.2; the server caps it at 25). */
+const LONG_POLL_WAIT_SECONDS = 20;
+/** A poll that returns faster than this is paced, so a misbehaving proxy cannot spin the loop. */
+const MIN_POLL_INTERVAL_MS = 500;
+const MAX_POLL_BACKOFF_MS = 30_000;
+/** Consecutive 404s from the long-poll that mean the control plane has no steering endpoint. */
+const LONG_POLL_NOT_FOUND_LIMIT = 3;
+/** Waits between attempts at one ack; about 15 s in all, well inside the 90 s `deliver_by`. */
+const ACK_RETRY_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
+const SENDER_NAME_MAX_LENGTH = 80;
+/**
+ * The record to send at claim, or undefined for a legacy runtime: an adapter
+ * that declares none, or an operator who set NAVARCH_LIVE_STEERING=off.
+ */
+function liveSteeringCapabilities(adapter, config) {
+    if (config.liveSteering === false)
+        return undefined;
+    const { steering } = adapter;
+    return steering ? { steer: steering.steer, queue: steering.queue, interrupt: steering.interrupt } : undefined;
+}
+/** True when the record lets the control plane send this runtime anything live. */
+function canTakeLiveMessages(capabilities) {
+    return Boolean(capabilities && (capabilities.steer !== "none" || capabilities.queue !== "none" || capabilities.interrupt !== "none"));
+}
+/**
+ * The messages a 409 `steering_pending` completion refusal lists, or null when
+ * the error is anything else (section 6.6).
+ */
+function steeringPendingMessages(err) {
+    if (!(err instanceof api_cjs_1.NavarchApiError) || err.status !== 409)
+        return null;
+    const body = err.body;
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return null;
+    const record = body;
+    if (record.code !== "steering_pending")
+        return null;
+    return Array.isArray(record.messages) ? record.messages : [];
+}
+function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+/** One display line for the prompt header; the name is profile data, so it cannot add structure. */
+function steeringSenderName(name) {
+    const clean = (name ?? "").replace(/[\u0000-\u001f\u007f\[\]]+/g, " ").replace(/\s+/g, " ").trim();
+    return clean ? clean.slice(0, SENDER_NAME_MAX_LENGTH) : null;
+}
+/**
+ * Per-lease steering state: what was received, what each turn was handed, and
+ * the acks. The session loop owns the turns; this owns the messages.
+ */
+class SteeringSession {
+    options;
+    entries = new Map();
+    acks = new Set();
+    pollAbort = new AbortController();
+    sleep;
+    ackRetryDelaysMs;
+    cursorSeq = 0;
+    stopped = false;
+    poller = null;
+    capabilities;
+    channel = null;
+    /** 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),
+    };
+    constructor(options) {
+        this.options = options;
+        this.capabilities = options.capabilities;
+        this.sleep = options.sleep ?? defaultSleep;
+        this.ackRetryDelaysMs = options.ackRetryDelaysMs ?? ACK_RETRY_DELAYS_MS;
+    }
+    /** The adapter's probe found more than the claim promised: use (and report) the upgraded record. */
+    setCapabilities(capabilities) {
+        this.capabilities = capabilities;
+    }
+    /** Highest `seq` taken so far: the `steering_after_seq` of the next pull. */
+    get cursor() {
+        return this.cursorSeq;
+    }
+    /** A message is waiting for a turn to carry it. */
+    hasDeliverable() {
+        for (const entry of this.entries.values())
+            if (entry.phase === "held")
+                return true;
+        return false;
+    }
+    /** Starts the long-poll. A no-op for a record that takes nothing, and after stop(). */
+    start() {
+        if (this.poller || this.stopped || !canTakeLiveMessages(this.capabilities))
+            return;
+        this.poller = this.pollLoop();
+    }
+    /** Ends the long-poll. Acks already started still finish; no new retries begin. */
+    stop() {
+        this.stopped = true;
+        this.pollAbort.abort();
+    }
+    /**
+     * Takes what one pull returned. Safe to call with the same message again:
+     * a pull from an earlier cursor, or the heartbeat after the long-poll, can
+     * return a message this session already holds.
+     */
+    ingest(messages, cursor) {
+        if (typeof cursor === "number" && cursor > this.cursorSeq)
+            this.cursorSeq = cursor;
+        if (!messages)
+            return;
+        for (const message of [...messages].sort((a, b) => a.seq - b.seq))
+            this.ingestOne(message);
+    }
+    /** One immediate pull, without waiting. Used to close the completion race (section 6.6). */
+    async pullNow(afterSeq = this.cursorSeq) {
+        const pulled = await this.options.transport.pollSteering(this.options.leaseId, {
+            afterSeq,
+            waitSeconds: 0,
+        });
+        this.ingest(pulled.steering, pulled.steering_cursor);
+    }
+    /**
+     * Selects every held message, in `seq` order, for the turn that starts now.
+     * An interrupt carries each earlier queued message with it (section 6.4), and
+     * at a turn boundary a queued message joins whatever else is waiting, so one
+     * turn takes the lot.
+     */
+    takeForTurn() {
+        const held = [...this.entries.values()]
+            .filter((entry) => entry.phase === "held")
+            .sort((a, b) => a.message.seq - b.message.seq);
+        return held.map((entry) => {
+            entry.phase = "taken";
+            return {
+                message: entry.message,
+                // `interrupt_restart` is reported only when a running turn really was
+                // stopped; one that arrived between turns, or that carried an earlier
+                // queued note, was delivered at a turn boundary.
+                mode: entry.message.effective_mode === "interrupt_restart" && entry.stoppedTurn
+                    ? "interrupt_restart"
+                    : "queue",
+                stoppedTurn: entry.stoppedTurn,
+            };
+        });
+    }
+    /** How the prompt introduces a taken message (see prompt.cts#renderMidFlightGuidanceSection). */
+    toGuidance(taken) {
+        return taken.map(({ message, stoppedTurn }) => this.guidanceFor(message, stoppedTurn));
+    }
+    guidanceFor(message, interrupted) {
+        return {
+            // The `guidance.given` event id is what the claim bundle and the legacy
+            // heartbeat list use, so the session's de-duplication sees the same id.
+            id: message.guidance_event_id ?? message.id,
+            content: message.content,
+            actor_id: message.actor_id,
+            given_at: message.created_at,
+            message_id: message.id,
+            steering: {
+                seq: message.seq,
+                mode: message.requested_mode,
+                sender: steeringSenderName(message.actor_display_name),
+                interrupted,
+                ...(this.capabilities.steer === "native" && this.options.token ? { token: this.options.token } : {}),
+            },
+        };
+    }
+    /**
+     * The turn's agent process is gone. A message written to it that was never
+     * read goes back to waiting, to ride in the next turn's prompt (and be acked
+     * as delivered at the turn boundary).
+     */
+    turnEnded() {
+        this.channel = null;
+        for (const entry of this.entries.values())
+            if (entry.phase === "sent")
+                entry.phase = "held";
+    }
+    /** The agent process for the turn started, so it holds the messages: report them delivered. */
+    markInjected(taken) {
+        for (const item of taken) {
+            const entry = this.entries.get(item.message.id);
+            if (!entry || entry.phase === "done")
+                continue;
+            entry.phase = "done";
+            void this.sendAck(item.message.id, entry.cancelRequested
+                ? {
+                    state: "too_late",
+                    effective_mode: item.mode,
+                    detail: "The cancel arrived after the message was handed to the agent.",
+                }
+                : { state: "delivered", effective_mode: item.mode });
+        }
+    }
+    /** The turn could not carry these messages: hand them to the next session. */
+    failTaken(taken, detail) {
+        for (const item of taken) {
+            const entry = this.entries.get(item.message.id);
+            if (!entry || entry.phase === "done")
+                continue;
+            entry.phase = "done";
+            void this.sendAck(item.message.id, { state: "failed", detail });
+        }
+        return this.flush();
+    }
+    /** The session is ending with messages unread: hand them to the next session. */
+    failHeld(detail) {
+        for (const [id, entry] of this.entries) {
+            if (entry.phase !== "held")
+                continue;
+            entry.phase = "done";
+            void this.sendAck(id, { state: "failed", detail });
+        }
+        return this.flush();
+    }
+    /**
+     * A completion refusal listed messages this runtime has nothing to deliver
+     * them with: hand them to the next session (section 6.6).
+     */
+    failListed(messages, detail) {
+        for (const { id } of messages) {
+            const entry = this.entries.get(id);
+            if (entry?.phase === "held")
+                continue;
+            if (entry)
+                entry.phase = "done";
+            void this.sendAck(id, { state: "failed", detail });
+        }
+        return this.flush();
+    }
+    /** Resolves when every ack started so far has been answered or abandoned. */
+    async flush() {
+        while (this.acks.size > 0)
+            await Promise.allSettled([...this.acks]);
+    }
+    attachChannel(channel) {
+        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())
+            this.trySteer(entry);
+    }
+    /** 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)
+            return;
+        const sent = this.channel.send({
+            id: entry.message.id,
+            text: (0, prompt_cjs_1.renderSteerInjection)(this.guidanceFor(entry.message, false)),
+        });
+        if (!sent)
+            return;
+        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) {
+        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 });
+    }
+    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 });
+                void this.sendAck(message.id, { state: "canceled", detail: "Canceled before the runtime read it." });
+            }
+            else if (known.phase === "held") {
+                known.phase = "done";
+                void this.sendAck(message.id, { state: "canceled", detail: "Canceled before the next turn started." });
+            }
+            else if (known.phase === "taken" || known.phase === "sent") {
+                // Already in the agent's hands: the ack will say the cancel was too late.
+                known.cancelRequested = true;
+            }
+            return;
+        }
+        if (known) {
+            // A copy of a message this session already knows. Only a held message can
+            // still change. The CX-1.1b substrate retargets only a `pending` message
+            // (a queued one is dispatched at once), so this is a guard for a control
+            // plane that retargets a dispatched one, as the design describes.
+            if (known.phase === "held" && known.message.effective_mode !== message.effective_mode) {
+                known.message = message;
+                this.stopTurnForInterrupt(known);
+            }
+            return;
+        }
+        const entry = { message, phase: "held", stoppedTurn: false, cancelRequested: false };
+        this.entries.set(message.id, entry);
+        const refusal = this.refusal(message);
+        if (refusal) {
+            entry.phase = "done";
+            log.warn(`message ${message.id} (seq ${message.seq}) refused: ${refusal}`);
+            void this.sendAck(message.id, { state: "failed", detail: refusal });
+            return;
+        }
+        this.stopTurnForInterrupt(entry);
+        this.trySteer(entry);
+    }
+    /** Why this runtime cannot deliver `message` as the control plane resolved it, or null. */
+    refusal(message) {
+        const { capabilities } = this;
+        switch (message.effective_mode) {
+            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.";
+            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.";
+            default:
+                return `This runtime cannot deliver a message resolved as ${String(message.effective_mode)}.`;
+        }
+    }
+    stopTurnForInterrupt(entry) {
+        if (entry.message.effective_mode !== "interrupt_restart" || entry.stoppedTurn)
+            return;
+        entry.stoppedTurn = this.options.interruptTurn();
+        log.info(`interrupt message ${entry.message.id} (seq ${entry.message.seq}) ` +
+            `${entry.stoppedTurn ? "stopped the running turn; the next turn reads it" : "is held for the next turn"}.`);
+    }
+    sendAck(messageId, ack) {
+        const task = this.ackWithRetry(messageId, ack).finally(() => this.acks.delete(task));
+        this.acks.add(task);
+        return task;
+    }
+    async ackWithRetry(messageId, ack) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await this.options.transport.ackSteering(this.options.leaseId, messageId, ack);
+                log.info(`message ${messageId}: acked ${ack.state}${ack.effective_mode ? ` as ${ack.effective_mode}` : ""}.`);
+                return;
+            }
+            catch (err) {
+                if (err instanceof api_cjs_1.NavarchApiError && err.status >= 400 && err.status < 500 && err.status !== 408 && err.status !== 429) {
+                    // 409 already_fell_back: the control plane gave up on this lease and
+                    // will hand the message to the next session, so a message already in
+                    // a prompt may be read twice. The prompt header carries the id.
+                    log.warn(`message ${messageId}: control plane refused the ${ack.state} ack (${err.status} ${describeBody(err.body)})` +
+                        `${ack.state === "delivered" ? "; the next session may read it again." : "."}`);
+                    return;
+                }
+                const delay = this.ackRetryDelaysMs[attempt];
+                if (delay === undefined || this.stopped) {
+                    log.warn(`message ${messageId}: giving up on the ${ack.state} ack: ${String(err)}`);
+                    return;
+                }
+                await this.sleep(delay);
+            }
+        }
+    }
+    async pollLoop() {
+        let failures = 0;
+        let notFound = 0;
+        while (!this.stopped) {
+            const startedAt = Date.now();
+            try {
+                const pulled = await this.options.transport.pollSteering(this.options.leaseId, {
+                    afterSeq: this.cursorSeq,
+                    waitSeconds: LONG_POLL_WAIT_SECONDS,
+                    signal: this.pollAbort.signal,
+                });
+                failures = 0;
+                notFound = 0;
+                if (this.stopped)
+                    return;
+                this.ingest(pulled.steering, pulled.steering_cursor);
+                const elapsed = Date.now() - startedAt;
+                if (elapsed < MIN_POLL_INTERVAL_MS)
+                    await this.sleep(MIN_POLL_INTERVAL_MS - elapsed, this.pollAbort.signal);
+            }
+            catch (err) {
+                if (this.stopped)
+                    return;
+                if (err instanceof api_cjs_1.NavarchApiError && (err.status === 403 || err.status === 410)) {
+                    // The lease is gone, and the heartbeat path is what stops the session.
+                    log.info(`steering long-poll ended for ${this.options.leaseId}: ${err.status}.`);
+                    return;
+                }
+                if (err instanceof api_cjs_1.NavarchApiError && err.status === 404) {
+                    // A control plane without the endpoint answers 404 every time, and the
+                    // heartbeat is then the only transport. One 404 can be a rollout or a
+                    // proxy, and giving up on a session for it would turn a message's 90 s
+                    // deadline into the heartbeat interval, so ask again before concluding.
+                    notFound += 1;
+                    if (notFound >= LONG_POLL_NOT_FOUND_LIMIT) {
+                        log.info(`steering long-poll ended for ${this.options.leaseId}: the control plane has no steering endpoint.`);
+                        return;
+                    }
+                }
+                else {
+                    notFound = 0;
+                }
+                failures += 1;
+                const backoff = Math.min(MAX_POLL_BACKOFF_MS, 1_000 * 2 ** Math.min(failures, 5));
+                log.warn(`steering long-poll failed for ${this.options.leaseId}: ${String(err)}; retrying in ${backoff / 1000}s.`);
+                await this.sleep(backoff, this.pollAbort.signal);
+            }
+        }
+    }
+}
+exports.SteeringSession = SteeringSession;
+function describeBody(body) {
+    if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+        const code = body.code;
+        if (typeof code === "string")
+            return code;
+    }
+    return "no detail";
+}

package/package.json

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