workflow 5.0.0-beta.1 → 5.0.0-beta.2

package/docs/migration-guides/migrating-from-temporal.mdx

@@ -0,0 +1,284 @@
+---
+title: Migrating from Temporal
+description: Move a Temporal TypeScript workflow to the Workflow SDK by replacing Activities, Workers, Signals, and Child Workflows with Workflows, Steps, Hooks, and start()/getRun().
+type: guide
+summary: Translate a Temporal app into the Workflow SDK with side-by-side code examples.
+prerequisites:
+  - /docs/getting-started/next
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/starting-workflows
+  - /docs/foundations/errors-and-retries
+  - /docs/foundations/hooks
+  - /docs/foundations/streaming
+  - /docs/deploying/world/vercel-world
+---
+
+<Callout type="info">
+Install the Workflow SDK migration skill:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+## Why migrate to the Workflow SDK
+
+- Streaming is built in. Durable progress writes go to named streams via `getWritable({ namespace })`, and clients read them directly. No separate WebSocket, SSE, or progress-polling layer to operate.
+- Infrastructure and orchestration live in a single deployment. There is no separate Worker fleet or Temporal Server to run. The runtime, step logic, and orchestration share the app's observability and log aggregation.
+- TypeScript-first developer experience. Workflows and steps live in the same file with plain `await` control flow, `try/catch`, and `Promise.all`.
+- Agent-first tooling. A first-class CLI (`npx workflow`), `@workflow/ai` integration for durable AI agents, and a bundled Claude skill for AI-assisted authoring.
+- Per-step retry controls. `RetryableError`, `FatalError`, and `maxRetries` live at the step boundary instead of an Activity-level retry policy configured elsewhere.
+
+## What changes when you leave Temporal
+
+Temporal requires operating a control plane (Temporal Server or Cloud), a Worker fleet, Activity modules wired through `proxyActivities`, and Task Queues. The workflow code is durable; the surrounding infrastructure is substantial.
+
+The Workflow SDK runs on managed infrastructure. Write `"use workflow"` functions that orchestrate `"use step"` functions in the same file, in plain TypeScript. There are no Workers, Task Queues, or separate Activity modules. Durable replay, automatic retries, and event history are handled by the runtime.
+
+Migration removes infrastructure and collapses indirection. Business logic stays as regular async TypeScript.
+
+## Concept mapping
+
+| Temporal | Workflow SDK | Migration note |
+| --- | --- | --- |
+| Workflow Definition / Workflow Execution | `"use workflow"` function / run started with `start()` | Keep orchestration code in the workflow function. |
+| Activity | `"use step"` function | Put side effects and Node.js access in steps. |
+| Worker + Task Queue | Managed execution | No worker fleet or polling loop to operate. |
+| Signal | `createHook()` or `createWebhook()` | Use hooks for typed resume signals; webhooks for HTTP callbacks. |
+| Query | `getWritable({ namespace: 'status' })` stream | Durably stream status updates from the workflow. Clients read from the stream instead of polling a database. |
+| Update | `createHook()` + `resumeHook()` | Writes go through hooks. |
+| Child Workflow | `"use step"` wrappers around `start()` / `getRun()` | Spawn from a step and return the `Run` object so observability can deep-link into child runs. |
+| Activity retry policy | Step retries, `RetryableError`, `FatalError`, `maxRetries` | Retries live at the step boundary. |
+| Event History | Workflow event log / run timeline | Same durable replay, fewer surfaces to manage. |
+
+## Translate your first workflow
+
+### Minimal translation
+
+Start with the directive change. The Temporal definition proxies activities through a module; the Workflow SDK version puts the directive inline.
+
+{/* @skip-typecheck: Temporal SDK types not available */}
+```typescript title="workflows/order.ts (Temporal)"
+const { chargePayment } = wf.proxyActivities<typeof activities>({
+  startToCloseTimeout: '5 minutes',
+});
+
+export async function processOrder(orderId: string) {
+  await chargePayment(orderId);
+  return { orderId, status: 'completed' };
+}
+```
+
+```typescript title="workflows/order.ts (Workflow SDK)"
+export async function processOrder(orderId: string) {
+  'use workflow'; // [!code highlight]
+  await chargePayment(orderId);
+  return { orderId, status: 'completed' };
+}
+```
+
+**What changed:** `proxyActivities` and the activity module disappear. The orchestrator is plain async TypeScript marked with `"use workflow"`.
+
+### Adding a step
+
+Side effects move into a colocated `"use step"` function:
+
+```typescript title="workflow/workflows/order.ts"
+async function chargePayment(orderId: string) {
+  'use step'; // [!code highlight]
+  await fetch(`https://example.com/api/orders/${orderId}/charge`, {
+    method: 'POST',
+  });
+}
+```
+
+Additional steps (`loadOrder`, `reserveInventory`) follow the same shape and can be called from the workflow in sequence.
+
+### Starting the run
+
+Replace Worker + Task Queue wiring with a single `start()` call from an API route:
+
+```typescript title="app/api/orders/route.ts"
+import { start } from 'workflow/api';
+import { processOrder } from '@/workflows/order';
+
+export async function POST(request: Request) {
+  const { orderId } = (await request.json()) as { orderId: string };
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  return Response.json({ runId: run.runId });
+}
+```
+
+## Wait for an external signal
+
+### Minimal translation
+
+Temporal needs a signal definition, a handler, and a `condition()` guard. The Workflow SDK collapses all three into a single `createHook()` + `await`.
+
+{/* @skip-typecheck: Temporal SDK types not available */}
+```typescript title="temporal/workflows/refund.ts"
+export const approveRefund = wf.defineSignal<[boolean]>('approveRefund');
+
+export async function refundWorkflow(refundId: string) {
+  let approved: boolean | undefined;
+  wf.setHandler(approveRefund, (v) => { approved = v; });
+  await wf.condition(() => approved !== undefined);
+  return { refundId, approved };
+}
+```
+
+```typescript title="workflow/workflows/refund.ts"
+import { createHook } from 'workflow';
+
+export async function refundWorkflow(refundId: string) {
+  'use workflow';
+  using approval = createHook<{ approved: boolean }>({
+    token: `refund:${refundId}:approval`, // [!code highlight]
+  });
+  const { approved } = await approval; // [!code highlight]
+  return { refundId, approved };
+}
+```
+
+The workflow suspends durably at `await approval` until resumed. No polling, no handler registration.
+
+### Resuming from an API route
+
+Any HTTP caller can resume by token:
+
+```typescript title="app/api/refunds/[refundId]/approve/route.ts"
+import { resumeHook } from 'workflow/api';
+
+export async function POST(request: Request, { params }: { params: Promise<{ refundId: string }> }) {
+  const { refundId } = await params;
+  const body = (await request.json()) as { approved: boolean };
+  await resumeHook(`refund:${refundId}:approval`, body); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+<Callout type="info">
+Temporal Queries expose in-memory workflow state on demand. In the Workflow SDK, the equivalent is a durable stream: call `getWritable({ namespace: 'status' })` from inside the workflow to write status updates, and have clients read from the end of that stream to get the current state. Hooks are the write channel for resuming a paused workflow with new data.
+</Callout>
+
+## Spawn a child workflow
+
+### Minimal translation
+
+`start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the `Run` object (not a plain `runId` string) so workflow observability can deep-link into child runs.
+
+```typescript title="workflow/workflows/parent.ts"
+import { start } from 'workflow/api';
+
+async function spawnChild(item: string) {
+  'use step'; // [!code highlight]
+  return start(childWorkflow, [item]); // [!code highlight]
+}
+
+export async function parentWorkflow(item: string) {
+  'use workflow';
+  const child = await spawnChild(item); // [!code highlight]
+  return { childRunId: child.runId };
+}
+```
+
+### Awaiting the child's return value
+
+A second step fetches the run and awaits `returnValue`:
+
+```typescript title="workflow/workflows/parent.ts"
+import { getRun } from 'workflow/api';
+
+async function collectResult(runId: string) {
+  'use step';
+  const run = getRun(runId);
+  return (await run.returnValue) as { item: string; result: string }; // [!code highlight]
+}
+```
+
+Call both steps from the parent in sequence: `const result = await collectResult(child.runId)`. To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls.
+
+<Callout type="warn">
+Activity retry policy moves to the step boundary. Use `maxRetries`, `RetryableError`, and `FatalError` on each step instead of a single workflow-wide retry block.
+</Callout>
+
+## What you stop operating
+
+- **Temporal Server or Cloud.** Durable state lives in the managed event log.
+- **Worker fleet.** The runtime schedules execution; workflows run where the app runs.
+- **Task Queues.** No queue routing to configure or monitor.
+- **Activity modules and `proxyActivities`.** Steps live next to the workflow that calls them.
+- **Custom progress transport.** `getWritable()` streams updates from steps.
+
+Suspended workflows (on `sleep()` or a hook) consume no compute until resumed.
+
+## Step-by-step first migration
+
+Pick one Temporal workflow and migrate it end-to-end before touching the rest. The steps below describe the smallest viable path.
+
+### Step 1: Install the Workflow SDK
+
+Add the runtime. The Next.js integration ships as a subpath (`workflow/next`) of the same package.
+
+```bash
+pnpm add workflow
+```
+
+### Step 2: Collapse Activities into step functions
+
+Delete the `activities/` module and the `proxyActivities` call. Each former Activity becomes a plain async function with `"use step"` on the first line, living next to the orchestrator.
+
+```ts title="workflows/order.ts"
+async function loadOrder(id: string) {
+  "use step"; // [!code highlight]
+  return fetch(`/api/orders/${id}`).then((r) => r.json());
+}
+```
+
+### Step 3: Mark the orchestrator with `"use workflow"`
+
+Keep the existing control flow: `await`, `try/catch`, `Promise.all`. The directive turns the function into a durable replay target.
+
+```ts
+export async function processOrder(orderId: string) {
+  "use workflow"; // [!code highlight]
+  const order = await loadOrder(orderId);
+  // ...
+}
+```
+
+### Step 4: Replace Signals with hooks
+
+Swap `defineSignal` + `setHandler` for `createHook()`. Callers `resumeHook(token, payload)` instead of `client.workflow.signal(...)`.
+
+### Step 5: Start runs from an API route or server action
+
+Delete the Worker bootstrap. Launch runs from an API route or server action with `start()`:
+
+```ts title="app/api/orders/route.ts"
+import { start } from "workflow/api";
+import { processOrder } from "@/workflows/order";
+
+export async function POST(req: Request) {
+  const { orderId } = await req.json();
+  const run = await start(processOrder, [orderId]);
+  return Response.json({ runId: run.runId });
+}
+```
+
+### Step 6: Retire the Temporal infrastructure
+
+Remove the Worker process, `@temporalio/*` dependencies, and the Temporal Server or Cloud connection. Verify the run in the built-in observability UI (`npx workflow web`) before shipping.
+
+## Quick-start checklist
+
+- Move orchestration into a `"use workflow"` function.
+- Convert each Activity into a `"use step"` function.
+- Remove Worker and Task Queue code. Start workflows from the app with `start()`.
+- Replace Signals with `createHook()` or `createWebhook()` for HTTP callers.
+- Wrap `start()` and `getRun()` in `"use step"` functions for child workflows. Return the `Run` object from `start()` so observability can deep-link into child runs.
+- Set retry policy per step with `maxRetries`, `RetryableError`, and `FatalError`.
+- Use `getStepMetadata().stepId` as the idempotency key for external side effects.
+- Stream status and progress from steps with `getWritable({ namespace: 'status' })`, and have clients read from the stream instead of polling.
+- Deploy the app and verify runs end-to-end in the built-in observability UI.

package/docs/migration-guides/migrating-from-trigger-dev.mdx

@@ -0,0 +1,296 @@
+---
+title: Migrating from trigger.dev
+description: Move a trigger.dev v3 TypeScript app to the Workflow SDK by replacing task(), schemaTask(), wait.for / wait.forToken, triggerAndWait, and metadata streams with Workflows, Steps, Hooks, and start() / getRun().
+type: guide
+summary: Translate a trigger.dev v3 app into the Workflow SDK with side-by-side code examples.
+prerequisites:
+  - /docs/getting-started/next
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/starting-workflows
+  - /docs/foundations/errors-and-retries
+  - /docs/foundations/hooks
+  - /docs/foundations/streaming
+  - /docs/deploying/world/vercel-world
+---
+
+<Callout type="info">
+Install the Workflow SDK migration skill:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+## Why migrate to the Workflow SDK?
+
+- Streaming is built in via named streams (`getWritable()` and `getWritable({ namespace })`). Durable status writes replace `metadata.stream()` and `metadata.set()`, and clients read from the end of the stream for current status.
+- Orchestration and infrastructure live in a single deployment. There is no separate trigger.dev cloud or self-hosted worker fleet to operate.
+- TypeScript-first DX: plain async/await control flow, no `task()` factory, no `schemaTask()` wrapper for payloads you already type with TypeScript.
+- Agent-first tooling: the `npx workflow` CLI, `@workflow/ai` for durable AI agents, and a Claude skill for generating workflows.
+- Retry policy is per step. Throw `RetryableError` to retry with a delay, or `FatalError` to stop. There is no central task-level retry config.
+
+## What changes when you leave trigger.dev?
+
+trigger.dev v3 defines durable work with `task()` or `schemaTask()` from `@trigger.dev/sdk/v3`, deploys tasks to the trigger.dev cloud or a self-hosted instance, and triggers runs via `tasks.trigger()`. A separate worker fleet picks up runs, applies retry policies, and routes `wait.for`, `wait.forToken`, and `metadata.stream` calls through the platform.
+
+The Workflow SDK replaces that with `"use workflow"` functions that orchestrate `"use step"` functions in plain TypeScript. There is no task registry, separate deploy target, or SDK client. Durable replay, retries, and event history ship with the runtime.
+
+Migration collapses the task abstraction into plain async functions. Business logic stays the same.
+
+## Concept mapping
+
+| trigger.dev | Workflow SDK | Migration note |
+| --- | --- | --- |
+| `task({ id, run })` | `"use workflow"` function started with `start()` | No factory or id registry. |
+| `schemaTask({ schema, run })` | Typed function + `"use workflow"` | Validate inputs at the call site. |
+| Inline `run` body | `"use step"` function | Side effects move into named steps. |
+| `logger` / `metadata.set` | `console` + `getWritable({ namespace: 'status' })` | Logs flow through the run timeline. Status writes go on a named stream. |
+| `wait.for({ seconds })` / `wait.until({ date })` | `sleep()` | Import from `workflow`. |
+| `wait.forToken({ timeout })` | `createHook()` + `Promise.race` with `sleep()` | Hooks carry a typed token. |
+| `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Wrap both in `"use step"` functions. |
+| `batch.triggerAndWait()` | `Promise.all(runIds.map(collectResult))` | Fan out via standard concurrency. |
+| `AbortTaskRunError` | `FatalError` | Stops retries immediately. |
+| `retry.onThrow` / `retry.fetch` | `RetryableError`, `FatalError`, `maxRetries` | Retry lives on the step. Exponential backoff is a step `maxRetries` config, not a helper. |
+| `metadata.stream()` / Realtime | `getWritable()` / `getWritable({ namespace })` | Named streams are the canonical read channel. Clients read from the end of the stream for current status. Do not poll `getRun()` or persist status to a database for client reads. |
+| Self-hosted worker + dashboard | Managed execution + built-in UI | No worker fleet to operate. |
+
+## Translate your first workflow
+
+Start with the shell. trigger.dev wraps the handler in `task()`; the Workflow SDK marks the function with a directive.
+
+```typescript title="trigger/order.ts (trigger.dev)"
+import { task } from '@trigger.dev/sdk/v3';
+
+export const processOrder = task({
+  id: 'process-order',
+  run: async (payload: { orderId: string }) => {
+    return { orderId: payload.orderId, status: 'completed' };
+  },
+});
+```
+
+```typescript title="trigger/order.ts (Workflow SDK)"
+export async function processOrder(orderId: string) {
+  'use workflow'; // [!code highlight]
+  return { orderId, status: 'completed' };
+}
+```
+
+**What changed:** the `task()` factory and its `id` field disappear. The function is a plain export tagged with `"use workflow"`.
+
+### Add a step
+
+The body of `run` becomes one or more `"use step"` functions.
+
+```typescript title="workflow/workflows/order.ts"
+async function loadOrder(orderId: string) {
+  'use step'; // [!code highlight]
+  const res = await fetch(`https://example.com/api/orders/${orderId}`);
+  return res.json() as Promise<{ id: string }>;
+}
+```
+
+Call it from the workflow with a plain `await`. Each additional side effect (`reserveInventory`, `chargePayment`) follows the same shape.
+
+### Start the run
+
+trigger.dev dispatches with `tasks.trigger<typeof processOrder>('process-order', { orderId })`. The Workflow SDK calls `start()` directly:
+
+```typescript title="app/api/orders/route.ts"
+import { start } from 'workflow/api';
+import { processOrder } from '@/workflows/order';
+
+export async function POST(request: Request) {
+  const { orderId } = (await request.json()) as { orderId: string };
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  return Response.json({ runId: run.runId });
+}
+```
+
+No id lookup, no API key, no separate worker. `start()` returns a handle immediately.
+
+## Wait for an external signal
+
+`wait.forToken()` becomes `createHook()` plus `await`.
+
+{/* @skip-typecheck: trigger.dev SDK types not available */}
+```typescript title="workflow/workflows/refund.ts (trigger.dev, abbreviated)"
+// import { wait } from '@trigger.dev/sdk/v3';
+const token = await wait.createToken({ timeout: '7d' });
+const approval = await wait.forToken<{ approved: boolean }>(token.id).unwrap();
+// External system resumes with: await wait.completeToken(token.id, { approved: true });
+```
+
+{/* @skip-typecheck: snippet without imports */}
+```typescript title="workflow/workflows/refund.ts (Workflow SDK)"
+using approval = createHook<{ approved: boolean }>({ // [!code highlight]
+  token: `refund:${refundId}:approval`,
+});
+const payload = await approval;
+```
+
+**What changed:** the platform-issued opaque token becomes an app-owned string. The caller that resumes the run supplies that same string, so there is no token lookup.
+
+### Resume from an API route
+
+trigger.dev completes a token with `wait.completeToken(tokenId, { approved })`. The SDK equivalent is `resumeHook`:
+
+```typescript title="app/api/refunds/[refundId]/approve/route.ts"
+import { resumeHook } from 'workflow/api';
+
+export async function POST(request: Request, { params }: { params: Promise<{ refundId: string }> }) {
+  const { refundId } = await params;
+  const { approved } = (await request.json()) as { approved: boolean };
+  await resumeHook(`refund:${refundId}:approval`, { approved }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+### Add a timeout and branch on the payload
+
+trigger.dev's `timeout: '7d'` option maps to a `Promise.race()` with `sleep()`:
+
+{/* @skip-typecheck: continuation snippet */}
+```typescript title="workflow/workflows/refund.ts"
+const result = await Promise.race([
+  approval.then((p) => ({ type: 'decision' as const, approved: p.approved })),
+  sleep('7d').then(() => ({ type: 'timeout' as const })), // [!code highlight]
+]);
+
+if (result.type === 'timeout') return { refundId, status: 'timed-out' };
+if (!result.approved) return { refundId, status: 'rejected' };
+return { refundId, status: 'approved' };
+```
+
+<Callout type="info">
+A hook is an inbound write channel. The caller that knows the token resumes the run with a typed payload. To expose in-flight state to a dashboard, write updates from a step with `getWritable()` (or `getWritable({ namespace: 'status' })`), and have the client read from the end of that named stream.
+</Callout>
+
+## Spawn a child workflow
+
+`triggerAndWait()` splits into two steps: spawn and collect. `start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the full `Run` object from `spawnChild` so observability tooling can deep-link to the child run.
+
+```typescript title="workflow/workflows/parent.ts"
+import { start } from 'workflow/api';
+
+async function spawnChild(item: string) {
+  'use step';
+  return start(childWorkflow, [item]); // [!code highlight]
+}
+```
+
+Await the result in a second step, then orchestrate both from the parent:
+
+```typescript title="workflow/workflows/parent.ts"
+import { getRun } from 'workflow/api';
+
+async function collectResult(runId: string) {
+  'use step';
+  const run = getRun(runId);
+  return (await run.returnValue) as { item: string; result: string }; // [!code highlight]
+}
+
+export async function parentWorkflow(item: string) {
+  'use workflow';
+  const child = await spawnChild(item);
+  return await collectResult(child.runId);
+}
+```
+
+To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
+
+## What you stop operating
+
+Dropping the trigger.dev SDK removes several moving parts:
+
+- **No task registry or `id` strings.** Workflow files carry directive annotations and export plain functions.
+- **No `@trigger.dev/sdk/v3` client or API key.** `start()` launches runs directly from API routes or server actions.
+- **No worker fleet or self-hosted instance.** The runtime schedules execution inside the app's deploy target.
+- **No separate Realtime channel.** `getWritable()` streams updates from steps over the run's durable stream.
+- **No dashboard account.** The built-in observability UI (`npx workflow web`) reads the same event log the runtime writes.
+
+Workflows suspended on `sleep()` or a hook consume no compute until resumed.
+
+## Step-by-step first migration
+
+Pick one trigger.dev task and migrate it end-to-end before touching the rest. The steps below describe the smallest viable path.
+
+### Step 1: Install the Workflow SDK
+
+Add the runtime. The Next.js integration ships as the `workflow/next` subpath of the same package.
+
+```bash
+pnpm add workflow
+```
+
+### Step 2: Convert `task()` to a `"use workflow"` export
+
+Drop the factory call and the `id`. Move the handler body up and replace the payload object with typed function arguments.
+
+```ts title="workflows/order.ts"
+// Before (trigger.dev)
+// export const processOrder = task({
+//   id: "process-order",
+//   run: async ({ orderId }: { orderId: string }) => { ... },
+// });
+
+// After (Workflow SDK)
+export async function processOrder(orderId: string) {
+  "use workflow"; // [!code highlight]
+  // ...
+}
+```
+
+### Step 3: Convert the task body into `"use step"` named functions
+
+Each side effect becomes a named function with `"use step"` on the first line. The workflow calls them with a plain `await`. `schemaTask()` validation moves to the call site: validate with zod before calling `start()`.
+
+```ts
+async function loadOrder(id: string) {
+  "use step"; // [!code highlight]
+  return fetch(`/api/orders/${id}`).then((r) => r.json());
+}
+```
+
+### Step 4: Replace `wait.*` with hooks and `sleep`
+
+- `wait.for({ seconds })` / `wait.until({ date })` → `sleep('5m')` or `sleep(date)` from `workflow`.
+- `wait.forToken(token)` → `createHook({ token })` + `await`. Complete it with `resumeHook(token, payload)` from an API route.
+- `wait.forToken({ timeout })` → `Promise.race([hook, sleep(timeout)])`.
+- `triggerAndWait(payload)` → wrap `start(child, [payload])` in a `"use step"` function and return the `Run` object, then read the result with a second step that calls `getRun(runId).returnValue`.
+
+### Step 5: Start runs from the app
+
+Delete the trigger.dev client setup. Launch runs directly from an API route or server action:
+
+```ts title="app/api/orders/route.ts"
+import { start } from "workflow/api";
+import { processOrder } from "@/workflows/order";
+
+export async function POST(req: Request) {
+  const { orderId } = await req.json();
+  const run = await start(processOrder, [orderId]);
+  return Response.json({ runId: run.runId });
+}
+```
+
+### Step 6: Retire trigger.dev infrastructure
+
+Remove the `@trigger.dev/sdk` dependency, the `trigger.config.ts` file, the `trigger/` directory, and any self-hosted worker deployment. Delete dashboard API keys from the environment. Verify the run in `npx workflow web` before shipping.
+
+## Quick-start checklist
+
+- Replace `task({ id, run })` with a `"use workflow"` function; launch it with `start()`.
+- Convert each task body into named `"use step"` functions.
+- Swap `wait.for` / `wait.until` for `sleep()` from `workflow`.
+- Swap `wait.forToken` for `createHook()` (internal) or `createWebhook()` (HTTP).
+- Model `wait.forToken` timeouts as `Promise.race()` between the hook and `sleep()`.
+- Replace `triggerAndWait()` with `"use step"` wrappers around `start()` and `getRun()`.
+- Replace `batch.triggerAndWait()` with `Promise.all` over the collected child `Run` handles.
+- Move `schemaTask` validation to the call site; pass typed arguments into the workflow.
+- Replace `AbortTaskRunError` with `FatalError`; model retries per step with `RetryableError` and `maxRetries`.
+- Use `getStepMetadata().stepId` as the idempotency key for external side effects.
+- Replace `metadata.stream()` and Realtime with `getWritable()`.
+- Remove the `@trigger.dev/sdk` dependency, `trigger.config.ts`, and any self-hosted worker.
+- Deploy and verify runs end-to-end with the built-in observability UI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.2",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -56,18 +56,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.1",
-    "@workflow/cli": "5.0.0-beta.1",
-    "@workflow/core": "5.0.0-beta.1",
-    "@workflow/errors": "5.0.0-beta.0",
-    "@workflow/typescript-plugin": "5.0.0-beta.1",
-    "@workflow/utils": "5.0.0-beta.0",
-    "@workflow/next": "5.0.0-beta.1",
-    "@workflow/nest": "5.0.0-beta.1",
-    "@workflow/nitro": "5.0.0-beta.1",
-    "@workflow/nuxt": "5.0.0-beta.1",
-    "@workflow/sveltekit": "5.0.0-beta.1",
-    "@workflow/rollup": "5.0.0-beta.1"
+    "@workflow/astro": "5.0.0-beta.2",
+    "@workflow/core": "5.0.0-beta.2",
+    "@workflow/errors": "5.0.0-beta.1",
+    "@workflow/cli": "5.0.0-beta.2",
+    "@workflow/typescript-plugin": "5.0.0-beta.2",
+    "@workflow/next": "5.0.0-beta.2",
+    "@workflow/utils": "5.0.0-beta.1",
+    "@workflow/nuxt": "5.0.0-beta.2",
+    "@workflow/nest": "5.0.0-beta.2",
+    "@workflow/nitro": "5.0.0-beta.2",
+    "@workflow/sveltekit": "5.0.0-beta.2",
+    "@workflow/rollup": "5.0.0-beta.2"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",