kiku-agent 1.3.1 → 1.3.2

package/server/agent/eval/modules/utils/smokes.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { REPO_ROOT, DEFAULTS } from '../core/config.js';
+import { estimateTextTokens } from '../../../contextCompactor.js';
+
+export async function runWebSmoke({ out = DEFAULTS.webSmokeOut, timeoutMs = 60000 } = {}) {
+  const outPath = path.isAbsolute(out) ? out : path.resolve(REPO_ROOT, out);
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+  process.env.KIKU_DATA_DIR = await fs.mkdtemp(path.join(os.tmpdir(), 'kiku-web-eval-'));
+  const { executeTool } = await import('../../../tools.js');
+  const checks = [
+    ['web_search', { query: 'Ju Jingyi Legend of Yunxi' }],
+    ['search_chinese_web', { query: '鞠婧祎 芸汐传' }],
+    ['fetch_webpage', { url: 'https://example.com' }],
+    ['web_extract', { query: 'Ju Jingyi Legend of Yunxi', maxResults: 2 }],
+  ];
+  const rows = [];
+  try {
+    for (const [tool, parameters] of checks) {
+      const start = performance.now();
+      let row;
+      try {
+        const result = await executeTool(tool, parameters, { signal: AbortSignal.timeout(timeoutMs) });
+        row = { tool, parameters, result, durationMs: Math.round(performance.now() - start) };
+      } catch (error) {
+        row = { tool, parameters, error: error.message, durationMs: Math.round(performance.now() - start) };
+      }
+      rows.push(row);
+      await fs.writeFile(outPath, JSON.stringify({ checkedAt: new Date().toISOString(), scope: 'Real external tool availability, not answer-quality scoring. Success status does not establish result relevance.', rows }, null, 2));
+      console.log(`${tool}: ${row.result?.status || row.error}; ${row.durationMs}ms`);
+    }
+  } finally {
+    await fs.rm(process.env.KIKU_DATA_DIR, { recursive: true, force: true });
+  }
+  return { out: outPath, rows };
+}
+
+export async function runResearchSmoke({ out = DEFAULTS.researchSmokeOut, model = DEFAULTS.model, baseUrl = DEFAULTS.baseUrl, timeoutMs = 180000 } = {}) {
+  const outPath = path.isAbsolute(out) ? out : path.resolve(REPO_ROOT, out);
+  const fsSync = await import('node:fs');
+  const dir = fsSync.mkdtempSync(path.join(os.tmpdir(), 'kiku-research-eval-'));
+  process.env.KIKU_DATA_DIR = dir;
+  const [{ LLMClient }, { ResearchOrchestrator }, { scoreResearchComplexity, shouldAutoResearch }] = await Promise.all([
+    import('../../../llmClient.js'), import('../../../research.js'), import('../../../agentCore.js'),
+  ]);
+  const question = 'Compare In Blossom and Sword and Fairy 4 using the Kiku catalog and public sources. Verify the release years, the characters played by Ju Jingyi, and episode counts. Explain any source disagreement, and clearly distinguish unverified information. Provide a concise evidence report with sources.';
+  const client = new LLMClient({ provider: 'lmstudio', model, apiKey: 'lm-studio', baseUrl });
+  const started = Date.now();
+  const report = {
+    startedAt: new Date().toISOString(), model: client.model, question, timeoutMs,
+    complexity: scoreResearchComplexity(question), autoEligible: shouldAutoResearch(question, { mode: 'auto' }),
+    scope: 'Direct real ResearchOrchestrator run, default 3 workers and 3 iterations. Auto eligibility is checked separately; this does not test the main agent decision to invoke research.',
+    state: 'running', maxConcurrentRequests: 0, requests: [], progress: [],
+  };
+  fsSync.mkdirSync(path.dirname(outPath), { recursive: true });
+  const save = () => { report.elapsedMs = Date.now() - started; fsSync.writeFileSync(outPath, JSON.stringify(report, null, 2)); };
+  let active = 0;
+  const chat = client.chat.bind(client);
+  client.chat = async options => {
+    const row = { startedMs: Date.now() - started };
+    report.requests.push(row);
+    report.maxConcurrentRequests = Math.max(report.maxConcurrentRequests, ++active);
+    save();
+    try { const result = await chat(options); row.usage = result?.usage; return result; }
+    catch (error) { row.error = error.message; throw error; }
+    finally { active--; row.endedMs = Date.now() - started; save(); }
+  };
+  const research = new ResearchOrchestrator({ client });
+  const hardStop = setTimeout(() => {
+    report.state = 'timeout'; report.error = 'Hard timeout after cancellation grace period'; save(); process.exit(1);
+  }, timeoutMs + 15000);
+  try {
+    report.result = await research.run(question, {
+      signal: AbortSignal.timeout(timeoutMs),
+      onProgress: event => { report.progress.push({ elapsedMs: Date.now() - started, ...event }); save(); console.log(JSON.stringify(event)); },
+    });
+    report.state = 'completed';
+  } catch (error) {
+    report.state = 'error'; report.error = error.message; process.exitCode = 1;
+  } finally {
+    clearTimeout(hardStop); research.cancel(); save(); fsSync.rmSync(dir, { recursive: true, force: true });
+  }
+  console.log(JSON.stringify({ state: report.state, elapsedMs: report.elapsedMs, requests: report.requests.length, maxConcurrentRequests: report.maxConcurrentRequests }));
+  return report;
+}
+
+export async function runTokenCalibration({ out = DEFAULTS.tokenCalibrationOut, model = DEFAULTS.model, baseUrl = DEFAULTS.baseUrl } = {}) {
+  const outPath = path.isAbsolute(out) ? out : path.resolve(REPO_ROOT, out);
+  const samples = {
+    th: 'จวีจิ้งอีเป็นนักร้องและนักแสดงชาวจีน แฟนคลับต้องการตรวจสอบข้อมูลผลงานจากแหล่งอ้างอิง หากไม่มีข้อมูลเพียงพอควรบอกตรงไปตรงมาและไม่แต่งรายละเอียดเพิ่มเติม ',
+    en: 'The assistant should verify the title, character and release year against the catalog. If evidence is missing, explain the uncertainty instead of inventing details. ',
+    zh: '请根据资料库核实电视剧名称、角色和发行年份。如果没有足够证据，请明确说明不确定性，不要编造细节。',
+    mixed: 'ข้อมูล作品 In Blossom (花间令) ปี 2024: {"role":"Yang Caiwei","episodes":32,"verified":true}. ',
+  };
+  const rows = [];
+  for (const [language, sample] of Object.entries(samples)) {
+    const measurements = [];
+    for (const repeats of [3, 6]) {
+      const content = sample.repeat(repeats).trim();
+      const started = Date.now();
+      const response = await fetch(`${baseUrl.replace(/\/$/, '')}/chat/completions`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' }, signal: AbortSignal.timeout(90000),
+        body: JSON.stringify({ model, messages: [{ role: 'user', content }], max_tokens: 1, temperature: 0, stream: false }),
+      });
+      if (!response.ok) throw new Error(`Calibration HTTP ${response.status}`);
+      const result = await response.json();
+      if (!Number.isFinite(result.usage?.prompt_tokens)) throw new Error('Provider did not report prompt token usage');
+      measurements.push({ repeats, characters: content.length, estimate: estimateTextTokens(content), promptTokens: result.usage.prompt_tokens, durationMs: Date.now() - started });
+    }
+    const estimatedDelta = measurements[1].estimate - measurements[0].estimate;
+    const measuredDelta = measurements[1].promptTokens - measurements[0].promptTokens;
+    rows.push({ language, sample, measurements, estimatedDelta, measuredDelta, ratio: measuredDelta > 0 ? estimatedDelta / measuredDelta : null });
+    await fs.mkdir(path.dirname(outPath), { recursive: true });
+    await fs.writeFile(outPath, JSON.stringify({ model, checkedAt: new Date().toISOString(), method: 'Real prompt usage delta between 3 and 6 repeats; chat-template overhead cancels. Four samples only, no universal tokenizer bound or o200k claim.', rows }, null, 2));
+    console.log(`${language}: estimated delta ${estimatedDelta}, measured ${measuredDelta}, ratio ${rows.at(-1).ratio}`);
+  }
+  return { out: outPath, rows };
+}

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,127 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { extractAgentFollowUpQuestions, generateDynamicFollowUps, normalizeSuggestionKey, dedupeSuggestions } 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`);
+  }
+});

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

@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+
+import { handleApiRequest } from '../../apiRouter.js';
+import { PACKAGE_VERSION } from '../version.js';
+
+async function withApiServer(run) {
+  const server = createServer((req, res) => {
+    void handleApiRequest(req, res).catch(error => {
+      res.statusCode = 500;
+      res.end(error.message);
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+
+  const address = server.address();
+  try {
+    await run(`http://127.0.0.1:${address.port}`);
+  } finally {
+    await new Promise(resolve => server.close(resolve));
+  }
+}
+
+test('REST API, OpenAPI, and MCP discovery expose the package version', async () => {
+  await withApiServer(async baseUrl => {
+    const [healthResponse, openApiResponse, mcpResponse] = await Promise.all([
+      fetch(`${baseUrl}/api/v1/health`),
+      fetch(`${baseUrl}/api/v1/openapi.json`),
+      fetch(`${baseUrl}/mcp`),
+    ]);
+    const [health, openApi, mcp] = await Promise.all([
+      healthResponse.json(),
+      openApiResponse.json(),
+      mcpResponse.json(),
+    ]);
+
+    assert.equal(health.data.version, `v${PACKAGE_VERSION}`);
+    assert.equal(openApi.info.version, PACKAGE_VERSION);
+    assert.equal(mcp.version, PACKAGE_VERSION);
+  });
+});
+
+test('REST API does not grant VIP rate limits to forged kiku_ keys', async () => {
+  await withApiServer(async baseUrl => {
+    const response = await fetch(`${baseUrl}/api/v1/health`, {
+      headers: {
+        'X-API-Key': 'kiku_forged_not_issued',
+        'X-Forwarded-For': '198.51.100.10',
+      },
+    });
+
+    assert.equal(response.status, 200);
+    assert.equal(response.headers.get('x-ratelimit-limit'), '60');
+    assert.equal(response.headers.get('x-ratelimit-tier'), 'Public-Anonymous (60/min)');
+    const payload = await response.json();
+    assert.equal(payload.data.tier, 'Public');
+  });
+});
+
+test('REST API isolates bounded rate-limit probes from normal client traffic', async () => {
+  await withApiServer(async baseUrl => {
+    const testIp = `198.51.100.${Math.floor(Math.random() * 80) + 120}`;
+    const headers = { 'X-Forwarded-For': testIp };
+    const probeUrl = `${baseUrl}/api/v1/health?testRateLimit=2`;
+
+    assert.equal((await fetch(probeUrl, { headers })).status, 200);
+    assert.equal((await fetch(probeUrl, { headers })).status, 200);
+    assert.equal((await fetch(probeUrl, { headers })).status, 429);
+
+    const normal = await fetch(`${baseUrl}/api/v1/health`, { headers });
+    assert.equal(normal.status, 200);
+    const remaining = Number(normal.headers.get('x-ratelimit-remaining'));
+    assert.ok(Number.isFinite(remaining) && remaining >= 0 && remaining < 60);
+
+    const malformed = await fetch(`${baseUrl}/api/v1/health?testRateLimit=not-a-number`, {
+      headers: { 'X-Forwarded-For': `198.51.100.${Math.floor(Math.random() * 80) + 200}` },
+    });
+    assert.equal(malformed.status, 200);
+    assert.equal(malformed.headers.get('x-ratelimit-limit'), '60');
+  });
+});
+
+test('REST API discography type filters return real catalog subsets', async () => {
+  await withApiServer(async baseUrl => {
+    const [allResponse, ostResponse, singlesResponse] = await Promise.all([
+      fetch(`${baseUrl}/api/v1/discography`),
+      fetch(`${baseUrl}/api/v1/discography?type=ost`),
+      fetch(`${baseUrl}/api/v1/discography?type=singles`),
+    ]);
+    const [all, ost, singles] = await Promise.all([
+      allResponse.json(),
+      ostResponse.json(),
+      singlesResponse.json(),
+    ]);
+
+    assert.ok(ost.meta.count > 0);
+    assert.ok(singles.meta.count > 0);
+    assert.ok(ost.meta.count < all.meta.count);
+    assert.ok(singles.meta.count < all.meta.count);
+    assert.ok(ost.data.every(track => track.catalogTypes.includes('ost')));
+    assert.ok(singles.data.every(track => track.catalogTypes.includes('singles')));
+  });
+});

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

