@milpa/comal 0.2.1 → 0.2.3

package/src/tui/swarm-panel.mjs

@@ -0,0 +1,217 @@
+import { t } from '../i18n/index.mjs';
+import { tone, safeText, wrap, clip } from './text.mjs';
+
+// Panel /swarm (fase 4 de open-relay): presentación pura, como el tablero F3. Entra una
+// foto (la que el plugin publica con ctx.provide y el host copia) y salen líneas. Todo
+// texto que viene de relayd o de los agentes es NO confiable: se vuelve a limpiar aquí
+// (escapes de terminal, controles, bidi), se acota y nunca se interpreta. El panel no
+// ejecuta nada: para actuar prepara un pedido en el composer que el humano envía, y las
+// acciones (Reply, Decide, ApprovePlan, RejectPlan) siguen en sus tarjetas confirmadas.
+const BIDI = /[​-‏‪-‮⁦-⁩]/g;
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,199}$/;
+const LIMITS = Object.freeze({ swarms: 16, tasks: 80, roles: 40, pending: 30, plans: 20 });
+const text = (value, limit = 200) => { const clean = safeText(value).replace(BIDI, '').replace(/\s+/g, ' ').trim(); const chars = [...clean]; return chars.length > limit ? chars.slice(0, limit).join('') + '…' : clean; };
+const id = value => { const clean = text(value, 200); return ID.test(clean) ? clean : null; };
+const count = value => { const number = Number(value); return Number.isFinite(number) && number >= 0 ? Math.floor(number) : 0; };
+const time = value => { const number = Number(value); return Number.isFinite(number) && number > 0 ? number : null; };
+const list = (value, limit) => Array.isArray(value) ? value.slice(0, limit) : [];
+
+/** Limpia y acota una foto del host. Lo que no es válido se descarta, no se pinta. */
+export function normalizeSwarmView(view) {
+  if (!view || typeof view !== 'object') return null;
+  if (view.available !== true) return { available: false, reason: text(view.reason || 'unknown', 40), error: view.error ? text(view.error, 600) : null };
+  const c = view.connection && typeof view.connection === 'object' ? view.connection : {};
+  const connection = {
+    notify: c.notify === 'off' ? 'off' : 'on', mode: c.notify === 'off' ? 'off' : ['cards', 'wake'].includes(c.mode) ? c.mode : 'on', state: text(c.state || 'idle', 30), cursor: c.cursor == null ? null : text(c.cursor, 24),
+    events_seen: count(c.events_seen), reconnects: count(c.reconnects),
+    last_event: c.last_event ? { seq: text(c.last_event.seq, 24), type: text(c.last_event.type, 60) } : null,
+    last_error: c.last_error ? { code: text(c.last_error.code, 60), message: text(c.last_error.message, 400) } : null,
+    delegate: c.delegate ? { principal: text(c.delegate.principal, 80), client: text(c.delegate.client, 40), caps: list(c.delegate.caps, 12).map(cap => text(cap, 30)) } : null,
+    missing_caps: list(c.missing_caps, 8).map(cap => text(cap, 30)), issue_command: c.issue_command ? text(c.issue_command, 600) : null,
+  };
+  const swarms = list(view.swarms, LIMITS.swarms).map(swarm => ({
+    id: id(swarm?.id) || '?', objective: swarm?.objective ? text(swarm.objective, 300) : null, root_team: swarm?.root_team ? text(swarm.root_team, 120) : null, truncated: swarm?.truncated === true,
+    tasks: list(swarm?.tasks, LIMITS.tasks).map(task => ({ id: id(task?.id) || '?', title: task?.title ? text(task.title, 160) : null, state: text(task?.state || '?', 40), team: text(task?.team || '', 120), role: text(task?.role || '', 120), role_name: task?.role_name ? text(task.role_name, 60) : null, attempts_used: count(task?.attempts_used), counted_attempts: count(task?.counted_attempts ?? task?.attempts_used), max_attempts: count(task?.max_attempts), since: time(task?.since), since_exact: task?.since_exact === true, infra_exhausted: task?.infra_exhausted === true, wake_cap: task?.wake_cap === true, review_rounds: count(task?.review_rounds), review_kind: ['task', 'integration', 'final'].includes(task?.review_kind) ? task.review_kind : null })),
+    roles: list(swarm?.roles, LIMITS.roles).map(role => ({ id: text(role?.id || '?', 120), name: text(role?.name || role?.id || '?', 60), team: text(role?.team || '', 120), occupied: role?.occupied === true, model: role?.model ? text(role.model, 60) : null })),
+    pending: list(swarm?.pending, LIMITS.pending).map(item => ({ delivery_id: text(item?.delivery_id || '', 200), message_id: id(item?.message_id), kind: text(item?.kind || 'message', 30), from: text(item?.from || '?', 120), sent_at: time(item?.sent_at), excerpt: item?.excerpt ? text(item.excerpt, 240) : null, task: id(item?.task), decision: item?.decision ? { question: text(item.decision.question, 200), options: list(item.decision.options, 4).map(option => text(option, 120)), recommended: item.decision.recommended ? text(item.decision.recommended, 120) : null } : null })),
+    // Revisor (open-relay F7): estado de los criterios de éxito del swarm (criteria.get).
+    criteria: swarm?.criteria && typeof swarm.criteria === 'object' ? { status: text(swarm.criteria.status || 'none', 20), version: count(swarm.criteria.version), digest: /^[a-f0-9]{64}$/.test(String(swarm.criteria.digest || '')) ? swarm.criteria.digest : null, rounds: count(swarm.criteria.rounds), renegotiating: Boolean(swarm.criteria.renegotiating), in_force: count(swarm.criteria.in_force) } : null,
+    plans: list(swarm?.plans, LIMITS.plans).map(plan => ({ proposal_id: id(plan?.proposal_id), proposer_role: text(plan?.proposer_role || '?', 120), parent_task: id(plan?.parent_task), summary: plan?.summary ? text(plan.summary, 240) : null, proposed_at: time(plan?.proposed_at), tasks: count(plan?.tasks), roles: count(plan?.roles) })),
+  }));
+  return { available: true, connection, swarms, swarms_total: count(view.swarms_total) || swarms.length, updated_at: time(view.updated_at), generated_at: time(view.generated_at) };
+}
+
+/** Columnas del kanban, en orden. Los estados de relayd caen en una; lo desconocido, en «otros». */
+export const SWARM_COLUMNS = Object.freeze(['pending', 'running', 'verifying', 'reviewing', 'blocked', 'done', 'closed', 'other']);
+export function swarmColumn(state) {
+  if (['draft', 'ready'].includes(state)) return 'pending';
+  if (['assigned', 'in_progress'].includes(state)) return 'running';
+  if (state === 'verifying') return 'verifying';
+  // Revisor (open-relay F4–F6): con los checks en verde, esperando el veredicto del revisor.
+  if (state === 'reviewing') return 'reviewing';
+  if (state === 'needs_attention' || String(state).startsWith('blocked')) return 'blocked';
+  if (state === 'done') return 'done';
+  if (['failed', 'cancelled'].includes(state)) return 'closed';
+  return 'other';
+}
+// Intentos que cuentan contra el máximo (counted_attempts de relayd); los excusados por
+// infraestructura o reabiertos tras despertar (attempts_used de más) sólo como nota.
+const attemptsLabel = task => {
+  const excused = task.attempts_used - task.counted_attempts;
+  return excused > 0 ? t('{used}/{max} attempts (+{excused} excused)', { used: task.counted_attempts, max: task.max_attempts, excused }) : t('{used}/{max} attempts', { used: task.counted_attempts, max: task.max_attempts });
+};
+const columnLabel = column => ({ pending: t('PENDING'), running: t('IN PROGRESS'), verifying: t('VERIFYING'), reviewing: t('IN REVIEW'), blocked: t('BLOCKED'), done: t('DONE'), closed: t('FAILED · CANCELLED'), other: t('OTHER') })[column];
+export const blockLabel = state => {
+  if (state === 'needs_attention') return t('needs attention');
+  const cause = String(state).split(':')[1];
+  return { question: t('waiting for your answer'), approval: t('waiting for approval'), dependency: t('waiting for a dependency'), capacity: t('no free role'), budget: t('budget exhausted'), children: t('waiting for subtasks'), config: t('dispatch configuration'), environment: t('environment'), criteria: t('waiting for the success criteria'), review: t('the reviewer is correcting it') }[cause] || cause || '';
+};
+export function formatAge(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return '';
+  const s = Math.floor(ms / 1000); if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60); if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60); if (h < 48) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/** Lo pendiente para el humano en un swarm, con el pedido que prepara Enter. Sin ids válidos no hay pedido. */
+export function swarmActions(view, index = 0) {
+  const swarm = view?.available ? view.swarms[index] : null; if (!swarm) return [];
+  const items = [];
+  for (const item of swarm.pending) {
+    if (!item.message_id) continue;
+    const question = item.kind === 'question', structured = Boolean(item.decision);
+    items.push({ kind: structured ? 'decision' : question ? 'question' : 'message', id: item.message_id, item,
+      hint: structured ? t('Dossier, then Decide: you choose the option and confirm the card') : question ? t('Dossier, then Reply: you confirm the card') : t('Message, then Reply or Ack'),
+      request: structured ? t('Open the decision dossier for the open-relay structured question {id} (plugin__open-relay__Dossier {"message_id":"{id}"}) and present it to me with its options. I will choose the option myself; then propose Decide so I can confirm it on the card.', { id: item.message_id })
+        : question ? t('Open the decision dossier for the open-relay question {id} (plugin__open-relay__Dossier {"message_id":"{id}"}) and present it to me. Do not reply yet: I will decide the answer and confirm it on the card.', { id: item.message_id })
+          : t('Show me the open-relay message {id} (plugin__open-relay__Message {"message_id":"{id}"}). I will decide whether to reply or acknowledge it.', { id: item.message_id }) });
+  }
+  for (const plan of swarm.plans) {
+    if (!plan.proposal_id) continue;
+    items.push({ kind: 'plan', id: plan.proposal_id, item: plan, hint: t('Plan, then ApprovePlan or RejectPlan: you confirm the card'),
+      request: t('Show me the open-relay plan proposal {id} (plugin__open-relay__Plan {"proposal_id":"{id}"}) with its tasks, roles and digest. I will decide whether to approve or reject it and confirm it on the card.', { id: plan.proposal_id }) });
+  }
+  return items;
+}
+
+function connectionLines(view, columns) {
+  const c = view.connection, out = [];
+  if (c.notify === 'off') out.push(tone.warning(clip('  ' + t('Live watch is off (notify=off): /plugins config open-relay notify=on'), columns)));
+  else {
+    const who = c.delegate ? t('delegate {principal} via {client} · caps {caps}', { principal: c.delegate.principal, client: c.delegate.client, caps: c.delegate.caps.join(',') || '—' }) : t('delegate not confirmed yet');
+    const where = c.cursor != null ? t('cursor {cursor} · {events} events', { cursor: c.cursor, events: c.events_seen }) : '';
+    const states = { waiting: [tone.good, t('● connected · live (events.wait)')], catching_up: [tone.accent, t('◌ catching up with relayd')], connecting: [tone.accent, t('◌ connecting')], backoff: [tone.warning, t('◌ relayd unavailable · reconnecting')], needs_human: [tone.bad, t('✗ needs you: the delegate session is missing, revoked or invalid')], stopped: [tone.bad, t('✗ watch stopped')], idle: [tone.muted, t('◌ starting')] };
+    const [paint, label] = states[c.state] || [tone.muted, c.state];
+    out.push(...wrap([label, ...(c.state === 'waiting' || c.delegate ? [who] : []), where, c.reconnects ? t('{n} reconnections', { n: c.reconnects }) : ''].filter(Boolean).join(' · '), columns - 4).map(line => '  ' + paint(line)));
+  }
+  if (c.missing_caps.length) out.push(...wrap(t('Missing capabilities: {caps} (the matching actions will be refused)', { caps: c.missing_caps.join(', ') }), columns - 4).map(line => '  ' + tone.warning(line)));
+  if (c.last_error && c.state !== 'waiting') out.push(...wrap(`${c.last_error.code}: ${c.last_error.message}`, columns - 6).slice(0, 4).map(line => '    ' + tone.muted(line)));
+  if (c.issue_command && (c.state === 'needs_human' || c.missing_caps.length)) out.push(tone.muted('  ' + t('Issue it once (it never prints the token):')), ...wrap(c.issue_command, columns - 6).map(line => '    ' + tone.accent(line)));
+  return out;
+}
+
+function unavailableLines(view, columns) {
+  const lines = { not_configured: [t('The open-relay plugin is not configured in this project.'), t('1. Issue Comal\'s delegate session once: relay --control-dir DIR session issue-delegate --principal YOU --client comal --caps read,converse,plans,decide --ttl 30d --out DIR/comal.token'), t('2. /plugins add open-relay controlDir=DIR'), t('Guide: docs/open-relay-operator.md')],
+    disabled: [t('The open-relay plugin is disabled.'), t('/plugins enable open-relay turns it on (you review and trust it).')],
+    pending_trust: [t('The open-relay plugin is waiting for your trust.'), t('/plugins enable open-relay reviews it.')],
+    loading: [t('The open-relay plugin is starting…')],
+    failed: [t('The open-relay plugin could not start.')],
+    no_service: [t('This open-relay version does not publish the swarm panel. Reload it: /plugins reload open-relay')],
+    invalid: [t('The plugin sent a view that is not valid; nothing is shown.')] }[view.reason] || [t('The swarm panel has no data yet.')];
+  const out = [];
+  for (const [index, line] of lines.entries()) out.push(...wrap(line, columns - 4).map(part => '  ' + (index ? tone.muted : tone.warning)(part)));
+  if (view.error) out.push('', ...wrap(view.error, columns - 6).slice(0, 6).map(line => '    ' + tone.muted(line)));
+  return out;
+}
+
+/**
+ * Líneas del panel (overlay, como el tablero F3). state: { swarm, index, scroll }.
+ * Ajusta state.scroll para que la elección quede a la vista.
+ */
+export function swarmPanelLines(raw, state, columns, height, { now = Date.now(), busy = false } = {}) {
+  const view = raw?.available === true || raw?.available === false ? raw : null;
+  // Un turno (p. ej. despertado por un aviso urgente) corre con el panel abierto: se escribe en
+  // la conversación, detrás; el encabezado lo dice para que el humano vuelva a verlo.
+  const hint = busy ? tone.warning(clip('  ' + t('Comal is working · Esc to see the conversation'), columns)) : tone.muted(clip('  ' + t('↑/↓ choose · Enter prepares the request (does not send) · Tab swarm · PgUp/PgDn · Esc returns'), columns));
+  if (!view) return [tone.accent(t('  Swarm · open-relay')), hint, '', '  ' + tone.muted(t('Waiting for the open-relay plugin…'))].slice(0, height);
+  if (!view.available) { const lines = [tone.accent(t('  Swarm · open-relay')), busy ? hint : tone.muted(clip('  ' + t('Esc returns'), columns)), '', ...unavailableLines(view, columns)]; state.scroll = Math.min(state.scroll || 0, Math.max(0, lines.length - height)); return lines.slice(state.scroll, state.scroll + height); }
+  state.swarm = Math.max(0, Math.min(state.swarm || 0, view.swarms.length - 1));
+  const swarm = view.swarms[state.swarm], actions = swarmActions(view, state.swarm);
+  state.index = Math.max(0, Math.min(state.index || 0, actions.length - 1));
+  const lines = [tone.accent(clip(swarm ? t('  Swarm · {id} ({n}/{total})', { id: swarm.id, n: state.swarm + 1, total: view.swarms.length }) : t('  Swarm · open-relay'), columns)), hint, ...connectionLines(view, columns)];
+  if (!swarm) {
+    lines.push('', ...wrap(view.connection.notify === 'off' ? t('Without the live watch there is no panel data.') : view.connection.state === 'waiting' ? t('relayd has no swarms visible to this delegation yet.') : t('No swarm data yet.'), columns - 4).map(line => '  ' + tone.muted(line)));
+    state.scroll = Math.min(state.scroll || 0, Math.max(0, lines.length - height)); return lines.slice(state.scroll, state.scroll + height);
+  }
+  if (swarm.objective) lines.push(...wrap(swarm.objective, columns - 4).slice(0, 3).map(line => '  ' + line));
+  const teams = [...new Set([swarm.root_team, ...swarm.roles.map(role => role.team), ...swarm.tasks.map(task => task.team)].filter(Boolean))];
+  const roleNames = new Map(swarm.roles.map(role => [role.id, role.name]));
+  if (teams.length) lines.push(...wrap(t('Teams: {teams}', { teams: teams.join(', ') }), columns - 4).slice(0, 2).map(line => '  ' + tone.muted(line)));
+  if (swarm.roles.length) lines.push(...wrap(t('Roles: {roles}', { roles: swarm.roles.map(role => `${role.name}${role.name !== role.id ? ` (${role.id})` : ''}${role.occupied ? '' : ' · ' + t('vacant')}${role.model ? ' · ' + role.model : ''}`).join(' · ') }), columns - 4).slice(0, 3).map(line => '  ' + tone.muted(line)));
+  lines.push('');
+  // Lo que espera al humano: preguntas (marcando las estructuradas) y planes por aprobar.
+  let selected = -1;
+  if (actions.length) {
+    lines.push(tone.warning(t('  FOR YOU ({n}) · agent text, untrusted', { n: actions.length })));
+    actions.forEach((action, index) => {
+      const mine = index === state.index, mark = mine ? '❯' : ' ', paint = mine ? tone.accent : String;
+      if (mine) selected = lines.length;
+      if (action.kind === 'plan') {
+        const plan = action.item, age = plan.proposed_at ? formatAge(now - plan.proposed_at) : '';
+        lines.push(paint(clip(`  ${mark} ◇ ${t('Plan {id} · by {role}{age} · {tasks} tasks, {roles} roles', { id: plan.proposal_id, role: plan.proposer_role, age: age ? ' · ' + age : '', tasks: plan.tasks, roles: plan.roles })}${plan.parent_task ? ' · ' + t('under {task}', { task: plan.parent_task }) : ''}`, columns)));
+        if (plan.summary) lines.push(...wrap(`«${plan.summary}»`, columns - 8).slice(0, 2).map(line => '      ' + tone.muted(line)));
+      } else {
+        const item = action.item, age = item.sent_at ? formatAge(now - item.sent_at) : '';
+        const label = action.kind === 'decision' ? t('Structured question') : action.kind === 'question' ? t('Question') : t('Message ({kind})', { kind: item.kind });
+        lines.push(paint(clip(`  ${mark} ${action.kind === 'message' ? '·' : '?'} ${label} ${item.message_id} · ${item.from}${age ? ' · ' + age : ''}${item.task ? ' · ' + t('blocks {task}', { task: item.task }) : ''}`, columns)));
+        if (item.decision) lines.push(...wrap(t('«{question}» · options: {options}', { question: item.decision.question, options: item.decision.options.map(option => `«${option}»${option === item.decision.recommended ? ' ' + t('(agent recommends)') : ''}`).join(' | ') }), columns - 8).slice(0, 3).map(line => '      ' + tone.muted(line)));
+        else if (item.excerpt) lines.push(...wrap(`«${item.excerpt}»`, columns - 8).slice(0, 2).map(line => '      ' + tone.muted(line)));
+      }
+      if (mine) lines.push(...wrap('→ ' + action.hint, columns - 8).map(line => '      ' + tone.accent(line)));
+    });
+    lines.push('');
+  } else lines.push(tone.muted(t('  Nothing waiting for you in this swarm.')), '');
+  // Kanban: columnas como secciones, igual que el tablero F3.
+  for (const column of SWARM_COLUMNS) {
+    const tasks = swarm.tasks.filter(task => swarmColumn(task.state) === column);
+    if (!tasks.length) continue;
+    lines.push(tone.accent(`  ${columnLabel(column)} (${tasks.length})`));
+    for (const task of tasks) {
+      lines.push(...wrap(`${task.id}${task.title ? ' · ' + task.title : ''}`, columns - 6).slice(0, 2).map(line => '    ' + line));
+      const role = task.role_name || roleNames.get(task.role), age = task.since ? (task.since_exact ? '' : '≥') + formatAge(now - task.since) : '';
+      const review = task.review_kind ? t({ task: 'task review', integration: 'integration review', final: 'final review' }[task.review_kind]) : '';
+      const detail = [role ? `${role}${role !== task.role && task.role ? ` (${task.role})` : ''}` : task.role, task.state, column === 'blocked' ? blockLabel(task.state) : '', review, task.review_rounds ? t('reviewer objections: {n}', { n: task.review_rounds }) : '', task.max_attempts ? attemptsLabel(task) : '', task.infra_exhausted ? t('infrastructure streak exhausted') : '', task.wake_cap ? t('wake cap reached: only you can resume it') : '', age].filter(Boolean).join(' · ');
+      lines.push(...wrap(detail, columns - 8).slice(0, 2).map(line => '      ' + (column === 'blocked' ? tone.warning : tone.muted)(line)));
+    }
+    lines.push('');
+  }
+  if (!swarm.tasks.length) lines.push(tone.muted(t('  No tasks in this swarm yet.')), '');
+  if (swarm.truncated) lines.push(tone.muted(t('  Some tasks or roles are not shown (panel limit). Ask for plugin__open-relay__Swarm for the full list.')));
+  const footer = [view.connection.last_event ? t('last event {seq} · {type}', { seq: view.connection.last_event.seq, type: view.connection.last_event.type }) : '', view.updated_at ? t('updated {time}', { time: new Date(view.updated_at).toTimeString().slice(0, 8) }) : '', t('ages: since Comal saw the state (≥ before the watch)')].filter(Boolean).join(' · ');
+  lines.push(...wrap(footer, columns - 4).map(line => '  ' + tone.muted(line)));
+  // Desplazamiento: la elección siempre a la vista (como la cola F4); PgUp/PgDn mueve libre.
+  const max = Math.max(0, lines.length - height);
+  if (state.follow && selected >= 0) { if (selected < state.scroll + 2) state.scroll = Math.max(0, selected - 2); else if (selected >= state.scroll + height - 3) state.scroll = selected - height + 4; state.follow = false; }
+  state.scroll = Math.max(0, Math.min(state.scroll || 0, max));
+  return lines.slice(state.scroll, state.scroll + height);
+}
+
+/** Franja lateral compacta (opcional, /swarm strip): resumen siempre visible. */
+export function swarmStripLines(view, width) {
+  if (!view) return [];
+  const head = tone.accent(clip(' ' + t('Swarm'), width));
+  if (!view.available) return ['', head, tone.muted(clip(' ' + t('unavailable · /swarm'), width))];
+  const c = view.connection, out = ['', head];
+  const state = c.notify === 'off' ? t('watch off') : { waiting: t('● live'), needs_human: t('✗ needs you'), backoff: t('◌ reconnecting'), stopped: t('✗ stopped') }[c.state] || t('◌ connecting');
+  out.push((c.state === 'waiting' ? tone.good : c.state === 'needs_human' || c.state === 'stopped' ? tone.bad : tone.muted)(clip(' ' + state, width)));
+  for (const swarm of view.swarms.slice(0, 3)) {
+    const by = column => swarm.tasks.filter(task => swarmColumn(task.state) === column).length;
+    const questions = swarm.pending.filter(item => item.kind === 'question').length, plans = swarm.plans.length;
+    out.push(clip(' ' + swarm.id, width));
+    out.push(...wrap(t('{run} run · {blocked} blocked · {done} done', { run: by('running') + by('verifying') + by('reviewing'), blocked: by('blocked'), done: by('done') }), width - 1).slice(0, 2).map(line => tone.muted(' ' + line)));
+    if (questions || plans) out.push(...wrap(t('{q} questions · {p} plans', { q: questions, p: plans }), width - 1).slice(0, 2).map(line => tone.warning(' ' + line)));
+  }
+  out.push(tone.muted(clip(' ' + t('/swarm opens'), width)));
+  return out;
+}

