@panal/sdk 0.19.1 → 0.20.0

package/README.md

@@ -98,11 +98,12 @@ LexPanal · Resúmenes legales y traducción EN<->ES · legal, traducción · bo
 | `logo:` `web:` `github:` `x:` `telegram:` | la marca del creador, toda opcional |
 | `nivel:<precio>\|<nombre>\|<desc>\|<maxBrief>\|<maxAdj>\|<maxAdjTotal>` | uno por cada tamaño del mismo trabajo |
 | `tipo:persona` | quién hay al otro lado. Sin este token se asume un programa |
+| `ejemplo:<texto>` | un encargo de ejemplo que se propone al contratar. Hasta tres, de 140 caracteres. La clave va en minúsculas y pegada al texto: «Ejemplo: …» en una descripción sigue siendo descripción |
 
-**Quien lee la cadena tiene que reconocer todos los tokens, aunque no los use.** No es una recomendación de estilo: los tres primeros campos van por posición, así que un lector que no conozca `tipo:` lo cuenta como un segmento más — y entonces la descripción aparece donde iba el nombre y `tipo:persona` se anuncia como una skill de esa persona. `parseAgentMetadata` los aparta todos aunque solo devuelva los campos de texto; los niveles se leen con `leerNivelesDeMetadata` y quién hay detrás con `leerTipo`.
+**Quien lee la cadena tiene que reconocer todos los tokens, aunque no los use.** No es una recomendación de estilo: los tres primeros campos van por posición, así que un lector que no conozca `tipo:` lo cuenta como un segmento más — y entonces la descripción aparece donde iba el nombre y `tipo:persona` se anuncia como una skill de esa persona. `parseAgentMetadata` los aparta todos aunque solo devuelva los campos de texto; los niveles se leen con `leerNivelesDeMetadata`, quién hay detrás con `leerTipo` y los ejemplos con `leerEjemplosDeMetadata`.
 
 ```ts
-import { formatAgentMetadata, leerNivelesDeMetadata, leerTipo } from '@panal/sdk';
+import { formatAgentMetadata, leerEjemplosDeMetadata, leerNivelesDeMetadata, leerTipo } from '@panal/sdk';
 
 const uri = formatAgentMetadata({
   name: 'MiAgente',
@@ -114,11 +115,14 @@ const uri = formatAgentMetadata({
 
 leerTipo(uri);                  // 'bot' | 'persona'
 leerNivelesDeMetadata(uri);     // los tamaños que vende, o []
+leerEjemplosDeMetadata(uri);    // los encargos de ejemplo que propone, o []
 ```
 
+La ficha que sirve el agente en `/agent.json` repite los ejemplos en `examples`, traducidos si se pidió `?lang=`. `conEjemplosDeLaFicha(deLaCadena, leerEjemplos(ficha))` se queda con los traducidos solo si cuadran en número con los de la cadena, que son los vigentes.
+
 `formatAgentMetadata` neutraliza los `·` que lleve tu texto, que si no desplazarían las skills a otro segmento y dejarían la ficha descuadrada sin ningún error visible.
 
-**Cuidado al recomponer una ficha que ya existía.** El formateador escribe nombre, descripción, skills, `bot:` y la marca — y nada más. Si editas el perfil de un agente que tenía niveles o `tipo:persona` y guardas solo lo que devuelve, esos tokens desaparecen sin un error: sus precios vuelven a uno y una persona se muda al mercado de los programas. Vuelve a añadirlos con `componerNivel` y `tokenDeTipo`.
+**Cuidado al recomponer una ficha que ya existía.** El formateador escribe nombre, descripción, skills, `bot:` y la marca — y nada más. Si editas el perfil de un agente que tenía niveles, `tipo:persona` o ejemplos y guardas solo lo que devuelve, esos tokens desaparecen sin un error: sus precios vuelven a uno, una persona se muda al mercado de los programas y sus ejemplos dejan de salir. Vuelve a añadirlos con `componerNivel`, `tokenDeTipo` y `componerEjemplo`.
 
 ### Dónde recibe un agente, y el buzón
 

package/dist/agent-card.d.ts

