@agentplate/cli 1.1.0 → 1.3.0

package/src/agents/turn-runner.ts

@@ -23,6 +23,8 @@ export interface RunTurnOptions {
 	env?: Record<string, string>;
 	/** Prior runtime session id, to resume across turns. */
 	resumeSessionId?: string;
+	/** Hard wall-clock cap in ms; the child is killed past it. 0/undefined = none. */
+	timeoutMs?: number;
 	/** Called for each parsed event (e.g. to record tool calls). */
 	onEvent?: (event: AgentEvent) => void;
 }
@@ -33,6 +35,8 @@ export interface TurnResult {
 	runtimeSessionId: string | null;
 	/** Captured stderr (already bounded by the child). */
 	stderr: string;
+	/** True if the turn was killed by the wall-clock cap. */
+	timedOut: boolean;
 }
 
 /** Run a single headless turn and resolve when the child process exits. */
@@ -59,6 +63,18 @@ export async function runTurn(opts: RunTurnOptions): Promise<TurnResult> {
 		stdin: "ignore",
 	});
 
+	// Hard wall-clock cap: kill a turn that runs past the limit even if it keeps
+	// streaming (idle reaping only catches inactivity). Closing the child's pipes
+	// ends the drain/parse loops below, so the turn resolves with a non-zero exit.
+	let timedOut = false;
+	const timer =
+		opts.timeoutMs && opts.timeoutMs > 0
+			? setTimeout(() => {
+					timedOut = true;
+					proc.kill(); // SIGTERM
+				}, opts.timeoutMs)
+			: null;
+
 	// Read stderr concurrently so a full pipe buffer can't deadlock the child.
 	const stderrPromise = new Response(proc.stderr).text();
 
@@ -75,5 +91,6 @@ export async function runTurn(opts: RunTurnOptions): Promise<TurnResult> {
 
 	const stderr = await stderrPromise;
 	const exitCode = await proc.exited;
-	return { exitCode, runtimeSessionId, stderr };
+	if (timer) clearTimeout(timer);
+	return { exitCode, runtimeSessionId, stderr, timedOut };
 }

package/src/commands/sling.ts

@@ -6,36 +6,35 @@
  * the agent identity + session row → dispatch the task over mail → run the first
  * headless turn → observe the agent's terminal mail to transition the session.
  *
- * Headless spawn-per-turn: this runs the FIRST turn. Subsequent turns are driven
- * by new mail (a later refinement); the basic core proves the single-turn loop.
+ * Headless spawn-per-turn: this runs the FIRST turn (a fresh runtime session).
+ * Follow-up turns are run by `agentplate turn <agent>`, which resumes the same
+ * session (warm start). Both share the {@link driveTurn} core.
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { Command } from "commander";
-import { createIdentity, updateIdentity } from "../agents/identity.ts";
+import { assertCapacity } from "../agents/capacity.ts";
+import { driveTurn } from "../agents/drive.ts";
+import { createIdentity } from "../agents/identity.ts";
 import { buildDefaultManifest, getDefinition, loadManifest } from "../agents/manifest.ts";
 import { writeOverlay } from "../agents/overlay.ts";
-import { runTurn } from "../agents/turn-runner.ts";
 import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
-import { runQualityGates } from "../insights/quality-gates.ts";
 import { jsonOutput } from "../json.ts";
 import { brand, muted, printHint, printInfo, printSuccess } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
-import { createMailStore } from "../mail/store.ts";
 import {
 	currentRunPath,
 	eventsDbPath,
-	mailDbPath,
 	manifestFilePath,
 	packageAgentDefPath,
 	sessionsDbPath,
 } from "../paths.ts";
-import { getRuntime } from "../runtimes/registry.ts";
+import { getRuntime, runtimeNameForCapability } from "../runtimes/registry.ts";
 import { resolveModel } from "../runtimes/resolve.ts";
 import { createSessionStore } from "../sessions/store.ts";
