@stonyx/cron 0.2.1-alpha.4 → 0.2.1-alpha.6

package/src/job.js

@@ -1,200 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-/**
- * 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/main.js

@@ -1,112 +0,0 @@
-/*
- * Copyright 2025 Stone Costa
- *
- * Licensed under the Apache License, Version 2.0 (the 'License');
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import { getTimestamp } from "@stonyx/utils/date";
-import MinHeap from '@stonyx/cron/min-heap';
-
-export default class Cron {
-  jobs = {};
-  heap = new MinHeap();
-  timer = null;
-
-  constructor() {
-    if (Cron.instance) return Cron.instance;
-    Cron.instance = this;
-  }
-
-  scheduleNextRun() {
-    clearTimeout(this.timer);
-
-    const { heap } = this;
-
-    if (heap.isEmpty()) return;
-
-    const nextJob = heap.peek();
-    const delay = Math.max(0, nextJob.nextTrigger - getTimestamp()) * 1000;
-
-    this.timer = setTimeout(() => this.runDueJobs(), delay);
-  }
-
-  async runDueJobs() {
-    const now = getTimestamp();
-    const { heap } = this;
-
-    while (!heap.isEmpty() && heap.peek().nextTrigger <= now) {
-      const job = heap.pop();
-
-      if (config.debug) this.log('job has been triggered', job.key);
-
-      try {
-        await job.callback();
-      } catch (err) {
-        log.error(`Cron job "${job.key}" failed:`, err);
-      }
-
-      this.setNextTrigger(job);
-      heap.push(job);
-    }
-
-    this.scheduleNextRun();
-  }
-
-  register(key, callback, interval, runOnInit=false) {
-    const job = { callback, interval, key };
-    this.jobs[key] = job;
-    this.setNextTrigger(job);
-    this.heap.push(job);
-
-    if (config.debug) {
-      this.log(`job has been registered with interval: ${interval}`, key);
-    }
-
-    if (runOnInit) {
-      try {
-        callback();
-      } catch (err) {
-        log.error(`Cron job "${key}" failed on init:`, err);
-      }
-    }
-
-    this.scheduleNextRun();
-  }
-
-  unregister(key) {
-    const { heap, jobs } = this;
-    const job = jobs[key];
-    
-    if (!job) return;
-
-    delete jobs[key];
-    heap.remove(job);
-
-    if (config.debug) this.log('job has been unregistered', key);
-
-    this.scheduleNextRun();
-  }
-
-  setNextTrigger(job) {
-    job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
-  }
-
-  log(text, key = null) {
-    if (!config.cron?.log) return;
-    
-    const tag = key ? `Cron::${key}` : `Cron`;
-    log.cron(`${tag} - ${text}:`);
-  }
-}

package/src/min-heap.js

@@ -1,73 +0,0 @@
-export default class MinHeap {
-  constructor() {
-    this.items = [];
-  }
-
-  push(job) {
-    this.items.push(job);
-    this.bubbleUp();
-  }
-
-  pop() {
-    if (this.items.length === 1) return this.items.pop();
-    const top = this.items[0];
-    this.items[0] = this.items.pop();
-    this.bubbleDown();
-    return top;
-  }
-
-  peek() {
-    return this.items[0];
-  }
-
-  bubbleUp() {
-    let idx = this.items.length - 1;
-    while (idx > 0) {
-      const parentIdx = Math.floor((idx - 1) / 2);
-      if (this.items[idx].nextTrigger >= this.items[parentIdx].nextTrigger) break;
-      [this.items[idx], this.items[parentIdx]] = [this.items[parentIdx], this.items[idx]];
-      idx = parentIdx;
-    }
-  }
-
-  bubbleDown() {
-    let idx = 0;
-    const length = this.items.length;
-
-    while (true) {
-      let leftIdx = 2 * idx + 1;
-      let rightIdx = 2 * idx + 2;
-      let swapIdx = null;
-
-      if (leftIdx < length && this.items[leftIdx].nextTrigger < this.items[idx].nextTrigger) {
-        swapIdx = leftIdx;
-      }
-      if (
-        rightIdx < length &&
-        this.items[rightIdx].nextTrigger < (
-          swapIdx === null ? this.items[idx].nextTrigger : this.items[leftIdx].nextTrigger
-        )
-      ) {
-        swapIdx = rightIdx;
-      }
-      if (swapIdx === null) break;
-      [this.items[idx], this.items[swapIdx]] = [this.items[swapIdx], this.items[idx]];
-      idx = swapIdx;
-    }
-  }
-
-  remove(job) {
-    const idx = this.items.indexOf(job);
-    if (idx === -1) return;
-    const end = this.items.pop();
-    if (idx < this.items.length) {
-      this.items[idx] = end;
-      this.bubbleUp();
-      this.bubbleDown();
-    }
-  }
-
-  isEmpty() {
-    return this.items.length === 0;
-  }
-}

package/src/normalize.js

@@ -1,163 +0,0 @@
-/**
- * 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

@@ -1,79 +0,0 @@
-/**
- * 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();
-  }
-}