elsabro 6.0.0 → 7.0.0

package/flow-engine/src/callbacks.js

@@ -0,0 +1,268 @@
+'use strict';
+
+/**
+ * CallbackProtocol — Agent Teams decision logic + team composition.
+ *
+ * Encodes the rules for when to use Agent Teams vs regular subagents,
+ * and how to compose teams (minimum 5 members, context-aware padding).
+ * Does NOT manage team lifecycle — Claude Code handles that automatically.
+ */
+
+// ---------- Support agent roster for padding ----------
+
+const SUPPORT_AGENTS = [
+  { id: 'verifier', agent: 'elsabro-verifier', role: 'Quality verification' },
+  { id: 'qa', agent: 'elsabro-qa', role: 'Test writing & QA' },
+  { id: 'analyst', agent: 'elsabro-analyst', role: 'Requirements analysis' },
+  { id: 'debugger', agent: 'elsabro-debugger', role: 'Bug investigation' },
+  { id: 'orchestrator', agent: 'elsabro-orchestrator', role: 'Team coordination' },
+  { id: 'planner', agent: 'elsabro-planner', role: 'Implementation planning' }
+];
+
+// Context-specific padding priority (index into SUPPORT_AGENTS by id)
+const PADDING_ORDER = {
+  implementation: ['verifier', 'analyst', 'debugger', 'qa', 'orchestrator'],
+  review:         ['verifier', 'qa', 'analyst', 'debugger', 'orchestrator'],
+  fix:            ['verifier', 'qa', 'analyst', 'orchestrator', 'planner'],
+  default:        ['verifier', 'qa', 'analyst', 'debugger', 'orchestrator']
+};
+
+class CallbackProtocol {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.teamNamePrefix='elsabro'] – prefix for generated team names
+   * @param {number} [options.minTeammates=5] – minimum team members
+   * @param {object[]} [options.supportAgents] – override support agent roster
+   */
+  constructor(options = {}) {
+    this.teamNamePrefix = options.teamNamePrefix || 'elsabro';
+    this.minTeammates = options.minTeammates || 5;
+    this.supportAgents = options.supportAgents || SUPPORT_AGENTS;
+
+    this._activeTeam = null;
+    this._teamMembers = [];
+    this._log = [];
+  }
+
+  /**
+   * Determine if branches require an Agent Team.
+   * Rules: 2+ branches AND not all-haiku.
+   *
+   * @param {object[]} branches – array of branch definitions
+   * @returns {boolean}
+   */
+  requiresTeam(branches) {
+    if (!Array.isArray(branches) || branches.length < 2) return false;
+
+    const allHaiku = branches.every(b =>
+      b.config && b.config.model === 'haiku'
+    );
+
+    return !allHaiku;
+  }
+
+  /**
+   * Generate a team name from nodeId and optional task slug.
+   * Convention: {prefix}-{slug}, max 38 chars.
+   *
+   * @param {string} nodeId
+   * @param {string} [taskSlug]
+   * @returns {string}
+   */
+  generateTeamName(nodeId, taskSlug) {
+    const slug = taskSlug
+      ? `${nodeId}-${taskSlug}`
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+      : nodeId.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
+
+    const name = `${this.teamNamePrefix}-${slug}`;
+    return name.slice(0, 38);
+  }
+
+  /**
+   * Compose a team from branch agents + padding to minimum.
+   *
+   * @param {object[]} branches – branch definitions with id, agent, config, description
+   * @param {string} [nodeContext='default'] – one of: implementation, review, fix, default
+   * @returns {{ name: string, agent: string, role: string, model: string }[]}
+   */
+  composeTeam(branches, nodeContext = 'default') {
+    // 1. Start with branch agents
+    const members = branches.map((b, i) => ({
+      name: `${b.id}-${i + 1}`,
+      agent: b.agent,
+      role: b.description || `Branch: ${b.id}`,
+      model: (b.config && b.config.model) || 'opus'
+    }));
+
+    // 2. Determine padding agents based on context
+    const existingAgents = new Set(members.map(m => m.agent));
+    const paddingPool = this._getPaddingPool(nodeContext, existingAgents);
+
+    // 3. Pad to minimum
+    let idx = members.length;
+    while (members.length < this.minTeammates && paddingPool.length > 0) {
+      const support = paddingPool.shift();
+      idx++;
+      members.push({
+        name: `${support.id}-${idx}`,
+        agent: support.agent,
+        role: support.role,
+        model: 'opus'
+      });
+    }
+
+    return members;
+  }
+
+  /**
+   * Build instruction for a parallel node.
+   *
+   * @param {string} nodeId
+   * @param {object[]} branches
+   * @param {object} [context={}] – { nodeContext, taskSlug }
+   * @returns {object}
+   */
+  buildParallelInstruction(nodeId, branches, context = {}) {
+    const useAgentTeams = this.requiresTeam(branches);
+
+    const instruction = {
+      type: 'parallel',
+      nodeId,
+      useAgentTeams,
+      branches: branches.map(b => ({
+        id: b.id,
+        agent: b.agent,
+        inputs: b.inputs || {}
+      }))
+    };
+
+    if (useAgentTeams) {
+      const members = this.composeTeam(branches, context.nodeContext || 'default');
+      const teamName = this.generateTeamName(nodeId, context.taskSlug);
+
+      instruction.team = {
+        name: teamName,
+        description: `Agent team for ${nodeId}`,
+        members
+      };
+
+      this._activeTeam = teamName;
+      this._teamMembers = members;
+      this._log.push({
+        action: 'team_parallel',
+        nodeId,
+        teamName,
+        memberCount: members.length
+      });
+    } else {
+      this._log.push({
+        action: 'subagent_parallel',
+        nodeId,
+        branchCount: branches.length
+      });
+    }
+
+    return instruction;
+  }
+
+  /**
+   * Build instruction for an agent node.
+   */
+  buildAgentInstruction(nodeId, agent, config, inputs) {
+    this._log.push({ action: 'agent', nodeId, agent });
+    return {
+      type: 'agent',
+      nodeId,
+      agent,
+      model: (config && config.model) || 'opus',
+      inputs: inputs || {}
+    };
+  }
+
+  /**
+   * Build instruction for an interrupt node.
+   */
+  buildInterruptInstruction(nodeId, display, routes, reason) {
+    this._log.push({ action: 'interrupt', nodeId });
+    return {
+      type: 'interrupt',
+      nodeId,
+      display,
+      routes: routes || {},
+      reason: reason || ''
+    };
+  }
+
+  /**
+   * Build instruction for a bash command.
+   */
+  buildBashInstruction(command) {
+    return { type: 'bash', command };
+  }
+
+  /**
+   * Build instruction for reading files.
+   */
+  buildReadFilesInstruction(files) {
+    return { type: 'read_files', files };
+  }
+
+  /**
+   * Build instruction for a sequence node.
+   */
+  buildSequenceInstruction(nodeId, steps) {
+    this._log.push({ action: 'sequence', nodeId, stepCount: (steps || []).length });
+    return {
+      type: 'sequence',
+      nodeId,
+      steps: steps || []
+    };
+  }
+
+  /** @returns {boolean} */
+  hasActiveTeam() {
+    return this._activeTeam !== null;
+  }
+
+  /** @returns {string|null} */
+  getActiveTeam() {
+    return this._activeTeam;
+  }
+
+  /** @returns {object[]} */
+  getTeamMembers() {
+    return [...this._teamMembers];
+  }
+
+  /** @returns {object[]} */
+  getLog() {
+    return [...this._log];
+  }
+
+  /** Clear active team state (call after team completes). */
+  clearActiveTeam() {
+    this._activeTeam = null;
+    this._teamMembers = [];
+  }
+
+  // ---------- Internal ----------
+
+  /**
+   * Get ordered list of support agents for padding, excluding those already in the team.
+   * @private
+   */
+  _getPaddingPool(nodeContext, existingAgents) {
+    const order = PADDING_ORDER[nodeContext] || PADDING_ORDER.default;
+    const supportMap = new Map(this.supportAgents.map(s => [s.id, s]));
+
+    return order
+      .map(id => supportMap.get(id))
+      .filter(s => s && !existingAgents.has(s.agent));
+  }
+}
+
+module.exports = { CallbackProtocol, SUPPORT_AGENTS, PADDING_ORDER };