workflow 5.0.0-beta.50 → 5.0.0-beta.52

package/docs/ai/index.mdx

@@ -57,55 +57,49 @@ cd workflow-examples/flight-booking-app
 
 <Step>
 
-### Set up API keys
+### Configure model access
 
-To connect to an LLM, set up an API key. You can use Vercel Gateway, which works with all providers at zero markup, or configure a custom provider.
-<Tabs items={['Gateway', 'Custom Provider']}>
+<Tabs items={['AI Gateway', 'Provider package']}>
 
-<Tab value="Gateway">
+<Tab value="AI Gateway">
 
-Get a Gateway API key from the [Vercel Gateway](https://vercel.com/docs/ai-gateway/authentication) page.
+AI SDK uses [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) as its default global provider, so plain `"provider/model"` strings need no provider-specific package. Vercel deployments authenticate with OIDC automatically. For local development, link the project and pull a short-lived OIDC token:
 
-Then add it to your `.env.local` file:
-
-```bash title=".env.local" lineNumbers
-GATEWAY_API_KEY=...
+```bash
+vercel link
+vercel env pull .env.local
 ```
 
+You can alternatively set `AI_GATEWAY_API_KEY` from the [AI Gateway authentication](https://vercel.com/docs/ai-gateway/authentication) page.
+
 </Tab>
 
-<Tab value="Custom Provider">
+<Tab value="Provider package">
 
-This is an example of how to use the OpenAI provider for AI SDK. For details on other providers and more details, see the [AI SDK provider guide](https://ai-sdk.dev/providers/ai-sdk-providers).
+`WorkflowAgent` accepts any AI SDK provider. To use OpenAI, install its provider package:
 
 ```package-install
 npm i @ai-sdk/openai
 ```
 
-Set your OpenAI API key in your environment variables:
+Set the provider's API key:
 
 ```bash title=".env.local" lineNumbers
 OPENAI_API_KEY=...
 ```
 
-Then modify your API endpoint to use the OpenAI provider:
+Then construct the model with the provider package:
 
-{/* @skip-typecheck: incomplete code sample */}
-```typescript title="app/api/chat/route.ts" lineNumbers
-// ...
-import { openai } from "@ai-sdk/openai"; // [!code highlight]
+```typescript
+import { openai } from "@ai-sdk/openai";
 
-export async function POST(req: Request) {
-  // ...
-  const agent = new Agent({
-    // This uses the OPENAI_API_KEY environment variable by default, but you
-    // can also pass { apiKey: string } as an option.
-    model: openai("gpt-5.1"), // [!code highlight]
-    // ...
-  });
+const model = openai("gpt-5.6-sol");
 ```
 
+See the [AI SDK provider guide](https://ai-sdk.dev/providers/ai-sdk-providers) for Anthropic, Google, Amazon Bedrock, and other providers.
+
 </Tab>
+
 </Tabs>
 </Step>
 
@@ -131,7 +125,7 @@ import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
   const agent = new ToolLoopAgent({ // [!code highlight]
-    model: "bedrock/claude-4-5-haiku-20251001-v1",
+    model: "spacexai/grok-4.6",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
@@ -257,12 +251,10 @@ export default withWorkflow(nextConfig);
 
 Move the agent logic into a separate function, which will serve as our workflow definition.
 
-{/* @skip-typecheck: Shows two mutually exclusive model options */}
 ```typescript title="workflows/chat/workflow.ts" lineNumbers
 import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow"; // [!code highlight]
 import { getWritable } from "workflow"; // [!code highlight]
-import { tools } from "@/ai/tools";
-import { openai } from "@ai-sdk/openai";
+import { flightBookingTools, FLIGHT_ASSISTANT_PROMPT } from "@/ai/tools";
 import { convertToModelMessages, type UIMessage } from "ai";
 
 export async function chatWorkflow(messages: UIMessage[]) {
@@ -271,13 +263,8 @@ export async function chatWorkflow(messages: UIMessage[]) {
   const writable = getWritable<ModelCallStreamPart>(); // [!code highlight]
 
   const agent = new WorkflowAgent({ // [!code highlight]
-
-    // If using AI Gateway, specify the model name as a string:
-    model: "bedrock/claude-4-5-haiku-20251001-v1", // [!code highlight]
-
-    // ELSE if using a custom provider, pass the provider call as an argument:
-    model: openai("gpt-5.1"), // [!code highlight]
-
+    // Plain model strings use Vercel AI Gateway.
+    model: "spacexai/grok-4.6", // [!code highlight]
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
@@ -291,6 +278,10 @@ export async function chatWorkflow(messages: UIMessage[]) {
 }
 ```
 
+<Callout type="info">
+`WorkflowAgent` accepts any AI SDK provider. Import the provider and pass its model instance, for example `model: openai("gpt-5.6-sol")` from `@ai-sdk/openai`. The rest of the integration is unchanged.
+</Callout>
+
 Key changes:
 
 - Add the `"use workflow"` directive to mark our Agent as a workflow function

package/docs/ai/message-queueing.mdx

@@ -7,7 +7,6 @@ prerequisites:
   - /docs/ai
 related:
   - /docs/ai/chat-session-modeling
-  - /docs/api-reference/workflow-ai/durable-agent
   - /docs/api-reference/workflow/define-hook
 ---
 
@@ -29,27 +28,24 @@ If you need basic multi-turn conversations where messages arrive between turns,
 
 ## The `prepareStep` callback
 
-The `prepareStep` callback runs before each step in the agent loop. It receives the current state and can modify the messages sent to the model:
+The `prepareStep` callback runs before each step in the agent loop. Use WorkflowAgent's exported types rather than redeclaring its normalized provider-prompt contract:
 
 ```typescript lineNumbers
-import type { ModelMessage, LanguageModel } from "ai";
-
-interface PrepareStepInfo {
-  model: string | (() => Promise<LanguageModel>);    // Current model
-  stepNumber: number;                                // 0-indexed step count
-  steps: StepResult[];                               // Previous step results
-  messages: ModelMessage[];                          // Messages to be sent
-}
-
-interface PrepareStepResult {
-  model?: string | (() => Promise<LanguageModel>);   // Override model
-  messages?: ModelMessage[];                         // Override messages
-}
+import type {
+  PrepareStepInfo,
+  PrepareStepResult,
+} from "@ai-sdk/workflow";
+
+const prepareStep = (
+  { messages }: PrepareStepInfo
+): PrepareStepResult => ({ messages });
 ```
 
-## Injecting queued messages
+`PrepareStepInfo.messages` is a normalized `LanguageModelV4Prompt`, not the application-level `ModelMessage[]` accepted by `WorkflowAgent.stream()`.
 
-Once you have a [multi-turn workflow](/docs/ai/chat-session-modeling#multi-turn-workflows), you can combine a message queue with `prepareStep` to inject messages that arrive during processing:
+## Queueing messages during and between turns
+
+Use one async Hook consumer and one FIFO. `prepareStep` atomically drains messages that arrived during a model turn; messages that arrive after the final model step become input to the next turn. Each Hook payload therefore has exactly one ownership path.
 
 ```typescript title="workflows/chat/index.ts" lineNumbers
 import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
@@ -63,112 +59,77 @@ export async function chat(initialMessages: ModelMessage[]) {
 
   const { workflowRunId: runId } = getWorkflowMetadata();
   const writable = getWritable<ModelCallStreamPart>();
+  let messages: ModelMessage[] = [...initialMessages];
   const messageQueue: Array<{ role: "user"; content: string }> = []; // [!code highlight]
+  let stopped = false;
+  let notifyMessage: (() => void) | undefined;
 
   const agent = new WorkflowAgent({
-    model: "bedrock/claude-haiku-4-5-20251001-v1",
+    model: "spacexai/grok-4.6",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
-  // Listen for messages in background (non-blocking) // [!code highlight]
   const hook = chatMessageHook.create({ token: runId }); // [!code highlight]
-  hook.then(({ message }) => { // [!code highlight]
-    messageQueue.push({ role: "user", content: message }); // [!code highlight]
-  }); // [!code highlight]
-
-  await agent.stream({
-    messages: initialMessages,
-    writable,
-    prepareStep: ({ messages: currentMessages }) => { // [!code highlight]
-      // Inject any queued messages before the next LLM call // [!code highlight]
-      if (messageQueue.length > 0) { // [!code highlight]
-        const newMessages = messageQueue.splice(0); // Drain queue // [!code highlight]
-        return { // [!code highlight]
-          messages: [ // [!code highlight]
-            ...currentMessages, // [!code highlight]
-            ...newMessages.map((m) => ({ // [!code highlight]
-              role: m.role, // [!code highlight]
-              content: [{ type: "text" as const, text: m.content }], // [!code highlight]
-            })), // [!code highlight]
-          ], // [!code highlight]
-        }; // [!code highlight]
+  // This is the only code path that consumes Hook payloads. // [!code highlight]
+  const consumeMessages = (async () => { // [!code highlight]
+    for await (const { message } of hook) { // [!code highlight]
+      if (message === "/done") { // [!code highlight]
+        stopped = true; // [!code highlight]
+        notifyMessage?.(); // [!code highlight]
+        break; // [!code highlight]
       } // [!code highlight]
-      return {}; // [!code highlight]
-    }, // [!code highlight]
-  });
-}
-```
-
-Messages sent via `chatMessageHook.resume()` accumulate in the queue and get injected before the next step, whether that's a tool call or another LLM request.
-
-<Callout type="info">
-The `prepareStep` callback receives messages in `ModelMessage[]` format (with content arrays), which is the internal format used by the AI SDK.
-</Callout>
-
-## Combining with multi-turn sessions
-
-You can also combine message queueing with the standard multi-turn pattern:
-
-```typescript title="workflows/chat/index.ts" lineNumbers
-import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
-import { getWritable, getWorkflowMetadata } from "workflow";
-import { chatMessageHook } from "./hooks/chat-message";
-import type { ModelMessage } from "ai";
-
-export async function chat(initialMessages: ModelMessage[]) {
-  "use workflow";
-
-  const { workflowRunId: runId } = getWorkflowMetadata();
-  const writable = getWritable<ModelCallStreamPart>();
-  const messages: ModelMessage[] = [...initialMessages];
-  const messageQueue: Array<{ role: "user"; content: string }> = [];
-
-  const agent = new WorkflowAgent({ /* ... */ });
-  const hook = chatMessageHook.create({ token: runId });
-
-  while (true) {
-    // Set up non-blocking listener for mid-turn messages // [!code highlight]
-    let pendingMessage: string | null = null; // [!code highlight]
-    hook.then(({ message }) => { // [!code highlight]
-      if (message === "/done") return; // [!code highlight]
       messageQueue.push({ role: "user", content: message }); // [!code highlight]
-      pendingMessage = message; // [!code highlight]
-    }); // [!code highlight]
-
+      notifyMessage?.(); // [!code highlight]
+      notifyMessage = undefined; // [!code highlight]
+    } // [!code highlight]
+  })(); // [!code highlight]
+
+  const waitForMessage = async () => {
+    while (messageQueue.length === 0 && !stopped) {
+      await new Promise<void>((resolve) => {
+        notifyMessage = resolve;
+      });
+    }
+  };
+
+  while (!stopped) {
     const result = await agent.stream({
       messages,
       writable,
       preventClose: true,
+      sendFinish: false,
       prepareStep: ({ messages: currentMessages }) => {
-        // Inject queued messages during turn // [!code highlight]
-        if (messageQueue.length > 0) {
-          const newMessages = messageQueue.splice(0);
-          return {
-            messages: [
-              ...currentMessages,
-              ...newMessages.map((m) => ({
-                role: m.role,
-                content: [{ type: "text" as const, text: m.content }],
-              })),
-            ],
-          };
-        }
-        return {};
+        const queued = messageQueue.splice(0); // Atomic drain // [!code highlight]
+        if (queued.length === 0) return {};
+        return {
+          messages: [
+            ...currentMessages,
+            ...queued.map(({ role, content }) => ({
+              role,
+              content: [{ type: "text" as const, text: content }],
+            })),
+          ],
+        };
       },
     });
+    messages = result.messages;
 
-    messages.push(...result.messages.slice(messages.length));
-
-    // Wait for next message (either queued during turn or new) // [!code highlight]
-    const { message: followUp } = pendingMessage ? { message: pendingMessage } : await hook; // [!code highlight]
-    if (followUp === "/done") break;
+    if (stopped) break;
+    await waitForMessage(); // [!code highlight]
+    if (stopped) break;
 
-    messages.push({ role: "user", content: followUp });
+    // Anything not consumed by prepareStep arrived after the final model step.
+    messages = [...messages, ...messageQueue.splice(0)]; // [!code highlight]
   }
+
+  await consumeMessages;
+  return { messages };
 }
 ```
 
+Messages sent via `chatMessageHook.resume()` accumulate until either `prepareStep` or the between-turn branch drains the FIFO. Send `/done` to stop the consumer and let the workflow return.
+
 ## Related documentation
 
 - [Chat Session Modeling](/docs/ai/chat-session-modeling) - Single-turn vs multi-turn patterns

package/docs/api-reference/index.mdx

@@ -51,7 +51,7 @@ All the functions and primitives that come with Workflow SDK by package.
         Serialization symbols for custom class serialization in workflows.
     </Card>
     <Card title="@workflow/ai" href="/docs/api-reference/workflow-ai">
-        Helpers for integrating AI SDK for building AI-powered workflows.
+        Deprecated AI integration APIs kept for existing applications. Use `@ai-sdk/workflow` for new agents.
     </Card>
     <Card title="@workflow/vitest" href="/docs/api-reference/vitest">
         Vitest plugin and test helpers for integration testing workflows in-process.

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

@@ -199,7 +199,7 @@ async function weatherAgentWorkflow(userQuery: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getWeather: {
         description: "Get current weather for a location",
@@ -244,7 +244,7 @@ async function multiToolAgentWorkflow(userQuery: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getWeather: {
         description: "Get weather for a location",
@@ -289,7 +289,7 @@ async function multiTurnAgentWorkflow() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       searchProducts: {
         description: "Search for products",
@@ -368,7 +368,7 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       scheduleTask: {
         description: "Pause the workflow for the specified number of seconds",
@@ -405,7 +405,7 @@ async function agentWithPrepareStep(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "openai/gpt-4.1-mini", // Default model
+    model: "spacexai/grok-4.6", // Default model
     instructions: "You are a helpful assistant.",
   });
 
@@ -459,7 +459,7 @@ async function agentWithMessageQueue(initialMessage: string) {
   });
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     instructions: "You are a helpful assistant.",
   });
 
@@ -500,7 +500,7 @@ async function agentWithGenerationSettings() {
 
   // Set default generation settings in constructor
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     temperature: 0.7,
     maxOutputTokens: 2000,
     topP: 0.9,
@@ -548,7 +548,7 @@ async function multiStepAgent() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       searchWeb: {
         description: "Search the web for information",
@@ -588,7 +588,7 @@ async function agentWithCallbacks() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   await agent.stream({
@@ -630,7 +630,7 @@ async function agentWithStructuredOutput() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   const result = await agent.stream({
@@ -665,7 +665,7 @@ async function agentWithToolChoice() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       calculator: {
         description: "Perform calculations",
@@ -733,7 +733,7 @@ async function agentWithContext(userId: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getUserData: {
         description: "Get user data",
@@ -771,7 +771,7 @@ async function agentWithUIMessages(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     instructions: "You are a helpful assistant.",
   });
 
@@ -819,7 +819,7 @@ async function agentWithToolInspection(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       checkOrderStatus: {
         description: "Check order status",
@@ -874,7 +874,7 @@ async function agentWithTimeout(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   await agent.stream({

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

@@ -1,13 +1,13 @@
 ---
 title: "@workflow/ai"
-description: Helpers for building AI-powered workflows with the AI SDK.
+description: Deprecated AI integration APIs kept for existing Workflow applications.
 type: overview
-summary: Explore helpers for integrating AI SDK to build durable AI-powered workflows.
+summary: Migrate legacy @workflow/ai APIs to AI SDK's WorkflowAgent and WorkflowChatTransport.
 related:
   - /docs/ai
 ---
 
-The `@workflow/ai` package provides helpers for integrating AI SDK into AI-powered workflows.
+The `@workflow/ai` package is deprecated in Workflow 5 and remains documented for existing applications. Build new agents with [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and [`WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) from `@ai-sdk/workflow`.
 
 ## Classes
 

package/docs/changelog/batched-event-writes.mdx

@@ -66,7 +66,7 @@ The contract:
 
 **Per-chunk continuation.** Each chunk's follow-on work starts the moment **that chunk** commits, not when the whole fold does: a chunk's step-execution queue messages publish right off its own commit (publish-after-create holds per step), and only the chunk carrying the inline pairs gates the replay's continuation: trailing chunks' commits and publishes are joined before the invocation can acknowledge its message, so the durability contract ("every create durable before ack") is unchanged.
 
-**Pre-claimed inline pairs.** When the fold engages and has company for them (at least two inline steps, or one plus other batchable events), the steps the runtime is about to execute inline join the batch as adjacent `[step_created, step_started]` pairs: the created row carrying the input, the started row a bare ownership-stamped claim the World folds into a born-running create. The inline bodies start straight off the pair chunk's commit (in parallel with the queue publishes and any trailing chunks) with no per-step claim POST at all, and a pair that loses its atomic create-claim to a concurrent delivery skips its body exactly as a lost lazy claim does. A lone inline step with nothing else to batch keeps the optimistic lazy-start path, whose claim overlaps the body.
+**Pre-claimed inline pairs.** When the fold engages with at least two inline steps, the steps the runtime is about to execute inline join the batch as adjacent `[step_created, step_started]` pairs: the created row carrying the input, the started row a bare ownership-stamped claim the World folds into a born-running create. The pairs commit in a chunk of their own, ahead of the plain `step_created` and `wait_created` chunks, so the write the inline bodies wait for carries only two rows per inline step (a small transaction that commits faster than a full 32-event chunk) while the plain creates commit concurrently beside it. The inline bodies start straight off the pair chunk's commit (in parallel with the queue publishes and the sibling chunks) with no per-step claim POST at all, and a pair that loses its atomic create-claim to a concurrent delivery skips its body exactly as a lost lazy claim does. A lone inline step keeps the optimistic lazy-start path (one row, whose claim overlaps the body) even when eager creates batch beside it: the pairs share no round trip with those creates, so only two or more inline steps make a pair chunk worth the trade. A plain partition of exactly one `step_created` or `wait_created` beside the pairs is written through the ordinary single path rather than a one-row batch, and its queue message still waits for that write.
 
 Per-event `409`s are tolerated the same way the single path tolerates `EntityConflictError` (a concurrent delivery already created the entity); any other per-event failure fails the suspension write the way a single-path rejection would. A batch carrying a `step_started` (that is, any batch with inline pairs) is **not** retried in-process on a transport blip: a pair's `409` cannot be told apart from the caller's own earlier attempt having committed it, so recovery goes through queue redelivery instead, where the step's ownership stamp routes it back to the same invocation.
 

package/docs/configuration/runtime-tuning.mdx

@@ -314,6 +314,11 @@ These variables are primarily for tests, debugging, or unusual deployments.
 - Group-commit window for the *leading* chunk of an idle stream. `0` sends it at once; a positive value holds it up to that many milliseconds to collect a group. This opt-in setting trades first-chunk latency for larger batches and can benefit slow-but-steady producers. Chunks arriving while a request is already in flight always coalesce into the next group regardless of this setting.
 - Also available as `streamFlushIntervalMs` on Worlds that expose it (the env var, when set, takes precedence over the World option).
 
+### `WORKFLOW_STEP_STREAM_DRAIN_TIMEOUT_MS`
+
+- Default: `30000` (30 seconds)
+- Maximum time a step waits for writes queued by a released workflow stream writer to be acknowledged by the Workflow server before recording `step_completed`. A timeout fails the step instead of exposing a completion while released-writer data remains client-side. A writer intentionally kept locked does not trigger this durability wait.
+
 ### `WORKFLOW_STREAM_MAX_INFLIGHT_CHUNKS`
 
 - Default: `1000`

package/docs/configuration/worlds.mdx

@@ -286,7 +286,7 @@ Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, an
 - Factory option: none
 - CLI flag: none
 - Default: `http`
-- Experimental stream-write transport capability. Set to exactly `ws` to advertise support for `workflow-stream-ws/v1` when it becomes available. The server authoritatively accepts or declines an upgrade; a decline uses HTTP directly. Stream reads remain HTTP and demand-driven.
+- Experimental stream-write transport capability. Set to exactly `ws` to attempt `workflow-stream-ws/v1`. The server authoritatively accepts or declines each upgrade; a decline uses HTTP directly for that writer lifetime. Stream reads remain HTTP and demand-driven.
 - This is not tenant rollout policy or a package-version check. HTTP remains the compatibility path. `/websockets/v1` is independent of REST v2/v4 and persisted workflow `specVersion` values.
 
 ### `WORKFLOW_DISABLE_ANALYTICS_READS`