|
| 1 | +# Migration Plan: Unified Tool Definitions |
| 2 | + |
| 3 | +This document outlines the steps to migrate from the existing separate tool definitions in `/schema` and `/prompts/tools` to the new unified architecture in `/definitions`. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The migration involves: |
| 8 | + |
| 9 | +1. Replacing schema imports with unified definition imports |
| 10 | +2. Updating the ToolExecutor to use the new definitions |
| 11 | +3. Modifying the ToolParser to work with the unified format |
| 12 | +4. Updating tool runners to reference the new definitions |
| 13 | +5. Integrating the system prompt generator |
| 14 | + |
| 15 | +## Detailed Steps |
| 16 | + |
| 17 | +### 1. Update Tool Executor |
| 18 | + |
| 19 | +The `tool-executor.ts` file needs to be modified to use the new unified definitions: |
| 20 | + |
| 21 | +```typescript |
| 22 | +// Replace this import |
| 23 | +import { tools, writeToFileTool } from "./schema" |
| 24 | + |
| 25 | +// With this import |
| 26 | +import { toolDefinitions, writeToFileTool } from "./definitions" |
| 27 | + |
| 28 | +// Update the ToolParser initialization |
| 29 | +this.toolParser = new ToolParser( |
| 30 | + toolDefinitions.map((tool) => ({ name: tool.name, schema: tool.schema })), |
| 31 | + { |
| 32 | + onToolUpdate: this.handleToolUpdate.bind(this), |
| 33 | + onToolEnd: this.handleToolEnd.bind(this), |
| 34 | + onToolError: this.handleToolError.bind(this), |
| 35 | + } |
| 36 | +) |
| 37 | + |
| 38 | +// Make the createTool method more dynamic |
| 39 | +private createTool(params: FullToolParams<any>) { |
| 40 | + const toolName = params.name as ToolName; |
| 41 | + |
| 42 | + // Define the mapping of tool names to their implementation classes |
| 43 | + const toolImplementations = { |
| 44 | + read_file: ReadFileTool, |
| 45 | + search_files: SearchFilesTool, |
| 46 | + execute_command: ExecuteCommandTool, |
| 47 | + list_files: ListFilesTool, |
| 48 | + file_editor: FileEditorTool, |
| 49 | + ask_followup_question: AskFollowupQuestionTool, |
| 50 | + search_symbol: SearchSymbolTool, |
| 51 | + url_screenshot: UrlScreenshotTool, |
| 52 | + attempt_completion: AttemptCompletionTool, |
| 53 | + explore_repo_folder: ExploreRepoFolderTool, |
| 54 | + spawn_agent: SpawnAgentTool, |
| 55 | + exit_agent: ExitAgentTool, |
| 56 | + server_runner: ServerRunnerTool, |
| 57 | + web_search: WebSearchTool, |
| 58 | + write_to_file: WriteToFileTool, |
| 59 | + add_interested_file: AddInterestedFileTool, |
| 60 | + file_changes_plan: FileChangePlanTool, |
| 61 | + submit_review: SubmitReviewTool, |
| 62 | + reject_file_changes: RejectFileChangesTool, |
| 63 | + } as const; |
| 64 | + |
| 65 | + const ToolClass = toolImplementations[toolName]; |
| 66 | + if (!ToolClass) { |
| 67 | + throw new Error(`Unknown tool: ${params.name}`); |
| 68 | + } |
| 69 | + |
| 70 | + return new ToolClass(params, this.options); |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +### 2. Update Tool Runners |
| 75 | + |
| 76 | +Each tool runner should be updated to import its types from the new unified definitions: |
| 77 | + |
| 78 | +```typescript |
| 79 | +// Replace this import |
| 80 | +import { ReadFileToolParams } from "../schema/read_file"; |
| 81 | + |
| 82 | +// With this import |
| 83 | +import { ReadFileToolParams } from "../definitions"; |
| 84 | +``` |
| 85 | + |
| 86 | +### 3. Integrate System Prompt Generator |
| 87 | + |
| 88 | +Update the agent initialization to use the new system prompt generator: |
| 89 | + |
| 90 | +```typescript |
| 91 | +// Import the generator |
| 92 | +import { generateToolsSystemPrompt } from "../tools/utils/system-prompt-generator"; |
| 93 | + |
| 94 | +// Use it in the system prompt |
| 95 | +const systemPrompt = ` |
| 96 | +${baseSystemPrompt} |
| 97 | +
|
| 98 | +${generateToolsSystemPrompt()} |
| 99 | +
|
| 100 | +${additionalInstructions} |
| 101 | +`; |
| 102 | +``` |
| 103 | + |
| 104 | +### 4. Update Tool Parser |
| 105 | + |
| 106 | +Enhance the ToolParser to support both the standard and legacy XML formats: |
| 107 | + |
| 108 | +```typescript |
| 109 | +// Add support for both formats in the pattern matching |
| 110 | +const standardPattern = /<tool name="([^"]+)">([\s\S]*?)<\/tool>/g; |
| 111 | +const legacyPattern = /<([^>]+)>([\s\S]*?)<\/\1>/g; |
| 112 | + |
| 113 | +// Check both patterns when parsing |
| 114 | +function parseToolUse(text: string) { |
| 115 | + let match; |
| 116 | + |
| 117 | + // Try standard format first |
| 118 | + match = standardPattern.exec(text); |
| 119 | + if (match) { |
| 120 | + const [fullMatch, toolName, paramsText] = match; |
| 121 | + // Process params and return |
| 122 | + return { toolName, params, fullMatch }; |
| 123 | + } |
| 124 | + |
| 125 | + // Try legacy format as fallback |
| 126 | + match = legacyPattern.exec(text); |
| 127 | + if (match) { |
| 128 | + const [fullMatch, toolName, paramsText] = match; |
| 129 | + // Process params and return |
| 130 | + return { toolName, params, fullMatch }; |
| 131 | + } |
| 132 | + |
| 133 | + return null; |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +### 5. Phase Out Old Definitions |
| 138 | + |
| 139 | +Once the new system is in place and tested: |
| 140 | + |
| 141 | +1. Create a deprecation notice in the `/schema` and `/prompts/tools` directories |
| 142 | +2. Mark the old imports as deprecated in the codebase |
| 143 | +3. Establish a timeline for removing the old files entirely |
| 144 | + |
| 145 | +## Testing Strategy |
| 146 | + |
| 147 | +1. Create unit tests for the new unified definitions |
| 148 | +2. Test each tool with both standard and legacy XML formats |
| 149 | +3. Perform integration tests with the ToolExecutor |
| 150 | +4. Verify the system prompt generation includes all tools correctly |
| 151 | +5. Conduct end-to-end tests with the Claude agent using the new formats |
| 152 | + |
| 153 | +## Rollout Plan |
| 154 | + |
| 155 | +1. Implement the changes in a separate branch |
| 156 | +2. Review and test thoroughly |
| 157 | +3. Merge to development branch and test in the full system |
| 158 | +4. Schedule the production deployment |
| 159 | +5. Monitor for any issues after deployment |
| 160 | +6. After successful rollout, create a cleanup ticket to remove the deprecated code |
0 commit comments