@sagentlab/navarch-runtime 0.1.61 → 0.1.63

package/README.md

@@ -8,8 +8,9 @@ machine.
 
 The machine operator selects **Claude Code**, **OpenAI Codex**, **Google
 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.
+run any unpinned project task; task eligibility depends on capabilities and
+project gates. A task pinned to a runtime waits for a worker that advertises
+that adapter and runs on it — see "Choosing an agent" below.
 
 See [`docs/agent-platform-project-plan.md`](../docs/agent-platform-project-plan.md)
 §3.8/§3.9/§3.11 and [`docs/navarch/implementation-plan.md`](../docs/navarch/implementation-plan.md)
@@ -29,7 +30,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`, `opencode`, or `dsh` for the default ACP integration — and complete its normal authentication flow; and
+  `gemini`, `opencode`, `dsh` for the default ACP integration, or `qoder` — 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 +45,7 @@ node --version       # 20 or later
 npm --version
 npx --version
 git --version
-codex --version      # or: claude / gemini / opencode / dsh --version
+codex --version      # or: claude / gemini / opencode / qoder / dsh --version
 ```
 
 Every command above must succeed before the long-running worker starts. See
@@ -156,7 +157,7 @@ The from-source flow — `git clone` + `./install.sh` + `node bin/navarch.cjs
 | `connect --token <t> --name <n> [--agent claude-code\|codex\|gemini\|opencode\|acp\|qoder] [--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\|qoder]` | Runs the daemon. A start-time agent choice overrides the saved choice. |
 | `supervise [--agent claude-code\|codex\|gemini\|opencode\|acp\|qoder]` | Runs the daemon under the update supervisor, enabling drain-safe automatic updates and rollback. |
-| `doctor` | Prints resolved config + Docker/registration status; no side effects. |
+| `doctor [--agent claude-code\|codex\|gemini\|opencode\|acp\|qoder]` | Prints resolved config + Docker/registration status; no side effects. |
 
 ### Running multiple agents on one machine
 
@@ -369,7 +370,7 @@ unchanged across the deployment.
 | `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 adapter: `claude-code`, `codex`, `gemini`, `opencode`, `acp`, or `qoder`. Overrides the choice saved by `connect`/`register`; `start --agent` has highest priority. |
-| `NAVARCH_RUNTIMES` | resolved local agent choice | Comma list of installed/authenticated adapters advertised to dispatch. The control plane chooses among these per project/task. |
+| `NAVARCH_RUNTIMES` | resolved local agent choice | Comma list of installed/authenticated adapters advertised to dispatch. Unpinned tasks run on the preferred agent; a task runtime pin selects the matching adapter. Unrecognized ids are dropped with a warning that names them, so a typo cannot silently shrink the advertised set. |
 | `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`. |
 | `NAVARCH_CLAUDE_BIN` | `claude` | Path/name of the Claude Code CLI binary. |
@@ -530,8 +531,13 @@ export NAVARCH_RUNTIMES=claude-code,codex,gemini,opencode,acp,qoder
 For the legacy single-runtime setting, priority is `start --agent` →
 `NAVARCH_AGENT` → the locally saved choice → `claude-code`.
 `NAVARCH_RUNTIMES` expands what the worker advertises. For normal projects,
-the locally selected `NAVARCH_AGENT` handles every claimed task. Sandbox
-projects remain constrained to Claude Code.
+the locally selected `NAVARCH_AGENT` handles every unpinned task. A task with a
+runtime override (for example `gemini`) is claimed only by a worker that
+advertises that adapter, and the claim returns it as the session runtime.
+Sandbox projects remain constrained to Claude Code, so they claim only unpinned
+or `claude-code`-pinned tasks. List only adapters this worker can really run:
+in Docker mode that means CLIs installed in `NAVARCH_DOCKER_IMAGE`, otherwise
+pinned tasks for a missing adapter are claimed and then fail.
 
 All five BYO adapters implement the same `AgentAdapter` interface
 (`src/adapters/types.cts`) and run either directly on the host or via

package/dist/cli.cjs

@@ -20,6 +20,8 @@ const supervisor_cjs_1 = require("./supervisor.cjs");
 const worktree_janitor_cjs_1 = require("./worktree-janitor.cjs");
 const log = (0, logger_cjs_1.createLogger)("cli");
 const PACKAGE_NAME = "@sagentlab/navarch-runtime";
