kiku-agent 1.0.0 → 1.0.4

package/server/agent/config.js

@@ -1,90 +1,264 @@
-export const config = {
-  lmStudio: {
-    baseUrl: process.env.LMSTUDIO_BASE_URL || process.env.OPENAI_BASE_URL || 'http://127.0.0.1:1234/v1',
-    model: 'google/gemma-4-e4b',
-    defaultModel: 'google/gemma-4-e4b',
-    temperature: 0.3,
-    maxTokens: 1536,
-    requestTimeoutMs: 180000,
-  },
-
-  agent: {
-    maxIterations: 4,
-    slidingWindowSize: 8,
-    language: 'auto',
-    systemPersona: `You are "Kiku AI" (จวีจิ้งอี AI ผู้ช่วยอัจฉริยะ / 鞠婧祎智能AI助手), an expert AI specialist 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. PROPORTIONAL RESPONSE & GREETINGS:
-   - CASUAL GREETINGS ("Hi", "Hello", "สวัสดี", "你好"): Reply warmly in 1-2 sentences. DO NOT call tools or dump catalogs.
-   - SHORT QUESTIONS: Give direct, concise 1-3 sentence answer.
-   - BROAD REQUESTS: Provide structured, well-organized list with key details and clickable links.
-
-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 (USE TOOLS TO GATHER FACTS, THEN ANSWER):
-   - Music videos & stages ➔ get_music_videos or get_media_links
-   - Songs, OSTs, Singles ➔ search_discography or get_media_links
-   - Drama works & trailers ➔ search_works or get_work_detail
-   - Profile & fandom ➔ get_profile_and_fandom
-   - Brand endorsements ➔ get_brand_endorsements
-   - Breaking news & external facts ➔ web_search or web_extract (preferred for multi-source research)
-   - Deep research on a topic ➔ web_extract (search + auto-fetch top results)
-   - Read a specific webpage ➔ fetch_webpage (cheerio-powered extraction)
-   - Fetch REST API / JSON data ➔ fetch_json
-   - Read local project files ➔ read_local_file
-   - Browse directory structure ➔ list_directory
-   - Visual screenshot ➔ screenshot_webpage
-   - If local tools return insufficient results, 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. CONCISE & SMART RESPONSE QUALITY:
-   - Match the depth of your answer to what the user asked.
-   - Do not dump the entire database unless specifically requested.
-   - Start directly with the answer — no template greetings like "Hello!" or "I searched...".
-   - Keep the interface visually restrained; omit emoji unless one clearly improves recognition of the topic.
-
-9. PROACTIVE MUSIC INVITATION:
-   - When discussing a specific song/MV/OST, naturally ask if the user wants to listen.
-- Example: "เพลง FIND THE WAY จังหวะทรงพลังมากเลยค่ะ! อยากให้ Kiku เปิดให้ฟังมั้ยคะ?"
-   - If user agrees → call play_music. If user says "Stop" → call stop_music.`,
-  }
-};
+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).' },
+    ],
+  },
+  openai: {
+    id: 'openai',
+    name: 'OpenAI Cloud',
+    baseUrl: process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY || '',
+    defaultModel: process.env.OPENAI_MODEL || 'gpt-4o-mini',
+    isLocal: false,
+    envKey: 'OPENAI_API_KEY',
+    docUrl: 'https://platform.openai.com/docs',
+    apiRefUrl: 'https://platform.openai.com/docs/api-reference',
+    pricingSummary: 'Pay-per-token (gpt-4o-mini: ~$0.15/1M in, $0.60/1M out)',
+    features: ['tools', 'streaming', 'vision', 'reasoning', 'system-prompt'],
+    recommendedModels: [
+      { id: 'gpt-4o-mini', name: 'GPT-4o Mini', tier: 'ultra-cheap', cost: '$0.15 / 1M in', context: '128k', hasTools: true, description: 'Recommended default. Fast, intelligent, and highly cost-effective with tool use.' },
+      { id: 'gpt-4o', name: 'GPT-4o', tier: 'flagship', cost: '$2.50 / 1M in', context: '128k', hasTools: true, description: 'OpenAI flagship multimodal model for complex multimodal & reasoning tasks.' },
+      { id: 'o3-mini', name: 'o3 Mini', tier: 'reasoning', cost: '$1.10 / 1M in', context: '200k', hasTools: true, description: 'Fast, cost-efficient reasoning model with function calling capabilities.' },
+      { id: 'o1-mini', name: 'o1 Mini', tier: 'reasoning', cost: '$1.10 / 1M in', context: '128k', hasTools: true, description: 'Reasoning model specialized for complex STEM logic 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: process.env.OPENROUTER_MODEL || 'google/gemini-2.5-flash',
+    extraHeaders: {
+      'HTTP-Referer': 'https://jujingyi-kikuuu.vercel.app/',
+      'X-Title': 'Kiku Agent',
+    },
+    isLocal: false,
+    envKey: 'OPENROUTER_API_KEY',
+    docUrl: 'https://openrouter.ai/docs/quick-start',
+    apiRefUrl: 'https://openrouter.ai/docs/api_reference/overview',
+    pricingSummary: 'Universal aggregator with free tiers & flexible pay-as-you-go',
+    features: ['universal-routing', 'tools', 'streaming', 'free-tier', 'fallback'],
+    recommendedModels: [
+      { id: 'google/gemini-2.5-flash', name: 'Gemini 2.5 Flash', tier: 'ultra-cheap', cost: '$0.10 / 1M in', context: '1M', hasTools: true, description: 'Super fast with huge 1M context window and native function calling.' },
+      { id: 'deepseek/deepseek-chat', name: 'DeepSeek Chat (V3)', tier: 'ultra-cheap', cost: '$0.14 / 1M in', context: '64k', hasTools: true, description: 'DeepSeek-V3 671B MoE via OpenRouter at ultra-low price.' },
+      { id: 'deepseek/deepseek-r1', name: 'DeepSeek Reasoner (R1)', tier: 'reasoning', cost: '$0.55 / 1M in', context: '64k', hasTools: false, description: 'Full DeepSeek-R1 reasoning with Chain-of-Thought output.' },
+      { id: 'meta-llama/llama-3.3-70b-instruct', name: 'Llama 3.3 70B Instruct', tier: 'balanced', cost: '$0.40 / 1M in', context: '128k', hasTools: true, description: 'State-of-the-art open-weights flagship model.' },
+      { id: 'openai/gpt-4o-mini', name: 'GPT-4o Mini', tier: 'ultra-cheap', cost: '$0.15 / 1M in', context: '128k', hasTools: true, description: 'OpenAI mini model routed via OpenRouter.' },
+      { id: 'qwen/qwen-2.5-72b-instruct', name: 'Qwen 2.5 72B Instruct', tier: 'balanced', cost: '$0.35 / 1M in', context: '128k', hasTools: true, description: 'Top-tier open-weights multilingual and coding model.' },
+      { id: 'meta-llama/llama-3.1-8b-instruct:free', name: 'Llama 3.1 8B (Free)', tier: 'free', cost: '$0.00', context: '128k', hasTools: true, description: 'Free tier Llama 3.1 8B on OpenRouter.' },
+    ],
+  },
+  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: process.env.GROQ_MODEL || 'llama-3.3-70b-versatile',
+    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 (llama-3.1-8b: $0.05/1M, llama-3.3-70b: $0.59/1M)',
+    features: ['lpu-speed', 'tools', 'streaming', 'openai-compatible'],
+    recommendedModels: [
+      { id: 'llama-3.3-70b-versatile', name: 'Llama 3.3 70B Versatile', tier: 'balanced', cost: '$0.59 / 1M in', context: '128k', hasTools: true, description: 'Recommended default. 70B flagship quality with fast LPU speed and tool use.' },
+      { id: 'llama-3.1-8b-instant', name: 'Llama 3.1 8B Instant', tier: 'ultra-cheap', cost: '$0.05 / 1M in', context: '128k', hasTools: true, description: 'Blazing fast (~800 tokens/s) and ultra-low cost for quick inquiries.' },
+      { id: 'gpt-oss-120b', name: 'GPT-OSS 120B', tier: 'balanced', cost: '$0.59 / 1M in', context: '128k', hasTools: true, description: 'Open-weights 120B flagship model running with ultra-fast Groq LPU inference.' },
+      { id: 'mixtral-8x7b-32768', name: 'Mixtral 8x7B', tier: 'cheap', cost: '$0.24 / 1M in', context: '32k', hasTools: true, description: 'Mistral MoE architecture with 32k context.' },
+      { id: 'gemma2-9b-it', name: 'Gemma 2 9B IT', tier: 'cheap', cost: '$0.20 / 1M in', context: '8k', hasTools: true, description: 'Google Gemma 2 on Groq LPU hardware.' },
+    ],
+  },
+  deepseek: {
+    id: 'deepseek',
+    name: 'DeepSeek Cloud',
+    baseUrl: process.env.DEEPSEEK_BASE_URL || 'https://api.deepseek.com/v1',
+    apiKey: process.env.DEEPSEEK_API_KEY || '',
+    defaultModel: process.env.DEEPSEEK_MODEL || 'deepseek-chat',
+    isLocal: false,
+    envKey: 'DEEPSEEK_API_KEY',
+    docUrl: 'https://api-docs.deepseek.com',
+    apiRefUrl: 'https://api-docs.deepseek.com/api/create-chat-completion',
+    pricingSummary: 'Ultra-low cost (deepseek-chat: $0.14 cached / $0.27 uncached / 1M)',
+    features: ['deepseek-v3', 'deepseek-r1-reasoning', 'tools', 'streaming', 'context-cache'],
+    recommendedModels: [
+      { id: 'deepseek-chat', name: 'DeepSeek Chat (V3)', tier: 'ultra-cheap', cost: '$0.14-$0.27 / 1M in', context: '64k', hasTools: true, description: 'Recommended default. DeepSeek-V3 671B MoE, top-tier reasoning, tool calling, fast & ultra-cheap.' },
+      { id: 'deepseek-reasoner', name: 'DeepSeek Reasoner (R1)', tier: 'reasoning', cost: '$0.55 / 1M in', context: '64k', hasTools: false, description: 'DeepSeek-R1 full Chain-of-Thought reasoning with native thinking output.' },
+    ],
+  },
+  gemini: {
+    id: 'gemini',
+    name: 'Google Gemini Cloud',
+    baseUrl: process.env.GEMINI_BASE_URL || 'https://generativelanguage.googleapis.com/v1beta/openai/',
+    apiKey: process.env.GEMINI_API_KEY || '',
+    defaultModel: process.env.GEMINI_MODEL || 'gemini-2.5-flash',
+    isLocal: false,
+    envKey: 'GEMINI_API_KEY',
+    docUrl: 'https://ai.google.dev/docs',
+    apiRefUrl: 'https://ai.google.dev/api',
+    pricingSummary: 'Ultra-cheap (gemini-2.5-flash: $0.10/1M in, $0.40/1M out)',
+    features: ['1m-context', 'multimodal', 'tools', 'streaming', 'thinking'],
+    recommendedModels: [
+      { id: 'gemini-2.5-flash', name: 'Gemini 2.5 Flash', tier: 'ultra-cheap', cost: '$0.10 / 1M in', context: '1M', hasTools: true, description: 'Recommended default. Advanced reasoning and thinking capabilities with 1M context.' },
+      { id: 'gemini-2.5-flash-lite', name: 'Gemini 2.5 Flash Lite', tier: 'lowest-cost', cost: '$0.075 / 1M in', context: '1M', hasTools: true, description: 'Cost-optimized 2.5 lightweight model for high volume queries.' },
+      { id: 'gemini-2.5-pro', name: 'Gemini 2.5 Pro', tier: 'flagship', cost: '$1.25 / 1M in', context: '2M', hasTools: true, description: 'Deep reasoning and 2M context for complex multimodal analysis.' },
+      { id: 'gemini-3.1-pro', name: 'Gemini 3.1 Pro', tier: 'flagship', cost: '$1.50 / 1M in', context: '2M', hasTools: true, description: 'Next-gen Gemini 3.1 flagship with state-of-the-art coding and multimodal reasoning.' },
+    ],
+  },
+  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>.' },
+    ],
+  },
+};
+
+export function resolveDefaultProvider() {
+  const explicit = process.env.LLM_PROVIDER?.toLowerCase();
+  if (explicit && CLOUD_PROVIDERS[explicit]) return explicit;
+
+  if (process.env.OPENROUTER_API_KEY) return 'openrouter';
+  if (process.env.OPENAI_API_KEY) return 'openai';
+  if (process.env.GEMINI_API_KEY) return 'gemini';
+  if (process.env.DEEPSEEK_API_KEY) return 'deepseek';
+  if (process.env.GROQ_API_KEY) 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 || []) : [];
+}
+
+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: 1536,
+    requestTimeoutMs: 180000,
+  },
+
+  agent: {
+    maxIterations: 4,
+    slidingWindowSize: 8,
+    language: 'auto',
+    systemPersona: `You are "Kiku AI" (จวีจิ้งอี AI ผู้ช่วยอัจฉริยะ / 鞠婧祎智能AI助手), an expert AI specialist 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. PROPORTIONAL RESPONSE & GREETINGS:
+   - CASUAL GREETINGS ("Hi", "Hello", "สวัสดี", "你好"): Reply warmly in 1-2 sentences. DO NOT call tools or dump catalogs.
+   - SHORT QUESTIONS: Give direct, concise 1-3 sentence answer.
+   - BROAD REQUESTS: Provide structured, well-organized list with key details and clickable links.
+
+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 (USE TOOLS TO GATHER FACTS, THEN ANSWER):
+   - Music videos & stages ➔ get_music_videos or get_media_links
+   - Songs, OSTs, Singles ➔ search_discography or get_media_links
+   - Drama works & trailers ➔ search_works or get_work_detail
+   - Profile & fandom ➔ get_profile_and_fandom
+   - Brand endorsements ➔ get_brand_endorsements
+   - Breaking news & external facts ➔ web_search or web_extract (preferred for multi-source research)
+   - Deep research on a topic ➔ web_extract (search + auto-fetch top results)
+   - Read a specific webpage ➔ fetch_webpage (cheerio-powered extraction)
+   - Fetch REST API / JSON data ➔ fetch_json
+   - Read local project files ➔ read_local_file
+   - Browse directory structure ➔ list_directory
+   - Visual screenshot ➔ screenshot_webpage
+   - If local tools return insufficient results, 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. CONCISE & SMART RESPONSE QUALITY:
+   - Match the depth of your answer to what the user asked.
+   - Do not dump the entire database unless specifically requested.
+   - Start directly with the answer — no template greetings like "Hello!" or "I searched...".
+   - Keep the interface visually restrained; omit emoji unless one clearly improves recognition of the topic.
+
+9. PROACTIVE MUSIC INVITATION:
+   - When discussing a specific song/MV/OST, naturally ask if the user wants to listen.
+   - Example: "เพลง FIND THE WAY จังหวะทรงพลังมากเลยค่ะ! อยากให้ Kiku เปิดให้ฟังมั้ยคะ?"
+   - If user agrees → call play_music. If user says "Stop" → call stop_music.`,
+  }
+};

