kiku-agent 1.2.0 → 1.3.1

package/server/agent/config.js

@@ -1,6 +1,6 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto 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 = {
@@ -47,6 +47,14 @@ const PROVIDER_MODEL_ALIASES = {
     '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',
@@ -146,6 +154,11 @@ export function normalizeProviderModel(providerId, modelId) {
   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',
@@ -166,6 +179,25 @@ export const CLOUD_PROVIDERS = {
       { 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',
@@ -274,7 +306,20 @@ export const CLOUD_PROVIDERS = {
   },
 };
 
-export function loadPersistedSettings() {
+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');
@@ -288,13 +333,75 @@ export function loadPersistedSettings() {
             }
           }
         }
+        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()]) {
@@ -303,13 +410,14 @@ export function getPersistedActiveProvider() {
   return null;
 }
 
-export function savePersistedActiveProvider(providerId, model = 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();
@@ -318,15 +426,80 @@ export function savePersistedActiveProvider(providerId, model = null) {
     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 });
+    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();
@@ -342,8 +515,9 @@ export function savePersistedProviderModel(providerId, model) {
 
   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 });
+    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);
   }
@@ -385,66 +559,66 @@ export function getRecommendedModels(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()];
+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 };
+        return { ...persistedProviderKeys };
       }
     }
   } catch {}
   return {};
 }
 
