@ag-eco/agentplate-cli 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ag-eco/agentplate-cli",
-	"version": "0.14.1",
+	"version": "0.15.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

@@ -738,13 +738,61 @@ describe("startCoordinator", () => {
 		expect(sessions[0]?.pid).toBe(4321);
 	});
 
-	test("--headless with a tmux-only runtime (pi) is rejected with ValidationError", async () => {
+	test("--headless with a tmux-only runtime (codex) is rejected with ValidationError", async () => {
 		const { deps } = makeDeps();
 		await expect(
-			coordinatorCommand(["start", "--no-attach", "--headless", "--runtime", "pi"], deps),
+			coordinatorCommand(["start", "--no-attach", "--headless", "--runtime", "codex"], deps),
 		).rejects.toThrow(ValidationError);
 	});
 
+	test("--headless --runtime pi spawns RPC mode and frames the prompt via the connection", async () => {
+		const { deps, calls } = makeDeps();
+		const stdinWrites: string[] = [];
+		const spawnArgvs: string[][] = [];
+		deps._spawnHeadless = async (argv) => {
+			spawnArgvs.push(argv);
+			return {
+				pid: 5678,
+				stdin: {
+					write: (d: string | Uint8Array) => {
+						stdinWrites.push(typeof d === "string" ? d : new TextDecoder().decode(d));
+						return 0;
+					},
+				},
+				// RPC path requires a piped stdout; an immediately-closing stream is enough
+				// for the fire-and-forget sendPrompt used at startup.
+				stdout: new ReadableStream<Uint8Array>({
+					start(c) {
+						c.close();
+					},
+				}),
+			};
+		};
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() =>
+				coordinatorCommand(
+					["start", "--no-attach", "--json", "--headless", "--runtime", "pi"],
+					deps,
+				),
+			);
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Headless RPC: spawned `pi --mode rpc`, never touched tmux.
+		expect(calls.createSession).toHaveLength(0);
+		expect(spawnArgvs[0]?.slice(0, 3)).toEqual(["pi", "--mode", "rpc"]);
+		// The prompt is delivered as a framed Pi command, not raw stdin text.
+		expect(stdinWrites.some((w) => w.includes('"type":"prompt"'))).toBe(true);
+		// Session recorded headless (no tmux pane) with the spawn pid.
+		const sessions = loadSessionsFromDb();
+		expect(sessions[0]?.tmuxSession).toBe("");
+		expect(sessions[0]?.pid).toBe(5678);
+	});
+
 	test("--json outputs JSON with expected fields", async () => {
 		const { deps } = makeDeps();
 		const originalSleep = Bun.sleep;

package/src/commands/coordinator.ts

@@ -24,6 +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 { setConnection } from "../runtimes/connections.ts";
 import { getHeadlessRuntimeNames, getRuntime, getRuntimeNames } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore, createSessionStore } from "../sessions/store.ts";
@@ -581,16 +582,8 @@ export async function startCoordinatorSession(
 			const headlessLogDir = join(agentplateDir, "logs", "coordinator", logTimestamp);
 			await mkdir(headlessLogDir, { recursive: true });
 
-			const headlessProc = await spawnHeadless(argv, {
-				cwd: projectRoot,
-				env: { ...(process.env as Record<string, string>), ...directEnv },
-				stdoutFile: join(headlessLogDir, "stdout.log"),
-				stderrFile: join(headlessLogDir, "stderr.log"),
-				agentName: coordinatorName,
-			});
-
-			// Build the initial stdin prompt from agent definition + pending dispatch
-			// mail + activation beacon. Replaces SessionStart hooks (no-op headless).
+			// Build the initial prompt from agent definition + pending dispatch mail +
+			// activation beacon. Replaces SessionStart hooks (no-op headless).
 			const agentDefPath = join(projectRoot, ".agentplate", "agent-defs", agentDefFile);
 			const agentDefHandle = Bun.file(agentDefPath);
 			const primeContext = (await agentDefHandle.exists()) ? await agentDefHandle.text() : "";
@@ -614,7 +607,46 @@ export async function startCoordinatorSession(
 				mailSection || undefined,
 				beacon,
 			);
-			await headlessProc.stdin.write(initialPrompt);
+
+			const spawnEnv = { ...(process.env as Record<string, string>), ...directEnv };
+			let headlessProc: Awaited<ReturnType<typeof spawnHeadless>>;
+			if (runtime.connect) {
+				// EXPERIMENTAL RPC runtime (e.g. Pi --mode rpc): stdout must be a pipe so
+				// the connection's reader can route get_state responses, and the prompt +
+				// mail are delivered as framed RPC commands rather than raw stdin text.
+				// We register the runtime's own connection instead of the generic
+				// stdin-writer (no agentName → spawnHeadless skips that registration).
+				// Trade-off: Pi event lines are not file-logged in this path yet.
+				headlessProc = await spawnHeadless(argv, {
+					cwd: projectRoot,
+					env: spawnEnv,
+					stderrFile: join(headlessLogDir, "stderr.log"),
+				});
+				if (!headlessProc.stdout) {
+					throw new AgentError(
+						`Runtime "${runtime.id}" needs a piped stdout for RPC mode but none was provided`,
+						{ agentName: coordinatorName },
+					);
+				}
+				const connection = runtime.connect({
+					stdin: headlessProc.stdin,
+					stdout: headlessProc.stdout,
+				});
+				setConnection(coordinatorName, connection);
+				await connection.sendPrompt(initialPrompt);
+			} else {
+				// Stream-json runtimes (Claude): the generic HeadlessClaudeConnection
+				// (registered by agentName) writes the prompt + mail as raw stdin text,
+				// and stdout is captured to a log file for `ap logs`.
+				headlessProc = await spawnHeadless(argv, {
+					cwd: projectRoot,
+					env: spawnEnv,
+					stdoutFile: join(headlessLogDir, "stdout.log"),
+					stderrFile: join(headlessLogDir, "stderr.log"),
+					agentName: coordinatorName,
+				});
+				await headlessProc.stdin.write(initialPrompt);
+			}
 
 			// Create run record + current-run.txt + session row.
 			const sessionId = `session-${Date.now()}-${coordinatorName}`;
@@ -1707,7 +1739,7 @@ export function createPersistentAgentCommand(
 		)
 		.option(
 			"--headless",
-			"Spawn without tmux (direct subprocess). Required on native Windows; runtime must be headless-capable (claude)",
+			"Spawn without tmux (direct subprocess). Required on native Windows; runtime must be headless-capable (claude, or pi via experimental --mode rpc)",
 		)
 		.option("--no-headless", "Force the tmux spawn path (overrides the Windows headless default)")
 		.option("--json", "Output as JSON")

package/src/runtimes/pi.test.ts

@@ -787,3 +787,84 @@ describe("PiRuntime integration: registry resolves 'pi'", () => {
 		expect(() => getRuntime("does-not-exist")).toThrow('Unknown runtime: "does-not-exist"');
 	});
 });
+
+describe("PiRuntime headless RPC: buildDirectSpawn", () => {
+	const runtime = new PiRuntime();
+
+	test("returns `pi --mode rpc` with no --model when model omitted", () => {
+		expect(runtime.buildDirectSpawn({ cwd: "/x", env: {}, instructionPath: "AGENTS.md" })).toEqual([
+			"pi",
+			"--mode",
+			"rpc",
+		]);
+	});
+
+	test("appends the expanded --model when provided", () => {
+		expect(
+			runtime.buildDirectSpawn({
+				cwd: "/x",
+				env: {},
+				model: "opus",
+				instructionPath: "AGENTS.md",
+			}),
+		).toEqual(["pi", "--mode", "rpc", "--model", "anthropic/claude-opus-4-6"]);
+	});
+});
+
+describe("PiRuntime headless RPC: connect() command framing", () => {
+	const runtime = new PiRuntime();
+
+	function fakeProc(emit?: string): {
+		proc: { stdin: { write(d: string | Uint8Array): number }; stdout: ReadableStream<Uint8Array> };
+		writes: string[];
+	} {
+		const writes: string[] = [];
+		const stdout = new ReadableStream<Uint8Array>({
+			start(c) {
+				if (emit) c.enqueue(new TextEncoder().encode(emit));
+				c.close();
+			},
+		});
+		const stdin = {
+			write: (d: string | Uint8Array): number => {
+				writes.push(typeof d === "string" ? d : new TextDecoder().decode(d));
+				return 0;
+			},
+		};
+		return { proc: { stdin, stdout }, writes };
+	}
+
+	test("sendPrompt frames a `prompt` command", async () => {
+		const { proc, writes } = fakeProc();
+		const conn = runtime.connect(proc);
+		await conn.sendPrompt("hello");
+		conn.close();
+		expect(writes).toContain('{"type":"prompt","message":"hello"}\n');
+	});
+
+	test("followUp frames a `follow_up` command", async () => {
+		const { proc, writes } = fakeProc();
+		const conn = runtime.connect(proc);
+		await conn.followUp("more work");
+		conn.close();
+		expect(writes).toContain('{"type":"follow_up","message":"more work"}\n');
+	});
+
+	test("abort frames an `abort` command", async () => {
+		const { proc, writes } = fakeProc();
+		const conn = runtime.connect(proc);
+		await conn.abort();
+		conn.close();
+		expect(writes).toContain('{"type":"abort"}\n');
+	});
+
+	test("getState maps an isStreaming response to working", async () => {
+		const { proc } = fakeProc(
+			'{"type":"response","id":0,"command":"get_state","data":{"isStreaming":true}}\n',
+		);
+		const conn = runtime.connect(proc);
+		const state = await conn.getState();
+		expect(state.status).toBe("working");
+		conn.close();
+	});
+});

package/src/runtimes/pi.ts

@@ -7,9 +7,13 @@ import type { PiRuntimeConfig, ResolvedModel } from "../types.ts";
 import { generatePiGuardExtension } from "./pi-guards.ts";
 import type {
 	AgentRuntime,
+	ConnectionState,
+	DirectSpawnOpts,
 	HooksDef,
 	OverlayContent,
 	ReadyState,
+	RpcProcessHandle,
+	RuntimeConnection,
 	SpawnOpts,
 	TranscriptSummary,
 } from "./types.ts";
@@ -24,12 +28,174 @@ const DEFAULT_PI_CONFIG: PiRuntimeConfig = {
 	},
 };
 
