@ag-eco/agentplate-cli 0.13.0

package/src/runtimes/pi.ts

@@ -0,0 +1,305 @@
+// Pi runtime adapter for agentplate's AgentRuntime interface.
+// Implements the AgentRuntime contract for the `pi` CLI (Mario Zechner's Pi coding agent).
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { PiRuntimeConfig, ResolvedModel } from "../types.ts";
+import { generatePiGuardExtension } from "./pi-guards.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/** Default Pi runtime config used when no config is provided. */
+const DEFAULT_PI_CONFIG: PiRuntimeConfig = {
+	provider: "anthropic",
+	modelMap: {
+		opus: "anthropic/claude-opus-4-6",
+		sonnet: "anthropic/claude-sonnet-4-6",
+		haiku: "anthropic/claude-haiku-4-5",
+	},
+};
+
+/**
+ * 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.
+ */
+export class PiRuntime implements AgentRuntime {
+	/** Unique identifier for this runtime. */
+	readonly id = "pi";
+
+	/** Stability level. Pi adapter is experimental — not fully validated. */
+	readonly stability = "experimental" as const;
+
+	/** Relative path to the instruction file within a worktree. Pi reads AGENTS.md at startup. */
+	readonly instructionPath = "AGENTS.md";
+
+	private readonly config: PiRuntimeConfig;
+
+	constructor(config?: PiRuntimeConfig) {
+		this.config = config ?? DEFAULT_PI_CONFIG;
+	}
+
+	/**
+	 * Expand a model alias to a provider-qualified model ID.
+	 *
+	 * 1. If model contains "/" → already qualified, pass through
+	 * 2. If model is in modelMap → return the mapped value
+	 * 3. Otherwise → return `${provider}/${model}`
+	 */
+	expandModel(model: string): string {
+		if (model.includes("/")) return model;
+		const mapped = this.config.modelMap[model];
+		if (mapped) return mapped;
+		return `${this.config.provider}/${model}`;
+	}
+
+	/**
+	 * Build the shell command string to spawn an interactive Pi agent.
+	 *
+	 * Maps SpawnOpts to the `pi` CLI flags:
+	 * - `model` → `--model <model>`
+	 * - `permissionMode` is accepted but NOT mapped — Pi has no permission-mode flag.
+	 *   Security is enforced via guard extensions deployed by deployConfig().
+	 * - `appendSystemPrompt` → `--append-system-prompt '<escaped>'` (POSIX single-quote escaping)
+	 *
+	 * The `cwd` and `env` fields are handled by the tmux session creator, not embedded here.
+	 *
+	 * @param opts - Spawn options (model, appendSystemPrompt; permissionMode is ignored)
+	 * @returns Shell command string suitable for tmux new-session -c
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		let cmd = `pi --model ${this.expandModel(opts.model)}`;
+
+		if (opts.appendSystemPromptFile) {
+			// Read from file at shell expansion time — avoids tmux command length limits.
+			const escaped = opts.appendSystemPromptFile.replace(/'/g, "'\\''");
+			cmd += ` --append-system-prompt "$(cat '${escaped}')"`;
+		} else if (opts.appendSystemPrompt) {
+			// POSIX single-quote escape: end quote, backslash-quote, start quote.
+			const escaped = opts.appendSystemPrompt.replace(/'/g, "'\\''");
+			cmd += ` --append-system-prompt '${escaped}'`;
+		}
+
+		return cmd;
+	}
+
+	/**
+	 * Build the argv array for a headless one-shot Pi invocation.
+	 *
+	 * Returns an argv array suitable for `Bun.spawn()`. The `--print` flag causes Pi
+	 * to run the prompt and exit. Unlike Claude Code, the prompt is a positional argument
+	 * (last), not passed via `-p`.
+	 *
+	 * @param prompt - The prompt to pass as a positional argument
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["pi", "--print"];
+		if (model !== undefined) {
+			cmd.push("--model", this.expandModel(model));
+		}
+		cmd.push(prompt);
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions and guards to a worktree.
+	 *
+	 * Writes up to three files:
+	 * 1. `AGENTS.md` — agent's task-specific overlay. Skipped when overlay is undefined.
+	 * 2. `.pi/extensions/agentplate-guard.ts` — Pi guard extension (always deployed).
+	 * 3. `.pi/settings.json` — Pi settings enabling the extensions directory (always deployed).
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content to write as AGENTS.md, or undefined for guard-only deployment
+	 * @param hooks - Agent identity, capability, worktree path, and optional quality gates
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		hooks: HooksDef,
+	): Promise<void> {
+		if (overlay) {
+			await mkdir(worktreePath, { recursive: true });
+			await Bun.write(join(worktreePath, this.instructionPath), overlay.content);
+		}
+
+		// Always deploy Pi guard extension.
+		const piExtDir = join(worktreePath, ".pi", "extensions");
+		await mkdir(piExtDir, { recursive: true });
+		await Bun.write(join(piExtDir, "agentplate-guard.ts"), generatePiGuardExtension(hooks));
+
+		// Always deploy Pi settings pointing at the extensions directory.
+		const piDir = join(worktreePath, ".pi");
+		const settings = { extensions: ["./extensions"] };
+		await Bun.write(join(piDir, "settings.json"), `${JSON.stringify(settings, null, "\t")}\n`);
+	}
+
+	/**
+	 * Pi does not require beacon verification/resend.
+	 *
+	 * Claude Code's TUI sometimes swallows Enter during late initialization, so the
+	 * orchestrator resends the beacon until the pane leaves the "idle" state. Pi's TUI
+	 * does not have this issue AND its idle vs. processing states are indistinguishable
+	 * via detectReady (the header "pi v..." and status bar token counter are visible in
+	 * both states). Enabling the resend loop would spam Pi with duplicate beacon messages.
+	 */
+	requiresBeaconVerification(): boolean {
+		return false;
+	}
+
+	/**
+	 * Detect Pi TUI readiness from a tmux pane content snapshot.
+	 *
+	 * Pi shows a header containing "pi" and "model:" when the TUI has fully rendered.
+	 * Pi has no trust dialog phase.
+	 *
+	 * @param paneContent - Captured tmux pane content to analyze
+	 * @returns Current readiness phase
+	 */
+	detectReady(paneContent: string): ReadyState {
+		// Pi's TUI shows "pi v<version>" in the header and a status bar with
+		// a token usage indicator like "0.0%/200k" or "0.0%/1.0M" when fully rendered.
+		// The context window size uses k-scale (e.g. 200k) for smaller models and
+		// M-scale (e.g. 1.0M) for Opus/Sonnet with 1M+ context windows.
+		const hasHeader = paneContent.includes("pi v");
+		const hasStatusBar = /\d+\.\d+%\/[\d.]+[kKmM]/.test(paneContent);
+		if (hasHeader && hasStatusBar) {
+			return { phase: "ready" };
+		}
+		return { phase: "loading" };
+	}
+
+	/**
+	 * Parse a Pi transcript JSONL file into normalized token usage.
+	 *
+	 * Pi JSONL format (version 3):
+	 * - Session metadata: `{ type: "session", version: 3, id, cwd }`
+	 * - Model identity: `{ type: "model_change", provider, modelId }`
+	 * - Token usage: on `{ type: "message" }` events where `message.role === "assistant"`,
+	 *   nested under `message.usage`: `{ input, output, cacheRead, cacheWrite, totalTokens, cost }`
+	 * - Cost data: `message.usage.cost.total` (USD)
+	 *
+	 * Returns null if the file does not exist or cannot be parsed.
+	 *
+	 * @param path - Absolute path to the Pi transcript JSONL 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 entry: Record<string, unknown>;
+				try {
+					entry = JSON.parse(line) as Record<string, unknown>;
+				} catch {
+					// Skip malformed lines — Pi transcripts may have partial writes.
+					continue;
+				}
+
+				// Model identity from model_change events.
+				if (entry.type === "model_change") {
+					if (typeof entry.modelId === "string") {
+						model = entry.modelId;
+					} else if (typeof entry.model === "string") {
+						model = entry.model;
+					}
+				}
+
+				// Token usage from assistant message events.
+				// Pi v3 format: message.usage.input / message.usage.output
+				if (entry.type === "message") {
+					const msg = entry.message as Record<string, unknown> | undefined;
+					if (msg?.role === "assistant") {
+						const usage = msg.usage as Record<string, unknown> | undefined;
+						if (usage) {
+							if (typeof usage.input === "number") {
+								inputTokens += usage.input;
+							}
+							if (typeof usage.output === "number") {
+								outputTokens += usage.output;
+							}
+							// Also count cache tokens toward input for compatibility.
+							if (typeof usage.cacheRead === "number") {
+								inputTokens += usage.cacheRead;
+							}
+						}
+
+						// Capture model from message if model_change was missed.
+						if (typeof msg.model === "string" && model === "") {
+							model = msg.model;
+						}
+					}
+				}
+
+				// Fallback: message_end events (older Pi versions).
+				if (entry.type === "message_end") {
+					if (typeof entry.inputTokens === "number") {
+						inputTokens += entry.inputTokens;
+					}
+					if (typeof entry.outputTokens === "number") {
+						outputTokens += entry.outputTokens;
+					}
+				}
+			}
+
+			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, or an empty
+	 * object if none are set.
+	 *
+	 * @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 ?? {};
+	}
+
+	/**
+	 * Return the directory containing Pi session transcript files.
+	 *
+	 * Pi stores JSONL transcripts in `~/.pi/agent/sessions/{encoded-project-path}/`.
+	 * The project path is encoded by replacing path separators with `--` and
+	 * prefixing/suffixing with `--`.
+	 *
+	 * Example: `/home/user/project` → `~/.pi/agent/sessions/--home-user-project--/`
+	 *
+	 * @param projectRoot - Absolute path to the project root
+	 * @returns Absolute path to the transcript directory
+	 */
+	getTranscriptDir(projectRoot: string): string | null {
+		const home = process.env.HOME ?? process.env.USERPROFILE;
+		if (!home) return null;
+
+		// Pi encodes the project path: replace separators with dashes, wrap with --
+		const encoded = `--${projectRoot.replace(/[\\/]/g, "-").replace(/:/g, "")}--`;
+		return join(home, ".pi", "agent", "sessions", encoded);
+	}
+}

package/src/runtimes/registry.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "bun:test";
+import type { AgentplateConfig } from "../types.ts";
+import { ClaudeRuntime } from "./claude.ts";
+import { CodexRuntime } from "./codex.ts";
+import { CopilotRuntime } from "./copilot.ts";
+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";
+
+describe("getRuntime", () => {
+	it("returns a ClaudeRuntime by default (no args)", () => {
+		const runtime = getRuntime();
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+		expect(runtime.id).toBe("claude");
+	});
+
+	it('returns a ClaudeRuntime when name is "claude"', () => {
+		const runtime = getRuntime("claude");
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+		expect(runtime.id).toBe("claude");
+	});
+
+	it("throws with a helpful message for an unknown runtime", () => {
+		expect(() => getRuntime("unknown-runtime")).toThrow(
+			'Unknown runtime: "unknown-runtime". Available: aider, amp, claude, codex, copilot, cursor, gemini, goose, opencode, pi, sapling',
+		);
+	});
+
+	it("uses config.runtime.default when name is omitted", () => {
+		const config = { runtime: { default: "claude" } } as AgentplateConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+		expect(runtime.id).toBe("claude");
+	});
+
+	it("explicit name overrides config.runtime.default", () => {
+		const config = { runtime: { default: "claude" } } as AgentplateConfig;
+		// Both are "claude" here since that's the only registered runtime,
+		// but the name arg takes precedence over config.
+		const runtime = getRuntime("claude", config);
+		expect(runtime).toBeInstanceOf(ClaudeRuntime);
+	});
+
+	it("resolves codex runtime from config default", () => {
+		const config = { runtime: { default: "codex" } } as AgentplateConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(CodexRuntime);
+		expect(runtime.id).toBe("codex");
+	});
+
+	it("returns a new instance on each call (factory pattern)", () => {
+		const a = getRuntime();
+		const b = getRuntime();
+		expect(a).not.toBe(b);
+	});
+
+	it("returns PiRuntime when name is 'pi'", () => {
+		const runtime = getRuntime("pi");
+		expect(runtime).toBeInstanceOf(PiRuntime);
+		expect(runtime.id).toBe("pi");
+	});
+
+	it("passes Pi config from AgentplateConfig to PiRuntime", () => {
+		const config = {
+			runtime: {
+				default: "pi",
+				pi: {
+					provider: "amazon-bedrock",
+					modelMap: {
+						opus: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1",
+					},
+				},
+			},
+		} as unknown as AgentplateConfig;
+		const runtime = getRuntime(undefined, config) as PiRuntime;
+		expect(runtime).toBeInstanceOf(PiRuntime);
+		// Verify the config was applied by testing model expansion
+		expect(runtime.expandModel("opus")).toBe("amazon-bedrock/us.anthropic.claude-opus-4-6-v1");
+	});
+
+	it("Pi runtime uses defaults when no Pi config in AgentplateConfig", () => {
+		const config = { runtime: { default: "pi" } } as AgentplateConfig;
+		const runtime = getRuntime(undefined, config) as PiRuntime;
+		expect(runtime).toBeInstanceOf(PiRuntime);
+		// Should use default anthropic mappings
+		expect(runtime.expandModel("sonnet")).toBe("anthropic/claude-sonnet-4-6");
+	});
+
+	it("returns CopilotRuntime when name is 'copilot'", () => {
+		const runtime = getRuntime("copilot");
+		expect(runtime).toBeInstanceOf(CopilotRuntime);
+		expect(runtime.id).toBe("copilot");
+	});
+
+	it("uses config.runtime.default 'copilot' when name is omitted", () => {
+		const config = { runtime: { default: "copilot" } } as AgentplateConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(CopilotRuntime);
+		expect(runtime.id).toBe("copilot");
+	});
+
+	it("copilot runtime returns a new instance on each call", () => {
+		const a = getRuntime("copilot");
+		const b = getRuntime("copilot");
+		expect(a).not.toBe(b);
+	});
+
+	it("returns CursorRuntime when name is 'cursor'", () => {
+		const runtime = getRuntime("cursor");
+		expect(runtime).toBeInstanceOf(CursorRuntime);
+		expect(runtime.id).toBe("cursor");
+	});
+
+	it("uses config.runtime.default 'cursor' when name is omitted", () => {
+		const config = { runtime: { default: "cursor" } } as AgentplateConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(CursorRuntime);
+		expect(runtime.id).toBe("cursor");
+	});
+
+	it("cursor runtime returns a new instance on each call", () => {
+		const a = getRuntime("cursor");
+		const b = getRuntime("cursor");
+		expect(a).not.toBe(b);
+	});
+
+	it("returns GeminiRuntime when name is 'gemini'", () => {
+		const runtime = getRuntime("gemini");
+		expect(runtime).toBeInstanceOf(GeminiRuntime);
+		expect(runtime.id).toBe("gemini");
+	});
+
+	it("uses config.runtime.default 'gemini' when name is omitted", () => {
+		const config = { runtime: { default: "gemini" } } as AgentplateConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(GeminiRuntime);
+		expect(runtime.id).toBe("gemini");
+	});
+
+	it("returns OpenCodeRuntime when name is 'opencode'", () => {
+		const runtime = getRuntime("opencode");
+		expect(runtime).toBeInstanceOf(OpenCodeRuntime);
+		expect(runtime.id).toBe("opencode");
+	});
+
+	it("uses config.runtime.default 'opencode' when name is omitted", () => {
+		const config = { runtime: { default: "opencode" } } as AgentplateConfig;
+		const runtime = getRuntime(undefined, config);
+		expect(runtime).toBeInstanceOf(OpenCodeRuntime);
+		expect(runtime.id).toBe("opencode");
+	});
+
+	it("opencode runtime returns a new instance on each call", () => {
+		const a = getRuntime("opencode");
+		const b = getRuntime("opencode");
+		expect(a).not.toBe(b);
+	});
+
+	describe("capability routing", () => {
+		it("resolves capability-specific runtime from config", () => {
+			const config = {
+				runtime: { default: "claude", capabilities: { builder: "gemini" } },
+			} as unknown as AgentplateConfig;
+			const runtime = getRuntime(undefined, config, "builder");
+			expect(runtime).toBeInstanceOf(GeminiRuntime);
+			expect(runtime.id).toBe("gemini");
+		});
+
+		it("falls back to default when capability has no override", () => {
+			const config = {
+				runtime: { default: "codex", capabilities: { builder: "gemini" } },
+			} as unknown as AgentplateConfig;
+			const runtime = getRuntime(undefined, config, "scout");
+			expect(runtime).toBeInstanceOf(CodexRuntime);
+			expect(runtime.id).toBe("codex");
+		});
+
+		it("explicit name overrides capability routing", () => {
+			const config = {
+				runtime: { default: "claude", capabilities: { builder: "gemini" } },
+			} as unknown as AgentplateConfig;
+			const runtime = getRuntime("copilot", config, "builder");
+			expect(runtime).toBeInstanceOf(CopilotRuntime);
+			expect(runtime.id).toBe("copilot");
+		});
+
+		it("works when capabilities is undefined", () => {
+			const config = { runtime: { default: "claude" } } as AgentplateConfig;
+			const runtime = getRuntime(undefined, config, "coordinator");
+			expect(runtime).toBeInstanceOf(ClaudeRuntime);
+			expect(runtime.id).toBe("claude");
+		});
+	});
+});

