quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/slash/ledger.js

@@ -0,0 +1,83 @@
+/**
+ * Session usage ledger for /cost, /usage and /context. Fed the raw stream events of each turn; counts only
+ * what the server reported (turn.finished.usage, or done.usage on a server that never sends turn.finished).
+ * Nothing is estimated: a turn without usage is counted as "not reported", and cost stays blank unless the
+ * server sent cost_usd.
+ */
+const num = (v) => (v == null || v === '' || !Number.isFinite(Number(v)) ? null : Number(v));
+
+export function readUsage(u) {
+  const o = u && typeof u === 'object' ? u : {};
+  const input = num(o.input_tokens ?? o.prompt_tokens);
+  const output = num(o.output_tokens ?? o.completion_tokens);
+  const cacheRead = num(o.cache_read_input_tokens);
+  const cacheWrite = num(o.cache_creation_input_tokens);
+  const cost = num(o.cost_usd);
+  return { input, output, cacheRead, cacheWrite, cost, reported: input != null || output != null };
+}
+
+export function createLedger() {
+  const models = new Map(); // key -> row
+  const convs = new Map(); // conversation id -> tokens
+  let turn = null;
+  const finalize = (usage, convId) => {
+    if (!turn) return;
+    const t = turn; turn = null;
+    const u = readUsage(usage ?? t.doneUsage);
+    const key = `${t.provider || '?'}|${t.model || '?'}`;
+    const r = models.get(key) || { provider: t.provider, model: t.model, turns: 0, reported: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, costTurns: 0 };
+    r.turns++;
+    if (u.reported) {
+      r.reported++;
+      r.input += u.input || 0; r.output += u.output || 0; r.cacheRead += u.cacheRead || 0; r.cacheWrite += u.cacheWrite || 0;
+      const id = convId || t.conversationId;
+      if (id) convs.set(id, (convs.get(id) || 0) + (u.input || 0) + (u.output || 0));
+    }
+    if (u.cost != null) { r.cost += u.cost; r.costTurns++; }
+    models.set(key, r);
+  };
+  return {
+    observe(ev) {
+      if (!ev || typeof ev !== 'object') return;
+      if (ev.type === 'turn.started') turn = { provider: ev.provider || null, model: ev.model || null, conversationId: ev.conversation_id || null, doneUsage: null };
+      else if (ev.type === 'done' && turn) turn.doneUsage = ev.usage || (ev.cost_usd != null ? { cost_usd: ev.cost_usd } : null);
+      else if (ev.type === 'turn.finished') finalize(ev.usage, ev.conversation_id);
+    },
+    /** The stream closed: settle a turn whose turn.finished never came (legacy servers send only done). */
+    end() { if (turn) finalize(null, null); },
+    rows: () => [...models.values()],
+    conversationTokens: (id) => (id ? convs.get(id) ?? 0 : 0),
+    totals() {
+      const t = { turns: 0, reported: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, costTurns: 0 };
+      for (const r of models.values()) for (const k of Object.keys(t)) t[k] += r[k];
+      return t;
+    }
+  };
+}
+
+const n = (v) => Number(v || 0).toLocaleString('en-US');
+const usd = (v) => `$${v < 0.01 ? v.toFixed(4) : v.toFixed(2)}`;
+
+function line(r) {
+  const parts = [`${r.turns} turn${r.turns === 1 ? '' : 's'}`];
+  if (r.reported) {
+    parts.push(`in ${n(r.input)}`, `out ${n(r.output)}`);
+    if (r.cacheRead || r.cacheWrite) parts.push(`cache ${n(r.cacheRead)} read / ${n(r.cacheWrite)} written`);
+  }
+  if (r.reported < r.turns) parts.push(`${r.turns - r.reported} without usage from the server`);
+  parts.push(r.costTurns === r.turns && r.turns ? usd(r.cost) : r.costTurns ? `${usd(r.cost)} for ${r.costTurns} of ${r.turns} turns` : 'cost not reported');
+  return parts.join(' · ');
+}
+
+/** -> help model rows for /cost. */
+export function costModel(ledger) {
+  const rows = ledger.rows();
+  const out = [{ kind: 'head', text: 'Cost and usage, this session' }];
+  if (!rows.length) return [...out, { kind: 'plain', text: 'No turns yet in this session.' }];
+  for (const r of rows) out.push({ kind: 'row', key: `${r.provider || '?'} ${r.model || ''}`.trim(), text: line(r) });
+  const t = ledger.totals();
+  if (rows.length > 1) out.push({ kind: 'row', key: 'Total', text: line(t) });
+  if (t.costTurns < t.turns) out.push({ kind: 'dim', text: 'Cost is blank where the server sent tokens but no cost_usd for that provider; Quox does not guess prices.' });
+  if (t.reported < t.turns) out.push({ kind: 'dim', text: 'Some turns ended without usage (an older server, or a turn that failed or was interrupted).' });
+  return out;
+}

