quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/orgLabel.js

@@ -0,0 +1,10 @@
+/** The org as the status line shows it: its name, or a short "org …H398" until the name arrives. Never a raw ULID. */
+const ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+export const isOrgId = (s) => ULID.test(String(s || '').trim());
+export function orgLabel(name, id = null) {
+  const n = name == null ? '' : String(name).trim();
+  if (n && !isOrgId(n)) return n;
+  const raw = isOrgId(n) ? n : (id ? String(id).trim() : '');
+  if (!raw) return null;
+  return isOrgId(raw) ? `org …${raw.slice(-4)}` : raw; // only a real ULID is masked
+}

package/lib/quoxon/orgSwitch.js

@@ -0,0 +1,33 @@
+/** /org helpers (pure). Org list rows, fuzzy match, and the lines the command prints. QUOXON-FW3. */
+const norm = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+
+export const orgRows = (list) => (Array.isArray(list) ? list : []).map((o) => ({ id: o.id, name: o.name || o.slug || o.id, slug: o.slug || null, role: o.role || null }));
+
+/**
+ * Resolve a typed name or id against the user's orgs. Exact id, exact slug/name, then every word of the
+ * query found in the name or slug (so "hot tubs hampshire" finds "Hot Tubs Hampshire Ltd"). Never guesses between ties.
+ * -> { org } | { ambiguous: [orgs] } | { none: true }
+ */
+export function matchOrg(query, list) {
+  const rows = orgRows(list);
+  const q = norm(query);
+  if (!q) return { none: true };
+  // An exact slug wins outright, so a slug never ties with another org's look-alike name (#1141).
+  const bySlug = rows.filter((o) => o.slug && o.slug === String(query).trim());
+  if (bySlug.length === 1) return { org: bySlug[0] };
+  const exact = rows.filter((o) => String(o.id).toLowerCase() === String(query).trim().toLowerCase() || norm(o.slug) === q || norm(o.name) === q);
+  if (exact.length === 1) return { org: exact[0] };
+  if (exact.length > 1) return { ambiguous: exact };
+  const words = q.split(' ');
+  const fuzzy = rows.filter((o) => { const hay = `${norm(o.name)} ${norm(o.slug)}`; return words.every((w) => hay.includes(w)); });
+  if (fuzzy.length === 1) return { org: fuzzy[0] };
+  if (fuzzy.length > 1) return { ambiguous: fuzzy };
+  return { none: true };
+}
+
+/** One line per org; the current one is marked. */
+export function orgLines(list, currentId) {
+  const rows = orgRows(list);
+  const w = Math.min(36, Math.max(4, ...rows.map((o) => [...o.name].length)));
+  return rows.map((o) => `${o.id === currentId ? '* ' : '  '}${o.name.padEnd(w)}  ${o.slug || o.id}${o.role ? `  (${o.role})` : ''}`);
+}

package/lib/quoxon/ownBroadcast.js

@@ -0,0 +1,22 @@
+/**
+ * Your own broadcast is not news to you: the fan-out reaches every held slot in the org, including this window's, and
+ * the "BROADCAST sent" card already told the sender. Match by the sender's identity, never by text.
+ */
+import { parseBroadcastText } from './slash/broadcast.js';
+
+const norm = (s) => String(s || '').toLowerCase().replace(/\s*\(.*?\)\s*/g, ' ').replace(/\s+/g, ' ').trim();
+
+/**
+ * @param {object} m           the slot message
+ * @param {object} me          { label: this window's sender label, display: the signed-in display name, userId }
+ */
+export function isOwnBroadcast(m, me = {}) {
+  const bc = parseBroadcastText(m?.text);
+  if (!bc) return false;
+  const uid = me.userId ? String(me.userId) : null;
+  if (uid && [m.user_id, m.from_user_id, m.author_user_id, m.author_id].some((x) => x != null && String(x) === uid)) return true;
+  const sender = norm(bc.sender), from = norm(m.from);
+  const mine = [me.label, me.display].map(norm).filter(Boolean);
+  if (!mine.length) return false;
+  return mine.some((x) => x === sender || x === from) || (me.label && m.from === me.label) || false;
+}

