quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/sound/output.js

@@ -0,0 +1,52 @@
+/**
+ * Where a terminal earcon goes: a local OS player, the terminal bell, or
+ * nowhere. Pure decisions here; the controller (index.js) does the I/O.
+ */
+import { spawnSync } from 'node:child_process';
+
+const OFF_VALUES = new Set(['off', '0', 'false', 'no', 'silent']);
+
+/**
+ * 'off'   : --print, non-TTY, CI, or QUOX_SOUND=off. Never a sound, never an escape write.
+ * 'bel'   : over SSH the speaker is on the other end, so only the terminal bell can reach it.
+ * 'audio' : a local desktop; play the WAV (falls back to the bell when no player exists).
+ */
+export function soundMode({ env = {}, stdout, print = false } = {}) {
+  if (print || !stdout?.isTTY) return 'off';
+  if (env.CI && !OFF_VALUES.has(String(env.CI).toLowerCase())) return 'off';
+  if (OFF_VALUES.has(String(env.QUOX_SOUND ?? '').toLowerCase())) return 'off';
+  if (env.SSH_CONNECTION || env.SSH_TTY) return 'bel';
+  return 'audio';
+}
+
+const psQuote = (s) => `'${String(s).replace(/'/g, "''")}'`;
+
+const PLAYERS = {
+  linux: [
+    { cmd: 'pw-play', args: (f) => [f] },
+    { cmd: 'paplay', args: (f) => [f] },
+    { cmd: 'aplay', args: (f) => ['-q', f] }
+  ],
+  darwin: [{ cmd: 'afplay', args: (f) => [f] }],
+  win32: [{ cmd: 'powershell', args: (f) => ['-NoProfile', '-NonInteractive', '-Command', `(New-Object Media.SoundPlayer(${psQuote(f)})).PlaySync()`] }]
+};
+
+/** Is `cmd` on PATH? (one lookup per player, cached by the controller) */
+export function onPath(cmd, platform = process.platform) {
+  try {
+    const r = platform === 'win32'
+      ? spawnSync('where', [cmd], { stdio: 'ignore', timeout: 2000 })
+      : spawnSync('sh', ['-c', `command -v ${cmd}`], { stdio: 'ignore', timeout: 2000 });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+/** First available player for this platform, or null. */
+export function findPlayer({ platform = process.platform, has = (c) => onPath(c, platform) } = {}) {
+  const list = PLAYERS[platform] || PLAYERS.linux;
+  return list.find(p => has(p.cmd)) || null;
+}
+
+/** Only these may ring the bell: the bell is for a human, not for feedback. */
+export const BEL_IDS = new Set(['hitl', 'critical']);
+export const BEL = '\x07';

package/lib/quoxon/sound/synth.js

@@ -0,0 +1,122 @@
+/**
+ * Offline renderer for the QuoxSound earcons: the dashboard's Web Audio
+ * recipes (src/services/quoxSound.js RECIPES) rendered sample by sample into
+ * 16-bit mono PCM WAV. No assets, no dependencies.
+ *
+ * Timbre: fundamental + octave (0.18) + twelfth (0.07), linear attack then an
+ * exponential decay to near-silence, same as the phone earcons. `success`
+ * reuses the granted interval (587 -> 880 Hz), `denied` the denied floor
+ * (233 Hz gliding down through a 600 Hz lowpass).
+ */
+
+export const SAMPLE_RATE = 44100;
+const HARMONICS = [[1, 1], [2, 0.18], [3, 0.07]];
+const FLOOR = 0.0001;
+
+/** The recipes as data: the same notes, times and envelopes as the dashboard. */
+export const RECIPES = {
+  hitl: { notes: [
+    { freq: 523.25, at: 0, decay: 0.30, peak: 0.20 },
+    { freq: 659.25, at: 0.15, decay: 0.30, peak: 0.19 },
+    { freq: 880.0, at: 0.30, decay: 0.32, peak: 0.18 }
+  ] },
+  notify: { notes: [
+    { freq: 698.46, at: 0, attack: 0.01, decay: 0.10, peak: 0.11 },
+    { freq: 932.33, at: 0.10, attack: 0.01, decay: 0.14, peak: 0.10 }
+  ] },
+  success: { notes: [
+    { freq: 587.33, at: 0, attack: 0.003, decay: 0.04, peak: 0.09 },
+    { freq: 880.0, at: 0.045, attack: 0.003, decay: 0.07, peak: 0.09 }
+  ] },
+  denied: { lowpass: 600, notes: [
+    { freq: 233.08, glideTo: 150, at: 0, attack: 0.004, decay: 0.16, peak: 0.28, harmonics: [[1, 1]] }
+  ] },
+  critical: { lowpass: 2400, notes: [0, 1, 2].map(i => (
+    { freq: 622.25, at: i * 0.12, type: 'square', attack: 0.003, decay: 0.07, peak: 0.12, harmonics: [[1, 1]] }
+  )) }
+};
+
+function envelope(t, attack, decay, peak) {
+  if (t < 0) return 0;
+  if (t < attack) return FLOOR + (peak - FLOOR) * (t / attack);
+  const d = t - attack;
+  if (d < decay) return peak * Math.pow(FLOOR / peak, d / decay);
+  return 0;
+}
+
+function renderNote(out, sr, n) {
+  const attack = n.attack ?? 0.008;
+  const decay = n.decay ?? 0.2;
+  const peak = n.peak ?? 0.2;
+  const harmonics = n.harmonics || HARMONICS;
+  const len = attack + decay + 0.02;
+  const start = Math.round(n.at * sr);
+  const count = Math.min(out.length - start, Math.round(len * sr));
+  for (const [mult, level] of harmonics) {
+    let phase = 0;
+    for (let i = 0; i < count; i++) {
+      const t = i / sr;
+      // exponential glide over attack + decay, then held (as exponentialRampToValueAtTime)
+      const f = n.glideTo ? n.freq * Math.pow(n.glideTo / n.freq, Math.min(1, t / (attack + decay))) : n.freq;
+      phase += (2 * Math.PI * f * mult) / sr;
+      const osc = n.type === 'square' ? (Math.sin(phase) >= 0 ? 1 : -1) : Math.sin(phase);
+      out[start + i] += osc * level * envelope(t, attack, decay, peak);
+    }
+  }
+}
+
+/** RBJ biquad lowpass, in place. */
+function lowpass(buf, sr, cutoff, q = Math.SQRT1_2) {
+  const w0 = (2 * Math.PI * cutoff) / sr;
+  const alpha = Math.sin(w0) / (2 * q);
+  const cos = Math.cos(w0);
+  const a0 = 1 + alpha;
+  const b0 = (1 - cos) / 2 / a0, b1 = (1 - cos) / a0, b2 = (1 - cos) / 2 / a0;
+  const a1 = (-2 * cos) / a0, a2 = (1 - alpha) / a0;
+  let x1 = 0, x2 = 0, y1 = 0, y2 = 0;
+  for (let i = 0; i < buf.length; i++) {
+    const x = buf[i];
+    const y = b0 * x + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
+    x2 = x1; x1 = x; y2 = y1; y1 = y;
+    buf[i] = y;
+  }
+}
+
+/** Render one earcon to float samples in [-1, 1]. */
+export function renderEarcon(id, { volume = 0.6, sampleRate = SAMPLE_RATE } = {}) {
+  const r = RECIPES[id];
+  if (!r) throw new Error(`unknown earcon ${id}`);
+  const secs = Math.max(...r.notes.map(n => n.at + (n.attack ?? 0.008) + (n.decay ?? 0.2) + 0.02));
+  const out = new Float32Array(Math.ceil(secs * sampleRate));
+  for (const n of r.notes) renderNote(out, sampleRate, n);
+  if (r.lowpass) lowpass(out, sampleRate, r.lowpass);
+  const g = Math.min(1, Math.max(0, volume));
+  for (let i = 0; i < out.length; i++) out[i] = Math.max(-1, Math.min(1, out[i] * g));
+  return out;
+}
+
+/** Float samples -> 16-bit mono PCM WAV (44-byte RIFF header). */
+export function toWav(samples, sampleRate = SAMPLE_RATE) {
+  const data = samples.length * 2;
+  const buf = Buffer.alloc(44 + data);
+  buf.write('RIFF', 0, 'ascii');
+  buf.writeUInt32LE(36 + data, 4);
+  buf.write('WAVE', 8, 'ascii');
+  buf.write('fmt ', 12, 'ascii');
+  buf.writeUInt32LE(16, 16);        // fmt chunk size
+  buf.writeUInt16LE(1, 20);         // PCM
+  buf.writeUInt16LE(1, 22);         // mono
+  buf.writeUInt32LE(sampleRate, 24);
+  buf.writeUInt32LE(sampleRate * 2, 28); // byte rate
+  buf.writeUInt16LE(2, 32);         // block align
+  buf.writeUInt16LE(16, 34);        // bits per sample
+  buf.write('data', 36, 'ascii');
+  buf.writeUInt32LE(data, 40);
+  for (let i = 0; i < samples.length; i++) {
+    const v = Math.max(-1, Math.min(1, samples[i]));
+    buf.writeInt16LE(Math.round(v < 0 ? v * 0x8000 : v * 0x7fff), 44 + i * 2);
+  }
+  return buf;
+}
+
+export const earconWav = (id, opts = {}) => toWav(renderEarcon(id, opts), opts.sampleRate ?? SAMPLE_RATE);

package/lib/quoxon/stray.js

@@ -0,0 +1,22 @@
+/**
+ * TUI-INPUT: a letter then "/" ("n/help") is a card answer that leaked into the composer ahead of a command.
+ * Pure: -> { letter, command } when the text looks like that and the rest names a known slash command, else null.
+ * (Ordinary "w/o", "b/c" or "and/or" never match: the word after the slash must be a command.)
+ */
+export function strayCardAnswer(text, names = []) {
+  const t = String(text ?? '').trim();
+  const m = /^([a-z])\/([a-z][\w-]*)(?=\s|$)/i.exec(t);
+  if (!m) return null;
+  if (!names.includes(`/${m[2].toLowerCase()}`)) return null;
+  return { letter: m[1].toLowerCase(), command: t.slice(1) };
+}
+
+/** The one-line question (askText adds the y/N/c keys). */
+export const strayQuestion = (s) => `Did you mean ${s.command.split(/\s+/)[0]}? (the '${s.letter}' looks like a stray card answer)`;
+
+/** True when the same message is already queued, steered or waiting for the server. */
+export function alreadyQueued(text, { pending = [], steering = [], waiting = null } = {}) {
+  const t = String(text ?? '').trim();
+  if (!t) return false;
+  return [...pending, ...steering].some(p => String(p.text ?? '').trim() === t) || String(waiting?.text ?? '').trim() === t;
+}

package/lib/quoxon/suggestCommand.js

@@ -0,0 +1,59 @@
+/**
+ * The assistant can hand the TUI a slash command for things only the terminal can do (attach a slot, join a room,
+ * open a view). The TUI is the authority: only an active registry command, never a `!` shell, never the commands the
+ * human must type (approvals, grants, session end, sign-in). The offer is "Run /slot hitl? y/N"; y runs it through the
+ * normal command path so every existing guard applies. A read-only view may run without asking when the user's
+ * ask was explicit.
+ */
+import { findCommandEntry } from './commands.js';
+
+// Commands that need the human's own typing: never offered, never run from a model suggestion.
+export const HUMAN_TYPED = new Set(['approve', 'yestoall', 'deny', 'authorise', 'authorize', 'authenticate', 'override', 'restart', 'quit', 'exit', 'login']);
+// Pure views, no effect: may run without asking when explicit, and only with no arguments.
+export const READ_ONLY_VIEWS = new Set(['approvals', 'mind', 'which', 'context', 'rooms', 'active', 'slots']);
+
+/** -> { ok: true, line, id, readOnly } | { ok: false, reason } */
+export function vetSuggestion(raw) {
+  const line = typeof raw === 'string' ? raw.trim() : '';
+  if (!line) return { ok: false, reason: 'empty' };
+  if (/[\r\n]/.test(line) || line.length > 120) return { ok: false, reason: 'not a single short line' };
+  if (!line.startsWith('/') || line.startsWith('//')) return { ok: false, reason: 'only slash commands can be suggested' };
+  const word = line.slice(1).split(/\s+/)[0];
+  const entry = findCommandEntry(word);
+  if (!entry || entry.kind !== 'command' || entry.status !== 'active') return { ok: false, reason: `/${word} is not a command here` };
+  if (HUMAN_TYPED.has(entry.id) || HUMAN_TYPED.has(word.toLowerCase())) return { ok: false, reason: `/${word} must be typed by you` };
+  const bare = line.slice(1 + word.length).trim() === '';
+  return { ok: true, line, id: entry.id, readOnly: READ_ONLY_VIEWS.has(entry.id) && bare };
+}
+
+/**
+ * Safety net (owner 2026-10-15 "STOP TELLING ME TO RUN COMMANDS"): the answer text named a command instead of the
+ * model calling terminal_suggest_command. Exactly ONE distinct slash command in backticks that passes vetSuggestion
+ * -> that vetted suggestion; none, two or more distinct, or a human-typed one (/approve, /restart...) -> null.
+ */
+export function namedCommand(text) {
+  const src = String(text || '');
+  const seen = new Set();
+  for (const m of src.matchAll(/`(\/[a-z][^`\n]{0,118})`/gi)) {
+    if (mentionsAPath(src, m.index, m[0].length, m[1])) continue; // `/health` the endpoint is not /health the command
+    seen.add(m[1].trim().replace(/\s+/g, ' '));
+  }
+  if (seen.size !== 1) return null;
+  const v = vetSuggestion([...seen][0]);
+  return v.ok ? v : null;
+}
+
+// A URL path, not a command (owner live 05:26: "the `/health` endpoint is erroring" offered "Run /health?").
+const PATHY = /\b(endpoints?|paths?|routes?|urls?|uris?|ports?|curl|wget|https?|localhost)\b|:\d{2,5}\b/i;
+const VERBS = /\b(GET|POST|PUT|PATCH|DELETE|HEAD)\b/; // upper-case only: "to get a view" is not an HTTP verb
+function mentionsAPath(src, at, len, inner) {
+  const first = String(inner).trim().split(/\s+/)[0];
+  if (/^\/[^/]*\//.test(first)) return true; // /api/x or /health/ready: a longer path
+  const sentence = (from, dir) => { // the same sentence, up to 40 characters away
+    const t = dir < 0 ? src.slice(Math.max(0, from - 40), from) : src.slice(from, from + 40);
+    const parts = t.split(/[.!?\n]/);
+    return dir < 0 ? parts[parts.length - 1] : parts[0];
+  };
+  const near = sentence(at, -1) + ' ' + sentence(at + len, 1);
+  return PATHY.test(near) || VERBS.test(near);
+}

package/lib/quoxon/term.js

@@ -0,0 +1,141 @@
+import { graphemes } from './textBuffer.js';
+import { createScreenMirror, MOUSE_ON, MOUSE_OFF, DSR } from './mouse.js';
+/**
+ * The terminal as Ink sees it.
+ *
+ * Ink 6.8 has a bookkeeping defect on its "frame was as tall as the screen" path (ink.js onRender): it
+ * repaints with clearTerminal + all static output + the frame WITHOUT a trailing newline, then records the
+ * frame WITH one (log.sync(outputToRender)). log-update then believes the cursor is one row lower than it
+ * is, so its next erase removes one extra row: the last line of whatever <Static> printed last. On
+ * 2026-10-12 that silently deleted "status writeup that's supposed to accompany completion." from a LUCID
+ * answer at 64x34 (test/quoxon/dropped.test.jsx replays it).
+ *
+ * Fix: Ink is told the screen has unlimited rows, so it never takes that path (only the fullscreen and
+ * repaint checks read stdout.rows). The app reads the real height from termRows() and keeps its live
+ * region shorter than the screen itself (app.js), so log-update can always erase it.
+ */
+export function inkStdout(out, { tap = null } = {}) {
+  if (!out || out.__quoxInk) return out;
+  // QUOXON-MOUSE: what Ink has drawn, as plain lines, for click hit-testing (mouse.js). Fed the same writes.
+  const mirror = out.isTTY ? createScreenMirror({ columns: () => out.columns }) : null;
+  // SCREEN-FRAMES: the same feed goes to the screen recorder's tap (screenFrames.js), which only queues it.
+  const feed = mirror && tap ? {
+    write: (c) => { mirror.write(c); try { tap.write(c); } catch { /* never break a frame */ } },
+    reset: () => { mirror.reset(); try { tap.reset(); } catch { /* ignore */ } }
+  } : mirror;
+  const diff = out.isTTY ? createLineDiff({ columns: () => out.columns, mirror: feed }) : null;
+  // One frame = one write: Ink brackets each frame in separate synchronized-update writes (?2026h ... ?2026l);
+  // they are held and sent together with the (diffed) frame, and a frame that changed nothing sends nothing.
+  // A write that sends nothing (or is held for the frame) must still call its callback: Ink's unmount waits
+  // on write('', cb) before waitUntilExit() resolves, and a dropped callback let the event loop drain, so
+  // the process exited without running anything after the app (/restart never started the new client).
+  let held = null;
+  let waiting = [];
+  const settle = () => { const cbs = waiting; waiting = []; for (const cb of cbs) cb(); };
+  const flush = () => {
+    if (held == null) return;
+    const body = held; held = null;
+    if (body) out.write(SYNC_ON + body + SYNC_OFF, settle); else if (waiting.length) out.write('', settle);
+  };
+  const write = diff ? (chunk, ...rest) => {
+    if (typeof chunk !== 'string') { flush(); diff.reset(); return out.write(chunk, ...rest); }
+    const cb = rest.find(a => typeof a === 'function');
+    if (chunk === SYNC_ON) { flush(); held = ''; setImmediate(flush); if (cb) waiting.push(cb); return true; }
+    if (chunk === SYNC_OFF && held != null) { if (cb) waiting.push(cb); flush(); return true; }
+    const d = diff(chunk);
+    if (held != null) { held += d; if (cb) waiting.push(cb); return true; }
+    if (d) return out.write(d, ...rest);
+    if (cb) out.write('', cb); // nothing to send: still a barrier behind the earlier writes
+    return true;
+  } : null;
+  return new Proxy(out, {
+    get(target, prop) {
+      if (prop === 'write' && write) return write;
+      if (prop === 'rows') return Infinity;
+      if (prop === 'termRows') return target.rows;
+      if (prop === 'frameRows') { const n = diff?.rows(); return n == null ? null : Math.min(n, Math.max(0, (target.rows || n + 1) - 1)); }
+      if (prop === '__quoxInk') return true;
+      if (prop === 'screen') return mirror;
+      const v = Reflect.get(target, prop, target);
+      return typeof v === 'function' ? v.bind(target) : v;
+    },
+    set(target, prop, value) { return Reflect.set(target, prop, value, target); }
+  });
+}
+
+/** Real terminal height, or null when unknown (not a TTY, tests). */
+export function termRows(stdout) {
+  const r = stdout?.__quoxInk ? stdout.termRows : stdout?.rows;
+  return Number.isFinite(r) && r > 0 ? r : null;
+}
+
+/**
+ * Line-diffed live frames (so native text selection survives animation).
+ *
+ * Ink repaints its live region as ONE write: eraseLines(previous line count) followed by the whole frame. A 12 fps
+ * ring or activity word would then rewrite the input line, and the user's selection on it, every frame. This
+ * transform recognises exactly that shape; when the new frame has the same height as the last one it moves up
+ * and rewrites only the lines that changed, leaving the cursor where Ink expects it (start of the line after the
+ * frame). Anything else (static history, clears, a height change, a resize, a write it did not see) passes
+ * through untouched and resets the diff, so the next frame is drawn in full. Cursor moves never scroll.
+ * (Ink's own incrementalRendering was tried first and duplicates lines on the dropped-text replay.)
+ */
+const ANSI_RE = /\x1b\[[0-9;?]*[ -\/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const visibleWidth = (line) => graphemes(String(line).replace(ANSI_RE, '')).length;
+const FRAME_RE = /^((?:\x1b\[2K\x1b\[1A)*\x1b\[2K\x1b\[G)([\s\S]*)$/;
+const SYNC_ON = '\x1b[?2026h', SYNC_OFF = '\x1b[?2026l';
+const TRANSPARENT = new Set(['\x1b[?2026h', '\x1b[?2026l', '\x1b[?25l', '\x1b[?25h', '', MOUSE_ON, MOUSE_OFF, DSR]); // + QUOXON-MOUSE mode switches and the click's cursor query
+export function createLineDiff({ columns = () => null, mirror = null } = {}) {
+  let prev = null; // lines of the last frame, trailing '' included
+  const bodyLines = (body) => (body && body.endsWith('\n') && !body.includes('\x1b[2J') ? body.split('\n') : null);
+  const diff = (chunk) => {
+    if (TRANSPARENT.has(chunk)) return chunk;
+    mirror?.write(chunk); // synchronized-update brackets and cursor hide/show around a frame
+    const m = FRAME_RE.exec(chunk);
+    // Not an erase+frame: a frame Ink drew after clearing (no erase prefix), static history, or something else.
+    // The last such write before the next erase is the frame on screen (Ink writes static output, then the frame).
+    if (!m) { prev = bodyLines(chunk); return chunk; }
+    const erased = (m[1].match(/\x1b\[2K/g) || []).length;
+    const cols = columns();
+    if (prev && cols > 0) {
+      // R3 D2: after a resize the terminal has reflowed the old frame (a narrower screen wraps each line onto more
+      // rows), and Ink's erase counts lines, not rows: ghost composers, or history reprinted to cover them. Count
+      // the rows the frame really occupies at this width; when that differs, go to its top and clear down.
+      const rows = prev.slice(0, -1).reduce((n, l) => n + Math.max(1, Math.ceil(visibleWidth(l) / cols)), 0);
+      if (rows !== erased - 1) {
+        prev = bodyLines(m[2]);
+        return `\r${rows ? `\x1b[${rows}A` : ''}\x1b[J${m[2]}`;
+      }
+    }
+    if (!m[2].endsWith('\n') || m[2].includes('\x1b[2J')) { prev = null; return chunk; }
+    const next = m[2].split('\n');
+    if (!prev || erased !== prev.length || next.length !== prev.length || next.length < 2) { prev = next; return chunk; }
+    const body = next.length - 1;
+    let out = body > 1 ? `\x1b[${body}A` : (body === 1 ? '\x1b[1A' : '');
+    let changed = 0;
+    for (let i = 0; i < body; i++) {
+      if (next[i] !== prev[i]) { out += `\r${next[i]}\x1b[K`; changed++; }
+      out += '\x1b[1B';
+    }
+    out += '\r';
+    prev = next;
+    return changed ? out : '';
+  };
+  diff.reset = () => { prev = null; mirror?.reset(); };
+  /** Rows the live frame occupies on screen (wrapped at the current width), or null when unknown. SLOT-RUN hand-over. */
+  diff.rows = () => {
+    if (!prev) return null;
+    const cols = columns();
+    return prev.slice(0, -1).reduce((n, l) => n + (cols > 0 ? Math.max(1, Math.ceil(visibleWidth(l) / cols)) : 1), 0);
+  };
+  return diff;
+}
+
+/**
+ * Ink render options for the interactive client. Standard rendering (Ink's incrementalRendering duplicated lines on
+ * the dropped-text replay); the stdout proxy line-diffs same-height frames instead. Never the alternate screen, and
+ * no mouse tracking unless the user turns it on (/mouse on, QUOXON-MOUSE): native selection keeps working by default.
+ */
+export function inkRenderOptions(stdout, { tap = null } = {}) {
+  return { exitOnCtrlC: false, stdout: inkStdout(stdout, { tap }) };
+}