@prometheus-ai/swarm-extension 0.5.1

package/package.json

@@ -0,0 +1,64 @@
+{
+	"type": "module",
+	"name": "@prometheus-ai/swarm-extension",
+	"version": "0.5.1",
+	"description": "Swarm orchestration extension for prometheus",
+	"homepage": "https://prometheus.trivlab.com",
+	"author": "Derek Rynd",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/uttamtrivedi/Prometheus.git",
+		"directory": "packages/swarm-extension"
+	},
+	"bugs": {
+		"url": "https://github.com/uttamtrivedi/Prometheus/issues"
+	},
+	"keywords": [
+		"swarm",
+		"orchestration",
+		"agent",
+		"extension"
+	],
+	"main": "./src/extension.ts",
+	"types": "./dist/types/extension.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/extension.d.ts",
+			"import": "./src/extension.ts"
+		}
+	},
+	"bin": {
+		"prometheus-swarm": "src/cli.ts"
+	},
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@prometheus-ai/utils": "0.5.1"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"peerDependencies": {
+		"@prometheus-ai/agent": "0.5.1"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"prometheus": {
+		"extensions": [
+			"./src/extension.ts"
+		]
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	]
+}

package/src/cli.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * Direct pipeline runner — executes a swarm pipeline outside of the TUI.
+ *
+ * Usage: bun cli.ts <path-to-yaml>
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { discoverAuthStorage } from "@prometheus-ai/agent";
+import { ModelRegistry } from "@prometheus-ai/agent/config/model-registry";
+import { Settings } from "@prometheus-ai/agent/config/settings";
+import { buildDependencyGraph, buildExecutionWaves, detectCycles } from "./swarm/dag";
+import { PipelineController } from "./swarm/pipeline";
+import { renderSwarmProgress } from "./swarm/render";
+import { parseSwarmYaml, validateSwarmDefinition } from "./swarm/schema";
+import { StateTracker } from "./swarm/state";
+
+const yamlPath = process.argv[2];
+if (!yamlPath) {
+	console.error("Usage: prometheus-swarm <path-to-yaml>");
+	process.exit(1);
+}
+
+const resolvedPath = path.resolve(yamlPath);
+console.log(`Reading: ${resolvedPath}`);
+
+const content = await Bun.file(resolvedPath).text();
+const def = parseSwarmYaml(content);
+
+console.log(`Swarm: ${def.name}`);
+console.log(`Mode: ${def.mode}`);
+console.log(`Target count: ${def.targetCount}`);
+console.log(`Agents: ${[...def.agents.keys()].join(", ")}`);
+
+// Validate
+const errors = validateSwarmDefinition(def);
+if (errors.length > 0) {
+	console.error("Validation errors:", errors);
+	process.exit(1);
+}
+
+// Build DAG
+const deps = buildDependencyGraph(def);
+const cycles = detectCycles(deps);
+if (cycles) {
+	console.error("Cycle detected:", cycles);
+	process.exit(1);
+}
+const waves = buildExecutionWaves(deps);
+console.log(`Waves: ${waves.map((w, i) => `W${i + 1}:[${w.join(",")}]`).join(" -> ")}`);
+
+// Resolve workspace
+const workspace = path.isAbsolute(def.workspace)
+	? def.workspace
+	: path.resolve(path.dirname(resolvedPath), def.workspace);
+
+await fs.mkdir(workspace, { recursive: true });
+console.log(`Workspace: ${workspace}`);
+
+// Initialize
+const stateTracker = new StateTracker(workspace, def.name);
+await stateTracker.init([...def.agents.keys()], def.targetCount, def.mode);
+
+// Auth + settings
+const authStorage = await discoverAuthStorage();
+const modelRegistry = new ModelRegistry(authStorage);
+const settings = Settings.isolated();
+
+// Progress display
+let lastProgressDump = 0;
+const PROGRESS_INTERVAL_MS = 5000;
+
+// Run
+console.log("\n--- Pipeline starting ---\n");
+
+const controller = new PipelineController(def, waves, stateTracker);
+const result = await controller.run({
+	workspace,
+	onProgress: () => {
+		const now = Date.now();
+		if (now - lastProgressDump > PROGRESS_INTERVAL_MS) {
+			lastProgressDump = now;
+			const lines = renderSwarmProgress(stateTracker.state);
+			console.log(lines.join("\n"));
+			console.log();
+		}
+	},
+	modelRegistry,
+	settings,
+});
+
+console.log("\n--- Pipeline finished ---\n");
+console.log(`Status: ${result.status}`);
+console.log(`Iterations completed: ${result.iterations}/${def.targetCount}`);
+if (result.errors.length > 0) {
+	console.log(`Errors (${result.errors.length}):`);
+	for (const err of result.errors) {
+		console.log(`  - ${err}`);
+	}
+}
+console.log(`\nState saved to: ${stateTracker.swarmDir}`);
+
+// Final state dump
+const lines = renderSwarmProgress(stateTracker.state);
+console.log(lines.join("\n"));

