elsabro 5.2.0 → 6.0.1

package/flow-engine/src/executors.js

@@ -0,0 +1,406 @@
+'use strict';
+
+/**
+ * Node executors for the ELSABRO flow engine.
+ *
+ * Each executor: async execute{Type}(node, context, callbacks)
+ *   → { next: nodeId|null, outputs: {}, status?: string }
+ *
+ * 9 node types total:
+ *   Simple (Wave 2):  entry, exit, condition, router, sequence
+ *   Complex (Wave 3): agent, parallel, interrupt, team
+ */
+
+const { resolveTemplate, resolveExpression } = require('./template');
+
+// ---------- Error types ----------
+
+class NotImplementedError extends Error {
+  constructor(nodeId, gaps) {
+    const gapText = gaps ? gaps.join('; ') : 'No details available';
+    super(`Node "${nodeId}" is not yet implemented. Gaps: ${gapText}`);
+    this.name = 'NotImplementedError';
+    this.nodeId = nodeId;
+    this.gaps = gaps || [];
+  }
+}
+
+class ExecutorError extends Error {
+  constructor(nodeId, message) {
+    super(`Executor error in node "${nodeId}": ${message}`);
+    this.name = 'ExecutorError';
+    this.nodeId = nodeId;
+  }
+}
+
+// ---------- Runtime status guard ----------
+
+function checkRuntimeStatus(node) {
+  if (node.runtime_status === 'not_implemented') {
+    throw new NotImplementedError(node.id, node.gaps);
+  }
+}
+
+// ---------- Simple Executors ----------
+
+/**
+ * Entry node: no-op, just transitions to next.
+ */
+async function executeEntry(node, context, callbacks) {
+  return { next: node.next, outputs: {} };
+}
+
+/**
+ * Exit node: resolve output templates, terminate flow.
+ */
+async function executeExit(node, context, callbacks) {
+  const resolvedOutputs = node.outputs
+    ? resolveTemplate(node.outputs, context)
+    : {};
+
+  return {
+    next: null,
+    outputs: resolvedOutputs,
+    status: node.status || 'completed'
+  };
+}
+
+/**
+ * Condition node: evaluate condition, route to true/false branch.
+ */
+async function executeCondition(node, context, callbacks) {
+  if (!node.condition) {
+    throw new ExecutorError(node.id, 'Condition node has no "condition" field');
+  }
+
+  const conditionStr = typeof node.condition === 'string' && node.condition.startsWith('{{')
+    ? node.condition
+    : `{{${node.condition}}}`;
+
+  const result = resolveTemplate(conditionStr, context);
+
+  const nextNode = result ? node.true : node.false;
+
+  if (!nextNode) {
+    throw new ExecutorError(
+      node.id,
+      `Condition evaluated to ${!!result} but no "${result ? 'true' : 'false'}" branch defined`
+    );
+  }
+
+  return { next: nextNode, outputs: { conditionResult: !!result } };
+}
+
+/**
+ * Router node: evaluate condition as a string, match against routes map.
+ */
+async function executeRouter(node, context, callbacks) {
+  if (!node.condition) {
+    throw new ExecutorError(node.id, 'Router node has no "condition" field');
+  }
+
+  const conditionStr = typeof node.condition === 'string' && node.condition.startsWith('{{')
+    ? node.condition
+    : `{{${node.condition}}}`;
+
+  const routeKey = resolveTemplate(conditionStr, context);
+  const stringKey = String(routeKey);
+
+  const routes = node.routes || {};
+  let nextNode = routes[stringKey];
+
+  if (!nextNode && node.default) {
+    nextNode = typeof node.default === 'string' && routes[node.default]
+      ? routes[node.default]
+      : node.default;
+  }
+
+  if (!nextNode) {
+    throw new ExecutorError(
+      node.id,
+      `Router could not match "${stringKey}" to any route. Available: ${Object.keys(routes).join(', ')}`
+    );
+  }
+
+  return { next: nextNode, outputs: { routeKey: stringKey } };
+}
+
+/**
+ * Sequence node: execute steps sequentially, collect step outputs.
+ */
+async function executeSequence(node, context, callbacks) {
+  const steps = node.steps || [];
+
+  for (const step of steps) {
+    const stepLabel = step.as || step.action || 'unnamed';
+
+    try {
+      let stepOutput = null;
+
+      switch (step.action) {
+        case 'bash': {
+          const command = resolveTemplate(step.command, context);
+          if (callbacks.onBash) {
+            stepOutput = await callbacks.onBash(command);
+          } else {
+            stepOutput = { output: '', exitCode: -1, skipped: true };
+          }
+          break;
+        }
+
+        case 'read_files': {
+          const files = resolveTemplate(step.files, context);
+          if (callbacks.onReadFiles) {
+            stepOutput = await callbacks.onReadFiles(files);
+          } else {
+            stepOutput = { content: '', skipped: true };
+          }
+          break;
+        }
+
+        case 'agent': {
+          const resolvedInputs = step.inputs
+            ? resolveTemplate(step.inputs, context)
+            : {};
+          if (callbacks.onAgent) {
+            stepOutput = await callbacks.onAgent({
+              agent: step.agent,
+              model: step.model,
+              inputs: resolvedInputs,
+              as: stepLabel
+            });
+          } else {
+            stepOutput = { result: null, skipped: true };
+          }
+          break;
+        }
+
+        default: {
+          // Unrecognized step actions (load_memory, inject_state, learn_patterns, etc.)
+          // These are aspirational actions not yet implemented in the engine.
+          stepOutput = { skipped: true, reason: `Action "${step.action}" not implemented in engine` };
+          break;
+        }
+      }
+
+      // Store step output in context
+      if (step.as) {
+        context.steps[step.as] = { output: stepOutput };
+      }
+
+    } catch (err) {
+      if (step.optional) {
+        // Optional steps don't break the flow
+        if (step.as) {
+          context.steps[step.as] = { output: null, error: err.message };
+        }
+        continue;
+      }
+
+      if (node.errorPolicy === 'continue') {
+        if (step.as) {
+          context.steps[step.as] = { output: null, error: err.message };
+        }
+        continue;
+      }
+
+      throw new ExecutorError(node.id, `Step "${stepLabel}" failed: ${err.message}`);
+    }
+  }
+
+  // Resolve output templates
+  const resolvedOutputs = node.outputs
+    ? resolveTemplate(node.outputs, context)
+    : {};
+
+  return { next: node.next, outputs: resolvedOutputs };
+}
+
+// ---------- Complex Executors (Wave 3) ----------
+
+/**
+ * Agent node: invoke an external agent via callback.
+ */
+async function executeAgent(node, context, callbacks) {
+  const resolvedInputs = node.inputs
+    ? resolveTemplate(node.inputs, context)
+    : {};
+
+  let result = null;
+
+  if (callbacks.onAgent) {
+    result = await callbacks.onAgent({
+      id: node.id,
+      agent: node.agent,
+      config: node.config || {},
+      inputs: resolvedInputs
+    });
+  } else {
+    result = { result: null, skipped: true };
+  }
+
+  // Store in context
+  context.nodes[node.id] = context.nodes[node.id] || {};
+  context.nodes[node.id].outputs = { output: result };
+
+  // Resolve output templates (some agent nodes define outputs)
+  const resolvedOutputs = node.outputs
+    ? resolveTemplate(node.outputs, context)
+    : { output: result };
+
+  return { next: node.next, outputs: resolvedOutputs };
+}
+
+/**
+ * Parallel node: execute branches concurrently via callback.
+ */
+async function executeParallel(node, context, callbacks) {
+  const branches = node.branches || [];
+
+  // Resolve inputs for each branch
+  const resolvedBranches = branches.map(branch => ({
+    ...branch,
+    inputs: branch.inputs ? resolveTemplate(branch.inputs, context) : {}
+  }));
+
+  // Agent Teams enforcement: if 2+ branches, notify callback
+  if (resolvedBranches.length >= 2 && callbacks.onTeamRequired) {
+    await callbacks.onTeamRequired({
+      nodeId: node.id,
+      branches: resolvedBranches
+    });
+  }
+
+  // Track iterations for maxIterations support
+  context._iterations = context._iterations || {};
+  context._iterations[node.id] = (context._iterations[node.id] || 0) + 1;
+
+  let branchResults;
+
+  if (callbacks.onParallel) {
+    branchResults = await callbacks.onParallel({
+      nodeId: node.id,
+      branches: resolvedBranches,
+      joinType: node.joinType || 'all',
+      timeout: node.timeout
+    });
+  } else {
+    branchResults = resolvedBranches.map(b => ({ id: b.id, result: null, skipped: true }));
+  }
+
+  // Store branch results
+  const branchOutputs = {};
+  if (Array.isArray(branchResults)) {
+    for (let i = 0; i < branchResults.length; i++) {
+      const branchId = resolvedBranches[i]?.id || `branch_${i}`;
+      branchOutputs[branchId] = branchResults[i];
+    }
+  }
+
+  // Check maxIterations
+  if (node.maxIterations && context._iterations[node.id] >= node.maxIterations) {
+    if (node.onMaxIterations) {
+      return { next: node.onMaxIterations, outputs: { branches: branchOutputs } };
+    }
+  }
+
+  return { next: node.next, outputs: { branches: branchOutputs } };
+}
+
+/**
+ * Interrupt node: pause execution, display info, route on user choice.
+ */
+async function executeInterrupt(node, context, callbacks) {
+  const resolvedDisplay = node.display
+    ? resolveTemplate(node.display, context)
+    : { title: node.reason || 'Interrupt', options: [] };
+
+  let selectedOption = null;
+
+  if (callbacks.onInterrupt) {
+    selectedOption = await callbacks.onInterrupt({
+      nodeId: node.id,
+      display: resolvedDisplay,
+      routes: node.routes || {},
+      reason: node.reason
+    });
+  } else {
+    // Default: pick first option if available
+    const options = resolvedDisplay.options || [];
+    selectedOption = options.length > 0 ? options[0].id : null;
+  }
+
+  const routes = node.routes || {};
+  const nextNode = selectedOption ? routes[selectedOption] : null;
+
+  if (!nextNode) {
+    throw new ExecutorError(
+      node.id,
+      `Interrupt: user selected "${selectedOption}" but no matching route found. Available: ${Object.keys(routes).join(', ')}`
+    );
+  }
+
+  return { next: nextNode, outputs: { selection: selectedOption } };
+}
+
+/**
+ * Team node: deprecated, throws NotImplementedError.
+ */
+async function executeTeam(node, context, callbacks) {
+  // Team nodes are deprecated in ELSABRO v5.3+
+  // Agent Teams are now handled inline via IMPERATIVO_AGENT_TEAMS in execute.md
+  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) {
+    const result = await callbacks.onTeam(node);
+    return { next: node.next, outputs: result || {} };
+  }
+
+  return { next: node.next, outputs: {} };
+}
+
+// ---------- Executor registry ----------
+
+const executors = {
+  entry: executeEntry,
+  exit: executeExit,
+  condition: executeCondition,
+  router: executeRouter,
+  sequence: executeSequence,
+  agent: executeAgent,
+  parallel: executeParallel,
+  interrupt: executeInterrupt,
+  team: executeTeam
+};
+
+/**
+ * Get the executor function for a node type.
+ * @param {string} type
+ * @returns {function}
+ */
+function getExecutor(type) {
+  const executor = executors[type];
+  if (!executor) {
+    throw new ExecutorError('unknown', `No executor for node type "${type}"`);
+  }
+  return executor;
+}
+
+module.exports = {
+  executeEntry,
+  executeExit,
+  executeCondition,
+  executeRouter,
+  executeSequence,
+  executeAgent,
+  executeParallel,
+  executeInterrupt,
+  executeTeam,
+  getExecutor,
+  checkRuntimeStatus,
+  NotImplementedError,
+  ExecutorError
+};

