@stonyx/cron 0.2.1-alpha.2 → 0.2.1-alpha.20

package/dist/main.js

@@ -0,0 +1,238 @@
+/*
+ * 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 './min-heap.js';
+/**
+ * Floor for a job interval, in whole seconds.
+ *
+ * `runDueJobs` no longer awaits the callback, so `next.nextTrigger > now` is the
+ * drain loop's only exit condition *and* the loop has no suspension point left.
+ * An interval that fails to advance `nextTrigger` therefore spins the loop
+ * forever and blocks the event loop, rather than merely scheduling too often.
+ */
+const MIN_INTERVAL_SECONDS = 1;
+/**
+ * Render an unknown thrown value as log text.
+ *
+ * `@stonyx/logs` reads a second argument as `logToFile`, not as a format
+ * argument, so `log.error(message, err)` discards the error entirely *and*
+ * forces a disk write on every failure. The error has to be interpolated into
+ * the message instead — the shape `CronService.executeJob` already uses.
+ */
+function describeError(err) {
+    if (err instanceof Error)
+        return err.stack ?? `${err.name}: ${err.message}`;
+    return String(err);
+}
+export default class Cron {
+    static instance;
+    jobs = {};
+    heap = new MinHeap();
+    timer = null;
+    constructor() {
+        if (Cron.instance)
+            return Cron.instance;
+        Cron.instance = this;
+    }
+    async init() {
+        // Self-register so log.cron works even when @stonyx/cron is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = '#888', logMethod = 'cron' } = config.cron ?? {};
+        log.defineType(logMethod, logColor);
+    }
+    scheduleNextRun() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        const { heap } = this;
+        if (heap.isEmpty())
+            return;
+        const nextJob = heap.peek();
+        if (!nextJob)
+            return;
+        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()) {
+            const next = heap.peek();
+            if (!next || next.nextTrigger > now)
+                break;
+            const job = heap.pop();
+            if (config.debug)
+                this.log('job has been triggered', job.key);
+            // Reschedule *before* invoking. The callback's result is not used by this
+            // class (`runDueJobs` returns void), so awaiting it bought nothing and
+            // cost the scheduler: a callback that never settled left the job absent
+            // from the heap and stopped the timer from ever re-arming.
+            this.setNextTrigger(job);
+            heap.push(job);
+            this.safeInvoke(job);
+        }
+        this.scheduleNextRun();
+    }
+    /**
+     * The one safe way this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections alike, and skips the invocation entirely when the job's previous
+     * invocation has not settled yet (fire-and-forget would otherwise let a slow
+     * job stack invocations on itself).
+     */
+    safeInvoke(job, runOnInit = false) {
+        const { key } = job;
+        const context = runOnInit ? 'failed on init:' : 'failed:';
+        // The in-flight guard lives on the job object, not in a module-level set
+        // keyed by string. That is what gives each invocation an identity: the only
+        // thing that ever clears the flag is the settle handler of the invocation
+        // that set it, and that handler closes over this exact job object. A stale
+        // handler therefore cannot release a *later* invocation's guard. It also
+        // matches the in-repo idiom one tier up (`job.state.runningAtMs`).
+        //
+        // `unregister` needs no explicit clear as a result: the flag is dropped with
+        // the job object, so a re-registered key gets a fresh object and runs
+        // immediately, while the abandoned invocation can only ever release itself.
+        if (job.runningAtMs !== undefined) {
+            // Bounded: one line per stuck run, not one per tick. A permanently hung
+            // job is re-pushed and re-skipped every interval forever, which at the
+            // 1s interval this class's own tests use is ~86k log lines a day, per job
+            // — a disk-fill and ingest-cost vector on any deployment capturing stdout.
+            if (!job.skipReported) {
+                job.skipReported = true;
+                const runningForSeconds = Math.max(0, Math.round((Date.now() - job.runningAtMs) / 1000));
+                this.report('warn', `Cron job ${JSON.stringify(key)} is still running after ${runningForSeconds}s; skipping this `
+                    + 'tick and any further ticks until it settles (this warning is not repeated for this run)');
+            }
+            return;
+        }
+        job.runningAtMs = Date.now();
+        job.skipReported = false;
+        try {
+            const result = job.callback();
+            if (result && typeof result.then === 'function') {
+                Promise.resolve(result)
+                    .catch((err) => {
+                    // Braces matter: returning `report`'s value would put it back into
+                    // the chain, and `.finally` passes a rejection straight through.
+                    this.report('error', `Cron job ${JSON.stringify(key)} ${context} ${describeError(err)}`);
+                })
+                    .finally(() => { this.release(job); })
+                    // Backstop: a throw inside the error handler or the release must not
+                    // re-create the unhandled rejection this helper exists to prevent.
+                    .catch(() => { });
+                return;
+            }
+            this.release(job);
+        }
+        catch (err) {
+            this.release(job);
+            this.report('error', `Cron job ${JSON.stringify(key)} ${context} ${describeError(err)}`);
+        }
+    }
+    /**
+     * Report a scheduler-level message without ever letting the logger's own
+     * failure reach the caller.
+     *
+     * `@stonyx/logs` convenience methods return a promise and write to disk
+     * through an unguarded `mkdirSync` + `fsp.appendFile`. On a read-only or full
+     * log volume that promise rejects; an unobserved rejection raised from inside
+     * the handler that exists to prevent unhandled rejections would re-create
+     * exactly the defect this class was fixed for (measured: exit code 1).
+     */
+    report(level, message) {
+        try {
+            const result = level === 'error' ? log.error(message) : log.warn(message);
+            void Promise.resolve(result).catch(() => { });
+        }
+        catch {
+            // Nowhere left to report to; the logger must never stop the scheduler.
+        }
+    }
+    /** Release a job's in-flight guard. Only ever called for the job it belongs to. */
+    release(job) {
+        job.runningAtMs = undefined;
+        job.skipReported = false;
+    }
+    register(key, callback, interval, runOnInit = false) {
+        const seconds = this.parseInterval(interval);
+        // Fail fast rather than clamp. An unparseable interval is a programming
+        // error with exactly one likely cause — a cron expression handed to the
+        // legacy class, which takes whole seconds — and clamping it would silently
+        // run a job intended for every 5 minutes once per second, hammering whatever
+        // the callback talks to. Throwing surfaces it at the call site, at boot,
+        // before anything is scheduled. A degenerate-but-parseable interval (`'0'`,
+        // `'-5'`) is a different case: it is interpretable as "as often as possible"
+        // and is clamped to the floor with one warning.
+        if (seconds === null) {
+            throw new TypeError(`Cron job ${JSON.stringify(key)} has an invalid interval ${JSON.stringify(interval)}: `
+                + 'expected whole seconds (e.g. \'30\'). The legacy Cron class does not accept cron '
+                + 'expressions — use CronService for those.');
+        }
+        if (parseInt(interval, 10) < MIN_INTERVAL_SECONDS) {
+            this.report('warn', `Cron job ${JSON.stringify(key)} interval ${JSON.stringify(interval)} is below the `
+                + `${MIN_INTERVAL_SECONDS}s floor; clamping to ${MIN_INTERVAL_SECONDS}s`);
+        }
+        const job = { callback, interval, key, nextTrigger: 0 };
+        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)
+            this.safeInvoke(job, true);
+        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();
+    }
+    /**
+     * Parse a job interval (whole seconds, as a string) into a positive integer.
+     *
+     * Returns `null` when the value cannot be parsed at all, so callers can choose
+     * between failing fast (`register`) and falling back (`setNextTrigger`).
+     */
+    parseInterval(interval) {
+        const seconds = parseInt(interval, 10);
+        if (!Number.isFinite(seconds))
+            return null;
+        return Math.max(MIN_INTERVAL_SECONDS, seconds);
+    }
+    setNextTrigger(job) {
+        // `register` rejects an unparseable interval up front; this floor is the
+        // backstop for a job object mutated after registration (`cron.jobs` is
+        // public, mutable state) and is what actually guarantees the drain loop
+        // terminates. Never let `nextTrigger` land on `NaN` or on `now`.
+        job.nextTrigger = getTimestamp() + (this.parseInterval(job.interval) ?? MIN_INTERVAL_SECONDS);
+    }
+    log(text, key = null) {
+        if (!config.cron?.log)
+            return;
+        const tag = key ? `Cron::${key}` : `Cron`;
+        log.cron(`${tag} - ${text}:`);
+    }
+}

