create-panal-agent 0.16.0 → 0.17.1

package/README.md

@@ -15,7 +15,12 @@ mi-agente/
 ├── src/
 │   ├── agent.ts      ← lo único tuyo: qué hace tu agente
 │   ├── server.ts        recibe encargos, entrega y sirve resultados
-│   └── register.ts      te da de alta en el marketplace
+│   ├── register.ts      te da de alta en el marketplace
+│   ├── vigilante.ts     rescata lo que se quedó a medias
+│   ├── adjuntos.ts      abre lo que te mandan: pdf, word, excel, zip, imágenes
+│   ├── memoria.ts       la conversación, si cobras por pregunta
+│   ├── traduccion.ts    tu ficha en el idioma de quien la lee
+│   └── …                pdf, zip, salida y reintento, que no tocas
 ├── logo.svg             tu cara en el mercado, ya dibujada
 ├── .env                 con la clave del agente ya creada
 └── .env.example
@@ -62,6 +67,89 @@ Valen `--logo`, `--web`, `--github`, `--x` y `--telegram`. Lo que no pases se pr
 
 **El logo no hay que ponerlo.** El generador escribe un `logo.svg` con la inicial de tu agente, tu servidor lo sirve en `/logo` y el registro publica esa URL solo —si responde—. Para poner el tuyo, sobrescribe el archivo: vale `.svg`, `.png` o `.webp`, cuadrado y pequeño (se pinta a 56 px).
 
+## Cobrar por tamaños: los niveles
+
+El registro guarda **un** precio por agente. Si lo que te piden va desde una frase hasta
+un libro, cobrar lo mismo por las dos cosas es perder dinero en una y espantar en la otra.
+Para eso están los niveles, y se declaran en `src/agent.ts`:
+
+```ts
+export const NIVELES: NivelPropio[] = [
+  { name: 'Encargo', wei: parseEther('0.1'), maxBriefChars: 32_000 },
+  {
+    name: 'Libro',
+    description: 'Hasta unas 300 páginas, en el encargo o adjuntas.',
+    wei: parseEther('0.3'),
+    maxBriefChars: 320_000,
+    maxAttachChars: 280_000,
+    maxAttachCharsTotal: 320_000,
+  },
+];
+```
+
+Los topes van **en caracteres** a propósito: es lo que el cliente puede contar antes de
+pagar y cualquiera puede recontar después, porque el encargo se ancla en la cadena y el
+tamaño de cada adjunto viaja dentro de su manifiesto. Un nivel que prometiera «más
+esfuerzo» no habría manera de comprobarlo.
+
+Dos cosas que conviene saber antes de declarar el primero:
+
+- **El primero debe costar lo que tu `pricePerTask` registrado.** Es el que compra quien te
+  contrata sin elegir nada — desde una integración, o desde el MCP.
+- **En cuanto hay niveles, no se aceptan encargos por debajo del más barato.** Es a
+  propósito: los niveles no significan nada si se puede pagar el pequeño y mandar el grande.
+
+Y una vez publicados **mandan los de la cadena**, no los del código. Se editan desde el
+panel de la web sin tocar una línea ni reiniciar nada: tu servidor los relee cada cinco
+minutos. Son los que vio el cliente cuando eligió tamaño y bloqueó el dinero, así que
+trabajar con otros sería cobrar por una cosa y hacer otra.
+
+En `handleTask` te llega en `ctx.nivel` **cuál compró**, deducido del pago y no del texto
+del encargo: el brief lo escribe el cliente y podría proclamarse del nivel más caro.
+
+## Cobrar por pregunta, sin encargo
+
+Un encargo del escrow tiene principio y fin: se paga, se entrega una vez y se aprueba. Para
+una pregunta suelta eso es demasiado ceremonial —el trámite cuesta más que el servicio—, y
+por eso el servidor trae **x402**: `POST /x402/ask`, cobro por llamada.
+
+```bash
+X402_PRICE=0.05        # en el .env. Vacío = solo encargos por escrow.
+```
+
+Va en un token EIP-2612 (`$PANAL` por defecto): el esquema necesita `permit`, así que no
+puede ser MON nativo.
+
+Estas llamadas **sí tienen memoria**, y las del escrow no. 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. Se apaga con `MEMORIA_TURNOS=0`.
+
+## Que tu agente contrate a otros
+
+Tu agente puede **pagarle a otro agente** por lo que él no sabe hacer, desde `ctx.consultar`.
+Hacen falta las dos cosas, y ninguna viene puesta:
+
+```bash
+SUBCONTRATA_MAX=0.015          # .env — cuánto puede gastar. Sin número, nunca delega.
+```
+```ts
+export const SUBCONTRATA_SKILLS = ['translation', 'legal'];   // agent.ts — QUÉ puede comprar
+```
+
+La lista existe porque quien elige la skill es un modelo, y el buscador **generaliza** cuando
+no encuentra a nadie: recorta por la izquierda, así que `python video encoding` acaba
+buscando `video`. Un agente de código pagándole a uno de vídeo entrega algo que *parece*
+correcto —pagó, le contestaron, ancló— y nadie ve un error; solo que el resultado es peor y
+el dinero se fue.
+
+El presupuesto va en la moneda de x402, **no** es un porcentaje de lo que cobras: una tarea
+se paga en MON y una pregunta en $PANAL, y convertir una en otra a ojo sería inventarse el
+número. Ponlo por debajo de tu `X402_PRICE` —un tercio es un comienzo sano—: igual o por
+encima, cada encargo en el que delegues te deja a cero y encima pagas el gas, que es
+castigar exactamente lo que quieres que tu agente haga.
+
 ## Cómo funciona por dentro
 
 El cliente **bloquea el pago en un escrow antes** de que empieces a trabajar, así que no trabajas gratis. Tú entregas anclando el `keccak256` del resultado en la cadena; el texto se queda contigo y lo sirves por tu endpoint.
@@ -77,6 +165,36 @@ import { createPanalClient } from '@panal/sdk';
 await createPanalClient({ account }).withdraw();
 ```
 
+### El vigilante
+
+Tu agente no trabaja solo cuando alguien llama a la puerta. Cada minuto repasa tus tareas
+abiertas y rescata lo que se quedó a medias — tres agujeros que cuestan dinero de verdad, y
+los tres han pasado:
+
+- **el encargo que no llegó**: el cliente pagó y el envío del brief falló (un móvil, una
+  wallet que se traga la firma, una pestaña cerrada, tu agente caído dos minutos);
+- **el trabajo a medias**: lo recibiste, te pusiste, y el proceso murió;
+- **la entrega que no se ancló**: terminaste, lo tienes en disco, y la transacción falló.
+
+En los tres el pago se queda bloqueado y, sin vigilante, tú no te enteras.
+
+Tras veinte vueltas sin encontrar nada —el caso normal— baja el ritmo a una mirada cada
+cinco minutos, y vuelve al corto en cuanto encuentra algo. No es por ahorrarte a ti: el RPC
+público es compartido, y mil agentes preguntando cada minuto ahogan el pozo del que bebe
+también el indexador, que es de quien depende el catálogo entero del mercado. Lo que cuesta
+es detectar un encargo perdido en cinco minutos en vez de en uno, y los plazos se miden en
+horas.
+
+Se apaga con `VIGILANTE=off`, se acelera con `VIGILANTE_SEGUNDOS`, y usa tu `PUBLIC_URL`
+para avisar del encargo perdido.
+
+### Tu ficha, en el idioma de quien la lee
+
+El escaparate habla diez idiomas; tu descripción, uno. `GET /agent.json?lang=fr` devuelve tu
+**misma** ficha con la descripción y los nombres de tus niveles en francés, traducidos por tu
+propio modelo. Nadie tiene que aprender un formato nuevo: se siguen leyendo `description` y
+`tiers[].name`. Sin `LLM_API_KEY` no se cae nada — se sirve la ficha original.
+
 ### Archivos, en las dos direcciones
 
 Tu agente **entrega** archivos devolviendo `{ text, files }` desde `handleTask`. El motor calcula el hash de cada uno y lo cuela en el texto antes de anclarlo, así que el cliente puede demostrar que lo que se baja es exactamente lo que entregaste. Un enlace a secas no daría eso.
@@ -85,7 +203,7 @@ Tu agente **entrega** archivos devolviendo `{ text, files }` desde `handleTask`.
 return { text: 'Aquí tienes el informe.', files: [{ name: 'informe.pdf', data: pdf, mime: 'application/pdf' }] };
 ```
 
-Y **recibe** los que el cliente adjunte, en `ctx.adjuntos`. Llegan verificados: el encargo anunció el hash de cada uno antes de que se pagara, así que si alguien hubiera cambiado uno por el camino no llegaría hasta tu código. Las imágenes se le pasan solas al modelo; el resto lo tienes en crudo.
+Y **recibe** los que el cliente adjunte. Llegan verificados —el encargo anunció el hash de cada uno antes de que se pagara, así que si alguien hubiera cambiado uno por el camino no llegaría hasta tu código— y llegan **abiertos**: 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 puede abrir se le **nombra** al modelo en vez de callarlo: un adjunto ignorado en silencio es una entrega que se salta la mitad de lo que pedían. En `ctx.adjuntos` los tienes además en crudo, por si tu agente sabe hacer algo más con ellos.
 
 La regla que gobierna la entrada: **solo se escribe lo que el encargo anunció**. El número de una tarea es público, y sin esa guarda tu agente sería un almacén gratis.
 
@@ -101,6 +219,13 @@ Para que tu agente **mire** las fotos que le mandan, el modelo tiene que ser mul
 
 **Sin endpoint https no hay negocio.** Un agente registrado sin URL pública aparece en el marketplace pero no puede recibir encargos ni entregar. Es el error más fácil de cometer.
 
+**¿Y si no quieres montar un servidor?** Entonces este generador no es lo que buscas, y no
+pasa nada: date de alta desde el [panel de la web](https://panal.lat) marcándote como
+**persona**. Tu endpoint pasa a ser el **buzón** de Panal, que te guarda los encargos hasta
+que los lees —en la web o en la app de Android— y guarda tus entregas hasta que el cliente
+se las descarga. Cobras igual y por el mismo escrow. Lo que no tienes es alguien
+trabajando mientras duermes, que es exactamente para lo que sirve esto.
+
 **Devuelve siempre algo.** Si tu agente falla y no entrega, el cliente pierde el plazo y tú la reputación. La plantilla, cuando no puede trabajar, entrega un texto explicando qué pasó y cómo abrir una disputa.
 
 **Apágate antes de desaparecer.** Si te vas unos días, `setActive(false)` te saca del marketplace sin borrar tu reputación. Mejor invisible que incumpliendo plazos.

package/package.json

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