@ag-eco/agentplate-cli 0.13.0

package/src/runtimes/aider.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AiderRuntime } from "./aider.ts";
+
+describe("AiderRuntime", () => {
+	const runtime = new AiderRuntime();
+	let testDir: string;
+
+	beforeEach(async () => {
+		testDir = await mkdtemp(join(tmpdir(), "agentplate-aider-test-"));
+	});
+
+	afterEach(async () => {
+		await rm(testDir, { recursive: true });
+	});
+
+	it("has correct id and instruction path", () => {
+		expect(runtime.id).toBe("aider");
+		expect(runtime.instructionPath).toBe("CONVENTIONS.md");
+	});
+
+	it("buildSpawnCommand includes --yes-always --no-auto-commits and model", () => {
+		const cmd = runtime.buildSpawnCommand({
+			model: "anthropic/claude-sonnet-4-6",
+			permissionMode: "bypass",
+			cwd: "/tmp/test",
+			env: {},
+		});
+		expect(cmd).toContain("aider --yes-always --no-auto-commits");
+		expect(cmd).toContain("--model anthropic/claude-sonnet-4-6");
+	});
+
+	it("buildSpawnCommand includes append system prompt as --message", () => {
+		const cmd = runtime.buildSpawnCommand({
+			model: "sonnet",
+			permissionMode: "bypass",
+			appendSystemPrompt: "You are a scout.",
+			cwd: "/tmp/test",
+			env: {},
+		});
+		expect(cmd).toContain("--message");
+		expect(cmd).toContain("You are a scout.");
+	});
+
+	it("buildSpawnCommand uses --read for appendSystemPromptFile", () => {
+		const cmd = runtime.buildSpawnCommand({
+			model: "sonnet",
+			permissionMode: "bypass",
+			appendSystemPromptFile: "/tmp/role.md",
+			cwd: "/tmp/test",
+			env: {},
+		});
+		expect(cmd).toContain("--read '/tmp/role.md'");
+	});
+
+	it("buildPrintCommand returns correct argv", () => {
+		const argv = runtime.buildPrintCommand("fix the bug");
+		expect(argv[0]).toBe("aider");
+		expect(argv).toContain("--message");
+		expect(argv).toContain("fix the bug");
+		expect(argv).toContain("--yes-always");
+		expect(argv).toContain("--no-auto-commits");
+	});
+
+	it("buildPrintCommand includes model when provided", () => {
+		const argv = runtime.buildPrintCommand("fix the bug", "gpt-4o");
+		expect(argv).toContain("--model");
+		expect(argv).toContain("gpt-4o");
+	});
+
+	it("deployConfig writes CONVENTIONS.md", async () => {
+		await runtime.deployConfig(
+			testDir,
+			{ content: "# Scout instructions" },
+			{
+				agentName: "scout-1",
+				capability: "scout",
+				worktreePath: testDir,
+			},
+		);
+		const content = await readFile(join(testDir, "CONVENTIONS.md"), "utf-8");
+		expect(content).toBe("# Scout instructions");
+	});
+
+	it("deployConfig is no-op when overlay is undefined", async () => {
+		await runtime.deployConfig(testDir, undefined, {
+			agentName: "scout-1",
+			capability: "scout",
+			worktreePath: testDir,
+		});
+		const file = Bun.file(join(testDir, "CONVENTIONS.md"));
+		expect(await file.exists()).toBe(false);
+	});
+
+	it("detectReady recognizes aider prompt", () => {
+		expect(runtime.detectReady("some output\naider> ").phase).toBe("ready");
+		expect(runtime.detectReady("> ").phase).toBe("ready");
+		expect(runtime.detectReady("Loading...").phase).toBe("loading");
+	});
+
+	it("does not require beacon verification", () => {
+		expect(runtime.requiresBeaconVerification()).toBe(false);
+	});
+
+	it("parseTranscript returns null", async () => {
+		expect(await runtime.parseTranscript("/nonexistent")).toBeNull();
+	});
+
+	it("buildEnv returns model env vars", () => {
+		expect(runtime.buildEnv({ model: "sonnet", env: { OPENAI_API_KEY: "sk-test" } })).toEqual({
+			OPENAI_API_KEY: "sk-test",
+		});
+	});
+
+	it("buildEnv returns empty object when no env", () => {
+		expect(runtime.buildEnv({ model: "sonnet" })).toEqual({});
+	});
+
+	it("getTranscriptDir returns null", () => {
+		expect(runtime.getTranscriptDir("/tmp/project")).toBeNull();
+	});
+});

