create-panal-agent 0.15.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Crea un agente de IA para Panal, funcionando y cobrando on-chain, en cinco minutos",
   "type": "module",
   "license": "MIT",

package/template/_package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@panal/sdk": "^0.15.0",
+    "@panal/sdk": "^0.17.0",
     "unpdf": "^1.8.1",
     "dotenv": "^17.0.0",
     "tsx": "^4.19.0",

package/template/src/register.ts

@@ -12,7 +12,7 @@
  */
 
 import 'dotenv/config';
-import { createPanalClient, formatAgentMetadata, NATIVE_CURRENCY } from '@panal/sdk';
+import { createPanalClient, formatAgentMetadata, NATIVE_CURRENCY, rutaDeAgente } from '@panal/sdk';
 import { privateKeyToAccount } from 'viem/accounts';
 import { createPublicClient, createWalletClient, formatEther, http, parseEther } from 'viem';
 
@@ -138,7 +138,7 @@ export function loQueFaltaDelPerfil(perfil: typeof PERFIL): string | null {
 async function compruebaEndpoint(botUrl: string, yo: string): Promise<string | null> {
   let url: string;
   try {
-    url = new URL('/agent.json', botUrl).toString();
+    url = rutaDeAgente(botUrl, 'agent.json');
   } catch {
     return `PERFIL.botUrl no es una URL válida: ${botUrl}`;
   }
@@ -192,7 +192,7 @@ async function compruebaEndpoint(botUrl: string, yo: string): Promise<string | n
 async function logoQueSirves(botUrl: string): Promise<string> {
   let url: string;
   try {
-    url = new URL('/logo', botUrl).toString();
+    url = rutaDeAgente(botUrl, 'logo');
   } catch {
     return '';
   }

package/template/src/server.ts

@@ -32,6 +32,9 @@ import {
   buildQuote,
   createPanalClient,
   leerNiveles,
+  leerNivelesDeMetadata,
+  normalizarIdioma,
+  resolverLlm,
   LoopDetected,
   MAINNET_ADDRESSES,
   monad,
@@ -49,6 +52,7 @@ import {
   type CallEnvelope,
   type DeliveredFile,
   type FichaNivel,
+  type LlmConfig,
   type Nivel,
   type PermitDomain,
 } from '@panal/sdk';
@@ -57,6 +61,7 @@ import { privateKeyToAccount } from 'viem/accounts';
 import { isAddress, keccak256, parseEther, toBytes, verifyMessage } from 'viem';
 import type { Address } from 'viem';
 import { handleTask, NIVELES, SUBCONTRATA_SKILLS } from './agent.js';
+import { frasesGuardadas, pedirTraduccion } from './traduccion.js';
 import type { AdjuntoRecibido, NivelPropio, TaskContext, TaskFile, TaskResult } from './agent.js';
 import { arrancarVigilante } from './vigilante.js';
 import { historialParaElModelo, recordarTurno, type Turno } from './memoria.js';
@@ -90,7 +95,7 @@ const MAX_BRIEF_CHARS = 32_000;
 // propios clientes van a descartar: si aquí no sobrevive, no se anuncia.
 // ---------------------------------------------------------------------------
 
-const NIVELES_OK = leerNiveles({
+let NIVELES_OK = leerNiveles({
   tiers: NIVELES.map((n) => ({ ...n, amountWei: n.wei.toString() })),
 });
 
@@ -102,7 +107,7 @@ if (NIVELES.length > 0 && NIVELES_OK.length !== NIVELES.length) {
 }
 
 /** El nivel más barato: por debajo de eso, un agente con niveles no trabaja. */
-const NIVEL_MINIMO = NIVELES_OK[0] ?? null;
+let NIVEL_MINIMO = NIVELES_OK[0] ?? null;
 
 // Se dicen al arrancar. Antes sólo salían dentro del bloque de subcontratación
 // —que no se imprime si no hay presupuesto—, así que un agente con niveles y
@@ -133,7 +138,7 @@ for (const n of NIVELES) {
 
 
 /** El tope de encargo del nivel mayor, o el de siempre si no hay niveles. */
-const TOPE_BRIEF_MAYOR = Math.max(MAX_BRIEF_CHARS, ...NIVELES_OK.map((n) => n.maxBriefChars ?? 0));
+let TOPE_BRIEF_MAYOR = Math.max(MAX_BRIEF_CHARS, ...NIVELES_OK.map((n) => n.maxBriefChars ?? 0));
 
 /**
  * Tope del cuerpo de una petición: sin esto, cualquiera te tumba el proceso.
@@ -144,7 +149,22 @@ const TOPE_BRIEF_MAYOR = Math.max(MAX_BRIEF_CHARS, ...NIVELES_OK.map((n) => n.ma
  * los 32 KB de propina cubren el resto del JSON: la firma, la dirección y el
  * manifiesto de adjuntos que viaja dentro del encargo.
  */
-const MAX_BODY = Math.max(256 * 1024, TOPE_BRIEF_MAYOR * 4 + 32 * 1024);
+let MAX_BODY = Math.max(256 * 1024, TOPE_BRIEF_MAYOR * 4 + 32 * 1024);
+
+/**
+ * Los tres números de arriba se recalculan cuando cambian los niveles.
+ *
+ * Cambian porque ahora se pueden editar desde la web sin tocar este código:
+ * viven en el `metadataURI` on-chain y el dueño del agente los mueve firmando
+ * una transacción. Si estos números se quedaran con lo que había al arrancar,
+ * un nivel nuevo de 320 000 caracteres se anunciaría y luego se rechazaría por
+ * pasarse del tope, que es la peor de las dos opciones: se cobra y no se hace.
+ */
+function recalcularTopes(): void {
+  NIVEL_MINIMO = NIVELES_OK[0] ?? null;
+  TOPE_BRIEF_MAYOR = Math.max(MAX_BRIEF_CHARS, ...NIVELES_OK.map((n) => n.maxBriefChars ?? 0));
+  MAX_BODY = Math.max(256 * 1024, TOPE_BRIEF_MAYOR * 4 + 32 * 1024);
+}
 
 /** Un nivel ya validado, en la forma con la que se anuncia y se devuelve. */
 function comoFicha(n: Nivel): FichaNivel {
@@ -163,9 +183,22 @@ function nivelDe(pagado: bigint): NivelPropio | null {
   if (NIVELES_OK.length === 0) return null;
   const leido = nivelPara(NIVELES_OK, pagado);
   if (!leido) return null;
-  // Se devuelve el declarado en `agent.ts`, no el normalizado: es el que tiene
-  // los tipos que el autor del agente espera encontrar en `ctx.nivel`.
-  return NIVELES.find((n) => n.wei === leido.wei) ?? null;
+  // Se prefiere el declarado en `agent.ts`: es el que tiene los tipos que el
+  // autor del agente espera en `ctx.nivel`, y el único que puede traer
+  // `subcontrata`, que no cabe en la ficha on-chain.
+  const propio = NIVELES.find((n) => n.wei === leido.wei);
+  if (propio) return propio;
+  // Y si viene de la CADENA, se arma uno. Devolver null aquí sería lo peor que
+  // podría pasar: el cliente pagó el nivel grande, lo vio anunciado y el
+  // agente trabajaría creyendo que no compró ninguno.
+  return {
+    name: leido.name ?? '',
+    ...(leido.description === null ? {} : { description: leido.description }),
+    wei: leido.wei,
+    ...(leido.maxBriefChars === null ? {} : { maxBriefChars: leido.maxBriefChars }),
+    ...(leido.maxAttachChars === null ? {} : { maxAttachChars: leido.maxAttachChars }),
+    ...(leido.maxAttachCharsTotal === null ? {} : { maxAttachCharsTotal: leido.maxAttachCharsTotal }),
+  };
 }
 
 const key = process.env.AGENT_PRIVATE_KEY?.trim();
@@ -178,6 +211,85 @@ const panal = createPanalClient({ account, rpcUrl: process.env.RPC_URL });
 
 console.log(`Agente ${account.address} escuchando en :${PORT}`);
 
+// ---------------------------------------------------------------------------
+// Los niveles de la CADENA mandan sobre los de `agent.ts`.
+//
+// Se pueden editar desde el panel de la web sin tocar una línea de código: van
+// dentro del `metadataURI`, y cambiarlos es una transacción. Este bloque los
+// lee y los deja al mando, porque son LOS QUE VIO EL CLIENTE: es contra la
+// ficha on-chain contra lo que eligió tamaño y contra lo que bloqueó el dinero,
+// así que trabajar con otros sería cobrar por una cosa y hacer otra.
+//
+// Se relee cada rato, y no solo al arrancar, porque el sentido de haberlos
+// sacado del código es justamente no tener que reiniciar nada para cambiarlos.
+// Si la lectura falla, se queda lo que hubiera: un RPC lento no puede dejar sin
+// niveles a un agente que los tiene.
+// ---------------------------------------------------------------------------
+
+/** Cada cuánto se vuelve a mirar la ficha. */
+const REFRESCO_NIVELES = 5 * 60 * 1000;
+
+/**
+ * El modelo con el que este agente traduce SU PROPIA ficha para `?lang=`.
+ *
+ * Se resuelve una vez y falla a `null` en vez de tumbar el arranque: un agente
+ * sin `LLM_API_KEY` es un agente perfectamente válido —hay agentes que no usan
+ * modelo ninguno— y quedarse sin poder servir la ficha por no poder traducirla
+ * sería dejarlo fuera del mercado por un lujo. Sin modelo, ficha original.
+ */
+const LLM_FICHA: LlmConfig | null = (() => {
+  try {
+    return resolverLlm(process.env);
+  } catch {
+    return null;
+  }
+})();
+
+/** Los de `agent.ts`, para poder volver a ellos si la ficha se queda sin niveles. */
+const NIVELES_DEL_CODIGO = NIVELES_OK;
+
+/**
+ * El nombre y la descripción que este agente tiene EN LA CADENA.
+ *
+ * La plantilla no los tenía: su `/agent.json` publicaba endpoints y precios, y
+ * el texto salía solo del registro. Hacen falta aquí para poder servirlos
+ * TRADUCIDOS, que es lo que pide `?lang=`.
+ */
+let FICHA_TEXTO: { name: string; description: string } = { name: '', description: '' };
+
+async function refrescarNiveles(): Promise<void> {
+  try {
+    const ficha = await panal.getAgent(account.address);
+    FICHA_TEXTO = {
+      name: ficha.metadata.name,
+      description: ficha.metadata.description,
+    };
+    const enCadena = leerNivelesDeMetadata(ficha.metadataURI);
+    const antes = NIVELES_OK.map((n) => `${n.wei}:${n.name ?? ''}`).join('|');
+    NIVELES_OK = enCadena.length > 0 ? enCadena : NIVELES_DEL_CODIGO;
+    const ahora = NIVELES_OK.map((n) => `${n.wei}:${n.name ?? ''}`).join('|');
+    if (antes !== ahora) {
+      recalcularTopes();
+      console.log(
+        NIVELES_OK.length > 0
+          ? `[panal] niveles actualizados desde la cadena (${NIVELES_OK.length}): ` +
+              NIVELES_OK.map((n) => `${n.name ?? '?'} ${n.wei}`).join(', ')
+          : '[panal] este agente ya no publica niveles',
+      );
+    }
+  } catch {
+    // Sin RPC, con la ficha ilegible o con el agente aún sin registrar: se
+    // queda lo que hubiera. Callado, porque esto corre cada cinco minutos y un
+    // aviso por cada fallo llenaría el log de un agente que funciona.
+  }
+}
+
+// La primera va ANTES de escuchar: `MAX_BODY` sale del tope del nivel mayor, y
+// arrancar con el número viejo sería anunciar un encargo de 320 000 caracteres
+// y cortarlo al recibirlo.
+await refrescarNiveles();
+setInterval(() => void refrescarNiveles(), REFRESCO_NIVELES).unref();
+
 // ---------------------------------------------------------------------------
 // x402: cobrar por llamada, sin escrow.
 //
@@ -1149,6 +1261,50 @@ const server = createServer((req, res) => {
     // salía en su tarjeta: un cobro que nadie puede descubrir no existe.
     if (url.pathname === '/agent.json' && req.method === 'GET') {
       const base = process.env.PUBLIC_URL?.trim().replace(/\/+$/, '') || null;
+      /**
+       * `?lang=fr`: la misma ficha con las frases en francés.
+       *
+       * SIN ESPERAR. Si el idioma ya está traducido se sirve traducido; si no,
+       * se sirve el original y la traducción se encarga por detrás para la
+       * próxima vez. Traducir aquí dentro obliga a no reintentar —nadie espera
+       * a un modelo con la tarjeta en blanco— y sin reintentos un 429 pasajero
+       * dejaba ese idioma sin traducir para siempre.
+       */
+      const idioma = normalizarIdioma(url.searchParams.get('lang'));
+      const nivelesFicha = NIVELES_OK.map(comoFicha);
+      let descripcion = FICHA_TEXTO.description;
+      /**
+       * En qué idioma va lo que se sirve, y `null` si va en el original.
+       *
+       * Hay que DECIRLO, no dejarlo adivinar. Como la traducción va por detrás,
+       * pedir `?lang=fr` antes de que esté lista devuelve la ficha original con
+       * un 200 impecable: quien la guarde —el indexador lo hace— se queda con
+       * el texto en inglés creyendo que es el francés, y como le llegaron los
+       * diez idiomas da el trabajo por hecho y no vuelve nunca. Pasó en
+       * mainnet: nueve de cada diez «traducciones» del catálogo eran el
+       * original.
+       */
+      let servidoEn: string | null = null;
+      if (idioma) {
+        const frases = {
+          description: descripcion,
+          tiers: NIVELES_OK.map((n) => ({ name: n.name ?? '', description: n.description ?? '' })),
+        };
+        const traducido = frasesGuardadas(frases, idioma, DATA_DIR);
+        if (!traducido) pedirTraduccion(frases, idioma, LLM_FICHA, DATA_DIR);
+        if (traducido) {
+          servidoEn = idioma;
+          descripcion = traducido.description;
+          traducido.tiers.forEach((t, i) => {
+            const destino = nivelesFicha[i];
+            // Solo se pisa lo que ya había: un nivel sin nombre no gana uno
+            // por pasar por el traductor, y uno con nombre no lo pierde.
+            if (!destino) return;
+            if (destino.name && t.name) destino.name = t.name;
+            if (destino.description && t.description) destino.description = t.description;
+          });
+        }
+      }
       const x402 =
         X402_PRICE !== null
           ? {
@@ -1169,6 +1325,13 @@ const server = createServer((req, res) => {
         protocol: 'panal',
         network: 'monad-mainnet',
         chainId: monad.id,
+        // El nombre NO se traduce nunca: «LexPanal» no significa nada en
+        // francés y traducirlo sería inventarle otro nombre a este agente.
+        ...(FICHA_TEXTO.name ? { name: FICHA_TEXTO.name } : {}),
+        ...(descripcion ? { description: descripcion } : {}),
+        // Solo cuando se ha traducido de verdad. Ausente = esto va en el
+        // idioma en que su dueño lo escribió, aunque lo hayas pedido en otro.
+        ...(servidoEn ? { lang: servidoEn } : {}),
         endpoints: {
           base,
           postBrief: {
@@ -1203,7 +1366,7 @@ const server = createServer((req, res) => {
         },
         // Los niveles, sólo si este agente vende alguno. Ausente significa que
         // no los ofrece, y quien lee NO debe inventárselos a partir del precio.
-        ...(NIVELES_OK.length > 0 ? { tiers: NIVELES_OK.map(comoFicha) } : {}),
+        ...(nivelesFicha.length > 0 ? { tiers: nivelesFicha } : {}),
         // ALIAS ANTIGUO, en la raíz. Aquí es donde esta plantilla lo publicaba
         // antes, y hay clientes ahí fuera que solo miran este sitio. Se sirve
         // por compatibilidad y desaparecerá; lo que se lee es `endpoints`.

package/template/src/traduccion.ts

@@ -0,0 +1,246 @@
+/**
+ * Panal — tu ficha en el idioma de quien la lee.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * QUÉ ARREGLA
+ *
+ * El marketplace habla diez idiomas; tu ficha, uno. Tu descripción y los
+ * nombres de tus niveles son texto que escribiste tú, y salen igual en las
+ * diez versiones del escaparate: quien entra en árabe ve toda la interfaz en
+ * árabe y tu agente descrito en español, o peor, la descripción en inglés y
+ * los niveles en español, que es lo que pasa hoy en mainnet.
+ *
+ * Aquí `GET /agent.json?lang=fr` devuelve tu MISMA ficha con las frases en
+ * francés. Nadie tiene que aprender un formato nuevo: los lectores siguen
+ * mirando `description` y `tiers[].name`, solo que traducidos.
+ *
+ * QUÉ CUESTA, QUE ES LA PREGUNTA DE VERDAD
+ *
+ * Una llamada a tu modelo por idioma, UNA VEZ. El resultado se guarda en disco
+ * con la huella del texto original dentro del nombre, así que:
+ *
+ *   - la segunda petición en francés no llama a nadie;
+ *   - y si cambias tu descripción, la huella cambia y se vuelve a traducir
+ *     sola, sin que tengas que acordarte de borrar nada.
+ *
+ * Diez idiomas son diez llamadas en toda la vida de una descripción. Traducir
+ * cuatro frases es la llamada más barata que va a hacer tu agente.
+ *
+ * NADIE ESPERA A QUE TRADUZCA
+ *
+ * La ficha se sirve SIEMPRE al momento. Si el idioma ya está guardado va
+ * traducida; si no, va original y la traducción se pide POR DETRÁS, para la
+ * próxima vez que alguien pregunte por ese idioma.
+ *
+ * Traducir dentro de la petición obliga a no reintentar, porque nadie va a
+ * esperar a un modelo con la tarjeta en blanco. Y sin reintentos un
+ * `429 Too Many Requests` —que en una cuenta compartida por cuatro agentes es
+ * lo normal, no la excepción— significa «esta ficha no se traduce»; como no se
+ * guarda nada, el siguiente que pregunte se come otro 429 y el idioma no llega
+ * a traducirse NUNCA. Comprobado contra los agentes de mainnet: la misma
+ * petición que falla con cero reintentos entra en cuanto se la deja insistir.
+ *
+ * Fuera de la petición sí se puede insistir, porque no hay nadie mirando.
+ *
+ * CUANDO FALLA NO SE NOTA
+ *
+ * Si el modelo no contesta, se acabó la cuota o no hay `LLM_API_KEY`, se sirve
+ * la ficha ORIGINAL. Una traducción es una mejora, no un requisito: quedarse
+ * sin ficha por no poder traducirla sería dejar al agente fuera del mercado
+ * por un lujo.
+ *
+ * Y NO SE TRADUCE TU NOMBRE. «LexPanal» no significa nada en francés, y
+ * traducirlo sería inventarle otro nombre a tu agente y romper toda referencia
+ * escrita a él.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { llmChat, NOMBRE_IDIOMA, type Idioma, type LlmConfig } from '@panal/sdk';
+
+/** Lo que se traduce de una ficha. Nada más: el nombre del agente no se toca. */
+export interface Frases {
+  description: string;
+  /** Nombre y descripción de cada nivel, en el orden en que van en la ficha. */
+  tiers: { name: string; description: string }[];
+}
+
+/** Tope de la respuesta que se acepta del modelo, por frase. */
+const MAX_FRASE = 400;
+
+/**
+ * Cuánto se espera al modelo, y cuántas veces se insiste.
+ *
+ * Holgado porque esto ya NO corre dentro de la petición de la ficha: nadie está
+ * mirando. Los reintentos son lo que hace que la traducción llegue; sin ellos
+ * un 429 pasajero dejaba el idioma sin traducir para siempre.
+ */
+const ESPERA_MS = 60_000;
+const REINTENTOS = 4;
+
+/**
+ * Los idiomas que se están traduciendo ahora mismo.
+ *
+ * El indexador pide los diez seguidos, y sin esta lista tres peticiones en
+ * francés llegadas antes de que vuelva la primera lanzarían tres traducciones
+ * idénticas: tres veces el gasto contra una cuenta que ya va justa de
+ * peticiones por minuto, para escribir el mismo archivo.
+ */
+const enCurso = new Set<string>();
+
+/** La huella del texto original: si cambia, la traducción guardada ya no vale. */
+function huella(frases: Frases): string {
+  return createHash('sha256').update(JSON.stringify(frases)).digest('hex').slice(0, 16);
+}
+
+function rutaCache(dir: string, idioma: Idioma, h: string): string {
+  return join(dir, 'idiomas', `${idioma}-${h}.json`);
+}
+
+/** Lo guardado, si vale. Nunca lanza: un archivo roto es como si no estuviera. */
+function leerGuardado(dir: string, idioma: Idioma, h: string): Frases | null {
+  try {
+    const ruta = rutaCache(dir, idioma, h);
+    if (!existsSync(ruta)) return null;
+    return validar(JSON.parse(readFileSync(ruta, 'utf8')), null);
+  } catch {
+    return null;
+  }
+}
+
+function guardar(dir: string, idioma: Idioma, h: string, frases: Frases): void {
+  try {
+    mkdirSync(join(dir, 'idiomas'), { recursive: true });
+    writeFileSync(rutaCache(dir, idioma, h), JSON.stringify(frases), 'utf8');
+  } catch {
+    // Sin disco se traduce más veces, que es lo peor que puede pasar aquí.
+  }
+}
+
+/**
+ * Lo que devolvió el modelo, comprobado contra la forma que se le pidió.
+ *
+ * Un modelo puede contestar cualquier cosa: una disculpa, el JSON envuelto en
+ * markdown, o la lista con un nivel de más. Lo que no cuadre se descarta
+ * ENTERO y se sirve el original, porque media traducción en una tarjeta es
+ * peor que ninguna: parece que al agente le falta la mitad de la ficha.
+ *
+ * `original` sirve para exigir el mismo número de niveles. Con `null` solo se
+ * comprueba la forma, que es lo que hace falta al leer del disco.
+ */
+function validar(v: unknown, original: Frases | null): Frases | null {
+  if (!v || typeof v !== 'object') return null;
+  const { description, tiers } = v as Record<string, unknown>;
+  if (typeof description !== 'string' || !description.trim()) return null;
+  if (!Array.isArray(tiers)) return null;
+  if (original && tiers.length !== original.tiers.length) return null;
+
+  const salida: Frases['tiers'] = [];
+  for (const t of tiers) {
+    if (!t || typeof t !== 'object') return null;
+    const { name, description: d } = t as Record<string, unknown>;
+    if (typeof name !== 'string' || typeof d !== 'string') return null;
+    salida.push({ name: name.trim().slice(0, MAX_FRASE), description: d.trim().slice(0, MAX_FRASE) });
+  }
+  return { description: description.trim().slice(0, MAX_FRASE), tiers: salida };
+}
+
+/** El JSON que venga, aunque llegue envuelto en un bloque de markdown. */
+function comoJson(crudo: string): unknown {
+  const limpio = crudo.trim().replace(/^```(?:json)?\s*/i, '').replace(/```$/, '');
+  try {
+    return JSON.parse(limpio);
+  } catch {
+    // A veces el modelo escribe una frase antes del JSON. Se busca el objeto.
+    const i = limpio.indexOf('{');
+    const j = limpio.lastIndexOf('}');
+    if (i < 0 || j <= i) return null;
+    try {
+      return JSON.parse(limpio.slice(i, j + 1));
+    } catch {
+      return null;
+    }
+  }
+}
+
+const SISTEMA =
+  'You translate short marketplace copy. Reply with JSON only, no explanation, ' +
+  'no markdown fence. Keep the exact same JSON shape and the same number of ' +
+  'array items you are given. Translate the meaning, not word by word: these ' +
+  'are product labels that people choose from, so they must read naturally and ' +
+  'stay short. Do not translate brand names, product names or code identifiers.';
+
+/**
+ * Las frases ya traducidas, si están guardadas. NO llama a nadie.
+ *
+ * Esta es la que usa la ficha, y por eso es síncrona: contesta en microsegundos
+ * y no puede hacer esperar a quien pide `/agent.json`.
+ */
+export function frasesGuardadas(frases: Frases, idioma: Idioma, dir: string): Frases | null {
+  return leerGuardado(dir, idioma, huella(frases));
+}
+
+/**
+ * Pide la traducción POR DETRÁS, para la próxima vez.
+ *
+ * No devuelve nada y no se espera: quien la llama ya ha servido la ficha
+ * original. Si sale bien queda guardada y la siguiente petición en ese idioma
+ * la encuentra hecha; si sale mal no se entera nadie y se reintentará.
+ */
+export function pedirTraduccion(
+  frases: Frases,
+  idioma: Idioma,
+  llm: LlmConfig | null,
+  dir: string,
+): void {
+  if (!llm) return;
+  if (!frases.description.trim() && frases.tiers.length === 0) return;
+  const clave = `${idioma}-${huella(frases)}`;
+  if (enCurso.has(clave) || frasesGuardadas(frases, idioma, dir)) return;
+  enCurso.add(clave);
+  void traducirFrases(frases, idioma, llm, dir).finally(() => enCurso.delete(clave));
+}
+
+/**
+ * Las frases de la ficha en otro idioma, esperando al modelo.
+ *
+ * Devuelve `null` cuando no se ha podido traducir. La ficha NO la llama
+ * directamente —usa el par de arriba—; esta existe para las pruebas y para
+ * traducir a mano, donde sí se quiere el resultado.
+ */
+export async function traducirFrases(
+  frases: Frases,
+  idioma: Idioma,
+  llm: LlmConfig | null,
+  dir: string,
+): Promise<Frases | null> {
+  // Sin nada que traducir no se molesta a nadie.
+  if (!frases.description.trim() && frases.tiers.length === 0) return null;
+
+  const h = huella(frases);
+  const guardado = leerGuardado(dir, idioma, h);
+  if (guardado) return guardado;
+  if (!llm) return null;
+
+  try {
+    const crudo = await llmChat(
+      { ...llm, timeoutMs: ESPERA_MS, maxRetries: REINTENTOS },
+      {
+        system: SISTEMA,
+        user:
+          `Translate the values of this JSON into ${NOMBRE_IDIOMA[idioma]}.\n` +
+          'Keep the keys in English and the array in the same order.\n\n' +
+          JSON.stringify(frases),
+      },
+    );
+    const traducido = validar(comoJson(crudo), frases);
+    if (!traducido) return null;
+    guardar(dir, idioma, h, traducido);
+    return traducido;
+  } catch {
+    // Sin clave, sin cuota, sin red o con el modelo caído: la ficha original.
+    return null;
+  }
+}