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

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;

package/dist/schedule.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+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.
+ */
+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}"`);
+}

package/dist/service.d.ts

@@ -0,0 +1,125 @@
+import MinHeap, { type HeapItem } from './min-heap.js';
+import { type Job, type JobPatch } from './job.js';
+import RunLog from './run-log.js';
+interface HeapEntry extends HeapItem {
+    key: string;
+}
+interface JobDueResult {
+    status?: string;
+    error?: string;
+    summary?: string;
+}
+interface ExecuteResult {
+    status: string;
+    error?: string;
+    summary?: string;
+    durationMs?: number;
+    deleted?: boolean;
+    /** Only set when `status` is `'skipped'`. */
+    reason?: 'not due' | 'already running' | 'removed';
+}
+interface ServiceStatus {
+    started: boolean;
+    jobCount: number;
+    nextWakeAtMs: number | undefined;
+}
+interface ListOptions {
+    includeDisabled?: boolean;
+}
+type OnJobDueCallback = (job: Job) => Promise<JobDueResult | void> | JobDueResult | void;
+export default class CronService {
+    #private;
+    jobs: Map<string, Job>;
+    heap: MinHeap<HeapEntry>;
+    timer: ReturnType<typeof setTimeout> | null;
+    running: boolean;
+    runLog: RunLog;
+    started: boolean;
+    onJobDue: OnJobDueCallback | null;
+    constructor();
+    /**
+     * Start the service. Loads jobs from store (if any), arms timer.
+     */
+    start(initialJobs?: Job[]): Promise<void>;
+    /**
+     * Stop the service. Clears timer.
+     */
+    stop(): void;
+    /**
+     * Get service status.
+     */
+    status(): ServiceStatus;
+    /**
+     * List jobs, optionally including disabled ones.
+     */
+    list(opts?: ListOptions): Job[];
+    /**
+     * Get a single job by ID.
+     */
+    get(id: string): Job | null;
+    /**
+     * Add a new job. Input is normalized for AI compatibility.
+     */
+    add(rawInput: Record<string, unknown>): Promise<Job>;
+    /**
+     * Update an existing job.
+     */
+    update(id: string, patch: JobPatch): Promise<Job>;
+    /**
+     * Remove a job.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Manually trigger a job.
+     */
+    run(id: string, mode?: 'due' | 'force'): Promise<ExecuteResult>;
+    /**
+     * Get run history for a job.
+     */
+    runs(id: string, limit?: number): ReturnType<RunLog['get']>;
+    armTimer(): void;
+    onTimer(): Promise<void>;
+    findDueJobs(nowMs: number): Job[];
+    /**
+     * Execute a job in three phases:
+     *
+     *   1. claim  (locked)   - take ownership of the job, detach it from the heap
+     *   2. invoke (UNLOCKED) - await the consumer callback
+     *   3. settle (locked)   - apply the result, log it, re-insert into the heap
+     *
+     * The critical section deliberately excludes phase 2. `onJobDue` is
+     * arbitrary, unbounded consumer code; awaiting it under the module-global
+     * lock is what wedged every subsequent `locked()` call (add/update/remove)
+     * when a callback never settled.
+     *
+     * `onTimer` performs the batch claim (findDueJobs + markRunning) for all due
+     * jobs under a single lock, then enters at phase 2 via `#executeClaimed`.
+     * That entry point is a `#private` method rather than a parameter on this
+     * one: as a published `alreadyClaimed` boolean it was a supported way for a
+     * consumer to skip phase 1 entirely, which defeats the claim guard AC4 asks
+     * for and allows concurrent `onJobDue` invocations for the same job.
+     */
+    executeJob(job: Job): Promise<ExecuteResult>;
+    /**
+     * Phase 1 - claim. Must be called while holding the lock.
+     *
+     * Returns `null` on a successful claim, or the reason the claim was refused.
+     * "already running" is what makes a second `run()` report a skip instead of
+     * launching a concurrent invocation. "removed" covers the job being deleted
+     * between `run()`'s unlocked lookup and this lock turn - claiming then would
+     * `markRunning` an orphan and, worse, `removeFromHeap` an id that may now
+     * belong to a replacement.
+     *
+     * Detaching from the heap here (rather than relying on phase 3 to push a
+     * fresh entry) is what keeps manual runs from permanently duplicating heap
+     * entries.
+     */
+    claimJob(job: Job): 'already running' | 'removed' | null;
+    /**
+     * Phase 3 - settle. Must be called while holding the lock.
+     */
+    settleJob(job: Job, status: string, error: string | undefined, summary: string | undefined, startMs: number, durationMs: number): ExecuteResult;
+    removeFromHeap(id: string): void;
+    log(message: string): void;
+}
+export {};