@sagentlab/navarch-runtime 0.1.129 → 0.1.131

package/dist/session.cjs

@@ -7,6 +7,7 @@ exports.runSession = runSession;
 exports.gitGrantCredentialHelper = gitGrantCredentialHelper;
 exports.toEnvMap = toEnvMap;
 const muse_cjs_1 = require("./adapters/muse.cjs");
+const node_crypto_1 = require("node:crypto");
 const node_path_1 = __importDefault(require("node:path"));
 const node_perf_hooks_1 = require("node:perf_hooks");
 const node_fs_1 = require("node:fs");
@@ -30,6 +31,7 @@ const github_pr_cjs_1 = require("./github-pr.cjs");
 const delivery_cjs_1 = require("./delivery.cjs");
 const worktree_guard_cjs_1 = require("./worktree-guard.cjs");
 const adapter_watchdog_cjs_1 = require("./adapter-watchdog.cjs");
+const steering_cjs_1 = require("./steering.cjs");
 const lease_heartbeat_cjs_1 = require("./lease-heartbeat.cjs");
 const completion_retry_cjs_1 = require("./completion-retry.cjs");
 const adapter_capacity_cjs_1 = require("./adapter-capacity.cjs");
@@ -38,6 +40,7 @@ const agent_model_cjs_1 = require("./agent-model.cjs");
 const github_credential_cjs_1 = require("./github-credential.cjs");
 const browser_evidence_cjs_1 = require("./browser-evidence.cjs");
 const git_grant_cjs_1 = require("./git-grant.cjs");
+const commit_attribution_cjs_1 = require("./commit-attribution.cjs");
 /** Filename the generated platform MCP config is written under inside the session metadata directory. */
 const MCP_CONFIG_FILENAME = "mcp-config.json";
 const GIT_CREDENTIAL_HELPER_FILENAME = "git-credential-navarch.cjs";
@@ -50,6 +53,20 @@ const COMPLETION_REMEDIATION_RETRIES = 2;
  * and one must not consume the other's budget.
  */
 const DELIVERY_CORRECTION_RETRIES = 1;
+/**
+ * Times one completion is re-sent after the control plane answered
+ * `steering_pending` while this runtime held nothing to deliver: the pending
+ * messages were being acked, or were handed to the next session by the last
+ * re-send. A message the runtime does hold gets another turn instead.
+ */
+const STEERING_COMPLETION_RESENDS = 3;
+const STEERING_COMPLETION_RESEND_DELAY_MS = 1_000;
+/**
+ * How long an agent process may run before the messages in its prompt count as
+ * delivered, when it has printed nothing yet. A launch that fails does so
+ * within milliseconds; the control plane gives an interrupt 90 s to be acked.
+ */
+const STEERING_START_GRACE_MS = 5_000;
 const log = (0, logger_cjs_1.createLogger)("session");
 function resolveSessionExecution(config, claimed) {
     const runtime = claimed.runtime ?? config.agentType;
@@ -248,6 +265,11 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         };
     }
     const sessionEnv = toEnvMap(secrets, gitCredentialRefresh, config.gitAuthorName, config.gitAuthorEmail, gitGrantEnv);
+    // Proxied projects (CX-3.7): the control-plane identity replaces the
+    // NAVARCH_GIT_AUTHOR_* default for this session; mode `off` sends none.
+    const commitIdentity = (0, commit_attribution_cjs_1.parseCommitIdentity)(bundle.repository?.commit_identity);
+    if (commitIdentity)
+        (0, commit_attribution_cjs_1.applyCommitIdentityEnv)(sessionEnv, commitIdentity);
     const ghConfigDir = (0, worktree_guard_cjs_1.sessionGhConfigDir)(workDir);
     await node_fs_1.promises.mkdir(ghConfigDir, { recursive: true, mode: 0o700 });
     sessionEnv.GH_CONFIG_DIR = ghConfigDir;
@@ -305,6 +327,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             : undefined,
         // Hosted runs skip checkpoints for verify tasks, which deliver a verdict.
         restoreHostedCheckpoint: !allowBranchRename && task.task_type !== "verify",
+        ...(commitIdentity ? { ownershipCommitIdentity: commitIdentity.committer } : {}),
     });
     const knownGuidanceIds = new Set((bundle.guidance ?? []).map((entry) => entry.id));
     const deliveredGuidance = [...(bundle.guidance ?? [])];
@@ -326,7 +349,52 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     let heartbeatInFlight = null;
     let heartbeatWorkspaceUpdate = null;
     let completingLease = false;
+    let adapterRunning = false;
     const sessionOutcome = {};
