@spinabot/brigade 0.1.2 → 1.0.1

package/dist/cron/service/store.js

@@ -0,0 +1,350 @@
+/**
+ * On-disk persistence for the cron store.
+ *
+ * Single file at `~/.brigade/cron.json`. Atomic writes via tmp+rename so a
+ * crash mid-write can't leave the operator with a half-truncated store.
+ * Read is lenient: a missing file returns an empty store, a parse failure
+ * returns an empty store + logs a warning (the alternative — refusing to
+ * start — would brick the gateway daemon on a single corrupted byte).
+ *
+ * Schema version is hardcoded to 1 today; future-version files are accepted
+ * with a warning and downgraded to v1 semantics (we ignore fields we don't
+ * understand). Past-version migration will land alongside any v2 bump.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "../../config/paths.js";
+import { renameWithRetry } from "../../infra/fs/atomic-rename.js";
+import { createSubsystemLogger } from "../../logging/subsystem-logger.js";
+import { getCachedCronJobs, writeThroughCronCache } from "../../storage/cron-cache.js";
+import { tryGetRuntimeContext } from "../../storage/runtime-context.js";
+import { coerceScheduleInput, normalizeSchedule } from "../normalize.js";
+import { computeNextRunAtMs } from "../schedule.js";
+const log = createSubsystemLogger("cron/store");
+const CURRENT_STORE_VERSION = 1;
+export function loadCronStore(storePath) {
+    return loadCronStoreWithRepairFlag(storePath).store;
+}
+export function loadCronStoreWithRepairFlag(storePath) {
+    // Convex mode — serve from the boot-hydrated cache. Jobs run through the
+    // same schedule-repair pass as the disk path so a malformed row stored by
+    // an older build is healed identically in both modes.
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        const cached = getCachedCronJobs();
+        const jobs = [];
+        let repaired = false;
+        for (const raw of cached) {
+            if (!isMinimalJobShape(raw)) {
+                repaired = true;
+                continue;
+            }
+            const result = repairLoadedJobWithFlag(structuredClone(raw));
+            if (!result) {
+                repaired = true;
+                continue;
+            }
+            if (result.changed)
+                repaired = true;
+            jobs.push(result.job);
+        }
+        return { store: { version: CURRENT_STORE_VERSION, jobs }, repaired };
+    }
+    if (!fs.existsSync(storePath)) {
+        return { store: { version: CURRENT_STORE_VERSION, jobs: [] }, repaired: false };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(storePath, "utf8");
+    }
+    catch {
+        return { store: { version: CURRENT_STORE_VERSION, jobs: [] }, repaired: false };
+    }
+    if (!raw.trim()) {
+        return { store: { version: CURRENT_STORE_VERSION, jobs: [] }, repaired: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { store: { version: CURRENT_STORE_VERSION, jobs: [] }, repaired: false };
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return { store: { version: CURRENT_STORE_VERSION, jobs: [] }, repaired: false };
+    }
+    const candidate = parsed;
+    const rawJobs = Array.isArray(candidate.jobs) ? candidate.jobs : [];
+    const jobs = [];
+    let repaired = false;
+    for (const raw of rawJobs) {
+        if (!isMinimalJobShape(raw)) {
+            repaired = true; // drop = a change vs disk
+            continue;
+        }
+        // Repair on read: an older Brigade build (or an agent that called
+        // the tool with the wrong shape) may have persisted `schedule` as a
+        // bare string ("0 9 * * *") or an object missing `kind`. In that
+        // state `computeNextRunAtMs` returned undefined and the job NEVER
+        // fired. Run the stored schedule through `coerceScheduleInput` so
+        // the shape becomes canonical on the next save — and if the schedule
+        // truly can't be coerced (genuine corruption), drop the job with a
+        // log rather than poison the whole store.
+        const result = repairLoadedJobWithFlag(raw);
+        if (!result) {
+            repaired = true; // drop
+            continue;
+        }
+        if (result.changed)
+            repaired = true;
+        jobs.push(result.job);
+    }
+    // Version is normalized to CURRENT — unknown future fields on each job
+    // pass through (CronJob is `[key: string]: unknown`-friendly via the
+    // state field) so we don't blow away operator data on read.
+    return { store: { version: CURRENT_STORE_VERSION, jobs }, repaired };
+}
+/**
+ * Coerce a freshly-loaded job's schedule into the canonical shape (so an
+ * older bad-shape entry becomes executable) and recompute `nextRunAtMs`
+ * when the original was missing because the schedule had been unschedulable.
+ * Returns `null` if the schedule is genuinely uncoercible.
+ */
+function repairLoadedJob(job) {
+    const result = repairLoadedJobWithFlag(job);
+    return result ? result.job : null;
+}
+/**
+ * Value-compare a stored schedule against its canonical form. Reference
+ * inequality is useless here — `coerceScheduleInput` always allocates a fresh
+ * object, so `canonical !== job.schedule` was ALWAYS true, marking every job
+ * "repaired" on every load: `ensureLoaded` then recomputed nextRunAtMs (off
+ * real wall-clock, not the scheduler clock) and re-persisted on EVERY tick —
+ * spamming "canonicalised on load" and clobbering stored fire-times (incl.
+ * backoff + missed-replay slots). A by-value check makes an already-canonical
+ * load a true no-op. A string / kindless / shape-shifted original is treated
+ * as NOT equivalent, so genuine legacy repairs still fire.
+ */
+function schedulesEquivalent(original, canonical) {
+    if (!original || typeof original !== "object")
+        return false;
+    const o = original;
+    if (o.kind !== canonical.kind)
+        return false;
+    switch (canonical.kind) {
+        case "at":
+            return o.at === canonical.at;
+        case "every":
+            return o.everyMs === canonical.everyMs && o.anchorMs === canonical.anchorMs;
+        case "cron":
+            return (o.expr === canonical.expr &&
+                o.tz === canonical.tz &&
+                o.staggerMs === canonical.staggerMs);
+        default:
+            return false;
+    }
+}
+/**
+ * Repair variant that also reports whether the job changed shape vs disk —
+ * lets `loadCronStoreWithRepairFlag` decide to persist the canonical form
+ * ONCE so subsequent loads see no change and don't re-emit the "repaired"
+ * log line on every tick (Bug #10).
+ */
+function repairLoadedJobWithFlag(job) {
+    let canonical;
+    try {
+        canonical = normalizeSchedule(coerceScheduleInput(job.schedule));
+    }
+    catch (err) {
+        log.warn("dropping job with uncoercible schedule on load", {
+            id: job.id,
+            name: job.name,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+    // Migration: legacy `every` jobs created before anchors were persisted
+    // carry no `anchorMs`, so `computeNextRunAtMs` re-anchors to "now" on every
+    // recompute and the fire grid drifts forward on each restart (an hourly
+    // reminder kept sliding past its slot and never fired). Stamp a stable
+    // anchor from the job's creation time (falling back to its current
+    // next-fire) so the grid is fixed from here on — marks the schedule
+    // changed below, so nextRunAtMs is recomputed + persisted ONCE.
+    if (canonical.kind === "every" && canonical.anchorMs === undefined) {
+        const anchor = typeof job.createdAtMs === "number" ? job.createdAtMs : job.state?.nextRunAtMs;
+        if (typeof anchor === "number") {
+            canonical = { ...canonical, anchorMs: anchor };
+        }
+    }
+    const scheduleChanged = !schedulesEquivalent(job.schedule, canonical);
+    // Recompute nextRunAtMs if it's missing on an enabled job (this is the
+    // signature of an OLD build's failed compute) OR if we just changed the
+    // schedule shape (a new canonical may have a different fire-time).
+    const needsRecompute = (job.enabled && job.state?.nextRunAtMs === undefined) || scheduleChanged;
+    if (!scheduleChanged && !needsRecompute)
+        return { job, changed: false };
+    const now = Date.now();
+    let nextRunAtMs;
+    try {
+        nextRunAtMs = computeNextRunAtMs(canonical, now);
+    }
+    catch {
+        nextRunAtMs = undefined;
+    }
+    if (scheduleChanged) {
+        // Logged at debug — the canonical form is persisted by the caller on
+        // first repair, so subsequent loads observe a no-op repair. If the
+        // log ever returns on every tick, the persist-on-repair path
+        // downstream is broken.
+        log.debug("repaired job schedule on load (string/legacy → canonical object)", {
+            id: job.id,
+            name: job.name,
+            nextRunAtMs,
+        });
+    }
+    return {
+        job: {
+            ...job,
+            schedule: canonical,
+            state: {
+                ...(job.state ?? {}),
+                ...(nextRunAtMs !== undefined ? { nextRunAtMs } : {}),
+            },
+        },
+        changed: true,
+    };
+}
+/**
+ * Atomic write of the store. Hardening details:
+ *
+ *   1. tmp+rename so a crash mid-write can't leave a half-truncated file.
+ *   2. `0o600` perms on the tmp + final so an unprivileged process on a
+ *      shared box can't read the operator's cron schedules — schedules
+ *      can contain sensitive context (e.g. "ping me about acquisition
+ *      negotiation at 9am Monday") + downstream announce destinations.
+ *   3. `.bak` rotation: before overwriting an existing store, the previous
+ *      contents are copied to `<path>.bak`. A single backup is enough —
+ *      if the next write corrupts the file too, the operator has the
+ *      one-back state to recover from. Older `.bak.<N>` rotations would
+ *      blow up disk for marginal benefit.
+ *
+ * Backup is skipped on the first-ever write (no existing file) and on
+ * read-failure of the existing file (we don't want to write a broken
+ * backup over a previously-good one).
+ */
+export function saveCronStore(storePath, store) {
+    // Convex mode — prime the cache (next load sees this write) and enqueue
+    // the per-job mutations realising the diff. The cron service serialises
+    // its own saves, so the diff base is always the previous save's state.
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        writeThroughCronCache(rctx.store, store);
+        return;
+    }
+    ensureDir(path.dirname(storePath));
+    const tmp = `${storePath}.tmp`;
+    const bak = `${storePath}.bak`;
+    // Rotate the existing store to `.bak` BEFORE we overwrite. Best-effort
+    // — a missing source file (first-ever save) skips silently; a read /
+    // write error logs at warn but doesn't block the new write (we'd rather
+    // lose the backup than refuse the legitimate update).
+    if (fs.existsSync(storePath)) {
+        try {
+            fs.copyFileSync(storePath, bak);
+            try {
+                fs.chmodSync(bak, 0o600);
+            }
+            catch {
+                /* perm-set best-effort on platforms that don't support it */
+            }
+        }
+        catch (err) {
+            log.warn("cron store .bak rotation failed", {
+                path: bak,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Write tmp with 0o600 perms set at create-time when possible — fall
+    // back to a post-write chmod on platforms that don't honour the
+    // `mode` option (Windows). The rename inherits the tmp's mode.
+    fs.writeFileSync(tmp, JSON.stringify(store, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    try {
+        fs.chmodSync(tmp, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+    // `renameWithRetry` defends the Windows EPERM/EBUSY/EACCES window where
+    // antivirus / search-indexer / Defender briefly holds an open handle on
+    // the destination file as the tmp lands. Linux/macOS hit the success
+    // path on the first attempt.
+    renameWithRetry(tmp, storePath);
+}
+/** Persist the in-memory store under the per-instance lock. */
+export async function persist(state) {
+    saveCronStore(state.storePath, state.store);
+}
+/**
+ * Refresh `state.store` from disk. Called before every persist-write
+ * sequence so concurrent edits made by ANOTHER process (e.g., the operator
+ * running `brigade cron edit` while the daemon is also writing) don't get
+ * silently overwritten. Last-write-wins WITH a fresh read is the safety net.
+ *
+ * Persists the canonical form back to disk on the FIRST load that needs
+ * schedule repair (Bug #10). Without this, every subsequent tick reloaded
+ * the still-uncanonical disk file, re-emitted the "repaired job schedule
+ * on load" log line, and noise-saturated the operator's diagnostic
+ * stream. After the persist, the on-disk shape is canonical and future
+ * loads observe a no-op repair.
+ */
+export async function ensureLoaded(state) {
+    const result = loadCronStoreWithRepairFlag(state.storePath);
+    state.store = result.store;
+    if (result.repaired) {
+        try {
+            saveCronStore(state.storePath, state.store);
+            log.info("cron store canonicalised on load — subsequent loads will be silent", {
+                path: state.storePath,
+                jobCount: state.store.jobs.length,
+            });
+        }
+        catch (err) {
+            // A persist failure isn't fatal — the next persist on a normal
+            // mutation will eventually canonicalise. We just keep paying the
+            // repair cost on each load until it succeeds.
+            log.warn("cron store canonicalisation persist failed", {
+                path: state.storePath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+/**
+ * Minimal shape check — just enough to reject clearly-broken entries on
+ * load. Full validation lives in `assertSupportedJobSpec` (jobs.ts) and
+ * runs on EDIT, not on every restart. This is the "didn't get mangled by
+ * a half-write" check.
+ */
+function isMinimalJobShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    // `schedule` is accepted as either an object (canonical) OR a string
+    // (legacy / agent-passed bare cron expression). The `repairLoadedJob`
+    // pass downstream coerces strings to the canonical shape before the
+    // timer sees them; rejecting them here would drop user data, which is
+    // the bug we're trying to undo.
+    const scheduleOk = (typeof v.schedule === "object" && v.schedule !== null) ||
+        typeof v.schedule === "string";
+    return (typeof v.id === "string" &&
+        typeof v.name === "string" &&
+        typeof v.enabled === "boolean" &&
+        scheduleOk &&
+        typeof v.payload === "object" && v.payload !== null &&
+        typeof v.sessionTarget === "string");
+}
+//# sourceMappingURL=store.js.map

package/dist/cron/service/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/cron/service/store.ts"],"names":[],"mappings":"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"}

package/dist/cron/service/timer.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Scheduler tick loop + per-job execution dispatch.
+ *
+ * Three pieces work together here:
+ *
+ *   - **armTimer** — schedules the next `onTimer` call via `setTimeout`,
+ *     clamped at `MAX_TIMER_DELAY_MS` (60 s) so process suspend / wall-clock
+ *     skew can't leave us asleep past a missed fire. We use a fresh
+ *     `setTimeout` each tick (not `setInterval`) so the scheduling is
+ *     anchored to actual completion time, not nominal interval ticks.
+ *
+ *   - **onTimer** — the tick handler. Walks the job list, finds whatever's
+ *     due (or marginally past-due), spawns up to `maxConcurrentRuns`
+ *     parallel `runDueJob` calls, then rearms the timer to the next wake
+ *     time. A watchdog also rearms during long-running jobs so the timer
+ *     can't stay disarmed indefinitely.
+ *
+ *   - **runDueJob** — sets the `runningAtMs` marker, persists it, calls the
+ *     injected `runIsolatedAgentJob` (or `enqueueSystemEvent` for main-
+ *     session payloads), then applies the outcome via `applyJobResult`.
+ *     Emits `started` + `finished` events for every fire. Writes a run-log
+ *     entry on finish. Triggers failure-alert if the consecutive-error
+ *     count crosses the configured threshold.
+ *
+ * The startup catchup (`runMissedJobs`) is invoked separately by `ops.start`
+ * — it's a one-shot at-restart sweep, not part of the tick loop.
+ */
+import type { CronJob } from "../types.js";
+import type { CronServiceState } from "./state.js";
+/**
+ * Anti-drift clamp on the timer delay. This is ALSO the cron's own
+ * always-on heartbeat cadence: the scheduler wakes up at least every
+ * 30 seconds regardless of whether any agent has `heartbeat.intervalMs`
+ * configured. Cron MUST NOT depend on the agent heartbeat scheduler — if
+ * an operator runs Brigade with no heartbeat interval set, `wakeMode:
+ * "next-heartbeat"` system events would otherwise wait forever.
+ *
+ * Why 30 s (not 60 s): a 60-second worst-case for `wakeMode: "now"`
+ * crons feels laggy when the operator says "ping me in a minute".
+ * 30 s halves that perceived latency while keeping the timer cost
+ * negligible (one `setTimeout` per 30 s, no I/O on a quiet tick).
+ */
+export declare const MAX_TIMER_DELAY_MS = 30000;
+/** Spin-loop safety net — if the calculated delay rounds to 0, fall back to this. */
+export declare const MIN_REFIRE_GAP_MS = 2000;
+/** Compute the minimum next-fire across all enabled jobs. `undefined` = no work pending. */
+export declare function nextWakeAtMs(state: CronServiceState): number | undefined;
+/** Cancel any pending scheduler timer. Safe to call when no timer is armed. */
+export declare function stopTimer(state: CronServiceState): void;
+/**
+ * Schedule the next `onTimer` call. Idempotent — cancels any previous timer
+ * before scheduling the new one so multiple `armTimer` calls don't pile up.
+ *
+ * Cron owns its OWN tick — `setTimeout` driven, capped at
+ * `MAX_TIMER_DELAY_MS` (30 s). It is COMPLETELY INDEPENDENT of the agent
+ * heartbeat scheduler. Even if no agent has `heartbeat.intervalMs` set,
+ * the cron tick still fires every 30 s, drains pending wake intents, and
+ * picks up `wakeMode: "next-heartbeat"` system-event crons. Without this
+ * decoupling, an install with zero agent-heartbeat config would leave
+ * `next-heartbeat` crons stuck in the enqueue queue forever.
+ */
+export declare function armTimer(state: CronServiceState): void;
+/**
+ * One tick of the scheduler. Always re-arms before returning.
+ *
+ * Lifecycle: load fresh from disk → normalize every job's tick-state →
+ * collect runnables (within concurrency budget) → spawn them in parallel
+ * → wait for all → recompute next-fire → persist → rearm.
+ */
+export declare function onTimer(state: CronServiceState): Promise<void>;
+/**
+ * Resolve the effective max-concurrent-runs setting. Defaults to 4 so a
+ * burst of same-instant fires (a reminder + a "check status" cron sharing
+ * a 09:00 slot) all dispatch in parallel — the prior default of 1 caused
+ * losers to silently get pushed past their slot. Operators can still set
+ * `maxConcurrentRuns: 1` in `brigade.json` to opt back into single-file
+ * dispatch when their downstream provider can't handle parallel turns.
+ */
+export declare function resolveRunConcurrency(state: CronServiceState): number;
+/**
+ * Find every job whose next-fire has arrived. Does NOT cap by the
+ * concurrency limit — the caller (`onTimer`) spawns a worker pool keyed by
+ * the concurrency limit so losers stay sequenced inside the SAME tick
+ * (oldest-due-first) instead of being dropped past their slot. Capping
+ * here used to silently advance the loser's `nextRunAtMs` on the very
+ * next maintenance pass (Bug #2).
+ */
+export declare function collectRunnableJobs(state: CronServiceState, nowMs: number): CronJob[];
+/**
+ * Execute one job. Dispatches based on `sessionTarget`:
+ *   - `"main"` → enqueue system event (parent operator session sees it).
+ *   - other     → call `runIsolatedAgentJob` dep with the job spec.
+ *
+ * Outcome path:
+ *   - emit `started` event
+ *   - run + capture outcome
+ *   - apply outcome to job state (clears runningAtMs, sets nextRunAtMs +
+ *     backoff for transient errors, disables for permanent / one-shot ok)
+ *   - persist
+ *   - emit `finished` event
+ *   - append run-log entry
+ *   - maybe send failure-alert
+ *   - maybe delete one-shot
+ */
+export declare function runDueJob(state: CronServiceState, job: CronJob, runAtMs: number): Promise<void>;
+/**
+ * Bounded startup catchup. Called by `ops.start`. Find missed recurring jobs,
+ * cap at `maxMissedJobsPerRestart`, schedule them with staggered offsets.
+ * One-shot `at` jobs whose `runningAtMs` was set get the marker cleared
+ * (interrupted mid-run, can't re-fire — they're presumed done).
+ */
+export declare function planStartupCatchup(state: CronServiceState): Promise<void>;
+//# sourceMappingURL=timer.d.ts.map

package/dist/cron/service/timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.d.ts","sourceRoot":"","sources":["../../../src/cron/service/timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAoBH,OAAO,KAAK,EAEX,OAAO,EAGP,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAGX,gBAAgB,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAqDvC,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAUxE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAKvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CA4BtD;AAeD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6IpE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAIrE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CAarF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC9B,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmIf;AAifD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4F/E"}