@caoscompanybr/merlin 3.5.0

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

@@ -0,0 +1,247 @@
+/**
+ * Cron Engine — native scheduled agent turns (v3.4)
+ *
+ * Owns the cron job model, a CLI-first file-backed store (`.merlin/crons.json`),
+ * due-evaluation, isolated agent-turn dispatch (mode "cron" → Sonnet), and the
+ * watchdog audit. The actual timer that ticks lives in the dashboard backend
+ * and shells `merlin cron run <id>`; this engine is the source of truth.
+ *
+ * Ports the MerlinBot cron doctrine (X:\Claw-Ops\F1): isolated + agentTurn,
+ * Sonnet for automation (never Opus), watchdog retries 3× then alerts.
+ *
+ * @module core/execution/cron-engine
+ * @version 3.4.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { matchesCron, parseCron } = require("./cron-expression");
+
+/** Max consecutive failures before the watchdog flags a job for alerting. */
+const MAX_FAILS_BEFORE_ALERT = 3;
+
+/**
+ * Validate (and normalize) a job definition. Throws on invalid input.
+ * @param {Object} job
+ * @returns {Object} normalized job
+ */
+function validateJob(job) {
+  if (!job || typeof job !== "object") throw new Error("job must be an object");
+  if (!job.name || typeof job.name !== "string") {
+    throw new Error("job.name is required");
+  }
+  const schedule = job.schedule || {};
+  if (schedule.kind === "cron") {
+    if (!schedule.expr) throw new Error("cron schedule requires `expr`");
+    parseCron(schedule.expr); // throws if malformed
+  } else if (schedule.kind === "at") {
+    if (!schedule.at || Number.isNaN(Date.parse(schedule.at))) {
+      throw new Error("`at` schedule requires a valid ISO `at` timestamp");
+    }
+  } else {
+    throw new Error('job.schedule.kind must be "cron" or "at"');
+  }
+  const payload = job.payload || {};
+  if (payload.kind !== "agentTurn") {
+    throw new Error('job.payload.kind must be "agentTurn"');
+  }
+  if (!payload.message || typeof payload.message !== "string") {
+    throw new Error("job.payload.message is required");
+  }
+
+  return {
+    id: job.id || slugify(job.name),
+    name: job.name,
+    schedule: {
+      kind: schedule.kind,
+      expr: schedule.expr || null,
+      tz: schedule.tz || null,
+      at: schedule.at || null,
+    },
+    sessionTarget: "isolated", // v1: only isolated supported
+    payload: {
+      kind: "agentTurn",
+      message: payload.message,
+      agent: payload.agent || "@merlin-master",
+      model: payload.model || null,
+    },
+    delivery: { mode: (job.delivery && job.delivery.mode) || "announce" },
+    enabled: job.enabled !== false,
+    last_run: job.last_run || null,
+    last_result: job.last_result || null,
+    fail_count: job.fail_count || 0,
+    done: job.done || false,
+  };
+}
+
+function slugify(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+}
+
+/**
+ * File-backed cron job store (CLI is the source of truth — Constitution I).
+ */
+class CronStore {
+  /**
+   * @param {Object} [config]
+   * @param {string} [config.projectRoot=process.cwd()]
+   * @param {string} [config.filePath] - explicit store path (overrides default)
+   */
+  constructor(config = {}) {
+    this.projectRoot = config.projectRoot || process.cwd();
+    this.filePath =
+      config.filePath || path.join(this.projectRoot, ".merlin", "crons.json");
+  }
+
+  load() {
+    try {
+      const raw = fs.readFileSync(this.filePath, "utf8");
+      const data = JSON.parse(raw);
+      return Array.isArray(data.jobs) ? data.jobs : [];
+    } catch {
+      return []; // missing/corrupt → empty
+    }
+  }
+
+  save(jobs) {
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+    fs.writeFileSync(
+      this.filePath,
+      JSON.stringify({ version: 1, jobs }, null, 2),
+      "utf8",
+    );
+  }
+
+  list() {
+    return this.load();
+  }
+
+  get(id) {
+    return this.load().find((j) => j.id === id) || null;
+  }
+
+  add(job) {
+    const normalized = validateJob(job);
+    const jobs = this.load();
+    if (jobs.some((j) => j.id === normalized.id)) {
+      throw new Error(`cron job already exists: ${normalized.id}`);
+    }
+    jobs.push(normalized);
+    this.save(jobs);
+    return normalized;
+  }
+
+  remove(id) {
+    const jobs = this.load();
+    const next = jobs.filter((j) => j.id !== id);
+    const removed = next.length !== jobs.length;
+    if (removed) this.save(next);
+    return removed;
+  }
+
+  /** Update a job's runtime fields after a run. */
+  recordRun(id, { ok, at }) {
+    const jobs = this.load();
+    const job = jobs.find((j) => j.id === id);
+    if (!job) return null;
+    job.last_run = at;
+    job.last_result = ok ? "success" : "error";
+    job.fail_count = ok ? 0 : (job.fail_count || 0) + 1;
+    if (job.schedule.kind === "at") job.done = true; // one-shot
+    this.save(jobs);
+    return job;
+  }
+}
+
+/**
+ * Is a job due to run at `now`?
+ * @param {Object} job - normalized job
+ * @param {Date} now
+ * @returns {boolean}
+ */
+function isDue(job, now) {
+  if (!job.enabled) return false;
+  if (job.schedule.kind === "at") {
+    if (job.done) return false;
+    return now.getTime() >= Date.parse(job.schedule.at);
+  }
+  return matchesCron(job.schedule.expr, now, job.schedule.tz);
+}
+
+/**
+ * Run a single job: dispatch an isolated agent turn (mode "cron" → Sonnet).
+ * Records the result in the store. Never throws.
+ *
+ * @param {Object} job - normalized job
+ * @param {Object} deps
+ * @param {Object} deps.dispatcher - SubagentDispatcher (or stub with dispatch())
+ * @param {CronStore} [deps.store] - store to record the result in
+ * @param {Date} [deps.now]
+ * @returns {Promise<{ok:boolean, output?:string, error?:string}>}
+ */
+async function runJob(job, deps = {}) {
+  const { dispatcher, store } = deps;
+  const at = (deps.now || new Date()).toISOString();
+  try {
+    const result = await dispatcher.dispatch(
+      job.payload.agent,
+      {
+        id: `cron-${job.id}-${Date.parse(at)}`,
+        description: job.payload.message,
+      },
+      {
+        mode: "cron",
+        // explicit per-job model override wins; else mode→Sonnet via router
+        agentModel: job.payload.model || undefined,
+      },
+    );
+    const ok = !!(result && result.success);
+    if (store) store.recordRun(job.id, { ok, at });
+    return ok
+      ? { ok: true, output: (result && result.output) || "" }
+      : { ok: false, error: (result && result.error) || "dispatch failed" };
+  } catch (err) {
+    const error = err && err.message ? err.message : String(err);
+    if (store) store.recordRun(job.id, { ok: false, at });
+    return { ok: false, error };
+  }
+}
+
+/**
+ * Watchdog audit — port of MerlinBot's 08:30 watchdog.
+ * Classifies jobs by last result; flags repeat failures for alerting.
+ *
+ * @param {CronStore} store
+ * @returns {{healthy:Object[], failing:Object[], needsAlert:Object[]}}
+ */
+function watchdog(store) {
+  const jobs = store.list().filter((j) => j.enabled);
+  const healthy = [];
+  const failing = [];
+  const needsAlert = [];
+  for (const job of jobs) {
+    if (job.last_result === "error") {
+      failing.push(job);
+      if ((job.fail_count || 0) >= MAX_FAILS_BEFORE_ALERT) needsAlert.push(job);
+    } else {
+      healthy.push(job);
+    }
+  }
+  return { healthy, failing, needsAlert };
+}
+
+module.exports = {
+  CronStore,
+  validateJob,
+  slugify,
+  isDue,
+  runJob,
+  watchdog,
+  MAX_FAILS_BEFORE_ALERT,
+};

