create-panal-agent 0.21.0 → 0.22.0

package/README.md

@@ -115,10 +115,23 @@ 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.
+X402_TOKEN=USDC        # PANAL (por defecto), MON, GHO, USDC o AUSD
 ```
 
-Va en un token EIP-2612 (`$PANAL` por defecto): el esquema necesita `permit`, así que no
-puede ser MON nativo.
+El precio se lee **en la moneda que elijas**, con sus decimales: `0.05` en USDC son cinco
+céntimos, en $PANAL son 0,05 $PANAL. La lista de monedas es fija y viene del SDK
+(`x402Currencies()`): con cualquier otra cosa en `X402_TOKEN` el servidor lo dice al
+arrancar y el cobro por llamada queda apagado, en vez de cobrar en algo que ningún cliente
+de Panal acepta pagar.
+
+Cómo se paga depende de la moneda:
+
+- **$PANAL, GHO, USDC y AUSD** tienen `permit` (EIP-2612): el cliente firma una
+  autorización, sin gas, y tu servidor ejecuta el cobro antes de contestar.
+- **MON** no tiene `permit`, así que el cliente **manda** la transferencia y paga él su gas.
+  La cotización pide el precio más unas unidades al azar (menos de una millonésima de
+  céntimo), y tu servidor comprueba en la cadena que llegó *esa* transferencia exacta, a tu
+  dirección y dentro de plazo. Cada transacción se acepta una sola vez.
 
 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 —
@@ -144,9 +157,10 @@ buscando `video`. Un agente de código pagándole a uno de vídeo entrega algo q
 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
+El presupuesto va en la moneda de `X402_TOKEN`, **no** es un porcentaje de lo que cobras:
+tus encargos pueden ir en MON y tus preguntas en USDC, y convertir una cosa en otra a ojo
+sería inventarse el número. Por eso tu agente solo subcontrata a quien cobre en esa misma
+moneda. 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.
 
@@ -195,6 +209,21 @@ El escaparate habla diez idiomas; tu descripción, uno. `GET /agent.json?lang=fr
 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.
 
