Why. Prior art the owner named: Vercel's workflow ("use workflow", steps, sleep) and Cloudflare's Durable Objects alarms and Workflows. What they give is one thing: code that reads top to bottom, can wait an hour or a week without a process running, survives a deploy, and never repeats a step that already finished. With timers (the issue before this) the forge has the only server-side piece that needs; the rest is a small library in the app template.
How it runs: each step result is saved in the app's own data, keyed by job run and step name. sleep and waitFor save where the job is, arm a forge timer and return; the process is free to stop. When the timer fires (or the event is sent with job.signal(event, data)), the job function runs again from the top and every finished step returns its saved result at once, so it continues where it left off. Steps must be safe to retry until they return; the docs say so in two lines with the idempotency helper.
A step that throws is retried with backoff (declared per step, default 3), then the run is failed and the owner is asked once, as for a schedule.
A deploy in the middle is fine: saved steps are data. A changed job is detected (a step name that no longer exists) and the run is failed plainly rather than continuing wrongly; version lets old runs finish on old code paths when the author wants.
Seen and steered: the app's page lists job runs (name, key, started, where it is now: running, sleeping until, waiting for, done, failed), with Cancel and Retry from the failed step; the API and an MCP tool answer the same.
Limits: step results up to 256 KB each; runs per app and timers per app are settings.
Acceptance. Tests with a fake clock and a process that is killed between steps: a job with step → sleep 3 days → step → waitFor finishes with each step executed exactly once; a signal wakes a waiting job; a thrown step retries then fails with one ask; a restart of the forge and of the app mid-sleep changes nothing. The template's README has a "Jobs" section of one screen with the example above. A worked example ships in the template: a reminder that waits a day.
Why. Prior art the owner named: Vercel's workflow (
"use workflow", steps,sleep) and Cloudflare's Durable Objects alarms and Workflows. What they give is one thing: code that reads top to bottom, can wait an hour or a week without a process running, survives a deploy, and never repeats a step that already finished. With timers (the issue before this) the forge has the only server-side piece that needs; the rest is a small library in the app template.What.
``
ts export const remind = job("remind", async (ctx, input) => { const order = await ctx.step("load", () => loadOrder(input.id)); await ctx.sleep("wait", { days: 3 }); if (!(await ctx.step("paid?", () => isPaid(order)))) await ctx.step("email", () => sendReminder(order)); const reply = await ctx.waitFor("reply", { event:reply:${order.id}, timeout: { days: 7 } }); return reply ?? "no reply"; }); await remind.start({ id }, { key:remind:${id}});``stepresult is saved in the app's own data, keyed by job run and step name.sleepandwaitForsave where the job is, arm a forge timer and return; the process is free to stop. When the timer fires (or the event is sent withjob.signal(event, data)), the job function runs again from the top and every finished step returns its saved result at once, so it continues where it left off. Steps must be safe to retry until they return; the docs say so in two lines with the idempotency helper.versionlets old runs finish on old code paths when the author wants.Acceptance. Tests with a fake clock and a process that is killed between steps: a job with step → sleep 3 days → step → waitFor finishes with each step executed exactly once; a signal wakes a waiting job; a thrown step retries then fails with one ask; a restart of the forge and of the app mid-sleep changes nothing. The template's README has a "Jobs" section of one screen with the example above. A worked example ships in the template: a reminder that waits a day.