quoxcli 0.0.0-stage → 0.3.1

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',
+  '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;
+}

package/lib/core/cliBuild.js

@@ -0,0 +1,62 @@
+/**
+ * KEEPER-REEXEC: which quox build is installed, read from files only (cheap enough to check on
+ * every keeper control poll, no git or child process). A git checkout (the dev box runs quox from
+ * a detached worktree) reports its HEAD sha; an npm install reports `v<version>`. null = unknown,
+ * and an unknown build never triggers a re-exec or a takeover.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SHA_RE = /^[0-9a-f]{40,64}$/;
+const read = (p) => { try { return readFileSync(p, 'utf-8').trim(); } catch { return null; } };
+
+function gitDirFor(root) {
+  const dotGit = join(root, '.git');
+  if (!existsSync(dotGit)) return null;
+  try {
+    if (statSync(dotGit).isDirectory()) return dotGit;
+  } catch { return null; }
+  const m = /^gitdir:\s*(.+)$/m.exec(read(dotGit) || '');
+  if (!m) return null;
+  return isAbsolute(m[1]) ? m[1] : resolve(root, m[1]);
+}
+
+function resolveRef(gitDir, ref) {
+  const loose = read(join(gitDir, ref));
+  if (loose && SHA_RE.test(loose)) return loose;
+  const commonRel = read(join(gitDir, 'commondir'));
+  const common = commonRel ? (isAbsolute(commonRel) ? commonRel : resolve(gitDir, commonRel)) : null;
+  if (common) {
+    const c = read(join(common, ref));
+    if (c && SHA_RE.test(c)) return c;
+  }
+  for (const d of [gitDir, common].filter(Boolean)) {
+    const packed = read(join(d, 'packed-refs')) || '';
+    for (const line of packed.split('\n')) {
+      const [sha, name] = line.trim().split(/\s+/);
+      if (name === ref && SHA_RE.test(sha)) return sha;
+    }
+  }
+  return null;
+}
+
+/** cliDir = the CLI package dir (holds package.json); its parent may be the git root. */
+export function readInstalledBuild(cliDir) {
+  try {
+    for (const root of [cliDir, dirname(cliDir)]) {
+      const gd = gitDirFor(root);
+      if (!gd) continue;
+      const head = read(join(gd, 'HEAD'));
+      if (!head) continue;
+      if (SHA_RE.test(head)) return head;
+      const m = /^ref:\s*(\S+)$/.exec(head);
+      if (m) { const sha = resolveRef(gd, m[1]); if (sha) return sha; }
+    }
+    const pkg = JSON.parse(readFileSync(join(cliDir, 'package.json'), 'utf-8'));
+    return pkg && pkg.version ? `v${pkg.version}` : null;
+  } catch { return null; }
+}
+
+/** The CLI package this module was loaded from (cli/lib/core -> cli). */
+export const CLI_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');