@@ -0,0 +1,81 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { detectDominantLanguage } from '../agentCore.js';
+import { levenshteinDistance, levenshteinSimilarity, resolveQueryEntities } from '../catalogEntityResolver.js';
+import { DynamicToolRouter } from '../toolRouter.js';
+import { routingInterceptor } from '../routingInterceptor.js';
+import { executeTool } from '../tools.js';
+
+test('Architecture Fix 1: Language detection handles mixed Thai queries and session stickiness without English drift', () => {
+ 
+  assert.equal(detectDominantLanguage('By My POI หละ'), 'th');
+  assert.equal(detectDominantLanguage('รู้จัก Be My POI ไหม'), 'th');
+  assert.equal(detectDominantLanguage('เพลง FIND THE WAY เพราะไหม'), 'th');
+
+  
+  assert.equal(detectDominantLanguage('Be My POI', 'th'), 'th');
+  assert.equal(detectDominantLanguage('By My POI', 'th'), 'th');
+
+  
+  assert.equal(detectDominantLanguage('What are the main awards won by Ju Jingyi in her solo career?'), 'en');
+  assert.equal(detectDominantLanguage('Ju Jingyi Chinese name 鞠婧祎 and fandom name Miju 蜜橘 details'), 'en');
+
+ 
+  assert.equal(detectDominantLanguage('请问鞠婧祎在2026年有哪些新剧待播？'), 'zh');
+});
+
+test('Architecture Fix 2: Levenshtein & fuzzy matching resolves typos to catalog entities', () => {
+  
+  assert.equal(levenshteinDistance('by my poi', 'be my poi'), 1);
+  assert.ok(levenshteinSimilarity('by my poi', 'be my poi') >= 0.85);
+
+  
+  const resolution = resolveQueryEntities('By My POI หละ');
+  assert.ok(resolution.matchedEntities.length > 0, 'Should match at least one entity');
+  assert.equal(resolution.matchedEntities[0].id, 'mv-be-my-poi');
+  assert.equal(resolution.hasBrand, false, 'Should not match brand');
+  assert.equal(resolution.hasSong, true, 'Should match song/media');
+  assert.ok(resolution.matchedEntities[0].recommendedTools.includes('get_music_videos'));
+});
+
+test('Architecture Fix 3: Tool routing and routingInterceptor redirect misrouted brand calls to media', () => {
+  const router = new DynamicToolRouter();
+  const routed = router.routeToolsForQuery('By My POI หละ');
+  const toolNames = routed.map(t => t.function.name);
+
+ 
+  assert.ok(toolNames.includes('get_music_videos'));
+  assert.ok(toolNames.includes('search_discography'));
+
+ 
+  const intercepted = routingInterceptor.interceptToolCall({
+    name: 'get_brand_endorsements',
+    params: { brand: 'By My POI' }
+  });
+  assert.equal(intercepted.rerouted, true);
+  assert.equal(intercepted.replacement.name, 'get_music_videos');
+  assert.equal(intercepted.replacement.params.query, 'By My POI');
+  routingInterceptor.reset();
+});
+
+test('Architecture Fix 4: Cascade retrieval and fuzzy matching in tools return accurate ground-truth facts', async () => {
+ 
+  const mvRes = await executeTool('get_music_videos', { query: 'By My POI' });
+  assert.equal(mvRes.status, 'success');
+  assert.ok(mvRes.count > 0);
+  assert.equal(mvRes.videos[0].id, 'mv-be-my-poi');
+  assert.equal(mvRes.videos[0].year, 2022);
+  assert.equal(mvRes.videos[0].youtubeUrl, 'https://www.youtube.com/watch?v=IolEgdwvjEU');
+
+ 
+  const discoRes = await executeTool('search_discography', { query: 'By My POI' });
+  assert.equal(discoRes.status, 'success');
+  assert.equal(discoRes.cascadeMatched, true);
+  assert.equal(discoRes.source, 'musicVideoData');
+  assert.ok(discoRes.songs[0].title.includes('Be My POI'));
+
+ 
+  const brandRes = await executeTool('get_brand_endorsements', { query: 'By My POI' });
+  assert.equal(brandRes.status, 'not_found');
+  assert.ok(brandRes.message.includes('search_discography') || brandRes.message.includes('get_music_videos'));
+});