Skip to content

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 ​

ts
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 before atMs". You may keep an earlier pending wake. Never move a pending wake later, and never remove one. A past atMs means 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 sessionId and atMs, never by sessionId alone. 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 with at_ms = LEAST(wakes.at_ms, excluded.at_ms), and on each tick claim each due row by DELETING it, call executor.wake(sessionId), await settled, and put the claimed time back on a failure. A self-polling implementation takes executor.wake (core WakeFn) in its own start(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 an agentRegistry: 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 rejects state_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 rejects DueWorkUnscheduledError when 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, and getHandle() returns its handle. A failed or timed-out schedule on those paths is logged (due_work.schedule_failed) and reported to the new onDueWorkUnscheduled({ sessionId, site: 'outcome' | 'reconnect', error }) option; the next touch re-arms.
  • submitToolResult() and wake() still reject DueWorkUnscheduledError (framework_due_work_unscheduled, retryable). Nothing is undone; a re-sent submit answers already_completed and 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 ​

BeforeAfter
clientToolDeadlineTimer: { schedule }dueWorkTimer: { schedule }. The ONE timer per session runs the owed stops too
clientToolDeadlineTimer: falsedueWorkTimer: false, plus a scheduler or onOwedStopsChanged
  • dueWorkTimer: false now means the host paces ALL its due work: through a scheduler, or its own alarms and onOwedStopsChanged (the CF Durable Object). With neither, the constructor throws framework_not_supported: before, the owed stops still had their own in-process timer, so nothing would retry them now.
  • dueWorkTimer.schedule now drives the single timer per session, which also covers the owed stops. A host that held deadline fires through schedule would now hold the owed-stop retries as well. Use dueWorkTimer.sourceGate, which withholds one kind of work ('client_tool_deadlines' or 'owed_remote_stops'), and is asked only by the in-process timer.
  • onOwedStopsChanged keeps 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 paused session (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. batchOwner and continuationAttempts ride in each pending entry, which every store keeps as one JSON value; a whole-state write never lowers the count (core mergePendingAnswers). 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: false with its onOwedStopsChanged. Its alarm expires through the shared resolver, so it stamps batchOwner, 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_resumes while the batch is stamped the deadline's. Both continue, and the run-start commit keeps it to one. When the wake wins, the caller's resume() loses its run-start commit typed (AgentAlreadyRunningError, state_run_start_conflict; over handleChatStream, its 409 busy answer). This race already existed with the old timer.

Released under the MIT License.