kiku-agent 1.3.1 → 1.3.3

package/server/agent/session.js

@@ -33,9 +33,16 @@ function normalizeStorageKey(value) {
 
 export class AgentSession {
   constructor(options = {}) {
-    this.persistenceEnabled = options.persistence !== false;
+    const isTestEnv = process.env.NODE_ENV === 'test'
+      || process.env.npm_lifecycle_event === 'test'
+      || Boolean(process.env.npm_lifecycle_script?.includes('test'));
+    this.persistenceEnabled = options.persistence === true
+      || Boolean(options.storageFile)
+      || (options.persistence !== false && !isTestEnv);
     this.id = options.sessionId || `sess_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
-    this.createdAt = new Date();
+    this.createdAt = options.createdAt && !isNaN(new Date(options.createdAt).getTime())
+      ? new Date(options.createdAt)
+      : new Date();
     this.thinkingMode = options.thinkingMode || 'hide';
     const storageKey = normalizeStorageKey(options.storageKey);
     this.storageFile = options.storageFile
@@ -292,10 +299,54 @@ export class AgentSession {
     };
   }
 
+  _syncDerivedStats() {
+    let derivedQueries = 0;
+    let derivedToolCalls = 0;
+    let derivedDurationMs = 0;
+
+    for (const msg of this.messages || []) {
+      if (msg.role === 'user') derivedQueries++;
+      if (typeof msg.durationMs === 'number' && msg.durationMs > 0) {
+        derivedDurationMs += msg.durationMs;
+      }
+      for (const part of msg.parts || []) {
+        if (part.type === 'tool') {
+          derivedToolCalls++;
+          if (typeof part.durationMs === 'number' && part.durationMs > 0) {
+            derivedDurationMs += part.durationMs;
+          }
+        }
+      }
+    }
+
+    if (!this.stats.totalQueries && derivedQueries > 0) {
+      this.stats.totalQueries = derivedQueries;
+    }
+    if (derivedToolCalls > (this.stats.totalToolCalls || 0)) {
+      this.stats.totalToolCalls = derivedToolCalls;
+    }
+    if (derivedDurationMs > (this.stats.totalDurationMs || 0)) {
+      this.stats.totalDurationMs = derivedDurationMs;
+    }
+  }
+
+  getTotalToolCalls() {
+    const statsCount = Number(this.stats?.totalToolCalls) || 0;
+    let messageToolCount = 0;
+    for (const msg of this.messages || []) {
+      for (const part of msg.parts || []) {
+        if (part.type === 'tool') messageToolCount++;
+      }
+    }
+    return Math.max(statsCount, messageToolCount);
+  }
+
   restoreFromSnapshot(sessionData) {
     if (!sessionData) return false;
     this.id = sessionData.id || `sess_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`;
-    this.createdAt = sessionData.createdAt ? new Date(sessionData.createdAt) : new Date();
+    this.createdAt = sessionData.createdAt && !isNaN(new Date(sessionData.createdAt).getTime())
+      ? new Date(sessionData.createdAt)
+      : new Date();
     this.thinkingMode = sessionData.thinkingMode || 'hide';
     this.messages = Array.isArray(sessionData.messages) ? sessionData.messages : [];
     this.stats = {
@@ -309,6 +360,7 @@ export class AgentSession {
       totalCostUsd: 0,
       ...(sessionData.stats || {})
     };
+    this._syncDerivedStats();
     return true;
   }
 
@@ -337,7 +389,9 @@ export class AgentSession {
       const sessionData = JSON.parse(data);
       
       this.id = sessionData.id;
-      this.createdAt = new Date(sessionData.createdAt);
+      this.createdAt = sessionData.createdAt && !isNaN(new Date(sessionData.createdAt).getTime())
+        ? new Date(sessionData.createdAt)
+        : new Date();
       this.thinkingMode = sessionData.thinkingMode || 'hide';
       this.messages = sessionData.messages || [];
       this.stats = {
@@ -351,6 +405,7 @@ export class AgentSession {
         totalCostUsd: 0,
         ...(sessionData.stats || {})
       };
+      this._syncDerivedStats();
       return true;
     } catch {
       return false;

package/server/agent/tests/agentBubbleSystem.test.js

@@ -0,0 +1,65 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+await import('../../web-chat/ui/scripts/agentBubbleSystem.js');
+
+const { AgentBubbleSystem } = globalThis;
+
+test('agent bubble reducer follows the streaming lifecycle without replacing parts', () => {
+  let model = AgentBubbleSystem.createModel({
+    id: 'message_1',
+    status: 'queued',
+    agent: { id: 'research', name: 'Research Agent', avatar: 'R' }
+  });
+
+  model = AgentBubbleSystem.reduceEvent(model, { type: 'reasoning', chunk: 'Check ' });
+  model = AgentBubbleSystem.reduceEvent(model, { type: 'reasoning', chunk: 'sources.' });
+  assert.equal(model.status, 'thinking');
+  assert.equal(model.parts.find(part => part.type === 'reasoning').content, 'Check sources.');
+
+  model = AgentBubbleSystem.reduceEvent(model, {
+    type: 'tool_start',
+    callId: 'call_1',
+    name: 'search_works',
+    input: { query: 'In Blossom' }
+  });
+  model = AgentBubbleSystem.reduceEvent(model, {
+    type: 'tool_result',
+    callId: 'call_1',
+    name: 'search_works',
+    result: { count: 1 },
+    durationMs: 24
+  });
+  assert.equal(model.parts.find(part => part.id === 'call_1').status, 'done');
+
+  model = AgentBubbleSystem.reduceEvent(model, { type: 'token', chunk: 'Found ' });
+  model = AgentBubbleSystem.reduceEvent(model, { type: 'token', chunk: 'one result.' });
+  assert.equal(model.status, 'streaming');
+  assert.equal(model.parts.find(part => part.type === 'text').content, 'Found one result.');
+
+  model = AgentBubbleSystem.reduceEvent(model, { type: 'done' });
+  assert.equal(model.status, 'done');
+  assert.equal(model.parts.length, 3);
+});
+
+test('agent bubble reducer accepts agent handoffs and exposes explicit waiting and error states', () => {
+  const base = AgentBubbleSystem.createModel({
+    agent: { id: 'coordinator', name: 'Coordinator', avatar: 'C' }
+  });
+  const waiting = AgentBubbleSystem.reduceEvent(base, {
+    type: 'clarifying_questions',
+    agentId: 'fact-checker',
+    agentName: 'Fact-check Agent',
+    agentAvatar: 'F'
+  });
+  assert.equal(waiting.status, 'waiting');
+  assert.equal(waiting.agent.id, 'fact-checker');
+
+  const failed = AgentBubbleSystem.reduceEvent(waiting, {
+    type: 'error',
+    error: 'Catalog unavailable.'
+  });
+  assert.equal(failed.status, 'error');
+  assert.equal(failed.error, 'Catalog unavailable.');
+  assert.equal(failed.parts.at(-1).type, 'error');
+});

package/server/agent/tests/agentFollowUps.test.js

@@ -0,0 +1,253 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { extractAgentFollowUpQuestions, generateDynamicFollowUps, normalizeSuggestionKey, dedupeSuggestions, isOffTopicChat, buildOffTopicFollowUps } from '../../web-chat/core/followUpEngine.js';
+import { executeDirectCatalogKnowledge } from '../../web-chat/core/directCatalogEngine.js';
+
+test('extractAgentFollowUpQuestions extracts [SUGGESTED_FOLLOW_UPS] block and strips it from cleanText', () => {
+  const text = `นี่คือเนื้อหาการแสดงของจวีจิ้งอีในฮวาเจียนลิ่งครับ
+
+[SUGGESTED_FOLLOW_UPS]
+- วิเคราะห์พัฒนาการของหยางไฉ่เวย
+- ฉากแต่งงานที่น่าประทับใจ
+- เพลงประกอบซีรีส์ฮวาเจียนลิ่ง
+[/SUGGESTED_FOLLOW_UPS]`;
+
+  const result = extractAgentFollowUpQuestions(text);
+  assert.equal(result.cleanText, 'นี่คือเนื้อหาการแสดงของจวีจิ้งอีในฮวาเจียนลิ่งครับ');
+  assert.equal(result.suggestions.length, 3);
+  assert.equal(result.suggestions[0].query, 'วิเคราะห์พัฒนาการของหยางไฉ่เวย');
+  assert.ok(result.suggestions[0].label.startsWith('💡 วิเคราะห์พัฒนาการ'));
+});
+
+test('extractAgentFollowUpQuestions extracts inline 💡 section at the end of answer', () => {
+  const text = `จวีจิ้งอีได้ปล่อยซิงเกิลใหม่ FIND THE WAY ในปี 2026
+
+💡 แนะนำถามต่อ:
+- ฟังเพลง FIND THE WAY และดู MV
+- สเตจการแสดงสดของเพลงนี้
+- ทิศทางดนตรีใหม่ในปี 2026`;
+
+  const result = extractAgentFollowUpQuestions(text);
+  assert.equal(result.cleanText, 'จวีจิ้งอีได้ปล่อยซิงเกิลใหม่ FIND THE WAY ในปี 2026');
+  assert.equal(result.suggestions.length, 3);
+  assert.equal(result.suggestions[0].query, 'ฟังเพลง FIND THE WAY และดู MV');
+});
+
+test('generateDynamicFollowUps creates contextual questions based on entities', () => {
+  const dramaSuggestions = generateDynamicFollowUps({
+    query: 'ซีรีส์ฮวาเจียนลิ่ง',
+    answer: 'จวีจิ้งอีรับบทเป็นหยางไฉ่เวยและซ่างกวนจื่อ',
+    tools: [{ name: 'search_works' }]
+  });
+
+  assert.ok(dramaSuggestions.length >= 2);
+  assert.ok(dramaSuggestions.some(s => s.query.includes('ฮวาเจียนลิ่ง') || s.query.includes('หยางไฉ่เวย')));
+
+  const musicSuggestions = generateDynamicFollowUps({
+    query: 'ผลงานเพลงของจวีจิ้งอี',
+    answer: 'เพลง FIND THE WAY และเพลง Everyday',
+    tools: [{ name: 'search_discography' }]
+  });
+
+  assert.ok(musicSuggestions.length >= 2);
+  assert.ok(musicSuggestions.some(s => s.query.includes('เพลง') || s.query.includes('FIND THE WAY')));
+});
+
+test('executeDirectCatalogKnowledge returns suggestions dynamically generated by agent engine', async () => {
+  const response = await executeDirectCatalogKnowledge('ผลงานซีรีส์ In Blossom');
+  assert.ok(response.answer);
+  assert.ok(Array.isArray(response.suggestions));
+  assert.ok(response.suggestions.length > 0);
+  assert.ok(response.suggestions[0].query);
+});
+
+test('followUpEngine: normalizeSuggestionKey and dedupeSuggestions collapse duplicates', () => {
+  assert.equal(normalizeSuggestionKey('💡 เพลงประกอบ ฮวาเจียนลิ่ง!'), normalizeSuggestionKey('เพลงประกอบฮวาเจียนลิ่ง'));
+
+  const seen = new Set([normalizeSuggestionKey('วิเคราะห์พัฒนาการของหยางไฉ่เวย')]);
+  const out = dedupeSuggestions([
+    { label: 'a', query: 'วิเคราะห์พัฒนาการของหยางไฉ่เวย' },
+    { label: 'b', query: 'วิเคราะห์พัฒนาการของหยางไฉ่เวยในเรื่อง' },
+    { label: 'c', query: 'เพลงประกอบซีรีส์ฮวาเจียนลิ่ง' },
+  ], seen);
+
+  assert.equal(out.length, 1);
+  assert.equal(out[0].query, 'เพลงประกอบซีรีส์ฮวาเจียนลิ่ง');
+});
+
+test('followUpEngine: extractAgentFollowUpQuestions dedupes within one block', () => {
+  const text = `[SUGGESTED_FOLLOW_UPS]
+- วิเคราะห์พัฒนาการของหยางไฉ่เวย
+- วิเคราะห์พัฒนาการของหยางไฉ่เวย
+- เพลงประกอบซีรีส์ฮวาเจียนลิ่ง
+[/SUGGESTED_FOLLOW_UPS]`;
+
+  const result = extractAgentFollowUpQuestions(text);
+  assert.equal(result.suggestions.length, 2);
+});
+
+test('generateDynamicFollowUps: recentKeys suppresses already-shown questions', () => {
+  const first = generateDynamicFollowUps({ query: 'ซีรีส์ฮวาเจียนลิ่ง', answer: '', tools: [] });
+  assert.ok(first.length >= 2);
+
+  const seen = new Set(first.map(s => normalizeSuggestionKey(s.query)));
+  const second = generateDynamicFollowUps({ query: 'ซีรีส์ฮวาเจียนลิ่ง', answer: '', tools: [], recentKeys: seen });
+
+  assert.ok(second.length >= 2);
+  for (const s of second) {
+    assert.ok(!seen.has(normalizeSuggestionKey(s.query)), `repeat leaked: ${s.query}`);
+  }
+});
+
+test('generateDynamicFollowUps: rotation keeps proposing fresh questions across turns', () => {
+  const seen = new Set();
+  const asked = new Set();
+  for (let turn = 0; turn < 4; turn++) {
+    const round = generateDynamicFollowUps({ query: 'จวีจิ้งอีเป็นใคร', answer: '', tools: [], recentKeys: seen });
+    assert.ok(round.length >= 2, `turn ${turn} returned too few suggestions`);
+    for (const s of round) {
+      const key = normalizeSuggestionKey(s.query);
+      assert.ok(!asked.has(key), `question repeated on turn ${turn}: ${s.query}`);
+      asked.add(key);
+      seen.add(key);
+    }
+  }
+});
+test('generateDynamicFollowUps: exhausted pool still returns suggestions (recycled)', () => {
+  const seen = new Set();
+  for (let turn = 0; turn < 6; turn++) {
+    const round = generateDynamicFollowUps({ query: 'จวีจิ้งอีเป็นใคร', answer: '', tools: [], recentKeys: seen });
+    for (const s of round) seen.add(normalizeSuggestionKey(s.query));
+  }
+  for (let turn = 0; turn < 3; turn++) {
+    const round = generateDynamicFollowUps({ query: 'จวีจิ้งอีเป็นใคร', answer: '', tools: [], recentKeys: seen });
+    assert.ok(round.length >= 2, `exhausted turn ${turn} returned too few suggestions`);
+  }
+});
+
+test('generateDynamicFollowUps: off-topic chats stay on the user topic, never Ju Jingyi', () => {
+  assert.equal(isOffTopicChat('วิธีทำต้มยำกุ้งน้ำข้น', []), true);
+  assert.equal(isOffTopicChat('จวีจิ้งอีเป็นใคร', []), false);
+  assert.equal(isOffTopicChat('อากาศวันนี้เป็นอย่างไร', [{ name: 'web_search', result: { status: 'success' } }]), true);
+
+  const th = generateDynamicFollowUps({ query: 'วิธีทำต้มยำกุ้งน้ำข้น', answer: 'ต้มยำกุ้งเป็นอาหารไทย', tools: [] });
+  assert.ok(th.length >= 2);
+  for (const s of th) {
+    assert.ok(s.query.includes('ต้มยำกุ้ง'), `off-topic chip must stay on topic: ${s.query}`);
+    assert.ok(!/จวีจิ้งอี|ju\s*jingyi|鞠婧祎/i.test(s.query), `off-topic chip must not mention Ju Jingyi: ${s.query}`);
+  }
+
+  const en = generateDynamicFollowUps({ query: 'What is quantum computing?', answer: 'Quantum computing uses qubits', tools: [] });
+  assert.ok(en.length >= 2);
+  assert.ok(en[0].query.includes('quantum computing'));
+
+  const onTopic = generateDynamicFollowUps({ query: 'จวีจิ้งอีเป็นใคร', answer: '', tools: [] });
+  assert.ok(onTopic.some(s => /จวีจิ้งอี/.test(s.query)), 'on-topic queries keep Ju Jingyi suggestions');
+});
+
+test('generateDynamicFollowUps: multilingual chips for zh and en', () => {
+  const zh = generateDynamicFollowUps({
+    query: '鞠婧祎的代表作品有哪些？',
+    answer: '主要作品包括《花间令》、《芸汐传》',
+    tools: [{ name: 'search_works' }],
+    lang: 'zh'
+  });
+  assert.ok(zh.length >= 2);
+  assert.ok(zh.some(s => /[\u4E00-\u9FFF]/.test(s.query)), 'Should contain Chinese characters');
+
+  const en = generateDynamicFollowUps({
+    query: 'Tell me about Ju Jingyi dramas',
+    answer: 'Her famous works include In Blossom and Legend of Yunxi',
+    tools: [{ name: 'search_works' }],
+    lang: 'en'
+  });
+  assert.ok(en.length >= 2);
+  assert.ok(en.every(s => !/[\u0E00-\u0E7F]/.test(s.query)), 'English mode should not output Thai text');
+});
+
+test('generateDynamicFollowUps: multi-topic score ranking synthesizes blended suggestions', () => {
+  const hybrid = generateDynamicFollowUps({
+    query: 'เพลงประกอบซีรีส์ ฮวาเจียนหลิง มีเพลงอะไรบ้าง',
+    answer: 'มีเพลง Dewdrops (露水) และเพลงอื่นๆ ใน In Blossom OST',
+    tools: [{ name: 'search_works' }, { name: 'search_discography' }],
+    lang: 'th'
+  });
+  assert.ok(hybrid.length >= 3, 'Should produce at least 3 suggestions');
+  const queriesText = hybrid.map(s => s.query).join(' ');
+  assert.ok(queriesText.includes('ซีรีส์') || queriesText.includes('ฮวาเจียนหลิง') || queriesText.includes('หยางไฉ่เวย'), 'Should contain drama chips');
+  assert.ok(queriesText.includes('เพลง') || queriesText.includes('OST') || queriesText.includes('FIND THE WAY'), 'Should contain music chips');
+});
+
+test('generateDynamicFollowUps: handles expanded catalog works (The Eternal Fragrance, Sword & Fairy 4)', () => {
+  const fragrance = generateDynamicFollowUps({
+    query: 'ซีรีส์ พันกลิ่นบุปผา The Eternal Fragrance',
+    answer: 'รับบทเป็น เจียง黎非 (Jiang Lifei) ซีรีส์ Youku S+',
+    tools: [{ name: 'search_works' }]
+  });
+  assert.ok(fragrance.some(s => s.query.includes('พันกลิ่นบุปผา') || s.query.includes('Eternal Fragrance')));
+
+  const sword = generateDynamicFollowUps({
+    query: 'ซีรีส์ เซียนกระบี่พิชิตมาร 4 Sword and Fairy',
+    answer: 'รับบทเป็น หานหลิงซา ร้องเพลง 如纱 (Ru Sha)',
+    tools: [{ name: 'search_works' }]
+  });
+  assert.ok(sword.some(s => s.query.includes('เซียนกระบี่') || s.query.includes('หานหลิงซา') || s.query.includes('Ru Sha')));
+});
+
+test('buildOffTopicFollowUps: generates specialized calculus & limits suggestions without broken LaTeX truncation', () => {
+  const mathQuery = 'จงหาค่าของลิมิต $\\lim_{x \\to 2} \\frac{x^2 - 4}{x^2 + x - 6}$';
+  const followUps = buildOffTopicFollowUps(mathQuery, 'th');
+
+  assert.ok(followUps.length >= 3, 'Should produce at least 3 follow-ups');
+
+  // Verify specialized limit/calculus content
+  const allText = followUps.map(f => `${f.label} ${f.query}`).join(' ');
+  assert.ok(/โลปีตาล|L'Hôpital|แยกตัวประกอบ|Factoring|0\/0|ความต่อเนื่อง|Continuity/i.test(allText),
+    'Should contain specialized calculus concepts instead of generic templates');
+
+  // Assert NO broken sliced LaTeX math fragments (e.g. $\lim_{x \to 2} \frac{x^2 -)
+  for (const item of followUps) {
+    assert.ok(!item.query.includes('x^2 -ให้'), `Must not contain sliced formula syntax: ${item.query}`);
+    assert.ok(!item.label.includes('x^2 -ให้'), `Label must not contain sliced formula syntax: ${item.label}`);
+    assert.ok(!/อธิบายเรื่องจงหาค่าของ/i.test(item.label), `Must strip Thai question verbs from labels: ${item.label}`);
+
+    // Check LaTeX delimiter balancing if dollar signs are present
+    const dollarCount = (item.query.match(/\$/g) || []).length;
+    assert.equal(dollarCount % 2, 0, `Query has unbalanced $ delimiters: ${item.query}`);
+  }
+});
+
+test('buildOffTopicFollowUps: generates specialized programming suggestions for Kotlin and Python', () => {
+  const kotlinQuery = 'ช่วยสอนฉันเขียนโค้ด kotlin หน่อยง่ายๆนะ';
+  const kotlinFollowUps = buildOffTopicFollowUps(kotlinQuery, 'th');
+
+  assert.ok(kotlinFollowUps.length >= 3);
+  const kotlinText = kotlinFollowUps.map(f => `${f.label} ${f.query}`).join(' ');
+  assert.ok(/Null Safety|Coroutines|Scope functions|Data Class/i.test(kotlinText),
+    'Should propose specialized Kotlin language topics');
+
+  const pythonQuery = 'สอนเขียนโค้ด Python เบื้องต้นหน่อย';
+  const pythonFollowUps = buildOffTopicFollowUps(pythonQuery, 'th');
+  assert.ok(pythonFollowUps.length >= 3);
+  const pythonText = pythonFollowUps.map(f => `${f.label} ${f.query}`).join(' ');
+  assert.ok(/List Comprehension|OOP|Class|Virtual Environment|PIP/i.test(pythonText),
+    'Should propose specialized Python topics');
+});
+
+test('buildOffTopicFollowUps: gracefully sanitizes and balances long math queries', () => {
+  const longMathQuery = 'คำนวณค่าของ $f(x) = \\int_{0}^{\\pi} \\sin(x) \\cos(x) dx$ และตรวจสอบความถูกต้อง';
+  const followUps = buildOffTopicFollowUps(longMathQuery, 'th');
+
+  assert.ok(followUps.length >= 3);
+  const text = followUps.map(f => f.query).join(' ');
+  assert.ok(/อินทิกรัล|Integral|Substitution|Calculus/i.test(text),
+    'Integral query should match integral or calculus specialization');
+
+  for (const f of followUps) {
+    const dollars = (f.query.match(/\$/g) || []).length;
+    assert.equal(dollars % 2, 0, `Unbalanced $ in follow-up: ${f.query}`);
+    assert.ok(!f.query.endsWith('\\'), `Query ends with dangling backslash: ${f.query}`);
+  }
+});
+
+

package/server/agent/tests/agentMusicControl.test.js

@@ -0,0 +1,245 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { audioPlayer, resolveCatalogSong } from '../audioPlayer.js';
+import { toolHandlers, toolsSchema } from '../tools.js';
+import { dynamicToolRouter } from '../toolRouter.js';
+
+test('resolveCatalogSong correctly identifies songs across languages and aliases', () => {
+  const s1 = resolveCatalogSong('Heartbeat Alert');
+  assert.ok(s1);
+  assert.equal(s1.youtubeId, '5MLPdCmnlmE');
+
+  const s2 = resolveCatalogSong('恋爱告急');
+  assert.ok(s2);
+  assert.equal(s2.youtubeId, '5MLPdCmnlmE');
+
+  const s3 = resolveCatalogSong('FIND THE WAY');
+  assert.ok(s3);
+  assert.equal(s3.youtubeId, '9AeErG03SZw');
+
+  const s4 = resolveCatalogSong('In Blossom');
+  assert.ok(s4);
+  assert.ok(s4.youtubeId);
+
+  const rand = resolveCatalogSong('random');
+  assert.ok(rand);
+  assert.ok(rand.youtubeId);
+});
+
+test('resolveCatalogSong matches long composite queries bidirectionally', () => {
+  const s1 = resolveCatalogSong('รักกลางสายฝน (雨爱) / Yu Ai (Rain Love)');
+  assert.ok(s1);
+  assert.equal(s1.youtubeId, 'OMLpNyp8T7Q');
+
+  const s2 = resolveCatalogSong('雨爱');
+  assert.ok(s2);
+  assert.equal(s2.youtubeId, 'OMLpNyp8T7Q');
+
+  assert.equal(resolveCatalogSong('zzzz-not-a-song-xyz'), null);
+});
+
+test('audioPlayer controls volume, seek, repeat, and shuffle states', () => {
+  assert.equal(typeof audioPlayer.setVolume, 'function');
+  const vMsg = audioPlayer.setVolume(75);
+  assert.equal(audioPlayer.volume, 75);
+  assert.match(vMsg, /75%/);
+
+  audioPlayer.setVolume(150);
+  assert.equal(audioPlayer.volume, 100);
+
+  audioPlayer.setVolume(-20);
+  assert.equal(audioPlayer.volume, 0);
+
+  assert.equal(typeof audioPlayer.seek, 'function');
+  const sMsg = audioPlayer.seek(125);
+  assert.equal(audioPlayer._currentOffsetSeconds, 125);
+  assert.match(sMsg, /2:05/);
+
+  assert.equal(typeof audioPlayer.setRepeatMode, 'function');
+  audioPlayer.setRepeatMode('one');
+  assert.equal(audioPlayer.repeatMode, 'one');
+  audioPlayer.setRepeatMode('all');
+  assert.equal(audioPlayer.repeatMode, 'all');
+  audioPlayer.setRepeatMode('off');
+  assert.equal(audioPlayer.repeatMode, 'off');
+
+  assert.equal(typeof audioPlayer.setShuffleMode, 'function');
+  audioPlayer.setShuffleMode(true);
+  assert.equal(audioPlayer.isShuffle, true);
+  audioPlayer.setShuffleMode(false);
+  assert.equal(audioPlayer.isShuffle, false);
+
+  const state = audioPlayer.getFullState();
+  assert.equal(typeof state.volume, 'number');
+  assert.equal(typeof state.repeatMode, 'string');
+  assert.equal(typeof state.isShuffle, 'boolean');
+  assert.equal(typeof state.currentTime, 'number');
+});
+
+test('music tool handlers emit standard action payloads with song metadata', async () => {
+  const { audioPlayer: player } = await import('../audioPlayer.js');
+  const originalCreateStream = player._createStream;
+
+  player._createStream = async function () {
+    player.isPlaying = true;
+    player.isPaused = false;
+  };
+  try {
+    player.stop();
+
+    const playRes = await toolHandlers.play_music({ query: 'Heartbeat Alert' });
+    assert.equal(playRes.status, 'success');
+    assert.equal(playRes.action, 'play');
+    assert.ok(playRes.song);
+    assert.equal(playRes.song.youtubeId, '5MLPdCmnlmE');
+    assert.equal(playRes.localPlayback, true);
+    assert.ok(playRes.youtubeUrl.includes('5MLPdCmnlmE'));
+
+    const pauseRes = await toolHandlers.pause_music({});
+    assert.equal(pauseRes.status, 'success');
+    assert.equal(pauseRes.action, 'pause');
+
+    const resumeRes = await toolHandlers.resume_music({});
+    assert.equal(resumeRes.status, 'success');
+    assert.equal(resumeRes.action, 'resume');
+
+    const stopRes = await toolHandlers.stop_music({});
+    assert.equal(stopRes.status, 'success');
+    assert.equal(stopRes.action, 'stop');
+
+ 
+    player.queue = ['Heartbeat Alert', 'FIND THE WAY'];
+    player.currentIndex = 0;
+    player.currentTrack = 'Heartbeat Alert';
+    player.isPlaying = true;
+    player.isPaused = false;
+
+    const nextRes = await toolHandlers.next_track({});
+    assert.equal(nextRes.status, 'success');
+    assert.equal(nextRes.action, 'next');
+
+    const prevRes = await toolHandlers.prev_track({});
+    assert.equal(prevRes.status, 'success');
+    assert.equal(prevRes.action, 'prev');
+
+    player.stop();
+  } finally {
+    player._createStream = originalCreateStream;
+    player.stop();
+  }
+
+  const volRes = await toolHandlers.set_volume({ volume: 60 });
+  assert.equal(volRes.status, 'success');
+  assert.equal(volRes.action, 'set_volume');
+  assert.equal(volRes.volume, 60);
+
+  const seekSecRes = await toolHandlers.seek_music({ seconds: 90 });
+  assert.equal(seekSecRes.status, 'success');
+  assert.equal(seekSecRes.action, 'seek');
+  assert.equal(seekSecRes.seconds, 90);
+
+  const seekStrRes = await toolHandlers.seek_music({ position: '01:30' });
+  assert.equal(seekStrRes.status, 'success');
+  assert.equal(seekStrRes.action, 'seek');
+  assert.equal(seekStrRes.seconds, 90);
+
+  const repRes = await toolHandlers.set_repeat_mode({ mode: 'one' });
+  assert.equal(repRes.status, 'success');
+  assert.equal(repRes.action, 'set_repeat');
+  assert.equal(repRes.mode, 'one');
+
+  const shufRes = await toolHandlers.set_shuffle_mode({ enabled: true });
+  assert.equal(shufRes.status, 'success');
+  assert.equal(shufRes.action, 'set_shuffle');
+  assert.equal(shufRes.enabled, true);
+
+  const vidRes = await toolHandlers.toggle_video_mode({ showVideo: true });
+  assert.equal(vidRes.status, 'success');
+  assert.equal(vidRes.action, 'toggle_video');
+  assert.equal(vidRes.isVideoOpen, true);
+});
+
+test('music tool handlers report honest errors on no-ops instead of phantom success', async () => {
+  const { audioPlayer: player } = await import('../audioPlayer.js');
+  player.stop();
+
+ 
+  const pauseIdle = await toolHandlers.pause_music({});
+  assert.equal(pauseIdle.status, 'error');
+
+  const resumeIdle = await toolHandlers.resume_music({});
+  assert.equal(resumeIdle.status, 'error');
+
+  const muteIdle = await toolHandlers.mute_music({});
+  assert.equal(muteIdle.status, 'error');
+
+  const unmuteIdle = await toolHandlers.unmute_music({});
+  assert.equal(unmuteIdle.status, 'error');
+
+  const nextIdle = await toolHandlers.next_track({});
+  assert.equal(nextIdle.status, 'error');
+
+  const prevIdle = await toolHandlers.prev_track({});
+  assert.equal(prevIdle.status, 'error');
+
+ 
+  const playEmpty = await toolHandlers.play_music({ query: '   ' });
+  assert.equal(playEmpty.status, 'error');
+
+ 
+  const originalCreateStream = player._createStream;
+  player._createStream = async function () {
+    
+    player._cleanup();
+    player.isPlaying = false;
+    player.isPaused = false;
+    player._removeCurrentFromQueue();
+    throw new Error('No playable audio source found');
+  };
+  try {
+    const playFail = await toolHandlers.play_music({ query: 'Heartbeat Alert' });
+    assert.equal(playFail.status, 'success');
+    assert.equal(playFail.localPlayback, false);
+    assert.ok(playFail.playbackError);
+    assert.ok(playFail.youtubeUrl);
+    assert.equal(player.isPlaying, false);
+    assert.equal(player.currentTrack, null);
+  } finally {
+    player._createStream = originalCreateStream;
+    player.stop();
+  }
+});
+
+test('new music tools are registered in toolsSchema', () => {
+  const schemaNames = new Set(toolsSchema.map(t => t.function?.name));
+  assert.ok(schemaNames.has('set_volume'));
+  assert.ok(schemaNames.has('seek_music'));
+  assert.ok(schemaNames.has('set_repeat_mode'));
+  assert.ok(schemaNames.has('set_shuffle_mode'));
+  assert.ok(schemaNames.has('toggle_video_mode'));
+});
+
+test('toolRouter routes conversational music commands to music tools', () => {
+  const queries = [
+    'ช่วยเปิดเพลง Heartbeat Alert หน่อย',
+    'หยุดเพลงก่อน',
+    'เล่นเพลงต่อ',
+    'ปรับเสียงเป็น 80%',
+    'ข้ามไปเพลงถัดไป',
+    'ย้อนกลับไปเพลงก่อนหน้า',
+    'วนซ้ำเพลงนี้',
+    'เปิดโหมดสุ่มเพลง',
+    'ขอเปิด MV ดูหน่อย',
+    'กรอไปที่นาทีที่ 1:30',
+  ];
+
+  for (const q of queries) {
+    const routed = dynamicToolRouter.routeToolsForQuery(q);
+    const names = new Set(routed.map(t => t.function?.name));
+    const hasMusicTool = names.has('play_music') || names.has('pause_music') ||
+      names.has('set_volume') || names.has('next_track') || names.has('prev_track') ||
+      names.has('seek_music') || names.has('set_repeat_mode') || names.has('set_shuffle_mode') ||
+      names.has('toggle_video_mode');
+    assert.ok(hasMusicTool, `Query "${q}" should route to at least one music playback tool`);
+  }
+});