package/src/extension.ts

@@ -0,0 +1,256 @@
+/**
+ * Swarm Extension — Multi-agent pipeline orchestration from YAML definitions.
+ *
+ * Registers:
+ * - /swarm run <file.yaml>   — Execute a swarm pipeline
+ * - /swarm status             — Show current pipeline status
+ *
+ * Usage: Add this extension's directory to your extensions config,
+ * then use /swarm in any prometheus session.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@prometheus-ai/agent";
+import { formatDuration } from "@prometheus-ai/utils";
+import { buildDependencyGraph, buildExecutionWaves, detectCycles } from "./swarm/dag";
+import { PipelineController } from "./swarm/pipeline";
+import { renderSwarmProgress } from "./swarm/render";
+import { parseSwarmYaml, type SwarmDefinition, validateSwarmDefinition } from "./swarm/schema";
+import { StateTracker } from "./swarm/state";
+
+export default function swarmExtension(pi: ExtensionAPI): void {
+	pi.setLabel("Swarm Orchestrator");
+
+	pi.registerCommand("swarm", {
+		description: "Run a multi-agent swarm pipeline from YAML",
+		getArgumentCompletions: prefix => {
+			const subcommands = ["run", "status", "help"];
+			if (!prefix) return subcommands.map(s => ({ label: s, value: s }));
+			return subcommands.filter(s => s.startsWith(prefix)).map(s => ({ label: s, value: s }));
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const parts = args.trim().split(/\s+/);
+			const subcommand = parts[0] ?? "help";
+
+			switch (subcommand) {
+				case "run": {
+					const yamlPath = parts[1];
+					if (!yamlPath) {
+						ctx.ui.notify("Usage: /swarm run <path/to/pipeline.yaml>", "error");
+						return;
+					}
+					await handleRun(yamlPath, ctx, pi);
+					return;
+				}
+				case "status": {
+					await handleStatus(parts[1], ctx);
+					return;
+				}
+				default:
+					ctx.ui.notify(
+						[
+							"Swarm — multi-agent pipeline orchestrator",
+							"",
+							"  /swarm run <file.yaml>     Run a pipeline",
+							"  /swarm status [name]       Show pipeline status",
+							"  /swarm help                Show this help",
+						].join("\n"),
+						"info",
+					);
+					return;
+			}
+		},
+	});
+}
+
+// ============================================================================
+// /swarm run
+// ============================================================================
+
+async function handleRun(yamlPath: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+	// 1. Resolve and read YAML
+	const resolvedPath = path.isAbsolute(yamlPath) ? yamlPath : path.resolve(ctx.cwd, yamlPath);
+
+	let content: string;
+	try {
+		content = await Bun.file(resolvedPath).text();
+	} catch {
+		ctx.ui.notify(`Cannot read file: ${resolvedPath}`, "error");
+		return;
+	}
+
+	// 2. Parse YAML
+	let def: SwarmDefinition;
+	try {
+		def = parseSwarmYaml(content);
+	} catch (err) {
+		ctx.ui.notify(`YAML error: ${err instanceof Error ? err.message : String(err)}`, "error");
+		return;
+	}
+
+	// 3. Validate
+	const validationErrors = validateSwarmDefinition(def);
+	if (validationErrors.length > 0) {
+		ctx.ui.notify(`Validation errors:\n${validationErrors.map(e => `  - ${e}`).join("\n")}`, "error");
+		return;
+	}
+
+	// 4. Build DAG
+	const deps = buildDependencyGraph(def);
+	const cycleNodes = detectCycles(deps);
+	if (cycleNodes) {
+		ctx.ui.notify(`Cycle detected in agent dependencies: [${cycleNodes.join(", ")}]`, "error");
+		return;
+	}
+	const waves = buildExecutionWaves(deps);
+
+	// 5. Resolve workspace (relative to YAML file location)
+	const workspace = path.isAbsolute(def.workspace)
+		? def.workspace
+		: path.resolve(path.dirname(resolvedPath), def.workspace);
+
+	// Ensure workspace exists
+	await fs.mkdir(workspace, { recursive: true });
+
+	// 6. Initialize state tracker
+	const stateTracker = new StateTracker(workspace, def.name);
+	await stateTracker.init([...def.agents.keys()], def.targetCount, def.mode);
+
+	// 7. Log start
+	const agentList = [...def.agents.keys()].join(", ");
+	const waveDesc = waves.map((w, i) => `wave ${i + 1}: [${w.join(", ")}]`).join("; ");
+	pi.logger.debug("Swarm starting", {
+		name: def.name,
+		mode: def.mode,
+		agents: agentList,
+		waves: waveDesc,
+		workspace,
+	});
+
+	ctx.ui.notify(
+		`Starting swarm '${def.name}': ${def.agents.size} agents, ${waves.length} waves, ${def.targetCount} iteration(s)`,
+		"info",
+	);
+
+	// 8. Set up progress widget
+	const widgetKey = `swarm-${def.name}`;
+	const updateWidget = () => {
+		const lines = renderSwarmProgress(stateTracker.state);
+		ctx.ui.setWidget(widgetKey, lines);
+	};
+	updateWidget();
+
+	// 9. Run pipeline
+	const controller = new PipelineController(def, waves, stateTracker);
+
+	const result = await controller.run({
+		workspace,
+		onProgress: () => updateWidget(),
+		modelRegistry: ctx.modelRegistry,
+		settings: pi.pi.settings,
+	});
+
+	// 10. Clear widget and show summary
+	ctx.ui.setWidget(widgetKey, undefined);
+
+	const elapsed = stateTracker.state.completedAt
+		? formatDuration(stateTracker.state.completedAt - stateTracker.state.startedAt)
+		: "unknown";
+
+	const summaryParts = [
+		`Swarm '${def.name}' ${result.status}`,
+		`${result.iterations}/${def.targetCount} iterations`,
+		`elapsed: ${elapsed}`,
+	];
+
+	if (result.errors.length > 0) {
+		summaryParts.push(`${result.errors.length} error(s)`);
+	}
+
+	const summaryType = result.status === "completed" ? "info" : "error";
+	ctx.ui.notify(summaryParts.join(" | "), summaryType);
+
+	// Log errors
+	if (result.errors.length > 0) {
+		pi.logger.warn("Swarm completed with errors", { errors: result.errors });
+	}
+
+	// 11. Send summary to the conversation so the LLM knows what happened
+	const summaryMessage = buildSummaryMessage(def, result, stateTracker, workspace);
+	pi.sendMessage(
+		{
+			customType: "swarm-result",
+			content: [{ type: "text", text: summaryMessage }],
+			display: true,
+			details: {
+				swarmName: def.name,
+				status: result.status,
+				iterations: result.iterations,
+				errorCount: result.errors.length,
+			},
+		},
+		{ triggerTurn: false },
+	);
+}
+
+// ============================================================================
+// /swarm status
+// ============================================================================
+
+async function handleStatus(name: string | undefined, ctx: ExtensionCommandContext): Promise<void> {
+	if (!name) {
+		ctx.ui.notify("Usage: /swarm status <name>  (reads .swarm_<name>/state/pipeline.json from cwd)", "info");
+		return;
+	}
+
+	const stateTracker = new StateTracker(ctx.cwd, name);
+	const state = await stateTracker.load();
+	if (!state) {
+		ctx.ui.notify(`No state found for swarm '${name}' in ${ctx.cwd}`, "error");
+		return;
+	}
+
+	const lines = renderSwarmProgress(state);
+	ctx.ui.notify(lines.join("\n"), "info");
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function buildSummaryMessage(
+	def: SwarmDefinition,
+	result: { status: string; iterations: number; errors: string[] },
+	stateTracker: StateTracker,
+	workspace: string,
+): string {
+	const lines: string[] = [];
+	lines.push(`## Swarm Pipeline: ${def.name}`);
+	lines.push("");
+	lines.push(`- **Status**: ${result.status}`);
+	lines.push(`- **Mode**: ${def.mode}`);
+	lines.push(`- **Iterations**: ${result.iterations}/${def.targetCount}`);
+	lines.push(`- **Workspace**: ${workspace}`);
+	lines.push(`- **State dir**: ${stateTracker.swarmDir}`);
+	lines.push("");
+
+	lines.push("### Agent Results");
+	lines.push("");
+	for (const [name, agent] of Object.entries(stateTracker.state.agents)) {
+		const duration =
+			agent.startedAt && agent.completedAt ? formatDuration(agent.completedAt - agent.startedAt) : "n/a";
+		lines.push(`- **${name}**: ${agent.status} (${duration})${agent.error ? ` — ${agent.error}` : ""}`);
+	}
+
+	if (result.errors.length > 0) {
+		lines.push("");
+		lines.push("### Errors");
+		lines.push("");
+		for (const error of result.errors) {
+			lines.push(`- ${error}`);
+		}
+	}
+
+	return lines.join("\n");
+}

package/src/swarm/__tests__/executor.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ModelRegistry, SingleResult } from "@prometheus-ai/agent";
+import * as taskExecutor from "@prometheus-ai/agent";
+import { executeSwarmAgent } from "../executor";
+import { StateTracker } from "../state";
+
+const mockResult = {
+	index: 0,
+	id: "test-agent-0",
+	agent: "test",
+	agentSource: "project",
+	task: "test task",
+	exitCode: 0,
+	output: "ok",
+	stderr: "",
+	truncated: false,
+	durationMs: 100,
+	tokens: 0,
+} as SingleResult;
+
+let workspace: string;
+
+beforeEach(async () => {
+	workspace = await fs.mkdtemp(path.join(os.tmpdir(), "swarm-test-"));
+});
+
+afterEach(async () => {
+	vi.restoreAllMocks();
+	await fs.rm(workspace, { recursive: true, force: true });
+});
+
+describe("executeSwarmAgent", () => {
+	it("does not pass authStorage to runSubprocess when modelRegistry is provided", async () => {
+		const runSubprocessSpy = vi.spyOn(taskExecutor, "runSubprocess").mockResolvedValue(mockResult);
+
+		const mockModelRegistry = {
+			authStorage: { discover: vi.fn() },
+		} as unknown as ModelRegistry;
+
+		const stateTracker = new StateTracker(workspace, "test-swarm");
+		await stateTracker.init(["test-agent"], 1, "parallel");
+
+		const agent = {
+			name: "test-agent",
+			role: "tester",
+			task: "do something",
+			reportsTo: [],
+			waitsFor: [],
+		};
+
+		await executeSwarmAgent(agent, 0, {
+			workspace,
+			swarmName: "test-swarm",
+			iteration: 0,
+			modelRegistry: mockModelRegistry,
+			stateTracker,
+		});
+
+		expect(runSubprocessSpy).toHaveBeenCalledTimes(1);
+		const passedOptions = runSubprocessSpy.mock.calls[0][0];
+		const { authStorage, modelRegistry } = passedOptions;
+		expect(authStorage).toBeUndefined();
+		expect(modelRegistry).toBe(mockModelRegistry);
+	});
+});

package/src/swarm/dag.ts

@@ -0,0 +1,146 @@
+/**
+ * Directed Acyclic Graph operations for swarm agent dependencies.
+ *
+ * Builds a dependency graph from waits_for / reports_to relationships,
+ * detects cycles, and produces execution waves via topological sort.
+ */
+import type { SwarmDefinition } from "./schema";
+
+/**
+ * Build a dependency map: agent name → set of agents it depends on.
+ *
+ * Dependencies come from:
+ * 1. Explicit `waits_for` declarations
+ * 2. Implicit from `reports_to` (if A reports_to B, then B depends on A)
+ * 3. For pipeline/sequential mode with no explicit deps: chain by YAML declaration order
+ */
+export function buildDependencyGraph(def: SwarmDefinition): Map<string, Set<string>> {
+	const deps = new Map<string, Set<string>>();
+
+	for (const name of def.agents.keys()) {
+		deps.set(name, new Set());
+	}
+
+	// Explicit waits_for
+	for (const [name, agent] of def.agents) {
+		for (const dep of agent.waitsFor) {
+			if (deps.has(dep)) {
+				deps.get(name)!.add(dep);
+			}
+		}
+	}
+
+	// reports_to implies the target waits for the reporter
+	for (const [name, agent] of def.agents) {
+		for (const target of agent.reportsTo) {
+			if (deps.has(target)) {
+				deps.get(target)!.add(name);
+			}
+		}
+	}
+
+	// For pipeline/sequential with no explicit deps, chain by declaration order
+	if ((def.mode === "pipeline" || def.mode === "sequential") && !hasExplicitDeps(deps)) {
+		for (let i = 1; i < def.agentOrder.length; i++) {
+			deps.get(def.agentOrder[i])!.add(def.agentOrder[i - 1]);
+		}
+	}
+
+	return deps;
+}
+
+function hasExplicitDeps(deps: Map<string, Set<string>>): boolean {
+	for (const s of deps.values()) {
+		if (s.size > 0) return true;
+	}
+	return false;
+}
+
+/**
+ * Detect cycles in the dependency graph.
+ * Returns the names of agents involved in cycles, or null if acyclic.
+ */
+export function detectCycles(deps: Map<string, Set<string>>): string[] | null {
+	// Kahn's algorithm: if topological sort doesn't include all nodes, cycles exist
+	const inDegree = new Map<string, number>();
+	const forward = new Map<string, string[]>(); // dependency → its dependents
+
+	for (const [node, nodeDeps] of deps) {
+		inDegree.set(node, nodeDeps.size);
+		for (const dep of nodeDeps) {
+			const list = forward.get(dep) ?? [];
+			list.push(node);
+			forward.set(dep, list);
+		}
+	}
+
+	const queue: string[] = [];
+	for (const [node, degree] of inDegree) {
+		if (degree === 0) queue.push(node);
+	}
+
+	const sorted: string[] = [];
+	while (queue.length > 0) {
+		const node = queue.shift()!;
+		sorted.push(node);
+		for (const dependent of forward.get(node) ?? []) {
+			const newDegree = inDegree.get(dependent)! - 1;
+			inDegree.set(dependent, newDegree);
+			if (newDegree === 0) queue.push(dependent);
+		}
+	}
+
+	if (sorted.length < deps.size) {
+		return [...deps.keys()].filter(k => !sorted.includes(k));
+	}
+
+	return null;
+}
+
+/**
+ * Build execution waves from dependency graph via topological sort.
+ *
+ * Each wave contains agents whose dependencies are all in earlier waves.
+ * Agents within a wave can execute in parallel.
+ */
+export function buildExecutionWaves(deps: Map<string, Set<string>>): string[][] {
+	const waves: string[][] = [];
+	const completed = new Set<string>();
+	const remaining = new Set(deps.keys());
+
+	while (remaining.size > 0) {
+		const wave: string[] = [];
+
+		for (const node of remaining) {
+			const nodeDeps = deps.get(node)!;
+			let ready = true;
+			for (const dep of nodeDeps) {
+				if (!completed.has(dep)) {
+					ready = false;
+					break;
+				}
+			}
+			if (ready) {
+				wave.push(node);
+			}
+		}
+
+		if (wave.length === 0) {
+			throw new Error(
+				`Deadlock: agents [${[...remaining].join(", ")}] cannot make progress. This indicates a bug in cycle detection.`,
+			);
+		}
+
+		// Sort for deterministic execution order
+		wave.sort();
+
+		for (const node of wave) {
+			remaining.delete(node);
+			completed.add(node);
+		}
+
+		waves.push(wave);
+	}
+
+	return waves;
+}