@ajuarezso/lienzo-mcp 0.3.1 → 0.5.0

package/lib/menciones.mjs

@@ -0,0 +1,200 @@
+// Menciones y tope de turnos entre agentes (F2, docs/rediseno-chat-lienzo.md §6).
+//
+// · `menciones` es un campo opcional de la tarjeta: lista de ids de participantes (hasta MAX_MENCIONES). El puente
+//   acepta ids o nombres y los resuelve contra la sala (un nombre repetido no se adivina). «@todos» = sin menciones.
+// · Convención: un agente contesta en la sala solo si lo mencionan o si la tarjeta es para él (paraId).
+// · Tope: un TURNO es una tarjeta de un agente DIRIGIDA a otro agente (paraId, menciones o respondeA a una tarjeta de
+//   otro agente) que sigue a la de OTRO agente; la respuesta a una tarea por lienzo_tarea (tomadaPor = otro agente)
+//   cuenta como turno de quien responde aunque no cree tarjeta. Después de TOPE_TURNOS turnos sin una persona en
+//   medio, el puente no publica nada dirigido a otro agente, y cada agente tiene UNA tarjeta más (a toda la sala o a
+//   una persona) para avisar que esperan a alguien. Lo que no va a otro agente no suma: varios agentes que publican
+//   avances para sus personas no se frenan entre sí. Una lista de puntos cuenta como una sola tarjeta.
+//   Las reglas de Firestore no pueden contarlo (no hay consultas entre documentos): es convención del puente.
+import { cuentaDe } from './agentes.mjs';
+
+export const MAX_MENCIONES = 10;
+export const TOPE_TURNOS = 6;
+/**
+ * El puente lee las tarjetas recientes de a PAGINA_TURNOS, de la más nueva a la más vieja, hasta dar con una de una
+ * persona (lo anterior no cuenta) o hasta PAGINAS_TURNOS páginas. Si en VENTANA_TURNOS tarjetas no escribió ninguna
+ * persona y hay más viejas, se trata como tope (`sinPersona`): así llenar la sala de tarjetas (una lista de 30 puntos)
+ * no reinicia la cuenta. Lo normal es una sola lectura de PAGINA_TURNOS.
+ */
+export const PAGINA_TURNOS = 16;
+export const PAGINAS_TURNOS = 3;
+export const VENTANA_TURNOS = PAGINA_TURNOS * PAGINAS_TURNOS;
+
+/** Palabras que significan «toda la sala» (no son una mención). */
+const TODOS = new Set(['todos', 'todas', 'all', 'everyone', 'sala']);
+
+/** ¿El participante es una persona? `{uid}` sí; `{uid}_agente` y `{uid}_agente_{slug}` no. */
+export const esPersona = (id) => Boolean(id) && cuentaDe(id) === String(id);
+
+/** ¿Es un agente? (cualquier participante que no es una persona) */
+export const esAgente = (id) => Boolean(id) && !esPersona(id);
+
+/**
+ * Las menciones tal como las pasó el agente → referencias limpias (sin «@», sin repetidos, sin «todos»).
+ * Lanza Error con el texto para el agente si no es una lista o trae más de MAX_MENCIONES.
+ */
+export function referenciasDeMenciones(menciones) {
+  if (menciones == null) return [];
+  if (!Array.isArray(menciones)) throw new Error('menciones es una lista de ids o nombres de participantes.');
+  const refs = [];
+  const vistas = new Set();
+  for (const m of menciones) {
+    const r = String(m ?? '').trim().replace(/^@+/, '').trim();
+    if (!r) continue;
+    if (TODOS.has(r.toLowerCase())) continue;
+    const clave = r.toLowerCase();
+    if (vistas.has(clave)) continue;
+    vistas.add(clave);
+    refs.push(r);
+  }
+  if (refs.length > MAX_MENCIONES) {
+    throw new Error(`Una tarjeta menciona hasta ${MAX_MENCIONES} participantes (trae ${refs.length}). Para toda la sala, publica sin menciones.`);
+  }
+  return refs;
+}
+
+/** Las menciones guardadas en una tarjeta (lo que venga: solo strings, sin repetidos, a lo sumo MAX_MENCIONES). */
+export function mencionesDe(t) {
+  const m = t?.menciones;
+  if (!Array.isArray(m)) return [];
+  return [...new Set(m.filter((x) => typeof x === 'string' && x))].slice(0, MAX_MENCIONES);
+}
+
+/** ¿La tarjeta menciona a `id`? */
+export const menciona = (t, id) => Boolean(id) && mencionesDe(t).includes(id);
+
+// ── turnos ─────────────────────────────────────────────────────────────────
+// La misma lógica vive en la web (web/src/app/sala/chat/turnos.ts) para la fila «los agentes van N turnos»: un
+// cambio acá va también allá, con sus tests.
+
+const RE_PUNTO = /^(.+)-p\d{2}$/;
+
+/** ¿Es un punto de una lista (id «<lista>-pNN» que responde a la lista)? Cuenta junto con su lista, no aparte. */
+export const esPuntoDeLista = (t) => Boolean(t?.respondeA) && RE_PUNTO.exec(String(t.id ?? ''))?.[1] === t.respondeA;
+
+/** A quiénes va una tarjeta: paraId, menciones y el autor de la tarjeta a la que responde (si se conoce). */
+export function destinosDe(t, autorDe = () => null) {
+  const d = [t?.paraId, ...mencionesDe(t)];
+  if (t?.respondeA) d.push(autorDe(t.respondeA));
+  return [...new Set(d.filter((x) => typeof x === 'string' && x))];
+}
+
+/** ¿Algún destino es un agente que no es quien publica? */
+export const vaAOtroAgente = (autorId, destinos) => (destinos ?? []).some((d) => d && d !== autorId && esAgente(d));
+
+/**
+ * Lo que una tarjeta aporta a la racha, en orden: { autor, persona } o { autor, dirigido }. Un punto de lista no
+ * aporta nada (va con su lista). Una tarea de un agente que tomó o respondió OTRO agente suma después la respuesta
+ * de ese agente (lienzo_tarea no crea tarjeta, pero es contestarle al que pidió).
+ */
+export function eventosDe(t, autorDe = () => null) {
+  if (!t?.autorId || esPuntoDeLista(t)) return [];
+  if (esPersona(t.autorId)) return [{ autor: t.autorId, persona: true }];
+  const eventos = [{ autor: t.autorId, dirigido: vaAOtroAgente(t.autorId, destinosDe(t, autorDe)) }];
+  if (t.tipo === 'tarea' && esAgente(t.tomadaPor) && t.tomadaPor !== t.autorId) eventos.push({ autor: t.tomadaPor, dirigido: true });
+  return eventos;
+}
+
+/**
+ * Racha: turnos agente↔agente desde la última persona, el autor del último paso dirigido a un agente, los agentes
+ * que ya usaron su tarjeta de salida después del tope y si la cuenta es por no haber visto a ninguna persona.
+ */
+export const RACHA_VACIA = Object.freeze({ turnos: 0, ultimo: null, salidas: Object.freeze([]), sinPersona: false });
+
+/** Suma un evento (eventosDe) a la racha. */
+export function sumarEvento(r, e) {
+  if (!e?.autor) return r;
+  if (e.persona) return { ...RACHA_VACIA, ultimo: e.autor };
+  if (!e.dirigido) {
+    // antes del tope no cuenta; después, es la única tarjeta que le queda a ese agente hasta que escriba una persona
+    return r.turnos >= TOPE_TURNOS && !r.salidas.includes(e.autor) ? { ...r, salidas: [...r.salidas, e.autor] } : r;
+  }
+  if (e.autor === r.ultimo) return r; // el mismo agente sigue: no es un turno nuevo
+  return { ...r, turnos: r.ultimo && esAgente(r.ultimo) ? r.turnos + 1 : r.turnos, ultimo: e.autor };
+}
+
+/** Suma una tarjeta a la racha (en orden de creación). */
+export const sumarTarjeta = (r, t, autorDe) => eventosDe(t, autorDe).reduce(sumarEvento, r);
+
+/** La racha de una lista de tarjetas en orden de creación (de la más vieja a la más nueva). */
+export function rachaDe(tarjetas, inicio = RACHA_VACIA) {
+  const autorDe = autoresDe(tarjetas);
+  return (tarjetas ?? []).reduce((r, t) => sumarTarjeta(r, t, autorDe), inicio);
+}
+
+const autoresDe = (tarjetas) => {
+  const porId = new Map((tarjetas ?? []).filter((t) => t?.id).map((t) => [t.id, t.autorId]));
+  return (id) => porId.get(id) ?? null;
+};
+
+/**
+ * La racha de las tarjetas recientes tal como las devuelve la consulta (de la más NUEVA a la más vieja). Cuenta solo
+ * desde la última tarjeta de una persona. `agotada` = no hay tarjetas más viejas que estas. Sin persona a la vista y
+ * con más tarjetas detrás, la racha arranca en el tope (`sinPersona`): nadie mira desde hace VENTANA_TURNOS tarjetas.
+ */
+export function rachaDeRecientes(nuevasPrimero, { agotada = true } = {}) {
+  const lista = nuevasPrimero ?? [];
+  const autorDe = autoresDe(lista);
+  const tramo = [];
+  let persona = null;
+  for (const t of lista) {
+    if (t?.autorId && esPersona(t.autorId)) { persona = t.autorId; break; }
+    tramo.push(t);
+  }
+  let inicio = RACHA_VACIA;
+  if (persona) inicio = { ...RACHA_VACIA, ultimo: persona };
+  else if (!agotada) inicio = { ...RACHA_VACIA, turnos: TOPE_TURNOS, sinPersona: true };
+  return tramo.reverse().reduce((r, t) => sumarTarjeta(r, t, autorDe), inicio);
+}
+
+/**
+ * ¿Publicar ahora pasaría el tope? Con TOPE_TURNOS turnos (o sin persona a la vista): nada dirigido a otro agente;
+ * lo demás (a toda la sala o a personas) pasa una vez por agente, para llamar a alguien. Sin persona a la vista la
+ * salida no se acaba: la sala solo tiene agentes y lo que no va a otro agente no gasta a nadie.
+ * @param {{ turnos: number, salidas: string[], sinPersona?: boolean }} racha
+ * @param {string} yo  el participante que publica
+ * @param {boolean} dirigido  ¿lo que publica va a otro agente? (vaAOtroAgente)
+ */
+export function pasaElTope(racha, yo, dirigido) {
+  if (!racha || racha.turnos < TOPE_TURNOS) return false;
+  if (dirigido) return true;
+  if (racha.sinPersona) return false;
+  return (racha.salidas ?? []).includes(yo);
+}
+
+const porQue = (racha) => (racha.sinPersona
+  ? `en las últimas ${VENTANA_TURNOS} tarjetas de la sala no escribió ninguna persona`
+  : `los agentes ya llevan ${racha.turnos} turnos seguidos contestándose sin que escriba una persona (el tope de Lienzo es ${TOPE_TURNOS})`);
+
+/** El mensaje con el que el puente rechaza la publicación que pasaría el tope. */
+export function textoTope(racha, dirigido = true) {
+  if (dirigido) {
+    return `No publiqué: ${porQue(racha)}, y esto va a otro agente (paraId, menciones o respondeA). Avísale a tu ` +
+      'usuario qué quedó pendiente y espera a que una persona escriba en la sala (lienzo_esperar). Si necesitas que ' +
+      'alguien decida, publica UNA tarjeta para una persona (paraId o menciones con el id de una persona) o para toda la sala.';
+  }
+  return `No publiqué: ${porQue(racha)}, y ya usaste tu tarjeta para avisar. Hasta que escriba una persona no ` +
+    'publicas más en esta sala: cuéntale a tu usuario qué quedó pendiente y espera (lienzo_esperar).';
+}
+
+/** La línea que el puente agrega a lo que entrega cuando la sala llegó al tope (null si no). */
+export function lineaTope(racha) {
+  if (!racha || racha.turnos < TOPE_TURNOS) return null;
+  return `Turnos entre agentes: ${racha.sinPersona ? `ninguna persona escribió en las últimas ${VENTANA_TURNOS} tarjetas` : `${racha.turnos} seguidos sin una persona en medio`} ` +
+    `(tope ${TOPE_TURNOS}). No le escribas a otro agente hasta que escriba una persona: el puente no lo publica. Avísale ` +
+    'a tu usuario; si hace falta que alguien decida, tienes UNA tarjeta para una persona o para la sala.';
+}
+
+/** Texto de la convención, para las instructions del servidor, la skill y los prompts. */
+export const CONVENCION =
+  'CUÁNDO CONTESTAR EN LA SALA: contesta solo si te mencionan (te lo dice «te mencionan») o si la tarjeta es para ti ' +
+  '(para: ti). Lo que va a toda la sala o a otros, léelo y cuéntaselo a tu usuario si le sirve, sin contestar. Para ' +
+  'nombrar a alguien usa menciones en lienzo_publicar (ids o nombres; sin menciones = toda la sala). Tope: después de ' +
+  `${TOPE_TURNOS} turnos seguidos entre agentes sin que escriba una persona (pedir una tarea a otro agente y que te ` +
+  'la responda también son turnos), el puente no publica nada dirigido a otro agente y te deja UNA tarjeta más, para ' +
+  'una persona o para la sala, para avisar que esperan a alguien. Así dos agentes no gastan las cuentas de sus ' +
+  'personas sin que nadie mire.';

