operon-agents 0.1.0-alpha.0

package/dist/cron/extension.js

@@ -0,0 +1,141 @@
+import { CronManager } from "./manager.js";
+import { isValidCronTask } from "./persist.js";
+import { MAX_CRON_JOBS_PER_SESSION, cronCreateTool, cronDeleteTool, cronListTool } from "./tools.js";
+import { hasFireWithinYears, parseCronExpression } from "./cron-expr.js";
+const MAX_CRON_PROMPT_BYTES = 8 * 1024;
+const STATE_KEY = "registry";
+/** Host-path validation (the tools carry their own): trims/caps the input, refuses expressions
+ *  that never fire within 5 years, enforces the per-session job cap. */
+export function normalizeCronTaskInput(manager, input) {
+    const cron = input.cron.trim().split(/\s+/).join(" ");
+    const prompt = input.prompt;
+    if (cron.length === 0)
+        throw new Error("Cron expression cannot be empty.");
+    if (prompt.trim().length === 0)
+        throw new Error("Cron prompt cannot be empty.");
+    const promptBytes = Buffer.byteLength(prompt, "utf8");
+    if (promptBytes > MAX_CRON_PROMPT_BYTES) {
+        throw new Error(`Cron prompt exceeds ${MAX_CRON_PROMPT_BYTES} bytes (got ${promptBytes}).`);
+    }
+    if (manager.store.list().length >= MAX_CRON_JOBS_PER_SESSION) {
+        throw new Error(`Cron job cap reached (max ${MAX_CRON_JOBS_PER_SESSION} per session).`);
+    }
+    const parsed = parseCronExpression(cron);
+    if (!hasFireWithinYears(parsed, 5, manager.clocks.wallNow())) {
+        throw new Error(`Cron expression ${JSON.stringify(cron)} has no fire within 5 years; refusing to schedule.`);
+    }
+    return { ...input, cron };
+}
+export function cronExtension(options = {}) {
+    return {
+        id: "cron",
+        async setup(api) {
+            // One manager per session: setup runs per session open, so scheduling state is
+            // session-scoped exactly as the capability's openSession was.
+            const manager = new CronManager(options);
+            manager.attach({
+                steer: (prompt, metadata) => {
+                    const receipt = api.actions.steer(prompt, { metadata });
+                    return receipt === undefined ? undefined : { buffered: receipt.wakeTurnId === null };
+                },
+                emit: (name, data) => api.emitEvent(name, data),
+                isIdle: () => api.actions.isIdle(),
+                persistence: {
+                    load: async () => {
+                        const raw = await api.state.get(STATE_KEY);
+                        return Array.isArray(raw) ? raw.filter(isValidCronTask) : [];
+                    },
+                    save: (tasks) => api.state.set(STATE_KEY, tasks),
+                },
+            });
+            api.registerTool(cronCreateTool(manager));
+            api.registerTool(cronDeleteTool(manager));
+            api.registerTool(cronListTool(manager));
+            const handle = {
+                addTask: (input) => manager.addTask(normalizeCronTaskInput(manager, input)),
+                listTasks: () => manager.store.list(),
+                removeTask: (id) => manager.removeTasks([id]).length > 0,
+                tick: () => manager.tick(),
+                getNextFireTime: (taskId) => (taskId === undefined ? manager.getNextFireTime() : manager.getNextFireForTask(taskId)),
+            };
+            api.expose(handle);
+            api.registerCommand(cronCommand(handle));
+            await manager.loadPersisted();
+            manager.start();
+            return async () => {
+                await manager.stop();
+            };
+        },
+    };
+}
+/** `/cron` — behaviorally the command the core registry used to carry, now carried by the
+ *  extension itself: attached ⇒ the command exists, detached ⇒ it doesn't. */
+function cronCommand(handle) {
+    return {
+        name: "cron",
+        description: "Manage cron jobs (list | add <m h dom mon dow> <prompt> [--once] | remove <id> | tick | next [id]).",
+        run: (rawArgs) => {
+            const { head: sub, tail } = splitHead(rawArgs);
+            if (sub.length === 0 || sub === "list") {
+                const tasks = handle.listTasks();
+                return { ok: true, message: `${tasks.length} cron job(s).`, data: tasks };
+            }
+            if (sub === "add") {
+                const init = parseCronAdd(tail);
+                if (init === undefined)
+                    return { ok: false, message: "Usage: /cron add <m h dom mon dow> <prompt> [--once]" };
+                try {
+                    const task = handle.addTask(init);
+                    return { ok: true, message: `Scheduled cron job ${task.id} (${task.cron}).`, data: task };
+                }
+                catch (error) {
+                    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+                }
+            }
+            if (sub === "remove" || sub === "delete" || sub === "rm") {
+                const { head: id } = splitHead(tail);
+                if (id.length === 0)
+                    return { ok: false, message: `Usage: /cron ${sub} <id>` };
+                return handle.removeTask(id)
+                    ? { ok: true, message: `Removed cron job ${id}.` }
+                    : { ok: false, message: `No cron job "${id}".` };
+            }
+            if (sub === "tick") {
+                handle.tick();
+                return { ok: true, message: "Cron ticked.", data: { nextFireAt: handle.getNextFireTime() } };
+            }
+            if (sub === "next") {
+                const { head: id } = splitHead(tail);
+                const taskId = id.length > 0 ? id : undefined;
+                const nextFireAt = handle.getNextFireTime(taskId);
+                return {
+                    ok: true,
+                    message: nextFireAt === null ? "No upcoming cron fire." : `Next fire at ${nextFireAt}.`,
+                    data: { taskId: taskId ?? null, nextFireAt },
+                };
+            }
+            return { ok: false, message: `Unknown /cron action: ${sub}` };
+        },
+    };
+}
+function splitHead(input) {
+    const trimmed = input.trim();
+    const space = trimmed.search(/\s/);
+    return space === -1 ? { head: trimmed, tail: "" } : { head: trimmed.slice(0, space), tail: trimmed.slice(space + 1).trim() };
+}
+function parseCronAdd(input) {
+    let recurring = true;
+    const tokens = [];
+    for (const token of input.trim().split(/\s+/)) {
+        if (token.length === 0)
+            continue;
+        if (token === "--once")
+            recurring = false;
+        else
+            tokens.push(token);
+    }
+    if (tokens.length < 6)
+        return undefined; // 5 cron fields + at least one prompt token
+    return { cron: tokens.slice(0, 5).join(" "), prompt: tokens.slice(5).join(" "), recurring };
+}
+//# sourceMappingURL=extension.js.map

