@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/cli/llm-mock.js

@@ -0,0 +1,233 @@
+/**
+ * MockLLMProvider — instant canned responses for E2E testing.
+ * Activated when AVC_LLM_MOCK=1 is set in the environment.
+ *
+ * Detects what kind of response to return by inspecting the prompt text.
+ */
+export class MockLLMProvider {
+  constructor() {
+    this.providerName = 'mock';
+    this.model = 'mock-model';
+    this.tokenUsage = { inputTokens: 0, outputTokens: 0, totalCalls: 0 };
+  }
+
+  async validateApiKey() {
+    return { valid: true };
+  }
+
+  getTokenUsage() {
+    return {
+      inputTokens: this.tokenUsage.inputTokens,
+      outputTokens: this.tokenUsage.outputTokens,
+      totalTokens: this.tokenUsage.inputTokens + this.tokenUsage.outputTokens,
+      totalCalls: this.tokenUsage.totalCalls,
+      estimatedCost: 0,
+      provider: 'mock',
+      model: 'mock-model'
+    };
+  }
+
+  _track(prompt = '') {
+    this.tokenUsage.inputTokens += Math.ceil(prompt.length / 4);
+    this.tokenUsage.outputTokens += 50;
+    this.tokenUsage.totalCalls++;
+  }
+
+  /** generateJSON — detect call type from agent instructions (most reliable discriminator) */
+  async generateJSON(prompt, agentInstructions = null) {
+    this._track(prompt);
+
+    const p = (prompt || '').toLowerCase();
+    // Use agent instructions filename/content as the primary discriminator — it's
+    // more reliable than prompt text which can contain overlapping keywords.
+    const agent = (agentInstructions || '').toLowerCase();
+
+    // Validation calls (validator-documentation.md / validator-context.md)
+    // validator-documentation.md contains "validationStatus" and "overallScore" as output fields
+    if (agent.includes('validationstatus') || agent.includes('overallscore') ||
+        p.includes('validate the following')) {
+      return {
+        validationStatus: 'acceptable',
+        overallScore: 90,
+        issues: [],
+        contentIssues: [],
+        structuralIssues: [],
+        applicationFlowGaps: [],
+        strengths: ['Well-structured document (mock validation)'],
+        improvementPriorities: [],
+        readyForPublication: true,
+        readyForUse: true
+      };
+    }
+
+    // Database recommendation (database-recommender.md)
+    // database-recommender.md uniquely contains "hasDatabaseNeeds" as an output field
+    if (agent.includes('hasdatabaseneeds') || p.includes('determine if it needs a database')) {
+      return {
+        hasDatabaseNeeds: true,
+        comparison: {
+          sqlOption: {
+            database: 'PostgreSQL',
+            specificVersion: 'PostgreSQL 16',
+            bestFor: 'Relational data with ACID guarantees',
+            strengths: ['Strong consistency', 'Rich query language', 'Mature ecosystem'],
+            weaknesses: ['Schema migrations required'],
+            estimatedCosts: { monthly: '$0 (local Docker)' }
+          },
+          nosqlOption: {
+            database: 'MongoDB',
+            specificVersion: 'MongoDB 7',
+            bestFor: 'Flexible document storage',
+            strengths: ['Schema flexibility', 'Easy horizontal scaling'],
+            weaknesses: ['Eventual consistency by default'],
+            estimatedCosts: { monthly: '$0 (local Docker)' }
+          },
+          keyMetrics: {
+            estimatedReadWriteRatio: '70/30',
+            expectedThroughput: 'Low-medium (< 1000 req/s)',
+            dataComplexity: 'Medium — relational entities with joins'
+          }
+        },
+        recommendation: 'sql',
+        confidence: 85,
+        reasoning: 'Mock: task management apps benefit from relational integrity'
+      };
+    }
+
+    // Architecture recommendations (architecture-recommender.md)
+    // architecture-recommender.md uniquely contains "requiresCloudProvider" as an output field
+    if (agent.includes('requirescloudprovider') || p.includes('recommend 3-5') || p.includes('deployment architectures')) {
+      return {
+        architectures: [
+          {
+            name: 'Local Hybrid Stack',
+            description: 'Express.js/FastAPI backend on localhost with PostgreSQL in Docker',
+            requiresCloudProvider: false,
+            bestFor: 'Experienced developers who want fast debugging with database isolation',
+            migrationPath: {
+              targetCloud: 'AWS ECS / Azure Container Apps / GCP Cloud Run',
+              steps: [
+                'Containerize backend with Docker',
+                'Push images to ECR/ACR/GCR',
+                'Deploy to container orchestration service'
+              ]
+            }
+          },
+          {
+            name: 'Full Docker Compose',
+            description: 'All services in Docker Compose — database, backend, and frontend',
+            requiresCloudProvider: false,
+            bestFor: 'Teams who want identical environments across all machines',
+            migrationPath: {
+              targetCloud: 'AWS ECS / GCP Cloud Run',
+              steps: ['Convert docker-compose.yml to ECS task definitions', 'Set up managed database']
+            }
+          }
+        ]
+      };
+    }
+
+    // Question prefilling (question-prefiller.md)
+    // question-prefiller.md uniquely contains "TARGET_USERS" as an output field
+    if (agent.includes('target_users') || p.includes('target_users')) {
+      return {
+        TARGET_USERS: 'Developers and project teams managing software development tasks',
+        DEPLOYMENT_TARGET: 'Local development environment using Docker Compose; ready to migrate to AWS ECS or Azure Container Apps for production',
+        TECHNICAL_CONSIDERATIONS: 'Node.js/Express.js or FastAPI backend, React 18 + Vite frontend, PostgreSQL 16 in Docker for local development with production migration path',
+        SECURITY_AND_COMPLIANCE_REQUIREMENTS: 'JWT authentication with refresh tokens, bcrypt password hashing, HTTPS in production, standard OWASP security practices'
+      };
+    }
+
+    // Context generation (project-context-generator.md)
+    // project-context-generator.md uniquely contains "contextMarkdown" as an output field
+    if (agent.includes('contextmarkdown') || agent.includes('context generator')) {
+      const mockContext = `# Project Context
+
+**Mission:** Build a test task manager app
+**Architecture:** Local Hybrid Stack
+**Database:** PostgreSQL 16
+**Tech Stack:** Node.js, Express.js, React 18, Vite
+**Deployment:** Local Docker Compose → AWS ECS
+`;
+      return {
+        contextMarkdown: mockContext,
+        tokenCount: Math.ceil(mockContext.length / 4),
+        withinBudget: true
+      };
+    }
+
+    // Generic fallback
+    return { result: 'Mock JSON response', success: true };
+  }
+
+  /** generate — return a mock sponsor-call document */
+  async generate(prompt, maxTokens = 256, systemInstructions = null) {
+    this._track(prompt);
+
+    const p = (prompt || '').toLowerCase();
+
+    // Document generation
+    if (p.includes('sponsor') || p.includes('project brief') || p.includes('enhance')) {
+      return `# Sponsor Call — Test Task Manager
+
+## Mission Statement
+Build a test task manager app to help teams manage development tasks efficiently.
+
+## Initial Scope & Key Features
+MVP with task creation and basic authentication.
+
+## Target Users
+Developers and project teams managing software development tasks.
+
+## Deployment Target
+Local development environment with Docker Compose. Ready to migrate to AWS ECS when needed.
+
+## Technical Considerations
+Node.js/Express.js backend, React 18 + Vite frontend, PostgreSQL 16 in Docker.
+
+## Security & Compliance
+JWT authentication with refresh tokens, bcrypt password hashing, HTTPS in production.
+
+## Architecture
+Local Hybrid Stack: backend on localhost, database in Docker for isolation.
+
+---
+*Generated by AVC mock provider for E2E testing*
+`;
+    }
+
+    // Improvement pass (iterative validation improve step)
+    if (p.includes('improve') || p.includes('enhancement')) {
+      return `# Sponsor Call — Test Task Manager (Improved)
+
+## Mission Statement
+Build a comprehensive test task manager app for development teams.
+
+## Initial Scope & Key Features
+MVP with task creation, assignment, and basic JWT authentication.
+
+## Target Users
+Software development teams and individual developers.
+
+## Deployment Target
+Local development with Docker Compose, production on AWS ECS.
+
+## Technical Considerations
+Express.js/Node.js backend, React 18 frontend, PostgreSQL 16 in Docker container.
+
+## Security & Compliance
+JWT + bcrypt authentication, OWASP security practices.
+
+---
+*Improved by AVC mock provider for E2E testing*
+`;
+    }
+
+    return 'Mock text response from AVC E2E mock provider.';
+  }
+
+  /** generateText — alias for generate (used by migration guide generator) */
+  async generateText(prompt, agentInstructions = null) {
+    return this.generate(prompt, 4096, agentInstructions);
+  }
+}