package/lib/storage.mjs

@@ -0,0 +1,107 @@
+// Cliente REST mínimo de Firebase Storage, con el idToken de la cuenta conectada (la de la persona), igual que
+// firestore.mjs: las reglas (storage.rules) se aplican como en la web y el puente no tiene privilegios.
+//   subir   POST {base}/o?name=<ruta>      multipart: metadatos JSON + bytes (contentType, contentDisposition, autorId)
+//   bajar   GET  {base}/o/<ruta>?alt=media
+//   borrar  DELETE {base}/o/<ruta>
+// Nunca pide ni usa la URL con token de descarga (esa se salta las reglas).
+import { randomBytes } from 'node:crypto';
+
+export const TIMEOUT_STORAGE_MS = 120 * 1000; // 25 MB por una conexión lenta
+
+export class ErrorStorage extends Error {
+  constructor(status, cuerpo) {
+    super(cuerpo?.error?.message || `HTTP ${status}`);
+    this.status = status;
+  }
+  get negado() { return this.status === 403 || this.status === 401; }
+  get noExiste() { return this.status === 404; }
+}
+
+export class Storage {
+  /** @param {{ storageBucket: string, emuladorStorage?: string|null }} config */
+  constructor(config, sesion, { fetch: f = globalThis.fetch } = {}) {
+    this.sesion = sesion;
+    this.fetch = f;
+    this.bucket = config.storageBucket;
+    const raiz = config.emuladorStorage ? `http://${config.emuladorStorage}` : 'https://firebasestorage.googleapis.com';
+    this.base = `${raiz}/v0/b/${encodeURIComponent(this.bucket ?? '')}/o`;
+  }
+
+  async _pedir(metodo, url, { cuerpo, cabeceras = {}, reintento = true, signal } = {}) {
+    if (!this.bucket) throw new ErrorStorage(0, { error: { message: 'falta storageBucket en firebase.config.json' } });
+    const token = await this.sesion.token();
+    const senales = [AbortSignal.timeout(TIMEOUT_STORAGE_MS), signal].filter(Boolean);
+    let r;
+    try {
+      r = await this.fetch(url, {
+        method: metodo,
+        headers: { Authorization: `Firebase ${token}`, ...cabeceras },
+        body: cuerpo,
+        signal: senales.length > 1 ? AbortSignal.any(senales) : senales[0],
+      });
+    } catch (e) {
+      if (e?.name === 'TimeoutError') throw new Error(`Storage no respondió en ${TIMEOUT_STORAGE_MS / 1000} s`);
+      throw e;
+    }
+    if (r.status === 401 && reintento) {
+      await this.sesion.renovar();
+      return this._pedir(metodo, url, { cuerpo, cabeceras, reintento: false, signal });
+    }
+    return r;
+  }
+
+  static async _error(r) {
+    const d = await r.json().catch(() => ({}));
+    return new ErrorStorage(r.status, d);
+  }
+
+  /**
+   * Sube `bytes` a `ruta` en UNA petición (multipart): los metadatos que miran las reglas viajan con el archivo.
+   * @param {string} ruta  salas/{salaId}/adjuntos/{tarjetaId}/{nombre}
+   * @param {Uint8Array} bytes
+   * @param {{ contentType: string, contentDisposition: string, metadatos: Record<string,string> }} m
+   */
+  async subir(ruta, bytes, { contentType, contentDisposition, metadatos }) {
+    const limite = `lienzo-${randomBytes(12).toString('hex')}`;
+    const meta = JSON.stringify({ name: ruta, contentType, contentDisposition, metadata: metadatos });
+    const cuerpo = Buffer.concat([
+      Buffer.from(`--${limite}\r\nContent-Type: application/json; charset=utf-8\r\n\r\n${meta}\r\n--${limite}\r\nContent-Type: ${contentType}\r\n\r\n`),
+      Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+      Buffer.from(`\r\n--${limite}--`),
+    ]);
+    const r = await this._pedir('POST', `${this.base}?name=${encodeURIComponent(ruta)}`, {
+      cuerpo,
+      cabeceras: { 'Content-Type': `multipart/related; boundary=${limite}`, 'X-Goog-Upload-Protocol': 'multipart' },
+    });
+    if (!r.ok) throw await Storage._error(r);
+    return r.json().catch(() => ({}));
+  }
+
+  /**
+   * Baja el objeto entero (con un tope: no se aceptan más bytes que `maxBytes`). Devuelve un Uint8Array.
+   */
+  async bajar(ruta, { maxBytes, signal } = {}) {
+    const r = await this._pedir('GET', `${this.base}/${encodeURIComponent(ruta)}?alt=media`, { signal });
+    if (!r.ok) throw await Storage._error(r);
+    const largo = Number(r.headers.get('content-length'));
+    if (maxBytes != null && Number.isFinite(largo) && largo > maxBytes) {
+      await r.body?.cancel?.().catch(() => {});
+      throw new ErrorStorage(413, { error: { message: `el archivo pesa ${largo} bytes y la tarjeta dice ${maxBytes}` } });
+    }
+    const partes = [];
+    let total = 0;
+    for await (const trozo of r.body ?? []) {
+      total += trozo.byteLength;
+      if (maxBytes != null && total > maxBytes) {
+        throw new ErrorStorage(413, { error: { message: `el archivo pesa más de lo que dice la tarjeta (${maxBytes} bytes)` } });
+      }
+      partes.push(trozo);
+    }
+    return new Uint8Array(Buffer.concat(partes));
+  }
+
+  async borrar(ruta) {
+    const r = await this._pedir('DELETE', `${this.base}/${encodeURIComponent(ruta)}`);
+    if (!r.ok && r.status !== 404) throw await Storage._error(r);
+  }
+}

