@panal/sdk 0.9.0 → 0.10.1

package/dist/abis.d.ts

@@ -293,3 +293,46 @@ export declare const erc20Abi: readonly [{
         readonly type: "bool";
     }];
 }];
+/**
+ * PanalNames, solo las lecturas.
+ *
+ * Es la parte de la identidad de un agente que no depende de nadie: un nombre
+ * lo tiene una sola direccion, y se comprueba con una llamada `view` contra la
+ * cadena. La verificacion de dominio prueba mas —control de un servidor que
+ * declara esa direccion— pero la hace el indexador contra un tercero, asi que
+ * desaparece si el indexador se cae o va atrasado. Esta no.
+ */
+export declare const namesAbi: readonly [{
+    readonly type: "function";
+    readonly name: "nombreDe";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agente";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "fichaDe";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "nombre";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "dueno";
+        readonly type: "address";
+    }, {
+        readonly name: "desde";
+        readonly type: "uint64";
+    }, {
+        readonly name: "precio";
+        readonly type: "uint256";
+    }, {
+        readonly name: "transferible";
+        readonly type: "bool";
+    }];
+}];

package/dist/abis.js

@@ -212,3 +212,36 @@ export const erc20Abi = [
         outputs: [{ name: '', type: 'bool' }],
     },
 ];
+/**
+ * PanalNames, solo las lecturas.
+ *
+ * Es la parte de la identidad de un agente que no depende de nadie: un nombre
+ * lo tiene una sola direccion, y se comprueba con una llamada `view` contra la
+ * cadena. La verificacion de dominio prueba mas —control de un servidor que
+ * declara esa direccion— pero la hace el indexador contra un tercero, asi que
+ * desaparece si el indexador se cae o va atrasado. Esta no.
+ */
+export const namesAbi = [
+    {
+        type: 'function',
+        name: 'nombreDe',
+        stateMutability: 'view',
+        inputs: [{ name: 'agente', type: 'address' }],
+        outputs: [{ name: '', type: 'string' }],
+    },
+    {
+        // `desde` es cuando el nombre paso a ser de esta direccion, no cuando se
+        // creo: en una venta se reinicia, que es justo el dato que delata a un
+        // nombre con historia recien cambiado de manos.
+        type: 'function',
+        name: 'fichaDe',
+        stateMutability: 'view',
+        inputs: [{ name: 'nombre', type: 'string' }],
+        outputs: [
+            { name: 'dueno', type: 'address' },
+            { name: 'desde', type: 'uint64' },
+            { name: 'precio', type: 'uint256' },
+            { name: 'transferible', type: 'bool' },
+        ],
+    },
+];

package/dist/chains.d.ts

@@ -119,6 +119,17 @@ export interface PanalAddresses {
     panalToken: Address;
     /** Multisig 2-de-3 que resuelve las disputas. Se lee del escrow en caliente. */
     arbitrator: Address;
+    /**
+     * PanalNames: el nombre único de cada agente.
+     *
+     * Es la única señal de identidad que vive EN LA CADENA. El nombre del perfil
+     * es texto libre y se repite —hoy hay tres direcciones anunciándose como
+     * "LexPanal"—, mientras que aquí un nombre lo tiene una sola dirección. Y a
+     * diferencia de la verificación de dominio, que la hace el indexador contra
+     * un servidor ajeno, esto se lee con una llamada `view`: no depende de que
+     * nada esté levantado.
+     */
+    names: Address;
 }
 /** Desplegados en Monad mainnet el 2026-07-29 (escrow v2 auditado). */
 export declare const MAINNET_ADDRESSES: PanalAddresses;

package/dist/chains.js

@@ -32,6 +32,7 @@ export const MAINNET_ADDRESSES = {
     escrow: '0xe138A9A492CFe27A13f8b7A6D312DA831791bCe9',
     panalToken: '0x2e2e44e7fa6178822d4397299f719e89d1a67777',
     arbitrator: '0xc384C1F5D6716571DA84329BeAaE6F064C6b1Fe0',
+    names: '0xc94a8107C87859cAd2E472e71BbE25c15cdD614A',
 };
 /**
  * En testnet solo hay registry y escrow desplegados. El resto queda a cero: el
@@ -43,6 +44,7 @@ export const TESTNET_ADDRESSES = {
     escrow: '0x0000000000000000000000000000000000000000',
     panalToken: '0x0000000000000000000000000000000000000000',
     arbitrator: '0x0000000000000000000000000000000000000000',
+    names: '0x0000000000000000000000000000000000000000',
 };
 /** `address(0)` significa MON nativo en todo el protocolo. */
 export const NATIVE_CURRENCY = '0x0000000000000000000000000000000000000000';

