Workflow SDK Changelog

The latest Workflow SDK releases, improvements, and fixes.

v5.5.0

Minor Changes

  • #5227 e866ab9 Thanks @VaguelySerious! - Remove opt-out and test-only environment variables that are no longer needed. The runtime no longer reads WORKFLOW_INLINE_EARLY_ADVANCE, WORKFLOW_RETURN_VALUE_LONG_POLL, WORKFLOW_SLOT_GAP_CHECK, WORKFLOW_LOG_ORDER_DRAWS, WORKFLOW_INLINE_OWNERSHIP or WORKFLOW_BATCH_TRANSITIONS, and the behavior they could switch off is always on. WORKFLOW_SEALED_LOG (deprecated) is no longer read, and @workflow/world no longer exports SEALED_LOG_ENV_VAR: set WORKFLOW_SPEC_VERSION=6 to create new runs without the sealed log. The Vercel World no longer reads WORKFLOW_MAX_CHUNKS_PER_REQUEST or WORKFLOW_TEST_LIMIT_OVERRIDES, and the Local and Postgres Worlds no longer read WORKFLOW_LOCAL_RUN_STATUS_POLL_INTERVAL_MS and WORKFLOW_POSTGRES_RUN_STATUS_POLL_INTERVAL_MS.

  • #5214 1bcd7ef Thanks @karthikscale3! - Add createStateResolver() to workflow/observability and createRunStateHydrator() to @workflow/web-shared, so run inspectors show the actual values of state stored by reference.

Patch Changes

v5.4.0

Patch Changes

  • #5226 50d425f Thanks @pranaygp! - Removed: reading response.body with getReader(), values() or for await inside workflow functions (added in 5.3.0) throws again. Use response.json(), response.text() or response.arrayBuffer(), or make the request and read the response in a step function. If you assigned globalThis.fetch = fetch to run AI SDK calls in a workflow function, move those calls into a step function, or use AI SDK's WorkflowAgent for agents.
  • Updated dependencies [e1bce44, 9bed0a7, 9bed0a7, 6291260, 50d425f, 50a61e7, 11a904f]:
    • @workflow/core@5.4.0
    • @workflow/cli@5.0.8
    • @workflow/nitro@5.0.8
    • @workflow/nuxt@5.0.8
    • @workflow/next@5.0.8
    • @workflow/astro@5.0.8
    • @workflow/nest@5.1.6
    • @workflow/rollup@5.0.8
    • @workflow/sveltekit@5.0.8
    • @workflow/typescript-plugin@5.0.0

v5.3.0

Minor Changes

  • #4996 eb07a8d Thanks @alangenfeld! - Add start(workflow, args, { hook: { token, metadata, experimental_minRetention } }), which admits the run and creates its start Hook in one atomic step, and throws HookConflictError naming the owner for a duplicate, which never becomes a run. resumeHook(token) works as soon as the run is admitted, and payloads sent before the workflow calls createHook({ token }) are delivered in order once it does; that createHook() binds to the start Hook without registering a new one. Disposing the start Hook releases the token immediately; otherwise the run's end releases it, after any experimental_minRetention (there is no default retention). cancel() of a candidate that never became a run fences it.

Patch Changes

v5.2.3

Patch Changes

  • Updated dependencies [91297ab, 0bc17d7, 0bc17d7, 42077f2, 59b76f8, 59b76f8, 73a7efa, 2163290, 0d434fc, cd2f917]:
    • @workflow/core@5.2.3
    • @workflow/cli@5.0.6
    • @workflow/errors@5.0.5
    • @workflow/next@5.0.6
    • @workflow/nitro@5.0.6
    • @workflow/typescript-plugin@5.0.0
    • @workflow/astro@5.0.6
    • @workflow/nest@5.1.4
    • @workflow/rollup@5.0.6
    • @workflow/sveltekit@5.0.6
    • @workflow/nuxt@5.0.6

