@stonyx/cron 0.2.0 → 0.2.1-alpha.1

package/src/job.js

@@ -0,0 +1,200 @@
+/**
+ * Job data model and state machine for the advanced scheduling system.
+ */
+import { computeNextRunAtMs, validateSchedule } from './schedule.js';
+
+/**
+ * Error backoff table (milliseconds).
+ * Applied after consecutive errors to prevent hammering.
+ */
+const ERROR_BACKOFF_MS = [30_000, 60_000, 300_000, 900_000, 3_600_000];
+
+export function errorBackoffMs(consecutiveErrors) {
+  if (consecutiveErrors < 1) return 0;
+  return ERROR_BACKOFF_MS[Math.min(consecutiveErrors - 1, ERROR_BACKOFF_MS.length - 1)];
+}
+
+/**
+ * Create a new job object from input.
+ *
+ * @param {object} input - Job creation input
+ * @param {string} input.name - Job name
+ * @param {object} input.schedule - Schedule definition (at/every/cron)
+ * @param {object} input.payload - What to execute
+ * @param {string} [input.description]
+ * @param {boolean} [input.enabled=true]
+ * @param {boolean} [input.deleteAfterRun=false]
+ * @param {string} [input.sessionTarget="isolated"]
+ * @param {string} [input.wakeMode="now"]
+ * @param {object} [input.delivery]
+ * @returns {object} Complete job object with state
+ */
+export function createJob(input) {
+  validateSchedule(input.schedule);
+
+  const nowMs = Date.now();
+  const enabled = input.enabled !== false;
+  const deleteAfterRun = input.deleteAfterRun ?? (input.schedule.kind === 'at');
+
+  const job = {
+    id: crypto.randomUUID(),
+    name: input.name,
+    description: input.description || undefined,
+    enabled,
+    deleteAfterRun,
+    createdAtMs: nowMs,
+    updatedAtMs: nowMs,
+    schedule: { ...input.schedule },
+    sessionTarget: input.sessionTarget || 'isolated',
+    wakeMode: input.wakeMode || 'now',
+    payload: { ...input.payload },
+    delivery: input.delivery ? { ...input.delivery } : undefined,
+    state: {
+      nextRunAtMs: undefined,
+      runningAtMs: undefined,
+      lastRunAtMs: undefined,
+      lastStatus: undefined,
+      lastError: undefined,
+      lastDurationMs: undefined,
+      consecutiveErrors: 0,
+      scheduleErrorCount: 0,
+    },
+  };
+
+  // Compute initial next run
+  if (enabled) {
+    try {
+      job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+    } catch {
+      job.state.scheduleErrorCount = 1;
+    }
+  }
+
+  return job;
+}
+
+/**
+ * Apply an update patch to a job.
+ *
+ * @param {object} job - Existing job
+ * @param {object} patch - Fields to update
+ * @returns {object} Updated job (same reference, mutated)
+ */
+export function updateJob(job, patch) {
+  const nowMs = Date.now();
+
+  if (patch.name !== undefined) job.name = patch.name;
+  if (patch.description !== undefined) job.description = patch.description || undefined;
+  if (patch.deleteAfterRun !== undefined) job.deleteAfterRun = patch.deleteAfterRun;
+  if (patch.sessionTarget !== undefined) job.sessionTarget = patch.sessionTarget;
+  if (patch.wakeMode !== undefined) job.wakeMode = patch.wakeMode;
+  if (patch.payload !== undefined) job.payload = { ...patch.payload };
+  if (patch.delivery !== undefined) job.delivery = patch.delivery ? { ...patch.delivery } : undefined;
+
+  if (patch.schedule !== undefined) {
+    validateSchedule(patch.schedule);
+    job.schedule = { ...patch.schedule };
+    job.state.scheduleErrorCount = 0;
+    // Recompute next run
+    if (job.enabled) {
+      try {
+        job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+      } catch {
+        job.state.scheduleErrorCount = 1;
+      }
+    }
+  }
+
+  if (patch.enabled !== undefined) {
+    job.enabled = patch.enabled;
+    if (job.enabled && !job.state.nextRunAtMs) {
+      try {
+        job.state.nextRunAtMs = computeNextRunAtMs(job.schedule, nowMs);
+      } catch {
+        job.state.scheduleErrorCount++;
+      }
+    }
+    if (!job.enabled) {
+      job.state.nextRunAtMs = undefined;
+    }
+  }
+
+  job.updatedAtMs = nowMs;
+  return job;
+}
+
+/**
+ * Mark a job as started (running).
+ */
+export function markRunning(job) {
+  job.state.runningAtMs = Date.now();
+}
+
+/**
+ * Apply the result of a job execution.
+ *
+ * @param {object} job - The job
+ * @param {"ok"|"error"|"skipped"} status - Execution result
+ * @param {string} [error] - Error message if status is "error"
+ * @param {number} [durationMs] - Execution duration
+ */
+export function applyResult(job, status, error, durationMs) {
+  const nowMs = Date.now();
+
+  job.state.lastRunAtMs = job.state.runningAtMs || nowMs;
+  job.state.runningAtMs = undefined;
+  job.state.lastStatus = status;
+  job.state.lastError = status === 'error' ? error : undefined;
+  job.state.lastDurationMs = durationMs;
+
+  if (status === 'error') {
+    job.state.consecutiveErrors = (job.state.consecutiveErrors || 0) + 1;
+  } else {
+    job.state.consecutiveErrors = 0;
+  }
+
+  // One-shot jobs: disable after any terminal status
+  if (job.schedule.kind === 'at') {
+    job.enabled = false;
+    job.state.nextRunAtMs = undefined;
+    return;
+  }
+
+  // Recurring jobs: compute next run with backoff
+  if (job.enabled) {
+    try {
+      const normalNext = computeNextRunAtMs(job.schedule, nowMs);
+      if (normalNext === undefined) {
+        job.enabled = false;
+        job.state.nextRunAtMs = undefined;
+        return;
+      }
+
+      if (status === 'error' && job.state.consecutiveErrors > 0) {
+        const backoff = errorBackoffMs(job.state.consecutiveErrors);
+        job.state.nextRunAtMs = Math.max(normalNext, nowMs + backoff);
+      } else {
+        job.state.nextRunAtMs = normalNext;
+      }
+
+      job.state.scheduleErrorCount = 0;
+    } catch {
+      job.state.scheduleErrorCount = (job.state.scheduleErrorCount || 0) + 1;
+      // Auto-disable after 3 consecutive schedule computation errors
+      if (job.state.scheduleErrorCount >= 3) {
+        job.enabled = false;
+        job.state.nextRunAtMs = undefined;
+      }
+    }
+  }
+}
+
+/**
+ * Check if a job is due to run.
+ */
+export function isDue(job, nowMs) {
+  return job.enabled
+    && !job.state.runningAtMs
+    && job.state.nextRunAtMs !== undefined
+    && job.state.nextRunAtMs <= nowMs;
+}

