@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/success-verifier.js

@@ -0,0 +1,227 @@
+/**
+ * Success Verifier -- Multi-signal success verification
+ *
+ * Requires minimum 2 independent success signals before declaring
+ * task completion. Prevents the failure mode where an agent checks
+ * only one indicator (e.g. API status) while the real result is
+ * different (e.g. output file exists on disk).
+ *
+ * Merlin Framework -- Gestao Merlin v3.0.0
+ *
+ * @module core/execution/success-verifier
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Minimum number of independent success signals required.
+ */
+const MIN_SIGNALS_REQUIRED = 2;
+
+/**
+ * Built-in signal types and their verification functions.
+ * Each signal is independent -- failure of one does not affect others.
+ */
+const SignalType = {
+  /** Agent self-reported success */
+  SELF_REPORT: "self_report",
+  /** Output file exists on disk */
+  FILE_EXISTS: "file_exists",
+  /** Output file has non-zero size */
+  FILE_NON_EMPTY: "file_non_empty",
+  /** Output content is non-empty string */
+  OUTPUT_NON_EMPTY: "output_non_empty",
+  /** Expected files were modified */
+  FILES_MODIFIED: "files_modified",
+  /** Exit code was 0 */
+  EXIT_CODE_ZERO: "exit_code_zero",
+  /** Custom verification function passed */
+  CUSTOM: "custom",
+};
+
+class SuccessVerifier {
+  /**
+   * @param {Object} [config]
+   * @param {number} [config.minSignals] - Minimum signals required for success
+   * @param {string} [config.projectRoot] - Project root for file checks
+   * @param {boolean} [config.debug=false]
+   */
+  constructor(config = {}) {
+    this.minSignals = config.minSignals || MIN_SIGNALS_REQUIRED;
+    this.projectRoot = config.projectRoot || process.cwd();
+    this.debug = config.debug || false;
+  }
+
+  /**
+   * Verify task success using multiple independent signals.
+   *
+   * Collects all applicable signals, checks each independently,
+   * and requires at least `minSignals` to pass.
+   *
+   * @param {Object} result - Agent execution result
+   * @param {boolean} [result.success] - Self-reported success
+   * @param {string} [result.output] - Text output
+   * @param {string[]} [result.filesModified] - Files the agent reports modifying
+   * @param {number} [result.exitCode] - Process exit code
+   * @param {Object} task - Original task descriptor
+   * @param {string[]} [task.expectedOutputFiles] - Files expected to exist after success
+   * @param {string[]} [task.files] - Task file list
+   * @param {Function[]} [task.customVerifiers] - Custom verification functions
+   * @returns {{verified: boolean, signals: Array<{type: string, passed: boolean, detail: string}>, passedCount: number, totalCount: number, confidence: number}}
+   */
+  verify(result, task = {}) {
+    const signals = [];
+
+    // Signal 1: Self-reported success
+    signals.push({
+      type: SignalType.SELF_REPORT,
+      passed: result?.success === true,
+      detail: result?.success
+        ? "Agent reported success"
+        : `Agent reported failure${result?.error ? ": " + result.error : ""}`,
+    });
+
+    // Signal 2: Output is non-empty
+    if (result?.output !== undefined) {
+      const hasOutput =
+        typeof result.output === "string"
+          ? result.output.trim().length > 0
+          : result.output != null;
+      signals.push({
+        type: SignalType.OUTPUT_NON_EMPTY,
+        passed: hasOutput,
+        detail: hasOutput
+          ? `Output present (${typeof result.output === "string" ? result.output.length : "non-string"} chars)`
+          : "Output is empty or missing",
+      });
+    }
+
+    // Signal 3: Exit code check
+    if (result?.exitCode !== undefined) {
+      signals.push({
+        type: SignalType.EXIT_CODE_ZERO,
+        passed: result.exitCode === 0,
+        detail:
+          result.exitCode === 0
+            ? "Exit code 0"
+            : `Exit code ${result.exitCode}`,
+      });
+    }
+
+    // Signal 4: Expected output files exist
+    if (task.expectedOutputFiles && Array.isArray(task.expectedOutputFiles)) {
+      for (const file of task.expectedOutputFiles) {
+        const filePath = path.isAbsolute(file)
+          ? file
+          : path.resolve(this.projectRoot, file);
+
+        const exists = fs.existsSync(filePath);
+        signals.push({
+          type: SignalType.FILE_EXISTS,
+          passed: exists,
+          detail: exists ? `File exists: ${file}` : `File NOT found: ${file}`,
+        });
+
+        // Also check non-empty if file exists
+        if (exists) {
+          try {
+            const stats = fs.statSync(filePath);
+            signals.push({
+              type: SignalType.FILE_NON_EMPTY,
+              passed: stats.size > 0,
+              detail:
+                stats.size > 0
+                  ? `File has content: ${file} (${stats.size} bytes)`
+                  : `File is EMPTY: ${file} (0 bytes)`,
+            });
+          } catch {
+            signals.push({
+              type: SignalType.FILE_NON_EMPTY,
+              passed: false,
+              detail: `Could not stat file: ${file}`,
+            });
+          }
+        }
+      }
+    }
+
+    // Signal 5: Expected files were modified
+    if (task.files && result?.filesModified) {
+      const expected = new Set(
+        task.files.map((f) => path.basename(f).toLowerCase()),
+      );
+      const actual = new Set(
+        result.filesModified.map((f) => path.basename(f).toLowerCase()),
+      );
+      const matched = [...expected].filter((f) => actual.has(f));
+      const allMatched = matched.length === expected.size;
+
+      signals.push({
+        type: SignalType.FILES_MODIFIED,
+        passed: allMatched,
+        detail: allMatched
+          ? `All ${expected.size} expected files were modified`
+          : `Only ${matched.length}/${expected.size} expected files modified (missing: ${[...expected].filter((f) => !actual.has(f)).join(", ")})`,
+      });
+    }
+
+    // Signal 6: Custom verifiers
+    if (task.customVerifiers && Array.isArray(task.customVerifiers)) {
+      for (let i = 0; i < task.customVerifiers.length; i++) {
+        try {
+          const customResult = task.customVerifiers[i](result, task);
+          const passed =
+            typeof customResult === "boolean"
+              ? customResult
+              : customResult?.passed === true;
+          signals.push({
+            type: SignalType.CUSTOM,
+            passed,
+            detail:
+              typeof customResult === "object" && customResult?.detail
+                ? customResult.detail
+                : `Custom verifier #${i + 1}: ${passed ? "passed" : "failed"}`,
+          });
+        } catch (err) {
+          signals.push({
+            type: SignalType.CUSTOM,
+            passed: false,
+            detail: `Custom verifier #${i + 1} threw: ${err.message}`,
+          });
+        }
+      }
+    }
+
+    // Calculate verdict
+    const passedCount = signals.filter((s) => s.passed).length;
+    const totalCount = signals.length;
+    const confidence =
+      totalCount === 0 ? 0 : Math.round((passedCount / totalCount) * 100) / 100;
+    const verified = passedCount >= this.minSignals;
+
+    if (this.debug) {
+      console.log(
+        `[SuccessVerifier] ${passedCount}/${totalCount} signals passed ` +
+          `(need ${this.minSignals}). Verified: ${verified}`,
+      );
+      for (const s of signals) {
+        console.log(`  [${s.passed ? "PASS" : "FAIL"}] ${s.type}: ${s.detail}`);
+      }
+    }
+
+    return {
+      verified,
+      signals,
+      passedCount,
+      totalCount,
+      confidence,
+      minRequired: this.minSignals,
+    };
+  }
+}
+
+module.exports = { SuccessVerifier, SignalType };

