create-panal-agent 0.21.1 → 0.22.0

package/README.md

@@ -209,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.

package/package.json

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