+/** Accepted `--agent` ids as usage metavariables, generated from one source of truth. */
+const AGENT_TYPE_USAGE = config_cjs_1.RUNTIME_AGENT_TYPES.join("|");
 /**
  * Exit code for "this machine's identity is gone". Deliberately outside the
  * supervisor's restart codes (75 update, 76 remote restart): respawning cannot
@@ -78,10 +80,32 @@ 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', 'opencode', 'acp', or 'qoder'.");
+        throw new Error(`--agent must be one of ${formatChoices(config_cjs_1.RUNTIME_AGENT_TYPES)}.`);
     }
     return value;
 }
+/** `'a', 'b', or 'c'` — one prose list for every place the accepted ids are shown. */
+function formatChoices(values) {
+    const quoted = values.map((value) => `'${value}'`);
+    const last = quoted.at(-1) ?? "";
+    if (quoted.length < 2)
+        return last;
+    return `${quoted.slice(0, -1).join(", ")}, or ${last}`;
+}
+/**
+ * A typo in NAVARCH_RUNTIMES must not silently shrink the advertised adapter
+ * set, so name every dropped id on stderr. Runs once per top-level command (not
+ * per config load) to avoid duplicate lines when start/supervise/doctor resolve
+ * the identity and reload config. A supervised worker inherits NAVARCH_RUNTIMES
+ * from the `supervise` parent that already warned, so it stays quiet.
+ */
+function warnUnknownRuntimes(config) {
+    const unknown = config.unknownRuntimes;
+    if (config.supervised || unknown.length === 0)
+        return;
+    log.warn(`NAVARCH_RUNTIMES ignores unrecognized adapter id(s): ${unknown.join(", ")}. ` +
+        `Known adapters: ${config_cjs_1.RUNTIME_AGENT_TYPES.join(", ")}.`);
+}
 /** Saved pins only apply to the adapter they were selected for. */
 function modelFromFlags(flags, agentType, identity) {
     const model = flags.model ?? (identity?.agent_type === agentType ? identity.model : undefined);
@@ -116,6 +140,7 @@ function parseArgs(argv) {
  */
 async function registerCommand(flags) {
     const config = configFromFlags(flags);
+    warnUnknownRuntimes(config);
     const apiBase = flags["api-base"] ?? config.apiBase;
     const enrollmentToken = flags.token ?? process.env.NAVARCH_ENROLLMENT_TOKEN;
     const name = flags.name ?? process.env.NAVARCH_MACHINE_NAME;
@@ -166,6 +191,7 @@ async function registerCommand(flags) {
  */
 async function connectCommand(flags) {
     const config = configFromFlags(flags);
+    warnUnknownRuntimes(config);
     const apiBase = flags["api-base"] ?? config.apiBase;
     const enrollmentToken = flags.token ?? process.env.NAVARCH_ENROLLMENT_TOKEN;
     const name = flags.name ?? process.env.NAVARCH_MACHINE_NAME;
@@ -209,6 +235,7 @@ async function startCommand(flags) {
     const baseConfig = configFromFlags(flags);
     const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(baseConfig.configDir, baseConfig.apiBase);
     const config = configFromFlags(flags, identity);
+    warnUnknownRuntimes(config);
     const api = new api_cjs_1.NavarchApiClient({ baseUrl: identity.api_base, token: identity.token });
     const capacity = new capacity_cjs_1.CapacityTracker(config.maxSessions);
     const runtimeShutdown = new AbortController();
@@ -287,6 +314,7 @@ async function superviseCommand(flags) {
     const baseConfig = configFromFlags(flags);
     const identity = await (0, machine_store_cjs_1.resolveMachineIdentity)(baseConfig.configDir, baseConfig.apiBase);
     const config = configFromFlags(flags, identity);
+    warnUnknownRuntimes(config);
     // Resolve and pin the adapter before spawning the worker. The supervisor
     // passes machine credentials through the environment, so the child no
     // longer reads machine.json for identity fields (including agent_type).
@@ -325,8 +353,15 @@ async function doctorCommand(flags) {
         }
         if (identity)
             config = configFromFlags(flags, identity);
+        warnUnknownRuntimes(config);
     }
     catch (err) {
+        // The typo may be why the config is unusable (e.g. `opencode,gemni` on a
+        // guarded host leaves only OpenCode), so still name it.
+        warnUnknownRuntimes({
+            supervised: process.env.NAVARCH_SUPERVISED === "1",
+            unknownRuntimes: (0, config_cjs_1.unknownRuntimeIds)(process.env),
+        });
         console.log(`config:          UNUSABLE — ${err instanceof Error ? err.message : String(err)}`);
         process.exitCode = 1;
         return;
@@ -353,12 +388,12 @@ function helpText() {
 
 Usage:
   navarch-runtime register --token <enrollment-token> --name <machine-name> \\
-      [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--model <model>] [--capabilities a,b] [--max-sessions N] [--owner-zone z] [--api-base url]
+      [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}] [--model <model>] [--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|acp] [--model <model>] [--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] [--model <model>]
-  navarch-runtime supervise [--config-dir <path>] [--agent claude-code|codex|gemini|opencode|acp] [--model <model>]
-  navarch-runtime doctor [--config-dir <path>]
+      [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}] [--model <model>] [--project <project-id>] [--capabilities a,b] [--max-sessions N] [--api-base url]
+  navarch-runtime start [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}] [--model <model>]
+  navarch-runtime supervise [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}] [--model <model>]
+  navarch-runtime doctor [--config-dir <path>] [--agent ${AGENT_TYPE_USAGE}]
   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.

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.OPENCODE_HOST_GUARD_MESSAGE = exports.DEFAULT_SANDBOX_IMAGE = void 0;
+exports.OPENCODE_HOST_GUARD_MESSAGE = exports.RUNTIME_AGENT_TYPES = exports.DEFAULT_SANDBOX_IMAGE = void 0;
 exports.isRuntimeAgentType = isRuntimeAgentType;
+exports.unknownRuntimeIds = unknownRuntimeIds;
 exports.opencodeBlockedOnHost = opencodeBlockedOnHost;
 exports.loadRuntimeConfig = loadRuntimeConfig;
 const node_path_1 = __importDefault(require("node:path"));
@@ -12,13 +13,26 @@ const node_os_1 = __importDefault(require("node:os"));
 const sandbox_profile_cjs_1 = require("./sandbox-profile.cjs");
 /** Published image containing git, GitHub CLI, and the pinned Claude Code CLI. */
 exports.DEFAULT_SANDBOX_IMAGE = "ghcr.io/sagentlab/navarch-sandbox-agent:0.1.0";
+/**
+ * Adapter ids the runtime accepts for `NAVARCH_AGENT` / `--agent`, in display
+ * order. `NAVARCH_RUNTIMES` is validated against this same list, and the CLI
+ * usage/error copy is generated from it so the advertised set cannot drift.
+ */
+exports.RUNTIME_AGENT_TYPES = [
+    "claude-code",
+    "codex",
+    "gemini",
+    "opencode",
+    "acp",
+    "qoder",
+];
 function isRuntimeAgentType(value) {
-    return (value === "claude-code" ||
-        value === "codex" ||
-        value === "gemini" ||
-        value === "opencode" ||
-        value === "acp" ||
-        value === "qoder");
+    return typeof value === "string" && exports.RUNTIME_AGENT_TYPES.includes(value);
+}
+/** Unrecognized ids in NAVARCH_RUNTIMES, deduplicated, in the order given. */
+function unknownRuntimeIds(env) {
+    const ids = envList(env, "NAVARCH_RUNTIMES", []);
+    return [...new Set(ids.filter((runtime) => !isRuntimeAgentType(runtime)))];
 }
 function envInt(env, name, fallback) {
     const raw = env[name];
@@ -82,7 +96,11 @@ function loadRuntimeConfig(env = process.env) {
     // 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);
+    const requestedRuntimeIds = envList(env, "NAVARCH_RUNTIMES", [requestedAgentType]);
+    // Keep unknown ids visible so a typo surfaces (CLI warns) instead of the
+    // machine quietly shrinking the adapters it advertises.
+    const unknownRuntimes = unknownRuntimeIds(env);
+    const requestedRuntimes = requestedRuntimeIds.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
@@ -114,6 +132,7 @@ function loadRuntimeConfig(env = process.env) {
         worktreeStaleAfterMs: envInt(env, "NAVARCH_WORKTREE_STALE_AFTER_MS", 24 * 60 * 60 * 1000),
         agentType,
         runtimes: runtimes.length > 0 ? runtimes : [agentType],
+        unknownRuntimes,
         claudeBin: env.NAVARCH_CLAUDE_BIN ?? "claude",
         claudeExtraArgs: envList(env, "NAVARCH_CLAUDE_EXTRA_ARGS", []),
         codexBin: env.NAVARCH_CODEX_BIN ?? "codex",

package/dist/machine-store.cjs

@@ -8,6 +8,7 @@ exports.loadMachineIdentity = loadMachineIdentity;
 exports.resolveMachineIdentity = resolveMachineIdentity;
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
+const config_cjs_1 = require("./config.cjs");
 function storePath(configDir) {
     return node_path_1.default.join(configDir, "machine.json");
 }
@@ -48,12 +49,10 @@ async function resolveMachineIdentity(configDir, apiBaseFallback) {
             token: envToken,
             name: process.env.NAVARCH_MACHINE_NAME ?? envId,
             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 === "opencode" ||
-                process.env.NAVARCH_AGENT === "acp" ||
-                process.env.NAVARCH_AGENT === "qoder"
+            // Validate against the one accepted adapter list so a new adapter cannot
+            // be added to `--agent`/NAVARCH_AGENT while this env-based identity path
+            // silently drops it.
+            agent_type: (0, config_cjs_1.isRuntimeAgentType)(process.env.NAVARCH_AGENT)
                 ? process.env.NAVARCH_AGENT
                 : undefined,
         };

package/package.json

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