@buihongduc132/pi-acp-agents 0.3.1

package/src/coordination/alias-resolver.ts

@@ -0,0 +1,208 @@
+/**
+ * pi-acp-agents — Alias resolver with fallback chains.
+ *
+ * Resolves an alias name to a concrete agent using configurable
+ * strategies: failover (sequential) or race (parallel, first wins).
+ */
+import type { AcpAliasConfig, AcpPromptResult } from "../config/types.js";
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class AllAgentsFailedError extends Error {
+	constructor(
+		public readonly attempts: Array<{ agent: string; error: Error }>,
+		aliasName: string,
+	) {
+		super(
+			`All agents failed for alias "${aliasName}": ${attempts.map((a) => a.agent).join(", ")}`,
+		);
+		this.name = "AllAgentsFailedError";
+	}
+}
+
+export class NoHealthyAgentsError extends Error {
+	constructor(aliasName: string) {
+		super(`No healthy agents for alias "${aliasName}"`);
+		this.name = "NoHealthyAgentsError";
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DelegateFn = (
+	agentName: string,
+	message: string,
+	cwd?: string,
+) => Promise<AcpPromptResult>;
+
+export type IsHealthyFn = (agentName: string) => boolean;
+
+/** Called to cancel an in-flight agent request by name */
+export type CancelFn = (agentName: string) => void;
+
+/** Optional config for race strategy */
+export interface AliasResolverConfig {
+	raceTimeoutMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// AliasResolver
+// ---------------------------------------------------------------------------
+
+export class AliasResolver {
+	private readonly raceTimeoutMs: number;
+
+	constructor(
+		private readonly aliases: Record<string, AcpAliasConfig>,
+		private readonly delegateFn: DelegateFn,
+		private readonly isHealthyFn: IsHealthyFn,
+		private readonly cancelFn?: CancelFn,
+		config?: AliasResolverConfig,
+	) {
+		this.raceTimeoutMs = config?.raceTimeoutMs ?? 30_000;
+	}
+
+	/**
+	 * Resolve an alias to a concrete agent result.
+	 *
+	 * @throws Error if alias not found or has no agents
+	 * @throws NoHealthyAgentsError if all agents are unhealthy (circuit open)
+	 * @throws AllAgentsFailedError if all agents in the chain fail
+	 */
+	async resolve(
+		aliasName: string,
+		message: string,
+		cwd?: string,
+	): Promise<AcpPromptResult> {
+		const alias = this.aliases[aliasName];
+		if (!alias) throw new Error(`Alias "${aliasName}" not found`);
+		if (!alias.agents || alias.agents.length === 0)
+			throw new Error(`Alias "${aliasName}" has no agents`);
+
+		// Filter healthy agents based on circuit breaker state
+		const healthyAgents = alias.agents.filter((name) =>
+			this.isHealthyFn(name),
+		);
+
+		if (alias.strategy === "race") {
+			return this.race(aliasName, healthyAgents, message, cwd);
+		}
+		return this.failover(aliasName, healthyAgents, message, cwd);
+	}
+
+	// -------------------------------------------------------------------------
+	// Failover: try agents sequentially, return on first success
+	// -------------------------------------------------------------------------
+
+	private async failover(
+		aliasName: string,
+		agents: string[],
+		message: string,
+		cwd?: string,
+	): Promise<AcpPromptResult> {
+		if (agents.length === 0) throw new NoHealthyAgentsError(aliasName);
+
+		const attempts: Array<{ agent: string; error: Error }> = [];
+
+		for (const agent of agents) {
+			try {
+				return await this.delegateFn(agent, message, cwd);
+			} catch (err) {
+				attempts.push({
+					agent,
+					error: err instanceof Error ? err : new Error(String(err)),
+				});
+			}
+		}
+
+		throw new AllAgentsFailedError(attempts, aliasName);
+	}
+
+	// -------------------------------------------------------------------------
+	// Race: dispatch to all healthy agents in parallel, first response wins.
+	// EC-1: Timeout guard — rejects if no agent responds within raceTimeoutMs.
+	// EC-2: Loser cancellation — aborts all in-flight delegates when one wins.
+	// -------------------------------------------------------------------------
+
+	private async race(
+		aliasName: string,
+		agents: string[],
+		message: string,
+		cwd?: string,
+	): Promise<AcpPromptResult> {
+		if (agents.length === 0) throw new NoHealthyAgentsError(aliasName);
+
+		const abortControllers = new Map<string, AbortController>();
+		const attempts: Array<{ agent: string; error: Error }> = [];
+
+		return new Promise<AcpPromptResult>((resolve, reject) => {
+			let settled = false;
+			let failureCount = 0;
+			const pending = new Set(agents);
+
+			const settle = (result: AcpPromptResult, winnerName: string) => {
+				if (!settled) {
+					settled = true;
+					// EC-2: Cancel all losing agents
+					for (const [name, ctrl] of abortControllers) {
+						if (pending.has(name)) {
+							ctrl.abort();
+							this.cancelFn?.(name);
+						}
+					}
+					resolve(result);
+				}
+			};
+
+			// EC-1: Timeout guard
+			const timer = setTimeout(() => {
+				if (!settled) {
+					settled = true;
+					// Cancel all in-flight delegates
+					for (const name of pending) {
+						const ctrl = abortControllers.get(name);
+						if (ctrl) ctrl.abort();
+						this.cancelFn?.(name);
+					}
+					reject(
+						new Error(
+							`Race timeout for alias "${aliasName}": no agent responded within ${this.raceTimeoutMs}ms`,
+						),
+					);
+				}
+			}, this.raceTimeoutMs);
+
+			for (const agent of agents) {
+				const controller = new AbortController();
+				abortControllers.set(agent, controller);
+
+				this.delegateFn(agent, message, cwd)
+					.then((result) => {
+						pending.delete(agent);
+						settle(result, agent);
+					})
+					.catch((err) => {
+						pending.delete(agent);
+						if (!settled) {
+							attempts.push({
+								agent,
+								error: err instanceof Error
+									? err
+									: new Error(String(err)),
+							});
+							failureCount++;
+							if (failureCount === agents.length) {
+								clearTimeout(timer);
+								settled = true;
+								reject(new AllAgentsFailedError(attempts, aliasName));
+							}
+						}
+					});
+			}
+		});
+	}
+}

package/src/coordination/coordinator.ts

@@ -0,0 +1,266 @@
+/**
+ * pi-acp-agents — Agent Coordinator for Level 3 multi-agent operations.
+ *
+ * Provides delegate, broadcast, compare, and formatComparison operations
+ * across multiple ACP agents. Each operation creates isolated adapter
+ * instances that are disposed after use.
+ */
+import { createAdapter } from "../adapter-factory.js";
+import { AliasResolver } from "./alias-resolver.js";
+import type { AcpConfig, AcpPromptResult } from "../config/types.js";
+
+/** Wrap a promise with a timeout. Throws on expiry with descriptive message. */
+function withTimeoutMs<T>(promise: Promise<T>, ms: number | undefined, label: string): Promise<T> {
+  const effectiveMs = ms ?? 300_000;
+  if (effectiveMs <= 0) return promise;
+  let timer: ReturnType<typeof setTimeout>;
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} timed out after ${effectiveMs}ms`)), effectiveMs);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/** Progress update during delegation */
+export interface AcpDelegateProgress {
+  agentName: string;
+  phase: "spawning" | "initializing" | "prompting" | "done" | "error";
+  durationMs?: number;
+  lastActivityAt?: number;
+  text?: string;
+}
+
+/** Flat result from a single agent in a multi-agent operation */
+export interface AgentResult {
+  agent: string;
+  text: string;
+  sessionId: string;
+  stopReason: string;
+  error?: string;
+}
+
+/** Comparison result from multiple agents */
+export interface ComparisonResult {
+  prompt: string;
+  responses: AgentResult[];
+  timestamp: string;
+}
+
+export interface AgentCoordinatorDeps {
+  /** Check if a specific agent's circuit breaker is healthy */
+  isHealthyFn?: (agentName: string) => boolean;
+  /** Record success/failure for circuit breaker tracking */
+  recordSuccessFn?: (agentName: string) => void;
+  recordFailureFn?: (agentName: string) => void;
+}
+
+export class AgentCoordinator {
+  private isHealthyFn: (agentName: string) => boolean;
+  private recordSuccessFn?: (agentName: string) => void;
+  private recordFailureFn?: (agentName: string) => void;
+
+  constructor(
+    private config: AcpConfig,
+    private cwd: string,
+    deps?: AgentCoordinatorDeps,
+  ) {
+    this.isHealthyFn = deps?.isHealthyFn ?? (() => true);
+    this.recordSuccessFn = deps?.recordSuccessFn;
+    this.recordFailureFn = deps?.recordFailureFn;
+  }
+
+  /** Delegate a task to a single agent or alias. Creates a short-lived session. */
+  async delegate(
+    agentName: string,
+    message: string,
+    cwd?: string,
+    onProgress?: (progress: AcpDelegateProgress) => void,
+    signal?: AbortSignal,
+  ): Promise<AcpPromptResult> {
+    // Pre-aborted check
+    if (signal?.aborted) {
+      const adapter = this.createAdapterForAgent(agentName, cwd);
+      try {
+        adapter.cancel();
+      } catch { /* best-effort */ }
+      try {
+        adapter.dispose();
+      } catch { /* best-effort — dispose must not throw */ }
+      const err = new DOMException("Operation cancelled", "AbortError");
+      onProgress?.({ agentName, phase: "error" });
+      throw err;
+    }
+
+    // Check if it's an alias first
+    const aliasConfig = this.config.agent_aliases?.[agentName];
+    if (aliasConfig) {
+      const isHealthy = this.isHealthyFn;
+      const recordSuccess = this.recordSuccessFn;
+      const recordFailure = this.recordFailureFn;
+      const resolver = new AliasResolver(
+        { [agentName]: aliasConfig },
+        async (name, msg, c) => {
+          try {
+            const result = await this.delegateToAgent(name, msg, c, onProgress, signal);
+            recordSuccess?.(name);
+            return result;
+          } catch (err) {
+            recordFailure?.(name);
+            throw err;
+          }
+        },
+        (name) => isHealthy(name),
+        undefined,
+        this.config.raceTimeoutMs ? { raceTimeoutMs: this.config.raceTimeoutMs } : undefined,
+      );
+      return resolver.resolve(agentName, message, cwd);
+    }
+
+    return this.delegateToAgent(agentName, message, cwd, onProgress, signal);
+  }
+
+  /** Create an adapter for a concrete agent. */
+  private createAdapterForAgent(agentName: string, cwd?: string) {
+    const agentCfg = this.config.agent_servers[agentName];
+    if (!agentCfg) throw new Error(`Agent "${agentName}" not found`);
+    const effectiveCwd = cwd ?? this.cwd;
+    return createAdapter(agentName, agentCfg, this.config, effectiveCwd);
+  }
+
+  /** Delegate directly to a concrete agent. Creates a short-lived session. */
+  private async delegateToAgent(
+    agentName: string,
+    message: string,
+    cwd?: string,
+    onProgress?: (progress: AcpDelegateProgress) => void,
+    signal?: AbortSignal,
+  ): Promise<AcpPromptResult> {
+    const agentCfg = this.config.agent_servers[agentName];
+    if (!agentCfg) throw new Error(`Agent "${agentName}" not found`);
+
+    const effectiveCwd = cwd ?? this.cwd;
+    const adapter = createAdapter(agentName, agentCfg, this.config, effectiveCwd);
+    const startTime = Date.now();
+
+    const emitProgress = (phase: AcpDelegateProgress["phase"]) => {
+      onProgress?.({
+        agentName,
+        phase,
+        durationMs: Date.now() - startTime,
+        lastActivityAt: Date.now(),
+      });
+    };
+
+    // Abort handler: cancel + dispose + reject pending prompt
+    let abortReject: ((err: Error) => void) | null = null;
+    const abortPromise = new Promise<never>((_, reject) => {
+      abortReject = reject;
+    });
+    // Safety: prevent unhandled rejection if abort fires after race settles
+    abortPromise.catch(() => {});
+
+    const onAbort = () => {
+      try { adapter.cancel(); } catch { /* best-effort */ }
+      try { adapter.dispose(); } catch { /* best-effort — dispose must not throw */ }
+      emitProgress("error");
+      abortReject?.(new DOMException("Operation cancelled", "AbortError"));
+    };
+
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    try {
+      emitProgress("spawning");
+      await withTimeoutMs(adapter.spawn(), this.config.stallTimeoutMs, `acp_spawn(delegate:${agentName})`);
+      emitProgress("initializing");
+      await adapter.initialize();
+      await adapter.newSession(effectiveCwd);
+      emitProgress("prompting");
+      const promptPromise = adapter.prompt(message);
+      // Prevent unhandled rejection if abort wins the race
+      promptPromise.catch(() => {});
+      return await Promise.race([promptPromise, abortPromise]);
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+      try { adapter.dispose(); } catch { /* best-effort — dispose must not mask errors */ }
+    }
+  }
+
+  /** Broadcast the same prompt to multiple agents in parallel. */
+  async broadcast(
+    agentNames: string[],
+    message: string,
+    cwd?: string,
+  ): Promise<AgentResult[]> {
+    const results = await Promise.allSettled(
+      agentNames.map(async (name): Promise<AgentResult> => {
+        try {
+          const result = await this.delegate(name, message, cwd);
+          return {
+            agent: name,
+            text: result.text,
+            sessionId: result.sessionId,
+            stopReason: result.stopReason,
+          };
+        } catch (err: unknown) {
+          const msg = err instanceof Error ? err.message : String(err);
+          return {
+            agent: name,
+            text: "",
+            sessionId: "",
+            stopReason: "error",
+            error: msg,
+          };
+        }
+      }),
+    );
+
+    return results.map((r) =>
+      r.status === "fulfilled"
+        ? r.value
+        : { agent: "unknown", text: "", sessionId: "", stopReason: "error", error: String(r.reason) },
+    );
+  }
+
+  /** Get responses from multiple agents and return structured comparison. */
+  async compare(
+    agentNames: string[],
+    message: string,
+    cwd?: string,
+  ): Promise<ComparisonResult> {
+    const responses = await this.broadcast(agentNames, message, cwd);
+    return {
+      prompt: message,
+      responses,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /** Format a comparison result as readable text */
+  formatComparison(comparison: {
+    prompt: string;
+    responses: Array<{
+      agent: string;
+      text?: string;
+      sessionId?: string;
+      stopReason?: string;
+      error?: string;
+    }>;
+    timestamp: string;
+  }): string {
+    const lines = comparison.responses.map((r) => {
+      if (r.error) {
+        return `  ${r.agent}: (ERROR) ${r.error}`;
+      }
+      return `  ${r.agent}: ${r.text ?? "(no response)"}`;
+    });
+
+    return (
+      `ACP Agent Comparison\n` +
+      `────────────────────\n` +
+      `Prompt: ${comparison.prompt}\n` +
+      `Time:   ${comparison.timestamp}\n\n` +
+      lines.join("\n")
+    );
+  }
+}

package/src/coordination/worker-dispatcher.ts

@@ -0,0 +1,191 @@
+/**
+ * pi-acp-agents — Worker Dispatcher (M6: Auto-Claim Dispatch)
+ *
+ * Background auto-claim loop that dispatches tasks to idle workers.
+ * Uses round-robin/FIFO selection when multiple idle workers compete for tasks.
+ * Respects SessionManager busy mutex — skips workers that are already busy.
+ */
+import type { AcpWorkerRecord } from "../config/types.js";
+
+export interface WorkerDispatcherDeps {
+	workerStore: {
+		list(options?: { status?: string }): AcpWorkerRecord[];
+		updateStatus(name: string, status: "idle" | "busy" | "online" | "offline"): AcpWorkerRecord;
+		assignTask(name: string, taskId: string): void;
+		unassignTask(name: string): AcpWorkerRecord;
+		get(name: string): AcpWorkerRecord | undefined;
+		updateMetadata(name: string, metadata: Partial<Record<string, unknown>>): AcpWorkerRecord | undefined;
+	};
+	taskStore: {
+		claimNextAvailable(): Promise<{ id: string; subject: string; description: string | null } | null>;
+		update(id: string, mut: (task: { status: string; result: string | null }) => void): Promise<any>;
+	};
+	eventLog: {
+		append(event: string, data: Record<string, unknown>): void;
+	};
+	busySessions: Map<string, boolean>;
+	dispatchTask: (sessionId: string, prompt: string) => Promise<{ ok: boolean; value?: any; error?: string }>;
+	getSessionIdForWorker: (workerName: string) => string | undefined;
+}
+
+export class WorkerDispatcher {
+	private intervalId: ReturnType<typeof setInterval> | null = null;
+	private dispatchIndex = 0; // Round-robin index for FIFO worker selection
+	private running = false;
+
+	constructor(
+		private deps: WorkerDispatcherDeps,
+		private intervalMs: number = 5000,
+	) {}
+
+	/** Start the auto-claim dispatch loop */
+	start(): void {
+		if (this.running) return;
+		this.running = true;
+		this.intervalId = setInterval(() => {
+			this.dispatchOnce().catch((err) => {
+				this.deps.eventLog.append("dispatch_error", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			});
+		}, this.intervalMs);
+	}
+
+	/** Stop the auto-claim dispatch loop */
+	stop(): void {
+		if (this.intervalId) {
+			clearInterval(this.intervalId);
+			this.intervalId = null;
+		}
+		this.running = false;
+	}
+
+	get isRunning(): boolean {
+		return this.running;
+	}
+
+	/**
+	 * Single dispatch cycle: iterate idle workers in round-robin order,
+	 * attempt to claim a task for each, and dispatch.
+	 */
+	async dispatchOnce(): Promise<void> {
+		const idleWorkers = this.deps.workerStore.list({ status: "idle" });
+		if (idleWorkers.length === 0) return;
+
+		// Round-robin: start from dispatchIndex, wrap around
+		for (let i = 0; i < idleWorkers.length; i++) {
+			const workerIdx = (this.dispatchIndex + i) % idleWorkers.length;
+			const worker = idleWorkers[workerIdx]!;
+
+			// Respect busy mutex — skip if session is in-flight
+			const sessionId = this.deps.getSessionIdForWorker(worker.name);
+			if (sessionId && this.deps.busySessions.get(sessionId)) {
+				continue;
+			}
+
+			// Try to claim a task
+			const task = await this.deps.taskStore.claimNextAvailable();
+			if (!task) continue;
+
+			// Build task prompt, prepending any queued steer message
+			let prompt = this.buildTaskPrompt(task);
+			const workerRecord = this.deps.workerStore.get(worker.name);
+			if (workerRecord?.metadata?.pendingSteer) {
+				prompt = String(workerRecord.metadata.pendingSteer) + "\n\n" + prompt;
+				this.deps.workerStore.updateMetadata(worker.name, { pendingSteer: undefined });
+			}
+
+			// Mark worker busy and assign task
+			this.deps.workerStore.updateStatus(worker.name, "busy");
+			this.deps.workerStore.assignTask(worker.name, task.id);
+
+			// Emit task_assigned event
+			this.deps.eventLog.append("task_assigned", {
+				workerName: worker.name,
+				taskId: task.id,
+				sessionId,
+			});
+
+			// Advance dispatch index (next worker gets priority)
+			this.dispatchIndex = workerIdx + 1;
+
+			// Dispatch and handle completion
+			if (sessionId) {
+				// Fire-and-forget: dispatch the task, handle completion asynchronously
+				this.handleDispatchResult(worker.name, sessionId, task.id, this.deps.dispatchTask(sessionId, prompt));
+			}
+
+			// Only dispatch one task per cycle to avoid overwhelming
+			return;
+		}
+	}
+
+	private buildTaskPrompt(task: { id: string; subject: string; description: string | null }): string {
+		let prompt = `## Task: ${task.subject}\nTask ID: ${task.id}\n`;
+		if (task.description) {
+			prompt += `\n${task.description}\n`;
+		}
+		prompt += `\nComplete this task. Report the result when done.`;
+		return prompt;
+	}
+
+	private async handleDispatchResult(
+		workerName: string,
+		sessionId: string,
+		taskId: string,
+		resultPromise: Promise<{ ok: boolean; value?: any; error?: string }>,
+	): Promise<void> {
+		try {
+			const result = await resultPromise;
+
+			if (result.ok) {
+				// Mark task completed
+				await this.deps.taskStore.update(taskId, (task) => {
+					task.status = "completed";
+					task.result = typeof result.value === "string" ? result.value : JSON.stringify(result.value);
+				});
+
+				// Emit task_completed event
+				this.deps.eventLog.append("task_completed", {
+					workerName,
+					taskId,
+					sessionId,
+				});
+			} else {
+				// Task failed — set back to pending
+				await this.deps.taskStore.update(taskId, (task) => {
+					task.status = "pending";
+					task.result = null;
+				});
+
+				this.deps.eventLog.append("task_dispatch_failed", {
+					workerName,
+					taskId,
+					sessionId,
+					error: result.error,
+				});
+			}
+		} catch (err) {
+			// Unexpected error — set task back to pending
+			try {
+				await this.deps.taskStore.update(taskId, (task) => {
+					task.status = "pending";
+					task.result = null;
+				});
+			} catch {
+				// Ignore update errors
+			}
+
+			this.deps.eventLog.append("task_dispatch_error", {
+				workerName,
+				taskId,
+				sessionId,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		} finally {
+			// Always return worker to idle and unassign task
+			this.deps.workerStore.updateStatus(workerName, "idle");
+			this.deps.workerStore.unassignTask(workerName);
+		}
+	}
+}