kiku-agent 1.0.4 → 1.0.6

package/server/agent/commands.js

@@ -2,10 +2,15 @@ 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 {
+  C, UI_ICONS, printSolidPanel, formatTerminalMarkdown, formatMarkdownLines, randomFanName, createProgressRunner, wrapText, getFullWidth, getWelcomeHeroLines, sanitizeTerminalText,
+  formatRichCardLines, printRichCard, printRichStatusCard, formatStatusBadge, formatRichTable
+} from './ui.js';
+import { COMMAND_NAMES, getCommandDetails, findCommandDefinition } from './commandRegistry.js';
 import { THEMES, THEME_NAMES, ansiBackground, ansiForeground, getThemeName, setTheme } from './theme.js';
 import { getGpuMetrics, formatProgressBar } from './gpuMetrics.js';
+import { PACKAGE_NAME, PACKAGE_VERSION } from './version.js';
+import { UpdateError, UpdateManager, UPDATE_CHANNELS } from './updateManager.js';
 
 function levenshteinDistance(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -87,15 +92,50 @@ export const handlers = {
   },
 
   '/help': async (ctx) => {
-    const sub = ctx.sub || ctx.extra || '';
+    const sub = (ctx.sub || ctx.extra || '').trim();
     if (typeof ctx.printHelp === 'function') {
       ctx.printHelp(sub);
+      return 'HANDLED';
+    }
+
+    if (sub) {
+      const rawName = sub.toLowerCase();
+      const cmdName = rawName.startsWith('/') ? rawName : `/${rawName}`;
+      const definition = findCommandDefinition(cmdName);
+      const details = getCommandDetails(cmdName);
+      if (definition || details) {
+        const titleName = definition?.name || cmdName;
+        const summary = details?.summary || definition?.desc || '';
+        const usage = details?.usage || definition?.usage || '';
+        const lines = [
+          `${C.bold}${C.white}${summary}${C.reset}`,
+          '',
+          `${C.bold}${C.lavender}Usage:${C.reset} ${C.cyberCyan}${usage}${C.reset}`,
+        ];
+        if (details?.subcommands?.length) {
+          lines.push('', `${C.bold}${C.roseGlow}Subcommands & Options:${C.reset}`);
+          for (const s of details.subcommands) {
+            lines.push(`  ${C.bold}${C.gold}${s.cmd.padEnd(24)}${C.reset} ${C.white}${s.desc}${C.reset}`);
+            if (s.example) lines.push(`    ${C.dim}↳ Example: ${C.cyberCyan}${s.example}${C.reset}`);
+          }
+        }
+        if (details?.examples?.length) {
+          lines.push('', `${C.bold}${C.emerald}Quick Examples:${C.reset}`);
+          for (const ex of details.examples) {
+            lines.push(`  ${C.cyberCyan}❯ ${ex}${C.reset}`);
+          }
+        }
+        printSolidPanel({ title: `Command Help • ${titleName}`, lines });
+        return 'HANDLED';
+      }
     }
+
+    console.log(`\n  ${C.bold}Type /help <command> for detailed subcommand breakdown.${C.reset}\n`);
     return 'HANDLED';
   },
 
   '/details': async (ctx) => {
-    ctx.printQueryDetails(ctx.sub || '');
+    ctx.printQueryDetails([ctx.sub, ctx.extra].filter(Boolean).join(' '));
     return 'HANDLED';
   },
 
@@ -131,7 +171,7 @@ export const handlers = {
       }
 
       lines.push(`${C.bold}${C.roseGlow}Findings Report:${C.reset}`);
-      for (const fLine of String(latest.answer || 'No report generated.').split('\n')) {
+      for (const fLine of formatMarkdownLines(latest.answer || 'No report generated.')) {
         lines.push(`  ${fLine}`);
       }
 
@@ -172,6 +212,7 @@ export const handlers = {
     });
 
     const startTime = Date.now();
+    ctx.setIsProcessing?.(true, `Subagent: ${task.slice(0, 24)}`);
     try {
       const result = await ctx.agent.runSubagent(task, {
         onProgress: event => {
@@ -200,7 +241,7 @@ export const handlers = {
       }
 
       lines.push(`${C.bold}${C.roseGlow}Synthesized Evidence:${C.reset}`);
-      for (const line of String(result.answer || 'No findings returned.').split('\n')) {
+      for (const line of formatMarkdownLines(result.answer || 'No findings returned.')) {
         lines.push(`  ${line}`);
       }
 
@@ -213,6 +254,8 @@ export const handlers = {
       });
     } catch (error) {
       console.log(`\n  ${C.red}[SUBAGENT ERROR] ${error.message}${C.reset}\n`);
+    } finally {
+      ctx.setIsProcessing?.(false);
     }
     return 'HANDLED';
   },
@@ -306,6 +349,7 @@ export const handlers = {
     });
 
     const startTime = Date.now();
+    ctx.setIsProcessing?.(true, `Research: ${question.slice(0, 24)}`);
     try {
       const result = await ctx.agent.runResearch(question, {
         onProgress: event => {
@@ -319,7 +363,7 @@ export const handlers = {
         `${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}`),
+        ...formatMarkdownLines(result.answer || 'No findings returned.').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}`]),
@@ -331,6 +375,8 @@ export const handlers = {
       });
     } catch (error) {
       console.log(`\n  ${C.red}[RESEARCH ERROR] ${error.message}${C.reset}\n`);
+    } finally {
+      ctx.setIsProcessing?.(false);
     }
     return 'HANDLED';
   },
@@ -364,6 +410,7 @@ export const handlers = {
     });
 
     const startTime = Date.now();
+    ctx.setIsProcessing?.(true, `Verifying: ${claim.slice(0, 24)}`);
     try {
       const result = await ctx.agent.runResearch(claim, { mode: 'verify' });
       const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
@@ -382,7 +429,7 @@ export const handlers = {
         `${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}`),
+        ...formatMarkdownLines(answerStr).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}`])
@@ -394,6 +441,8 @@ export const handlers = {
       });
     } catch (error) {
       console.log(`\n  ${C.red}[VERIFY ERROR] ${error.message}${C.reset}\n`);
+    } finally {
+      ctx.setIsProcessing?.(false);
     }
     return 'HANDLED';
   },
