@poolzin/pool-bot 2026.2.21 → 2026.2.23

package/dist/cron/run-log.js

@@ -68,6 +68,9 @@ export async function readCronRunLogEntries(filePath, opts) {
             if (jobId && obj.jobId !== jobId) {
                 continue;
             }
+            const usage = obj.usage && typeof obj.usage === "object"
+                ? obj.usage
+                : undefined;
             const entry = {
                 ts: obj.ts,
                 jobId: obj.jobId,
@@ -78,6 +81,17 @@ export async function readCronRunLogEntries(filePath, opts) {
                 runAtMs: obj.runAtMs,
                 durationMs: obj.durationMs,
                 nextRunAtMs: obj.nextRunAtMs,
+                model: typeof obj.model === "string" && obj.model.trim() ? obj.model : undefined,
+                provider: typeof obj.provider === "string" && obj.provider.trim() ? obj.provider : undefined,
+                usage: usage
+                    ? {
+                        input_tokens: typeof usage.input_tokens === "number" ? usage.input_tokens : undefined,
+                        output_tokens: typeof usage.output_tokens === "number" ? usage.output_tokens : undefined,
+                        total_tokens: typeof usage.total_tokens === "number" ? usage.total_tokens : undefined,
+                        cache_read_tokens: typeof usage.cache_read_tokens === "number" ? usage.cache_read_tokens : undefined,
+                        cache_write_tokens: typeof usage.cache_write_tokens === "number" ? usage.cache_write_tokens : undefined,
+                    }
+                    : undefined,
             };
             if (typeof obj.sessionId === "string" && obj.sessionId.trim().length > 0) {
                 entry.sessionId = obj.sessionId;

package/dist/cron/service/jobs.js

@@ -1,8 +1,42 @@
 import crypto from "node:crypto";
 import { parseAbsoluteTimeMs } from "../parse.js";
 import { computeNextRunAtMs } from "../schedule.js";
-import { normalizeOptionalAgentId, normalizeOptionalText, normalizePayloadToSystemText, normalizeRequiredName, } from "./normalize.js";
+import { normalizeCronStaggerMs, resolveCronStaggerMs, resolveDefaultCronStaggerMs, } from "../stagger.js";
+import { normalizeHttpWebhookUrl } from "../webhook-url.js";
+import { normalizeOptionalAgentId, normalizeOptionalSessionKey, normalizeOptionalText, normalizePayloadToSystemText, normalizeRequiredName, } from "./normalize.js";
 const STUCK_RUN_MS = 2 * 60 * 60 * 1000;
+function resolveStableCronOffsetMs(jobId, staggerMs) {
+    if (staggerMs <= 1) {
+        return 0;
+    }
+    const digest = crypto.createHash("sha256").update(jobId).digest();
+    return digest.readUInt32BE(0) % staggerMs;
+}
+function computeStaggeredCronNextRunAtMs(job, nowMs) {
+    if (job.schedule.kind !== "cron") {
+        return computeNextRunAtMs(job.schedule, nowMs);
+    }
+    const staggerMs = resolveCronStaggerMs(job.schedule);
+    const offsetMs = resolveStableCronOffsetMs(job.id, staggerMs);
+    if (offsetMs <= 0) {
+        return computeNextRunAtMs(job.schedule, nowMs);
+    }
+    // Shift the schedule cursor backwards by the per-job offset so we can still
+    // target the current schedule window if its staggered slot has not passed yet.
+    let cursorMs = Math.max(0, nowMs - offsetMs);
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const baseNext = computeNextRunAtMs(job.schedule, cursorMs);
+        if (baseNext === undefined) {
+            return undefined;
+        }
+        const shifted = baseNext + offsetMs;
+        if (shifted > nowMs) {
+            return shifted;
+        }
+        cursorMs = Math.max(cursorMs + 1, baseNext + 1_000);
+    }
+    return undefined;
+}
 function resolveEveryAnchorMs(params) {
     const raw = params.schedule.anchorMs;
     if (typeof raw === "number" && Number.isFinite(raw)) {
@@ -19,8 +53,19 @@ export function assertSupportedJobSpec(job) {
     }
 }
 function assertDeliverySupport(job) {
-    if (job.delivery && job.sessionTarget !== "isolated") {
-        throw new Error('cron delivery config is only supported for sessionTarget="isolated"');
+    if (!job.delivery) {
+        return;
+    }
+    if (job.delivery.mode === "webhook") {
+        const target = normalizeHttpWebhookUrl(job.delivery.to);
+        if (!target) {
+            throw new Error("cron webhook delivery requires delivery.to to be a valid http(s) URL");
+        }
+        job.delivery.to = target;
+        return;
+    }
+    if (job.sessionTarget !== "isolated") {
+        throw new Error('cron channel delivery config is only supported for sessionTarget="isolated"');
     }
 }
 export function findJobOrThrow(state, id) {
@@ -59,50 +104,134 @@ export function computeJobNextRunAtMs(job, nowMs) {
                     : null;
         return atMs !== null ? atMs : undefined;
     }
-    return computeNextRunAtMs(job.schedule, nowMs);
+    const next = computeStaggeredCronNextRunAtMs(job, nowMs);
+    if (next === undefined && job.schedule.kind === "cron") {
+        const nextSecondMs = Math.floor(nowMs / 1000) * 1000 + 1000;
+        return computeStaggeredCronNextRunAtMs(job, nextSecondMs);
+    }
+    return next;
 }
-export function recomputeNextRuns(state) {
+/** Maximum consecutive schedule errors before auto-disabling a job. */
+const MAX_SCHEDULE_ERRORS = 3;
+function recordScheduleComputeError(params) {
+    const { state, job, err } = params;
+    const errorCount = (job.state.scheduleErrorCount ?? 0) + 1;
+    const errText = String(err);
+    job.state.scheduleErrorCount = errorCount;
+    job.state.nextRunAtMs = undefined;
+    job.state.lastError = `schedule error: ${errText}`;
+    if (errorCount >= MAX_SCHEDULE_ERRORS) {
+        job.enabled = false;
+        state.deps.log.error({ jobId: job.id, name: job.name, errorCount, err: errText }, "cron: auto-disabled job after repeated schedule errors");
+    }
+    else {
+        state.deps.log.warn({ jobId: job.id, name: job.name, errorCount, err: errText }, "cron: failed to compute next run for job (skipping)");
+    }
+    return true;
+}
+function normalizeJobTickState(params) {
+    const { state, job, nowMs } = params;
+    let changed = false;
+    if (!job.state) {
+        job.state = {};
+        changed = true;
+    }
+    if (!job.enabled) {
+        if (job.state.nextRunAtMs !== undefined) {
+            job.state.nextRunAtMs = undefined;
+            changed = true;
+        }
+        if (job.state.runningAtMs !== undefined) {
+            job.state.runningAtMs = undefined;
+            changed = true;
+        }
+        return { changed, skip: true };
+    }
+    const runningAt = job.state.runningAtMs;
+    if (typeof runningAt === "number" && nowMs - runningAt > STUCK_RUN_MS) {
+        state.deps.log.warn({ jobId: job.id, runningAtMs: runningAt }, "cron: clearing stuck running marker");
+        job.state.runningAtMs = undefined;
+        changed = true;
+    }
+    return { changed, skip: false };
+}
+function walkSchedulableJobs(state, fn) {
     if (!state.store) {
         return false;
     }
     let changed = false;
     const now = state.deps.nowMs();
     for (const job of state.store.jobs) {
-        if (!job.state) {
-            job.state = {};
+        const tick = normalizeJobTickState({ state, job, nowMs: now });
+        if (tick.changed) {
             changed = true;
         }
-        if (!job.enabled) {
-            if (job.state.nextRunAtMs !== undefined) {
-                job.state.nextRunAtMs = undefined;
-                changed = true;
-            }
-            if (job.state.runningAtMs !== undefined) {
-                job.state.runningAtMs = undefined;
-                changed = true;
-            }
+        if (tick.skip) {
             continue;
         }
-        const runningAt = job.state.runningAtMs;
-        if (typeof runningAt === "number" && now - runningAt > STUCK_RUN_MS) {
-            state.deps.log.warn({ jobId: job.id, runningAtMs: runningAt }, "cron: clearing stuck running marker");
-            job.state.runningAtMs = undefined;
+        if (fn({ job, nowMs: now })) {
+            changed = true;
+        }
+    }
+    return changed;
+}
+function recomputeJobNextRunAtMs(params) {
+    let changed = false;
+    try {
+        const newNext = computeJobNextRunAtMs(params.job, params.nowMs);
+        if (params.job.state.nextRunAtMs !== newNext) {
+            params.job.state.nextRunAtMs = newNext;
             changed = true;
         }
+        // Clear schedule error count on successful computation.
+        if (params.job.state.scheduleErrorCount) {
+            params.job.state.scheduleErrorCount = undefined;
+            changed = true;
+        }
+    }
+    catch (err) {
+        if (recordScheduleComputeError({ state: params.state, job: params.job, err })) {
+            changed = true;
+        }
+    }
+    return changed;
+}
+export function recomputeNextRuns(state) {
+    return walkSchedulableJobs(state, ({ job, nowMs: now }) => {
+        let changed = false;
         // Only recompute if nextRunAtMs is missing or already past-due.
         // Preserving a still-future nextRunAtMs avoids accidentally advancing
         // a job that hasn't fired yet (e.g. during restart recovery).
         const nextRun = job.state.nextRunAtMs;
         const isDueOrMissing = nextRun === undefined || now >= nextRun;
         if (isDueOrMissing) {
-            const newNext = computeJobNextRunAtMs(job, now);
-            if (job.state.nextRunAtMs !== newNext) {
-                job.state.nextRunAtMs = newNext;
+            if (recomputeJobNextRunAtMs({ state, job, nowMs: now })) {
                 changed = true;
             }
         }
-    }
-    return changed;
+        return changed;
+    });
+}
+/**
+ * Maintenance-only version of recomputeNextRuns that handles disabled jobs
+ * and stuck markers, but does NOT recompute nextRunAtMs for enabled jobs
+ * with existing values. Used during timer ticks when no due jobs were found
+ * to prevent silently advancing past-due nextRunAtMs values without execution
+ * (see #13992).
+ */
+export function recomputeNextRunsForMaintenance(state) {
+    return walkSchedulableJobs(state, ({ job, nowMs: now }) => {
+        let changed = false;
+        // Only compute missing nextRunAtMs, do NOT recompute existing ones.
+        // If a job was past-due but not found by findDueJobs, recomputing would
+        // cause it to be silently skipped.
+        if (job.state.nextRunAtMs === undefined) {
+            if (recomputeJobNextRunAtMs({ state, job, nowMs: now })) {
+                changed = true;
+            }
+        }
+        return changed;
+    });
 }
 export function nextWakeAtMs(state) {
     const jobs = state.store?.jobs ?? [];
@@ -123,7 +252,18 @@ export function createJob(state, input) {
                 fallbackAnchorMs: now,
             }),
         }
-        : input.schedule;
+        : input.schedule.kind === "cron"
+            ? (() => {
+                const explicitStaggerMs = normalizeCronStaggerMs(input.schedule.staggerMs);
+                if (explicitStaggerMs !== undefined) {
+                    return { ...input.schedule, staggerMs: explicitStaggerMs };
+                }
+                const defaultStaggerMs = resolveDefaultCronStaggerMs(input.schedule.expr);
+                return defaultStaggerMs !== undefined
+                    ? { ...input.schedule, staggerMs: defaultStaggerMs }
+                    : input.schedule;
+            })()
+            : input.schedule;
     const deleteAfterRun = typeof input.deleteAfterRun === "boolean"
         ? input.deleteAfterRun
         : schedule.kind === "at"
@@ -133,6 +273,7 @@ export function createJob(state, input) {
     const job = {
         id,
         agentId: normalizeOptionalAgentId(input.agentId),
+        sessionKey: normalizeOptionalSessionKey(input.sessionKey),
         name: normalizeRequiredName(input.name),
         description: normalizeOptionalText(input.description),
         enabled,
@@ -167,7 +308,25 @@ export function applyJobPatch(job, patch) {
         job.deleteAfterRun = patch.deleteAfterRun;
     }
     if (patch.schedule) {
-        job.schedule = patch.schedule;
+        if (patch.schedule.kind === "cron") {
+            const explicitStaggerMs = normalizeCronStaggerMs(patch.schedule.staggerMs);
+            if (explicitStaggerMs !== undefined) {
+                job.schedule = { ...patch.schedule, staggerMs: explicitStaggerMs };
+            }
+            else if (job.schedule.kind === "cron") {
+                job.schedule = { ...patch.schedule, staggerMs: job.schedule.staggerMs };
+            }
+            else {
+                const defaultStaggerMs = resolveDefaultCronStaggerMs(patch.schedule.expr);
+                job.schedule =
+                    defaultStaggerMs !== undefined
+                        ? { ...patch.schedule, staggerMs: defaultStaggerMs }
+                        : patch.schedule;
+            }
+        }
+        else {
+            job.schedule = patch.schedule;
+        }
     }
     if (patch.sessionTarget) {
         job.sessionTarget = patch.sessionTarget;
@@ -190,7 +349,7 @@ export function applyJobPatch(job, patch) {
     if (patch.delivery) {
         job.delivery = mergeCronDelivery(job.delivery, patch.delivery);
     }
-    if (job.sessionTarget === "main" && job.delivery) {
+    if (job.sessionTarget === "main" && job.delivery?.mode !== "webhook") {
         job.delivery = undefined;
     }
     if (patch.state) {
@@ -199,6 +358,9 @@ export function applyJobPatch(job, patch) {
     if ("agentId" in patch) {
         job.agentId = normalizeOptionalAgentId(patch.agentId);
     }
+    if ("sessionKey" in patch) {
+        job.sessionKey = normalizeOptionalSessionKey(patch.sessionKey);
+    }
     assertSupportedJobSpec(job);
     assertDeliverySupport(job);
 }

package/dist/cron/service/normalize.js

@@ -1,32 +1,45 @@
 import { normalizeAgentId } from "../../routing/session-key.js";
 import { truncateUtf16Safe } from "../../utils.js";
 export function normalizeRequiredName(raw) {
-    if (typeof raw !== "string")
+    if (typeof raw !== "string") {
         throw new Error("cron job name is required");
+    }
     const name = raw.trim();
-    if (!name)
+    if (!name) {
         throw new Error("cron job name is required");
+    }
     return name;
 }
 export function normalizeOptionalText(raw) {
-    if (typeof raw !== "string")
+    if (typeof raw !== "string") {
         return undefined;
+    }
     const trimmed = raw.trim();
     return trimmed ? trimmed : undefined;
 }
 function truncateText(input, maxLen) {
-    if (input.length <= maxLen)
+    if (input.length <= maxLen) {
         return input;
+    }
     return `${truncateUtf16Safe(input, Math.max(0, maxLen - 1)).trimEnd()}…`;
 }
 export function normalizeOptionalAgentId(raw) {
-    if (typeof raw !== "string")
+    if (typeof raw !== "string") {
         return undefined;
+    }
     const trimmed = raw.trim();
-    if (!trimmed)
+    if (!trimmed) {
         return undefined;
+    }
     return normalizeAgentId(trimmed);
 }
+export function normalizeOptionalSessionKey(raw) {
+    if (typeof raw !== "string") {
+        return undefined;
+    }
+    const trimmed = raw.trim();
+    return trimmed || undefined;
+}
 export function inferLegacyName(job) {
     const text = job?.payload?.kind === "systemEvent" && typeof job.payload.text === "string"
         ? job.payload.text
@@ -37,19 +50,24 @@ export function inferLegacyName(job) {
         .split("\n")
         .map((l) => l.trim())
         .find(Boolean) ?? "";
-    if (firstLine)
+    if (firstLine) {
         return truncateText(firstLine, 60);
+    }
     const kind = typeof job?.schedule?.kind === "string" ? job.schedule.kind : "";
-    if (kind === "cron" && typeof job?.schedule?.expr === "string")
+    if (kind === "cron" && typeof job?.schedule?.expr === "string") {
         return `Cron: ${truncateText(job.schedule.expr, 52)}`;
-    if (kind === "every" && typeof job?.schedule?.everyMs === "number")
+    }
+    if (kind === "every" && typeof job?.schedule?.everyMs === "number") {
         return `Every: ${job.schedule.everyMs}ms`;
-    if (kind === "at")
+    }
+    if (kind === "at") {
         return "One-shot";
+    }
     return "Cron job";
 }
 export function normalizePayloadToSystemText(payload) {
-    if (payload.kind === "systemEvent")
+    if (payload.kind === "systemEvent") {
         return payload.text.trim();
+    }
     return payload.message.trim();
 }

package/dist/cron/service/store.js

@@ -1,38 +1,11 @@
 import fs from "node:fs";
+import { buildDeliveryFromLegacyPayload, hasLegacyDeliveryHints, stripLegacyDeliveryFields, } from "../legacy-delivery.js";
 import { parseAbsoluteTimeMs } from "../parse.js";
 import { migrateLegacyCronPayload } from "../payload-migration.js";
+import { normalizeCronStaggerMs, resolveDefaultCronStaggerMs } from "../stagger.js";
 import { loadCronStore, saveCronStore } from "../store.js";
 import { recomputeNextRuns } from "./jobs.js";
 import { inferLegacyName, normalizeOptionalText } from "./normalize.js";
-function hasLegacyDeliveryHints(payload) {
-    if (typeof payload.deliver === "boolean") {
-        return true;
-    }
-    if (typeof payload.bestEffortDeliver === "boolean") {
-        return true;
-    }
-    if (typeof payload.to === "string" && payload.to.trim()) {
-        return true;
-    }
-    return false;
-}
-function buildDeliveryFromLegacyPayload(payload) {
-    const deliver = payload.deliver;
-    const mode = deliver === false ? "none" : "announce";
-    const channelRaw = typeof payload.channel === "string" ? payload.channel.trim().toLowerCase() : "";
-    const toRaw = typeof payload.to === "string" ? payload.to.trim() : "";
-    const next = { mode };
-    if (channelRaw) {
-        next.channel = channelRaw;
-    }
-    if (toRaw) {
-        next.to = toRaw;
-    }
-    if (typeof payload.bestEffortDeliver === "boolean") {
-        next.bestEffort = payload.bestEffortDeliver;
-    }
-    return next;
-}
 function buildDeliveryPatchFromLegacyPayload(payload) {
     const deliver = payload.deliver;
     const channelRaw = typeof payload.channel === "string" ? payload.channel.trim().toLowerCase() : "";
@@ -86,20 +59,6 @@ function mergeLegacyDeliveryInto(delivery, payload) {
     }
     return { delivery: next, mutated };
 }
-function stripLegacyDeliveryFields(payload) {
-    if ("deliver" in payload) {
-        delete payload.deliver;
-    }
-    if ("channel" in payload) {
-        delete payload.channel;
-    }
-    if ("to" in payload) {
-        delete payload.to;
-    }
-    if ("bestEffortDeliver" in payload) {
-        delete payload.bestEffortDeliver;
-    }
-}
 function normalizePayloadKind(payload) {
     const raw = typeof payload.kind === "string" ? payload.kind.trim().toLowerCase() : "";
     if (raw === "agentturn") {
@@ -143,7 +102,7 @@ function copyTopLevelAgentTurnFields(raw, payload) {
     if (typeof payload.timeoutSeconds !== "number" &&
         typeof raw.timeoutSeconds === "number" &&
         Number.isFinite(raw.timeoutSeconds)) {
-        payload.timeoutSeconds = Math.max(1, Math.floor(raw.timeoutSeconds));
+        payload.timeoutSeconds = Math.max(0, Math.floor(raw.timeoutSeconds));
         mutated = true;
     }
     if (typeof payload.allowUnsafeExternalContent !== "boolean" &&
@@ -256,6 +215,13 @@ export async function ensureLoaded(state, opts) {
             raw.description = desc;
             mutated = true;
         }
+        if ("sessionKey" in raw) {
+            const sessionKey = typeof raw.sessionKey === "string" ? normalizeOptionalText(raw.sessionKey) : undefined;
+            if (raw.sessionKey !== sessionKey) {
+                raw.sessionKey = sessionKey;
+                mutated = true;
+            }
+        }
         if (typeof raw.enabled !== "boolean") {
             raw.enabled = true;
             mutated = true;
@@ -350,6 +316,26 @@ export async function ensureLoaded(state, opts) {
                     mutated = true;
                 }
             }
+            const exprRaw = typeof sched.expr === "string" ? sched.expr.trim() : "";
+            if (typeof sched.expr === "string" && sched.expr !== exprRaw) {
+                sched.expr = exprRaw;
+                mutated = true;
+            }
+            if ((kind === "cron" || sched.kind === "cron") && exprRaw) {
+                const explicitStaggerMs = normalizeCronStaggerMs(sched.staggerMs);
+                const defaultStaggerMs = resolveDefaultCronStaggerMs(exprRaw);
+                const targetStaggerMs = explicitStaggerMs ?? defaultStaggerMs;
+                if (targetStaggerMs === undefined) {
+                    if ("staggerMs" in sched) {
+                        delete sched.staggerMs;
+                        mutated = true;
+                    }
+                }
+                else if (sched.staggerMs !== targetStaggerMs) {
+                    sched.staggerMs = targetStaggerMs;
+                    mutated = true;
+                }
+            }
         }
         const delivery = raw.delivery;
         if (delivery && typeof delivery === "object" && !Array.isArray(delivery)) {