@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/party-session.js

@@ -0,0 +1,311 @@
+/**
+ * Party Session -- Multi-agent collaboration sessions
+ *
+ * Agents interact in rounds around a topic until convergence or max rounds.
+ * Each round, all agents receive the topic plus previous contributions
+ * and produce their response via SubagentDispatcher.
+ *
+ * @module core/execution/party-session
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const { EventEmitter } = require("events");
+const crypto = require("crypto");
+const { SubagentDispatcher } = require("./subagent-dispatcher");
+const { GuardrailEngine } = require("./guardrail-engine");
+
+const PartyStatus = {
+  PENDING: "pending",
+  ACTIVE: "active",
+  CONVERGED: "converged",
+  CONCLUDED: "concluded",
+};
+
+class PartySession extends EventEmitter {
+  /**
+   * @param {Object} config
+   * @param {string} config.topic - Discussion topic
+   * @param {string[]} config.agents - Agent IDs to participate
+   * @param {number} [config.maxRounds=3] - Maximum rounds
+   * @param {string} [config.projectRoot] - Project root path
+   * @param {number} [config.timeout=300000] - Per-agent timeout
+   */
+  constructor(config = {}) {
+    super();
+    this.sessionId = `party-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
+    this.topic = config.topic || "";
+    this.agents = config.agents || [];
+    this.maxRounds = config.maxRounds || 3;
+    this.projectRoot = config.projectRoot || process.cwd();
+
+    this.dispatcher = new SubagentDispatcher({
+      rootPath: this.projectRoot,
+      defaultTimeout: config.timeout || 300000,
+      guardrailEngine:
+        config.guardrailEngine ||
+        new GuardrailEngine({ projectRoot: this.projectRoot }),
+    });
+
+    this.status = PartyStatus.PENDING;
+    this.rounds = [];
+    this.currentRound = 0;
+    this._startTime = null;
+  }
+
+  /**
+   * Start the party session.
+   *
+   * @returns {string} Session ID
+   */
+  start() {
+    this.status = PartyStatus.ACTIVE;
+    this._startTime = Date.now();
+    this.emit("party-start", {
+      sessionId: this.sessionId,
+      topic: this.topic,
+      agents: this.agents,
+    });
+    return this.sessionId;
+  }
+
+  /**
+   * Execute one round of contributions from all agents.
+   *
+   * @returns {Promise<Object>} Round result with contributions per agent
+   */
+  async runRound() {
+    if (this.status !== PartyStatus.ACTIVE) {
+      return { error: "Party is not active" };
+    }
+
+    this.currentRound++;
+    if (this.currentRound > this.maxRounds) {
+      return { error: "Max rounds reached" };
+    }
+
+    this.emit("round-start", {
+      round: this.currentRound,
+      sessionId: this.sessionId,
+    });
+
+    const previousContext = this._buildPreviousContext();
+    const contributions = [];
+
+    // Dispatch to all agents in parallel
+    const assignments = this.agents.map((agentId) => ({
+      agentId,
+      task: {
+        id: `${this.sessionId}-r${this.currentRound}-${agentId}`,
+        description: this._buildAgentPrompt(agentId, previousContext),
+      },
+    }));
+
+    const results = await this.dispatcher.dispatchParallel(assignments);
+
+    for (let i = 0; i < this.agents.length; i++) {
+      contributions.push({
+        agentId: this.agents[i],
+        output: results[i].success
+          ? results[i].output
+          : `[Error: ${results[i].error}]`,
+        success: results[i].success,
+      });
+    }
+
+    const round = {
+      number: this.currentRound,
+      contributions,
+      timestamp: Date.now(),
+    };
+    this.rounds.push(round);
+
+    // Check for convergence
+    if (this._detectConvergence(contributions)) {
+      this.status = PartyStatus.CONVERGED;
+      this.emit("convergence", { round: this.currentRound });
+    }
+
+    this.emit("round-end", {
+      round: this.currentRound,
+      contributionCount: contributions.length,
+    });
+    return round;
+  }
+
+  /**
+   * Conclude the party and generate a summary.
+   *
+   * @returns {Object} Party summary
+   */
+  conclude() {
+    this.status = PartyStatus.CONCLUDED;
+    const duration = this._startTime ? Date.now() - this._startTime : 0;
+
+    const summary = {
+      sessionId: this.sessionId,
+      topic: this.topic,
+      agents: this.agents,
+      rounds: this.rounds.length,
+      duration,
+      contributions: this._flattenContributions(),
+      consensus: this._extractConsensus(),
+      status: this.status,
+    };
+
+    this.emit("party-end", summary);
+    return summary;
+  }
+
+  /**
+   * Get current party state.
+   *
+   * @returns {Object} Current state
+   */
+  getState() {
+    return {
+      sessionId: this.sessionId,
+      topic: this.topic,
+      status: this.status,
+      currentRound: this.currentRound,
+      maxRounds: this.maxRounds,
+      agents: this.agents,
+      roundCount: this.rounds.length,
+    };
+  }
+
+  /**
+   * Build the prompt for an agent including previous round context.
+   */
+  _buildAgentPrompt(agentId, previousContext) {
+    let prompt = `You are participating in a multi-agent collaboration party as ${agentId}.\n\n`;
+    prompt += `## Topic\n${this.topic}\n\n`;
+    prompt += `## Round ${this.currentRound} of ${this.maxRounds}\n\n`;
+
+    if (previousContext) {
+      prompt += `## Previous Contributions\n${previousContext}\n\n`;
+    }
+
+    prompt += "## Your Task\n";
+    prompt += "1. Consider the topic and any previous contributions.\n";
+    prompt += "2. Provide your expert perspective as " + agentId + ".\n";
+    prompt +=
+      "3. If you agree with a previous contribution, state so and build on it.\n";
+    prompt += "4. If you disagree, explain why with reasoning.\n";
+    prompt += "5. End with a clear RECOMMENDATION in one sentence.\n";
+
+    return prompt;
+  }
+
+  /**
+   * Build context string from previous rounds.
+   */
+  _buildPreviousContext() {
+    if (this.rounds.length === 0) return "";
+
+    // H9 fix: Sliding window — only keep last round to prevent unbounded growth
+    const MAX_CONTEXT_CHARS = 16000;
+    const lastRound = this.rounds[this.rounds.length - 1];
+    const lines = [`### Round ${lastRound.number}`];
+    const perAgentBudget = Math.floor(
+      MAX_CONTEXT_CHARS / Math.max(1, this.agents.length),
+    );
+
+    for (const c of lastRound.contributions) {
+      if (c.success) {
+        const summary =
+          c.output.length > perAgentBudget
+            ? c.output.slice(0, perAgentBudget) + "..."
+            : c.output;
+        lines.push(`**${c.agentId}:** ${summary}`);
+      }
+    }
+    return lines.join("\n\n");
+  }
+
+  /**
+   * Detect if agents are converging (agreeing).
+   * Simple heuristic: look for agreement keywords in outputs.
+   */
+  _detectConvergence(contributions) {
+    const successfulOutputs = contributions
+      .filter((c) => c.success)
+      .map((c) => c.output.toLowerCase());
+
+    if (successfulOutputs.length < 2) return false;
+
+    // M2 fix: Use word-boundary regex to avoid false positives like "I do not agree"
+    const agreementPatterns = [
+      /\bi agree\b/,
+      /\bconcur\b/,
+      /\baligned\b/,
+      /\bsame conclusion\b/,
+      /\bconsensus\b/,
+    ];
+    const negationPattern = /\b(?:do not|don't|not|disagree|cannot)\b/;
+    let agreeCount = 0;
+
+    for (const output of successfulOutputs) {
+      for (const pattern of agreementPatterns) {
+        const match = output.match(pattern);
+        if (!match) continue;
+        const matchIdx = match.index;
+        const window = output.slice(Math.max(0, matchIdx - 20), matchIdx + 30);
+        if (!negationPattern.test(window)) {
+          agreeCount++;
+          break;
+        }
+      }
+    }
+
+    return agreeCount >= Math.ceil(successfulOutputs.length / 2);
+  }
+
+  /**
+   * Flatten all contributions across rounds.
+   */
+  _flattenContributions() {
+    const flat = [];
+    for (const round of this.rounds) {
+      for (const c of round.contributions) {
+        flat.push({ round: round.number, ...c });
+      }
+    }
+    return flat;
+  }
+
+  /**
+   * Extract consensus or divergent points from final round.
+   */
+  _extractConsensus() {
+    if (this.rounds.length === 0)
+      return { reached: false, summary: "No rounds completed" };
+
+    const lastRound = this.rounds[this.rounds.length - 1];
+    const successful = lastRound.contributions.filter((c) => c.success);
+
+    if (successful.length === 0)
+      return { reached: false, summary: "No successful contributions" };
+
+    // Extract recommendations (look for RECOMMENDATION keyword)
+    const recommendations = [];
+    for (const c of successful) {
+      const match = c.output.match(/RECOMMENDATION[:\s]+(.+?)(?:\n|$)/i);
+      if (match) {
+        recommendations.push({
+          agentId: c.agentId,
+          recommendation: match[1].trim(),
+        });
+      }
+    }
+
+    return {
+      reached: this.status === PartyStatus.CONVERGED,
+      recommendations,
+      participantCount: successful.length,
+    };
+  }
+}
+
+module.exports = { PartySession, PartyStatus };

