quoxcli 0.3.1 → 0.4.0

package/lib/quoxon/extensions.js

@@ -0,0 +1,276 @@
+/**
+ * Extension host (QUOXON, 2026-10-26; contract: EXTENSIONS.md). Optional npm packages that add surfaces to quoxon
+ * (a MIDI pad deck, a status bar, ...). Nothing loads unless the package is installed AND listed in
+ * ~/.quox/extensions.json (`quox ext add <pkg>`, `/ext list|on|off <name>`). Core knows nothing about any one extension:
+ * it pushes one generic snapshot (buildSnapshot) and accepts three emit actions (open_approval, pick, alert_ack).
+ * An extension can OPEN an approval or PRESELECT an answer; it can never resolve one.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+export const THROTTLE_MS = 1000;
+export const notInstalled = (name) => `not installed: npm i -g ${name}`;
+const HEALTH = new Set(['ok', 'warn', 'down']);
+const CHAIN = new Set(['ok', 'broken', 'unknown']);
+const FLEET_MAX = 16;
+
+// ---- the listing: ~/.quox/extensions.json ---------------------------------------------------------------------------
+export const extListPath = (home = os.homedir()) => path.join(home, '.quox', 'extensions.json');
+const validName = (n) => typeof n === 'string' && /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(n);
+
+export function readExtList(file = extListPath()) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return (Array.isArray(j?.extensions) ? j.extensions : []).filter((x) => validName(x?.name)).map((x) => ({ name: x.name, enabled: x.enabled !== false }));
+  } catch { return []; } // no file or unreadable: nothing is listed, so nothing loads
+}
+export function writeExtList(list, file = extListPath()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ extensions: list }, null, 2) + '\n');
+}
+export function extAdd(name, file = extListPath()) {
+  if (!validName(name)) return { ok: false, text: `"${name}" is not a package name.` };
+  const list = readExtList(file);
+  const had = list.find((x) => x.name === name);
+  if (had) had.enabled = true; else list.push({ name, enabled: true });
+  writeExtList(list, file);
+  return { ok: true, text: `${name} is listed. It loads in quoxon once installed (npm i -g ${name}).` };
+}
+export function extRemove(name, file = extListPath()) {
+  const list = readExtList(file);
+  if (!list.some((x) => x.name === name)) return { ok: false, text: `${name} is not listed.` };
+  writeExtList(list.filter((x) => x.name !== name), file);
+  return { ok: true, text: `${name} is no longer listed.` };
+}
+export function extSetEnabled(name, enabled, file = extListPath()) {
+  const list = readExtList(file);
+  const it = list.find((x) => x.name === name);
+  if (!it) return { ok: false, text: `${name} is not listed. quox ext add ${name}` };
+  it.enabled = enabled; writeExtList(list, file);
+  return { ok: true, text: `${name} ${enabled ? 'enabled' : 'disabled'}.` };
+}
+
+// ---- resolution: env override, local, global ------------------------------------------------------------------------
+export const envKey = (name) => `QUOX_EXT_${String(name).replace(/^@/, '').replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()}_MODULE`;
+const defaultImporter = (spec) => import(spec);
+const NOT_FOUND = (e) => e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND';
+
+let npmRootCache; // `npm root -g` runs at most once per process
+export function globalNpmRoot(run = execFileSync) {
+  if (npmRootCache !== undefined) return npmRootCache;
+  try { npmRootCache = String(run('npm', ['root', '-g'], { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] })).trim() || null; } catch { npmRootCache = null; }
+  return npmRootCache;
+}
+export const _resetNpmRootCache = () => { npmRootCache = undefined; };
+
+/** The file a package directory imports: exports["."] (import/default), module, main, index.js. */
+export function packageEntry(dir) {
+  try {
+    const pj = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const ex = pj.exports;
+    const root = typeof ex === 'string' ? ex : (ex?.['.'] ?? ex);
+    const pick = typeof root === 'string' ? root : (root?.import || root?.default || (typeof root?.import === 'object' ? root.import.default : null));
+    return path.join(dir, pick || pj.module || pj.main || 'index.js');
+  } catch { return path.join(dir, 'index.js'); }
+}
+
+/**
+ * Find and import one extension. Order: QUOX_EXT_<NAME>_MODULE, local import(name), then the global npm root
+ * (dirname(execPath)/../lib/node_modules first, which costs no spawn; `npm root -g` once, cached, only if that misses).
+ * -> { ok:true, mod, where } | { ok:false, notFound:true, tried:[...] } | { ok:false, error }
+ */
+export async function resolveExtension(name, { env = process.env, importer = defaultImporter, execPath = process.execPath, npmRoot = globalNpmRoot, exists = fs.existsSync } = {}) {
+  const tried = [];
+  const ov = env?.[envKey(name)];
+  if (ov) {
+    tried.push(`${envKey(name)}=${ov}`);
+    try { return { ok: true, mod: await importer(path.isAbsolute(ov) ? pathToFileURL(ov).href : ov), where: `env ${envKey(name)} (${ov})` }; }
+    catch (e) { return { ok: false, error: e?.message || String(e), tried }; } // an override that fails is an error, never a silent fall-through
+  }
+  tried.push(`local import('${name}')`);
+  try { return { ok: true, mod: await importer(name), where: `local (${name})` }; }
+  catch (e) { if (!NOT_FOUND(e)) return { ok: false, error: e?.message || String(e), tried }; }
+  const roots = [];
+  const guess = path.join(path.dirname(execPath || ''), '..', 'lib', 'node_modules');
+  roots.push(guess);
+  let spawned = false;
+  for (let i = 0; i < 2; i++) {
+    for (const root of roots.splice(0)) {
+      const dir = path.join(root, name);
+      tried.push(`global ${dir}`);
+      if (!exists(dir)) continue;
+      try { return { ok: true, mod: await importer(pathToFileURL(packageEntry(dir)).href), where: `global (${dir})` }; }
+      catch (e) { return { ok: false, error: e?.message || String(e), tried }; }
+    }
+    if (spawned) break;
+    spawned = true;
+    const g = npmRoot();
+    if (g && path.resolve(g) !== path.resolve(guess)) roots.push(g);
+  }
+  return { ok: false, notFound: true, tried };
+}
+
+/** An extension module -> { name, version, commands, create } or null. Accepts default export or the module itself. */
+export function normalizeExtension(mod, fallbackName) {
+  const ext = mod?.default && typeof mod.default === 'object' ? mod.default : mod;
+  const create = typeof ext?.create === 'function' ? ext.create : (typeof mod?.createDeck === 'function' ? mod.createDeck : null); // createDeck: quoxdeck v1
+  if (!create) return null;
+  const commands = (Array.isArray(ext.commands) ? ext.commands : []).filter((c) => /^\/[a-z][\w-]*$/i.test(c?.name || '') && typeof c.run === 'function');
+  return { name: ext.name || fallbackName, version: ext.version || null, commands, create };
+}
+
+// ---- the snapshot every extension gets ------------------------------------------------------------------------------
+function itemRisk(it) {
+  return it?.privileged === true || it?.payload?.privileged === true || it?.risk === 'high' || it?.payload?.risk === 'high' ? 'high' : 'low';
+}
+const hostState = (s) => (s === 'ok' || s === 'warn' || s === 'down' ? s : (/^(down|offline|failed|unreachable)$/i.test(s || '') ? 'down' : (/^(warn|warning|degraded)$/i.test(s || '') ? 'warn' : 'ok')));
+
+/** Pure. fleet input: [{id|name, health|state}] or null. */
+export function buildFleet(hosts) {
+  if (!Array.isArray(hosts)) return { total: 0, online: 0, offline: 0, warn: 0, hosts: [] };
+  const list = hosts.map((h) => ({ name: String(h.name ?? h.id ?? '').slice(0, 60), state: hostState(h.state ?? h.health) }));
+  return {
+    total: list.length, online: list.filter((h) => h.state !== 'down').length,
+    offline: list.filter((h) => h.state === 'down').length, warn: list.filter((h) => h.state === 'warn').length,
+    hosts: list.slice(0, FLEET_MAX)
+  };
+}
+
+export function buildSnapshot({ org = null, items = [], health = {}, loops = [], event = null, fleet = null, evidence = null, sessions = null } = {}) {
+  const list = (items || []).map((it, i) => {
+    const row = {
+      n: i + 1, id: it.id ?? null, risk: itemRisk(it),
+      title: String(it.title || it.summary || it.payload?.title || it.payload?.question || it.payload?.summary || '').slice(0, 120),
+      agent: it.agent || it.requester || it.payload?.agent || null
+    };
+    const opts = Array.isArray(it.payload?.options) ? it.payload.options.filter((o) => o?.key != null).map((o) => ({ key: String(o.key), label: String(o.label ?? o.key) })) : [];
+    if (opts.length) row.options = opts;
+    return row;
+  });
+  const h = {};
+  for (const [k, v] of Object.entries(health || {})) if (HEALTH.has(v)) h[k] = v;
+  const state = {
+    org: { id: org?.id ?? null, name: org?.name ?? null },
+    approvals: { count: list.length, items: list },
+    health: h,
+    loops: (loops || []).map((l) => ({ id: l.id, title: String(l.title || ''), turn: Number(l.turn) || 0, max: Number(l.max) || 0, status: l.status || 'running' })),
+    fleet: Array.isArray(fleet) ? buildFleet(fleet) : (fleet && typeof fleet === 'object' ? { total: fleet.total | 0, online: fleet.online | 0, offline: fleet.offline | 0, warn: fleet.warn | 0, hosts: (fleet.hosts || []).slice(0, FLEET_MAX) } : buildFleet(null)),
+    evidence: { chain: CHAIN.has(evidence?.chain) ? evidence.chain : 'unknown', checked_at: evidence?.checked_at ?? null },
+    sessions: { active: Math.max(0, Number(sessions?.active) || 0) }
+  };
+  if (event) state.event = { kind: event.kind, text: event.text, level: event.level || 'info' };
+  return state;
+}
+
+/** What the composer is filled with when an extension picks an option; the user still presses Enter. null = nothing to preselect. */
+export function pickDraft(item, n, option) {
+  if (!item) return null;
+  const opt = String(option ?? '').trim();
+  if (!opt) return null;
+  const keys = (item.payload?.options || []).map((o) => String(o.key));
+  if (keys.length) return keys.includes(opt) ? `/answer ${n} ${opt}` : null;
+  if (/^(y|yes|approve)$/i.test(opt)) return `/approve ${n}`;
+  if (/^(n|no|deny)$/i.test(opt)) return `/deny ${n} `;
+  return null;
+}
+
+// ---- the host -------------------------------------------------------------------------------------------------------
+/**
+ * handlers: { openApproval(n), preselect(n, option), changed() } are the window's own actions. getSettings() feeds create().
+ * Loaded extensions all receive the same deduped, 1/s-throttled snapshot.
+ */
+export function createExtensionHost({ importer = defaultImporter, env = process.env, execPath, npmRoot, exists, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout,
+  handlers = {}, log = () => {}, getSettings = () => ({}) } = {}) {
+  const loaded = new Map(); // name -> { ext, inst, where }
+  const starting = new Map();
+  let lastSent = 0; let lastKey = null; let pending = null; let timer = null;
+  let event = null; const prevLoops = new Map(); let prevCount = null;
+
+  const sendAll = (state) => {
+    const key = JSON.stringify(state);
+    if (key === lastKey) return;
+    lastKey = key; lastSent = now();
+    for (const [name, l] of loaded) { try { l.inst?.update?.(state); } catch (e) { log(`extension ${name} update failed: ${e?.message || e}`); } }
+  };
+  const flush = () => { timer = null; if (pending && loaded.size) { const s = pending; pending = null; sendAll(s); } };
+
+  const emitFor = (name) => (msg) => {
+    if (!loaded.has(name) || !msg || typeof msg !== 'object') return false; // ignored unless this extension is loaded
+    try {
+      if (msg.type === 'open_approval' && Number.isInteger(msg.n) && msg.n >= 1) { handlers.openApproval?.(msg.n); return true; }
+      if (msg.type === 'pick' && Number.isInteger(msg.n) && msg.n >= 1) { handlers.preselect?.(msg.n, msg.option); return true; }
+      if (msg.type === 'alert_ack') { event = null; handlers.changed?.(); return true; }
+    } catch (e) { log(`extension ${name} emit failed: ${e?.message || e}`); }
+    return false;
+  };
+
+  const host = {
+    armed: () => loaded.size > 0,
+    isLoaded: (name) => loaded.has(name),
+    loadedNames: () => [...loaded.keys()],
+    where: (name) => loaded.get(name)?.where || null,
+    /** emit as one extension (tests and the shim); extensions get their own bound emit in create(). */
+    emit: (msg, name) => (name ? emitFor(name)(msg) : [...loaded.keys()].some((n) => emitFor(n)(msg))),
+    async load(name) {
+      if (loaded.has(name)) return { ok: true, text: `${name} is already loaded.` };
+      if (starting.has(name)) return starting.get(name);
+      const p = (async () => {
+        try {
+          const r = await resolveExtension(name, { env, importer, execPath, npmRoot, exists });
+          if (!r.ok && r.notFound) return { ok: false, notFound: true, text: `${name} ${notInstalled(name)} (looked in: ${r.tried.join('; ')})`, tried: r.tried };
+          if (!r.ok) return { ok: false, text: `${name} could not load: ${r.error}` };
+          const ext = normalizeExtension(r.mod, name);
+          if (!ext) return { ok: false, text: `${name} could not load: the package has no create().` };
+          let inst;
+          try { inst = ext.create({ emit: emitFor(name), log, settings: getSettings() }); } catch (e) { return { ok: false, text: `${name} could not start: ${e?.message || e}` }; }
+          loaded.set(name, { ext, inst, where: r.where });
+          lastKey = null; lastSent = 0; pending = null; event = null; prevLoops.clear(); prevCount = null;
+          handlers.changed?.();
+          return { ok: true, text: `${ext.name} is on (found: ${r.where}).`, ext };
+        } finally { starting.delete(name); }
+      })();
+      starting.set(name, p);
+      return p;
+    },
+    unload(name) {
+      const l = loaded.get(name);
+      if (!l) return { ok: true, text: `${name} was not loaded.` };
+      loaded.delete(name);
+      if (!loaded.size) { pending = null; lastKey = null; if (timer) { clearTimer(timer); timer = null; } }
+      try { l.inst?.close?.(); } catch (e) { log(`extension ${name} close failed: ${e?.message || e}`); }
+      handlers.changed?.();
+      return { ok: true, text: `${name} is off.` };
+    },
+    unloadAll() { for (const n of [...loaded.keys()]) host.unload(n); },
+    /** Slash commands of loaded extensions only. -> [{ name, help, ext }] */
+    commands: () => [...loaded.values()].flatMap((l) => l.ext.commands.map((c) => ({ name: c.name, help: c.help || '', ext: l.ext.name }))),
+    async runCommand(cmd, args, ctx = {}) {
+      for (const l of loaded.values()) {
+        const c = l.ext.commands.find((x) => x.name === cmd);
+        if (c) { try { return { handled: true, result: await c.run(args, { ...ctx, extension: l.ext.name, loaded: host.loadedNames() }) }; } catch (e) { return { handled: true, error: e?.message || String(e) }; } }
+      }
+      return { handled: false };
+    },
+    /** Push the current snapshot inputs: derives an event from changes, throttles to one update per second. */
+    push(input) {
+      if (!loaded.size) return;
+      const items = input?.items || [];
+      for (const l of input?.loops || []) {
+        const was = prevLoops.get(l.id);
+        if (was && was !== l.status && (l.status === 'done' || l.status === 'failed')) event = { kind: 'loop', text: `${l.title || l.id} ${l.status}`, level: l.status === 'failed' ? 'error' : 'ok' };
+        prevLoops.set(l.id, l.status);
+      }
+      if (prevCount != null && items.length > prevCount) event = { kind: 'approval', text: `${items.length} waiting`, level: 'warn' };
+      prevCount = items.length;
+      const state = buildSnapshot({ ...input, event });
+      const wait = THROTTLE_MS - (now() - lastSent);
+      if (wait <= 0 && !timer) { pending = null; sendAll(state); return; }
+      pending = state;
+      if (!timer) timer = setTimer(flush, Math.max(wait, 0));
+    }
+  };
+  return host;
+}