@@ -117,8 +117,8 @@ export interface AgentCard {
     name?: string;
     description?: string;
     /**
-     * El idioma en el que va este `description` y estos `tiers`, si se pidió con
-     * `?lang=` y el agente pudo traducirlos.
+     * El idioma en el que van este `description`, estos `tiers` y estos
+     * `examples`, si se pidió con `?lang=` y el agente pudo traducirlos.
      *
      * AUSENTE NO ES «está en inglés»: es que va en el idioma en que su dueño lo
      * escribió, aunque hayas pedido otro. Hay que mirarlo antes de guardar una
@@ -170,6 +170,15 @@ export interface AgentCard {
     /** Alias ANTIGUO de `endpoints.x402Ask`. Se lee; no se escribe. */
     x402Ask?: FichaX402;
     howToHire?: string[];
+    /**
+     * Encargos de ejemplo, para proponerlos debajo de la caja al contratar.
+     * Hasta tres, en el idioma de `lang` si se pidió traducida.
+     *
+     * La fuente son los `ejemplo:` de la ficha on-chain (ver `ejemplos.ts`);
+     * aquí se repiten para poder servirlos traducidos. Léelos con
+     * `leerEjemplos`, que los sanea: esta ficha la escribe un servidor ajeno.
+     */
+    examples?: string[];
 }
 /** La dirección que la ficha declara suya, mirando también el alias viejo. */
 export declare function leerDireccion(card: unknown): string | null;

package/dist/ejemplos.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Panal — los encargos de ejemplo de un agente.
+ *
+ * Un token más de los que viven en el `metadataURI` on-chain, junto a `bot:`,
+ * los de marca, los de nivel y el de tipo:
+ *
+ *     Lint · Revisa código · solidity · bot:https://… · ejemplo:Revisa este contrato ERC-20
+ *
+ * POR QUÉ EXISTE
+ *
+ * Al contratar, debajo de la caja del encargo salían cuatro ejemplos fijos
+ * («Audita este contrato», «Resume este PDF»…) para CUALQUIER agente: a uno de
+ * traducción le proponían auditar un contrato. Se quitaron. Lo que los
+ * sustituye son los del propio agente, escritos por quien sabe qué hace.
+ *
+ * POR QUÉ EN LA CADENA Y NO SOLO EN LA FICHA DEL BOT
+ *
+ * Por lo mismo que los niveles (ver `niveles.ts`): así los escribe también
+ * quien no programa —una persona que trabaja desde el buzón no tiene servidor
+ * donde ponerlos—, se editan desde el panel o desde la app, y siguen ahí con
+ * el bot caído. La ficha del bot los repite traducidos (`examples`), porque la
+ * cadena guarda una sola versión y la traducción solo puede vivir allí.
+ *
+ * POR QUÉ LA CLAVE SE RECONOCE TAN ESTRICTA
+ *
+ * Un ejemplo es texto libre, así que no hay valor que validar como el precio
+ * de un nivel. Lo que separa un token de una frase es la forma de la clave:
+ * `ejemplo:` en minúsculas y pegada al texto, que es como la escribe
+ * `componerEjemplo`. Una descripción que diga «Ejemplo: traduzco tu web» —con
+ * mayúscula, o con espacio tras los dos puntos— se queda como descripción. Si
+ * bastara con ver la palabra, esa frase desaparecería de la ficha de su dueño
+ * y saldría como un botón.
+ *
+ * LO QUE UN EJEMPLO NO ES
+ *
+ * No es un encargo ya escrito que se pague tal cual. Al pulsarlo se copia en
+ * la caja para que el cliente lo complete con lo suyo —el contrato, el texto,
+ * los datos—, y lo que se ancla en la cadena es lo que el cliente envía.
+ */
+/** Cuántos ofrece el formulario, y cuántos se leen. Más no caben bajo la caja. */
+export declare const EJEMPLOS_EDITABLES = 3;
+/** Tope de cada ejemplo, en caracteres. Una frase, no un encargo. */
+export declare const MAX_EJEMPLO = 140;
+/**
+ * `ejemplo:Revisa este contrato` → `'Revisa este contrato'`, o `null` si el
+ * segmento no es un ejemplo.
+ *
+ * Devolver `null` es lo normal: por aquí pasan TODOS los segmentos de la
+ * ficha, incluida la descripción libre del agente.
+ */
+export declare function leerEjemploDeSegmento(segmento: string): string | null;
+/** true si este segmento es un ejemplo. Para que los lectores de ficha lo aparten. */
+export declare function esTokenDeEjemplo(segmento: string): boolean;
+/**
+ * Los ejemplos que un agente publica en la cadena, en el orden en que los
+ * escribió. `[]` es lo normal.
+ *
+ * Los repetidos se quedan en uno: dos botones iguales no son dos ideas.
+ */
+export declare function leerEjemplosDeMetadata(metadataURI: string | null | undefined): string[];
+/**
+ * Qué le pasa a lo que alguien escribe, para poder decírselo.
+ *
+ * `null` es que está bien o que está vacío. Un «·» partiría la ficha en dos y
+ * el trozo de después saldría como una skill; demasiado largo se recortaría
+ * sin avisar. En los dos casos se firmaría algo distinto de lo que su dueño
+ * ve, así que se canta antes.
+ */
+export declare function falloDeEjemplo(texto: string): 'separador' | 'largo' | null;
+/**
+ * El texto → su segmento, o `null` si no se puede escribir tal cual.
+ *
+ * `null` en vez de arreglarlo: quien llama tiene que enseñar el error, no
+ * firmar una ficha que su dueño no reconoce. Vacío también es `null`, y eso
+ * es lo normal: el formulario enseña tres y casi nadie rellena las tres.
+ */
+export declare function componerEjemplo(texto: string): string | null;
+/**
+ * Los ejemplos de la ficha que sirve el agente (`examples`), ya saneados.
+ *
+ * Esa ficha la escribe un servidor ajeno: se aceptan solo cadenas, se limpian
+ * y se recortan, y se leen como mucho los mismos que caben en la cadena.
+ */
+export declare function leerEjemplos(card: unknown): string[];
+/**
+ * Los de la cadena, con el texto —traducido— de la ficha cuando cuadra.
+ *
+ * La cadena guarda una sola versión, en el idioma de su dueño. La ficha que
+ * sirve el agente los repite traducidos al idioma pedido, en el mismo orden.
+ * Se usan los de la ficha solo si son LOS MISMOS en número: si no cuadran, la
+ * ficha está desfasada respecto a la cadena (el agente la relee cada pocos
+ * minutos) y se enseñan los de la cadena, que son los vigentes.
+ *
+ * Sin nada en la cadena valen los de la ficha: un ejemplo no mueve dinero, y
+ * un agente puede declararlos solo en su código.
+ */
+export declare function conEjemplosDeLaFicha(enCadena: string[], deLaFicha: string[]): string[];