package/flow-engine/src/graph.js

@@ -0,0 +1,129 @@
+'use strict';
+
+/**
+ * Graph builder and node lookup for ELSABRO flow definitions.
+ *
+ * Takes a raw flow JSON object (with a "nodes" array) and produces
+ * a Map-based graph that the engine traverses at runtime.
+ */
+
+class GraphError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'GraphError';
+  }
+}
+
+/**
+ * Build an in-memory graph from a flow definition.
+ *
+ * @param {object} flowDefinition – parsed development-flow.json
+ * @returns {{ nodes: Map<string, object>, entryNode: string, meta: object }}
+ */
+function buildGraph(flowDefinition) {
+  if (!flowDefinition || !Array.isArray(flowDefinition.nodes)) {
+    throw new GraphError('Flow definition must have a "nodes" array');
+  }
+
+  const nodes = new Map();
+  let entryNode = null;
+
+  for (const node of flowDefinition.nodes) {
+    if (!node.id) {
+      throw new GraphError('Every node must have an "id" field');
+    }
+    if (nodes.has(node.id)) {
+      throw new GraphError(`Duplicate node id: "${node.id}"`);
+    }
+    nodes.set(node.id, node);
+
+    if (node.type === 'entry') {
+      if (entryNode !== null) {
+        throw new GraphError(`Multiple entry nodes found: "${entryNode}" and "${node.id}"`);
+      }
+      entryNode = node.id;
+    }
+  }
+
+  if (entryNode === null) {
+    throw new GraphError('No entry node (type "entry") found in flow');
+  }
+
+  const meta = {
+    id: flowDefinition.id || 'unknown',
+    name: flowDefinition.name || '',
+    version: flowDefinition.version || '0.0.0',
+    config: flowDefinition.config || {},
+    inputs: flowDefinition.inputs || {},
+    outputs: flowDefinition.outputs || {},
+    sync_metadata: flowDefinition.sync_metadata || null
+  };
+
+  return { nodes, entryNode, meta };
+}
+
+/**
+ * Validate that all node references (next, routes, true, false, onMaxIterations,
+ * onError) point to existing nodes.
+ *
+ * @param {{ nodes: Map<string, object> }} graph
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateGraph(graph) {
+  const errors = [];
+  const nodeIds = new Set(graph.nodes.keys());
+
+  for (const [id, node] of graph.nodes) {
+    const refs = getNextNodes(node);
+    for (const ref of refs) {
+      if (!nodeIds.has(ref)) {
+        errors.push(`Node "${id}" references non-existent node "${ref}"`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Get a node by ID, or throw if not found.
+ *
+ * @param {{ nodes: Map<string, object> }} graph
+ * @param {string} id
+ * @returns {object}
+ */
+function getNode(graph, id) {
+  const node = graph.nodes.get(id);
+  if (!node) {
+    throw new GraphError(`Node "${id}" not found in graph`);
+  }
+  return node;
+}
+
+/**
+ * Collect all possible next-node IDs from a node (for validation purposes).
+ * This covers: next, routes, true, false, onMaxIterations, onError.
+ *
+ * @param {object} node
+ * @returns {string[]}
+ */
+function getNextNodes(node) {
+  const refs = [];
+
+  if (node.next) refs.push(node.next);
+  if (node.true) refs.push(node.true);
+  if (node.false) refs.push(node.false);
+  if (node.onMaxIterations) refs.push(node.onMaxIterations);
+  if (node.onError) refs.push(node.onError);
+
+  if (node.routes && typeof node.routes === 'object') {
+    for (const target of Object.values(node.routes)) {
+      if (typeof target === 'string') refs.push(target);
+    }
+  }
+
+  // Deduplicate
+  return [...new Set(refs)];
+}
+
+module.exports = { buildGraph, validateGraph, getNode, getNextNodes, GraphError };