package/lib/quoxon/palette.js

@@ -0,0 +1,43 @@
+/**
+ * The semantic palette (QUOXON-FW11). One role per MEANING, so a reader can see where prose stops and a thing
+ * they can type starts:
+ *
+ *   prose    default text. White on dark, ink on light. Never grey.
+ *   command  anything the user can type: /slash commands, `quox ...`, !bang, flags and args INCLUDED. The whole
+ *            command is ONE span in ONE colour (never split into differently coloured parts).
+ *   value    ids, names, numbers, paths, URLs (theme role `id`; theme's `value` stays the near-white card text).
+ *   ok / warn / error   state. Carried by a glyph or label ("⚠"), never by tinting the sentence, so commands and
+ *            values inside keep their own colours.
+ *   brand    Quox purple: chrome only (logo, status-bar labels, headers). Never a command inside prose.
+ *   quiet    secondary text and rules: a tinted, readable shade (never a mid-grey).
+ *
+ * Both tables: [truecolor hex, ansi256 index]. DARK >= 4.5:1 on #000, LIGHT >= 4.5:1 on #fff (tests).
+ */
+export const SEMANTIC_DARK = {
+  prose: ['#f1f5f9', 255], command: ['#2dd4bf', 80], value: ['#93c5fd', 117],
+  ok: ['#4ade80', 78], warn: ['#f59e0b', 214], error: ['#f87171', 210],
+  brand: ['#a855f7', 135], quiet: ['#bcc8e8', 189], rule: ['#7c8fe0', 105]
+};
+export const SEMANTIC_LIGHT = {
+  prose: ['#0f172a', 234], command: ['#0f766e', 30], value: ['#1d4ed8', 26],
+  ok: ['#15803d', 28], warn: ['#b45309', 130], error: ['#b91c1c', 124],
+  brand: ['#7e22ce', 91], quiet: ['#3b4f87', 60], rule: ['#7280c8', 104]
+};
+export const SEMANTIC_ROLES = Object.keys(SEMANTIC_DARK);
+
+/** Is this hex a mid-grey? Low saturation in the middle of the lightness range (white and ink are allowed). */
+export function isGrey(hex) {
+  const [r, g, b] = [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16) / 255);
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2, d = max - min;
+  const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
+  return s < 0.25 && l > 0.2 && l < 0.85;
+}
+
+// ---- inline markup used by every notice producer --------------------------------------------------
+// ⟦text⟧ = a command (one span, markers dropped on screen). ⟪text⟫ = a value. Helpers build them. (Not backticks:
+// plain backticks already appear literally in notices.)
+export const cmd = (s) => `⟦${s}⟧`;
+export const val = (s) => `⟪${s}⟫`;
+export const MARK = /⟦([^⟧\n]+)⟧|⟪([^⟫\n]+)⟫/g;
+/** The on-screen characters of marked-up text (markers dropped). Use for width and wrapping. */
+export const stripMarks = (s) => String(s ?? '').replace(MARK, (_, a, b) => a ?? b);

package/lib/quoxon/print.js

