@hncode/hncode 0.5.0 → 0.5.2

package/src/config.js

@@ -388,6 +388,14 @@ const b = baseUrl.replace(/\/+$/, '');
     // "use the built-in SYSTEM_PROMPT". Read from config.toml so it persists
     // across restarts.
     systemPrompt: process.env.HNCODE_SYSTEM_PROMPT || root.system_prompt || '',
+    // The prompt knobs added alongside it, all editable from /settings › Prompt. Separate
+    // keys rather than one blob, because they mean different things: `append` keeps the
+    // built-in prompt and adds to it, `personal` is the user's own standing note, and the
+    // per-mode ones only apply while that mode is on.
+    appendSystemPrompt: process.env.HNCODE_APPEND_SYSTEM_PROMPT || root.append_system_prompt || '',
+    planInstructions: root.plan_instructions || '',
+    focusInstructions: root.focus_instructions || '',
+    swarmInstructions: root.swarm_instructions || '',
     // ---- Web UI daemon -------------------------------------------------------
     // One daemon serves EVERY hncode session on this machine: it holds the fixed
     // port, proxies each session's requests to that session's own loopback
@@ -1146,24 +1154,43 @@ export function effortOptions(cfg, modelKeyName) {
   return ['off', 'on'];
 }
 
+// Token budget for a NAMED grade, on a protocol that wants a number rather than a word.
+//
+// The grades the catalog declares are low/medium/high, and a user may also write their own
+// in config.toml (`efforts = ["xhigh"]`). A grade with no entry here has no honest budget to
+// send, so the field is omitted — the previous code fell back to 8000, which silently gave
+// every unknown grade the same strength as `on` and `medium`.
+const EFFORT_BUDGETS = { low: 2000, medium: 8000, high: 16000, max: 32000 };
+
 // Map a chosen effort to the wire value for the active protocol.
+//
+// `on` means "thinking on", NOT "medium". The two are different requests: a model may
+// support a plain toggle without any graded control, in which case there is no grade to
+// send and inventing one (`medium`) can be rejected outright by the provider. `on` therefore
+// sends the protocol's plain enable, or nothing at all.
 export function effortWire(cfg, effort) {
   if (!effort || effort === 'off') return null;
+  const named = Object.prototype.hasOwnProperty.call(EFFORT_BUDGETS, effort);
+
   if (cfg.protocol === 'anthropic') {
-    const budget = { on: 8000, low: 2000, medium: 8000, high: 16000, max: 32000 }[effort] || 8000;
-    return { thinking: { type: 'enabled', budget_tokens: budget } };
+    // `thinking: { type: 'enabled' }` IS the plain toggle; `budget_tokens` is optional and
+    // only meaningful for a named grade. Omitting it lets the provider pick its own budget,
+    // which is what "on" asked for.
+    return named
+      ? { thinking: { type: 'enabled', budget_tokens: EFFORT_BUDGETS[effort] } }
+      : { thinking: { type: 'enabled' } };
   }
-  // Responses API nests the grade: `reasoning: { effort }`.
-  if (cfg.protocol === 'responses') {
-    const grade = effort === 'on' ? 'medium' : effort;
-    return { reasoning: { effort: grade } };
-  }
-  // OpenAI-compatible: `reasoning_effort`. "on" is not a valid grade, so map it
-  // to "medium"; concrete grades pass through.
-  const grade = effort === 'on' ? 'medium' : effort;
-  return { reasoning_effort: grade };
+
+  // Responses API and the OpenAI-compatible shape both take a GRADE word, and neither has
+  // a value meaning "on". So a named grade passes through, and `on` sends nothing — the
+  // request carries whatever the provider does by default for that model, rather than a
+  // grade the model may not accept.
+  if (!named) return {};
+  if (cfg.protocol === 'responses') return { reasoning: { effort } };
+  return { reasoning_effort: effort };
 }
 
