@stonyx/cron 0.2.1-beta.12 → 0.2.1-beta.121

package/dist/main.js

@@ -0,0 +1,276 @@
+/*
+ * 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';
+/** Longest error text that may reach a log line. Anything past this is truncated. */
+const MAX_LOGGED_ERROR_LENGTH = 512;
+/**
+ * Flatten a value for interpolation into a single log line.
+ *
+ * `@stonyx/logs` writes `${timestamp} ${content}\n` to a newline-delimited
+ * file, so any `\r` or `\n` inside `content` ends the record early and
+ * everything after it is read back as a separate entry — including a forged
+ * `[timestamp] ...` prefix that is indistinguishable from a real one. Newlines
+ * become the literal two characters so the content survives for a reader, and
+ * the length cap keeps one pathological value from swamping the file.
+ *
+ * Kept byte-identical to the `forLog` landing in `src/service.ts` on #34: the
+ * two tiers render the same untrusted values into the same log file, and a
+ * reader diagnosing a forged record should not have to know which tier wrote
+ * it. Duplicated rather than shared because the two land on separate branches;
+ * folding them into one helper is a follow-up once both are on `dev`, not a
+ * cross-PR dependency that would make either unmergeable alone.
+ */
+function forLog(value, maxLength) {
+    const flattened = value.replace(/\r\n|[\r\n\u2028\u2029]/g, '\\n');
+    return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}...` : flattened;
+}
+/**
+ * Render an unknown thrown value as log text. Total by construction.
+ *
+ * `@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.
+ *
+ * Every read below touches a consumer-controlled value and can therefore throw:
+ * `instanceof` runs a proxy's `getPrototypeOf` trap, `stack`/`name`/`message`
+ * can be accessor properties, and `String(Object.create(null))` throws outright.
+ * This function runs *inside* `invokeJob`'s catch — the one place whose job is
+ * to stop a callback failure from reaching the scheduler — so a throw here
+ * escapes that catch and skips `scheduleNextRun()`, which is defect #36.
+ */
+function describeError(err) {
+    try {
+        if (err instanceof Error) {
+            return forLog(err.stack ?? `${err.name}: ${err.message}`, MAX_LOGGED_ERROR_LENGTH);
+        }
+        return forLog(String(err), MAX_LOGGED_ERROR_LENGTH);
+    }
+    catch {
+        // Deliberately not re-entrant: describing the failure to describe the error
+        // would be the same read that just threw.
+        return '<thrown value could not be rendered>';
+    }
+}
+/**
+ * Render a consumer-supplied job key safely for log output.
+ *
+ * Keys reach the log verbatim, so a key containing a newline can forge a
+ * complete, well-formed log line (`'a:\n[FORGED] Cron::admin - all jobs
+ * healthy'`). `JSON.stringify` quotes the value and escapes the control
+ * characters, which is also how the key is rendered one tier up.
+ */
+function describeKey(key) {
+    return JSON.stringify(key);
+}
+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;
+        // Terminal catch: `runDueJobs` is async, so anything that escapes it would
+        // otherwise become an unhandled rejection raised from a bare timer callback
+        // — the very failure mode this class was fixed for.
+        this.timer = setTimeout(() => {
+            this.runDueJobs().catch((err) => {
+                this.report('error', `Cron scheduler tick failed: ${describeError(err)}`);
+            });
+        }, delay);
+    }
+    async runDueJobs() {
+        const now = getTimestamp();
+        const { heap } = this;
+        // `finally`, not a trailing statement: `scheduleNextRun()` running on every
+        // exit from the drain loop is the invariant this whole fix is about. If
+        // anything in the loop body ever throws, the scheduler must still re-arm
+        // rather than stopping silently while `timer` still holds a fired handle.
+        try {
+            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: a consumer callback is never awaited here,
+                // so a callback that hangs or rejects can no longer starve the drain loop
+                // or leave the job orphaned outside the heap.
+                this.setNextTrigger(job);
+                heap.push(job);
+                this.invokeJob(job);
+            }
+        }
+        finally {
+            this.scheduleNextRun();
+        }
+    }
+    register(key, callback, interval, runOnInit = false) {
+        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);
+        }
+        // `finally`, not a trailing statement, for the same reason as `runDueJobs`:
+        // a job that is registered but never scheduled is defect #36's terminal
+        // state reached through the other entry point. `invokeJob` is total, so
+        // this guard should be unreachable — which is exactly why it is a guard and
+        // not an assumption.
+        try {
+            if (runOnInit)
+                this.invokeJob(job, true);
+        }
+        finally {
+            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();
+    }
+    /**
+     * The one place this class invokes a consumer callback.
+     *
+     * Never blocks the caller, catches synchronous throws and asynchronous
+     * rejections identically, and skips the invocation entirely while the job's
+     * previous invocation has not settled (fire-and-forget would otherwise let a
+     * slow job stack invocations on itself).
+     *
+     * Everything that touches the callback — including the thenable probe and the
+     * handler attachment — is inside the `try`. A callback may return an object
+     * whose `then` is a throwing getter, and reading it outside the guard would
+     * abort the drain loop before `scheduleNextRun()`, which is defect #36 again.
+     */
+    invokeJob(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. Object identity is invocation identity: the only thing
+        // that clears the guard is the settle handler of the invocation that set it,
+        // and that handler closes over this exact job object, so a stale handler can
+        // never release a later invocation's guard.
+        if (job.runningAtMs !== undefined) {
+            // Bounded to one line per stuck run, not one per tick. A permanently hung
+            // job is re-pushed and re-skipped every interval forever; at the 1s
+            // interval this class's own tests use that measures 43,200 lines/day per
+            // job — a disk-fill and ingest-cost vector whose natural operator response
+            // is to silence the only signal that the job is dead.
+            if (!job.skipReported) {
+                job.skipReported = true;
+                const runningForSeconds = Math.max(0, Math.round((Date.now() - job.runningAtMs) / 1000));
+                // Ungated, deliberately, matching the sibling `CronService` handler. A
+                // skipped run is a *lost* execution, and `runDueJobs`/`register` both
+                // return `void`, so this is the legacy class's only wedged-job channel.
+                // Routing it through `this.log` would put it behind `config.cron.log`,
+                // where a permanently dead job is indistinguishable from a healthy one.
+                this.report('warn', `Cron job ${describeKey(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 ${describeKey(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 ${describeKey(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.
+     */
+    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;
+    }
+    setNextTrigger(job) {
+        job.nextTrigger = getTimestamp() + parseInt(job.interval, 10);
+    }
+    log(text, key = null) {
+        if (!config.cron?.log)
+            return;
+        // The key is consumer-controlled and reaches the log verbatim. Strip the
+        // line terminators so a key cannot forge a second, well-formed log line;
+        // the surrounding format is unchanged.
+        const tag = key ? `Cron::${key.replace(/[\r\n]+/g, ' ')}` : `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;