@fred-drake/anvil 0.0.1

package/src/subagent/herdr.ts

@@ -0,0 +1,142 @@
+/**
+ * Herdr backend for Anvil's declarative subagent steps.
+ *
+ * Herdr panes are the terminal surfaces. The first subagent creates a right
+ * split beside the current Pi pane; later subagents open labelled tabs in the
+ * same workspace so the layout does not keep shrinking. Completion detection is
+ * shared with cmux via the `.exit` sidecar and terminal sentinel poller.
+ */
+import { execFile } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { promisify } from "node:util";
+import { shellEscape } from "../shell.ts";
+import { pollForExitWithReadScreen } from "./exit.ts";
+import type { SubagentExit } from "./exit.ts";
+
+const execFileAsync = promisify(execFile);
+
+/** Workspace used for Anvil subagent tabs after the initial split. */
+let subagentWorkspace: string | null = null;
+
+export { shellEscape };
+
+export function isHerdrAvailable(): boolean {
+	return process.env.HERDR_ENV === "1" && Boolean(process.env.HERDR_PANE_ID);
+}
+
+export function herdrUnavailableMessage(): string {
+	return 'herdr is not available. Start pi inside herdr to run workflows with `delegation: { subagent: "herdr" }`.';
+}
+
+async function runHerdr(args: string[]): Promise<string> {
+	const { stdout } = await execFileAsync(process.env.HERDR_BIN_PATH ?? "herdr", args, { encoding: "utf8" });
+	return stdout;
+}
+
+function parseJsonOutput(output: string, command: string): Record<string, unknown> {
+	try {
+		const parsed = JSON.parse(output);
+		if (parsed && typeof parsed === "object") return parsed as Record<string, unknown>;
+	} catch {}
+	throw new Error(`Unexpected herdr ${command} output: ${output.trim()}`);
+}
+
+function getPath(record: unknown, path: string[]): unknown {
+	let current = record;
+	for (const part of path) {
+		if (!current || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[part];
+	}
+	return current;
+}
+
+function parseCreatedPane(output: string, command: string, candidatePaths: string[][]): string {
+	const parsed = parseJsonOutput(output, command);
+	for (const path of candidatePaths) {
+		const value = getPath(parsed, path);
+		if (typeof value === "string" && value.trim()) return value;
+	}
+	throw new Error(`Unexpected herdr ${command} output: missing pane_id in ${output.trim()}`);
+}
+
+function inferWorkspaceId(paneId: string | undefined): string | undefined {
+	if (!paneId) return undefined;
+	const match = paneId.match(/^(\d+)[-:]/);
+	return match?.[1];
+}
+
+async function createSplitSurface(name: string): Promise<string> {
+	const stdout = await runHerdr(["pane", "split", "--current", "--direction", "right", "--no-focus"]);
+	const paneId = parseCreatedPane(stdout, "pane split", [
+		["result", "pane", "pane_id"],
+		["result", "root_pane", "pane_id"],
+		["pane", "pane_id"],
+		["pane_id"],
+	]);
+	await runHerdr(["pane", "rename", paneId, name]);
+	// Empty string means "ask Herdr to use the current workspace" when no stable id is available.
+	subagentWorkspace = process.env.HERDR_WORKSPACE_ID || inferWorkspaceId(process.env.HERDR_PANE_ID) || inferWorkspaceId(paneId) || "";
+	return paneId;
+}
+
+async function createTabSurface(name: string, workspace: string): Promise<string> {
+	const args = ["tab", "create"];
+	if (workspace) args.push("--workspace", workspace);
+	args.push("--label", name, "--no-focus");
+	const stdout = await runHerdr(args);
+	return parseCreatedPane(stdout, "tab create", [
+		["result", "root_pane", "pane_id"],
+		["result", "pane", "pane_id"],
+		["root_pane", "pane_id"],
+		["pane", "pane_id"],
+		["pane_id"],
+	]);
+}
+
+/**
+ * Create a Herdr pane for a subagent. The first call creates a right split;
+ * subsequent calls create labelled tabs in the same workspace.
+ */
+export async function createSurface(name: string): Promise<string> {
+	if (subagentWorkspace !== null) return createTabSurface(name, subagentWorkspace);
+	return createSplitSurface(name);
+}
+
+/**
+ * Send a command by writing it to a script file and executing that script in
+ * the pane, so long commands survive terminal line-wrapping.
+ */
+export async function sendLongCommand(surface: string, command: string, scriptPath: string): Promise<void> {
+	mkdirSync(dirname(scriptPath), { recursive: true });
+	writeFileSync(scriptPath, `#!/bin/bash\n${command}\n`, { mode: 0o600 });
+	await runHerdr(["pane", "run", surface, `bash ${shellEscape(scriptPath)}`]);
+}
+
+export async function readScreen(surface: string, lines = 5): Promise<string> {
+	return runHerdr(["pane", "read", surface, "--source", "recent-unwrapped", "--lines", String(lines)]);
+}
+
+export function pollForExit(
+	surface: string,
+	sessionFile: string,
+	signal?: AbortSignal,
+	intervalMs?: number,
+	timeoutMs?: number,
+): Promise<SubagentExit> {
+	const readForPoll = (pane: string, lines = 5) => readScreen(pane, Math.max(lines, 20));
+	return pollForExitWithReadScreen(readForPoll, surface, sessionFile, signal, intervalMs, timeoutMs);
+}
+
+export async function closeSurface(surface: string): Promise<void> {
+	await runHerdr(["pane", "close", surface]);
+}
+
+function resetState(): void {
+	subagentWorkspace = null;
+}
+
+export const __testing__ = { resetState };
+
+// Keep the shared exit type visible from this backend for parity with cmux.
+export type { SubagentExit };

package/src/subagent/runner.ts

@@ -0,0 +1,178 @@
+/**
+ * Launches a declaratively-delegated workflow step as a pi subagent in a
+ * terminal-multiplexer surface, waits for it to finish, and extracts the final
+ * assistant message as the step summary.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as cmux from "./cmux.ts";
+import * as herdr from "./herdr.ts";
+import { shellEscape, SUBAGENT_SENTINEL_PREFIX, type SubagentExit } from "./cmux.ts";
+
+export interface SubagentLaunch {
+	/** Display name for the subagent terminal surface. */
+	name: string;
+	/** Full task prompt for the subagent. */
+	task: string;
+	/** Working directory the subagent starts in. */
+	cwd: string;
+	runId: string;
+	stepId: string;
+	/** Pi model reference (provider/id) for the child session. */
+	model?: string;
+	thinkingLevel?: string;
+	timeoutMs?: number;
+}
+
+export interface SubagentResult {
+	summary: string;
+	sessionFile: string;
+	exitCode: number;
+	errorMessage?: string;
+}
+
+const CHILD_EXTENSION_PATH = join(dirname(fileURLToPath(import.meta.url)), "child.ts");
+
+export function buildSubagentLaunchCommand(args: {
+	cwd: string;
+	sessionFile: string;
+	taskFile: string;
+	model?: string;
+	thinkingLevel?: string;
+	childExtensionPath?: string;
+}): string {
+	const parts = [
+		"pi",
+		"--print",
+		"--session",
+		shellEscape(args.sessionFile),
+		"-e",
+		shellEscape(args.childExtensionPath ?? CHILD_EXTENSION_PATH),
+	];
+	if (args.model) parts.push("--model", shellEscape(args.model));
+	if (args.thinkingLevel) parts.push("--thinking", shellEscape(args.thinkingLevel));
+	parts.push(shellEscape(`@${args.taskFile}`));
+
+	const envPrefix = `PI_ANVIL_SUBAGENT_SESSION=${shellEscape(args.sessionFile)} `;
+	return `cd ${shellEscape(args.cwd)} && ${envPrefix}${parts.join(" ")}; echo '${SUBAGENT_SENTINEL_PREFIX}'$?'__'`;
+}
+
+export function extractLastAssistantText(sessionFile: string): string | undefined {
+	if (!existsSync(sessionFile)) return undefined;
+	let last: string | undefined;
+	for (const line of readFileSync(sessionFile, "utf8").split("\n")) {
+		if (!line.trim()) continue;
+		let entry: { type?: string; message?: { role?: string; content?: unknown } };
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+		const content = entry.message.content;
+		const text = Array.isArray(content)
+			? content
+					.filter((block): block is { type: string; text: string } => block?.type === "text" && typeof block.text === "string")
+					.map((block) => block.text)
+					.join("\n")
+					.trim()
+			: "";
+		if (text) last = text;
+	}
+	return last;
+}
+
+interface SubagentBackendAdapter {
+	isAvailable(): boolean;
+	unavailableMessage(): string;
+	createSurface(name: string): Promise<string>;
+	sendLongCommand(surface: string, command: string, scriptPath: string): Promise<void>;
+	pollForExit(surface: string, sessionFile: string, signal?: AbortSignal, intervalMs?: number, timeoutMs?: number): Promise<SubagentExit>;
+	closeSurface(surface: string): Promise<void>;
+}
+
+/* v8 ignore start -- launches real multiplexer/pi child processes; command building and summary extraction are covered separately. */
+export async function runCmuxSubagent(launch: SubagentLaunch, signal?: AbortSignal): Promise<SubagentResult> {
+	return runSubagentWithBackend(
+		launch,
+		{
+			isAvailable: cmux.isCmuxAvailable,
+			unavailableMessage: cmux.cmuxUnavailableMessage,
+			createSurface: cmux.createSurface,
+			sendLongCommand: cmux.sendLongCommand,
+			pollForExit: cmux.pollForExit,
+			closeSurface: cmux.closeSurface,
+		},
+		signal,
+	);
+}
+
+export async function runHerdrSubagent(launch: SubagentLaunch, signal?: AbortSignal): Promise<SubagentResult> {
+	return runSubagentWithBackend(
+		launch,
+		{
+			isAvailable: herdr.isHerdrAvailable,
+			unavailableMessage: herdr.herdrUnavailableMessage,
+			createSurface: herdr.createSurface,
+			sendLongCommand: herdr.sendLongCommand,
+			pollForExit: herdr.pollForExit,
+			closeSurface: herdr.closeSurface,
+		},
+		signal,
+	);
+}
+
+async function runSubagentWithBackend(
+	launch: SubagentLaunch,
+	backend: SubagentBackendAdapter,
+	signal?: AbortSignal,
+): Promise<SubagentResult> {
+	if (!backend.isAvailable()) throw new Error(backend.unavailableMessage());
+
+	const rootDir = join(tmpdir(), "anvil");
+	mkdirSync(rootDir, { recursive: true, mode: 0o700 });
+	chmodSync(rootDir, 0o700);
+	const workDir = join(rootDir, launch.runId);
+	mkdirSync(workDir, { recursive: true, mode: 0o700 });
+	chmodSync(workDir, 0o700);
+	const base = join(workDir, `${sanitizeForFilename(launch.stepId)}-${Date.now().toString(36)}`);
+	const sessionFile = `${base}.jsonl`;
+	const taskFile = `${base}.task.md`;
+	writeFileSync(taskFile, launch.task, "utf8");
+
+	const command = buildSubagentLaunchCommand({
+		cwd: launch.cwd,
+		sessionFile,
+		taskFile,
+		model: launch.model,
+		thinkingLevel: launch.thinkingLevel,
+	});
+
+	const surface = await backend.createSurface(launch.name);
+	try {
+		await backend.sendLongCommand(surface, command, `${base}.sh`);
+		const exit = await backend.pollForExit(surface, sessionFile, signal, undefined, launch.timeoutMs);
+		const summary =
+			extractLastAssistantText(sessionFile) ??
+			(exit.errorMessage
+				? `Subagent error: ${exit.errorMessage}`
+				: exit.exitCode !== 0
+					? `Subagent exited with code ${exit.exitCode}`
+					: "Subagent exited without output.");
+		return { summary, sessionFile, exitCode: exit.exitCode, errorMessage: exit.errorMessage };
+	} finally {
+		try {
+			await backend.closeSurface(surface);
+		} catch {
+			// Surface may already be gone.
+		}
+	}
+}
+/* v8 ignore stop */
+
+/* v8 ignore next -- only used by ignored real-process launcher. */
+function sanitizeForFilename(value: string): string {
+	return value.replace(/[^a-zA-Z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "step";
+}

package/src/types.ts

@@ -0,0 +1,122 @@
+export interface WorkflowContext {
+	/** Free-form text from `/anvil run <name> ...`. */
+	input: string;
+	step: { id: string; index: number };
+	/** "<checkId>-><stepId>" -> count. */
+	loopCounts: Record<string, number>;
+	cwd: string;
+}
+
+export type Templatable = string | ((ctx: WorkflowContext) => string | Promise<string>);
+
+export type WorkflowThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export type OnFailPolicy =
+	| "stop"
+	| "continue"
+	| {
+			goto: string;
+			/** Defaults to workflow.defaults.maxLoops ?? 3. */
+			maxLoops?: number;
+			/** Defaults to "stop". */
+			onExhausted?: "stop" | "continue";
+			/** Defaults to true. */
+			feedback?: boolean;
+	  };
+
+/** Terminal-multiplexer backend Anvil can spawn subagent sessions in. */
+export type WorkflowSubagentBackend = "cmux" | "herdr";
+
+export type WorkflowDelegation =
+	| "auto"
+	| "none"
+	| {
+			/** Pi skill name to prefer when delegating this workflow/step. */
+			skill: string;
+	  }
+	| {
+			/** Anvil spawns the step itself in a dedicated subagent session on this backend. */
+			subagent: WorkflowSubagentBackend;
+	  };
+
+export interface DeterministicCheck {
+	type: "deterministic";
+	id?: string;
+	name?: string;
+	/** Executed with `bash -c`; exit code 0 means pass. */
+	command: Templatable;
+	cwd?: string;
+	/** Defaults to 300_000. */
+	timeoutMs?: number;
+	onFail?: OnFailPolicy;
+}
+
+export interface AgentCheck {
+	type: "agent";
+	id?: string;
+	name?: string;
+	/** Evaluation criteria; anvil wraps this with verdict instructions. */
+	prompt: Templatable;
+	/** Subagent to delegate evaluation to; omit for main-agent evaluation. */
+	agent?: string;
+	onFail?: OnFailPolicy;
+}
+
+export type Check = DeterministicCheck | AgentCheck;
+
+export interface WorkflowModelSelection {
+	/** Model reference. Supports pi's provider/id and optional :<thinking> shorthand. */
+	model?: string;
+	/** Thinking level. Omitted values keep the workflow-start or base step default. */
+	thinkingLevel?: WorkflowThinkingLevel;
+}
+
+export interface WorkflowRetryModelSelection extends WorkflowModelSelection {
+	/** Retry count threshold where this selection begins applying; 0 is the first attempt. */
+	retry: number;
+}
+
+export interface WorkflowStep {
+	id: string;
+	title?: string;
+	prompt: Templatable;
+	/** Model reference for this step. Supports pi's provider/id and optional :<thinking> shorthand. */
+	model?: string;
+	/** Thinking level for this step. Omitted steps use the workflow-start default. */
+	thinkingLevel?: WorkflowThinkingLevel;
+	/** Retry-based model/thinking overrides. Highest retry <= current retry count wins. */
+	retryModelSelections?: WorkflowRetryModelSelection[];
+	/** Preferred per-step delegation mode; overrides workflow.defaults.delegation. */
+	delegation?: WorkflowDelegation;
+	/** Timeout for declarative subagent execution. Defaults to 1_800_000ms. */
+	subagentTimeoutMs?: number;
+	/** Legacy delegation hint. Prefer delegation: { skill: "..." } or delegation: "auto". */
+	agent?: string;
+	/** Main agent does the work itself. */
+	runInMain?: boolean;
+	skipIf?: (ctx: WorkflowContext) => boolean | Promise<boolean>;
+	checks?: Check[];
+	/** Default for this step's checks. */
+	onFail?: OnFailPolicy;
+}
+
+export interface WorkflowDefinition {
+	/** Must match /^[a-z0-9-]+$/. */
+	name: string;
+	description?: string;
+	defaults?: {
+		/** Preferred workflow-wide delegation mode; defaults to auto-detected delegation. */
+		delegation?: WorkflowDelegation;
+		/** Default timeout for declarative subagent execution. Defaults to 1_800_000ms. */
+		subagentTimeoutMs?: number;
+		/** Legacy delegation hint. Prefer delegation: { skill: "..." } or delegation: "auto". */
+		agent?: string;
+		onFail?: OnFailPolicy;
+		maxLoops?: number;
+	};
+	steps: WorkflowStep[];
+}
+
+export function defineWorkflow(def: WorkflowDefinition): WorkflowDefinition {
+	return def;
+}

package/src/ui.ts

@@ -0,0 +1,94 @@
+import type { RunSummary, StepRunState } from "./engine.ts";
+
+export interface StatusInfo {
+	workflowName: string;
+	stepIndex?: number;
+	stepTotal?: number;
+	stepTitle?: string;
+	phase: "starting" | "step" | "check" | "loop" | "done" | "failed" | "aborted";
+	checkIndex?: number;
+	checkTotal?: number;
+	checkName?: string;
+}
+
+export function formatStatus(info: StatusInfo): string | undefined {
+	if (info.phase === "done") return `anvil: ${info.workflowName} done`;
+	if (info.phase === "failed") return `anvil: ${info.workflowName} failed`;
+	if (info.phase === "aborted") return undefined;
+	if (info.phase === "starting") return `anvil: ${info.workflowName} starting`;
+
+	const step =
+		info.stepIndex !== undefined && info.stepTotal !== undefined
+			? `${info.stepIndex + 1}/${info.stepTotal}`
+			: "?/?";
+	const title = info.stepTitle ?? "step";
+	if (info.phase === "check") {
+		const check =
+			info.checkIndex !== undefined && info.checkTotal !== undefined
+				? ` — check ${info.checkIndex + 1}/${info.checkTotal}`
+				: " — check";
+		return `anvil: ${step} ${title}${check}${info.checkName ? ` (${info.checkName})` : ""}`;
+	}
+	if (info.phase === "loop") return `anvil: ${step} ${title} — retrying`;
+	return `anvil: ${step} ${title}`;
+}
+
+export function formatStepWidget(steps: StepRunState[], currentStepId?: string): string[] | undefined {
+	if (steps.length === 0) return undefined;
+	return steps.map((step) => {
+		const icon = iconForStep(step, currentStepId);
+		const loopSuffix = step.loops > 0 ? ` ↻(${step.loops})` : "";
+		const title = step.title ? ` — ${step.title}` : "";
+		const checkSummary = step.checks.length > 0 ? ` [${step.checks.filter((c) => c.pass).length}/${step.checks.length} checks]` : "";
+		return `${icon} ${step.id}${title}${loopSuffix}${checkSummary}`;
+	});
+}
+
+export function renderSummaryMarkdown(summary: RunSummary): string {
+	const stateIcon = summary.state === "succeeded" ? "✅" : summary.state === "failed" ? "❌" : "⏹";
+	const lines = [
+		`${stateIcon} **Anvil workflow \`${summary.workflowName}\` ${summary.state}**`,
+		"",
+		`Run ID: \`${summary.runId}\``,
+		"",
+		"| Step | Status | Checks |",
+		"| --- | --- | --- |",
+	];
+
+	for (const step of summary.steps) {
+		const checks = step.checks.length === 0
+			? "—"
+			: step.checks
+					.map((check) => `${check.pass ? "✔" : "✖"} ${escapePipes(check.name)}${check.pass ? "" : ` — ${escapePipes(check.reason)}`}`)
+					.join("<br>");
+		lines.push(`| \`${escapePipes(step.id)}\` | ${step.status}${step.loops ? ` ↻ ${step.loops}` : ""} | ${checks} |`);
+	}
+
+	if (summary.failureReason) {
+		lines.push("", `Failure: ${summary.failureReason}`);
+	}
+
+	return lines.join("\n");
+}
+
+function iconForStep(step: StepRunState, currentStepId?: string): string {
+	if (step.id === currentStepId && step.status === "running") return "▶";
+	switch (step.status) {
+		case "passed":
+			return "✔";
+		case "failed":
+			return "✖";
+		case "skipped":
+			return "↷";
+		case "continued":
+			return "⚠";
+		case "running":
+			return "▶";
+		default:
+			return "○";
+	}
+}
+
+function escapePipes(text: string): string {
+	return text.replaceAll("|", "\\|").replaceAll("\n", " ");
+}