ft-scout 1.0.9 → 1.1.0

package/bin/src/engine/llm.js

@@ -1,20 +1,552 @@
+import chalk from 'chalk';
 import OpenAI from 'openai';
 import dotenv from 'dotenv';
 import * as url from 'url';
 import path from 'path';
+import { getWebContext } from './web.js';
+import { getLanguageInstruction } from '../utils/language.js';
+import { loadAuthConfig } from '../utils/auth.js';
+import { logAuditEvent } from '../utils/auditLogger.js';
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
-// Attempt to load .env from the root of the CLI installation
+// Attempt to load .env from the root of the CLI installation or current working directory
 dotenv.config({ path: path.resolve(__dirname, '../../../.env'), quiet: true });
-// We pass a dummy key because the OpenAI SDK requires it, but the real key is held on the Proxy Server
-const openai = new OpenAI({
-    apiKey: 'proxy-managed-key',
-    baseURL: 'https://frontterrain.com/api',
+dotenv.config({ quiet: true });
+const groqApiKey = process.env.GROQ_API_KEY;
+const openaiApiKey = process.env.OPENAI_API_KEY;
+const geminiApiKey = process.env.GEMINI_API_KEY;
+const nvidiaApiKey = process.env.NVIDIA_API_KEY || process.env.NVCF_API_KEY;
+const authConfig = loadAuthConfig();
+const byokApiKey = authConfig.byokEnabled ? authConfig.customApiKey?.trim() : undefined;
+const byokProvider = authConfig.customLlmProvider?.trim().toLowerCase();
+const byokDefaultBaseUrls = {
+    openai: 'https://api.openai.com/v1',
+    groq: 'https://api.groq.com/openai/v1',
+    gemini: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    nvidia: 'https://integrate.api.nvidia.com/v1',
+};
+const byokBaseUrl = byokApiKey
+    ? authConfig.customBaseUrl?.trim() || byokDefaultBaseUrls[byokProvider || '']
+    : undefined;
+const isByokConfigured = Boolean(byokApiKey && byokBaseUrl);
+const clientCache = new Map();
+export function getClientForModel(modelName) {
+    if (isByokConfigured) {
+        if (!clientCache.has('byok')) {
+            clientCache.set('byok', new OpenAI({ apiKey: byokApiKey, baseURL: byokBaseUrl, timeout: 35000 }));
+        }
+        return clientCache.get('byok');
+    }
+    const modelLower = (modelName || '').toLowerCase();
+    if ((modelLower.startsWith('nvidia/') || modelLower.includes('nemotron') || modelLower.startsWith('deepseek-ai/')) && nvidiaApiKey) {
+        if (!clientCache.has('nvidia')) {
+            clientCache.set('nvidia', new OpenAI({ apiKey: nvidiaApiKey, baseURL: 'https://integrate.api.nvidia.com/v1', timeout: 35000 }));
+        }
+        return clientCache.get('nvidia');
+    }
+    if ((modelLower.startsWith('groq/') || modelLower.includes('groq') || modelLower.startsWith('qwen/') || modelLower.startsWith('llama-') || modelLower.startsWith('llama3-') || modelLower.startsWith('mixtral')) && groqApiKey) {
+        if (!clientCache.has('groq')) {
+            clientCache.set('groq', new OpenAI({ apiKey: groqApiKey, baseURL: 'https://api.groq.com/openai/v1', timeout: 20000 }));
+        }
+        return clientCache.get('groq');
+    }
+    if (modelLower.startsWith('gemini-') && geminiApiKey) {
+        if (!clientCache.has('gemini')) {
+            clientCache.set('gemini', new OpenAI({ apiKey: geminiApiKey, baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai', timeout: 20000 }));
+        }
+        return clientCache.get('gemini');
+    }
+    if (modelLower.startsWith('gpt-') && openaiApiKey) {
+        if (!clientCache.has('openai')) {
+            clientCache.set('openai', new OpenAI({ apiKey: openaiApiKey, baseURL: 'https://api.openai.com/v1', timeout: 20000 }));
+        }
+        return clientCache.get('openai');
+    }
+    if (modelLower.startsWith('openai/')) {
+        if (groqApiKey) {
+            if (!clientCache.has('groq')) {
+                clientCache.set('groq', new OpenAI({ apiKey: groqApiKey, baseURL: 'https://api.groq.com/openai/v1', timeout: 20000 }));
+            }
+            return clientCache.get('groq');
+        }
+        if (nvidiaApiKey) {
+            if (!clientCache.has('nvidia')) {
+                clientCache.set('nvidia', new OpenAI({ apiKey: nvidiaApiKey, baseURL: 'https://integrate.api.nvidia.com/v1', timeout: 35000 }));
+            }
+            return clientCache.get('nvidia');
+        }
+    }
+    // Default fallback to available API provider
+    if (!clientCache.has('proxy')) {
+        const fallbackKey = groqApiKey || nvidiaApiKey || geminiApiKey || openaiApiKey || 'proxy-managed-key';
+        const fallbackBase = groqApiKey
+            ? 'https://api.groq.com/openai/v1'
+            : nvidiaApiKey
+                ? 'https://integrate.api.nvidia.com/v1'
+                : 'https://frontterrain.com/api';
+        clientCache.set('proxy', new OpenAI({ apiKey: fallbackKey, baseURL: fallbackBase, timeout: 25000 }));
+    }
+    return clientCache.get('proxy');
+}
+export const openai = new Proxy({}, {
+    get(_target, prop) {
+        if (prop === 'chat') {
+            return {
+                completions: {
+                    create: (params, options) => {
+                        const model = params?.model || MODEL_FALLBACKS[0] || 'nvidia/nemotron-3.5-lightning-30b-a3b';
+                        const client = getClientForModel(model);
+                        const req = { ...params };
+                        // NVIDIA models do NOT support response_format: { type: 'json_object' } and hang if passed.
+                        if ((model.startsWith('nvidia/') || model.includes('nemotron')) && req.response_format) {
+                            delete req.response_format;
+                        }
+                        return client.chat.completions.create(req, options);
+                    }
+                }
+            };
+        }
+        const defaultClient = getClientForModel(MODEL_FALLBACKS[0]);
+        const val = defaultClient[prop];
+        return typeof val === 'function' ? val.bind(defaultClient) : val;
+    }
 });
-export async function generateRepoSummary(projectName, filesList, packageJsonContent) {
+export const AGENT_MODEL_FALLBACKS = [
+    ...(nvidiaApiKey || byokProvider === 'nvidia' ? ['nvidia/nemotron-3.5-lightning-30b-a3b', 'mistralai/mistral-nemotron'] : []),
+    ...(groqApiKey || byokProvider === 'groq' ? ['groq/compound-mini', 'groq/compound', 'qwen/qwen3.8-27b'] : []),
+    'openai/gpt-oss-20b',
+    ...(openaiApiKey || byokProvider === 'openai' ? ['gpt-4o-mini', 'gpt-4o'] : []),
+];
+export const INIT_MODEL_FALLBACKS = [
+    ...(groqApiKey || byokProvider === 'groq' ? ['qwen/qwen3.6-27b', 'qwen/qwen3.8-27b', 'groq/compound-mini', 'openai/gpt-oss-120b'] : []),
+    ...(geminiApiKey || byokProvider === 'gemini' ? ['gemini-2.5-flash', 'gemini-2.0-flash'] : []),
+    ...(nvidiaApiKey || byokProvider === 'nvidia' ? ['nvidia/nemotron-3.5-lightning-30b-a3b', 'mistralai/mistral-nemotron'] : []),
+    'openai/gpt-oss-20b',
+    ...(openaiApiKey || byokProvider === 'openai' ? ['gpt-4o-mini', 'gpt-4o'] : []),
+];
+export const WEB_MODEL_FALLBACKS = [
+    'qwen/qwen3.8-27b',
+    ...(groqApiKey || byokProvider === 'groq' ? ['qwen/qwen3.6-27b', 'groq/compound-mini', 'groq/compound'] : []),
+    ...(geminiApiKey || byokProvider === 'gemini' ? ['gemini-2.5-flash', 'gemini-2.0-flash'] : []),
+    ...(nvidiaApiKey || byokProvider === 'nvidia' ? ['nvidia/nemotron-3.5-lightning-30b-a3b', 'mistralai/mistral-nemotron'] : []),
+    'openai/gpt-oss-20b',
+    ...(openaiApiKey || byokProvider === 'openai' ? ['gpt-4o-mini', 'gpt-4o'] : []),
+];
+export const MODEL_FALLBACKS = AGENT_MODEL_FALLBACKS;
+export const NVIDIA_INCEPTION_MODELS = [
+    'nvidia/nemotron-3.5-lightning-30b-a3b',
+    'deepseek-ai/deepseek-r1',
+    'mistralai/mistral-nemotron'
+];
+let inceptionBadgeShown = false;
+export function showInceptionBadgeIfNeeded(tier) {
+    if (inceptionBadgeShown)
+        return;
+    const currentTier = (tier || loadAuthConfig().currentTier || 'free').toLowerCase();
+    if (currentTier === 'pro' || currentTier === 'enterprise') {
+        inceptionBadgeShown = true;
+    }
+}
+export function getTierPrioritizedFallbackChain(baseChain) {
+    const config = loadAuthConfig();
+    const tier = (config.currentTier || 'free').toLowerCase();
+    if ((tier === 'pro' || tier === 'enterprise') && (nvidiaApiKey || byokProvider === 'nvidia')) {
+        const inceptionModels = NVIDIA_INCEPTION_MODELS.filter(m => nvidiaApiKey || byokProvider === 'nvidia');
+        const remaining = baseChain.filter(m => !inceptionModels.includes(m));
+        return [...inceptionModels, ...remaining];
+    }
+    return baseChain;
+}
+let currentActiveModel = MODEL_FALLBACKS[0];
+let lastFallbackInfo = null;
+export function getActiveModelInfo() {
+    return {
+        primaryModel: MODEL_FALLBACKS[0],
+        currentActiveModel,
+        fallbackChain: [...MODEL_FALLBACKS],
+        lastFallbackInfo,
+    };
+}
+// Models scheduled for decommission: map model id -> decommission date (YYYY-MM-DD)
+const DECOMMISSIONED_MODELS = {
+    'llama3-8b-8192': '2024-12-31',
+    'llama3-70b-8192': '2024-12-31',
+    'gpt-oss-8b': '2024-01-01',
+    'deepseek-r1-distill-llama-70b': '2025-01-01',
+    'deepseek-r1-distill-qwen-32b': '2025-01-01',
+};
+export function getModelDecommissionInfo(model) {
+    const date = DECOMMISSIONED_MODELS[model];
+    if (!date)
+        return { decommissioned: false };
+    const now = new Date();
+    const decommDate = new Date(date + 'T00:00:00Z');
+    return { decommissioned: now >= decommDate, decommissionDate: date };
+}
+export function isQuotaExceededError(err) {
+    if (!err)
+        return false;
+    const status = err?.status || err?.statusCode || err?.response?.status;
+    const errStr = String(err?.message || err?.error?.message || err?.error || err || '').toLowerCase();
+    return (status === 429 ||
+        errStr.includes('429') ||
+        errStr.includes('insufficient_quota') ||
+        errStr.includes('quota exceeded') ||
+        errStr.includes('exceeded your current quota') ||
+        errStr.includes('rate_limit_exceeded') ||
+        errStr.includes('quota_exceeded') ||
+        errStr.includes('resource_exhausted') ||
+        errStr.includes('out of credits') ||
+        errStr.includes('too many requests'));
+}
+export function sanitizeMessage(msg) {
+    if (!msg || typeof msg !== 'object')
+        return msg;
+    const cleanMsg = {};
+    if (typeof msg.role === 'string' && msg.role.trim().length > 0) {
+        cleanMsg.role = msg.role.trim();
+    }
+    else {
+        cleanMsg.role = 'user';
+    }
+    if (cleanMsg.role === 'tool') {
+        cleanMsg.role = 'user';
+        const toolIdStr = msg.tool_call_id ? ` (ID: ${msg.tool_call_id})` : '';
+        const nameStr = msg.name ? ` (${msg.name})` : '';
+        cleanMsg.content = `[Tool Execution Result${nameStr}${toolIdStr}]:\n${msg.content ?? ''}`;
+    }
+    else {
+        if (msg.content !== undefined) {
+            cleanMsg.content = msg.content;
+        }
+    }
+    if (typeof msg.name === 'string' && msg.name.trim().length > 0) {
+        cleanMsg.name = msg.name.trim();
+    }
+    if (Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
+        cleanMsg.tool_calls = msg.tool_calls.map((tc) => ({
+            id: String(tc?.id || 'call_' + Math.random().toString(36).substring(2, 9)),
+            type: tc?.type || 'function',
+            function: tc?.function
+                ? {
+                    name: String(tc.function.name || ''),
+                    arguments: typeof tc.function.arguments === 'string'
+                        ? tc.function.arguments
+                        : JSON.stringify(tc.function.arguments || {}),
+                }
+                : { name: '', arguments: '{}' },
+        }));
+    }
+    if (typeof msg.tool_call_id === 'string' && msg.tool_call_id.trim().length > 0) {
+        cleanMsg.tool_call_id = msg.tool_call_id.trim();
+    }
+    if (msg.function_call && typeof msg.function_call === 'object') {
+        cleanMsg.function_call = msg.function_call;
+    }
+    return cleanMsg;
+}
+export function sanitizeMessages(messages) {
+    if (!Array.isArray(messages))
+        return [];
+    const rawCleaned = messages
+        .filter((m) => m && typeof m === 'object')
+        .map(sanitizeMessage);
+    if (rawCleaned.length === 0) {
+        return [{ role: 'user', content: 'Begin task execution.' }];
+    }
+    // 1. Separate System messages (put at front if index 0, or convert subsequent system messages to user context)
+    const result = [];
+    let hasSystemPrompt = false;
+    for (let i = 0; i < rawCleaned.length; i++) {
+        const item = rawCleaned[i];
+        if (item.role === 'system') {
+            if (!hasSystemPrompt && result.length === 0) {
+                result.push(item);
+                hasSystemPrompt = true;
+            }
+            else {
+                result.push({
+                    role: 'user',
+                    content: `[System Context]:\n${item.content || ''}`,
+                });
+            }
+        }
+        else {
+            result.push(item);
+        }
+    }
+    // 2. Collapse consecutive messages with same role
+    const collapsed = [];
+    for (const msg of result) {
+        if (collapsed.length === 0) {
+            collapsed.push({ ...msg });
+            continue;
+        }
+        const prev = collapsed[collapsed.length - 1];
+        if (prev.role === msg.role && msg.role !== 'system') {
+            const prevText = typeof prev.content === 'string' ? prev.content : '';
+            const currText = typeof msg.content === 'string' ? msg.content : '';
+            prev.content = prevText + (prevText && currText ? '\n\n' : '') + currText;
+            if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
+                prev.tool_calls = [...(prev.tool_calls || []), ...msg.tool_calls];
+            }
+        }
+        else {
+            collapsed.push({ ...msg });
+        }
+    }
+    // 3. Ensure conversation ends with 'user' role for Gemini 3.6 Flash / Anthropic Claude API compatibility
+    if (collapsed.length === 0) {
+        return [{ role: 'user', content: 'Begin task execution.' }];
+    }
+    const lastMsg = collapsed[collapsed.length - 1];
+    if (lastMsg.role !== 'user') {
+        collapsed.push({
+            role: 'user',
+            content: 'Please proceed with executing necessary tools to complete the user goal, or invoke task_completed if finished.',
+        });
+    }
+    // 4. Prune only very old tool result contents if total message length is high (>120,000 chars ~30k tokens) to prevent payload errors
+    const totalLen = collapsed.reduce((acc, m) => acc + (typeof m.content === 'string' ? m.content.length : 0), 0);
+    if (totalLen > 120000) {
+        // Leave recent messages (last 6) intact; prune older tool execution results to 1500 chars max
+        const keepIndexStart = Math.max(1, collapsed.length - 6);
+        for (let i = 1; i < keepIndexStart; i++) {
+            const msg = collapsed[i];
+            if (msg && msg.role === 'user' && typeof msg.content === 'string') {
+                if (msg.content.includes('[Tool Execution Result') && msg.content.length > 1500) {
+                    msg.content = msg.content.slice(0, 1500) + '\n...[Older tool output truncated for token efficiency]...';
+                }
+            }
+        }
+    }
+    return collapsed;
+}
+const LLM_CONCURRENCY = Math.max(1, Number.parseInt(process.env.FT_LLM_CONCURRENCY || '1', 10) || 1);
+let activeLlmRequests = 0;
+const pendingLlmRequests = [];
+async function withLlmConcurrency(fn) {
+    if (activeLlmRequests >= LLM_CONCURRENCY) {
+        await new Promise((resolve) => pendingLlmRequests.push(resolve));
+    }
+    activeLlmRequests++;
+    try {
+        return await fn();
+    }
+    finally {
+        activeLlmRequests--;
+        const next = pendingLlmRequests.shift();
+        if (next)
+            next();
+    }
+}
+export async function callOpenAIWithRetry(fn, maxRetries = 2, initialDelayMs = 300, customFallbackChain) {
+    return withLlmConcurrency(() => callOpenAIWithRetryUnqueued(fn, maxRetries, initialDelayMs, customFallbackChain));
+}
+async function callOpenAIWithRetryUnqueued(fn, maxRetries, initialDelayMs, customFallbackChain) {
+    let lastError;
+    const MODEL_REPLACEMENTS = {
+        'llama3-8b-8192': 'qwen/qwen3.8-27b',
+        'llama3-70b-8192': 'qwen/qwen3.8-27b',
+        'llama-3.3-70b-versatile': 'qwen/qwen3.8-27b',
+        'llama-3.1-8b-instant': 'qwen/qwen3.8-27b',
+        'gpt-oss-8b': 'openai/gpt-oss-20b',
+        'deepseek-r1-distill-llama-70b': 'qwen/qwen3.8-27b',
+        'deepseek-r1-distill-qwen-32b': 'qwen/qwen3.8-27b',
+    };
+    showInceptionBadgeIfNeeded();
+    const rawChain = customFallbackChain && customFallbackChain.length > 0 ? customFallbackChain : MODEL_FALLBACKS;
+    const targetChain = getTierPrioritizedFallbackChain(rawChain);
+    const primaryCandidate = customFallbackChain && customFallbackChain.length > 0
+        ? customFallbackChain[0]
+        : (currentActiveModel && targetChain.includes(currentActiveModel) ? currentActiveModel : targetChain[0]);
+    const modelsToTry = [
+        primaryCandidate,
+        ...targetChain.filter((m) => m !== primaryCandidate),
+    ];
+    for (let i = 0; i < modelsToTry.length; i++) {
+        const model = modelsToTry[i] || 'nvidia/nemotron-3.5-lightning-30b-a3b';
+        let modelToUse = model;
+        try {
+            const info = getModelDecommissionInfo(model);
+            if (info.decommissioned) {
+                const repl = MODEL_REPLACEMENTS[model];
+                if (repl)
+                    modelToUse = repl;
+            }
+        }
+        catch {
+            // proceed using the original model if any parsing error occurs
+        }
+        if (i > 0 && lastError) {
+            const prevModel = currentActiveModel || 'llama-3.3-70b-versatile';
+            currentActiveModel = modelToUse;
+            lastFallbackInfo = {
+                previousModel: prevModel,
+                fallbackModel: modelToUse,
+                reason: lastError?.message || 'Rate limit or service unavailable',
+                timestamp: new Date(),
+            };
+            console.log(`\n${chalk.bold.yellow('Fallback with:')} ${chalk.dim(prevModel)} failed (${lastError?.message || '429/Rate-limit'}).`);
+            console.log(` ${chalk.bold.cyan('↳ Routed To:')} ${chalk.bold.green(modelToUse)}\n`);
+            // Brief 100ms pause before trying fallback model for instant failover
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        else {
+            currentActiveModel = modelToUse;
+        }
+        let attempt = 0;
+        while (attempt <= maxRetries) {
+            try {
+                const result = await fn(modelToUse);
+                logAuditEvent('llm_completion', { model: modelToUse, attempt });
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                attempt++;
+                const status = error?.status || error?.statusCode;
+                const errorStr = String(error?.message || error?.error?.message || error?.error || error || '').toLowerCase();
+                const isHardQuota = errorStr.includes('insufficient_quota') ||
+                    errorStr.includes('exceeded your current quota') ||
+                    errorStr.includes('out of credits') ||
+                    errorStr.includes('credit limit reached') ||
+                    errorStr.includes('tokens per day') ||
+                    errorStr.includes('(tpd)') ||
+                    errorStr.includes('tpd: limit');
+                if (isHardQuota) {
+                    throw error;
+                }
+                const isModelNotFound = status === 404 || errorStr.includes('404') || errorStr.includes('does not exist') || errorStr.includes('not have access');
+                const isUnsupportedTool = errorStr.includes('tool calling is not supported') || errorStr.includes('tool choice') || (status === 400 && errorStr.includes('tool'));
+                const isPayloadTooLarge = status === 413 || errorStr.includes('413') || errorStr.includes('request too large') || errorStr.includes('reduce your message size');
+                const isTimeout = status === 408 || errorStr.includes('timeout') || errorStr.includes('timed out') || errorStr.includes('econnaborted') || errorStr.includes('request timed out') || error?.code === 'ETIMEDOUT' || error?.code === 'ECONNABORTED' || error?.name === 'AbortError';
+                if (isModelNotFound || isUnsupportedTool || isPayloadTooLarge || isTimeout) {
+                    break;
+                }
+                const isRateLimit = status === 429 ||
+                    errorStr.includes('429') ||
+                    errorStr.includes('ratelimit') ||
+                    errorStr.includes('rate limit') ||
+                    errorStr.includes('upstream api error');
+                const isServerError = typeof status === 'number' && status >= 500 && status < 600;
+                // If multiple models exist in fallback chain, failover immediately on rate limit to avoid long delays
+                if ((isRateLimit || isServerError) && i < modelsToTry.length - 1 && attempt >= 1) {
+                    break;
+                }
+                if ((isRateLimit || isServerError) && attempt <= maxRetries) {
+                    const delay = Math.pow(2, attempt - 1) * initialDelayMs + Math.random() * 100;
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+                break;
+            }
+        }
+    }
+    throw lastError;
+}
+async function mapWithConcurrency(items, concurrency, fn) {
+    const results = new Array(items.length);
+    let currentIndex = 0;
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (currentIndex < items.length) {
+            const index = currentIndex++;
+            results[index] = await fn(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+function sanitizeRepoSummary(parsed, projectName, filesList) {
+    const entryPoint = parsed.entryPoint && typeof parsed.entryPoint === 'string' && parsed.entryPoint.length > 2
+        ? parsed.entryPoint
+        : (filesList.find(f => /index|main|app|server|entry|root/i.test(f)) || filesList[0] || 'index.js');
+    // Sanitize summary lines (ensure bold headers exist and description after colon is not just commas/dots)
+    let summary = typeof parsed.summary === 'string' ? parsed.summary : '';
+    summary = summary.replace(/-\s*\*\*(?:\s*\*)*:\s*/g, '- **Core Capability**: ');
+    // Remove bullets where text after colon is only punctuation/commas/spaces
+    const summaryLines = summary.split('\n').filter((line) => {
+        const parts = line.split(':');
+        if (parts.length > 1) {
+            const val = parts.slice(1).join(':').trim();
+            return val.length > 3 && !/^[,\s.\-[\]:]*$/.test(val);
+        }
+        return line.trim().length > 10;
+    });
+    summary = summaryLines.join('\n').trim();
+    if (!summary || summary.length < 20) {
+        summary = `- **Core Capability**: ${projectName} repository analyzed for developer onboarding and codebase navigation.\n- **Architecture & Stack**: Multi-component application structure.\n- **Architectural Moat**: Automated code teardown and due-diligence mapping.`;
+    }
+    // Sanitize readOrder (remove incomplete items where description after -> is empty/commas)
+    let readOrder = Array.isArray(parsed.readOrder)
+        ? parsed.readOrder
+            .filter((r) => typeof r === 'string')
+            .map((r) => r.trim())
+            .filter((r) => {
+            const parts = r.split('->');
+            if (parts.length > 1) {
+                const desc = parts[1].trim();
+                return desc.length > 3 && !/^[,\s.\-[\]:]*$/.test(desc);
+            }
+            return r.length > 8;
+        })
+        : [];
+    if (readOrder.length === 0) {
+        const mainFiles = filesList.filter(f => !f.includes('node_modules') && !f.startsWith('.')).slice(0, 3);
+        if (mainFiles.length > 0) {
+            readOrder = mainFiles.map(f => `${f} -> Core source module in ${projectName}`);
+        }
+        else {
+            readOrder = [
+                'README.md -> Overview and installation instructions',
+                'package.json -> Dependency manifest and script configurations'
+            ];
+        }
+    }
+    // Sanitize painPoints (remove incomplete items where description after colon is empty/commas)
+    let painPoints = Array.isArray(parsed.painPoints)
+        ? parsed.painPoints
+            .filter((p) => typeof p === 'string')
+            .map((p) => p.trim())
+            .filter((p) => {
+            const parts = p.split(':');
+            if (parts.length > 1) {
+                const desc = parts.slice(1).join(':').trim();
+                return desc.length > 3 && !/^[,\s.\-[\]:]*$/.test(desc);
+            }
+            return p.length > 10;
+        })
+        : [];
+    if (painPoints.length === 0) {
+        painPoints = [
+            ` [Subsystem Risk]: Verify environment variable configurations and API credentials for ${projectName}.`,
+            ` [Scaling Bottleneck]: Ensure core services in ${projectName} handle high load and concurrency.`,
+            ` [Execution Requirement]: Validate local setup and build dependencies prior to deployment.`
+        ];
+    }
+    let architectureDiagram = typeof parsed.architectureDiagram === 'string' && parsed.architectureDiagram.trim().length > 10
+        ? parsed.architectureDiagram.trim()
+        : `┌───────────────────────┐
+│ Client / User │
+└───────────┬───────────┘
+ │
+ 
+┌───────────────────────┐
+│ ${projectName.padEnd(21).substring(0, 21)} │
+└───────────┬───────────┘
+ │
+ 
+┌───────────────────────┐
+│ Data & Services │
+└───────────────────────┘`;
+    return { summary, entryPoint, readOrder, painPoints, architectureDiagram };
+}
+export async function generateRepoSummary(projectName, filesList, packageJsonContent, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
     const prompt = `
 You are a world-class Principal Software Architect and Y Combinator Technical Partner conducting an elite, high-energy codebase teardown for a YC Demo Day pitch.
 
 Target Project: ${projectName}
+Target Output Language: ${langInfo.displayName}
 
 File Tree Overview:
 ${filesList.join('\n')}
@@ -24,46 +556,743 @@ ${packageJsonContent}
 
 Your goal: Generate an extremely engaging, technically deep, punchy, and impressive breakdown of this codebase. Avoid generic or dry 1-sentence answers. Make it read like a million-dollar technical due-diligence report that wows investors and engineers alike!
 
+CRITICAL JSON & SCRIPT GENERATION RULE: ${langInfo.instruction}
+You MUST write complete, deep, rich technical sentences in ${langInfo.displayName} for EVERY SINGLE property in the JSON schema below.
+Keep the bold bullet header titles exact in English (e.g. "- **Core Capability**:", "- **Architecture & Stack**:", "- **Architectural Moat**:") and write the descriptive explanation after the colon in ${langInfo.displayName}.
+Do NOT leave any empty strings, isolated commas, or blank placeholders after colons or arrows (e.g. do NOT output ", ," or "file.js -> ").
+Every read order item MUST be formatted as: "filepath -> Detailed explanation in ${langInfo.displayName}".
+Every pain point item MUST be formatted as: " [Category]: Detailed technical risk analysis in ${langInfo.displayName}".
+
 Provide a JSON output matching this exact schema:
 {
-  "summary": "A rich, high-octane 3-4 sentence architectural executive summary explaining: 1) The core problem solved and primary functionality, 2) The underlying technical stack & runtime architecture, 3) The architectural moat or unique value proposition of this engineering design.",
-  "entryPoint": "the exact relative path to the primary execution entry point file",
-  "readOrder": [
-    "file/path/1 -> Strategic reason detailing why this file is foundational to the architecture",
-    "file/path/2 -> Technical justification for reading this subsystem next",
-    "file/path/3 -> Crucial module detailing core business logic or pipeline routing"
-  ],
-  "painPoints": [
-    "⚡ [Subsystem Risk]: Deep technical insight into potential architectural debt, fragile dependency, or scaling bottleneck",
-    "⚡ [Scaling Bottleneck]: Critical operational or state management risk engineers must watch out for",
-    "⚡ [Execution Note]: Key architectural constraint or environment requirement for developer onboarding"
-  ]
+ "summary": "- **Core Capability**: A punchy 1-2 sentence description of what the project does written in ${langInfo.displayName}.\n- **Architecture & Stack**: Tech stack & core design pattern written in ${langInfo.displayName}.\n- **Architectural Moat**: Unique engineering advantage or value prop written in ${langInfo.displayName}.",
+ "entryPoint": "the exact relative path to the primary execution entry point file",
+ "readOrder": [
+ "file/path/1 -> Strategic reason written in ${langInfo.displayName} detailing why this file is foundational to the architecture",
+ "file/path/2 -> Technical justification written in ${langInfo.displayName} for reading this subsystem next",
+ "file/path/3 -> Crucial module written in ${langInfo.displayName} detailing core business logic or pipeline routing"
+ ],
+ "painPoints": [
+ " [Subsystem Risk]: Deep technical insight written in ${langInfo.displayName} into potential architectural debt, fragile dependency, or scaling bottleneck",
+ " [Scaling Bottleneck]: Critical operational or state management risk written in ${langInfo.displayName} engineers must watch out for",
+ " [Execution Note]: Key architectural constraint or environment requirement written in ${langInfo.displayName} for developer onboarding"
+ ],
+ "architectureDiagram": "A clean 4-8 line ASCII box diagram representing the subsystem flow (e.g. [Client] --> [API Router] --> [Service Layer] --> [Database])"
 }
 `;
     try {
-        const response = await openai.chat.completions.create({
-            model: 'llama-3.3-70b-versatile',
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
             messages: [{ role: 'user', content: prompt }],
             response_format: { type: 'json_object' },
-        });
-        return JSON.parse(response.choices[0]?.message?.content || '{}');
+        }), 2, 300, INIT_MODEL_FALLBACKS);
+        const parsed = JSON.parse(response.choices[0]?.message?.content || '{}');
+        return sanitizeRepoSummary(parsed, projectName, filesList);
+    }
+    catch (error) {
+        console.error("OpenAI Error:", error);
+        return sanitizeRepoSummary({}, projectName, filesList);
+    }
+}
+export async function explainCodebaseRisks(file, lineRanges, commitMsgs, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
+    const prompt = `
+You are a Principal Software Architect analyzing a fragile, high-churn source code file in a software repository.
+
+File Path: ${file}
+Fragile Hotspot Line Ranges: ${lineRanges.join(', ') || 'Entire File'}
+Recent Hotfix / Patch Commit Messages:
+${commitMsgs.map((m) => `- ${m}`).join('\n')}
+
+Output Language: ${langInfo.displayName}
+Language Instruction: ${langInfo.instruction}
+
+Your Goal: Provide a deep technical explanation of:
+1. Why these specific line ranges/hotspots are repeatedly failing or requiring emergency patches.
+2. ️ What architectural debt or design pattern flaws are creating this fragility.
+3. ️ Step-by-step actionable recommendations for refactoring and stabilizing this file.
+
+Format the output in clean, elegant Markdown.
+`;
+    try {
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+        }));
+        return response.choices[0]?.message?.content || 'Unable to generate risk explanation for this file.';
+    }
+    catch (error) {
+        return `️ Risk Analysis Fallback: File ${file} shows ${commitMsgs.length} recent hotfixes in lines ${lineRanges.join(', ')}. Common root causes include tight coupling, missing unit tests, or unhandled edge cases in execution logic.`;
+    }
+}
+export async function askRepoQuestion(question, projectName, filesList, manifestContent, chatHistory = [], options) {
+    const isWebQuery = options?.useWeb ||
+        !!options?.webContext ||
+        /^\/(web|internet|search)\b/i.test(question) ||
+        /\b(search the web|internet|online docs|latest docs|web search)\b/i.test(question);
+    let liveWebContext = options?.webContext || '';
+    if (isWebQuery && !liveWebContext) {
+        try {
+            const cleanSearchQuery = question.replace(/^\/(web|internet|search)\s*/i, '').trim();
+            const webRes = await getWebContext(cleanSearchQuery || question);
+            liveWebContext = webRes.context;
+        }
+        catch {
+            // Fallback if web fetch fails
+        }
+    }
+    const langInfo = getLanguageInstruction(options?.language, options?.native);
+    const systemPrompt = `You are FrontTerrain AI, a world-class Principal Software Architect and Y Combinator Technical Co-Pilot.
+You have indexed the codebase for project: "${projectName}".
+${isWebQuery ? ' Internet Access: ACTIVE. You have live web search capabilities enabled.' : ''}
+
+Repository File Structure:
+${filesList.slice(0, 150).join('\n')}
+
+Manifest / Config Highlights:
+${manifestContent.slice(0, 2000)}
+${liveWebContext
+        ? `\n${liveWebContext}\nInstructions for Internet Context: Utilize the live web search results above to supplement repository technical analysis, provide up-to-date documentation details, and answer external library or architectural questions accurately.`
+        : ''}
+
+Your mission: Answer technical questions about this repository and web context with extreme clarity, deep technical insight, and structured formatting.
+
+CRITICAL LANGUAGE & TERMINAL RENDERING REQUIREMENT: ${langInfo.instruction} Translate all explanations, section titles, and architectural notes into ${langInfo.displayName} while keeping exact code blocks, filenames, function names, and option flags intact.
+
+CRITICAL CLI FORMATTING INSTRUCTIONS:
+1. Always structure your answer into short sections using Markdown headers (e.g. ### Architecture Overview).
+2. Use bold lead-in bullet points (e.g. - **Subsystem**: Description) instead of monolithic text walls.
+3. Enclose all filenames, function names, paths, and options in backticks (e.g. \`src/index.ts\`).
+4. Wrap any code snippet in typed markdown code blocks (e.g. \`\`\`ts ... \`\`\`).
+5. Keep paragraphs short (2-3 sentences max) to ensure medium line-width readability in terminal interfaces.`;
+    const messages = [
+        { role: 'system', content: systemPrompt },
+        ...chatHistory,
+        { role: 'user', content: question },
+    ];
+    const fallbackChain = isWebQuery ? WEB_MODEL_FALLBACKS : MODEL_FALLBACKS;
+    try {
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
+            messages: sanitizeMessages(messages),
+        }), 2, 300, fallbackChain);
+        return response.choices[0]?.message?.content || 'No response generated from AI.';
     }
     catch (error) {
         console.error("OpenAI Error:", error);
-        // Fallback if no API key or network failure
+        return `️ AI Error: Could not generate answer (${error instanceof Error ? error.message : String(error)}). Please check network or proxy credentials.`;
+    }
+}
+export async function generateCodeScanReport(projectName, filesList, codeSample, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
+    const prompt = `You are a Principal Security & Software Quality Auditor performing a read-only bug and code quality scan for project: "${projectName}".
+
+File Tree:
+${filesList.slice(0, 100).join('\n')}
+
+Key Code Sample / Config Context:
+${codeSample.slice(0, 2500)}
+
+Language requirement: Write descriptions in ${langInfo.displayName}.
+
+Identify 3 potential bugs, unhandled null pointers, fragile error handlers, or performance risks in this repository.
+Return a valid JSON array matching this exact schema:
+[
+ {
+ "id": 1,
+ "title": "Short title of the bug or issue",
+ "file": "relative/file/path.ts",
+ "severity": "high",
+ "description": "Detailed explanation of why this is a bug or fragile pattern, matching patterns from past hotfixes."
+ }
+]
+`;
+    try {
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+            response_format: { type: 'json_object' },
+        }));
+        const content = response.choices[0]?.message?.content || '{}';
+        const parsed = JSON.parse(content);
+        let rawList = [];
+        if (Array.isArray(parsed))
+            rawList = parsed;
+        else if (parsed.issues && Array.isArray(parsed.issues))
+            rawList = parsed.issues;
+        else if (parsed.bugs && Array.isArray(parsed.bugs))
+            rawList = parsed.bugs;
+        else if (parsed.reports && Array.isArray(parsed.reports))
+            rawList = parsed.reports;
+        if (rawList.length === 0) {
+            rawList = [
+                {
+                    title: "Potential Unhandled Null Check in Service Provider",
+                    file: filesList.find(f => f.includes('service') || f.includes('api') || f.includes('ts') || f.includes('js')) || "src/index.ts",
+                    severity: "high",
+                    description: "Missing defensive null check on optional data payloads which can trigger unhandled promise rejections."
+                },
+                {
+                    title: "Unbounded Memory Consumption in Log/Buffer Batching",
+                    file: filesList.find(f => f.includes('utils') || f.includes('log') || f.includes('engine')) || "src/engine/llm.ts",
+                    severity: "medium",
+                    description: "Array allocations in loop routines lack upper bounding limits under high concurrency."
+                },
+                {
+                    title: "Missing Environment Fallback for Proxy Key Authentication",
+                    file: "package.json",
+                    severity: "low",
+                    description: "Fallback default string used when authorization environment variables are missing."
+                }
+            ];
+        }
+        return rawList.map((item, idx) => ({
+            id: idx + 1,
+            title: typeof item.title === 'string' ? item.title : `Code Quality Issue #${idx + 1}`,
+            file: typeof item.file === 'string' ? item.file : (filesList[0] || 'src/index.ts'),
+            severity: (item.severity && ['high', 'medium', 'low'].includes(String(item.severity).toLowerCase())
+                ? String(item.severity).toLowerCase()
+                : 'medium'),
+            description: typeof item.description === 'string' ? item.description : 'Potential vulnerability or code smell identified.',
+        }));
+    }
+    catch {
+        return [
+            {
+                id: 1,
+                title: "Defensive Check Missing in Primary Controller",
+                file: filesList[0] || "src/index.ts",
+                severity: "high",
+                description: "Dynamic property access on unvalidated response payload may throw TypeError."
+            }
+        ];
+    }
+}
+export async function generateCodeRecommendations(projectName, filesList, codeSample, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
+    const prompt = `You are a Principal Software Architect and Y Combinator Technical Partner.
+Provide architecture, performance, and DSA-level suggestions for repository "${projectName}".
+
+File Tree:
+${filesList.slice(0, 100).join('\n')}
+
+Manifest / Code Highlights:
+${codeSample.slice(0, 2000)}
+
+Language requirement: ${langInfo.instruction} Write all headers and explanations in ${langInfo.displayName}.
+
+Structure your response into 3 sections:
+1. ### ️ Architectural Enhancements
+2. ### Performance & Caching Optimizations
+3. ### Algorithmic & DSA Recommendations
+
+Provide concrete, actionable technical recommendations with exact file names and code pattern suggestions.
+`;
+    try {
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+        }));
+        return response.choices[0]?.message?.content || 'No recommendations generated.';
+    }
+    catch (error) {
+        return `️ Could not generate recommendations: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+export async function generateFeaturePlan(idea, projectName, filesList, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
+    const prompt = `You are a Lead Solutions Architect assessing feature request: "${idea}" for project "${projectName}".
+
+File Tree:
+${filesList.slice(0, 120).join('\n')}
+
+Language requirement: ${langInfo.instruction} Write all explanations in ${langInfo.displayName}.
+
+Produce a comprehensive Feasibility Assessment & Step-by-Step Implementation Roadmap:
+1. ### Feasibility & Complexity Assessment
+2. ### Target Files & Affected Subsystems
+3. ### ️ Step-by-Step Implementation Plan
+4. ### ️ Architectural Risks & Considerations
+`;
+    try {
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+        }));
+        return response.choices[0]?.message?.content || 'No feature plan generated.';
+    }
+    catch (error) {
+        return `️ Feasibility analysis error: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+export function cleanAndParseJsonPayload(rawContent) {
+    if (!rawContent || !rawContent.trim())
+        return {};
+    let cleaned = rawContent.trim();
+    if (cleaned.startsWith('```')) {
+        cleaned = cleaned.replace(/^```[a-zA-Z0-9_\-]*\r?\n?/, '').replace(/\r?\n?```\s*$/, '').trim();
+    }
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch { }
+    const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+        try {
+            return JSON.parse(jsonMatch[0]);
+        }
+        catch { }
+    }
+    const tripleQuoteFixed = cleaned.replace(/"(code|fixedCode|fixed_code|content|source|snippet|description)"\s*:\s*"""([\s\S]*?)"""/g, (_match, key, val) => {
+        return `"${key}": ${JSON.stringify(val.trim())}`;
+    });
+    try {
+        return JSON.parse(tripleQuoteFixed);
+    }
+    catch { }
+    const parsed = {};
+    const descMatch = cleaned.match(/"description"\s*:\s*"([\s\S]*?)"(?=\s*,\s*"(?:code|targetFile|fixedCode)")/i);
+    if (descMatch && descMatch[1]) {
+        parsed.description = descMatch[1].trim();
+    }
+    const codeMatch = cleaned.match(/"(?:code|fixedCode|fixed_code|content|source|snippet)"\s*:\s*(?:"""|"|```[a-zA-Z0-9_-]*\r?\n)?([\s\S]*?)(?:"""|"|```\s*\}|\}\s*$)/i);
+    if (codeMatch && codeMatch[1]) {
+        parsed.code = codeMatch[1].replace(/^```[a-zA-Z0-9_\-]*\r?\n?/, '').replace(/\r?\n?```\s*$/, '').trim();
+    }
+    return parsed;
+}
+export function extractCodeFromRawResponse(rawContent) {
+    if (!rawContent || !rawContent.trim())
+        return undefined;
+    const codeBlockMatch = rawContent.match(/```(?:[a-zA-Z0-9_\-]+)?\r?\n([\s\S]*?)(?:```|$)/);
+    if (codeBlockMatch && codeBlockMatch[1] && codeBlockMatch[1].trim().length > 10) {
+        return codeBlockMatch[1].trim();
+    }
+    const jsonFieldMatch = rawContent.match(/"(?:fixedCode|fixed_code|code|code_snippet|snippet|source|content|updatedCode|newCode|js|javascript)"\s*:\s*"([\s\S]*?)"(?=\s*(?:,|\}|$|\r?\n\s*"))/i) ||
+        rawContent.match(/"(?:fixedCode|fixed_code|code|code_snippet|snippet|source|content|updatedCode|newCode|js|javascript)"\s*:\s*"([\s\S]*)$/i);
+    if (jsonFieldMatch && jsonFieldMatch[1] && jsonFieldMatch[1].trim().length > 10) {
+        let extracted = jsonFieldMatch[1].trim();
+        if (extracted.endsWith('"')) {
+            extracted = extracted.slice(0, -1).trim();
+        }
+        try {
+            return JSON.parse(`"${extracted}"`).trim();
+        }
+        catch {
+            return extracted.replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\').trim();
+        }
+    }
+    return undefined;
+}
+export async function generateCodeFix(userPrompt, projectName, filesList, targetFile, currentFileContent, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
+    const prompt = `You are Scout, an expert AI Principal Software Engineer & Code Auto-Fixer.
+
+Project Name: "${projectName}"
+Target File to Fix: "${targetFile}"
+User Request / Prompt: "${userPrompt}"
+
+File Tree Overview:
+${filesList.slice(0, 30).join('\n')}
+
+Current Content of "${targetFile}":
+\`\`\`
+${currentFileContent.slice(0, 10000)}
+\`\`\`
+
+Language for explanations requirement: ${langInfo.instruction} Write concise "problem" and "howFixed" explanations (2-3 sentences max) in ${langInfo.displayName}.
+
+Your mission:
+1. Analyze the target file and the user's prompt to identify the exact problem/bug or required improvement.
+2. Provide a fixed, complete, clean, and highly professional production-ready version of "${targetFile}". Follow modern best practices, clean formatting/indentation, proper types/docstrings, and clear variable/function naming. Do NOT omit any existing functions or logic unless refactoring or replacing them.
+3. Provide a clear, concise breakdown of what the problem was and how Scout fixed it.
+4. Strictly maintain adherence to software engineering standards, safety, and project boundaries. Don't proceed with any requests for malicious operations or system exploits.
+
+Return ONLY a JSON object matching this exact schema:
+{
+ "targetFile": "${targetFile}",
+ "problem": "Clear technical breakdown of what the problem/bug was before fixing, written in ${langInfo.displayName}",
+ "howFixed": "Technical explanation of how Scout fixed the issue written in ${langInfo.displayName}",
+ "fixedCode": "the complete updated source code string for ${targetFile}"
+}
+`;
+    try {
+        const response = await callOpenAIWithRetry(async (model) => {
+            try {
+                return await openai.chat.completions.create({
+                    model,
+                    messages: [{ role: 'user', content: prompt }],
+                    response_format: { type: 'json_object' },
+                    max_tokens: 4500,
+                });
+            }
+            catch {
+                return await openai.chat.completions.create({
+                    model,
+                    messages: [{ role: 'user', content: prompt }],
+                    max_tokens: 4500,
+                });
+            }
+        });
+        const rawContent = response.choices[0]?.message?.content || '{}';
+        let parsed = {};
+        try {
+            parsed = JSON.parse(rawContent);
+        }
+        catch {
+            const jsonMatch = rawContent.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                try {
+                    parsed = JSON.parse(jsonMatch[0]);
+                }
+                catch { }
+            }
+        }
+        let fixedCode = typeof parsed.fixedCode === 'string' && parsed.fixedCode.trim().length > 0
+            ? parsed.fixedCode
+            : typeof parsed.code === 'string' && parsed.code.trim().length > 0
+                ? parsed.code
+                : typeof parsed.content === 'string' && parsed.content.trim().length > 0
+                    ? parsed.content
+                    : typeof parsed.source === 'string' && parsed.source.trim().length > 0
+                        ? parsed.source
+                        : typeof parsed.codeContent === 'string' && parsed.codeContent.trim().length > 0
+                            ? parsed.codeContent
+                            : typeof parsed.fileContent === 'string' && parsed.fileContent.trim().length > 0
+                                ? parsed.fileContent
+                                : typeof parsed.fixed_code === 'string' && parsed.fixed_code.trim().length > 0
+                                    ? parsed.fixed_code
+                                    : typeof parsed.snippet === 'string' && parsed.snippet.trim().length > 0
+                                        ? parsed.snippet
+                                        : typeof parsed.code_snippet === 'string' && parsed.code_snippet.trim().length > 0
+                                            ? parsed.code_snippet
+                                            : typeof parsed.updatedCode === 'string' && parsed.updatedCode.trim().length > 0
+                                                ? parsed.updatedCode
+                                                : typeof parsed.newCode === 'string' && parsed.newCode.trim().length > 0
+                                                    ? parsed.newCode
+                                                    : typeof parsed.js === 'string' && parsed.js.trim().length > 0
+                                                        ? parsed.js
+                                                        : typeof parsed.javascript === 'string' && parsed.javascript.trim().length > 0
+                                                            ? parsed.javascript
+                                                            : typeof parsed.solution === 'string' && parsed.solution.trim().length > 0
+                                                                ? parsed.solution
+                                                                : extractCodeFromRawResponse(rawContent) || currentFileContent;
+        // Clean up code block markdown fences if model wrapped fixedCode in ```
+        fixedCode = fixedCode.trim();
+        if (fixedCode.startsWith('```')) {
+            fixedCode = fixedCode.replace(/^```[a-zA-Z0-9_\-]*\r?\n?/, '').replace(/\r?\n?```\s*$/, '').trim();
+        }
+        return {
+            targetFile: parsed.targetFile || targetFile,
+            problem: parsed.problem || `Issue identified based on user prompt: "${userPrompt}"`,
+            howFixed: parsed.howFixed || `Applied automated refactoring and fixes to ${targetFile}`,
+            fixedCode,
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to generate code fix via AI: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function identifyTargetFiles(userPrompt, projectName, filesList, language, native) {
+    const prompt = `You are Scout, an AI Principal Software Engineer.
+Project: "${projectName}"
+User Request: "${userPrompt}"
+
+File Tree Overview:
+${filesList.slice(0, 150).join('\n')}
+
+Based on the user request, identify which specific file path(s) from the file tree list above need to be modified.
+Select ONLY the file(s) that strictly need modifications to fulfill the request. Unless the request explicitly asks to modify all files, prefer selecting only the single file or minimal set of files directly relevant.
+Return ONLY a JSON object matching this exact schema:
+{
+ "targetFiles": ["relative/file/path1.ts", "relative/file/path2.html"]
+}
+`;
+    try {
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+            response_format: { type: 'json_object' },
+            max_tokens: 500,
+        }));
+        const parsed = JSON.parse(response.choices[0]?.message?.content || '{}');
+        if (Array.isArray(parsed.targetFiles)) {
+            return parsed.targetFiles.filter((f) => typeof f === 'string' && filesList.includes(f));
+        }
+    }
+    catch { }
+    return [];
+}
+export async function generateMultiCodeFix(userPrompt, projectName, filesList, targetFilesMap, language, native, onProgress) {
+    const langInfo = getLanguageInstruction(language, native);
+    const filePaths = Object.keys(targetFilesMap);
+    if (filePaths.length === 1) {
+        const singleFile = filePaths[0];
+        const singleContent = targetFilesMap[singleFile];
+        if (onProgress) {
+            onProgress(0, 1, singleFile);
+        }
+        const res = await generateCodeFix(userPrompt, projectName, filesList, singleFile, singleContent, language, native);
+        if (onProgress) {
+            onProgress(1, 1, singleFile);
+        }
+        return {
+            problem: res.problem,
+            howFixed: res.howFixed,
+            files: [{ targetFile: res.targetFile, problem: res.problem, howFixed: res.howFixed, fixedCode: res.fixedCode }],
+        };
+    }
+    let combinedFilesPrompt = '';
+    let totalLength = 0;
+    for (const f of filePaths) {
+        const content = targetFilesMap[f] || '';
+        totalLength += content.length;
+        combinedFilesPrompt += `\n--- File: "${f}" ---\n\`\`\`\n${content.slice(0, 8000)}\n\`\`\`\n`;
+    }
+    if (totalLength < 25000 && filePaths.length <= 10) {
+        const prompt = `You are Scout, an expert AI Principal Software Engineer & Code Auto-Fixer.
+
+Project Name: "${projectName}"
+User Request / Prompt: "${userPrompt}"
+Target Files to Fix (${filePaths.length} files): ${filePaths.join(', ')}
+
+File Tree Overview:
+${filesList.slice(0, 50).join('\n')}
+
+Contents of Target Files:
+${combinedFilesPrompt}
+
+Language for explanations requirement: ${langInfo.instruction} Write "problem" and "howFixed" explanations in ${langInfo.displayName}.
+
+Your mission:
+1. Analyze ALL target files and the user prompt.
+2. Provide updated, complete production-ready code for EACH target file according to the user request. Do NOT omit existing logic unless refactoring or fulfilling the prompt.
+3. Return a JSON object matching this exact schema:
+{
+ "problem": "Clear technical breakdown of what the issue was across these files written in ${langInfo.displayName}",
+ "howFixed": "Technical explanation of how Scout fixed all target files written in ${langInfo.displayName}",
+ "files": [
+ {
+ "targetFile": "relative/file/path",
+ "fixedCode": "complete updated source code string for this file"
+ }
+ ]
+}
+`;
+        try {
+            const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+                model,
+                messages: [{ role: 'user', content: prompt }],
+                response_format: { type: 'json_object' },
+                max_tokens: 4000,
+            }));
+            const parsed = JSON.parse(response.choices[0]?.message?.content || '{}');
+            const files = [];
+            if (Array.isArray(parsed.files)) {
+                for (const item of parsed.files) {
+                    if (item && typeof item.targetFile === 'string' && typeof item.fixedCode === 'string') {
+                        let code = item.fixedCode;
+                        if (code.trim().startsWith('```')) {
+                            code = code.trim().replace(/^```[a-zA-Z0-9_\-]*\r?\n?/, '').replace(/\r?\n?```\s*$/, '').trim();
+                        }
+                        files.push({
+                            targetFile: item.targetFile,
+                            fixedCode: code,
+                        });
+                    }
+                }
+            }
+            if (files.length === filePaths.length) {
+                return {
+                    problem: parsed.problem || `Issue identified across ${filePaths.length} files for prompt: "${userPrompt}"`,
+                    howFixed: parsed.howFixed || `Applied automated fixes to ${filePaths.length} files.`,
+                    files,
+                };
+            }
+        }
+        catch { }
+    }
+    let completedCount = 0;
+    const CONCURRENCY_LIMIT = 2;
+    const results = await mapWithConcurrency(filePaths, CONCURRENCY_LIMIT, async (f) => {
+        const content = targetFilesMap[f] || '';
+        if (onProgress) {
+            onProgress(completedCount, filePaths.length, f);
+        }
+        let resItem;
+        try {
+            const singleRes = await generateCodeFix(userPrompt, projectName, filesList, f, content, language, native);
+            resItem = {
+                targetFile: f,
+                problem: singleRes.problem,
+                howFixed: singleRes.howFixed,
+                fixedCode: singleRes.fixedCode,
+            };
+        }
+        catch (err) {
+            resItem = {
+                targetFile: f,
+                fixedCode: content,
+            };
+        }
+        completedCount++;
+        if (onProgress) {
+            onProgress(completedCount, filePaths.length, f);
+        }
+        return resItem;
+    });
+    return {
+        problem: `Issue identified across ${filePaths.length} files matching prompt: "${userPrompt}"`,
+        howFixed: `Updated ${filePaths.length} files to resolve user request.`,
+        files: results,
+    };
+}
+export async function generateCodeFile(filePath, userPrompt, projectName, filesList, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
+    const prompt = `You are Scout, an expert AI Software Architect & Code Generator.
+
+Project Name: "${projectName}"
+Target File to Create: "${filePath}"
+User Instructions / Prompt: "${userPrompt}"
+
+File Tree Context:
+${filesList.slice(0, 80).join('\n')}
+
+Language requirement: ${langInfo.instruction} Write the "description" explanation in ${langInfo.displayName}.
+
+Your mission:
+1. Generate complete, clean, highly professional, modular, and production-ready source code for "${filePath}".
+2. Maintain strict code elegance: modern language standards, proper syntax, clear variable/function names, explicit types (if TypeScript) or docstrings, defensive null checks, robust error handling, clean formatting, and industry best practices.
+3. Provide a clear description of what this code does.
+
+Return ONLY a JSON object matching this exact schema:
+{
+ "targetFile": "${filePath}",
+ "description": "Clear description of the generated code and its capabilities written in ${langInfo.displayName}",
+ "code": "complete source code string for ${filePath}"
+}
+`;
+    try {
+        const response = await callOpenAIWithRetry(async (model) => {
+            try {
+                return await openai.chat.completions.create({
+                    model,
+                    messages: [{ role: 'user', content: prompt }],
+                    response_format: { type: 'json_object' },
+                    max_tokens: 3500,
+                });
+            }
+            catch {
+                return await openai.chat.completions.create({
+                    model,
+                    messages: [{ role: 'user', content: prompt }],
+                    max_tokens: 3500,
+                });
+            }
+        });
+        const rawContent = response.choices[0]?.message?.content || '{}';
+        const parsed = cleanAndParseJsonPayload(rawContent);
+        let code = typeof parsed.code === 'string' && parsed.code.trim().length > 0
+            ? parsed.code
+            : typeof parsed.fixedCode === 'string' && parsed.fixedCode.trim().length > 0
+                ? parsed.fixedCode
+                : typeof parsed.content === 'string' && parsed.content.trim().length > 0
+                    ? parsed.content
+                    : typeof parsed.source === 'string' && parsed.source.trim().length > 0
+                        ? parsed.source
+                        : typeof parsed.codeContent === 'string' && parsed.codeContent.trim().length > 0
+                            ? parsed.codeContent
+                            : typeof parsed.fileContent === 'string' && parsed.fileContent.trim().length > 0
+                                ? parsed.fileContent
+                                : typeof parsed.fixed_code === 'string' && parsed.fixed_code.trim().length > 0
+                                    ? parsed.fixed_code
+                                    : typeof parsed.snippet === 'string' && parsed.snippet.trim().length > 0
+                                        ? parsed.snippet
+                                        : typeof parsed.code_snippet === 'string' && parsed.code_snippet.trim().length > 0
+                                            ? parsed.code_snippet
+                                            : typeof parsed.python === 'string' && parsed.python.trim().length > 0
+                                                ? parsed.python
+                                                : typeof parsed.py === 'string' && parsed.py.trim().length > 0
+                                                    ? parsed.py
+                                                    : typeof parsed.solution === 'string' && parsed.solution.trim().length > 0
+                                                        ? parsed.solution
+                                                        : extractCodeFromRawResponse(rawContent) ||
+                                                            (rawContent && !rawContent.trim().startsWith('{') ? rawContent.trim() : '');
+        if (!code && parsed && typeof parsed === 'object') {
+            for (const val of Object.values(parsed)) {
+                if (typeof val === 'string' &&
+                    val.trim().length > 15 &&
+                    (val.includes('\n') || val.includes('def ') || val.includes('function') || val.includes('import') || val.includes('class'))) {
+                    code = val.trim();
+                    break;
+                }
+            }
+        }
+        code = code.trim();
+        if (code.startsWith('```')) {
+            code = code.replace(/^```[a-zA-Z0-9_\-]*\r?\n?/, '').replace(/\r?\n?```\s*$/, '').trim();
+        }
+        return {
+            targetFile: parsed.targetFile || filePath,
+            description: parsed.description || `Generated code for ${filePath}`,
+            code,
+        };
+    }
+    catch (error) {
+        console.error("OpenAI Code Generation Error:", error);
+        throw new Error(`Failed to generate code file via AI: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function analyzeCommandError(command, exitCode, output, projectName, filesList, language, native) {
+    const langInfo = getLanguageInstruction(language, native);
+    const prompt = `You are Scout, an expert AI Systems & Build Engineer diagnosing a command failure.
+
+Project: "${projectName}"
+Executed Command: \`${command}\`
+Exit Code: ${exitCode}
+
+File Tree Overview:
+${filesList.slice(0, 80).join('\n')}
+
+Command Output / Failure Logs:
+\`\`\`
+${output.slice(0, 8000)}
+\`\`\`
+
+Language requirement: ${langInfo.instruction} Write "rootCause" and "suggestedFix" in ${langInfo.displayName}.
+
+Diagnose why the command failed and identify which source file in the project likely needs to be fixed.
+
+Return ONLY a JSON object matching this exact schema:
+{
+ "command": "${command}",
+ "exitCode": ${exitCode},
+ "rootCause": "Clear explanation of why the command failed written in ${langInfo.displayName}",
+ "suggestedFix": "Concrete suggestion on how to resolve the failure written in ${langInfo.displayName}",
+ "targetFileToFix": "relative path to the source file that caused the failure, or empty string if unknown"
+}
+`;
+    try {
+        const response = await callOpenAIWithRetry((model) => openai.chat.completions.create({
+            model,
+            messages: [{ role: 'user', content: prompt }],
+            response_format: { type: 'json_object' },
+        }));
+        const parsed = JSON.parse(response.choices[0]?.message?.content || '{}');
+        return {
+            command,
+            exitCode,
+            rootCause: parsed.rootCause || 'Command process returned a non-zero exit status.',
+            suggestedFix: parsed.suggestedFix || 'Check output logs for syntax or runtime errors.',
+            targetFileToFix: parsed.targetFileToFix || undefined,
+        };
+    }
+    catch (error) {
         return {
-            summary: `🚀 ${projectName} Architecture Teardown: A high-performance, modular system engineered for rapid execution and developer agility. Built on top of a modern runtime stack, it features decoupled command routing, intelligent static analysis, and automated developer productivity tooling designed to scale.`,
-            entryPoint: filesList.find(f => f.includes('index') || f.includes('main') || f.includes('app')) || 'src/index.ts',
-            readOrder: [
-                'package.json -> Core manifest defining build targets, execution binaries, and dependency graph',
-                'src/index.ts -> Primary router establishing CLI hooks, subcommand registration, and execution workflow',
-                'src/engine/llm.ts -> Core AI engine managing prompt orchestration and LLM proxy synthesis'
-            ],
-            painPoints: [
-                '⚡ AI Gateway Orchestration: Ensure API keys or FrontTerrain Proxy authentication headers are active for live AI synthesis.',
-                '⚡ Asynchronous Git Churn Analysis: High-volume repository scanning requires optimized commit log batching for large-scale codebases.',
-                '⚡ Module Resolution & ESM Boundaries: Strict TypeScript transpilation requires precise extension matching across ESM module dependencies.'
-            ],
+            command,
+            exitCode,
+            rootCause: `Command failed with code ${exitCode}. AI diagnosis error: ${error instanceof Error ? error.message : String(error)}`,
+            suggestedFix: 'Inspect terminal output above for missing packages or compiler errors.',
         };
     }
 }