@@ -407,6 +456,138 @@ export const handlers = {
     return 'HANDLED';
   },
 
+  '/suggestion': async (ctx) => {
+    const rawAction = (ctx.sub || 'list').toLowerCase();
+    const extra = (ctx.extra || '').trim();
+
+    if (rawAction === 'run' || rawAction === 'exec' || rawAction === 'start') {
+      const targets = extra || 'all';
+
+      printRichCard({
+        title: 'Multi-Subagent Suggestions Execution',
+        status: 'autostart',
+        lines: [
+          `• Target Questions: ${targets}`,
+          '• Dispatching bounded concurrent ResearchSubagents...',
+        ],
+      });
+
+      const startTime = Date.now();
+      ctx.setIsProcessing?.(true, `Suggestions: ${targets.slice(0, 20)}`);
+      try {
+        const batchResult = await ctx.agent.runSuggestionBatch(targets, {
+          onProgress: event => {
+            if (event.type === 'worker-start') {
+              console.log(`  ${C.cyberCyan}▸ Worker ${event.index} Started:${C.reset} ${C.bold}${event.label}${C.reset} — ${C.dim}${event.question}${C.reset}`);
+            } else if (event.type === 'tool') {
+              console.log(`    ${C.dim}[Worker] Executing tool: ${event.name}...${C.reset}`);
+            } else if (event.type === 'worker-complete') {
+              console.log(`  ${C.emerald}[✓] Worker ${event.index} Finished:${C.reset} ${event.label}`);
+            }
+          },
+        });
+
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+        console.log('');
+        printRichCard({
+          title: `Subagent Batch Complete (${batchResult.successfulCount}/${batchResult.tasksCount} Succeeded)`,
+          status: 'ok',
+          lines: [
+            `Completed ${batchResult.tasksCount} research tasks concurrently in ${elapsed}s.`,
+          ],
+        });
+
+        for (const res of batchResult.results) {
+          if (res.answer) {
+            const answerLines = formatMarkdownLines(res.answer);
+            printSolidPanel({
+              title: `[Worker ${res.index}] ${res.category} • ${res.question}`,
+              lines: [
+                `${C.bold}${C.cyberCyan}Question:${C.reset} ${res.question}`,
+                `${C.dim}Tool calls: ${res.toolCalls?.length || 0} • Iterations: ${res.iterations || 1}${C.reset}`,
+                '',
+                `${C.bold}${C.roseGlow}Findings:${C.reset}`,
+                ...answerLines,
+              ],
+            });
+          } else {
+            printRichCard({
+              title: `Worker ${res.index} Failed: ${res.category}`,
+              status: 'error',
+              lines: [
+                `Question: ${res.question}`,
+                `Error: ${res.error || 'Failed to research'}`,
+              ],
+            });
+          }
+        }
+      } catch (err) {
+        printRichCard({
+          title: 'Batch Subagent Error',
+          status: 'error',
+          lines: [err.message],
+        });
+      } finally {
+        ctx.setIsProcessing?.(false);
+      }
+      return 'HANDLED';
+    }
+
+    if (rawAction === 'auto') {
+      console.log(`\n  ${C.cyberCyan}Generating fresh suggestions and launching concurrent subagents...${C.reset}\n`);
+      ctx.setIsProcessing?.(true, 'Auto Suggestions');
+      try {
+        await ctx.agent.generateSuggestions({ limit: 3 });
+      } finally {
+        ctx.setIsProcessing?.(false);
+      }
+      return handlers['/suggestion']({ ...ctx, sub: 'run', extra: 'all' });
+    }
+
+    const isTopic = rawAction === 'topic';
+    const topicName = isTopic ? extra : (rawAction !== 'list' && rawAction !== 'refresh' ? rawAction : '');
+
+    try {
+      console.log(`\n  ${C.cyberCyan}✦ Fetching AI research suggestions...${C.reset}`);
+      ctx.setIsProcessing?.(true, 'Fetching Suggestions');
+      const suggestions = await ctx.agent.generateSuggestions({
+        topic: topicName,
+        limit: 5,
+      });
+
+      const cardLines = [
+        `${C.dim}Explore exciting Ju Jingyi topics with concurrent subagents:${C.reset}`,
+        '',
+        ...suggestions.flatMap((s) => [
+          `  ${C.bold}${C.gold}[${s.id}]${C.reset} ${C.bold}${C.cyberCyan}[${s.category}]${C.reset} ${C.white}${s.question}${C.reset}`,
+          `      ${C.dim}↳ ${s.description}${C.reset}`,
+        ]),
+        '',
+        `${C.bold}${C.roseGlow}Quick Execution Tips:${C.reset}`,
+        `  • Run one task: ${C.white}/suggestion run 1${C.reset}`,
+        `  • Run parallel batch: ${C.white}/suggestion run 1,2,3${C.reset}`,
+        `  • Run all concurrently: ${C.white}/suggestion run all${C.reset}`,
+        `  • Auto-generate & run: ${C.white}/suggestion auto${C.reset}`,
+        `  • Filter by topic: ${C.white}/suggestion topic drama | music | brand | 2026${C.reset}`,
+      ];
+
+      printRichCard({
+        title: `AI Research Suggestions (${suggestions.length} Questions Generated)`,
+        status: 'info',
+        lines: cardLines,
+      });
+    } catch (err) {
+      printRichCard({
+        title: 'Suggestion Error',
+        status: 'error',
+        lines: [err.message],
+      });
+    } finally {
+      ctx.setIsProcessing?.(false);
+    }
+    return 'HANDLED';
+  },
+
   '/skill': async (ctx) => {
     const action = (ctx.sub || 'list').toLowerCase();
     const memory = ctx.agent.memory;
@@ -976,8 +1157,12 @@ export const handlers = {
   },
 
   '/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`);
+    try {
+      const exported = await ctx.agent.session.exportToMarkdown();
+      console.log(`\n  ${C.emerald}[OK] Exported.${C.reset} ${C.white}${exported.filePath}${C.reset}\n`);
+    } catch (err) {
+      console.log(`\n  ${C.red}[SAVE ERROR] ${err.message || String(err)}${C.reset}\n`);
+    }
     return 'HANDLED';
   },
 
