astrabot 0.1.0

package/modes/multi/orchestrator.ts

@@ -0,0 +1,414 @@
+/**
+ * Smart Multi-Agent Mode Integration
+ *
+ * This file integrates the multi-agent orchestration system into the main
+ * application. It analyzes the goal text using an LLM to smartly choose
+ * a template or dynamically craft a custom agent topology.
+ */
+
+import { text, isCancel, select, confirm, multiselect, spinner } from "@clack/prompts";
+import chalk from "chalk";
+import { generateText, stepCountIs } from "ai";
+import { getAgentModel } from "../../ai";
+import { MultiAgentOrchestrator } from "./multi-agent-orchestrator";
+import { WorkflowBuilder, WorkflowTemplates } from "./workflow-builder";
+import type { MultiAgentWorkflow, OrchestratorEvent } from "./types";
+import { composeBeforeAfter, formatPatch } from "../agent/diff-view";
+import { renderTerminalMarkdown } from "../../tui/terminal-md";
+import { withSpinner } from "../../tui/spinner";
+import type { ActionLog } from "../agent/types";
+
+interface ReviewGroup {
+  label: string;
+  actionIds: string[];
+  patch: string | null;
+}
+
+function groupPendingByAgent(agentId: string, pending: ActionLog[]): ReviewGroup[] {
+  const byPath = new Map<string, ActionLog[]>();
+  const shells: ActionLog[] = [];
+
+  for (const a of pending) {
+    if (a.type === "tool_execute") {
+      shells.push(a);
+      continue;
+    }
+    const key = a.path;
+    if (!byPath.has(key)) byPath.set(key, []);
+    byPath.get(key)!.push(a);
+  }
+
+  const groups: ReviewGroup[] = [];
+  const pathEntries = [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b));
+
+  for (const [p, acts] of pathEntries) {
+    const sorted = acts.sort((x, y) => x.timestamp.getTime() - y.timestamp.getTime());
+    const ids = sorted.map((x) => x.id);
+
+    if (sorted.every((x) => x.type === "folder_create")) {
+      groups.push({
+        label: `Create folder: ${p}`,
+        actionIds: ids,
+        patch: null,
+      });
+      continue;
+    }
+
+    const { before, after } = composeBeforeAfter(sorted);
+    const patch = formatPatch(p, before, after);
+    const kinds = [...new Set(sorted.map((x) => x.type))].join(", ");
+    groups.push({ label: `${p} (${kinds})`, actionIds: ids, patch });
+  }
+
+  for (const s of shells) {
+    groups.push({
+      label: `Shell: ${s.details.command ?? "(no command)"}`,
+      actionIds: [s.id],
+      patch: null,
+    });
+  }
+
+  return groups;
+}
+
+const TEMPLATE_CATALOG = [
+  { id: "code_review", name: "Code Review", template: WorkflowTemplates.codeReviewWorkflow },
+  { id: "feature_dev", name: "Feature Development", template: WorkflowTemplates.featureDevelopmentWorkflow },
+  { id: "bug_fix", name: "Bug Fixing", template: WorkflowTemplates.bugFixingWorkflow },
+  { id: "research", name: "Collaborative Research", template: WorkflowTemplates.collaborativeResearchWorkflow },
+  { id: "security_audit", name: "Security Audit", template: WorkflowTemplates.securityAuditWorkflow },
+  { id: "fullstack", name: "Full-Stack Feature", template: WorkflowTemplates.fullStackFeatureWorkflow },
+];
+
+// ─── Main Entry Point ──────────────────────────────────────────────────────
+
+export async function runMultiAgentMode(preCapturedGoal?: string): Promise<void> {
+  console.log(chalk.bold("\n👥 Multi-Agent Orchestration\n"));
+
+  // 1. Gather the goal text if not passed directly from Auto Mode
+  const finalGoal = preCapturedGoal?.trim() ?? await text({
+    message: "What complex operations workflow would you like to run?",
+    placeholder: "e.g., 'Audit auth code security and patch the leaks'...",
+  });
+
+  if (!finalGoal || isCancel(finalGoal) || !finalGoal.trim()) return;
+
+  let workflow: MultiAgentWorkflow | null = null;
+
+  // 2. AI Intelligence Engine: Analyze and assemble the best team
+  const decisionSpinner = spinner();
+  decisionSpinner.start("AI analyzing requirements and building optimal agent team topology...");
+
+  try {
+    const analysisResponse = await generateText({
+      model: getAgentModel(),
+      stopWhen: stepCountIs(1),
+      prompt: [
+        "You are an expert system architecture manager designing multi-agent software pipelines.",
+        "Analyze the following user task goal, and decide the absolute best workflow setup.",
+        "",
+        `User Task Goal: "${finalGoal}"`,
+        "",
+        "Available Catalog Templates:",
+        "- 'code_review': For reading existing code changes, analyzing style/vulnerabilities, and summarizing changes.",
+        "- 'feature_dev': Core workflows needing planning, engineering implementation, and QA reviews.",
+        "- 'bug_fix': Repair loops starting with debugging/diagnostics, code patch modifications, and testing cycles.",
+        "- 'research': Broad reading, framework discoveries, or documentation analysis without writing active patches.",
+        "- 'security_audit': Scanners running sweeps across directories feeding synthesis workflows.",
+        "- 'fullstack': Complex tasks requiring layered architectures (Database models, APIs, and UI controls) executing in parallel blocks.",
+        "",
+        "Your task is to respond with a clean, unformatted JSON object containing instructions on how to structure the agent swarm.",
+        "Format your response as a valid raw JSON matching EXACTLY one of these two configurations. Do not use markdown blocks.",
+        "",
+        "Option A: If a catalog template fits perfectly:",
+        '{"decisionType": "template", "templateId": "feature_dev" | "bug_fix" | "code_review" | "research" | "security_audit" | "fullstack"}',
+        "",
+        "Option B: If the task is unique and requires a customized specialized agent group configuration:",
+        '{',
+        '  "decisionType": "custom",',
+        '  "strategy": "sequential" | "parallel" | "hierarchical" | "collaborative",',
+        '  "agents": [',
+        '    { "name": "string", "role": "researcher"|"implementer"|"reviewer"|"coordinator", "description": "precise operational prompt instruction directive context for this agent" }',
+        '  ]',
+        '}'
+      ].join("\n"),
+    });
+
+    // Clean any accidental markdown wraps from the raw response text
+    let cleanJsonText = analysisResponse.text.trim();
+    if (cleanJsonText.startsWith("```")) {
+      cleanJsonText = cleanJsonText.replace(/^```json\s*/, "").replace(/```$/, "").trim();
+    }
+
+    const config = JSON.parse(cleanJsonText);
+    const timestamp = Date.now();
+
+    if (config.decisionType === "template" && config.templateId) {
+      const match = TEMPLATE_CATALOG.find(t => t.id === config.templateId);
+      if (match) {
+        decisionSpinner.stop(`✨ AI designated standard pipeline template: [${match.name}]`);
+        workflow = match.template(`wf_ai_${config.templateId}_${timestamp}`, finalGoal);
+      }
+    }
+
+    // fallback / bespoke generation block
+    if (!workflow && config.decisionType === "custom" && Array.isArray(config.agents)) {
+      decisionSpinner.stop(`🛠️ AI created bespoke customized workspace swarm [Strategy: ${config.strategy.toUpperCase()}]`);
+      const builder = new WorkflowBuilder(`wf_custom_ai_${timestamp}`, finalGoal);
+
+      for (const a of config.agents) {
+        if (a.role === "researcher") builder.addResearcher(a.name, a.name, a.description);
+        else if (a.role === "implementer") builder.addImplementer(a.name, a.name, a.description);
+        else if (a.role === "reviewer") builder.addReviewer(a.name, a.name, a.description);
+        else builder.addCoordinator(a.name, a.name, a.description);
+      }
+
+      if (config.strategy === "parallel") builder.withParallelStrategy(3, 45000);
+      else if (config.strategy === "hierarchical") builder.withHierarchicalStrategy();
+      else if (config.strategy === "collaborative") builder.withCollaborativeStrategy(60000);
+      else builder.withSequentialStrategy();
+
+      builder.withRetryOnFailure(1);
+      workflow = builder.build();
+    }
+  } catch (err) {
+    // Fail-safe graceful fallback if model errors or outputs invalid JSON
+    decisionSpinner.stop("⚠️ Model parsing bottleneck; falling back to dynamic Feature Development group");
+  }
+
+  // Double fallback to protect operation runtime loop
+  if (!workflow) {
+    const timestamp = Date.now();
+    workflow = WorkflowTemplates.featureDevelopmentWorkflow(`wf_fallback_${timestamp}`, finalGoal);
+  }
+
+  // 3. Complete Validation Layer
+  const validation = WorkflowBuilder.validateWorkflow(workflow);
+  if (!validation.isValid) {
+    console.log(chalk.red("\n❌ Generated Workflow validation failed:\n"));
+    for (const error of validation.errors) console.log(chalk.red(`  • ${error}`));
+    return;
+  }
+
+  // 4. Summarize and Confirm Execution with User
+  displayWorkflowSummary(workflow);
+
+  const shouldContinue = await confirm({
+    message: "Execute this smart-built agent workflow?",
+    initialValue: true,
+  });
+  if (isCancel(shouldContinue) || !shouldContinue) {
+    console.log(chalk.dim("\nWorkflow cancelled.\n"));
+    return;
+  }
+
+  // 5. Standard Core Operational Orchestrator Lifecycle Loop Execution
+  const orchestrator = new MultiAgentOrchestrator(workflow);
+
+  const unsubscribe = orchestrator.onEvent((event: OrchestratorEvent) => {
+    if (event.type === "agent:start") {
+      orchestrationLogger.debug(`Agent ${event.agentId} running...`);
+    } else if (event.type === "agent:complete") {
+      orchestrationLogger.debug(`Agent ${event.agentId} successfully completed steps`);
+    }
+  });
+
+  await withSpinner(
+    {
+      message: "Orchestrating system agents pipeline execution...",
+      doneMessage: "workflow steps completed successfully",
+      failMessage: "workflow processing routine encountered a bottleneck",
+    },
+    () => orchestrator.execute(),
+  );
+
+  unsubscribe();
+
+  // 6. Print Summary Metric Sheets & Route Approval
+  displayExecutionResults(orchestrator);
+  await runMultiAgentApprovalFlow(orchestrator);
+}
+
+// ─── Native Selector Methods (Preserved for standard fallback uses) ────────
+
+async function selectTemplateWorkflow(): Promise<MultiAgentWorkflow | null> {
+  const selected = await select({
+    message: "Select a workflow template",
+    options: TEMPLATE_CATALOG.map((t) => ({
+      value: t.id,
+      label: chalk.bold(t.name),
+    })),
+  });
+  if (isCancel(selected)) return null;
+  const catalog = TEMPLATE_CATALOG.find((t) => t.id === selected);
+  if (!catalog) return null;
+  const goal = await text({ message: "Describe the goal for this workflow" });
+  if (isCancel(goal) || !goal.trim()) return null;
+  return catalog.template(`workflow_${selected}_${Date.now()}`, goal.trim());
+}
+
+async function buildCustomWorkflow(): Promise<MultiAgentWorkflow | null> {
+  return null; // Interface is bypassed dynamically by the structural smart engine
+}
+
+async function buildAdvancedDAGWorkflow(): Promise<MultiAgentWorkflow | null> {
+  return null; // Interface is bypassed dynamically by the structural smart engine
+}
+
+// ─── Display & Approval ────────────────────────────────────────────────────
+
+function displayWorkflowSummary(workflow: MultiAgentWorkflow): void {
+  console.log(chalk.bold("\n📋 Smart Workflow Configuration\n"));
+  console.log(`Goal: ${workflow.goal}`);
+  console.log(`Strategy: ${chalk.cyan(workflow.strategy.type)}`);
+  console.log(`Agents: ${workflow.agents.length}`);
+  console.log(
+    `${workflow.agents
+      .map(
+        (a) =>
+          `  • ${chalk.bold(a.name)} (${a.role})${a.model ? ` [${chalk.dim(a.model)}]` : ""}${
+            a.dependsOn?.length ? ` → depends: ${a.dependsOn.join(", ")}` : ""
+          }`,
+      )
+      .join("\n")}`,
+  );
+  console.log();
+}
+
+async function runMultiAgentApprovalFlow(orchestrator: MultiAgentOrchestrator): Promise<void> {
+  const trackers = orchestrator.getAllTrackers();
+  const executors = orchestrator.getAllExecutors();
+
+  let totalPending = 0;
+  for (const [, tracker] of trackers) {
+    totalPending += tracker.getPendingMutations().length;
+  }
+
+  if (totalPending === 0) {
+    console.log(chalk.dim("\nNo staged changes to review.\n"));
+    return;
+  }
+
+  console.log(chalk.bold(`\n📝 ${totalPending} staged change(s) from ${trackers.size} agent(s)\n`));
+
+  const choice = await select({
+    message: "Apply staged changes?",
+    options: [
+      { value: "all", label: "Approve all" },
+      { value: "select", label: "Review one by one" },
+      { value: "cancel", label: "Discard all" },
+    ],
+  });
+
+  if (isCancel(choice) || choice === "cancel") {
+    for (const [, tracker] of trackers) {
+      for (const action of tracker.getPendingMutations()) {
+        tracker.updateStatus(action.id, "rejected", false);
+      }
+    }
+    for (const [, executor] of executors) {
+      executor.discardChanges();
+    }
+    console.log(chalk.yellow("\nAll changes discarded.\n"));
+    return;
+  }
+
+  if (choice === "all") {
+    for (const [, tracker] of trackers) {
+      for (const action of tracker.getPendingMutations()) {
+        tracker.updateStatus(action.id, "approved", true);
+      }
+    }
+  } else if (choice === "select") {
+    for (const [agentId, tracker] of trackers) {
+      const pending = tracker.getPendingMutations();
+      if (pending.length === 0) continue;
+
+      console.log(chalk.bold(`\n🤖 Agent: ${agentId} (${pending.length} change(s))`));
+      const groups = groupPendingByAgent(agentId, pending);
+
+      for (const g of groups) {
+        while (true) {
+          const opt = await select({
+            message: chalk.bold(g.label),
+            options: [
+              { value: "accept", label: "Accept" },
+              { value: "diff", label: "Show diff", hint: g.patch ? "" : "N/A" },
+              { value: "reject", label: "Reject" },
+            ],
+          });
+
+          if (isCancel(opt)) {
+            for (const [, t] of trackers) {
+              for (const a of t.getPendingMutations()) t.updateStatus(a.id, "rejected", false);
+            }
+            for (const [, executor] of executors) executor.discardChanges();
+            console.log(chalk.yellow("\nAll changes discarded.\n"));
+            return;
+          }
+
+          if (opt === "diff") {
+            if (g.patch) {
+              console.log("\n" + renderTerminalMarkdown("```diff\n" + g.patch + "\n```\n") + "\n");
+            }
+            continue;
+          }
+
+          for (const id of g.actionIds) {
+            tracker.updateStatus(id, opt === "accept" ? "approved" : "rejected", opt === "accept");
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  await withSpinner(
+    {
+      message: "Applying approved changes…",
+      doneMessage: "all changes applied",
+      failMessage: "some operations failed",
+    },
+    async () => {
+      const allErrors: string[] = [];
+      for (const [agentId, executor] of executors) {
+        const { errors } = executor.applyApprovedFromTracker();
+        allErrors.push(...errors.map((e) => `[${agentId}] ${e}`));
+      }
+      if (allErrors.length > 0) {
+        console.log(chalk.red("\nErrors:\n"));
+        for (const e of allErrors) console.log(chalk.red(`  · ${e}`));
+      } else {
+        console.log(chalk.green("\n✔ All changes applied.\n"));
+      }
+    },
+  );
+}
+
+function displayExecutionResults(orchestrator: MultiAgentOrchestrator): void {
+  const summary = orchestrator.getSummary();
+  console.log(chalk.bold("\n📊 Execution Summary\n"));
+  const statusColor = summary.status === "completed" ? chalk.green : chalk.red;
+  console.log(`Status: ${statusColor(`● ${summary.status}`)}`);
+  console.log(`Strategy: ${summary.strategy}`);
+  console.log(`Duration: ${summary.duration ? `${summary.duration}ms` : "N/A"}`);
+
+  console.log(chalk.bold("\n🤖 Pool Stats\n"));
+  console.log(`Total Agents Assigned: ${summary.poolStats.totalAgents}`);
+  console.log(`Completed Steps: ${chalk.green(String(summary.poolStats.completedAgents))}`);
+  console.log(`Completion Accuracy: ${chalk.cyan(`${summary.poolStats.completionPercentage}%`)}`);
+}
+
+const orchestrationLogger = {
+  debug: (msg: string) => {
+    if (process.env.DEBUG) console.log(chalk.dim(`[DEBUG] ${msg}`));
+  },
+};
+
+export default {
+  runMultiAgentMode,
+  selectTemplateWorkflow,
+  buildCustomWorkflow,
+  buildAdvancedDAGWorkflow,
+  displayExecutionResults,
+};

package/modes/multi/types.ts

@@ -0,0 +1,245 @@
+/**
+ * Multi-Agent Orchestration Types
+ *
+ * Defines the interfaces and types for coordinating multiple agents
+ * working together on complex tasks.
+ */
+
+// ─── Core Agent Types ────────────────────────────────────────────────────────
+
+export type AgentRole =
+  | "researcher"   // Gathers information and analyzes
+  | "implementer"  // Writes code and modifies files
+  | "reviewer"     // Reviews changes and validates
+  | "coordinator"  // Manages workflow and delegates tasks
+  | "custom";      // Custom role defined by user
+
+export type AgentStatus = "pending" | "running" | "completed" | "failed" | "skipped" | "retrying";
+
+export interface AgentConfig {
+  id: string;
+  role: AgentRole;
+  name: string;
+  description: string;
+  model?: string;             // Override default model (e.g. "anthropic/claude-sonnet-4.5")
+  maxSteps: number;
+  tools: string[];            // List of tool names this agent can use
+  systemPrompt?: string;      // Custom system instructions
+  specializations?: string[]; // What this agent is good at
+  /** IDs of agents that must complete before this one starts (DAG dependency) */
+  dependsOn?: string[];
+  /** Hard timeout in ms for this specific agent (overrides strategy timeout) */
+  timeoutMs?: number;
+  /** Tags for grouping/filtering agents */
+  tags?: string[];
+}
+
+// ─── Messaging ───────────────────────────────────────────────────────────────
+
+export type MessageType = "request" | "response" | "status" | "error" | "result" | "handoff";
+
+export interface AgentMessage {
+  id: string;
+  fromAgentId: string;
+  toAgentId?: string;         // undefined = broadcast to all
+  type: MessageType;
+  content: string;
+  context?: Record<string, unknown>;
+  timestamp: Date;
+  requiresResponse: boolean;
+  /** Message this is a reply to */
+  replyToId?: string;
+  /** Priority for ordering message delivery */
+  priority?: "low" | "normal" | "high";
+}
+
+// ─── Context & State ─────────────────────────────────────────────────────────
+
+export interface AgentContext {
+  goal: string;
+  conversationHistory: AgentMessage[];
+  sharedState: Map<string, unknown>;
+  parentContext?: AgentContext;
+  metadata: AgentContextMetadata;
+}
+
+export interface AgentContextMetadata {
+  startTime: Date;
+  endTime?: Date;
+  currentStep: number;
+  completedTasks: string[];
+  failedTasks: string[];
+  retryCount: number;
+  /** Structured findings the agent surfaced for downstream agents */
+  findings?: Record<string, unknown>;
+  /** Tokens used, if tracked by the model provider */
+  tokensUsed?: number;
+}
+
+// ─── Execution Results ───────────────────────────────────────────────────────
+
+export interface AgentExecutionResult {
+  agentId: string;
+  success: boolean;
+  output: string;
+  executedTools: string[];
+  messagesReceived: AgentMessage[];
+  messagesSent: AgentMessage[];
+  context: AgentContext;
+  error?: Error;
+  /** Wall-clock duration in ms */
+  durationMs: number;
+  /** Which attempt produced this result (1-based) */
+  attemptNumber: number;
+}
+
+// ─── Orchestration Strategy ──────────────────────────────────────────────────
+
+export type StrategyType = "sequential" | "parallel" | "hierarchical" | "collaborative" | "dag";
+
+export interface OrchestrationStrategy {
+  type: StrategyType;
+  config: StrategyConfig;
+}
+
+export interface StrategyConfig {
+  maxConcurrentAgents?: number;
+  /** Default timeout in ms applied to all agents (can be overridden per-agent) */
+  timeout?: number;
+  retryOnFailure?: boolean;
+  maxRetries?: number;
+  fallbackAgents?: string[];
+  /**
+   * "fail-fast": abort entire workflow on first agent failure (default for sequential).
+   * "continue": skip failed agents and continue.
+   * "fail-at-end": complete all agents, then surface errors.
+   */
+  failureMode?: "fail-fast" | "continue" | "fail-at-end";
+}
+
+// ─── Workflow ─────────────────────────────────────────────────────────────────
+
+export interface MultiAgentWorkflow {
+  id: string;
+  goal: string;
+  agents: AgentConfig[];
+  strategy: OrchestrationStrategy;
+  initialPrompt: string;
+  expectedOutput?: string;
+  createdAt: Date;
+  updatedAt: Date;
+  /** Optional metadata bag for user-defined fields */
+  meta?: Record<string, unknown>;
+}
+
+// ─── Pool ────────────────────────────────────────────────────────────────────
+
+export interface AgentPool {
+  agents: Map<string, AgentInstance>;
+  activeAgents: Set<string>;
+  waitingAgents: Set<string>;
+  failedAgents: Set<string>;
+  completedAgents: Set<string>;
+}
+
+export interface AgentInstance {
+  config: AgentConfig;
+  context: AgentContext;
+  status: AgentStatus;
+  /** For backward compat */
+  get isActive(): boolean;
+  lastMessageTime: Date;
+  messageQueue: AgentMessage[];
+  completionPercentage: number;
+  startedAt?: Date;
+  completedAt?: Date;
+}
+
+// ─── Orchestrator State ───────────────────────────────────────────────────────
+
+export type OrchestratorStatus = "pending" | "running" | "paused" | "completed" | "failed";
+
+export interface OrchestratorState {
+  workflowId: string;
+  status: OrchestratorStatus;
+  pool: AgentPool;
+  sharedContext: AgentContext;
+  timeline: AgentExecutionResult[];
+  startTime: Date;
+  endTime?: Date;
+  currentCoordinator: string;
+  /** Emitted events in order */
+  events: OrchestratorEvent[];
+}
+
+// ─── Events ───────────────────────────────────────────────────────────────────
+
+export type OrchestratorEventType =
+  | "workflow:start"
+  | "workflow:complete"
+  | "workflow:failed"
+  | "agent:start"
+  | "agent:complete"
+  | "agent:failed"
+  | "agent:retry"
+  | "agent:timeout"
+  | "strategy:phase"
+  | "message:sent";
+
+export interface OrchestratorEvent {
+  type: OrchestratorEventType;
+  timestamp: Date;
+  agentId?: string;
+  payload?: Record<string, unknown>;
+}
+
+export type OrchestratorEventListener = (event: OrchestratorEvent) => void;
+
+// ─── Communication ────────────────────────────────────────────────────────────
+
+export interface CommunicationChannel {
+  messageBuffer: AgentMessage[];
+  subscribers: Map<string, (msg: AgentMessage) => void>;
+  broadcast(message: Omit<AgentMessage, "id" | "timestamp">): AgentMessage;
+  subscribe(agentId: string, callback: (msg: AgentMessage) => void): () => void;
+  getMessagesFor(agentId: string): AgentMessage[];
+  getConversation(agentId1: string, agentId2: string): AgentMessage[];
+  clearBuffer(): void;
+}
+
+// ─── Summary Types ────────────────────────────────────────────────────────────
+
+export interface AgentResultSummary {
+  agentId: string;
+  success: boolean;
+  role: AgentRole | undefined;
+  steps: number;
+  durationMs: number;
+  toolsUsed: string[];
+  attemptNumber: number;
+  output?: string;
+}
+
+export interface PoolStats {
+  totalAgents: number;
+  activeAgents: number;
+  waitingAgents: number;
+  failedAgents: number;
+  completedAgents: number;
+  completionPercentage: number;
+}
+
+export interface OrchestratorSummary {
+  workflowId: string;
+  status: OrchestratorStatus;
+  goal: string;
+  strategy: StrategyType;
+  startTime: Date;
+  endTime?: Date;
+  duration: number | null;
+  totalAgents: number;
+  completedTasks: number;
+  failedTasks: number;
+  poolStats: PoolStats;
+  executionResults: AgentResultSummary[];
+}