ai-pro-sdk 2.0.1

package/docs/ai-sdk-v4/README.md

@@ -0,0 +1,7 @@
+# AI SDK v4 Documentation (Historical)
+
+> **Historical:** These documents cover legacy provider versions 0.x (AI SDK v4, `@anthropic-ai/claude-code`). For current documentation, see the [main README](../../README.md).
+
+- [GUIDE.md](GUIDE.md) - Usage guide
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions
+- [DEVELOPMENT-STATUS.md](DEVELOPMENT-STATUS.md) - Development status

package/docs/ai-sdk-v4/TROUBLESHOOTING.md

@@ -0,0 +1,249 @@
+# Troubleshooting Guide
+
+This guide documents common issues and solutions for the Claude Code AI SDK Provider.
+
+## Common Issues
+
+### 1. Authentication Errors
+
+**Problem**: Getting authentication errors when trying to use the provider.
+
+**Solution**:
+
+```bash
+# Install Claude Code SDK globally
+npm install -g @anthropic-ai/claude-code
+
+# Authenticate with your Claude account
+claude login
+```
+
+**Verification**:
+
+```bash
+# Check if authenticated
+npx tsx ../examples/check-cli.ts
+```
+
+### 2. SDK Not Found
+
+**Problem**: Error about `@anthropic-ai/claude-code` module not found.
+
+**Solution**: The SDK is a dependency of this provider and should be installed automatically. If not:
+
+```bash
+npm install @anthropic-ai/claude-code
+```
+
+### 3. Handling Long-Running Tasks
+
+**Problem**: Complex queries with Claude Opus 4 may take longer due to extended thinking mode.
+
+**Solution**: Use AbortSignal with custom timeouts:
+
+```typescript
+import { generateText } from 'ai';
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+
+// Create a custom timeout (5 minutes for complex tasks)
+const controller = new AbortController();
+const timeoutId = setTimeout(() => {
+  controller.abort(new Error('Request timeout'));
+}, 300000);
+
+try {
+  const { text } = await generateText({
+    model: claudeCode('opus'),
+    prompt: 'Complex reasoning task...',
+    abortSignal: controller.signal,
+  });
+  clearTimeout(timeoutId);
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('Request timed out');
+  }
+}
+```
+
+**Guidelines**:
+
+- Simple queries: Default timeout is sufficient
+- Complex reasoning: 5-10 minutes may be needed
+- Very long tasks: Consider breaking into smaller chunks
+
+### 4. Object Generation Issues
+
+**Problem**: Claude returns text instead of valid JSON when using `generateObject`.
+
+**Solutions**:
+
+1. **Simplify your schema** - Start with fewer fields
+2. **Clear prompts** - Be explicit: "Generate a user profile with name and age"
+3. **Use descriptions** - Add `.describe()` to schema fields
+4. **Retry logic** - Implement retries for production:
+
+```typescript
+async function generateWithRetry(schema, prompt, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await generateObject({
+        model: claudeCode('sonnet'),
+        schema,
+        prompt,
+      });
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, i)));
+    }
+  }
+}
+```
+
+### 5. Session Management
+
+**Problem**: Conversations don't maintain context.
+
+**Solution**: Use message history (recommended pattern):
+
+```typescript
+const messages = [
+  { role: 'user', content: 'My name is Alice' },
+  { role: 'assistant', content: 'Nice to meet you, Alice!' },
+  { role: 'user', content: 'What is my name?' },
+];
+
+const { text } = await generateText({
+  model: claudeCode('sonnet'),
+  messages, // Pass full conversation history
+});
+```
+
+**Note**: While the provider returns session IDs in metadata, the recommended approach is to use message history for conversation continuity.
+
+### 6. Error Handling
+
+**Problem**: Need to handle different types of errors appropriately.
+
+**Solution**: Use the provider's error utilities:
+
+```typescript
+import { isAuthenticationError, getErrorMetadata } from 'ai-sdk-provider-claude-code';
+
+try {
+  const { text } = await generateText({
+    model: claudeCode('sonnet'),
+    prompt: 'Hello',
+  });
+} catch (error) {
+  if (isAuthenticationError(error)) {
+    console.error('Please run: claude login');
+  } else if (error.name === 'AbortError') {
+    console.error('Request was cancelled or timed out');
+  } else {
+    // Get additional error details
+    const metadata = getErrorMetadata(error);
+    console.error('Error details:', metadata);
+  }
+}
+```
+
+## Debugging Tips
+
+### 1. Verify Setup
+
+```bash
+# Check Claude CLI version
+claude --version
+
+# Test authentication
+npx tsx ../examples/check-cli.ts
+
+# Run integration tests
+npx tsx ../examples/integration-test.ts
+```
+
+### 2. Enable Debug Logging
+
+```typescript
+// Log provider metadata to debug issues
+const { text, providerMetadata } = await generateText({
+  model: claudeCode('sonnet'),
+  prompt: 'Test',
+});
+
+console.log('Metadata:', providerMetadata);
+// Shows: sessionId, costUsd, durationMs, rawUsage
+```
+
+### 3. Test Specific Features
+
+```bash
+# Test streaming
+npx tsx ../examples/streaming.ts
+
+# Test object generation
+npx tsx ../examples/generate-object-basic.ts
+
+# Test conversations
+npx tsx ../examples/conversation-history.ts
+
+# Test long-running tasks
+npx tsx ../examples/long-running-tasks.ts
+```
+
+## Platform-Specific Issues
+
+### Windows
+
+- Ensure Claude CLI is in your PATH
+- Use PowerShell or Command Prompt (not WSL) for installation
+
+### macOS
+
+- May need to allow CLI in Security & Privacy settings
+- Use Homebrew or direct npm installation
+
+### Linux
+
+- Ensure Node.js ≥ 18 is installed
+- May need to use `sudo` for global npm installs
+
+## Performance Tips
+
+1. **Model Selection**
+   - Use `sonnet` for faster responses
+   - Use `opus` for complex reasoning tasks
+
+2. **Request Optimization**
+   - Keep prompts concise and clear
+   - Use streaming for better UX
+   - Implement proper error handling
+
+3. **Resource Management**
+   - The provider manages concurrent requests automatically
+   - Use AbortSignal for cancellable requests
+   - Clean up timeouts in finally blocks
+
+## Known Limitations
+
+1. **No Image Support**: The Claude Code SDK doesn't support image inputs
+2. **No AI SDK Tool Calling**: The AI SDK's function calling interface isn't implemented, but Claude can use tools via MCP servers and built-in CLI tools
+3. **Object Generation**: Relies on prompt engineering rather than native JSON mode
+4. **Model Options**: Limited to 'opus' and 'sonnet' models
+
+## Getting Help
+
+1. **Check Examples**: Review the `../examples` directory for working code
+2. **Integration Test**: Run `npx tsx ../examples/integration-test.ts` to verify setup
+3. **GitHub Issues**: Report bugs at https://github.com/ben-vargas/ai-sdk-provider-claude-code/issues
+4. **Documentation**: See the main README.md and GUIDE.md for detailed API documentation
+
+## Common Error Messages
+
+| Error                              | Cause                 | Solution                                       |
+| ---------------------------------- | --------------------- | ---------------------------------------------- |
+| "Claude Code executable not found" | CLI not installed     | Run `npm install -g @anthropic-ai/claude-code` |
+| "Authentication required"          | Not logged in         | Run `claude login`                             |
+| "No object generated"              | Invalid JSON response | Simplify schema, improve prompt                |
+| "Request timeout"                  | Task took too long    | Increase timeout with AbortSignal              |
+| "Session not found"                | Invalid session ID    | Use message history instead                    |