package/dist/cron/index.d.ts

@@ -0,0 +1,20 @@
+export { CronManager } from "./manager.ts";
+export type { CronManagerOptions, CronManagerRuntime } from "./manager.ts";
+export { CRON_ID_REGEX, isValidCronTask } from "./persist.ts";
+export type { CronPersistence } from "./persist.ts";
+export { SessionCronStore } from "./session-store.ts";
+export type { SessionCronTaskInit } from "./session-store.ts";
+export { createCronScheduler } from "./scheduler.ts";
+export type { CronScheduler, CronSchedulerOptions } from "./scheduler.ts";
+export { SYSTEM_CLOCKS, mutableClock } from "./clock.ts";
+export type { ClockSources, MutableClock } from "./clock.ts";
+export { parseCronExpression, computeNextCronRun, hasFireWithinYears, cronToHuman, } from "./cron-expr.ts";
+export type { ParsedCronExpression } from "./cron-expr.ts";
+export { jitteredNextCronRunMs, oneShotJitteredNextCronRunMs, DEFAULT_CRON_JITTER_CONFIG, } from "./jitter.ts";
+export type { JitterConfig } from "./jitter.ts";
+export { formatLocalIsoWithOffset } from "./time-format.ts";
+export { cronCreateTool, cronDeleteTool, cronListTool, MAX_CRON_JOBS_PER_SESSION } from "./tools.ts";
+export type { CronTask } from "./types.ts";
+export { cronExtension, normalizeCronTaskInput } from "./extension.ts";
+export type { CronHandle } from "./extension.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/cron/index.js

