musubi-sdd 3.0.1 → 3.5.1

package/src/orchestration/patterns/nested.js

@@ -0,0 +1,322 @@
+/**
+ * NestedPattern - Hierarchical skill delegation pattern
+ * 
+ * Executes tasks by delegating to sub-skills in a hierarchical manner.
+ * Each skill can spawn child tasks creating a tree-like execution structure.
+ */
+
+const { BasePattern } = require('../pattern-registry');
+const { PatternType, ExecutionContext, ExecutionStatus } = require('../orchestration-engine');
+
+/**
+ * Nested execution mode
+ */
+const NestedMode = {
+  DEPTH_FIRST: 'depth-first',
+  BREADTH_FIRST: 'breadth-first'
+};
+
+/**
+ * NestedPattern - Hierarchical task delegation
+ */
+class NestedPattern extends BasePattern {
+  constructor(options = {}) {
+    super({
+      name: PatternType.NESTED,
+      type: PatternType.NESTED,
+      description: 'Execute tasks hierarchically, delegating to sub-skills',
+      version: '1.0.0',
+      tags: ['hierarchical', 'delegation', 'decomposition'],
+      useCases: [
+        'Complex task breakdown',
+        'Hierarchical processing',
+        'Multi-level delegation'
+      ],
+      complexity: 'high',
+      supportsParallel: false,
+      requiresHuman: false
+    });
+
+    this.options = {
+      maxDepth: options.maxDepth || 5,
+      mode: options.mode || NestedMode.DEPTH_FIRST,
+      allowSelfDelegation: options.allowSelfDelegation || false,
+      aggregateResults: options.aggregateResults || true,
+      ...options
+    };
+  }
+
+  /**
+   * Validate the execution context
+   * @param {ExecutionContext} context - Execution context
+   * @param {OrchestrationEngine} engine - Orchestration engine
+   * @returns {object} Validation result
+   */
+  validate(context, engine) {
+    const errors = [];
+    const input = context.input;
+
+    // Check for root skill or task
+    if (!input.rootSkill && !input.task) {
+      errors.push('Nested pattern requires input.rootSkill or input.task');
+    }
+
+    // Check root skill exists
+    if (input.rootSkill && !engine.getSkill(input.rootSkill)) {
+      errors.push(`Unknown root skill: ${input.rootSkill}`);
+    }
+
+    // Check delegation map if provided
+    if (input.delegationMap) {
+      for (const [parent, children] of Object.entries(input.delegationMap)) {
+        if (!engine.getSkill(parent)) {
+          errors.push(`Unknown skill in delegation map: ${parent}`);
+        }
+        for (const child of children) {
+          if (!engine.getSkill(child)) {
+            errors.push(`Unknown child skill: ${child}`);
+          }
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Execute nested pattern
+   * @param {ExecutionContext} context - Execution context
+   * @param {OrchestrationEngine} engine - Orchestration engine
+   * @returns {Promise<object>} Execution result
+   */
+  async execute(context, engine) {
+    const validation = this.validate(context, engine);
+    if (!validation.valid) {
+      throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
+    }
+
+    const { rootSkill, task, delegationMap = {}, initialInput = {} } = context.input;
+    
+    engine.emit('nestedStarted', {
+      context,
+      rootSkill,
+      delegationMap
+    });
+
+    // Determine root skill from task if not provided
+    let actualRootSkill = rootSkill;
+    if (!actualRootSkill && task) {
+      actualRootSkill = await engine.resolveSkill(task);
+      if (!actualRootSkill) {
+        throw new Error(`Cannot resolve skill for task: ${task}`);
+      }
+    }
+
+    const executionTree = {
+      skill: actualRootSkill,
+      children: [],
+      output: null,
+      status: ExecutionStatus.PENDING,
+      depth: 0
+    };
+
+    try {
+      await this._executeNode(
+        executionTree,
+        initialInput,
+        delegationMap,
+        context,
+        engine,
+        0
+      );
+
+      const aggregatedResult = this.options.aggregateResults
+        ? this._aggregateResults(executionTree)
+        : executionTree;
+
+      engine.emit('nestedCompleted', {
+        context,
+        tree: executionTree,
+        aggregatedResult
+      });
+
+      return {
+        tree: executionTree,
+        aggregatedResult,
+        summary: this._createSummary(executionTree)
+      };
+
+    } catch (error) {
+      engine.emit('nestedFailed', {
+        context,
+        tree: executionTree,
+        error
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Execute a single node in the tree
+   * @private
+   */
+  async _executeNode(node, input, delegationMap, parentContext, engine, depth) {
+    if (depth >= this.options.maxDepth) {
+      node.status = ExecutionStatus.FAILED;
+      node.error = `Max depth (${this.options.maxDepth}) exceeded`;
+      return;
+    }
+
+    const stepContext = new ExecutionContext({
+      task: `Nested: ${node.skill} (depth: ${depth})`,
+      skill: node.skill,
+      input,
+      parentId: parentContext.id,
+      metadata: {
+        pattern: PatternType.NESTED,
+        depth,
+        hasChildren: delegationMap[node.skill]?.length > 0
+      }
+    });
+
+    parentContext.children.push(stepContext);
+
+    engine.emit('nestedNodeStarted', {
+      node,
+      depth,
+      stepContext
+    });
+
+    try {
+      stepContext.start();
+      node.status = ExecutionStatus.RUNNING;
+
+      // Execute the skill
+      const output = await engine.executeSkill(node.skill, input, parentContext);
+      node.output = output;
+      stepContext.complete(output);
+
+      // Check for child skills to delegate to
+      const childSkills = delegationMap[node.skill] || [];
+      
+      if (childSkills.length > 0) {
+        for (const childSkill of childSkills) {
+          // Skip self-delegation unless allowed
+          if (!this.options.allowSelfDelegation && childSkill === node.skill) {
+            continue;
+          }
+
+          const childNode = {
+            skill: childSkill,
+            children: [],
+            output: null,
+            status: ExecutionStatus.PENDING,
+            depth: depth + 1
+          };
+          node.children.push(childNode);
+
+          // Use parent output as child input
+          await this._executeNode(
+            childNode,
+            output,
+            delegationMap,
+            parentContext,
+            engine,
+            depth + 1
+          );
+        }
+      }
+
+      node.status = ExecutionStatus.COMPLETED;
+
+      engine.emit('nestedNodeCompleted', {
+        node,
+        depth,
+        output
+      });
+
+    } catch (error) {
+      node.status = ExecutionStatus.FAILED;
+      node.error = error.message;
+      stepContext.fail(error);
+
+      engine.emit('nestedNodeFailed', {
+        node,
+        depth,
+        error
+      });
+
+      throw error;
+    }
+  }
+
+  /**
+   * Aggregate results from tree
+   * @private
+   */
+  _aggregateResults(node) {
+    const result = {
+      skill: node.skill,
+      output: node.output,
+      childOutputs: []
+    };
+
+    for (const child of node.children) {
+      result.childOutputs.push(this._aggregateResults(child));
+    }
+
+    return result;
+  }
+
+  /**
+   * Create execution summary
+   * @private
+   */
+  _createSummary(tree) {
+    let totalNodes = 0;
+    let completed = 0;
+    let failed = 0;
+    let maxDepth = 0;
+
+    const traverse = (node) => {
+      totalNodes++;
+      if (node.status === ExecutionStatus.COMPLETED) completed++;
+      if (node.status === ExecutionStatus.FAILED) failed++;
+      if (node.depth > maxDepth) maxDepth = node.depth;
+      
+      for (const child of node.children) {
+        traverse(child);
+      }
+    };
+
+    traverse(tree);
+
+    return {
+      totalNodes,
+      completed,
+      failed,
+      maxDepth,
+      successRate: totalNodes > 0 
+        ? (completed / totalNodes * 100).toFixed(1) + '%' 
+        : '0%'
+    };
+  }
+}
+
+/**
+ * Create a nested pattern with custom options
+ * @param {object} options - Pattern options
+ * @returns {NestedPattern} Nested pattern instance
+ */
+function createNestedPattern(options = {}) {
+  return new NestedPattern(options);
+}
+
+module.exports = {
+  NestedPattern,
+  NestedMode,
+  createNestedPattern
+};

package/src/orchestration/patterns/sequential.js

@@ -0,0 +1,278 @@
+/**
+ * SequentialPattern - Linear skill execution pattern
+ * 
+ * Executes skills in sequence, passing output from one skill
+ * as input to the next. Supports error handling and recovery.
+ */
+
+const { BasePattern } = require('../pattern-registry');
+const { PatternType, ExecutionContext, ExecutionStatus } = require('../orchestration-engine');
+
+/**
+ * Sequential execution options
+ */
+const SequentialOptions = {
+  STOP_ON_ERROR: 'stop-on-error',
+  CONTINUE_ON_ERROR: 'continue-on-error',
+  RETRY_ON_ERROR: 'retry-on-error'
+};
+
+/**
+ * SequentialPattern - Execute skills one after another
+ */
+class SequentialPattern extends BasePattern {
+  constructor(options = {}) {
+    super({
+      name: PatternType.SEQUENTIAL,
+      type: PatternType.SEQUENTIAL,
+      description: 'Execute skills in sequence, passing output as input to next skill',
+      version: '1.0.0',
+      tags: ['linear', 'pipeline', 'workflow'],
+      useCases: [
+        'Step-by-step workflows',
+        'Data transformation pipelines',
+        'Dependent task chains'
+      ],
+      complexity: 'low',
+      supportsParallel: false,
+      requiresHuman: false
+    });
+
+    this.options = {
+      errorHandling: options.errorHandling || SequentialOptions.STOP_ON_ERROR,
+      maxRetries: options.maxRetries || 3,
+      retryDelay: options.retryDelay || 1000,
+      transformOutput: options.transformOutput || ((output, context) => output),
+      ...options
+    };
+  }
+
+  /**
+   * Validate the execution context
+   * @param {ExecutionContext} context - Execution context
+   * @param {OrchestrationEngine} engine - Orchestration engine
+   * @returns {object} Validation result
+   */
+  validate(context, engine) {
+    const errors = [];
+    const input = context.input;
+
+    // Check for skills array
+    if (!input.skills || !Array.isArray(input.skills)) {
+      errors.push('Sequential pattern requires input.skills array');
+    } else if (input.skills.length === 0) {
+      errors.push('Sequential pattern requires at least one skill');
+    } else {
+      // Validate each skill exists
+      for (const skillName of input.skills) {
+        if (!engine.getSkill(skillName)) {
+          errors.push(`Unknown skill: ${skillName}`);
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Execute skills sequentially
+   * @param {ExecutionContext} context - Execution context
+   * @param {OrchestrationEngine} engine - Orchestration engine
+   * @returns {Promise<object>} Execution result
+   */
+  async execute(context, engine) {
+    const validation = this.validate(context, engine);
+    if (!validation.valid) {
+      throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
+    }
+
+    const { skills, initialInput = {} } = context.input;
+    const results = [];
+    let currentInput = { ...initialInput };
+    let lastOutput = null;
+
+    engine.emit('sequentialStarted', {
+      context,
+      skills,
+      totalSteps: skills.length
+    });
+
+    for (let i = 0; i < skills.length; i++) {
+      const skillName = skills[i];
+      const stepContext = new ExecutionContext({
+        task: `Step ${i + 1}: ${skillName}`,
+        skill: skillName,
+        input: currentInput,
+        parentId: context.id,
+        metadata: {
+          stepIndex: i,
+          totalSteps: skills.length,
+          pattern: PatternType.SEQUENTIAL
+        }
+      });
+
+      context.children.push(stepContext);
+
+      engine.emit('sequentialStepStarted', {
+        context,
+        stepContext,
+        stepIndex: i,
+        skillName
+      });
+
+      try {
+        stepContext.start();
+        
+        const output = await this._executeWithRetry(
+          () => engine.executeSkill(skillName, currentInput, context),
+          skillName,
+          engine
+        );
+
+        stepContext.complete(output);
+        lastOutput = output;
+        
+        // Transform output for next step
+        currentInput = this.options.transformOutput(output, stepContext);
+        
+        results.push({
+          step: i + 1,
+          skill: skillName,
+          status: ExecutionStatus.COMPLETED,
+          output
+        });
+
+        engine.emit('sequentialStepCompleted', {
+          context,
+          stepContext,
+          stepIndex: i,
+          skillName,
+          output
+        });
+
+      } catch (error) {
+        stepContext.fail(error);
+
+        results.push({
+          step: i + 1,
+          skill: skillName,
+          status: ExecutionStatus.FAILED,
+          error: error.message
+        });
+
+        engine.emit('sequentialStepFailed', {
+          context,
+          stepContext,
+          stepIndex: i,
+          skillName,
+          error
+        });
+
+        // Handle error based on configuration
+        if (this.options.errorHandling === SequentialOptions.STOP_ON_ERROR) {
+          throw new Error(
+            `Sequential execution failed at step ${i + 1} (${skillName}): ${error.message}`
+          );
+        }
+        
+        // Continue on error - use previous output as input
+        engine.emit('sequentialContinuingAfterError', {
+          context,
+          stepIndex: i,
+          skillName,
+          error
+        });
+      }
+    }
+
+    const summary = this._createSummary(results, skills);
+
+    engine.emit('sequentialCompleted', {
+      context,
+      results,
+      summary
+    });
+
+    return {
+      results,
+      summary,
+      finalOutput: lastOutput
+    };
+  }
+
+  /**
+   * Execute with retry
+   * @private
+   */
+  async _executeWithRetry(fn, skillName, engine) {
+    let lastError;
+    
+    for (let attempt = 1; attempt <= this.options.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+        
+        if (attempt < this.options.maxRetries && 
+            this.options.errorHandling === SequentialOptions.RETRY_ON_ERROR) {
+          engine.emit('sequentialRetrying', {
+            skillName,
+            attempt,
+            maxRetries: this.options.maxRetries,
+            error
+          });
+          
+          await this._delay(this.options.retryDelay * attempt);
+        } else {
+          throw error;
+        }
+      }
+    }
+    
+    throw lastError;
+  }
+
+  /**
+   * Delay helper
+   * @private
+   */
+  _delay(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Create execution summary
+   * @private
+   */
+  _createSummary(results, skills) {
+    const completed = results.filter(r => r.status === ExecutionStatus.COMPLETED).length;
+    const failed = results.filter(r => r.status === ExecutionStatus.FAILED).length;
+    
+    return {
+      totalSteps: skills.length,
+      completed,
+      failed,
+      successRate: skills.length > 0 ? (completed / skills.length * 100).toFixed(1) + '%' : '0%',
+      allCompleted: completed === skills.length,
+      hasFailed: failed > 0
+    };
+  }
+}
+
+/**
+ * Create a sequential pattern with custom options
+ * @param {object} options - Pattern options
+ * @returns {SequentialPattern} Sequential pattern instance
+ */
+function createSequentialPattern(options = {}) {
+  return new SequentialPattern(options);
+}
+
+module.exports = {
+  SequentialPattern,
+  SequentialOptions,
+  createSequentialPattern
+};