@@ -0,0 +1,98 @@
+/**
+ * Headless mode: `quox --print "<prompt>"` sends one turn and exits.
+ * (-p is --profile across quox, so print has no short flag.)
+ * Exit codes: 0 completed, 2 held for approval, 3 interrupted, 4 auth, 5 unconfirmed
+ * (stream closed without turn.finished), 1 other.
+ */
+import { textGate } from './events.js';
+import { streamFields, fallbackNote } from './model.js';
+import { connectOfferFor } from './connect.js';
+import { isConsentError, consentPrintMessage } from './consent.js';
+
+export const EXIT = { ok: 0, error: 1, approval: 2, interrupted: 3, auth: 4, unconfirmed: 5 };
+
+export async function readStdin(stream = process.stdin) {
+  if (stream.isTTY) return '';
+  let s = '';
+  stream.setEncoding?.('utf8');
+  for await (const chunk of stream) s += chunk;
+  return s;
+}
+
+/** Resolve the prompt: arg wins; absent or "-" reads stdin. */
+export async function resolvePrompt(arg, stdin) {
+  if (arg && arg !== '-') return arg;
+  return (await readStdin(stdin)).replace(/\n+$/, '');
+}
+
+const isAuth = (e) => e?.status === 401 || /valid jwt|service key|unauthor|not authenticated/i.test(e?.message || '');
+const newTurnId = () => `QXN_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+/** Runs one turn. out/err are write(string) sinks. Returns the exit code. */
+export async function runPrint({ api, prompt, agent = 'quox', output = 'text', conversation = null, turnId = newTurnId(), timeoutS = 0, color = false, stopGraceMs = 8000, context = undefined, choice = null, promptProfile = undefined, profile = null, out, err }) {
+  if (!prompt || !prompt.trim()) { err('quox: empty prompt (pass --print "<prompt>" or pipe it on stdin)\n'); return EXIT.error; }
+  const ctrl = new AbortController();
+  let abandoned = false, graceTimer = null;
+  // A timeout asks the SERVER to stop; only if it cannot (or does not answer in the grace) do we abandon the
+  // local stream, and then we say "abandoned", never "interrupted": the server may still finish the turn.
+  const requestStop = async () => {
+    let r = { ok: false };
+    try { if (api.interrupt) r = await api.interrupt(convo, turnId); } catch { r = { ok: false }; }
+    if (r?.ok) graceTimer = setTimeout(() => { abandoned = true; ctrl.abort(); }, stopGraceMs);
+    else { abandoned = true; ctrl.abort(); }
+  };
+  const timer = timeoutS > 0 ? setTimeout(requestStop, timeoutS * 1000) : null;
+  const t0 = Date.now();
+  const sum = { tools: 0, approvals: 0, receipts: [] };
+  let convo = conversation, doneSession = null, status = null, text = '', sawApproval = false, errorMsg = null, authFail = false;
+  const seen = new Set();
+  let offer = null, handoff = null;
+  let gate = null;
+  try {
+    for await (const ev of api.stream({ turnId, message: prompt, agent: agent || 'quox', conversationId: conversation, context, ...streamFields(choice), ...(promptProfile ? { promptProfile } : {}), ...(timeoutS > 0 ? { turnBudgetMs: timeoutS * 1000 } : {}) }, ctrl.signal)) {
+      if (output === 'json') out(JSON.stringify(ev) + '\n');
+      const fb = fallbackNote(choice, ev);
+      if (fb) err(`quox: ${fb}\n`);
+      if (!offer) offer = connectOfferFor(ev);
+      if (ev.conversation_id) convo = ev.conversation_id;
+      if (ev.session_id) doneSession = ev.session_id; // the server's real id: v1 events only echo the request
+      if (ev.type === 'chunk' || ev.type === 'text.delta' || ev.type === 'turn.started') { const g = textGate(gate, ev); gate = g.st; if (g.append) text += ev.content; }
+      else if (ev.type === 'done' && !text && ev.full_response) text = ev.full_response;
+      else if (ev.type === 'tool.started' && !seen.has(ev.call_id)) { seen.add(ev.call_id); sum.tools++; }
+      else if (ev.type === 'tool.finished') { if (!seen.has(ev.call_id)) { seen.add(ev.call_id); sum.tools++; } if (ev.receipt?.ward_seq != null) sum.receipts.push(ev.receipt.ward_seq); }
+      else if (ev.type === 'approval.requested') { sawApproval = true; sum.approvals++; }
+      else if (ev.type === 'approval.resolved') sawApproval = false;
+      else if (ev.type === 'turn.handoff_suggested' && ev.handoff_suggested?.agent) handoff = ev.handoff_suggested; // QUOXON handoff offer
+      else if (ev.type === 'turn.finished') status = ev.status || 'completed';
+      else if (ev.type === 'error') errorMsg = isConsentError(ev) ? consentPrintMessage(ev, profile) : (ev.error || 'stream error');
+    }
+  } catch (e) {
+    if (ctrl.signal.aborted) { status = 'abandoned'; errorMsg = `timed out after ${timeoutS}s; the server was not confirmed stopped`; }
+    else { authFail = isAuth(e); errorMsg = e?.message || String(e); }
+  } finally { if (timer) clearTimeout(timer); clearTimeout(graceTimer); }
+  if (ctrl.signal.aborted && !status) { status = 'abandoned'; errorMsg = errorMsg || `timed out after ${timeoutS}s; the server was not confirmed stopped`; }
+  if (doneSession) convo = doneSession;
+  const serverStopped = abandoned && status === 'abandoned' ? false : status === 'interrupted' ? true : null;
+
+  let code;
+  if (authFail) code = EXIT.auth;
+  else if (sawApproval && status !== 'interrupted' && status !== 'abandoned') { status = status === 'completed' || !status ? 'held_for_approval' : status; code = EXIT.approval; }
+  else if (status === 'completed' && !errorMsg) code = EXIT.ok;
+  else if (status === 'interrupted' || status === 'abandoned') code = EXIT.interrupted;
+  else if (sawApproval) { status = status || 'held_for_approval'; code = EXIT.approval; }
+  else if (!status && !errorMsg) { status = 'unconfirmed'; code = EXIT.unconfirmed; }
+  else code = EXIT.error;
+  if (!status) status = authFail ? 'auth' : 'failed';
+
+  if (output === 'json') {
+    out(JSON.stringify({ type: 'summary', status, turn_id: turnId, conversation_id: convo, duration_ms: Date.now() - t0, server_stopped: serverStopped, ...sum, ...(handoff ? { handoff_suggested: handoff } : {}) }) + '\n');
+  } else if (text) out(text.endsWith('\n') ? text : text + '\n');
+  if (authFail) err(`Not signed in for chat. Run: quox login -p <profile>\n`);
+  else if (code === EXIT.approval) err('Held for approval: approve it in the dashboard or with `quox` /approvals.\n');
+  else if (code === EXIT.unconfirmed) err('quox: Ended without confirmation from the server\n');
+  else if (errorMsg) err(`quox: ${errorMsg}\n`);
+  if (offer && code !== EXIT.ok) err(`${offer}\n`);
+  // QUOXON handoff offer: no y/N here, so name the exact one-turn command (same question, same conversation).
+  if (handoff && output !== 'json' && code === EXIT.ok) err(`quox: ${handoff.reason ? `${String(handoff.reason).replace(/\s+$/, '')} ` : ''}${handoff.name || handoff.agent} can answer it: quox --print --agent ${handoff.agent}${convo ? ` --conversation ${convo}` : ''} ${JSON.stringify(prompt)}\n`);
+  return code;
+}

package/lib/quoxon/profileSwitch.js

@@ -0,0 +1,53 @@
+// PROFILE-SWITCH (owner 2026-10-16): switch this window between logged-in profiles with one y, never automatically.
+import { askText } from './ask.js';
+
+/**
+ * The App's api, swappable in place: every reader (and every controller built at mount) goes through this proxy,
+ * so a profile switch replaces ref.current.live and the whole window follows. Methods are bound to the live api.
+ */
+export function liveApi(ref) {
+  return new Proxy({}, {
+    get(_, k) {
+      const a = ref.current?.live;
+      if (a == null) return undefined;
+      const v = a[k];
+      return typeof v === 'function' ? v.bind(a) : v;
+    },
+    has(_, k) { const a = ref.current?.live; return a != null && k in Object(a); },
+  });
+}
+
+/** The ask card offering to switch an agent-login window to a human login. */
+export const switchAskLine = (profile, human) => askText('Switch?', {
+  title: `This window is an agent login (${profile}).`,
+  action: `switch this window to your login '${human}' (same conversation, attach, slot and groups)`,
+});
+
+/** The ask card for a /slot name that does not exist (the near misses are said on the line above). */
+export const slotCreateAskLine = (nm) => askText('Create it?', { title: `No slot ${nm}.`, action: `create and hold slot ${nm}` });
+
+/** A local run request (the shared run card): sign a profile in with the real `quox login`, terminal handed over. */
+export function loginRunRequest(name, why, now = Date.now()) {
+  return { id: null, cmd: `quox login -p ${name}`, why, who: 'Quox', runnable: true, refuse: null, danger: null, expiresAt: now + 120000 };
+}
+
+/** A safe profile name to put on a command line (letters, digits, . _ -). */
+export const okProfileName = (n) => /^[A-Za-z0-9._-]{1,64}$/.test(String(n || ''));
+
+/**
+ * /profile chooser rows (PROFILE-CHOOSER): signed-in profiles first (this window's marked), then profiles on this
+ * machine that are not signed in, then the current login's orgs (the window's org marked). Each row carries `pick`:
+ * { profile } switches this window in place, { login } offers `quox login -p`, { org } goes through /org switch
+ * (window-scoped since #1034, confirmed first). Nothing here writes the shared default profile.
+ */
+export function profileChooserRows({ current, humanProfiles = [], loginCandidates = [], orgs = [], orgId = null }) {
+  const names = [...new Set([current, ...humanProfiles].filter(okProfileName))];
+  const later = loginCandidates.filter(n => okProfileName(n) && !names.includes(n));
+  const orgList = (Array.isArray(orgs) ? orgs : []).map(o => ({ id: o.id, name: o.name || o.slug || o.id, slug: o.slug || null, role: o.role || null }));
+  const w = Math.min(28, Math.max(8, ...[...names, ...later].map(n => n.length + 8), ...orgList.map(o => [...o.name].length + 4)));
+  const rows = [];
+  for (const n of names) rows.push({ key: `${n === current ? '* ' : '  '}${`profile ${n}`.padEnd(w)}`, text: n === current ? 'this window' : 'signed in: switch this window to it', pick: { profile: n } });
+  for (const n of later) rows.push({ key: `  ${`profile ${n}`.padEnd(w)}`, text: 'not signed in: offers quox login', pick: { login: n } });
+  for (const o of orgList) rows.push({ key: `${o.id === orgId ? '* ' : '  '}${`org ${o.name}`.padEnd(w)}`, text: `${o.slug || o.id}${o.role ? `  (${o.role})` : ''}${o.id === orgId ? '  this window' : ''}`, pick: { org: o } });
+  return rows;
+}

package/lib/quoxon/promptHistory.js

@@ -0,0 +1,41 @@
+/**
+ * QUOXON-HISTORY: what the user typed, kept across quox runs so Up recalls it (most recent first), like a shell.
+ * Local only (~/.quox/history.jsonl, mode 0600), capped. The caller never offers it anything that looks like a key:
+ * keys, PINs and /connect secrets are refused before they reach history.
+ */
+import { readFileSync, appendFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const HISTORY_CAP = 500;
+export const defaultHistoryPath = (home = homedir()) => join(home, '.quox', 'history.jsonl');
+
+/** -> { load(): string[] oldest first, add(text) } on the given file. Every failure is quiet: history is a convenience. */
+export function fileHistory(path = defaultHistoryPath(), { cap = HISTORY_CAP } = {}) {
+  const load = () => {
+    try {
+      const out = [];
+      for (const ln of readFileSync(path, 'utf8').split('\n')) {
+        if (!ln) continue;
+        try { const t = JSON.parse(ln)?.t; if (typeof t === 'string' && t) out.push(t); } catch { /* a torn line */ }
+      }
+      return out.slice(-cap);
+    } catch { return []; }
+  };
+  const add = (text) => {
+    try {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      appendFileSync(path, JSON.stringify({ t: text }) + '\n', { mode: 0o600 });
+      if (statSync(path).size > cap * 400) { const keep = load(); writeFileSync(path, keep.map(t => JSON.stringify({ t })).join('\n') + '\n', { mode: 0o600 }); }
+    } catch { /* read-only home: this run still has it in memory */ }
+  };
+  return { load, add };
+}
+
+/** Push onto the in-memory list, skipping an exact repeat of the last entry (shell ignoredups). -> true when added. */
+export function pushHistory(list, text) {
+  if (typeof text !== 'string' || !text.trim()) return false;
+  if (list.length && list[list.length - 1] === text) return false;
+  list.push(text);
+  return true;
+}

package/lib/quoxon/providers.js

@@ -0,0 +1,48 @@
+/**
+ * Provider availability, one source of truth for /model, /connect, /doctor and /capabilities (R3 audit D5:
+ * the Claude subscription used to tell five different stories).
+ *
+ * The SERVER decides: GET /api/v1/capabilities reports `provider.<id>` from real signals (org vault keys,
+ * instance keys, the server's Claude sign-in). The org vault list only adds detail (which credential, a
+ * stored-but-not-default key). A provider the server does not report (Ollama) falls back to the vault; when
+ * neither answers the state is unknown, never "not connected".
+ *
+ * Pure: `caps` is { ok, capabilities } from api.capabilities(), `vault` is { ok, rows } from api.connections().
+ */
+
+export const SUBSCRIPTION_NAME = 'Claude (subscription, dev only)';
+const DISPLAY = { 'provider.claude_subscription': SUBSCRIPTION_NAME };
+
+/** The name every surface shows for a capability (the server's own name, except where Quox has a fixed one). */
+export const capabilityName = (c) => DISPLAY[c?.id] || c?.name || c?.id;
+
+/** The server could not read this provider's status (not "not available"): shown as ? unknown on every surface. */
+export const statusUnreadable = (c) => c?.availability === 'unavailable' && /^Could not read .* status/i.test(c.reason || '');
+
+export const vaultPick = (rows, type) => {
+  const of = rows.filter(r => r.integration_type === type);
+  return { def: of.find(r => r.is_default === 1 || r.is_default === true) || null, any: of[0] || null };
+};
+
+/**
+ * -> { state, row?, reason?, setup?, source } for one provider.
+ * state: 'connected' (the server can use it) | 'stored' (a key exists but is not the org default) |
+ *        'missing' (needs setup) | 'unavailable' (not on this server) | 'unknown' (nothing answered).
+ * p: { cap: 'openai' | 'claude_subscription' | ..., vault?: integration type }
+ */
+export function providerState(p, caps, vault) {
+  const rows = vault?.ok && Array.isArray(vault.rows) ? vault.rows : null;
+  const v = rows && p.vault ? vaultPick(rows, p.vault) : { def: null, any: null };
+  const c = caps?.ok && Array.isArray(caps.capabilities) ? caps.capabilities.find(x => x?.id === `provider.${p.cap}`) : null;
+  if (c && statusUnreadable(c)) return { state: 'unknown', reason: c.reason, source: 'server' };
+  if (c) {
+    const base = { reason: c.reason || null, setup: c.setup || null, source: 'server' };
+    if (c.availability === 'installed') return { ...base, state: 'connected', row: v.def || null };
+    if (c.availability === 'requires_setup') return v.any && !v.def ? { ...base, state: 'stored', row: v.any } : { ...base, state: 'missing' };
+    return { ...base, state: 'unavailable' };
+  }
+  if (!rows || !p.vault) return { state: 'unknown', source: 'none' };
+  if (v.def) return { state: 'connected', row: v.def, source: 'vault' };
+  if (v.any) return { state: 'stored', row: v.any, source: 'vault' };
+  return { state: 'missing', source: 'vault' };
+}