package/server/agent/contextCompactor.js

@@ -0,0 +1,79 @@
+export function estimateTokenCount(textOrMessages) {
+  if (!textOrMessages) return 0;
+  if (typeof textOrMessages === 'string') {
+    return Math.ceil(textOrMessages.length / 3.5);
+  }
+  if (Array.isArray(textOrMessages)) {
+    let chars = 0;
+    for (const msg of textOrMessages) {
+      if (typeof msg.content === 'string') chars += msg.content.length;
+      if (msg.tool_calls) chars += JSON.stringify(msg.tool_calls).length;
+    }
+    return Math.ceil(chars / 3.5);
+  }
+  return 0;
+}
+
+export class ContextCompactor {
+  constructor(options = {}) {
+    this.maxTokens = options.maxTokens || 6000;
+    this.keepRecentMessages = options.keepRecentMessages || 6;
+  }
+
+  summarizeHistorySync(messages = []) {
+    if (!messages || messages.length === 0) return '';
+    const points = [];
+    for (const msg of messages) {
+      if (msg.role === 'user' && typeof msg.content === 'string' && msg.content.trim()) {
+        const text = msg.content.slice(0, 100).replace(/\n+/g, ' ').trim();
+        points.push(`User asked: "${text}"`);
+      } else if (msg.role === 'assistant' && typeof msg.content === 'string' && msg.content.trim()) {
+        const text = msg.content.slice(0, 120).replace(/\n+/g, ' ').trim();
+        points.push(`Assistant covered: "${text}"`);
+      } else if (msg.role === 'tool') {
+        const toolName = msg.name || 'tool';
+        points.push(`Verified via ${toolName}`);
+      }
+    }
+    return points.slice(-8).join(' | ');
+  }
+
+  compact(conversationHistory = [], options = {}) {
+    if (!Array.isArray(conversationHistory) || conversationHistory.length <= this.keepRecentMessages + 1) {
+      return conversationHistory;
+    }
+
+    const currentTokens = estimateTokenCount(conversationHistory);
+    const maxTokens = options.maxTokens || this.maxTokens;
+    const keepRecent = options.keepRecentMessages || this.keepRecentMessages;
+
+    if (currentTokens <= maxTokens && conversationHistory.length <= keepRecent + 2) {
+      return conversationHistory;
+    }
+
+    const systemMessage = conversationHistory[0]?.role === 'system' ? conversationHistory[0] : null;
+    const nonSystemMessages = systemMessage ? conversationHistory.slice(1) : conversationHistory;
+
+    if (nonSystemMessages.length <= keepRecent) {
+      return conversationHistory;
+    }
+
+    const olderMessages = nonSystemMessages.slice(0, -keepRecent);
+    const recentMessages = nonSystemMessages.slice(-keepRecent);
+
+    const summaryText = this.summarizeHistorySync(olderMessages);
+    const summaryContextMessage = {
+      role: 'system',
+      content: `[CONVERSATION CONTEXT SUMMARY OF EARLIER MESSAGES: ${summaryText}]`
+    };
+
+    const compacted = [];
+    if (systemMessage) compacted.push(systemMessage);
+    if (summaryText) compacted.push(summaryContextMessage);
+    compacted.push(...recentMessages);
+
+    return compacted;
+  }
+}
+
+export const contextCompactor = new ContextCompactor();

