elsabro 6.0.0 → 7.0.0

package/flow-engine/src/party.js

@@ -0,0 +1,414 @@
+'use strict';
+
+/**
+ * PartyEngine — Multi-agent collaborative discussion engine.
+ *
+ * Selects relevant agents based on topic keywords, runs round-based
+ * discussions with callbacks, and produces synthesis summaries.
+ * Reuses CheckpointManager for session persistence.
+ *
+ * Zero external dependencies. CommonJS, Node 18+.
+ */
+
+const path = require('path');
+const { CheckpointManager } = require('./checkpoint');
+
+// ── Agent Personality Cards ──────────────────────────────────────────────────
+
+const CARDS = require('./agent-cards.json');
+
+// ── Relevance Map ────────────────────────────────────────────────────────────
+// Maps keywords to agent scores. Each bucket awards points to 1-3 agents.
+// Higher score = more relevant to the topic.
+
+const RELEVANCE_MAP = {
+  architecture:   { planner: 3, executor: 2, debugger: 1 },
+  testing:        { qa: 3, executor: 2, verifier: 1 },
+  design:         { 'ux-designer': 3, planner: 2, analyst: 1 },
+  ux:             { 'ux-designer': 3, analyst: 2, 'tech-writer': 1 },
+  ui:             { 'ux-designer': 3, executor: 2, analyst: 1 },
+  bug:            { debugger: 3, qa: 2, executor: 1 },
+  debug:          { debugger: 3, qa: 2, verifier: 1 },
+  performance:    { debugger: 3, executor: 2, qa: 1 },
+  documentation:  { 'tech-writer': 3, planner: 2, analyst: 1 },
+  docs:           { 'tech-writer': 3, 'ux-designer': 1, planner: 1 },
+  planning:       { planner: 3, 'scrum-master': 2, analyst: 1 },
+  sprint:         { 'scrum-master': 3, planner: 2, qa: 1 },
+  scope:          { analyst: 3, 'scrum-master': 2, planner: 1 },
+  requirements:   { analyst: 3, planner: 2, 'ux-designer': 1 },
+  deploy:         { executor: 3, qa: 2, verifier: 1 },
+  refactor:       { executor: 3, debugger: 2, verifier: 1 },
+  security:       { verifier: 3, debugger: 2, qa: 1 },
+  quality:        { verifier: 3, qa: 2, 'tech-writer': 1 }
+};
+
+// Default scores when no keywords match — ensures every agent is reachable.
+const DEFAULT_SCORES = {
+  analyst: 2, planner: 2, executor: 1,
+  qa: 1, debugger: 1, 'ux-designer': 1,
+  'scrum-master': 1, 'tech-writer': 1, verifier: 1
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Slugify a topic string for use as a checkpoint flowId component.
+ * @param {string} text
+ * @returns {string}
+ */
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+}
+
+/**
+ * Detect agent names mentioned directly in topic text.
+ * Returns array of matching agent IDs.
+ * @param {string} topic
+ * @returns {string[]}
+ */
+function detectAgentNames(topic) {
+  const lower = topic.toLowerCase();
+  const found = [];
+  for (const card of Object.values(CARDS)) {
+    if (lower.includes(card.name.toLowerCase())) {
+      found.push(card.id);
+    }
+  }
+  return found;
+}
+
+// ── PartyEngine ──────────────────────────────────────────────────────────────
+
+class PartyEngine {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.checkpointDir] – checkpoint directory
+   * @param {number} [options.maxRounds] – max discussion rounds (default: 3)
+   * @param {number} [options.maxAgents] – max agents per party (default: 3)
+   */
+  constructor(options = {}) {
+    this.maxRounds = options.maxRounds || 3;
+    this.maxAgents = options.maxAgents || 3;
+    this.cards = { ...CARDS };
+    this.checkpoint = new CheckpointManager({
+      dir: options.checkpointDir
+    });
+  }
+
+  /**
+   * Select the most relevant agents for a topic.
+   *
+   * Algorithm:
+   * 1. Tokenize topic (lowercase, split on whitespace)
+   * 2. Match tokens against RELEVANCE_MAP keys
+   * 3. Accumulate scores (each keyword scores once per agent)
+   * 4. Break ties by first matching keyword position
+   * 5. Respect manual overrides (options.agents)
+   * 6. Detect agent names in topic → force inclusion
+   *
+   * @param {string} topic
+   * @param {object} [options]
+   * @param {string[]} [options.agents] – manual agent IDs (bypass scoring)
+   * @param {number} [options.maxAgents] – override instance maxAgents
+   * @returns {object[]} array of agent card objects
+   */
+  selectAgents(topic, options = {}) {
+    const max = options.maxAgents || this.maxAgents;
+
+    // Manual override: bypass scoring entirely
+    if (options.agents && options.agents.length > 0) {
+      return options.agents
+        .map(id => this.cards[id])
+        .filter(Boolean)
+        .slice(0, max);
+    }
+
+    // Detect agent names mentioned in topic
+    const forced = detectAgentNames(topic || '');
+
+    // Tokenize
+    const tokens = (topic || '').toLowerCase().split(/\s+/).filter(Boolean);
+
+    // Score accumulation
+    const scores = {};
+    const firstMatch = {}; // track first keyword position for tie-breaking
+
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i];
+      const bucket = RELEVANCE_MAP[token];
+      if (!bucket) continue;
+
+      for (const [agentId, score] of Object.entries(bucket)) {
+        // Each keyword scores once per agent (no duplicates from repeated tokens)
+        const key = `${agentId}:${token}`;
+        if (!scores[`_seen_${key}`]) {
+          scores[`_seen_${key}`] = true;
+          scores[agentId] = (scores[agentId] || 0) + score;
+          if (firstMatch[agentId] === undefined) {
+            firstMatch[agentId] = i;
+          }
+        }
+      }
+    }
+
+    // If no keywords matched, use defaults
+    const hasMatches = Object.keys(scores).some(k => !k.startsWith('_seen_'));
+    if (!hasMatches) {
+      for (const [id, score] of Object.entries(DEFAULT_SCORES)) {
+        scores[id] = score;
+        firstMatch[id] = 999;
+      }
+    }
+
+    // Build sorted agent list
+    const agentIds = Object.keys(this.cards);
+    const ranked = agentIds
+      .filter(id => scores[id] > 0)
+      .sort((a, b) => {
+        // Primary: higher score first
+        const scoreDiff = (scores[b] || 0) - (scores[a] || 0);
+        if (scoreDiff !== 0) return scoreDiff;
+        // Tiebreak: earlier first-match position
+        return (firstMatch[a] || 999) - (firstMatch[b] || 999);
+      });
+
+    // Merge forced agents (from name detection) with scored ranking
+    const result = [];
+    const added = new Set();
+
+    // Forced agents first
+    for (const id of forced) {
+      if (this.cards[id] && !added.has(id)) {
+        result.push(this.cards[id]);
+        added.add(id);
+      }
+    }
+
+    // Fill remaining from ranked
+    for (const id of ranked) {
+      if (added.has(id)) continue;
+      if (result.length >= max) break;
+      result.push(this.cards[id]);
+      added.add(id);
+    }
+
+    return result.slice(0, max);
+  }
+
+  /**
+   * Run a full party discussion session.
+   *
+   * @param {string} topic – discussion topic
+   * @param {object} [options] – { agents, maxRounds, maxAgents, projectContext }
+   * @param {object} callbacks
+   * @param {function} callbacks.onAgentTurn – (params) => string response
+   * @param {function} [callbacks.onSynthesize] – (params) => { consensus, debates, actionItems, keyInsights, suggestedNext }
+   * @param {function} [callbacks.onRoundComplete] – (params) => "continue"|"stop"|"add_round"
+   * @param {function} [callbacks.onFormatSummary] – (template, data) => string
+   * @returns {Promise<object>} { topic, agents, rounds, history, synthesis, sessionId }
+   */
+  async run(topic, options = {}, callbacks = {}) {
+    if (!callbacks.onAgentTurn) {
+      throw new Error('PartyEngine.run() requires callbacks.onAgentTurn');
+    }
+
+    const agents = this.selectAgents(topic, options);
+    let totalRounds = options.maxRounds || this.maxRounds;
+    const sessionId = `party-${slugify(topic)}-${Date.now()}`;
+    const history = [];
+
+    for (let round = 1; round <= totalRounds; round++) {
+      const roundResponses = [];
+
+      for (const agent of agents) {
+        const instruction = round === 1
+          ? 'Share your initial perspective on this topic.'
+          : 'React to previous perspectives and refine your position.';
+
+        const response = await callbacks.onAgentTurn({
+          agent,
+          topic,
+          round,
+          totalRounds,
+          history: [...history],
+          instruction,
+          projectContext: options.projectContext || null
+        });
+
+        const entry = {
+          round,
+          agent: { id: agent.id, name: agent.name },
+          response: response || '',
+          timestamp: new Date().toISOString()
+        };
+
+        history.push(entry);
+        roundResponses.push(entry);
+      }
+
+      // Checkpoint after each round
+      this.checkpoint.save(sessionId, {
+        topic,
+        agents: agents.map(a => a.id),
+        currentRound: round,
+        totalRounds,
+        history,
+        options
+      });
+
+      // Round complete callback
+      if (callbacks.onRoundComplete) {
+        const decision = await callbacks.onRoundComplete({
+          completedRound: round,
+          totalRounds,
+          lastResponses: roundResponses
+        });
+
+        if (decision === 'stop') break;
+        if (decision === 'add_round') totalRounds++;
+      }
+    }
+
+    // Synthesis
+    let synthesis = null;
+    if (callbacks.onSynthesize) {
+      synthesis = await callbacks.onSynthesize({
+        history,
+        topic,
+        agents
+      });
+    } else {
+      synthesis = { consensus: [], debates: [], actionItems: [], keyInsights: [], suggestedNext: null };
+    }
+
+    // Clean old checkpoints (keep last 2)
+    this.checkpoint.clean(sessionId, 2);
+
+    return {
+      topic,
+      agents: agents.map(a => ({ id: a.id, name: a.name })),
+      rounds: history.length > 0 ? history[history.length - 1].round : 0,
+      history,
+      synthesis,
+      sessionId
+    };
+  }
+
+  /**
+   * Resume a party session from checkpoint.
+   *
+   * @param {string} sessionId – checkpoint session ID
+   * @param {object} callbacks – same as run()
+   * @returns {Promise<object>} same as run()
+   */
+  async resume(sessionId, callbacks = {}) {
+    if (!callbacks.onAgentTurn) {
+      throw new Error('PartyEngine.resume() requires callbacks.onAgentTurn');
+    }
+
+    const checkpoint = this.checkpoint.load(sessionId);
+    if (!checkpoint) {
+      throw new Error(`No checkpoint found for session: ${sessionId}`);
+    }
+
+    const { topic, agents: agentIds, currentRound, totalRounds, history, options } = checkpoint;
+    const agents = agentIds.map(id => this.cards[id]).filter(Boolean);
+    let rounds = totalRounds;
+    const startRound = currentRound + 1;
+
+    for (let round = startRound; round <= rounds; round++) {
+      const roundResponses = [];
+
+      for (const agent of agents) {
+        const instruction = round === 1
+          ? 'Share your initial perspective on this topic.'
+          : 'React to previous perspectives and refine your position.';
+
+        const response = await callbacks.onAgentTurn({
+          agent,
+          topic,
+          round,
+          totalRounds: rounds,
+          history: [...history],
+          instruction,
+          projectContext: (options && options.projectContext) || null
+        });
+
+        const entry = {
+          round,
+          agent: { id: agent.id, name: agent.name },
+          response: response || '',
+          timestamp: new Date().toISOString()
+        };
+
+        history.push(entry);
+        roundResponses.push(entry);
+      }
+
+      this.checkpoint.save(sessionId, {
+        topic,
+        agents: agentIds,
+        currentRound: round,
+        totalRounds: rounds,
+        history,
+        options
+      });
+
+      if (callbacks.onRoundComplete) {
+        const decision = await callbacks.onRoundComplete({
+          completedRound: round,
+          totalRounds: rounds,
+          lastResponses: roundResponses
+        });
+
+        if (decision === 'stop') break;
+        if (decision === 'add_round') rounds++;
+      }
+    }
+
+    let synthesis = null;
+    if (callbacks.onSynthesize) {
+      synthesis = await callbacks.onSynthesize({
+        history,
+        topic,
+        agents
+      });
+    } else {
+      synthesis = { consensus: [], debates: [], actionItems: [], keyInsights: [], suggestedNext: null };
+    }
+
+    this.checkpoint.clean(sessionId, 2);
+
+    return {
+      topic,
+      agents: agents.map(a => ({ id: a.id, name: a.name })),
+      rounds: history.length > 0 ? history[history.length - 1].round : 0,
+      history,
+      synthesis,
+      sessionId
+    };
+  }
+
+  /**
+   * Get all loaded personality cards.
+   * @returns {object} map of agentId → card
+   */
+  getCards() {
+    return { ...this.cards };
+  }
+
+  /**
+   * Get a single personality card by agent ID.
+   * @param {string} agentId
+   * @returns {object|undefined}
+   */
+  getCard(agentId) {
+    return this.cards[agentId];
+  }
+}
+
+module.exports = { PartyEngine, RELEVANCE_MAP, slugify, detectAgentNames };

