elsabro 6.0.0 → 7.0.0

package/flow-engine/src/cli.js

@@ -0,0 +1,597 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CLI entry point for the ELSABRO flow engine.
+ *
+ * Commands:
+ *   validate  --flow <path>                        Validate flow, report parallel nodes + team compositions
+ *   dry-run   --flow <path> --task <str> --profile <str>  Full run with mock callbacks
+ *   init      --flow <path> --task <str> --profile <str>  Create initial checkpoint
+ *   step      --flow <path>                        Advance to next actionable node
+ *   complete  --flow <path> --result <json>         Apply result, advance checkpoint
+ *   status    --flow <path>                        Show current state
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { FlowEngine } = require('./index');
+const { CheckpointManager } = require('./checkpoint');
+const { CallbackProtocol } = require('./callbacks');
+const { resolveTemplate } = require('./template');
+const { checkRuntimeStatus, NotImplementedError, DeprecatedNodeError } = require('./executors');
+const { serializeContext, deserializeContext } = require('./runner');
+
+// ---------- Argument parsing ----------
+
+function parseArgs(argv) {
+  const args = {};
+  let command = null;
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--') && !command) {
+      command = arg;
+    } else if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+
+  return { command, args };
+}
+
+// ---------- Flow ID from path ----------
+
+function flowIdFromPath(flowPath) {
+  const basename = path.basename(flowPath, '.json');
+  return basename.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+}
+
+// ---------- Node classification ----------
+
+const AUTO_RESOLVABLE = new Set(['entry', 'condition', 'router', 'exit']);
+
+function isAutoResolvable(node) {
+  if (AUTO_RESOLVABLE.has(node.type)) return true;
+  // Deprecated team nodes are auto-skipped
+  if (node.type === 'team' && node.runtime_status === 'deprecated') return true;
+  return false;
+}
+
+// ---------- Detect node context for team padding ----------
+
+function detectNodeContext(nodeId) {
+  if (nodeId.includes('implementation') || nodeId.includes('implement')) return 'implementation';
+  if (nodeId.includes('review') || nodeId.includes('check')) return 'review';
+  if (nodeId.includes('fix') || nodeId.includes('debug') || nodeId.includes('error')) return 'fix';
+  return 'default';
+}
+
+// ---------- Commands ----------
+
+/**
+ * validate: Parse and validate flow, report parallel nodes + team compositions.
+ */
+function cmdValidate(args) {
+  const flowPath = args.flow;
+  if (!flowPath) return { error: 'Missing --flow <path>' };
+
+  const flowJson = JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+  const engine = new FlowEngine();
+  engine.loadFlow(flowJson);
+
+  const protocol = new CallbackProtocol();
+  const parallelNodes = engine.getNodesWhere(n => n.type === 'parallel');
+
+  const teamAnalysis = parallelNodes.map(node => {
+    const branches = node.branches || [];
+    const needsTeam = protocol.requiresTeam(branches);
+    const nodeContext = detectNodeContext(node.id);
+
+    let team = null;
+    if (needsTeam) {
+      const members = protocol.composeTeam(branches, nodeContext);
+      team = {
+        name: protocol.generateTeamName(node.id),
+        memberCount: members.length,
+        members: members.map(m => ({ name: m.name, agent: m.agent, role: m.role }))
+      };
+    }
+
+    return {
+      nodeId: node.id,
+      branchCount: branches.length,
+      useAgentTeams: needsTeam,
+      reason: needsTeam ? `${branches.length} non-haiku branches` : 'all-haiku (subagents)',
+      team
+    };
+  });
+
+  return {
+    valid: true,
+    flowId: engine.getFlowMetadata().id,
+    nodeCount: engine.getNodeCount(),
+    parallelNodes: teamAnalysis
+  };
+}
+
+/**
+ * dry-run: Run full flow with mock callbacks, report path + team actions.
+ */
+async function cmdDryRun(args) {
+  const flowPath = args.flow;
+  if (!flowPath) return { error: 'Missing --flow <path>' };
+
+  const task = args.task || 'dry-run task';
+  const profile = args.profile || 'default';
+  const complexity = args.complexity || 'medium';
+
+  const flowJson = JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+  const engine = new FlowEngine();
+  engine.loadFlow(flowJson);
+
+  const protocol = new CallbackProtocol();
+  const teamActions = [];
+
+  const callbacks = {
+    onAgent: async (params) => {
+      // Return passed:true for verifier agents so verify_check conditions pass
+      if (params.agent === 'elsabro-verifier' || (params.id && params.id.includes('verify'))) {
+        return { passed: true, result: 'mock' };
+      }
+      return { result: 'mock', agent: params.agent };
+    },
+    onParallel: async (params) => {
+      const instruction = protocol.buildParallelInstruction(
+        params.nodeId,
+        params.branches,
+        { nodeContext: detectNodeContext(params.nodeId), taskSlug: task }
+      );
+      if (instruction.useAgentTeams) {
+        teamActions.push({
+          nodeId: params.nodeId,
+          teamName: instruction.team.name,
+          memberCount: instruction.team.members.length,
+          members: instruction.team.members.map(m => m.agent)
+        });
+      }
+      return params.branches.map(b => ({ id: b.id, result: 'mock' }));
+    },
+    onInterrupt: async (params) => {
+      const routes = params.routes || {};
+      const options = (params.display && params.display.options) || [];
+      // Auto-select: prefer 'approve' or first option
+      const approveOpt = options.find(o => o.id === 'approve' || o.id === 'continue');
+      if (approveOpt) return approveOpt.id;
+      const keys = Object.keys(routes);
+      return keys.length > 0 ? keys[0] : null;
+    },
+    onBash: async (cmd) => ({ output: 'mock', exitCode: 0 }),
+    onReadFiles: async (files) => ({ content: 'mock' }),
+    onNodeComplete: async (nodeId, result, ctx) => {
+      // For sequence nodes without explicit outputs: copy step data into node
+      // outputs so downstream conditions (e.g. quality_check) can reference them.
+      if (ctx) {
+        const node = engine.graph.nodes.get(nodeId);
+        if (node && node.type === 'sequence' && !node.outputs) {
+          const stepOutputs = {};
+          for (const step of (node.steps || [])) {
+            if (step.as && ctx.steps[step.as]) {
+              stepOutputs[step.as] = ctx.steps[step.as].output || {};
+            }
+          }
+          if (Object.keys(stepOutputs).length > 0) {
+            ctx.nodes[nodeId] = ctx.nodes[nodeId] || {};
+            ctx.nodes[nodeId].outputs = stepOutputs;
+          }
+        }
+      }
+    }
+  };
+
+  const result = await engine.run(
+    { task, profile, complexity },
+    callbacks
+  );
+
+  return {
+    success: result.success,
+    nodesVisited: result.nodesVisited,
+    nodeCount: result.nodesVisited.length,
+    teamActions,
+    log: protocol.getLog()
+  };
+}
+
+/**
+ * init: Create initial checkpoint for a flow.
+ */
+function cmdInit(args) {
+  const flowPath = args.flow;
+  if (!flowPath) return { error: 'Missing --flow <path>' };
+
+  const task = args.task || '';
+  const profile = args.profile || 'default';
+  const complexity = args.complexity || 'medium';
+
+  const flowJson = JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+  const engine = new FlowEngine();
+  engine.loadFlow(flowJson);
+
+  const flowId = flowIdFromPath(flowPath);
+  const cpManager = new CheckpointManager();
+
+  const context = {
+    inputs: { task, profile, complexity },
+    nodes: {},
+    steps: {},
+    state: {},
+    _iterations: {}
+  };
+
+  const entryNode = engine.graph.entryNode;
+
+  cpManager.save(flowId, {
+    currentNode: null,
+    nextNode: entryNode,
+    context: serializeContext(context),
+    nodesVisited: []
+  });
+
+  return {
+    initialized: true,
+    flowId,
+    entryNode,
+    task,
+    profile
+  };
+}
+
+/**
+ * step: Advance through auto-resolvable nodes, stop at actionable node.
+ */
+async function cmdStep(args) {
+  const flowPath = args.flow;
+  if (!flowPath) return { error: 'Missing --flow <path>' };
+
+  const flowJson = JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+  const engine = new FlowEngine();
+  engine.loadFlow(flowJson);
+
+  const flowId = flowIdFromPath(flowPath);
+  const cpManager = new CheckpointManager();
+  const checkpoint = cpManager.load(flowId);
+
+  if (!checkpoint) {
+    return { error: 'No checkpoint found. Run init first.' };
+  }
+
+  const protocol = new CallbackProtocol();
+  const context = deserializeContext(checkpoint.context);
+  const nodesVisited = checkpoint.nodesVisited || [];
+  let currentNodeId = checkpoint.nextNode;
+
+  if (currentNodeId === null) {
+    return { finished: true, nodesVisited };
+  }
+
+  const maxSteps = 50;
+  let stepCount = 0;
+
+  while (currentNodeId !== null) {
+    stepCount++;
+    if (stepCount > maxSteps) {
+      return { error: 'Exceeded max auto-resolve steps (50). Possible loop.' };
+    }
+
+    const node = engine.graph.nodes.get(currentNodeId);
+    if (!node) {
+      return { error: `Node "${currentNodeId}" not found in graph` };
+    }
+
+    // Check for deprecated/not-implemented
+    try {
+      checkRuntimeStatus(node);
+    } catch (err) {
+      if (err instanceof DeprecatedNodeError) {
+        // Skip deprecated nodes
+        nodesVisited.push(node.id);
+        currentNodeId = node.next || null;
+        continue;
+      }
+      if (err instanceof NotImplementedError) {
+        return { error: err.message, stoppedAt: node.id };
+      }
+    }
+
+    // If auto-resolvable, execute inline
+    if (isAutoResolvable(node)) {
+      let result;
+
+      switch (node.type) {
+        case 'entry':
+          result = { next: node.next, outputs: {} };
+          break;
+
+        case 'exit': {
+          const resolvedOutputs = node.outputs
+            ? resolveTemplate(node.outputs, context)
+            : {};
+          nodesVisited.push(node.id);
+          context.nodes[node.id] = { outputs: resolvedOutputs };
+
+          cpManager.save(flowId, {
+            currentNode: node.id,
+            nextNode: null,
+            context: serializeContext(context),
+            nodesVisited: [...nodesVisited]
+          });
+
+          return {
+            finished: true,
+            exitNode: node.id,
+            status: node.status || 'completed',
+            nodesVisited
+          };
+        }
+
+        case 'condition': {
+          const conditionStr = typeof node.condition === 'string' && node.condition.startsWith('{{')
+            ? node.condition
+            : `{{${node.condition}}}`;
+          const condResult = resolveTemplate(conditionStr, context);
+          result = { next: condResult ? node.true : node.false, outputs: { conditionResult: !!condResult } };
+          break;
+        }
+
+        case 'router': {
+          const condStr = typeof node.condition === 'string' && node.condition.startsWith('{{')
+            ? node.condition
+            : `{{${node.condition}}}`;
+          const routeKey = String(resolveTemplate(condStr, context));
+          const routes = node.routes || {};
+          let nextNode = routes[routeKey];
+          if (!nextNode && node.default) {
+            nextNode = typeof node.default === 'string' && routes[node.default]
+              ? routes[node.default]
+              : node.default;
+          }
+          result = { next: nextNode || null, outputs: { routeKey } };
+          break;
+        }
+
+        case 'team':
+          // Deprecated team nodes — skip
+          result = { next: node.next || null, outputs: {} };
+          break;
+
+        default:
+          result = { next: node.next || null, outputs: {} };
+      }
+
+      // Store and advance
+      nodesVisited.push(node.id);
+      context.nodes[node.id] = { outputs: result.outputs || {} };
+      currentNodeId = result.next;
+      continue;
+    }
+
+    // Actionable node — build instruction and stop
+    let instruction;
+    const nodeContext = detectNodeContext(node.id);
+
+    switch (node.type) {
+      case 'agent': {
+        const resolvedInputs = node.inputs
+          ? resolveTemplate(node.inputs, context)
+          : {};
+        instruction = protocol.buildAgentInstruction(
+          node.id, node.agent, node.config, resolvedInputs
+        );
+        break;
+      }
+
+      case 'parallel': {
+        const resolvedBranches = (node.branches || []).map(b => ({
+          ...b,
+          inputs: b.inputs ? resolveTemplate(b.inputs, context) : {}
+        }));
+        instruction = protocol.buildParallelInstruction(
+          node.id, resolvedBranches,
+          { nodeContext, taskSlug: context.inputs && context.inputs.task }
+        );
+        break;
+      }
+
+      case 'interrupt': {
+        const resolvedDisplay = node.display
+          ? resolveTemplate(node.display, context)
+          : { title: node.reason || 'Interrupt', options: [] };
+        instruction = protocol.buildInterruptInstruction(
+          node.id, resolvedDisplay, node.routes, node.reason
+        );
+        break;
+      }
+
+      case 'sequence': {
+        instruction = protocol.buildSequenceInstruction(node.id, node.steps);
+        break;
+      }
+
+      default:
+        instruction = { type: node.type, nodeId: node.id };
+    }
+
+    // Save checkpoint at this actionable node
+    cpManager.save(flowId, {
+      currentNode: node.id,
+      nextNode: currentNodeId,
+      context: serializeContext(context),
+      nodesVisited: [...nodesVisited]
+    });
+
+    return {
+      instruction,
+      nodeId: node.id,
+      nodeType: node.type,
+      description: node.description || ''
+    };
+  }
+
+  // Reached end without actionable node
+  return { finished: true, nodesVisited };
+}
+
+/**
+ * complete: Apply result to current node, advance checkpoint.
+ */
+function cmdComplete(args) {
+  const flowPath = args.flow;
+  if (!flowPath) return { error: 'Missing --flow <path>' };
+
+  const resultStr = args.result;
+  if (!resultStr) return { error: 'Missing --result <json>' };
+
+  let result;
+  try {
+    result = JSON.parse(resultStr);
+  } catch {
+    return { error: 'Invalid JSON in --result' };
+  }
+
+  const flowJson = JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+  const engine = new FlowEngine();
+  engine.loadFlow(flowJson);
+
+  const flowId = flowIdFromPath(flowPath);
+  const cpManager = new CheckpointManager();
+  const checkpoint = cpManager.load(flowId);
+
+  if (!checkpoint) {
+    return { error: 'No checkpoint found. Run init first.' };
+  }
+
+  const context = deserializeContext(checkpoint.context);
+  const nodesVisited = checkpoint.nodesVisited || [];
+  const currentNodeId = checkpoint.nextNode || checkpoint.currentNode;
+
+  if (!currentNodeId) {
+    return { error: 'No current node to complete.' };
+  }
+
+  // Guard against double-completion: after cmdStep, nextNode === currentNode.
+  // After cmdComplete, nextNode advances past currentNode. If we see them
+  // differ, this checkpoint was already completed — need a step first.
+  if (checkpoint.nextNode && checkpoint.nextNode !== checkpoint.currentNode) {
+    return { error: `Node "${checkpoint.currentNode}" was already completed. Run step first.` };
+  }
+
+  const node = engine.graph.nodes.get(currentNodeId);
+  if (!node) {
+    return { error: `Node "${currentNodeId}" not found` };
+  }
+
+  // Store result
+  nodesVisited.push(node.id);
+  context.nodes[node.id] = { outputs: result };
+
+  // Determine next node
+  let nextNode = node.next || null;
+
+  // Handle maxIterations for parallel nodes
+  if (node.type === 'parallel' && node.maxIterations) {
+    context._iterations = context._iterations || {};
+    context._iterations[node.id] = (context._iterations[node.id] || 0) + 1;
+    if (context._iterations[node.id] >= node.maxIterations && node.onMaxIterations) {
+      nextNode = node.onMaxIterations;
+    }
+  }
+
+  cpManager.save(flowId, {
+    currentNode: node.id,
+    nextNode,
+    context: serializeContext(context),
+    nodesVisited: [...nodesVisited]
+  });
+
+  return {
+    completed: true,
+    nodeId: node.id,
+    nextNode
+  };
+}
+
+/**
+ * status: Show current state of an active session.
+ */
+function cmdStatus(args) {
+  const flowPath = args.flow;
+  if (!flowPath) return { error: 'Missing --flow <path>' };
+
+  const flowId = flowIdFromPath(flowPath);
+  const cpManager = new CheckpointManager();
+  const checkpoint = cpManager.load(flowId);
+
+  if (!checkpoint) {
+    return { active: false, message: 'No active session.' };
+  }
+
+  return {
+    active: true,
+    flowId: checkpoint.flowId || flowId,
+    currentNode: checkpoint.currentNode,
+    nextNode: checkpoint.nextNode,
+    nodesVisited: checkpoint.nodesVisited || [],
+    visitedCount: (checkpoint.nodesVisited || []).length,
+    createdAt: checkpoint.createdAt || null
+  };
+}
+
+// ---------- Main dispatcher ----------
+
+const COMMANDS = {
+  validate: cmdValidate,
+  'dry-run': cmdDryRun,
+  init: cmdInit,
+  step: cmdStep,
+  complete: cmdComplete,
+  status: cmdStatus
+};
+
+async function main(argv) {
+  const { command, args } = parseArgs(argv || process.argv);
+
+  if (!command || command === 'help') {
+    return {
+      usage: 'elsabro-flow <command> [options]',
+      commands: Object.keys(COMMANDS)
+    };
+  }
+
+  const handler = COMMANDS[command];
+  if (!handler) {
+    return { error: `Unknown command: "${command}". Available: ${Object.keys(COMMANDS).join(', ')}` };
+  }
+
+  return handler(args);
+}
+
+// Run if invoked directly
+if (require.main === module) {
+  main().then(result => {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    if (result.error) process.exitCode = 1;
+  }).catch(err => {
+    process.stdout.write(JSON.stringify({ error: err.message }, null, 2) + '\n');
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { main, parseArgs, flowIdFromPath, isAutoResolvable, detectNodeContext, COMMANDS };

package/flow-engine/src/executors.js

@@ -33,12 +33,24 @@ class ExecutorError extends Error {
   }
 }
 
+class DeprecatedNodeError extends Error {
+  constructor(nodeId, reason) {
+    super(`Node "${nodeId}" is deprecated: ${reason}`);
+    this.name = 'DeprecatedNodeError';
+    this.nodeId = nodeId;
+    this.reason = reason;
+  }
+}
+
 // ---------- Runtime status guard ----------
 
 function checkRuntimeStatus(node) {
   if (node.runtime_status === 'not_implemented') {
     throw new NotImplementedError(node.id, node.gaps);
   }
+  if (node.runtime_status === 'deprecated') {
+    throw new DeprecatedNodeError(node.id, node.deprecated_reason || 'Node is deprecated');
+  }
 }
 
 // ---------- Simple Executors ----------
@@ -402,5 +414,6 @@ module.exports = {
   getExecutor,
   checkRuntimeStatus,
   NotImplementedError,
-  ExecutorError
+  ExecutorError,
+  DeprecatedNodeError
 };

package/flow-engine/src/index.js

@@ -15,7 +15,9 @@ const { buildGraph, validateGraph, getNode, GraphError } = require('./graph');
 const { resolveTemplate, resolveExpression, TemplateError } = require('./template');
 const { runFlow, serializeContext, deserializeContext } = require('./runner');
 const { CheckpointManager } = require('./checkpoint');
-const { NotImplementedError } = require('./executors');
+const { NotImplementedError, DeprecatedNodeError } = require('./executors');
+const { PartyEngine } = require('./party');
+const { CallbackProtocol } = require('./callbacks');
 
 class FlowEngine {
   /**
@@ -134,4 +136,4 @@ class FlowEngine {
   }
 }
 
-module.exports = { FlowEngine, GraphError, TemplateError, NotImplementedError, CheckpointManager };
+module.exports = { FlowEngine, GraphError, TemplateError, NotImplementedError, DeprecatedNodeError, CheckpointManager, PartyEngine, CallbackProtocol };