get-convex · zboyles · Dec 24, 2025 · Dec 24, 2025 · Jan 15, 2026 · Jan 15, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.6.0
+
+**Note on versioning:** This release jumps from 0.3.2 to 0.6.0, skipping versions 0.4.0 and 0.5.0. This is intentional and aligns the `@convex-dev/agent` package version with the AI SDK v6 major version for clearer compatibility signaling. Going forward, the minor version of this package will track the AI SDK major version to make it easier for developers to identify which version of the AI SDK is supported.
+
+- Breaking: Requires AI SDK v6 and drops support for AI SDK v5. Projects pinned
+  to v5 must upgrade their AI SDK dependencies before updating to this
+  version.
+- Aligns this package's message and tool invocation types with the AI SDK v6
+  APIs to reduce casting/adapter code when integrating with the core SDK.
+- Updates internal helpers to use the AI SDK v6 request/response shapes and
+  error handling semantics.
+- Migration from 0.3.x:
+  - Update your AI SDK dependency to v6 in `package.json` and reinstall
+    dependencies.
+  - Rebuild and run your type checker to surface any call sites that depend on
+    the old AI SDK v5 types or message shapes.
+  - Review any custom integrations that relied on deprecated v5-only helpers
+    and update them to the new AI SDK v6-compatible APIs.
+  - See Vercel's [v6 migration guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0) for details on AI SDK changes.
+
 ## 0.3.2
 
 - Fix deleteByOrder spanning many messages
@@ -306,8 +326,7 @@ data at rest is backwards compatible.
 - Adds a `rawRequestResponseHandler` argument to the Agent that is a good spot
   to log or save all raw request/responses if you're trying to debug model
   behavior, headers, etc.
-- Centralizes the example model usage so you can swap openai for openrouter /
-  grok in one place.
+- Centralizes the example model usage so you can swap models in one place.
 - StorageOptions now takes a better argument name
   `saveMessages?: "all" | "none" | "promptAndOutput";`, deprecating
   `save{All,Any}InputMessages` and `saveOutputMessages`.

diff --git a/TYPE_FIX_SUMMARY.md b/TYPE_FIX_SUMMARY.md
@@ -0,0 +1,63 @@
+# AI SDK v6 Type Error Fix Summary
+
+## Problem
+The build fails with TypeScript errors after upgrading to AI SDK v6. The main issues are:
+1. `ToolCallPart` type now requires `input` field (not optional), but stored data may only have deprecated `args` field
+2. Tool-result output types missing newer types like `execution-denied` and extended content types
+3. Generated component types out of sync with updated validators
+
+## Changes Made
+
+### 1. Fixed `tool-call` Part Handling (src/mapping.ts)
+- Updated `toModelMessageContent()` to ensure `input` is always present by falling back to `args` or `{}`
+- Updated `serializeContent()` and `fromModelMessageContent()` to handle both `input` and legacy `args` fields
+- This fixes the core issue where AI SDK v6's `ToolCallPart` expects non-nullable `input`
+
+### 2. Fixed Tool Approval Response Handling (src/client/search.ts)
+- Updated `filterOutOrphanedToolMessages()` to handle tool-approval-response parts that don't have `toolCallId`
+- Tool-approval-response only has `approvalId`, not `toolCallId`
+
+### 3. Updated Generated Component Types (src/component/_generated/component.ts)
+Made manual updates to sync with validators (normally done via `convex codegen`):
+- Added `input: any` field to all tool-call type definitions
+- Made `args` optional (`args?: any`) in tool-call types  
+- Added `execution-denied` output type to tool-result
+- Added extended content types: `file-data`, `file-url`, `file-id`, `image-data`, `image-url`, `image-file-id`, `custom`
+- Added `providerOptions` to text types in content values
+
+## Remaining Issues (5 TypeScript errors)
+
+The remaining errors are due to a structural mismatch in the generated component types:
+- Generated types have BOTH `experimental_content` (deprecated) and `output` (new) fields on tool-result
+- Our validators only define `output`, not `experimental_content`
+- TypeScript is comparing our new output types against the old experimental_content types
+- This cannot be fixed manually - requires proper component regeneration
+
+### To Complete the Fix:
+1. Run `convex codegen --component-dir ./src/component` with a valid Convex deployment
+2. This will regenerate `src/component/_generated/component.ts` from the validators
+3. The regenerated types will:
+   - Remove the deprecated `experimental_content` field
+   - Use only the `output` field with correct types
+   - Properly match the validator definitions
+
+### Error Locations:
+- `src/client/index.ts:1052` - addMessages call
+- `src/client/index.ts:1103` - addMessages call  
+- `src/client/index.ts:1169` - updateMessage call
+- `src/client/messages.ts:141` - addMessages call
+- `src/client/start.ts:265` - addMessages call
+
+All errors have the same root cause: content value types in tool-result output don't match experimental_content expectations.
+
+## Testing Plan
+Once component types are regenerated:
+1. Run `npm run build` - should complete without errors
+2. Run `npm test` - ensure no regressions
+3. Test with actual AI SDK v6 workflow - verify tool-call handling works with both new `input` and legacy `args` fields
+
+## Notes
+- The mapping functions in `src/mapping.ts` correctly handle both old and new formats
+- Data with only `args` will be converted to have `input` (with `args` as fallback)
+- Data with `input` will work directly
+- This provides backward compatibility while supporting AI SDK v6's requirements
diff --git a/docs/agent-usage.mdx b/docs/agent-usage.mdx
@@ -43,7 +43,7 @@ requiring the LLM to always pass through full context to each tool call. It also
 allows dynamically choosing a model or other options for the Agent.
 
 ```ts
-import { Agent } from "@convex-dev/agent";
+import { Agent, stepCountIs } from "@convex-dev/agent";
 import { type LanguageModel } from "ai";
 import type { ActionCtx } from "./_generated/server";
 import type { Id } from "./_generated/dataModel";
@@ -63,7 +63,7 @@ function createAuthorAgent(
       researchCharacter: researchCharacterTool(ctx, bookId),
       writeChapter: writeChapterTool(ctx, bookId),
     },
-    maxSteps: 10, // Alternative to stopWhen: stepCountIs(10)
+    stopWhen: stepCountIs(10),
   });
 }
 ```
