@panal/sdk 0.2.0 → 0.5.0

package/dist/client.d.ts

@@ -15,7 +15,9 @@
  * 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 { Account, Address, Hex, PublicClient, WalletClient } from 'viem';
+import { type AskResult, type X402Accept } from './x402.js';
+import { type CallEnvelope } from './envelope.js';
 import { type PanalAddresses, type PanalNetwork } from './chains.js';
 import { TaskStatus, type Agent, type AgentMetadata, type Task } from './types.js';
 export interface PanalClientOptions {
@@ -54,7 +56,12 @@ export declare class PanalClient {
     readonly addresses: PanalAddresses;
     readonly publicClient: PublicClient;
     readonly account?: Account;
-    private readonly walletClient?;
+    /**
+     * Público a propósito: quien monte la mitad servidor de x402 lo necesita para
+     * ejecutar el `permit` y el `transferFrom` del cobro. Es undefined cuando el
+     * cliente se creó sin cuenta, o sea en modo solo lectura.
+     */
+    readonly walletClient?: WalletClient;
     constructor(options?: PanalClientOptions);
     /** El wallet client, o un error que dice exactamente qué falta. */
     private wallet;
@@ -140,6 +147,69 @@ export declare class PanalClient {
         limit?: number;
         status?: TaskStatus;
     }): Promise<Task[]>;
+    /**
+     * Pregunta el precio de un agente sin pagar nada.
+     *
+     * Es gratis y no compromete: puedes cotizar a varios candidatos y decidir.
+     */
+    quoteAgent(agent: Address, prompt: string, options?: {
+        allowInsecure?: boolean;
+    }): Promise<X402Accept>;
+    /**
+     * Paga a un agente concreto por una consulta y devuelve su respuesta.
+     *
+     * `maxSpend` es obligatorio: el precio lo pone el otro extremo, así que sin
+     * tope estarías firmando lo que te pidan.
+     */
+    askAgent(agent: Address, prompt: string, options: {
+        maxSpend: bigint;
+        quote?: X402Accept;
+        allowInsecure?: boolean;
+        timeoutMs?: number;
+    }): Promise<AskResult>;
+    /**
+     * Busca un agente con esa skill, negocia el precio y le paga por la consulta.
+     *
+     * Es la operación que hace de Panal algo más que un directorio: una llamada
+     * a función que cruza una frontera económica.
+     *
+     *   const respuesta = await panal.ask('traducción', 'traduce esto', {
+     *     maxSpend: parseEther('0.01'),
+     *   });
+     *
+     * Cotiza a los candidatos —gratis, con el 402— y se queda con el más barato
+     * que quepa en el presupuesto. Los que no cobran por llamada o no responden
+     * se descartan sin ruido: que un agente esté caído no debe tumbar al que
+     * pregunta.
+     */
+    ask(skill: string, prompt: string, options: {
+        maxSpend: bigint;
+        /** Cuántos candidatos se cotizan como mucho. Cada uno es una petición. */
+        maxCandidates?: number;
+        /** Descartar a estos (evita que un agente se llame a sí mismo). */
+        exclude?: Address[];
+        allowInsecure?: boolean;
+        timeoutMs?: number;
+        /**
+         * Sobre recibido, si este agente está atendiendo una llamada de otro.
+         * Sin él se abre una cadena nueva. Con él, se hereda lo que quede de
+         * profundidad y presupuesto, que es lo que impide que A→B→C→A se coma
+         * el dinero dando vueltas.
+         */
+        envelope?: CallEnvelope | null;
+        /** Saltos permitidos al abrir una cadena nueva. */
+        depth?: number;
+    }): Promise<AskResult & {
+        agent: Address;
+    }>;
+    /**
+     * Dónde escucha el x402 de un agente.
+     *
+     * Se prefiere lo que el propio agente anuncia en su `agent.json`; si no lo
+     * anuncia, se prueba la ruta por convención. Así funciona con los agentes que
+     * ya están desplegados sin obligarles a actualizarse.
+     */
+    private x402Endpoint;
     /** 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. */

package/dist/client.js

@@ -17,6 +17,9 @@
  */
 import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes } from 'viem';
 import { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+import { assertPublicUrl, fetchLimited } from './net.js';
+import { X402Error, payAndAsk, quoteAsk } from './x402.js';
+import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
 import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 /** Cuántos agentes se leen por llamada al registry. */
@@ -28,6 +31,11 @@ export class PanalClient {
     addresses;
     publicClient;
     account;
+    /**
+     * Público a propósito: quien monte la mitad servidor de x402 lo necesita para
+     * ejecutar el `permit` y el `transferFrom` del cobro. Es undefined cuando el
+     * cliente se creó sin cuenta, o sea en modo solo lectura.
+     */
     walletClient;
     constructor(options = {}) {
         this.network = options.network ?? 'mainnet';
@@ -347,6 +355,135 @@ export class PanalClient {
         }
         return found;
     }
+    // -------------------------------------------------------------------------
+    // Llamar a otro agente y pagarle al momento (x402).
+    //
+    // Esto es lo que permite que un agente contrate a otro sin humano de por
+    // medio. A diferencia del escrow, aquí no hay tarea, ni plazo, ni disputa:
+    // se paga y se responde en la misma llamada. Por eso vale para consultas de
+    // céntimos y NO vale para un encargo serio.
+    // -------------------------------------------------------------------------
+    /**
+     * Pregunta el precio de un agente sin pagar nada.
+     *
+     * Es gratis y no compromete: puedes cotizar a varios candidatos y decidir.
+     */
+    async quoteAgent(agent, prompt, options = {}) {
+        const endpoint = await this.x402Endpoint(agent, options);
+        return quoteAsk(endpoint, prompt, { payer: this.account?.address, ...options });
+    }
+    /**
+     * Paga a un agente concreto por una consulta y devuelve su respuesta.
+     *
+     * `maxSpend` es obligatorio: el precio lo pone el otro extremo, así que sin
+     * tope estarías firmando lo que te pidan.
+     */
+    async askAgent(agent, prompt, options) {
+        const wallet = this.wallet();
+        const endpoint = await this.x402Endpoint(agent, options);
+        return payAndAsk(wallet, this.account, endpoint, prompt, {
+            ...options,
+            chainId: chainFor(this.network).id,
+            // Se ata a quién esperamos pagar: si el endpoint estuviera secuestrado y
+            // cotizara a nombre de otro, la firma no llega a producirse.
+            expectedPayee: agent,
+        });
+    }
+    /**
+     * Busca un agente con esa skill, negocia el precio y le paga por la consulta.
+     *
+     * Es la operación que hace de Panal algo más que un directorio: una llamada
+     * a función que cruza una frontera económica.
+     *
+     *   const respuesta = await panal.ask('traducción', 'traduce esto', {
+     *     maxSpend: parseEther('0.01'),
+     *   });
+     *
+     * Cotiza a los candidatos —gratis, con el 402— y se queda con el más barato
+     * que quepa en el presupuesto. Los que no cobran por llamada o no responden
+     * se descartan sin ruido: que un agente esté caído no debe tumbar al que
+     * pregunta.
+     */
+    async ask(skill, prompt, options) {
+        const wallet = this.wallet();
+        const excluded = new Set([...(options.exclude ?? []), this.account.address].map((a) => getAddress(a).toLowerCase()));
+        // El presupuesto real es el menor entre lo que dice el sobre y el tope de
+        // esta llamada: heredar una cadena no puede ampliar lo que autorizaste.
+        const heredado = options.envelope ?? newEnvelope({ budget: options.maxSpend, depth: options.depth });
+        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))
+            .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.`);
+        const quotes = [];
+        const rechazos = [];
+        for (const agent of candidates) {
+            try {
+                const endpoint = await this.x402Endpoint(agent.address, options, agent);
+                const accept = await quoteAsk(endpoint, prompt, {
+                    payer: this.account.address,
+                    ...options,
+                    envelope: heredado,
+                });
+                if (BigInt(accept.amount) <= tope)
+                    quotes.push({ agent, endpoint, accept });
+                else
+                    rechazos.push(`${agent.metadata.name || agent.address}: pide ${accept.amount}, por encima del tope`);
+            }
+            catch (err) {
+                rechazos.push(`${agent.metadata.name || agent.address}: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        if (!quotes.length) {
+            throw new X402Error(`Ningún agente de "${skill}" pudo cotizar dentro del presupuesto.\n  ${rechazos.join('\n  ')}`);
+        }
+        quotes.sort((a, b) => (BigInt(a.accept.amount) < BigInt(b.accept.amount) ? -1 : 1));
+        const elegido = quotes[0];
+        // Se desciende el sobre ANTES de firmar: aquí es donde se comprueba que
+        // quedan saltos, que hay presupuesto y que no estamos cerrando un ciclo.
+        const siguiente = descend(heredado, this.account.address, BigInt(elegido.accept.amount));
+        const result = await payAndAsk(wallet, this.account, elegido.endpoint, prompt, {
+            ...options,
+            maxSpend: tope,
+            chainId: chainFor(this.network).id,
+            expectedPayee: elegido.agent.address,
+            quote: elegido.accept,
+            envelope: siguiente,
+        });
+        return { ...result, agent: elegido.agent.address };
+    }
+    /**
+     * Dónde escucha el x402 de un agente.
+     *
+     * Se prefiere lo que el propio agente anuncia en su `agent.json`; si no lo
+     * anuncia, se prueba la ruta por convención. Así funciona con los agentes que
+     * ya están desplegados sin obligarles a actualizarse.
+     */
+    async x402Endpoint(agent, options = {}, known) {
+        const info = known ?? (await this.getAgent(agent));
+        const base = info.metadata.botUrl;
+        if (!base)
+            throw new X402Error(`El agente ${agent} no publica endpoint en su metadata.`);
+        try {
+            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;
+                if (anunciado?.url)
+                    return anunciado.url;
+                if (anunciado?.path)
+                    return new URL(anunciado.path, base).toString();
+            }
+        }
+        catch {
+            /* sin tarjeta o ilegible: se cae a la convención */
+        }
+        return new URL('/x402/ask', base).toString();
+    }
     /** Retira lo acreditado en una moneda (patrón pull payment). */
     async withdraw(currency = NATIVE_CURRENCY) {
         const wallet = this.wallet();

package/dist/envelope.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Panal SDK — el sobre que viaja con una llamada entre agentes.
+ *
+ * Cuando un agente puede llamar a otro, y ese a otro, aparecen tres problemas
+ * que no existen en una llamada suelta:
+ *
+ *   1. CICLOS. A llama a B, B a C y C a A. Bucle infinito, y aquí cada vuelta
+ *      cuesta dinero de verdad.
+ *   2. PROFUNDIDAD. Sin tope, una cadena se alarga sola y el que empezó paga
+ *      saltos que nunca autorizó.
+ *   3. PRESUPUESTO. Si A tiene 0.01 para gastar y B subcontrata por 0.05, ¿quién
+ *      lo paga? Sin un límite que viaje con la llamada, nadie sabe cuánto queda.
+ *
+ * El sobre resuelve los tres con cuatro cabeceras que se propagan hop a hop,
+ * como un trace distribuido pero con dinero dentro:
+ *
+ *   X-Panal-Trace:  id de la cadena entera, para poder seguirla en los logs
+ *   X-Panal-Depth:  saltos que QUEDAN. Cada agente lo decrementa al delegar
+ *   X-Panal-Budget: wei disponibles para sub-llamadas, menos lo ya gastado
+ *   X-Panal-Path:   por dónde ha pasado ya, para detectar el ciclo
+ *
+ * Es deliberadamente sin estado: todo va en la petición. Un agente que se
+ * reinicia no pierde la protección, y no hace falta coordinar nada entre ellos.
+ *
+ * Sobre la confianza: un intermediario malicioso podría borrarse del `path` para
+ * provocar un bucle. Puede, pero el bucle lo paga él —cada salto lo abona quien
+ * llama—, así que el incentivo va en contra. El sobre protege de cadenas
+ * accidentales y de agentes mal escritos, que es de lo que hay que protegerse.
+ */
+import type { Address } from 'viem';
+export declare const ENVELOPE_HEADERS: {
+    readonly trace: "x-panal-trace";
+    readonly depth: "x-panal-depth";
+    readonly budget: "x-panal-budget";
+    readonly path: "x-panal-path";
+};
+/** Saltos por defecto si quien empieza la cadena no dice otra cosa. */
+export declare const DEFAULT_DEPTH = 3;
+/** Tope duro: ni aunque lo pidan. Acota el coste máximo de una cadena. */
+export declare const MAX_DEPTH = 8;
+export interface CallEnvelope {
+    /** Identifica la cadena entera. Solo sirve para seguirla en los logs. */
+    trace: string;
+    /** Saltos que quedan. 0 = este agente resuelve solo, sin delegar. */
+    depth: number;
+    /** Unidades mínimas disponibles para sub-llamadas. */
+    budget: bigint;
+    /** Agentes que ya han atendido esta cadena, en orden. */
+    path: Address[];
+}
+export declare class LoopDetected extends Error {
+    readonly me: Address;
+    readonly trace: string;
+    constructor(me: Address, trace: string);
+}
+export declare class DepthExhausted extends Error {
+    readonly trace: string;
+    constructor(trace: string);
+}
+export declare class BudgetExhausted extends Error {
+    readonly available: bigint;
+    readonly needed: bigint;
+    constructor(available: bigint, needed: bigint);
+}
+/** Abre una cadena nueva. Lo llama quien la empieza, no un intermediario. */
+export declare function newEnvelope(params: {
+    budget: bigint;
+    depth?: number;
+    trace?: string;
+}): CallEnvelope;
+/** Las cabeceras a poner en la petición saliente. */
+export declare function envelopeHeaders(env: CallEnvelope): Record<string, string>;
+/**
+ * Lee el sobre de una petición entrante. Devuelve null si no viene ninguno —una
+ * llamada suelta de un humano, por ejemplo—, que es un caso legítimo.
+ *
+ * Nunca lanza: las cabeceras las escribe quien llama, o sea un desconocido, así
+ * que todo se sanea en vez de confiar. Un `depth` de un millón se recorta al
+ * tope y un path descomunal se trunca.
+ */
+export declare function parseEnvelope(headers: Record<string, string | string[] | undefined> | Headers): CallEnvelope | null;
+/**
+ * Comprueba, del lado del SERVIDOR, que se puede atender esta llamada.
+ *
+ * Se llama nada más recibir la petición y antes de trabajar: si es un ciclo,
+ * responder costaría dinero a alguien para nada. El código HTTP correcto para
+ * rechazarla es 508 Loop Detected.
+ */
+export declare function assertCanServe(env: CallEnvelope | null, me: Address): void;
+/**
+ * Prepara el sobre para el SIGUIENTE salto, del lado del CLIENTE.
+ *
+ * Lo llama un agente justo antes de delegar: se añade al path, gasta un salto y
+ * descuenta lo que va a pagar. Lanza si no queda profundidad o presupuesto, así
+ * que el límite se aplica antes de firmar nada.
+ */
+export declare function descend(env: CallEnvelope, me: Address, willSpend: bigint): CallEnvelope;
+/** Cuánto puede gastar este agente en sub-llamadas, según el sobre. */
+export declare function remainingBudget(env: CallEnvelope | null, fallback: bigint): bigint;

package/dist/envelope.js

@@ -0,0 +1,188 @@
+/**
+ * Panal SDK — el sobre que viaja con una llamada entre agentes.
+ *
+ * Cuando un agente puede llamar a otro, y ese a otro, aparecen tres problemas
+ * que no existen en una llamada suelta:
+ *
+ *   1. CICLOS. A llama a B, B a C y C a A. Bucle infinito, y aquí cada vuelta
+ *      cuesta dinero de verdad.
+ *   2. PROFUNDIDAD. Sin tope, una cadena se alarga sola y el que empezó paga
+ *      saltos que nunca autorizó.
+ *   3. PRESUPUESTO. Si A tiene 0.01 para gastar y B subcontrata por 0.05, ¿quién
+ *      lo paga? Sin un límite que viaje con la llamada, nadie sabe cuánto queda.
+ *
+ * El sobre resuelve los tres con cuatro cabeceras que se propagan hop a hop,
+ * como un trace distribuido pero con dinero dentro:
+ *
+ *   X-Panal-Trace:  id de la cadena entera, para poder seguirla en los logs
+ *   X-Panal-Depth:  saltos que QUEDAN. Cada agente lo decrementa al delegar
+ *   X-Panal-Budget: wei disponibles para sub-llamadas, menos lo ya gastado
+ *   X-Panal-Path:   por dónde ha pasado ya, para detectar el ciclo
+ *
+ * Es deliberadamente sin estado: todo va en la petición. Un agente que se
+ * reinicia no pierde la protección, y no hace falta coordinar nada entre ellos.
+ *
+ * Sobre la confianza: un intermediario malicioso podría borrarse del `path` para
+ * provocar un bucle. Puede, pero el bucle lo paga él —cada salto lo abona quien
+ * llama—, así que el incentivo va en contra. El sobre protege de cadenas
+ * accidentales y de agentes mal escritos, que es de lo que hay que protegerse.
+ */
+import { getAddress, isAddress } from 'viem';
+export const ENVELOPE_HEADERS = {
+    trace: 'x-panal-trace',
+    depth: 'x-panal-depth',
+    budget: 'x-panal-budget',
+    path: 'x-panal-path',
+};
+/** Saltos por defecto si quien empieza la cadena no dice otra cosa. */
+export const DEFAULT_DEPTH = 3;
+/** Tope duro: ni aunque lo pidan. Acota el coste máximo de una cadena. */
+export const MAX_DEPTH = 8;
+/** Tope de direcciones en el path, por si llega una cabecera enorme. */
+const MAX_PATH = 16;
+export class LoopDetected extends Error {
+    me;
+    trace;
+    constructor(me, trace) {
+        super(`Ciclo detectado: ${me} ya atendió la cadena ${trace}. Se rechaza para no pagarla dos veces.`);
+        this.me = me;
+        this.trace = trace;
+        this.name = 'LoopDetected';
+    }
+}
+export class DepthExhausted extends Error {
+    trace;
+    constructor(trace) {
+        super(`Sin saltos disponibles en la cadena ${trace}: hay que resolver sin delegar.`);
+        this.trace = trace;
+        this.name = 'DepthExhausted';
+    }
+}
+export class BudgetExhausted extends Error {
+    available;
+    needed;
+    constructor(available, needed) {
+        super(`El presupuesto que queda (${available}) no cubre ${needed}.`);
+        this.available = available;
+        this.needed = needed;
+        this.name = 'BudgetExhausted';
+    }
+}
+/** Abre una cadena nueva. Lo llama quien la empieza, no un intermediario. */
+export function newEnvelope(params) {
+    return {
+        trace: params.trace ?? randomTrace(),
+        depth: clampDepth(params.depth ?? DEFAULT_DEPTH),
+        budget: params.budget < 0n ? 0n : params.budget,
+        path: [],
+    };
+}
+/** Las cabeceras a poner en la petición saliente. */
+export function envelopeHeaders(env) {
+    return {
+        [ENVELOPE_HEADERS.trace]: env.trace,
+        [ENVELOPE_HEADERS.depth]: String(env.depth),
+        [ENVELOPE_HEADERS.budget]: env.budget.toString(),
+        [ENVELOPE_HEADERS.path]: env.path.join(','),
+    };
+}
+/**
+ * Lee el sobre de una petición entrante. Devuelve null si no viene ninguno —una
+ * llamada suelta de un humano, por ejemplo—, que es un caso legítimo.
+ *
+ * Nunca lanza: las cabeceras las escribe quien llama, o sea un desconocido, así
+ * que todo se sanea en vez de confiar. Un `depth` de un millón se recorta al
+ * tope y un path descomunal se trunca.
+ */
+export function parseEnvelope(headers) {
+    const get = (name) => {
+        if (typeof headers.get === 'function')
+            return headers.get(name) ?? undefined;
+        const raw = headers[name];
+        return Array.isArray(raw) ? raw[0] : raw;
+    };
+    const trace = get(ENVELOPE_HEADERS.trace)?.trim();
+    if (!trace)
+        return null;
+    let depth = Number.parseInt(get(ENVELOPE_HEADERS.depth) ?? '', 10);
+    if (!Number.isFinite(depth))
+        depth = 0;
+    let budget = 0n;
+    try {
+        const raw = get(ENVELOPE_HEADERS.budget)?.trim();
+        if (raw)
+            budget = BigInt(raw);
+    }
+    catch {
+        budget = 0n; // ilegible = sin presupuesto, que es el lado seguro
+    }
+    const path = (get(ENVELOPE_HEADERS.path) ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        // `strict: false`: sin esto viem exige checksum y una direccion en
+        // minusculas —perfectamente valida, y lo que manda cualquier otra
+        // implementacion— se descartaria en silencio. El ciclo dejaria de
+        // detectarse justo con los agentes que no son nuestros.
+        .filter((s) => isAddress(s, { strict: false }))
+        .slice(0, MAX_PATH)
+        .map((s) => getAddress(s));
+    return {
+        trace: trace.slice(0, 128),
+        depth: clampDepth(depth),
+        budget: budget < 0n ? 0n : budget,
+        path,
+    };
+}
+/**
+ * Comprueba, del lado del SERVIDOR, que se puede atender esta llamada.
+ *
+ * Se llama nada más recibir la petición y antes de trabajar: si es un ciclo,
+ * responder costaría dinero a alguien para nada. El código HTTP correcto para
+ * rechazarla es 508 Loop Detected.
+ */
+export function assertCanServe(env, me) {
+    if (!env)
+        return; // sin sobre no hay cadena que vigilar
+    const yo = getAddress(me);
+    if (env.path.some((a) => getAddress(a) === yo))
+        throw new LoopDetected(yo, env.trace);
+}
+/**
+ * Prepara el sobre para el SIGUIENTE salto, del lado del CLIENTE.
+ *
+ * Lo llama un agente justo antes de delegar: se añade al path, gasta un salto y
+ * descuenta lo que va a pagar. Lanza si no queda profundidad o presupuesto, así
+ * que el límite se aplica antes de firmar nada.
+ */
+export function descend(env, me, willSpend) {
+    if (env.depth <= 0)
+        throw new DepthExhausted(env.trace);
+    if (willSpend > env.budget)
+        throw new BudgetExhausted(env.budget, willSpend);
+    const yo = getAddress(me);
+    if (env.path.some((a) => getAddress(a) === yo))
+        throw new LoopDetected(yo, env.trace);
+    return {
+        trace: env.trace,
+        depth: env.depth - 1,
+        budget: env.budget - willSpend,
+        path: [...env.path, yo].slice(-MAX_PATH),
+    };
+}
+/** Cuánto puede gastar este agente en sub-llamadas, según el sobre. */
+export function remainingBudget(env, fallback) {
+    if (!env)
+        return fallback;
+    return env.budget < fallback ? env.budget : fallback;
+}
+function clampDepth(depth) {
+    if (!Number.isFinite(depth) || depth < 0)
+        return 0;
+    return Math.min(Math.floor(depth), MAX_DEPTH);
+}
+function randomTrace() {
+    const g = globalThis;
+    if (typeof g.crypto?.randomUUID === 'function')
+        return g.crypto.randomUUID();
+    return `panal-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}

package/dist/index.d.ts

@@ -26,3 +26,11 @@ export type { PanalNetwork, PanalAddresses } from './chains.js';
 export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 export type { Agent, AgentMetadata, Task } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
+export type { AskResult, PayAndAskOptions, PermitDomain, X402Accept, X402Quote } from './x402.js';
+export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';
+export type { SettleDeps, SettleResult, X402Payment, X402ServerAccept, X402ServerQuote, } from './x402-server.js';
+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';

package/dist/index.js

@@ -23,3 +23,11 @@ export { PanalClient, createPanalClient } from './client.js';
 export { monad, monadTestnet, addressesFor, chainFor, MAINNET_ADDRESSES, TESTNET_ADDRESSES, NATIVE_CURRENCY, FEE_BPS, AUTO_RELEASE_SECONDS, DISPUTE_TIMEOUT_SECONDS, } from './chains.js';
 export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
+// x402: pagar a otro agente por una consulta, sin escrow y sin humano.
+export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
+export { assertPublicUrl, fetchLimited, isPrivateIp } from './net.js';
+// x402: la otra mitad, cobrar por llamada. Portada del bot de LexPanal, donde
+// lleva meses cobrando en produccion.
+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';

package/dist/net.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Panal SDK — validación de las URLs de otros agentes.
+ *
+ * El endpoint de un agente sale de su metadata on-chain, así que lo escribe un
+ * desconocido. Cualquiera puede registrarse con
+ * `bot:http://169.254.169.254/latest/meta-data/` y usar tu agente para leer las
+ * credenciales de la máquina donde corre. Por eso toda URL ajena pasa por aquí
+ * antes de que se le pida nada.
+ *
+ * Funciona en Node y en el navegador. En Node resuelve el DNS para cazar un
+ * dominio que apunte a una IP interna; en el navegador no hay DNS accesible, se
+ * queda en la validación de la URL, y tampoco importa tanto: ahí el riesgo de
+ * alcanzar la red privada de un servidor no existe.
+ */
+/** ¿Esta IP apunta dentro de una red privada o reservada? */
+export declare function isPrivateIp(ip: string): boolean;
+export interface UrlGuardOptions {
+    /**
+     * Permitir http:// y direcciones privadas. SOLO para desarrollo local: la
+     * petición lleva una firma tuya, y en claro la lee cualquiera por el camino.
+     */
+    allowInsecure?: boolean;
+}
+/**
+ * Devuelve la URL si es segura de visitar, o lanza explicando por qué no.
+ *
+ * Queda una ventana de DNS rebinding —se resuelve aquí y `fetch` vuelve a
+ * resolver por su cuenta—. Cerrarla del todo exige un agente HTTP a medida; el
+ * riesgo residual es aceptable porque la respuesta nunca se ejecuta.
+ */
+export declare function assertPublicUrl(raw: string, options?: UrlGuardOptions): Promise<URL>;
+/**
+ * `fetch` con tope de tamaño y de tiempo. La respuesta viene de un servidor
+ * ajeno: sin tope, uno hostil se lleva por delante el proceso.
+ */
+export declare function fetchLimited(url: URL | string, init?: RequestInit & {
+    maxBytes?: number;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    headers: Headers;
+    text: string;
+}>;