create-panal-agent 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Crea un agente de IA para Panal, funcionando y cobrando on-chain, en cinco minutos",
   "type": "module",
   "license": "MIT",
@@ -30,9 +30,11 @@
     "node": ">=20"
   },
   "devDependencies": {
-    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "@types/node": "^22.0.0"
+    "typescript": "^5.6.0",
+    "unpdf": "^1.8.1",
+    "xlsx": "^0.18.5"
   },
   "dependencies": {
     "viem": "^2.21.0"
@@ -40,6 +42,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/i18n.test.ts && tsx test/memoria.test.ts && tsx test/reintento.test.ts && tsx test/scaffold.test.ts"
+    "test": "tsx test/i18n.test.ts && tsx test/memoria.test.ts && tsx test/reintento.test.ts && tsx test/zip.test.ts && tsx test/adjuntos.test.ts && tsx test/salida.test.ts && tsx test/scaffold.test.ts"
   }
 }

package/template/_package.json

@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@panal/sdk": "^0.13.0",
+    "unpdf": "^1.8.1",
     "dotenv": "^17.0.0",
     "tsx": "^4.19.0",
     "viem": "^2.21.0"

package/template/src/adjuntos.ts

@@ -0,0 +1,359 @@
+/**
+ * Lo que el cliente adjuntó, convertido en algo que un modelo pueda usar.
+ *
+ * Un encargo puede traer cinco archivos de hasta 25 MB, y llegan verificados:
+ * su hash se anunció DENTRO del encargo antes de que se pagara, así que son
+ * exactamente los que el escrow cubre. Lo que hace este archivo es la otra
+ * mitad: abrirlos.
+ *
+ * Cada tipo entra por donde puede:
+ *
+ *   imagen (png/jpeg/gif/webp)  se le ENSEÑA al modelo, no se describe
+ *   texto (código, md, csv…)    tal cual
+ *   PDF                         se le extrae el texto
+ *   .docx                       es un ZIP con XML dentro
+ *   .zip                        se abre y se leen los que sí se puedan
+ *   cualquier otra cosa         se NOMBRA, y se dice que no se pudo abrir
+ *
+ * ESE ÚLTIMO CASO NO ES UN DESCUIDO. Callar un archivo que no se pudo abrir
+ * hace que el modelo conteste como si el cliente no hubiera mandado nada, y el
+ * cliente recibe una respuesta que ignora la mitad de lo que pidió sin decir
+ * por qué. Decirlo cuesta una línea y convierte un fallo en una explicación.
+ *
+ * EL TIPO SE MIRA POR LOS BYTES, no por el nombre ni por el `content-type` que
+ * mandó el cliente: los dos los escribe él, y un `.txt` que en realidad es un
+ * PDF es un accidente normal, no un ataque.
+ */
+
+import { esZip, leerZip } from './zip.js';
+
+export interface AdjuntoRecibido {
+  name: string;
+  mime?: string;
+  bytes: Uint8Array;
+}
+
+/** Una imagen lista para enseñársela al modelo. */
+export interface ImagenAdjunta {
+  mime: string;
+  bytes: Uint8Array;
+}
+
+export interface AdjuntosLeidos {
+  /** Ya etiquetado y listo para pegar al encargo. Vacío si no hay nada. */
+  texto: string;
+  /** Las que el modelo puede mirar de verdad. */
+  imagenes: ImagenAdjunta[];
+}
+
+/** Tope de caracteres que aporta UN adjunto. El encargo lo paga el agente. */
+const MAX_CHARS_POR_ADJUNTO = 8_000;
+/** Y el de todos juntos, porque cinco archivos al tope son demasiado. */
+const MAX_CHARS_TOTAL = 24_000;
+/** Archivos que se miran dentro de un ZIP. */
+const MAX_DENTRO_DEL_ZIP = 40;
+
+const MIMES_IMAGEN: Record<string, string> = {
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+};
+
+/** Qué es esto, mirando los primeros bytes. */
+export function tipoDe(bytes: Uint8Array): 'png' | 'jpeg' | 'gif' | 'webp' | 'pdf' | 'zip' | 'otro' {
+  const b = bytes;
+  if (b.length < 4) return 'otro';
+  if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return 'png';
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpeg';
+  if (b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46) return 'gif';
+  if (b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[8] === 0x57 && b[9] === 0x45) return 'webp';
+  // El %PDF- puede venir tras unos bytes de basura; el estándar tolera hasta
+  // 1024, y hay generadores que se aprovechan.
+  const cabeza = new TextDecoder('latin1').decode(b.subarray(0, Math.min(1024, b.length)));
+  if (cabeza.includes('%PDF-')) return 'pdf';
+  if (esZip(b)) return 'zip';
+  return 'otro';
+}
+
+/**
+ * ¿Esto es texto?
+ *
+ * Se decodifica en modo estricto, así un binario LANZA en vez de colarse como
+ * un reguero de caracteres de reemplazo. Y aun decodificando bien, se rechaza
+ * lo que trae bytes de control: hay binarios que pasan por UTF-8 válido y
+ * mandárselos a un modelo es gastar el encargo en basura.
+ */
+export function comoTexto(bytes: Uint8Array): string | null {
+  try {
+    const texto = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    for (const ch of texto) {
+      const c = ch.codePointAt(0)!;
+      if (c < 0x20 && c !== 0x0a && c !== 0x0d && c !== 0x09) return null;
+    }
+    return texto;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * El texto de un `.docx`.
+ *
+ * Un .docx es un ZIP con `word/document.xml` dentro. No hace falta entender
+ * Word: cada `</w:p>` cierra un párrafo y cada `<w:t>` envuelve un trozo de
+ * texto. Se quitan las etiquetas y quedan las palabras.
+ *
+ * Los `<w:t>` se conservan PEGADOS entre sí a propósito: Word parte una misma
+ * frase en varios cuando cambia algo del formato, y meter espacios entre ellos
+ * escribiría «contra tante» donde pone «contratante».
+ */
+export function textoDeDocx(bytes: Uint8Array): string | null {
+  const doc = leerZip(bytes).find((e) => e.nombre === 'word/document.xml');
+  if (!doc) return null;
+  const xml = comoTexto(doc.bytes);
+  if (!xml) return null;
+  return xml
+    .replace(/<w:p\b[^>]*\/>/g, '\n')
+    .replace(/<\/w:p>/g, '\n')
+    .replace(/<w:tab\b[^>]*\/>/g, '\t')
+    .replace(/<w:br\b[^>]*\/>/g, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/** `A1` → 0, `B1` → 1, `AA7` → 26. Sirve para no descolocar una fila con huecos. */
+function columnaDe(ref: string): number {
+  const letras = /^([A-Z]+)/.exec(ref.toUpperCase())?.[1];
+  if (!letras) return 0;
+  let n = 0;
+  for (const c of letras) n = n * 26 + (c.charCodeAt(0) - 64);
+  return n - 1;
+}
+
+/** Lo que el XML trae escapado, de vuelta a texto. */
+function desescapar(s: string): string {
+  return s
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, d: string) => String.fromCodePoint(Number(d)))
+    .replace(/&amp;/g, '&');
+}
+
+/**
+ * El contenido de un `.xlsx`, como filas de texto.
+ *
+ * Un Excel es otro ZIP con XML, como el .docx, pero con una vuelta de tuerca:
+ * las celdas de texto no suelen guardar el texto. Guardan un ÍNDICE a
+ * `sharedStrings.xml`, donde cada cadena aparece una sola vez aunque se repita
+ * en mil celdas. Sin resolver esa tabla, una hoja llena de nombres se lee como
+ * una lista de números.
+ *
+ * Y hay cuatro maneras de que una celda tenga texto, según quién escribiera el
+ * archivo: `t="s"` (la tabla), `t="str"` (resultado de fórmula), `t="inlineStr"`
+ * (el texto ahí mismo) y sin `t` (un número). Se contemplan las cuatro porque
+ * Excel, LibreOffice y las librerías no escogen la misma.
+ *
+ * Las filas salen separadas por tabuladores: es lo que un modelo lee como
+ * tabla sin tener que adivinar dónde acaba una celda, y no exige entrecomillar
+ * nada.
+ */
+export function textoDeXlsx(bytes: Uint8Array): string | null {
+  const partes = leerZip(bytes);
+  const hojas = partes
+    .filter((e) => /^xl\/worksheets\/sheet\d*\.xml$/.test(e.nombre))
+    .sort((a, b) => a.nombre.localeCompare(b.nombre));
+  if (hojas.length === 0) return null;
+
+  // La tabla de cadenas compartidas, si la hay.
+  const compartidas: string[] = [];
+  const tabla = partes.find((e) => e.nombre === 'xl/sharedStrings.xml');
+  if (tabla) {
+    const xml = comoTexto(tabla.bytes) ?? '';
+    for (const si of xml.match(/<si>[\s\S]*?<\/si>/g) ?? []) {
+      // Una cadena puede venir partida en varios <t> cuando lleva formato
+      // dentro; se pegan sin separador, como en Word.
+      compartidas.push(desescapar([...si.matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((m) => m[1] ?? '').join('')));
+    }
+  }
+
+  const salida: string[] = [];
+  for (const hoja of hojas) {
+    const xml = comoTexto(hoja.bytes);
+    if (!xml) continue;
+    const filas: string[] = [];
+
+    for (const fila of xml.match(/<row[^>]*>[\s\S]*?<\/row>/g) ?? []) {
+      const celdas: string[] = [];
+      for (const m of fila.matchAll(/<c\b([^>]*)>([\s\S]*?)<\/c>/g)) {
+        const attrs = m[1] ?? '';
+        const cuerpo = m[2] ?? '';
+        const tipo = /\bt="([^"]+)"/.exec(attrs)?.[1];
+        const ref = /\br="([^"]+)"/.exec(attrs)?.[1] ?? '';
+
+        let valor = '';
+        if (tipo === 'inlineStr') {
+          valor = desescapar([...cuerpo.matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((x) => x[1] ?? '').join(''));
+        } else {
+          const v = /<v[^>]*>([\s\S]*?)<\/v>/.exec(cuerpo)?.[1] ?? '';
+          if (tipo === 's') valor = compartidas[Number(v)] ?? '';
+          else if (tipo === 'b') valor = v === '1' ? 'VERDADERO' : 'FALSO';
+          else valor = desescapar(v);
+        }
+
+        // Una fila puede saltarse columnas: `A1` y luego `D1`. Colocar cada
+        // valor en SU columna es lo que evita que una tabla con huecos salga
+        // desplazada y el modelo lea el dato de otra cabecera.
+        const col = ref ? columnaDe(ref) : celdas.length;
+        while (celdas.length < col) celdas.push('');
+        celdas[col] = valor;
+      }
+      if (celdas.some((c) => c !== '')) filas.push(celdas.join('\t'));
+    }
+
+    if (filas.length > 0) {
+      salida.push(hojas.length > 1 ? `[hoja ${salida.length + 1}]\n${filas.join('\n')}` : filas.join('\n'));
+    }
+  }
+
+  return salida.length > 0 ? salida.join('\n\n') : null;
+}
+
+/**
+ * El texto de un PDF.
+ *
+ * Se apoya en `unpdf`, que es el motor de pdf.js empaquetado. Se hizo así tras
+ * medir: un extractor a mano lee bien los PDF que genera este mismo agente y
+ * se atraganta con los de Word o Chrome, que son justo los que manda un
+ * cliente. Las codificaciones de fuente son el problema, y resolverlas es lo
+ * que hace pdf.js.
+ *
+ * Devuelve null si no sale texto: un PDF escaneado es una imagen dentro de un
+ * PDF, y sin OCR no hay nada que leer. Decirlo es mejor que entregar el vacío.
+ */
+export async function textoDePdf(bytes: Uint8Array): Promise<string | null> {
+  try {
+    const { extractText, getDocumentProxy } = await import('unpdf');
+    const doc = await getDocumentProxy(bytes);
+    const { text } = await extractText(doc, { mergePages: true });
+    const limpio = (Array.isArray(text) ? text.join('\n') : text).trim();
+    return limpio.length > 0 ? limpio : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Recorta y avisa de que ha recortado, que es lo que evita una cita a medias. */
+function acotar(texto: string, tope: number): string {
+  if (texto.length <= tope) return texto;
+  return `${texto.slice(0, tope)}\n--- (recortado: son ${texto.length} caracteres) ---`;
+}
+
+/**
+ * Abre todos los adjuntos de un encargo.
+ *
+ * Es `async` porque leer un PDF lo es. Los agentes ya trabajaban en `async`,
+ * así que lo único que cambia para quien llama es un `await`.
+ */
+export async function leerAdjuntos(adjuntos: AdjuntoRecibido[]): Promise<AdjuntosLeidos> {
+  const partes: string[] = [];
+  const imagenes: ImagenAdjunta[] = [];
+  let gastado = 0;
+
+  const anadir = (cabecera: string, cuerpo: string): void => {
+    const queda = MAX_CHARS_TOTAL - gastado;
+    if (queda <= 200) return;
+    const trozo = acotar(cuerpo, Math.min(MAX_CHARS_POR_ADJUNTO, queda));
+    gastado += trozo.length;
+    partes.push(`--- ${cabecera} ---\n${trozo}\n--- fin ---`);
+  };
+
+  const noSePudo = (a: AdjuntoRecibido, motivo: string): void => {
+    partes.push(
+      `[Archivo adjunto "${a.name}"${a.mime ? ` (${a.mime})` : ''}: ${motivo}. ` +
+        `Dilo con claridad en la respuesta en vez de ignorarlo.]`,
+    );
+  };
+
+  for (const a of adjuntos) {
+    const tipo = tipoDe(a.bytes);
+
+    if (tipo in MIMES_IMAGEN) {
+      // La imagen no se describe: se le enseña. El agente decide si su modelo
+      // puede mirarla; aquí sólo se separa de lo que es texto.
+      imagenes.push({ mime: MIMES_IMAGEN[tipo]!, bytes: a.bytes });
+      partes.push(`[Imagen adjunta "${a.name}": va con este mensaje, míralo.]`);
+      continue;
+    }
+
+    if (tipo === 'pdf') {
+      const texto = await textoDePdf(a.bytes);
+      if (texto) anadir(`PDF adjunto: ${a.name}`, texto);
+      else noSePudo(a, 'es un PDF del que no se pudo sacar texto (probablemente escaneado)');
+      continue;
+    }
+
+    if (tipo === 'zip') {
+      // Word y Excel son ZIPs también, así que se prueban antes de tratarlo
+      // como una carpeta: leer un .xlsx entrada por entrada devolvería su XML
+      // en crudo, que para un modelo es ruido caro.
+      const docx = textoDeDocx(a.bytes);
+      if (docx) {
+        anadir(`Documento adjunto: ${a.name}`, docx);
+        continue;
+      }
+      const xlsx = textoDeXlsx(a.bytes);
+      if (xlsx) {
+        anadir(`Hoja de cálculo adjunta (columnas separadas por tabulador): ${a.name}`, xlsx);
+        continue;
+      }
+      // Un ZIP normal: una carpeta. Se leen los que sí sean texto y se
+      // NOMBRAN los que no, para que el modelo sepa qué había dentro.
+      const dentro = leerZip(a.bytes).slice(0, MAX_DENTRO_DEL_ZIP);
+      if (dentro.length === 0) {
+        noSePudo(a, 'es un archivo comprimido que no se pudo abrir');
+        continue;
+      }
+      const ilegibles: string[] = [];
+      for (const e of dentro) {
+        const texto = comoTexto(e.bytes);
+        if (texto === null) ilegibles.push(e.nombre);
+        else anadir(`${a.name} → ${e.nombre}`, texto);
+      }
+      if (ilegibles.length > 0) {
+        partes.push(`[Dentro de "${a.name}" hay ${ilegibles.length} archivo(s) que no son texto: ${ilegibles.join(', ')}.]`);
+      }
+      continue;
+    }
+
+    const texto = comoTexto(a.bytes);
+    if (texto !== null) anadir(`Archivo adjunto: ${a.name}`, texto);
+    else noSePudo(a, 'no es texto y este agente no puede abrirlo');
+  }
+
+  return { texto: partes.join('\n\n'), imagenes };
+}
+
+/**
+ * La imagen en el formato que espera `/chat/completions`.
+ *
+ * Vive aquí y no en cada agente porque los cuatro la necesitan igual, y una
+ * data-url mal montada falla con un error del proveedor que no dice nada.
+ */
+export function parteDeImagen(img: ImagenAdjunta): {
+  type: 'image_url';
+  image_url: { url: string };
+} {
+  return {
+    type: 'image_url',
+    image_url: { url: `data:${img.mime};base64,${Buffer.from(img.bytes).toString('base64')}` },
+  };
+}

package/template/src/agent.ts

@@ -11,19 +11,18 @@
  * anclado en la cadena al entregar. Si luego sirves otra cosa, se nota.
  */
 
-import { esImagenSoportada, llmChat, resolverLlm, type CallEnvelope, type LlmConfig } from '@panal/sdk';
-import { textoAPdf } from './pdf.js';
+import { llmChat, resolverLlm, type CallEnvelope, type LlmConfig } from '@panal/sdk';
+import { leerAdjuntos, type AdjuntoRecibido, type AdjuntosLeidos } from './adjuntos.js';
+import { comoArchivo, formatoPedido } from './salida.js';
 import { historialComoTexto, type Turno } from './memoria.js';
 
-/** Un archivo que el CLIENTE te mandó con el encargo. */
-export interface AdjuntoRecibido {
-  /** Nombre ya limpio, tal y como lo anunció el encargo. */
-  name: string;
-  /** Tipo MIME, si lo declaró: `image/png`, `application/pdf`… */
-  mime?: string;
-  /** El contenido. Su hash ya se comprobó contra lo que la cadena cubre. */
-  bytes: Uint8Array;
-}
+/**
+ * Un archivo que el CLIENTE te mandó con el encargo.
+ *
+ * El tipo vive en `adjuntos.js`, que es quien sabe abrirlos; se reexporta aquí
+ * para tenerlo a mano sin salir de este archivo.
+ */
+export type { AdjuntoRecibido };
 
 export interface TaskContext {
   /**
@@ -45,8 +44,11 @@ export interface TaskContext {
    * pagara, así que estos bytes son exactamente los que la cadena cubre — si
    * alguien hubiera cambiado uno por el camino, no habría llegado hasta aquí.
    *
-   * Las imágenes se le pasan solas al modelo, si el tuyo sabe mirarlas. El
-   * resto lo tienes aquí en crudo para hacer lo que sepas hacer con ello.
+   * El motor los ABRE por ti antes de llamarte: las imágenes se le enseñan al
+   * modelo, y de un PDF, un Word, un Excel o una carpeta comprimida se saca el
+   * texto y entra en el encargo. Lo que no se pueda abrir se le NOMBRA al
+   * modelo en vez de callarlo. Aquí los tienes en crudo por si tu agente sabe
+   * hacer algo más con ellos.
    *
    * Vacío en una llamada x402: ahí no hay tarea donde anclar un adjunto.
    */
@@ -174,14 +176,12 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     );
   }
 
-  // Lo que el cliente adjuntó y un modelo puede MIRAR. El resto de adjuntos
-  // sigue en `ctx.adjuntos` para que hagas con ellos lo que sepas hacer.
-  const imagenes = ctx.adjuntos
-    .filter((a) => esImagenSoportada(a.mime))
-    .map((a) => ({ mime: a.mime!, bytes: a.bytes }));
+  // Se abre TODO lo que mandó el cliente: imágenes para que las mire el
+  // modelo, y el texto de los PDF, Word, Excel y carpetas que vengan dentro.
+  const leido = await leerAdjuntos(ctx.adjuntos);
   if (ctx.adjuntos.length > 0) {
     console.log(
-      `[agente] ${etiqueta(ctx)} ${ctx.adjuntos.length} adjunto(s), ${imagenes.length} para el modelo: ` +
+      `[agente] ${etiqueta(ctx)} ${ctx.adjuntos.length} adjunto(s), ${leido.imagenes.length} para el modelo: ` +
         ctx.adjuntos.map((a) => a.name).join(', '),
     );
   }
@@ -195,11 +195,11 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
   // que entregues queda anclado en la cadena y ya no se puede rectificar.
   let queja: string | null = null;
   for (let intento = 1; intento <= 2; intento++) {
-    const texto = await pedirAlModelo(brief, cfg, queja, ayuda, imagenes, ctx.adjuntos, ctx.historial);
+    const texto = await pedirAlModelo(brief, cfg, queja, ayuda, leido, ctx.historial);
     const problema = revisar(brief, texto);
     if (!problema) {
       console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
-      return conPdfSiLoPidio(brief, texto, ctx);
+      return conArchivoSiLoPidio(brief, texto, ctx);
     }
     console.error(`[agente] ${etiqueta(ctx)} intento ${intento}: ${problema}`);
     // A la segunda se entrega igual. Tu revisión puede equivocarse, y un falso
@@ -207,7 +207,7 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     // entregar algo imperfecto y que él decida, que dejarlo sin nada.
     if (intento === 2) {
       console.error(`[agente] ${etiqueta(ctx)} se entrega pese a: ${problema}`);
-      return conPdfSiLoPidio(brief, texto, ctx);
+      return conArchivoSiLoPidio(brief, texto, ctx);
     }
     queja = problema;
   }
@@ -372,11 +372,15 @@ function revisar(brief: string, resultado: string): string | null {
  * lo ancla en la cadena, así que el cliente puede demostrar que el archivo que
  * se baja es exactamente el que le entregaste.
  */
-function conPdfSiLoPidio(brief: string, texto: string, ctx: TaskContext): TaskResult {
-  if (!/\bpdf\b/i.test(brief)) return texto;
-  const pdf = textoAPdf(`Panal - entrega ${etiqueta(ctx)}`, texto);
-  console.log(`[agente] ${etiqueta(ctx)} PDF de ${pdf.byteLength} bytes adjunto`);
-  return { text: texto, files: [{ name: 'entrega.pdf', data: pdf, mime: 'application/pdf' }] };
+function conArchivoSiLoPidio(brief: string, texto: string, ctx: TaskContext): TaskResult {
+  const formato = formatoPedido(brief);
+  if (!formato) return texto;
+  const archivo = comoArchivo(formato, 'entrega', `Panal - entrega ${etiqueta(ctx)}`, texto);
+  const bytes = typeof archivo.data === 'string' ? archivo.data.length : archivo.data.byteLength;
+  console.log(`[agente] ${etiqueta(ctx)} ${archivo.name} de ${bytes} bytes adjunto`);
+  // El TEXTO se sigue entregando: es lo que se ancla en la cadena. El archivo
+  // va además, y su hash viaja dentro de la entrega.
+  return { text: texto, files: [archivo] };
 }
 
 async function pedirAlModelo(
@@ -384,8 +388,7 @@ async function pedirAlModelo(
   cfg: LlmConfig,
   queja: string | null,
   ayuda: string | null,
-  imagenes: { mime: string; bytes: Uint8Array }[],
-  adjuntos: AdjuntoRecibido[],
+  leido: AdjuntosLeidos,
   historial: Turno[],
 ): Promise<string> {
   // Todo va en un solo turno de usuario, con cada parte etiquetada. Los tres
@@ -404,17 +407,11 @@ async function pedirAlModelo(
 
   partes.push(historial.length > 0 ? `Ahora te pide:\n${brief}` : brief);
 
-  // Los adjuntos que el modelo NO puede mirar. Se nombran para que sepa que
-  // existen: sin esto contesta como si el cliente no hubiera mandado nada, y
-  // el cliente ve una respuesta que ignora la mitad de lo que pidió.
-  const noMirables = adjuntos.filter((a) => !imagenes.some((i) => i.bytes === a.bytes));
-  if (noMirables.length > 0) {
-    partes.push(
-      `[El cliente adjuntó estos archivos, que no puedes abrir: ${noMirables
-        .map((a) => `${a.name}${a.mime ? ` (${a.mime})` : ''}`)
-        .join(', ')}. El agente los tiene y los procesa aparte.]`,
-    );
-  }
+  // Lo que se pudo sacar de los adjuntos, ya etiquetado: el texto de un PDF,
+  // las filas de un Excel, los archivos de una carpeta. Y lo que NO se pudo
+  // abrir, nombrado — callarlo hace que el modelo conteste como si el cliente
+  // no hubiera mandado nada.
+  if (leido.texto) partes.push(leido.texto);
 
   // Lo que contestó el especialista, si se le preguntó. Va marcado como
   // material de apoyo y no como parte del encargo: sin esa aclaración el
@@ -465,7 +462,7 @@ async function pedirAlModelo(
         'say you cannot make them. This does NOT apply to images the client sent you: those you can ' +
         'and should refer to, because the client knows they sent them.',
       user: partes.join('\n\n'),
-      ...(imagenes.length > 0 ? { imagenes } : {}),
+      ...(leido.imagenes.length > 0 ? { imagenes: leido.imagenes } : {}),
     },
   );
 }

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/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]);
+}