@agile-vibe-coding/avc 0.2.3 → 0.3.2

package/cli/llm-openai.js

@@ -2,6 +2,9 @@ import OpenAI from 'openai';
 import { jsonrepair } from 'jsonrepair';
 import { LLMProvider } from './llm-provider.js';
 import { getMaxTokensForModel } from './llm-token-limits.js';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 
 export class OpenAIProvider extends LLMProvider {
   constructor(model = 'gpt-5.2-chat-latest', reasoningEffort = 'medium') {
@@ -10,11 +13,116 @@ export class OpenAIProvider extends LLMProvider {
   }
 
   _createClient() {
+    if (process.env.OPENAI_AUTH_MODE === 'oauth') {
+      const oauthPath = path.join(process.cwd(), '.avc', 'openai-oauth.json');
+      // Only use OAuth mode if the token file actually exists — avoids per-call ENOENT warnings
+      if (existsSync(oauthPath)) return { mode: 'oauth' };
+    }
     const apiKey = process.env.OPENAI_API_KEY;
     if (!apiKey) throw new Error('OPENAI_API_KEY not set. Add it to your .env file.');
     return new OpenAI({ apiKey });
   }
 
+  /**
+   * Load OAuth tokens from .avc/openai-oauth.json, refreshing if close to expiry.
+   */
+  async _loadOAuthTokens() {
+    const oauthPath = path.join(process.cwd(), '.avc', 'openai-oauth.json');
+    const raw = await fs.readFile(oauthPath, 'utf8');
+    let tokens = JSON.parse(raw);
+
+    // Refresh if within 60s of expiry
+    if (tokens.expires - Date.now() < 60_000) {
+      const body = new URLSearchParams({
+        grant_type:    'refresh_token',
+        client_id:     'app_EMoamEEZ73f0CkXaXp7hrann',
+        refresh_token: tokens.refresh,
+      });
+      const resp = await fetch('https://auth.openai.com/oauth/token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+      });
+      if (!resp.ok) throw new Error(`OAuth token refresh failed: ${resp.status}`);
+      const refreshed = await resp.json();
+      tokens = {
+        access:    refreshed.access_token,
+        refresh:   refreshed.refresh_token || tokens.refresh,
+        expires:   Date.now() + (refreshed.expires_in || 3600) * 1000,
+        accountId: tokens.accountId,
+      };
+      await fs.writeFile(oauthPath, JSON.stringify(tokens, null, 2), 'utf8');
+    }
+
+    return { access: tokens.access, accountId: tokens.accountId };
+  }
+
+  /**
+   * Call the ChatGPT Codex endpoint using OAuth bearer token.
+   */
+  async _callChatGPTCodex(prompt, agentInstructions) {
+    const { access, accountId } = await this._loadOAuthTokens();
+
+    const t0 = Date.now();
+    const resp = await fetch('https://chatgpt.com/backend-api/codex/responses', {
+      method: 'POST',
+      headers: {
+        'Authorization':       `Bearer ${access}`,
+        'chatgpt-account-id':  accountId,
+        'Content-Type':        'application/json',
+        'OpenAI-Beta':         'responses=experimental',
+        'accept':              'application/json',
+      },
+      body: JSON.stringify({
+        model:        this.model,
+        instructions: agentInstructions || 'You are a helpful assistant.',
+        input:        [{ role: 'user', content: prompt }],
+        store:        false,
+        stream:       true,
+      }),
+    });
+
+    if (!resp.ok) {
+      const raw = await resp.text();
+      throw new Error(`ChatGPT Codex API error (${resp.status}): ${raw}`);
+    }
+
+    // Parse SSE stream — accumulate text from delta events; use response.done for final text + usage
+    const body = await resp.text();
+    let text = '';
+    let finalEvent = null;
+    for (const line of body.split('\n')) {
+      if (!line.startsWith('data: ')) continue;
+      const chunk = line.slice(6).trim();
+      if (chunk === '[DONE]') break;
+      try {
+        const event = JSON.parse(chunk);
+        if (event.type === 'response.output_text.delta') {
+          text += event.delta ?? '';
+        } else if (event.type === 'response.output_text.done') {
+          text = event.text ?? text;   // prefer the complete text when available
+        } else if (event.type === 'response.done' || event.type === 'response.completed') {
+          finalEvent = event.response ?? event;
+          // response.done may carry output_text if delta events were absent
+          if (!text) {
+            text = finalEvent?.output_text ?? finalEvent?.output?.[0]?.content?.[0]?.text ?? '';
+          }
+          break;
+        }
+      } catch { /* skip malformed lines */ }
+    }
+    const usage = finalEvent?.usage ?? null;
+
+    this._trackTokens(usage, {
+      prompt,
+      agentInstructions: agentInstructions ?? null,
+      response: text,
+      elapsed: Date.now() - t0,
+    });
+
+    return text;
+  }
+
   /**
    * Determine if model uses Responses API instead of Chat Completions API
    * Models that use Responses API: gpt-5.2-pro, gpt-5.2-codex
@@ -42,11 +150,11 @@ export class OpenAIProvider extends LLMProvider {
       messages
     };
 
-    // GPT-5+ models use max_completion_tokens, older models use max_tokens
-    if (this.model.startsWith('gpt-5') || this.model.startsWith('o1') || this.model.startsWith('o3')) {
-      params.max_completion_tokens = maxTokens;
-    } else {
+    // max_completion_tokens is the modern unified parameter; max_tokens is only for legacy gpt-3.5-turbo
+    if (this.model.startsWith('gpt-3.5')) {
       params.max_tokens = maxTokens;
+    } else {
+      params.max_completion_tokens = maxTokens;
     }
 
     const response = await this._client.chat.completions.create(params);
@@ -57,8 +165,11 @@ export class OpenAIProvider extends LLMProvider {
 
   /**
    * Call using Responses API (pro/codex models)
+   * @param {string} prompt
+   * @param {string|null} systemInstructions
+   * @param {Object|null} [promptPayload] - Partial payload { prompt, agentInstructions } to log
    */
-  async _callResponsesAPI(prompt, systemInstructions) {
+  async _callResponsesAPI(prompt, systemInstructions, promptPayload = null) {
     // Combine system instructions with prompt
     const fullInput = systemInstructions
       ? `${systemInstructions}\n\n${prompt}`
@@ -74,20 +185,33 @@ export class OpenAIProvider extends LLMProvider {
       params.reasoning = { effort: this.reasoningEffort };
     }
 
+    const _t0 = Date.now();
     const response = await this._withRetry(
       () => this._client.responses.create(params),
       'Responses API call'
     );
+    const _elapsed = Date.now() - _t0;
+
+    const text = response.output_text;
 
     // Track tokens if usage data is available
     if (response.usage) {
-      this._trackTokens(response.usage);
+      const finalPayload = promptPayload ? {
+        ...promptPayload,
+        response: text,
+        elapsed: _elapsed,
+      } : null;
+      this._trackTokens(response.usage, finalPayload);
     }
 
-    return response.output_text;
+    return text;
   }
 
   async _callProvider(prompt, maxTokens, systemInstructions) {
+    // OAuth mode: all calls go through the ChatGPT Codex endpoint
+    if (this._client?.mode === 'oauth') {
+      return await this._callChatGPTCodex(prompt, systemInstructions);
+    }
     if (this._usesResponsesAPI()) {
       return await this._callResponsesAPI(prompt, systemInstructions);
     } else {
@@ -95,17 +219,56 @@ export class OpenAIProvider extends LLMProvider {
     }
   }
 
-  async generateJSON(prompt, agentInstructions = null) {
+  /** True when oauth mode is active AND fallback to api-key is enabled AND key is present */
+  _hasFallback() {
+    return process.env.OPENAI_AUTH_MODE === 'oauth'
+      && process.env.OPENAI_OAUTH_FALLBACK === 'true'
+      && !!process.env.OPENAI_API_KEY;
+  }
+
+  /** Create a plain OpenAI SDK client using OPENAI_API_KEY (for fallback) */
+  _createApiKeyClient() {
+    return new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+  }
+
+  async generateJSON(prompt, agentInstructions = null, cachedContext = null) {
     if (!this._client) {
       this._client = this._createClient();
     }
 
+    // OAuth path — route through ChatGPT Codex endpoint
+    if (this._client?.mode === 'oauth') {
+      try {
+        const jsonInstructions = (agentInstructions ? agentInstructions + '\n\n' : '')
+          + 'You are a helpful assistant that always returns valid JSON. Your response must be a valid JSON object or array, nothing else.';
+        const text = await this._callChatGPTCodex(prompt, jsonInstructions);
+        let jsonStr = text.trim();
+        if (jsonStr.startsWith('```')) {
+          jsonStr = jsonStr.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?\s*```\s*$/, '').trim();
+        }
+        try {
+          return JSON.parse(jsonStr);
+        } catch (firstError) {
+          if (jsonStr.startsWith('{') || jsonStr.startsWith('[')) {
+            try { return JSON.parse(jsonrepair(jsonStr)); } catch { /* fall through */ }
+          }
+          throw new Error(`Failed to parse JSON response: ${firstError.message}\n\nResponse was:\n${text}`);
+        }
+      } catch (oauthErr) {
+        if (!this._hasFallback()) throw oauthErr;
+        console.warn(`[openai] OAuth call failed, falling back to API key: ${oauthErr.message}`);
+        this._client = this._createApiKeyClient();
+        // fall through to standard paths below
+      }
+    }
+
     const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
 
     if (this._usesResponsesAPI()) {
       // Responses API: Use system instructions to enforce JSON
       const systemInstructions = 'You are a helpful assistant that always returns valid JSON. Your response must be a valid JSON object or array, nothing else.';
-      const response = await this._callResponsesAPI(fullPrompt, systemInstructions);
+      const _rApiPayload = this._promptLogger ? { prompt: fullPrompt, agentInstructions: agentInstructions ?? null } : null;
+      const response = await this._callResponsesAPI(fullPrompt, systemInstructions, _rApiPayload);
 
       // Parse and return JSON
       let jsonStr = response.trim();
@@ -126,31 +289,35 @@ export class OpenAIProvider extends LLMProvider {
         throw new Error(`Failed to parse JSON response: ${firstError.message}\n\nResponse was:\n${response}`);
       }
     } else {
-      // Chat Completions API: Use native JSON mode
+      // Chat Completions API: Use native JSON mode.
+      // Build system message as: JSON_SYSTEM + agentInstructions + cachedContext.
+      // Putting agentInstructions in the system message (not the user message) makes the full
+      // prefix eligible for OpenAI automatic prefix caching — identical system prefixes across
+      // repeated calls of the same stage type get a 90% discount after the first 1024 tokens.
+      const JSON_SYSTEM = 'You are a helpful assistant that always returns valid JSON. Your response must be a valid JSON object or array, nothing else.';
+      const systemParts = [JSON_SYSTEM];
+      if (agentInstructions) systemParts.push(agentInstructions);
+      if (cachedContext) systemParts.push(`---\n\n${cachedContext}`);
+      const systemContent = systemParts.join('\n\n');
+
       const messages = [
-        {
-          role: 'system',
-          content: 'You are a helpful assistant that always returns valid JSON. Your response must be a valid JSON object or array, nothing else.'
-        },
-        {
-          role: 'user',
-          content: fullPrompt
-        }
+        { role: 'system', content: systemContent },
+        { role: 'user',   content: prompt },
       ];
 
       const params = {
         model: this.model,
-        messages
+        messages,
       };
 
       // Use model-specific maximum tokens
       const maxTokens = getMaxTokensForModel(this.model);
 
-      // GPT-5+ models use max_completion_tokens, older models use max_tokens
-      if (this.model.startsWith('gpt-5') || this.model.startsWith('o1') || this.model.startsWith('o3')) {
-        params.max_completion_tokens = maxTokens;
-      } else {
+      // max_completion_tokens is the modern unified parameter; max_tokens is only for legacy gpt-3.5-turbo
+      if (this.model.startsWith('gpt-3.5')) {
         params.max_tokens = maxTokens;
+      } else {
+        params.max_completion_tokens = maxTokens;
       }
 
       // Enable JSON mode if model supports it (GPT-4+)
@@ -158,13 +325,38 @@ export class OpenAIProvider extends LLMProvider {
         params.response_format = { type: 'json_object' };
       }
 
+      // Extended 24-hour cache retention — free on gpt-5.x and gpt-4.1+ families.
+      // Keeps the system-message prefix in cache across long ceremony runs (>1 hr).
+      if (this.model.startsWith('gpt-5') || this.model.startsWith('gpt-4.1')) {
+        params.prompt_cache_retention = '24h';
+      }
+
+      const _t0Json = Date.now();
       const response = await this._withRetry(
         () => this._client.chat.completions.create(params),
         'JSON generation (Chat Completions)'
       );
 
-      this._trackTokens(response.usage);
-      const content = response.choices[0].message.content;
+      const choice = response.choices[0];
+      const content = choice.message.content;
+
+      // Detect output truncation — json_object mode returns null/empty when cut off at token limit
+      if (choice.finish_reason === 'length' || !content) {
+        const maxTok = getMaxTokensForModel(this.model);
+        const usedOut = response.usage?.completion_tokens ?? '?';
+        throw new Error(
+          `Response truncated at token limit (finish_reason=length). ` +
+          `Model: ${this.model}, limit: ${maxTok}, used: ${usedOut}. ` +
+          `Increase max tokens for this model in llm-token-limits.js or reduce prompt size.`
+        );
+      }
+
+      this._trackTokens(response.usage, {
+        prompt: fullPrompt,
+        agentInstructions: agentInstructions ?? null,
+        response: content,
+        elapsed: Date.now() - _t0Json,
+      });
 
       // Strip markdown code fences if present (defense-in-depth)
       let jsonStr = content.trim();
@@ -187,47 +379,76 @@ export class OpenAIProvider extends LLMProvider {
     }
   }
 
-  async generateText(prompt, agentInstructions = null) {
+  async generateText(prompt, agentInstructions = null, cachedContext = null) {
     if (!this._client) {
       this._client = this._createClient();
     }
 
+    // OAuth path — route through ChatGPT Codex endpoint
+    if (this._client?.mode === 'oauth') {
+      try {
+        return await this._callChatGPTCodex(prompt, agentInstructions);
+      } catch (oauthErr) {
+        if (!this._hasFallback()) throw oauthErr;
+        console.warn(`[openai] OAuth call failed, falling back to API key: ${oauthErr.message}`);
+        this._client = this._createApiKeyClient();
+        // fall through to standard paths below
+      }
+    }
+
     const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
 
     if (this._usesResponsesAPI()) {
       // Responses API
-      return await this._callResponsesAPI(fullPrompt, null);
+      const _rApiPayload = this._promptLogger ? { prompt: fullPrompt, agentInstructions: agentInstructions ?? null } : null;
+      return await this._callResponsesAPI(fullPrompt, null, _rApiPayload);
     } else {
-      // Chat Completions API
-      const messages = [
-        {
-          role: 'user',
-          content: fullPrompt
-        }
-      ];
+      // Chat Completions API.
+      // Build system message as agentInstructions + cachedContext so both are eligible for
+      // OpenAI automatic prefix caching (90% discount when system prefix is stable across calls).
+      const systemParts = [];
+      if (agentInstructions) systemParts.push(agentInstructions);
+      if (cachedContext) systemParts.push(cachedContext);
+      const messages = [];
+      if (systemParts.length > 0) {
+        messages.push({ role: 'system', content: systemParts.join('\n\n') });
+      }
+      messages.push({ role: 'user', content: prompt });
 
       const params = {
         model: this.model,
-        messages
+        messages,
       };
 
       // Use model-specific maximum tokens
       const maxTokens = getMaxTokensForModel(this.model);
 
-      // GPT-5+ models use max_completion_tokens, older models use max_tokens
-      if (this.model.startsWith('gpt-5') || this.model.startsWith('o1') || this.model.startsWith('o3')) {
-        params.max_completion_tokens = maxTokens;
-      } else {
+      // max_completion_tokens is the modern unified parameter; max_tokens is only for legacy gpt-3.5-turbo
+      if (this.model.startsWith('gpt-3.5')) {
         params.max_tokens = maxTokens;
+      } else {
+        params.max_completion_tokens = maxTokens;
+      }
+
+      // Extended 24-hour cache retention — free on gpt-5.x and gpt-4.1+ families.
+      if (this.model.startsWith('gpt-5') || this.model.startsWith('gpt-4.1')) {
+        params.prompt_cache_retention = '24h';
       }
 
+      const _t0Text = Date.now();
       const response = await this._withRetry(
         () => this._client.chat.completions.create(params),
         'Text generation (Chat Completions)'
       );
 
-      this._trackTokens(response.usage);
-      return response.choices[0].message.content;
+      const textContent = response.choices[0].message.content;
+      this._trackTokens(response.usage, {
+        prompt: fullPrompt,
+        agentInstructions: agentInstructions ?? null,
+        response: textContent,
+        elapsed: Date.now() - _t0Text,
+      });
+      return textContent;
     }
   }
 }

package/cli/llm-provider.js

@@ -6,6 +6,8 @@ export class LLMProvider {
     this.tokenUsage = {
       inputTokens: 0,
       outputTokens: 0,
+      cachedInputTokens: 0,  // cache reads (already counted inside inputTokens)
+      cacheWriteTokens: 0,   // cache writes (billed at 1.25× on Claude, free on OpenAI/Gemini)
       totalCalls: 0
     };
 
@@ -71,7 +73,15 @@ export class LLMProvider {
       'rate limit',
       'quota exceeded',
       'resource exhausted',
-      'resource has been exhausted'
+      'resource has been exhausted',
+      // Transient network/connection errors (e.g. WSL2 IPv6, momentary TCP failures)
+      'connection error',
+      'econnreset',
+      'econnrefused',
+      'enotfound',
+      'etimedout',
+      'network error',
+      'fetch failed',
     ];
 
     const hasHighDemandMessage = highDemandPatterns.some(pattern =>
@@ -146,7 +156,8 @@ export class LLMProvider {
         // Log retry attempt with helpful info
         const retrySource = retryAfterDelay ? 'server directive' : 'exponential backoff';
         console.log(`\n⏳ ${operationName} failed (attempt ${attempt + 1}/${this.retryConfig.maxRetries + 1})`);
-        console.log(`   Error: ${error.message}`);
+        const causeMsg = error.cause?.message || error.cause?.code || '';
+        console.log(`   Error: ${error.message}${causeMsg ? ` (cause: ${causeMsg})` : ''}`);
         console.log(`   Retrying in ${currentDelay / 1000}s (${retrySource})...`);
 
         // Wait before retrying
@@ -174,23 +185,64 @@ export class LLMProvider {
     this._callCallbacks.push(fn);
   }
 
+  /**
+   * Attach a PromptLogger instance and set the stage label for subsequent calls.
+   * @param {import('./prompt-logger.js').PromptLogger} promptLogger
+   * @param {string} [stage]
+   */
+  setPromptLogger(promptLogger, stage) {
+    this._promptLogger = promptLogger;
+    this._promptLoggerStage = stage || 'unknown';
+  }
+
   /**
    * Track token usage from API response and fire per-call callbacks.
+   * Optionally writes a prompt/response payload to the attached PromptLogger.
    * @param {Object} usage - Usage object from API response
+   * @param {Object|null} [promptPayload] - Optional { prompt, agentInstructions, response, elapsed }
    */
-  _trackTokens(usage) {
+  _trackTokens(usage, promptPayload = null) {
     if (usage) {
       const deltaIn  = usage.input_tokens  || usage.inputTokens  || usage.promptTokenCount    || usage.prompt_tokens    || 0;
       const deltaOut = usage.output_tokens || usage.outputTokens || usage.candidatesTokenCount || usage.completion_tokens || 0;
-      this.tokenUsage.inputTokens  += deltaIn;
-      this.tokenUsage.outputTokens += deltaOut;
+      // Cache stats — each provider uses a different field name:
+      //   Claude:  cache_read_input_tokens / cache_creation_input_tokens
+      //   OpenAI:  prompt_tokens_details.cached_tokens
+      //   Gemini:  cachedContentTokenCount
+      const deltaCacheRead  = usage.cache_read_input_tokens
+        || usage.cachedContentTokenCount
+        || usage.prompt_tokens_details?.cached_tokens
+        || 0;
+      const deltaCacheWrite = usage.cache_creation_input_tokens || 0;
+      this.tokenUsage.inputTokens       += deltaIn;
+      this.tokenUsage.outputTokens      += deltaOut;
+      this.tokenUsage.cachedInputTokens += deltaCacheRead;
+      this.tokenUsage.cacheWriteTokens  += deltaCacheWrite;
       this.tokenUsage.totalCalls++;
+      if (deltaCacheRead > 0 || deltaCacheWrite > 0) {
+        console.log(`   [cache] write=${deltaCacheWrite} read=${deltaCacheRead} tokens`);
+      }
       if (this._callCallbacks.length > 0 && (deltaIn > 0 || deltaOut > 0)) {
-        const delta = { input: deltaIn, output: deltaOut, provider: this.providerName, model: this.model };
+        const delta = { input: deltaIn, output: deltaOut, cached: deltaCacheRead, cacheWrite: deltaCacheWrite, provider: this.providerName, model: this.model };
         for (const fn of this._callCallbacks) {
           try { fn(delta); } catch (_) {}
         }
       }
+      if (this._promptLogger && promptPayload) {
+        this._promptLogger.write({
+          ceremony: this._promptLogger.ceremony,
+          stage: this._promptLoggerStage || 'unknown',
+          call: (this._promptLogger.callCount || 0) + 1,
+          timestamp: new Date().toISOString(),
+          elapsed_ms: promptPayload.elapsed ?? null,
+          provider: this.providerName,
+          model: this.model,
+          tokens: { input: deltaIn, output: deltaOut },
+          prompt: promptPayload.prompt ?? null,
+          agentInstructions: promptPayload.agentInstructions ?? null,
+          response: promptPayload.response ?? null,
+        });
+      }
     }
   }
 
@@ -205,7 +257,9 @@ export class LLMProvider {
     const pricing = {
       'claude': { input: 3.00, output: 15.00 },  // Claude Sonnet 4.5
       'gemini': { input: 0.15, output: 0.60 },   // Gemini 2.0 Flash
-      'openai': { input: 1.75, output: 14.00 }   // GPT-5.2
+      'openai': { input: 1.75, output: 14.00 },  // GPT-5.2
+      'local':  { input: 0,    output: 0 },       // Local models — free
+      'xiaomi': { input: 0.09, output: 0.29 }     // MiMo V2 Flash (default)
     };
 
     const rates = pricing[this.providerName] || { input: 0, output: 0 };
@@ -216,6 +270,8 @@ export class LLMProvider {
     return {
       inputTokens: this.tokenUsage.inputTokens,
       outputTokens: this.tokenUsage.outputTokens,
+      cachedInputTokens: this.tokenUsage.cachedInputTokens,
+      cacheWriteTokens: this.tokenUsage.cacheWriteTokens,
       totalTokens: total,
       totalCalls: this.tokenUsage.totalCalls,
       estimatedCost,
@@ -224,6 +280,81 @@ export class LLMProvider {
     };
   }
 
+  /**
+   * Map of cloud providers to their required env var.
+   */
+  static PROVIDER_ENV_MAP = {
+    'claude': 'ANTHROPIC_API_KEY',
+    'gemini': 'GEMINI_API_KEY',
+    'openai': 'OPENAI_API_KEY',
+    'xiaomi': 'XIAOMI_API_KEY',
+  };
+
+  /**
+   * Default model per provider (used as fallback when switching providers).
+   */
+  static PROVIDER_DEFAULT_MODELS = {
+    'claude': 'claude-sonnet-4-6',
+    'gemini': 'gemini-2.5-flash',
+    'openai': 'gpt-4.1',
+    'xiaomi': 'MiMo-V2-Flash',
+  };
+
+  /**
+   * Check whether a provider has valid credentials available.
+   * For cloud providers this means the env var is set.
+   * For local, probe the server (with a short timeout).
+   * @param {string} providerName
+   * @returns {Promise<boolean>}
+   */
+  static async hasProviderCredentials(providerName) {
+    if (providerName === 'local') {
+      try {
+        const { discoverLocalServers } = await import('./llm-local.js');
+        const servers = await Promise.race([
+          discoverLocalServers(),
+          new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000))
+        ]);
+        return servers.length > 0;
+      } catch {
+        return false;
+      }
+    }
+    if (providerName === 'openai') {
+      const oauthMode = process.env.OPENAI_AUTH_MODE === 'oauth';
+      return !!(process.env.OPENAI_API_KEY || (oauthMode && process.env.OPENAI_OAUTH_TOKEN));
+    }
+    const envVar = LLMProvider.PROVIDER_ENV_MAP[providerName];
+    return envVar ? !!process.env[envVar] : false;
+  }
+
+  /**
+   * Resolve a provider+model pair, falling back to any available provider
+   * if the requested one has no credentials.
+   * @param {string} provider - Requested provider name
+   * @param {string} model - Requested model name
+   * @returns {Promise<{ provider: string, model: string, fellBack: boolean }>}
+   */
+  static async resolveAvailableProvider(provider, model) {
+    // Check requested provider first
+    if (await LLMProvider.hasProviderCredentials(provider)) {
+      return { provider, model, fellBack: false };
+    }
+
+    // Fallback priority: claude → gemini → openai → xiaomi → local
+    const fallbackOrder = ['claude', 'gemini', 'openai', 'xiaomi', 'local'];
+    for (const candidate of fallbackOrder) {
+      if (candidate === provider) continue; // already checked
+      if (await LLMProvider.hasProviderCredentials(candidate)) {
+        const fallbackModel = LLMProvider.PROVIDER_DEFAULT_MODELS[candidate] || candidate;
+        return { provider: candidate, model: fallbackModel, fellBack: true };
+      }
+    }
+
+    // Nothing available — return original and let create() throw the usual error
+    return { provider, model, fellBack: false };
+  }
+
   // Factory — async because of dynamic import (only loads the SDK you need)
   static async create(providerName, model) {
     // AVC_LLM_MOCK=1: return instant mock provider for E2E testing (no API calls)
@@ -245,8 +376,16 @@ export class LLMProvider {
         const { OpenAIProvider } = await import('./llm-openai.js');
         return new OpenAIProvider(model);
       }
+      case 'local': {
+        const { LocalProvider } = await import('./llm-local.js');
+        return new LocalProvider(model);
+      }
+      case 'xiaomi': {
+        const { XiaomiProvider } = await import('./llm-xiaomi.js');
+        return new XiaomiProvider(model);
+      }
       default:
-        throw new Error(`Unknown LLM provider: "${providerName}". Supported: claude, gemini, openai`);
+        throw new Error(`Unknown LLM provider: "${providerName}". Supported: claude, gemini, openai, local, xiaomi`);
     }
   }