package/cli/llm-openai.js

@@ -0,0 +1,454 @@
+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') {
+    super('openai', model);
+    this.reasoningEffort = reasoningEffort;
+  }
+
+  _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
+   */
+  _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
+    };
+
+    // 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);
+
+    this._trackTokens(response.usage);
+    return response.choices[0].message.content;
+  }
+
+  /**
+   * 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, promptPayload = null) {
+    // 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 _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) {
+      const finalPayload = promptPayload ? {
+        ...promptPayload,
+        response: text,
+        elapsed: _elapsed,
+      } : null;
+      this._trackTokens(response.usage, finalPayload);
+    }
+
+    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 {
+      return await this._callChatCompletions(prompt, maxTokens, systemInstructions);
+    }
+  }
+
+  /** 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 _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();
+      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.
+      // 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: systemContent },
+        { role: 'user',   content: prompt },
+      ];
+
+      const params = {
+        model: this.model,
+        messages,
+      };
+
+      // Use model-specific maximum tokens
+      const maxTokens = getMaxTokensForModel(this.model);
+
+      // 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+)
+      if (this.model.startsWith('gpt-4') || this.model.startsWith('gpt-5') || this.model.startsWith('o')) {
+        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)'
+      );
+
+      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();
+      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, 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
+      const _rApiPayload = this._promptLogger ? { prompt: fullPrompt, agentInstructions: agentInstructions ?? null } : null;
+      return await this._callResponsesAPI(fullPrompt, null, _rApiPayload);
+    } else {
+      // 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,
+      };
+
+      // Use model-specific maximum tokens
+      const maxTokens = getMaxTokensForModel(this.model);
+
+      // 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)'
+      );
+
+      const textContent = response.choices[0].message.content;
+      this._trackTokens(response.usage, {
+        prompt: fullPrompt,
+        agentInstructions: agentInstructions ?? null,
+        response: textContent,
+        elapsed: Date.now() - _t0Text,
+      });
+      return textContent;
+    }
+  }
+}