ai-pro-sdk 2.0.1

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

@@ -0,0 +1,77 @@
+# V5-Beta Migration Summary
+
+This document summarizes the migration of the `ai-sdk-provider-claude-code` to be compatible with the Vercel AI SDK v5-beta.
+
+## Current Status
+
+The migration is complete. The codebase is now compatible with the Vercel AI SDK v5-beta. All tests are passing, TypeScript compilation is successful, and the examples have been updated to use the new APIs.
+
+## Modified Files
+
+The following files were modified during the migration:
+
+- `package.json`: Updated to use the `@beta` versions of the `ai`, `@ai-sdk/provider`, and `@ai-sdk/provider-utils` packages.
+- `src/claude-code-language-model.ts`: Updated to implement the `LanguageModelV2` interface, and the `doGenerate` and `doStream` methods were updated to handle the new message format.
+- `src/convert-to-claude-code-messages.ts`: Updated to handle the new `ModelMessage` format and added v4 compatibility.
+- `src/map-claude-code-finish-reason.ts`: Updated to use the `LanguageModelV2FinishReason` type.
+- `src/claude-code-provider.ts`: Updated to use the `ProviderV2` and `LanguageModelV2` types.
+- `examples/basic-usage.ts`: Updated to use the new `streamText` API with proper async handling.
+- `examples/conversation-history.ts`: Updated to use the new `streamText` API and `CoreMessage` type.
+- `examples/tool-management.ts`: Updated to use the new `streamText` API with promises.
+- `examples/limitations.ts`: Updated parameter names (`maxOutputTokens` instead of `maxTokens`).
+- `src/claude-code-language-model.test.ts`: Updated to use the new v5-beta APIs and correct assertions.
+- `src/convert-to-claude-code-messages.test.ts`: Updated to use type-only import for `CoreMessage`.
+
+## Key Migration Challenges and Solutions
+
+### 1. Token Usage Property Names
+
+**Issue**: V4 used `promptTokens`/`completionTokens` while V5 uses `inputTokens`/`outputTokens`/`totalTokens`.
+**Solution**: Updated all token usage calculations and test assertions to use the new property names.
+
+### 2. Message Content Format
+
+**Issue**: V5 requires user messages to have content as an array of parts, not a string.
+**Solution**: Updated message handling to check for array content and extract text from parts.
+
+### 3. Stream Response Format
+
+**Issue**: V5 streams use different event types and structure.
+**Solutions**:
+
+- Added `stream-start` event emission with warnings
+- Changed `textDelta` to `delta` in stream parts
+- Removed `warnings` from doStream return type (now included in stream-start)
+
+### 4. Example Code Patterns
+
+**Issue**: Examples were using destructuring pattern that doesn't work with v5's promise-based API.
+**Solution**: Updated all examples to call streamText first, then await individual properties.
+
+### 5. TypeScript Strict Mode Issues
+
+**Issues**:
+
+- Lexical declarations in switch cases
+- Type-only imports required for `CoreMessage`
+- Invalid properties in API calls
+  **Solutions**:
+- Added block scope to switch cases
+- Changed to type-only imports where needed
+- Removed mode parameter from low-level API calls
+
+### 6. Tool Result Format
+
+**Issue**: Tests were using v4 format with `result` property, but v5 uses `output`.
+**Solution**: Added handling for test data that was still using v4 format. In production, only v5 format messages will be received.
+
+## Rationale for Changes
+
+The changes were made to align the provider with the new `LanguageModelV2` architecture and the other breaking changes introduced in the Vercel AI SDK v5-beta. This is a complete breaking change - the updated provider ONLY works with AI SDK v5-beta and is NOT compatible with v4.
+
+## Testing and Validation
+
+- All 230 tests are passing
+- TypeScript compilation is successful with no errors
+- ESLint passes with only minor warnings about `any` types in tests
+- Examples have been updated and are syntactically correct

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

