kiku-agent 1.2.0 → 1.3.0

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

@@ -1,397 +1,488 @@
-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);
-  }
-}
+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, dedupeSuggestions, normalizeSuggestionKey } 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 extractSearchImagesFromTools(tools = [], query = '') {
+  const images = [];
+  const seen = new Set();
+  const add = (img) => {
+    const url = img?.imageUrl || img?.thumbUrl || img?.url || img?.src || img?.image;
+    if (!url || typeof url !== 'string' || seen.has(url)) return;
+    seen.add(url);
+    images.push({
+      title: img.title || img.alt || query || 'Ju Jingyi',
+      imageUrl: url,
+      thumbUrl: img.thumbUrl || img.imageUrl || url,
+      source: img.source || 'Search'
+    });
+  };
+
+  for (const t of tools) {
+    const res = t?.result;
+    if (!res) continue;
+    if (Array.isArray(res.images)) res.images.forEach(add);
+    if (Array.isArray(res.photos)) res.photos.forEach(add);
+    if (t.name === 'search_web_images' && Array.isArray(res.results)) res.results.forEach(add);
+    if (Array.isArray(res.works)) {
+      res.works.forEach(w => {
+        if (w.poster) add({ title: w.titleTh || w.titleCn || w.titleEn, imageUrl: w.poster, source: 'Series Poster' });
+      });
+    }
+  }
+
+  const rowAlignedCount = Math.floor(images.length / 3) * 3;
+  if (rowAlignedCount >= 3) {
+    return images.slice(0, Math.min(rowAlignedCount, 9));
+  }
+  return images.slice(0, 6);
+}
+
+
+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;
+}
+
+
+const recentSuggestionKeys = new Map();
+
+function getRecentSuggestionSet(sessionKey) {
+  let set = recentSuggestionKeys.get(sessionKey);
+  if (!set) {
+    set = new Set();
+    recentSuggestionKeys.set(sessionKey, set);
+    if (recentSuggestionKeys.size > 200) {
+      const oldest = recentSuggestionKeys.keys().next().value;
+      recentSuggestionKeys.delete(oldest);
+    }
+  }
+  return set;
+}
+
+function finalizeSuggestions(sessionKey, baseSuggestions, { query, answer, tools }) {
+  const recentKeys = getRecentSuggestionSet(sessionKey);
+  let out = dedupeSuggestions(Array.isArray(baseSuggestions) ? baseSuggestions : [], recentKeys);
+  if (out.length < 3) {
+    const dynamic = generateDynamicFollowUps({ query, answer, tools, recentKeys });
+    const localSeen = new Set(recentKeys);
+    for (const s of out) localSeen.add(normalizeSuggestionKey(s.query || s.label));
+    out = [...out, ...dedupeSuggestions(dynamic, localSeen)].slice(0, 3);
+  }
+  if (out.length) {
+    const set = getRecentSuggestionSet(sessionKey);
+    for (const s of out) {
+      set.add(normalizeSuggestionKey(s.query || s.label));
+      if (set.size > 60) {
+        const oldest = set.values().next().value;
+        set.delete(oldest);
+      }
+    }
+  }
+  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 sessionKey = String(body.sessionId || 'global');
+  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,
+      baseUrl: typeof body.baseUrl === 'string' && body.baseUrl.trim() ? body.baseUrl.trim() : undefined,
+    }, { signal: abortController.signal });
+
+  
+    const queryForAgent = conversationContext.resolvedQuery;
+    const systemDirectives = [
+      `[SYSTEM DIRECTIVE (Fact Grounding & Multi-Domain Retrieval):
+1. อ้างอิงเฉพาะเพลง ซีรีส์ แบรนด์พรีเซนเตอร์ และข้อมูลจริงที่ได้จากผลลัพธ์เครื่องมือ (search_works, search_discography, get_brand_endorsements, get_character_roles, get_awards, get_career_timeline, search_bilibili, search_chinese_web, web_search, get_media_links) เท่านั้น ห้ามแต่งชื่อผลงาน ชื่อแบรนด์ ตัวเลข หรือลิงก์สื่อขึ้นเอง หากตรวจสอบเครื่องมือที่เกี่ยวข้องแล้วไม่พบ จึงแจ้งผู้ใช้ตามหลักฐานจริง
+2. เมื่อพูดถึงเพลงหรือแบรนด์ใด ให้ระบุ "ชื่อจริง" จากคลังข้อมูลกำกับในประโยคเสมอ (เช่น "เพลง 千年等一回", "แบรนด์ PRSR (帕莎眼镜)") และห้ามแนบ URL ที่ไม่ได้มาจากผลลัพธ์เครื่องมือโดยเด็ดขาด
+3. เงื่อนไขการเสนอเปิดเพลงใน Mini Player: ให้เสนอเปิดเพลงเฉพาะเมื่อผู้ใช้ถามเรื่องบทเพลง การฟังเพลง หรือ OST โดยตรงเท่านั้น และต้องระบุชื่อเพลงที่เจาะจงในประโยคเดียวกัน ห้ามเสนอเปิดเพลงหรือถามชวนเปิดเพลงเมื่อผู้ใช้ถามเรื่องซีรีส์ แบรนด์ ข่าวลือ หรือเนื้อหาทั่วไป
+4. การแยกแยะชื่อเรื่อง แบรนด์ และข่าวลือ (Entity Disambiguation & Anti-Hallucination): ตรวจสอบชื่อเฉพาะให้ตรงกับเอนทิตีที่ถูกต้อง (เช่น เมื่อค้นหาแคมเปญโฆษณาหรือแบรนด์ ให้ตรวจสอบด้วย get_brand_endorsements และค้นหาคลิปบน Bilibili ควบคู่กับชื่อภาษาจีนของแบรนด์ เช่น 帕莎/PRSR เสมอ; และห้ามเดาหรือจับคู่คำค้นหาที่ออกเสียงคล้ายกันเข้ากับผลงานอื่นในคลังโดยไม่มีหลักฐานเด็ดขาด)
+5. หากผู้ใช้ส่งคำว่า "ดำเนินการต่อ" หรือตอบตกลงต่อคำถามก่อนหน้า ให้ลงมือทำสิ่งที่เสนอไว้ทันทีด้วยข้อมูลจริงจากเครื่องมือ อย่าถามคำถามเดิมซ้ำอีก
+6. ข้อมูลที่เกี่ยวกับแบรนด์ สินค้า แคมเปญโฆษณา และสื่อบนแพลตฟอร์มโซเชียล (Bilibili, YouTube, Weibo): ให้ใช้ get_brand_endorsements ควบคู่กับ search_bilibili หรือ get_media_links เสมอ โดยระบุคำค้นภาษาจีนของศิลปินและแบรนด์อย่างครบถ้วน]`,
+
+      `[SYSTEM DIRECTIVE (Answer Quality for Drama Analysis):
+1. แยก "ข้อเท็จจริงจากเครื่องมือ" ออกจาก "บทวิเคราะห์" ให้ชัดเจน ห้ามนำเรื่องย่อไปสรุปเป็นเสียงวิจารณ์หรือการยอมรับของวงการ
+2. ห้ามเหมารวมว่าผลงานใหม่กว่าแปลว่าลึกกว่า สมจริงกว่า หรือแสดงดีกว่า ให้เทียบจากภาระของบท แรงขับของตัวละคร แนวเรื่อง และฉากที่มีหลักฐานเท่านั้น
+3. ห้ามใช้คำยกย่องแบบไม่มีหลักฐาน เช่น "ระดับแนวหน้า", "ไม่มีใครเทียบได้", "ก้าวข้ามไอดอลอย่างสมบูรณ์" หรือ "ได้รับรางวัลมากมาย"
+4. คะแนนในแคตตาล็อกที่ไม่มีชื่อแหล่งและเกณฑ์คะแนนเป็นเพียง metadata ภายใน ห้ามใช้ยืนยันคุณภาพและไม่ต้องแสดงในบทวิเคราะห์
+5. In Blossom: จวีจิ้งอีแสดงตัวตนของหยางไฉ่เวยภายใต้รูปลักษณ์ซ่างกวนจื่อหลัง premise การเปลี่ยนใบหน้า ไม่ใช่สองตัวละครอิสระที่สลับเล่นตลอดเรื่อง
+6. The Legend of White Snake: ไป๋ซู่เจินคือวิญญาณ/ปีศาจงูขาวที่แปลงเป็นหญิงมนุษย์ ส่วนสวี่เซียนคือมนุษย์ชาย ห้ามสลับเพศหรือเผ่าพันธุ์
+7. หากเป็นคำสั่ง "ดำเนินการต่อ" ให้ตอบเฉพาะมุมใหม่ที่ผู้ใช้ขอ ห้ามคัดลอกคำตอบก่อนหน้ามาตอบซ้ำ]`,
+
+      `[SYSTEM DIRECTIVE (Topic & Future-event Safety):
+1. คำถามสั้นที่มีสรรพนามหรืออ้างถึง "เรื่องนี้/งานนี้/ทำไม/น่าจับตามอง" ต้องยึดหัวข้อหลักล่าสุดในบทสนทนาก่อน ห้ามเปลี่ยนไปตอบเรื่องศิลปินเพียงเพราะ Persona หรือฐานข้อมูลเน้นศิลปิน
+2. วันนี้คือ ${conversationContext.today}. เหตุการณ์หลังวันนี้เป็นข้อมูลอนาคต: ใช้คำว่า "มีกำหนด", "มีรายงาน", หรือ "ยังไม่ยืนยัน" ตามหลักฐาน ห้ามฟันธงว่าได้รับเชิญหรือจะเข้าร่วมแน่นอนโดยไม่มีแหล่งทางการที่เป็นปัจจุบัน
+3. ห้ามนำวัน เดือน รายชื่อแขก หรือสถานะการเข้าร่วมจากงานคนละปีมาใช้กับฉบับปีปัจจุบัน หากต้องระบุวันที่แน่นอนหรือผู้เข้าร่วมงานอนาคต ให้ตรวจสอบด้วยเครื่องมือเว็บก่อน]`,
+
+      `[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(queryForAgent, {
+            signal: abortController.signal,
+            systemDirectives,
+            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;
+          }
+
+          suggestions = finalizeSuggestions(sessionKey, suggestions, { query, answer: finalAnswer, tools: toolsUsed });
+
+          const searchImages = extractSearchImagesFromTools(toolsUsed, query);
+
+          sendSse({
+            type: 'final',
+            answer: finalAnswer,
+            suggestions,
+            searchImages,
+            durationMs: Date.now() - startTime,
+            tokens: conn.agent?.lastTelemetry?.tokens || conn.agent?.session?.lastQueryTokens || null,
+            metrics: conn.agent?.lastQueryMetrics || 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 });
+          const fallbackImages = extractSearchImagesFromTools(fallback.tools, query);
+          sendSse({
+            type: 'final',
+            answer: applyFutureEventGuard(fallback.answer, { tools: fallback.tools }),
+            suggestions: finalizeSuggestions(sessionKey, fallback.suggestions || [], { query, answer: fallback.answer, tools: fallback.tools }),
+            searchImages: fallbackImages,
+            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 });
+      const fallbackImages = extractSearchImagesFromTools(fallback.tools, query);
+      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: finalizeSuggestions(sessionKey, fallback.suggestions || [], { query, answer: guardedFallbackAnswer, tools: fallback.tools }),
+        searchImages: fallbackImages,
+        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(queryForAgent, {
+          signal: abortController.signal,
+          systemDirectives,
+        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 = finalizeSuggestions(sessionKey, suggestions, { query, answer, tools: toolsUsed });
+      }
+
+      const searchImages = extractSearchImagesFromTools(toolsUsed, query);
+
+      return sendJson(res, 200, {
+        status: 'ok',
+        query,
+        persona,
+        answer,
+        suggestions,
+        searchImages,
+        thinking,
+        thinkingDurationMs,
+        tools: toolsUsed,
+        subagents: subagentActivity,
+        tokens: conn.agent?.lastTelemetry?.tokens || conn.agent?.session?.lastQueryTokens || null,
+        metrics: conn.agent?.lastQueryMetrics || 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 });
+    const searchImages = extractSearchImagesFromTools(fallback.tools, query);
+    return sendJson(res, 200, {
+      status: 'ok',
+      query,
+      persona,
+      answer: applyFutureEventGuard(fallback.answer, { tools: fallback.tools }),
+      suggestions: finalizeSuggestions(sessionKey, fallback.suggestions || [], { query, answer: fallback.answer, tools: fallback.tools }),
+      searchImages,
+      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);
+  }
+}