kiku-agent 1.0.0 → 1.0.3

package/server/agent/commands.js

@@ -1,788 +1,1694 @@
-import { toolsSchema, executeTool } from './tools.js';
-import { audioPlayer } from './audioPlayer.js';
-import { ensureYouTubeCookies, resetCookieCheck, getCookieStatus } from './youtubeAuth.js';
-import { AgentMemory } from './memory.js';
-import { C, UI_ICONS, printSolidPanel, randomFanName } from './ui.js';
-import { COMMAND_NAMES } from './commandRegistry.js';
-import { THEMES, THEME_NAMES, ansiBackground, ansiForeground, getThemeName, setTheme } from './theme.js';
-
-function levenshteinDistance(a, b) {
-  const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
-  for (let i = 0; i <= a.length; i++) matrix[i][0] = i;
-  for (let j = 0; j <= b.length; j++) matrix[0][j] = j;
-  for (let i = 1; i <= a.length; i++) {
-    for (let j = 1; j <= b.length; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      matrix[i][j] = Math.min(
-        matrix[i - 1][j] + 1,
-        matrix[i][j - 1] + 1,
-        matrix[i - 1][j - 1] + cost
-      );
-    }
-  }
-  return matrix[a.length][b.length];
-}
-
-const VALID_COMMANDS = [...COMMAND_NAMES, '/export'];
-
-export function findClosestCommand(cmd) {
-  let closest = null;
-  let minDistance = Infinity;
-  for (const vc of VALID_COMMANDS) {
-    const dist = levenshteinDistance(cmd.toLowerCase(), vc);
-    if (dist < minDistance) {
-      minDistance = dist;
-      closest = vc;
-    }
-  }
-  return minDistance <= 3 ? closest : null;
-}
-
-export function fuzzyMatchTools(query) {
-  if (!query) return toolsSchema.map(t => ({ tool: t, score: 10 }));
-  const q = query.toLowerCase();
-  const qWords = q.split(/\s+/).filter(Boolean);
-
-  const scored = toolsSchema.map(t => {
-    const name = t.function.name.toLowerCase();
-    const desc = (t.function.description || '').toLowerCase();
-    let score = 0;
-
-    if (name === q) score = 200;
-    else if (name.startsWith(q)) score = 150;
-    else if (name.includes(q)) score = 100;
-    else if (qWords.every(w => name.includes(w))) score = 80;
-    else if (qWords.some(w => name.includes(w))) score = 65;
-    else if (qWords.every(w => desc.includes(w))) score = 50;
-    else if (qWords.some(w => desc.includes(w))) score = 40;
-    else {
-      const dist = levenshteinDistance(q, name);
-      const threshold = Math.floor(Math.min(q.length, name.length) * 0.4);
-      if (dist <= threshold && dist <= 6) score = 30 - dist * 3;
-      if (score === 0) {
-        for (const word of name.split('_')) {
-          const wd = levenshteinDistance(q, word);
-          const wThreshold = Math.floor(Math.min(q.length, word.length) * 0.4);
-          if (wd <= wThreshold && wd <= 4) {
-            score = Math.max(score, 35 - wd * 5);
-          }
-        }
-      }
-    }
-
-    return { tool: t, score };
-  });
-
-  return scored
-    .filter(s => s.score > 0)
-    .sort((a, b) => b.score - a.score);
-}
-
-export const handlers = {
-  '/exit': async (ctx) => {
-    try { await ctx.agent.endSession(); } catch {}
-    console.log(`\n  ${C.sakura}Session archived. Thank you for supporting Ju Jingyi. Goodbye. (鞠躬 ~ 谢谢!)${C.reset}\n`);
-    return 'EXIT';
-  },
-
-  '/help': async (ctx) => {
-    const sub = ctx.extra || '';
-    ctx.printHelp(sub);
-    return 'HANDLED';
-  },
-
-  '/details': async (ctx) => {
-    ctx.printQueryDetails(ctx.sub || '');
-    return 'HANDLED';
-  },
-
-  '/history': async (ctx) => {
-    const { agent, sub, extra } = ctx;
-    if (sub === 'clear') {
-      agent.session.messages = [];
-      agent.conversationHistory = [agent.conversationHistory[0]];
-      await agent.session.clearDisk().catch(() => {});
-      console.log(`\n  ${C.emerald}[OK] Chat history cleared.${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    if (sub === 'search' && extra) {
-      const q = extra.toLowerCase().trim();
-      const matches = [];
-      for (const msg of agent.session.messages) {
-        const textPart = msg.parts.find(p => p.type === 'text');
-        if (textPart && textPart.content.toLowerCase().includes(q)) {
-          matches.push({ role: msg.role, text: textPart.content, createdAt: msg.createdAt });
-        }
-      }
-      printSolidPanel({
-        title: `History Search Results for "${extra}" (${matches.length} matches)`,
-        lines: matches.length === 0
-          ? [`${C.dim}No messages found matching "${extra}".${C.reset}`]
-          : matches.map(m => {
-            const prefix = m.role === 'user' ? `${C.roseGlow}User` : `${C.cyberCyan}Kiku`;
-            return `${prefix}:${C.reset} ${C.white}${m.text.slice(0, 80)}${m.text.length > 80 ? '...' : ''}${C.reset}`;
-          }),
-        headerBg: '\x1b[48;2;48;54;70m',
-        bg: '\x1b[48;2;36;40;52m'
-      });
-      return 'HANDLED';
-    }
-
-    let count = 10;
-    if (sub && !isNaN(parseInt(sub))) count = Math.min(parseInt(sub), 50);
-
-    const recentMessages = agent.session.messages.slice(-count);
-    if (recentMessages.length === 0) {
-      console.log(`\n  ${C.dim}No conversation history yet.${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    const lines = [];
-    for (const msg of recentMessages) {
-      if (msg.role === 'user') {
-        const textPart = msg.parts.find(p => p.type === 'text');
-        if (textPart) {
-          lines.push(`${C.roseGlow}${C.bold}${randomFanName()}:${C.reset} ${C.white}${textPart.content}${C.reset}`);
-        }
-      } else if (msg.role === 'assistant') {
-        const textPart = msg.parts.find(p => p.type === 'text');
-        if (textPart) {
-          const preview = textPart.content.length > 120 ? textPart.content.slice(0, 120) + '…' : textPart.content;
-          lines.push(`${C.cyberCyan}${C.bold}Kiku:${C.reset} ${C.white}${preview.replace(/\n/g, ' ')}${C.reset}`);
-        }
-      }
-    }
-    printSolidPanel({
-      title: `Conversation History (last ${recentMessages.length} messages)`,
-      lines,
-      headerBg: '\x1b[48;2;48;54;70m',
-      bg: '\x1b[48;2;36;40;52m'
-    });
-    return 'HANDLED';
-  },
-
-  '/session': async (ctx) => {
-    const { agent, sub } = ctx;
-    const sess = agent.session;
-    const action = (sub || 'info').toLowerCase();
-
-    if (action === 'info' || !action) {
-      const msgCount = sess.messages.length;
-      const userMsgs = sess.messages.filter(m => m.role === 'user').length;
-      const assistantMsgs = sess.messages.filter(m => m.role === 'assistant').length;
-      const toolCalls = sess.stats.totalToolCalls || 0;
-      const totalDur = ((sess.stats.totalDurationMs || 0) / 1000).toFixed(1);
-      const createdAt = sess.createdAt ? sess.createdAt.toLocaleString() : 'unknown';
-
-      printSolidPanel({
-        title: `Active Session Details`,
-        lines: [
-          `${C.gold}Session ID:${C.reset}      ${C.white}${sess.id}${C.reset}`,
-          `${C.gold}Created At:${C.reset}      ${C.white}${createdAt}${C.reset}`,
-          `${C.gold}Total Messages:${C.reset}  ${C.cyberCyan}${msgCount}${C.reset} total ${C.dim}(${userMsgs} user, ${assistantMsgs} assistant)${C.reset}`,
-          `${C.gold}Total Queries:${C.reset}   ${C.cyberCyan}${sess.stats.totalQueries}${C.reset}`,
-          `${C.gold}Tool Calls:${C.reset}      ${C.cyberCyan}${toolCalls}${C.reset}`,
-          `${C.gold}Total Duration:${C.reset}  ${C.cyberCyan}${totalDur}s${C.reset}`,
-          `${C.gold}Thinking Mode:${C.reset}   ${C.bold}${C.gold}${sess.thinkingMode.toUpperCase()}${C.reset}`
-        ],
-        headerBg: '\x1b[48;2;48;54;70m',
-        bg: '\x1b[48;2;36;40;52m'
-      });
-      return 'HANDLED';
-    }
-
-    if (action === 'list') {
-      const sessions = agent.memory.getArchivedSessions(15);
-      printSolidPanel({
-        title: `Archived Sessions (Total: ${sessions.length})`,
-        lines: sessions.length === 0
-          ? [`${C.dim}No archived sessions found.${C.reset}`]
-          : sessions.map(s => {
-            const date = new Date(s.createdAt).toLocaleString();
-            const dur = ((s.stats?.totalDurationMs || 0) / 1000).toFixed(1);
-            return `${C.gold}${s.id}${C.reset} ${C.dim}(${date})${C.reset} — ${s.messageCount} msgs, ${dur}s`;
-          }),
-        headerBg: '\x1b[48;2;48;54;70m',
-        bg: '\x1b[48;2;36;40;52m'
-      });
-      return 'HANDLED';
-    }
-
-    if (action === 'export') {
-      const exported = await agent.session.exportToMarkdown();
-      console.log(`\n  ${C.emerald}[OK] Session transcript exported.${C.reset}`);
-      console.log(`  ${C.slate}• File:${C.reset} ${C.white}${exported.filePath}${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    if (action === 'clear' || action === 'new' || action === 'reset') {
-      await agent.endSession();
-      console.log(`\n  ${C.emerald}[OK] Previous session archived. Started fresh.${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    console.log(`\n  ${C.amber}Unknown session action: "${sub}". Use /session [info|list|export|clear]${C.reset}\n`);
-    return 'HANDLED';
-  },
-
-  '/thinking': async (ctx) => {
-    const { agent, sub } = ctx;
-    const targetMode = (sub || '').toLowerCase();
-    if (targetMode === 'show' || targetMode === 'hide') {
-      agent.session.setThinkingMode(targetMode);
-      console.log(`\n  ${C.emerald}[OK] Thinking mode set to ${C.bold}${targetMode.toUpperCase()}${C.reset}\n`);
-    } else {
-      const current = agent.session.toggleThinkingMode();
-      console.log(`\n  ${C.emerald}[OK] Thinking mode toggled to ${C.bold}${current.toUpperCase()}${C.reset}\n`);
-    }
-    return 'HANDLED';
-  },
-
-  '/lang': async (ctx) => {
-    const { agent, sub } = ctx;
-    const langArg = (sub || '').toLowerCase();
-    if (langArg === 'th' || langArg === 'zh' || langArg === 'en' || langArg === 'auto') {
-      agent.memory.setPreference('language', langArg === 'auto' ? null : langArg);
-      const langNames = { th: 'Thai', zh: 'Chinese', en: 'English', auto: 'Auto-detect' };
-      console.log(`\n  ${C.emerald}[OK] Language updated to:${C.reset} ${C.bold}${C.white}${langNames[langArg]}${C.reset}\n`);
-    } else {
-      const current = agent.memory.preferences.language || 'auto';
-      printSolidPanel({
-        title: `Language Preference`,
-        lines: [`${C.gold}Current:${C.reset} ${C.bold}${C.white}${current.toUpperCase()}${C.reset}`, `${C.dim}Usage: /lang [th|zh|en|auto]${C.reset}`],
-        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-      });
-    }
-    return 'HANDLED';
-  },
-
-  '/theme': async (ctx) => {
-    const action = (ctx.sub || 'current').toLowerCase();
-    const current = getThemeName();
-
-    if (action === 'list') {
-      printSolidPanel({
-        title: `Themes (${THEME_NAMES.length})`,
-        lines: THEME_NAMES.map(name => {
-          const theme = THEMES[name];
-          const marker = name === current ? '[x]' : '[ ]';
-          const sample = ansiForeground(theme.colors.primary);
-          const preview = `${ansiBackground(theme.colors.panel)}${ansiForeground(theme.colors.text)}${C.bold} Aa ${C.reset}`;
-          return `${marker} ${preview} ${sample}${C.bold}${name.padEnd(12)}${C.reset} ${C.dim}${theme.description}${C.reset}`;
-        }),
-      });
-      return 'HANDLED';
-    }
-
-    if (action === 'current') {
-      const theme = THEMES[current];
-      printSolidPanel({
-        title: 'Theme',
-        lines: [
-          `${C.gold}Current:${C.reset} ${C.bold}${C.white}${theme.label} (${current})${C.reset}`,
-          `${C.dim}${theme.description}${C.reset}`,
-          `${C.sakura}Primary${C.reset}  ${C.roseGlow}Accent${C.reset}  ${C.cyberCyan}Info${C.reset}  ${C.emerald}Success${C.reset}  ${C.amber}Warning${C.reset}  ${C.red}Error${C.reset}`,
-          `${C.dim}Usage: /theme list or /theme <name>${C.reset}`,
-        ],
-      });
-      return 'HANDLED';
-    }
-
-    const requested = action === 'reset' ? 'sakura' : action;
-    const theme = setTheme(requested);
-    if (!theme) {
-      console.log(`\n  ${C.amber}Unknown theme: "${action}".${C.reset}`);
-      console.log(`  ${C.dim}Available: ${THEME_NAMES.join(', ')}${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    printSolidPanel({
-      title: 'Theme Updated',
-      lines: [
-        `${C.emerald}[OK] Active theme: ${C.bold}${theme.label} (${requested})${C.reset}`,
-        `${C.dim}${theme.description}${C.reset}`,
-        `${C.sakura}Primary${C.reset}  ${C.roseGlow}Accent${C.reset}  ${C.cyberCyan}Info${C.reset}  ${C.emerald}Success${C.reset}  ${C.amber}Warning${C.reset}  ${C.red}Error${C.reset}`,
-        `${C.dim}Saved for future Kiku Agent sessions.${C.reset}`,
-      ],
-    });
-    return 'HANDLED';
-  },
-
-  '/tool': async (ctx) => {
-    const { sub, extra } = ctx;
-    const toolName = sub;
-    const rawArgs = extra || '';
-
-    if (!toolName) {
-      console.log(`\n  ${C.amber}Usage: /tool <tool_name> [args]${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    const schema = toolsSchema.find(t => t.function.name.toLowerCase() === toolName.toLowerCase());
-    if (!schema) {
-      console.log(`\n  ${C.red}Unknown tool: "${toolName}". Use /tools to view all.${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    const actualToolName = schema.function.name;
-
-    if (!rawArgs || !rawArgs.trim()) {
-      const props = schema.function.parameters?.properties || {};
-      const required = schema.function.parameters?.required || [];
-      console.log(`\n  ${C.gold}Tool:${C.reset} ${C.bold}${C.cyberCyan}${actualToolName}${C.reset}`);
-      console.log(`  ${C.gold}Description:${C.reset} ${C.white}${schema.function.description}${C.reset}`);
-      for (const [pName, pMeta] of Object.entries(props)) {
-        const reqStr = required.includes(pName) ? `${C.red}[required]${C.reset}` : `${C.dim}[optional]${C.reset}`;
-        console.log(`    • ${C.bold}${pName}${C.reset} (${pMeta.type || 'any'}) ${reqStr}: ${pMeta.description || ''}`);
-      }
-      console.log(`\n`);
-      return 'HANDLED';
-    }
-
-    let parsedArgs = {};
-    if (rawArgs.startsWith('{') && rawArgs.endsWith('}')) {
-      try { parsedArgs = JSON.parse(rawArgs); } catch { parsedArgs = { query: rawArgs }; }
-    } else {
-      const props = schema.function.parameters?.properties || {};
-      const firstProp = Object.keys(props)[0] || 'query';
-      parsedArgs = { [firstProp]: rawArgs };
-    }
-
-    console.log(`\n  ${C.cyberCyan}[RUNNING] ${C.bold}${actualToolName}${C.reset}...`);
-    const start = Date.now();
-    try {
-      const result = await executeTool(actualToolName, parsedArgs);
-      const dur = ((Date.now() - start) / 1000).toFixed(2);
-      console.log(`  ${C.emerald}[OK] Completed in ${dur}s${C.reset}`);
-      console.log(JSON.stringify(result, null, 2));
-      console.log('');
-    } catch (err) {
-      console.log(`  ${C.red}[ERROR] ${err.message}${C.reset}\n`);
-    }
-    return 'HANDLED';
-  },
-
-  '/tools': async (ctx) => {
-    const filter = (ctx.sub || '').toLowerCase().trim();
-    const filtered = filter
-      ? toolsSchema.filter(t => t.function.name.toLowerCase().includes(filter) || t.function.description.toLowerCase().includes(filter))
-      : toolsSchema;
-
-    console.log(`\n  ${C.bold}${C.sakura}Registered Tools (${filtered.length}/${toolsSchema.length})${C.reset}\n`);
-    for (const [idx, t] of filtered.entries()) {
-      const f = t.function;
-      const params = Object.keys(f.parameters?.properties || {}).join(', ');
-      console.log(`  ${C.gold}${String(idx + 1).padStart(2)}. ${C.bold}${C.cyberCyan}${f.name}${C.reset}${C.slate}(${params})${C.reset}`);
-      console.log(`      ${C.dim}${C.roseGlow}${f.description}${C.reset}`);
-    }
-    console.log(`\n`);
-    return 'HANDLED';
-  },
-
-  '/mem': async (ctx) => {
-    const { agent, sub, extra, parts } = ctx;
-    const memAction = (sub || '').toLowerCase();
-
-    if (memAction === 'add') {
-      const factText = (parts || []).slice(2).join(' ').trim();
-      if (!factText) {
-        console.log(`\n  ${C.amber}Usage: /mem add <fact>${C.reset}\n`);
-      } else {
-        const entry = agent.memory.addFact(factText, { source: 'user' });
-        console.log(`\n  ${C.emerald}[OK] Saved:${C.reset} ${C.white}${factText.slice(0, 80)}${C.reset} (ID: ${entry.id})\n`);
-      }
-      return 'HANDLED';
-    }
-
-    if (memAction === 'del' || memAction === 'rm') {
-      const factId = (parts || [])[2]?.trim();
-      if (!factId) {
-        console.log(`\n  ${C.amber}Usage: /mem del <fact_id>${C.reset}\n`);
-      } else if (agent.memory.removeFact(factId)) {
-        console.log(`\n  ${C.emerald}[OK] Removed [${factId}]${C.reset}\n`);
-      } else {
-        console.log(`\n  ${C.red}Not found [${factId}]${C.reset}\n`);
-      }
-      return 'HANDLED';
-    }
-
-    if (memAction === 'search') {
-      const query = (parts || []).slice(2).join(' ').trim();
-      if (!query) {
-        console.log(`\n  ${C.amber}Usage: /mem search <keyword>${C.reset}\n`);
-      } else {
-        const results = agent.memory.searchFacts(query);
-        printSolidPanel({
-          title: `Memory Search: "${query}" (${results.length})`,
-          lines: results.map(fact => `${C.white}${fact.content.slice(0, 65)}${C.reset} ${C.dim}(${fact.id})${C.reset}`),
-        });
-      }
-      return 'HANDLED';
-    }
-
-    if (memAction === 'list') {
-      const grouped = agent.memory.getFactsByCategory();
-      const factLines = [];
-      for (const [cat, facts] of Object.entries(grouped)) {
-        factLines.push(`${C.bold}${C.cyberCyan}${cat.toUpperCase()}${C.reset} (${facts.length})`);
-        for (const fact of facts.slice(0, 6)) {
-          factLines.push(` • ${C.white}${fact.content.slice(0, 65)}${C.reset}`);
-        }
-      }
-      printSolidPanel({ title: 'Stored Facts', lines: factLines });
-      return 'HANDLED';
-    }
-
-    if (memAction === 'topics') {
-      const topics = agent.memory.getTopTopics(10);
-      printSolidPanel({
-        title: 'Topic Profile',
-        lines: topics.map(t => {
-        const bar = '█'.repeat(Math.min(t.count, 15));
-          return `${C.gold}${t.topic.padEnd(14)}${C.reset} ${C.cyberCyan}${bar}${C.reset} ${C.dim}(${t.count}x)${C.reset}`;
-        }),
-      });
-      return 'HANDLED';
-    }
-
-    if (memAction === 'export') {
-      const exported = await agent.memory.exportToJSON();
-      console.log(`\n  ${C.emerald}[OK] Memory exported.${C.reset} ${C.white}${exported.filePath}${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    if (memAction === 'import') {
-      const filePath = (parts || []).slice(2).join(' ').trim();
-      if (!filePath) {
-        console.log(`\n  ${C.amber}Usage: /mem import <path>${C.reset}\n`);
-      } else {
-        const result = await agent.memory.importFromJSON(filePath);
-        if (result.success) {
-          console.log(`\n  ${C.emerald}[OK] Imported ${result.factsImported} facts.${C.reset}\n`);
-        } else {
-          console.log(`\n  ${C.red}[ERROR] ${result.message}${C.reset}\n`);
-        }
-      }
-      return 'HANDLED';
-    }
-
-    if (memAction === 'clear') {
-      await agent.memory.clearAll();
-      console.log(`\n  ${C.emerald}[OK] Memory cleared.${C.reset}\n`);
-      return 'HANDLED';
-    }
-
-    const memStatus = agent.memory.getStatus();
-    printSolidPanel({
-      title: 'Memory Status',
-      lines: [`${C.gold}Facts:${C.reset} ${C.cyberCyan}${memStatus.factsCount}${C.reset}  ${C.gold}Sessions:${C.reset} ${C.cyberCyan}${memStatus.sessionsCount}${C.reset}`],
-    });
-    return 'HANDLED';
-  },
-
-  '/play': async (ctx) => {
-    const songName = ctx.extra || '';
-    if (!songName) {
-      console.log(`\n  ${C.amber}Usage: /play <song name>${C.reset}\n`);
-    } else {
-      await audioPlayer.play(songName);
-      console.log(`\n  ${C.emerald}[OK] Playing: ${C.white}${songName}${C.reset}\n`);
-    }
-    return 'HANDLED';
-  },
-
-  '/stop': async () => { await audioPlayer.stop(); console.log(`\n  ${C.emerald}[OK] Stopped${C.reset}\n`); return 'HANDLED'; },
-  '/pause': async () => { const r = await audioPlayer.pause(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
-  '/resume': async () => { const r = await audioPlayer.resume(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
-  '/next': async () => { const r = await audioPlayer.next(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
-  '/prev': async () => { const r = await audioPlayer.prev(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
-  '/mute': async () => { const r = await audioPlayer.mute(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
-  '/unmute': async () => { const r = await audioPlayer.unmute(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
-
-  '/add': async (ctx) => {
-    const song = ctx.extra || '';
-    if (!song) { console.log(`\n  ${C.amber}Usage: /add <song>${C.reset}\n`); }
-    else { const r = await audioPlayer.addToQueue(song); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); }
-    return 'HANDLED';
-  },
-
-  '/remove': async (ctx) => {
-    const index = parseInt(ctx.sub, 10);
-    if (isNaN(index)) { console.log(`\n  ${C.amber}Usage: /remove <index>${C.reset}\n`); }
-    else { const r = await audioPlayer.removeFromQueue(index); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); }
-    return 'HANDLED';
-  },
-
-  '/clearqueue': async () => { const r = await audioPlayer.clearQueue(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
-
-  '/search': async (ctx) => {
-    const q = ctx.extra || '';
-    if (!q) { console.log(`\n  ${C.amber}Usage: /search <query>${C.reset}\n`); return 'HANDLED'; }
-    try {
-      const results = await audioPlayer.searchYouTube(q);
-      if (results.length === 0) { console.log(`\n  ${C.amber}No results for "${q}"${C.reset}\n`); }
-      else {
-        printSolidPanel({
-          title: `YouTube: "${q}" (${results.length})`,
-          lines: results.map((r, i) => `${C.gold}${i + 1}.${C.reset} ${C.white}${r.title}${C.reset} ${C.dim}(${r.duration})${C.reset}`),
-          headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-        });
-      }
-    } catch (err) { console.log(`\n  ${C.red}${err.message}${C.reset}\n`); }
-    return 'HANDLED';
-  },
-
-  '/current': async () => {
-    const state = audioPlayer.getFullState();
-    if (!state.isPlaying && !state.isPaused) {
-      console.log(`\n  ${C.slate}No music playing.${C.reset}\n`);
-    } else {
-      printSolidPanel({
-        title: `${UI_ICONS.music} Current Track`,
-        lines: [
-          `${C.gold}Track:${C.reset} ${C.white}${state.currentTrack}${C.reset}`,
-          `${C.gold}Status:${C.reset} ${state.isPaused ? C.amber + 'Paused' : C.emerald + 'Playing'}${C.reset}`,
-          `${C.gold}Queue:${C.reset} ${C.cyberCyan}${state.queueLength} songs${C.reset}`
-        ],
-        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-      });
-    }
-    return 'HANDLED';
-  },
-
-  '/retry': async (ctx) => {
-    if (!ctx.lastQuery) {
-      console.log(`\n  ${C.amber}No previous query.${C.reset}\n`);
-      return 'HANDLED';
-    }
-    return 'RETRY';
-  },
-
-  '/clear': async (ctx) => {
-    try { await ctx.agent.endSession(); } catch {}
-    console.clear();
-    ctx.printWelcome();
-    console.log(`  ${C.emerald}[OK] Fresh start.${C.reset}\n`);
-    return 'HANDLED';
-  },
-
-  '/save': async (ctx) => {
-    const exported = await ctx.agent.session.exportToMarkdown();
-    console.log(`\n  ${C.emerald}[OK] Exported.${C.reset} ${C.white}${exported.filePath}${C.reset}\n`);
-    return 'HANDLED';
-  },
-
-  '/model': async (ctx) => {
-    const liveCheck = await ctx.client.checkConnection();
-    printSolidPanel({
-      title: `LM Studio Diagnostics`,
-      lines: [
-        `${C.gold}Status:${C.reset} ${liveCheck.connected ? C.emerald + '● Online' : C.red + '○ Offline'}${C.reset}`,
-        `${C.gold}Model:${C.reset}  ${C.bold}${C.white}${liveCheck.activeModel || 'None'}${C.reset}`,
-        `${C.gold}URL:${C.reset}   ${C.cyberCyan}${ctx.baseUrl}${C.reset}`
-      ],
-      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-    });
-    return 'HANDLED';
-  },
-
-  '/ping': async (ctx) => {
-    const start = Date.now();
-    const check = await ctx.client.checkConnection();
-    const ms = Date.now() - start;
-    if (check.connected) {
-      console.log(`\n  ${C.emerald}● Connected${C.reset} ${C.dim}(${ms}ms)${C.reset} — ${C.white}${check.activeModel}${C.reset}\n`);
-    } else {
-      console.log(`\n  ${C.red}● Disconnected${C.reset} ${C.dim}(${ms}ms)${C.reset}\n`);
-    }
-    return 'HANDLED';
-  },
-
-  '/config': async (ctx) => {
-    const { config } = await import('./config.js');
-    printSolidPanel({
-      title: `Configuration`,
-      lines: [
-        `${C.gold}URL:${C.reset}      ${C.cyberCyan}${ctx.baseUrl}${C.reset}`,
-        `${C.gold}Model:${C.reset}     ${C.white}${config.lmStudio.model}${C.reset}`,
-        `${C.gold}Theme:${C.reset}     ${C.white}${getThemeName()}${C.reset}`,
-        `${C.gold}Max Iters:${C.reset} ${C.white}${ctx.agent.maxIterations}${C.reset}`,
-        `${C.gold}Window:${C.reset}    ${C.white}${ctx.agent.slidingWindowSize}${C.reset}`,
-        `${C.gold}Tools:${C.reset}     ${C.cyberCyan}${toolsSchema.length}${C.reset}`
-      ],
-      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-    });
-    return 'HANDLED';
-  },
-
-  '/version': async () => {
-    printSolidPanel({
-      title: 'Version',
-      lines: [
-        `${C.gold}Version:${C.reset} ${C.white}1.0.0${C.reset}`,
-        `${C.gold}Node:${C.reset}    ${C.white}${process.version}${C.reset}`,
-        `${C.gold}Platform:${C.reset} ${C.white}${process.platform} ${process.arch}${C.reset}`,
-      ],
-    });
-    return 'HANDLED';
-  },
-
-  '/system': async () => {
-    const os = await import('node:os');
-    const mem = process.memoryUsage();
-    printSolidPanel({
-      title: 'System',
-      lines: [
-        `${C.gold}OS:${C.reset}   ${C.white}${os.default.platform()} ${os.default.release()}${C.reset}`,
-        `${C.gold}CPU:${C.reset}  ${C.white}${os.default.cpus().length} cores${C.reset}`,
-        `${C.gold}RAM:${C.reset}  ${C.white}${(os.default.totalmem() / 1073741824).toFixed(1)} GB${C.reset}`,
-        `${C.gold}Heap:${C.reset} ${C.white}${(mem.heapUsed / 1048576).toFixed(1)} MB${C.reset}`,
-      ],
-    });
-    return 'HANDLED';
-  },
-
-  '/about': async () => {
-    printSolidPanel({
-      title: 'About Kiku AI Agent',
-      lines: [
-        `${C.white}Intelligent assistant for Ju Jingyi (鞠婧祎)${C.reset}`,
-        `${C.gold}Engine:${C.reset} ${C.white}LM Studio + Gemma 4${C.reset}`,
-        `${C.gold}Tools:${C.reset} ${C.white}${toolsSchema.length} registered${C.reset}`,
-        `${C.gold}Languages:${C.reset} ${C.white}TH, ZH, EN (auto)${C.reset}`,
-      ],
-    });
-    return 'HANDLED';
-  },
-
-  '/login': async (ctx) => {
-    console.log(`\n  ${C.cyberCyan}YouTube Login${C.reset}\n`);
-    resetCookieCheck();
-    const result = await ensureYouTubeCookies({ timeout: 180000 });
-    if (result.ok) {
-      console.log(`  ${C.emerald}[OK] Session active (${result.source}).${C.reset}\n`);
-    } else {
-      console.log(`  ${C.red}[ERROR] Not available: ${result.reason}${C.reset}\n`);
-    }
-    return 'HANDLED';
-  },
-
-  '/ytstatus': async () => {
-    const status = getCookieStatus();
-    const ensured = status.ensured;
-    printSolidPanel({
-      title: 'YouTube Status',
-      lines: [
-        `${C.gold}Browser:${C.reset} ${status.envBrowser ? C.emerald + status.envBrowser : C.dim + 'n/a'}${C.reset}`,
-        `${C.gold}Cookies:${C.reset} ${status.envCookies ? C.emerald + status.envCookies : C.dim + 'n/a'}${C.reset}`,
-        `${C.gold}Status:${C.reset}  ${ensured ? (ensured.ok ? C.emerald + '[OK]' : C.red + '[ERROR] Failed') : C.dim + 'Unchecked'}${C.reset}`
-      ],
-      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-    });
-    return 'HANDLED';
-  },
-
-  '/queue': async (ctx) => {
-    const { sub } = ctx;
-    if (sub === 'clear') {
-      if (audioPlayer.isPlaying || audioPlayer.queue.length > 0) {
-        console.log(`\n  ${C.emerald}${await audioPlayer.clearQueue()}${C.reset}\n`);
-      } else {
-        ctx.clearQueryQueue();
-        console.log(`\n  ${C.emerald}[OK] Execution queue cleared.${C.reset}\n`);
-      }
-    } else if (audioPlayer.isPlaying || audioPlayer.queue.length > 0) {
-      const queue = audioPlayer.getQueue();
-      printSolidPanel({
-        title: `${UI_ICONS.music} Queue (${queue.length})`,
-        lines: queue.map((item, idx) => `${item.isCurrent ? C.gold + '[PLAYING]' : C.dim + (idx + 1)} ${C.white}${item.title}${C.reset}`),
-        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-      });
-    } else {
-      const qLen = ctx.getQueryQueueLength();
-      console.log(`\n  ${C.slate}Execution queue: ${qLen} items${C.reset}\n`);
-    }
-    return 'HANDLED';
-  },
-
-  '/stats': async () => {
-    const result = await executeTool('get_system_stats', {});
-    const s = result.stats;
-    printSolidPanel({
-      title: `Database Overview`,
-      lines: [
-        `${C.gold}Works:${C.reset}     ${C.cyberCyan}${s.totalWorks}${C.reset}`,
-        `${C.gold}Songs:${C.reset}     ${C.cyberCyan}${s.totalUniqueSongs}${C.reset}`,
-        `${C.gold}Brands:${C.reset}    ${C.cyberCyan}${s.brandEndorsements}${C.reset}`,
-        `${C.gold}Awards:${C.reset}    ${C.cyberCyan}${s.totalAwards}${C.reset}`,
-        `${C.gold}Timeline:${C.reset}  ${C.cyberCyan}${s.timelineMilestones}${C.reset}`
-      ],
-      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
-    });
-    return 'HANDLED';
-  },
-
-  '/prompt': async (ctx) => {
-    const { config } = await import('./config.js');
-    const lines = config.agent.systemPersona.split('\n').slice(0, 20).map(l => `${C.dim}${C.white}${l}${C.reset}`);
-    printSolidPanel({ title: `System Prompt`, lines, headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m' });
-    return 'HANDLED';
-  },
-
-  '/ads': async (ctx) => {
-    ctx.printAd();
-    return 'HANDLED';
-  },
-};
-
-const ALIASES = {
-  '/quit': '/exit', '/q': '/exit',
-  '/?': '/help', '/commands': '/help', '/menu': '/help',
-  '/hist': '/history', '/h': '/history',
-  '/sess': '/session', '/sessions': '/session',
-  '/think': '/thinking', '/th': '/thinking',
-  '/detail': '/details', '/d': '/details',
-  '/language': '/lang',
-  '/themes': '/theme',
-  '/exec': '/tool', '/call': '/tool',
-  '/toollist': '/tools',
-  '/metrics': '/stats', '/catalog': '/stats',
-  '/llm': '/model', '/engine': '/model',
-  '/health': '/ping',
-  '/settings': '/config', '/conf': '/config',
-  '/persona': '/prompt', '/sysprompt': '/prompt',
-  '/ver': '/version', '/v': '/version',
-  '/sys': '/system', '/os': '/system',
-  '/info': '/about',
-  '/sponsor': '/ads', '/ad': '/ads',
-  '/cls': '/clear', '/reset': '/clear',
-  '/export': '/save',
-  '/r': '/retry',
-};
-
-export async function routeCommand(rawInput, ctx) {
-  const trimmed = rawInput.trim();
-  if (!trimmed.startsWith('/')) return 'UNKNOWN';
-
-  const parts = trimmed.split(/\s+/);
-  let rawCmd = parts[0].toLowerCase();
-  const sub = parts[1] || '';
-  const extra = parts.slice(2).join(' ');
-
-  if (ALIASES[rawCmd]) rawCmd = ALIASES[rawCmd];
-
-  const handler = handlers[rawCmd];
-  if (!handler) {
-    const suggestion = findClosestCommand(rawCmd);
-    console.log(`\n  ${C.amber}Unknown command: "${rawCmd}"${C.reset}`);
-    if (suggestion) {
-      console.log(`  ${C.dim}Did you mean ${C.bold}${C.cyberCyan}${suggestion}${C.reset}${C.dim}?${C.reset}\n`);
-    } else {
-      console.log(`  ${C.dim}Type ${C.emerald}/help${C.reset}${C.dim} for available commands.${C.reset}\n`);
-    }
-    return 'UNKNOWN';
-  }
-
-  return await handler({ ...ctx, sub, extra, parts });
-}
+import { toolsSchema, executeTool } from './tools.js';
+import { audioPlayer } from './audioPlayer.js';
+import { ensureYouTubeCookies, resetCookieCheck, getCookieStatus } from './youtubeAuth.js';
+import { AgentMemory } from './memory.js';
+import { C, UI_ICONS, printSolidPanel, randomFanName, createProgressRunner, wrapText, getFullWidth, getWelcomeHeroLines } from './ui.js';
+import { COMMAND_NAMES } from './commandRegistry.js';
+import { THEMES, THEME_NAMES, ansiBackground, ansiForeground, getThemeName, setTheme } from './theme.js';
+import { getGpuMetrics, formatProgressBar } from './gpuMetrics.js';
+
+function levenshteinDistance(a, b) {
+  const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i++) matrix[i][0] = i;
+  for (let j = 0; j <= b.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return matrix[a.length][b.length];
+}
+
+const VALID_COMMANDS = [...COMMAND_NAMES, '/export'];
+
+export function findClosestCommand(cmd) {
+  let closest = null;
+  let minDistance = Infinity;
+  for (const vc of VALID_COMMANDS) {
+    const dist = levenshteinDistance(cmd.toLowerCase(), vc);
+    if (dist < minDistance) {
+      minDistance = dist;
+      closest = vc;
+    }
+  }
+  return minDistance <= 3 ? closest : null;
+}
+
+export function fuzzyMatchTools(query) {
+  if (!query) return toolsSchema.map(t => ({ tool: t, score: 10 }));
+  const q = query.toLowerCase();
+  const qWords = q.split(/\s+/).filter(Boolean);
+
+  const scored = toolsSchema.map(t => {
+    const name = t.function.name.toLowerCase();
+    const desc = (t.function.description || '').toLowerCase();
+    let score = 0;
+
+    if (name === q) score = 200;
+    else if (name.startsWith(q)) score = 150;
+    else if (name.includes(q)) score = 100;
+    else if (qWords.every(w => name.includes(w))) score = 80;
+    else if (qWords.some(w => name.includes(w))) score = 65;
+    else if (qWords.every(w => desc.includes(w))) score = 50;
+    else if (qWords.some(w => desc.includes(w))) score = 40;
+    else {
+      const dist = levenshteinDistance(q, name);
+      const threshold = Math.floor(Math.min(q.length, name.length) * 0.4);
+      if (dist <= threshold && dist <= 6) score = 30 - dist * 3;
+      if (score === 0) {
+        for (const word of name.split('_')) {
+          const wd = levenshteinDistance(q, word);
+          const wThreshold = Math.floor(Math.min(q.length, word.length) * 0.4);
+          if (wd <= wThreshold && wd <= 4) {
+            score = Math.max(score, 35 - wd * 5);
+          }
+        }
+      }
+    }
+
+    return { tool: t, score };
+  });
+
+  return scored
+    .filter(s => s.score > 0)
+    .sort((a, b) => b.score - a.score);
+}
+
+export const handlers = {
+  '/exit': async (ctx) => {
+    try { await ctx.agent.endSession(); } catch {}
+    console.log(`\n  ${C.sakura}Session archived. Thank you for supporting Ju Jingyi. Goodbye. (鞠躬 ~ 谢谢!)${C.reset}\n`);
+    return 'EXIT';
+  },
+
+  '/help': async (ctx) => {
+    const sub = ctx.sub || ctx.extra || '';
+    if (typeof ctx.printHelp === 'function') {
+      ctx.printHelp(sub);
+    }
+    return 'HANDLED';
+  },
+
+  '/details': async (ctx) => {
+    ctx.printQueryDetails(ctx.sub || '');
+    return 'HANDLED';
+  },
+
+  '/subagent': async (ctx) => {
+    const rawSub = (ctx.sub || '').toLowerCase();
+    const latest = ctx.agent._lastSubagentResult || null;
+
+    if (rawSub === 'status' || rawSub === 'last' || rawSub === 'tools') {
+      if (!latest) {
+        printSolidPanel({
+          title: 'Subagent Status',
+          lines: [`${C.dim}No subagent has been executed yet. Run /subagent <task> to start one.${C.reset}`]
+        });
+        return 'HANDLED';
+      }
+
+      const lines = [
+        `${C.bold}${C.cyberCyan}Task:${C.reset} ${latest.task}`,
+        `${C.bold}${C.slate}Iterations:${C.reset} ${latest.iterations || 1} • ${C.bold}Tools Used:${C.reset} ${latest.toolCalls?.length || 0}`,
+        ''
+      ];
+
+      if (latest.toolCalls && latest.toolCalls.length > 0) {
+        lines.push(`${C.bold}${C.lavender}Tool Execution History:${C.reset}`);
+        for (const [idx, tc] of latest.toolCalls.entries()) {
+          const statusBadge = tc.status === 'error' ? `${C.red}[ERROR]` : `${C.emerald}[OK]`;
+          lines.push(`  ${C.gold}[${idx + 1}]${C.reset} ${C.bold}${tc.name}${C.reset} ${statusBadge}`);
+          if (tc.args && Object.keys(tc.args).length > 0) {
+            lines.push(`     ${C.dim}args: ${JSON.stringify(tc.args)}${C.reset}`);
+          }
+        }
+        lines.push('');
+      }
+
+      lines.push(`${C.bold}${C.roseGlow}Findings Report:${C.reset}`);
+      for (const fLine of String(latest.answer || 'No report generated.').split('\n')) {
+        lines.push(`  ${fLine}`);
+      }
+
+      printSolidPanel({
+        title: `Subagent Details • ${latest.toolCalls?.length || 0} Tools`,
+        lines
+      });
+      return 'HANDLED';
+    }
+
+    const task = [ctx.sub, ctx.extra].filter(Boolean).join(' ').trim();
+    if (!task) {
+      printSolidPanel({
+        title: 'Subagent Command Help',
+        lines: [
+          `${C.bold}${C.white}Usage:${C.reset} ${C.cyberCyan}/subagent <task>${C.reset}`,
+          `${C.dim}Examples:${C.reset}`,
+          `  • ${C.amber}/subagent สรุปผลงานซีรีส์ปี 2026 พร้อมตรวจสอบค่ายเพลง${C.reset}`,
+          `  • ${C.amber}/subagent ค้นหาประวัติรางวัล Golden Eagle ของจวีจิ้งอี${C.reset}`,
+          `  • ${C.amber}/subagent status${C.reset}  ${C.dim}(ดูรายงานและ Tool calls ของ Subagent ล่าสุด)${C.reset}`,
+        ]
+      });
+      return 'HANDLED';
+    }
+
+    if (ctx.catalogOnlyMode) {
+      console.log(`\n  ${C.amber}Subagents require a loaded LM Studio chat model. Use /model reconnect after starting LM Studio.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    printSolidPanel({
+      title: 'Subagent Spawned • Autonomous Worker',
+      lines: [
+        `${C.bold}${C.cyberCyan}Objective:${C.reset} ${task}`,
+        `${C.dim}Mode: Bounded Iterative Search (Catalog + Web) | Capabilities: 14 tools${C.reset}`
+      ],
+      bg: '\x1b[48;2;32;36;48m'
+    });
+
+    const startTime = Date.now();
+    try {
+      const result = await ctx.agent.runSubagent(task, {
+        onProgress: event => {
+          if (event.type === 'iteration') {
+            console.log(`  ${C.dim}[ITERATION ${event.iteration}/${event.maxIterations}]...${C.reset}`);
+          } else if (event.type === 'tool') {
+            console.log(`  ${C.cyberCyan}▸ [TOOL]${C.reset} Executing ${C.bold}${event.name}${C.reset}...`);
+          }
+        },
+      });
+
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+      ctx.agent._lastSubagentResult = result;
+
+      const lines = [
+        `${C.bold}${C.emerald}[DONE] Subagent completed in ${elapsed}s with ${result.toolCalls.length} tool calls.${C.reset}`,
+        ''
+      ];
+
+      if (result.toolCalls.length > 0) {
+        lines.push(`${C.bold}${C.lavender}Tools Invoked:${C.reset}`);
+        for (const [i, tc] of result.toolCalls.entries()) {
+          lines.push(`  ${C.gold}[${i + 1}]${C.reset} ${C.cyberCyan}${tc.name}${C.reset} ${C.dim}(${JSON.stringify(tc.args || {})})${C.reset}`);
+        }
+        lines.push('');
+      }
+
+      lines.push(`${C.bold}${C.roseGlow}Synthesized Evidence:${C.reset}`);
+      for (const line of String(result.answer || 'No findings returned.').split('\n')) {
+        lines.push(`  ${line}`);
+      }
+
+      lines.push('');
+      lines.push(`${C.dim}Tip: Type /subagent status or press F2 (/details) to inspect tool parameters and results.${C.reset}`);
+
+      printSolidPanel({
+        title: `Subagent Report • ${result.toolCalls.length} tool calls • ${elapsed}s`,
+        lines,
+      });
+    } catch (error) {
+      console.log(`\n  ${C.red}[SUBAGENT ERROR] ${error.message}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/research': async (ctx) => {
+    const action = (ctx.sub || '').toLowerCase();
+    const latest = ctx.agent.getResearchStatus().lastResult;
+
+    if (action === 'status' || action === 'workers') {
+      const status = ctx.agent.getResearchStatus();
+      const lines = status.state === 'running'
+        ? [
+            `${C.bold}${C.cyberCyan}Question:${C.reset} ${status.question}`,
+            `${C.bold}${C.lavender}Active Multi-Workers (3 parallel subagents):${C.reset}`,
+            ...status.workers.map((worker, i) => `  ${C.gold}[Worker ${i + 1}]${C.reset} ${C.bold}${worker.label}${C.reset}: ${worker.state === 'running' ? C.amber + 'RUNNING' : C.emerald + 'COMPLETE'}${C.reset} (${worker.toolCalls} tool calls)`),
+          ]
+        : [
+            `${C.dim}No research job is currently running.${C.reset}`,
+            ...(latest ? [`${C.bold}Latest Research ID:${C.reset} ${latest.id}`, `${C.dim}Run /research last to view the full report.${C.reset}`] : [])
+          ];
+      printSolidPanel({ title: `Research Status • ${status.state.toUpperCase()}`, lines });
+      return 'HANDLED';
+    }
+
+    if (action === 'cancel') {
+      console.log(ctx.agent.cancelResearch()
+        ? `\n  ${C.emerald}[OK] Research cancellation requested.${C.reset}\n`
+        : `\n  ${C.amber}No research job is running.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    if (action === 'last') {
+      const lines = latest
+        ? [
+            `${C.bold}${C.cyberCyan}Research ID:${C.reset} ${latest.id}`,
+            `${C.bold}${C.slate}Sources Found:${C.reset} ${latest.sources?.length || 0}`,
+            '',
+            `${C.bold}${C.roseGlow}Synthesized Answer:${C.reset}`,
+            ...String(latest.answer).split('\n').map(l => `  ${l}`),
+            '',
+            `${C.bold}${C.lavender}Sources Cited:${C.reset}`,
+            ...(latest.sources?.length ? latest.sources.map((s, i) => `  [${i + 1}] ${s}`) : [`  ${C.dim}None recorded.${C.reset}`])
+          ]
+        : [`${C.dim}No completed research yet. Run /research <question> to start.${C.reset}`];
+
+      printSolidPanel({
+        title: latest ? `Research Findings • ${latest.id}` : 'Research',
+        lines,
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'sources') {
+      printSolidPanel({
+        title: 'Research Sources',
+        lines: latest?.sources?.length ? latest.sources.map((url, index) => `${C.gold}[${index + 1}]${C.reset} ${C.cyberCyan}${url}${C.reset}`) : [`${C.dim}No research sources recorded.${C.reset}`],
+      });
+      return 'HANDLED';
+    }
+
+    const question = [ctx.sub, ctx.extra].filter(Boolean).join(' ').trim();
+    if (!question) {
+      printSolidPanel({
+        title: 'Deep Research Command Help',
+        lines: [
+          `${C.bold}${C.white}Usage:${C.reset} ${C.cyberCyan}/research <question>${C.reset}`,
+          `${C.dim}Subcommands:${C.reset}`,
+          `  • ${C.amber}/research status${C.reset}   ${C.dim}(ดูสถานะ Worker ทั้ง 3 ตัว)${C.reset}`,
+          `  • ${C.amber}/research last${C.reset}     ${C.dim}(ดูรายงานวิจัยล่าสุด)${C.reset}`,
+          `  • ${C.amber}/research sources${C.reset}  ${C.dim}(ดูรายการแหล่งอ้างอิง URL ทั้งหมด)${C.reset}`,
+          `  • ${C.amber}/research cancel${C.reset}   ${C.dim}(ยกเลิกงานวิจัยที่กำลังทำ)${C.reset}`,
+        ]
+      });
+      return 'HANDLED';
+    }
+
+    if (ctx.catalogOnlyMode) {
+      console.log(`\n  ${C.amber}Coordinated research requires a loaded chat model. Local catalog queries remain available.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    printSolidPanel({
+      title: 'Deep Research Initiated • 3 Coordinated Workers',
+      lines: [
+        `${C.bold}${C.cyberCyan}Research Question:${C.reset} ${question}`,
+        `  ${C.gold}[Worker 1]${C.reset} Local Ju Jingyi Catalog & Work Detail Explorer`,
+        `  ${C.gold}[Worker 2]${C.reset} Web News, Endorsements & Discography Explorer`,
+        `  ${C.gold}[Worker 3]${C.reset} Fact Verification & Contradiction Resolver`,
+      ],
+      bg: '\x1b[48;2;32;36;48m'
+    });
+
+    const startTime = Date.now();
+    try {
+      const result = await ctx.agent.runResearch(question, {
+        onProgress: event => {
+          if (event.type === 'worker-start') console.log(`  ${C.dim}▸ Worker started: ${event.label}${C.reset}`);
+          if (event.type === 'worker-complete') console.log(`  ${C.emerald}[OK] Worker finished: ${event.label}${C.reset}`);
+        },
+      });
+
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+      const lines = [
+        `${C.bold}${C.emerald}[DONE] Research synthesis completed in ${elapsed}s across 3 workers.${C.reset}`,
+        '',
+        `${C.bold}${C.roseGlow}Comprehensive Findings:${C.reset}`,
+        ...String(result.answer).split('\n').map(l => `  ${l}`),
+        '',
+        `${C.bold}${C.lavender}Validated Sources (${result.sources.length}):${C.reset}`,
+        ...(result.sources.length > 0 ? result.sources.map((s, i) => `  [${i + 1}] ${C.cyberCyan}${s}${C.reset}`) : [`  ${C.dim}Catalog sources${C.reset}`]),
+      ];
+
+      printSolidPanel({
+        title: `Deep Research Report • ${result.sources.length} sources • ${elapsed}s`,
+        lines
+      });
+    } catch (error) {
+      console.log(`\n  ${C.red}[RESEARCH ERROR] ${error.message}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/verify': async (ctx) => {
+    const claim = [ctx.sub, ctx.extra].filter(Boolean).join(' ').trim();
+    if (!claim) {
+      printSolidPanel({
+        title: 'Claim Verification Help',
+        lines: [
+          `${C.bold}${C.white}Usage:${C.reset} ${C.cyberCyan}/verify <claim about Ju Jingyi>${C.reset}`,
+          `${C.dim}Checks facts across Catalog, Official Media, and Contradiction Resolver.${C.reset}`,
+          `Example: ${C.amber}/verify จวีจิ้งอีเป็น Global Ambassador ของ Maybelline ในปี 2026${C.reset}`
+        ]
+      });
+      return 'HANDLED';
+    }
+
+    if (ctx.catalogOnlyMode) {
+      console.log(`\n  ${C.amber}Verification requires a loaded chat model. Use /model reconnect after starting LM Studio.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    printSolidPanel({
+      title: 'Fact-Check & Verification Mode',
+      lines: [
+        `${C.bold}${C.cyberCyan}Claim:${C.reset} "${claim}"`,
+        `  ${C.dim}1. Catalog Verification -> 2. Web Corroboration -> 3. Contradiction Analysis${C.reset}`
+      ],
+      bg: '\x1b[48;2;36;40;52m'
+    });
+
+    const startTime = Date.now();
+    try {
+      const result = await ctx.agent.runResearch(claim, { mode: 'verify' });
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+      const answerStr = String(result.answer || '');
+
+      let verdictBadge = `${C.amber}[UNVERIFIED / AMBIGUOUS]`;
+      if (/VERIFIED|จริง|ถูกต้อง|ยืนยันแล้ว|CONFIRMED/i.test(answerStr) && !/UNVERIFIED|FALSE|เท็จ|ไม่จริง/i.test(answerStr.slice(0, 80))) {
+        verdictBadge = `${C.emerald}${C.bold}[VERIFIED / FACTUAL]${C.reset}`;
+      } else if (/FALSE|เท็จ|ไม่จริง|ข่าวลือ|CONTRADICTED|REFUTED/i.test(answerStr)) {
+        verdictBadge = `${C.red}${C.bold}[FALSE / REFUTED]${C.reset}`;
+      } else {
+        verdictBadge = `${C.amber}${C.bold}[UNVERIFIED / INSUFFICIENT EVIDENCE]${C.reset}`;
+      }
+
+      const lines = [
+        `${C.bold}Verdict:${C.reset} ${verdictBadge}  ${C.dim}(Checked in ${elapsed}s)${C.reset}`,
+        '',
+        `${C.bold}${C.roseGlow}Verification Breakdown:${C.reset}`,
+        ...answerStr.split('\n').map(l => `  ${l}`),
+        '',
+        `${C.bold}${C.lavender}Evidence & Sources (${result.sources.length}):${C.reset}`,
+        ...(result.sources.length > 0 ? result.sources.map((s, i) => `  [${i + 1}] ${C.cyberCyan}${s}${C.reset}`) : [`  ${C.dim}Catalog data verification${C.reset}`])
+      ];
+
+      printSolidPanel({
+        title: `Verification Verdict • ${result.sources.length} sources`,
+        lines
+      });
+    } catch (error) {
+      console.log(`\n  ${C.red}[VERIFY ERROR] ${error.message}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/sources': async (ctx) => {
+    const latest = ctx.agent.getResearchStatus().lastResult;
+    printSolidPanel({
+      title: 'Latest Research Sources',
+      lines: latest?.sources?.length ? latest.sources.map((url, index) => `${C.gold}[${index + 1}]${C.reset} ${C.cyberCyan}${url}${C.reset}`) : [`${C.dim}No research sources recorded.${C.reset}`],
+    });
+    return 'HANDLED';
+  },
+
+  '/skill': async (ctx) => {
+    const action = (ctx.sub || 'list').toLowerCase();
+    const memory = ctx.agent.memory;
+
+    if (action === 'learn' || action === 'add') {
+      if (!ctx.extra) {
+        printSolidPanel({
+          title: 'Skill Learn Help',
+          lines: [
+            `${C.bold}${C.white}Usage:${C.reset} ${C.cyberCyan}/skill learn <instruction on how Kiku should answer>${C.reset}`,
+            `Example: ${C.amber}/skill learn ตอบสั้นกระชับและลงท้ายด้วย '蜜橘' เสมอ${C.reset}`
+          ]
+        });
+      } else {
+        const skill = memory.addUserSkill(ctx.extra);
+        printSolidPanel({
+          title: 'Learned Response Skill Added',
+          lines: [
+            `${C.emerald}[OK] Skill successfully saved to long-term agent memory!${C.reset}`,
+            `${C.bold}ID:${C.reset} ${skill.id}`,
+            `${C.bold}Rule:${C.reset} ${skill.instruction}`,
+            `${C.dim}Kiku will now apply this persona rule across all future answers.${C.reset}`
+          ]
+        });
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'del' || action === 'remove') {
+      const deleted = memory.removeUserSkill(ctx.extra);
+      printSolidPanel({
+        title: 'Remove Skill',
+        lines: [
+          deleted
+            ? `${C.emerald}[OK] Response skill ${ctx.extra} removed.${C.reset}`
+            : `${C.amber}Skill not found. Use /skill list to see active skill IDs.${C.reset}`
+        ]
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'clear') {
+      memory.clearUserSkills();
+      printSolidPanel({
+        title: 'Skills Cleared',
+        lines: [`${C.emerald}[OK] All learned response skills have been cleared.${C.reset}`]
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'on' || action === 'off') {
+      const isEnabled = action === 'on';
+      memory.setPreference('skillsEnabled', isEnabled);
+      printSolidPanel({
+        title: 'Skill Toggle',
+        lines: [`${C.emerald}[OK] Learned response skills are now ${isEnabled ? `${C.bold}ENABLED (ON)` : `${C.dim}DISABLED (OFF)`}${C.reset}.`]
+      });
+      return 'HANDLED';
+    }
+
+    const skills = memory.preferences.userSkills || [];
+    const isEnabled = memory.preferences.skillsEnabled !== false;
+    const lines = [
+      `${C.bold}Status:${C.reset} ${isEnabled ? `${C.emerald}ACTIVE (ON)${C.reset}` : `${C.amber}INACTIVE (OFF)${C.reset}`} • ${skills.length} skills learned`,
+      ''
+    ];
+
+    if (skills.length > 0) {
+      lines.push(`${C.bold}${C.lavender}Learned Rules:${C.reset}`);
+      for (const s of skills) {
+        lines.push(`  ${C.gold}[${s.id}]${C.reset} ${C.white}${s.instruction}${C.reset}`);
+      }
+    } else {
+      lines.push(`${C.dim}No custom skills learned yet.${C.reset}`);
+      lines.push(`Teach Kiku rules with: ${C.cyberCyan}/skill learn <instruction>${C.reset}`);
+    }
+
+    printSolidPanel({
+      title: `Learned Response Skills • ${isEnabled ? 'ON' : 'OFF'}`,
+      lines
+    });
+    return 'HANDLED';
+  },
+
+  '/history': async (ctx) => {
+    const { agent, sub, extra } = ctx;
+    if (sub === 'clear') {
+      agent.session.messages = [];
+      agent.conversationHistory = [agent.conversationHistory[0]];
+      await agent.session.clearDisk().catch(() => {});
+      console.log(`\n  ${C.emerald}[OK] Chat history cleared.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    if (sub === 'search' && extra) {
+      const q = extra.toLowerCase().trim();
+      const matches = [];
+      for (const msg of agent.session.messages) {
+        const textPart = msg.parts.find(p => p.type === 'text');
+        if (textPart && textPart.content.toLowerCase().includes(q)) {
+          matches.push({ role: msg.role, text: textPart.content, createdAt: msg.createdAt });
+        }
+      }
+      printSolidPanel({
+        title: `History Search Results for "${extra}" (${matches.length} matches)`,
+        lines: matches.length === 0
+          ? [`${C.dim}No messages found matching "${extra}".${C.reset}`]
+          : matches.map(m => {
+            const prefix = m.role === 'user' ? `${C.roseGlow}User` : `${C.cyberCyan}Kiku`;
+            return `${prefix}:${C.reset} ${C.white}${m.text.slice(0, 80)}${m.text.length > 80 ? '...' : ''}${C.reset}`;
+          }),
+        headerBg: '\x1b[48;2;48;54;70m',
+        bg: '\x1b[48;2;36;40;52m'
+      });
+      return 'HANDLED';
+    }
+
+    let count = 10;
+    if (sub && !isNaN(parseInt(sub))) count = Math.min(parseInt(sub), 50);
+
+    const recentMessages = agent.session.messages.slice(-count);
+    if (recentMessages.length === 0) {
+      console.log(`\n  ${C.dim}No conversation history yet.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    const lines = [];
+    for (const msg of recentMessages) {
+      if (msg.role === 'user') {
+        const textPart = msg.parts.find(p => p.type === 'text');
+        if (textPart) {
+          lines.push(`${C.roseGlow}${C.bold}${randomFanName()}:${C.reset} ${C.white}${textPart.content}${C.reset}`);
+        }
+      } else if (msg.role === 'assistant') {
+        const textPart = msg.parts.find(p => p.type === 'text');
+        if (textPart) {
+          const preview = textPart.content.length > 120 ? textPart.content.slice(0, 120) + '…' : textPart.content;
+          lines.push(`${C.cyberCyan}${C.bold}Kiku:${C.reset} ${C.white}${preview.replace(/\n/g, ' ')}${C.reset}`);
+        }
+      }
+    }
+    printSolidPanel({
+      title: `Conversation History (last ${recentMessages.length} messages)`,
+      lines,
+      headerBg: '\x1b[48;2;48;54;70m',
+      bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/session': async (ctx) => {
+    const { agent, sub } = ctx;
+    const sess = agent.session;
+    const action = (sub || 'info').toLowerCase();
+
+    if (action === 'info' || !action) {
+      const msgCount = sess.messages.length;
+      const userMsgs = sess.messages.filter(m => m.role === 'user').length;
+      const assistantMsgs = sess.messages.filter(m => m.role === 'assistant').length;
+      const toolCalls = sess.stats.totalToolCalls || 0;
+      const totalDur = ((sess.stats.totalDurationMs || 0) / 1000).toFixed(1);
+      const createdAt = sess.createdAt ? sess.createdAt.toLocaleString() : 'unknown';
+
+      printSolidPanel({
+        title: `Active Session Details`,
+        lines: [
+          `${C.gold}Session ID:${C.reset}      ${C.white}${sess.id}${C.reset}`,
+          `${C.gold}Created At:${C.reset}      ${C.white}${createdAt}${C.reset}`,
+          `${C.gold}Total Messages:${C.reset}  ${C.cyberCyan}${msgCount}${C.reset} total ${C.dim}(${userMsgs} user, ${assistantMsgs} assistant)${C.reset}`,
+          `${C.gold}Total Queries:${C.reset}   ${C.cyberCyan}${sess.stats.totalQueries}${C.reset}`,
+          `${C.gold}Tool Calls:${C.reset}      ${C.cyberCyan}${toolCalls}${C.reset}`,
+          `${C.gold}Total Duration:${C.reset}  ${C.cyberCyan}${totalDur}s${C.reset}`,
+          `${C.gold}Thinking Mode:${C.reset}   ${C.bold}${C.gold}${sess.thinkingMode.toUpperCase()}${C.reset}`
+        ],
+        headerBg: '\x1b[48;2;48;54;70m',
+        bg: '\x1b[48;2;36;40;52m'
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'list') {
+      const sessions = agent.memory.getArchivedSessions(15);
+      printSolidPanel({
+        title: `Archived Sessions (Total: ${sessions.length})`,
+        lines: sessions.length === 0
+          ? [`${C.dim}No archived sessions found.${C.reset}`]
+          : sessions.map(s => {
+            const date = new Date(s.createdAt).toLocaleString();
+            const dur = ((s.stats?.totalDurationMs || 0) / 1000).toFixed(1);
+            return `${C.gold}${s.id}${C.reset} ${C.dim}(${date})${C.reset} — ${s.messageCount} msgs, ${dur}s`;
+          }),
+        headerBg: '\x1b[48;2;48;54;70m',
+        bg: '\x1b[48;2;36;40;52m'
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'export') {
+      const exported = await agent.session.exportToMarkdown();
+      console.log(`\n  ${C.emerald}[OK] Session transcript exported.${C.reset}`);
+      console.log(`  ${C.slate}• File:${C.reset} ${C.white}${exported.filePath}${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    if (action === 'clear' || action === 'new' || action === 'reset') {
+      await agent.endSession();
+      console.log(`\n  ${C.emerald}[OK] Previous session archived. Started fresh.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    console.log(`\n  ${C.amber}Unknown session action: "${sub}". Use /session [info|list|export|clear]${C.reset}\n`);
+    return 'HANDLED';
+  },
+
+  '/thinking': async (ctx) => {
+    const { agent, sub } = ctx;
+    const targetMode = (sub || '').toLowerCase();
+    if (targetMode === 'show' || targetMode === 'hide') {
+      agent.session.setThinkingMode(targetMode);
+      console.log(`\n  ${C.emerald}[OK] Thinking mode set to ${C.bold}${targetMode.toUpperCase()}${C.reset}\n`);
+    } else {
+      const current = agent.session.toggleThinkingMode();
+      console.log(`\n  ${C.emerald}[OK] Thinking mode toggled to ${C.bold}${current.toUpperCase()}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/lang': async (ctx) => {
+    const { agent, sub } = ctx;
+    const langArg = (sub || '').toLowerCase();
+    if (langArg === 'th' || langArg === 'zh' || langArg === 'en' || langArg === 'auto') {
+      agent.memory.setPreference('language', langArg === 'auto' ? null : langArg);
+      const langNames = { th: 'Thai', zh: 'Chinese', en: 'English', auto: 'Auto-detect' };
+      console.log(`\n  ${C.emerald}[OK] Language updated to:${C.reset} ${C.bold}${C.white}${langNames[langArg]}${C.reset}\n`);
+    } else {
+      const current = agent.memory.preferences.language || 'auto';
+      printSolidPanel({
+        title: `Language Preference`,
+        lines: [`${C.gold}Current:${C.reset} ${C.bold}${C.white}${current.toUpperCase()}${C.reset}`, `${C.dim}Usage: /lang [th|zh|en|auto]${C.reset}`],
+        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+      });
+    }
+    return 'HANDLED';
+  },
+
+  '/theme': async (ctx) => {
+    const action = (ctx.sub || 'current').toLowerCase();
+    const current = getThemeName();
+
+    if (action === 'list') {
+      printSolidPanel({
+        title: `Themes (${THEME_NAMES.length})`,
+        lines: THEME_NAMES.map(name => {
+          const theme = THEMES[name];
+          const marker = name === current ? '[x]' : '[ ]';
+          const sample = ansiForeground(theme.colors.primary);
+          const preview = `${ansiBackground(theme.colors.panel)}${ansiForeground(theme.colors.text)}${C.bold} Aa ${C.reset}`;
+          return `${marker} ${preview} ${sample}${C.bold}${name.padEnd(12)}${C.reset} ${C.dim}${theme.description}${C.reset}`;
+        }),
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'current') {
+      const theme = THEMES[current];
+      printSolidPanel({
+        title: 'Theme',
+        lines: [
+          `${C.gold}Current:${C.reset} ${C.bold}${C.white}${theme.label} (${current})${C.reset}`,
+          `${C.dim}${theme.description}${C.reset}`,
+          `${C.sakura}Primary${C.reset}  ${C.roseGlow}Accent${C.reset}  ${C.cyberCyan}Info${C.reset}  ${C.emerald}Success${C.reset}  ${C.amber}Warning${C.reset}  ${C.red}Error${C.reset}`,
+          `${C.dim}Usage: /theme list or /theme <name>${C.reset}`,
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    const requested = action === 'reset' ? 'sakura' : action;
+    const theme = setTheme(requested);
+    if (!theme) {
+      console.log(`\n  ${C.amber}Unknown theme: "${action}".${C.reset}`);
+      console.log(`  ${C.dim}Available: ${THEME_NAMES.join(', ')}${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    printSolidPanel({
+      title: 'Theme Updated',
+      lines: [
+        `${C.emerald}[OK] Active theme: ${C.bold}${theme.label} (${requested})${C.reset}`,
+        `${C.dim}${theme.description}${C.reset}`,
+        `${C.sakura}Primary${C.reset}  ${C.roseGlow}Accent${C.reset}  ${C.cyberCyan}Info${C.reset}  ${C.emerald}Success${C.reset}  ${C.amber}Warning${C.reset}  ${C.red}Error${C.reset}`,
+        `${C.dim}Saved for future Kiku Agent sessions.${C.reset}`,
+      ],
+    });
+    return 'HANDLED';
+  },
+
+  '/tool': async (ctx) => {
+    const { sub, extra } = ctx;
+    const toolName = sub;
+    const rawArgs = extra || '';
+
+    if (!toolName) {
+      console.log(`\n  ${C.amber}Usage: /tool <tool_name> [args]${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    const schema = toolsSchema.find(t => t.function.name.toLowerCase() === toolName.toLowerCase());
+    if (!schema) {
+      console.log(`\n  ${C.red}Unknown tool: "${toolName}". Use /tools to view all.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    const actualToolName = schema.function.name;
+
+    if (!rawArgs || !rawArgs.trim()) {
+      const props = schema.function.parameters?.properties || {};
+      const required = schema.function.parameters?.required || [];
+      console.log(`\n  ${C.gold}Tool:${C.reset} ${C.bold}${C.cyberCyan}${actualToolName}${C.reset}`);
+      console.log(`  ${C.gold}Description:${C.reset} ${C.white}${schema.function.description}${C.reset}`);
+      for (const [pName, pMeta] of Object.entries(props)) {
+        const reqStr = required.includes(pName) ? `${C.red}[required]${C.reset}` : `${C.dim}[optional]${C.reset}`;
+        console.log(`    • ${C.bold}${pName}${C.reset} (${pMeta.type || 'any'}) ${reqStr}: ${pMeta.description || ''}`);
+      }
+      console.log(`\n`);
+      return 'HANDLED';
+    }
+
+    let parsedArgs = {};
+    if (rawArgs.startsWith('{') && rawArgs.endsWith('}')) {
+      try { parsedArgs = JSON.parse(rawArgs); } catch { parsedArgs = { query: rawArgs }; }
+    } else {
+      const props = schema.function.parameters?.properties || {};
+      const firstProp = Object.keys(props)[0] || 'query';
+      parsedArgs = { [firstProp]: rawArgs };
+    }
+
+    const runner = createProgressRunner({
+      badge: 'RUN',
+      title: `Executing ${actualToolName}`,
+      step: JSON.stringify(parsedArgs).slice(0, 50),
+      badgeBg: '\x1b[48;2;14;165;233m\x1b[38;2;15;23;42m',
+    });
+    const start = Date.now();
+    try {
+      const result = await executeTool(actualToolName, parsedArgs);
+      const dur = ((Date.now() - start) / 1000).toFixed(2);
+      runner.stop();
+      console.log(`\n  \x1b[48;2;16;185;129m\x1b[38;2;15;23;42m${C.bold} OK ${C.reset} ${C.emerald}Completed in ${dur}s${C.reset}\n`);
+      console.log(JSON.stringify(result, null, 2));
+      console.log('');
+    } catch (err) {
+      runner.fail(err);
+    }
+    return 'HANDLED';
+  },
+
+  '/tools': async (ctx) => {
+    const filter = (ctx.sub || '').toLowerCase().trim();
+    const filtered = filter
+      ? toolsSchema.filter(t => t.function.name.toLowerCase().includes(filter) || t.function.description.toLowerCase().includes(filter))
+      : toolsSchema;
+
+    console.log(`\n  ${C.bold}${C.sakura}Registered Tools (${filtered.length}/${toolsSchema.length})${C.reset}\n`);
+    for (const [idx, t] of filtered.entries()) {
+      const f = t.function;
+      const params = Object.keys(f.parameters?.properties || {}).join(', ');
+      console.log(`  ${C.gold}${String(idx + 1).padStart(2)}. ${C.bold}${C.cyberCyan}${f.name}${C.reset}${C.slate}(${params})${C.reset}`);
+      console.log(`      ${C.dim}${C.roseGlow}${f.description}${C.reset}`);
+    }
+    console.log(`\n`);
+    return 'HANDLED';
+  },
+
+  '/mem': async (ctx) => {
+    const { agent, sub, extra, parts } = ctx;
+    const memAction = (sub || '').toLowerCase();
+
+    if (memAction === 'add') {
+      const factText = (parts || []).slice(2).join(' ').trim();
+      if (!factText) {
+        console.log(`\n  ${C.amber}Usage: /mem add <fact>${C.reset}\n`);
+      } else {
+        const entry = agent.memory.addFact(factText, { source: 'user' });
+        console.log(`\n  ${C.emerald}[OK] Saved:${C.reset} ${C.white}${factText.slice(0, 80)}${C.reset} (ID: ${entry.id})\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (memAction === 'del' || memAction === 'rm') {
+      const factId = (parts || [])[2]?.trim();
+      if (!factId) {
+        console.log(`\n  ${C.amber}Usage: /mem del <fact_id>${C.reset}\n`);
+      } else if (agent.memory.removeFact(factId)) {
+        console.log(`\n  ${C.emerald}[OK] Removed [${factId}]${C.reset}\n`);
+      } else {
+        console.log(`\n  ${C.red}Not found [${factId}]${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (memAction === 'search') {
+      const query = (parts || []).slice(2).join(' ').trim();
+      if (!query) {
+        console.log(`\n  ${C.amber}Usage: /mem search <keyword>${C.reset}\n`);
+      } else {
+        const results = agent.memory.searchFacts(query);
+        printSolidPanel({
+          title: `Memory Search: "${query}" (${results.length})`,
+          lines: results.map(fact => `${C.white}${fact.content.slice(0, 65)}${C.reset} ${C.dim}(${fact.id})${C.reset}`),
+        });
+      }
+      return 'HANDLED';
+    }
+
+    if (memAction === 'list') {
+      const grouped = agent.memory.getFactsByCategory();
+      const factLines = [];
+      for (const [cat, facts] of Object.entries(grouped)) {
+        factLines.push(`${C.bold}${C.cyberCyan}${cat.toUpperCase()}${C.reset} (${facts.length})`);
+        for (const fact of facts.slice(0, 6)) {
+          factLines.push(` • ${C.white}${fact.content.slice(0, 65)}${C.reset}`);
+        }
+      }
+      printSolidPanel({ title: 'Stored Facts', lines: factLines });
+      return 'HANDLED';
+    }
+
+    if (memAction === 'topics') {
+      const topics = agent.memory.getTopTopics(10);
+      printSolidPanel({
+        title: 'Topic Profile',
+        lines: topics.map(t => {
+        const bar = '█'.repeat(Math.min(t.count, 15));
+          return `${C.gold}${t.topic.padEnd(14)}${C.reset} ${C.cyberCyan}${bar}${C.reset} ${C.dim}(${t.count}x)${C.reset}`;
+        }),
+      });
+      return 'HANDLED';
+    }
+
+    if (memAction === 'export') {
+      const exported = await agent.memory.exportToJSON();
+      console.log(`\n  ${C.emerald}[OK] Memory exported.${C.reset} ${C.white}${exported.filePath}${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    if (memAction === 'import') {
+      const filePath = (parts || []).slice(2).join(' ').trim();
+      if (!filePath) {
+        console.log(`\n  ${C.amber}Usage: /mem import <path>${C.reset}\n`);
+      } else {
+        const result = await agent.memory.importFromJSON(filePath);
+        if (result.success) {
+          console.log(`\n  ${C.emerald}[OK] Imported ${result.factsImported} facts.${C.reset}\n`);
+        } else {
+          console.log(`\n  ${C.red}[ERROR] ${result.message}${C.reset}\n`);
+        }
+      }
+      return 'HANDLED';
+    }
+
+    if (memAction === 'clear') {
+      await agent.memory.clearAll();
+      console.log(`\n  ${C.emerald}[OK] Memory cleared.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    const memStatus = agent.memory.getStatus();
+    printSolidPanel({
+      title: 'Memory Status',
+      lines: [`${C.gold}Facts:${C.reset} ${C.cyberCyan}${memStatus.factsCount}${C.reset}  ${C.gold}Sessions:${C.reset} ${C.cyberCyan}${memStatus.sessionsCount}${C.reset}`],
+    });
+    return 'HANDLED';
+  },
+
+  '/play': async (ctx) => {
+    const songName = ctx.extra || '';
+    if (!songName) {
+      console.log(`\n  ${C.amber}Usage: /play <song name>${C.reset}\n`);
+    } else {
+      await audioPlayer.play(songName);
+      console.log(`\n  ${C.emerald}[OK] Playing: ${C.white}${songName}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/stop': async () => { await audioPlayer.stop(); console.log(`\n  ${C.emerald}[OK] Stopped${C.reset}\n`); return 'HANDLED'; },
+  '/pause': async () => { const r = await audioPlayer.pause(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
+  '/resume': async () => { const r = await audioPlayer.resume(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
+  '/next': async () => { const r = await audioPlayer.next(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
+  '/prev': async () => { const r = await audioPlayer.prev(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
+  '/mute': async () => { const r = await audioPlayer.mute(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
+  '/unmute': async () => { const r = await audioPlayer.unmute(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
+
+  '/add': async (ctx) => {
+    const song = ctx.extra || '';
+    if (!song) { console.log(`\n  ${C.amber}Usage: /add <song>${C.reset}\n`); }
+    else { const r = await audioPlayer.addToQueue(song); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); }
+    return 'HANDLED';
+  },
+
+  '/remove': async (ctx) => {
+    const index = parseInt(ctx.sub, 10);
+    if (isNaN(index)) { console.log(`\n  ${C.amber}Usage: /remove <index>${C.reset}\n`); }
+    else { const r = await audioPlayer.removeFromQueue(index); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); }
+    return 'HANDLED';
+  },
+
+  '/clearqueue': async () => { const r = await audioPlayer.clearQueue(); console.log(`\n  ${C.emerald}${r}${C.reset}\n`); return 'HANDLED'; },
+
+  '/search': async (ctx) => {
+    const q = ctx.extra || '';
+    if (!q) { console.log(`\n  ${C.amber}Usage: /search <query>${C.reset}\n`); return 'HANDLED'; }
+    try {
+      const results = await audioPlayer.searchYouTube(q);
+      if (results.length === 0) { console.log(`\n  ${C.amber}No results for "${q}"${C.reset}\n`); }
+      else {
+        printSolidPanel({
+          title: `YouTube: "${q}" (${results.length})`,
+          lines: results.map((r, i) => `${C.gold}${i + 1}.${C.reset} ${C.white}${r.title}${C.reset} ${C.dim}(${r.duration})${C.reset}`),
+          headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+        });
+      }
+    } catch (err) { console.log(`\n  ${C.red}${err.message}${C.reset}\n`); }
+    return 'HANDLED';
+  },
+
+  '/current': async () => {
+    const state = audioPlayer.getFullState();
+    if (!state.isPlaying && !state.isPaused) {
+      console.log(`\n  ${C.slate}No music playing.${C.reset}\n`);
+    } else {
+      printSolidPanel({
+        title: `${UI_ICONS.music} Current Track`,
+        lines: [
+          `${C.gold}Track:${C.reset} ${C.white}${state.currentTrack}${C.reset}`,
+          `${C.gold}Status:${C.reset} ${state.isPaused ? C.amber + 'Paused' : C.emerald + 'Playing'}${C.reset}`,
+          `${C.gold}Queue:${C.reset} ${C.cyberCyan}${state.queueLength} songs${C.reset}`
+        ],
+        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+      });
+    }
+    return 'HANDLED';
+  },
+
+  '/retry': async (ctx) => {
+    if (!ctx.lastQuery) {
+      console.log(`\n  ${C.amber}No previous query.${C.reset}\n`);
+      return 'HANDLED';
+    }
+    return 'RETRY';
+  },
+
+  '/clear': async (ctx) => {
+    try { await ctx.agent.endSession(); } catch {}
+    if (ctx.tuiPrompt) {
+      ctx.tuiPrompt.viewportLines = [...getWelcomeHeroLines()];
+      ctx.tuiPrompt.scrollOffset = 0;
+      ctx.tuiPrompt.addViewportLines(`  ${C.emerald}[OK] Fresh start.${C.reset}\n`);
+      ctx.tuiPrompt.render();
+    } else {
+      console.clear();
+      ctx.printWelcome();
+      console.log(`  ${C.emerald}[OK] Fresh start.${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/save': async (ctx) => {
+    const exported = await ctx.agent.session.exportToMarkdown();
+    console.log(`\n  ${C.emerald}[OK] Exported.${C.reset} ${C.white}${exported.filePath}${C.reset}\n`);
+    return 'HANDLED';
+  },
+
+  '/provider': async (ctx) => {
+    const { CLOUD_PROVIDERS, getProvider, getRecommendedModels } = await import('./config.js');
+    const action = (ctx.sub || 'status').toLowerCase();
+    const parts = ctx.parts || [];
+
+    if (action === 'list') {
+      const active = ctx.client.provider || 'lmstudio';
+      const lines = Object.values(CLOUD_PROVIDERS).map(p => {
+        const marker = p.id === active ? '[x]' : '[ ]';
+        const isSet = Boolean(p.apiKey && p.apiKey !== 'lm-studio') || p.isLocal;
+        const keyBadge = isSet
+          ? (p.isLocal ? `${C.slate}local (free)${C.reset}` : `${C.emerald}ready${C.reset}`)
+          : `${C.amber}no key${C.reset}`;
+        return `${marker} ${C.bold}${C.cyberCyan}${p.id.padEnd(12)}${C.reset} ${C.white}${p.name.padEnd(22)}${C.reset} ${keyBadge.padEnd(20)} ${C.dim}(${p.defaultModel})${C.reset}`;
+      });
+      printSolidPanel({
+        title: `AI Providers (${Object.keys(CLOUD_PROVIDERS).length})`,
+        lines: [
+          ...lines,
+          '',
+          `${C.dim}Switch: /provider use <name> [model] | Models: /provider models <name> | Docs: /provider info <name>${C.reset}`
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'use') {
+      const targetProvider = (parts[2] || ctx.extra || '').toLowerCase().trim();
+      const targetModel = parts.slice(3).join(' ').trim() || null;
+
+      if (!targetProvider) {
+        console.log(`\n  ${C.amber}Usage: /provider use <provider_name> [model_id]${C.reset}`);
+        console.log(`  ${C.dim}Example: /provider use groq llama-3.1-8b-instant${C.reset}\n`);
+        return 'HANDLED';
+      }
+
+      try {
+        const options = targetModel ? { model: targetModel } : {};
+        const info = ctx.client.switchProvider(targetProvider, options);
+        if (ctx.agent?.client) ctx.agent.client.switchProvider(targetProvider, options);
+        if (ctx.modelManager) {
+          ctx.modelManager.client = ctx.client;
+          ctx.modelManager.requestedModel = info.model;
+        }
+        ctx.baseUrl = info.baseUrl;
+
+        console.log(`\n  ${C.emerald}[OK] Switched provider to ${C.bold}${info.providerName}${C.reset} (${info.provider})`);
+        console.log(`  ${C.slate}• Model:${C.reset}     ${C.white}${info.model}${C.reset}`);
+        console.log(`  ${C.slate}• Base URL:${C.reset}  ${C.cyberCyan}${info.baseUrl}${C.reset}`);
+        console.log(`  ${C.slate}• API Key:${C.reset}   ${info.hasApiKey ? `${C.emerald}Configured` : (info.isLocal ? `${C.slate}Local (not required)` : `${C.amber}Unset (${info.envKey || 'API key required'})`)}${C.reset}`);
+        if (!info.hasApiKey && !info.isLocal) {
+          console.log(`  ${C.dim}Tip: Set ${info.envKey} in .env or run /provider setkey <key>${C.reset}`);
+        }
+        console.log('');
+      } catch (err) {
+        console.log(`\n  ${C.red}[PROVIDER ERROR] ${err.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'models' || action === 'model' || action === 'catalog') {
+      const targetProvider = (ctx.extra || ctx.client.provider || 'lmstudio').toLowerCase().trim();
+      const providerDef = getProvider(targetProvider);
+      if (!providerDef) {
+        console.log(`\n  ${C.red}[ERROR] Unknown provider "${targetProvider}". Available: ${Object.keys(CLOUD_PROVIDERS).join(', ')}${C.reset}\n`);
+        return 'HANDLED';
+      }
+
+      const models = getRecommendedModels(targetProvider);
+      const lines = [];
+      lines.push(`${C.gold}Provider:${C.reset} ${C.bold}${C.white}${providerDef.name}${C.reset} (${providerDef.id})`);
+      lines.push(`${C.gold}Pricing:${C.reset}  ${C.slate}${providerDef.pricingSummary}${C.reset}`);
+      lines.push('');
+
+      for (const m of models) {
+        const isCurrent = m.id === ctx.client.model;
+        const marker = isCurrent ? `${C.gold}[x]${C.reset}` : `${C.dim}[ ]${C.reset}`;
+        const tierBadge = m.tier === 'free'
+          ? `${C.slate}[FREE]${C.reset}`
+          : m.tier === 'ultra-cheap' || m.tier === 'lowest-cost'
+            ? `${C.emerald}[ULTRA-CHEAP]${C.reset}`
+            : m.tier === 'reasoning'
+              ? `${C.lavender}[REASONING]${C.reset}`
+              : m.tier === 'flagship'
+                ? `${C.sakura}[FLAGSHIP]${C.reset}`
+                : `${C.cyberCyan}[BALANCED]${C.reset}`;
+        lines.push(`${marker} ${C.bold}${C.white}${m.id}${C.reset} ${tierBadge} ${C.dim}• Cost: ${m.cost} • Context: ${m.context}${C.reset}`);
+        lines.push(`   ${C.slate}${m.description}${C.reset}`);
+      }
+
+      lines.push('');
+      lines.push(`${C.dim}Use model: /provider use ${providerDef.id} <model_id> or /model use <model_id>${C.reset}`);
+
+      printSolidPanel({
+        title: `${providerDef.name} • Recommended Models (${models.length})`,
+        lines,
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'info' || action === 'doc' || action === 'docs') {
+      const targetProvider = (ctx.extra || ctx.client.provider || 'lmstudio').toLowerCase().trim();
+      const p = getProvider(targetProvider);
+      if (!p) {
+        console.log(`\n  ${C.red}[ERROR] Unknown provider "${targetProvider}".${C.reset}\n`);
+        return 'HANDLED';
+      }
+
+      const isSet = Boolean(p.apiKey && p.apiKey !== 'lm-studio') || p.isLocal;
+      printSolidPanel({
+        title: `${p.name} Developer Details`,
+        lines: [
+          `${C.gold}ID:${C.reset}          ${C.white}${p.id}${C.reset}`,
+          `${C.gold}Base URL:${C.reset}    ${C.cyberCyan}${p.baseUrl}${C.reset}`,
+          `${C.gold}Default:${C.reset}     ${C.white}${p.defaultModel}${C.reset}`,
+          `${C.gold}ENV Key:${C.reset}     ${C.white}${p.envKey || 'N/A'}${C.reset} (${isSet ? `${C.emerald}Configured` : `${C.amber}Missing`}${C.reset})`,
+          `${C.gold}Pricing:${C.reset}     ${C.slate}${p.pricingSummary || 'N/A'}${C.reset}`,
+          `${C.gold}Features:${C.reset}    ${C.slate}${(p.features || []).join(', ')}${C.reset}`,
+          `${C.gold}Docs:${C.reset}        ${C.cyberCyan}${p.docUrl || 'N/A'}${C.reset}`,
+          `${C.gold}API Ref:${C.reset}     ${C.cyberCyan}${p.apiRefUrl || 'N/A'}${C.reset}`,
+          '',
+          `${C.dim}Switch: /provider use ${p.id} | Models: /provider models ${p.id}${C.reset}`
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'test' || action === 'ping' || action === 'check') {
+      const targetProvider = (ctx.extra || ctx.client.provider || 'lmstudio').toLowerCase().trim();
+      console.log(`\n  ${C.cyberCyan}[TESTING] Testing connection to ${targetProvider}...${C.reset}`);
+      let testClient = ctx.client;
+      if (targetProvider !== ctx.client.provider) {
+        const { LLMClient } = await import('./llmClient.js');
+        testClient = new LLMClient({ provider: targetProvider });
+      }
+      const check = await testClient.checkConnection();
+      if (check.connected) {
+        console.log(`  ${C.emerald}[OK] Connected to ${check.providerName}!${C.reset}`);
+        console.log(`  ${C.slate}• Latency:${C.reset}     ${C.emerald}${check.latencyMs || 0}ms${C.reset}`);
+        console.log(`  ${C.slate}• Active Model:${C.reset} ${C.white}${check.activeModel || check.model || 'N/A'}${C.reset}`);
+        console.log(`  ${C.slate}• Models Found:${C.reset} ${C.cyberCyan}${check.models?.length || 0}${C.reset}\n`);
+      } else {
+        console.log(`  ${C.red}[FAILED] Connection check failed for ${check.providerName}.${C.reset}`);
+        console.log(`  ${C.amber}• Error:${C.reset} ${check.error}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'setkey' || action === 'key') {
+      const arg1 = parts[2] || '';
+      const arg2 = parts[3] || '';
+      let targetProvider = ctx.client.provider;
+      let newKey = arg1;
+
+      if (arg2 && getProvider(arg1)) {
+        targetProvider = arg1.toLowerCase();
+        newKey = arg2;
+      }
+
+      if (!newKey) {
+        console.log(`\n  ${C.amber}Usage: /provider setkey <api_key> or /provider setkey <provider> <api_key>${C.reset}\n`);
+        return 'HANDLED';
+      }
+
+      if (targetProvider === ctx.client.provider) {
+        ctx.client.setApiKey(newKey);
+        if (ctx.agent?.client) ctx.agent.client.setApiKey(newKey);
+      }
+      const pDef = getProvider(targetProvider);
+      if (pDef) pDef.apiKey = newKey;
+
+      const masked = newKey.length > 8
+        ? `${newKey.slice(0, 4)}...${newKey.slice(-4)}`
+        : '****';
+      console.log(`\n  ${C.emerald}[OK] API key updated for ${targetProvider}${C.reset} (${masked})\n`);
+      return 'HANDLED';
+    }
+
+    const pInfo = ctx.client.getProviderInfo ? ctx.client.getProviderInfo() : {
+      provider: ctx.client.provider || 'lmstudio',
+      providerName: ctx.client.providerName || 'LM Studio',
+      baseUrl: ctx.client.baseUrl,
+      model: ctx.client.model,
+      hasApiKey: false,
+    };
+
+    printSolidPanel({
+      title: `Active AI Provider • ${pInfo.providerName}`,
+      lines: [
+        `${C.gold}Provider:${C.reset}  ${C.bold}${C.white}${pInfo.providerName}${C.reset} (${pInfo.provider})`,
+        `${C.gold}Base URL:${C.reset}  ${C.cyberCyan}${pInfo.baseUrl}${C.reset}`,
+        `${C.gold}Model:${C.reset}     ${C.white}${pInfo.model}${C.reset}`,
+        `${C.gold}API Key:${C.reset}   ${pInfo.hasApiKey ? `${C.emerald}Configured` : (pInfo.isLocal ? `${C.slate}Local (not required)` : `${C.amber}Unset (${pInfo.envKey || 'API key required'})`)}${C.reset}`,
+        `${C.gold}Pricing:${C.reset}   ${C.slate}${pInfo.pricingSummary || 'N/A'}${C.reset}`,
+        `${C.gold}Docs:${C.reset}      ${C.cyberCyan}${pInfo.docUrl || 'N/A'}${C.reset}`,
+        '',
+        `${C.dim}Commands: /provider list | /provider use <name> [model] | /provider models | /provider test${C.reset}`,
+      ],
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/model': async (ctx) => {
+    const action = (ctx.sub || 'status').toLowerCase();
+    const providerName = ctx.client.providerName || 'Model';
+    const { getRecommendedModels } = await import('./config.js');
+
+    if (action === 'reconnect') {
+      if (!ctx.modelManager) {
+        console.log(`\n  ${C.red}[MODEL ERROR] Runtime model manager is unavailable.${C.reset}\n`);
+        return 'HANDLED';
+      }
+      const resolution = await ctx.modelManager.resolve();
+      if (resolution.connected && resolution.selectedModel) {
+        ctx.setCatalogOnlyMode?.(false);
+        console.log(`\n  ${C.emerald}[OK] Connected using ${resolution.selectedModel}.${C.reset}\n`);
+      } else {
+        console.log(`\n  ${C.red}[MODEL ERROR] ${resolution.error || 'No chat model is ready.'}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'recommend' || action === 'rec') {
+      const recs = getRecommendedModels(ctx.client.provider);
+      const lines = recs.map(m => {
+        const isCurrent = m.id === ctx.client.model;
+        const marker = isCurrent ? `${C.gold}[x]${C.reset}` : `${C.dim}[ ]${C.reset}`;
+        return `${marker} ${C.bold}${C.white}${m.id.padEnd(30)}${C.reset} ${C.slate}${m.cost.padEnd(16)}${C.reset} ${C.dim}${m.description}${C.reset}`;
+      });
+      printSolidPanel({
+        title: `${providerName} Recommended Models`,
+        lines: lines.length ? lines : [`${C.dim}No specific recommendations for ${providerName}.${C.reset}`],
+      });
+      return 'HANDLED';
+    }
+
+    const liveCheck = ctx.modelManager
+      ? await ctx.modelManager.inspect()
+      : await ctx.client.checkConnection();
+
+    if (action === 'list') {
+      const serverModels = (liveCheck.models || []).slice(0, 40).map(id => `${id === ctx.client.model ? '[x]' : '[ ]'} ${id}`);
+      const recs = getRecommendedModels(ctx.client.provider);
+      const recLines = recs.length > 0
+        ? [
+            `${C.bold}${C.lavender}Recommended Active Models:${C.reset}`,
+            ...recs.map(m => `  ${m.id === ctx.client.model ? C.gold + '[x]' : C.dim + '[ ]'} ${C.white}${m.id}${C.reset} ${C.dim}(${m.cost} • ${m.tier})${C.reset}`),
+            ''
+          ]
+        : [];
+
+      printSolidPanel({
+        title: `${providerName} Models • ${(liveCheck.models || []).length} available`,
+        lines: [
+          ...recLines,
+          `${C.bold}${C.lavender}Reported by Server:${C.reset}`,
+          ...(serverModels.length ? serverModels.map(s => `  ${s}`) : [`  ${C.dim}No live model list reported by ${providerName}.${C.reset}`]),
+          '',
+          `${C.dim}Select model: /model use <model_id>${C.reset}`
+        ],
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'use') {
+      try {
+        const targetModel = ctx.extra?.trim() || '';
+        if (!targetModel) {
+          console.log(`\n  ${C.amber}Usage: /model use <model_id>${C.reset}\n`);
+          return 'HANDLED';
+        }
+        if (ctx.modelManager) {
+          const selected = ctx.modelManager.select(targetModel, liveCheck.models || []);
+          console.log(`\n  ${C.emerald}[OK] Active model changed to ${selected}.${C.reset}\n`);
+        } else {
+          ctx.client.setModel(targetModel);
+          console.log(`\n  ${C.emerald}[OK] Active model changed to ${targetModel}.${C.reset}\n`);
+        }
+      } catch (error) {
+        console.log(`\n  ${C.red}[MODEL ERROR] ${error.message}${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    printSolidPanel({
+      title: `${providerName} Diagnostics`,
+      lines: [
+        `${C.gold}Provider:${C.reset}  ${C.white}${ctx.client.providerName || 'LM Studio'}${C.reset}`,
+        `${C.gold}Status:${C.reset}    ${liveCheck.connected ? C.emerald + '● Online' : C.red + '○ Offline'}${C.reset}${liveCheck.latencyMs ? ` ${C.dim}(${liveCheck.latencyMs}ms)${C.reset}` : ''}`,
+        `${C.gold}State:${C.reset}     ${C.white}${liveCheck.state || 'ready'}${C.reset}`,
+        `${C.gold}Model:${C.reset}     ${C.bold}${C.white}${ctx.client.model || 'None'}${C.reset}`,
+        `${C.gold}Available:${C.reset} ${C.white}${liveCheck.models?.length || 0} model(s)${C.reset}`,
+        `${C.gold}URL:${C.reset}       ${C.cyberCyan}${ctx.baseUrl}${C.reset}`,
+        '',
+        `${C.dim}Commands: /model list | /model use <id> | /model recommend | /model reconnect${C.reset}`
+      ],
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/mcp': async (ctx) => {
+    const action = (ctx.sub || 'status').toLowerCase();
+    const mcpManager = ctx.agent?.mcpManager;
+
+    if (!mcpManager) {
+      console.log(`\n  ${C.red}[MCP ERROR] MCP Client Manager is unavailable.${C.reset}\n`);
+      return 'HANDLED';
+    }
+
+    if (action === 'tools') {
+      const tools = mcpManager.getToolsSchema();
+      const lines = [];
+      if (tools.length === 0) {
+        lines.push(`${C.dim}No MCP tools registered. Connect to an MCP server using /mcp connect <name> <url>${C.reset}`);
+      } else {
+        for (const [idx, t] of tools.entries()) {
+          const f = t.function;
+          const params = Object.keys(f.parameters?.properties || {}).join(', ');
+          lines.push(`${C.gold}${idx + 1}.${C.reset} ${C.bold}${C.cyberCyan}${f.name}${C.reset}${C.slate}(${params})${C.reset}`);
+          const desc = f.description || 'No description provided';
+          const wrapped = wrapText(desc, Math.max(30, getFullWidth() - 8));
+          for (const dLine of wrapped) {
+            lines.push(`    ${C.dim}${dLine}${C.reset}`);
+          }
+        }
+      }
+      printSolidPanel({
+        title: `Connected MCP Tools (${tools.length})`,
+        lines,
+      });
+      return 'HANDLED';
+    }
+
+    if (action === 'connect') {
+      const parts = (ctx.parts || []).slice(2);
+      const name = parts[0];
+      const targetUrlOrType = parts[1];
+
+      if (!name || !targetUrlOrType) {
+        printSolidPanel({
+          title: 'MCP Connect Usage',
+          lines: [
+            `${C.bold}Connect to Remote HTTP MCP:${C.reset}`,
+            `  ${C.cyberCyan}/mcp connect <name> <url>${C.reset}`,
+            `  ${C.dim}Example: /mcp connect kiku https://jujingyi-kikuuu.vercel.app/mcp${C.reset}`,
+            '',
+            `${C.bold}Connect to Stdio MCP Process:${C.reset}`,
+            `  ${C.cyberCyan}/mcp connect <name> stdio <command> [args...]${C.reset}`,
+            `  ${C.dim}Example: /mcp connect local-kiku stdio node ./server/mcp/stdio.js${C.reset}`,
+          ]
+        });
+        return 'HANDLED';
+      }
+
+      const runner = createProgressRunner({
+        badge: 'RUN',
+        title: `Connecting to MCP Server "${name}"`,
+        step: targetUrlOrType,
+        badgeBg: '\x1b[48;2;14;165;233m\x1b[38;2;15;23;42m',
+      });
+
+      try {
+        let serverConfig;
+        if (targetUrlOrType.toLowerCase() === 'stdio') {
+          const command = parts[2];
+          const args = parts.slice(3);
+          serverConfig = { type: 'stdio', command, args };
+        } else {
+          serverConfig = { type: 'streamable-http', url: targetUrlOrType };
+        }
+
+        const res = await ctx.agent.connectMcp(name, serverConfig);
+
+        runner.done({
+          title: `MCP Server Connected • "${name}"`,
+          lines: [
+            `${C.gold}Server:${C.reset}       ${C.bold}${C.white}${name}${C.reset} ${C.dim}(${serverConfig.type})${C.reset}`,
+            `${C.gold}Target:${C.reset}       ${C.cyberCyan}${targetUrlOrType}${C.reset}`,
+            `${C.gold}Capabilities:${C.reset} ${C.emerald}${res.toolsCount} Tools${C.reset}  ${C.slate}•${C.reset}  ${C.cyberCyan}${res.resourcesCount} Resources${C.reset}  ${C.slate}•${C.reset}  ${C.lavender}${res.promptsCount} Prompts${C.reset}`,
+            `${C.gold}Integration:${C.reset}  ${C.dim}Tools prefixed with ${C.cyberCyan}mcp_${name}_*${C.dim} and auto-routed to agent${C.reset}`,
+            '',
+            `${C.dim}Tip: Run /mcp tools to inspect all registered tools or /mcp status for overview.${C.reset}`
+          ],
+          headerBg: '\x1b[48;2;48;54;70m',
+          bg: '\x1b[48;2;36;40;52m'
+        });
+      } catch (err) {
+        runner.fail(err);
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'disconnect' || action === 'rm' || action === 'del') {
+      const name = (ctx.extra || '').trim();
+      if (!name) {
+        console.log(`\n  ${C.amber}Usage: /mcp disconnect <server_name>${C.reset}\n`);
+        return 'HANDLED';
+      }
+      const success = await ctx.agent.disconnectMcp(name);
+      if (success) {
+        console.log(`\n  ${C.emerald}[OK] Disconnected MCP server "${name}".${C.reset}\n`);
+      } else {
+        console.log(`\n  ${C.amber}MCP server "${name}" not found.${C.reset}\n`);
+      }
+      return 'HANDLED';
+    }
+
+    const status = mcpManager.getStatus();
+    const lines = [
+      `${C.gold}Active Servers:${C.reset} ${C.cyberCyan}${status.activeServersCount}${C.reset}  •  ${C.gold}Total MCP Tools:${C.reset} ${C.cyberCyan}${status.totalToolsCount}${C.reset}`,
+      ''
+    ];
+
+    if (status.servers.length > 0) {
+      lines.push(`${C.bold}${C.lavender}Connected Servers:${C.reset}`);
+      for (const s of status.servers) {
+        lines.push(`  ${C.emerald}●${C.reset} ${C.bold}${C.white}${s.name}${C.reset} ${C.dim}(${s.type})${C.reset} — ${s.toolsCount} tools, ${s.resourcesCount} resources`);
+      }
+    } else {
+      lines.push(`${C.dim}No active MCP servers connected.${C.reset}`);
+      lines.push(`Connect with: ${C.cyberCyan}/mcp connect <name> <url>${C.reset}`);
+    }
+
+    printSolidPanel({
+      title: `Model Context Protocol (MCP) Client`,
+      lines,
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/ping': async (ctx) => {
+    const start = Date.now();
+    const check = await ctx.client.checkConnection();
+    const ms = Date.now() - start;
+    if (check.connected) {
+      console.log(`\n  ${C.emerald}● Connected${C.reset} ${C.dim}(${ms}ms)${C.reset} — ${C.white}${check.activeModel}${C.reset}\n`);
+    } else {
+      console.log(`\n  ${C.red}● Disconnected${C.reset} ${C.dim}(${ms}ms)${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/config': async (ctx) => {
+    const { config } = await import('./config.js');
+    printSolidPanel({
+      title: `Configuration`,
+      lines: [
+        `${C.gold}URL:${C.reset}      ${C.cyberCyan}${ctx.baseUrl}${C.reset}`,
+        `${C.gold}Model:${C.reset}     ${C.white}${ctx.client.model}${C.reset}`,
+        `${C.gold}Theme:${C.reset}     ${C.white}${getThemeName()}${C.reset}`,
+        `${C.gold}Max Iters:${C.reset} ${C.white}${ctx.agent.maxIterations}${C.reset}`,
+        `${C.gold}Window:${C.reset}    ${C.white}${ctx.agent.slidingWindowSize}${C.reset}`,
+        `${C.gold}Tools:${C.reset}     ${C.cyberCyan}${toolsSchema.length}${C.reset}`
+      ],
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/doctor': async (ctx) => {
+    const { runDoctor } = await import('./doctor.js');
+    const report = await runDoctor({ client: ctx.client });
+    printSolidPanel({
+      title: `Kiku Doctor • ${report.ok ? 'READY' : 'ACTION REQUIRED'}`,
+      lines: report.checks.map(check => {
+        const marker = check.ok ? '[OK]' : check.required ? '[FAIL]' : '[OPTIONAL]';
+        return `${marker} ${check.id}: ${check.detail}`;
+      }),
+    });
+    return 'HANDLED';
+  },
+
+  '/version': async () => {
+    printSolidPanel({
+      title: 'Version',
+      lines: [
+        `${C.gold}Version:${C.reset} ${C.white}1.0.3${C.reset}`,
+        `${C.gold}Node:${C.reset}    ${C.white}${process.version}${C.reset}`,
+        `${C.gold}Platform:${C.reset} ${C.white}${process.platform} ${process.arch}${C.reset}`,
+      ],
+    });
+    return 'HANDLED';
+  },
+
+  '/system': async () => {
+    const os = await import('node:os');
+    const mem = process.memoryUsage();
+    const gpuData = await getGpuMetrics().catch(() => ({ available: false }));
+
+    const lines = [
+      `${C.gold}OS:${C.reset}   ${C.white}${os.default.platform()} ${os.default.release()}${C.reset}`,
+      `${C.gold}CPU:${C.reset}  ${C.white}${os.default.cpus().length} cores${C.reset}`,
+      `${C.gold}RAM:${C.reset}  ${C.white}${(os.default.totalmem() / 1073741824).toFixed(1)} GB${C.reset}`,
+      `${C.gold}Heap:${C.reset} ${C.white}${(mem.heapUsed / 1048576).toFixed(1)} MB${C.reset}`,
+    ];
+
+    if (gpuData.available && gpuData.primary) {
+      const g = gpuData.primary;
+      const vramInfo = g.usedGb != null ? ` (${g.usedGb} / ${g.totalGb} GB VRAM • ${g.usedPercent}%)` : ` (${g.totalGb} GB)`;
+      const utilInfo = g.utilizationGpu != null ? ` • ${g.utilizationGpu}% load` : '';
+      const tempInfo = g.temperatureC != null ? ` • ${g.temperatureC}°C` : '';
+      lines.splice(3, 0, `${C.gold}GPU:${C.reset}  ${C.white}${g.name}${C.reset}${C.dim}${vramInfo}${utilInfo}${tempInfo}${C.reset}`);
+    } else {
+      lines.splice(3, 0, `${C.gold}GPU:${C.reset}  ${C.dim}No dedicated hardware acceleration detected${C.reset}`);
+    }
+
+    printSolidPanel({
+      title: 'System & Hardware',
+      lines,
+    });
+    return 'HANDLED';
+  },
+
+  '/gpu': async () => {
+    const gpuData = await getGpuMetrics().catch(() => ({ available: false }));
+
+    if (!gpuData.available || !gpuData.primary) {
+      printSolidPanel({
+        title: 'GPU Hardware Resources',
+        lines: [
+          `${C.amber}No dedicated GPU hardware acceleration metrics available.${C.reset}`,
+          `${C.dim}Standard CPU inference / CPU memory active.${C.reset}`,
+        ]
+      });
+      return 'HANDLED';
+    }
+
+    const lines = [];
+    for (const [idx, g] of gpuData.gpus.entries()) {
+      if (gpuData.gpus.length > 1) {
+        lines.push(`${C.bold}${C.lavender}GPU ${idx + 1}:${C.reset} ${C.bold}${C.white}${g.name}${C.reset}`);
+      } else {
+        lines.push(`${C.gold}Device:${C.reset}      ${C.bold}${C.white}${g.name}${C.reset} ${C.dim}(Driver ${g.driverVersion})${C.reset}`);
+      }
+
+      if (g.usedGb != null && g.totalMb > 0) {
+        const bar = formatProgressBar(g.usedPercent, 18);
+        lines.push(`${C.gold}VRAM Usage:${C.reset}  ${bar} ${C.white}${g.usedGb} / ${g.totalGb} GB${C.reset}`);
+        lines.push(`${C.gold}Free VRAM:${C.reset}   ${C.emerald}${g.freeMb} MB (${g.freeGb} GB free)${C.reset}`);
+      } else {
+        lines.push(`${C.gold}VRAM Total:${C.reset}  ${C.white}${g.totalGb} GB${C.reset}`);
+      }
+
+      if (g.utilizationGpu != null) {
+        lines.push(`${C.gold}GPU Core:${C.reset}    ${C.cyberCyan}${g.utilizationGpu}% Load${C.reset}`);
+      }
+
+      if (g.temperatureC != null) {
+        const tempColor = g.temperatureC >= 80 ? C.roseGlow : g.temperatureC >= 65 ? C.gold : C.emerald;
+        lines.push(`${C.gold}Temperature:${C.reset} ${tempColor}${g.temperatureC}°C${C.reset}`);
+      }
+
+      if (idx < gpuData.gpus.length - 1) lines.push('');
+    }
+
+    printSolidPanel({
+      title: `GPU Hardware Resources • ${gpuData.primary.name}`,
+      lines,
+      headerBg: '\x1b[48;2;48;54;70m',
+      bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/about': async () => {
+    printSolidPanel({
+      title: 'About Kiku AI Agent',
+      lines: [
+        `${C.white}Intelligent assistant for Ju Jingyi (鞠婧祎)${C.reset}`,
+        `${C.gold}Engine:${C.reset} ${C.white}LM Studio + Gemma 4${C.reset}`,
+        `${C.gold}Tools:${C.reset} ${C.white}${toolsSchema.length} registered${C.reset}`,
+        `${C.gold}Languages:${C.reset} ${C.white}TH, ZH, EN (auto)${C.reset}`,
+      ],
+    });
+    return 'HANDLED';
+  },
+
+  '/login': async (ctx) => {
+    console.log(`\n  ${C.cyberCyan}YouTube Login${C.reset}\n`);
+    resetCookieCheck();
+    const result = await ensureYouTubeCookies({ timeout: 180000 });
+    if (result.ok) {
+      console.log(`  ${C.emerald}[OK] Session active (${result.source}).${C.reset}\n`);
+    } else {
+      console.log(`  ${C.red}[ERROR] Not available: ${result.reason}${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/ytstatus': async () => {
+    const status = getCookieStatus();
+    const ensured = status.ensured;
+    printSolidPanel({
+      title: 'YouTube Status',
+      lines: [
+        `${C.gold}Browser:${C.reset} ${status.envBrowser ? C.emerald + status.envBrowser : C.dim + 'n/a'}${C.reset}`,
+        `${C.gold}Cookies:${C.reset} ${status.envCookies ? C.emerald + status.envCookies : C.dim + 'n/a'}${C.reset}`,
+        `${C.gold}Status:${C.reset}  ${ensured ? (ensured.ok ? C.emerald + '[OK]' : C.red + '[ERROR] Failed') : C.dim + 'Unchecked'}${C.reset}`
+      ],
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/queue': async (ctx) => {
+    const { sub } = ctx;
+    if (sub === 'clear') {
+      if (audioPlayer.isPlaying || audioPlayer.queue.length > 0) {
+        console.log(`\n  ${C.emerald}${await audioPlayer.clearQueue()}${C.reset}\n`);
+      } else {
+        ctx.clearQueryQueue();
+        console.log(`\n  ${C.emerald}[OK] Execution queue cleared.${C.reset}\n`);
+      }
+    } else if (audioPlayer.isPlaying || audioPlayer.queue.length > 0) {
+      const queue = audioPlayer.getQueue();
+      printSolidPanel({
+        title: `${UI_ICONS.music} Queue (${queue.length})`,
+        lines: queue.map((item, idx) => `${item.isCurrent ? C.gold + '[PLAYING]' : C.dim + (idx + 1)} ${C.white}${item.title}${C.reset}`),
+        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+      });
+    } else {
+      const qLen = ctx.getQueryQueueLength();
+      console.log(`\n  ${C.slate}Execution queue: ${qLen} items${C.reset}\n`);
+    }
+    return 'HANDLED';
+  },
+
+  '/stats': async () => {
+    const result = await executeTool('get_system_stats', {});
+    const s = result.stats;
+    printSolidPanel({
+      title: `Database Overview`,
+      lines: [
+        `${C.gold}Works:${C.reset}     ${C.cyberCyan}${s.totalWorks}${C.reset}`,
+        `${C.gold}Songs:${C.reset}     ${C.cyberCyan}${s.totalUniqueSongs}${C.reset}`,
+        `${C.gold}Brands:${C.reset}    ${C.cyberCyan}${s.brandEndorsements}${C.reset}`,
+        `${C.gold}Awards:${C.reset}    ${C.cyberCyan}${s.totalAwards}${C.reset}`,
+        `${C.gold}Timeline:${C.reset}  ${C.cyberCyan}${s.timelineMilestones}${C.reset}`
+      ],
+      headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+    });
+    return 'HANDLED';
+  },
+
+  '/prompt': async (ctx) => {
+    const { config } = await import('./config.js');
+    const lines = config.agent.systemPersona.split('\n').slice(0, 20).map(l => `${C.dim}${C.white}${l}${C.reset}`);
+    printSolidPanel({ title: `System Prompt`, lines, headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m' });
+    return 'HANDLED';
+  },
+
+  '/ads': async (ctx) => {
+    ctx.printAd();
+    return 'HANDLED';
+  },
+};
+
+const ALIASES = {
+  '/quit': '/exit', '/q': '/exit',
+  '/?': '/help', '/commands': '/help', '/menu': '/help',
+  '/hist': '/history', '/h': '/history',
+  '/sess': '/session', '/sessions': '/session',
+  '/think': '/thinking', '/th': '/thinking',
+  '/detail': '/details', '/d': '/details',
+  '/language': '/lang',
+  '/themes': '/theme',
+  '/exec': '/tool', '/call': '/tool',
+  '/toollist': '/tools',
+  '/metrics': '/stats', '/catalog': '/stats',
+  '/llm': '/model', '/engine': '/model',
+  '/health': '/ping',
+  '/settings': '/config', '/conf': '/config',
+  '/persona': '/prompt', '/sysprompt': '/prompt',
+  '/ver': '/version', '/v': '/version',
+  '/sys': '/system', '/os': '/system',
+  '/vram': '/gpu', '/gpus': '/gpu',
+  '/info': '/about',
+  '/sponsor': '/ads', '/ad': '/ads',
+  '/cls': '/clear', '/reset': '/clear',
+  '/export': '/save',
+  '/r': '/retry',
+};
+
+export async function routeCommand(rawInput, ctx) {
+  const trimmed = rawInput.trim();
+  if (!trimmed.startsWith('/')) return 'UNKNOWN';
+
+  const parts = trimmed.split(/\s+/);
+  let rawCmd = parts[0].toLowerCase();
+  const sub = parts[1] || '';
+  const extra = parts.slice(2).join(' ');
+
+  if (ALIASES[rawCmd]) rawCmd = ALIASES[rawCmd];
+
+  const handler = handlers[rawCmd];
+  if (!handler) {
+    const suggestion = findClosestCommand(rawCmd);
+    console.log(`\n  ${C.amber}Unknown command: "${rawCmd}"${C.reset}`);
+    if (suggestion) {
+      console.log(`  ${C.dim}Did you mean ${C.bold}${C.cyberCyan}${suggestion}${C.reset}${C.dim}?${C.reset}\n`);
+    } else {
+      console.log(`  ${C.dim}Type ${C.emerald}/help${C.reset}${C.dim} for available commands.${C.reset}\n`);
+    }
+    return 'UNKNOWN';
+  }
+
+  return await handler({ ...ctx, sub, extra, parts });
+}