@hncode/hncode 0.1.0

package/src/colors.js

@@ -0,0 +1,149 @@
+// Cyan-blue visual theme for hncode. Adapts to the terminal's color depth:
+// uses true-color when available, 256/16-color fallbacks otherwise.
+
+function colorDepth() {
+  try { return process.stdout.getColorDepth?.() || 0; } catch { return 0; }
+}
+const DEPTH = colorDepth();
+export const TRUECOLOR = DEPTH >= 24 || process.env.COLORTERM === 'truecolor' || /^xterm.*-256color$|.*-truecolor$/.test(process.env.TERM || '');
+
+function rgb(r, g, b) { return TRUECOLOR ? `\x1b[38;2;${r};${g};${b}m` : `\x1b[38;5;${ansi256(r, g, b)}m`; }
+function brgb(r, g, b) { return TRUECOLOR ? `\x1b[48;2;${r};${g};${b}m` : `\x1b[48;5;${ansi256(r, g, b)}m`; }
+
+// Quantize a truecolor triple to the nearest 256-color xterm index.
+function ansi256(r, g, b) {
+  const ri = Math.round(r / 51), gi = Math.round(g / 51), bi = Math.round(b / 51);
+  if (ri === gi && gi === bi) {
+    if (ri === 0) return 16;
+    if (ri === 255 / 51) return 232 + ri;
+    return 232 + ri; // grayscale ramp
+  }
+  return 16 + 36 * ri + 6 * gi + bi;
+}
+
+// Brand: cyan-blue (青蓝色).
+export const TEAL = rgb(0, 184, 219);     // 青蓝
+export const CYAN = rgb(0, 215, 255);
+export const BLUE = rgb(66, 135, 245);
+export const FG = TEAL;                   // primary fg
+export const BG = rgb(0, 18, 26);
+export const BORDER = rgb(70, 130, 180);
+
+// Named accent colours per theme. `auto` keeps the brand cyan-blue and lets the
+// terminal's own palette show through for everything else; `dark`/`light` pick
+// accent triples that stay readable on that background.
+const THEMES = {
+  auto: { teal: [0, 184, 219], cyan: [0, 215, 255], blue: [66, 135, 245], border: [70, 130, 180], hover: [190, 245, 255] },
+  dark: { teal: [0, 200, 230], cyan: [90, 225, 255], blue: [90, 150, 255], border: [80, 140, 190], hover: [190, 245, 255] },
+  light: { teal: [0, 120, 160], cyan: [0, 140, 200], blue: [40, 90, 200], border: [120, 160, 200], hover: [0, 80, 110] },
+};
+export const THEME_NAMES = Object.keys(THEMES);
+
+export const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  muted: '\x1b[90m',
+  teal: TEAL,
+  cyan: CYAN,
+  blue: BLUE,
+  fg: FG,
+  bg: BG,
+  bgTeal: brgb(0, 184, 219),
+  bgDim: brgb(12, 24, 30),
+  bgPanel: TRUECOLOR ? '\x1b[48;5;236m' : '\x1b[48;5;236m',
+  border: BORDER,
+  red: '\x1b[91m',
+  green: '\x1b[92m',
+  yellow: '\x1b[93m',
+  magenta: '\x1b[95m',
+  gray: '\x1b[90m',
+  white: '\x1b[97m',
+  orange: TRUECOLOR ? rgb(255, 140, 0) : '\x1b[38;5;208m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  // Selection highlight (mouse text selection) and the scrollbar gutter.
+  // Selection uses a dark teal background so white text stays readable.
+  selBg: TRUECOLOR ? brgb(0, 70, 84) : '\x1b[48;5;23m', // Original dark cyan background
+  scrollTrack: '\x1b[90m',          // dim gutter
+  scrollThumb: TRUECOLOR ? rgb(0, 184, 219) : '\x1b[38;5;37m', // brand cyan-blue
+  // Scrollbar interaction states. hover: a touch whiter/brighter than the brand
+  // colour; active (pressed/dragging): a touch darker. Idle returns to
+  // scrollThumb (the brand colour) — the caller swaps back automatically.
+  scrollThumbHover: TRUECOLOR ? rgb(120, 226, 245) : '\x1b[38;5;123m',
+  scrollThumbActive: TRUECOLOR ? rgb(0, 140, 168) : '\x1b[38;5;31m',
+  // Hover highlight for clickable rows (menu items, picker options, form
+  // fields, composer rows). An explicit bright foreground + BOLD rather than a
+  // bare BOLD: BOLD only brightens the 16-colour palette (it does nothing to a
+  // true-color row), which is why hover used to be invisible on most rows.
+  // tintRange() re-applies this so the row's own SGR codes cannot cancel it.
+  hover: '\x1b[1m' + rgb(190, 245, 255),
+};
+
+export function style(text, ...codes) {
+  return codes.join('') + text + '\x1b[0m';
+}
+
+// Linearly interpolate between two RGB triples and return an ANSI colour string.
+// Used for the pulsing Working indicator (orange pulses to a brighter/darker
+// shade over a 2s cycle).
+export function lerpColor(r1, g1, b1, r2, g2, b2, t) {
+  const ti = Math.max(0, Math.min(1, t));
+  const r = Math.round(r1 + (r2 - r1) * ti);
+  const g = Math.round(g1 + (g2 - g1) * ti);
+  const b = Math.round(b1 + (b2 - b1) * ti);
+  return rgb(r, g, b);
+}
+
+// Apply a named theme IN PLACE. `C` is a module-level object and ESM imports are
+// live bindings, so mutating its properties here changes the colours everywhere
+// without re-importing. Returns true when the name was recognised.
+export function setTheme(name) {
+  const t = THEMES[name];
+  if (!t) return false;
+  C.teal = rgb(...t.teal);
+  C.fg = C.teal;
+  C.cyan = rgb(...t.cyan);
+  C.blue = rgb(...t.blue);
+  C.border = rgb(...t.border);
+  C.bgTeal = brgb(...t.teal);
+  // Hover stays visible on this theme's background (bright on dark, dark on light).
+  C.hover = '\x1b[1m' + rgb(...(t.hover || [190, 245, 255]));
+  return true;
+}
+
+export function clearScreen() {
+  return '\x1b[3J\x1b[H\x1b[2J';
+}
+export function eraseLine() {
+  return '\x1b[2K';
+}
+export function eraseScreen() {
+  return '\x1b[2J';
+}
+export function moveTo(r, c) {
+  return `\x1b[${r + 1};${c + 1}H`;
+}
+export function cursorUp(n) { return `\x1b[${n}A`; }
+export function cursorDown(n) { return `\x1b[${n}B`; }
+export function cursorLeft(n) { return `\x1b[${n}D`; }
+export function cursorForward(n) { return `\x1b[${n}C`; }
+export function hideCursor() { return '\x1b[?25l'; }
+export function showCursor() { return '\x1b[?25h'; }
+// Cursor shape: terminals accept DECSCUSR — 2 = block, 4 = underline, 6 = bar(I-beam);
+// 1/3/5 = blinking variants. Force a solid block cursor so positioning is always exact
+// and unaffected by I-beam alignment.
+export function blockCursor() { return '\x1b[2 q'; }
+export function underlineCursor() { return '\x1b[4 q'; }
+export function barCursor() { return '\x1b[6 q'; }
+export function alternateScreen(on) { return on ? '\x1b[?1049h' : '\x1b[?1049l'; }
+export function setScrollRegion(top, bottom) {
+  if (process.platform === 'win32') return ''; // win TTY scroll regions are unreliable
+  return `\x1b[${top + 1};${bottom + 1}r`;
+}
+export function resetScrollRegion() {
+  return '\x1b[r';
+}
+export function setBracketed(on) {
+  return `\x1b[?2004h${on ? '' : ''}`; // placeholder; real impl toggles bracketed paste
+}

