@sagentlab/navarch-runtime 0.1.40 → 0.1.42

package/README.md

@@ -2,12 +2,12 @@
 
 The machine-side half of Navarch (WP-07): registers this machine with the
 control plane, then loops claim → sandbox → agent CLI → report until you stop
-it. Plain Node/TypeScript, zero production dependencies, no Next.js coupling
+it. Plain Node/TypeScript, no Next.js coupling, and no shared app-code coupling
 — this directory is a self-contained package you can `npx` on any fresh
 machine.
 
 The machine operator selects **Claude Code**, **OpenAI Codex**, **Google
-Gemini CLI**, or **OpenCode** when connecting a worker. Any selected agent can
+Gemini CLI**, **OpenCode**, or an **Agent Client Protocol (ACP)** agent when connecting a worker. Any selected agent can
 run any project task; task eligibility depends on capabilities and project
 gates, not agent type — see "Choosing an agent" below.
 
@@ -29,7 +29,7 @@ Before generating the command, prepare the machine:
 - install Node.js 20 or later (the standard installation includes `npm` and
   `npx`) and Git;
 - install the coding-agent CLI selected in Navarch — `claude`, `codex`,
-  `gemini`, or `opencode` — and complete its normal authentication flow; and
+  `gemini`, `opencode`, or `dsh` for the default ACP integration — and complete its normal authentication flow; and
 - for Docker-backed sessions, install and start Docker and use an image that
   contains the selected agent CLI and the repository toolchain, with provider
   credentials supplied through the approved machine or project configuration.
@@ -44,7 +44,7 @@ node --version       # 20 or later
 npm --version
 npx --version
 git --version
-codex --version      # or: claude --version / gemini --version / opencode --version
+codex --version      # or: claude / gemini / opencode / dsh --version
 ```
 
 Every command above must succeed before the long-running worker starts. See
@@ -152,10 +152,10 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 
 | Command | Purpose |
 |---|---|
-| `register --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
-| `connect --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
-| `start [--agent claude-code\|codex\|gemini\|opencode]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
-| `supervise [--agent claude-code\|codex\|gemini\|opencode]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
+| `register --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode\|acp] […]` | Registers this machine, saves its local agent choice, and prints the token once. |
+| `connect --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode\|acp] [--project <id>] […]` | Connects this machine to one project, saves its local agent choice, and prints the token once. |
+| `start [--agent claude-code\|codex\|gemini\|opencode\|acp]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
+| `supervise [--agent claude-code\|codex\|gemini\|opencode\|acp]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
 | `doctor` | Prints resolved config + Docker/registration status; no side effects. |
 
 ### Running multiple agents on one machine
@@ -311,7 +311,7 @@ unchanged across the deployment.
 | `NAVARCH_SANDBOX_PROFILE` | `trusted-development` | Named security profile for Docker sessions (`src/sandbox-profile.cts`): `trusted-development` (image-default user, uncapped, open egress), `untrusted-code` (non-root, 2 CPU / 4g / 512 PIDs, deny-by-default egress, read-only shared git), `elevated-verification` (non-root, 4 CPU / 8g / 2048 PIDs, egress limited to GitHub plus package registries). The default is the exact pre-profile flag set. |
 | `NAVARCH_SANDBOX_EGRESS_NETWORK` | _(unset)_ | Docker network that enforces a profile's egress allowlist. Docker cannot filter by domain itself, so an allowlist profile without this fails closed to `--network=none` and records the denial. |
 | `NAVARCH_DOCKER_IMAGE` | `ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0` | Version-pinned per-session image with Node 20, git, GitHub CLI, ripgrep, jq, SSH, and Claude Code 2.1.218. Override with an image tag or digest you control. |
-| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent CLI: `claude-code`, `codex`, `gemini`, or `opencode`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
+| `NAVARCH_AGENT` | saved choice, then `claude-code` | Local choice of agent adapter: `claude-code`, `codex`, `gemini`, `opencode`, or `acp`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
 | `NAVARCH_RUNTIMES` | selected `NAVARCH_AGENT` | Comma list of installed/authenticated adapters advertised to dispatch. The control plane chooses among these per project/task. |
 | `NAVARCH_UPDATE_CHANNEL` | `stable` | Release channel advertised by the worker (`stable` or `canary`); the server-managed machine channel remains authoritative. |
 | `NAVARCH_AUTO_UPDATE` | on under `supervise` | Set `off`, `false`, or `0` to report releases without staging or activating them. Automatic activation is always off under plain `start`. |
@@ -323,6 +323,8 @@ unchanged across the deployment.
 | `NAVARCH_GEMINI_EXTRA_ARGS` | — | Comma list of extra CLI args appended after the generated MCP settings, `stream-json`, and unattended defaults (Gemini). |
 | `NAVARCH_OPENCODE_BIN` | `opencode` | Path/name of the OpenCode CLI binary. |
 | `NAVARCH_OPENCODE_EXTRA_ARGS` | — | Comma list of extra CLI args appended after `run`, the prompt, and the generated `--format json` argument. Explicit `--format`, `--model`, or `--variant` values replace the corresponding per-session default. |
+| `NAVARCH_ACP_BIN` | `dsh` | Path/name of an Agent Client Protocol v1 stdio server. DeepSeek Harness is the default implementation. |
+| `NAVARCH_ACP_EXTRA_ARGS` | `--profile,acp` | Comma list of arguments used to start the ACP server. Override this together with `NAVARCH_ACP_BIN` for another ACP-compatible coding agent. |
 | `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. |
 | `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. |
@@ -383,6 +385,10 @@ as an explicit read-only mount.
   OpenCode receives a private, per-session config, project config discovery is
   disabled, and lease MCP headers are referenced through child-only environment
   variables instead of being copied into its config file or argv.
+- **ACP agents:** the protocol client rejects every unattended permission
+  escalation. The agent remains responsible for enforcing its declared file
+  sandbox; use Navarch Docker mode when the ACP server itself does not provide
+  a trustworthy workspace boundary.
 
 The resulting boundary is:
 
@@ -443,8 +449,12 @@ export NAVARCH_AGENT=gemini
 # use a Docker image containing OpenCode for the normal isolated path.
 export NAVARCH_AGENT=opencode
 
+# Agent Client Protocol — defaults to DeepSeek Harness `dsh --profile acp`.
+# Override NAVARCH_ACP_BIN / NAVARCH_ACP_EXTRA_ARGS for another ACP v1 server.
+export NAVARCH_AGENT=acp
+
 # Advanced compatibility mode: advertise every installed adapter.
-export NAVARCH_RUNTIMES=claude-code,codex,gemini,opencode
+export NAVARCH_RUNTIMES=claude-code,codex,gemini,opencode,acp
 ```
 
 For the legacy single-runtime setting, priority is `start --agent` →
