@defai.digital/ax-cli 3.8.21 → 3.8.23

package/dist/agent/llm-agent.js

@@ -1,10 +1,6 @@
 import { LLMClient } from "../llm/client.js";
 import { getAllGrokTools, getMCPManager, initializeMCPServers, } from "../llm/tools.js";
 import { loadMCPConfig } from "../mcp/config.js";
-import { TextEditorTool, BashTool, TodoTool, SearchTool, } from "../tools/index.js";
-import { BashOutputTool } from "../tools/bash-output.js";
-import { ArchitectureTool } from "../tools/analysis-tools/architecture-tool.js";
-import { ValidationTool } from "../tools/analysis-tools/validation-tool.js";
 import { EventEmitter } from "events";
 import { AGENT_CONFIG, CACHE_CONFIG, TIMEOUT_CONFIG } from "../constants.js";
 import { getTokenCounter } from "../utils/token-counter.js";
@@ -12,26 +8,37 @@ import { loadCustomInstructions } from "../utils/custom-instructions.js";
 import { getSettingsManager } from "../utils/settings-manager.js";
 import { ContextManager } from "./context-manager.js";
 import { buildSystemPrompt } from "../utils/prompt-builder.js";
-import { getUsageTracker } from "../utils/usage-tracker.js";
+// Note: getUsageTracker is now used by StreamHandler (Phase 2 refactoring)
 import { extractErrorMessage } from "../utils/error-handler.js";
 import { getCheckpointManager } from "../checkpoint/index.js";
 import { SubagentOrchestrator } from "./subagent-orchestrator.js";
 import { getTaskPlanner, isComplexRequest, } from "../planner/index.js";
+// Note: TaskPhase now used by PlanExecutor (Phase 2 refactoring)
 import { PLANNER_CONFIG } from "../constants.js";
 import { resolveMCPReferences, extractMCPReferences } from "../mcp/resources.js";
 import { SDKError, SDKErrorCode } from "../sdk/errors.js";
 import { getStatusReporter } from "./status-reporter.js";
 import { getLoopDetector, resetLoopDetector } from "./loop-detector.js";
+// Import from extracted modules (Phase 2 refactoring)
+import { ToolExecutor } from "./execution/index.js";
+import { StreamHandler } from "./streaming/index.js";
+import { PlanExecutor } from "./planning/index.js";
+/** Debug flag for loop detection logging (set DEBUG_LOOP_DETECTION=1 to enable) */
+const DEBUG_LOOP = process.env.DEBUG_LOOP_DETECTION === '1';
+/** Log debug message for loop detection (only when DEBUG_LOOP_DETECTION=1) */
+function debugLoop(message) {
+    if (DEBUG_LOOP) {
+        console.error(`[LOOP DETECTION] ${message}`);
+    }
+}
 export class LLMAgent extends EventEmitter {
     llmClient;
-    textEditor;
-    bash;
-    bashOutput;
-    todoTool;
-    search;
-    // Lazy-loaded tools (rarely used)
-    _architectureTool;
-    _validationTool;
+    // Tool execution delegated to ToolExecutor (Phase 2 refactoring)
+    toolExecutor;
+    // Stream processing delegated to StreamHandler (Phase 2 refactoring)
+    streamHandler;
+    // Plan execution delegated to PlanExecutor (Phase 2 refactoring)
+    planExecutor;
     chatHistory = [];
     messages = [];
     tokenCounter;
@@ -69,39 +76,52 @@ export class LLMAgent extends EventEmitter {
         }
         this.maxToolRounds = maxToolRounds || 400;
         this.llmClient = new LLMClient(apiKey, modelToUse, baseURL);
-        this.textEditor = new TextEditorTool();
-        this.bash = new BashTool();
-        this.bashOutput = new BashOutputTool();
-        this.todoTool = new TodoTool();
-        this.search = new SearchTool();
-        // architectureTool and validationTool are lazy-loaded (see getters below)
+        // Initialize ToolExecutor with checkpoint callback (Phase 2 refactoring)
+        this.toolExecutor = new ToolExecutor({
+            checkpointCallback: async (files, description) => {
+                // BUG FIX: Check if agent is disposed before creating checkpoint
+                if (this.disposed)
+                    return;
+                // Create immutable snapshot of chat history at callback time
+                const chatHistorySnapshot = JSON.parse(JSON.stringify(this.chatHistory));
+                await this.checkpointManager.createCheckpoint({
+                    files,
+                    conversationState: chatHistorySnapshot,
+                    description,
+                    metadata: {
+                        model: this.llmClient.getCurrentModel(),
+                        triggeredBy: 'auto',
+                    },
+                });
+            },
+        });
+        // Initialize StreamHandler with callbacks (Phase 2 refactoring)
+        this.streamHandler = new StreamHandler({
+            isCancelled: () => this.isCancelled(),
+            yieldCancellation: () => this.yieldCancellation(),
+            model: modelToUse,
+        });
         this.tokenCounter = getTokenCounter(modelToUse);
         this.contextManager = new ContextManager({ model: modelToUse });
         this.checkpointManager = getCheckpointManager();
         this.subagentOrchestrator = new SubagentOrchestrator({ maxConcurrentAgents: 5 });
         this.taskPlanner = getTaskPlanner();
+        // Initialize PlanExecutor with callbacks (Phase 2 refactoring)
+        this.planExecutor = new PlanExecutor({
+            llmClient: this.llmClient,
+            tokenCounter: this.tokenCounter,
+            toolExecutor: this.toolExecutor,
+            getTools: () => getAllGrokTools(),
+            executeTool: (toolCall) => this.executeTool(toolCall),
+            parseToolArgumentsCached: (toolCall) => this.parseToolArgumentsCached(toolCall),
+            buildChatOptions: (options) => this.buildChatOptions(options),
+            applyContextPruning: () => this.applyContextPruning(),
+            emitter: this,
+            maxToolRounds: Math.min(this.maxToolRounds, 50),
+            setPlanningEnabled: (enabled) => { this.planningEnabled = enabled; },
+        });
         // Load sampling configuration from settings (supports env vars, project, and user settings)
         this.samplingConfig = manager.getSamplingSettings();
-        // Wire up checkpoint callback for automatic checkpoint creation
-        // CRITICAL FIX: Deep clone chatHistory to prevent race conditions
-        // The checkpoint creation is async and chatHistory can be modified during the operation
-        this.textEditor.setCheckpointCallback(async (files, description) => {
-            // Create immutable snapshot of chat history at callback time
-            // This prevents inconsistencies if messages are added during checkpoint creation
-            // BUG FIX: Check if agent is disposed before creating checkpoint
-            if (this.disposed)
-                return;
-            const chatHistorySnapshot = JSON.parse(JSON.stringify(this.chatHistory));
-            await this.checkpointManager.createCheckpoint({
-                files,
-                conversationState: chatHistorySnapshot,
-                description,
-                metadata: {
-                    model: this.llmClient.getCurrentModel(),
-                    triggeredBy: 'auto',
-                },
-            });
-        });
         // Initialize checkpoint manager
         this.initializeCheckpointManager();
         // Initialize MCP servers if configured
@@ -142,42 +162,41 @@ export class LLMAgent extends EventEmitter {
         };
         this.contextManager.on('before_prune', this.contextOverflowListener);
     }
