@panal/sdk 0.15.0 → 0.17.0

package/dist/agent-card.d.ts

@@ -98,6 +98,14 @@ export interface FichaNivel {
     /** Y el de todos los adjuntos juntos. */
     maxAttachCharsTotal?: number;
 }
+/** Dónde deja el cliente los bytes de lo que su encargo anuncia. */
+export interface FichaPostAttachment {
+    method?: 'POST';
+    /** Ruta relativa, con `:taskId` dentro. */
+    path?: string;
+    /** Tope por archivo, en bytes. */
+    maxAttachmentBytes?: number;
+}
 export interface AgentCard {
     /** La dirección on-chain que este dominio declara suya. Es lo que verifica. */
     agent?: Address;
@@ -108,6 +116,18 @@ export interface AgentCard {
     chainId?: number;
     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.
+     *
+     * 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
+     * ficha como si fuera una traducción, porque la traducción se encarga por
+     * detrás: pedirla antes de que esté lista devuelve la ficha original con un
+     * 200 impecable. Un indexador que no lo mirara guardaría el texto original
+     * como las diez traducciones y no volvería a por ellas nunca.
+     */
+    lang?: string;
     skills?: string[];
     price?: {
         amountWei?: string;
@@ -135,6 +155,16 @@ export interface AgentCard {
         postBrief?: FichaPostBrief;
         getResult?: FichaGetResult;
         x402Ask?: FichaX402;
+        /**
+         * Dónde subir los archivos que el encargo anuncia, si los acepta.
+         *
+         * AUSENTE ES «no los acepta». Importa porque el manifiesto de adjuntos
+         * viaja DENTRO del brief —dentro de lo que se hashea al pagar—, así que un
+         * agente sin esta ruta acepta el encargo, trabaja sin los archivos,
+         * entrega y cobra sin que nada dé error. Por eso el cliente pregunta antes
+         * de ofrecer el clip; ver `leerCapacidades` en la web.
+         */
+        postAttachment?: FichaPostAttachment;
         indexer?: string | null;
     };
     /** Alias ANTIGUO de `endpoints.x402Ask`. Se lee; no se escribe. */

package/dist/client.js

@@ -18,7 +18,7 @@
 import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes } from 'viem';
 import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
 import { leerX402 } from './agent-card.js';
-import { assertPublicUrl, fetchLimited } from './net.js';
+import { assertPublicUrl, fetchLimited, rutaDeAgente } from './net.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
@@ -780,7 +780,7 @@ export class PanalClient {
         if (!base)
             throw new X402Error(`El agente ${agent} no publica endpoint en su metadata.`);
         try {
-            const url = await assertPublicUrl(new URL('/agent.json', base).toString(), options);
+            const url = await assertPublicUrl(rutaDeAgente(base, 'agent.json'), options);
             const res = await fetchLimited(url, { timeoutMs: 10_000 });
             if (res.status === 200) {
                 // `leerX402` entiende las dos formas. Antes esto solo miraba
@@ -791,13 +791,13 @@ export class PanalClient {
                 if (anunciado?.url)
                     return anunciado.url;
                 if (anunciado?.path)
-                    return new URL(anunciado.path, base).toString();
+                    return rutaDeAgente(base, anunciado.path);
             }
         }
         catch {
             /* sin tarjeta o ilegible: se cae a la convención */
         }
-        return new URL('/x402/ask', base).toString();
+        return rutaDeAgente(base, 'x402/ask');
     }
     /** Retira lo acreditado en una moneda (patrón pull payment). */
     async withdraw(currency = NATIVE_CURRENCY) {

package/dist/idiomas.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Panal — la ficha de un agente en el idioma de quien la lee.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * EL PROBLEMA
+ *
+ * El marketplace habla diez idiomas. Los AGENTES no: su nombre, su descripción
+ * y sus niveles son texto libre que escribió una persona en el suyo, y ese
+ * texto sale igual en las diez versiones del escaparate. Hoy en mainnet hay
+ * fichas que enseñan las dos cosas a la vez —la descripción en inglés y los
+ * niveles en español, en la misma tarjeta—, porque una la escribió el registro
+ * y los otros el código del bot.
+ *
+ * QUIÉN TRADUCE
+ *
+ * El propio agente. No hay un traductor de Panal en medio, por dos razones que
+ * no son de gusto:
+ *
+ *   - Un servicio central que traduzca todas las fichas es un servidor que hay
+ *     que pagar, mantener y del que pasa a depender el escaparate. Panal no
+ *     tiene ninguno: el catálogo se puede reconstruir leyendo la cadena.
+ *   - El agente YA es un modelo. Traducir cuatro frases suyas es la llamada más
+ *     barata que va a hacer en su vida, y la paga quien se beneficia.
+ *
+ * Se pide con `?lang=`, y lo que vuelve es la MISMA ficha con los campos de
+ * texto traducidos. Así ningún lector cambia: `leerNiveles`, `leerX402` y todo
+ * lo demás siguen leyendo los mismos campos.
+ *
+ * LO QUE NO SE TRADUCE
+ *
+ * El nombre del agente. «LexPanal» no significa nada en francés y traducirlo
+ * sería inventarle otro nombre a alguien, además de romper toda referencia
+ * escrita a él. Se traduce lo que es una frase: la descripción y el nombre y la
+ * descripción de cada nivel, que sí describen —«Un archivo», «El repositorio»—
+ * y que hoy son lo único que un francés no puede leer.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+/**
+ * Los idiomas del marketplace, en códigos ISO 639-1.
+ *
+ * Es la MISMA lista que `src/i18n/locales` de la web. Si allí entra uno nuevo,
+ * entra aquí, o los agentes no sabrán que se lo pueden pedir.
+ */
+export declare const IDIOMAS: readonly ["ar", "bn", "en", "es", "fr", "hi", "pt", "ru", "ur", "zh"];
+export type Idioma = (typeof IDIOMAS)[number];
+/**
+ * `'fr-CA'` → `'fr'`, `'klingon'` → `null`.
+ *
+ * El navegador dice `es-419` y `zh-Hans`, no `es` y `zh`. Quedarse con la
+ * primera parte es lo que hace que un mexicano y un argentino vean lo mismo en
+ * vez de caer los dos al inglés.
+ */
+export declare function normalizarIdioma(v: unknown): Idioma | null;
+/**
+ * La URL de la ficha de un agente en un idioma.
+ *
+ * Sin idioma reconocible se pide la ficha de siempre, SIN parámetro: un agente
+ * viejo que no sepa de esto contesta igual, y uno nuevo no gasta una traducción
+ * en un código que no existe.
+ */
+export declare function fichaEnIdioma(botUrl: string, idioma: unknown): string;
+/**
+ * Cómo se llama cada idioma EN ese idioma.
+ *
+ * Para pedirle una traducción a un modelo, que entiende mucho mejor «français»
+ * que «fr». Y de paso es la lista que enseñaría un selector, si algún día hace
+ * falta uno aquí.
+ */
+export declare const NOMBRE_IDIOMA: Record<Idioma, string>;

package/dist/idiomas.js

@@ -0,0 +1,88 @@
+/**
+ * Panal — la ficha de un agente en el idioma de quien la lee.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * EL PROBLEMA
+ *
+ * El marketplace habla diez idiomas. Los AGENTES no: su nombre, su descripción
+ * y sus niveles son texto libre que escribió una persona en el suyo, y ese
+ * texto sale igual en las diez versiones del escaparate. Hoy en mainnet hay
+ * fichas que enseñan las dos cosas a la vez —la descripción en inglés y los
+ * niveles en español, en la misma tarjeta—, porque una la escribió el registro
+ * y los otros el código del bot.
+ *
+ * QUIÉN TRADUCE
+ *
+ * El propio agente. No hay un traductor de Panal en medio, por dos razones que
+ * no son de gusto:
+ *
+ *   - Un servicio central que traduzca todas las fichas es un servidor que hay
+ *     que pagar, mantener y del que pasa a depender el escaparate. Panal no
+ *     tiene ninguno: el catálogo se puede reconstruir leyendo la cadena.
+ *   - El agente YA es un modelo. Traducir cuatro frases suyas es la llamada más
+ *     barata que va a hacer en su vida, y la paga quien se beneficia.
+ *
+ * Se pide con `?lang=`, y lo que vuelve es la MISMA ficha con los campos de
+ * texto traducidos. Así ningún lector cambia: `leerNiveles`, `leerX402` y todo
+ * lo demás siguen leyendo los mismos campos.
+ *
+ * LO QUE NO SE TRADUCE
+ *
+ * El nombre del agente. «LexPanal» no significa nada en francés y traducirlo
+ * sería inventarle otro nombre a alguien, además de romper toda referencia
+ * escrita a él. Se traduce lo que es una frase: la descripción y el nombre y la
+ * descripción de cada nivel, que sí describen —«Un archivo», «El repositorio»—
+ * y que hoy son lo único que un francés no puede leer.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+/**
+ * Los idiomas del marketplace, en códigos ISO 639-1.
+ *
+ * Es la MISMA lista que `src/i18n/locales` de la web. Si allí entra uno nuevo,
+ * entra aquí, o los agentes no sabrán que se lo pueden pedir.
+ */
+export const IDIOMAS = ['ar', 'bn', 'en', 'es', 'fr', 'hi', 'pt', 'ru', 'ur', 'zh'];
+/**
+ * `'fr-CA'` → `'fr'`, `'klingon'` → `null`.
+ *
+ * El navegador dice `es-419` y `zh-Hans`, no `es` y `zh`. Quedarse con la
+ * primera parte es lo que hace que un mexicano y un argentino vean lo mismo en
+ * vez de caer los dos al inglés.
+ */
+export function normalizarIdioma(v) {
+    if (typeof v !== 'string')
+        return null;
+    const base = v.trim().toLowerCase().split(/[-_]/)[0];
+    return IDIOMAS.includes(base ?? '') ? base : null;
+}
+/**
+ * La URL de la ficha de un agente en un idioma.
+ *
+ * Sin idioma reconocible se pide la ficha de siempre, SIN parámetro: un agente
+ * viejo que no sepa de esto contesta igual, y uno nuevo no gasta una traducción
+ * en un código que no existe.
+ */
+export function fichaEnIdioma(botUrl, idioma) {
+    const base = `${botUrl.replace(/\/+$/, '')}/agent.json`;
+    const lang = normalizarIdioma(idioma);
+    return lang ? `${base}?lang=${lang}` : base;
+}
+/**
+ * Cómo se llama cada idioma EN ese idioma.
+ *
+ * Para pedirle una traducción a un modelo, que entiende mucho mejor «français»
+ * que «fr». Y de paso es la lista que enseñaría un selector, si algún día hace
+ * falta uno aquí.
+ */
+export const NOMBRE_IDIOMA = {
+    ar: 'العربية (Arabic)',
+    bn: 'বাংলা (Bengali)',
+    en: 'English',
+    es: 'español (Spanish)',
+    fr: 'français (French)',
+    hi: 'हिन्दी (Hindi)',
+    pt: 'português (Portuguese)',
+    ru: 'русский (Russian)',
+    ur: 'اردو (Urdu)',
+    zh: '中文 (Chinese, simplified)',
+};

package/dist/index.d.ts

@@ -39,4 +39,10 @@ export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhau
 export type { CallEnvelope } from './envelope.js';
 export type { UrlGuardOptions } from './net.js';
 export { leerDireccion, leerMaxBriefChars, leerNiveles, leerX402, nivelPara } from './agent-card.js';
-export type { AgentCard, FichaGetResult, FichaNivel, FichaPostBrief, FichaX402, Nivel } from './agent-card.js';
+export type { AgentCard, FichaGetResult, FichaNivel, FichaPostAttachment, FichaPostBrief, FichaX402, Nivel, } from './agent-card.js';
+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 { rutaDeAgente } from './net.js';
+export { fichaEnIdioma, IDIOMAS, NOMBRE_IDIOMA, normalizarIdioma } from './idiomas.js';
+export type { Idioma } from './idiomas.js';

package/dist/index.js

@@ -40,3 +40,15 @@ export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhau
 // La ficha de GET /agent.json: un solo formato, y lectores que perdonan el
 // antiguo. En agent-card.ts está por qué llegó a haber dos.
 export { leerDireccion, leerMaxBriefChars, leerNiveles, leerX402, nivelPara } from './agent-card.js';
+// Los niveles escritos en el metadataURI on-chain. Mismo tipo `Nivel` que los
+// de la ficha; en niveles.ts está por qué viven en los dos sitios.
+export { componerNivel, conTextoDeLaFicha, esTokenDeNivel, leerNivelDeSegmento, leerNivelesDeMetadata, NIVELES_EDITABLES, precioAWei, weiAPrecio, } from './niveles.js';
+// 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';
+// 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
+// puede vivir en un subcamino, y `new URL('/x', base)` se lo come.
+export { rutaDeAgente } from './net.js';
+export { fichaEnIdioma, IDIOMAS, NOMBRE_IDIOMA, normalizarIdioma } from './idiomas.js';

package/dist/net.d.ts

@@ -53,3 +53,18 @@ export declare function fetchLimited(url: URL | string, init?: RequestInit & {
     headers: Headers;
     text: string;
 }>;
+/**
+ * Una ruta del agente, colgando de DONDE está el agente.
+ *
+ * Parece una tontería y no lo es: `new URL('/brief/12', base)` descarta el
+ * camino de la base. Con un agente que vive en la raíz de su dominio
+ * —`https://bot.panal.lat`— da lo mismo y funcionó siempre; con uno que vive
+ * en un subcamino —`https://api.panal.lat/buzon/0xAAA`, que es donde reciben
+ * los que no tienen servidor propio— manda la petición a
+ * `https://api.panal.lat/brief/12`, que no es de nadie.
+ *
+ * Y lo que se rompe así no avisa: el 404 se lee como «ese agente no contesta»
+ * con el pago ya bloqueado, y a las 72 h se libera solo. Por eso la unión de
+ * rutas se hace en un sitio y no a mano en cada llamada.
+ */
+export declare function rutaDeAgente(base: string, ruta: string): string;

package/dist/net.js

@@ -148,3 +148,20 @@ export async function fetchLimited(url, init = {}) {
     const { status, headers, bytes } = await fetchBytesLimited(url, init);
     return { status, headers, text: new TextDecoder().decode(bytes) };
 }
+/**
+ * Una ruta del agente, colgando de DONDE está el agente.
+ *
+ * Parece una tontería y no lo es: `new URL('/brief/12', base)` descarta el
+ * camino de la base. Con un agente que vive en la raíz de su dominio
+ * —`https://bot.panal.lat`— da lo mismo y funcionó siempre; con uno que vive
+ * en un subcamino —`https://api.panal.lat/buzon/0xAAA`, que es donde reciben
+ * los que no tienen servidor propio— manda la petición a
+ * `https://api.panal.lat/brief/12`, que no es de nadie.
+ *
+ * Y lo que se rompe así no avisa: el 404 se lee como «ese agente no contesta»
+ * con el pago ya bloqueado, y a las 72 h se libera solo. Por eso la unión de
+ * rutas se hace en un sitio y no a mano en cada llamada.
+ */
+export function rutaDeAgente(base, ruta) {
+    return `${base.replace(/\/+$/, '')}/${ruta.replace(/^\/+/, '')}`;
+}

package/dist/niveles.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Panal — los niveles de un agente dentro del `metadataURI` on-chain.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ AQUÍ Y NO SOLO EN LA FICHA
+ *
+ * Los niveles nacieron en la ficha que sirve el bot (`tiers`, ver
+ * `agent-card.ts`), y allí siguen: es donde un agente declara los topes de
+ * caracteres que su modelo puede masticar. Pero vivir SOLO ahí tiene dos
+ * consecuencias que se notan:
+ *
+ *   - Para cambiar un precio hay que tocar el código del agente y reiniciarlo.
+ *     Quien no programa no puede tocar lo que cobra.
+ *   - Si el bot está caído, sus niveles no existen. El escaparate enseña un
+ *     precio suelto de un agente que en realidad vende tres cosas distintas.
+ *
+ * En el `metadataURI` los escribe el registro, los guarda la cadena y los lee
+ * cualquiera sin preguntarle a nadie. El precio —que es lo único que hay que
+ * bloquear de verdad— deja de depender de que un servidor conteste.
+ *
+ * EL FORMATO
+ *
+ *     nivel:<precio>|<nombre>|<descripción>|<brief>|<adjunto>|<adjuntos>
+ *
+ * Un segmento por nivel, entre los demás de la ficha:
+ *
+ *     Lint · Revisa código · solidity · bot:https://… · nivel:0.03|Un archivo|…
+ *
+ * El precio va en unidades enteras («0.03»), no en wei. En wei son diecisiete
+ * dígitos por nivel y esta cadena se escribe en la cadena de bloques: lo que
+ * ocupa se paga. Los tres topes son opcionales y los vacíos del final no se
+ * escriben, así que un nivel sin topes son tres campos y punto.
+ *
+ * POR QUÉ SE VALIDA TAN DURO
+ *
+ * La regla la fija `marca.ts` y es la misma: UN TOKEN SOLO CUENTA SI SU VALOR
+ * VALE. La descripción de un agente es texto libre y alguien va a escribir
+ * «nivel: depende del encargo» dentro de ella; si bastara con ver dos puntos,
+ * esa frase se convertiría en un nivel fantasma y además desaparecería de la
+ * descripción. Exigiendo un número decimal, una barra y un nombre no vacío, la
+ * frase se queda donde estaba.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+import type { Nivel } from './agent-card.js';
+/**
+ * Cuántos ofrece el formulario.
+ *
+ * Tres es lo que la gente entiende de un vistazo —pequeño, mediano, grande— y
+ * lo que ya publican los agentes que los usan. El LECTOR admite hasta ocho
+ * porque una ficha la escribe cualquiera y recortar lo que ya está escrito
+ * sería tirar un nivel que su dueño creía publicado.
+ */
+export declare const NIVELES_EDITABLES = 3;
+/**
+ * `'0.03'` → `30000000000000000n`.
+ *
+ * A mano y no con `parseUnits` porque este módulo no importa viem: lo lee el
+ * bot de cada agente, que depende de viem a propósito solo en su cliente. La
+ * cuenta es rellenar de ceros a la derecha, que es exactamente lo que hace
+ * `parseUnits` sin coma flotante por medio.
+ */
+export declare function precioAWei(precio: string): bigint | null;
+/**
+ * `30000000000000000n` → `'0.03'`.
+ *
+ * Sin ceros de relleno al final: `'0.030000000000000000'` es el mismo número
+ * y ocupa quince caracteres más en la cadena de bloques.
+ */
+export declare function weiAPrecio(wei: bigint): string;
+/**
+ * `nivel:0.03|Un archivo|Un fichero suelto` → el nivel, o `null` si no lo es.
+ *
+ * Devolver `null` es lo normal: por aquí pasan TODOS los segmentos de la
+ * ficha, incluida la descripción libre del agente.
+ */
+export declare function leerNivelDeSegmento(segmento: string): Nivel | null;
+/** true si este segmento es un nivel. Para que los lectores de ficha lo aparten. */
+export declare function esTokenDeNivel(segmento: string): boolean;
+/**
+ * Los niveles que un agente publica en la cadena, de menor a mayor precio.
+ *
+ * `[]` significa que no publica ninguno, y eso hay que tratarlo como se
+ * trataba antes de que esto existiera: el agente tiene UN precio, el del
+ * registro. Nadie debe fabricarle niveles a partir de él.
+ */
+export declare function leerNivelesDeMetadata(metadataURI: string | null | undefined): Nivel[];
+/**
+ * El nivel → su segmento, o `null` si no se puede escribir.
+ *
+ * `null` en vez de arreglarlo por su cuenta: un «·» dentro del nombre partiría
+ * la ficha en dos y un «|» correría los campos, así que la salida silenciosa
+ * sería un nivel que dice algo distinto de lo que su dueño escribió. Quien
+ * llama tiene que enseñar el error, no firmar una ficha que no reconoce.
+ */
+export declare function componerNivel(nivel: {
+    name: string;
+    description?: string | null;
+    precio: string;
+    maxBriefChars?: number | null;
+    maxAttachChars?: number | null;
+    maxAttachCharsTotal?: number | null;
+}): string | null;
+/**
+ * Los niveles de la cadena, con el texto de la ficha del agente.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ HACE FALTA JUNTARLOS, EN VEZ DE ELEGIR UNO
+ *
+ * Un nivel es dos cosas distintas con dueños distintos:
+ *
+ *   - El PRECIO y los topes. Es lo que se bloquea en el escrow, y tiene que
+ *     salir de la cadena: son los únicos que siguen ahí con el bot caído, y los
+ *     únicos que nadie puede cambiarte entre que miras y pagas.
+ *
+ *   - El NOMBRE y la descripción. Son una etiqueta, y la ficha del agente es el
+ *     único sitio donde pueden estar TRADUCIDAS: `?lang=fr` devuelve la ficha
+ *     en francés, la cadena guarda una sola versión y traducirla costaría una
+ *     transacción por idioma.
+ *
+ * Quedarse solo con los de la cadena —que es lo que se hizo primero— deja el
+ * escaparate entero en francés y los tres niveles de cada agente en español.
+ * Quedarse solo con los de la ficha devuelve el problema de antes: un agente
+ * caído se queda sin niveles y se le encarga el tamaño grande al precio del
+ * pequeño.
+ *
+ * SE EMPAREJAN POR PRECIO, que es la identidad de un nivel: el agente arma su
+ * ficha a partir de lo que tiene en la cadena, así que los importes coinciden
+ * exactos. Lo que no empareje se queda con su texto de la cadena, que es la
+ * respuesta correcta cuando la ficha dice otra cosa: enseñar el nombre de un
+ * nivel junto a un precio que no es el suyo sería peor que no traducirlo.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+export declare function conTextoDeLaFicha(enCadena: Nivel[], deLaFicha: Nivel[]): Nivel[];

package/dist/niveles.js

@@ -0,0 +1,256 @@
+/**
+ * Panal — los niveles de un agente dentro del `metadataURI` on-chain.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ AQUÍ Y NO SOLO EN LA FICHA
+ *
+ * Los niveles nacieron en la ficha que sirve el bot (`tiers`, ver
+ * `agent-card.ts`), y allí siguen: es donde un agente declara los topes de
+ * caracteres que su modelo puede masticar. Pero vivir SOLO ahí tiene dos
+ * consecuencias que se notan:
+ *
+ *   - Para cambiar un precio hay que tocar el código del agente y reiniciarlo.
+ *     Quien no programa no puede tocar lo que cobra.
+ *   - Si el bot está caído, sus niveles no existen. El escaparate enseña un
+ *     precio suelto de un agente que en realidad vende tres cosas distintas.
+ *
+ * En el `metadataURI` los escribe el registro, los guarda la cadena y los lee
+ * cualquiera sin preguntarle a nadie. El precio —que es lo único que hay que
+ * bloquear de verdad— deja de depender de que un servidor conteste.
+ *
+ * EL FORMATO
+ *
+ *     nivel:<precio>|<nombre>|<descripción>|<brief>|<adjunto>|<adjuntos>
+ *
+ * Un segmento por nivel, entre los demás de la ficha:
+ *
+ *     Lint · Revisa código · solidity · bot:https://… · nivel:0.03|Un archivo|…
+ *
+ * El precio va en unidades enteras («0.03»), no en wei. En wei son diecisiete
+ * dígitos por nivel y esta cadena se escribe en la cadena de bloques: lo que
+ * ocupa se paga. Los tres topes son opcionales y los vacíos del final no se
+ * escriben, así que un nivel sin topes son tres campos y punto.
+ *
+ * POR QUÉ SE VALIDA TAN DURO
+ *
+ * La regla la fija `marca.ts` y es la misma: UN TOKEN SOLO CUENTA SI SU VALOR
+ * VALE. La descripción de un agente es texto libre y alguien va a escribir
+ * «nivel: depende del encargo» dentro de ella; si bastara con ver dos puntos,
+ * esa frase se convertiría en un nivel fantasma y además desaparecería de la
+ * descripción. Exigiendo un número decimal, una barra y un nombre no vacío, la
+ * frase se queda donde estaba.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+/**
+ * Decimales de las dos monedas del registro: MON nativo y $PANAL.
+ *
+ * Está fijo a propósito. `PanalRegistryV2` solo admite esas dos y las dos
+ * tienen dieciocho, así que el precio de un nivel se puede escribir en
+ * unidades enteras sin arrastrar de qué moneda se trata. El día que el
+ * registro admita un token con otros decimales, esto se rompe de la única
+ * forma aceptable: aquí, en un sitio, y no repartido por seis lectores.
+ */
+const DECIMALES = 18;
+/** Cuántos niveles se leen de una ficha ajena. El mismo tope que `leerNiveles`. */
+const MAX_NIVELES = 8;
+/**
+ * Cuántos ofrece el formulario.
+ *
+ * Tres es lo que la gente entiende de un vistazo —pequeño, mediano, grande— y
+ * lo que ya publican los agentes que los usan. El LECTOR admite hasta ocho
+ * porque una ficha la escribe cualquiera y recortar lo que ya está escrito
+ * sería tirar un nivel que su dueño creía publicado.
+ */
+export const NIVELES_EDITABLES = 3;
+/** Tope de cada texto. Los mismos que aplica `leerNiveles` a la ficha del bot. */
+const MAX_NOMBRE = 60;
+const MAX_DESCRIPCION = 200;
+/** Un decimal positivo con hasta dieciocho cifras detrás de la coma. */
+const PRECIO = /^\d{1,12}(\.\d{1,18})?$/;
+/**
+ * `'0.03'` → `30000000000000000n`.
+ *
+ * A mano y no con `parseUnits` porque este módulo no importa viem: lo lee el
+ * bot de cada agente, que depende de viem a propósito solo en su cliente. La
+ * cuenta es rellenar de ceros a la derecha, que es exactamente lo que hace
+ * `parseUnits` sin coma flotante por medio.
+ */
+export function precioAWei(precio) {
+    const s = precio.trim();
+    if (!PRECIO.test(s))
+        return null;
+    const [entera, decimal = ''] = s.split('.');
+    const wei = BigInt(entera + decimal.padEnd(DECIMALES, '0').slice(0, DECIMALES));
+    return wei > 0n ? wei : null;
+}
+/**
+ * `30000000000000000n` → `'0.03'`.
+ *
+ * Sin ceros de relleno al final: `'0.030000000000000000'` es el mismo número
+ * y ocupa quince caracteres más en la cadena de bloques.
+ */
+export function weiAPrecio(wei) {
+    const s = wei.toString().padStart(DECIMALES + 1, '0');
+    const entera = s.slice(0, -DECIMALES);
+    const decimal = s.slice(-DECIMALES).replace(/0+$/, '');
+    return decimal ? `${entera}.${decimal}` : entera;
+}
+/** Un entero positivo, o `null`. Misma regla que los topes de la ficha. */
+function tope(v) {
+    if (v === undefined)
+        return null;
+    const s = v.trim();
+    if (!/^\d{1,9}$/.test(s))
+        return null;
+    const n = Number(s);
+    return n > 0 ? n : null;
+}
+/** Texto de un desconocido: espacios colapsados y recortado, porque va a un escaparate. */
+function letrero(v, max) {
+    if (v === undefined)
+        return null;
+    const limpio = v.replace(/\s+/g, ' ').trim().slice(0, max);
+    return limpio || null;
+}
+/**
+ * `nivel:0.03|Un archivo|Un fichero suelto` → el nivel, o `null` si no lo es.
+ *
+ * Devolver `null` es lo normal: por aquí pasan TODOS los segmentos de la
+ * ficha, incluida la descripción libre del agente.
+ */
+export function leerNivelDeSegmento(segmento) {
+    const i = segmento.indexOf(':');
+    if (i <= 0)
+        return null;
+    if (segmento.slice(0, i).trim().toLowerCase() !== 'nivel')
+        return null;
+    const campos = segmento.slice(i + 1).split('|');
+    // Sin nombre no hay nivel: el cliente elige por el nombre, y un botón vacío
+    // con un precio al lado no es una oferta, es un acertijo.
+    if (campos.length < 2)
+        return null;
+    const wei = precioAWei(campos[0] ?? '');
+    if (wei === null)
+        return null;
+    const name = letrero(campos[1], MAX_NOMBRE);
+    if (!name)
+        return null;
+    return {
+        name,
+        description: letrero(campos[2], MAX_DESCRIPCION),
+        wei,
+        maxBriefChars: tope(campos[3]),
+        maxAttachChars: tope(campos[4]),
+        maxAttachCharsTotal: tope(campos[5]),
+    };
+}
+/** true si este segmento es un nivel. Para que los lectores de ficha lo aparten. */
+export function esTokenDeNivel(segmento) {
+    return leerNivelDeSegmento(segmento) !== null;
+}
+/**
+ * Los niveles que un agente publica en la cadena, de menor a mayor precio.
+ *
+ * `[]` significa que no publica ninguno, y eso hay que tratarlo como se
+ * trataba antes de que esto existiera: el agente tiene UN precio, el del
+ * registro. Nadie debe fabricarle niveles a partir de él.
+ */
+export function leerNivelesDeMetadata(metadataURI) {
+    if (!metadataURI)
+        return [];
+    const out = [];
+    for (const segmento of metadataURI.split('·')) {
+        if (out.length >= MAX_NIVELES)
+            break;
+        const nivel = leerNivelDeSegmento(segmento.trim());
+        // Un nivel mal escrito se cae de la lista en vez de tumbarla entera: un
+        // campo roto no puede dejar sin comprar los niveles buenos de al lado.
+        if (nivel)
+            out.push(nivel);
+    }
+    // De menor a mayor, que es como se enseñan y lo que `nivelPara` necesita
+    // para quedarse con el último que entra en lo pagado.
+    return out.sort((a, b) => (a.wei < b.wei ? -1 : a.wei > b.wei ? 1 : 0));
+}
+/**
+ * El nivel → su segmento, o `null` si no se puede escribir.
+ *
+ * `null` en vez de arreglarlo por su cuenta: un «·» dentro del nombre partiría
+ * la ficha en dos y un «|» correría los campos, así que la salida silenciosa
+ * sería un nivel que dice algo distinto de lo que su dueño escribió. Quien
+ * llama tiene que enseñar el error, no firmar una ficha que no reconoce.
+ */
+export function componerNivel(nivel) {
+    if (precioAWei(nivel.precio) === null)
+        return null;
+    const name = nivel.name.replace(/\s+/g, ' ').trim();
+    const description = (nivel.description ?? '').replace(/\s+/g, ' ').trim();
+    if (!name || name.length > MAX_NOMBRE)
+        return null;
+    if (description.length > MAX_DESCRIPCION)
+        return null;
+    if (/[·|]/.test(name) || /[·|]/.test(description))
+        return null;
+    const campos = [
+        nivel.precio.trim(),
+        name,
+        description,
+        entero(nivel.maxBriefChars),
+        entero(nivel.maxAttachChars),
+        entero(nivel.maxAttachCharsTotal),
+    ];
+    // Los vacíos del FINAL se van; los de en medio no pueden irse o el siguiente
+    // campo ocuparía el sitio del que falta.
+    while (campos.length > 2 && campos[campos.length - 1] === '')
+        campos.pop();
+    return `nivel:${campos.join('|')}`;
+}
+function entero(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0 ? String(v) : '';
+}
+/**
+ * Los niveles de la cadena, con el texto de la ficha del agente.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ HACE FALTA JUNTARLOS, EN VEZ DE ELEGIR UNO
+ *
+ * Un nivel es dos cosas distintas con dueños distintos:
+ *
+ *   - El PRECIO y los topes. Es lo que se bloquea en el escrow, y tiene que
+ *     salir de la cadena: son los únicos que siguen ahí con el bot caído, y los
+ *     únicos que nadie puede cambiarte entre que miras y pagas.
+ *
+ *   - El NOMBRE y la descripción. Son una etiqueta, y la ficha del agente es el
+ *     único sitio donde pueden estar TRADUCIDAS: `?lang=fr` devuelve la ficha
+ *     en francés, la cadena guarda una sola versión y traducirla costaría una
+ *     transacción por idioma.
+ *
+ * Quedarse solo con los de la cadena —que es lo que se hizo primero— deja el
+ * escaparate entero en francés y los tres niveles de cada agente en español.
+ * Quedarse solo con los de la ficha devuelve el problema de antes: un agente
+ * caído se queda sin niveles y se le encarga el tamaño grande al precio del
+ * pequeño.
+ *
+ * SE EMPAREJAN POR PRECIO, que es la identidad de un nivel: el agente arma su
+ * ficha a partir de lo que tiene en la cadena, así que los importes coinciden
+ * exactos. Lo que no empareje se queda con su texto de la cadena, que es la
+ * respuesta correcta cuando la ficha dice otra cosa: enseñar el nombre de un
+ * nivel junto a un precio que no es el suyo sería peor que no traducirlo.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+export function conTextoDeLaFicha(enCadena, deLaFicha) {
+    if (enCadena.length === 0 || deLaFicha.length === 0)
+        return enCadena;
+    return enCadena.map((n) => {
+        const igual = deLaFicha.find((f) => f.wei === n.wei);
+        if (!igual)
+            return n;
+        return {
+            ...n,
+            // Solo se pisa lo que la ficha REALMENTE trae: un nivel con nombre no
+            // puede perderlo porque la ficha venga a medias.
+            name: igual.name ?? n.name,
+            description: igual.description ?? n.description,
+        };
+    });
+}

package/dist/tipo.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Panal — quién hay al otro lado: una persona o un programa.
+ *
+ * Un token más de los que viven en el `metadataURI` on-chain, junto a `bot:`,
+ * los de marca y los de nivel:
+ *
+ *     Marta · Traduce contratos ES⇄FR · traducción · tipo:persona · bot:…
+ *
+ * POR QUÉ ESTÁ EN LA CADENA Y NO EN LA TARJETA
+ *
+ * Porque es lo que decide en qué mercado sale y con quién se le compara, y eso
+ * no puede depender de que un servidor conteste. Una persona que apaga el
+ * ordenador el viernes no se convierte en un bot el sábado.
+ *
+ * POR QUÉ NO SE ADIVINA
+ *
+ * Se podría intentar: quien usa el buzón de Panal parece una persona, quien
+ * tiene servidor propio parece un bot. Las dos cosas son falsas —un bot puede
+ * usar el buzón y una persona puede montarse un servidor—, y equivocarse aquí
+ * es etiquetar a alguien de lo que no es. Así que se declara, y quien no
+ * declara nada es lo que han sido todos los agentes registrados hasta hoy: un
+ * programa.
+ *
+ * LO QUE ESTE TOKEN NO ES
+ *
+ * No es una verificación. Nadie comprueba que detrás de `tipo:persona` haya
+ * una persona, igual que nadie comprueba que detrás de un nombre haya quien
+ * dice. Lo que hace es que la respuesta sea SUYA y esté firmada, en vez de que
+ * la deduzca el mercado por su cuenta.
+ */
+/** Quién trabaja: una persona, o un programa. */
+export type TipoDeAgente = 'persona' | 'bot';
+/**
+ * Qué dice un segmento, o `null` si no es uno de estos.
+ *
+ * Solo se reconocen los dos valores. `tipo:` con cualquier otra cosa detrás no
+ * es un tipo desconocido que haya que respetar: es texto que alguien escribió
+ * mal, y tratarlo como token lo borraría de su descripción sin decírselo.
+ */
+export declare function leerTipoDeSegmento(segmento: string): TipoDeAgente | null;
+/** true si este segmento es un tipo. Para que los lectores de ficha lo aparten. */
+export declare function esTokenDeTipo(segmento: string): boolean;
+/**
+ * Quién hay detrás de esta ficha. Sin token, un programa.
+ *
+ * Ausente NO es «no se sabe» a efectos de enseñarlo: hay que ponerlo en algún
+ * mercado, y el sitio honrado para los diez agentes que ya estaban registrados
+ * antes de que esto existiera es el de programas, que es lo que son.
+ */
+export declare function leerTipo(metadataURI: string | null | undefined): TipoDeAgente;
+/**
+ * El token que hay que escribir, o `null` si no hay que escribir ninguno.
+ *
+ * `bot` no escribe nada a propósito. Es lo que se supone sin token, así que
+ * escribirlo alarga la ficha de todos los agentes —y el gas de registrarlos—
+ * para no decir nada que no se supiera.
+ */
+export declare function tokenDeTipo(tipo: TipoDeAgente): string | null;

package/dist/tipo.js

@@ -0,0 +1,77 @@
+/**
+ * Panal — quién hay al otro lado: una persona o un programa.
+ *
+ * Un token más de los que viven en el `metadataURI` on-chain, junto a `bot:`,
+ * los de marca y los de nivel:
+ *
+ *     Marta · Traduce contratos ES⇄FR · traducción · tipo:persona · bot:…
+ *
+ * POR QUÉ ESTÁ EN LA CADENA Y NO EN LA TARJETA
+ *
+ * Porque es lo que decide en qué mercado sale y con quién se le compara, y eso
+ * no puede depender de que un servidor conteste. Una persona que apaga el
+ * ordenador el viernes no se convierte en un bot el sábado.
+ *
+ * POR QUÉ NO SE ADIVINA
+ *
+ * Se podría intentar: quien usa el buzón de Panal parece una persona, quien
+ * tiene servidor propio parece un bot. Las dos cosas son falsas —un bot puede
+ * usar el buzón y una persona puede montarse un servidor—, y equivocarse aquí
+ * es etiquetar a alguien de lo que no es. Así que se declara, y quien no
+ * declara nada es lo que han sido todos los agentes registrados hasta hoy: un
+ * programa.
+ *
+ * LO QUE ESTE TOKEN NO ES
+ *
+ * No es una verificación. Nadie comprueba que detrás de `tipo:persona` haya
+ * una persona, igual que nadie comprueba que detrás de un nombre haya quien
+ * dice. Lo que hace es que la respuesta sea SUYA y esté firmada, en vez de que
+ * la deduzca el mercado por su cuenta.
+ */
+/** El prefijo del token, en minúsculas. */
+const PREFIJO = 'tipo:';
+/**
+ * Qué dice un segmento, o `null` si no es uno de estos.
+ *
+ * Solo se reconocen los dos valores. `tipo:` con cualquier otra cosa detrás no
+ * es un tipo desconocido que haya que respetar: es texto que alguien escribió
+ * mal, y tratarlo como token lo borraría de su descripción sin decírselo.
+ */
+export function leerTipoDeSegmento(segmento) {
+    const s = segmento.trim();
+    if (!s.toLowerCase().startsWith(PREFIJO))
+        return null;
+    const valor = s.slice(PREFIJO.length).trim().toLowerCase();
+    return valor === 'persona' || valor === 'bot' ? valor : null;
+}
+/** true si este segmento es un tipo. Para que los lectores de ficha lo aparten. */
+export function esTokenDeTipo(segmento) {
+    return leerTipoDeSegmento(segmento) !== null;
+}
+/**
+ * Quién hay detrás de esta ficha. Sin token, un programa.
+ *
+ * Ausente NO es «no se sabe» a efectos de enseñarlo: hay que ponerlo en algún
+ * mercado, y el sitio honrado para los diez agentes que ya estaban registrados
+ * antes de que esto existiera es el de programas, que es lo que son.
+ */
+export function leerTipo(metadataURI) {
+    if (!metadataURI)
+        return 'bot';
+    for (const seg of metadataURI.split('·')) {
+        const tipo = leerTipoDeSegmento(seg);
+        if (tipo)
+            return tipo;
+    }
+    return 'bot';
+}
+/**
+ * El token que hay que escribir, o `null` si no hay que escribir ninguno.
+ *
+ * `bot` no escribe nada a propósito. Es lo que se supone sin token, así que
+ * escribirlo alarga la ficha de todos los agentes —y el gas de registrarlos—
+ * para no decir nada que no se supiera.
+ */
+export function tokenDeTipo(tipo) {
+    return tipo === 'persona' ? `${PREFIJO}persona` : null;
+}

package/dist/types.js

@@ -7,6 +7,8 @@
  * 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 { 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. */
 export var TaskStatus;
 (function (TaskStatus) {
@@ -164,6 +166,15 @@ export function parseAgentMetadata(metadataURI) {
                 links[link[0]] = link[1];
             continue;
         }
+        // Los niveles tampoco son texto de la ficha: sin apartarlos, los tres
+        // `nivel:…` de un agente saldrían anunciados como skills suyas. Los lee
+        // `leerNivelesDeMetadata`; aquí solo hace falta reconocerlos.
+        if (esTokenDeNivel(seg))
+            continue;
+        // Y quién hay detrás, por lo mismo: sin apartarlo, `tipo:persona` saldría
+        // anunciado como una skill de esa persona.
+        if (esTokenDeTipo(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.15.0",
+  "version": "0.17.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/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",
+    "test": "tsx test/sdk.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",
     "test:nombres": "tsx test/nombres.test.ts"
   }
 }