openlore 2.0.0

package/dist/core/services/llm-service.js

@@ -0,0 +1,1553 @@
+/**
+ * LLM Service
+ *
+ * Provides a clean interface for LLM interactions with proper error handling,
+ * retry logic, token management, and cost tracking.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import logger from '../../utils/logger.js';
+import { CLAUDE_MAX_CONTEXT_TOKENS, CLAUDE_MAX_OUTPUT_TOKENS, MISTRAL_VIBE_MAX_CONTEXT_TOKENS, MISTRAL_VIBE_MAX_OUTPUT_TOKENS, LLM_CLI_MAX_BUFFER_BYTES, LLM_CLI_TIMEOUT_MS, DEFAULT_ANTHROPIC_MODEL, DEFAULT_OPENAI_MODEL, DEFAULT_OPENAI_COMPAT_MODEL, DEFAULT_COPILOT_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_LLM_MAX_RETRIES, DEFAULT_LLM_INITIAL_DELAY_MS, DEFAULT_LLM_MAX_DELAY_MS, DEFAULT_LLM_TIMEOUT_MS, DEFAULT_LLM_COST_WARNING_THRESHOLD, CONTEXT_LIMIT_WARNING_RATIO, OPENLORE_DIR, OPENLORE_LOGS_SUBDIR, } from '../../constants.js';
+// ============================================================================
+// CLAUDE CODE PROVIDER (uses local `claude` CLI, no API key required)
+// ============================================================================
+/**
+ * Claude Code CLI provider
+ *
+ * Routes LLM calls through the local `claude` CLI binary in non-interactive
+ * mode (`claude -p ...`).  Authentication is handled by the Claude Code session
+ * (Max/Pro subscription) — no ANTHROPIC_API_KEY is required.
+ */
+export class ClaudeCodeProvider {
+    name = 'claude-code';
+    maxContextTokens = CLAUDE_MAX_CONTEXT_TOKENS;
+    maxOutputTokens = CLAUDE_MAX_OUTPUT_TOKENS;
+    model;
+    constructor(model) {
+        // Only pass --model if it looks like a Claude model name.
+        // Ignore the sentinel 'claude-code' string and non-Claude model names
+        // (e.g. 'mistral-large-latest' from a shared config).
+        this.model = model && model !== 'claude-code' && model.startsWith('claude-') ? model : undefined;
+    }
+    async generateCompletion(request) {
+        const { execFileSync } = await import('child_process');
+        // Claude Code CLI takes a single prompt; combine system + user prompts
+        const fullPrompt = request.systemPrompt
+            ? `${request.systemPrompt}\n\n---\n\n${request.userPrompt}`
+            : request.userPrompt;
+        const args = ['-p', fullPrompt, '--output-format', 'json'];
+        if (this.model)
+            args.push('--model', this.model);
+        // Remove Claude Code session env vars so the CLI can run inside an existing session
+        const env = { ...process.env };
+        delete env.CLAUDECODE;
+        delete env.CLAUDE_CODE_ENTRYPOINT;
+        delete env.CLAUDE_CODE_SSE_PORT;
+        delete env.CLAUDE_CODE_IDE_PORT;
+        let raw;
+        try {
+            raw = execFileSync('claude', args, {
+                encoding: 'utf8',
+                maxBuffer: LLM_CLI_MAX_BUFFER_BYTES,
+                timeout: LLM_CLI_TIMEOUT_MS,
+                env,
+            });
+        }
+        catch (err) {
+            const e = err;
+            const detail = e.stderr || e.stdout || e.message || String(err);
+            throw Object.assign(new Error(`claude CLI failed: ${detail}`), { retryable: false });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`claude CLI returned non-JSON output: ${raw.slice(0, 200)}`);
+        }
+        if (parsed.is_error) {
+            throw Object.assign(new Error(`claude CLI error: ${parsed.result}`), { retryable: false });
+        }
+        const inputTokens = parsed.usage?.input_tokens ?? estimateTokens(fullPrompt);
+        const outputTokens = parsed.usage?.output_tokens ?? estimateTokens(parsed.result ?? '');
+        return {
+            content: parsed.result ?? '',
+            usage: { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens },
+            model: this.model ?? 'claude-code',
+            finishReason: 'stop',
+        };
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+}
+// ============================================================================
+// MISTRAL VIBE PROVIDER (uses local `mistral-vibe` CLI, no API key required)
+// ============================================================================
+/**
+ * Mistral Vibe CLI provider
+ *
+ * Routes LLM calls through the local `mistral-vibe` CLI binary (standalone, no npm).
+ * No API key required — uses local LLM execution.
+ * If the binary is not on PATH, set MISTRAL_VIBE_CLI to its full path.
+ * The CLI is invoked as `vibe` (not `mistral-vibe`).
+ */
+export class MistralVibeProvider {
+    name = 'mistral-vibe';
+    maxContextTokens = MISTRAL_VIBE_MAX_CONTEXT_TOKENS;
+    maxOutputTokens = MISTRAL_VIBE_MAX_OUTPUT_TOKENS;
+    model;
+    constructor(model) {
+        // Ignore the sentinel 'mistral-vibe' string — let the CLI pick the default
+        this.model = model && model !== 'mistral-vibe' ? model : undefined;
+    }
+    async generateCompletion(request) {
+        const { execFileSync } = await import('child_process');
+        // Mistral Vibe CLI takes a single prompt; combine system + user prompts
+        const fullPrompt = request.systemPrompt
+            ? `${request.systemPrompt}\n\n---\n\n${request.userPrompt}`
+            : request.userPrompt;
+        // vibe CLI: -p for prompt, --output json for JSON, --agent for model/agent name
+        const args = ['-p', fullPrompt, '--output', 'json'];
+        if (this.model)
+            args.push('--agent', this.model);
+        // Use MISTRAL_VIBE_CLI if set (standalone install not on PATH), else 'vibe'
+        const mistralVibeBin = process.env.MISTRAL_VIBE_CLI ?? 'vibe';
+        let raw;
+        try {
+            raw = execFileSync(mistralVibeBin, args, {
+                encoding: 'utf8',
+                maxBuffer: LLM_CLI_MAX_BUFFER_BYTES,
+                timeout: LLM_CLI_TIMEOUT_MS,
+            });
+        }
+        catch (err) {
+            const e = err;
+            const detail = e.stderr ?? e.stdout ?? e.message ?? String(err);
+            throw Object.assign(new Error(`mistral-vibe CLI failed: ${detail}`), { retryable: false });
+        }
+        // Defensive parsing: vibe --output json format is undocumented.
+        // Try multiple known shapes before falling back to raw text.
+        let content = '';
+        let inputTokens;
+        let outputTokens;
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                // Shape: [{role, content}, ...] — "all messages at end"
+                const msgs = parsed;
+                const lastAssistant = [...msgs].reverse().find(m => m.role === 'assistant');
+                content = String(lastAssistant?.content ?? '');
+            }
+            else if (typeof parsed === 'object' && parsed !== null) {
+                const p = parsed;
+                // Shape: {result: string, usage?: {...}} — Claude Code-style
+                if (typeof p.result === 'string') {
+                    content = p.result;
+                    const u = p.usage;
+                    inputTokens = u?.input_tokens;
+                    outputTokens = u?.output_tokens;
+                    // Shape: {message: string} or {text: string} or {content: string}
+                }
+                else {
+                    content = String(p.message ?? p.text ?? p.content ?? '');
+                }
+            }
+        }
+        catch {
+            // non-JSON output: use raw text
+        }
+        if (!content)
+            content = raw.trim();
+        inputTokens ??= estimateTokens(fullPrompt);
+        outputTokens ??= estimateTokens(content);
+        return {
+            content,
+            usage: { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens },
+            model: this.model ?? 'mistral-vibe',
+            finishReason: 'stop',
+        };
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+}
+// ============================================================================
+// SSL / FETCH HELPERS
+// ============================================================================
+/**
+ * Disable TLS certificate verification for all fetch requests in this process.
+ *
+ * Node.js native fetch does not support per-request TLS configuration.
+ * The only reliable cross-version approach is the NODE_TLS_REJECT_UNAUTHORIZED
+ * environment variable, which is process-global.  This is set once and logged
+ * prominently so the user is aware.
+ */
+function disableSslVerification() {
+    if (process.env.NODE_TLS_REJECT_UNAUTHORIZED === '0')
+        return; // already disabled
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+    // Warn prominently: this is process-global and affects all fetch calls.
+    console.warn('[openlore] WARNING: TLS certificate verification is DISABLED for this process.' +
+        ' All HTTPS connections (including LLM API calls) are vulnerable to MITM attacks.' +
+        ' Only use --insecure on trusted private networks with self-signed certificates.');
+}
+/**
+ * Validate and normalise an API base URL.
+ * Returns the cleaned URL or throws on invalid input.
+ */
+function normalizeApiBase(url) {
+    // Must be a valid, absolute URL
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid API base URL: "${url}". Must be a valid URL (e.g., http://localhost:8000/v1).`);
+    }
+    // Only allow http and https schemes
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`Unsupported protocol in API base URL: "${parsed.protocol}". Only http and https are allowed.`);
+    }
+    // Strip trailing slashes for consistent path joining
+    return parsed.toString().replace(/\/+$/, '');
+}
+// ============================================================================
+// RETRY-AFTER PARSING
+// ============================================================================
+/**
+ * Parse the number of milliseconds to wait before retrying a 429 response.
+ *
+ * Checks (in order):
+ *  1. Standard `Retry-After` HTTP header (seconds as integer, or HTTP-date)
+ *  2. `Limit resets at: YYYY-MM-DD HH:MM:SS UTC` in the response body
+ *
+ * Returns `undefined` when nothing useful is found so the caller can fall back
+ * to its own exponential-backoff delay.
+ */
+export function parseRetryAfterMs(body, retryAfterHeader) {
+    const BUFFER_MS = 500; // small buffer to avoid hitting the wall again immediately
+    // 1. Retry-After header
+    if (retryAfterHeader) {
+        const seconds = Number(retryAfterHeader);
+        if (!isNaN(seconds) && seconds > 0) {
+            return Math.ceil(seconds * 1000) + BUFFER_MS;
+        }
+        // HTTP-date format
+        const headerDate = Date.parse(retryAfterHeader);
+        if (!isNaN(headerDate)) {
+            const ms = headerDate - Date.now();
+            if (ms > 0)
+                return ms + BUFFER_MS;
+        }
+    }
+    // 2. "Limit resets at: YYYY-MM-DD HH:MM:SS UTC" in body
+    const match = body.match(/Limit resets at:\s*(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?\s*UTC)/i);
+    if (match) {
+        const resetMs = Date.parse(match[1].replace(' UTC', 'Z').replace(' ', 'T'));
+        if (!isNaN(resetMs)) {
+            const ms = resetMs - Date.now();
+            if (ms > 0)
+                return ms + BUFFER_MS;
+        }
+    }
+    return undefined;
+}
+// ============================================================================
+// PRICING (per 1M tokens)
+// ============================================================================
+const PRICING = {
+    anthropic: {
+        // Claude 4 family
+        'claude-opus-4': { input: 15.0, output: 75.0 },
+        'claude-sonnet-4': { input: 3.0, output: 15.0 },
+        'claude-haiku-4': { input: 0.80, output: 4.0 },
+        // Claude 3.7 / 3.5
+        'claude-3-7-sonnet': { input: 3.0, output: 15.0 },
+        'claude-3-5-sonnet': { input: 3.0, output: 15.0 },
+        'claude-3-5-haiku': { input: 0.80, output: 4.0 },
+        // Claude 3 (legacy)
+        'claude-3-opus': { input: 15.0, output: 75.0 },
+        'claude-3-sonnet': { input: 3.0, output: 15.0 },
+        'claude-3-haiku': { input: 0.25, output: 1.25 },
+        // Fallback: assume Sonnet-class pricing
+        default: { input: 3.0, output: 15.0 },
+    },
+    openai: {
+        // GPT-4o family
+        'gpt-4o': { input: 2.5, output: 10.0 },
+        'gpt-4o-mini': { input: 0.15, output: 0.6 },
+        // o-series reasoning models
+        'o1': { input: 15.0, output: 60.0 },
+        'o1-mini': { input: 3.0, output: 12.0 },
+        'o3': { input: 10.0, output: 40.0 },
+        'o3-mini': { input: 1.1, output: 4.4 },
+        'o4-mini': { input: 1.1, output: 4.4 },
+        // Legacy (still in use)
+        'gpt-4-turbo': { input: 10.0, output: 30.0 },
+        'gpt-4': { input: 30.0, output: 60.0 },
+        'gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+        default: { input: 2.5, output: 10.0 },
+    },
+    'openai-compat': {
+        // Mistral
+        'mistral-large-latest': { input: 2.0, output: 6.0 },
+        'mistral-small-latest': { input: 0.1, output: 0.3 },
+        'codestral-latest': { input: 0.2, output: 0.6 },
+        // Groq
+        'llama-3.3-70b-versatile': { input: 0.59, output: 0.79 },
+        'llama-3.1-8b-instant': { input: 0.05, output: 0.08 },
+        default: { input: 1.0, output: 3.0 },
+    },
+    gemini: {
+        'gemini-2.0-flash': { input: 0.1, output: 0.4 },
+        'gemini-2.0-flash-lite': { input: 0.075, output: 0.3 },
+        'gemini-2.5-pro': { input: 1.25, output: 10.0 },
+        'gemini-1.5-pro': { input: 1.25, output: 5.0 },
+        'gemini-1.5-flash': { input: 0.075, output: 0.3 },
+        default: { input: 0.1, output: 0.4 },
+    },
+    'claude-code': {
+        // No per-token cost: covered by Claude Max/Pro subscription
+        default: { input: 0, output: 0 },
+    },
+    'mistral-vibe': {
+        // No per-token cost: local CLI tool
+        default: { input: 0, output: 0 },
+    },
+    'gemini-cli': {
+        // No per-token cost: covered by Google account free tier
+        default: { input: 0, output: 0 },
+    },
+    'cursor-agent': {
+        // No per-token cost in openlore: Cursor subscription / CLI auth
+        default: { input: 0, output: 0 },
+    },
+    copilot: {
+        // No per-token cost: covered by GitHub Copilot subscription
+        default: { input: 0, output: 0 },
+    },
+};
+/**
+ * Exported for use in pre-flight cost estimation.
+ * Look up pricing for a model ID using prefix/family matching.
+ * Exact match first, then longest prefix match, then provider default.
+ *
+ * This is robust to minor version suffixes like "claude-sonnet-4-6-20251120"
+ * matching the "claude-sonnet-4" family entry.
+ */
+export function lookupPricing(providerName, modelId) {
+    const table = PRICING[providerName] ?? PRICING.anthropic;
+    // 1. Exact match
+    if (table[modelId])
+        return table[modelId];
+    // 2. Longest prefix match (handles "claude-sonnet-4-6-20251120" → "claude-sonnet-4")
+    const modelLower = modelId.toLowerCase();
+    let bestKey = '';
+    for (const key of Object.keys(table)) {
+        if (key === 'default')
+            continue;
+        if (modelLower.startsWith(key) && key.length > bestKey.length) {
+            bestKey = key;
+        }
+    }
+    if (bestKey)
+        return table[bestKey];
+    // 3. Provider default
+    return table.default ?? { input: 3.0, output: 15.0 };
+}
+// ============================================================================
+// TOKEN ESTIMATION
+// ============================================================================
+/**
+ * Estimate token count from text (rough approximation)
+ * ~4 characters per token for English text
+ */
+export function estimateTokens(text) {
+    // More accurate estimation considering code
+    // Code tends to have more tokens per character due to special chars
+    const codePatterns = /[{}()[\];:,.<>/\\|`~!@#$%^&*=+]/g;
+    const codeCharCount = (text.match(codePatterns) || []).length;
+    const regularCharCount = text.length - codeCharCount;
+    // Regular text: ~4 chars per token, code chars: ~2 chars per token
+    return Math.ceil(regularCharCount / 4 + codeCharCount / 2);
+}
+// ============================================================================
+// ANTHROPIC PROVIDER
+// ============================================================================
+/**
+ * Anthropic Claude provider
+ */
+export class AnthropicProvider {
+    name = 'anthropic';
+    maxContextTokens = 200000;
+    maxOutputTokens = 4096;
+    apiKey;
+    model;
+    baseUrl;
+    constructor(apiKey, model = DEFAULT_ANTHROPIC_MODEL, baseUrl, sslVerify = true) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.baseUrl = baseUrl ? normalizeApiBase(baseUrl) : 'https://api.anthropic.com/v1';
+        if (!sslVerify)
+            disableSslVerification();
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+    async generateCompletion(request) {
+        const response = await fetch(`${this.baseUrl}/messages`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify({
+                model: this.model,
+                max_tokens: request.maxTokens ?? this.maxOutputTokens,
+                temperature: request.temperature ?? 0.3,
+                system: request.systemPrompt,
+                messages: [
+                    { role: 'user', content: request.userPrompt },
+                ],
+                stop_sequences: request.stopSequences,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            const errorObj = this.parseError(error, response.status, response.headers.get('retry-after'));
+            throw errorObj;
+        }
+        const data = await response.json();
+        const content = data.content
+            .filter(c => c.type === 'text')
+            .map(c => c.text)
+            .join('');
+        return {
+            content,
+            usage: {
+                inputTokens: data.usage.input_tokens,
+                outputTokens: data.usage.output_tokens,
+                totalTokens: data.usage.input_tokens + data.usage.output_tokens,
+            },
+            model: data.model,
+            finishReason: data.stop_reason === 'end_turn' ? 'stop' : data.stop_reason === 'max_tokens' ? 'length' : 'error',
+        };
+    }
+    parseError(error, status, retryAfterHeader) {
+        const detail = error.trim() || '(empty response body)';
+        const err = new Error(`HTTP ${status}: ${detail}`);
+        err.status = status;
+        err.retryable = status === 429 || status >= 500;
+        if (status === 429) {
+            err.retryAfterMs = parseRetryAfterMs(error, retryAfterHeader);
+        }
+        return err;
+    }
+}
+// ============================================================================
+// OPENAI PROVIDER
+// ============================================================================
+/**
+ * Wrap a top-level array schema in an object so it satisfies OpenAI's
+ * structured-output requirement that the root type is "object".
+ * The existing unwrap logic in completeJSON (single-key object → array)
+ * reverses this transparently.  See: #52
+ */
+function wrapArraySchema(schema) {
+    if (schema.type === 'array') {
+        return {
+            type: 'object',
+            properties: { items: schema },
+            required: ['items'],
+        };
+    }
+    return schema;
+}
+function isSchemaRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function schemaAllowsNull(schema) {
+    if (!isSchemaRecord(schema))
+        return false;
+    const type = schema.type;
+    if (type === 'null')
+        return true;
+    if (Array.isArray(type) && type.includes('null'))
+        return true;
+    for (const key of ['anyOf', 'oneOf']) {
+        const schemas = schema[key];
+        if (Array.isArray(schemas) && schemas.some(schemaAllowsNull)) {
+            return true;
+        }
+    }
+    return false;
+}
+function makeSchemaNullable(schema) {
+    if (schemaAllowsNull(schema))
+        return schema;
+    if (isSchemaRecord(schema)) {
+        const type = schema.type;
+        if (typeof type === 'string') {
+            schema.type = [type, 'null'];
+            return schema;
+        }
+    }
+    return { anyOf: [schema, { type: 'null' }] };
+}
+function normalizeOpenAISchemaNode(node) {
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            normalizeOpenAISchemaNode(item);
+        }
+        return;
+    }
+    if (!isSchemaRecord(node))
+        return;
+    const isObjectSchema = node.type === 'object' || (Array.isArray(node.type) && node.type.includes('object'));
+    if (isObjectSchema) {
+        const properties = isSchemaRecord(node.properties) ? node.properties : {};
+        const originalRequired = new Set(Array.isArray(node.required)
+            ? node.required.filter((field) => typeof field === 'string')
+            : []);
+        node.properties = properties;
+        node.additionalProperties = false;
+        node.required = Object.keys(properties);
+        for (const [key, propertySchema] of Object.entries(properties)) {
+            normalizeOpenAISchemaNode(propertySchema);
+            if (!originalRequired.has(key)) {
+                properties[key] = makeSchemaNullable(properties[key]);
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (isObjectSchema && key === 'properties')
+            continue;
+        normalizeOpenAISchemaNode(value);
+    }
+}
+function normalizeOpenAIResponseSchema(schema) {
+    const clonedSchema = JSON.parse(JSON.stringify(schema));
+    const wrappedSchema = wrapArraySchema(clonedSchema);
+    normalizeOpenAISchemaNode(wrappedSchema);
+    return wrappedSchema;
+}
+/**
+ * OpenAI provider
+ */
+export class OpenAIProvider {
+    name = 'openai';
+    maxContextTokens = 128000;
+    maxOutputTokens = 4096;
+    apiKey;
+    model;
+    baseUrl;
+    constructor(apiKey, model = DEFAULT_OPENAI_MODEL, baseUrl, sslVerify = true) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.baseUrl = baseUrl ? normalizeApiBase(baseUrl) : 'https://api.openai.com/v1';
+        if (!sslVerify)
+            disableSslVerification();
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+    async generateCompletion(request) {
+        const messages = [
+            { role: 'system', content: request.systemPrompt },
+            { role: 'user', content: request.userPrompt },
+        ];
+        const body = {
+            model: this.model,
+            messages,
+            max_tokens: request.maxTokens ?? this.maxOutputTokens,
+            temperature: request.temperature ?? 0.3,
+            stop: request.stopSequences,
+        };
+        if (request.responseFormat === 'json' && request.jsonSchema) {
+            // Use OpenAI structured outputs when a JSON schema is provided.
+            // This forces the model to conform to the schema (e.g. start an array). (#26)
+            // Wrap top-level array schemas in an object to satisfy OpenAI's requirement. (#52)
+            body.response_format = {
+                type: 'json_schema',
+                json_schema: {
+                    name: 'response',
+                    schema: normalizeOpenAIResponseSchema(request.jsonSchema),
+                },
+            };
+        }
+        else if (request.responseFormat === 'json') {
+            body.response_format = { type: 'json_object' };
+        }
+        const response = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            const errorObj = this.parseError(error, response.status, response.headers.get('retry-after'));
+            throw errorObj;
+        }
+        const data = await response.json();
+        return {
+            content: data.choices[0]?.message?.content ?? '',
+            usage: {
+                inputTokens: data.usage.prompt_tokens,
+                outputTokens: data.usage.completion_tokens,
+                totalTokens: data.usage.total_tokens,
+            },
+            model: data.model,
+            finishReason: data.choices[0]?.finish_reason === 'stop' ? 'stop' : data.choices[0]?.finish_reason === 'length' ? 'length' : 'error',
+        };
+    }
+    parseError(error, status, retryAfterHeader) {
+        const detail = error.trim() || '(empty response body)';
+        const err = new Error(`HTTP ${status}: ${detail}`);
+        err.status = status;
+        err.retryable = status === 429 || status >= 500;
+        if (status === 429) {
+            err.retryAfterMs = parseRetryAfterMs(error, retryAfterHeader);
+        }
+        return err;
+    }
+}
+export class OpenAICompatibleProvider {
+    name = 'openai-compat';
+    maxContextTokens = 128000;
+    maxOutputTokens = 4096;
+    apiKey;
+    model;
+    baseUrl;
+    disableResponseFormat;
+    constructor(apiKey, baseUrl, model = DEFAULT_OPENAI_COMPAT_MODEL, disableResponseFormat = false) {
+        this.apiKey = apiKey;
+        this.baseUrl = normalizeApiBase(baseUrl);
+        this.model = model;
+        this.disableResponseFormat = disableResponseFormat;
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+    /**
+     * Fetch available models from the API endpoint
+     */
+    async fetchAvailableModels() {
+        try {
+            const response = await fetch(`${this.baseUrl}/models`, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                return [];
+            }
+            const data = await response.json();
+            return data.data?.map(model => model.id).sort() ?? [];
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get known models for common API endpoints when /models is not available
+     */
+    getKnownModelsForEndpoint() {
+        const url = this.baseUrl.toLowerCase();
+        if (url.includes('codestral.mistral.ai')) {
+            return ['codestral-2508', 'codestral-latest'];
+        }
+        if (url.includes('api.mistral.ai')) {
+            return [
+                'mistral-large-3-25-12',
+                'mistral-medium-3-1-25-08',
+                'mistral-small-4-0-26-03',
+                'mistral-nemo-12b-24-07',
+                'codestral-2508',
+                'devstral-2-25-12'
+            ];
+        }
+        if (url.includes('api.openai.com')) {
+            return [
+                'gpt-4o',
+                'gpt-4o-mini',
+                'gpt-4-turbo',
+                'gpt-4',
+                'gpt-3.5-turbo'
+            ];
+        }
+        if (url.includes('api.groq.com')) {
+            return [
+                'llama-3.1-70b-versatile',
+                'llama-3.1-8b-instant',
+                'mixtral-8x7b-32768'
+            ];
+        }
+        // For unknown endpoints, return empty array
+        return [];
+    }
+    async generateCompletion(request) {
+        const body = {
+            model: this.model,
+            messages: [
+                { role: 'system', content: request.systemPrompt },
+                { role: 'user', content: request.userPrompt },
+            ],
+            max_tokens: request.maxTokens ?? this.maxOutputTokens,
+            temperature: request.temperature ?? 0.3,
+            stream: true,
+            stream_options: { include_usage: true },
+            ...(request.stopSequences && { stop: request.stopSequences }),
+        };
+        if (!this.disableResponseFormat) {
+            if (request.responseFormat === 'json' && request.jsonSchema) {
+                body.response_format = {
+                    type: 'json_schema',
+                    json_schema: {
+                        name: 'response',
+                        schema: normalizeOpenAIResponseSchema(request.jsonSchema),
+                    },
+                };
+            }
+            else if (request.responseFormat === 'json') {
+                body.response_format = { type: 'json_object' };
+            }
+        }
+        const response = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            const detail = error.trim() || '(empty response body)';
+            const err = new Error(`HTTP ${response.status}: ${detail}`);
+            err.status = response.status;
+            err.retryable = response.status === 429 || response.status >= 500;
+            if (response.status === 429) {
+                err.retryAfterMs = parseRetryAfterMs(error, response.headers.get('retry-after'));
+            }
+            throw err;
+        }
+        let content = '';
+        let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        let finishReason = 'stop';
+        let model = this.model;
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        outer: while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line.startsWith('data: '))
+                    continue;
+                const data = line.slice(6).trim();
+                if (data === '[DONE]')
+                    break outer;
+                try {
+                    const chunk = JSON.parse(data);
+                    const delta = chunk.choices?.[0]?.delta?.content;
+                    if (delta)
+                        content += delta;
+                    const fr = chunk.choices?.[0]?.finish_reason;
+                    if (fr)
+                        finishReason = fr === 'length' ? 'length' : 'stop';
+                    if (chunk.model)
+                        model = chunk.model;
+                    if (chunk.usage) {
+                        usage = {
+                            inputTokens: chunk.usage.prompt_tokens,
+                            outputTokens: chunk.usage.completion_tokens,
+                            totalTokens: chunk.usage.total_tokens,
+                        };
+                    }
+                }
+                catch { /* ignore malformed SSE chunks */ }
+            }
+        }
+        return { content, usage, model, finishReason };
+    }
+}
+// ============================================================================
+// COPILOT PROVIDER (via copilot-api proxy — OpenAI-compatible)
+// ============================================================================
+/**
+ * GitHub Copilot provider via copilot-api proxy.
+ * Requires a running copilot-api proxy (https://github.com/ericc-ch/copilot-api)
+ * which exposes an OpenAI-compatible /v1/chat/completions endpoint.
+ *
+ * Required env vars:
+ *   COPILOT_API_BASE_URL — Base URL of the copilot-api proxy (default: http://localhost:4141/v1)
+ *
+ * Optional env vars:
+ *   COPILOT_API_KEY      — API key if the proxy requires auth (default: "copilot")
+ */
+export class CopilotProvider {
+    name = 'copilot';
+    maxContextTokens = 128000;
+    maxOutputTokens = 4096;
+    apiKey;
+    model;
+    baseUrl;
+    constructor(baseUrl, model = DEFAULT_COPILOT_MODEL, apiKey = 'copilot') {
+        this.apiKey = apiKey;
+        this.baseUrl = normalizeApiBase(baseUrl);
+        this.model = model;
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+    async generateCompletion(request) {
+        const body = {
+            model: this.model,
+            messages: [
+                { role: 'system', content: request.systemPrompt },
+                { role: 'user', content: request.userPrompt },
+            ],
+            max_tokens: request.maxTokens ?? this.maxOutputTokens,
+            temperature: request.temperature ?? 0.3,
+            ...(request.stopSequences && { stop: request.stopSequences }),
+        };
+        if (request.responseFormat === 'json' && request.jsonSchema) {
+            body.response_format = {
+                type: 'json_schema',
+                json_schema: {
+                    name: 'response',
+                    schema: wrapArraySchema(request.jsonSchema),
+                },
+            };
+        }
+        else if (request.responseFormat === 'json') {
+            body.response_format = { type: 'json_object' };
+        }
+        const response = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            const detail = error.trim() || '(empty response body)';
+            const err = new Error(`HTTP ${response.status}: ${detail}`);
+            err.status = response.status;
+            err.retryable = response.status === 429 || response.status >= 500;
+            if (response.status === 429) {
+                err.retryAfterMs = parseRetryAfterMs(error, response.headers.get('retry-after'));
+            }
+            throw err;
+        }
+        const data = await response.json();
+        return {
+            content: data.choices[0]?.message?.content ?? '',
+            usage: {
+                inputTokens: data.usage.prompt_tokens,
+                outputTokens: data.usage.completion_tokens,
+                totalTokens: data.usage.total_tokens,
+            },
+            model: data.model ?? this.model,
+            finishReason: data.choices[0]?.finish_reason === 'stop' ? 'stop' : data.choices[0]?.finish_reason === 'length' ? 'length' : 'error',
+        };
+    }
+}
+// ============================================================================
+// GEMINI CLI PROVIDER (uses local `gemini` CLI, no API key required)
+// ============================================================================
+/**
+ * Gemini CLI provider
+ *
+ * Routes LLM calls through the local `gemini` CLI binary in non-interactive
+ * mode (`gemini -p ...`).  Authentication is handled by the Google account
+ * session — no GEMINI_API_KEY is required.
+ * If the binary is not on PATH, set GEMINI_CLI to its full path.
+ */
+export class GeminiCLIProvider {
+    name = 'gemini-cli';
+    maxContextTokens = 1_000_000;
+    maxOutputTokens = 8_192;
+    model;
+    constructor(model) {
+        this.model = model && model !== 'gemini-cli' ? model : undefined;
+    }
+    async generateCompletion(request) {
+        const { execFileSync } = await import('child_process');
+        const fullPrompt = request.systemPrompt
+            ? `${request.systemPrompt}\n\n---\n\n${request.userPrompt}`
+            : request.userPrompt;
+        // gemini CLI: -p for prompt, --output-format json, -m for model
+        const args = ['-p', fullPrompt, '--output-format', 'json'];
+        if (this.model)
+            args.push('-m', this.model);
+        const geminiCLIBin = process.env.GEMINI_CLI ?? 'gemini';
+        let raw;
+        try {
+            raw = execFileSync(geminiCLIBin, args, {
+                encoding: 'utf8',
+                maxBuffer: 50 * 1024 * 1024,
+                timeout: 300_000,
+            });
+        }
+        catch (err) {
+            const e = err;
+            const detail = e.stderr ?? e.stdout ?? e.message ?? String(err);
+            throw Object.assign(new Error(`gemini CLI failed: ${detail}`), { retryable: false });
+        }
+        // Format: {response: string, stats: {models: {[name]: {tokens: {input, candidates, total}}}}}
+        let content = '';
+        let inputTokens;
+        let outputTokens;
+        let modelUsed = this.model ?? 'gemini-cli';
+        try {
+            const parsed = JSON.parse(raw);
+            content = parsed.response ?? '';
+            if (parsed.stats?.models) {
+                const models = Object.entries(parsed.stats.models);
+                if (models.length > 0) {
+                    modelUsed = models[0][0];
+                    // Sum tokens across all models used (gemini-cli may use multiple internally)
+                    inputTokens = models.reduce((sum, [, m]) => sum + (m.tokens?.input ?? 0), 0);
+                    outputTokens = models.reduce((sum, [, m]) => sum + (m.tokens?.candidates ?? 0), 0);
+                }
+            }
+        }
+        catch {
+            content = raw.trim();
+        }
+        if (!content)
+            content = raw.trim();
+        inputTokens ??= estimateTokens(fullPrompt);
+        outputTokens ??= estimateTokens(content);
+        return {
+            content,
+            usage: { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens },
+            model: modelUsed,
+            finishReason: 'stop',
+        };
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+}
+// ============================================================================
+// CURSOR AGENT CLI PROVIDER (uses local `cursor-agent` CLI, no cloud API key)
+// ============================================================================
+/**
+ * Cursor Agent CLI provider
+ *
+ * Routes LLM calls through the Cursor Agent CLI in print mode (`-p`, JSON output).
+ * Authentication is handled by Cursor (see Cursor CLI headless documentation) —
+ * e.g. `cursor auth login` or `CURSOR_API_KEY` — not ANTHROPIC_API_KEY / OPENAI_API_KEY.
+ * If the binary is not on PATH, set `CURSOR_AGENT_CLI` to its full path.
+ */
+export class CursorAgentProvider {
+    name = 'cursor-agent';
+    maxContextTokens = 1_000_000;
+    maxOutputTokens = 8192;
+    model;
+    constructor(model) {
+        this.model = model && model !== 'cursor-agent' ? model : undefined;
+    }
+    async generateCompletion(request) {
+        const { execFileSync } = await import('child_process');
+        const fullPrompt = request.systemPrompt
+            ? `${request.systemPrompt}\n\n---\n\n${request.userPrompt}`
+            : request.userPrompt;
+        const args = ['-p', fullPrompt, '--output-format', 'json'];
+        if (this.model)
+            args.push('--model', this.model);
+        const bin = process.env.CURSOR_AGENT_CLI ?? 'cursor-agent';
+        let raw;
+        try {
+            raw = execFileSync(bin, args, {
+                encoding: 'utf8',
+                maxBuffer: LLM_CLI_MAX_BUFFER_BYTES,
+                timeout: LLM_CLI_TIMEOUT_MS,
+            });
+        }
+        catch (err) {
+            const e = err;
+            const detail = e.stderr ?? e.stdout ?? e.message ?? String(err);
+            throw Object.assign(new Error(`cursor-agent CLI failed: ${detail}`), { retryable: false });
+        }
+        let content = '';
+        let inputTokens;
+        let outputTokens;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.is_error === true && typeof parsed.result === 'string') {
+                throw Object.assign(new Error(`cursor-agent CLI error: ${parsed.result}`), { retryable: false });
+            }
+            if (typeof parsed.result === 'string') {
+                content = parsed.result;
+            }
+            else if (typeof parsed.response === 'string') {
+                content = parsed.response;
+            }
+            else {
+                content = String(parsed.message ?? parsed.text ?? parsed.content ?? '');
+            }
+            const u = parsed.usage;
+            if (u) {
+                inputTokens = (u.input_tokens ?? u.inputTokens);
+                outputTokens = (u.output_tokens ?? u.outputTokens);
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && /cursor-agent CLI error:/.test(err.message))
+                throw err;
+            content = raw.trim();
+        }
+        if (!content)
+            content = raw.trim();
+        inputTokens ??= estimateTokens(fullPrompt);
+        outputTokens ??= estimateTokens(content);
+        return {
+            content,
+            usage: { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens },
+            model: this.model ?? 'cursor-agent',
+            finishReason: 'stop',
+        };
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+}
+// ============================================================================
+// GEMINI PROVIDER
+// ============================================================================
+/**
+ * Google Gemini provider
+ */
+export class GeminiProvider {
+    name = 'gemini';
+    maxContextTokens = 1000000;
+    maxOutputTokens = 8192;
+    apiKey;
+    model;
+    baseUrl = 'https://generativelanguage.googleapis.com/v1beta/models';
+    constructor(apiKey, model = DEFAULT_GEMINI_MODEL) {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+    async generateCompletion(request) {
+        const body = {
+            contents: [
+                { role: 'user', parts: [{ text: request.userPrompt }] },
+            ],
+            systemInstruction: {
+                parts: [{ text: request.systemPrompt }],
+            },
+            generationConfig: {
+                temperature: request.temperature ?? 0.3,
+                maxOutputTokens: request.maxTokens ?? this.maxOutputTokens,
+                ...(request.responseFormat === 'json' && { responseMimeType: 'application/json' }),
+                ...(request.responseFormat === 'json' && request.jsonSchema && { responseSchema: request.jsonSchema }),
+                ...(request.stopSequences && { stopSequences: request.stopSequences }),
+            },
+        };
+        const url = `${this.baseUrl}/${this.model}:generateContent?key=${this.apiKey}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            const detail = error.trim() || '(empty response body)';
+            const err = new Error(`HTTP ${response.status}: ${detail}`);
+            err.status = response.status;
+            err.retryable = response.status === 429 || response.status >= 500;
+            if (response.status === 429) {
+                err.retryAfterMs = parseRetryAfterMs(error, response.headers.get('retry-after'));
+            }
+            throw err;
+        }
+        const data = await response.json();
+        const content = data.candidates[0]?.content?.parts?.map(p => p.text).join('') ?? '';
+        const finishReason = data.candidates[0]?.finishReason;
+        return {
+            content,
+            usage: {
+                inputTokens: data.usageMetadata.promptTokenCount,
+                outputTokens: data.usageMetadata.candidatesTokenCount,
+                totalTokens: data.usageMetadata.totalTokenCount,
+            },
+            model: this.model,
+            finishReason: finishReason === 'STOP' ? 'stop' : finishReason === 'MAX_TOKENS' ? 'length' : 'error',
+        };
+    }
+}
+// ============================================================================
+// MOCK PROVIDER (for testing)
+// ============================================================================
+/**
+ * Mock provider for testing
+ */
+export class MockLLMProvider {
+    name = 'mock';
+    maxContextTokens = 100000;
+    maxOutputTokens = 4096;
+    responses = new Map();
+    defaultResponse = '{"result": "mock response"}';
+    callHistory = [];
+    shouldFail = false;
+    failCount = 0;
+    currentFailCount = 0;
+    setResponse(promptContains, response) {
+        this.responses.set(promptContains, response);
+    }
+    setDefaultResponse(response) {
+        this.defaultResponse = response;
+    }
+    countTokens(text) {
+        return estimateTokens(text);
+    }
+    async generateCompletion(request) {
+        this.callHistory.push(request);
+        if (this.shouldFail && this.currentFailCount < this.failCount) {
+            this.currentFailCount++;
+            const err = new Error('Mock failure');
+            err.status = 500;
+            err.retryable = true;
+            throw err;
+        }
+        // Find matching response
+        let content = this.defaultResponse;
+        for (const [key, value] of this.responses) {
+            if (request.userPrompt.includes(key) || request.systemPrompt.includes(key)) {
+                content = value;
+                break;
+            }
+        }
+        const inputTokens = this.countTokens(request.systemPrompt + request.userPrompt);
+        const outputTokens = this.countTokens(content);
+        return {
+            content,
+            usage: {
+                inputTokens,
+                outputTokens,
+                totalTokens: inputTokens + outputTokens,
+            },
+            model: 'mock-model',
+            finishReason: 'stop',
+        };
+    }
+    reset() {
+        this.callHistory = [];
+        this.shouldFail = false;
+        this.failCount = 0;
+        this.currentFailCount = 0;
+        this.responses.clear();
+    }
+}
+// ============================================================================
+// LLM SERVICE
+// ============================================================================
+/**
+ * LLM Service - main interface for LLM interactions
+ */
+export class LLMService {
+    provider;
+    retryConfig;
+    options;
+    tokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, requests: 0 };
+    costTracking = { estimatedCost: 0, currency: 'USD', byProvider: {} };
+    requestLog = [];
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.options = {
+            provider: options.provider ?? 'anthropic',
+            model: options.model ?? '',
+            apiBase: options.apiBase ?? '',
+            sslVerify: options.sslVerify ?? true,
+            openaiCompatBaseUrl: options.openaiCompatBaseUrl ?? '',
+            maxRetries: options.maxRetries ?? DEFAULT_LLM_MAX_RETRIES,
+            initialDelay: options.initialDelay ?? DEFAULT_LLM_INITIAL_DELAY_MS,
+            maxDelay: options.maxDelay ?? DEFAULT_LLM_MAX_DELAY_MS,
+            timeout: options.timeout ?? DEFAULT_LLM_TIMEOUT_MS,
+            costWarningThreshold: options.costWarningThreshold ?? DEFAULT_LLM_COST_WARNING_THRESHOLD,
+            logDir: options.logDir ?? `${OPENLORE_DIR}/${OPENLORE_LOGS_SUBDIR}`,
+            enableLogging: options.enableLogging ?? false,
+            disableResponseFormat: options.disableResponseFormat ?? false,
+        };
+        this.retryConfig = {
+            maxRetries: this.options.maxRetries,
+            initialDelay: this.options.initialDelay,
+            maxDelay: this.options.maxDelay,
+            timeout: this.options.timeout,
+        };
+    }
+    /**
+     * Get the provider name
+     */
+    getProviderName() {
+        return this.provider.name;
+    }
+    /**
+     * Get maximum context tokens for the provider
+     */
+    getMaxContextTokens() {
+        return this.provider.maxContextTokens;
+    }
+    /**
+     * Count tokens in text
+     */
+    countTokens(text) {
+        return this.provider.countTokens(text);
+    }
+    /**
+     * Get current token usage
+     */
+    getTokenUsage() {
+        return { ...this.tokenUsage };
+    }
+    /**
+     * Get current cost tracking
+     */
+    getCostTracking() {
+        return { ...this.costTracking };
+    }
+    /**
+     * Reset usage tracking
+     */
+    resetTracking() {
+        this.tokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, requests: 0 };
+        this.costTracking = { estimatedCost: 0, currency: 'USD', byProvider: {} };
+        this.requestLog = [];
+    }
+    /**
+     * Generate a completion with retry logic
+     */
+    async complete(request) {
+        // Pre-calculate tokens and warn if approaching limit
+        const inputTokens = this.countTokens(request.systemPrompt + request.userPrompt);
+        const maxTokens = request.maxTokens ?? this.provider.maxOutputTokens;
+        const totalExpected = inputTokens + maxTokens;
+        if (totalExpected > this.provider.maxContextTokens * CONTEXT_LIMIT_WARNING_RATIO) {
+            logger.warning(`Approaching context limit: ${totalExpected} tokens (max: ${this.provider.maxContextTokens})`);
+        }
+        if (totalExpected > this.provider.maxContextTokens) {
+            throw new Error(`Request exceeds context limit: ${totalExpected} > ${this.provider.maxContextTokens}`);
+        }
+        // Execute with retry logic
+        let lastError = null;
+        let delay = this.retryConfig.initialDelay;
+        for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+            try {
+                logger.debug(`LLM request attempt ${attempt + 1}/${this.retryConfig.maxRetries + 1}`);
+                const response = await this.executeWithTimeout(request);
+                // Update tracking
+                this.updateTracking(response);
+                // Log if enabled
+                if (this.options.enableLogging) {
+                    this.logRequest(request, response);
+                }
+                // Check cost threshold
+                if (this.costTracking.estimatedCost > this.options.costWarningThreshold) {
+                    logger.warning(`Cost threshold exceeded: $${this.costTracking.estimatedCost.toFixed(4)} > $${this.options.costWarningThreshold}`);
+                }
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                const errWithStatus = error;
+                // Log error
+                if (this.options.enableLogging) {
+                    this.logRequest(request, undefined, lastError.message);
+                }
+                // Check if retryable
+                if (!errWithStatus.retryable || attempt === this.retryConfig.maxRetries) {
+                    throw lastError;
+                }
+                // Use the provider-supplied reset time if available, otherwise exponential backoff
+                const retryAfterMs = errWithStatus.retryAfterMs;
+                const waitMs = retryAfterMs !== undefined ? retryAfterMs : delay;
+                logger.warning(`LLM request failed (attempt ${attempt + 1}), retrying in ${waitMs}ms: ${lastError.message}`);
+                await this.sleep(waitMs);
+                // Only advance the backoff delay when we didn't use a provider-supplied wait
+                if (retryAfterMs === undefined) {
+                    delay = Math.min(delay * 2, this.retryConfig.maxDelay);
+                }
+            }
+        }
+        throw lastError ?? new Error('Unknown error');
+    }
+    /**
+     * Generate a completion expecting JSON response
+     */
+    async completeJSON(request, schema) {
+        const jsonRequest = { ...request, responseFormat: 'json', jsonSchema: schema };
+        // Add JSON instruction to prompt if not already present
+        if (!jsonRequest.systemPrompt.toLowerCase().includes('json')) {
+            jsonRequest.systemPrompt += '\n\nRespond with valid JSON only.';
+        }
+        // When a schema is provided, append it to the system prompt so the model
+        // knows the exact shape expected (especially that it must start an array).
+        // This addresses issue #26: without this, models may return a single object.
+        if (schema) {
+            jsonRequest.systemPrompt += `\n\nYour response MUST conform to this JSON Schema:\n${JSON.stringify(schema)}`;
+        }
+        const response = await this.complete(jsonRequest);
+        let content = response.content;
+        // Extract JSON from markdown code blocks if present
+        const jsonMatch = content.match(/```(?:json)?\s*([\s\S]*?)```/);
+        if (jsonMatch) {
+            content = jsonMatch[1].trim();
+        }
+        // Parse JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (parseError) {
+            // Retry with correction prompt for parse errors
+            logger.warning('JSON parse failed, attempting correction');
+            const correctionRequest = {
+                systemPrompt: 'Fix the following invalid JSON and return only valid JSON. Do not include any explanation.',
+                userPrompt: `Invalid JSON:\n${content}\n\nError: ${parseError.message}\n\nReturn the corrected JSON:`,
+                temperature: 0.1,
+                responseFormat: 'json',
+            };
+            const correctionResponse = await this.complete(correctionRequest);
+            let correctedContent = correctionResponse.content;
+            // Extract from code blocks again
+            const correctedMatch = correctedContent.match(/```(?:json)?\s*([\s\S]*?)```/);
+            if (correctedMatch) {
+                correctedContent = correctedMatch[1].trim();
+            }
+            parsed = JSON.parse(correctedContent);
+        }
+        // Unwrap single-key object whose value is an array (e.g. {entities:[...]} → [...])
+        // LLM correction attempts sometimes wrap arrays in an object
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed)) {
+            const keys = Object.keys(parsed);
+            if (keys.length === 1) {
+                const val = parsed[keys[0]];
+                if (Array.isArray(val)) {
+                    parsed = val;
+                }
+            }
+        }
+        // Validate against schema if provided (after successful parsing)
+        if (schema) {
+            this.validateSchema(parsed, schema);
+        }
+        return parsed;
+    }
+    /**
+     * Execute request with timeout
+     */
+    async executeWithTimeout(request) {
+        const timeoutMs = this.retryConfig.timeout;
+        const result = await Promise.race([
+            this.provider.generateCompletion(request),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`LLM request timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+        return result;
+    }
+    /**
+     * Update tracking after a successful request
+     */
+    updateTracking(response) {
+        this.tokenUsage.inputTokens += response.usage.inputTokens;
+        this.tokenUsage.outputTokens += response.usage.outputTokens;
+        this.tokenUsage.totalTokens += response.usage.totalTokens;
+        this.tokenUsage.requests++;
+        // Calculate cost
+        const cost = this.calculateCost(response);
+        this.costTracking.estimatedCost += cost;
+        this.costTracking.byProvider[this.provider.name] = (this.costTracking.byProvider[this.provider.name] ?? 0) + cost;
+    }
+    /**
+     * Calculate cost for a response
+     */
+    calculateCost(response) {
+        const modelPricing = lookupPricing(this.provider.name, response.model);
+        const inputCost = (response.usage.inputTokens / 1_000_000) * modelPricing.input;
+        const outputCost = (response.usage.outputTokens / 1_000_000) * modelPricing.output;
+        return inputCost + outputCost;
+    }
+    /**
+     * Log request/response
+     */
+    logRequest(request, response, error) {
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            request: this.redactSecrets(request),
+            response,
+            error,
+        };
+        this.requestLog.push(logEntry);
+    }
+    /**
+     * Redact potential secrets from request
+     */
+    redactSecrets(request) {
+        const secretPatterns = [
+            /(?:api[_-]?key|password|secret|token|auth)['":\s]*[=:]\s*['"]?[\w-]{20,}['"]?/gi,
+            /['"]?[a-zA-Z0-9]{32,}['"]?/g, // Long alphanumeric strings
+        ];
+        let systemPrompt = request.systemPrompt;
+        let userPrompt = request.userPrompt;
+        for (const pattern of secretPatterns) {
+            systemPrompt = systemPrompt.replace(pattern, '[REDACTED]');
+            userPrompt = userPrompt.replace(pattern, '[REDACTED]');
+        }
+        return { ...request, systemPrompt, userPrompt };
+    }
+    /**
+     * Simple schema validation
+     */
+    validateSchema(data, schema) {
+        const schemaObj = schema;
+        if (schemaObj.type === 'array') {
+            if (!Array.isArray(data)) {
+                throw new Error('Expected JSON array but received object');
+            }
+            // Validate each item against the items schema if provided
+            const itemsSchema = schemaObj.items;
+            if (itemsSchema?.required && Array.isArray(itemsSchema.required)) {
+                for (const item of data) {
+                    for (const field of itemsSchema.required) {
+                        if (!(field in item)) {
+                            throw new Error(`Missing required field in array item: ${field}`);
+                        }
+                    }
+                }
+            }
+        }
+        else if (schemaObj.type === 'object' && schemaObj.required && Array.isArray(schemaObj.required)) {
+            const dataObj = data;
+            for (const field of schemaObj.required) {
+                if (!(field in dataObj)) {
+                    throw new Error(`Missing required field: ${field}`);
+                }
+            }
+        }
+    }
+    /**
+     * Save logs to disk
+     */
+    async saveLogs() {
+        if (this.requestLog.length === 0)
+            return;
+        await mkdir(this.options.logDir, { recursive: true });
+        const filename = `llm-log-${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
+        const filepath = join(this.options.logDir, filename);
+        await writeFile(filepath, JSON.stringify({
+            summary: {
+                tokenUsage: this.tokenUsage,
+                costTracking: this.costTracking,
+            },
+            requests: this.requestLog,
+        }, null, 2));
+        logger.debug(`Saved LLM logs to ${filepath}`);
+    }
+    /**
+     * Sleep helper
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+/**
+ * Create an LLM service with the specified provider
+ */
+export function createLLMService(options = {}) {
+    const providerName = options.provider ?? 'anthropic';
+    const sslVerify = options.sslVerify ?? true;
+    let provider;
+    if (providerName === 'anthropic') {
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (!apiKey) {
+            throw new Error('ANTHROPIC_API_KEY environment variable is not set');
+        }
+        const apiBase = options.apiBase ?? process.env.ANTHROPIC_API_BASE ?? undefined;
+        provider = new AnthropicProvider(apiKey, options.model ?? DEFAULT_ANTHROPIC_MODEL, apiBase, sslVerify);
+    }
+    else if (providerName === 'openai') {
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('OPENAI_API_KEY environment variable is not set');
+        }
+        const apiBase = options.apiBase ?? process.env.OPENAI_API_BASE ?? undefined;
+        provider = new OpenAIProvider(apiKey, options.model ?? DEFAULT_OPENAI_MODEL, apiBase, sslVerify);
+    }
+    else if (providerName === 'openai-compat') {
+        const apiKey = process.env.OPENAI_COMPAT_API_KEY;
+        const baseUrl = options.openaiCompatBaseUrl ?? options.apiBase ?? process.env.OPENAI_COMPAT_BASE_URL;
+        if (!apiKey) {
+            throw new Error('OPENAI_COMPAT_API_KEY environment variable is not set');
+        }
+        if (!baseUrl) {
+            throw new Error('openaiCompatBaseUrl must be set in config or OPENAI_COMPAT_BASE_URL env var (e.g. https://api.mistral.ai/v1)');
+        }
+        provider = new OpenAICompatibleProvider(apiKey, baseUrl, options.model ?? DEFAULT_OPENAI_COMPAT_MODEL, options.disableResponseFormat ?? false);
+    }
+    else if (providerName === 'copilot') {
+        const baseUrl = options.openaiCompatBaseUrl ?? options.apiBase ?? process.env.COPILOT_API_BASE_URL ?? 'http://localhost:4141/v1';
+        const apiKey = process.env.COPILOT_API_KEY ?? 'copilot';
+        provider = new CopilotProvider(baseUrl, options.model ?? DEFAULT_COPILOT_MODEL, apiKey);
+    }
+    else if (providerName === 'gemini') {
+        const apiKey = process.env.GEMINI_API_KEY;
+        if (!apiKey) {
+            throw new Error('GEMINI_API_KEY environment variable is not set');
+        }
+        provider = new GeminiProvider(apiKey, options.model ?? DEFAULT_GEMINI_MODEL);
+    }
+    else if (providerName === 'claude-code') {
+        provider = new ClaudeCodeProvider(options.model);
+    }
+    else if (providerName === 'mistral-vibe') {
+        provider = new MistralVibeProvider(options.model);
+    }
+    else if (providerName === 'gemini-cli') {
+        provider = new GeminiCLIProvider(options.model);
+    }
+    else if (providerName === 'cursor-agent') {
+        provider = new CursorAgentProvider(options.model);
+    }
+    else {
+        throw new Error(`Unknown provider: ${providerName}. Supported: anthropic, openai, openai-compat, copilot, gemini, gemini-cli, claude-code, mistral-vibe, cursor-agent`);
+    }
+    if (!sslVerify) {
+        logger.warning('SSL verification is disabled. Use only for trusted internal servers.');
+    }
+    return new LLMService(provider, options);
+}
+/**
+ * Create an LLM service with a mock provider (for testing)
+ */
+export function createMockLLMService(options = {}) {
+    const provider = new MockLLMProvider();
+    const service = new LLMService(provider, options);
+    return { service, provider };
+}
+//# sourceMappingURL=llm-service.js.map