@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/heartbeat-engine.js

@@ -0,0 +1,198 @@
+/**
+ * Heartbeat Engine — proactive autonomy pulse (v3.4)
+ *
+ * Runs a single "heartbeat": reads HEARTBEAT.md, dispatches one cheap
+ * (Haiku) agent turn to check project state, and reports either silence
+ * (HEARTBEAT_OK) or an alert. Designed to be driven on a schedule by the
+ * dashboard backend (via `merlin heartbeat run`), but is self-contained
+ * and runnable on its own.
+ *
+ * Ports the MerlinBot heartbeat doctrine (X:\Claw-Ops\F1) natively:
+ *   - cheap model per beat (mode: "heartbeat" → Haiku via ModelRouter)
+ *   - HEARTBEAT_OK sentinel = stay silent
+ *   - per-beat auto-recovery: a failed beat never throws / never stalls
+ *
+ * @module core/execution/heartbeat-engine
+ * @version 3.4.0
+ */
+
+"use strict";
+
+const { EventEmitter } = require("events");
+const fs = require("fs");
+const path = require("path");
+const { SubagentDispatcher } = require("./subagent-dispatcher");
+const { GuardrailEngine } = require("./guardrail-engine");
+const { ModelRouter } = require("./model-router");
+
+/** Sentinel the beat emits when nothing needs attention. */
+const HEARTBEAT_OK = "HEARTBEAT_OK";
+
+/** Beat outcome status values. */
+const HeartbeatStatus = {
+  OK: "ok", // HEARTBEAT_OK — no alert
+  ALERT: "alert", // something needs attention
+  ERROR: "error", // beat failed (recovered — loop continues)
+};
+
+class HeartbeatEngine extends EventEmitter {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.projectRoot=process.cwd()] - Project root
+   * @param {string} [config.heartbeatAgent="@merlin-master"] - Agent that runs the beat
+   * @param {number} [config.timeout=120000] - Per-beat timeout (ms)
+   * @param {SubagentDispatcher} [config.dispatcher] - Inject a dispatcher (else one is created)
+   * @param {ModelRouter} [config.modelRouter] - Inject a router (else one is created)
+   */
+  constructor(config = {}) {
+    super();
+    this.projectRoot = config.projectRoot || process.cwd();
+    this.heartbeatAgent = config.heartbeatAgent || "@merlin-master";
+    this.timeout = config.timeout || 120000;
+
+    // A ModelRouter is required for the mode→Haiku cost split to apply.
+    this.modelRouter = config.modelRouter || new ModelRouter();
+    this.dispatcher =
+      config.dispatcher ||
+      new SubagentDispatcher({
+        rootPath: this.projectRoot,
+        defaultTimeout: this.timeout,
+        modelRouter: this.modelRouter,
+        guardrailEngine:
+          config.guardrailEngine ||
+          new GuardrailEngine({ projectRoot: this.projectRoot }),
+      });
+  }
+
+  /**
+   * Resolve the HEARTBEAT.md checklist content.
+   * Looks for <root>/HEARTBEAT.md, then <root>/.merlin/HEARTBEAT.md; if
+   * neither exists, bootstraps from the shipped template (and writes a copy
+   * to the project root so the user can edit it).
+   *
+   * @returns {string} checklist markdown
+   * @private
+   */
+  _loadHeartbeatDoc() {
+    const candidates = [
+      path.join(this.projectRoot, "HEARTBEAT.md"),
+      path.join(this.projectRoot, ".merlin", "HEARTBEAT.md"),
+    ];
+    for (const p of candidates) {
+      try {
+        if (fs.existsSync(p)) return fs.readFileSync(p, "utf8");
+      } catch {
+        // ignore unreadable candidate, try next
+      }
+    }
+
+    // Bootstrap from the shipped template.
+    const template = path.join(
+      __dirname,
+      "..",
+      "..",
+      "development",
+      "templates",
+      "HEARTBEAT-template.md",
+    );
+    let content = "";
+    try {
+      content = fs.readFileSync(template, "utf8");
+    } catch {
+      content =
+        "# HEARTBEAT.md\n\n- [ ] Pending reminders/objectives\n- [ ] Overdue follow-ups\n- [ ] Cron health\n";
+    }
+    try {
+      fs.writeFileSync(candidates[0], content, "utf8");
+      this.emit("heartbeat-bootstrapped", { path: candidates[0] });
+    } catch {
+      // non-fatal: run with template content even if we can't persist it
+    }
+    return content;
+  }
+
+  /**
+   * Build the beat prompt from the checklist.
+   * @param {string} checklist
+   * @returns {string}
+   * @private
+   */
+  _buildBeatPrompt(checklist) {
+    return [
+      "You are running a HEARTBEAT — a lightweight proactive pulse. Work ONLY from",
+      "Merlin's local state (thoughts: reminders/objectives/handoffs, cron health).",
+      "Do NOT take any external action (no email/posts/messages) and do NOT modify config.",
+      "",
+      "Checklist to evaluate:",
+      "----------------------------------------",
+      checklist.trim(),
+      "----------------------------------------",
+      "",
+      `If NOTHING needs the user's attention, reply with EXACTLY "${HEARTBEAT_OK}" and nothing else.`,
+      "If something DOES need attention, reply with a concise alert (1-3 lines): what it is and why it matters.",
+      "Respect silence hours noted in the checklist.",
+    ].join("\n");
+  }
+
+  /**
+   * Run a single heartbeat. Never throws — a failed beat is recovered and
+   * reported as { status: "error" } so the scheduler loop keeps ticking.
+   *
+   * @param {Object} [options]
+   * @returns {Promise<{status: string, message?: string, severity?: string, error?: string}>}
+   */
+  async run(options = {}) {
+    const beatId = `beat-${Date.now().toString(36)}`;
+    this.emit("heartbeat-start", { beatId });
+
+    try {
+      const checklist = this._loadHeartbeatDoc();
+      const task = {
+        id: beatId,
+        description: this._buildBeatPrompt(checklist),
+      };
+
+      const result = await this.dispatcher.dispatch(this.heartbeatAgent, task, {
+        mode: "heartbeat",
+        timeout: this.timeout,
+        ...options,
+      });
+
+      if (!result || !result.success) {
+        const error = (result && result.error) || "beat dispatch failed";
+        this.emit("heartbeat-error", { beatId, error });
+        this.emit("heartbeat-end", { beatId, status: HeartbeatStatus.ERROR });
+        return { status: HeartbeatStatus.ERROR, error };
+      }
+
+      const output = (result.output || "").trim();
+
+      // HEARTBEAT_OK sentinel → stay silent.
+      if (output === HEARTBEAT_OK || output.includes(HEARTBEAT_OK)) {
+        this.emit("heartbeat-end", { beatId, status: HeartbeatStatus.OK });
+        return { status: HeartbeatStatus.OK };
+      }
+
+      const severity = /\b(urgent|overdue|fail|failed|error|critical)\b/i.test(
+        output,
+      )
+        ? "high"
+        : "info";
+      this.emit("heartbeat-alert", { beatId, message: output, severity });
+      this.emit("heartbeat-end", { beatId, status: HeartbeatStatus.ALERT });
+      return { status: HeartbeatStatus.ALERT, message: output, severity };
+    } catch (err) {
+      // Per-beat auto-recovery: swallow, report, never stall the loop.
+      const error = err && err.message ? err.message : String(err);
+      this.emit("heartbeat-error", { beatId, error });
+      this.emit("heartbeat-end", { beatId, status: HeartbeatStatus.ERROR });
+      return { status: HeartbeatStatus.ERROR, error };
+    }
+  }
+}
+
+module.exports = {
+  HeartbeatEngine,
+  HeartbeatStatus,
+  HEARTBEAT_OK,
+};

