@panal/sdk 0.1.0

package/dist/chains.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Panal SDK — redes y direcciones de los contratos.
+ *
+ * Hasta ahora esto vivía duplicado en tres sitios: el frontend
+ * (`src/contracts/config.ts`, atado a `import.meta.env` de Vite), el bot
+ * (`bot/src/config.ts`) y el servidor MCP. Quien quisiera integrarse con Panal
+ * tenía que copiar las direcciones a mano de uno de ellos, y cuando un contrato
+ * rotara no habría forma de enterarse. Aquí son un dato exportado y versionado
+ * con el paquete.
+ */
+import type { Address } from 'viem';
+/** Monad mainnet. Es la red por defecto: Panal está desplegado y en uso ahí. */
+export declare const monad: {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "MonadVision";
+            readonly url: "https://monadvision.com";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: import("viem").ChainContract | {
+            [sourceId: number]: import("viem").ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: import("viem").ChainContract | undefined;
+        ensUniversalResolver?: import("viem").ChainContract | undefined;
+        multicall3?: import("viem").ChainContract | undefined;
+        erc6492Verifier?: import("viem").ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 143;
+    name: "Monad";
+    nativeCurrency: {
+        readonly name: "Monad";
+        readonly symbol: "MON";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://rpc.monad.xyz"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    supportsTransactionReplacementDetection?: boolean | undefined | undefined;
+    testnet?: boolean | undefined | undefined;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+};
+/** Monad testnet, para probar un agente sin gastar dinero real. */
+export declare const monadTestnet: {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "MonadVision";
+            readonly url: "https://testnet.monadvision.com";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: import("viem").ChainContract | {
+            [sourceId: number]: import("viem").ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: import("viem").ChainContract | undefined;
+        ensUniversalResolver?: import("viem").ChainContract | undefined;
+        multicall3?: import("viem").ChainContract | undefined;
+        erc6492Verifier?: import("viem").ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 10143;
+    name: "Monad Testnet";
+    nativeCurrency: {
+        readonly name: "Monad";
+        readonly symbol: "MON";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://testnet-rpc.monad.xyz"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    supportsTransactionReplacementDetection?: boolean | undefined | undefined;
+    testnet: true;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+};
+export type PanalNetwork = 'mainnet' | 'testnet';
+export interface PanalAddresses {
+    registry: Address;
+    escrow: Address;
+    /** El token $PANAL. Los agentes pueden cobrar en él o en MON nativo. */
+    panalToken: Address;
+    /** Multisig 2-de-3 que resuelve las disputas. Se lee del escrow en caliente. */
+    arbitrator: Address;
+}
+/** Desplegados en Monad mainnet el 2026-07-29 (escrow v2 auditado). */
+export declare const MAINNET_ADDRESSES: PanalAddresses;
+/**
+ * En testnet solo hay registry y escrow desplegados. El resto queda a cero: el
+ * cliente avisa si se pide una operación que los necesite, en vez de mandar una
+ * transacción a la dirección cero.
+ */
+export declare const TESTNET_ADDRESSES: PanalAddresses;
+/** `address(0)` significa MON nativo en todo el protocolo. */
+export declare const NATIVE_CURRENCY: Address;
+export declare function addressesFor(network: PanalNetwork): PanalAddresses;
+export declare function chainFor(network: PanalNetwork): {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "MonadVision";
+            readonly url: "https://monadvision.com";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: import("viem").ChainContract | {
+            [sourceId: number]: import("viem").ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: import("viem").ChainContract | undefined;
+        ensUniversalResolver?: import("viem").ChainContract | undefined;
+        multicall3?: import("viem").ChainContract | undefined;
+        erc6492Verifier?: import("viem").ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 143;
+    name: "Monad";
+    nativeCurrency: {
+        readonly name: "Monad";
+        readonly symbol: "MON";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://rpc.monad.xyz"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    supportsTransactionReplacementDetection?: boolean | undefined | undefined;
+    testnet?: boolean | undefined | undefined;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+} | {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "MonadVision";
+            readonly url: "https://testnet.monadvision.com";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts?: {
+        [x: string]: import("viem").ChainContract | {
+            [sourceId: number]: import("viem").ChainContract | undefined;
+        } | undefined;
+        ensRegistry?: import("viem").ChainContract | undefined;
+        ensUniversalResolver?: import("viem").ChainContract | undefined;
+        multicall3?: import("viem").ChainContract | undefined;
+        erc6492Verifier?: import("viem").ChainContract | undefined;
+    } | undefined;
+    ensTlds?: readonly string[] | undefined;
+    id: 10143;
+    name: "Monad Testnet";
+    nativeCurrency: {
+        readonly name: "Monad";
+        readonly symbol: "MON";
+        readonly decimals: 18;
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly ["https://testnet-rpc.monad.xyz"];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    supportsTransactionReplacementDetection?: boolean | undefined | undefined;
+    testnet: true;
+    custom?: Record<string, unknown> | undefined;
+    extendSchema?: Record<string, unknown> | undefined;
+    fees?: import("viem").ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+        client: import("viem").Client;
+        phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+    }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+        runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+    }] | undefined;
+    serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+    verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+};
+/** Comisión del protocolo, en puntos básicos (250 = 2,5 %). */
+export declare const FEE_BPS = 250n;
+/** Si el cliente no aprueba ni disputa, el pago se libera solo pasado esto. */
+export declare const AUTO_RELEASE_SECONDS: number;
+/** Si el árbitro no resuelve una disputa en este plazo, se reembolsa al cliente. */
+export declare const DISPUTE_TIMEOUT_SECONDS: number;

package/dist/chains.js

@@ -0,0 +1,60 @@
+/**
+ * Panal SDK — redes y direcciones de los contratos.
+ *
+ * Hasta ahora esto vivía duplicado en tres sitios: el frontend
+ * (`src/contracts/config.ts`, atado a `import.meta.env` de Vite), el bot
+ * (`bot/src/config.ts`) y el servidor MCP. Quien quisiera integrarse con Panal
+ * tenía que copiar las direcciones a mano de uno de ellos, y cuando un contrato
+ * rotara no habría forma de enterarse. Aquí son un dato exportado y versionado
+ * con el paquete.
+ */
+import { defineChain } from 'viem';
+/** Monad mainnet. Es la red por defecto: Panal está desplegado y en uso ahí. */
+export const monad = defineChain({
+    id: 143,
+    name: 'Monad',
+    nativeCurrency: { name: 'Monad', symbol: 'MON', decimals: 18 },
+    rpcUrls: { default: { http: ['https://rpc.monad.xyz'] } },
+    blockExplorers: { default: { name: 'MonadVision', url: 'https://monadvision.com' } },
+});
+/** Monad testnet, para probar un agente sin gastar dinero real. */
+export const monadTestnet = defineChain({
+    id: 10143,
+    name: 'Monad Testnet',
+    nativeCurrency: { name: 'Monad', symbol: 'MON', decimals: 18 },
+    rpcUrls: { default: { http: ['https://testnet-rpc.monad.xyz'] } },
+    blockExplorers: { default: { name: 'MonadVision', url: 'https://testnet.monadvision.com' } },
+    testnet: true,
+});
+/** Desplegados en Monad mainnet el 2026-07-29 (escrow v2 auditado). */
+export const MAINNET_ADDRESSES = {
+    registry: '0x89a812BFb1c35fc814ef25a3E6Ca75068B16Ac51',
+    escrow: '0xe138A9A492CFe27A13f8b7A6D312DA831791bCe9',
+    panalToken: '0x2e2e44e7fa6178822d4397299f719e89d1a67777',
+    arbitrator: '0xc384C1F5D6716571DA84329BeAaE6F064C6b1Fe0',
+};
+/**
+ * En testnet solo hay registry y escrow desplegados. El resto queda a cero: el
+ * cliente avisa si se pide una operación que los necesite, en vez de mandar una
+ * transacción a la dirección cero.
+ */
+export const TESTNET_ADDRESSES = {
+    registry: '0x0000000000000000000000000000000000000000',
+    escrow: '0x0000000000000000000000000000000000000000',
+    panalToken: '0x0000000000000000000000000000000000000000',
+    arbitrator: '0x0000000000000000000000000000000000000000',
+};
+/** `address(0)` significa MON nativo en todo el protocolo. */
+export const NATIVE_CURRENCY = '0x0000000000000000000000000000000000000000';
+export function addressesFor(network) {
+    return network === 'mainnet' ? MAINNET_ADDRESSES : TESTNET_ADDRESSES;
+}
+export function chainFor(network) {
+    return network === 'mainnet' ? monad : monadTestnet;
+}
+/** Comisión del protocolo, en puntos básicos (250 = 2,5 %). */
+export const FEE_BPS = 250n;
+/** Si el cliente no aprueba ni disputa, el pago se libera solo pasado esto. */
+export const AUTO_RELEASE_SECONDS = 3 * 24 * 60 * 60;
+/** Si el árbitro no resuelve una disputa en este plazo, se reembolsa al cliente. */
+export const DISPUTE_TIMEOUT_SECONDS = 14 * 24 * 60 * 60;

package/dist/client.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Panal SDK — el cliente.
+ *
+ *   import { createPanalClient } from '@panal/sdk';
+ *
+ *   const panal = createPanalClient();                 // solo lectura, mainnet
+ *   const agents = await panal.searchAgents('traducción');
+ *
+ * Con una cuenta pasa a poder contratar:
+ *
+ *   import { privateKeyToAccount } from 'viem/accounts';
+ *   const panal = createPanalClient({ account: privateKeyToAccount(key) });
+ *   const { taskId } = await panal.hire({ agent, brief });
+ *
+ * Sin configuración apunta a Monad mainnet, que es donde Panal está desplegado
+ * y en uso: el caso de "quiero probar esto ahora" no debería exigir un .env.
+ */
+import type { Account, Address, Hex, PublicClient } from 'viem';
+import { type PanalAddresses, type PanalNetwork } from './chains.js';
+import { type Agent, type Task } from './types.js';
+export interface PanalClientOptions {
+    /** `mainnet` por defecto. */
+    network?: PanalNetwork;
+    /** RPC propio. Sin esto se usa el público, que limita a ~15 llamadas/s. */
+    rpcUrl?: string;
+    /** Necesaria solo para contratar y aprobar; leer no la requiere. */
+    account?: Account;
+    /** Sobrescribe direcciones concretas (para pruebas o un despliegue propio). */
+    addresses?: Partial<PanalAddresses>;
+}
+export interface HireParams {
+    /** Dirección del agente que hará el trabajo. */
+    agent: Address;
+    /** El encargo. No viaja on-chain: solo su keccak256. */
+    brief: string;
+    /**
+     * Cuánto pagar, en unidades mínimas. Por defecto el `pricePerTask` que el
+     * agente publica, leído en el momento de contratar.
+     */
+    amount?: bigint;
+    /** Plazo de entrega. Por defecto 24 h desde ahora. */
+    deadline?: bigint;
+}
+export interface HireResult {
+    taskId: bigint;
+    txHash: Hex;
+    amount: bigint;
+    currency: Address;
+    /** El hash del brief que quedó registrado, para poder probarlo después. */
+    taskHash: Hex;
+}
+export declare class PanalClient {
+    readonly network: PanalNetwork;
+    readonly addresses: PanalAddresses;
+    readonly publicClient: PublicClient;
+    readonly account?: Account;
+    private readonly walletClient?;
+    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[]>;
+    /** Un agente concreto, con su metadata ya interpretada. */
+    getAgent(address: Address): Promise<Agent>;
+    /**
+     * Busca agentes activos por texto libre sobre nombre, descripción y skills.
+     *
+     * Sin `query` devuelve todos los activos. La búsqueda es del lado del cliente
+     * porque el registry no indexa texto: son pocos agentes y una lectura
+     * paginada sale más barata que montar un índice.
+     */
+    searchAgents(query?: string, options?: {
+        includeInactive?: boolean;
+    }): Promise<Agent[]>;
+    /** Una tarea por su id. */
+    getTask(taskId: bigint): Promise<Task>;
+    /** Cuántas tareas se han creado en total (los ids van de 0 a este número - 1). */
+    getTaskCount(): Promise<bigint>;
+    /** Saldo acreditado y pendiente de retirar, por moneda. */
+    getPendingWithdrawal(account: Address, currency?: Address): Promise<bigint>;
+    /**
+     * Contrata a un agente: bloquea el pago en el escrow y crea la tarea.
+     *
+     * El brief no se sube a ningún sitio; lo que va on-chain es su keccak256. Se
+     * lo tienes que hacer llegar tú al agente (por su endpoint, por el dashboard
+     * o como quieras), y el hash sirve para demostrar después qué se encargó.
+     *
+     * Si el agente cobra en $PANAL, esto hace dos transacciones: el `approve` por
+     * el importe exacto y luego `createTask`. En MON nativo va en una sola.
+     */
+    hire(params: HireParams): Promise<HireResult>;
+    /**
+     * Aprueba el resultado y libera el pago, con una valoración de 1 a 5.
+     *
+     * Si no apruebas ni disputas, el escrow libera el pago solo a las 72 h. Este
+     * método existe para cobrar antes y, sobre todo, para que la valoración quede
+     * registrada: sin ella el agente no construye reputación.
+     */
+    approveTask(taskId: bigint, rating: number): Promise<Hex>;
+    /** Retira lo acreditado en una moneda (patrón pull payment). */
+    withdraw(currency?: Address): Promise<Hex>;
+    /** Comprueba el saldo antes de firmar, para fallar con un mensaje legible. */
+    private assertFunds;
+}
+/** Atajo: `createPanalClient()` sin argumentos ya habla con mainnet. */
+export declare function createPanalClient(options?: PanalClientOptions): PanalClient;

package/dist/client.js

@@ -0,0 +1,266 @@
+/**
+ * Panal SDK — el cliente.
+ *
+ *   import { createPanalClient } from '@panal/sdk';
+ *
+ *   const panal = createPanalClient();                 // solo lectura, mainnet
+ *   const agents = await panal.searchAgents('traducción');
+ *
+ * Con una cuenta pasa a poder contratar:
+ *
+ *   import { privateKeyToAccount } from 'viem/accounts';
+ *   const panal = createPanalClient({ account: privateKeyToAccount(key) });
+ *   const { taskId } = await panal.hire({ agent, brief });
+ *
+ * Sin configuración apunta a Monad mainnet, que es donde Panal está desplegado
+ * 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 { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
+import { TaskStatus, parseAgentMetadata } from './types.js';
+/** Cuántos agentes se leen por llamada al registry. */
+const REGISTRY_PAGE = 50n;
+/** Tope duro de agentes recorridos, por si el registro crece mucho. */
+const REGISTRY_MAX = 500;
+export class PanalClient {
+    network;
+    addresses;
+    publicClient;
+    account;
+    walletClient;
+    constructor(options = {}) {
+        this.network = options.network ?? 'mainnet';
+        const chain = chainFor(this.network);
+        this.addresses = { ...addressesFor(this.network), ...options.addresses };
+        if (this.addresses.registry === NATIVE_CURRENCY || this.addresses.escrow === NATIVE_CURRENCY) {
+            throw new Error(`Panal no tiene contratos desplegados en ${this.network}. ` +
+                'Usa network: "mainnet", o pasa `addresses` con los tuyos.');
+        }
+        const transport = http(options.rpcUrl ?? chain.rpcUrls.default.http[0]);
+        this.publicClient = createPublicClient({ chain, transport });
+        this.account = options.account;
+        if (options.account) {
+            this.walletClient = createWalletClient({ chain, transport, account: options.account });
+        }
+    }
+    /** El wallet client, o un error que dice exactamente qué falta. */
+    wallet() {
+        if (!this.walletClient || !this.account) {
+            throw new Error('Esta operación firma una transacción: crea el cliente con `account`.');
+        }
+        return this.walletClient;
+    }
+    // -------------------------------------------------------------------------
+    // Lectura
+    // -------------------------------------------------------------------------
+    /** Todos los agentes del registry, activos e inactivos. */
+    async listAgents() {
+        const count = (await this.publicClient.readContract({
+            address: this.addresses.registry,
+            abi: registryAbi,
+            functionName: 'getAgentCount',
+        }));
+        const addresses = [];
+        const total = Math.min(Number(count), REGISTRY_MAX);
+        for (let offset = 0n; offset < BigInt(total); offset += REGISTRY_PAGE) {
+            const page = (await this.publicClient.readContract({
+                address: this.addresses.registry,
+                abi: registryAbi,
+                functionName: 'getAgents',
+                args: [offset, REGISTRY_PAGE],
+            }));
+            addresses.push(...page);
+            if (page.length < Number(REGISTRY_PAGE))
+                break;
+        }
+        return Promise.all(addresses.map((address) => this.getAgent(address)));
+    }
+    /** Un agente concreto, con su metadata ya interpretada. */
+    async getAgent(address) {
+        const raw = (await this.publicClient.readContract({
+            address: this.addresses.registry,
+            abi: registryAbi,
+            functionName: 'getAgent',
+            args: [getAddress(address)],
+        }));
+        return {
+            address: getAddress(address),
+            owner: raw.owner,
+            pricePerTask: raw.pricePerTask,
+            currency: raw.currency,
+            active: raw.active,
+            registeredAt: raw.registeredAt,
+            metadataURI: raw.metadataURI,
+            metadata: parseAgentMetadata(raw.metadataURI),
+        };
+    }
+    /**
+     * Busca agentes activos por texto libre sobre nombre, descripción y skills.
+     *
+     * Sin `query` devuelve todos los activos. La búsqueda es del lado del cliente
+     * porque el registry no indexa texto: son pocos agentes y una lectura
+     * paginada sale más barata que montar un índice.
+     */
+    async searchAgents(query, options = {}) {
+        const all = await this.listAgents();
+        const pool = options.includeInactive ? all : all.filter((a) => a.active);
+        if (!query?.trim())
+            return pool;
+        const needles = query.toLowerCase().split(/\s+/).filter(Boolean);
+        return pool.filter((agent) => {
+            const haystack = [agent.metadata.name, agent.metadata.description, ...agent.metadata.skills]
+                .join(' ')
+                .toLowerCase();
+            return needles.every((n) => haystack.includes(n));
+        });
+    }
+    /** Una tarea por su id. */
+    async getTask(taskId) {
+        // El ABI declara los campos con nombre, así que viem devuelve un objeto y
+        // no una tupla: desestructurar por posición aquí compilaría pero leería
+        // basura si algún día cambia el orden.
+        const raw = (await this.publicClient.readContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'tasks',
+            args: [taskId],
+        }));
+        return { id: taskId, ...raw };
+    }
+    /** Cuántas tareas se han creado en total (los ids van de 0 a este número - 1). */
+    async getTaskCount() {
+        return (await this.publicClient.readContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'getTaskCount',
+        }));
+    }
+    /** Saldo acreditado y pendiente de retirar, por moneda. */
+    async getPendingWithdrawal(account, currency = NATIVE_CURRENCY) {
+        return (await this.publicClient.readContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'pendingWithdrawals',
+            args: [currency, getAddress(account)],
+        }));
+    }
+    // -------------------------------------------------------------------------
+    // Escritura
+    // -------------------------------------------------------------------------
+    /**
+     * Contrata a un agente: bloquea el pago en el escrow y crea la tarea.
+     *
+     * El brief no se sube a ningún sitio; lo que va on-chain es su keccak256. Se
+     * lo tienes que hacer llegar tú al agente (por su endpoint, por el dashboard
+     * o como quieras), y el hash sirve para demostrar después qué se encargó.
+     *
+     * Si el agente cobra en $PANAL, esto hace dos transacciones: el `approve` por
+     * el importe exacto y luego `createTask`. En MON nativo va en una sola.
+     */
+    async hire(params) {
+        const wallet = this.wallet();
+        const agent = await this.getAgent(params.agent);
+        if (!agent.active)
+            throw new Error(`El agente ${params.agent} está dado de baja: no acepta encargos.`);
+        const amount = params.amount ?? agent.pricePerTask;
+        if (amount <= 0n)
+            throw new Error('El importe tiene que ser mayor que cero.');
+        const deadline = params.deadline ?? BigInt(Math.floor(Date.now() / 1000) + 24 * 60 * 60);
+        const taskHash = keccak256(toBytes(params.brief));
+        const isNative = agent.currency.toLowerCase() === NATIVE_CURRENCY.toLowerCase();
+        // Antes de nada: ¿hay saldo? Fallar aquí da un mensaje claro; fallar dentro
+        // del contrato da un revert sin contexto.
+        await this.assertFunds(agent.currency, amount, isNative);
+        if (!isNative) {
+            // approve por el importe exacto, no infinito: si el escrow tuviera un
+            // fallo, la exposición se limita a este encargo.
+            const approveHash = await wallet.writeContract({
+                address: agent.currency,
+                abi: erc20Abi,
+                functionName: 'approve',
+                args: [this.addresses.escrow, amount],
+                chain: chainFor(this.network),
+                account: this.account,
+            });
+            await this.publicClient.waitForTransactionReceipt({ hash: approveHash });
+        }
+        const txHash = await wallet.writeContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'createTask',
+            args: [agent.address, taskHash, deadline, agent.currency, amount],
+            value: isNative ? amount : 0n,
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        const receipt = await this.publicClient.waitForTransactionReceipt({ hash: txHash });
+        if (receipt.status !== 'success')
+            throw new Error(`createTask revirtió (tx ${txHash}).`);
+        // El id es el contador ANTES de crear: se relee del recibo para no asumirlo.
+        const taskId = (await this.getTaskCount()) - 1n;
+        return { taskId, txHash, amount, currency: agent.currency, taskHash };
+    }
+    /**
+     * Aprueba el resultado y libera el pago, con una valoración de 1 a 5.
+     *
+     * Si no apruebas ni disputas, el escrow libera el pago solo a las 72 h. Este
+     * método existe para cobrar antes y, sobre todo, para que la valoración quede
+     * registrada: sin ella el agente no construye reputación.
+     */
+    async approveTask(taskId, rating) {
+        if (!Number.isInteger(rating) || rating < 1 || rating > 5) {
+            throw new Error('La valoración es un entero de 1 a 5.');
+        }
+        const wallet = this.wallet();
+        const task = await this.getTask(taskId);
+        if (task.status !== TaskStatus.Delivered) {
+            throw new Error(`La tarea #${taskId} está "${TaskStatus[task.status]}": solo se aprueba lo entregado.`);
+        }
+        const hash = await wallet.writeContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'approveAndRelease',
+            args: [taskId, rating],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    /** Retira lo acreditado en una moneda (patrón pull payment). */
+    async withdraw(currency = NATIVE_CURRENCY) {
+        const wallet = this.wallet();
+        const hash = await wallet.writeContract({
+            address: this.addresses.escrow,
+            abi: escrowAbi,
+            functionName: 'withdraw',
+            args: [currency],
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.publicClient.waitForTransactionReceipt({ hash });
+        return hash;
+    }
+    /** Comprueba el saldo antes de firmar, para fallar con un mensaje legible. */
+    async assertFunds(currency, amount, isNative) {
+        const owner = this.account.address;
+        const balance = isNative
+            ? await this.publicClient.getBalance({ address: owner })
+            : (await this.publicClient.readContract({
+                address: currency,
+                abi: erc20Abi,
+                functionName: 'balanceOf',
+                args: [owner],
+            }));
+        if (balance < amount) {
+            const symbol = isNative ? 'MON' : '$PANAL';
+            throw new Error(`Saldo insuficiente: hacen falta ${formatEther(amount)} ${symbol} y ${owner} tiene ${formatEther(balance)}.` +
+                (isNative ? ' Además necesitas algo extra para el gas.' : ''));
+        }
+    }
+}
+/** Atajo: `createPanalClient()` sin argumentos ya habla con mainnet. */
+export function createPanalClient(options = {}) {
+    return new PanalClient(options);
+}