@agentplate/cli 1.0.0

package/src/runtimes/claude.ts

@@ -0,0 +1,313 @@
+/**
+ * Claude Code runtime adapter.
+ *
+ * Drives Anthropic's `claude` CLI in headless, spawn-per-turn mode. Each turn is
+ * a single `claude -p … --output-format stream-json` invocation whose stdout is a
+ * stream of NDJSON events; {@link ClaudeRuntime.parseEvents} normalizes those into
+ * {@link AgentEvent}s. The adapter is stateless — session continuity across turns
+ * is carried entirely by the runtime session id (`--resume`), which the caller
+ * extracts from the `sessionId` an event reports and threads back in via
+ * {@link DirectSpawnOpts.resumeSessionId}.
+ */
+
+import type { ResolvedModel } from "../types.ts";
+import type { AgentEvent, AgentRuntime, DirectSpawnOpts, InteractiveSpawnOpts } from "./types.ts";
+
+/**
+ * Claude Code's own sub-agent / orchestration tools, disabled on every
+ * Agentplate-driven session. Agents MUST spawn teammates only through
+ * `agentplate sling` (via Bash) so the work is tracked in the session store, mail
+ * bus, and merge queue. Subagents launched with Claude Code's native tools are
+ * invisible to all of that — they never show in `ap serve`/`ap tui` and their
+ * work is never merged. Blocking the tools makes sling the ONLY spawn path
+ * (Bash/Read/Edit/Write etc. remain available, so sling still works). Unknown
+ * names are harmless — Claude Code just ignores tools it doesn't have.
+ */
+const BLOCKED_SPAWN_TOOLS = ["Task", "Agent", "Workflow"] as const;
+
+/**
+ * Additional tools disabled for the INTERACTIVE coordinator only. The coordinator
+ * is a dispatcher, not an implementer — it must hire agents via `agentplate sling`
+ * (Bash) and never edit code itself. Blocking the file-mutation tools enforces
+ * that at the tool layer (Bash/Read/Grep/Glob stay, so sling + surveying work).
+ * Headless worker turns ({@link ClaudeRuntime.buildDirectSpawn}) do NOT get this —
+ * workers must edit.
+ */
+const COORDINATOR_BLOCKED_TOOLS = [
+	...BLOCKED_SPAWN_TOOLS,
+	"Edit",
+	"Write",
+	"MultiEdit",
+	"NotebookEdit",
+] as const;
+
+export class ClaudeRuntime implements AgentRuntime {
+	/** Registry id; also the value users pass to `--runtime claude`. */
+	readonly id = "claude";
+
+	/** Claude Code is the primary, fully-supported runtime. */
+	readonly stability = "stable" as const;
+
+	/**
+	 * Claude Code automatically reads `.claude/CLAUDE.md` from the working
+	 * directory, so the overlay is written there rather than passed as a flag.
+	 */
+	readonly instructionPath = ".claude/CLAUDE.md";
+
+	/**
+	 * Build argv for one headless streaming turn (run via `Bun.spawn`).
+	 *
+	 * Flag choices:
+	 * - `-p <prompt>` runs the prompt non-interactively and exits on completion.
+	 *   The prompt defaults to "" so a resume-only nudge turn (where the caller
+	 *   feeds the real text on stdin) still produces a well-formed argv.
+	 * - `--output-format stream-json` + `--verbose` emit the per-event NDJSON that
+	 *   {@link parseEvents} consumes; `--verbose` is required for the streaming
+	 *   form to include tool-use / session events rather than a single result.
+	 * - `--model <model>` pins the concrete model resolved upstream.
+	 * - `--resume <id>` is emitted ONLY on follow-up turns (a non-empty session
+	 *   id). The first turn omits it so Claude Code starts a fresh session.
+	 * - `--permission-mode bypassPermissions` because workers run unattended in an
+	 *   isolated worktree; interactive permission prompts would deadlock a
+	 *   headless process.
+	 *
+	 * Returned as an argv array (never a shell string) so no value is subject to
+	 * shell interpolation.
+	 */
+	buildDirectSpawn(opts: DirectSpawnOpts): string[] {
+		return [
+			"claude",
+			"-p",
+			opts.prompt ?? "",
+			"--output-format",
+			"stream-json",
+			"--verbose",
+			"--model",
+			opts.model,
+			// Only resume when a prior turn handed us a real session id. An empty
+			// string is treated as "no resume" so the first turn opens a new session.
+			...(opts.resumeSessionId ? ["--resume", opts.resumeSessionId] : []),
+			// Force sling-only spawning. The variadic `--disallowedTools <tools...>` is
+			// placed before `--permission-mode` so that flag terminates the list and the
+			// `-p` prompt (a leading flag value) is never swallowed.
+			"--disallowedTools",
+			...BLOCKED_SPAWN_TOOLS,
+			"--permission-mode",
+			"bypassPermissions",
+		];
+	}
+
+	/**
+	 * Build argv for an ATTENDED interactive Claude Code session.
+	 *
+	 * Run in the foreground with inherited stdio so the operator chats directly
+	 * (`coordinator start`). The interactive session IS the coordinator, so it is
+	 * dispatch-only: {@link COORDINATOR_BLOCKED_TOOLS} disables the native sub-agent
+	 * tools AND file-mutation tools, leaving Bash (for `agentplate sling`) + Read.
+	 * The agent's role is injected via `--append-system-prompt` — a literal argv
+	 * value (no `$(cat …)` shell trick) since we spawn an argv array.
+	 */
+	buildInteractiveSpawn(opts: InteractiveSpawnOpts): string[] {
+		const permMode = opts.permissionMode === "bypass" ? "bypassPermissions" : "default";
+		// `--disallowedTools` (variadic) sits before `--permission-mode` so that flag
+		// terminates the tool list and the trailing seed message is never swallowed.
+		const argv = [
+			"claude",
+			"--model",
+			opts.model,
+			"--disallowedTools",
+			...COORDINATOR_BLOCKED_TOOLS,
+			"--permission-mode",
+			permMode,
+		];
+		if (opts.systemPrompt && opts.systemPrompt.length > 0) {
+			argv.push("--append-system-prompt", opts.systemPrompt);
+		}
+		// A seed message becomes the first user turn (claude treats a trailing
+		// positional as the initial prompt while staying interactive).
+		if (opts.initialMessage && opts.initialMessage.length > 0) {
+			argv.push(opts.initialMessage);
+		}
+		return argv;
+	}
+
+	/**
+	 * Provider env vars for the resolved model (API keys, base URLs).
+	 *
+	 * Auth is never hardcoded here — it is whatever the provider layer resolved
+	 * onto the model. A fresh object is returned (rather than `model.env` itself)
+	 * so a caller mutating the result cannot leak back into shared config.
+	 */
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return { ...(model.env ?? {}) };
+	}
+
+	/**
+	 * Build argv for a one-shot, non-streaming call (`claude -p … --output-format
+	 * text`). Used later by AI-assisted merge resolution and skill distillation,
+	 * where we want only the final text answer, not an event stream. The model is
+	 * appended only when provided so the caller can defer to Claude Code's own
+	 * default.
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const argv = ["claude", "-p", prompt, "--output-format", "text"];
+		if (model !== undefined) {
+			argv.push("--model", model);
+		}
+		return argv;
+	}
+
+	/**
+	 * Parse Claude Code's stream-json stdout into normalized {@link AgentEvent}s.
+	 *
+	 * The stream is NDJSON: one JSON object per line, but TCP/pipe chunk
+	 * boundaries do NOT align to newlines, so we keep a `buffer` of the trailing
+	 * partial line across reads and only parse once a `\n` completes it. For each
+	 * complete, non-blank line we:
+	 *   - parse JSON (silently skipping malformed lines — a partial flush or a
+	 *     non-JSON diagnostic line must not abort the whole turn),
+	 *   - copy through the message `type`,
+	 *   - capture `session_id` → `sessionId` (Claude emits it on the early
+	 *     `system` init event; the caller needs it for the next turn's --resume),
+	 *   - lift a tool name out of an assistant `tool_use` content block → `tool`,
+	 *   - attach the raw parsed object as `raw` for callers needing more detail.
+	 */
+	async *parseEvents(stream: ReadableStream<Uint8Array>): AsyncIterable<AgentEvent> {
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				// `stream: true` lets the decoder hold back a trailing partial
+				// multi-byte sequence until the next chunk completes it.
+				buffer += decoder.decode(value, { stream: true });
+
+				const lines = buffer.split("\n");
+				// The last element is an incomplete line (no terminating newline yet)
+				// or "" — keep it buffered for the next read.
+				buffer = lines.pop() ?? "";
+
+				for (const line of lines) {
+					const event = parseClaudeLine(line);
+					if (event) yield event;
+				}
+			}
+
+			// Emit any final line left after a clean stream end without a trailing
+			// newline (e.g. the process exits right after writing the result event).
+			const tail = parseClaudeLine(buffer);
+			if (tail) yield tail;
+		} finally {
+			// Always release the lock so the underlying stream can be GC'd / reused
+			// even if the consumer breaks out of the loop early.
+			reader.releaseLock();
+		}
+	}
+}
+
+/**
+ * Parse a single stream-json line into an {@link AgentEvent}, or `null` for a
+ * blank or unparseable line. Kept as a free function (not a closure) so it is
+ * trivially unit-testable and allocation-free per line.
+ */
+function parseClaudeLine(line: string): AgentEvent | null {
+	const trimmed = line.trim();
+	if (!trimmed) return null;
+
+	let raw: unknown;
+	try {
+		raw = JSON.parse(trimmed);
+	} catch {
+		// Not valid JSON (partial flush, diagnostic noise) — skip, never throw.
+		return null;
+	}
+
+	if (typeof raw !== "object" || raw === null) return null;
+	const msg = raw as Record<string, unknown>;
+
+	const event: AgentEvent = {
+		type: typeof msg.type === "string" ? msg.type : "unknown",
+		raw,
+	};
+
+	// session_id appears on the init/system event and is reused for --resume.
+	if (typeof msg.session_id === "string" && msg.session_id.length > 0) {
+		event.sessionId = msg.session_id;
+	}
+
+	const tool = extractToolName(msg);
+	if (tool !== undefined) event.tool = tool;
+
+	const usage = extractUsage(msg);
+	if (usage !== undefined) event.usage = usage;
+
+	// Surface a failure reason: a `result` event with `is_error` carries the
+	// message in `result`; a bare `error` event carries it in `error`/`message`.
+	if (msg.is_error === true && typeof msg.result === "string") {
+		event.error = msg.result;
+	} else if (msg.type === "error") {
+		if (typeof msg.error === "string") event.error = msg.error;
+		else if (typeof msg.message === "string") event.error = msg.message;
+	}
+
+	return event;
+}
+
+/**
+ * Pull token usage + USD cost out of a Claude Code `result` event, which carries
+ * `total_cost_usd` and a `usage` object (`input_tokens`, `output_tokens`, and the
+ * two cache token counts). We sum all numeric token fields so cache reads/writes
+ * are counted too. Returns `undefined` for non-result events or when no spend was
+ * reported, so the Costs page only aggregates real usage.
+ */
+function extractUsage(
+	msg: Record<string, unknown>,
+): { tokens: number; costUsd: number } | undefined {
+	if (msg.type !== "result") return undefined;
+
+	let tokens = 0;
+	const usage = msg.usage;
+	if (typeof usage === "object" && usage !== null) {
+		for (const key of [
+			"input_tokens",
+			"output_tokens",
+			"cache_creation_input_tokens",
+			"cache_read_input_tokens",
+		]) {
+			const v = (usage as Record<string, unknown>)[key];
+			if (typeof v === "number") tokens += v;
+		}
+	}
+	const costUsd = typeof msg.total_cost_usd === "number" ? msg.total_cost_usd : 0;
+	if (tokens === 0 && costUsd === 0) return undefined;
+	return { tokens, costUsd };
+}
+
+/**
+ * Pull a tool name out of an assistant message's content blocks. Claude nests
+ * tool calls as `{ type: "tool_use", name: "Edit", … }` blocks inside
+ * `message.content`; we return the first such name. Returns `undefined` for any
+ * shape that does not carry a tool_use block.
+ */
+function extractToolName(msg: Record<string, unknown>): string | undefined {
+	const message = msg.message;
+	if (typeof message !== "object" || message === null) return undefined;
+
+	const content = (message as Record<string, unknown>).content;
+	if (!Array.isArray(content)) return undefined;
+
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) continue;
+		const b = block as Record<string, unknown>;
+		if (b.type === "tool_use" && typeof b.name === "string") {
+			return b.name;
+		}
+	}
+	return undefined;
+}
+
+/** Singleton for callers that do not need dependency injection. */
+export const claudeRuntime = new ClaudeRuntime();