@@ -0,0 +1,46 @@
+# V5-Beta Migration Tasks
+
+This document outlines the sequential tasks that were executed to migrate the `ai-sdk-provider-claude-code` to be compatible with the Vercel AI SDK v5-beta.
+
+## Phase 1: Setup and Dependency Updates
+
+1.  **Update `package.json`:**
+    - Update `ai` to `@beta`.
+    - Update `@ai-sdk/provider` to `@beta`.
+    - Update `@ai-sdk/provider-utils` to `@beta`.
+    - Run `npm install` to install the new dependencies.
+
+## Phase 2: Core Provider Migration
+
+1.  **Update `ClaudeCodeLanguageModel`:**
+    - Modify the class to implement the `LanguageModelV2` interface.
+    - Update the `doStream` and `doGenerate` methods to handle the new message formats and streaming protocol.
+
+2.  **Update `convertToClaudeCodeMessages`:**
+    - Modify the function to accept `ModelMessage`s as input.
+    - Update the conversion logic to correctly transform `ModelMessage`s into the Claude API format.
+
+3.  **Update `mapClaudeCodeFinishReason`:**
+    - Review and update the finish reason mapping to align with any changes in the v5-beta API.
+
+## Phase 3: Tooling and Error Handling
+
+1.  **Update Tool Handling:**
+    - Review the new type-safe tool call mechanism.
+    - Update any tool-related logic in the provider to use the new APIs.
+
+2.  **Update Error Handling:**
+    - Review the error handling in the provider and update it to align with any changes in the v5-beta API.
+
+## Phase 4: Validation and Testing
+
+1.  **Update Examples:**
+    - Go through each example in the `examples` directory and update it to use the new v5-beta APIs.
+    - This involved updating how the `useChat` hook is used, how messages are handled, and how the provider is instantiated.
+
+2.  **Update Tests:**
+    - Go through each test file in the `src` directory and update it to use the new v5-beta APIs.
+    - This involved updating how the language model is mocked and how the test assertions are written.
+
+3.  **Run all tests and examples:**
+    - Execute all tests and examples to ensure that the migration was successful and that there are no regressions.

package/docs/sessions.md