package/src/runtimes/aider.ts

@@ -0,0 +1,147 @@
+// Aider runtime adapter for agentplate's AgentRuntime interface.
+// Implements the AgentRuntime contract for the `aider` CLI (Paul Gauthier's AI pair programming tool).
+//
+// Key differences from Claude/Pi adapters:
+// - Interactive: `aider` stays alive in tmux as a REPL-like session
+// - Instruction file: .aider.conf.yml or CONVENTIONS.md (we use CONVENTIONS.md for overlay)
+// - No hooks: Aider has no PreToolUse/PostToolUse hook system
+// - One-shot calls use `aider --message <prompt> --yes-always`
+// - Model is passed via `--model <model>` (supports litellm model strings)
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ResolvedModel } from "../types.ts";
+import type {
+	AgentRuntime,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/**
+ * Aider runtime adapter.
+ *
+ * Implements AgentRuntime for Paul Gauthier's `aider` CLI. Tmux-spawned
+ * Aider agents run in interactive mode with `--yes-always` for automatic
+ * confirmation of file edits.
+ *
+ * Security relies on Aider's built-in file-scope limiting — it only edits
+ * files explicitly added to its context. No OS-level sandbox or hook guards.
+ */
+export class AiderRuntime implements AgentRuntime {
+	readonly id = "aider";
+
+	/** Experimental — community-contributed adapter, not yet battle-tested in production. */
+	readonly stability = "experimental" as const;
+
+	/**
+	 * Aider reads CONVENTIONS.md from the repo root for project-level instructions.
+	 * We write the overlay here so Aider picks it up natively.
+	 */
+	readonly instructionPath = "CONVENTIONS.md";
+
+	/**
+	 * Build the shell command string to spawn an Aider agent in a tmux pane.
+	 *
+	 * Uses `--yes-always` for automatic approval of file edits and
+	 * `--no-auto-commits` so agentplate controls git operations.
+	 *
+	 * @param opts - Spawn options
+	 * @returns Shell command string suitable for tmux new-session
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		let cmd = "aider --yes-always --no-auto-commits";
+
+		// Aider accepts litellm model strings: provider/model-name
+		cmd += ` --model ${opts.model}`;
+
+		if (opts.appendSystemPromptFile) {
+			const escaped = opts.appendSystemPromptFile.replace(/'/g, "'\\''");
+			cmd += ` --read '${escaped}'`;
+		} else if (opts.appendSystemPrompt) {
+			const escaped = opts.appendSystemPrompt.replace(/'/g, "'\\''");
+			cmd += ` --message '${escaped} Read CONVENTIONS.md for your task assignment and begin.'`;
+		} else {
+			cmd += ` --message 'Read CONVENTIONS.md for your task assignment and begin immediately.'`;
+		}
+
+		return cmd;
+	}
+
+	/**
+	 * Build argv for a headless one-shot Aider invocation.
+	 *
+	 * Uses `--message` for the prompt with `--yes-always` for non-interactive mode.
+	 *
+	 * @param prompt - The prompt to pass
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["aider", "--message", prompt, "--yes-always", "--no-auto-commits"];
+		if (model !== undefined) {
+			cmd.push("--model", model);
+		}
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions to a worktree.
+	 *
+	 * Writes the overlay to CONVENTIONS.md (Aider's native conventions file).
+	 * No hooks or guard extensions — Aider has no hook system.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content, or undefined for no-op
+	 * @param _hooks - Unused — Aider has no hook system
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		_hooks: HooksDef,
+	): Promise<void> {
+		if (!overlay) return;
+		await mkdir(worktreePath, { recursive: true });
+		await Bun.write(join(worktreePath, this.instructionPath), overlay.content);
+	}
+
+	/**
+	 * Detect Aider TUI readiness from tmux pane content.
+	 *
+	 * Aider shows a prompt like "aider>" or "> " when ready for input.
+	 *
+	 * @param paneContent - Captured tmux pane content
+	 * @returns Readiness phase
+	 */
+	detectReady(paneContent: string): ReadyState {
+		// Aider shows its prompt when ready: "aider> " or "> "
+		if (/(?:aider)?>\s*$/.test(paneContent)) {
+			return { phase: "ready" };
+		}
+		return { phase: "loading" };
+	}
+
+	/** Aider does not require beacon verification — accepts input reliably. */
+	requiresBeaconVerification(): boolean {
+		return false;
+	}
+
+	/**
+	 * Aider does not produce machine-readable transcripts.
+	 * Returns null — cost tracking relies on provider billing.
+	 */
+	async parseTranscript(_path: string): Promise<TranscriptSummary | null> {
+		return null;
+	}
+
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return model.env ?? {};
+	}
+
+	/** Aider logs to .aider.chat.history.md but not in a parseable transcript format. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
+}

package/src/runtimes/amp.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AmpRuntime } from "./amp.ts";
+
+describe("AmpRuntime", () => {
+	const runtime = new AmpRuntime();
+	let testDir: string;
+
+	beforeEach(async () => {
+		testDir = await mkdtemp(join(tmpdir(), "agentplate-amp-test-"));
+	});
+
+	afterEach(async () => {
+		await rm(testDir, { recursive: true });
+	});
+
+	it("has correct id and instruction path", () => {
+		expect(runtime.id).toBe("amp");
+		expect(runtime.instructionPath).toBe(".amp/AGENT.md");
+	});
+
+	it("buildSpawnCommand includes --model and --yes", () => {
+		const cmd = runtime.buildSpawnCommand({
+			model: "anthropic/claude-sonnet-4-6",
+			permissionMode: "bypass",
+			cwd: "/tmp/test",
+			env: {},
+		});
+		expect(cmd).toContain("amp --model anthropic/claude-sonnet-4-6 --yes");
+	});
+
+	it("buildSpawnCommand includes append system prompt as --prompt", () => {
+		const cmd = runtime.buildSpawnCommand({
+			model: "sonnet",
+			permissionMode: "bypass",
+			appendSystemPrompt: "You are a reviewer.",
+			cwd: "/tmp/test",
+			env: {},
+		});
+		expect(cmd).toContain("--prompt");
+		expect(cmd).toContain("You are a reviewer.");
+	});
+
+	it("buildSpawnCommand uses cat for appendSystemPromptFile", () => {
+		const cmd = runtime.buildSpawnCommand({
+			model: "sonnet",
+			permissionMode: "bypass",
+			appendSystemPromptFile: "/tmp/role.md",
+			cwd: "/tmp/test",
+			env: {},
+		});
+		expect(cmd).toContain("--prompt");
+		expect(cmd).toContain("cat '/tmp/role.md'");
+	});
+
+	it("buildSpawnCommand includes default prompt when no append", () => {
+		const cmd = runtime.buildSpawnCommand({
+			model: "sonnet",
+			permissionMode: "bypass",
+			cwd: "/tmp/test",
+			env: {},
+		});
+		expect(cmd).toContain("--prompt");
+		expect(cmd).toContain("Read .amp/AGENT.md");
+	});
+
+	it("buildPrintCommand returns correct argv", () => {
+		const argv = runtime.buildPrintCommand("review the diff");
+		expect(argv[0]).toBe("amp");
+		expect(argv).toContain("--prompt");
+		expect(argv).toContain("review the diff");
+		expect(argv).toContain("--no-input");
+		expect(argv).toContain("--yes");
+	});
+
+	it("buildPrintCommand includes model when provided", () => {
+		const argv = runtime.buildPrintCommand("review the diff", "gpt-4o");
+		expect(argv).toContain("--model");
+		expect(argv).toContain("gpt-4o");
+	});
+
+	it("deployConfig writes .amp/AGENT.md", async () => {
+		await runtime.deployConfig(
+			testDir,
+			{ content: "# Reviewer instructions" },
+			{
+				agentName: "reviewer-1",
+				capability: "reviewer",
+				worktreePath: testDir,
+			},
+		);
+		const content = await readFile(join(testDir, ".amp", "AGENT.md"), "utf-8");
+		expect(content).toBe("# Reviewer instructions");
+	});
+
+	it("deployConfig creates parent .amp directory", async () => {
+		await runtime.deployConfig(
+			testDir,
+			{ content: "# Test" },
+			{
+				agentName: "test",
+				capability: "scout",
+				worktreePath: testDir,
+			},
+		);
+		const file = Bun.file(join(testDir, ".amp", "AGENT.md"));
+		expect(await file.exists()).toBe(true);
+	});
+
+	it("deployConfig is no-op when overlay is undefined", async () => {
+		await runtime.deployConfig(testDir, undefined, {
+			agentName: "test",
+			capability: "scout",
+			worktreePath: testDir,
+		});
+		const file = Bun.file(join(testDir, ".amp", "AGENT.md"));
+		expect(await file.exists()).toBe(false);
+	});
+
+	it("detectReady requires both prompt AND branding (AND logic)", () => {
+		// Both prompt and branding → ready
+		expect(runtime.detectReady("some output\namp> ").phase).toBe("ready");
+		expect(runtime.detectReady("amp v1.0.0\n> ").phase).toBe("ready");
+		expect(runtime.detectReady("AMP CLI\n> ").phase).toBe("ready");
+
+		// Prompt only (no branding) → loading
+		expect(runtime.detectReady("some output\n> ").phase).toBe("loading");
+
+		// Branding only (no prompt) → loading
+		expect(runtime.detectReady("amp v1.0.0").phase).toBe("loading");
+		expect(runtime.detectReady("amp v1.2.3 starting...").phase).toBe("loading");
+
+		// Neither → loading
+		expect(runtime.detectReady("Initializing...").phase).toBe("loading");
+
+		// Substring false-positive prevention: "amp" inside other words must NOT match branding
+		expect(runtime.detectReady("this is an example output\n> ").phase).toBe("loading");
+		expect(runtime.detectReady("stamped result\n> ").phase).toBe("loading");
+	});
+
+	it("does not require beacon verification", () => {
+		expect(runtime.requiresBeaconVerification()).toBe(false);
+	});
+
+	it("parseTranscript returns null", async () => {
+		expect(await runtime.parseTranscript("/nonexistent")).toBeNull();
+	});
+
+	it("buildEnv returns model env vars", () => {
+		expect(runtime.buildEnv({ model: "sonnet", env: { SRC_ACCESS_TOKEN: "token" } })).toEqual({
+			SRC_ACCESS_TOKEN: "token",
+		});
+	});
+
+	it("buildEnv returns empty object when no env", () => {
+		expect(runtime.buildEnv({ model: "sonnet" })).toEqual({});
+	});
+
+	it("getTranscriptDir returns null", () => {
+		expect(runtime.getTranscriptDir("/tmp/project")).toBeNull();
+	});
+});

package/src/runtimes/amp.ts

@@ -0,0 +1,154 @@
+// Amp runtime adapter for agentplate's AgentRuntime interface.
+// Implements the AgentRuntime contract for Sourcegraph's `amp` CLI (AI coding agent).
+//
+// Key differences from Claude/Pi adapters:
+// - Interactive: `amp` runs as an interactive chat session in tmux
+// - Instruction file: .amp/AGENT.md (Amp's native instruction file)
+// - No hooks: Amp manages permissions via its own approval system
+// - One-shot calls use `amp --prompt <prompt> --no-input`
+// - Model is passed via `--model <model>`
+
+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";
+
+/**
+ * Amp runtime adapter.
+ *
+ * Implements AgentRuntime for Sourcegraph's `amp` CLI. Amp agents run
+ * as interactive chat sessions with configurable models and tools.
+ *
+ * Security is managed by Amp's built-in approval system for file
+ * modifications and command execution.
+ */
+export class AmpRuntime implements AgentRuntime {
+	readonly id = "amp";
+
+	/** Experimental — community-contributed adapter, not yet battle-tested in production. */
+	readonly stability = "experimental" as const;
+
+	/**
+	 * Amp reads .amp/AGENT.md from the repo for project-level instructions.
+	 */
+	readonly instructionPath = ".amp/AGENT.md";
+
+	/**
+	 * Build the shell command string to spawn an Amp agent in a tmux pane.
+	 *
+	 * Uses `amp` in interactive mode with `--model` for model selection
+	 * and `--yes` for automatic approval.
+	 *
+	 * @param opts - Spawn options
+	 * @returns Shell command string suitable for tmux new-session
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		let cmd = `amp --model ${opts.model} --yes`;
+
+		if (opts.appendSystemPromptFile) {
+			const escaped = opts.appendSystemPromptFile.replace(/'/g, "'\\''");
+			cmd += ` --prompt "$(cat '${escaped}') Read .amp/AGENT.md for your task assignment."`;
+		} else if (opts.appendSystemPrompt) {
+			const escaped =
+				`${opts.appendSystemPrompt}\n\nRead .amp/AGENT.md for your task assignment and begin.`.replace(
+					/'/g,
+					"'\\''",
+				);
+			cmd += ` --prompt '${escaped}'`;
+		} else {
+			cmd += ` --prompt 'Read .amp/AGENT.md for your task assignment and begin immediately.'`;
+		}
+
+		return cmd;
+	}
+
+	/**
+	 * Build argv for a headless one-shot Amp invocation.
+	 *
+	 * Uses `amp --prompt <prompt> --no-input --yes` for non-interactive execution.
+	 *
+	 * @param prompt - The prompt to pass
+	 * @param model - Optional model override
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["amp", "--prompt", prompt, "--no-input", "--yes"];
+		if (model !== undefined) {
+			cmd.push("--model", model);
+		}
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions to a worktree.
+	 *
+	 * Writes the overlay to .amp/AGENT.md (Amp's native instruction file).
+	 * No hooks — Amp manages approvals internally.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content, or undefined for no-op
+	 * @param _hooks - Unused — Amp has no hook system
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		_hooks: HooksDef,
+	): Promise<void> {
+		if (!overlay) return;
+		const agentPath = join(worktreePath, this.instructionPath);
+		await mkdir(dirname(agentPath), { recursive: true });
+		await Bun.write(agentPath, overlay.content);
+	}
+
+	/**
+	 * Detect Amp TUI readiness from tmux pane content.
+	 *
+	 * Amp shows a prompt indicator when ready for input.
+	 *
+	 * @param paneContent - Captured tmux pane content
+	 * @returns Readiness phase
+	 */
+	detectReady(paneContent: string): ReadyState {
+		const lower = paneContent.toLowerCase();
+
+		// Prompt indicator: ">" or "amp>" at end of a line
+		const hasPrompt = /(?:amp)?>\s*$/.test(paneContent);
+
+		// Branding indicator: "amp" as a standalone word (word boundary prevents
+		// matching inside "example", "stamp", "&amp;", etc.)
+		const hasBranding = /\bamp\b/.test(lower);
+
+		// Both required (AND logic) to prevent premature ready detection
+		// during startup messages like "amp v1.2.3 starting..."
+		if (hasPrompt && hasBranding) {
+			return { phase: "ready" };
+		}
+		return { phase: "loading" };
+	}
+
+	/** Amp does not require beacon verification. */
+	requiresBeaconVerification(): boolean {
+		return false;
+	}
+
+	/** Amp does not produce machine-readable transcripts. */
+	async parseTranscript(_path: string): Promise<TranscriptSummary | null> {
+		return null;
+	}
+
+	buildEnv(model: ResolvedModel): Record<string, string> {
+		return model.env ?? {};
+	}
+
+	/** Amp does not expose a transcript directory. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
+}