package/src/locked.js

@@ -0,0 +1,34 @@
+/**
+ * Async locking mechanism to serialize state mutations.
+ * Prevents concurrent operations from corrupting job state.
+ */
+
+let chain = Promise.resolve();
+
+/**
+ * Execute a function with exclusive access to cron state.
+ * Operations queue behind each other — no concurrent mutations.
+ *
+ * @param {Function} fn - Async function to execute under lock
+ * @returns {Promise<*>} Result of fn
+ */
+export async function locked(fn) {
+  let resolve;
+  const prev = chain;
+  chain = new Promise(r => { resolve = r; });
+
+  await prev;
+
+  try {
+    return await fn();
+  } finally {
+    resolve();
+  }
+}
+
+/**
+ * Reset the lock chain. Only for testing.
+ */
+export function resetLock() {
+  chain = Promise.resolve();
+}

package/src/normalize.js

@@ -0,0 +1,163 @@
+/**
+ * Input normalization for AI-generated job definitions.
+ * Handles imperfect JSON from AI models: wrong casing, missing fields,
+ * flat-param recovery, type coercion.
+ */
+
+/**
+ * Normalize a schedule object. Infers kind from fields if missing.
+ */
+export function normalizeSchedule(raw) {
+  if (!raw || typeof raw !== 'object') return raw;
+
+  const schedule = { ...raw };
+
+  // Infer kind from fields if missing
+  if (!schedule.kind) {
+    if (schedule.at || schedule.atMs) schedule.kind = 'at';
+    else if (schedule.everyMs) schedule.kind = 'every';
+    else if (schedule.expr) schedule.kind = 'cron';
+  }
+
+  // Case normalization
+  if (typeof schedule.kind === 'string') {
+    schedule.kind = schedule.kind.toLowerCase();
+  }
+
+  // Legacy: atMs (number) → at (ISO string)
+  if (schedule.atMs && !schedule.at) {
+    schedule.at = new Date(schedule.atMs).toISOString();
+    delete schedule.atMs;
+  }
+
+  // Coerce string everyMs to number
+  if (typeof schedule.everyMs === 'string') {
+    schedule.everyMs = Number(schedule.everyMs);
+  }
+
+  return schedule;
+}
+
+/**
+ * Normalize a payload object. Infers kind from fields if missing.
+ */
+export function normalizePayload(raw) {
+  if (!raw || typeof raw !== 'object') return raw;
+
+  const payload = { ...raw };
+
+  // Infer kind from fields
+  if (!payload.kind) {
+    if (payload.message) payload.kind = 'agentTurn';
+    else if (payload.text) payload.kind = 'systemEvent';
+  }
+
+  // Case normalization
+  if (typeof payload.kind === 'string') {
+    const lower = payload.kind.toLowerCase();
+    if (lower === 'agentturn') payload.kind = 'agentTurn';
+    else if (lower === 'systemevent') payload.kind = 'systemEvent';
+  }
+
+  return payload;
+}
+
+/**
+ * Recover a job object from flat parameters.
+ * AI models sometimes flatten nested fields to the top level.
+ */
+const JOB_KEYS = new Set([
+  'name', 'description', 'schedule', 'sessionTarget', 'payload',
+  'delivery', 'enabled', 'deleteAfterRun', 'wakeMode',
+]);
+
+export function recoverFlatParams(params) {
+  if (params.job && typeof params.job === 'object' && Object.keys(params.job).length > 0) {
+    return params.job;
+  }
+
+  const synthetic = {};
+  for (const key of Object.keys(params)) {
+    if (JOB_KEYS.has(key)) {
+      synthetic[key] = params[key];
+    }
+  }
+
+  // message/text are not JOB_KEYS but need to be recovered for payload wrapping
+  const message = params.message;
+  const text = params.text;
+
+  if (synthetic.schedule || synthetic.payload || message || text) {
+    // If message/text are at top level, wrap into payload
+    if (!synthetic.payload) {
+      if (message) {
+        synthetic.payload = { kind: 'agentTurn', message };
+      } else if (text) {
+        synthetic.payload = { kind: 'systemEvent', text };
+      }
+    }
+    return synthetic;
+  }
+
+  return params;
+}
+
+/**
+ * Normalize a complete job input for creation.
+ * Applies all normalization: schedule, payload, defaults.
+ */
+export function normalizeJobInput(raw) {
+  const job = { ...raw };
+
+  if (job.schedule) {
+    job.schedule = normalizeSchedule(job.schedule);
+  }
+
+  if (job.payload) {
+    job.payload = normalizePayload(job.payload);
+  }
+
+  // Default: enabled
+  if (job.enabled === undefined) job.enabled = true;
+
+  // Default: wakeMode
+  if (!job.wakeMode) job.wakeMode = 'now';
+
+  // Default: sessionTarget inferred from payload
+  if (!job.sessionTarget && job.payload) {
+    job.sessionTarget = job.payload.kind === 'systemEvent' ? 'main' : 'isolated';
+  }
+
+  // Default: deleteAfterRun for one-shot
+  if (job.deleteAfterRun === undefined && job.schedule?.kind === 'at') {
+    job.deleteAfterRun = true;
+  }
+
+  // Default: delivery for isolated agentTurn
+  if (!job.delivery && job.sessionTarget === 'isolated' && job.payload?.kind === 'agentTurn') {
+    job.delivery = { mode: 'announce' };
+  }
+
+  // Auto-generate name if missing
+  if (!job.name) {
+    job.name = inferName(job);
+  }
+
+  return job;
+}
+
+/**
+ * Infer a job name from schedule and payload.
+ */
+function inferName(job) {
+  const parts = [];
+
+  if (job.schedule?.kind === 'at') parts.push('One-shot');
+  else if (job.schedule?.kind === 'every') parts.push('Recurring');
+  else if (job.schedule?.kind === 'cron') parts.push('Scheduled');
+
+  if (job.payload?.kind === 'agentTurn') parts.push('agent task');
+  else if (job.payload?.kind === 'systemEvent') parts.push('system event');
+
+  return parts.join(' ') || 'Unnamed job';
+}

