create-panal-agent 0.10.0 → 0.12.0

package/template/src/agent.ts

@@ -11,8 +11,19 @@
  * anclado en la cadena al entregar. Si luego sirves otra cosa, se nota.
  */
 
-import type { CallEnvelope } from '@panal/sdk';
+import { esImagenSoportada, llmChat, resolverLlm, type CallEnvelope, type LlmConfig } from '@panal/sdk';
 import { textoAPdf } from './pdf.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;
+}
 
 export interface TaskContext {
   /**
@@ -27,6 +38,20 @@ export interface TaskContext {
   /** Fecha límite de entrega, en segundos epoch. Cero en una llamada x402. */
   deadline: bigint;
 
+  /**
+   * LO QUE EL CLIENTE TE ADJUNTÓ: una foto, un PDF que revisar, un CSV.
+   *
+   * Llegan verificados. El encargo anunció el hash de cada uno ANTES de que se
+   * 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.
+   *
+   * Vacío en una llamada x402: ahí no hay tarea donde anclar un adjunto.
+   */
+  adjuntos: AdjuntoRecibido[];
+
   /**
    * PREGUNTAR A OTRO AGENTE, Y PAGARLE.
    *
@@ -61,6 +86,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. */
@@ -115,10 +157,15 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
   // código, consultar una API, lo que quieras. No tiene por qué usar un modelo.
   // ──────────────────────────────────────────────────────────────────────────
 
-  const apiKey = process.env.LLM_API_KEY;
-  if (!apiKey) {
+  // El modelo, sea cual sea. `LLM_PROVIDER=claude|kimi|grok|glm|gemini|…` o
+  // `LLM_BASE_URL` a pelo para cualquiera que no esté en la lista.
+  let cfg: LlmConfig;
+  try {
+    cfg = resolverLlm(process.env);
+  } catch (err) {
     // Sin modelo configurado se entrega algo honesto en vez de fallar: el
     // cliente ya pagó, y dejarlo sin nada le cuesta el plazo entero.
+    console.error(`[agente] ${etiqueta(ctx)} sin modelo: ${err instanceof Error ? err.message : err}`);
     return (
       `No puedo completar este encargo ahora mismo: al agente le falta configurar su modelo.\n\n` +
       `Lo que pediste:\n${brief}\n\n` +
@@ -127,16 +174,28 @@ 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 }));
+  if (ctx.adjuntos.length > 0) {
+    console.log(
+      `[agente] ${etiqueta(ctx)} ${ctx.adjuntos.length} adjunto(s), ${imagenes.length} para el modelo: ` +
+        ctx.adjuntos.map((a) => a.name).join(', '),
+    );
+  }
+
   // ¿Esto lo sé hacer yo, o me conviene preguntar? La decisión es del agente,
   // no del cliente: él pidió un trabajo, no una arquitectura.
-  const ayuda = await pedirAyudaSiHaceFalta(brief, ctx, apiKey);
+  const ayuda = await pedirAyudaSiHaceFalta(brief, ctx, cfg);
 
   // Un intento, una revisión y una corrección. Un modelo falla el formato de
   // vez en cuando, y aquí eso no es un mensaje feo en un chat: el hash de lo
   // 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, apiKey, queja, ayuda);
+    const texto = await pedirAlModelo(brief, cfg, queja, ayuda, imagenes, ctx.adjuntos, ctx.historial);
     const problema = revisar(brief, texto);
     if (!problema) {
       console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
@@ -172,12 +231,12 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
 async function pedirAyudaSiHaceFalta(
   brief: string,
   ctx: TaskContext,
-  apiKey: string,
+  cfg: LlmConfig,
 ): Promise<string | null> {
   // Sin presupuesto no hay nada que decidir, y así se ahorra la llamada.
   if (ctx.presupuesto <= 0n) return null;
 
-  const decision = await decidirDelegacion(brief, apiKey);
+  const decision = await decidirDelegacion(brief, cfg);
   if (!decision) return null;
 
   try {
@@ -197,44 +256,52 @@ async function pedirAyudaSiHaceFalta(
   }
 }
 
+/**
+ * Saca el JSON de una respuesta, aunque venga envuelto.
+ *
+ * `response_format: json_object` sólo lo entiende parte del mercado, y este
+ * agente puede correr contra cualquiera. Se pide JSON en el prompt y se busca
+ * el objeto a la vuelta: unos lo envuelven en ```json y otros le ponen una
+ * frase delante, y las dos cosas son fáciles de perdonar.
+ */
+function extraerJson(crudo: string): unknown {
+  const sinValla = crudo.replace(/^\s*```(?:json)?\s*/i, '').replace(/\s*```\s*$/, '');
+  const ini = sinValla.indexOf('{');
+  const fin = sinValla.lastIndexOf('}');
+  if (ini === -1 || fin <= ini) return null;
+  try {
+    return JSON.parse(sinValla.slice(ini, fin + 1));
+  } catch {
+    return null;
+  }
+}
+
 /** Una llamada corta al modelo: ¿delego, y a quién? Formato JSON o nada. */
 async function decidirDelegacion(
   brief: string,
-  apiKey: string,
+  cfg: LlmConfig,
 ): Promise<{ skill: string; pregunta: string } | null> {
   try {
-    const res = await fetch(`${process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1'}/chat/completions`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
-      // Corto a propósito: si decidir tarda más que trabajar, no compensa.
-      signal: AbortSignal.timeout(30_000),
-      body: JSON.stringify({
-        model: process.env.LLM_MODEL ?? 'gpt-4o-mini',
-        response_format: { type: 'json_object' },
-        messages: [
-          {
-            role: 'system',
-            content:
-              'You are an agent deciding whether to PAY another specialist agent out of your own earnings ' +
-              'to do part of a job. Answer with JSON only.\n' +
-              '{"delegate": false} if you can do the job yourself. This is the right answer almost always.\n' +
-              '{"delegate": true, "skill": "…", "question": "…"} ONLY if the job clearly needs expertise ' +
-              'outside your own, and a specialist answer would measurably improve the result.\n' +
-              '"skill" is one or two words to search a marketplace by (e.g. "translation", "legal", "json").\n' +
-              '"question" is the self-contained question for that specialist: it will be sent on its own, ' +
-              'so it must make sense without the rest of the job.\n' +
-              'Paying costs real money. If in doubt, do not delegate.',
-          },
-          { role: 'user', content: brief },
-        ],
-      }),
-    });
-    if (!res.ok) return null;
-    const data = (await res.json()) as { choices?: { message?: { content?: string } }[] };
-    const crudo = data.choices?.[0]?.message?.content;
-    if (!crudo) return null;
-    const parsed = JSON.parse(crudo) as { delegate?: boolean; skill?: string; question?: string };
-    if (parsed.delegate !== true) return null;
+    const crudo = await llmChat(
+      // Corto a propósito, y sin reintentos: si decidir tarda más que trabajar
+      // —o cuesta más—, no compensa. Ante la duda se trabaja solo.
+      { ...cfg, timeoutMs: 30_000, maxRetries: 0, maxTokens: 400 },
+      {
+        system:
+          'You are an agent deciding whether to PAY another specialist agent out of your own earnings ' +
+          'to do part of a job. Answer with JSON only, no prose and no code fences.\n' +
+          '{"delegate": false} if you can do the job yourself. This is the right answer almost always.\n' +
+          '{"delegate": true, "skill": "…", "question": "…"} ONLY if the job clearly needs expertise ' +
+          'outside your own, and a specialist answer would measurably improve the result.\n' +
+          '"skill" is one or two words to search a marketplace by (e.g. "translation", "legal", "json").\n' +
+          '"question" is the self-contained question for that specialist: it will be sent on its own, ' +
+          'so it must make sense without the rest of the job.\n' +
+          'Paying costs real money. If in doubt, do not delegate.',
+        user: brief,
+      },
+    );
+    const parsed = extraerJson(crudo) as { delegate?: boolean; skill?: string; question?: string } | null;
+    if (!parsed || parsed.delegate !== true) return null;
     const skill = parsed.skill?.trim();
     const pregunta = parsed.question?.trim();
     if (!skill || !pregunta) return null;
@@ -314,71 +381,91 @@ function conPdfSiLoPidio(brief: string, texto: string, ctx: TaskContext): TaskRe
 
 async function pedirAlModelo(
   brief: string,
-  apiKey: string,
+  cfg: LlmConfig,
   queja: string | null,
   ayuda: string | null,
+  imagenes: { mime: string; bytes: Uint8Array }[],
+  adjuntos: AdjuntoRecibido[],
+  historial: Turno[],
 ): Promise<string> {
-  const res = await fetch(`${process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1'}/chat/completions`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+  // 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: string[] = [];
+
+  // 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);
+
+  // 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 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.
+  if (ayuda) {
+    partes.push(
+      'Material de apoyo, pagado a un agente especialista. Úsalo si ayuda y descártalo si no; ' +
+        `no lo copies tal cual ni lo menciones en la entrega:\n\n${ayuda}`,
+    );
+  }
+
+  // La corrección va como una parte más: decirle QUÉ falló acierta mucho más
+  // que repetirle la misma petición a ciegas esperando otra suerte.
+  if (queja) partes.push(`Tu respuesta anterior no vale: ${queja}. Corrígela.`);
+
+  return llmChat(
     // Sin este tope, un modelo que se cuelga deja la tarea colgada para
     // siempre: el cliente ni cobra el resultado ni recupera su dinero hasta
     // que vence el plazo. Pasó de verdad, en mainnet.
-    signal: AbortSignal.timeout(120_000),
-    body: JSON.stringify({
-      model: process.env.LLM_MODEL ?? 'gpt-4o-mini',
-      messages: [
-        {
-          role: 'system',
-          content:
-            // Estas tres reglas cuestan de acertar a mano y se pagan caras:
-            // 1. Sin la del idioma, el modelo contesta en el suyo aunque el
-            //    cliente escriba en otro, y el cliente recibe algo inservible.
-            // 2. Sin la del formato, entrega Markdown y el cliente ve `**esto**`
-            //    en crudo, porque ni el dashboard ni Telegram lo renderizan.
-            // 3. Sin la del registro, envuelve el trabajo en "¡Claro! Aquí
-            //    tienes…" y el entregable parece un chat, no un producto.
-            'You are a professional agent on the Panal marketplace. ' +
-            // El "never fall back to English" y lo de los títulos no son
-            // adorno: en producción, una petición en portugués volvió entera en
-            // inglés porque el prompt listaba los títulos de sección en inglés y
-            // el modelo los copiaba; y otra en chino devolvió las claves en
-            // inglés. Los dos fallos con la regla del idioma ya puesta.
-            'RULE 1, before anything else: detect the language of the request and reply in that exact same ' +
-            'language; never switch part-way, and never fall back to English because the request is not in ' +
-            'English. If the instructions below name sections, headings or field names, translate those too: ' +
-            'they are written in one language only because these instructions are. ' +
-            'RULE 2: plain text only, never Markdown — no # headings, no ** bold, no backticks. ' +
-            'RULE 3: deliver finished professional work, with no preamble or meta-commentary.\n' +
-            // El agente adjunta el archivo por su cuenta; el modelo no se entera
-            // y, sin esta regla, se disculpa por no poder generarlo.
-            'RULE 4: the client may ask for the result as a PDF or a file. The agent attaches it after ' +
-            'you answer. Never mention files, PDFs or attachments — not even to say you cannot make them.',
-        },
-        { role: 'user', content: brief },
-        // 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.
-        ...(ayuda
-          ? [
-              {
-                role: 'user' as const,
-                content:
-                  'Material de apoyo, pagado a un agente especialista. Úsalo si ayuda y descártalo si no; ' +
-                  `no lo copies tal cual ni lo menciones en la entrega:\n\n${ayuda}`,
-              },
-            ]
-          : []),
-        // La corrección va como un mensaje más: decirle QUÉ falló acierta mucho
-        // más que repetirle la misma petición a ciegas esperando otra suerte.
-        ...(queja ? [{ role: 'user' as const, content: `Tu respuesta anterior no vale: ${queja}. Corrígela.` }] : []),
-      ],
-    }),
-  });
-
-  if (!res.ok) throw new Error(`El modelo respondió ${res.status}`);
-  const data = (await res.json()) as { choices?: { message?: { content?: string } }[] };
-  const text = data.choices?.[0]?.message?.content?.trim();
-  if (!text) throw new Error('El modelo devolvió una respuesta vacía.');
-  return text;
+    { ...cfg, timeoutMs: cfg.timeoutMs ?? 120_000 },
+    {
+      system:
+        // Estas cuatro reglas cuestan de acertar a mano y se pagan caras:
+        // 1. Sin la del idioma, el modelo contesta en el suyo aunque el
+        //    cliente escriba en otro, y el cliente recibe algo inservible.
+        // 2. Sin la del formato, entrega Markdown y el cliente ve `**esto**`
+        //    en crudo, porque ni el dashboard ni Telegram lo renderizan.
+        // 3. Sin la del registro, envuelve el trabajo en "¡Claro! Aquí
+        //    tienes…" y el entregable parece un chat, no un producto.
+        'You are a professional agent on the Panal marketplace. ' +
+        // El "never fall back to English" y lo de los títulos no son
+        // adorno: en producción, una petición en portugués volvió entera en
+        // inglés porque el prompt listaba los títulos de sección en inglés y
+        // el modelo los copiaba; y otra en chino devolvió las claves en
+        // inglés. Los dos fallos con la regla del idioma ya puesta.
+        'RULE 1, before anything else: detect the language of the request and reply in that exact same ' +
+        'language; never switch part-way, and never fall back to English because the request is not in ' +
+        'English. If the instructions below name sections, headings or field names, translate those too: ' +
+        'they are written in one language only because these instructions are. ' +
+        'RULE 2: plain text only, never Markdown — no # headings, no ** bold, no backticks. ' +
+        'RULE 3: deliver finished professional work, with no preamble or meta-commentary.\n' +
+        // El agente adjunta el archivo por su cuenta; el modelo no se entera
+        // y, sin esta regla, se disculpa por no poder generarlo. Ojo al
+        // matiz: prohibirle hablar de archivos A SECAS le hacía callar
+        // también sobre la foto que le acababan de mandar.
+        'RULE 4: the client may ask for the result as a PDF or a file. The agent attaches it after ' +
+        'you answer. Never mention files, PDFs or attachments you would have to produce — not even to ' +
+        '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 } : {}),
+    },
+  );
 }

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