kiku-agent 1.3.2 → 1.3.3

package/server/agent/config.js

@@ -1,690 +1,1088 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { PROVIDER_KEYS_FILE, SETTINGS_FILE } from './appPaths.js';
-
-const PROVIDER_MODEL_ALIASES = {
-  lmstudio: {
-    'q8': 'google/gemma-4-e4b-Q8_0',
-    'q8_0': 'google/gemma-4-e4b-Q8_0',
-    'q8-0': 'google/gemma-4-e4b-Q8_0',
-    '8bit': 'google/gemma-4-e4b-Q8_0',
-    '8-bit': 'google/gemma-4-e4b-Q8_0',
-    'gemma-q8': 'google/gemma-4-e4b-Q8_0',
-    'gemma-q8_0': 'google/gemma-4-e4b-Q8_0',
-    'gemma-4-e4b-q8': 'google/gemma-4-e4b-Q8_0',
-    'gemma-4-e4b-q8_0': 'google/gemma-4-e4b-Q8_0',
-    'google/gemma-4-e4b-q8_0': 'google/gemma-4-e4b-Q8_0',
-    'google/gemma-4-e4b-q8': 'google/gemma-4-e4b-Q8_0',
-
-    'q6': 'google/gemma-4-e4b-Q6_K',
-    'q6_k': 'google/gemma-4-e4b-Q6_K',
-    'q6-k': 'google/gemma-4-e4b-Q6_K',
-    '6bit': 'google/gemma-4-e4b-Q6_K',
-    '6-bit': 'google/gemma-4-e4b-Q6_K',
-    'gemma-q6': 'google/gemma-4-e4b-Q6_K',
-    'gemma-q6_k': 'google/gemma-4-e4b-Q6_K',
-    'gemma-4-e4b-q6': 'google/gemma-4-e4b-Q6_K',
-    'gemma-4-e4b-q6_k': 'google/gemma-4-e4b-Q6_K',
-    'google/gemma-4-e4b-q6_k': 'google/gemma-4-e4b-Q6_K',
-    'google/gemma-4-e4b-q6': 'google/gemma-4-e4b-Q6_K',
-
-    'q4': 'google/gemma-4-e4b-Q4_K_M',
-    'q4_k': 'google/gemma-4-e4b-Q4_K_M',
-    'q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
-    'q4-k-m': 'google/gemma-4-e4b-Q4_K_M',
-    '4bit': 'google/gemma-4-e4b-Q4_K_M',
-    '4-bit': 'google/gemma-4-e4b-Q4_K_M',
-    'gemma-q4': 'google/gemma-4-e4b-Q4_K_M',
-    'gemma-q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
-    'gemma-4-e4b-q4': 'google/gemma-4-e4b-Q4_K_M',
-    'gemma-4-e4b-q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
-    'google/gemma-4-e4b-q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
-    'google/gemma-4-e4b-q4': 'google/gemma-4-e4b-Q4_K_M',
-
-    'gemma': 'google/gemma-4-e4b',
-    'gemma4': 'google/gemma-4-e4b',
-    'gemma-4': 'google/gemma-4-e4b',
-    'gemma-4-e4b': 'google/gemma-4-e4b',
-  },
-  vllm: {
-    'gemma': 'google/gemma-4-e4b',
-    'gemma4': 'google/gemma-4-e4b',
-    'gemma-4': 'google/gemma-4-e4b',
-    'gemma-4-e4b': 'google/gemma-4-e4b',
-    'qwen': 'Qwen/Qwen2.5-7B-Instruct',
-    'llama': 'meta-llama/Llama-3.1-8B-Instruct',
-  },
-  openai: {
-    'o1-mini': 'gpt-5.6-luna',
-    'o3-mini': 'gpt-5.6-luna',
-  },
-  openrouter: {
-    auto: 'openrouter/auto',
-  },
-  groq: {
-    'gpt-oss-120b': 'openai/gpt-oss-120b',
-    'gpt-oss-20b': 'openai/gpt-oss-20b',
-  },
-  deepseek: {
-    'deepseek-chat': 'deepseek-v4-flash',
-    'deepseek-reasoner': 'deepseek-v4-flash',
-  },
-  gemini: {
-    'gemini-3.1-pro': 'gemini-3.1-pro-preview',
-  },
-};
-
-const GENERIC_MODEL_TOKENS = new Set(['model', 'chat', 'default', 'base', 'instruct', 'text', 'embedding']);
-
-export function extractModelQuantization(modelId) {
-  if (!modelId || typeof modelId !== 'string') return null;
-  const clean = modelId.toUpperCase();
-  const m = clean.match(/(Q[0-9]+_[A-Z0-9_]+|Q[0-9]+_[A-Z]|Q[0-9]+|[0-9]+BIT|FP16|FP32|BF16)/i);
-  return m ? m[1].toUpperCase() : null;
-}
-
-export function cleanModelName(modelId) {
-  if (!modelId || typeof modelId !== 'string') return '';
-  let name = modelId.trim();
-  name = name.replace(/\.(gguf|bin|safetensors)$/i, '');
-  if (name.includes('/')) {
-    const parts = name.split('/').filter(Boolean);
-    name = parts[parts.length - 1] || parts[0];
-  }
-  return name.toLowerCase().replace(/[^a-z0-9_-]/g, '');
-}
-
-export function matchModelIdentifier(target, candidate) {
-  if (!target || !candidate) return false;
-  if (target === candidate) return true;
-
-  const targetLower = String(target).toLowerCase().trim();
-  const candLower = String(candidate).toLowerCase().trim();
-  if (targetLower === candLower) return true;
-
-  const targetClean = cleanModelName(target);
-  const candClean = cleanModelName(candidate);
-  if (targetClean && candClean && targetClean === candClean) return true;
-
-  const targetQuant = extractModelQuantization(target);
-  const candQuant = extractModelQuantization(candidate);
-
-  const targetIsGemma = /gemma/i.test(target);
-  const candIsGemma = /gemma/i.test(candidate);
-
-  if (candIsGemma) {
-    if (targetIsGemma) {
-      if (targetQuant && candQuant) {
-        const normTargetQ = targetQuant.replace(/[^A-Z0-9]/g, '');
-        const normCandQ = candQuant.replace(/[^A-Z0-9]/g, '');
-        if (normTargetQ === normCandQ || normCandQ.startsWith(normTargetQ) || normTargetQ.startsWith(normCandQ)) {
-          return true;
-        }
-      } else if (!targetQuant) {
-        if (targetClean.includes('gemma') && candClean.includes('gemma')) {
-          return true;
-        }
-      }
-    } else if (targetQuant && !GENERIC_MODEL_TOKENS.has(targetClean)) {
-      if (candQuant) {
-        const normTargetQ = targetQuant.replace(/[^A-Z0-9]/g, '');
-        const normCandQ = candQuant.replace(/[^A-Z0-9]/g, '');
-        if (normTargetQ === normCandQ || normCandQ.startsWith(normTargetQ) || normTargetQ.startsWith(normCandQ)) {
-          return true;
-        }
-      }
-    }
-  }
-
-  if (targetClean && candClean && !GENERIC_MODEL_TOKENS.has(targetClean) && targetClean.length >= 5) {
-    if (candClean.includes(targetClean) || (candClean.length >= 5 && targetClean.includes(candClean))) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-export function normalizeProviderModel(providerId, modelId) {
-  const normalizedProvider = String(providerId || '').toLowerCase().trim();
-  const normalizedModel = String(modelId || '').trim();
-  const aliasMatch = PROVIDER_MODEL_ALIASES[normalizedProvider]?.[normalizedModel.toLowerCase()]
-    || PROVIDER_MODEL_ALIASES[normalizedProvider]?.[normalizedModel];
-  return aliasMatch || normalizedModel;
-}
-
-export const DEFAULT_LOCAL_ENDPOINTS = Object.freeze({
-  lmstudio: 'http://127.0.0.1:1234/v1',
-  vllm: 'http://127.0.0.1:8000/v1',
-});
-
-export const CLOUD_PROVIDERS = {
-  lmstudio: {
-    id: 'lmstudio',
-    name: 'LM Studio (Local)',
-    baseUrl: process.env.LMSTUDIO_BASE_URL || process.env.OPENAI_BASE_URL || 'http://127.0.0.1:1234/v1',
-    apiKey: process.env.LMSTUDIO_API_KEY || 'lm-studio',
-    defaultModel: 'google/gemma-4-e4b',
-    isLocal: true,
-    envKey: 'LMSTUDIO_BASE_URL',
-    docUrl: 'https://lmstudio.ai/docs',
-    apiRefUrl: 'https://lmstudio.ai/docs/api/local-server',
-    pricingSummary: '100% Free / Local (No API Key required)',
-    features: ['local', 'private', 'offline', 'zero-cost', 'openai-compatible'],
-    recommendedModels: [
-      { id: 'google/gemma-4-e4b', name: 'Gemma 4 e4b (Default / Q4_K_M)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: 'Recommended default. Balanced 4-bit quantization (Q4_K_M) — fastest inference and lowest RAM usage.' },
-      { id: 'google/gemma-4-e4b-Q4_K_M', name: 'Gemma 4 e4b (Q4_K_M Quant)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: '4-bit medium quantization (Q4_K_M) optimized for speed and low memory footprint (~2.5GB RAM).' },
-      { id: 'google/gemma-4-e4b-Q6_K', name: 'Gemma 4 e4b (Q6_K Quant)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: '6-bit quantization (Q6_K) offering higher precision and near-original fidelity (~3.5GB RAM).' },
-      { id: 'google/gemma-4-e4b-Q8_0', name: 'Gemma 4 e4b (Q8_0 Quant)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: '8-bit full quantization (Q8_0) for maximum accuracy and reasoning precision (~4.5GB RAM).' },
-    ],
-  },
-  vllm: {
-    id: 'vllm',
-    name: 'vLLM (Local / WSL)',
-    baseUrl: process.env.VLLM_BASE_URL || 'http://127.0.0.1:8000/v1',
-    apiKey: process.env.VLLM_API_KEY || 'token-kiku',
-    defaultModel: process.env.VLLM_MODEL || 'google/gemma-4-e4b',
-    isLocal: true,
-    envKey: 'VLLM_BASE_URL',
-    docUrl: 'https://docs.vllm.ai',
-    apiRefUrl: 'https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html',
-    pricingSummary: '100% Free / Local (High-throughput PagedAttention server via WSL/Linux)',
-    features: ['local', 'high-throughput', 'paged-attention', 'wsl-required', 'openai-compatible'],
-    platformNotice: 'You cannot install vLLM natively on Windows. Please install and run vLLM via WSL (Windows Subsystem for Linux, e.g. wsl -d kali-linux or Ubuntu) using "vllm serve <model> --port 8000".',
-    recommendedModels: [
-      { id: 'google/gemma-4-e4b', name: 'Gemma 4 e4b (Default)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: 'Recommended default model served via vllm serve on port 8000.' },
-      { id: 'Qwen/Qwen2.5-7B-Instruct', name: 'Qwen 2.5 7B Instruct', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'High capability open model with function calling on vLLM.' },
-      { id: 'meta-llama/Llama-3.1-8B-Instruct', name: 'Llama 3.1 8B Instruct', tier: 'free', cost: '$0.00 (Local)', context: '128k', hasTools: true, description: 'Fast general-purpose open model hosted on vLLM.' },
-    ],
-  },
-  openai: {
-    id: 'openai',
-    name: 'OpenAI Cloud',
-    baseUrl: process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
-    apiKey: process.env.OPENAI_API_KEY || '',
-    defaultModel: normalizeProviderModel('openai', process.env.OPENAI_MODEL || 'gpt-5.6-luna'),
-    isLocal: false,
-    envKey: 'OPENAI_API_KEY',
-    docUrl: 'https://developers.openai.com/api/docs/models',
-    apiRefUrl: 'https://developers.openai.com/api/reference',
-    pricingSummary: 'GPT-5.6 Luna: $0.20/1M in, $1.20/1M out; Terra/Sol available for higher capability',
-    features: ['tools', 'streaming', 'vision', 'reasoning', 'system-prompt'],
-    recommendedModels: [
-      { id: 'gpt-5.6-luna', name: 'GPT-5.6 Luna', tier: 'cost-sensitive', cost: '$0.20 / 1M in', context: '1.05M', hasTools: true, description: 'Recommended default for efficient, high-volume multilingual agent workloads.' },
-      { id: 'gpt-5.6-terra', name: 'GPT-5.6 Terra', tier: 'balanced', cost: '$2.00 / 1M in', context: '1.05M', hasTools: true, description: 'Balances intelligence and cost for production reasoning and tool use.' },
-      { id: 'gpt-5.6-sol', name: 'GPT-5.6 Sol', tier: 'flagship', cost: '$4.00 / 1M in', context: '1.05M', hasTools: true, description: 'Flagship model for complex professional reasoning and coding.' },
-    ],
-  },
-  openrouter: {
-    id: 'openrouter',
-    name: 'OpenRouter Cloud',
-    baseUrl: process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1',
-    apiKey: process.env.OPENROUTER_API_KEY || '',
-    defaultModel: normalizeProviderModel('openrouter', process.env.OPENROUTER_MODEL || 'openrouter/auto'),
-    extraHeaders: {
-      'HTTP-Referer': 'https://jujingyi-kikuuu.vercel.app/',
-      'X-OpenRouter-Title': 'Kiku Agent',
-    },
-    isLocal: false,
-    envKey: 'OPENROUTER_API_KEY',
-    docUrl: 'https://openrouter.ai/docs/guides/routing/routers/auto-router',
-    apiRefUrl: 'https://openrouter.ai/docs/api/reference/overview',
-    pricingSummary: 'Auto Router selects a current model dynamically; usage is billed at the routed model rate',
-    features: ['universal-routing', 'tools', 'streaming', 'free-tier', 'fallback'],
-    recommendedModels: [
-      { id: 'openrouter/auto', name: 'OpenRouter Auto Router', tier: 'dynamic', cost: 'Routed model rate', context: 'Model-dependent', hasTools: true, description: 'Recommended default. Chooses from the current catalog so a retired third-party model does not break startup.' },
-    ],
-  },
-  groq: {
-    id: 'groq',
-    name: 'Groq Cloud',
-    baseUrl: process.env.GROQ_BASE_URL || 'https://api.groq.com/openai/v1',
-    apiKey: process.env.GROQ_API_KEY || '',
-    defaultModel: normalizeProviderModel('groq', process.env.GROQ_MODEL || 'openai/gpt-oss-120b'),
-    isLocal: false,
-    envKey: 'GROQ_API_KEY',
-    docUrl: 'https://console.groq.com/docs/quickstart',
-    apiRefUrl: 'https://console.groq.com/docs/api-reference',
-    pricingSummary: 'Ultra-fast LPU inference (GPT-OSS 20B: $0.075/1M in, GPT-OSS 120B: $0.15/1M in)',
-    features: ['lpu-speed', 'tools', 'streaming', 'openai-compatible'],
-    recommendedModels: [
-      { id: 'openai/gpt-oss-120b', name: 'GPT-OSS 120B', tier: 'flagship', cost: '$0.15 / 1M in', context: '131k', hasTools: true, description: 'Recommended default. Production-grade 120B reasoning model with tool use on Groq.' },
-      { id: 'openai/gpt-oss-20b', name: 'GPT-OSS 20B', tier: 'ultra-cheap', cost: '$0.075 / 1M in', context: '131k', hasTools: true, description: 'Fast production model for lower-cost, high-volume requests.' },
-    ],
-  },
-  deepseek: {
-    id: 'deepseek',
-    name: 'DeepSeek Cloud',
-    baseUrl: process.env.DEEPSEEK_BASE_URL || 'https://api.deepseek.com',
-    apiKey: process.env.DEEPSEEK_API_KEY || '',
-    defaultModel: normalizeProviderModel('deepseek', process.env.DEEPSEEK_MODEL || 'deepseek-v4-flash'),
-    isLocal: false,
-    envKey: 'DEEPSEEK_API_KEY',
-    docUrl: 'https://api-docs.deepseek.com',
-    apiRefUrl: 'https://api-docs.deepseek.com/api/create-chat-completion',
-    pricingSummary: 'V4 Flash: $0.22-$0.44/1M uncached input; V4 Pro: $0.66-$1.32/1M (off-peak/peak)',
-    features: ['deepseek-v4', 'thinking', 'tools', 'streaming', 'context-cache', '1m-context'],
-    recommendedModels: [
-      { id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash', tier: 'balanced', cost: '$0.22-$0.44 / 1M uncached in', context: '1M', hasTools: true, description: 'Recommended default. Current V4 model with tool calls and thinking/non-thinking modes.' },
-      { id: 'deepseek-v4-pro', name: 'DeepSeek V4 Pro', tier: 'flagship', cost: '$0.66-$1.32 / 1M uncached in', context: '1M', hasTools: true, description: 'Higher-capability V4 model with tool calls and thinking mode.' },
-    ],
-  },
-  gemini: {
-    id: 'gemini',
-    name: 'Google Gemini',
-    baseUrl: process.env.GEMINI_BASE_URL || 'https://generativelanguage.googleapis.com/v1beta/openai',
-    apiKey: process.env.GEMINI_API_KEY || '',
-    defaultModel: normalizeProviderModel('gemini', process.env.GEMINI_MODEL || 'gemini-3.7-flash'),
-    isLocal: false,
-    envKey: 'GEMINI_API_KEY',
-    docUrl: 'https://ai.google.dev/gemini-api/docs',
-    apiRefUrl: 'https://ai.google.dev/api/generate-content',
-    pricingSummary: 'Gemini 3.7 Flash: free tier available; paid standard $0.75/1M input through 2026',
-    features: ['1m-context', 'multimodal', 'tools', 'streaming', 'thinking'],
-    recommendedModels: [
-      { id: 'gemini-3.7-flash', name: 'Gemini 3.7 Flash', tier: 'latest-stable', cost: '$0.75 / 1M in (2026)', context: '1M', hasTools: true, description: 'Recommended default. Latest stable Flash model for agentic workflows and multimodal reasoning.' },
-      { id: 'gemini-3.5-flash-lite', name: 'Gemini 3.5 Flash-Lite', tier: 'lowest-cost', cost: '$0.30 / 1M in', context: '1M', hasTools: true, description: 'Stable, cost-efficient model for high-volume translation and simple processing.' },
-      { id: 'gemini-3.6-flash', name: 'Gemini 3.6 Flash', tier: 'stable', cost: '$0.75 / 1M in (2026)', context: '1M', hasTools: true, description: 'Stable previous-generation Flash fallback with function calling and thinking.' },
-    ],
-  },
-  custom: {
-    id: 'custom',
-    name: 'Custom OpenAI-Compatible',
-    baseUrl: process.env.LLM_BASE_URL || '',
-    apiKey: process.env.LLM_API_KEY || '',
-    defaultModel: process.env.LLM_MODEL || 'default',
-    isLocal: false,
-    envKey: 'LLM_BASE_URL',
-    docUrl: 'https://platform.openai.com/docs/api-reference',
-    apiRefUrl: 'https://platform.openai.com/docs/api-reference/chat',
-    pricingSummary: 'Self-hosted or Custom Gateway',
-    features: ['custom-endpoint', 'openai-compatible', 'tools', 'streaming'],
-    recommendedModels: [
-      { id: 'default', name: 'Default Model', tier: 'custom', cost: 'Custom', context: 'Custom', hasTools: true, description: 'Custom model specified via LLM_MODEL or /model use <id>.' },
-    ],
-  },
-};
-
-let cachedSettings = null;
-let lastSettingsLoadTime = 0;
-const SETTINGS_CACHE_TTL_MS = 2000;
-
-export function invalidateSettingsCache() {
-  cachedSettings = null;
-  lastSettingsLoadTime = 0;
-}
-
-export function loadPersistedSettings(force = false) {
-  const now = Date.now();
-  if (!force && cachedSettings && (now - lastSettingsLoadTime < SETTINGS_CACHE_TTL_MS)) {
-    return cachedSettings;
-  }
-  try {
-    if (fs.existsSync(SETTINGS_FILE)) {
-      const data = fs.readFileSync(SETTINGS_FILE, 'utf-8');
-      const parsed = JSON.parse(data);
-      if (parsed && typeof parsed === 'object') {
-        if (parsed.providerModels && typeof parsed.providerModels === 'object') {
-          for (const [pId, model] of Object.entries(parsed.providerModels)) {
-            const providerDef = CLOUD_PROVIDERS[pId.toLowerCase()];
-            if (providerDef && typeof model === 'string' && model.trim()) {
-              providerDef.defaultModel = model.trim();
-            }
-          }
-        }
-        if (parsed.providerBaseUrls && typeof parsed.providerBaseUrls === 'object') {
-          for (const [pId, url] of Object.entries(parsed.providerBaseUrls)) {
-            const providerDef = CLOUD_PROVIDERS[pId.toLowerCase()];
-            if (providerDef && typeof url === 'string' && url.trim()) {
-              providerDef.baseUrl = url.trim().replace(/\/+$/, '');
-            }
-          }
-        }
-        cachedSettings = parsed;
-        lastSettingsLoadTime = now;
-        return parsed;
-      }
-    }
-  } catch {}
-  cachedSettings = {};
-  lastSettingsLoadTime = now;
-  return {};
-}
-
-export function getProviderBaseUrl(providerId) {
-  const pId = String(providerId || '').toLowerCase().trim();
-  const settings = loadPersistedSettings();
-  if (settings.providerBaseUrls && typeof settings.providerBaseUrls[pId] === 'string' && settings.providerBaseUrls[pId].trim()) {
-    return settings.providerBaseUrls[pId].trim().replace(/\/+$/, '');
-  }
-  const providerDef = CLOUD_PROVIDERS[pId];
-  if (providerDef) {
-    if (providerDef.envKey && process.env[providerDef.envKey]) {
-      return process.env[providerDef.envKey].trim().replace(/\/+$/, '');
-    }
-    if (pId === 'lmstudio' && process.env.OPENAI_BASE_URL) {
-      return process.env.OPENAI_BASE_URL.trim().replace(/\/+$/, '');
-    }
-    if (DEFAULT_LOCAL_ENDPOINTS[pId]) {
-      return DEFAULT_LOCAL_ENDPOINTS[pId];
-    }
-    if (providerDef.baseUrl) {
-      return providerDef.baseUrl.trim().replace(/\/+$/, '');
-    }
-  }
-  return DEFAULT_LOCAL_ENDPOINTS.lmstudio;
-}
-
-export function savePersistedProviderBaseUrl(providerId, baseUrl) {
-  const pId = String(providerId || '').toLowerCase().trim();
-  const cleanUrl = String(baseUrl || '').trim().replace(/\/+$/, '');
-  if (!CLOUD_PROVIDERS[pId] || !cleanUrl) return cleanUrl;
-
-  const settings = loadPersistedSettings();
-  if (!settings.providerBaseUrls) settings.providerBaseUrls = {};
-  settings.providerBaseUrls[pId] = cleanUrl;
-  if (CLOUD_PROVIDERS[pId]) {
-    CLOUD_PROVIDERS[pId].baseUrl = cleanUrl;
-  }
-  if (config.activeProvider === pId && config.lmStudio) {
-    config.lmStudio.baseUrl = cleanUrl;
-  }
-
-  try {
-    const dir = path.dirname(SETTINGS_FILE);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), { encoding: 'utf-8', mode: 0o600 });
-    invalidateSettingsCache();
-  } catch (err) {
-    console.error(`Failed to save baseUrl to ${SETTINGS_FILE}:`, err.message);
-  }
-  return cleanUrl;
-}
-
-export function getPersistedActiveProvider() {
-  const settings = loadPersistedSettings();
-  if (settings.activeProvider && CLOUD_PROVIDERS[settings.activeProvider.toLowerCase()]) {
-    return settings.activeProvider.toLowerCase();
-  }
-  return null;
-}
-
-export function savePersistedActiveProvider(providerId, model = null, baseUrl = null) {
-  const pId = String(providerId || '').toLowerCase().trim();
-  if (!CLOUD_PROVIDERS[pId]) return;
-
-  const settings = loadPersistedSettings();
-  settings.activeProvider = pId;
-  if (!settings.providerModels) settings.providerModels = {};
-  if (!settings.providerBaseUrls) settings.providerBaseUrls = {};
-
-  if (model) {
-    const cleanModel = String(model).trim();
-    settings.providerModels[pId] = cleanModel;
-    settings.activeModel = cleanModel;
-    if (CLOUD_PROVIDERS[pId]) CLOUD_PROVIDERS[pId].defaultModel = cleanModel;
-  }
-
-  if (baseUrl) {
-    const cleanUrl = String(baseUrl).trim().replace(/\/+$/, '');
-    settings.providerBaseUrls[pId] = cleanUrl;
-    if (CLOUD_PROVIDERS[pId]) CLOUD_PROVIDERS[pId].baseUrl = cleanUrl;
-  }
-
-  try {
-    const dir = path.dirname(SETTINGS_FILE);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), { encoding: 'utf-8', mode: 0o600 });
-    invalidateSettingsCache();
-  } catch (err) {
-    console.error(`Failed to save settings to ${SETTINGS_FILE}:`, err.message);
-  }
-}
-
-export function setActiveProvider(providerId, { model = null, baseUrl = null } = {}) {
-  const pId = String(providerId || '').toLowerCase().trim();
-  if (!CLOUD_PROVIDERS[pId]) {
-    throw new Error(`Unknown provider "${providerId}".`);
-  }
-  savePersistedActiveProvider(pId, model, baseUrl);
-  config.activeProvider = pId;
-  const def = CLOUD_PROVIDERS[pId];
-  if (config.lmStudio) {
-    config.lmStudio.baseUrl = def.baseUrl;
-    config.lmStudio.apiKey = def.apiKey;
-    config.lmStudio.model = def.defaultModel;
-    config.lmStudio.defaultModel = def.defaultModel;
-  }
-  return {
-    provider: pId,
-    name: def.name,
-    baseUrl: def.baseUrl,
-    model: def.defaultModel,
-    isLocal: Boolean(def.isLocal),
-    platformNotice: def.platformNotice || null,
-  };
-}
-
-export function getUnifiedProviderCatalog() {
-  const active = config.activeProvider || resolveDefaultProvider();
-  return {
-    activeProvider: active,
-    activeBaseUrl: getProviderBaseUrl(active),
-    activeModel: CLOUD_PROVIDERS[active]?.defaultModel || 'google/gemma-4-e4b',
-    localEndpoints: {
-      lmstudio: {
-        id: 'lmstudio',
-        name: CLOUD_PROVIDERS.lmstudio.name,
-        baseUrl: getProviderBaseUrl('lmstudio'),
-        defaultModel: CLOUD_PROVIDERS.lmstudio.defaultModel,
-        isActive: active === 'lmstudio',
-      },
-      vllm: {
-        id: 'vllm',
-        name: CLOUD_PROVIDERS.vllm.name,
-        baseUrl: getProviderBaseUrl('vllm'),
-        defaultModel: CLOUD_PROVIDERS.vllm.defaultModel,
-        platformNotice: CLOUD_PROVIDERS.vllm.platformNotice || null,
-        isActive: active === 'vllm',
-      }
-    },
-    providers: Object.values(CLOUD_PROVIDERS).map(p => ({
-      id: p.id,
-      name: p.name,
-      baseUrl: getProviderBaseUrl(p.id),
-      defaultModel: p.defaultModel,
-      isLocal: Boolean(p.isLocal),
-      isActive: p.id === active,
-    }))
-  };
-}
-
-export function savePersistedProviderModel(providerId, model) {
-  const pId = String(providerId || '').toLowerCase().trim();
-  const cleanModel = String(model || '').trim();
-  if (!CLOUD_PROVIDERS[pId] || !cleanModel) return;
-
-  const settings = loadPersistedSettings();
-  if (!settings.providerModels) settings.providerModels = {};
-  settings.providerModels[pId] = cleanModel;
-  if (settings.activeProvider === pId) {
-    settings.activeModel = cleanModel;
-  }
-  if (CLOUD_PROVIDERS[pId]) CLOUD_PROVIDERS[pId].defaultModel = cleanModel;
-
-  try {
-    const dir = path.dirname(SETTINGS_FILE);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), { encoding: 'utf-8', mode: 0o600 });
-    invalidateSettingsCache();
-  } catch (err) {
-    console.error(`Failed to save model to ${SETTINGS_FILE}:`, err.message);
-  }
-}
-
-export function resolveDefaultProvider() {
-  const explicit = String(process.env.LLM_PROVIDER || '').toLowerCase().trim();
-  if (explicit && CLOUD_PROVIDERS[explicit]) return explicit;
-
-  const persisted = getPersistedActiveProvider();
-  if (persisted && CLOUD_PROVIDERS[persisted]) {
-    const def = CLOUD_PROVIDERS[persisted];
-    if (def.isLocal || def.apiKey) {
-      return persisted;
-    }
-  }
-
-  if (process.env.OPENROUTER_API_KEY && !process.env.OPENROUTER_API_KEY.includes('...')) return 'openrouter';
-  if (process.env.OPENAI_API_KEY && !process.env.OPENAI_API_KEY.includes('...')) return 'openai';
-  if (process.env.GEMINI_API_KEY && !process.env.GEMINI_API_KEY.includes('...')) return 'gemini';
-  if (process.env.DEEPSEEK_API_KEY && !process.env.DEEPSEEK_API_KEY.includes('...')) return 'deepseek';
-  if (process.env.GROQ_API_KEY && !process.env.GROQ_API_KEY.includes('...')) return 'groq';
-  if (process.env.LLM_API_KEY && process.env.LLM_BASE_URL) return 'custom';
-
-  return 'lmstudio';
-}
-
-export function getProvider(id) {
-  const pId = String(id || '').toLowerCase().trim();
-  return CLOUD_PROVIDERS[pId] || null;
-}
-
-export function getProviderList() {
-  return Object.values(CLOUD_PROVIDERS);
-}
-
-export function getRecommendedModels(providerId) {
-  const provider = getProvider(providerId);
-  return provider ? (provider.recommendedModels || []) : [];
-}
-
-let persistedProviderKeys = {};
-const providerKeyEncryptionSecret = process.env.KIKU_PROVIDER_KEY_ENCRYPTION_KEY ||
-  (process.execArgv.includes('--test') ? 'kiku-agent-test-process-only-key' : '');
-
-export function isProviderKeyPersistenceEnabled() {
-  return Boolean(providerKeyEncryptionSecret);
-}
-
-function encryptProviderKeys(keys) {
-  if (!providerKeyEncryptionSecret) return null;
-  const key = crypto.createHash('sha256').update(providerKeyEncryptionSecret).digest();
-  const iv = crypto.randomBytes(12);
-  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
-  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(keys), 'utf8'), cipher.final()]);
-  return {
-    version: 1,
-    algorithm: 'aes-256-gcm',
-    iv: iv.toString('base64'),
-    tag: cipher.getAuthTag().toString('base64'),
-    ciphertext: ciphertext.toString('base64'),
-  };
-}
-
-function decryptProviderKeys(envelope) {
-  if (!providerKeyEncryptionSecret || envelope?.version !== 1 || envelope?.algorithm !== 'aes-256-gcm') return {};
-  const key = crypto.createHash('sha256').update(providerKeyEncryptionSecret).digest();
-  const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(envelope.iv, 'base64'));
-  decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
-  const plaintext = Buffer.concat([
-    decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
-    decipher.final(),
-  ]).toString('utf8');
-  const parsed = JSON.parse(plaintext);
-  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-}
-
-export function loadPersistedProviderKeys() {
-  try {
-    if (fs.existsSync(PROVIDER_KEYS_FILE)) {
-      const data = fs.readFileSync(PROVIDER_KEYS_FILE, 'utf-8');
-      const parsed = JSON.parse(data);
-      const keys = parsed?.ciphertext
-        ? decryptProviderKeys(parsed)
-        : (process.env.KIKU_ALLOW_PLAINTEXT_PROVIDER_KEYS === 'true' ? parsed : {});
-      if (keys && typeof keys === 'object') {
-        persistedProviderKeys = { ...keys };
-        for (const [pId, key] of Object.entries(keys)) {
-          const providerDef = CLOUD_PROVIDERS[pId.toLowerCase()];
-          if (providerDef && !providerDef.isLocal && !providerDef.apiKey && typeof key === 'string' && key.trim()) {
-            providerDef.apiKey = key.trim();
-          }
-        }
-        return { ...persistedProviderKeys };
-      }
-    }
-  } catch {}
-  return {};
-}
-
-export function savePersistedProviderKey(providerId, apiKey) {
-  const pId = String(providerId || '').toLowerCase().trim();
-  const providerDef = CLOUD_PROVIDERS[pId];
-  if (!providerDef) {
-    throw new Error(`Unknown provider "${providerId}".`);
-  }
-  const cleanKey = String(apiKey || '').trim();
-  providerDef.apiKey = cleanKey;
-
-  const existing = { ...persistedProviderKeys };
-
-  if (cleanKey) {
-    existing[pId] = cleanKey;
-  } else {
-    delete existing[pId];
-  }
-
-  persistedProviderKeys = existing;
-  try {
-    const envelope = encryptProviderKeys(existing);
-    if (!envelope) return { provider: pId, hasKey: Boolean(cleanKey), persisted: false };
-    const dir = path.dirname(PROVIDER_KEYS_FILE);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(PROVIDER_KEYS_FILE, JSON.stringify(envelope, null, 2), { encoding: 'utf-8', mode: 0o600 });
-  } catch (err) {
-    console.error(`Failed to save provider key to ${PROVIDER_KEYS_FILE}:`, err.message);
-  }
-
-  return { provider: pId, hasKey: Boolean(cleanKey) };
-}
-
-export function getPersistedProviderKeys() {
-  return { ...persistedProviderKeys };
-}
-
-loadPersistedSettings();
-loadPersistedProviderKeys();
-
-const defaultProviderId = resolveDefaultProvider();
-const defaultProviderConfig = CLOUD_PROVIDERS[defaultProviderId] || CLOUD_PROVIDERS.lmstudio;
-
-export const config = {
-  activeProvider: defaultProviderId,
-  providers: CLOUD_PROVIDERS,
-
-  lmStudio: {
-    baseUrl: defaultProviderConfig.baseUrl,
-    apiKey: defaultProviderConfig.apiKey,
-    model: defaultProviderConfig.defaultModel,
-    defaultModel: defaultProviderConfig.defaultModel,
-    temperature: 0.3,
-    maxTokens: 8192,
-    requestTimeoutMs: 180000,
-  },
-
-  agent: {
-    maxIterations: 6,
-    slidingWindowSize: 12,
-    language: 'auto',
-
-    autoResearch: ['on', 'off', 'auto'].includes(String(process.env.KIKU_AUTO_RESEARCH || '').toLowerCase())
-      ? String(process.env.KIKU_AUTO_RESEARCH).toLowerCase()
-      : 'auto',
-    systemPersona: `You are KIKU AGENT (菊), the authoritative AI encyclopedia agent and concierge for international artist Ju Jingyi (鞠婧祎).
-Speak with elegance, utmost respect, professional warmth, and meticulous factual rigor. You deliver concise, polite answers for simple facts, and structured, in-depth breakdowns for rich cultural and artistic inquiries.
-
-MULTI-ANGLE RETRIEVAL & SMART MULTI-TOOL PARALLELISM:
-Always retrieve verified facts through parallel multi-angle tool calls when addressing complex or cross-cutting queries.`,
-  }
-};
+import { randomUUID as settingsRandomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { PROVIDER_KEYS_FILE, SETTINGS_FILE } from './appPaths.js';
+
+const PROVIDER_MODEL_ALIASES = {
+  lmstudio: {
+    'q8': 'google/gemma-4-e4b-Q8_0',
+    'q8_0': 'google/gemma-4-e4b-Q8_0',
+    'q8-0': 'google/gemma-4-e4b-Q8_0',
+    '8bit': 'google/gemma-4-e4b-Q8_0',
+    '8-bit': 'google/gemma-4-e4b-Q8_0',
+    'gemma-q8': 'google/gemma-4-e4b-Q8_0',
+    'gemma-q8_0': 'google/gemma-4-e4b-Q8_0',
+    'gemma-4-e4b-q8': 'google/gemma-4-e4b-Q8_0',
+    'gemma-4-e4b-q8_0': 'google/gemma-4-e4b-Q8_0',
+    'google/gemma-4-e4b-q8_0': 'google/gemma-4-e4b-Q8_0',
+    'google/gemma-4-e4b-q8': 'google/gemma-4-e4b-Q8_0',
+
+    'q6': 'google/gemma-4-e4b-Q6_K',
+    'q6_k': 'google/gemma-4-e4b-Q6_K',
+    'q6-k': 'google/gemma-4-e4b-Q6_K',
+    '6bit': 'google/gemma-4-e4b-Q6_K',
+    '6-bit': 'google/gemma-4-e4b-Q6_K',
+    'gemma-q6': 'google/gemma-4-e4b-Q6_K',
+    'gemma-q6_k': 'google/gemma-4-e4b-Q6_K',
+    'gemma-4-e4b-q6': 'google/gemma-4-e4b-Q6_K',
+    'gemma-4-e4b-q6_k': 'google/gemma-4-e4b-Q6_K',
+    'google/gemma-4-e4b-q6_k': 'google/gemma-4-e4b-Q6_K',
+    'google/gemma-4-e4b-q6': 'google/gemma-4-e4b-Q6_K',
+
+    'q4': 'google/gemma-4-e4b-Q4_K_M',
+    'q4_k': 'google/gemma-4-e4b-Q4_K_M',
+    'q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
+    'q4-k-m': 'google/gemma-4-e4b-Q4_K_M',
+    '4bit': 'google/gemma-4-e4b-Q4_K_M',
+    '4-bit': 'google/gemma-4-e4b-Q4_K_M',
+    'gemma-q4': 'google/gemma-4-e4b-Q4_K_M',
+    'gemma-q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
+    'gemma-4-e4b-q4': 'google/gemma-4-e4b-Q4_K_M',
+    'gemma-4-e4b-q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
+    'google/gemma-4-e4b-q4_k_m': 'google/gemma-4-e4b-Q4_K_M',
+    'google/gemma-4-e4b-q4': 'google/gemma-4-e4b-Q4_K_M',
+
+    'gemma': 'google/gemma-4-e4b',
+    'gemma4': 'google/gemma-4-e4b',
+    'gemma-4': 'google/gemma-4-e4b',
+    'gemma-4-e4b': 'google/gemma-4-e4b',
+    'gemma-4-e4b-it-q4_k_m.gguf': 'google/gemma-4-e4b',
+    'gemma-4-e4b-it-q4_k_m': 'google/gemma-4-e4b',
+    'gemma-4-e4b-q4_k_m.gguf': 'google/gemma-4-e4b',
+    'gemma-4-e4b-q6_k.gguf': 'google/gemma-4-e4b-Q6_K',
+    'gemma-4-e4b-q8_0.gguf': 'google/gemma-4-e4b-Q8_0',
+    'gemma-4-e4b.gguf': 'google/gemma-4-e4b',
+    'qwen': 'Qwen/Qwen2.5-7B-Instruct-GGUF',
+    'qwen-7b': 'Qwen/Qwen2.5-7B-Instruct-GGUF',
+    'qwen2.5': 'Qwen/Qwen2.5-7B-Instruct-GGUF',
+    'qwen2.5-7b': 'Qwen/Qwen2.5-7B-Instruct-GGUF',
+    'qwen-3b': 'Qwen/Qwen2.5-3B-Instruct-GGUF',
+    'qwen2.5-3b': 'Qwen/Qwen2.5-3B-Instruct-GGUF',
+    'qwen-coder': 'Qwen/Qwen2.5-Coder-7B-Instruct-GGUF',
+    'qwen2.5-coder': 'Qwen/Qwen2.5-Coder-7B-Instruct-GGUF',
+    'qwen3': 'Qwen/Qwen3-8B',
+    'qwq': 'Qwen/QwQ-32B',
+  },
+  vllm: {
+    'gemma': 'google/gemma-4-e4b',
+    'gemma4': 'google/gemma-4-e4b',
+    'gemma-4': 'google/gemma-4-e4b',
+    'gemma-4-e4b': 'google/gemma-4-e4b',
+    'qwen': 'Qwen/Qwen2.5-7B-Instruct',
+    'qwen-7b': 'Qwen/Qwen2.5-7B-Instruct',
+    'qwen2.5': 'Qwen/Qwen2.5-7B-Instruct',
+    'qwen2.5-7b': 'Qwen/Qwen2.5-7B-Instruct',
+    'qwen-3b': 'Qwen/Qwen2.5-3B-Instruct',
+    'qwen2.5-3b': 'Qwen/Qwen2.5-3B-Instruct',
+    'qwen-coder': 'Qwen/Qwen2.5-Coder-7B-Instruct',
+    'qwen2.5-coder': 'Qwen/Qwen2.5-Coder-7B-Instruct',
+    'qwen3': 'Qwen/Qwen3-8B',
+    'qwq': 'Qwen/QwQ-32B',
+    'llama': 'meta-llama/Llama-3.1-8B-Instruct',
+  },
+  ollama: {
+    'qwen': 'qwen2.5:7b',
+    'qwen-7b': 'qwen2.5:7b',
+    'qwen2.5': 'qwen2.5:7b',
+    'qwen2.5-7b': 'qwen2.5:7b',
+    'qwen-3b': 'qwen2.5:3b',
+    'qwen2.5-3b': 'qwen2.5:3b',
+    'qwen-coder': 'qwen2.5-coder:7b',
+    'qwen2.5-coder': 'qwen2.5-coder:7b',
+    'llama': 'llama3.1:8b',
+    'llama3': 'llama3.1:8b',
+    'deepseek': 'deepseek-r1:7b',
+    'deepseek-r1': 'deepseek-r1:7b',
+    'r1': 'deepseek-r1:7b',
+    'gemma': 'gemma2:9b',
+  },
+  openai: {
+    'o1-mini': 'gpt-5.6-luna',
+    'o3-mini': 'gpt-5.6-luna',
+  },
+  openrouter: {
+    auto: 'openrouter/auto',
+  },
+  groq: {
+    'gpt-oss-120b': 'openai/gpt-oss-120b',
+    'gpt-oss-20b': 'openai/gpt-oss-20b',
+  },
+  deepseek: {
+    'deepseek-chat': 'deepseek-v4-flash',
+    'deepseek-reasoner': 'deepseek-v4-flash',
+  },
+  gemini: {
+    'gemini-3.1-pro': 'gemini-3.1-pro-preview',
+  },
+};
+
+const GENERIC_MODEL_TOKENS = new Set(['model', 'chat', 'default', 'base', 'instruct', 'text', 'embedding']);
+
+export function extractModelQuantization(modelId) {
+  if (!modelId || typeof modelId !== 'string') return null;
+  const clean = modelId.toUpperCase();
+  const m = clean.match(/(Q[0-9]+_[A-Z0-9_]+|Q[0-9]+_[A-Z]|Q[0-9]+|[0-9]+BIT|FP16|FP32|BF16)/i);
+  return m ? m[1].toUpperCase() : null;
+}
+
+export function cleanModelName(modelId) {
+  if (!modelId || typeof modelId !== 'string') return '';
+  let name = modelId.trim();
+  name = name.replace(/\.(gguf|bin|safetensors)$/i, '');
+  if (name.includes('/')) {
+    const parts = name.split('/').filter(Boolean);
+    name = parts[parts.length - 1] || parts[0];
+  }
+  return name.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+}
+
+export function matchModelIdentifier(target, candidate) {
+  if (!target || !candidate) return false;
+  if (target === candidate) return true;
+
+  const targetLower = String(target).toLowerCase().trim();
+  const candLower = String(candidate).toLowerCase().trim();
+  if (targetLower === candLower) return true;
+
+  const targetClean = cleanModelName(target);
+  const candClean = cleanModelName(candidate);
+  if (targetClean && candClean && targetClean === candClean) return true;
+
+  const targetQuant = extractModelQuantization(target);
+  const candQuant = extractModelQuantization(candidate);
+
+  const targetIsGemma = /gemma/i.test(target);
+  const candIsGemma = /gemma/i.test(candidate);
+
+  if (candIsGemma) {
+    if (targetIsGemma) {
+      if (targetQuant && candQuant) {
+        const normTargetQ = targetQuant.replace(/[^A-Z0-9]/g, '');
+        const normCandQ = candQuant.replace(/[^A-Z0-9]/g, '');
+        if (normTargetQ === normCandQ || normCandQ.startsWith(normTargetQ) || normTargetQ.startsWith(normCandQ)) {
+          return true;
+        }
+      } else if (!targetQuant) {
+        if (targetClean.includes('gemma') && candClean.includes('gemma')) {
+          return true;
+        }
+      }
+    } else if (targetQuant && !GENERIC_MODEL_TOKENS.has(targetClean)) {
+      if (candQuant) {
+        const normTargetQ = targetQuant.replace(/[^A-Z0-9]/g, '');
+        const normCandQ = candQuant.replace(/[^A-Z0-9]/g, '');
+        if (normTargetQ === normCandQ || normCandQ.startsWith(normTargetQ) || normTargetQ.startsWith(normCandQ)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  if (targetClean && candClean && !GENERIC_MODEL_TOKENS.has(targetClean) && targetClean.length >= 5) {
+    if (candClean.includes(targetClean) || (candClean.length >= 5 && targetClean.includes(candClean))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function normalizeProviderModel(providerId, modelId) {
+  const normalizedProvider = String(providerId || '').toLowerCase().trim();
+  const normalizedModel = String(modelId || '').trim();
+  const aliasMatch = PROVIDER_MODEL_ALIASES[normalizedProvider]?.[normalizedModel.toLowerCase()]
+    || PROVIDER_MODEL_ALIASES[normalizedProvider]?.[normalizedModel];
+  if (aliasMatch) return aliasMatch;
+
+  if (normalizedProvider === 'lmstudio') {
+    const clean = normalizedModel.toLowerCase().replace(/\\/g, '/');
+    const baseName = clean.split('/').pop();
+    if (baseName && PROVIDER_MODEL_ALIASES.lmstudio[baseName]) {
+      return PROVIDER_MODEL_ALIASES.lmstudio[baseName];
+    }
+    if (/(?=.*gemma)(?=.*e4b)/i.test(baseName || clean)) {
+      if (/(?:q6|6bit)/i.test(baseName || clean)) return 'google/gemma-4-e4b-Q6_K';
+      if (/(?:q8|8bit)/i.test(baseName || clean)) return 'google/gemma-4-e4b-Q8_0';
+      return 'google/gemma-4-e4b';
+    }
+  }
+
+  return normalizedModel;
+}
+
+export const DEFAULT_LOCAL_ENDPOINTS = Object.freeze({
+  lmstudio: 'http://127.0.0.1:1234/v1',
+  vllm: 'http://127.0.0.1:8000/v1',
+  ollama: 'http://127.0.0.1:11434/v1',
+});
+
+export const CLOUD_PROVIDERS = {
+  lmstudio: {
+    id: 'lmstudio',
+    name: 'LM Studio (Local)',
+    baseUrl: process.env.LMSTUDIO_BASE_URL || process.env.OPENAI_BASE_URL || 'http://127.0.0.1:1234/v1',
+    apiKey: process.env.LMSTUDIO_API_KEY || 'lm-studio',
+    defaultModel: 'google/gemma-4-e4b',
+    isLocal: true,
+    envKey: 'LMSTUDIO_BASE_URL',
+    docUrl: 'https://lmstudio.ai/docs',
+    apiRefUrl: 'https://lmstudio.ai/docs/api/local-server',
+    pricingSummary: '100% Free / Local (No API Key required)',
+    features: ['local', 'private', 'offline', 'zero-cost', 'openai-compatible'],
+    recommendedModels: [
+      { id: 'google/gemma-4-e4b', name: 'Gemma 4 e4b (Default / Q4_K_M)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: 'Recommended default. Balanced 4-bit quantization (Q4_K_M) — fastest inference and lowest RAM usage.' },
+      { id: 'google/gemma-4-e4b-Q4_K_M', name: 'Gemma 4 e4b (Q4_K_M Quant)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: '4-bit medium quantization (Q4_K_M) optimized for speed and low memory footprint (~2.5GB RAM).' },
+      { id: 'Qwen/Qwen2.5-7B-Instruct-GGUF', name: 'Qwen 2.5 7B Instruct (Q4_K_M)', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'High-capability open reasoning and tool-calling model (~4.8GB RAM/VRAM with Q4_K_M).' },
+      { id: 'Qwen/Qwen2.5-3B-Instruct-GGUF', name: 'Qwen 2.5 3B Instruct (Q4_K_M)', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'Ultra-lightweight open model for low-VRAM machines (~2.2GB RAM/VRAM).' },
+      { id: 'google/gemma-4-e4b-Q6_K', name: 'Gemma 4 e4b (Q6_K Quant)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: '6-bit quantization (Q6_K) offering higher precision and near-original fidelity (~3.5GB RAM).' },
+      { id: 'google/gemma-4-e4b-Q8_0', name: 'Gemma 4 e4b (Q8_0 Quant)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: '8-bit full quantization (Q8_0) for maximum accuracy and reasoning precision (~4.5GB RAM).' },
+    ],
+  },
+  vllm: {
+    id: 'vllm',
+    name: 'vLLM (Local / WSL)',
+    baseUrl: process.env.VLLM_BASE_URL || 'http://127.0.0.1:8000/v1',
+    apiKey: process.env.VLLM_API_KEY || 'token-kiku',
+    defaultModel: process.env.VLLM_MODEL || 'google/gemma-4-e4b',
+    isLocal: true,
+    envKey: 'VLLM_BASE_URL',
+    docUrl: 'https://docs.vllm.ai',
+    apiRefUrl: 'https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html',
+    pricingSummary: '100% Free / Local (High-throughput PagedAttention server via WSL/Linux)',
+    features: ['local', 'high-throughput', 'paged-attention', 'wsl-required', 'openai-compatible'],
+    platformNotice: 'You cannot install vLLM natively on Windows. Please install and run vLLM via WSL (Windows Subsystem for Linux, e.g. wsl -d kali-linux or Ubuntu) using "vllm serve <model> --port 8000".',
+    recommendedModels: [
+      { id: 'google/gemma-4-e4b', name: 'Gemma 4 e4b (Default)', tier: 'free', cost: '$0.00 (Local)', context: '8k', hasTools: true, description: 'Recommended default model served via vllm serve on port 8000.' },
+      { id: 'Qwen/Qwen2.5-7B-Instruct', name: 'Qwen 2.5 7B Instruct', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'High capability open model with function calling on vLLM.' },
+      { id: 'Qwen/Qwen2.5-3B-Instruct', name: 'Qwen 2.5 3B Instruct', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'Ultra-fast, low-memory open model for constrained vLLM instances (~3GB VRAM).' },
+      { id: 'meta-llama/Llama-3.1-8B-Instruct', name: 'Llama 3.1 8B Instruct', tier: 'free', cost: '$0.00 (Local)', context: '128k', hasTools: true, description: 'Fast general-purpose open model hosted on vLLM.' },
+    ],
+  },
+  ollama: {
+    id: 'ollama',
+    name: 'Ollama (Local)',
+    baseUrl: process.env.OLLAMA_BASE_URL || 'http://127.0.0.1:11434/v1',
+    apiKey: process.env.OLLAMA_API_KEY || 'ollama',
+    defaultModel: process.env.OLLAMA_MODEL || 'qwen2.5:7b',
+    isLocal: true,
+    envKey: 'OLLAMA_BASE_URL',
+    docUrl: 'https://github.com/ollama/ollama',
+    apiRefUrl: 'https://github.com/ollama/ollama/blob/main/docs/openai.md',
+    pricingSummary: '100% Free / Local (Auto-quantization and model management)',
+    features: ['local', 'private', 'offline', 'zero-cost', 'openai-compatible', 'auto-quant'],
+    recommendedModels: [
+      { id: 'qwen2.5:7b', name: 'Qwen 2.5 7B', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'Recommended default for Ollama. 4-bit quant loaded on demand (~4.7GB VRAM).' },
+      { id: 'qwen2.5:3b', name: 'Qwen 2.5 3B', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'Lightweight model for machines with <6GB VRAM (~2.0GB VRAM).' },
+      { id: 'qwen2.5-coder:7b', name: 'Qwen 2.5 Coder 7B', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'Specialized coding and structured tool-calling model.' },
+      { id: 'deepseek-r1:7b', name: 'DeepSeek R1 Distill 7B', tier: 'free', cost: '$0.00 (Local)', context: '32k', hasTools: true, description: 'Distilled reasoning model with <think> chain-of-thought.' },
+      { id: 'llama3.1:8b', name: 'Llama 3.1 8B', tier: 'free', cost: '$0.00 (Local)', context: '128k', hasTools: true, description: 'General-purpose open model with large context.' },
+    ],
+  },
+  openai: {
+    id: 'openai',
+    name: 'OpenAI Cloud',
+    baseUrl: process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY || '',
+    defaultModel: normalizeProviderModel('openai', process.env.OPENAI_MODEL || 'gpt-5.6-luna'),
+    isLocal: false,
+    envKey: 'OPENAI_API_KEY',
+    docUrl: 'https://developers.openai.com/api/docs/models',
+    apiRefUrl: 'https://developers.openai.com/api/reference',
+    pricingSummary: 'GPT-5.6 Luna: $0.20/1M in, $1.20/1M out; Terra/Sol available for higher capability',
+    features: ['tools', 'streaming', 'vision', 'reasoning', 'system-prompt'],
+    recommendedModels: [
+      { id: 'gpt-5.6-luna', name: 'GPT-5.6 Luna', tier: 'cost-sensitive', cost: '$0.20 / 1M in', context: '1.05M', hasTools: true, description: 'Recommended default for efficient, high-volume multilingual agent workloads.' },
+      { id: 'gpt-5.6-terra', name: 'GPT-5.6 Terra', tier: 'balanced', cost: '$2.00 / 1M in', context: '1.05M', hasTools: true, description: 'Balances intelligence and cost for production reasoning and tool use.' },
+      { id: 'gpt-5.6-sol', name: 'GPT-5.6 Sol', tier: 'flagship', cost: '$4.00 / 1M in', context: '1.05M', hasTools: true, description: 'Flagship model for complex professional reasoning and coding.' },
+    ],
+  },
+  openrouter: {
+    id: 'openrouter',
+    name: 'OpenRouter Cloud',
+    baseUrl: process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1',
+    apiKey: process.env.OPENROUTER_API_KEY || '',
+    defaultModel: normalizeProviderModel('openrouter', process.env.OPENROUTER_MODEL || 'openrouter/auto'),
+    extraHeaders: {
+      'HTTP-Referer': 'https://jujingyi-kikuuu.vercel.app/',
+      'X-OpenRouter-Title': 'Kiku Agent',
+    },
+    isLocal: false,
+    envKey: 'OPENROUTER_API_KEY',
+    docUrl: 'https://openrouter.ai/docs/guides/routing/routers/auto-router',
+    apiRefUrl: 'https://openrouter.ai/docs/api/reference/overview',
+    pricingSummary: 'Auto Router selects a current model dynamically; usage is billed at the routed model rate',
+    features: ['universal-routing', 'tools', 'streaming', 'free-tier', 'fallback'],
+    recommendedModels: [
+      { id: 'openrouter/auto', name: 'OpenRouter Auto Router', tier: 'dynamic', cost: 'Routed model rate', context: 'Model-dependent', hasTools: true, description: 'Recommended default. Chooses from the current catalog so a retired third-party model does not break startup.' },
+    ],
+  },
+  groq: {
+    id: 'groq',
+    name: 'Groq Cloud',
+    baseUrl: process.env.GROQ_BASE_URL || 'https://api.groq.com/openai/v1',
+    apiKey: process.env.GROQ_API_KEY || '',
+    defaultModel: normalizeProviderModel('groq', process.env.GROQ_MODEL || 'openai/gpt-oss-120b'),
+    isLocal: false,
+    envKey: 'GROQ_API_KEY',
+    docUrl: 'https://console.groq.com/docs/quickstart',
+    apiRefUrl: 'https://console.groq.com/docs/api-reference',
+    pricingSummary: 'Ultra-fast LPU inference (GPT-OSS 20B: $0.075/1M in, GPT-OSS 120B: $0.15/1M in)',
+    features: ['lpu-speed', 'tools', 'streaming', 'openai-compatible'],
+    recommendedModels: [
+      { id: 'openai/gpt-oss-120b', name: 'GPT-OSS 120B', tier: 'flagship', cost: '$0.15 / 1M in', context: '131k', hasTools: true, description: 'Recommended default. Production-grade 120B reasoning model with tool use on Groq.' },
+      { id: 'openai/gpt-oss-20b', name: 'GPT-OSS 20B', tier: 'ultra-cheap', cost: '$0.075 / 1M in', context: '131k', hasTools: true, description: 'Fast production model for lower-cost, high-volume requests.' },
+    ],
+  },
+  deepseek: {
+    id: 'deepseek',
+    name: 'DeepSeek Cloud',
+    baseUrl: process.env.DEEPSEEK_BASE_URL || 'https://api.deepseek.com',
+    apiKey: process.env.DEEPSEEK_API_KEY || '',
+    defaultModel: normalizeProviderModel('deepseek', process.env.DEEPSEEK_MODEL || 'deepseek-v4-flash'),
+    isLocal: false,
+    envKey: 'DEEPSEEK_API_KEY',
+    docUrl: 'https://api-docs.deepseek.com',
+    apiRefUrl: 'https://api-docs.deepseek.com/api/create-chat-completion',
+    pricingSummary: 'V4 Flash: $0.22-$0.44/1M uncached input; V4 Pro: $0.66-$1.32/1M (off-peak/peak)',
+    features: ['deepseek-v4', 'thinking', 'tools', 'streaming', 'context-cache', '1m-context'],
+    recommendedModels: [
+      { id: 'deepseek-v4-flash', name: 'DeepSeek V4 Flash', tier: 'balanced', cost: '$0.22-$0.44 / 1M uncached in', context: '1M', hasTools: true, description: 'Recommended default. Current V4 model with tool calls and thinking/non-thinking modes.' },
+      { id: 'deepseek-v4-pro', name: 'DeepSeek V4 Pro', tier: 'flagship', cost: '$0.66-$1.32 / 1M uncached in', context: '1M', hasTools: true, description: 'Higher-capability V4 model with tool calls and thinking mode.' },
+    ],
+  },
+  gemini: {
+    id: 'gemini',
+    name: 'Google Gemini',
+    baseUrl: process.env.GEMINI_BASE_URL || 'https://generativelanguage.googleapis.com/v1beta/openai',
+    apiKey: process.env.GEMINI_API_KEY || '',
+    defaultModel: normalizeProviderModel('gemini', process.env.GEMINI_MODEL || 'gemini-3.7-flash'),
+    isLocal: false,
+    envKey: 'GEMINI_API_KEY',
+    docUrl: 'https://ai.google.dev/gemini-api/docs',
+    apiRefUrl: 'https://ai.google.dev/api/generate-content',
+    pricingSummary: 'Gemini 3.7 Flash: free tier available; paid standard $0.75/1M input through 2026',
+    features: ['1m-context', 'multimodal', 'tools', 'streaming', 'thinking'],
+    recommendedModels: [
+      { id: 'gemini-3.7-flash', name: 'Gemini 3.7 Flash', tier: 'latest-stable', cost: '$0.75 / 1M in (2026)', context: '1M', hasTools: true, description: 'Recommended default. Latest stable Flash model for agentic workflows and multimodal reasoning.' },
+      { id: 'gemini-3.5-flash-lite', name: 'Gemini 3.5 Flash-Lite', tier: 'lowest-cost', cost: '$0.30 / 1M in', context: '1M', hasTools: true, description: 'Stable, cost-efficient model for high-volume translation and simple processing.' },
+      { id: 'gemini-3.6-flash', name: 'Gemini 3.6 Flash', tier: 'stable', cost: '$0.75 / 1M in (2026)', context: '1M', hasTools: true, description: 'Stable previous-generation Flash fallback with function calling and thinking.' },
+    ],
+  },
+  anthropic: {
+    id: 'anthropic',
+    name: 'Anthropic Claude',
+    baseUrl: process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com',
+    apiKey: process.env.ANTHROPIC_API_KEY || '',
+    defaultModel: process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-5',
+    isLocal: false,
+    envKey: 'ANTHROPIC_API_KEY',
+    docUrl: 'https://docs.anthropic.com/en/docs',
+    apiRefUrl: 'https://docs.anthropic.com/en/api/messages',
+    pricingSummary: 'Claude Messages API with native tool use and extended thinking support',
+    features: ['tools', 'streaming', 'vision', 'thinking', 'native-messages'],
+    extraHeaders: { 'anthropic-version': '2023-06-01' },
+    recommendedModels: [
+      { id: 'claude-sonnet-4-5', name: 'Claude Sonnet 4.5', tier: 'balanced', cost: 'Provider pricing', context: '200k', hasTools: true, description: 'Balanced Claude model for agentic tool use.' },
+      { id: 'claude-opus-4-1', name: 'Claude Opus 4.1', tier: 'flagship', cost: 'Provider pricing', context: '200k', hasTools: true, description: 'Highest-capability Claude model for complex reasoning.' },
+      { id: 'claude-haiku-3-5', name: 'Claude Haiku 3.5', tier: 'fast', cost: 'Provider pricing', context: '200k', hasTools: true, description: 'Fast, lower-cost Claude model.' },
+    ],
+  },
+  custom: {
+    id: 'custom',
+    name: 'Custom OpenAI-Compatible',
+    baseUrl: process.env.LLM_BASE_URL || '',
+    apiKey: process.env.LLM_API_KEY || '',
+    defaultModel: process.env.LLM_MODEL || 'default',
+    isLocal: false,
+    envKey: 'LLM_API_KEY',
+    docUrl: 'https://platform.openai.com/docs/api-reference',
+    apiRefUrl: 'https://platform.openai.com/docs/api-reference/chat',
+    pricingSummary: 'Self-hosted or Custom Gateway',
+    features: ['custom-endpoint', 'openai-compatible', 'tools', 'streaming'],
+    recommendedModels: [
+      { id: 'default', name: 'Default Model', tier: 'custom', cost: 'Custom', context: 'Custom', hasTools: true, description: 'Custom model specified via LLM_MODEL or /model use <id>.' },
+    ],
+  },
+};
+
+let cachedSettings = null;
+let lastSettingsLoadTime = 0;
+const SETTINGS_CACHE_TTL_MS = 2000;
+
+export function invalidateSettingsCache() {
+  cachedSettings = null;
+  lastSettingsLoadTime = 0;
+}
+
+export function loadPersistedSettings(force = false) {
+  const now = Date.now();
+  if (!force && cachedSettings && (now - lastSettingsLoadTime < SETTINGS_CACHE_TTL_MS)) {
+    return cachedSettings;
+  }
+  try {
+    if (fs.existsSync(SETTINGS_FILE)) {
+      const data = fs.readFileSync(SETTINGS_FILE, 'utf-8');
+      const parsed = JSON.parse(data);
+      if (parsed && typeof parsed === 'object') {
+        if (parsed.providerModels && typeof parsed.providerModels === 'object') {
+          for (const [pId, model] of Object.entries(parsed.providerModels)) {
+            const providerDef = CLOUD_PROVIDERS[pId.toLowerCase()];
+            if (providerDef && typeof model === 'string' && model.trim()) {
+              providerDef.defaultModel = model.trim();
+            }
+          }
+        }
+        if (parsed.providerBaseUrls && typeof parsed.providerBaseUrls === 'object') {
+          for (const [pId, url] of Object.entries(parsed.providerBaseUrls)) {
+            const providerDef = CLOUD_PROVIDERS[pId.toLowerCase()];
+            if (providerDef && typeof url === 'string' && url.trim()) {
+              providerDef.baseUrl = url.trim().replace(/\/+$/, '');
+            }
+          }
+        }
+        cachedSettings = parsed;
+        lastSettingsLoadTime = now;
+        return parsed;
+      }
+    }
+  } catch {}
+  cachedSettings = {};
+  lastSettingsLoadTime = now;
+  return {};
+}
+
+export function writeSettingsFileAtomic(settings) {
+  fs.mkdirSync(path.dirname(SETTINGS_FILE), { recursive: true, mode: 0o700 });
+  const temporary = SETTINGS_FILE + '.' + process.pid + '.' + settingsRandomUUID() + '.tmp';
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(settings, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    try {
+      fs.renameSync(temporary, SETTINGS_FILE);
+    } catch (err) {
+      if (err.code === 'EPERM' || err.code === 'EBUSY') {
+        fs.copyFileSync(temporary, SETTINGS_FILE);
+      } else {
+        throw err;
+      }
+    }
+    invalidateSettingsCache();
+  } finally {
+    if (fs.existsSync(temporary)) {
+      try { fs.unlinkSync(temporary); } catch {}
+    }
+  }
+}
+
+let settingsWriteQueue = Promise.resolve();
+export function withSettingsWriteQueue(update) {
+  const pending = settingsWriteQueue.then(update);
+  settingsWriteQueue = pending.catch(() => {});
+  return pending;
+}
+
+export const INFERENCE_DEFAULTS = Object.freeze({
+  temperature: 0.7,
+  topP: 0.95,
+  contextLimit: 32768,
+  thinking: 'show',
+  persona: 'default',
+  stream: true,
+});
+
+export function normalizeInferenceSettings(partial = {}, base = INFERENCE_DEFAULTS) {
+  const result = { ...base };
+  for (const [key, min, max] of [
+    ['temperature', 0, 2],
+    ['topP', 0.01, 1],
+    ['contextLimit', 1024, 131072],
+  ]) {
+    if (partial[key] === null || partial[key] === '' || partial[key] === undefined || typeof partial[key] === 'boolean') continue;
+    const value = Number(partial[key]);
+    if (Number.isFinite(value)) result[key] = Math.max(min, Math.min(max, key === 'contextLimit' ? Math.floor(value) : value));
+  }
+  for (const [key, min, max] of [
+    ['minP', 0, 1],
+    ['repeatPenalty', 1.0, 2.0],
+  ]) {
+    if (partial[key] !== null && partial[key] !== '' && partial[key] !== undefined && typeof partial[key] !== 'boolean') {
+      const value = Number(partial[key]);
+      if (Number.isFinite(value)) result[key] = Math.max(min, Math.min(max, value));
+    } else if (base[key] !== undefined) {
+      result[key] = base[key];
+    }
+  }
+  if (['show', 'collapse', 'hide'].includes(partial.thinking)) result.thinking = partial.thinking;
+  if (['default', 'official', 'fan', 'researcher'].includes(partial.persona)) result.persona = partial.persona;
+  if (typeof partial.stream === 'boolean') result.stream = partial.stream;
+  return result;
+}
+export function getPersistedInferenceSettings() {
+  return normalizeInferenceSettings(loadPersistedSettings().inference || {});
+}
+export function savePersistedInferenceSettings(partial = {}) {
+  const settings = structuredClone(loadPersistedSettings(true));
+  settings.inference = normalizeInferenceSettings(partial, normalizeInferenceSettings(settings.inference || {}));
+  writeSettingsFileAtomic(settings);
+  return settings.inference;
+}
+
+export const MODEL_LOAD_DEFAULTS = Object.freeze({
+  activeEngine: 'lms',
+  gpuOffload: 'auto',
+  cpuThreads: 1,
+  contextLength: 32768,
+  autoContext: true,
+  splitMode: 'layer',
+  tensorSplit: null,
+  mainGpu: 0,
+  flashAttn: true,
+  batchSize: 2048,
+  ubatchSize: 512,
+  kvCacheDtype: 'auto',
+  vllm: Object.freeze({
+    gpuMemoryUtilization: 0.90,
+    maxModelLen: null,
+    tensorParallelSize: 1,
+    dtype: 'auto',
+    enforceEager: false,
+    enablePrefixCaching: true,
+    kvCacheDtype: 'auto',
+  }),
+});
+
+export function normalizeModelLoadSettings(partial = {}, base = MODEL_LOAD_DEFAULTS) {
+  const result = {
+    activeEngine: base.activeEngine || 'lms',
+    gpuOffload: base.gpuOffload || 'auto',
+    cpuThreads: base.cpuThreads !== undefined ? base.cpuThreads : 1,
+    contextLength: base.contextLength ?? null,
+    autoContext: base.autoContext ?? true,
+    splitMode: base.splitMode || 'layer',
+    tensorSplit: base.tensorSplit ?? null,
+    mainGpu: base.mainGpu !== undefined ? base.mainGpu : 0,
+    flashAttn: base.flashAttn ?? true,
+    batchSize: base.batchSize !== undefined ? base.batchSize : 2048,
+    ubatchSize: base.ubatchSize !== undefined ? base.ubatchSize : 512,
+    kvCacheDtype: base.kvCacheDtype || 'auto',
+    htMode: base.htMode || 'auto',
+    vllm: { ...base.vllm },
+  };
+
+  if (partial.activeEngine !== undefined && partial.activeEngine !== null) {
+    const eng = String(partial.activeEngine).toLowerCase().trim();
+    if (['lms', 'lmstudio', 'vllm'].includes(eng)) {
+      result.activeEngine = eng === 'lmstudio' ? 'lms' : eng;
+    }
+  }
+
+  if (partial.gpuOffload !== undefined && partial.gpuOffload !== null) {
+    const gpu = String(partial.gpuOffload).toLowerCase().trim();
+    if (['auto', 'off', 'max'].includes(gpu)) {
+      result.gpuOffload = gpu;
+    } else {
+      const ratio = Number(gpu);
+      if (Number.isFinite(ratio) && ratio >= 0 && ratio <= 1) {
+        result.gpuOffload = ratio;
+      }
+    }
+  }
+
+  if (partial.cpuThreads !== undefined) {
+    if (partial.cpuThreads === null || partial.cpuThreads === '' || partial.cpuThreads === 'auto') {
+      result.cpuThreads = null;
+    } else {
+      const n = Number(partial.cpuThreads);
+      if (Number.isFinite(n) && n >= 1 && n <= 256) {
+        result.cpuThreads = Math.floor(n);
+      } else {
+        result.cpuThreads = null;
+      }
+    }
+  }
+
+  if (partial.contextLength !== undefined) {
+    if (partial.contextLength === null || partial.contextLength === '' || partial.contextLength === 'auto') {
+      result.contextLength = null;
+    } else {
+      const c = Number(partial.contextLength);
+      if (Number.isFinite(c) && c >= 512 && c <= 131072) {
+        result.contextLength = Math.floor(c);
+      }
+    }
+  }
+
+  if (partial.autoContext !== undefined && partial.autoContext !== null && partial.autoContext !== '') {
+    const text = String(partial.autoContext).trim().toLowerCase();
+    if (typeof partial.autoContext === 'boolean') {
+      result.autoContext = partial.autoContext;
+    } else if (['true', '1', 'yes', 'on', 'auto'].includes(text)) {
+      result.autoContext = true;
+    } else if (['false', '0', 'no', 'off'].includes(text)) {
+      result.autoContext = false;
+    }
+  }
+
+  if (partial.splitMode !== undefined && partial.splitMode !== null) {
+    const sm = String(partial.splitMode).toLowerCase().trim();
+    if (['layer', 'row', 'none'].includes(sm)) {
+      result.splitMode = sm;
+    }
+  }
+
+  if (partial.tensorSplit !== undefined) {
+    if (partial.tensorSplit === null || partial.tensorSplit === '' || partial.tensorSplit === 'auto') {
+      result.tensorSplit = null;
+    } else if (Array.isArray(partial.tensorSplit)) {
+      result.tensorSplit = partial.tensorSplit.map(n => Number(n)).filter(n => Number.isFinite(n) && n >= 0).join(',');
+    } else if (typeof partial.tensorSplit === 'string') {
+      const cleaned = partial.tensorSplit.split(',').map(s => s.trim()).filter(Boolean).join(',');
+      result.tensorSplit = cleaned || null;
+    }
+  }
+
+  if (partial.mainGpu !== undefined) {
+    const mg = Number(partial.mainGpu);
+    if (Number.isFinite(mg) && mg >= 0 && mg <= 16) {
+      result.mainGpu = Math.floor(mg);
+    }
+  }
+
+  if (partial.flashAttn !== undefined && partial.flashAttn !== null) {
+    if (typeof partial.flashAttn === 'boolean') {
+      result.flashAttn = partial.flashAttn;
+    } else {
+      const s = String(partial.flashAttn).toLowerCase().trim();
+      result.flashAttn = !['false', '0', 'off', 'no'].includes(s);
+    }
+  }
+
+  if (partial.batchSize !== undefined) {
+    const b = Number(partial.batchSize);
+    if (Number.isFinite(b) && b >= 128 && b <= 32768) {
+      result.batchSize = Math.floor(b);
+    }
+  }
+
+  if (partial.ubatchSize !== undefined) {
+    const ub = Number(partial.ubatchSize);
+    if (Number.isFinite(ub) && ub >= 64 && ub <= 8192) {
+      result.ubatchSize = Math.floor(ub);
+    }
+  }
+
+  if (partial.kvCacheDtype !== undefined && partial.kvCacheDtype !== null) {
+    const dt = String(partial.kvCacheDtype).toLowerCase().trim();
+    if (['auto', 'fp16', 'f16', 'q8_0', 'q8', 'q4_0', 'q4'].includes(dt)) {
+      result.kvCacheDtype = dt;
+    }
+  }
+
+  if (partial.htMode !== undefined && partial.htMode !== null) {
+    const ht = String(partial.htMode).toLowerCase().trim();
+    if (['auto', 'physical', 'smt', 'all', 'custom'].includes(ht)) {
+      result.htMode = ht === 'all' ? 'smt' : ht;
+    }
+  }
+
+  const vllmPart = {
+    ...(partial.vllm || {}),
+    ...(partial.gpuMemoryUtilization !== undefined ? { gpuMemoryUtilization: partial.gpuMemoryUtilization } : {}),
+    ...(partial.maxModelLen !== undefined ? { maxModelLen: partial.maxModelLen } : {}),
+    ...(partial.tensorParallelSize !== undefined ? { tensorParallelSize: partial.tensorParallelSize } : {}),
+    ...(partial.dtype !== undefined ? { dtype: partial.dtype } : {}),
+    ...(partial.enforceEager !== undefined ? { enforceEager: partial.enforceEager } : {}),
+    ...(partial.enablePrefixCaching !== undefined ? { enablePrefixCaching: partial.enablePrefixCaching } : {}),
+    ...(partial.kvCacheDtype !== undefined ? { kvCacheDtype: partial.kvCacheDtype } : {}),
+  };
+  if (typeof vllmPart === 'object' && vllmPart !== null) {
+    if (vllmPart.gpuMemoryUtilization !== undefined) {
+      const mem = Number(vllmPart.gpuMemoryUtilization);
+      if (Number.isFinite(mem) && mem >= 0.1 && mem <= 1.0) {
+        result.vllm.gpuMemoryUtilization = Math.round(mem * 100) / 100;
+      }
+    }
+    if (vllmPart.maxModelLen !== undefined) {
+      if (vllmPart.maxModelLen === null || vllmPart.maxModelLen === '' || vllmPart.maxModelLen === 'auto') {
+        result.vllm.maxModelLen = null;
+      } else {
+        const len = Number(vllmPart.maxModelLen);
+        if (Number.isFinite(len) && len >= 512 && len <= 131072) {
+          result.vllm.maxModelLen = Math.floor(len);
+        }
+      }
+    }
+    if (vllmPart.tensorParallelSize !== undefined) {
+      const tp = Number(vllmPart.tensorParallelSize);
+      if (Number.isFinite(tp) && tp >= 1 && tp <= 8) {
+        result.vllm.tensorParallelSize = Math.floor(tp);
+      }
+    }
+    if (vllmPart.dtype !== undefined) {
+      const dt = String(vllmPart.dtype).toLowerCase().trim();
+      if (['auto', 'float16', 'bfloat16', 'half', 'float'].includes(dt)) {
+        result.vllm.dtype = dt;
+      }
+    }
+    if (vllmPart.enforceEager !== undefined) {
+      result.vllm.enforceEager = Boolean(vllmPart.enforceEager);
+    }
+    if (vllmPart.enablePrefixCaching !== undefined) {
+      result.vllm.enablePrefixCaching = Boolean(vllmPart.enablePrefixCaching);
+    }
+    if (vllmPart.kvCacheDtype !== undefined) {
+      const kv = String(vllmPart.kvCacheDtype).toLowerCase().trim();
+      if (['auto', 'fp8', 'fp8_e5m2', 'fp8_e4m3'].includes(kv)) {
+        result.vllm.kvCacheDtype = kv;
+      }
+    }
+  }
+
+  return result;
+}
+
+export function getPersistedModelLoadSettings() {
+  return normalizeModelLoadSettings(loadPersistedSettings().modelLoad || {});
+}
+
+export function savePersistedModelLoadSettings(partial = {}) {
+  const settings = structuredClone(loadPersistedSettings(true));
+  settings.modelLoad = normalizeModelLoadSettings(partial, normalizeModelLoadSettings(settings.modelLoad || {}));
+  writeSettingsFileAtomic(settings);
+  return settings.modelLoad;
+}
+
+export function getActiveLocalEngine() {
+  const settings = getPersistedModelLoadSettings();
+  return settings.activeEngine || 'lms';
+}
+
+export function setActiveLocalEngine(engine) {
+  const norm = String(engine).toLowerCase().trim();
+  const valid = norm === 'vllm' ? 'vllm' : 'lms';
+  savePersistedModelLoadSettings({ activeEngine: valid });
+  return valid;
+}
+
+export function getProviderBaseUrl(providerId) {
+  const pId = String(providerId || '').toLowerCase().trim();
+  const settings = loadPersistedSettings();
+  if (settings.providerBaseUrls && typeof settings.providerBaseUrls[pId] === 'string' && settings.providerBaseUrls[pId].trim()) {
+    return settings.providerBaseUrls[pId].trim().replace(/\/+$/, '');
+  }
+  const providerDef = CLOUD_PROVIDERS[pId];
+  if (providerDef) {
+    if (providerDef.envKey?.endsWith('_BASE_URL') && process.env[providerDef.envKey]) {
+      return process.env[providerDef.envKey].trim().replace(/\/+$/, '');
+    }
+    if (pId === 'lmstudio' && process.env.OPENAI_BASE_URL) {
+      return process.env.OPENAI_BASE_URL.trim().replace(/\/+$/, '');
+    }
+    if (DEFAULT_LOCAL_ENDPOINTS[pId]) {
+      return DEFAULT_LOCAL_ENDPOINTS[pId];
+    }
+    if (providerDef.baseUrl) {
+      return providerDef.baseUrl.trim().replace(/\/+$/, '');
+    }
+  }
+  return DEFAULT_LOCAL_ENDPOINTS.lmstudio;
+}
+
+export function savePersistedProviderBaseUrl(providerId, baseUrl) {
+  const pId = String(providerId || '').toLowerCase().trim();
+  const cleanUrl = String(baseUrl || '').trim().replace(/\/+$/, '');
+  if (!CLOUD_PROVIDERS[pId] || !cleanUrl) return cleanUrl;
+
+  const settings = structuredClone(loadPersistedSettings(true));
+  if (!settings.providerBaseUrls) settings.providerBaseUrls = {};
+  settings.providerBaseUrls[pId] = cleanUrl;
+  if (CLOUD_PROVIDERS[pId]) {
+    CLOUD_PROVIDERS[pId].baseUrl = cleanUrl;
+  }
+  if (config.activeProvider === pId && config.lmStudio) {
+    config.lmStudio.baseUrl = cleanUrl;
+  }
+
+  writeSettingsFileAtomic(settings);
+  return cleanUrl;
+}
+
+export function getPersistedActiveProvider() {
+  const settings = loadPersistedSettings();
+  if (settings.activeProvider && CLOUD_PROVIDERS[settings.activeProvider.toLowerCase()]) {
+    return settings.activeProvider.toLowerCase();
+  }
+  return null;
+}
+
+export function savePersistedActiveProvider(providerId, model = null, baseUrl = null) {
+  const pId = String(providerId || '').toLowerCase().trim();
+  if (!CLOUD_PROVIDERS[pId]) return;
+
+  const settings = structuredClone(loadPersistedSettings(true));
+  settings.activeProvider = pId;
+  if (!settings.providerModels) settings.providerModels = {};
+  if (!settings.providerBaseUrls) settings.providerBaseUrls = {};
+
+  if (model) {
+    const cleanModel = String(model).trim();
+    settings.providerModels[pId] = cleanModel;
+    settings.activeModel = cleanModel;
+    if (CLOUD_PROVIDERS[pId]) CLOUD_PROVIDERS[pId].defaultModel = cleanModel;
+  }
+
+  if (baseUrl) {
+    const cleanUrl = String(baseUrl).trim().replace(/\/+$/, '');
+    settings.providerBaseUrls[pId] = cleanUrl;
+    if (CLOUD_PROVIDERS[pId]) CLOUD_PROVIDERS[pId].baseUrl = cleanUrl;
+  }
+
+  writeSettingsFileAtomic(settings);
+}
+
+export function setActiveProvider(providerId, { model = null, baseUrl = null } = {}) {
+  const pId = String(providerId || '').toLowerCase().trim();
+  if (!CLOUD_PROVIDERS[pId]) {
+    throw new Error(`Unknown provider "${providerId}".`);
+  }
+  savePersistedActiveProvider(pId, model, baseUrl);
+  config.activeProvider = pId;
+  const def = CLOUD_PROVIDERS[pId];
+  if (config.lmStudio) {
+    config.lmStudio.baseUrl = def.baseUrl;
+    config.lmStudio.apiKey = def.apiKey;
+    config.lmStudio.model = def.defaultModel;
+    config.lmStudio.defaultModel = def.defaultModel;
+  }
+  return {
+    provider: pId,
+    name: def.name,
+    baseUrl: def.baseUrl,
+    model: def.defaultModel,
+    isLocal: Boolean(def.isLocal),
+    platformNotice: def.platformNotice || null,
+  };
+}
+
+export function getUnifiedProviderCatalog() {
+  const active = config.activeProvider || resolveDefaultProvider();
+  return {
+    activeProvider: active,
+    activeBaseUrl: getProviderBaseUrl(active),
+    activeModel: CLOUD_PROVIDERS[active]?.defaultModel || 'google/gemma-4-e4b',
+    localEndpoints: {
+      lmstudio: {
+        id: 'lmstudio',
+        name: CLOUD_PROVIDERS.lmstudio.name,
+        baseUrl: getProviderBaseUrl('lmstudio'),
+        defaultModel: CLOUD_PROVIDERS.lmstudio.defaultModel,
+        isActive: active === 'lmstudio',
+      },
+      vllm: {
+        id: 'vllm',
+        name: CLOUD_PROVIDERS.vllm.name,
+        baseUrl: getProviderBaseUrl('vllm'),
+        defaultModel: CLOUD_PROVIDERS.vllm.defaultModel,
+        platformNotice: CLOUD_PROVIDERS.vllm.platformNotice || null,
+        isActive: active === 'vllm',
+      },
+      ollama: {
+        id: 'ollama',
+        name: CLOUD_PROVIDERS.ollama?.name || 'Ollama (Local)',
+        baseUrl: getProviderBaseUrl('ollama'),
+        defaultModel: CLOUD_PROVIDERS.ollama?.defaultModel || 'qwen2.5:7b',
+        isActive: active === 'ollama',
+      }
+    },
+    providers: Object.values(CLOUD_PROVIDERS).map(p => ({
+      id: p.id,
+      name: p.name,
+      baseUrl: getProviderBaseUrl(p.id),
+      defaultModel: p.defaultModel,
+      isLocal: Boolean(p.isLocal),
+      isActive: p.id === active,
+    }))
+  };
+}
+
+export function savePersistedProviderModel(providerId, model) {
+  const pId = String(providerId || '').toLowerCase().trim();
+  const cleanModel = String(model || '').trim();
+  if (!CLOUD_PROVIDERS[pId] || !cleanModel) return;
+
+  const settings = structuredClone(loadPersistedSettings(true));
+  if (!settings.providerModels) settings.providerModels = {};
+  settings.providerModels[pId] = cleanModel;
+  if (settings.activeProvider === pId) {
+    settings.activeModel = cleanModel;
+  }
+  if (CLOUD_PROVIDERS[pId]) CLOUD_PROVIDERS[pId].defaultModel = cleanModel;
+
+  writeSettingsFileAtomic(settings);
+}
+
+export function resolveDefaultProvider() {
+  const explicit = String(process.env.LLM_PROVIDER || '').toLowerCase().trim();
+  if (explicit && CLOUD_PROVIDERS[explicit]) return explicit;
+
+  const persisted = getPersistedActiveProvider();
+  if (persisted && CLOUD_PROVIDERS[persisted]) {
+    const def = CLOUD_PROVIDERS[persisted];
+    if (def.isLocal || def.apiKey) {
+      return persisted;
+    }
+  }
+
+  if (process.env.OPENROUTER_API_KEY && !process.env.OPENROUTER_API_KEY.includes('...')) return 'openrouter';
+  if (process.env.OPENAI_API_KEY && !process.env.OPENAI_API_KEY.includes('...')) return 'openai';
+  if (process.env.GEMINI_API_KEY && !process.env.GEMINI_API_KEY.includes('...')) return 'gemini';
+  if (process.env.DEEPSEEK_API_KEY && !process.env.DEEPSEEK_API_KEY.includes('...')) return 'deepseek';
+  if (process.env.GROQ_API_KEY && !process.env.GROQ_API_KEY.includes('...')) return 'groq';
+  if (process.env.LLM_API_KEY && process.env.LLM_BASE_URL) return 'custom';
+
+  return 'lmstudio';
+}
+
+export function getProvider(id) {
+  const pId = String(id || '').toLowerCase().trim();
+  return CLOUD_PROVIDERS[pId] || null;
+}
+
+export function getProviderList() {
+  return Object.values(CLOUD_PROVIDERS);
+}
+
+export function getRecommendedModels(providerId) {
+  const provider = getProvider(providerId);
+  return provider ? (provider.recommendedModels || []) : [];
+}
+
+let persistedProviderKeys = {};
+const providerKeyEncryptionSecret = process.env.KIKU_PROVIDER_KEY_ENCRYPTION_KEY ||
+  (process.execArgv.includes('--test') ? 'kiku-agent-test-process-only-key' : '');
+
+export function isProviderKeyPersistenceEnabled() {
+  return Boolean(providerKeyEncryptionSecret);
+}
+
+function encryptProviderKeys(keys) {
+  if (!providerKeyEncryptionSecret) return null;
+  const key = crypto.createHash('sha256').update(providerKeyEncryptionSecret).digest();
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(keys), 'utf8'), cipher.final()]);
+  return {
+    version: 1,
+    algorithm: 'aes-256-gcm',
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+  };
+}
+
+function decryptProviderKeys(envelope) {
+  if (!providerKeyEncryptionSecret || envelope?.version !== 1 || envelope?.algorithm !== 'aes-256-gcm') return {};
+  const key = crypto.createHash('sha256').update(providerKeyEncryptionSecret).digest();
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(envelope.iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
+  const plaintext = Buffer.concat([
+    decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
+    decipher.final(),
+  ]).toString('utf8');
+  const parsed = JSON.parse(plaintext);
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+}
+
+export function loadPersistedProviderKeys() {
+  try {
+    if (fs.existsSync(PROVIDER_KEYS_FILE)) {
+      const data = fs.readFileSync(PROVIDER_KEYS_FILE, 'utf-8');
+      const parsed = JSON.parse(data);
+      const keys = parsed?.ciphertext
+        ? decryptProviderKeys(parsed)
+        : (process.env.KIKU_ALLOW_PLAINTEXT_PROVIDER_KEYS === 'true' ? parsed : {});
+      if (keys && typeof keys === 'object') {
+        persistedProviderKeys = { ...keys };
+        for (const [pId, key] of Object.entries(keys)) {
+          const providerDef = CLOUD_PROVIDERS[pId.toLowerCase()];
+          if (providerDef && !providerDef.isLocal && !providerDef.apiKey && typeof key === 'string' && key.trim()) {
+            providerDef.apiKey = key.trim();
+          }
+        }
+        return { ...persistedProviderKeys };
+      }
+    }
+  } catch {}
+  return {};
+}
+
+export function savePersistedProviderKey(providerId, apiKey) {
+  const pId = String(providerId || '').toLowerCase().trim();
+  const providerDef = CLOUD_PROVIDERS[pId];
+  if (!providerDef) {
+    throw new Error(`Unknown provider "${providerId}".`);
+  }
+  const cleanKey = String(apiKey || '').trim();
+  providerDef.apiKey = cleanKey;
+
+  const existing = { ...persistedProviderKeys };
+
+  if (cleanKey) {
+    existing[pId] = cleanKey;
+  } else {
+    delete existing[pId];
+  }
+
+  persistedProviderKeys = existing;
+  try {
+    const envelope = encryptProviderKeys(existing);
+    if (!envelope) return { provider: pId, hasKey: Boolean(cleanKey), persisted: false };
+    const dir = path.dirname(PROVIDER_KEYS_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(PROVIDER_KEYS_FILE, JSON.stringify(envelope, null, 2), { encoding: 'utf-8', mode: 0o600 });
+  } catch (err) {
+    console.error(`Failed to save provider key to ${PROVIDER_KEYS_FILE}:`, err.message);
+  }
+
+  return { provider: pId, hasKey: Boolean(cleanKey) };
+}
+
+export function getPersistedProviderKeys() {
+  return { ...persistedProviderKeys };
+}
+
+loadPersistedSettings();
+loadPersistedProviderKeys();
+
+const defaultProviderId = resolveDefaultProvider();
+const defaultProviderConfig = CLOUD_PROVIDERS[defaultProviderId] || CLOUD_PROVIDERS.lmstudio;
+
+export const config = {
+  activeProvider: defaultProviderId,
+  providers: CLOUD_PROVIDERS,
+
+  lmStudio: {
+    baseUrl: defaultProviderConfig.baseUrl,
+    apiKey: defaultProviderConfig.apiKey,
+    model: defaultProviderConfig.defaultModel,
+    defaultModel: defaultProviderConfig.defaultModel,
+    temperature: 0.3,
+    maxTokens: 8192,
+    requestTimeoutMs: 180000,
+  },
+
+  agent: {
+    maxIterations: 6,
+    slidingWindowSize: 12,
+    language: 'auto',
+
+    autoResearch: ['on', 'off', 'auto'].includes(String(process.env.KIKU_AUTO_RESEARCH || '').toLowerCase())
+      ? String(process.env.KIKU_AUTO_RESEARCH).toLowerCase()
+      : 'auto',
+    systemPersona: `You are KIKU AGENT (菊), the authoritative AI encyclopedia agent and concierge for international artist Ju Jingyi (鞠婧祎).
+Speak with elegance, utmost respect, professional warmth, and meticulous factual rigor. You deliver concise, polite answers for simple facts, and structured, in-depth breakdowns for rich cultural and artistic inquiries.
+
+MULTI-ANGLE RETRIEVAL & SMART MULTI-TOOL PARALLELISM:
+Always retrieve verified facts through parallel multi-angle tool calls when addressing complex or cross-cutting queries.`,
+  }
+};