@ag-eco/agentplate-cli 0.13.3 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ag-eco/agentplate-cli",
-	"version": "0.13.3",
+	"version": "0.14.0",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/commands/coordinator.test.ts

@@ -682,6 +682,34 @@ describe("startCoordinator", () => {
 		expect(cmd).not.toContain("--model opus");
 	});
 
+	test("--runtime overrides the spawned runtime adapter (pi)", async () => {
+		const { deps, calls } = makeDeps();
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() =>
+				coordinatorCommand(["start", "--no-attach", "--json", "--runtime", "pi"], deps),
+			);
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		expect(calls.createSession).toHaveLength(1);
+		const cmd = calls.createSession[0]?.command ?? "";
+		// Pi's buildSpawnCommand emits `pi --model <provider/model>`; the default
+		// claude runtime would not. Proves --runtime took precedence over config.
+		expect(cmd).toContain("pi --model");
+		expect(cmd).toContain("opus");
+	});
+
+	test("--runtime rejects an unknown adapter with ValidationError", async () => {
+		const { deps } = makeDeps();
+		await expect(
+			coordinatorCommand(["start", "--no-attach", "--runtime", "bogus"], deps),
+		).rejects.toThrow(ValidationError);
+	});
+
 	test("--json outputs JSON with expected fields", async () => {
 		const { deps } = makeDeps();
 		const originalSleep = Bun.sleep;

package/src/commands/coordinator.ts

@@ -24,7 +24,7 @@ import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
-import { getRuntime } from "../runtimes/registry.ts";
+import { getRuntime, getRuntimeNames } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore, createSessionStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
@@ -332,6 +332,13 @@ export interface CoordinatorSessionOptions {
 	watchdog: boolean;
 	monitor: boolean;
 	profile?: string;
+	/**
+	 * Runtime adapter override (e.g. "claude", "codex", "pi", "opencode",
+	 * "gemini"). Takes precedence over config's per-capability and default
+	 * runtime. When omitted, resolution falls back to
+	 * runtime.capabilities[capability] → runtime.default → "claude".
+	 */
+	runtime?: string;
 	/** Override coordinator name (default: "coordinator"). */
 	coordinatorName?: string;
 	/** Generic persistent agent name override. Preferred over coordinatorName for new callers. */
@@ -386,6 +393,7 @@ export async function startCoordinatorSession(
 		watchdog: watchdogFlag,
 		monitor: monitorFlag,
 		profile: profileFlag,
+		runtime: runtimeOverride,
 		coordinatorName: coordinatorNameOpt,
 		agentName: agentNameOpt,
 		capability: capabilityOpt,
@@ -402,6 +410,16 @@ export async function startCoordinatorSession(
 	const displayName = displayNameOpt ?? COORDINATOR_SPEC.displayName;
 	const beaconBuilder = beaconBuilderOpt ?? buildCoordinatorBeacon;
 
+	// Fail fast on an unknown --runtime before doing any setup work, listing the
+	// valid adapters. getRuntime() would also reject it, but later and with a
+	// plain Error; this gives an immediate, typed, actionable message.
+	if (runtimeOverride && !getRuntimeNames().includes(runtimeOverride)) {
+		throw new ValidationError(
+			`Unknown runtime "${runtimeOverride}". Available: ${getRuntimeNames().join(", ")}`,
+			{ field: "runtime", value: runtimeOverride },
+		);
+	}
+
 	if (isRunningAsRoot()) {
 		throw new AgentError(
 			"Cannot spawn agents as root (UID 0). The claude CLI rejects --permission-mode bypassPermissions when run as root, causing the tmux session to die immediately. Run agentplate as a non-root user.",
@@ -478,7 +496,7 @@ export async function startCoordinatorSession(
 		);
 		const manifest = await manifestLoader.load();
 		const resolvedModel = resolveModel(config, manifest, capability, "opus");
-		const runtime = getRuntime(undefined, config, capability);
+		const runtime = getRuntime(runtimeOverride, config, capability);
 
 		// Deploy hooks to the project root so the coordinator gets event logging,
 		// mail check --inject, and activity tracking via the standard hook pipeline.
@@ -875,6 +893,7 @@ async function startPersistentAgent(
 		watchdog: boolean;
 		monitor: boolean;
 		profile?: string;
+		runtime?: string;
 		acceptExistingWatchdog?: boolean;
 	},
 	deps: CoordinatorDeps = {},
@@ -1645,7 +1664,7 @@ export function createPersistentAgentCommand(
 
 	cmd
 		.command("start")
-		.description(`Start the ${spec.commandName} (spawns Claude Code at project root)`)
+		.description(`Start the ${spec.commandName} (spawns the configured runtime at project root)`)
 		.option("--attach", "Always attach to tmux session after start")
 		.option("--no-attach", "Never attach to tmux session after start")
 		.option("--watchdog", `Auto-start watchdog daemon with ${spec.commandName}`)
@@ -1655,6 +1674,10 @@ export function createPersistentAgentCommand(
 		)
 		.option("--monitor", `Auto-start Tier 2 monitor agent with ${spec.commandName}`)
 		.option("--profile <name>", "Trellis profile to apply to spawned agents")
+		.option(
+			"--runtime <name>",
+			"Runtime adapter: claude | codex | pi | opencode | gemini (default: config or claude)",
+		)
 		.option("--json", "Output as JSON")
 		.action(
 			async (opts: {
@@ -1664,6 +1687,7 @@ export function createPersistentAgentCommand(
 				monitor?: boolean;
 				json?: boolean;
 				profile?: string;
+				runtime?: string;
 			}) => {
 				// opts.attach = true if --attach, false if --no-attach, undefined if neither
 				const shouldAttach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
@@ -1676,6 +1700,7 @@ export function createPersistentAgentCommand(
 						acceptExistingWatchdog: opts.acceptExistingWatchdog ?? false,
 						monitor: opts.monitor ?? false,
 						profile: opts.profile,
+						runtime: opts.runtime,
 					},
 					deps,
 				);

package/src/commands/init.ts

@@ -96,7 +96,11 @@ const SIBLING_TOOLS: SiblingTool[] = [
  * tool's entrypoint resolved inside this package. PATH-independent.
  */
 function toolArgv(tool: SiblingTool, ...cmd: string[]): string[] {
-	const entryPath = new URL(tool.entry, import.meta.url).pathname;
+	// Resolve via import.meta.dir (a decoded filesystem path) rather than
+	// `new URL(...).pathname`, which percent-encodes — a path like
+	// `/Users/Jane Doe/...` would become `/Users/Jane%20Doe/...` and fail to
+	// spawn, surfacing as a spurious "loam/sprout/trellis unavailable" error.
+	const entryPath = join(import.meta.dir, tool.entry);
 	return [process.execPath, entryPath, ...cmd];
 }
 

package/src/commands/serve.ts

@@ -139,13 +139,15 @@ export function resolveUiDistPath(
 ): string {
 	const projectDist = join(projectRoot, "ui", "dist");
 	if (_exists(projectDist)) return projectDist;
-	return new URL("../../ui/dist", import.meta.url).pathname;
+	// import.meta.dir is a decoded filesystem path; `new URL(...).pathname` would
+	// percent-encode spaces/special chars in the install path and 404 the SPA.
+	return join(import.meta.dir, "..", "..", "ui", "dist");
 }
 
 /** Read the package version once at module load to avoid circular imports with index.ts. */
 const _pkgVersion = (): string => {
 	try {
-		const raw = readFileSync(new URL("../../package.json", import.meta.url).pathname, "utf-8");
+		const raw = readFileSync(join(import.meta.dir, "..", "..", "package.json"), "utf-8");
 		return (JSON.parse(raw) as { version: string }).version;
 	} catch {
 		return "unknown";

package/src/runtimes/registry.test.ts

@@ -7,7 +7,7 @@ import { CursorRuntime } from "./cursor.ts";
 import { GeminiRuntime } from "./gemini.ts";
 import { OpenCodeRuntime } from "./opencode.ts";
 import { PiRuntime } from "./pi.ts";
-import { getRuntime } from "./registry.ts";
+import { getRuntime, getRuntimeNames } from "./registry.ts";
 
 describe("getRuntime", () => {
 	it("returns a ClaudeRuntime by default (no args)", () => {
@@ -194,3 +194,18 @@ describe("getRuntime", () => {
 		});
 	});
 });
+
+describe("getRuntimeNames", () => {
+	it("lists every registered adapter, including the coordinator-supported set", () => {
+		const names = getRuntimeNames();
+		for (const expected of ["claude", "codex", "pi", "opencode", "gemini"]) {
+			expect(names).toContain(expected);
+		}
+	});
+
+	it("returns names that all resolve via getRuntime", () => {
+		for (const name of getRuntimeNames()) {
+			expect(getRuntime(name).id).toBe(name);
+		}
+	});
+});

package/src/runtimes/registry.ts

@@ -55,6 +55,18 @@ export function getAllRuntimes(): AgentRuntime[] {
 	];
 }
 
+/**
+ * Names of all registered runtime adapters, in registration order.
+ *
+ * Used to validate a user-supplied `--runtime <name>` before resolution so the
+ * error can list the valid choices (see `ap coordinator start --runtime`).
+ *
+ * @returns Array of runtime names (e.g. "claude", "codex", "pi").
+ */
+export function getRuntimeNames(): string[] {
+	return [...runtimes.keys()];
+}
+
 /**
  * Resolve a runtime adapter by name.
  *

package/src/version.ts

@@ -2,4 +2,4 @@
  * Single source of truth for the package version, shared by every bundled bin
  * (ap/agentplate, lm/loam, sr, tl). Updated by scripts/version-bump.ts.
  */
-export const VERSION = "0.13.3";
+export const VERSION = "0.14.0";