@prometheus-ai/swarm-extension 0.5.1

package/src/swarm/executor.ts

@@ -0,0 +1,111 @@
+/**
+ * Swarm agent execution via prometheus's subagent infrastructure.
+ *
+ * Wraps `runSubprocess` to spawn individual swarm agents with full tool access.
+ * Each agent runs in the swarm workspace with its task instructions as the user prompt.
+ */
+import * as path from "node:path";
+import type {
+	AgentDefinition,
+	AgentProgress,
+	AgentSource,
+	ModelRegistry,
+	Settings,
+	SingleResult,
+} from "@prometheus-ai/agent";
+import { runSubprocess } from "@prometheus-ai/agent";
+import type { SwarmAgent } from "./schema";
+import type { StateTracker } from "./state";
+
+export interface SwarmExecutorOptions {
+	workspace: string;
+	swarmName: string;
+	iteration: number;
+	modelOverride?: string;
+	signal?: AbortSignal;
+	onProgress?: (agentName: string, progress: AgentProgress) => void;
+	modelRegistry?: ModelRegistry;
+	settings?: Settings;
+	stateTracker: StateTracker;
+}
+
+/**
+ * Execute a single swarm agent as an prometheus subagent.
+ *
+ * The agent receives:
+ * - System prompt: built from role + extra_context
+ * - User prompt (task): the full task instructions from the YAML
+ * - Working directory: the swarm workspace
+ * - Full tool access (bash, python, read, write, edit, grep, find, fetch, web_search, browser)
+ */
+export async function executeSwarmAgent(
+	agent: SwarmAgent,
+	index: number,
+	options: SwarmExecutorOptions,
+): Promise<SingleResult> {
+	const { workspace, swarmName, iteration, modelOverride, signal, onProgress, modelRegistry, settings, stateTracker } =
+		options;
+
+	const agentId = `swarm-${swarmName}-${agent.name}-${iteration}`;
+
+	const agentDef: AgentDefinition = {
+		name: agent.name,
+		description: `Swarm agent: ${agent.role}`,
+		systemPrompt: buildSystemPrompt(agent),
+		source: "project" as AgentSource,
+	};
+
+	await stateTracker.updateAgent(agent.name, {
+		status: "running",
+		iteration,
+		startedAt: Date.now(),
+	});
+	await stateTracker.appendLog(agent.name, `Starting iteration ${iteration}`);
+
+	try {
+		const result = await runSubprocess({
+			cwd: workspace,
+			agent: agentDef,
+			task: agent.task,
+			index,
+			id: agentId,
+			modelOverride,
+			signal,
+			onProgress: progress => onProgress?.(agent.name, progress),
+			modelRegistry,
+			settings,
+			enableLsp: false,
+			artifactsDir: path.join(stateTracker.swarmDir, "context"),
+		});
+
+		const status = result.exitCode === 0 ? ("completed" as const) : ("failed" as const);
+		await stateTracker.updateAgent(agent.name, {
+			status,
+			completedAt: Date.now(),
+			error: result.error,
+		});
+		await stateTracker.appendLog(
+			agent.name,
+			`Iteration ${iteration} ${status}${result.error ? `: ${result.error}` : ""}`,
+		);
+
+		return result;
+	} catch (err) {
+		const error = err instanceof Error ? err.message : String(err);
+		await stateTracker.updateAgent(agent.name, {
+			status: "failed",
+			completedAt: Date.now(),
+			error,
+		});
+		await stateTracker.appendLog(agent.name, `Iteration ${iteration} error: ${error}`);
+		throw err;
+	}
+}
+
+function buildSystemPrompt(agent: SwarmAgent): string {
+	const parts = [`You are a ${agent.role}.`];
+	if (agent.extraContext) {
+		parts.push(agent.extraContext);
+	}
+	return parts.join("\n\n");
+}

package/src/swarm/pipeline.ts

