carthagent 0.0.0-stage → 1.0.7

package/lib/tui/glyphs.mjs

@@ -0,0 +1,172 @@
+/**
+ * Terminal glyph registry.
+ *
+ * carthagent draws a lot of icons — tool marks, status dots, a D2 graph and progress
+ * spinners. Fonts that lack Geometric Shapes / Braille / Misc Symbols render
+ * those codepoints as `?`, which makes the console unreadable. This module
+ * centralizes every non-text glyph behind two complete tiers:
+ *
+ *   unicode — the designed set (box drawing + widely supported shapes).
+ *   ascii   — a pure-ASCII fallback for limited fonts and legacy consoles.
+ *
+ * The tier is resolved once from `--ascii` / `CARTHAGENT_GLYPHS` / `CARTHAGENT_ASCII` and,
+ * in `auto` mode, from the locale + terminal markers. Consumers receive a flat
+ * object whose values are all single display cells (spinner is an array).
+ *
+ * When adding a glyph: give it an entry in BOTH tiers. Box drawing stays
+ * Unicode in the `unicode` tier because every monospace font ships it; the
+ * `ascii` tier replaces it with `+ - | ' .` so the graph survives anywhere.
+ */
+
+const U = {
+  // --- tool / activity icons ---------------------------------------------
+  read: '\u25c8',        // ◈
+  run: '\u25b8',         // ▸
+  write: '\u270e',       // ✎
+  search: '\u2315',      // ⌕
+  list: '\u25a4',        // ▤
+  plan: '\u25c7',        // ◇
+  check: '\u2691',       // ⚑
+  status: '\u00b7',      // ·
+
+  // --- status marks -------------------------------------------------------
+  done: '\u2713',        // ✓
+  fail: '\u2717',        // ✗
+  warn: '\u25b2',        // ▲
+  stale: '\u25d0',       // ◐
+  blocked: '\u25a0',     // ■
+  active: '\u25b6',      // ▶
+  pending: '\u25cb',     // ○
+  running: '\u25cf',     // ●
+  queued: '\u25cc',      // ◌
+  info: '\u00b7',        // ·
+  aleph: '\u{10900}',    // 𐤀 — Phoenician aleph, Carthagent's Aleph mark
+  sparkle: '\u2726',     // ✦
+  sparkleHollow: '\u2727', // ✧
+
+  // --- navigation / decoration -------------------------------------------
+  up: '\u2191',          // ↑
+  down: '\u2193',        // ↓
+  left: '\u2190',        // ←
+  right: '\u2192',       // →
+  shift: '\u21e7',       // ⇧
+  bullet: '\u2022',      // •
+  ellipsis: '\u2026',    // …
+  fold: '\u22ee',        // ⋮
+  back: '\u21a9',        // ↩
+  tail: '\u23bf',        // ⎿ (tool-output gutter)
+  // pane scrollbars (box drawing — present in every monospace font)
+  scrollTrack: '\u2502', // │
+  scrollThumb: '\u2503', // ┃
+  // phase strip dots
+  phaseDone: '\u25cf',   // ●
+  phaseCurrent: '\u25c9',// ◉
+  phasePending: '\u25cb',// ○
+
+  // --- D2 graph animation -------------------------------------------------
+  arrowDown: '\u25bc',       // ▼
+  arrowDownHollow: '\u25bd', // ▽
+  arrowLeft: '\u25c0',       // ◀
+  arrowLeftHollow: '\u25c1', // ◁
+  packetOn: '\u25cf',        // ●
+  packetOff: '\u25e6',       // ◦
+
+  // --- D2 graph box drawing ----------------------------------------------
+  box: {
+    tl: '\u256d', tr: '\u256e', bl: '\u2570', br: '\u256f', h: '\u2500', v: '\u2502',
+    mtl: '\u2554', mtr: '\u2557', mbl: '\u255a', mbr: '\u255d', mh: '\u2550', mv: '\u2551',
+    topJoin: '\u252c', botJoin: '\u2534', topJoinM: '\u2564', botJoinM: '\u2567', tee: '\u251c',
+    elbowDR: '\u256d', elbowDL: '\u256e', elbowUR: '\u2570', elbowUL: '\u256f',
+    dashV: '\u2504', dashH: '\u254c',
+  },
+
+  // --- spinners -----------------------------------------------------------
+  spinner: ['\u280b', '\u2819', '\u2839', '\u2838', '\u283c', '\u2834', '\u2826', '\u2827', '\u2807', '\u280f'],
+};
+
+const A = {
+  read: 'r', run: '>', write: 'w', search: '/', list: '=',
+  plan: '+', check: '!', status: '-',
+
+  done: '+', fail: 'x', warn: '!', stale: '~', blocked: '#',
+  aleph: 'A',
+  sparkle: '*', sparkleHollow: '*',
+  active: '>', pending: '.', running: '*', queued: ':', info: '-',
+
+  up: '^', down: 'v', left: '<', right: '>', shift: '^',
+  bullet: '*', ellipsis: '..', fold: ':', back: '<-', tail: '\\',
+  scrollTrack: '|', scrollThumb: '#',
+  phaseDone: '*', phaseCurrent: '@', phasePending: '.',
+
+  arrowDown: 'v', arrowDownHollow: 'v', arrowLeft: '<', arrowLeftHollow: '<',
+  packetOn: '*', packetOff: 'o',
+
+  box: {
+    tl: '.', tr: '.', bl: "'", br: "'", h: '-', v: '|',
+    mtl: '+', mtr: '+', mbl: '+', mbr: '+', mh: '=', mv: '|',
+    topJoin: '+', botJoin: '+', topJoinM: '+', botJoinM: '+', tee: '+',
+    elbowDR: '.', elbowDL: '.', elbowUR: "'", elbowUL: "'",
+    dashV: ':', dashH: '.',
+  },
+
+  spinner: ['|', '/', '-', '\\'],
+};
+
+export const UNICODE_GLYPHS = Object.freeze({ ...U, box: Object.freeze({ ...U.box }), spinner: Object.freeze([...U.spinner]) });
+export const ASCII_GLYPHS = Object.freeze({ ...A, box: Object.freeze({ ...A.box }), spinner: Object.freeze([...A.spinner]) });
+
+const KNOWN_UTF8_TERMINALS = ['WT_SESSION', 'TERM_PROGRAM', 'ITERM_SESSION_ID', 'KITTY_WINDOW_ID', 'WEZTERM_EXECUTABLE', 'ALACRITTY_WINDOW_ID', 'GHOSTTY_RESOURCES_DIR', 'VTE_VERSION', 'KONSOLE_VERSION', 'TMUX', 'STY'];
+
+/**
+ * Pick a glyph tier. Explicit config always wins; otherwise `auto` keeps the
+ * Unicode set on terminals we can reasonably expect to support it and falls
+ * back to ASCII everywhere else (non-UTF-8 locale, legacy Windows console,
+ * unknown TERM). `NO_COLOR` is deliberately NOT a signal — it disables color,
+ * not glyphs.
+ *
+ * @returns {'unicode'|'ascii'}
+ */
+export function detectGlyphMode(env = process.env, platform = process.platform) {
+  const explicit = String(env.CARTHAGENT_GLYPHS || '').trim().toLowerCase();
+  if (explicit === 'ascii' || explicit === 'unicode') return explicit;
+  const flag = String(env.CARTHAGENT_ASCII || '').trim().toLowerCase();
+  if (flag === '1' || flag === 'true' || flag === 'yes') return 'ascii';
+  if (flag === '0' || flag === 'false' || flag === 'no') return 'unicode';
+
+  // A non-UTF-8 locale or a dumb terminal can't carry the symbol set at all.
+  const locale = String(env.LC_ALL || env.LC_CTYPE || env.LANG || '');
+  const utf8 = !locale || /utf-?8/i.test(locale);
+  if (!utf8) return 'ascii';
+  if (env.TERM === 'dumb') return 'ascii';
+
+  // `auto` prefers ASCII unless we have positive evidence of a modern terminal
+  // emulator. Half the designed glyphs (Geometric Shapes, Braille, Misc
+  // Symbols) silently render as `?` in legacy consoles and limited fonts, and
+  // there is no reliable runtime font probe — so opt in to Unicode, not out.
+  // Set CARTHAGENT_GLYPHS=unicode / --glyphs unicode to force the designed set.
+  const marker = KNOWN_UTF8_TERMINALS.some(k => env[k]);
+  const truecolor = /truecolor|24bit/i.test(env.COLORTERM || '');
+  const modernTerm = /xterm|screen|tmux|linux|vt|ansi|alacritty|kitty|wezterm|ghostty/i.test(env.TERM || '');
+  if (marker || (truecolor && modernTerm)) return 'unicode';
+  return 'ascii';
+}
+
+/** Resolve a full glyph object for an option bag / env. */
+export function resolveGlyphs({ mode, ascii, env = process.env, platform = process.platform } = {}) {
+  // Only explicit ascii/unicode win; `auto`, undefined and unknown values
+  // fall through to detection (so `--glyphs auto` behaves as documented).
+  const explicit = mode === 'ascii' || mode === 'unicode' ? mode : ascii ? 'ascii' : null;
+  const chosen = explicit || detectGlyphMode(env, platform);
+  return chosen === 'ascii' ? ASCII_GLYPHS : UNICODE_GLYPHS;
+}
+
+/** Spinner frame for a resolved set. */
+export function spinnerFrame(glyphs, frame) {
+  const s = glyphs?.spinner || UNICODE_GLYPHS.spinner;
+  return s[((frame % s.length) + s.length) % s.length];
+}
+
+/** True when a resolved set is the ASCII fallback tier. */
+export function isAsciiGlyphs(glyphs) {
+  return glyphs === ASCII_GLYPHS;
+}