@@ -249,7 +249,7 @@ const supportAgent = new Agent(components.agent, {
       },
     }),
     // Standard AI SDK tool
-    myTool: tool({ description, parameters, execute: () => {}}),
+    myTool: tool({ description, inputSchema: parameters, execute: () => {}}),
   },
   // Used for limiting the number of steps when tool calls are involved.
   // NOTE: if you want tool calls to happen automatically with a single call,

diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
@@ -40,15 +40,15 @@ successfully run once before you start defining Agents.
 
 ```ts
 import { components } from "./_generated/api";
-import { Agent } from "@convex-dev/agent";
+import { Agent, stepCountIs } from "@convex-dev/agent";
 import { openai } from "@ai-sdk/openai";
 
 const agent = new Agent(components.agent, {
   name: "My Agent",
   languageModel: openai.chat("gpt-4o-mini"),
   instructions: "You are a weather forecaster.",
   tools: { getWeather, getGeocoding },
-  maxSteps: 3,
+  stopWhen: stepCountIs(3),
 });
 ```
 

diff --git a/docs/tools.mdx b/docs/tools.mdx
@@ -66,7 +66,7 @@ export const ideaSearch = createTool({
 async function createTool(ctx: ActionCtx, teamId: Id<"teams">) {
   const myTool = tool({
     description: "My tool",
-    parameters: z.object({...}).describe("The arguments for the tool"),
+    inputSchema: z.object({...}).describe("The arguments for the tool"),
     execute: async (args, options): Promise<BarReturnType> => {
       return await ctx.runQuery(internal.foo.bar, args);
     },

diff --git a/example/convex/modelsForDemo.ts b/example/convex/modelsForDemo.ts
@@ -1,29 +1,26 @@
-import { openrouter } from "@openrouter/ai-sdk-provider";
 import { type EmbeddingModel } from "ai";
-import type { LanguageModelV2 } from "@ai-sdk/provider";
+import type { LanguageModelV3 } from "@ai-sdk/provider";
 import { anthropic } from "@ai-sdk/anthropic";
 import { openai } from "@ai-sdk/openai";
 import { groq } from "@ai-sdk/groq";
 import { mockModel } from "@convex-dev/agent";
 
-let languageModel: LanguageModelV2;
-let textEmbeddingModel: EmbeddingModel<string>;
+let languageModel: LanguageModelV3;
+let textEmbeddingModel: EmbeddingModel;
 
 if (process.env.ANTHROPIC_API_KEY) {
   languageModel = anthropic.chat("claude-opus-4-20250514");
 } else if (process.env.OPENAI_API_KEY) {
   languageModel = openai.chat("gpt-4o-mini");
-  textEmbeddingModel = openai.textEmbeddingModel("text-embedding-3-small");
+  textEmbeddingModel = openai.embedding("text-embedding-3-small");
 } else if (process.env.GROQ_API_KEY) {
   languageModel = groq.languageModel(
     "meta-llama/llama-4-scout-17b-16e-instruct",
   );
-} else if (process.env.OPENROUTER_API_KEY) {
-  languageModel = openrouter.chat("openai/gpt-4o-mini") as LanguageModelV2;
 } else {
   languageModel = mockModel({});
   console.warn(
-    "Run `npx convex env set GROQ_API_KEY=<your-api-key>` or `npx convex env set OPENAI_API_KEY=<your-api-key>` or `npx convex env set OPENROUTER_API_KEY=<your-api-key>` from the example directory to set the API key.",
+    "Run `npx convex env set GROQ_API_KEY=<your-api-key>` or `npx convex env set OPENAI_API_KEY=<your-api-key>` from the example directory to set the API key.",
   );
 }
 

diff --git a/example/convex/threads.ts b/example/convex/threads.ts
@@ -73,7 +73,6 @@ export const updateThreadTitle = action({
       object: { title, summary },
     } = await thread.generateObject(
       {
-        mode: "json",
         schemaDescription:
           "Generate a title and summary for the thread. The title should be a single sentence that captures the main topic of the thread. The summary should be a short description of the thread that could be used to describe it to someone who hasn't read it.",
         schema: z.object({

diff --git a/example/tsconfig.json b/example/tsconfig.json
@@ -11,7 +11,7 @@
     "strict": true,
     "forceConsistentCasingInFileNames": true,
     "module": "ESNext",
-    "moduleResolution": "Bundler",
+    "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
     "jsx": "react-jsx",