create-panal-agent 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.16.0",
+  "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.16.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

@@ -61,7 +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 { traducirFrases } from './traduccion.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';
@@ -1264,25 +1264,36 @@ const server = createServer((req, res) => {
       /**
        * `?lang=fr`: la misma ficha con las frases en francés.
        *
-       * Traduce este agente con su propio modelo y guarda el resultado, así
-       * que la primera petición en cada idioma cuesta una llamada y las demás
-       * ninguna. Si falla —sin clave, sin cuota, sin red— se sirve el original:
-       * no traducir no puede ser un error para quien pide la ficha.
+       * 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 traducido = await traducirFrases(
-          {
-            description: descripcion,
-            tiers: NIVELES_OK.map((n) => ({ name: n.name ?? '', description: n.description ?? '' })),
-          },
-          idioma,
-          LLM_FICHA,
-          DATA_DIR,
-        );
+        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];
@@ -1318,6 +1329,9 @@ const server = createServer((req, res) => {
         // 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: {

package/template/src/traduccion.ts

@@ -26,6 +26,22 @@
  * 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
@@ -55,11 +71,24 @@ export interface Frases {
 const MAX_FRASE = 400;
 
 /**
- * Cuánto se espera. Corto a propósito: esto corre DENTRO de una petición de la
- * ficha, y una tarjeta que tarda medio minuto en pintar es una tarjeta rota.
- * Lo que no llegue a tiempo sale sin traducir y se traducirá en la siguiente.
+ * 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 ESPERA_MS = 20_000;
+const enCurso = new Set<string>();
 
 /** La huella del texto original: si cambia, la traducción guardada ya no vale. */
 function huella(frases: Frases): string {
@@ -144,10 +173,42 @@ const SISTEMA =
   'stay short. Do not translate brand names, product names or code identifiers.';
 
 /**
- * Las frases de la ficha en otro idioma.
+ * 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, y quien llama sirve el
- * original: no traducir NUNCA puede ser un error para el que pide la ficha.
+ * 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,
@@ -165,7 +226,7 @@ export async function traducirFrases(
 
   try {
     const crudo = await llmChat(
-      { ...llm, timeoutMs: ESPERA_MS, maxRetries: 0 },
+      { ...llm, timeoutMs: ESPERA_MS, maxRetries: REINTENTOS },
       {
         system: SISTEMA,
         user: