@milpa/comal 0.2.3 → 0.2.4

package/src/remote-device-card.mjs

@@ -0,0 +1,111 @@
+// Permission card for the paired M5Stack: what Comal wants to run, trimmed and sanitized so the
+// person sees what they approve. Pure module; the host wires it where the permission is armed.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { digest } from './operations.mjs';
+
+const CARD = JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json', import.meta.url), 'utf8')).card;
+const MAX_BYTES = CARD.maxBytes;
+const MAX_LINES = CARD.schema.properties.lines.maxItems;
+const LINE_CHARS = CARD.schema.properties.lines.items.maxLength;
+const TOOL_CHARS = CARD.schema.properties.tool.maxLength;
+const BASH_CHARS = 600;
+const BODY_LINES = 12;
+const SUMMARY_TITLE = 'Resumen declarado por la operación';
+
+// Same set as the terminal card (src/tui/present.mjs INVISIBLE): controls, bidi and format
+// characters. The terminal escapes them; the device strips them (tab and newline handled apart).
+const INVISIBLE = /[\x00-\x08\x0b-\x1f\x7f-\x9f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g;
+export const stripForDevice = text => String(text ?? '').replace(/\t/g, '  ').replace(INVISIBLE, '');
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+const cpLength = text => Array.from(text).length;
+
+/** Pieces of at most `limit` code points; a grapheme cluster is kept whole when it fits. */
+function pieces(text, limit) {
+  const out = [];
+  let current = '', used = 0;
+  const push = (part, size) => {
+    if (used + size > limit) { out.push(current); current = ''; used = 0; }
+    current += part; used += size;
+  };
+  for (const { segment } of segmenter.segment(text)) {
+    const size = cpLength(segment);
+    if (size <= limit) push(segment, size);
+    else for (const point of Array.from(segment)) push(point, 1);
+  }
+  if (current || !out.length) out.push(current);
+  return out;
+}
+/** First `limit` code points, ending on a grapheme boundary. */
+function cut(text, limit) {
+  let used = 0, out = '';
+  for (const { segment } of segmenter.segment(text)) {
+    const size = cpLength(segment);
+    if (used + size > limit) return { text: out, cut: true };
+    out += segment; used += size;
+  }
+  return { text: out, cut: false };
+}
+// Characters removed by the strip are reported (state.stripped) so the card says it is not the raw text.
+const strip = (text, state) => { const raw = String(text ?? ''); const clean = stripForDevice(raw); if (raw.replace(INVISIBLE, '') !== raw) state.stripped = true; return clean; };
+const oneLine = (text, state) => strip(text, state).replace(/\n/g, ' ');
+const countLines = text => text === '' ? 0 : text.split('\n').length;
+
+function wrapped(text, maxChars, maxLines) {
+  const head = cut(text, maxChars);
+  const lines = head.text.split('\n').flatMap(line => pieces(line, LINE_CHARS));
+  return { lines: lines.slice(0, maxLines), truncated: head.cut || lines.length > maxLines };
+}
+/** Header line plus up to BODY_LINES prefixed lines, each cut to one device line. */
+function headed(header, body) {
+  const lines = [], flags = [];
+  const head = cut(header, LINE_CHARS); lines.push(head.text); flags.push(head.cut);
+  for (const [prefix, text] of body.slice(0, BODY_LINES)) {
+    const line = cut(prefix + text, LINE_CHARS); lines.push(line.text); flags.push(line.cut);
+  }
+  return { lines, truncated: flags.some(Boolean) || body.length > BODY_LINES };
+}
+const plainObject = value => value && typeof value === 'object' && !Array.isArray(value);
+
+function render({ tool, input, summary, overwrite }, state) {
+  if (typeof summary === 'string' && summary.trim()) {
+    const body = wrapped(strip(summary.trim(), state), BASH_CHARS, MAX_LINES - 1);
+    return { kind: 'summary', lines: [SUMMARY_TITLE, ...body.lines], truncated: body.truncated };
+  }
+  if (plainObject(input) && tool === 'Bash' && typeof input.command === 'string') return { kind: 'bash', ...wrapped(strip(input.command, state), BASH_CHARS, MAX_LINES) };
+  if (plainObject(input) && tool === 'Write' && typeof input.content === 'string') {
+    const content = strip(input.content, state);
+    const path = oneLine(input.file_path ?? '', state);
+    const body = (content === '' ? [] : content.split('\n')).map(line => ['', line]);
+    return { kind: 'write', ...headed(`${path} · ${overwrite === true ? 'reemplaza' : overwrite === false ? 'nueva' : '?'} · ${countLines(content)} líneas`, body) };
+  }
+  if (plainObject(input) && tool === 'Edit' && typeof input.old_string === 'string' && typeof input.new_string === 'string') {
+    const removed = strip(input.old_string, state), added = strip(input.new_string, state);
+    const body = [...(removed === '' ? [] : removed.split('\n')).map(line => ['- ', line]), ...(added === '' ? [] : added.split('\n')).map(line => ['+ ', line])];
+    return { kind: 'edit', ...headed(`${oneLine(input.file_path ?? '', state)} · +${countLines(added)} −${countLines(removed)}${input.replace_all === true ? ' · todas' : ''}`, body) };
+  }
+  return { kind: 'terminal', lines: [], truncated: true };
+}
+
+export function buildDeviceCard({ questionId, name, input, summary, overwrite, terminalOnly = false } = {}) {
+  // Only the exact built-in names render natively: a namespaced tool (mcp__x__Bash) is never a bash card.
+  // terminalOnly: a card the device may not answer (confirm:'always', plan mode) says only the tool name.
+  const state = { stripped: false };
+  const tool = String(name ?? '');
+  const rendered = terminalOnly ? { kind: 'terminal', lines: [], truncated: true } : render({ tool, input, summary, overwrite }, state);
+  const toolName = cut(strip(tool, state), TOOL_CHARS);
+  const card = {
+    question_id: questionId,
+    card_digest: createHash('sha256').update(JSON.stringify(['device-card/1', name, digest(input)])).digest('hex'),
+    tool: toolName.text,
+    kind: rendered.kind,
+    lines: rendered.lines,
+    truncated: rendered.truncated || toolName.cut || state.stripped,
+  };
+  if (rendered.kind === 'write' && typeof overwrite === 'boolean') card.overwrite = overwrite;
+  const size = () => Buffer.byteLength(JSON.stringify(card));
+  while (size() > MAX_BYTES && card.lines.length > 1) { card.lines.pop(); card.truncated = true; }
+  if (size() > MAX_BYTES) { card.kind = 'terminal'; card.lines = []; card.truncated = true; delete card.overwrite; }
+  return card;
+}

package/src/remote-device.mjs

@@ -0,0 +1,92 @@
+import { t as translate, registerMessages } from './i18n/index.mjs';
+import { isCameraPath } from './qr-scan.mjs';
+
+registerMessages({
+  'Scanning the pairing QR needs an interactive terminal; type the code instead: /rc device CODE.': 'Escanear el QR de emparejamiento necesita una terminal interactiva; escribe el código: /rc device CODE.',
+  'Not paired; nothing was sent.': 'No se emparejó; no se envió nada.',
+  'Scanning the M5Stack pairing QR': 'Escaneando el QR de emparejamiento del M5Stack',
+  'Bring the M5Stack 10-20 cm from the camera, so the QR fills about a third of the picture. Up to 30 s; Esc cancels. Frames stay on this machine and are deleted at once.': 'Acerca el M5Stack a 10-20 cm de la cámara, que el QR ocupe un tercio de la imagen. Hasta 30 s; Esc cancela. Las imágenes se quedan en esta máquina y se borran al instante.',
+  'Pair this M5Stack?': '¿Emparejar este M5Stack?',
+  'The camera read the code {code}. Pair only if it is the code on the M5Stack\'s screen.': 'La cámara leyó el código {code}. Empareja sólo si es el código de la pantalla del M5Stack.',
+  'Pair {code}': 'Emparejar {code}',
+  'Do not pair': 'No emparejar',
+});
+
+// Forward the House's permission rows to the Remote Control projection.
+// Only the current session's waits and answers cross; subagent sessions stay local.
+const FORWARDED = new Set(['house_waiting', 'house_answered']);
+
+export function forwardHouseRow(row, { sessionId, remoteHost } = {}) {
+  if (!row || !FORWARDED.has(row.type) || row.session_id !== sessionId) return;
+  remoteHost?.observe(row);
+}
+
+/** /rc device [CODE|forget|scan [/dev/videoN]] → {kind:'status'|'forget'|'pair'|'scan', code?, camera?} or null when
+ * it is not that command. A scan camera that is not /dev/videoN throws. */
+export function parseRcDevice(action) {
+  const match = /^device(?:\s+(\S.*))?$/i.exec(String(action ?? '').trim());
+  if (!match) return null;
+  const arg = (match[1] || '').trim();
+  if (!arg) return { kind: 'status' };
+  if (arg.toLowerCase() === 'forget') return { kind: 'forget' };
+  const scan = /^scan(?:\s+(.+))?$/i.exec(arg);
+  if (scan) {
+    if (!scan[1]) return { kind: 'scan' };
+    const camera = scan[1].trim();
+    if (!isCameraPath(camera)) throw Error(translate('The camera must be a /dev/videoN device.'));
+    return { kind: 'scan', camera };
+  }
+  return { kind: 'pair', code: arg };
+}
+
+/** Runs a parsed /rc device command against the host; `t` translates. */
+export async function runRcDevice(parsed, host, t, { record } = {}) {
+  if (!host || host.stopped || !host.deviceAvailable()) throw Error(t('Open /rc first, with a Comal backend that supports devices.'));
+  if (parsed.kind === 'status') {
+    const device = host.status().device;
+    return device ? t('Device: {label} ({id}){connected}.', { label: device.label, id: device.id, connected: device.connected_at ? t(', connected {time}', { time: String(device.connected_at) }) : '' }) : t('No device paired.');
+  }
+  if (parsed.kind === 'forget') { const wasArmed = host.permissionsArmed(); await host.forgetDevice(); if (wasArmed) await record?.(ARM_ROW(false, 0)); return t('Device removed; its permission answers are off.'); }
+  const paired = await host.pairDevice(parsed.code);
+  return t('Device paired: {label} ({id}).', { label: paired.label, id: paired.device_id });
+}
+
+/** /rc device scan: the camera reads the device's pairing QR (only now, at most 30 s), the person confirms the code,
+ * and it pairs through runRcDevice's own path. `scan({camera})` → {code, camera}; `confirm({code, camera})` → boolean,
+ * absent without an interactive terminal (then it is refused before the camera turns on). */
+export async function runRcDeviceScan(parsed, host, t, { scan, confirm, record } = {}) {
+  if (typeof confirm !== 'function') throw Error(t('Scanning the pairing QR needs an interactive terminal; type the code instead: /rc device CODE.'));
+  if (!host || host.stopped || !host.deviceAvailable()) throw Error(t('Open /rc first, with a Comal backend that supports devices.'));
+  const found = await scan({ camera: parsed.camera });
+  if (!await confirm({ code: found.code, camera: found.camera })) return t('Not paired; nothing was sent.');
+  return runRcDevice({ kind: 'pair', code: found.code }, host, t, { record });
+}
+
+/** The yes/no card for a scanned code: "Do not pair" comes first and is highlighted, so Enter never pairs. */
+export function deviceCodeChoice(code, t) {
+  return { title: t('Pair this M5Stack?'), description: t('The camera read the code {code}. Pair only if it is the code on the M5Stack\'s screen.', { code }), items: [{ id: 'cancel', label: t('Do not pair') }, { id: 'pair', label: t('Pair {code}', { code }) }], selected: 'cancel' };
+}
+
+const ARM_ROW = (armed, until) => ({ type: 'remote_control', action: 'permissions.arm', armed, until: armed ? new Date(until).toISOString() : null });
+const clock = ms => new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', hour12: false });
+
+/** /rc permissions [on [N m|min|h]|off] → {kind:'status'|'off'|'on', ms} or null when it is not that command. */
+export function parseRcPermissions(action) {
+  const match = /^permissions(?:\s+(?:(off)|(on)(?:\s+(\d+(?:[.,]\d+)?)\s*(m|min|h)?)?))?$/i.exec(String(action ?? '').trim());
+  if (!match) return null;
+  if (match[1]) return { kind: 'off' };
+  if (!match[2]) return { kind: 'status' };
+  if (!match[3]) return { kind: 'on', ms: null };
+  return { kind: 'on', ms: Math.round(Number(match[3].replace(',', '.')) * (String(match[4] || 'm').toLowerCase() === 'h' ? 3600e3 : 60e3)) };
+}
+
+/** Runs a parsed /rc permissions command; `record(row)` appends the book row. */
+export async function runRcPermissions(parsed, host, t, { record } = {}) {
+  if (!host || host.stopped || !host.deviceAvailable()) throw Error(t('Open /rc first, with a Comal backend that supports devices.'));
+  const status = () => host.permissionsArmed() ? t('Permission answers from the M5Stack: armed until {time}.', { time: clock(host.permissionUntil) }) : t('Permission answers from the M5Stack: off.');
+  if (parsed.kind === 'status') return status();
+  if (parsed.kind === 'off') { host.disarmPermissions(); await record?.(ARM_ROW(false, 0)); return status(); }
+  const until = host.armPermissions(parsed.ms ?? undefined);
+  await record?.(ARM_ROW(true, until));
+  return t('M5Stack permission answers are armed until {time}. Each card\'s command or path goes through comal.milpahq.com to the device and is not stored.', { time: clock(until) });
+}

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

package/src/tui/discovery.mjs

@@ -6,7 +6,7 @@ import { graphemes, safeText } from './text.mjs';
 
 const COMMANDS = [
   ['cloud', '[login|status|logout]', 'Connect your Comal account for Artifacts and Remote Control'],
-  ['remote-control', '[start|status|stop|relay on|off]', 'Open this local session on the web'], ['rc', '[start|status|stop|relay on|off]', 'Remote Control shortcut'],
+  ['remote-control', '[start|status|stop|relay on|off|device CODE|scan|forget|permissions on|off]', 'Open this local session on the web'], ['rc', '[start|status|stop|relay on|off|device CODE|scan|forget|permissions on|off]', 'Remote Control shortcut'],
   ['help', '', "Help and keyboard"], ['status', '', "Session, provider and budget"],
   ['tools', '', "Tools available at this time"], ['house', '', "Receipts and interrupted operations"],
   ['operations', '', "Contracts and effects of operations"], ['sessions', '', "Open the session selector"],
@@ -122,9 +122,15 @@ export function commandCatalog(context = {}) {
 
 function argumentItems(command, args, context) {
   const first = args[0] || '', position = args.length - 1;
-  if (position === 1 && (command === 'rc' || command === 'remote-control') && first === 'relay') return named(['on', 'off'], 'on [30m|2h|8h] arms in memory for this /rc session; off disarms');
+  if (command === 'rc' || command === 'remote-control') {
+    const durations = () => named(['30m', '2h', '8h'], 'How long the arm lasts (30 min by default, 8 h at most)');
+    if (position === 1 && first === 'relay') return named(['on', 'off'], 'on [30m|2h|8h] arms in memory for this /rc session; off disarms');
+    if (position === 1 && first === 'device') return [...named(['scan'], 'Read the pairing QR with the camera (at most 30 s); you confirm the code'), ...named(['forget'], 'Unpair the M5Stack')];
+    if (position === 1 && first === 'permissions') return named(['on', 'off'], 'on [30m|2h|8h] lets the paired M5Stack allow once or deny; off disarms');
+    if (position === 2 && (first === 'relay' || first === 'permissions') && args[1] === 'on') return durations();
+  }
   if (position === 0) {
-    if (command === 'rc' || command === 'remote-control')return [...named(['start','status','stop'],'Remote session projection; local tools and permissions'), ...named(['relay'], 'Answers to /relay cards from the browser (off by default)')];
+    if (command === 'rc' || command === 'remote-control')return [...named(['start','status','stop'],'Remote session projection; local tools and permissions'), ...named(['relay'], 'Answers to /relay cards from the browser (off by default)'), ...named(['device'], 'Pair an M5Stack: type its CODE, or scan its QR'), ...named(['permissions'], 'Let the paired M5Stack answer permission cards (off by default)')];
     if (command === 'cloud') return named(['login','status','logout'],'Comal account; separate from the model provider');
     if (command === 'permissions') return context.mode === BYPASS_PERMISSION_MODE ? [] : [...named(['default', 'plan', 'acceptEdits', 'auto'], t("Permissions mode; does not change the model")), ...named(['allow', 'ask', 'deny', 'remove'], t("Saved permission rule; deny wins"))];
     if (command === 'autonomy') return context.mode === BYPASS_PERMISSION_MODE ? [] : named(languageInfo().language === 'es' ? ['observar', 'asistir', 'editar', 'autonomo'] : ['observe', 'assist', 'edit', 'autonomous'], t("Autonomy level; never enables the startup bypass"));