package/dist/min-heap.d.ts

@@ -0,0 +1,13 @@
+export interface HeapItem {
+    nextTrigger: number;
+}
+export default class MinHeap<T extends HeapItem> {
+    items: T[];
+    push(job: T): void;
+    pop(): T | undefined;
+    peek(): T | undefined;
+    bubbleUp(): void;
+    bubbleDown(): void;
+    remove(job: T): void;
+    isEmpty(): boolean;
+}

package/dist/min-heap.js

@@ -0,0 +1,67 @@
+export default class MinHeap {
+    items = [];
+    push(job) {
+        this.items.push(job);
+        this.bubbleUp();
+    }
+    pop() {
+        if (this.items.length <= 1)
+            return this.items.pop();
+        const top = this.items[0];
+        const last = this.items.pop();
+        if (last === undefined)
+            return top;
+        this.items[0] = last;
+        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) {
+            const leftIdx = 2 * idx + 1;
+            const 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 (end === undefined)
+            return;
+        if (idx < this.items.length) {
+            this.items[idx] = end;
+            this.bubbleUp();
+            this.bubbleDown();
+        }
+    }
+    isEmpty() {
+        return this.items.length === 0;
+    }
+}

package/dist/normalize.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Input normalization for AI-generated job definitions.
+ * Handles imperfect JSON from AI models: wrong casing, missing fields,
+ * flat-param recovery, type coercion.
+ */
+interface RawSchedule {
+    kind?: string;
+    at?: string | number;
+    atMs?: number;
+    everyMs?: string | number;
+    expr?: string;
+    tz?: string;
+}
+interface RawPayload {
+    kind?: string;
+    message?: string;
+    text?: string;
+    [key: string]: unknown;
+}
+interface RawJobInput {
+    name?: string;
+    description?: string;
+    schedule?: RawSchedule;
+    payload?: RawPayload;
+    delivery?: Record<string, unknown>;
+    sessionTarget?: string;
+    wakeMode?: string;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    job?: RawJobInput;
+    message?: string;
+    text?: string;
+    [key: string]: unknown;
+}
+/**
+ * Normalize a schedule object. Infers kind from fields if missing.
+ */
+export declare function normalizeSchedule(raw: unknown): RawSchedule;
+/**
+ * Normalize a payload object. Infers kind from fields if missing.
+ */
+export declare function normalizePayload(raw: unknown): RawPayload;
+export declare function recoverFlatParams(params: RawJobInput): RawJobInput;
+/**
+ * Normalize a complete job input for creation.
+ * Applies all normalization: schedule, payload, defaults.
+ */
+export declare function normalizeJobInput(raw: RawJobInput): RawJobInput;
+export {};

