@agentplate/cli 1.1.0 → 1.3.0

package/src/runtimes/registry.test.ts

@@ -1,15 +1,29 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { ValidationError } from "../errors.ts";
-import type { ResolvedModel } from "../types.ts";
+import type { ResolvedModel, RuntimeConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CursorRuntime } from "./cursor.ts";
 import { GeminiRuntime } from "./gemini.ts";
 import { MockRuntime } from "./mock.ts";
 import { OpenCodeRuntime, opencodeModel } from "./opencode.ts";
-import { getRuntime, getRuntimeNames } from "./registry.ts";
+import { getRuntime, getRuntimeNames, runtimeNameForCapability } from "./registry.ts";
 import type { AgentEvent, DirectSpawnOpts } from "./types.ts";
 
+describe("runtimeNameForCapability", () => {
+	const rt: RuntimeConfig = { default: "claude", capabilities: { scout: "codex" } };
+	test("explicit override wins over everything", () => {
+		expect(runtimeNameForCapability(rt, "scout", "gemini")).toBe("gemini");
+	});
+	test("per-capability override applies when set", () => {
+		expect(runtimeNameForCapability(rt, "scout")).toBe("codex");
+	});
+	test("falls back to the default runtime", () => {
+		expect(runtimeNameForCapability(rt, "builder")).toBe("claude");
+		expect(runtimeNameForCapability({ default: "opencode" }, "scout")).toBe("opencode");
+	});
+});
+
 // Minimal DirectSpawnOpts builder for argv-shape assertions. `cwd` and
 // `instructionPath` are required by the type but irrelevant to argv here.
 function spawnOpts(overrides: Partial<DirectSpawnOpts> = {}): DirectSpawnOpts {

package/src/runtimes/registry.ts

@@ -8,6 +8,7 @@
  */
 
 import { ValidationError } from "../errors.ts";
+import type { Capability, RuntimeConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CursorRuntime } from "./cursor.ts";
@@ -54,6 +55,18 @@ export function getRuntime(name?: string, fallback?: string): AgentRuntime {
 	return factory();
 }
 
+/**
+ * Resolve which runtime adapter drives a given capability: an explicit `override`
+ * wins, then a per-capability entry in `runtime.capabilities`, then the default.
+ */
+export function runtimeNameForCapability(
+	runtime: RuntimeConfig,
+	capability: Capability,
+	override?: string,
+): string {
+	return override ?? runtime.capabilities?.[capability] ?? runtime.default;
+}
+
 /**
  * Names of all registered runtimes, in registration order. Used to validate a
  * user-supplied runtime name and to render the choices in help / errors.

package/src/runtimes/resolve.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Tests for resolveModel — focused on per-capability model tiering. Auth-mode is
+ * set to "none" so no secret is read; we assert which model id is chosen.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_CONFIG } from "../config.ts";
+import type { AgentplateConfig, Capability } from "../types.ts";
+import { resolveModel } from "./resolve.ts";
+
+/** A config whose active provider has a default model + optional tiering map. */
+function configWith(
+	model: string | undefined,
+	models?: Partial<Record<Capability, string>>,
+): AgentplateConfig {
+	const cfg = structuredClone(DEFAULT_CONFIG);
+	cfg.activeProvider = "anthropic";
+	cfg.providers.anthropic = { type: "native", authMode: "none", model, models };
+	return cfg;
+}
+
+const ROOT = "/tmp/agentplate-resolve-test"; // never read (authMode "none")
+
+describe("resolveModel — tiering", () => {
+	test("uses the provider default model when no capability is given", () => {
+		const { model } = resolveModel(configWith("claude-opus-4-8"), ROOT, "alias");
+		expect(model).toBe("claude-opus-4-8");
+	});
+
+	test("a per-capability override wins over the provider default", () => {
+		const cfg = configWith("claude-opus-4-8", {
+			scout: "claude-haiku-4-5",
+			reviewer: "claude-haiku-4-5",
+		});
+		expect(resolveModel(cfg, ROOT, "alias", "scout").model).toBe("claude-haiku-4-5");
+		expect(resolveModel(cfg, ROOT, "alias", "reviewer").model).toBe("claude-haiku-4-5");
+	});
+
+	test("a capability without an override falls back to the provider default", () => {
+		const cfg = configWith("claude-opus-4-8", { scout: "claude-haiku-4-5" });
+		expect(resolveModel(cfg, ROOT, "alias", "builder").model).toBe("claude-opus-4-8");
+	});
+
+	test("falls back to the manifest alias when the provider has no model", () => {
+		expect(resolveModel(configWith(undefined), ROOT, "manifest-alias", "builder").model).toBe(
+			"manifest-alias",
+		);
+	});
+});

package/src/runtimes/resolve.ts

@@ -2,11 +2,12 @@
  * Model resolution — bridge between the agent manifest (which names models by
  * alias) and a concrete {@link ResolvedModel} the runtime can spawn.
  *
- * Phase 2 keeps this deliberately simple: the active provider's configured
- * `model` (set by `agentplate setup`) is the concrete model, and the provider's
- * `authTokenEnv` secret is injected as an env var. Per-capability model tiering
- * (opus/sonnet/haiku) is a later refinement; for now the manifest alias is the
- * fallback when no provider model is configured.
+ * The active provider's configured `model` (set by `agentplate setup`) is the
+ * concrete model, and the provider's `authTokenEnv` secret is injected as an env
+ * var. Per-capability **model tiering** is supported: when a `capability` is given
+ * and the provider has a `models[capability]` override (e.g. a fast model for
+ * `scout`/`reviewer`), that wins; otherwise the provider `model`, otherwise the
+ * manifest alias.
  *
  * Auth mode matters here: only `api-key`/`env` providers inject a credential env
  * var. `subscription` providers delegate to the runtime CLI's own login (e.g. a
@@ -15,7 +16,7 @@
  */
 
 import { getSecret } from "../secrets.ts";
-import type { AgentplateConfig, ResolvedModel } from "../types.ts";
+import type { AgentplateConfig, Capability, ResolvedModel } from "../types.ts";
 
 /**
  * Resolve the concrete model + provider env for a manifest model alias.
@@ -23,14 +24,17 @@ import type { AgentplateConfig, ResolvedModel } from "../types.ts";
  * @param config  loaded Agentplate config
  * @param root    project root (to read the gitignored secret value)
  * @param manifestModel the model alias/id from the agent definition
+ * @param capability optional agent capability for per-capability model tiering
  */
 export function resolveModel(
 	config: AgentplateConfig,
 	root: string,
 	manifestModel: string,
+	capability?: Capability,
 ): ResolvedModel {
 	const provider = config.providers[config.activeProvider];
-	const model = provider?.model ?? manifestModel;
+	const tiered = capability ? provider?.models?.[capability] : undefined;
+	const model = tiered ?? provider?.model ?? manifestModel;
 	const env: Record<string, string> = {};
 
 	// Default to "api-key" for legacy configs written before authMode existed.

package/src/sessions/store.test.ts

@@ -318,6 +318,19 @@ describe("createSessionStore — countActive", () => {
 		store.updateSessionState(s.id, "completed");
 		expect(store.countActive("run-x")).toBe(0);
 	});
+
+	test("countActiveByParent counts a parent's active children only", () => {
+		store.upsertSession(makeSession({ runId: "r", parentAgent: "lead-1", state: "working" }));
+		store.upsertSession(makeSession({ runId: "r", parentAgent: "lead-1", state: "booting" }));
+		const done = makeSession({ runId: "r", parentAgent: "lead-1", state: "completed" });
+		store.upsertSession(done);
+		store.upsertSession(makeSession({ runId: "r", parentAgent: "lead-2", state: "working" }));
+
+		expect(store.countActiveByParent("lead-1", "r")).toBe(2); // excludes the completed child
+		expect(store.countActiveByParent("lead-2", "r")).toBe(1);
+		expect(store.countActiveByParent("lead-1", "other-run")).toBe(0);
+		expect(store.countActiveByParent("nobody")).toBe(0);
+	});
 });
 
 describe("createSessionStore — file-backed database", () => {

package/src/sessions/store.ts

@@ -57,6 +57,7 @@ export interface SessionStore {
 	setRuntimeSessionId(id: string, runtimeSessionId: string): void;
 	touch(id: string): void;
 	countActive(runId?: string): number;
+	countActiveByParent(parentAgent: string, runId?: string): number;
 	// --- Lifecycle ---
 	close(): void;
 }
@@ -328,6 +329,24 @@ export function createSessionStore(dbPath: string): SessionStore {
 		return row.n;
 	}
 
+	function countActiveByParent(parentAgent: string, runId?: string): number {
+		// Active children of a given parent (for the per-lead child cap).
+		if (runId !== undefined) {
+			const row = db
+				.query(
+					`SELECT COUNT(*) AS n FROM sessions WHERE parent_agent = ? AND run_id = ? AND state IN ${ACTIVE_STATES_SQL}`,
+				)
+				.get(parentAgent, runId) as { n: number };
+			return row.n;
+		}
+		const row = db
+			.query(
+				`SELECT COUNT(*) AS n FROM sessions WHERE parent_agent = ? AND state IN ${ACTIVE_STATES_SQL}`,
+			)
+			.get(parentAgent) as { n: number };
+		return row.n;
+	}
+
 	function close(): void {
 		db.close();
 	}
@@ -345,6 +364,7 @@ export function createSessionStore(dbPath: string): SessionStore {
 		setRuntimeSessionId,
 		touch,
 		countActive,
+		countActiveByParent,
 		close,
 	};
 }

package/src/types.ts

@@ -127,6 +127,11 @@ export interface ProviderConfig {
 	authTokenEnv?: string;
 	/** Default model id for this provider. */
 	model?: string;
+	/**
+	 * Per-capability model overrides (tiering): e.g. a fast/cheap model for
+	 * `scout`/`reviewer` and a strong model for `builder`. Falls back to `model`.
+	 */
+	models?: Partial<Record<Capability, string>>;
 }
 
 /** Orchestration limits and agent registry locations. */
@@ -148,12 +153,36 @@ export interface AgentsConfig {
 	 * `0` disables idle reaping. Default 10.
 	 */
 	idleTimeoutMinutes: number;
+	/**
+	 * Hard wall-clock cap on a SINGLE turn, in minutes. Unlike idle reaping (which
+	 * needs inactivity), this kills a turn that keeps streaming but never finishes.
+	 * `0` disables the cap. Default 0.
+	 */
+	turnTimeoutMinutes: number;
+	/** Default: leads skip the scout step (go straight to builders). */
+	skipScout: boolean;
+	/** Default: leads skip the reviewer step before integrating. */
+	skipReview: boolean;
+	/** Skip the post-turn quality-gate run (speed; disables `on-gates-pass` merge). */
+	skipGates: boolean;
+	/** Skip the post-turn skill-distillation loop. */
+	skipSkills: boolean;
 }
 
-/** Conflict-resolution behavior for merging agent branches. */
+/**
+ * When a completed worker's branch is auto-merged into the canonical branch.
+ * - `off`: never (the operator/coordinator merges manually) — the default.
+ * - `on-gates-pass`: merge only if the task's quality gates pass.
+ * - `on-complete`: merge as soon as the agent finishes without error.
+ */
+export type AutoMergeMode = "off" | "on-gates-pass" | "on-complete";
+
+/** Conflict-resolution and auto-merge behavior for merging agent branches. */
 export interface MergeConfig {
 	/** Allow AI-assisted resolution of semantic conflicts. */
 	aiResolveEnabled: boolean;
+	/** When to auto-merge a completed worker's branch into the canonical branch. */
+	autoMerge: AutoMergeMode;
 }
 
 /** Logging behavior. */

package/src/version.ts

@@ -4,4 +4,4 @@
  * Kept as a plain constant (not read from package.json at runtime) so the value
  * is available without filesystem access and survives bundling.
  */
-export const VERSION = "1.1.0";
+export const VERSION = "1.3.0";

package/src/wizard/setup.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Wizard helper tests. The interactive prompts themselves need a TTY, but the
+ * pure pieces are unit-tested directly. `detectQualityGates` reads a project's
+ * package.json to suggest gate commands.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { detectQualityGates } from "./setup.ts";
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "agentplate-wizard-"));
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("detectQualityGates", () => {
+	test("falls back to stack defaults when there is no package.json", () => {
+		const gates = detectQualityGates(dir);
+		expect(gates).toEqual([
+			{ name: "test", command: "bun test" },
+			{ name: "lint", command: "biome check ." },
+			{ name: "typecheck", command: "tsc --noEmit" },
+		]);
+	});
+
+	test("prefers `bun run <script>` for scripts the project defines", () => {
+		writeFileSync(
+			join(dir, "package.json"),
+			JSON.stringify({ scripts: { test: "vitest", typecheck: "tsc -p ." } }),
+			"utf8",
+		);
+		const gates = detectQualityGates(dir);
+		const byName = Object.fromEntries(gates.map((g) => [g.name, g.command]));
+		expect(byName.test).toBe("bun run test"); // script present → run it
+		expect(byName.typecheck).toBe("bun run typecheck"); // script present
+		expect(byName.lint).toBe("biome check ."); // no lint script → fallback
+	});
+});

