@panal/sdk 0.26.0 → 0.27.0

package/README.md

@@ -208,6 +208,14 @@ El nombre y los decimales salen de la lista, nunca de lo que diga la cotización
 
 `panal.ask(skill, pregunta, { maxSpend, asset })` hace lo mismo sin elegir agente: cotiza a los que tienen esa skill y paga al más barato que quepa en el tope, comparando solo a los que cobran en `asset` ($PANAL si no se indica).
 
+**Con archivos.** `panal.askAgent(agente, pregunta, { maxSpend, files })` y `panal.ask(…, { files })` mandan hasta 5 archivos de 25 MB (`{ name, bytes, mime }`) y devuelven en `files` los que conteste el agente, ya bajados, comprobados contra su hash y abiertos:
+
+- Solo se mandan a un agente cuya cotización diga que los acepta (`accept.files`); `ask` elige solo entre esos. Si no, no se firma nada.
+- Los bytes no viajan en la pregunta: se dejan en el buzón de Panal a nombre del agente —cifrados para él si publicó su clave— y en la pregunta va su lista con el hash de cada uno. Solo pueden bajarlos el destinatario y quien los dejó.
+- Por piezas: `uploadFilesFor(para, archivos)` y `receiveFiles(lista)` en el cliente, o `uploadConsultaFile` / `downloadConsultaFile` / `parseConsultaFiles` sueltas. Del lado que cobra, `buildQuote` y `buildNativeQuote` aceptan `files: CONSULTA_FILES_CAPABILITY` para anunciarlo.
+
+Si el agente que te contesta subcontrató a otros, `r.subcontracts` dice a quién, para qué y cuánto pagó (ver `parseSubcontractsManifest` para leerlo de una entrega).
+
 **Cobrar es la otra mitad**, y la plantilla de [`create-panal-agent`](../create-agent) ya la trae montada en `POST /x402/ask`. Por piezas:
 
 - **Con `permit`:** `buildQuote` hace la cotización. `readPermitDomain` lee el dominio de firma del token y lo comprueba contra su `DOMAIN_SEPARATOR` (el de USDC es la versión 2, no la 1). `parseX402Header` lee el pago y `verifyAndSettle` lo verifica y cobra en la cadena.

package/dist/client.d.ts

@@ -19,6 +19,7 @@ import type { Account, Address, Hex, PublicClient, WalletClient } from 'viem';
 import { type AttachedFile, type HashedFile } from './files.js';
 import { type Acceso, type ClaveDeCifrado } from './cifrado.js';
 import { type AskResult, type X402Accept } from './x402.js';
+import { type OutgoingFile, type ReceivedFile } from './consultas.js';
 import { type CallEnvelope } from './envelope.js';
 import { type PanalAddresses, type PanalNetwork } from './chains.js';
 import { type OpcionesPrecios, type Precios } from './precios.js';
@@ -509,7 +510,27 @@ export declare class PanalClient {
          * heredaba ni presupuesto ni camino, y el ciclo dejaba de detectarse.
          */
         envelope?: CallEnvelope;
+        /**
+         * Archivos para el agente (una foto, un audio, un PDF…): como mucho 5 de
+         * 25 MB. Se dejan en el buzón a su nombre —cifrados si publicó clave— y
+         * en la pregunta solo va su lista. Solo si su cotización dice que los acepta.
+         */
+        files?: OutgoingFile[];
     }): Promise<AskResult>;
+    /** Lanza si la cotización no admite estos archivos: sin firmar ni subir nada. */
+    private comprobarQueAceptaArchivos;
+    /**
+     * Deja archivos en el buzón para `para`. Si publicó clave, cifrados para él
+     * y con un nombre opaco: el buzón no ve ni el contenido ni cómo se llaman, y
+     * el nombre real viaja solo en la lista que recibe el agente.
+     */
+    uploadFilesFor(para: Address, archivos: OutgoingFile[]): Promise<HashedFile[]>;
+    /**
+     * Los archivos que alguien dejó en el buzón para esta cuenta (la respuesta
+     * de un agente, o la pregunta de otro): bajados, comprobados contra su hash
+     * y abiertos si iban cifrados.
+     */
+    receiveFiles(manifest: HashedFile[]): Promise<ReceivedFile[]>;
     /**
      * Busca un agente con esa skill, negocia el precio y le paga por la consulta.
      *
@@ -563,6 +584,8 @@ export declare class PanalClient {
          * y un tope en una moneda no dice nada de otra.
          */
         asset?: Address;
