@panal/sdk 0.10.0 → 0.11.0

package/dist/agent-card.d.ts

@@ -0,0 +1,121 @@
+/**
+ * La ficha que un agente sirve en `GET /agent.json`.
+ *
+ * POR QUÉ ESTE ARCHIVO EXISTE
+ *
+ * Había dos formatos. El bot colocaba el cobro por llamada en
+ * `endpoints.x402Ask`; la plantilla lo ponía en la raíz, como `x402Ask`. Los
+ * dos servían la misma información y ningún lector veía las dos, porque cada
+ * uno parseaba con un tipo escrito a mano allí donde hacía falta.
+ *
+ * No fue un descuido de nadie: el tipo `AgentJson` vivía dentro del bot, así
+ * que la plantilla —que no depende del bot— no tenía de dónde copiarlo y
+ * escribió su propio objeto. Dos implementaciones honestas de una idea que
+ * nunca se escribió en un sitio común divergen solas.
+ *
+ * Aquí está esa idea, en el paquete del que ya dependen la plantilla y el MCP.
+ * Quien sirva una ficha, que la sirva con esta forma; quien la lea, que la lea
+ * con `leerX402` y `leerMaxBriefChars`, que entienden también la forma vieja.
+ *
+ * COMPATIBILIDAD
+ *
+ * Hay agentes desplegados sirviendo el formato antiguo, y no se les puede
+ * pedir que se actualicen para seguir siendo contratables. Los lectores
+ * aceptan las dos formas y lo seguirán haciendo: quien escribe se moderniza,
+ * quien lee perdona. Es la misma regla que ya seguía `agentAddress`.
+ */
+import type { Address } from 'viem';
+/** Cobro por llamada (x402), tal y como lo anuncia un agente. */
+export interface FichaX402 {
+    method?: 'POST';
+    /** Ruta relativa. `url` gana si están las dos. */
+    path?: string;
+    url?: string;
+    scheme?: string;
+    /** Token ERC-20 en el que cobra. */
+    asset?: Address;
+    assetSymbol?: string;
+    /** Precio por llamada, en wei del token, como cadena decimal. */
+    amount?: string;
+    payTo?: Address;
+    howTo?: string;
+}
+/** Cómo mandarle el encargo a un agente, y cuánto texto acepta. */
+export interface FichaPostBrief {
+    method?: 'POST';
+    path?: string;
+    signMessage?: string;
+    body?: string;
+    /**
+     * Tope de caracteres del encargo.
+     *
+     * Publicarlo es lo que evita que un cliente bloquee el pago con un encargo
+     * que el agente va a rechazar. Ausente significa NO LO DICE, que no es lo
+     * mismo que «no hay tope»: tratarlo como ilimitado es volver a averiguarlo
+     * pagando.
+     */
+    maxBriefChars?: number;
+}
+/** Cómo descargar el resultado ya entregado. */
+export interface FichaGetResult {
+    method?: 'GET';
+    path?: string;
+    signMessage?: string;
+}
+/**
+ * La ficha completa. Casi todo es opcional a propósito: los dos motores tienen
+ * capacidades distintas —el de la plantilla no lee el registry al servirla, y
+ * el del bot sí— y un esquema que obligue a rellenar lo que no se sabe termina
+ * rellenándose con mentiras.
+ */
+export interface AgentCard {
+    /** La dirección on-chain que este dominio declara suya. Es lo que verifica. */
+    agent?: Address;
+    /** Alias antiguo de `agent`. Se sigue leyendo; no lo escribas en fichas nuevas. */
+    agentAddress?: Address;
+    protocol?: 'panal';
+    network?: string;
+    chainId?: number;
+    name?: string;
+    description?: string;
+    skills?: string[];
+    price?: {
+        amountWei?: string;
+        currency?: Address;
+        symbol?: string;
+    } | null;
+    active?: boolean | null;
+    contracts?: {
+        escrow?: Address;
+        registry?: Address;
+        token?: Address;
+    };
+    endpoints?: {
+        base?: string | null;
+        postBrief?: FichaPostBrief;
+        getResult?: FichaGetResult;
+        x402Ask?: FichaX402;
+        indexer?: string | null;
+    };
+    /** Alias ANTIGUO de `endpoints.x402Ask`. Se lee; no se escribe. */
+    x402Ask?: FichaX402;
+    howToHire?: string[];
+}
+/** La dirección que la ficha declara suya, mirando también el alias viejo. */
+export declare function leerDireccion(card: unknown): string | null;
+/**
+ * El bloque de cobro por llamada, venga en el sitio nuevo o en el viejo.
+ *
+ * El sitio canónico gana si están los dos: un agente que sirva ambos está en
+ * mitad de una migración, y el nuevo es el que va a seguir manteniendo.
+ */
+export declare function leerX402(card: unknown): FichaX402 | null;
+/**
+ * El tope de caracteres del encargo, o `null` si la ficha no lo dice.
+ *
+ * `null` es NO LO SÉ y hay que tratarlo así. La ficha la sirve un desconocido,
+ * así que solo cuenta un entero positivo: un 0 o un negativo harían imposible
+ * cualquier encargo, y eso lo decide el agente bajando su tope, no mandando
+ * basura en un campo.
+ */
+export declare function leerMaxBriefChars(card: unknown): number | null;

