ai-pro-sdk 2.0.1

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

@@ -0,0 +1,10 @@
+# AI SDK v5 Documentation (Historical)
+
+> **Historical:** These documents cover legacy provider versions 1.x–2.x (AI SDK v5). Much of the guidance still applies to 3.x, but new features are documented in the [main README](../../README.md).
+
+- [GUIDE.md](GUIDE.md) - Usage guide
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions
+- [TOOL_STREAMING_SUPPORT.md](TOOL_STREAMING_SUPPORT.md) - Tool streaming event semantics
+- [V5_BREAKING_CHANGES.md](V5_BREAKING_CHANGES.md) - v0.x to v1.x migration guide
+- [V5_MIGRATION_PLAN.md](V5_MIGRATION_PLAN.md), [V5_MIGRATION_SUMMARY.md](V5_MIGRATION_SUMMARY.md), [V5_MIGRATION_TASKS.md](V5_MIGRATION_TASKS.md) - Internal v5 migration records
+- [DEVELOPMENT-STATUS.md](DEVELOPMENT-STATUS.md) - Development status

package/docs/ai-sdk-v5/TOOL_STREAMING_SUPPORT.md

@@ -0,0 +1,55 @@
+# Tool Streaming Support (AI SDK v5)
+
+## Overview
+
+Claude Code now emits full tool streaming events when used through the AI SDK v5 provider. This aligns the provider with the AI SDK's `LanguageModelV2StreamPart` contract, enabling downstream UIs to surface tool calls, inputs, and results in real time.
+
+## Requirements
+
+- **Streaming input enabled**: set `streamingInput: 'always'` or rely on `'auto'` by supplying `canUseTool`.
+- **Provider-executed tools**: Claude Code's built-in tools run inside the CLI; for every `tool-call` and `tool-result` event the provider sets `providerExecuted: true` so the AI SDK will not attempt to re-run the tool client-side.
+- **Claude Code CLI**: authenticate with `claude login` and ensure the CLI is on your PATH before running streaming examples or tests. Allow the built-in tools explicitly (for example `allowedTools: ['Bash', 'Read']`) or set a permissive permission mode such as `bypassPermissions`.
+
+## Stream Parts Emitted
+
+| Event              | Description                                                                                                                                                                                                                                                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tool-input-start` | Sent once per tool use with Claude's tool name and a stable ID.                                                                                                                                                                                                                                                           |
+| `tool-input-delta` | JSON-serialized argument chunks. The provider emits deltas only for incremental prefix updates (new content appended to previous input). Non-prefix updates (corrections, replacements, or duplicate transmissions) do not emit `tool-input-delta`; the final complete input is always captured in the `tool-call` event. |
+| `tool-input-end`   | Marks completion of the request payload going to the tool.                                                                                                                                                                                                                                                                |
+| `tool-call`        | Includes `toolCallId`, `toolName`, serialized `input`, and `providerExecuted: true`. Raw, non-serialized input is preserved in `providerMetadata['claude-code'].rawInput`.                                                                                                                                                |
+| `tool-error`       | Emitted when tool execution fails, includes `toolCallId`, `toolName`, error message, and is distinct from `tool-result` with `isError: true`.                                                                                                                                                                             |
+| `tool-result`      | Streams the CLI output (JSON parsed when possible) with `toolName`, `toolCallId`, `isError`, `providerExecuted: true`, and the original output under `providerMetadata['claude-code'].rawResult`.                                                                                                                         |
+
+Text streaming (`text-start`/`text-delta`/`text-end`), response metadata, and finish parts continue to behave as before.
+
+## Usage Example
+
+Run the new example to observe the events:
+
+```bash
+npm run build
+npx tsx examples/tool-streaming.ts
+```
+
+The script approves tools via `canUseTool` and logs each event in order, demonstrating directory listing and file-read operations executed by the CLI.
+
+## Testing & Validation
+
+- Vitest suite includes coverage that asserts tool stream parts surface for provider-executed tools (`src/claude-code-language-model.test.ts`).
+- Integration and example scripts rely on the compiled `dist` build; run `npm run build && npm run test` before publishing.
+- If stream parts stop appearing, re-run with `DEBUG=1` or enable a custom logger (`settings.logger`) to capture warnings from the underlying SDK.
+
+## Known Limitations
+
+- Claude Code does not emit incremental tool argument chunks today; the provider emits a single `tool-input-delta` payload per tool call unless the SDK starts sending partial updates.
+- Delta skipping: If Claude sends non-prefix input updates (e.g., corrections or replacements rather than appends), the provider will skip delta emission and include the final input in the `tool-call` event only.
+- Remote image URLs remain unsupported; convert images to base64 data URLs and set `streamingInput` accordingly.
+
+## Performance Considerations
+
+- Delta calculation: Performed only for tool inputs ≤ 10KB and for prefix-only updates. Larger or non-prefix updates skip deltas and are captured in the final `tool-call` payload.
+- Size limits: Tool inputs exceeding 1MB throw an error. Inputs above 100KB log a warning due to potential performance impact.
+- Memory management: Tool state is retained until stream completion to avoid duplicate `tool-call` emissions when multiple result or error chunks arrive.
+
+Note: This provider extends `tool-error` events to include `providerExecuted: true` and `providerMetadata['claude-code']` for parity with tool-call/result. Downstream consumers can safely ignore these fields if not used.

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

@@ -0,0 +1,381 @@
+# Troubleshooting Guide (AI SDK v5)
+
+This guide documents common issues and solutions for the Claude Code AI SDK Provider with v5.
+
+## 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-agent-sdk` 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-agent-sdk
+```
+
+### 3. v5 Message Format Errors
+
+**Problem**: Error about invalid message content format.
+
+**Solution**: In v5, user messages must have content as an array of parts:
+
+```typescript
+// ❌ Wrong (v4 format)
+{ role: 'user', content: 'Hello' }
+
+// ✅ Correct (v5 format)
+{ role: 'user', content: [{ type: 'text', text: 'Hello' }] }
+```
+
+### 4. Streaming API Changes
+
+**Problem**: Streaming code from v4 doesn't work.
+
+**Solution**: v5 uses a new streaming pattern with promises:
+
+```typescript
+// ❌ Old v4 pattern
+const { textStream } = await streamText({
+  model: claudeCode('sonnet'),
+  prompt: 'Hello',
+});
+
+// ✅ New v5 pattern
+const result = streamText({
+  model: claudeCode('sonnet'),
+  prompt: 'Hello',
+});
+
+// Access parts as promises
+const text = await result.text;
+const usage = await result.usage;
+
+// Or stream chunks
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### 5. Token Usage Property Names
+
+**Problem**: Getting undefined for `promptTokens` or `completionTokens`.
+
+**Solution**: Token properties have been renamed in v5:
+
+```typescript
+// ❌ Old v4 names
+console.log(usage.promptTokens);
+console.log(usage.completionTokens);
+
+// ✅ New v5 names
+console.log(usage.inputTokens);
+console.log(usage.outputTokens);
+console.log(usage.totalTokens); // New in v5
+```
+
+### 6. 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 result = await generateText({
+    model: claudeCode('opus'),
+    prompt: 'Complex reasoning task...',
+    abortSignal: controller.signal,
+  });
+  clearTimeout(timeoutId);
+  console.log(result.text);
+} 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
+
+### 7. 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)));
+    }
+  }
+}
+```
+
+### 8. Session Management
+
+**Problem**: Conversations don't maintain context.
+
+**Solution**: Use message history with v5 format:
+
+```typescript
+import { ModelMessage } from 'ai';
+
+const messages: ModelMessage[] = [
+  { role: 'user', content: [{ type: 'text', text: 'My name is Alice' }] },
+  { role: 'assistant', content: [{ type: 'text', text: 'Nice to meet you, Alice!' }] },
+  { role: 'user', content: [{ type: 'text', text: 'What is my name?' }] },
+];
+
+const result = 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.
+
+### 9. 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 result = 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);
+  }
+}
+```
+
+## v5-Specific Migration Issues
+
+### 1. Result Structure Changes
+
+**Problem**: Code expecting v4 result structure fails.
+
+**Solution**: Update to v5 result structure:
+
+```typescript
+// ❌ v4 pattern
+const { text, usage } = await generateText(...);
+
+// ✅ v5 pattern
+const result = await generateText(...);
+console.log(result.text);
+console.log(result.usage);
+```
+
+### 2. Stream Event Changes
+
+**Problem**: Stream events have different names.
+
+**Solution**: v5 includes a `stream-start` event:
+
+```typescript
+const result = streamText({
+  model: claudeCode('sonnet'),
+  prompt: 'Hello',
+});
+
+// v5 stream includes: stream-start, text-delta, finish
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'stream-start':
+      console.log('Stream started');
+      break;
+    case 'text-delta':
+      process.stdout.write(chunk.textDelta);
+      break;
+    case 'finish':
+      console.log('Stream finished');
+      break;
+  }
+}
+```
+
+### 3. Unsupported Settings
+
+**Problem**: Getting warnings about unsupported settings.
+
+**Solution**: Some v4 settings are renamed or removed in v5:
+
+```typescript
+// ❌ v4 setting names
+{
+  maxTokens: 1000;
+}
+
+// ✅ v5 setting names
+{
+  maxOutputTokens: 1000;
+}
+
+// Note: Many settings like temperature, topP, etc. are still not supported by Claude Code SDK
+```
+
+## 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 result = await generateText({
+  model: claudeCode('sonnet'),
+  prompt: 'Test',
+});
+
+console.log('Metadata:', result.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 `haiku` for fastest, most cost-effective responses
+   - Use `sonnet` for balanced performance
+   - 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. **Image Support Requires Streaming Mode**: Image inputs are supported via streaming mode with base64/data URLs. See `examples/images.ts`. Remote HTTP(S) URLs are not supported.
+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', 'sonnet', and 'haiku' 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 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                    |
+| "Invalid message content"          | v4 message format     | Update to v5 array format                      |
+| "promptTokens is undefined"        | v4 property names     | Use inputTokens/outputTokens                   |

package/docs/ai-sdk-v5/V5_BREAKING_CHANGES.md

@@ -0,0 +1,158 @@
+# Breaking Changes: V4 to V5 Migration
+
+This document outlines the breaking changes users will encounter when upgrading from v4 to v5 of the ai-sdk-provider-claude-code.
+
+⚠️ **IMPORTANT**: This is a complete breaking change. The v5 version of this provider ONLY works with AI SDK v5. You cannot use:
+
+- v5 provider with AI SDK v4 ❌
+- v4 provider with AI SDK v5 ❌
+
+You must upgrade both together.
+
+## Installation
+
+Update your dependencies to use the beta versions:
+
+```json
+{
+  "dependencies": {
+    "ai": "beta",
+    "ai-sdk-provider-claude-code": "latest"
+  }
+}
+```
+
+## API Changes
+
+### 1. Token Usage Properties
+
+The token usage properties have been renamed:
+
+```typescript
+// V4
+const { usage } = await generateText(...);
+console.log(usage.promptTokens);    // ❌ Old
+console.log(usage.completionTokens); // ❌ Old
+
+// V5
+const { usage } = await generateText(...);
+console.log(usage.inputTokens);     // ✅ New
+console.log(usage.outputTokens);    // ✅ New
+console.log(usage.totalTokens);     // ✅ New
+```
+
+### 2. Streaming Response Pattern
+
+The streamText function now returns a result object with promises:
+
+```typescript
+// V4
+const { text, usage } = await streamText({
+  model: claudeCode('opus'),
+  prompt: 'Hello',
+});
+
+// V5
+const result = streamText({
+  model: claudeCode('opus'),
+  prompt: 'Hello',
+});
+const text = await result.text;
+const usage = await result.usage;
+```
+
+### 3. Message Types
+
+In v5, messages sent to the model should use `ModelMessage` type:
+
+```typescript
+// V4
+import type { Message } from 'ai';
+const messages: Message[] = [];
+
+// V5
+import type { ModelMessage } from 'ai';
+const messages: ModelMessage[] = [];
+```
+
+**Note**: `UIMessage` is for UI state management, while `ModelMessage` is for sending to language models.
+
+### 4. Parameter Names
+
+Some parameter names have changed:
+
+```typescript
+// V4
+generateText({
+  model: claudeCode('opus'),
+  prompt: 'Hello',
+  maxTokens: 100, // ❌ Old
+});
+
+// V5
+generateText({
+  model: claudeCode('opus'),
+  prompt: 'Hello',
+  maxOutputTokens: 100, // ✅ New
+});
+```
+
+### 5. Stream Events
+
+V5 streams now emit additional events:
+
+```typescript
+// V5 stream includes these events:
+// - stream-start (with warnings)
+// - response-metadata
+// - text-delta (with 'delta' property, not 'textDelta')
+// - finish
+```
+
+## Code Examples
+
+### Basic Text Generation
+
+```typescript
+// V5 Pattern
+import { streamText } from 'ai';
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+
+const result = streamText({
+  model: claudeCode('opus'),
+  prompt: 'Write a haiku',
+});
+
+// Await the results
+const text = await result.text;
+const usage = await result.usage;
+const metadata = await result.providerMetadata;
+```
+
+### Conversation with History
+
+```typescript
+// V5 Pattern
+import { streamText } from 'ai';
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+import type { CoreMessage } from 'ai';
+
+const messages: CoreMessage[] = [
+  { role: 'user', content: 'Hello!' },
+  { role: 'assistant', content: 'Hi there!' },
+  { role: 'user', content: 'How are you?' },
+];
+
+const result = streamText({
+  model: claudeCode('opus'),
+  messages,
+});
+
+const response = await result.text;
+```
+
+## Notes
+
+- All Claude Code SDK-specific limitations still apply (no temperature control, no output length limits, etc.)
+- TypeScript users will get compile-time errors for most breaking changes
+- This is a complete rewrite for v5 compatibility - no v4 compatibility is maintained

package/docs/ai-sdk-v5/V5_MIGRATION_PLAN.md

@@ -0,0 +1,22 @@
+# V5-Beta Migration Plan
+
+The goal of this migration is to update the `ai-sdk-provider-claude-code` to be compatible with the Vercel AI SDK v5-beta. This document outlines the plan that was followed to achieve this.
+
+## Key Areas of Change
+
+The migration focused on the following key areas:
+
+1.  **Dependency Upgrades:** The first step was to update all relevant `@ai-sdk` and `ai` packages to their `@beta` versions. This brought in the new `LanguageModelV2` architecture and other breaking changes.
+
+2.  **`LanguageModelV2` Adoption:** The core of the migration was to rewrite the `ClaudeCodeLanguageModel` to conform to the new `LanguageModelV2` interface. This involved the following:
+    - Changing the `doStream` and `doGenerate` methods to handle the new `UIMessage` and `ModelMessage` formats.
+    - Adopting the "content-first" design, where all outputs are treated as ordered content parts.
+    - Ensuring type safety with the new `LanguageModelV2` types.
+
+3.  **Message Overhaul:** The provider was updated to handle the new `UIMessage` and `ModelMessage` types. This meant that the `convertToClaudeCodeMessages` function was updated to accept `ModelMessage`s and convert them to the format that the Claude API expects.
+
+4.  **Server-Sent Events (SSE):** The provider was updated to work with the new SSE-based streaming protocol. This required changes to how the streaming responses are handled and formatted.
+
+5.  **Tool Handling:** The provider was updated to handle the new type-safe tool calls. This involved changes to how tools are defined and how tool calls are processed.
+
+6.  **Examples and Tests:** All examples and tests were updated to use the new v5-beta APIs. This was a good way to validate the migration and ensure that everything was working as expected.