@panal/sdk 0.25.0 → 0.27.0

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/idiomas.js

@@ -35,6 +35,7 @@
  * y que hoy son lo único que un francés no puede leer.
  * ───────────────────────────────────────────────────────────────────────────
  */
+import { sinBarraFinal } from './net.js';
 /**
  * Los idiomas del marketplace, en códigos ISO 639-1.
  *
@@ -63,7 +64,7 @@ export function normalizarIdioma(v) {
  * en un código que no existe.
  */
 export function fichaEnIdioma(botUrl, idioma) {
-    const base = `${botUrl.replace(/\/+$/, '')}/agent.json`;
+    const base = `${sinBarraFinal(botUrl)}/agent.json`;
     const lang = normalizarIdioma(idioma);
     return lang ? `${base}?lang=${lang}` : base;
 }

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';
@@ -46,7 +48,7 @@ export { componerNivel, conTextoDeLaFicha, esTokenDeNivel, leerNivelDeSegmento,
 export { esTokenDeTipo, leerTipo, leerTipoDeSegmento, tokenDeTipo } from './tipo.js';
 export type { TipoDeAgente } from './tipo.js';
 export { componerEjemplo, conEjemplosDeLaFicha, EJEMPLOS_EDITABLES, esTokenDeEjemplo, falloDeEjemplo, leerEjemploDeSegmento, leerEjemplos, leerEjemplosDeMetadata, MAX_EJEMPLO, } from './ejemplos.js';
-export { rutaDeAgente } from './net.js';
+export { rutaDeAgente, sinBarraFinal } from './net.js';
 export { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
 export type { EncargoDelTablon } from './tablon.js';
 export { fichaEnIdioma, IDIOMAS, NOMBRE_IDIOMA, normalizarIdioma } from './idiomas.js';
@@ -54,5 +56,6 @@ export type { Idioma } from './idiomas.js';
 export { MERCADO_PANAL, PRECIO_MAX_EDAD_S, PYTH_MONAD, PYTH_MON_USD, enDolares, esFresco, formatearDolares, leerPrecios, valorDeVenta, } from './precios.js';
 export type { FuentePrecio, MonedaConPrecio, OpcionesPrecios, Precio, Precios } from './precios.js';
 export { panalTablonAbi } from './tablon-abi.js';
-export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_ARCHIVOS_TABLON, MAX_BYTES_ARCHIVOS_TABLON, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, entregaConArchivos, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_ARCHIVOS_TABLON, MAX_BYTES_ARCHIVOS_TABLON, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, entregaConArchivos, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonAccesoSignMessage, tablonArchivoSignMessage, tablonDisputaSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
 export type { ArchivoParaSubir, AudienciaTablon, CategoriaTablon, EncargoConReglas, OfertaConReglas, PublicarEnElTablon, SituacionEnElTablon, } from './tablon-reglas.js';
+export { CIFRADO_V1, aBase64, accesoSignMessage, archivosAnunciadosEnSobre, claveDesdeFirma, concederAcceso, cifrarArchivo, cifrarTexto, comprobarClavePublicada, deBase64, descifrarArchivo, descifrarTexto, destinatariosDe, disputaSignMessage, esArchivoCifrado, esTextoCifrado, mensajeParaDerivarClave, mensajeParaPublicarClave, nombreEnBuzon, puedeAbrir, type Acceso, type ArchivoAnunciado, type ClaveDeCifrado, type ClavePublicada, type Destinatario, } from './cifrado.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.
@@ -54,7 +56,7 @@ export { componerEjemplo, conEjemplosDeLaFicha, EJEMPLOS_EDITABLES, esTokenDeEje
 // propio agente y no un servicio de Panal.
 // Unir una ruta con la URL de un agente. Ver por qué en `net.ts`: un agente
 // puede vivir en un subcamino, y `new URL('/x', base)` se lo come.
-export { rutaDeAgente } from './net.js';
+export { rutaDeAgente, sinBarraFinal } from './net.js';
 // El tablón: encargos sin dueño para que los coja un programa. Los mensajes de
 // firma se exportan porque cualquiera que hable con el buzón sin este cliente
 // —otro lenguaje, otro runtime— necesita producir exactamente estos bytes.
@@ -67,4 +69,7 @@ export { MERCADO_PANAL, PRECIO_MAX_EDAD_S, PYTH_MONAD, PYTH_MON_USD, enDolares,
 // el cliente (`…BoardJob`); aquí, el ABI, los tipos y lo que se calcula sin la
 // cadena. Ver tablon-reglas.ts y contracts/BOARD.md.
 export { panalTablonAbi } from './tablon-abi.js';
-export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_ARCHIVOS_TABLON, MAX_BYTES_ARCHIVOS_TABLON, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, entregaConArchivos, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+export { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_ANUNCIO, MAX_ARCHIVOS_TABLON, MAX_BYTES_ARCHIVOS_TABLON, MAX_CATEGORIAS, MAX_TEXTO_ANUNCIO, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, anuncioPara, audienciaAdmite, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, entregaConArchivos, idDeCampana, leerAnuncio, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonAccesoSignMessage, tablonArchivoSignMessage, tablonDisputaSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+// Encargos cifrados de punta a punta: la clave sale de una firma, el sobre se
+// abre solo con la de sus destinatarios, y el buzón guarda lo que no sabe leer.
+export { CIFRADO_V1, aBase64, accesoSignMessage, archivosAnunciadosEnSobre, claveDesdeFirma, concederAcceso, cifrarArchivo, cifrarTexto, comprobarClavePublicada, deBase64, descifrarArchivo, descifrarTexto, destinatariosDe, disputaSignMessage, esArchivoCifrado, esTextoCifrado, mensajeParaDerivarClave, mensajeParaPublicarClave, nombreEnBuzon, puedeAbrir, } from './cifrado.js';

package/dist/net.d.ts

@@ -68,3 +68,12 @@ export declare function fetchLimited(url: URL | string, init?: RequestInit & {
  * rutas se hace en un sitio y no a mano en cada llamada.
  */
 export declare function rutaDeAgente(base: string, ruta: string): string;
+/**
+ * Una URL sin las barras del final.
+ *
+ * Con un bucle y no con `replace(/\/+$/, '')`: esa expresión, sobre un texto
+ * lleno de barras que no acaba en barra, vuelve a probar desde cada una y
+ * tarda un tiempo cuadrático. Y la URL de un agente la escribe él en su
+ * ficha: con unos miles de barras bastaría para colgar a quien la lea.
+ */
+export declare function sinBarraFinal(url: string): string;

package/dist/net.js

@@ -163,5 +163,19 @@ export async function fetchLimited(url, init = {}) {
  * rutas se hace en un sitio y no a mano en cada llamada.
  */
 export function rutaDeAgente(base, ruta) {
-    return `${base.replace(/\/+$/, '')}/${ruta.replace(/^\/+/, '')}`;
+    return `${sinBarraFinal(base)}/${ruta.replace(/^\/+/, '')}`;
+}
+/**
+ * Una URL sin las barras del final.
+ *
+ * Con un bucle y no con `replace(/\/+$/, '')`: esa expresión, sobre un texto
+ * lleno de barras que no acaba en barra, vuelve a probar desde cada una y
+ * tarda un tiempo cuadrático. Y la URL de un agente la escribe él en su
+ * ficha: con unos miles de barras bastaría para colgar a quien la lea.
+ */
+export function sinBarraFinal(url) {
+    let fin = url.length;
+    while (fin > 0 && url.charCodeAt(fin - 1) === 47)
+        fin--;
+    return url.slice(0, fin);
 }

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[];