package/lib/quoxon/slash/listView.js

@@ -0,0 +1,28 @@
+/**
+ * One small list component for everything slash commands pop up under the composer: the command
+ * palette, the /resume picker and the /config card. Rows: { key, text, note?, dim? }. The selected
+ * row carries a marker; dim rows show their note (the reason) in muted text.
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { c, clip } from '../theme.js';
+
+const h = React.createElement;
+
+export function ListView({ title = null, rows = [], sel = 0, cols = 80, hint = null, empty = null, more = 0 }) {
+  const keyW = Math.min(22, Math.max(8, ...rows.map(r => [...String(r.key || '')].length)) + 1);
+  const textW = Math.max(10, cols - keyW - 6);
+  return h(Box, { flexDirection: 'column', paddingLeft: 1 },
+    title ? h(Text, { color: c('muted'), bold: true }, clip(title, cols - 2)) : null,
+    !rows.length && empty ? h(Text, { color: c('muted') }, `  ${clip(empty, cols - 4)}`) : null,
+    ...rows.map((r, i) => {
+      const on = i === sel;
+      const body = r.dim && r.note ? `${r.note} · ${r.text}` : r.note ? `${r.text}  ${r.note}` : r.text;
+      return h(Box, { key: `${i}:${r.key}` },
+        h(Text, { color: on ? c('key') : c('muted') }, on ? '▸ ' : '  '),
+        h(Box, { width: keyW, flexShrink: 0 }, h(Text, { color: r.dim ? c('muted') : on ? c('key') : c('label'), bold: on && !r.dim, wrap: 'truncate-end' }, String(r.key || ''))),
+        h(Text, { color: c(r.dim ? 'muted' : 'text'), wrap: 'truncate-end' }, clip(String(body || ''), textW)));
+    }),
+    more > 0 ? h(Text, { color: c('muted') }, `  … ${more} more, keep typing to narrow`) : null,
+    hint ? h(Text, { color: c('dim') }, `  ${clip(hint, cols - 4)}`) : null);
+}

package/lib/quoxon/slash/palette.js

@@ -0,0 +1,104 @@
+/**
+ * L0 command palette: the pure model behind the list that opens under the composer when a draft
+ * starts with `/`. Built from the one REGISTRY (commands.js), so the palette, /help and dispatch can
+ * never disagree. Only commands that can work here are bright; anything this session cannot run is
+ * dim with the reason. Planned commands stay hidden unless typed exactly.
+ */
+import { REGISTRY } from '../commands.js';
+
+export const PALETTE_MAX = 8;
+
+/** The draft as a palette query: '/co' -> 'co'; null when the draft is not a bare command word. */
+export function paletteQuery(draft) {
+  const t = String(draft ?? '');
+  if (!t.startsWith('/') || t.startsWith('//')) return null;
+  if (/[\s]/.test(t)) return null; // args typed (or several lines): the palette steps aside
+  return t.slice(1).toLowerCase();
+}
+
+/**
+ * Why a command cannot run in this session, or null. `api` is the session's server wrapper (a method
+ * missing means this mode has no route for it); `caps` is GET /api/v1/capabilities when the server has
+ * it ({ id: { available, reason } }), else null; `blocked` is the not-signed-in message.
+ */
+export function unavailableReason(entry, { api = {}, caps = null, blocked = null } = {}) {
+  const cap = caps ? caps[entry.cap || entry.id] : null;
+  if (cap && cap.available === false) return cap.reason || 'not available on this server';
+  for (const m of entry.needs || []) if (typeof api[m] !== 'function') return 'not available in this mode';
+  if (blocked && entry.server) return 'not signed in';
+  return null;
+}
+
+/**
+ * GET /api/v1/capabilities as api.capabilities() returns it ({ ok, capabilities:[{ id, availability, reason, setup }] })
+ * -> { id: { available, reason } }, or null when the server has no contract. Only `installed` runs.
+ */
+export function capabilityMap(res) {
+  if (!res || res.ok !== true || !Array.isArray(res.capabilities)) return null;
+  const label = { requires_setup: 'needs setup', unavailable: 'unavailable on this server', planned: 'planned, not built yet' };
+  return Object.fromEntries(res.capabilities.filter(c => c && c.id).map(c => {
+    const available = c.availability === 'installed';
+    return [c.id, { available, reason: available ? null : (c.reason || label[c.availability] || 'not available on this server'), setup: c.setup || null }];
+  }));
+}
+
+/** All palette rows for this session, registry order. */
+export function paletteItems(ctx = {}, registry = REGISTRY) {
+  return registry.filter(e => e.kind === 'command').map(e => ({
+    id: e.id,
+    name: '/' + e.id,
+    usage: e.usage,
+    desc: e.desc,
+    aliases: (e.aliases || []).map(a => '/' + a),
+    planned: e.status === 'planned',
+    disabled: e.status === 'planned' ? 'planned, not built yet' : unavailableReason(e, ctx)
+  }));
+}
+
+/** Subsequence score of q in s (lower is better), or null when q is not a subsequence. */
+export function fuzzy(q, s) {
+  q = String(q).toLowerCase(); s = String(s).toLowerCase();
+  if (!q) return 0;
+  if (s.startsWith(q)) return 0;
+  const at = s.indexOf(q);
+  if (at >= 0) return 10 + at;
+  let i = 0, gaps = 0, last = -1;
+  for (let j = 0; j < s.length && i < q.length; j++) {
+    if (s[j] === q[i]) { if (last >= 0) gaps += j - last - 1; last = j; i++; }
+  }
+  return i === q.length ? 100 + gaps : null;
+}
+
+/** Filter + rank. Planned rows appear only on an exact name or alias match. */
+export function filterPalette(items, query) {
+  const q = String(query ?? '').toLowerCase();
+  const exact = (it) => it.id === q || it.aliases.includes('/' + q);
+  const scored = [];
+  items.forEach((it, idx) => {
+    if (it.planned && !exact(it)) return;
+    const names = [it.id, ...it.aliases.map(a => a.slice(1))];
+    let best = null;
+    for (const n of names) { const sc = fuzzy(q, n); if (sc != null && (best == null || sc < best)) best = sc; }
+    if (best == null && q.length >= 3 && it.desc.toLowerCase().includes(q)) best = 500; // words in the description
+    if (best == null) return;
+    if (exact(it)) best = -1;
+    if (it.disabled) best += 0.5; // a working command outranks an unavailable one on a tie
+    scored.push({ it, best, idx });
+  });
+  return scored.sort((a, b) => a.best - b.best || a.idx - b.idx).map(x => x.it);
+}
+
+/** What Tab puts in the draft: the name, plus a space when the command takes arguments. */
+export function completion(item) {
+  const takesArgs = /^\S+\s+\S/.test(String(item.usage).trim());
+  return item.name + (takesArgs ? ' ' : '');
+}
+
+/** View rows for the palette: a window of PALETTE_MAX around the selection. */
+export function paletteView(rows, sel, max = PALETTE_MAX) {
+  if (!rows.length) return { rows: [], sel: 0, more: 0, empty: true };
+  const s = Math.max(0, Math.min(sel, rows.length - 1));
+  const start = Math.max(0, Math.min(s - max + 1, rows.length - max));
+  const win = rows.slice(Math.max(0, start), Math.max(0, start) + max);
+  return { rows: win, sel: s - Math.max(0, start), more: rows.length - win.length, empty: false };
+}

