@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/cli/llm-provider.js

@@ -1,12 +1,368 @@
 export class LLMProvider {
-  constructor(providerName, model) {
+  constructor(providerName, model, retryConfig = {}) {
     this.providerName = providerName;
     this.model = model;
     this._client = null;
+    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
+    };
+
+    // 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',
+      // 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 =>
+      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})`);
+        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
+        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);
+  }
+
+  /**
+   * 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, 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;
+      // 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, 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,
+        });
+      }
+    }
+  }
+
+  /**
+   * 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
+      '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 };
+    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,
+      cachedInputTokens: this.tokenUsage.cachedInputTokens,
+      cacheWriteTokens: this.tokenUsage.cacheWriteTokens,
+      totalTokens: total,
+      totalCalls: this.tokenUsage.totalCalls,
+      estimatedCost,
+      provider: this.providerName,
+      model: this.model
+    };
+  }
+
+  /**
+   * 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)
+    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');
@@ -16,8 +372,20 @@ export class LLMProvider {
         const { GeminiProvider } = await import('./llm-gemini.js');
         return new GeminiProvider(model);
       }
+      case 'openai': {
+        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`);
+        throw new Error(`Unknown LLM provider: "${providerName}". Supported: claude, gemini, openai, local, xiaomi`);
     }
   }
 
@@ -26,7 +394,10 @@ export class LLMProvider {
     if (!this._client) {
       this._client = this._createClient();
     }
-    return this._callProvider(prompt, maxTokens, systemInstructions);
+    return this._withRetry(
+      () => this._callProvider(prompt, maxTokens, systemInstructions),
+      'Text generation'
+    );
   }
 
   // Validate API key and provider connectivity with a minimal test call
@@ -57,6 +428,11 @@ export class LLMProvider {
     }
   }
 
+  // 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,211 @@
+/**
+ * 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
+ */
+
+// Suppress duplicate warnings — each model warned only once per process
+const _warnedModels = new Set();
+
+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 family (32K output tokens assumed; add specific overrides as official limits are confirmed)
+  'gpt-5':         32768,
+  'gpt-5.1':       32768,
+  'gpt-5.2':       32768,
+  'gpt-5.4':       32768,
+  'gpt-5-mini':    32768,
+  'gpt-5.2-chat-latest': 16384,  // Keep at 16384 — existing tests depend on this value
+  '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
+};
+
+/**
+ * Model context window sizes (total input + output tokens)
+ *
+ * These represent the full context window each model supports.
+ * For local models, we use conservative defaults since the actual
+ * model behind the endpoint is unknown.
+ */
+export const MODEL_CONTEXT_WINDOWS = {
+  // Claude models
+  'claude-sonnet-4-5': 200000,
+  'claude-sonnet-4': 200000,
+  'claude-opus-4-6': 200000,
+  'claude-opus-4': 200000,
+  'claude-haiku-4-5': 200000,
+  'claude-haiku-4': 200000,
+
+  // OpenAI models
+  'gpt-5': 128000,
+  'gpt-5.1': 128000,
+  'gpt-5.2': 128000,
+  'gpt-5.4': 128000,
+  'gpt-5-mini': 128000,
+  'gpt-4o': 128000,
+  'gpt-4o-mini': 128000,
+  'gpt-4-turbo': 128000,
+  'gpt-4': 8192,
+
+  // Google Gemini models
+  'gemini-3.1-pro-preview': 1048576,
+  'gemini-3-flash-preview': 1048576,
+  'gemini-2.5-pro': 1048576,
+  'gemini-2.5-flash': 1048576,
+  'gemini-2.0-flash': 1048576,
+  'gemini-1.5-pro': 2097152,
+  'gemini-1.5-flash': 1048576,
+
+  // Default for unknown local models - conservative estimate
+  'local-default': 8192,
+
+  // Xiaomi MiMo models
+  'mimo-v2-flash': 262144,
+  'mimo-v2-pro': 1048576,
+  'mimo-v2-omni': 262144,
+};
+
+/**
+ * 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];
+  }
+
+  // Prefix fallback: catch any gpt-5.x variant not explicitly listed
+  if (modelId.startsWith('gpt-5')) {
+    if (!_warnedModels.has(modelId)) {
+      _warnedModels.add(modelId);
+      console.warn(`No exact max tokens for "${modelId}", using GPT-5 family default: 32768`);
+    }
+    return 32768;
+  }
+
+  // Fallback to default
+  if (!_warnedModels.has(modelId)) {
+    _warnedModels.add(modelId);
+    console.warn(`No max tokens configured for model "${modelId}", using default: ${MODEL_MAX_TOKENS['default']}`);
+  }
+  return MODEL_MAX_TOKENS['default'];
+}
+
+/**
+ * Get the context window size for a specific model
+ * @param {string} modelId - The model identifier
+ * @param {string} provider - The provider name ('claude', 'openai', 'gemini', 'local')
+ * @returns {number|null} Context window size in tokens, or null if no limit enforcement
+ */
+export function getContextWindowForModel(modelId, provider) {
+  // Local provider: use conservative default, overridable via env var
+  if (provider === 'local') {
+    const envOverride = process.env.LOCAL_LLM_CONTEXT_WINDOW;
+    if (envOverride) {
+      const parsed = parseInt(envOverride, 10);
+      if (!isNaN(parsed) && parsed > 0) {
+        return parsed;
+      }
+      console.warn(`Invalid LOCAL_LLM_CONTEXT_WINDOW value "${envOverride}", using default: ${MODEL_CONTEXT_WINDOWS['local-default']}`);
+    }
+    return MODEL_CONTEXT_WINDOWS['local-default'];
+  }
+
+  if (!modelId) {
+    return null;
+  }
+
+  // Direct lookup
+  if (MODEL_CONTEXT_WINDOWS[modelId]) {
+    return MODEL_CONTEXT_WINDOWS[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_CONTEXT_WINDOWS[baseModel]) {
+    return MODEL_CONTEXT_WINDOWS[baseModel];
+  }
+
+  // Unknown cloud model — no limit enforcement
+  return null;
+}
+
+/**
+ * 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) {
+    const clampKey = `clamp:${modelId}:${requestedTokens}`;
+    if (!_warnedModels.has(clampKey)) {
+      _warnedModels.add(clampKey);
+      console.warn(`Requested ${requestedTokens} tokens for ${modelId}, clamping to model limit: ${maxTokens}`);
+    }
+    return maxTokens;
+  }
+
+  return requestedTokens;
+}