kiku-agent 1.0.11 → 1.2.0

package/server/agent/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
 import { stdin as input } from 'node:process';
 import { existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
@@ -15,11 +16,14 @@ import { eventBus, Events } from './eventBus.js';
 import { AgentStates } from './agentState.js';
 import { sanitizeQuery } from './sanitizer.js';
 import { isAbortError, formatExecutionErrorCard } from './errors.js';
-import { COMMAND_DEFINITIONS, SUB_COMMANDS, findCommandDefinition, getCommandDetails } from './commandRegistry.js';
+import { COMMAND_DEFINITIONS, COMMAND_CATEGORIES, SUB_COMMANDS, findCommandDefinition, getCommandDetails } from './commandRegistry.js';
 import { ModelManager } from './modelManager.js';
 import { PACKAGE_VERSION } from './version.js';
-import { getTheme, getThemeName } from './theme.js';
+import { getProfile, listProfiles } from './profiles.js';
+import { formatCitationsBlock } from './citations.js';
+import { getTheme, getThemeName, setTheme, THEME_NAMES, setColorDisabled } from './theme.js';
 import { createTerminalImageGallery, getWelcomeGalleryLines } from './terminalImage.js';
+import { formatQuestionsForCLI } from './clarifyingQuestions.js';
 import {
   classifyToolResult,
   formatDetailDuration,
@@ -33,7 +37,7 @@ import {
 import {
   C, getStringDisplayWidth, getFullWidth, wrapText, stripAnsi, fitStyledText, sanitizeTerminalText,
   previousGraphemeBoundary, nextGraphemeBoundary, sliceLineForDisplay,
-  printSolidBannerRow, printSolidPanel, formatSolidPanelLines, formatTerminalMarkdown,
+  printSolidBannerRow, printSolidPanel, formatSolidPanelLines, formatTerminalMarkdown, formatMarkdownLines,
   parseMarkdownTableRow, isMarkdownTableSeparator, expandMarkdownLinks,
   formatRichCardLines, printRichCard, printRichStatusCard, formatStatusBadge, formatRichTable,
   printWelcomeHero, getWelcomeHeroLines, randomFanName, setupOutputInterception,
@@ -53,9 +57,64 @@ const deferredCommands = [];
 let globalTuiPrompt = null;
 let lastQueryDetails = null;
 const queryDetails = new Map();
+let globalSpinnerInterval = null;
 
-function parseCliArgs() {
-  const args = process.argv.slice(2);
+function startGlobalSpinner(label) {
+  if (globalTuiPrompt) {
+    if (label !== undefined && label !== null) {
+      globalTuiPrompt.agentState = label;
+      globalTuiPrompt.agentStateTime = Date.now();
+    }
+    globalTuiPrompt.render();
+  }
+  if (!globalSpinnerInterval) {
+    globalSpinnerInterval = setInterval(() => {
+      if (globalTuiPrompt && isProcessing) {
+        globalTuiPrompt.render();
+      }
+    }, 80);
+  }
+}
+
+function stopGlobalSpinner() {
+  if (globalSpinnerInterval) {
+    clearInterval(globalSpinnerInterval);
+    globalSpinnerInterval = null;
+  }
+  if (globalTuiPrompt) {
+    globalTuiPrompt.agentState = '';
+    globalTuiPrompt.render();
+  }
+}
+
+function recordQueryDiagnostics(details) {
+  if (!details) return null;
+  const num = details.number ?? nextQueryNumber++;
+  lastQueryDetails = {
+    number: num,
+    prompt: details.prompt || '',
+    answer: details.answer || '',
+    thinking: details.thinking || '',
+    tools: details.tools || [],
+    status: details.status || 'complete',
+    error: details.error || null,
+    provider: details.provider || 'unknown',
+    model: details.model || 'unknown',
+    language: details.language || null,
+    iterations: details.iterations || (details.tools?.length ? 1 : 0),
+    maxIterations: details.maxIterations || 3,
+    startedAt: details.startedAt || Date.now(),
+    completedAt: details.completedAt || Date.now(),
+    durationMs: details.durationMs || (details.completedAt && details.startedAt ? details.completedAt - details.startedAt : 0),
+    timestamp: Date.now(),
+  };
+  queryDetails.set(num, lastQueryDetails);
+  if (queryDetails.size > 50) queryDetails.delete(queryDetails.keys().next().value);
+  return lastQueryDetails;
+}
+
+export function parseCliArgs(customArgs = null) {
+  const args = customArgs || process.argv.slice(2);
   const options = {
     query: null,
     provider: null,
@@ -63,12 +122,20 @@ function parseCliArgs() {
     model: null,
     url: null,
     mcp: null,
+    profile: null,
     showTools: false,
     showStats: false,
     thinking: 'show',
     verbose: false,
     help: false,
-    version: false
+    version: false,
+    print: false,
+    output: 'text',
+    plain: false,
+    noColor: false,
+    webChat: false,
+    port: null,
+    noOpen: false,
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -85,8 +152,54 @@ function parseCliArgs() {
     else if (arg === '--model' || arg === '-m') options.model = args[++i];
     else if (arg === '--url' || arg === '-u') options.url = args[++i];
     else if (arg === '--query' || arg === '-q') options.query = args[++i];
+    else if (arg === '--profile') options.profile = args[++i];
+    else if (arg === '--print' || arg === '-p') options.print = true;
+    else if (arg === '--output' || arg === '-o') options.output = (args[++i] || 'text').toLowerCase();
+    else if (arg === '--plain') { options.plain = true; options.noColor = true; }
+    else if (arg === '--no-color') options.noColor = true;
+    else if (arg === '--web-chat' || arg === '--web') options.webChat = true;
+    else if (arg.startsWith('--web-chat=')) {
+      options.webChat = true;
+      const maybePort = Number(arg.slice('--web-chat='.length));
+      if (Number.isFinite(maybePort) && maybePort > 0) options.port = Math.trunc(maybePort);
+    }
+    else if (arg === '--port') {
+      const maybePort = Number(args[++i]);
+      if (!Number.isFinite(maybePort) || maybePort < 1 || maybePort > 65535) {
+        console.error(`Invalid --port: ${args[i]}. Expected 1-65535.`);
+        process.exit(3);
+      }
+      options.port = Math.trunc(maybePort);
+    }
+    else if (arg.startsWith('--port=')) {
+      const maybePort = Number(arg.slice('--port='.length));
+      if (!Number.isFinite(maybePort) || maybePort < 1 || maybePort > 65535) {
+        console.error(`Invalid --port: ${arg}. Expected 1-65535.`);
+        process.exit(3);
+      }
+      options.port = Math.trunc(maybePort);
+    }
+    else if (arg === '--no-open') options.noOpen = true;
+    else if (arg === '--open') options.noOpen = false;
     else if (!arg.startsWith('-') && !options.query) { options.query = args.slice(i).join(' '); break; }
+    else if (arg.startsWith('-')) {
+      console.error(`Unknown option: ${arg}`);
+      process.exit(3);
+    }
   }
+
+  if (options.output !== 'text' && options.output !== 'json') {
+    console.error(`Invalid --output format: ${options.output}. Supported formats: text, json`);
+    process.exit(3);
+  }
+
+  if (options.noColor || options.plain || (typeof process !== 'undefined' && process.env?.NO_COLOR)) {
+    setColorDisabled(true);
+  }
+  if (options.output === 'json') {
+    options.print = true;
+  }
+
   return options;
 }
 
@@ -236,7 +349,7 @@ function printQueryDetails(reference = '') {
     printSolidPanel({
       title: `Answer • ${queryLabel}`,
       lines: details.answer
-        ? String(details.answer).split('\n').flatMap(line => wrapText(sanitizeTerminalText(line, 500000), width)).map(line => `${C.white}${formatTerminalMarkdown(line)}${C.reset}`)
+        ? formatMarkdownLines(details.answer, width - 4)
         : [`${C.dim}${C.slate}No final answer was recorded.${C.reset}`],
     });
     return;
@@ -292,7 +405,7 @@ function printQueryDetails(reference = '') {
     const copyable = getCopyableContent(details, request);
     printSolidPanel({
       title: copyable.title,
-      lines: copyable.text.split('\n').flatMap(line => wrapText(line, width)).map(line => `${C.white}${line}${C.reset}`),
+      lines: formatMarkdownLines(copyable.text, width - 4),
     });
     return;
   }
@@ -338,19 +451,33 @@ function copyQueryDetails(reference = '', session = null) {
     return false;
   }
 
+  if (request.isSession) {
+    if (!session || !session.messages || session.messages.length === 0) {
+      console.log(`\n  ${C.amber}[EMPTY] No conversation messages in the current session to copy.${C.reset}\n`);
+      return false;
+    }
+  } else {
+    const details = request.queryNumber == null
+      ? lastQueryDetails
+      : queryDetails.get(request.queryNumber);
+
+    if (!details) {
+      const target = request.queryNumber == null ? 'the latest query' : `Q${request.queryNumber}`;
+      console.log(`\n  ${C.amber}[NOT FOUND] No diagnostics recorded for ${target}. Ask a question or run a tool first.${C.reset}\n`);
+      return false;
+    }
+  }
+
   const details = request.queryNumber == null
     ? lastQueryDetails
     : queryDetails.get(request.queryNumber);
 
-  if (!details && !request.isSession && !session) {
-    const target = request.queryNumber == null ? 'the latest query' : `Q${request.queryNumber}`;
-    console.log(`\n  ${C.amber}[NOT FOUND] No diagnostics recorded for ${target}.${C.reset}\n`);
-    return false;
-  }
-
   const copyable = getCopyableContent(details, request, session);
-  if (!copyable || !copyable.text) {
-    console.log(`\n  ${C.amber}[EMPTY] Nothing to copy for ${request.view || 'answer'}.${C.reset}\n`);
+  if (!copyable || !copyable.text || !copyable.text.trim()) {
+    const target = request.isSession
+      ? 'the active session'
+      : (request.queryNumber == null ? `the latest query (${request.view})` : `Q${request.queryNumber} (${request.view})`);
+    console.log(`\n  ${C.amber}[EMPTY] Nothing recorded to copy for ${target}.${C.reset}\n`);
     return false;
   }
 
@@ -437,23 +564,55 @@ export function printHelp(specificCmd = null) {
   const termWidth = getFullWidth();
   const maxContentWidth = Math.max(40, termWidth - 8);
   const helpLines = [];
-
-  for (const command of COMMAND_DEFINITIONS) {
-    const usageWidth = 30;
-    const descWidth = maxContentWidth - usageWidth - 2;
-
-    if (command.usage.length > 28 || command.desc.length > descWidth) {
-      const wrappedDesc = wrapText(command.desc, maxContentWidth - 6);
-      helpLines.push(`${C.emerald}${command.usage}${C.reset}`);
-      for (const d of wrappedDesc) {
-        helpLines.push(`  ${C.dim}↳${C.reset} ${C.white}${d}${C.reset}`);
+  const cmdMap = new Map(COMMAND_DEFINITIONS.map(c => [c.name, c]));
+  const categories = Array.isArray(COMMAND_CATEGORIES) && COMMAND_CATEGORIES.length > 0
+    ? COMMAND_CATEGORIES
+    : [{ id: 'all', name: 'All Commands', icon: '✦', commands: COMMAND_DEFINITIONS.map(c => c.name) }];
+
+  for (const cat of categories) {
+    helpLines.push(`${C.bold}${C.sakura}${cat.icon || '✦'} ${cat.name}${C.reset}`);
+    for (const cmdName of cat.commands) {
+      const command = cmdMap.get(cmdName);
+      if (!command) continue;
+      const usageWidth = 30;
+      const descWidth = maxContentWidth - usageWidth - 4;
+
+      if (command.usage.length > 28 || command.desc.length > descWidth) {
+        const wrappedDesc = wrapText(command.desc, maxContentWidth - 8);
+        helpLines.push(`  ${C.emerald}${command.usage}${C.reset}`);
+        for (const d of wrappedDesc) {
+          helpLines.push(`    ${C.dim}↳${C.reset} ${C.white}${d}${C.reset}`);
+        }
+      } else {
+        helpLines.push(`  ${C.emerald}${command.usage.padEnd(usageWidth)}${C.reset} ${C.white}${command.desc}${C.reset}`);
       }
-    } else {
-      helpLines.push(`${C.emerald}${command.usage.padEnd(usageWidth)}${C.reset} ${C.white}${command.desc}${C.reset}`);
     }
+    helpLines.push('');
   }
 
-  helpLines.push('', `${C.dim}Tip: Press Tab for auto-completion • Type /help <command> (e.g. /help suggestion, /help mcp, /help provider) for detailed subcommand breakdowns.${C.reset}`);
+  if (helpLines[helpLines.length - 1] === '') helpLines.pop();
+  helpLines.push('', `${C.dim}Tip: Press Tab for auto-completion • Type /help <command> (e.g. /help session, /help provider, /help mcp) for detailed subcommand breakdowns.${C.reset}`);
+
+  helpLines.push('', `${C.bold}${C.sakura}✦ CLI Flags & Options${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-q, --query <text>".padEnd(28)}${C.reset} ${C.white}Run a one-shot query${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-p, --print".padEnd(28)}${C.reset} ${C.white}Headless non-interactive print mode (clean text output)${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-o, --output <format>".padEnd(28)}${C.reset} ${C.white}Output format: text (default) or json${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-P, --provider <name>".padEnd(28)}${C.reset} ${C.white}Select provider (lmstudio, openai, gemini, groq, etc.)${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--profile <name>".padEnd(28)}${C.reset} ${C.white}Load configuration profile (default, fast, deep-reasoning, cloud, gemini)${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-m, --model <id>".padEnd(28)}${C.reset} ${C.white}Model ID override${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-k, --api-key <key>".padEnd(28)}${C.reset} ${C.white}Provider API key override${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-u, --url <url>".padEnd(28)}${C.reset} ${C.white}Provider base URL override${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--plain".padEnd(28)}${C.reset} ${C.white}Disable ANSI styles, colors, and alternate screen${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--no-color".padEnd(28)}${C.reset} ${C.white}Disable ANSI colors (honors NO_COLOR env)${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--thinking <mode>".padEnd(28)}${C.reset} ${C.white}Show or hide reasoning process (show | hide)${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-t, --tools".padEnd(28)}${C.reset} ${C.white}List all registered tools${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-s, --stats".padEnd(28)}${C.reset} ${C.white}Show system and catalog stats${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--web-chat, --web".padEnd(28)}${C.reset} ${C.white}Start standalone web chatbot (default port 3300)${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--port <n>".padEnd(28)}${C.reset} ${C.white}Web chatbot port 1-65535 (or --web-chat=<port>)${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--no-open, --open".padEnd(28)}${C.reset} ${C.white}Skip or force auto-open browser for --web-chat${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-v, --verbose".padEnd(28)}${C.reset} ${C.white}Verbose logging and thinking${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-V, --version".padEnd(28)}${C.reset} ${C.white}Print version${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"-h, --help".padEnd(28)}${C.reset} ${C.white}Show this help message${C.reset}`);
 
   printSolidPanel({
     title: `${UI_ICONS.help} Kiku AI Agent — ${COMMAND_DEFINITIONS.length} Commands`,
@@ -694,6 +853,7 @@ class InteractiveTuiPrompt {
     this._cleanupInput();
     this.line = '';
     this.cursor = 0;
+    this.ghostText = '';
     this.popoverActive = false;
     this.popoverItems = [];
     if (this.recordInputHistory && result && result.trim()) this.history.push(result);
@@ -1002,8 +1162,15 @@ class InteractiveTuiPrompt {
     if (isF3) { this.finish('/details thinking'); return; }
     if (isF4) { this.finish('/details tools'); return; }
     if (isF5) { this.finish('/copy'); return; }
-    if (isF6) { this.finish('/gallery'); return; }
-    if (isF7) { this.finish('/theme next'); return; }
+    if (isF6) { this.finish('/timeline'); return; }
+    if (isF7) {
+      const current = getThemeName();
+      const currentIndex = THEME_NAMES.indexOf(current);
+      const nextIndex = (currentIndex + 1) % THEME_NAMES.length;
+      setTheme(THEME_NAMES[nextIndex]);
+      this.render();
+      return;
+    }
     if (isF8) { this.finish('/stats'); return; }
     if (isF9) { this.finish('/provider'); return; }
     if (isF10) { this.finish('/mcp list'); return; }
@@ -1014,12 +1181,21 @@ class InteractiveTuiPrompt {
     const isCtrlR = (key?.ctrl && key?.name === 'r') || str === '\x12';
     const isCtrlS = (key?.ctrl && key?.name === 's') || str === '\x13';
     const isCtrlG = (key?.ctrl && key?.name === 'g') || str === '\x07';
+    const isCtrlK = (key?.ctrl && key?.name === 'k') || str === '\x0b';
+    const isCtrlP = (key?.ctrl && key?.name === 'p') || str === '\x10';
 
     if (isCtrlL) { this.render(); return; }
     if (isCtrlT) { this.finish('/thinking toggle'); return; }
     if (isCtrlR) { this.finish('/retry'); return; }
     if (isCtrlS) { this.finish('/save'); return; }
     if (isCtrlG) { this.finish('/gallery'); return; }
+    if (isCtrlK || isCtrlP) {
+      this.line = '/';
+      this.cursor = 1;
+      this.updateState();
+      this.render();
+      return;
+    }
 
     if (key?.name === 'tab' || str === '\t') {
       if (this.popoverActive && this.popoverItems.length > 0) {
@@ -1443,29 +1619,11 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
           };
 
           const startSpinner = (label) => {
-            if (globalTuiPrompt) {
-              globalTuiPrompt.agentState = label;
-              globalTuiPrompt.agentStateTime = Date.now();
-              globalTuiPrompt.render();
-            }
-            if (!spinnerInterval) {
-              spinnerInterval = setInterval(() => {
-                if (globalTuiPrompt && isProcessing) {
-                  globalTuiPrompt.render();
-                }
-              }, 80);
-            }
+            startGlobalSpinner(label);
           };
 
           const stopSpinner = () => {
-            if (spinnerInterval) {
-              clearInterval(spinnerInterval);
-              spinnerInterval = null;
-            }
-            if (globalTuiPrompt) {
-              globalTuiPrompt.agentState = '';
-              globalTuiPrompt.render();
-            }
+            stopGlobalSpinner();
           };
 
           let thinkingShown = false;
@@ -1479,12 +1637,13 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
           let finalMeta = {};
 
           const persistQueryDetails = (status, error = null) => {
-            lastQueryDetails = {
+            recordQueryDiagnostics({
               number: queryNumber,
               prompt,
               answer: finalAnswer,
               thinking: accumulatedThinking,
               tools: recordedTools,
+              citations: agent?.lastCitations || [],
               status,
               error: error ? String(error.message || error) : null,
               provider: agent.client?.providerName || agent.client?.provider || 'unknown',
@@ -1495,12 +1654,7 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
               startedAt: queryStartedAt,
               completedAt: Date.now(),
               durationMs: finalMeta.durationMs ?? (Date.now() - queryStartedAt),
-              timestamp: Date.now(),
-            };
-            if (queryNumber != null) {
-              queryDetails.set(queryNumber, lastQueryDetails);
-              if (queryDetails.size > 50) queryDetails.delete(queryDetails.keys().next().value);
-            }
+            });
           };
 
           startSpinner(`${C.slate}Thinking…${C.reset}`);
@@ -1508,6 +1662,19 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
           try {
             const returnedAnswer = await agent.ask(prompt, {
               signal,
+              onClarifyingQuestions: (questions) => {
+                stopSpinner();
+                console.log(formatQuestionsForCLI(questions, C));
+              },
+              onClarifyingAnswer: (queryId) => {
+                return new Promise((resolve) => {
+                  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                  rl.question(`${C.gold}> ${C.reset}`, (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                  });
+                });
+              },
               onStepStart: iteration => { completedIterations = Math.max(completedIterations, Number(iteration) || 0); },
               onReasoningStart: () => {
                 startSpinner(`${C.slate}Thinking…${C.reset}`);
@@ -1624,6 +1791,16 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
             if (!finalAnswer && returnedAnswer) finalAnswer = String(returnedAnswer);
             persistQueryDetails('complete');
             if (responsePanelStarted) console.log('');
+            if (agent?.lastCitations?.length > 0) {
+              const citLines = agent.lastCitations.map(c => {
+                const yearStr = c.year ? ` [${c.year}]` : '';
+                const catStr = c.category ? ` • ${c.category}` : '';
+                const srcStr = c.url ? ` • ${c.url}` : ` • ${c.source}`;
+                return `  ${C.gold}[${c.id}]${C.reset} ${C.bold}${c.title}${C.reset}${C.dim}${yearStr}${catStr}${srcStr}${C.reset}`;
+              });
+              console.log(`${C.dim}📖 Sources & Citations (${agent.lastCitations.length}):${C.reset}`);
+              console.log(citLines.join('\n') + '\n');
+            }
           } catch (err) {
             stopSpinner();
             persistQueryDetails(isAbortError(err) ? 'aborted' : 'error', err);
@@ -1641,44 +1818,267 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
           }
         }
 
+async function readStdin() {
+  if (process.stdin.isTTY) return null;
+  return new Promise((resolve) => {
+    let data = '';
+    let hasData = false;
+    const timer = setTimeout(() => {
+      if (!hasData) resolve(null);
+    }, 120);
+    timer.unref();
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      hasData = true;
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      resolve(data.trim() || null);
+    });
+    process.stdin.on('error', () => {
+      clearTimeout(timer);
+      resolve(null);
+    });
+  });
+}
+
+async function executeHeadlessQuery(opts, query) {
+  const startTime = Date.now();
+
+  if (opts.profile) {
+    const p = getProfile(opts.profile);
+    if (!p) {
+      console.error(`Profile "${opts.profile}" not found. Run kiku-agent with /profile list or check available profiles.`);
+      process.exit(3);
+    }
+    opts.provider = opts.provider || p.provider;
+    opts.model = opts.model || p.model;
+    if (p.thinking && !process.argv.includes('--thinking')) opts.thinking = p.thinking;
+  }
+
+  const client = new LLMClient({
+    provider: opts.provider || config.activeProvider,
+    baseUrl: opts.url,
+    apiKey: opts.apiKey,
+    model: opts.model
+  });
+
+  let agent = null;
+  let answer = '';
+  let thinking = '';
+  const recordedTools = [];
+  let executionError = null;
+
+  try {
+    const modelManager = new ModelManager(client, { requestedModel: opts.model || client.model });
+    const modelResolution = await modelManager.resolve({ requestedModel: opts.model || client.model });
+
+    if (!modelResolution.connected || !modelResolution.selectedModel) {
+      throw new Error(modelResolution.error || `Cannot reach model server or no model found for ${client.providerName}`);
+    }
+
+    agent = new KikuAgent({ client, thinkingMode: opts.thinking });
+    await agent.ready();
+
+    answer = await agent.run(query, {
+      onReasoningDelta: (chunk) => {
+        thinking += chunk;
+      },
+      onToolStart: (name, args) => {
+        recordedTools.push({ name, args, status: 'running' });
+      },
+      onToolResult: (name, result, duration) => {
+        const t = recordedTools.find(tool => tool.name === name && tool.status === 'running');
+        if (t) {
+          t.status = 'done';
+          t.result = result;
+          t.duration = duration;
+        } else {
+          recordedTools.push({ name, result, duration, status: 'done' });
+        }
+      }
+    });
+  } catch (err) {
+    executionError = err;
+  }
+
+  const durationMs = Date.now() - startTime;
+  const isError = Boolean(executionError);
+
+  if (opts.output === 'json') {
+    const payload = {
+      version: PACKAGE_VERSION,
+      sessionId: agent?.session?.id || null,
+      query,
+      status: isError ? 'error' : 'success',
+      answer: isError ? '' : (answer || '').trim(),
+      ...(opts.thinking === 'show' ? { thinking: (thinking || '').trim() } : {}),
+      tools: recordedTools.map(t => ({
+        name: t.name,
+        durationMs: t.duration || 0,
+        status: t.status || 'done'
+      })),
+      citations: agent?.lastCitations || [],
+      metrics: {
+        durationMs,
+        iterations: recordedTools.length ? 1 : 0,
+        tokens: agent?.lastTelemetry?.tokens || agent?.session?.lastQueryTokens || {
+          prompt: 0,
+          completion: 0,
+          reasoning: 0,
+          total: 0
+        },
+        costUsd: agent?.lastTelemetry?.costUsd ?? agent?.session?.lastQueryCostUsd ?? 0
+      }
+    };
+    if (isError) {
+      payload.error = executionError.message;
+    }
+    console.log(JSON.stringify(payload, null, 2));
+    process.exit(isError ? 2 : 0);
+  }
+
+
+  if (isError) {
+    console.error(`Error: ${executionError.message}`);
+    process.exit(2);
+  }
+
+  if (opts.thinking === 'show' && thinking.trim()) {
+    console.log(`[Thinking]\n${thinking.trim()}\n`);
+  }
+  console.log((answer || '').trim());
+  if (agent?.lastCitations?.length) {
+    console.log('\n' + formatCitationsBlock(agent.lastCitations, { lang: 'auto' }));
+  }
+  process.exit(0);
+}
+
+async function runWebChatStandalone(opts) {
+  const { startWebChatServer, stopWebChatServer, openBrowser } = await import('../webChatServer.js');
+  const port = opts.port || Number(process.env.PORT_WEB_CHAT) || 3300;
+
+  const client = new LLMClient({
+    provider: opts.provider || config.activeProvider,
+    baseUrl: opts.url,
+    apiKey: opts.apiKey,
+    model: opts.model,
+  });
+  const agent = new KikuAgent({ client, thinkingMode: opts.thinking });
+
+  const res = await startWebChatServer({ port, agent });
+  if (!opts.noOpen) {
+    try { openBrowser(res.url); } catch { /* browser is best-effort */ }
+  }
+
+  if (!opts.plain && !opts.noColor) printWelcomeHero();
+  printRichCard({
+    title: res.alreadyRunning ? 'Web Chatbot Already Running' : 'Kiku Web Chatbot Ready',
+    status: 'connected',
+    lines: [
+      `• URL: ${res.url}`,
+      `• Port: ${res.port}${res.alreadyRunning ? ' (existing server reused)' : ''}`,
+      `• Provider: ${client.providerName || client.provider}  • Model: ${client.model}`,
+      `• Browser: ${opts.noOpen ? 'skipped (--no-open)' : 'opened automatically'}`,
+      '• Press Ctrl+C to stop the server.',
+      '• Endpoints: /  /api/chat  /api/status  /api/v1/timeline',
+    ],
+  });
+
+  const shutdown = async () => {
+    try { await stopWebChatServer(); } catch { /* best-effort */ }
+    try { await agent.endSession?.(); } catch { /* best-effort */ }
+    console.log(`\n  ${C.sakura}Web chatbot stopped • 再见!${C.reset}\n`);
+    process.exit(0);
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+
+  // Keep the process alive until Ctrl+C.
+  await new Promise(() => {});
+}
+
 async function main() {
-          const opts = parseCliArgs();
-
-          if (opts.version) { console.log(PACKAGE_VERSION); process.exit(0); }
-          if (opts.help) { printWelcomeHero(); printHelp(); process.exit(0); }
-          if (opts.showTools) {
-            printWelcomeHero();
-            console.log(`\n  ${C.bold}${C.sakura}Tools (${toolsSchema.length})${C.reset}\n`);
-            for (const [i, t] of toolsSchema.entries()) {
-              console.log(`  ${C.gold}${String(i + 1).padStart(2)}${C.reset} ${C.cyberCyan}${t.function.name}${C.reset} — ${C.dim}${t.function.description.slice(0, 60)}${C.reset}`);
-            }
-            console.log('');
-            process.exit(0);
-          }
+  const opts = parseCliArgs();
 
-          if (opts.showStats) { printWelcomeHero(); const r = await executeTool('get_system_stats', {}); console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+  if (!opts.query && !process.stdin.isTTY) {
+    const pipedInput = await readStdin();
+    if (pipedInput) {
+      opts.query = pipedInput;
+      opts.print = true;
+    }
+  }
 
-          if (opts.query) {
-            printWelcomeHero();
-            const client = new LLMClient({
-              provider: opts.provider || config.activeProvider,
-              baseUrl: opts.url,
-              apiKey: opts.apiKey,
-              model: opts.model
-            });
-            const modelManager = new ModelManager(client, { requestedModel: opts.model || client.model });
-            const modelResolution = await modelManager.resolve({ requestedModel: opts.model || client.model });
-            if (!modelResolution.connected || !modelResolution.selectedModel) {
-              throw new Error(modelResolution.error || `No available chat model found for ${client.providerName}`);
-            }
-            if (modelResolution.usedFallback) {
-              console.log(`  ${C.amber}Model ${modelResolution.requestedModel} is unavailable; using ${modelResolution.selectedModel}.${C.reset}\n`);
-            }
-            console.log(`  ${C.bold}${C.gold}QUERY${C.reset} ${C.white}${opts.query}${C.reset}\n`);
-            const agent = new KikuAgent({ client, thinkingMode: opts.thinking });
-            await executeQueryWithUI(agent, opts.query, agent.session.thinkingMode === 'show', null, 1);
-            process.exit(0);
-          }
+  if (opts.profile) {
+    const p = getProfile(opts.profile);
+    if (!p) {
+      console.error(`Profile "${opts.profile}" not found. Run kiku-agent with /profile list to view available profiles.`);
+      process.exit(3);
+    }
+    opts.provider = opts.provider || p.provider;
+    opts.model = opts.model || p.model;
+    if (p.thinking && !process.argv.includes('--thinking')) {
+      opts.thinking = p.thinking;
+    }
+  }
+
+  if (opts.version) { console.log(PACKAGE_VERSION); process.exit(0); }
+  if (opts.help) {
+    if (!opts.plain && !opts.noColor) printWelcomeHero();
+    printHelp();
+    process.exit(0);
+  }
+  if (opts.showTools) {
+    if (!opts.plain && !opts.noColor) printWelcomeHero();
+    console.log(`\n  ${C.bold}${C.sakura}Tools (${toolsSchema.length})${C.reset}\n`);
+    for (const [i, t] of toolsSchema.entries()) {
+      console.log(`  ${C.gold}${String(i + 1).padStart(2)}${C.reset} ${C.cyberCyan}${t.function.name}${C.reset} — ${C.dim}${t.function.description.slice(0, 60)}${C.reset}`);
+    }
+    console.log('');
+    process.exit(0);
+  }
+
+  if (opts.showStats) {
+    if (!opts.plain && !opts.noColor) printWelcomeHero();
+    const r = await executeTool('get_system_stats', {});
+    console.log(JSON.stringify(r, null, 2));
+    process.exit(0);
+  }
+
+  if (opts.webChat) {
+    await runWebChatStandalone(opts);
+    return;
+  }
+
+  if (opts.query) {
+    if (opts.print || opts.output === 'json') {
+      await executeHeadlessQuery(opts, opts.query);
+      return;
+    }
+
+    printWelcomeHero();
+    const client = new LLMClient({
+      provider: opts.provider || config.activeProvider,
+      baseUrl: opts.url,
+      apiKey: opts.apiKey,
+      model: opts.model
+    });
+    const modelManager = new ModelManager(client, { requestedModel: opts.model || client.model });
+    const modelResolution = await modelManager.resolve({ requestedModel: opts.model || client.model });
+    if (!modelResolution.connected || !modelResolution.selectedModel) {
+      console.error(modelResolution.error || `No available chat model found for ${client.providerName}`);
+      process.exit(2);
+    }
+    if (modelResolution.usedFallback) {
+      console.log(`  ${C.amber}Model ${modelResolution.requestedModel} is unavailable; using ${modelResolution.selectedModel}.${C.reset}\n`);
+    }
+    console.log(`  ${C.bold}${C.gold}QUERY${C.reset} ${C.white}${opts.query}${C.reset}\n`);
+    const agent = new KikuAgent({ client, thinkingMode: opts.thinking });
+    await executeQueryWithUI(agent, opts.query, agent.session.thinkingMode === 'show', null, 1);
+    process.exit(0);
+  }
 
 
           try { process.stdout.write('\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1005l\x1b[?1006l\x1b[?1015l'); } catch { }
@@ -1969,9 +2369,11 @@ async function main() {
             copyQueryDetails: (ref) => copyQueryDetails(ref, agent?.session),
             printWelcome: printWelcomeHero,
             printAd,
-            showTerminalImage: (count = 2) => {
-              const num = Number(count) || 2;
-              const imageLines = terminalGallery.maybeRender(queryCount, { force: true, count: num });
+            showTerminalImage: (options = 2) => {
+              const opts = typeof options === 'number'
+                ? { count: options, force: true }
+                : (typeof options === 'object' && options !== null ? { force: true, ...options } : { count: 2, force: true });
+              const imageLines = terminalGallery.maybeRender(queryCount, opts);
               if (imageLines.length > 0) tuiPrompt.addViewportLines(imageLines);
               return imageLines.length > 0;
             },
@@ -1984,12 +2386,13 @@ async function main() {
             clearQueryQueue: () => { queryQueue.length = 0; },
             getQueryQueueLength: () => queryQueue.length,
             get isProcessing() { return isProcessing; },
+            recordQueryDiagnostics: (details) => recordQueryDiagnostics(details),
             setIsProcessing: (val, label = '') => {
               isProcessing = Boolean(val);
-              if (globalTuiPrompt) {
-                globalTuiPrompt.agentState = label || '';
-                if (label) globalTuiPrompt.agentStateTime = Date.now();
-                globalTuiPrompt.render();
+              if (isProcessing) {
+                startGlobalSpinner(label || 'Processing…');
+              } else {
+                stopGlobalSpinner();
               }
             },
             setAgentState: (label, time = Date.now()) => {
@@ -1998,6 +2401,9 @@ async function main() {
                 globalTuiPrompt.agentStateTime = time;
                 globalTuiPrompt.render();
               }
+              if (label && isProcessing) {
+                startGlobalSpinner();
+              }
             },
           };
 
@@ -2114,20 +2520,27 @@ async function main() {
               const extra = parts.slice(2).join(' ');
 
               let result;
+              activeAbortController = new AbortController();
               try {
                 result = await routeCommand(trimmed, {
                   ...cmdCtx,
+                  signal: activeAbortController.signal,
                   sub,
                   extra,
                   parts,
                 });
               } catch (cmdErr) {
-                printRichCard({
-                  title: 'Command Error',
-                  status: 'error',
-                  lines: [cmdErr.message || String(cmdErr)],
-                });
+                if (!isAbortError(cmdErr)) {
+                  printRichCard({
+                    title: 'Command Error',
+                    status: 'error',
+                    lines: [cmdErr.message || String(cmdErr)],
+                  });
+                }
                 continue;
+              } finally {
+                activeAbortController = null;
+                cmdCtx.setIsProcessing(false);
               }
 
               if (result === 'EXIT') {
@@ -2250,24 +2663,35 @@ async function main() {
           });
         }
 
-process.on('exit', () => {
-          try { globalTuiPrompt?.dispose(); } catch { }
-          exitAlternateScreen();
-        });
-    process.on('uncaughtException', (err) => {
-      try { globalTuiPrompt?.dispose(); } catch { }
-      exitAlternateScreen();
-      console.error(`\n  Uncaught: ${err.message}`);
-      process.exit(1);
-    });
-    process.on('SIGINT', () => {
-      try { globalTuiPrompt?.dispose(); } catch { }
-      exitAlternateScreen();
-      process.exit(130);
-    });
+const currentScriptPath = fileURLToPath(import.meta.url);
+const isDirectRun = process.argv[1] && (
+  process.argv[1] === currentScriptPath ||
+  process.argv[1].endsWith('server/agent/cli.js') ||
+  process.argv[1].endsWith('server\\agent\\cli.js') ||
+  process.argv[1].endsWith('bin/kiku-agent') ||
+  process.argv[1].endsWith('bin\\kiku-agent')
+);
+
+if (isDirectRun) {
+  process.on('exit', () => {
+    try { globalTuiPrompt?.dispose(); } catch { }
+    exitAlternateScreen();
+  });
+  process.on('uncaughtException', (err) => {
+    try { globalTuiPrompt?.dispose(); } catch { }
+    exitAlternateScreen();
+    console.error(`\n  Uncaught: ${err.message}`);
+    process.exit(1);
+  });
+  process.on('SIGINT', () => {
+    try { globalTuiPrompt?.dispose(); } catch { }
+    exitAlternateScreen();
+    process.exit(130);
+  });
 
-    main().catch(err => {
-      exitAlternateScreen();
-      console.error(`\n  ${C.red}Fatal: ${err.message}${C.reset}\n`);
-      process.exit(1);
-    });
+  main().catch(err => {
+    exitAlternateScreen();
+    console.error(`\n  ${C.red}Fatal: ${err.message}${C.reset}\n`);
+    process.exit(1);
+  });
+}