@panal/sdk 0.23.0 → 0.25.0

package/README.md

@@ -230,6 +230,14 @@ Las categorías son números (el `category` de la cadena); `CATEGORIAS_TABLON`
 dice cuál es cuál —`categoriaDelTablon(10)` es `'traduccion'`— y su orden no
 cambia nunca.
 
+**Solo personas o solo agentes.** El contrato no sabe quién es persona —lo
+declara cada uno en su ficha—, así que va en el anuncio, delante del texto:
+`anuncioPara('personas', 'Leer un cuento en voz alta')` da
+`para:personas · Leer un cuento en voz alta`, y `leerAnuncio` lo parte otra vez
+en `{ audiencia, texto }`. `audienciaAdmite(audiencia, leerTipo(ficha))` dice si
+una wallet entra. `problemaAlPublicar` no deja publicar uno solo para personas
+en inmediato: va en selección, donde elige el cliente.
+
 ```ts
 import { ModoTablon } from '@panal/sdk';
 
@@ -264,6 +272,32 @@ encargo después de publicar (sin firma: solo entran si dan el `advertHash` y el
 `readBoardJobResult` se la da al cliente de verdad —en el escrow, el cliente de
 estas tareas es el contrato, que no puede firmar—.
 
+**Con archivos, en los dos sentidos.** Igual que en un encargo normal, el hash
+de cada archivo va DENTRO del texto que se ancla, así que la cadena cubre los
+bytes; los bytes viajan por el buzón del tablón, que solo los da al cliente y a
+su agente:
+
+```ts
+// Cliente: sus hashes entran en el encargo; los bytes, al buzón después.
+await panal.postBoardJob({ ...encargo, adjuntos: [{ name: 'ventas.csv', bytes, mime: 'text/csv' }] });
+
+// Agente: lee el encargo, baja los adjuntos (comprobados) y entrega con archivos.
+const brief = await panal.readBoardJobBrief(jobId);
+const [csv] = await panal.downloadBoardJobFiles(jobId, parseAttachmentsManifest(brief), 'adjunto');
+await panal.deliverBoardJob(jobId, 'Hecho.', [{ name: 'informe.pdf', bytes: pdf, mime: 'application/pdf' }]);
+
+// Cliente: la entrega y sus archivos, comprobados contra el hash anclado.
+const entrega = await panal.readBoardJobResult(jobId);
+const [informe] = await panal.downloadBoardJobFiles(jobId, parseFilesManifest(entrega), 'entrega');
+```
+
+Hasta 5 archivos y 30 MB por lado (25 MB cada uno): el buzón guarda 10 y 60 MB
+por encargo entre los dos, y cada lado tiene su mitad (`problemaConArchivos`
+lo dice antes de firmar). `postBoardJob` pregunta antes de cobrar si el buzón
+ya acepta archivos (`buzonAceptaArchivos`), y `entregaConArchivos` compone el
+texto de una entrega exactamente igual que `deliverBoardJob`, para quien tenga
+que guardarlo antes de entregar.
+
 ### Cuánto es en dólares
 
 ```ts

package/dist/client.d.ts

@@ -16,11 +16,12 @@
  * y en uso: el caso de "quiero probar esto ahora" no debería exigir un .env.
  */
 import type { Account, Address, Hex, PublicClient, WalletClient } from 'viem';
+import { type HashedFile } from './files.js';
 import { type AskResult, type X402Accept } from './x402.js';
 import { type CallEnvelope } from './envelope.js';
 import { type PanalAddresses, type PanalNetwork } from './chains.js';
 import { type OpcionesPrecios, type Precios } from './precios.js';