package/lib/quoxon/inboxView.js

@@ -0,0 +1,79 @@
+/**
+ * HITL-INBOX-BAR (owner 2026-10-26): the owner's Quox inbox in the chat. Pure helpers: the status-area bar text,
+ * the arrival line, the /inbox table and the one-item view. No I/O here; app.js owns the calls.
+ */
+const clip = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, Math.max(0, n - 1))}…` : t; };
+const pad = (s, n) => { const t = clip(s, n); return t + ' '.repeat(Math.max(0, n - [...t].length)); };
+const ms = (v) => { const t = Date.parse(String(v ?? '').includes('T') || !v ? v : `${String(v).replace(' ', 'T')}Z`); return Number.isFinite(t) ? t : 0; };
+const CLOSED = new Set(['resolved', 'cancelled', 'expired', 'deleted', 'archived']);
+
+/** Newest first. */
+export const newestFirst = (items) => [...(Array.isArray(items) ? items : [])].filter((i) => i && i.id).sort((a, b) => ms(b.created_at ?? b.createdAt) - ms(a.created_at ?? a.createdAt));
+/** Unread = the server's per-user is_read flag is not set, and the item is not closed or archived. */
+export const isUnread = (it) => !it.is_read && !it.archived_at && !CLOSED.has(String(it.status || '').toLowerCase());
+export const unreadItems = (items) => newestFirst(items).filter(isUnread);
+
+/** The status-area line, or '' when nothing is unread: `📨 2 new · <newest title>`. */
+export function inboxBarText(items, cols = 80) {
+  const un = unreadItems(items);
+  if (!un.length) return '';
+  const head = `📨 ${un.length} new · `;
+  return head + clip(un[0].title || un[0].kind || 'untitled', Math.max(8, cols - 4 - [...head].length));
+}
+
+/** Unread items not seen on an earlier poll. `seen` is a Set of ids; the first poll seeds it and announces nothing. */
+export function arrivals(items, seen) {
+  const un = unreadItems(items);
+  const fresh = seen ? un.filter((i) => !seen.has(i.id)) : [];
+  return { fresh, ids: new Set((Array.isArray(items) ? items : []).map((i) => i?.id).filter(Boolean)) };
+}
+export const arrivalLine = (it) => `📨 ${clip(it.title || it.kind || 'untitled', 70)} · /inbox 1`;
+
+export const fromOf = (it) => String(it.created_by_name || it.payload?.source || it.payload?.approval_context?.source_label || it.source || it.inbox_type || it.kind || 'system');
+export function ageOf(v, now = Date.now()) {
+  const t = ms(v); if (!t) return '?';
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 90) return 'now';
+  if (s < 5400) return `${Math.round(s / 60)}m`;
+  if (s < 129600) return `${Math.round(s / 3600)}h`;
+  return `${Math.round(s / 86400)}d`;
+}
+
+/** The latest 10 as a compact table; unread rows carry a dot. -> [{ text, tone }] */
+export function inboxTable(items, now = Date.now(), cols = 100, max = 10) {
+  const rows = newestFirst(items).slice(0, max);
+  if (!rows.length) return [{ text: 'Your inbox is empty.', tone: 'dim' }];
+  const tw = Math.max(16, Math.min(60, cols - 40));
+  const out = [{ text: `  ${pad('#', 3)}${pad('when', 6)}${pad('from', 14)}${pad('title', tw)} state`, tone: 'dim' }];
+  rows.forEach((it, i) => {
+    const un = isUnread(it);
+    out.push({ text: `${un ? '●' : ' '} ${pad(i + 1, 3)}${pad(ageOf(it.created_at ?? it.createdAt, now), 6)}${pad(fromOf(it), 14)}${pad(it.title || it.kind || 'untitled', tw)} ${un ? 'unread' : (it.status || 'read')}`, tone: un ? 'accent' : 'dim' });
+  });
+  const un = unreadItems(items).length;
+  out.push({ text: `${un} unread · /inbox N open one · /inbox read N|all · /inbox open N (approvals)`, tone: 'dim' });
+  return out;
+}
+
+/** Arg grammar: '' | N | read N|all | open N. -> { kind, n?|all? } | { kind:'usage' } */
+export function parseInbox(arg) {
+  const a = String(arg || '').trim().toLowerCase();
+  if (!a || a === 'list' || a === 'latest') return { kind: 'list' };
+  let m = /^(?:show\s+)?#?(\d+)$/.exec(a); if (m) return { kind: 'show', n: Number(m[1]) };
+  m = /^open\s+#?(\d+)$/.exec(a); if (m) return { kind: 'open', n: Number(m[1]) };
+  m = /^read\s+(all|#?\d+)$/.exec(a); if (m) return m[1] === 'all' ? { kind: 'read', all: true } : { kind: 'read', n: Number(m[1].replace('#', '')) };
+  return { kind: 'usage' };
+}
+export const INBOX_USAGE = 'Usage: /inbox | /inbox N | /inbox read N|all | /inbox open N';
+
+/** One item in full. -> [{ text, tone }] */
+export function inboxDetail(it, now = Date.now()) {
+  const p = it.payload || {};
+  const body = it.body || it.message || p.message || p.body || p.summary || p.text || '';
+  const out = [{ text: `${it.title || it.kind || 'untitled'}`, tone: 'accent' },
+    { text: `from ${fromOf(it)} · ${ageOf(it.created_at ?? it.createdAt, now)} ago · ${it.kind || 'item'} · ${it.priority || 'normal'} · ${it.status || '?'}`, tone: 'dim' }];
+  if (body) for (const l of String(body).split('\n')) out.push({ text: l, tone: 'text' });
+  if (it.dashboard_url) out.push({ text: it.dashboard_url, tone: 'dim' });
+  return out;
+}
+/** Approval-type items route to /approvals (the existing view). */
+export const isApprovalItem = (it) => String(it.kind || '').toLowerCase() === 'approval' || Boolean(it.payload?.approval_context) || it.payload?.type === 'decision';

package/lib/quoxon/installCli.js

@@ -0,0 +1,79 @@
+/**
+ * LAZY-AI-CLI (owner 2026-10-19): "Quox can depend heavily on your choice or blend of Claude and OpenAI models.
+ * We advise installing both Claude Code and Codex." Draw people in step by step: when something needs a vendor CLI
+ * that is missing, offer to install it THEN, as a y/N.
+ *
+ * ONE flow behind `quox provider install` and the TUI offer cards (first-run suggestion + just-in-time), so they
+ * cannot drift. The server downloads the vendor's own npm package (never a binary Quox ships), as the Quox service
+ * user, into a volume that survives updates, audited start and finish (services/collector/routes/providerCli.js).
+ */
+import { detectCallerSource } from '../core/callerSource.js';
+
+export const INSTALL_TOOLS = {
+  'claude-code': { id: 'claude-code', name: 'Claude Code', vendor: 'Anthropic', bin: 'claude', after: 'Claude sign-in is available now: sign in from the dashboard Terminal, then pick Claude in /model.' },
+  codex: { id: 'codex', name: 'Codex', vendor: 'OpenAI', bin: 'codex', after: 'Codex is ready: sign in to ChatGPT from the dashboard Terminal (Codex), then pick it in /model.' },
+};
+
+export const SUGGEST_LINE = 'Quox works best with both Claude and OpenAI models. We suggest installing Claude Code and Codex.';
+
+const ALIASES = { claude: 'claude-code', 'claude-code': 'claude-code', claudecode: 'claude-code', codex: 'codex', 'openai-codex': 'codex' };
+export const toolFor = (s) => ALIASES[String(s || '').trim().toLowerCase()] || null;
+
+const sizeText = (p) => (p?.downloadMb ? `about ${p.downloadMb} MB` : null);
+
+export function planLine(p) {
+  const t = INSTALL_TOOLS[p?.id] || { name: p?.name || p?.id };
+  const size = sizeText(p);
+  return `${t.name} ${p?.version || ''} (${t.vendor ? `${t.vendor}'s ` : ''}${p?.package || ''}) from ${p?.source || 'registry.npmjs.org'}${size ? `, ${size} download` : ''}${p?.installedMb ? `, ${p.installedMb} MB on disk` : ''}. It installs on this server as the Quox service user and stays across updates.`.replace(/\s+/g, ' ');
+}
+
+export function offerQuestion(tool, plan) {
+  const t = INSTALL_TOOLS[tool];
+  const size = sizeText(plan);
+  return `${t.name} isn't installed on this server. Install it now? (${size ? `${size} from npm` : 'from npm'})`;
+}
+
+/** The CLIs the server says are missing, in a stable order. */
+export function missingTools(status) {
+  if (!status?.ok || !Array.isArray(status.tools)) return [];
+  return Object.keys(INSTALL_TOOLS).filter((id) => status.tools.some((t) => t.id === id && t.installed === false));
+}
+
+/** An agent (a session, an attached agent, a Claude process) never self-approves an install: it files a card. */
+export function isAgentCaller(env = process.env, detect = detectCallerSource) {
+  if (env.QUOX_AGENT_ID || env.QUOX_SESSION_ID || env.QUOX_SESSION) return true;
+  let src = null;
+  try { src = detect(env); } catch { src = null; }
+  if (!src) return false;
+  if (['attached_agent', 'held_slot', 'QUOX_STREAM'].includes(src.via)) return true;
+  return src.via === 'process' && /^claude\b/i.test(String(src.label || ''));
+}
+
+const POLL_MS = 3000;
+
+/**
+ * Start the server install and wait for it. Never throws.
+ * @returns {Promise<{ok:boolean, version?:string|null, lines:string[]}>}
+ */
+export async function runInstall(api, tool, { approvalId = null, onProgress = () => {}, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, timeoutMs = 15 * 60 * 1000 } = {}) {
+  const t = INSTALL_TOOLS[tool];
+  if (!t) return { ok: false, lines: [`No installable CLI called "${tool}". Use one of: ${Object.keys(INSTALL_TOOLS).join(', ')}`] };
+  const start = await api.providerCliInstall(tool, { approvalId });
+  if (!start?.ok || !start.job_id) {
+    if (start?.status === 404 || start?.status === 405) return { ok: false, lines: [`This Quox server is too old to install ${t.name} for you. Update it first: quox server update`] };
+    if (start?.status === 403) return { ok: false, lines: [`✖ ${start.error || 'Only an instance admin can install software on this server.'} Nothing was installed.`] };
+    return { ok: false, lines: [`✖ ${t.name} was not installed: ${start?.error || 'the server did not start the install'}`] };
+  }
+  const began = now();
+  let last = began;
+  for (;;) {
+    await sleep(POLL_MS);
+    const j = await api.providerCliJob(start.job_id);
+    if (j?.state === 'done' && j.ok) {
+      return { ok: true, version: j.version || null, lines: [`✔ ${t.name} ${j.version || ''} is installed on this server.`.replace(/\s+/g, ' ').replace(' .', '.'), t.after] };
+    }
+    if (j?.state === 'failed') return { ok: false, lines: [`✖ ${t.name} was not installed: ${j.error || 'the install failed'}`] };
+    if (now() - began >= timeoutMs) return { ok: false, lines: [`◐ ${t.name} is still running its install on the server. Check again shortly: quox provider list`] };
+    if (now() - last >= 15000) { last = now(); onProgress(`◐ installing ${t.name} (${Math.round((now() - began) / 1000)}s)`); }
+  }
+}