+/** Pending get_state request awaiting its NDJSON response. */
+interface PiPendingRequest {
+	resolve: (state: ConnectionState) => void;
+	reject: (err: Error) => void;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * RPC connection to a running `pi --mode rpc` process.
+ *
+ * Pi's RPC mode is a long-lived loop that reads newline-delimited JSON commands
+ * on stdin and emits NDJSON events + responses on stdout (see Pi's
+ * `src/modes/rpc/rpc-mode.ts`). This maps the agentplate RuntimeConnection
+ * contract onto Pi's command vocabulary:
+ *
+ * - sendPrompt → `{ type: "prompt", message }`
+ * - followUp   → `{ type: "follow_up", message }`
+ * - abort      → `{ type: "abort" }`
+ * - getState   → `{ type: "get_state", id }` → `{ type: "response", id, data }`
+ *
+ * A background reader drains stdout, routing `type: "response"` lines with a
+ * matching numeric `id` to pending getState() waiters and discarding the
+ * agent event stream (observability for Pi events is a follow-up).
+ *
+ * EXPERIMENTAL: validated against Pi's documented RPC protocol but not yet
+ * exercised end-to-end. Not exported — constructed only by PiRuntime.connect().
+ */
+class PiConnection implements RuntimeConnection {
+	private nextId = 0;
+	private readonly pending = new Map<number, PiPendingRequest>();
+	private closed = false;
+	private readonly proc: RpcProcessHandle;
+	private readonly timeoutMs: number;
+
+	constructor(proc: RpcProcessHandle, timeoutMs = 5000) {
+		this.proc = proc;
+		this.timeoutMs = timeoutMs;
+		this.drainStdout();
+	}
+
+	/** Background reader: route `type:"response"` lines to pending getState waiters. */
+	private drainStdout(): void {
+		const reader = this.proc.stdout.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+
+		const processLine = (line: string): void => {
+			const trimmed = line.trim();
+			if (!trimmed) return;
+			let parsed: Record<string, unknown>;
+			try {
+				parsed = JSON.parse(trimmed) as Record<string, unknown>;
+			} catch {
+				return; // partial write or non-JSON debug line
+			}
+			// Pi responses: { type: "response", id, command, success, data }
+			if (parsed.type === "response" && typeof parsed.id === "number") {
+				const waiter = this.pending.get(parsed.id);
+				if (waiter) {
+					clearTimeout(waiter.timer);
+					this.pending.delete(parsed.id);
+					waiter.resolve(mapPiState(parsed.data));
+				}
+			}
+			// Agent event lines are discarded here (Pi event observability is TODO).
+		};
+
+		const read = async (): Promise<void> => {
+			try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					buffer += decoder.decode(value, { stream: true });
+					const lines = buffer.split("\n");
+					buffer = lines.pop() ?? "";
+					for (const line of lines) processLine(line);
+				}
+				if (buffer.trim()) processLine(buffer);
+			} catch {
+				// stream error — reject all pending below
+			} finally {
+				reader.releaseLock();
+				for (const [, waiter] of this.pending) {
+					clearTimeout(waiter.timer);
+					waiter.reject(new Error("connection closed"));
+				}
+				this.pending.clear();
+			}
+		};
+
+		read().catch(() => {
+			// handled in finally
+		});
+	}
+
+	/** Write one NDJSON command line to stdin (fire-and-forget). */
+	private writeMsg(msg: Record<string, unknown>): void {
+		const result = this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
+		if (result instanceof Promise) {
+			result.catch(() => {
+				// non-fatal for fire-and-forget control messages
+			});
+		}
+	}
+
+	async sendPrompt(text: string): Promise<void> {
+		this.writeMsg({ type: "prompt", message: text });
+	}
+
+	async followUp(text: string): Promise<void> {
+		this.writeMsg({ type: "follow_up", message: text });
+	}
+
+	async abort(): Promise<void> {
+		this.writeMsg({ type: "abort" });
+	}
+
+	getState(): Promise<ConnectionState> {
+		if (this.closed) return Promise.reject(new Error("connection closed"));
+		const id = this.nextId++;
+		return new Promise<ConnectionState>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error("getState timed out"));
+			}, this.timeoutMs);
+			this.pending.set(id, { resolve, reject, timer });
+			const result = this.proc.stdin.write(`${JSON.stringify({ type: "get_state", id })}\n`);
+			if (result instanceof Promise) {
+				result.catch(() => {
+					clearTimeout(timer);
+					this.pending.delete(id);
+					reject(new Error("write failed"));
+				});
+			}
+		});
+	}
+
+	close(): void {
+		this.closed = true;
+		for (const [, waiter] of this.pending) {
+			clearTimeout(waiter.timer);
+			waiter.reject(new Error("connection closed"));
+		}
+		this.pending.clear();
+	}
+}
+
+/**
+ * Map a Pi get_state response payload to the agentplate ConnectionState.
+ * Pi reports `isStreaming` (a turn is in flight); everything else is idle.
+ */
+function mapPiState(data: unknown): ConnectionState {
+	const streaming =
+		typeof data === "object" && data !== null && (data as { isStreaming?: unknown }).isStreaming;
+	return { status: streaming ? "working" : "idle" };
+}
+
 /**
  * Pi runtime adapter.
  *
  * Implements AgentRuntime for the `pi` CLI (Mario Zechner's Pi coding agent).
  * Security is enforced via Pi guard extensions rather than permission-mode flags —
  * Pi has no --permission-mode equivalent.
+ *
+ * Pi runs in two modes here: an interactive TUI in a tmux pane
+ * (buildSpawnCommand) and a headless `--mode rpc` subprocess (buildDirectSpawn +
+ * connect) for tmux-less hosts such as native Windows. The RPC path is
+ * experimental.
  */
 export class PiRuntime implements AgentRuntime {
 	/** Unique identifier for this runtime. */
@@ -111,6 +277,42 @@ export class PiRuntime implements AgentRuntime {
 		return cmd;
 	}
 
+	/**
+	 * Build the argv for a long-lived headless Pi process in RPC mode.
+	 *
+	 * `pi --mode rpc` reads newline-delimited JSON commands on stdin and emits
+	 * NDJSON events/responses on stdout, staying alive across turns — the shape a
+	 * tmux-less coordinator needs (e.g. native Windows). Pi reads its task from
+	 * AGENTS.md (instructionPath) in the cwd; prompts/mail are delivered as RPC
+	 * commands via connect(), not argv.
+	 *
+	 * EXPERIMENTAL: the RPC headless path is not yet validated end-to-end.
+	 *
+	 * @param opts - Direct spawn options (cwd, env, model handled by the caller)
+	 * @returns Argv array for Bun.spawn — do not shell-interpolate
+	 */
+	buildDirectSpawn(opts: DirectSpawnOpts): string[] {
+		const argv = ["pi", "--mode", "rpc"];
+		if (opts.model !== undefined) {
+			argv.push("--model", this.expandModel(opts.model));
+		}
+		return argv;
+	}
+
+	/**
+	 * Establish a JSON-command RPC connection to a running `pi --mode rpc` process.
+	 *
+	 * Returns a PiConnection that frames sendPrompt/followUp/abort as NDJSON
+	 * commands on stdin and routes get_state responses from stdout. Used by the
+	 * headless coordinator path in place of tmux send-keys.
+	 *
+	 * @param process - Stdin/stdout handles from the spawned Pi subprocess
+	 * @returns RuntimeConnection for framed control + health checks
+	 */
+	connect(process: RpcProcessHandle): RuntimeConnection {
+		return new PiConnection(process);
+	}
+
 	/**
 	 * Deploy per-agent instructions and guards to a worktree.
 	 *

package/src/runtimes/registry.test.ts

@@ -211,14 +211,16 @@ describe("getRuntimeNames", () => {
 });
 
 describe("getHeadlessRuntimeNames", () => {
-	it("includes claude (buildDirectSpawn) and sapling (static headless)", () => {
+	it("includes claude (buildDirectSpawn), sapling (static headless), and pi (rpc)", () => {
 		const names = getHeadlessRuntimeNames();
 		expect(names).toContain("claude");
 		expect(names).toContain("sapling");
+		// Pi gained a headless RPC path (buildDirectSpawn + connect via `pi --mode rpc`).
+		expect(names).toContain("pi");
 	});
 
-	it("excludes tmux-only runtimes like pi", () => {
-		expect(getHeadlessRuntimeNames()).not.toContain("pi");
+	it("excludes tmux-only runtimes like codex", () => {
+		expect(getHeadlessRuntimeNames()).not.toContain("codex");
 	});
 
 	it("every headless name actually resolves to a headless-capable runtime", () => {

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.14.1";
+export const VERSION = "0.15.0";