Skip to main content
@clawboo/scheduler holds the pure scheduling rules behind Routines: how a schedule is written, when it fires next, how its runs land on the board calendar, what a fire creates, and the schedule-source layer that merges Clawboo’s routines with an OpenClaw Gateway’s own cron jobs and the Hermes agents’ own jobs. It is browser-safe, and it is the only place croner is imported, so the Routines view does next-run math in the browser with the same code the server fires on. Use this page when you change how routines are scheduled or listed. The engine that fires them is on How routines run, the REST surface on Schedules API, and the how-to on Run work on a schedule with routines.

Two spec forms

nextOccurrence(spec, fromMs, timeZone?) returns the next run strictly after fromMs, or null when the spec will never fire again (a spent one-shot). A cron expression is wall-clock time read in timeZone, an IANA name; without one it is read in the process’s own zone. A one-shot is a fixed instant and ignores it. The server passes the scheduler time zone (GET /api/schedules/time-zone) whenever one is set. probeCronSpec(spec, timeZone?) validates a spec when it is registered, and both throw InvalidCronSpecError for a malformed one. Every other part of the system (the routines ledger, the ticker, the REST layer) stores precomputed epoch-millisecond times, so a change of cron library touches one file, src/occurrence.ts.

The calendar projection

occurrencesInWindows(spec, bounds, { after, first, countCap, timesCap, timeZone }) spreads a spec’s future runs over consecutive windows, where window i runs from bounds[i] up to bounds[i + 1]. The board calendar sends the viewer’s local midnights as the bounds, which keeps daylight-saving days right, and GET /api/schedules/occurrences serves the result. Each window reports a capped count, a more flag when the cap was hit, and the first few run times. Work is bounded by the windows and the cap, not by how often the spec fires. Bounds that are not at least two finite, strictly ascending numbers throw RangeError.

What a fire creates

TaskTemplate (validated by taskTemplateSchema, parsed with parseTaskTemplate, which returns null for an invalid one) is what each fire materializes:
  • target is team (the instructions go to the team’s chat, where its lead picks them up) or agent (a board task run through the task runner). A template with no target is an agent routine (routineTargetOf).
  • title, description, kind (default code), priority (default 0), repoPath and model describe the task. With a repoPath, a code fire gets its own worktree; without one, the wake bridge runs the fire as a research task with no checkout (runKindFor in apps/web/server/lib/routines/wakeBridge.ts).
  • maxNodeCents sets a per-run cost ceiling, and teamTaskId binds the routine to an existing board task instead of creating one per fire. A bound routine must be a one-shot (BoundRecurringScheduleError).

Schedule sources

The Routines view lists three kinds of schedule through one interface, ScheduleSource, each normalized to a ScheduleRecord: ScheduleMultiplexer merges every source’s read(). A source that fails reports a degraded status instead of failing the whole list. Writes go to the source that owns the id (ids are <source>:<raw id>, built by makeScheduleId and split by parseScheduleId), after three checks in order: an unknown source throws UnknownScheduleError, an observe-only source throws UnsupportedScheduleWriteError, and creating a team-task schedule on a runtime-own-life source (the OpenClaw Gateway’s or Hermes’s) throws TeamTaskDomainViolationError. The pattern it shares with the capability sources is described on Capability and schedule sources. Every error class carries a code for callers to branch on. The REST layer maps them to statuses and sends each class’s own code, so a malformed spec comes back as a 400 with invalid_cron_spec. The full mapping is on Schedules API.

Who uses it

Only apps/web. On the server: the routines ticker and wake bridge, the OpenClaw routine dispatcher, the three schedule sources, and the /api/schedules routes. In the SPA: the Routines view, which imports the spec helpers as well as the types, and the board calendar. @clawboo/db does not depend on this package; its routines ledger stores precomputed times.

Test it

Run pnpm --filter @clawboo/scheduler test. The spec, window, record, template and multiplexer cases each have their own file under src/__tests__/; pass explicit fromMs and after values in a new case so it does not depend on the current time.
Last modified on November 14, 2026