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

shipped production is serving it opened this has it

Landed in pull #11626 · 2 runs · run

opened this

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.

  • Firing: the forge wakes the app if it sleeps, then POSTs path with 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.
  • Exactly-once from the app's side comes from the key: the template gives a helper that runs a handler once per key and answers 200 for a repeat.
  • Missed runs: if the forge was down or mid-release at the time, the run fires as soon as it is back if it is within the schedule's catchUp window (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.
  • An app can also arm timers at runtime: POST /api/v1/timers with its own token (at or in, path, optional key, optional body up to 64 KB), and cancel by key. Limits per app are a setting.
  • Seen and steered: the app's page shows each schedule in one row (next run, last run and how it went, in the owner's timezone) with Run now and Pause; GET /api/v1/repos/{owner}/{name}/schedules and an MCP tool answer the same. Every run is recorded with its attempts, duration, status and the first 2 KB of the response.
  • When it fails: a failed or missed run raises one ask for the app's owner (and their phone notify URL if set) with the reason in plain words; repeated failures do not repeat the ask. A schedule that fails five days running pauses itself and says so.
  • Costs nothing while waiting: no process, no CPU; the timer is a row. A fired job counts toward the app's own limits like any request.

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.

  • Tests with a fake clock: fires at the right instant across both daylight-saving changes; wakes a sleeping app; retries then fails with one ask; a duplicate delivery runs the handler once; a timer due during a restart fires after boot inside catchUp and is marked late; a preview does not fire production's schedule; pause and run-now work.
  • docs/APPS.md gains a "Time" section of one screen.
  • On production: morning-paper's schedule shows its next run on the app's page, and one morning's paper prints with no person and no session involved; paste that run's record. Do not close this until that has happened.
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.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs