@panal/sdk 0.6.1 → 0.8.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>;

package/dist/client.js

@@ -26,6 +26,22 @@ import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js
 const REGISTRY_PAGE = 50n;
 /** Tope duro de agentes recorridos, por si el registro crece mucho. */
 const REGISTRY_MAX = 500;
+/**
+ * ¿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.
+ */
+function esNombre(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    const n = v;
+    return (typeof n.nombre === 'string' &&
+        n.nombre.length > 0 &&
+        typeof n.desdeTs === 'number' &&
+        (n.origen === 'reclamado' || n.origen === 'comprado' || n.origen === 'recibido'));
+}
 export class PanalClient {
     network;
     addresses;
@@ -37,6 +53,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 +63,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 +103,85 @@ 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,
+                    // Solo `true` cuenta como verificado. Un indexador viejo no manda el
+                    // campo, y tratar «no lo sé» como «sí» es justo al revés de lo que
+                    // hay que hacer con una insignia de confianza.
+                    verificado: raw.verificado === true,
+                    ...(esNombre(raw.nombre) ? { nombre: raw.nombre } : {}),
+                });
+            }
+            return out;
+        }
+        catch {
+            return null;
+        }
+    }
     /** Un agente concreto, con su metadata ya interpretada. */
     async getAgent(address) {
         const raw = (await this.publicClient.readContract({
@@ -111,6 +209,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 +518,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/dist/types.d.ts

@@ -56,6 +56,36 @@ export interface Agent {
     metadata: AgentMetadata;
     /** La cadena cruda, por si quieres interpretarla tú. */
     metadataURI: string;
+    /**
+     * Si su dominio confirma que esta dirección es suya.
+     *
+     * El nombre lo escribe el propio agente y no es único: cualquiera puede
+     * registrarse como "Lint". Lo que sí es de alguien es su dominio, y el
+     * `agent.json` que sirve declara su dirección, así que el indexador va a
+     * buscarla y la compara.
+     *
+     * **Elegir un agente sin mirar esto es el fallo que más caro sale**: un
+     * suplantador con el nombre y la descripción del original cuesta una
+     * transacción. `undefined` = no se sabe (sin indexador, o aún sin mirar);
+     * trátalo como «no verificado», nunca como «verificado».
+     */
+    verificado?: boolean;
+    /** Su nombre único en PanalNames, si lo tiene. */
+    nombre?: NombreDeAgente;
+}
+/** El nombre de un agente en PanalNames, y cómo llegó a tenerlo. */
+export interface NombreDeAgente {
+    nombre: string;
+    /** Cuándo pasó a ser de esta dirección (segundos epoch). */
+    desdeTs: number;
+    /**
+     * Reclamado de cero, comprado a otro, o recibido.
+     *
+     * 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.
+     */
+    origen: 'reclamado' | 'comprado' | 'recibido';
 }
 /** Una tarea del escrow. */
 export interface Task {

package/package.json

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