@@ -453,7 +463,7 @@ For the legacy single-runtime setting, priority is `start --agent` →
 the locally selected `NAVARCH_AGENT` handles every claimed task. Sandbox
 projects remain constrained to Claude Code.
 
-All four BYO adapters implement the same `AgentAdapter` interface
+All five BYO adapters implement the same `AgentAdapter` interface
 (`src/adapters/types.cts`) and run either directly on the host or via
 `docker exec` in the session's sandbox container, exactly like the Claude
 adapter always has — `session.cts` picks one (`src/adapters/index.cts`'s
@@ -469,7 +479,8 @@ effort on completion. Gemini currently uses its `auto` model default and does
 not expose a reasoning-effort flag. OpenCode accepts any `provider/model`
 reference (the platform default is `opencode/x-preview-f-free`, Ox Alpha Free
 (Unlimited) on OpenCode Zen), or `default` to preserve the authenticated
-account's selection.
+account's selection. ACP sessions use the agent's advertised default model and
+set the standard `reasoning_effort` configuration option when it is available.
 Machine-wide extra arguments still configure other CLI behavior; dispatched
 model policy wins.
 
@@ -527,6 +538,15 @@ to OpenCode's remote-server config with OAuth disabled and environment-backed
 headers. Missing accounting fields stay absent rather than becoming a
 fabricated zero.
 
+The ACP adapter speaks the standard [Agent Client Protocol](https://agentclientprotocol.com)
+v1 JSON-RPC transport over stdio. It creates one protocol session in the task
+worktree, converts Navarch's HTTP/stdio MCP entries, consumes semantic message,
+thought, and usage updates, and fails permission requests closed because no
+human is attached to a worker turn. [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+ships that server as `dsh --profile acp`. This is intentionally not the
+REST-based [Agent Communication Protocol](https://agentcommunicationprotocol.dev),
+which is a different protocol now maintained as part of A2A.
+
 ## Architecture
 
 ```
@@ -547,6 +567,8 @@ cli.cts
                     - claudeCodeAdapter (adapters/claude.cts) — `claude -p <prompt> --mcp-config <path>`
                     - codexAdapter      (adapters/codex.cts)  — `codex exec <prompt> --json -c mcp_servers.*=...`
                     - geminiAdapter     (adapters/gemini.cts) — `gemini --prompt <prompt> --output-format stream-json`
+                    - openCodeAdapter   (adapters/opencode.cts) — `opencode run <prompt> --format json`
+                    - acpAdapter        (adapters/acp.cts) — ACP v1 JSON-RPC/stdio; defaults to `dsh --profile acp`
                   heartbeating the lease every NAVARCH_LEASE_HEARTBEAT_INTERVAL_MS throughout either;
                   a failed heartbeat aborts the run (kills the process) and marks the outcome as lease-lost
                5. mapExitCondition (exit-conditions.cts) → redact.cts scrubs the transcript → upload.cts PUTs it

package/dist/adapters/acp.cjs

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acpAdapter = void 0;
+exports.runAcpAdapter = runAcpAdapter;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_stream_1 = require("node:stream");
+/**
+ * How long a cancelled agent may take to observe `session/cancel` and settle
+ * the in-flight `session/prompt` before the subprocess is terminated. The
+ * notification is only written to the child's stdin; without this window the
+ * SIGTERM in `terminateChild` can land before the agent's event loop ever
+ * reads the line, so the protocol cancellation is silently lost and the agent
+ * gets no chance to release what it is holding.
+ */
+const CANCEL_GRACE_MS = 2_000;
+/**
+ * Generic Agent Client Protocol v1 adapter. DeepSeek Harness is the default
+ * implementation (`dsh --profile acp`), while NAVARCH_ACP_BIN and
+ * NAVARCH_ACP_EXTRA_ARGS let an operator substitute any ACP-compatible coding
+ * agent without adding another Navarch adapter.
+ *
+ * The similarly named Agent Communication Protocol at
+ * agentcommunicationprotocol.dev is a different, REST-based agent-to-agent
+ * protocol. Coding-agent subprocesses such as dsh expose Agent Client Protocol
+ * over newline-delimited JSON-RPC on stdio, which is the boundary implemented
+ * here.
+ */
+async function runAcpAdapter(options) {
+    const acp = await import("@agentclientprotocol/sdk");
+    const mcpServers = await readMcpServers(options.mcpConfigPath, options.env);
+    const child = spawnAcpAgent(options);
+    const rawStdout = [];
+    const stderr = [];
+    const protocolInput = new node_stream_1.PassThrough();
+    const messages = [];
+    const thoughts = [];
+    let costUsd;
+    let timedOut = false;
+    let killedByLeaseLoss = false;
+    let sessionId;
+    let stopReason;
+    // Resolved once the in-flight prompt request settles, however it settles, so
+    // cancellation can wait for the agent instead of racing the kill.
+    let settlePrompt = () => undefined;
+    const promptSettled = new Promise((resolve) => {
+        settlePrompt = resolve;
+    });
+    child.stdout.on("data", (chunk) => {
+        rawStdout.push(chunk);
+        protocolInput.write(chunk);
+    });
+    child.stdout.on("end", () => protocolInput.end());
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on("error", (error) => {
+        stderr.push(`\n${describeError(error)}`);
+        protocolInput.end();
+    });
+    const stream = acp.ndJsonStream(node_stream_1.Writable.toWeb(child.stdin), node_stream_1.Readable.toWeb(protocolInput));
+    const client = acp.client({ name: "navarch-runtime" })
+        .onNotification(acp.methods.client.session.update, ({ params }) => {
+        collectUpdate(params, messages, thoughts, (value) => {
+            costUsd = value;
+        });
+    })
+        // Navarch sessions are unattended. Permission escalation therefore fails
+        // closed instead of inventing human consent on the worker's behalf.
+        .onRequest(acp.methods.client.session.requestPermission, ({ params }) => {
+        const rejection = params.options.find((option) => option.kind === "reject_always")
+            ?? params.options.find((option) => option.kind === "reject_once");
+        return rejection
+            ? { outcome: { outcome: "selected", optionId: rejection.optionId } }
+            : { outcome: { outcome: "cancelled" } };
+    });
+    const connection = client.connect(stream);
+    const controller = new AbortController();
+    let abortProtocol = Promise.resolve();
+    controller.signal.addEventListener("abort", () => {
+        abortProtocol = (async () => {
+            if (sessionId) {
+                await connection.agent.notify(acp.methods.agent.session.cancel, { sessionId }).catch(() => undefined);
+                await Promise.race([
+                    promptSettled,
+                    new Promise((resolve) => setTimeout(resolve, CANCEL_GRACE_MS)),
+                ]);
+            }
+            connection.close();
+        })();
+    }, { once: true });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, options.timeoutMs);
+    const onAbort = () => {
+        killedByLeaseLoss = true;
+        controller.abort();
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted)
+        onAbort();
+    try {
+        const context = connection.agent;
+        await context.request(acp.methods.agent.initialize, {
+            protocolVersion: acp.PROTOCOL_VERSION,
+            clientCapabilities: {},
+        });
+        const created = await context.request(acp.methods.agent.session.new, {
+            cwd: options.cwd ?? process.cwd(),
+            mcpServers,
+        });
+        sessionId = created.sessionId;
+        let configOptions = created.configOptions ?? [];
+        configOptions = await setConfigOption(context, acp.methods.agent.session.setConfigOption, sessionId, configOptions, "model", options.model === "default" ? undefined : options.model);
+        await setConfigOption(context, acp.methods.agent.session.setConfigOption, sessionId, configOptions, "reasoning_effort", options.reasoningEffort);
+        let response;
+        try {
+            response = await context.request(acp.methods.agent.session.prompt, {
+                sessionId,
+                prompt: [{ type: "text", text: options.prompt }],
+            });
+        }
+        finally {
+            settlePrompt();
+        }
+        stopReason = response.stopReason;
+        await Promise.race([
+            context.request(acp.methods.agent.session.close, { sessionId }).catch(() => undefined),
+            new Promise((resolve) => setTimeout(resolve, Math.min(5_000, options.timeoutMs))),
+        ]);
+    }
+    catch (error) {
+        if (!controller.signal.aborted)
+            stderr.push(`\n${describeError(error)}`);
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+        await abortProtocol;
+        connection.close();
+        await terminateChild(child, options, controller.signal.aborted);
+    }
+    if (thoughts.length > 0)
+        stderr.push(`\n# ACP agent thoughts\n${thoughts.join("\n")}`);
+    const reportText = messages.join("").trim();
+    const successfulStop = stopReason === "end_turn" || stopReason === "max_tokens" || stopReason === "max_turn_requests";
+    return {
+        exitCode: successfulStop ? 0 : timedOut || killedByLeaseLoss ? null : 1,
+        timedOut,
+        killedByLeaseLoss,
+        stdout: Buffer.concat(rawStdout).toString("utf8"),
+        stderr: stderr.join(""),
+        ...(reportText ? { reportText } : {}),
+        ...(costUsd !== undefined ? { costUsd } : {}),
+    };
+}
+function collectUpdate(notification, messages, thoughts, setCostUsd) {
+    const update = notification.update;
+    if ((update.sessionUpdate === "agent_message_chunk" || update.sessionUpdate === "agent_thought_chunk")
+        && update.content.type === "text") {
+        (update.sessionUpdate === "agent_message_chunk" ? messages : thoughts).push(update.content.text);
+    }
+    if (update.sessionUpdate === "usage_update"
+        && update.cost?.currency.toUpperCase() === "USD"
+        && Number.isFinite(update.cost.amount)
+        && update.cost.amount >= 0) {
+        setCostUsd(update.cost.amount);
+    }
+}
+async function setConfigOption(context, method, sessionId, options, configId, desired) {
+    if (!desired)
+        return options;
+    const expectedCategory = configId === "model" ? "model" : "thought_level";
+    const option = options.find((candidate) => ((candidate.id === configId || candidate.category === expectedCategory)
+        && candidate.type === "select"));
+    if (!option || option.type !== "select")
+        return options;
+    const choices = option.options.flatMap((candidate) => "group" in candidate ? candidate.options : [candidate]);
+    const selected = choices.find((candidate) => candidate.value === desired || candidate.name === desired);
+    if (!selected || selected.value === option.currentValue)
+        return options;
+    const response = await context.request(method, { sessionId, configId, value: selected.value });
+    return response.configOptions ?? options;
+}
+async function readMcpServers(configPath, env) {
+    if (!configPath)
+        return [];
+    const parsed = JSON.parse(await node_fs_1.promises.readFile(configPath, "utf8"));
+    return Object.entries(parsed.mcpServers ?? {}).flatMap(([name, server]) => {
+        const url = server.httpUrl ?? server.url;
+        if (url) {
+            return [{
+                    type: "http",
+                    name,
+                    url,
+                    headers: Object.entries(server.headers ?? {}).map(([header, value]) => ({
+                        name: header,
+                        value: resolveEnvReference(value, env),
+                    })),
+                }];
+        }
+        if (!server.command)
+            return [];
+        return [{
+                name,
+                command: server.command,
+                args: server.args ?? [],
+                env: Object.entries(server.env ?? {}).map(([key, value]) => ({
+                    name: key,
+                    value: resolveEnvReference(value, env),
+                })),
+            }];
+    });
+}
+function resolveEnvReference(value, env) {
+    const name = value.match(/^\{env:([A-Z_][A-Z0-9_]*)\}$/)?.[1];
+    if (!name)
+        return value;
+    const resolved = env[name] ?? process.env[name];
+    if (resolved === undefined)
+        throw new Error(`ACP MCP configuration references missing environment variable ${name}.`);
+    return resolved;
+}
+function spawnAcpAgent(options) {
+    const env = { ...process.env, ...options.env };
+    if (!options.dockerExec) {
+        return (0, node_child_process_1.spawn)(options.bin, options.extraArgs, {
+            cwd: options.cwd,
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    }
+    const { containerName } = options.dockerExec;
+    const forwardedEnv = Object.keys(options.env).flatMap((name) => ["--env", name]);
+    return (0, node_child_process_1.spawn)("docker", [
+        "exec",
+        "-i",
+        ...forwardedEnv,
+        containerName,
+        "sh",
+        "-c",
+        '[ -f /tmp/session.env ] && . /tmp/session.env; exec "$@"',
+        "sh",
+        options.bin,
+        ...options.extraArgs,
+    ], { env, stdio: ["pipe", "pipe", "pipe"] });
+}
+async function terminateChild(child, options, forceContainerKill) {
+    if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGTERM");
+        await Promise.race([
+            new Promise((resolve) => child.once("close", () => resolve())),
+            new Promise((resolve) => setTimeout(resolve, 1_000)),
+        ]);
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill("SIGKILL");
+    }
+    if (options.dockerExec && forceContainerKill) {
+        await options.dockerExec.runner.run("docker", ["kill", options.dockerExec.containerName]).catch(() => undefined);
+    }
+}
+function describeError(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+exports.acpAdapter = {
+    agentType: "acp",
+    run: runAcpAdapter,
+};

package/dist/adapters/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runPiAdapter = exports.piAdapter = exports.runOpenCodeAdapter = exports.openCodeAdapter = exports.runGeminiAdapter = exports.geminiAdapter = exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
+exports.runAcpAdapter = exports.acpAdapter = exports.runPiAdapter = exports.piAdapter = exports.runOpenCodeAdapter = exports.openCodeAdapter = exports.runGeminiAdapter = exports.geminiAdapter = exports.runCodexAdapter = exports.codexAdapter = exports.runClaudeCodeAdapter = exports.claudeCodeAdapter = void 0;
 exports.selectAdapter = selectAdapter;
 const claude_cjs_1 = require("./claude.cjs");
 Object.defineProperty(exports, "claudeCodeAdapter", { enumerable: true, get: function () { return claude_cjs_1.claudeCodeAdapter; } });
@@ -17,6 +17,9 @@ Object.defineProperty(exports, "runOpenCodeAdapter", { enumerable: true, get: fu
 const pi_cjs_1 = require("./pi.cjs");
 Object.defineProperty(exports, "piAdapter", { enumerable: true, get: function () { return pi_cjs_1.piAdapter; } });
 Object.defineProperty(exports, "runPiAdapter", { enumerable: true, get: function () { return pi_cjs_1.runPiAdapter; } });
+const acp_cjs_1 = require("./acp.cjs");
+Object.defineProperty(exports, "acpAdapter", { enumerable: true, get: function () { return acp_cjs_1.acpAdapter; } });
+Object.defineProperty(exports, "runAcpAdapter", { enumerable: true, get: function () { return acp_cjs_1.runAcpAdapter; } });
 /**
  * Picks the AgentAdapter (adapters/types.cts) session.cts should run a
  * session with, keyed off config.cts's `agentType` (NAVARCH_AGENT). This is
@@ -32,6 +35,8 @@ function selectAdapter(agentType) {
             return gemini_cjs_1.geminiAdapter;
         case "opencode":
             return opencode_cjs_1.openCodeAdapter;
+        case "acp":
+            return acp_cjs_1.acpAdapter;
         case "claude-code":
             return claude_cjs_1.claudeCodeAdapter;
         case "pi":

package/dist/adapters/opencode.cjs

@@ -4,6 +4,7 @@ exports.openCodeAdapter = void 0;
 exports.runOpenCodeAdapter = runOpenCodeAdapter;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
+const config_cjs_1 = require("../config.cjs");
 /**
  * Headless OpenCode adapter, fixture-pinned to the OpenCode 1.18 JSON/config
  * contract:
@@ -24,9 +25,7 @@ async function runOpenCodeAdapter(options) {
             timedOut: false,
             killedByLeaseLoss: false,
             stdout: "",
-            stderr: "OpenCode cannot enforce Navarch's host worktree boundary for shell side effects. " +
-                "Use NAVARCH_SANDBOX_MODE=docker, or explicitly set NAVARCH_WORKTREE_GUARD=off " +
-                "only on an otherwise isolated machine.",
+            stderr: config_cjs_1.OPENCODE_HOST_GUARD_MESSAGE,
         };
     }
     const env = { ...options.env };

package/dist/cli.cjs

@@ -66,7 +66,7 @@ function agentFromFlag(flags) {
     if (value === undefined)
         return undefined;
     if (!(0, config_cjs_1.isRuntimeAgentType)(value)) {
-        throw new Error("--agent must be one of 'claude-code', 'codex', 'gemini', or 'opencode'.");
+        throw new Error("--agent must be one of 'claude-code', 'codex', 'gemini', 'opencode', or 'acp'.");
     }
     return value;
 }
@@ -274,7 +274,19 @@ async function superviseCommand(flags) {
     process.exitCode = exitCode;
 }
 async function doctorCommand(flags) {
-    const config = configFromFlags(flags);
+    // doctor is the command an operator reaches for precisely when the config
+    // will not load — an OpenCode-only machine on a guarded host refuses to
+    // start (config.cts). Report that as the diagnosis instead of rethrowing it
+    // as a bare CLI error.
+    let config;
+    try {
+        config = configFromFlags(flags);
+    }
+    catch (err) {
+        console.log(`config:          UNUSABLE — ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+        return;
+    }
     const dockerOk = await (0, sandbox_cjs_1.isDockerAvailable)();
     console.log(`api_base:        ${config.apiBase}`);
     console.log(`config_dir:      ${config.configDir}`);
@@ -282,6 +294,8 @@ async function doctorCommand(flags) {
     console.log(`max_sessions:    ${config.maxSessions}`);
     console.log(`capabilities:    ${config.capabilities.join(", ")}`);
     console.log(`sandbox_mode:    ${config.sandboxMode}`);
+    console.log(`worktree_guard:  ${config.worktreeGuard ? "on" : "off"}`);
+    console.log(`runtimes:        ${config.runtimes?.join(", ") ?? config.agentType}`);
     console.log(`docker:          ${dockerOk ? "available" : "NOT AVAILABLE (docker-backed sessions will fail)"}`);
     let identity;
     try {
@@ -301,11 +315,11 @@ function helpText() {
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
   navarch-runtime connect --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
-  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex|gemini|opencode]
-  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini|opencode]
+      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
+  navarch-runtime start [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp]
+  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp]
   navarch-runtime doctor [--config-dir <path>]
   navarch-runtime code-graph --query <symbol-or-file> [--mode search|callers|callees|impact] [--commit HEAD] [--depth 1..5] [--repo <path>]
 

package/dist/config.cjs

@@ -3,8 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SANDBOX_IMAGE = void 0;
+exports.OPENCODE_HOST_GUARD_MESSAGE = exports.DEFAULT_SANDBOX_IMAGE = void 0;
 exports.isRuntimeAgentType = isRuntimeAgentType;
+exports.opencodeBlockedOnHost = opencodeBlockedOnHost;
 exports.loadRuntimeConfig = loadRuntimeConfig;
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -15,7 +16,8 @@ function isRuntimeAgentType(value) {
     return (value === "claude-code" ||
         value === "codex" ||
         value === "gemini" ||
-        value === "opencode");
+        value === "opencode" ||
+        value === "acp");
 }
 function envInt(env, name, fallback) {
     const raw = env[name];
@@ -43,6 +45,18 @@ function envList(env, name, fallback) {
         .map((s) => s.trim())
         .filter(Boolean);
 }
+/**
+ * OpenCode is the one runtime Navarch cannot fence into a per-session worktree
+ * on the host: its CLI has no equivalent of Claude's PreToolUse hook or
+ * Codex's native permission profile. Docker mode supplies the boundary
+ * instead, and NAVARCH_WORKTREE_GUARD=off is the explicit opt-out.
+ */
+function opencodeBlockedOnHost(sandboxMode, worktreeGuard) {
+    return sandboxMode === "host" && worktreeGuard;
+}
+exports.OPENCODE_HOST_GUARD_MESSAGE = "OpenCode cannot enforce Navarch's host worktree boundary for shell side effects. " +
+    "Use NAVARCH_SANDBOX_MODE=docker, or explicitly set NAVARCH_WORKTREE_GUARD=off " +
+    "only on an otherwise isolated machine.";
 /**
  * Loads runtime config from NAVARCH_* env vars, with sane defaults for a
  * fresh machine. Accepts an explicit env map (defaulting to process.env) so
@@ -56,8 +70,23 @@ function loadRuntimeConfig(env = process.env) {
     // prerequisite for claiming ordinary shell work.
     const sandboxMode = env.NAVARCH_SANDBOX_MODE === "docker" ? "docker" : "host";
     const defaultCapabilities = sandboxMode === "docker" ? ["docker-sandbox", "shell"] : ["shell", "browser-use"];
-    const agentType = isRuntimeAgentType(env.NAVARCH_AGENT) ? env.NAVARCH_AGENT : "claude-code";
-    const runtimes = envList(env, "NAVARCH_RUNTIMES", [agentType]).filter(isRuntimeAgentType);
+    const requestedAgentType = isRuntimeAgentType(env.NAVARCH_AGENT) ? env.NAVARCH_AGENT : "claude-code";
+    // Multiple sessions share one machine; keeping each agent inside its own
+    // worktree is the safe default, so disabling is the explicit opt-out.
+    const worktreeGuard = !["off", "false", "0"].includes(env.NAVARCH_WORKTREE_GUARD ?? "");
+    const requestedRuntimes = envList(env, "NAVARCH_RUNTIMES", [requestedAgentType]).filter(isRuntimeAgentType);
+    // OpenCode's CLI cannot express the host worktree boundary, so its adapter
+    // fails closed there (adapters/opencode.cts). Advertising it anyway meant
+    // the machine claimed OpenCode tasks it could only fail, one lease at a
+    // time; keep it out of the claim instead of discovering this per session.
+    const runnableRuntimes = requestedRuntimes.filter((runtime) => runtime !== "opencode" || !opencodeBlockedOnHost(sandboxMode, worktreeGuard));
+    if (requestedRuntimes.includes("opencode") && runnableRuntimes.length === 0) {
+        throw new Error(exports.OPENCODE_HOST_GUARD_MESSAGE);
+    }
+    const agentType = runnableRuntimes.includes(requestedAgentType) || runnableRuntimes.length === 0
+        ? requestedAgentType
+        : (runnableRuntimes[0] ?? requestedAgentType);
+    const runtimes = runnableRuntimes;
     return {
         apiBase: env.NAVARCH_API_BASE ?? "http://localhost:3000",
         workspaceRoot: env.NAVARCH_WORKSPACE_ROOT ?? node_path_1.default.join(configDir, "sandboxes"),
@@ -83,6 +112,8 @@ function loadRuntimeConfig(env = process.env) {
         geminiExtraArgs: envList(env, "NAVARCH_GEMINI_EXTRA_ARGS", []),
         opencodeBin: env.NAVARCH_OPENCODE_BIN ?? "opencode",
         opencodeExtraArgs: envList(env, "NAVARCH_OPENCODE_EXTRA_ARGS", []),
+        acpBin: env.NAVARCH_ACP_BIN ?? "dsh",
+        acpExtraArgs: envList(env, "NAVARCH_ACP_EXTRA_ARGS", ["--profile", "acp"]),
         gitAuthorName: env.NAVARCH_GIT_AUTHOR_NAME ?? "sagentlab",
         gitAuthorEmail: env.NAVARCH_GIT_AUTHOR_EMAIL ?? "z@sagentlab.com",
         mcpConfigPath: env.NAVARCH_MCP_CONFIG_PATH ?? null,
@@ -95,9 +126,7 @@ function loadRuntimeConfig(env = process.env) {
             : sandbox_profile_cjs_1.DEFAULT_SANDBOX_PROFILE_ID,
         sandboxEgressNetwork: env.NAVARCH_SANDBOX_EGRESS_NETWORK?.trim() || null,
         dockerImage: env.NAVARCH_DOCKER_IMAGE ?? exports.DEFAULT_SANDBOX_IMAGE,
-        // Multiple sessions share one machine; keeping each agent inside its own
-        // worktree is the safe default, so disabling is the explicit opt-out.
-        worktreeGuard: !["off", "false", "0"].includes(env.NAVARCH_WORKTREE_GUARD ?? ""),
+        worktreeGuard,
         guardExtraRoots: (env.NAVARCH_GUARD_EXTRA_ROOTS ?? "")
             .split(node_path_1.default.delimiter)
             .map((s) => s.trim())

package/dist/machine-store.cjs

@@ -50,7 +50,9 @@ async function resolveMachineIdentity(configDir, apiBaseFallback) {
             api_base: process.env.NAVARCH_API_BASE ?? apiBaseFallback,
             agent_type: process.env.NAVARCH_AGENT === "codex" ||
                 process.env.NAVARCH_AGENT === "claude-code" ||
-                process.env.NAVARCH_AGENT === "gemini"
+                process.env.NAVARCH_AGENT === "gemini" ||
+                process.env.NAVARCH_AGENT === "opencode" ||
+                process.env.NAVARCH_AGENT === "acp"
                 ? process.env.NAVARCH_AGENT
                 : undefined,
         };

package/dist/session.cjs

@@ -67,7 +67,7 @@ async function runSession(deps, claimed, sessionId) {
                 ? "gpt-6-astra"
                 : runtime === "gemini"
                     ? "auto"
-                    : runtime === "opencode"
+                    : runtime === "opencode" || runtime === "acp"
                         ? "default"
                         : "claude-fable-5-1",
             reasoning_effort: "medium",
@@ -105,7 +105,7 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
             ? "gpt-6-astra"
             : runtime === "gemini"
                 ? "auto"
-                : runtime === "opencode"
+                : runtime === "opencode" || runtime === "acp"
                     ? "default"
                     : "claude-fable-5-1",
         reasoning_effort: "medium",
@@ -392,7 +392,9 @@ async function runClaimedSession(deps, claimed, sessionId, lifecycle) {
                 codexGuardArgs,
                 geminiSandboxMounts: geminiGuardMounts,
                 opencodeHostGuard: runtime === "opencode" && config.sandboxMode === "host" && config.worktreeGuard,
-                cwd: sandbox ? undefined : gitWorktree.worktreePath,
+                // ACP requires an absolute session cwd. Docker mounts the worktree at
+                // this same absolute path, while the other Docker adapters ignore cwd.
+                cwd: gitWorktree.worktreePath,
                 dockerExec: sandbox ? { containerName: sandbox.name, runner: sandbox_cjs_1.nodeCommandRunner } : undefined,
                 signal: activeAbortController.signal,
             });
@@ -616,6 +618,8 @@ function adapterCommand(config, runtime) {
             return { bin: config.geminiBin, extraArgs: config.geminiExtraArgs };
         case "opencode":
             return { bin: config.opencodeBin, extraArgs: config.opencodeExtraArgs };
+        case "acp":
+            return { bin: config.acpBin, extraArgs: config.acpExtraArgs };
     }
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.40",
-  "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, Gemini, or OpenCode.",
+  "version": "0.1.42",
+  "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,8 @@
     "codex",
     "gemini-cli",
     "opencode",
+    "agent-client-protocol",
+    "deepseek-harness",
     "task-runner"
   ],
   "bin": {
@@ -50,6 +52,7 @@
     "vitest": "^4.1.10"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^1.4.0",
     "typescript": "^5.7.2"
   }
 }