@@ -1288,7 +1473,11 @@ export const handlers = {
     const mcpManager = ctx.agent?.mcpManager;
 
     if (!mcpManager) {
-      console.log(`\n  ${C.red}[MCP ERROR] MCP Client Manager is unavailable.${C.reset}\n`);
+      printRichCard({
+        title: 'MCP Error',
+        status: 'error',
+        lines: ['MCP Client Manager is unavailable.'],
+      });
       return 'HANDLED';
     }
 
@@ -1300,9 +1489,10 @@ export const handlers = {
       } 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 toolName = sanitizeTerminalText(f.name, 128) || 'unknown_tool';
+          const params = Object.keys(f.parameters?.properties || {}).map(param => sanitizeTerminalText(param, 80)).join(', ');
+          lines.push(`${C.gold}${idx + 1}.${C.reset} ${C.bold}${C.cyberCyan}${toolName}${C.reset}${C.slate}(${params})${C.reset}`);
+          const desc = sanitizeTerminalText(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}`);
@@ -1316,7 +1506,7 @@ export const handlers = {
       return 'HANDLED';
     }
 
-    if (action === 'connect') {
+    if (action === 'connect' || action === 'add') {
       const parts = (ctx.parts || []).slice(2);
       const name = parts[0];
       const targetUrlOrType = parts[1];
@@ -1325,11 +1515,11 @@ export const handlers = {
         printSolidPanel({
           title: 'MCP Connect Usage',
           lines: [
-            `${C.bold}Connect to Remote HTTP MCP:${C.reset}`,
+            `${C.bold}Connect & Save 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.bold}Connect & Save 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}`,
           ]
@@ -1357,11 +1547,12 @@ export const handlers = {
         const res = await ctx.agent.connectMcp(name, serverConfig);
 
         runner.done({
-          title: `MCP Server Connected • "${name}"`,
+          title: `MCP Server Connected & Saved • "${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}Persisted:${C.reset}    ${C.emerald}Saved to configuration (auto-reconnects on start)${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}`
@@ -1375,7 +1566,81 @@ export const handlers = {
       return 'HANDLED';
     }
 