package/docs/ai-sdk-v5/DEVELOPMENT-STATUS.md

@@ -0,0 +1,309 @@
+# Community Provider Status Analysis (v5)
+
+## Overview
+
+This document analyzes the requirements for ai-sdk-provider-claude-code to achieve community provider status in the Vercel AI SDK v5 ecosystem.
+
+## Current Implementation Status
+
+### ✅ What We Have
+
+#### Core Functionality
+
+- **SDK Integration**: Uses official `@anthropic-ai/claude-agent-sdk` for all Claude interactions
+- **Text Generation**: Full support for both streaming and non-streaming text generation with v5 patterns
+- **Object Generation**: Reliable JSON generation through prompt engineering and extraction
+- **Multi-turn Conversations**: Proper message history support with v5 message format
+- **Provider Metadata**: Rich metadata including sessionId, costUsd, durationMs, and rawUsage
+- **Error Handling**: Comprehensive error handling with authentication detection
+- **AbortSignal Support**: Standard AI SDK pattern for timeouts and cancellation
+
+#### v5 Specific Features
+
+- **LanguageModelV2 Implementation**: Fully compliant with `specificationVersion: 'v2'`
+- **Stream-Start Event**: Properly emits initial stream event with warnings
+- **Token Usage Naming**: Uses v5 convention (inputTokens, outputTokens, totalTokens)
+- **Message Format**: Supports v5's array-based content structure
+- **Promise-based Streaming**: Implements v5's new streaming API pattern
+
+#### Build & Distribution
+
+- **TypeScript**: Full TypeScript support with proper type definitions
+- **Dual Formats**: Both CommonJS and ES Module builds via tsup
+- **Source Maps**: Generated for debugging support
+- **Package Structure**: Proper exports configuration for modern Node.js
+- **Beta Tag**: Published with `beta` tag on npm
+
+#### Testing
+
+- **Unit Tests**: Comprehensive test coverage with Vitest
+- **Integration Tests**: Full integration test suite
+- **Edge/Node Tests**: Separate configurations for different environments
+- **Examples**: Extensive example collection demonstrating all v5 features
+
+#### Documentation
+
+- **README**: Comprehensive documentation with version compatibility matrix
+- **CHANGELOG**: Proper version history following Keep a Changelog format
+- **Examples README**: Detailed guide for all example files
+- **API Documentation**: Clear documentation of all configuration options
+- **Migration Guide**: Comprehensive v4 to v5 migration documentation
+
+### 🚀 Meeting AI SDK v5 Standards
+
+Based on analysis of official v5 providers, we now meet all requirements:
+
+1. **Provider Pattern** ✅
+   - Factory function with provider instance
+   - Default export
+   - Proper settings interface
+   - Protection against `new` keyword misuse
+
+2. **Language Model Implementation** ✅
+   - `specificationVersion: 'v2'`
+   - Correct `doGenerate` and `doStream` methods for v5
+   - Proper provider metadata
+   - Object generation support
+   - Stream-start event emission
+
+3. **Build System** ✅
+   - tsup for dual format builds
+   - Source maps
+   - Proper package.json configuration
+   - Beta tag in publishConfig
+
+4. **Testing** ✅
+   - Separate edge/node configurations
+   - Unit and integration tests
+   - Example test coverage
+   - All tests passing with v5 patterns
+
+5. **Error Handling** ✅
+   - Standard AI SDK error classes
+   - Proper `isRetryable` flags
+   - AbortSignal support
+
+## 📁 Current Project Structure
+
+```
+ai-sdk-provider-claude-code/
+├── src/
+│   ├── index.ts                          # Main exports
+│   ├── claude-code-provider.ts           # Provider factory
+│   ├── claude-code-language-model.ts     # Language model implementation (v2)
+│   ├── convert-to-claude-code-messages.ts # Message formatting (v5 format)
+│   ├── extract-json.ts                   # JSON extraction (using jsonc-parser)
+│   ├── errors.ts                         # Error utilities
+│   ├── logger.ts                         # Logger abstraction
+│   ├── map-claude-code-finish-reason.ts  # Finish reason mapping
+│   ├── mcp-helpers.ts                    # Helper for SDK MCP servers
+│   ├── types.ts                          # TypeScript definitions
+│   └── validation.ts                     # Settings validation (Zod)
+├── docs/
+│   ├── ai-sdk-v4/                        # v4-specific documentation (archived)
+│   │   ├── DEVELOPMENT-STATUS.md
+│   │   ├── GUIDE.md
+│   │   └── TROUBLESHOOTING.md
+│   └── ai-sdk-v5/                        # v5 documentation
+│       ├── DEVELOPMENT-STATUS.md         # This document
+│       ├── GUIDE.md                      # v5-specific usage guide
+│       ├── TROUBLESHOOTING.md            # v5-specific troubleshooting
+│       ├── V5_BREAKING_CHANGES.md        # User migration guide
+│       ├── V5_MIGRATION_PLAN.md          # Technical migration plan
+│       ├── V5_MIGRATION_SUMMARY.md       # Migration implementation summary
+│       └── V5_MIGRATION_TASKS.md         # Migration task tracking
+├── examples/
+│   ├── README.md                         # Examples guide
+│   ├── abort-signal.ts                   # Cancellation
+│   ├── basic-usage.ts                    # Simple generation (v5 pattern)
+│   ├── bull.webp                         # Default test image for images.ts
+│   ├── check-cli.ts                      # Setup verification
+│   ├── conversation-history.ts           # Multi-turn conversations (v5 format)
+│   ├── custom-config.ts                  # Configuration options
+│   ├── generate-object-basic.ts          # Object generation (basic)
+│   ├── generate-object-constraints.ts    # Object generation (constraints)
+│   ├── generate-object-nested.ts         # Object generation (nested)
+│   ├── generate-object.ts                # Object generation (general)
+│   ├── hooks-callbacks.ts                # Hooks example (PreToolUse/PostToolUse)
+│   ├── images.ts                         # Image input with streaming mode
+│   ├── integration-test.ts               # Test suite
+│   ├── limitations.ts                    # Limitations walkthrough
+│   ├── long-running-tasks.ts             # Timeout handling
+│   ├── sdk-tools-callbacks.ts            # In-process SDK tools example
+│   ├── streaming.ts                      # Streaming demo (v5 pattern)
+│   ├── tool-management.ts                # Tool access control
+│   └── tool-streaming.ts                 # Tool streaming events demo
+├── vitest.config.ts                      # Test configuration
+├── tsup.config.ts                        # Build configuration
+├── package.json                          # Package metadata
+├── CHANGELOG.md                          # Version history
+├── README.md                             # Main documentation with version matrix
+└── LICENSE                               # MIT license
+```
+
+## 🎯 Ready for Community Status
+
+The provider now meets all requirements for v5 community provider status:
+
+### Technical Requirements ✅
+
+- Implements LanguageModelV2 specification
+- Follows provider factory pattern
+- Uses standard error handling
+- Supports AbortSignal
+- Has proper TypeScript types
+- Includes comprehensive tests
+- Emits stream-start event
+- Uses v5 token naming convention
+
+### Build Requirements ✅
+
+- Uses tsup for builds
+- Generates both CJS and ESM
+- Includes source maps
+- Has proper package.json configuration
+- Published with beta tag
+
+### Documentation Requirements ✅
+
+- Comprehensive README with version compatibility
+- CHANGELOG with version history
+- Extensive examples using v5 patterns
+- Clear setup instructions
+- Migration guide from v4
+
+## Version Strategy
+
+- **0.x versions**: AI SDK v4 compatibility (maintained on `ai-sdk-v4` branch)
+- **1.x versions**: AI SDK v5 with `@anthropic-ai/claude-code` (maintained on `v1` branch)
+- **2.x versions**: AI SDK v5 with `@anthropic-ai/claude-agent-sdk` (maintained on `main` branch)
+
+## Next Steps for Community Submission
+
+1. **Publish to npm with beta tag**
+
+   ```bash
+   npm publish --tag beta
+   ```
+
+2. **Prepare MDX Documentation**
+   Create a documentation file following the v5 community provider format (see example below)
+
+3. **Submit PR to AI SDK Repository**
+   - Add provider to v5 community providers list
+   - Include MDX documentation
+   - Reference npm package with beta tag
+
+## Example Community Provider MDX (v5)
+
+````mdx
+---
+title: Claude Code (v5)
+description: Use Claude via the official Claude Agent SDK with your Pro/Max subscription
+---
+
+# Claude Code Provider (v5)
+
+[ben-vargas/ai-sdk-provider-claude-code](https://github.com/ben-vargas/ai-sdk-provider-claude-code)
+is a community provider that uses the official [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+to provide language model support for the AI SDK v5.
+
+<Note type="warning">
+  This is the v5 compatible version. For AI SDK v4 support, use version 0.2.x.
+</Note>
+
+## Setup
+
+The Claude Code provider is available in the `ai-sdk-provider-claude-code` module. You can install it with:
+
+<Tabs items={['pnpm', 'npm', 'yarn']}>
+  <Tab>
+    <Snippet text="pnpm add ai-sdk-provider-claude-code@beta ai@beta" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install ai-sdk-provider-claude-code@beta ai@beta" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add ai-sdk-provider-claude-code@beta ai@beta" dark />
+  </Tab>
+</Tabs>
+
+### Prerequisites
+
+Install and authenticate the Claude CLI:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+```
+````
+
+## Provider Instance
+
+You can import the default provider instance `claudeCode` from `ai-sdk-provider-claude-code`:
+
+```ts
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+```
+
+## Language Models
+
+The Claude Code provider supports the following models:
+
+- `haiku` - Claude 4.5 Haiku (fastest, most cost-effective)
+- `sonnet` - Claude 4.5 Sonnet (balanced speed and capability)
+- `opus` - Claude 4.1 Opus (most capable)
+
+```ts
+import { generateText } from 'ai';
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+
+const result = await generateText({
+  model: claudeCode('sonnet'),
+  prompt: 'Explain recursion in one sentence',
+});
+
+console.log(result.text);
+```
+
+### Model Capabilities
+
+| Model  | Text Generation | Object Generation | Image Input | AI SDK Tool Calling | MCP Tools |
+| ------ | --------------- | ----------------- | ----------- | ------------------- | --------- |
+| opus   | ✅              | ✅                | ✅\*        | ❌                  | ✅        |
+| sonnet | ✅              | ✅                | ✅\*        | ❌                  | ✅        |
+
+\*Image inputs supported via streaming mode with base64/data URLs. Remote HTTP(S) URLs not supported.
+
+<Note>
+  The provider uses the official Claude Agent SDK. While the models support tool use, this provider
+  doesn't implement the AI SDK's tool calling interface. However, you can configure MCP servers
+  for tool functionality, and Claude can use built-in tools (Bash, Read, Write, etc.) through
+  the Claude Agent SDK.
+</Note>
+
+## v5 Specific Features
+
+This version includes full support for AI SDK v5 features:
+
+- **New streaming API** with promise-based result objects
+- **Updated token usage** properties (inputTokens, outputTokens, totalTokens)
+- **Stream-start events** for better stream initialization
+- **Array-based message content** format
+
+```ts
+// v5 streaming pattern
+const result = streamText({
+  model: claudeCode('sonnet'),
+  prompt: 'Write a haiku',
+});
+
+const text = await result.text;
+const usage = await result.usage;
+```
+
+See the [migration guide](https://github.com/ben-vargas/ai-sdk-provider-claude-code/blob/main/docs/ai-sdk-v5/V5_BREAKING_CHANGES.md) for details on upgrading from v0.x to v1.x-beta.
+
+```
+
+```