Add DurableAgent compat tests, e2e tests, and migrate to AI SDK v6

.changeset/durable-agent-ai-sdk-v6.md

@@ -0,0 +1,17 @@
+---
+"@workflow/ai": minor
+---
+
+**BREAKING CHANGE**: Migrate to AI SDK v6. Drop AI SDK v5 support.
+
+- Migrate all types from V2 to V3 (`LanguageModelV2*` → `LanguageModelV3*`)
+- Update peer dependency: `ai` `^5 || ^6` → `^6`, `@ai-sdk/provider` `^2 || ^3` → `^3`
+- Simplify `CompatibleLanguageModel` from V2|V3 union to `LanguageModelV3`
+- Remove `providerExecuted` guard on tool-result stream parts (V3: all tool-results are provider-executed)
+- Add `instructions` constructor option (replaces deprecated `system`)
+- Add `onStepFinish` and `onFinish` on constructor (merged with stream callbacks)
+- Add `timeout` stream option
+- Enrich `onFinish` event with `text`, `finishReason`, `totalUsage`
+- Add `@workflow/ai/test` export with `mockTextModel` and `mockSequenceModel` for workflow e2e testing
+- Update `OutputSpecification` to match AI SDK v6 Output interface
+- Fix `WorkflowChatTransport` to forward `body` and `headers` from `ChatRequestOptions` to `prepareSendMessagesRequest` and the default request body

docs/content/docs/ai/chat-session-modeling.mdx

@@ -39,12 +39,12 @@ export async function chat(messages: UIMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
   await agent.stream({
-    messages: convertToModelMessages(messages), // [!code highlight] Full history from client
+    messages: await convertToModelMessages(messages), // [!code highlight] Full history from client
     writable,
   });
 }
