workflow 4.2.0-beta.73 → 4.2.0-beta.75

package/README.md

@@ -2,7 +2,7 @@
   <a href="https://useworkflow.dev">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="https://useworkflow.dev/workflow-circle-symbol-dark.svg">
-      <img alt="Workflow DevKit logo" src="https://useworkflow.dev/workflow-circle-symbol-light.svg" height="128">
+      <img alt="Workflow SDK logo" src="https://useworkflow.dev/workflow-circle-symbol-light.svg" height="128">
     </picture>
   </a>
   <h1>Workflow Development Kit</h1>
@@ -22,15 +22,15 @@ Visit [https://useworkflow.dev](https://useworkflow.dev) to view the full docume
 
 ## Community
 
-The Workflow DevKit community can be found on [GitHub Discussions](https://github.com/vercel/workflow/discussions), where you can ask questions, voice ideas, and share your projects with other people.
+The Workflow SDK community can be found on [GitHub Discussions](https://github.com/vercel/workflow/discussions), where you can ask questions, voice ideas, and share your projects with other people.
 
 ## Contributing
 
-Contributions to Workflow DevKit are welcome and highly appreciated. Please use GitHub [issues](https://github.com/vercel/workflow/issues) and [discussions](https://github.com/vercel/workflow/discussions) to collaborate with the team and wider community.
+Contributions to Workflow SDK are welcome and highly appreciated. Please use GitHub [issues](https://github.com/vercel/workflow/issues) and [discussions](https://github.com/vercel/workflow/discussions) to collaborate with the team and wider community.
 
 ## Author list
 
-Workflow DevKit was built by engineers at [Vercel](https://vercel.com) and the [Open Source Community](https://github.com/vercel/workflow/graphs/contributors).
+Workflow SDK was built by engineers at [Vercel](https://vercel.com) and the [Open Source Community](https://github.com/vercel/workflow/graphs/contributors).
 
 The initial core contributing engineers are:
 
@@ -42,12 +42,12 @@ The initial core contributing engineers are:
 - Peter Wielander ([@VaguelySerious](https://github.com/VaguelySerious))
 - Pranay Prakash ([@pranaygp](https://github.com/pranaygp))
 
-The Workflow DevKit logo was designed by Cecilio Ruiz [@ceciliorz](https://x.com/ceciliorz)
+The Workflow SDK logo was designed by Cecilio Ruiz [@ceciliorz](https://x.com/ceciliorz)
 
 ---
 
 ## Security
 
-If you believe you have found a security vulnerability in Workflow DevKit, we encourage you to **_responsibly disclose this and not open a public issue_**.
+If you believe you have found a security vulnerability in Workflow SDK, we encourage you to **_responsibly disclose this and not open a public issue_**.
 
 To participate in our Open Source Software Bug Bounty program, please email [responsible.disclosure@vercel.com](mailto:responsible.disclosure@vercel.com). We will add you to the program and provide further instructions for submitting your report.

package/docs/ai/defining-tools.mdx

@@ -1,6 +1,6 @@
 ---
 title: Patterns for Defining Tools
-description: Common patterns for defining tools in durable AI agents using Workflow DevKit.
+description: Common patterns for defining tools in durable AI agents using Workflow SDK.
 type: guide
 summary: Define step-level and workflow-level tools for durable AI agents with stream writing and context access.
 prerequisites:
@@ -12,7 +12,7 @@ related:
   - /docs/api-reference/workflow/get-writable
 ---
 
-This page covers the details for some common patterns when defining tools for AI agents using Workflow DevKit.
+This page covers the details for some common patterns when defining tools for AI agents using Workflow SDK.
 
 Using DurableAgent, we model most tools as steps. These can be anything from a simple function call to a entire multi-day long workflow.
 

package/docs/ai/human-in-the-loop.mdx

@@ -15,7 +15,7 @@ related:
 
 A common pre-requisite for running AI agents in production is the ability to wait for human input or external events before proceeding.
 
-Workflow DevKit's [webhook](/docs/api-reference/workflow/create-webhook) and [hook](/docs/api-reference/workflow/define-hook) primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action, allowing smooth resumption of workflows even after days of inactivity, and provides stability across code deployments.
+Workflow SDK's [webhook](/docs/api-reference/workflow/create-webhook) and [hook](/docs/api-reference/workflow/define-hook) primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action, allowing smooth resumption of workflows even after days of inactivity, and provides stability across code deployments.
 
 If you need to react to external events programmatically, see the [hooks](/docs/foundations/hooks) documentation for more information. This part of the guide will focus on the human-in-the-loop pattern, which is a subset of the more general hook pattern.
 

package/docs/ai/index.mdx

@@ -2,7 +2,7 @@
 title: Building Durable AI Agents
 description: Build AI agents that survive crashes, scale across requests, and maintain state with durable LLM tool-call loops.
 type: overview
-summary: Convert a basic AI chat app into a durable, resumable agent using Workflow DevKit.
+summary: Convert a basic AI chat app into a durable, resumable agent using Workflow SDK.
 related:
   - /docs/foundations/workflows-and-steps
   - /docs/foundations/streaming
@@ -15,11 +15,11 @@ related:
 
 AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events.
 
-Workflow DevKit makes your agents production-ready, by turning them into durable, resumable workflows. It transforms your LLM calls, tool executions, and other async operations into retryable, scalable, and observable steps.
+Workflow SDK makes your agents production-ready, by turning them into durable, resumable workflows. It transforms your LLM calls, tool executions, and other async operations into retryable, scalable, and observable steps.
 
 <AgentTraces />
 
-This guide walks you through converting a basic AI chat app into a durable AI agent using Workflow DevKit.
+This guide walks you through converting a basic AI chat app into a durable AI agent using Workflow SDK.
 
 ## Why Durable Agents?
 
@@ -30,20 +30,20 @@ Aside from the usual challenges of getting your long-running tasks to be product
 - **Resumability**: Resuming streams requires not just storing your messages, but also storing streams, and piping them across services.
 - **Human-in-the-loop**: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations.
 
-Workflow DevKit provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
+Workflow SDK provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
 
 ## Getting Started
 
 To make an Agent durable, we first need an Agent, which we'll be setting up here. If you already have an app you'd like to follow along with, you can skip this section.
 
-For our example, we'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow DevKit to it. We'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
+For our example, we'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow SDK to it. We'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
 
 <Steps>
 
 <Step>
 ### Clone example app
 
-We'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow DevKit to it. For the follow-along steps, we'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
+We'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow SDK to it. For the follow-along steps, we'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
 
 If you have your own project, you can skip this step, and simply apply the changes of the following steps to your own project.
 
@@ -219,7 +219,7 @@ export default function ChatPage() {
 
 </Steps>
 
-## Integrating Workflow DevKit
+## Integrating Workflow SDK
 
 Now that we have a basic agent using AI SDK, we can modify it to make it durable.
 
@@ -228,7 +228,7 @@ Now that we have a basic agent using AI SDK, we can modify it to make it durable
 
 ### Install Dependencies
 
-Add the Workflow DevKit packages to your project:
+Add the Workflow SDK packages to your project:
 
 ```package-install
 npm i workflow @workflow/ai

package/docs/ai/resumable-streams.mdx

@@ -16,7 +16,7 @@ When building chat interfaces, it's common to run into network interruptions, pa
 
 Where a standard chat implementation would require the user to resend their message and wait for the entire response again, workflow runs are durable, and so are the streams attached to them. This means a stream can be resumed at any point, optionally only syncing the data that was missed since the last connection.
 
-Resumable streams come out of the box with Workflow DevKit, however, the client needs to recognize that a stream exists, and needs to know which stream to reconnect to, and needs to know where to start from. For this, Workflow DevKit provides the [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport) helper, a drop-in transport for the AI SDK that handles client-side resumption logic for you.
+Resumable streams come out of the box with Workflow SDK, however, the client needs to recognize that a stream exists, and needs to know which stream to reconnect to, and needs to know where to start from. For this, Workflow SDK provides the [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport) helper, a drop-in transport for the AI SDK that handles client-side resumption logic for you.
 
 ## Implementing stream resumption
 

package/docs/ai/sleep-and-delays.mdx

@@ -14,7 +14,7 @@ related:
 
 AI agents sometimes need to pause execution in order to schedule recurring or future actions, wait before retrying an operation (e.g. for rate limiting), or wait for external state to be available.
 
-Workflow DevKit's `sleep` function enables Agents to pause execution without consuming resources, and resume at a specified time, after a specified duration, or in response to an external event. Workflow operation that suspend will survive restarts, new deploys, and infrastructure changes, independent of whether the suspense takes seconds or months.
+Workflow SDK's `sleep` function enables Agents to pause execution without consuming resources, and resume at a specified time, after a specified duration, or in response to an external event. Workflow operation that suspend will survive restarts, new deploys, and infrastructure changes, independent of whether the suspense takes seconds or months.
 
 <Callout type="info">
 See the [`sleep()` API Reference](/docs/api-reference/workflow/sleep) for the full list of supported duration formats and detailed API documentation, and see the [hooks](/docs/foundations/hooks) documentation for more information on how to resume in response to external events.
@@ -22,7 +22,7 @@ See the [`sleep()` API Reference](/docs/api-reference/workflow/sleep) for the fu
 
 ## Adding a Sleep Tool
 
-Sleep is a built-in function in Workflow DevKit, so exposing it as a tool is as simple as wrapping it in a tool definition. Learn more about how to define tools in [Patterns for Defining Tools](/docs/ai/defining-tools).
+Sleep is a built-in function in Workflow SDK, so exposing it as a tool is as simple as wrapping it in a tool definition. Learn more about how to define tools in [Patterns for Defining Tools](/docs/ai/defining-tools).
 
 <Steps>
 

package/docs/ai/streaming-updates-from-tools.mdx

@@ -14,7 +14,7 @@ related:
 
 After [building a durable AI agent](/docs/ai), we already get UI message chunks for displaying tool invocations and return values. However, for long-running steps, we may want to show progress updates, or stream step output to the user while it's being generated.
 
-Workflow DevKit enables this by letting step functions write custom chunks to the same stream the agent uses. These chunks appear as data parts in your messages, which you can render however you like.
+Workflow SDK enables this by letting step functions write custom chunks to the same stream the agent uses. These chunks appear as data parts in your messages, which you can render however you like.
 
 As an example, we'll extend out Flight Booking Agent to use emit more granular progress updates while searching for flights.
 

package/docs/api-reference/index.mdx

@@ -1,13 +1,16 @@
 ---
 title: API Reference
-description: Complete reference for all Workflow DevKit functions and primitives by package.
+description: Complete reference for all Workflow SDK functions and primitives by package.
 type: overview
 summary: Browse all available functions and primitives organized by package.
 ---
 
-All the functions and primitives that come with Workflow DevKit by package.
+All the functions and primitives that come with Workflow SDK by package.
 
 <Cards>
+    <Card title="Workflow Globals" href="/docs/api-reference/workflow-globals">
+        Global APIs available inside workflow functions, including deterministic APIs, Web Platform APIs, and environment variables.
+    </Card>
     <Card title="workflow" href="/docs/api-reference/workflow">
         Core workflow primitives including steps, context management, streaming, webhooks, and error handling.
     </Card>
@@ -15,7 +18,10 @@ All the functions and primitives that come with Workflow DevKit by package.
         API reference for runtime functions from the `workflow/api` package.
     </Card>
     <Card title="workflow/next" href="/docs/api-reference/workflow-next">
-        Next.js integration for Workflow DevKit that automatically configures bundling and runtime support.
+        Next.js integration for Workflow SDK that automatically configures bundling and runtime support.
+    </Card>
+    <Card title="workflow/errors" href="/docs/api-reference/workflow-errors">
+        Semantic error types for handling workflow storage backend failures.
     </Card>
     <Card title="@workflow/serde" href="/docs/api-reference/workflow-serde">
         Serialization symbols for custom class serialization in workflows.

package/docs/api-reference/meta.json

@@ -1,4 +1,13 @@
 {
   "title": "API Reference",
-  "pages": ["...", "workflow-errors", "workflow-serde", "workflow-ai", "vitest"]
+  "pages": [
+    "workflow-globals",
+    "workflow",
+    "workflow-api",
+    "workflow-next",
+    "workflow-errors",
+    "workflow-serde",
+    "workflow-ai",
+    "vitest"
+  ]
 }

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

@@ -13,6 +13,10 @@ Creates a webhook that can be used to suspend and resume a workflow run upon rec
 
 Webhooks provide a way for external systems to send HTTP requests directly to your workflow. Unlike hooks which accept arbitrary payloads, webhooks work with standard HTTP `Request` objects and can return HTTP `Response` objects.
 
+<Callout type="warn">
+`createWebhook()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. This is convenient for prototypes and simple resume links because it avoids creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+</Callout>
+
 ```ts lineNumbers
 import { createWebhook } from "workflow"
 

package/docs/api-reference/workflow/index.mdx

@@ -20,7 +20,7 @@ npm i workflow
 
 ## Functions
 
-Workflow DevKit contains the following functions you can use inside your workflow functions:
+Workflow SDK contains the following functions you can use inside your workflow functions:
 
 <Cards>
     <Card href="/docs/api-reference/workflow/get-workflow-metadata" title="getWorkflowMetadata()">
@@ -51,7 +51,7 @@ Workflow DevKit contains the following functions you can use inside your workflo
 
 ## Error Classes
 
-Workflow DevKit includes error classes that can be thrown in a workflow or step to change the error exit strategy of a workflow.
+Workflow SDK includes error classes that can be thrown in a workflow or step to change the error exit strategy of a workflow.
 
 <Cards>
     <Card href="/docs/api-reference/workflow/fatal-error" title="FatalError()">

package/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -204,7 +204,7 @@ export default OutputSpecification;`}
 - **Durable Execution**: Agents can be interrupted and resumed without losing state
 - **Flexible Tool Implementation**: Tools can be implemented as workflow steps for automatic retries, or as regular workflow-level logic
 - **Stream Processing**: Handles streaming responses and tool calls in a structured way
-- **Workflow Native**: Fully integrated with Workflow DevKit for production-grade reliability
+- **Workflow Native**: Fully integrated with Workflow SDK for production-grade reliability
 - **AI SDK Parity**: Supports the same options as AI SDK's `streamText` including generation settings, callbacks, and structured output
 
 ## Good to Know

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

@@ -14,7 +14,7 @@ Use this function when you need direct access to the underlying workflow infrast
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = getWorld(); // [!code highlight]
 ```
 
 ## API Signature
@@ -34,167 +34,43 @@ export default World;`}
 showSections={["returns"]}
 />
 
-## Examples
-
-### List Workflow Runs
-
-List all workflow runs with pagination:
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const cursor = url.searchParams.get("cursor") ?? undefined;
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    const runs = await world.runs.list({
-      pagination: { cursor },
-    });
-
-    return Response.json(runs);
-  } catch (error) {
-    return Response.json(
-      { error: "Failed to list workflow runs" },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### Cancel a Workflow Run
-
-Cancel a running workflow:
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-
-export async function POST(req: Request) {
-  const { runId } = await req.json();
-
-  if (!runId) {
-    return Response.json({ error: "No runId provided" }, { status: 400 });
-  }
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    const run = await world.runs.cancel(runId); // [!code highlight]
-
-    return Response.json({ status: run.status });
-  } catch (error) {
-    return Response.json(
-      { error: "Failed to cancel workflow run" },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### List Steps for a Run (Without Data)
-
-List steps for a workflow run with `resolveData: 'none'` to efficiently get step metadata without fetching serialized input/output. Use `parseStepName` to extract user-friendly display names:
+## World SDK
+
+The World object provides access to several entity interfaces. See the [World SDK](/docs/api-reference/workflow-api/world) reference for complete documentation:
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-api/world/runs" title="world.runs">
+        List, filter, and inspect workflow runs.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/steps" title="world.steps">
+        List and inspect step execution data.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/hooks" title="world.hooks">
+        Look up hooks by ID or token.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/events" title="world.events">
+        Query the append-only event log.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/streams" title="world.streams">
+        Read, write, and manage data streams.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="world.queue">
+        Enqueue runs and create queue handlers.
+    </Card>
+</Cards>
+
+## Data Hydration
+
+Step and run data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `workflow/observability` to hydrate it for display:
 
 ```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "@workflow/utils/parse-name"; // [!code highlight]
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const runId = url.searchParams.get("runId");
-
-  if (!runId) {
-    return Response.json({ error: "No runId provided" }, { status: 400 });
-  }
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    const steps = await world.steps.list({ // [!code highlight]
-      runId, // [!code highlight]
-      resolveData: "none", // Skip fetching input/output for performance // [!code highlight]
-    }); // [!code highlight]
-
-    // Map steps to a progress view using parseStepName for display
-    const progress = steps.data.map((step) => {
-      const parsed = parseStepName(step.stepName); // [!code highlight]
-      return {
-        stepId: step.stepId,
-        // Use shortName for UI display (e.g., "fetchUserData") // [!code highlight]
-        displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
-        // Module info available for debugging // [!code highlight]
-        module: parsed?.moduleSpecifier, // [!code highlight]
-        status: step.status,
-        startedAt: step.startedAt,
-        completedAt: step.completedAt,
-      };
-    });
-
-    return Response.json({ progress, cursor: steps.cursor });
-  } catch (error) {
-    return Response.json(
-      { error: "Failed to list steps" },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### Get Step with Hydrated Input/Output
-
-Retrieve a step with its serialized data and hydrate it for display. This example shows how to decrypt and deserialize step input/output:
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
 
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseStepName } from "@workflow/utils/parse-name"; // [!code highlight]
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!code highlight]
-} from "@workflow/core/serialization-format"; // [!code highlight]
-
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const runId = url.searchParams.get("runId");
-  const stepId = url.searchParams.get("stepId");
-
-  if (!runId || !stepId) {
-    return Response.json({ error: "runId and stepId required" }, { status: 400 });
-  }
-
-  try {
-    const world = getWorld(); // [!code highlight]
-    // Fetch step with data (default resolveData behavior) // [!code highlight]
-    const step = await world.steps.get(runId, stepId); // [!code highlight]
-
-    // Hydrate serialized input/output for display // [!code highlight]
-    const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-
-    // Parse the stepName for user-friendly display
-    const parsed = parseStepName(step.stepName);
-
-    return Response.json({
-      stepId: hydrated.stepId,
-      displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
-      module: parsed?.moduleSpecifier, // [!code highlight]
-      status: hydrated.status,
-      attempt: hydrated.attempt,
-      // Hydrated input/output ready for rendering // [!code highlight]
-      input: hydrated.input, // [!code highlight]
-      output: hydrated.output, // [!code highlight]
-    });
-  } catch (error) {
-    return Response.json(
-      { error: "Step not found" },
-      { status: 404 }
-    );
-  }
-}
+const step = await world.steps.get(runId, stepId);
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
 ```
 
-<Callout type="info">
-  The `stepName` field contains a machine-readable identifier like `step//./src/workflows/order//processPayment`.
-  Use `parseStepName()` from `@workflow/utils/parse-name` to extract the `shortName` (e.g., `"processPayment"`)
-  and `moduleSpecifier` for display in your UI.
-</Callout>
+See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full hydration, parsing, and encryption API.
 
 ## Related Functions
 

package/docs/api-reference/workflow-api/index.mdx

@@ -30,4 +30,7 @@ The API package is for access and introspection of workflow data to inspect runs
     <Card href="/docs/api-reference/workflow-api/get-world" title="getWorld()">
         Get direct access to workflow storage, queuing, and streaming backends.
     </Card>
+    <Card href="/docs/api-reference/workflow-api/world" title="World SDK">
+        Low-level API for inspecting runs, steps, events, hooks, streams, and queues.
+    </Card>
 </Cards>