quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/markdown.js

@@ -13,23 +13,14 @@
  */
 import React from 'react';
 import { Box, Text, Transform } from 'ink';
-import { Lexer } from 'marked';
 import { graphemes } from './textBuffer.js';
-import { c, mono, clip, gradient, bulletRole } from './theme.js';
+import { c, mono, gradient, bulletRole } from './theme.js';
 
 const h = React.createElement;
 
-export const lex = (src) => new Lexer({ gfm: true, breaks: false }).lex(src);
+import { lex, splitSettled } from './markdownSettle.js';
 
-export function splitSettled(text) {
-  const tokens = lex(text);
-  let last = -1;
-  for (let i = tokens.length - 1; i >= 0; i--) if (tokens[i].type !== 'space') { last = i; break; }
-  if (last <= 0) return { settled: '', rest: text };
-  let off = 0;
-  for (let i = 0; i < last; i++) off += tokens[i].raw.length;
-  return { settled: text.slice(0, off), rest: text.slice(off) };
-}
+export { lex, splitSettled }; // QUOXON-LATENCY: defined in markdownSettle.js so --print never loads Ink
 
 export function healInline(text) {
   let t = text;
@@ -128,22 +119,55 @@ function inline(tokens = [], style = {}, key = 'i') {
 const w = (s) => graphemes(s).length;
 const padTo = (s, n) => s + ' '.repeat(Math.max(0, n - w(s)));
 
-/** Plain-text table layout: returns { mode: 'grid'|'vertical', lines: [{ text, head? }] }. Pure, for tests. */
+/** Hard-wrap plain text to `width` columns at word boundaries (long words split). Never drops text. Always >= 1 line. */
+export function wrapCell(text, width) {
+  const width_ = Math.max(1, width);
+  const out = [];
+  for (const para of String(text ?? '').split('\n')) {
+    let cur = '';
+    for (const word of para.split(/\s+/).filter(Boolean)) {
+      let g = graphemes(word).map(x => x.text);
+      if (cur && w(cur) + 1 + g.length <= width_) { cur += ' ' + word; continue; }
+      if (cur) { out.push(cur); cur = ''; }
+      while (g.length > width_) { out.push(g.slice(0, width_).join('')); g = g.slice(width_); }
+      cur = g.join('');
+    }
+    out.push(cur);
+  }
+  return out;
+}
+
+/**
+ * Plain-text table layout: { mode: 'grid'|'vertical', lines: [{ text, head?, rule? }] }. Pure, for tests.
+ * Grid when it fits, else vertical key/value blocks whose values wrap under a hanging indent. No cell is ever truncated
+ * (TUI-UX #3: the grounding warning named an id that sat in a clipped cell).
+ */
 export function layoutTable(header, rows, cols) {
   const n = header.length;
   const widths = header.map((hd, i) => Math.max(w(hd), ...rows.map(r => w(r[i] ?? '')), 1));
   const total = widths.reduce((a, b) => a + b, 0) + 3 * (n - 1);
-  if (total <= cols) {
-    const line = (r) => r.map((cell, i) => padTo(cell ?? '', widths[i])).join(' │ ').replace(/\s+$/, '');
-    const rule = widths.map(x => '─'.repeat(x)).join('─┼─');
-    return { mode: 'grid', lines: [{ text: line(header), head: true }, { text: rule, rule: true }, ...rows.map(r => ({ text: line(r) }))] };
-  }
-  // too wide: vertical key: value, one block per row
+  const gridLines = (ws) => {
+    const cellLines = (r) => {
+      const cells = r.map((cell, i) => wrapCell(cell ?? '', ws[i]));
+      const h_ = Math.max(...cells.map(x => x.length));
+      return Array.from({ length: h_ }, (_, k) => cells.map((x, i) => padTo(x[k] ?? '', ws[i])).join(' │ ').replace(/\s+$/, ''));
+    };
+    const rule = ws.map(x => '─'.repeat(x)).join('─┼─');
+    return [...cellLines(header).map(text => ({ text, head: true })), { text: rule, rule: true }, ...rows.flatMap(r => cellLines(r).map(text => ({ text })))];
+  };
+  if (total <= cols) return { mode: 'grid', lines: gridLines(widths) };
+  // vertical key: value, one block per row; values wrap under a hanging indent
   const lines = [];
   const keyW = Math.min(Math.max(...header.map(w)), Math.floor(cols / 3));
+  const valW = Math.max(8, cols - keyW - 2);
   rows.forEach((r, ri) => {
     if (ri) lines.push({ text: '' });
-    header.forEach((hd, i) => lines.push({ text: `${padTo(clip(hd, keyW), keyW)}  ${r[i] ?? ''}`, key: keyW }));
+    header.forEach((hd, i) => {
+      const keyLines = wrapCell(hd, keyW);
+      const val = wrapCell(r[i] ?? '', valW);
+      const count = Math.max(keyLines.length, val.length);
+      for (let k = 0; k < count; k++) lines.push({ text: `${padTo(keyLines[k] ?? '', keyW)}  ${val[k] ?? ''}`.replace(/\s+$/, ''), key: k === 0 ? keyW : undefined });
+    });
   });
   return { mode: 'vertical', lines };
 }
@@ -153,7 +177,7 @@ function Table({ t, cols }) {
   const rows = t.rows.map(r => r.map(x => inlineText(x.tokens)));
   const lay = layoutTable(header, rows, cols);
   return h(Box, { flexDirection: 'column' }, ...lay.lines.map((l, i) => h(Text, {
-    key: i, bold: l.head, color: l.rule ? c('muted') : (l.head ? c('label') : undefined), wrap: 'truncate-end'
+    key: i, bold: l.head, color: l.rule ? c('muted') : (l.head ? c('label') : undefined), wrap: 'wrap'
   }, l.text || ' ')));
 }
 

package/lib/quoxon/markdownSettle.js

@@ -0,0 +1,19 @@
+/**
+ * The streaming split, without the renderer. events.js (and so `quox --print`) needs only
+ * splitSettled; importing it from markdown.js loaded React + Ink (~2 s cold) on every
+ * headless turn before the request was even sent (QUOXON-LATENCY). markdown.js re-exports
+ * both names, so the interactive client is unchanged.
+ */
+import { Lexer } from 'marked';
+
+export const lex = (src) => new Lexer({ gfm: true, breaks: false }).lex(src);
+
+export function splitSettled(text) {
+  const tokens = lex(text);
+  let last = -1;
+  for (let i = tokens.length - 1; i >= 0; i--) if (tokens[i].type !== 'space') { last = i; break; }
+  if (last <= 0) return { settled: '', rest: text };
+  let off = 0;
+  for (let i = 0; i < last; i++) off += tokens[i].raw.length;
+  return { settled: text.slice(0, off), rest: text.slice(off) };
+}

package/lib/quoxon/matrixDomains.json

@@ -0,0 +1,46 @@
+{
+  "_comment": "Vendored from ~/cli.quox.ai/matrix/domains.json (the proof matrix, 40 domain ids). Source: https://github.com/quoxai/cli.quox.ai matrix/domains.json. Tips name a domain from this list so the matrix can ingest them. When the matrix becomes canonical this file is replaced by the matrix export.",
+  "domains": [
+    "chat",
+    "providers",
+    "approvals",
+    "receipts",
+    "safety",
+    "hats",
+    "fleet",
+    "proxmox",
+    "monitoring",
+    "lucid",
+    "memory",
+    "qortex",
+    "vault",
+    "agents",
+    "workflows",
+    "skills",
+    "objectives",
+    "mail",
+    "calendar",
+    "contacts",
+    "notes",
+    "actions",
+    "voice",
+    "quoxchat",
+    "seo",
+    "plan",
+    "signal",
+    "browser",
+    "lens",
+    "social",
+    "comms",
+    "sessions",
+    "code",
+    "security",
+    "spend",
+    "files",
+    "plugins",
+    "identity",
+    "install",
+    "compliance",
+    "mind"
+  ]
+}

package/lib/quoxon/mentions.js

@@ -0,0 +1,90 @@
+/**
+ * @mention completion in the composer (MENTIONS). Typing `@` at the start of a word suggests agents, fleet hosts,
+ * tasks (objectives) and receipts (this session's own tool-call envelopes). The remote lists are fetched ONCE per
+ * session on the first `@`, then every keystroke filters the cache: no request per key. A failed fetch is quiet
+ * (that kind just has no rows) and is retried at most every RETRY_MS. Tab or Enter accepts, Esc closes.
+ */
+export const RETRY_MS = 30000;
+export const KIND_ORDER = ['agent', 'host', 'task', 'receipt'];
+
+/** The @word being typed at the end of the draft -> { start (index after '@'), partial } or null. */
+export function mentionContext(draft) {
+  const t = String(draft ?? '');
+  const m = t.match(/(^|\s)@([^\s@]*)$/);
+  if (!m) return null;
+  return { start: t.length - m[2].length, partial: m[2] };
+}
+
+const clean = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+
+/** api -> [{ value, kind, label }] from the session's remote sources, never throwing; failures named per kind. */
+export async function loadMentions(api) {
+  const kinds = {
+    agent: async () => (await api.agents()).map(a => ({ value: String(a.agent_id), kind: 'agent', label: a.name && a.name !== a.agent_id ? clean(a.name) : '' })),
+    host: async () => {
+      const none = { status: 'absent', value: [] };
+      const [inv, beat] = await Promise.all([api.mentionHosts, api.objects?.fleetNames].map((fn, i) => (fn ? Promise.allSettled([i ? api.objects.fleetNames() : api.mentionHosts()]).then(r => r[0]) : none)));
+      const tried = [inv, beat].filter(r => r.status !== 'absent');
+      if (tried.length && tried.every(r => r.status === 'rejected')) throw tried[0].reason;
+      const out = (inv.status === 'fulfilled' ? inv.value : []).map(h => ({ value: String(h.id), kind: 'host', label: clean([h.group, h.health].filter(Boolean).join(' · ')) }));
+      for (const h of beat.status === 'fulfilled' ? beat.value || [] : []) if (!out.some(o => o.value === String(h.value))) out.push({ value: String(h.value), kind: 'host', label: clean(h.desc) });
+      return out;
+    },
+    task: async () => ((await api.mentionTasks?.()) || []).map(o => ({ value: String(o.id), kind: 'task', label: clean(`${o.title || ''}${o.status ? ` (${o.status})` : ''}`) })),
+  };
+  const out = []; const failed = [];
+  await Promise.all(Object.entries(kinds).map(async ([k, fn]) => {
+    try { out.push(...(await fn()).filter(x => x.value && /^[\w.:-]+$/.test(x.value))); } catch { failed.push(k); }
+  }));
+  return { items: out, failed };
+}
+
+/** This session's tool calls that carry an envelope id: their receipts, newest first. Local, no request. */
+export function receiptMentions(items) {
+  const seen = new Set(); const out = [];
+  for (const b of [...(items || [])].reverse()) {
+    if (!b || b.kind !== 'tool' || !b.envelopeId || seen.has(b.envelopeId)) continue;
+    seen.add(b.envelopeId);
+    out.push({ value: String(b.envelopeId), kind: 'receipt', label: clean(`${b.tool || 'tool call'}${b.status ? ` ${b.status}` : ''}`) });
+  }
+  return out;
+}
+
+/** Prefix on the value first, then a substring of the value or its label; agents, hosts, tasks, receipts in that order. */
+export function rankMentions(items, partial, max = 50) {
+  const q = String(partial || '').toLowerCase();
+  const seen = new Set();
+  const uniq = (items || []).filter(i => i?.value && !seen.has(`${i.kind}:${i.value}`) && seen.add(`${i.kind}:${i.value}`));
+  const order = (a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind);
+  if (!q) return uniq.sort(order).slice(0, max);
+  const pre = uniq.filter(i => i.value.toLowerCase().startsWith(q)).sort(order);
+  const sub = uniq.filter(i => !i.value.toLowerCase().startsWith(q) && (i.value.toLowerCase().includes(q) || i.label.toLowerCase().includes(q))).sort(order);
+  const out = [...pre, ...sub];
+  return out.length === 1 && out[0].value.toLowerCase() === q ? [] : out.slice(0, max);
+}
+
+/** Accepting a mention: replace the partial word, add one space. */
+export const applyMention = (draft, cx, value) => String(draft).slice(0, cx.start) + value + ' ';
+
+/**
+ * One cache for the session. items() returns what is loaded (never blocks) and starts the single load the first
+ * time it is asked; a failed kind is retried no sooner than RETRY_MS. loads() counts fetches (tests, /status).
+ */
+export function createMentionCache({ load, refresh = () => {}, now = Date.now, retryMs = RETRY_MS }) {
+  let items = []; let state = 'idle'; let failedAt = 0; let loads = 0;
+  const start = () => {
+    state = 'loading'; loads++;
+    Promise.resolve().then(load).then(
+      (r) => { items = r?.items || []; state = r?.failed?.length ? 'partial' : 'ready'; if (state === 'partial') failedAt = now(); },
+      () => { state = 'failed'; failedAt = now(); }
+    ).then(() => refresh());
+  };
+  return {
+    items() {
+      if (state === 'idle' || ((state === 'failed' || state === 'partial') && now() - failedAt >= retryMs)) start();
+      return items;
+    },
+    state: () => state,
+    loads: () => loads,
+  };
+}

package/lib/quoxon/mind.js

@@ -0,0 +1,103 @@
+/**
+ * /mind: QuoxMind cognitive implants, read from the collector (same data as `quox mind`).
+ * Pure: takes api.mind() output, returns [[text, tone]]. Implants with nothing recorded
+ * say "no activity recorded"; nothing is invented. Lines are not clipped: notes wrap to the
+ * terminal width, so a long description reads in full (owner drive 2026-10-15).
+ */
+
+const MARK = { healthy: '✔', degraded: '⚠', weak: '⚠', collecting: '◐', 'not-reported': '·', unreachable: '✖', 'license-required': '⛔' };
+
+/** The 14 implant short ids (the collector's registry, in order). Used for help and for "did you mean". */
+export const MIND_IMPLANTS = ['sense', 'repobrain', 'memory', 'temporal', 'focus', 'value', 'guard', 'qortex', 'insight', 'executive', 'predict', 'reflect', 'dream', 'learn'];
+const SHORT_OF = { 'quox-nucleus': 'repobrain', 'quox-brain2': 'qortex' };
+const shortOf = (id) => SHORT_OF[id] || String(id).replace(/^quox-/, '');
+
+export const MIND_HELP_ARGS = new Set(['help', '-h', '--help', '?']);
+
+/** /mind help: the forms and the implant ids. No server call. */
+export function mindHelpLines() {
+  return [
+    ['/mind lists every QuoxMind implant with its status and last activity. Read-only, no model call.'],
+    ['/mind <implant> shows one implant in full: what it does, how it grows, its metrics.'],
+    [`Implants: ${MIND_IMPLANTS.join(', ')}.`],
+  ];
+}
+
+/**
+ * A failed /mind call as plain lines. A 404 "unknown implant" names the implant that does not exist,
+ * lists the real ones, and points at a TUI command of the same name when there is one (/mind doctor -> /doctor).
+ * Any other failure reports the server's own reason, not just "Request failed with status N".
+ */
+export function mindErrorLines(e, arg, { isCommand = () => false } = {}) {
+  const body = e?.body && typeof e.body === 'object' ? e.body : {};
+  const reason = body.error || body.message || (typeof e?.code === 'string' && !/^E[A-Z]/.test(e.code) ? e.code : '') || e?.message || 'failed';
+  if (arg && (e?.status === 404 || /unknown implant/i.test(reason))) {
+    const ids = Array.isArray(body.valid) && body.valid.length ? body.valid.map(shortOf) : MIND_IMPLANTS;
+    const out = [[`No implant called "${arg}". /mind <implant> shows one implant's status (read-only).`, 'warn'],
+      [`Implants: ${ids.join(', ')}.`]];
+    const cmd = String(arg).split(/\s+/)[0].toLowerCase();
+    if (isCommand(cmd)) out.push([`For the ${cmd} command, use /${cmd}.`]);
+    else out.push(['/mind on its own lists them all.']);
+    return out;
+  }
+  return [[`mind: ${e?.status ? `HTTP ${e.status}: ` : ''}${reason}`, 'error']];
+}
+
+/** Relative "fired" time for an ISO timestamp; 'never' when null. `now` is injectable for tests. */
+export function fmtFired(iso, now = Date.now()) {
+  if (!iso) return 'never';
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return String(iso);
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+/**
+ * The firing evidence for one implant (QUOXMIND-PROOF): last fired + 7-day count from the server.
+ * Returns null when the server predates the evidence fields, so the old line is kept.
+ */
+function firingText(i, now) {
+  if (!('fired_7d' in i)) return null;
+  if (i.activity_error) return `firing unknown: ${i.activity_error}`;
+  if (typeof i.fired_7d !== 'number') return 'firing not tracked';
+  const idle = typeof i.idle_runs_7d === 'number' && i.idle_runs_7d > 0 ? ` (${i.idle_runs_7d} idle runs)` : '';
+  return `${i.last_fired ? `fired ${fmtFired(i.last_fired, now)}` : 'never fired'} · 7d ${i.fired_7d}${idle}`;
+}
+
+export function mindLines(d, { now = Date.now() } = {}) {
+  const out = [];
+  const add = (t, tone) => out.push([t, tone]);
+  if (d.implant) {
+    const i = d.implant;
+    add(`${MARK[i.status] || '·'} ${i.name} (${i.short}) · ${i.status}${i.tier ? ` · ${i.tier}` : ''}`);
+    add(`  ${i.description || i.purpose}`);
+    if (i.inspired_by) add(`  inspired by: ${i.inspired_by}`);
+    if (i.summary) add(`  now: ${i.summary}`);
+    add(`  ${i.activity}`);
+    const fired = firingText(i, now);
+    if (fired && typeof i.fired_7d === 'number') add(`  fired: ${fmtFired(i.last_fired, now)}${i.last_fired ? ` (${i.last_fired})` : ''} · 7d ${i.fired_7d}${i.activity_source ? ` · from ${i.activity_source}` : ''}`);
+    else if (fired) add(`  ${fired}`);
+    if (i.how_to_grow) add(`  how it grows: ${i.how_to_grow}`);
+    if (Array.isArray(i.connected_to) && i.connected_to.length) add(`  connected to: ${i.connected_to.map(shortOf).join(', ')}`);
+    for (const [k, v] of Object.entries(i.metrics || {})) if (v !== null && typeof v !== 'object') add(`  ${k}: ${typeof v === 'number' && !Number.isInteger(v) ? Math.round(v * 100) / 100 : v}`);
+    const others = MIND_IMPLANTS.filter(s => s !== i.short);
+    add(`This is ${i.name}'s status, read-only: nothing runs. /mind for all; others: ${others.map(s => `/mind ${s}`).join(', ')}.`, 'dim');
+    return out;
+  }
+  const list = d.implants || [];
+  add(`QuoxMind: ${list.length} cognitive implants`);
+  for (const i of list) {
+    const fired = firingText(i, now);
+    const tail = fired !== null
+      ? `${fired}${typeof i.fired_7d === 'number' && !i.activity_error && i.summary && i.activity !== 'no activity recorded' ? ` · ${i.summary}` : ''}`
+      : (i.activity === 'no activity recorded' ? 'no activity recorded' : i.summary || i.activity);
+    add(`${MARK[i.status] || '·'} ${i.short.padEnd(10)} ${i.status.padEnd(13)} ${tail}`, i.status === 'unreachable' ? 'warn' : undefined);
+  }
+  const h = d.health;
+  if (h && typeof h.fired_7d_total === 'number') add(`${h.fired_7d_implants} of ${list.length} fired in the last 7 days (${h.fired_7d_total} firings), ${h.silent_7d} silent, ${h.activity_unknown} not tracked. /mind <id> for one.`);
+  else if (h) add(`${h.with_activity} with activity, ${h.no_activity} with none recorded${h.average_health !== null ? `, average health ${h.average_health}` : ''}. /mind <id> for one.`);
+  return out;
+}

package/lib/quoxon/mode.js

@@ -0,0 +1,46 @@
+/**
+ * /mode (owner 2026-10-16 "/say quoxon a but log b"): this window's mode.
+ *   ask   (default) Quox asks you before it acts; what needs approval is your org's policy.
+ *   plan  Quox investigates (read tools) and proposes the steps and exact commands; it runs nothing that
+ *         changes state. The SERVER enforces it: the turn carries mode 'plan' (lib/planMode.js in the collector).
+ *   auto  not built. Logged as a plan: it needs standing grants first.
+ * Window-scoped: carried across /restart (QUOX_RESTART_MODE), never written to the shared profile.
+ */
+
+export const MODES = ['ask', 'plan'];
+export const AUTO_NOT_YET = 'not available yet: auto mode needs standing grants (planned).';
+export const PLAN_GO = 'go ahead with the plan';
+
+/** -> 'plan' | 'ask' (anything else, including 'auto', is 'ask'). */
+export function normMode(v) {
+  return String(v || '').trim().toLowerCase() === 'plan' ? 'plan' : 'ask';
+}
+
+const DESC = {
+  ask: 'ask first: Quox asks you before it acts. What needs your approval is your org\'s policy on the server (/approvals lists what is waiting).',
+  plan: 'plan only: Quox investigates with read tools and proposes the steps and the exact commands. It runs nothing that changes state; the server enforces it.',
+};
+
+/** One line per mode for the arrow-key chooser (the same one /model uses). Auto is not offered: it is not built. */
+export const MODE_ROWS = [
+  { id: 'ask', text: 'ask first: Quox asks before it acts' },
+  { id: 'plan', text: 'plan only: Quox proposes the steps and runs nothing that changes state' },
+];
+
+/**
+ * Pure: the reply to `/mode [arg]` given the current mode.
+ * -> { text, tone, mode? } where mode is set only when it changes.
+ */
+export function modeReply(arg, current) {
+  const cur = normMode(current);
+  const a = String(arg || '').trim().toLowerCase();
+  if (!a || /^(-h|--help|help|\?)$/.test(a)) {
+    return { tone: null, text: `mode ${DESC[cur]}\nOptions: /mode ask (the default), /mode plan (plan only). Auto mode is ${AUTO_NOT_YET}` };
+  }
+  if (a === 'auto') return { tone: 'warn', text: `/mode auto is ${AUTO_NOT_YET} Options: /mode ask, /mode plan.` };
+  if (!MODES.includes(a)) return { tone: 'warn', text: `Unknown mode '${clipWord(a)}'. Options: /mode ask, /mode plan.` };
+  if (a === cur) return { tone: 'dim', text: `Already in mode ${DESC[cur]}` };
+  return { mode: a, tone: 'ok', text: a === 'plan' ? `mode ${DESC.plan} /mode ask to go back.` : `mode ${DESC.ask}` };
+}
+
+function clipWord(w) { return w.length > 20 ? `${w.slice(0, 19)}…` : w; }