@@ -171,7 +171,7 @@ export async function chat(initialMessages: UIMessage[]) {
 
   const { workflowRunId: runId } = getWorkflowMetadata();
   const writable = getWritable<UIMessageChunk>();
-  const messages: ModelMessage[] = convertToModelMessages(initialMessages);
+  const messages: ModelMessage[] = await convertToModelMessages(initialMessages);
 
   // Write markers for initial user messages (for replay) // [!code highlight]
   for (const msg of initialMessages) { // [!code highlight]
@@ -183,7 +183,7 @@ export async function chat(initialMessages: UIMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 

docs/content/docs/ai/defining-tools.mdx

@@ -25,7 +25,7 @@ When you tool needs access to the full message history, you can access it via th
 ```typescript title="tools.ts" lineNumbers
 async function getWeather(
   { city }: { city: string },
-  { messages, toolCallId }: { messages: LanguageModelV2Prompt, toolCallId: string }) { // [!code highlight]
+  { messages, toolCallId }: { messages: ModelMessage[], toolCallId: string }) { // [!code highlight]
   "use step";
   return `Weather in ${city} is sunny`;
 }

docs/content/docs/ai/index.mdx

@@ -127,11 +127,11 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
   const agent = new Agent({ // [!code highlight]
     model: gateway("bedrock/claude-4-5-haiku-20251001-v1"),
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
-  const modelMessages = convertToModelMessages(messages);
-  const stream = agent.stream({ messages: modelMessages }); // [!code highlight]
+  const modelMessages = await convertToModelMessages(messages);
+  const stream = await agent.stream({ messages: modelMessages }); // [!code highlight]
   return createUIMessageStreamResponse({
     stream: stream.toUIMessageStream(),
   });
@@ -273,7 +273,7 @@ export async function chatWorkflow(messages: ModelMessage[]) {
     // ELSE if using a custom provider, pass the provider call as an argument:
     model: openai("gpt-5.1"), // [!code highlight]
 
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
@@ -304,7 +304,7 @@ import { chatWorkflow } from "@/workflows/chat/workflow";
 
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = convertToModelMessages(messages);
+  const modelMessages = await convertToModelMessages(messages);
 
   const run = await start(chatWorkflow, [modelMessages]); // [!code highlight]
 

docs/content/docs/ai/message-queueing.mdx

@@ -33,15 +33,15 @@ The `prepareStep` callback runs before each step in the agent loop. It receives
 
 ```typescript lineNumbers
 interface PrepareStepInfo {
-  model: string | (() => Promise<LanguageModelV2>);  // Current model
+  model: string | (() => Promise<LanguageModel>);    // Current model
   stepNumber: number;                                // 0-indexed step count
   steps: StepResult[];                               // Previous step results
-  messages: LanguageModelV2Prompt;                   // Messages to be sent
+  messages: ModelMessage[];                          // Messages to be sent
 }
 
 interface PrepareStepResult {
-  model?: string | (() => Promise<LanguageModelV2>); // Override model
-  messages?: LanguageModelV2Prompt;                  // Override messages
+  model?: string | (() => Promise<LanguageModel>);   // Override model
+  messages?: ModelMessage[];                         // Override messages
 }
 ```
 
@@ -65,7 +65,7 @@ export async function chat(initialMessages: ModelMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
@@ -101,7 +101,7 @@ export async function chat(initialMessages: ModelMessage[]) {
 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 `LanguageModelV2Prompt` format (with content arrays), which is the internal format used by the AI SDK.
+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

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

@@ -34,7 +34,7 @@ async function myAgent() {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful weather assistant.",
+    instructions: "You are a helpful weather assistant.",
     temperature: 0.7,
     tools: {
       getWeather: {
@@ -249,7 +249,7 @@ async function weatherAgentWorkflow(userQuery: string) {
         execute: getWeather,
       },
     },
-    system: "You are a helpful weather assistant. Always provide accurate weather information.",
+    instructions: "You are a helpful weather assistant. Always provide accurate weather information.",
   });
 
   await agent.stream({
@@ -446,7 +446,7 @@ async function agentWithPrepareStep(userMessage: string) {
 
   const agent = new DurableAgent({
     model: "openai/gpt-4.1-mini", // Default model
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   await agent.stream({
@@ -500,7 +500,7 @@ async function agentWithMessageQueue(initialMessage: string) {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   await agent.stream({
@@ -812,7 +812,7 @@ async function agentWithUIMessages(userMessage: string) {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   const result = await agent.stream({

package.json

@@ -33,7 +33,7 @@
     "test": "turbo test",
     "clean": "turbo clean",
     "typecheck": "turbo typecheck",
-    "test:e2e": "vitest run packages/core/e2e/e2e.test.ts",
+    "test:e2e": "vitest run packages/core/e2e/e2e.test.ts packages/core/e2e/e2e-agent.test.ts",
     "test:e2e:nextjs-webpack:staged": "node scripts/test-staged-nextjs-webpack.mjs",
     "test:docs": "pnpm --filter @workflow/docs-typecheck test:docs",
     "bench": "vitest bench packages/core/e2e/bench.bench.ts",

packages/ai/package.json

@@ -53,6 +53,10 @@
     "./xai": {
       "types": "./dist/providers/xai.d.ts",
       "default": "./dist/providers/xai.js"
+    },
+    "./test": {
+      "types": "./dist/providers/mock.d.ts",
+      "default": "./dist/providers/mock.js"
     }
   },
   "scripts": {
@@ -68,18 +72,19 @@
     "workflow": "workspace:*"
   },
   "peerDependencies": {
-    "ai": "^5 || ^6",
+    "ai": "^6",
     "workflow": "workspace:^"
   },
   "dependencies": {
-    "@ai-sdk/provider": "^2.0.0 || ^3.0.0",
+    "@ai-sdk/provider": "^3.0.0",
+    "@workflow/serde": "workspace:^",
     "zod": "catalog:"
   },
   "optionalDependencies": {
-    "@ai-sdk/anthropic": "^2.0.0 || ^3.0.0",
-    "@ai-sdk/gateway": "^2.0.0 || ^3.0.0",
-    "@ai-sdk/google": "^2.0.0 || ^3.0.0",
-    "@ai-sdk/openai": "^2.0.0 || ^3.0.0",
-    "@ai-sdk/xai": "^2.0.0 || ^3.0.0"
+    "@ai-sdk/anthropic": "^3.0.0",
+    "@ai-sdk/gateway": "^3.0.0",
+    "@ai-sdk/google": "^3.0.0",
+    "@ai-sdk/openai": "^3.0.0",
+    "@ai-sdk/xai": "^3.0.0"
   }
 }

packages/ai/src/agent/do-stream-step.test.ts

@@ -26,10 +26,6 @@ describe('normalizeFinishReason', () => {
     it('should pass through "other"', () => {
       expect(normalizeFinishReason('other')).toBe('other');
     });
-
-    it('should pass through "unknown"', () => {
-      expect(normalizeFinishReason('unknown')).toBe('unknown');
-    });
   });
 
   describe('object finish reasons', () => {
@@ -59,20 +55,20 @@ describe('normalizeFinishReason', () => {
       expect(normalizeFinishReason({ type: 'other' })).toBe('other');
     });
 
-    it('should extract "unknown" from object', () => {
-      expect(normalizeFinishReason({ type: 'unknown' })).toBe('unknown');
+    it('should return "other" for object with unrecognized type', () => {
+      expect(normalizeFinishReason({ type: 'unknown' })).toBe('other');
     });
 
-    it('should return "unknown" for object without type property', () => {
-      expect(normalizeFinishReason({})).toBe('unknown');
+    it('should return "other" for object without type property', () => {
+      expect(normalizeFinishReason({})).toBe('other');
     });
 
-    it('should return "unknown" for object with null type', () => {
-      expect(normalizeFinishReason({ type: null })).toBe('unknown');
+    it('should return "other" for object with null type', () => {
+      expect(normalizeFinishReason({ type: null })).toBe('other');
     });
 
-    it('should return "unknown" for object with undefined type', () => {
-      expect(normalizeFinishReason({ type: undefined })).toBe('unknown');
+    it('should return "other" for object with undefined type', () => {
+      expect(normalizeFinishReason({ type: undefined })).toBe('other');
     });
 
     it('should handle object with additional properties', () => {
@@ -87,24 +83,24 @@ describe('normalizeFinishReason', () => {
   });
 
   describe('edge cases', () => {
-    it('should return "unknown" for undefined', () => {
-      expect(normalizeFinishReason(undefined)).toBe('unknown');
+    it('should return "other" for undefined', () => {
+      expect(normalizeFinishReason(undefined)).toBe('other');
     });
 
-    it('should return "unknown" for null', () => {
-      expect(normalizeFinishReason(null)).toBe('unknown');
+    it('should return "other" for null', () => {
+      expect(normalizeFinishReason(null)).toBe('other');
     });
 
-    it('should return "unknown" for number', () => {
-      expect(normalizeFinishReason(42)).toBe('unknown');
+    it('should return "other" for number', () => {
+      expect(normalizeFinishReason(42)).toBe('other');
     });
 
-    it('should return "unknown" for boolean', () => {
-      expect(normalizeFinishReason(true)).toBe('unknown');
+    it('should return "other" for boolean', () => {
+      expect(normalizeFinishReason(true)).toBe('other');
     });
 
-    it('should return "unknown" for array', () => {
-      expect(normalizeFinishReason(['stop'])).toBe('unknown');
+    it('should return "other" for array', () => {
+      expect(normalizeFinishReason(['stop'])).toBe('other');
     });
 
     it('should handle empty string', () => {