aiden-runtime 4.0.2 → 4.1.0

package/dist/core/v4/cron/cronManager.js

@@ -0,0 +1,502 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/cron/cronManager.ts — Phase v4.1-cron
+ *
+ * Public scheduler API. Replaces the legacy `core/cronManager.ts`
+ * with the same exported function names so existing callers
+ * (cli/v4/commands/cron.ts) keep working.
+ *
+ * Architecture: state lives on disk (cron_jobs.json), in-memory
+ * cache + timers are this module's singleton state, refreshed
+ * by the heartbeat. All API calls acquire the file lock before
+ * mutating state — multi-process safety.
+ *
+ * Public surface (preserved from legacy):
+ *   - createJob(description, schedule, action) → CronJob
+ *   - listJobs() → CronJob[]
+ *   - getJob(id) → CronJob | undefined
+ *   - pauseJob(id, reason?) → boolean
+ *   - resumeJob(id) → boolean
+ *   - deleteJob(id) → boolean
+ *   - triggerJob(id) → Promise<boolean>
+ *   - parseSchedule(input) → ScheduleSpec  (re-exported)
+ *   - loadJobs() → void                    (idempotent boot)
+ *   - awaitPendingSaves() → Promise<void>  (test/shutdown)
+ *   - __resetForTests() → void
+ *
+ * New surface (additive):
+ *   - getDiagnostics() → CronDiagnostics
+ *   - startHeartbeat() / stopHeartbeat()
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHeartbeatActive = exports.stopHeartbeat = exports.AIDEN_CRON_BUILD = exports.parseSchedule = void 0;
+exports.setCronPathsForTests = setCronPathsForTests;
+exports.setRunActionForTests = setRunActionForTests;
+exports.loadJobs = loadJobs;
+exports.listJobs = listJobs;
+exports.listJobsAsync = listJobsAsync;
+exports.getJob = getJob;
+exports.getJobAsync = getJobAsync;
+exports.createJob = createJob;
+exports.createJobAsync = createJobAsync;
+exports.pauseJob = pauseJob;
+exports.resumeJob = resumeJob;
+exports.deleteJob = deleteJob;
+exports.triggerJob = triggerJob;
+exports.getDiagnostics = getDiagnostics;
+exports.getStateSnapshot = getStateSnapshot;
+exports.startHeartbeat = startHeartbeat;
+exports.awaitPendingSaves = awaitPendingSaves;
+exports.__resetForTests = __resetForTests;
+exports.__testPaths = __testPaths;
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const scheduleParser_1 = require("./scheduleParser");
+const cronState_1 = require("./cronState");
+const cronExecute_1 = require("./cronExecute");
+const cronTick_1 = require("./cronTick");
+Object.defineProperty(exports, "stopHeartbeat", { enumerable: true, get: function () { return cronTick_1.stopHeartbeat; } });
+Object.defineProperty(exports, "isHeartbeatActive", { enumerable: true, get: function () { return cronTick_1.isHeartbeatActive; } });
+const diagnostics_1 = require("./diagnostics");
+// ── Re-exports for backwards compat ──────────────────────────────────────
+var scheduleParser_2 = require("./scheduleParser");
+Object.defineProperty(exports, "parseSchedule", { enumerable: true, get: function () { return scheduleParser_2.parseSchedule; } });
+var diagnostics_2 = require("./diagnostics");
+Object.defineProperty(exports, "AIDEN_CRON_BUILD", { enumerable: true, get: function () { return diagnostics_2.AIDEN_CRON_BUILD; } });
+// ── State (in-memory cache + per-job timers) ─────────────────────────────
+const _timers = new Map();
+let _paths = (0, cronState_1.defaultCronPaths)();
+let _runAction = cronExecute_1.defaultRunAction;
+let _bootedPid = null;
+/** Override paths — for tests. */
+function setCronPathsForTests(paths) {
+    _paths = paths;
+}
+/** Override the action runner — for tests. */
+function setRunActionForTests(fn) {
+    _runAction = fn;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+function clearTimer(id) {
+    const h = _timers.get(id);
+    if (h) {
+        clearTimeout(h);
+        _timers.delete(id);
+    }
+}
+async function withLock(fn) {
+    const lock = await (0, cronState_1.acquireCronLock)(_paths, { failFast: false });
+    if (!lock) {
+        throw new Error('cron lock held by another process — try again');
+    }
+    try {
+        const state = await (0, cronState_1.readCronState)(_paths.stateFile);
+        return await fn(state);
+    }
+    finally {
+        await lock.release();
+    }
+}
+/** Re-arm a per-job setTimeout based on its current `nextRun`.
+ *  Cancels any existing timer first. */
+async function armJobTimer(job) {
+    clearTimer(job.id);
+    if (!job.enabled || job.state === 'paused' || job.state === 'completed')
+        return;
+    const { next } = await (0, cronExecute_1.computeNextFire)(job);
+    if (next === null)
+        return;
+    const delay = Math.max(0, next - Date.now());
+    const handle = setTimeout(() => {
+        _timers.delete(job.id);
+        void (0, cronExecute_1.fireJob)({
+            paths: _paths,
+            jobId: job.id,
+            runAction: _runAction,
+        }).then(async () => {
+            // After fire, re-arm based on the freshly persisted state.
+            const refreshed = await (0, cronState_1.readCronState)(_paths.stateFile);
+            const fresh = refreshed.jobs.find((j) => j.id === job.id);
+            if (fresh)
+                await armJobTimer(fresh);
+        }).catch(() => undefined);
+    }, delay);
+    if (typeof handle.unref === 'function')
+        handle.unref();
+    _timers.set(job.id, handle);
+}
+function genId(state) {
+    let max = 0;
+    for (const j of state.jobs) {
+        const n = Number.parseInt(j.id, 10);
+        if (Number.isFinite(n) && n > max)
+            max = n;
+    }
+    return String(max + 1);
+}
+// ── In-memory cache (sync read fallback for legacy callers) ─────────────
+/** Cache of last-read jobs. Refreshed by every async-public-API call
+ *  + the heartbeat. Sync wrappers below read from this — accepting
+ *  brief staleness in exchange for source-compat with v3 callers. */
+let _cache = [];
+function refreshCacheFromState(state) {
+    _cache = state.jobs;
+}
+// ── Public API ───────────────────────────────────────────────────────────
+/** Idempotent boot — call once at runtime startup. Loads state +
+ *  arms timers for every enabled job. Safe to call multiple times
+ *  (re-arms cleanly). */
+async function loadJobs() {
+    if (_bootedPid === process.pid)
+        return;
+    _bootedPid = process.pid;
+    const lock = await (0, cronState_1.acquireCronLock)(_paths, { failFast: false });
+    let state;
+    if (lock) {
+        try {
+            state = await (0, cronState_1.readCronState)(_paths.stateFile);
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    else {
+        // Lock held — best-effort read without lock. Persisters use
+        // atomicWrite so the read always sees a consistent file.
+        state = await (0, cronState_1.readCronState)(_paths.stateFile);
+    }
+    refreshCacheFromState(state);
+    for (const job of state.jobs) {
+        void armJobTimer(job);
+    }
+}
+/** SYNC list — reads from the in-memory cache populated by
+ *  loadJobs / heartbeat / API mutations. Backward-compat for
+ *  legacy callers (cli/v4/commands/cron.ts, core/toolRegistry.ts).
+ *  For up-to-the-millisecond accuracy use `listJobsAsync()`. */
+function listJobs() {
+    return [..._cache];
+}
+/** Async list — re-reads under lock. Preferred for new code. */
+async function listJobsAsync() {
+    const lock = await (0, cronState_1.acquireCronLock)(_paths, { failFast: false });
+    let state;
+    if (lock) {
+        try {
+            state = await (0, cronState_1.readCronState)(_paths.stateFile);
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    else {
+        state = await (0, cronState_1.readCronState)(_paths.stateFile);
+    }
+    refreshCacheFromState(state);
+    return state.jobs;
+}
+/** SYNC accessor — uses cache. */
+function getJob(id) {
+    return _cache.find((j) => j.id === id);
+}
+async function getJobAsync(id) {
+    const jobs = await listJobsAsync();
+    return jobs.find((j) => j.id === id);
+}
+/** SYNC create — returns the job object immediately. Persistence
+ *  happens in the background via `withLock`; legacy callers that
+ *  expected sync semantics keep working. The cache reflects the
+ *  new job before this returns. */
+function createJob(description, schedule, action) {
+    const spec = (0, scheduleParser_1.parseSchedule)(schedule);
+    // Compute id from in-memory cache.
+    let max = 0;
+    for (const j of _cache) {
+        const n = Number.parseInt(j.id, 10);
+        if (Number.isFinite(n) && n > max)
+            max = n;
+    }
+    const id = String(max + 1);
+    const createdAt = new Date().toISOString();
+    const job = {
+        id,
+        description,
+        schedule: spec.display,
+        kind: spec.kind,
+        action,
+        enabled: true,
+        state: 'scheduled',
+        pausedAt: null,
+        pausedReason: null,
+        createdAt,
+        lastError: null,
+        lastDeliveryError: null,
+        runCount: 0,
+        ...attachKindFields(spec),
+    };
+    // Update cache immediately — getJob right after createJob sees it.
+    _cache = [..._cache, job];
+    // Persist + arm timer in background.
+    void (async () => {
+        try {
+            await withLock(async (state) => {
+                // Re-genId in case another process added a job between now
+                // and the lock acquisition.
+                const idx = state.jobs.findIndex((j) => j.id === job.id);
+                if (idx === -1)
+                    state.jobs.push(job);
+                const { next } = await (0, cronExecute_1.computeNextFire)(job);
+                if (next !== null)
+                    job.nextRun = new Date(next).toISOString();
+                await (0, cronState_1.writeCronState)(_paths.stateFile, state);
+            });
+            void armJobTimer(job);
+        }
+        catch { /* persistence error — surface via logger only */ }
+    })();
+    return job;
+}
+/** Async variant — awaitable. */
+async function createJobAsync(description, schedule, action) {
+    const spec = (0, scheduleParser_1.parseSchedule)(schedule);
+    return withLock(async (state) => {
+        const id = genId(state);
+        const createdAt = new Date().toISOString();
+        const job = {
+            id,
+            description,
+            schedule: spec.display,
+            kind: spec.kind,
+            action,
+            enabled: true,
+            state: 'scheduled',
+            pausedAt: null,
+            pausedReason: null,
+            createdAt,
+            lastError: null,
+            lastDeliveryError: null,
+            runCount: 0,
+            ...attachKindFields(spec),
+        };
+        const { next } = await (0, cronExecute_1.computeNextFire)(job);
+        if (next !== null)
+            job.nextRun = new Date(next).toISOString();
+        state.jobs.push(job);
+        refreshCacheFromState(state);
+        await (0, cronState_1.writeCronState)(_paths.stateFile, state);
+        void armJobTimer(job);
+        return job;
+    });
+}
+function attachKindFields(spec) {
+    if (spec.kind === 'interval')
+        return { intervalMs: spec.intervalMs };
+    if (spec.kind === 'cron')
+        return { cronExpr: spec.cronExpr };
+    return { oneshotIso: spec.runAtIso };
+}
+/** SYNC pause — updates cache immediately, persists in background.
+ *  `reason` is the new optional second arg added by v4.1-cron
+ *  (legacy callers passing one arg still work). */
+function pauseJob(id, reason) {
+    const idx = _cache.findIndex((j) => j.id === id);
+    if (idx === -1)
+        return false;
+    const job = { ..._cache[idx] };
+    job.enabled = false;
+    job.state = 'paused';
+    job.pausedAt = new Date().toISOString();
+    job.pausedReason = reason ?? null;
+    _cache = [..._cache];
+    _cache[idx] = job;
+    clearTimer(id);
+    void (async () => {
+        try {
+            await withLock(async (state) => {
+                const sIdx = state.jobs.findIndex((j) => j.id === id);
+                if (sIdx === -1)
+                    return;
+                state.jobs[sIdx] = job;
+                await (0, cronState_1.writeCronState)(_paths.stateFile, state);
+            });
+        }
+        catch { /* surfaced via logger only */ }
+    })();
+    return true;
+}
+/** SYNC resume — recomputes nextRun from now. Hard-learned: don't
+ *  carry forward stale next_run after a long pause. */
+function resumeJob(id) {
+    const idx = _cache.findIndex((j) => j.id === id);
+    if (idx === -1)
+        return false;
+    const job = { ..._cache[idx] };
+    job.enabled = true;
+    job.state = 'scheduled';
+    job.pausedAt = null;
+    job.pausedReason = null;
+    _cache = [..._cache];
+    _cache[idx] = job;
+    void (async () => {
+        try {
+            const { next } = await (0, cronExecute_1.computeNextFire)(job);
+            if (next !== null)
+                job.nextRun = new Date(next).toISOString();
+            _cache[idx] = job;
+            await withLock(async (state) => {
+                const sIdx = state.jobs.findIndex((j) => j.id === id);
+                if (sIdx !== -1) {
+                    state.jobs[sIdx] = job;
+                    await (0, cronState_1.writeCronState)(_paths.stateFile, state);
+                }
+            });
+            await armJobTimer(job);
+        }
+        catch { /* surfaced via logger only */ }
+    })();
+    return true;
+}
+/** SYNC delete — removes from cache + clears timer immediately,
+ *  persists in background. */
+function deleteJob(id) {
+    const idx = _cache.findIndex((j) => j.id === id);
+    if (idx === -1)
+        return false;
+    _cache = _cache.filter((j) => j.id !== id);
+    clearTimer(id);
+    void (async () => {
+        try {
+            await withLock(async (state) => {
+                const sIdx = state.jobs.findIndex((j) => j.id === id);
+                if (sIdx !== -1) {
+                    state.jobs.splice(sIdx, 1);
+                    await (0, cronState_1.writeCronState)(_paths.stateFile, state);
+                }
+            });
+        }
+        catch { /* surfaced via logger only */ }
+    })();
+    return true;
+}
+async function triggerJob(id) {
+    // A trigger fires NOW, then the post-fire armJobTimer re-schedules.
+    const exists = await getJob(id);
+    if (!exists)
+        return false;
+    clearTimer(id);
+    await (0, cronExecute_1.fireJob)({
+        paths: _paths,
+        jobId: id,
+        runAction: _runAction,
+    });
+    const refreshed = await getJob(id);
+    if (refreshed && refreshed.enabled && refreshed.state === 'scheduled') {
+        await armJobTimer(refreshed);
+    }
+    return true;
+}
+// ── Diagnostics + heartbeat ──────────────────────────────────────────────
+async function getDiagnostics() {
+    const lockHeld = await (0, cronState_1.isCronLockHeld)(_paths);
+    return (0, diagnostics_1.getDiagnosticsSnapshot)({
+        lockPath: _paths.lockFile,
+        lockHeld,
+        schemaVersion: diagnostics_1.CRON_SCHEMA_VERSION,
+    });
+}
+async function getStateSnapshot() {
+    return (0, cronState_1.readCronState)(_paths.stateFile);
+}
+/** Start the heartbeat singleton with a default onTick that
+ *  re-arms changed timers. Idempotent. */
+function startHeartbeat() {
+    (0, cronTick_1.startHeartbeat)({
+        paths: _paths,
+        onTick: async (jobs) => {
+            for (const j of jobs) {
+                const armed = _timers.has(j.id);
+                const shouldArm = j.enabled
+                    && j.state !== 'paused'
+                    && j.state !== 'completed';
+                if (shouldArm && !armed) {
+                    await armJobTimer(j);
+                }
+                else if (!shouldArm && armed) {
+                    clearTimer(j.id);
+                }
+            }
+            // Drop timers for deleted jobs.
+            const live = new Set(jobs.map((j) => j.id));
+            for (const id of [..._timers.keys()]) {
+                if (!live.has(id))
+                    clearTimer(id);
+            }
+        },
+    });
+}
+// ── Drain hook ───────────────────────────────────────────────────────────
+/** Test/shutdown drain. */
+async function awaitPendingSaves() {
+    const { awaitAllPending } = await Promise.resolve().then(() => __importStar(require('./atomicWrite')));
+    await awaitAllPending();
+}
+// ── Test reset ───────────────────────────────────────────────────────────
+function __resetForTests() {
+    for (const id of [..._timers.keys()])
+        clearTimer(id);
+    _bootedPid = null;
+    _paths = (0, cronState_1.defaultCronPaths)();
+    _runAction = cronExecute_1.defaultRunAction;
+    (0, cronTick_1.stopHeartbeat)();
+}
+// Used by test bench to exercise the full path under a temp dir.
+function __testPaths(rootDir) {
+    return {
+        stateFile: node_path_1.default.join(rootDir, 'cron_jobs.json'),
+        lockFile: node_path_1.default.join(rootDir, 'cron_jobs.json.lock'),
+        logsDir: node_path_1.default.join(rootDir, 'cron-logs'),
+    };
+}
+void node_os_1.default; // import retained for future homedir-relative APIs