Upgrade: runtime-js due work, scheduler + executor.wake (the wake hook)
runtime-js used to pace a session's due work with two in-process timers, both lost when the process exits:
- CP-138's client-tool deadline timer;
- CP-217's owed remote stop
setTimeout.
They are now one rule, the arm contract: every arm asks for a wake at the session's earliest due time across every kind of work, and asks for nothing when nothing is due. An app scheduler can own the timing, so a serverless or scale-to-zero host advances a run at a client-tool deadline, retries the stops a session owes, and recovers a wake-started run whose process died.
It is a major release of @helix-agents/runtime-js (an executor option is removed), a minor of @helix-agents/core (the scheduler interface, two optional pending-call fields and the error code framework_due_work_unscheduled), and a patch of @helix-agents/runtime-cloudflare (the DO's wiring; no behaviour change). The store packages do not change.
Wiring a scheduler
import { JSAgentExecutor, type WakeScheduler } from '@helix-agents/runtime-js';
const MAX_DELAY_MS = 15 * 60_000; // your queue's longest delay (SQS: 15 minutes)
const scheduler: WakeScheduler = {
schedule: (sessionId, atMs) => {
const at = Math.min(Math.max(atMs, Date.now()), Date.now() + MAX_DELAY_MS);
return queue.send({ sessionId }, { delayUntil: new Date(at), dedupeKey: `${sessionId}:${at}` });
},
};
const executor = new JSAgentExecutor(stateStore, streamManager, llm, { scheduler, agentRegistry });
// The queue's handler, in any process (pass what your entries pass):
queue.handle(async ({ sessionId }) => {
const woke = await executor.wake(sessionId, { usageStore });
await woke.settled; // or ctx.waitUntil(woke.settled), before you ack
});WakeScheduler has one method. It is core's interface (@helix-agents/core), re-exported by runtime-js, so a store or queue package can implement it.
schedule(sessionId, atMs)means "make sure a wake happens at or beforeatMs". You may keep an earlier pending wake. Never move a pending wake later, and never remove one. A pastatMsmeans now.- There is no
cancel. Early, stale and duplicate wakes are normal and harmless:wake()re-reads the store, does what is due, and re-arms. A wake that did nothing asks for nothing sooner than 1 s later (a waker whose clock is behind your scheduler's never loops). A deadline is "not before": an expiry may land up to that minimum re-arm delay (1 s) after its deadline. - Dedupe by
sessionIdandatMs, never bysessionIdalone. On queues with a dedupe window (SQS FIFO, QStash) or names a queue keeps blocked for a while (Cloud Tasks, BullMQ job ids), a session-only key silently drops a re-arm. - Clamp to your queue's maximum delay. The early wake re-arms the rest.
- Quick and durable. Each call is bounded by
schedulerTimeoutMs(default 10 000 ms); past it the arm counts as failed. - A cron or a poller instead of a queue: keep a table
wakes(session_id PRIMARY KEY, at_ms), upsert withat_ms = LEAST(wakes.at_ms, excluded.at_ms), and on each tick claim each due row by DELETING it, callexecutor.wake(sessionId), awaitsettled, and put the claimed time back on a failure. A self-polling implementation takesexecutor.wake(coreWakeFn) in its ownstart(onDue).
executor.wake(sessionId, options?) (it took the agent before):
- The agent comes from the session's stored type, through your
agentRegistry. A scheduler now requires anagentRegistry: an executor built without one is refused (framework_not_supported). - An unknown type rejects
AgentResolutionError(framework_agent_not_found) before anything is written; the run is untouched. A missing session rejectsstate_session_not_found. - It returns when its work has STARTED, with
settled: it settles when the work is DONE (the continued run settled and the wake's final arm recorded), resolving{ run?: { runId, status }, nextDueAt? }. It rejectsDueWorkUnscheduledErrorwhen that final arm failed; let it fail the delivery so your queue retries. It is marked handled: ignoring it never makes an unhandled rejection. - It rejects when the store cannot be read, a write fails, a continuation failed transiently before its run-start commit, or (with nothing continued) its final arm failed.
Reads never fail on the scheduler; writes do:
- A handle's
result()never rejects, andgetHandle()returns its handle. A failed or timed-outscheduleon those paths is logged (due_work.schedule_failed) and reported to the newonDueWorkUnscheduled({ sessionId, site: 'outcome' | 'reconnect', error })option; the next touch re-arms. submitToolResult()andwake()still rejectDueWorkUnscheduledError(framework_due_work_unscheduled, retryable). Nothing is undone; a re-sent submit answersalready_completedand arms again.- agent-server adds no route for this: the handler is yours, behind your own auth.
Give-up is durable. A continuation that fails to start transiently is retried across wakes, in any process, and counted on its batch (PendingClientToolCall.continuationAttempts); at 5 its run ends failed with the classified error. A refused or fatal start ends it at once.
Stranded continuations. With a scheduler, a wake-started run whose process died (its JS run lease lapsed on the store's clock, plus a 10 s grace) is driven again by a later wake: a continue entry that supersedes it, gated by its run-start commit. A wake arms this right after its continuation starts, so a healthy long run costs one no-op wake per lease period. Runs your app started itself are not covered.
Reference: durable due work.
Breaking: clientToolDeadlineTimer is removed
| Before | After |
|---|---|
clientToolDeadlineTimer: { schedule } | dueWorkTimer: { schedule }. The ONE timer per session runs the owed stops too |
clientToolDeadlineTimer: false | dueWorkTimer: false, plus a scheduler or onOwedStopsChanged |
dueWorkTimer: falsenow means the host paces ALL its due work: through ascheduler, or its own alarms andonOwedStopsChanged(the CF Durable Object). With neither, the constructor throwsframework_not_supported: before, the owed stops still had their own in-process timer, so nothing would retry them now.dueWorkTimer.schedulenow drives the single timer per session, which also covers the owed stops. A host that held deadline fires throughschedulewould now hold the owed-stop retries as well. UsedueWorkTimer.sourceGate, which withholds one kind of work ('client_tool_deadlines'or'owed_remote_stops'), and is asked only by the in-process timer.onOwedStopsChangedkeeps its meaning: the host paces the owed stops, and they are left out of the executor's own arms.
Behaviour changes without a scheduler
- One timer per session instead of two. The fire times are the same (each kind of work's own due time); the earliest one wins. A fire that did nothing re-arms no sooner than 1 s later.
- It arms where runtime-js always armed: a suspended run's outcome and a reconnect of a
pausedsession (an ended run arms only the stops it still owes, at their own write sites). - A deadline continuation survives a process restart. Before, a landed expiry's continuation was remembered in memory, so a process that died between the expiry and the continuation left the run paused until the next request. Now the write that completes a batch stamps who continues it (
PendingClientToolCall.batchOwner). The next arm in any process (a reconnect, a submit, a wake) finds an expiry-completed batch due now and continues it. - A batch a client's submit completed is always the caller's (the router told it
caller_resumes). Before, an in-process timer that had expired an earlier call of the batch could also continue it; now the wake defers. - The give-up count is durable (
continuationAttempts): a continuation that keeps failing to start ends its run typed after 5 attempts, whichever process made them.
Deploying
- No migration.
batchOwnerandcontinuationAttemptsride in each pending entry, which every store keeps as one JSON value; a whole-state write never lowers the count (coremergePendingAnswers). A batch an older release completed carries no stamp: a wake does not continue it, and the next resume does, as before. - The CF DO passes
dueWorkTimer: falsewith itsonOwedStopsChanged. Its alarm expires through the shared resolver, so it stampsbatchOwner, but its continuation gate never reads it. - Known window: FU-JS-WAKE-OWNS-TOLD-CALLER. A submit saved just before another call's deadline, whose expiry lands before the router reads the batch, is told
caller_resumeswhile the batch is stamped the deadline's. Both continue, and the run-start commit keeps it to one. When the wake wins, the caller'sresume()loses its run-start commit typed (AgentAlreadyRunningError,state_run_start_conflict; overhandleChatStream, its 409 busy answer). This race already existed with the old timer.