v5.2.2

Patch Changes

  • Updated dependencies [afdc68b, a04ecaa, 0948b0a]:
    • @workflow/core@5.2.2
    • @workflow/cli@5.0.5
    • @workflow/next@5.0.5
    • @workflow/nitro@5.0.5
    • @workflow/typescript-plugin@5.0.0
    • @workflow/astro@5.0.5
    • @workflow/nest@5.1.3
    • @workflow/rollup@5.0.5
    • @workflow/sveltekit@5.0.5
    • @workflow/nuxt@5.0.5

v5.2.1

Patch Changes

  • #4733 e6bd692 Thanks @VaguelySerious! - Add InBandSupersededError and optional inBand/expectedSeqInBand event-create params for the in-band writer fence. @workflow/world-vercel forwards them, does not retry a fenced write in-process, and records the fence on its event spans. The runtime does not use them yet.
  • Updated dependencies [1342a96, 854242e, e6bd692, fcb554b, 73a6ca3, fcb554b]:
    • @workflow/cli@5.0.4
    • @workflow/core@5.2.1
    • @workflow/errors@5.0.4
    • @workflow/utils@5.0.2
    • @workflow/next@5.0.4
    • @workflow/nitro@5.0.4
    • @workflow/typescript-plugin@5.0.0
    • @workflow/nest@5.1.2
    • @workflow/astro@5.0.4
    • @workflow/rollup@5.0.4
    • @workflow/sveltekit@5.0.4
    • @workflow/nuxt@5.0.4

v5.2.0

Patch Changes

  • #4438 515dc9f Thanks @TooTallNate! - Reject lifecycle registration inside steps, preserve reporting diagnostics for unreadable errors, and document executor registration and stream-lifetime constraints.
  • Updated dependencies [2036247, de8d985, 306a40f, 515dc9f, 878979b, 3949c07, 5589df7]:
    • @workflow/cli@5.0.3
    • @workflow/core@5.2.0
    • @workflow/next@5.0.3
    • @workflow/nitro@5.0.3
    • @workflow/typescript-plugin@5.0.0
    • @workflow/errors@5.0.3
    • @workflow/astro@5.0.3
    • @workflow/nest@5.1.1
    • @workflow/rollup@5.0.3
    • @workflow/sveltekit@5.0.3
    • @workflow/nuxt@5.0.3

v5.1.0

Minor Changes

  • #4578 941e031 Thanks @wycats! - Export the existing Serializable type from @workflow/core and workflow.

Patch Changes

  • Updated dependencies [941e031, ab9e640, a216e77, 482b918, 09bc2f8, a7cc482, 8fa7584, 94e3890, c1e70ef, e71d1c7]:
    • @workflow/core@5.1.0
    • @workflow/next@5.0.2
    • @workflow/utils@5.0.1
    • @workflow/nest@5.1.0
    • @workflow/cli@5.0.2
    • @workflow/nitro@5.0.2
    • @workflow/typescript-plugin@5.0.0
    • @workflow/astro@5.0.2
    • @workflow/rollup@5.0.2
    • @workflow/sveltekit@5.0.2
    • @workflow/errors@5.0.2
    • @workflow/nuxt@5.0.2

v5.0.1

Patch Changes

  • #3251 b79ad01 Thanks @TooTallNate! - Add experimental threshold-based VM-memory snapshotting to the QuickJS engine via WORKFLOW_SNAPSHOT_THRESHOLD (or per-run executionContext.snapshotThreshold). Once the configured number of events has been processed since the last snapshot, suspensions persist a compressed, encrypted VM snapshot, which is later used for resumption. Runs without an encryption key are only snapshotted with WORKFLOW_SNAPSHOT_ALLOW_UNENCRYPTED=1
  • Updated dependencies [14dbfdc, 1fcf4bb, 0147fa5, 0e64f7b, a11d037, e915eab, b79ad01, 156e023, 3b09dd7, 98442de]:
    • @workflow/core@5.0.1
    • @workflow/next@5.0.1
    • @workflow/nitro@5.0.1
    • @workflow/cli@5.0.1
    • @workflow/astro@5.0.1
    • @workflow/nest@5.0.1
    • @workflow/rollup@5.0.1
    • @workflow/sveltekit@5.0.1
    • @workflow/typescript-plugin@5.0.0
    • @workflow/nuxt@5.0.1
    • @workflow/errors@5.0.1

v5.0.0

Major Changes

  • #3988 efbdc21 Thanks @pranaygp! - Breaking: hook.metadata on hooks returned by getHookByToken() and resumeHook() is now a lazy getter that returns a Promise, like run.returnValue, and needs to be awaited. Looking a hook up by token no longer pays for hydrating metadata that is never read.

  • #1217 e55c636 Thanks @pranaygp! - Initial v5 beta release

  • #3128 7959acc Thanks @NathanColosimo! - BREAKING CHANGE: Remove the deprecated experimental_setAttributes and ExperimentalSetAttributesOptions aliases; use setAttributes and SetAttributesOptions instead.

  • #1632 0a86de3 Thanks @TooTallNate! - BREAKING CHANGE: Remove @workflow/core/private and workflow/internal/private public subpath exports. The SWC compiler plugin no longer generates imports from these paths.

  • #3061 62d570e Thanks @NathanColosimo! - Remove the retired step route runtime and make queue health checks target the combined flow handler.

  • #3045 d813fb8 Thanks @NathanColosimo! - Deterministic sandbox hardening: crypto.subtle.digest in workflow functions now computes synchronously via node:crypto (byte-identical values, deterministic timing under replay); Atomics.waitAsync, async WebAssembly compilation, WeakRef, and FinalizationRegistry are no longer exposed (wall-clock timing and GC observation cannot be replayed).

Minor Changes

  • #1853 303b6da Thanks @TooTallNate! - Add opt-in wire-level framing for byte streams (type: 'bytes') so consumers can identify chunk boundaries — a prerequisite for transparent auto-reconnect. The framing decision is gated on a new framedByteStreams capability and recorded per-stream in the serialized ref (framing: 'framed-v1'); legacy raw streams continue to work unchanged.

  • #1981 9da2d76 Thanks @TooTallNate! - start() now delegates run ID generation to world.createRunId(options) when the world provides it, falling back to a monotonic ULID otherwise. The full options bag is passed through so worlds can read whichever fields they recognise. Adds a new region option that worlds may consume — when set, it is also forwarded onto the queue options so the initial workflow message is routed to the matching region.

  • #2062 20e8440 Thanks @pranaygp! - Add experimental dynamic workflows: start() accepts workflow source as a string, compiles and stores it with the run through the run-payload serialization pipeline, and replays from that stored code. Steps are exposed to the source through an explicit experimental_dynamic.steps map, which is not a security boundary: dynamic source runs with the deployment's full privileges. Off by default; a deployment opts in with WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS=1, and dynamic runs can only start on the current deployment.

  • #3145 1471f25 Thanks @VaguelySerious! - Strengthen the event-creation precondition guard: replay-context writes now also send the number of loaded events, so a snapshot that is missing an event is rejected instead of committing a divergent event log, and a rejection restarts the replay in-process (consuming the events a world may attach to the rejection) rather than re-committing the rejected payload or re-invoking over the queue. @workflow/world-local and @workflow/world-postgres do not implement the check.

  • #2266 a00d169 Thanks @VaguelySerious! - Add an opt-in optimistic-concurrency guard for event creation (WORKFLOW_PRECONDITION_GUARD=1): replay-context event creations send a stateUpdatedAt snapshot timestamp, and the runtime reloads the event log and retries (then falls back to a queue re-invocation) when the backend reports a newer out-of-band event with a 412 PreconditionFailedError.

  • #1854 8d75491 Thanks @TooTallNate! - Surface workflowCoreVersion from the responding deployment in healthCheck() results.

  • #2373 01c8c08 Thanks @pranaygp! - Replace hook.hasConflict (a Promise<boolean> property) with hook.getConflict(), a method returning a promise that suspends the workflow to commit hook registration and resolves with the conflicting Run when another active hook owns the token (or null once the hook is registered), without waiting for hook payload data. Code using await hook.hasConflict should migrate to const conflict = await hook.getConflict() and branch on conflict !== null.

  • #3230 31f92df Thanks @karthikscale3! - Lazy hook resumption: on a fast path, resumeHook() writes the hook_received event and dispatches the workflow queue message concurrently instead of sequentially, cutting a round trip off resume latency. A (runId, resumeId) dedup constraint keeps the two writers converging on exactly one event; the runtime falls back to the sequential path when dedup support is unavailable or when WORKFLOW_DISABLE_LAZY_HOOK_RESUME=1. resumeHook() resolves to a ResumedHook (a Hook plus an optional resilientResume: true flag, set only when the direct write failed transiently and the resume was recovered via the queue consumer's re-ensure) — preserving the contract introduced alongside the resilient-resume work.

  • #3700 9b1b8c7 Thanks @VaguelySerious! - Pin correlation-ID draw order to event-log order (Node.js VM engine), so two concurrent replays of the same run assign the same IDs even when one loaded a shorter event-log prefix. Set WORKFLOW_LOG_ORDER_DRAWS=0 to opt back into arrival-order delivery resolution.

  • #2226 ae8d6fe Thanks @pranaygp! - Allow passing initial run attributes through start(), and speed up workflow-level setAttribute calls by using native events for recording attributes.

  • #1616 71d39d2 Thanks @TooTallNate! - Use custom class serialization for Run across runtime and workflow VM contexts, and add e2e coverage for Run instance boundary roundtrips

  • #2363 926a5e7 Thanks @karthikscale3! - Add WORKFLOW_TRACE_MODE with a new linked default: each workflow/step invocation span is now its own trace root with span links to the delivery and run-origin contexts, instead of one trace spanning the entire run. world-vercel now explicitly injects W3C traceparent/tracestate/baggage headers on outgoing workflow-server requests.

    Span names are also friendlier: workflow and step spans now use the short function name (e.g. workflow.execute processOrder, step.execute chargeCard, workflow.start processOrder) instead of the uppercase prefixes and full machine names (WORKFLOW_V2 workflow//./src/jobs/order//processOrder). The full name remains available in the workflow.name / step.name span attributes, and new workflowDisplayName / stepDisplayName helpers are exported from @workflow/utils.

    Behavioral changes to telemetry under the new default (set WORKFLOW_TRACE_MODE=continuous to restore the previous trace shape exactly; the span-name change applies in both modes):

    • A run no longer shares one trace ID: the trace of the request that called start() no longer contains the workflow's execution spans — navigate via span links or the workflow.run.id attribute instead.
    • Sampling decisions are made independently per invocation root (previously one parent-based decision covered the whole run), and the number of root spans/traces increases to one per invocation.
    • workflow.execute/step.execute invocation spans (formerly WORKFLOW_V2/STEP) become parentless roots, which changes parent/child-based queries and service-map edges.
    • Re-enqueued queue messages forward the original run-origin trace carrier unchanged, rather than each invocation's current context.
    • Queries or dashboards matching the old WORKFLOW_V2 .../STEP ... span names must switch to the new names.
    • The queue-delivered workflow.execute span kind changed from internal to consumer, matching the queue-delivered step.execute span (this applies in both modes).

    Existing attributes and baggage keys are unchanged, and everything remains a no-op when no OpenTelemetry SDK is registered.

  • #2516 84ccd40 Thanks @VaguelySerious! - Inline execution now runs up to WORKFLOW_MAX_INLINE_STEPS (default 3) steps in parallel per suspension, each lazily created. An opt-in WORKFLOW_OPTIMISTIC_INLINE_START (default off) additionally starts step bodies before step_started is confirmed, reconciling the in-flight start before the terminal write so a lost create-claim is discarded; it is off by default because under contention a step body can run more than once (e.g. two runs writing to the workflow stream can corrupt it), so only enable it for idempotent steps.

  • #2946 eb8fdb9 Thanks @VaguelySerious! - The WORKFLOW_PRECONDITION_GUARD event-creation guard is now on by default; opt out with WORKFLOW_PRECONDITION_GUARD=0.

  • #3048 f8f6e17 Thanks @TooTallNate! - Add an experimental QuickJS WASM VM engine for workflow execution, opt-in via WORKFLOW_VM=quickjs (or per-run executionContext.workflowVm). The engine performs the same full event replay as the default node:vm engine but runs workflow code in a QuickJS VM compiled to WebAssembly, enabling platforms without node:vm support and laying the groundwork for VM-memory snapshotting.

  • #2882 0b956f6 Thanks @VaguelySerious! - Rename experimental_setAttributes to setAttributes — the attributes feature is no longer experimental. The old name remains available as a deprecated alias.

  • #1834 438eaa6 Thanks @TooTallNate! - Make resumeHook() resilient to transient hook_received event write failures (429/5xx) by carrying the payload on the queue message for the runtime to materialize. Returned Hook gets a new resilientResume: true flag when this fallback path is taken.

  • #3046 5d591d2 Thanks @NathanColosimo! - Retain workflow execution across inline steps within one invocation; WORKFLOW_RETAINED_VM=0 disables retention. Boundaries whose step arguments are not primitive values fall back to ordinary replay.

  • #3047 89ede82 Thanks @NathanColosimo! - Retained workflow VMs now keep the fast path when step arguments are plain data or standard built-ins (Map, Set, Date, typed arrays, URL, Headers, …), not just primitives. A boundary falls back to a normal replay only when serializing its arguments ran code the workflow controls — a getter, a proxy, a custom serializer — or computed an Error's stack trace.

  • #3972 c340820 Thanks @alangenfeld! - Add Run#getWritable() and run.writable to append to an existing run's stream.

  • #2385 628795a Thanks @pranaygp! - Add an allowReservedAttributes option to start() so framework-level callers can seed reserved $-prefixed run attributes at creation, matching the existing experimental_setAttributes option. The flag is carried through the resilient-start queue input so lazy run creation validates identically.

  • #1491 e295bae Thanks @pranaygp! - Allow start() to be called directly inside workflow functions

  • #3850 fe2fd8c Thanks @alangenfeld! - Add a catchable StreamError and classify Workflow stream infrastructure failures as STREAM_ERROR instead of USER_ERROR.

  • #2059 49da6c5 Thanks @TooTallNate! - A WritableStream from a workflow's getWritable() can now be passed as an argument to a child workflow via start(); the child's writes land on the parent run's stream directly for the full lifetime of the child run.

  • #2526 3e82a12 Thanks @VaguelySerious! - Add turbo mode (on by default, disable with WORKFLOW_TURBO=0): on the first delivery of a run's first invocation the runtime backgrounds run_started, skips the initial event-log load, and forces optimistic inline start so the run reaches its first steps with no preceding network round-trips. It is safe there because the first delivery has no concurrent handler to race; turbo mode deactivates once a hook or sleep is encountered.

  • #3678 20ad2b3 Thanks @TooTallNate! - Add registerLifecycleHooks from workflow/api for best-effort completion and failure reporting with a read-free workflow name, lazy Run instance, and failure cause hydrated from the persisted payload. Run metadata getters avoid resolving input/output payloads.

Patch Changes