Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.
import { CronExpressionParser } from "cron-parser";
/** Routines may run at most this often. A model can be talked into anything; the floor cannot. */
export const MINIMUM_INTERVAL_MS = 15 * 60 * 1000;
export class ScheduleRefusedError extends Error {
constructor(message: string) {
super(message);
this.name = "ScheduleRefusedError";
}
}
const UNREADABLE_MESSAGE = "That schedule could not be read.";
const UNKNOWN_TIMEZONE_MESSAGE = "That is not a timezone I know.";
const TOO_FREQUENT_MESSAGE = "Routines may run at most every 15 minutes.";
/**
* cron-parser is lenient about field count on purpose (it also accepts a leading
* seconds field or a trailing year field), so it will happily "parse" a four-field
* or six-field string by filling in defaults. We want a hard five-field contract,
* so that check happens here, before the string ever reaches the parser.
*/
function hasFiveFields(cron: string): boolean {
return cron.trim().split(/\s+/).length === 5;
}
/**
* Both memo caches below are keyed by caller-supplied strings, so an unbounded map is a slow leak a
* hostile caller can drive on purpose: one invalid timezone per request grows it forever. Cleared
* wholesale at the cap rather than evicted piecemeal — the population that matters (the handful of
* zones and expressions real routines use) is re-learned in one pass and the code stays one line.
*/
const MAX_MEMOIZED_VERDICTS = 1000;
const timeZoneVerdicts = new Map<string, boolean>();
/**
* The only reliable way to validate an IANA zone name in plain JS/TS: ask Intl to
* build a formatter for it and see whether it throws. cron-parser (via luxon)
* accepts an invalid zone silently at parse() time and only blows up later, with
* a message ("unhandled timestamp: Invalid Date") that says nothing about
* timezones — so we check this ourselves, up front, to give a sentence that means
* something.
*
* Memoized because this sits on the sweep's hot path: `advanceNextRun` calls in here for every due
* routine on every pass, and building an Intl.DateTimeFormat per call is the expensive way to keep
* re-learning that "UTC" is a timezone.
*/
function isKnownTimeZone(timezone: string): boolean {
const cached = timeZoneVerdicts.get(timezone);
if (cached !== undefined) return cached;
let known: boolean;
try {
new Intl.DateTimeFormat(undefined, { timeZone: timezone });
known = true;
} catch {
known = false;
}
if (timeZoneVerdicts.size >= MAX_MEMOIZED_VERDICTS) timeZoneVerdicts.clear();
timeZoneVerdicts.set(timezone, known);
return known;
}
/**
* Where the floor scan starts, fixed so acceptance is a property of the expression rather than of
* the clock at the moment somebody asked. The failure this prevents: `45,55 8 * * *` asked about at
* 08:50 sees 08:55 and then tomorrow's 08:45 as its next two occurrences — a 23h50m gap — so a check
* that samples from "now" accepts at some times of day what it refuses at others, and the accepted
* routine then wedges the moment the sweep tries to advance it past the ten-minute pair. A leap-year
* start, so expressions pinned to 29 February are scanned on days they actually fire.
*/
const FLOOR_SCAN_START = new Date("2024-01-01T00:00:00Z");
/**
* How many successive occurrences the floor scan walks.
*
* The intra-day pattern of a five-field cron is the same on every day it fires (minutes × hours),
* so the first firing day already shows every within-day gap, and the densest day the floor allows
* is 96 firings — 200 covers a full day of those plus the wrap into the next firing day, and for
* sparse expressions the iterator simply walks forward until it has seen 200 real firings, however
* far apart they are. Not exhaustive: a sub-floor gap that only exists under a DST compression more
* than 200 occurrences from the scan start can still slip through, which is why the per-call pair
* check below stays as the runtime backstop.
*/
const FLOOR_SCAN_OCCURRENCES = 200;
/** null means the expression cleared the floor; a string is the refusal to throw. */
const floorVerdicts = new Map<string, string | null>();
/**
* Refuse any expression whose own cycle contains an adjacent pair under the floor, deterministically.
*
* Scanned from a fixed start rather than from `after`, because the caller's `after` moves with the
* clock and a floor sampled near it is a floor that depends on when the question was asked. Parse
* and iteration errors are swallowed here on purpose: an unreadable expression is the caller's
* refusal to make (with the unreadable-schedule sentence), and an expression that runs out of
* occurrences mid-scan has shown every gap it has. Memoized because this runs inside
* `nextOccurrence`, which the sweep calls for every due routine on every pass.
*/
function refuseSubFloorCycle(cron: string, timezone: string): void {
const key = `${timezone}\u0000${cron}`;
const cached = floorVerdicts.get(key);
if (cached !== undefined) {
if (cached !== null) throw new ScheduleRefusedError(cached);
return;
}
let verdict: string | null = null;
try {
const expression = CronExpressionParser.parse(cron, {
tz: timezone,
currentDate: FLOOR_SCAN_START,
});
let previous = expression.next().toDate().getTime();
for (let index = 1; index < FLOOR_SCAN_OCCURRENCES; index += 1) {
const current = expression.next().toDate().getTime();
if (current - previous < MINIMUM_INTERVAL_MS) {
verdict = TOO_FREQUENT_MESSAGE;
break;
}
previous = current;
}
} catch {
// Unreadable, or fewer occurrences than the scan wanted. Either way the gaps seen were fine,
// and unreadability is refused by the parse in `nextOccurrence` with the sentence for it.
}
if (floorVerdicts.size >= MAX_MEMOIZED_VERDICTS) floorVerdicts.clear();
floorVerdicts.set(key, verdict);
if (verdict !== null) throw new ScheduleRefusedError(verdict);
}
/**
* Parse, validate against the floor, and return the next occurrence after `after`.
*
* One function owns both acceptance and scheduling, so what was accepted is always schedulable. The
* floor is enforced twice, on purpose: `refuseSubFloorCycle` scans the expression's own cycle from a
* fixed start, so acceptance cannot depend on the time of the asking, and the pair check at the
* bottom re-measures the gap actually ahead of `after`, catching the rare shapes the bounded scan
* cannot see (a DST compression far from the scan window). A pair-check throw at sweep time is what
* the sweep's unschedulable-routine switch-off exists for.
*/
export function nextOccurrence(
cron: string,
timezone: string,
after: Date,
): Date {
if (!hasFiveFields(cron)) {
throw new ScheduleRefusedError(UNREADABLE_MESSAGE);
}
if (!isKnownTimeZone(timezone)) {
throw new ScheduleRefusedError(UNKNOWN_TIMEZONE_MESSAGE);
}
refuseSubFloorCycle(cron, timezone);
let first: Date;
let second: Date;
try {
const expression = CronExpressionParser.parse(cron, {
tz: timezone,
currentDate: after,
});
// next() is strictly after currentDate, including when currentDate itself
// lands exactly on an occurrence.
first = expression.next().toDate();
second = expression.next().toDate();
} catch {
throw new ScheduleRefusedError(UNREADABLE_MESSAGE);
}
if (second.getTime() - first.getTime() < MINIMUM_INTERVAL_MS) {
throw new ScheduleRefusedError(TOO_FREQUENT_MESSAGE);
}
return first;
}
const WEEKDAY_NAMES = [
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday",
];
function pad2(value: number): string {
return value.toString().padStart(2, "0");
}
function ordinal(day: number): string {
const remainder100 = day % 100;
if (remainder100 >= 11 && remainder100 <= 13) {
return `${day}th`;
}
switch (day % 10) {
case 1:
return `${day}st`;
case 2:
return `${day}nd`;
case 3:
return `${day}rd`;
default:
return `${day}th`;
}
}
/** Joins names the way a person would say them: "A", "A and B", "A, B and C". */
function joinWords(words: string[]): string {
if (words.length === 1) return words[0];
const last = words[words.length - 1];
const rest = words.slice(0, -1);
return `${rest.join(", ")} and ${last}`;
}
/**
* The days a plain day-of-week field names, or null when it is not one.
*
* SUNDAY IS 0 AND IT IS ALSO 7. Both are ordinary crontab, `cron-parser` fires on Sunday for either,
* and `nextOccurrence` above accepts both — so a routine written `0 9 * * 7` is scheduled, fires on
* Sunday, and was then described to its owner and back to the model as `0 9 * * 7`, because only the
* 0 spelling was recognised here. That is not the raw-expression fallback doing its job on a shape
* this cannot render; it is one of this function's own shapes arriving under the other of the two
* names its own scheduler takes.
*
* De-duplicated, because 7 and 0 are one day and `0,7` would otherwise render as "Sundays and
* Sundays", which is worse than the raw expression it replaced. Order is left as written, like the
* weekday list always has been.
*/
function weekdays(field: string): number[] | null {
if (!/^[0-7](,[0-7])*$/.test(field)) return null;
return [
...new Set(field.split(",").map((digit) => Number.parseInt(digit, 10) % 7)),
];
}
function parsePlainInt(field: string, min: number, max: number): number | null {
if (!/^\d{1,2}$/.test(field)) return null;
const value = Number.parseInt(field, 10);
if (value < min || value > max) return null;
return value;
}
/**
* "Weekdays at 09:00", "Every day at 18:30", or the raw expression when it is stranger than
* words.
*
* This string gets read by a model mid-conversation and rendered on a page. A formatter that
* throws on a weird expression would take a page down over a schedule nobody could read anyway,
* so unrecognized shapes fall back to the raw expression rather than raising anything, and the
* whole body is wrapped in a belt-and-suspenders try/catch to guarantee it.
*/
export function describeCron(cron: string): string {
try {
const fields = cron.trim().split(/\s+/);
if (fields.length !== 5) return cron;
const [
minuteField,
hourField,
dayOfMonthField,
monthField,
dayOfWeekField,
] = fields;
const wideOpen =
dayOfMonthField === "*" && monthField === "*" && dayOfWeekField === "*";
// "*/20 * * * *": a step under the floor's shape but at or above the floor itself, e.g. */15
// and up. Only when hour/day/month/weekday are all "*" — a step on any other field is stranger
// than this narrow rendering is meant to cover.
if (wideOpen && hourField === "*") {
const stepMatch = /^\*\/(\d{1,2})$/.exec(minuteField);
if (stepMatch) {
const step = Number.parseInt(stepMatch[1] as string, 10);
// A minute step restarts every hour rather than counting continuously from the first
// firing, so it only actually recurs every N minutes when N divides the hour evenly
// (e.g. */20 fires at :00, :20, :40 — a steady 20-minute gap). A step like */40 fires at
// :00 and :40 and then wraps, a 20-minute gap the second time round, so "Every 40 minutes"
// would be false. `step > 1` also rules out */1, which is reachable here even though the
// create-time floor refuses it, and would otherwise render the ungrammatical "Every 1
// minutes". Anything that fails this falls back to the raw expression.
if (Number.isInteger(step) && step > 1 && 60 % step === 0) {
return `Every ${step} minutes`;
}
}
}
const minute = parsePlainInt(minuteField, 0, 59);
const hour = parsePlainInt(hourField, 0, 23);
// "0,30 9 * * *": a handful of plain minutes within one hour, every day. Only when the hour is
// a single plain value and day/month/weekday are all "*" — anything with its own weekday or
// day-of-month shape stays out of this narrow rendering.
if (wideOpen && hour !== null && /^\d{1,2}(,\d{1,2})+$/.test(minuteField)) {
const minutes = minuteField
.split(",")
.map((part) => parsePlainInt(part, 0, 59));
if (minutes.every((value): value is number => value !== null)) {
// De-duplicated like `weekdays`: cron fires once for `0,0`, so it must not read as
// "09:00 and 09:00".
const times = [...new Set(minutes)]
.sort((a, b) => a - b)
.map((value) => `${pad2(hour)}:${pad2(value)}`);
return `Every day at ${joinWords(times)}`;
}
}
if (minute === null || hour === null) return cron;
const time = `${pad2(hour)}:${pad2(minute)}`;
if (dayOfMonthField === "*" && monthField === "*") {
if (dayOfWeekField === "*") {
return `Every day at ${time}`;
}
if (dayOfWeekField === "1-5") {
return `Weekdays at ${time}`;
}
const days = weekdays(dayOfWeekField);
if (days?.length === 1) {
return `${WEEKDAY_NAMES[days[0] as number]}s at ${time}`;
}
if (days && days.length > 1) {
const names = days.map((day) => `${WEEKDAY_NAMES[day]}s`);
return `${joinWords(names)} at ${time}`;
}
}
if (monthField === "*" && dayOfWeekField === "*") {
const day = parsePlainInt(dayOfMonthField, 1, 31);
if (day !== null) {
return `On the ${ordinal(day)} of the month at ${time}`;
}
}
return cron;
} catch {
return cron;
}
}