package/src/run-log.js

@@ -0,0 +1,79 @@
+/**
+ * In-memory run log for job execution history.
+ * Stores recent execution results per job with auto-pruning.
+ *
+ * Persistence (via ORM) is added in PR 2.
+ */
+
+const DEFAULT_MAX_ENTRIES_PER_JOB = 100;
+
+export default class RunLog {
+  constructor(maxEntriesPerJob = DEFAULT_MAX_ENTRIES_PER_JOB) {
+    this.maxEntries = maxEntriesPerJob;
+    this.entries = new Map(); // jobId → RunLogEntry[]
+  }
+
+  /**
+   * Record a job execution result.
+   *
+   * @param {object} entry
+   * @param {string} entry.jobId
+   * @param {"ok"|"error"|"skipped"} entry.status
+   * @param {string} [entry.error]
+   * @param {string} [entry.summary]
+   * @param {number} [entry.runAtMs]
+   * @param {number} [entry.durationMs]
+   * @param {number} [entry.nextRunAtMs]
+   */
+  record(entry) {
+    const log = {
+      ts: Date.now(),
+      jobId: entry.jobId,
+      status: entry.status,
+      error: entry.error,
+      summary: entry.summary,
+      runAtMs: entry.runAtMs,
+      durationMs: entry.durationMs,
+      nextRunAtMs: entry.nextRunAtMs,
+    };
+
+    if (!this.entries.has(entry.jobId)) {
+      this.entries.set(entry.jobId, []);
+    }
+
+    const logs = this.entries.get(entry.jobId);
+    logs.push(log);
+
+    // Auto-prune
+    if (logs.length > this.maxEntries) {
+      logs.splice(0, logs.length - this.maxEntries);
+    }
+  }
+
+  /**
+   * Get run history for a job.
+   *
+   * @param {string} jobId
+   * @param {number} [limit=20]
+   * @returns {object[]} Most recent entries, newest first
+   */
+  get(jobId, limit = 20) {
+    const logs = this.entries.get(jobId);
+    if (!logs) return [];
+    return logs.slice(-limit).reverse();
+  }
+
+  /**
+   * Remove all entries for a job.
+   */
+  removeJob(jobId) {
+    this.entries.delete(jobId);
+  }
+
+  /**
+   * Clear all entries.
+   */
+  clear() {
+    this.entries.clear();
+  }
+}