package/dist/normalize.js

@@ -0,0 +1,148 @@
+/**
+ * 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/dist/run-log.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-memory run log for job execution history.
+ * Stores recent execution results per job with auto-pruning.
+ */
+export interface RunLogEntry {
+    ts: number;
+    jobId: string;
+    status: string;
+    error?: string;
+    summary?: string;
+    runAtMs?: number;
+    durationMs?: number;
+    nextRunAtMs?: number;
+}
+export interface RunLogInput {
+    jobId: string;
+    status: string;
+    error?: string;
+    summary?: string;
+    runAtMs?: number;
+    durationMs?: number;
+    nextRunAtMs?: number;
+}
+export default class RunLog {
+    maxEntries: number;
+    entries: Map<string, RunLogEntry[]>;
+    constructor(maxEntriesPerJob?: number);
+    /**
+     * Record a job execution result.
+     */
+    record(entry: RunLogInput): void;
+    /**
+     * Get run history for a job.
+     */
+    get(jobId: string, limit?: number): RunLogEntry[];
+    /**
+     * Remove all entries for a job.
+     */
+    removeJob(jobId: string): void;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+}

package/dist/run-log.js

@@ -0,0 +1,60 @@
+/**
+ * In-memory run log for job execution history.
+ * Stores recent execution results per job with auto-pruning.
+ */
+const DEFAULT_MAX_ENTRIES_PER_JOB = 100;
+export default class RunLog {
+    maxEntries;
+    entries;
+    constructor(maxEntriesPerJob = DEFAULT_MAX_ENTRIES_PER_JOB) {
+        this.maxEntries = maxEntriesPerJob;
+        this.entries = new Map();
+    }
+    /**
+     * Record a job execution result.
+     */
+    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);
+        if (!logs)
+            return;
+        logs.push(log);
+        // Auto-prune
+        if (logs.length > this.maxEntries) {
+            logs.splice(0, logs.length - this.maxEntries);
+        }
+    }
+    /**
+     * Get run history for a job.
+     */
+    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/dist/schedule.d.ts

@@ -0,0 +1,23 @@
+export interface AtSchedule {
+    kind: 'at';
+    at: string | number;
+}
+export interface EverySchedule {
+    kind: 'every';
+    everyMs: number;
+    anchorMs?: number;
+}
+export interface CronSchedule {
+    kind: 'cron';
+    expr: string;
+    tz?: string;
+}
+export type Schedule = AtSchedule | EverySchedule | CronSchedule;
+/**
+ * Compute the next run time for a schedule.
+ */
+export declare function computeNextRunAtMs(schedule: Schedule, nowMs: number): number | undefined;
+/**
+ * Validate a schedule definition.
+ */
+export declare function validateSchedule(schedule: Schedule): void;