quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/textBuffer.js

@@ -0,0 +1,242 @@
+/**
+ * QUOXON composer text buffer: a pure reducer over { text, cursor, undo, redo,
+ * pastes, pasteSeq }. Written for Quox (no third-party code). The pattern is
+ * the usual one for Ink editors: all edits are actions, the view is derived.
+ *
+ * - cursor is a UTF-16 index that always sits on a grapheme boundary
+ *   (Intl.Segmenter), so emoji, ZWJ sequences and combining marks move as one.
+ * - Large pastes collapse to `[Pasted text #N +L lines]` and expand on send.
+ * - Invisible Unicode (zero width, bidi controls, tag characters) is detected
+ *   and stripped on Enter with a review round trip (see sanitizeForSend).
+ */
+
+const seg = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+export const PASTE_CHAR_LIMIT = 800;
+export const PASTE_LINE_LIMIT = 3;
+const UNDO_LIMIT = 100;
+const PASTE_RE = /\[Pasted text #(\d+) \+\d+ lines\]/g;
+
+export function initialBuffer(text = '') {
+  return { text, cursor: text.length, undo: [], redo: [], pastes: {}, pasteSeq: 0 };
+}
+
+export function graphemes(text) {
+  return Array.from(seg.segment(text), s => ({ index: s.index, text: s.segment }));
+}
+
+/** Boundary strictly before `idx` (0 if none). */
+export function prevBoundary(text, idx) {
+  let prev = 0;
+  for (const s of seg.segment(text)) {
+    if (s.index >= idx) break;
+    prev = s.index;
+  }
+  return prev;
+}
+
+/** Boundary strictly after `idx` (text.length if none). */
+export function nextBoundary(text, idx) {
+  for (const s of seg.segment(text)) {
+    if (s.index > idx) return s.index;
+  }
+  return text.length;
+}
+
+export function displayWidthOfLine(s) { return graphemes(s).length; }
+
+/** Placeholder range under or touching `idx` when deleting in a direction. */
+function placeholderAt(text, from, to) {
+  PASTE_RE.lastIndex = 0;
+  let m;
+  while ((m = PASTE_RE.exec(text))) {
+    const a = m.index, b = a + m[0].length;
+    if (to > a && from < b) return { a, b };
+  }
+  return null;
+}
+
+function snapshot(s) { return { text: s.text, cursor: s.cursor, pastes: s.pastes, pasteSeq: s.pasteSeq }; }
+
+function commit(s, next) {
+  const undo = [...s.undo, snapshot(s)].slice(-UNDO_LIMIT);
+  return { ...s, ...next, undo, redo: [] };
+}
+
+export function lineCol(text, cursor) {
+  const before = text.slice(0, cursor);
+  const line = before.split('\n').length - 1;
+  const start = before.lastIndexOf('\n') + 1;
+  return { line, col: graphemes(text.slice(start, cursor)).length, start };
+}
+
+function lineStarts(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) if (text[i] === '\n') starts.push(i + 1);
+  return starts;
+}
+
+function indexAtLineCol(text, line, col) {
+  const starts = lineStarts(text);
+  const l = Math.max(0, Math.min(line, starts.length - 1));
+  const start = starts[l];
+  const end = l + 1 < starts.length ? starts[l + 1] - 1 : text.length;
+  const gs = graphemes(text.slice(start, end));
+  if (col >= gs.length) return end;
+  return start + gs[col].index;
+}
+
+export function normalizeNewlines(t) { return String(t).replace(/\r\n?/g, '\n'); }
+
+/** Build the collapsed form of a paste, or null when it is small enough to inline. */
+export function shouldCollapse(text) {
+  const lines = text.split('\n').length;
+  return text.length > PASTE_CHAR_LIMIT || lines > PASTE_LINE_LIMIT;
+}
+
+export function bufferReducer(s, a) {
+  switch (a.type) {
+    case 'insert': {
+      const t = normalizeNewlines(a.text);
+      if (!t) return s;
+      return commit(s, { text: s.text.slice(0, s.cursor) + t + s.text.slice(s.cursor), cursor: s.cursor + t.length });
+    }
+    case 'newline':
+      return bufferReducer(s, { type: 'insert', text: '\n' });
+    case 'paste': {
+      const t = normalizeNewlines(a.text);
+      if (!t) return s;
+      if (!shouldCollapse(t)) return bufferReducer(s, { type: 'insert', text: t });
+      const n = s.pasteSeq + 1;
+      const ph = `[Pasted text #${n} +${t.split('\n').length} lines]`;
+      return commit(s, {
+        text: s.text.slice(0, s.cursor) + ph + s.text.slice(s.cursor),
+        cursor: s.cursor + ph.length,
+        pastes: { ...s.pastes, [n]: t },
+        pasteSeq: n
+      });
+    }
+    case 'backspace': {
+      if (s.cursor === 0) return s;
+      const ph = placeholderAt(s.text, prevBoundary(s.text, s.cursor), s.cursor);
+      const from = ph ? ph.a : prevBoundary(s.text, s.cursor);
+      const to = ph ? Math.max(ph.b, s.cursor) : s.cursor;
+      return commit(s, { text: s.text.slice(0, from) + s.text.slice(to), cursor: from });
+    }
+    case 'delete': {
+      if (s.cursor >= s.text.length) return s;
+      const nb = nextBoundary(s.text, s.cursor);
+      const ph = placeholderAt(s.text, s.cursor, nb);
+      const from = ph ? Math.min(ph.a, s.cursor) : s.cursor;
+      const to = ph ? ph.b : nb;
+      return commit(s, { text: s.text.slice(0, from) + s.text.slice(to), cursor: from });
+    }
+    case 'deleteWordBack': {
+      let i = s.cursor;
+      while (i > 0 && /\s/.test(s.text[i - 1])) i--;
+      while (i > 0 && !/\s/.test(s.text[i - 1])) i--;
+      if (i === s.cursor) return s;
+      return commit(s, { text: s.text.slice(0, i) + s.text.slice(s.cursor), cursor: i });
+    }
+    case 'killLineBack': {
+      const { start } = lineCol(s.text, s.cursor);
+      const from = start === s.cursor && start > 0 ? start - 1 : start;
+      if (from === s.cursor) return s;
+      return commit(s, { text: s.text.slice(0, from) + s.text.slice(s.cursor), cursor: from });
+    }
+    case 'left': return { ...s, cursor: prevBoundary(s.text, s.cursor) };
+    case 'right': return { ...s, cursor: nextBoundary(s.text, s.cursor) };
+    case 'home': return { ...s, cursor: lineCol(s.text, s.cursor).start };
+    case 'end': {
+      const nl = s.text.indexOf('\n', s.cursor);
+      return { ...s, cursor: nl === -1 ? s.text.length : nl };
+    }
+    case 'up': case 'down': {
+      const { line, col } = lineCol(s.text, s.cursor);
+      const target = a.type === 'up' ? line - 1 : line + 1;
+      const count = s.text.split('\n').length;
+      if (target < 0 || target >= count) return s;
+      return { ...s, cursor: indexAtLineCol(s.text, target, col) };
+    }
+    case 'undo': {
+      if (!s.undo.length) return s;
+      const prev = s.undo[s.undo.length - 1];
+      return { ...s, ...prev, undo: s.undo.slice(0, -1), redo: [...s.redo, snapshot(s)] };
+    }
+    case 'redo': {
+      if (!s.redo.length) return s;
+      const next = s.redo[s.redo.length - 1];
+      return { ...s, ...next, redo: s.redo.slice(0, -1), undo: [...s.undo, snapshot(s)] };
+    }
+    case 'set': {
+      const t = normalizeNewlines(a.text ?? '');
+      return commit(s, { text: t, cursor: t.length, pastes: a.keepPastes ? s.pastes : {}, pasteSeq: a.keepPastes ? s.pasteSeq : 0 });
+    }
+    case 'clear':
+      return s.text === '' ? s : commit(s, { text: '', cursor: 0, pastes: {}, pasteSeq: 0 });
+    default:
+      return s;
+  }
+}
+
+/** Replace placeholders with the pasted text. */
+export function expandPastes(s) {
+  return s.text.replace(PASTE_RE, (m, n) => (s.pastes[n] !== undefined ? s.pastes[n] : m));
+}
+
+// Invisible characters that can hide instructions in pasted text.
+const INVISIBLE_RE = /[­͏؜ᅟᅠ឴឵᠋-᠏​-‏‪-‮⁠-⁤⁦-ㅤ︀-︎ﾠ\u{E0000}-\u{E007F}\u{E0100}-\u{E01EF}]/u;
+const PICTO = /\p{Extended_Pictographic}/u;
+
+/**
+ * Strip invisible characters. ZWJ (U+200D) is kept only between two
+ * pictographs (family/flag emoji); VS16 is kept (not in the set above).
+ * Returns { clean, removed: [{ code, count }], total }.
+ */
+export function stripInvisible(text) {
+  const chars = Array.from(text);
+  const counts = new Map();
+  let out = '';
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i];
+    const isZwj = ch === '‍';
+    const keepZwj = isZwj && i > 0 && i + 1 < chars.length && PICTO.test(chars[i - 1]) && PICTO.test(chars[i + 1]);
+    if (!keepZwj && INVISIBLE_RE.test(ch)) {
+      const code = 'U+' + ch.codePointAt(0).toString(16).toUpperCase().padStart(4, '0');
+      counts.set(code, (counts.get(code) || 0) + 1);
+      continue;
+    }
+    out += ch;
+  }
+  const removed = [...counts].map(([code, count]) => ({ code, count }));
+  return { clean: out, removed, total: removed.reduce((n, r) => n + r.count, 0) };
+}
+
+/**
+ * Enter-time check. If anything invisible is present (in typed text or in a
+ * collapsed paste), return a cleaned buffer plus a note; the caller must NOT
+ * send, so the user reviews the cleaned text and presses Enter again.
+ * Otherwise returns { ok: true, text } with pastes expanded.
+ */
+export function sanitizeForSend(s) {
+  const typed = stripInvisible(s.text);
+  const pastes = {};
+  let total = typed.total;
+  const removed = [...typed.removed];
+  for (const [k, v] of Object.entries(s.pastes)) {
+    const r = stripInvisible(v);
+    pastes[k] = r.clean;
+    total += r.total;
+    removed.push(...r.removed);
+  }
+  if (total === 0) return { ok: true, text: expandPastes(s) };
+  const merged = new Map();
+  for (const r of removed) merged.set(r.code, (merged.get(r.code) || 0) + r.count);
+  const detail = [...merged].map(([c, n]) => (n > 1 ? `${c} x${n}` : c)).join(', ');
+  const cursor = Math.min(s.cursor, typed.clean.length);
+  return {
+    ok: false,
+    buffer: { ...s, text: typed.clean, cursor, pastes },
+    note: `Removed ${total} invisible character${total === 1 ? '' : 's'} (${detail}). Review, then press Enter again to send.`
+  };
+}

