@sagentlab/navarch-runtime 0.1.39 → 0.1.41

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
@@ -716,3 +738,26 @@ not match, making it a clean, zero-touch way to keep this package fully
 isolated. Vite/Vitest's default esbuild transform filter also excludes
 `.cts` by default — `vitest.config.cts` overrides it (`esbuild.include`) so
 tests are actually type-stripped and run.
+
+## Inspect code dependencies
+
+`navarch-runtime code-graph --query saveInvoice --mode impact --commit HEAD`
+returns JSON with the indexed commit, checkout HEAD, dirty-worktree warning,
+source paths and line numbers, and bounded dependency edges. Modes are `search`,
+`callers`, `callees`, and `impact`; impact accepts `--depth 1` through `5`.
+Use an exact node ID to disambiguate duplicate symbol names. A file query includes
+its functions and file import dependencies. `--repo` defaults to the current
+working directory. The CLI works without a Navarch login or network access.
+
+This first implementation analyzes committed JavaScript and TypeScript with the
+TypeScript compiler. It resolves static imports and named functions/methods,
+including imported aliases. It does not execute repository code, follow symlinks,
+load tsconfig plugins, or upload source. Root tsconfig path aliases are supported;
+extended configs, dynamic dispatch, external dependencies and other languages
+are not fully resolved. Warnings report omissions. No graph is an assurance that
+a change has no other effects: inspect the actual diff and run relevant tests.
+
+Each invocation rebuilds from Git blobs at the requested commit, avoiding stale
+persistent indexes. Bounds are 2,000 files, 10 MB total source, 500 KB per file,
+100 returned nodes and 300 edges. A later persistent index can optimize large
+repositories without changing the query format.

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/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;
 }
@@ -301,12 +301,13 @@ 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>]
 
 Use a different --config-dir (or NAVARCH_CONFIG_DIR) for every agent instance.
 Other configuration is via NAVARCH_* environment variables; see runtime/README.md.