package/lib/tui/hash-worker.mjs

@@ -0,0 +1,11 @@
+/** Worker thread: compute the workspace fingerprint off the UI thread. */
+import { parentPort } from 'node:worker_threads';
+import { fingerprint } from '../delivery.mjs';
+
+parentPort.on('message', ({ cwd, roots }) => {
+  try {
+    parentPort.postMessage({ hash: fingerprint(cwd, roots) });
+  } catch (err) {
+    parentPort.postMessage({ error: String(err.message || err) });
+  }
+});

package/lib/tui/mock-engine.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * Mock the engine's `--mode rpc` for `carthagent demo`: speaks the rpc line protocol and plays a
+ * scripted end-to-end delivery (plan → build → check → finish) so the console's
+ * visuals can be exercised without a provider or API credit.
+ *
+ * It also writes real .harness/<session>/<run>/report.json + plan.d2 files, so
+ * the side panel exercises the same file-watching path as a live run.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { planD2, fingerprint } from '../delivery.mjs';
+
+const SPEED = Math.max(0.05, Number(process.env.CARTHAGENT_DEMO_SPEED) || 1);
+const START_DELAY = Math.max(0, Number(process.env.CARTHAGENT_DEMO_START_DELAY) || 0);
+const sleep = ms => new Promise(r => setTimeout(r, ms * SPEED));
+const emit = obj => process.stdout.write(JSON.stringify(obj) + '\n');
+
+const SESSION_ID = 'demo';
+const cwd = process.cwd();
+const runId = randomUUID();
+const harnessDir = join(cwd, '.harness', SESSION_ID, runId);
+
+let activeModel = { provider: 'demo', id: 'carthagent-demo-1' };
+let thinkingLevel = 'medium';
+const stats = { tokens: 0, cost: 0, toolCalls: 0, userMessages: 0, streaming: false, compacting: false, autoCompact: true, ctx: 9000 };
+let aborted = false;
+
+const usage = (input, output) => {
+  const totalTokens = input + output;
+  stats.tokens += totalTokens;
+  stats.cost += totalTokens * 1.2e-6;
+  stats.ctx = Math.min(190000, stats.ctx + Math.round(totalTokens * 0.8));
+  return { totalTokens, input, output, cost: { total: totalTokens * 1.2e-6 } };
+};
+
+function taskSummary(prompt) {
+  // The console wraps tasks in the delivery template; recover the user's text.
+  const m = String(prompt).match(/^Deliver this task in phases(?: with executable evidence)?:\s*([\s\S]*?)\n\n/);
+  const clean = (m ? m[1] : String(prompt)).replace(/\s+/g, ' ').trim();
+  return clean.length > 64 ? clean.slice(0, 63) + '…' : clean || 'demo task';
+}
+
+function demoPlan(prompt) {
+  return {
+    goal: taskSummary(prompt),
+    assumptions: ['standard library only', 'tests run in a fresh subprocess'],
+    artifacts: ['.'],
+    steps: ['Inspect workspace and probe runtime', 'Implement runnable vertical slice', 'Cover edge cases, tests and docs'],
+    acceptance: [
+      { requirement: 'Core behavior works in a fresh process', checks: ['smoke'] },
+      { requirement: 'Edge cases and persistence covered by tests', checks: ['unit'] },
+    ],
+    checks: [
+      { id: 'unit', kind: 'test', argv: ['node', '--test', 'tests/app.test.mjs'], timeoutSeconds: 60 },
+      { id: 'smoke', kind: 'runtime', argv: ['node', 'app.mjs', '--smoke'], timeoutSeconds: 30 },
+    ],
+  };
+}
+
+function writeReport(state) {
+  mkdirSync(harnessDir, { recursive: true });
+  writeFileSync(join(harnessDir, 'report.json'), JSON.stringify(state, null, 2) + '\n');
+  writeFileSync(join(harnessDir, 'plan.d2'), planD2(state.plan));
+}
+
+async function toolCall(id, name, args, result, { update, ms = 600 } = {}) {
+  emit({ type: 'message_update', assistantMessageEvent: { type: 'toolcall_start', contentIndex: 1, id, toolName: name } });
+  stats.toolCalls++;
+  emit({ type: 'tool_execution_start', toolCallId: id, toolName: name, args });
+  if (update) for (const u of update) { await sleep(320); emit({ type: 'tool_execution_update', toolCallId: id, partialResult: { content: [{ type: 'text', text: u }] } }); }
+  await sleep(ms);
+  emit({ type: 'tool_execution_end', toolCallId: id, toolName: name, isError: false, result: { content: [{ type: 'text', text: result }] } });
+}
+
+async function assistantText(text, { thinking } = {}) {
+  emit({ type: 'message_start', message: { role: 'assistant', content: [] } });
+  if (thinking) {
+    for (const chunk of thinking.match(/.{1,24}/gs) || []) {
+      emit({ type: 'message_update', assistantMessageEvent: { type: 'thinking_delta', contentIndex: 0, delta: chunk } });
+      await sleep(60);
+    }
+  }
+  for (const chunk of text.match(/.{1,28}/gs) || []) {
+    emit({ type: 'message_update', assistantMessageEvent: { type: 'text_delta', contentIndex: 0, delta: chunk } });
+    await sleep(45);
+  }
+  emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text }], usage: usage(4200, 900), stopReason: 'stop' } });
+}
+
+async function runDemo(prompt) {
+  const plan = demoPlan(prompt);
+  const state = { version: 1, runId, plan, evidence: {}, status: 'implementing', createdAt: new Date().toISOString() };
+  stats.streaming = true; aborted = false;
+  if (START_DELAY) await new Promise(r => setTimeout(r, START_DELAY));
+  emit({ type: 'agent_start' });
+  emit({ type: 'message_start', message: { role: 'user', content: [{ type: 'text', text: prompt }] } });
+  emit({ type: 'message_end', message: { role: 'user', content: [{ type: 'text', text: prompt }] } });
+  await sleep(250);
+
+  emit({ type: 'turn_start' });
+  await assistantText('I’ll inspect the workspace, define the checks, and implement the task.', {
+    thinking: 'Mapping the request to a small acceptance contract.',
+  });
+  if (aborted) return endRun();
+
+  await toolCall('t1', 'delivery_plan', plan, JSON.stringify({ plan: join(harnessDir, 'plan.d2'), report: join(harnessDir, 'report.json'), next: 'Build a runnable slice, add regression tests, then delivery_check each check ID.' }, null, 2));
+  writeReport(state);
+  await sleep(300);
+
+  emit({ type: 'turn_start' });
+  await toolCall('t2', 'ls', { path: '.' }, 'app.mjs\ntests/\nREADME.md', { ms: 350 });
+  await toolCall('t3', 'write', { path: 'app.mjs', content: '// demo' }, 'Wrote app.mjs (86 lines)', { ms: 500 });
+  if (aborted) return endRun();
+  await toolCall('t4', 'write', { path: 'tests/app.test.mjs', content: '// demo' }, 'Wrote tests/app.test.mjs (41 lines)', { ms: 500 });
+  await assistantText('The implementation is ready. I’m exercising the entry point before running the declared checks.', { thinking: 'Verify the runnable path end to end, not just imports.' });
+
+  emit({ type: 'turn_start' });
+  await toolCall('t5', 'bash', { command: 'node app.mjs --smoke' }, 'SMOKE ok · 3 interactions · exit 0', { ms: 700 });
+  if (aborted) return endRun();
+
+  state.status = 'verifying';
+  writeReport(state);
+  let fp;
+  try { fp = fingerprint(cwd, ['.']); } catch { fp = 'f'.repeat(64); }
+  await toolCall('t6', 'delivery_check', { id: 'all' }, JSON.stringify([
+    { id: 'unit', passed: true, code: 0, durationMs: 812 },
+    { id: 'smoke', passed: true, code: 0, durationMs: 1330 },
+  ], null, 2), {
+    update: ['Running unit: ["node","--test","tests/app.test.mjs"]', 'Running smoke: ["node","app.mjs","--smoke"]'],
+    ms: 400,
+  });
+  for (const [id, ms] of [['unit', 812], ['smoke', 1330]]) {
+    state.evidence[id] = { passed: true, fingerprint: fp, code: 0, durationMs: ms, outputTail: `${id} passed` };
+  }
+  writeReport(state);
+  await sleep(400);
+
+  emit({ type: 'turn_start' });
+  await assistantText('The checks pass on the current fingerprint. I’m reviewing scope before finishing.');
+  await toolCall('t7', 'delivery_finish', { status: 'verified', review: 'Fresh-process smoke plus unit coverage pass; scope matches the request.', launch: 'node app.mjs', limitations: ['demo evidence is scripted'] },
+    JSON.stringify({ status: 'verified', report: join(harnessDir, 'report.json'), note: 'Evidence covers declared checks, not a guarantee of correctness.' }, null, 2));
+  state.status = 'verified';
+  state.handoff = { status: 'verified', review: 'Fresh-process smoke plus unit coverage pass.', launch: 'node app.mjs', limitations: ['demo evidence is scripted'], fingerprint: fp, at: new Date().toISOString() };
+  writeReport(state);
+  await assistantText('Verified. Run with `node app.mjs`.');
+  endRun();
+}
+
+function endRun() {
+  stats.streaming = false;
+  emit({ type: 'agent_end', messages: [] });
+  emit({ type: 'agent_settled' });
+}
+
+async function respond(cmd) {
+  const reply = data => emit({ type: 'response', id: cmd.id, success: true, data });
+  switch (cmd.type) {
+    case 'get_state':
+      return reply({
+        model: activeModel, thinkingLevel,
+        isStreaming: stats.streaming, isCompacting: stats.compacting,
+        sessionId: SESSION_ID, sessionName: 'demo', messageCount: stats.userMessages * 2,
+        pendingMessageCount: 0, steeringMode: 'all', followUpMode: 'one-at-a-time', autoCompactionEnabled: stats.autoCompact,
+      });
+    case 'get_session_stats':
+      return reply({
+        sessionId: SESSION_ID, userMessages: stats.userMessages, assistantMessages: stats.userMessages * 3,
+        toolCalls: stats.toolCalls, toolResults: stats.toolCalls, totalMessages: stats.userMessages * 4,
+        tokens: { input: Math.round(stats.tokens * 0.7), output: Math.round(stats.tokens * 0.3), cacheRead: 0, cacheWrite: 0, total: stats.tokens },
+        cost: stats.cost,
+        contextUsage: { tokens: stats.ctx, contextWindow: 200000, percent: Math.round(stats.ctx / 2000) },
+      });
+    case 'prompt':
+      stats.userMessages++;
+      reply({});
+      if (stats.streaming) return;
+      runDemo(cmd.message || '').catch(() => endRun());
+      return;
+    case 'steer':
+      reply({});
+      emit({ type: 'message_start', message: { role: 'user', content: [{ type: 'text', text: cmd.message || '' }] } });
+      emit({ type: 'message_end', message: { role: 'user', content: [{ type: 'text', text: cmd.message || '' }] } });
+      return;
+    case 'bash':
+      return reply({ exitCode: 0, output: `demo$ ${cmd.command || ''}\n(mock shell — no real execution)` });
+    case 'abort': aborted = true; return reply({});
+    case 'cycle_model': return reply({ model: { provider: 'demo', id: 'carthagent-demo-1' } });
+    case 'set_model': activeModel = { provider: cmd.provider, id: cmd.modelId }; return reply(activeModel);
+    case 'get_available_thinking_levels': return reply({ levels: ['off', 'low', 'medium', 'high'] });
+    case 'set_thinking_level': thinkingLevel = cmd.level; return reply({});
+    case 'get_available_models': return reply({ models: [
+      { provider: 'demo', id: 'carthagent-demo-1' },
+      { provider: 'demo', id: 'carthagent-demo-2' },
+      { provider: 'openrouter', id: 'google/gemini-flash-latest' },
+      { provider: 'openrouter', id: 'anthropic/claude-sonnet-latest' },
+      { provider: 'openrouter', id: 'openai/gpt-latest' },
+      { provider: 'openrouter', id: 'deepseek/deepseek-v4.1-flash', name: 'DeepSeek: DeepSeek V4.1 Flash' },
+    ] });
+    case 'cycle_thinking_level': return reply({ level: 'high' });
+    case 'compact': stats.compacting = true; reply({}); setTimeout(() => { stats.compacting = false; stats.ctx = 9000; }, 900); return;
+    case 'set_auto_compaction': stats.autoCompact = Boolean(cmd.enabled); return reply({});
+    case 'new_session': stats.userMessages = 0; stats.tokens = 0; stats.cost = 0; stats.ctx = 9000; return reply({ cancelled: false });
+    case 'export_html': return reply({ path: join(cwd, 'demo-export.html') });
+    case 'extension_ui_response': return;
+    default: return reply({});
+  }
+}
+
+let buf = '';
+process.stdin.on('data', d => {
+  buf += d.toString();
+  let i;
+  while ((i = buf.indexOf('\n')) !== -1) {
+    const line = buf.slice(0, i); buf = buf.slice(i + 1);
+    if (!line.trim()) continue;
+    let cmd; try { cmd = JSON.parse(line); } catch { continue; }
+    respond(cmd);
+  }
+});
+process.stdin.on('end', () => process.exit(0));