+### Encargos de ejemplo
+
+Quien te contrata ve, debajo de la caja del encargo, hasta **tres ejemplos de lo que te
+puede pedir**, escritos por ti. Se ponen desde el panel de [panal.lat](https://panal.lat)
+o desde la app, en «Editar ficha», y se guardan en tu ficha on-chain como
+`ejemplo:<texto>`. No hay que tocar código: tu servidor los relee de la cadena cada cinco
+minutos y los sirve en `/agent.json` (`examples`), traducidos como tu descripción.
+
+Escribe lo que de verdad te piden, en una frase. Al pulsarlo, el cliente lo copia en la caja
+y lo completa con lo suyo —el contrato, el texto, los datos—: un ejemplo no es un encargo
+listo para pagar.
+
+`npm run register` reescribe la ficha entera desde `PERFIL` y **borra** los niveles y los
+ejemplos que pusiste desde el panel. Si ya estás registrado, edita la ficha desde el panel.
+
 ### 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.
@@ -241,3 +270,5 @@ Y pregúntale a Claude *«¿qué agentes hay en Panal?»*. Si sales, cualquiera
 ## Licencia
 
 MIT — [código en GitHub](https://github.com/AgentHiv/Panal).
+
+La licencia cubre el código, no la marca. El nombre **Panal** y su logo son marcas de Panal y Kreno y no entran en la MIT: un fork es bienvenido, pero necesita un nombre y un logo propios.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.21.0",
+  "version": "0.22.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.19.0",
+    "@panal/sdk": "^0.20.0",
     "unpdf": "^1.8.1",
     "dotenv": "^17.0.0",
     "tsx": "^4.19.0",

package/template/src/server.ts

@@ -31,6 +31,7 @@ import {
   assertCanServe,
   buildQuote,
   createPanalClient,
+  leerEjemplosDeMetadata,
   leerNiveles,
   leerNivelesDeMetadata,
   normalizarIdioma,
@@ -269,6 +270,15 @@ const NIVELES_DEL_CODIGO = NIVELES_OK;
  */
 let FICHA_TEXTO: { name: string; description: string } = { name: '', description: '' };
 
+/**
+ * Los encargos de ejemplo que este agente propone al contratarle.
+ *
+ * Viven en la cadena (`ejemplo:` en la ficha) y se editan desde el panel de la
+ * web o desde la app, sin tocar este código. Se releen con los niveles, cada
+ * cinco minutos, y se sirven en `/agent.json` traducidos como la descripción.
+ */
+let EJEMPLOS_OK: string[] = [];
+
 async function refrescarNiveles(): Promise<void> {
   try {
     const ficha = await panal.getAgent(account.address);
@@ -276,6 +286,7 @@ async function refrescarNiveles(): Promise<void> {
       name: ficha.metadata.name,
       description: ficha.metadata.description,
     };
+    EJEMPLOS_OK = leerEjemplosDeMetadata(ficha.metadataURI);
     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;
@@ -1318,6 +1329,7 @@ const server = createServer((req, res) => {
        */
       const idioma = normalizarIdioma(url.searchParams.get('lang'));
       const nivelesFicha = NIVELES_OK.map(comoFicha);
+      let ejemplos = EJEMPLOS_OK;
       let descripcion = FICHA_TEXTO.description;
       /**
        * En qué idioma va lo que se sirve, y `null` si va en el original.
@@ -1335,6 +1347,9 @@ const server = createServer((req, res) => {
         const frases = {
           description: descripcion,
           tiers: NIVELES_OK.map((n) => ({ name: n.name ?? '', description: n.description ?? '' })),
+          // Sin campo si no hay: la huella de la ficha no cambia y lo que ya
+          // estaba traducido sigue valiendo.
+          ...(EJEMPLOS_OK.length > 0 ? { examples: EJEMPLOS_OK } : {}),
         };
         const traducido = frasesGuardadas(frases, idioma, DATA_DIR);
         if (!traducido) pedirTraduccion(frases, idioma, LLM_FICHA, DATA_DIR);
@@ -1349,6 +1364,7 @@ const server = createServer((req, res) => {
             if (destino.name && t.name) destino.name = t.name;
             if (destino.description && t.description) destino.description = t.description;
           });
+          if (traducido.examples?.length === EJEMPLOS_OK.length) ejemplos = traducido.examples;
         }
       }
       const x402 =
@@ -1418,6 +1434,9 @@ 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.
         ...(nivelesFicha.length > 0 ? { tiers: nivelesFicha } : {}),
+        // Los encargos de ejemplo, en el mismo idioma que la descripción. Los
+        // escribe su dueño en la ficha de la cadena; ausente es que no hay.
+        ...(ejemplos.length > 0 ? { examples: ejemplos } : {}),
         // 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

@@ -12,7 +12,7 @@
  *
  * 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.
+ * mirando `description`, `tiers[].name` y `examples`, solo que traducidos.
  *
  * QUÉ CUESTA, QUE ES LA PREGUNTA DE VERDAD
  *
@@ -65,6 +65,12 @@ 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 }[];
+  /**
+   * Los encargos de ejemplo, en su orden. Sin campo cuando no hay ninguno, y
+   * a propósito: así la huella de una ficha sin ejemplos es la de siempre y
+   * sus traducciones ya guardadas siguen valiendo.
+   */
+  examples?: string[];
 }
 
 /** Tope de la respuesta que se acepta del modelo, por frase. */
@@ -144,7 +150,20 @@ function validar(v: unknown, original: Frases | null): Frases | null {
     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 };
+  // Los ejemplos, con la misma regla que los niveles: los mismos en número o
+  // se descarta todo. Si el original no tiene, no se esperan.
+  const crudos = (v as Record<string, unknown>).examples;
+  let examples: string[] = [];
+  if ((original?.examples?.length ?? 0) > 0 || crudos !== undefined) {
+    if (!Array.isArray(crudos) || crudos.some((e) => typeof e !== 'string')) return null;
+    if (original && crudos.length !== (original.examples?.length ?? 0)) return null;
+    examples = (crudos as string[]).map((e) => e.trim().slice(0, MAX_FRASE));
+  }
+  return {
+    description: description.trim().slice(0, MAX_FRASE),
+    tiers: salida,
+    ...(examples.length > 0 ? { examples } : {}),
+  };
 }
 
 /** El JSON que venga, aunque llegue envuelto en un bloque de markdown. */