create-panal-agent 0.11.0 → 0.13.0

package/template/src/agent.ts

@@ -11,18 +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 {
   /**
@@ -44,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.
    */
@@ -85,6 +88,23 @@ export interface TaskContext {
    * `consultar` ya lo respeta por su cuenta.
    */
   envelope: CallEnvelope | null;
+
+  /**
+   * LO QUE YA SE HABLÓ CON ESTA PERSONA.
+   *
+   * Sólo en llamadas x402, que son las que forman una conversación. En un
+   * encargo del escrow va vacío: un encargo tiene principio y fin, y
+   * arrastrarle memoria sería confundir dos cosas distintas.
+   *
+   * Quién es "esta persona" lo dice el PAGO, no una cabecera: firmó un permiso
+   * y el cobro se ejecutó en la cadena, así que nadie puede continuar la
+   * conversación de otro sin haber pagado como él.
+   *
+   * Va acotado por turnos y por caracteres (`MEMORIA_TURNOS`, `MEMORIA_CHARS`)
+   * porque entra en el prompt, y el prompt lo pagas TÚ mientras el cliente
+   * paga un precio fijo por mensaje.
+   */
+  historial: Turno[];
 }
 
 /** Un archivo que entregas junto al texto. */
@@ -156,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(', '),
     );
   }
@@ -177,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);
+    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
@@ -189,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;
   }
