@ag-eco/agentplate-cli 0.13.0

package/src/agents/turn-runner-dispatch.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentRuntime } from "../runtimes/types.ts";
+import type { AgentManifest, AgentplateConfig, AgentSession } from "../types.ts";
+import { buildRunTurnOptsFactory, isSpawnPerTurnAgent } from "./turn-runner-dispatch.ts";
+
+function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
+	return {
+		id: "session-1",
+		agentName: "build-agent-1",
+		capability: "builder",
+		worktreePath: "/tmp/wt-build",
+		branchName: "agentplate/b/task-1",
+		taskId: "task-1",
+		tmuxSession: "",
+		state: "working",
+		pid: 12345,
+		parentAgent: "lead-1",
+		depth: 1,
+		runId: "run-abc",
+		startedAt: new Date().toISOString(),
+		lastActivity: new Date().toISOString(),
+		escalationLevel: 0,
+		stalledSince: null,
+		transcriptPath: null,
+		...overrides,
+	};
+}
+
+function makeConfig(overrides: Partial<AgentplateConfig> = {}): AgentplateConfig {
+	const base: AgentplateConfig = {
+		project: {
+			name: "test",
+			root: "/tmp/proj",
+			canonicalBranch: "main",
+		},
+		agents: {
+			baseDir: "agents",
+			manifestPath: ".agentplate/agent-manifest.json",
+			maxConcurrent: 5,
+			maxSessionsPerRun: 0,
+			maxAgentsPerLead: 5,
+			maxDepth: 2,
+			staggerDelayMs: 0,
+			autoNudgeOnMail: false,
+		},
+		worktrees: { baseDir: ".agentplate/worktrees" },
+		merge: { mode: "manual" },
+		loam: { enabled: false, domains: {} },
+		trellis: { enabled: false },
+		taskTracker: { backend: "sprout", enabled: true },
+		watchdog: {
+			tier0Enabled: false,
+			tier0IntervalMs: 30_000,
+			tier1Enabled: false,
+			maxEscalationLevel: 3,
+		},
+		models: {},
+		logging: { verbose: false, redactSecrets: true },
+		runtime: {
+			default: "claude",
+		},
+		providers: {},
+	} as unknown as AgentplateConfig;
+	return { ...base, ...overrides } as AgentplateConfig;
+}
+
+function makeManifest(): AgentManifest {
+	return {
+		version: "1",
+		agents: {
+			builder: {
+				file: "builder.md",
+				model: "claude-sonnet",
+				tools: [],
+				capabilities: ["build"],
+				canSpawn: false,
+				constraints: [],
+			},
+		},
+		capabilityIndex: { build: ["builder"] },
+	} as AgentManifest;
+}
+
+function fakeRuntime(overrides: Partial<AgentRuntime> = {}): AgentRuntime {
+	return {
+		id: "claude",
+		stability: "stable",
+		instructionPath: ".claude/CLAUDE.md",
+		buildSpawnCommand: () => "",
+		buildPrintCommand: () => [],
+		deployConfig: async () => {},
+		buildEnv: () => ({}),
+		buildDirectSpawn: () => ["claude"],
+		parseEvents: async function* () {},
+		...overrides,
+	} as unknown as AgentRuntime;
+}
+
+describe("buildRunTurnOptsFactory", () => {
+	test("threads session metadata + project paths into runTurn opts", () => {
+		const session = makeSession();
+		const config = makeConfig();
+		const manifest = makeManifest();
+		const runtime = fakeRuntime();
+
+		const factory = buildRunTurnOptsFactory({
+			session,
+			config,
+			manifest,
+			agentplateDir: "/tmp/proj/.agentplate",
+			_getRuntime: () => runtime,
+			_resolveModel: () => ({ model: "claude-sonnet", isExplicitOverride: false }),
+		});
+
+		const opts = factory.build('{"type":"user"}\n');
+		expect(opts.agentName).toBe("build-agent-1");
+		expect(opts.capability).toBe("builder");
+		expect(opts.worktreePath).toBe("/tmp/wt-build");
+		expect(opts.taskId).toBe("task-1");
+		expect(opts.runId).toBe("run-abc");
+		expect(opts.projectRoot).toBe("/tmp/proj");
+		expect(opts.mailDbPath).toBe("/tmp/proj/.agentplate/mail.db");
+		expect(opts.eventsDbPath).toBe("/tmp/proj/.agentplate/events.db");
+		expect(opts.sessionsDbPath).toBe("/tmp/proj/.agentplate/sessions.db");
+		expect(opts.userTurnNdjson).toBe('{"type":"user"}\n');
+		expect(opts.runtime).toBe(runtime);
+	});
+
+	test("threads merger capability through to runTurn opts", () => {
+		const session = makeSession({ capability: "merger", agentName: "merge-1" });
+		const factory = buildRunTurnOptsFactory({
+			session,
+			config: makeConfig(),
+			manifest: makeManifest(),
+			agentplateDir: "/tmp/proj/.agentplate",
+			_getRuntime: () => fakeRuntime(),
+			_resolveModel: () => ({ model: "claude-sonnet", isExplicitOverride: false }),
+		});
+		expect(factory.build("x").capability).toBe("merger");
+	});
+});
+
+describe("isSpawnPerTurnAgent", () => {
+	const runtime = fakeRuntime();
+	const config = makeConfig();
+
+	test("returns true for a builder in non-terminal state on a claude-like runtime", () => {
+		const ok = isSpawnPerTurnAgent(
+			makeSession({ capability: "builder", state: "working" }),
+			config,
+			runtime,
+		);
+		expect(ok).toBe(true);
+	});
+
+	test("admits all task-scoped capabilities (scout, reviewer, merger, lead, builder)", () => {
+		for (const cap of ["builder", "scout", "reviewer", "merger", "lead"]) {
+			expect(isSpawnPerTurnAgent(makeSession({ capability: cap }), config, runtime)).toBe(true);
+		}
+	});
+
+	test("rejects persistent capabilities (coordinator, orchestrator, monitor)", () => {
+		for (const cap of ["coordinator", "orchestrator", "monitor"]) {
+			expect(isSpawnPerTurnAgent(makeSession({ capability: cap }), config, runtime)).toBe(false);
+		}
+	});
+
+	test("returns false for terminal states (completed, zombie)", () => {
+		expect(isSpawnPerTurnAgent(makeSession({ state: "completed" }), config, runtime)).toBe(false);
+		expect(isSpawnPerTurnAgent(makeSession({ state: "zombie" }), config, runtime)).toBe(false);
+	});
+
+	test("returns false when runtime cannot direct-spawn", () => {
+		const noDirectSpawn = fakeRuntime({ buildDirectSpawn: undefined });
+		expect(isSpawnPerTurnAgent(makeSession(), config, noDirectSpawn)).toBe(false);
+	});
+
+	test("returns false when runtime cannot parseEvents", () => {
+		const noParser = fakeRuntime({ parseEvents: undefined });
+		expect(isSpawnPerTurnAgent(makeSession(), config, noParser)).toBe(false);
+	});
+});