package/flow-engine/src/runner.js

@@ -8,7 +8,7 @@
  * not_implemented nodes gracefully.
  */
 
-const { getExecutor, checkRuntimeStatus, NotImplementedError } = require('./executors');
+const { getExecutor, checkRuntimeStatus, NotImplementedError, DeprecatedNodeError } = require('./executors');
 
 class RunnerError extends Error {
   constructor(message, nodeId) {
@@ -81,8 +81,8 @@ async function runFlow(engine, inputs, callbacks, checkpoint) {
       checkRuntimeStatus(node);
       result = await executor(node, context, callbacks);
     } catch (err) {
-      // Let NotImplementedError propagate cleanly
-      if (err instanceof NotImplementedError) {
+      // Let NotImplementedError and DeprecatedNodeError propagate cleanly
+      if (err instanceof NotImplementedError || err instanceof DeprecatedNodeError) {
         // Save a checkpoint before stopping
         if (callbacks.onCheckpoint) {
           await callbacks.onCheckpoint({
@@ -121,9 +121,9 @@ async function runFlow(engine, inputs, callbacks, checkpoint) {
       });
     }
 
-    // 6. Notify: node completed
+    // 6. Notify: node completed (context passed for post-processing, e.g. dry-run fixups)
     if (callbacks.onNodeComplete) {
-      await callbacks.onNodeComplete(node.id, result);
+      await callbacks.onNodeComplete(node.id, result, context);
     }
 
     // 7. Advance