@@ -354,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(
@@ -366,27 +388,31 @@ 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
   // dialectos aceptan varios turnos, pero cada uno los cuenta a su manera, y
   // lo que aquí importa no es de quién es cada mensaje: es que el modelo no
   // confunda el material de apoyo con el encargo.
-  const partes = [brief];
+  const partes: string[] = [];
 
-  // 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 hablado antes va PRIMERO y marcado como tal. Sin la etiqueta, el modelo
+  // confunde una pregunta vieja con la de ahora y contesta a la equivocada;
+  // con ella entiende que es contexto y que lo último es lo que se le pide.
+  const antes = historialComoTexto(historial);
+  if (antes) {
+    partes.push(`Conversación anterior con este cliente, para que sepas de qué habláis:\n\n${antes}`);
   }
 
+  partes.push(historial.length > 0 ? `Ahora te pide:\n${brief}` : brief);
+
+  // 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
   // modelo tiende a copiarlo tal cual y a entregar la respuesta de otro.
@@ -436,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/memoria.ts

@@ -0,0 +1,136 @@
+/**
+ * La memoria de una conversación.
+ *
+ * Sin esto, cada llamada x402 es independiente: el cliente pregunta algo, tu
+ * agente contesta, y a la siguiente no sabe de qué se hablaba. Eso no es un
+ * chat, es un buscador que pasa factura — y quien lo usa lo nota al segundo
+ * mensaje, cuando tiene que repetir el contexto entero.
+ *
+ * QUIÉN HABLA LO DICE EL PAGO. La conversación se guarda por la dirección del
+ * pagador, y esa dirección no la afirma nadie: firmó un permiso y el cobro se
+ * ejecutó en la cadena. Nadie puede leer ni continuar la conversación de otro
+ * sin haber pagado como él, así que no hace falta ninguna autenticación
+ * aparte. Es la propiedad más útil de cobrar por llamada.
+ *
+ * SOLO EN x402, NO EN EL ESCROW. Un encargo del escrow es un trabajo con
+ * principio y fin: se paga, se entrega una vez y se aprueba. Arrastrarle
+ * memoria sería confundir dos cosas distintas.
+ *
+ * LO QUE CUESTA, porque conviene tenerlo delante: el historial va dentro del
+ * prompt, y el prompt lo pagas TÚ mientras el cliente paga un precio fijo por
+ * mensaje. Una conversación larga es cada vez más cara de contestar por lo
+ * mismo. De ahí los dos topes de abajo, y de ahí que se puedan bajar.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Un intercambio ya cerrado: lo que preguntaron y lo que contestaste. */
+export interface Turno {
+  pregunta: string;
+  respuesta: string;
+  /** Epoch en milisegundos. */
+  cuando: number;
+}
+
+/**
+ * Cuántos turnos se recuerdan. `MEMORIA_TURNOS=0` apaga la memoria.
+ *
+ * Seis es un número corto a propósito: cubre una conversación normal y deja
+ * el coste acotado. Súbelo si tu agente necesita hilos largos y te sale a
+ * cuenta; bájalo a cero si lo tuyo son preguntas sueltas.
+ */
+const TURNOS = (() => {
+  const n = Number(process.env.MEMORIA_TURNOS?.trim() || '6');
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 6;
+})();
+
+/**
+ * Tope de caracteres del historial que entra en el prompt.
+ *
+ * El tope de turnos por sí solo no acota nada: seis turnos pueden ser seis
+ * líneas o seis pantallas de código pegado.
+ */
+const MAX_CHARS = (() => {
+  const n = Number(process.env.MEMORIA_CHARS?.trim() || '4000');
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 4000;
+})();
+
+/** Cuántos turnos se guardan en disco, que es más de lo que se manda. */
+const GUARDADOS = 60;
+
+/**
+ * El archivo de una conversación.
+ *
+ * El nombre sale de la dirección, y aunque venga ya validada como tal se
+ * limpia igual: es lo que decide una ruta en disco, y una comprobación de más
+ * en un sitio así no cuesta nada.
+ */
+function archivo(dataDir: string, quien: string): string {
+  const limpio = quien.toLowerCase().replace(/[^a-z0-9x]/g, '');
+  return join(dataDir, 'chats', `${limpio}.json`);
+}
+
+/** Todo lo que se recuerda de esa persona, de lo más viejo a lo más nuevo. */
+export function leerConversacion(dataDir: string, quien: string): Turno[] {
+  try {
+    const turnos = JSON.parse(readFileSync(archivo(dataDir, quien), 'utf8')) as Turno[];
+    return Array.isArray(turnos) ? turnos : [];
+  } catch {
+    // Sin archivo, o con un archivo ilegible: se empieza de cero. Una memoria
+    // rota no puede impedir contestar a alguien que acaba de pagar.
+    return [];
+  }
+}
+
+/**
+ * Guarda un intercambio.
+ *
+ * Se llama DESPUÉS de contestar, con las dos mitades: un turno con pregunta y
+ * sin respuesta ensucia la memoria de la siguiente vez, y es justo lo que
+ * pasaría si se guardara antes de trabajar y el modelo fallara.
+ */
+export function recordarTurno(dataDir: string, quien: string, turno: Turno): void {
+  if (TURNOS === 0) return;
+  try {
+    const previos = leerConversacion(dataDir, quien);
+    mkdirSync(join(dataDir, 'chats'), { recursive: true });
+    writeFileSync(archivo(dataDir, quien), JSON.stringify([...previos, turno].slice(-GUARDADOS)), 'utf8');
+  } catch (err) {
+    // Perder la memoria no puede tumbar una respuesta ya cobrada.
+    console.error(`[memoria] no se pudo guardar el turno: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+/**
+ * El historial que se le pasa al modelo, ya acotado.
+ *
+ * Se recorta desde el final: lo reciente es lo que da contexto, y lo viejo es
+ * lo primero que sobra. Devuelve vacío con la memoria apagada.
+ */
+export function historialParaElModelo(dataDir: string, quien: string): Turno[] {
+  if (TURNOS === 0) return [];
+
+  const recientes = leerConversacion(dataDir, quien).slice(-TURNOS);
+  const salida: Turno[] = [];
+  let chars = 0;
+
+  // Se recorren del más nuevo al más viejo para que, si hay que dejar fuera
+  // algo, sea lo antiguo. Luego se devuelve en orden cronológico.
+  for (let i = recientes.length - 1; i >= 0; i--) {
+    const t = recientes[i]!;
+    const coste = t.pregunta.length + t.respuesta.length;
+    if (chars + coste > MAX_CHARS) break;
+    chars += coste;
+    salida.unshift(t);
+  }
+  return salida;
+}
+
+/** Cómo se le cuenta el historial al modelo. Vacío si no hay nada que contar. */
+export function historialComoTexto(turnos: Turno[]): string {
+  if (turnos.length === 0) return '';
+  return turnos
+    .map((t) => `Cliente: ${t.pregunta}\nTú: ${t.respuesta}`)
+    .join('\n\n');
+}

package/template/src/reintento.ts

@@ -0,0 +1,68 @@
+/**
+ * Reintentar cuando el modelo dice «ahora no».
+ *
+ * POR QUÉ EXISTE. Un proveedor devuelve 429 cuando está saturado o cuando has
+ * ido demasiado deprisa, y 5xx cuando le pasa algo a él. Ninguna de las dos es
+ * culpa tuya y las dos se arreglan solas en segundos. Sin esto, cualquiera de
+ * ellas mata la tarea: el cliente ya pagó, el pago se queda bloqueado, y no
+ * recupera nada hasta que vence el plazo.
+ *
+ * Medido contra Moonshot en agosto de 2026: dos llamadas seguidas y la segunda
+ * volvió con `engine_overloaded_error`. No es un caso raro que haya que
+ * imaginar, es lo normal en una tarde con tráfico.
+ *
+ * QUÉ **NO** SE REINTENTA, que importa igual: los demás 4xx. Un 401 es una
+ * clave mala, un 400 es una petición mal formada y un 404 es un modelo que no
+ * existe. Repetirlos gasta tiempo y dinero para llegar a la misma respuesta, y
+ * retrasa la única noticia útil —que hay algo mal configurado— hasta que se
+ * agotan los intentos.
+ *
+ * La espera CRECE entre intentos. Volver a preguntar de inmediato a un motor
+ * saturado es pedirle el mismo 429: empuja más carga justo cuando menos puede
+ * con ella.
+ */
+
+/** Esperas entre intentos, en milisegundos. Cuatro llamadas como mucho. */
+const ESPERAS = [1_000, 4_000, 10_000];
+
+/** Los códigos que se vuelven a intentar. El resto son respuestas firmes. */
+export function esReintentable(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+/**
+ * `fetch` que aguanta un proveedor con hipo.
+ *
+ * Devuelve la última respuesta, reintentable o no: quien llama decide qué
+ * hacer con ella, como con un `fetch` normal. Los fallos de RED sí se
+ * propagan al agotar los intentos, porque ahí no hay respuesta que devolver.
+ */
+export async function fetchModelo(
+  url: string,
+  init: RequestInit,
+  dormir: (ms: number) => Promise<void> = (ms) => new Promise((r) => setTimeout(r, ms)),
+): Promise<Response> {
+  let ultimoFallo: unknown;
+
+  for (let intento = 0; intento <= ESPERAS.length; intento++) {
+    if (intento > 0) {
+      const espera = ESPERAS[intento - 1]!;
+      console.warn(`[modelo] reintento ${intento} de ${ESPERAS.length} dentro de ${espera} ms`);
+      await dormir(espera);
+    }
+    try {
+      const res = await fetch(url, init);
+      if (!esReintentable(res.status) || intento === ESPERAS.length) return res;
+      console.warn(`[modelo] el proveedor respondió ${res.status}`);
+    } catch (err) {
+      // Un corte de red o el timeout del AbortSignal. Se reintenta igual: son
+      // tan pasajeros como un 503, y con el pago bloqueado no rendirse al
+      // primer tropiezo es lo que separa entregar de no entregar.
+      ultimoFallo = err;
+      if (intento === ESPERAS.length) throw err;
+      console.warn(`[modelo] la llamada falló: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  throw ultimoFallo ?? new Error('inalcanzable');
+}