kiku-agent 1.0.11 → 1.2.0

package/server/web-chat/routes/chatRoute.js

@@ -0,0 +1,397 @@
+import { randomUUID } from 'node:crypto';
+import { resolveAgentConnection } from '../core/connection.js';
+import { executeDirectCatalogKnowledge } from '../core/directCatalogEngine.js';
+import { makeInspectableToolPayload } from '../core/toolInspector.js';
+import { getAgentMemorySnapshot } from '../core/memorySnapshot.js';
+import { parseJsonBody, sendJson, sendError } from '../core/errorHandler.js';
+import { registerClarificationResolver } from './clarifyRoute.js';
+import { extractAgentFollowUpQuestions, generateDynamicFollowUps } from '../core/followUpEngine.js';
+import { resolveConversationContext } from '../core/conversationContext.js';
+import { applyFutureEventGuard } from '../core/futureEventGuard.js';
+import { extractApiKey } from '../core/security.js';
+import { assessDramaAnswerQuality } from '../core/dramaKnowledge.js';
+
+function stripInvalidYouTubeLinks(text) {
+  if (!text || typeof text !== 'string') return text || '';
+  return text.replace(/(?:https?:\/\/)?(?:www\.)?(?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]{1,20})/gi, (m, id) => (id.length === 11 ? m : ''));
+}
+
+async function replaceLowQualityDramaAnswer({ query, answer, persona, conversationContext, toolsUsed }) {
+  const assessment = assessDramaAnswerQuality(query, answer);
+  if (!assessment.applicable || assessment.valid) return null;
+
+  const fallback = await executeDirectCatalogKnowledge(query, persona, { conversationContext });
+  if (Array.isArray(toolsUsed)) toolsUsed.push(...fallback.tools);
+  return {
+    answer: fallback.answer,
+    suggestions: fallback.suggestions || [],
+    issues: assessment.issues
+  };
+}
+
+
+export function sanitizeSubagentProgress(event = {}) {
+  const text = (value, max = 200) => String(value ?? '').slice(0, max);
+  const num = (value) => (Number.isFinite(Number(value)) ? Number(value) : undefined);
+  const out = { type: 'subagent_progress' };
+  if (['subagent', 'research', 'verify'].includes(event.source)) out.source = event.source;
+  else out.source = 'subagent';
+  if (['start', 'iteration', 'tool', 'worker-start', 'worker-complete', 'complete'].includes(event.type)) out.kind = event.type;
+  else out.kind = 'tool';
+  const subject = event.task ?? event.question ?? event.claim ?? '';
+  if (subject) out.subject = text(subject);
+  if (event.iteration !== undefined) out.iteration = num(event.iteration);
+  if (event.maxIterations !== undefined) out.maxIterations = num(event.maxIterations);
+  if (event.name) out.tool = text(event.name, 80);
+  if (event.label) out.label = text(event.label, 120);
+  if (event.id) out.workerId = text(event.id, 80);
+  if (event.workerId) out.workerId = text(event.workerId, 80);
+  if (event.sources !== undefined) out.sources = num(event.sources);
+  return out;
+}
+
+export async function handleChatRoute(req, res, urlObj) {
+  let body;
+  try {
+    body = await parseJsonBody(req);
+  } catch (err) {
+    return sendError(res, 400, `Invalid JSON body: ${err.message}`);
+  }
+
+  const query = String(body.query || '').trim();
+
+  const persona = 'default';
+  const wantsStream = body.stream === true || (req.headers.accept && req.headers.accept.includes('text/event-stream'));
+
+  if (!query) {
+    return sendError(res, 400, 'Query is required');
+  }
+
+  const apiKey = extractApiKey(req);
+  const abortController = new AbortController();
+  req.on('close', () => {
+    if (!res.writableEnded) {
+      abortController.abort();
+    }
+  });
+
+  const startTime = Date.now();
+  const clarificationIds = new Map();
+  const externalClarificationId = (internalId) => {
+    if (!clarificationIds.has(internalId)) clarificationIds.set(internalId, randomUUID());
+    return clarificationIds.get(internalId);
+  };
+  const conversationContext = resolveConversationContext(query, body.history);
+  const publicContext = {
+    contextual: conversationContext.contextual,
+    domain: conversationContext.domain
+  };
+
+  try {
+    const conn = await resolveAgentConnection({
+      provider: body.provider,
+      model: body.model,
+      thinking: body.thinking,
+      apiKey,
+      sessionId: body.sessionId,
+      history: body.history,
+    }, { signal: abortController.signal });
+
+    let augmentedQuery = conversationContext.resolvedQuery;
+
+    augmentedQuery += `\n\n[SYSTEM DIRECTIVE (Fact Grounding & Music Playback):
+1. อ้างอิงเฉพาะเพลง ซีรีส์ และข้อมูลที่ได้จากผลลัพธ์เครื่องมือ (search_works, search_discography, get_song_detail, get_character_roles, get_awards, get_career_timeline) เท่านั้น ห้ามแต่งชื่อเพลง ชื่อซีรีส์ ตัวเลข หรือลิงก์ YouTube ขึ้นเอง หากเครื่องมือไม่พบข้อมูล ให้บอกผู้ใช้ตามตรงว่าไม่พบข้อมูลในคลัง
+2. เมื่อพูดถึงเพลงใด ให้ระบุ "ชื่อเพลงจริง" จากคลังข้อมูลกำกับในประโยคเสมอ (เช่น "เพลง 千年等一回") และห้ามแนบ URL YouTube ใดๆ ที่ไม่ได้มาจากผลลัพธ์เครื่องมือโดยเด็ดขาด
+3. เงื่อนไขการเสนอเปิดเพลงใน Mini Player: ให้เสนอเปิดเพลงเฉพาะเมื่อผู้ใช้ถามเรื่องบทเพลง การฟังเพลง หรือ OST โดยตรงเท่านั้น และต้องระบุชื่อเพลงที่เจาะจงในประโยคเดียวกัน ห้ามเสนอเปิดเพลงหรือถามชวนเปิดเพลงเมื่อผู้ใช้ถามเรื่องซีรีส์ ข่าวลือ หรือเนื้อหาทั่วไป
+4. การแยกแยะชื่อเรื่องและข่าวลือแคสติ้ง (Entity Disambiguation & Anti-Hallucination): ห้ามเดาหรือจับคู่คำค้นหาที่ออกเสียงคล้ายกันเข้ากับผลงานในคลังโดยไม่มีหลักฐานเด็ดขาด (เช่น คำว่า "Qi Xiang Cai" หรือ "七星彩" (ชีซิงไฉ่) คือโปรเจกต์ซีรีส์จีนโบราณของ Youku x Stellar Media ดัดแปลงจากนิยายของหมิงเยว่ตัง ที่มีกระแสข่าวลือแคสติ้ง ไม่ใช่เพลงหรือซีรีส์ 《千香》 (The Eternal Fragrance / พันกลิ่นบุปผา) และไม่มีความเกี่ยวข้องกัน ห้ามอ้างว่าเป็นเพลง OST หรือผลงานในคลังเด็ดขาด)
+5. หากผู้ใช้ส่งคำว่า "ดำเนินการต่อ" หรือตอบตกลงต่อคำถามก่อนหน้า ให้ลงมือทำสิ่งที่เสนอไว้ทันทีด้วยข้อมูลจริงจากเครื่องมือ (เช่น สรุปเพลงที่เสนอพร้อมชื่อจริงและรายละเอียด) อย่าถามคำถามเดิมซ้ำอีก
+6. ข้อมูลที่อ่อนไหวต่อเวลา (ผลงานล่าสุด, กำหนดการ, โซเชียล, ข่าว, ข่าวลือแคสติ้ง, รางวัล, แบรนด์) ให้ลำดับการใช้ข้อมูลสดจาก fetch_api/global_search/verify_claim/web_search แทนข้อมูลที่อาจเก่าในคลัง เพื่อหลีกเลี่ยงคำตอบที่ล้าหลังหรือเข้าใจผิด]`;
+
+    augmentedQuery += `\n\n[SYSTEM DIRECTIVE (Answer Quality for Drama Analysis):
+1. แยก "ข้อเท็จจริงจากเครื่องมือ" ออกจาก "บทวิเคราะห์" ให้ชัดเจน ห้ามนำเรื่องย่อไปสรุปเป็นเสียงวิจารณ์หรือการยอมรับของวงการ
+2. ห้ามเหมารวมว่าผลงานใหม่กว่าแปลว่าลึกกว่า สมจริงกว่า หรือแสดงดีกว่า ให้เทียบจากภาระของบท แรงขับของตัวละคร แนวเรื่อง และฉากที่มีหลักฐานเท่านั้น
+3. ห้ามใช้คำยกย่องแบบไม่มีหลักฐาน เช่น "ระดับแนวหน้า", "ไม่มีใครเทียบได้", "ก้าวข้ามไอดอลอย่างสมบูรณ์" หรือ "ได้รับรางวัลมากมาย"
+4. คะแนนในแคตตาล็อกที่ไม่มีชื่อแหล่งและเกณฑ์คะแนนเป็นเพียง metadata ภายใน ห้ามใช้ยืนยันคุณภาพและไม่ต้องแสดงในบทวิเคราะห์
+5. In Blossom: จวีจิ้งอีแสดงตัวตนของหยางไฉ่เวยภายใต้รูปลักษณ์ซ่างกวนจื่อหลัง premise การเปลี่ยนใบหน้า ไม่ใช่สองตัวละครอิสระที่สลับเล่นตลอดเรื่อง
+6. The Legend of White Snake: ไป๋ซู่เจินคือวิญญาณ/ปีศาจงูขาวที่แปลงเป็นหญิงมนุษย์ ส่วนสวี่เซียนคือมนุษย์ชาย ห้ามสลับเพศหรือเผ่าพันธุ์
+7. หากเป็นคำสั่ง "ดำเนินการต่อ" ให้ตอบเฉพาะมุมใหม่ที่ผู้ใช้ขอ ห้ามคัดลอกคำตอบก่อนหน้ามาตอบซ้ำ]`;
+
+    augmentedQuery += `\n\n[SYSTEM DIRECTIVE (Topic & Future-event Safety):
+1. คำถามสั้นที่มีสรรพนามหรืออ้างถึง "เรื่องนี้/งานนี้/ทำไม/น่าจับตามอง" ต้องยึดหัวข้อหลักล่าสุดในบทสนทนาก่อน ห้ามเปลี่ยนไปตอบเรื่องศิลปินเพียงเพราะ Persona หรือฐานข้อมูลเน้นศิลปิน
+2. วันนี้คือ ${conversationContext.today}. เหตุการณ์หลังวันนี้เป็นข้อมูลอนาคต: ใช้คำว่า "มีกำหนด", "มีรายงาน", หรือ "ยังไม่ยืนยัน" ตามหลักฐาน ห้ามฟันธงว่าได้รับเชิญหรือจะเข้าร่วมแน่นอนโดยไม่มีแหล่งทางการที่เป็นปัจจุบัน
+3. ห้ามนำวัน เดือน รายชื่อแขก หรือสถานะการเข้าร่วมจากงานคนละปีมาใช้กับฉบับปีปัจจุบัน หากต้องระบุวันที่แน่นอนหรือผู้เข้าร่วมงานอนาคต ให้ตรวจสอบด้วยเครื่องมือเว็บก่อน]`;
+
+    augmentedQuery += `\n\n[SYSTEM DIRECTIVE: After completing your answer, proactively formulate and suggest 2-3 engaging, creative, and relevant follow-up questions tailored specifically to what you just discussed for the user to explore deeper. Place them at the very end of your response strictly formatted as:
+[SUGGESTED_FOLLOW_UPS]
+- [คำถามแนะนำที่ 1 ที่เชื่อมโยงกับเรื่องที่เพิ่งเล่า]
+- [คำถามแนะนำที่ 2 ที่เชื่อมโยงกับเรื่องที่เพิ่งเล่า]
+- [คำถามแนะนำที่ 3 ที่เชื่อมโยงกับเรื่องที่เพิ่งเล่า]
+[/SUGGESTED_FOLLOW_UPS]
+Rules for the block: one question per line, plain text only — no markdown bold/italic, no extra headers, no lead-in sentences, no numbering inside the block.]`;
+
+    if (wantsStream) {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no'
+      });
+
+      const sendSse = (eventObj) => {
+        res.write(`data: ${JSON.stringify(eventObj)}\n\n`);
+      };
+
+      if (conn.ready && conn.agent) {
+        try {
+          const toolsUsed = [];
+          let reasoningStarted = false;
+          const runRes = await conn.agent.run(augmentedQuery, {
+            signal: abortController.signal,
+            onReasoningDelta: () => {
+              if (reasoningStarted) return;
+              reasoningStarted = true;
+              sendSse({ type: 'reasoning', chunk: 'กำลังวิเคราะห์บริบทและวางแผนคำตอบ' });
+            },
+            onToolStart: (name, input) => {
+              toolsUsed.push({ name, input });
+              sendSse({ type: 'tool_start', name, input: makeInspectableToolPayload(input) });
+            },
+            onToolResult: (name, result, durationMs) => {
+              const existing = toolsUsed.find(t => t.name === name);
+              if (existing) { existing.result = result; existing.durationMs = durationMs; }
+              sendSse({
+                type: 'tool_result',
+                name,
+                durationMs,
+                resultCount: result?.count ?? 0,
+                result: makeInspectableToolPayload(result)
+              });
+            },
+            onSubagentProgress: (event) => {
+              sendSse(sanitizeSubagentProgress(event));
+            },
+            onTokenDelta: (chunk) => {
+              sendSse({ type: 'token', chunk });
+            },
+            ...(conversationContext.contextual ? {} : {
+              onClarifyingQuestions: (questions, queryId) => {
+                sendSse({ type: 'clarifying_questions', questions, queryId: externalClarificationId(queryId) });
+              },
+              onClarifyingAnswer: (queryId) => {
+                return new Promise((resolve) => {
+                  registerClarificationResolver(externalClarificationId(queryId), resolve);
+                });
+              }
+            })
+          });
+
+          let finalAnswer = runRes?.answer || String(runRes || '');
+          finalAnswer = finalAnswer.replace(/The user has provided a complex instruction set:[\s\S]*?(?=\n\n|\n[A-Zก-๙]|$)/i, '').trim();
+          finalAnswer = finalAnswer.replace(/^\[SYSTEM (?:INSTRUCTION|DIRECTIVE):[\s\S]*?\]\s*/i, '').trim();
+
+          let suggestions = [];
+          const extracted = extractAgentFollowUpQuestions(finalAnswer);
+          finalAnswer = stripInvalidYouTubeLinks(extracted.cleanText);
+          finalAnswer = applyFutureEventGuard(finalAnswer, { tools: toolsUsed });
+          suggestions = extracted.suggestions;
+
+          if (!finalAnswer.trim()) {
+            const fallback = await executeDirectCatalogKnowledge(query, persona, { conversationContext });
+            finalAnswer = applyFutureEventGuard(fallback.answer, { tools: fallback.tools });
+            if (!suggestions.length) suggestions = fallback.suggestions || [];
+          }
+
+          const qualityFallback = await replaceLowQualityDramaAnswer({
+            query,
+            answer: finalAnswer,
+            persona,
+            conversationContext,
+            toolsUsed
+          });
+          if (qualityFallback) {
+            finalAnswer = applyFutureEventGuard(qualityFallback.answer, { tools: toolsUsed });
+            suggestions = qualityFallback.suggestions;
+          }
+
+          if (!suggestions.length) {
+            suggestions = generateDynamicFollowUps({ query, answer: finalAnswer, tools: toolsUsed });
+          }
+
+          sendSse({
+            type: 'final',
+            answer: finalAnswer,
+            suggestions,
+            durationMs: Date.now() - startTime,
+            tokens: conn.agent?.lastTelemetry?.tokens || conn.agent?.session?.lastQueryTokens || null,
+            costUsd: conn.agent?.lastTelemetry?.costUsd ?? conn.agent?.session?.lastQueryCostUsd ?? 0,
+            citations: conn.agent?.lastCitations || [],
+            context: publicContext,
+            memory: getAgentMemorySnapshot(conn.agent, body.sessionId)
+          });
+          res.write('data: [DONE]\n\n');
+          res.end();
+          return;
+        } catch (streamErr) {
+          if (abortController.signal.aborted || streamErr?.name === 'AbortError') {
+            if (!res.writableEnded) {
+              res.write('data: [DONE]\n\n');
+              res.end();
+            }
+            return;
+          }
+          const fallback = await executeDirectCatalogKnowledge(query, persona, { conversationContext });
+          sendSse({
+            type: 'final',
+            answer: applyFutureEventGuard(fallback.answer, { tools: fallback.tools }),
+            suggestions: fallback.suggestions,
+            durationMs: Date.now() - startTime,
+            citations: [],
+            context: publicContext,
+            memory: { sessionId: body.sessionId || null, messageCount: body.history?.length || 0, persistent: false }
+          });
+          res.write('data: [DONE]\n\n');
+          res.end();
+          return;
+        }
+      }
+
+      sendSse({ type: 'reasoning', chunk: '⚡ ตรวจพบ LM Studio ออฟไลน์ -> เปิดใช้งาน Auto Direct Catalog Knowledge Engine...' });
+
+      const fallback = await executeDirectCatalogKnowledge(query, persona, { conversationContext });
+      const guardedFallbackAnswer = applyFutureEventGuard(fallback.answer, { tools: fallback.tools });
+      for (const t of fallback.tools) {
+        sendSse({ type: 'tool_start', name: t.name, input: t.input });
+        sendSse({ type: 'tool_result', name: t.name, durationMs: t.durationMs, resultCount: t.resultCount, result: t.result });
+      }
+      sendSse({ type: 'token', chunk: guardedFallbackAnswer });
+      sendSse({
+        type: 'final',
+        answer: guardedFallbackAnswer,
+        suggestions: fallback.suggestions,
+        durationMs: Date.now() - startTime,
+        citations: [],
+        context: publicContext,
+        memory: { sessionId: body.sessionId || null, messageCount: body.history?.length || 0, persistent: false }
+      });
+      res.write('data: [DONE]\n\n');
+      res.end();
+      return;
+    }
+
+    if (conn.ready && conn.agent) {
+      let answer = '';
+      let thinking = '';
+      let thinkingDurationMs = 0;
+      const toolsUsed = [];
+      const subagentActivity = [];
+
+      let runRes;
+      try {
+        runRes = await conn.agent.run(augmentedQuery, {
+          signal: abortController.signal,
+        onReasoningDelta: () => { thinking = 'วิเคราะห์บริบทและวางแผนคำตอบแล้ว'; },
+        onReasoningEnd: () => { thinkingDurationMs = Date.now() - startTime; },
+        onSubagentProgress: (event) => {
+          subagentActivity.push(sanitizeSubagentProgress(event));
+        },
+        onToolStart: (name, input) => {
+          toolsUsed.push({ name, input: makeInspectableToolPayload(input), status: 'running' });
+        },
+        onToolResult: (name, result, dur) => {
+          let tool = null;
+          for (let index = toolsUsed.length - 1; index >= 0; index--) {
+            if (toolsUsed[index].name === name && toolsUsed[index].status === 'running') {
+              tool = toolsUsed[index];
+              break;
+            }
+          }
+          if (!tool) {
+            tool = { name };
+            toolsUsed.push(tool);
+          }
+          Object.assign(tool, {
+            status: 'done',
+            result: makeInspectableToolPayload(result),
+            resultCount: result?.count ?? 0,
+            durationMs: dur
+          });
+        }
+      });
+      } catch (agentErr) {
+        if (abortController.signal.aborted || agentErr?.name === 'AbortError') {
+          if (!res.writableEnded) {
+            return sendError(res, 499, 'Request aborted by client');
+          }
+          return;
+        }
+        throw agentErr;
+      }
+
+      answer = runRes?.answer || String(runRes || '');
+      let suggestions = [];
+      const extracted = extractAgentFollowUpQuestions(answer);
+      answer = stripInvalidYouTubeLinks(extracted.cleanText);
+      answer = applyFutureEventGuard(answer, { tools: toolsUsed });
+      suggestions = extracted.suggestions;
+
+      if (!answer.trim()) {
+        const fallback = await executeDirectCatalogKnowledge(query, persona, { conversationContext });
+        answer = applyFutureEventGuard(fallback.answer, { tools: fallback.tools });
+        if (!suggestions.length) suggestions = fallback.suggestions || [];
+      }
+
+      const qualityFallback = await replaceLowQualityDramaAnswer({
+        query,
+        answer,
+        persona,
+        conversationContext,
+        toolsUsed
+      });
+      if (qualityFallback) {
+        answer = applyFutureEventGuard(qualityFallback.answer, { tools: toolsUsed });
+        suggestions = qualityFallback.suggestions;
+      }
+
+      if (!suggestions.length) {
+        suggestions = generateDynamicFollowUps({ query, answer, tools: toolsUsed });
+      }
+
+      return sendJson(res, 200, {
+        status: 'ok',
+        query,
+        persona,
+        answer,
+        suggestions,
+        thinking,
+        thinkingDurationMs,
+        tools: toolsUsed,
+        subagents: subagentActivity,
+        tokens: conn.agent?.lastTelemetry?.tokens || conn.agent?.session?.lastQueryTokens || null,
+        costUsd: conn.agent?.lastTelemetry?.costUsd ?? conn.agent?.session?.lastQueryCostUsd ?? 0,
+        citations: conn.agent?.lastCitations || [],
+        context: publicContext,
+        memory: getAgentMemorySnapshot(conn.agent, body.sessionId),
+        durationMs: Date.now() - startTime
+      });
+    }
+
+    const fallback = await executeDirectCatalogKnowledge(query, persona, { conversationContext });
+    return sendJson(res, 200, {
+      status: 'ok',
+      query,
+      persona,
+      answer: applyFutureEventGuard(fallback.answer, { tools: fallback.tools }),
+      suggestions: fallback.suggestions || [],
+      thinking: fallback.thinking,
+      thinkingDurationMs: Date.now() - startTime,
+      tools: fallback.tools,
+      citations: [],
+      context: publicContext,
+      memory: { sessionId: body.sessionId || null, messageCount: body.history?.length || 0, persistent: false },
+      durationMs: Date.now() - startTime
+    });
+
+  } catch (err) {
+    return sendError(res, 500, err.message);
+  }
+}