+        /** Archivos para el agente que responda. Ver `askAgent`: solo se elige entre los que los aceptan. */
+        files?: OutgoingFile[];
     }): Promise<AskResult & {
         agent: Address;
         skill: string;

package/dist/client.js

@@ -22,6 +22,7 @@ import { assertPublicUrl, fetchBytesLimited, fetchLimited, rutaDeAgente, sinBarr
 import { MAX_FILE_BYTES, appendAttachmentsManifest, attachmentFrom, parseAttachmentsManifest, parseFilesManifest, sanitizeFileName, verifyFileBytes, } from './files.js';
 import { accesoSignMessage, cifrarArchivo, cifrarTexto, claveDesdeFirma, comprobarClavePublicada, concederAcceso, descifrarArchivo, descifrarTexto, esArchivoCifrado, esTextoCifrado, mensajeParaDerivarClave, mensajeParaPublicarClave, nombreEnBuzon, puedeAbrir, } from './cifrado.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
+import { MAX_CONSULTA_FILES, downloadConsultaFile, uploadConsultaFile, } from './consultas.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
 import { leerPrecios, valorDeVenta } from './precios.js';
@@ -1193,13 +1194,82 @@ export class PanalClient {
     async askAgent(agent, prompt, options) {
         const wallet = this.wallet();
         const endpoint = await this.x402Endpoint(agent, options);
-        return payAndAsk(wallet, this.account, endpoint, prompt, {
+        const archivos = options.files ?? [];
+        let quote = options.quote;
+        let manifiesto = [];
+        if (archivos.length) {
+            // Se cotiza ANTES de subir nada: si no acepta archivos, no se deja ni uno.
+            quote ??= await quoteAsk(endpoint, prompt, { payer: this.account.address, ...options });
+            this.comprobarQueAceptaArchivos(quote, archivos);
+            manifiesto = await this.uploadFilesFor(agent, archivos);
+        }
+        const result = await payAndAsk(wallet, this.account, endpoint, prompt, {
             ...options,
+            ...(quote ? { quote } : {}),
+            files: manifiesto,
             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,
         });
+        return { ...result, files: await this.receiveFiles(result.fileManifest) };
+    }
+    /** Lanza si la cotización no admite estos archivos: sin firmar ni subir nada. */
+    comprobarQueAceptaArchivos(accept, archivos) {
+        if (archivos.length > MAX_CONSULTA_FILES) {
+            throw new X402Error(`Como mucho ${MAX_CONSULTA_FILES} archivos por pregunta, y mandas ${archivos.length}.`);
+        }
+        if (!accept.files)
+            throw new X402Error('Este agente no acepta archivos con la pregunta.');
+        if (archivos.length > accept.files.max) {
+            throw new X402Error(`Este agente acepta ${accept.files.max} archivo(s) por pregunta y mandas ${archivos.length}.`);
+        }
+        const grande = archivos.find((f) => f.bytes.byteLength > accept.files.maxBytes || f.bytes.byteLength > MAX_FILE_BYTES);
+        if (grande)
+            throw new X402Error(`"${grande.name}" pasa del tamaño que acepta este agente.`);
+    }
+    /**
+     * Deja archivos en el buzón para `para`. Si publicó clave, cifrados para él
+     * y con un nombre opaco: el buzón no ve ni el contenido ni cómo se llaman, y
+     * el nombre real viaja solo en la lista que recibe el agente.
+     */
+    async uploadFilesFor(para, archivos) {
+        const wallet = this.wallet();
+        const yo = this.account.address;
+        const suClave = await this.getPublicKey(para);
+        const sign = (message) => wallet.signMessage({ account: this.account, message });
+        const out = [];
+        for (const f of archivos) {
+            const bytes = suClave ? new Uint8Array(cifrarArchivo(f.bytes, [{ cuenta: getAddress(para), clave: suClave }])) : f.bytes;
+            const subido = await uploadConsultaFile({
+                buzonUrl: this.buzonUrl,
+                para,
+                de: yo,
+                file: { name: suClave ? nombreEnBuzon(keccak256(bytes)) : f.name, bytes, ...(suClave ? {} : f.mime ? { mime: f.mime } : {}) },
+                sign,
+            });
+            out.push({ ...subido, name: sanitizeFileName(f.name), ...(f.mime ? { mime: f.mime } : {}) });
+        }
+        return out;
+    }
+    /**
+     * Los archivos que alguien dejó en el buzón para esta cuenta (la respuesta
+     * de un agente, o la pregunta de otro): bajados, comprobados contra su hash
+     * y abiertos si iban cifrados.
+     */
+    async receiveFiles(manifest) {
+        if (!manifest.length)
+            return [];
+        const wallet = this.wallet();
+        const yo = this.account.address;
+        const sign = (message) => wallet.signMessage({ account: this.account, message });
+        const out = [];
+        for (const f of manifest) {
+            const crudo = await downloadConsultaFile({ buzonUrl: this.buzonUrl, para: yo, lector: yo, file: f, sign });
+            const bytes = await this.decryptFile(crudo);
+            out.push({ name: f.name, size: bytes.byteLength, bytes, ...(f.mime ? { mime: f.mime } : {}) });
+        }
+        return out;
     }
     /**
      * Busca un agente con esa skill, negocia el precio y le paga por la consulta.
@@ -1218,6 +1288,7 @@ export class PanalClient {
      */
     async ask(skill, prompt, options) {
         const wallet = this.wallet();
+        const archivos = options.files ?? [];
         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.
@@ -1273,6 +1344,8 @@ export class PanalClient {
                     ...options,
                     envelope: heredado,
                 });
+                if (archivos.length)
+                    this.comprobarQueAceptaArchivos(accept, archivos);
                 if (getAddress(accept.asset) !== moneda) {
                     rechazos.push(`${agent.metadata.name || agent.address}: cobra en ${accept.asset}, no en ${moneda}`);
                 }
@@ -1293,8 +1366,11 @@ export class PanalClient {
         // 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));
+        // Los archivos se suben SOLO para el elegido, y ya sabiendo que los acepta.
+        const manifiesto = archivos.length ? await this.uploadFilesFor(elegido.agent.address, archivos) : [];
         const result = await payAndAsk(wallet, this.account, elegido.endpoint, prompt, {
             ...options,
+            files: manifiesto,
             maxSpend: tope,
             chainId: chainFor(this.network).id,
             expectedPayee: elegido.agent.address,
@@ -1305,7 +1381,12 @@ export class PanalClient {
         // `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 };
+        return {
+            ...result,
+            files: await this.receiveFiles(result.fileManifest),
+            agent: elegido.agent.address,
+            skill: usada,
+        };
     }
     /**
      * Dónde escucha el x402 de un agente.

package/dist/consultas.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Panal SDK — archivos en una pregunta pagada (x402) entre agentes.
+ *
+ * Una pregunta x402 es texto: 2.000 caracteres a la ida y una respuesta a la
+ * vuelta. Para pedirle a otro agente que lea una foto, transcriba un audio o
+ * resuma un PDF hacía falta poder mandarle el archivo, y que él pudiera
+ * devolver los suyos.
+ *
+ * Los bytes NO viajan en la pregunta. Van al buzón de Panal, a nombre de quien
+ * tiene que leerlos, y en la pregunta solo va la lista con su hash:
+ *
+ *     POST /x402/ask   { "prompt": "…", "files": [{ name, size, hash, mime }] }
+ *
+ * Quien recibe la lista baja cada archivo y comprueba sus bytes contra el hash
+ * antes de hacer nada: lo que le llega es exactamente lo que le anunciaron, y
+ * el buzón no puede cambiarlo por el camino. A la vuelta, igual al revés.
+ *
+ * En el buzón, cada archivo es de dos cuentas y de nadie más: quien lo dejó y
+ * su destinatario. Subirlo pide la firma de quien lo deja (con el destinatario
+ * y el hash dentro); bajarlo, la de una de las dos. Y si el destinatario tiene
+ * clave de cifrado publicada, se cifra para él antes de subirlo: entonces ni el
+ * buzón puede leerlo. Caduca como todo lo del buzón: es un relevo, no un archivo.
+ *
+ * Ningún mensaje lleva gas: son firmas EIP-191 con caducidad dentro.
+ */
+import type { Address, Hex } from 'viem';
+import { type HashedFile } from './files.js';
+/** Cuántos archivos como mucho en una pregunta o en su respuesta. Como los adjuntos de un encargo. */
+export declare const MAX_CONSULTA_FILES = 5;
+/** Lo que anuncia un agente en su cotización si acepta archivos: cuántos y de qué tamaño. */
+export interface ConsultaFilesCapability {
+    max: number;
+    maxBytes: number;
+}
+/** La capacidad con la que cotiza un agente con el motor de Panal. */
+export declare const CONSULTA_FILES_CAPABILITY: ConsultaFilesCapability;
+/** Un archivo para mandar: lo que se tiene antes de subirlo. */
+export interface OutgoingFile {
+    name: string;
+    bytes: Uint8Array;
+    mime?: string;
+}
+/** Un archivo recibido, ya comprobado contra su hash y abierto si iba cifrado. */
+export interface ReceivedFile {
+    name: string;
+    mime?: string;
+    size: number;
+    bytes: Uint8Array;
+}
+/** Firma que autoriza a dejar ESTOS bytes para ESTE destinatario. */
+export declare function consultaUploadMessage(para: Address, hash: Hex, expira: number): string;
+/** Firma que autoriza a leer un archivo, a su destinatario o a quien lo dejó. */
+export declare function consultaReadMessage(hash: Hex, expira: number): string;
+/** La ruta de un archivo de consulta en el buzón. */
+export declare function consultaFileUrl(buzonUrl: string, para: Address, hash?: Hex): string;
+/**
+ * Valida la lista de archivos que llega en una pregunta o en una respuesta.
+ * Entrada no fiable: devuelve `null` si algo no cuadra, para rechazarla entera
+ * —una pregunta con un archivo mal anunciado no se cobra a medias—.
+ */
+export declare function parseConsultaFiles(value: unknown, max?: number): HashedFile[] | null;
+/** Firma un mensaje con caducidad: lo que firma la cuenta que sube o que lee. */
+export type SignMessage = (message: string) => Promise<Hex>;
+/**
+ * Deja un archivo en el buzón para `para`. Los bytes se suben tal cual
+ * llegan: si hay que cifrarlos, se cifran ANTES (y el hash es el de lo
+ * cifrado, que es lo que se guarda y se comprueba).
+ */
+export declare function uploadConsultaFile(params: {
+    buzonUrl: string;
+    para: Address;
+    de: Address;
+    file: OutgoingFile;
+    sign: SignMessage;
+}): Promise<HashedFile>;
+/**
+ * Baja un archivo de consulta y comprueba sus bytes contra el hash anunciado.
+ * Lanza si no cuadran: un archivo cambiado no se le pasa a nadie «avisando».
+ */
+export declare function downloadConsultaFile(params: {
+    buzonUrl: string;
+    /** Su destinatario: en qué buzón está. */
+    para: Address;
+    /** Quien lo lee: el destinatario o quien lo dejó. */
+    lector: Address;
+    file: HashedFile;
+    sign: SignMessage;
+}): Promise<Uint8Array>;

package/dist/consultas.js

@@ -0,0 +1,142 @@
+/**
+ * Panal SDK — archivos en una pregunta pagada (x402) entre agentes.
+ *
+ * Una pregunta x402 es texto: 2.000 caracteres a la ida y una respuesta a la
+ * vuelta. Para pedirle a otro agente que lea una foto, transcriba un audio o
+ * resuma un PDF hacía falta poder mandarle el archivo, y que él pudiera
+ * devolver los suyos.
+ *
+ * Los bytes NO viajan en la pregunta. Van al buzón de Panal, a nombre de quien
+ * tiene que leerlos, y en la pregunta solo va la lista con su hash:
+ *
+ *     POST /x402/ask   { "prompt": "…", "files": [{ name, size, hash, mime }] }
+ *
+ * Quien recibe la lista baja cada archivo y comprueba sus bytes contra el hash
+ * antes de hacer nada: lo que le llega es exactamente lo que le anunciaron, y
+ * el buzón no puede cambiarlo por el camino. A la vuelta, igual al revés.
+ *
+ * En el buzón, cada archivo es de dos cuentas y de nadie más: quien lo dejó y
+ * su destinatario. Subirlo pide la firma de quien lo deja (con el destinatario
+ * y el hash dentro); bajarlo, la de una de las dos. Y si el destinatario tiene
+ * clave de cifrado publicada, se cifra para él antes de subirlo: entonces ni el
+ * buzón puede leerlo. Caduca como todo lo del buzón: es un relevo, no un archivo.
+ *
+ * Ningún mensaje lleva gas: son firmas EIP-191 con caducidad dentro.
+ */
+import { getAddress, isAddress, keccak256 } from 'viem';
+import { fetchBytesLimited, fetchLimited, sinBarraFinal } from './net.js';
+import { MAX_FILE_BYTES, sanitizeFileName, verifyFileBytes } from './files.js';
+/** Cuántos archivos como mucho en una pregunta o en su respuesta. Como los adjuntos de un encargo. */
+export const MAX_CONSULTA_FILES = 5;
+/** Lo que dura una firma de subida o de lectura. */
+const VENTANA_FIRMA_S = 10 * 60;
+/** La capacidad con la que cotiza un agente con el motor de Panal. */
+export const CONSULTA_FILES_CAPABILITY = { max: MAX_CONSULTA_FILES, maxBytes: MAX_FILE_BYTES };
+/** Firma que autoriza a dejar ESTOS bytes para ESTE destinatario. */
+export function consultaUploadMessage(para, hash, expira) {
+    return `Panal: dejo un archivo para ${getAddress(para)}\nhash: ${hash.toLowerCase()}\nexpira: ${expira}`;
+}
+/** Firma que autoriza a leer un archivo, a su destinatario o a quien lo dejó. */
+export function consultaReadMessage(hash, expira) {
+    return `Panal: leer el archivo ${hash.toLowerCase()}\nexpira: ${expira}`;
+}
+/** La ruta de un archivo de consulta en el buzón. */
+export function consultaFileUrl(buzonUrl, para, hash) {
+    // `sinBarraFinal` y no una expresión regular: con una URL llena de `/` una
+    // regex como /\/+$/ tarda en cuadrático (CodeQL js/polynomial-redos).
+    const base = `${sinBarraFinal(buzonUrl)}/${getAddress(para)}/consulta-archivo`;
+    return hash ? `${base}/${hash.toLowerCase()}` : base;
+}
+/**
+ * Valida la lista de archivos que llega en una pregunta o en una respuesta.
+ * Entrada no fiable: devuelve `null` si algo no cuadra, para rechazarla entera
+ * —una pregunta con un archivo mal anunciado no se cobra a medias—.
+ */
+export function parseConsultaFiles(value, max = MAX_CONSULTA_FILES) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.length > max)
+        return null;
+    const out = [];
+    for (const v of value) {
+        if (!v || typeof v !== 'object')
+            return null;
+        const { name, size, hash, mime } = v;
+        if (typeof name !== 'string' || typeof hash !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(hash))
+            return null;
+        if (typeof size !== 'number' || !Number.isInteger(size) || size <= 0 || size > MAX_FILE_BYTES)
+            return null;
+        if (mime !== undefined && (typeof mime !== 'string' || mime.length > 120))
+            return null;
+        let limpio = '';
+        try {
+            limpio = sanitizeFileName(name);
+        }
+        catch {
+            return null;
+        }
+        if (!limpio)
+            return null;
+        out.push({ name: limpio, size, hash: hash.toLowerCase(), ...(mime ? { mime } : {}) });
+    }
+    return out;
+}
+/**
+ * Deja un archivo en el buzón para `para`. Los bytes se suben tal cual
+ * llegan: si hay que cifrarlos, se cifran ANTES (y el hash es el de lo
+ * cifrado, que es lo que se guarda y se comprueba).
+ */
+export async function uploadConsultaFile(params) {
+    const { file } = params;
+    if (file.bytes.byteLength === 0)
+        throw new Error(`"${file.name}" está vacío.`);
+    if (file.bytes.byteLength > MAX_FILE_BYTES) {
+        throw new Error(`"${file.name}" pasa de ${Math.round(MAX_FILE_BYTES / 1024 / 1024)} MB.`);
+    }
+    const name = sanitizeFileName(file.name);
+    if (!name)
+        throw new Error('El archivo no tiene un nombre válido.');
+    const hash = keccak256(file.bytes);
+    const expira = Math.floor(Date.now() / 1000) + VENTANA_FIRMA_S;
+    const signature = await params.sign(consultaUploadMessage(params.para, hash, expira));
+    const { status, text } = await fetchLimited(consultaFileUrl(params.buzonUrl, params.para), {
+        method: 'POST',
+        headers: {
+            'content-type': file.mime || 'application/octet-stream',
+            'x-panal-address': getAddress(params.de),
+            'x-panal-signature': signature,
+            'x-panal-expira': String(expira),
+            'x-panal-filename': encodeURIComponent(name),
+        },
+        body: file.bytes,
+        timeoutMs: 120_000,
+        maxBytes: 10_000,
+    });
+    if (status !== 200)
+        throw new Error(`El buzón no aceptó "${name}" (${status}: ${text.slice(0, 160)}).`);
+    return { name, size: file.bytes.byteLength, hash, ...(file.mime ? { mime: file.mime } : {}) };
+}
+/**
+ * Baja un archivo de consulta y comprueba sus bytes contra el hash anunciado.
+ * Lanza si no cuadran: un archivo cambiado no se le pasa a nadie «avisando».
+ */
+export async function downloadConsultaFile(params) {
+    const { file } = params;
+    if (!isAddress(params.para) || !isAddress(params.lector))
+        throw new Error('Dirección no válida.');
+    const expira = Math.floor(Date.now() / 1000) + VENTANA_FIRMA_S;
+    const signature = await params.sign(consultaReadMessage(file.hash, expira));
+    const { status, bytes } = await fetchBytesLimited(consultaFileUrl(params.buzonUrl, params.para, file.hash), {
+        headers: {
+            'x-panal-address': getAddress(params.lector),
+            'x-panal-signature': signature,
+            'x-panal-expira': String(expira),
+        },
+        timeoutMs: 120_000,
+        maxBytes: Math.min(MAX_FILE_BYTES, file.size) + 1024,
+    });
+    if (status !== 200)
+        throw new Error(`El buzón no dio "${file.name}" (${status}).`);
+    verifyFileBytes(file, bytes);
+    return bytes;
+}

package/dist/files.d.ts

@@ -92,6 +92,16 @@ export declare function sanitizeFileName(name: string): string;
 export declare function buildFilesManifest(files: DeliveredFile[]): string;
 /** El texto de la entrega con el manifiesto pegado al final. */
 export declare function appendFilesManifest(text: string, files: DeliveredFile[]): string;
+/**
+ * Lee los bloques `clave: valor` que van bajo una cabecera dada.
+ *
+ * Lo comparten el manifiesto de entrega y el de adjuntos: los dos se anclan en
+ * la cadena y los dos tienen que leerse igual en todas partes. Un bloque
+ * termina en la primera línea vacía o que ya no es `clave: valor`, y eso basta
+ * para que dos manifiestos pegados no se contaminen: ninguna cabecera lleva
+ * dos puntos.
+ */
+export declare function parseBlocks(text: string, tag: string): Record<string, string>[];
 /**
  * Lee los archivos anunciados en el texto de una entrega.
  *
@@ -101,10 +111,11 @@ export declare function appendFilesManifest(text: string, files: DeliveredFile[]
  */
 export declare function parseFilesManifest(text: string): DeliveredFile[];
 /**
- * El texto de la entrega sin los bloques del manifiesto.
+ * El texto de la entrega sin los bloques de Panal: archivos, adjuntos y
+ * subcontrataciones.
  *
- * Para enseñárselo a una persona: el manifiesto es para la máquina, y en un
- * chat de Telegram no aporta más que ruido.
+ * Para enseñárselo a una persona: los bloques son para la máquina, y en un
+ * chat de Telegram no aportan más que ruido. Lo que dicen se enseña aparte.
  */
 export declare function stripFilesManifest(text: string): string;
 /** Comprueba unos bytes contra lo que el manifiesto prometía. Lanza si no cuadra. */

package/dist/files.js

@@ -111,7 +111,7 @@ export function appendFilesManifest(text, files) {
  * para que dos manifiestos pegados no se contaminen: ninguna cabecera lleva
  * dos puntos.
  */
-function parseBloques(text, tag) {
+export function parseBlocks(text, tag) {
     const out = [];
     const lineas = text.split(/\r?\n/);
     for (let i = 0; i < lineas.length; i++) {
@@ -161,7 +161,7 @@ function parseComun(campos) {
  */
 export function parseFilesManifest(text) {
     const out = [];
-    for (const campos of parseBloques(text, FILES_BLOCK)) {
+    for (const campos of parseBlocks(text, FILES_BLOCK)) {
         const comun = parseComun(campos);
         if (!comun)
             continue;
@@ -175,17 +175,24 @@ export function parseFilesManifest(text) {
     return out;
 }
 /**
- * El texto de la entrega sin los bloques del manifiesto.
+ * Cualquier cabecera de bloque de Panal: `[panal-files/1]`, `[panal-attach/1]`,
+ * `[panal-subcontracts/1]` y las que vengan. Se reconocen por la forma para que
+ * una versión nueva de un bloque no le salga a nadie como texto de la entrega.
+ */
+const CABECERA_DE_BLOQUE = /^\[panal-[a-z]+\/\d+\]$/;
+/**
+ * El texto de la entrega sin los bloques de Panal: archivos, adjuntos y
+ * subcontrataciones.
  *
- * Para enseñárselo a una persona: el manifiesto es para la máquina, y en un
- * chat de Telegram no aporta más que ruido.
+ * Para enseñárselo a una persona: los bloques son para la máquina, y en un
+ * chat de Telegram no aportan más que ruido. Lo que dicen se enseña aparte.
  */
 export function stripFilesManifest(text) {
     const lineas = text.split(/\r?\n/);
     const fuera = [];
     let dentro = false;
     for (const linea of lineas) {
-        if (linea.trim() === FILES_BLOCK || linea.trim() === ATTACH_BLOCK) {
+        if (CABECERA_DE_BLOQUE.test(linea.trim())) {
             dentro = true;
             continue;
         }
@@ -332,7 +339,7 @@ export function appendAttachmentsManifest(brief, files) {
 /** Lee los adjuntos anunciados en un encargo. No lanza por un bloque roto. */
 export function parseAttachmentsManifest(brief) {
     const out = [];
-    for (const campos of parseBloques(brief, ATTACH_BLOCK)) {
+    for (const campos of parseBlocks(brief, ATTACH_BLOCK)) {
         const comun = parseComun(campos);
         if (comun)
             out.push(comun);

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, normalizeAgentLink,
 export type { Agent, AgentLinkKey, AgentLinks, AgentMetadata, Task } from './types.js';
 export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
+export { MAX_SUBCONTRACTS, SUBCONTRACTS_BLOCK, appendSubcontractsManifest, buildSubcontractsManifest, parseSubcontractsManifest, subcontractsFromJson, subcontractsOfAnswer, subcontractsToJson, type SubcontractJson, type SubcontractRecord, } from './subcontratos.js';
+export { CONSULTA_FILES_CAPABILITY, MAX_CONSULTA_FILES, consultaFileUrl, consultaReadMessage, consultaUploadMessage, downloadConsultaFile, parseConsultaFiles, uploadConsultaFile, type ConsultaFilesCapability, type OutgoingFile, type ReceivedFile, type SignMessage, } from './consultas.js';
 export { X402_NATIVE, formatX402Amount, networkOfChain, parseX402Amount, x402Currencies, x402Currency, x402CurrencyByName, } from './currencies.js';
 export type { X402Currency, X402Scheme } from './currencies.js';
 export type { AskResult, PayAndAskOptions, PermitDomain, X402Accept, X402Quote } from './x402.js';

package/dist/index.js

@@ -25,6 +25,8 @@ export { TaskStatus, TASK_STATUS_LABEL, formatAgentMetadata, normalizeAgentLink,
 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 { MAX_SUBCONTRACTS, SUBCONTRACTS_BLOCK, appendSubcontractsManifest, buildSubcontractsManifest, parseSubcontractsManifest, subcontractsFromJson, subcontractsOfAnswer, subcontractsToJson, } from './subcontratos.js';
+export { CONSULTA_FILES_CAPABILITY, MAX_CONSULTA_FILES, consultaFileUrl, consultaReadMessage, consultaUploadMessage, downloadConsultaFile, parseConsultaFiles, uploadConsultaFile, } from './consultas.js';
 export { X402_NATIVE, formatX402Amount, networkOfChain, parseX402Amount, x402Currencies, x402Currency, x402CurrencyByName, } from './currencies.js';
 export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
 // Archivos: entregar un PDF o un vídeo anclando SU hash, no el del enlace.

package/dist/subcontratos.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Panal SDK — a quién pagó un agente para hacer tu encargo, dicho en la entrega.
+ *
+ * Un agente puede subcontratar: preguntarle a otro, pagándole de lo que cobró,
+ * lo que no sabe hacer. Hasta ahora eso solo quedaba en los logs de quien lo
+ * hacía, y el cliente recibía un trabajo en el que había participado gente que
+ * no conocía. Si además le manda sus archivos a ese otro, deja de ser un
+ * detalle interno: es su información en manos de un tercero.
+ *
+ * Por eso va DENTRO del texto que se entrega, como el manifiesto de archivos:
+ *
+ *     Aquí tienes la revisión.
+ *
+ *     [panal-subcontracts/1]
+ *     agent: 0x8e9c…
+ *     skill: tests
+ *     amount: 150000000000000000
+ *     currency: $PANAL
+ *     asset: 0x2E2e…7777
+ *     decimals: 18
+ *     tx: 0x51ab…
+ *
+ * Ese texto es el que se ancla en la cadena, así que el apartado no se puede
+ * quitar ni cambiar después de entregar, y cada pago se comprueba en el
+ * explorador con su `tx`. Lo escribe el motor del agente, no su autor: ningún
+ * `handleTask` puede olvidarse de decirlo.
+ *
+ * `via` es para la cadena entera. Si el agente que contrataste pagó a B y B, a
+ * su vez, pagó a C, la entrega lleva a B y a C, y C lleva `via: B`. El dinero
+ * de C salió de B, no de ti, pero tu información pasó por los dos.
+ *
+ * Por la red, en la respuesta de una pregunta x402, la misma lista va en JSON
+ * (`subcontracts`): así el que pregunta sabe a quién subcontrató el que le
+ * respondió, sin leer su texto.
+ */
+import type { Address, Hex } from 'viem';
+/** Cabecera del bloque. Lleva versión porque el formato se ancla en la cadena. */
+export declare const SUBCONTRACTS_BLOCK = "[panal-subcontracts/1]";
+/**
+ * Cuántas subcontrataciones se cuentan como mucho en una entrega.
+ *
+ * Una cadena tiene un tope de saltos y cada agente un presupuesto, así que en
+ * la práctica son pocas; el tope es para que una respuesta hostil no llene una
+ * entrega con miles de líneas.
+ */
+export declare const MAX_SUBCONTRACTS = 32;
+/** Una subcontratación: a quién, para qué y cuánto se le pagó. */
+export interface SubcontractRecord {
+    /** El agente que cobró y respondió. */
+    agent: Address;
+    /** Para qué: la skill con la que se le buscó. */
+    skill: string;
+    /** Lo pagado, en unidades mínimas de `currency`. */
+    amount: bigint;
+    /** En qué se pagó. */
+    currency: {
+        symbol: string;
+        address: Address;
+        decimals: number;
+    };
+    /** La transacción del cobro, si el agente la reportó. */
+    txHash?: Hex;
+    /** Si no lo contrató el agente del encargo sino uno de sus subcontratados: cuál. */
+    via?: Address;
+    /** Cuántos archivos se le mandaron con la pregunta: tu información pasó por él. */
+    files?: number;
+}
+/**
+ * Construye el bloque. Orden de claves fijo y `\n`: se ancla en la cadena, y
+ * las mismas subcontrataciones tienen que dar exactamente los mismos bytes.
+ */
+export declare function buildSubcontractsManifest(list: SubcontractRecord[]): string;
+/** El texto de la entrega con las subcontrataciones al final. Sin ninguna, igual que estaba. */
+export declare function appendSubcontractsManifest(text: string, list: SubcontractRecord[]): string;
+/**
+ * Lee las subcontrataciones anunciadas en una entrega.
+ *
+ * Nunca lanza: un bloque mal formado se salta y los demás se leen. Que una
+ * línea rota impida leer la entrega sería peor que no enseñar esa línea.
+ */
+export declare function parseSubcontractsManifest(text: string): SubcontractRecord[];
+/** La forma JSON, para la respuesta de una pregunta x402. */
+export interface SubcontractJson {
+    agent: string;
+    skill: string;
+    amount: string;
+    currency: string;
+    asset: string;
+    decimals: number;
+    tx?: string;
+    via?: string;
+    files?: number;
+}
+export declare function subcontractsToJson(list: SubcontractRecord[]): SubcontractJson[];
+/**
+ * Lee la lista que manda otro agente en su respuesta. Es entrada no fiable:
+ * se valida entrada a entrada y lo que no cuadra se descarta, nunca se lanza.
+ */
+export declare function subcontractsFromJson(value: unknown): SubcontractRecord[];
+/**
+ * Lo que apunta un agente al subcontratar: la subcontratación directa y, detrás,
+ * las que hizo a su vez el que respondió, con `via` para saber de dónde vienen.
+ */
+export declare function subcontractsOfAnswer(direct: Omit<SubcontractRecord, 'via'>, nested?: SubcontractRecord[]): SubcontractRecord[];

package/dist/subcontratos.js

@@ -0,0 +1,171 @@
+/**
+ * Panal SDK — a quién pagó un agente para hacer tu encargo, dicho en la entrega.
+ *
+ * Un agente puede subcontratar: preguntarle a otro, pagándole de lo que cobró,
+ * lo que no sabe hacer. Hasta ahora eso solo quedaba en los logs de quien lo
+ * hacía, y el cliente recibía un trabajo en el que había participado gente que
+ * no conocía. Si además le manda sus archivos a ese otro, deja de ser un
+ * detalle interno: es su información en manos de un tercero.
+ *
+ * Por eso va DENTRO del texto que se entrega, como el manifiesto de archivos:
+ *
+ *     Aquí tienes la revisión.
+ *
+ *     [panal-subcontracts/1]
+ *     agent: 0x8e9c…
+ *     skill: tests
+ *     amount: 150000000000000000
+ *     currency: $PANAL
+ *     asset: 0x2E2e…7777
+ *     decimals: 18
+ *     tx: 0x51ab…
+ *
+ * Ese texto es el que se ancla en la cadena, así que el apartado no se puede
+ * quitar ni cambiar después de entregar, y cada pago se comprueba en el
+ * explorador con su `tx`. Lo escribe el motor del agente, no su autor: ningún
+ * `handleTask` puede olvidarse de decirlo.
+ *
+ * `via` es para la cadena entera. Si el agente que contrataste pagó a B y B, a
+ * su vez, pagó a C, la entrega lleva a B y a C, y C lleva `via: B`. El dinero
+ * de C salió de B, no de ti, pero tu información pasó por los dos.
+ *
+ * Por la red, en la respuesta de una pregunta x402, la misma lista va en JSON
+ * (`subcontracts`): así el que pregunta sabe a quién subcontrató el que le
+ * respondió, sin leer su texto.
+ */
+import { getAddress, isAddress } from 'viem';
+import { parseBlocks } from './files.js';
+/** Cabecera del bloque. Lleva versión porque el formato se ancla en la cadena. */
+export const SUBCONTRACTS_BLOCK = '[panal-subcontracts/1]';
+/**
+ * Cuántas subcontrataciones se cuentan como mucho en una entrega.
+ *
+ * Una cadena tiene un tope de saltos y cada agente un presupuesto, así que en
+ * la práctica son pocas; el tope es para que una respuesta hostil no llene una
+ * entrega con miles de líneas.
+ */
+export const MAX_SUBCONTRACTS = 32;
+/** Una línea `clave: valor` no puede llevar saltos, y la skill la eligió un modelo. */
+function enUnaLinea(texto, max) {
+    return texto.replace(/[\r\n\u2028\u2029]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+/**
+ * Construye el bloque. Orden de claves fijo y `\n`: se ancla en la cadena, y
+ * las mismas subcontrataciones tienen que dar exactamente los mismos bytes.
+ */
+export function buildSubcontractsManifest(list) {
+    return list
+        .slice(0, MAX_SUBCONTRACTS)
+        .map((s) => {
+        const lineas = [
+            SUBCONTRACTS_BLOCK,
+            `agent: ${getAddress(s.agent)}`,
+            `skill: ${enUnaLinea(s.skill, 64)}`,
+            `amount: ${s.amount.toString()}`,
+            `currency: ${enUnaLinea(s.currency.symbol, 16)}`,
+            `asset: ${getAddress(s.currency.address)}`,
+            `decimals: ${s.currency.decimals}`,
+        ];
+        if (s.txHash)
+            lineas.push(`tx: ${s.txHash.toLowerCase()}`);
+        if (s.via)
+            lineas.push(`via: ${getAddress(s.via)}`);
+        if (s.files)
+            lineas.push(`files: ${s.files}`);
+        return lineas.join('\n');
+    })
+        .join('\n\n');
+}
+/** El texto de la entrega con las subcontrataciones al final. Sin ninguna, igual que estaba. */
+export function appendSubcontractsManifest(text, list) {
+    if (list.length === 0)
+        return text;
+    return `${text.trimEnd()}\n\n${buildSubcontractsManifest(list)}\n`;
+}
+/** Valida una subcontratación venga de donde venga. Lo que no se entiende, se descarta. */
+function validar(c) {
+    const { agent, skill, amount, currency, asset, decimals, tx, via, files } = c;
+    if (typeof agent !== 'string' || !isAddress(agent))
+        return null;
+    if (typeof asset !== 'string' || !isAddress(asset))
+        return null;
+    if (typeof skill !== 'string' || !enUnaLinea(skill, 64))
+        return null;
+    if (typeof currency !== 'string' || !enUnaLinea(currency, 16))
+        return null;
+    const cantidad = typeof amount === 'string' && /^\d{1,78}$/.test(amount) ? BigInt(amount) : null;
+    if (cantidad === null)
+        return null;
+    const dec = typeof decimals === 'number' ? decimals : Number(decimals);
+    if (!Number.isInteger(dec) || dec < 0 || dec > 36)
+        return null;
+    if (tx !== undefined && (typeof tx !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(tx)))
+        return null;
+    if (via !== undefined && (typeof via !== 'string' || !isAddress(via)))
+        return null;
+    // Un recuento raro no tumba la línea: solo se deja de decir.
+    const archivos = files === undefined ? 0 : Number(files);
+    return {
+        agent: getAddress(agent),
+        skill: enUnaLinea(skill, 64),
+        amount: cantidad,
+        currency: { symbol: enUnaLinea(currency, 16), address: getAddress(asset), decimals: dec },
+        ...(tx ? { txHash: tx.toLowerCase() } : {}),
+        ...(via ? { via: getAddress(via) } : {}),
+        ...(Number.isInteger(archivos) && archivos > 0 && archivos <= 1000 ? { files: archivos } : {}),
+    };
+}
+/**
+ * Lee las subcontrataciones anunciadas en una entrega.
+ *
+ * Nunca lanza: un bloque mal formado se salta y los demás se leen. Que una
+ * línea rota impida leer la entrega sería peor que no enseñar esa línea.
+ */
+export function parseSubcontractsManifest(text) {
+    const out = [];
+    for (const campos of parseBlocks(text, SUBCONTRACTS_BLOCK)) {
+        const s = validar(campos);
+        if (s)
+            out.push(s);
+        if (out.length >= MAX_SUBCONTRACTS)
+            break;
+    }
+    return out;
+}
+export function subcontractsToJson(list) {
+    return list.slice(0, MAX_SUBCONTRACTS).map((s) => ({
+        agent: s.agent,
+        skill: s.skill,
+        amount: s.amount.toString(),
+        currency: s.currency.symbol,
+        asset: s.currency.address,
+        decimals: s.currency.decimals,
+        ...(s.txHash ? { tx: s.txHash } : {}),
+        ...(s.via ? { via: s.via } : {}),
+        ...(s.files ? { files: s.files } : {}),
+    }));
+}
+/**
+ * Lee la lista que manda otro agente en su respuesta. Es entrada no fiable:
+ * se valida entrada a entrada y lo que no cuadra se descarta, nunca se lanza.
+ */
+export function subcontractsFromJson(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const v of value.slice(0, MAX_SUBCONTRACTS)) {
+        if (!v || typeof v !== 'object')
+            continue;
+        const s = validar(v);
+        if (s)
+            out.push(s);
+    }
+    return out;
+}
+/**
+ * Lo que apunta un agente al subcontratar: la subcontratación directa y, detrás,
+ * las que hizo a su vez el que respondió, con `via` para saber de dónde vienen.
+ */
+export function subcontractsOfAnswer(direct, nested = []) {
+    return [direct, ...nested.map((s) => ({ ...s, via: s.via ?? direct.agent }))].slice(0, MAX_SUBCONTRACTS);
+}

package/dist/x402-server.d.ts

@@ -37,6 +37,7 @@
 import { type Address, type Hex, type PublicClient, type WalletClient } from 'viem';
 import { type PanalNetwork } from './chains.js';
 import type { PermitDomain } from './x402.js';
+import type { ConsultaFilesCapability } from './consultas.js';
 export type { PermitDomain };
 export declare const X402_VERSION = 1;
 export declare const X402_SERVER_SCHEME = "eip2612-permit";
@@ -110,6 +111,8 @@ export interface X402ServerAccept {
     payerNonce?: string;
     /** Dominio EIP-712 con el que firmar, para no obligar al cliente a leerlo. */
     domain: PermitDomain;
+    /** Si se aceptan archivos con la pregunta (ver `consultas.ts`). */
+    files?: ConsultaFilesCapability;
 }
 export interface X402ServerQuote {
     x402Version: typeof X402_VERSION;
@@ -128,6 +131,8 @@ export declare function buildQuote(params: {
     payerNonce?: bigint;
     network?: PanalNetwork;
     nowS?: number;
+    /** Anunciar que se aceptan archivos: con el motor de Panal, `CONSULTA_FILES_CAPABILITY`. */
+    files?: ConsultaFilesCapability;
 }): X402ServerQuote;
 export interface X402Payment {
     scheme: typeof X402_SERVER_SCHEME;
@@ -194,6 +199,8 @@ export interface X402NativeAccept {
     maxTimeoutSeconds: number;
     /** Secreto de esta cotización: se presenta con el pago, nunca va a la cadena. */
     paymentId: Hex;
+    /** Si se aceptan archivos con la pregunta (ver `consultas.ts`). */
+    files?: ConsultaFilesCapability;
 }
 /**
  * La cotización de una pregunta en MON.
@@ -212,6 +219,8 @@ export declare function buildNativeQuote(params: {
     payer?: Address | null;
     network?: PanalNetwork;
     nowS?: number;
+    /** Anunciar que se aceptan archivos: con el motor de Panal, `CONSULTA_FILES_CAPABILITY`. */
+    files?: ConsultaFilesCapability;
 }): {
     x402Version: typeof X402_VERSION;
     accepts: X402NativeAccept[];

package/dist/x402-server.js

@@ -172,6 +172,7 @@ export function buildQuote(params) {
                 maxTimeoutSeconds: 120,
                 payerNonce: params.payerNonce?.toString(),
                 domain: params.domain,
+                ...(params.files ? { files: params.files } : {}),
             },
         ],
         hint: 'Sign an EIP-2612 permit with the domain and fields of accepts[0] (spender = payTo, ' +
@@ -477,6 +478,7 @@ export function buildNativeQuote(params) {
                 deadline,
                 maxTimeoutSeconds: 120,
                 paymentId: nativePaymentId(params.secret, { payer, payTo: params.payTo, amount, deadline, resource: params.resource }),
+                ...(params.files ? { files: params.files } : {}),
             },
         ],
         hint: 'Send EXACTLY `amount` MON to `payTo` before `deadline`, then repeat the request with the header ' +

package/dist/x402.d.ts

@@ -19,6 +19,9 @@ import type { Account, Address, Hex, WalletClient } from 'viem';
 import { type UrlGuardOptions } from './net.js';
 import { type CallEnvelope } from './envelope.js';
 import { type X402Currency } from './currencies.js';
+import { type SubcontractRecord } from './subcontratos.js';
+import { type ConsultaFilesCapability, type ReceivedFile } from './consultas.js';
+import type { HashedFile } from './files.js';
 /** El esquema de las monedas con `permit`. Debe coincidir con el servidor. */
 export declare const X402_SCHEME = "eip2612-permit";
 export interface PermitDomain {
@@ -45,6 +48,12 @@ export interface X402Accept {
     domain?: PermitDomain;
     /** Solo en MON: el código de esta cotización, que se presenta con el pago. */
     paymentId?: Hex;
+    /**
+     * Si el agente acepta archivos con la pregunta, cuántos y de qué tamaño.
+     * Sin esto, no se le mandan: un agente que no los espera los ignoraría y
+     * cobraría igual una respuesta que no los ha mirado. Ver `consultas.ts`.
+     */
+    files?: ConsultaFilesCapability;
 }
 export interface X402Quote {
     x402Version?: number;
@@ -87,6 +96,12 @@ export interface PayAndAskOptions extends UrlGuardOptions {
      * ha gastado su salto. Ver `descend()` en envelope.ts.
      */
     envelope?: CallEnvelope;
+    /**
+     * Archivos que acompañan a la pregunta, YA en el buzón a nombre del agente
+     * (ver `uploadConsultaFile`): aquí solo va su lista. Si la cotización no
+     * dice que el agente los acepta, no se firma nada.
+     */
+    files?: HashedFile[];
 }
 export interface AskResult {
     answer: string;
@@ -99,6 +114,19 @@ export interface AskResult {
     /** Transacción del cobro, si el servidor la reporta. */
     txHash?: Hex;
     endpoint: string;
+    /**
+     * A quién subcontrató, a su vez, el agente que respondió para contestarte
+     * (vacío si no subcontrató o si su motor no lo dice). Ver `subcontratos.ts`.
+     */
+    subcontracts: SubcontractRecord[];
+    /** Los archivos que devolvió, tal y como los anunció: dejados en el buzón a tu nombre. */
+    fileManifest: HashedFile[];
+    /**
+     * Esos archivos ya bajados, comprobados y abiertos. Los rellena el cliente
+     * (`ask`, `askAgent`); con `payAndAsk` a pelo va vacío y la lista está en
+     * `fileManifest`, para bajarlos con `downloadConsultaFile`.
+     */
+    files: ReceivedFile[];
 }
 /**
  * Paga una consulta a un endpoint x402 y devuelve la respuesta.

package/dist/x402.js

@@ -20,6 +20,8 @@ import { estimateGas, waitForTransactionReceipt } from 'viem/actions';
 import { assertPublicUrl, fetchLimited } from './net.js';
 import { envelopeHeaders } from './envelope.js';
 import { networkOfChain, x402Currency } from './currencies.js';
+import { subcontractsFromJson } from './subcontratos.js';
+import { parseConsultaFiles } from './consultas.js';
 /** El esquema de las monedas con `permit`. Debe coincidir con el servidor. */
 export const X402_SCHEME = 'eip2612-permit';
 /** El de MON, que no tiene `permit`: se manda una transferencia y se presenta. */
@@ -112,6 +114,19 @@ export async function payAndAsk(wallet, account, endpoint, prompt, options) {
         // atacante creyendo que pagas al agente que elegiste.
         throw new X402Error(`La cotización cobra a ${accept.payTo} y esperabas a ${options.expectedPayee}: no se firma.`);
     }
+    const enviados = options.files ?? [];
+    if (enviados.length) {
+        const puede = accept.files;
+        if (!puede) {
+            throw new X402Error('Este agente no acepta archivos con la pregunta: no se firma.');
+        }
+        if (enviados.length > puede.max) {
+            throw new X402Error(`Este agente acepta ${puede.max} archivo(s) por pregunta y mandas ${enviados.length}.`);
+        }
+        const grande = enviados.find((f) => f.size > puede.maxBytes);
+        if (grande)
+            throw new X402Error(`"${grande.name}" pasa del tamaño que acepta este agente.`);
+    }
     if (options.asset && getAddress(accept.asset) !== getAddress(options.asset)) {
         throw new X402Error(`La cotización pide pagar en ${accept.asset} y esperabas ${options.asset}.`);
     }
@@ -146,7 +161,7 @@ export async function payAndAsk(wallet, account, endpoint, prompt, options) {
             'x-payment': header.value,
             ...(options.envelope ? envelopeHeaders(options.envelope) : {}),
         },
-        body: JSON.stringify({ prompt }),
+        body: JSON.stringify(enviados.length ? { prompt, files: enviados } : { prompt }),
         timeoutMs: options.timeoutMs ?? (accept.maxTimeoutSeconds ?? 120) * 1000,
     });
     // `paid` es como lo devuelve la plantilla de agentes; `payment`, como lo
@@ -181,6 +196,11 @@ export async function payAndAsk(wallet, account, endpoint, prompt, options) {
         payee: getAddress(accept.payTo),
         txHash: body.payment?.txHash ?? body.paid?.txHash ?? header.txHash,
         endpoint: url.toString(),
+        // Entrada de otro agente: se valida entrada a entrada y lo que no cuadra se descarta.
+        subcontracts: subcontractsFromJson(body.subcontracts),
+        // Una lista de archivos mal formada se ignora entera: no hay a medias.
+        fileManifest: parseConsultaFiles(body.files) ?? [],
+        files: [],
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/sdk.test.ts && tsx test/currencies.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/attachments.test.ts && tsx test/llm.test.ts && tsx test/skill.test.ts && tsx test/agent-card.test.ts && tsx test/niveles.test.ts && tsx test/ejemplos.test.ts && tsx test/tablon.test.ts && tsx test/reserva.test.ts && tsx test/precios.test.ts && tsx test/tablon-reglas.test.ts && tsx test/cifrado.test.ts",
+    "test": "tsx test/sdk.test.ts && tsx test/currencies.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/attachments.test.ts && tsx test/llm.test.ts && tsx test/skill.test.ts && tsx test/agent-card.test.ts && tsx test/niveles.test.ts && tsx test/ejemplos.test.ts && tsx test/tablon.test.ts && tsx test/reserva.test.ts && tsx test/precios.test.ts && tsx test/tablon-reglas.test.ts && tsx test/cifrado.test.ts && tsx test/subcontratos.test.ts && tsx test/consultas.test.ts",
     "test:nombres": "tsx test/nombres.test.ts"
   }
 }