-import { retrieveSkillsForSpawn, runSkillFeedbackAndDistill } from "../skills/lifecycle.ts";
+import { retrieveSkillsForSpawn } from "../skills/lifecycle.ts";
 import type { AgentManifest, AgentSession, Capability, OverlayConfig } from "../types.ts";
 import { SUPPORTED_CAPABILITIES } from "../types.ts";
 import { createWorktree } from "../worktree/manager.ts";
@@ -130,6 +129,17 @@ export function createSlingCommand(): Command {
 				// Resolve the run this agent belongs to.
 				const runId = resolveRun(store, root, opts);
 
+				// Enforce orchestration capacity BEFORE any worktree/session is created,
+				// so a runaway fan-out is refused cleanly instead of spawning unbounded.
+				const parentAgent = opts.parent ?? null;
+				assertCapacity({
+					depth: Number(opts.depth ?? "0"),
+					active: store.countActive(runId),
+					parentAgent,
+					parentActiveChildren: parentAgent ? store.countActiveByParent(parentAgent, runId) : 0,
+					limits: config.agents,
+				});
+
 				const name = uniqueName(store, opts.name ?? `${capability}-${taskId}`);
 				const branchName = `agentplate/${name}`;
 
@@ -149,7 +159,18 @@ export function createSlingCommand(): Command {
 				});
 
 				// 3. Overlay (base definition + assignment + skills) → instruction file.
-				const runtime = getRuntime(opts.runtime ?? config.runtime.default, config.runtime.default);
+				const runtime = getRuntime(
+					runtimeNameForCapability(config.runtime, capability, opts.runtime),
+					config.runtime.default,
+				);
+				// Surface project skip-defaults as constraints the spawning agent obeys.
+				const skipDirectives: string[] = [];
+				if (def.canSpawn && config.agents.skipScout) {
+					skipDirectives.push("Skip the scout step — dispatch builders directly (--skip-scout).");
+				}
+				if (def.canSpawn && config.agents.skipReview) {
+					skipDirectives.push("Skip the reviewer step before integrating (--skip-review).");
+				}
 				const overlayConfig: OverlayConfig = {
 					agentName: name,
 					capability,
@@ -163,7 +184,7 @@ export function createSlingCommand(): Command {
 					baseDefinition: readBaseDefinition(root, def.file),
 					canSpawn: def.canSpawn,
 					qualityGates: config.project.qualityGates ?? [],
-					constraints: def.constraints,
+					constraints: [...def.constraints, ...skipDirectives],
 					siblings: opts.siblings ? opts.siblings.split(",").map((s) => s.trim()) : undefined,
 					skillsOverlay: skillsOverlay || undefined,
 				};
@@ -199,91 +220,22 @@ export function createSlingCommand(): Command {
 					type: "dispatch",
 				});
 
-				// 5. Run the first headless turn.
-				const resolved = resolveModel(config, root, def.model);
-				store.updateSessionState(session.id, "working");
+				// 5. Run the first turn. Follow-up turns warm-start (resume) via
+				//    `agentplate turn`; driveTurn owns state + skills + auto-merge.
+				const resolved = resolveModel(config, root, def.model, capability);
 				const prompt = buildInitialPrompt(mail.checkInject(name), runtime.instructionPath);