package/server/web-chat/routes/clarifyConfigRoute.js

@@ -0,0 +1,98 @@
+import { resolveAgentConnection } from '../core/connection.js';
+import { parseJsonBody, sendJson, sendError } from '../core/errorHandler.js';
+import { ClarificationAnalytics, ClarificationConfig, formatAnalyticsForAPI } from '../../agent/clarificationAnalytics.js';
+import { isWebChatAdmin } from '../core/security.js';
+
+let sharedAnalytics = null;
+let sharedConfig = null;
+
+function getAnalytics() {
+  if (!sharedAnalytics) {
+    sharedAnalytics = new ClarificationAnalytics();
+  }
+  return sharedAnalytics;
+}
+
+function getConfig() {
+  if (!sharedConfig) {
+    sharedConfig = new ClarificationConfig();
+  }
+  return sharedConfig;
+}
+
+export async function handleClarifyAnalyticsRoute(req, res, options = {}) {
+  if (!isWebChatAdmin(req)) return sendError(res, 401, 'Admin API key required');
+  try {
+    const urlObj = new URL(req.url, `http://localhost:${options.port || 3001}`);
+    const days = parseInt(urlObj.searchParams.get('days') || '7', 10);
+    
+    const analytics = getAnalytics();
+    const data = analytics.getAnalytics({ days: Math.min(Math.max(days, 1), 90) });
+    
+    return sendJson(res, 200, {
+      status: 'ok',
+      ...formatAnalyticsForAPI(data),
+    });
+  } catch (err) {
+    return sendError(res, 500, `Failed to get analytics: ${err.message}`);
+  }
+}
+
+export async function handleClarifyConfigRoute(req, res, options = {}, action = 'get') {
+  try {
+    const config = getConfig();
+    
+    if (action === 'get') {
+      return sendJson(res, 200, {
+        status: 'ok',
+        config: config.getConfig(),
+      });
+    }
+
+    if (!isWebChatAdmin(req)) return sendError(res, 401, 'Admin API key required');
+    
+    if (action === 'reset') {
+      const newConfig = config.reset();
+      return sendJson(res, 200, {
+        status: 'ok',
+        message: 'Configuration reset to defaults',
+        config: newConfig,
+      });
+    }
+    
+    if (action === 'update') {
+      let body;
+      try {
+        body = await parseJsonBody(req);
+      } catch (err) {
+        return sendError(res, 400, `Invalid JSON body: ${err.message}`);
+      }
+      
+      const { enabled, confidenceThreshold, maxRounds, timeoutMs, preferLLMQuestions } = body;
+      const updates = {};
+      
+      if (enabled !== undefined) updates.enabled = enabled;
+      if (confidenceThreshold !== undefined) updates.confidenceThreshold = confidenceThreshold;
+      if (maxRounds !== undefined) updates.maxRounds = maxRounds;
+      if (timeoutMs !== undefined) updates.timeoutMs = timeoutMs;
+      if (preferLLMQuestions !== undefined) updates.preferLLMQuestions = preferLLMQuestions;
+      
+      if (Object.keys(updates).length === 0) {
+        return sendError(res, 400, 'No valid configuration updates provided');
+      }
+      
+      const newConfig = config.updateConfig(updates);
+      return sendJson(res, 200, {
+        status: 'ok',
+        message: 'Configuration updated',
+        config: newConfig,
+      });
+    }
+    
+    return sendError(res, 400, 'Invalid action');
+  } catch (err) {
+    return sendError(res, 500, `Failed to handle config: ${err.message}`);
+  }
+}
+
+export default { handleClarifyAnalyticsRoute, handleClarifyConfigRoute };