+    // Live steering (docs/navarch/live-steering.md): messages a human sent to
+    // this task arrive through the heartbeat and the steering long-poll. An
+    // adapter without a capability record, or NAVARCH_LIVE_STEERING=off, is a
+    // legacy runtime: it sends nothing and keeps the `guidance` handling below.
+    const adapter = (0, index_cjs_1.selectAdapter)(runtime);
+    let steeringCapabilities = (0, steering_cjs_1.liveSteeringCapabilities)(adapter, config);
+    // Native steering: ids of messages the running agent has read during the
+    // current turn. The conversation holds them, so a resumed turn must not be
+    // sent them again, while a fresh invocation's full brief still lists them.
+    const steeredThisTurn = [];
+    // A turn was stopped to deliver an interrupt. The message can be canceled
+    // after that, so the session has to run another turn even with none held.
+    let steeringStoppedTurn = false;
+    // Marks a genuine live message to an agent that takes native steering. It is
+    // per lease and never leaves the prompt, so registering it keeps it out of
+    // transcripts, reports and logs even if the agent repeats it.
+    const steeringToken = `nvl-${(0, node_crypto_1.randomBytes)(6).toString("hex")}`;
+    registry.register(steeringToken);
+    const steering = steeringCapabilities && (0, steering_cjs_1.canTakeLiveMessages)(steeringCapabilities)
+        ? new steering_cjs_1.SteeringSession({
+            transport: api,
+            leaseId,
+            capabilities: steeringCapabilities,
+            token: steeringToken,
+            // Stop only an agent turn. An interrupt must not abort worktree
+            // preparation or the dependency install that runs before the first turn.
+            interruptTurn: () => {
+                if (!adapterRunning || leaseLost || sessionClosing)
+                    return false;
+                steeringStoppedTurn = true;
+                activeAbortController?.abort();
+                return true;
+            },
+            onSteerConsumed: (entry) => {
+                knownGuidanceIds.add(entry.id);
+                deliveredGuidance.push(entry);
+                steeredThisTurn.push(entry.id);
+            },
+        })
+        : undefined;
+    // The record last acknowledged by a heartbeat. The claim carried the primary
+    // adapter's record, and this lease may run another advertised runtime or
+    // have an adapter probe upgrade it, so the first heartbeat sends it too.
+    let reportedSteeringCapabilities;
     const checkpointForRecovery = async (result, reason) => {
         if (result.checkpointPath || result.retainedWorktreePath)
             return;
@@ -345,12 +413,21 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             return Promise.resolve();
         if (heartbeatInFlight)
             return heartbeatInFlight;
+        const sentSteeringCapabilities = steeringCapabilities;
         const request = api
-            .heartbeatLease(leaseId, { guidance_after: guidanceCursor })
+            .heartbeatLease(leaseId, {
+            guidance_after: guidanceCursor,
+            ...(steering ? { steering_after_seq: steering.cursor } : {}),
+            ...(steering && sentSteeringCapabilities !== reportedSteeringCapabilities
+                ? { steering_capabilities: sentSteeringCapabilities }
+                : {}),
+        })
             .then(async (heartbeat) => {
             if (sessionClosing)
                 return;
             heartbeatGuard.renew(heartbeat.expires_at);
+            if (steering)
+                reportedSteeringCapabilities = sentSteeringCapabilities;
             if (leaseLost)
                 return;
             heartbeatWorkspaceUpdate = (0, worktree_janitor_cjs_1.markSessionWorkspaceActive)(workDir);
@@ -371,6 +448,14 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 log.info(`received ${fresh.length} guidance update${fresh.length === 1 ? "" : "s"} for ${leaseId}; restarting the agent turn in the same worktree.`);
                 activeAbortController?.abort();
             }
+            // After the legacy guidance so a message that interrupts stops the turn once.
+            try {
+                steering?.ingest(heartbeat.steering, heartbeat.steering_cursor);
+            }
+            catch (error) {
+                // A malformed steering field is not a lease failure: the long-poll and the next heartbeat read again.
+                log.warn(`could not read the steering messages in the heartbeat for ${leaseId}: ${String(error)}`);
+            }
         })
             .catch((err) => {
             if (leaseLost || sessionClosing)
@@ -536,7 +621,6 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     let outputReportedAt = 0;
     let outputUpdates = 0;
     let agentTurnStartedAt = 0;
-    let adapterRunning = false;
     const reportActivity = (phase, detail) => {
         activityPending = activityPending.then(() => api.reportActivity(leaseId, phase, detail)).catch((error) => {
             log.warn(`activity update failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(String(error), registry.list())}`);
@@ -567,6 +651,34 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
     let liveTranscript;
     try {
         reportActivity("preparing");
+        if (steering && adapter.probeSteering) {
+            // The claim carried the adapter's baseline record. A probe that finds the
+            // installed CLI can do more (native steering) upgrades it. The upgrade is
+            // reported before the long-poll starts, so no message resolves as `steer`
+            // before the probe has passed, or as `queue` after it has.
+            const probed = adapterCommand(config, runtime);
+            const upgraded = await adapter
+                .probeSteering({ bin: probed.bin, extraArgs: probed.extraArgs, env: sessionEnv, sandboxMode: config.sandboxMode })
+                .catch(() => null);
+            if (upgraded && !leaseLost) {
+                steeringCapabilities = upgraded;
+                steering.setCapabilities(upgraded);
+                if (upgraded.steer === "native") {
+                    // A native steer reaches the agent next to a tool result, where a
+                    // model discards it as untrusted tool output unless the brief says
+                    // how to recognise a real one. This goes in before any message can
+                    // be dispatched against the upgraded record.
+                    promptText = `${promptText}\n${(0, prompt_cjs_1.steeringPromptNote)(steeringToken)}`;
+                    await node_fs_1.promises.writeFile(node_path_1.default.join(workDir, "prompt.md"), promptText, "utf8");
+                }
+                await pollLease();
+                // An already running heartbeat can answer for the older record.
+                if (reportedSteeringCapabilities !== upgraded)
+                    await pollLease();
+                log.info(`steering capabilities for ${leaseId}: steer ${upgraded.steer}, queue ${upgraded.queue}, interrupt ${upgraded.interrupt}.`);
+            }
+        }
+        steering?.start();
         await gitWorktree.prepare();
         if (!config.mcpConfigPath && config.sandboxMode === "host"
             && ["build", "verify", "qa"].includes(task.task_type)
@@ -672,7 +784,6 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         // All adapters implement the same AgentAdapter.run() shape
         // (adapters/types.cts), so nothing else in this function branches on
         // which agent is running.
-        const adapter = (0, index_cjs_1.selectAdapter)(runtime);
         const { bin, extraArgs } = adapterCommand(config, runtime);
         const attempts = [];
         // The task view follows the run through periodic redacted snapshots of
@@ -719,6 +830,33 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             activeAbortController = turnAbort;
             if (leaseLost || deps.shutdownSignal?.aborted)
                 turnAbort.abort();
+            // Live-steering messages that arrived during preparation, while the last
+            // turn ran, or after it ended ride in this turn's prompt as mid-flight
+            // guidance, so the resume and full-brief paths below carry them like any
+            // other guidance. They are acked once the agent process has started.
+            steeringStoppedTurn = false;
+            const steeringTaken = steering?.takeForTurn() ?? [];
+            const steeringGuidance = steering ? steering.toGuidance(steeringTaken) : [];
+            if (steering && steeringTaken.length > 0) {
+                for (const entry of steeringGuidance)
+                    knownGuidanceIds.add(entry.id);
+                deliveredGuidance.push(...steeringGuidance);
+                log.info(`delivering ${steeringTaken.length} steering message${steeringTaken.length === 1 ? "" : "s"} ` +
+                    `to ${leaseId} (seq ${steeringTaken.map((item) => item.message.seq).join(", ")}).`);
+            }
+            // The messages count as delivered once the agent has them: its first
+            // output, or a short while after its process started without failing. A
+            // spawn that fails on the next tick (no such binary) must not count, and a
+            // Docker exec has no process-start signal at all.
+            let steeringTurnStarted = false;
+            let steeringStartTimer;
+            const markSteeringStarted = () => {
+                if (steeringTurnStarted)
+                    return;
+                steeringTurnStarted = true;
+                clearTimeout(steeringStartTimer);
+                steering?.markInjected(steeringTaken);
+            };
             // The task brief plus any mid-flight guidance. Correction turns build on
             // this rather than on the previous turn's prompt so they never nest.
             const midFlightGuidance = deliveredGuidance.filter((entry) => !briefGuidanceIds.has(entry.id));
@@ -774,7 +912,21 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                         cwd: gitWorktree.worktreePath,
                         dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
                         signal: turnAbort.signal,
-                        onActivity: () => { outputObservedAt = Date.now(); outputUpdates += 1; },
+                        // Native steering: the adapter keeps the agent's input open and
+                        // reports each message the agent reads. Absent for every adapter
+                        // whose record says `steer: none`.
+                        liveInput: steering && steeringCapabilities?.steer === "native" ? steering.liveInput : undefined,
+                        onProcessStarted: () => {
+                            if (steeringTaken.length > 0 && !steeringTurnStarted) {
+                                clearTimeout(steeringStartTimer);
+                                steeringStartTimer = setTimeout(markSteeringStarted, STEERING_START_GRACE_MS);
+                            }
+                        },
+                        onActivity: () => {
+                            outputObservedAt = Date.now();
+                            outputUpdates += 1;
+                            markSteeringStarted();
+                        },
                         onOutput: (stream, chunk) => {
                             if (stream !== "stdout")
                                 return;
@@ -796,6 +948,23 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             }
             activeAbortController = null;
             adapterRunning = false;
+            clearTimeout(steeringStartTimer);
+            // The agent process is gone: a message written to it and never read goes
+            // back to waiting for the next turn.
+            steering?.turnEnded();
+            // An agent that ran and ended before the grace period, or whose launcher
+            // reports no start (Docker), still got the prompt.
+            if (!steeringTurnStarted && (turnResult.exitCode !== null || turnResult.stdout))
+                markSteeringStarted();
+            if (steering && steeringTaken.length > 0 && !steeringTurnStarted) {
+                // No agent process ever ran, so it holds none of them. They go to the
+                // next session, and no later prompt of this one may repeat them.
+                await steering.failTaken(steeringTaken, "The agent process did not start, so it never read the message.");
+                const dropped = new Set(steeringGuidance.map((entry) => entry.id));
+                deliveredGuidance.splice(0, deliveredGuidance.length, ...deliveredGuidance.filter((entry) => !dropped.has(entry.id)));
+                for (const id of dropped)
+                    knownGuidanceIds.delete(id);
+            }
             if (turnResult.timedOut || leaseLost)
                 await checkpointForRecovery(turnResult);
             if (turnResult.model) {
@@ -832,7 +1001,12 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                     // mid-flight guidance entry received so far.
                     conversationGuidanceIds = new Set(midFlightGuidance.map((entry) => entry.id));
                 }
+                // Messages the agent read mid-turn are in this conversation too.
+                if (resumableSessionId)
+                    for (const id of steeredThisTurn)
+                        conversationGuidanceIds.add(id);
             }
+            steeredThisTurn.length = 0;
             attempts.push(turnResult);
             liveStdout = "";
             liveTranscript.markDirty();
@@ -870,19 +1044,37 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 log.warn(`session ${leaseId} stopped without completion because its lease is no longer active.`);
                 return sessionOutcome;
             }
-            if (!capacityLimit && !authFailure && !modelUnavailable && !leaseLost && !turnResult.timedOut && pendingGuidance.length > 0) {
-                // Muse cancellation kills the whole task-owned container. Guidance
-                // still holds the lease, so restart that SAME container and restore
-                // its tmpfs environment before the next turn; never launch into a
-                // stopped sandbox or substitute an unisolated host process.
-                if (runtime === "muse" && sandbox && turnResult.killedByLeaseLoss) {
+            const canRunAnotherTurn = !capacityLimit && !authFailure && !modelUnavailable && !leaseLost && !turnResult.timedOut;
+            // An interrupt stopped this turn, but the message may have been canceled
+            // since, so nothing is held. The task is not done: carry on from where the
+            // turn stopped instead of completing a session that only lost a turn.
+            const turnStoppedBySteering = steeringStoppedTurn && turnResult.killedByLeaseLoss && !leaseLost;
+            if (canRunAnotherTurn && (pendingGuidance.length > 0 || steering?.hasDeliverable() || turnStoppedBySteering)) {
+                if (turnStoppedBySteering && pendingGuidance.length === 0 && !steering?.hasDeliverable()) {
+                    const stopped = "Your previous turn was stopped for a message that was then canceled. Nothing has changed in the task: inspect the worktree (`git status`, recent changes) and continue from where you stopped.";
+                    nextCorrection = {
+                        full: (brief) => `${brief.trimEnd()}\n\n${stopped}\n`,
+                        resumed: `${(0, prompt_cjs_1.renderResumedTurnPreamble)(resumedTask)}\n\n${stopped}\n`,
+                    };
+                }
+                // Cancelling a Docker agent kills the whole task-owned container (every
+                // adapter's Docker path does, Muse's included). The lease is still held,
+                // so restart that SAME container and restore its tmpfs environment before
+                // the next turn; never launch into a stopped sandbox or substitute an
+                // unisolated host process.
+                if (sandbox && turnResult.killedByLeaseLoss) {
                     const restarted = await sandbox_cjs_1.nodeCommandRunner.run("docker", ["start", sandbox.name], { timeoutMs: 10_000 });
                     if (restarted.code !== 0)
-                        throw new Error("Could not restart the task-owned Muse sandbox after guidance.");
+                        throw new Error("Could not restart the task-owned sandbox after guidance.");
                     await sandbox.injectEnv(sessionEnv);
                 }
                 continue;
             }
+            // No further turn can read a message that is still waiting, so give it to
+            // the next session now and say why, instead of leaving it to the lease end.
+            // A lost lease needs no ack: its release already moved them there.
+            if (!leaseLost)
+                await steering?.failHeld("The session ended before the message could be delivered to the agent.");
             const result = {
                 ...turnResult,
                 tokensIn: sumReportedUsage(attempts, "tokensIn", runtime === "muse"),
@@ -1047,11 +1239,51 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 cost: completion.cost,
                 transcript_url: completion.transcript_url,
             };
+            if (steering && !leaseLost) {
+                if (completion.status === "completed" && steering.hasDeliverable()) {
+                    // A message arrived while the delivery checks ran: it gets its turn
+                    // before the lease completes.
+                    log.info(`steering message received while finishing ${leaseId}; running another turn before completing.`);
+                    continue;
+                }
+                // A failed outcome has no further turn, so the next session reads it.
+                await steering.failHeld("The session ended before the message could be delivered to the agent.");
+            }
+            // The control plane refuses a completion while live messages are
+            // undelivered (409 steering_pending, section 6.6). A message this runtime
+            // holds gets another turn; anything else was being acked or is handed to
+            // the next session, and the completion is sent again.
+            const sendCompletion = async () => {
+                for (let resend = 0;; resend += 1) {
+                    try {
+                        await (0, completion_retry_cjs_1.completeWithTransientRetry)(() => api.completeLease(leaseId, completion), {
+                            onRetry: (attempt, delayMs, err) => log.warn(`completion for ${leaseId} did not reach the control plane (${(0, redact_cjs_1.redactText)(String(err), knownSecrets)}); re-sending in ${delayMs / 1000}s (${attempt}).`),
+                        });
+                        return "sent";
+                    }
+                    catch (err) {
+                        const listed = (0, steering_cjs_1.steeringPendingMessages)(err);
+                        if (!listed || !steering || leaseLost)
+                            throw err;
+                        await steering.flush();
+                        // From the start, so a message dispatched but never received is read now.
+                        await steering.pullNow(0).catch((pullError) => log.warn(`steering pull before completion failed for ${leaseId}: ${(0, redact_cjs_1.redactText)(String(pullError), knownSecrets)}`));
+                        if (steering.hasDeliverable())
+                            return "steering_turn";
+                        if (resend >= STEERING_COMPLETION_RESENDS)
+                            throw err;
+                        if (resend === STEERING_COMPLETION_RESENDS - 1) {
+                            log.warn(`completion for ${leaseId} still lists ${listed.length} steering message(s); handing them to the next session.`);
+                            await steering.failListed(listed, "The runtime could not deliver the message before the session completed.");
+                        }
+                        await new Promise((resolve) => setTimeout(resolve, STEERING_COMPLETION_RESEND_DELAY_MS));
+                    }
+                }
+            };
             try {
                 completingLease = true;
-                await (0, completion_retry_cjs_1.completeWithTransientRetry)(() => api.completeLease(leaseId, completion), {
-                    onRetry: (attempt, delayMs, err) => log.warn(`completion for ${leaseId} did not reach the control plane (${(0, redact_cjs_1.redactText)(String(err), knownSecrets)}); re-sending in ${delayMs / 1000}s (${attempt}).`),
-                });
+                if (await sendCompletion() === "steering_turn")
+                    continue;
                 if (deliveredPullRequest && completion.status === "completed" && gitWorktree.restoredHostedCheckpoint) {
                     // The pull request carries the hosted attempt's work now; a later
                     // hosted attempt must not resume the stale snapshot.
@@ -1142,6 +1374,8 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         // locally. NavarchApiError.message contains only the HTTP status line; its
         // response body carries the actionable server error shown in session UI.
         const failureSummary = `Session crashed: ${crashDetail}`;
+        if (!leaseLost)
+            await steering?.failHeld("The session crashed before the message could be delivered to the agent.").catch(() => undefined);
         await api
             .completeLease(leaseId, {
             status: "failed",
@@ -1164,6 +1398,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
         await liveTranscript?.stop();
         deps.shutdownSignal?.removeEventListener("abort", abortForRuntimeShutdown);
         sessionClosing = true;
+        steering?.stop();
         clearInterval(heartbeatTimer);
         clearInterval(activityTimer);
         heartbeatGuard.stop();