anthropic-sdk-upgrader by microsoft/vscode-copilot-chat

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

Packages

Package	Description
`@anthropic-ai/claude-agent-sdk`	Official Claude Agent SDK - provides the core agent runtime, tools, hooks, sessions, and message streaming
`@anthropic-ai/sdk`	Anthropic API SDK - provides base types, API client, and message structures used by the agent SDK

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:

Read the GitHub Release Notes: Go through each release between your versions
Consolidate by Category: Group all features together, all bug fixes together, etc.
Identify Breaking Changes: Look for:
- Removed or renamed exports
- Changed function signatures
- Modified type definitions
- Deprecated APIs that have been removed
Document Migration Steps: For breaking changes, include the old and new patterns
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:

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.

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
    echo "+++ NEW FILE: $f"
  fi
done

Analyze the diff and produce a report with the following categories:

New Exports — Functions, classes, types, or constants that were added:
- New exported functions or methods
- New type/interface definitions
- New enum values
New Parameters — Optional or required parameters added to existing functions:
- New optional fields on existing option/config types
- New required parameters (these are breaking changes — flag them as critical)
- New overloads of existing functions
Changed Signatures — Modifications to existing function/method signatures:
- Parameter type changes (e.g., string → string | string[])
- Return type changes
- Generic type parameter changes
Removed or Renamed — Items that were removed or renamed:
- Removed exports (breaking — flag as critical)
- Renamed types/functions (breaking — flag as critical)
- Removed fields from interfaces
Deprecations — Items newly marked as @deprecated:
- Functions or types with new @deprecated JSDoc tags
Cross-reference with our usage: For each change found, check whether the codebase currently uses the affected API:
```
# Example: if `createSession` gained a new parameter, check our usage
grep -rn "createSession" src/extension/agents/claude/
```
Flag changes that affect APIs we actively use as higher priority.
Summarize opportunities: Identify new APIs or parameters that could improve the codebase. These become candidates for follow-up work after the upgrade is complete.
Clean up:
```
rm -rf /tmp/anthropic-sdk-old
```

6. Fix Compilation Errors

After updating, check for compilation errors:

npm run compile

Address any type errors in the following key files:

src/extension/agents/claude/node/claudeCodeAgent.ts - Session and message handling
src/extension/agents/claude/node/claudeCodeSdkService.ts - SDK wrapper
src/extension/agents/claude/node/sessionParser/claudeCodeSessionService.ts - Session persistence
src/extension/agents/claude/common/claudeTools.ts - Tool type definitions
src/extension/agents/claude/node/hooks/*.ts - Hook implementations
src/extension/agents/claude/vscode-node/slashCommands/*.ts - Slash command handlers
src/extension/agents/claude/node/toolPermissionHandlers/*.ts - Permission handlers

7. Run Tests

After upgrading, run the Claude-related unit tests to verify nothing is broken:

# Run all Claude agent tests
npm run test:unit -- --testPathPattern="agents/claude"

Fix any test failures before proceeding. Common test files to check:

src/extension/agents/claude/node/test/claudeCodeAgent.spec.ts
src/extension/agents/claude/node/test/claudeCodeSessionService.spec.ts
src/extension/agents/claude/node/sessionParser/test/*.spec.ts

8. Update Documentation

If needed, update documentation in the codebase:

Update src/extension/agents/claude/AGENTS.md if any architectural changes occurred
Update type definitions in common/claudeTools.ts if tools changed
Document any new features or capabilities added
Update the "Official Claude Agent SDK Documentation" links if URLs changed

9. Commit with a Detailed Message

Create a commit message that documents the upgrade clearly. Include:

Package version changes - Both old and new versions
Features - Notable new capabilities added
Bug fixes - Important fixes included
Breaking changes - What changed and how it was addressed in the code

Example commit message:

Update Anthropic SDK packages

### `@anthropic-ai/sdk` (0.71.2 → 0.72.1)

#### Features
- Structured Outputs support in Messages API
- MCP SDK helper functions

#### Breaking Changes
- `output_format` → `output_config` parameter migration

### `@anthropic-ai/claude-agent-sdk` (0.2.5 → 0.2.31)

#### Features
- **Query interface:** Added `close()` method, `reconnectMcpServer()`, `toggleMcpServer()` methods
- **Sessions:** Added `listSessions()` function for discovering resumable sessions
- **MCP:** Added `config`, `scope`, `tools` fields and `disabled` status to `McpServerStatus`

#### Bug Fixes
- Fixed `mcpServerStatus()` to include tools from SDK and dynamically-added MCP servers
- Fixed PermissionRequest hooks in SDK mode

#### Breaking Changes
- `KillShellInput` → `TaskStopInput`: Updated type mapping in claudeTools.ts

Troubleshooting Common Issues

Type Errors After Upgrade:

Check if types were renamed (common: Message → ContentBlock, etc.)
Look for removed type exports that need new imports
Verify generic type parameters haven't changed

Session Loading Failures:

Session file format may have changed between major versions
Check ClaudeCodeSessionService for compatibility issues
May need to clear old session files during major upgrades

Hook Registration Failures:

Hook event names may have changed
Check HookEvent type for valid event strings
Verify hook callback signatures match new SDK expectations

Tool Execution Errors:

Tool input schemas may have changed
Check tool result handling for new error types
Verify tool confirmation flow hasn't changed