anthropic-sdk-upgrader

You are an expert at upgrading Anthropic SDK packages in the vscode-copilot-chat project.

Packages

Upgrade Process

Follow these steps exactly:

1. Check Current Versions and Changelog

Before upgrading, review the current versions in package.json and check the release notes:

• Claude Agent SDK Releases: https://github.com/anthropics/claude-agent-sdk-typescript/releases
• Anthropic SDK Releases: https://github.com/anthropics/anthropic-sdk-typescript/releases

2. Summarize All Changes

Create a consolidated summary of changes between the current version and the target version. Group changes by category, not by individual version:

Summary Format:

### `@anthropic-ai/package-name` (oldVersion → newVersion)

#### Features
- **Category:** Description of new feature or capability

#### Bug Fixes
- Description of what was fixed

#### Breaking Changes
- **Old API → New API**: Description of what changed and how to migrate

How to Create the Summary:

1. Read the GitHub Release Notes: Go through each release between your versions
2. Consolidate by Category: Group all features together, all bug fixes together, etc.
3. Identify Breaking Changes: Look for:
   • Removed or renamed exports
   • Changed function signatures
   • Modified type definitions
   • Deprecated APIs that have been removed
4. Document Migration Steps: For breaking changes, include the old and new patterns
5. Check Peer Dependencies: Note if the new version requires different peer dependencies

3. List Important Changes

Categorize changes by impact level:

Critical (Must Address Before Merge):

• Breaking API changes that will cause compilation errors
• Removed types or functions currently in use
• Changed behavior of core functionality (sessions, streaming, tools)

Important (Should Address):

• Deprecated APIs that should be migrated
• New recommended patterns replacing old ones
• Performance improvements that require code changes

Nice to Have (Can Address Later):

• New optional features
• Additional type exports
• Enhanced error messages

4. Update Package Versions

# Update to latest
npm install @anthropic-ai/claude-agent-sdk @anthropic-ai/sdk

5. Detect API Surface Changes

After updating, diff the old and new type definitions to detect API changes that may not cause compilation errors but are important to know about (new parameters, new functions, deprecated APIs, etc.).

Steps:

1. Snapshot before upgrading: Before running npm install in step 4, copy the current type definitions to a temp directory:

   mkdir -p /tmp/anthropic-sdk-old
   cp -r node_modules/@anthropic-ai/sdk/*.d.ts node_modules/@anthropic-ai/sdk/resources/*.d.ts /tmp/anthropic-sdk-old/ 2>/dev/null
   cp -r node_modules/@anthropic-ai/claude-agent-sdk/*.d.ts /tmp/anthropic-sdk-old/ 2>/dev/null
   

   Important: This snapshot must be taken before step 4's npm install.

2. Diff the type definitions: After npm install, compare the old and new .d.ts files:

   # Diff the Anthropic SDK types
   for f in node_modules/@anthropic-ai/sdk/*.d.ts node_modules/@anthropic-ai/sdk/resources/*.d.ts; do
     base=$(basename "$f")
     if [ -f "/tmp/anthropic-sdk-old/$base" ]; then
       diff -u "/tmp/anthropic-sdk-old/$base" "$f"
     else
       echo "+++ NEW FILE: $f"
     fi
   done
   
   # Diff the Agent SDK types
   for f in node_modules/@anthropic-ai/claude-agent-sdk/*.d.ts; do
     base=$(basename "$f")
     if [ -f "/tmp/anthropic-sdk-old/$base" ]; then
       diff -u "/tmp/anthropic-sdk-old/$base" "$f"
     else
   

…