kiku-agent 1.2.0 → 1.3.1

package/server/agent/cli.js

@@ -5,11 +5,11 @@ import { fileURLToPath } from 'node:url';
 import { stdin as input } from 'node:process';
 import { existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
-import './youtubeAuth.js';
+import './envBootstrap.js';
 import { KikuAgent } from './agentCore.js';
 import { LLMClient, LMStudioClient } from './llmClient.js';
 import { toolsSchema, toolHandlers, executeTool } from './tools.js';
-import { config, CLOUD_PROVIDERS } from './config.js';
+import { config, CLOUD_PROVIDERS, matchModelIdentifier } from './config.js';
 import { audioPlayer } from './audioPlayer.js';
 import { routeCommand } from './commands.js';
 import { eventBus, Events } from './eventBus.js';
@@ -18,6 +18,9 @@ import { sanitizeQuery } from './sanitizer.js';
 import { isAbortError, formatExecutionErrorCard } from './errors.js';
 import { COMMAND_DEFINITIONS, COMMAND_CATEGORIES, SUB_COMMANDS, findCommandDefinition, getCommandDetails } from './commandRegistry.js';
 import { ModelManager } from './modelManager.js';
+import { runVramPreflight, probeLmStudioRuntime, getHardwareTarget } from './vramService.js';
+import { resolveModelConfig } from './modelConfig.js';
+import { estimateVramFootprint, classifyAllocation, formatGb } from '../../src/lib/vram/estimator.js';
 import { PACKAGE_VERSION } from './version.js';
 import { getProfile, listProfiles } from './profiles.js';
 import { formatCitationsBlock } from './citations.js';
@@ -30,7 +33,7 @@ import {
   parseDetailsRequest,
   serializeDetailValue,
   summarizeQueryDetails,
-  copyToClipboard,
+  copyToClipboardAsync,
   getCopyableContent,
 } from './queryDetails.js';
 
@@ -39,7 +42,7 @@ import {
   previousGraphemeBoundary, nextGraphemeBoundary, sliceLineForDisplay,
   printSolidBannerRow, printSolidPanel, formatSolidPanelLines, formatTerminalMarkdown, formatMarkdownLines,
   parseMarkdownTableRow, isMarkdownTableSeparator, expandMarkdownLinks,
-  formatRichCardLines, printRichCard, printRichStatusCard, formatStatusBadge, formatRichTable,
+  formatRichCardLines, printRichCard, printRichStatusCard, formatStatusBadge, formatRichTable, cleanTableCell,
   printWelcomeHero, getWelcomeHeroLines, randomFanName, setupOutputInterception,
   rawWrite, INPUT_PLACEHOLDER, UI_ICONS,
   spinnerFrames, thinkingFrames, createProgressRunner,
@@ -136,6 +139,11 @@ export function parseCliArgs(customArgs = null) {
     webChat: false,
     port: null,
     noOpen: false,
+    force: false,
+    vram: null,
+    eval: null,
+    hub: null,
+    portal: null,
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -157,6 +165,9 @@ export function parseCliArgs(customArgs = null) {
     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 === '--cn-tools' || arg === '--cn' || arg === '--enable-cn-tools') {
+      process.env.KIKU_ENABLE_CN_WEB_TOOLS = 'true';
+    }
     else if (arg === '--web-chat' || arg === '--web') options.webChat = true;
     else if (arg.startsWith('--web-chat=')) {
       options.webChat = true;
@@ -181,6 +192,19 @@ export function parseCliArgs(customArgs = null) {
     }
     else if (arg === '--no-open') options.noOpen = true;
     else if (arg === '--open') options.noOpen = false;
+    else if (arg === '--force') options.force = true;
+    else if (arg === '--vram' || arg === '--gpu') {
+      options.vram = (args[i + 1] && !args[i + 1].startsWith('-')) ? args[++i] : 'live';
+    }
+    else if (arg === '--hub') {
+      options.hub = (args[i + 1] && !args[i + 1].startsWith('-')) ? args[++i] : true;
+    }
+    else if (arg === '--eval') {
+      options.eval = (args[i + 1] && !args[i + 1].startsWith('-')) ? args[++i] : 'ui';
+    }
+    else if (arg === '--portal') {
+      options.portal = (args[i + 1] && !args[i + 1].startsWith('-')) ? args[++i] : 'open';
+    }
     else if (!arg.startsWith('-') && !options.query) { options.query = args.slice(i).join(' '); break; }
     else if (arg.startsWith('-')) {
       console.error(`Unknown option: ${arg}`);
@@ -431,7 +455,7 @@ function printQueryDetails(reference = '') {
   });
 }
 
-function copyQueryDetails(reference = '', session = null) {
+async function copyQueryDetails(reference = '', session = null) {
   const request = parseDetailsRequest(reference);
   if (request.error) {
     printSolidPanel({
@@ -481,7 +505,7 @@ function copyQueryDetails(reference = '', session = null) {
     return false;
   }
 
-  const copied = copyToClipboard(copyable.text);
+  const copied = await copyToClipboardAsync(copyable.text);
   const lineCount = copyable.text.split('\n').length;
   const charCount = copyable.text.length.toLocaleString();
 
@@ -597,7 +621,7 @@ export function printHelp(specificCmd = null) {
   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}${"-P, --provider <name>".padEnd(28)}${C.reset} ${C.white}Select provider (lmstudio, vllm, 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}`);
@@ -607,7 +631,12 @@ export function printHelp(specificCmd = null) {
   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}${"--hub [filter]".padEnd(28)}${C.reset} ${C.white}Show Kiku Master Command Center hub${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--portal [open|api|chat]".padEnd(28)}${C.reset} ${C.white}Open Fan Portal SPA, REST API docs, or Web Chat${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--eval [ui|dash|val]".padEnd(28)}${C.reset} ${C.white}Eval Studio web UI, dashboard, or validation${C.reset}`);
+  helpLines.push(`  ${C.emerald}${"--vram [live|compare|tier]".padEnd(28)}${C.reset} ${C.white}VRAM memory telemetry & hardware classification${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}${"--cn-tools, --cn".padEnd(28)}${C.reset} ${C.white}Enable Chinese web tools (search_bilibili, Baidu)${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}`);
@@ -863,6 +892,22 @@ class InteractiveTuiPrompt {
     if (resolve) resolve(result);
   }
 
+  abortActiveRead(result = null) {
+    if (this.isDisposed || !this.activeResolve || this.isResolving) return false;
+    this.isResolving = true;
+    this._cleanupInput();
+    this.line = '';
+    this.cursor = 0;
+    this.ghostText = '';
+    this.popoverActive = false;
+    this.popoverItems = [];
+    const resolve = this.activeResolve;
+    this.activeResolve = null;
+    this.activeReject = null;
+    resolve(result);
+    return true;
+  }
+
   fail(error) {
     if (this.isResolving) return;
     this.isResolving = true;
@@ -901,7 +946,7 @@ class InteractiveTuiPrompt {
       this.popoverItems = [];
       this.popoverIndex = 0;
       if (!this.isConnected && this.line.length > 0) {
-        this.ghostText = ' (LM Studio offline - type /model reconnect)';
+        this.ghostText = ' (LM Studio offline - will auto-connect once loaded)';
       } else {
         this.ghostText = '';
       }
@@ -924,7 +969,7 @@ class InteractiveTuiPrompt {
     this.screenBuffer.clear(C.bgDark);
 
 
-    const shortModel = (this.modelName || 'gemma-4-e4b').replace(/^.*\//, '');
+    const shortModel = String(this.modelName || 'gemma-4-e4b').split(/[/\\]/).pop();
     const modelLabel = this.isConnected
       ? `${C.gold}✦ ${shortModel}${C.reset}`
       : `${C.roseGlow}✦ OFFLINE${C.reset}`;
@@ -981,7 +1026,7 @@ class InteractiveTuiPrompt {
     } else if (musicStatus) {
       statusStyled = `  ${C.cyberCyan}🎵 ${musicStatus}${C.reset}`;
     } else if (!this.isConnected) {
-      statusStyled = `  ${C.roseGlow}○ OFFLINE${C.reset} ${C.slate}• Start LM Studio & type ${C.cyberCyan}/model reconnect${C.reset}`;
+      statusStyled = `  ${C.roseGlow}○ OFFLINE${C.reset} ${C.slate}• Auto-detecting LM Studio... (${C.cyberCyan}/model reconnect${C.reset}${C.slate})${C.reset}`;
     } else {
       const hkHints = `${C.slate}F1${C.reset}${C.dim} Help${C.reset}  ${C.slate}F3${C.reset}${C.dim} Think${C.reset}  ${C.slate}F4${C.reset}${C.dim} Tools${C.reset}  ${C.slate}F5${C.reset}${C.dim} Copy${C.reset}  ${C.slate}F7${C.reset}${C.dim} Theme${C.reset}`;
       statusStyled = `  ${C.emerald}● READY${C.reset}  ${C.slate}│${C.reset}  ${hkHints}`;
@@ -1038,7 +1083,7 @@ class InteractiveTuiPrompt {
     } else if (!this.line) {
       const defaultPlaceholder = this.isConnected
         ? this.inputPlaceholder
-        : '[AI Offline] Start LM Studio & type /model reconnect (or /help)';
+        : '[AI Offline] Load model in LM Studio to auto-connect (or /help)';
       const placeholder = sliceLineForDisplay(defaultPlaceholder, 0, maxLineWidth).displayLine;
       trailingStyled = `${C.dim}${C.slate}${placeholder}${C.reset}`;
     }
@@ -1548,7 +1593,7 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
             const maxWidth = Math.max(16, getFullWidth() - 8);
             for (let index = 0; index < activeTableHeaders.length; index++) {
               const header = activeTableHeaders[index] || `Column ${index + 1}`;
-              const value = expandMarkdownLinks(cells[index] || '—');
+              const value = expandMarkdownLinks(cleanTableCell(cells[index] || '—'));
               const prefix = `${header}: `;
               const wrapped = wrapText(prefix + value, maxWidth);
               for (const line of wrapped) {
@@ -1757,6 +1802,28 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
                 }
               },
 
+              onSubagentProgress: (event) => {
+                if (!event || !event.type) return;
+                let line = null;
+                if (event.type === 'start') {
+                  line = `   ${C.slate}↳ deep research • ${event.workers || '?'} workers${C.reset}`;
+                } else if (event.type === 'iteration') {
+                  line = `   ${C.slate}↳ iteration ${event.iteration}/${event.maxIterations}${C.reset}`;
+                } else if (event.type === 'tool') {
+                  line = `   ${C.slate}↳ ${C.cyberCyan}${event.name}${C.reset}`;
+                } else if (event.type === 'worker-start') {
+                  line = `   ${C.slate}↳ ${C.bold}${C.white}${event.label || event.id || 'worker'}${C.reset} ${C.dim}started${C.reset}`;
+                } else if (event.type === 'worker-complete') {
+                  line = `   ${C.emerald}↳ ${event.label || event.id || 'worker'} done${C.reset}`;
+                }
+                if (!line) return;
+                if (globalTuiPrompt?.addViewportLines) {
+                  globalTuiPrompt.addViewportLines(line);
+                } else {
+                  console.log(line);
+                }
+              },
+
               onTokenStart: () => {
                 if (globalTuiPrompt) {
                   globalTuiPrompt.agentState = 'Streaming…';
@@ -1783,6 +1850,11 @@ async function executeQueryWithUI(agent, prompt, isThinkingVisible = false, sign
                 }
               },
 
+              onNotice: (text) => {
+                stopSpinner();
+                console.log(`\n  ${C.amber}▸ ${text}${C.reset}`);
+              },
+
               onError: (_err) => {
                 stopSpinner();
               },
@@ -1844,6 +1916,134 @@ async function readStdin() {
   });
 }
 
+function vramZoneTag(zone) {
+  const color = zone === 'GREEN' ? C.emerald : zone === 'YELLOW' ? C.gold : zone === 'RED' ? C.roseGlow : C.slate;
+  return `${color}[${zone}]${C.reset}`;
+}
+
+/**
+ * Startup "Resource Verification" panel: live VRAM usage plus the running
+ * model's estimated footprint, so users immediately see whether the loaded
+ * model is a heavy fit for their card. Informational only — never blocks.
+ */
+async function printResourceVerificationPanel(client) {
+  if (!client || client.provider !== 'lmstudio') return;
+  try {
+    const [hw, runtime] = await Promise.all([
+      getHardwareTarget(),
+      probeLmStudioRuntime(client.baseUrl).catch(() => null),
+    ]);
+    const config = await resolveModelConfig({ modelName: client.model, allowNetwork: false });
+    const cfg = config?.config || null;
+    const runtimeCtx = runtime?.loadedContextLength || cfg?.contextLength || null;
+
+    const estimate = estimateVramFootprint({
+      modelId: client.model,
+      quant: cfg?.quant || 'q4_k_m',
+      paramCount: cfg?.paramCount,
+      paramsB: cfg?.paramsB,
+      layers: cfg?.layers,
+      queryHeads: cfg?.queryHeads,
+      kvHeads: cfg?.kvHeads,
+      headDim: cfg?.headDim,
+      hiddenSize: cfg?.hiddenSize,
+      contextLength: runtimeCtx,
+    });
+
+    const lines = [];
+    let livePct = null;
+    if (hw.available && hw.freeBytes !== null && hw.freeBytes !== undefined) {
+      const usedBytes = Math.max(0, hw.totalBytes - hw.freeBytes);
+      const live = classifyAllocation({ totalBytes: usedBytes, availableBytes: hw.totalBytes });
+      livePct = live.usagePct;
+      lines.push(`${C.gold}GPU (live):${C.reset}   ${C.white}${hw.name}${C.reset} — ${C.bold}${live.usagePct}%${C.reset} ${C.dim}(${formatGb(usedBytes)} / ${formatGb(hw.totalBytes)} used)${C.reset} ${vramZoneTag(live.zone)}`);
+      lines.push(`${C.gold}Free VRAM:${C.reset}   ${C.emerald}${formatGb(hw.freeBytes)}${C.reset}`);
+    } else if (hw.available) {
+      lines.push(`${C.gold}GPU:${C.reset} ${C.white}${hw.name}${C.reset} ${C.dim}(total ${formatGb(hw.totalBytes)} — live usage unavailable)${C.reset}`);
+    } else {
+      lines.push(`${C.gold}GPU:${C.reset} ${C.dim}not detected — VRAM feasibility checks unavailable (KIKU_VRAM_TOTAL_GB can pin a budget)${C.reset}`);
+    }
+
+    const quantLabel = String(runtime?.quantization || estimate.quant || 'q4_k_m').toUpperCase();
+    const paramsLabel = estimate.paramCount ? `${(estimate.paramCount / 1e9).toFixed(1)}B` : '?';
+    const sourceLabel = config?.source === 'gguf' ? 'gguf metadata' : config?.source === 'registry' ? 'registry approx' : config?.source || 'unknown';
+    lines.push(`${C.gold}Model:${C.reset}     ${C.white}${client.model}${C.reset} ${C.dim}(${quantLabel} • ${paramsLabel} params • ${sourceLabel})${C.reset}`);
+
+    if (estimate.totalBytes > 0 && runtimeCtx) {
+      const estCls = hw.available ? classifyAllocation({ totalBytes: estimate.totalBytes, availableBytes: hw.totalBytes }) : null;
+      lines.push(`${C.gold}Estimate:${C.reset}   ${C.bold}${C.white}${formatGb(estimate.totalBytes)}${C.reset} @ ${runtimeCtx.toLocaleString('en-US')} ctx` +
+        (estCls && estCls.zone !== 'UNKNOWN' ? ` ${vramZoneTag(estCls.zone)}` : ''));
+    }
+
+    let verdict = null;
+    if (livePct !== null) {
+      if (livePct <= 80) verdict = `${C.emerald}Resource load is comfortable (${livePct}% VRAM in use).${C.reset}`;
+      else if (livePct <= 95) verdict = `${C.gold}This model is heavy for the card (${livePct}% VRAM in use) — expect slower prefill on long contexts.${C.reset}`;
+      else verdict = `${C.roseGlow}VRAM is critically full (${livePct}%) — lower the context or switch to a smaller quant in LM Studio.${C.reset}`;
+    } else if (estimate.totalBytes > 0 && hw.available) {
+      const estCls = classifyAllocation({ totalBytes: estimate.totalBytes, availableBytes: hw.totalBytes });
+      if (estCls.zone === 'RED') verdict = `${C.gold}Naive estimate exceeds the card — if it loads anyway, sliding-window caching is saving you; otherwise lower ctx/quant.${C.reset}`;
+      else verdict = `${C.dim}Live usage unavailable — estimate says ${estCls.zone}.${C.reset}`;
+    }
+    if (verdict) lines.push(`${C.gold}Verdict:${C.reset}    ${verdict}`);
+    lines.push(`${C.dim}Details: /vram live • /vram compare • /vram ctx${C.reset}`);
+
+    printSolidPanel({ title: 'Resource Verification', lines, headerBg: '\x1b[48;2;48;54;70m', bg: '\x1b[48;2;36;40;52m' });
+  } catch { /* the startup sequence must never break because of this panel */ }
+}
+
+/**
+ * Pre-flight VRAM gate for one-shot runs against local GPU inference.
+ * A RED verdict aborts (exit 4) before the first request is sent unless
+ * --force is supplied — unless the model is already loaded in LM Studio, in
+ * which case live VRAM is authoritative and the gate only warns. Best-effort:
+ * probe failures never block execution.
+ */
+async function runOneShotPreflightGate(client, opts) {
+  if (!client || client.provider !== 'lmstudio') return null;
+  const runtime = await probeLmStudioRuntime(client.baseUrl).catch(() => null);
+  const alreadyLoaded = Boolean(runtime?.reachable && runtime.loadedModel && matchModelIdentifier(client.model, runtime.loadedModel));
+  let preflight = null;
+  try {
+    preflight = await runVramPreflight({
+      model: client.model,
+      force: Boolean(opts?.force),
+      contextLength: runtime?.loadedContextLength || undefined,
+      allowNetwork: false,
+    });
+  } catch {
+    return null;
+  }
+  if (!preflight || preflight.verdict === 'UNKNOWN' || preflight.verdict === 'GREEN') return preflight;
+
+  if (preflight.verdict === 'YELLOW') {
+    if (opts?.verbose) {
+      console.log(`  ${C.gold}[WARN] VRAM pre-flight: ${preflight.message} (${preflight.classification.usagePct}% of ${(preflight.hardware.totalBytes / 1024 ** 3).toFixed(1)} GB)${C.reset}`);
+      for (const suggestion of preflight.remediation || []) {
+        console.log(`  ${C.dim}↳ ${suggestion.description}${C.reset}`);
+      }
+      console.log('');
+    }
+    return preflight;
+  }
+
+  if (alreadyLoaded) {
+    return preflight;
+  }
+
+  console.error(`\n  ${C.roseGlow}${C.bold}ABORT: VRAM pre-flight failed (RED ZONE).${C.reset}`);
+  console.error(`  ${C.white}Estimated footprint ${formatGb(preflight.estimate?.totalBytes)} vs ${formatGb(preflight.hardware?.totalBytes)} available on ${preflight.hardware?.name || 'device'}.${C.reset}`);
+  for (const suggestion of preflight.remediation || []) {
+    console.error(`  ${C.amber}↳ ${suggestion.description}${C.reset}`);
+  }
+  if (opts?.force) {
+    console.error(`  ${C.gold}--force supplied — continuing despite OOM risk.${C.reset}\n`);
+    return preflight;
+  }
+  console.error(`  ${C.dim}Re-run with --force to override (CPU offloading / CUDA OOM risk).${C.reset}\n`);
+  process.exit(4);
+}
+
 async function executeHeadlessQuery(opts, query) {
   const startTime = Date.now();
 
@@ -1879,6 +2079,8 @@ async function executeHeadlessQuery(opts, query) {
       throw new Error(modelResolution.error || `Cannot reach model server or no model found for ${client.providerName}`);
     }
 
+    await runOneShotPreflightGate(client, opts);
+
     agent = new KikuAgent({ client, thinkingMode: opts.thinking });
     await agent.ready();
 
@@ -1958,7 +2160,7 @@ async function executeHeadlessQuery(opts, query) {
 
 async function runWebChatStandalone(opts) {
   const { startWebChatServer, stopWebChatServer, openBrowser } = await import('../webChatServer.js');
-  const port = opts.port || Number(process.env.PORT_WEB_CHAT) || 3300;
+  const port = opts.port || Number(process.env.PORT_WEB_CHAT) || 3002;
 
   const client = new LLMClient({
     provider: opts.provider || config.activeProvider,
@@ -1970,7 +2172,7 @@ async function runWebChatStandalone(opts) {
 
   const res = await startWebChatServer({ port, agent });
   if (!opts.noOpen) {
-    try { openBrowser(res.url); } catch { /* browser is best-effort */ }
+    try { openBrowser(res.url); } catch {  }
   }
 
   if (!opts.plain && !opts.noColor) printWelcomeHero();
@@ -1988,19 +2190,22 @@ async function runWebChatStandalone(opts) {
   });
 
   const shutdown = async () => {
-    try { await stopWebChatServer(); } catch { /* best-effort */ }
-    try { await agent.endSession?.(); } catch { /* best-effort */ }
+    try { await stopWebChatServer(); } catch {  }
+    try { await agent.endSession?.(); } catch {  }
     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() {
+  if (process.argv[2] === 'kiku-mcp' || process.argv[2] === 'mcp-server') {
+    await import('../mcp/stdio.js');
+    return;
+  }
   const opts = parseCliArgs();
 
   if (!opts.query && !process.stdin.isTTY) {
@@ -2052,7 +2257,59 @@ async function main() {
     return;
   }
 
+  if (opts.vram) {
+    const vramSub = typeof opts.vram === 'string' && opts.vram !== 'true' ? opts.vram : 'live';
+    await routeCommand(`/vram ${vramSub}`.trim(), {});
+    process.exit(0);
+  }
+
+  if (opts.hub) {
+    const hubFilter = typeof opts.hub === 'string' && opts.hub !== 'true' ? opts.hub : '';
+    await routeCommand(`/hub ${hubFilter}`.trim(), {});
+    process.exit(0);
+  }
+
+  if (opts.eval) {
+    const evalSub = typeof opts.eval === 'string' && opts.eval !== 'true' ? opts.eval : 'ui';
+    await routeCommand(`/eval ${evalSub}`.trim(), {});
+    process.exit(0);
+  }
+
+  if (opts.portal) {
+    const portalSub = typeof opts.portal === 'string' && opts.portal !== 'true' ? opts.portal : 'open';
+    await routeCommand(`/portal ${portalSub}`.trim(), {});
+    process.exit(0);
+  }
+
   if (opts.query) {
+    const trimmedQuery = opts.query.trim();
+    if (trimmedQuery.startsWith('/')) {
+      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 parts = trimmedQuery.split(/\s+/);
+      const sub = parts[1] || '';
+      const extra = parts.slice(2).join(' ');
+      const cmdCtx = {
+        agent,
+        client,
+        thinkingMode: opts.thinking,
+        setThinkingMode: () => {},
+        theme: getTheme(),
+        setTheme: () => {},
+        audioPlayer,
+        sub,
+        extra,
+        parts,
+      };
+      await routeCommand(trimmedQuery, cmdCtx);
+      process.exit(0);
+    }
+
     if (opts.print || opts.output === 'json') {
       await executeHeadlessQuery(opts, opts.query);
       return;
@@ -2074,7 +2331,7 @@ async function main() {
     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`);
+    await runOneShotPreflightGate(client, opts);
     const agent = new KikuAgent({ client, thinkingMode: opts.thinking });
     await executeQueryWithUI(agent, opts.query, agent.session.thinkingMode === 'show', null, 1);
     process.exit(0);
@@ -2200,7 +2457,7 @@ async function main() {
                     status: 'offline',
                     lines: [
                       'LM Studio is not running. Free-form chat typing is locked to prevent errors.',
-                      'Open LM Studio, load a model (e.g. google/gemma-4-e4b), then type /model reconnect.',
+                      'Open LM Studio and load a model (e.g. google/gemma-4-e4b) — it will auto-connect once loaded.',
                       'Offline commands available: /model reconnect, /help, /provider, /doctor, /theme, /exit',
                     ],
                   });
@@ -2231,7 +2488,7 @@ async function main() {
               status: 'warning',
               lines: [
                 modelResolution.error || 'No chat-capable model loaded',
-                'Load a model in LM Studio, then type /model reconnect.',
+                'Load a model in LM Studio — the CLI will auto-connect as soon as it is loaded in VRAM.',
               ],
             });
             catalogOnlyMode = true;
@@ -2313,6 +2570,10 @@ async function main() {
             });
           }
 
+          if (!catalogOnlyMode) {
+            await printResourceVerificationPanel(client);
+          }
+
           if (agent.restoredMessageCount > 0) {
             const s = agent.session;
             console.log(`\n  ${C.sakura}${C.bold}[SESSION RESTORED]${C.reset} ${C.dim}${s.id} — ${s.messages.length} messages${C.reset}\n`);
@@ -2348,13 +2609,74 @@ async function main() {
             }
           });
 
+          let autoReconnectTimer = null;
+          const stopAutoReconnectWatcher = () => {
+            if (autoReconnectTimer) {
+              clearInterval(autoReconnectTimer);
+              autoReconnectTimer = null;
+            }
+          };
+
+          const startAutoReconnectWatcher = () => {
+            if (autoReconnectTimer) return;
+            autoReconnectTimer = setInterval(async () => {
+              if (!catalogOnlyMode && tuiPrompt.isConnected) {
+                stopAutoReconnectWatcher();
+                return;
+              }
+              if (isProcessing) return;
+
+              try {
+                const resolution = modelManager
+                  ? await modelManager.resolve()
+                  : await client.checkConnection();
+
+                if (resolution?.connected && (resolution.selectedModel || resolution.activeLoadedModel)) {
+                  const detectedModel = resolution.selectedModel || resolution.activeLoadedModel;
+                  catalogOnlyMode = false;
+                  tuiPrompt.isConnected = true;
+                  tuiPrompt.modelName = detectedModel;
+                  tuiPrompt.render();
+                  stopAutoReconnectWatcher();
+
+                  printRichCard({
+                    title: 'Model Auto-Connected',
+                    status: 'connected',
+                    lines: [
+                      `• Provider: ${client.providerName}${client.provider === 'lmstudio' ? ' (Local)' : ''}  • Model: ${detectedModel}`,
+                      '• Auto-detected model in VRAM: chat is ready without requiring /model reconnect.',
+                    ],
+                  });
+                }
+              } catch {
+               
+              }
+            }, 2500);
+
+            if (autoReconnectTimer?.unref) {
+              autoReconnectTimer.unref();
+            }
+          };
+
           const cmdCtx = {
             tuiPrompt,
             agent,
             client,
             baseUrl,
             modelManager,
-            catalogOnlyMode,
+            get catalogOnlyMode() { return catalogOnlyMode; },
+            set catalogOnlyMode(value) {
+              catalogOnlyMode = Boolean(value);
+              if (tuiPrompt) {
+                tuiPrompt.isConnected = !catalogOnlyMode;
+                tuiPrompt.render();
+              }
+              if (catalogOnlyMode) {
+                startAutoReconnectWatcher();
+              } else {
+                stopAutoReconnectWatcher();
+              }
+            },
             setCatalogOnlyMode: value => {
               catalogOnlyMode = Boolean(value);
               if (tuiPrompt) {
@@ -2407,6 +2729,10 @@ async function main() {
             },
           };
 
+          if (catalogOnlyMode) {
+            startAutoReconnectWatcher();
+          }
+
           const triggerQueueProcessing = () => {
             if (isProcessing || queryQueue.length === 0) return;
             isProcessing = true;
@@ -2420,6 +2746,18 @@ async function main() {
                   activeAbortController = new AbortController();
 
                   try {
+                    if (catalogOnlyMode && modelManager) {
+                      try {
+                        const autoProbe = await modelManager.resolve();
+                        if (autoProbe?.connected && (autoProbe.selectedModel || autoProbe.activeLoadedModel)) {
+                          cmdCtx.setCatalogOnlyMode(false);
+                          if (tuiPrompt) {
+                            tuiPrompt.modelName = autoProbe.selectedModel || autoProbe.activeLoadedModel;
+                          }
+                        }
+                      } catch {}
+                    }
+
                     if (catalogOnlyMode) {
                       if (nextItem.prompt.startsWith('@')) {
                         const targetTool = nextItem.prompt.slice(1).split(/\s+/)[0];
@@ -2480,6 +2818,48 @@ async function main() {
             })();
           };
 
+          const IMMEDIATE_COMMAND_NAMES = new Set([
+            '/help', '/?', '/menu', '/commands',
+            '/cancel', '/abort', '/stop',
+            '/version', '/ver', '/v',
+            '/status', '/doctor', '/about', '/info',
+            '/jobs', '/job',
+            '/theme', '/themes',
+            '/ping', '/health',
+            '/system', '/sys', '/os',
+            '/gpu', '/gpus',
+            '/vram', '/resource',
+            '/details', '/detail', '/d',
+            '/copy', '/cp', '/clip', '/clipboard',
+            '/prompt', '/persona', '/sysprompt',
+            '/config', '/settings', '/conf',
+            '/sources', '/src', '/srcs',
+            '/queue',
+            '/ads', '/sponsor', '/ad',
+          ]);
+
+          function isImmediateCommand(rawInput) {
+            const trimmed = (rawInput || '').trim();
+            if (!trimmed.startsWith('/')) return false;
+            const parts = trimmed.split(/\s+/);
+            const base = parts[0].toLowerCase();
+            const sub = (parts[1] || '').toLowerCase();
+            if (IMMEDIATE_COMMAND_NAMES.has(base)) return true;
+            if (base === '/research' && ['status', 'sources', 'cancel', 'last', 'workers'].includes(sub)) return true;
+            if (base === '/subagent' && ['status', 'last', 'tools'].includes(sub)) return true;
+            if (base === '/debate' && ['status', 'last'].includes(sub)) return true;
+            if (base === '/favorites' && ['list', 'show', 'export'].includes(sub)) return true;
+            if (base === '/history' && (!sub || ['list', 'summary', 'search'].includes(sub))) return true;
+            if (base === '/session' && (!sub || ['info', 'list', 'summary'].includes(sub))) return true;
+            if (base === '/lang' && !sub) return true;
+            if (base === '/thinking' && !sub) return true;
+            if (base === '/model' && (!sub || sub === 'status' || sub === 'list' || sub === 'recommend')) return true;
+            if (base === '/provider' && (!sub || sub === 'list' || sub === 'status' || sub === 'info')) return true;
+            if (base === '/mcp' && (!sub || sub === 'status' || sub === 'list' || sub === 'tools')) return true;
+            if (base === '/env' && (!sub || sub === 'get' || sub === 'path')) return true;
+            return false;
+          }
+
           while (true) {
             let rawInput;
 
@@ -2502,10 +2882,38 @@ async function main() {
               const lower = trimmed.toLowerCase();
               if (lower === '/cancel' || lower === '/abort' || (lower === '/stop' && isProcessing)) {
                 cancelActiveQuery();
+                printRichCard({
+                  title: 'Cancelled',
+                  status: 'info',
+                  lines: ['• Active operation cancelled by user.'],
+                });
                 continue;
               }
 
               if (isProcessing) {
+                if (isImmediateCommand(trimmed)) {
+                  const parts = trimmed.split(/\s+/);
+                  const sub = parts[1] || '';
+                  const extra = parts.slice(2).join(' ');
+                  try {
+                    await routeCommand(trimmed, {
+                      ...cmdCtx,
+                      sub,
+                      extra,
+                      parts,
+                    });
+                  } catch (cmdErr) {
+                    if (!isAbortError(cmdErr)) {
+                      printRichCard({
+                        title: 'Command Error',
+                        status: 'error',
+                        lines: [cmdErr.message || String(cmdErr)],
+                      });
+                    }
+                  }
+                  continue;
+                }
+
                 deferredCommands.push(trimmed);
                 printRichCard({
                   title: 'Command Queued',
@@ -2519,45 +2927,71 @@ async function main() {
               const sub = parts[1] || '';
               const extra = parts.slice(2).join(' ');
 
-              let result;
+              console.log(`\n  ${C.dim}❯ ${trimmed}${C.reset}`);
+              cmdCtx.setIsProcessing(true, `Running ${parts[0]}`);
               activeAbortController = new AbortController();
-              try {
-                result = await routeCommand(trimmed, {
-                  ...cmdCtx,
-                  signal: activeAbortController.signal,
-                  sub,
-                  extra,
-                  parts,
-                });
-              } catch (cmdErr) {
-                if (!isAbortError(cmdErr)) {
-                  printRichCard({
-                    title: 'Command Error',
-                    status: 'error',
-                    lines: [cmdErr.message || String(cmdErr)],
+
+              (async () => {
+                try {
+                  const result = await routeCommand(trimmed, {
+                    ...cmdCtx,
+                    signal: activeAbortController.signal,
+                    sub,
+                    extra,
+                    parts,
                   });
+                  if (result === 'EXIT') {
+                    cancelActiveQuery();
+                    activeAbortController = null;
+                    cmdCtx.setIsProcessing(false);
+                    tuiPrompt.abortActiveRead(null);
+                    return;
+                  }
+                  if (result === 'RETRY' && cmdCtx.lastQuery) {
+                    const retryNumber = nextQueryNumber++;
+                    printSolidPanel({
+                      title: `${C.roseGlow}${C.bold}Question ${retryNumber} • Retry${C.reset}`,
+                      lines: wrapText(cmdCtx.lastQuery, getFullWidth() - 8)
+                        .map(wLine => `${C.cyberCyan}❯${C.reset} ${C.white}${wLine}${C.reset}`),
+                      bg: C.bgPanel
+                    });
+                    queryQueue.push({ id: 'q_' + Date.now(), number: retryNumber, prompt: cmdCtx.lastQuery, addedAt: Date.now() });
+                    triggerQueueProcessing();
+                  }
+                } catch (cmdErr) {
+                  if (!isAbortError(cmdErr)) {
+                    printRichCard({
+                      title: 'Command Error',
+                      status: 'error',
+                      lines: [cmdErr.message || String(cmdErr)],
+                    });
+                  }
+                } finally {
+                  activeAbortController = null;
+                  cmdCtx.setIsProcessing(false);
+                  if (deferredCommands.length > 0) {
+                    const nextCmd = deferredCommands.shift();
+                    printRichCard({
+                      title: 'Deferred Command Executed',
+                      status: 'info',
+                      lines: [nextCmd],
+                    });
+                    setTimeout(async () => {
+                      try {
+                        const defParts = nextCmd.split(/\s+/);
+                        await routeCommand(nextCmd, {
+                          ...cmdCtx,
+                          parts: defParts,
+                          sub: defParts[1] || '',
+                          extra: defParts.slice(2).join(' '),
+                        });
+                      } catch (err) {
+                        printRichCard({ title: 'Deferred Command Error', status: 'error', lines: [err.message || String(err)] });
+                      }
+                    }, 10);
+                  }
                 }
-                continue;
-              } finally {
-                activeAbortController = null;
-                cmdCtx.setIsProcessing(false);
-              }
-
-              if (result === 'EXIT') {
-                cancelActiveQuery();
-                break;
-              }
-              if (result === 'RETRY' && cmdCtx.lastQuery) {
-                const retryNumber = nextQueryNumber++;
-                printSolidPanel({
-                  title: `${C.roseGlow}${C.bold}Question ${retryNumber} • Retry${C.reset}`,
-                  lines: wrapText(cmdCtx.lastQuery, getFullWidth() - 8)
-                    .map(wLine => `${C.cyberCyan}❯${C.reset} ${C.white}${wLine}${C.reset}`),
-                  bg: C.bgPanel
-                });
-                queryQueue.push({ id: 'q_' + Date.now(), number: retryNumber, prompt: cmdCtx.lastQuery, addedAt: Date.now() });
-                triggerQueueProcessing();
-              }
+              })();
               continue;
             }
 
@@ -2612,22 +3046,46 @@ async function main() {
               }
 
            
-              printSolidPanel({
-                title: 'AI Chat Locked • LM Studio Offline',
-                lines: [
-                  `${C.bold}${C.amber}LM Studio is not running or connected.${C.reset}`,
-                  `${C.white}Chat query typing is disabled until the AI server is active.${C.reset}`,
-                  '',
-                  `${C.bold}${C.white}How to unlock & connect:${C.reset}`,
-                  `  1. Open ${C.cyberCyan}LM Studio${C.reset} on your computer`,
-                  `  2. Load model ${C.gold}${opts.model || client.model || 'google/gemma-4-e4b'}${C.reset} and ensure the local server is running (port 1234)`,
-                  `  3. Type ${C.cyberCyan}/model reconnect${C.reset} in this terminal (or type ${C.cyberCyan}reconnect${C.reset})`,
-                  '',
-                  `${C.dim}Offline commands available: /model reconnect, /help, /provider, /doctor, /theme, /exit${C.reset}`,
-                ],
-                bg: C.bgPanel,
-              });
-              continue;
+             
+              try {
+                const autoProbe = modelManager
+                  ? await modelManager.resolve()
+                  : await client.checkConnection();
+                if (autoProbe?.connected && (autoProbe.selectedModel || autoProbe.activeLoadedModel)) {
+                  catalogOnlyMode = false;
+                  tuiPrompt.isConnected = true;
+                  tuiPrompt.modelName = autoProbe.selectedModel || autoProbe.activeLoadedModel;
+                  tuiPrompt.render();
+                  stopAutoReconnectWatcher();
+                  printRichCard({
+                    title: 'Model Auto-Connected',
+                    status: 'connected',
+                    lines: [
+                      `• Provider: ${client.providerName}${client.provider === 'lmstudio' ? ' (Local)' : ''}  • Model: ${tuiPrompt.modelName}`,
+                      '• Loaded model detected in VRAM: chat typing unlocked.',
+                    ],
+                  });
+                }
+              } catch {}
+
+              if (catalogOnlyMode || !tuiPrompt.isConnected) {
+                printSolidPanel({
+                  title: 'AI Chat Locked • LM Studio Offline',
+                  lines: [
+                    `${C.bold}${C.amber}LM Studio is not running or connected.${C.reset}`,
+                    `${C.white}Chat query typing is disabled until the AI server is active.${C.reset}`,
+                    '',
+                    `${C.bold}${C.white}How to unlock & connect:${C.reset}`,
+                    `  1. Open ${C.cyberCyan}LM Studio${C.reset} on your computer`,
+                    `  2. Load model ${C.gold}${opts.model || client.model || 'google/gemma-4-e4b'}${C.reset} and ensure the local server is running (port 1234)`,
+                    `  3. The agent will auto-connect automatically (or type ${C.cyberCyan}/model reconnect${C.reset})`,
+                    '',
+                    `${C.dim}Offline commands available: /model reconnect, /help, /provider, /doctor, /theme, /exit${C.reset}`,
+                  ],
+                  bg: C.bgPanel,
+                });
+                continue;
+              }
             }
 
             const { sanitized, warnings } = sanitizeQuery(trimmed);
@@ -2653,6 +3111,7 @@ async function main() {
             triggerQueueProcessing();
           }
 
+          stopAutoReconnectWatcher();
           if (globalTuiPrompt) {
             globalTuiPrompt.dispose();
             globalTuiPrompt = null;