workflow 4.1.0-beta.62 → 4.2.0-beta.64

package/dist/api-workflow.d.ts

@@ -1,4 +1,4 @@
-export type { Event, StartOptions, WorkflowReadableStreamOptions, WorkflowRun, } from '@workflow/core/runtime';
+export type { Event, StartOptions, StopSleepOptions, StopSleepResult, WorkflowReadableStreamOptions, WorkflowRun, } from '@workflow/core/runtime';
 export declare class Run {
     constructor();
 }

package/dist/api-workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-workflow.d.ts","sourceRoot":"","sources":["../src/api-workflow.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,KAAK,EACL,YAAY,EACZ,6BAA6B,EAC7B,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAQhC,qBAAa,GAAG;;CAIf;AACD,eAAO,MAAM,MAAM,aAA+B,CAAC;AACnD,eAAO,MAAM,cAAc,aAAuC,CAAC;AACnE,eAAO,MAAM,UAAU,aAAmC,CAAC;AAC3D,eAAO,MAAM,aAAa,aAAsC,CAAC;AACjE,eAAO,MAAM,OAAO,aAAgC,CAAC;AACrD,eAAO,MAAM,KAAK,aAA8B,CAAC"}
+{"version":3,"file":"api-workflow.d.ts","sourceRoot":"","sources":["../src/api-workflow.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,6BAA6B,EAC7B,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAQhC,qBAAa,GAAG;;CAIf;AACD,eAAO,MAAM,MAAM,aAA+B,CAAC;AACnD,eAAO,MAAM,cAAc,aAAuC,CAAC;AACnE,eAAO,MAAM,UAAU,aAAmC,CAAC;AAC3D,eAAO,MAAM,aAAa,aAAsC,CAAC;AACjE,eAAO,MAAM,OAAO,aAAgC,CAAC;AACrD,eAAO,MAAM,KAAK,aAA8B,CAAC"}

package/dist/api-workflow.js

@@ -12,4 +12,4 @@ export const resumeHook = () => workflowStub('resumeHook');
 export const resumeWebhook = () => workflowStub('resumeWebhook');
 export const runStep = () => workflowStub('runStep');
 export const start = () => workflowStub('start');
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLXdvcmtmbG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS13b3JrZmxvdy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFPQSxNQUFNLFlBQVksR0FBRyxDQUFDLElBQVksRUFBRSxFQUFFO0lBQ3BDLE1BQU0sSUFBSSxLQUFLLENBQ2IsZ0VBQWdFLElBQUksMkZBQTJGLENBQ2hLLENBQUM7QUFDSixDQUFDLENBQUM7QUFFRixNQUFNLE9BQU8sR0FBRztJQUNkO1FBQ0UsWUFBWSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQ3RCLENBQUM7Q0FDRjtBQUNELE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsUUFBUSxDQUFDLENBQUM7QUFDbkQsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDO0FBQ25FLE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsWUFBWSxDQUFDLENBQUM7QUFDM0QsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxlQUFlLENBQUMsQ0FBQztBQUNqRSxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQUcsR0FBRyxFQUFFLENBQUMsWUFBWSxDQUFDLFNBQVMsQ0FBQyxDQUFDO0FBQ3JELE1BQU0sQ0FBQyxNQUFNLEtBQUssR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsT0FBTyxDQUFDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLXdvcmtmbG93LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS13b3JrZmxvdy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFTQSxNQUFNLFlBQVksR0FBRyxDQUFDLElBQVksRUFBRSxFQUFFO0lBQ3BDLE1BQU0sSUFBSSxLQUFLLENBQ2IsZ0VBQWdFLElBQUksMkZBQTJGLENBQ2hLLENBQUM7QUFDSixDQUFDLENBQUM7QUFFRixNQUFNLE9BQU8sR0FBRztJQUNkO1FBQ0UsWUFBWSxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQ3RCLENBQUM7Q0FDRjtBQUNELE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsUUFBUSxDQUFDLENBQUM7QUFDbkQsTUFBTSxDQUFDLE1BQU0sY0FBYyxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDO0FBQ25FLE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsWUFBWSxDQUFDLENBQUM7QUFDM0QsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLEdBQUcsRUFBRSxDQUFDLFlBQVksQ0FBQyxlQUFlLENBQUMsQ0FBQztBQUNqRSxNQUFNLENBQUMsTUFBTSxPQUFPLEdBQUcsR0FBRyxFQUFFLENBQUMsWUFBWSxDQUFDLFNBQVMsQ0FBQyxDQUFDO0FBQ3JELE1BQU0sQ0FBQyxNQUFNLEtBQUssR0FBRyxHQUFHLEVBQUUsQ0FBQyxZQUFZLENBQUMsT0FBTyxDQUFDLENBQUMifQ==

package/dist/api.d.ts

@@ -1,2 +1,2 @@
-export { type Event, getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, type StartOptions, start, type WorkflowReadableStreamOptions, type WorkflowRun, } from '@workflow/core/runtime';
+export { type Event, getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, type StartOptions, start, type StopSleepOptions, type StopSleepResult, type WorkflowReadableStreamOptions, type WorkflowRun, } from '@workflow/core/runtime';
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EACV,cAAc,EACd,MAAM,EACN,GAAG,EACH,UAAU,EACV,aAAa,EACb,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,EACL,KAAK,6BAA6B,EAClC,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EACV,cAAc,EACd,MAAM,EACN,GAAG,EACH,UAAU,EACV,aAAa,EACb,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,6BAA6B,EAClC,KAAK,WAAW,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/api.js

@@ -1,2 +1,2 @@
 export { getHookByToken, getRun, Run, resumeHook, resumeWebhook, runStep, start, } from '@workflow/core/runtime';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBRUwsY0FBYyxFQUNkLE1BQU0sRUFDTixHQUFHLEVBQ0gsVUFBVSxFQUNWLGFBQWEsRUFDYixPQUFPLEVBRVAsS0FBSyxHQUdOLE1BQU0sd0JBQXdCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBRUwsY0FBYyxFQUNkLE1BQU0sRUFDTixHQUFHLEVBQ0gsVUFBVSxFQUNWLGFBQWEsRUFDYixPQUFPLEVBRVAsS0FBSyxHQUtOLE1BQU0sd0JBQXdCLENBQUMifQ==

package/docs/api-reference/workflow/create-hook.mdx

@@ -100,7 +100,7 @@ export async function slackBotWorkflow(channelId: string) {
 
   // Token constructed from channel ID
   using hook = createHook<SlackMessage>({ // [!code highlight]
-    token: `slack_webhook:${channelId}`, // [!code highlight]
+    token: `slack_messages:${channelId}`, // [!code highlight]
   }); // [!code highlight]
 
   for await (const message of hook) {

package/docs/api-reference/workflow/create-webhook.mdx

@@ -120,46 +120,6 @@ async function processData(data: any) {
 }
 ```
 
-### Customizing Tokens
-
-Tokens are used to identify a specific webhook. You can customize the token to be more specific to a use case.
-
-```typescript lineNumbers
-import { createWebhook, type RequestWithResponse } from "workflow"
-
-async function sendAck(request: RequestWithResponse) {
-  "use step";
-  await request.respondWith(
-    new Response(JSON.stringify({ received: true }), {
-      headers: { "Content-Type": "application/json" }
-    })
-  );
-}
-
-export async function githubWebhookWorkflow(repoName: string) {
-  "use workflow";
-
-  // Use a deterministic token based on the repository
-  using webhook = createWebhook({ // [!code highlight]
-    token: `github_webhook:${repoName}`, // [!code highlight]
-  }); // [!code highlight]
-
-  console.log("Configure GitHub webhook:", webhook.url);
-
-  const request = await webhook;
-  const event = await request.json();
-
-  await sendAck(request);
-
-  await deployCommit(event);
-}
-
-async function deployCommit(event: any) {
-  "use step";
-  // Deploy logic here
-}
-```
-
 ### Waiting for Multiple Requests
 
 You can also wait for multiple requests by using the `for await...of` syntax.
@@ -167,62 +127,35 @@ You can also wait for multiple requests by using the `for await...of` syntax.
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow"
 
-async function sendSlackResponse(request: RequestWithResponse, message: string) {
+async function sendAck(request: RequestWithResponse, message: string) {
   "use step";
   await request.respondWith(
-    new Response(
-      JSON.stringify({
-        response_type: "in_channel",
-        text: message
-      }),
-      { headers: { "Content-Type": "application/json" } }
-    )
+    Response.json({ received: true, message })
   );
 }
 
-async function sendStopResponse(request: RequestWithResponse) {
+async function processEvent(data: any) {
   "use step";
-  await request.respondWith(
-    new Response("Stopping workflow...")
-  );
+  console.log("Processing event:", data);
 }
 
-export async function slackCommandWorkflow(channelId: string) {
+export async function eventCollectorWorkflow() {
   "use workflow";
 
-  using webhook = createWebhook({
-    token: `slack_command:${channelId}`,
-  });
+  using webhook = createWebhook({ respondWith: "manual" });
+  console.log("Send events to:", webhook.url);
 
   for await (const request of webhook) { // [!code highlight]
-    const formData = await request.formData();
-    const command = formData.get("command");
-    const text = formData.get("text");
+    const data = await request.json();
 
-    if (command === "/status") {
-      // Respond immediately to Slack
-      await sendSlackResponse(request, "Checking status...");
-
-      // Process the command
-      const status = await checkSystemStatus();
-      await postToSlack(channelId, `Status: ${status}`);
-    }
-
-    if (text === "stop") {
-      await sendStopResponse(request);
+    if (data.type === "done") {
+      await sendAck(request, "Workflow complete");
       break;
     }
-  }
-}
-
-async function checkSystemStatus() {
-  "use step";
-  return "All systems operational";
-}
 
-async function postToSlack(channelId: string, message: string) {
-  "use step";
-  // Post message to Slack
+    await sendAck(request, "Event received");
+    await processEvent(data);
+  }
 }
 ```
 

package/docs/api-reference/workflow-api/get-run.mdx

@@ -47,6 +47,22 @@ import type { WorkflowReadableStreamOptions } from "workflow/api";
 export default WorkflowReadableStreamOptions;`}
 />
 
+#### StopSleepOptions
+
+<TSDoc
+definition={`
+import type { StopSleepOptions } from "workflow/api";
+export default StopSleepOptions;`}
+/>
+
+#### StopSleepResult
+
+<TSDoc
+definition={`
+import type { StopSleepResult } from "workflow/api";
+export default StopSleepResult;`}
+/>
+
 ## Examples
 
 ### Basic Status Check
@@ -78,6 +94,33 @@ export async function GET(req: Request) {
 }
 ```
 
+### Wake Up a Sleeping Workflow
+
+Interrupt pending `sleep()` calls to resume a workflow early. This is useful for testing workflows or building custom UIs that let users skip wait periods:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+export async function POST(req: Request) {
+  const { runId } = await req.json();
+  const run = getRun(runId);
+
+  // Wake up all pending sleep calls
+  const { stoppedCount } = await run.wakeUp(); // [!code highlight]
+
+  return Response.json({ stoppedCount });
+}
+```
+
+You can also target specific sleep calls by correlation ID:
+
+```typescript lineNumbers
+const run = getRun("my-run-id"); // @setup
+const { stoppedCount } = await run.wakeUp({
+  correlationIds: ["wait_abc123"],
+});
+```
+
 ## Related Functions
 
 - [`start()`](/docs/api-reference/workflow-api/start) - Start a new workflow and get its run ID.

package/docs/api-reference/workflow-api/resume-webhook.mdx

@@ -56,11 +56,17 @@ Returns a `Promise<Response>` that resolves to:
 
 Throws an error if the webhook token is not found or invalid.
 
-## Examples
+## Usage Note
 
-### Basic API Route
+<Callout type="warn">
+In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a random webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
+
+For server-side hook resumption with deterministic tokens, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) with [`createHook()`](/docs/api-reference/workflow/create-hook) instead.
+</Callout>
 
-Forward incoming HTTP requests to a webhook by token:
+## Example
+
+Forward an incoming HTTP request to a webhook by token:
 
 ```typescript lineNumbers
 import { resumeWebhook } from "workflow/api";
@@ -82,159 +88,6 @@ export async function POST(request: Request) {
 }
 ```
 
-### GitHub Webhook Handler
-
-Handle GitHub webhook events and forward them to workflows:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-import { verifyGitHubSignature } from "@/lib/github";
-
-export async function POST(request: Request) {
-  // Extract repository name from URL
-  const url = new URL(request.url);
-  const repo = url.pathname.split("/").pop();
-
-  // Verify GitHub signature
-  const signature = request.headers.get("x-hub-signature-256");
-  const isValid = await verifyGitHubSignature(request, signature);
-
-  if (!isValid) {
-    return new Response("Invalid signature", { status: 401 });
-  }
-
-  // Construct deterministic token
-  const token = `github_webhook:${repo}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    return new Response("Workflow not found", { status: 404 });
-  }
-}
-```
-
-### Slack Slash Command Handler
-
-Process Slack slash commands and route them to workflow webhooks:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-
-export async function POST(request: Request) {
-  const formData = await request.formData();
-  const channelId = formData.get("channel_id") as string;
-  const command = formData.get("command") as string;
-
-  // Verify Slack request signature
-  const slackSignature = request.headers.get("x-slack-signature");
-  if (!slackSignature) {
-    return new Response("Unauthorized", { status: 401 });
-  }
-
-  // Construct token from channel ID
-  const token = `slack_command:${channelId}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    // If no workflow is listening, return a default response
-    return new Response(
-      JSON.stringify({
-        response_type: "ephemeral",
-        text: "No active workflow for this channel"
-      }),
-      {
-        headers: { "Content-Type": "application/json" }
-      }
-    );
-  }
-}
-```
-
-### Multi-Tenant Webhook Router
-
-Route webhooks to different workflows based on tenant/organization:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-
-export async function POST(request: Request) {
-  const url = new URL(request.url);
-
-  // Extract tenant and webhook ID from path
-  // e.g., /api/webhooks/tenant-123/webhook-abc
-  const [, , , tenantId, webhookId] = url.pathname.split("/");
-
-  if (!tenantId || !webhookId) {
-    return new Response("Invalid webhook URL", { status: 400 });
-  }
-
-  // Verify API key for tenant
-  const apiKey = request.headers.get("authorization");
-  const isAuthorized = await verifyTenantApiKey(tenantId, apiKey);
-
-  if (!isAuthorized) {
-    return new Response("Unauthorized", { status: 401 });
-  }
-
-  // Construct namespaced token
-  const token = `tenant:${tenantId}:webhook:${webhookId}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    return new Response("Webhook not found or expired", { status: 404 });
-  }
-}
-
-async function verifyTenantApiKey(tenantId: string, apiKey: string | null) {
-  // Verify API key logic
-  return apiKey === process.env[`TENANT_${tenantId}_API_KEY`];
-}
-```
-
-### Server Action (Next.js)
-
-Use `resumeWebhook` in a Next.js server action:
-
-```typescript lineNumbers
-"use server";
-
-import { resumeWebhook } from "workflow/api";
-
-export async function triggerWebhook(
-  token: string,
-  payload: Record<string, any>
-) {
-  // Create a Request object from the payload
-  const request = new Request("http://localhost/webhook", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(payload),
-  });
-
-  try {
-    const response = await resumeWebhook(token, request);
-
-    // Parse and return the response
-    const contentType = response.headers.get("content-type");
-    if (contentType?.includes("application/json")) {
-      return await response.json();
-    }
-
-    return await response.text();
-  } catch (error) {
-    throw new Error("Webhook not found");
-  }
-}
-```
-
 ## Related Functions
 
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Create a webhook in a workflow

package/docs/deploying/index.mdx

@@ -49,6 +49,8 @@ Simply deploy your application:
 vercel deploy
 ```
 
