orquesta-cli 0.1.12

package/src/core/llm/llm-client.ts

@@ -0,0 +1,1550 @@
+/**
+ * LLM Client
+ *
+ * OpenAI Compatible API client
+ * Supports Gemini (HTTPS) and LiteLLM (HTTP)
+ *
+ * Logger usage guide:
+ * - This file already uses logger.httpRequest(), logger.httpResponse(), logger.error(), etc.
+ * - Additional improvements: Add logger.enter/exit to main public functions
+ * - Example: logger.enter('sendMessage', { messageLength: userMessage.length });
+ * - For detailed usage, see docs/LOGGER_USAGE_KR.md
+ */
+
+import axios, { AxiosInstance, AxiosError } from 'axios';
+import { Message, LLMRequestOptions } from '../../types/index.js';
+import { configManager } from '../config/config-manager.js';
+import {
+  NetworkError,
+  APIError,
+  TimeoutError,
+  ConnectionError,
+} from '../../errors/network.js';
+import {
+  LLMError,
+  TokenLimitError,
+  RateLimitError,
+  ContextLengthError,
+} from '../../errors/llm.js';
+import { logger, isLLMLogEnabled } from '../../utils/logger.js';
+import { usageTracker } from '../usage-tracker.js';
+
+/**
+ * LLM response interface (OpenAI Compatible)
+ */
+export interface LLMResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: Message & {
+      reasoning?: string;
+    };
+    finish_reason: string | null;
+  }>;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/**
+ * Streaming chunk interface
+ */
+export interface LLMStreamChunk {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    delta: {
+      role?: string;
+      content?: string;
+      reasoning?: string;
+    };
+    finish_reason: string | null;
+  }>;
+}
+
+/**
+ * Retry configuration interface
+ */
+export interface RetryConfig {
+  /** Maximum retry attempts (default: 3) */
+  maxRetries?: number;
+  /** Current attempt number (internal use) */
+  currentAttempt?: number;
+  /** Whether retry is disabled */
+  disableRetry?: boolean;
+}
+
+/**
+ * LLM Client class
+ */
+export class LLMClient {
+  private axiosInstance: AxiosInstance;
+  private baseUrl: string;
+  private apiKey: string;
+  private model: string;
+  private modelName: string;
+  private currentAbortController: AbortController | null = null;
+  private isInterrupted: boolean = false;
+
+  /** Default maximum retry attempts */
+  private static readonly DEFAULT_MAX_RETRIES = 3;
+
+  constructor() {
+    // Get current settings from ConfigManager
+    const endpoint = configManager.getCurrentEndpoint();
+    const currentModel = configManager.getCurrentModel();
+
+    if (!endpoint || !currentModel) {
+      throw new Error('No endpoint or model configured. Run: open config init');
+    }
+
+    this.baseUrl = endpoint.baseUrl;
+    this.apiKey = endpoint.apiKey || '';
+    this.model = currentModel.id;
+    this.modelName = currentModel.name;
+
+    // Create Axios instance
+    this.axiosInstance = axios.create({
+      baseURL: this.baseUrl,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.apiKey && { Authorization: `Bearer ${this.apiKey}` }),
+      },
+      timeout: 600000, // 600 seconds (10 minutes)
+    });
+  }
+
+  /**
+   * Preprocess messages for model-specific requirements
+   *
+   * Handles:
+   * 1. reasoning_content → content conversion (for reasoning LLM responses)
+   * 2. Harmony format for gpt-oss models
+   */
+  private preprocessMessages(messages: Message[], modelId: string): Message[] {
+    return messages.map((msg) => {
+      // Skip non-assistant messages
+      if (msg.role !== 'assistant') {
+        return msg;
+      }
+
+      const msgAny = msg as any;
+      let processedMsg = { ...msg };
+
+      // Handle reasoning_content from reasoning LLMs (DeepSeek-V3, etc.)
+      // When switching between reasoning LLM and regular LLM, content field is required
+      if (msgAny.reasoning_content && (!msg.content || msg.content.trim() === '')) {
+        processedMsg.content = msgAny.reasoning_content;
+        // Remove reasoning_content to avoid confusion
+        delete (processedMsg as any).reasoning_content;
+      }
+
+      // gpt-oss-120b / gpt-oss-20b: Harmony format handling
+      // These models require content field even when tool_calls are present
+      if (/^gpt-oss-(120b|20b)$/i.test(modelId)) {
+        if (msg.tool_calls && msg.tool_calls.length > 0) {
+          if (!processedMsg.content || processedMsg.content.trim() === '') {
+            const toolNames = msg.tool_calls.map(tc => tc.function.name).join(', ');
+            processedMsg.content = msgAny.reasoning || `Calling tools: ${toolNames}`;
+          }
+        }
+      }
+
+      // Ensure content is at least empty string for assistant messages
+      if (processedMsg.content === undefined || processedMsg.content === null) {
+        processedMsg.content = '';
+      }
+
+      return processedMsg;
+    });
+  }
+
+  /**
+   * Chat Completion API call (Non-streaming)
+   * Retries up to 3 times by default, errors not shown in UI during retry
+   */
+  async chatCompletion(
+    options: Partial<LLMRequestOptions>,
+    retryConfig?: RetryConfig
+  ): Promise<LLMResponse> {
+    const maxRetries = retryConfig?.disableRetry ? 1 : (retryConfig?.maxRetries ?? LLMClient.DEFAULT_MAX_RETRIES);
+    const currentAttempt = retryConfig?.currentAttempt ?? 1;
+
+    logger.enter('chatCompletion', {
+      model: options.model || this.model,
+      messagesCount: options.messages?.length || 0,
+      hasTools: !!options.tools,
+      attempt: currentAttempt,
+      maxRetries
+    });
+
+    const url = '/chat/completions';
+
+    try {
+      logger.flow('Starting message preprocessing');
+      // Preprocess messages for model-specific requirements
+      const modelId = options.model || this.model;
+      const processedMessages = options.messages ?
+        this.preprocessMessages(options.messages, modelId) : [];
+
+      logger.vars(
+        { name: 'modelId', value: modelId },
+        { name: 'originalMessages', value: options.messages?.length || 0 },
+        { name: 'processedMessages', value: processedMessages.length },
+        { name: 'temperature', value: options.temperature ?? 0.7 }
+      );
+
+      const requestBody = {
+        model: modelId,
+        messages: processedMessages,
+        temperature: options.temperature ?? 0.7,
+        max_tokens: options.max_tokens,
+        stream: false,
+        ...(options.tools && {
+          tools: options.tools,
+          parallel_tool_calls: false,  // Enforce one tool at a time via API
+          ...(options.tool_choice && { tool_choice: options.tool_choice }),
+        }),
+      };
+
+      logger.flow('API request preparation complete');
+
+      // Log request
+      logger.httpRequest('POST', `${this.baseUrl}${url}`, {
+        model: modelId,
+        messages: `${processedMessages.length} messages`,
+        temperature: requestBody.temperature,
+        max_tokens: requestBody.max_tokens,
+        tools: options.tools ? `${options.tools.length} tools` : 'none',
+      });
+
+      logger.verbose('Full Request Body', requestBody);
+
+      // LLM Log mode: Log request
+      if (isLLMLogEnabled()) {
+        logger.llmRequest(processedMessages, modelId, options.tools);
+      }
+
+      logger.startTimer('llm-api-call');
+
+      // Create AbortController for this request
+      this.currentAbortController = new AbortController();
+
+      const response = await this.axiosInstance.post<LLMResponse>(url, requestBody, {
+        signal: this.currentAbortController.signal,
+      });
+
+      this.currentAbortController = null;
+      const elapsed = logger.endTimer('llm-api-call');
+
+      logger.flow('API response received');
+
+      // Validate response structure
+      if (!response.data.choices || !Array.isArray(response.data.choices)) {
+        logger.error('Invalid response structure - missing choices array', response.data);
+        throw new Error('Invalid LLM response format. Missing choices array.');
+      }
+
+      // Log response
+      logger.httpResponse(response.status, response.statusText, {
+        choices: response.data.choices.length,
+        usage: response.data.usage,
+      });
+
+      logger.verbose('Full Response', response.data);
+
+      logger.vars(
+        { name: 'responseChoices', value: response.data.choices.length },
+        { name: 'tokensUsed', value: response.data.usage?.total_tokens || 0 },
+        { name: 'responseTime', value: elapsed }
+      );
+
+      // LLM Log mode: Log response
+      if (isLLMLogEnabled()) {
+        const responseContent = response.data.choices[0]?.message?.content || '';
+        const toolCalls = response.data.choices[0]?.message?.tool_calls;
+        logger.llmResponse(responseContent, toolCalls);
+      }
+
+      // Emit reasoning if present (extended thinking from o1 models)
+      // Only emit for user-facing responses (skip internal classifier calls)
+      const reasoningContent = response.data.choices[0]?.message?.reasoning;
+      const maxTokens = options.max_tokens;
+      const isInternalCall = maxTokens && maxTokens < 500; // Internal calls use small max_tokens
+
+      if (reasoningContent && !isInternalCall) {
+        const { emitReasoning } = await import('../../tools/llm/simple/file-tools.js');
+        emitReasoning(reasoningContent, false);
+        logger.debug('Reasoning content emitted', { length: reasoningContent.length });
+      } else if (reasoningContent && isInternalCall) {
+        logger.debug('Reasoning skipped (internal call)', { maxTokens, length: reasoningContent.length });
+      }
+
+      // Track token usage (Phase 3) + context tracking for auto-compact
+      if (response.data.usage) {
+        const promptTokens = response.data.usage.prompt_tokens || 0;
+        usageTracker.recordUsage(
+          this.model,
+          promptTokens,
+          response.data.usage.completion_tokens || 0,
+          undefined,  // sessionId
+          promptTokens  // lastPromptTokens for context tracking
+        );
+      }
+
+      logger.exit('chatCompletion', {
+        success: true,
+        choices: response.data.choices.length,
+        elapsed
+      });
+
+      return response.data;
+    } catch (error) {
+      this.currentAbortController = null;
+
+      // Check if this was an abort/cancel
+      if (axios.isCancel(error) || (error instanceof Error && error.name === 'CanceledError')) {
+        logger.flow('API call canceled (user interrupt)');
+        logger.exit('chatCompletion', { success: false, aborted: true });
+        throw new Error('INTERRUPTED');
+      }
+
+      // If retryable error and retries remaining, retry
+      if (currentAttempt < maxRetries && this.isRetryableError(error)) {
+        // During retry, only log at debug level (not shown in UI)
+        const delay = Math.pow(2, currentAttempt - 1) * 1000; // Exponential backoff: 1s, 2s, 4s
+        logger.debug(`LLM call failed (${currentAttempt}/${maxRetries}), retrying after ${delay}ms...`, {
+          error: (error as Error).message,
+          attempt: currentAttempt,
+          maxRetries,
+          delay
+        });
+
+        await this.sleep(delay);
+
+        // Retry recursively
+        return this.chatCompletion(options, {
+          maxRetries,
+          currentAttempt: currentAttempt + 1,
+        });
+      }
+
+      // Final failure: Log error and throw
+      logger.flow('API call failed - Error handling');
+      if (currentAttempt > 1) {
+        // Only show error log if final failure after retries
+        logger.error(`LLM call final failure after ${maxRetries} retries`, {
+          error: (error as Error).message,
+          attempts: currentAttempt
+        });
+      }
+      logger.exit('chatCompletion', { success: false, error: (error as Error).message, attempts: currentAttempt });
+      throw this.handleError(error, {
+        method: 'POST',
+        url,
+        body: options,
+      });
+    }
+  }
+
+  /**
+   * Abort current LLM request and set interrupt flag (for ESC interrupt)
+   */
+  abort(): void {
+    logger.flow('LLM interrupt - Stopping all operations');
+    this.isInterrupted = true;
+
+    if (this.currentAbortController) {
+      this.currentAbortController.abort();
+      this.currentAbortController = null;
+    }
+  }
+
+  /**
+   * Check if interrupted
+   */
+  checkInterrupted(): boolean {
+    return this.isInterrupted;
+  }
+
+  /**
+   * Reset interrupt flag (call before starting new operation)
+   */
+  resetInterrupt(): void {
+    this.isInterrupted = false;
+  }
+
+  /**
+   * Check if there's an active request
+   */
+  isRequestActive(): boolean {
+    return this.currentAbortController !== null;
+  }
+
+  /**
+   * Check if error is retryable
+   * - 5xx server errors
+   * - Network errors (ECONNREFUSED, ETIMEDOUT, ECONNRESET, etc.)
+   * - Rate Limit (429)
+   * - Tool argument parsing errors are not retried (LLM response issue)
+   */
+  private isRetryableError(error: unknown): boolean {
+    // Do not retry user interrupts
+    if (error instanceof Error && error.message === 'INTERRUPTED') {
+      return false;
+    }
+
+    if (axios.isAxiosError(error)) {
+      const axiosError = error as AxiosError;
+
+      // Network error (no response)
+      if (!axiosError.response) {
+        const retryableCodes = ['ECONNREFUSED', 'ETIMEDOUT', 'ECONNRESET', 'ECONNABORTED', 'ENOTFOUND', 'EHOSTUNREACH'];
+        if (axiosError.code && retryableCodes.includes(axiosError.code)) {
+          return true;
+        }
+        // Timeout
+        if (axiosError.message.includes('timeout')) {
+          return true;
+        }
+        return true; // Retry other network errors too
+      }
+
+      const status = axiosError.response.status;
+
+      // Rate Limit (429)
+      if (status === 429) {
+        return true;
+      }
+
+      // Server error (5xx)
+      if (status >= 500) {
+        return true;
+      }
+
+      // Do not retry auth/permission errors (401, 403)
+      // Do not retry bad requests (400)
+      // Do not retry Context Length exceeded
+      return false;
+    }
+
+    // Do not retry other errors
+    return false;
+  }
+
+  /**
+   * Wait for specified time (for retry)
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Chat Completion API call (Streaming)
+   */
+  async *chatCompletionStream(
+    options: Partial<LLMRequestOptions>
+  ): AsyncGenerator<LLMStreamChunk, void, unknown> {
+    const url = '/chat/completions';
+
+    try {
+      // Preprocess messages for model-specific requirements
+      const modelId = options.model || this.model;
+      const processedMessages = options.messages ?
+        this.preprocessMessages(options.messages, modelId) : [];
+
+      const requestBody = {
+        model: modelId,
+        messages: processedMessages,
+        temperature: options.temperature ?? 0.7,
+        max_tokens: options.max_tokens,
+        stream: true,
+        ...(options.tools && {
+          tools: options.tools,
+          ...(options.tool_choice && { tool_choice: options.tool_choice }),
+        }),
+      };
+
+      // Log request
+      logger.httpRequest('POST (stream)', `${this.baseUrl}${url}`, {
+        model: modelId,
+        messages: `${processedMessages.length} messages`,
+        temperature: requestBody.temperature,
+        max_tokens: requestBody.max_tokens,
+      });
+
+      logger.verbose('Full Streaming Request Body', requestBody);
+
+      // Create AbortController for streaming request
+      this.currentAbortController = new AbortController();
+
+      const response = await this.axiosInstance.post(url, requestBody, {
+        responseType: 'stream',
+        signal: this.currentAbortController.signal,
+      });
+
+      logger.debug('Streaming response started', { status: response.status });
+
+      // SSE (Server-Sent Events) parsing
+      const stream = response.data as AsyncIterable<Buffer>;
+      let buffer = '';
+      let chunkCount = 0;
+
+      // Check if this is an internal call (skip reasoning for classifier calls)
+      const maxTokens = options.max_tokens;
+      const isInternalCall = maxTokens && maxTokens < 500;
+
+      // Import emitReasoning once before loop
+      const { emitReasoning } = await import('../../tools/llm/simple/file-tools.js');
+
+      try {
+        for await (const chunk of stream) {
+          // Check for interrupt at the start of each chunk
+          if (this.isInterrupted) {
+            logger.flow('Interrupt detected during streaming - stopping');
+            throw new Error('INTERRUPTED');
+          }
+
+          buffer += chunk.toString();
+          const lines = buffer.split('\n');
+          buffer = lines.pop() || '';
+
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed === 'data: [DONE]') continue;
+
+            if (trimmed.startsWith('data: ')) {
+              try {
+                const jsonStr = trimmed.slice(6);
+                const data = JSON.parse(jsonStr) as LLMStreamChunk;
+                chunkCount++;
+
+                // Emit reasoning if present in stream (extended thinking)
+                // Skip for internal classifier calls
+                const reasoningDelta = data.choices[0]?.delta?.reasoning;
+                if (reasoningDelta && !isInternalCall) {
+                  emitReasoning(reasoningDelta, true);
+                  logger.debug('Reasoning delta emitted', { length: reasoningDelta.length });
+                } else if (reasoningDelta && isInternalCall) {
+                  logger.debug('Reasoning delta skipped (internal call)', { maxTokens });
+                }
+
+                yield data;
+              } catch (parseError) {
+                // Ignore JSON parsing error (incomplete chunk)
+                logger.debug('Skipping invalid chunk', { line: trimmed });
+                continue;
+              }
+            }
+          }
+        }
+      } finally {
+        // Clear abort controller after streaming completes
+        this.currentAbortController = null;
+      }
+
+      logger.debug('Streaming response completed', { chunkCount });
+
+    } catch (error) {
+      throw this.handleError(error, {
+        method: 'POST (stream)',
+        url,
+        body: options,
+      });
+    }
+  }
+
+  /**
+   * Send simple chat message (helper method)
+   */
+  async sendMessage(userMessage: string, systemPrompt?: string): Promise<string> {
+    logger.enter('sendMessage', {
+      messageLength: userMessage.length,
+      hasSystemPrompt: !!systemPrompt
+    });
+
+    logger.flow('Constructing message array');
+    const messages: Message[] = [];
+
+    if (systemPrompt) {
+      logger.vars({ name: 'systemPrompt', value: systemPrompt.substring(0, 100) + (systemPrompt.length > 100 ? '...' : '') });
+      messages.push({
+        role: 'system',
+        content: systemPrompt,
+      });
+    }
+
+    messages.push({
+      role: 'user',
+      content: userMessage,
+    });
+
+    logger.vars(
+      { name: 'totalMessages', value: messages.length },
+      { name: 'userMessage', value: userMessage.substring(0, 100) + (userMessage.length > 100 ? '...' : '') }
+    );
+
+    logger.flow('Calling LLM API');
+    logger.startTimer('sendMessage-api');
+
+    const response = await this.chatCompletion({ messages });
+
+    const elapsed = logger.endTimer('sendMessage-api');
+
+    logger.flow('Processing response');
+    if (response.choices.length === 0) {
+      logger.flow('No response - Error occurred');
+      logger.exit('sendMessage', { success: false, reason: 'No response from LLM' });
+      throw new Error('No response from LLM');
+    }
+
+    const responseContent = response.choices[0]?.message.content || '';
+
+    logger.vars(
+      { name: 'responseLength', value: responseContent.length },
+      { name: 'apiTime', value: elapsed }
+    );
+
+    logger.exit('sendMessage', {
+      success: true,
+      responseLength: responseContent.length,
+      elapsed
+    });
+
+    return responseContent;
+  }
+
+  /**
+   * Send streaming chat message
+   */
+  async *sendMessageStream(
+    userMessage: string,
+    systemPrompt?: string
+  ): AsyncGenerator<string, void, unknown> {
+    const messages: Message[] = [];
+
+    if (systemPrompt) {
+      messages.push({
+        role: 'system',
+        content: systemPrompt,
+      });
+    }
+
+    messages.push({
+      role: 'user',
+      content: userMessage,
+    });
+
+    for await (const chunk of this.chatCompletionStream({ messages })) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        yield content;
+      }
+    }
+  }
+
+  /**
+   * Chat Completion with Tools (maintain conversation history)
+   * Used in Interactive Mode - supports tool calling with full conversation history
+   * No iteration limit - continues until LLM stops calling tools
+   *
+   * @param messages - Conversation history
+   * @param tools - Available tools
+   * @param options - Additional options
+   * @param options.getPendingMessage - Callback to get pending user message
+   * @param options.clearPendingMessage - Callback to clear pending message after processing
+   */
+  async chatCompletionWithTools(
+    messages: Message[],
+    tools: import('../../types/index.js').ToolDefinition[],
+    options?: {
+      getPendingMessage?: () => string | null;
+      clearPendingMessage?: () => void;
+    }
+  ): Promise<{
+    message: Message;
+    toolCalls: Array<{ tool: string; args: unknown; result: string }>;
+    allMessages: Message[];
+  }> {
+    let workingMessages = [...messages];
+    const toolCallHistory: Array<{ tool: string; args: unknown; result: string }> = [];
+    let iterations = 0;
+    let contextLengthRecoveryAttempted = false;  // Prevent infinite recovery loop
+    let noToolCallRetries = 0;  // Prevent infinite loop when LLM doesn't use tools
+    let finalResponseFailures = 0;  // Prevent infinite loop when final_response keeps failing
+    const MAX_NO_TOOL_CALL_RETRIES = 3;  // Max retries for enforcing tool usage
+    const MAX_FINAL_RESPONSE_FAILURES = 3;  // Max retries for final_response failures
+
+    while (true) {
+      // Check for interrupt at start of each iteration
+      if (this.isInterrupted) {
+        logger.flow('Interrupt detected - stopping tool loop');
+        throw new Error('INTERRUPTED');
+      }
+
+      iterations++;
+
+      // Check for pending user message and inject it
+      if (options?.getPendingMessage && options?.clearPendingMessage) {
+        const pendingMsg = options.getPendingMessage();
+        if (pendingMsg) {
+          logger.flow('Injecting pending user message into conversation');
+          workingMessages.push({ role: 'user' as const, content: pendingMsg });
+          options.clearPendingMessage();
+        }
+      }
+
+      // Call LLM (with tools) - with ContextLengthError recovery
+      // tool_choice: 'required' forces LLM to always use a tool (use final_response for final answer)
+      let response: LLMResponse;
+      try {
+        response = await this.chatCompletion({
+          messages: workingMessages,
+          tools,
+          tool_choice: 'required',
+        });
+      } catch (error) {
+        // ContextLengthError recovery: rollback last tool + compact + retry
+        if (error instanceof ContextLengthError && !contextLengthRecoveryAttempted) {
+          contextLengthRecoveryAttempted = true;
+          logger.flow('ContextLengthError detected - attempting recovery with compact');
+
+          // Rollback: remove last tool results and assistant message with tool_calls
+          let rollbackIdx = workingMessages.length - 1;
+          while (rollbackIdx >= 0 && workingMessages[rollbackIdx]?.role === 'tool') {
+            rollbackIdx--;
+          }
+          // rollbackIdx now points to last assistant message (with tool_calls)
+          if (rollbackIdx >= 0 && workingMessages[rollbackIdx]?.tool_calls) {
+            workingMessages = workingMessages.slice(0, rollbackIdx);
+            logger.debug('Rolled back messages to before last tool execution', {
+              removedCount: workingMessages.length - rollbackIdx,
+            });
+          }
+
+          // Execute compact
+          const { CompactManager } = await import('../compact/compact-manager.js');
+          const { buildCompactedMessages } = await import('../compact/compact-prompts.js');
+          const compactManager = new CompactManager(this);
+
+          const compactResult = await compactManager.compact(workingMessages, {
+            workingDirectory: process.cwd(),
+          });
+
+          if (compactResult.success && compactResult.compactedSummary) {
+            // Replace workingMessages with compacted result
+            const compactedMessages = buildCompactedMessages(compactResult.compactedSummary, {
+              workingDirectory: process.cwd(),
+            });
+            workingMessages = [...compactedMessages];
+            logger.flow('Compact completed, retrying with reduced context', {
+              originalCount: compactResult.originalMessageCount,
+              newCount: compactedMessages.length,
+            });
+
+            // Retry loop
+            continue;
+          } else {
+            // Compact failed - throw original error
+            logger.error('Compact failed during recovery', { error: compactResult.error });
+            throw error;
+          }
+        }
+
+        // Other errors or second ContextLengthError - rethrow
+        throw error;
+      }
+
+      // Check for interrupt after LLM call
+      if (this.isInterrupted) {
+        logger.flow('Interrupt detected after LLM call - stopping');
+        throw new Error('INTERRUPTED');
+      }
+
+      const choice = response.choices[0];
+      if (!choice) {
+        throw new Error('Cannot find choice in response.');
+      }
+
+      const assistantMessage = choice.message;
+      workingMessages.push(assistantMessage);
+
+      // Check tool calls
+      if (assistantMessage.tool_calls && assistantMessage.tool_calls.length > 0) {
+        // Multi-tool detection logging
+        if (assistantMessage.tool_calls.length > 1) {
+          const toolNames = assistantMessage.tool_calls.map(tc => tc.function.name).join(', ');
+          logger.warn(`[MULTI-TOOL DETECTED] LLM returned ${assistantMessage.tool_calls.length} tools: ${toolNames}`);
+        }
+
+        // Execute tool calls (parallel_tool_calls: false ensures single tool from API)
+        for (const toolCall of assistantMessage.tool_calls) {
+          const toolName = toolCall.function.name;
+          let toolArgs: Record<string, unknown>;
+
+          try {
+            toolArgs = JSON.parse(toolCall.function.arguments) as Record<string, unknown>;
+          } catch (parseError) {
+            const errorMsg = `Tool argument parsing failed for ${toolName}`;
+            logger.error(errorMsg, parseError);
+            logger.debug('Raw arguments', { raw: toolCall.function.arguments });
+
+            workingMessages.push({
+              role: 'tool',
+              content: `Error: Failed to parse tool arguments - ${parseError instanceof Error ? parseError.message : 'Unknown error'}`,
+              tool_call_id: toolCall.id,
+            });
+
+            toolCallHistory.push({
+              tool: toolName,
+              args: { raw: toolCall.function.arguments },
+              result: `Error: Argument parsing failed`,
+            });
+
+            continue;
+          }
+
+          // Execute tool
+          const { executeFileTool, requestToolApproval } = await import('../../tools/llm/simple/file-tools.js');
+
+          // Supervised Mode: Request user approval before tool execution
+          const approvalResult = await requestToolApproval(toolName, toolArgs);
+
+          if (approvalResult && typeof approvalResult === 'object' && approvalResult.reject) {
+            // User rejected the tool execution
+            logger.flow(`Tool rejected by user: ${toolName}`);
+
+            const rejectMessage = approvalResult.comment
+              ? `Tool execution rejected by user. Reason: ${approvalResult.comment}`
+              : 'Tool execution rejected by user.';
+
+            workingMessages.push({
+              role: 'tool',
+              content: rejectMessage,
+              tool_call_id: toolCall.id,
+            });
+
+            toolCallHistory.push({
+              tool: toolName,
+              args: toolArgs,
+              result: rejectMessage,
+            });
+
+            continue;
+          }
+
+          logger.debug(`Executing tool: ${toolName}`, toolArgs);
+
+          let result: { success: boolean; result?: string; error?: string; metadata?: Record<string, unknown> };
+
+          try {
+            result = await executeFileTool(toolName, toolArgs);
+            logger.toolExecution(toolName, toolArgs, result);
+
+            // LLM Log mode: Log tool result
+            if (isLLMLogEnabled()) {
+              logger.llmToolResult(toolName, result.result || '', result.success);
+            }
+
+            // Handle final_response tool
+            if (toolName === 'final_response') {
+              if (result.success && result.metadata?.['isFinalResponse']) {
+                // Success - return immediately
+                // Note: emitAssistantResponse is already called via finalResponseCallback in final-response-tool.ts
+                logger.flow('final_response tool executed successfully - returning');
+
+                // Add tool result to messages for completeness
+                workingMessages.push({
+                  role: 'tool',
+                  content: result.result || '',
+                  tool_call_id: toolCall.id,
+                });
+
+                // Add to history
+                toolCallHistory.push({
+                  tool: toolName,
+                  args: toolArgs,
+                  result: result.result || '',
+                });
+
+                // Return final response
+                return {
+                  message: {
+                    role: 'assistant' as const,
+                    content: result.result || '',
+                  },
+                  toolCalls: toolCallHistory,
+                  allMessages: workingMessages,
+                };
+              } else {
+                // Failure - track attempts to prevent infinite loop
+                finalResponseFailures++;
+                logger.flow(`final_response failed (attempt ${finalResponseFailures}/${MAX_FINAL_RESPONSE_FAILURES}): ${result.error}`);
+
+                if (finalResponseFailures >= MAX_FINAL_RESPONSE_FAILURES) {
+                  logger.warn('Max final_response failures exceeded - forcing completion');
+                  const fallbackMessage = (toolArgs['message'] as string) || 'Task completed with incomplete TODOs.';
+
+                  // Emit as assistant response
+                  const { emitAssistantResponse } = await import('../../tools/llm/simple/file-tools.js');
+                  emitAssistantResponse(fallbackMessage);
+
+                  return {
+                    message: { role: 'assistant' as const, content: fallbackMessage },
+                    toolCalls: toolCallHistory,
+                    allMessages: workingMessages,
+                  };
+                }
+              }
+            }
+          } catch (toolError) {
+            logger.toolExecution(toolName, toolArgs, undefined, toolError as Error);
+
+            // LLM Log mode: Log tool error
+            if (isLLMLogEnabled()) {
+              const errorMsg = toolError instanceof Error ? toolError.message : String(toolError);
+              logger.llmToolResult(toolName, `Error: ${errorMsg}`, false);
+            }
+
+            result = {
+              success: false,
+              error: toolError instanceof Error ? toolError.message : String(toolError),
+            };
+          }
+
+          // Add result to messages
+          workingMessages.push({
+            role: 'tool',
+            content: result.success ? result.result || '' : `Error: ${result.error}`,
+            tool_call_id: toolCall.id,
+          });
+
+          // Add to history
+          toolCallHistory.push({
+            tool: toolName,
+            args: toolArgs,
+            result: result.success ? result.result || '' : `Error: ${result.error}`,
+          });
+
+          // Check for interrupt after tool execution
+          if (this.isInterrupted) {
+            logger.flow('Interrupt detected after tool execution - stopping');
+            throw new Error('INTERRUPTED');
+          }
+        }
+
+        // Tool execution complete - Continue calling LLM (continue)
+        // Loop continues until LLM returns finish_reason: stop
+        continue;
+      } else {
+        // No tool call - Force tool call
+        // LLM must use tools (including final_response)
+        noToolCallRetries++;
+        logger.flow(`No tool call - enforcing tool usage (attempt ${noToolCallRetries}/${MAX_NO_TOOL_CALL_RETRIES})`);
+
+        // Max retries exceeded - return content as final response to prevent infinite loop
+        if (noToolCallRetries > MAX_NO_TOOL_CALL_RETRIES) {
+          logger.warn('Max no-tool-call retries exceeded - returning content as final response');
+          const fallbackContent = assistantMessage.content || 'Task completed.';
+
+          // Emit as assistant response
+          const { emitAssistantResponse } = await import('../../tools/llm/simple/file-tools.js');
+          emitAssistantResponse(fallbackContent);
+
+          return {
+            message: { role: 'assistant' as const, content: fallbackContent },
+            toolCalls: toolCallHistory,
+            allMessages: workingMessages,
+          };
+        }
+
+        // Check for malformed tool call patterns in content
+        const hasMalformedToolCall = assistantMessage.content &&
+          (/<tool_call>/i.test(assistantMessage.content) ||
+           /<arg_key>/i.test(assistantMessage.content) ||
+           /<arg_value>/i.test(assistantMessage.content) ||
+           /<\/tool_call>/i.test(assistantMessage.content) ||
+           /bash<arg_key>/i.test(assistantMessage.content));
+
+        const retryMessage = hasMalformedToolCall
+          ? 'Your previous response contained a malformed tool call (XML tags in content). You MUST use the proper tool_calls API format. Use final_response tool to deliver your message to the user.'
+          : 'You must use tools for all actions. Use final_response tool to deliver your final message to the user after completing all tasks.';
+
+        // Add assistant message (to preserve context) and retry instruction
+        workingMessages.push({
+          role: 'user',
+          content: retryMessage,
+        });
+
+        logger.debug('Enforcing tool call - added retry message');
+
+        // Continue loop to retry
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Get current model information
+   */
+  getModelInfo(): { model: string; endpoint: string } {
+    return {
+      model: this.modelName,
+      endpoint: this.baseUrl,
+    };
+  }
+
+  /**
+   * Enhanced error handler with detailed logging
+   */
+  private handleError(error: unknown, requestContext?: { method?: string; url?: string; body?: unknown }): Error {
+    // Log the error with context
+    logger.error('LLM Client Error', error);
+
+    if (requestContext) {
+      logger.debug('Request Context', requestContext);
+    }
+
+    if (axios.isAxiosError(error)) {
+      const axiosError = error as AxiosError;
+
+      // Timeout error
+      if (axiosError.code === 'ECONNABORTED' || axiosError.message.includes('timeout')) {
+        logger.error('Request Timeout', {
+          timeout: this.axiosInstance.defaults.timeout,
+          endpoint: this.baseUrl,
+        });
+        return new TimeoutError(
+          this.axiosInstance.defaults.timeout || 60000,
+          {
+            cause: axiosError,
+            details: {
+              endpoint: this.baseUrl,
+              method: requestContext?.method,
+              url: requestContext?.url,
+            },
+          }
+        );
+      }
+
+      if (axiosError.response) {
+        // Server responded with error status (4xx, 5xx)
+        const status = axiosError.response.status;
+        const data = axiosError.response.data as any;
+        const errorMessage = data?.error?.message || data?.message || axiosError.message;
+        const errorType = data?.error?.type || 'unknown';
+        const errorCode = data?.error?.code || data?.code;
+
+        // Enhanced error logging for debugging
+        logger.error('=== API ERROR DETAILS ===', {
+          status,
+          statusText: axiosError.response.statusText,
+          endpoint: this.baseUrl,
+          model: this.model,
+          errorMessage,
+          errorType,
+          errorCode,
+          // Full API response body
+          responseBody: JSON.stringify(data, null, 2),
+          // Request info
+          requestMethod: requestContext?.method,
+          requestUrl: requestContext?.url,
+          // Request body (truncated for large payloads)
+          requestBody: requestContext?.body
+            ? JSON.stringify(requestContext.body, null, 2).substring(0, 5000)
+            : undefined,
+          // Response headers
+          responseHeaders: axiosError.response.headers,
+        });
+
+        logger.httpResponse(status, axiosError.response.statusText, data);
+
+        // Context length exceeded (common OpenAI error)
+        if (
+          errorType === 'invalid_request_error' &&
+          (errorMessage.includes('context_length_exceeded') ||
+           errorMessage.includes('maximum context length') ||
+           errorCode === 'context_length_exceeded')
+        ) {
+          const maxLength = data?.error?.param?.max_tokens || 'unknown';
+          logger.error('Context Length Exceeded', {
+            maxLength,
+            errorMessage,
+            model: this.model,
+          });
+
+          return new ContextLengthError(
+            typeof maxLength === 'number' ? maxLength : 0,
+            undefined,
+            {
+              cause: axiosError,
+              details: {
+                model: this.model,
+                endpoint: this.baseUrl,
+                errorType,
+                fullError: data,
+              },
+            }
+          );
+        }
+
+        // Token limit error
+        if (
+          errorMessage.includes('token') &&
+          (errorMessage.includes('limit') || errorMessage.includes('exceeded'))
+        ) {
+          logger.error('Token Limit Error', {
+            errorMessage,
+            model: this.model,
+          });
+
+          return new TokenLimitError(
+            0, // We don't know the exact limit from error message
+            undefined,
+            {
+              cause: axiosError,
+              details: {
+                model: this.model,
+                endpoint: this.baseUrl,
+                fullError: data,
+              },
+              userMessage: errorMessage,
+            }
+          );
+        }
+
+        // Rate limit (429)
+        if (status === 429) {
+          const retryAfter = axiosError.response.headers['retry-after'];
+          const retrySeconds = retryAfter ? parseInt(retryAfter) : undefined;
+
+          logger.error('Rate Limit Exceeded', {
+            retryAfter: retrySeconds,
+            errorMessage,
+          });
+
+          return new RateLimitError(retrySeconds, {
+            cause: axiosError,
+            details: {
+              endpoint: this.baseUrl,
+              model: this.model,
+              fullError: data,
+            },
+          });
+        }
+
+        // Authentication error (401)
+        if (status === 401) {
+          logger.error('Authentication Failed', {
+            endpoint: this.baseUrl,
+            errorMessage,
+          });
+
+          return new APIError(
+            `Authentication failed: ${errorMessage}`,
+            status,
+            this.baseUrl,
+            {
+              cause: axiosError,
+              details: {
+                apiKeyProvided: !!this.apiKey,
+                apiKeyLength: this.apiKey?.length || 0,
+                fullError: data,
+              },
+              isRecoverable: false,
+              userMessage: `Invalid API key. Please check your settings.\nDetails: ${errorMessage}`,
+            }
+          );
+        }
+
+        // Forbidden (403)
+        if (status === 403) {
+          logger.error('Access Forbidden', {
+            endpoint: this.baseUrl,
+            errorMessage,
+          });
+
+          return new APIError(
+            `Access denied: ${errorMessage}`,
+            status,
+            this.baseUrl,
+            {
+              cause: axiosError,
+              details: {
+                fullError: data,
+              },
+              isRecoverable: false,
+            }
+          );
+        }
+
+        // Not found (404)
+        if (status === 404) {
+          logger.error('Endpoint Not Found', {
+            endpoint: this.baseUrl,
+            url: requestContext?.url,
+            errorMessage,
+          });
+
+          return new APIError(
+            `Endpoint not found: ${errorMessage}`,
+            status,
+            this.baseUrl,
+            {
+              cause: axiosError,
+              details: {
+                url: requestContext?.url,
+                fullError: data,
+              },
+              isRecoverable: false,
+              userMessage: `API endpoint does not exist.\nURL: ${this.baseUrl}${requestContext?.url || ''}\nDetails: ${errorMessage}`,
+            }
+          );
+        }
+
+        // Server error (5xx)
+        if (status >= 500) {
+          logger.error('Server Error', {
+            status,
+            endpoint: this.baseUrl,
+            errorMessage,
+          });
+
+          return new APIError(
+            `Server error (${status}): ${errorMessage}`,
+            status,
+            this.baseUrl,
+            {
+              cause: axiosError,
+              details: {
+                fullError: data,
+              },
+              isRecoverable: true, // Server errors are usually temporary
+            }
+          );
+        }
+
+        // Other API errors (4xx)
+        logger.error('API Error', {
+          status,
+          endpoint: this.baseUrl,
+          errorMessage,
+          errorType,
+          errorCode,
+        });
+
+        return new APIError(
+          `API error (${status}): ${errorMessage}`,
+          status,
+          this.baseUrl,
+          {
+            cause: axiosError,
+            details: {
+              errorType,
+              errorCode,
+              fullError: data,
+            },
+            userMessage: `API request failed (${status}):\n${errorMessage}\n\nError type: ${errorType}\nError code: ${errorCode}`,
+          }
+        );
+
+      } else if (axiosError.request) {
+        // Request sent but no response received (network error)
+        const errorCode = axiosError.code;
+
+        logger.error('Network Error - No Response', {
+          code: errorCode,
+          endpoint: this.baseUrl,
+          message: axiosError.message,
+        });
+
+        // Connection refused, host not found, etc.
+        if (
+          errorCode === 'ECONNREFUSED' ||
+          errorCode === 'ENOTFOUND' ||
+          errorCode === 'ECONNRESET' ||
+          errorCode === 'EHOSTUNREACH'
+        ) {
+          return new ConnectionError(this.baseUrl, {
+            cause: axiosError,
+            details: {
+              code: errorCode,
+              message: axiosError.message,
+            },
+            userMessage: `Cannot connect to server.\nEndpoint: ${this.baseUrl}\nError code: ${errorCode}\nDetails: ${axiosError.message}\n\nPlease check network connection and endpoint URL.`,
+          });
+        }
+
+        // General network error
+        return new NetworkError(
+          `Network error: ${axiosError.message}`,
+          {
+            cause: axiosError,
+            details: {
+              code: errorCode,
+              endpoint: this.baseUrl,
+            },
+            userMessage: `Network connection failed.\nEndpoint: ${this.baseUrl}\nError: ${axiosError.message}`,
+          }
+        );
+      }
+
+      // Axios error without response or request
+      logger.error('Axios Error', {
+        code: axiosError.code,
+        message: axiosError.message,
+      });
+
+      return new LLMError(
+        `LLM client error: ${axiosError.message}`,
+        {
+          cause: axiosError,
+          details: {
+            code: axiosError.code,
+          },
+        }
+      );
+    }
+
+    // Non-axios error
+    if (error instanceof Error) {
+      logger.error('Unexpected Error', error);
+      return new LLMError(
+        `Unexpected error: ${error.message}`,
+        {
+          cause: error,
+          userMessage: `An error occurred:\n${error.message}\n\nStack:\n${error.stack}`,
+        }
+      );
+    }
+
+    // Unknown error type
+    logger.error('Unknown Error Type', { error });
+    return new LLMError('An unknown error occurred.', {
+      details: { unknownError: error },
+    });
+  }
+
+  /**
+   * Chat Completion with retry logic
+   * @deprecated chatCompletion now performs retry by default
+   */
+  async chatCompletionWithRetry(
+    options: Partial<LLMRequestOptions>,
+    maxRetries = 3
+  ): Promise<LLMResponse> {
+    // Call directly as chatCompletion now performs retry internally
+    return this.chatCompletion(options, { maxRetries });
+  }
+
+  /**
+   * Health check for currently configured endpoint
+   */
+  async healthCheck(): Promise<{
+    success: boolean;
+    latency?: number;
+    error?: string;
+  }> {
+    const endpoint = configManager.getCurrentEndpoint();
+    const model = configManager.getCurrentModel();
+
+    if (!endpoint || !model) {
+      return { success: false, error: 'No endpoint or model configured' };
+    }
+
+    const startTime = Date.now();
+
+    try {
+      const response = await this.axiosInstance.post<LLMResponse>('/chat/completions', {
+        model: model.id,
+        messages: [{ role: 'user', content: 'ping' }],
+        max_tokens: 5,
+      });
+
+      const latency = Date.now() - startTime;
+
+      if (response.status === 200 && response.data.choices?.[0]?.message) {
+        return { success: true, latency };
+      } else {
+        return { success: false, latency, error: 'Invalid response format' };
+      }
+    } catch (error) {
+      const latency = Date.now() - startTime;
+      const axiosError = error as AxiosError;
+
+      if (axiosError.response) {
+        const status = axiosError.response.status;
+        return { success: false, latency, error: `HTTP ${status}` };
+      } else if (axiosError.request) {
+        return { success: false, latency, error: 'Connection failed' };
+      } else {
+        return { success: false, latency, error: axiosError.message || 'Unknown error' };
+      }
+    }
+  }
+
+  /**
+   * Bulk health check for all registered endpoints
+   */
+  static async healthCheckAll(): Promise<
+    Map<string, { modelId: string; healthy: boolean; latency?: number; error?: string }[]>
+  > {
+    const endpoints = configManager.getAllEndpoints();
+    const results = new Map<
+      string,
+      { modelId: string; healthy: boolean; latency?: number; error?: string }[]
+    >();
+
+    for (const endpoint of endpoints) {
+      const modelResults: { modelId: string; healthy: boolean; latency?: number; error?: string }[] = [];
+
+      for (const model of endpoint.models) {
+        if (!model.enabled) {
+          modelResults.push({
+            modelId: model.id,
+            healthy: false,
+            error: 'Model disabled',
+          });
+          continue;
+        }
+
+        const startTime = Date.now();
+
+        try {
+          const axiosInstance = axios.create({
+            baseURL: endpoint.baseUrl,
+            headers: {
+              'Content-Type': 'application/json',
+              ...(endpoint.apiKey && { Authorization: `Bearer ${endpoint.apiKey}` }),
+            },
+            timeout: 30000, // 30 second timeout
+          });
+
+          const response = await axiosInstance.post<LLMResponse>('/chat/completions', {
+            model: model.id,
+            messages: [{ role: 'user', content: 'ping' }],
+            max_tokens: 5,
+          });
+
+          const latency = Date.now() - startTime;
+
+          if (response.status === 200 && response.data.choices?.[0]?.message) {
+            modelResults.push({ modelId: model.id, healthy: true, latency });
+          } else {
+            modelResults.push({
+              modelId: model.id,
+              healthy: false,
+              latency,
+              error: 'Invalid response',
+            });
+          }
+        } catch (error) {
+          const latency = Date.now() - startTime;
+          const axiosError = error as AxiosError;
+
+          let errorMessage = 'Unknown error';
+          if (axiosError.response) {
+            errorMessage = `HTTP ${axiosError.response.status}`;
+          } else if (axiosError.code === 'ECONNREFUSED') {
+            errorMessage = 'Connection refused';
+          } else if (axiosError.code === 'ETIMEDOUT' || axiosError.code === 'ECONNABORTED') {
+            errorMessage = 'Timeout';
+          } else if (axiosError.request) {
+            errorMessage = 'Network error';
+          }
+
+          modelResults.push({
+            modelId: model.id,
+            healthy: false,
+            latency,
+            error: errorMessage,
+          });
+        }
+      }
+
+      results.set(endpoint.id, modelResults);
+    }
+
+    return results;
+  }
+
+  /**
+   * Endpoint connection test (Static)
+   * Static method for use during config init
+   */
+  static async testConnection(
+    baseUrl: string,
+    apiKey: string,
+    model: string
+  ): Promise<{ success: boolean; latency?: number; error?: string }> {
+    const startTime = Date.now();
+
+    try {
+      const axiosInstance = axios.create({
+        baseURL: baseUrl,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(apiKey && { Authorization: `Bearer ${apiKey}` }),
+        },
+        timeout: 60000, // 60 second timeout
+      });
+
+      // Verify connection with simple test message
+      const response = await axiosInstance.post<LLMResponse>('/chat/completions', {
+        model: model,
+        messages: [
+          {
+            role: 'user',
+            content: 'test',
+          },
+        ],
+        max_tokens: 10,
+      });
+
+      const latency = Date.now() - startTime;
+
+      if (response.status === 200 && response.data.choices?.[0]?.message) {
+        return { success: true, latency };
+      } else {
+        return { success: false, latency, error: 'Invalid response format' };
+      }
+    } catch (error) {
+      const latency = Date.now() - startTime;
+      const axiosError = error as AxiosError;
+
+      if (axiosError.response) {
+        const status = axiosError.response.status;
+        const data = axiosError.response.data as { error?: { message?: string } };
+        const message = data?.error?.message || axiosError.message;
+
+        if (status === 401) {
+          return { success: false, latency, error: 'Invalid API key.' };
+        } else if (status === 404) {
+          return { success: false, latency, error: 'Endpoint or model not found.' };
+        } else {
+          return { success: false, latency, error: `API error (${status}): ${message}` };
+        }
+      } else if (axiosError.request) {
+        return { success: false, latency, error: `Network error: Cannot connect to endpoint.` };
+      } else {
+        return { success: false, latency, error: axiosError.message || 'Unknown error' };
+      }
+    }
+  }
+}
+
+/**
+ * LLMClient singleton instance
+ * Available after ConfigManager initialization
+ */
+export function createLLMClient(): LLMClient {
+  return new LLMClient();
+}