kiku-agent 1.0.11 → 1.2.0

package/server/agent/agentCore.js

@@ -1,32 +1,61 @@
-import { config } from './config.js';
-import { toolsSchema, executeTool, prepareToolArguments } from './tools.js';
-import { LLMClient, LMStudioClient } from './llmClient.js';
-import { AgentSession } from './session.js';
-import { AgentMemory } from './memory.js';
 import { AgentStateMachine, AgentStates } from './agentState.js';
-import { eventBus, Events } from './eventBus.js';
-import { sanitizeQuery, isLikelySafe } from './sanitizer.js';
+import { config } from './config.js';
+import { contextCompactor } from './contextCompactor.js';
 import { createAbortError, isAbortError } from './errors.js';
-import { ResearchSubagent } from './subagent.js';
+import { Events, eventBus } from './eventBus.js';
+import { AgentJobManager } from './jobManager.js';
+import { LLMClient } from './llmClient.js';
+import { McpClientManager } from './mcpClient.js';
+import { AgentMemory } from './memory.js';
 import { ResearchOrchestrator } from './research.js';
+import { sanitizeQuery, sanitizeResponse } from './sanitizer.js';
+import { AgentSession } from './session.js';
+import { ResearchSubagent } from './subagent.js';
 import { SuggestionEngine } from './suggestions.js';
-import { McpClientManager } from './mcpClient.js';
 import { DynamicToolRouter } from './toolRouter.js';
-import { contextCompactor } from './contextCompactor.js';
-import { AgentJobManager } from './jobManager.js';
+import { executeTool, prepareToolArguments, toolsSchema, isBuiltinTool } from './tools.js';
+import { detectAmbiguities, isQueryTooVague, emitClarifyingQuestions, calculateConfidence, generateClarifyingQuestions, buildClarificationContext } from './clarifyingQuestions.js';
+import { ClarificationAnalytics, ClarificationConfig } from './clarificationAnalytics.js';
+import { calculateTokenCost } from './telemetry.js';
+import { extractCitations, resolveCitationReference } from './citations.js';
 
 export function detectDominantLanguage(text) {
   if (!text || typeof text !== 'string') return 'th';
 
-  const thaiMatches = text.match(/[\u0E00-\u0E7F]/g) || [];
+  const clean = text
+    .replace(/\[SYSTEM\s+[A-Z]+:[^\]]*\]/gi, '')
+    .replace(/\[SYSTEM:[^\]]*\]/gi, '')
+    .replace(/\[SYSTEM\s+INSTRUCTION:[^\]]*\]/gi, '')
+    .replace(/\[SYSTEM\s+DIRECTIVE:[^\]]*\]/gi, '')
+    .replace(/^User Question:\s*/gim, '')
+    .trim();
+
+  const targetText = clean || text;
+
+  const thaiMatches = targetText.match(/[\u0E00-\u0E7F]/g) || [];
   const thaiCount = thaiMatches.length;
 
-  const chineseMatches = text.match(/[\u4E00-\u9FA5]/g) || [];
+  const chineseMatches = targetText.match(/[\u4E00-\u9FA5]/g) || [];
   const chineseCount = chineseMatches.length;
 
-  const englishMatches = text.match(/[a-zA-Z]+/g) || [];
+  const kanaMatches = targetText.match(/[\u3040-\u30FF]/g) || [];
+  const kanaCount = kanaMatches.length;
+
+  const hangulMatches = targetText.match(/[\uAC00-\uD7AF]/g) || [];
+  const hangulCount = hangulMatches.length;
+
+  const englishMatches = targetText.match(/[a-zA-Z]+/g) || [];
   const englishCount = englishMatches.join('').length;
 