@@ -0,0 +1,11 @@
+export { CronManager } from "./manager.js";
+export { CRON_ID_REGEX, isValidCronTask } from "./persist.js";
+export { SessionCronStore } from "./session-store.js";
+export { createCronScheduler } from "./scheduler.js";
+export { SYSTEM_CLOCKS, mutableClock } from "./clock.js";
+export { parseCronExpression, computeNextCronRun, hasFireWithinYears, cronToHuman, } from "./cron-expr.js";
+export { jitteredNextCronRunMs, oneShotJitteredNextCronRunMs, DEFAULT_CRON_JITTER_CONFIG, } from "./jitter.js";
+export { formatLocalIsoWithOffset } from "./time-format.js";
+export { cronCreateTool, cronDeleteTool, cronListTool, MAX_CRON_JOBS_PER_SESSION } from "./tools.js";
+export { cronExtension, normalizeCronTaskInput } from "./extension.js";
+//# sourceMappingURL=index.js.map

package/dist/cron/jitter.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedCronExpression } from "./cron-expr.ts";
+export interface JitterConfig {
+    readonly recurringMaxFractionOfPeriod: number;
+    readonly recurringMaxMs: number;
+    readonly oneShotMaxMs: number;
+    readonly noJitter?: boolean;
+}
+export declare const DEFAULT_CRON_JITTER_CONFIG: JitterConfig;
+export declare function jitteredNextCronRunMs(task: {
+    id: string;
+    cron: string;
+    recurring?: boolean;
+}, parsed: ParsedCronExpression, idealMs: number, config?: JitterConfig): number;
+export declare function oneShotJitteredNextCronRunMs(task: {
+    id: string;
+    createdAt?: number | undefined;
+}, idealMs: number, config?: JitterConfig): number;
+//# sourceMappingURL=jitter.d.ts.map

package/dist/cron/jitter.js

@@ -0,0 +1,46 @@
+import { computeNextCronRun } from "./cron-expr.js";
+export const DEFAULT_CRON_JITTER_CONFIG = {
+    recurringMaxFractionOfPeriod: 0.1,
+    recurringMaxMs: 15 * 60_000,
+    oneShotMaxMs: 90_000,
+};
+const MS_PER_DAY = 24 * 60 * 60_000;
+const MS_PER_MINUTE = 60_000;
+function fractionFromId(id) {
+    if (/^[0-9a-f]{8}$/i.test(id)) {
+        const n = Number.parseInt(id, 16);
+        if (Number.isFinite(n))
+            return n / 0x1_0000_0000;
+    }
+    let hash = 5381;
+    for (let i = 0; i < id.length; i++)
+        hash = ((hash << 5) + hash + id.charCodeAt(i)) | 0;
+    return (hash >>> 0) / 0x1_0000_0000;
+}
+export function jitteredNextCronRunMs(task, parsed, idealMs, config = DEFAULT_CRON_JITTER_CONFIG) {
+    if (config.noJitter === true)
+        return idealMs;
+    const nextNext = computeNextCronRun(parsed, idealMs);
+    const period = nextNext !== null && nextNext > idealMs ? nextNext - idealMs : MS_PER_DAY;
+    const cap = Math.min(period * config.recurringMaxFractionOfPeriod, config.recurringMaxMs);
+    if (!(cap > 0))
+        return idealMs;
+    return idealMs + cap * fractionFromId(task.id);
+}
+export function oneShotJitteredNextCronRunMs(task, idealMs, config = DEFAULT_CRON_JITTER_CONFIG) {
+    if (config.noJitter === true)
+        return idealMs;
+    if (idealMs % MS_PER_MINUTE !== 0)
+        return idealMs;
+    const minuteOfHour = new Date(idealMs).getMinutes();
+    if (minuteOfHour !== 0 && minuteOfHour !== 30)
+        return idealMs;
+    if (!(config.oneShotMaxMs > 0))
+        return idealMs;
+    const shifted = idealMs + -config.oneShotMaxMs * fractionFromId(task.id);
+    // Insufficient budget: returning idealMs keeps the fire on schedule, never earlier.
+    if (task.createdAt !== undefined && shifted < task.createdAt)
+        return idealMs;
+    return shifted;
+}
+//# sourceMappingURL=jitter.js.map

