Add compile-time errors for AI SDK v5 patterns and docs

CLAUDE.md

@@ -59,6 +59,7 @@ npm run typecheck    # Full TypeScript validation including example/convex
 - **Message-centric design** - All operations revolve around message persistence/retrieval
 - **Component-based encapsulation** - Uses Convex Components pattern
 - **Multi-user support** - Threads have optional `userId` for ownership
+- **Tool approval flow** - Tools can require human approval via `needsApproval`, with `agent.approveToolCall()` and `agent.denyToolCall()` methods
 
 ### Database Tables (Convex Component)
 
@@ -87,82 +88,138 @@ Follow the rules in `.cursor/rules/convex_rules.mdc`:
 - `@convex-dev/agent/validators` - Convex validators for integration
 - `@convex-dev/agent/test` - Testing utilities
 
-## Upgrading to v0.6.0 (AI SDK v6)
+## AI Guidance: Helping Users Upgrade to v0.6.0
 
-When helping users upgrade from @convex-dev/agent v0.3.x to v0.6.0, follow these steps:
+**IMPORTANT: v0.6.0 requires AI SDK v6 (ai@^6.0.0)**
 
-### Step 1: Update dependencies in package.json
+When helping users upgrade from @convex-dev/agent v0.3.x (AI SDK v5) to v0.6.0 (AI SDK v6):
+
+### Step 1: Update Dependencies First
+
+Update all AI SDK packages together to avoid peer dependency conflicts:
 
 ```bash
 npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/provider-utils@^4.0.6
+npm install @ai-sdk/openai@^3.0.10  # or whichever provider
 ```
 
-Also update any AI SDK provider packages:
-```bash
-npm install @ai-sdk/openai@^3.0.10 @ai-sdk/anthropic@^3.0.13
-```
+**Compatible sibling packages:**
+- `@convex-dev/rag@^0.7.0` (v0.6.0 has type conflicts with AI SDK v6)
+- `@convex-dev/workflow@^0.3.2`
+
+### Step 2: Detect v5 Patterns
 
-### Step 2: Update tool definitions
+Search for these patterns indicating v5 usage:
+- `createTool({ args:` - should be `inputSchema`
+- `createTool({ handler:` - should be `execute`
+- `textEmbeddingModel:` - should be `embeddingModel`
+- `maxSteps:` in generateText/streamText - should be `stopWhen: stepCountIs(N)`
+- `mode: "json"` in generateObject - removed in v6
+- `@ai-sdk/*` packages at v1.x or v2.x - should be v3.x
+- Type imports: `LanguageModelV2` → `LanguageModelV3`, `EmbeddingModel<string>` → `EmbeddingModelV3`
 
-Replace `parameters` with `inputSchema`:
+### Step 3: Apply Transformations
 
+**Tool definitions:**
 ```typescript
-// Before (v5)
+// BEFORE (v5)
 const myTool = createTool({
   description: "...",
   parameters: z.object({ query: z.string() }),
-  execute: async (ctx, args) => { ... }
+  handler: async (ctx, args) => {
+    return args.query.toUpperCase();
+  }
 })
 
-// After (v6)
+// AFTER (v6)
 const myTool = createTool({
   description: "...",
   inputSchema: z.object({ query: z.string() }),
-  execute: async (ctx, input, options) => { ... }
+  execute: async (ctx, input, options) => {
+    return input.query.toUpperCase();
+  }
 })
 ```
 
-### Step 3: Update maxSteps usage (if applicable)
+**Agent embedding config:**
+```typescript
+// BEFORE
+new Agent(components.agent, {
+  textEmbeddingModel: openai.embedding("text-embedding-3-small")
+})
+
+// AFTER
+new Agent(components.agent, {
+  embeddingModel: openai.embedding("text-embedding-3-small")
+})
+```
 
+**Step limits:**
 ```typescript
-// Before (v5)
+// BEFORE
 await agent.generateText(ctx, { threadId }, {
   prompt: "...",
   maxSteps: 5
 })
 
-// After (v6) - maxSteps still works but stopWhen is preferred
-import { stepCountIs } from "ai"
+// AFTER
+import { stepCountIs } from "@convex-dev/agent"
 await agent.generateText(ctx, { threadId }, {
   prompt: "...",
   stopWhen: stepCountIs(5)
 })
 ```
 
-### Step 4: Update embedding model config (optional)
+**Type imports:**
+```typescript
+// BEFORE (v5)
+import type { LanguageModelV2 } from "@ai-sdk/provider";
+import type { EmbeddingModel } from "ai";
+let model: LanguageModelV2;
+let embedder: EmbeddingModel<string>;
+
+// AFTER (v6)
+import type { LanguageModelV3, EmbeddingModelV3 } from "@ai-sdk/provider";
+let model: LanguageModelV3;
+let embedder: EmbeddingModelV3;
+```
 