package/src/turn-timing.mjs

@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { performance } from 'node:perf_hooks';
+import { t } from './i18n/index.mjs';
+
+// Per-turn timing on the host's monotonic clock. A turn runs inside its timer's
+// async context, so a permission card shown by any tool of that turn (or of a
+// nested subagent turn) is charged as human wait, never as Comal time.
+const active = new AsyncLocalStorage();
+export const monotonic = () => performance.now();
+export const TURN_TIMING_VERSION = 1;
+const round = value => value == null ? null : Math.round(value * 10) / 10;
+
+export class TurnTimer {
+  constructor({ clock = monotonic, parent = active.getStore() } = {}) {
+    this.clock = clock; this.parent = parent; this.started = clock();
+    this.requests = []; this.toolsMs = 0; this.humanMs = 0; this.open = 0; this.openedAt = 0;
+    this.firstText = null; this.firstOutput = null;
+  }
+  now() { return this.clock(); }
+  run(fn) { return active.run(this, fn); }
+  // Overlapping waits (parallel cards) count once: the union of open intervals.
+  humanStart() { if (this.open++ === 0) this.openedAt = this.clock(); this.parent?.humanStart(); }
+  humanEnd() { if (this.open > 0 && --this.open === 0) this.humanMs += this.clock() - this.openedAt; this.parent?.humanEnd(); }
+  humanTotal() { return this.humanMs + (this.open ? this.clock() - this.openedAt : 0); }
+  // Accepts a promise or a function that starts the wait (so the clock starts first).
+  async humanWait(wait) { this.humanStart(); try { return await (typeof wait === 'function' ? wait() : wait); } finally { this.humanEnd(); } }
+  async tools(run) {
+    const start = this.clock(), human = this.humanTotal();
+    try { return await run(); } finally { this.toolsMs += Math.max(0, this.clock() - start - (this.humanTotal() - human)); }
+  }
+  observeText() { this.firstText ??= this.clock() - this.started; this.observeOutput(); }
+  observeOutput() { this.firstOutput ??= this.clock() - this.started; }
+  record(event) { this.requests.push(event); }
+  summary({ status = 'answered' } = {}) {
+    const total = this.clock() - this.started, human = this.humanTotal();
+    const model = this.requests.reduce((sum, item) => sum + (item.phases?.find(phase => phase.phase === 'provider')?.elapsed_ms || 0), 0);
+    const reasoned = this.requests.filter(item => item.reasoning_ms != null);
+    return {
+      version: TURN_TIMING_VERSION, scope: 'host_monotonic_not_provider_billing', status,
+      total_ms: round(total), comal_ms: round(Math.max(0, total - human)), model_ms: round(model),
+      reasoning_ms: reasoned.length ? round(reasoned.reduce((sum, item) => sum + item.reasoning_ms, 0)) : null,
+      first_text_ms: round(this.firstText), first_output_ms: round(this.firstOutput),
+      tools_ms: round(this.toolsMs), human_wait_ms: round(human),
+      host_ms: round(Math.max(0, total - human - model - this.toolsMs)), requests: this.requests.length,
+      reasoning_requests: reasoned.length,
+      reasoning_tokens: this.requests.some(item => Number.isSafeInteger(item.reasoning_tokens)) ? this.requests.reduce((sum, item) => sum + (item.reasoning_tokens || 0), 0) : null
+    };
+  }
+}
+
+export function currentTurnTimer() { return active.getStore(); }
+/** Wraps a wait for a human answer; outside a turn it is a no-op. */
+export function measureHumanWait(wait) { const timer = active.getStore(); return timer ? timer.humanWait(wait) : typeof wait === 'function' ? wait() : wait; }
+
+export function formatSeconds(ms) {
+  if (ms < 1000) return `${Math.round(ms)} ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)} s`;
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes} min ${String(Math.round(seconds - minutes * 60)).padStart(2, '0')} s`;
+}
+
+/** One dim line for the TUI. Zero or unknown parts are omitted; when `width`
+ * is given, the least important parts are dropped instead of cutting a number. */
+export function formatTurnTiming(timing, { width = Infinity } = {}) {
+  if (!timing || !(Math.round(timing.comal_ms) > 0)) return '';
+  const parts = [];
+  const add = (key, value, label) => { if (Math.round(value) > 0) parts.push({ key, text: t(label, { v0: formatSeconds(value) }) }); };
+  add('reasoning', timing.reasoning_ms, 'reasoned {v0}');
+  add('first', timing.first_output_ms, 'first response {v0}');
+  add('tools', timing.tools_ms, 'tools {v0}');
+  add('human', timing.human_wait_ms, 'waiting for you {v0}');
+  const line = () => [`⏱ ${formatSeconds(timing.comal_ms)}`, ...parts.map(part => part.text)].join(' · ');
+  for (const key of ['first', 'tools', 'reasoning']) { if ([...line()].length <= width) break; const index = parts.findIndex(part => part.key === key); if (index >= 0) parts.splice(index, 1); }
+  return line();
+}
+
+/** Public JSON contract of the final `result` event. */
+export function resultTiming(summary) {
+  const { total_ms, model_ms, reasoning_ms, first_text_ms, tools_ms, human_wait_ms, requests, comal_ms, first_output_ms, host_ms, reasoning_requests, reasoning_tokens } = summary;
+  return { total_ms, model_ms, reasoning_ms, first_text_ms, tools_ms, human_wait_ms, requests, comal_ms, first_output_ms, host_ms, reasoning_requests, reasoning_tokens };
+}

package/src/usage-accounting.mjs

@@ -8,11 +8,22 @@ export function normalizeUsage(protocol, raw) {
   let input=null, fresh=null, read=null, write=null, output=null, reasoning=null, semantics='unknown';
   const fields={};
   const take=(name,value)=>{const n=count(value);if(n!==null)fields[name]=n;return n;};
-  if(protocol==='anthropic') {
+  const anthropicIters=protocol==='anthropic'&&Array.isArray(raw.iterations)?raw.iterations.filter(entry=>entry&&typeof entry==='object'):null;
+  if(protocol==='anthropic'&&anthropicIters&&anthropicIters.length) {
+    // usage.iterations es la verdad de facturación por intento (fallback incluido):
+    // se suma por intento para el costo. El model de nivel superior cubre sólo el
+    // intento que produjo el mensaje; aquí se agrega la cadena entera.
+    const add=(name,pick)=>{const vals=anthropicIters.map(pick).map(count);if(vals.length&&vals.every(value=>value!==null)){fields[name]=vals.reduce((a,b)=>a+b,0);return fields[name];}return null;};
+    fresh=add('input_tokens',entry=>entry.input_tokens);read=add('cache_read_input_tokens',entry=>entry.cache_read_input_tokens);write=add('cache_creation_input_tokens',entry=>entry.cache_creation_input_tokens);
+    output=add('output_tokens',entry=>entry.output_tokens);reasoning=add('thinking_tokens',entry=>entry.output_tokens_details?.thinking_tokens);
+    input=sum([fresh,read,write]);if(fresh!==null && read===null && write===null) input=fresh;semantics='cache_components_separate';
+  } else if(protocol==='anthropic') {
     fresh=take('input_tokens',raw.input_tokens);read=take('cache_read_input_tokens',raw.cache_read_input_tokens);write=take('cache_creation_input_tokens',raw.cache_creation_input_tokens);
     // Anthropic omits absent cache components on uncached responses; omission is
     // not observed zero. The base is exact only if all components are reported.
     input=sum([fresh,read,write]);output=take('output_tokens',raw.output_tokens);semantics='cache_components_separate';
+    // Claude 5.x reports thinking inside output_tokens (output_tokens_details.thinking_tokens).
+    reasoning=take('thinking_tokens',raw.output_tokens_details?.thinking_tokens);
     if(fresh!==null && read===null && write===null) input=fresh;
   } else if(['openai','codex'].includes(protocol)) {
     input=take(protocol==='openai'?'prompt_tokens':'input_tokens',protocol==='openai'?raw.prompt_tokens:raw.input_tokens);

package/src/vision.mjs

@@ -4,10 +4,15 @@ import { workProjection } from './work-plan.mjs';
 import { comalEnvironment } from './compat.mjs';
 import { digest } from './operations.mjs';
 import { humanImageReferences, resolveHumanImage } from './image-attachments.mjs';
+import { VISUAL_IMAGE_OPERATIONS } from './visual/names.mjs';
 
 export const IMAGE_LIMIT = 2 * 1024 * 1024;
 export const IMAGE_COUNT = 2;
-const mcpReceipt = row => row.origin?.kind === 'mcp' || row.origin == null && /^mcp__.+__.+$/.test(row.operation || '');
+// Image-bearing receipts: MCP tools, the native Read of an image file, the native visual
+// acceptance operations, and exactly one plugin receipt (chrome-lab Screenshot), which carries
+// the same structured image block.
+const mcpReceipt = row => row.origin?.plugin === 'chrome-lab' && row.operation === 'plugin__chrome-lab__Screenshot'
+  || row.origin?.kind === 'mcp' || row.origin == null && (/^mcp__.+__.+$/.test(row.operation || '') || row.operation === 'Read' || VISUAL_IMAGE_OPERATIONS.includes(row.operation));
 export function visionSettings(options = {}, env = process.env) {
   env = comalEnvironment(env);
   const vision = options.vision ?? env.COMAL_VISION ?? 'auto';