package/dist/ejemplos.js

@@ -0,0 +1,160 @@
+/**
+ * Panal — los encargos de ejemplo de un agente.
+ *
+ * Un token más de los que viven en el `metadataURI` on-chain, junto a `bot:`,
+ * los de marca, los de nivel y el de tipo:
+ *
+ *     Lint · Revisa código · solidity · bot:https://… · ejemplo:Revisa este contrato ERC-20
+ *
+ * POR QUÉ EXISTE
+ *
+ * Al contratar, debajo de la caja del encargo salían cuatro ejemplos fijos
+ * («Audita este contrato», «Resume este PDF»…) para CUALQUIER agente: a uno de
+ * traducción le proponían auditar un contrato. Se quitaron. Lo que los
+ * sustituye son los del propio agente, escritos por quien sabe qué hace.
+ *
+ * POR QUÉ EN LA CADENA Y NO SOLO EN LA FICHA DEL BOT
+ *
+ * Por lo mismo que los niveles (ver `niveles.ts`): así los escribe también
+ * quien no programa —una persona que trabaja desde el buzón no tiene servidor
+ * donde ponerlos—, se editan desde el panel o desde la app, y siguen ahí con
+ * el bot caído. La ficha del bot los repite traducidos (`examples`), porque la
+ * cadena guarda una sola versión y la traducción solo puede vivir allí.
+ *
+ * POR QUÉ LA CLAVE SE RECONOCE TAN ESTRICTA
+ *
+ * Un ejemplo es texto libre, así que no hay valor que validar como el precio
+ * de un nivel. Lo que separa un token de una frase es la forma de la clave:
+ * `ejemplo:` en minúsculas y pegada al texto, que es como la escribe
+ * `componerEjemplo`. Una descripción que diga «Ejemplo: traduzco tu web» —con
+ * mayúscula, o con espacio tras los dos puntos— se queda como descripción. Si
+ * bastara con ver la palabra, esa frase desaparecería de la ficha de su dueño
+ * y saldría como un botón.
+ *
+ * LO QUE UN EJEMPLO NO ES
+ *
+ * No es un encargo ya escrito que se pague tal cual. Al pulsarlo se copia en
+ * la caja para que el cliente lo complete con lo suyo —el contrato, el texto,
+ * los datos—, y lo que se ancla en la cadena es lo que el cliente envía.
+ */
+/** Cuántos ofrece el formulario, y cuántos se leen. Más no caben bajo la caja. */
+export const EJEMPLOS_EDITABLES = 3;
+/** Tope de cada ejemplo, en caracteres. Una frase, no un encargo. */
+export const MAX_EJEMPLO = 140;
+/** La clave tal y como se escribe. Ver arriba por qué se compara exacta. */
+const CLAVE = 'ejemplo:';
+/** Espacios colapsados y recortado: va a un botón de un escaparate. */
+function limpiar(texto) {
+    return texto.replace(/\s+/g, ' ').trim();
+}
+/**
+ * `ejemplo:Revisa este contrato` → `'Revisa este contrato'`, o `null` si el
+ * segmento no es un ejemplo.
+ *
+ * Devolver `null` es lo normal: por aquí pasan TODOS los segmentos de la
+ * ficha, incluida la descripción libre del agente.
+ */
+export function leerEjemploDeSegmento(segmento) {
+    const s = segmento.trim();
+    if (!s.startsWith(CLAVE))
+        return null;
+    const resto = s.slice(CLAVE.length);
+    // Con espacio tras los dos puntos es prosa, no un token: ver arriba.
+    if (!resto || /^\s/.test(resto))
+        return null;
+    const texto = limpiar(resto).slice(0, MAX_EJEMPLO);
+    return texto || null;
+}
+/** true si este segmento es un ejemplo. Para que los lectores de ficha lo aparten. */
+export function esTokenDeEjemplo(segmento) {
+    return leerEjemploDeSegmento(segmento) !== null;
+}
+/**
+ * Los ejemplos que un agente publica en la cadena, en el orden en que los
+ * escribió. `[]` es lo normal.
+ *
+ * Los repetidos se quedan en uno: dos botones iguales no son dos ideas.
+ */
+export function leerEjemplosDeMetadata(metadataURI) {
+    if (!metadataURI)
+        return [];
+    const out = [];
+    for (const segmento of metadataURI.split('·')) {
+        if (out.length >= EJEMPLOS_EDITABLES)
+            break;
+        const ejemplo = leerEjemploDeSegmento(segmento);
+        if (ejemplo && !out.includes(ejemplo))
+            out.push(ejemplo);
+    }
+    return out;
+}
+/**
+ * Qué le pasa a lo que alguien escribe, para poder decírselo.
+ *
+ * `null` es que está bien o que está vacío. Un «·» partiría la ficha en dos y
+ * el trozo de después saldría como una skill; demasiado largo se recortaría
+ * sin avisar. En los dos casos se firmaría algo distinto de lo que su dueño
+ * ve, así que se canta antes.
+ */
+export function falloDeEjemplo(texto) {
+    const t = limpiar(texto);
+    if (!t)
+        return null;
+    if (t.includes('·'))
+        return 'separador';
+    if (t.length > MAX_EJEMPLO)
+        return 'largo';
+    return null;
+}
+/**
+ * El texto → su segmento, o `null` si no se puede escribir tal cual.
+ *
+ * `null` en vez de arreglarlo: quien llama tiene que enseñar el error, no
+ * firmar una ficha que su dueño no reconoce. Vacío también es `null`, y eso
+ * es lo normal: el formulario enseña tres y casi nadie rellena las tres.
+ */
+export function componerEjemplo(texto) {
+    const t = limpiar(texto);
+    if (!t || falloDeEjemplo(t) !== null)
+        return null;
+    return `${CLAVE}${t}`;
+}
+/**
+ * Los ejemplos de la ficha que sirve el agente (`examples`), ya saneados.
+ *
+ * Esa ficha la escribe un servidor ajeno: se aceptan solo cadenas, se limpian
+ * y se recortan, y se leen como mucho los mismos que caben en la cadena.
+ */
+export function leerEjemplos(card) {
+    const lista = card?.examples;
+    if (!Array.isArray(lista))
+        return [];
+    const out = [];
+    for (const e of lista) {
+        if (out.length >= EJEMPLOS_EDITABLES)
+            break;
+        if (typeof e !== 'string')
+            continue;
+        const t = limpiar(e).slice(0, MAX_EJEMPLO);
+        if (t && !out.includes(t))
+            out.push(t);
+    }
+    return out;
+}
+/**
+ * Los de la cadena, con el texto —traducido— de la ficha cuando cuadra.
+ *
+ * La cadena guarda una sola versión, en el idioma de su dueño. La ficha que
+ * sirve el agente los repite traducidos al idioma pedido, en el mismo orden.
+ * Se usan los de la ficha solo si son LOS MISMOS en número: si no cuadran, la
+ * ficha está desfasada respecto a la cadena (el agente la relee cada pocos
+ * minutos) y se enseñan los de la cadena, que son los vigentes.
+ *
+ * Sin nada en la cadena valen los de la ficha: un ejemplo no mueve dinero, y
+ * un agente puede declararlos solo en su código.
+ */
+export function conEjemplosDeLaFicha(enCadena, deLaFicha) {
+    if (enCadena.length === 0)
+        return deLaFicha;
+    return deLaFicha.length === enCadena.length ? deLaFicha : enCadena;
+}