package/lib/quoxon/slash/paletteController.js

@@ -0,0 +1,59 @@
+/**
+ * The palette's key handling, kept out of app.js. The palette is not modal: it shows while the draft is
+ * a bare `/word`, and only Up, Down, Tab, Enter and Esc go to it. Everything else is ordinary typing,
+ * which narrows the list because the draft IS the filter.
+ */
+import { findEntry } from '../commands.js';
+import { paletteQuery, paletteItems, filterPalette, completion, paletteView, PALETTE_MAX } from './palette.js';
+
+export function createPalette({ getDraft, setDraft, run, say, ctx = () => ({}) }) {
+  const st = { sel: 0, q: null, dismissed: null };
+  const rows = () => {
+    const q = paletteQuery(getDraft());
+    if (q !== st.q) { st.q = q; st.sel = 0; }
+    return q === null ? [] : filterPalette(paletteItems(ctx()), q);
+  };
+  const isOpen = () => {
+    const d = getDraft();
+    if (st.dismissed !== null && st.dismissed !== d) st.dismissed = null;
+    return paletteQuery(d) !== null && st.dismissed !== d;
+  };
+  /** -> true when the key was the palette's. */
+  function onKey(name) {
+    if (!isOpen()) return false;
+    const list = rows();
+    switch (name) {
+      case 'up': if (!list.length) return false; st.sel = (st.sel - 1 + list.length) % list.length; return true;
+      case 'down': if (!list.length) return false; st.sel = (st.sel + 1) % list.length; return true;
+      case 'escape': st.dismissed = getDraft(); return true;
+      case 'tab': {
+        const it = list[st.sel];
+        if (!it) return true;
+        setDraft(completion(it));
+        return true;
+      }
+      case 'enter': {
+        const typed = findEntry(getDraft());
+        if (typed && typed.kind === 'command') return false; // an exact command runs as typed (planned ones say so)
+        const it = list[st.sel];
+        if (!it) return false; // nothing matches: the normal path says "Unknown command"
+        if (it.disabled) { say(`${it.name} is ${it.disabled}.`, 'warn'); return true; }
+        setDraft('');
+        run(it.name);
+        return true;
+      }
+      default: return false;
+    }
+  }
+  function view() {
+    const list = rows();
+    const v = paletteView(list, st.sel, PALETTE_MAX);
+    return {
+      rows: v.rows.map(it => ({ key: it.name, text: (it.aliases.length ? `(also ${it.aliases.join(', ')}) ` : '') + it.desc, dim: Boolean(it.disabled), note: it.disabled || null })),
+      sel: v.sel, more: v.more,
+      empty: 'No command matches. Enter sends it anyway; /help lists everything.',
+      hint: '↑↓ select · Tab complete · Enter run · Esc close'
+    };
+  }
+  return { isOpen, onKey, view, state: st };
+}