package/.merlin-core/core/execution/task-metadata.js

@@ -0,0 +1,105 @@
+/**
+ * Task Metadata Service -- Real-time task name tracking (#31)
+ *
+ * Provides 2-5 word task descriptions for dashboard/status display.
+ * Agents call setActive() at dispatch start and setComplete() at end.
+ * Events published to EventBus channel `task-metadata`.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/task-metadata
+ * @version 3.0.0
+ */
+
+"use strict";
+
+class TaskMetadataService {
+  /**
+   * @param {Object} [config]
+   * @param {Object} [config.eventBus] - EventBus instance for publishing
+   */
+  constructor(config = {}) {
+    this._eventBus = config.eventBus || null;
+    this._current = null;
+    this._history = [];
+    this._maxHistory = 50;
+  }
+
+  /**
+   * Set the currently active task name.
+   *
+   * @param {string} taskName - 2-5 word description (e.g., "Reading auth config")
+   * @param {Object} [metadata] - Optional metadata (agentId, dispatchId, etc.)
+   */
+  setActive(taskName, metadata = {}) {
+    this._current = {
+      name: taskName,
+      startedAt: new Date().toISOString(),
+      ...metadata,
+    };
+
+    if (this._eventBus) {
+      this._eventBus.publish("task-metadata", "active", {
+        name: taskName,
+        ...metadata,
+      });
+    }
+  }
+
+  /**
+   * Mark the current task as complete and archive it.
+   *
+   * @param {string} [taskName] - Task name to complete (defaults to current)
+   * @param {Object} [result] - Optional result metadata
+   */
+  setComplete(taskName, result = {}) {
+    const name = taskName || this._current?.name || "Unknown task";
+    const entry = {
+      name,
+      startedAt: this._current?.startedAt || new Date().toISOString(),
+      completedAt: new Date().toISOString(),
+      ...result,
+    };
+
+    this._history.push(entry);
+    if (this._history.length > this._maxHistory) {
+      this._history.shift();
+    }
+
+    this._current = null;
+
+    if (this._eventBus) {
+      this._eventBus.publish("task-metadata", "complete", {
+        name,
+        ...result,
+      });
+    }
+  }
+
+  /**
+   * Get the currently active task.
+   * @returns {Object|null} Current task or null
+   */
+  getCurrent() {
+    return this._current;
+  }
+
+  /**
+   * Get recent task history.
+   * @param {number} [limit=10] - Max entries to return
+   * @returns {Array<Object>}
+   */
+  getHistory(limit = 10) {
+    return this._history.slice(-limit);
+  }
+
+  /**
+   * Attach an EventBus for publishing.
+   * @param {Object} eventBus - EventBus instance
+   */
+  setEventBus(eventBus) {
+    this._eventBus = eventBus;
+  }
+}
+
+module.exports = { TaskMetadataService };