+
+  if (kanaCount > 0) {
+    return 'ja';
+  }
+
+  if (hangulCount > 0 && hangulCount >= thaiCount && hangulCount >= chineseCount && hangulCount >= englishCount) {
+    return 'ko';
+  }
+
   if (thaiCount >= chineseCount && thaiCount >= englishCount && thaiCount > 0) {
     return 'th';
   } else if (chineseCount > thaiCount && chineseCount >= englishCount && chineseCount > 0) {
@@ -49,8 +78,11 @@ function stableToolSignature(toolName, args) {
   return `${toolName}:${JSON.stringify(sortValue(args || {}))}`;
 }
 
-export class KikuAgent {
-  constructor(options = {}) {
+export class KikuAgent {
+  constructor(options = {}) {
+    this.allowedToolNames = options.allowedToolNames
+      ? new Set(Array.from(options.allowedToolNames, String))
+      : null;
     this.client = options.client || new LLMClient({
       provider: options.provider || config.activeProvider,
       baseUrl: options.baseUrl,
@@ -59,20 +91,29 @@ export class KikuAgent {
     });
     this.maxIterations = options.maxIterations || config.agent.maxIterations || 5;
     this.slidingWindowSize = options.slidingWindowSize || config.agent.slidingWindowSize || 8;
-    this.session = new AgentSession({ thinkingMode: options.thinkingMode || 'hide' });
-    this.memory = new AgentMemory();
+    this.session = new AgentSession({
+      thinkingMode: options.thinkingMode || 'hide',
+      sessionId: options.sessionId,
+      storageKey: options.sessionStorageKey,
+      storageFile: options.sessionStorageFile,
+      persistence: options.sessionPersistence !== false,
+    });
+    this.memory = options.memory || new AgentMemory();
     this.mcpManager = options.mcpManager || new McpClientManager();
     this.router = new DynamicToolRouter(this.getAllToolsSchema());
     this.research = new ResearchOrchestrator({ client: this.client });
     this.suggestions = new SuggestionEngine({ client: this.client, memory: this.memory });
     this.jobs = new AgentJobManager();
+    this.clarifyConfig = options.clarifyConfig || new ClarificationConfig();
+    this.clarifyAnalytics = options.clarifyAnalytics || new ClarificationAnalytics();
     this.systemPrompt = this.buildSystemPrompt();
     this.initHistory();
     this.restoredMessageCount = 0;
+    this.lastCitations = [];
 
     this.stateMachine = new AgentStateMachine();
 
-    this.stateMachine.on('transition', ({ from, to }) => {
+    this.stateMachine.on('transition', ({ to }) => {
       eventBus.emit(Events.AGENT_STATE_CHANGE, {
         state: to,
         label: this.stateMachine.label,
@@ -85,7 +126,7 @@ export class KikuAgent {
   }
 
   async _init() {
-    await this.memory.load();
+    if (!this.memory._loaded) await this.memory.load();
     await this.loadSession();
     if (this.mcpManager && typeof this.mcpManager.loadPersistedServers === 'function') {
       try {
@@ -171,6 +212,141 @@ export class KikuAgent {
     return this.jobs.clear();
   }
 
+  async _handleClarifyingQuestions(query, lang, queryId, callbacks) {
+    if (!callbacks.onClarifyingQuestions || !callbacks.onClarifyingAnswer) {
+      return null;
+    }
+
+    const clarifyConfig = this.clarifyConfig.getConfig();
+    if (!clarifyConfig.enabled) {
+      return null;
+    }
+
+  
+    const hasPriorClarification = (this._clarificationAskedCount && this._clarificationAskedCount >= 1) ||
+      (this.conversationHistory && this.conversationHistory.some(m => m.content && (m.content.includes('[SYSTEM CLARIFICATION]') || m.content.includes('CLARIFICATION:'))));
+    if (hasPriorClarification) {
+      return null;
+    }
+
+    if (isQueryTooVague(query)) {
+      return null;
+    }
+
+    if (query.includes('[SYSTEM CLARIFICATION]') || query.includes('CLARIFICATION:')) {
+      return null;
+    }
+
+    const ambiguities = detectAmbiguities(query, lang);
+    const confidence = calculateConfidence(query, ambiguities);
+    const threshold = clarifyConfig.confidenceThreshold;
+
+  
+    const CROSS_CATEGORY_PRIORITIES = ['media_type', 'career_phase', 'specific_work', 'timeframe', 'comparison'];
+    const highImpactAmbiguities = ambiguities.filter(a => CROSS_CATEGORY_PRIORITIES.includes(a.category));
+
+    const shouldAsk = (confidence.score < threshold || confidence.shouldAsk) && highImpactAmbiguities.length > 0;
+
+    eventBus.emit(Events.AGENT_CLARIFYING_QUESTIONS, {
+      queryId,
+      confidence,
+      threshold,
+      shouldAsk,
+      timestamp: Date.now(),
+    });
+
+    if (!shouldAsk || highImpactAmbiguities.length === 0) {
+      return null;
+    }
+
+  
+    
+    let questionsToAsk = null;
+    try {
+      questionsToAsk = await generateClarifyingQuestions(query, lang, {
+        conversationHistory: this.conversationHistory,
+        client: this.client,
+        maxQuestions: 4,
+        detectedAmbiguities: highImpactAmbiguities,
+      });
+    } catch {
+     
+    }
+
+    if (!questionsToAsk || questionsToAsk.length === 0) {
+      questionsToAsk = highImpactAmbiguities.slice(0, 4).map(q => ({
+        ...q,
+        options: (q.options || []).slice(0, 4)
+      }));
+    } else {
+      questionsToAsk = questionsToAsk.slice(0, 5).map(q => ({
+        ...q,
+        options: (q.options || []).slice(0, 4)
+      }));
+    }
+
+    this._clarificationAskedCount = (this._clarificationAskedCount || 0) + 1;
+
+    const startTime = Date.now();
+    this.clarifyAnalytics.recordClarificationStart(queryId, questionsToAsk, confidence.score);
+
+    try {
+      eventBus.emit(Events.AGENT_CLARIFYING_QUESTIONS, {
+        queryId,
+        questions: questionsToAsk,
+        confidence,
+        threshold,
+        timestamp: Date.now(),
+      });
+
+      callbacks.onClarifyingQuestions(questionsToAsk, queryId);
+
+      const answers = await Promise.race([
+        callbacks.onClarifyingAnswer(queryId),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('CLARIFY_TIMEOUT')), clarifyConfig.timeoutMs)
+        ),
+      ]);
+
+      const responseTimeMs = Date.now() - startTime;
+      const { parseClarifyingAnswers } = await import('./clarifyingQuestions.js');
+      const result = parseClarifyingAnswers(answers, questionsToAsk);
+
+      if (result.summary.includes('skip')) {
+        this.clarifyAnalytics.recordClarificationSkipped(queryId);
+      } else {
+        this.clarifyAnalytics.recordClarificationAnswer(queryId, result.answers, 1, responseTimeMs);
+      }
+
+      eventBus.emit(Events.AGENT_CLARIFYING_ANSWER, {
+        queryId,
+        answers: result.answers,
+        summary: result.summary,
+        confidence,
+        threshold,
+        responseTimeMs,
+        timestamp: Date.now(),
+      });
+
+      return result;
+    } catch {
+      this.clarifyAnalytics.recordClarificationTimeout(queryId);
+      return null;
+    }
+  }
+
+  getClarificationAnalytics(options = {}) {
+    return this.clarifyAnalytics.getAnalytics(options);
+  }
+
+  getClarificationConfig() {
+    return this.clarifyConfig.getConfig();
+  }
+
+  updateClarificationConfig(updates) {
+    return this.clarifyConfig.updateConfig(updates);
+  }
+
   initHistory() {
     this.conversationHistory = [
       {
@@ -280,19 +456,74 @@ export class KikuAgent {
     eventBus.emit(Events.SESSION_SAVED, { sessionId: this.session.id });
   }
 
+  async hydrateConversationHistory(messages = [], options = {}) {
+    await this._ready;
+    const alreadyHasConversation = this.conversationHistory?.some(message =>
+      message.role === 'user' || message.role === 'assistant'
+    );
+    if (alreadyHasConversation && options.force !== true) {
+      return { hydrated: false, reason: 'session_already_loaded', messageCount: this.session.messages.length };
+    }
+
+    const maxMessages = Math.max(1, Math.min(Number(options.maxMessages) || 24, 50));
+    const normalized = (Array.isArray(messages) ? messages : [])
+      .slice(-maxMessages)
+      .map(message => {
+        const role = message?.role === 'user' ? 'user' :
+          (message?.role === 'assistant' || message?.role === 'bot' ? 'assistant' : null);
+        const content = String(message?.content ?? message?.text ?? '').trim().slice(0, 6000);
+        return role && content ? { role, content } : null;
+      })
+      .filter(Boolean);
+
+    if (normalized.length === 0) {
+      return { hydrated: false, reason: 'empty_history', messageCount: 0 };
+    }
+
+    const createdAt = new Date();
+    const sessionMessages = normalized.map((message, index) => ({
+      id: `msg_hydrated_${createdAt.getTime()}_${index}`,
+      role: message.role,
+      queryNumber: Math.floor(index / 2) + 1,
+      createdAt,
+      parts: [{ type: 'text', content: message.content }]
+    }));
+    const userMessageCount = normalized.filter(message => message.role === 'user').length;
+
+    this.session.restoreFromSnapshot({
+      id: options.sessionId || this.session.id,
+      createdAt,
+      thinkingMode: this.session.thinkingMode,
+      messages: sessionMessages,
+      stats: {
+        totalQueries: userMessageCount,
+        totalToolCalls: 0,
+        totalDurationMs: 0,
+      }
+    });
+    this.initHistory();
+    normalized.forEach(message => this.conversationHistory.push(message));
+    this.restoredMessageCount = normalized.length;
+    await this.saveSession();
+
+    return { hydrated: true, messageCount: normalized.length };
+  }
+
   applySlidingWindow() {
     if (this.conversationHistory.length > this.slidingWindowSize + 1) {
       this.conversationHistory = contextCompactor.compact(this.conversationHistory, {
-        maxTokens: 6000,
+        maxTokens: 24000,
         keepRecentMessages: this.slidingWindowSize,
       });
     }
   }
 
-  getAllToolsSchema() {
-    const mcpTools = this.mcpManager ? this.mcpManager.getToolsSchema() : [];
-    return [...toolsSchema, ...mcpTools];
-  }
+  getAllToolsSchema() {
+    const mcpTools = this.mcpManager ? this.mcpManager.getToolsSchema() : [];
+    const allTools = [...toolsSchema, ...mcpTools];
+    if (!this.allowedToolNames) return allTools;
+    return allTools.filter(tool => this.allowedToolNames.has(tool.function?.name));
+  }
 
   async connectMcp(name, serverConfig) {
     const result = await this.mcpManager.connect(name, serverConfig);
@@ -357,6 +588,7 @@ export class KikuAgent {
 
   buildSystemPrompt() {
     const allTools = this.getAllToolsSchema();
+    const today = new Date().toISOString().slice(0, 10);
     const toolsSummary = allTools.map(t => {
       const f = t.function;
       const paramKeys = Object.keys(f.parameters?.properties || {}).join(', ');
@@ -390,25 +622,49 @@ ${toolsSummary}
 
 3. FACT ACCURACY & NO DUPLICATION:
    - Always use tools to verify facts before answering. Do NOT hallucinate.
-   - Current year is 2026. Prioritize 2026/2025 projects.
+   - Current date is ${today}. Prioritize current and recent projects when relevant.
    - Never repeat the same statement. Sort newest first.
 
-4. RESPONSE STYLE:
-   - NEVER start with template greetings — dive DIRECTLY into the answer.
-   - Format with Markdown headers (###), bold (**text**), bullet points (•).
-   - Emoji are optional: use at most one contextually relevant emoji per response and never repeat them across headings or bullets.
-   - Match answer depth to what the user asked.
-
-5. SMART TOOL SELECTION:
-   - Videos/stages ➔ get_music_videos or get_media_links
-   - Songs/OSTs ➔ search_discography or get_media_links
-   - Dramas ➔ search_works or get_work_detail
+3A. CONVERSATION TOPIC ANCHOR:
+   - Resolve short or ambiguous follow-ups (for example "ทำไมน่าจับตามอง?", "งานนี้", "why is it notable?") against the most recent user topic and assistant answer.
+   - The current follow-up inherits that topic. Do not default the subject to Ju Jingyi merely because the persona or knowledge base focuses on her.
+   - A persona changes voice and tone only; it never replaces the user's subject.
+   - If the reference remains genuinely ambiguous after reading recent history, ask one focused clarification question instead of guessing.
+
+3B. FUTURE-EVENT CLAIM SAFETY:
+   - Treat any event after today's date as scheduled or reported, not completed fact.
+   - Never assert an exact future date, invitation, guest list, or attendance without checking a current official source with a live web tool.
+   - Never carry a date, guest list, or attendance status from one annual edition into another year.
+   - When official confirmation is unavailable, say clearly that the detail is unconfirmed and subject to change.
+
+4. RESPONSE STYLE:
+   - NEVER start with template greetings — dive DIRECTLY into the answer.
+   - Format with Markdown headers (###), bold (**text**), bullet points (•).
+   - Emoji are optional: use at most one contextually relevant emoji per response and never repeat them across headings or bullets.
+   - Match answer depth to what the user asked.
+   - Separate catalog facts from interpretation. Clearly frame acting observations as analysis unless a cited review supports them.
+   - Do not infer that newer means deeper, more realistic, or better acted. Compare concrete role demands, narrative agency, genre, and verified scenes instead.
+   - Omit catalog ratings from analytical conclusions unless the tool output names the rating source and scale.
+   - Avoid unsupported superlatives or career verdicts (for example "unrivalled", "top-tier", or "completely transcended idol status").
+   - In Blossom (花间令): Ju Jingyi portrays Yang Caiwei's identity in Shangguan Zhi's appearance after the face-swap premise; do not describe this as two unrelated roles throughout the series.
+   - The Legend of White Snake (新白娘子传奇): Bai Suzhen is the white-snake spirit in human form and Xu Xian is the human man; never reverse this relationship.
+   - On an explicit continuation, answer the new angle without restating the previous response.
+
+5. SMART TOOL SELECTION (MANDATORY LOCAL DATABASE FIRST):
+   - ALWAYS call LOCAL built-in database tools FIRST. They query the rich, local catalog database directly in-process and are the authoritative source of truth.
+   - Videos/stages/audio ➔ search_discography, get_music_videos, get_media_links, play_music
+   - Songs/OSTs ➔ search_discography
+   - Dramas/roles ➔ search_works, get_work_detail, get_character_roles
+   - Profile/fandom ➔ get_profile_and_fandom
+   - Brands ➔ get_brand_endorsements
+   - Awards ➔ get_awards
+   - Career timeline ➔ get_career_timeline
+   - Local files ➔ read_local_file, list_directory, get_system_stats
+   - MCP tools (mcp_*) ➔ Secondary only; only invoke when user explicitly mentions MCP (@mcp) or when specialized external services are required.
    - News/external facts ➔ web_search or web_extract
    - Deep multi-source research ➔ web_extract (search + auto-fetch)
    - Read webpage content ➔ fetch_webpage
    - Fetch API/JSON ➔ fetch_json
-   - Local files ➔ read_local_file
-   - Directory listing ➔ list_directory
    - Screenshot ➔ screenshot_webpage
 
 6. AGGRESSIVE WEB SEARCH FALLBACK (CRITICAL):
@@ -429,7 +685,33 @@ ${toolsSummary}
    • Isolated In-Depth Subtask ➔ Call run_subagent with a specific task parameter to delegate an isolated iterative investigation with evidence and tool call tracing.
    • Complex Multi-Faceted Research ➔ Call run_deep_research with question when the user asks an open-ended, complex query that requires parallel multi-worker investigation across catalog, live web sources, and independent verifier with cited sources.
    • Rumors, Cast Leaks & Fact Verification ➔ Call verify_claim with claim when the user asks whether a rumor, statement, or unconfirmed news is true (returns VERIFIED, UNVERIFIED, CONFLICTING, or FALSE).
-   • Teaching / Updating Response Preferences ➔ Call manage_skill with action 'learn' (with instruction), 'list', 'remove' (with skillId), 'clear', 'enable', or 'disable' when the user instructs how they want Kiku to answer in future conversations.`;
+    • Teaching / Updating Response Preferences ➔ Call manage_skill with action 'learn' (with instruction), 'list', 'remove' (with skillId), 'clear', 'enable', or 'disable' when the user instructs how they want Kiku to answer in future conversations.
+
+9. ANTI-HALLUCINATION GUARDRAILS (CRITICAL — MANDATORY COMPLIANCE):
+
+   0. INDEPENDENT VERIFICATION FIRST:
+      - When asked about specific named entities (e.g., upcoming dramas, casts, titles, products, brand deals, real-world releases), do NOT generate an explanation based solely on keyword inference or assumed context.
+      - You MUST cross-reference and verify the exact entity existence using your local catalog tools (search_works, search_discography, get_brand_endorsements, etc.) BEFORE writing the response.
+      - If the local catalog has no match, you MUST call web_search or web_extract to verify externally before responding.
+
+   1. ZERO-ASSUMPTION ON UNVERIFIED ENTITIES:
+      - If the subject/entity cannot be verified with official records (not found in catalog tools AND not found via web_search), explicitly state that no verified record exists.
+      - Strictly avoid fabricating plausible generic narratives (e.g., generic tropes, placeholder plotlines, speculative casting, invented brand partnerships).
+      - NEVER invent drama titles, song names, character roles, brand endorsements, or career milestones that are not backed by tool results.
+
+   2. FALLBACK & UNCERTAINTY PROTOCOL:
+      - If the entity appears to be misspelled, fan fiction, or an unverified rumor, directly flag the discrepancy (including linguistic errors like incorrect Pinyin or romanization) rather than adopting the user's premise as true.
+      - Always prioritize stating "No official information found in the database" over generating a complete but ungrounded description.
+      - If tool results are ambiguous or partial, present only what is confirmed and clearly label uncertain parts as "unverified" or "not confirmed."
+
+   3. SOURCE ATTRIBUTION:
+      - When stating facts, prefer answers that trace back to tool results. If a claim comes from local catalog, you may present it as confirmed data. If from web search, note it as external/recent information.
+      - NEVER present fabricated information as if it were verified catalog data.
+
+   4. SELF-CHECK BEFORE FINAL ANSWER:
+      - Before synthesizing your final response, mentally verify: "Does every factual claim in my answer have a corresponding tool result backing it up?"
+      - If any claim lacks tool evidence, either (a) call the appropriate tool to verify it, or (b) remove it from your answer.
+      - This applies to ALL entity types: dramas, songs, MVs, brands, awards, dates, character names, and career milestones.`;
   }
 
   parseTextToolCalls(content) {
@@ -438,8 +720,7 @@ ${toolsSummary}
     const allTools = this.getAllToolsSchema();
 
     const jsonBlockRegex = /```(?:json)?\s*(\{[\s\S]*?\})\s*```/g;
-    let match;
-    while ((match = jsonBlockRegex.exec(content)) !== null) {
+    for (const match of content.matchAll(jsonBlockRegex)) {
       try {
         const parsed = JSON.parse(match[1]);
         const toolName = parsed.action || parsed.tool || parsed.name || parsed.function;
@@ -458,9 +739,9 @@ ${toolsSummary}
     }
 
     const actionRegex = /Action:\s*([a-zA-Z0-9_]+)\s*\nAction Input:\s*(\{[\s\S]*?\}|[^\n]+)/g;
-    while ((match = actionRegex.exec(content)) !== null) {
+    for (const match of content.matchAll(actionRegex)) {
       const toolName = match[1].trim();
-      let rawInput = match[2].trim();
+      const rawInput = match[2].trim();
       if (allTools.some(t => t.function.name === toolName)) {
         let args = {};
         try {
@@ -506,6 +787,7 @@ ${toolsSummary}
       onReasoningEnd = () => { },
       onToolStart = () => { },
       onToolResult = () => { },
+      onSubagentProgress = () => { },
       onTokenStart = () => { },
       onTokenDelta = () => { },
       onFinalAnswer = () => { },
@@ -527,8 +809,16 @@ ${toolsSummary}
       ];
     }
 
+    let promptForLLMWithGrounding = promptForLLM;
+    if (this.lastCitations && this.lastCitations.length > 0) {
+      const citedRef = resolveCitationReference(promptForLLM, this.lastCitations);
+      if (citedRef) {
+        promptForLLMWithGrounding = `${promptForLLM}\n\n[CONTEXT GROUNDING: User references Citation [${citedRef.id}] "${citedRef.title}" (${citedRef.category || citedRef.type || ''}${citedRef.year ? `, ${citedRef.year}` : ''})]`;
+      }
+    }
+
     this.session.createUserMessage(promptForLLM);
-    const userMessage = { role: 'user', content: promptForLLM };
+    const userMessage = { role: 'user', content: promptForLLMWithGrounding };
     this.conversationHistory.push(userMessage);
 
     const memoryContext = this.memory.buildMemoryContext(promptForLLM);
@@ -542,6 +832,10 @@ ${toolsSummary}
       langInstruction = '[SYSTEM NOTE: User language is Thai. Reply in Thai only.]\n';
     } else if (dominantLang === 'zh') {
       langInstruction = '[SYSTEM NOTE: User language is Chinese. Reply in Chinese only.]\n';
+    } else if (dominantLang === 'ja') {
+      langInstruction = '[SYSTEM NOTE: User language is Japanese. Reply in Japanese only.]\n';
+    } else if (dominantLang === 'ko') {
+      langInstruction = '[SYSTEM NOTE: User language is Korean. Reply in Korean only.]\n';
     } else {
       langInstruction = '[SYSTEM NOTE: User language is English. Reply in English only.]\n';
     }
@@ -552,6 +846,19 @@ ${toolsSummary}
     }
     this.conversationHistory.push({ role: 'system', content: langInstruction });
 
+    const clarifyingResult = await this._handleClarifyingQuestions(
+      promptForLLM,
+      dominantLang,
+      queryId,
+      callbacks
+    );
+    if (clarifyingResult) {
+      this.conversationHistory.push({
+        role: 'user',
+        content: `[SYSTEM CLARIFICATION] ${clarifyingResult.summary}\nOriginal query: ${promptForLLM}`
+      });
+    }
+
     this.applySlidingWindow();
 
     const currentAssistantSessionMsg = this.session.createAssistantMessage({
@@ -559,8 +866,13 @@ ${toolsSummary}
       provider: this.client?.providerName || this.client?.provider || null,
     });
 
+    let queryPromptTokens = 0;
+    let queryCompletionTokens = 0;
+    let queryReasoningTokens = 0;
+
     let currentIteration = 0;
     const toolResultCache = new Map();
+    const toolResultTracker = { notFound: 0, error: 0, success: 0, total: 0, toolNames: [] };
     const activeTools = this.router.routeToolsForQuery(promptForLLM, {
       showAll: callbacks.showAllTools || false,
       includeMcp: true,
@@ -584,6 +896,7 @@ ${toolsSummary}
           messages: this.conversationHistory,
           tools: activeTools,
           temperature: 0.3,
+          maxTokens: 8192,
           stream: true,
           signal,
           onThought: (thoughtChunk) => {
@@ -640,6 +953,12 @@ ${toolsSummary}
         throw new Error(`No response received from ${this.client?.providerName || 'AI provider'}.`);
       }
 
+      if (assistantMessage.usage) {
+        queryPromptTokens += Number(assistantMessage.usage.prompt_tokens || 0);
+        queryCompletionTokens += Number(assistantMessage.usage.completion_tokens || 0);
+        queryReasoningTokens += Number(assistantMessage.usage.reasoning_tokens || 0);
+      }
+
       let toolCalls = assistantMessage.tool_calls || [];
       if (toolCalls.length === 0 && assistantMessage.content) {
         toolCalls = this.parseTextToolCalls(assistantMessage.content);
@@ -660,11 +979,13 @@ ${toolsSummary}
         const totalDurationMs = Date.now() - queryStartTime;
         this.session.stats.totalDurationMs += totalDurationMs;
 
-        const finalAnswer = assistantMessage.content || (
+        const finalAnswer = sanitizeResponse(assistantMessage.content || (
           dominantLang === 'zh' ? "抱歉，无法处理您的回答。" :
-            dominantLang === 'en' ? "Sorry, unable to process a response." :
-              "ขออภัยค่ะ ไม่สามารถประมวลผลคำตอบได้"
-        );
+            dominantLang === 'ja' ? "申し訳ありません、回答を処理できませんでした。" :
+              dominantLang === 'ko' ? "죄송합니다. 답변을 처리할 수 없습니다." :
+                dominantLang === 'en' ? "Sorry, unable to process a response." :
+                  "ขออภัยค่ะ ไม่สามารถประมวลผลคำตอบได้"
+        ));
         onFinalAnswer(finalAnswer, { durationMs: totalDurationMs, language: dominantLang });
         this._extractFactsFromFinalAnswer(finalAnswer);
 
@@ -672,15 +993,30 @@ ${toolsSummary}
         eventBus.emit(Events.AGENT_FINAL_ANSWER, { queryId, answer: finalAnswer, durationMs: totalDurationMs });
         this.stateMachine.reset();
 
+        await this.saveSession().catch(err => console.error('Session save failed:', err));
         return finalAnswer;
       }
 
       const executionPromises = toolCalls.map(async (tc, toolCallIndex) => {
         if (signal?.aborted) throw createAbortError();
 
-        const toolName = tc?.function?.name || '';
-        const toolCallId = tc?.id || `call_${queryId}_${currentIteration}_${toolCallIndex}`;
-        const isMcp = Boolean(this.mcpManager?.isMcpTool(toolName));
+        const toolName = tc?.function?.name || '';
+        const toolCallId = tc?.id || `call_${queryId}_${currentIteration}_${toolCallIndex}`;
+        if (this.allowedToolNames && !this.allowedToolNames.has(toolName)) {
+          const rejectedResult = { status: 'error', message: `Tool "${toolName}" is not permitted in this execution context.` };
+          onToolStart(toolName, {});
+          onToolResult(toolName, rejectedResult, 0);
+          return {
+            toolMessage: {
+              role: 'tool',
+              tool_call_id: toolCallId,
+              name: toolName,
+              content: JSON.stringify(rejectedResult),
+            },
+          };
+        }
+        const isBuiltin = isBuiltinTool(toolName);
+        const isMcp = !isBuiltin && (toolName.startsWith('mcp_') || Boolean(this.mcpManager?.isMcpTool(toolName)));
 
         let prepared;
         if (isMcp) {
@@ -735,10 +1071,12 @@ ${toolsSummary}
         let result;
         if (cachedResult) {
           result = { ...cachedResult, cache: { hit: true, reason: 'duplicate_call_in_query' } };
+        } else if (isBuiltin) {
+          result = await executeTool(toolName, finalArgs, { agent: this, memory: this.memory, client: this.client, signal, onSubagentProgress });
         } else if (isMcp) {
           result = await this.mcpManager.callTool(toolName, finalArgs);
         } else {
-          result = await executeTool(toolName, finalArgs, { agent: this, memory: this.memory, client: this.client, signal });
+          result = await executeTool(toolName, finalArgs, { agent: this, memory: this.memory, client: this.client, signal, onSubagentProgress });
         }
 
         if (!cachedResult) toolResultCache.set(signature, result);
@@ -750,7 +1088,12 @@ ${toolsSummary}
 
         this._extractFactsFromToolResult(toolName, finalArgs, result);
 
-     
+        toolResultTracker.total++;
+        toolResultTracker.toolNames.push(toolName);
+        if (result.status === 'not_found') toolResultTracker.notFound++;
+        else if (result.status === 'error') toolResultTracker.error++;
+        else toolResultTracker.success++;
+
         const cappedResult = this._capToolResultForHistory(result);
 
         return {
@@ -758,14 +1101,14 @@ ${toolsSummary}
             role: 'tool',
             tool_call_id: toolCallId,
             name: toolName,
-            content: JSON.stringify({
+              content: JSON.stringify({
               authoritative: true,
               result: cappedResult,
               instruction: result.status === 'not_found'
-                ? 'No matching data was found. Do not invent records; say that the catalog has no match or use an appropriate fallback tool.'
+                ? 'CRITICAL: No matching data was found for this query. Do NOT invent, fabricate, or guess any records. You MUST either (a) state explicitly that no verified information exists, or (b) immediately call web_search to look up live external information. Under no circumstances should you generate plausible-sounding but unverified details.'
                 : result.status === 'error'
-                  ? 'The tool failed. Do not claim that the requested facts were verified.'
-                  : 'Use only facts present in this result when answering. Do not echo raw JSON data — summarize in natural language.'
+                  ? 'CRITICAL: The tool failed to retrieve data. Do NOT claim that the requested facts were verified. You MUST acknowledge the error and either retry or inform the user that the information could not be retrieved.'
+                  : 'Use ONLY the specific facts present in this result when answering. Do NOT add, infer, or extrapolate information beyond what is explicitly provided. Do NOT fabricate additional details, dates, names, or relationships not present in this result. Do not echo raw JSON data — summarize in natural language while preserving factual accuracy.'
             })
           }
         };
@@ -779,13 +1122,20 @@ ${toolsSummary}
       }
     }
 
+    const selfCritiqueDirective = await this._performSelfCritique(
+      toolResultTracker,
+      dominantLang,
+      promptForLLM
+    );
+
     const langPrompt = dominantLang === 'zh'
-      ? "请根据上述工具查询结果，直接回答（不要开头问候语），用流畅优雅的中文，先1-2句概述，再列要点。包含具体的 YouTube 真实链接（如 Direct Watch: https://www.youtube.com/watch?v=... หรือ Search: https://www.youtube.com/results?search_query=...）及事实数据。"
+      ? "请根据上述工具查询结果，为粉丝提供详细、全面且深入的解答。条理清晰地阐述作品背景、角色特质、音乐成就与演艺里程碑，包含具体的 YouTube 真实链接（如 Direct Watch: https://www.youtube.com/watch?v=... 或 Search: https://www.youtube.com/results?search_query=...）及完整事实数据。\n\n【反幻觉守则 — 必须遵守】只陈述工具结果中明确包含的事实。禁止编造、推测或补充工具结果中不存在的剧名、歌曲名、角色名、品牌名、日期或任何细节。如果工具结果不足以完整回答，请明确说明哪些部分未经验证，而不是凭空补全。"
       : dominantLang === 'en'
-        ? "Based on the tool results above, answer directly (no opening greeting or template phrase). Give a 1-2 sentence summary, then concise bullet points in polished English. Include verified YouTube direct and search links (https://www.youtube.com/results?search_query=...)."
-        : "สรุปคำตอบจากผลลัพธ์เครื่องมือข้างต้น โดยไม่ต้องทักทาย ตอบตรงประเด็น 1-2 ประโยค แล้วตามด้วย bullet points สั้นๆ เป็นภาษาไทย พร้อมแสดงลิงก์ YouTube จริง (Direct Watch Link และ https://www.youtube.com/results?search_query=...) และข้อมูลผลงานที่ถูกต้องแม่นยำ";
+        ? "Based on the tool results above, provide a comprehensive, richly detailed response for fans. Explain background storylines, character traits, musical highlights, and career milestones with well-organized Markdown headers, bullet points, and verified YouTube links (https://www.youtube.com/results?search_query=...).\n\n【Anti-Hallucination Mandate — MANDATORY】Only state facts explicitly present in the tool results above. Do NOT fabricate, infer, or supplement drama titles, song names, character roles, brand names, dates, or any details not found in the tool results. If the tool results are insufficient to fully answer, explicitly note which parts are unverified rather than inventing plausible-sounding details."
+        : "สรุปคำตอบจากผลลัพธ์เครื่องมือข้างต้น โดยให้ข้อมูลแฟนคลับอย่างละเอียด ลึกซึ้ง ครบถ้วนและชัดเจน จัดโครงสร้างด้วยหัวข้อ Markdown, ตาราง และ bullet points ให้สวยงาม พร้อมแสดงลิงก์ YouTube จริง (Direct Watch Link และ https://www.youtube.com/results?search_query=...) พร้อมเกร็ดประวัติและผลงานอย่างเต็มที่\n\n【กฎป้องกันการแต่งข้อมูล — บังคับใช้】ระบุเฉพาะข้อเท็จจริงที่มีอยู่จริงในผลลัพธ์เครื่องมือเท่านั้น ห้ามสร้างชื่อละคร เพลง ตัวละคร แบรนด์ วันที่ หรือรายละเอียดใดๆ ที่ไม่มีอยู่ในผลลัพธ์เครื่องมือ หากข้อมูลไม่เพียงพอสำหรับคำตอบที่สมบูรณ์ ให้ระบุชัดเจนว่าส่วนใดยังไม่ได้รับการยืนยัน แทนการเติมข้อมูลที่ฟังดูน่าเชื่อแต่ไม่มีหลักฐาน";
 
     this.conversationHistory.push({ role: 'user', content: langPrompt });
+    this.conversationHistory.push({ role: 'system', content: selfCritiqueDirective });
 
     if (this.stateMachine.state !== AgentStates.STREAMING_ANSWER) {
       this.stateMachine.transition(AgentStates.STREAMING_ANSWER);
@@ -796,6 +1146,7 @@ ${toolsSummary}
     const finalRes = await this.client.chat({
       messages: this.conversationHistory,
       temperature: 0.3,
+      maxTokens: 8192,
       stream: true,
       signal,
       onThought: (thoughtChunk) => {
@@ -821,29 +1172,147 @@ ${toolsSummary}
       }
     });
 
+    if (finalRes?.usage) {
+      queryPromptTokens += Number(finalRes.usage.prompt_tokens || 0);
+      queryCompletionTokens += Number(finalRes.usage.completion_tokens || 0);
+      queryReasoningTokens += Number(finalRes.usage.reasoning_tokens || 0);
+    }
+
+    const queryTokens = {
+      prompt: queryPromptTokens,
+      completion: queryCompletionTokens,
+      reasoning: queryReasoningTokens,
+      total: queryPromptTokens + queryCompletionTokens
+    };
+
+    const queryCostUsd = calculateTokenCost(
+      this.client?.provider || 'lmstudio',
+      this.client?.model || 'google/gemma-4-e4b',
+      queryPromptTokens,
+      queryCompletionTokens
+    );
+
+    this.session.recordQueryTokens(queryTokens, queryCostUsd);
+    this.lastTelemetry = { tokens: queryTokens, costUsd: queryCostUsd };
+
     const totalDurationMs = Date.now() - queryStartTime;
     this.session.stats.totalDurationMs += totalDurationMs;
 
-    const defaultDone = dominantLang === 'zh' ? "查询完毕" : dominantLang === 'en' ? "Search complete." : "เสร็จสิ้นการค้นหาข้อมูล";
-    const output = finalRes?.content || defaultDone;
-    onFinalAnswer(output, { durationMs: totalDurationMs, language: dominantLang });
+    const defaultDone =
+      dominantLang === 'zh' ? "查询完毕" :
+        dominantLang === 'ja' ? "検索が完了しました" :
+          dominantLang === 'ko' ? "검색이 완료되었습니다" :
+            dominantLang === 'en' ? "Search complete." : "เสร็จสิ้นการค้นหาข้อมูล";
+    const output = sanitizeResponse(finalRes?.content || defaultDone);
+    const citations = extractCitations(output, recordedTools);
+    this.lastCitations = citations;
+    if (currentAssistantSessionMsg) {
+      currentAssistantSessionMsg.citations = citations;
+    }
+
+    onFinalAnswer(output, {
+      durationMs: totalDurationMs,
+      language: dominantLang,
+      tokens: queryTokens,
+      costUsd: queryCostUsd,
+      citations
+    });
 
     this._extractFactsFromFinalAnswer(output);
 
     this.stateMachine.transition(AgentStates.COMPLETE);
-    eventBus.emit(Events.AGENT_FINAL_ANSWER, { queryId, answer: output, durationMs: totalDurationMs });
-    eventBus.emit(Events.AGENT_QUERY_END, { queryId, durationMs: totalDurationMs });
-    this.stateMachine.reset();
-
-    this.saveSession().catch(err => console.error('Session save failed:', err));
+    eventBus.emit(Events.AGENT_FINAL_ANSWER, {
+      queryId,
+      answer: output,
+      durationMs: totalDurationMs,
+      tokens: queryTokens,
+      costUsd: queryCostUsd,
+      citations
+    });
+    eventBus.emit(Events.AGENT_QUERY_END, {
+      queryId,
+      durationMs: totalDurationMs,
+      tokens: queryTokens,
+      costUsd: queryCostUsd,
+      citations
+    });
+    await this.saveSession().catch(err => console.error('Session save failed:', err));
 
     return output;
   }
 
+  async run(userPrompt, callbacks = {}) {
+    return this.ask(userPrompt, callbacks);
+  }
+
+  _computeConfidenceScore(toolResultTracker) {
+    if (toolResultTracker.total === 0) return 0;
+
+    const successRatio = toolResultTracker.success / toolResultTracker.total;
+    const errorPenalty = toolResultTracker.error * 0.5;
+    const notFoundPenalty = toolResultTracker.notFound * 0.35;
+    const base = Math.max(0, successRatio - errorPenalty - notFoundPenalty);
+
+    const hasVerifiedSource = toolResultTracker.success > 0;
+    const allFailed = toolResultTracker.success === 0 && (toolResultTracker.notFound > 0 || toolResultTracker.error > 0);
+
+    if (allFailed) return Math.min(base, 0.2);
+    if (!hasVerifiedSource) return Math.min(base, 0.4);
+
+    return Math.max(0.1, Math.min(1, base));
+  }
+
+  async _performSelfCritique(toolResultTracker, dominantLang, originalQuery) {
+    const confidence = this._computeConfidenceScore(toolResultTracker);
+
+    const th = dominantLang === 'th';
+    const zh = dominantLang === 'zh';
+
+    if (confidence <= 0.35) {
+      const prefix = th
+        ? '【คำสั่งระบบเชิงวิพากษ์ — ลดระดับความมั่นใจต่ำ】'
+        : zh
+          ? '【系统自我审查 — 证据不足】'
+          : '【SYSTEM SELF-CRITIQUE — EVIDENCE INSUFFICIENT】';
+      const body = th
+        ? 'เครื่องมือที่เรียกใช้ส่วนใหญ่ (หรือทั้งหมด) ไม่พบข้อมูลที่ยืนยันได้ หรือเกิดข้อผิดพลาด ความมั่นใจในความถูกต้องของข้อมูลต่ำในระดับที่จะตอบได้อย่างสมบูรณ์ ดังนั้นคุณต้องปฏิบัติตามนี้: (1) ห้ามแต่งเติมหรือคาดเดารายละเอียดใดๆ (ชื่อผลงาน, นักแสดง, วันที่, แบรนด์) (2) ระบุอย่างตรงไปตรงมาว่าไม่พบข้อมูลที่ยืนยันได้สำหรับการสอบถามนี้ และ (3) แนะนำวิธีอื่นให้ผู้ใช้ค้นหาข้อมูล เช่น ถามใหม่ด้วยคำค้นหาอื่น หรือรอการประกาศอย่างเป็นทางการ การตอบแบบ "ไม่มีข้อมูลอย่างเป็นทางการ" ดีกว่าการสร้างคำตอบที่สมบูรณ์แต่ไม่มีหลักฐานเสมอ'
+        : zh
+          ? '您请求的信息在已验证的数据库中未能找到充分的证据支持。您必须遵循以下规则：(1) 严禁编造、推测或虚构任何清晰信息（作品名称、演员、日期、品牌）；(2) 如实说明当前没有找到可核实的记录；(3) 建议用户换一种问法或等待官方公告。始终优先说"未找到官方信息"，而不是生成完整但缺乏依据的描述。'
+          : 'The verification tools returned insufficient or no confirmed evidence for this query. You MUST follow these rules: (1) Do NOT fabricate, infer, or invent any concrete details (titles, casts, dates, brands); (2) Honestly state that no verified record could be found; (3) Suggest alternative ways for the user to find the information. Always prefer stating "No official information found" over generating a complete but ungrounded description.';
+      return `${prefix}\n${body}\nOriginal query: ${originalQuery}`;
+    }
+
+    if (confidence >= 0.7) {
+      const prefix = th
+        ? '【คำสั่งระบบเชิงวิพากษ์ — แหล่งข้อมูลแข็งแกร่ง】'
+        : zh
+          ? '【系统自我审查 — 证据充分】'
+          : '【SYSTEM SELF-CRITIQUE — EVIDENCE STRONG】';
+      const body = th
+        ? 'เครื่องมือยืนยันข้อมูลได้สำเร็จเพียงพอสำหรับการตั้งคำถามนี้ คุณสามารถตอบได้อย่างมั่นใจโดยอ้างอิงเฉพาะข้อเท็จจริงที่ปรากฏในผลลัพธ์เครื่องมือเท่านั้น ยังคงห้ามเติมรายละเอียดที่ไม่มีในผลลัพธ์เครื่องมือ'
+        : zh
+          ? '工具已成功验证足够的数据。您可以自信地回答，但仅基于工具结果中呈现的事实。仍然禁止添加工具结果中不存在的细节。'
+          : 'Tool results successfully verified sufficient data for this query. You may answer with confidence, but ONLY based on what is present in the tool results. Do NOT add details not present in the tool output.';
+      return `${prefix}\n${body}`;
+    }
+
+    const prefix = th
+      ? '【คำสั่งระบบเชิงวิพากษ์ — ความมั่นใจปานกลาง】'
+      : zh
+        ? '【系统自我审查 — 需谨慎】'
+        : '【SYSTEM SELF-CRITIQUE — PROCEED WITH CAUTION】';
+    const body = th
+      ? 'เครื่องมือให้ข้อมูลบางส่วนแต่ยังไม่ครบถ้วนสมบูรณ์ ตรวจสอบคำตอบของคุณก่อนส่งให้ผู้ใช้: (1) ระบุเฉพาะข้อเท็จจริงที่ยืนยันโดยผลลัพธ์เครื่องมือเท่านั้น (2) ส่วนที่ยังไม่ยืนยัน ให้ระบุชัดเจนว่า "ยังไม่ได้รับการยืนยัน" หรือ "รายงานไม่ชัดเจน" (3) ห้ามเติมโครงเรื่อง การคัดเลือกนักแสดง หรือวันที่ที่ไม่มีแหล่งที่มา'
+      : zh
+        ? '工具提供部分但非完整的信息。在回答前自查：(1) 只陈述工具结果已确认的事实；(2) 明确标记仍未确认的部分为"未验证"或"未官方确认"；(3) 不要补充没有来源支持的剧情、选角或日期。'
+        : 'Tool results provide partial but incomplete information. Before answering, self-check: (1) Only state facts confirmed by tool results. (2) Explicitly label unconfirmed aspects as "unverified" or "not officially confirmed." (3) Do not supplement plotlines, casting, or dates without supporting source.';
+    return `${prefix}\n${body}`;
+  }
+
   _capToolResultForHistory(result) {
     if (!result || typeof result !== 'object') return result;
 
-    const MAX_RESULT_BYTES = 4096;
+    const MAX_RESULT_BYTES = 16384;
     const serialized = JSON.stringify(result);
     if (serialized.length <= MAX_RESULT_BYTES) return result;
 
@@ -866,7 +1335,7 @@ ${toolsSummary}
       }
     
       if (typeof obj === 'string' && obj.length > 500) {
-        return obj.slice(0, 500) + '…[truncated]';
+        return `${obj.slice(0, 500)}…[truncated]`;
       }
       return obj;
     };
@@ -876,7 +1345,7 @@ ${toolsSummary}
     return capped;
   }
 
-  _extractFactsFromToolResult(toolName, toolArgs, result) {
+  _extractFactsFromToolResult(toolName, _toolArgs, result) {
     if (!result || result.status === 'error' || result.status === 'not_found') return;
 
     const facts = [];
@@ -898,7 +1367,7 @@ ${toolsSummary}
 
       case 'get_work_detail': {
         const w = result.work;
-        if (w && w.titleCn) {
+        if (w?.titleCn) {
           facts.push({
             content: `${w.titleCn} (${w.titleEn || w.titleTh || ''}) — ${w.role || 'Actor'} | ${w.platform || ''} | ${w.year || ''}`,
             category: 'drama',
@@ -1029,9 +1498,8 @@ ${toolsSummary}
     if (!answer || answer.length < 20) return;
 
     const ytRegex = /https?:\/\/www\.youtube\.com\/watch\?v=([a-zA-Z0-9_-]+)/g;
-    let match;
     const ytIds = new Set();
-    while ((match = ytRegex.exec(answer)) !== null) {
+    for (const match of answer.matchAll(ytRegex)) {
       ytIds.add(match[1]);
     }
     if (ytIds.size > 0) {