@ag-eco/agentplate-cli 0.13.0

package/src/runtimes/claude.ts

@@ -0,0 +1,579 @@
+// Claude Code runtime adapter for agentplate's AgentRuntime interface.
+// Pure extraction — no new behavior. All implementation delegates to existing code.
+// Phase 0: file exists and compiles. Callers are not rewired until Phase 2.
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { deployHooks } from "../agents/hooks-deployer.ts";
+import { estimateCost } from "../metrics/pricing.ts";
+import { parseTranscriptUsage } from "../metrics/transcript.ts";
+import type { ResolvedModel } from "../types.ts";
+import type {
+	AgentEvent,
+	AgentRuntime,
+	DirectSpawnOpts,
+	HooksDef,
+	OverlayContent,
+	ReadyState,
+	SpawnOpts,
+	TranscriptSummary,
+} from "./types.ts";
+
+/**
+ * Claude Code runtime adapter.
+ *
+ * Implements AgentRuntime for the `claude` CLI (Anthropic's Claude Code).
+ * All methods delegate to existing agentplate subsystems — this adapter
+ * only provides the runtime-agnostic interface layer.
+ *
+ * Phase 0: file exists, compiles, and exports the class.
+ * Phase 2 will rewire callers (sling.ts, coordinator.ts, etc.) to use this adapter.
+ */
+export class ClaudeRuntime implements AgentRuntime {
+	/** Unique identifier for this runtime. */
+	readonly id = "claude";
+
+	/** Stability level. Claude Code is the primary runtime. */
+	readonly stability = "stable" as const;
+
+	/** Relative path to the instruction file within a worktree. */
+	readonly instructionPath = ".claude/CLAUDE.md";
+
+	/**
+	 * Build the shell command string to spawn an interactive Claude Code agent.
+	 *
+	 * Maps SpawnOpts to the `claude` CLI flags:
+	 * - `model` → `--model <model>`
+	 * - `permissionMode` → `--permission-mode <mode>`
+	 *   - "bypass" maps to "bypassPermissions"
+	 *   - "ask" maps to "default"
+	 * - `appendSystemPrompt` → `--append-system-prompt '<escaped>'`
+	 *
+	 * The returned string is passed directly to tmux as the initial command.
+	 * The `cwd` and `env` fields of SpawnOpts are handled by the tmux session
+	 * creator, not embedded in the command string.
+	 *
+	 * @param opts - Spawn options (model, permissionMode, appendSystemPrompt)
+	 * @returns Shell command string suitable for tmux new-session -c
+	 */
+	buildSpawnCommand(opts: SpawnOpts): string {
+		const permMode = opts.permissionMode === "bypass" ? "bypassPermissions" : "default";
+		let cmd = `claude --model ${opts.model} --permission-mode ${permMode}`;
+
+		if (opts.appendSystemPromptFile) {
+			// Read from file at shell expansion time — avoids tmux IPC message size
+			// limits (~8-16KB) that cause "command too long" errors when large agent
+			// definitions are inlined. The $(cat ...) expands inside the tmux pane's
+			// shell, so the tmux IPC message only carries the short command string.
+			const escaped = opts.appendSystemPromptFile.replace(/'/g, "'\\''");
+			cmd += ` --append-system-prompt "$(cat '${escaped}')"`;
+		} else if (opts.appendSystemPrompt) {
+			// Single-quote the content for safe shell expansion.
+			// POSIX single-quoted strings cannot contain single quotes, so escape
+			// them using the standard technique: end quote, escaped 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 Claude invocation.
+	 *
+	 * Returns an argv array suitable for `Bun.spawn()`. The `--print` flag
+	 * causes Claude Code to run the prompt and exit, writing output to stdout.
+	 *
+	 * Used by merge/resolver.ts (AI-assisted conflict resolution) and
+	 * watchdog/triage.ts (AI-assisted failure classification).
+	 *
+	 * @param prompt - The prompt to pass via `-p`
+	 * @param model - Optional model override (omit to use Claude Code's default)
+	 * @returns Argv array for Bun.spawn
+	 */
+	buildPrintCommand(prompt: string, model?: string): string[] {
+		const cmd = ["claude", "--print", "-p", prompt];
+		if (model !== undefined) {
+			cmd.push("--model", model);
+		}
+		return cmd;
+	}
+
+	/**
+	 * Deploy per-agent instructions and guards to a worktree.
+	 *
+	 * For Claude Code this means writes to the worktree's `.claude/` directory:
+	 * 1. `CLAUDE.md` — the agent's task-specific overlay (generated by ap sling).
+	 *    Skipped when overlay is undefined (hooks-only deployment for coordinator/supervisor/monitor).
+	 * 2. `settings.local.json` — Claude Code hooks for security guards
+	 *
+	 * The `overlay.content` is written verbatim when provided. The hooks are generated by
+	 * `deployHooks()` from `src/agents/hooks-deployer.ts`.
+	 *
+	 * @param worktreePath - Absolute path to the agent's git worktree
+	 * @param overlay - Overlay content to write as CLAUDE.md, or undefined for hooks-only deployment
+	 * @param hooks - Hook definition used by deployHooks
+	 * @throws {AgentError} If the hooks template is missing or writes fail
+	 */
+	async deployConfig(
+		worktreePath: string,
+		overlay: OverlayContent | undefined,
+		hooks: HooksDef,
+	): Promise<void> {
+		if (overlay) {
+			const claudeDir = join(worktreePath, ".claude");
+			await mkdir(claudeDir, { recursive: true });
+
+			const claudeMdPath = join(claudeDir, "CLAUDE.md");
+			await Bun.write(claudeMdPath, overlay.content);
+		}
+
+		// Always deploy hooks — headless Claude Code DOES dispatch settings.local.json
+		// PreToolUse hooks (verified empirically against `claude -p --output-format stream-json`).
+		// The original design (agentplate-1c32 / docs/headless-hooks-design.md Q6) wrongly assumed
+		// hooks don't fire in headless mode and skipped deployment, leaving headless agents with
+		// none of the destructive-command guards. agentplate-e24b reverses that: in headless mode
+		// we deploy a settings.local.json containing only PreToolUse security guards (path boundary,
+		// capability blocks, bash danger patterns, tracker close, lead close gate). The other
+		// hook types are dropped because they have headless equivalents already wired up
+		// (initial stdin prompt, serve mail injection loop, stream-json event capture).
+		await deployHooks(
+			hooks.worktreePath,
+			hooks.agentName,
+			hooks.capability,
+			hooks.qualityGates,
+			hooks.isHeadless ?? false,
+		);
+	}
+
+	/**
+	 * Detect Claude Code TUI readiness from a tmux pane content snapshot.
+	 *
+	 * Uses the same heuristics as `waitForTuiReady()` in `src/worktree/tmux.ts`,
+	 * but operates on a pre-captured pane string rather than polling tmux directly.
+	 * The caller is responsible for capturing pane content and acting on the result
+	 * (e.g. sending "Enter" to dismiss a trust dialog).
+	 *
+	 * Detection phases:
+	 * - Trust dialog: "trust this folder" detected → `{ phase: "dialog", action: "Enter" }`
+	 * - Ready: prompt indicator (❯ or 'Try "') AND status bar ("bypass permissions")
+	 *   both present → `{ phase: "ready" }`
+	 * - Otherwise → `{ phase: "loading" }`
+	 *
+	 * @param paneContent - Captured tmux pane content to analyze
+	 * @returns Current readiness phase
+	 */
+	detectReady(paneContent: string): ReadyState {
+		// Claude Code v2.1.71+ shows a dedicated bypass confirmation screen.
+		// It already contains both a prompt marker and the phrase "bypass permissions",
+		// so it must be detected before the normal ready heuristics.
+		if (
+			paneContent.includes("WARNING: Claude Code running in Bypass Permissions mode") &&
+			paneContent.includes("1. No, exit") &&
+			paneContent.includes("2. Yes, I accept")
+		) {
+			return { phase: "dialog", action: "type:2" };
+		}
+
+		// Trust dialog takes precedence — it replaces the normal TUI temporarily.
+		// The caller should send the action key to dismiss it.
+		if (paneContent.includes("trust this folder")) {
+			return { phase: "dialog", action: "Enter" };
+		}
+
+		// Phase 1: prompt indicator confirms Claude Code has started.
+		// ❯ is the claude prompt character; 'Try "' appears in the welcome banner.
+		const hasPrompt = paneContent.includes("\u276f") || paneContent.includes('Try "');
+
+		// Phase 2: status bar text confirms full TUI render.
+		// Only match 'bypass permissions' — 'shift+tab' appears in ALL Claude Code sessions
+		// regardless of permission mode and would cause false-positive ready detection.
+		const hasStatusBar = paneContent.includes("bypass permissions");
+
+		if (hasPrompt && hasStatusBar) {
+			return { phase: "ready" };
+		}
+
+		return { phase: "loading" };
+	}
+
+	/**
+	 * Parse a Claude Code transcript JSONL file into normalized token usage.
+	 *
+	 * Reads the JSONL file at `path` and aggregates token usage across all
+	 * assistant turns. Returns null if the file does not exist or cannot be read.
+	 *
+	 * Delegates to `parseTranscriptUsage()` and `estimateCost()` from
+	 * `src/metrics/transcript.ts`. The `estimatedCostUsd` is computed but
+	 * not exposed here because `TranscriptSummary` only carries the three
+	 * core fields (inputTokens, outputTokens, model). Cost data is available
+	 * via `src/metrics/transcript.ts` directly for callers that need it.
+	 *
+	 * @param path - Absolute path to the 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 usage = await parseTranscriptUsage(path);
+			// estimateCost is called to validate the model is recognized,
+			// though the result is not surfaced in TranscriptSummary.
+			if (usage.modelUsed !== null) {
+				estimateCost(usage);
+			}
+			return {
+				inputTokens: usage.inputTokens,
+				outputTokens: usage.outputTokens,
+				model: usage.modelUsed ?? "",
+			};
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Build the argv array for Bun.spawn() to launch a Claude Code agent in headless mode.
+	 *
+	 * Returns the exact flags Multica uses for headless Claude Code sessions:
+	 * `-p --output-format stream-json --input-format stream-json --verbose
+	 * --strict-mcp-config --permission-mode bypassPermissions [--model <m>]`
+	 *
+	 * Claude Code reads `.claude/CLAUDE.md` from cwd automatically — do NOT
+	 * pass `--append-system-prompt` or consume `opts.instructionPath`.
+	 * The initial stdin prompt is the caller's responsibility.
+	 *
+	 * @param opts - Direct spawn options; only `model` is consumed
+	 * @returns Argv array for Bun.spawn — do not shell-interpolate
+	 */
+	buildDirectSpawn(opts: DirectSpawnOpts): string[] {
+		const argv = [
+			"claude",
+			"-p",
+			"--output-format",
+			"stream-json",
+			"--input-format",
+			"stream-json",
+			"--verbose",
+			"--strict-mcp-config",
+			"--permission-mode",
+			"bypassPermissions",
+		];
+		if (opts.model !== undefined) {
+			argv.push("--model", opts.model);
+		}
+		// Phase 1 (agentplate-b835): emit --resume on follow-up spawns. Mirrors
+		// multica/server/pkg/agent/claude.go:434 (positional). Empty string and
+		// null are treated as "no resume" — only non-empty strings activate it.
+		if (typeof opts.resumeSessionId === "string" && opts.resumeSessionId.length > 0) {
+			argv.push("--resume", opts.resumeSessionId);
+		}
+		return argv;
+	}
+
+	/**
+	 * Parse stream-json stdout from a Claude Code headless subprocess into typed AgentEvent objects.
+	 *
+	 * Reads the ReadableStream from Bun.spawn() stdout, buffers partial lines,
+	 * and yields a typed AgentEvent for each complete JSON line. Malformed lines
+	 * and unknown message types are silently skipped.
+	 *
+	 * Adjacent assistant_text deltas are coalesced into a single assistant_message
+	 * event using a batching window. The batch flushes on timer expiry, size cap,
+	 * any non-text event, or stream end — whichever comes first.
+	 *
+	 * Event mapping (Claude stream-json → AgentEvent):
+	 * - assistant/text     → buffered; emitted as one assistant_message per batch
+	 * - assistant/tool_use → { type: "tool_use", callId, name, input }
+	 * - assistant/thinking → (skipped)
+	 * - user/tool_result   → { type: "tool_result", toolUseId, content }
+	 * - system             → { type: "status", sessionId, subtype }
+	 * - result             → { type: "result", sessionId, result, isError, durationMs, numTurns }
+	 *
+	 * @param stream - ReadableStream<Uint8Array> from Bun.spawn stdout
+	 * @param opts - Optional hooks and tuning:
+	 *   - `onSessionId` is invoked once, synchronously, on the first event that carries a
+	 *     non-empty `sessionId`. Consumer errors are swallowed so they cannot crash the parser.
+	 *   - `flushIntervalMs` — Max ms to buffer text before emitting (default 500).
+	 *   - `flushSizeBytes` — Max UTF-8 byte size of a text batch (default 4096).
+	 * @yields Parsed AgentEvent objects in emission order
+	 */
+	async *parseEvents(
+		stream: ReadableStream<Uint8Array>,
+		opts?: {
+			onSessionId?: (sessionId: string) => void;
+			flushIntervalMs?: number;
+			flushSizeBytes?: number;
+		},
+	): AsyncIterable<AgentEvent> {
+		const flushIntervalMs = opts?.flushIntervalMs ?? 500;
+		const flushSizeBytes = opts?.flushSizeBytes ?? 4096;
+
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+		let sessionIdPinned = false;
+
+		// Batch state for adjacent assistant_text deltas.
+		let pendingText: string[] = [];
+		let pendingByteSize = 0;
+		let pendingStartTs: string | null = null;
+		let pendingModel: string | undefined;
+		let pendingUsage: unknown;
+
+		// Returns batched assistant_message event and resets state; null when buffer is empty.
+		const flushText = (): AgentEvent | null => {
+			if (pendingText.length === 0) return null;
+			const text = pendingText.join("");
+			const event: AgentEvent = {
+				type: "assistant_message",
+				timestamp: pendingStartTs ?? new Date().toISOString(),
+				text,
+			};
+			if (pendingModel !== undefined) event.model = pendingModel;
+			if (pendingUsage !== undefined) event.usage = pendingUsage;
+			pendingText = [];
+			pendingByteSize = 0;
+			pendingStartTs = null;
+			pendingModel = undefined;
+			pendingUsage = undefined;
+			return event;
+		};
+
+		// Sync generator: parses one JSON line, yielding AgentEvents in order.
+		// Mutates batch state via closure — do not call concurrently.
+		function* processLine(line: string): Generator<AgentEvent> {
+			const trimmed = line.trim();
+			if (!trimmed) return;
+
+			let msg: Record<string, unknown>;
+			try {
+				msg = JSON.parse(trimmed) as Record<string, unknown>;
+			} catch {
+				return;
+			}
+
+			const timestamp = new Date().toISOString();
+
+			if (msg.type === "assistant") {
+				const message =
+					typeof msg.message === "object" && msg.message !== null
+						? (msg.message as Record<string, unknown>)
+						: null;
+				if (!message) return;
+				const content = Array.isArray(message.content) ? message.content : [];
+				const model = typeof message.model === "string" ? message.model : undefined;
+				const usage = message.usage !== undefined ? message.usage : undefined;
+
+				for (const block of content) {
+					if (typeof block !== "object" || block === null) continue;
+					const b = block as Record<string, unknown>;
+					if (b.type === "text") {
+						const text = typeof b.text === "string" ? b.text : String(b.text);
+						const textByteSize = new TextEncoder().encode(text).byteLength;
+
+						// Size-cap: if appending would exceed cap and buffer is non-empty, flush first.
+						if (pendingByteSize > 0 && pendingByteSize + textByteSize > flushSizeBytes) {
+							const ev = flushText();
+							if (ev) yield ev;
+						}
+
+						// Record the start-of-batch timestamp on the first fragment.
+						if (pendingByteSize === 0) pendingStartTs = timestamp;
+
+						pendingText.push(text);
+						pendingByteSize += textByteSize;
+						// Latest contributing message wins for model/usage.
+						if (model !== undefined) pendingModel = model;
+						if (usage !== undefined) pendingUsage = usage;
+
+						// Immediate flush when a single fragment meets or exceeds the size cap.
+						if (pendingByteSize >= flushSizeBytes) {
+							const ev = flushText();
+							if (ev) yield ev;
+						}
+					} else if (b.type === "tool_use") {
+						// Non-text block: flush pending text first to preserve in-order delivery.
+						const ev = flushText();
+						if (ev) yield ev;
+						yield {
+							type: "tool_use",
+							timestamp,
+							callId: b.id,
+							name: b.name,
+							input: b.input,
+						};
+					}
+					// thinking and other block types → skip
+				}
+			} else if (msg.type === "user") {
+				const message =
+					typeof msg.message === "object" && msg.message !== null
+						? (msg.message as Record<string, unknown>)
+						: null;
+				if (!message) return;
+				const content = Array.isArray(message.content) ? message.content : [];
+
+				const flushEv = flushText();
+				if (flushEv) yield flushEv;
+
+				for (const block of content) {
+					if (typeof block !== "object" || block === null) continue;
+					const b = block as Record<string, unknown>;
+					if (b.type === "tool_result") {
+						yield {
+							type: "tool_result",
+							timestamp,
+							toolUseId: b.tool_use_id,
+							content: b.content,
+						};
+					}
+				}
+			} else if (msg.type === "system") {
+				const flushEv = flushText();
+				if (flushEv) yield flushEv;
+				yield { type: "status", timestamp, sessionId: msg.session_id, subtype: msg.subtype };
+			} else if (msg.type === "result") {
+				const flushEv = flushText();
+				if (flushEv) yield flushEv;
+				yield {
+					type: "result",
+					timestamp,
+					sessionId: msg.session_id,
+					result: msg.result,
+					isError: msg.is_error,
+					durationMs: msg.duration_ms,
+					numTurns: msg.num_turns,
+				};
+			}
+		}
+
+		const maybePinSession = (event: AgentEvent): void => {
+			if (sessionIdPinned || !opts?.onSessionId) return;
+			const sid = event.sessionId;
+			if (typeof sid !== "string" || sid.length === 0) return;
+			sessionIdPinned = true;
+			try {
+				opts.onSessionId(sid);
+			} catch {
+				// Consumer errors must not crash the parser.
+			}
+		};
+
+		try {
+			// Use the inferred return type of reader.read() to stay compatible with
+			// both the standard Web Streams API and Bun's slightly divergent typings.
+			type ReadResult = Awaited<ReturnType<typeof reader.read>>;
+			type Race = { kind: "read"; result: ReadResult } | { kind: "timeout" };
+
+			let readPromise = reader.read();
+
+			while (true) {
+				if (pendingText.length > 0 && pendingStartTs !== null) {
+					// Race the next read chunk against the flush timer.
+					const elapsed = Date.now() - new Date(pendingStartTs).getTime();
+					const remaining = Math.max(0, flushIntervalMs - elapsed);
+
+					let timerId: ReturnType<typeof setTimeout> | undefined;
+					const wrappedRead: Promise<Race> = readPromise.then((result) => ({
+						kind: "read" as const,
+						result,
+					}));
+					const wrappedTimer = new Promise<Race>((resolve) => {
+						timerId = setTimeout(() => resolve({ kind: "timeout" }), remaining);
+					});
+
+					const winner = await Promise.race([wrappedRead, wrappedTimer]);
+					if (timerId !== undefined) clearTimeout(timerId);
+
+					if (winner.kind === "timeout") {
+						const ev = flushText();
+						if (ev) yield ev;
+						continue; // readPromise still in flight — re-enter loop without refreshing
+					}
+
+					const result = winner.result;
+					if (result.done) break;
+					buffer += decoder.decode(result.value, { stream: true });
+					const lines = buffer.split("\n");
+					buffer = lines.pop() ?? "";
+					for (const line of lines) {
+						for (const event of processLine(line)) {
+							maybePinSession(event);
+							yield event;
+						}
+					}
+					readPromise = reader.read();
+				} else {
+					const result = await readPromise;
+					if (result.done) break;
+					buffer += decoder.decode(result.value, { stream: true });
+					const lines = buffer.split("\n");
+					// Last element is either empty or an incomplete line — keep in buffer.
+					buffer = lines.pop() ?? "";
+					for (const line of lines) {
+						for (const event of processLine(line)) {
+							maybePinSession(event);
+							yield event;
+						}
+					}
+					readPromise = reader.read();
+				}
+			}
+
+			// Flush remaining buffer on clean stream end (no trailing newline).
+			if (buffer.trim()) {
+				for (const event of processLine(buffer)) {
+					maybePinSession(event);
+					yield event;
+				}
+			}
+
+			// Drain any remaining buffered text after the read loop exits.
+			const finalEv = flushText();
+			if (finalEv) yield finalEv;
+		} finally {
+			reader.releaseLock();
+		}
+	}
+
+	/**
+	 * Build runtime-specific environment variables for model/provider routing.
+	 *
+	 * Returns the provider environment variables from the resolved model.
+	 * For Anthropic native: may include ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL.
+	 * For gateway providers: may include gateway-specific auth and routing vars.
+	 *
+	 * Returns an empty object if the resolved model has no provider env vars.
+	 * Callers (sling.ts, coordinator.ts) merge this with AGENTPLATE_AGENT_NAME
+	 * and AGENTPLATE_WORKTREE_PATH before passing to createSession().
+	 *
+	 * @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 Claude Code transcript directory for a given project root.
+	 *
+	 * Claude Code stores session transcripts at ~/.claude/projects/<projectKey>/
+	 * where <projectKey> is the project root path with "/" replaced by "-".
+	 *
+	 * @param projectRoot - Absolute path to the project root
+	 * @returns Absolute path to the transcript directory, or null if HOME is unavailable
+	 */
+	getTranscriptDir(projectRoot: string): string | null {
+		const home = process.env.HOME ?? "";
+		if (home.length === 0) return null;
+		const projectKey = projectRoot.replace(/\//g, "-");
+		return join(home, ".claude", "projects", projectKey);
+	}
+}
+
+/** Singleton instance for use in callers that do not need DI. */
+export const claudeRuntime = new ClaudeRuntime();