-    if (action === 'disconnect' || action === 'rm' || action === 'del') {
+    if (action === 'save') {
+      const target = (ctx.extra || 'global').toLowerCase().trim();
+      const saveRes = await ctx.agent.saveMcpConfig(target);
+      if (saveRes.success) {
+        printRichCard({
+          title: 'MCP Configuration Saved',
+          status: 'ok',
+          lines: [
+            `• Target: ${target === 'workspace' ? 'Workspace (.mcp.json)' : 'Global config (mcp_servers.json)'}`,
+            `• File: ${saveRes.filePath}`,
+            `• Total servers persisted: ${saveRes.count}`,
+          ],
+        });
+      } else {
+        printRichCard({
+          title: 'MCP Save Failed',
+          status: 'error',
+          lines: [saveRes.error || 'Failed to write MCP config'],
+        });
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'reload' || action === 'reconnect') {
+      const target = (ctx.extra || '').trim();
+      printRichCard({
+        title: 'Reloading MCP Configuration',
+        status: 'autostart',
+        lines: [`Reconnecting saved MCP servers...`],
+      });
+      try {
+        await ctx.agent.reconnectMcp(target || 'all');
+        const active = ctx.agent.mcpManager.servers.size;
+        printRichCard({
+          title: 'MCP Servers Reconnected',
+          status: 'ok',
+          lines: [
+            `Active live servers: ${active}`,
+            `Total tools available: ${ctx.agent.mcpManager.getToolsSchema().length}`,
+          ],
+        });
+      } catch (err) {
+        printRichCard({
+          title: 'MCP Reconnect Error',
+          status: 'error',
+          lines: [err.message],
+        });
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'remove' || action === 'rm' || action === 'del') {
+      const name = (ctx.extra || '').trim();
+      if (!name) {
+        console.log(`\n  ${C.amber}Usage: /mcp remove <server_name>${C.reset}\n`);
+        return 'HANDLED';
+      }
+      const success = await ctx.agent.removeMcp(name);
+      if (success) {
+        printRichCard({
+          title: 'MCP Server Removed',
+          status: 'ok',
+          lines: [`Removed "${name}" from saved configuration and disconnected.`],
+        });
+      } else {
+        printRichCard({
+          title: 'MCP Server Not Found',
+          status: 'warning',
+          lines: [`Server "${name}" was not found in saved configuration.`],
+        });
+      }
+      return 'HANDLED';
+    }
+
+    if (action === 'disconnect') {
       const name = (ctx.extra || '').trim();
       if (!name) {
         console.log(`\n  ${C.amber}Usage: /mcp disconnect <server_name>${C.reset}\n`);
@@ -1383,45 +1648,81 @@ export const handlers = {
       }
       const success = await ctx.agent.disconnectMcp(name);
       if (success) {
-        console.log(`\n  ${C.emerald}[OK] Disconnected MCP server "${name}".${C.reset}\n`);
+        printRichCard({
+          title: 'MCP Server Disconnected',
+          status: 'info',
+          lines: [
+            `Disconnected session for "${name}".`,
+            `Config remains saved. Run /mcp reconnect ${name} to reconnect.`,
+          ],
+        });
       } else {
-        console.log(`\n  ${C.amber}MCP server "${name}" not found.${C.reset}\n`);
+        printRichCard({
+          title: 'MCP Server Not Found',
+          status: 'warning',
+          lines: [`MCP server "${name}" is not currently connected.`],
+        });
       }
       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}`,
+      `${C.gold}Active Live Servers:${C.reset} ${C.cyberCyan}${status.activeServersCount}${C.reset}  •  ${C.gold}Total Configured:${C.reset} ${C.white}${status.totalConfiguredCount}${C.reset}  •  ${C.gold}Total Tools:${C.reset} ${C.cyberCyan}${status.totalToolsCount}${C.reset}`,
       ''
     ];
 
     if (status.servers.length > 0) {
-      lines.push(`${C.bold}${C.lavender}Connected Servers:${C.reset}`);
+      lines.push(`${C.bold}${C.lavender}Configured MCP 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`);
+        const serverName = sanitizeTerminalText(s.name, 128) || 'unnamed';
+        const serverType = sanitizeTerminalText(s.type, 80) || 'unknown';
+        if (s.status === 'connected') {
+          lines.push(`  ${C.emerald}● Connected:${C.reset} ${C.bold}${C.white}${serverName}${C.reset} ${C.dim}(${serverType})${C.reset} — ${C.emerald}${s.toolsCount} tools${C.reset}, ${s.resourcesCount} resources`);
+        } else if (s.status === 'saved_offline') {
+          lines.push(`  ${C.slate}○ Saved (Offline):${C.reset} ${C.bold}${C.white}${serverName}${C.reset} ${C.dim}(${serverType})${C.reset} — ${C.dim}type /mcp reconnect ${serverName} to start${C.reset}`);
+        } else {
+          lines.push(`  ${C.red}✕ Error:${C.reset} ${C.bold}${C.white}${serverName}${C.reset} ${C.dim}(${serverType})${C.reset} — ${C.red}${s.error || 'Connection failed'}${C.reset}`);
+        }
+      }
+
+      const connectedTools = mcpManager.getToolsSchema();
+      if (connectedTools.length > 0) {
+        lines.push('', `${C.bold}${C.lavender}Available MCP Tool Commands (${connectedTools.length}):${C.reset}`);
+        const commandList = connectedTools
+          .map(tool => `@${sanitizeTerminalText(tool.function?.name, 128) || 'unknown_tool'}`)
+          .join('  •  ');
+        for (const commandLine of wrapText(commandList, Math.max(30, getFullWidth() - 8))) {
+          lines.push(`  ${C.cyberCyan}${commandLine}${C.reset}`);
+        }
+        lines.push(`${C.dim}Use /mcp tools for parameters and full descriptions.${C.reset}`);
       }
     } else {
-      lines.push(`${C.dim}No active MCP servers connected.${C.reset}`);
-      lines.push(`Connect with: ${C.cyberCyan}/mcp connect <name> <url>${C.reset}`);
+      lines.push(`${C.dim}No MCP servers configured.${C.reset}`);
+      lines.push(`Connect and save with: ${C.cyberCyan}/mcp connect <name> <url>${C.reset}`);
     }
 
+    lines.push('', `${C.dim}Commands: /mcp connect <name> <url> | /mcp reconnect [all] | /mcp save | /mcp remove <name> | /mcp tools${C.reset}`);
+
     printSolidPanel({
-      title: `Model Context Protocol (MCP) Client`,
+      title: `Model Context Protocol (MCP) Manager • ${status.activeServersCount} Active / ${status.totalConfiguredCount} Saved`,
       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`);
+    try {
+      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 || check.model || 'Ready'}${C.reset}\n`);
+      } else {
+        console.log(`\n  ${C.red}● Disconnected${C.reset} ${C.dim}(${ms}ms)${C.reset} — ${C.amber}${check.error || 'Server unreachable'}${C.reset}\n`);
+      }
+    } catch (err) {
+      console.log(`\n  ${C.red}[PING ERROR] ${err.message || String(err)}${C.reset}\n`);
     }
     return 'HANDLED';
   },
@@ -1444,15 +1745,19 @@ export const handlers = {
   },
 
   '/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}`;
-      }),
-    });
+    try {
+      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}`;
+        }),
+      });
+    } catch (err) {
+      console.log(`\n  ${C.red}[DOCTOR ERROR] ${err.message || String(err)}${C.reset}\n`);
+    }
     return 'HANDLED';
   },
 
@@ -1460,7 +1765,8 @@ export const handlers = {
     printSolidPanel({
       title: 'Version',
       lines: [
-        `${C.gold}Version:${C.reset} ${C.white}1.0.4${C.reset}`,
+        `${C.gold}Package:${C.reset} ${C.white}${PACKAGE_NAME}${C.reset}`,
+        `${C.gold}Version:${C.reset} ${C.white}${PACKAGE_VERSION}${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}`,
       ],
@@ -1468,6 +1774,186 @@ export const handlers = {
     return 'HANDLED';
   },
 
+  '/update': async (ctx) => {
+    const manager = ctx.updateManager || new UpdateManager();
+    const action = (ctx.sub || 'check').toLowerCase();
+    const parts = ctx.parts || [];
+    const allowMajor = parts.includes('--allow-major');
+    const allowDeprecated = parts.includes('--allow-deprecated');
+    const positional = parts.slice(2).filter(part => !part.startsWith('--'));
+    const flags = parts.slice(2).filter(part => part.startsWith('--'));
+
+    const printUpdateHelp = () => printSolidPanel({
+      title: 'Kiku Agent Update',
+      lines: [
+        `${C.bold}${C.white}/update${C.reset} ${C.dim}or /update check — check the configured channel${C.reset}`,
+        `${C.bold}${C.white}/update install [latest|next|canary|x.y.z]${C.reset}`,
+        `${C.bold}${C.white}/update channel [latest|next|canary]${C.reset}`,
+        `${C.bold}${C.white}/update rollback${C.reset} ${C.dim}— reinstall the previously recorded version${C.reset}`,
+        '',
+        `${C.dim}Major releases require --allow-major. Deprecated releases require --allow-deprecated.${C.reset}`,
+      ],
+    });
+
+    const statusLines = status => {
+      const changeLabel = status.change === 'upgrade'
+        ? `${C.emerald}UPDATE AVAILABLE${C.reset}`
+        : status.change === 'downgrade'
+          ? `${C.amber}OLDER RELEASE${C.reset}`
+          : `${C.emerald}UP TO DATE${C.reset}`;
+      const lines = [
+        `${C.gold}Current:${C.reset}      ${C.white}${status.currentVersion}${C.reset}`,
+        `${C.gold}Target:${C.reset}       ${C.white}${status.targetVersion}${C.reset} ${C.dim}(${status.target})${C.reset}`,
+        `${C.gold}Status:${C.reset}       ${changeLabel}`,
+        `${C.gold}Installation:${C.reset} ${C.white}${status.installMode.label}${C.reset}`,
+        `${C.gold}Node:${C.reset}         ${status.nodeCompatible ? C.emerald + 'Compatible' : C.red + 'Incompatible'}${C.reset}${status.nodeRange ? ` ${C.dim}(requires ${status.nodeRange})${C.reset}` : ''}`,
+        `${C.gold}Integrity:${C.reset}    ${status.integrity ? C.emerald + 'Published with npm integrity metadata' : C.amber + 'Not reported'}${C.reset}`,
+      ];
+      if (status.majorChange) lines.push(`${C.amber}[MAJOR] This release crosses a major-version boundary.${C.reset}`);
+      if (status.deprecated) lines.push(`${C.red}[DEPRECATED] ${status.deprecated}${C.reset}`);
+      lines.push('', `${C.bold}${C.lavender}What's new:${C.reset}`);
+      if (status.releaseNotes.length > 0) {
+        for (const note of status.releaseNotes) lines.push(`  ${C.sakura}•${C.reset} ${C.white}${note}${C.reset}`);
+      } else {
+        lines.push(`  ${C.dim}No release summary was published for this version.${C.reset}`);
+      }
+      if (status.releaseUrl) lines.push('', `${C.dim}Release: ${status.releaseUrl}${C.reset}`);
+      return lines;
+    };
+
+    try {
+      const allowedFlags = action === 'install'
+        ? ['--allow-major', '--allow-deprecated']
+        : action === 'rollback'
+          ? ['--allow-deprecated']
+          : [];
+      if (flags.some(flag => !allowedFlags.includes(flag))) {
+        throw new UpdateError('Unknown option. Run /update help for supported arguments.', 'INVALID_OPTION');
+      }
+      if (positional.length > 1 || ((action === 'rollback' || action === 'help') && positional.length > 0)) {
+        throw new UpdateError('Too many update arguments. Run /update help for usage.', 'INVALID_ARGUMENTS');
+      }
+
+      if (action === 'help') {
+        printUpdateHelp();
+        return 'HANDLED';
+      }
+
+      if (action === 'channel') {
+        const requested = positional[0];
+        if (!requested) {
+          const channel = await manager.getChannel();
+          printSolidPanel({
+            title: 'Update Channel',
+            lines: [
+              `${C.gold}Current:${C.reset} ${C.white}${channel}${C.reset}`,
+              `${C.dim}Available: ${UPDATE_CHANNELS.join(', ')}${C.reset}`,
+            ],
+          });
+          return 'HANDLED';
+        }
+        const channel = await manager.setChannel(requested);
+        printSolidPanel({
+          title: 'Update Channel Changed',
+          lines: [
+            `${C.emerald}[OK] Future /update checks will use ${C.bold}${channel}${C.reset}${C.emerald}.${C.reset}`,
+            `${C.dim}This changes only the release channel; it does not install anything.${C.reset}`,
+          ],
+        });
+        return 'HANDLED';
+      }
+
+      if (action === 'install') {
+        const target = positional[0];
+        console.log(`\n  ${C.cyberCyan}[UPDATE] Resolving and validating the requested npm release...${C.reset}\n`);
+        const result = await manager.install(target, {
+          allowMajor,
+          allowDeprecated,
+          onProgress: message => { if (message) console.log(`  ${C.dim}${message}${C.reset}`); },
+        });
+        if (result.outcome === 'manual') {
+          printSolidPanel({
+            title: 'Manual Update Required',
+            lines: [
+              ...statusLines(result),
+              '',
+              `${C.amber}This installation type is not modified automatically.${C.reset}`,
+              `${C.gold}Run:${C.reset} ${C.white}${result.command}${C.reset}`,
+            ],
+          });
+          return 'HANDLED';
+        }
+        if (result.outcome === 'current') {
+          printSolidPanel({ title: 'Kiku Agent Is Up to Date', lines: statusLines(result) });
+          return 'HANDLED';
+        }
+        printSolidPanel({
+          title: 'Update Installed Successfully',
+          lines: [
+            `${C.emerald}[OK] ${PACKAGE_NAME} ${result.installedVersion} was installed and verified.${C.reset}`,
+            ...(!result.historyRecorded ? [`${C.amber}[WARNING] Rollback history could not be saved.${C.reset}`] : []),
+            `${C.dim}This session will close. Start kiku-agent again to load the new code.${C.reset}`,
+            `${C.dim}Restart MCP hosts to load the matching kiku-mcp server version.${C.reset}`,
+          ],
+        });
+        try { await ctx.agent?.endSession?.(); } catch {}
+        return 'EXIT';
+      }
+
+      if (action === 'rollback') {
+        console.log(`\n  ${C.cyberCyan}[UPDATE] Resolving the previously installed version...${C.reset}\n`);
+        const result = await manager.rollback({ allowDeprecated });
+        if (result.outcome === 'manual') {
+          printSolidPanel({
+            title: 'Manual Rollback Required',
+            lines: [
+              `${C.amber}Run the following command outside Kiku Agent:${C.reset}`,
+              `${C.white}${result.command}${C.reset}`,
+            ],
+          });
+          return 'HANDLED';
+        }
+        if (result.outcome === 'current') {
+          printSolidPanel({ title: 'Rollback Not Needed', lines: statusLines(result) });
+          return 'HANDLED';
+        }
+        printSolidPanel({
+          title: 'Rollback Installed Successfully',
+          lines: [
+            `${C.emerald}[OK] Restored ${PACKAGE_NAME} ${result.installedVersion}.${C.reset}`,
+            ...(!result.historyRecorded ? [`${C.amber}[WARNING] Rollback history could not be saved.${C.reset}`] : []),
+            `${C.dim}This session will close. Restart Kiku Agent and any MCP host.${C.reset}`,
+          ],
+        });
+        try { await ctx.agent?.endSession?.(); } catch {}
+        return 'EXIT';
+      }
+
+      if (action === 'check' || action === 'status') {
+        const status = await manager.check(positional[0]);
+        const lines = statusLines(status);
+        if (status.updateAvailable) {
+          lines.push('', `${C.cyberCyan}Run /update install${status.target === 'latest' ? '' : ` ${status.target}`} to update.${C.reset}`);
+        }
+        printSolidPanel({ title: 'Kiku Agent Update', lines });
+        return 'HANDLED';
+      }
+
+      printUpdateHelp();
+      return 'HANDLED';
+    } catch (error) {
+      const safeMessage = error instanceof UpdateError ? error.message : 'The update operation failed unexpectedly.';
+      printSolidPanel({
+        title: 'Update Failed',
+        lines: [
+          `${C.red}[${error.code || 'UPDATE_ERROR'}] ${safeMessage}${C.reset}`,
+          `${C.dim}No session, memory, or environment files were changed.${C.reset}`,
+        ],
+      });
+      return 'HANDLED';
+    }
+  },
+
   '/system': async () => {
     const os = await import('node:os');
     const mem = process.memoryUsage();
@@ -1564,11 +2050,16 @@ export const handlers = {
   '/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`);
+    ctx.setIsProcessing?.(true, 'YouTube Login');
+    try {
+      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`);
+      }
+    } finally {
+      ctx.setIsProcessing?.(false);
     }
     return 'HANDLED';
   },
@@ -1612,19 +2103,23 @@ export const handlers = {
   },
 
   '/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'
-    });
+    try {
+      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 || 0}${C.reset}`,
+          `${C.gold}Songs:${C.reset}     ${C.cyberCyan}${s.totalUniqueSongs || 0}${C.reset}`,
+          `${C.gold}Brands:${C.reset}    ${C.cyberCyan}${s.brandEndorsements || 0}${C.reset}`,
+          `${C.gold}Awards:${C.reset}    ${C.cyberCyan}${s.totalAwards || 0}${C.reset}`,
+          `${C.gold}Timeline:${C.reset}  ${C.cyberCyan}${s.timelineMilestones || 0}${C.reset}`
+        ],
+        headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m'
+      });
+    } catch (err) {
+      console.log(`\n  ${C.red}[STATS ERROR] ${err.message || String(err)}${C.reset}\n`);
+    }
     return 'HANDLED';
   },
 
