elsabro 7.3.0 → 7.3.1

package/flow-engine/src/callbacks.js

@@ -54,6 +54,9 @@ class CallbackProtocol {
   requiresTeam(branches) {
     if (!Array.isArray(branches) || branches.length < 2) return false;
 
+    // Validate each branch before accessing config
+    this._validateBranches(branches, 'requiresTeam');
+
     const allHaiku = branches.every(b =>
       b.config && b.config.model === 'haiku'
     );
@@ -90,6 +93,9 @@ class CallbackProtocol {
    * @returns {{ name: string, agent: string, role: string, model: string }[]}
    */
   composeTeam(branches, nodeContext = 'default') {
+    // Validate branches before processing
+    this._validateBranches(branches, 'composeTeam');
+
     // 1. Start with branch agents
     const members = branches.map((b, i) => ({
       name: `${b.id}-${i + 1}`,
@@ -127,6 +133,9 @@ class CallbackProtocol {
    * @returns {object}
    */
   buildParallelInstruction(nodeId, branches, context = {}) {
+    // Validate branches before processing
+    this._validateBranches(branches, 'buildParallelInstruction');
+
     const useAgentTeams = this.requiresTeam(branches);
 
     const instruction = {
@@ -251,6 +260,76 @@ class CallbackProtocol {
 
   // ---------- Internal ----------
 
+  /**
+   * Validate a single branch object structure.
+   * @private
+   * @param {*} branch - Branch object to validate
+   * @param {number} index - Index in branches array (for error messages)
+   * @param {string} methodName - Name of calling method (for error messages)
+   * @throws {Error} If branch is invalid
+   */
+  _validateBranch(branch, index, methodName) {
+    if (!branch || typeof branch !== 'object') {
+      throw new Error(
+        `[CallbackProtocol.${methodName}] Invalid branch at index ${index}: ` +
+        `expected object, got ${typeof branch}`
+      );
+    }
+
+    if (!branch.id || typeof branch.id !== 'string') {
+      throw new Error(
+        `[CallbackProtocol.${methodName}] Invalid branch at index ${index}: ` +
+        `missing or invalid "id" property (expected non-empty string)`
+      );
+    }
+
+    if (!branch.agent || typeof branch.agent !== 'string') {
+      throw new Error(
+        `[CallbackProtocol.${methodName}] Invalid branch at index ${index}: ` +
+        `missing or invalid "agent" property (expected non-empty string)`
+      );
+    }
+
+    // Validate config if present (optional but must be object if provided)
+    if (branch.config !== undefined && branch.config !== null) {
+      if (typeof branch.config !== 'object') {
+        throw new Error(
+          `[CallbackProtocol.${methodName}] Invalid branch at index ${index}: ` +
+          `"config" must be an object, got ${typeof branch.config}`
+        );
+      }
+
+      // Validate model if present in config
+      if (branch.config.model !== undefined &&
+          typeof branch.config.model !== 'string') {
+        throw new Error(
+          `[CallbackProtocol.${methodName}] Invalid branch at index ${index}: ` +
+          `"config.model" must be a string, got ${typeof branch.config.model}`
+        );
+      }
+    }
+  }
+
+  /**
+   * Validate branches array structure.
+   * @private
+   * @param {*} branches - Branches array to validate
+   * @param {string} methodName - Name of calling method (for error messages)
+   * @throws {Error} If branches array or any branch is invalid
+   */
+  _validateBranches(branches, methodName) {
+    if (!Array.isArray(branches)) {
+      throw new Error(
+        `[CallbackProtocol.${methodName}] Invalid branches parameter: ` +
+        `expected array, got ${typeof branches}`
+      );
+    }
+
+    branches.forEach((branch, index) => {
+      this._validateBranch(branch, index, methodName);
+    });
+  }
+
   /**
    * Get ordered list of support agents for padding, excluding those already in the team.
    * @private

package/flow-engine/src/checkpoint.js

@@ -107,6 +107,47 @@ class CheckpointManager {
 
     return toRemove.length;
   }
+
+  /**
+   * Auto-cleanup checkpoints older than a specified number of days.
+   *
+   * @param {string} [flowId] – optional flow identifier (if not provided, cleans all flows)
+   * @param {number} [daysOld=7] – remove checkpoints older than this many days
+   * @returns {number} number of checkpoints removed
+   */
+  autoCleanup(flowId = null, daysOld = 7) {
+    if (!fs.existsSync(this.dir)) return 0;
+
+    const now = Date.now();
+    const maxAge = daysOld * 24 * 60 * 60 * 1000; // convert days to milliseconds
+    const cutoffTimestamp = now - maxAge;
+
+    let files = fs.readdirSync(this.dir).filter(f => f.endsWith('.json'));
+
+    // If flowId specified, filter to only that flow
+    if (flowId) {
+      files = files.filter(f => f.startsWith(`${flowId}-`));
+    }
+
+    let removedCount = 0;
+
+    for (const filename of files) {
+      // Extract timestamp from filename pattern: flowId-timestamp-seq.json
+      const match = filename.match(/-(\d+)-\d+\.json$/);
+      if (match) {
+        const timestamp = parseInt(match[1], 10);
+        if (timestamp < cutoffTimestamp) {
+          const filepath = path.join(this.dir, filename);
+          if (fs.existsSync(filepath)) {
+            fs.unlinkSync(filepath);
+            removedCount++;
+          }
+        }
+      }
+    }
+
+    return removedCount;
+  }
 }
 
 module.exports = { CheckpointManager };

package/flow-engine/src/cli.js

@@ -22,6 +22,152 @@ const { resolveTemplate } = require('./template');
 const { checkRuntimeStatus, NotImplementedError, DeprecatedNodeError } = require('./executors');
 const { serializeContext, deserializeContext } = require('./runner');
 
+// ---------- State and Context Management ----------
+
+/**
+ * Update state.json with current flow execution state.
+ *
+ * @param {string} flowId - Flow identifier
+ * @param {object} checkpoint - Current checkpoint data
+ * @param {string} phase - Current execution phase
+ * @param {object} [metadata] - Additional metadata
+ */
+function updateStateJson(flowId, checkpoint, phase, metadata = {}) {
+  const stateFile = path.join(process.cwd(), '.elsabro', 'state.json');
+  let state = {};
+
+  // Read existing state
+  try {
+    if (fs.existsSync(stateFile)) {
+      state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    }
+  } catch (err) {
+    // Initialize new state if file doesn't exist or is corrupted
+    state = {
+      version: '1.0.0',
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      current_flow: null,
+      context: {},
+      history: [],
+      pending_tasks: [],
+      blocked_on: null
+    };
+  }
+
+  // Update state with current flow info
+  state.updated_at = new Date().toISOString();
+  state.current_flow = {
+    command: 'flow-engine',
+    flowId,
+    phase,
+    currentNode: checkpoint.currentNode,
+    nextNode: checkpoint.nextNode,
+    nodesVisited: checkpoint.nodesVisited || [],
+    started_at: metadata.started_at || state.current_flow?.started_at || new Date().toISOString()
+  };
+
+  // Merge context from checkpoint
+  if (checkpoint.context) {
+    const ctx = typeof checkpoint.context === 'string'
+      ? deserializeContext(checkpoint.context)
+      : checkpoint.context;
+    state.context = { ...state.context, ...ctx };
+  }
+
+  // Add metadata
+  if (metadata.error) {
+    state.current_flow.error = metadata.error;
+  }
+  if (metadata.finished) {
+    state.current_flow.finished = true;
+    state.current_flow.completed_at = new Date().toISOString();
+  }
+
+  // Ensure directory exists
+  const stateDir = path.dirname(stateFile);
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+  }
+
+  // Write state
+  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
+}
+
+/**
+ * Update context.md with human-readable summary.
+ *
+ * @param {string} flowId - Flow identifier
+ * @param {object} checkpoint - Current checkpoint data
+ * @param {string} phase - Current execution phase
+ * @param {object} [state] - Current state object
+ */
+function updateContextMd(flowId, checkpoint, phase, state = null) {
+  const contextFile = path.join(process.cwd(), '.elsabro', 'context.md');
+
+  // Load state if not provided
+  if (!state) {
+    const stateFile = path.join(process.cwd(), '.elsabro', 'state.json');
+    try {
+      if (fs.existsSync(stateFile)) {
+        state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      }
+    } catch (err) {
+      state = { context: {}, history: [] };
+    }
+  }
+
+  const now = new Date().toISOString();
+  const ctx = state.context || {};
+  const history = state.history || [];
+
+  let content = `# Estado Actual del Proyecto\n\n`;
+  content += `**Última actualización**: ${now}\n`;
+  content += `**Comando actual**: flow-engine (${flowId})\n`;
+  content += `**Fase**: ${phase}\n`;
+  content += `**Nodo actual**: ${checkpoint.currentNode || 'none'}\n`;
+  content += `**Siguiente nodo**: ${checkpoint.nextNode || 'none'}\n\n`;
+
+  content += `## Progreso del Flow\n`;
+  content += `- **Nodos visitados**: ${(checkpoint.nodesVisited || []).length}\n`;
+  content += `- **Nodos recientes**: ${(checkpoint.nodesVisited || []).slice(-5).join(', ') || 'none'}\n\n`;
+
+  if (ctx.inputs) {
+    content += `## Contexto de Entrada\n`;
+    content += `- **Task**: ${ctx.inputs.task || 'N/A'}\n`;
+    content += `- **Profile**: ${ctx.inputs.profile || 'N/A'}\n`;
+    content += `- **Complexity**: ${ctx.inputs.complexity || 'N/A'}\n\n`;
+  }
+
+  if (history.length > 0) {
+    content += `## Historial Reciente\n`;
+    history.slice(-3).reverse().forEach((entry, idx) => {
+      content += `${idx + 1}. ${entry.command} - ${entry.result} (${entry.completed_at || 'N/A'})\n`;
+    });
+    content += `\n`;
+  }
+
+  content += `## Para Continuar\n`;
+  content += `\`\`\`bash\n`;
+  if (checkpoint.nextNode) {
+    content += `# Flow en progreso - ejecutar siguiente paso\n`;
+    content += `node flow-engine/src/cli.js step --flow flows/development-flow.json\n`;
+  } else {
+    content += `# Flow completado o sin inicializar\n`;
+    content += `node flow-engine/src/cli.js status --flow flows/development-flow.json\n`;
+  }
+  content += `\`\`\`\n`;
+
+  // Ensure directory exists
+  const contextDir = path.dirname(contextFile);
+  if (!fs.existsSync(contextDir)) {
+    fs.mkdirSync(contextDir, { recursive: true });
+  }
+
+  // Write context
+  fs.writeFileSync(contextFile, content);
+}
+
 // ---------- Argument parsing ----------
 
 function parseArgs(argv) {
@@ -238,12 +384,20 @@ function cmdInit(args) {
 
   const entryNode = engine.graph.entryNode;
 
-  cpManager.save(flowId, {
+  const checkpointData = {
     currentNode: null,
     nextNode: entryNode,
     context: serializeContext(context),
     nodesVisited: []
+  };
+
+  cpManager.save(flowId, checkpointData);
+
+  // Update state.json and context.md
+  updateStateJson(flowId, checkpointData, 'initialized', {
+    started_at: new Date().toISOString()
   });
+  updateContextMd(flowId, checkpointData, 'initialized');
 
   return {
     initialized: true,
@@ -307,6 +461,17 @@ async function cmdStep(args) {
         continue;
       }
       if (err instanceof NotImplementedError) {
+        // Update state with error before returning
+        const errorCheckpoint = {
+          currentNode: node.id,
+          nextNode: currentNodeId,
+          context: serializeContext(context),
+          nodesVisited: [...nodesVisited]
+        };
+        updateStateJson(flowId, errorCheckpoint, 'error', {
+          error: err.message
+        });
+        updateContextMd(flowId, errorCheckpoint, 'error');
         return { error: err.message, stoppedAt: node.id };
       }
     }
@@ -327,12 +492,20 @@ async function cmdStep(args) {
           nodesVisited.push(node.id);
           context.nodes[node.id] = { outputs: resolvedOutputs };
 
-          cpManager.save(flowId, {
+          const exitCheckpoint = {
             currentNode: node.id,
             nextNode: null,
             context: serializeContext(context),
             nodesVisited: [...nodesVisited]
+          };
+
+          cpManager.save(flowId, exitCheckpoint);
+
+          // Update state.json and context.md for completion
+          updateStateJson(flowId, exitCheckpoint, 'done', {
+            finished: true
           });
+          updateContextMd(flowId, exitCheckpoint, 'done');
 
           return {
             finished: true,
@@ -430,12 +603,18 @@ async function cmdStep(args) {
     }
 
     // Save checkpoint at this actionable node
-    cpManager.save(flowId, {
+    const actionCheckpoint = {
       currentNode: node.id,
       nextNode: currentNodeId,
       context: serializeContext(context),
       nodesVisited: [...nodesVisited]
-    });
+    };
+
+    cpManager.save(flowId, actionCheckpoint);
+
+    // Update state.json and context.md
+    updateStateJson(flowId, actionCheckpoint, 'stepping');
+    updateContextMd(flowId, actionCheckpoint, 'stepping');
 
     return {
       instruction,
@@ -446,6 +625,17 @@ async function cmdStep(args) {
   }
 
   // Reached end without actionable node
+  const finishedCheckpoint = {
+    currentNode: null,
+    nextNode: null,
+    context: serializeContext(context),
+    nodesVisited: [...nodesVisited]
+  };
+
+  // Update state for finished flow
+  updateStateJson(flowId, finishedCheckpoint, 'done', { finished: true });
+  updateContextMd(flowId, finishedCheckpoint, 'done');
+
   return { finished: true, nodesVisited };
 }
 
@@ -514,12 +704,21 @@ function cmdComplete(args) {
     }
   }
 
-  cpManager.save(flowId, {
+  const completedCheckpoint = {
     currentNode: node.id,
     nextNode,
     context: serializeContext(context),
     nodesVisited: [...nodesVisited]
+  };
+
+  cpManager.save(flowId, completedCheckpoint);
+
+  // Update state.json and context.md
+  const phase = nextNode ? 'stepping' : 'done';
+  updateStateJson(flowId, completedCheckpoint, phase, {
+    finished: !nextNode
   });
+  updateContextMd(flowId, completedCheckpoint, phase);
 
   return {
     completed: true,
@@ -594,4 +793,13 @@ if (require.main === module) {
   });
 }
 
-module.exports = { main, parseArgs, flowIdFromPath, isAutoResolvable, detectNodeContext, COMMANDS };
+module.exports = {
+  main,
+  parseArgs,
+  flowIdFromPath,
+  isAutoResolvable,
+  detectNodeContext,
+  updateStateJson,
+  updateContextMd,
+  COMMANDS
+};

package/flow-engine/src/executors.js

@@ -9,9 +9,15 @@
  * 9 node types total:
  *   Simple (Wave 2):  entry, exit, condition, router, sequence
  *   Complex (Wave 3): agent, parallel, interrupt, team
+ *
+ * NOTE: The elsabro-orchestrator agent uses Agent Teams (TeamCreate, TeamDelete, SendMessage)
+ * for parallel execution coordination. This is NOT related to the elsabro-scrum-master agent,
+ * which is a separate utility for sprint planning. They are independent agents serving
+ * different purposes.
  */
 
 const { resolveTemplate, resolveExpression } = require('./template');
+const { serializeContext } = require('./runner');
 
 // ---------- Error types ----------
 
@@ -59,6 +65,7 @@ function checkRuntimeStatus(node) {
  * Entry node: no-op, just transitions to next.
  */
 async function executeEntry(node, context, callbacks) {
+  checkRuntimeStatus(node);
   return { next: node.next, outputs: {} };
 }
 
@@ -66,6 +73,7 @@ async function executeEntry(node, context, callbacks) {
  * Exit node: resolve output templates, terminate flow.
  */
 async function executeExit(node, context, callbacks) {
+  checkRuntimeStatus(node);
   const resolvedOutputs = node.outputs
     ? resolveTemplate(node.outputs, context)
     : {};
@@ -81,7 +89,18 @@ async function executeExit(node, context, callbacks) {
  * Condition node: evaluate condition, route to true/false branch.
  */
 async function executeCondition(node, context, callbacks) {
+  checkRuntimeStatus(node);
   if (!node.condition) {
+    // Save checkpoint before error
+    if (callbacks.onCheckpoint) {
+      await callbacks.onCheckpoint({
+        currentNode: node.id,
+        nextNode: null,
+        context: serializeContext(context),
+        stoppedAt: node.id,
+        reason: 'Condition node has no "condition" field'
+      });
+    }
     throw new ExecutorError(node.id, 'Condition node has no "condition" field');
   }
 
@@ -94,6 +113,16 @@ async function executeCondition(node, context, callbacks) {
   const nextNode = result ? node.true : node.false;
 
   if (!nextNode) {
+    // Save checkpoint before error
+    if (callbacks.onCheckpoint) {
+      await callbacks.onCheckpoint({
+        currentNode: node.id,
+        nextNode: null,
+        context: serializeContext(context),
+        stoppedAt: node.id,
+        reason: `Condition evaluated to ${!!result} but no "${result ? 'true' : 'false'}" branch defined`
+      });
+    }
     throw new ExecutorError(
       node.id,
       `Condition evaluated to ${!!result} but no "${result ? 'true' : 'false'}" branch defined`
@@ -107,6 +136,7 @@ async function executeCondition(node, context, callbacks) {
  * Router node: evaluate condition as a string, match against routes map.
  */
 async function executeRouter(node, context, callbacks) {
+  checkRuntimeStatus(node);
   if (!node.condition) {
     throw new ExecutorError(node.id, 'Router node has no "condition" field');
   }
@@ -139,8 +169,19 @@ async function executeRouter(node, context, callbacks) {
 
 /**
  * Sequence node: execute steps sequentially, collect step outputs.
+ *
+ * Special integrations:
+ * - skill-discovery.sh: Auto-parses JSON output, extracts discovered/recommended skills
+ * - skill-install.sh: Can be called via bash action for skill installation
+ *
+ * Callbacks used:
+ * - onBash(command): Execute bash commands
+ * - onReadFiles(files): Read file contents
+ * - onAgent(params): Invoke agent execution
+ * - onLog(level, message): Optional logging callback for skill discovery results
  */
 async function executeSequence(node, context, callbacks) {
+  checkRuntimeStatus(node);
   const steps = node.steps || [];
 
   for (const step of steps) {
@@ -154,6 +195,39 @@ async function executeSequence(node, context, callbacks) {
           const command = resolveTemplate(step.command, context);
           if (callbacks.onBash) {
             stepOutput = await callbacks.onBash(command);
+
+            // Special handling for skill-discovery hook integration
+            if (command.includes('skill-discovery.sh') && stepOutput.output) {
+              try {
+                // Parse JSON output from skill-discovery
+                const discoveryData = JSON.parse(stepOutput.output);
+
+                // Enhance output with parsed discovery data
+                stepOutput.discovered = discoveryData.discovered || [];
+                stepOutput.recommended = discoveryData.recommended || {};
+                stepOutput.registry_available = discoveryData.registry_available || false;
+
+                // Log skill discovery results (if callbacks provide logging)
+                if (callbacks.onLog) {
+                  callbacks.onLog('info', `[skill-discovery] Found ${stepOutput.discovered.length} installed skills`);
+
+                  if (stepOutput.recommended.skills && stepOutput.recommended.skills.length > 0) {
+                    callbacks.onLog('info', `[skill-discovery] Recommended: ${stepOutput.recommended.skills.join(', ')}`);
+                  }
+
+                  if (stepOutput.recommended.install_commands && stepOutput.recommended.install_commands.length > 0) {
+                    callbacks.onLog('info', `[skill-discovery] ${stepOutput.recommended.install_commands.length} install commands available`);
+                  }
+                }
+              } catch (parseErr) {
+                // If JSON parse fails, log warning but don't fail the step
+                if (callbacks.onLog) {
+                  callbacks.onLog('warn', `[skill-discovery] Failed to parse output as JSON: ${parseErr.message}`);
+                }
+                // Keep raw output available
+                stepOutput.parseError = parseErr.message;
+              }
+            }
           } else {
             stepOutput = { output: '', exitCode: -1, skipped: true };
           }
@@ -234,6 +308,7 @@ async function executeSequence(node, context, callbacks) {
  * Agent node: invoke an external agent via callback.
  */
 async function executeAgent(node, context, callbacks) {
+  checkRuntimeStatus(node);
   const resolvedInputs = node.inputs
     ? resolveTemplate(node.inputs, context)
     : {};
@@ -267,6 +342,7 @@ async function executeAgent(node, context, callbacks) {
  * Parallel node: execute branches concurrently via callback.
  */
 async function executeParallel(node, context, callbacks) {
+  checkRuntimeStatus(node);
   const branches = node.branches || [];
 
   // Resolve inputs for each branch
@@ -313,9 +389,65 @@ async function executeParallel(node, context, callbacks) {
   if (node.maxIterations && context._iterations[node.id] >= node.maxIterations) {
     if (node.onMaxIterations) {
       return { next: node.onMaxIterations, outputs: { branches: branchOutputs } };
+    } else {
+      // Fall through to next when no handler defined (graceful degradation)
+      return { next: node.next, outputs: { branches: branchOutputs } };
     }
   }
 
+  // Check errorPolicy quorum for parallel failures
+  if (node.errorPolicy === 'quorum') {
+    // Count successful branches
+    let successCount = 0;
+    const totalCount = branchResults.length;
+
+    for (const branchResult of branchResults) {
+      // Consider a branch successful if it doesn't have an error and wasn't skipped
+      if (branchResult && !branchResult.error && !branchResult.skipped) {
+        successCount++;
+      }
+    }
+
+    // Determine if quorum is met
+    let quorumMet = true;
+    let quorumType = 'default';
+
+    if (node.quorumThreshold !== undefined) {
+      // Percentage-based quorum (0.0 to 1.0)
+      quorumType = 'threshold';
+      const successRate = totalCount > 0 ? successCount / totalCount : 0;
+      quorumMet = successRate >= node.quorumThreshold;
+    } else if (node.quorumMinSuccess !== undefined) {
+      // Absolute count quorum
+      quorumType = 'minSuccess';
+      quorumMet = successCount >= node.quorumMinSuccess;
+    } else {
+      // Default: all must succeed (100% quorum)
+      quorumType = 'all';
+      quorumMet = successCount === totalCount;
+    }
+
+    // Build detailed outputs
+    const quorumOutputs = {
+      branches: branchOutputs,
+      quorumMet,
+      quorumType,
+      successCount,
+      totalCount,
+      failureCount: totalCount - successCount,
+      successRate: totalCount > 0 ? successCount / totalCount : 0
+    };
+
+    if (!quorumMet) {
+      // Quorum not met, route to error handler if defined
+      const errorRoute = node.onError || node.next;
+      return { next: errorRoute, outputs: quorumOutputs };
+    }
+
+    // Quorum met, proceed to next
+    return { next: node.next, outputs: quorumOutputs };
+  }
+
   return { next: node.next, outputs: { branches: branchOutputs } };
 }
 
@@ -323,6 +455,7 @@ async function executeParallel(node, context, callbacks) {
  * Interrupt node: pause execution, display info, route on user choice.
  */
 async function executeInterrupt(node, context, callbacks) {
+  checkRuntimeStatus(node);
   const resolvedDisplay = node.display
     ? resolveTemplate(node.display, context)
     : { title: node.reason || 'Interrupt', options: [] };
@@ -359,11 +492,9 @@ async function executeInterrupt(node, context, callbacks) {
  * Team node: deprecated, throws NotImplementedError.
  */
 async function executeTeam(node, context, callbacks) {
+  checkRuntimeStatus(node);
   // Team nodes are deprecated in ELSABRO v5.3+
   // Agent Teams are now handled via parallel dispatch in execute.md#3-dispatch + callbacks.js
-  if (node.runtime_status === 'not_implemented') {
-    throw new NotImplementedError(node.id, node.gaps);
-  }
 
   // If somehow called on a non-deprecated team node
   if (callbacks.onTeam) {