@sagentlab/navarch-runtime 0.1.91 → 0.1.93

package/README.md

@@ -9,6 +9,16 @@ environment, outside the coding agent's OS sandbox, with a fresh browser
 context for desktop and touch-enabled mobile captures. It neither uses the
 operator's browser profile nor executes agent-provided scripts.
 
+The same server offers interactive `local_browser_open`, `local_browser_click`,
+`local_browser_fill`, `local_browser_press`, `local_browser_snapshot`, and
+`local_browser_screenshot` tools for walking through a service the agent starts
+on this machine. That browser is limited to loopback (`localhost`,
+`*.localhost`, `127.0.0.0/8`, `::1`). Every request, WebSocket, or navigation
+to any other host is aborted and listed in the tool result. The agent's own
+sandbox can already reach these services, so the tools add a browser without
+adding network reach. Each lease gets one tab at a time, a fresh context per
+viewport, and at most 300 actions.
+
 Install the runtime's pinned browser once on the agent host (and after a
 Playwright version update):
 
@@ -36,9 +46,13 @@ lifetime, so restart the agent after fixing the browser to re-probe.
 `navarch-runtime doctor` runs the same check.
 
 Codex's macOS seatbelt denies Chromium's Mach port registration
-(`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), so a
-sandboxed Codex machine on macOS does not take browser tasks. Run those with
-another agent such as Claude Code, or use Docker mode. Docker mode is not
+(`bootstrap_check_in ... MachPortRendezvousServer: Permission denied`), and
+`--single-process` crashes once a second page opens. When Node runs in the
+sandbox and only Chromium fails, the probe still passes, with that reason. Codex
+sessions then browse local services through the `local_browser_*` tools above,
+and the session prompt tells them to. With an operator `NAVARCH_MCP_CONFIG_PATH`
+those tools are absent, so the machine does not take browser tasks; run those
+with another agent such as Claude Code, or use Docker mode. Docker mode is not
 probed because its image supplies the browser. Set `NAVARCH_BROWSER_PROBE=off`
 to trust the configured capability list without a check.
 
@@ -460,6 +474,9 @@ unchanged across the deployment.
 | `NAVARCH_QODER_EXTRA_ARGS` | — | Comma list of extra CLI args appended after the unattended defaults (`--setting-sources`, `--permission-mode auto`, `--output-format json`). An explicit `--output-format`, `--permission-mode`, `--settings`, `--model`, or `--reasoning-effort` here replaces the per-session default. Qoder selects its own account models; pin one via `--model` here or `connect --model` to override. |
 | `NAVARCH_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
 | `NAVARCH_WORKTREE_GUARD` | on | Host-mode sessions get an adapter-native per-session worktree boundary guard (see below). Set `off` to disable it for every runtime on the machine — required to run OpenCode on the host. |
+| `NAVARCH_NAVI_CONVERSATIONS` | on | Serve read-only Navi repository conversations on this machine. Only the `claude-code` adapter on the host sandbox with the worktree guard on is supported; `navarch-runtime doctor` prints the `navi_chat:` state and reason. Set `off` to stop polling for conversations. |
+| `NAVARCH_CONVERSATION_POLL_MS` | `5000` | Idle poll interval for queued conversation turns (1000–30000). |
+| `NAVARCH_CONVERSATION_TURN_TIMEOUT_MS` | `540000` | Time limit for one conversation turn's agent process (at most nine minutes). |
 | `NAVARCH_GUARD_EXTRA_ROOTS` | — | `path.delimiter`-separated (`:` on POSIX) extra directories the worktree guard allows beyond the session worktree, shared bare repo, and temp dirs. |
 
 ## Worktree boundary guard (host mode)

package/dist/adapters/claude-conversation.cjs

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeConversationRunner = exports.ClaudeStreamParser = exports.CLAUDE_CONVERSATION_TOOLS = void 0;
+exports.claudeConversationArgs = claudeConversationArgs;
+exports.runClaudeConversationTurn = runClaudeConversationTurn;
+const node_child_process_1 = require("node:child_process");
+const node_perf_hooks_1 = require("node:perf_hooks");
+const kill_agent_cjs_1 = require("../kill-agent.cjs");
+/**
+ * Read-only tools a Navi repository question may use. Anything not listed
+ * (Bash, Edit, Write, WebFetch, Task, MCP tools) is absent from the model's
+ * tool list, so a question cannot itself authorize a code change, PR,
+ * deployment, or new task. Machine-wide NAVARCH_CLAUDE_EXTRA_ARGS are
+ * deliberately not applied here: they could add --dangerously-skip-permissions
+ * or --allowedTools and widen this boundary.
+ */
+exports.CLAUDE_CONVERSATION_TOOLS = "Read,Grep,Glob";
+const STDERR_TAIL_BYTES = 8 * 1024;
+/**
+ * Incremental parser for `claude -p --output-format stream-json --verbose
+ * --include-partial-messages`. Chunks may split a record anywhere. Text is
+ * emitted from `text_delta` records the moment they are parsed. A complete
+ * `assistant` message is used only for a message that streamed no deltas
+ * (a CLI without partial-message support), so text is never emitted twice.
+ */
+class ClaudeStreamParser {
+    emit;
+    onRecord;
+    buffer = "";
+    currentMessageId = null;
+    streamedMessages = new Set();
+    emittedText = false;
+    separatorPending = false;
+    result = null;
+    /** `onRecord` fires for each complete record before any event it produces is emitted. */
+    constructor(emit, onRecord = () => undefined) {
+        this.emit = emit;
+        this.onRecord = onRecord;
+    }
+    /** Returns the number of complete records parsed from this chunk. */
+    push(chunk) {
+        this.buffer += chunk;
+        let records = 0;
+        for (;;) {
+            const newline = this.buffer.indexOf("\n");
+            if (newline < 0)
+                break;
+            const line = this.buffer.slice(0, newline).trim();
+            this.buffer = this.buffer.slice(newline + 1);
+            if (!line)
+                continue;
+            records += 1;
+            this.onRecord();
+            this.record(line);
+        }
+        return records;
+    }
+    /** Parses a final record that lacks a trailing newline. */
+    flush() {
+        const line = this.buffer.trim();
+        this.buffer = "";
+        if (line) {
+            this.onRecord();
+            this.record(line);
+        }
+    }
+    /** Used when the agent finished without any streamed text. */
+    get hasEmittedText() {
+        return this.emittedText;
+    }
+    text(text) {
+        if (!text)
+            return;
+        this.emit({ type: "text", text: this.separatorPending ? `\n\n${text}` : text });
+        this.separatorPending = false;
+        this.emittedText = true;
+    }
+    record(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!parsed || typeof parsed !== "object")
+            return;
+        const record = parsed;
+        switch (record.type) {
+            case "stream_event":
+                this.streamEvent(record.event, record.parent_tool_use_id);
+                break;
+            case "assistant":
+                this.assistant(record);
+                break;
+            case "user":
+                this.toolResults(record);
+                break;
+            case "result":
+                this.result = {
+                    isError: record.is_error === true || (typeof record.subtype === "string" && record.subtype !== "success"),
+                    text: typeof record.result === "string" ? record.result : null,
+                };
+                if (this.result.isError)
+                    this.emit({ type: "failure", reason: String(record.subtype ?? "error") });
+                break;
+        }
+    }
+    streamEvent(event, parentToolUseId) {
+        // Sub-agent output is not part of the user's answer.
+        if (!event || typeof event !== "object" || parentToolUseId)
+            return;
+        const e = event;
+        const message = asRec(e.message);
+        const delta = asRec(e.delta);
+        if (e.type === "message_start") {
+            this.currentMessageId = typeof message?.id === "string" ? message.id : null;
+        }
+        else if (e.type === "content_block_start") {
+            const block = asRec(e.content_block);
+            if (block?.type === "tool_use" && typeof block.name === "string") {
+                this.emit({ type: "tool_status", tool: block.name, phase: "started" });
+            }
+            else if (block?.type === "text" && this.emittedText) {
+                this.separatorPending = true;
+            }
+        }
+        else if (e.type === "content_block_delta" && delta?.type === "text_delta" && typeof delta.text === "string") {
+            if (this.currentMessageId)
+                this.streamedMessages.add(this.currentMessageId);
+            this.text(delta.text);
+        }
+    }
+    assistant(record) {
+        const message = asRec(record.message);
+        if (record.parent_tool_use_id || !message || !Array.isArray(message.content))
+            return;
+        if (typeof message.id === "string" && this.streamedMessages.has(message.id))
+            return;
+        for (const item of message.content) {
+            const block = asRec(item);
+            if (block?.type === "text" && typeof block.text === "string") {
+                if (this.emittedText)
+                    this.separatorPending = true;
+                this.text(block.text);
+            }
+            else if (block?.type === "tool_use" && typeof block.name === "string" && !(typeof message.id === "string" && this.streamedMessages.has(message.id))) {
+                this.emit({ type: "tool_status", tool: block.name, phase: "started" });
+            }
+        }
+    }
+    toolResults(record) {
+        const content = asRec(record.message)?.content;
+        if (!Array.isArray(content))
+            return;
+        for (const item of content) {
+            const block = asRec(item);
+            if (block?.type === "tool_result" && block.is_error === true) {
+                this.emit({ type: "tool_status", tool: "tool", phase: "failed" });
+            }
+        }
+    }
+}
+exports.ClaudeStreamParser = ClaudeStreamParser;
+function asRec(value) {
+    return value && typeof value === "object" ? value : null;
+}
+/** Fixed, read-only argument list for one conversation turn. */
+function claudeConversationArgs(options) {
+    const args = [
+        "-p",
+        "--output-format", "stream-json",
+        "--verbose",
+        "--include-partial-messages",
+        // The server holds the bounded history. A local Claude transcript would
+        // be a second, unbounded private copy of the conversation.
+        "--no-session-persistence",
+        // No operator hooks, project settings or MCP servers (including the
+        // lease-scoped Navarch task tools) in a conversation.
+        "--setting-sources", "",
+        "--strict-mcp-config",
+        "--tools", exports.CLAUDE_CONVERSATION_TOOLS,
+        "--permission-mode", "default",
+    ];
+    if (options.settingsPath)
+        args.push("--settings", options.settingsPath);
+    if (options.model)
+        args.push("--model", options.model);
+    return args;
+}
+async function runClaudeConversationTurn(options) {
+    const idle = (aborted) => ({
+        exitCode: null, timedOut: false, aborted, succeeded: false, firstEventMs: null, firstTextMs: null, stderr: "",
+    });
+    if (options.signal.aborted)
+        return idle(true);
+    const startedAt = node_perf_hooks_1.performance.now();
+    let firstEventMs = null;
+    let firstTextMs = null;
+    let timedOut = false;
+    let aborted = false;
+    let closed = false;
+    let stderr = "";
+    const deliver = (event) => {
+        // After stop, timeout or exit, late output must not reach the caller.
+        if (closed || aborted || timedOut)
+            return;
+        if (event.type === "text" && firstTextMs === null)
+            firstTextMs = node_perf_hooks_1.performance.now() - startedAt;
+        options.onEvent(event);
+    };
+    const parser = new ClaudeStreamParser(deliver, () => {
+        if (firstEventMs === null)
+            firstEventMs = node_perf_hooks_1.performance.now() - startedAt;
+    });
+    return new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)(options.bin, claudeConversationArgs(options), {
+            detached: process.platform !== "win32",
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdin?.on("error", () => undefined);
+        child.stdin?.end(options.prompt);
+        options.onProcessStarted?.(child.pid);
+        const timer = options.timeoutMs > 0 ? setTimeout(() => {
+            timedOut = true;
+            (0, kill_agent_cjs_1.killAgent)(child);
+        }, options.timeoutMs) : undefined;
+        const onAbort = () => {
+            aborted = true;
+            (0, kill_agent_cjs_1.killAgent)(child);
+        };
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            parser.push(chunk);
+        });
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr = (stderr + chunk).slice(-STDERR_TAIL_BYTES);
+        });
+        const finish = (exitCode) => {
+            if (closed)
+                return;
+            parser.flush();
+            // An answer delivered only in the final result record (no stream deltas).
+            if (!parser.hasEmittedText && parser.result && !parser.result.isError && parser.result.text) {
+                deliver({ type: "text", text: parser.result.text });
+            }
+            closed = true;
+            clearTimeout(timer);
+            options.signal.removeEventListener("abort", onAbort);
+            resolve({
+                exitCode, timedOut, aborted,
+                succeeded: exitCode === 0 && !aborted && !timedOut && !!parser.result && !parser.result.isError,
+                firstEventMs, firstTextMs, stderr,
+            });
+        };
+        child.on("error", (err) => {
+            stderr = (stderr + `\n${String(err)}`).slice(-STDERR_TAIL_BYTES);
+            finish(null);
+        });
+        child.on("close", (code) => finish(code));
+        if (options.signal.aborted)
+            onAbort();
+    });
+}
+exports.claudeConversationRunner = { run: runClaudeConversationTurn };

