quoxcli 0.0.0-stage → 0.2.0

package/lib/core/banner.js

@@ -0,0 +1,143 @@
+/**
+ * The bare-`quox` splash (DEVSUITE-GLYPH follow-on): the horned Q in
+ * truecolor half-blocks with the brand gradient, plus a one-glance verb map.
+ * Bitmap generated from QuoxSymbols quoxQ (fontforge export at 26px); the
+ * gradient stops mirror @quox/glyph. Colour gating matches the renderer:
+ * QUOX_COLOR=0 off / 1|2 force on, else tty && !NO_COLOR.
+ */
+import { GRAD } from './quoxglyph.js';
+
+const Q_BITMAP = [
+  '          #   ',
+  '  #       #   ',
+  ' ##       #   ',
+  ' ##       ##  ',
+  '  #########   ',
+  ' ###########  ',
+  ' ###     ###  ',
+  '###       ### ',
+  '###       ### ',
+  '###       ### ',
+  '###       ### ',
+  '###       ### ',
+  '###   ### ### ',
+  '###   ######  ',
+  ' ###   #####  ',
+  ' ############ ',
+  '   ###########',
+  '          ### ',
+];
+
+export function colorOn() {
+  const env = process.env.QUOX_COLOR;
+  if (env === '0') return false;
+  if (env === '1' || env === '2') return true;
+  return Boolean(process.stdout && process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+const R = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+function gradFg(t) {
+  const [a, b] = GRAD;
+  const c = a.map((v, k) => Math.round(v + (b[k] - v) * t));
+  return `\x1b[38;2;${c[0]};${c[1]};${c[2]}m`;
+}
+function gradBg(t) {
+  const [a, b] = GRAD;
+  const c = a.map((v, k) => Math.round(v + (b[k] - v) * t));
+  return `\x1b[48;2;${c[0]};${c[1]};${c[2]}m`;
+}
+
+/** Render the Q as half-block rows (2 bitmap rows per terminal row). */
+export function qArt(col) {
+  const cols = Q_BITMAP[0].length;
+  const out = [];
+  for (let y = 0; y < Q_BITMAP.length; y += 2) {
+    const top = Q_BITMAP[y];
+    const bot = Q_BITMAP[y + 1] || ' '.repeat(cols);
+    let line = '';
+    for (let x = 0; x < cols; x++) {
+      const t = x / (cols - 1);
+      const hasTop = top[x] === '#';
+      const hasBot = bot[x] === '#';
+      if (!col) {
+        line += hasTop && hasBot ? '█' : hasTop ? '▀' : hasBot ? '▄' : ' ';
+      } else if (hasTop && hasBot) {
+        line += `${gradFg(t)}${gradBg(t)}▀${R}`;
+      } else if (hasTop) {
+        line += `${gradFg(t)}▀${R}`;
+      } else if (hasBot) {
+        line += `${gradFg(t)}▄${R}`;
+      } else {
+        line += ' ';
+      }
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+/**
+ * One frame of the intro sweep: the Q is revealed left to right with a bright
+ * leading edge; progress >= 1 returns exactly qArt(col). Always the same
+ * number of rows and columns, so the live region never changes height.
+ */
+export function qArtFrame(progress, col) {
+  if (progress >= 1 || !col) return qArt(col);
+  const cols = Q_BITMAP[0].length;
+  const head = progress * (cols + 3) - 1.5;
+  const px = (x, on) => (on && x <= head ? 1 : 0);
+  const glow = (x, t) => {
+    const d = head - x; // 0 at the leading edge, grows behind it
+    const k = d < 3 ? 1 - d / 3 : 0;
+    const [a, b] = GRAD;
+    const base = a.map((v, j) => v + (b[j] - v) * t);
+    const c = base.map(v => Math.round(v + (255 - v) * 0.7 * k));
+    return `\x1b[38;2;${c[0]};${c[1]};${c[2]}m`;
+  };
+  const out = [];
+  for (let y = 0; y < Q_BITMAP.length; y += 2) {
+    const top = Q_BITMAP[y];
+    const bot = Q_BITMAP[y + 1] || ' '.repeat(cols);
+    let line = '';
+    for (let x = 0; x < cols; x++) {
+      const t = x / (cols - 1);
+      const hasTop = px(x, top[x] === '#');
+      const hasBot = px(x, bot[x] === '#');
+      if (!hasTop && !hasBot) line += ' ';
+      else if (hasTop && hasBot) line += `${glow(x, t)}${gradBg(t)}▀${R}`;
+      else line += `${glow(x, t)}${hasTop ? '▀' : '▄'}${R}`;
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+export function printBanner(version, { loggedIn = true } = {}) {
+  const col = colorOn();
+  const art = qArt(col);
+  const b = (s) => (col ? `${BOLD}${s}${R}` : s);
+  const d = (s) => (col ? `${DIM}${s}${R}` : s);
+  const text = [
+    '',
+    `${b('Quox')} ${d('— the governed agent platform')}${version ? d(`  v${version}`) : ''}`,
+    d('every action witnessed · every agent governed'),
+    '',
+    // quox#624: a logged-out first run starts at login, not at the auth wall.
+    ...(loggedIn ? [] : [`🔑 ${b('quox login')}           ${d('start here: sign in to your instance')}`]),
+    `🧭 ${b('quox plan focus')}      ${d('what matters now')}`,
+    `🛰️ ${b('quox fleet status')}    ${d('the estate at a glance')}`,
+    `📡 ${b('quox workflow list')}   ${d('governed automations')}`,
+    `⛓ ${b('quox volt verify')}     ${d('the evidence chain')}`,
+    '',
+    d('quox --help for everything'),
+  ];
+  const lines = [];
+  const rows = Math.max(art.length, text.length);
+  for (let i = 0; i < rows; i++) {
+    lines.push(`  ${art[i] || ' '.repeat(Q_BITMAP[0].length)}   ${text[i] || ''}`);
+  }
+  process.stdout.write('\n' + lines.join('\n') + '\n\n');
+}

package/lib/core/brainPrime.js

@@ -0,0 +1,90 @@
+/**
+ * ONE-BRAIN CX4 (attach-time prime) and CX3 (handoff-to-note) helpers.
+ *
+ * Both are best effort by design: neither may ever fail an attach or a detach.
+ * Endpoints reused: brain.context.pack (`quox brain context`) and
+ * brain.capture.create (`quox brain add` / `decide`).
+ */
+import { execFileSync } from 'node:child_process';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const PRIME_TIMEOUT_MS = 5000;
+export const PRIME_TOKEN_BUDGET = 1200;
+export const PRIME_SNIPPET_CHARS = 300;
+
+function gitOut(args) {
+  try { return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; }
+}
+
+/** Does this attach kit's resolved tool list carry the brain_context tool? */
+export function kitHasBrainContext(kit) {
+  return Array.isArray(kit?.tools) && kit.tools.includes('brain_context');
+}
+
+/** Query text from the working context: repo, branch, advisory stream, last 3 commit subjects. */
+export function buildPrimeQuery({ git = gitOut, env = process.env } = {}) {
+  const top = git(['rev-parse', '--show-toplevel']);
+  const repo = top ? top.split('/').pop() : '';
+  const branch = git(['rev-parse', '--abbrev-ref', 'HEAD']);
+  const subjects = git(['log', '-3', '--pretty=%s']).split('\n').map((s) => s.trim()).filter(Boolean);
+  const parts = [];
+  if (repo) parts.push(`repo ${repo}`);
+  if (branch && branch !== 'HEAD') parts.push(`branch ${branch}`);
+  if (env.QUOX_STREAM) parts.push(`stream ${env.QUOX_STREAM} (advisory)`);
+  if (subjects.length) parts.push(`recent work: ${subjects.join('; ')}`);
+  return parts.join(', ');
+}
+
+function withTimeout(promise, ms) {
+  let timer;
+  const t = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`timed out after ${ms / 1000}s`)), ms); });
+  return Promise.race([promise, t]).finally(() => clearTimeout(timer));
+}
+
+/** Returns the "## Brain primer" markdown section. Never throws. */
+export async function buildBrainPrimer(client, { query, timeoutMs = PRIME_TIMEOUT_MS } = {}) {
+  const head = '## Brain primer';
+  try {
+    const q = query ?? buildPrimeQuery();
+    if (!q) return `${head}\n\nNo primer: the brain returned nothing relevant\n`;
+    const ep = resolveEndpoint('brain.context.pack');
+    const data = await withTimeout(
+      Promise.resolve().then(() => client.post(ep.path, { service: ep.service, body: { query: q, tokenBudget: PRIME_TOKEN_BUDGET } })),
+      timeoutMs,
+    );
+    const passages = Array.isArray(data?.passages) ? data.passages : [];
+    const insufficient = data?.insufficient === true || data?.relevance?.insufficient === true || passages.length === 0;
+    if (insufficient) return `${head}\n\nNo primer: the brain returned nothing relevant\n`;
+    const lines = passages.map((p) => {
+      const c = p.citation || {};
+      const text = String(p.text || '').replace(/\s+/g, ' ').trim().slice(0, PRIME_SNIPPET_CHARS);
+      return `- ${c.title || 'Untitled'} (${p.noteId || c.noteId || '?'}): ${text}`;
+    });
+    return `${head}\n\nQuery (stream is advisory): ${q}\n\n${lines.join('\n')}\n`;
+  } catch (err) {
+    return `${head}\n\nNo primer: brain unreachable (${err?.message || 'unknown error'})\n`;
+  }
+}
+
+/** Save a handoff to the knowledge brain as a private note. Returns { ok, noteId?, error? }; never throws. */
+export async function saveHandoffNote(client, { agentId, content, prov = {}, sessionName, now = new Date() }) {
+  try {
+    const ep = resolveEndpoint('brain.capture.create');
+    const iso = now.toISOString();
+    const provLines = [
+      `Agent: ${agentId}`,
+      prov.repo ? `Repo: ${prov.repo}` : null,
+      prov.commit ? `Commit: ${prov.commit}` : null,
+      sessionName ? `Session: ${sessionName}` : null,
+      `At: ${iso}`,
+    ].filter(Boolean);
+    const text = `${content}\n\n## Provenance\n\n${provLines.map((l) => `- ${l}`).join('\n')}\n`;
+    const data = await client.post(ep.path, {
+      service: ep.service,
+      body: { title: `Handoff: ${agentId} ${iso}`, text, tags: ['handoff', agentId], scope: 'user' },
+    });
+    return { ok: true, noteId: data?.noteId };
+  } catch (err) {
+    return { ok: false, error: err?.message || 'unknown error' };
+  }
+}

package/lib/core/callerSource.js

@@ -0,0 +1,129 @@
+/**
+ * HITL-CONTEXT (AQ-9A phase 6): work out WHICH session is calling when
+ * $QUOX_SESSION is unset, so an approval card says "BRAIN2-AUDIT (CLI)"
+ * instead of a bare user id. Display-only: the server never authorizes on it.
+ *
+ * Precedence:
+ *   1. QUOX_SESSION
+ *   2. QUOX_STREAM (advisory)
+ *   3. the agent attached by this Claude process tree
+ *      (~/.quox/attach/sessions/claude-<pid>/<agent>/)
+ *   4. the slot held by this process tree (held-slots.json sessionKey claude-<pid>)
+ *   5. last resort: "<parent process> in ~/<cwd>"
+ *
+ * Never reads token contents and never emits secrets: only directory names,
+ * the kit's display_name, the slot's session label and the cwd.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+
+/** Tools the collector always holds for a human when an agent proposes them. */
+export const APPROVAL_GATED_TOOLS = new Set([
+  'loop_halt', 'slot_assign', 'bob_dispatch_build', 'email_send', 'send_notification',
+  'remote_ssh', 'ssh_exec', 'db_query', 'alerts_manage', 'backup_run',
+  'keeper_backup_create', 'deploy_template', 'gemini_generate', 'perplexity_research',
+  'system_admin', 'proxmox_vm_action', 'calendar_event_create',
+]);
+
+export const MISSING_REASON_WARNING =
+  'approval requests without --reason show \'none given\' to the human; pass --reason "why"';
+
+/** One-line stderr warning when a gated tool is run without --reason, else null. */
+export function missingReasonWarning(toolName, reason) {
+  if (!APPROVAL_GATED_TOOLS.has(String(toolName || ''))) return null;
+  if (typeof reason === 'string' && reason.trim()) return null;
+  return `warning: ${MISSING_REASON_WARNING}`;
+}
+
+function cleanLabel(v, n = 48) {
+  const s = String(v == null ? '' : v).replace(/[^\w .:@+\-/~]/g, '').trim().slice(0, n);
+  return s || null;
+}
+
+const defaultDeps = {
+  readName: (pid) => { try { return readFileSync(`/proc/${pid}/comm`, 'utf-8').trim(); } catch { return null; } },
+  readPpid: (pid) => {
+    try {
+      const s = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+      const rest = s.slice(s.lastIndexOf(')') + 2).trim().split(/\s+/);
+      const p = parseInt(rest[1], 10);
+      return Number.isFinite(p) ? p : null;
+    } catch { return null; }
+  },
+  attachSessionsRoot: () => join(homedir(), '.quox', 'attach', 'sessions'),
+  heldSlotsPath: () => join(homedir(), '.quox', 'held-slots.json'),
+  readdir: (d) => { try { return readdirSync(d, { withFileTypes: true }); } catch { return []; } },
+  readJson: (p) => { try { return existsSync(p) ? JSON.parse(readFileSync(p, 'utf-8')) : null; } catch { return null; } },
+  exists: existsSync,
+  cwd: () => { try { return process.cwd(); } catch { return ''; } },
+  home: () => homedir(),
+  pid: () => process.pid,
+};
+
+function findClaudeAncestor(deps, startPid) {
+  let pid = startPid;
+  for (let hop = 0; hop < 24; hop += 1) {
+    if (deps.readName(pid) === 'claude') return pid;
+    const pp = deps.readPpid(pid);
+    if (!pp || pp === pid || pid === 1) break;
+    pid = pp;
+  }
+  return null;
+}
+
+function attachedAgentLabel(deps, claudePid) {
+  const dir = join(deps.attachSessionsRoot(), `claude-${claudePid}`);
+  const agents = deps.readdir(dir).filter((e) => e.isDirectory() && deps.exists(join(dir, e.name, 'token')));
+  if (agents.length === 0) return null;
+  const name = agents[0].name;
+  const kit = deps.readJson(join(dir, name, 'kit.json'));
+  return cleanLabel(kit && kit.display_name) || cleanLabel(name);
+}
+
+function heldSlotLabel(deps, claudePid) {
+  const all = deps.readJson(deps.heldSlotsPath());
+  if (!all || typeof all !== 'object') return null;
+  for (const [slot, e] of Object.entries(all)) {
+    if (e && e.sessionKey === `claude-${claudePid}`) return cleanLabel(e.session) || cleanLabel(slot);
+  }
+  return null;
+}
+
+function cwdLabel(deps) {
+  const cwd = deps.cwd();
+  if (!cwd) return null;
+  const home = deps.home();
+  if (home && cwd === home) return '~';
+  if (home && cwd.startsWith(`${home}/`)) return `~/${cwd.slice(home.length + 1)}`;
+  return basename(cwd) || null;
+}
+
+/** @returns {{ label: string|null, via: string }} */
+export function detectCallerSource(env = process.env, overrides = {}) {
+  const deps = { ...defaultDeps, ...overrides };
+  const fromSession = cleanLabel(env.QUOX_SESSION);
+  if (fromSession) return { label: fromSession, via: 'QUOX_SESSION' };
+  const fromStream = cleanLabel(env.QUOX_STREAM);
+  if (fromStream) return { label: fromStream, via: 'QUOX_STREAM' };
+
+  let claudePid = null;
+  try { claudePid = findClaudeAncestor(deps, deps.pid()); } catch { claudePid = null; }
+  if (claudePid) {
+    const agent = attachedAgentLabel(deps, claudePid);
+    if (agent) return { label: agent, via: 'attached_agent' };
+    const slot = heldSlotLabel(deps, claudePid);
+    if (slot) return { label: slot, via: 'held_slot' };
+  }
+
+  let parent = null;
+  try {
+    const pp = deps.readPpid(deps.pid());
+    parent = pp ? deps.readName(pp) : null;
+  } catch { parent = null; }
+  const who = claudePid ? 'claude' : cleanLabel(parent, 24);
+  const where = cwdLabel(deps);
+  if (who && where) return { label: cleanLabel(`${who} in ${where}`), via: 'process' };
+  if (who) return { label: who, via: 'process' };
+  return { label: null, via: 'none' };
+}

package/lib/core/claudeLs.js

@@ -0,0 +1,94 @@
+/**
+ * `quox claude ls`: one row per quox-* tmux session. Pure parse/build/render
+ * functions take injected tmux output, held-slots JSON and a clock so they
+ * unit-test without tmux. SLOT comes from ~/.quox/held-slots.json (holder
+ * session name), AGENT from the attach kit of the claude pid that slot entry
+ * records (~/.quox/attach/sessions/claude-<pid>/<agent>/). Both are '-' when
+ * not derivable (a session that holds no slot has no recorded pid).
+ */
+import { spawnSync as realSpawnSync } from 'node:child_process';
+import { PREFIX, programOf } from './governedSession.js';
+import { slotsBySession, readAttachSafe, readHeldSlotsSafe } from './liveSessionsReport.js';
+import { line } from './quoxglyph.js';
+
+export const LS_FORMAT = '#{session_name}\t#{session_created}\t#{session_attached}\t#{session_activity}\t#{session_windows}';
+
+export function formatAge(sec) {
+  const s = Math.max(0, Math.floor(sec));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+const toDate = (v) => new Date(Number(v) * 1000);
+
+export function parseQuoxSessions(out) {
+  return String(out || '').split('\n').map((l) => l.split('\t'))
+    .filter((c) => c.length >= 5 && c[0].startsWith(PREFIX) && c[0].length > PREFIX.length)
+    .map((c) => ({
+      name: c[0].slice(PREFIX.length),
+      created: toDate(c[1]),
+      clients: Number(c[2]) || 0,
+      activity: toDate(c[3]),
+      windows: Number(c[4]) || 0,
+    }));
+}
+
+export function buildRows({ tmuxOut, held, now = new Date(), attachLookup = readAttachSafe }) {
+  const bySession = slotsBySession(held);
+  return parseQuoxSessions(tmuxOut)
+    .sort((a, b) => b.activity - a.activity)
+    .map((s) => {
+      // The slot ledger records the bare session name (what --resume NAME used).
+      const hit = bySession[s.name] || bySession[s.name.replace(/^(codex-|gemini-|tui-)/, '')] || null;
+      const att = hit ? attachLookup(hit.pid) : null;
+      const age = (d) => formatAge((now - d) / 1000);
+      return {
+        name: s.name,
+        state: s.clients > 0 ? 'attached' : 'detached',
+        clients: s.clients,
+        created: s.created.toISOString(),
+        created_age: age(s.created),
+        last_active: s.activity.toISOString(),
+        active_age: age(s.activity),
+        slot: hit ? hit.slot : null,
+        agent: att ? att.agent : null,
+        backend: programOf(s.name),
+      };
+    });
+}
+
+const clip = (v, n) => {
+  const a = [...String(v)];
+  return a.length > n ? a.slice(0, n - 1).join('') + '…' : String(v);
+};
+
+export function renderTable(rows, { color = false } = {}) {
+  const W = { NAME: 20, STATE: 9, CLIENTS: 8, CREATED: 8, 'LAST ACTIVE': 12, SLOT: 8, AGENT: 8, BACKEND: 7 };
+  const cols = Object.keys(W);
+  const cell = (v, k, last) => (last ? clip(v, W[k]) : clip(v, W[k] - 1).padEnd(W[k]));
+  const fmt = (vals) => cols.map((k, i) => cell(vals[i], k, i === cols.length - 1)).join('');
+  const head = line('quox', 'sessions', { result: `${rows.length} running` });
+  const body = rows.map((r) => fmt([r.name, r.state, r.clients, r.created_age, r.active_age, r.slot || '-', r.agent || '-', r.backend]));
+  return [head, fmt(cols), ...body].join('\n');
+}
+
+export function runClaudeLs({ json = false } = {}, over = {}) {
+  const d = {
+    spawnSync: realSpawnSync, now: () => new Date(), write: (s) => process.stdout.write(s),
+    held: undefined, attachLookup: readAttachSafe, ...over,
+  };
+  const r = d.spawnSync('tmux', ['list-sessions', '-F', LS_FORMAT], { encoding: 'utf8' });
+  if (r && r.error && r.error.code === 'ENOENT') {
+    d.write('tmux is not installed (apt install tmux / brew install tmux).\n');
+    return 1;
+  }
+  // A non-zero exit means no server is running (nothing to list), not an error.
+  const out = r && r.status === 0 ? r.stdout : '';
+  const rows = buildRows({ tmuxOut: out, held: d.held ?? readHeldSlotsSafe(), now: d.now(), attachLookup: d.attachLookup });
+  if (json) { d.write(JSON.stringify(rows, null, 2) + '\n'); return 0; }
+  if (!rows.length) { d.write('No quox sessions running.\n'); return 0; }
+  d.write(renderTable(rows) + '\n');
+  return 0;
+}