package/lib/quoxon/slash/panels.js

@@ -0,0 +1,101 @@
+/**
+ * Pure panel models for /status, /context and /doctor, rendered with the /help view (head + key/value rows).
+ * Every value comes from the caller's real data; anything not known is said plainly, never filled in.
+ */
+import { capabilityMap } from './palette.js';
+
+const n = (v) => Number(v || 0).toLocaleString('en-US');
+const row = (key, text) => ({ kind: 'row', key, text: String(text) });
+
+export function healthText(hl) {
+  if (!hl) return '? not checked';
+  if (hl.ok) return `✔ answering (HTTP ${hl.status})`;
+  if (hl.absent) return `✖ nothing running there (${hl.status})`;
+  return `✖ not healthy (${hl.status})`;
+}
+
+/** What actually ran (turn.started), else what was asked for, said as such. */
+export function modelText(ctx = {}, choice = null) {
+  if (ctx.provider || ctx.model) return `${[ctx.provider, ctx.model].filter(Boolean).join(' ')} (as the server last reported)`;
+  const ask = choice ? [choice.provider, choice.model].filter(Boolean).join(' ') : 'auto (server policy)';
+  return `no turn yet; asking for ${ask}`;
+}
+
+export function statusModel(d = {}) {
+  return [
+    { kind: 'head', text: 'Status' },
+    row('Profile', d.profile || '?'),
+    row('Org', d.org || '? not in this login'),
+    row('Server', `${d.serverUrl || '?'} · ${healthText(d.health)}`),
+    row('Model', modelText(d.ctx, d.choice)),
+    row('Agent', d.agent || 'CommanderQ (quox)'),
+    row('Slot', d.slot || 'none (/slot <name>)'),
+    row('Session', d.sessionName || 'unnamed (/rename <name>)'),
+    row('Conversation', d.conversationId || 'new (starts with your next message)'),
+    row('Version', d.version || '?'),
+    ...(d.local ? [{ kind: 'dim', text: 'Server health not re-checked for this tip; /status checks it live.' }] : [])
+  ];
+}
+
+export function contextModel(d = {}) {
+  const rules = d.rules;
+  const ruleFiles = rules?.files || [];
+  const out = [
+    { kind: 'head', text: 'Context' },
+    row('Model', modelText(d.ctx, d.choice)),
+    row('Conversation', !d.conversationId ? 'new, nothing sent yet' : d.server ? `${d.server.tokensText}${d.server.turnsText ? ` · ${d.server.turnsText}` : ''}` : `${n(d.tokens)} tokens reported so far in this session${d.serverError ? ` (server context: ${d.serverError})` : ''}`),
+    ...(d.conversationId && d.server ? [row('Summary', d.server.summaryText)] : []),
+    row('Rules', d.rulesOn === false ? 'off for this session (/rules on)' : ruleFiles.length ? `${ruleFiles.length} QUOX.md file${ruleFiles.length === 1 ? '' : 's'}, ${n(rules.totalChars)} chars${rules.truncated ? ' (truncated to fit)' : ''}` : 'none loaded')
+  ];
+  if (d.rulesOn !== false) for (const f of ruleFiles) out.push({ kind: 'dim', key: '', text: `  ${f.label || f.path}  ${n(f.chars)} chars` });
+  const sk = d.skills;
+  out.push(row('Skills', !sk ? '? not checked (/context checks it live)' : sk.ok ? `${sk.count} available in your org (/skills)` : `? ${sk.error}`));
+  const mem = d.memory;
+  out.push(row('Memory', !mem ? '? not checked (/context checks it live)' : mem.ok ? 'connected (persistent memory answers)' : `not reachable: ${mem.error}`));
+  out.push(row('Agent', d.agent || 'CommanderQ (quox)'));
+  return out;
+}
+
+const icon = (s) => (s === 'pass' ? '✔' : s === 'warn' ? '⚠' : s === 'skip' ? '·' : '✖');
+
+/** checks: [{ name, status:'pass'|'warn'|'fail'|'error'|'skip', detail?, latency_ms? }] */
+export function doctorModel(platform, chat, platformError = null) {
+  const rowOf = (c) => ({ kind: c.status === 'skip' ? 'dim' : 'row', key: `${icon(c.status)} ${c.name}`, text: [c.detail, c.latency_ms != null ? `${c.latency_ms}ms` : null].filter(Boolean).join(' · ') || (c.status === 'pass' ? 'ok' : c.status) });
+  const out = [{ kind: 'head', text: 'Doctor' }];
+  if (platformError) out.push(row('✖ quox doctor', platformError));
+  for (const c of platform || []) out.push(rowOf(c));
+  out.push({ kind: 'gap' }, { kind: 'head', text: 'Chat' });
+  for (const c of chat || []) out.push(rowOf(c));
+  const all = [...(platform || []), ...(chat || [])];
+  const count = (s) => all.filter(c => c.status === s || (s === 'fail' && c.status === 'error')).length;
+  out.push({ kind: 'gap' }, { kind: 'dim', text: `${count('pass')} passed · ${count('warn')} warning${count('warn') === 1 ? '' : 's'} · ${count('fail')} failed` });
+  return out;
+}
+
+/** Chat checks, each on its own: the chat routes answer, a provider is connected, the capability contract. */
+export async function chatChecks(api, providerTypes = ['openai', 'anthropic', 'ollama']) {
+  const one = async (name, fn) => { try { return { name, ...(await fn()) }; } catch (e) { return { name, status: 'fail', detail: e?.status ? `HTTP ${e.status} ${e.message || ''}`.trim() : (e?.message || 'failed') }; } };
+  return Promise.all([
+    one('Chat server', async () => {
+      if (!api.conversations) return { status: 'skip', detail: 'not available in this mode' };
+      const t0 = Date.now(); await api.conversations(1);
+      return { status: 'pass', detail: 'conversation routes answer for this login', latency_ms: Date.now() - t0 };
+    }),
+    one('AI provider', async () => {
+      if (!api.connections) return { status: 'skip', detail: 'not available in this mode' };
+      const r = await api.connections();
+      if (!r.ok) return { status: 'fail', detail: `could not read the vault: ${r.error}` };
+      const have = providerTypes.filter(t => r.rows.some(x => x.integration_type === t));
+      return have.length ? { status: 'pass', detail: `connected: ${have.join(', ')}` } : { status: 'warn', detail: 'no AI provider in your org vault; /connect openai' };
+    }),
+    one('Capabilities', async () => {
+      if (!api.capabilities) return { status: 'skip', detail: 'not available in this mode' };
+      const res = await api.capabilities();
+      if (res && res.ok === false) return res.missing ? { status: 'warn', detail: 'this server has no capability contract yet (GET /api/v1/capabilities)' } : { status: 'fail', detail: res.error || 'failed' };
+      const m = capabilityMap(res);
+      if (!m) return { status: 'warn', detail: 'unexpected capability response' };
+      const off = Object.entries(m).filter(([, v]) => v && v.available === false).map(([k]) => k);
+      return { status: off.length ? 'warn' : 'pass', detail: `${Object.keys(m).length} known${off.length ? `, unavailable: ${off.slice(0, 6).join(', ')}` : ', all available'}` };
+    })
+  ]);
+}