@@ -328,6 +329,11 @@ async function main(argv = process.argv.slice(2)) {
             case "supervise":
                 await superviseCommand(flags);
                 break;
+            case "code-graph": {
+                const { codeGraphCommand } = await import("./code-graph.cjs");
+                console.log(JSON.stringify(codeGraphCommand(flags), null, 2));
+                break;
+            }
             case "doctor":
                 await doctorCommand(flags);
                 break;

package/dist/code-graph.cjs

@@ -0,0 +1,198 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCodeSnapshot = readCodeSnapshot;
+exports.buildCodeGraph = buildCodeGraph;
+exports.queryCodeGraph = queryCodeGraph;
+exports.codeGraphCommand = codeGraphCommand;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const typescript_1 = __importDefault(require("typescript"));
+const ROOT = "/navarch-repo/";
+const MAX_BYTES = 10_000_000;
+const MAX_FILES = 2_000;
+/** Reads committed blobs only. Never follows worktree symlinks, runs project code, or loads plugins. */
+function readCodeSnapshot(cwd, ref = "HEAD") {
+    const git = (args, input) => (0, node_child_process_1.execFileSync)("git", args, {
+        cwd, input, encoding: "utf8", maxBuffer: 16_000_000, timeout: 15_000,
+    });
+    const commit = git(["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]).trim();
+    const head = git(["rev-parse", "HEAD"]).trim();
+    const dirty = Boolean(git(["status", "--porcelain", "--untracked-files=no"]).trim());
+    const warnings = [];
+    if (dirty)
+        warnings.push("Tracked worktree edits are not indexed; this graph describes committed code.");
+    if (commit !== head)
+        warnings.push("Indexed commit differs from checkout HEAD.");
+    const files = [];
+    let bytes = 0;
+    for (const entry of git(["ls-tree", "--full-tree", "-rlz", commit]).split("\0")) {
+        const match = /^(100644|100755) blob ([a-f0-9]+) +([0-9]+)\t(.+)$/s.exec(entry);
+        if (!match)
+            continue;
+        const file = match[4];
+        if ((!/\.(?:[cm]?[jt]sx?)$/.test(file) && file !== "tsconfig.json") ||
+            /(^|\/)(node_modules|dist|build|vendor|\.next)\//.test(file))
+            continue;
+        const size = Number(match[3]);
+        if (/[\r\n]/.test(file) || size > 500_000 || files.length >= MAX_FILES || bytes + size > MAX_BYTES) {
+            warnings.push(`Skipped source: ${file}`);
+            continue;
+        }
+        files.push({ file, sha: match[2], size });
+        bytes += size;
+    }
+    const contents = {};
+    if (files.length) {
+        // Object IDs, rather than paths, form the batch protocol input.
+        const output = (0, node_child_process_1.execFileSync)("git", ["cat-file", "--batch"], {
+            cwd, input: files.map((f) => f.sha).join("\n") + "\n", maxBuffer: 16_000_000, timeout: 15_000,
+        });
+        let offset = 0;
+        for (const file of files) {
+            const end = output.indexOf(10, offset);
+            if (end < 0 || output.subarray(offset, end).toString() !== `${file.sha} blob ${file.size}`) {
+                throw new Error("Invalid git object batch");
+            }
+            offset = end + 1;
+            contents[file.file] = output.subarray(offset, offset + file.size).toString("utf8");
+            offset += file.size + 1;
+        }
+    }
+    return { commit, head, dirty, contents, warnings };
+}
+function buildCodeGraph(snapshot) {
+    const warnings = [...snapshot.warnings];
+    const sources = new Map(Object.entries(snapshot.contents).map(([file, text]) => [ROOT + file, text]));
+    const config = sources.get(ROOT + "tsconfig.json");
+    const raw = config ? typescript_1.default.parseConfigFileTextToJson("tsconfig.json", config) : { config: {} };
+    if (raw.error)
+        warnings.push("Could not parse tsconfig.json; using default module resolution.");
+    if (raw.config?.extends)
+        warnings.push("Inherited tsconfig options are not loaded; unresolved aliases may be omitted.");
+    const converted = typescript_1.default.convertCompilerOptionsFromJson(raw.config?.compilerOptions ?? {}, ROOT);
+    const options = { ...converted.options, allowJs: true, noLib: true, noEmit: true };
+    const canonical = (file) => node_path_1.default.posix.normalize(file);
+    const host = {
+        fileExists: (file) => sources.has(canonical(file)),
+        readFile: (file) => sources.get(canonical(file)),
+        getSourceFile: (file, languageVersion) => {
+            const text = sources.get(canonical(file));
+            return text === undefined ? undefined : typescript_1.default.createSourceFile(file, text, languageVersion, true);
+        },
+        getDefaultLibFileName: () => "", writeFile: () => { }, getCurrentDirectory: () => ROOT,
+        getDirectories: () => [], directoryExists: (dir) => [...sources.keys()].some((f) => f.startsWith(dir.replace(/\/$/, "") + "/")),
+        getCanonicalFileName: canonical, useCaseSensitiveFileNames: () => true, getNewLine: () => "\n",
+    };
+    const program = typescript_1.default.createProgram([...sources.keys()].filter((f) => f !== ROOT + "tsconfig.json"), options, host);
+    const checker = program.getTypeChecker();
+    const nodes = [];
+    const declarations = new Map();
+    const ownedFunctions = new Map();
+    const sourceFiles = program.getSourceFiles().filter((f) => sources.has(f.fileName));
+    for (const source of sourceFiles) {
+        const file = source.fileName.slice(ROOT.length);
+        const fileId = `file:${file}`;
+        nodes.push({ id: fileId, name: file, file, line: 1, kind: "file" });
+        declarations.set(source, fileId);
+        const collect = (node) => {
+            let name;
+            let body;
+            if (typescript_1.default.isFunctionDeclaration(node) || typescript_1.default.isMethodDeclaration(node) || typescript_1.default.isGetAccessorDeclaration(node) || typescript_1.default.isSetAccessorDeclaration(node)) {
+                name = node.name;
+                body = node.body;
+            }
+            else if (typescript_1.default.isVariableDeclaration(node) && node.initializer &&
+                (typescript_1.default.isArrowFunction(node.initializer) || typescript_1.default.isFunctionExpression(node.initializer))) {
+                name = node.name;
+                body = node.initializer;
+            }
+            if (name && body) {
+                const position = source.getLineAndCharacterOfPosition(name.getStart(source));
+                const line = position.line + 1;
+                const id = `${file}:${line}:${position.character + 1}:${name.getText(source)}`;
+                nodes.push({ id, name: name.getText(source), file, line, kind: "function" });
+                declarations.set(node, id);
+                ownedFunctions.set(body, id);
+            }
+            typescript_1.default.forEachChild(node, collect);
+        };
+        collect(source);
+    }
+    const edges = [];
+    let unresolved = 0;
+    const target = (node) => {
+        let symbol = checker.getSymbolAtLocation(node);
+        if (symbol && symbol.flags & typescript_1.default.SymbolFlags.Alias)
+            symbol = checker.getAliasedSymbol(symbol);
+        const targets = new Set(symbol?.declarations?.map((d) => declarations.get(d)).filter((id) => Boolean(id)));
+        return targets.size === 1 ? [...targets][0] : undefined;
+    };
+    for (const source of sourceFiles) {
+        const visit = (node, parent) => {
+            const owner = ownedFunctions.get(node) ?? parent;
+            if (typescript_1.default.isCallExpression(node)) {
+                const expression = typescript_1.default.isPropertyAccessExpression(node.expression) ? node.expression.name : node.expression;
+                const to = target(expression);
+                if (to)
+                    edges.push({ from: owner, to, kind: "call" });
+                else
+                    unresolved++;
+            }
+            if (typescript_1.default.isImportDeclaration(node) || (typescript_1.default.isExportDeclaration(node) && node.moduleSpecifier)) {
+                const to = node.moduleSpecifier ? target(node.moduleSpecifier) : undefined;
+                if (to)
+                    edges.push({ from: declarations.get(source), to, kind: "import" });
+            }
+            typescript_1.default.forEachChild(node, (child) => visit(child, owner));
+        };
+        visit(source, declarations.get(source));
+    }
+    warnings.push(`Static JS/TS analysis only; ${unresolved} external or unresolved calls omitted. Dynamic dispatch and runtime dependencies may be missing.`);
+    return { commit: snapshot.commit, head: snapshot.head, dirty: snapshot.dirty, nodes,
+        edges: [...new Map(edges.map((e) => [`${e.from}\0${e.to}\0${e.kind}`, e])).values()], warnings };
+}
+function queryCodeGraph(graph, query, mode = "search", depth = 3) {
+    if (!query.trim() || query.length > 500)
+        throw new Error("Provide a non-empty --query of at most 500 characters");
+    if (!["search", "callers", "callees", "impact"].includes(mode))
+        throw new Error("--mode must be search, callers, callees, or impact");
+    if (!Number.isInteger(depth) || depth < 1 || depth > 5)
+        throw new Error("--depth must be 1 through 5");
+    const exact = graph.nodes.filter((n) => n.id === query || n.name === query || n.file === query);
+    const matches = exact.length ? exact : graph.nodes.filter((n) => n.name.toLowerCase().includes(query.toLowerCase()));
+    const selected = new Set(matches.slice(0, 100).map((n) => n.id));
+    const paths = [];
+    let truncated = matches.length > 100;
+    if (mode !== "search") {
+        for (let hop = 0; hop < (mode === "impact" ? depth : 1); hop++) {
+            const frontier = new Set(selected);
+            for (const edge of graph.edges) {
+                const from = mode === "callees" ? edge.from : edge.to;
+                const to = mode === "callees" ? edge.to : edge.from;
+                if (!frontier.has(from))
+                    continue;
+                if (!selected.has(to) && selected.size >= 100) {
+                    truncated = true;
+                    continue;
+                }
+                if (paths.length >= 300) {
+                    truncated = true;
+                    break;
+                }
+                selected.add(to);
+                if (!paths.some((p) => p.from === edge.from && p.to === edge.to && p.kind === edge.kind))
+                    paths.push(edge);
+            }
+        }
+    }
+    return { commit: graph.commit, checkout_head: graph.head, dirty: graph.dirty, mode,
+        nodes: graph.nodes.filter((n) => selected.has(n.id)), edges: paths,
+        truncated, warnings: graph.warnings };
+}
+function codeGraphCommand(flags) {
+    const graph = buildCodeGraph(readCodeSnapshot(flags.repo ?? process.cwd(), flags.commit ?? "HEAD"));
+    return queryCodeGraph(graph, flags.query ?? "", flags.mode ?? "search", Number(flags.depth ?? 3));
+}

package/dist/config.cjs

@@ -15,7 +15,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];
@@ -83,6 +84,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,

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/prompt.cjs

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderPrompt = renderPrompt;
 exports.renderGuidanceCorrectionPrompt = renderGuidanceCorrectionPrompt;
+const CODE_GRAPH_GUIDANCE = "For JS/TS dependency inspection, the runtime provides `navarch-runtime code-graph --query <symbol-or-file> --mode search|callers|callees|impact --commit HEAD`. If the runtime is not on PATH, use its installed entry point; do not install another copy mid-task. Results describe committed source and include commit/freshness warnings; inspect current files for uncommitted changes and unresolved dependencies.";
 /**
  * Renders the four-layer context bundle (project-plan.md §3.8: steering docs,
  * task itself, task-type playbook, depends_on reports) into the single prompt
@@ -14,7 +15,7 @@ function renderPrompt(task, bundle) {
         const repositoryContext = bundle.repository
             ? `Repository: ${bundle.repository.full_name} (${bundle.repository.url})\nLocal checkout: this session's isolated git worktree (current working directory).`
             : null;
-        return [repositoryContext, bundle.task_context.trim(), bundle.retry_context?.trim()]
+        return [repositoryContext, bundle.task_context.trim(), CODE_GRAPH_GUIDANCE, bundle.retry_context?.trim()]
             .filter((section) => Boolean(section))
             .join("\n\n") + "\n";
     }
@@ -42,6 +43,7 @@ function renderPrompt(task, bundle) {
     }
     sections.push("## Playbook");
     sections.push(bundle.playbook);
+    sections.push(CODE_GRAPH_GUIDANCE);
     return sections.join("\n\n");
 }
 /**

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.39",
-  "description": "Navarch machine-side session manager: claims delivery tasks and runs them through Claude Code, Codex, Gemini, or OpenCode.",
+  "version": "0.1.41",
+  "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": {
@@ -47,7 +49,10 @@
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
-    "typescript": "^5.7.2",
     "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.4.0",
+    "typescript": "^5.7.2"
   }
 }