+<FluidComputeCallout />
+
 <Callout>
   Learn more about the [Vercel World](/worlds/vercel) and its capabilities.
 </Callout>

package/docs/deploying/world/vercel-world.mdx

@@ -22,6 +22,8 @@ Deploy your application to Vercel:
 vercel deploy
 ```
 
+<FluidComputeCallout />
+
 That's it. Vercel automatically:
 
 - Selects the Vercel World backend

package/docs/foundations/hooks.mdx

@@ -339,53 +339,36 @@ Like hooks, webhooks support iteration:
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow";
 
-async function respondToSlack(request: RequestWithResponse, text: string) {
+async function sendAck(request: RequestWithResponse, message: string) {
   "use step";
 
   await request.respondWith(
-    new Response(
-      JSON.stringify({ response_type: "in_channel", text }),
-      { headers: { "Content-Type": "application/json" } }
-    )
+    Response.json({ received: true, message })
   );
 }
 
-export async function slackCommandWorkflow(channelId: string) {
-  "use workflow";
+async function processEvent(data: any) {
+  "use step";
+  console.log("Processing event:", data);
+}
 
-  using webhook = createWebhook({
-    token: `slack_command:${channelId}`,
-    respondWith: "manual"
-  });
+export async function eventCollectorWorkflow() {
+  "use workflow";
 
-  console.log("Configure Slack command webhook:", webhook.url);
+  using webhook = createWebhook({ respondWith: "manual" });
+  console.log("Send events to:", webhook.url);
 
   for await (const request of webhook) {
-    const formData = await request.formData();
-    const command = formData.get("command");
-    const text = formData.get("text");
-
-    if (command === "/status") {
-      await respondToSlack(request, "Checking status...");
-      const status = await checkSystemStatus();
-      await postToSlack(channelId, `Status: ${status}`);
-    }
+    const data = await request.json();
 
-    if (text === "stop") {
-      await respondToSlack(request, "Stopping workflow...");
+    if (data.type === "done") {
+      await sendAck(request, "Workflow complete");
       break;
     }
-  }
-}
 
-async function checkSystemStatus() {
-  "use step";
-  return "All systems operational";
-}
-
-async function postToSlack(channelId: string, message: string) {
-  "use step";
-  // Post message to Slack
+    await sendAck(request, "Event received");
+    await processEvent(data);
+  }
 }
 ```
 