package/src/runtimes/codex.ts

@@ -0,0 +1,280 @@
+/**
+ * OpenAI Codex runtime adapter.
+ *
+ * Drives OpenAI's `codex` CLI in headless, spawn-per-turn mode. Like Claude Code,
+ * Codex authenticates with its OWN login: a ChatGPT/Codex OAuth session stored in
+ * `~/.codex/auth.json` (`auth_mode` + `tokens`). When the active provider uses
+ * `authMode: "subscription"`, the provider layer injects no key (see
+ * `src/runtimes/resolve.ts`) and Codex falls back to that OAuth login — the exact
+ * mirror of how the Anthropic provider reuses the `claude` login. An
+ * `api-key` / `env` provider instead flows `OPENAI_API_KEY` through
+ * {@link CodexRuntime.buildEnv}; auth is never hardcoded here.
+ *
+ * A headless turn is `codex exec --json …`, whose stdout is a stream of JSONL
+ * thread/item events (`thread.started`, `item.completed`, `turn.completed`);
+ * {@link CodexRuntime.parseEvents} normalizes those into {@link AgentEvent}s.
+ * Session continuity across turns is carried by the `thread_id` captured from the
+ * `thread.started` event and threaded back via `codex exec resume <id>`
+ * ({@link DirectSpawnOpts.resumeSessionId}).
+ *
+ * Validated against codex-cli 0.128 flag + JSON-event shapes.
+ */
+
+import type { ResolvedModel } from "../types.ts";
+import type { AgentEvent, AgentRuntime, DirectSpawnOpts, InteractiveSpawnOpts } from "./types.ts";
+
+export class CodexRuntime implements AgentRuntime {
+	/** Registry id; also the value users pass to `--runtime codex`. */
+	readonly id = "codex";
+
+	/** Beta: validated against codex-cli 0.128 flag shapes. */
+	readonly stability = "beta" as const;
+
+	/** Codex reads `AGENTS.md` from the working directory at startup. */
+	readonly instructionPath = "AGENTS.md";
+
+	/**
+	 * Build argv for one headless streaming turn (`codex exec --json`).
+	 *
+	 * Flag choices:
+	 * - `exec` runs Codex non-interactively and exits on completion.
+	 * - `--json` emits the per-event EventMsg JSONL that {@link parseEvents}
+	 *   consumes (including the `session_configured` event carrying the session id).
+	 * - `--model <model>` pins the concrete model resolved upstream.
+	 * - `--dangerously-bypass-approvals-and-sandbox` is the analog of Claude Code's
+	 *   `bypassPermissions`: workers run unattended in an isolated worktree, so
+	 *   interactive approval prompts would deadlock a headless process.
+	 * - `resume <id>` (a subcommand) is emitted ONLY on follow-up turns; the first
+	 *   turn omits it so Codex starts a fresh session.
+	 *
+	 * The prompt is the trailing positional. Returned as an argv array (never a
+	 * shell string) so no value is subject to shell interpolation.
+	 */
+	buildDirectSpawn(opts: DirectSpawnOpts): string[] {
+		const prompt = opts.prompt ?? "";
+		// Only resume when a prior turn handed us a real session id. An empty string
+		// is treated as "no resume" so the first turn opens a new session.
+		if (opts.resumeSessionId) {
+			return [
+				"codex",
+				"exec",
+				"resume",
+				opts.resumeSessionId,
+				"--json",
+				"--model",
+				opts.model,
+				"--dangerously-bypass-approvals-and-sandbox",
+				prompt,
+			];
+		}
+		return [
+			"codex",
+			"exec",
+			"--json",
+			"--model",
+			opts.model,
+			"--dangerously-bypass-approvals-and-sandbox",
+			prompt,
+		];
+	}
+
+	/**
+	 * Build argv for an ATTENDED interactive Codex session.
+	 *
+	 * Run in the foreground with inherited stdio so the operator chats directly
+	 * (`coordinator start`). Codex has no `--append-system-prompt` flag, so the
+	 * agent's role must be supplied via the `AGENTS.md` overlay; `systemPrompt`/
+	 * `permissionMode` are accepted for interface parity but not passed as flags
+	 * (the human is present to approve actions, so the default posture applies). A
+	 * seed message becomes the initial prompt while the TUI stays interactive.
+	 */
+	buildInteractiveSpawn(opts: InteractiveSpawnOpts): string[] {
+		const argv = ["codex", "--model", opts.model];
+		if (opts.initialMessage && opts.initialMessage.length > 0) {
+			argv.push(opts.initialMessage);
+		}
+		return argv;
+	}
+
+	/**
+	 * Provider env vars for the resolved model (API keys, base URLs).
+	 *
+	 * Auth is never hardcoded here — it is whatever the provider layer resolved
+	 * onto the model (empty for subscription/OAuth login, `OPENAI_API_KEY` for an
+	 * api-key/env provider). A fresh object is returned so a caller mutating the
+	 * result cannot leak back into shared config.
+	 */
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return { ...(model.env ?? {}) };
+	}
+
+	/**
+	 * Build argv for a one-shot, non-streaming call (`codex exec`). Used by
+	 * AI-assisted merge resolution and skill distillation, where we want only the
+	 * final text answer, not an event stream. The bypass flag keeps it
+	 * non-interactive; the model is appended only when provided so the caller can
+	 * defer to Codex's own default.
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const argv = ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox"];
+		if (model !== undefined) {
+			argv.push("--model", model);
+		}
+		argv.push(prompt);
+		return argv;
+	}
+
+	/**
+	 * Parse Codex's `--json` stdout into normalized {@link AgentEvent}s.
+	 *
+	 * The stream is JSONL: one JSON object per line, but pipe chunk boundaries do
+	 * NOT align to newlines, so we keep a `buffer` of the trailing partial line
+	 * across reads and only parse once a `\n` completes it. Malformed lines are
+	 * skipped (a partial flush or diagnostic line must not abort the whole turn).
+	 */
+	async *parseEvents(stream: ReadableStream<Uint8Array>): AsyncIterable<AgentEvent> {
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+
+		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) {
+					const event = parseCodexLine(line);
+					if (event) yield event;
+				}
+			}
+
+			const tail = parseCodexLine(buffer);
+			if (tail) yield tail;
+		} finally {
+			reader.releaseLock();
+		}
+	}
+}
+
+/**
+ * Parse a single `codex exec --json` line into an {@link AgentEvent}, or `null`
+ * for a blank or unparseable line.
+ *
+ * codex-cli 0.128 emits the thread/item schema, flat per line:
+ *   - `{ type: "thread.started", thread_id }`        ← the resume session id
+ *   - `{ type: "turn.started" | "turn.completed", usage? }`
+ *   - `{ type: "item.completed", item: { type, … } }` ← messages / tool actions
+ * We also tolerate the older EventMsg form (`{ id, msg: { type, … } }`) so the
+ * parser works across codex versions — mirroring the Claude parser's resilience.
+ */
+function parseCodexLine(line: string): AgentEvent | null {
+	const trimmed = line.trim();
+	if (!trimmed) return null;
+
+	let raw: unknown;
+	try {
+		raw = JSON.parse(trimmed);
+	} catch {
+		return null;
+	}
+
+	if (typeof raw !== "object" || raw === null) return null;
+	const top = raw as Record<string, unknown>;
+
+	// Thread/item form is flat; the legacy EventMsg form nests under `msg`.
+	const msg =
+		typeof top.msg === "object" && top.msg !== null ? (top.msg as Record<string, unknown>) : top;
+
+	const type =
+		typeof top.type === "string" ? top.type : typeof msg.type === "string" ? msg.type : "unknown";
+
+	const event: AgentEvent = { type, raw };
+
+	const sessionId = extractCodexSessionId(msg, top);
+	if (sessionId !== undefined) event.sessionId = sessionId;
+
+	const tool = extractCodexTool(top, msg);
+	if (tool !== undefined) event.tool = tool;
+
+	const usage = extractCodexUsage(top);
+	if (usage !== undefined) event.usage = usage;
+
+	return event;
+}
+
+/**
+ * Pull the resume session id from a Codex event: `thread_id` on `thread.started`
+ * (0.128), or `session_id` on the legacy `session_configured` event. A top-level
+ * `session_id` is also accepted so resume keeps working across codex versions.
+ */
+function extractCodexSessionId(
+	msg: Record<string, unknown>,
+	top: Record<string, unknown>,
+): string | undefined {
+	for (const candidate of [top.thread_id, msg.session_id, top.session_id]) {
+		if (typeof candidate === "string" && candidate.length > 0) return candidate;
+	}
+	return undefined;
+}
+
+/**
+ * Derive a coarse tool name from a Codex event. In the thread/item schema, tool
+ * activity is an `item` whose `type` is something other than `agent_message` /
+ * `reasoning` (e.g. `command_execution`, `mcp_tool_call`, `file_change`,
+ * `web_search`). Legacy EventMsg shapes use `exec_command_begin` /
+ * `mcp_tool_call_begin`. Returns `undefined` when no tool is involved.
+ */
+function extractCodexTool(
+	top: Record<string, unknown>,
+	msg: Record<string, unknown>,
+): string | undefined {
+	const item = top.item;
+	if (typeof item === "object" && item !== null) {
+		const it = item as Record<string, unknown>;
+		const itype = typeof it.type === "string" ? it.type : undefined;
+		if (itype && itype !== "agent_message" && itype !== "reasoning") {
+			if (itype === "mcp_tool_call" && typeof it.tool === "string") return it.tool;
+			if (itype === "command_execution") return "shell";
+			return itype;
+		}
+	}
+
+	if (msg.type === "exec_command_begin") return "shell";
+	if (msg.type === "mcp_tool_call_begin") {
+		if (typeof msg.tool === "string") return msg.tool;
+		const invocation = msg.invocation;
+		if (typeof invocation === "object" && invocation !== null) {
+			const tool = (invocation as Record<string, unknown>).tool;
+			if (typeof tool === "string") return tool;
+		}
+		return "mcp";
+	}
+	return undefined;
+}
+
+/**
+ * Pull token usage from a Codex `turn.completed` event's `usage` object. Codex
+ * reports token counts but not a USD figure, so `costUsd` is 0. Tokens are
+ * `input_tokens + output_tokens` (cached/reasoning counts are subsets of those,
+ * so they are not added again). Returns `undefined` when no usage is present.
+ */
+function extractCodexUsage(
+	top: Record<string, unknown>,
+): { tokens: number; costUsd: number } | undefined {
+	if (top.type !== "turn.completed") return undefined;
+	const usage = top.usage;
+	if (typeof usage !== "object" || usage === null) return undefined;
+	const u = usage as Record<string, unknown>;
+	const input = typeof u.input_tokens === "number" ? u.input_tokens : 0;
+	const output = typeof u.output_tokens === "number" ? u.output_tokens : 0;
+	const tokens = input + output;
+	if (tokens === 0) return undefined;
+	return { tokens, costUsd: 0 };
+}
+
+/** Singleton for callers that do not need dependency injection. */
+export const codexRuntime = new CodexRuntime();