package/lib/tui/models.mjs

@@ -0,0 +1,73 @@
+/**
+ * Pure helpers for the console's provider/model picker.
+ *
+ * `state.modelList` is a flat array of `{ provider, id, full }` from the engine's
+ * `get_available_models`. The settings overlay groups/filters it by provider
+ * so multiple authenticated providers can coexist and be switched between.
+ * Provider ids remain internal routing identities; user-facing surfaces map the
+ * managed provider to the Carthagent Ship product name.
+ */
+import { providerDisplayName } from '../providers/names.mjs';
+
+/** Sorted unique provider ids present in a model list. */
+export function providersFromModels(list) {
+  const seen = new Set();
+  for (const m of list || []) if (m?.provider) seen.add(m.provider);
+  return [...seen].sort((a, b) => a.localeCompare(b));
+}
+
+/** Provider id for the current model, resolved against the available list.
+ *  Falls back to the `provider/…` prefix when the model isn't listed yet. */
+export function providerForModel(model, list) {
+  const s = String(model || '');
+  const hit = (list || []).find(m => m.full === s) || (list || []).find(m => m.id === s);
+  if (hit) return hit.provider;
+  const slash = s.indexOf('/');
+  return slash > 0 ? s.slice(0, slash) : '';
+}
+
+/** Filter a model list by provider and (optionally) a search string, capped. */
+export function modelMatchesQuery(model, query) {
+  const tokens = String(query || '').toLowerCase().match(/[\p{L}\p{N}]+/gu) || [];
+  if (!tokens.length) return true;
+  const searchable = [model?.provider, providerDisplayName(model?.provider), model?.id, model?.full, model?.name]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+  return tokens.every(token => searchable.includes(token));
+}
+
+export function filterModelsByProvider(list, provider, query, limit = 50) {
+  let out = list || [];
+  if (provider) out = out.filter(m => m.provider === provider);
+  if (query) out = out.filter(m => modelMatchesQuery(m, query));
+  return out.slice(0, limit);
+}
+
+/** True when the engine resolved the model as reasoning-capable. */
+export function modelSupportsThinking(model) {
+  return model?.reasoning === true;
+}
+
+/** Next provider id when cycling a list, wrapping in both directions. */
+export function cycleProvider(providers, current, dir) {
+  if (!providers?.length) return '';
+  const i = providers.indexOf(current);
+  const at = i === -1 ? 0 : i;
+  return providers[(at + dir + providers.length) % providers.length];
+}
+
+/** Coalesce RPC reads, but never retain a startup snapshot indefinitely. */
+export function createModelLoader(rpc, state) {
+  let pending;
+  return () => {
+    if (pending) return pending;
+    pending = rpc.send({ type: 'get_available_models' }).then(response => {
+      if (!Array.isArray(response?.models)) return state.modelList || [];
+      const list = response.models.map(model => ({ ...model, name: model.name || '', full: `${model.provider}/${model.id}` }));
+      state.modelList = list;
+      return list;
+    }).catch(() => state.modelList || []).finally(() => { pending = null; });
+    return pending;
+  };
+}

package/lib/tui/picker.mjs

@@ -0,0 +1,18 @@
+/** Shared keyboard semantics: navigation is never a commit. */
+export function pickerKey(picker, key, count) {
+  if (picker.pending) return 'pending';
+  const moves = { up: -1, down: 1, pgup: -8, pgdn: 8 };
+  if (key in moves) picker.sel = Math.max(0, Math.min(Math.max(0, count - 1), picker.sel + moves[key]));
+  if (key === 'esc') return 'cancel';
+  if (key === 'enter' && count) return 'commit';
+  return 'browse';
+}
+
+export async function commitPicker(picker, action, success) {
+  if (picker.pending) return;
+  picker.pending = true;
+  picker.error = '';
+  try { await action(); success(); }
+  catch (error) { picker.error = error.message; }
+  finally { picker.pending = false; }
+}