kiku-agent 1.3.1 → 1.3.3

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

@@ -0,0 +1,199 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { getDocsHtml } from '../../web-chat/ui/docsBuilder.js';
+import { getSettingsHtml } from '../../web-chat/ui/settingsBuilder.js';
+import { handleStaticRoute } from '../../web-chat/routes/staticRoute.js';
+
+test('Inference Control Center Web Documentation Portal', async (t) => {
+  await t.test('getDocsHtml returns valid HTML with all 7 chapters and hardware telemetry', () => {
+    const html = getDocsHtml();
+    assert.ok(typeof html === 'string' && html.length > 5000, 'HTML should be generated and non-empty');
+    assert.ok(html.includes('<!DOCTYPE html>'), 'Should have DOCTYPE');
+    assert.ok(html.includes('Inference Control Center'), 'Should have title');
+    assert.ok(html.includes('Architecture &amp; System Manual'), 'Should have manual subtitle in title');
+
+  
+    assert.ok(html.includes('id="section-arch"'), 'Chapter 1: Architecture section exists');
+    assert.ok(html.includes('id="section-engines"'), 'Chapter 2: Engines section exists');
+    assert.ok(html.includes('id="section-cpu-ht"'), 'Chapter 3: CPU SMT section exists');
+    assert.ok(html.includes('id="section-vram"'), 'Chapter 4: VRAM section exists');
+    assert.ok(html.includes('id="section-lan"'), 'Chapter 5: LAN Discovery section exists');
+    assert.ok(html.includes('id="section-api"'), 'Chapter 6: API section exists');
+    assert.ok(html.includes('id="section-tuning"'), 'Chapter 7: Tuning section exists');
+
+   
+    assert.ok(html.includes('Hyper-Threading') || html.includes('SMT'), 'Includes CPU SMT & Hyper-Threading documentation');
+    assert.ok(html.includes('VRAM'), 'Includes VRAM formula and calculation');
+    assert.ok(html.includes('LM Studio') && html.includes('vLLM'), 'Includes engine comparisons');
+    assert.ok(html.includes('SSRF'), 'Includes Zero-Key LAN security');
+
+   
+    assert.ok(html.includes('DOCS_I18N'), 'Includes DOCS_I18N dictionary');
+    assert.ok(html.includes('data-theme="dark"'), 'Supports dark theme by default');
+    assert.ok(html.includes('toggleTheme'), 'Includes theme toggle function');
+    assert.ok(html.includes('toggleLanguage'), 'Includes language toggle function');
+  });
+
+  await t.test('staticRoute serves /docs and /settings/docs with 200 and caching headers', () => {
+    const mockReq = (url) => ({
+      url,
+      headers: {
+        host: 'localhost:3002',
+        'accept-encoding': 'gzip, deflate, br'
+      }
+    });
+
+    const createMockRes = () => {
+      let statusCode = 200;
+      let headers = {};
+      let bodyChunks = [];
+      return {
+        writeHead(status, hdrs) {
+          statusCode = status;
+          if (hdrs) Object.assign(headers, hdrs);
+        },
+        setHeader(k, v) {
+          headers[k] = v;
+        },
+        write(chunk) {
+          bodyChunks.push(chunk);
+        },
+        end(chunk) {
+          if (chunk) bodyChunks.push(chunk);
+        },
+        get result() {
+          const buf = Buffer.isBuffer(bodyChunks[0])
+            ? Buffer.concat(bodyChunks)
+            : Buffer.from(bodyChunks.join(''));
+          return { statusCode, headers, buf };
+        }
+      };
+    };
+
+   
+    const res1 = createMockRes();
+    const handled1 = handleStaticRoute(mockReq('/docs'), res1, '/docs', 3002);
+    assert.strictEqual(handled1, true, '/docs should be handled by staticRoute');
+    assert.strictEqual(res1.result.statusCode, 200);
+    assert.strictEqual(res1.result.headers['Content-Type'], 'text/html; charset=utf-8');
+    assert.ok(res1.result.headers['ETag'], 'Should return an ETag');
+    assert.ok(res1.result.headers['Content-Encoding'], 'Should use compression (e.g. br or gzip)');
+    assert.ok(res1.result.buf.length > 0, 'Should return compressed body');
+
+   
+    const res2 = createMockRes();
+    const handled2 = handleStaticRoute(mockReq('/settings/docs'), res2, '/settings/docs', 3002);
+    assert.strictEqual(handled2, true, '/settings/docs should be handled by staticRoute');
+    assert.strictEqual(res2.result.statusCode, 200);
+    assert.strictEqual(res2.result.headers['Content-Type'], 'text/html; charset=utf-8');
+    assert.strictEqual(res2.result.headers['ETag'], res1.result.headers['ETag'], 'ETags should match for identical bundles');
+  });
+
+  await t.test('settings page contains navigation button linking to /docs', () => {
+    const settingsHtml = getSettingsHtml();
+    assert.ok(settingsHtml.includes('href="/docs"'), 'Settings navbar should link to /docs');
+    assert.ok(settingsHtml.includes('data-i18n="btnDocsGuide"'), 'Settings navbar has i18n key for docs guide');
+    assert.ok(settingsHtml.includes('btnDocsGuide:'), 'SETTINGS_I18N contains btnDocsGuide entry');
+  });
+
+  await t.test('docs page comprehensively supports smartphones and mobile viewports', () => {
+    const html = getDocsHtml();
+
+
+    assert.ok(html.includes('@media (max-width: 960px)'), 'Includes tablet/mobile breakpoint');
+    assert.ok(html.includes('@media (max-width: 480px)'), 'Includes small phone breakpoint');
+
+
+    assert.ok(html.includes('scroll-snap-type: x proximity'), 'Supports touch horizontal snap');
+    assert.ok(html.includes('-webkit-overflow-scrolling: touch'), 'Supports momentum scrolling on iOS');
+
+   
+    assert.ok(html.includes('id="btn-scroll-top"'), 'Contains floating back to top button');
+    assert.ok(html.includes('.btn-scroll-top'), 'Contains styles for floating button');
+    assert.ok(html.includes('initScrollTop'), 'Initializes scroll-to-top handler');
+
+  
+    assert.ok(html.includes('initScrollSpy'), 'Initializes scrollspy observer');
+    assert.ok(html.includes('safe-area-inset-bottom'), 'Respects mobile safe area insets');
+  });
+
+  await t.test('docs page has exhaustive technical Table of Contents sub-anchors and model tuning playbook', () => {
+    const html = getDocsHtml();
+
+    const expectedSubAnchors = [
+      'arch-topology', 'arch-ipc', 'arch-persistence',
+      'engine-arch', 'engine-quant', 'engine-flags',
+      'cpu-bandwidth', 'cpu-thrashing', 'cpu-modes',
+      'vram-weights', 'vram-kv', 'vram-overhead', 'vram-split',
+      'lan-scanner', 'lan-ports', 'lan-security',
+      'cmd-cli', 'params-load', 'params-sampling', 'api-reference',
+      'tuning-tiers', 'tuning-oom', 'tuning-pcie'
+    ];
+
+    for (const anchor of expectedSubAnchors) {
+      assert.ok(html.includes(`href="#${anchor}"`), `TOC should link to sub-anchor #${anchor}`);
+      assert.ok(html.includes(`id="${anchor}"`), `Content section should contain anchor id="${anchor}"`);
+    }
+
+    assert.ok(html.includes('contextLength'), 'Includes contextLength parameter card');
+    assert.ok(html.includes('gpuOffload'), 'Includes gpuOffload parameter card');
+    assert.ok(html.includes('htMode'), 'Includes htMode parameter card');
+    assert.ok(html.includes('flashAttn'), 'Includes flashAttn parameter card');
+    assert.ok(html.includes('batchSize'), 'Includes batchSize parameter card');
+    assert.ok(html.includes('splitMode'), 'Includes splitMode parameter card');
+    assert.ok(html.includes('kvQuant'), 'Includes kvQuant parameter card');
+
+    assert.ok(html.includes('temperature'), 'Includes temperature sampling card');
+    assert.ok(html.includes('min_p'), 'Includes min_p sampling card');
+    assert.ok(html.includes('top_p'), 'Includes top_p sampling card');
+    assert.ok(html.includes('repeatPenalty'), 'Includes repeatPenalty sampling card');
+    assert.ok(html.includes('maxTokens'), 'Includes maxTokens sampling card');
+
+    assert.ok(html.includes('/lan'), 'Includes /lan command documentation');
+    assert.ok(html.includes('/model'), 'Includes /model command documentation');
+    assert.ok(html.includes('/provider'), 'Includes /provider command documentation');
+    assert.ok(html.includes('/eval'), 'Includes /eval command documentation');
+    assert.ok(html.includes('/vram'), 'Includes /vram command documentation');
+    assert.ok(html.includes('/gpu'), 'Includes /gpu command documentation');
+    assert.ok(html.includes('/mcp'), 'Includes /mcp command documentation');
+
+    assert.ok(html.includes('highlightSublink'), 'Includes highlightSublink function');
+  });
+
+  await t.test('docs page has 100% comprehensive i18n coverage across TH, ZH, and EN', () => {
+    const html = getDocsHtml();
+
+    
+    const matches = [...html.matchAll(/data-i18n="([^"]+)"/g)].map(m => m[1]);
+    const uniqueKeys = [...new Set(matches)];
+
+    assert.ok(uniqueKeys.length >= 80, `Expected at least 80 data-i18n keys across all chapters, found ${uniqueKeys.length}`);
+
+  
+    const dictMatch = html.match(/const DOCS_I18N = (\{[\s\S]*?\n\s*\};)/);
+    assert.ok(dictMatch, 'DOCS_I18N object should exist in HTML script');
+
+    
+    const getDict = new Function(`return ${dictMatch[1]}`);
+    const dict = getDict();
+
+    assert.ok(dict.th && dict.zh && dict.en, 'Dictionary should have th, zh, and en languages');
+
+    
+    const missingTh = uniqueKeys.filter(k => dict.th[k] === undefined);
+    const missingZh = uniqueKeys.filter(k => dict.zh[k] === undefined);
+    const missingEn = uniqueKeys.filter(k => dict.en[k] === undefined);
+
+    assert.deepStrictEqual(missingTh, [], `Missing TH translations for keys: ${missingTh.join(', ')}`);
+    assert.deepStrictEqual(missingZh, [], `Missing ZH translations for keys: ${missingZh.join(', ')}`);
+    assert.deepStrictEqual(missingEn, [], `Missing EN translations for keys: ${missingEn.join(', ')}`);
+
+  
+    const thKeys = Object.keys(dict.th).sort();
+    const zhKeys = Object.keys(dict.zh).sort();
+    const enKeys = Object.keys(dict.en).sort();
+    assert.deepStrictEqual(thKeys, zhKeys, 'TH and ZH should have identical keys');
+    assert.deepStrictEqual(thKeys, enKeys, 'TH and EN should have identical keys');
+  });
+});
+

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

