@milpa/comal 0.2.2 → 0.2.4

package/src/relay/broker.mjs

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { t, registerMessages } from '../i18n/index.mjs';
+import { RELAY_ANSWERS } from '../remote-relay.mjs';
+
+// /rc + /relay, fase «responder»: una tarjeta, dos superficies (la TUI y el navegador de /rc).
+// Gana el primero que CONFIRMA (D3): abrir o mirar la tarjeta no reserva nada. El candado es
+// síncrono en el event loop, por card key (la misma clave que follow.mjs y remote-relay.mjs), y
+// sólo lo toma una mutación en curso. Una tarjeta decidida queda en `decided` y cualquier otro
+// intento (otra superficie, un control repetido o viejo) responde already_decided sin mutar.
+// Hace falta en Comal porque relayd admite rechazar un plan ya aprobado y aún no aplicado.
+registerMessages({
+  'Open /rc first, with a Comal backend that supports devices.': 'Abre /rc primero, con un backend de Comal que admita dispositivos.',
+  'Device: {label} ({id}){connected}.': 'Dispositivo: {label} ({id}){connected}.',
+  ', connected {time}': ', conectado {time}',
+  'No device paired.': 'Ningún dispositivo emparejado.',
+  'Device removed; its permission answers are off.': 'Dispositivo quitado; sus respuestas de permisos quedan apagadas.',
+  'Permission answers from the M5Stack: armed until {time}.': 'Respuestas de permisos desde el M5Stack: armadas hasta las {time}.',
+  'Permission answers from the M5Stack: off.': 'Respuestas de permisos desde el M5Stack: apagadas.',
+  'Pair a device first with /rc device CODE.': 'Empareja un dispositivo primero con /rc device CODE.',
+  'The /rc session has expired; open /rc again.': 'La sesión de /rc caducó; abre /rc de nuevo.',
+  '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.': 'Permisos desde el M5Stack activos hasta {time}. El comando o la ruta de cada tarjeta pasa por comal.milpahq.com hacia el aparato y no se guarda.',
+  'Device paired: {label} ({id}).': 'Dispositivo emparejado: {label} ({id}).',
+  'Answered on the M5Stack: {decision} · {tool}': 'Contestada en el M5Stack: {decision} · {tool}',
+  'allowed once': 'permitida una vez', 'denied': 'negada',
+  '{what} was decided from the browser ({outcome}).': '{what} se decidió desde el navegador ({outcome}).',
+  'Already decided from the browser ({outcome}); nothing was sent.': 'Ya decidida desde el navegador ({outcome}); no se envió nada.',
+  'This card is being decided in this terminal right now.': 'Esta tarjeta se está decidiendo ahora mismo en esta terminal.',
+  'Plan {id}': 'El plan {id}', 'The question {id}': 'La pregunta {id}', 'The success criteria of {swarm}': 'Los criterios de éxito de {swarm}',
+  '/relay answers from the browser: armed until {time}.': 'Respuestas de /relay desde el navegador: armadas hasta las {time}.',
+  '/relay answers from the browser: off.': 'Respuestas de /relay desde el navegador: apagadas.',
+  'Open /rc first; /rc relay on arms answers for that session only.': 'Abre /rc primero; /rc relay on arma las respuestas sólo para esa sesión.',
+  'Plans and success criteria also need a sign-in from the last 10 minutes in that browser; retrying blocked tasks stays here. /rc relay off disarms.': 'Aprobar planes y criterios de éxito exige además haber iniciado sesión en ese navegador hace ≤ 10 min; reintentar tareas bloqueadas sigue aquí. /rc relay off las apaga.',
+  'approved': 'aprobado', 'rejected': 'rechazado', 'decided': 'decidida', 'answered': 'respondida', 'acked': 'dada por leída',
+});
+
+const sha256 = value => createHash('sha256').update(value).digest('hex');
+const KIND_OF = action => RELAY_ANSWERS.actions[action]?.card || null;
+const APPLIED = new Set(RELAY_ANSWERS.outcomes.applied);
+
+// Lo decidido se recuerda 10 min (el TTL de un control): pasado eso manda la re-lectura de relayd.
+const DECIDED_MS = RELAY_ANSWERS.control_ttl_seconds * 1000;
+export class RelayDecisionBroker {
+  constructor({ now = Date.now } = {}) { this.now = now; this.locks = new Map(); this.decided = new Map(); this.watchers = new Map(); }
+  /** Candado de una sola entrada. {ok} o {ok:false, holder|decided}. Lo decidido por la OTRA
+   *  superficie bloquea; lo decidido por la misma lo juzga relayd al volver a leer. */
+  begin(key, source) {
+    const decided = this.outcome(key); if (decided && decided.by !== source) return { ok: false, decided };
+    const holder = this.locks.get(key); if (holder) return { ok: false, holder };
+    this.locks.set(key, source); return { ok: true };
+  }
+  release(key) { this.locks.delete(key); }
+  /** La tarjeta quedó decidida: suelta el candado, la recuerda y cierra la tarjeta abierta en la otra superficie. */
+  commit(key, { outcome, by, request_id = null }) {
+    this.locks.delete(key);
+    this.decided.set(key, { outcome, by, request_id, at: this.now() });
+    if (this.decided.size > 2000) this.decided.delete(this.decided.keys().next().value);
+    for (const controller of this.watchers.get(key) || []) controller.abort();
+  }
+  outcome(key) { const decided = this.decided.get(key); return decided && this.now() - decided.at < DECIDED_MS ? decided : null; }
+  /** Señal por tarjeta abierta en la TUI (combinada con la de la sesión): si la otra superficie
+   *  decide, su setupChoice/setupInput se cierra solo. */
+  open(key, signal) {
+    const controller = new AbortController(), set = this.watchers.get(key) || new Set();
+    set.add(controller); this.watchers.set(key, set);
+    return { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal, close: () => { set.delete(controller); if (!set.size) this.watchers.delete(key); } };
+  }
+}
+
+/** ¿El texto cumple la regla de la acción? (none | required | optional, en bytes UTF-8). */
+export function relayText(action, text) {
+  const rule = RELAY_ANSWERS.actions[action], value = typeof text === 'string' ? text : '';
+  if (!rule) return false;
+  if (rule.text === 'none') return value === '';
+  if (Buffer.byteLength(value) > rule.text_max) return false;
+  return rule.text === 'optional' || value.trim() !== '';
+}
+
+/**
+ * Camino del navegador (RemoteHost → onRelay). Revalida en local, en este orden (§4.2 del
+ * diseño), y sólo entonces muta con las funciones de la TUI (RelayFlow.apply*):
+ *   1. libro: ¿ya se resolvió este request_id? → el mismo resultado, sin mutar (ACK perdido, reinicio);
+ *   2. sesión y época de /rc; 3. armado local vigente; 4. caducidad del control;
+ *   5. tarjeta pendiente en esta sesión, de la clase y el sujeto del control, acción permitida;
+ *      candado libre (si ya está decidida: already_decided);
+ *   6. remote.inputs.validate (el login del navegador sigue vivo);
+ *   7. relayd en vivo (dentro de apply*: plan.get / msg.get+inbox / criteria.get) y mutación.
+ * Todo control deja su fila relay_control con source remote_browser y su request_id.
+ */
+export class RemoteRelayAnswers {
+  constructor({ broker, flow, feed, rows = async () => [], now = Date.now }) {
+    Object.assign(this, { broker, flow, feed, rows, now });
+    this.ledger = null;
+  }
+  async #ledger() {
+    if (!this.ledger) {
+      this.ledger = new Map();
+      try { for (const row of await this.rows()) if (row?.type === 'relay_control' && row.source === 'remote_browser' && row.remote_request_id && row.remote_outcome) this.ledger.set(row.remote_request_id, { state: row.remote_state, outcome: row.remote_outcome }); } catch {}
+    }
+    return this.ledger;
+  }
+  async #settle(input, control, result, extra = {}) {
+    const ledger = await this.#ledger();
+    ledger.set(input.request_id, result);
+    if (ledger.size > 4096) ledger.delete(ledger.keys().next().value);
+    // Las mutaciones aplicadas ya dejaron su fila (apply*, con remote_*); el resto deja la suya aquí.
+    if (!extra.recorded) try { await this.flow.record({ action: 'remote.answer', source: 'remote_browser', remote_session: input.remote_session_id, remote_request_id: input.request_id, remote_action: control?.action || null, card_id: control?.card_id || null, remote_state: result.state, remote_outcome: result.outcome, ...extra.row }); } catch {}
+    return result;
+  }
+  async handle(input, { session, epoch, armed = () => false, validate = async () => true } = {}) {
+    const control = input?.control || {}, ledger = await this.#ledger();
+    // 1. Libro: el mismo request_id devuelve lo mismo y nunca vuelve a mutar.
+    if (ledger.has(input?.request_id)) return ledger.get(input.request_id);
+    const refuse = (state, outcome) => this.#settle(input, control, { state, outcome });
+    if (input?.kind !== 'relay' || !KIND_OF(control.action)) return refuse('refused', 'invalid');
+    // 2. Sesión y época.
+    if (input.remote_session_id !== session || control.host_epoch !== epoch) return refuse('stale', 'epoch');
+    // 3. Armado local (D1).
+    if (!armed()) return refuse('refused', 'local_arm_off');
+    // 4. Caducidad (10 min desde la admisión en Milpa).
+    if (!Number.isFinite(Number(input.expires_at)) || Number(input.expires_at) * 1000 <= this.now()) return refuse('expired', 'expired');
+    // 5. Tarjeta: publicada en esta sesión y todavía pendiente aquí.
+    const entry = this.feed?.card(control.card_id);
+    // Una tarjeta ya cerrada (decidida en cualquier superficie, o por otro control) no se vuelve a decidir.
+    if (!entry) return refuse('stale', this.feed?.resolution?.(control.card_id) ? 'already_decided' : 'card_gone');
+    const card = entry.card, rule = RELAY_ANSWERS.actions[control.action];
+    if (card.kind !== rule.card || card.subject !== control.subject || card.project !== control.project || card.swarm !== control.swarm) return refuse('stale', 'kind');
+    if (!card.answerable?.browser || !card.answerable.actions?.includes(control.action)) return refuse('refused', 'cap_missing');
+    if (!relayText(control.action, control.text ?? '')) return refuse('refused', 'invalid');
+    for (const field of rule.fields) if (control[field] === undefined || control[field] === null) return refuse('refused', 'invalid');
+    if (rule.fields.includes('digest') && control.digest !== card.body.digest) return refuse('stale', 'digest');
+    if (control.action === 'plan.approve' && control.projection_sha256 !== card.body.projection_sha256) return refuse('stale', 'projection');
+    const lock = this.broker.begin(entry.key, 'browser');
+    if (!lock.ok) return lock.decided ? refuse('stale', 'already_decided') : refuse('refused', 'local_in_progress');
+    let result;
+    try {
+      // 6. El navegador que lo pidió sigue con sesión (login padre).
+      try { await validate(); } catch { this.broker.release(entry.key); return refuse('refused', 'revoked'); }
+      // 7. relayd en vivo + mutación, con las funciones y claves de la TUI.
+      const remote = { source: 'remote_browser', remote_session: input.remote_session_id, remote_request_id: input.request_id, card_id: control.card_id };
+      result = await this.#apply(entry, control, remote);
+    } catch (error) {
+      this.broker.release(entry.key);
+      const delegation = ['NOT_DELEGATED', 'UNAUTHORIZED', 'RELAY_DELEGATE_MISSING', 'RELAY_TOKEN_INVALID', 'RELAY_TOKEN_UNSAFE'].includes(error?.code);
+      return refuse('refused', delegation ? 'delegation' : 'relay_unavailable');
+    }
+    if (APPLIED.has(result.outcome)) {
+      this.broker.commit(entry.key, { outcome: result.outcome, by: 'browser', request_id: input.request_id });
+      this.flow.ui?.notice?.(t('{what} was decided from the browser ({outcome}).', { what: this.#what(card), outcome: t(result.outcome) }));
+      return this.#settle(input, control, { state: 'applied', outcome: result.outcome }, { recorded: true });
+    }
+    // Obsoleta o ya decidida fuera de Comal (relayd lo dice): no se muta y la TUI decide con su propia re-lectura.
+    this.broker.release(entry.key);
+    return refuse('stale', result.outcome || 'stale');
+  }
+  #what(card) {
+    if (card.kind === 'plan') return t('Plan {id}', { id: card.subject });
+    if (card.kind === 'question') return t('The question {id}', { id: card.subject });
+    return t('The success criteria of {swarm}', { swarm: card.swarm });
+  }
+  async #apply(entry, control, remote) {
+    const item = entry.item, base = { project: item.project, root: item.root, swarm: item.swarm, ...remote };
+    if (entry.card.kind === 'plan') return this.flow.applyPlan({ ...base, proposal_id: item.proposal_id, digest: control.digest, choice: control.action === 'plan.approve' ? 'approve' : 'reject', reason: control.text, projection: control.projection_sha256 });
+    if (entry.card.kind === 'question') {
+      const mode = control.action.slice('question.'.length);
+      // La opción se identifica por índice Y por el sha256 de la etiqueta que vio el navegador.
+      const option = mode === 'option' ? entry.card.body.decision?.options?.[control.option_index] : null;
+      if (mode === 'option' && (!option || sha256(option.label) !== control.option_label_sha256)) return { outcome: 'option' };
+      return this.flow.applyQuestion({ ...base, message_id: item.message_id, mode, option_index: control.option_index, option_label_sha256: control.option_label_sha256, text: control.text || '' });
+    }
+    if (entry.card.kind === 'criteria') return this.flow.applyCriteria({ ...base, digest: control.digest, choice: control.action === 'criteria.accept' ? 'accept' : 'reject', reason: control.text });
+    return { outcome: 'kind' };
+  }
+}