@@ -0,0 +1,117 @@
+# Session Management
+
+Every `generateText`/`streamText` call through this provider runs as a Claude Code **session**. By default the CLI persists each session as a JSONL transcript under `~/.claude/projects/` (honoring `CLAUDE_CONFIG_DIR`), and the session ID is surfaced on AI SDK v7's final step: `result.finalStep.providerMetadata['claude-code'].sessionId` for `generateText`, or `(await stream.finalStep).providerMetadata['claude-code'].sessionId` for `streamText`. Use that ID to resume, fork, inspect, retitle, tag, or delete the session later.
+
+This guide ties together the session-related **settings** (passed to `claudeCode(modelId, settings)`) and the session **helper functions** (re-exported from the Claude Agent SDK).
+
+For a runnable end-to-end walkthrough, see [examples/session-management.ts](../examples/session-management.ts) (`npm run example:sessions`).
+
+## Session settings
+
+| Setting           | Type      | Description                                                                                                                                                       |
+| ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sessionId`       | `string`  | Use a specific session ID for a **new** session (deterministic tracking/correlation). Must be a UUID.                                                             |
+| `resume`          | `string`  | Resume an existing session by ID. The conversation context is restored from the persisted transcript.                                                             |
+| `resumeSessionAt` | `string`  | When resuming, restore the session only up to a specific message UUID (later messages are discarded from context).                                                |
+| `forkSession`     | `boolean` | When resuming, fork to a **new** session ID instead of continuing under the original ID (combine with `sessionId` to choose the fork's ID).                       |
+| `continue`        | `boolean` | Continue the most recent conversation for the working directory, without needing its ID.                                                                          |
+| `persistSession`  | `boolean` | When `false`, the session is not written to `~/.claude/projects/` and cannot be resumed or inspected later. Useful for ephemeral workflows. Default `true`.       |
+| `title`           | `string`  | Custom title for a **new** session (instead of auto-generating one from the first prompt). When resuming, the resumed session's persisted title takes precedence. |
+
+### Capturing the session ID
+
+```ts
+import { generateText } from 'ai';
+import { claudeCode } from 'ai-sdk-provider-claude-code';
+
+const result = await generateText({
+  model: claudeCode('sonnet'),
+  prompt: 'Remember this code word: papaya. Reply with OK.',
+});
+
+const sessionId = result.finalStep.providerMetadata?.['claude-code']?.sessionId as string;
+```
+
+### Resuming a session
+
+```ts
+const followUp = await generateText({
+  model: claudeCode('sonnet', { resume: sessionId }),
+  prompt: 'What was the code word?',
+});
+// followUp.text mentions "papaya"; the session keeps the same ID.
+```
+
+### Forking at query time (the `forkSession` setting)
+
+```ts
+const branched = await generateText({
+  model: claudeCode('sonnet', { resume: sessionId, forkSession: true }),
+  prompt: 'Explore an alternative approach from here.',
+});
+// branched runs under a NEW session ID; the original transcript is untouched.
+const forkId = branched.finalStep.providerMetadata?.['claude-code']?.sessionId as string;
+```
+
+## Session helper functions
+
+These are re-exported from `@anthropic-ai/claude-agent-sdk` for convenience — no extra dependency needed. They are plain async functions, independent of any provider/model instance.
+
+| Helper                                              | Description                                                                                                                                                                                               |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `listSessions(options?)`                            | List metadata for all persisted sessions (`SDKSessionInfo[]`) — the discovery API for building session pickers. Supports filtering options (e.g. by project directory via `dir`, plus `limit`).           |
+| `getSessionMessages(sessionId, options?)`           | Read the main conversation transcript of a session (`SessionMessage[]`) — the counterpart to `getSubagentMessages()` for the top-level thread.                                                            |
+| `getSessionInfo(sessionId, options?)`               | Read metadata for one session (`SDKSessionInfo`: `summary`, `customTitle`, `firstPrompt`, `lastModified`, `cwd`, `gitBranch`, `tag`, ...). Returns `undefined` if not found.                              |
+| `forkSession(sessionId, options?)`                  | Copy a session's transcript into a new session ID **without running a query** (optionally sliced via `upToMessageId`, retitled via `title`). Returns `{ sessionId }`, resumable via the `resume` setting. |
+| `renameSession(sessionId, title, options?)`         | Retitle an existing session.                                                                                                                                                                              |
+| `tagSession(sessionId, tag, options?)`              | Set (or clear, with `null`) a session's tag.                                                                                                                                                              |
+| `deleteSession(sessionId, options?)`                | Delete a session's persisted transcript.                                                                                                                                                                  |
+| `listSubagents(sessionId, options?)`                | List agent IDs of subagent transcripts recorded under a session.                                                                                                                                          |
+| `getSubagentMessages(sessionId, agentId, options?)` | Read a subagent's transcript messages (`SessionMessage[]`).                                                                                                                                               |
+| `importSessionToStore(sessionId, store, options?)`  | Copy a local JSONL session (and, by default, its subagent transcripts) into a custom `SessionStore` (alpha).                                                                                              |
+| `foldSessionSummary(prev, key, entries, options?)`  | Pure utility for `SessionStore` implementers: fold appended entries into a `SessionSummaryEntry` inside `append()` (alpha).                                                                               |
+
+```ts
+import {
+  forkSession,
+  getSessionInfo,
+  renameSession,
+  deleteSession,
+} from 'ai-sdk-provider-claude-code';
+
+const info = await getSessionInfo(sessionId);
+console.log(info?.summary, info?.lastModified);
+
+const fork = await forkSession(sessionId, { title: 'experiment branch' });
+// ...resume the fork via claudeCode('sonnet', { resume: fork.sessionId })...
+
+await renameSession(sessionId, 'main investigation');
+await deleteSession(fork.sessionId);
+```
+
+### Two ways to fork
+
+- **`forkSession` setting** (`{ resume, forkSession: true }`) — fork **and run a query** in one step; the new ID arrives in `finalStep.providerMetadata` (or `await stream.finalStep` for streaming).
+- **`forkSession()` helper** — fork the stored transcript **without** running a query (and optionally slice it with `upToMessageId`); resume it later with the `resume` setting.
+
+## Disk storage vs custom `SessionStore`
+
+By default, everything above operates on the local JSONL files under `~/.claude/projects/` (the directory the CLI writes to; `CLAUDE_CONFIG_DIR` relocates it). Helpers that take an `options` object accept `dir` to scope the lookup to one project directory — when omitted, all project directories are searched.
+
+For custom backends (Postgres, S3, Redis, ...), the SDK defines a **`SessionStore`** adapter (alpha — subject to upstream change):
+
+- The `sessionStore` **setting** (with `sessionStoreFlush`, `loadTimeoutMs`) mirrors transcripts to your store **in addition to** local files while queries run. It cannot be combined with `persistSession: false` (local writes are required for the mirror) or `enableFileCheckpointing: true`, and combining it with `continue: true` (without an explicit `resume` ID) requires the store to implement `listSessions()` — the SDK uses it to discover the most recent session. The provider rejects all three invalid combinations at validation time.
+- Each helper's `options.sessionStore` redirects that helper to read/write **your store instead of the local filesystem** (e.g. `getSessionInfo(id, { sessionStore: myStore })`).
+- `importSessionToStore()` migrates an existing local session into a store; `foldSessionSummary()` and the `SessionKey`/`SessionStoreEntry`/`SessionSummaryEntry` types are the building blocks for writing a store; `InMemorySessionStore` is a reference implementation for tests.
+
+## `title` setting vs `renameSession()`
+
+- The `title` **setting** only names a **new** session at creation time. When resuming, the resumed session's persisted title takes precedence and the setting is ignored.
+- To retitle an **existing** session, use the `renameSession()` helper.
+- `forkSession()` accepts its own `title` for the fork; if omitted, the fork derives its title from the original (`"<original> (fork)"`).
+
+## Notes
+
+- `sessionId` cannot be combined with `continue` or `resume` unless `forkSession: true` is also set (in which case it names the forked session's ID). The provider enforces this — and the UUID requirement — at validation time, and on multi-turn conversations it stops forwarding `sessionId` once it auto-resumes via the captured session ID (which already carries the custom ID).
+- Sessions are stored per working directory (project). If you run queries with different `cwd` settings, pass `dir` to the helpers to disambiguate, or rely on the default search across all project directories.
+- `persistSession: false` sessions never reach disk, so none of the helpers can see them.

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "ai-pro-sdk",
+  "version": "2.0.1",
+  "description": "AI SDK v7 provider for Claude via Claude Agent SDK (use Pro/Max subscription)",
+  "keywords": [
+    "ai-sdk",
+    "claude-agent-sdk",
+    "anthropic",
+    "cli",
+    "language-model",
+    "llm"
+  ],
+  "homepage": "https://github.com/ben-vargas/ai-pro-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ben-vargas/ai-pro-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ben-vargas/ai-pro-sdk/issues"
+  },
+  "license": "MIT",
+  "author": "Ben Vargas",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "docs/**/*",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"console.log('Build skipped; dist artifacts are already present')\"",
+    "clean": "rm -rf dist",
+    "dev": "node -e \"console.log('Development build is not configured for this package')\"",
+    "lint": "eslint src",
+    "lint:all": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "ci": "npm run typecheck && npm run lint:all && npm run test",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "node -e \"console.log('No test suite configured')\"",
+    "test:coverage": "node -e \"console.log('No coverage suite configured')\"",
+    "test:edge": "node -e \"console.log('No edge tests configured')\"",
+    "test:node": "node -e \"console.log('No node tests configured')\"",
+    "test:watch": "node -e \"console.log('No watch tests configured')\"",
+    "test:integration": "npm run build && npx tsx examples/integration-test.ts",
+    "typecheck": "tsc --noEmit",
+    "example:basic": "npm run build && npx tsx examples/basic-usage.ts",
+    "example:streaming": "npm run build && npx tsx examples/streaming.ts",
+    "example:conversation": "npm run build && npx tsx examples/conversation-history.ts",
+    "example:config": "npm run build && npx tsx examples/custom-config.ts",
+    "example:object": "npm run build && npx tsx examples/generate-object.ts",
+    "example:object:constraints": "npm run build && npx tsx examples/generate-object-constraints.ts",
+    "example:tools": "npm run build && npx tsx examples/tool-management.ts",
+    "example:ai-sdk-tools": "npm run build && npx tsx examples/ai-sdk-tools.ts",
+    "example:sessions": "npm run build && npx tsx examples/session-management.ts",
+    "example:hooks-permissions": "npm run build && npx tsx examples/hooks-permission-denied.ts",
+    "example:warm-start": "npm run build && npx tsx examples/warm-start.ts",
+    "example:context-usage": "npm run build && npx tsx examples/context-usage.ts",
+    "example:prompt-suggestions": "npm run build && npx tsx examples/prompt-suggestions.ts",
+    "example:skills-option": "npm run build && npx tsx examples/skills-option.ts",
+    "example:mcp:filesystem": "npm run build && npx tsx examples/mcp-filesystem.ts",
+    "example:mcp:exa": "npm run build && npx tsx examples/mcp-exa.ts",
+    "example:timeout": "npm run build && npx tsx examples/long-running-tasks.ts",
+    "example:zod4": "npm run build && npx tsx examples/zod4-compatibility-test.ts",
+    "example:structured-repro": "npx tsx examples/structured-output-repro.ts",
+    "example:all": "npm run build && npm run example:basic && npm run example:streaming && npm run example:conversation && npm run example:config && npm run example:object && npm run example:object:constraints && npm run example:tools && npm run example:timeout"
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "^4.0.2",
+    "@ai-sdk/provider-utils": "^5.0.5",
+    "@anthropic-ai/claude-agent-sdk": "0.3.205",
+    "crypto-js": "^4.2.0",
+    "data-blockv": "^1.0.1"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "5.0.0",
+    "@eslint/js": "9.28.0",
+    "@types/node": "^22.10.0",
+    "@typescript-eslint/eslint-plugin": "8.34.0",
+    "@typescript-eslint/parser": "8.34.0",
+    "ai": "^7.0.16",
+    "eslint": "9.28.0",
+    "globals": "16.2.0",
+    "prettier": "^3.6.2",
+    "tsup": "8.5.0",
+    "typescript": "5.6.3",
+    "zod": "^4.1.12"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  }
+}