@milpa/comal 0.2.3 → 0.2.5

package/src/remote-permissions.mjs

@@ -0,0 +1,159 @@
+// Permission cards answered from the paired M5Stack, racing the terminal card: the first surface
+// that DECIDES wins. The desk is the single owner of "decided": a question is settled exactly once
+// (terminal or device), synchronously on the event loop, and every later answer reads stale.
+// A device answer is only ever "allow once" or "deny": it never saves a rule and never widens the
+// policy. It is checked again here, whatever the backend and the relay already checked:
+//   arm on → not expired → from the armed device → the question still pending here → the card the
+//   person saw (digest) → a card the device may answer → no confirm:'always' → not plan → a decision.
+import { readFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { t } from './i18n/index.mjs';
+import { buildDeviceCard } from './remote-device-card.mjs';
+
+const CONTRACT = JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json', import.meta.url), 'utf8'));
+const DECISIONS = new Set(CONTRACT.inputs.permission_answer.properties.decision.enum);
+/** What a permission.answer ACK may say: its verdict states, and a decision or a contract refusal. */
+export const PERMISSION_ACK_STATES = new Set(['applied', 'stale', 'refused', 'expired', 'rejected']);
+export const PERMISSION_OUTCOMES = new Set([...DECISIONS, ...CONTRACT.refusals]);
+const LEDGER_MAX = 512;
+const live = value => typeof value === 'function' ? value() : value;
+
+export class PermissionDesk {
+  constructor({ now = Date.now, sendCard = () => {}, closeCard = () => {}, record = async () => {} } = {}) {
+    Object.assign(this, { now, sendCard, closeCard, record });
+    this.pending = new Map();
+    // Same request_id (a lost ACK redelivers it) → the same answer, never a second decision.
+    this.ledger = new Map();
+  }
+  /** One open question. `decision` resolves once, with whichever surface settled it first. */
+  open({ questionId, name, input, confirmAlways = false, mode = 'default', card }) {
+    if (this.pending.has(questionId)) throw Error('This permission question is already open.');
+    const controller = new AbortController();
+    let resolve, reject;
+    const decision = new Promise((done, fail) => { resolve = done; reject = fail; });
+    decision.catch(() => {});
+    const entry = { questionId, name, input, confirmAlways, mode, card, controller, decided: false, closed: false };
+    const settle = (result, failed = false) => {
+      if (entry.decided) return false;
+      entry.decided = true;
+      this.#closeCard(entry);
+      if (failed) reject(result); else resolve(result);
+      controller.abort();
+      return true;
+    };
+    entry.settle = settle;
+    this.pending.set(questionId, entry);
+    try { this.sendCard(card); } catch {}
+    return {
+      signal: controller.signal,
+      decision,
+      /** The terminal card answered (or rejected): first wins, a later device answer reads stale. */
+      terminal: value => settle({ allowed: Boolean(value && typeof value === 'object' ? value.allowed : value), by: 'terminal', value }),
+      fail: error => settle(error, true),
+      close: () => {
+        if (this.pending.get(questionId) === entry) this.pending.delete(questionId);
+        settle(Object.assign(Error('The permission question closed.'), { name: 'AbortError' }), true);
+        this.#closeCard(entry);
+      },
+    };
+  }
+  #closeCard(entry) {
+    if (entry.closed) return;
+    entry.closed = true;
+    try { this.closeCard(entry.questionId); } catch {}
+  }
+  #remember(requestId, result) {
+    if (typeof requestId !== 'string' || !requestId) return result;
+    this.ledger.set(requestId, result);
+    if (this.ledger.size > LEDGER_MAX) this.ledger.delete(this.ledger.keys().next().value);
+    return result;
+  }
+  /** A claimed device input (kind permission.answer). Returns the ACK verdict {state, outcome}. */
+  async handle(input, { deviceId = null, armed = () => false } = {}) {
+    const requestId = input?.request_id;
+    if (typeof requestId === 'string' && this.ledger.has(requestId)) return this.ledger.get(requestId);
+    const refuse = (state, outcome) => this.#remember(requestId, { state, outcome });
+    const control = input?.control && typeof input.control === 'object' ? input.control : {};
+    let isArmed = false;
+    try { isArmed = armed() === true; } catch {}
+    if (!isArmed) return refuse('refused', 'disarmed');
+    const expires = Number(input?.expires_at);
+    if (input?.expires_at === undefined || input?.expires_at === null || !Number.isFinite(expires) || expires * 1000 <= this.now()) return refuse('expired', 'expired');
+    if (typeof deviceId !== 'string' || !deviceId || input?.device_id !== deviceId) return refuse('refused', 'other_device');
+    const entry = typeof control.question_id === 'string' ? this.pending.get(control.question_id) : undefined;
+    if (!entry || entry.decided) return refuse('stale', 'stale');
+    if (typeof control.card_digest !== 'string' || control.card_digest !== entry.card?.card_digest) return refuse('stale', 'stale');
+    if (entry.card.kind === 'terminal') return refuse('refused', 'terminal_only');
+    let always = true, mode = 'plan';
+    try { always = live(entry.confirmAlways) === true; mode = live(entry.mode); } catch {}
+    if (always) return refuse('refused', 'confirm_always');
+    if (mode === 'plan') return refuse('refused', 'plan_mode');
+    if (!DECISIONS.has(control.decision)) return refuse('refused', 'stale');
+    // Settled synchronously: nothing else can decide this question after this line.
+    if (!entry.settle({ allowed: control.decision === 'allow_once', by: 'device' })) return refuse('stale', 'stale');
+    const result = this.#remember(requestId, { state: 'applied', outcome: control.decision });
+    try { await this.record({ type: 'remote_control', action: 'permissions.answer', question_id: entry.questionId, decision: control.decision, device_id: input.device_id }); } catch {}
+    return result;
+  }
+}
+
+/**
+ * The confirm path with both surfaces: the terminal card (terminal(signal) → ui.confirm) and the
+ * device card. Returns what PermissionPolicy expects from confirm: the terminal's own value, or
+ * the device's boolean (never a remember choice).
+ */
+export async function answerFromEitherSurface({ desk, questionId, name, input, confirmAlways, mode, card, signal, terminal, notice = () => {} }) {
+  let entry;
+  // A desk that cannot open the question leaves the terminal card, as before the device existed.
+  try { entry = desk.open({ questionId, name, input, confirmAlways, mode, card }); } catch { return terminal(signal); }
+  try {
+    let shown;
+    try { shown = Promise.resolve(terminal(signal ? AbortSignal.any([signal, entry.signal]) : entry.signal)); }
+    catch (error) { shown = Promise.reject(error); }
+    shown.then(value => entry.terminal(value), error => entry.fail(error));
+    const result = await entry.decision;
+    if (result.by !== 'device') return result.value;
+    // The terminal card closed because the device answered: the terminal says so.
+    try { notice(deviceAnswerNotice({ allowed: result.allowed, tool: card?.tool ?? name })); } catch {}
+    return result.allowed;
+  } finally { entry.close(); }
+}
+
+/** The terminal's line when the M5Stack decided a card. */
+export const deviceAnswerNotice = ({ allowed, tool }) => t('Answered on the M5Stack: {decision} · {tool}', { decision: t(allowed ? 'allowed once' : 'denied'), tool: String(tool ?? '') });
+
+/**
+ * PermissionPolicy's confirm when /rc may carry the card to the M5Stack. Only an armed host with a
+ * question id engages the device; an aborted question, or any failure while preparing the device
+ * card, shows the plain terminal card instead (the device is a convenience, never a gate).
+ */
+export async function confirmWithDevice({ armed, desk, questionId, name, input, summary, signal, terminal, resolveWrite, confirmAlways, mode, notice }) {
+  if (!armed || !questionId || signal?.aborted) return terminal(signal);
+  let card;
+  try {
+    // confirm:'always' and plan mode stay in the terminal: the device gets a card it cannot answer, and nothing of
+    // the command, the change or a summary leaves the machine (an unreadable policy counts as terminal-only too).
+    let terminalOnly = true;
+    try { terminalOnly = live(confirmAlways) === true || live(mode) === 'plan'; } catch {}
+    card = terminalOnly ? buildDeviceCard({ questionId, name, input, terminalOnly: true }) : buildDeviceCard({ questionId, name, input, summary, overwrite: await writeOverwrite(name, input, resolveWrite) });
+  }
+  catch { return terminal(signal); }
+  if (signal?.aborted) return terminal(signal);
+  return answerFromEitherSurface({ desk, questionId, name, input, confirmAlways, mode, card, signal, terminal, notice });
+}
+
+export const OVERWRITE_TIMEOUT_MS = 250;
+/** Write only: does the path the Write tool would write already exist? undefined when it cannot tell,
+ *  including when resolving and stat take longer than `timeoutMs` (the terminal card must not wait). */
+export async function writeOverwrite(name, input, resolve, { timeoutMs = OVERWRITE_TIMEOUT_MS } = {}) {
+  if (name !== 'Write' || typeof input?.file_path !== 'string') return undefined;
+  const probe = (async () => {
+    let file;
+    try { file = await resolve(input.file_path, { create: true }); } catch { return undefined; }
+    try { await stat(file); return true; }
+    catch (error) { return error?.code === 'ENOENT' ? false : undefined; }
+  })();
+  let timer;
+  const late = new Promise(done => { timer = setTimeout(() => done(undefined), timeoutMs); timer.unref?.(); });
+  try { return await Promise.race([probe, late]); } finally { clearTimeout(timer); }
+}

