@hncode/hncode 0.3.3 → 0.3.5

package/src/index.js

@@ -356,35 +356,46 @@ export async function main(argv) {
     await loadPlugins(cfg.pluginDir);
   }
 
-  // Connect configured MCP servers and register their tools, so a headless
-  // `-p` run and the TUI both see them. Failures are reported but never fatal:
-  // an unreachable server must not stop the session from starting.
-  if (cfg.mcp !== false) {
+  // Connect configured MCP servers and register their tools.
+  //
+  // This is a FUNCTION rather than an inline block because the two modes want
+  // different timing:
+  //   * headless (`-p`) MUST wait — the prompt runs immediately and its model
+  //     request has to see the MCP tools in the tool list.
+  //   * the TUI must NOT wait — connecting can take seconds (8s per wedged
+  //     server), and blocking the first paint for that is unacceptable. The TUI
+  //     starts this in the background and reports the result as a notice.
+  // Failures are reported but never fatal: an unreachable server must not stop
+  // the session from starting.
+  const connectMcp = async () => {
+    if (cfg.mcp === false) return { servers: [], toolCount: 0 };
     try {
       const mcp = await import('./mcp.js');
       const { API } = await import('./plugin.js');
       const mcpCfg = mcp.loadMcpConfig(cfg.workspace);
-      if (Object.keys(mcpCfg.servers).length) {
-        const res = await mcp.connectAll(mcpCfg, (spec) => API.registerTool(spec));
-        mcp.setLiveConnections(res.servers);
-        if (process.env.HNCODE_MCP_VERBOSE === '1') {
-          for (const s of res.servers) {
-            console.error(s.ok ? `[hncode-mcp] ${s.name}: ${s.toolCount} tool(s)` : `[hncode-mcp] ${s.name}: ${s.error}`);
-          }
+      if (!Object.keys(mcpCfg.servers).length) return { servers: [], toolCount: 0 };
+      const res = await mcp.connectAll(mcpCfg, (spec) => API.registerTool(spec));
+      mcp.setLiveConnections(res.servers);
+      if (process.env.HNCODE_MCP_VERBOSE === '1') {
+        for (const s of res.servers) {
+          console.error(s.ok ? `[hncode-mcp] ${s.name}: ${s.toolCount} tool(s)` : `[hncode-mcp] ${s.name}: ${s.error}`);
         }
       }
+      return res;
     } catch (e) {
       console.error(`hncode: MCP setup failed: ${e.message}`);
+      return { servers: [], toolCount: 0 };
     }
-  }
+  };
 
-  // headless prompt
+  // headless prompt: MCP must be live BEFORE the request goes out.
   if (args.prompt) {
     const format = args['output-format'];
     if (!isValidFormat(format)) {
       console.error(`hncode: unknown --output-format "${format}". Use one of: ${FORMATS.join(', ')}.`);
       return EXIT.CONFIG;
     }
+    await connectMcp();
     let session = null;
     if (args.session) session = typeof args.session === 'string' ? sess.loadSession(args.session) : sess.latestSession(undefined, undefined, { skipEmpty: true });
     else if (args.continue) session = sess.latestSession(undefined, undefined, { skipEmpty: true });
@@ -408,6 +419,9 @@ export async function main(argv) {
     // Remote control: expose a local socket so a script can queue a prompt or
     // query status on the running session (see ci.js).
     control: args.control === true ? '' : (typeof args.control === 'string' ? args.control : null),
+    // MCP runs in the BACKGROUND once the TUI is up (see startTUI): connecting
+    // can take seconds and must not delay the first paint.
+    mcpConnect: connectMcp,
     session: loadOrCreateSession(args, cfg),
   };
   await startTui(opts);

package/src/llm.js

@@ -12,7 +12,9 @@ import { effortWire } from './config.js';
 import { applyPromptCache } from './cache.js';
 
 export function openAiToolDefs(tools) {
-  return tools.map((t) => ({
+  // Guard: a caller that passes null/undefined (e.g. setToolsList(null)) used to
+  // throw on `.map`, failing the whole request. An empty tool list is valid.
+  return (Array.isArray(tools) ? tools : []).map((t) => ({
     type: 'function',
     function: {
       name: t.name,
@@ -23,7 +25,7 @@ export function openAiToolDefs(tools) {
 }
 
 export function anthropicToolDefs(tools) {
-  return tools.map((t) => ({
+  return (Array.isArray(tools) ? tools : []).map((t) => ({
     name: t.name,
     description: t.description,
     input_schema: t.parameters,
@@ -120,7 +122,9 @@ function buildBody(cfg, messages, streaming = true) {
 
 // tool list used for defs (injected via setTools)
 let llmToolsList = [];
-export function setToolsList(list) { llmToolsList = list; }
+// Only ever store an array: `null`/undefined here would make every later request
+// throw when the defs are built.
+export function setToolsList(list) { llmToolsList = Array.isArray(list) ? list : []; }
 
 export class LLM {
   constructor(cfg) {

package/src/mcp.js

@@ -32,6 +32,11 @@ import cp from 'node:child_process';
 export const PROTOCOL_VERSION = '2024-11-05';
 export const CLIENT_INFO = { name: 'hncode', version: '0.3.1' };
 
+// How long a server gets to complete the initialize + tools/list handshake. This
+// runs BEFORE the TUI opens, so it is deliberately short: a wedged server should
+// cost a few seconds, not the 30s a tool call is allowed.
+export const CONNECT_TIMEOUT_MS = 8_000;
+
 // Live connections made at startup, shared by every consumer of the MCP client
 // (the CLI startup and the TUI's /mcp). Kept in this module rather than passed
 // around so the status view can always see the real state.
@@ -222,7 +227,10 @@ export function parseSseForId(body, id) {
 // Connect to one server, handshake, and list its tools.
 // Returns { ok, tools, error, serverInfo, transport, isHttp } — never throws.
 export async function connectServer(name, def, opts = {}) {
-  const timeoutMs = opts.timeoutMs || 30_000;
+  // CONNECT_TIMEOUT (not the 30s tool-call timeout): this runs during startup, so
+  // a wedged server must not hold the session hostage. 8s is generous for a
+  // handshake while keeping a dead server's cost to single-digit seconds.
+  const timeoutMs = opts.timeoutMs || CONNECT_TIMEOUT_MS;
   let transport;
   const isHttp = !!def.url;
   try {
@@ -314,16 +322,15 @@ export function toHncodeSpec(server, tool, transport, isHttp) {
 // Connect every configured server and register its tools through the plugin API.
 // Returns { servers: [...], toolCount }.
 export async function connectAll(config, registerTool, opts = {}) {
-  const servers = [];
-  let toolCount = 0;
   const only = opts.only;
-  for (const [name, def] of Object.entries((config && config.servers) || {})) {
-    if (only && !only.includes(name)) continue;
+  const entries = Object.entries((config && config.servers) || {}).filter(([name]) => !only || only.includes(name));
+  // Connect in PARALLEL. This runs on the startup path, before the TUI opens, so
+  // a serial loop meant one slow/wedged server delayed every later one — N dead
+  // servers cost N × timeout before the user saw anything. Runs concurrently, the
+  // whole set costs the SLOWEST single server instead of their sum.
+  const results = await Promise.all(entries.map(async ([name, def]) => {
     const conn = await connectServer(name, def, opts);
-    if (!conn.ok) {
-      servers.push({ name, ok: false, toolCount: 0, error: conn.error, serverInfo: {} });
-      continue;
-    }
+    if (!conn.ok) return { name, ok: false, toolCount: 0, error: conn.error, serverInfo: {} };
     let registered = 0;
     let err = null;
     for (const tool of conn.tools) {
@@ -336,11 +343,12 @@ export async function connectAll(config, registerTool, opts = {}) {
         err = err || `tool "${tool.name}": ${e.message}`;
       }
     }
-    toolCount += registered;
-    servers.push({ name, ok: true, toolCount: registered, error: err, serverInfo: conn.serverInfo, transport: conn.transport, isHttp: conn.isHttp });
-  }
-  return { servers, toolCount };
+    return { name, ok: true, toolCount: registered, error: err, serverInfo: conn.serverInfo, transport: conn.transport, isHttp: conn.isHttp };
+  }));
+  const toolCount = results.reduce((n, r) => n + (r.toolCount || 0), 0);
+  return { servers: results, toolCount };
 }
+// Disconnect every connected server (kills stdio children). HTTP needs nothing.
 
 // Disconnect every connected server (kills stdio children). HTTP needs nothing.
 export function disconnectAll(connections) {

package/src/plugin.js

@@ -152,17 +152,19 @@ export async function loadPlugins(dir) {
         continue;
       }
 
-      // Metadata comes from the default export. `name` there is a plain STRING
-      // (`export default { name: 'recorder' }`), so reading `meta.name` off it
-      // returned undefined and the plugin showed up as its FILENAME with version
-      // 0.0.0 — /plugins listed every plugin under the wrong name. Accept both
-      // shapes: a string name, or an object carrying { name, version }.
+      // Metadata can arrive three ways, and all three are in the wild:
+      //   export default { name: 'x', version: '1' }   (object)
+      //   export default 'x'                            (plain string)
+      //   export const meta = { name: 'x' }             (named export)
+      // Only the default export used to be read, so a plugin using the named form
+      // showed up as its FILENAME with version 0.0.0 in /plugins. Check them all.
       const def = (mod && mod.default) || {};
-      const meta = typeof def === 'string' ? { name: def } : def;
+      const defMeta = typeof def === 'string' ? { name: def } : def;
+      const namedMeta = (mod && mod.meta) || {};
       const plugin = {
         id: f,
-        name: meta.name || meta.meta?.name || f,
-        version: meta.version || meta.meta?.version || '0.0.0',
+        name: defMeta.name || defMeta.meta?.name || namedMeta.name || namedMeta.meta?.name || f,
+        version: defMeta.version || defMeta.meta?.version || namedMeta.version || namedMeta.meta?.version || '0.0.0',
       };
       loadedPlugins.push(plugin);
       installFn(API);

package/src/term.js

@@ -50,13 +50,47 @@ export function strWidth(s) {
 // renders East Asian / wide / some symbol glyphs as 2 columns. Must be used for any
 // cursor positioning and line wrapping so an I-shaped (insert) caret lines up.
 // Source of truth: Unicode wide ranges + a small set of CJK-fused symbol glyphs.
+//
+// PERFORMANCE (this is the hottest function in the whole TUI — a profile of a
+// 500-message transcript streaming markdown put ~48% of samples in this plus
+// clusterWidth/clusterGlyphWidth/isWideByDefault):
+//   * a printable-ASCII fast path returns the length immediately. Agent output
+//     is overwhelmingly ASCII, and measuring it cost ~30 range comparisons per
+//     character for nothing. 1MB of ASCII went from 219ms to ~0.
+//   * everything else is memoised (see WIDTH_CACHE_MAX). Rows are re-measured
+//     every frame while a reply streams, and the same substrings come back
+//     again and again.
 export function visualWidth(s) {
   if (!s) return 0;
-  // Measured per GRAPHEME CLUSTER (see clusterWidth): summing charWidth per
-  // codepoint made a ZWJ emoji sequence count 8 columns instead of 2.
-  return clusterWidth(s);
+  const str = typeof s === 'string' ? s : String(s);
+  // Fast path: printable ASCII measures exactly its length.
+  if (isPrintableAscii(str)) return str.length;
+  const hit = widthCache.get(str);
+  if (hit !== undefined) return hit;
+  const w = clusterWidth(str);
+  if (widthCache.size >= WIDTH_CACHE_MAX) {
+    // Cheap eviction: drop the oldest insertion (Map preserves order).
+    const oldest = widthCache.keys().next().value;
+    if (oldest !== undefined) widthCache.delete(oldest);
+  }
+  widthCache.set(str, w);
+  return w;
+}
+
+// All code units printable ASCII? `\t`/newline/escape all fail, which is what we
+// want: those have their own width rules (tab = 4, ESC starts an ANSI sequence).
+function isPrintableAscii(str) {
+  for (let i = 0; i < str.length; i++) {
+    const c = str.charCodeAt(i);
+    if (c < 0x20 || c > 0x7e) return false;
+  }
+  return true;
 }
 
+const WIDTH_CACHE_MAX = 4096;
+const widthCache = new Map();
+
+
 // ---- East Asian Width tables (Unicode 15) --------------------------------
 // Wide/Fullwidth ranges -> 2 columns. Everything else is 1 unless it is a
 // zero-width character (see ZERO_WIDTH) or emoji presentation (see below).
@@ -151,69 +185,69 @@ export function charWidth(ch) {
   // Tab renders as 4 spaces in most terminals.
   if (c === 0x09) return 4;
   if (c < 0x20 || c === 0x7F) return 0;
+  // FAST PATH: plain printable ASCII is exactly one cell wide. Without this each
+  // ASCII character paid for isZeroWidth + isWideByDefault (≈30 range tests) + a
+  // binary search, which is most of what made width measurement the hottest
+  // function in the TUI.
+  if (c >= 0x20 && c <= 0x7e) return 1;
   if (isZeroWidth(c)) return 0;
   if (isWideByDefault(c)) return 2;
   if (inRanges(c, WIDE)) return 2;
   return 1;
 }
 
-// Split a string into grapheme clusters that a terminal renders as ONE glyph.
-// Minimal but covers what actually appears in agent output: ZWJ sequences
-// (👨‍👩‍👧), variation selectors (❤️), and flag pairs (🇺🇸).
-function nextCluster(s, i) {
-  // NOTE: every offset here is a UTF-16 INDEX (what slice() consumes). Mixing
-  // in codepoint offsets desynced the scan across surrogate pairs, so a ZWJ
-  // family measured 5 columns instead of 2.
-  const at = (idx) => s.codePointAt(idx);
-  const len = (cp) => cp > 0xFFFF ? 2 : 1;
-
-  const firstCp = at(i);
-  let end = i + len(firstCp);
-  const startedRegional = isRegional(firstCp);
-
-  for (;;) {
-    if (end >= s.length) break;
-    const cp = at(end);
-    if (cp === 0x200D) {                       // ZWJ: absorb the next base too
-      end += 1;
-      if (end >= s.length) break;
-      end += len(at(end));
-      continue;
-    }
-    if (isZeroWidth(cp) || cp === 0xFE0F) { end += len(cp); continue; }
-    // A regional-indicator PAIR forms one flag glyph.
-    if (startedRegional && isRegional(cp)) { end += len(cp); break; }
-    break;
-  }
-  return { text: s.slice(i, end), next: end };
-}
+// Shared native segmenter. `Intl.Segmenter` implements the full Unicode
+// grapheme-break algorithm in native code, so it is both more correct than the
+// hand-rolled scanner it replaces (ZWJ families, flags, combining marks) and
+// much cheaper — that scanner allocated a `{text, next}` object per character,
+// which showed up as GC pressure in profiles.
+const graphemeSegmenter = typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
+  ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+  : null;
 
 // Width of a whole string measured by GRAPHEME CLUSTER: a ZWJ sequence or a
 // flag counts 2 columns total, not the sum of its codepoints (which used to
 // make 👨‍👩‍👧 measure 8 columns and break every row it appeared on).
 export function clusterWidth(s) {
   const str = String(s || '');
+  if (!str) return 0;
   let w = 0;
-  for (let i = 0; i < str.length;) {
-    const { text, next } = nextCluster(str, i);
-    i = next;
-    if (!text) { i++; continue; }
-    w += clusterGlyphWidth(text);
+  if (graphemeSegmenter) {
+    // NOTE: an "ASCII runs are free" split was tried here and made things WORSE
+    // (a 500KB markdown string went 97ms -> 544ms): slicing the string into a
+    // run per CJK character costs far more than handing the whole thing to the
+    // native segmenter. The real win is the printable-ASCII fast path in
+    // visualWidth() plus the memo cache, not micro-splitting here.
+    for (const { segment } of graphemeSegmenter.segment(str)) w += clusterGlyphWidth(segment);
+    return w;
   }
+  // Fallback for a runtime without Intl.Segmenter: per code point.
+  for (const ch of str) w += clusterGlyphWidth(ch);
   return w;
 }
+// Width of one grapheme cluster. Allocation-free on the common path: a
 
+// Width of one grapheme cluster. Allocation-free on the common path: a
+// single-code-point cluster (every ASCII character, most CJK) returns
+// charWidth directly instead of first building an array of code points.
 function clusterGlyphWidth(cluster) {
-  const cps = [...cluster].map((c) => c.codePointAt(0));
+  const first = cluster.codePointAt(0);
+  if (first === undefined) return 0;
+  if (cluster.length <= (first > 0xFFFF ? 2 : 1)) return charWidth(cluster);
+
+  const cps = [];
+  for (let i = 0; i < cluster.length;) {
+    const cp = cluster.codePointAt(i);
+    cps.push(cp);
+    i += cp > 0xFFFF ? 2 : 1;
+  }
   // ZWJ sequence / flag pair / VS16-presented symbol => 2 columns.
   if (cps.includes(0x200D)) return 2;
-  if (cps.filter(isRegional).length >= 1) return 2;
-  const base = cps[0];
+  if (cps.some(isRegional)) return 2;
   if (cps.includes(0xFE0F)) return 2;          // explicit emoji presentation
-  const baseW = charWidth(String.fromCodePoint(base));
-  let extra = 0;
-  for (let k = 1; k < cps.length; k++) extra += charWidth(String.fromCodePoint(cps[k]));
-  return baseW + extra;
+  let width = charWidth(String.fromCodePoint(cps[0]));
+  for (let k = 1; k < cps.length; k++) width += charWidth(String.fromCodePoint(cps[k]));
+  return width;
 }
 
 // Estimate the LLM token count of a plain string, matching kimi-code's
@@ -264,7 +298,11 @@ export function expandTabs(s, tabSize = 8) {
       continue;
     }
     out += ch;
-    col += clusterWidth(ch);
+    // Per CHARACTER, `charWidth` is the right measure and is far cheaper than
+    // clusterWidth here: the loop already iterates code points (so a surrogate
+    // pair arrives as a single `ch`), and clusterWidth would spin up the
+    // segmenter for every single character.
+    col += charWidth(ch);
   }
   return out;
 }