package/lib/version.mjs

@@ -0,0 +1,48 @@
+// ¿Hay una versión nueva del puente en npm? (21-10-2026, «el MCP de Figma se actualiza solo, el nuestro también debería»)
+//
+// Instalado con `npx -y @ajuarezso/lienzo-mcp@latest`, el puente ya se actualiza solo cada vez que el cliente lo
+// arranca. Esto cubre lo demás (una versión fija, el plugin del repo, la extensión .mcpb de Claude Desktop, o un
+// cliente que lleva días abierto): al arrancar se pregunta UNA vez al registro de npm, con un timeout corto y sin
+// bloquear el arranque; si hay una más nueva, la primera respuesta de herramienta lo dice en una línea.
+export const PAQUETE = '@ajuarezso/lienzo-mcp';
+export const COMANDO = `claude mcp add lienzo --scope user -- npx -y ${PAQUETE}@latest`;
+const TIMEOUT_MS = 1500;
+
+/** «0.10.0» > «0.9.3». Solo x.y.z (una prerelease nunca se ofrece como nueva). */
+export function esMasNueva(candidata, actual) {
+  const p = (v) => (/^\d+\.\d+\.\d+$/.test(String(v ?? '')) ? String(v).split('.').map(Number) : null);
+  const a = p(candidata);
+  const b = p(actual);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return false;
+}
+
+/**
+ * La versión `latest` en npm si es más nueva que `actual`; null si no, si no hay red o si tarda más de 1,5 s.
+ * Nunca lanza.
+ */
+export async function versionNueva(actual, { fetch: f = globalThis.fetch, timeoutMs = TIMEOUT_MS, registro = 'https://registry.npmjs.org' } = {}) {
+  try {
+    const r = await f(`${registro}/${PAQUETE.replace('/', '%2F')}/latest`, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!r.ok) return null;
+    const { version } = await r.json();
+    return esMasNueva(version, actual) ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Para pasar de una versión fija (o del comando viejo) a la que se actualiza sola: quitar y volver a agregar. */
+export const COMANDO_REINSTALAR = `claude mcp remove lienzo --scope user && ${COMANDO}`;
+
+/** La línea que va al agente (una vez por proceso). */
+export const avisoDeVersion = (nueva, actual) =>
+  `(Lienzo: hay una versión nueva del puente, ${nueva}; esta es ${actual}. Díselo a tu usuario una vez: si lo instaló con ` +
+  `@latest (o sin versión), se actualiza solo al reiniciar su cliente (en Claude Code, /mcp → lienzo → reconectar); si ` +
+  `tiene una versión fija, que lo reinstale con «${COMANDO_REINSTALAR}» y, si lo tenía con -e (LIENZO_AGENTE, ` +
+  `LIENZO_NOMBRE…), que los repita en el add, antes del --. La extensión de Claude Desktop (.mcpb) no se actualiza sola: ` +
+  `hay que bajar la nueva.)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajuarezso/lienzo-mcp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Servidor MCP de Lienzo: une tu agente (Claude Code u otro cliente MCP) a una sala compartida con los agentes de otras personas. / MCP server that joins your agent to a room shared with other people's agents.",
   "keywords": [
     "mcp",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "test": "node --test test/unit/*.test.mjs",
-    "test:emulador": "cd .. && npx -y firebase-tools emulators:exec --only auth,firestore --project demo-lienzo \"node --test --test-timeout=120000 --test-force-exit mcp/test/emulador/*.test.mjs\"",
+    "test:emulador": "cd .. && npx -y firebase-tools emulators:exec --only auth,firestore,storage --project demo-lienzo \"node --test --test-timeout=120000 --test-force-exit mcp/test/emulador/*.test.mjs\"",
     "e2e:real": "node test/e2e-real.mjs",
     "prepack": "node -e \"require('node:fs').copyFileSync('../firebase.config.json', 'firebase.config.json')\"",
     "postpack": "node -e \"require('node:fs').rmSync('firebase.config.json', { force: true })\""