@panal/sdk 0.6.0 → 0.7.0

package/dist/client.d.ts

@@ -29,6 +29,20 @@ export interface PanalClientOptions {
     account?: Account;
     /** Sobrescribe direcciones concretas (para pruebas o un despliegue propio). */
     addresses?: Partial<PanalAddresses>;
+    /**
+     * Indexador desde el que buscar agentes. `https://api.panal.lat` por defecto.
+     *
+     * Buscar leyendo el registro entero deja de funcionar justo cuando más falta
+     * hace: `searchAgents` pagina hasta 500 agentes y luego lanza 500 lecturas a
+     * la vez, y el RPC público corta a partir de ~50 concurrentes. O sea que
+     * cuantos más agentes hay, MENOS puede un agente encontrar a otro.
+     *
+     * Con el indexador es una petición. Si no responde, se vuelve al registro:
+     * peor y con tope, pero nunca sin respuesta.
+     *
+     * `null` lo desactiva y lee siempre de la cadena.
+     */
+    indexerUrl?: string | null;
 }
 export interface HireParams {
     /** Dirección del agente que hará el trabajo. */
@@ -62,11 +76,21 @@ export declare class PanalClient {
      * cliente se creó sin cuenta, o sea en modo solo lectura.
      */
     readonly walletClient?: WalletClient;
+    /** Indexador para buscar agentes, o null si se lee siempre de la cadena. */
+    readonly indexerUrl: string | null;
     constructor(options?: PanalClientOptions);
     /** El wallet client, o un error que dice exactamente qué falta. */
     private wallet;
     /** Todos los agentes del registry, activos e inactivos. */
     listAgents(): Promise<Agent[]>;
+    /**
+     * Los agentes que dice el indexador, o null si no se puede contar con él.
+     *
+     * Devuelve null —y no una lista vacía— cuando no responde, va atrasado o
+     * contesta algo raro: quien llama tiene que poder distinguir «no hay
+     * ninguno» de «no lo sé», porque en el segundo caso toca leer la cadena.
+     */
+    private buscarEnIndice;
     /** Un agente concreto, con su metadata ya interpretada. */
     getAgent(address: Address): Promise<Agent>;
     /**
@@ -78,6 +102,8 @@ export declare class PanalClient {
      */
     searchAgents(query?: string, options?: {
         includeInactive?: boolean;
+        skill?: string;
+        limit?: number;
     }): Promise<Agent[]>;
     /** Una tarea por su id. */
     getTask(taskId: bigint): Promise<Task>;
@@ -166,6 +192,14 @@ export declare class PanalClient {
         quote?: X402Accept;
         allowInsecure?: boolean;
         timeoutMs?: number;
+        /**
+         * Sobre de la cadena, YA descendido con `descend()`. Va aquí y no se
+         * construye dentro porque `askAgent` apunta a un agente concreto: quien
+         * elige a quién llamar es quien tiene que gastar el salto. Sin esto, un
+         * agente que delega con `askAgent` rompía la cadena — el siguiente no
+         * heredaba ni presupuesto ni camino, y el ciclo dejaba de detectarse.
+         */
+        envelope?: CallEnvelope;
     }): Promise<AskResult>;
     /**
      * Busca un agente con esa skill, negocia el precio y le paga por la consulta.

package/dist/client.js

@@ -37,6 +37,8 @@ export class PanalClient {
      * cliente se creó sin cuenta, o sea en modo solo lectura.
      */
     walletClient;
+    /** Indexador para buscar agentes, o null si se lee siempre de la cadena. */
+    indexerUrl;
     constructor(options = {}) {
         this.network = options.network ?? 'mainnet';
         const chain = chainFor(this.network);
@@ -45,6 +47,7 @@ export class PanalClient {
             throw new Error(`Panal no tiene contratos desplegados en ${this.network}. ` +
                 'Usa network: "mainnet", o pasa `addresses` con los tuyos.');
         }
+        this.indexerUrl = options.indexerUrl === undefined ? 'https://api.panal.lat' : options.indexerUrl;
         const transport = http(options.rpcUrl ?? chain.rpcUrls.default.http[0]);
         this.publicClient = createPublicClient({ chain, transport });
         this.account = options.account;
@@ -84,6 +87,80 @@ export class PanalClient {
         }
         return Promise.all(addresses.map((address) => this.getAgent(address)));
     }
+    /**
+     * Los agentes que dice el indexador, o null si no se puede contar con él.
+     *
+     * Devuelve null —y no una lista vacía— cuando no responde, va atrasado o
+     * contesta algo raro: quien llama tiene que poder distinguir «no hay
+     * ninguno» de «no lo sé», porque en el segundo caso toca leer la cadena.
+     */
+    async buscarEnIndice(query, options) {
+        if (!this.indexerUrl)
+            return null;
+        try {
+            const url = new URL('/index/agents', this.indexerUrl);
+            if (query?.trim())
+                url.searchParams.set('q', query.trim());
+            if (options.skill?.trim())
+                url.searchParams.set('skill', options.skill.trim());
+            if (options.includeInactive)
+                url.searchParams.set('include_inactive', 'true');
+            url.searchParams.set('limit', String(Math.min(options.limit ?? 50, 200)));
+            const res = await fetchLimited(url.toString(), { timeoutMs: 8000 });
+            if (res.status !== 200)
+                return null;
+            const cuerpo = JSON.parse(res.text);
+            if (!Array.isArray(cuerpo.agents))
+                return null;
+            // `total` solo lo devuelve la respuesta del CATÁLOGO. Sin esta
+            // comprobación, un indexador viejo —que no entiende `q` ni `skill` pero
+            // responde igual con su lista de siempre— hacía creer que había filtrado:
+            // toda búsqueda devolvía todos los agentes, incluida una imposible.
+            // Un servidor que no entiende la pregunta y contesta es peor que uno que
+            // calla, porque no hay forma de notarlo desde fuera. Aquí sí.
+            if (typeof cuerpo.total !== 'number')
+                return null;
+            const out = [];
+            for (const raw of cuerpo.agents) {
+                // El indexador es un servicio, o sea que su respuesta se valida como
+                // la de cualquier desconocido: una ficha rota se descarta sin llevarse
+                // la búsqueda entera por delante.
+                const address = typeof raw.address === 'string' ? raw.address : null;
+                if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address))
+                    continue;
+                const skills = Array.isArray(raw.skills) ? raw.skills.filter((x) => typeof x === 'string') : [];
+                let pricePerTask;
+                let registeredAt;
+                try {
+                    pricePerTask = BigInt(String(raw.pricePerTask ?? '0'));
+                    registeredAt = BigInt(Number(raw.registeredAt ?? 0));
+                }
+                catch {
+                    continue;
+                }
+                const metadata = {
+                    name: typeof raw.name === 'string' ? raw.name : '',
+                    description: typeof raw.description === 'string' ? raw.description : '',
+                    skills,
+                    botUrl: typeof raw.botUrl === 'string' ? raw.botUrl : null,
+                };
+                out.push({
+                    address: getAddress(address),
+                    owner: getAddress(typeof raw.owner === 'string' && /^0x[0-9a-fA-F]{40}$/.test(raw.owner) ? raw.owner : address),
+                    pricePerTask,
+                    currency: getAddress(typeof raw.currency === 'string' && /^0x[0-9a-fA-F]{40}$/.test(raw.currency) ? raw.currency : NATIVE_CURRENCY),
+                    active: raw.active !== false,
+                    registeredAt,
+                    metadataURI: formatAgentMetadata(metadata),
+                    metadata,
+                });
+            }
+            return out;
+        }
+        catch {
+            return null;
+        }
+    }
     /** Un agente concreto, con su metadata ya interpretada. */
     async getAgent(address) {
         const raw = (await this.publicClient.readContract({
@@ -111,6 +188,13 @@ export class PanalClient {
      * paginada sale más barata que montar un índice.
      */
     async searchAgents(query, options = {}) {
+        // Por el indexador primero. Leer el registro entero para buscar deja de
+        // funcionar justo cuando más falta hace: son 500 lecturas a la vez contra
+        // un RPC que corta a partir de ~50 concurrentes, y con más de 500 agentes
+        // ni siquiera los ve. Aquí es una petición.
+        const delIndice = await this.buscarEnIndice(query, options);
+        if (delIndice !== null)
+            return delIndice;
         const all = await this.listAgents();
         const pool = options.includeInactive ? all : all.filter((a) => a.active);
         if (!query?.trim())
@@ -413,7 +497,10 @@ export class PanalClient {
         const tope = remainingBudget(options.envelope ?? null, options.maxSpend);
         if (tope <= 0n)
             throw new X402Error('El presupuesto de la cadena está agotado: no se puede delegar más.');
-        const candidates = (await this.searchAgents(skill))
+        // 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)

package/dist/files.d.ts

@@ -108,8 +108,16 @@ export interface DownloadOptions extends UrlGuardOptions {
     baseUrl?: string;
     /** Wallet del cliente; el agente solo entrega a quien pagó. */
     address?: string;
-    /** Firma de `Panal resultado #<taskId>`, la misma que abre `/result/:id`. */
+    /** Firma de `Panal resultado #<taskId> · <expira>`, la misma que abre `/result/:id`. */
     signature?: string;
+    /**
+     * Segundo en el que caduca esa firma, tal y como se firmó.
+     *
+     * Va con la firma porque el agente la necesita para reconstruir el mensaje.
+     * Mandarla en claro no regala nada: está DENTRO de lo firmado, así que
+     * cambiarla invalida la firma.
+     */
+    expira?: number;
     maxBytes?: number;
     timeoutMs?: number;
 }

package/dist/files.js

@@ -204,10 +204,19 @@ export function fileUrl(file, baseUrl) {
  */
 export async function downloadDeliveredFile(file, options = {}) {
     const destino = new URL(fileUrl(file, options.baseUrl));
+    // Las credenciales van en CABECERAS, no en la query.
+    //
+    // Esta firma abre el resultado y todos los archivos de la tarea, o sea que es
+    // un pase de acceso. En la query acababa escrita en el log de accesos del
+    // proxy y en el historial del navegador — se encontraron 23 en claro en un
+    // log de producción. Una cabecera no se registra por defecto.
+    const cabeceras = {};
     if (options.address)
-        destino.searchParams.set('address', options.address);
+        cabeceras['x-panal-address'] = options.address;
     if (options.signature)
-        destino.searchParams.set('signature', options.signature);
+        cabeceras['x-panal-signature'] = options.signature;
+    if (options.expira !== undefined)
+        cabeceras['x-panal-expira'] = String(options.expira);
     await assertPublicUrl(destino.toString(), options);
     // El tope se ata al tamaño ANUNCIADO, no al de por defecto: si el manifiesto
     // dice 2 MB, no hay razón para dejar que lleguen 25.
@@ -216,6 +225,7 @@ export async function downloadDeliveredFile(file, options = {}) {
         maxBytes: tope,
         timeoutMs: options.timeoutMs ?? 120_000,
         redirect: 'error',
+        headers: cabeceras,
     });
     if (status !== 200) {
         throw new FileVerificationError(`El agente respondió ${status} al pedirle "${file.name}".`, file.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",