package/src/runtimes/registry.ts

@@ -0,0 +1,99 @@
+// Runtime registry — maps runtime names to adapter factory functions.
+// This is the ONLY module that imports concrete adapter classes.
+
+import type { AgentplateConfig } from "../types.ts";
+import { AiderRuntime } from "./aider.ts";
+import { AmpRuntime } from "./amp.ts";
+import { ClaudeRuntime } from "./claude.ts";
+import { CodexRuntime } from "./codex.ts";
+import { CopilotRuntime } from "./copilot.ts";
+import { CursorRuntime } from "./cursor.ts";
+import { GeminiRuntime } from "./gemini.ts";
+import { GooseRuntime } from "./goose.ts";
+import { OpenCodeRuntime } from "./opencode.ts";
+import { PiRuntime } from "./pi.ts";
+import { SaplingRuntime } from "./sapling.ts";
+import type { AgentRuntime } from "./types.ts";
+
+/** Registry of config-independent runtime adapters (name → factory). */
+const runtimes = new Map<string, () => AgentRuntime>([
+	["aider", () => new AiderRuntime()],
+	["amp", () => new AmpRuntime()],
+	["claude", () => new ClaudeRuntime()],
+	["codex", () => new CodexRuntime()],
+	["copilot", () => new CopilotRuntime()],
+	["cursor", () => new CursorRuntime()],
+	["gemini", () => new GeminiRuntime()],
+	["goose", () => new GooseRuntime()],
+	["opencode", () => new OpenCodeRuntime()],
+	["pi", () => new PiRuntime()],
+	["sapling", () => new SaplingRuntime()],
+]);
+
+/**
+ * Return all registered runtime adapter instances.
+ *
+ * Used by callers that need to enumerate all runtimes (e.g. to build a
+ * dynamic list of known instruction file paths from each runtime's
+ * `instructionPath` property).
+ *
+ * @returns Array of one fresh instance per registered runtime.
+ */
+export function getAllRuntimes(): AgentRuntime[] {
+	return [
+		new AiderRuntime(),
+		new AmpRuntime(),
+		new ClaudeRuntime(),
+		new CodexRuntime(),
+		new CopilotRuntime(),
+		new CursorRuntime(),
+		new GeminiRuntime(),
+		new GooseRuntime(),
+		new OpenCodeRuntime(),
+		new PiRuntime(),
+		new SaplingRuntime(),
+	];
+}
+
+/**
+ * Resolve a runtime adapter by name.
+ *
+ * Lookup order:
+ * 1. Explicit `name` argument (if provided)
+ * 2. `config.runtime.capabilities[capability]` (if capability provided)
+ * 3. `config.runtime.default` (if config is provided)
+ * 4. `"claude"` (hardcoded fallback)
+ *
+ * Special cases:
+ * - Pi runtime receives `config.runtime.pi` for model alias expansion.
+ *
+ * @param name - Runtime name to resolve (e.g. "claude"). Omit to use config default.
+ * @param config - Agentplate config for reading the default runtime.
+ * @param capability - Agent capability (e.g. "coordinator", "builder") for per-capability routing.
+ * @throws {Error} If the resolved runtime name is not registered.
+ * @returns A fresh AgentRuntime instance.
+ */
+export function getRuntime(
+	name?: string,
+	config?: AgentplateConfig,
+	capability?: string,
+): AgentRuntime {
+	const capabilityRuntime =
+		capability && config?.runtime?.capabilities
+			? config.runtime.capabilities[capability]
+			: undefined;
+	const runtimeName = name ?? capabilityRuntime ?? config?.runtime?.default ?? "claude";
+
+	// Pi runtime needs config for model alias expansion.
+	if (runtimeName === "pi") {
+		return new PiRuntime(config?.runtime?.pi);
+	}
+
+	const factory = runtimes.get(runtimeName);
+	if (!factory) {
+		throw new Error(
+			`Unknown runtime: "${runtimeName}". Available: ${[...runtimes.keys()].join(", ")}`,
+		);
+	}
+	return factory();
+}