package/src/wizard/setup.ts

@@ -7,10 +7,18 @@
  * module owns only the interactive I/O.
  */
 
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import * as p from "@clack/prompts";
 import { applyProviderSelection, buildProviderConfig } from "../providers/apply.ts";
 import { getProviderSpec, listProviders, meetsContextFloor } from "../providers/registry.ts";
-import type { AgentplateConfig, AuthMode } from "../types.ts";
+import type {
+	AgentplateConfig,
+	AuthMode,
+	AutoMergeMode,
+	Capability,
+	QualityGate,
+} from "../types.ts";
 import { commandOnPath, detectDefaultRuntime } from "../utils/detect.ts";
 
 /** Runtimes the wizard can offer. */
@@ -34,6 +42,32 @@ export interface WizardResult {
 	secret?: { key: string; value: string };
 }
 
+/**
+ * Suggest quality gates for a project. Prefers the project's own package.json
+ * scripts (`bun run <script>`) when present, falling back to the Bun/Biome/TS
+ * defaults this stack uses. The user confirms/deselects in the wizard.
+ */
+export function detectQualityGates(root: string): QualityGate[] {
+	let scripts: Record<string, string> = {};
+	try {
+		const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+			scripts?: Record<string, string>;
+		};
+		scripts = pkg.scripts ?? {};
+	} catch {
+		// No package.json (or unreadable) — fall back to stack defaults below.
+	}
+	const gate = (name: string, fallback: string): QualityGate => ({
+		name,
+		command: scripts[name] ? `bun run ${name}` : fallback,
+	});
+	return [
+		gate("test", "bun test"),
+		gate("lint", "biome check ."),
+		gate("typecheck", "tsc --noEmit"),
+	];
+}
+
 /** Abort the wizard cleanly if the user cancelled a prompt. */
 function ensure<T>(value: T | symbol): T {
 	if (p.isCancel(value)) {
@@ -192,6 +226,31 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 		).trim();
 	}
 