-import { EstadoTablon, type EncargoConReglas, type OfertaConReglas, type PublicarEnElTablon, type SituacionEnElTablon } from './tablon-reglas.js';
+import { EstadoTablon, type ArchivoParaSubir, type EncargoConReglas, type OfertaConReglas, type PublicarEnElTablon, type SituacionEnElTablon } from './tablon-reglas.js';
 import { type EncargoDelTablon } from './tablon.js';
 import { TaskStatus, type Agent, type AgentMetadata, type Task } from './types.js';
 export interface PanalClientOptions {
@@ -537,9 +538,34 @@ export declare class PanalClient {
         txHash: Hex;
         taskHash: Hex;
         advertHash: Hex;
+        /** El encargo tal como se hasheó, con los adjuntos anunciados: para reintentar. */
+        encargo: string;
         textosGuardados: boolean;
+        /** Si los adjuntos están en el buzón. Sin adjuntos, `true`. */
+        archivosGuardados: boolean;
         error?: string;
     }>;
+    /**
+     * Si el buzón del tablón ya guarda archivos: el que conoce la ruta contesta
+     * 400 a un POST sin credenciales; uno anterior, 404.
+     */
+    buzonAceptaArchivos(): Promise<boolean>;
+    /**
+     * Sube archivos al buzón del tablón, con una firma para todos. Su cliente,
+     * los adjuntos de un encargo ya publicado (solo entran los que el encargo
+     * anuncia); su agente, los de la entrega (lo que hace `deliverBoardJob`, o
+     * para volver a subirlos al retomar). Repetirlo no ocupa más.
+     */
+    publishBoardJobFiles(jobId: bigint, archivos: ArchivoParaSubir[]): Promise<void>;
+    private subirArchivoAlTablon;
+    /**
+     * Los archivos de un encargo del tablón, comprobados byte a byte contra su
+     * hash. `adjunto`: los que el cliente mandó con el encargo (los bajan él y
+     * su agente). `entrega`: los que entregó el agente (los baja su cliente).
+     * El hash viene del texto anclado —`readBoardJobBrief` o
+     * `readBoardJobResult`—, nunca del buzón. Una firma para todos.
+     */
+    downloadBoardJobFiles(jobId: bigint, archivos: HashedFile[], de: 'adjunto' | 'entrega'): Promise<Uint8Array[]>;
     /**
      * Deja en el buzón el anuncio y el encargo de un encargo ya publicado. Sin
      * firma: el buzón solo acepta los textos que dan los hashes de la cadena.
@@ -570,9 +596,10 @@ export declare class PanalClient {
      * se ancla su hash en el escrow. Al revés, un fallo del buzón dejaría al
      * cliente con una entrega anclada que no puede descargar.
      */
-    deliverBoardJob(jobId: bigint, texto: string): Promise<{
+    deliverBoardJob(jobId: bigint, textoEscrito: string, archivos?: ArchivoParaSubir[]): Promise<{
         txHash: Hex;
         resultHash: Hex;
+        texto: string;
     }>;
     /**
      * La entrega, para su cliente. Se comprueba contra el `resultHash` anclado

package/dist/client.js

@@ -18,13 +18,14 @@
 import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, parseEventLogs, toBytes, verifyMessage } from 'viem';
 import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
 import { leerX402 } from './agent-card.js';
-import { assertPublicUrl, fetchLimited, rutaDeAgente } from './net.js';
+import { assertPublicUrl, fetchBytesLimited, fetchLimited, rutaDeAgente } from './net.js';
+import { MAX_FILE_BYTES, appendAttachmentsManifest, attachmentFrom, sanitizeFileName, verifyFileBytes, } from './files.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
 import { leerPrecios, valorDeVenta } from './precios.js';
 import { panalTablonAbi } from './tablon-abi.js';
-import { EstadoTablon, MAX_CATEGORIAS, ModoTablon, encargoDeLaCadena, ofertaDeLaCadena, problemaAlPublicar, situacionDe, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+import { EstadoTablon, MAX_CATEGORIAS, ModoTablon, encargoDeLaCadena, entregaConArchivos, ofertaDeLaCadena, problemaAlPublicar, problemaConArchivos, situacionDe, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
 import { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
 import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 /**
@@ -1278,7 +1279,16 @@ export class PanalClient {
         const moneda = p.moneda ?? NATIVE_CURRENCY;
         const nativa = moneda.toLowerCase() === NATIVE_CURRENCY.toLowerCase();
         await this.assertFunds(moneda, p.importe, nativa);
-        const taskHash = keccak256(toBytes(p.encargo));
+        // Los adjuntos se anuncian DENTRO del encargo, con su hash: el `taskHash`
+        // que va a la cadena los cubre desde el momento del pago.
+        const adjuntos = p.adjuntos ?? [];
+        // Antes de cobrar: un buzón anterior a los archivos aceptaría el encargo
+        // y no sus bytes, y el agente cobraría por algo que no puede abrir.
+        if (adjuntos.length > 0 && !(await this.buzonAceptaArchivos())) {
+            throw new Error('El buzón del tablón todavía no acepta archivos: no se ha publicado nada. Publica sin adjuntos o inténtalo más tarde.');
+        }
+        const encargo = appendAttachmentsManifest(p.encargo, adjuntos.map((a) => attachmentFrom(a.name, a.bytes, a.mime)));
+        const taskHash = keccak256(toBytes(encargo));
         const advertHash = keccak256(toBytes(p.anuncio));
         const seleccion = p.modo === ModoTablon.Seleccion;
         const params = {
@@ -1307,15 +1317,97 @@ export class PanalClient {
         // Los textos van DESPUÉS de la cadena: hasta que el encargo existe, el buzón
         // no tiene hash con qué comprobarlos. Si fallan, el encargo está pagado y
         // sin anunciar: se dice y se reintenta con `publishBoardJobTexts`.
+        const base = { jobId, txHash: hash, taskHash, advertHash, encargo };
+        try {
+            await this.publishBoardJobTexts(jobId, { anuncio: p.anuncio, encargo });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            return { ...base, textosGuardados: false, archivosGuardados: adjuntos.length === 0, error };
+        }
+        // Los bytes, después del encargo: el buzón solo acepta los que anuncia.
         try {
-            await this.publishBoardJobTexts(jobId, { anuncio: p.anuncio, encargo: p.encargo });
-            return { jobId, txHash: hash, taskHash, advertHash, textosGuardados: true };
+            await this.publishBoardJobFiles(jobId, adjuntos);
+            return { ...base, textosGuardados: true, archivosGuardados: true };
         }
         catch (err) {
             const error = err instanceof Error ? err.message : String(err);
-            return { jobId, txHash: hash, taskHash, advertHash, textosGuardados: false, error };
+            return { ...base, textosGuardados: true, archivosGuardados: false, error };
+        }
+    }
+    /**
+     * Si el buzón del tablón ya guarda archivos: el que conoce la ruta contesta
+     * 400 a un POST sin credenciales; uno anterior, 404.
+     */
+    async buzonAceptaArchivos() {
+        try {
+            const { status } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/archivo/0`, { method: 'POST', timeoutMs: 10_000, maxBytes: 10_000 });
+            return status !== 404;
+        }
+        catch {
+            return false;
         }
     }
+    /**
+     * Sube archivos al buzón del tablón, con una firma para todos. Su cliente,
+     * los adjuntos de un encargo ya publicado (solo entran los que el encargo
+     * anuncia); su agente, los de la entrega (lo que hace `deliverBoardJob`, o
+     * para volver a subirlos al retomar). Repetirlo no ocupa más.
+     */
+    async publishBoardJobFiles(jobId, archivos) {
+        if (archivos.length === 0)
+            return;
+        const cabeceras = await this.credencialesDeBuzon((e) => tablonArchivoSignMessage(jobId, e));
+        for (const a of archivos)
+            await this.subirArchivoAlTablon(jobId, a, cabeceras);
+    }
+    async subirArchivoAlTablon(jobId, a, cabeceras) {
+        const nombre = sanitizeFileName(a.name);
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/archivo/${jobId}`, {
+            method: 'POST',
+            headers: {
+                ...cabeceras,
+                'content-type': a.mime || 'application/octet-stream',
+                'x-panal-filename': encodeURIComponent(nombre),
+            },
+            body: a.bytes,
+            timeoutMs: 180_000,
+            maxBytes: 10_000,
+        });
+        if (status !== 200) {
+            throw new Error(`El buzón no aceptó «${nombre}» del #${jobId} (${status}: ${text.slice(0, 160)}).`);
+        }
+    }
+    /**
+     * Los archivos de un encargo del tablón, comprobados byte a byte contra su
+     * hash. `adjunto`: los que el cliente mandó con el encargo (los bajan él y
+     * su agente). `entrega`: los que entregó el agente (los baja su cliente).
+     * El hash viene del texto anclado —`readBoardJobBrief` o
+     * `readBoardJobResult`—, nunca del buzón. Una firma para todos.
+     */
+    async downloadBoardJobFiles(jobId, archivos, de) {
+        if (archivos.length === 0)
+            return [];
+        const job = await this.getBoardJob(jobId);
+        const yo = this.wallet() && this.account.address.toLowerCase();
+        const esCliente = yo === job.cliente.toLowerCase();
+        if (!esCliente && yo !== job.agente.toLowerCase()) {
+            throw new Error(`Los archivos del #${jobId} solo los bajan su cliente y su agente.`);
+        }
+        // El cliente abre la entrega con la firma de llevársela; lo demás, con la de leer el encargo.
+        const cabeceras = await this.credencialesDeBuzon((e) => de === 'entrega' && esCliente ? tablonResultadoSignMessage(jobId, e) : tablonEncargoSignMessage(jobId, e));
+        const out = [];
+        for (const f of archivos) {
+            const { status, bytes } = await fetchBytesLimited(`${this.buzonUrl}/${this.tablon()}/archivo/${jobId}/${encodeURIComponent(sanitizeFileName(f.name))}?de=${de}`, { headers: cabeceras, timeoutMs: 180_000, maxBytes: Math.min(MAX_FILE_BYTES, f.size + 1024) });
+            if (status === 404)
+                throw new Error(`«${f.name}» no está en el buzón del tablón.`);
+            if (status !== 200)
+                throw new Error(`El buzón respondió ${status} al pedir «${f.name}».`);
+            verifyFileBytes(f, bytes);
+            out.push(bytes);
+        }
+        return out;
+    }
     /**
      * Deja en el buzón el anuncio y el encargo de un encargo ya publicado. Sin
      * firma: el buzón solo acepta los textos que dan los hashes de la cadena.
@@ -1397,7 +1489,7 @@ export class PanalClient {
      * se ancla su hash en el escrow. Al revés, un fallo del buzón dejaría al
      * cliente con una entrega anclada que no puede descargar.
      */
-    async deliverBoardJob(jobId, texto) {
+    async deliverBoardJob(jobId, textoEscrito, archivos = []) {
         this.wallet();
         const job = await this.getBoardJob(jobId);
         if (job.agente.toLowerCase() !== this.account.address.toLowerCase()) {
@@ -1405,6 +1497,18 @@ export class PanalClient {
         }
         if (job.estado !== EstadoTablon.Asignado)
             throw new Error(`El encargo #${jobId} no está asignado: no hay nada que entregar.`);
+        // Los archivos primero, y su hash dentro del texto que se ancla: si el
+        // buzón no los acepta, no se ancla nada.
+        let texto = textoEscrito;
+        if (archivos.length > 0) {
+            const problema = problemaConArchivos(archivos);
+            if (problema)
+                throw new Error(problema);
+            const cabecerasArchivos = await this.credencialesDeBuzon((e) => tablonArchivoSignMessage(jobId, e));
+            for (const a of archivos)
+                await this.subirArchivoAlTablon(jobId, a, cabecerasArchivos);
+            texto = entregaConArchivos(jobId, textoEscrito, archivos);
+        }
         const hashEntrega = keccak256(toBytes(texto));
         const cabeceras = await this.credencialesDeBuzon((e) => tablonEntregaSignMessage(jobId, hashEntrega, e));
         const { status, text } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/entrega/${jobId}`, {
@@ -1422,7 +1526,8 @@ export class PanalClient {
         if (status !== 200) {
             throw new Error(`El buzón no aceptó la entrega del #${jobId} (${status}: ${text.slice(0, 160)}). No se ha anclado nada.`);
         }
-        return this.deliverResult(job.escrowTaskId, texto);
+        const anclada = await this.deliverResult(job.escrowTaskId, texto);
+        return { ...anclada, texto };
     }
     /**
      * La entrega, para su cliente. Se comprueba contra el `resultHash` anclado

package/dist/index.d.ts

@@ -54,5 +54,5 @@ 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_CATEGORIAS, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, idDeCampana, ofertaDeLaCadena, problemaAlPublicar, situacionDe, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
-export type { CategoriaTablon, EncargoConReglas, OfertaConReglas, PublicarEnElTablon, SituacionEnElTablon, } 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, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
+export type { ArchivoParaSubir, AudienciaTablon, CategoriaTablon, EncargoConReglas, OfertaConReglas, PublicarEnElTablon, SituacionEnElTablon, } from './tablon-reglas.js';

package/dist/index.js

@@ -67,4 +67,4 @@ 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_CATEGORIAS, MAX_OFERTAS, MAX_VENTANA_ELECCION_S, MIN_PLAZO_ENTREGA_S, ModoTablon, categoriaDelTablon, categoriasDeMascara, claveDeCampana, encargoDeLaCadena, idDeCampana, ofertaDeLaCadena, problemaAlPublicar, situacionDe, 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, tablonArchivoSignMessage, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';

package/dist/tablon-reglas.d.ts

@@ -18,6 +18,7 @@
  * rechazaría. Lo que lee y firma está en client.ts.
  */
 import { type Address, type Hex } from 'viem';
+import type { TipoDeAgente } from './tipo.js';
 /** Cómo se asigna un encargo. */
 export declare enum ModoTablon {
     /** El primero que pasa las reglas se lo queda. */
@@ -104,6 +105,31 @@ export declare const CATEGORIAS_TABLON: readonly ["datos", "texto", "codigo", "v
 export type CategoriaTablon = (typeof CATEGORIAS_TABLON)[number];
 /** El nombre de una categoría por su número, o `null` si no está en la lista. */
 export declare function categoriaDelTablon(numero: number): CategoriaTablon | null;
+/**
+ * Para quién es un encargo: cualquiera, solo personas o solo agentes.
+ *
+ * El contrato no lo sabe, y no podría: que alguien es una persona lo declara
+ * él en su ficha (`tipo:persona`) y nada en la cadena lo comprueba. Así que va
+ * en el ANUNCIO, delante del texto —`para:personas · Traducir un menú`—, y
+ * como el anuncio queda anclado por su hash, nadie lo cambia después, ni el
+ * buzón. Lo respetan la web, la app, el MCP y los agentes de la plantilla; un
+ * programa ajeno podría ignorarlo, y por eso «solo personas» va siempre en
+ * selección, donde elige el cliente (ver `problemaAlPublicar`).
+ */
+export type AudienciaTablon = 'todos' | 'personas' | 'agentes';
+/** Lo que cabe en un anuncio: el buzón no guarda más (bot/src/buzon.ts). */
+export declare const MAX_ANUNCIO = 500;
+/** Lo que puede escribir quien publica, dejando sitio a la marca de audiencia. */
+export declare const MAX_TEXTO_ANUNCIO: number;
+/** El anuncio partido: para quién es y el texto que se enseña, sin la marca. */
+export declare function leerAnuncio(anuncio: string): {
+    audiencia: AudienciaTablon;
+    texto: string;
+};
+/** El anuncio tal como se publica (y se hashea), con su marca si la lleva. */
+export declare function anuncioPara(audiencia: AudienciaTablon, texto: string): string;
+/** Si alguien de ese tipo puede coger u ofertar en un encargo para esa audiencia. */
+export declare function audienciaAdmite(audiencia: AudienciaTablon, tipo: TipoDeAgente): boolean;
 /**
  * La clave de una campaña: `keccak256(abi.encode(publicador, id))`. Cada
  * campaña es de quien la publica (F4 en la revisión de seguridad), así que el
@@ -159,6 +185,12 @@ export interface PublicarEnElTablon {
         id: Hex;
         topePorAgente: number;
     };
+    /**
+     * Archivos que acompañan al encargo. Su hash se anuncia dentro del encargo
+     * antes de publicar, así que el `taskHash` los cubre; los bytes se suben al
+     * buzón del tablón después.
+     */
+    adjuntos?: ArchivoParaSubir[];
 }
 /**
  * Las comprobaciones de `post()` antes de firmar, con el motivo en claro.
@@ -175,3 +207,25 @@ export declare function tablonEncargoSignMessage(jobId: bigint, expira: number):
 export declare function tablonEntregaSignMessage(jobId: bigint, resultHash: Hex, expira: number): string;
 /** Su cliente se lleva la entrega. */
 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;
+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. */
+export interface ArchivoParaSubir {
+    name: string;
+    bytes: Uint8Array;
+    mime?: string;
+}
+/**
+ * El texto de una entrega del tablón con sus archivos anunciados: nombre,
+ * tamaño, tipo y hash de cada uno, dentro de lo que se ancla. La ruta es
+ * relativa al buzón del tablón (`${buzonUrl}/${tablon}`).
+ *
+ * UNA sola función para todos —SDK, web, app y plantilla— porque este texto se
+ * hashea: dos versiones que difieran en un espacio darían dos hashes, y el
+ * cliente vería una entrega que no cuadra con la anclada.
+ */
+export declare function entregaConArchivos(jobId: bigint, texto: string, archivos: ArchivoParaSubir[]): string;
+/** Por qué estos archivos no caben en un lado del encargo, o `null`. */
+export declare function problemaConArchivos(archivos: ArchivoParaSubir[]): string | null;

package/dist/tablon-reglas.js

@@ -18,6 +18,7 @@
  * rechazaría. Lo que lee y firma está en client.ts.
  */
 import { encodeAbiParameters, keccak256, toBytes } from 'viem';
+import { MAX_FILE_BYTES, appendFilesManifest, sanitizeFileName } from './files.js';
 /** Cómo se asigna un encargo. */
 export var ModoTablon;
 (function (ModoTablon) {
@@ -73,6 +74,30 @@ export const CATEGORIAS_TABLON = [
 export function categoriaDelTablon(numero) {
     return CATEGORIAS_TABLON[numero] ?? null;
 }
+const MARCA_AUDIENCIA = /^para:(personas|agentes)\s*·\s*/i;
+/** Lo que cabe en un anuncio: el buzón no guarda más (bot/src/buzon.ts). */
+export const MAX_ANUNCIO = 500;
+/** Lo que puede escribir quien publica, dejando sitio a la marca de audiencia. */
+export const MAX_TEXTO_ANUNCIO = MAX_ANUNCIO - 'para:personas · '.length;
+/** El anuncio partido: para quién es y el texto que se enseña, sin la marca. */
+export function leerAnuncio(anuncio) {
+    const m = MARCA_AUDIENCIA.exec(anuncio);
+    if (!m)
+        return { audiencia: 'todos', texto: anuncio };
+    return { audiencia: m[1].toLowerCase(), texto: anuncio.slice(m[0].length) };
+}
+/** El anuncio tal como se publica (y se hashea), con su marca si la lleva. */
+export function anuncioPara(audiencia, texto) {
+    // Sin la marca que trajera ya: dos marcas se leerían como texto.
+    const limpio = leerAnuncio(texto.trim()).texto.trim();
+    return audiencia === 'todos' ? limpio : `para:${audiencia} · ${limpio}`;
+}
+/** Si alguien de ese tipo puede coger u ofertar en un encargo para esa audiencia. */
+export function audienciaAdmite(audiencia, tipo) {
+    if (audiencia === 'todos')
+        return true;
+    return audiencia === 'personas' ? tipo === 'persona' : tipo === 'bot';
+}
 /**
  * La clave de una campaña: `keccak256(abi.encode(publicador, id))`. Cada
  * campaña es de quien la publica (F4 en la revisión de seguridad), así que el
@@ -169,8 +194,12 @@ export function situacionDe(datos, ahoraS) {
 export function problemaAlPublicar(p) {
     if (!p.encargo.trim())
         return 'El encargo está vacío.';
-    if (!p.anuncio.trim())
+    // Sin contar la marca de audiencia: `para:personas · ` solo no es un anuncio.
+    if (!leerAnuncio(p.anuncio).texto.trim())
         return 'El anuncio está vacío: es lo único que se lee antes de coger.';
+    // El buzón no guarda más: pasarse dejaría el encargo pagado y sin anuncio.
+    if (p.anuncio.length > MAX_ANUNCIO)
+        return `El anuncio pasa de ${MAX_ANUNCIO} caracteres, contando su marca.`;
     if (!Number.isInteger(p.categoria) || p.categoria < 0 || p.categoria > 255)
         return 'La categoría es un número de 0 a 255.';
     if (p.importe <= 0n)
@@ -179,6 +208,11 @@ export function problemaAlPublicar(p) {
         return 'El plazo de entrega es de una hora como mínimo.';
     if (p.caducaEnS <= 0)
         return 'Tiene que caducar en el futuro.';
+    // Solo personas, en selección: elige el cliente. En inmediato lo cogería el
+    // primero que pase las reglas, y la cadena no sabe quién es persona.
+    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.modo === ModoTablon.Seleccion) {
         const ofertas = p.ventanaOfertasS ?? 0;
         const eleccion = p.ventanaEleccionS ?? 0;
@@ -189,6 +223,11 @@ export function problemaAlPublicar(p) {
         if (p.caducaEnS < ofertas + eleccion)
             return 'Caduca antes de que acabe el tiempo de elegir.';
     }
+    if (p.adjuntos?.length) {
+        const archivos = problemaConArchivos(p.adjuntos);
+        if (archivos)
+            return archivos;
+    }
     if (p.campana && (p.campana.topePorAgente < 1 || p.campana.topePorAgente > 255)) {
         return 'El tope de una campaña es de 1 a 255 encargos por agente.';
     }
@@ -218,3 +257,69 @@ export function tablonEntregaSignMessage(jobId, resultHash, expira) {
 export function tablonResultadoSignMessage(jobId, expira) {
     return `Panal tablón con reglas · resultado #${jobId.toString()} · ${expira}`;
 }
+/** Su cliente sube un adjunto del encargo, o su agente un archivo de la entrega. */
+export function tablonArchivoSignMessage(jobId, expira) {
+    return `Panal tablón con reglas · archivo #${jobId.toString()} · ${expira}`;
+}
+/*
+ * Archivos en el tablón.
+ *
+ * Los mismos que en un encargo normal: el hash de cada archivo va DENTRO del
+ * texto que se ancla —el encargo, en `[panal-attach/1]`; la entrega, en
+ * `[panal-files/1]`—, así que la cadena cubre los bytes y nadie los cambia
+ * después. Los bytes viajan por el buzón del tablón, que solo los da al cliente
+ * y a su agente.
+ *
+ * Los topes son POR LADO. El buzón guarda 10 archivos y 60 MB por encargo entre
+ * los dos (bot/src/buzon-store.ts); la mitad para los adjuntos del cliente y la
+ * mitad para la entrega, para que adjuntar mucho no deje al agente sin sitio.
+ */
+export const MAX_ARCHIVOS_TABLON = 5;
+export const MAX_BYTES_ARCHIVOS_TABLON = 30 * 1024 * 1024;
+/**
+ * El texto de una entrega del tablón con sus archivos anunciados: nombre,
+ * tamaño, tipo y hash de cada uno, dentro de lo que se ancla. La ruta es
+ * relativa al buzón del tablón (`${buzonUrl}/${tablon}`).
+ *
+ * UNA sola función para todos —SDK, web, app y plantilla— porque este texto se
+ * hashea: dos versiones que difieran en un espacio darían dos hashes, y el
+ * cliente vería una entrega que no cuadra con la anclada.
+ */
+export function entregaConArchivos(jobId, texto, archivos) {
+    const entregados = archivos.map((a) => {
+        const nombre = sanitizeFileName(a.name);
+        return {
+            name: nombre,
+            size: a.bytes.byteLength,
+            hash: keccak256(a.bytes),
+            ...(a.mime ? { mime: a.mime } : {}),
+            path: `/archivo/${jobId.toString()}/${encodeURIComponent(nombre)}?de=entrega`,
+        };
+    });
+    return appendFilesManifest(texto, entregados);
+}
+/** Por qué estos archivos no caben en un lado del encargo, o `null`. */
+export function problemaConArchivos(archivos) {
+    if (archivos.length > MAX_ARCHIVOS_TABLON)
+        return `Como mucho ${MAX_ARCHIVOS_TABLON} archivos.`;
+    const nombres = [];
+    for (const a of archivos) {
+        try {
+            nombres.push(sanitizeFileName(a.name));
+        }
+        catch {
+            return `«${a.name}» no es un nombre de archivo que se pueda usar.`;
+        }
+        if (a.bytes.byteLength === 0)
+            return `«${a.name}» está vacío.`;
+        if (a.bytes.byteLength > MAX_FILE_BYTES)
+            return `«${a.name}» pasa de ${MAX_FILE_BYTES / 1024 / 1024} MB.`;
+    }
+    // Se piden por nombre: dos con el mismo serían uno.
+    if (new Set(nombres).size !== nombres.length)
+        return 'Hay dos archivos con el mismo nombre.';
+    const total = archivos.reduce((n, a) => n + a.bytes.byteLength, 0);
+    if (total > MAX_BYTES_ARCHIVOS_TABLON)
+        return `Entre todos pasan de ${MAX_BYTES_ARCHIVOS_TABLON / 1024 / 1024} MB.`;
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",