@poolzin/pool-bot 2026.2.21 → 2026.2.23

package/dist/cron/service/timer.js

@@ -1,10 +1,18 @@
 import { DEFAULT_AGENT_ID } from "../../routing/session-key.js";
 import { resolveCronDeliveryPlan } from "../delivery.js";
 import { sweepCronRunSessions } from "../session-reaper.js";
-import { computeJobNextRunAtMs, nextWakeAtMs, recomputeNextRuns, resolveJobPayloadTextForMain, } from "./jobs.js";
+import { computeJobNextRunAtMs, nextWakeAtMs, recomputeNextRunsForMaintenance, resolveJobPayloadTextForMain, } from "./jobs.js";
 import { locked } from "./locked.js";
 import { ensureLoaded, persist } from "./store.js";
 const MAX_TIMER_DELAY_MS = 60_000;
+/**
+ * Minimum gap between consecutive fires of the same cron job.  This is a
+ * safety net that prevents spin-loops when `computeJobNextRunAtMs` returns
+ * a value within the same second as the just-completed run.  The guard
+ * is intentionally generous (2 s) so it never masks a legitimate schedule
+ * but always breaks an infinite re-trigger cycle.  (See #17821)
+ */
+const MIN_REFIRE_GAP_MS = 2_000;
 /**
  * Maximum wall-clock time for a single job execution. Acts as a safety net
  * on top of the per-provider / per-agent timeouts to prevent one stuck job
@@ -45,7 +53,7 @@ function applyJobResult(state, job, result) {
     else {
         job.state.consecutiveErrors = 0;
     }
-    const shouldDelete = job.schedule.kind === "at" && result.status === "ok" && job.deleteAfterRun === true;
+    const shouldDelete = job.schedule.kind === "at" && job.deleteAfterRun === true && result.status === "ok";
     if (!shouldDelete) {
         if (job.schedule.kind === "at") {
             // One-shot jobs are always disabled after ANY terminal status
@@ -78,7 +86,19 @@ function applyJobResult(state, job, result) {
             }, "cron: applying error backoff");
         }
         else if (job.enabled) {
-            job.state.nextRunAtMs = computeJobNextRunAtMs(job, result.endedAt);
+            const naturalNext = computeJobNextRunAtMs(job, result.endedAt);
+            if (job.schedule.kind === "cron") {
+                // Safety net: ensure the next fire is at least MIN_REFIRE_GAP_MS
+                // after the current run ended.  Prevents spin-loops when the
+                // schedule computation lands in the same second due to
+                // timezone/croner edge cases (see #17821).
+                const minNext = result.endedAt + MIN_REFIRE_GAP_MS;
+                job.state.nextRunAtMs =
+                    naturalNext !== undefined ? Math.max(naturalNext, minNext) : minNext;
+            }
+            else {
+                job.state.nextRunAtMs = naturalNext;
+            }
         }
         else {
             job.state.nextRunAtMs = undefined;
@@ -109,18 +129,36 @@ export function armTimer(state) {
     // Wake at least once a minute to avoid schedule drift and recover quickly
     // when the process was paused or wall-clock time jumps.
     const clampedDelay = Math.min(delay, MAX_TIMER_DELAY_MS);
-    state.timer = setTimeout(async () => {
-        try {
-            await onTimer(state);
-        }
-        catch (err) {
+    // Intentionally avoid an `async` timer callback:
+    // Vitest's fake-timer helpers can await async callbacks, which would block
+    // tests that simulate long-running jobs. Runtime behavior is unchanged.
+    state.timer = setTimeout(() => {
+        void onTimer(state).catch((err) => {
             state.deps.log.error({ err: String(err) }, "cron: timer tick failed");
-        }
+        });
     }, clampedDelay);
     state.deps.log.debug({ nextAt, delayMs: clampedDelay, clamped: delay > MAX_TIMER_DELAY_MS }, "cron: timer armed");
 }
 export async function onTimer(state) {
     if (state.running) {
+        // Re-arm the timer so the scheduler keeps ticking even when a job is
+        // still executing.  Without this, a long-running job (e.g. an agentTurn
+        // exceeding MAX_TIMER_DELAY_MS) causes the clamped 60 s timer to fire
+        // while `running` is true.  The early return then leaves no timer set,
+        // silently killing the scheduler until the next gateway restart.
+        //
+        // We use MAX_TIMER_DELAY_MS as a fixed re-check interval to avoid a
+        // zero-delay hot-loop when past-due jobs are waiting for the current
+        // execution to finish.
+        // See: https://github.com/poolbot/poolbot/issues/12025
+        if (state.timer) {
+            clearTimeout(state.timer);
+        }
+        state.timer = setTimeout(() => {
+            void onTimer(state).catch((err) => {
+                state.deps.log.error({ err: String(err) }, "cron: timer tick failed");
+            });
+        }, MAX_TIMER_DELAY_MS);
         return;
     }
     state.running = true;
@@ -129,7 +167,10 @@ export async function onTimer(state) {
             await ensureLoaded(state, { forceReload: true, skipRecompute: true });
             const due = findDueJobs(state);
             if (due.length === 0) {
-                const changed = recomputeNextRuns(state);
+                // Use maintenance-only recompute to avoid advancing past-due nextRunAtMs
+                // values without execution. This prevents jobs from being silently skipped
+                // when the timer wakes up but findDueJobs returns empty (see #13992).
+                const changed = recomputeNextRunsForMaintenance(state);
                 if (changed) {
                     await persist(state);
                 }
@@ -151,21 +192,37 @@ export async function onTimer(state) {
             const startedAt = state.deps.nowMs();
             job.state.runningAtMs = startedAt;
             emit(state, { jobId: job.id, action: "started", runAtMs: startedAt });
-            const jobTimeoutMs = job.payload.kind === "agentTurn" && typeof job.payload.timeoutSeconds === "number"
-                ? job.payload.timeoutSeconds * 1_000
+            const configuredTimeoutMs = job.payload.kind === "agentTurn" && typeof job.payload.timeoutSeconds === "number"
+                ? Math.floor(job.payload.timeoutSeconds * 1_000)
+                : undefined;
+            const jobTimeoutMs = configuredTimeoutMs !== undefined
+                ? configuredTimeoutMs <= 0
+                    ? undefined
+                    : configuredTimeoutMs
                 : DEFAULT_JOB_TIMEOUT_MS;
             try {
-                let timeoutId;
-                const result = await Promise.race([
-                    executeJobCore(state, job),
-                    new Promise((_, reject) => {
-                        timeoutId = setTimeout(() => reject(new Error("cron: job execution timed out")), jobTimeoutMs);
-                    }),
-                ]).finally(() => clearTimeout(timeoutId));
+                const result = typeof jobTimeoutMs === "number"
+                    ? await (async () => {
+                        let timeoutId;
+                        try {
+                            return await Promise.race([
+                                executeJobCore(state, job),
+                                new Promise((_, reject) => {
+                                    timeoutId = setTimeout(() => reject(new Error("cron: job execution timed out")), jobTimeoutMs);
+                                }),
+                            ]);
+                        }
+                        finally {
+                            if (timeoutId) {
+                                clearTimeout(timeoutId);
+                            }
+                        }
+                    })()
+                    : await executeJobCore(state, job);
                 results.push({ jobId: id, ...result, startedAt, endedAt: state.deps.nowMs() });
             }
             catch (err) {
-                state.deps.log.warn({ jobId: id, jobName: job.name, timeoutMs: jobTimeoutMs }, `cron: job failed: ${String(err)}`);
+                state.deps.log.warn({ jobId: id, jobName: job.name, timeoutMs: jobTimeoutMs ?? null }, `cron: job failed: ${String(err)}`);
                 results.push({
                     jobId: id,
                     status: "error",
@@ -189,24 +246,18 @@ export async function onTimer(state) {
                         startedAt: result.startedAt,
                         endedAt: result.endedAt,
                     });
-                    emit(state, {
-                        jobId: job.id,
-                        action: "finished",
-                        status: result.status,
-                        error: result.error,
-                        summary: result.summary,
-                        sessionId: result.sessionId,
-                        sessionKey: result.sessionKey,
-                        runAtMs: result.startedAt,
-                        durationMs: job.state.lastDurationMs,
-                        nextRunAtMs: job.state.nextRunAtMs,
-                    });
+                    emitJobFinished(state, job, result, result.startedAt);
                     if (shouldDelete && state.store) {
                         state.store.jobs = state.store.jobs.filter((j) => j.id !== job.id);
                         emit(state, { jobId: job.id, action: "removed" });
                     }
                 }
-                recomputeNextRuns(state);
+                // Use maintenance-only recompute to avoid advancing past-due
+                // nextRunAtMs values that became due between findDueJobs and this
+                // locked block.  The full recomputeNextRuns would silently skip
+                // those jobs (advancing nextRunAtMs without execution), causing
+                // daily cron schedules to jump 48 h instead of 24 h (#17852).
+                recomputeNextRunsForMaintenance(state);
                 await persist(state);
             });
         }
@@ -254,41 +305,49 @@ function findDueJobs(state) {
         return [];
     }
     const now = state.deps.nowMs();
-    return state.store.jobs.filter((j) => {
-        if (!j.state) {
-            j.state = {};
-        }
-        if (!j.enabled) {
-            return false;
-        }
-        if (typeof j.state.runningAtMs === "number") {
-            return false;
-        }
-        const next = j.state.nextRunAtMs;
-        return typeof next === "number" && now >= next;
-    });
+    return collectRunnableJobs(state, now);
+}
+function isRunnableJob(params) {
+    const { job, nowMs } = params;
+    if (!job.state) {
+        job.state = {};
+    }
+    if (!job.enabled) {
+        return false;
+    }
+    if (params.skipJobIds?.has(job.id)) {
+        return false;
+    }
+    if (typeof job.state.runningAtMs === "number") {
+        return false;
+    }
+    if (params.skipAtIfAlreadyRan && job.schedule.kind === "at" && job.state.lastStatus) {
+        // Any terminal status (ok, error, skipped) means the job already ran at least once.
+        // Don't re-fire it on restart — applyJobResult disables one-shot jobs, but guard
+        // here defensively (#13845).
+        return false;
+    }
+    const next = job.state.nextRunAtMs;
+    return typeof next === "number" && nowMs >= next;
+}
+function collectRunnableJobs(state, nowMs, opts) {
+    if (!state.store) {
+        return [];
+    }
+    return state.store.jobs.filter((job) => isRunnableJob({
+        job,
+        nowMs,
+        skipJobIds: opts?.skipJobIds,
+        skipAtIfAlreadyRan: opts?.skipAtIfAlreadyRan,
+    }));
 }
-export async function runMissedJobs(state) {
+export async function runMissedJobs(state, opts) {
     if (!state.store) {
         return;
     }
     const now = state.deps.nowMs();
-    const missed = state.store.jobs.filter((j) => {
-        if (!j.state) {
-            j.state = {};
-        }
-        if (!j.enabled) {
-            return false;
-        }
-        if (typeof j.state.runningAtMs === "number") {
-            return false;
-        }
-        const next = j.state.nextRunAtMs;
-        if (j.schedule.kind === "at" && j.state.lastStatus === "ok") {
-            return false;
-        }
-        return typeof next === "number" && now >= next;
-    });
+    const skipJobIds = opts?.skipJobIds;
+    const missed = collectRunnableJobs(state, now, { skipJobIds, skipAtIfAlreadyRan: true });
     if (missed.length > 0) {
         state.deps.log.info({ count: missed.length, jobIds: missed.map((j) => j.id) }, "cron: running missed jobs after restart");
         for (const job of missed) {
@@ -301,19 +360,7 @@ export async function runDueJobs(state) {
         return;
     }
     const now = state.deps.nowMs();
-    const due = state.store.jobs.filter((j) => {
-        if (!j.state) {
-            j.state = {};
-        }
-        if (!j.enabled) {
-            return false;
-        }
-        if (typeof j.state.runningAtMs === "number") {
-            return false;
-        }
-        const next = j.state.nextRunAtMs;
-        return typeof next === "number" && now >= next;
-    });
+    const due = collectRunnableJobs(state, now);
     for (const job of due) {
         await executeJob(state, job, now, { forced: false });
     }
@@ -330,24 +377,37 @@ async function executeJobCore(state, job) {
                     : 'main job requires payload.kind="systemEvent"',
             };
         }
-        state.deps.enqueueSystemEvent(text, { agentId: job.agentId });
+        state.deps.enqueueSystemEvent(text, {
+            agentId: job.agentId,
+            sessionKey: job.sessionKey,
+            contextKey: `cron:${job.id}`,
+        });
         if (job.wakeMode === "now" && state.deps.runHeartbeatOnce) {
             const reason = `cron:${job.id}`;
             const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-            const maxWaitMs = 2 * 60_000;
+            const maxWaitMs = state.deps.wakeNowHeartbeatBusyMaxWaitMs ?? 2 * 60_000;
+            const retryDelayMs = state.deps.wakeNowHeartbeatBusyRetryDelayMs ?? 250;
             const waitStartedAt = state.deps.nowMs();
             let heartbeatResult;
             for (;;) {
-                heartbeatResult = await state.deps.runHeartbeatOnce({ reason });
+                heartbeatResult = await state.deps.runHeartbeatOnce({
+                    reason,
+                    agentId: job.agentId,
+                    sessionKey: job.sessionKey,
+                });
                 if (heartbeatResult.status !== "skipped" ||
                     heartbeatResult.reason !== "requests-in-flight") {
                     break;
                 }
                 if (state.deps.nowMs() - waitStartedAt > maxWaitMs) {
-                    state.deps.requestHeartbeatNow({ reason });
+                    state.deps.requestHeartbeatNow({
+                        reason,
+                        agentId: job.agentId,
+                        sessionKey: job.sessionKey,
+                    });
                     return { status: "ok", summary: text };
                 }
-                await delay(250);
+                await delay(retryDelayMs);
             }
             if (heartbeatResult.status === "ran") {
                 return { status: "ok", summary: text };
@@ -360,7 +420,11 @@ async function executeJobCore(state, job) {
             }
         }
         else {
-            state.deps.requestHeartbeatNow({ reason: `cron:${job.id}` });
+            state.deps.requestHeartbeatNow({
+                reason: `cron:${job.id}`,
+                agentId: job.agentId,
+                sessionKey: job.sessionKey,
+            });
             return { status: "ok", summary: text };
         }
     }
@@ -371,15 +435,28 @@ async function executeJobCore(state, job) {
         job,
         message: job.payload.message,
     });
-    // Post a short summary back to the main session.
+    // Post a short summary back to the main session — but only when the
+    // isolated run did NOT already deliver its output to the target channel.
+    // When `res.delivered` is true the announce flow (or direct outbound
+    // delivery) already sent the result, so posting the summary to main
+    // would wake the main agent and cause a duplicate message.
+    // See: https://github.com/poolbot/poolbot/issues/15692
     const summaryText = res.summary?.trim();
     const deliveryPlan = resolveCronDeliveryPlan(job);
-    if (summaryText && deliveryPlan.requested) {
+    if (summaryText && deliveryPlan.requested && !res.delivered) {
         const prefix = "Cron";
         const label = res.status === "error" ? `${prefix} (error): ${summaryText}` : `${prefix}: ${summaryText}`;
-        state.deps.enqueueSystemEvent(label, { agentId: job.agentId });
+        state.deps.enqueueSystemEvent(label, {
+            agentId: job.agentId,
+            sessionKey: job.sessionKey,
+            contextKey: `cron:${job.id}`,
+        });
         if (job.wakeMode === "now") {
-            state.deps.requestHeartbeatNow({ reason: `cron:${job.id}` });
+            state.deps.requestHeartbeatNow({
+                reason: `cron:${job.id}`,
+                agentId: job.agentId,
+                sessionKey: job.sessionKey,
+            });
         }
     }
     return {
@@ -388,6 +465,9 @@ async function executeJobCore(state, job) {
         summary: res.summary,
         sessionId: res.sessionId,
         sessionKey: res.sessionKey,
+        model: res.model,
+        provider: res.provider,
+        usage: res.usage,
     };
 }
 /**
@@ -416,22 +496,28 @@ export async function executeJob(state, job, _nowMs, _opts) {
         startedAt,
         endedAt,
     });
+    emitJobFinished(state, job, coreResult, startedAt);
+    if (shouldDelete && state.store) {
+        state.store.jobs = state.store.jobs.filter((j) => j.id !== job.id);
+        emit(state, { jobId: job.id, action: "removed" });
+    }
+}
+function emitJobFinished(state, job, result, runAtMs) {
     emit(state, {
         jobId: job.id,
         action: "finished",
-        status: coreResult.status,
-        error: coreResult.error,
-        summary: coreResult.summary,
-        sessionId: coreResult.sessionId,
-        sessionKey: coreResult.sessionKey,
-        runAtMs: startedAt,
+        status: result.status,
+        error: result.error,
+        summary: result.summary,
+        sessionId: result.sessionId,
+        sessionKey: result.sessionKey,
+        runAtMs,
         durationMs: job.state.lastDurationMs,
         nextRunAtMs: job.state.nextRunAtMs,
+        model: result.model,
+        provider: result.provider,
+        usage: result.usage,
     });
-    if (shouldDelete && state.store) {
-        state.store.jobs = state.store.jobs.filter((j) => j.id !== job.id);
-        emit(state, { jobId: job.id, action: "removed" });
-    }
 }
 export function wake(state, opts) {
     const text = opts.text.trim();

package/dist/cron/service.js

@@ -29,6 +29,9 @@ export class CronService {
     async run(id, mode) {
         return await ops.run(this.state, id, mode);
     }
+    getJob(id) {
+        return this.state.store?.jobs.find((job) => job.id === id);
+    }
     wake(opts) {
         return ops.wakeNow(this.state, opts);
     }

package/dist/cron/stagger.js

@@ -0,0 +1,37 @@
+export const DEFAULT_TOP_OF_HOUR_STAGGER_MS = 5 * 60 * 1000;
+function parseCronFields(expr) {
+    return expr.trim().split(/\s+/).filter(Boolean);
+}
+export function isRecurringTopOfHourCronExpr(expr) {
+    const fields = parseCronFields(expr);
+    if (fields.length === 5) {
+        const [minuteField, hourField] = fields;
+        return minuteField === "0" && hourField.includes("*");
+    }
+    if (fields.length === 6) {
+        const [secondField, minuteField, hourField] = fields;
+        return secondField === "0" && minuteField === "0" && hourField.includes("*");
+    }
+    return false;
+}
+export function normalizeCronStaggerMs(raw) {
+    const numeric = typeof raw === "number"
+        ? raw
+        : typeof raw === "string" && raw.trim()
+            ? Number(raw)
+            : Number.NaN;
+    if (!Number.isFinite(numeric)) {
+        return undefined;
+    }
+    return Math.max(0, Math.floor(numeric));
+}
+export function resolveDefaultCronStaggerMs(expr) {
+    return isRecurringTopOfHourCronExpr(expr) ? DEFAULT_TOP_OF_HOUR_STAGGER_MS : undefined;
+}
+export function resolveCronStaggerMs(schedule) {
+    const explicit = normalizeCronStaggerMs(schedule.staggerMs);
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    return resolveDefaultCronStaggerMs(schedule.expr) ?? 0;
+}