@ag-eco/agentplate-cli 0.13.0

package/src/commands/agents.test.ts

@@ -0,0 +1,328 @@
+/**
+ * Tests for the agents command.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createSessionStore } from "../sessions/store.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
+import type { AgentSession } from "../types.ts";
+import { agentsCommand, discoverAgents, extractFileScope } from "./agents.ts";
+
+describe("extractFileScope", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "agentplate-test-"));
+	});
+
+	it("should return empty array when overlay doesn't exist", async () => {
+		const scope = await extractFileScope(tempDir);
+		expect(scope).toEqual([]);
+	});
+
+	it("should return empty array when 'No file scope restrictions'", async () => {
+		const overlayPath = join(tempDir, ".claude", "CLAUDE.md");
+		const content = `# Agent Overlay
+
+## File Scope (exclusive ownership)
+
+No file scope restrictions. You may modify any file in the worktree.
+
+## Expertise
+
+Some expertise here.
+`;
+		await Bun.write(overlayPath, content);
+		const scope = await extractFileScope(tempDir);
+		expect(scope).toEqual([]);
+	});
+
+	it("should extract file paths from valid overlay", async () => {
+		const overlayPath = join(tempDir, ".claude", "CLAUDE.md");
+		const content = `# Agent Overlay
+
+## File Scope (exclusive ownership)
+
+These files are yours to modify:
+
+- \`src/commands/agents.ts\`
+- \`src/commands/agents.test.ts\`
+- \`src/index.ts\`
+
+## Expertise
+
+Some expertise here.
+`;
+		await Bun.write(overlayPath, content);
+		const scope = await extractFileScope(tempDir);
+		expect(scope).toEqual([
+			"src/commands/agents.ts",
+			"src/commands/agents.test.ts",
+			"src/index.ts",
+		]);
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+});
+
+describe("discoverAgents", () => {
+	let tempDir: string;
+	let dbPath: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "agentplate-test-"));
+		const agentplateDir = join(tempDir, ".agentplate");
+		await Bun.write(join(agentplateDir, ".gitkeep"), "");
+		dbPath = join(agentplateDir, "sessions.db");
+	});
+
+	it("should return empty when no sessions", async () => {
+		const store = createSessionStore(dbPath);
+		store.close();
+
+		const agents = await discoverAgents(tempDir);
+		expect(agents).toEqual([]);
+	});
+
+	it("should return active agents", async () => {
+		const store = createSessionStore(dbPath);
+
+		const session: AgentSession = {
+			id: "session-1",
+			agentName: "builder-test",
+			capability: "builder",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "builder-test"),
+			branchName: "agentplate/builder-test/task-123",
+			taskId: "task-123",
+			tmuxSession: "agentplate-test-builder",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+
+		store.upsert(session);
+		store.close();
+
+		const agents = await discoverAgents(tempDir);
+		expect(agents).toHaveLength(1);
+		expect(agents[0]?.agentName).toBe("builder-test");
+		expect(agents[0]?.capability).toBe("builder");
+		expect(agents[0]?.state).toBe("working");
+	});
+
+	it("should filter by capability", async () => {
+		const store = createSessionStore(dbPath);
+
+		const builder: AgentSession = {
+			id: "session-1",
+			agentName: "builder-test",
+			capability: "builder",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "builder-test"),
+			branchName: "agentplate/builder-test/task-123",
+			taskId: "task-123",
+			tmuxSession: "agentplate-test-builder",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+
+		const scout: AgentSession = {
+			id: "session-2",
+			agentName: "scout-test",
+			capability: "scout",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "scout-test"),
+			branchName: "agentplate/scout-test/task-456",
+			taskId: "task-456",
+			tmuxSession: "agentplate-test-scout",
+			state: "working",
+			pid: 12346,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+
+		store.upsert(builder);
+		store.upsert(scout);
+		store.close();
+
+		const agents = await discoverAgents(tempDir, { capability: "builder" });
+		expect(agents).toHaveLength(1);
+		expect(agents[0]?.agentName).toBe("builder-test");
+		expect(agents[0]?.capability).toBe("builder");
+	});
+
+	it("should includeAll returns completed agents too", async () => {
+		const store = createSessionStore(dbPath);
+
+		const working: AgentSession = {
+			id: "session-1",
+			agentName: "builder-working",
+			capability: "builder",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "builder-working"),
+			branchName: "agentplate/builder-working/task-123",
+			taskId: "task-123",
+			tmuxSession: "agentplate-test-working",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:01:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+
+		const completed: AgentSession = {
+			id: "session-2",
+			agentName: "builder-completed",
+			capability: "builder",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "builder-completed"),
+			branchName: "agentplate/builder-completed/task-456",
+			taskId: "task-456",
+			tmuxSession: "agentplate-test-completed",
+			state: "completed",
+			pid: null,
+			parentAgent: null,
+			depth: 0,
+			runId: "run-1",
+			startedAt: "2024-01-01T00:00:00Z",
+			lastActivity: "2024-01-01T00:02:00Z",
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+
+		store.upsert(working);
+		store.upsert(completed);
+		store.close();
+
+		// Without includeAll, only active agents
+		const activeAgents = await discoverAgents(tempDir);
+		expect(activeAgents).toHaveLength(1);
+		expect(activeAgents[0]?.agentName).toBe("builder-working");
+
+		// With includeAll, both working and completed
+		const allAgents = await discoverAgents(tempDir, { includeAll: true });
+		expect(allAgents).toHaveLength(2);
+		const names = allAgents.map((a) => a.agentName);
+		expect(names).toContain("builder-working");
+		expect(names).toContain("builder-completed");
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+});
+
+describe("agentsCommand", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalStdoutWrite: typeof process.stdout.write;
+	let stdoutBuffer: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "agentplate-test-"));
+		const agentplateDir = join(tempDir, ".agentplate");
+
+		// Create config.yaml
+		const configContent = `project:
+  name: test-project
+  root: ${tempDir}
+  canonicalBranch: main
+agents:
+  manifestPath: .agentplate/agent-manifest.json
+  baseDir: agents
+  maxConcurrent: 5
+  staggerDelayMs: 100
+  maxDepth: 2
+worktrees:
+  baseDir: .agentplate/worktrees
+beads:
+  enabled: true
+loam:
+  enabled: true
+  domains: []
+  primeFormat: markdown
+merge:
+  aiResolveEnabled: false
+  reimagineEnabled: false
+watchdog:
+  tier0Enabled: false
+  tier0IntervalMs: 30000
+  tier1Enabled: false
+  tier2Enabled: false
+  staleThresholdMs: 300000
+  zombieThresholdMs: 600000
+  nudgeIntervalMs: 60000
+logging:
+  verbose: false
+  redactSecrets: true
+`;
+		await Bun.write(join(agentplateDir, "config.yaml"), configContent);
+
+		// Create sessions.db
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+		store.close();
+
+		// Mock stdout.write
+		stdoutBuffer = "";
+		originalStdoutWrite = process.stdout.write;
+		process.stdout.write = mock((chunk: unknown) => {
+			stdoutBuffer += String(chunk);
+			return true;
+		});
+
+		// Change to temp dir
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+	});
+
+	it("should show help with --help flag", async () => {
+		await agentsCommand(["--help"]);
+		expect(stdoutBuffer).toContain("agents");
+		expect(stdoutBuffer).toContain("discover");
+	});
+
+	it("should show help with no subcommand", async () => {
+		await agentsCommand([]);
+		expect(stdoutBuffer).toContain("agents");
+		expect(stdoutBuffer).toContain("discover");
+	});
+
+	it("should error on unknown subcommand", async () => {
+		await expect(agentsCommand(["unknown"])).rejects.toThrow("unknown command");
+	});
+
+	afterEach(async () => {
+		process.stdout.write = originalStdoutWrite;
+		process.chdir(originalCwd);
+		await cleanupTempDir(tempDir);
+	});
+});

package/src/commands/agents.ts

@@ -0,0 +1,299 @@
+/**
+ * CLI command: ap agents <sub> [--json]
+ *
+ * Discover and query agents by capability.
+ */
+
+import { join } from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { accent, color } from "../logging/color.ts";
+import { getAllRuntimes, getRuntime } from "../runtimes/registry.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import { type AgentSession, SUPPORTED_CAPABILITIES } from "../types.ts";
+
+/**
+ * Discovered agent information including file scope.
+ */
+export interface DiscoveredAgent {
+	agentName: string;
+	capability: string;
+	state: string;
+	taskId: string;
+	branchName: string;
+	parentAgent: string | null;
+	depth: number;
+	fileScope: string[];
+	startedAt: string;
+	lastActivity: string;
+}
+
+/** Build the list of known instruction file paths from all registered runtimes. */
+function getKnownInstructionPaths(): string[] {
+	return [...new Set(getAllRuntimes().map((r) => r.instructionPath))];
+}
+
+/**
+ * Extract file scope from an agent's overlay instruction file.
+ * Returns empty array if no overlay exists, has no file scope restrictions,
+ * or can't be read.
+ *
+ * @param worktreePath - Absolute path to the agent's worktree
+ * @param runtimeInstructionPath - Optional runtime-specific instruction path to try first
+ * @returns Array of file paths (relative to worktree root)
+ */
+export async function extractFileScope(
+	worktreePath: string,
+	runtimeInstructionPath?: string,
+): Promise<string[]> {
+	try {
+		let content: string | null = null;
+		const knownPaths = getKnownInstructionPaths();
+		const pathsToTry = runtimeInstructionPath
+			? [runtimeInstructionPath, ...knownPaths]
+			: knownPaths;
+		for (const relPath of pathsToTry) {
+			const overlayPath = join(worktreePath, relPath);
+			const overlayFile = Bun.file(overlayPath);
+			if (await overlayFile.exists()) {
+				content = await overlayFile.text();
+				break;
+			}
+		}
+		if (content === null) {
+			return [];
+		}
+
+		// Find the section between "## File Scope (exclusive ownership)" and "## Expertise"
+		const startMarker = "## File Scope (exclusive ownership)";
+		const endMarker = "## Expertise";
+
+		const startIdx = content.indexOf(startMarker);
+		if (startIdx === -1) {
+			return [];
+		}
+
+		const endIdx = content.indexOf(endMarker, startIdx);
+		if (endIdx === -1) {
+			return [];
+		}
+
+		const section = content.slice(startIdx, endIdx);
+
+		// Check for "No file scope restrictions"
+		if (section.includes("No file scope restrictions")) {
+			return [];
+		}
+
+		// Extract file paths from markdown list items: - `path`
+		const paths: string[] = [];
+		const regex = /^- `(.+)`$/gm;
+		let match = regex.exec(section);
+
+		while (match !== null) {
+			if (match[1]) {
+				paths.push(match[1]);
+			}
+			match = regex.exec(section);
+		}
+
+		return paths;
+	} catch {
+		// Best effort: return empty array if anything fails
+		return [];
+	}
+}
+
+/**
+ * Discover agents in the project.
+ *
+ * @param root - Absolute path to project root
+ * @param opts - Filter options
+ * @returns Array of discovered agents with file scopes
+ */
+export async function discoverAgents(
+	root: string,
+	opts?: { capability?: string; includeAll?: boolean },
+): Promise<DiscoveredAgent[]> {
+	const agentplateDir = join(root, ".agentplate");
+	const { store } = openSessionStore(agentplateDir);
+
+	// Resolve runtime instruction path from config; fall back gracefully if config is absent.
+	let runtimeInstructionPath: string | undefined;
+	try {
+		const config = await loadConfig(root);
+		const runtime = getRuntime(undefined, config);
+		runtimeInstructionPath = runtime.instructionPath;
+	} catch {
+		// Config may not exist in all contexts; KNOWN_INSTRUCTION_PATHS will be used as fallback.
+	}
+
+	try {
+		const sessions: AgentSession[] = opts?.includeAll ? store.getAll() : store.getActive();
+
+		// Filter by capability if specified
+		let filteredSessions = sessions;
+		if (opts?.capability) {
+			filteredSessions = sessions.filter((s) => s.capability === opts.capability);
+		}
+
+		// Extract file scopes for each agent
+		const agents: DiscoveredAgent[] = await Promise.all(
+			filteredSessions.map(async (session) => {
+				const fileScope = await extractFileScope(session.worktreePath, runtimeInstructionPath);
+				return {
+					agentName: session.agentName,
+					capability: session.capability,
+					state: session.state,
+					taskId: session.taskId,
+					branchName: session.branchName,
+					parentAgent: session.parentAgent,
+					depth: session.depth,
+					fileScope,
+					startedAt: session.startedAt,
+					lastActivity: session.lastActivity,
+				};
+			}),
+		);
+
+		return agents;
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Format the state icon for display.
+ *
+ * `in_turn` and `between_turns` (agentplate-3087) render with the same cyan
+ * accent as `working` so a spawn-per-turn worker is visually grouped with
+ * other healthy/active agents in `ap agents` output. They use distinct
+ * glyphs ('>' vs '~') to mirror the dashboard / theme.ts mapping.
+ */
+function getStateIcon(state: string): string {
+	switch (state) {
+		case "working":
+			return color.cyan(">");
+		case "in_turn":
+			return color.cyan(">");
+		case "between_turns":
+			return color.cyan("~");
+		case "booting":
+			return color.green("-");
+		case "stalled":
+			return color.yellow("!");
+		default:
+			return " ";
+	}
+}
+
+/**
+ * Print discovered agents in human-readable format.
+ */
+function printAgents(agents: DiscoveredAgent[]): void {
+	const w = process.stdout.write.bind(process.stdout);
+
+	if (agents.length === 0) {
+		w("No agents found.\n");
+		return;
+	}
+
+	w(`Found ${agents.length} agent${agents.length === 1 ? "" : "s"}:\n\n`);
+
+	for (const agent of agents) {
+		const icon = getStateIcon(agent.state);
+		w(`  ${icon} ${accent(agent.agentName)} [${agent.capability}]\n`);
+		w(`    State: ${agent.state} | Task: ${accent(agent.taskId)}\n`);
+		w(`    Branch: ${accent(agent.branchName)}\n`);
+		w(
+			`    Parent: ${agent.parentAgent ? accent(agent.parentAgent) : "none"} | Depth: ${agent.depth}\n`,
+		);
+
+		if (agent.fileScope.length === 0) {
+			w("    Files: (unrestricted)\n");
+		} else {
+			w(`    Files: ${agent.fileScope.join(", ")}\n`);
+		}
+
+		w("\n");
+	}
+}
+
+/**
+ * Create the Commander command for `ap agents`.
+ */
+export function createAgentsCommand(): Command {
+	const cmd = new Command("agents").description("Discover and query agents");
+
+	cmd
+		.command("discover")
+		.description("Find active agents by capability")
+		.option(
+			"--capability <type>",
+			"Filter by capability (builder, scout, reviewer, lead, merger, orchestrator, coordinator, supervisor)",
+		)
+		.option("--all", "Include completed and zombie agents (default: active only)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { capability?: string; all?: boolean; json?: boolean }) => {
+			const capability = opts.capability;
+
+			// Validate capability if provided
+			if (capability && !SUPPORTED_CAPABILITIES.includes(capability as never)) {
+				throw new ValidationError(
+					`Invalid capability: ${capability}. Must be one of: ${SUPPORTED_CAPABILITIES.join(", ")}`,
+					{
+						field: "capability",
+						value: capability,
+					},
+				);
+			}
+
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			const root = config.project.root;
+
+			const agents = await discoverAgents(root, {
+				capability,
+				includeAll: opts.all ?? false,
+			});
+
+			if (opts.json) {
+				jsonOutput("agents discover", { agents });
+			} else {
+				printAgents(agents);
+			}
+		});
+
+	return cmd;
+}
+
+/**
+ * Entry point for `ap agents <subcommand>`.
+ */
+export async function agentsCommand(args: string[]): Promise<void> {
+	const cmd = createAgentsCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
+		return;
+	}
+
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
+	}
+}