@@ -0,0 +1,298 @@
+import test, { after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { EventEmitter } from 'node:events';
+import vm from 'node:vm';
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'kiku-inference-'));
+process.env.KIKU_DATA_DIR = temp;
+process.env.NODE_ENV = 'test';
+process.env.WEBCHAT_ADMIN_KEY = 'inference-test-admin';
+process.env.WEBCHAT_ALLOW_TEST_ADMIN = 'false';
+after(() => fs.rmSync(temp, { recursive: true, force: true }));
+const { validateInferenceBaseUrl, sanitizeInferenceError, isTrustedRequest } = await import('../../web-chat/core/urlGuard.js');
+const { handleProviderUpdateRoute } = await import('../../web-chat/routes/providerRoute.js');
+const { handleChatRoute } = await import('../../web-chat/routes/chatRoute.js');
+const { handleAiSuggestRoute } = await import('../../web-chat/routes/suggestRoute.js');
+const { setCurrentAgent } = await import('../../web-chat/core/connection.js');
+const { getSettingsHtml } = await import('../../web-chat/ui/settingsBuilder.js');
+
+function request(body, ip = '127.0.0.1', key = '') {
+  const req = Readable.from([JSON.stringify(body)]);
+  req.socket = { remoteAddress: ip };
+  req.headers = key ? { authorization: 'Bearer ' + key } : {};
+  return req;
+}
+function response() {
+  const res = new EventEmitter();
+  res.chunks = '';
+  res.writeHead = (code) => { res.statusCode = code; res.headersSent = true; };
+  res.write = (data) => { res.chunks += data; };
+  res.end = (data = '') => { res.chunks += data; res.writableEnded = true; res.emit('finish'); };
+  res.json = () => JSON.parse(res.chunks);
+  return res;
+}
+
+test('inference URL guard rejects dangerous schemes, metadata aliases, and private remote targets', async () => {
+  for (const url of ['file:///etc/passwd', 'ftp://example.com', 'http://user:pass@example.com', 'http://169.254.169.254', 'http://[::ffff:a9fe:a9fe]', 'http://metadata.google.internal', 'http://[fd00:ec2::254]']) {
+    assert.equal((await validateInferenceBaseUrl(url, { callerIsTrusted: true })).ok, false, url);
+  }
+  for (const url of ['http://127.0.0.1:1234/v1', 'http://192.168.1.5:8000', 'http://[::1]:1234', 'http://[::ffff:7f00:1]']) {
+    assert.equal((await validateInferenceBaseUrl(url)).ok, false, url);
+    assert.equal((await validateInferenceBaseUrl(url, { callerIsTrusted: true })).ok, true, url);
+  }
+  assert.equal((await validateInferenceBaseUrl('https://8.8.8.8/v1')).ok, true);
+  assert.equal((await validateInferenceBaseUrl('https://example.com/' + 'x'.repeat(2048))).ok, false);
+});
+test('DNS checks every answer and blocks metadata even for trusted callers', async () => {
+  const lookupHost = async () => [{ address: '8.8.8.8' }, { address: '169.254.1.1' }];
+  assert.equal((await validateInferenceBaseUrl('https://inference.example', { callerIsTrusted: true, lookupHost })).ok, false);
+  assert.equal((await validateInferenceBaseUrl('http://local.example', { callerIsTrusted: true, lookupHost: async () => [{address:'192.168.1.1'}] })).ok, true);
+});
+test('remote errors are generic and local diagnostics are capped and redacted', () => {
+  assert.equal(sanitizeInferenceError('secret upstream response').includes('secret'), false);
+  const text = sanitizeInferenceError('Bearer secret sk-testsecret ' + 'x'.repeat(300), true);
+  assert.ok(text.length <= 200);
+  assert.ok(!text.includes('secret'));
+  assert.equal(isTrustedRequest(request({}, '203.0.113.1', 'wrong')), false);
+  assert.equal(isTrustedRequest(request({}, '203.0.113.1', 'inference-test-admin')), true);
+});
+test('provider validates model and returns live switch failures', async () => {
+  let res = response();
+  await handleProviderUpdateRoute(request({provider:'lmstudio', model:'bad<script>'}), res);
+  assert.equal(res.statusCode, 400);
+  setCurrentAgent({ client: { provider:'lmstudio', switchProvider: async () => { throw new Error('switch failed'); } } });
+  res = response();
+  await handleProviderUpdateRoute(request({provider:'lmstudio', model:'google/gemma-4-e4b'}), res);
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.json().switchError, 'switch failed');
+});
+test('remote cloud calls require actual admin credentials, including ai-suggest', async () => {
+  for (const route of [handleChatRoute, handleAiSuggestRoute]) {
+    const res = response();
+    await route(request({provider:'openai', query:'hello'}, '203.0.113.1', 'wrong'), res);
+    assert.equal(res.statusCode, 403);
+  }
+});
+test('invalid provider and oversized query are client errors', async () => {
+  for (const body of [{query:'hello',provider:'no-such-provider'}, {query:'x'.repeat(32001)}]) {
+    const res = response();
+    await handleChatRoute(request(body), res);
+    assert.equal(res.statusCode, 400);
+  }
+});
+test('settings generated inline scripts compile and define all inline handlers', () => {
+  const html = getSettingsHtml();
+  let scriptContent = '';
+  for (const match of html.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/g)) {
+    new vm.Script(match[1]);
+    scriptContent += '\n' + match[1];
+  }
+  assert.ok(scriptContent.includes('function onGpuOffloadChange'), 'onGpuOffloadChange must be defined');
+  assert.ok(scriptContent.includes('isLocal && !modelLoaded'), 'testConnectionProbe must distinguish server online vs model loaded in VRAM');
+});
+
+test('settings page comprehensively supports 3 languages (Thai, Chinese, English)', () => {
+  const html = getSettingsHtml();
+  assert.ok(html.includes('id="btn-lang-toggle"'), 'Language toggle button must be present in navbar');
+  assert.ok(html.includes('toggleSettingsLanguage()'), 'Language toggle button must invoke toggleSettingsLanguage()');
+  assert.ok(html.includes('data-i18n="heroTitle"'), 'Hero section must have data-i18n');
+  assert.ok(html.includes('data-i18n="tabEngine"'), 'Tabs must have data-i18n');
+
+  let scriptContent = '';
+  for (const match of html.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/g)) {
+    scriptContent += '\n' + match[1];
+  }
+  assert.ok(scriptContent.includes('const SETTINGS_I18N = {'), 'SETTINGS_I18N dictionary must be defined');
+  assert.ok(scriptContent.includes('function applySettingsLanguage('), 'applySettingsLanguage must be defined');
+  assert.ok(scriptContent.includes('function toggleSettingsLanguage()'), 'toggleSettingsLanguage must be defined');
+
+  
+  const sandbox = { window: {}, document: {}, localStorage: { getItem: () => 'th', setItem: () => {} }, console };
+  const ctx = vm.createContext(sandbox);
+  const i18nMatch = scriptContent.match(/const SETTINGS_I18N\s*=\s*(\{[\s\S]*?\n\s{4}\};)/);
+  assert.ok(i18nMatch, 'SETTINGS_I18N object match found');
+  vm.runInContext(i18nMatch[0].replace('const SETTINGS_I18N', 'SETTINGS_I18N'), ctx);
+  const dict = sandbox.SETTINGS_I18N;
+  assert.ok(dict.th && dict.zh && dict.en, 'All 3 languages (th, zh, en) must be defined in SETTINGS_I18N');
+  const thKeys = Object.keys(dict.th);
+  assert.ok(thKeys.length >= 70, 'Dictionary should cover at least 70 keys');
+  for (const key of thKeys) {
+    assert.ok(dict.zh[key], `Chinese translation missing for key: ${key}`);
+    assert.ok(dict.en[key], `English translation missing for key: ${key}`);
+  }
+});
+
+const settingsApi = await import('../config.js');
+const { handleStatusRoute } = await import('../../web-chat/routes/statusRoute.js');
+const { checkRateLimit } = await import('../../web-chat/core/security.js');
+test('inference persistence clamps, round trips, and preserves unrelated settings under queued writes', async () => {
+  fs.writeFileSync(path.join(temp, 'settings.json'), JSON.stringify({ legacy: 'kept' }));
+  await Promise.all([
+    settingsApi.withSettingsWriteQueue(() => settingsApi.savePersistedProviderBaseUrl('vllm', 'http://127.0.0.1:8000/v1')),
+    settingsApi.withSettingsWriteQueue(() => settingsApi.savePersistedActiveProvider('lmstudio', 'model-a')),
+    settingsApi.withSettingsWriteQueue(() => settingsApi.savePersistedProviderModel('lmstudio', 'model-b')),
+    settingsApi.withSettingsWriteQueue(() => settingsApi.savePersistedInferenceSettings({ temperature: 9, topP: 0, contextLimit: 1000000, persona: 'fan', thinking: 'hide', stream: false }))
+  ]);
+  const saved = JSON.parse(fs.readFileSync(path.join(temp, 'settings.json'), 'utf8'));
+  assert.equal(saved.legacy, 'kept');
+  assert.equal(saved.providerModels.lmstudio, 'model-b');
+  assert.equal(saved.providerBaseUrls.vllm, 'http://127.0.0.1:8000/v1');
+  assert.deepEqual(saved.inference, { temperature:2, topP:0.01, contextLimit:131072, persona:'fan', thinking:'hide', stream:false });
+  settingsApi.invalidateSettingsCache();
+  assert.deepEqual(settingsApi.getPersistedInferenceSettings(), saved.inference);
+  assert.ok(!fs.readdirSync(temp).some(name => name.endsWith('.tmp')));
+  await assert.rejects(settingsApi.withSettingsWriteQueue(() => { throw new Error('write failure'); }));
+  await settingsApi.withSettingsWriteQueue(() => settingsApi.savePersistedInferenceSettings({temperature:0}));
+  assert.equal(settingsApi.getPersistedInferenceSettings().temperature, 0);
+});
+test('rate limit buckets remain independent', () => {
+  for(let n=0;n<6;n++) assert.equal(checkRateLimit('test-ip', 'lan-discovery', 6).allowed, true);
+  assert.equal(checkRateLimit('test-ip', 'lan-discovery', 6).allowed, false);
+  assert.equal(checkRateLimit('test-ip', 'chat', 60).allowed, true);
+  for(let n=0;n<120;n++) assert.equal(checkRateLimit('test-ip', 'status-light', 120).allowed, true);
+  assert.equal(checkRateLimit('test-ip', 'status-light', 120).allowed, false);
+});
+test('light status performs no fetches and reports persisted inference', async t => {
+  const fetchMock = t.mock.method(globalThis, 'fetch', () => { throw new Error('light status must not fetch'); });
+  const res = response();
+  await handleStatusRoute(request({}), res, new URL('http://localhost/api/status?light=1'), 3000);
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.json().light, true);
+  assert.equal(fetchMock.mock.callCount(), 0);
+  assert.equal(res.json().inference.contextLimit, 131072);
+});
+test('chat caps inference overrides and emits visible fallback before catalog answer', async () => {
+  let options;
+  const resolveConnection = async opts => { options = opts; return { ready:false, error:'Upstream 429' }; };
+  let res = response();
+  await handleChatRoute(request({query:'hello',provider:'lmstudio',stream:false}), res, null, {resolveConnection});
+  assert.equal(res.statusCode, 502);
+  res = response();
+  await handleChatRoute(request({query:'hello',provider:'lmstudio',stream:true}), res, null, {resolveConnection});
+  assert.equal(res.statusCode, 200);
+  const events = res.chunks.split('\n').filter(line => line.startsWith('data: {')).map(line => JSON.parse(line.slice(6)));
+  assert.equal(events[0].type, 'error');
+  assert.equal(events[0].fallback, true);
+  assert.ok(events.some(e => e.type === 'final'));
+  assert.ok(res.chunks.includes('[DONE]'));
+  assert.equal(options.thinking, 'hide');
+});
+
+const { KIKU_DEFAULT_MODEL } = await import('../modelDefaults.js');
+const connModule = await import('../../web-chat/core/connection.js');
+const { handleLanApplyRoute } = await import('../../web-chat/routes/lanDiscoveryRoute.js');
+
+test('model defaults and web agent connection cleanup', () => {
+  assert.equal(KIKU_DEFAULT_MODEL, 'google/gemma-4-e4b');
+  assert.equal(typeof connModule.setCurrentAgent, 'function');
+  assert.equal(connModule.webAgentCache, undefined);
+  const html = getSettingsHtml();
+  assert.ok(html.includes("window.KIKU_DEFAULT_MODEL = '" + KIKU_DEFAULT_MODEL + "'"));
+  assert.ok(html.includes('id="btn-lang-toggle"'));
+  assert.ok(html.includes('gemini-3.7-flash'));
+});
+
+test('lan apply route persists configuration for discovered host', async () => {
+  const req = request({
+    host: '192.168.1.120',
+    port: 1234,
+    serverType: 'lmstudio',
+    model: 'custom-model'
+  });
+  const res = response();
+  await handleLanApplyRoute(req, res);
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.json().status, 'ok');
+  assert.equal(res.json().applied.provider, 'lmstudio');
+  assert.equal(res.json().applied.model, 'custom-model');
+  assert.equal(res.json().applied.baseUrl, 'http://192.168.1.120:1234/v1');
+});
+
+test('chat route accepts attached images with empty query and injects attachment context', async () => {
+  let capturedQuery = null;
+  let capturedDirectives = null;
+  const resolveConnection = async () => ({
+    ready: true,
+    agent: {
+      run: async (q, opts) => {
+        capturedQuery = q;
+        capturedDirectives = opts.systemDirectives;
+        return { answer: 'รูปภาพนี้คือผลงานของจวีจิ้งอีค่ะ' };
+      }
+    }
+  });
+
+  const attachments = [
+    { name: 'jujingyi_drama.jpg', size: 10240, type: 'image/jpeg', isImage: true, dataUrl: 'data:image/jpeg;base64,/9j/4AAQSkZJRg==' }
+  ];
+
+  
+  const resStream = response();
+  await handleChatRoute(request({ query: '', attachments, provider: 'lmstudio', stream: true }), resStream, null, { resolveConnection });
+  assert.equal(resStream.statusCode, 200);
+  assert.ok(capturedQuery.includes('jujingyi_drama.jpg'));
+  assert.ok(capturedQuery.includes('[USER ATTACHMENT:'));
+  assert.ok(capturedDirectives.some(d => d.includes('User Image Attachments Received')));
+  const events = resStream.chunks.split('\n').filter(line => line.startsWith('data: {')).map(line => JSON.parse(line.slice(6)));
+  const finalEvent = events.find(e => e.type === 'final');
+  assert.ok(finalEvent);
+  assert.equal(finalEvent.attachments?.length, 1);
+  assert.equal(finalEvent.attachments[0].name, 'jujingyi_drama.jpg');
+
+
+  const resJson = response();
+  await handleChatRoute(request({ query: 'ช่วยดูรูปนี้ให้หน่อย', attachments, provider: 'lmstudio', stream: false }), resJson, null, { resolveConnection });
+  assert.equal(resJson.statusCode, 200);
+  const jsonBody = resJson.json();
+  assert.equal(jsonBody.status, 'ok');
+  assert.equal(jsonBody.attachments?.length, 1);
+  assert.equal(jsonBody.attachments[0].name, 'jujingyi_drama.jpg');
+});
+
+test('chat route rescues refusal or empty answers for image attachments with helpful image fallback', async () => {
+  const resolveConnection = async () => ({
+    ready: true,
+    agent: {
+      run: async () => ({ answer: 'ขออภัยค่ะ ไม่สามารถประมวลผลคำตอบได้' })
+    }
+  });
+
+  const attachments = [
+    { name: 'in_blossom_poster.jpg', size: 20480, type: 'image/jpeg', isImage: true, dataUrl: 'data:image/jpeg;base64,/9j/4AAQSkZJRg==' }
+  ];
+
+  const resJson = response();
+  await handleChatRoute(request({ query: '', attachments, provider: 'lmstudio', stream: false }), resJson, null, { resolveConnection });
+  assert.equal(resJson.statusCode, 200);
+  const jsonBody = resJson.json();
+  assert.ok(!jsonBody.answer.includes('ขออภัยค่ะ ไม่สามารถประมวลผลคำตอบได้'));
+  assert.ok(jsonBody.answer.includes('ได้รับรูปภาพเรียบร้อยแล้วค่ะ') || jsonBody.answer.includes('In Blossom') || jsonBody.answer.includes('ฮวาเจียนลิ่ง'));
+});
+
+test('chat route resolves catalog entities from image filename into recognition hints', async () => {
+  let capturedQuery = null;
+  const resolveConnection = async () => ({
+    ready: true,
+    agent: {
+      run: async (q) => {
+        capturedQuery = q;
+        return { answer: 'รับทราบภาพ In Blossom ค่ะ' };
+      }
+    }
+  });
+
+  const attachments = [
+    { name: 'in_blossom.jpg', size: 15000, type: 'image/jpeg', isImage: true, dataUrl: 'data:image/jpeg;base64,/9j/4AAQSkZJRg==' }
+  ];
+
+  const resJson = response();
+  await handleChatRoute(request({ query: 'รูปนี้เรื่องอะไร', attachments, provider: 'lmstudio', stream: false }), resJson, null, { resolveConnection });
+  assert.equal(resJson.statusCode, 200);
+  assert.ok(capturedQuery.includes('[IMAGE RECOGNITION HINTS:'));
+  assert.ok(capturedQuery.includes('In Blossom') || capturedQuery.includes('花间令'));
+});
+