package/.merlin-core/core/execution/cron-expression.js

@@ -0,0 +1,148 @@
+/**
+ * Cron Expression Matcher — zero-dependency, timezone-aware (v3.4)
+ *
+ * Evaluates standard 5-field crontab expressions
+ * (minute hour day-of-month month day-of-week) against a Date, optionally
+ * in an IANA timezone (via the built-in Intl API — no external deps).
+ *
+ * Supported per-field syntax: wildcard, single value `a`, list `a,b,c`,
+ * range `a-b`, and step forms (slash-N), including range-with-step.
+ * Day-of-week: 0-6 (0 = Sunday). Standard Vixie semantics: when BOTH
+ * day-of-month and day-of-week are restricted, the job runs if EITHER
+ * matches; otherwise fields combine with AND.
+ *
+ * @module core/execution/cron-expression
+ * @version 3.4.0
+ */
+
+"use strict";
+
+const FIELD_RANGES = [
+  { name: "minute", min: 0, max: 59 },
+  { name: "hour", min: 0, max: 23 },
+  { name: "dom", min: 1, max: 31 },
+  { name: "month", min: 1, max: 12 },
+  { name: "dow", min: 0, max: 6 },
+];
+
+/**
+ * Parse one cron field into a Set of allowed integers.
+ * @param {string} field
+ * @param {number} min
+ * @param {number} max
+ * @returns {Set<number>}
+ */
+function parseField(field, min, max) {
+  const allowed = new Set();
+  for (const part of String(field).split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? parseInt(stepPart, 10) : 1;
+    if (!Number.isInteger(step) || step <= 0) {
+      throw new Error(`Invalid step in cron field: "${part}"`);
+    }
+
+    let lo;
+    let hi;
+    if (rangePart === "*") {
+      lo = min;
+      hi = max;
+    } else if (rangePart.includes("-")) {
+      const [a, b] = rangePart.split("-").map((n) => parseInt(n, 10));
+      lo = a;
+      hi = b;
+    } else {
+      lo = parseInt(rangePart, 10);
+      hi = lo;
+    }
+    if (!Number.isInteger(lo) || !Number.isInteger(hi)) {
+      throw new Error(`Invalid cron field: "${part}"`);
+    }
+    if (lo < min || hi > max || lo > hi) {
+      throw new Error(`Cron field out of range (${min}-${max}): "${part}"`);
+    }
+    for (let v = lo; v <= hi; v += step) allowed.add(v);
+  }
+  return allowed;
+}
+
+/**
+ * Parse a full 5-field cron expression.
+ * @param {string} expr
+ * @returns {{minute:Set,hour:Set,dom:Set,month:Set,dow:Set,domRestricted:boolean,dowRestricted:boolean}}
+ */
+function parseCron(expr) {
+  const fields = String(expr).trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(
+      `Cron expression must have 5 fields, got ${fields.length}: "${expr}"`,
+    );
+  }
+  const parsed = {};
+  FIELD_RANGES.forEach((spec, i) => {
+    parsed[spec.name] = parseField(fields[i], spec.min, spec.max);
+  });
+  parsed.domRestricted = fields[2] !== "*";
+  parsed.dowRestricted = fields[4] !== "*";
+  return parsed;
+}
+
+/**
+ * Extract the wall-clock fields of a Date in a given timezone.
+ * @param {Date} date
+ * @param {string} [tz] - IANA tz (e.g. "America/Sao_Paulo"); defaults to system local
+ * @returns {{minute:number,hour:number,dom:number,month:number,dow:number}}
+ */
+function fieldsInTz(date, tz) {
+  if (!tz) {
+    return {
+      minute: date.getMinutes(),
+      hour: date.getHours(),
+      dom: date.getDate(),
+      month: date.getMonth() + 1,
+      dow: date.getDay(),
+    };
+  }
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hourCycle: "h23",
+    minute: "2-digit",
+    hour: "2-digit",
+    day: "2-digit",
+    month: "2-digit",
+    weekday: "short",
+  });
+  const parts = {};
+  for (const p of fmt.formatToParts(date)) parts[p.type] = p.value;
+  const dowMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  return {
+    minute: parseInt(parts.minute, 10),
+    hour: parseInt(parts.hour, 10) % 24,
+    dom: parseInt(parts.day, 10),
+    month: parseInt(parts.month, 10),
+    dow: dowMap[parts.weekday],
+  };
+}
+
+/**
+ * Does `date` match the cron `expr` (in optional tz)?
+ * @param {string} expr - 5-field cron expression
+ * @param {Date} date - the instant to test
+ * @param {string} [tz] - IANA timezone
+ * @returns {boolean}
+ */
+function matchesCron(expr, date, tz) {
+  const c = parseCron(expr);
+  const f = fieldsInTz(date, tz);
+
+  const baseMatch =
+    c.minute.has(f.minute) && c.hour.has(f.hour) && c.month.has(f.month);
+  if (!baseMatch) return false;
+
+  // Vixie day semantics
+  if (c.domRestricted && c.dowRestricted) {
+    return c.dom.has(f.dom) || c.dow.has(f.dow);
+  }
+  return c.dom.has(f.dom) && c.dow.has(f.dow);
+}
+
+module.exports = { matchesCron, parseCron, parseField, fieldsInTz };