package/lib/quoxon/keys.js

@@ -68,7 +68,7 @@ const CSI_KEYS = {
 const CSI_LIST = Object.keys(CSI_KEYS).sort((a, b) => b.length - a.length);
 
 const CTRL = {
-  '\x01': 'home', '\x05': 'end', '\x03': 'ctrl-c', '\x04': 'ctrl-d', '\x07': 'ctrl-g',
+  '\x01': 'home', '\x05': 'end', '\x03': 'ctrl-c', '\x04': 'ctrl-d', '\x07': 'ctrl-g', '\x12': 'ctrl-r',
   '\x0b': 'kill-line-forward', '\x0f': 'ctrl-o', '\x13': 'ctrl-s', '\x15': 'kill-line', '\x17': 'delete-word',
   '\x1f': 'undo', '\x19': 'redo', '\x0a': 'newline', '\x7f': 'backspace', '\x08': 'backspace',
   '\r': 'enter', '\t': 'tab', '\x02': 'left', '\x06': 'right'
@@ -118,7 +118,7 @@ export function parseChunk(chunk, state = initialKeyState(), draft = '') {
     const run = /^[^\x00-\x1f\x7f]+/.exec(s);
     if (run) { events.push({ type: 'text', text: run[0] }); s = s.slice(run[0].length); continue; }
     const c = s[0];
-    if (CTRL[c]) { events.push({ type: 'key', name: CTRL[c] }); }
+    if (CTRL[c]) { events.push(c === '\x01' ? { type: 'key', name: CTRL[c], via: 'ctrl-a' } : { type: 'key', name: CTRL[c] }); } // via: a double Ctrl+A selects all (app.js)
     s = s.slice(1);
   }
   return { events: coalesceBurst(events, draft), state: st };