@ag-eco/agentplate-cli 0.13.0

package/src/runtimes/codex.ts

@@ -0,0 +1,273 @@
+// Codex runtime adapter for agentplate's AgentRuntime interface.
+// Implements the AgentRuntime contract for the OpenAI `codex` CLI.
+//
+// Key differences from Claude/Pi adapters:
+// - Interactive: `codex` (without `exec`) stays alive in tmux for orchestration
+// - Instruction file: AGENTS.md (not .claude/CLAUDE.md)
+// - No hooks: Codex uses OS-level sandbox (Seatbelt/Landlock)
+// - One-shot calls still use `codex exec` (buildPrintCommand)
+
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ResolvedModel } from "../types.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/**
+ * Codex runtime adapter.
+ *
+ * Implements AgentRuntime for the OpenAI `codex` CLI. Tmux-spawned Codex
+ * agents run in interactive mode (`codex`) so sessions stay alive and can be
+ * nudged via tmux.
+ *
+ * Security is enforced via Codex's OS-level sandbox (Seatbelt on macOS,
+ * Landlock on Linux) rather than hook-based guards. The `--full-auto` flag
+ * enables `workspace-write` sandbox + automatic approvals.
+ *
+ * Instructions are delivered via `AGENTS.md` (Codex's native convention),
+ * not `.claude/CLAUDE.md`.
+ */
+export class CodexRuntime implements AgentRuntime {
+	/** Unique identifier for this runtime. */
+	readonly id = "codex";
+
+	/** Stability level. Codex adapter is experimental — not fully validated. */
+	readonly stability = "experimental" as const;
+
+	/** Relative path to the instruction file within a worktree. */
+	readonly instructionPath = "AGENTS.md";
+
+	/**
+	 * Anthropic aliases used by agentplate manifests that Codex CLI does not
+	 * accept as --model values.
+	 */
+	private static readonly MANIFEST_ALIASES = new Set(["sonnet", "opus", "haiku"]);
+
+	/**
+	 * Strip a provider prefix from a model ID.
+	 *
+	 * Codex CLI expects bare model names. The orchestrator may resolve a model to
+	 * a provider-qualified form (e.g. `"openai/gpt-5.4"`) — strip the `"openai/"`
+	 * prefix before passing to the CLI.
+	 *
+	 * @param model - Possibly provider-qualified model ID
+	 * @returns Bare model name (everything after the first `/`, or unchanged if no `/`)
+	 */
+	private static stripProviderPrefix(model: string): string {
+		const slashIdx = model.indexOf("/");
+		return slashIdx !== -1 ? model.slice(slashIdx + 1) : model;
+	}
+
+	/**
+	 * Escape a directory path for use in a single-quoted shell argument.
+	 *
+	 * @param path - Absolute directory path
+	 * @returns POSIX shell-safe path string
+	 */
+	private static shellEscape(path: string): string {
+		return path.replace(/'/g, "'\\''");
+	}
+
+	/**
+	 * Build the shell command string to spawn a Codex agent in a tmux pane.
+	 *
+	 * Uses interactive `codex` with `--full-auto` for workspace-write sandbox +
+	 * automatic approvals.
+	 *
+	 * The prompt directs the agent to read AGENTS.md for its full instructions.
+	 * If `appendSystemPrompt` or `appendSystemPromptFile` is provided, the
+	 * content is prepended to the prompt (Codex has no --append-system-prompt
+	 * flag — all context goes through the exec prompt or AGENTS.md).
+	 *
+	 * @param opts - Spawn options (model, appendSystemPrompt; permissionMode is accepted but
+	 *   not mapped — Codex enforces security via OS sandbox, not permission flags)
+	 * @returns Shell command string suitable for tmux new-session -c
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		// Strip provider prefix before alias check and model flag injection.
+		// Codex CLI expects bare model names (e.g. "gpt-5.4", not "openai/gpt-5.4").
+		const bareModel = CodexRuntime.stripProviderPrefix(opts.model);
+		// When model comes from default manifest aliases (sonnet/opus/haiku),
+		// omit --model so Codex uses the user's configured default model.
+		let cmd = "codex --full-auto";
+		if (!CodexRuntime.MANIFEST_ALIASES.has(bareModel)) {
+			cmd += ` --model ${bareModel}`;
+		}
+		for (const dir of opts.sharedWritableDirs ?? []) {
+			cmd += ` --add-dir '${CodexRuntime.shellEscape(dir)}'`;
+		}
+
+		if (opts.appendSystemPromptFile) {
+			// Read role definition from file at shell expansion time — avoids tmux
+			// IPC message size limits. Append the "read AGENTS.md" instruction.
+			const escaped = CodexRuntime.shellEscape(opts.appendSystemPromptFile);
+			cmd += ` "$(cat '${escaped}')"' Read AGENTS.md for your task assignment and begin immediately.'`;
+		} else if (opts.appendSystemPrompt) {
+			// Inline role definition + instruction to read AGENTS.md.
+			const prompt = `${opts.appendSystemPrompt}\n\nRead AGENTS.md for your task assignment and begin immediately.`;
+			const escaped = CodexRuntime.shellEscape(prompt);
+			cmd += ` '${escaped}'`;
+		} else {
+			cmd += ` 'Read AGENTS.md for your task assignment and begin immediately.'`;
+		}
+
+		return cmd;
+	}
+
+	/**
+	 * Build the argv array for a headless one-shot Codex invocation.
+	 *
+	 * Returns an argv array suitable for `Bun.spawn()`. Uses `codex exec`
+	 * with `--full-auto` and `--ephemeral` (no session persistence).
+	 * Without `--json`, stdout contains the plain text final message.
+	 *
+	 * Used by merge/resolver.ts (AI-assisted conflict resolution) and
+	 * watchdog/triage.ts (AI-assisted failure classification).
+	 *
+	 * @param prompt - The prompt to pass as the exec argument
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["codex", "exec", "--full-auto", "--ephemeral"];
+		if (model !== undefined) {
+			// Strip provider prefix — Codex CLI expects bare model names.
+			cmd.push("--model", CodexRuntime.stripProviderPrefix(model));
+		}
+		cmd.push(prompt);
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions to a worktree.
+	 *
+	 * Writes the overlay to `AGENTS.md` in the worktree root (Codex's native
+	 * instruction file convention). Unlike Claude/Pi adapters, no hooks or
+	 * guard extensions are deployed — Codex enforces security boundaries via
+	 * its OS-level sandbox (Seatbelt on macOS, Landlock on Linux).
+	 *
+	 * When overlay is undefined (hooks-only deployment for coordinator/supervisor/monitor),
+	 * this is a no-op since Codex has no hook system to deploy.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content to write as AGENTS.md, or undefined for no-op
+	 * @param _hooks - Hook definition (unused — Codex uses OS sandbox, not hooks)
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		_hooks: HooksDef,
+	): Promise<void> {
+		if (!overlay) return;
+
+		const agentsPath = join(worktreePath, this.instructionPath);
+		// Ensure parent directory exists (AGENTS.md is in the worktree root,
+		// but the worktree dir itself might not exist yet).
+		await mkdir(dirname(agentsPath), { recursive: true });
+		await Bun.write(agentsPath, overlay.content);
+	}
+
+	/**
+	 * Codex interactive startup is treated as ready once a pane exists.
+	 *
+	 * @param _paneContent - Captured tmux pane content (unused)
+	 * @returns Always `{ phase: "ready" }`
+	 */
+	detectReady(_paneContent: string): ReadyState {
+		return { phase: "ready" };
+	}
+
+	/**
+	 * Codex does not require beacon verification/resend.
+	 *
+	 * Codex accepts startup input reliably once spawned.
+	 */
+	requiresBeaconVerification(): boolean {
+		return false;
+	}
+
+	/**
+	 * Parse a Codex NDJSON transcript file into normalized token usage.
+	 *
+	 * Codex NDJSON format (from `--json` flag) differs from Claude/Pi:
+	 * - Token counts are in `turn.completed` events with
+	 *   `usage.input_tokens` and `usage.output_tokens`
+	 * - Model identity may appear in `thread.started` events or item metadata
+	 *
+	 * Returns null if the file does not exist or cannot be parsed.
+	 *
+	 * @param path - Absolute path to the Codex NDJSON transcript file
+	 * @returns Aggregated token usage, or null if unavailable
+	 */
+	async parseTranscript(path: string): Promise<TranscriptSummary | null> {
+		const file = Bun.file(path);
+		if (!(await file.exists())) {
+			return null;
+		}
+
+		try {
+			const text = await file.text();
+			const lines = text.split("\n").filter((l) => l.trim().length > 0);
+
+			let inputTokens = 0;
+			let outputTokens = 0;
+			let model = "";
+
+			for (const line of lines) {
+				let event: Record<string, unknown>;
+				try {
+					event = JSON.parse(line) as Record<string, unknown>;
+				} catch {
+					// Skip malformed lines — partial writes during capture.
+					continue;
+				}
+
+				if (event.type === "turn.completed") {
+					const usage = event.usage as Record<string, number | undefined> | undefined;
+					if (usage) {
+						if (typeof usage.input_tokens === "number") {
+							inputTokens += usage.input_tokens;
+						}
+						if (typeof usage.output_tokens === "number") {
+							outputTokens += usage.output_tokens;
+						}
+					}
+				}
+
+				// Capture model from any event that carries it.
+				if (typeof event.model === "string") {
+					model = event.model;
+				}
+			}
+
+			return { inputTokens, outputTokens, model };
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Build runtime-specific environment variables for model/provider routing.
+	 *
+	 * Returns the provider environment variables from the resolved model.
+	 * For OpenAI native: may include OPENAI_API_KEY, OPENAI_BASE_URL.
+	 * For gateway providers: may include gateway-specific auth and routing vars.
+	 *
+	 * @param model - Resolved model with optional provider env vars
+	 * @returns Environment variable map (may be empty)
+	 */
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return model.env ?? {};
+	}
+
+	/** Codex does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
+}

package/src/runtimes/connections.test.ts

@@ -0,0 +1,214 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+	addHeadlessConnectionListener,
+	getConnection,
+	registerHeadlessConnection,
+	removeConnection,
+	setConnection,
+} from "./connections.ts";
+import type { ConnectionState, RuntimeConnection } from "./types.ts";
+
+/** Minimal RuntimeConnection stub for testing the registry. */
+function makeConn(onClose?: () => void): RuntimeConnection {
+	return {
+		sendPrompt: async (_text: string) => {},
+		followUp: async (_text: string) => {},
+		abort: async () => {},
+		getState: async (): Promise<ConnectionState> => ({ status: "idle" }),
+		close: () => {
+			if (onClose) onClose();
+		},
+	};
+}
+
+describe("connection registry", () => {
+	// Reset registry between tests by removing any entries set during each test.
+	// We track names used so we can clean up without affecting other entries.
+	const usedNames: string[] = [];
+
+	afterEach(() => {
+		for (const name of usedNames.splice(0)) {
+			const conn = getConnection(name);
+			if (conn) {
+				removeConnection(name);
+			}
+		}
+	});
+
+	test("set and get returns the registered connection", () => {
+		const conn = makeConn();
+		usedNames.push("agent-alpha");
+		setConnection("agent-alpha", conn);
+		expect(getConnection("agent-alpha")).toBe(conn);
+	});
+
+	test("get unknown returns undefined", () => {
+		expect(getConnection("does-not-exist-xyz")).toBeUndefined();
+	});
+
+	test("removeConnection calls close() on the connection", () => {
+		let closed = false;
+		const conn = makeConn(() => {
+			closed = true;
+		});
+		usedNames.push("agent-beta");
+		setConnection("agent-beta", conn);
+		removeConnection("agent-beta");
+		expect(closed).toBe(true);
+	});
+
+	test("removeConnection deletes the entry (get returns undefined after)", () => {
+		const conn = makeConn();
+		usedNames.push("agent-gamma");
+		setConnection("agent-gamma", conn);
+		removeConnection("agent-gamma");
+		expect(getConnection("agent-gamma")).toBeUndefined();
+	});
+
+	test("removeConnection on unknown name is a no-op (does not throw)", () => {
+		expect(() => removeConnection("never-registered-xyz")).not.toThrow();
+	});
+
+	test("setConnection overwrites an existing entry", () => {
+		const conn1 = makeConn();
+		const conn2 = makeConn();
+		usedNames.push("agent-delta");
+		setConnection("agent-delta", conn1);
+		setConnection("agent-delta", conn2);
+		expect(getConnection("agent-delta")).toBe(conn2);
+	});
+});
+
+describe("headless connection listener API", () => {
+	const usedNames: string[] = [];
+	const unsubscribers: Array<() => void> = [];
+
+	afterEach(() => {
+		for (const unsub of unsubscribers.splice(0)) unsub();
+		for (const name of usedNames.splice(0)) {
+			if (getConnection(name)) {
+				removeConnection(name);
+			}
+		}
+	});
+
+	function makeStdin(): { write(): Promise<number> } {
+		return { write: () => Promise.resolve(0) };
+	}
+
+	test("onRegister fires when registerHeadlessConnection runs", () => {
+		const seen: Array<{ name: string }> = [];
+		unsubscribers.push(
+			addHeadlessConnectionListener({
+				onRegister(agentName) {
+					seen.push({ name: agentName });
+				},
+			}),
+		);
+
+		usedNames.push("listener-agent-1");
+		registerHeadlessConnection("listener-agent-1", { pid: 99999, stdin: makeStdin() });
+
+		expect(seen).toEqual([{ name: "listener-agent-1" }]);
+	});
+
+	test("onRemove fires when a headless connection is removed", () => {
+		const removed: string[] = [];
+		unsubscribers.push(
+			addHeadlessConnectionListener({
+				onRegister: () => {},
+				onRemove(agentName) {
+					removed.push(agentName);
+				},
+			}),
+		);
+
+		usedNames.push("listener-agent-2");
+		registerHeadlessConnection("listener-agent-2", { pid: 99999, stdin: makeStdin() });
+		removeConnection("listener-agent-2");
+
+		expect(removed).toEqual(["listener-agent-2"]);
+	});
+
+	test("onRemove does NOT fire for non-headless connections", () => {
+		const removed: string[] = [];
+		unsubscribers.push(
+			addHeadlessConnectionListener({
+				onRegister: () => {},
+				onRemove(agentName) {
+					removed.push(agentName);
+				},
+			}),
+		);
+
+		const conn: RuntimeConnection = {
+			sendPrompt: async () => {},
+			followUp: async () => {},
+			abort: async () => {},
+			getState: async (): Promise<ConnectionState> => ({ status: "idle" }),
+			close: () => {},
+		};
+		usedNames.push("non-headless-agent");
+		setConnection("non-headless-agent", conn);
+		removeConnection("non-headless-agent");
+
+		expect(removed).toEqual([]);
+	});
+
+	test("listener added after registration sees existing agents via catch-up", () => {
+		usedNames.push("preexisting-agent");
+		registerHeadlessConnection("preexisting-agent", { pid: 99999, stdin: makeStdin() });
+
+		const seen: string[] = [];
+		unsubscribers.push(
+			addHeadlessConnectionListener({
+				onRegister(agentName) {
+					seen.push(agentName);
+				},
+			}),
+		);
+
+		expect(seen).toContain("preexisting-agent");
+	});
+
+	test("unsubscribe stops further notifications", () => {
+		const seen: string[] = [];
+		const unsub = addHeadlessConnectionListener({
+			onRegister(agentName) {
+				seen.push(agentName);
+			},
+		});
+		unsub();
+
+		usedNames.push("after-unsub-agent");
+		registerHeadlessConnection("after-unsub-agent", { pid: 99999, stdin: makeStdin() });
+
+		expect(seen).toEqual([]);
+	});
+
+	test("onRegister receives the stdin handle from the spawned process", async () => {
+		const writes: string[] = [];
+		const stdin = {
+			write(data: string | Uint8Array) {
+				writes.push(typeof data === "string" ? data : new TextDecoder().decode(data));
+				return Promise.resolve(0);
+			},
+		};
+
+		const observed: Array<{ write(data: string | Uint8Array): number | Promise<number> }> = [];
+		unsubscribers.push(
+			addHeadlessConnectionListener({
+				onRegister(_agentName, s) {
+					observed.push(s);
+				},
+			}),
+		);
+
+		usedNames.push("stdin-pass-agent");
+		registerHeadlessConnection("stdin-pass-agent", { pid: 99999, stdin });
+		expect(observed.length).toBe(1);
+		expect(observed[0]).toBe(stdin);
+		await observed[0]?.write("hello");
+		expect(writes).toEqual(["hello"]);
+	});
+});

package/src/runtimes/connections.ts

@@ -0,0 +1,103 @@
+/**
+ * Module-level connection registry for active RuntimeConnection instances.
+ *
+ * Tracks RPC connections to headless agent processes (e.g., Sapling, headless Claude).
+ * Keyed by agent name — same namespace as AgentSession.agentName.
+ *
+ * Thread safety: single-threaded Bun runtime; no locking needed.
+ */
+
+import { HeadlessClaudeConnection } from "./headless-connection.ts";
+import type { RuntimeConnection } from "./types.ts";
+
+/** Writable handle exposed to headless connection listeners. */
+export type HeadlessStdin = { write(data: string | Uint8Array): number | Promise<number> };
+
+/**
+ * Listener fired on headless Claude connection lifecycle events.
+ * Fires only for connections created via registerHeadlessConnection() — Sapling
+ * and other RuntimeConnection registrants via setConnection() are not surfaced
+ * because their wire format differs from headless Claude's stream-json stdin.
+ */
+export interface HeadlessConnectionListener {
+	onRegister(agentName: string, stdin: HeadlessStdin): void;
+	onRemove?(agentName: string): void;
+}
+
+const connections = new Map<string, RuntimeConnection>();
+const headlessAgents = new Map<string, HeadlessStdin>();
+const listeners = new Set<HeadlessConnectionListener>();
+
+/** Retrieve the active connection for a given agent, or undefined if none. */
+export function getConnection(agentName: string): RuntimeConnection | undefined {
+	return connections.get(agentName);
+}
+
+/** Register a connection for a given agent. Overwrites any existing entry. */
+export function setConnection(agentName: string, conn: RuntimeConnection): void {
+	connections.set(agentName, conn);
+}
+
+/**
+ * Remove the connection for a given agent, calling close() first.
+ * Safe to call if no connection exists (no-op).
+ */
+export function removeConnection(agentName: string): void {
+	const conn = connections.get(agentName);
+	if (!conn) return;
+	if (headlessAgents.delete(agentName)) {
+		for (const listener of listeners) {
+			listener.onRemove?.(agentName);
+		}
+	}
+	conn.close();
+	connections.delete(agentName);
+}
+
+/**
+ * Create a HeadlessClaudeConnection from a spawned process handle and register it.
+ *
+ * Called by spawnHeadlessAgent() (process.ts) when an agentName is provided.
+ * The registered connection is retrievable via getConnection(agentName) for
+ * follow-up delivery, state polling, and abort — all without tmux.
+ *
+ * This is the sibling registration path to Sapling's connect() flow. It does NOT
+ * generalize RpcProcessHandle and does NOT touch other runtime adapters.
+ *
+ * @param agentName - Unique agent identifier (same namespace as AgentSession.agentName)
+ * @param proc - Spawned headless process with pid and stdin
+ * @returns The newly created and registered RuntimeConnection
+ */
+export function registerHeadlessConnection(
+	agentName: string,
+	proc: { pid: number; stdin: HeadlessStdin },
+): RuntimeConnection {
+	const conn = new HeadlessClaudeConnection(proc.pid, proc.stdin);
+	setConnection(agentName, conn);
+	headlessAgents.set(agentName, proc.stdin);
+	for (const listener of listeners) {
+		listener.onRegister(agentName, proc.stdin);
+	}
+	return conn;
+}
+
+/**
+ * Subscribe to headless Claude connection lifecycle events.
+ *
+ * onRegister fires synchronously after registerHeadlessConnection() inserts the
+ * connection. onRemove fires synchronously before removeConnection() closes the
+ * connection. Listeners observing already-registered agents at subscribe time
+ * receive an immediate onRegister for each — this lets late subscribers (e.g.,
+ * runServe started after agents already exist) catch up without rescanning.
+ *
+ * @returns Unsubscribe function that removes this listener.
+ */
+export function addHeadlessConnectionListener(listener: HeadlessConnectionListener): () => void {
+	listeners.add(listener);
+	for (const [agentName, stdin] of headlessAgents) {
+		listener.onRegister(agentName, stdin);
+	}
+	return () => {
+		listeners.delete(listener);
+	};
+}