package/dist/client.d.ts

@@ -65,6 +65,31 @@ export interface HireResult {
     /** El hash del brief que quedó registrado, para poder probarlo después. */
     taskHash: Hex;
 }
+/**
+ * ¿Esto que manda el indexador es un nombre de PanalNames?
+ *
+ * Se valida como todo lo que llega de un servicio: si viene a medias se
+ * descarta, porque un `origen` inventado haria que la web avisara de una venta
+ * que no existio, o peor, que callara una que si.
+ */
+/**
+ * La skill pedida y, detrás, versiones cada vez más generales de ella.
+ *
+ * `searchAgents` exige que TODAS las palabras aparezcan, así que cuantas más
+ * lleve la skill, menos gente la cumple. Quien escribe estas cadenas suele ser
+ * un modelo, y un modelo pide "Spanish tax law" donde el mercado vende "tax".
+ *
+ * Se recorta POR LA IZQUIERDA porque en inglés el núcleo del sintagma va al
+ * final: "Spanish tax law" → "tax law" → "law" sigue hablando de lo mismo.
+ * Recortar por la derecha dejaría "Spanish", que casa con cualquier cosa
+ * española y con nada de impuestos: peor que no encontrar a nadie, porque se
+ * pagaría al agente equivocado.
+ *
+ * Nunca baja de una palabra y nunca devuelve duplicados, así que en el caso
+ * normal —una o dos palabras, que es lo que el prompt pide— esto es una sola
+ * búsqueda y no cambia nada.
+ */
+export declare function variantesDeSkill(skill: string): string[];
 export declare class PanalClient {
     readonly network: PanalNetwork;
     readonly addresses: PanalAddresses;
@@ -91,8 +116,34 @@ export declare class PanalClient {
      * ninguno» de «no lo sé», porque en el segundo caso toca leer la cadena.
      */
     private buscarEnIndice;
-    /** Un agente concreto, con su metadata ya interpretada. */
+    /**
+     * Un agente concreto, con su metadata interpretada y su nombre único.
+     *
+     * El nombre se lee de PanalNames EN LA CADENA, y por eso está aquí y no solo
+     * en la ruta del indexador: el nombre del perfil es texto libre y se repite
+     * —ahora mismo hay tres direcciones anunciándose como "LexPanal"—, mientras
+     * que un nombre de PanalNames lo tiene una sola dirección. Es la única señal
+     * de identidad que sigue en pie si el indexador se cae, porque no depende de
+     * que nadie esté levantado: es una llamada `view`.
+     *
+     * No sustituye a la verificación de dominio, que prueba más: control de un
+     * servidor que declara esta misma dirección. Prueba unicidad, no quién hay
+     * detrás. Y como los nombres se venden, `desdeTs` importa tanto como el
+     * nombre — pero `origen` se queda sin saber por esta ruta, porque sale de los
+     * eventos del contrato y no de una lectura.
+     */
     getAgent(address: Address): Promise<Agent>;
+    /** La ficha del registry, sin las lecturas de más. Lo que usa `listAgents`. */
+    private leerAgente;
+    /**
+     * El nombre de PanalNames de una dirección, o null si no tiene.
+     *
+     * Nunca lanza: un agente sin nombre es lo normal, y que el contrato de
+     * nombres no esté desplegado —testnet— tampoco puede impedir leer una ficha.
+     * Devolver null y seguir es lo correcto; caerse aquí convertiría un dato
+     * adicional en un fallo de la operación entera.
+     */
+    private nombreEnCadena;
     /**
      * Busca agentes activos por texto libre sobre nombre, descripción y skills.
      *
@@ -264,6 +315,7 @@ export declare class PanalClient {
         depth?: number;
     }): Promise<AskResult & {
         agent: Address;
+        skill: string;
     }>;
     /**
      * Dónde escucha el x402 de un agente.

package/dist/client.js

@@ -16,7 +16,7 @@
  * y en uso: el caso de "quiero probar esto ahora" no debería exigir un .env.
  */
 import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes } from 'viem';
-import { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
 import { assertPublicUrl, fetchLimited } from './net.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
@@ -33,6 +33,35 @@ const REGISTRY_MAX = 500;
  * descarta, porque un `origen` inventado haria que la web avisara de una venta
  * que no existio, o peor, que callara una que si.
  */
+/**
+ * La skill pedida y, detrás, versiones cada vez más generales de ella.
+ *
+ * `searchAgents` exige que TODAS las palabras aparezcan, así que cuantas más
+ * lleve la skill, menos gente la cumple. Quien escribe estas cadenas suele ser
+ * un modelo, y un modelo pide "Spanish tax law" donde el mercado vende "tax".
+ *
+ * Se recorta POR LA IZQUIERDA porque en inglés el núcleo del sintagma va al
+ * final: "Spanish tax law" → "tax law" → "law" sigue hablando de lo mismo.
+ * Recortar por la derecha dejaría "Spanish", que casa con cualquier cosa
+ * española y con nada de impuestos: peor que no encontrar a nadie, porque se
+ * pagaría al agente equivocado.
+ *
+ * Nunca baja de una palabra y nunca devuelve duplicados, así que en el caso
+ * normal —una o dos palabras, que es lo que el prompt pide— esto es una sola
+ * búsqueda y no cambia nada.
+ */
+export function variantesDeSkill(skill) {
+    const palabras = skill.trim().split(/\s+/).filter(Boolean);
+    if (palabras.length <= 1)
+        return [skill.trim()].filter(Boolean);
+    const out = [];
+    for (let i = 0; i < palabras.length; i++) {
+        const v = palabras.slice(i).join(' ');
+        if (!out.includes(v))
+            out.push(v);
+    }
+    return out;
+}
 function esNombre(v) {
     if (v === null || typeof v !== 'object')
         return false;
@@ -101,7 +130,11 @@ export class PanalClient {
             if (page.length < Number(REGISTRY_PAGE))
                 break;
         }
-        return Promise.all(addresses.map((address) => this.getAgent(address)));
+        // `leerAgente` y no `getAgent`: este listado ya son N lecturas en paralelo
+        // contra un RPC que corta sobre 50 concurrentes, y buscar el nombre de cada
+        // uno las triplicaria. Quien quiera el nombre de uno concreto llama a
+        // getAgent(); quien quiera el de todos tiene el indexador, que ya lo trae.
+        return Promise.all(addresses.map((address) => this.leerAgente(address)));
     }
     /**
      * Los agentes que dice el indexador, o null si no se puede contar con él.
@@ -182,8 +215,29 @@ export class PanalClient {
             return null;
         }
     }
-    /** Un agente concreto, con su metadata ya interpretada. */
+    /**
+     * Un agente concreto, con su metadata interpretada y su nombre único.
+     *
+     * El nombre se lee de PanalNames EN LA CADENA, y por eso está aquí y no solo
+     * en la ruta del indexador: el nombre del perfil es texto libre y se repite
+     * —ahora mismo hay tres direcciones anunciándose como "LexPanal"—, mientras
+     * que un nombre de PanalNames lo tiene una sola dirección. Es la única señal
+     * de identidad que sigue en pie si el indexador se cae, porque no depende de
+     * que nadie esté levantado: es una llamada `view`.
+     *
+     * No sustituye a la verificación de dominio, que prueba más: control de un
+     * servidor que declara esta misma dirección. Prueba unicidad, no quién hay
+     * detrás. Y como los nombres se venden, `desdeTs` importa tanto como el
+     * nombre — pero `origen` se queda sin saber por esta ruta, porque sale de los
+     * eventos del contrato y no de una lectura.
+     */
     async getAgent(address) {
+        const base = await this.leerAgente(address);
+        const nombre = await this.nombreEnCadena(address);
+        return nombre ? { ...base, nombre } : base;
+    }
+    /** La ficha del registry, sin las lecturas de más. Lo que usa `listAgents`. */
+    async leerAgente(address) {
         const raw = (await this.publicClient.readContract({
             address: this.addresses.registry,
             abi: registryAbi,
@@ -201,6 +255,42 @@ export class PanalClient {
             metadata: parseAgentMetadata(raw.metadataURI),
         };
     }
+    /**
+     * El nombre de PanalNames de una dirección, o null si no tiene.
+     *
+     * Nunca lanza: un agente sin nombre es lo normal, y que el contrato de
+     * nombres no esté desplegado —testnet— tampoco puede impedir leer una ficha.
+     * Devolver null y seguir es lo correcto; caerse aquí convertiría un dato
+     * adicional en un fallo de la operación entera.
+     */
+    async nombreEnCadena(address) {
+        const names = this.addresses.names;
+        if (!names || names === '0x0000000000000000000000000000000000000000')
+            return null;
+        try {
+            const nombre = (await this.publicClient.readContract({
+                address: names,
+                abi: namesAbi,
+                functionName: 'nombreDe',
+                args: [getAddress(address)],
+            }));
+            if (!nombre)
+                return null;
+            const ficha = (await this.publicClient.readContract({
+                address: names,
+                abi: namesAbi,
+                functionName: 'fichaDe',
+                args: [nombre],
+            }));
+            // `origen` a propósito ausente: por esta ruta no se sabe, y ponerle
+            // 'reclamado' seria inventarse justo la parte que avisa de una compra
+            // reciente.
+            return { nombre, desdeTs: Number(ficha[1]) };
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Busca agentes activos por texto libre sobre nombre, descripción y skills.
      *
@@ -582,11 +672,31 @@ export class PanalClient {
         // Se busca por SKILL, no por texto libre: encontrar a alguien porque la
         // palabra aparece en su descripción no sirve para delegar. Si el indexador
         // no está, `searchAgents` cae solo a la cadena con su texto libre.
-        const candidates = (await this.searchAgents(skill, { skill }))
-            .filter((a) => !excluded.has(a.address.toLowerCase()) && a.metadata.botUrl)
-            .slice(0, options.maxCandidates ?? 5);
-        if (!candidates.length)
-            throw new X402Error(`Ningún agente activo con la skill "${skill}" publica endpoint.`);
+        //
+        // La búsqueda exige que TODAS las palabras casen, así que una skill de más
+        // de dos palabras no encuentra a nadie casi nunca: quien la escribe es un
+        // modelo, y un modelo pide "Spanish tax law" donde el mercado vende "tax".
+        // Se reintenta quitando palabras POR LA IZQUIERDA porque en inglés el
+        // núcleo va al final: "Spanish tax law" → "tax law" → "law". Así se
+        // generaliza sin perder de qué se estaba hablando; recortar por la derecha
+        // dejaría "Spanish", que casaría con cualquier cosa española.
+        let candidates = [];
+        let usada = skill;
+        for (const intento of variantesDeSkill(skill)) {
+            candidates = (await this.searchAgents(intento, { skill: intento }))
+                .filter((a) => !excluded.has(a.address.toLowerCase()) && a.metadata.botUrl)
+                .slice(0, options.maxCandidates ?? 5);
+            if (candidates.length) {
+                usada = intento;
+                break;
+            }
+        }
+        if (!candidates.length) {
+            throw new X402Error(`Ningún agente activo con la skill "${skill}" publica endpoint.` +
+                (variantesDeSkill(skill).length > 1
+                    ? ` Se probó también con ${variantesDeSkill(skill).slice(1).map((v) => `"${v}"`).join(' y ')}.`
+                    : ''));
+        }
         const quotes = [];
         const rechazos = [];
         for (const agent of candidates) {
@@ -622,7 +732,10 @@ export class PanalClient {
             quote: elegido.accept,
             envelope: siguiente,
         });
-        return { ...result, agent: elegido.agent.address };
+        // `skill` es la que de verdad encontró al vendedor, que puede no ser la que
+        // pediste: quien llama necesita poder decirlo en su log, o cada búsqueda
+        // ensanchada es un cambio de comportamiento invisible.
+        return { ...result, agent: elegido.agent.address, skill: usada };
     }
     /**
      * Dónde escucha el x402 de un agente.

package/dist/types.d.ts

@@ -84,8 +84,15 @@ export interface NombreDeAgente {
      * Importa tanto como el nombre: en una venta lo único que viaja es el
      * nombre, y la reputación se queda con el vendedor. Un `lint` comprado la
      * semana pasada no hizo las tareas que hicieron valer ese nombre.
+     *
+     * OPCIONAL porque no siempre se puede saber. Se deduce de los eventos del
+     * contrato de nombres, así que lo tiene el indexador; leyendo la cadena solo
+     * hay `nombreDe()` y `fichaDe()`, que dicen cuál es el nombre y desde cuándo
+     * es suyo, no cómo llegó a serlo. Cuando falta es `undefined`, y hay que
+     * tratarlo como «no lo sé», nunca como «reclamado»: suponer el origen limpio
+     * es justo el error que la advertencia existe para evitar.
      */
-    origen: 'reclamado' | 'comprado' | 'recibido';
+    origen?: 'reclamado' | 'comprado' | 'recibido';
 }
 /** Una tarea del escrow. */
 export interface Task {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,6 +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"
+    "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/skill.test.ts",
+    "test:nombres": "tsx test/nombres.test.ts"
   }
 }