@@ -464,7 +447,9 @@ This pattern is especially valuable in larger applications where the workflow an
 
 ### Token Design
 
-When using custom tokens:
+Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always use randomly generated tokens to prevent unauthorized access to public webhook endpoints.
+
+When using custom tokens with `createHook()`:
 
 - **Make them deterministic**: Base them on data the external system can reconstruct (like channel IDs, user IDs, etc.)
 - **Use namespacing**: Prefix tokens to avoid conflicts (e.g., `slack:${channelId}`, `github:${repoId}`)

package/docs/foundations/workflows-and-steps.mdx

@@ -122,6 +122,8 @@ Keep in mind that calling a step function outside of a workflow function will no
 
 Workflow functions have the ability to automatically suspend while they wait on asynchronous work. While suspended, the workflow's state is stored via the [event log](/docs/how-it-works/event-sourcing) and no compute resources are used until the workflow resumes execution.
 
+<FluidComputeCallout />
+
 There are multiple ways a workflow can suspend:
 
 - Waiting on a step function: the workflow yields while the step runs in the step runtime.

package/docs/getting-started/astro.mdx

@@ -225,6 +225,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 To deploy your Astro project to Vercel, ensure that the [Astro Vercel adapter](https://docs.astro.build/en/guides/integrations-guide/vercel) is configured:
 
 ```bash

package/docs/getting-started/express.mdx

@@ -258,6 +258,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/getting-started/fastify.mdx

@@ -245,6 +245,8 @@ npx workflow inspect runs # add '--web' for an interactive Web based UI
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/getting-started/hono.mdx

@@ -240,6 +240,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/getting-started/nestjs.mdx

@@ -327,6 +327,8 @@ WorkflowModule.forRoot({
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/getting-started/next.mdx

@@ -260,6 +260,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Troubleshooting

package/docs/getting-started/nitro.mdx

@@ -224,6 +224,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/getting-started/nuxt.mdx

@@ -225,6 +225,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/getting-started/sveltekit.mdx

@@ -224,6 +224,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/getting-started/vite.mdx

@@ -230,6 +230,8 @@ npx workflow inspect runs
 
 Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
 
+<FluidComputeCallout />
+
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
 ## Next Steps

package/docs/meta.json

@@ -7,6 +7,7 @@
     "how-it-works",
     "observability",
     "ai",
+    "testing",
     "deploying",
     "errors",
     "api-reference"

package/docs/testing/index.mdx

@@ -0,0 +1,368 @@
+---
+title: Testing
+description: Unit test individual steps and integration test entire workflows using Vitest and the Vite plugin.
+type: conceptual
+summary: Learn how to unit test steps and integration test workflows using Vitest.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+  - /docs/getting-started/vite
+related:
+  - /docs/foundations/hooks
+  - /docs/api-reference/workflow-api/start
+  - /docs/api-reference/workflow-api/resume-hook
+  - /docs/api-reference/workflow-api/get-run
+  - /docs/observability
+---
+
+Testing is a critical part of building reliable workflows. Because steps are just functions annotated with directives, they can be unit tested like any other JavaScript function. Workflow DevKit also provides a [Vite plugin](/docs/getting-started/vite) that integrates with [Vitest](https://vitest.dev), enabling full integration tests against a real workflow runtime.
+
+This guide covers two approaches:
+
+1. **Unit testing** - Test individual steps as plain functions, without the workflow runtime.
+2. **Integration testing** - Test entire workflows against a real workflow setup using the Vite plugin. Required for workflows that use [hooks](/docs/foundations/hooks), webhooks, [`sleep()`](/docs/api-reference/workflow/sleep), or retries.
+
+## Unit Testing Steps
+
+Without the workflow compiler, the `"use step"` directive is a no-op. Your step functions run as regular JavaScript functions, making them straightforward to unit test with no special configuration.
+
+### Example Steps
+
+Given a workflow file with step functions like this:
+
+```typescript title="workflows/user-signup.ts" lineNumbers
+import { sleep } from "workflow";
+
+export async function handleUserSignup(email: string) {
+  "use workflow";
+
+  const user = await createUser(email);
+  await sendWelcomeEmail(user);
+
+  await sleep("5d");
+  await sendOnboardingEmail(user);
+
+  return { userId: user.id, status: "onboarded" };
+}
+
+export async function createUser(email: string) {
+  "use step"; // [!code highlight]
+  return { id: crypto.randomUUID(), email };
+}
+
+export async function sendWelcomeEmail(user: { id: string; email: string }) {
+  "use step"; // [!code highlight]
+  // Send email logic
+}
+
+export async function sendOnboardingEmail(user: { id: string; email: string }) {
+  "use step"; // [!code highlight]
+  // Send email logic
+}
+```
+
+### Writing Unit Tests for Steps
+
+You can import and test step functions directly with Vitest. No special configuration or workflow plugin is needed:
+
+```typescript title="workflows/user-signup.test.ts" lineNumbers
+import { describe, it, expect } from "vitest";
+import { createUser, sendWelcomeEmail } from "./user-signup"; // [!code highlight]
+
+describe("createUser step", () => {
+  it("should create a user with the given email", async () => {
+    const user = await createUser("test@example.com");
+
+    expect(user.email).toBe("test@example.com");
+    expect(user.id).toBeDefined();
+  });
+});
+
+describe("sendWelcomeEmail step", () => {
+  it("should send a welcome email without throwing", async () => {
+    const user = { id: "user-1", email: "test@example.com" };
+    await expect(sendWelcomeEmail(user)).resolves.not.toThrow();
+  });
+});
+```
+
+This approach is ideal for verifying the business logic inside individual steps in isolation.
+
+<Callout type="info">
+Unit testing works well for individual steps. A simple workflow that only calls steps can also be unit tested this way, since `"use workflow"` is similarly a no-op without the compiler. However, any workflow that uses runtime features like [`sleep()`](/docs/api-reference/workflow/sleep), [hooks](/docs/foundations/hooks), or [webhooks](/docs/foundations/hooks#understanding-webhooks) cannot be unit tested directly because those APIs require the workflow runtime. Use [integration testing](#integration-testing-with-the-vite-plugin) for testing entire workflows, especially those that depend on workflow-only features.
+</Callout>
+
+## Integration Testing with the Vite Plugin
+
+For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `workflow/vite` plugin integrates directly with Vitest, compiling your `"use workflow"` and `"use step"` directives so the full workflow runtime is active during tests.
+
+### Vitest Configuration
+
+Create a separate Vitest config for integration tests that includes the `workflow()` plugin and a `globalSetup` script:
+
+```typescript title="vitest.integration.config.ts" lineNumbers
+import { defineConfig } from "vitest/config";
+import { workflow } from "workflow/vite"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [workflow()], // [!code highlight]
+  test: {
+    include: ["**/*.integration.test.ts"],
+    testTimeout: 60_000, // Workflows may take longer than default timeout
+    globalSetup: "./vitest.integration.setup.ts", // [!code highlight]
+  },
+});
+```
+
+<Callout type="info">
+Use a separate Vitest configuration and a distinct file naming convention (e.g. `*.integration.test.ts`) to keep unit tests and integration tests separate. Unit tests run with a standard Vitest config without the workflow plugin, while integration tests use the config above.
+</Callout>
+
+### Global Setup Script
+
+Integration tests need a running server to execute workflow steps. The `globalSetup` script starts a [Nitro](https://v3.nitro.build) server as a sidecar process before tests run, and tears it down afterwards:
+
+```typescript title="vitest.integration.setup.ts" lineNumbers
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import type { ChildProcess } from "node:child_process";
+
+let server: ChildProcess | null = null;
+const PORT = "4000";
+
+export async function setup() { // [!code highlight]
+  console.log("Starting server for workflow execution...");
+
+  server = spawn("npx", ["nitro", "dev", "--port", PORT], {
+    stdio: "pipe",
+    detached: false,
+    env: process.env,
+  });
+
+  // Wait for the server to be ready
+  const ready = await new Promise<boolean>((resolve) => {
+    const timeout = setTimeout(() => resolve(false), 15_000);
+
+    server?.stdout?.on("data", (data) => {
+      const output = data.toString();
+      console.log("[server]", output);
+      if (output.includes("listening") || output.includes("ready")) {
+        clearTimeout(timeout);
+        resolve(true);
+      }
+    });
+
+    server?.stderr?.on("data", (data) => {
+      console.error("[server]", data.toString());
+    });
+
+    server?.on("error", (error) => {
+      console.error("Failed to start server:", error);
+      clearTimeout(timeout);
+      resolve(false);
+    });
+  });
+
+  if (!ready) {
+    throw new Error("Server failed to start within 15 seconds");
+  }
+
+  await delay(2_000); // Allow full initialization
+
+  // Point the workflow runtime at the local server
+  process.env.WORKFLOW_LOCAL_BASE_URL = `http://localhost:${PORT}`; // [!code highlight]
+  process.env.WORKFLOW_LOCAL_DATA_DIR = "./.workflow-data"; // [!code highlight]
+
+  console.log("Server ready for workflow execution");
+}
+
+export async function teardown() { // [!code highlight]
+  if (server) {
+    console.log("Stopping server...");
+    server.kill("SIGTERM");
+    await delay(1_000);
+    if (!server.killed) {
+      server.kill("SIGKILL");
+    }
+  }
+}
+```
+
+The setup script sets two environment variables that the workflow runtime reads:
+
+- `WORKFLOW_LOCAL_BASE_URL` tells the runtime where to send step execution requests
+- `WORKFLOW_LOCAL_DATA_DIR` tells the runtime where to persist workflow state locally
+
+<Callout type="info">
+You can use any server framework that supports the workflow runtime. The example above uses [Nitro](https://v3.nitro.build), but you could also use a [Next.js](https://nextjs.org), [Hono](https://hono.dev), or any other supported server.
+</Callout>
+
+### Running Integration Tests
+
+Add a script to your `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "vitest",
+    "test:integration": "vitest --config vitest.integration.config.ts"
+  }
+}
+```
+
+### Testing Hooks and Waits
+
+The real power of integration testing comes when testing workflow-only features. Hooks and waits can be resumed programmatically using the [`workflow/api`](/docs/api-reference/workflow-api) functions, making it straightforward to simulate external events in your tests.
+
+Given a workflow that waits for approval via a hook, then sleeps before publishing:
+
+```typescript title="workflows/approval.ts" lineNumbers
+import { createHook, sleep } from "workflow";
+
+export async function approvalWorkflow(documentId: string) {
+  "use workflow";
+
+  const prepared = await prepareDocument(documentId);
+
+  using hook = createHook<{ approved: boolean; reviewer: string }>({ // [!code highlight]
+    token: `approval:${documentId}`, // [!code highlight]
+  }); // [!code highlight]
+
+  const decision = await hook; // [!code highlight]
+
+  if (decision.approved) {
+    // Wait 24 hours before publishing (e.g. grace period for retractions)
+    await sleep("24h"); // [!code highlight]
+    await publishDocument(prepared);
+    return { status: "published", reviewer: decision.reviewer };
+  }
+
+  return { status: "rejected", reviewer: decision.reviewer };
+}
+
+async function prepareDocument(documentId: string) {
+  "use step";
+  return { id: documentId, content: "..." };
+}
+
+async function publishDocument(doc: { id: string; content: string }) {
+  "use step";
+  console.log(`Publishing document ${doc.id}`);
+}
+```
+
+You can write an integration test that starts the workflow, resumes the hook, and uses [`wakeUp()`](/docs/api-reference/workflow-api/get-run) to skip the sleep — so your tests don't have to wait for the full duration:
+
+```typescript title="workflows/approval.integration.test.ts" lineNumbers
+import { describe, it, expect } from "vitest";
+import { setTimeout as delay } from "node:timers/promises";
+import { start, getRun, resumeHook } from "workflow/api"; // [!code highlight]
+import { approvalWorkflow } from "./approval";
+
+describe("approvalWorkflow", () => {
+  it("should publish when approved", async () => {
+    const run = await start(approvalWorkflow, ["doc-123"]); // [!code highlight]
+
+    // Resume the hook programmatically, simulating an external approval
+    await resumeHook("approval:doc-123", { // [!code highlight]
+      approved: true, // [!code highlight]
+      reviewer: "alice", // [!code highlight]
+    }); // [!code highlight]
+
+    // Wait for the workflow to replay and reach the sleep() call
+    await delay(5_000); // [!code highlight]
+
+    // Skip the 24-hour sleep so the test completes immediately
+    await getRun(run.runId).wakeUp(); // [!code highlight]
+
+    const result = await run.returnValue;
+    expect(result).toEqual({
+      status: "published",
+      reviewer: "alice",
+    });
+  });
+
+  it("should reject when not approved", async () => {
+    const run = await start(approvalWorkflow, ["doc-456"]);
+
+    await resumeHook("approval:doc-456", {
+      approved: false,
+      reviewer: "bob",
+    });
+
+    // No wakeUp() needed here — the rejected path has no sleep
+    const result = await run.returnValue;
+    expect(result).toEqual({
+      status: "rejected",
+      reviewer: "bob",
+    });
+  });
+});
+```
+
+<Callout type="info">
+[`start()`](/docs/api-reference/workflow-api/start), [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), and [`getRun().wakeUp()`](/docs/api-reference/workflow-api/get-run) are the key API functions for integration testing. Use `start()` to trigger a workflow, `resumeHook()` to simulate external events, and `wakeUp()` to skip `sleep()` calls so tests run instantly. See the [API Reference](/docs/api-reference/workflow-api) for the full list of available functions.
+</Callout>
+
+## Debugging Test Runs
+
+When integration tests fail, the [Workflow DevKit CLI and Web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state to `WORKFLOW_LOCAL_DATA_DIR`, you can use the same observability tools you would use in development.
+
+Launch the Web UI to visually explore your test workflow runs:
+
+```bash
+npx workflow web
+```
+
+Or use the CLI to inspect runs in the terminal:
+
+```bash
+# List recent workflow runs
+npx workflow inspect runs
+
+# Inspect a specific run
+npx workflow inspect runs <run-id>
+```
+
+The Web UI shows each step, its inputs and outputs, retry attempts, hook state, and timing. This is especially useful for diagnosing issues with hooks that were not resumed, steps that failed unexpectedly, or workflows that timed out.
+
+![Workflow DevKit Web UI](/o11y-ui.png)
+
+<Callout type="info">
+See the [Observability](/docs/observability) docs for the full set of CLI commands and Web UI features.
+</Callout>
+
+## Best Practices
+
+### Separate Unit and Integration Tests
+
+Keep two test configurations:
+
+- **Unit tests** - Standard Vitest config, no workflow plugin. Fast, no infrastructure required.
+- **Integration tests** - Vitest config with `workflow()` plugin. Tests the full workflow lifecycle including hooks, sleeps, and retries.
+
+### Use Custom Hook Tokens for Deterministic Testing
+
+When testing workflows with hooks, use [custom tokens](/docs/foundations/hooks#custom-tokens-for-deterministic-hooks) based on predictable values (like document IDs or test identifiers). This makes it easy to resume the correct hook in your test code.
+
+### Set Appropriate Timeouts
+
+Workflows may take longer to execute than typical unit tests, especially when they involve multiple steps or retries. Set a generous `testTimeout` in your integration test config.
+
+### Test Error and Retry Scenarios
+
+Integration tests are the right place to verify that your workflows handle errors correctly, including retryable errors, fatal errors, and timeout scenarios.
+
+## Further Reading
+
+- [Hooks & Webhooks](/docs/foundations/hooks) - Pausing and resuming workflows with external data
+- [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows programmatically
+- [`resumeHook()` API Reference](/docs/api-reference/workflow-api/resume-hook) - Resume hooks with data
+- [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Check workflow run status and wake up sleeping runs
+- [Vite Integration](/docs/getting-started/vite) - Set up the Vite plugin
+- [Observability](/docs/observability) - Inspect and debug workflow runs with the CLI and Web UI
+
+---
+
+<Callout type="info">
+This guide was inspired by the testing approach described in Mux's article [*Launching durable AI workflows for video with @mux/ai*](https://www.mux.com/blog/launching-durable-ai-workflows-for-video-with-mux-ai#testing), which demonstrates how Mux uses the `workflow/vite` plugin with Vitest to integration test their durable AI video workflows built on Workflow DevKit.
+</Callout>

package/docs/testing/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Testing",
+  "pages": ["testing"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.1.0-beta.62",
+  "version": "4.2.0-beta.64",
   "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -52,17 +52,17 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.36",
-    "@workflow/cli": "4.1.0-beta.62",
-    "@workflow/core": "4.1.0-beta.62",
-    "@workflow/errors": "4.1.0-beta.17",
+    "@workflow/astro": "4.0.0-beta.38",
+    "@workflow/cli": "4.2.0-beta.64",
+    "@workflow/core": "4.2.0-beta.64",
+    "@workflow/errors": "4.1.0-beta.18",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
-    "@workflow/next": "4.0.1-beta.58",
-    "@workflow/nest": "0.0.0-beta.11",
-    "@workflow/nitro": "4.0.1-beta.57",
-    "@workflow/nuxt": "4.0.1-beta.46",
-    "@workflow/sveltekit": "4.0.0-beta.51",
-    "@workflow/rollup": "4.0.0-beta.19"
+    "@workflow/next": "4.0.1-beta.60",
+    "@workflow/nest": "0.0.0-beta.13",
+    "@workflow/nitro": "4.0.1-beta.59",
+    "@workflow/nuxt": "4.0.1-beta.48",
+    "@workflow/sveltekit": "4.0.0-beta.53",
+    "@workflow/rollup": "4.0.0-beta.21"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",