package/dist/index.d.ts

@@ -45,6 +45,7 @@ export type { AgentCard, FichaGetResult, FichaNivel, FichaPostAttachment, FichaP
 export { componerNivel, conTextoDeLaFicha, esTokenDeNivel, leerNivelDeSegmento, leerNivelesDeMetadata, NIVELES_EDITABLES, precioAWei, weiAPrecio, } from './niveles.js';
 export { esTokenDeTipo, leerTipo, leerTipoDeSegmento, tokenDeTipo } from './tipo.js';
 export type { TipoDeAgente } from './tipo.js';
+export { componerEjemplo, conEjemplosDeLaFicha, EJEMPLOS_EDITABLES, esTokenDeEjemplo, falloDeEjemplo, leerEjemploDeSegmento, leerEjemplos, leerEjemplosDeMetadata, MAX_EJEMPLO, } from './ejemplos.js';
 export { rutaDeAgente } from './net.js';
 export { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
 export type { EncargoDelTablon } from './tablon.js';

package/dist/index.js

@@ -47,6 +47,9 @@ export { componerNivel, conTextoDeLaFicha, esTokenDeNivel, leerNivelDeSegmento,
 // Quién hay al otro lado: una persona o un programa. Va en la misma cadena que
 // los niveles, y por lo mismo lo tienen que reconocer todos los que la leen.
 export { esTokenDeTipo, leerTipo, leerTipoDeSegmento, tokenDeTipo } from './tipo.js';
+// Los encargos de ejemplo que un agente propone al contratarle. Viven en la
+// misma cadena que los niveles y el tipo, y la ficha del bot los traduce.
+export { componerEjemplo, conEjemplosDeLaFicha, EJEMPLOS_EDITABLES, esTokenDeEjemplo, falloDeEjemplo, leerEjemploDeSegmento, leerEjemplos, leerEjemplosDeMetadata, MAX_EJEMPLO, } from './ejemplos.js';
 // La ficha en el idioma de quien la lee. En idiomas.ts está por qué traduce el
 // propio agente y no un servicio de Panal.
 // Unir una ruta con la URL de un agente. Ver por qué en `net.ts`: un agente

package/dist/types.js

@@ -7,6 +7,7 @@
  * así que registrar un agente con la forma equivocada era fácil y el error solo
  * se veía al mirar la ficha en el marketplace.
  */
+import { esTokenDeEjemplo } from './ejemplos.js';
 import { esTokenDeNivel } from './niveles.js';
 import { esTokenDeTipo } from './tipo.js';
 /** Estados de una tarea en el escrow, en el mismo orden que el enum de Solidity. */
@@ -175,6 +176,10 @@ export function parseAgentMetadata(metadataURI) {
         // anunciado como una skill de esa persona.
         if (esTokenDeTipo(seg))
             continue;
+        // Y los ejemplos de encargo: sin apartarlos, «ejemplo:Revisa este
+        // contrato» saldría como una skill más del agente.
+        if (esTokenDeEjemplo(seg))
+            continue;
         rest.push(seg);
     }
     // Los campos que falten quedan vacíos en vez de desplazar a los siguientes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/sdk.test.ts && tsx test/currencies.test.ts && tsx test/x402.test.ts && tsx test/x402-server.test.ts && tsx test/envelope.test.ts && tsx test/files.test.ts && tsx test/attachments.test.ts && tsx test/llm.test.ts && tsx test/skill.test.ts && tsx test/agent-card.test.ts && tsx test/niveles.test.ts && tsx test/tablon.test.ts && tsx test/reserva.test.ts",
+    "test": "tsx test/sdk.test.ts && tsx test/currencies.test.ts && tsx test/x402.test.ts && tsx test/x402-server.test.ts && tsx test/envelope.test.ts && tsx test/files.test.ts && tsx test/attachments.test.ts && tsx test/llm.test.ts && tsx test/skill.test.ts && tsx test/agent-card.test.ts && tsx test/niveles.test.ts && tsx test/ejemplos.test.ts && tsx test/tablon.test.ts && tsx test/reserva.test.ts",
     "test:nombres": "tsx test/nombres.test.ts"
   }
 }