utils/cron/cron_manager library

Classes

CronFields
Expanded cron fields — each is a sorted list of matching values.
CronJitterConfig
Cron scheduler tuning knobs.
CronScheduler
A running cron scheduler.
CronSchedulerOptions
Options for creating a cron scheduler.
CronTask
A scheduled cron task.
SchedulerLock
Scheduler lock data.
SchedulerLockOptions
Options for out-of-REPL callers that don't have bootstrap state.

Constants

kCheckIntervalMs → const int
Check interval for the scheduler timer.
kDefaultCronJitterConfig → const CronJitterConfig
Default jitter config.
kFileStabilityMs → const int
File stability threshold for watcher debouncing.
kLockProbeIntervalMs → const int
How often a non-owning session re-probes the scheduler lock.

Functions

addCronTask({required String cron, required String prompt, required bool recurring, required bool durable, String? agentId, List<CronTask>? sessionTasks}) → Future<String>
Append a task. Returns the generated id.
buildMissedTaskNotification(List<CronTask> missed) → String
Build the missed-task notification text.
computeNextCronRun(CronFields fields, DateTime from) → DateTime?
Compute the next DateTime strictly after from that matches the cron fields, using the process's local timezone. Walks forward minute-by-minute. Bounded at 366 days; returns null if no match.
cronToHuman(String cron, {bool utc = false}) → String
Convert a cron expression to a human-readable string. Covers common patterns; falls through to the raw cron string for anything else.
findMissedTasks(List<CronTask> tasks, int nowMs) → List<CronTask>
A task is "missed" when its next scheduled run (computed from createdAt) is in the past.
getCronFilePath({String? dir}) → String
Path to the cron file. dir defaults to the project root.
hasCronTasksSync({String? dir}) → bool
Sync check for whether the cron file has any valid tasks.
isRecurringTaskAged(CronTask t, int nowMs, int maxAgeMs) → bool
True when a recurring task was created more than maxAgeMs ago and should be deleted on its next fire.
jitteredNextCronRunMs(String cron, int fromMs, String taskId, [CronJitterConfig cfg = kDefaultCronJitterConfig]) → int?
Same as nextCronRunMs, plus a deterministic per-task delay to avoid a thundering herd when many sessions schedule the same cron string.
listAllCronTasks({String? dir, List<CronTask>? sessionTasks}) → Future<List<CronTask>>
File-backed tasks + session-only tasks, merged.
markCronTasksFired(List<String> ids, int firedAt, {String? dir}) → Future<void>
Stamp lastFiredAt on the given recurring tasks and write back.
nextCronRunMs(String cron, int fromMs) → int?
Next fire time in epoch ms for a cron string, strictly after fromMs. Returns null if invalid or no match in the next 366 days.
oneShotJitteredNextCronRunMs(String cron, int fromMs, String taskId, [CronJitterConfig cfg = kDefaultCronJitterConfig]) → int?
Same as nextCronRunMs, minus a deterministic per-task lead time when the fire time lands on a minute boundary matching CronJitterConfig.oneShotMinuteMod.
parseCronExpression(String expr) → CronFields?
Parse a 5-field cron expression into expanded number arrays. Returns null if invalid or unsupported syntax.
readCronTasks({String? dir}) → Future<List<CronTask>>
Read and parse .neomage/scheduled_tasks.json. Returns an empty task list if the file is missing, empty, or malformed. Tasks with invalid cron strings are silently dropped.
releaseSchedulerLock({SchedulerLockOptions? opts, String? sessionId}) → Future<void>
Release the scheduler lock if the current session owns it.
removeCronTasks(List<String> ids, {String? dir, List<CronTask>? sessionTasks}) → Future<void>
Remove tasks by id. No-op if none match.
tryAcquireSchedulerLock({SchedulerLockOptions? opts, String? sessionId}) → Future<bool>
Try to acquire the scheduler lock for the current session. Returns true on success, false if another live session holds it.
writeCronTasks(List<CronTask> tasks, {String? dir}) → Future<void>
Overwrite .neomage/scheduled_tasks.json with the given tasks. Creates .neomage/ if missing.