@@ -0,0 +1,212 @@
+/**
+ * Pipeline controller for swarm execution.
+ *
+ * Orchestrates execution waves within each iteration:
+ * - Agents in the same wave execute in parallel
+ * - Waves execute sequentially (wave N+1 starts after wave N completes)
+ * - For pipeline mode, iterations repeat the full DAG execution
+ */
+import type { AgentSource, ModelRegistry, Settings, SingleResult } from "@prometheus-ai/agent";
+import { executeSwarmAgent } from "./executor";
+import type { SwarmDefinition } from "./schema";
+import type { StateTracker } from "./state";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PipelineOptions {
+	workspace: string;
+	signal?: AbortSignal;
+	onProgress?: (state: PipelineProgress) => void;
+	modelRegistry?: ModelRegistry;
+	settings?: Settings;
+}
+
+export interface PipelineProgress {
+	iteration: number;
+	targetCount: number;
+	currentWave: number;
+	totalWaves: number;
+	agents: Record<string, { status: string; iteration: number }>;
+}
+
+export interface PipelineResult {
+	status: "completed" | "failed" | "aborted";
+	iterations: number;
+	agentResults: Map<string, SingleResult[]>;
+	errors: string[];
+}
+
+// ============================================================================
+// Controller
+// ============================================================================
+
+export class PipelineController {
+	#def: SwarmDefinition;
+	#waves: string[][];
+	#stateTracker: StateTracker;
+
+	constructor(def: SwarmDefinition, waves: string[][], stateTracker: StateTracker) {
+		this.#def = def;
+		this.#waves = waves;
+		this.#stateTracker = stateTracker;
+	}
+
+	async run(options: PipelineOptions): Promise<PipelineResult> {
+		const { workspace, signal, onProgress, modelRegistry, settings } = options;
+		const allResults = new Map<string, SingleResult[]>();
+		const errors: string[] = [];
+
+		for (const name of this.#def.agents.keys()) {
+			allResults.set(name, []);
+		}
+
+		const targetCount = this.#def.targetCount;
+
+		await this.#stateTracker.appendOrchestratorLog(
+			`Pipeline '${this.#def.name}' starting: mode=${this.#def.mode} iterations=${targetCount} waves=${this.#waves.length} agents=${this.#def.agents.size}`,
+		);
+
+		try {
+			for (let iteration = 0; iteration < targetCount; iteration++) {
+				if (signal?.aborted) {
+					await this.#stateTracker.updatePipeline({ status: "aborted" });
+					return { status: "aborted", iterations: iteration, agentResults: allResults, errors };
+				}
+
+				await this.#stateTracker.updatePipeline({ iteration });
+				await this.#stateTracker.appendOrchestratorLog(`--- Iteration ${iteration + 1}/${targetCount} ---`);
+
+				const emitProgress = (currentWave: number) => {
+					onProgress?.({
+						iteration,
+						targetCount,
+						currentWave,
+						totalWaves: this.#waves.length,
+						agents: this.#buildProgressSnapshot(),
+					});
+				};
+
+				const iterationResults = await this.#runIteration(iteration, {
+					workspace,
+					signal,
+					emitProgress,
+					modelRegistry,
+					settings,
+				});
+
+				for (const [agentName, result] of iterationResults) {
+					allResults.get(agentName)!.push(result);
+					if (result.exitCode !== 0) {
+						errors.push(
+							`${agentName} (iteration ${iteration + 1}): ${result.error || `exit code ${result.exitCode}`}`,
+						);
+					}
+				}
+			}
+
+			const status = errors.length > 0 ? ("failed" as const) : ("completed" as const);
+			await this.#stateTracker.updatePipeline({ status, completedAt: Date.now() });
+			await this.#stateTracker.appendOrchestratorLog(`Pipeline ${status} (${errors.length} errors)`);
+			return { status, iterations: targetCount, agentResults: allResults, errors };
+		} catch (err) {
+			const error = err instanceof Error ? err.message : String(err);
+			await this.#stateTracker.updatePipeline({ status: "failed", completedAt: Date.now() });
+			await this.#stateTracker.appendOrchestratorLog(`Pipeline fatal error: ${error}`);
+			errors.push(error);
+			return { status: "failed", iterations: 0, agentResults: allResults, errors };
+		}
+	}
+
+	async #runIteration(
+		iteration: number,
+		options: {
+			workspace: string;
+			signal?: AbortSignal;
+			emitProgress: (currentWave: number) => void;
+			modelRegistry?: ModelRegistry;
+			settings?: Settings;
+		},
+	): Promise<Map<string, SingleResult>> {
+		const results = new Map<string, SingleResult>();
+		let agentIndex = 0;
+
+		for (let waveIdx = 0; waveIdx < this.#waves.length; waveIdx++) {
+			const wave = this.#waves[waveIdx];
+
+			if (options.signal?.aborted) break;
+
+			await this.#stateTracker.appendOrchestratorLog(
+				`Wave ${waveIdx + 1}/${this.#waves.length}: [${wave.join(", ")}]`,
+			);
+
+			// Mark agents in this wave as waiting
+			for (const agentName of wave) {
+				await this.#stateTracker.updateAgent(agentName, {
+					status: "waiting",
+					iteration,
+					wave: waveIdx,
+				});
+			}
+			options.emitProgress(waveIdx);
+
+			// Execute all agents in wave in parallel, catching per-agent errors
+			const waveResults = await Promise.all(
+				wave.map(async agentName => {
+					const agent = this.#def.agents.get(agentName)!;
+					const currentIndex = agentIndex++;
+					try {
+						const result = await executeSwarmAgent(agent, currentIndex, {
+							workspace: options.workspace,
+							swarmName: this.#def.name,
+							iteration,
+							modelOverride: agent.model ?? this.#def.model,
+							signal: options.signal,
+							onProgress: (_name, _progress) => {
+								options.emitProgress(waveIdx);
+							},
+							modelRegistry: options.modelRegistry,
+							settings: options.settings,
+							stateTracker: this.#stateTracker,
+						});
+						return { agentName, result };
+					} catch (err) {
+						const error = err instanceof Error ? err.message : String(err);
+						const failResult: SingleResult = {
+							index: currentIndex,
+							id: `swarm-${this.#def.name}-${agentName}-${iteration}`,
+							agent: agentName,
+							agentSource: "project" as AgentSource,
+							task: agent.task,
+							exitCode: 1,
+							output: "",
+							stderr: error,
+							truncated: false,
+							durationMs: 0,
+							tokens: 0,
+							error,
+						};
+						return { agentName, result: failResult };
+					}
+				}),
+			);
+
+			for (const { agentName, result } of waveResults) {
+				results.set(agentName, result);
+			}
+
+			options.emitProgress(waveIdx);
+		}
+
+		return results;
+	}
+
+	#buildProgressSnapshot(): Record<string, { status: string; iteration: number }> {
+		const snapshot: Record<string, { status: string; iteration: number }> = {};
+		for (const [name, agent] of Object.entries(this.#stateTracker.state.agents)) {
+			snapshot[name] = { status: agent.status, iteration: agent.iteration };
+		}
+		return snapshot;
+	}
+}

