AI SDK v6 Support

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`.

CLAUDE.md

@@ -0,0 +1,168 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+@convex-dev/agent is a TypeScript/NPM package that provides an AI Agent component for Convex. It enables building agentic AI applications with thread/message management, LLM integration via AI SDK, WebSocket streaming, tool calling, vector embeddings, and RAG.
+
+Documentation: [Convex Agent Docs](https://docs.convex.dev/agents)
+
+## Commands
+
+### Development
+```bash
+npm run dev          # Run backend + frontend + build watch concurrently
+npm run build        # TypeScript build (tsc --project ./tsconfig.build.json)
+```
+
+### Testing
+```bash
+npm test             # Run tests with typecheck (vitest run --typecheck)
+npm run test:watch   # Watch mode (vitest --typecheck)
+```
+
+### Code Quality
+```bash
+npm run lint         # ESLint
+npm run typecheck    # Full TypeScript validation including example/convex
+```
+
+## Architecture
+
+### Source Structure (`/src`)
+
+**Three-Layer Architecture:**
+1. **Client** (`src/client/`) - Public API for consuming applications
+   - `index.ts` - Main `Agent` class and exports
+   - `start.ts` - `startGeneration()` core generation logic
+   - `streaming.ts`, `search.ts`, `messages.ts`, `threads.ts` - Feature modules
+
+2. **Component** (`src/component/`) - Convex backend (runs on Convex servers)
+   - `schema.ts` - Database schema (threads, messages, streamingMessages, streamDeltas, memories, files)
+   - `index.ts` - Main component implementation
+   - Backend operations for messages, threads, streaming, vector search
+
+3. **React** (`src/react/`) - React hooks for UI integration
+   - `useThreadMessages.ts` - Paginated + streaming messages
+   - `useUIMessages.ts` - UIMessage-first hook with metadata
+   - `useSmoothText.ts` - Animated text rendering
+
+**Shared Files:**
+- `validators.ts` - Convex validators (vMessage, vMessageDoc, vThreadDoc, etc.)
+- `UIMessages.ts` - UIMessage types and conversion utilities
+- `mapping.ts` - Message serialization between ModelMessage and stored formats
+
+### Key Patterns
+
+- **Streaming via WebSocket deltas** - Not HTTP streaming. Delta compression with heartbeats.
+- **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
+
+### Database Tables (Convex Component)
+
+- **threads** - Conversations with userId, title, summary, status
+- **messages** - Chat messages with order, stepOrder, status, metadata
+- **streamingMessages** - Real-time streaming state (streaming/finished/aborted)
+- **streamDeltas** - Stream chunks with start/end ranges
+- **memories** - User/thread memories for RAG with embedding references
+
+## Convex-Specific Guidelines
+
+Follow the rules in `.cursor/rules/convex_rules.mdc`:
+
+- **Function syntax**: Always use new syntax with `args` and `returns` validators
+- **Validators**: Use `v.null()` for null returns, `v.int64()` instead of deprecated `v.bigint()`
+- **Indexes**: Include all fields in index name (e.g., `by_threadId_and_status`)
+- **Queries**: Use `withIndex` instead of `filter`; define indexes in schema
+- **Internal functions**: Use `internalQuery`/`internalMutation`/`internalAction` for private functions
+- **Actions**: Add `"use node";` for Node.js modules; actions cannot use `ctx.db`
+- **Type safety**: Use `Id<'tableName'>` for document IDs, strict TypeScript
+
+## Export Surfaces
+
+- `@convex-dev/agent` - Main exports (Agent class, types, validators, tools)
+- `@convex-dev/agent/react` - React hooks (useThreadMessages, useUIMessages, etc.)
+- `@convex-dev/agent/validators` - Convex validators for integration
+- `@convex-dev/agent/test` - Testing utilities
+
+## Upgrading to v0.6.0 (AI SDK v6)
+
+When helping users upgrade from @convex-dev/agent v0.3.x to v0.6.0, follow these steps:
+
+### Step 1: Update dependencies in package.json
+
+```bash
+npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/provider-utils@^4.0.6
+```
+
+Also update any AI SDK provider packages:
+```bash
+npm install @ai-sdk/openai@^3.0.10 @ai-sdk/anthropic@^3.0.13
+```
+
+### Step 2: Update tool definitions
+
+Replace `parameters` with `inputSchema`:
+
+```typescript
+// Before (v5)
+const myTool = createTool({
+  description: "...",
+  parameters: z.object({ query: z.string() }),
+  execute: async (ctx, args) => { ... }
+})
+
+// After (v6)
+const myTool = createTool({
+  description: "...",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async (ctx, input, options) => { ... }
+})
+```
+
+### Step 3: Update maxSteps usage (if applicable)
+
+```typescript
+// Before (v5)
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  maxSteps: 5
+})
+
+// After (v6) - maxSteps still works but stopWhen is preferred
+import { stepCountIs } from "ai"
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  stopWhen: stepCountIs(5)
+})
+```
+
+### Step 4: Update embedding model config (optional)
+
+```typescript
+// Before
+new Agent(components.agent, {
+  textEmbeddingModel: openai.embedding("text-embedding-3-small")
+})
+
+// After (textEmbeddingModel still works but embeddingModel is preferred)
+new Agent(components.agent, {
+  embeddingModel: openai.embedding("text-embedding-3-small")
+})
+```
+
+### Step 5: Verify the upgrade
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+```
+
+### Common issues
+
+- **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)