package/dist/agent-card.js

@@ -0,0 +1,54 @@
+/**
+ * La ficha que un agente sirve en `GET /agent.json`.
+ *
+ * POR QUÉ ESTE ARCHIVO EXISTE
+ *
+ * Había dos formatos. El bot colocaba el cobro por llamada en
+ * `endpoints.x402Ask`; la plantilla lo ponía en la raíz, como `x402Ask`. Los
+ * dos servían la misma información y ningún lector veía las dos, porque cada
+ * uno parseaba con un tipo escrito a mano allí donde hacía falta.
+ *
+ * No fue un descuido de nadie: el tipo `AgentJson` vivía dentro del bot, así
+ * que la plantilla —que no depende del bot— no tenía de dónde copiarlo y
+ * escribió su propio objeto. Dos implementaciones honestas de una idea que
+ * nunca se escribió en un sitio común divergen solas.
+ *
+ * Aquí está esa idea, en el paquete del que ya dependen la plantilla y el MCP.
+ * Quien sirva una ficha, que la sirva con esta forma; quien la lea, que la lea
+ * con `leerX402` y `leerMaxBriefChars`, que entienden también la forma vieja.
+ *
+ * COMPATIBILIDAD
+ *
+ * Hay agentes desplegados sirviendo el formato antiguo, y no se les puede
+ * pedir que se actualicen para seguir siendo contratables. Los lectores
+ * aceptan las dos formas y lo seguirán haciendo: quien escribe se moderniza,
+ * quien lee perdona. Es la misma regla que ya seguía `agentAddress`.
+ */
+/** La dirección que la ficha declara suya, mirando también el alias viejo. */
+export function leerDireccion(card) {
+    const c = card;
+    const dir = typeof c?.agent === 'string' ? c.agent : typeof c?.agentAddress === 'string' ? c.agentAddress : '';
+    return dir || null;
+}
+/**
+ * El bloque de cobro por llamada, venga en el sitio nuevo o en el viejo.
+ *
+ * El sitio canónico gana si están los dos: un agente que sirva ambos está en
+ * mitad de una migración, y el nuevo es el que va a seguir manteniendo.
+ */
+export function leerX402(card) {
+    const c = card;
+    return c?.endpoints?.x402Ask ?? c?.x402Ask ?? null;
+}
+/**
+ * El tope de caracteres del encargo, o `null` si la ficha no lo dice.
+ *
+ * `null` es NO LO SÉ y hay que tratarlo así. La ficha la sirve un desconocido,
+ * así que solo cuenta un entero positivo: un 0 o un negativo harían imposible
+ * cualquier encargo, y eso lo decide el agente bajando su tope, no mandando
+ * basura en un campo.
+ */
+export function leerMaxBriefChars(card) {
+    const max = card?.endpoints?.postBrief?.maxBriefChars;
+    return typeof max === 'number' && Number.isInteger(max) && max > 0 ? max : null;
+}

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;
@@ -290,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

@@ -17,6 +17,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 { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
@@ -33,6 +34,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;
@@ -643,11 +673,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) {
@@ -683,7 +733,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.
@@ -701,8 +754,11 @@ export class PanalClient {
             const url = await assertPublicUrl(new URL('/agent.json', base).toString(), options);
             const res = await fetchLimited(url, { timeoutMs: 10_000 });
             if (res.status === 200) {
-                const card = JSON.parse(res.text);
-                const anunciado = card.endpoints?.x402Ask;
+                // `leerX402` entiende las dos formas. Antes esto solo miraba
+                // `endpoints.x402Ask`, así que con la ficha de un agente de plantilla
+                // no encontraba nada y caía a la convención: funcionaba de casualidad,
+                // y solo mientras el agente escuchara justo en /x402/ask.
+                const anunciado = leerX402(JSON.parse(res.text));
                 if (anunciado?.url)
                     return anunciado.url;
                 if (anunciado?.path)

package/dist/index.d.ts

@@ -36,3 +36,5 @@ export type { SettleDeps, SettleResult, X402Payment, X402ServerAccept, X402Serve
 export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';
 export type { CallEnvelope } from './envelope.js';
 export type { UrlGuardOptions } from './net.js';
+export { leerDireccion, leerMaxBriefChars, leerX402 } from './agent-card.js';
+export type { AgentCard, FichaGetResult, FichaPostBrief, FichaX402 } from './agent-card.js';

package/dist/index.js

@@ -33,3 +33,6 @@ export { FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendFilesManifest
 export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';
 // El sobre que viaja entre agentes: profundidad, presupuesto y detección de ciclos.
 export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';
+// 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, leerX402 } from './agent-card.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.10.0",
+  "version": "0.11.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",
+    "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 && tsx test/agent-card.test.ts",
     "test:nombres": "tsx test/nombres.test.ts"
   }
 }