package/src/swarm/render.ts

@@ -0,0 +1,63 @@
+/**
+ * TUI progress rendering for swarm pipeline status.
+ */
+import { formatDuration, truncate } from "@prometheus-ai/utils";
+import type { AgentState, SwarmState } from "./state";
+
+const STATUS_LABELS: Record<string, string> = {
+	completed: "[done]",
+	running: "[....]",
+	failed: "[FAIL]",
+	pending: "[    ]",
+	waiting: "[wait]",
+	idle: "[idle]",
+	aborted: "[stop]",
+};
+
+export function renderSwarmProgress(state: SwarmState): string[] {
+	const lines: string[] = [];
+
+	const statusLabel = state.status.toUpperCase();
+	lines.push(`Swarm: ${state.name} [${statusLabel}]`);
+	lines.push(`Mode: ${state.mode} | Iteration: ${state.iteration + 1}/${state.targetCount}`);
+	lines.push("");
+
+	const agents: AgentState[] = Object.values(state.agents);
+	if (agents.length === 0) {
+		lines.push("  (no agents)");
+		return lines;
+	}
+
+	for (const agent of agents) {
+		const icon = STATUS_LABELS[agent.status] ?? "[????]";
+		const duration = formatAgentDuration(agent);
+		const errorSuffix = agent.error ? ` - ${truncate(agent.error, 60)}` : "";
+		lines.push(`  ${icon} ${agent.name}: ${agent.status}${duration}${errorSuffix}`);
+	}
+
+	// Summary line
+	const completed = agents.filter(a => a.status === "completed").length;
+	const failed = agents.filter(a => a.status === "failed").length;
+	const running = agents.filter(a => a.status === "running").length;
+
+	lines.push("");
+	const parts = [`${completed}/${agents.length} done`];
+	if (running > 0) parts.push(`${running} running`);
+	if (failed > 0) parts.push(`${failed} failed`);
+	if (state.startedAt) {
+		parts.push(`elapsed: ${formatDuration(Date.now() - state.startedAt)}`);
+	}
+	lines.push(`  ${parts.join(" | ")}`);
+
+	return lines;
+}
+
+function formatAgentDuration(agent: { startedAt?: number; completedAt?: number; status: string }): string {
+	if (agent.startedAt && agent.completedAt) {
+		return ` (${formatDuration(agent.completedAt - agent.startedAt)})`;
+	}
+	if (agent.startedAt && (agent.status === "running" || agent.status === "waiting")) {
+		return ` (${formatDuration(Date.now() - agent.startedAt)}...)`;
+	}
+	return "";
+}

package/src/swarm/schema.ts

