@claude-flow/shared 3.0.0-alpha.1

package/src/plugins/official/maestro-plugin.ts

@@ -0,0 +1,508 @@
+/**
+ * Maestro Plugin - Official Plugin (ADR-004)
+ *
+ * Implements orchestration patterns for complex multi-agent workflows.
+ * Part of the official plugin collection.
+ *
+ * @module v3/shared/plugins/official/maestro
+ */
+
+import type { ClaudeFlowPlugin, PluginContext, PluginConfig } from '../types.js';
+import { HookEvent, HookPriority, type TaskInfo, type ErrorInfo } from '../../hooks/index.js';
+
+/**
+ * Maestro configuration
+ */
+export interface MaestroConfig extends PluginConfig {
+  orchestrationMode: 'sequential' | 'parallel' | 'adaptive';
+  maxConcurrentWorkflows: number;
+  workflowTimeout: number; // ms
+  autoRecovery: boolean;
+  checkpointInterval: number; // ms
+}
+
+/**
+ * Workflow step
+ */
+export interface WorkflowStep {
+  id: string;
+  name: string;
+  type: string;
+  input: Record<string, unknown>;
+  dependencies: string[];
+  assignedAgent?: string;
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+  output?: unknown;
+  error?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+}
+
+/**
+ * Workflow definition
+ */
+export interface Workflow {
+  id: string;
+  name: string;
+  description: string;
+  steps: WorkflowStep[];
+  status: 'created' | 'running' | 'paused' | 'completed' | 'failed';
+  currentStep?: string;
+  progress: number;
+  createdAt: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  checkpoints: Map<string, unknown>;
+}
+
+/**
+ * Orchestration result
+ */
+export interface OrchestrationResult {
+  workflowId: string;
+  success: boolean;
+  stepsCompleted: number;
+  stepsTotal: number;
+  outputs: Record<string, unknown>;
+  errors: Array<{ stepId: string; error: string }>;
+  duration: number;
+}
+
+/**
+ * Maestro Plugin Implementation
+ */
+export class MaestroPlugin implements ClaudeFlowPlugin {
+  readonly id = 'maestro';
+  readonly name = 'Maestro Workflow Orchestrator';
+  readonly version = '1.0.0';
+  readonly description = 'Complex multi-agent workflow orchestration with adaptive strategies';
+
+  private context?: PluginContext;
+  private config: MaestroConfig;
+  private workflows: Map<string, Workflow> = new Map();
+  private activeWorkflows = 0;
+
+  constructor(config?: Partial<MaestroConfig>) {
+    this.config = {
+      enabled: true,
+      orchestrationMode: 'adaptive',
+      maxConcurrentWorkflows: 5,
+      workflowTimeout: 600000, // 10 minutes
+      autoRecovery: true,
+      checkpointInterval: 30000, // 30 seconds
+      ...config,
+    };
+  }
+
+  async initialize(context: PluginContext): Promise<void> {
+    this.context = context;
+
+    // Register hooks for workflow monitoring
+    context.hooks?.register(
+      HookEvent.PostTaskComplete,
+      async (ctx) => {
+        // Update workflow progress on task completion
+        for (const workflow of this.workflows.values()) {
+          if (workflow.status === 'running' && ctx.task) {
+            this.updateWorkflowProgress(workflow, ctx.task);
+          }
+        }
+        return { success: true, continueChain: true };
+      },
+      HookPriority.High,
+      { name: 'maestro-task-complete' }
+    );
+
+    context.hooks?.register(
+      HookEvent.OnError,
+      async (ctx) => {
+        // Handle workflow errors with recovery
+        if (this.config.autoRecovery && ctx.error) {
+          for (const workflow of this.workflows.values()) {
+            if (workflow.status === 'running') {
+              this.handleWorkflowError(workflow, ctx.error);
+            }
+          }
+        }
+        return { success: true, continueChain: true };
+      },
+      HookPriority.High,
+      { name: 'maestro-error-handler' }
+    );
+  }
+
+  async shutdown(): Promise<void> {
+    // Checkpoint all running workflows
+    for (const workflow of this.workflows.values()) {
+      if (workflow.status === 'running') {
+        this.checkpointWorkflow(workflow);
+      }
+    }
+    this.workflows.clear();
+    this.context = undefined;
+  }
+
+  // ============================================================================
+  // Workflow Management
+  // ============================================================================
+
+  /**
+   * Create a new workflow
+   */
+  createWorkflow(
+    name: string,
+    description: string,
+    steps: Array<Omit<WorkflowStep, 'id' | 'status'>>
+  ): Workflow {
+    const workflow: Workflow = {
+      id: `workflow-${Date.now()}`,
+      name,
+      description,
+      steps: steps.map((step, index) => ({
+        ...step,
+        id: `step-${index}`,
+        status: 'pending',
+      })),
+      status: 'created',
+      progress: 0,
+      createdAt: new Date(),
+      checkpoints: new Map(),
+    };
+
+    this.workflows.set(workflow.id, workflow);
+    return workflow;
+  }
+
+  /**
+   * Execute a workflow
+   */
+  async executeWorkflow(workflowId: string): Promise<OrchestrationResult> {
+    const workflow = this.workflows.get(workflowId);
+    if (!workflow) {
+      throw new Error(`Workflow not found: ${workflowId}`);
+    }
+
+    if (this.activeWorkflows >= this.config.maxConcurrentWorkflows) {
+      throw new Error('Maximum concurrent workflows reached');
+    }
+
+    const startTime = Date.now();
+    workflow.status = 'running';
+    workflow.startedAt = new Date();
+    this.activeWorkflows++;
+
+    const errors: Array<{ stepId: string; error: string }> = [];
+    const outputs: Record<string, unknown> = {};
+
+    try {
+      switch (this.config.orchestrationMode) {
+        case 'sequential':
+          await this.executeSequential(workflow, outputs, errors);
+          break;
+        case 'parallel':
+          await this.executeParallel(workflow, outputs, errors);
+          break;
+        case 'adaptive':
+          await this.executeAdaptive(workflow, outputs, errors);
+          break;
+      }
+
+      workflow.status = errors.length === 0 ? 'completed' : 'failed';
+      workflow.completedAt = new Date();
+    } catch (error) {
+      workflow.status = 'failed';
+      errors.push({
+        stepId: 'workflow',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      this.activeWorkflows--;
+    }
+
+    return {
+      workflowId,
+      success: workflow.status === 'completed',
+      stepsCompleted: workflow.steps.filter((s) => s.status === 'completed').length,
+      stepsTotal: workflow.steps.length,
+      outputs,
+      errors,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Pause a workflow
+   */
+  pauseWorkflow(workflowId: string): boolean {
+    const workflow = this.workflows.get(workflowId);
+    if (!workflow || workflow.status !== 'running') return false;
+
+    this.checkpointWorkflow(workflow);
+    workflow.status = 'paused';
+    return true;
+  }
+
+  /**
+   * Resume a paused workflow
+   */
+  async resumeWorkflow(workflowId: string): Promise<OrchestrationResult> {
+    const workflow = this.workflows.get(workflowId);
+    if (!workflow || workflow.status !== 'paused') {
+      throw new Error('Workflow cannot be resumed');
+    }
+
+    // Restore from checkpoint and continue
+    return this.executeWorkflow(workflowId);
+  }
+
+  /**
+   * Get workflow status
+   */
+  getWorkflow(workflowId: string): Workflow | undefined {
+    return this.workflows.get(workflowId);
+  }
+
+  /**
+   * List all workflows
+   */
+  listWorkflows(): Workflow[] {
+    return Array.from(this.workflows.values());
+  }
+
+  // ============================================================================
+  // Execution Strategies
+  // ============================================================================
+
+  private async executeSequential(
+    workflow: Workflow,
+    outputs: Record<string, unknown>,
+    errors: Array<{ stepId: string; error: string }>
+  ): Promise<void> {
+    for (const step of workflow.steps) {
+      if (step.status !== 'pending') continue;
+
+      // Check dependencies
+      const depsComplete = step.dependencies.every((depId) => {
+        const dep = workflow.steps.find((s) => s.id === depId);
+        return dep?.status === 'completed';
+      });
+
+      if (!depsComplete) {
+        step.status = 'skipped';
+        continue;
+      }
+
+      workflow.currentStep = step.id;
+      const result = await this.executeStep(step, outputs);
+
+      if (!result.success) {
+        errors.push({ stepId: step.id, error: result.error ?? 'Unknown error' });
+        break;
+      }
+
+      outputs[step.id] = result.output;
+      this.updateProgress(workflow);
+    }
+  }
+
+  private async executeParallel(
+    workflow: Workflow,
+    outputs: Record<string, unknown>,
+    errors: Array<{ stepId: string; error: string }>
+  ): Promise<void> {
+    const layers = this.buildExecutionLayers(workflow.steps);
+
+    for (const layer of layers) {
+      const results = await Promise.all(
+        layer.map((step) => this.executeStep(step, outputs))
+      );
+
+      for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        const step = layer[i];
+
+        if (!result.success) {
+          errors.push({ stepId: step.id, error: result.error ?? 'Unknown error' });
+        } else {
+          outputs[step.id] = result.output;
+        }
+      }
+
+      this.updateProgress(workflow);
+    }
+  }
+
+  private async executeAdaptive(
+    workflow: Workflow,
+    outputs: Record<string, unknown>,
+    errors: Array<{ stepId: string; error: string }>
+  ): Promise<void> {
+    // Adaptive: start parallel, switch to sequential on errors
+    const completedIds = new Set<string>();
+    const pendingSteps = [...workflow.steps];
+    let consecutiveErrors = 0;
+    const maxConsecutiveErrors = 2;
+
+    while (pendingSteps.length > 0) {
+      // Find steps that can run (all dependencies complete)
+      const runnableSteps = pendingSteps.filter((step) =>
+        step.dependencies.every((depId) => completedIds.has(depId))
+      );
+
+      if (runnableSteps.length === 0) {
+        // No runnable steps but pending remain - circular dependency
+        for (const step of pendingSteps) {
+          step.status = 'skipped';
+        }
+        break;
+      }
+
+      // Decide batch size based on error rate
+      const batchSize = consecutiveErrors >= maxConsecutiveErrors ? 1 : runnableSteps.length;
+      const batch = runnableSteps.slice(0, batchSize);
+
+      const results = await Promise.all(
+        batch.map((step) => this.executeStep(step, outputs))
+      );
+
+      for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        const step = batch[i];
+        const stepIndex = pendingSteps.indexOf(step);
+
+        if (stepIndex > -1) {
+          pendingSteps.splice(stepIndex, 1);
+        }
+
+        if (!result.success) {
+          errors.push({ stepId: step.id, error: result.error ?? 'Unknown error' });
+          consecutiveErrors++;
+        } else {
+          outputs[step.id] = result.output;
+          completedIds.add(step.id);
+          consecutiveErrors = 0;
+        }
+      }
+
+      this.updateProgress(workflow);
+    }
+  }
+
+  // ============================================================================
+  // Helpers
+  // ============================================================================
+
+  private async executeStep(
+    step: WorkflowStep,
+    outputs: Record<string, unknown>
+  ): Promise<{ success: boolean; output?: unknown; error?: string }> {
+    step.status = 'running';
+    step.startedAt = new Date();
+
+    try {
+      // Resolve input references from previous outputs
+      const resolvedInput = this.resolveInputReferences(step.input, outputs);
+
+      // Simulate step execution
+      // In real implementation, this would delegate to agents via MCP
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      step.output = { ...resolvedInput, processed: true };
+      step.status = 'completed';
+      step.completedAt = new Date();
+
+      return { success: true, output: step.output };
+    } catch (error) {
+      step.status = 'failed';
+      step.error = error instanceof Error ? error.message : String(error);
+      step.completedAt = new Date();
+
+      return { success: false, error: step.error };
+    }
+  }
+
+  private buildExecutionLayers(steps: WorkflowStep[]): WorkflowStep[][] {
+    const layers: WorkflowStep[][] = [];
+    const completed = new Set<string>();
+
+    while (completed.size < steps.length) {
+      const layer: WorkflowStep[] = [];
+
+      for (const step of steps) {
+        if (completed.has(step.id)) continue;
+
+        const depsComplete = step.dependencies.every((depId) => completed.has(depId));
+        if (depsComplete) {
+          layer.push(step);
+        }
+      }
+
+      if (layer.length === 0) break; // No more runnable steps
+      layers.push(layer);
+      layer.forEach((step) => completed.add(step.id));
+    }
+
+    return layers;
+  }
+
+  private resolveInputReferences(
+    input: Record<string, unknown>,
+    outputs: Record<string, unknown>
+  ): Record<string, unknown> {
+    const resolved: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(input)) {
+      if (typeof value === 'string' && value.startsWith('$')) {
+        const ref = value.slice(1);
+        resolved[key] = outputs[ref];
+      } else {
+        resolved[key] = value;
+      }
+    }
+
+    return resolved;
+  }
+
+  private updateProgress(workflow: Workflow): void {
+    const completed = workflow.steps.filter((s) => s.status === 'completed').length;
+    workflow.progress = (completed / workflow.steps.length) * 100;
+  }
+
+  private updateWorkflowProgress(workflow: Workflow, taskData: TaskInfo): void {
+    // Match task to workflow step and update
+    const taskId = taskData.id;
+    const step = workflow.steps.find((s) => s.id === taskId);
+    if (step && step.status === 'running') {
+      step.status = 'completed';
+      step.output = taskData.metadata;
+      step.completedAt = new Date();
+      this.updateProgress(workflow);
+    }
+  }
+
+  private handleWorkflowError(workflow: Workflow, errorData: ErrorInfo): void {
+    const stepId = errorData.context ?? '';
+    const step = workflow.steps.find((s) => s.id === stepId);
+
+    if (step && step.status === 'running') {
+      step.status = 'failed';
+      step.error = errorData.error?.message ?? 'Unknown error';
+      step.completedAt = new Date();
+    }
+  }
+
+  private checkpointWorkflow(workflow: Workflow): void {
+    workflow.checkpoints.set(`checkpoint-${Date.now()}`, {
+      progress: workflow.progress,
+      currentStep: workflow.currentStep,
+      stepStatuses: workflow.steps.map((s) => ({ id: s.id, status: s.status })),
+    });
+  }
+}
+
+/**
+ * Factory function
+ */
+export function createMaestroPlugin(config?: Partial<MaestroConfig>): MaestroPlugin {
+  return new MaestroPlugin(config);
+}

package/src/plugins/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Plugin Types - ADR-004 Implementation
+ *
+ * Type definitions for the plugin system.
+ *
+ * @module v3/shared/plugins/types
+ */
+
+import type { HookRegistry } from '../hooks/index.js';
+
+/**
+ * Plugin configuration base
+ */
+export interface PluginConfig {
+  enabled: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * Plugin context provided during initialization
+ */
+export interface PluginContext {
+  hooks?: HookRegistry;
+  services?: Record<string, unknown>;
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Plugin lifecycle events
+ */
+export type PluginEvent = 'initialized' | 'shutdown' | 'error';
+
+/**
+ * Plugin event handler
+ */
+export type PluginEventHandler = (event: PluginEvent, data?: unknown) => void;
+
+/**
+ * Claude Flow Plugin Interface
+ *
+ * All plugins must implement this interface.
+ */
+export interface ClaudeFlowPlugin {
+  /** Unique plugin identifier */
+  readonly id: string;
+
+  /** Human-readable name */
+  readonly name: string;
+
+  /** Plugin version */
+  readonly version: string;
+
+  /** Plugin description */
+  readonly description: string;
+
+  /** Dependencies on other plugins */
+  readonly dependencies?: string[];
+
+  /**
+   * Initialize the plugin
+   * @param context Plugin context with hooks and services
+   */
+  initialize(context: PluginContext): Promise<void>;
+
+  /**
+   * Shutdown the plugin
+   */
+  shutdown(): Promise<void>;
+
+  /**
+   * Optional event handler
+   */
+  onEvent?: PluginEventHandler;
+}
+
+/**
+ * Plugin metadata
+ */
+export interface PluginMetadata {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  author?: string;
+  license?: string;
+  homepage?: string;
+  dependencies?: string[];
+}
+
+/**
+ * Plugin registry
+ */
+export interface IPluginRegistry {
+  register(plugin: ClaudeFlowPlugin): void;
+  unregister(pluginId: string): void;
+  get(pluginId: string): ClaudeFlowPlugin | undefined;
+  getAll(): ClaudeFlowPlugin[];
+  isRegistered(pluginId: string): boolean;
+}
+
+/**
+ * Plugin loader interface
+ */
+export interface IPluginLoader {
+  loadFromPath(path: string): Promise<ClaudeFlowPlugin>;
+  loadFromPackage(packageName: string): Promise<ClaudeFlowPlugin>;
+  loadBuiltin(pluginId: string): Promise<ClaudeFlowPlugin>;
+}