create-panal-agent 0.11.0 → 0.13.0

package/template/src/salida.ts

@@ -0,0 +1,391 @@
+/**
+ * Devolverle al cliente el archivo que pidió.
+ *
+ * Un agente entrega TEXTO: es lo que se le enseña al cliente y lo que se ancla
+ * en la cadena. Pero mucha gente no quiere texto en una caja, quiere un archivo
+ * que abrir, reenviar o imprimir. Esto convierte lo uno en lo otro.
+ *
+ * QUÉ SE ENTREGA SIGUE SIENDO EL TEXTO. El archivo va ADEMÁS, nunca en lugar
+ * de él: su hash se cuela en la entrega y acaba en la cadena, así que el
+ * cliente puede demostrar que el archivo que se baja es exactamente el que se
+ * le entregó. Sustituir el texto por el archivo rompería eso.
+ *
+ * Y NO SE ADJUNTA SI NO LO PIDIÓ. A varios de estos agentes los llama otro
+ * programa que va a leer la respuesta; colgarle un PDF que nadie va a abrir es
+ * peso y confusión.
+ */
+
+import { textoAPdf } from './pdf.js';
+import { escribirZip } from './zip.js';
+
+export type Formato = 'pdf' | 'docx' | 'xlsx' | 'md' | 'txt' | 'csv' | 'json';
+
+export interface ArchivoDeSalida {
+  name: string;
+  data: Uint8Array | string;
+  mime?: string;
+}
+
+/**
+ * Qué formato pidió, si es que pidió alguno.
+ *
+ * Se mira el ENCARGO, no la respuesta: es donde la persona lo dice. Y se busca
+ * en varios idiomas, porque el mercado no es sólo hispanohablante — un encargo
+ * en inglés que pide «as a Word document» tiene que salir en Word.
+ *
+ * Devuelve `null` cuando no pide nada, que es el caso normal.
+ */
+export function formatoPedido(brief: string): Formato | null {
+  const t = brief.toLowerCase();
+  const mencion: { formato: Formato; en: number }[] = [];
+
+  for (const [formato, patron] of PATRONES) {
+    for (const m of t.matchAll(patron)) mencion.push({ formato, en: m.index });
+  }
+  if (mencion.length === 0) return null;
+
+  // Las que hablan del archivo que ENTRÓ no cuentan. Sin esto, «lee el PDF
+  // adjunto y devuélvemelo en Word» entregaba un PDF: el primer formato que
+  // aparecía era el de la entrada. Pasó en una prueba de punta a punta, que es
+  // donde se ve y no en una frase inventada.
+  const deSalida = mencion.filter((x) => !esDeEntrada(t, x.en));
+  if (deSalida.length === 0) return null;
+
+  // Si alguna viene precedida de un verbo de entrega, ésa es la buena.
+  const pedida = deSalida.find((x) => ENTREGA.test(t.slice(Math.max(0, x.en - 40), x.en)));
+  if (pedida) return pedida.formato;
+
+  // Y si no, la ÚLTIMA: el formato de salida se suele decir al final.
+  return deSalida[deSalida.length - 1]!.formato;
+}
+
+/** Cómo se nombra cada formato, en los idiomas del mercado. */
+const PATRONES: [Formato, RegExp][] = [
+  ['pdf', /\bpdfs?\b/g],
+  ['docx', /\bdocx?\b|\bword\b/g],
+  // «hoja de cálculo» y «spreadsheet» van a Excel, no a CSV: quien lo pide así
+  // quiere abrirlo y sumar, no un archivo de texto con comas.
+  ['xlsx', /\bxlsx?\b|\bexcel\b|hoja de c[aá]lculo|\bspreadsheet\b/g],
+  ['csv', /\bcsvs?\b/g],
+  ['json', /\bjson\b/g],
+  ['md', /\bmarkdown\b|\bmd\b/g],
+  ['txt', /\btxt\b|texto plano|plain text|archivo de texto|text file/g],
+];
+
+/** Que se lo den a uno: lo que distingue pedir un formato de nombrarlo. */
+const ENTREGA =
+  /\b(devu[eé]lve|dame|d[aá]melo|entr[eé]ga|env[ií]a|quiero|genera|crea|exporta|conviert|p[aá]sa|as an?|in|into|return|output|format[oe]?|como)\b[^.]{0,30}$/;
+
+/** Y lo que delata que se habla del archivo que MANDÓ el cliente. */
+const ENTRADA = /\b(adjunt\w*|attach\w*|subid\w*|uploaded|este|esta|el|la|mi|my|the)\b/;
+
+function esDeEntrada(t: string, en: number): boolean {
+  const antes = t.slice(Math.max(0, en - 18), en);
+  const despues = t.slice(en, en + 30);
+  // «el PDF adjunto», «the attached pdf», «mi word»: se habla de lo que entró.
+  return /\badjunt|attach|\bsub[ií]|uploaded|que te (mand|pas|envi)/.test(despues) || (ENTRADA.test(antes) && /\badjunt|attach/.test(despues));
+}
+
+/** La extensión y el tipo de cada formato. */
+const TIPOS: Record<Formato, { ext: string; mime: string }> = {
+  pdf: { ext: 'pdf', mime: 'application/pdf' },
+  docx: {
+    ext: 'docx',
+    mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  },
+  xlsx: {
+    ext: 'xlsx',
+    mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  },
+  md: { ext: 'md', mime: 'text/markdown; charset=utf-8' },
+  txt: { ext: 'txt', mime: 'text/plain; charset=utf-8' },
+  csv: { ext: 'csv', mime: 'text/csv; charset=utf-8' },
+  json: { ext: 'json', mime: 'application/json; charset=utf-8' },
+};
+
+/**
+ * Lo que XML no admite tal cual.
+ *
+ * Los caracteres de control se quitan además de escapar: uno solo hace que
+ * Word se niegue a abrir el archivo ENTERO, sin decir cuál era.
+ */
+function escaparXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, '');
+}
+
+/**
+ * Un `.docx` de verdad, con lo mínimo que Word exige para abrirlo.
+ *
+ * Un .docx es un ZIP con tres archivos dentro. No hace falta ninguna librería:
+ * cada línea del texto es un `<w:p>` y ya está.
+ */
+export function textoADocx(titulo: string, texto: string): Uint8Array {
+  const parrafo = (linea: string, negrita = false): string =>
+    `<w:p><w:r>${negrita ? '<w:rPr><w:b/></w:rPr>' : ''}` +
+    `<w:t xml:space="preserve">${escaparXml(linea)}</w:t></w:r></w:p>`;
+
+  const cuerpo = [parrafo(titulo, true), ...texto.split(/\r?\n/).map((l) => parrafo(l))].join('');
+
+  const documento =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">' +
+    `<w:body>${cuerpo}</w:body></w:document>`;
+
+  const tipos =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+    '<Default Extension="xml" ContentType="application/xml"/>' +
+    '<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>' +
+    '</Types>';
+
+  const rels =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>' +
+    '</Relationships>';
+
+  const b = (s: string): Uint8Array => new TextEncoder().encode(s);
+  return escribirZip([
+    { nombre: '[Content_Types].xml', bytes: b(tipos) },
+    { nombre: '_rels/.rels', bytes: b(rels) },
+    { nombre: 'word/document.xml', bytes: b(documento) },
+  ]);
+}
+
+/**
+ * Cómo está separada una tabla en texto.
+ *
+ * Se decide mirando TODAS las líneas y no la primera: una tabla cuya cabecera
+ * lleva una coma en un título —«Ventas, por región»— haría creer que el
+ * separador es la coma cuando en realidad es el tabulador.
+ */
+function separadorDe(lineas: string[]): '\t' | ',' | null {
+  const conTab = lineas.filter((l) => l.includes('\t')).length;
+  if (conTab >= lineas.length / 2) return '\t';
+  const conComa = lineas.filter((l) => l.includes(',')).length;
+  if (conComa >= lineas.length / 2) return ',';
+  return null;
+}
+
+/** Un CSV puede traer campos entrecomillados con comas dentro. */
+function partirCsv(linea: string): string[] {
+  const campos: string[] = [];
+  let actual = '';
+  let dentro = false;
+  for (let i = 0; i < linea.length; i++) {
+    const c = linea[i]!;
+    if (c === '"') {
+      if (dentro && linea[i + 1] === '"') {
+        actual += '"';
+        i++;
+      } else dentro = !dentro;
+    } else if (c === ',' && !dentro) {
+      campos.push(actual);
+      actual = '';
+    } else actual += c;
+  }
+  campos.push(actual);
+  return campos;
+}
+
+/** `0` → A, `26` → AA. */
+function letraDe(col: number): string {
+  let s = '';
+  let n = col + 1;
+  while (n > 0) {
+    const r = (n - 1) % 26;
+    s = String.fromCharCode(65 + r) + s;
+    n = Math.floor((n - 1) / 26);
+  }
+  return s;
+}
+
+/**
+ * Un `.xlsx` con lo mínimo que Excel exige.
+ *
+ * Los números se escriben COMO NÚMEROS y no como texto. Es la diferencia entre
+ * una hoja con la que se puede sumar y una en la que cada celda lleva el
+ * triangulito verde de «esto parece un número guardado como texto» — que es
+ * justo lo que va a hacer quien pide un Excel: sumar.
+ *
+ * Las cadenas van en línea (`inlineStr`) en vez de en una tabla compartida:
+ * ocupa algo más y ahorra una parte entera del archivo, y aquí el tamaño no es
+ * el problema.
+ */
+export function textoAXlsx(titulo: string, texto: string): Uint8Array {
+  const lineas = texto.split(/\r?\n/).filter((l, i, a) => l !== '' || i < a.length - 1);
+  const sep = separadorDe(lineas);
+  const filas = lineas.map((l) => (sep === ',' ? partirCsv(l) : sep === '\t' ? l.split('\t') : [l]));
+
+  const celdas = (fila: string[], nFila: number): string =>
+    fila
+      .map((valor, col) => {
+        const ref = `${letraDe(col)}${nFila}`;
+        if (valor === '') return '';
+        // Un número es un número; todo lo demás, texto.
+        return /^-?\d+([.,]\d+)?$/.test(valor.trim())
+          ? `<c r="${ref}"><v>${valor.trim().replace(',', '.')}</v></c>`
+          : `<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${escaparXml(valor)}</t></is></c>`;
+      })
+      .join('');
+
+  const sheet =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><sheetData>' +
+    filas.map((f, i) => `<row r="${i + 1}">${celdas(f, i + 1)}</row>`).join('') +
+    '</sheetData></worksheet>';
+
+  const workbook =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" ' +
+    'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">' +
+    `<sheets><sheet name="${escaparXml(titulo).slice(0, 31)}" sheetId="1" r:id="rId1"/></sheets></workbook>`;
+
+  const workbookRels =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>' +
+    '</Relationships>';
+
+  const tipos =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+    '<Default Extension="xml" ContentType="application/xml"/>' +
+    '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+    '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>' +
+    '</Types>';
+
+  const rels =
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>' +
+    '</Relationships>';
+
+  const b = (s: string): Uint8Array => new TextEncoder().encode(s);
+  return escribirZip([
+    { nombre: '[Content_Types].xml', bytes: b(tipos) },
+    { nombre: '_rels/.rels', bytes: b(rels) },
+    { nombre: 'xl/workbook.xml', bytes: b(workbook) },
+    { nombre: 'xl/_rels/workbook.xml.rels', bytes: b(workbookRels) },
+    { nombre: 'xl/worksheets/sheet1.xml', bytes: b(sheet) },
+  ]);
+}
+
+/**
+ * Una tabla, si el texto entregado la lleva dentro.
+ *
+ * Nace de un resultado real y malo: se le pidió a un agente una hoja de
+ * cálculo, entregó su JSON de siempre —correcto— y el Excel salió con UNA
+ * columna de frases, porque el texto no traía ni comas ni tabuladores. Válido
+ * y sin ningún valor: quien pide un Excel quiere columnas para sumarlas.
+ *
+ * Así que antes de montar un xlsx o un csv se mira si lo entregado es JSON con
+ * una lista de objetos planos. Si lo es, sus claves son la cabecera. Si no, se
+ * sigue como antes.
+ */
+export function comoTabla(texto: string): string | null {
+  let dato: unknown;
+  try {
+    dato = JSON.parse(texto);
+  } catch {
+    return null;
+  }
+
+  // La lista puede ser la raíz, o estar dentro bajo cualquier nombre —los
+  // agentes la llaman `hallazgos`, `entries`, `puertos`…
+  const lista = Array.isArray(dato)
+    ? dato
+    : dato && typeof dato === 'object'
+      ? Object.values(dato as Record<string, unknown>).find(
+          (v): v is unknown[] => Array.isArray(v) && v.length > 0,
+        )
+      : undefined;
+  if (!lista || lista.length === 0) return null;
+
+  const filas = lista.filter(
+    (x): x is Record<string, unknown> => !!x && typeof x === 'object' && !Array.isArray(x),
+  );
+  if (filas.length !== lista.length) return null;
+
+  // La cabecera es la unión de las claves, en el orden en que aparecen: una
+  // fila a la que le falte un campo no puede descolocar a las demás.
+  const columnas: string[] = [];
+  for (const f of filas) for (const k of Object.keys(f)) if (!columnas.includes(k)) columnas.push(k);
+  if (columnas.length === 0) return null;
+
+  const celda = (v: unknown): string => {
+    if (v === null || v === undefined) return '';
+    // Un objeto anidado no cabe en una celda; se pone su JSON antes que
+    // «[object Object]», que no le sirve a nadie.
+    if (typeof v === 'object') return JSON.stringify(v);
+    return String(v).replace(/[\t\r\n]+/g, ' ');
+  };
+
+  return [
+    columnas.map((c) => c.replace(/[_-]+/g, ' ')).join('\t'),
+    ...filas.map((f) => columnas.map((c) => celda(f[c])).join('\t')),
+  ].join('\n');
+}
+
+/**
+ * El archivo listo para adjuntar a la entrega.
+ *
+ * `paraLeer` es la versión legible del contenido, y existe por un caso real:
+ * hay agentes cuyo texto entregado es JSON —bueno para una máquina, ilegible
+ * dentro de un PDF—, y ahí se les pasa aparte lo que debe ver una persona. Si
+ * no se da, se usa el texto tal cual.
+ */
+export function comoArchivo(
+  formato: Formato,
+  nombreBase: string,
+  titulo: string,
+  texto: string,
+  paraLeer?: string,
+): ArchivoDeSalida {
+  const { ext, mime } = TIPOS[formato];
+  const name = `${nombreBase}.${ext}`;
+  // Para un Excel o un CSV se busca primero una TABLA dentro de lo entregado:
+  // la versión en prosa daría una sola columna de frases, que es un archivo
+  // válido y sin ningún valor para quien lo pidió para sumar.
+  const tabla = formato === 'xlsx' || formato === 'csv' ? comoTabla(texto) : null;
+  const legible = tabla ?? paraLeer ?? texto;
+
+  switch (formato) {
+    case 'pdf':
+      return { name, data: textoAPdf(titulo, legible), mime };
+    case 'docx':
+      return { name, data: textoADocx(titulo, legible), mime };
+    case 'xlsx':
+      return { name, data: textoAXlsx(titulo, legible), mime };
+    // El markdown lleva el título como encabezado, porque es lo que un `.md`
+    // hace. Los demás van tal cual: un CSV con un `#` delante deja de ser CSV.
+    case 'md':
+      return { name, data: `# ${titulo}\n\n${legible}\n`, mime };
+    case 'csv':
+      // Una tabla en tabuladores se convierte a comas; si no había tabla, el
+      // texto va tal cual, que es lo que ya hacía.
+      return { name, data: tabla ? aCsv(tabla) : texto, mime };
+    default:
+      return { name, data: texto, mime };
+  }
+}
+
+/** Tabuladores a comas, entrecomillando sólo lo que lo necesita. */
+function aCsv(tabla: string): string {
+  return tabla
+    .split('\n')
+    .map((fila) =>
+      fila
+        .split('\t')
+        .map((c) => (/[",\n]/.test(c) ? `"${c.replace(/"/g, '""')}"` : c))
+        .join(','),
+    )
+    .join('\n');
+}

package/template/src/server.ts

@@ -53,6 +53,7 @@ import type { Address } from 'viem';
 import { handleTask } from './agent.js';
 import type { AdjuntoRecibido, TaskContext, TaskFile, TaskResult } from './agent.js';
 import { arrancarVigilante } from './vigilante.js';
+import { historialParaElModelo, recordarTurno, type Turno } from './memoria.js';
 
 const PORT = Number(process.env.PORT ?? 8787);
 const DATA_DIR = process.env.DATA_DIR ?? './data';
@@ -503,6 +504,7 @@ function contexto(
     amount: bigint;
     deadline: bigint;
     adjuntos: AdjuntoRecibido[];
+    historial: Turno[];
   },
   sobre: CallEnvelope | null,
 ): TaskContext {
@@ -568,6 +570,9 @@ async function work(taskId: bigint, brief: string, sobre: CallEnvelope | null):
           amount: task.amount,
           deadline: task.deadline,
           adjuntos: recibidos,
+          // Un encargo del escrow no arrastra conversación: se paga, se
+          // entrega una vez y se aprueba. La memoria es de los chats.
+          historial: [],
         },
         sobre,
       ),
@@ -1045,6 +1050,11 @@ const server = createServer((req, res) => {
               // Una llamada x402 es una pregunta y una respuesta: no hay tarea
               // donde anclar un adjunto, así que tampoco hay adjuntos.
               adjuntos: [],
+              // Lo que ya se habló con ESTA persona. Quién es lo dice el pago:
+              // firmó un permiso y el cobro se ejecutó en la cadena, así que
+              // nadie puede continuar la conversación de otro sin pagar como
+              // él. Por eso no hace falta autenticar nada aquí.
+              historial: historialParaElModelo(DATA_DIR, leido.payment.payer),
             },
             sobre,
           ),
@@ -1062,6 +1072,12 @@ const server = createServer((req, res) => {
         }
         res.setHeader('x-payment-tx', cobro.txHash);
         json(res, 200, { answer, paid: { txHash: cobro.txHash, amount: cobro.amount.toString(), asset: X402_TOKEN } });
+
+        // El turno se guarda AQUÍ, con las dos mitades y sólo si hubo
+        // respuesta. Guardarlo antes de trabajar dejaría preguntas sin
+        // contestar en la memoria, y la siguiente vez el modelo leería una
+        // conversación en la que él se quedó callado.
+        recordarTurno(DATA_DIR, leido.payment.payer, { pregunta: prompt, respuesta: answer, cuando: Date.now() });
       } catch (err) {
         console.error(`[x402] cobrado pero falló al responder: ${err instanceof Error ? err.message : err}`);
         json(res, 502, {

package/template/src/zip.ts

@@ -0,0 +1,245 @@
+/**
+ * Leer un ZIP sin dependencias.
+ *
+ * Hace falta para DOS cosas que parecen distintas y son la misma: una carpeta
+ * que el cliente comprimió, y un `.docx` —que es un ZIP con XML dentro—. Con
+ * un lector se resuelven las dos.
+ *
+ * Node trae `zlib`, que es el 90% del trabajo. Lo que falta es entender la
+ * estructura del archivo, y es poca cosa: se lee el directorio central del
+ * final, no las cabeceras locales, porque el directorio central es el índice
+ * fiable —las locales pueden traer los tamaños a cero y remitir a un
+ * descriptor que va DETRÁS de los datos—.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * ESTO LO MANDA UN DESCONOCIDO Y HAY QUE TRATARLO COMO TAL.
+ *
+ * El ZIP llega de un cliente que pagó, pero pagar no vuelve a nadie de fiar.
+ * Tres defensas, y las tres importan:
+ *
+ *   - Una bomba zip: 42 kB que se descomprimen en petabytes. Se mira el tamaño
+ *     DECLARADO antes de descomprimir y se lleva un total acumulado, así que
+ *     se corta antes de reservar la memoria, no después.
+ *   - Rutas con `..` o absolutas: aquí nada se escribe en disco, pero el
+ *     nombre viaja al modelo y acaba en logs. Se normaliza igual.
+ *   - Un ZIP con cien mil entradas vacías, que no infla memoria pero sí tiempo.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+
+import { inflateRawSync } from 'node:zlib';
+
+/** Un archivo dentro del ZIP, ya descomprimido. */
+export interface EntradaZip {
+  /** La ruta dentro del ZIP, ya normalizada. */
+  nombre: string;
+  bytes: Uint8Array;
+}
+
+export interface LimitesZip {
+  /** Cuántas entradas se miran como mucho. */
+  maxEntradas: number;
+  /** Tope del total descomprimido, sumando todas. */
+  maxTotalBytes: number;
+  /** Tope de una sola entrada. */
+  maxEntradaBytes: number;
+}
+
+export const LIMITES_ZIP: LimitesZip = {
+  maxEntradas: 200,
+  maxTotalBytes: 32 * 1024 * 1024,
+  maxEntradaBytes: 8 * 1024 * 1024,
+};
+
+/** Los cuatro bytes con los que empieza todo ZIP (y todo .docx, .xlsx, .odt). */
+export function esZip(bytes: Uint8Array): boolean {
+  return bytes.length > 4 && bytes[0] === 0x50 && bytes[1] === 0x4b && bytes[2] === 0x03 && bytes[3] === 0x04;
+}
+
+const u16 = (b: Uint8Array, i: number): number => b[i]! | (b[i + 1]! << 8);
+const u32 = (b: Uint8Array, i: number): number =>
+  (b[i]! | (b[i + 1]! << 8) | (b[i + 2]! << 16) | (b[i + 3]! << 24)) >>> 0;
+
+/**
+ * Quita lo que haría daño de una ruta interna.
+ *
+ * No se escribe nada en disco, así que esto no evita un escape de directorio:
+ * evita que un nombre inventado —`../../etc/passwd`— llegue al modelo y a los
+ * logs como si fuera un archivo de verdad del cliente.
+ */
+function rutaLimpia(nombre: string): string {
+  return nombre
+    .replace(/\\/g, '/')
+    .split('/')
+    .filter((p) => p && p !== '.' && p !== '..')
+    .join('/')
+    .slice(0, 200);
+}
+
+/** Dónde empieza el directorio central. Se busca desde el final. */
+function buscarDirectorio(b: Uint8Array): number | null {
+  // El comentario final puede ocupar hasta 64 kB, así que no basta con mirar
+  // los últimos 22 bytes.
+  const desde = Math.max(0, b.length - 22 - 0xffff);
+  for (let i = b.length - 22; i >= desde; i--) {
+    if (u32(b, i) === 0x06054b50) return u32(b, i + 16);
+  }
+  return null;
+}
+
+/**
+ * Los archivos de un ZIP, descomprimidos y acotados.
+ *
+ * Las carpetas y las entradas vacías se saltan solas: lo que interesa es el
+ * contenido. Una entrada que no se puede descomprimir se OMITE en vez de
+ * tumbar la lectura entera — un ZIP con un archivo roto sigue teniendo diez
+ * buenos, y el cliente ya pagó por que se mire lo que sí se puede.
+ */
+export function leerZip(datos: Uint8Array, limites: LimitesZip = LIMITES_ZIP): EntradaZip[] {
+  const inicio = buscarDirectorio(datos);
+  if (inicio === null || inicio >= datos.length) return [];
+
+  const salida: EntradaZip[] = [];
+  let total = 0;
+  let cursor = inicio;
+
+  while (cursor + 46 <= datos.length && u32(datos, cursor) === 0x02014b50) {
+    const metodo = u16(datos, cursor + 10);
+    const comprimido = u32(datos, cursor + 20);
+    const sinComprimir = u32(datos, cursor + 24);
+    const nLargo = u16(datos, cursor + 28);
+    const extraLargo = u16(datos, cursor + 30);
+    const comentarioLargo = u16(datos, cursor + 32);
+    const offsetLocal = u32(datos, cursor + 42);
+    const nombre = rutaLimpia(new TextDecoder().decode(datos.subarray(cursor + 46, cursor + 46 + nLargo)));
+
+    cursor += 46 + nLargo + extraLargo + comentarioLargo;
+
+    if (salida.length >= limites.maxEntradas) break;
+    // El tamaño se comprueba ANTES de descomprimir: es lo único que separa
+    // esto de reservar los petabytes que la bomba pide.
+    if (!nombre || sinComprimir === 0) continue;
+    if (sinComprimir > limites.maxEntradaBytes) continue;
+    if (total + sinComprimir > limites.maxTotalBytes) break;
+
+    // Ahora sí hay que mirar la cabecera local, sólo para saber dónde
+    // empiezan los datos: su longitud de extra puede ser distinta de la del
+    // directorio central, y darlo por hecho desplaza la lectura.
+    if (offsetLocal + 30 > datos.length || u32(datos, offsetLocal) !== 0x04034b50) continue;
+    const datosEn = offsetLocal + 30 + u16(datos, offsetLocal + 26) + u16(datos, offsetLocal + 28);
+    if (datosEn + comprimido > datos.length) continue;
+    const crudo = datos.subarray(datosEn, datosEn + comprimido);
+
+    try {
+      const bytes = metodo === 0 ? crudo : metodo === 8 ? new Uint8Array(inflateRawSync(crudo)) : null;
+      if (!bytes) continue;
+      total += bytes.length;
+      salida.push({ nombre, bytes });
+    } catch {
+      // Entrada corrupta o cifrada: se omite y se sigue con las demás.
+      continue;
+    }
+  }
+
+  return salida;
+}
+
+/* ══════════════════════════════════════════════════════════════════════════
+ * ESCRIBIR
+ *
+ * Hace falta para devolver un `.docx`, que es un ZIP con XML dentro. El mismo
+ * formato que se lee arriba, al revés.
+ * ══════════════════════════════════════════════════════════════════════════ */
+
+import { deflateRawSync } from 'node:zlib';
+
+/** CRC-32, que el ZIP exige por entrada. Tabla al vuelo: son 256 valores. */
+function crc32(bytes: Uint8Array): number {
+  let c: number;
+  const tabla: number[] = [];
+  for (let n = 0; n < 256; n++) {
+    c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    tabla[n] = c >>> 0;
+  }
+  let crc = 0xffffffff;
+  for (const b of bytes) crc = tabla[(crc ^ b) & 0xff]! ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function escribirU16(v: number): number[] {
+  return [v & 0xff, (v >>> 8) & 0xff];
+}
+function escribirU32(v: number): number[] {
+  return [v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff];
+}
+
+/**
+ * Monta un ZIP.
+ *
+ * Se comprime todo con deflate. Sin fecha real —se pone la del epoch de MS-DOS
+ * y ya— porque un archivo que cambia de bytes cada vez que se genera rompe una
+ * propiedad que aquí importa: el hash de la entrega se ancla en la cadena, y
+ * generar dos veces lo mismo tiene que dar exactamente lo mismo.
+ */
+export function escribirZip(entradas: { nombre: string; bytes: Uint8Array }[]): Uint8Array {
+  const local: number[] = [];
+  const central: number[] = [];
+  let offset = 0;
+
+  for (const e of entradas) {
+    const nombre = [...new TextEncoder().encode(e.nombre)];
+    const comprimido = [...new Uint8Array(deflateRawSync(e.bytes))];
+    const crc = crc32(e.bytes);
+
+    const cabecera = [
+      ...escribirU32(0x04034b50),
+      ...escribirU16(20), // versión mínima
+      ...escribirU16(0),
+      ...escribirU16(8), // deflate
+      ...escribirU16(0), // hora
+      ...escribirU16(0x21), // fecha: 1980-01-01
+      ...escribirU32(crc),
+      ...escribirU32(comprimido.length),
+      ...escribirU32(e.bytes.length),
+      ...escribirU16(nombre.length),
+      ...escribirU16(0),
+      ...nombre,
+    ];
+    local.push(...cabecera, ...comprimido);
+
+    central.push(
+      ...escribirU32(0x02014b50),
+      ...escribirU16(20), // versión que lo creó
+      ...escribirU16(20),
+      ...escribirU16(0),
+      ...escribirU16(8),
+      ...escribirU16(0),
+      ...escribirU16(0x21),
+      ...escribirU32(crc),
+      ...escribirU32(comprimido.length),
+      ...escribirU32(e.bytes.length),
+      ...escribirU16(nombre.length),
+      ...escribirU16(0),
+      ...escribirU16(0), // comentario
+      ...escribirU16(0), // disco
+      ...escribirU16(0), // atributos internos
+      ...escribirU32(0), // atributos externos
+      ...escribirU32(offset),
+      ...nombre,
+    );
+    offset += cabecera.length + comprimido.length;
+  }
+
+  const fin = [
+    ...escribirU32(0x06054b50),
+    ...escribirU16(0),
+    ...escribirU16(0),
+    ...escribirU16(entradas.length),
+    ...escribirU16(entradas.length),
+    ...escribirU32(central.length),
+    ...escribirU32(local.length),
+    ...escribirU16(0),
+  ];
+
+  return new Uint8Array([...local, ...central, ...fin]);
+}