@@ -0,0 +1,157 @@
+// ============================================================================
+// Raw YAML shape (snake_case, optional fields)
+// ============================================================================
+
+interface RawSwarmAgentConfig {
+	role: string;
+	task: string;
+	extra_context?: string;
+	reports_to?: string[];
+	waits_for?: string[];
+	model?: string;
+}
+
+interface RawSwarmConfig {
+	name: string;
+	workspace: string;
+	mode?: string;
+	target_count?: number;
+	model?: string;
+	agents: Record<string, RawSwarmAgentConfig>;
+}
+
+// ============================================================================
+// Normalized types (camelCase, defaults applied)
+// ============================================================================
+
+export type SwarmMode = "pipeline" | "parallel" | "sequential";
+
+export interface SwarmAgent {
+	name: string;
+	role: string;
+	task: string;
+	extraContext?: string;
+	reportsTo: string[];
+	waitsFor: string[];
+	model?: string;
+}
+
+export interface SwarmDefinition {
+	name: string;
+	workspace: string;
+	mode: SwarmMode;
+	targetCount: number;
+	model?: string;
+	agents: Map<string, SwarmAgent>;
+	/** Preserves YAML declaration order for implicit pipeline sequencing. */
+	agentOrder: string[];
+}
+
+// ============================================================================
+// Parsing
+// ============================================================================
+
+const VALID_MODES = new Set<string>(["pipeline", "parallel", "sequential"]);
+const VALID_SWARM_NAME = /^[a-zA-Z0-9._-]+$/;
+
+export function parseSwarmYaml(content: string): SwarmDefinition {
+	const raw = Bun.YAML.parse(content) as { swarm?: RawSwarmConfig } | null;
+	if (!raw?.swarm) {
+		throw new Error("YAML must have a top-level 'swarm' key");
+	}
+	const swarm = raw.swarm;
+
+	if (!swarm.name || typeof swarm.name !== "string") {
+		throw new Error("swarm.name is required and must be a string");
+	}
+	if (!VALID_SWARM_NAME.test(swarm.name)) {
+		throw new Error("swarm.name may only contain letters, numbers, dot, underscore, and dash");
+	}
+	if (!swarm.workspace || typeof swarm.workspace !== "string") {
+		throw new Error("swarm.workspace is required and must be a string");
+	}
+	if (!swarm.agents || typeof swarm.agents !== "object" || Object.keys(swarm.agents).length === 0) {
+		throw new Error("swarm.agents must contain at least one agent");
+	}
+
+	const mode = swarm.mode ?? "sequential";
+	if (!VALID_MODES.has(mode)) {
+		throw new Error(`Invalid mode '${mode}'. Must be one of: ${[...VALID_MODES].join(", ")}`);
+	}
+
+	const agentOrder: string[] = [];
+	const agents = new Map<string, SwarmAgent>();
+
+	for (const [name, config] of Object.entries(swarm.agents)) {
+		if (!config.role || typeof config.role !== "string") {
+			throw new Error(`Agent '${name}': 'role' is required`);
+		}
+		if (!config.task || typeof config.task !== "string") {
+			throw new Error(`Agent '${name}': 'task' is required`);
+		}
+
+		agentOrder.push(name);
+		agents.set(name, {
+			name,
+			role: config.role,
+			task: config.task.trim(),
+			extraContext: config.extra_context?.trim(),
+			reportsTo: Array.isArray(config.reports_to) ? config.reports_to : [],
+			model: typeof config.model === "string" ? config.model.trim() : undefined,
+			waitsFor: Array.isArray(config.waits_for) ? config.waits_for : [],
+		});
+	}
+
+	return {
+		name: swarm.name,
+		workspace: swarm.workspace,
+		mode: mode as SwarmMode,
+		targetCount: swarm.target_count ?? 1,
+		model: typeof swarm.model === "string" ? swarm.model.trim() : undefined,
+		agents,
+		agentOrder,
+	};
+}
+
+// ============================================================================
+// Validation (semantic — references, constraints)
+// ============================================================================
+
+export function validateSwarmDefinition(def: SwarmDefinition): string[] {
+	const errors: string[] = [];
+	const agentNames = new Set(def.agents.keys());
+
+	if (def.model !== undefined && def.model.length === 0) {
+		errors.push("swarm.model must not be empty when provided");
+	}
+	for (const [name, agent] of def.agents) {
+		for (const dep of agent.waitsFor) {
+			if (!agentNames.has(dep)) {
+				errors.push(`Agent '${name}' waits_for unknown agent '${dep}'`);
+			}
+			if (dep === name) {
+				errors.push(`Agent '${name}' cannot wait for itself`);
+			}
+		}
+		for (const target of agent.reportsTo) {
+			if (!agentNames.has(target)) {
+				errors.push(`Agent '${name}' reports_to unknown agent '${target}'`);
+			}
+			if (target === name) {
+				errors.push(`Agent '${name}' cannot report to itself`);
+			}
+		}
+		if (agent.model !== undefined && agent.model.length === 0) {
+			errors.push(`Agent '${name}' model must not be empty when provided`);
+		}
+	}
+
+	if (def.targetCount < 1) {
+		errors.push("target_count must be at least 1");
+	}
+	if (def.mode !== "pipeline" && def.targetCount !== 1) {
+		errors.push("target_count is only supported in pipeline mode");
+	}
+
+	return errors;
+}