package/.merlin-core/core/execution/rate-limit-manager.js

@@ -0,0 +1,152 @@
+/**
+ * Rate Limit Manager
+ *
+ * Manages API rate limiting for agent invocations using a sliding
+ * window algorithm. Prevents exceeding configurable per-key limits.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/rate-limit-manager
+ * @version 3.0.0
+ */
+
+// ---------------------------------------------------------------------------
+//  Default limits
+// ---------------------------------------------------------------------------
+
+const DEFAULT_LIMITS = {
+  perMinute: 60,
+  perHour: 1000,
+};
+
+// ---------------------------------------------------------------------------
+//  RateLimitManager
+// ---------------------------------------------------------------------------
+
+class RateLimitManager {
+  constructor() {
+    /**
+     * Per-key configuration: { perMinute, perHour }
+     * @type {Map<string, Object>}
+     */
+    this._limits = new Map();
+
+    /**
+     * Per-key usage timestamps.
+     * @type {Map<string, number[]>}
+     */
+    this._usage = new Map();
+  }
+
+  // -----------------------------------------------------------------------
+  //  Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Check whether a request for `key` is currently allowed.
+   *
+   * @param {string} key - Rate limit bucket (e.g. "claude-api", "gemini-api").
+   * @returns {{allowed: boolean, waitMs: number}}
+   *   `waitMs` is 0 when allowed, otherwise the ms to wait.
+   */
+  check(key) {
+    const limits = this._limitsFor(key);
+    const now = Date.now();
+    const timestamps = this._getTimestamps(key);
+
+    // M4 fix: Prune stale entries on check(), not just record()
+    const oneHourAgo = now - 3_600_000;
+    while (timestamps.length > 0 && timestamps[0] <= oneHourAgo) {
+      timestamps.shift();
+    }
+
+    // --- Per-minute window ---
+    const oneMinuteAgo = now - 60_000;
+    const recentMinute = timestamps.filter((t) => t > oneMinuteAgo);
+
+    if (recentMinute.length >= limits.perMinute) {
+      const oldest = recentMinute[0];
+      const waitMs = oldest + 60_000 - now;
+      return { allowed: false, waitMs: Math.max(waitMs, 1) };
+    }
+
+    // --- Per-hour window ---
+    const recentHour = timestamps.filter((t) => t > oneHourAgo);
+
+    if (recentHour.length >= limits.perHour) {
+      const oldest = recentHour[0];
+      const waitMs = oldest + 3_600_000 - now;
+      return { allowed: false, waitMs: Math.max(waitMs, 1) };
+    }
+
+    return { allowed: true, waitMs: 0 };
+  }
+
+  /**
+   * Record a usage event for `key`.
+   *
+   * @param {string} key
+   */
+  record(key) {
+    const timestamps = this._getTimestamps(key);
+    timestamps.push(Date.now());
+
+    // Garbage-collect entries older than 1 hour
+    const oneHourAgo = Date.now() - 3_600_000;
+    const pruned = timestamps.filter((t) => t > oneHourAgo);
+    this._usage.set(key, pruned);
+  }
+
+  /**
+   * Configure rate limits for a specific key.
+   *
+   * @param {string} key
+   * @param {{perMinute?: number, perHour?: number}} limits
+   */
+  configure(key, limits) {
+    this._limits.set(key, {
+      perMinute: limits.perMinute ?? DEFAULT_LIMITS.perMinute,
+      perHour: limits.perHour ?? DEFAULT_LIMITS.perHour,
+    });
+  }
+
+  /**
+   * Reset all usage history for a key.
+   *
+   * @param {string} key
+   */
+  reset(key) {
+    this._usage.set(key, []);
+  }
+
+  // -----------------------------------------------------------------------
+  //  Helpers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Get the configured limits for a key (or defaults).
+   * @param {string} key
+   * @returns {{perMinute: number, perHour: number}}
+   */
+  _limitsFor(key) {
+    return this._limits.get(key) || { ...DEFAULT_LIMITS };
+  }
+
+  /**
+   * Get (or create) the usage timestamp array for a key.
+   * @param {string} key
+   * @returns {number[]}
+   */
+  _getTimestamps(key) {
+    if (!this._usage.has(key)) {
+      this._usage.set(key, []);
+    }
+    return this._usage.get(key);
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { RateLimitManager };

package/.merlin-core/core/execution/result-aggregator.js

@@ -0,0 +1,215 @@
+/**
+ * Result Aggregator
+ *
+ * Aggregates results from parallel executions using different strategies.
+ * Supports: MERGE_ALL, BEST_QUALITY, FIRST_SUCCESS, VOTE.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/result-aggregator
+ * @version 3.0.0
+ */
+
+// ---------------------------------------------------------------------------
+//  Enums
+// ---------------------------------------------------------------------------
+
+const AggregateStrategy = {
+  MERGE_ALL: "merge-all",
+  BEST_QUALITY: "best-quality",
+  FIRST_SUCCESS: "first-success",
+  VOTE: "vote",
+};
+
+// ---------------------------------------------------------------------------
+//  ResultAggregator
+// ---------------------------------------------------------------------------
+
+class ResultAggregator {
+  /**
+   * @param {Object} [config]
+   * @param {Function} [config.qualityScorer] Custom (result) => number scorer.
+   */
+  constructor(config = {}) {
+    this.qualityScorer = config.qualityScorer || this._defaultScorer;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Aggregate an array of results using the specified strategy.
+   *
+   * Each result is expected to have `{ success, output, [error], [source] }`.
+   *
+   * @param {Array<Object>} results
+   * @param {string}        strategy - One of AggregateStrategy values.
+   * @returns {Object} Aggregated result with metadata.
+   */
+  aggregate(results, strategy = AggregateStrategy.FIRST_SUCCESS) {
+    if (!results || results.length === 0) {
+      return { success: false, error: "No results to aggregate", sources: [] };
+    }
+
+    switch (strategy) {
+      case AggregateStrategy.MERGE_ALL:
+        return this._mergeAll(results);
+      case AggregateStrategy.BEST_QUALITY:
+        return this._bestQuality(results);
+      case AggregateStrategy.FIRST_SUCCESS:
+        return this._firstSuccess(results);
+      case AggregateStrategy.VOTE:
+        return this._vote(results);
+      default:
+        return this._firstSuccess(results);
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  //  Strategy Implementations
+  // -----------------------------------------------------------------------
+
+  /**
+   * Combine all successful outputs into a single array.
+   * @private
+   */
+  _mergeAll(results) {
+    const successes = results.filter((r) => r.success);
+    if (successes.length === 0) {
+      return { success: false, error: "All results failed", sources: [] };
+    }
+
+    return {
+      success: true,
+      output: successes.map((r) => r.output),
+      sources: successes.map((r) => r.source || "unknown"),
+      strategy: AggregateStrategy.MERGE_ALL,
+      mergedCount: successes.length,
+    };
+  }
+
+  /**
+   * Pick the result with the highest quality score.
+   * @private
+   */
+  _bestQuality(results) {
+    const successes = results.filter((r) => r.success);
+    if (successes.length === 0) {
+      return { success: false, error: "All results failed", sources: [] };
+    }
+
+    let best = successes[0];
+    let bestScore = this.qualityScorer(best);
+
+    for (let i = 1; i < successes.length; i++) {
+      const score = this.qualityScorer(successes[i]);
+      if (score > bestScore) {
+        best = successes[i];
+        bestScore = score;
+      }
+    }
+
+    return {
+      success: true,
+      output: best.output,
+      source: best.source || "unknown",
+      qualityScore: bestScore,
+      strategy: AggregateStrategy.BEST_QUALITY,
+      sources: [best.source || "unknown"],
+    };
+  }
+
+  /**
+   * Return the first non-error result.
+   * @private
+   */
+  _firstSuccess(results) {
+    for (const r of results) {
+      if (r.success) {
+        return {
+          success: true,
+          output: r.output,
+          source: r.source || "unknown",
+          strategy: AggregateStrategy.FIRST_SUCCESS,
+          sources: [r.source || "unknown"],
+        };
+      }
+    }
+
+    return {
+      success: false,
+      error: results[results.length - 1]?.error || "All results failed",
+      sources: [],
+      strategy: AggregateStrategy.FIRST_SUCCESS,
+    };
+  }
+
+  /**
+   * Use majority consensus: group outputs, pick the most common.
+   * @private
+   */
+  _vote(results) {
+    const successes = results.filter((r) => r.success);
+    if (successes.length === 0) {
+      return { success: false, error: "All results failed", sources: [] };
+    }
+
+    // Group by stringified output
+    const groups = new Map();
+    for (const r of successes) {
+      const key = JSON.stringify(r.output);
+      if (!groups.has(key)) {
+        groups.set(key, { output: r.output, voters: [] });
+      }
+      groups.get(key).voters.push(r.source || "unknown");
+    }
+
+    // Find majority
+    let majorityGroup = null;
+    for (const group of groups.values()) {
+      if (!majorityGroup || group.voters.length > majorityGroup.voters.length) {
+        majorityGroup = group;
+      }
+    }
+
+    return {
+      success: true,
+      output: majorityGroup.output,
+      sources: majorityGroup.voters,
+      voteCount: majorityGroup.voters.length,
+      totalVoters: successes.length,
+      consensus: majorityGroup.voters.length > successes.length / 2,
+      strategy: AggregateStrategy.VOTE,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  //  Helpers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Default quality scorer.
+   * @param {Object} result
+   * @returns {number}
+   */
+  _defaultScorer(result) {
+    if (!result || !result.output) return 0;
+    const str =
+      typeof result.output === "string"
+        ? result.output
+        : JSON.stringify(result.output);
+    let score = 0;
+    if (str.length > 100) score += 1;
+    if (str.length > 500) score += 1;
+    if (str.includes("```")) score += 2;
+    if (!result.error) score += 1;
+    return score;
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { ResultAggregator, AggregateStrategy };