@agile-vibe-coding/avc 0.1.0 → 0.2.3

package/cli/llm-openai.js

@@ -0,0 +1,233 @@
+import OpenAI from 'openai';
+import { jsonrepair } from 'jsonrepair';
+import { LLMProvider } from './llm-provider.js';
+import { getMaxTokensForModel } from './llm-token-limits.js';
+
+export class OpenAIProvider extends LLMProvider {
+  constructor(model = 'gpt-5.2-chat-latest', reasoningEffort = 'medium') {
+    super('openai', model);
+    this.reasoningEffort = reasoningEffort;
+  }
+
+  _createClient() {
+    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 });
+  }
+
+  /**
+   * Determine if model uses Responses API instead of Chat Completions API
+   * Models that use Responses API: gpt-5.2-pro, gpt-5.2-codex
+   */
+  _usesResponsesAPI() {
+    const responsesAPIModels = ['gpt-5.2-pro', 'gpt-5.2-codex'];
+    return responsesAPIModels.includes(this.model);
+  }
+
+  /**
+   * Call using Chat Completions API (standard models)
+   */
+  async _callChatCompletions(prompt, maxTokens, systemInstructions) {
+    const messages = [];
+
+    // OpenAI uses message array - system instructions go first as system role
+    if (systemInstructions) {
+      messages.push({ role: 'system', content: systemInstructions });
+    }
+
+    messages.push({ role: 'user', content: prompt });
+
+    const params = {
+      model: this.model,
+      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 {
+      params.max_tokens = maxTokens;
+    }
+
+    const response = await this._client.chat.completions.create(params);
+
+    this._trackTokens(response.usage);
+    return response.choices[0].message.content;
+  }
+
+  /**
+   * Call using Responses API (pro/codex models)
+   */
+  async _callResponsesAPI(prompt, systemInstructions) {
+    // Combine system instructions with prompt
+    const fullInput = systemInstructions
+      ? `${systemInstructions}\n\n${prompt}`
+      : prompt;
+
+    const params = {
+      model: this.model,
+      input: fullInput
+    };
+
+    // Add reasoning effort for models that support it
+    if (this.model === 'gpt-5.2-codex' || this.model === 'gpt-5.2-pro') {
+      params.reasoning = { effort: this.reasoningEffort };
+    }
+
+    const response = await this._withRetry(
+      () => this._client.responses.create(params),
+      'Responses API call'
+    );
+
+    // Track tokens if usage data is available
+    if (response.usage) {
+      this._trackTokens(response.usage);
+    }
+
+    return response.output_text;
+  }
+
+  async _callProvider(prompt, maxTokens, systemInstructions) {
+    if (this._usesResponsesAPI()) {
+      return await this._callResponsesAPI(prompt, systemInstructions);
+    } else {
+      return await this._callChatCompletions(prompt, maxTokens, systemInstructions);
+    }
+  }
+
+  async generateJSON(prompt, agentInstructions = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    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);
+
+      // Parse and return JSON
+      let jsonStr = response.trim();
+      if (jsonStr.startsWith('```')) {
+        jsonStr = jsonStr.replace(/^```(?:json)?\s*\n?/, '');
+        jsonStr = jsonStr.replace(/\n?\s*```\s*$/, '');
+        jsonStr = jsonStr.trim();
+      }
+
+      try {
+        return JSON.parse(jsonStr);
+      } catch (firstError) {
+        if (jsonStr.startsWith('{') || jsonStr.startsWith('[')) {
+          try {
+            return JSON.parse(jsonrepair(jsonStr));
+          } catch { /* fall through to throw */ }
+        }
+        throw new Error(`Failed to parse JSON response: ${firstError.message}\n\nResponse was:\n${response}`);
+      }
+    } else {
+      // Chat Completions API: Use native JSON mode
+      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
+        }
+      ];
+
+      const params = {
+        model: this.model,
+        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 {
+        params.max_tokens = maxTokens;
+      }
+
+      // Enable JSON mode if model supports it (GPT-4+)
+      if (this.model.startsWith('gpt-4') || this.model.startsWith('gpt-5') || this.model.startsWith('o')) {
+        params.response_format = { type: 'json_object' };
+      }
+
+      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;
+
+      // Strip markdown code fences if present (defense-in-depth)
+      let jsonStr = content.trim();
+      if (jsonStr.startsWith('```')) {
+        jsonStr = jsonStr.replace(/^```(?:json)?\s*\n?/, '');
+        jsonStr = jsonStr.replace(/\n?\s*```\s*$/, '');
+        jsonStr = jsonStr.trim();
+      }
+
+      try {
+        return JSON.parse(jsonStr);
+      } catch (firstError) {
+        if (jsonStr.startsWith('{') || jsonStr.startsWith('[')) {
+          try {
+            return JSON.parse(jsonrepair(jsonStr));
+          } catch { /* fall through to throw */ }
+        }
+        throw new Error(`Failed to parse JSON response: ${firstError.message}\n\nResponse was:\n${content}`);
+      }
+    }
+  }
+
+  async generateText(prompt, agentInstructions = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n${prompt}` : prompt;
+
+    if (this._usesResponsesAPI()) {
+      // Responses API
+      return await this._callResponsesAPI(fullPrompt, null);
+    } else {
+      // Chat Completions API
+      const messages = [
+        {
+          role: 'user',
+          content: fullPrompt
+        }
+      ];
+
+      const params = {
+        model: this.model,
+        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 {
+        params.max_tokens = maxTokens;
+      }
+
+      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;
+    }
+  }
+}

package/cli/llm-provider.js

@@ -0,0 +1,300 @@
+export class LLMProvider {
+  constructor(providerName, model, retryConfig = {}) {
+    this.providerName = providerName;
+    this.model = model;
+    this._client = null;
+    this.tokenUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalCalls: 0
+    };
+
+    // Per-call token callbacks (fired synchronously after each _trackTokens call)
+    this._callCallbacks = [];
+
+    // Retry configuration
+    this.retryConfig = {
+      maxRetries: retryConfig.maxRetries || 5,
+      initialDelay: retryConfig.initialDelay || 1000, // 1 second
+      maxDelay: retryConfig.maxDelay || 32000, // 32 seconds
+      backoffMultiplier: retryConfig.backoffMultiplier || 2
+    };
+  }
+
+  /**
+   * Check if error is retryable (high demand, rate limit, temporary failures)
+   * Provider-specific error codes:
+   * - OpenAI: 429 (rate limit), 503 (overloaded)
+   * - Claude: 429 (rate_limit_error), 529 (overloaded_error)
+   * - Gemini: 429 (RESOURCE_EXHAUSTED), 503 (UNAVAILABLE/overloaded)
+   *
+   * @param {Error} error - The error to check
+   * @returns {boolean} True if error is retryable
+   */
+  _isRetryableError(error) {
+    const errorMessage = error.message?.toLowerCase() || '';
+    const errorCode = error.status || error.code;
+    const errorType = error.type || error.error?.type || '';
+
+    // Check for provider-specific error codes
+    const retryableStatusCodes = [
+      429,  // Rate limit (all providers)
+      503,  // Service unavailable (OpenAI, Gemini)
+      529   // Overloaded (Claude/Anthropic)
+    ];
+
+    const hasRetryableCode = retryableStatusCodes.includes(errorCode);
+
+    // Check for provider-specific error types
+    const retryableErrorTypes = [
+      'rate_limit_error',      // Claude
+      'overloaded_error',      // Claude
+      'resource_exhausted',    // Gemini
+      'unavailable'            // Gemini
+    ];
+
+    const hasRetryableType = retryableErrorTypes.some(type =>
+      errorType.toLowerCase().includes(type)
+    );
+
+    // Check for high demand/overload message patterns
+    const highDemandPatterns = [
+      'high demand',
+      'experiencing high demand',
+      'spikes in demand',
+      'try again later',
+      'temporarily unavailable',
+      'service unavailable',
+      'overloaded',
+      'model is overloaded',
+      'too many requests',
+      'rate limit',
+      'quota exceeded',
+      'resource exhausted',
+      'resource has been exhausted'
+    ];
+
+    const hasHighDemandMessage = highDemandPatterns.some(pattern =>
+      errorMessage.includes(pattern)
+    );
+
+    return hasRetryableCode || hasRetryableType || hasHighDemandMessage;
+  }
+
+  /**
+   * Sleep for specified milliseconds
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Extract retry delay from error headers (e.g., Claude's retry-after header)
+   * @param {Error} error - The error object
+   * @returns {number|null} Delay in milliseconds, or null if not found
+   */
+  _getRetryAfterDelay(error) {
+    // Check for retry-after header (Claude provides this)
+    const retryAfter = error.headers?.['retry-after'] || error.error?.headers?.['retry-after'];
+
+    if (retryAfter) {
+      // retry-after can be in seconds
+      const seconds = parseInt(retryAfter, 10);
+      if (!isNaN(seconds)) {
+        return seconds * 1000; // Convert to milliseconds
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Execute an async function with exponential backoff retry strategy
+   * Uses retry-after header when available (Claude), otherwise exponential backoff
+   *
+   * @param {Function} fn - Async function to execute
+   * @param {string} operationName - Name of operation for logging
+   * @returns {Promise<any>} Result of the function
+   */
+  async _withRetry(fn, operationName = 'API call') {
+    let lastError;
+    let delay = this.retryConfig.initialDelay;
+
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+
+        // Don't retry if it's not a retryable error
+        if (!this._isRetryableError(error)) {
+          throw error;
+        }
+
+        // Don't retry if we've exhausted all attempts
+        if (attempt === this.retryConfig.maxRetries) {
+          console.error(`\n${operationName} failed after ${this.retryConfig.maxRetries + 1} attempts`);
+          throw error;
+        }
+
+        // Check for retry-after header (Claude provides this)
+        const retryAfterDelay = this._getRetryAfterDelay(error);
+        const currentDelay = retryAfterDelay || delay;
+
+        // 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}`);
+        console.log(`   Retrying in ${currentDelay / 1000}s (${retrySource})...`);
+
+        // Wait before retrying
+        await this._sleep(currentDelay);
+
+        // Exponential backoff with max cap (only if not using retry-after)
+        if (!retryAfterDelay) {
+          delay = Math.min(
+            delay * this.retryConfig.backoffMultiplier,
+            this.retryConfig.maxDelay
+          );
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Register a callback to be fired synchronously after every LLM API call.
+   * Receives { input, output, provider, model } delta for that single call.
+   * @param {Function} fn - Callback function
+   */
+  onCall(fn) {
+    this._callCallbacks.push(fn);
+  }
+
+  /**
+   * Track token usage from API response and fire per-call callbacks.
+   * @param {Object} usage - Usage object from API response
+   */
+  _trackTokens(usage) {
+    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;
+      this.tokenUsage.totalCalls++;
+      if (this._callCallbacks.length > 0 && (deltaIn > 0 || deltaOut > 0)) {
+        const delta = { input: deltaIn, output: deltaOut, provider: this.providerName, model: this.model };
+        for (const fn of this._callCallbacks) {
+          try { fn(delta); } catch (_) {}
+        }
+      }
+    }
+  }
+
+  /**
+   * Get token usage statistics with cost estimate
+   * @returns {Object} Token usage and cost information
+   */
+  getTokenUsage() {
+    const total = this.tokenUsage.inputTokens + this.tokenUsage.outputTokens;
+
+    // Pricing per 1M tokens (as of 2026-02)
+    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
+    };
+
+    const rates = pricing[this.providerName] || { input: 0, output: 0 };
+    const inputCost = (this.tokenUsage.inputTokens / 1000000) * rates.input;
+    const outputCost = (this.tokenUsage.outputTokens / 1000000) * rates.output;
+    const estimatedCost = inputCost + outputCost;
+
+    return {
+      inputTokens: this.tokenUsage.inputTokens,
+      outputTokens: this.tokenUsage.outputTokens,
+      totalTokens: total,
+      totalCalls: this.tokenUsage.totalCalls,
+      estimatedCost,
+      provider: this.providerName,
+      model: this.model
+    };
+  }
+
+  // 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)
+    if (process.env.AVC_LLM_MOCK) {
+      const { MockLLMProvider } = await import('./llm-mock.js');
+      return new MockLLMProvider();
+    }
+
+    switch (providerName) {
+      case 'claude': {
+        const { ClaudeProvider } = await import('./llm-claude.js');
+        return new ClaudeProvider(model);
+      }
+      case 'gemini': {
+        const { GeminiProvider } = await import('./llm-gemini.js');
+        return new GeminiProvider(model);
+      }
+      case 'openai': {
+        const { OpenAIProvider } = await import('./llm-openai.js');
+        return new OpenAIProvider(model);
+      }
+      default:
+        throw new Error(`Unknown LLM provider: "${providerName}". Supported: claude, gemini, openai`);
+    }
+  }
+
+  // Public API — single method, callers never touch SDK objects
+  async generate(prompt, maxTokens = 256, systemInstructions = null) {
+    if (!this._client) {
+      this._client = this._createClient();
+    }
+    return this._withRetry(
+      () => this._callProvider(prompt, maxTokens, systemInstructions),
+      'Text generation'
+    );
+  }
+
+  // Validate API key and provider connectivity with a minimal test call
+  async validateApiKey() {
+    try {
+      // Make a minimal API call (just asks for a single word)
+      await this.generate('Reply with only the word "ok"', 10);
+      return { valid: true };
+    } catch (error) {
+      return {
+        valid: false,
+        error: error.message,
+        code: error.status || error.code
+      };
+    }
+  }
+
+  // Static helper to validate a provider config
+  static async validate(providerName, model) {
+    try {
+      const provider = await LLMProvider.create(providerName, model);
+      return await provider.validateApiKey();
+    } catch (error) {
+      return {
+        valid: false,
+        error: error.message
+      };
+    }
+  }
+
+  // Generate structured JSON output
+  async generateJSON(prompt, agentInstructions = null) {
+    throw new Error(`${this.constructor.name} must implement generateJSON()`);
+  }
+
+  // Subclass hooks — throw if not overridden
+  _createClient() { throw new Error(`${this.constructor.name} must implement _createClient()`); }
+  async _callProvider(prompt, maxTokens, systemInstructions) { throw new Error(`${this.constructor.name} must implement _callProvider()`); }
+}