+	// 4b. Model tiering — optionally use a faster/cheaper model for read-only
+	//     roles (scout, reviewer), keeping the chosen model for the rest.
+	let modelsByCapability: Partial<Record<Capability, string>> | undefined;
+	if (eligible.length > 1) {
+		const wantTiering = ensure(
+			await p.confirm({
+				message: "Use a faster/cheaper model for read-only roles (scout & reviewer)?",
+				initialValue: false,
+			}),
+		);
+		if (wantTiering) {
+			const fast = ensure(
+				await p.select({
+					message: "Fast model for scout & reviewer",
+					options: eligible.map((m) => ({
+						value: m.id,
+						label: m.label,
+						hint: `${Math.round(m.contextWindow / 1000)}k context`,
+					})),
+				}),
+			) as string;
+			modelsByCapability = { scout: fast, reviewer: fast };
+		}
+	}
+
 	// 5. Runtime -----------------------------------------------------------
 	const detected = await detectDefaultRuntime();
 	const installed = new Set<string>();
@@ -219,7 +278,115 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 		}),
 	);
 
-	// 6. Summary -----------------------------------------------------------
+	// 6. Orchestration & merge --------------------------------------------
+	const canonicalBranch = currentConfig.project.canonicalBranch;
+	const suggestedGates = detectQualityGates(currentConfig.project.root || ".");
+	const chosenGateNames = ensure(
+		await p.multiselect({
+			message:
+				"Quality gates to run on a worker's output (used by skill distillation and 'on gates pass' auto-merge)",
+			options: suggestedGates.map((g) => ({ value: g.name, label: g.name, hint: g.command })),
+			initialValues: suggestedGates.map((g) => g.name),
+			required: false,
+		}),
+	) as string[];
+	const qualityGates = suggestedGates.filter((g) => chosenGateNames.includes(g.name));
+
+	const autoMerge = ensure(
+		await p.select({
+			message: `Auto-merge a worker's branch into ${canonicalBranch} when it finishes?`,
+			initialValue: "off",
+			options: [
+				{ value: "off", label: "Never — merge manually", hint: "default; safest" },
+				{
+					value: "on-gates-pass",
+					label: "On quality gates pass",
+					hint: qualityGates.length
+						? "merge only when gates are green"
+						: "needs gates — will hold otherwise",
+				},
+				{
+					value: "on-complete",
+					label: "On complete",
+					hint: "merge as soon as the agent finishes (no gate check)",
+				},
+			],
+		}),
+	) as AutoMergeMode;
+
+	if (autoMerge === "on-gates-pass" && qualityGates.length === 0) {
+		p.note(
+			"No quality gates selected, so 'on gates pass' will hold every merge for manual review.\nAdd gates or pick a different mode to actually auto-merge.",
+			"Heads up",
+		);
+	}
+
+	// 6b. Advanced limits — gated so the common path stays short.
+	const agents = { ...currentConfig.agents };
+	const tuneAdvanced = ensure(
+		await p.confirm({
+			message: "Tune advanced limits (concurrency, timeouts, skip steps)?",
+			initialValue: false,
+		}),
+	);
+	if (tuneAdvanced) {
+		const posInt = (v: string | undefined): string | undefined =>
+			v && Number.isInteger(Number(v)) && Number(v) >= 0 ? undefined : "Enter a whole number ≥ 0";
+		agents.maxConcurrent = Number(
+			ensure(
+				await p.text({
+					message: "Max agents running at once",
+					initialValue: String(agents.maxConcurrent),
+					validate: (v) => (v && Number(v) >= 1 ? undefined : "Enter a number ≥ 1"),
+				}),
+			),
+		);
+		agents.maxAgentsPerLead = Number(
+			ensure(
+				await p.text({
+					message: "Max workers per lead",
+					initialValue: String(agents.maxAgentsPerLead),
+					validate: (v) => (v && Number(v) >= 1 ? undefined : "Enter a number ≥ 1"),
+				}),
+			),
+		);
+		agents.turnTimeoutMinutes = Number(
+			ensure(
+				await p.text({
+					message: "Per-turn timeout in minutes (0 = no cap)",
+					initialValue: String(agents.turnTimeoutMinutes),
+					validate: posInt,
+				}),
+			),
+		);
+		const skips = ensure(
+			await p.multiselect({
+				message: "Default speed shortcuts (leave empty for none)",
+				options: [
+					{
+						value: "skipScout",
+						label: "Skip scout step",
+						hint: "leads dispatch builders directly",
+					},
+					{ value: "skipReview", label: "Skip review step", hint: "no reviewer before integrate" },
+					{
+						value: "skipGates",
+						label: "Skip quality gates",
+						hint: "faster; disables on-gates-pass merge",
+					},
+					{ value: "skipSkills", label: "Skip skill distillation" },
+				],
+				initialValues: [],
+				required: false,
+			}),
+		) as string[];
+		agents.skipScout = skips.includes("skipScout");
+		agents.skipReview = skips.includes("skipReview");
+		agents.skipGates = skips.includes("skipGates");
+		agents.skipSkills = skips.includes("skipSkills");
+	}
+
+	// 7. Summary -----------------------------------------------------------
 	const previewProvider = buildProviderConfig(spec, model, authMode, baseUrl);
 	const authSummary: Record<AuthMode, string> = {
 		subscription: `subscription / ${runtimeCli(spec.subscriptionRuntime ?? runtime)} login (no key stored)`,
@@ -234,6 +401,11 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 			`runtime:   ${runtime}`,
 			`auth:      ${authSummary[authMode]}`,
 			previewProvider.baseUrl ? `base URL:  ${previewProvider.baseUrl}` : undefined,
+			`gates:     ${qualityGates.length ? qualityGates.map((g) => g.name).join(", ") : "none"}`,
+			`auto-merge:${autoMerge}`,
+			modelsByCapability?.scout
+				? `fast model: ${modelsByCapability.scout} (scout, reviewer)`
+				: undefined,
 		]
 			.filter(Boolean)
 			.join("\n"),
@@ -248,6 +420,13 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 		baseUrl,
 		runtime,
 	});
+	config.merge = { ...config.merge, autoMerge };
+	config.agents = agents;
+	if (qualityGates.length) config.project = { ...config.project, qualityGates };
+	if (modelsByCapability) {
+		const pc = config.providers[providerId];
+		if (pc) config.providers[providerId] = { ...pc, models: modelsByCapability };
+	}
 
 	p.outro("Ready to write configuration.");
 	return secret ? { config, secret } : { config };