Last updated:
Not all work should happen inside the request that triggers it. Sending a
welcome email, expiring a draft, reconciling with Stripe, or sweeping stale rows
all want to happen later: after the mutation commits, on a delay, or on a
recurring schedule. @lunora/scheduler covers both
shapes. Deferred jobs run through ctx.scheduler, recurring jobs through Cron
Triggers, both backed by a SchedulerDO you mount once per app.
Deferring a function
ctx.scheduler is available on MutationCtx and ActionCtx (not on a
read-only QueryCtx). It enqueues a function to run later:
ctx.scheduler.runAfter(delayMs, target, args?, options?)runs after a delay.ctx.scheduler.runAt(timestampMs, target, args?, options?)runs at an absolute time, given as an epoch-millisecond number. Passdate.getTime()for aDate: anything that is not a finite number is refused withINVALID_INPUT.
options.retry sets the job's retry policy.
Both return the scheduled job's id (a string) so you can track or cancel it. The
target is either a generated reference (internal.notifications.notifySubscribers,
api.…) or the equivalent "namespace:function" path string, and it may be a
mutation or an action — not a query. A reference is the better habit: it is
checked against what actually exists, where a path string is not.
Internal functions, which aren't exposed to
clients, are the usual choice for follow-up work.
import { internal } from "@/lunora/_generated/internal";
import { mutation, v } from "@/lunora/_generated/server";
export const publishPost = mutation.input({ postId: v.id("posts") }).mutation(async ({ ctx, args: { postId } }) => {
await ctx.db.patch("posts", postId, { status: "published" });
// Fire-and-forget follow-up: notify subscribers 30s later.
await ctx.scheduler.runAfter(30_000, internal.notifications.notifySubscribers, { postId });
});runAt is the same idea pinned to a wall-clock time, e.g. expire a trial at a
stored deadline:
await ctx.scheduler.runAt(trial.endsAt, "billing:expireTrial", { userId });Scheduling an agent or workflow
runAfter / runAt also accept a generated durable-target reference
(agents.<name> from @lunora/agent or
workflows.<name> from @lunora/workflow) instead
of a "namespace:function" path. Each fire starts a fresh durable instance
of that agent/workflow, so a one-shot delayed agent run is a scheduled target:
import { mutation, v } from "@/lunora/_generated/server";
import { agents } from "@/lunora/_generated/api";
export const ticketOpened = mutation.input({ ticketId: v.id("tickets") }).mutation(async ({ ctx, args: { ticketId } }) => {
await ctx.db.patch("tickets", ticketId, { state: "open" });
// Kick off a durable support-agent run five minutes from now.
await ctx.scheduler.runAfter(5 * 60_000, agents.support, { prompt: "Draft a first reply", ticketId });
});The second argument's shape decides the dispatch: a string path runs a Lunora
function, a generated agents.<name> / workflows.<name> reference starts a new
durable instance with the args as its run input. For a recurring agent, give
cronJobs() the same agents.<name> target; see
recurring jobs below.
Scheduling from a mutation vs. an action
The two contexts schedule identically, but the intent differs:
- From a mutation, scheduling moves a side effect out of the transactional
read/write scope. A mutation can't call
fetch()or write to R2, so it schedules an action to do that once the write has committed. The job is held until the commit and dropped if the mutation rolls back, so it can never fire for a write that never landed — you still get the job id back synchronously, so you can store it on the row andcancelit later. - From an action, scheduling chains further async work: retry an external call later, or fan a long job out into stages. An action has no transaction to wait for, so its jobs are enqueued immediately.
import { mutation, v } from "@/lunora/_generated/server";
export const orderPlaced = mutation.input({ orderId: v.id("orders") }).mutation(async ({ ctx, args: { orderId } }) => {
await ctx.db.patch("orders", orderId, { state: "placed" });
// The action does the external work the mutation isn't allowed to.
await ctx.scheduler.runAfter(0, "payments:charge", { orderId });
});runAfter(0, ...) is the idiomatic "do this right after I commit, but not in my
transaction" hand-off — literally so: the job reaches the scheduler after the
COMMIT, in the order the handler scheduled them.
If the job can't reach the scheduler
Everything between the COMMIT and the scheduler's acknowledgement happens
outside the transaction, so it can fail on its own: the SchedulerDO
unreachable, the shard evicted mid-hand-off. The write is durable by then and the
job is not, and rolling back is no longer on the table.
So the shard takes durable custody of each deferred job as the handler
schedules it — a row written inside the same transaction as the writes, released
once the scheduler has the job. A hand-off that fails still raises (a caller
error like a duplicate job id has to reach you), but what it can no longer do is
lose the job: the entry survives, and the shard re-offers it on a backoff ladder
until the scheduler accepts it. The retry reuses the id you were handed, so a job
that did land is recognised rather than scheduled twice, and the cancel(id) you
stored on a row keeps working throughout.
A job the scheduler refuses eight times over is parked: it stops being
retried, is logged at error naming its id and target, and is kept for a week from then so
you can see what was promised and never enqueued. That is the one case where a
scheduled job is dropped without the mutation being rolled back — and it is
reported rather than silent.
Studio's Schedule → Outbox view lists what a shard is holding for the
scheduler, retrying or parked. Retry now puts an entry back on the ladder
from its first rung, which is how a parked job gets a second chance once the
cause is fixed. Drop removes it for good, which is the only way to cancel a
job the scheduler has not accepted: ctx.scheduler.cancel(id) reaches only
jobs the SchedulerDO holds. A drop also asks the scheduler to cancel the id,
because the hand-off may have landed without the shard learning of it; if a
hand-off is in flight when you drop, the job is cancelled as soon as it lands.
If the scheduler cannot be reached to confirm the cancel, the entry is parked so it is never handed over,
and the drop reports the error; drop it again once the scheduler answers. On a shard with no scheduler
configured nothing will ever answer, so the first drop parks the entry and a second drop removes it,
recorded as unconfirmed. A drop the scheduler answers with "not found" still applies, but is logged:
that is also its answer for a job an earlier hand-off delivered without the shard hearing back, which
may already have run.
Entries are listed oldest first, parked or not. Both are admin RPCs (__lunora_admin__:retryOutboxEntry
and dropOutboxEntry), are recorded in the audit log, and act on one
shard at a time. The MCP server's lunora_get_schedule_outbox tool reads the
same list.
Retry policy
A job whose handler throws is retried by the SchedulerDO: five retries with
exponential backoff from 30 seconds, then a dead-letter park. Pass a retry
option as the fourth argument to change that for one job:
await ctx.scheduler.runAfter(0, internal.billing.syncInvoice, { invoiceId }, { retry: { maxAttempts: 10, maxMs: 600_000 } });retry.forever: true keeps retrying instead of dead-lettering, for work that
must eventually happen. Its delay is clamped to between 1 second and 30 minutes:
the default backoff climbs to 30 minutes, while a maxMs below that keeps it
retrying more often. The SchedulerDO logs it once at warn at the attempt that
would have dead-lettered it. The same opt-in keeps a job in the shard's custody
past the eight attempts above: it is logged once at warn when it reaches that
point and retried every 30 minutes after, until the scheduler accepts it. A call
the scheduler refuses as invalid is still parked. While a forever job is still
waiting in custody, drop it from the Outbox view; once the scheduler holds it,
ctx.scheduler.cancel(id) works as usual.
ctx.scheduler always goes to the SchedulerDO namespace the app declares, so
forever is honoured wherever that runs. Calling a SchedulerHost directly is
different: the Node host's schedule() refuses retry.forever with
INVALID_INPUT, since its job table has no unbounded retry.
Inspecting and cancelling
ctx.scheduler also exposes list(), get(id), and cancel(id) for managing
pending jobs. For example, cancel a scheduled reminder when the user completes
the action first:
const { cancelled } = await ctx.scheduler.cancel(reminderId);get(id) reports where a job is in its life as state: pending, running,
then how it ended — succeeded (the dispatch returned 2xx; for a workflow or
agent target, that its instance started), failed (its retry budget ran out and
it was dead-lettered, with the reason in error) or canceled. Finished jobs
keep answering, with completedAt, for seven days; after that get returns
null, as it does for an id that was never scheduled. Studio's Schedule tab
lists them under History.
You can also read pending jobs from a query via the _scheduled_functions
system table (ctx.db.system), which is
read-only and eventually consistent.
Recurring jobs (Cron Triggers)
For work on a fixed cadence (nightly cleanups, hourly digests) declare Cron
Triggers. They run on the platform's cron schedule, and the worker's
scheduled() handler dispatches the target straight to its shard — not
through the SchedulerDO:
import { createCronTrigger } from "@lunora/scheduler";
import { internal } from "@/lunora/_generated/internal";
export const triggers = [
createCronTrigger({ schedule: "0 3 * * *", fn: internal.cleanup.cleanupOldMessages }),
createCronTrigger({ schedule: "*/15 * * * *", fn: internal.presence.sweep, args: { roomId: "lobby", tenantId: "" } }),
];schedule is the cron expression and fn is a function reference from
_generated/api, not a path string — omit either and createCronTrigger throws
"createCronTrigger() requires schedule and fn". Each call returns
{ crons, wranglerJsonc, dispatcher }; paste wranglerJsonc under
triggers.crons in your wrangler.jsonc.
The CLI's wrangler validator surfaces a missing or unreachable trigger as an error during dev, so a bad reference fails fast rather than silently never firing.
A cron fire gets none of the SchedulerDO's durability. The retry ladder, exponential backoff, and dead-letter park described above belong to
ctx.scheduler jobs, which the Durable Object (DO) owns. A cron trigger is dispatched once from the worker's scheduled() handler; a failure is logged as
CRON_JOB_FAILED and the tick is gone until the next one. Make cron handlers idempotent, and re-derive missed work from your own data rather than assuming
a redelivery.
A code-defined cron job (cronJobs()) never overlaps itself. Before a run
starts, the worker takes a per-job lease held in the SchedulerDO. A tick that
lands while the previous run of the same job is still going is skipped
instead of run alongside it, whichever isolate it lands in, and the skip is
recorded. Run now in Studio answers 409 CRON_JOB_IN_FLIGHT in the same
situation. A run that never reports back (its invocation was torn down) gives
up its lease after fifteen minutes, the platform's cron wall-clock limit, and is
recorded as failed. If the SchedulerDO can't be reached, the run goes ahead
without the guard rather than stopping the cron, and a warning is logged. A cron
that targets a workflow holds the lease only while it starts the instance, so a
long-running workflow can still overlap the next tick's instance.
Every fire is recorded: start, duration, outcome, the error of a failed run, and how many ticks it caused to be skipped. The last 50 per job are kept, and Studio's Cron triggers view shows each job's last run plus the recent history.
How dispatch works
A scheduled job is stored in the SchedulerDO sorted by its fire time and
dispatched on the DO's alarm. When it fires, the DO calls back into your worker
and the runtime runs the target function on the same code path as an RPC: same
context, same ctx.db. There's no separate "background worker" mental model to
keep. A scheduled mutation is your mutation, run later.
The one difference is the caller. A scheduled or cron dispatch is
server-initiated: it carries no end-user identity, so ctx.auth.userId is
null and ctx.ip is undefined. That is also what lets it reach internal
functions. Pass whatever the job needs to know about a user in its args, and
don't gate a scheduled function on ctx.auth.
Start lag
Each scheduled job's dispatch records a scheduler.lag_ms histogram on the
shard that runs it: the time from the job's due time to the moment it started,
one series per function (the function attribute). A code-defined cron job
records it too, measured from the tick's planned time. It rides the same metric
pipeline as ctx.metrics, so a configured sink exports it, and the Studio's
Schedule → Pools view lists it per job. A pooled job that waited for a free
slot counts the wait from its original due time; a retry counts only its own
attempt's lateness, not the backoff. A lag that keeps climbing means the queue
is falling behind. On the Node host, createNodePlatform dispatches due jobs
to the shard itself (when onFetch is wired) and stamps scheduledFor, so the
metric is recorded. If you pass your own onDispatch it replaces that
delivery; forward scheduledFor in the dispatch body to get the same metric.
See also
- Queries & mutations:
ctx.schedulerlives on mutation/action contexts. - Actions: the kind of function you typically schedule for external work.
- File storage: a common reason to defer a write out of a mutation.
- @lunora/scheduler:
SchedulerDOsetup and the dispatch contract.