-    initializeCheckpointManager() {
-        // Initialize checkpoint manager in the background
+    /**
+     * Run an async task in background with proper error handling
+     * Centralizes the common pattern of background initialization
+     */
+    runBackgroundTask(taskName, task, options) {
         Promise.resolve().then(async () => {
             try {
-                await this.checkpointManager.initialize();
-                this.emit('system', 'Checkpoint system initialized');
+                await task();
+                if (options?.emitSuccess) {
+                    this.emit('system', options.emitSuccess);
+                }
             }
             catch (error) {
                 const errorMsg = extractErrorMessage(error);
-                console.warn("Checkpoint initialization failed:", errorMsg);
-                this.emit('system', `Checkpoint initialization failed: ${errorMsg}`);
+                if (options?.warnOnError !== false) {
+                    console.warn(`${taskName} failed:`, errorMsg);
+                }
+                this.emit('system', `${taskName} failed: ${errorMsg}`);
             }
         }).catch((error) => {
-            const errorMsg = extractErrorMessage(error);
-            console.warn("Unexpected error during checkpoint initialization:", errorMsg);
+            console.error(`Unexpected error during ${taskName}:`, error);
         });
     }
+    initializeCheckpointManager() {
+        this.runBackgroundTask('Checkpoint initialization', async () => {
+            await this.checkpointManager.initialize();
+        }, { emitSuccess: 'Checkpoint system initialized' });
+    }
     async initializeMCP() {
-        // Initialize MCP in the background without blocking
-        Promise.resolve().then(async () => {
-            try {
-                const config = loadMCPConfig();
-                if (config.servers.length > 0) {
-                    await initializeMCPServers();
-                    this.emit('system', 'MCP servers initialized successfully');
-                }
-            }
-            catch (error) {
-                const errorMsg = extractErrorMessage(error);
-                console.warn("MCP initialization failed:", errorMsg);
-                this.emit('system', `MCP initialization failed: ${errorMsg}`);
-            }
-        }).catch((error) => {
-            // Catch any errors from emit() or other unexpected failures
-            console.error("Unexpected MCP initialization error:", error);
-        });
+        const config = loadMCPConfig();
+        if (config.servers.length === 0)
+            return; // Skip if no servers configured
+        this.runBackgroundTask('MCP initialization', async () => {
+            await initializeMCPServers();
+        }, { emitSuccess: 'MCP servers initialized successfully', warnOnError: true });
     }
     /**
      * Build chat options with sampling and thinking configuration included
@@ -391,26 +410,6 @@ export class LLMAgent extends EventEmitter {
             return {};
         }
     }
-    /**
-     * Lazy-loaded getter for ArchitectureTool
-     * Only instantiates when first accessed to reduce startup time
-     */
-    get architectureTool() {
-        if (!this._architectureTool) {
-            this._architectureTool = new ArchitectureTool();
-        }
-        return this._architectureTool;
-    }
-    /**
-     * Lazy-loaded getter for ValidationTool
-     * Only instantiates when first accessed to reduce startup time
-     */
-    get validationTool() {
-        if (!this._validationTool) {
-            this._validationTool = new ValidationTool();
-        }
-        return this._validationTool;
-    }
     /**
      * Detect if a tool call is repetitive (likely causing a loop)
      * Uses the intelligent LoopDetector which provides:
@@ -427,32 +426,21 @@ export class LLMAgent extends EventEmitter {
         const detector = getLoopDetector();
         const result = detector.checkForLoop(toolCall);
         // Debug logging
-        if (process.env.DEBUG_LOOP_DETECTION === '1') {
-            console.error(`[LOOP DETECTION] Tool: ${toolCall.function.name}`);
-            console.error(`[LOOP DETECTION] Count: ${result.count}`);
-            console.error(`[LOOP DETECTION] Threshold: ${result.threshold}`);
-            console.error(`[LOOP DETECTION] Is Loop: ${result.isLoop}`);
-            if (result.reason) {
-                console.error(`[LOOP DETECTION] Reason: ${result.reason}`);
-            }
-            const stats = detector.getStats();
-            console.error(`[LOOP DETECTION] Stats: ${JSON.stringify(stats)}`);
-        }
+        debugLoop(`Tool: ${toolCall.function.name}`);
+        debugLoop(`Count: ${result.count}, Threshold: ${result.threshold}, Is Loop: ${result.isLoop}`);
+        if (result.reason)
+            debugLoop(`Reason: ${result.reason}`);
+        if (DEBUG_LOOP)
+            debugLoop(`Stats: ${JSON.stringify(detector.getStats())}`);
         if (result.isLoop) {
             // Store the result for generating better error message
             this.lastLoopResult = result;
-            if (process.env.DEBUG_LOOP_DETECTION === '1') {
-                console.error(`[LOOP DETECTION] ⚠️ LOOP DETECTED!`);
-                console.error(`[LOOP DETECTION] Reason: ${result.reason}`);
-                console.error(`[LOOP DETECTION] Suggestion: ${result.suggestion}`);
-            }
+            debugLoop(`⚠️ LOOP DETECTED! Reason: ${result.reason}, Suggestion: ${result.suggestion}`);
             return true;
         }
         // Note: We don't record here - recording happens AFTER execution
         // in executeToolCalls() with the actual success/failure status
-        if (process.env.DEBUG_LOOP_DETECTION === '1') {
-            console.error(`[LOOP DETECTION] ✅ Allowed, count: ${result.count}/${result.threshold}`);
-        }
+        debugLoop(`✅ Allowed, count: ${result.count}/${result.threshold}`);
         return false;
     }
     /** Last loop detection result for error messages */
@@ -461,10 +449,9 @@ export class LLMAgent extends EventEmitter {
      * Reset the tool call tracking (called at start of new user message)
      */
     resetToolCallTracking() {
-        if (process.env.DEBUG_LOOP_DETECTION === '1') {
-            const detector = getLoopDetector();
-            const stats = detector.getStats();
-            console.error(`[LOOP TRACKING] 🔄 Resetting tool call tracking (had ${stats.uniqueSignatures} signatures)`);
+        if (DEBUG_LOOP) {
+            const stats = getLoopDetector().getStats();
+            debugLoop(`🔄 Resetting tool call tracking (had ${stats.uniqueSignatures} signatures)`);
         }
         // Reset the new intelligent loop detector
         resetLoopDetector();
@@ -511,140 +498,6 @@ export class LLMAgent extends EventEmitter {
     getCurrentPlan() {
         return this.currentPlan;
     }
-    /**
-     * Execute a single phase using the LLM
-     */
-    async executePhase(phase, context) {
-        const startTime = Date.now();
-        const startTokens = this.tokenCounter.countMessageTokens(this.messages);
-        const filesModified = [];
-        let lastAssistantContent = "";
-        // Emit phase started event
-        this.emit("phase:started", { phase, planId: context.planId });
-        try {
-            // Build phase-specific prompt
-            const phasePrompt = this.buildPhasePrompt(phase, context);
-            // Execute through normal message processing (without recursively planning)
-            const savedPlanningState = this.planningEnabled;
-            this.planningEnabled = false; // Temporarily disable planning for phase execution
-            // Add phase context to messages
-            this.messages.push({
-                role: "user",
-                content: phasePrompt,
-            });
-            // Execute using the standard tool loop
-            const tools = await getAllGrokTools();
-            let toolRounds = 0;
-            const maxPhaseRounds = Math.min(this.maxToolRounds, 50); // Limit per phase
-            while (toolRounds < maxPhaseRounds) {
-                const response = await this.llmClient.chat(this.messages, tools, this.buildChatOptions());
-                const assistantMessage = response.choices[0]?.message;
-                if (!assistantMessage)
-                    break;
-                // Capture the assistant's content for phase output
-                if (assistantMessage.content) {
-                    lastAssistantContent = assistantMessage.content;
-                }
-                // Add to messages
-                this.messages.push({
-                    role: "assistant",
-                    content: assistantMessage.content || "",
-                    tool_calls: assistantMessage.tool_calls,
-                });
-                // Check for tool calls
-                if (!assistantMessage.tool_calls || assistantMessage.tool_calls.length === 0) {
-                    break; // No more tool calls, phase complete
-                }
-                toolRounds++;
-                // Execute tools and track file modifications
-                for (const toolCall of assistantMessage.tool_calls) {
-                    const result = await this.executeTool(toolCall);
-                    // Track file modifications from text_editor tool
-                    if (toolCall.function.name === "text_editor" ||
-                        toolCall.function.name === "str_replace_editor") {
-                        const args = this.parseToolArgumentsCached(toolCall);
-                        if (args.path && result.success) {
-                            if (!filesModified.includes(args.path)) {
-                                filesModified.push(args.path);
-                            }
-                        }
-                    }
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: toolCall.id,
-                        content: result.output || result.error || "No output",
-                    });
-                }
-            }
-            // Restore planning state
-            this.planningEnabled = savedPlanningState;
-            // Prune context if configured
-            if (PLANNER_CONFIG.PRUNE_AFTER_PHASE) {
-                this.applyContextPruning();
-            }
-            const endTokens = this.tokenCounter.countMessageTokens(this.messages);
-            const duration = Date.now() - startTime;
-            // Build meaningful output
-            const output = lastAssistantContent ||
-                `Phase "${phase.name}" completed (${toolRounds} tool rounds, ${filesModified.length} files modified)`;
-            // Emit phase completed event
-            this.emit("phase:completed", {
-                phase,
-                planId: context.planId,
-                result: { success: true, output, filesModified }
-            });
-            return {
-                phaseId: phase.id,
-                success: true,
-                output,
-                duration,
-                tokensUsed: endTokens - startTokens,
-                filesModified,
-                wasRetry: false,
-                retryAttempt: 0,
-            };
-        }
-        catch (error) {
-            const duration = Date.now() - startTime;
-            const errorMessage = extractErrorMessage(error);
-            // Emit phase failed event
-            this.emit("phase:failed", {
-                phase,
-                planId: context.planId,
-                error: errorMessage
-            });
-            return {
-                phaseId: phase.id,
-                success: false,
-                error: errorMessage,
-                duration,
-                tokensUsed: 0,
-                filesModified,
-                wasRetry: false,
-                retryAttempt: 0,
-            };
-        }
-    }
-    /**
-     * Build a prompt for phase execution
-     */
-    buildPhasePrompt(phase, context) {
-        let prompt = `## Phase ${phase.index + 1}: ${phase.name}\n\n`;
-        prompt += `**Objective:** ${phase.description}\n\n`;
-        if (phase.objectives.length > 0) {
-            prompt += "**Tasks to complete:**\n";
-            for (const obj of phase.objectives) {
-                prompt += `- ${obj}\n`;
-            }
-            prompt += "\n";
-        }
-        if (context.completedPhases.length > 0) {
-            prompt += `**Previously completed phases:** ${context.completedPhases.join(", ")}\n\n`;
-        }
-        prompt += `**Original request:** ${context.originalRequest}\n\n`;
-        prompt += "Please complete this phase. Focus only on the objectives listed above.";
-        return prompt;
-    }
     /**
      * Generate and execute a plan for a complex request
      * Uses TodoWrite for Claude Code-style seamless progress display
@@ -702,7 +555,7 @@ export class LLMAgent extends EventEmitter {
                         phase.riskLevel === "low" ? "low" : "medium",
                 }));
                 try {
-                    await this.todoTool.createTodoList(todoItems);
+                    await this.toolExecutor.getTodoTool().createTodoList(todoItems);
                 }
                 catch (todoError) {
                     // TodoWrite failure is non-critical, continue execution
@@ -713,7 +566,7 @@ export class LLMAgent extends EventEmitter {
                 // Display explicit plan summary
                 yield {
                     type: "content",
-                    content: this.formatPlanSummary(plan),
+                    content: this.planExecutor.formatPlanSummary(plan),
                 };
             }
             // Execute phases one by one with progress updates
@@ -726,7 +579,7 @@ export class LLMAgent extends EventEmitter {
                 if (PLANNER_CONFIG.SILENT_MODE) {
                     // Update TodoWrite: mark current phase as in_progress
                     try {
-                        await this.todoTool.updateTodoList([{
+                        await this.toolExecutor.getTodoTool().updateTodoList([{
                                 id: `phase-${i}`,
                                 status: "in_progress",
                             }]);
@@ -740,13 +593,14 @@ export class LLMAgent extends EventEmitter {
                         content: `\n**⏳ Phase ${i + 1}/${plan.phases.length}: ${phase.name}**\n`,
                     };
                 }
-                // Execute the phase
+                // Execute the phase (delegated to PlanExecutor - Phase 2 refactoring)
                 const context = {
                     planId: plan.id,
                     originalRequest: message,
                     completedPhases: phaseResults.filter(r => r.success).map(r => r.phaseId),
                 };
-                const result = await this.executePhase(phase, context);
+                const { result, messages: updatedMessages } = await this.planExecutor.executePhase(phase, context, this.messages, this.chatHistory);
+                this.messages = updatedMessages; // Update messages with phase execution results
                 phaseResults.push(result);
                 totalTokensUsed += result.tokensUsed;
                 // Report phase result
@@ -754,7 +608,7 @@ export class LLMAgent extends EventEmitter {
                     if (PLANNER_CONFIG.SILENT_MODE) {
                         // Update TodoWrite: mark phase as completed
                         try {
-                            await this.todoTool.updateTodoList([{
+                            await this.toolExecutor.getTodoTool().updateTodoList([{
                                     id: `phase-${i}`,
                                     status: "completed",
                                 }]);
@@ -778,7 +632,7 @@ export class LLMAgent extends EventEmitter {
                     if (PLANNER_CONFIG.SILENT_MODE) {
                         // Update TodoWrite: mark phase as failed (update content to show failure)
                         try {
-                            await this.todoTool.updateTodoList([{
+                            await this.toolExecutor.getTodoTool().updateTodoList([{
                                     id: `phase-${i}`,
                                     status: "completed", // Mark as done even if failed
                                     content: `${phase.name} (failed)`,
@@ -829,7 +683,7 @@ export class LLMAgent extends EventEmitter {
             if (!PLANNER_CONFIG.SILENT_MODE) {
                 yield {
                     type: "content",
-                    content: this.formatPlanResult(planResult),
+                    content: this.planExecutor.formatPlanResult(planResult),
                 };
             }
             else {
@@ -925,8 +779,12 @@ export class LLMAgent extends EventEmitter {
                 const stream = this.llmClient.chatStream(this.messages, tools, this.buildChatOptions({
                     searchOptions: { search_parameters: { mode: "off" } }
                 }));
-                // Process streaming chunks
-                const chunkGen = this.processStreamingChunks(stream, inputTokensRef.value, lastTokenUpdateRef, totalOutputTokensRef);
+                // Process streaming chunks (delegated to StreamHandler - Phase 2 refactoring)
+                const chunkGen = this.streamHandler.processChunks(stream, {
+                    inputTokens: inputTokensRef.value,
+                    lastTokenUpdate: lastTokenUpdateRef,
+                    totalOutputTokens: totalOutputTokensRef,
+                });
                 let streamResult;
                 for await (const chunk of chunkGen) {
                     if ('accumulated' in chunk) {
@@ -977,41 +835,6 @@ export class LLMAgent extends EventEmitter {
         };
         yield { type: "done" };
     }
-    /**
-     * Format plan summary for display
-     */
-    formatPlanSummary(plan) {
-        let output = `**📋 Execution Plan Created**\n\n`;
-        output += `**Request:** ${plan.originalPrompt.slice(0, 100)}${plan.originalPrompt.length > 100 ? "..." : ""}\n\n`;
-        output += `**Phases (${plan.phases.length}):**\n`;
-        for (const phase of plan.phases) {
-            const riskIcon = phase.riskLevel === "high" ? "⚠️" : phase.riskLevel === "medium" ? "△" : "";
-            output += `  ${phase.index + 1}. ${phase.name} ${riskIcon}\n`;
-        }
-        output += `\n**Estimated Duration:** ~${Math.ceil(plan.estimatedDuration / 60000)} min\n\n`;
-        output += "---\n\n";
-        return output;
-    }
-    /**
-     * Format plan result for display
-     */
-    formatPlanResult(result) {
-        let output = "\n---\n\n**📋 Plan Execution Complete**\n\n";
-        const successful = result.phaseResults.filter((r) => r.success).length;
-        const failed = result.phaseResults.filter((r) => !r.success).length;
-        output += `**Results:** ${successful}/${result.phaseResults.length} phases successful`;
-        if (failed > 0) {
-            output += ` (${failed} failed)`;
-        }
-        output += "\n";
-        if (result.totalDuration) {
-            output += `**Duration:** ${Math.ceil(result.totalDuration / 1000)}s\n`;
-        }
-        if (result.totalTokensUsed) {
-            output += `**Tokens Used:** ${result.totalTokensUsed.toLocaleString()}\n`;
-        }
-        return output;
-    }
     async processUserMessage(message) {
         // Check if agent has been disposed
         this.checkDisposed();
@@ -1057,17 +880,11 @@ export class LLMAgent extends EventEmitter {
                     assistantMessage.tool_calls.length > 0) {
                     toolRounds++;
                     // Check for repetitive tool calls (loop detection)
-                    if (process.env.DEBUG_LOOP_DETECTION === '1') {
-                        console.error(`\n[LOOP CHECK] Checking ${assistantMessage.tool_calls.length} tool calls...`);
-                    }
+                    debugLoop(`Checking ${assistantMessage.tool_calls.length} tool calls...`);
                     const hasRepetitiveCall = assistantMessage.tool_calls.some((tc) => this.isRepetitiveToolCall(tc));
-                    if (process.env.DEBUG_LOOP_DETECTION === '1') {
-                        console.error(`[LOOP CHECK] hasRepetitiveCall: ${hasRepetitiveCall}\n`);
-                    }
+                    debugLoop(`hasRepetitiveCall: ${hasRepetitiveCall}`);
                     if (hasRepetitiveCall) {
-                        if (process.env.DEBUG_LOOP_DETECTION === '1') {
-                            console.error(`[LOOP CHECK] 🛑 Breaking loop!`);
-                        }
+                        debugLoop(`🛑 Breaking loop!`);
                         const loopMsg = this.getLoopWarningMessage();
                         const warningEntry = {
                             type: "assistant",
@@ -1119,9 +936,7 @@ export class LLMAgent extends EventEmitter {
                             const updatedEntry = {
                                 ...this.chatHistory[entryIndex],
                                 type: "tool_result",
-                                content: result.success
-                                    ? result.output || "Success"
-                                    : result.error || "Error occurred",
+                                content: this.formatToolResultContent(result),
                                 toolResult: result,
                             };
                             this.chatHistory[entryIndex] = updatedEntry;
@@ -1135,9 +950,7 @@ export class LLMAgent extends EventEmitter {
                         // Add tool result to messages with proper format (needed for AI context)
                         this.messages.push({
                             role: "tool",
-                            content: result.success
-                                ? result.output || "Success"
-                                : result.error || "Error",
+                            content: this.formatToolResultContent(result, "Success", "Error"),
                             tool_call_id: toolCall.id,
                         });
                     }
@@ -1188,67 +1001,6 @@ export class LLMAgent extends EventEmitter {
             return [userEntry, errorEntry];
         }
     }
-    /**
-     * Optimized streaming delta merge - mutates accumulator for performance
-     * This is safe because accumulator is only used internally during streaming
-     *
-     * Performance: 50% faster than immutable approach (no object copying)
-     */
-    reduceStreamDelta(acc, delta) {
-        for (const [key, value] of Object.entries(delta)) {
-            if (value === undefined || value === null) {
-                continue; // Skip undefined/null values
-            }
-            if (acc[key] === undefined || acc[key] === null) {
-                // Initial value assignment
-                acc[key] = value;
-                // Clean up index properties from tool calls
-                if (Array.isArray(acc[key])) {
-                    for (const arr of acc[key]) {
-                        if (arr && typeof arr === 'object') {
-                            delete arr.index;
-                        }
-                    }
-                }
-            }
-            else if (typeof acc[key] === "string" && typeof value === "string") {
-                // String concatenation (most common case during streaming)
-                acc[key] += value;
-            }
-            else if (Array.isArray(acc[key]) && Array.isArray(value)) {
-                // Array merging (for tool calls)
-                const accArray = acc[key];
-                for (let i = 0; i < value.length; i++) {
-                    if (value[i] === undefined || value[i] === null)
-                        continue;
-                    if (!accArray[i]) {
-                        accArray[i] = {};
-                    }
-                    // Recursively merge array elements
-                    this.reduceStreamDelta(accArray[i], value[i]);
-                }
-            }
-            else if (typeof acc[key] === "object" && typeof value === "object") {
-                // Object merging
-                this.reduceStreamDelta(acc[key], value);
-            }
-            else {
-                // Direct assignment for other types
-                acc[key] = value;
-            }
-        }
-        return acc;
-    }
-    /**
-     * Accumulate streaming message chunks
-     */
-    messageReducer(previous, item) {
-        // Safety check: ensure item has valid structure
-        if (!item?.choices || item.choices.length === 0 || !item.choices[0]?.delta) {
-            return previous;
-        }
-        return this.reduceStreamDelta(previous, item.choices[0].delta);
-    }
     /**
      * Prepare user message and apply context management
      * Returns the calculated input tokens
@@ -1312,111 +1064,18 @@ export class LLMAgent extends EventEmitter {
         }
     }
     /**
-     * Process streaming chunks and accumulate message
+     * Format tool result content for display or message
+     * Centralizes the common pattern of formatting success/error output
+     *
+     * @param result - Tool execution result
+     * @param defaultSuccess - Default message if success but no output (default: "Success")
+     * @param defaultError - Default message if error but no error message (default: "Error occurred")
+     * @returns Formatted content string
      */
-    async *processStreamingChunks(stream, inputTokens, lastTokenUpdate, totalOutputTokens) {
-        let accumulatedMessage = {};
-        let accumulatedContent = "";
-        let toolCallsYielded = false;
-        let usageData = null;
-        // CRITICAL FIX: Ensure stream is properly closed on cancellation or error
-        // Without this, HTTP connections and buffers remain in memory
-        try {
-            for await (const chunk of stream) {
-                // Check for cancellation in the streaming loop
-                if (this.isCancelled()) {
-                    yield* this.yieldCancellation();
-                    // Return empty state after cancellation to avoid processing partial results
-                    return { accumulated: {}, content: "", yielded: false };
-                }
-                if (!chunk.choices?.[0])
-                    continue;
-                // Capture usage data from chunks (usually in the final chunk)
-                if (chunk.usage) {
-                    usageData = chunk.usage;
-                }
-                // Accumulate the message using reducer
-                accumulatedMessage = this.messageReducer(accumulatedMessage, chunk);
-                // Check for tool calls - yield when we have complete tool calls with function names
-                const toolCalls = accumulatedMessage.tool_calls;
-                if (!toolCallsYielded && toolCalls && Array.isArray(toolCalls) && toolCalls.length > 0) {
-                    const hasCompleteTool = toolCalls.some((tc) => tc.function?.name);
-                    if (hasCompleteTool) {
-                        yield {
-                            type: "tool_calls",
-                            toolCalls: toolCalls,
-                        };
-                        toolCallsYielded = true;
-                    }
-                }
-                // Stream reasoning content (GLM-4.6 thinking mode)
-                // Safety check: ensure choices[0] exists before accessing
-                if (chunk.choices[0]?.delta?.reasoning_content) {
-                    yield {
-                        type: "reasoning",
-                        reasoningContent: chunk.choices[0].delta.reasoning_content,
-                    };
-                }
-                // Stream content as it comes
-                if (chunk.choices[0]?.delta?.content) {
-                    accumulatedContent += chunk.choices[0].delta.content;
-                    yield {
-                        type: "content",
-                        content: chunk.choices[0].delta.content,
-                    };
-                    // Emit token count update (throttled and optimized)
-                    const now = Date.now();
-                    if (now - lastTokenUpdate.value > 1000) { // Increased throttle to 1s for better performance
-                        lastTokenUpdate.value = now;
-                        // Use fast estimation during streaming (4 chars ≈ 1 token)
-                        // This is ~70% faster than tiktoken encoding
-                        const estimatedOutputTokens = Math.floor(accumulatedContent.length / 4) +
-                            (accumulatedMessage.tool_calls
-                                ? Math.floor(JSON.stringify(accumulatedMessage.tool_calls).length / 4)
-                                : 0);
-                        totalOutputTokens.value = estimatedOutputTokens;
-                        yield {
-                            type: "token_count",
-                            tokenCount: inputTokens + estimatedOutputTokens,
-                        };
-                    }
-                }
-            }
-            // Track usage if available and emit accurate final token count
-            if (usageData) {
-                const tracker = getUsageTracker();
-                tracker.trackUsage(this.llmClient.getCurrentModel(), usageData);
-                // Emit accurate token count from API usage data (replaces estimation)
-                const totalTokens = usageData.total_tokens;
-                const completionTokens = usageData.completion_tokens;
-                if (totalTokens) {
-                    totalOutputTokens.value = completionTokens || 0;
-                    yield {
-                        type: "token_count",
-                        tokenCount: totalTokens,
-                    };
-                }
-            }
-            // CRITICAL: Yield the accumulated result so the main loop can access it!
-            const result = { accumulated: accumulatedMessage, content: accumulatedContent, yielded: toolCallsYielded };
-            yield result;
-            return result;
-        }
-        finally {
-            // CRITICAL FIX: Properly close the async iterator to release HTTP connections and buffers
-            // This prevents socket leaks when streams are cancelled or errors occur
-            try {
-                // Use a type assertion to safely access the return method
-                const streamWithReturn = stream;
-                if (typeof streamWithReturn.return === 'function') {
-                    await streamWithReturn.return();
-                }
-            }
-            catch (cleanupError) {
-                // Log but don't throw - cleanup errors shouldn't break the flow
-                console.warn('Stream cleanup warning:', cleanupError);
-            }
-        }
+    formatToolResultContent(result, defaultSuccess = "Success", defaultError = "Error occurred") {
+        return result.success
+            ? result.output || defaultSuccess
+            : result.error || defaultError;
     }
     /**
      * Add assistant message to history and conversation
@@ -1468,14 +1127,10 @@ export class LLMAgent extends EventEmitter {
             // This enables failure-based threshold adjustment (repeated failures = lower threshold)
             const detector = getLoopDetector();
             detector.recordToolCall(toolCall, result.success);
-            if (process.env.DEBUG_LOOP_DETECTION === '1') {
-                console.error(`[LOOP DETECTION] 📝 Recorded: ${toolCall.function.name}, success=${result.success}`);
-            }
+            debugLoop(`📝 Recorded: ${toolCall.function.name}, success=${result.success}`);
             const toolResultEntry = {
                 type: "tool_result",
-                content: result.success
-                    ? result.output || "Success"
-                    : result.error || "Error occurred",
+                content: this.formatToolResultContent(result),
                 timestamp: new Date(),
                 toolCall: toolCall,
                 toolResult: result,
@@ -1491,9 +1146,7 @@ export class LLMAgent extends EventEmitter {
             // Add tool result with proper format (needed for AI context)
             this.messages.push({
                 role: "tool",
-                content: result.success
-                    ? result.output || "Success"
-                    : result.error || "Error",
+                content: this.formatToolResultContent(result, "Success", "Error"),
                 tool_call_id: toolCall.id,
             });
         }
@@ -1534,9 +1187,7 @@ export class LLMAgent extends EventEmitter {
         try {
             // Agent loop - continue until no more tool calls or max rounds reached
             while (toolRounds < maxToolRounds) {
-                if (process.env.DEBUG_LOOP_DETECTION === '1') {
-                    console.error(`\n[LOOP DEBUG] Agent loop iteration, toolRounds: ${toolRounds}`);
-                }
+                debugLoop(`Agent loop iteration, toolRounds: ${toolRounds}`);
                 // Check if operation was cancelled
                 if (this.isCancelled()) {
                     yield* this.yieldCancellation();
@@ -1555,8 +1206,12 @@ export class LLMAgent extends EventEmitter {
                 const stream = this.llmClient.chatStream(this.messages, tools, this.buildChatOptions({
                     searchOptions: { search_parameters: { mode: "off" } }
                 }));
-                // Process streaming chunks
-                const chunkGen = this.processStreamingChunks(stream, inputTokensRef.value, lastTokenUpdateRef, totalOutputTokensRef);
+                // Process streaming chunks (delegated to StreamHandler - Phase 2 refactoring)
+                const chunkGen = this.streamHandler.processChunks(stream, {
+                    inputTokens: inputTokensRef.value,
+                    lastTokenUpdate: lastTokenUpdateRef,
+                    totalOutputTokens: totalOutputTokensRef,
+                });
                 let streamResult;
                 for await (const chunk of chunkGen) {
                     if ('accumulated' in chunk) {
@@ -1626,237 +1281,56 @@ export class LLMAgent extends EventEmitter {
         }
     }
     /**
-     * Parse and validate tool call arguments
-     * @param toolCall The tool call to parse arguments from
-     * @param toolType Type of tool (for error messages)
-     * @returns Parsed arguments or error result
+     * Execute a tool call using the ToolExecutor
+     * Handles tool approval for VSCode integration before delegation
      */
-    parseToolArguments(toolCall, toolType = 'Tool') {
-        const argsString = toolCall.function.arguments;
-        if (!argsString || typeof argsString !== 'string' || argsString.trim() === '') {
-            return {
-                success: false,
-                error: `${toolType} ${toolCall.function.name} called with empty arguments`,
-            };
-        }
-        try {
-            const args = JSON.parse(argsString);
-            // Validate that args is an object (not null, array, or primitive)
-            if (typeof args !== 'object' || args === null || Array.isArray(args)) {
-                return {
-                    success: false,
-                    error: `${toolType} ${toolCall.function.name} arguments must be a JSON object, got ${Array.isArray(args) ? 'array' : typeof args}`,
-                };
-            }
-            return { success: true, args };
-        }
-        catch (error) {
-            return {
-                success: false,
-                error: `Failed to parse ${toolType} arguments: ${error instanceof Error ? error.message : 'Invalid JSON'}`,
-            };
-        }
-    }
     async executeTool(toolCall) {
-        try {
-            const parseResult = this.parseToolArguments(toolCall, 'Tool');
-            if (!parseResult.success) {
-                return { success: false, error: parseResult.error };
-            }
-            const args = parseResult.args;
-            // Check if tool approval is required (for VSCode integration)
-            if (this.requireToolApproval) {
-                // Only require approval for file modification operations
-                const needsApproval = toolCall.function.name === "create_file" ||
-                    toolCall.function.name === "str_replace_editor" ||
-                    toolCall.function.name === "insert_text";
-                if (needsApproval) {
-                    // Emit event and wait for approval
-                    const approved = await this.waitForToolApproval(toolCall);
-                    if (!approved) {
-                        // User rejected the change
-                        this.emit('tool:rejected', toolCall);
-                        return {
-                            success: false,
-                            error: 'Change rejected by user'
-                        };
-                    }
-                    // User approved
-                    this.emit('tool:approved', toolCall);
-                }
-            }
-            // Helper to safely get string argument with validation
-            const getString = (key, required = true) => {
-                const value = args[key];
-                if (typeof value !== 'string') {
-                    if (required)
-                        throw new Error(`Tool argument '${key}' must be a string, got ${typeof value}`);
-                    return '';
-                }
-                return value;
-            };
-            // Helper to safely get number argument
-            const getNumber = (key) => {
-                const value = args[key];
-                if (value === undefined || value === null)
-                    return undefined;
-                if (typeof value !== 'number')
-                    return undefined;
-                return value;
-            };
-            // Helper to safely get boolean argument
-            const getBoolean = (key) => {
-                const value = args[key];
-                if (value === undefined || value === null)
-                    return undefined;
-                if (typeof value !== 'boolean')
-                    return undefined;
-                return value;
-            };
-            switch (toolCall.function.name) {
-                case "view_file":
-                    const startLine = getNumber('start_line');
-                    const endLine = getNumber('end_line');
-                    const range = startLine !== undefined && endLine !== undefined
-                        ? [startLine, endLine]
-                        : undefined;
-                    return await this.textEditor.view(getString('path'), range);
-                case "create_file":
-                    return await this.textEditor.create(getString('path'), getString('content'));
-                case "str_replace_editor":
-                    return await this.textEditor.strReplace(getString('path'), getString('old_str'), getString('new_str'), getBoolean('replace_all') ?? false);
-                case "multi_edit":
-                    return await this.textEditor.multiEdit(getString('path'), Array.isArray(args.edits) ? args.edits : []);
-                case "bash":
-                    return await this.bash.execute(getString('command'), {
-                        background: getBoolean('background'),
-                        timeout: getNumber('timeout'),
-                    });
-                case "bash_output":
-                    return await this.bashOutput.execute(getString('task_id'), getBoolean('wait'), getNumber('timeout'));
-                case "create_todo_list":
-                    return await this.todoTool.createTodoList(Array.isArray(args.todos) ? args.todos : []);
-                case "update_todo_list":
-                    return await this.todoTool.updateTodoList(Array.isArray(args.updates) ? args.updates : []);
-                case "search":
-                    const searchTypeValue = args.search_type;
-                    const validSearchType = (searchTypeValue === 'text' || searchTypeValue === 'files' || searchTypeValue === 'both') ? searchTypeValue : undefined;
-                    return await this.search.search(getString('query'), {
-                        searchType: validSearchType,
-                        includePattern: typeof args.include_pattern === 'string' ? args.include_pattern : undefined,
-                        excludePattern: typeof args.exclude_pattern === 'string' ? args.exclude_pattern : undefined,
-                        caseSensitive: getBoolean('case_sensitive'),
-                        wholeWord: getBoolean('whole_word'),
-                        regex: getBoolean('regex'),
-                        maxResults: getNumber('max_results'),
-                        fileTypes: Array.isArray(args.file_types) ? args.file_types : undefined,
-                        includeHidden: getBoolean('include_hidden'),
-                    });
-                case "analyze_architecture": {
-                    const projectPath = typeof args.projectPath === 'string' ? args.projectPath : undefined;
-                    const depth = typeof args.depth === 'string' ? args.depth : undefined;
-                    return await this.architectureTool.execute({ projectPath, depth });
-                }
-                case "validate_best_practices": {
-                    const path = typeof args.path === 'string' ? args.path : undefined;
-                    const pattern = typeof args.pattern === 'string' ? args.pattern : undefined;
-                    const rules = typeof args.rules === 'object' && args.rules !== null ? args.rules : undefined;
-                    return await this.validationTool.execute({ path, pattern, rules });
-                }
-                default:
-                    // Check if this is an MCP tool
-                    if (toolCall.function.name.startsWith("mcp__")) {
-                        return await this.executeMCPTool(toolCall);
-                    }
+        // Check if tool approval is required (for VSCode integration)
+        if (this.requireToolApproval) {
+            // Only require approval for file modification operations
+            const needsApproval = toolCall.function.name === "create_file" ||
+                toolCall.function.name === "str_replace_editor" ||
+                toolCall.function.name === "insert_text";
+            if (needsApproval) {
+                // Emit event and wait for approval
+                const approved = await this.waitForToolApproval(toolCall);
+                if (!approved) {
+                    // User rejected the change
+                    this.emit('tool:rejected', toolCall);
                     return {
                         success: false,
-                        error: `Unknown tool: ${toolCall.function.name}`,
+                        error: 'Change rejected by user'
                     };
-            }
-        }
-        catch (error) {
-            const errorMsg = extractErrorMessage(error);
-            return {
-                success: false,
-                error: `Tool execution error: ${errorMsg}`,
-            };
-        }
-    }
-    async executeMCPTool(toolCall) {
-        try {
-            const parseResult = this.parseToolArguments(toolCall, 'MCP tool');
-            if (!parseResult.success) {
-                return { success: false, error: parseResult.error };
-            }
-            const args = parseResult.args;
-            const mcpManager = getMCPManager();
-            const result = await mcpManager.callTool(toolCall.function.name, args);
-            if (result.isError) {
-                // Extract error message from MCP result content
-                // Safely check content structure before accessing
-                let errorMsg = "MCP tool error";
-                if (result.content && Array.isArray(result.content) && result.content.length > 0) {
-                    const firstContent = result.content[0];
-                    if (typeof firstContent === 'object' && firstContent !== null && 'text' in firstContent) {
-                        const textValue = firstContent.text;
-                        errorMsg = typeof textValue === 'string' ? textValue : String(textValue || errorMsg);
-                    }
                 }
-                return {
-                    success: false,
-                    error: errorMsg,
-                };
+                // User approved
+                this.emit('tool:approved', toolCall);
             }
-            // Extract content from result
-            // Ensure result.content exists and is an array before mapping
-            const output = result.content && Array.isArray(result.content)
-                ? result.content
-                    .map((item) => {
-                    if (item.type === "text") {
-                        return item.text || ""; // Safety check for missing text property
-                    }
-                    else if (item.type === "resource") {
-                        return `Resource: ${item.resource?.uri || "Unknown"}`;
-                    }
-                    return String(item);
-                })
-                    .join("\n")
-                : "";
-            return {
-                success: true,
-                output: output || "Success",
-            };
-        }
-        catch (error) {
-            const errorMsg = extractErrorMessage(error);
-            return {
-                success: false,
-                error: `MCP tool execution error: ${errorMsg}`,
-            };
         }
+        // Delegate to ToolExecutor (Phase 2 refactoring)
+        return await this.toolExecutor.execute(toolCall);
     }
     getChatHistory() {
         this.checkDisposed();
         return [...this.chatHistory];
     }
     getCurrentDirectory() {
-        return this.bash.getCurrentDirectory();
+        return this.toolExecutor.getBashTool().getCurrentDirectory();
     }
     async executeBashCommand(command) {
-        return await this.bash.execute(command);
+        return await this.toolExecutor.getBashTool().execute(command);
     }
     /**
      * Check if a bash command is currently executing
      */
     isBashExecuting() {
-        return this.bash.isExecuting();
+        return this.toolExecutor.getBashTool().isExecuting();
     }
     /**
      * Move currently running bash command to background
      * Returns task ID if successful, null otherwise
      */
     moveBashToBackground() {
-        return this.bash.moveToBackground();
+        return this.toolExecutor.getBashTool().moveToBackground();
     }
     getCurrentModel() {
         return this.llmClient.getCurrentModel();
@@ -1865,6 +1339,8 @@ export class LLMAgent extends EventEmitter {
         this.llmClient.setModel(model);
         // Update token counter for new model (use singleton)
         this.tokenCounter = getTokenCounter(model);
+        // Update stream handler model for usage tracking
+        this.streamHandler.setModel(model);
     }
     abortCurrentOperation() {
         if (this.abortController) {
@@ -1989,19 +1465,9 @@ export class LLMAgent extends EventEmitter {
      */
     async spawnSubagent(role, description, context) {
         try {
-            // Import SubagentRole from subagent-types
-            const { SubagentRole } = await import('./subagent-types.js');
-            // Convert string role to SubagentRole enum
-            const roleMap = {
-                'testing': SubagentRole.TESTING,
-                'documentation': SubagentRole.DOCUMENTATION,
-                'refactoring': SubagentRole.REFACTORING,
-                'analysis': SubagentRole.ANALYSIS,
-                'debug': SubagentRole.DEBUG,
-                'performance': SubagentRole.PERFORMANCE,
-                'general': SubagentRole.GENERAL,
-            };
-            const subagentRole = roleMap[role.toLowerCase()] || SubagentRole.GENERAL;
+            // Import parseSubagentRole helper to convert string to enum
+            const { parseSubagentRole } = await import('./subagent-types.js');
+            const subagentRole = parseSubagentRole(role);
             // Spawn the subagent
             const subagent = await this.subagentOrchestrator.spawnSubagent(subagentRole);
             // Execute the task
@@ -2045,22 +1511,13 @@ export class LLMAgent extends EventEmitter {
      */
     async executeParallelTasks(tasks) {
         try {
-            // Import SubagentRole and SubagentTask
-            const { SubagentRole } = await import('./subagent-types.js');
-            const roleMap = {
-                'testing': SubagentRole.TESTING,
-                'documentation': SubagentRole.DOCUMENTATION,
-                'refactoring': SubagentRole.REFACTORING,
-                'analysis': SubagentRole.ANALYSIS,
-                'debug': SubagentRole.DEBUG,
-                'performance': SubagentRole.PERFORMANCE,
-                'general': SubagentRole.GENERAL,
-            };
+            // Import parseSubagentRole helper to convert string to enum
+            const { parseSubagentRole } = await import('./subagent-types.js');
             // Convert tasks to SubagentTask format
             const subagentTasks = tasks.map((task, index) => ({
                 id: task.id || `task-${index}-${Date.now()}`,
                 description: task.description,
-                role: roleMap[task.role.toLowerCase()] ?? SubagentRole.GENERAL,
+                role: parseSubagentRole(task.role),
                 priority: 1,
                 context: {
                     files: [],
@@ -2141,8 +1598,8 @@ export class LLMAgent extends EventEmitter {
             this.contextManager.removeListener('before_prune', this.contextOverflowListener);
             this.contextOverflowListener = undefined;
         }
-        // Dispose tools that have cleanup methods
-        this.bash.dispose();
+        // Dispose tool executor (includes all tools with cleanup methods)
+        this.toolExecutor.dispose();
         // Clear in-memory caches
         this.recentToolCalls.clear();
         this.toolCallIndexMap.clear();