@oka-core/reason 0.2.14 → 0.2.16

package/dist/cron-lock.js

@@ -0,0 +1,127 @@
+/**
+ * Scheduler lease lock for cron task files.
+ *
+ * When multiple processes share the same task directory, only one should
+ * drive the cron scheduler. Uses O_EXCL atomic create, PID liveness probe,
+ * and stale-lock recovery.
+ */
+import { mkdir, readFile, unlink, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+const LOCK_FILE_NAME = "scheduled_tasks.lock";
+function getLockPath(dir) {
+    return join(dir, LOCK_FILE_NAME);
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getErrnoCode(e) {
+    if (e && typeof e === "object" && "code" in e) {
+        return e.code;
+    }
+    return undefined;
+}
+async function readLock(dir) {
+    let raw;
+    try {
+        raw = await readFile(getLockPath(dir), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed.ownerId === "string" &&
+            typeof parsed.pid === "number" &&
+            typeof parsed.acquiredAt === "number") {
+            return parsed;
+        }
+    }
+    catch {
+        // Corrupt file
+    }
+    return undefined;
+}
+async function tryCreateExclusive(lock, dir) {
+    const path = getLockPath(dir);
+    const body = JSON.stringify(lock);
+    try {
+        await writeFile(path, body, { flag: "wx" });
+        return true;
+    }
+    catch (e) {
+        const code = getErrnoCode(e);
+        if (code === "EEXIST")
+            return false;
+        if (code === "ENOENT") {
+            await mkdir(dirname(path), { recursive: true });
+            try {
+                await writeFile(path, body, { flag: "wx" });
+                return true;
+            }
+            catch (retryErr) {
+                if (getErrnoCode(retryErr) === "EEXIST")
+                    return false;
+                throw retryErr;
+            }
+        }
+        throw e;
+    }
+}
+/**
+ * Try to acquire the scheduler lock.
+ *
+ * Returns true on success, false if another live process holds it.
+ *
+ * Uses O_EXCL for atomic test-and-set. If the file exists:
+ *   - Already ours → true (idempotent)
+ *   - Another live PID → false
+ *   - Stale (PID dead / corrupt) → unlink and retry once
+ */
+export async function tryAcquireSchedulerLock(opts) {
+    const { dir, ownerId } = opts;
+    const lock = {
+        ownerId,
+        pid: process.pid,
+        acquiredAt: Date.now(),
+    };
+    if (await tryCreateExclusive(lock, dir)) {
+        return true;
+    }
+    const existing = await readLock(dir);
+    // Already ours (idempotent). Update PID if changed (e.g. after resume).
+    if (existing?.ownerId === ownerId) {
+        if (existing.pid !== process.pid) {
+            await writeFile(getLockPath(dir), JSON.stringify(lock));
+        }
+        return true;
+    }
+    // Another live process holds it.
+    if (existing && isProcessRunning(existing.pid)) {
+        return false;
+    }
+    // Stale — unlink and retry exclusive create once.
+    await unlink(getLockPath(dir)).catch(() => { });
+    return tryCreateExclusive(lock, dir);
+}
+/**
+ * Release the scheduler lock if we own it.
+ */
+export async function releaseSchedulerLock(opts) {
+    const { dir, ownerId } = opts;
+    const existing = await readLock(dir);
+    if (!existing || existing.ownerId !== ownerId)
+        return;
+    try {
+        await unlink(getLockPath(dir));
+    }
+    catch {
+        // Already gone.
+    }
+}

package/dist/cron-scheduler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Polling-based cron scheduler.
+ *
+ * Simplified extraction from CC's cronScheduler — strips chokidar file watching
+ * (uses polling), bootstrap state, analytics, and session tasks. Designed for
+ * standalone use with file-backed cron tasks.
+ */
+import { type CronJitterConfig, type CronTask } from "./cron-tasks.js";
+/**
+ * True when a recurring task was created more than maxAgeMs ago.
+ * Permanent tasks never age. maxAgeMs === 0 means unlimited.
+ */
+export declare function isRecurringTaskAged(t: CronTask, nowMs: number, maxAgeMs: number): boolean;
+export type CronSchedulerOptions = {
+    /** Directory containing scheduled_tasks.json. */
+    dir: string;
+    /** Stable owner identity for the scheduler lock. */
+    ownerId: string;
+    /** Called when a task fires. */
+    onFire: (prompt: string) => void;
+    /** Called with the full CronTask on fire (bypasses onFire). */
+    onFireTask?: (task: CronTask) => void;
+    /** Called with missed one-shot tasks on initial load. */
+    onMissed?: (tasks: CronTask[]) => void;
+    /** Per-task gate: tasks returning false are invisible to this scheduler. */
+    filter?: (t: CronTask) => boolean;
+    /** Jitter config (defaults to DEFAULT_CRON_JITTER_CONFIG). */
+    jitterConfig?: CronJitterConfig;
+    /** Killswitch: polled each tick. When true, check() bails. */
+    isKilled?: () => boolean;
+    /** Check interval in ms (default: 1000). */
+    checkIntervalMs?: number;
+};
+export type CronScheduler = {
+    start: () => void;
+    stop: () => void;
+    /** Epoch ms of the soonest scheduled fire, or null if nothing pending. */
+    getNextFireTime: () => number | null;
+};
+export declare function createCronScheduler(options: CronSchedulerOptions): CronScheduler;
+//# sourceMappingURL=cron-scheduler.d.ts.map

package/dist/cron-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-scheduler.d.ts","sourceRoot":"","sources":["../src/cron-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EAUd,MAAM,iBAAiB,CAAC;AAMzB;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,QAAQ,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAKT;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,IAAI,CAAC;IACvC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC;IAClC,8DAA8D;IAC9D,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC;IACzB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACtC,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,aAAa,CAqMf"}

package/dist/cron-scheduler.js

@@ -0,0 +1,189 @@
+/**
+ * Polling-based cron scheduler.
+ *
+ * Simplified extraction from CC's cronScheduler — strips chokidar file watching
+ * (uses polling), bootstrap state, analytics, and session tasks. Designed for
+ * standalone use with file-backed cron tasks.
+ */
+import { DEFAULT_CRON_JITTER_CONFIG, buildMissedTaskNotification, findMissedTasks, jitteredNextCronRunMs, oneShotJitteredNextCronRunMs, readCronTasks, removeCronTasks, markCronTasksFired, } from "./cron-tasks.js";
+import { tryAcquireSchedulerLock, releaseSchedulerLock } from "./cron-lock.js";
+const CHECK_INTERVAL_MS = 1000;
+const LOCK_PROBE_INTERVAL_MS = 5000;
+/**
+ * True when a recurring task was created more than maxAgeMs ago.
+ * Permanent tasks never age. maxAgeMs === 0 means unlimited.
+ */
+export function isRecurringTaskAged(t, nowMs, maxAgeMs) {
+    if (maxAgeMs === 0)
+        return false;
+    return Boolean(t.recurring && !t.permanent && nowMs - t.createdAt >= maxAgeMs);
+}
+export function createCronScheduler(options) {
+    const { dir, ownerId, onFire, onFireTask, onMissed, filter, isKilled, checkIntervalMs = CHECK_INTERVAL_MS, } = options;
+    const jitterCfg = options.jitterConfig ?? DEFAULT_CRON_JITTER_CONFIG;
+    const lockOpts = { dir, ownerId };
+    let tasks = [];
+    const nextFireAt = new Map();
+    const missedAsked = new Set();
+    const inFlight = new Set();
+    let checkTimer = null;
+    let lockProbeTimer = null;
+    let stopped = false;
+    let isOwner = false;
+    async function load(initial) {
+        const next = await readCronTasks(dir);
+        if (stopped)
+            return;
+        tasks = next;
+        if (!initial)
+            return;
+        const now = Date.now();
+        const missed = findMissedTasks(next, now).filter((t) => !t.recurring && !missedAsked.has(t.id) && (!filter || filter(t)));
+        if (missed.length > 0) {
+            for (const t of missed) {
+                missedAsked.add(t.id);
+                nextFireAt.set(t.id, Infinity);
+            }
+            if (onMissed) {
+                onMissed(missed);
+            }
+            else {
+                onFire(buildMissedTaskNotification(missed));
+            }
+            void removeCronTasks(missed.map((t) => t.id), dir).catch(() => { });
+        }
+    }
+    function check() {
+        if (isKilled?.())
+            return;
+        if (!isOwner)
+            return;
+        const now = Date.now();
+        const seen = new Set();
+        const firedFileRecurring = [];
+        for (const t of tasks) {
+            if (filter && !filter(t))
+                continue;
+            seen.add(t.id);
+            if (inFlight.has(t.id))
+                continue;
+            let next = nextFireAt.get(t.id);
+            if (next === undefined) {
+                next = t.recurring
+                    ? (jitteredNextCronRunMs(t.cron, t.lastFiredAt ?? t.createdAt, t.id, jitterCfg) ?? Infinity)
+                    : (oneShotJitteredNextCronRunMs(t.cron, t.createdAt, t.id, jitterCfg) ?? Infinity);
+                nextFireAt.set(t.id, next);
+            }
+            if (now < next)
+                continue;
+            // Fire
+            if (onFireTask) {
+                onFireTask(t);
+            }
+            else {
+                onFire(t.prompt);
+            }
+            const aged = isRecurringTaskAged(t, now, jitterCfg.recurringMaxAgeMs);
+            if (t.recurring && !aged) {
+                const newNext = jitteredNextCronRunMs(t.cron, now, t.id, jitterCfg) ?? Infinity;
+                nextFireAt.set(t.id, newNext);
+                firedFileRecurring.push(t.id);
+            }
+            else {
+                // One-shot or aged-out recurring: delete
+                inFlight.add(t.id);
+                void removeCronTasks([t.id], dir)
+                    .catch(() => { })
+                    .finally(() => inFlight.delete(t.id));
+                nextFireAt.delete(t.id);
+            }
+        }
+        // Batch lastFiredAt write
+        if (firedFileRecurring.length > 0) {
+            for (const id of firedFileRecurring)
+                inFlight.add(id);
+            void markCronTasksFired(firedFileRecurring, now, dir)
+                .catch(() => { })
+                .finally(() => {
+                for (const id of firedFileRecurring)
+                    inFlight.delete(id);
+            });
+        }
+        if (seen.size === 0) {
+            nextFireAt.clear();
+            return;
+        }
+        for (const id of nextFireAt.keys()) {
+            if (!seen.has(id))
+                nextFireAt.delete(id);
+        }
+    }
+    async function enable() {
+        if (stopped)
+            return;
+        isOwner = await tryAcquireSchedulerLock(lockOpts).catch(() => false);
+        if (stopped) {
+            if (isOwner) {
+                isOwner = false;
+                void releaseSchedulerLock(lockOpts);
+            }
+            return;
+        }
+        if (!isOwner) {
+            lockProbeTimer = setInterval(() => {
+                void tryAcquireSchedulerLock(lockOpts)
+                    .then((owned) => {
+                    if (stopped) {
+                        if (owned)
+                            void releaseSchedulerLock(lockOpts);
+                        return;
+                    }
+                    if (owned) {
+                        isOwner = true;
+                        if (lockProbeTimer) {
+                            clearInterval(lockProbeTimer);
+                            lockProbeTimer = null;
+                        }
+                        // Load tasks now that we own the lock
+                        void load(true);
+                    }
+                })
+                    .catch(() => { });
+            }, LOCK_PROBE_INTERVAL_MS);
+            lockProbeTimer.unref?.();
+            return;
+        }
+        void load(true);
+        checkTimer = setInterval(check, checkIntervalMs);
+        checkTimer.unref?.();
+    }
+    return {
+        start() {
+            stopped = false;
+            void enable();
+        },
+        stop() {
+            stopped = true;
+            if (checkTimer) {
+                clearInterval(checkTimer);
+                checkTimer = null;
+            }
+            if (lockProbeTimer) {
+                clearInterval(lockProbeTimer);
+                lockProbeTimer = null;
+            }
+            if (isOwner) {
+                isOwner = false;
+                void releaseSchedulerLock(lockOpts);
+            }
+        },
+        getNextFireTime() {
+            let min = Infinity;
+            for (const t of nextFireAt.values()) {
+                if (t < min)
+                    min = t;
+            }
+            return min === Infinity ? null : min;
+        },
+    };
+}

package/dist/cron-tasks.d.ts

@@ -0,0 +1,86 @@
+/**
+ * File-backed cron task persistence.
+ *
+ * Tasks are stored in `<dir>/scheduled_tasks.json` with the shape:
+ *   { "tasks": [{ id, cron, prompt, createdAt, lastFiredAt?, recurring?, permanent? }] }
+ *
+ * Provides CRUD operations, next-run computation with jitter, and missed-task detection.
+ */
+export type CronTask = {
+    id: string;
+    /** 5-field cron string (local time). */
+    cron: string;
+    /** Prompt or payload to deliver when the task fires. */
+    prompt: string;
+    /** Epoch ms when the task was created. */
+    createdAt: number;
+    /** Epoch ms of the most recent fire (recurring tasks only). */
+    lastFiredAt?: number;
+    /** When true, reschedules after firing instead of being deleted. */
+    recurring?: boolean;
+    /** When true, exempt from recurringMaxAgeMs auto-expiry. */
+    permanent?: boolean;
+};
+/**
+ * Path to the cron tasks file within `dir`.
+ */
+export declare function getCronFilePath(dir: string): string;
+/**
+ * Read and parse scheduled_tasks.json. Returns empty list if missing or malformed.
+ * Tasks with invalid cron strings are silently dropped.
+ */
+export declare function readCronTasks(dir: string): Promise<CronTask[]>;
+/**
+ * Overwrite the tasks file. Creates parent directory if missing.
+ */
+export declare function writeCronTasks(tasks: CronTask[], dir: string): Promise<void>;
+/**
+ * Append a task. Returns the generated id.
+ */
+export declare function addCronTask(dir: string, cron: string, prompt: string, recurring: boolean): Promise<string>;
+/**
+ * Remove tasks by id. No-op if none match.
+ */
+export declare function removeCronTasks(ids: string[], dir: string): Promise<void>;
+/**
+ * Stamp `lastFiredAt` on the given recurring tasks and write back.
+ */
+export declare function markCronTasksFired(ids: string[], firedAt: number, dir: string): Promise<void>;
+/**
+ * Next fire time in epoch ms for a cron string, strictly after `fromMs`.
+ */
+export declare function nextCronRunMs(cron: string, fromMs: number): number | null;
+export type CronJitterConfig = {
+    /** Recurring forward delay as fraction of interval between fires. */
+    recurringFrac: number;
+    /** Upper bound on recurring forward delay. */
+    recurringCapMs: number;
+    /** One-shot backward lead: max ms a task may fire early. */
+    oneShotMaxMs: number;
+    /** One-shot backward lead: min ms to fire early. */
+    oneShotFloorMs: number;
+    /** Jitter fires on minutes where minute % N === 0. */
+    oneShotMinuteMod: number;
+    /** Recurring tasks auto-expire after this many ms (0 = unlimited). */
+    recurringMaxAgeMs: number;
+};
+export declare const DEFAULT_CRON_JITTER_CONFIG: CronJitterConfig;
+/**
+ * Next fire time for recurring tasks, with deterministic forward jitter
+ * proportional to the interval between fires.
+ */
+export declare function jitteredNextCronRunMs(cron: string, fromMs: number, taskId: string, cfg?: CronJitterConfig): number | null;
+/**
+ * Next fire time for one-shot tasks, with deterministic backward jitter
+ * on round minutes (mod oneShotMinuteMod).
+ */
+export declare function oneShotJitteredNextCronRunMs(cron: string, fromMs: number, taskId: string, cfg?: CronJitterConfig): number | null;
+/**
+ * Tasks whose next scheduled run (from createdAt) is in the past.
+ */
+export declare function findMissedTasks(tasks: CronTask[], nowMs: number): CronTask[];
+/**
+ * Build a notification message for missed tasks.
+ */
+export declare function buildMissedTaskNotification(missed: CronTask[]): string;
+//# sourceMappingURL=cron-tasks.d.ts.map

package/dist/cron-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-tasks.d.ts","sourceRoot":"","sources":["../src/cron-tasks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAMF;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA4CpE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,QAAQ,EAAE,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EAAE,EACb,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EAAE,EACb,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAaf;AAID;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKzE;AAID,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,gBAOxC,CAAC;AAUF;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,gBAA6C,GACjD,MAAM,GAAG,IAAI,CAUf;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,gBAA6C,GACjD,MAAM,GAAG,IAAI,CAQf;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAK5E;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAmBtE"}

package/dist/cron-tasks.js

@@ -0,0 +1,205 @@
+/**
+ * File-backed cron task persistence.
+ *
+ * Tasks are stored in `<dir>/scheduled_tasks.json` with the shape:
+ *   { "tasks": [{ id, cron, prompt, createdAt, lastFiredAt?, recurring?, permanent? }] }
+ *
+ * Provides CRUD operations, next-run computation with jitter, and missed-task detection.
+ */
+import { randomUUID } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { computeNextCronRun, cronToHuman, parseCronExpression, } from "./cron.js";
+const DEFAULT_FILE_NAME = "scheduled_tasks.json";
+/**
+ * Path to the cron tasks file within `dir`.
+ */
+export function getCronFilePath(dir) {
+    return join(dir, DEFAULT_FILE_NAME);
+}
+/**
+ * Read and parse scheduled_tasks.json. Returns empty list if missing or malformed.
+ * Tasks with invalid cron strings are silently dropped.
+ */
+export async function readCronTasks(dir) {
+    let raw;
+    try {
+        raw = await readFile(getCronFilePath(dir), { encoding: "utf-8" });
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    const file = parsed;
+    if (!Array.isArray(file.tasks))
+        return [];
+    const out = [];
+    for (const t of file.tasks) {
+        if (!t ||
+            typeof t.id !== "string" ||
+            typeof t.cron !== "string" ||
+            typeof t.prompt !== "string" ||
+            typeof t.createdAt !== "number") {
+            continue;
+        }
+        if (!parseCronExpression(t.cron))
+            continue;
+        out.push({
+            id: t.id,
+            cron: t.cron,
+            prompt: t.prompt,
+            createdAt: t.createdAt,
+            ...(typeof t.lastFiredAt === "number"
+                ? { lastFiredAt: t.lastFiredAt }
+                : {}),
+            ...(t.recurring ? { recurring: true } : {}),
+            ...(t.permanent ? { permanent: true } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Overwrite the tasks file. Creates parent directory if missing.
+ */
+export async function writeCronTasks(tasks, dir) {
+    await mkdir(dirname(getCronFilePath(dir)), { recursive: true });
+    const body = { tasks };
+    await writeFile(getCronFilePath(dir), JSON.stringify(body, null, 2) + "\n", "utf-8");
+}
+/**
+ * Append a task. Returns the generated id.
+ */
+export async function addCronTask(dir, cron, prompt, recurring) {
+    const id = randomUUID().slice(0, 8);
+    const task = {
+        id,
+        cron,
+        prompt,
+        createdAt: Date.now(),
+        ...(recurring ? { recurring: true } : {}),
+    };
+    const tasks = await readCronTasks(dir);
+    tasks.push(task);
+    await writeCronTasks(tasks, dir);
+    return id;
+}
+/**
+ * Remove tasks by id. No-op if none match.
+ */
+export async function removeCronTasks(ids, dir) {
+    if (ids.length === 0)
+        return;
+    const idSet = new Set(ids);
+    const tasks = await readCronTasks(dir);
+    const remaining = tasks.filter((t) => !idSet.has(t.id));
+    if (remaining.length === tasks.length)
+        return;
+    await writeCronTasks(remaining, dir);
+}
+/**
+ * Stamp `lastFiredAt` on the given recurring tasks and write back.
+ */
+export async function markCronTasksFired(ids, firedAt, dir) {
+    if (ids.length === 0)
+        return;
+    const idSet = new Set(ids);
+    const tasks = await readCronTasks(dir);
+    let changed = false;
+    for (const t of tasks) {
+        if (idSet.has(t.id)) {
+            t.lastFiredAt = firedAt;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return;
+    await writeCronTasks(tasks, dir);
+}
+// --- Next-run computation ---
+/**
+ * Next fire time in epoch ms for a cron string, strictly after `fromMs`.
+ */
+export function nextCronRunMs(cron, fromMs) {
+    const fields = parseCronExpression(cron);
+    if (!fields)
+        return null;
+    const next = computeNextCronRun(fields, new Date(fromMs));
+    return next ? next.getTime() : null;
+}
+export const DEFAULT_CRON_JITTER_CONFIG = {
+    recurringFrac: 0.1,
+    recurringCapMs: 15 * 60 * 1000,
+    oneShotMaxMs: 90 * 1000,
+    oneShotFloorMs: 0,
+    oneShotMinuteMod: 30,
+    recurringMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
+};
+/**
+ * Parse taskId (8-hex UUID slice) to a [0, 1) fraction for deterministic jitter.
+ */
+function jitterFrac(taskId) {
+    const frac = parseInt(taskId.slice(0, 8), 16) / 0x1_0000_0000;
+    return Number.isFinite(frac) ? frac : 0;
+}
+/**
+ * Next fire time for recurring tasks, with deterministic forward jitter
+ * proportional to the interval between fires.
+ */
+export function jitteredNextCronRunMs(cron, fromMs, taskId, cfg = DEFAULT_CRON_JITTER_CONFIG) {
+    const t1 = nextCronRunMs(cron, fromMs);
+    if (t1 === null)
+        return null;
+    const t2 = nextCronRunMs(cron, t1);
+    if (t2 === null)
+        return t1;
+    const jitter = Math.min(jitterFrac(taskId) * cfg.recurringFrac * (t2 - t1), cfg.recurringCapMs);
+    return t1 + jitter;
+}
+/**
+ * Next fire time for one-shot tasks, with deterministic backward jitter
+ * on round minutes (mod oneShotMinuteMod).
+ */
+export function oneShotJitteredNextCronRunMs(cron, fromMs, taskId, cfg = DEFAULT_CRON_JITTER_CONFIG) {
+    const t1 = nextCronRunMs(cron, fromMs);
+    if (t1 === null)
+        return null;
+    if (new Date(t1).getMinutes() % cfg.oneShotMinuteMod !== 0)
+        return t1;
+    const lead = cfg.oneShotFloorMs +
+        jitterFrac(taskId) * (cfg.oneShotMaxMs - cfg.oneShotFloorMs);
+    return Math.max(t1 - lead, fromMs);
+}
+/**
+ * Tasks whose next scheduled run (from createdAt) is in the past.
+ */
+export function findMissedTasks(tasks, nowMs) {
+    return tasks.filter((t) => {
+        const next = nextCronRunMs(t.cron, t.createdAt);
+        return next !== null && next < nowMs;
+    });
+}
+/**
+ * Build a notification message for missed tasks.
+ */
+export function buildMissedTaskNotification(missed) {
+    const plural = missed.length > 1;
+    const header = `The following one-shot scheduled task${plural ? "s were" : " was"} missed. ` +
+        `${plural ? "They have" : "It has"} been removed from the task file.\n\n` +
+        `Do NOT execute ${plural ? "these prompts" : "this prompt"} yet. ` +
+        `First confirm with the user whether to run ${plural ? "each one" : "it"} now.`;
+    const blocks = missed.map((t) => {
+        const meta = `[${cronToHuman(t.cron)}, created ${new Date(t.createdAt).toLocaleString()}]`;
+        const longestRun = (t.prompt.match(/`+/g) ?? []).reduce((max, run) => Math.max(max, run.length), 0);
+        const fence = "`".repeat(Math.max(3, longestRun + 1));
+        return `${meta}\n${fence}\n${t.prompt}\n${fence}`;
+    });
+    return `${header}\n\n${blocks.join("\n\n")}`;
+}

package/dist/cron.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Minimal 5-field cron expression parser and next-run calculator.
+ *
+ * Field syntax: wildcard (*), step ( * /N), range (N-M), range-step (N-M/S),
+ * list (N,M,...), plain value (N). Sunday alias: 7 → 0.
+ *
+ * All times are local timezone. DST-safe: spring-forward gaps are skipped,
+ * fall-back duplicates fire once (vixie-cron semantics).
+ */
+export type CronFields = {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+};
+/**
+ * Parse a 5-field cron expression into expanded number arrays.
+ * Returns null if invalid or unsupported syntax.
+ */
+export declare function parseCronExpression(expr: string): CronFields | null;
+/**
+ * Compute the next Date strictly after `from` that matches the cron fields.
+ * Uses local timezone. Walks forward minute-by-minute, bounded at 366 days.
+ *
+ * Standard cron: when both dayOfMonth and dayOfWeek are constrained
+ * (neither is the full range), a date matches if EITHER matches.
+ */
+export declare function computeNextCronRun(fields: CronFields, from: Date): Date | null;
+/**
+ * Convert a cron expression to a human-readable description.
+ * Covers common patterns; falls through to the raw string for complex ones.
+ */
+export declare function cronToHuman(cron: string): string;
+//# sourceMappingURL=cron.d.ts.map