get-convex · sethconvex · Jan 25, 2026 · Jan 25, 2026 · Jan 26, 2026 · Jan 26, 2026
diff --git a/.cursor/rules/convex_rules.mdc b/.cursor/rules/convex_rules.mdc
@@ -159,7 +159,7 @@ export const listWithExtraArg = query({
     handler: async (ctx, args) => {
         return await ctx.db
         .query("messages")
-        .filter((q) => q.eq(q.field("author"), args.author))
+        .withIndex("by_author", (q) => q.eq("author", args.author))
         .order("desc")
         .paginate(args.paginationOpts);
     },
@@ -180,7 +180,7 @@ Note: `paginationOpts` is an object with the following properties:
 
 ## Schema guidelines
 - Always define your schema in `convex/schema.ts`.
-- Always import the schema definition functions from `convex/server`:
+- Always import the schema definition functions from `convex/server`.
 - System fields are automatically added to all documents and are prefixed with an underscore. The two system fields that are automatically added to all documents are `_creationTime` which has the validator `v.number()` and `_id` which has the validator `v.id(tableName)`.
 - Always include all index fields in the index name. For example, if an index is defined as `["field1", "field2"]`, the index name should be "by_field1_and_field2".
 - Index fields must be queried in the same order they are defined. If you want to be able to query by "field1" then "field2" and by "field2" then "field1", you must create separate indexes.
@@ -198,7 +198,7 @@ export const exampleQuery = query({
     handler: async (ctx, args) => {
         const idToUsername: Record<Id<"users">, string> = {};
         for (const userId of args.userIds) {
-            const user = await ctx.db.get(userId);
+            const user = await ctx.db.get("users", userId);
             if (user) {
                 idToUsername[user._id] = user.username;
             }
@@ -236,8 +236,8 @@ const messages = await ctx.db
 
 
 ## Mutation guidelines
-- Use `ctx.db.replace` to fully replace an existing document. This method will throw an error if the document does not exist.
-- Use `ctx.db.patch` to shallow merge updates into an existing document. This method will throw an error if the document does not exist.
+- Use `ctx.db.replace` to fully replace an existing document. This method will throw an error if the document does not exist. Syntax: `await ctx.db.replace('tasks', taskId, { name: 'Buy milk', completed: false })`
+- Use `ctx.db.patch` to shallow merge updates into an existing document. This method will throw an error if the document does not exist. Syntax: `await ctx.db.patch('tasks', taskId, { completed: true })`
 
 ## Action guidelines
 - Always add `"use node";` to the top of files containing actions that use Node.js built-in modules.
@@ -307,7 +307,7 @@ export const exampleQuery = query({
     args: { fileId: v.id("_storage") },
     returns: v.null(),
     handler: async (ctx, args) => {
-        const metadata: FileMetadata | null = await ctx.db.system.get(args.fileId);
+        const metadata: FileMetadata | null = await ctx.db.system.get("_storage", args.fileId);
         console.log(metadata);
         return null;
     },
@@ -434,7 +434,7 @@ Internal Functions:
   "description": "This example shows how to build a chat app without authentication.",
   "version": "1.0.0",
   "dependencies": {
-    "convex": "^1.17.4",
+    "convex": "^1.31.2",
     "openai": "^4.79.0"
   },
   "devDependencies": {
@@ -667,6 +667,35 @@ export default defineSchema({
 });
 ```
 
+#### convex/tsconfig.json
+```typescript
+{
+  /* This TypeScript project config describes the environment that
+   * Convex functions run in and is used to typecheck them.
+   * You can modify it, but some settings required to use Convex.
+   */
+  "compilerOptions": {
+    /* These settings are not required by Convex and can be modified. */
+    "allowJs": true,
+    "strict": true,
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+
+    /* These compiler options are required by Convex */
+    "target": "ESNext",
+    "lib": ["ES2021", "dom"],
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["./**/*"],
+  "exclude": ["./_generated"]
+}
+```
+
 #### src/App.tsx
 ```typescript
 export default function App() {

diff --git a/CLAUDE.md b/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
diff --git a/MIGRATION.md b/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)

diff --git a/example/convex/_generated/api.d.ts b/example/convex/_generated/api.d.ts
@@ -8,11 +8,13 @@
  * @module
  */
 
+import type * as agents_approval from "../agents/approval.js";
 import type * as agents_config from "../agents/config.js";
 import type * as agents_fashion from "../agents/fashion.js";
 import type * as agents_simple from "../agents/simple.js";
 import type * as agents_story from "../agents/story.js";
 import type * as agents_weather from "../agents/weather.js";
+import type * as chat_approval from "../chat/approval.js";
 import type * as chat_basic from "../chat/basic.js";
 import type * as chat_human from "../chat/human.js";
 import type * as chat_streamAbort from "../chat/streamAbort.js";
@@ -55,11 +57,13 @@ import type {
 } from "convex/server";
 
 declare const fullApi: ApiFromModules<{
+  "agents/approval": typeof agents_approval;
   "agents/config": typeof agents_config;
   "agents/fashion": typeof agents_fashion;
   "agents/simple": typeof agents_simple;
   "agents/story": typeof agents_story;
   "agents/weather": typeof agents_weather;
+  "chat/approval": typeof chat_approval;
   "chat/basic": typeof chat_basic;
   "chat/human": typeof chat_human;
   "chat/streamAbort": typeof chat_streamAbort;

diff --git a/example/convex/_generated/dataModel.d.ts b/example/convex/_generated/dataModel.d.ts
@@ -38,7 +38,7 @@ export type Doc<TableName extends TableNames> = DocumentByName<
  * Convex documents are uniquely identified by their `Id`, which is accessible
  * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
  *
- * Documents can be loaded using `db.get(id)` in query and mutation functions.
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
  *
  * IDs are just strings at runtime, but this type can be used to distinguish them from other
  * strings when type checking.