package/dist/cron/manager.d.ts

@@ -0,0 +1,55 @@
+import { type ClockSources } from "./clock.ts";
+import type { JitterConfig } from "./jitter.ts";
+import type { CronPersistence } from "./persist.ts";
+import { SessionCronStore, type SessionCronTaskInit } from "./session-store.ts";
+import type { CronTask } from "./types.ts";
+export interface CronManagerOptions {
+    readonly clocks?: ClockSources;
+    readonly pollIntervalMs?: number | null;
+    readonly jitter?: JitterConfig;
+    readonly noStale?: boolean;
+    readonly isKilled?: () => boolean;
+}
+/**
+ * What the manager needs from its host, narrowed so both worlds can supply it: the cron
+ * EXTENSION wires these to `api.actions.steer` / `api.emitEvent` / `api.state`, and a test
+ * can hand in stubs. The manager never sees a steer bus, an event sink or a store.
+ */
+export interface CronManagerRuntime {
+    /** Deliver a fired task's prompt. `metadata` becomes the `<extension-message>` attributes.
+     *  Returns whether the message was buffered (no run woke for it), or undefined if delivery
+     *  was impossible. */
+    readonly steer?: (prompt: string, metadata: Readonly<Record<string, string | number | boolean>>) => {
+        readonly buffered: boolean;
+    } | undefined;
+    /** Ephemeral stream signal (e.g. "cron.fired"). */
+    readonly emit?: (name: string, data: Record<string, unknown>) => void;
+    /** Whether the session currently has no run in flight (scheduler poll gating). */
+    readonly isIdle?: () => boolean;
+    readonly persistence?: CronPersistence;
+}
+export declare class CronManager {
+    readonly store: SessionCronStore;
+    readonly clocks: ClockSources;
+    private readonly scheduler;
+    private readonly noStale;
+    private started;
+    private runtime;
+    private persistQueue;
+    constructor(options?: CronManagerOptions);
+    attach(runtime: CronManagerRuntime): void;
+    addTask(init: SessionCronTaskInit): CronTask;
+    removeTasks(ids: readonly string[]): readonly string[];
+    private advanceCursor;
+    loadPersisted(): Promise<void>;
+    private persistSnapshot;
+    flushPersist(): Promise<void>;
+    start(): void;
+    stop(): Promise<void>;
+    tick(): void;
+    getNextFireTime(): number | null;
+    getNextFireForTask(taskId: string): number | null;
+    isStale(task: CronTask): boolean;
+    private handleFire;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/cron/manager.js

@@ -0,0 +1,123 @@
+import { SYSTEM_CLOCKS } from "./clock.js";
+import { SessionCronStore } from "./session-store.js";
+import { createCronScheduler } from "./scheduler.js";
+const STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
+export class CronManager {
+    store;
+    clocks;
+    scheduler;
+    noStale;
+    started = false;
+    runtime = {};
+    persistQueue = Promise.resolve();
+    constructor(options = {}) {
+        this.store = new SessionCronStore();
+        this.clocks = options.clocks ?? SYSTEM_CLOCKS;
+        this.noStale = options.noStale ?? false;
+        this.scheduler = createCronScheduler({
+            clocks: this.clocks,
+            source: () => this.store.list(),
+            isIdle: () => this.runtime.isIdle?.() ?? true,
+            ...(options.isKilled !== undefined ? { isKilled: options.isKilled } : {}),
+            onFire: (task, ctx) => this.handleFire(task, ctx),
+            removeOneShot: (id) => {
+                this.removeTasks([id]);
+            },
+            onAdvanceCursor: (id, lastFiredAt) => this.advanceCursor(id, lastFiredAt),
+            ...(options.pollIntervalMs !== undefined ? { pollIntervalMs: options.pollIntervalMs } : {}),
+            ...(options.jitter !== undefined ? { jitter: options.jitter } : {}),
+        });
+    }
+    attach(runtime) {
+        this.runtime = runtime;
+    }
+    addTask(init) {
+        const task = this.store.add(init, this.clocks.wallNow());
+        this.persistSnapshot();
+        return task;
+    }
+    removeTasks(ids) {
+        const removed = this.store.remove(ids);
+        if (removed.length > 0)
+            this.persistSnapshot();
+        return removed;
+    }
+    advanceCursor(id, lastFiredAt) {
+        const updated = this.store.markFired(id, lastFiredAt);
+        if (updated === undefined)
+            return;
+        this.persistSnapshot();
+    }
+    async loadPersisted() {
+        if (this.runtime.persistence === undefined)
+            return;
+        const tasks = await this.runtime.persistence.load();
+        this.store.clear();
+        for (const task of tasks)
+            this.store.adopt(task);
+    }
+    // The registry is one state value written whole, so every mutation enqueues a save of the
+    // list as of that mutation; the chain serializes writes and the last one wins.
+    persistSnapshot() {
+        const persistence = this.runtime.persistence;
+        if (persistence === undefined)
+            return;
+        const tasks = [...this.store.list()];
+        this.persistQueue = this.persistQueue.catch(() => { }).then(() => persistence.save(tasks)).catch(() => { });
+    }
+    async flushPersist() {
+        await this.persistQueue.catch(() => { });
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.scheduler.start();
+    }
+    async stop() {
+        await this.scheduler.stop();
+        await this.flushPersist();
+        this.started = false;
+    }
+    tick() {
+        this.scheduler.tick();
+    }
+    getNextFireTime() {
+        return this.scheduler.getNextFireTime();
+    }
+    getNextFireForTask(taskId) {
+        return this.scheduler.getNextFireForTask(taskId);
+    }
+    isStale(task) {
+        if (this.noStale)
+            return false;
+        if (task.recurring === false)
+            return false;
+        const age = this.clocks.wallNow() - task.createdAt;
+        return Number.isFinite(age) && age >= STALE_THRESHOLD_MS;
+    }
+    handleFire(task, ctx) {
+        const stale = this.isStale(task);
+        const recurring = task.recurring !== false;
+        const receipt = this.runtime.steer?.(task.prompt, {
+            jobId: task.id,
+            cron: task.cron,
+            recurring,
+            coalescedCount: ctx.coalescedCount,
+            stale,
+        });
+        this.runtime.emit?.("cron.fired", {
+            jobId: task.id,
+            cron: task.cron,
+            recurring,
+            coalescedCount: ctx.coalescedCount,
+            stale,
+            prompt: task.prompt,
+            buffered: receipt === undefined || receipt.buffered,
+        });
+        // 7-day auto-expire: a stale recurring task gets one final delivery (above) then drops.
+        if (stale && recurring)
+            this.removeTasks([task.id]);
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/cron/persist.d.ts

@@ -0,0 +1,10 @@
+import type { CronTask } from "./types.ts";
+export declare const CRON_ID_REGEX: RegExp;
+export declare function isValidCronTask(obj: unknown): obj is CronTask;
+/** Where the registry snapshot lives. The extension supplies this over `api.state` (the
+ *  per-extension SessionStore KV) — one key, written whole, single writer (the session loop). */
+export interface CronPersistence {
+    load(): Promise<CronTask[]>;
+    save(tasks: readonly CronTask[]): Promise<void>;
+}
+//# sourceMappingURL=persist.d.ts.map

package/dist/cron/persist.js

@@ -0,0 +1,22 @@
+export const CRON_ID_REGEX = /^[0-9a-f]{8}$/;
+/** The whole cron registry lives under one state key (bounded by MAX_CRON_JOBS_PER_SESSION). */
+const CRON_STATE_KEY = "cron";
+export function isValidCronTask(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const o = obj;
+    if (typeof o["id"] !== "string" || !CRON_ID_REGEX.test(o["id"]))
+        return false;
+    if (typeof o["cron"] !== "string")
+        return false;
+    if (typeof o["prompt"] !== "string")
+        return false;
+    if (typeof o["createdAt"] !== "number")
+        return false;
+    if (o["recurring"] !== undefined && typeof o["recurring"] !== "boolean")
+        return false;
+    if (o["lastFiredAt"] !== undefined && (typeof o["lastFiredAt"] !== "number" || !Number.isFinite(o["lastFiredAt"])))
+        return false;
+    return true;
+}
+//# sourceMappingURL=persist.js.map

package/dist/cron/scheduler.d.ts

@@ -0,0 +1,25 @@
+import type { ClockSources } from "./clock.ts";
+import { type JitterConfig } from "./jitter.ts";
+import type { CronTask } from "./types.ts";
+export interface CronSchedulerOptions {
+    readonly clocks: ClockSources;
+    readonly source: () => readonly CronTask[];
+    readonly onFire: (task: CronTask, ctx: {
+        readonly coalescedCount: number;
+    }) => void;
+    readonly isIdle: () => boolean;
+    readonly isKilled?: () => boolean;
+    readonly removeOneShot?: (id: string) => void;
+    readonly onAdvanceCursor?: (taskId: string, lastFiredAt: number) => void;
+    readonly pollIntervalMs?: number | null;
+    readonly jitter?: JitterConfig;
+}
+export interface CronScheduler {
+    start(): void;
+    stop(): Promise<void>;
+    tick(): void;
+    getNextFireTime(): number | null;
+    getNextFireForTask(taskId: string): number | null;
+}
+export declare function createCronScheduler(opts: CronSchedulerOptions): CronScheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/cron/scheduler.js

@@ -0,0 +1,192 @@
+import { computeNextCronRun, parseCronExpression } from "./cron-expr.js";
+import { DEFAULT_CRON_JITTER_CONFIG, jitteredNextCronRunMs, oneShotJitteredNextCronRunMs } from "./jitter.js";
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const MAX_COALESCE_ITERATIONS = 10_000;
+export function createCronScheduler(opts) {
+    const { clocks, source, onFire, isIdle, isKilled, removeOneShot, onAdvanceCursor, pollIntervalMs } = opts;
+    const jitter = opts.jitter ?? DEFAULT_CRON_JITTER_CONFIG;
+    const parsedCache = new Map();
+    const lastSeenAt = new Map();
+    const seededFromDisk = new Set();
+    const inFlight = new Set();
+    let timerHandle = null;
+    function getParsed(expr) {
+        const cached = parsedCache.get(expr);
+        if (cached !== undefined)
+            return cached;
+        const parsed = parseCronExpression(expr);
+        parsedCache.set(expr, parsed);
+        return parsed;
+    }
+    function debugLog(message) {
+        if (process.env["AGENTS_CRON_DEBUG"] === "1")
+            process.stderr.write(`[cron/scheduler] ${message}\n`);
+    }
+    function computeJitteredNext(task, parsed, baseMs) {
+        const ideal = computeNextCronRun(parsed, baseMs);
+        if (ideal === null)
+            return null;
+        if (task.recurring === false)
+            return oneShotJitteredNextCronRunMs(task, ideal, jitter);
+        return jitteredNextCronRunMs(task, parsed, ideal, jitter);
+    }
+    function countCoalesced(task, parsed, firstFireMs, nowMs) {
+        let count = 1;
+        let cursor = firstFireMs;
+        let lastDueMs = firstFireMs;
+        while (count < MAX_COALESCE_ITERATIONS) {
+            const next = computeNextCronRun(parsed, cursor);
+            if (next === null)
+                break;
+            if (next > nowMs)
+                break;
+            const jitteredNext = task.recurring === false ? oneShotJitteredNextCronRunMs(task, next, jitter) : jitteredNextCronRunMs(task, parsed, next, jitter);
+            if (jitteredNext > nowMs)
+                break;
+            count++;
+            cursor = next;
+            lastDueMs = next;
+        }
+        return { count, lastDueMs };
+    }
+    function tick() {
+        if (isKilled?.() === true)
+            return;
+        if (!isIdle())
+            return;
+        const tasks = source();
+        if (tasks.length === 0)
+            return;
+        const now = clocks.wallNow();
+        try {
+            for (const task of tasks) {
+                try {
+                    if (inFlight.has(task.id))
+                        continue;
+                    const parsed = getParsed(task.cron);
+                    // Seed `lastSeenAt` from persisted `lastFiredAt` once per task (resume no-replay).
+                    if (!seededFromDisk.has(task.id) &&
+                        task.lastFiredAt !== undefined &&
+                        Number.isFinite(task.lastFiredAt) &&
+                        task.lastFiredAt <= now &&
+                        !lastSeenAt.has(task.id)) {
+                        lastSeenAt.set(task.id, task.lastFiredAt);
+                    }
+                    seededFromDisk.add(task.id);
+                    const seen = lastSeenAt.get(task.id);
+                    const baseFromMs = seen !== undefined && seen > task.createdAt ? seen : task.createdAt;
+                    const nextFireAt = computeJitteredNext(task, parsed, baseFromMs);
+                    if (nextFireAt === null)
+                        continue;
+                    if (now < nextFireAt)
+                        continue;
+                    const ideal = computeNextCronRun(parsed, baseFromMs);
+                    let coalescedCount = 1;
+                    let lastDueMs = null;
+                    if (task.recurring !== false && ideal !== null) {
+                        const result = countCoalesced(task, parsed, ideal, now);
+                        coalescedCount = Math.max(1, result.count);
+                        lastDueMs = result.lastDueMs;
+                    }
+                    inFlight.add(task.id);
+                    let delivered = false;
+                    try {
+                        onFire(task, { coalescedCount });
+                        delivered = true;
+                    }
+                    catch (error) {
+                        debugLog(`onFire threw for task ${task.id}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    if (!delivered)
+                        continue;
+                    if (task.recurring === false) {
+                        try {
+                            removeOneShot?.(task.id);
+                        }
+                        catch (error) {
+                            debugLog(`removeOneShot threw for task ${task.id}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                        lastSeenAt.delete(task.id);
+                        seededFromDisk.delete(task.id);
+                    }
+                    else {
+                        const advancedTo = lastDueMs ?? now;
+                        lastSeenAt.set(task.id, advancedTo);
+                        try {
+                            onAdvanceCursor?.(task.id, advancedTo);
+                        }
+                        catch (error) {
+                            debugLog(`onAdvanceCursor threw for task ${task.id}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    debugLog(`tick failed for task ${task.id}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        finally {
+            inFlight.clear();
+        }
+    }
+    function start() {
+        if (timerHandle !== null)
+            return;
+        const interval = pollIntervalMs === undefined ? DEFAULT_POLL_INTERVAL_MS : pollIntervalMs;
+        if (interval === null || interval === 0)
+            return; // no automatic polling
+        const handle = setInterval(tick, interval);
+        if (typeof handle === "object" && handle !== null && "unref" in handle) {
+            handle.unref();
+        }
+        timerHandle = handle;
+    }
+    async function stop() {
+        if (timerHandle !== null) {
+            clearInterval(timerHandle);
+            timerHandle = null;
+        }
+        inFlight.clear();
+        lastSeenAt.clear();
+        seededFromDisk.clear();
+        parsedCache.clear();
+    }
+    function nextFireFor(task) {
+        try {
+            const parsed = getParsed(task.cron);
+            const seen = lastSeenAt.get(task.id);
+            const persistedCursor = task.lastFiredAt !== undefined && Number.isFinite(task.lastFiredAt) && task.lastFiredAt <= clocks.wallNow()
+                ? task.lastFiredAt
+                : undefined;
+            const cursor = seen !== undefined ? seen : persistedCursor;
+            const baseFromMs = cursor !== undefined && cursor > task.createdAt ? cursor : task.createdAt;
+            return computeJitteredNext(task, parsed, baseFromMs);
+        }
+        catch (error) {
+            debugLog(`getNextFireFor skipping task ${task.id}: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    function getNextFireTime() {
+        const tasks = source();
+        if (tasks.length === 0)
+            return null;
+        let min = null;
+        for (const task of tasks) {
+            const next = nextFireFor(task);
+            if (next === null)
+                continue;
+            if (min === null || next < min)
+                min = next;
+        }
+        return min;
+    }
+    function getNextFireForTask(taskId) {
+        const task = source().find((t) => t.id === taskId);
+        if (task === undefined)
+            return null;
+        return nextFireFor(task);
+    }
+    return { start, stop, tick, getNextFireTime, getNextFireForTask };
+}
+//# sourceMappingURL=scheduler.js.map