package/dist/adapters/claude.cjs

@@ -5,6 +5,7 @@ exports.runClaudeCodeAdapter = runClaudeCodeAdapter;
 const node_child_process_1 = require("node:child_process");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
 const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const claude_conversation_cjs_1 = require("./claude-conversation.cjs");
 const adapter_capacity_cjs_1 = require("../adapter-capacity.cjs");
 const DEFAULT_CLAUDE_MODEL = "claude-opus-5-5";
 const FALLBACK_CLAUDE_MODEL = "claude-opus-5-5";
@@ -281,4 +282,5 @@ function shellQuote(value) {
 exports.claudeCodeAdapter = {
     agentType: "claude-code",
     run: runClaudeCodeAdapter,
+    conversation: claude_conversation_cjs_1.claudeConversationRunner,
 };

package/dist/api.cjs

@@ -158,6 +158,20 @@ class NavarchApiClient {
             throw new Error("issueSecrets: empty response from control plane.");
         return result;
     }
+    /** Navi runtime v1: advertises conversation support for 90 s and returns queued turns for this machine. */
+    async pollConversations(machineId) {
+        const result = await this.request("POST", `/api/machines/${encodeURIComponent(machineId)}/conversations`, { protocol: 1 });
+        if (!result)
+            throw new Error("pollConversations: empty response from control plane.");
+        return result;
+    }
+    /** Navi runtime v1 claim / renew / append for one turn. */
+    async conversationCommand(machineId, conversationId, command) {
+        const result = await this.request("POST", `/api/machines/${encodeURIComponent(machineId)}/conversations/${encodeURIComponent(conversationId)}`, command);
+        if (!result)
+            throw new Error("conversationCommand: empty response from control plane.");
+        return result;
+    }
     /** Create a signed upload target for this lease's redacted transcript. */
     async getTranscriptUploadUrl(leaseId) {
         const result = await this.request("POST", `/api/dispatch/${encodeURIComponent(leaseId)}/transcript-upload-url`, {});

package/dist/browser-evidence.cjs

@@ -13,6 +13,7 @@ const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const playwright_1 = require("playwright");
 const zod_1 = require("zod");
+const local_browser_cjs_1 = require("./local-browser.cjs");
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
 const node_path_1 = __importDefault(require("node:path"));
@@ -46,7 +47,8 @@ const captureShape = {
 exports.captureSchema = zod_1.z.object(captureShape);
 /** Runs in the supervisor, outside the coding agent's OS sandbox. Fresh
  * contexts have no user cookies, arbitrary script execution, or file access.
- * Only the narrow capture operation is exposed to the lease. */
+ * The lease gets the narrow capture operation plus the loopback-only
+ * local_browser_* tools (local-browser.cts). */
 async function startBrowserEvidence(options) {
     const token = (0, node_crypto_1.randomBytes)(32).toString("hex");
     const fetchImpl = options.fetchImpl ?? fetch;
@@ -57,6 +59,10 @@ async function startBrowserEvidence(options) {
     let browser;
     let activeCapture;
     let attempts = 0;
+    const localBrowser = (0, local_browser_cjs_1.createLocalBrowser)({
+        launch: options.launch ?? launchCaptureBrowser,
+        isActive: () => !closed && options.isActive(),
+    });
     const assertActive = () => {
         if (closed || !options.isActive())
             throw new Error("Browser evidence lease is no longer active.");
@@ -204,6 +210,7 @@ async function startBrowserEvidence(options) {
                 return { isError: true, content: [{ type: "text", text: String(error) }] };
             }
         });
+        (0, local_browser_cjs_1.registerLocalBrowserTools)(server, localBrowser);
         res.on("close", () => { void transport.close(); void server.close(); });
         try {
             await server.connect(transport);
@@ -253,6 +260,7 @@ async function startBrowserEvidence(options) {
             const stopped = new Promise((resolve) => http.close(() => resolve()));
             http.closeAllConnections();
             await browser?.close().catch(() => undefined);
+            await localBrowser.close();
             await activeCapture?.catch(() => undefined);
             await stopped;
         },

package/dist/browser-probe.cjs

@@ -74,8 +74,19 @@ async function probeBrowserCapability(config, deps = {}) {
     const platform = deps.platform ?? process.platform;
     if (codexSandboxNeedsProbe(config, platform)) {
         const sandboxFailure = await probeCodexSandbox(config, deps);
+        if (sandboxFailure?.browserOnly && !config.mcpConfigPath) {
+            // Node runs in the sandbox, so the agent can start its services there;
+            // only Chromium cannot. Sessions get the supervisor's local_browser_*
+            // tools (local-browser.cts) instead, which reach the same loopback.
+            return {
+                status: "passed",
+                reason: truncate(`Headless Chromium cannot start inside the Codex sandbox (${sandboxFailure.detail}); ` +
+                    "Codex sessions browse local services through Navarch's local_browser tools, which run outside it."),
+                checked_at: now().toISOString(),
+            };
+        }
         if (sandboxFailure) {
-            return { status: "failed", reason: truncate(sandboxFailure), checked_at: now().toISOString() };
+            return { status: "failed", reason: truncate(sandboxFailure.reason), checked_at: now().toISOString() };
         }
     }
     return { status: "passed", checked_at: now().toISOString() };
@@ -215,8 +226,9 @@ async function probeCodexSandbox(config, deps) {
             // sandbox view: a path outside the granted read roots, not an old CLI.
             const hidden = /bwrap: execvp .*No such file or directory/.test(output);
             const opensslConfig = /OpenSSL configuration error/.test(output);
-            return ("Could not verify a browser inside the Codex sandbox: `codex sandbox` did not run the probe " +
-                `(${result.timedOut ? "timed out" : output.trim() ? summarizeLaunchFailure(output) : `exit ${result.code}`}). ` +
+            const detail = result.timedOut ? "timed out" : output.trim() ? summarizeLaunchFailure(output) : `exit ${result.code}`;
+            const reason = ("Could not verify a browser inside the Codex sandbox: `codex sandbox` did not run the probe " +
+                `(${detail}). ` +
                 (hidden
                     ? "The sandbox cannot see that executable; add its install directory to NAVARCH_GUARD_EXTRA_ROOTS, " +
                         "or run browser tasks with another agent."
@@ -224,19 +236,22 @@ async function probeCodexSandbox(config, deps) {
                         ? "Node cannot read its OpenSSL config inside the sandbox, so Codex sessions cannot run node either; " +
                             "update the Navarch runtime, or add that file's directory to NAVARCH_GUARD_EXTRA_ROOTS."
                         : "Update the Codex CLI, or run browser tasks with another agent."));
+            return { reason, detail, browserOnly: false };
         }
         const detail = result.timedOut ? "the launch timed out." : summarizeLaunchFailure(output);
         const machPort = /bootstrap_check_in|MachPortRendezvous|mach_port_rendezvous/i.test(output);
-        return (`Headless Chromium cannot start inside the Codex sandbox: ${detail} ` +
+        const reason = (`Headless Chromium cannot start inside the Codex sandbox: ${detail} ` +
             (machPort
                 ? "Codex's macOS sandbox denies Chromium's Mach port registration. "
                 : "") +
             "Run browser tasks with another agent (for example Claude Code), use NAVARCH_SANDBOX_MODE=docker, " +
             "or run Codex without its sandbox.");
+        return { reason, detail, browserOnly: true };
     }
     catch (error) {
         log.warn(`codex sandbox browser probe could not run: ${String(error)}`);
-        return `Could not verify a browser inside the Codex sandbox: ${summarizeLaunchFailure(String(error))}`;
+        const detail = summarizeLaunchFailure(String(error));
+        return { reason: `Could not verify a browser inside the Codex sandbox: ${detail}`, detail, browserOnly: false };
     }
     finally {
         await node_fs_1.promises.rm(probeRoot, { recursive: true, force: true }).catch(() => undefined);

package/dist/claim-loop.cjs

@@ -6,6 +6,7 @@ const api_cjs_1 = require("./api.cjs");
 const logger_cjs_1 = require("./logger.cjs");
 const log = (0, logger_cjs_1.createLogger)("claim");
 const MAX_CLAIM_BACKOFF_MS = 60_000;
+const pendingClaimSlot = "pending-claim-request";
 /**
  * Polls dispatch/claim on an interval, gated by available capacity
  * (implementation-plan.md WP-07 "Claim loop: poll dispatch, receive context
@@ -69,13 +70,24 @@ class ClaimLoop {
             // the dispatcher records it on the lease and excludes it from review
             // tasks of PRs this session authors.
             const sessionId = (0, node_crypto_1.randomUUID)();
-            const claimed = await this.api.claim({
-                available_capacity: this.capacity.available(),
-                capabilities: this.config.capabilities,
-                agent_type: this.config.agentType,
-                runtimes: this.config.runtimes,
-                session_id: sessionId,
-            });
+            // Hold the slot for the duration of the claim request. Navi conversation
+            // turns also take slots; without this reservation one could take the last
+            // slot while the control plane is granting a lease, stranding that lease.
+            const availableCapacity = this.capacity.available();
+            this.capacity.acquire(pendingClaimSlot);
+            let claimed;
+            try {
+                claimed = await this.api.claim({
+                    available_capacity: availableCapacity,
+                    capabilities: this.config.capabilities,
+                    agent_type: this.config.agentType,
+                    runtimes: this.config.runtimes,
+                    session_id: sessionId,
+                });
+            }
+            finally {
+                this.capacity.release(pendingClaimSlot);
+            }
             if (this.consecutiveFailures > 0) {
                 log.info(`claim polling recovered after ${this.consecutiveFailures} failed attempt(s)`);
             }

package/dist/cli.cjs

@@ -12,6 +12,8 @@ const api_cjs_1 = require("./api.cjs");
 const capacity_cjs_1 = require("./capacity.cjs");
 const heartbeat_loop_cjs_1 = require("./heartbeat-loop.cjs");
 const claim_loop_cjs_1 = require("./claim-loop.cjs");
+const loop_cjs_1 = require("./conversation/loop.cjs");
+const capability_cjs_1 = require("./conversation/capability.cjs");
 const session_cjs_1 = require("./session.cjs");
 const sandbox_cjs_1 = require("./sandbox.cjs");
 const logger_cjs_1 = require("./logger.cjs");
@@ -246,7 +248,7 @@ async function startCommand(flags) {
         log.warn(`not advertising browser-use: ${browserProbe.reason}`);
     }
     else if (browserProbe.status === "passed") {
-        log.info("browser probe passed; advertising browser-use");
+        log.info(`browser probe passed; advertising browser-use${browserProbe.reason ? ` (${browserProbe.reason})` : ""}`);
     }
     const config = {
         ...configuredConfig,
@@ -267,6 +269,13 @@ async function startCommand(flags) {
         return (0, session_cjs_1.runSession)({ api, config, shutdownSignal: runtimeShutdown.signal }, claimed, sessionId)
             .finally(() => activeSessionIds.delete(sessionId));
     });
+    const conversationLoop = new loop_cjs_1.ConversationLoop({
+        api,
+        machineId: identity.machine_id,
+        config,
+        capacity,
+        shutdownSignal: runtimeShutdown.signal,
+    });
     const bootId = (0, node_crypto_1.randomUUID)();
     const updateCoordinatorRef = {};
     let readySent = false;
@@ -282,6 +291,7 @@ async function startCommand(flags) {
         }
     }, (status) => {
         claimLoop.stop();
+        conversationLoop.stop();
         worktreeJanitor.stop();
         log.error(status === 410
             ? `agent ${identity.name} has been removed from the fleet; it can no longer claim tasks.`
@@ -298,12 +308,14 @@ async function startCommand(flags) {
     updateCoordinatorRef.current = new update_coordinator_cjs_1.RuntimeUpdateCoordinator({
         config,
         claimLoop,
+        conversationLoop,
         capacity,
         heartbeat,
     });
     heartbeat.start();
     worktreeJanitor.start();
     claimLoop.start();
+    conversationLoop.start();
     log.info(`navarch-runtime started: machine=${identity.name} agent=${config.agentType} max_sessions=${config.maxSessions} api_base=${identity.api_base}`);
     let shuttingDown = false;
     const shutdown = () => {
@@ -316,6 +328,7 @@ async function startCommand(flags) {
             log.info("shutting down: draining active sessions...");
             heartbeat.setUpdateState("draining");
             await claimLoop.drain();
+            await conversationLoop.drain();
             await capacity.waitForIdle();
             worktreeJanitor.stop();
             heartbeat.stop();
@@ -391,6 +404,8 @@ async function doctorCommand(flags) {
     console.log(`sandbox_mode:    ${config.sandboxMode}`);
     console.log(`worktree_guard:  ${config.worktreeGuard ? "on" : "off"}`);
     console.log(`runtimes:        ${config.runtimes?.join(", ") ?? config.agentType}`);
+    const conversation = (0, capability_cjs_1.conversationCapability)(config);
+    console.log(`navi_chat:       ${conversation.state.toUpperCase()}${conversation.state === "unsupported" ? ` — ${conversation.reason}` : ` (${config.agentType}, read-only)`}`);
     console.log(`docker:          ${dockerOk ? "available" : "NOT AVAILABLE (docker-backed sessions will fail)"}`);
     const browserProbe = await (0, browser_probe_cjs_1.probeBrowserCapability)(config);
     console.log(`browser:         ${browserProbe.status.toUpperCase()}${browserProbe.reason ? ` — ${browserProbe.reason}` : ""}`);

package/dist/config.cjs

@@ -178,6 +178,11 @@ function loadRuntimeConfig(env = process.env) {
         // by default; operators who would rather share nothing can opt out.
         reportUsageLimits: !["off", "false", "0"].includes(env.NAVARCH_USAGE_LIMITS ?? ""),
         browserProbe: !["off", "false", "0"].includes(env.NAVARCH_BROWSER_PROBE ?? ""),
+        naviConversations: !["off", "false", "0"].includes(env.NAVARCH_NAVI_CONVERSATIONS ?? ""),
+        // The server stops waiting for a capability advertisement after 90 s and
+        // asks for a poll at least every 30 s; the floor only bounds control-plane load.
+        conversationPollIntervalMs: Math.min(30_000, Math.max(1_000, envInt(env, "NAVARCH_CONVERSATION_POLL_MS", 5_000))),
+        conversationTurnTimeoutMs: Math.min(9 * 60_000, envInt(env, "NAVARCH_CONVERSATION_TURN_TIMEOUT_MS", 9 * 60_000)),
         codexHome: defaultCodexHome(env),
         claudeConfigPath: defaultClaudeConfigPath(env),
     };

package/dist/conversation/capability.cjs

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conversationCapability = conversationCapability;
+exports.conversationSupportMatrix = conversationSupportMatrix;
+const index_cjs_1 = require("../adapters/index.cjs");
+/**
+ * Whether this runtime can execute a Navi conversation turn, with the reason
+ * when it cannot. The runtime polls (and so advertises conversation support
+ * to the control plane) only when this returns `supported`.
+ *
+ * A conversation always runs on the machine's configured primary adapter
+ * (`agentType`). An unsupported primary adapter is reported, never replaced
+ * by another installed agent: the user selected this runtime for the agent it
+ * runs.
+ */
+function conversationCapability(config) {
+    if (!config.naviConversations) {
+        return { state: "unsupported", reason: "Disabled by NAVARCH_NAVI_CONVERSATIONS=off." };
+    }
+    const adapter = (0, index_cjs_1.selectAdapter)(config.agentType);
+    if (!adapter.conversation) {
+        return {
+            state: "unsupported",
+            reason: `The ${config.agentType} adapter has no streamed read-only conversation path.`,
+        };
+    }
+    if (config.sandboxMode !== "host") {
+        return {
+            state: "unsupported",
+            reason: "Conversations run on the host; NAVARCH_SANDBOX_MODE=docker is not supported yet.",
+        };
+    }
+    if (!config.worktreeGuard) {
+        return {
+            state: "unsupported",
+            reason: "Conversations need the worktree read boundary; NAVARCH_WORKTREE_GUARD is off.",
+        };
+    }
+    return { state: "supported" };
+}
+/** Per-adapter support table for docs and diagnostics (host sandbox, guard on, feature enabled). */
+function conversationSupportMatrix() {
+    const agents = ["claude-code", "codex", "gemini", "opencode", "acp", "qoder", "pi-local", "pi"];
+    return agents.map((agentType) => ({
+        agentType,
+        capability: conversationCapability({
+            agentType,
+            sandboxMode: "host",
+            worktreeGuard: true,
+            naviConversations: true,
+        }),
+    }));
+}