@panal/sdk 0.25.0 → 0.27.0

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/tablon-reglas.d.ts

@@ -191,6 +191,13 @@ export interface PublicarEnElTablon {
      * buzón del tablón después.
      */
     adjuntos?: ArchivoParaSubir[];
+    /**
+     * Confidencial: el encargo y sus adjuntos se cifran para quien publica, y al
+     * elegir una oferta se le da acceso solo a quien se elige (que tiene que
+     * tener su clave publicada). El anuncio sigue siendo público. Solo en
+     * selección: en inmediato lo cogería cualquiera sin que nadie le diera acceso.
+     */
+    confidencial?: boolean;
 }
 /**
  * Las comprobaciones de `post()` antes de firmar, con el motivo en claro.
@@ -209,6 +216,13 @@ export declare function tablonEntregaSignMessage(jobId: bigint, resultHash: Hex,
 export declare function tablonResultadoSignMessage(jobId: bigint, expira: number): string;
 /** Su cliente sube un adjunto del encargo, o su agente un archivo de la entrega. */
 export declare function tablonArchivoSignMessage(jobId: bigint, expira: number): string;
+/**
+ * Una parte da acceso a lo cifrado de su encargo: a quien lo cogió o a quien
+ * decide una disputa (`concederAcceso`, en cifrado.ts).
+ */
+export declare function tablonAccesoSignMessage(jobId: bigint, expira: number): string;
+/** Un firmante de la multisig lee una disputa: el encargo, la entrega y sus archivos. */
+export declare function tablonDisputaSignMessage(jobId: bigint, expira: number): string;
 export declare const MAX_ARCHIVOS_TABLON = 5;
 export declare const MAX_BYTES_ARCHIVOS_TABLON: number;
 /** Un archivo para subir al tablón: su nombre, sus bytes y su tipo si se sabe. */

package/dist/tablon-reglas.js

@@ -213,6 +213,9 @@ export function problemaAlPublicar(p) {
     if (leerAnuncio(p.anuncio).audiencia === 'personas' && p.modo !== ModoTablon.Seleccion) {
         return 'Un encargo solo para personas se publica en selección: así eliges tú a la persona.';
     }
+    if (p.confidencial && p.modo !== ModoTablon.Seleccion) {
+        return 'Un encargo confidencial se publica en selección: a quien lo coge se le da acceso al elegirlo.';
+    }
     if (p.modo === ModoTablon.Seleccion) {
         const ofertas = p.ventanaOfertasS ?? 0;
         const eleccion = p.ventanaEleccionS ?? 0;
@@ -261,6 +264,17 @@ export function tablonResultadoSignMessage(jobId, expira) {
 export function tablonArchivoSignMessage(jobId, expira) {
     return `Panal tablón con reglas · archivo #${jobId.toString()} · ${expira}`;
 }
+/**
+ * Una parte da acceso a lo cifrado de su encargo: a quien lo cogió o a quien
+ * decide una disputa (`concederAcceso`, en cifrado.ts).
+ */
+export function tablonAccesoSignMessage(jobId, expira) {
+    return `Panal tablón con reglas · acceso #${jobId.toString()} · ${expira}`;
+}
+/** Un firmante de la multisig lee una disputa: el encargo, la entrega y sus archivos. */
+export function tablonDisputaSignMessage(jobId, expira) {
+    return `Panal tablón con reglas · disputa #${jobId.toString()} · ${expira}`;
+}
 /*
  * Archivos en el tablón.
  *

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.25.0",
+  "version": "0.27.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,11 @@
   "engines": {
     "node": ">=20"
   },
+  "dependencies": {
+    "@noble/ciphers": "^1.3.0",
+    "@noble/curves": "^1.9.1",
+    "@noble/hashes": "^1.8.0"
+  },
   "peerDependencies": {
     "viem": "^2.21.0"
   },
@@ -45,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",
+    "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"
   }
 }