package/server/web-chat/routes/clarifyRoute.js

@@ -0,0 +1,83 @@
+import { resolveAgentConnection } from '../core/connection.js';
+import { parseJsonBody, sendJson, sendError } from '../core/errorHandler.js';
+import { eventBus, Events } from '../../agent/eventBus.js';
+
+const pendingClarifications = new Map();
+const MAX_PENDING_CLARIFICATIONS = 100;
+
+export function registerClarificationResolver(queryId, resolve) {
+  if (!/^[a-f0-9-]{36}$/i.test(String(queryId || '')) || typeof resolve !== 'function') return false;
+  while (pendingClarifications.size >= MAX_PENDING_CLARIFICATIONS) {
+    const oldestId = pendingClarifications.keys().next().value;
+    const oldest = pendingClarifications.get(oldestId);
+    clearTimeout(oldest?.timer);
+    oldest?.resolve?.('skip');
+    pendingClarifications.delete(oldestId);
+  }
+  const timer = setTimeout(() => {
+    const entry = pendingClarifications.get(queryId);
+    if (entry) {
+      pendingClarifications.delete(queryId);
+      entry.resolve('skip');
+    }
+  }, 35_000);
+  timer.unref?.();
+  pendingClarifications.set(queryId, { resolve, timer });
+  return true;
+}
+
+export function resolveClarification(queryId, answers) {
+  const entry = pendingClarifications.get(queryId);
+  if (entry) {
+    pendingClarifications.delete(queryId);
+    clearTimeout(entry.timer);
+    entry.resolve(answers);
+    return true;
+  }
+  return false;
+}
+
+export function resolveAllPendingClarifications(answers = 'skip') {
+  for (const [queryId, entry] of pendingClarifications.entries()) {
+    pendingClarifications.delete(queryId);
+    clearTimeout(entry.timer);
+    entry.resolve(answers);
+  }
+}
+
+export async function handleClarifyRoute(req, res) {
+  let body;
+  try {
+    body = await parseJsonBody(req);
+  } catch (err) {
+    return sendError(res, 400, `Invalid JSON body: ${err.message}`);
+  }
+
+  const { queryId, answers } = body;
+
+  if (!/^[a-f0-9-]{36}$/i.test(String(queryId || '')) || typeof answers !== 'string' || answers.length > 2000) {
+    return sendError(res, 400, 'queryId and answers (string) are required');
+  }
+
+  const resolved = resolveClarification(queryId, answers);
+
+  if (resolved) {
+    eventBus.emit(Events.AGENT_CLARIFYING_ANSWER, {
+      queryId,
+      answers,
+      timestamp: Date.now(),
+    });
+
+    return sendJson(res, 200, {
+      status: 'ok',
+      message: 'Clarifying answers received. Agent will continue processing.',
+    });
+  }
+
+  return sendJson(res, 200, {
+    status: 'ok',
+    message: 'No pending clarification found for this queryId. The agent may have already timed out or completed.',
+  });
+}
+
+export default { handleClarifyRoute, registerClarificationResolver, resolveClarification };