package/src/remote-speech.mjs

@@ -0,0 +1,275 @@
+// Granito's voice, host side: the short phrases a paired device speaks, and their conversion to the
+// device's PCM format. Pure module: the only I/O is the one read of the contract.
+import { readFileSync } from 'node:fs';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { stripForDevice } from './remote-device-card.mjs';
+
+const SPEECH = JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json', import.meta.url), 'utf8')).speech;
+export const SPEECH_RATE = SPEECH.format.sample_rate;
+export const SPEECH_CHUNK_BYTES = SPEECH.format.chunk_max_bytes;
+export const SPEECH_MAX_BYTES = SPEECH_RATE * SPEECH.format.phrase_max_seconds;
+// About 6 s of the voice (Piper speaks ~14-16 characters a second): a longer sentence would be cut mid-word.
+export const TURN_PHRASE_CHARS = 90;
+const TOOL_NAME_CHARS = 40;
+const BASENAME_CHARS = 60;
+
+const chars = text => Array.from(text);
+const collapse = text => text.replace(/\s+/g, ' ').trim();
+
+/** Cut to `limit` code points, ending on a whole word when one fits. */
+function capWords(text, limit) {
+  const all = chars(text);
+  if (all.length <= limit) return text;
+  if (all[limit] === ' ') return all.slice(0, limit).join('').trimEnd();
+  const space = all.slice(0, limit).lastIndexOf(' ');
+  return all.slice(0, space > 0 ? space : limit).join('').trimEnd();
+}
+
+export function speakableToolName(name) {
+  let text = stripForDevice(name).replace(/^mcp__.+?__/, '');
+  text = collapse(text.replace(/_/g, ' '));
+  return capWords(text, TOOL_NAME_CHARS);
+}
+
+function fileLabel(path) {
+  if (typeof path !== 'string') return '';
+  const base = path.split(/[\\/]/).filter(Boolean).pop() ?? '';
+  return chars(collapse(stripForDevice(base))).slice(0, BASENAME_CHARS).join('').trim();
+}
+
+export function permissionPhrase({ name, input, terminalOnly = false }) {
+  let what;
+  if (name === 'Write' || name === 'Edit') {
+    what = 'escribir ' + ((!terminalOnly && fileLabel(input?.file_path)) || 'un archivo');
+  } else if (name === 'Bash') what = 'correr un comando';
+  else what = 'usar ' + (speakableToolName(name) || 'una herramienta');
+  return `Necesito tu permiso para ${what}.`;
+}
+
+/** The permission phrase as spoken: the file is named only where the device itself may show it (armed, not plan
+ *  mode, not confirm-always); otherwise the name never leaves the terminal. */
+export function permissionSpeech({ name, input, armed = false, plan = false, confirmAlways = false }) {
+  return permissionPhrase({ name, input, terminalOnly: armed !== true || plan === true || confirmAlways === true });
+}
+
+export function failurePhrase(name) {
+  return `Falló ${speakableToolName(name) || 'una herramienta'}.`;
+}
+
+const HTML_ONLY = /^\s*(?:<\/?[A-Za-z][^>]*>\s*)+$/;
+const BOX_DRAWING = /[─-╿]/;
+const URL_RE = /\b(?:https?|ftp):\/\/\S+|\bwww\.\S+/g;
+const WRAP = '()[\\]"\'«»,;:';
+const PATH_TOKEN = new RegExp(`^([${WRAP}]*)(.*?)([${WRAP}]*)$`, 'u');
+
+function withoutFences(text) {
+  const out = [];
+  let fence = null;
+  for (const line of text.split('\n')) {
+    const open = /^\s*(```|~~~)/.exec(line);
+    if (fence) { if (open && open[1] === fence) fence = null; continue; }
+    if (open) { fence = open[1]; continue; }
+    out.push(line);
+  }
+  return out;
+}
+
+function reducePath(token) {
+  const m = PATH_TOKEN.exec(token);
+  const [, pre, core, post] = m;
+  if (!core.includes('/') || /^(?:https?|ftp):/i.test(core) || /^www\./i.test(core)) return token;
+  const segments = core.split('/').filter(Boolean);
+  if (!segments.length) return token;
+  const last = segments[segments.length - 1];
+  const pathLike = /^(?:\/|~\/|\.\/|\.\.\/)/.test(core) || core.split('/').length - 1 >= 2 || last.includes('.');
+  return pathLike ? pre + last + post : token;
+}
+
+export function turnPhrase(text) {
+  let lines = withoutFences(String(text ?? '').replace(/\r\n?/g, '\n'))
+    .filter(l => !/^\s{0,3}#{1,6}\s/.test(l) && !/^\s*\|/.test(l) && !HTML_ONLY.test(l) && !BOX_DRAWING.test(l))
+    .map(l => l.replace(/^\s*(?:(?:[-*+]|\d+[.)]|>)\s+)+/, ''));
+  lines = lines.map(line => line
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/`([^`]*)`/g, (_, code) => (!/\s/.test(code) && chars(code).length <= 60 ? code : ''))
+    .replace(URL_RE, '')
+    .replace(/\*\*|__|~~/g, '')
+    .replace(/(^|[\s(])([*_])(\S[^*_]*?)\2(?=[\s).,;:!?]|$)/g, '$1$3')
+    .replace(/<\/?[A-Za-z][^>]*>/g, '')
+    .replace(/\p{Extended_Pictographic}|️/gu, ''))
+    .map(line => stripForDevice(line).replace(/[ \t]+/g, ' ').split(' ').map(reducePath).join(' '));
+  const first = lines.find(l => l.trim());
+  if (first === undefined) return null;
+  const sentence = /^(.*?[.!?…])(?=\s|$)/.exec(first.trim());
+  let out = collapse(sentence ? sentence[1] : first).replace(/^[:;,\-–— ]+/, '');
+  if (!out) return null;
+  const all = chars(out);
+  if (all.length > TURN_PHRASE_CHARS) {
+    const space = all.lastIndexOf(' ', TURN_PHRASE_CHARS - 1);
+    out = all.slice(0, space > 0 ? space : TURN_PHRASE_CHARS - 1).join('').trimEnd() + '…';
+  }
+  return out;
+}
+
+/** 16-bit little-endian PCM at `rate` Hz to the device's 8-bit unsigned mono at 11025 Hz. */
+export function toDevicePcm(pcm16le, rate) {
+  const samples = Math.floor(pcm16le.length / 2);
+  const ratio = rate / SPEECH_RATE;
+  const outLen = Math.min(Math.floor(samples / ratio), SPEECH_MAX_BYTES);
+  const out = Buffer.alloc(outLen);
+  for (let i = 0; i < outLen; i++) {
+    const start = Math.floor(i * ratio);
+    const end = Math.min(samples, Math.max(start + 1, Math.floor((i + 1) * ratio)));
+    let sum = 0;
+    for (let j = start; j < end; j++) sum += pcm16le.readInt16LE(j * 2);
+    out[i] = Math.min(255, Math.max(0, Math.round(sum / (end - start) / 256) + 128));
+  }
+  return out;
+}
+
+export function speechChunks(pcm8, max = SPEECH_CHUNK_BYTES) {
+  const out = [];
+  for (let at = 0; at < pcm8.length; at += max) out.push(pcm8.subarray(at, at + max));
+  return out;
+}
+
+export function speechFrames({ id, about, pcm8 }) {
+  const chunks = speechChunks(pcm8);
+  return chunks.map((chunk, index) => ({ kind: 'speech', id, seq: String(index), last: index === chunks.length - 1, about, audio: chunk.toString('base64') }));
+}
+
+export const PIPER_TIMEOUT_MS = 8000;
+const DEFAULT_VOICE_RATE = 22050;
+
+/** The sample rate Piper writes for `voice`, from its `.onnx.json`; 22050 when unreadable. */
+export function voiceRate(voice, { readFile = readFileSync } = {}) {
+  try {
+    const rate = JSON.parse(readFile(voice + '.json')).audio.sample_rate;
+    return Number.isInteger(rate) && rate >= 8000 && rate <= 48000 ? rate : DEFAULT_VOICE_RATE;
+  } catch { return DEFAULT_VOICE_RATE; }
+}
+
+/** Renders a phrase with a local Piper process. Never rejects; null means "no voice this time". */
+export class PiperSpeech {
+  #piper; #voice; #spawn; #readFile; #timeoutMs; #rate = null;
+
+  constructor({ piper = 'piper', voice = null, spawn = nodeSpawn, readFile = readFileSync, timeoutMs = PIPER_TIMEOUT_MS } = {}) {
+    this.#piper = piper; this.#voice = voice; this.#spawn = spawn; this.#readFile = readFile; this.#timeoutMs = timeoutMs;
+  }
+
+  get ready() { return typeof this.#voice === 'string' && this.#voice !== ''; }
+
+  async render(text, { signal } = {}) {
+    try {
+      const line = typeof text === 'string' ? collapse(text) : '';
+      if (!this.ready || !line || signal?.aborted) return null;
+      this.#rate ??= voiceRate(this.#voice, { readFile: this.#readFile });
+      return await this.#run(line, this.#rate, signal);
+    } catch { return null; }
+  }
+
+  #run(line, rate, signal) {
+    return new Promise(resolve => {
+      const cap = rate * 2 * 7;
+      const parts = [];
+      let size = 0, capped = false, timer = null, child = null, done = false;
+      const onAbort = () => { kill(); finish(null); };
+      const kill = () => { try { child?.kill('SIGKILL'); } catch { /* already gone */ } };
+      const finish = value => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        child?.stdout?.removeAllListeners('data');
+        child?.removeAllListeners('close');
+        child?.removeAllListeners('error');
+        resolve(value);
+      };
+      const pcm = () => {
+        const out = toDevicePcm(Buffer.concat(parts), rate);
+        return out.length ? out : null;
+      };
+      try {
+        child = this.#spawn(this.#piper, ['--model', this.#voice, '--output-raw'], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
+        child.stdin.on('error', () => {});
+        child.stdout.on('data', chunk => {
+          if (capped) return;
+          const room = cap - size;
+          if (chunk.length >= room) {
+            parts.push(chunk.subarray(0, room)); size = cap; capped = true;
+            kill();
+          } else { parts.push(chunk); size += chunk.length; }
+        });
+        child.on('error', () => finish(null));
+        child.on('close', code => finish(capped || code === 0 ? pcm() : null));
+        signal?.addEventListener('abort', onAbort, { once: true });
+        timer = setTimeout(() => { kill(); finish(null); }, this.#timeoutMs);
+        child.stdin.write(line + '\n');
+        child.stdin.end();
+      } catch { kill(); finish(null); }
+    });
+  }
+}
+
+export function speechFromEnv(env = process.env, deps = {}) {
+  const set = value => (typeof value === 'string' && value.trim() ? value.trim() : null);
+  return new PiperSpeech({ ...deps, piper: set(env.COMAL_PIPER) ?? 'piper', voice: set(env.COMAL_PIPER_VOICE) });
+}
+
+// Pacing of speech frames over the host socket. The relay allows a host socket 100 frames / 10 s and 16 pending, and
+// silently drops a speech frame past 70 frames in its window or 4 pending: one chunk every 300 ms at most, only once
+// deltas have been quiet for a second, below 70 frames in the last 10 s and with little left in the send buffer.
+export const SPEECH_CHUNK_INTERVAL_MS = 300;
+export const SPEECH_QUIET_AFTER_DELTA_MS = 1000;
+export const SPEECH_WINDOW_MS = 10000;
+export const SPEECH_WINDOW_CEILING = 70;
+export const SPEECH_MAX_BUFFERED = 16384;
+export const SPEECH_PHRASE_DEADLINE_MS = 15000;
+
+/** Plays one phrase at a time, a chunk per tick while `room()` says so. A newer phrase replaces the current one; a
+ *  failed send or a phrase older than its deadline is dropped, never retried. Never throws. */
+export class SpeechPacer {
+  #send; #room; #now; #intervalMs; #deadlineMs; #setTimer; #clearTimer;
+  #frames = null; #next = 0; #startedAt = 0; #timer = null;
+
+  constructor({ send, room, now = Date.now, intervalMs = SPEECH_CHUNK_INTERVAL_MS, deadlineMs = SPEECH_PHRASE_DEADLINE_MS, setTimer = setTimeout, clearTimer = clearTimeout }) {
+    this.#send = send; this.#room = room; this.#now = now; this.#intervalMs = intervalMs; this.#deadlineMs = deadlineMs;
+    this.#setTimer = setTimer; this.#clearTimer = clearTimer;
+  }
+
+  get busy() { return this.#frames !== null && this.#now() - this.#startedAt <= this.#deadlineMs; }
+
+  play({ frames }) {
+    this.cancel();
+    if (!Array.isArray(frames) || !frames.length) return;
+    this.#frames = frames; this.#next = 0; this.#startedAt = this.#now();
+    this.#schedule(0);
+  }
+
+  cancel() {
+    if (this.#timer !== null) { try { this.#clearTimer(this.#timer); } catch { /* gone */ } }
+    this.#timer = null; this.#frames = null; this.#next = 0;
+  }
+
+  #schedule(ms) {
+    try {
+      const timer = this.#setTimer(() => this.#tick(), ms);
+      timer?.unref?.();
+      this.#timer = timer;
+    } catch { this.cancel(); }
+  }
+
+  #tick() {
+    this.#timer = null;
+    if (!this.#frames) return;
+    try {
+      if (this.#now() - this.#startedAt > this.#deadlineMs) { this.cancel(); return; }
+      if (this.#room()) {
+        if (this.#send(this.#frames[this.#next]) === false) { this.cancel(); return; }
+        if (++this.#next >= this.#frames.length) { this.cancel(); return; }
+      }
+    } catch { this.cancel(); return; }
+    this.#schedule(this.#intervalMs);
+  }
+}

package/src/remote-stats.mjs

@@ -0,0 +1,205 @@
+// session.stats for /rc surfaces (browser and paired M5Stack): a bounded summary built from what
+// /status, /context and the status bar already compute. Pure module: numbers, enums and bounded
+// labels only — never paths, file names, tool arguments or the cwd.
+import { readFileSync } from 'node:fs';
+import { stripForDevice } from './remote-device-card.mjs';
+
+const CONTRACT = JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json', import.meta.url), 'utf8')).stats;
+export const STATS_SCHEMA = CONTRACT.schema;
+export const STATS_MAX_BYTES = CONTRACT.maxBytes;
+// A change publishes a durable session.stats at most once a minute (each one is a stored row against the session's
+// 10,000-event cap and the account's storage); a turn end and a device connecting publish at once (1 s floor).
+export const STATS_INTERVAL_MS = 60000;
+export const STATS_FLOOR_MS = 1000;
+
+const GROUPS = STATS_SCHEMA.properties;
+const limit = (group, field) => GROUPS[group].properties[field].maxLength;
+const MODES = GROUPS.permissions.properties.mode.enum;
+const TRANSPORTS = GROUPS.connection.properties.transport.enum;
+const EFFORT_LEVELS = GROUPS.model.properties.effort_levels.maxItems;
+const SOURCES = GROUPS.capabilities.properties.sources.maxProperties;
+const SOURCE_NAME = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+const count = value => Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const flag = value => typeof value === 'boolean' ? value : null;
+const cut = (text, max) => Array.from(text).slice(0, max).join('');
+/** A label as the device shows it: invisible characters out, one line, cut to the schema's length. */
+function label(value, max) {
+  if (typeof value !== 'string') return undefined;
+  const text = cut(stripForDevice(value).replace(/\s+/g, ' ').trim(), max).trim();
+  return text || undefined;
+}
+// A token is path-like when it holds a separator, starts at home, or names a file (word.ext).
+const PATHISH = /[\\/]|^~|^[A-Za-z]:/;
+const FILENAME = /\w\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+const MODEL_FILE = /\w\.(gguf|ggml|bin|safetensors|onnx|pt|pth|mlx|llamafile|json|ya?ml|toml)$/i;
+/** Free text (objective, task title) without the cwd, paths or file names: each such token becomes «…». */
+function redacted(value, cwd, max) {
+  if (typeof value !== 'string') return undefined;
+  let text = stripForDevice(value).replace(/\s+/g, ' ');
+  if (typeof cwd === 'string' && cwd.length > 1) text = text.split(cwd).join('…');
+  text = text.split(' ').map(token => {
+    const bare = token.replace(/^[("'«“‘[]+|[)"'»”’\],.;:!?]+$/g, '');
+    return bare && (PATHISH.test(bare) || FILENAME.test(bare)) ? token.replace(bare, '…') : token;
+  }).join(' ');
+  return label(text, max);
+}
+/** A model or profile name. Local providers name a weights or profile FILE: only its bare name is shown, never the
+ *  path (or the cwd) — `/home/x/models/qwen-7b.gguf` reads `qwen-7b`; an id that is no path stays whole. */
+function nameLabel(value, cwd, max) {
+  if (typeof value !== 'string') return undefined;
+  let text = stripForDevice(value).replace(/\s+/g, ' ').trim();
+  if (typeof cwd === 'string' && cwd.length > 1) text = text.split(cwd).join('');
+  text = text.split(' ').map(token => {
+    const path = PATHISH.test(token);
+    let name = path ? token.split(/[\\/]+/).filter(Boolean).at(-1) ?? '' : token;
+    if (/^~|^[A-Za-z]:$/.test(name)) name = '';
+    // The last segment of a path loses any extension; an id that is no path only a model file's (meta.llama3 stays).
+    return (path ? FILENAME.test(name) : MODEL_FILE.test(name)) ? name.replace(/\.[A-Za-z][A-Za-z0-9]{0,11}$/, '') : name;
+  }).filter(Boolean).join(' ');
+  return label(text, max);
+}
+const compact = group => {
+  for (const key of Object.keys(group)) if (group[key] === undefined) delete group[key];
+  return Object.keys(group).length ? group : undefined;
+};
+const tally = value => {
+  if (!value || typeof value !== 'object') return undefined;
+  return compact({ input: count(value.input), output: count(value.output), cached: count(value.cached) });
+};
+
+/**
+ * Sources (each optional; a missing source omits its group or field):
+ * metadata (cli metadata()), promptCaching, contextStatus / contextPlan (compactor status/plan as
+ * /context computes them), messages {active, original}, lastCompaction (context_projection row),
+ * usage {last, session, calls, call_limit}, timing (result.timing), work (projectRemoteWorkspace),
+ * permissions {armed, until ms} (RemoteHost status().permission_answers), transport, addDirCount, cwd.
+ */
+export function buildSessionStats({ metadata, promptCaching, contextStatus, contextPlan, messages, lastCompaction, usage, timing, work, permissions, transport, addDirCount, cwd } = {}) {
+  const stats = {};
+  if (metadata && typeof metadata === 'object') {
+    const levels = metadata.modelCapabilities?.effort?.levels;
+    stats.model = compact({
+      provider: label(metadata.provider, limit('model', 'provider')),
+      profile: nameLabel(metadata.profile, cwd, limit('model', 'profile')),
+      model: nameLabel(metadata.model, cwd, limit('model', 'model')),
+      effort: label(metadata.effort, limit('model', 'effort')),
+      effort_levels: Array.isArray(levels) ? levels.map(level => label(level, GROUPS.model.properties.effort_levels.items.maxLength)).filter(Boolean).slice(0, EFFORT_LEVELS) : undefined,
+    });
+  }
+  const reported = metadata?.modelCapabilities?.capabilities;
+  if ((reported && typeof reported === 'object') || typeof promptCaching === 'boolean') {
+    const provenance = metadata?.modelCapabilities?.provenance || {}, sources = {};
+    const capabilities = {};
+    if (reported && typeof reported === 'object') for (const name of ['tools', 'vision', 'thinking']) {
+      capabilities[name] = flag(reported[name]);
+      const source = provenance[name]?.source;
+      if (typeof source === 'string' && SOURCE_NAME.test(source)) sources[name] = source;
+    }
+    capabilities.cache = typeof promptCaching === 'boolean' ? promptCaching : null;
+    if (typeof promptCaching === 'boolean') sources.cache = 'provider';
+    if (Object.keys(sources).length) capabilities.sources = Object.fromEntries(Object.entries(sources).slice(0, SOURCES));
+    stats.capabilities = capabilities;
+  }
+  {
+    const until = Number(permissions?.until);
+    const group = compact({
+      mode: MODES.includes(metadata?.mode) ? metadata.mode : undefined,
+      device_armed: typeof permissions?.armed === 'boolean' ? permissions.armed : undefined,
+      device_until: permissions ? (permissions.armed && Number.isFinite(until) && until > 0 ? Math.floor(until / 1000) : null) : undefined,
+      add_dirs: count(addDirCount),
+    });
+    if (group) stats.permissions = group;
+  }
+  if (contextStatus || contextPlan || messages || lastCompaction) {
+    const status = contextStatus || {}, plan = contextPlan || status;
+    const percent = typeof status.percent === 'number' && Number.isFinite(status.percent) ? Math.min(100, Math.max(0, status.percent)) : undefined;
+    const at = Date.parse(lastCompaction?.timestamp ?? lastCompaction?.at ?? '');
+    const group = compact({
+      input_tokens: count(status.input_tokens), window: count(status.context_window), output_reserve: count(status.output_reserve), percent,
+      compaction_window: count(plan.compaction_window), soft_threshold: count(plan.soft_threshold), hard_threshold: count(plan.hard_threshold),
+      last_compaction: lastCompaction ? compact({
+        at: Number.isFinite(at) && at >= 0 ? Math.floor(at / 1000) : undefined,
+        trigger: label(lastCompaction.compaction_trigger ?? lastCompaction.trigger, GROUPS.context.properties.last_compaction.properties.trigger.maxLength),
+        before: count(lastCompaction.before_tokens), after: count(lastCompaction.after_tokens),
+      }) ?? null : undefined,
+      messages_active: count(messages?.active), messages_original: count(messages?.original),
+    });
+    if (group) stats.context = group;
+  }
+  if (usage && typeof usage === 'object') {
+    const group = compact({ last: tally(usage.last), session: tally(usage.session), calls: count(usage.calls), call_limit: count(usage.call_limit) });
+    if (group) stats.usage = group;
+  }
+  if (timing && typeof timing === 'object') {
+    const group = compact({ comal_ms: count(timing.comal_ms), reasoning_ms: count(timing.reasoning_ms), first_response_ms: count(timing.first_output_ms ?? timing.first_text_ms), tools_ms: count(timing.tools_ms), human_wait_ms: count(timing.human_wait_ms) });
+    if (group) stats.timing = group;
+  }
+  if (work && typeof work === 'object' && (work.plan || work.tasks_total)) {
+    const tasks = Array.isArray(work.tasks) ? work.tasks : [], checks = tasks.flatMap(task => Array.isArray(task?.checks) ? task.checks : []);
+    const current = tasks.find(task => task?.status === 'in_progress');
+    const group = compact({
+      objective: redacted(work.plan?.objective, cwd, limit('work', 'objective')),
+      done: count(work.counts?.done), total: count(work.tasks_total),
+      current_task: current ? redacted(current.title, cwd, limit('work', 'current_task')) ?? null : null,
+      checks_passing: checks.filter(check => check?.status === 'passed').length,
+      checks_failing: checks.filter(check => ['failed', 'refused', 'interrupted', 'not_dispatched'].includes(check?.status)).length,
+    });
+    if (group) stats.work = group;
+  }
+  if (TRANSPORTS.includes(transport)) stats.connection = { transport, host_online: transport !== 'disconnected' };
+  for (const key of Object.keys(stats)) if (stats[key] === undefined) delete stats[key];
+  return fitStats(stats) ?? {};
+}
+
+// What goes first when a summary does not fit: free text, then timing, then the rest that is not essential.
+const DROPS = [
+  stats => { delete stats.work?.objective; },
+  stats => { delete stats.work?.current_task; },
+  stats => { delete stats.timing; },
+  stats => { delete stats.capabilities?.sources; },
+  stats => { delete stats.model?.effort_levels; },
+  stats => { delete stats.work; },
+  stats => { delete stats.usage; },
+];
+/** The summary itself when it fits in `max` bytes; otherwise a copy with optional parts dropped; null if nothing fits. */
+export function fitStats(stats, max = STATS_MAX_BYTES) {
+  if (!stats || typeof stats !== 'object') return null;
+  const size = value => Buffer.byteLength(JSON.stringify(value));
+  if (size(stats) <= max) return stats;
+  const copy = structuredClone(stats);
+  for (const drop of DROPS) {
+    drop(copy);
+    for (const key of Object.keys(copy)) if (copy[key] && typeof copy[key] === 'object' && !Object.keys(copy[key]).length) delete copy[key];
+    if (size(copy) <= max) return copy;
+  }
+  return null;
+}
+
+/** Context numbers exactly as /context computes them (same compactor calls). */
+export function readContext({ compactor, system, tools, maxTokens, session }) {
+  const contextStatus = compactor.status({ system, messages: session.messages, tools }, maxTokens);
+  const contextPlan = compactor.plan(contextStatus.output_reserve, contextStatus.overhead_tokens);
+  return { contextStatus, contextPlan, messages: { active: session.messages.length, original: session.historyMessages.length } };
+}
+
+const tokens = usage => ({ input: count(usage?.input_tokens) ?? 0, output: count(usage?.output_tokens) ?? 0 });
+const cacheRead = row => count(row?.usage_accounting?.cache_read_tokens) ?? 0;
+/** Usage, last timing and last compaction from the session book. Session totals count what the status
+ *  bar counts (results not already including subagents, and failed requests with usage). */
+export function statsFromRows(rows = []) {
+  const counted = rows.filter(row => (row.type === 'result' && !row.usage_includes_subagents) || (row.type === 'error' && row.usage));
+  const turns = rows.filter(row => row.type === 'result' && !row.usage_includes_subagents && row.usage && row.turns > 0);
+  const last = turns.at(-1), reads = rows.filter(row => row.type === 'model_usage');
+  const session = counted.reduce((sum, row) => { const n = tokens(row.usage); return { input: sum.input + n.input, output: sum.output + n.output }; }, { input: 0, output: 0 });
+  const usage = counted.length || reads.length ? {
+    ...(last ? { last: { ...tokens(last.usage), cached: last.turn_id ? reads.filter(row => row.turn_id === last.turn_id).reduce((n, row) => n + cacheRead(row), 0) : 0 } } : {}),
+    session: { ...session, cached: reads.reduce((n, row) => n + cacheRead(row), 0) },
+    ...(last ? { calls: last.turns } : {}),
+  } : null;
+  return {
+    usage,
+    timing: rows.findLast(row => row.type === 'result' && row.timing && typeof row.timing === 'object')?.timing ?? null,
+    lastCompaction: rows.findLast(row => row.type === 'context_projection') ?? null,
+  };
+}