+
 function toTomlLine(k, v) {
   if (typeof v === 'string') return `${k} = "${v.replace(/"/g, '\\"')}"`;
   if (typeof v === 'boolean') return `${k} = ${v}`;

package/src/context-bar.js

@@ -228,10 +228,51 @@ export function formatReadout(used, window, freeCols) {
   return '';
 }
 
-/** 1200 -> `1.2k`, 97000 -> `97.0k`, 3_400_000 -> `3.4M`. */
+/**
+ * A token count as a compact string: `1200` -> `1.2k`, `97000` -> `97k`, `3400000` -> `3.4M`.
+ *
+ * Deliberately the SAME shape `fmtTokensShort` produces for the working row, because both appear
+ * in one frame — the context bar and the live turn counter would otherwise disagree about the same
+ * quantity. Two rules:
+ *
+ *   * one decimal while it carries information, dropped when it is a zero (`97000` is `97k`, not
+ *     `97.0k` — the trailing `.0` is three characters saying nothing);
+ *   * K/M/B/T suffixes, with only the kilo lower-case, so `3.4M` here and `3.4M` on the working row
+ *     read as one vocabulary.
+ *
+ * The previous version kept `.0` and disagreed with the working row on units entirely: it divided
+ * by 1024 where the row divided by 1000, so a 97k context read `94.7k` beside a `97k` turn.
+ */
 export function compactTokens(n) {
-  const v = Number(n) || 0;
-  if (v >= 1e6) return `${(v / 1e6).toFixed(1)}M`;
-  if (v >= 1e3) return `${(v / 1e3).toFixed(1)}k`;
-  return String(Math.round(v));
+  const v = Math.max(0, Math.floor(Number(n) || 0));
+  const units = [
+    { at: 1e12, suffix: 'T' },
+    { at: 1e9, suffix: 'B' },
+    { at: 1e6, suffix: 'M' },
+    { at: 1e3, suffix: 'k' },
+  ];
+  for (let i = 0; i < units.length; i++) {
+    const u = units[i];
+    if (v < u.at) continue;
+    // The identical scaling rule the working row and the /ctx readout use: one decimal below 100,
+    // whole numbers above. Three formatters render token counts into one frame, so a single rule is
+    // the only way `262k` cannot appear beside `262.1k` for the same quantity.
+    const shown = scaleUnit(v / u.at);
+    // Rounding can reach the next unit (`999999` is `1000k`, which is `1m`), and showing `1000k`
+    // makes the reader convert a unit themselves.
+    if (Number(shown) >= 1000 && i > 0) return `${scaleUnit(v / units[i - 1].at)}${units[i - 1].suffix}`;
+    return `${shown}${u.suffix}`;
+  }
+  return String(v);
+}
+
+/**
+ * One unit's worth of a count: `1.2`, `97`, `262`.
+ *
+ * Duplicated from tui.js rather than imported, because `context-bar.js` must stay a leaf module the
+ * TUI can import without a cycle. The two are pinned together by test/context-bar.test.mjs and
+ * test/working-tokens.test.mjs, which assert the same table of values through both.
+ */
+function scaleUnit(v) {
+  return v < 100 ? v.toFixed(1).replace(/\.0$/, '') : String(Math.round(v));
 }

package/src/doctor.js

@@ -77,8 +77,10 @@ function checkConfig(cfg, files) {
   return out;
 }
 
-/** The session directory. A store that cannot be listed is a store whose work is invisible. */
-function checkSessions(files, sessionsDir, limit = 4) {
+/** The session directory. A store that cannot be listed is a store whose work is invisible.
+ *
+ *  Async because it profiles the largest session — see the memory breakdown below. */
+async function checkSessions(files, sessionsDir, limit = 4) {
   const out = [];
   if (!fs.existsSync(sessionsDir)) {
     return [check('session store', 'warn', `${sessionsDir} does not exist yet`,
@@ -110,14 +112,17 @@ function checkSessions(files, sessionsDir, limit = 4) {
   // actually hit: past ~512 MB `JSON.stringify` throws, and every save of that session
   // then fails until the transcript is trimmed.
   const V8_LIMIT = 512 * 1024 * 1024;
-  const big = [];
+  // Sizes of every session, so the memory profile can pick the largest regardless of how
+  // large it is. The `big` list below is filtered to the ones worth WARNING about; the
+  // profiler wants the largest whatever its size, because "this session holds 0.66 MB of
+  // tool arguments" is useful at 4 MB and not only at 500.
+  const sizes = [];
   for (const f of names) {
-    try {
-      const size = fs.statSync(path.join(sessionsDir, f)).size;
-      if (size > 8 * 1024 * 1024) big.push({ f, size });
-    } catch { /* raced away */ }
+    try { sizes.push({ f, size: fs.statSync(path.join(sessionsDir, f)).size }); } catch { /* raced away */ }
   }
-  big.sort((a, b) => b.size - a.size);
+  sizes.sort((a, b) => b.size - a.size);
+  const big = sizes.filter((x) => x.size > 8 * 1024 * 1024);
+
   for (const b of big.slice(0, limit)) {
     const mb = (b.size / 1048576).toFixed(1);
     const sev = b.size > V8_LIMIT * 0.75 ? 'error' : 'warn';
@@ -127,6 +132,38 @@ function checkSessions(files, sessionsDir, limit = 4) {
         : 'Large; loading and saving this session will be slow.'));
   }
 
+  // WHERE THE BYTES ARE in the biggest session, as opposed to how big the file is.
+  //
+  // A file size says nothing actionable: the same 2.5 MB can be a conversation or a
+  // runaway transcript, and only one of those is worth fixing. The breakdown also explains
+  // the file being LARGER than the content it holds — measured on a real session, the
+  // serialised JSON was 2.29 MB while text + tool results + tool arguments summed to
+  // 1.27 MB, so structure and escaping are as expensive as the text.
+  //
+  // Skipped below 1 MB: loading and measuring a session to learn it is small is itself
+  // work, and the finding would be "nothing to see". Deliberately NOT gated on `big` —
+  // that list only holds sessions big enough to warn about, and the breakdown is most
+  // useful on an ordinary one: it is where "half your memory is tool arguments" shows up.
+  if (sizes.length && sizes[0].size > 1024 * 1024) {
+    const top = sizes[0];
+    try {
+      const { loadSession } = await import('./session.js');
+      const { profileMemory, memoryHeadline } = await import('./memory-profile.js');
+      const loaded = loadSession(top.f.replace(/\.json$/, ''));
+      if (loaded) {
+        const profile = profileMemory({ session: loaded });
+        out.push(check('largest session memory', 'info',
+          `${memoryHeadline(profile)}  (${top.f})`,
+          'Text, tool results and tool ARGUMENTS are counted separately; run /memory-profile for the full breakdown.'));
+      }
+    } catch (e) {
+      out.push(check('largest session memory', 'warn', `could not profile ${top.f}: ${e.message}`,
+        'The file was readable by size but would not parse.'));
+    }
+  }
+
+  // Leftover temp files from an interrupted save.
+
   // Leftover temp files from an interrupted save.
   let tmp = [];
   try { tmp = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.tmp')); } catch { /* listed above */ }
@@ -213,6 +250,165 @@ function checkExtensions(files) {
   return out;
 }
 
+/**
+ * Free space where the sessions live.
+ *
+ * A store that fills up is a store that loses work, and the failure is not obviously about
+ * disk: the write fails, the turn is lost, and the error text says ENOENT or EACCES. The
+ * session directory held 608 MB on this machine at one point, which is the shape that walks
+ * a disk to full without anyone noticing.
+ *
+ * `statfs` is used where the platform has it (Node 18.15+). Where it does not, the check is
+ * SKIPPED rather than guessed — a wrong number here is worse than no number.
+ */
+function checkDisk(dir) {
+  if (typeof fs.statfsSync !== 'function') {
+    return [check('disk space', 'info', 'not measurable on this Node/platform', '')];
+  }
+  try {
+    const st = fs.statfsSync(dir);
+    const freeBytes = Number(st.bavail) * Number(st.bsize);
+    const totalBytes = Number(st.blocks) * Number(st.bsize);
+    const freeGb = freeBytes / 1024 ** 3;
+    const totalGb = totalBytes / 1024 ** 3;
+    // Thresholds are deliberately far apart: below 1 GB is an error (a long session can
+    // write hundreds of megabytes), below 5 GB is a warning.
+    const sev = freeGb < 1 ? 'error' : freeGb < 5 ? 'warn' : 'ok';
+    return [check('disk space', sev, `${freeGb.toFixed(1)} GB free of ${totalGb.toFixed(0)} GB`,
+      sev === 'ok' ? ''
+        : 'Saving a session writes the whole transcript, which has reached hundreds of MB. Free space, or point HNCODE_SESSIONS_DIR at another volume.')];
+  } catch (e) {
+    return [check('disk space', 'info', `could not measure: ${e.message}`, '')];
+  }
+}
+
+/**
+ * The workspace's git state.
+ *
+ * Two things here actually break work: a missing `user.name`/`user.email` makes every
+ * commit fail, and an unfinished merge or rebase means the tree is not what the agent
+ * thinks it is. Both are cheap to check and neither surfaced anywhere before.
+ */
+function checkGit(workspace, cp) {
+  if (!workspace) return [];
+  if (!cp) return [check('git', 'info', 'the git module is unavailable', '')];
+  const run = (args) => {
+    try {
+      const r = cp.spawnSync('git', args, { cwd: workspace, encoding: 'utf8', timeout: 5000, windowsHide: true });
+      return r.status === 0 ? String(r.stdout || '').trim() : null;
+    } catch { return null; }
+  };
+  // A workspace that is not a repo is normal, and says nothing about health.
+  const top = run(['rev-parse', '--show-toplevel']);
+  if (!top) return [check('git', 'info', 'not a git repository', '')];
+
+  const out = [];
+  const branch = run(['rev-parse', '--abbrev-ref', 'HEAD']);
+  out.push(check('git', 'ok', `${branch || '(detached)'} in ${top}`));
+
+  // Because `run` pins cwd to the workspace, `config --get` reports the identity that a
+  // commit HERE would actually use — not one inherited from an unrelated directory.
+  // A value that IS set is reported too: only a row in the report distinguishes
+  // "configured" from "the check never ran", and silence reads as success.
+  for (const key of ['user.name', 'user.email']) {
+    const value = run(['config', '--get', key]);
+    if (value) out.push(check(`git ${key}`, 'ok', value));
+    else {
+      out.push(check(`git ${key}`, 'warn', 'not set',
+        `Every commit fails without it. Run: git config --global ${key} "…"`));
+    }
+  }
+  // A half-finished operation changes what the agent is looking at.
+  const gitDir = run(['rev-parse', '--git-dir']);
+  if (gitDir) {
+    const abs = path.isAbsolute(gitDir) ? gitDir : path.join(workspace, gitDir);
+    for (const [file, what] of [['MERGE_HEAD', 'a merge'], ['REBASE_HEAD', 'a rebase'], ['CHERRY_PICK_HEAD', 'a cherry-pick']]) {
+      if (fs.existsSync(path.join(abs, file))) {
+        out.push(check('git in progress', 'warn', `${what} is unfinished`,
+          'The working tree is mid-operation; resolve it before trusting a diff.'));
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * A LIVE end-to-end probe: can this configuration actually complete a turn?
+ *
+ * This is the check a static report cannot make. Everything above reads files; a key that
+ * exists and an endpoint that parses still say nothing about whether a request SUCCEEDS, and
+ * the failures that matter — a revoked key, a wrong base URL, a model the account cannot
+ * reach, a provider that rejects `reasoning_effort` — are all invisible until a real request
+ * is made.
+ *
+ * It costs one request and a handful of tokens, so it is OPT-IN (`/doctor --probe`) and never
+ * part of a plain run. Modelled on jcode's provider-doctor, whose AUTH_CREDENTIAL_LOADED,
+ * NON_STREAMING_CHAT_COMPLETION and STREAMING_CHAT_COMPLETION checks do the same thing.
+ *
+ * The steps are reported as they happen, so a failure names the step that broke rather than
+ * only saying the whole thing did not work.
+ */
+async function probeProvider(cfg, input = {}) {
+  const out = [];
+  const send = input.probeRequest;      // injected by a test; see the note below
+  if (!cfg.provider || !cfg.model) {
+    return [check('probe', 'info', 'skipped: no provider/model configured', '')];
+  }
+  if (!cfg.endpoint) {
+    return [check('probe', 'info', 'skipped: no endpoint', '')];
+  }
+  // A test supplies its own transport. Without one, the real LLM class is used — lazily, so
+  // a plain /doctor never pays to import the provider stack.
+  const doRequest = send || (async () => {
+    const { LLM } = await import('./llm.js');
+    const llm = new LLM(cfg);
+    let text = '';
+    let sawError = null;
+    let usage = null;
+    await llm.request(
+      [{ role: 'user', content: 'Reply with the single word: ok' }],
+      (e) => {
+        if (e.type === 'data') text += e.text;
+        else if (e.type === 'error') sawError = e.error;
+        else if (e.type === 'usage') usage = e.usage;
+      },
+      // One turn, no tools, no streaming: the smallest request that proves the pipeline.
+      { noTools: true, streaming: false },
+    );
+    return { text, error: sawError, usage };
+  });
+
+  const t0 = Date.now();
+  let res;
+  try {
+    res = await doRequest();
+  } catch (e) {
+    return [check('probe', 'error', `request threw: ${(e && e.message) || e}`,
+      'The configuration parses but a request does not complete. Check the key, the endpoint and the network.')];
+  }
+  const ms = Date.now() - t0;
+
+  if (res && res.error) {
+    return [check('probe', 'error', `provider error: ${String(res.error).slice(0, 160)}`,
+      'The key may be revoked, the model unavailable, or the provider rejecting a field in the request.')];
+  }
+  const text = String((res && res.text) || '').trim();
+  if (!text) {
+    // A 200 with no text is the failure mode that looks like success: a reasoning model can
+    // spend its whole budget on `reasoning_content` and return an empty `content`.
+    return [check('probe', 'error', `empty reply in ${ms} ms`,
+      'The request completed but returned no text. If this model always reasons, it may be spending the whole output budget on reasoning.')];
+  }
+  // `usage` comes off the RESULT, not out of the closure that built it — reading the local
+  // inside `doRequest` from here was a ReferenceError on every successful probe.
+  const usage = res && res.usage;
+  out.push(check('probe', 'ok', `replied "${text.slice(0, 20)}" in ${ms} ms`,
+    usage ? `provider reported ${JSON.stringify(usage)}` : ''));
+  return out;
+  return out;
+}
+
+
 /** The terminal. An unknown size or a dumb TERM explains a broken-looking UI. */
 function checkTerminal(env, dims) {
   const out = [];
@@ -224,6 +420,8 @@ function checkTerminal(env, dims) {
   } else {
     out.push(check('TERM', 'ok', `${term}${env.COLORTERM ? ` / ${env.COLORTERM}` : ''}`));
   }
+  // Named distinctly from the TERM check: both used to be called "TERM", so a report with a
+  // small terminal showed the same name twice and read as a duplicated finding.
   if (dims && (dims.cols < 60 || dims.rows < 15)) {
     out.push(check('terminal size', 'warn', `${dims.cols}x${dims.rows}`,
       'Below 60x15 the layout cannot fit; widen the window.'));
@@ -257,7 +455,7 @@ function checkRuntime(node, platform, dirs) {
  * @param {string} [input.node]       process.version, for tests
  * @returns {Array<{name:string,severity:string,detail:string,fix:string}>}
  */
-export function runDoctor(input = {}) {
+export async function runDoctor(input = {}) {
   const cfg = input.cfg || {};
   const env = input.env || process.env;
   const workspace = input.workspace || cfg.workspace || process.cwd();
@@ -278,13 +476,18 @@ export function runDoctor(input = {}) {
     }),
     ...checkConfig(cfg, files),
     ...checkWorkspace(workspace),
-    ...checkSessions(files, sessionsDir),
+    ...(await checkSessions(files, sessionsDir)),
     ...checkErrorLog(files),
     ...checkMcp(input.mcpServers, input.mcpConnections),
     ...checkHooks(files, workspace),
     ...checkExtensions(files),
-    ...checkTerminal(env, input.dims),
+    ...checkDisk(sessionsDir),
+    ...checkGit(workspace, input.childProcess),
+...checkTerminal(env, input.dims),
   ];
+  // The live probe is OPT-IN: it spends a request and a few tokens, so it must never run
+  // as part of a plain /doctor.
+  if (input.probe) results.push(...await probeProvider(cfg, input));
   return results;
 }
 

package/src/git.js

@@ -33,6 +33,10 @@ const GIT_ENV = [
 
 // Run git with args in `cwd`. Returns { ok, stdout, stderr, code, error }.
 // Never throws: a missing git binary or a non-repo is data, not an exception.
+//
+// SYNCHRONOUS, and therefore only for the queries made at STARTUP (the status bar's branch and
+// sha). It blocks the event loop, so an AbortSignal cannot fire during it — use `runGitAsync` for
+// anything a tool call reaches.
 export function runGit(args, cwd, opts = {}) {
   const timeout = opts.timeoutMs || 30_000;
   try {
@@ -53,7 +57,6 @@ export function runGit(args, cwd, opts = {}) {
     return { ok: false, stdout: '', stderr: '', code: null, error: e.message };
   }
 }
-
 export function isRepo(cwd) {
   const r = runGit(['rev-parse', '--is-inside-work-tree'], cwd);
   return r.ok && r.stdout.trim() === 'true';
@@ -436,10 +439,20 @@ export function rebase(cwd, onto) {
 // The async form below runs the same command off the main thread, so the frame
 // draws immediately and the badge fills in when the data arrives.
 
+/**
+ * Run git without blocking the event loop.
+ *
+ * `opts.signal` makes the command interruptible, which is the whole reason a tool call must use this
+ * rather than `runGit`: a synchronous `spawnSync` holds the event loop, so an AbortSignal can never
+ * fire during it — measured, `spawnSync` accepts a `signal` option and ignores it, waiting out the
+ * full timeout. With Esc interrupting a turn, `git status` or `git log` on a large repository would
+ * otherwise freeze the TUI for up to the timeout with no key able to reach it.
+ */
 export function runGitAsync(args, cwd, opts = {}) {
   return new Promise((resolve) => {
     let child;
     const timeout = opts.timeoutMs || 30_000;
+    const signal = opts.signal;
     try {
       child = cp.spawn('git', [...GIT_ENV, ...args], {
         cwd: cwd || process.cwd(),
@@ -453,11 +466,29 @@ export function runGitAsync(args, cwd, opts = {}) {
     let stdout = '';
     let stderr = '';
     let done = false;
-    const finish = (r) => { if (!done) { done = true; clearTimeout(timer); resolve(r); } };
+    const finish = (r) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve(r);
+    };
     const timer = setTimeout(() => {
-      try { child.kill(); } catch {}
-      finish({ ok: false, stdout: '', stderr: '', code: null, error: 'git timed out' });
+      try { child.kill(); } catch { /* already gone */ }
+      // The partial output is returned rather than dropped: it is often still useful, and an empty
+      // string would look like "git had nothing to say" instead of "git was cut short".
+      finish({ ok: false, stdout, stderr, code: null, error: 'git timed out' });
     }, timeout);
+    // `interrupted` is a distinct error from a timeout, so the caller can tell a user's Esc from a
+    // command that hung.
+    const onAbort = () => {
+      try { child.kill(); } catch { /* already gone */ }
+      finish({ ok: false, stdout, stderr, code: null, error: 'interrupted' });
+    };
+    if (signal) {
+      if (signal.aborted) { clearTimeout(timer); onAbort(); return; }
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
     if (child.stdout) child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
     if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
     child.on('error', (e) => finish({ ok: false, stdout: '', stderr: '', code: null, error: e.message }));

package/src/llm.js

@@ -421,6 +421,12 @@ export class LLM {
 
     for (let attempt = 1; attempt <= RETRIES; attempt++) {
       attempts = attempt;
+      // Reset per attempt. Left holding the PREVIOUS attempt's response, a network error on
+      // this attempt left `res` truthy and `!res.ok` true, so the loop reported the old
+      // status and the old body — `LLM request failed (503)` for a connection that was
+      // actually refused, with `lastError` (the real cause) never reaching the user.
+      res = null;
+      lastError = null;
       // Fresh controller per attempt so an abort aborts this specific request
       // and the retry loop stops.
       this.controller = new AbortController();