package/src/agents/turn-runner-dispatch.ts

@@ -0,0 +1,105 @@
+/**
+ * Helpers for dispatching user turns through `runTurn` (Phase 2 spawn-per-turn).
+ *
+ * `runTurn` (src/agents/turn-runner.ts) needs ~12 inputs to drive one builder
+ * turn. Most of those derive from the agent's `AgentSession` row plus
+ * project-level paths. Consumers that route mail or nudges through the
+ * spawn-per-turn engine — `ap serve`, `ap nudge` — need the same setup
+ * boilerplate, so it lives here.
+ *
+ * The exported `buildRunTurnOptsFactory()` resolves the runtime adapter and
+ * model once per agent and returns a `(userTurnNdjson) => RunTurnOpts`
+ * closure. The closure is small and disposable; callers re-resolve it when
+ * the underlying session metadata changes (e.g. on rescan).
+ */
+
+import { join } from "node:path";
+import { getRuntime } from "../runtimes/registry.ts";
+import type { AgentRuntime } from "../runtimes/types.ts";
+import type { AgentManifest, AgentplateConfig, AgentSession, ResolvedModel } from "../types.ts";
+import { isTaskScopedCapability } from "./capabilities.ts";
+import { resolveModel } from "./manifest.ts";
+import type { RunTurnOpts } from "./turn-runner.ts";
+
+export interface BuildOptsFactoryInput {
+	session: AgentSession;
+	config: AgentplateConfig;
+	manifest: AgentManifest;
+	agentplateDir: string;
+	/** Optional override (test injection). Defaults to `getRuntime`. */
+	_getRuntime?: typeof getRuntime;
+	/** Optional override (test injection). Defaults to `resolveModel`. */
+	_resolveModel?: typeof resolveModel;
+}
+
+export interface BuiltOptsFactory {
+	runtime: AgentRuntime;
+	resolvedModel: ResolvedModel;
+	/** Produces a fresh `RunTurnOpts` for the given user turn payload. */
+	build: (userTurnNdjson: string) => RunTurnOpts;
+}
+
+/**
+ * Resolve runtime + model for a session and return a factory that produces
+ * `RunTurnOpts` given a user-turn NDJSON payload.
+ *
+ * The factory closes over the per-agent metadata (worktreePath, capability,
+ * runId, etc.) so callers only have to supply the dynamic payload. The
+ * factory's outputs are otherwise identical run-to-run.
+ */
+export function buildRunTurnOptsFactory(input: BuildOptsFactoryInput): BuiltOptsFactory {
+	const { session, config, manifest, agentplateDir } = input;
+	const _getRuntime = input._getRuntime ?? getRuntime;
+	const _resolveModel = input._resolveModel ?? resolveModel;
+
+	const runtime = _getRuntime(undefined, config, session.capability);
+	const fallback = manifest.agents[session.capability]?.model ?? "claude-sonnet";
+	const resolvedModel = _resolveModel(config, manifest, session.capability, fallback);
+
+	const mailDbPath = join(agentplateDir, "mail.db");
+	const eventsDbPath = join(agentplateDir, "events.db");
+	const sessionsDbPath = join(agentplateDir, "sessions.db");
+
+	const build = (userTurnNdjson: string): RunTurnOpts => ({
+		agentName: session.agentName,
+		capability: session.capability,
+		agentplateDir,
+		worktreePath: session.worktreePath,
+		projectRoot: config.project.root,
+		taskId: session.taskId,
+		userTurnNdjson,
+		runtime,
+		resolvedModel,
+		runId: session.runId,
+		mailDbPath,
+		eventsDbPath,
+		sessionsDbPath,
+	});
+
+	return { runtime, resolvedModel, build };
+}
+
+/**
+ * Predicate: is this agent eligible for spawn-per-turn dispatch?
+ *
+ * Capability gate: any task-scoped worker (builder, scout, reviewer, merger,
+ * lead — see {@link isTaskScopedCapability}) running on a runtime that
+ * implements `buildDirectSpawn`/`parseEvents` (today: claude). Non-terminal
+ * state required — completed/zombie sessions are never re-spawned.
+ *
+ * `_config` is unused at this layer (the project-level gate flag was removed in
+ * Phase 3 once spawn-per-turn became the only path for task-scoped Claude) but
+ * the parameter is preserved so call sites that already thread config in don't
+ * need to change.
+ */
+export function isSpawnPerTurnAgent(
+	session: AgentSession,
+	_config: AgentplateConfig,
+	runtime: AgentRuntime,
+): boolean {
+	if (!isTaskScopedCapability(session.capability)) return false;
+	if (session.state === "completed" || session.state === "zombie") return false;
+	if (typeof runtime.buildDirectSpawn !== "function") return false;
+	if (typeof runtime.parseEvents !== "function") return false;
+	return true;
+}