package/.merlin-core/core/execution/model-router.js

@@ -0,0 +1,282 @@
+/**
+ * Model Router — Smart model selection based on task complexity
+ *
+ * Generalizes the TwoTierEditor pattern into a first-class routing
+ * service. Maps task complexity to model tiers (haiku/sonnet/opus)
+ * with cost profiles for different operational modes.
+ *
+ * Expected savings: 60-80% cost reduction vs always using opus.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/model-router
+ * @version 3.0.0
+ */
+
+"use strict";
+
+/**
+ * Model tier identifiers.
+ * @enum {string}
+ */
+const ModelTier = {
+  HAIKU: "haiku",
+  SONNET: "sonnet",
+  OPUS: "opus",
+  LOCAL: "local", // v3.4 Manager tier — local GGUF on the GPU, $0
+};
+
+/**
+ * Cost profile presets.
+ * @enum {string}
+ */
+const CostProfile = {
+  ECONOMY: "economy", // Minimize cost: haiku whenever possible
+  BALANCED: "balanced", // Default: match capability to need
+  PERFORMANCE: "performance", // Maximize quality: opus whenever useful
+};
+
+/**
+ * Routing table: complexity × cost-profile → model tier.
+ * @constant
+ */
+const ROUTING_TABLE = {
+  //              economy    balanced   performance
+  TRIVIAL: { economy: "haiku", balanced: "haiku", performance: "sonnet" },
+  SIMPLE: { economy: "haiku", balanced: "sonnet", performance: "sonnet" },
+  MODERATE: { economy: "sonnet", balanced: "sonnet", performance: "opus" },
+  COMPLEX: { economy: "sonnet", balanced: "opus", performance: "opus" },
+};
+
+/**
+ * Task type overrides — these bypass the routing table.
+ * @constant
+ */
+const TASK_TYPE_OVERRIDES = {
+  "security-review": "opus", // Always needs deep reasoning
+  architecture: "sonnet", // Minimum sonnet for design work
+  "code-search": "haiku", // Simple pattern matching
+  formatting: "haiku", // Trivial transformations
+  rename: "haiku", // Simple substitution
+  documentation: "haiku", // Structured writing
+  "complex-refactor": "opus", // Multi-file reasoning
+  debugging: "sonnet", // Needs analytical capability
+};
+
+/**
+ * Execution-mode overrides — the operational dimension (v3.4 cost split).
+ * Distinct from task type: a "mode" describes HOW the turn runs, not what
+ * the task is. Heartbeats are cheap pulses, crons are routine automation,
+ * direct interaction earns the strongest model.
+ * @constant
+ */
+const EXECUTION_MODE_OVERRIDES = {
+  heartbeat: "local", // v3.4: offline GPU pulse ($0); falls back to Claude/haiku
+  cron: "sonnet", // Scheduled automation — never opus
+  interactive: "opus", // Direct user interaction
+};
+
+/**
+ * Relative cost weight per tier, proportional to public output-token pricing
+ * (~haiku:sonnet:opus = 1:3:15). Used to project a cost-distribution index at
+ * the routing layer, where true token counts are not yet available. Absolute
+ * $ accounting would require threading token usage from the dispatcher.
+ * @constant
+ */
+const COST_PER_TIER = {
+  local: 0, // local GPU inference — no API cost
+  haiku: 1,
+  sonnet: 3,
+  opus: 15,
+};
+
+/**
+ * ModelRouter — Smart model selection service.
+ */
+class ModelRouter {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.defaultModel="sonnet"] - Fallback model
+   * @param {string} [options.costProfile="balanced"] - Cost optimization profile
+   */
+  constructor(options = {}) {
+    this.defaultModel = options.defaultModel || ModelTier.SONNET;
+    this.costProfile = options.costProfile || CostProfile.BALANCED;
+
+    /** @type {Map<string, string>} Agent-specific model overrides */
+    this._overrides = new Map();
+
+    /** @type {Object} Routing metrics */
+    this._metrics = {
+      routings: 0,
+      byTier: { haiku: 0, sonnet: 0, opus: 0 },
+      byReason: {},
+      byMode: {},
+      costIndex: 0,
+    };
+  }
+
+  /**
+   * Resolve the optimal model for a given task context.
+   *
+   * Priority:
+   *   1. Explicit agent override (setAgentOverride)
+   *   2. Execution-mode override (EXECUTION_MODE_OVERRIDES — heartbeat/cron/interactive)
+   *   3. Task type override (TASK_TYPE_OVERRIDES)
+   *   4. Complexity × cost-profile routing table
+   *   5. Default model
+   *
+   * @param {string} complexity - Complexity level (TRIVIAL|SIMPLE|MODERATE|COMPLEX)
+   * @param {string} [taskType] - Task type for override lookup
+   * @param {string} [agentId] - Agent identifier for override lookup
+   * @param {string} [mode] - Execution mode (heartbeat|cron|interactive)
+   * @returns {{model: string, reason: string}}
+   */
+  resolveModel(complexity, taskType, agentId, mode) {
+    this._metrics.routings++;
+
+    // 1. Check agent override
+    if (agentId && this._overrides.has(agentId)) {
+      const model = this._overrides.get(agentId);
+      return this._track(model, `agent-override:${agentId}`, mode);
+    }
+
+    // 2. Check execution-mode override (operational dimension)
+    if (mode && EXECUTION_MODE_OVERRIDES[mode]) {
+      const model = EXECUTION_MODE_OVERRIDES[mode];
+      return this._track(model, `mode:${mode}`, mode);
+    }
+
+    // 3. Check task type override
+    if (taskType && TASK_TYPE_OVERRIDES[taskType]) {
+      const model = TASK_TYPE_OVERRIDES[taskType];
+      return this._track(model, `task-type:${taskType}`, mode);
+    }
+
+    // 4. Routing table lookup
+    const complexityKey = (complexity || "MODERATE").toUpperCase();
+    const row = ROUTING_TABLE[complexityKey];
+    if (row) {
+      const model = row[this.costProfile] || this.defaultModel;
+      return this._track(
+        model,
+        `${this.costProfile}:${complexityKey.toLowerCase()}`,
+        mode,
+      );
+    }
+
+    // 5. Default
+    return this._track(this.defaultModel, "default", mode);
+  }
+
+  /**
+   * Set a model override for a specific agent.
+   *
+   * @param {string} agentId - Agent identifier
+   * @param {string} model - Model tier (haiku|sonnet|opus)
+   */
+  setAgentOverride(agentId, model) {
+    if (!Object.values(ModelTier).includes(model)) {
+      throw new Error(
+        `Invalid model tier: ${model}. Must be one of: ${Object.values(ModelTier).join(", ")}`,
+      );
+    }
+    this._overrides.set(agentId, model);
+  }
+
+  /**
+   * Remove a model override for a specific agent.
+   *
+   * @param {string} agentId - Agent identifier
+   */
+  clearAgentOverride(agentId) {
+    this._overrides.delete(agentId);
+  }
+
+  /**
+   * Switch cost profile.
+   *
+   * @param {string} profile - Cost profile (economy|balanced|performance)
+   */
+  setCostProfile(profile) {
+    if (!Object.values(CostProfile).includes(profile)) {
+      throw new Error(
+        `Invalid cost profile: ${profile}. Must be one of: ${Object.values(CostProfile).join(", ")}`,
+      );
+    }
+    this.costProfile = profile;
+  }
+
+  /**
+   * Get routing metrics snapshot.
+   *
+   * @returns {Object} Metrics including total routings, tier distribution, reason breakdown
+   */
+  getMetrics() {
+    const total = this._metrics.routings;
+    // Baseline cost if every routing had used opus — lets us express savings.
+    const opusBaseline = total * COST_PER_TIER.opus;
+    const savingsPct =
+      opusBaseline > 0
+        ? `${(((opusBaseline - this._metrics.costIndex) / opusBaseline) * 100).toFixed(1)}%`
+        : "N/A";
+    return {
+      ...this._metrics,
+      tierDistribution:
+        total > 0
+          ? {
+              haiku: `${((this._metrics.byTier.haiku / total) * 100).toFixed(1)}%`,
+              sonnet: `${((this._metrics.byTier.sonnet / total) * 100).toFixed(1)}%`,
+              opus: `${((this._metrics.byTier.opus / total) * 100).toFixed(1)}%`,
+            }
+          : { haiku: "N/A", sonnet: "N/A", opus: "N/A" },
+      // Projected relative cost (sum of per-tier weights) vs an all-opus
+      // baseline. Relative units, not absolute $ (token counts not available here).
+      costSavingsVsOpus: savingsPct,
+    };
+  }
+
+  /**
+   * Reset metrics counters.
+   */
+  resetMetrics() {
+    this._metrics = {
+      routings: 0,
+      byTier: { haiku: 0, sonnet: 0, opus: 0 },
+      byReason: {},
+      byMode: {},
+      costIndex: 0,
+    };
+  }
+
+  /**
+   * Track a model selection in metrics and return result.
+   *
+   * @param {string} model - Selected model tier
+   * @param {string} reason - Selection reason
+   * @param {string} [mode] - Execution mode the routing ran under
+   * @returns {{model: string, reason: string}}
+   * @private
+   */
+  _track(model, reason, mode) {
+    this._metrics.byTier[model] = (this._metrics.byTier[model] || 0) + 1;
+    this._metrics.byReason[reason] = (this._metrics.byReason[reason] || 0) + 1;
+    if (mode) {
+      this._metrics.byMode[mode] = (this._metrics.byMode[mode] || 0) + 1;
+    }
+    // Nullish (not ||) so the local tier's legitimate 0 cost isn't coerced to
+    // the sonnet fallback weight.
+    this._metrics.costIndex += COST_PER_TIER[model] ?? COST_PER_TIER.sonnet;
+    return { model, reason };
+  }
+}
+
+module.exports = {
+  ModelRouter,
+  ModelTier,
+  CostProfile,
+  ROUTING_TABLE,
+  TASK_TYPE_OVERRIDES,
+  EXECUTION_MODE_OVERRIDES,
+  COST_PER_TIER,
+};