-				let sawError = false;
-				const turn = await runTurn({
+				const { finalState, exitCode } = await driveTurn({
+					root,
+					config,
 					runtime,
-					worktreePath: worktree.path,
-					model: resolved.model,
+					store,
+					events,
+					mail,
+					session,
+					model: resolved,
 					prompt,
-					env: resolved.env,
-					onEvent: (event) => {
-						if (event.error || event.type === "error") sawError = true;
-						// Prefer the error message (so a failed agent's reason is visible in
-						// the feed/logs), else the token/cost JSON the Costs page aggregates.
-						const detail = event.error
-							? event.error
-							: event.usage
-								? JSON.stringify({ tokens: event.usage.tokens, cost: event.usage.costUsd })
-								: null;
-						events.record({
-							agentName: name,
-							runId,
-							type: event.type,
-							tool: event.tool ?? null,
-							detail,
-						});
-						// Bump last_activity on every streamed event so a long but active
-						// turn keeps itself fresh and is never reaped as "idle".
-						store.touch(session.id);
-					},
-				});
-				if (turn.runtimeSessionId) store.setRuntimeSessionId(session.id, turn.runtimeSessionId);
-
-				// A non-zero exit with no error event means the runtime failed via stderr
-				// (e.g. Pi's "No API key found for anthropic"). Record that stderr so the
-				// failure reason is visible in the feed/logs instead of a blank "failed".
-				if (turn.exitCode !== 0 && !sawError) {
-					const reason = turn.stderr.trim();
-					if (reason) {
-						events.record({
-							agentName: name,
-							runId,
-							type: "error",
-							tool: null,
-							detail: reason.length > 1000 ? `${reason.slice(0, 1000)}…` : reason,
-						});
-					}
-				}
-
-				// 6. Observe terminal mail to transition the session.
-				const finalState = resolveFinalState(root, name, capability, turn.exitCode);
-				store.updateSessionState(session.id, finalState);
-				store.touch(session.id);
-				updateIdentity(root, name, {
-					taskId,
-					summary: `${capability} ran a turn for ${taskId} → ${finalState}`,
 				});
 
-				// 7. Self-improving loop: score quality gates, append outcomes to
-				//    applied skills, and distill a skill when the work passed. Only
-				//    runs for a completed task; best-effort (never fails the spawn).
-				if (finalState === "completed" && config.skills.enabled) {
-					try {
-						const gateOutcome = await runQualityGates(
-							config.project.qualityGates ?? [],
-							worktree.path,
-						);
-						await runSkillFeedbackAndDistill({
-							root,
-							agentName: name,
-							capability,
-							taskId,
-							worktreePath: worktree.path,
-							baseRef: config.project.canonicalBranch,
-							runtime,
-							outcomeStatus: gateOutcome?.status ?? null,
-							skills: config.skills,
-							model: resolved.model,
-						});
-					} catch {
-						// Skill loop is advisory; a failure here must not fail the spawn.
-					}
-				}
-
 				if (useJson) {
 					jsonOutput({
 						agent: name,
@@ -293,7 +245,7 @@ export function createSlingCommand(): Command {
 						branchName,
 						worktreePath: worktree.path,
 						state: finalState,
-						exitCode: turn.exitCode,
+						exitCode: exitCode,
 					});
 					return;
 				}
@@ -301,8 +253,8 @@ export function createSlingCommand(): Command {
 				printInfo(`  task:    ${taskId}`);
 				printInfo(`  branch:  ${branchName}`);
 				printInfo(`  worktree:${muted(` ${worktree.path}`)}`);
-				if (turn.exitCode !== 0) {
-					printHint(`  turn exited ${turn.exitCode}; see \`agentplate mail list --from ${name}\``);
+				if (exitCode !== 0) {
+					printHint(`  turn exited ${exitCode}; see \`agentplate mail list --from ${name}\``);
 				}
 			} finally {
 				events.close();
@@ -378,26 +330,3 @@ function buildInitialPrompt(injected: string, instructionPath: string): string {
 	const header = `Read your instructions at ${instructionPath}, then begin your task.`;
 	return injected ? `${injected}\n\n${header}` : header;
 }
-
-/** Terminal mail types that mark a capability's work complete. */
-function terminalTypesFor(capability: Capability): string[] {
-	return capability === "merger" ? ["merged", "merge_failed"] : ["worker_done"];
-}
-
-function resolveFinalState(
-	root: string,
-	name: string,
-	capability: Capability,
-	exitCode: number,
-): AgentSession["state"] {
-	const terminal = terminalTypesFor(capability);
-	const store = createMailStore(mailDbPath(root));
-	try {
-		const sent = store.list({ from: name });
-		if (sent.some((m) => terminal.includes(m.type))) return "completed";
-	} finally {
-		store.close();
-	}
-	if (exitCode === 0) return "idle";
-	return "failed";
-}

package/src/commands/turn.test.ts

@@ -0,0 +1,101 @@
+/**
+ * `agentplate turn` command tests. Real initialized temp project + a real (mock)
+ * runtime turn. Drives the exported command's action via parseAsync.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	AGENTPLATE_DIR,
+	CONFIG_FILE,
+	DEFAULT_CONFIG,
+	serializeConfig,
+	setProjectRootOverride,
+} from "../config.ts";
+import { NotFoundError, ValidationError } from "../errors.ts";
+import { sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentSession, SessionState } from "../types.ts";
+import { createTurnCommand } from "./turn.ts";
+
+let root: string;
+let worktree: string;
+
+function seedSession(over: Partial<AgentSession>): void {
+	const store = createSessionStore(sessionsDbPath(root));
+	const now = new Date().toISOString();
+	try {
+		store.upsertSession({
+			id: `session-${crypto.randomUUID()}`,
+			agentName: "builder-1",
+			capability: "builder",
+			taskId: "task-1",
+			runId: "run-1",
+			worktreePath: worktree,
+			branchName: "agentplate/builder-1",
+			state: "idle",
+			parentAgent: "lead-1",
+			depth: 1,
+			pid: null,
+			runtimeSessionId: "sess-prior",
+			startedAt: now,
+			lastActivity: now,
+			...over,
+		});
+	} finally {
+		store.close();
+	}
+}
+
+function sessionState(agent: string): SessionState | undefined {
+	const store = createSessionStore(sessionsDbPath(root));
+	try {
+		return store.getSessionByAgent(agent)?.state;
+	} finally {
+		store.close();
+	}
+}
+
+async function runTurnCmd(agent: string): Promise<void> {
+	await createTurnCommand().parseAsync([agent], { from: "user" });
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-turn-cmd-"));
+	worktree = mkdtempSync(join(tmpdir(), "agentplate-turn-wt-"));
+	mkdirSync(join(root, AGENTPLATE_DIR), { recursive: true });
+	const config = structuredClone(DEFAULT_CONFIG);
+	config.runtime.default = "mock";
+	writeFileSync(join(root, AGENTPLATE_DIR, CONFIG_FILE), serializeConfig(config), "utf8");
+	setProjectRootOverride(root);
+	process.env.AGENTPLATE_MOCK_CMD = "true";
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+	rmSync(worktree, { recursive: true, force: true });
+	process.env.AGENTPLATE_MOCK_CMD = undefined;
+});
+
+describe("agentplate turn — refusals", () => {
+	test("throws NotFoundError for an unknown agent", async () => {
+		await expect(runTurnCmd("ghost")).rejects.toBeInstanceOf(NotFoundError);
+	});
+
+	test("refuses a terminal (completed) agent", async () => {
+		seedSession({ state: "completed" });
+		await expect(runTurnCmd("builder-1")).rejects.toBeInstanceOf(ValidationError);
+	});
+});
+
+describe("agentplate turn — runs the next turn", () => {
+	test("an idle agent takes another turn and transitions", async () => {
+		seedSession({ state: "idle" });
+		await runTurnCmd("builder-1");
+		// No terminal mail from the mock no-op → stays idle (ran without throwing).
+		expect(sessionState("builder-1")).toBe("idle");
+	});
+});

package/src/commands/turn.ts

@@ -0,0 +1,88 @@
+/**
+ * `agentplate turn <agent>` — run the NEXT headless turn for an existing agent.
+ *
+ * Where `sling` opens a fresh runtime session (turn 1), `turn` **resumes** it: it
+ * passes the session's captured `runtimeSessionId` to the runtime's `--resume`, so
+ * follow-up turns keep the warm context and skip the cold-start cost. The agent's
+ * unread mail is injected as the turn's prompt; the shared {@link driveTurn} core
+ * handles the state transition, skills loop, and auto-merge identically to turn 1.
+ *
+ * This is the multi-turn primitive: a coordinator/lead (or a future watcher) calls
+ * it when new mail arrives for an `idle` agent. Spawn-per-turn is preserved — each
+ * call is one fresh, resumed runtime subprocess.
+ */
+
+import { Command } from "commander";
+import { driveAgentTurn } from "../agents/drive.ts";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { NotFoundError, ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, muted, printInfo, printSuccess } from "../logging/color.ts";
+import { createMailClient } from "../mail/client.ts";
+import { eventsDbPath, sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import type { SessionState } from "../types.ts";
+
+interface TurnOptions {
+	json?: boolean;
+}
+
+/** States a turn can be driven from: paused/awaiting mail (not terminal, not mid-turn). */
+const DRIVABLE_STATES: ReadonlySet<SessionState> = new Set<SessionState>(["idle", "booting"]);
+
+export function createTurnCommand(): Command {
+	return new Command("turn")
+		.description("Run the next (resumed) turn for an existing agent")
+		.argument("<agent>", "agent name")
+		.option("--json", "output JSON")
+		.action(async (agent: string, opts: TurnOptions, command: Command) => {
+			const useJson = command.optsWithGlobals().json === true;
+			const root = findProjectRoot();
+			if (!isInitialized(root)) {
+				throw new ValidationError("Not initialized. Run `agentplate setup` first.");
+			}
+			const config = loadConfig(root);
+
+			const store = createSessionStore(sessionsDbPath(root));
+			const mail = createMailClient(root);
+			const events = createEventStore(eventsDbPath(root));
+			try {
+				const session = store.getSessionByAgent(agent);
+				if (!session) throw new NotFoundError(`No agent named "${agent}".`);
+				if (!DRIVABLE_STATES.has(session.state)) {
+					throw new ValidationError(
+						`Agent "${agent}" is ${session.state}; only an idle agent can take another turn.`,
+					);
+				}
+
+				const { finalState, exitCode } = await driveAgentTurn({
+					root,
+					config,
+					session,
+					store,
+					events,
+					mail,
+				});
+
+				if (useJson) {
+					jsonOutput({
+						agent,
+						capability: session.capability,
+						taskId: session.taskId,
+						state: finalState,
+						resumed: Boolean(session.runtimeSessionId),
+						exitCode,
+					});
+					return;
+				}
+				printSuccess(`${brand(agent)} [${session.capability}] → ${finalState}`);
+				printInfo(`  resumed: ${session.runtimeSessionId ? "yes (warm)" : "no (cold)"}`);
+				printInfo(`  worktree:${muted(` ${session.worktreePath}`)}`);
+			} finally {
+				events.close();
+				mail.close();
+				store.close();
+			}
+		});
+}

package/src/commands/watch.test.ts

@@ -0,0 +1,136 @@
+/**
+ * `agentplate watch` tests. Real initialized temp project + real (mock) turns,
+ * driven deterministically via `--once`. Asserts which idle agents get advanced.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	AGENTPLATE_DIR,
+	CONFIG_FILE,
+	DEFAULT_CONFIG,
+	serializeConfig,
+	setProjectRootOverride,
+} from "../config.ts";
+import { createMailClient } from "../mail/client.ts";
+import { sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentSession } from "../types.ts";
+import { createWatchCommand } from "./watch.ts";
+
+let root: string;
+let worktree: string;
+
+function seedSession(over: Partial<AgentSession>): void {
+	const store = createSessionStore(sessionsDbPath(root));
+	const now = new Date().toISOString();
+	try {
+		store.upsertSession({
+			id: `session-${crypto.randomUUID()}`,
+			agentName: "builder-1",
+			capability: "builder",
+			taskId: "task-1",
+			runId: "run-1",
+			worktreePath: worktree,
+			branchName: "agentplate/builder-1",
+			state: "idle",
+			parentAgent: "lead-1",
+			depth: 1,
+			pid: null,
+			runtimeSessionId: "sess-prior",
+			startedAt: now,
+			lastActivity: now,
+			...over,
+		});
+	} finally {
+		store.close();
+	}
+}
+
+function sendMailTo(agent: string): void {
+	const mail = createMailClient(root);
+	try {
+		mail.send({ from: "lead-1", to: agent, subject: "ping", body: "continue", type: "status" });
+	} finally {
+		mail.close();
+	}
+}
+
+/** Run `watch --once --json` and return the parsed summary. */
+async function watchOnce(): Promise<{ driven: number; turns: Array<{ agent: string }> }> {
+	const original = process.stdout.write.bind(process.stdout);
+	let out = "";
+	process.stdout.write = (chunk: string | Uint8Array): boolean => {
+		out += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		return true;
+	};
+	try {
+		await createWatchCommand().parseAsync(["--once", "--json"], { from: "user" });
+	} finally {
+		process.stdout.write = original;
+	}
+	// jsonOutput wraps the payload in the standard { ok, data } envelope.
+	return JSON.parse(out.trim()).data;
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-watch-"));
+	worktree = mkdtempSync(join(tmpdir(), "agentplate-watch-wt-"));
+	mkdirSync(join(root, AGENTPLATE_DIR), { recursive: true });
+	const config = structuredClone(DEFAULT_CONFIG);
+	config.runtime.default = "mock";
+	writeFileSync(join(root, AGENTPLATE_DIR, CONFIG_FILE), serializeConfig(config), "utf8");
+	setProjectRootOverride(root);
+	process.env.AGENTPLATE_MOCK_CMD = "true";
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+	rmSync(worktree, { recursive: true, force: true });
+	process.env.AGENTPLATE_MOCK_CMD = undefined;
+});
+
+describe("agentplate watch --once", () => {
+	test("drives an idle agent that has unread mail", async () => {
+		seedSession({ agentName: "builder-1", state: "idle" });
+		sendMailTo("builder-1");
+		const out = await watchOnce();
+		expect(out.driven).toBe(1);
+		expect(out.turns[0]?.agent).toBe("builder-1");
+	});
+
+	test("skips an idle agent with no unread mail", async () => {
+		seedSession({ agentName: "builder-1", state: "idle" });
+		const out = await watchOnce();
+		expect(out.driven).toBe(0);
+	});
+
+	test("never drives a terminal agent, even with mail", async () => {
+		seedSession({ agentName: "builder-1", state: "completed" });
+		sendMailTo("builder-1");
+		const out = await watchOnce();
+		expect(out.driven).toBe(0);
+	});
+
+	test("drives only the idle-with-mail agents in a mixed fleet", async () => {
+		seedSession({ agentName: "has-mail", state: "idle" });
+		seedSession({ agentName: "no-mail", state: "idle" });
+		sendMailTo("has-mail");
+		const out = await watchOnce();
+		expect(out.driven).toBe(1);
+		expect(out.turns.map((t) => t.agent)).toEqual(["has-mail"]);
+	});
+
+	test("drives multiple idle-with-mail agents in one pass (concurrent)", async () => {
+		for (const a of ["a1", "a2", "a3"]) {
+			seedSession({ agentName: a, state: "idle" });
+			sendMailTo(a);
+		}
+		const out = await watchOnce();
+		expect(out.driven).toBe(3);
+		expect(out.turns.map((t) => t.agent).sort()).toEqual(["a1", "a2", "a3"]);
+	});
+});