+**generateObject (remove mode: "json"):**
 ```typescript
-// Before
-new Agent(components.agent, {
-  textEmbeddingModel: openai.embedding("text-embedding-3-small")
+// BEFORE (v5)
+await generateObject({
+  model,
+  mode: "json",
+  schema: z.object({ ... }),
+  prompt: "..."
 })
 
-// After (textEmbeddingModel still works but embeddingModel is preferred)
-new Agent(components.agent, {
-  embeddingModel: openai.embedding("text-embedding-3-small")
+// AFTER (v6) - mode: "json" removed, just use schema
+await generateObject({
+  model,
+  schema: z.object({ ... }),
+  prompt: "..."
 })
 ```
 
-### Step 5: Verify the upgrade
+### Step 4: Verify
 
 ```bash
 npm run typecheck
-npm run lint
 npm test
 ```
 
-### Common issues
+### Common Issues
+
+- **EmbeddingModelV2 vs V3 errors**: Ensure all `@ai-sdk/*` packages are v3.x
+- **Tool `args` vs `input`**: v6 uses `input` in execute signature (2nd param)
+- **`mimeType` vs `mediaType`**: v6 prefers `mediaType` (backwards compat maintained)
+- **Type import errors**: `LanguageModelV2` is now `LanguageModelV3`, `EmbeddingModel<string>` is now `EmbeddingModelV3` (no longer generic)
+- **generateObject mode errors**: `mode: "json"` was removed in v6 - just remove the mode option
+
+### New v6 Features to Mention
 
-- **EmbeddingModelV2 vs V3 errors**: Ensure all @ai-sdk/* packages are updated to v3.x
-- **Tool input/args**: v6 uses `input` instead of `args` in tool calls (backwards compat maintained)
-- **mimeType vs mediaType**: v6 uses `mediaType` (backwards compat maintained)
+After upgrade, users can now use:
+- **Tool approval**: `needsApproval` in createTool, `agent.approveToolCall()`, `agent.denyToolCall()`
+- **Reasoning streaming**: Works with models like Groq that support reasoning
+- **Detailed token usage**: `inputTokenDetails`, `outputTokenDetails` in usage tracking

MIGRATION.md

@@ -4,10 +4,14 @@ This guide helps you upgrade from @convex-dev/agent v0.3.x to v0.6.0.
 
 ## Step 1: Update dependencies
 
+Update all AI SDK packages **together** to avoid peer dependency conflicts:
+
 ```bash
 npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/provider-utils@^4.0.6
 ```
 
+### Official AI SDK providers
+
 Update your AI SDK provider packages to v3.x:
 ```bash
 # For OpenAI
@@ -18,8 +22,38 @@ npm install @ai-sdk/anthropic@^3.0.13
 
 # For Groq
 npm install @ai-sdk/groq@^3.0.8
+
+# For Google (Gemini)
+npm install @ai-sdk/google@^3.0.8
+```
+
+### Third-party providers
+
+Third-party providers also need updates to be compatible with AI SDK v6:
+
+```bash
+# For OpenRouter
+npm install @openrouter/ai-sdk-provider@^2.0.0
+
+# For other providers, check their documentation for AI SDK v6 compatibility
+```
+
+### Handling dependency conflicts
+
+If you see peer dependency warnings or errors, try updating all packages at once:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/openai@^3.0.10 @openrouter/ai-sdk-provider@^2.0.0
 ```
 
+If you still have conflicts, you can use `--force` as a last resort:
+
+```bash
+npm install @convex-dev/agent@^0.6.0 --force
+```
+
+> **Note**: Using `--force` can lead to inconsistent dependency trees. After using it, verify your app works correctly and consider running `npm dedupe` to clean up.
+
 ## Step 2: Update tool definitions
 
 Replace `parameters` with `inputSchema`:
@@ -89,6 +123,30 @@ AI SDK v6 renamed `args` to `input` in tool calls. The library maintains backwar
 ### `mimeType` vs `mediaType`
 AI SDK v6 renamed `mimeType` to `mediaType`. Backwards compatibility is maintained.
 
+### Peer dependency conflicts
+
+If you see errors like:
+```
+npm error ERESOLVE unable to resolve dependency tree
+npm error peer ai@"^5.0.0" from @openrouter/ai-sdk-provider@1.0.3
+```
+
+This means a third-party provider needs updating. Common solutions:
+
+1. **Update the provider** to a version compatible with AI SDK v6
+2. **Check npm** for the latest version: `npm view @openrouter/ai-sdk-provider versions`
+3. **Use `--force`** if a compatible version isn't available yet (temporary workaround)
+
+### Third-party provider compatibility
+
+| Provider | AI SDK v5 (ai@5.x) | AI SDK v6 (ai@6.x) |
+|----------|-------------------|-------------------|
+| @openrouter/ai-sdk-provider | v1.x | v2.x |
+| @ai-sdk/openai | v1.x-v2.x | v3.x |
+| @ai-sdk/anthropic | v1.x-v2.x | v3.x |
+| @ai-sdk/groq | v1.x-v2.x | v3.x |
+| @ai-sdk/google | v1.x-v2.x | v3.x |
+
 ## More Information
 
 - [AI SDK v6 Migration Guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0)

package.json

@@ -41,7 +41,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "MIGRATION.md"
   ],
   "exports": {
     "./package.json": "./package.json",