package/src/swarm/state.ts

@@ -0,0 +1,127 @@
+/**
+ * Filesystem state tracker for swarm pipeline execution.
+ *
+ * Persists pipeline and per-agent state to `.swarm_<name>/` in the workspace.
+ * Supports resumability by loading state from disk.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+// ============================================================================
+// State types
+// ============================================================================
+
+export type PipelineStatus = "idle" | "running" | "completed" | "failed" | "aborted";
+export type AgentStatus = "pending" | "waiting" | "running" | "completed" | "failed";
+
+export interface AgentState {
+	name: string;
+	status: AgentStatus;
+	iteration: number;
+	wave: number;
+	startedAt?: number;
+	completedAt?: number;
+	error?: string;
+}
+
+export interface SwarmState {
+	name: string;
+	status: PipelineStatus;
+	mode: string;
+	iteration: number;
+	targetCount: number;
+	agents: Record<string, AgentState>;
+	startedAt: number;
+	completedAt?: number;
+}
+
+// ============================================================================
+// State tracker
+// ============================================================================
+
+export class StateTracker {
+	#swarmDir: string;
+	#state: SwarmState;
+
+	constructor(workspaceDir: string, name: string) {
+		this.#swarmDir = path.join(workspaceDir, `.swarm_${name}`);
+		this.#state = {
+			name,
+			status: "idle",
+			mode: "sequential",
+			iteration: 0,
+			targetCount: 1,
+			agents: {},
+			startedAt: Date.now(),
+		};
+	}
+
+	get swarmDir(): string {
+		return this.#swarmDir;
+	}
+
+	get state(): Readonly<SwarmState> {
+		return this.#state;
+	}
+
+	async init(agentNames: string[], targetCount: number, mode: string): Promise<void> {
+		await fs.mkdir(path.join(this.#swarmDir, "state"), { recursive: true });
+		await fs.mkdir(path.join(this.#swarmDir, "logs"), { recursive: true });
+		await fs.mkdir(path.join(this.#swarmDir, "context"), { recursive: true });
+
+		this.#state.targetCount = targetCount;
+		this.#state.mode = mode;
+		this.#state.status = "running";
+		this.#state.startedAt = Date.now();
+
+		for (const name of agentNames) {
+			this.#state.agents[name] = {
+				name,
+				status: "pending",
+				iteration: 0,
+				wave: 0,
+			};
+		}
+
+		await this.#persist();
+	}
+
+	async updateAgent(name: string, update: Partial<AgentState>): Promise<void> {
+		const agent = this.#state.agents[name];
+		if (!agent) return;
+		Object.assign(agent, update);
+		await this.#persist();
+	}
+
+	async updatePipeline(update: Partial<SwarmState>): Promise<void> {
+		Object.assign(this.#state, update);
+		await this.#persist();
+	}
+
+	async appendLog(agentName: string, message: string): Promise<void> {
+		const logPath = path.join(this.#swarmDir, "logs", `${agentName}.log`);
+		const timestamp = new Date().toISOString();
+		await fs.appendFile(logPath, `[${timestamp}] ${message}\n`);
+	}
+
+	async appendOrchestratorLog(message: string): Promise<void> {
+		const logPath = path.join(this.#swarmDir, "logs", "orchestrator.log");
+		const timestamp = new Date().toISOString();
+		await fs.appendFile(logPath, `[${timestamp}] ${message}\n`);
+	}
+
+	async load(): Promise<SwarmState | null> {
+		const statePath = path.join(this.#swarmDir, "state", "pipeline.json");
+		try {
+			const content = await Bun.file(statePath).text();
+			this.#state = JSON.parse(content) as SwarmState;
+			return this.#state;
+		} catch {
+			return null;
+		}
+	}
+
+	async #persist(): Promise<void> {
+		await Bun.write(path.join(this.#swarmDir, "state", "pipeline.json"), JSON.stringify(this.#state, null, 2));
+	}
+}