package/server/web-chat/routes/compareRoute.js

@@ -0,0 +1,79 @@
+import { executeTool } from '../../agent/tools.js';
+import { parseJsonBody, sendJson, sendError } from '../core/errorHandler.js';
+
+export async function handleCompareRoute(req, res) {
+  let body;
+  try {
+    body = await parseJsonBody(req);
+  } catch (err) {
+    return sendError(res, 400, `Invalid JSON body: ${err.message}`);
+  }
+
+  const { itemA, itemB } = body;
+  if (!itemA || !itemB) {
+    return sendError(res, 400, 'Both itemA and itemB are required');
+  }
+
+  let resultA = null;
+  let resultB = null;
+
+  try {
+    resultA = await executeTool('global_search', { query: itemA });
+    resultB = await executeTool('global_search', { query: itemB });
+  } catch {}
+
+  const extractItems = (searchRes) => {
+    if (!searchRes) return [];
+    const raw = searchRes.results;
+    if (Array.isArray(raw)) return raw;
+    if (raw && typeof raw === 'object') {
+      const collected = [];
+      for (const val of Object.values(raw)) {
+        if (Array.isArray(val)) collected.push(...val);
+      }
+      return collected;
+    }
+    return [];
+  };
+
+  const formatItem = (item) => {
+    if (typeof item === 'string') {
+      return {
+        title: item,
+        type: 'general',
+        year: null,
+        description: item,
+        rating: null,
+        episodes: null,
+        streamingUrl: null
+      };
+    }
+    return {
+      title: item?.title || item?.titleCn || item?.name || 'N/A',
+      type: item?.type || item?.category || 'unknown',
+      year: item?.year || null,
+      description: item?.description || item?.synopsis || '',
+      rating: item?.rating || null,
+      episodes: item?.episodes || null,
+      streamingUrl: item?.streamingUrl || item?.youtubeSearchUrl || null
+    };
+  };
+
+  const itemsA = extractItems(resultA).slice(0, 3).map(formatItem);
+  const itemsB = extractItems(resultB).slice(0, 3).map(formatItem);
+
+  sendJson(res, 200, {
+    status: 'ok',
+    comparison: {
+      itemA: {
+        query: itemA,
+        results: itemsA,
+      },
+      itemB: {
+        query: itemB,
+        results: itemsB,
+      }
+    },
+    source: 'catalog'
+  });
+}