MIGRATION.md

@@ -0,0 +1,95 @@
+# Migration Guide: v0.3.x to v0.6.0 (AI SDK v6)
+
+This guide helps you upgrade from @convex-dev/agent v0.3.x to v0.6.0.
+
+## Step 1: Update dependencies
+
+```bash
+npm install @convex-dev/agent@^0.6.0 ai@^6.0.35 @ai-sdk/provider-utils@^4.0.6
+```
+
+Update your AI SDK provider packages to v3.x:
+```bash
+# For OpenAI
+npm install @ai-sdk/openai@^3.0.10
+
+# For Anthropic
+npm install @ai-sdk/anthropic@^3.0.13
+
+# For Groq
+npm install @ai-sdk/groq@^3.0.8
+```
+
+## Step 2: Update tool definitions
+
+Replace `parameters` with `inputSchema`:
+
+```typescript
+// Before (v5)
+const myTool = createTool({
+  description: "My tool",
+  parameters: z.object({ query: z.string() }),
+  execute: async (ctx, args) => { ... }
+})
+
+// After (v6)
+const myTool = createTool({
+  description: "My tool",
+  inputSchema: z.object({ query: z.string() }),
+  execute: async (ctx, input, options) => { ... }
+})
+```
+
+## Step 3: Update Agent config (if using embeddings)
+
+```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 4: Update maxSteps (optional)
+
+```typescript
+// Before
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  maxSteps: 5
+})
+
+// After (maxSteps still works, but stopWhen is preferred)
+import { stepCountIs } from "ai"
+await agent.generateText(ctx, { threadId }, {
+  prompt: "...",
+  stopWhen: stepCountIs(5)
+})
+```
+
+## Step 5: Verify
+
+```bash
+npm run typecheck
+npm test
+```
+
+## Common Issues
+
+### EmbeddingModelV2 vs EmbeddingModelV3 type errors
+Ensure all `@ai-sdk/*` packages are updated to v3.x. Older versions use AI SDK v5 types.
+
+### Tool `args` vs `input`
+AI SDK v6 renamed `args` to `input` in tool calls. The library maintains backwards compatibility, but you may see this in types.
+
+### `mimeType` vs `mediaType`
+AI SDK v6 renamed `mimeType` to `mediaType`. Backwards compatibility is maintained.
+
+## More Information
+
+- [AI SDK v6 Migration Guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0)
+- [Convex Agent Documentation](https://docs.convex.dev/agents)

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