@@ -1635,6 +2130,70 @@ export const handlers = {
     return 'HANDLED';
   },
 
+  '/cancel': async (ctx) => {
+    if (typeof ctx.cancelActiveQuery === 'function') {
+      const ok = ctx.cancelActiveQuery();
+      if (ok) {
+        printRichCard({
+          title: 'Query Cancelled',
+          status: 'cancel',
+          lines: ['Active query and queued tasks were cancelled.'],
+        });
+      } else {
+        printRichCard({
+          title: 'No Active Query',
+          status: 'info',
+          lines: ['There is no query currently running.'],
+        });
+      }
+      return 'HANDLED';
+    }
+    if (ctx.agent && typeof ctx.agent.cancelResearch === 'function') {
+      ctx.agent.cancelResearch();
+    }
+    return 'HANDLED';
+  },
+
+  '/copy': async (ctx) => {
+    if (typeof ctx.copyQueryDetails === 'function') {
+      const reference = [ctx.sub, ctx.extra].filter(Boolean).join(' ');
+      ctx.copyQueryDetails(reference);
+      return 'HANDLED';
+    }
+    const { getCopyableContent, copyToClipboard, parseDetailsRequest } = await import('./queryDetails.js');
+    const reference = [ctx.sub, ctx.extra].filter(Boolean).join(' ');
+    const request = parseDetailsRequest(reference);
+    const details = ctx.agent?.lastQueryDetails || null;
+    if (!details) {
+      printRichCard({
+        title: 'No Diagnostics Recorded',
+        status: 'warning',
+        lines: ['No completed model queries are available to copy.'],
+      });
+      return 'HANDLED';
+    }
+    const copyable = getCopyableContent(details, request);
+    if (!copyable?.text) {
+      printRichCard({
+        title: 'Nothing to Copy',
+        status: 'warning',
+        lines: ['The requested query section is empty.'],
+      });
+      return 'HANDLED';
+    }
+    const copied = copyToClipboard(copyable.text);
+    printRichCard({
+      title: copied ? 'Copied to Clipboard' : 'Copy Content Ready',
+      status: copied ? 'ok' : 'info',
+      lines: [
+        `• Target: ${copyable.title}`,
+        `• Characters: ${copyable.text.length} chars (${copyable.text.split('\n').length} lines)`,
+        ...(copied ? ['• Status: Copied to system clipboard (Ready to paste with Ctrl+V / Cmd+V)'] : []),
+      ],
+    });
+    return 'HANDLED';
+  },
+
   '/ads': async (ctx) => {
     ctx.printAd();
     return 'HANDLED';
@@ -1643,6 +2202,8 @@ export const handlers = {
 
 const ALIASES = {
   '/quit': '/exit', '/q': '/exit',
+  '/abort': '/cancel',
+  '/cp': '/copy', '/clip': '/copy', '/clipboard': '/copy',
   '/?': '/help', '/commands': '/help', '/menu': '/help',
   '/hist': '/history', '/h': '/history',
   '/sess': '/session', '/sessions': '/session',
@@ -1650,6 +2211,7 @@ const ALIASES = {
   '/detail': '/details', '/d': '/details',
   '/language': '/lang',
   '/themes': '/theme',
+  '/suggest': '/suggestion', '/suggestions': '/suggestion',
   '/exec': '/tool', '/call': '/tool',
   '/toollist': '/tools',
   '/metrics': '/stats', '/catalog': '/stats',
@@ -1690,5 +2252,9 @@ export async function routeCommand(rawInput, ctx) {
     return 'UNKNOWN';
   }
 
+  if (sub.toLowerCase() === 'help' && rawCmd !== '/help') {
+    return handlers['/help']({ ...ctx, sub: rawCmd, extra: '' });
+  }
+
   return await handler({ ...ctx, sub, extra, parts });
 }