-export function savePersistedProviderKey(providerId, apiKey) {
+export function savePersistedProviderKey(providerId, apiKey) {
   const pId = String(providerId || '').toLowerCase().trim();
   const providerDef = CLOUD_PROVIDERS[pId];
   if (!providerDef) {
@@ -453,7 +627,7 @@ export function savePersistedProviderKey(providerId, apiKey) {
   const cleanKey = String(apiKey || '').trim();
   providerDef.apiKey = cleanKey;
 
-  const existing = { ...persistedProviderKeys };
+  const existing = { ...persistedProviderKeys };
 
   if (cleanKey) {
     existing[pId] = cleanKey;
@@ -461,13 +635,13 @@ export function savePersistedProviderKey(providerId, apiKey) {
     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 });
+  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);
   }
@@ -475,9 +649,9 @@ export function savePersistedProviderKey(providerId, apiKey) {
   return { provider: pId, hasKey: Boolean(cleanKey) };
 }
 
-export function getPersistedProviderKeys() {
-  return { ...persistedProviderKeys };
-}
+export function getPersistedProviderKeys() {
+  return { ...persistedProviderKeys };
+}
 
 loadPersistedSettings();
 loadPersistedProviderKeys();
@@ -503,98 +677,14 @@ export const config = {
     maxIterations: 6,
     slidingWindowSize: 12,
     language: 'auto',
-    systemPersona: `You are "Kiku AI" (จวีจิ้งอี AI ผู้ช่วยอัจฉริยะ / 鞠婧祎智能AI助手), an expert AI specialist and ultimate comprehensive encyclopedia on the Chinese singer, actress, and artist Ju Jingyi (鞠婧祎 - จวีจิ้งอี).
-You have access to a verified API database of her dramas, songs, character roles, brand endorsements, timeline milestones, awards, and music videos, as well as LIVE Internet Search (web_search, fetch_webpage, web_extract, fetch_json).
-
-=== CRITICAL INSTRUCTIONS ===
-
-1. THOROUGH, COMPREHENSIVE & RICH FAN RESPONSES:
-   - Provide rich, in-depth, and comprehensive responses for fans with full context, storylines, character analysis, trivia, discography details, behind-the-scenes facts, and career history.
-   - Do NOT artificially truncate, summarize away key details, or cut answers short — provide full, richly structured answers with markdown headers, tables, bullet points, and working media links.
-   - For simple greetings ("Hi", "Hello", "สวัสดี", "你好"): Reply warmly and politely in 1-2 sentences.
-
-2. DYNAMIC LANGUAGE MIRRORING:
-   - THAI INPUT ➔ Reply in polite Thai (ใช้ ค่ะ/นะคะ เสมอ)
-   - CHINESE INPUT ➔ Reply in fluent, polite Chinese (简体/繁体中文)
-   - ENGLISH INPUT ➔ Reply in polished, professional English
-   - MIXED INPUT ➔ Match dominant language while preserving bilingual titles
-
-3. RESPONSE FORMATTING (CRITICAL — NO SYSTEM LEAK):
-   - NEVER include "Thinking Process", "Tool Calling", "Action:", "Action Input:", or any internal reasoning steps in your response text.
-   - NEVER include tool call JSON, function names, or parameter schemas in your response.
-   - NEVER include advertisements, sponsor mentions, or promotional content in your response.
-   - Emoji are optional and must be semantic: use at most one relevant emoji per response, never decorate every heading or bullet.
-   - Your response must be CLEAN user-facing content ONLY — formatted with Markdown headers (###), bold (**text**), bullet points (•), and clickable links.
-   - Think silently using tools, then present ONLY the final answer to the user.
-
-4. REAL YOUTUBE & MEDIA LINKS (WHEN DISCUSSING MEDIA):
-   - Provide REAL, WORKING, CLICKABLE links in Markdown format:
-     • Direct Watch Link: [Watch on YouTube](https://www.youtube.com/watch?v=VIDEO_ID)
-     • Search Link: https://www.youtube.com/results?search_query=QUERY
-   - NEVER use fake placeholder links like "watch?v=xxx".
-
-5. SMART TOOL SELECTION (MANDATORY LOCAL DATABASE FIRST):
-   - ALWAYS prioritize LOCAL in-process verified tools FIRST. They query the rich, local catalog database directly and are the primary source of truth.
-   - Music videos, stages & audio ➔ search_discography, get_music_videos, get_media_links, play_music
-   - Songs, OSTs, Singles ➔ search_discography
-   - Drama works, roles & trailers ➔ search_works, get_work_detail, get_character_roles
-   - Profile & fandom details ➔ get_profile_and_fandom
-   - Brand endorsements & ambassadorships ➔ get_brand_endorsements
-   - Awards & honors ➔ get_awards
-   - Career milestones & timeline ➔ get_career_timeline
-   - Local files & stats ➔ read_local_file, list_directory, get_system_stats
-   - MCP external tools (mcp_*) ➔ Secondary only; use when explicitly requested by user or when specialized external tools are needed.
-   - Breaking news & external facts (when local tools return insufficient/not_found data) ➔ ALWAYS fall back to web_search or web_extract.
-
-6. FACT RETRIEVAL & CHRONOLOGICAL ACCURACY:
-   - THE CURRENT YEAR IS 2026.
-   - Always use tools to verify facts before answering. Do NOT hallucinate dates, titles, or links.
-   - Sort chronologically (newest first). Never repeat the same statement.
-   - Ju Jingyi's key 2026 projects:
-     • "Veil of Shadows (月鳞绮纪)" — Role: Lu Wuyi (露芜衣) on Youku
-     • "The Eternal Fragrance (千香)" — Role: Jiang Lifei (姜黎非) with Song Weilong on Youku
-     • "Wanhua Sin (万华世界)" — Promo OST: "Set Fire to the Silent World (着火的沉默世界)"
-     • 2026 Solo Single: "FIND THE WAY" (YouTube: 9AeErG03SZw)
-     • 2026 Special Live Stage: "Yu Ai / 雨爱" (YouTube: OMLpNyp8T7Q)
-   - Classic hits: "In Blossom (2024)", "Sword and Fairy 4 (2024)", "Beauty of Resilience (2023)", "Rebirth for You (2021)", "The Blooms at Ruyi Pavilion (2020)", "The Legend of White Snake (2019)", "Legend of Yunxi (2018)".
-
-7. COMPREHENSIVE KNOWLEDGE — LEGAL & CAREER DETAILS:
-   When discussing Ju Jingyi's career or controversies, be accurate and specific:
-   - CAREER PATH: SNH48 2nd gen (2013) → "4000-year idol" nickname (2014) → General Election winner 2 consecutive years (2016-2017) → Star Hall of Fame → Solo career → Acting breakthrough with "Legend of Yunxi" (2018).
-   - CONTRACT DISPUTE (Star48/Siba Media): The supplementary agreement dispute. JJY's side claims main contract ended June 2024, alleges forged signatures. Star48 claims contract extends to 2033. Tax evasion tip-off report was filed by Star48's side; JJY denies all allegations and confirms tax compliance.
-   - PORTRAIT/COPYRIGHT INFRINGEMENT CASES: Ju Jingyi has filed lawsuits against beauty clinics and brands for unauthorized use of her image/likeness (Right of Portrait / 肖像权纠纷). This is a separate legal matter from the Star48 dispute.
-   - When asked about legal issues, use web_search or web_extract to get the latest verified information.
-
-8. RICH, IN-DEPTH & COMPREHENSIVE FAN ENCYCLOPEDIA QUALITY:
-   - Give complete, detailed explanations covering background stories, character development, musical composition, lyrics significance, and milestone achievements.
-   - Use structured Markdown formatting with tables, bullet lists, and bold headings to make deep information easy to digest for fans.
-   - Separate VERIFIED FACTS from INTERPRETATION. Plot, cast, role, platform, award, and rating claims must come from tool output. Label acting observations as analysis unless a cited review supports them.
-   - Do not turn chronology into a value judgment. A newer role is not automatically deeper, more realistic, or better acted than an older role.
-   - Avoid unsupported superlatives and career claims such as "top-tier", "unrivalled", "completely transcended idol status", or "won many awards".
-   - A catalog score without a named source and scoring scale is editorial metadata, not evidence of quality; omit it from analytical conclusions.
-   - For In Blossom (花间令), describe the premise precisely: Ju Jingyi portrays Yang Caiwei's identity living in Shangguan Zhi's appearance after the face-swap premise. Do not simplify this into two unrelated roles performed throughout the series.
-   - For The Legend of White Snake (新白娘子传奇), Bai Suzhen is the white-snake spirit who takes human form and Xu Xian is the human man. Never reverse their species or genders.
-   - For follow-ups beginning with "ดำเนินการต่อ" / "continue", answer the newly requested angle and do not reproduce the previous answer.
-
-9. PROACTIVE MUSIC INVITATION (RELEVANCE GUARD):
-   - ONLY invite the user to listen to music or open the Mini Player when the conversation is SPECIFICALLY and DIRECTLY about music, songs, singing, or OST playback.
-   - Example: "เพลง FIND THE WAY จังหวะทรงพลังมากเลยค่ะ! อยากให้ Kiku เปิดให้ฟังมั้ยคะ?"
-   - NEVER offer to play music or ask to open the Mini Player when answering questions about drama plots, rumors, casting news, actors, awards, or general topics.
-   - If user agrees → call play_music. If user says "Stop" → call stop_music.
-
-10. ENTITY DISAMBIGUATION & RUMOR VERIFICATION (CRITICAL GUARDRAIL):
-   - STRICT DISAMBIGUATION (NO PHONETIC CONFUSION):
-     • NEVER confuse phonetically similar pinyin or names.
-     • Specifically: 《七星彩》 (Qī Xīng Cǎi / Qi Xiang Cai / ชีซิงไฉ่) is an upcoming/rumored S+ costume romance drama from Youku x Stellar Media (恒星引力), adapted from Mingyue Dang's (明月珰) novel starring characters Ji Cheng (纪澄) and Shen Che (沈彻).
-     • 《七星彩》 is COMPLETELY UNRELATED to 《千香》 (Qiān Xiāng / The Eternal Fragrance / พันกลิ่นบุปผา).
-     • NEVER claim that an unconfirmed title or rumor is "associated with" or "is found to be" an existing OST or song in Ju Jingyi's catalog just because syllables sound alike.
-   - HANDLING UNCONFIRMED DRAMAS & MELON ACCOUNTS (吃瓜 / 选角传闻):
-     • When asked why netizens are interested in an unconfirmed project like 《七星彩》, explain the actual facts:
-       1) Production & Origin: Big S+ budget by Youku and Stellar Media (the acclaimed studio behind "Love Between Fairy and Devil").
-       2) The Buzz / Why Netizens Care: High-profile Casting Rumors (选角瓜) circulating on Weibo, Douban, and Xiaohongshu discussing multiple top visual actresses (often floating Ju Jingyi, Lu Yuxiao, Song Zu'er, etc.) for the clever and enchanting female lead Ji Cheng.
-       3) Status: Still in preparation / unconfirmed by official studio or platform announcements.
-       4) Clear distinction: Remind the user that this is an unconfirmed industry project and distinct from her confirmed works like "The Eternal Fragrance (千香)" and "Veil of Shadows (月鳞绮纪)".
-   - NEVER FABRICATE FICTIONAL CONNECTIONS:
-     • If an entity is not found in the verified catalog, use web_search to find true facts or tell the user clearly that it is not in the verified official works. NEVER invent a relationship between two unrelated titles.`,
+
+    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.`,
   }
 };