diff --git a/extensions/copilot/.claude/agents/anthropic-sdk-upgrader.md b/extensions/copilot/.claude/agents/anthropic-sdk-upgrader.md new file mode 100644 index 00000000000..d5712a94008 --- /dev/null +++ b/extensions/copilot/.claude/agents/anthropic-sdk-upgrader.md @@ -0,0 +1,179 @@ +--- +name: anthropic-sdk-upgrader +description: "Use this agent when the user needs to upgrade Anthropic SDK packages. This includes: upgrading @anthropic-ai/sdk or @anthropic-ai/claude-agent-sdk to newer versions, migrating between SDK versions, resolving SDK-related dependency conflicts, updating SDK types and interfaces, or asking about SDK upgrade procedures. Examples: 'Upgrade the Anthropic SDK to the latest version', 'Help me migrate to the latest claude-agent-sdk', 'What's the process for upgrading Anthropic packages?'" +model: opus +--- + +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:** +```markdown +### `@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 + +```bash +# Update to latest +npm install @anthropic-ai/claude-agent-sdk @anthropic-ai/sdk +``` + +### 5. Fix Compilation Errors + +After updating, check for compilation errors: + +```bash +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 + +### 6. Run Tests + +After upgrading, run the Claude-related unit tests to verify nothing is broken: + +```bash +# 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` + +### 7. Update Documentation + +If needed, update documentation in the codebase: + +1. Update `src/extension/agents/claude/AGENTS.md` if any architectural changes occurred +2. Update type definitions in `common/claudeTools.ts` if tools changed +3. Document any new features or capabilities added +4. Update the "Official Claude Agent SDK Documentation" links if URLs changed + +### 8. Commit with a Detailed Message + +Create a commit message that documents the upgrade clearly. Include: + +1. **Package version changes** - Both old and new versions +2. **Features** - Notable new capabilities added +3. **Bug fixes** - Important fixes included +4. **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 diff --git a/extensions/copilot/src/extension/agents/claude/AGENTS.md b/extensions/copilot/src/extension/agents/claude/AGENTS.md index 3e6c6ff89a4..5b8e1ff7f42 100644 --- a/extensions/copilot/src/extension/agents/claude/AGENTS.md +++ b/extensions/copilot/src/extension/agents/claude/AGENTS.md @@ -310,172 +310,15 @@ The integration respects VS Code settings: ## Upgrading Anthropic SDK Packages -This section documents the process for upgrading the Anthropic SDK packages used in the Claude integration. +For the complete upgrade process, use the **anthropic-sdk-upgrader** Claude Code agent. The agent provides step-by-step guidance for upgrading `@anthropic-ai/claude-agent-sdk` and `@anthropic-ai/sdk` packages, including: -### Packages +- Checking changelogs and summarizing changes +- Categorizing changes by impact level +- Fixing compilation errors in key files +- Complete testing checklist +- Troubleshooting common issues -| 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 - -#### 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 your current version and the target version. Group changes by category, not by individual version: - -**Summary Format:** -```markdown -### `@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 - -```bash -# Update to latest -npm install @anthropic-ai/claude-agent-sdk @anthropic-ai/sdk -``` - -#### 5. Fix Compilation Errors - -After updating, check for compilation errors: - -1. Run the `start-watch-tasks` VS Code task to see real-time compilation errors -2. Address any type errors in the following key files: - - `node/claudeCodeAgent.ts` - Session and message handling - - `node/claudeCodeSdkService.ts` - SDK wrapper - - `node/claudeCodeSessionService.ts` - Session persistence - - `common/claudeTools.ts` - Tool type definitions - - `node/hooks/*.ts` - Hook implementations - - `vscode-node/slashCommands/*.ts` - Slash command handlers - - `node/toolPermissionHandlers/*.ts` - Permission handlers - -#### 6. Things to Test - -After upgrading, verify the following functionality works correctly: - -**Core Functionality:** -- [ ] Starting a new Claude chat session -- [ ] Sending messages and receiving responses -- [ ] Streaming responses render correctly in the chat UI -- [ ] Session persistence and resumption works - -**Tool Operations:** -- [ ] `Read` tool - Reading files displays content correctly -- [ ] `Edit` tool - File edits apply correctly with proper diffs -- [ ] `Write` tool - New files are created correctly -- [ ] `Bash` tool - Shell commands execute and return output -- [ ] `Glob` tool - File pattern matching works -- [ ] `Grep` tool - Content search works -- [ ] `WebFetch` tool - URL fetching works (if applicable) - -**Tool Confirmation:** -- [ ] Auto-approval works for workspace files -- [ ] Confirmation dialogs appear for dangerous operations -- [ ] Denying a tool sends appropriate message to Claude -- [ ] Tool invocation formatting displays correctly in chat - -**Hooks:** -- [ ] `PreToolUse` hooks fire before tool execution -- [ ] `PostToolUse` hooks fire after tool completion -- [ ] `SessionStart`/`SessionEnd` hooks work correctly -- [ ] Logging hooks capture expected data - -**Slash Commands:** -- [ ] `/hooks` command works -- [ ] `/memory` command works -- [ ] `/agents` command works -- [ ] (If enabled) `/terminal` command works - -**Edge Cases:** -- [ ] Cancellation during streaming works correctly -- [ ] Error handling for failed tool operations -- [ ] Large file handling -- [ ] Multi-turn conversations maintain context -- [ ] Subagent execution (if used) - -**Regression Testing:** -- [ ] Run unit tests: `npm run test:unit` (filter to claude-related tests) -- [ ] Run integration tests for the Claude agent -- [ ] Manual testing in VS Code with various prompts - -#### 7. Update Documentation - -After a successful upgrade: - -1. Update this `AGENTS.md` if any architectural changes occurred -2. Update type definitions in `common/claudeTools.ts` if tools changed -3. Document any new features or capabilities added -4. Update the "Official Claude Agent SDK Documentation" links if URLs changed - -### 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 +See `.claude/agents/anthropic-sdk-upgrader.md` for the full process. ## Dependencies