package/.merlin-core/core/execution/team-executor.js

@@ -0,0 +1,195 @@
+/**
+ * Team Executor -- Multi-agent team execution with 3 modes
+ *
+ * Composes ParallelExecutor + SubagentDispatcher + ResultAggregator
+ * to provide COORDINATE, ROUTE, and BROADCAST execution modes.
+ *
+ * @module core/execution/team-executor
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const { EventEmitter } = require("events");
+const { ParallelExecutor } = require("./parallel-executor");
+const { SubagentDispatcher } = require("./subagent-dispatcher");
+const { ResultAggregator, AggregateStrategy } = require("./result-aggregator");
+const { classifyTop } = require("../orchestration/intent-classifier");
+const { GuardrailEngine } = require("./guardrail-engine");
+
+const TeamMode = {
+  COORDINATE: "coordinate",
+  ROUTE: "route",
+  BROADCAST: "broadcast",
+};
+
+class TeamExecutor extends EventEmitter {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.projectRoot]
+   * @param {number} [config.concurrencyLimit=4]
+   * @param {number} [config.timeout=300000]
+   */
+  constructor(config = {}) {
+    super();
+    this.projectRoot = config.projectRoot || process.cwd();
+    this.parallel = new ParallelExecutor({
+      concurrencyLimit: config.concurrencyLimit || 4,
+      timeout: config.timeout || 300000,
+    });
+    // v3.0.0 — Wire GuardrailEngine into dispatcher
+    const guardrailEngine =
+      config.guardrailEngine ||
+      new GuardrailEngine({ projectRoot: this.projectRoot });
+    this.dispatcher = new SubagentDispatcher({
+      rootPath: this.projectRoot,
+      defaultTimeout: config.timeout || 300000,
+      guardrailEngine,
+    });
+    this.aggregator = new ResultAggregator();
+  }
+
+  /**
+   * Execute a task using the specified team mode.
+   *
+   * @param {Object} task - Task descriptor (id, description, files, ...)
+   * @param {string} mode - One of TeamMode values
+   * @param {string[]} agents - Agent IDs to involve
+   * @returns {Promise<Object>} Aggregated result
+   */
+  async execute(task, mode = TeamMode.ROUTE, agents = [], options = {}) {
+    if (!task || !task.id) {
+      return { success: false, error: "Task with id is required" };
+    }
+    if (agents.length === 0) {
+      return { success: false, error: "At least one agent is required" };
+    }
+
+    this.emit("team-start", { mode, agents, taskId: task.id });
+
+    let result;
+    switch (mode) {
+      case TeamMode.COORDINATE:
+        result = await this._executeCoordinate(task, agents);
+        break;
+      case TeamMode.BROADCAST:
+        result = await this._executeBroadcast(task, agents);
+        break;
+      case TeamMode.ROUTE:
+      default:
+        result = await this._executeRoute(task, agents, options);
+        break;
+    }
+
+    this.emit("team-end", { mode, success: result.success, taskId: task.id });
+    return result;
+  }
+
+  /**
+   * COORDINATE: Split task among agents, run in parallel, merge results.
+   */
+  async _executeCoordinate(task, agents) {
+    const assignments = this._splitTask(task, agents);
+
+    // Stateless delegation (#43): COORDINATE subtasks get no parent context
+    const results = await this.dispatcher.dispatchParallel(
+      assignments.map((a) => ({
+        agentId: a.agentId,
+        task: a.subtask,
+        options: { stateless: true },
+      })),
+    );
+
+    return this.aggregator.aggregate(
+      results.map((r, i) => ({ ...r, source: assignments[i].agentId })),
+      AggregateStrategy.MERGE_ALL,
+    );
+  }
+
+  /**
+   * ROUTE: Dispatch to single best-fit agent.
+   */
+  async _executeRoute(task, agents, options = {}) {
+    const bestAgent = this._selectBestAgent(task, agents);
+    const agentModel =
+      options.agentModels?.[bestAgent] || options.defaultModel || null;
+    const result = await this.dispatcher.dispatch(bestAgent, task, {
+      agentModel,
+    });
+    return { ...result, mode: TeamMode.ROUTE, selectedAgent: bestAgent };
+  }
+
+  /**
+   * BROADCAST: Send same task to all agents, pick best result.
+   */
+  async _executeBroadcast(task, agents) {
+    const assignments = agents.map((agentId) => ({ agentId, task }));
+    const results = await this.dispatcher.dispatchParallel(assignments);
+
+    return this.aggregator.aggregate(
+      results.map((r, i) => ({ ...r, source: agents[i] })),
+      AggregateStrategy.BEST_QUALITY,
+    );
+  }
+
+  /**
+   * Select the best agent for a task using the IntentClassifier.
+   *
+   * @param {Object} task
+   * @param {string[]} agents
+   * @returns {string} Best agent ID
+   */
+  _selectBestAgent(task, agents) {
+    const description = task.description || "";
+    const result = classifyTop(description, agents);
+    if (result && result.confidence >= 0.1) {
+      return result.agentId;
+    }
+    // Fallback: first agent in the list
+    return agents[0];
+  }
+
+  /**
+   * Split a task's files among agents for COORDINATE mode.
+   *
+   * @param {Object} task
+   * @param {string[]} agents
+   * @returns {Array<{agentId: string, subtask: Object}>}
+   */
+  _splitTask(task, agents) {
+    const files = task.files || [];
+    const assignments = [];
+
+    if (files.length === 0) {
+      // No files to split — give full task to first agent
+      assignments.push({ agentId: agents[0], subtask: { ...task } });
+      return assignments;
+    }
+
+    // Round-robin file distribution
+    const agentFiles = {};
+    for (const agent of agents) agentFiles[agent] = [];
+
+    for (let i = 0; i < files.length; i++) {
+      const agent = agents[i % agents.length];
+      agentFiles[agent].push(files[i]);
+    }
+
+    for (const [agentId, agentFileList] of Object.entries(agentFiles)) {
+      if (agentFileList.length === 0) continue;
+      assignments.push({
+        agentId,
+        subtask: {
+          ...task,
+          id: `${task.id}-${agentId}`,
+          files: agentFileList,
+          description: `${task.description} (files: ${agentFileList.join(", ")})`,
+        },
+      });
+    }
+
+    return assignments;
+  }
+}
+
+module.exports = { TeamExecutor, TeamMode };