package/lib/quoxon/theme.js

@@ -0,0 +1,253 @@
+/**
+ * Shared look: the semantic palette, NO_COLOR handling, width helpers.
+ *
+ * Every colour is a ROLE mapped to a shade of the Q glyph (sky #38bdf8 -> indigo #6366f1 -> violet #a855f7,
+ * plus teal #06b6d4) or a state colour. Two tables: DARK (checked >= 4.5:1 against #000) and LIGHT
+ * (checked >= 4.5:1 against #fff), chosen by the terminal background (COLORFGBG when set, else dark).
+ * Each entry carries a 256-colour fallback used when the terminal is a 256-colour TTY without truecolor.
+ * Purple is for keys and accents only, never whole sentences.
+ */
+import { graphemes } from "./textBuffer.js";
+
+export const MIN_COLS = 40;
+
+/** role -> [truecolor hex, ansi256 index]. */
+export const DARK = {
+  heading: ['#38bdf8', 75], // first stop; the word is painted with HEADING_STOPS
+  icon: ['#06b6d4', 38],
+  bullet1: ['#38bdf8', 75], bullet2: ['#818cf8', 105], bullet3: ['#a855f7', 135],
+  label: ['#a5b4fc', 147],
+  value: ['#f1f5f9', 255],
+  number: ['#38bdf8', 75],
+  link: ['#38bdf8', 75],
+  code: ['#06b6d4', 38], codeBg: ['#1f2937', 235], codeRule: ['#155e75', 24],
+  key: ['#a855f7', 135],
+  muted: ['#7d8594', 245],
+  ok: ['#4ade80', 78], warn: ['#f59e0b', 214], error: ['#f87171', 210],
+  // legacy names, kept so existing call sites read the same
+  sky: ['#38bdf8', 75], violet: ['#a855f7', 135], indigo: ['#818cf8', 105], teal: ['#06b6d4', 38],
+  fail: ['#f87171', 210], dim: ['#7d8594', 245], faint: ['#4b5563', 240],
+  text: ['#cbd5e1', 252], input: ['#ffffff', 231], placeholder: ['#9ca3af', 248]
+};
+export const LIGHT = {
+  heading: ['#0369a1', 25],
+  icon: ['#0e7490', 30],
+  bullet1: ['#0369a1', 25], bullet2: ['#4338ca', 62], bullet3: ['#7e22ce', 91],
+  label: ['#4f46e5', 62],
+  value: ['#0f172a', 234],
+  number: ['#0369a1', 25],
+  link: ['#0369a1', 25],
+  code: ['#0e7490', 30], codeBg: ['#ecfeff', 195], codeRule: ['#67e8f9', 117],
+  key: ['#7e22ce', 91],
+  muted: ['#4b5563', 240],
+  ok: ['#15803d', 28], warn: ['#b45309', 130], error: ['#b91c1c', 124],
+  sky: ['#0369a1', 25], violet: ['#7e22ce', 91], indigo: ['#4338ca', 62], teal: ['#0e7490', 30],
+  fail: ['#b91c1c', 124], dim: ['#4b5563', 240], faint: ['#9ca3af', 248],
+  text: ['#334155', 238], input: ['#0f172a', 234], placeholder: ['#6b7280', 243]
+};
+/** Roles a reader must be able to read: each is held to >= 4.5:1 on its background (tests). */
+export const ROLES = ['heading', 'icon', 'bullet1', 'bullet2', 'bullet3', 'label', 'value', 'number', 'link', 'code', 'key', 'muted', 'ok', 'warn', 'error', 'text', 'placeholder'];
+
+/** Heading gradient stops across the word: sky -> indigo -> violet (light: the -700 shades). */
+export const HEADING_STOPS = { dark: ['#38bdf8', '#6366f1', '#a855f7'], light: ['#0369a1', '#4338ca', '#7e22ce'] };
+/** Agent names get a stable shade of the Q by hash. */
+export const AGENT_SHADES = {
+  dark: ['#38bdf8', '#a855f7', '#2dd4bf', '#818cf8', '#c4b5fd', '#7dd3fc'],
+  light: ['#0369a1', '#7e22ce', '#0f766e', '#4338ca', '#6d28d9', '#075985']
+};
+
+/** Model providers in their brand colours (dark, light). Unknown = muted. */
+export const PROVIDER_COLORS = {
+  openai: ['#f5f5f5', '#111111'], anthropic: ['#D97757', '#b4532e'], google: ['#4796E3', '#1a62c4'],
+  ollama: ['#e5e7eb', '#4b5563'], mistral: ['#FA520F', '#c2410c'], deepseek: ['#4D6BFE', '#2f4fe0'],
+  perplexity: ['#20808D', '#1a6b76'], xai: ['#f5f5f5', '#111111'],
+  // B5: OpenAI-compatible presets (dark bg shade, light bg shade; all >= 4.5:1 on their background)
+  openrouter: ['#6566F1', '#4f46e5'], huggingface: ['#FFD21E', '#8a6500'], groq: ['#F55036', '#c2290f'],
+  together: ['#0F6FFF', '#0b57d0'], lmstudio: ['#a78bfa', '#6d28d9'], vllm: ['#30A2FF', '#0b6bb8'],
+  openai_compatible: ['#9ca3af', '#4b5563']
+};
+/** Protocol trace marks (AEE, AOCL, VOLT, WARD), each its own Q shade (dark, light). */
+export const PROTO_COLORS = {
+  aee: ['#38bdf8', '#0369a1'], aocl: ['#818cf8', '#4338ca'], volt: ['#2dd4bf', '#0f766e'], ward: ['#a855f7', '#7e22ce']
+};
+
+/** Back-compat: the dark truecolor table as name -> hex. */
+export const COLORS = Object.fromEntries(Object.entries(DARK).map(([k, v]) => [k, v[0]]));
+export const MODE_COLOR = { ask: COLORS.sky, auto: COLORS.warn, plan: COLORS.violet, demo: COLORS.violet };
+
+export const mono = () => Boolean(process.env.NO_COLOR);
+
+/** Light background? COLORFGBG is "fg;bg" (sometimes "fg;x;bg"); bg 7 or 9..15 is light. Unknown = dark. */
+export function isLight(env = process.env) {
+  if (env.QUOX_THEME === 'light') return true;
+  if (env.QUOX_THEME === 'dark') return false;
+  const parts = String(env.COLORFGBG || '').split(';');
+  const bg = Number(parts[parts.length - 1]);
+  if (!env.COLORFGBG || !Number.isFinite(bg)) return false;
+  return bg === 7 || (bg >= 9 && bg <= 15);
+}
+export const table = (env = process.env) => (isLight(env) ? LIGHT : DARK);
+
+/** 256-colour terminal (a TTY that says 256color and not truecolor): use the explicit fallback index. */
+export function use256(env = process.env, isTTY = Boolean(process.stdout?.isTTY)) {
+  if (!isTTY) return false;
+  if (/^(truecolor|24bit)$/i.test(env.COLORTERM || '')) return false;
+  return /256/.test(env.TERM || '') || env.FORCE_COLOR === '2';
+}
+
+/** Role or legacy name -> an Ink colour string; anything else passes through. undefined under NO_COLOR.
+ *  `provider:<id>` and `proto:<name>` resolve through providerColor / proto. */
+export const c = (name) => {
+  if (mono()) return undefined;
+  if (typeof name === 'string' && name.startsWith('provider:')) return providerColor(name.slice(9));
+  if (typeof name === 'string' && name.startsWith('proto:')) return proto(name.slice(6));
+  const e = table()[name];
+  if (!e) return name;
+  return use256() ? `ansi256(${e[1]})` : e[0];
+};
+
+export function clampCols(n) { return Math.max(MIN_COLS, Number.isFinite(n) ? Math.floor(n) : 80); }
+
+export const clip = (s, max) => {
+  const gs = graphemes(String(s ?? '').replace(/\s+/g, ' '));
+  if (max <= 0) return '';
+  return gs.length > max ? gs.slice(0, max - 1).map(g => g.text).join('') + '…' : gs.map(g => g.text).join('');
+};
+
+const hex2rgb = (hex) => [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16));
+/** sRGB relative luminance and WCAG contrast. */
+export function luminance(hex) {
+  const [r, g, b] = hex2rgb(hex).map(v => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+export function contrast(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+}
+
+/** Per-character gradient colours for a heading (empty array under NO_COLOR). */
+export function gradient(text, stops = HEADING_STOPS[isLight() ? 'light' : 'dark']) {
+  const chars = [...String(text)];
+  if (mono()) return chars.map(ch => ({ ch, color: undefined }));
+  const rgb = stops.map(hex2rgb);
+  return chars.map((ch, i) => {
+    const k = chars.length > 1 ? i / (chars.length - 1) : 0;
+    const seg = Math.min(rgb.length - 2, Math.floor(k * (rgb.length - 1)));
+    const f = k * (rgb.length - 1) - seg;
+    const col = rgb[seg].map((v, j) => Math.round(v + (rgb[seg + 1][j] - v) * f));
+    return { ch, color: use256() ? stops[Math.round(k * (stops.length - 1))] : `#${col.map(v => v.toString(16).padStart(2, '0')).join('')}` };
+  });
+}
+
+/** Stable shade for an agent name (SEER, LUCID, VULCAN ... stay distinguishable). */
+export function agentColor(name) {
+  if (mono()) return undefined;
+  const shades = AGENT_SHADES[isLight() ? 'light' : 'dark'];
+  let x = 5381;
+  for (const ch of String(name || '').toUpperCase()) x = ((x * 33) ^ ch.codePointAt(0)) >>> 0;
+  return shades[x % shades.length];
+}
+
+/** Provider id from a provider and/or model name (turn.started.provider/model, vault types, display names). */
+export function providerOf(provider, model) {
+  const p = String(provider || '').toLowerCase().replace(/[\s_-]*(api|subscription)$/, '').trim();
+  const m = String(model || '').toLowerCase();
+  const DIRECT = { openai: 'openai', chatgpt: 'openai', gpt: 'openai', anthropic: 'anthropic', claude: 'anthropic', google: 'google', gemini: 'google',
+    ollama: 'ollama', local: 'ollama', mistral: 'mistral', deepseek: 'deepseek', perplexity: 'perplexity', xai: 'xai', grok: 'xai',
+    openrouter: 'openrouter', huggingface: 'huggingface', hf: 'huggingface', groq: 'groq', together: 'together', lmstudio: 'lmstudio', 'lm studio': 'lmstudio',
+    'lm-studio': 'lmstudio', vllm: 'vllm', custom: 'openai_compatible', openai_compatible: 'openai_compatible', 'openai-compatible': 'openai_compatible' };
+  if (DIRECT[p]) return DIRECT[p];
+  const x = m || p;
+  if (/^(gpt-|chatgpt|o[134](-|$)|openai)/.test(x)) return 'openai';
+  if (/^claude|^anthropic/.test(x)) return 'anthropic';
+  if (/^gemini|^google/.test(x)) return 'google';
+  if (/^ollama[:/]|^ollama$/.test(x)) return 'ollama';
+  if (/^(mistral|codestral|mixtral|magistral|devstral)/.test(x)) return 'mistral';
+  if (/^deepseek/.test(x)) return 'deepseek';
+  if (/^(sonar|perplexity|pplx)/.test(x)) return 'perplexity';
+  if (/^(grok|xai)/.test(x)) return 'xai';
+  return null;
+}
+/** Brand colour for a provider/model; unknown = muted; undefined under NO_COLOR. */
+export function providerColor(provider, model) {
+  if (mono()) return undefined;
+  const id = providerOf(provider, model);
+  if (!id) return c('muted');
+  return PROVIDER_COLORS[id][isLight() ? 1 : 0];
+}
+/** Colour for a protocol trace mark: aee sky, aocl indigo, volt teal, ward violet; unknown = muted. */
+export function proto(name) {
+  if (mono()) return undefined;
+  const e = PROTO_COLORS[String(name || '').toLowerCase()];
+  return e ? e[isLight() ? 1 : 0] : c('muted');
+}
+
+/** Bullet colour by list depth (0-based): sky, indigo, violet, cycling. */
+export const bulletRole = (depth) => ['bullet1', 'bullet2', 'bullet3'][((depth % 3) + 3) % 3];
+
+// ---- paint: split a plain line into coloured runs; the characters never change ---------------------
+const GLYPH_ROLE = {
+  '●': 'ok', '✔': 'ok', '◐': 'warn', '○': 'muted', '?': 'muted', '✖': 'error', '⚠': 'warn', '⊘': 'warn',
+  '◉': 'icon', 'Ⓠ': 'icon', '▸': 'key', '⛔': 'warn', '↳': 'icon', '»': 'muted', '·': 'muted', '⬢': 'icon', '⬡': 'muted'
+};
+const KEYS = '(?:(?:Ctrl|Shift|Alt|Cmd|Option)\\+\\S+|Enter|Tab|Esc|Up|Down|Left|Right|Space|Backspace|PgUp|PgDn)';
+const TOKEN = new RegExp([
+  '(https?:\\/\\/[^\\s)]+)', // 1 link
+  '(\\bquox(?: (?![·])[^\\s·,;)]+)+)', // 2 a quox command
+  '((?<![\\w/])\\/[a-z][\\w-]*)', // 3 slash command
+  `((?<![\\w+])${KEYS}(?![\\w+]))`, // 4 keyboard key
+  '((?<![\\w<])<[^>\\s]+>|\\[[^\\]\\s]+\\])', // 5 placeholder <name> or [args]
+  '( · )', // 6 separator
+  '((?<![\\w/.-])(?:(?:gpt|claude|gemini|o[134]|mistral|codestral|deepseek|sonar|grok)-[\\w.:-]*\\w|ollama:[\\w.:-]*\\w|OpenAI|openai|Anthropic|anthropic|Claude(?: API)?|Gemini|Ollama|ollama|Mistral|DeepSeek|Perplexity|Grok|xAI)(?![\\w-]))', // 7 provider/model
+  '((?<![\\w.#-])\\d+(?:[.,:-]\\d+)*(?:%|ms|s|k|m|h|d|x|KB|MB|GB)?(?![\\w]))' // 8 number
+].join('|'), 'g');
+const ROLE_OF = [null, 'link', 'code', 'key', 'key', 'muted', 'muted', 'provider', 'number'];
+const LETTER_KEY = /^([a-z])(?= (?:approve|deny|open|stop|peek|confirm|edit|retry|cancel|copy|quit)\b)/;
+
+/** Runs of `text` with roles; `base` colours the prose between tokens. Pure. */
+export function paintRuns(text, base) {
+  const out = [];
+  const push = (t, role) => { if (!t) return; const last = out[out.length - 1]; if (last && last.role === role) last.text += t; else out.push({ text: t, role }); };
+  const s = String(text ?? '');
+  let i = 0;
+  const startsSeg = (at) => at === 0 || s.slice(0, at).endsWith(' · ') || /^\s*$/.test(s.slice(0, at));
+  for (const m of s.matchAll(TOKEN)) {
+    proseRuns(s.slice(i, m.index), base, push, startsSeg(i));
+    const g = m.findIndex((x, k) => k > 0 && x !== undefined);
+    push(m[0], ROLE_OF[g] === 'provider' ? `provider:${providerOf(m[0], m[0])}` : ROLE_OF[g]);
+    i = m.index + m[0].length;
+  }
+  proseRuns(s.slice(i), base, push, startsSeg(i));
+  return out;
+}
+function proseRuns(seg, base, push, segStart) {
+  const k = segStart && seg.match(LETTER_KEY);
+  if (k) { push(k[1], 'key'); seg = seg.slice(1); }
+  push(seg, base);
+}
+
+/**
+ * A note/list line as runs: a leading state glyph, then `Label  value` (two spaces) or `label: value`,
+ * then tokens. tone: undefined/'dim' (neutral), 'ok', 'warn', 'accent', 'error'.
+ */
+export function paintLine(text, tone) {
+  const s = String(text ?? '');
+  const out = [];
+  const neutral = !tone || tone === 'dim';
+  const prose = tone === 'warn' ? 'warn' : tone === 'error' || tone === 'fail' ? 'error' : tone === 'accent' ? 'sky' : null;
+  const m = s.match(/^(\s*)(?:([●✔◐○?✖⚠⊘◉Ⓠ▸⛔↳»·⬢⬡])( ))?(.*)$/u);
+  const [, lead, glyph, gsp, rest0] = m;
+  if (lead) out.push({ text: lead, role: undefined });
+  if (glyph) out.push({ text: glyph, role: tone === 'warn' && glyph !== '○' ? 'warn' : GLYPH_ROLE[glyph] }, { text: gsp, role: undefined });
+  let rest = rest0;
+  const lv = rest.match(/^(\S[^·]{0,30}?\S|\S)( {2,})(\S.*)$/) || rest.match(/^([A-Za-z][\w .-]{0,22}:)( )(\S.*)$/);
+  let valueBase = prose || (tone === 'ok' && !glyph ? 'ok' : neutral && !lv && !glyph ? 'muted' : 'text');
+  if (lv && !/^https?:/.test(lv[1])) {
+    const pv = providerOf(lv[1].replace(/\s*\(.*\)$/, ''), null);
+    out.push({ text: lv[1], role: pv ? `provider:${pv}` : 'label' }, { text: lv[2], role: undefined });
+    rest = lv[3];
+    if (!prose) valueBase = 'value';
+  }
+  out.push(...paintRuns(rest, valueBase));
+  return out;
+}

package/lib/quoxon/transcript.js

@@ -0,0 +1,150 @@
+/**
+ * Dev transcript capture (opt-in, off by default). One JSONL line per client event so a local
+ * review loop can analyse sessions without the owner pasting terminal output.
+ *
+ * On when QUOX_DEV_TRANSCRIPT=1 or the flag file ~/.config/quox/dev-transcripts exists;
+ * QUOX_DEV_TRANSCRIPT=0 forces it off. Fields are ALLOWLISTED per event: objects are never
+ * dumped wholesale, and every string passes a token scrubber as a second line of defence.
+ */
+import { mkdirSync, openSync, writeSync, closeSync, existsSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const MAX_FIELD = 4000;
+export const SILENT_GAP_MS = 10000;
+
+export function transcriptEnabled({ env = process.env, home = homedir(), exists = existsSync } = {}) {
+  if (env.QUOX_DEV_TRANSCRIPT === '0') return false;
+  if (env.QUOX_DEV_TRANSCRIPT === '1') return true;
+  return exists(join(home, '.config', 'quox', 'dev-transcripts'));
+}
+
+const SCRUBS = [
+  [/eyJ[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]+)*/g, '[redacted-jwt]'],
+  [/\bBearer\s+[^\s"']+/gi, 'Bearer [redacted]'],
+  [/\bsk-[A-Za-z0-9_-]{8,}/g, '[redacted-key]'],
+  [/\b(?:ghp|gho|ghs|xox[abp]|qsk|AKIA)[A-Za-z0-9_-]{12,}/g, '[redacted-key]'],
+  [/((?:api[_-]?key|access[_-]?token|refresh[_-]?token|service[_-]?key|secret|password|passwd|authorization)["']?\s*[:=]\s*["']?)[^\s"',}]+/gi, '$1[redacted]']
+];
+
+export function scrub(s) {
+  let out = String(s);
+  for (const [re, rep] of SCRUBS) out = out.replace(re, rep);
+  return out;
+}
+
+/** Strings are scrubbed and truncated; non-strings become a scrubbed JSON string (never a raw object). */
+export function clean(v) {
+  if (v == null || typeof v === 'number' || typeof v === 'boolean') return v;
+  let s = typeof v === 'string' ? v : (() => { try { return JSON.stringify(v); } catch { return String(v); } })();
+  s = scrub(s);
+  return s.length > MAX_FIELD ? `${s.slice(0, MAX_FIELD)}…[truncated ${s.length - MAX_FIELD} chars]` : s;
+}
+
+// SSE event fields worth keeping, by name. Anything not listed is dropped.
+const SSE_FIELDS = ['type', 'agent', 'model', 'provider', 'hat', 'conversation_id', 'session_id', 'stage', 'message',
+  'content', 'call_id', 'tool', 'summary', 'status', 'result_summary', 'duration_ms', 'envelope_id', 'target', 'scope',
+  'risk', 'describable', 'dashboard_url', 'inbox_item_id', 'approval_id', 'decision', 'text', 'protocol', 'label', 'ref',
+  'detail', 'error', 'full_response'];
+const RECEIPT_FIELDS = ['verified', 'ward_seq'];
+// Metering only (numbers, never strings): lets a local eval loop sum the cost of interactive turns.
+const USAGE_FIELDS = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'];
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+
+export function pickSse(ev) {
+  const o = {};
+  if (!ev || typeof ev !== 'object') return o;
+  for (const k of SSE_FIELDS) if (ev[k] !== undefined) o[k] = clean(ev[k]);
+  if (ev.receipt && typeof ev.receipt === 'object') {
+    o.receipt = {};
+    for (const k of RECEIPT_FIELDS) if (ev.receipt[k] !== undefined) o.receipt[k] = clean(ev.receipt[k]);
+  }
+  if (num(ev.cost_usd)) o.cost_usd = ev.cost_usd;
+  if (ev.usage && typeof ev.usage === 'object') {
+    const u = {};
+    for (const k of USAGE_FIELDS) if (num(ev.usage[k])) u[k] = ev.usage[k];
+    if (Object.keys(u).length) o.usage = u;
+  }
+  return o;
+}
+
+/** Map one app dispatch action to a transcript record (or null to skip). */
+export function recordFor(a) {
+  switch (a?.type) {
+    case 'event': return { t: 'sse', ...pickSse(a.ev) };
+    case 'user': return { t: 'user', mode: a.queued ? 'queue-drain' : 'send', text: clean(a.text) };
+    case 'steer.add': return { t: 'user', mode: 'steer', id: clean(a.id), text: clean(a.text) };
+    case 'queue.add': return { t: 'user', mode: 'queue', text: clean(a.text) };
+    case 'steer.failed': case 'steer.converted': return { t: 'notice', kind: a.type, id: clean(a.id), text: clean(a.reason) };
+    case 'note': return { t: 'notice', kind: 'note', tone: clean(a.tone), text: clean(a.text) };
+    case 'error': return { t: 'error', text: clean(a.text) };
+    case 'notify': return { t: 'notify', approvals: a.patch?.approvals ?? null, error: clean(a.patch?.error ?? null) };
+    case 'turn.begin': return { t: 'turn.begin', turnId: clean(a.turnId) };
+    case 'approval.sent': return { t: 'approval.sent', action: clean(a.action), callId: clean(a.callId), tool: clean(a.tool), target: clean(a.target) };
+    case 'approval.result': return { t: 'approval.result', callId: clean(a.callId), outcome: clean(a.outcome), text: clean(a.text ?? null) };
+    case 'verbose': return { t: 'verbose', mode: clean(a.mode) };
+    case 'ctx': return { t: 'ctx', conversationId: clean(a.ctx?.conversationId ?? null) };
+    // /connect: provider and last 4 only, by construction (the key is never in an action).
+    case 'connect.started': return { t: 'connect.started', provider: clean(a.provider) };
+    case 'connect.saved': return { t: 'connect.saved', provider: clean(a.provider), last4: clean(a.last4) };
+    case 'inbox.sync': return null; // every 30 s, ids only: noise
+    default: return { t: 'action', type: clean(a?.type) };
+  }
+}
+
+/**
+ * -> null when disabled. Otherwise { action(a), command(line), resize(cols, rows), end(reason), path }.
+ * Never throws into the app: a write failure disables capture for the rest of the session.
+ */
+export function createTranscript({ env = process.env, home = homedir(), now = Date.now, exists = existsSync, meta = {} } = {}) {
+  if (!transcriptEnabled({ env, home, exists })) return null;
+  const dir = env.QUOX_DEV_TRANSCRIPT_DIR || join(home, '.local', 'share', 'quox', 'transcripts');
+  let fd = null;
+  const start = now();
+  const path = join(dir, `${new Date(start).toISOString().replace(/[:.]/g, '-')}-${process.pid}.jsonl`);
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+    fd = openSync(path, 'a', 0o600);
+    chmodSync(path, 0o600);
+  } catch { return null; }
+  const turn = { id: null, t0: 0, firstText: false, lastSse: 0 };
+  const write = (rec) => {
+    if (fd == null || !rec) return;
+    try { writeSync(fd, JSON.stringify({ ts: new Date(now()).toISOString(), ...rec }) + '\n'); }
+    catch { try { closeSync(fd); } catch { /* ignore */ } fd = null; }
+  };
+  write({ t: 'start', version: clean(meta.version ?? null), cols: meta.cols ?? null, rows: meta.rows ?? null,
+    profile: clean(meta.profile ?? null), org: clean(meta.org ?? null), cwd: clean(meta.cwd ?? null), pid: process.pid });
+
+  const action = (a) => {
+    const t = now();
+    const rec = recordFor(a);
+    if (a?.type === 'turn.begin') Object.assign(turn, { id: a.turnId, t0: t, firstText: false, lastSse: t });
+    if (a?.type === 'event' && turn.id) {
+      if (t - turn.lastSse > SILENT_GAP_MS) write({ t: 'gap', turnId: turn.id, ms: t - turn.lastSse, before: clean(a.ev?.type) });
+      turn.lastSse = t;
+    }
+    write(rec);
+    if (a?.type === 'event' && turn.id) {
+      const ty = a.ev?.type;
+      if (!turn.firstText && (ty === 'chunk' || ty === 'text.delta') && a.ev?.content) {
+        turn.firstText = true;
+        write({ t: 'timing', turnId: turn.id, first_text_ms: t - turn.t0 });
+      }
+      if (ty === 'turn.finished') {
+        write({ t: 'timing', turnId: turn.id, finish_ms: t - turn.t0, status: clean(a.ev?.status ?? null), saw_text: turn.firstText });
+        turn.id = null;
+      }
+    }
+  };
+  return {
+    path,
+    action,
+    command: (line) => { const [cmd, ...rest] = String(line).trim().split(/\s+/); write({ t: 'command', cmd: clean(cmd), arg: clean(rest.join(' ') || null) }); },
+    // Owner observation (/note): recorded verbatim (scrubbed, 2000 chars), never sent anywhere else.
+    note: (text) => write({ t: 'note', text: clean(String(text).slice(0, 2000)), ts: new Date(now()).toISOString() }),
+    resize: (cols, rows) => write({ t: 'resize', cols: cols ?? null, rows: rows ?? null }),
+    end: (reason = 'exit') => { write({ t: 'end', reason: clean(reason), duration_ms: now() - start }); if (fd != null) { try { closeSync(fd); } catch { /* ignore */ } fd = null; } }
+  };
+}