package/lib/quoxon/slash/picker.js

@@ -0,0 +1,38 @@
+/**
+ * A modal list under the composer (the /resume picker, the /config card). While open it takes every key,
+ * like the /connect card: Up/Down select, Enter picks, Esc closes, Left/Right/Space go to onAdjust.
+ */
+export function createPicker({ refresh = () => {} } = {}) {
+  let cur = null; // { title, rows, sel, hint, onPick, onAdjust, onClose, rowsFn }
+  const close = () => { const c = cur; cur = null; c?.onClose?.(); refresh(); };
+  return {
+    isOpen: () => Boolean(cur),
+    open(spec) { cur = { sel: 0, ...spec }; refresh(); },
+    close,
+    rows: () => (cur ? (cur.rowsFn ? cur.rowsFn() : cur.rows) : []),
+    onEvent(e) {
+      if (!cur) return false;
+      const rows = cur.rowsFn ? cur.rowsFn() : cur.rows;
+      if (e.type !== 'key' && !(e.type === 'text' && e.text === ' ')) return true; // typing is swallowed while open
+      const name = e.type === 'text' ? 'space' : e.name;
+      if (name === 'escape' || name === 'ctrl-c') { close(); return true; }
+      if (name === 'up' && rows.length) cur.sel = (cur.sel - 1 + rows.length) % rows.length;
+      else if (name === 'down' && rows.length) cur.sel = (cur.sel + 1) % rows.length;
+      else if ((name === 'left' || name === 'right' || name === 'space') && cur.onAdjust) cur.onAdjust(cur.sel, name === 'left' ? -1 : 1);
+      else if (name === 'enter') {
+        const c = cur; const pick = rows[c.sel];
+        if (c.keepOpen?.(c.sel)) c.onPick?.(pick, c.sel);
+        else { cur = null; c.onPick?.(pick, c.sel); }
+      }
+      refresh();
+      return true;
+    },
+    view() {
+      if (!cur) return null;
+      const rows = cur.rowsFn ? cur.rowsFn() : cur.rows;
+      const max = 10;
+      const start = Math.max(0, Math.min(cur.sel - max + 1, rows.length - max));
+      return { title: cur.title, rows: rows.slice(start, start + max), sel: cur.sel - start, more: Math.max(0, rows.length - max), hint: cur.hint, empty: cur.empty };
+    }
+  };
+}

