kiku-agent 1.0.11 → 1.2.0

package/server/agent/clarifyingQuestions.js

@@ -0,0 +1,1089 @@
+
+
+import { eventBus, Events } from './eventBus.js';
+
+// Languages supported by the clarifying-question system. Add a new code here
+// and fill its entries in the per-language `questions` / `options` maps below
+// to extend coverage.
+export const SUPPORTED_LANGUAGES = ['en', 'th', 'zh', 'ja', 'ko'];
+
+const LANGUAGE_ALIASES = {
+  jp: 'ja',
+  kr: 'ko',
+  cn: 'zh',
+  'zh-cn': 'zh',
+  'zh-hans': 'zh',
+  'zh-hant': 'zh',
+  'zh-tw': 'zh',
+  'zh-hk': 'zh',
+  'en-us': 'en',
+  'en-gb': 'en',
+  'th-th': 'th',
+  'ja-jp': 'ja',
+  'ko-kr': 'ko',
+};
+
+// Normalize any user/system supplied language tag (e.g. "JP", "zh-TW") to a
+// supported code; unknown tags fall back to English.
+export function normalizeLang(lang, fallback = 'en') {
+  if (!lang || typeof lang !== 'string') return fallback;
+  const key = lang.trim().toLowerCase().replace('_', '-');
+  if (SUPPORTED_LANGUAGES.includes(key)) return key;
+  if (LANGUAGE_ALIASES[key]) return LANGUAGE_ALIASES[key];
+  const short = key.split('-')[0];
+  if (SUPPORTED_LANGUAGES.includes(short)) return short;
+  return fallback;
+}
+
+const AMBIGUITY_PATTERNS = [
+  {
+    category: 'timeframe',
+    weight: 0.7,
+    detection: /\b(recent|latest|new|old|upcoming|past|this year|last year|this month|earliest|newest)\b|(ล่าสุด|ใหม่|เก่า|ย้อนหลัง|最新|最近|昔|以前|최신|최근|예전|최근작)/i,
+    questions: {
+      en: 'Could you specify the timeframe you\'re interested in? For example: 2024-2026, 2020-2023, or all time?',
+      th: 'กรุณาระบุช่วงเวลาที่สนใจ เช่น ปี 2024-2026, ปี 2020-2023 หรือทั้งหมด',
+      zh: '请问您感兴趣的时间范围是？例如：2024-2026年、2020-2023年、或全部时期？',
+      ja: 'ご興味のある期間を教えていただけますか？例：2024-2026年、2020-2023年、または全期間',
+      ko: '어떤 기간에 관심이 있으신가요? 예: 2024-2026년, 2020-2023년, 또는 전체 기간'
+    },
+    options: {
+      en: ['2024-2026 (latest)', '2020-2023', 'All time'],
+      th: ['2024-2026 (ล่าสุด)', '2020-2023', 'All time (ทั้งหมด)'],
+      zh: ['2024-2026 年（最新）', '2020-2023 年', '全部时期'],
+      ja: ['2024-2026年（最新）', '2020-2023年', '全期間'],
+      ko: ['2024-2026년 (최신)', '2020-2023년', '전체 기간']
+    }
+  },
+  {
+    category: 'scope',
+    weight: 0.6,
+    detection: /\b(all|every|list|show|tell me about|what about|how about|comprehensive|complete)\b|(ทั้งหมด|ทุกอย่าง|ภาพรวม|全部|一覧|まとめ|모든|전체|목록)/i,
+    questions: {
+      en: 'Would you like a comprehensive overview or a focused summary on a specific aspect?',
+      th: 'ต้องการภาพรวมที่ครอบคลุม หรือต้องการเน้นเฉพาะด้านใดด้านหนึ่ง?',
+      zh: '您想要全面的概览还是针对特定方面的重点介绍？',
+      ja: '包括的な概覧をご希望ですか、それとも特定の側面に絞った要約をご希望ですか？',
+      ko: '전체적인 개요를 원하시나요, 아니면 특정 측면에 집중한 요약을 원하시나요?'
+    },
+    options: {
+      en: ['Comprehensive overview', 'Focused summary', 'Key highlights only'],
+      th: ['ภาพรวมครอบคลุม', 'สรุปเฉพาะประเด็น', 'เฉพาะไฮไลต์สำคัญ'],
+      zh: ['全面概览', '聚焦摘要', '仅重点亮点'],
+      ja: ['包括的な概要', '要点を絞った要約', 'ハイライトのみ'],
+      ko: ['전체 개요', '핵심 요약', '주요 하이라이트만']
+    }
+  },
+  {
+    category: 'depth',
+    weight: 0.5,
+    detection: /\b(detailed|comprehensive|in-depth|brief|quick|summary|overview|explain|deep dive)\b|(ละเอียด|สรุป|เจาะลึก|ย่อ|詳しく|詳細|要約|자세히|요약|상세)/i,
+    questions: {
+      en: 'How detailed would you like the response to be?',
+      th: 'ต้องการคำตอบที่ละเอียดระดับไหน?',
+      zh: '您希望回答详细到什么程度？',
+      ja: '回答はどの程度の詳しさをご希望ですか？',
+      ko: '답변은 어느 정도 자세하게 원하시나요?'
+    },
+    options: {
+      en: ['Very detailed (full analysis)', 'Moderate (key points + details)', 'Brief (quick summary)'],
+      th: ['ละเอียดมาก (วิเคราะห์ครบ)', 'ปานกลาง (ประเด็นหลัก + รายละเอียด)', 'กระชับ (สรุปไว)'],
+      zh: ['非常详细（完整分析）', '适中（要点 + 细节）', '简短（快速总结）'],
+      ja: ['非常に詳しく（完全分析）', '普通（要点 + 詳細）', '簡潔に（クイック要約）'],
+      ko: ['매우 자세히 (전체 분석)', '보통 (핵심 + 세부)', '간결하게 (빠른 요약)']
+    }
+  },
+  {
+    category: 'comparison',
+    weight: 0.7,
+    detection: /\b(compare|vs|versus|difference|similar|better|worse|contrast|between)\b|(เปรียบเทียบ|เทียบกับ|ต่างกันยังไง|比較|違い|비교|차이)/i,
+    questions: {
+      en: 'Which specific items would you like me to compare?',
+      th: 'ต้องการให้เปรียบเทียบรายการใดเป็นพิเศษ?',
+      zh: '您希望我比较哪些具体项目？',
+      ja: '具体的にどの項目を比較しましょうか？',
+      ko: '구체적으로 어떤 항목을 비교해 드릴까요?'
+    },
+    options: {
+      en: ['Let me specify', 'Compare all available', 'Focus on top items'],
+      th: ['จะระบุเอง', 'เปรียบเทียบทั้งหมด', 'เน้นเฉพาะผลงานเด่น'],
+      zh: ['我来指定', '比较全部', '聚焦头部作品'],
+      ja: ['自分で指定する', 'すべて比較', '人気作に絞る'],
+      ko: ['직접 지정', '전체 비교', '대표작 집중']
+    }
+  },
+  {
+    category: 'media_type',
+    weight: 0.8,
+    detection: /\b(songs?|music|videos?|dramas?|works?|albums?|singles?|ost|stage|performance|mv)\b|(เพลง|ซีรีส์|ละคร|ผลงาน|สเตจ|คอนเสิร์ต|ドラマ|曲|歌|アルバム|シングル|노래|음악|드라마|앨범|작품)/i,
+    questions: {
+      en: 'Are you looking for her acting works (dramas) or music works?',
+      th: 'สนใจผลงานการแสดงซีรีส์ หรือผลงานเพลงเป็นพิเศษคะ?',
+      zh: '您是想了解影视剧作品还是音乐作品？',
+      ja: '演技作品（ドラマ）と音楽作品のどちらにご興味がありますか？',
+      ko: '연기 작품(드라마)과 음악 작품 중 어느 쪽에 관심이 있으신가요?'
+    },
+    options: {
+      en: ['Dramas', 'Music & OSTs', 'All types'],
+      th: ['Dramas (ซีรีส์ / ละคร)', 'Music (ผลงานเพลง / OST)', 'All types (รวมทุกประเภท)'],
+      zh: ['影视剧作品', '音乐与 OST', '全部类型'],
+      ja: ['ドラマ作品', '楽曲・OST', 'すべて'],
+      ko: ['드라마 작품', '음악·OST', '전체 유형']
+    }
+  },
+  {
+    category: 'language',
+    weight: 0.4,
+    detection: /\b(chinese|thai|english|cn|th|en)\b|(中文|ไทย|ภาษาไทย|ภาษาจีน|ภาษาอังกฤษ|日本語|韓国語|タイ語|中国語|일본어|한국어|태국어)/i,
+    questions: {
+      en: 'Would you prefer the response in a specific language?',
+      th: 'ต้องการคำตอบเป็นภาษาใด?',
+      zh: '您希望用哪种语言回答？',
+      ja: '回答は特定の言語をご希望ですか？',
+      ko: '답변을 특정 언어로 받기를 원하시나요?'
+    },
+    options: {
+      en: ['Match my language', 'Thai', 'Chinese', 'English'],
+      th: ['ตามภาษาที่ฉันใช้', 'ไทย', 'จีน', 'อังกฤษ'],
+      zh: ['跟随我的语言', '泰语', '中文', '英语'],
+      ja: ['この会話の言語に合わせる', 'タイ語', '中国語', '英語'],
+      ko: ['사용 중인 언어에 맞춤', '태국어', '중국어', '영어']
+    }
+  },
+  {
+    category: 'specific_work',
+    weight: 0.8,
+    detection: /(?:\b(drama|series|movie|film|show|showcase)\b|(ซีรีส์|ละคร|หนัง|ドラマ|映画|드라마|영화)).*(?:\b(which|what|tell|about|info|recommend)\b|(เรื่องไหน|แนะนำ|มีเรื่อง|เรื่องอะไร|どの|おすすめ|어느|추천))/i,
+    questions: {
+      en: 'Which specific drama or work are you interested in?',
+      th: 'สนใจซีรีส์หรือผลงานเรื่องใดเป็นพิเศษ?',
+      zh: '您对哪部具体的电视剧或作品感兴趣？',
+      ja: 'どのドラマや作品にご興味がありますか？',
+      ko: '어떤 드라마나 작품에 관심이 있으신가요?'
+    },
+    options: {
+      en: ['In Blossom (花间令)', 'Legend of Yunxi (芸汐传)', 'Sword and Fairy 4 (仙剑四)', 'All works'],
+      th: ['In Blossom (ฮวาเจียนลิ่ง)', 'Legend of Yunxi (ตำนานหยุนซี)', 'Sword and Fairy 4 (เซียนกระบี่ 4)', 'All works (ดูซีรีส์ทั้งหมด)'],
+      zh: ['《花间令》', '《芸汐传》', '《仙剑四》', '全部作品'],
+      ja: ['『花間令』(In Blossom)', '『芸汐伝』(Legend of Yunxi)', '『仙剣四』(Sword and Fairy 4)', 'すべての作品'],
+      ko: ['In Blossom (화간령)', 'Legend of Yunxi (윤희전)', 'Sword and Fairy 4 (선검사)', '전체 작품']
+    }
+  },
+  {
+    category: 'aspect_focus',
+    weight: 0.6,
+    detection: /\b(role|character|actor|acting|perform|portray)\b|(บทบาท|ตัวละคร|การแสดง|เบื้องหลัง|役|演技|配役|배역|연기|캐릭터)/i,
+    questions: {
+      en: 'Would you like to focus on the acting performance, character analysis, or behind-the-scenes details?',
+      th: 'ต้องการเน้นที่การแสดง วิเคราะห์ตัวละคร หรือเบื้องหลัง?',
+      zh: '您想关注表演分析、角色解读还是幕后花絮？',
+      ja: '演技の評価、キャラクター分析、メイキングのどれに注目しますか？',
+      ko: '연기력, 캐릭터 분석, 비하인드 중 어느 쪽에 집중할까요?'
+    },
+    options: {
+      en: ['Acting performance', 'Character analysis', 'Behind-the-scenes', 'All aspects'],
+      th: ['การแสดง', 'วิเคราะห์ตัวละคร', 'เบื้องหลัง', 'ทุกด้าน'],
+      zh: ['演技表现', '角色分析', '幕后花絮', '全部'],
+      ja: ['演技', 'キャラクター分析', 'メイキング・舞台裏', 'すべて'],
+      ko: ['연기', '캐릭터 분석', '비하인드', '전체']
+    }
+  },
+  {
+    category: 'date_range',
+    weight: 0.7,
+    detection: /\b(between|from|to|until|since|during|before|after|period|era)\b|(ช่วงปี|ตั้งแต่|ถึงปี|ยุค|期間|時代|年代|기간|시대|연도)/i,
+    questions: {
+      en: 'Could you specify the exact date range or period you\'re interested in?',
+      th: 'กรุณาระบุช่วงวันที่หรือระยะเวลาที่ชัดเจน',
+      zh: '请具体说明您感兴趣的日期范围或时期',
+      ja: '正確な期間や時代をご指定いただけますか？',
+      ko: '정확한 기간이나 시대를 알려주시겠어요?'
+    },
+    options: {
+      en: ['2024-2026', '2020-2024', 'Career total'],
+      th: ['ปี 2024-2026', 'ปี 2020-2024', 'ตลอดการงานอาชีพ'],
+      zh: ['2024-2026 年', '2020-2024 年', '出道至今'],
+      ja: ['2024-2026年', '2020-2024年', 'キャリア全体'],
+      ko: ['2024-2026년', '2020-2024년', '데뷔 전체']
+    }
+  },
+  {
+    category: 'content_format',
+    weight: 0.5,
+    detection: /\b(list|table|chart|summary|bullet|paragraph|essay|short|long)\b|(ตาราง|สรุป|ลิสต์|ข้อความสั้น|表|箇条書き|リスト|표|목록|글머리)/i,
+    questions: {
+      en: 'What format would you prefer for the response?',
+      th: 'ต้องการรูปแบบคำตอบแบบใด?',
+      zh: '您希望回答采用什么格式？',
+      ja: '回答はどの形式がよろしいですか？',
+      ko: '답변은 어떤 형식을 원하시나요?'
+    },
+    options: {
+      en: ['Detailed paragraphs', 'Bullet points', 'Summary table'],
+      th: ['ย่อหน้าละเอียด', 'รายการหัวข้อ (bullet)', 'ตารางสรุป'],
+      zh: ['详细段落', '要点列表', '汇总表格'],
+      ja: ['詳しい段落', '箇条書き', 'まとめ表'],
+      ko: ['상세 문단', '글머리 기호', '요약 표']
+    }
+  },
+  {
+    category: 'career_phase',
+    weight: 0.75,
+    detection: /\b(snh48|snh|group|solo|idol)\b|(วง|เดี่ยว|ไอดอล|ยุควง|ช่วงวง|ソロ|アイドル|グループ|솔로|아이돌|그룹)/i,
+    questions: {
+      en: 'Are you interested in her Solo artist works or SNH48 idol group era?',
+      th: 'สนใจผลงานช่วงศิลปินเดี่ยว (Solo) หรือช่วงไอดอลวง SNH48 คะ?',
+      zh: '请问您想了解个人 Solo 时期还是 SNH48 组合时期？',
+      ja: 'ソロアーティスト時代と SNH48 アイドルグループ時代、どちらに興味がありますか？',
+      ko: '솔로 아티스트 시절과 SNH48 그룹 시절 중 어느 쪽에 관심이 있으신가요?'
+    },
+    options: {
+      en: ['Solo works', 'SNH48 era', 'All eras'],
+      th: ['Solo works (ผลงานเดี่ยว)', 'SNH48 era (ช่วงวง SNH48)', 'All eras (ทุกช่วงเวลา)'],
+      zh: ['个人 Solo 时期', 'SNH48 组合时期', '全部时期'],
+      ja: ['ソロ活動', 'SNH48 時代', '全期間'],
+      ko: ['솔로 활동', 'SNH48 시절', '전체 시기']
+    }
+  }
+];
+
+// Resolve a pattern's question + options for a given language with English fallback.
+function localizePattern(pattern, lang) {
+  const questions = pattern.questions || {};
+  const options = pattern.options || {};
+  return {
+    category: pattern.category,
+    weight: pattern.weight,
+    question: questions[lang] || questions.en,
+    options: options[lang] || options.en || [],
+  };
+}
+
+export function calculateConfidence(query, detectedAmbiguities = []) {
+  if (!query || typeof query !== 'string') {
+    return { score: 0, level: 'very_low', shouldAsk: true };
+  }
+
+  const trimmed = query.trim();
+  let score = 1.0;
+
+  // CJK scripts do not separate words with spaces, so estimate word count from
+  // character length instead to avoid unfairly penalizing zh/ja/ko queries.
+  const cjkChars = (trimmed.match(/[\u3040-\u30FF\u3400-\u9FFF\uAC00-\uD7AF]/g) || []).length;
+  const wordCount = cjkChars > 0
+    ? Math.max(1, Math.round(cjkChars / 2))
+    : trimmed.split(/\s+/).length;
+  if (wordCount < 3) score -= 0.3;
+  else if (wordCount < 5) score -= 0.1;
+  else if (wordCount > 15) score += 0.1;
+
+  const knownWorksOrCharacters = /(花间令|花間令|In Blossom|ฮวาเจียนลิ่ง|芸汐传|芸汐伝|Yunxi|หยุนซี|新白娘子传奇|White Snake|นางพญางูขาว|如意芳霏|The Blooms at Ruyi Pavilion|กรุ่นรักกลิ่นบุปผา|嘉南传|嘉南傳|Rebirth For You|มู่หนานจือ|仙剑四|仙劍四|Sword and Fairy|เซียนกระบี่|杨采薇|上官芷|หยางไฉ่เวย|ซ่างกวนจื่อ|韩芸汐|หานหยุนซี|白素贞|ไป๋ซู่เจิน|傅容|ฟู่หรง|姜保宁|เจียงเป่าหนิง|韩菱纱|หานหลิงซา)/i;
+  if (knownWorksOrCharacters.test(trimmed)) {
+    return {
+      score: 0.95,
+      level: 'high',
+      shouldAsk: false,
+      reasoning: 'High confidence: specific work or character explicitly identified in query.'
+    };
+  }
+
+  const specificityPatterns = [
+    /\b(exactly|specifically|precisely|particular)\b/i,
+    /\b\d{4}\b/,
+    /["'"]/,
+    /\b(by|from|in|at|on)\b.*\b(Ju Jingyi|鞠婧祎|จวีจิ้งอี)\b/i,
+  ];
+
+  for (const pattern of specificityPatterns) {
+    if (pattern.test(trimmed)) score += 0.15;
+  }
+
+  if (/^(what|who|when|where|how|which|why|tell me|show me|list|compare)\b/i.test(trimmed)) {
+    score += 0.1;
+  }
+
+  for (const ambiguity of detectedAmbiguities) {
+    score -= (ambiguity.weight || 0.5) * 0.3;
+  }
+
+  score = Math.max(0, Math.min(1, score));
+
+  let level;
+  if (score >= 0.8) level = 'high';
+  else if (score >= 0.6) level = 'medium';
+  else if (score >= 0.4) level = 'low';
+  else level = 'very_low';
+
+  return {
+    score,
+    level,
+    shouldAsk: score < 0.65,
+    reasoning: `Confidence: ${(score * 100).toFixed(0)}% (${level}). ${detectedAmbiguities.length} ambiguities detected.`
+  };
+}
+
+export function detectAmbiguities(query, detectedLang = 'en') {
+  if (!query || typeof query !== 'string') return [];
+
+  const lang = normalizeLang(detectedLang);
+  const detected = [];
+  const seenCategories = new Set();
+
+  for (const pattern of AMBIGUITY_PATTERNS) {
+    if (seenCategories.has(pattern.category)) continue;
+
+    if (pattern.detection.test(query)) {
+      seenCategories.add(pattern.category);
+      detected.push({
+        category: pattern.category,
+        question: pattern.questions[lang] || pattern.questions.en,
+        options: pattern.options[lang] || pattern.options.en,
+        weight: pattern.weight,
+      });
+    }
+  }
+
+  return detected;
+}
+
+// Known Ju Jingyi works/characters so clarifying questions can reference the
+// actual subject of the user's query instead of generic facet questions.
+const KNOWN_ENTITY_PATTERNS = [
+  {
+    key: 'in_blossom',
+    labels: { en: 'In Blossom (花间令)', th: 'อินบลอสซัม/ฮวาเจียนหลิง (In Blossom)', zh: '《花间令》', ja: '『花間令』(In Blossom)', ko: 'In Blossom (화간령)' },
+  },
+  {
+    key: 'legend_of_yunxi',
+    labels: { en: 'Legend of Yunxi (芸汐传)', th: 'ตำนานหยุนซี (Legend of Yunxi)', zh: '《芸汐传》', ja: '『芸汐伝』(Legend of Yunxi)', ko: 'Legend of Yunxi (윤희전)' },
+  },
+  {
+    key: 'sword_fairy_4',
+    labels: { en: 'Sword and Fairy 4 (仙剑四)', th: 'เซียนกระบี่พิชิตมาร 4 (Sword and Fairy 4)', zh: '《仙剑四》', ja: '『仙剣四』(Sword and Fairy 4)', ko: 'Sword and Fairy 4 (선검사)' },
+  },
+  {
+    key: 'white_snake',
+    labels: { en: 'New Legend of Madame White Snake (新白娘子传奇)', th: 'นางพญางูขาว (New Legend of Madame White Snake)', zh: '《新白娘子传奇》', ja: '『新白娘子伝奇』(White Snake)', ko: 'New Legend of Madame White Snake (신백납자전기)' },
+  },
+  {
+    key: 'ruyi_pavilion',
+    labels: { en: 'The Blooms at Ruyi Pavilion (如意芳霏)', th: 'กรุ่นรักกลิ่นบุปผา (The Blooms at Ruyi Pavilion)', zh: '《如意芳霏》', ja: '『如意芳霏』(Ruyi Pavilion)', ko: 'The Blooms at Ruyi Pavilion (여의방비)' },
+  },
+  {
+    key: 'rebirth_for_you',
+    labels: { en: 'Rebirth For You (嘉南传)', th: 'กำเนิดใหม่เพื่อเธอ (Rebirth For You)', zh: '《嘉南传》', ja: '『嘉南伝』(Rebirth For You)', ko: 'Rebirth For You (가남전)' },
+  },
+  {
+    key: 'snh48',
+    labels: { en: 'SNH48 era', th: 'ยุควง SNH48', zh: 'SNH48 时期', ja: 'SNH48 時代', ko: 'SNH48 시절' },
+  },
+];
+
+export function stripSystemDirectives(text) {
+  if (!text || typeof text !== 'string') return '';
+  return text
+    .replace(/\[SYSTEM\s+[A-Z\s()&_-]+:[\s\S]*?\]/gi, '')
+    .replace(/\[SYSTEM:[^\]]*\]/gi, '')
+    .replace(/\[SYSTEM\s+NOTE:[^\]]*\]/gi, '')
+    .replace(/\[SYSTEM\s+INSTRUCTION:[^\]]*\]/gi, '')
+    .replace(/\[SYSTEM\s+DIRECTIVE:[^\]]*\]/gi, '')
+    .trim();
+}
+
+const KNOWN_ENTITY_REGEX = /(花间令|花間令|In Blossom|อินบลอสซัม|ฮวาเจียนหลิง|芸汐传|芸汐伝|Yunxi|ตำนานหยุนซี|หยุนซี|仙剑四|仙劍四|Sword and Fairy|เซียนกระบี่|新白娘子传奇|White Snake|นางพญางูขาว|如意芳霏|Ruyi Pavilion|กรุ่นรักกลิ่นบุปผา|嘉南传|嘉南傳|Rebirth For You|มู่หนานจือ|SNH48)/i;
+
+// Returns a recognized topic label (localized) that appears in the query, or null.
+function extractQueryTopic(query, lang) {
+  if (!query || typeof query !== 'string') return null;
+  const clean = stripSystemDirectives(query);
+  const hit = KNOWN_ENTITY_PATTERNS.find(p => {
+    try { return new RegExp(escapeRegex(p.key) + '|' + entityRegexFor(p.key), 'i').test(clean); } catch { return false; }
+  });
+  if (hit) return (hit.labels && hit.labels[lang]) || hit.labels.en;
+  const rawMatch = clean.match(KNOWN_ENTITY_REGEX);
+  if (rawMatch) return rawMatch[0];
+  return null;
+}
+
+function entityRegexFor(key) {
+  const map = {
+    in_blossom: '花间令|花間令|In Blossom|อินบลอสซัม|ฮวาเจียนหลิง',
+    legend_of_yunxi: '芸汐传|芸汐伝|Yunxi|ตำนานหยุนซี|หยุนซี',
+    sword_fairy_4: '仙剑四|仙劍四|Sword and Fairy|เซียนกระบี่',
+    white_snake: '新白娘子传奇|White Snake|นางพญางูขาว',
+    ruyi_pavilion: '如意芳霏|Ruyi Pavilion|กรุ่นรักกลิ่นบุปผา',
+    rebirth_for_you: '嘉南传|嘉南傳|Rebirth For You|มู่หนานจือ',
+    snh48: 'SNH48',
+  };
+  return map[key] || '';
+}
+
+function escapeRegex(str) {
+  return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Extract a short noun phrase that likely represents the topic (fallback when no known entity).
+function extractQueryPhrase(query) {
+  if (!query || typeof query !== 'string') return '';
+  const cleaned = stripSystemDirectives(query)
+    .replace(/\b(please|pls|tell me|show me|give me|about|regarding|hello|hi|hey)\b/gi, ' ')
+    .replace(/[?!。.,，]+$/g, '')
+    .trim();
+  const tokens = cleaned.split(/\s+/).filter(Boolean);
+  if (tokens.length <= 4) return cleaned;
+  return tokens.slice(0, 4).join(' ');
+}
+
+function synthesizeDynamicQuestions(query, lang = 'en', detectedAmbiguities = [], maxQuestions = 4) {
+  const results = [];
+  const addedCategories = new Set();
+
+  const addQ = (category, question, options) => {
+    if (!addedCategories.has(category) && results.length < maxQuestions) {
+      addedCategories.add(category);
+      results.push({ category, question, options });
+    }
+  };
+
+  const topic = extractQueryTopic(query, lang) || extractQueryPhrase(query) || null;
+
+  // 1) Subject-aware questions that reference the actual topic the user asked about,
+  //    so the clarifying questions feel directly connected to the query.
+  if (topic) {
+    const subject = String(topic).trim();
+    if (!addedCategories.has('subject_focus') && results.length < maxQuestions) {
+      if (lang === 'th') {
+        addQ('subject_focus', `เกี่ยวกับ "${subject}" นี้ คุณสนใจเจาะลึกด้านใดเป็นพิเศษคะ?`, [
+          'บทบาทและการแสดง',
+          'ตัวละครและเนื้อเรื่อง',
+          'กระแสตอบรับและรางวัล',
+          'รายละเอียดเบื้องหลัง'
+        ]);
+      } else if (lang === 'zh') {
+        addQ('subject_focus', `关于「${subject}」，您最想深入了解哪一方面？`, [
+          '角色与演技',
+          '故事与人设',
+          '口碑与奖项',
+          '幕后花絮'
+        ]);
+      } else if (lang === 'ja') {
+        addQ('subject_focus', `「${subject}」について、特にどの面を深掘りしましょうか？`, [
+          '演技と役柄',
+          'ストーリーとキャラクター',
+          '評価と賞',
+          'メイキング・舞台裏'
+        ]);
+      } else if (lang === 'ko') {
+        addQ('subject_focus', `"${subject}"에 대해 어떤 부분을 가장 깊이 알아볼까요?`, [
+          '연기와 배역',
+          '스토리와 캐릭터',
+          '평가와 수상',
+          '비하인드'
+        ]);
+      } else {
+        addQ('subject_focus', `About "${subject}" specifically, which aspect interests you most?`, [
+          'Acting & performance',
+          'Story & characters',
+          'Reception & awards',
+          'Behind-the-scenes'
+        ]);
+      }
+    }
+    if (!addedCategories.has('subject_scope') && results.length < maxQuestions && detectedAmbiguities.length === 0) {
+      if (lang === 'th') {
+        addQ('subject_scope', `ต้องการเน้นเฉพาะ "${subject}" นี้ หรือให้เชื่อมโยงกับผลงานอื่นๆ ของจวีจิ้งอีด้วยคะ?`, [
+          `เฉพาะ "${subject}"`,
+          'เชื่อมโยงกับผลงานอื่น',
+          'ภาพรวมทั้งหมด'
+        ]);
+      } else if (lang === 'zh') {
+        addQ('subject_scope', `您希望只围绕「${subject}」，还是也想关联她的其他作品？`, [
+          `仅「${subject}」`,
+          '关联其他作品',
+          '整体概述'
+        ]);
+      } else if (lang === 'ja') {
+        addQ('subject_scope', `「${subject}」だけに絞りますか、それとも他の作品とも絡めて紹介しましょうか？`, [
+          `「${subject}」のみ`,
+          '他の作品とも関連付け',
+          '全体概観'
+        ]);
+      } else if (lang === 'ko') {
+        addQ('subject_scope', `"${subject}"에만 집중할까요, 아니면 다른 작품과도 연결해서 알아볼까요?`, [
+          `"${subject}"만`,
+          '다른 작품과도 연결',
+          '전체 개요'
+        ]);
+      } else {
+        addQ('subject_scope', `Should we focus only on "${subject}" or also relate it to her other works?`, [
+          `Only "${subject}"`,
+          'Relate to other works',
+          'Overall overview'
+        ]);
+      }
+    }
+  }
+
+  // 2) Specific detected ambiguity categories (from the query).
+  if (Array.isArray(detectedAmbiguities) && detectedAmbiguities.length > 0) {
+    for (const amb of detectedAmbiguities) {
+      if (amb.category && amb.question && amb.options && !addedCategories.has(amb.category)) {
+        addQ(amb.category, amb.question, (amb.options || []).slice(0, 4));
+      }
+    }
+  }
+
+  // 3) Generic facet fillers to reach the target count.
+  if (lang === 'th') {
+    addQ('media_type', 'อยากให้เน้นผลงานการแสดงซีรีส์ หรือผลงานเพลงเดี่ยวและเพลงประกอบ (OST) คะ?', [
+      'ผลงานซีรีส์ (Dramas)',
+      'ผลงานเพลงเดี่ยวและ OST',
+      'รวมทุกประเภทผลงาน'
+    ]);
+    addQ('career_phase', 'คุณสนใจผลงานช่วงศิลปินเดี่ยวและนักแสดงในปัจจุบัน หรือช่วงยุคไอดอลวง SNH48 คะ?', [
+      'ศิลปินเดี่ยวปัจจุบัน (Solo)',
+      'ช่วงยุควง SNH48',
+      'ทุกช่วงเวลาทั้งหมด'
+    ]);
+    addQ('timeframe', 'ต้องการให้อัปเดตผลงานช่วงล่าสุด (ปี 2024-2026) หรือดูผลงานสร้างชื่อในอดีตคะ?', [
+      'ผลงานล่าสุด (2024-2026)',
+      'ผลงานสร้างชื่อในอดีต',
+      'ผลงานทั้งหมดตลอดกาล'
+    ]);
+    addQ('depth', 'ต้องการคำตอบแบบสรุปประเด็นสำคัญ หรือเจาะลึกรายละเอียดและเรื่องย่อเบื้องหลังคะ?', [
+      'สรุปกระชับ ได้ใจความ',
+      'เจาะลึกละเอียด ครบถ้วน',
+      'ไฮไลต์ยอดนิยม'
+    ]);
+    if (results.length < maxQuestions) {
+      addQ('aspect_focus', 'สนใจเจาะลึกด้านบทบาทการแสดง ตัวละคร หรือกระแสตอบรับและรางวัลคะ?', [
+        'บทบาทและการแสดง',
+        'ตัวละครและเนื้อเรื่อง',
+        'กระแสตอบรับและรางวัล'
+      ]);
+    }
+  } else if (lang === 'zh') {
+    addQ('media_type', '请问您希望重点了解影视剧作品，还是个人单曲与影视原声 (OST)？', [
+      '影视剧作品 (Dramas)',
+      '个人单曲与 OST',
+      '全方位作品介绍'
+    ]);
+    addQ('career_phase', '请问您想了解个人 Solo 时期作品，还是 SNH48 组合时期的舞台？', [
+      '个人 Solo 时期作品',
+      'SNH48 组合时期',
+      '全部演艺阶段'
+    ]);
+    addQ('timeframe', '请问您想了解近年 (2024-2026) 的最新动态，还是历年经典代表作？', [
+      '最新动态 (2024-2026)',
+      '历年经典代表作',
+      '历年全部作品'
+    ]);
+    addQ('depth', '您希望获取快速简练的重点总结，还是包含剧情与幕后细节的深度解读？', [
+      '精简要点总结',
+      '深度详尽解读',
+      '热门高光盘点'
+    ]);
+    if (results.length < maxQuestions) {
+      addQ('aspect_focus', '您想重点了解角色演技、故事设定还是作品热度与奖项？', [
+        '角色表现与演技',
+        '故事与人设解读',
+        '热度口碑与奖项'
+      ]);
+    }
+  } else if (lang === 'ja') {
+    addQ('media_type', '演技ドラマ作品と、ソロ楽曲や映画・ドラマの主題歌 (OST)、どちらを重視しましょうか？', [
+      'ドラマ作品',
+      '楽曲・OST',
+      'すべての作品'
+    ]);
+    addQ('career_phase', '現在のソロ活動と、SNH48 アイドルグループ時代のどちらが気になりますか？', [
+      '現在のソロ活動',
+      'SNH48 時代',
+      '全期間'
+    ]);
+    addQ('timeframe', '最近の活動 (2024-2026) と、過去の代表作のどちらをご覧になりたいですか？', [
+      '最新の活動 (2024-2026)',
+      '過去の代表作',
+      '全期間の作品'
+    ]);
+    addQ('depth', '簡潔な要約と、詳細な解説のどちらをご希望ですか？', [
+      '簡潔な要約',
+      '詳細な解説',
+      '人気ハイライト'
+    ]);
+    if (results.length < maxQuestions) {
+      addQ('aspect_focus', '演技、キャラクター、評価・賞のどれを深掘りしましょうか？', [
+        '演技と役柄',
+        'キャラクターとストーリー',
+        '評価と賞'
+      ]);
+    }
+  } else if (lang === 'ko') {
+    addQ('media_type', '연기 드라마 작품과 솔로 곡·주제가 (OST) 중 어떤 것을 중점적으로 볼까요?', [
+      '드라마 작품',
+      '솔로 곡·OST',
+      '전체 작품'
+    ]);
+    addQ('career_phase', '현재 솔로 활동과 SNH48 아이돌 그룹 시절 중 어떤 시기가 궁금하신가요?', [
+      '현재 솔로 활동',
+      'SNH48 시절',
+      '전체 시기'
+    ]);
+    addQ('timeframe', '최근 활동 (2024-2026)과 대표작 중 어떤 것을 볼까요?', [
+      '최근 활동 (2024-2026)',
+      '대표작',
+      '전체 작품'
+    ]);
+    addQ('depth', '간결한 요약과 상세한 해설 중 어떤 걸 원하시나요?', [
+      '간결한 요약',
+      '상세한 해설',
+      '인기 하이라이트'
+    ]);
+    if (results.length < maxQuestions) {
+      addQ('aspect_focus', '연기, 캐릭터, 평가·수상 중 어떤 부분을 깊이 알아볼까요?', [
+        '연기와 배역',
+        '캐릭터와 스토리',
+        '평가와 수상'
+      ]);
+    }
+  } else {
+    addQ('media_type', 'Would you like to focus on her acting dramas, or her solo music and OSTs?', [
+      'Acting Dramas',
+      'Solo Music & OSTs',
+      'All Works'
+    ]);
+    addQ('career_phase', 'Are you interested in her current Solo career or her SNH48 idol group era?', [
+      'Current Solo works',
+      'SNH48 group era',
+      'All career eras'
+    ]);
+    addQ('timeframe', 'Would you prefer updates on her recent works (2024-2026) or her classic breakthrough hits?', [
+      'Recent works (2024-2026)',
+      'Classic breakthrough hits',
+      'All time works'
+    ]);
+    addQ('depth', 'Would you prefer a concise quick summary or an in-depth comprehensive breakdown?', [
+      'Concise summary',
+      'In-depth breakdown',
+      'Key highlights'
+    ]);
+    if (results.length < maxQuestions) {
+      addQ('aspect_focus', 'Would you like to focus on character portrayals, storylines, or reception & awards?', [
+        'Character & Acting',
+        'Story & Lore',
+        'Reception & Awards'
+      ]);
+    }
+  }
+
+  return results.slice(0, maxQuestions);
+}
+
+function extractJsonArray(text) {
+  if (!text || typeof text !== 'string') return null;
+  let cleaned = text.trim();
+  const fenceMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+  if (fenceMatch) {
+    cleaned = fenceMatch[1].trim();
+  }
+  const firstBracket = cleaned.indexOf('[');
+  const lastBracket = cleaned.lastIndexOf(']');
+  if (firstBracket !== -1 && lastBracket !== -1 && lastBracket > firstBracket) {
+    const candidate = cleaned.slice(firstBracket, lastBracket + 1);
+    try {
+      const parsed = JSON.parse(candidate);
+      if (Array.isArray(parsed) && parsed.length > 0) {
+        return parsed;
+      }
+    } catch {
+      try {
+        const repaired = candidate.replace(/,\s*([\]}])/g, '$1');
+        const parsed = JSON.parse(repaired);
+        if (Array.isArray(parsed) && parsed.length > 0) {
+          return parsed;
+        }
+      } catch { }
+    }
+  }
+  return null;
+}
+
+const LLM_SYSTEM_PROMPTS = {
+  th:
+    'คุณคือ Kiku AI ระบบผู้ช่วยอัจฉริยะทางการของ "จวีจิ้งอี" (Ju Jingyi / 鞠婧祎 / เสี่ยงจวี)\n' +
+    'หน้าที่: วิเคราะห์คำถามของผู้ใช้ และคิดคำถามเจาะจง 3-4 ข้ออย่างเป็นมิตร สุภาพ (ลงท้ายด้วย คะ/นะคะ) เพื่อถามกลับผู้ใช้ก่อนจะเริ่มค้นหาข้อมูลหรือเริ่มกระบวนการ Timeline Agent\n' +
+    'เป้าหมาย:\n' +
+    '1. เจาะลึกความต้องการให้แคบลงและตรงกับสิ่งที่ผู้ใช้ถามจริง (เช่น บทบาท/ตัวละคร, ผลงานซีรีส์ vs เพลง, ช่วงปี พ.ศ./ค.ศ., ยุคปัจจุบัน vs ไอดอล SNH48, ความละเอียดของข้อมูล)\n' +
+    '2. แต่ละข้อต้องให้ตัวเลือกคำตอบ 2-4 ตัวเลือกที่เกี่ยวข้องโดยตรงเพื่อให้ผู้ใช้กดเลือกได้ทันที\n' +
+    '3. ห้ามพูดนอกเรื่อง หรือแต่งประโยคระบบคำสั่งลงในคำถาม\n' +
+    '4. ส่งคำตอบเป็น JSON Array เท่านั้น ห้ามใส่คำอธิบายอื่นนอกเหนือจาก JSON:\n' +
+    '[{"category": "subject_focus", "question": "คำถามภาษาไทย", "options": ["ตัวเลือก 1", "ตัวเลือก 2", "ตัวเลือก 3"]}]',
+  zh:
+    '你是鞠婧祎官方智能粉丝助手 Kiku。\n' +
+    '任务：根据用户的提问，主动思考并提出 3-4 个礼貌贴切的追问（针对具体作品、角色、音乐还是影视、年份阶段、SNH48时期还是Solo、详略程度等不同维度），以便在进入 Timeline Agent 检索前准确定位用户需求。\n' +
+    '每个追问提供 2-4 个清晰选项。\n' +
+    '仅输出合法的 JSON Array 格式，不要包含任何多余文字：\n' +
+    '[{"category": "subject_focus", "question": "中文追问", "options": ["选项1", "选项2", "选项3"]}]',
+  ja:
+    'あなたは鞠婧祎（Ju Jingyi）公式ファンアシスタント「Kiku AI」です。\n' +
+    'タスク：ユーザーの質問を分析し、Timeline Agent が検索を始める前に意図を正確に把握できるよう、3〜4件の丁寧で的確な確認質問を日本語で生成してください（具体的な作品・役柄、ドラマか音楽か、Solo か SNH48 か、時期、詳しさなどの観点）。\n' +
+    '各質問には2〜4個の選択肢を付けてください。\n' +
+    'JSON配列のみを出力し、他の文章は含めないでください：\n' +
+    '[{"category": "subject_focus", "question": "日本語の質問", "options": ["選択肢1", "選択肢2", "選択肢3"]}]',
+  ko:
+    '당신은 Ju Jingyi(鞠婧祎) 공식 팬 어시스턴트 Kiku AI입니다.\n' +
+    '임무: 사용자의 질문을 분석하여 Timeline Agent가 검색을 시작하기 전에 의도를 정확히 파악할 수 있도록 3-4개의 정중한 확인 질문을 한국어로 생성하세요(구체적 작품·배역, 드라마 vs 음악, Solo vs SNH48, 시기, 상세도 등의 관점).\n' +
+    '각 질문에는 2-4개의 선택지를 제공하세요.\n' +
+    'JSON 배열만 출력하고 다른 문장은 포함하지 마세요:\n' +
+    '[{"category": "subject_focus", "question": "한국어 질문", "options": ["선택지1", "선택지2", "선택지3"]}]',
+  en:
+    'You are Kiku AI, the official assistant for Ju Jingyi (鞠婧祎).\n' +
+    'Task: Analyze the user inquiry and generate 3-4 polite, targeted clarifying questions across relevant dimensions (specific role/work, drama vs music, solo vs SNH48, timeframe, depth) to pinpoint their intent before the Timeline Agent begins searching.\n' +
+    'Provide 2-4 concise clickable options per question.\n' +
+    'Output ONLY a valid JSON Array with no other text:\n' +
+    '[{"category": "subject_focus", "question": "Question?", "options": ["Option 1", "Option 2", "Option 3"]}]',
+};
+
+// Shown when a model-generated question arrives without usable options.
+const FALLBACK_OPTIONS = {
+  en: ['Yes', 'No', 'All'],
+  th: ['ใช่', 'ไม่ใช่', 'ทั้งหมด'],
+  zh: ['是', '不是', '全部'],
+  ja: ['はい', 'いいえ', 'すべて'],
+  ko: ['네', '아니요', '전체'],
+};
+
+export async function generateClarifyingQuestions(query, lang = 'en', options = {}) {
+  const { conversationHistory = [], client = null, maxQuestions = 4, detectedAmbiguities = [] } = options;
+  const cleanQuery = stripSystemDirectives(query) || (typeof query === 'string' ? query.trim() : '');
+  const normalizedLang = normalizeLang(lang);
+
+  if (client && typeof client.chat === 'function') {
+    const recentHistory = conversationHistory
+      .slice(-4)
+      .map(msg => `${msg.role}: ${(stripSystemDirectives(msg.content) || msg.content || '').slice(0, 150)}`)
+      .filter(line => !line.startsWith('system:'))
+      .join('\n');
+
+    const ambiguityAreas = detectedAmbiguities.map(a => a.category).join(', ');
+
+    const systemPrompt = LLM_SYSTEM_PROMPTS[normalizedLang] || LLM_SYSTEM_PROMPTS.en;
+
+    const userPrompt = `User inquiry: "${cleanQuery}"\n${ambiguityAreas ? `Ambiguity cues: ${ambiguityAreas}\n` : ''}${recentHistory ? `Recent history:\n${recentHistory}` : ''}\n\nFormulate 3-4 targeted clarifying questions as JSON array:`;
+
+    try {
+      const controller = new AbortController();
+      const timeoutMs = options.timeoutMs || Math.min(client.timeout || 30000, 15000);
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+      const response = await client.chat({
+        messages: [
+          { role: 'system', content: systemPrompt },
+          { role: 'user', content: userPrompt }
+        ],
+        temperature: 0.3,
+        maxTokens: 600,
+        stream: false,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+
+      const content = response?.content || '';
+      const rawQuestions = extractJsonArray(content);
+      if (Array.isArray(rawQuestions) && rawQuestions.length >= 2) {
+        const fallbackOpts = FALLBACK_OPTIONS[normalizedLang] || FALLBACK_OPTIONS.en;
+        const validated = rawQuestions
+          .filter(q => q && typeof q.question === 'string' && q.question.trim().length > 0)
+          .map((q, idx) => ({
+            category: String(q.category || `clarify_${idx + 1}`).toLowerCase().replace(/[^a-z0-9_]/g, '_'),
+            question: q.question.trim(),
+            options: Array.isArray(q.options) && q.options.length > 0
+              ? q.options.map(opt => String(opt).trim()).filter(Boolean).slice(0, 4)
+              : [...fallbackOpts]
+          }));
+
+        if (validated.length >= 2) {
+          return validated.slice(0, maxQuestions);
+        }
+      }
+    } catch {
+      // Fast fallback to dynamic contextual synthesis if model call fails/times out
+    }
+  }
+
+  return synthesizeDynamicQuestions(cleanQuery, normalizedLang, detectedAmbiguities, maxQuestions);
+}
+
+export function isQueryTooVague(query) {
+  if (!query || typeof query !== 'string') return true;
+
+  const trimmed = query.trim();
+
+  if (trimmed.length < 3) return true;
+
+  // Punctuation/symbols only — treat as vague (includes CJK punctuation).
+  if (/^[^\w\u0E00-\u0E7F\u3040-\u30FF\u3400-\u9FFF\uAC00-\uD7AF]+$/.test(trimmed)) return true;
+
+  const words = trimmed.split(/\s+/);
+  if (words.length === 1 && words[0].length < 4) return true;
+
+  return false;
+}
+
+export function formatQuestionsForCLI(questions, colors = {}) {
+  if (!questions || questions.length === 0) return '';
+
+  const C = colors;
+  const lines = [];
+
+  lines.push(`${C.gold || ''}┌─ Clarifying Questions ─────────────────────────────┐${C.reset || ''}`);
+  lines.push(`${C.gold || ''}│${C.reset || ''} ${C.dim || ''}The agent detected some ambiguity in your query.${C.reset || ''}`);
+  lines.push(`${C.gold || ''}│${C.reset || ''} ${C.dim || ''}Answering these will help provide a more accurate response.${C.reset || ''}`);
+  lines.push(`${C.gold || ''}│${C.reset || ''}`);
+
+  questions.forEach((q, index) => {
+    lines.push(`${C.gold || ''}│${C.reset || ''} ${C.bold || ''}${C.roseGlow || ''}${index + 1}. ${q.category.toUpperCase()}${C.reset || ''}`);
+    lines.push(`${C.gold || ''}│${C.reset || ''}    ${C.white || ''}${q.question}${C.reset || ''}`);
+    if (q.options && q.options.length > 0) {
+      q.options.forEach((opt, i) => {
+        lines.push(`${C.gold || ''}│${C.reset || ''}      ${C.dim || ''}${String.fromCharCode(97 + i)}) ${opt}${C.reset || ''}`);
+      });
+    }
+    lines.push(`${C.gold || ''}│${C.reset || ''}`);
+  });
+
+  lines.push(`${C.gold || ''}│${C.reset || ''} ${C.dim || ''}Type your answers (e.g., "1a 2c") or "skip" to proceed without clarifying.${C.reset || ''}`);
+  lines.push(`${C.gold || ''}└────────────────────────────────────────────────────┘${C.reset || ''}`);
+
+  return lines.join('\n');
+}
+
+const SSE_INSTRUCTIONS = {
+  en: 'Answer the questions above to help the agent provide a more accurate response. Type "skip" to proceed without answering.',
+  th: 'ตอบคำถามด้านบนเพื่อช่วยให้ AI ตอบได้แม่นยำยิ่งขึ้น หรือพิมพ์ "skip" เพื่อข้ามและตอบตามเดิม',
+  zh: '请回答上面的问题，以便助手给出更准确的回答。输入 "skip" 可跳过。',
+  ja: '上記の質問に答えると、より正確な回答が届きます。「skip」と入力するとスキップできます。',
+  ko: '위 질문에 답하면 더 정확한 답변을 받을 수 있습니다. "skip"을 입력하면 건너뛸 수 있습니다.',
+};
+
+export function formatQuestionsForSSE(questions, lang = 'en') {
+  if (!questions || questions.length === 0) return null;
+
+  const normalized = normalizeLang(lang);
+  return {
+    type: 'clarifying_questions',
+    language: normalized,
+    questions: questions.map(q => ({
+      category: q.category,
+      question: q.question,
+      options: q.options,
+    })),
+    instruction: SSE_INSTRUCTIONS[normalized] || SSE_INSTRUCTIONS.en,
+  };
+}
+
+// Words that mean "skip these questions" across the supported languages.
+const SKIP_WORDS = new Set([
+  'skip', 'next', 'no', 'none', 'pass', 'proceed',
+  'ข้าม', 'ไม่', 'ไม่ต้อง', 'ไม่ต้องถาม', 'ผ่าน',
+  '跳过', '不用', '不用了', '算了',
+  'スキップ', '結構です', 'いいえ',
+  '건너뛰기', '넘어가기', '괜찮아요', '아니요',
+]);
+
+export function parseClarifyingAnswers(answersText, questions) {
+  if (!answersText || typeof answersText !== 'string' || !questions) {
+    return { answers: {}, summary: '' };
+  }
+
+  const trimmed = answersText.trim().toLowerCase();
+
+  if (trimmed === '' || SKIP_WORDS.has(trimmed)) {
+    return { answers: {}, summary: 'User chose to skip clarifying questions.' };
+  }
+
+  const answers = {};
+  const summaryParts = [];
+
+  const isStructured = /^[\da-d\s,;]+$/.test(trimmed) && trimmed.length <= 20;
+
+  if (isStructured) {
+    const structuredPattern = /(\d+)?([a-d])/g;
+    let match;
+    while ((match = structuredPattern.exec(trimmed)) !== null) {
+      const questionIndex = match[1] ? parseInt(match[1], 10) - 1 : 0;
+      const optionIndex = match[2].charCodeAt(0) - 97;
+
+      if (questionIndex >= 0 && questionIndex < questions.length) {
+        const q = questions[questionIndex];
+        if (optionIndex >= 0 && optionIndex < (q.options?.length || 0)) {
+          answers[q.category] = q.options[optionIndex];
+          summaryParts.push(`${q.category}: ${q.options[optionIndex]}`);
+        }
+      }
+    }
+  }
+
+  if (Object.keys(answers).length === 0 && trimmed.length > 0) {
+    const interpretedAnswers = interpretFreeTextAnswers(answersText, questions);
+
+    if (Object.keys(interpretedAnswers).length > 0) {
+      Object.assign(answers, interpretedAnswers);
+      for (const [category, value] of Object.entries(interpretedAnswers)) {
+        summaryParts.push(`${category}: ${value}`);
+      }
+    } else {
+      if (questions.length > 0) {
+        answers[questions[0].category] = answersText.trim();
+        summaryParts.push(`${questions[0].category}: ${answersText.trim()}`);
+      }
+    }
+  }
+
+  return {
+    answers,
+    summary: summaryParts.length > 0
+      ? `User clarified: ${summaryParts.join('; ')}`
+      : 'User provided unstructured answers to clarifying questions.',
+  };
+}
+
+function interpretFreeTextAnswers(text, questions) {
+  const answers = {};
+  const lowerText = text.toLowerCase().trim();
+
+  const shorthandMap = {
+    'detailed': 'Very detailed (full analysis)',
+    'brief': 'Brief (quick summary)',
+    'quick': 'Brief (quick summary)',
+    'summary': 'Brief (quick summary)',
+    'comprehensive': 'Comprehensive overview',
+    'overview': 'Comprehensive overview',
+    'focused': 'Focused summary',
+    'highlights': 'Key highlights only',
+    '2026': '2026 (current year)',
+    'this year': '2026 (current year)',
+    '2025': '2025',
+    'last year': '2025',
+    'all': 'All types',
+    'everything': 'All types',
+    'skip': 'skip',
+    'proceed': 'skip',
+    'no': 'skip',
+    'english': 'English',
+    'thai': 'Thai',
+    'chinese': 'Chinese',
+  };
+
+  for (const q of questions) {
+    if (!q.options || q.options.length === 0) continue;
+
+    for (const opt of q.options) {
+      if (lowerText === opt.toLowerCase()) {
+        answers[q.category] = opt;
+        break;
+      }
+    }
+
+    if (!answers[q.category]) {
+      for (const [key, value] of Object.entries(shorthandMap)) {
+        if (lowerText.includes(key) && q.options.includes(value)) {
+          answers[q.category] = value;
+          break;
+        }
+      }
+    }
+
+    if (!answers[q.category]) {
+      for (const opt of q.options) {
+        const optLower = opt.toLowerCase();
+        if (optLower.includes(lowerText) || lowerText.includes(optLower.split(' ')[0])) {
+          answers[q.category] = opt;
+          break;
+        }
+      }
+    }
+  }
+
+  return answers;
+}
+
+export async function emitClarifyingQuestions(questions, queryId, options = {}) {
+  const { waitForResponse, timeoutMs = 30000 } = options;
+
+  eventBus.emit(Events.AGENT_CLARIFYING_QUESTIONS, {
+    queryId,
+    questions,
+    timestamp: Date.now(),
+  });
+
+  if (typeof waitForResponse === 'function') {
+    try {
+      const answers = await Promise.race([
+        waitForResponse(queryId, questions),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error('Clarifying questions timed out')), timeoutMs)
+        ),
+      ]);
+      return parseClarifyingAnswers(answers, questions);
+    } catch {
+      return { answers: {}, summary: 'Clarifying questions timed out; proceeding with original query.' };
+    }
+  }
+
+  return { answers: {}, summary: 'No response handler provided; proceeding with original query.' };
+}
+
+export function buildClarificationContext(clarifyingResult, originalQuery) {
+  if (!clarifyingResult || Object.keys(clarifyingResult.answers || {}).length === 0) {
+    return '';
+  }
+
+  const { answers, summary } = clarifyingResult;
+
+  const isDramaQuery = /(ซีรีส์|ละคร|drama|series|in blossom|ฮวาเจียนลิ่ง|花间令|花間令|หยุนซี|yunxi|นางพญางูขาว|드라마|ドラマ)/i.test(originalQuery);
+  const isMusicQuery = /(เพลง|song|music|ost|album|single|find the way|曲|歌|음악|노래)/i.test(originalQuery);
+
+  const parts = [];
+  parts.push('[SYSTEM CLARIFICATION]');
+  parts.push(`Original query: ${originalQuery}`);
+  parts.push(`Clarifications provided:`);
+
+  for (const [category, value] of Object.entries(answers)) {
+    // If the query is strictly about a drama but clarification was marked as Music, skip the contradictory field
+    if (category === 'media_type' && isDramaQuery && !isMusicQuery && String(value).toLowerCase().includes('music')) {
+      continue;
+    }
+    if (category === 'media_type' && isMusicQuery && !isDramaQuery && String(value).toLowerCase().includes('drama')) {
+      continue;
+    }
+    parts.push(`- ${category}: ${value}`);
+  }
+
+  if (summary) {
+    parts.push(`Summary: ${summary}`);
+  }
+
+  return parts.join('\n');
+}
+
+export function getAmbiguityPatterns() {
+  return [...AMBIGUITY_PATTERNS];
+}
+
+export default {
+  stripSystemDirectives,
+  detectAmbiguities,
+  isQueryTooVague,
+  normalizeLang,
+  SUPPORTED_LANGUAGES,
+  formatQuestionsForCLI,
+  formatQuestionsForSSE,
+  parseClarifyingAnswers,
+  emitClarifyingQuestions,
+  calculateConfidence,
+  generateClarifyingQuestions,
+  buildClarificationContext,
+  getAmbiguityPatterns,
+  AMBIGUITY_PATTERNS,
+};