@saulwade/swl-ses 1.3.8 → 1.4.0

package/gateway/cron/jobs.js

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * Cron Jobs — Parse de schedules y gestión de estado de jobs.
+ *
+ * Soporta 4 formatos de schedule (adoptados de Hermes Agent cron/jobs.py):
+ *   1. Duración única:     "30m", "2h", "1d"         → ejecutar una vez en N minutos
+ *   2. Intervalo recurrente: "every 30m", "every 2h"  → ejecutar cada N minutos
+ *   3. Expresión cron:     "0 9 * * 1-5"              → cron estándar (5 campos)
+ *   4. Timestamp ISO:      "2026-04-15T09:00"          → una vez a hora exacta
+ *
+ * Grace windows (adoptados de Hermes):
+ *   - Jobs one-shot: 120s de tolerancia para creación retrasada
+ *   - Jobs recurrentes: grace = period/2, clamped [120s, 7200s]
+ *
+ * @module gateway/cron/jobs
+ */
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const ONESHOT_GRACE_SECONDS = 120;
+const MIN_GRACE_SECONDS     = 120;
+const MAX_GRACE_SECONDS     = 7200; // 2 horas
+
+/** Regex para parse de duraciones: "30m", "2h", "1d" */
+const DURATION_RE = /^(\d+)\s*(m|min|h|hr|d)$/i;
+
+/** Regex para intervalo recurrente: "every 30m", "every 2h" */
+const INTERVAL_RE = /^every\s+(\d+)\s*(m|min|h|hr|d)$/i;
+
+/** Regex para expresión cron: "0 9 * * 1-5" (5 campos) */
+const CRON_RE = /^(\S+\s+){4}\S+$/;
+
+/** Multiplicadores de duración a minutos */
+const DURATION_MULTIPLIERS = {
+  m: 1, min: 1,
+  h: 60, hr: 60,
+  d: 1440,
+};
+
+// ---------------------------------------------------------------------------
+// Parse de schedules
+// ---------------------------------------------------------------------------
+
+/**
+ * Parsea un string de schedule en un objeto estructurado.
+ *
+ * @param {string} schedule - String del schedule.
+ * @returns {{ kind: 'once'|'interval'|'cron', minutes?: number, runAt?: string, expr?: string }}
+ * @throws {Error} Si el formato no es reconocido.
+ */
+function parseSchedule(schedule) {
+  if (!schedule || typeof schedule !== 'string') {
+    throw new Error(`Schedule inválido: "${schedule}"`);
+  }
+
+  const s = schedule.trim();
+
+  // 1. Intervalo recurrente: "every 30m"
+  const intervalMatch = s.match(INTERVAL_RE);
+  if (intervalMatch) {
+    const value = parseInt(intervalMatch[1], 10);
+    const unit  = intervalMatch[2].toLowerCase();
+    const mult  = DURATION_MULTIPLIERS[unit] || DURATION_MULTIPLIERS[unit.charAt(0)];
+    return { kind: 'interval', minutes: value * mult };
+  }
+
+  // 2. Duración única: "30m", "2h"
+  const durationMatch = s.match(DURATION_RE);
+  if (durationMatch) {
+    const value = parseInt(durationMatch[1], 10);
+    const unit  = durationMatch[2].toLowerCase();
+    const mult  = DURATION_MULTIPLIERS[unit] || DURATION_MULTIPLIERS[unit.charAt(0)];
+    const runAt = new Date(Date.now() + value * mult * 60000);
+    return { kind: 'once', minutes: value * mult, runAt: runAt.toISOString() };
+  }
+
+  // 3. Timestamp ISO: "2026-04-15T09:00", "2026-04-15T09:00:00Z"
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(s)) {
+    const dt = new Date(s);
+    if (isNaN(dt.getTime())) throw new Error(`Timestamp ISO inválido: "${s}"`);
+    return { kind: 'once', runAt: dt.toISOString() };
+  }
+
+  // 4. Expresión cron: "0 9 * * 1-5"
+  if (CRON_RE.test(s)) {
+    return { kind: 'cron', expr: s };
+  }
+
+  throw new Error(`Formato de schedule no reconocido: "${s}". Formatos válidos: "30m", "every 2h", "0 9 * * 1-5", "2026-04-15T09:00"`);
+}
+
+// ---------------------------------------------------------------------------
+// Cálculo de próxima ejecución
+// ---------------------------------------------------------------------------
+
+/**
+ * Calcula la próxima ejecución de un job.
+ *
+ * @param {object} job - Objeto del job con schedule parseado y lastRunAt.
+ * @returns {string|null} ISO timestamp de la próxima ejecución, o null si completado.
+ */
+function computeNextRun(job) {
+  const schedule = job.parsedSchedule || parseSchedule(job.schedule);
+  const now = new Date();
+
+  switch (schedule.kind) {
+    case 'once': {
+      // Si ya se ejecutó, no hay próxima
+      if (job.lastRunAt) return null;
+      return schedule.runAt;
+    }
+    case 'interval': {
+      const intervalMs = schedule.minutes * 60000;
+      if (job.lastRunAt) {
+        return new Date(new Date(job.lastRunAt).getTime() + intervalMs).toISOString();
+      }
+      // Primera ejecución: ahora + intervalo
+      return new Date(now.getTime() + intervalMs).toISOString();
+    }
+    case 'cron': {
+      // Cálculo simplificado de next cron (sin dependencia croniter)
+      // Para cron complejo, usar computeNextCronRun()
+      return _computeSimpleCronNext(schedule.expr, now);
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Calcula grace seconds para un job según su periodicidad.
+ * Jobs más frecuentes tienen grace más corto; diarios más largo.
+ *
+ * @param {object} job
+ * @returns {number} Segundos de tolerancia.
+ */
+function computeGraceSeconds(job) {
+  const schedule = job.parsedSchedule || parseSchedule(job.schedule);
+
+  if (schedule.kind === 'once') return ONESHOT_GRACE_SECONDS;
+
+  if (schedule.kind === 'interval') {
+    const periodSeconds = schedule.minutes * 60;
+    const grace = Math.floor(periodSeconds / 2);
+    return Math.max(MIN_GRACE_SECONDS, Math.min(grace, MAX_GRACE_SECONDS));
+  }
+
+  // Cron: asumir grace de 2 minutos por defecto
+  return MIN_GRACE_SECONDS;
+}
+
+/**
+ * Verifica si un job es elegible para ejecución.
+ *
+ * @param {object} job
+ * @param {Date} [now=new Date()]
+ * @returns {boolean}
+ */
+function isEligible(job, now = new Date()) {
+  if (job.status !== 'scheduled') return false;
+  if (!job.nextRun) return false;
+
+  // Verificar límite de repeticiones
+  if (job.repeat && job.repeat.times !== null && job.repeat.times !== undefined) {
+    if ((job.repeat.completed || 0) >= job.repeat.times) return false;
+  }
+
+  const nextRunDate = new Date(job.nextRun);
+  const graceMs     = computeGraceSeconds(job) * 1000;
+
+  // Elegible si: nextRun ya pasó pero dentro de la ventana de grace
+  // (now - grace) <= nextRun <= now
+  // Un job con nextRun más allá del grace se considera perdido (fast-forward)
+  const nextRunMs = nextRunDate.getTime();
+  const nowMs     = now.getTime();
+  return nextRunMs <= nowMs && nextRunMs >= (nowMs - graceMs);
+}
+
+// ---------------------------------------------------------------------------
+// Cron simple (sin dependencia externa)
+// ---------------------------------------------------------------------------
+
+/**
+ * Cálculo simplificado de próxima ejecución cron.
+ * Soporta: minuto, hora, día del mes, mes, día de la semana.
+ * Para expresiones complejas (rangos, listas), busca fuerza bruta en 48h.
+ *
+ * @param {string} expr - Expresión cron de 5 campos.
+ * @param {Date} from - Fecha desde la cual buscar.
+ * @returns {string|null} ISO timestamp o null si no se encuentra en 48h.
+ */
+function _computeSimpleCronNext(expr, from) {
+  const fields = expr.split(/\s+/);
+  if (fields.length !== 5) return null;
+
+  const [minF, hourF, domF, monF, dowF] = fields;
+
+  // Buscar en los próximos 2880 minutos (48 horas)
+  const candidate = new Date(from);
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1); // Empezar desde el próximo minuto
+
+  for (let i = 0; i < 2880; i++) {
+    if (_cronFieldMatches(minF, candidate.getMinutes()) &&
+        _cronFieldMatches(hourF, candidate.getHours()) &&
+        _cronFieldMatches(domF, candidate.getDate()) &&
+        _cronFieldMatches(monF, candidate.getMonth() + 1) &&
+        _cronFieldMatches(dowF, candidate.getDay())) {
+      return candidate.toISOString();
+    }
+    candidate.setMinutes(candidate.getMinutes() + 1);
+  }
+
+  return null; // No encontrado en 48h
+}
+
+/**
+ * Verifica si un valor coincide con un campo cron.
+ * Soporta: *, N, N-M, N/step, listas (N,M,O).
+ */
+function _cronFieldMatches(field, value) {
+  if (field === '*') return true;
+
+  // Lista: "1,3,5"
+  if (field.includes(',')) {
+    return field.split(',').some(f => _cronFieldMatches(f.trim(), value));
+  }
+
+  // Step: "*/5" o "1-10/2"
+  if (field.includes('/')) {
+    const [range, step] = field.split('/');
+    const stepN = parseInt(step, 10);
+    if (range === '*') return value % stepN === 0;
+    const [start] = range.split('-').map(Number);
+    return value >= start && (value - start) % stepN === 0;
+  }
+
+  // Rango: "1-5"
+  if (field.includes('-')) {
+    const [start, end] = field.split('-').map(Number);
+    return value >= start && value <= end;
+  }
+
+  // Valor exacto
+  return parseInt(field, 10) === value;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  parseSchedule,
+  computeNextRun,
+  computeGraceSeconds,
+  isEligible,
+  ONESHOT_GRACE_SECONDS,
+  MIN_GRACE_SECONDS,
+  MAX_GRACE_SECONDS,
+};

package/gateway/cron/scheduler.js

@@ -0,0 +1,322 @@
+'use strict';
+
+/**
+ * Cron Scheduler — Tick loop para ejecución de jobs programados.
+ *
+ * Inspirado en Hermes Agent (cron/scheduler.py):
+ *   - File lock exclusivo para prevenir ejecución concurrente
+ *   - Tick cada 60 segundos
+ *   - Grace windows para jobs retrasados
+ *   - Entrega de resultados local o vía gateway
+ *
+ * Uso:
+ *   node gateway/cron/scheduler.js [baseDir]
+ *
+ * También exporta funciones para uso programático desde otros módulos.
+ *
+ * @module gateway/cron/scheduler
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const { loadJobs, markExecuted, updateAgentState } = require('./store');
+const { isEligible } = require('./jobs');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+/** Intervalo entre ticks en milisegundos. */
+const TICK_INTERVAL_MS = 60000;
+
+/** Nombre del archivo de lock. */
+const LOCK_FILENAME = '.tick.lock';
+
+/** Timeout de ejecución de un job individual (5 minutos). */
+const JOB_TIMEOUT_MS = 300000;
+
+// ---------------------------------------------------------------------------
+// File lock (cross-platform)
+// ---------------------------------------------------------------------------
+
+let _lockFd = null;
+let _lockPath = null;
+
+/**
+ * Adquiere un lock exclusivo basado en archivo.
+ * Previene múltiples instancias del scheduler ejecutándose simultáneamente.
+ *
+ * @param {string} baseDir
+ * @returns {boolean} true si se adquirió el lock, false si ya está tomado.
+ */
+function acquireLock(baseDir) {
+  const cronDir = path.join(baseDir, '.planning', 'cron');
+  if (!fs.existsSync(cronDir)) fs.mkdirSync(cronDir, { recursive: true });
+
+  _lockPath = path.join(cronDir, LOCK_FILENAME);
+
+  try {
+    // O_WRONLY | O_CREAT | O_EXCL — falla si el archivo ya existe
+    _lockFd = fs.openSync(_lockPath, 'wx');
+    fs.writeSync(_lockFd, `${process.pid}\n${new Date().toISOString()}\n`);
+    return true;
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      // Lock ya existe — verificar si el proceso que lo creó sigue vivo
+      try {
+        const content = fs.readFileSync(_lockPath, 'utf8');
+        const pid = parseInt(content.split('\n')[0], 10);
+        if (pid && _isProcessAlive(pid)) {
+          return false; // Otro proceso lo tiene
+        }
+        // Proceso muerto — robar el lock
+        fs.unlinkSync(_lockPath);
+        return acquireLock(baseDir); // Reintentar
+      } catch (_) {
+        return false;
+      }
+    }
+    return false;
+  }
+}
+
+/**
+ * Libera el lock.
+ */
+function releaseLock() {
+  if (_lockFd !== null) {
+    try { fs.closeSync(_lockFd); } catch (e) { /* fd ya cerrado */ }
+    _lockFd = null;
+  }
+  if (_lockPath) {
+    try { fs.unlinkSync(_lockPath); } catch (e) { /* lock ya eliminado */ }
+    _lockPath = null;
+  }
+}
+
+function _isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0); // Signal 0 = check existence
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Ejecución de jobs
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta un job individual.
+ *
+ * @param {object} job - Job a ejecutar.
+ * @param {string} baseDir
+ * @returns {{ status: string, output: string }}
+ */
+function executeJob(job, baseDir) {
+  const command = job.command;
+  if (!command) {
+    return { status: 'error', output: 'Job sin comando definido' };
+  }
+
+  try {
+    const output = execSync(command, {
+      cwd: baseDir,
+      encoding: 'utf8',
+      timeout: JOB_TIMEOUT_MS,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        SWL_CRON_JOB_ID: job.id,
+        SWL_CRON_JOB_NAME: job.name,
+      },
+    });
+
+    return { status: 'completed', output: output.trim() };
+  } catch (err) {
+    const output = err.stdout ? err.stdout.toString() : err.message;
+    const stderr = err.stderr ? err.stderr.toString() : '';
+    return {
+      status: 'error',
+      output: `${output}\n${stderr}`.trim().substring(0, 2000),
+    };
+  }
+}
+
+/**
+ * Entrega el resultado de un job al destino configurado.
+ *
+ * @param {object} job    - Job ejecutado.
+ * @param {object} result - Resultado de executeJob.
+ * @param {string} baseDir
+ */
+function deliverResult(job, result, baseDir) {
+  const deliver = job.deliver || 'local';
+
+  if (deliver === 'local') {
+    // Guardar en .planning/cron/output/{jobId}/
+    const outputDir = path.join(baseDir, '.planning', 'cron', 'output', job.id);
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const filePath  = path.join(outputDir, `${timestamp}.md`);
+
+    const content = [
+      `# Cron: ${job.name}`,
+      ``,
+      `**Job ID**: ${job.id}`,
+      `**Ejecutado**: ${new Date().toISOString()}`,
+      `**Comando**: \`${job.command}\``,
+      `**Estado**: ${result.status}`,
+      ``,
+      '## Output',
+      '```',
+      result.output || '(sin output)',
+      '```',
+    ].join('\n');
+
+    try {
+      const { atomicWriteSync } = require('../../hooks/lib/atomic-write');
+      atomicWriteSync(filePath, content);
+    } catch (_) {
+      fs.writeFileSync(filePath, content, 'utf8');
+    }
+    return;
+  }
+
+  // Entrega vía gateway (telegram, discord, webhook)
+  // Escribir en agent-comms para que el gateway lo recoja
+  try {
+    const { enviarMensaje } = require('../../hooks/lib/agent-comms');
+    enviarMensaje(baseDir, {
+      type: 'gateway_notification',
+      from: 'cron-scheduler',
+      to: deliver,
+      payload: {
+        jobId: job.id,
+        jobName: job.name,
+        status: result.status,
+        output: result.output?.substring(0, 1000),
+      },
+    });
+  } catch (_) {
+    // Si agent-comms falla, guardar localmente como fallback
+    deliverResult({ ...job, deliver: 'local' }, result, baseDir);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tick
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta un tick del scheduler: evalúa y ejecuta jobs elegibles.
+ *
+ * @param {string} baseDir
+ * @returns {{ executed: number, errors: number }}
+ */
+function tick(baseDir) {
+  const jobs = loadJobs(baseDir);
+  const now  = new Date();
+  let executed = 0;
+  let errors   = 0;
+
+  for (const job of jobs) {
+    if (!isEligible(job, now)) continue;
+
+    const result = executeJob(job, baseDir);
+    markExecuted(baseDir, job.id, result);
+    updateAgentState(baseDir, job.id, result); // state-per-agent: consecutiveErrors, runCount
+    deliverResult(job, result, baseDir);
+
+    if (result.status === 'completed') {
+      executed++;
+    } else {
+      errors++;
+    }
+  }
+
+  return { executed, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Scheduler loop
+// ---------------------------------------------------------------------------
+
+let _intervalId = null;
+
+/**
+ * Inicia el scheduler loop.
+ *
+ * @param {string} baseDir
+ * @returns {boolean} true si se inició, false si ya hay uno corriendo.
+ */
+function startScheduler(baseDir) {
+  if (!acquireLock(baseDir)) {
+    return false;
+  }
+
+  // Registrar cleanup
+  const cleanup = () => {
+    stopScheduler();
+    process.exit(0);
+  };
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
+
+  // Tick inicial
+  tick(baseDir);
+
+  // Loop
+  _intervalId = setInterval(() => tick(baseDir), TICK_INTERVAL_MS);
+
+  return true;
+}
+
+/**
+ * Detiene el scheduler y libera el lock.
+ */
+function stopScheduler() {
+  if (_intervalId !== null) {
+    clearInterval(_intervalId);
+    _intervalId = null;
+  }
+  releaseLock();
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint CLI
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  const baseDir = process.argv[2] || process.cwd();
+
+  console.log(`[cron-scheduler] Iniciando en ${baseDir}`);
+  console.log(`[cron-scheduler] Tick interval: ${TICK_INTERVAL_MS / 1000}s`);
+
+  const started = startScheduler(baseDir);
+  if (!started) {
+    console.error('[cron-scheduler] Otro scheduler ya está corriendo. Saliendo.');
+    process.exit(1);
+  }
+
+  console.log('[cron-scheduler] Scheduler activo. Ctrl+C para detener.');
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  tick,
+  startScheduler,
+  stopScheduler,
+  executeJob,
+  deliverResult,
+  acquireLock,
+  releaseLock,
+  TICK_INTERVAL_MS,
+};