package/cli/llm-token-limits.js

@@ -0,0 +1,102 @@
+/**
+ * Model-specific maximum output token limits (ACTUAL API MAXIMUMS)
+ *
+ * These limits represent the ACTUAL maximum output tokens each model can generate
+ * according to official API documentation (verified February 2026).
+ *
+ * Critical Updates (Feb 2026):
+ * - Claude 4.x models: 64K-128K tokens (8x-16x previous limits)
+ * - Gemini 2.5 Flash: 65,535 tokens (8x previous limit)
+ * - GPT-4o/mini: 16,384 tokens (unchanged)
+ *
+ * Using actual model limits ensures complete documentation generation without truncation.
+ *
+ * Sources:
+ * - Claude: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/partner-models/claude/
+ * - Gemini: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/
+ * - OpenAI: https://community.openai.com/t/what-is-the-token-limit-of-the-new-version-gpt-4o/752528
+ */
+
+export const MODEL_MAX_TOKENS = {
+  // Claude models (Anthropic)
+  // Source: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/partner-models/claude/
+  'claude-sonnet-4-5-20250929': 64000,  // Was 8192 - ACTUAL: 64,000 tokens
+  'claude-sonnet-4-5': 64000,
+  'claude-sonnet-4': 64000,
+  'claude-opus-4-6': 128000,            // Was 16384 - ACTUAL: 128,000 tokens
+  'claude-opus-4': 128000,
+  'claude-haiku-4-5-20251001': 64000,   // Was 8192 - ACTUAL: 64,000 tokens
+  'claude-haiku-4-5': 64000,
+  'claude-haiku-4': 64000,
+
+  // OpenAI models
+  // Source: https://community.openai.com/t/what-is-the-token-limit-of-the-new-version-gpt-4o/752528
+  'gpt-5.2-chat-latest': 16384,    // Test/future model
+  'gpt-5.2-pro': 16384,
+  'gpt-5.2-codex': 16384,
+  'gpt-4o': 16384,                 // Correct - max 16,384 tokens
+  'gpt-4o-2024-11-20': 16384,
+  'gpt-4o-mini': 16384,            // Correct - max 16,384 tokens
+  'gpt-4-turbo': 4096,
+  'gpt-4': 8192,
+  'gpt-3.5-turbo': 4096,
+
+  // Google Gemini models
+  // Source: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/
+  'gemini-3.1-pro-preview': 65536, // ACTUAL: 65,536 tokens (verified March 2026)
+  'gemini-3-flash-preview': 65536, // ACTUAL: 65,536 tokens (verified March 2026)
+  'gemini-2.5-pro': 65536,         // ACTUAL: 65,536 tokens
+  'gemini-2.5-flash': 65535,       // Was 8192 - ACTUAL: 65,535 tokens
+  'gemini-2.5-flash-lite': 32768,  // ACTUAL: 32,768 tokens
+  'gemini-2.0-flash': 8192,        // Correct - max 8,192 tokens
+  'gemini-2.0-flash-exp': 8192,
+  'gemini-1.5-pro': 8192,
+  'gemini-1.5-flash': 8192,
+  'gemini-pro': 8192,
+
+  // Default fallback
+  'default': 8192
+};
+
+/**
+ * Get maximum output tokens for a specific model
+ * @param {string} modelId - The model identifier
+ * @returns {number} Maximum output tokens supported by the model
+ */
+export function getMaxTokensForModel(modelId) {
+  if (!modelId) {
+    return MODEL_MAX_TOKENS['default'];
+  }
+
+  // Direct lookup
+  if (MODEL_MAX_TOKENS[modelId]) {
+    return MODEL_MAX_TOKENS[modelId];
+  }
+
+  // Fuzzy match for versioned models (e.g., "claude-opus-4-latest" → "claude-opus-4")
+  const baseModel = modelId.split('-').slice(0, 3).join('-');
+  if (MODEL_MAX_TOKENS[baseModel]) {
+    return MODEL_MAX_TOKENS[baseModel];
+  }
+
+  // Fallback to default
+  console.warn(`No max tokens configured for model "${modelId}", using default: ${MODEL_MAX_TOKENS['default']}`);
+  return MODEL_MAX_TOKENS['default'];
+}
+
+/**
+ * Validate if requested tokens exceed model limit
+ * @param {string} modelId - The model identifier
+ * @param {number} requestedTokens - Requested output tokens
+ * @returns {number} Clamped token value within model limits
+ */
+export function clampTokensToModelLimit(modelId, requestedTokens) {
+  const maxTokens = getMaxTokensForModel(modelId);
+
+  if (requestedTokens > maxTokens) {
+    console.warn(`Requested ${requestedTokens} tokens for ${modelId}, clamping to model limit: ${maxTokens}`);
+    return maxTokens;
+  }
+
+  return requestedTokens;
+}