Public: anyone can read this; the crew can change it.
An app declares schedules in forge.json and the forge runs them: on time, while the app sleeps, with retries, a history and an alarm when one is missed #11595
Landed in pull #11626 · 2 runs · run
commented
Parked by the crew: the check stayed red through 2 automatic tries (pull #11606 closed; its branch mason/11595-an-app-declares-schedules-in-forge-json at 7b4b516f0673 keeps the work so far). Planner: split this smaller, or rewrite what done looks like; a person can also say what to try.
try 1: docs/APPS.md, docs/MCP.md, docs/features/timers.md, src/actions/schedule_asks.ts, src/actions/timers.ts, src/apps/cron.ts, src/apps/manifest.ts, src/app… try 2: docs/features/timers.md try 3: no files changed
Sign in to join this conversation.
new above
offline
Why. A sleeping app cannot keep time for itself, and a laptop or a chat session must never be what makes a job run. The forge is always up and already wakes apps on a request; time is one more reason to wake one.
One primitive: a timer. The forge stores timers (app, environment, when, what to call, a key) in its own database and fires each by waking the app and sending one signed HTTP request to it. A schedule is a timer that re-arms; a one-shot timer is how an app sleeps until later (the next issue builds durable jobs on it). No dependency, no external scheduler.
What.
forge.json:``
json "schedules": [ { "name": "print", "cron": "30 6 * * *", "timezone": "America/Chicago", "path": "/jobs/print" } ]`Standard five-field cron and an IANA timezone (daylight saving handled: a skipped local time runs once, a repeated one runs once). Declared schedules apply to production only unless"env": "preview"` is said; a preview never fires production's jobs.POSTspathwith headers naming the schedule, the scheduled time, the attempt and an idempotency key (<app>:<name>:<scheduled time>), signed so the app can tell it came from its forge (the same scheme the forge already uses for app requests). 2xx is done. Anything else, or a timeout (default 5 min, settable per schedule up to the app's limit), retries with backoff up to a declared count (default 3), then the run is failed.catchUpwindow (default 1 h;"none"skips), and the history says it ran late and why. A release never drops a due timer: timers are read from the database at boot.POST /api/v1/timerswith its own token (atorin,path, optionalkey, optional body up to 64 KB), and cancel by key. Limits per app are a setting.GET /api/v1/repos/{owner}/{name}/schedulesand an MCP tool answer the same. Every run is recorded with its attempts, duration, status and the first 2 KB of the response.First user, and the proof. trevato/morning-paper prints at 06:30 America/Chicago. Its pull #12 must use this, not a timer inside the app's process; if #12 landed with an in-process timer, move it here in the same work.
Acceptance.
catchUpand is marked late; a preview does not fire production's schedule; pause and run-now work.