ai-sdk-provider-claude-code 3.0.0-beta.1 → 3.0.1

package/README.md

@@ -9,7 +9,7 @@
 
 # AI SDK Provider for Claude Code SDK
 
-> **Latest Release**: Version 2.x uses the Claude Agent SDK with native structured outputs support (v2.2.0+). For AI SDK v4 support, use the `ai-sdk-v4` tag or version 0.2.x.
+> **Latest Release**: Version 3.x supports AI SDK v6 stable with the Claude Agent SDK. For AI SDK v5 support, use the `ai-sdk-v5` tag.
 
 **ai-sdk-provider-claude-code** lets you use Claude via the [Vercel AI SDK](https://sdk.vercel.ai/docs) through the official `@anthropic-ai/claude-agent-sdk` and the Claude Code CLI.
 
@@ -17,23 +17,24 @@
 
 | Provider Version | AI SDK Version | Underlying SDK                       | NPM Tag              | Status | Branch                                                                                  |
 | ---------------- | -------------- | ------------------------------------ | -------------------- | ------ | --------------------------------------------------------------------------------------- |
-| 2.x.x            | v5             | `@anthropic-ai/claude-agent-sdk`     | `latest`             | Stable | `main`                                                                                  |
-| 1.x.x            | v5             | `@anthropic-ai/claude-code` (legacy) | `v1-claude-code-sdk` | Stable | [`v1`](https://github.com/ben-vargas/ai-sdk-provider-claude-code/tree/v1)               |
-| 0.x.x            | v4             | `@anthropic-ai/claude-code`          | `ai-sdk-v4`          | Legacy | [`ai-sdk-v4`](https://github.com/ben-vargas/ai-sdk-provider-claude-code/tree/ai-sdk-v4) |
+| 3.x.x            | v6             | `@anthropic-ai/claude-agent-sdk`     | `latest`             | Stable | `main`                                                                                  |
+| 2.x.x            | v5             | `@anthropic-ai/claude-agent-sdk`     | `ai-sdk-v5`          | Stable | [`ai-sdk-v5`](https://github.com/ben-vargas/ai-sdk-provider-claude-code/tree/ai-sdk-v5) |
+| 1.x.x            | v5             | `@anthropic-ai/claude-code` (legacy) | `v1-claude-code-sdk` | Legacy | [`v1`](https://github.com/ben-vargas/ai-sdk-provider-claude-code/tree/v1)               |
+| 0.x.x            | v4             | `@anthropic-ai/claude-code` (legacy) | `ai-sdk-v4`          | Legacy | [`ai-sdk-v4`](https://github.com/ben-vargas/ai-sdk-provider-claude-code/tree/ai-sdk-v4) |
 
 ### Installing the Right Version
 
-**For AI SDK v5 with Claude Agent SDK (recommended):**
+**For AI SDK v6 (recommended):**
 
 ```bash
-npm install ai-sdk-provider-claude-code ai
+npm install ai-sdk-provider-claude-code ai@^6.0.0
 # or explicitly: npm install ai-sdk-provider-claude-code@latest
 ```
 
-**For AI SDK v5 with Claude Code SDK (legacy):**
+**For AI SDK v5:**
 
 ```bash
-npm install ai-sdk-provider-claude-code@v1-claude-code-sdk ai
+npm install ai-sdk-provider-claude-code@ai-sdk-v5 ai@^5.0.0
 ```
 
 **For AI SDK v4 (legacy):**
@@ -45,69 +46,17 @@ npm install ai-sdk-provider-claude-code@ai-sdk-v4 ai@^4.3.16
 
 ## Zod Compatibility
 
-This package is **tested and compatible with both Zod 3 and Zod 4**, but there's an important peer dependency consideration:
-
-### Current Status
-
-- ✅ **Zod 3** (fully supported, no warnings)
-- ⚠️ **Zod 4** (functional, but requires `--legacy-peer-deps`)
-
-While this package declares support for both versions (`peerDependencies: "zod": "^3.0.0 || ^4.0.0"`), the underlying `@anthropic-ai/claude-agent-sdk` currently only declares support for Zod 3 (`peerDependencies: "zod": "^3.24.1"`).
-
-**All 302 tests pass with both Zod 3 and Zod 4.** See `examples/zod4-compatibility-test.ts` for comprehensive compatibility verification.
-
-### Installation Instructions
-
-**With Zod 3 (recommended for now):**
+This package is **fully compatible with both Zod 3 and Zod 4**.
 
 ```bash
+# With Zod 3
 npm install ai-sdk-provider-claude-code ai zod@^3.0.0
-```
-
-**With Zod 4 (requires package manager-specific flags):**
-
-For **npm**:
-
-```bash
-npm install ai-sdk-provider-claude-code ai zod@^4.0.0 --legacy-peer-deps
-```
-
-For **pnpm**:
-
-```bash
-pnpm install ai-sdk-provider-claude-code ai zod@^4.0.0 --no-strict-peer-dependencies
-# Or configure it project-wide:
-pnpm config set strict-peer-dependencies false
-```
-
-For **Yarn** (Berry/v2+):
-
-```bash
-yarn add ai-sdk-provider-claude-code ai zod@^4.0.0
-# Yarn's peer resolution typically doesn't error here
-```
-
-### For Package Developers
-
-If you're developing with this package in your repository, add a configuration file to avoid needing the flag on every install:
-
-**For npm** (`.npmrc`):
-
-```ini
-# .npmrc
-legacy-peer-deps=true
-```
-
-**For pnpm** (`.npmrc`):
 
-```ini
-# .npmrc
-strict-peer-dependencies=false
+# With Zod 4
+npm install ai-sdk-provider-claude-code ai zod@^4.0.0
 ```
 
-> **Note**: The `.npmrc` file in this repository is committed for CI/development consistency but is **not included in the published package** (it's excluded via the `files` field in `package.json`). End users will still need to use the appropriate flags when installing with Zod 4.
-
-> **Temporary Workaround**: This configuration is needed until `@anthropic-ai/claude-agent-sdk` adds official Zod 4 support to their peer dependencies. Track progress in the [claude-agent-sdk repository](https://github.com/anthropics/anthropic-sdk-typescript).
+Both this package and the underlying `@anthropic-ai/claude-agent-sdk` declare support for both versions (`peerDependencies: "zod": "^3.24.1 || ^4.0.0"`).
 
 ## Installation
 
@@ -121,10 +70,13 @@ claude login
 ### 2. Add the provider
 
 ```bash
-# For v5 (recommended)
-npm install ai-sdk-provider-claude-code ai
+# For AI SDK v6 (recommended)
+npm install ai-sdk-provider-claude-code ai@^6.0.0
+
+# For AI SDK v5
+npm install ai-sdk-provider-claude-code@ai-sdk-v5 ai@^5.0.0
 
-# For v4 (legacy)
+# For AI SDK v4 (legacy)
 npm install ai-sdk-provider-claude-code@ai-sdk-v4 ai@^4.3.16
 ```
 
@@ -140,7 +92,7 @@ Please ensure you have appropriate permissions and comply with all applicable te
 
 ## Quick Start
 
-### AI SDK v5
+### AI SDK v6
 
 ```typescript
 import { streamText } from 'ai';
@@ -155,22 +107,31 @@ const text = await result.text;
 console.log(text);
 ```
 
-### AI SDK v4
+### AI SDK v5
 
 ```typescript
-import { generateText } from 'ai';
+// npm install ai-sdk-provider-claude-code@ai-sdk-v5 ai@^5.0.0
+import { streamText } from 'ai';
 import { claudeCode } from 'ai-sdk-provider-claude-code';
 
-const { text } = await generateText({
+const result = streamText({
   model: claudeCode('haiku'),
   prompt: 'Hello, Claude!',
 });
 
+const text = await result.text;
 console.log(text);
 ```
 
 ## Breaking Changes
 
+### Version 3.0.0 (AI SDK v6 Stable)
+
+This version upgrades to AI SDK v6 stable with updated provider types:
+
+- **`usage.raw`** now contains raw provider usage (previously in `providerMetadata['claude-code'].rawUsage`)
+- Internal type changes for `LanguageModelV3Usage` and `LanguageModelV3FinishReason` (transparent to most users)
+
 ### Version 2.0.0 (Claude Agent SDK Migration)
 
 This version migrates to `@anthropic-ai/claude-agent-sdk` with **new defaults for better control**:
@@ -317,6 +278,37 @@ console.log(result.object); // Guaranteed to match schema
 - Use realistic image payloads—very small placeholders may result in the model asking for a different image.
 - `examples/images.ts` accepts a local image path and converts it to a data URL on the fly: `npx tsx examples/images.ts /absolute/path/to/image.png`.
 
+## Skills Support
+
+Claude Code supports **Skills** - custom tools and capabilities defined in your user or project settings. To enable skills, configure both `settingSources` and `allowedTools`:
+
+```typescript
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+import { streamText } from 'ai';
+
+const result = await streamText({
+  model: claudeCode('sonnet', {
+    settingSources: ['user', 'project'],
+    allowedTools: ['Skill', 'Read', 'Write', 'Bash'],
+  }),
+  prompt: 'Use my /custom-skill to help with this task',
+});
+```
+
+**Requirements:**
+
+- `settingSources` - Where to load skills from (`'user'`, `'project'`, `'local'`)
+- `allowedTools` must include `'Skill'` to invoke skills
+
+**Where to define Skills:**
+
+- User: `~/.claude/skills/your-skill/SKILL.md`
+- Project: `.claude/skills/your-skill/SKILL.md`
+
+**Validation:** If you add `'Skill'` to `allowedTools` but forget to set `settingSources`, a validation warning will alert you that skills won't load.
+
+See [examples/skills-management.ts](examples/skills-management.ts) for more examples.
+
 ## Limitations
 
 - Requires Node.js ≥ 18

package/dist/index.cjs

@@ -407,13 +407,15 @@ function getErrorMetadata(error) {
 function mapClaudeCodeFinishReason(subtype) {
   switch (subtype) {
     case "success":
-      return "stop";
+      return { unified: "stop", raw: subtype };
     case "error_max_turns":
-      return "length";
+      return { unified: "length", raw: subtype };
     case "error_during_execution":
-      return "error";
+      return { unified: "error", raw: subtype };
+    case void 0:
+      return { unified: "stop", raw: void 0 };
     default:
-      return "stop";
+      return { unified: "other", raw: subtype };
   }
 }
 
@@ -585,6 +587,11 @@ function validateSettings(settings) {
     if (validSettings.disallowedTools) {
       validateToolNames(validSettings.disallowedTools, "disallowed");
     }
+    if (validSettings.allowedTools?.includes("Skill") && !validSettings.settingSources) {
+      warnings.push(
+        "allowedTools includes 'Skill' but settingSources is not set. Skills require settingSources (e.g., ['user', 'project']) to load skill definitions."
+      );
+    }
     return { valid: true, warnings, errors };
   } catch (error) {
     errors.push(`Validation error: ${error instanceof Error ? error.message : String(error)}`);
@@ -689,6 +696,42 @@ function isAbortError(err) {
   return false;
 }
 var STREAMING_FEATURE_WARNING = "Claude Agent SDK features (hooks/MCP/images) require streaming input. Set `streamingInput: 'always'` or provide `canUseTool` (auto streams only when canUseTool is set).";
+function createEmptyUsage() {
+  return {
+    inputTokens: {
+      total: 0,
+      noCache: 0,
+      cacheRead: 0,
+      cacheWrite: 0
+    },
+    outputTokens: {
+      total: 0,
+      text: void 0,
+      reasoning: void 0
+    },
+    raw: void 0
+  };
+}
+function convertClaudeCodeUsage(usage) {
+  const inputTokens = usage.input_tokens ?? 0;
+  const outputTokens = usage.output_tokens ?? 0;
+  const cacheWrite = usage.cache_creation_input_tokens ?? 0;
+  const cacheRead = usage.cache_read_input_tokens ?? 0;
+  return {
+    inputTokens: {
+      total: inputTokens + cacheWrite + cacheRead,
+      noCache: inputTokens,
+      cacheRead,
+      cacheWrite
+    },
+    outputTokens: {
+      total: outputTokens,
+      text: void 0,
+      reasoning: void 0
+    },
+    raw: usage
+  };
+}
 function toAsyncIterablePrompt(messagesPrompt, outputStreamEnded, sessionId, contentParts) {
   const content = contentParts && contentParts.length > 0 ? contentParts : [{ type: "text", text: messagesPrompt }];
   const msg = {
@@ -1042,16 +1085,12 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
     const queryOptions = this.createQueryOptions(abortController, options.responseFormat);
     let text = "";
     let structuredOutput;
-    let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-    let finishReason = "stop";
+    let usage = createEmptyUsage();
+    let finishReason = { unified: "stop", raw: void 0 };
     let wasTruncated = false;
     let costUsd;
     let durationMs;
-    let rawUsage;
-    const warnings = this.generateAllWarnings(
-      options,
-      messagesPrompt
-    );
+    const warnings = this.generateAllWarnings(options, messagesPrompt);
     if (messageWarnings) {
       messageWarnings.forEach((warning) => {
         warnings.push({
@@ -1114,18 +1153,13 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
             `[claude-code] Request completed - Session: ${message.session_id}, Cost: $${costUsd?.toFixed(4) ?? "N/A"}, Duration: ${durationMs ?? "N/A"}ms`
           );
           if ("usage" in message) {
-            rawUsage = message.usage;
-            usage = {
-              inputTokens: (message.usage.cache_creation_input_tokens ?? 0) + (message.usage.cache_read_input_tokens ?? 0) + (message.usage.input_tokens ?? 0),
-              outputTokens: message.usage.output_tokens ?? 0,
-              totalTokens: (message.usage.cache_creation_input_tokens ?? 0) + (message.usage.cache_read_input_tokens ?? 0) + (message.usage.input_tokens ?? 0) + (message.usage.output_tokens ?? 0)
-            };
+            usage = convertClaudeCodeUsage(message.usage);
             this.logger.debug(
-              `[claude-code] Token usage - Input: ${usage.inputTokens}, Output: ${usage.outputTokens}, Total: ${usage.totalTokens}`
+              `[claude-code] Token usage - Input: ${usage.inputTokens.total}, Output: ${usage.outputTokens.total}`
             );
           }
           finishReason = mapClaudeCodeFinishReason(message.subtype);
-          this.logger.debug(`[claude-code] Finish reason: ${finishReason}`);
+          this.logger.debug(`[claude-code] Finish reason: ${finishReason.unified}`);
         } else if (message.type === "system" && message.subtype === "init") {
           this.setSessionId(message.session_id);
           this.logger.info(`[claude-code] Session initialized: ${message.session_id}`);
@@ -1145,7 +1179,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
           `[claude-code] Detected truncated response, returning ${text.length} characters of buffered text`
         );
         wasTruncated = true;
-        finishReason = "length";
+        finishReason = { unified: "length", raw: "truncation" };
         warnings.push({
           type: "other",
           message: CLAUDE_CODE_TRUNCATION_WARNING
@@ -1177,7 +1211,6 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
           ...this.sessionId !== void 0 && { sessionId: this.sessionId },
           ...costUsd !== void 0 && { costUsd },
           ...durationMs !== void 0 && { durationMs },
-          ...rawUsage !== void 0 && { rawUsage },
           ...wasTruncated && { truncated: true }
         }
       }
@@ -1207,10 +1240,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
     if (queryOptions.includePartialMessages === void 0) {
       queryOptions.includePartialMessages = true;
     }
-    const warnings = this.generateAllWarnings(
-      options,
-      messagesPrompt
-    );
+    const warnings = this.generateAllWarnings(options, messagesPrompt);
     if (messageWarnings) {
       messageWarnings.forEach((warning) => {
         warnings.push({
@@ -1275,7 +1305,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
           }
           toolStates.clear();
         };
-        let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        let usage = createEmptyUsage();
         let accumulatedText = "";
         let textPartId;
         let streamedTextLength = 0;
@@ -1573,22 +1603,16 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
               this.logger.info(
                 `[claude-code] Stream completed - Session: ${message.session_id}, Cost: $${message.total_cost_usd?.toFixed(4) ?? "N/A"}, Duration: ${message.duration_ms ?? "N/A"}ms`
               );
-              let rawUsage;
               if ("usage" in message) {
-                rawUsage = message.usage;
-                usage = {
-                  inputTokens: (message.usage.cache_creation_input_tokens ?? 0) + (message.usage.cache_read_input_tokens ?? 0) + (message.usage.input_tokens ?? 0),
-                  outputTokens: message.usage.output_tokens ?? 0,
-                  totalTokens: (message.usage.cache_creation_input_tokens ?? 0) + (message.usage.cache_read_input_tokens ?? 0) + (message.usage.input_tokens ?? 0) + (message.usage.output_tokens ?? 0)
-                };
+                usage = convertClaudeCodeUsage(message.usage);
                 this.logger.debug(
-                  `[claude-code] Stream token usage - Input: ${usage.inputTokens}, Output: ${usage.outputTokens}, Total: ${usage.totalTokens}`
+                  `[claude-code] Stream token usage - Input: ${usage.inputTokens.total}, Output: ${usage.outputTokens.total}`
                 );
               }
               const finishReason = mapClaudeCodeFinishReason(
                 message.subtype
               );
-              this.logger.debug(`[claude-code] Stream finish reason: ${finishReason}`);
+              this.logger.debug(`[claude-code] Stream finish reason: ${finishReason.unified}`);
               this.setSessionId(message.session_id);
               const structuredOutput = "structured_output" in message ? message.structured_output : void 0;
               const alreadyStreamedJson = textPartId && options.responseFormat?.type === "json" && hasReceivedStreamEvents;
@@ -1647,7 +1671,6 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
                       costUsd: message.total_cost_usd
                     },
                     ...message.duration_ms !== void 0 && { durationMs: message.duration_ms },
-                    ...rawUsage !== void 0 && { rawUsage },
                     // JSON validation warnings are collected during streaming and included
                     // in providerMetadata since the AI SDK's finish event doesn't support
                     // a top-level warnings field (unlike stream-start which was already emitted)
@@ -1710,7 +1733,7 @@ var ClaudeCodeLanguageModel = class _ClaudeCodeLanguageModel {
             const warningsJson = this.serializeWarningsForMetadata(streamWarnings);
             controller.enqueue({
               type: "finish",
-              finishReason: "length",
+              finishReason: { unified: "length", raw: "truncation" },
               usage,
               providerMetadata: {
                 "claude-code": {