package/lib/quoxon/slash/restart.js

@@ -0,0 +1,144 @@
+/**
+ * /restart and the "newer build installed" notice.
+ *
+ * The installed quox is whatever `quox` on PATH runs: a symlink to cli/bin/quox.js, or a small wrapper
+ * script that execs one (the dev box's ~/bin/quox). Its build is the git HEAD of that CLI tree, read
+ * locally (no fetch, no network). The running build is that HEAD captured when this client started, so a
+ * refresh of the tree under a running client shows up as "newer installed".
+ */
+import { execFile, execFileSync, spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+
+/** The CLI tree this code runs from (…/cli). */
+export const RUNNING_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+export const NEWER_NOTICE = 'A newer quox is installed. /restart to use it.';
+export const DIFFERENT_NOTICE = 'A different quox build is installed. /restart to use it.';
+
+export function findOnPath(name = 'quox', env = process.env) {
+  for (const dir of String(env.PATH || '').split(delimiter)) {
+    if (!dir) continue;
+    const p = join(dir, name);
+    try { accessSync(p, constants.X_OK); if (statSync(p).isFile()) return p; } catch { /* next */ }
+  }
+  return null;
+}
+
+const isCliRoot = (d) => existsSync(join(d, 'lib', 'core', 'version.js')) && existsSync(join(d, 'bin', 'quox.js'));
+
+/** The CLI root a `quox` executable runs, or null. */
+export function cliRootOf(bin) {
+  if (!bin) return null;
+  let real;
+  try { real = realpathSync(bin); } catch { return null; }
+  if (/[/\\]bin[/\\]quox(\.js)?$/.test(real)) { const d = resolve(dirname(real), '..'); if (isCliRoot(d)) return d; }
+  try {
+    if (statSync(real).size > 65536) return null;
+    const m = /(\/[^\s"'$]+)\/bin\/quox\.js/.exec(readFileSync(real, 'utf8'));
+    if (m && isCliRoot(m[1])) return m[1];
+  } catch { /* unreadable */ }
+  return null;
+}
+
+const git = (root, args) => execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim();
+export function headOf(root) { try { return root ? git(root, ['rev-parse', '--short', 'HEAD']) || null : null; } catch { return null; } }
+/** true / false, or null when it cannot be told. */
+export function isAncestor(root, a, b) {
+  try { execFileSync('git', ['-C', root, 'merge-base', '--is-ancestor', a, b], { stdio: 'ignore', timeout: 2000 }); return true; }
+  catch (e) { return e?.status === 1 ? false : null; }
+}
+
+/**
+ * Compare the running build with the installed one. -> notice text or null. `deps` lets tests stand in for
+ * git and PATH.
+ */
+export function newerBuild({ startSha, runningRoot = RUNNING_ROOT, env = process.env, deps = {} } = {}) {
+  const d = { findOnPath, cliRootOf, headOf, isAncestor, ...deps };
+  if (!startSha) return null;
+  const root = d.cliRootOf(d.findOnPath('quox', env)) || runningRoot;
+  const head = d.headOf(root);
+  if (!head || head === startSha || head.startsWith(startSha) || startSha.startsWith(head)) return null;
+  if (d.isAncestor(root, startSha, head) === true) return NEWER_NOTICE;
+  if (d.isAncestor(root, head, startSha) === true) return null; // the installed build is older than this one: nothing to gain
+  return DIFFERENT_NOTICE; // unrelated or unknown history: say so, never claim "newer
+}
+
+/** Poll at most every `everyMs`; calls onNotice once. -> stop(). */
+export function startBuildWatch({ onNotice, everyMs = 60000, check = newerBuild, ...opts } = {}) {
+  let said = false;
+  const id = setInterval(() => {
+    if (said) return;
+    let t = null;
+    try { t = check(opts); } catch { t = null; }
+    if (t) { said = true; onNotice(t); clearInterval(id); }
+  }, everyMs);
+  id.unref?.();
+  return () => clearInterval(id);
+}
+
+/**
+ * Same arguments, minus any earlier resume target, plus --resume <id> for this conversation. The profile and
+ * session name this client is using are carried over when the original command line did not name them.
+ */
+export function restartArgs(argv = [], conversationId = null, { profile = null, name = null } = {}) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--conversation') { i++; continue; }
+    if (a === '--resume') { const n = argv[i + 1]; if (n !== undefined && !n.startsWith('-')) i++; continue; }
+    if (/^--(resume|conversation)=/.test(a)) continue;
+    out.push(a);
+  }
+  const has = (...f) => out.some(a => f.includes(a) || f.some(x => a.startsWith(`${x}=`)));
+  if (profile && !has('-p', '--profile') && !out.includes('--demo')) out.push('-p', profile);
+  if (name && !has('-n', '--name')) out.push('-n', name);
+  return conversationId ? [...out, '--resume', conversationId] : out;
+}
+
+/** The quox a restart would run: the one on PATH, else this client's own tree. -> [command, leading args]. */
+export function restartTarget(env = process.env, bin = findOnPath('quox', env)) {
+  return bin ? [bin, []] : [process.execPath, [join(RUNNING_ROOT, 'bin', 'quox.js')]];
+}
+
+/**
+ * Before the client lets go of the terminal: can the installed quox start at all? Runs `quox --version`
+ * (no network, no login). -> Promise<{ ok, bin (what runs), onPath (the PATH quox or null), version?, error? }>. A failure keeps the user in this client.
+ */
+export function checkRestart({ env = process.env, bin = findOnPath('quox', env), run = execFile, timeoutMs = 15000 } = {}) {
+  const [cmd, lead] = restartTarget(env, bin);
+  return new Promise((done) => {
+    run(cmd, [...lead, '--version'], { env, timeout: timeoutMs, encoding: 'utf8' }, (err, stdout, stderr) => {
+      if (err) {
+        const why = err.code === 'ENOENT' || err.code === 'EACCES' ? `${err.code}: it cannot be run`
+          : err.killed ? `no answer in ${Math.round(timeoutMs / 1000)} s`
+            : String(stderr || err.message || 'failed').trim().split('\n')[0].slice(0, 160);
+        return done({ ok: false, bin: cmd, onPath: bin || null, error: why });
+      }
+      done({ ok: true, bin: cmd, onPath: bin || null, version: String(stdout || '').trim().split('\n')[0] || null });
+    });
+  });
+}
+
+/** Terminal modes the client turns on (bracketed paste, focus reporting, hidden cursor): all off before the hand-over. */
+export const TERMINAL_RESTORE = '\x1b[?2004l\x1b[?1004l\x1b[?25h';
+
+/** Give the terminal back in a plain state: cooked mode, stdin paused, modes off. */
+export function restoreTerminal({ stdin = process.stdin, stdout = process.stdout } = {}) {
+  try { if (stdin?.isTTY) stdin.setRawMode?.(false); stdin?.pause?.(); } catch { /* not a tty */ }
+  try { if (stdout?.isTTY) stdout.write(TERMINAL_RESTORE); } catch { /* closed */ }
+}
+
+/**
+ * Run the installed quox in this terminal, wait for it, and hand back { code } (its exit code), or
+ * { error } when it could not be started (the caller stays in the current client and says so).
+ */
+export function execRestart({ argv, conversationId, profile = null, name = null, env = process.env, spawn = spawnSync, bin = findOnPath('quox', env), restore = restoreTerminal }) {
+  const args = restartArgs(argv, conversationId, { profile, name });
+  restore(); // the child owns the terminal now
+  const [cmd, lead] = restartTarget(env, bin);
+  const r = spawn(cmd, [...lead, ...args], { stdio: 'inherit', env });
+  if (r.error) return { error: `${r.error.code || 'failed'}: ${r.error.message}`, bin: cmd };
+  return { code: r.status ?? (r.signal ? 128 + (os.constants.signals[r.signal] || 0) : 1), bin: cmd };
+}

package/lib/quoxon/slash/resume.js

@@ -0,0 +1,59 @@
+/**
+ * /resume and `quox --resume`: pick a recent conversation, show its last turns as ordinary history, and
+ * continue it. Conversations come from GET /api/v1/conversations (title, updated_at, turn_count); the agent
+ * comes from the session index (GET /api/v1/sessions) when that answers, and names set with /rename from
+ * the local name store.
+ */
+export const RESUME_TURNS = 20;
+
+export function age(iso, now = Date.now()) {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return '?';
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.round(s / 60)}m ago`;
+  if (s < 86400) return `${Math.round(s / 3600)}h ago`;
+  return `${Math.round(s / 86400)}d ago`;
+}
+
+/** -> [{ id, title, agent, updated_at, turns }] newest first. */
+export function resumeRows(conversations = [], index = null, names = {}) {
+  const agentOf = new Map();
+  for (const r of index?.rows || []) if (r.kind === 'conversation' && r.id) agentOf.set(r.id, r.agent || null);
+  return conversations.map(c => ({
+    id: c.id,
+    title: names[c.id]?.name || c.title || '(untitled)',
+    agent: agentOf.get(c.id) ?? null,
+    updated_at: c.updated_at || null,
+    turns: c.turn_count ?? null
+  })).sort((a, b) => String(b.updated_at || '').localeCompare(String(a.updated_at || '')));
+}
+
+export const pickerRow = (r, now = Date.now()) => ({ key: r.id.slice(0, 12), text: `${r.title} · ${r.agent || 'agent not recorded'} · ${age(r.updated_at, now)}${r.turns != null ? ` · ${r.turns} turn${r.turns === 1 ? '' : 's'}` : ''}` });
+
+/** An id, an id prefix (4+), or a session name/title -> { row } | { ambiguous:[ids] } | { none:true }. */
+export function matchConversation(rows, q) {
+  const s = String(q || '').trim();
+  if (!s) return { none: true };
+  const exact = rows.find(r => r.id === s);
+  if (exact) return { row: exact };
+  const lower = s.toLowerCase();
+  const byName = rows.filter(r => r.title.toLowerCase() === lower);
+  if (byName.length === 1) return { row: byName[0] };
+  const pre = s.length >= 4 ? rows.filter(r => r.id.startsWith(s)) : [];
+  if (pre.length === 1) return { row: pre[0] };
+  const hits = byName.length ? byName : pre;
+  return hits.length > 1 ? { ambiguous: hits.map(r => r.id) } : { none: true };
+}
+
+/** Stored turns -> history items (user prompts and answers, rendered as normal history). */
+export function turnsToHistory(turns = [], max = RESUME_TURNS) {
+  const list = turns.filter(t => (t.role === 'user' || t.role === 'assistant') && String(t.content || '').trim());
+  const shown = list.slice(-max);
+  return {
+    items: shown.map(t => (t.role === 'user' ? { kind: 'user', text: String(t.content) } : { kind: 'text', text: String(t.content) })),
+    answers: shown.filter(t => t.role === 'assistant').map((t, i) => ({ id: `resumed_${i}`, text: String(t.content) })),
+    shown: shown.length,
+    total: list.length
+  };
+}