package/flow-engine/src/index.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * FlowEngine — main entry point for the ELSABRO flow engine runtime.
+ *
+ * Usage:
+ *   const { FlowEngine } = require('./flow-engine/src/index.js');
+ *   const flow = require('./flows/development-flow.json');
+ *   const engine = new FlowEngine({ callbacks: { onAgent, onBash, ... } });
+ *   engine.loadFlow(flow);
+ *   const result = await engine.run({ task: '...', profile: 'default' }, callbacks);
+ */
+
+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');
+
+class FlowEngine {
+  /**
+   * @param {object} options
+   * @param {object} [options.callbacks] – default callbacks for all operations
+   * @param {object} [options.config] – engine-level config overrides
+   */
+  constructor(options = {}) {
+    this.callbacks = options.callbacks || {};
+    this.config = options.config || {};
+    this.graph = null;
+    this._flowDefinition = null;
+  }
+
+  /**
+   * Load and validate a flow definition (e.g. development-flow.json).
+   *
+   * @param {object} flowJson – parsed flow JSON
+   * @returns {this}
+   */
+  loadFlow(flowJson) {
+    this._flowDefinition = flowJson;
+    this.graph = buildGraph(flowJson);
+
+    const validation = validateGraph(this.graph);
+    if (!validation.valid) {
+      throw new GraphError(
+        `Flow graph has ${validation.errors.length} reference error(s):\n` +
+        validation.errors.join('\n')
+      );
+    }
+
+    return this;
+  }
+
+  /**
+   * Get a node by ID.
+   * @param {string} id
+   * @returns {object}
+   */
+  getNode(id) {
+    if (!this.graph) {
+      throw new GraphError('No flow loaded. Call loadFlow() first.');
+    }
+    return getNode(this.graph, id);
+  }
+
+  /**
+   * Get flow-level metadata (version, config, sync_metadata).
+   * @returns {object}
+   */
+  getFlowMetadata() {
+    if (!this.graph) {
+      throw new GraphError('No flow loaded. Call loadFlow() first.');
+    }
+    return this.graph.meta;
+  }
+
+  /**
+   * Get total node count.
+   * @returns {number}
+   */
+  getNodeCount() {
+    if (!this.graph) return 0;
+    return this.graph.nodes.size;
+  }
+
+  /**
+   * Get nodes filtered by a predicate.
+   * @param {function} predicate – (node) => boolean
+   * @returns {object[]}
+   */
+  getNodesWhere(predicate) {
+    if (!this.graph) return [];
+    const results = [];
+    for (const node of this.graph.nodes.values()) {
+      if (predicate(node)) results.push(node);
+    }
+    return results;
+  }
+
+  /**
+   * Resolve a template expression against a context.
+   * Convenience method wrapping template.js.
+   *
+   * @param {*} template
+   * @param {object} context
+   * @returns {*}
+   */
+  resolveTemplate(template, context) {
+    return resolveTemplate(template, context);
+  }
+
+  /**
+   * Run the loaded flow from the entry node.
+   *
+   * @param {object} inputs – flow inputs (task, profile, complexity, etc.)
+   * @param {object} [callbacks] – override callbacks for this run
+   * @returns {Promise<{ success: boolean, outputs: object, context: object, nodesVisited: string[] }>}
+   */
+  async run(inputs, callbacks) {
+    const mergedCallbacks = { ...this.callbacks, ...callbacks };
+    return runFlow(this, inputs, mergedCallbacks);
+  }
+
+  /**
+   * Resume a flow from a checkpoint.
+   *
+   * @param {object} checkpoint – checkpoint data with { nextNode, context, nodesVisited }
+   * @param {object} [callbacks] – override callbacks for this run
+   * @returns {Promise<{ success: boolean, outputs: object, context: object, nodesVisited: string[] }>}
+   */
+  async resume(checkpoint, callbacks) {
+    const mergedCallbacks = { ...this.callbacks, ...callbacks };
+    return runFlow(this, null, mergedCallbacks, checkpoint);
+  }
+}
+
+module.exports = { FlowEngine, GraphError, TemplateError, NotImplementedError, CheckpointManager };