package/src/config.js

@@ -0,0 +1,533 @@
+// hncode configuration — fully independent of kimi-code-cli.
+// Loads ONLY ~/.hncode/config.toml (plus HNCODE_* env overrides). It does NOT
+// read ~/.kimi-code/config.toml; hncode and kimi-code are separate products.
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { parse } from './toml.js';
+
+const home = os.homedir();
+
+export const DEFAULTS = {
+  model: '',
+  provider: '',
+  baseUrl: '',
+  apiKey: '',
+  protocol: 'openai',
+  // Fallback context window when neither config nor /v1/models provides one.
+  maxContextTokens: 512000,
+  maxOutputTokens: 4096,
+  reasoning: false,
+  workspace: process.cwd(),
+  allowExternal: false,
+};
+
+// Provider/model catalog upstream — the same source kimi-code uses. Fetched by
+// `/provider` → Add so the user can pick a known provider (with its base_url)
+// or type a custom one. Shape: { [providerId]: { id, name, api, doc, env,
+// models: { [modelId]: { id, name, limit: { context, output }, reasoning, … } } } }.
+export const MODELS_DEV_URL = 'https://models.dev/api.json';
+let catalogCache = null;
+let catalogInFlight = null;
+const CATALOG_TTL_MS = 10 * 60 * 1000;
+let catalogFetchedAt = 0;
+
+// Fetch (and memoize) the models.dev catalog. Returns null on failure.
+export async function fetchCatalog() {
+  const now = Date.now();
+  if (catalogCache && now - catalogFetchedAt < CATALOG_TTL_MS) return catalogCache;
+  if (catalogInFlight) return catalogInFlight;
+  catalogInFlight = (async () => {
+    try {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 15000);
+      const res = await fetch(MODELS_DEV_URL, { signal: ctrl.signal });
+      clearTimeout(timer);
+      if (!res.ok) return null;
+      const json = await res.json();
+      if (json && typeof json === 'object') {
+        catalogCache = json;
+        catalogFetchedAt = Date.now();
+        return json;
+      }
+      return null;
+    } catch { return null; }
+    finally { catalogInFlight = null; }
+  })();
+  return catalogInFlight;
+}
+
+export function hncodeConfigFile() {
+  return process.env.HNCODE_CONFIG || path.join(home, '.hncode', 'config.toml');
+}
+
+function loadBaseToml() {
+  // Only hncode's own config file participates.
+  const f = hncodeConfigFile();
+  let base = {};
+  try {
+    if (fs.statSync(f).isFile()) base = parse(fs.readFileSync(f, 'utf8'));
+  } catch (e) {
+    if (e.code !== 'ENOENT') console.error(`hncode: failed to parse ${f}: ${e.message}`);
+  }
+  return base;
+}
+
+export function resolveConfig() {
+  const root = loadBaseToml() || {};
+
+  const providers = root.providers || {};
+  const models = root.models || {};
+  let model = process.env.HNCODE_MODEL || root.model || root.default_model || DEFAULTS.model;
+  // No hard-coded provider: fall back to the first one the user configured.
+  let providerName = process.env.HNCODE_PROVIDER || root.provider || Object.keys(providers)[0] || DEFAULTS.provider;
+  // If no model was named but models exist, adopt the first one under the
+  // active provider (so the status line always has a model to show).
+  if (!model) {
+    const first = Object.keys(models).find((k) => (models[k].provider || '') === providerName)
+      || Object.keys(models)[0];
+    if (first) model = first;
+  }
+
+  let baseUrl = process.env.HNCODE_BASE_URL || root.base_url || root.baseUrl || '';
+  let apiKey = process.env.HNCODE_API_KEY || root.api_key || root.apiKey || '';
+  let protocol = process.env.HNCODE_PROTOCOL || root.protocol || '';
+  // The model actually sent to the API: the [models.*] entry's `model` field
+  // when the key names a pool entry, otherwise the literal name.
+  const modelEntry = models[model] || {};
+  let innerModel = bareModelId(modelEntry.provider || providerName, model, modelEntry);
+  
+  // A [models.*] entry names its own provider; honour it.
+  if (modelEntry.provider) providerName = modelEntry.provider;
+
+  // Optional provider sub-tables: [providers.NAME] base_url / api_key / protocol.
+  const prov = providers[providerName];
+  if (prov) {
+    // Provider sub-table supplements env/root; an explicit HNCODE_* env var
+    // always wins, otherwise the provider table fills in the gaps it declares.
+    baseUrl = process.env.HNCODE_BASE_URL || (prov.base_url || prov.baseUrl) || baseUrl;
+    apiKey = process.env.HNCODE_API_KEY || (prov.api_key || prov.apiKey) || apiKey;
+    protocol = process.env.HNCODE_PROTOCOL || (prov.protocol) || protocol;
+    innerModel = prov.model || innerModel;
+  }
+  protocol = protocol || DEFAULTS.protocol;
+
+  // The base URL is used EXACTLY as configured — we only append the API path.
+  // (No `/v1` is injected: if the user's base ends in /v1, the result is
+  // `<base>/chat/completions`; if it doesn't, it's `<base>/chat/completions` too.)
+  const b = baseUrl.replace(/\/+$/, '');
+  const endpoint = protocol === 'anthropic' ? `${b}/messages` : `${b}/chat/completions`;
+
+  // Context window: an explicit env/root override wins, then the model's own
+  // `contextLength` (discovered from the provider's /v1/models), then the
+  // default. This is what stops every model from being pinned to 128k.
+  const overrideContext = process.env.HNCODE_MAX_CONTEXT || root.max_context_size || root.max_context_tokens;
+  const modelContext = Number(modelEntry.contextLength || modelEntry.context_length || modelEntry.max_context_size || 0);
+  const maxContext = Number(overrideContext || modelContext || DEFAULTS.maxContextTokens);
+  const maxOutput = Number(process.env.HNCODE_MAX_OUTPUT || root.max_output_size || DEFAULTS.maxOutputTokens);
+  const reasoning = process.env.HNCODE_REASONING ? /^(1|true|yes)$/i.test(process.env.HNCODE_REASONING) : !!root.reasoning;
+  const allowExternal = process.env.HNCODE_ALLOW_EXTERNAL === '1' || !!root.tool_allow_external_paths;
+
+  return {
+    model, provider: providerName, innerModel,
+    baseUrl: b, endpoint, apiKey, protocol,
+    maxContextTokens: maxContext, maxOutputTokens: maxOutput, reasoning,
+    workspace: process.env.HNCODE_WORKSPACE || root.workspace || DEFAULTS.workspace,
+    allowExternal,
+    // A user-supplied system prompt (set via /set-system-prompt). Empty means
+    // "use the built-in SYSTEM_PROMPT". Read from config.toml so it persists
+    // across restarts.
+    systemPrompt: process.env.HNCODE_SYSTEM_PROMPT || root.system_prompt || '',
+    // CALM MODE (/calm-mode): persisted boolean. When true an instruction is
+    // appended to the system prompt to suppress narration.
+    calmMode: process.env.HNCODE_CALM_MODE
+      ? /^(1|true|yes|on)$/i.test(process.env.HNCODE_CALM_MODE)
+      // Backwards-compat: read legacy cool_mode key if calm_mode is not set.
+      : (root.calm_mode === true || root.calm_mode === 'true'
+         || root.cool_mode === true || root.cool_mode === 'true'),
+    // Plugin directory (default: ~/.hncode/plugins). Set to "" or "false" to
+    // disable plugin loading entirely.
+    pluginDir: process.env.HNCODE_PLUGINS || root.plugins_dir || '',
+    raw: root,
+  };
+}
+
+export function saveConfig(overlay) {
+  const dir = hncodeConfigFile();
+  let out = '';
+  for (const [k, v] of Object.entries(overlay)) out += toTomlLine(k, v) + '\n';
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  
+  // Check if file exists and has content
+  try {
+    if (fs.statSync(dir).isFile()) {
+      const existing = fs.readFileSync(dir, 'utf8');
+      if (existing.trim().length > 0) {
+        // Append to existing config instead of overwriting
+        fs.writeFileSync(dir, existing + '\n' + out, 'utf8');
+        return dir;
+      }
+    }
+  } catch {}
+  
+  // New file or empty file
+  fs.writeFileSync(dir, out, 'utf8');
+  return dir;
+}
+
+// Persist a top-level string key in config.toml, replacing any previous value.
+// Used by /set-system-prompt. Multi-line values are written as a TOML MULTI-LINE
+// BASIC STRING ("""…"""), which keeps newlines readable and means the editor can
+// round-trip a prompt that contains them. An empty value REMOVES the key, so the
+// built-in prompt takes over again.
+export function setConfigString(key, value) {
+  const file = hncodeConfigFile();
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { /* new file */ }
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let skipping = false;          // inside a multi-line value we are dropping
+  let replaced = false;
+  const keyRe = new RegExp('^\\s*' + escapeRe(key) + '\\s*=');
+  // Track the index of the first table header — new root-level keys must be
+  // inserted BEFORE any [table] section, or TOML assigns them to the last table.
+  let firstTableIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+    if (skipping) {
+      // A multi-line basic string ends at an unescaped """.
+      if (/"""\s*$/.test(ln) || /'''\s*$/.test(ln)) skipping = false;
+      continue;
+    }
+    // Detect a TOML table header line like [foo] or [foo.bar] at column 0.
+    if (/^\[/.test(ln) && firstTableIdx < 0) firstTableIdx = out.length;
+    if (keyRe.test(ln)) {
+      // Drop this key's line, and its body if it opens a multi-line string.
+      const rest = ln.slice(ln.indexOf('=') + 1).trim();
+      const opensMultiline = /^"""|^'''/.test(rest) && !/^"""[\s\S]*"""\s*$/.test(rest);
+      if (opensMultiline) skipping = true;
+      if (!replaced && value !== '' && value != null) {
+        out.push(...renderTomlString(key, String(value)));
+        replaced = true;
+      }
+      continue;
+    }
+    out.push(ln);
+  }
+  while (out.length && out[out.length - 1].trim() === '') out.pop();
+  if (!replaced && value !== '' && value != null) {
+    // Insert new root-level keys BEFORE the first [table] section so they
+    // are parsed as root keys, not assigned to a table.
+    const rendered = renderTomlString(key, String(value));
+    if (firstTableIdx >= 0) {
+      out.splice(firstTableIdx, 0, '', ...rendered);
+    } else {
+      out.push('');
+      out.push(...rendered);
+    }
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, out.join('\n') + (out.length ? '\n' : ''), 'utf8');
+  return file;
+}
+
+// Render `key = <value>` as TOML. Uses a multi-line basic string when the value
+// contains newlines (readable, and TOML-valid), a plain one otherwise.
+function renderTomlString(key, value) {
+  if (value.includes('\n')) {
+    // Inside """…""" a backslash must be escaped; quotes are fine unless tripled.
+    const body = value.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
+    return [`${key} = """`, ...body.split('\n'), '"""'];
+  }
+  return [`${key} = "${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`];
+}
+
+// Append (or replace) a [providers.<name>] table in config.toml without
+// clobbering unrelated content. Used by /provider's "Add provider…" flow.
+export function addProvider(name, { base_url, api_key, protocol } = {}) {
+  const file = hncodeConfigFile();
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { /* new file */ }
+  const lines = text.split(/\r?\n/);
+  // drop any existing [providers.<name>] block (and its key lines) so we replace it
+  const out = [];
+  let skipping = false;
+  for (const ln of lines) {
+    const m = /^\s*\[providers\.([^\]]+)\]\s*$/.exec(ln);
+    if (m) { skipping = m[1] === name; if (skipping) continue; }
+    else if (/^\s*\[/.test(ln)) skipping = false;
+    if (!skipping) out.push(ln);
+  }
+  while (out.length && out[out.length - 1].trim() === '') out.pop();
+  out.push('');
+  out.push(`[providers.${name}]`);
+  if (base_url) out.push(`base_url = "${String(base_url).replace(/"/g, '\\"')}"`);
+  if (api_key) out.push(`api_key = "${String(api_key).replace(/"/g, '\\"')}"`);
+  if (protocol) out.push(`protocol = "${String(protocol).replace(/"/g, '\\"')}"`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, out.join('\n') + '\n', 'utf8');
+  return file;
+}
+
+// Remove a [providers.<name>] table (and its key lines) from config.toml, plus
+// every [models."<name>/..."] entry that belongs to it — otherwise /model keeps
+// listing the deleted provider's models.
+export function removeProvider(name) {
+  const file = hncodeConfigFile();
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return file; }
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let skipping = false;
+  // A models key is `[models."provider/modelId"]`; match the provider prefix.
+  const modelRe = /^\s*\[models\."([^"]+)"\]\s*$/;
+  for (const ln of lines) {
+    const pm = /^\s*\[providers\.([^\]]+)\]\s*$/.exec(ln);
+    if (pm) { skipping = pm[1] === name; if (skipping) continue; }
+    const mm = modelRe.exec(ln);
+    if (mm) {
+      // The model key starts with `<provider>/`; skip it if it is this provider's.
+      const keyProvider = mm[1].split('/')[0];
+      skipping = keyProvider === name;
+      if (skipping) continue;
+    } else if (/^\s*\[/.test(ln)) {
+      skipping = false;
+    }
+    if (!skipping) out.push(ln);
+  }
+  while (out.length && out[out.length - 1].trim() === '') out.pop();
+  fs.writeFileSync(file, out.join('\n') + (out.length ? '\n' : ''), 'utf8');
+  return file;
+}
+
+// ---- models: fetch + per-provider pools ----
+// Models are stored per provider as `[models."provider/model"]`, and also
+// mirrored into the provider's own pool at `[providers.NAME].models`. The
+// display name defaults to the model id (edit config.toml to override).
+export function modelKey(provider, modelId) { return `${provider}/${modelId}`; }
+
+// Append a model under a provider (used by the "add model" flow and by the
+// auto-fetch after adding a provider). Idempotent per key.
+export function addModel(provider, modelId, opts = {}) {
+  const file = hncodeConfigFile();
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch {}
+  const key = modelKey(provider, modelId);
+  if (new RegExp(`^\\s*\\[models\\."${escapeRe(key)}"\\]`, 'm').test(text)) return file; // already there
+  const lines = [`[models."${key}"]`, `provider = "${provider}"`, `model = "${modelId}"`];
+  if (opts.display_name) lines.push(`display_name = "${String(opts.display_name).replace(/"/g, '\\"')}"`);
+  // Persist the context window discovered from /v1/models so resolveConfig can
+  // size the context bar per model (not a global 128k).
+  if (opts.contextLength) lines.push(`context_length = ${Number(opts.contextLength)}`);
+  if (opts.maxTokens) lines.push(`max_tokens = ${Number(opts.maxTokens)}`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, '\n' + lines.join('\n') + '\n', 'utf8');
+  return file;
+}
+
+function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+// Fetch the model list from a provider's API. The base URL is used as given and
+// we append only `/models` (so `https://host/v1` → `https://host/v1/models`).
+// Anthropic sends x-api-key + anthropic-version. Returns [{id, display}] or [].
+export async function fetchModels({ baseUrl, apiKey, protocol }) {
+  const b = String(baseUrl || '').replace(/\/+$/, '');
+  if (!b) return [];
+  const url = `${b}/models`;
+  const headers = { 'content-type': 'application/json' };
+  if (protocol === 'anthropic') {
+    if (apiKey) headers['x-api-key'] = apiKey;
+    headers['anthropic-version'] = '2023-06-01';
+  } else if (apiKey) {
+    headers['authorization'] = `Bearer ${apiKey}`;
+  }
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 15000);
+  try {
+    const res = await fetch(url, { headers, signal: ctrl.signal });
+    if (!res.ok) return [];
+    const json = await res.json();
+    // OpenAI: { data: [{ id }] }  |  Anthropic: { data: [{ id, display_name }] }
+    const arr = Array.isArray(json.data) ? json.data : (Array.isArray(json.models) ? json.models : []);
+    return arr.map((m) => ({
+      id: String(m.id || m.name || ''),
+      display: m.display_name || m.displayName || '',
+      // Capability hints (servers vary in what they expose).
+      contextLength: m.context_length || m.contextLength || undefined,
+      maxTokens: m.max_tokens || undefined,          // NEW: per-model token limit from /v1/models
+      maxOutputTokens: m.max_output_tokens || m.maxOutputTokens || undefined,
+      ownedBy: m.owned_by || undefined,
+      // Reasoning support flags, when the server declares them.
+      reasoning: m.reasoning === true || m.supports_reasoning === true
+        || Array.isArray(m.reasoning_efforts) || Array.isArray(m.supported_efforts)
+        || undefined,
+      efforts: m.reasoning_efforts || m.supported_efforts || undefined,
+    })).filter((m) => m.id);
+  } catch { return []; }
+  finally { clearTimeout(timer); }
+}
+
+// ---- thinking effort capability ----
+// The set of selectable efforts for a model. Honours, in order:
+//   1. an explicit `efforts` / `reasoning_efforts` list on the model entry
+//   2. an explicit `reasoning = false` (model cannot think)
+//   3. a name heuristic for models known to expose graded effort
+// Returns [] when the model has no thinking control (then /model shows no
+// effort row and /effort reports it is unsupported).
+// Selectable thinking efforts for a model, mirroring kimi's `segmentsFor`:
+//   * a model that declares `efforts` uses exactly those (plus a leading 'off'
+//     unless it is `always_thinking`, which cannot be turned off)
+//   * `reasoning = false` / `thinking = false` -> no control at all
+//   * otherwise fall back to id heuristics: graded OpenAI models get
+//     off/low/medium/high, Anthropic and everything else get off/on.
+export function effortOptions(cfg, modelKeyName) {
+  const models = (cfg.raw && cfg.raw.models) || {};
+  const entry = models[modelKeyName || cfg.model] || {};
+  const declared = Array.isArray(entry.efforts) ? entry.efforts.filter(Boolean).slice() : [];
+  const alwaysOn = entry.always_thinking === true || entry.alwaysThinking === true;
+  if (declared.length) return alwaysOn ? declared : (declared[0] === 'off' ? declared : ['off', ...declared]);
+  if (alwaysOn) return ['on'];
+  if (entry.reasoning === false || entry.thinking === false) return [];
+  const id = String(entry.model || modelKeyName || cfg.innerModel || '').toLowerCase();
+  // OpenAI-style graded efforts.
+  if (/(^|\/)(gpt-5|o1|o3|o4)/.test(id) || /gpt-5|o1-|o3-|o4-/.test(id)) {
+    return ['off', 'low', 'medium', 'high'];
+  }
+  // Anthropic extended thinking is a budget, not a grade — expose on/off only.
+  if (cfg.protocol === 'anthropic') return ['off', 'on'];
+  // Default: thinking is on/off.
+  return ['off', 'on'];
+}
+
+// Map a chosen effort to the wire value for the active protocol.
+export function effortWire(cfg, effort) {
+  if (!effort || effort === 'off') return null;
+  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 } };
+  }
+  // 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 };
+}
+
+function toTomlLine(k, v) {
+  if (typeof v === 'string') return `${k} = "${v.replace(/"/g, '\\"')}"`;
+  if (typeof v === 'boolean') return `${k} = ${v}`;
+  if (typeof v === 'number') return `${k} = ${v}`;
+  if (Array.isArray(v)) return `${k} = [ ${v.map((x) => `"${x}"`).join(', ')} ]`;
+  return `${k} = "${v}"`;
+}
+
+// The bare model id sent to the API. The config KEY is authoritative: it is
+// always "<provider>/<model-id>", so the id is the key minus the provider
+// prefix. The entry's `model` field is only consulted when the key has no
+// provider prefix — older hncode versions wrote corrupt values there (e.g. a
+// different model's id), so it must not override a well-formed key.
+export function bareModelId(provider, key, entry) {
+  const e = entry || {};
+  const providerName = e.provider || provider || '';
+  const k = String(key || '');
+  // API 只需要 model id 本身（可能带子前缀，如 qoder/deepseek-flash），
+  // 不要 hncode 的 provider 前缀（traebuddy/）。所以剥掉 "<provider>/"。
+  if (providerName && k.startsWith(providerName + '/')) return k.slice(providerName.length + 1);
+  // key 没有 provider 前缀时，显式 model 字段优先；否则用 key 本身。
+  const fromField = typeof e.model === 'string' ? e.model : '';
+  return fromField || k;
+}
+
+// Human-friendly model label for the status line.
+//   1. an explicit `display_name` on the [models.*] entry wins (user's choice)
+//   2. otherwise the bare model id, exactly as configured
+export function modelLabel(cfg) {
+  const models = (cfg.raw && cfg.raw.models) || {};
+  const entry = models[cfg.model] || {};
+  if (entry.display_name) return entry.display_name;
+  return bareModelId(cfg.provider, cfg.model, entry) || cfg.innerModel || cfg.model || '';
+}
+
+// Remember the model the user last switched to, so a new hncode session starts
+// on it. Stored as a top-level `model = "..."` in config.toml.
+export function rememberModel(model) {
+  if (!model) return;
+  const file = hncodeConfigFile();
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch {}
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let replaced = false;
+  let seenTableHeader = false;
+  for (const ln of lines) {
+    const isModelLine = /^\s*model\s*=/.test(ln);
+    // A top-level `model = "..."` line lives before any `[table]` header.
+    // Once a table header appears, subsequent `model =` lines are table keys,
+    // not the active model.
+    if (isModelLine && !seenTableHeader && !replaced) {
+      out.push(`model = "${String(model).replace(/"/g, '\\"')}"`);
+      replaced = true;
+      continue;
+    }
+    out.push(ln);
+    if (/^\s*\[/.test(ln)) seenTableHeader = true;
+  }
+  if (!replaced) {
+    // No top-level model line: insert it before the first table header.
+    let at = out.findIndex((l) => /^\s*\[/.test(l));
+    if (at < 0) at = out.length;
+    out.splice(at, 0, `model = "${String(model).replace(/"/g, '\\"')}"`);
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const joined = out.join('\n').replace(/^\n+/, '');
+  fs.writeFileSync(file, joined + (joined.endsWith('\n') ? '' : '\n'), 'utf8');
+  return file;
+}
+
+// Non-secret snapshot for /settings display.
+export function effectiveSnapshot(cfg) {
+  return {
+    model: cfg.model,
+    provider: cfg.provider,
+    baseUrl: cfg.baseUrl,
+    protocol: cfg.protocol,
+    endpoint: cfg.endpoint,
+    apiKeySet: !!cfg.apiKey,
+    reasoning: cfg.reasoning,
+    maxContextTokens: cfg.maxContextTokens,
+    maxOutputTokens: cfg.maxOutputTokens,
+    workspace: cfg.workspace,
+    allowExternal: cfg.allowExternal,
+  };
+}
+
+// Re-resolve a provider's base URL / protocol / API key when the user switches
+// providers at runtime (/provider, /model). The chosen provider's [providers.NAME]
+// sub-table takes precedence (it's the point of switching); env vars set at boot
+// are already baked into `cfg` and only remain in effect when the provider table
+// does not override a given field.
+export function resolveProvider(cfg, providerName, innerModel) {
+  const pr = (cfg.raw && cfg.raw.providers) || {};
+  const prov = pr[providerName] || {};
+  const baseUrl = (prov.base_url || prov.baseUrl || '') || cfg.baseUrl;
+  const apiKey = (prov.api_key || prov.apiKey || '') || cfg.apiKey;
+  const protocol = (prov.protocol) || cfg.protocol;
+  const inner = prov.model || (innerModel != null ? innerModel : cfg.innerModel);
+  const b = String(baseUrl || '').replace(/\/+$/, '');
+  const endpoint = protocol === 'anthropic' ? `${b}/messages` : `${b}/chat/completions`;
+  return { ...cfg, provider: providerName, innerModel: inner, baseUrl: b, endpoint, apiKey, protocol };
+}
+
+// Switch model, optionally moving to a provider declared via [models.NAME].
+// The returned cfg carries BOTH: `model` is the pool key (what the status line
+// and rememberModel use) and `innerModel` is the bare id sent to the API.
+export function resolveModelArg(cfg, modelName) {
+  if (!modelName) return cfg;
+  const models = (cfg.raw && cfg.raw.models) || {};
+  const entry = models[modelName] || {};
+  const provider = entry.provider || cfg.provider;
+  const inner = bareModelId(provider, modelName, entry);
+  return { ...resolveProvider(cfg, provider, inner), model: modelName };
+}
+
+export default { resolveConfig, saveConfig, effectiveSnapshot, resolveProvider, resolveModelArg, addProvider, removeProvider, addModel, fetchModels, fetchCatalog, modelKey, modelLabel, bareModelId, rememberModel, hncodeConfigFile };