package/server/agent/doctor.js

@@ -0,0 +1,69 @@
+import { promises as fs } from 'node:fs';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { KIKU_DATA_DIR } from './appPaths.js';
+
+async function optionalImport(name) {
+  try { await import(name); return true; } catch { return false; }
+}
+
+function commandAvailable(command, args = ['--version']) {
+  return new Promise(resolve => {
+    let settled = false;
+    const child = spawn(command, args, { stdio: 'ignore', windowsHide: true });
+    const finish = available => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(available);
+    };
+    const timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch {}
+      finish(false);
+    }, 3000);
+    child.once('error', () => finish(false));
+    child.once('close', code => finish(code === 0));
+  });
+}
+
+async function checkDataDirectory() {
+  const probe = path.join(KIKU_DATA_DIR, `.write-test-${process.pid}`);
+  try {
+    await fs.mkdir(KIKU_DATA_DIR, { recursive: true, mode: 0o700 });
+    await fs.writeFile(probe, 'ok', { mode: 0o600 });
+    await fs.unlink(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+import { getGpuMetrics } from './gpuMetrics.js';
+
+export async function runDoctor(options = {}) {
+  const client = options.client;
+  const [dataWritable, speaker, ffmpegStatic, fluentFfmpeg, ytDlp, lm, gpu] = await Promise.all([
+    checkDataDirectory(),
+    optionalImport('speaker'),
+    optionalImport('ffmpeg-static'),
+    optionalImport('fluent-ffmpeg'),
+    commandAvailable(process.env.KIKU_YTDLP || 'yt-dlp'),
+    client ? client.checkConnection() : Promise.resolve({ connected: false, models: [] }),
+    getGpuMetrics().catch(() => ({ available: false })),
+  ]);
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  const checks = [
+    { id: 'node', required: true, ok: nodeMajor >= 20, detail: `Node ${process.versions.node} (requires >=20)` },
+    { id: 'data', required: true, ok: dataWritable, detail: KIKU_DATA_DIR },
+    { id: 'gpu', required: false, ok: Boolean(gpu.available), detail: gpu.available && gpu.primary ? `${gpu.primary.name} (${gpu.primary.totalGb} GB VRAM${gpu.primary.driverVersion !== 'N/A' ? `, Driver ${gpu.primary.driverVersion}` : ''})` : 'CPU fallback / no dedicated acceleration detected' },
+    { id: 'lmstudio', required: false, ok: Boolean(lm.connected), detail: lm.connected ? `${lm.models?.length || 0} loaded model(s)` : 'offline; catalog-only mode is available' },
+    { id: 'ffmpeg', required: false, ok: ffmpegStatic && fluentFfmpeg, detail: 'audio add-on only; intentionally not installed with the core CLI' },
+    { id: 'speaker', required: false, ok: speaker, detail: 'native audio add-on only; intentionally not installed with the core CLI' },
+    { id: 'yt-dlp', required: false, ok: ytDlp, detail: 'recommended for YouTube search and playback' },
+  ];
+  return {
+    ok: checks.every(check => !check.required || check.ok),
+    checks,
+    dataDir: KIKU_DATA_DIR,
+  };
+}