package/src/schedule.js

@@ -0,0 +1,81 @@
+/**
+ * Schedule types and next-run computation.
+ *
+ * Three schedule kinds:
+ *   - "at": One-shot at an absolute ISO-8601 timestamp
+ *   - "every": Recurring interval in milliseconds
+ *   - "cron": 5-field cron expression with optional timezone
+ */
+import { nextOccurrence, validateCronExpression } from './cron-parser.js';
+
+/**
+ * Compute the next run time for a schedule.
+ *
+ * @param {object} schedule - Schedule definition
+ * @param {string} schedule.kind - "at" | "every" | "cron"
+ * @param {number} nowMs - Current time in milliseconds
+ * @returns {number|undefined} Next run time in ms, or undefined if no future occurrence
+ */
+export function computeNextRunAtMs(schedule, nowMs) {
+  if (schedule.kind === 'at') {
+    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+    if (!Number.isFinite(atMs)) return undefined;
+    return atMs > nowMs ? atMs : undefined;
+  }
+
+  if (schedule.kind === 'every') {
+    const everyMs = Math.max(1, Math.floor(schedule.everyMs));
+    const anchor = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
+
+    if (nowMs < anchor) return anchor;
+
+    const elapsed = nowMs - anchor;
+    const steps = Math.max(1, Math.floor((elapsed + everyMs - 1) / everyMs));
+    return anchor + steps * everyMs;
+  }
+
+  if (schedule.kind === 'cron') {
+    const tz = schedule.tz?.trim() || undefined;
+    // Round nowMs down to the current second to avoid sub-second drift
+    const nowSecondMs = Math.floor(nowMs / 1000) * 1000;
+    return nextOccurrence(schedule.expr.trim(), nowSecondMs, tz);
+  }
+
+  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}
+
+/**
+ * Validate a schedule definition.
+ * @param {object} schedule
+ * @throws {Error} if the schedule is invalid
+ */
+export function validateSchedule(schedule) {
+  if (!schedule || typeof schedule !== 'object') {
+    throw new Error('Schedule must be an object');
+  }
+
+  if (schedule.kind === 'at') {
+    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
+    if (!Number.isFinite(atMs)) {
+      throw new Error(`Invalid "at" timestamp: "${schedule.at}"`);
+    }
+    return;
+  }
+
+  if (schedule.kind === 'every') {
+    if (typeof schedule.everyMs !== 'number' || schedule.everyMs < 1) {
+      throw new Error(`"every" schedule requires everyMs >= 1, got: ${schedule.everyMs}`);
+    }
+    return;
+  }
+
+  if (schedule.kind === 'cron') {
+    if (typeof schedule.expr !== 'string' || !schedule.expr.trim()) {
+      throw new Error('"cron" schedule requires a non-empty expr string');
+    }
+    validateCronExpression(schedule.expr.trim());
+    return;
+  }
+
+  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
+}