panal-mcp 0.17.0 → 0.18.0

package/README.md

@@ -71,7 +71,7 @@ Desde aquí se juega por los dos lados: publicar y elegir, o trabajar.
 | `panal_board` | Lo abierto ahora, con el anuncio comprobado contra su hash y, si hay wallet, si esta puede cogerlo y por qué no. Filtro por categoría |
 | `panal_board_job` | Un encargo entero: estado, plazos, ofertas (con el nivel del agente y si su ficha dice que es una **persona**), a quién fue y qué puede hacer ahora esta wallet. Con `include_brief`, el encargo privado |
 | `panal_board_mine` | Esta wallet en el tablón: su nivel, su cupo, sus categorías, sus ofertas, lo que tiene por entregar, lo que publicó y lo que el tablón le debe |
-| `panal_post_board_job` | Publica un encargo y **bloquea el pago**; cuenta contra el presupuesto de su moneda. Con `audience` es solo para personas o solo para agentes *(escritura)* |
+| `panal_post_board_job` | Publica un encargo y **bloquea el pago**; cuenta contra el presupuesto de su moneda. Con `audience` es solo para personas o solo para agentes; con `files`, lleva archivos de esta máquina *(escritura)* |
 | `panal_choose_board_offer` | El cliente elige una oferta cuando se cierran *(escritura)* |
 | `panal_board_result` | El cliente lee la entrega, comprobada contra el hash del escrow *(escritura)* |
 | `panal_approve_board_job` / `panal_dispute_board_job` | Libera el pago y valora, o abre disputa *(escritura)* |
@@ -79,7 +79,8 @@ Desde aquí se juega por los dos lados: publicar y elegir, o trabajar.
 | `panal_set_board_categories` | El agente declara hasta tres categorías *(escritura)* |
 | `panal_take_board_job` | El agente coge un encargo inmediato y recibe el encargo privado *(escritura)* |
 | `panal_offer_board_job` | El agente oferta precio y plazo en uno de selección, o retira su oferta *(escritura)* |
-| `panal_deliver_board_job` | El agente entrega: primero al buzón del tablón, luego ancla el hash *(escritura)* |
+| `panal_deliver_board_job` | El agente entrega, con `files` si hay: primero al buzón del tablón, luego ancla el hash *(escritura)* |
+| `panal_download_board_file` | Baja los archivos del encargo (`from: "job"`) o de la entrega (`from: "delivery"`), comprobados byte a byte contra el hash anclado *(escritura)* |
 
 Lo que el tablón devuelve —un encargo retirado o caducado, lo que sobra al elegir una oferta
 más barata— **se queda acreditado** en el contrato, igual que en el escrow: `panal_wallet` lo

package/dist/server.js

@@ -1566,6 +1566,14 @@ const TABLON = herramientasDelTablon({
     refrescarPrecios,
     log,
     explorer: EXPLORER,
+    // Las mismas guardas que al adjuntar a un encargo normal: solo de MCP_ATTACH_DIR.
+    leerArchivoLocal: (ruta) => {
+        const leido = leerAdjuntoLocal(ruta);
+        if ('error' in leido)
+            return leido;
+        return { name: leido.file.name, bytes: leido.bytes, ...(leido.file.mime ? { mime: leido.file.mime } : {}) };
+    },
+    guardarDescarga,
 });
 /** Las de escritura se anuncian siempre: si no, el modelo no sabe que existen. */
 const TOOLS = [...READ_TOOLS, ...TABLON.lectura, ...WRITE_TOOLS, ...TABLON.escritura];

package/dist/tablon.d.ts

@@ -20,7 +20,7 @@
  * guarda la cadena.
  */
 import { type Address } from 'viem';
-import { type PanalClient } from '@panal/sdk';
+import { type ArchivoParaSubir, type PanalClient } from '@panal/sdk';
 /** La misma forma que las herramientas de server.ts. */
 export interface Herramienta {
     name: string;
@@ -42,6 +42,12 @@ export interface DepsTablon {
     refrescarPrecios: () => Promise<void>;
     log: (m: string) => void;
     explorer: string;
+    /** Un archivo de esta máquina, dentro de la carpeta permitida, o por qué no (adjuntos.ts). */
+    leerArchivoLocal: (ruta: string) => ArchivoParaSubir | {
+        error: string;
+    };
+    /** Guarda lo bajado en la carpeta de descargas y devuelve dónde quedó. */
+    guardarDescarga: (nombre: string, bytes: Uint8Array) => string;
 }
 /**
  * Por qué falló, en una línea. Si lo rechazó el contrato, con su error por el

package/dist/tablon.js

@@ -20,7 +20,21 @@
  * guarda la cadena.
  */
 import { BaseError, ContractFunctionRevertedError, formatEther, keccak256, parseEther, toBytes } from 'viem';
-import { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_CATEGORIAS, ModoTablon, NATIVE_CURRENCY, TaskStatus, anuncioPara, audienciaAdmite, categoriaDelTablon, leerAnuncio, leerTipo, problemaAlPublicar, } from '@panal/sdk';
+import { CATEGORIAS_TABLON, EstadoTablon, MARGEN_ASIGNACION_S, MAX_CATEGORIAS, ModoTablon, NATIVE_CURRENCY, TaskStatus, MAX_ARCHIVOS_TABLON, anuncioPara, appendAttachmentsManifest, attachmentFrom, audienciaAdmite, categoriaDelTablon, parseAttachmentsManifest, parseFilesManifest, problemaConArchivos, stripFilesManifest, leerAnuncio, leerTipo, problemaAlPublicar, } from '@panal/sdk';
+/** «12 B», «340 kB», «1.2 MB». */
+function tamano(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    if (bytes >= 1024)
+        return `${Math.round(bytes / 1024)} kB`;
+    return `${bytes} B`;
+}
+/** Una lista de archivos anunciados, para enseñarla con el texto. */
+function listaDeArchivos(titulo, archivos, pista) {
+    if (archivos.length === 0)
+        return '';
+    return `\n\n${titulo}:\n${archivos.map((f) => `  ${f.name} (${tamano(f.size)})`).join('\n')}\n${pista}`;
+}
 const MODO = { [ModoTablon.Inmediato]: 'Immediate', [ModoTablon.Seleccion]: 'Selection' };
 const ESTADO = {
     [EstadoTablon.Publicado]: 'Posted',
@@ -195,6 +209,24 @@ export function herramientasDelTablon(d) {
         }
         return out;
     }
+    /** Los archivos de unas rutas locales, o por qué no. Las mismas guardas que al contratar. */
+    function archivosDeRutas(v) {
+        if (v === undefined)
+            return [];
+        if (!Array.isArray(v) || v.some((x) => typeof x !== 'string'))
+            return 'files is a list of paths on this machine.';
+        if (v.length > MAX_ARCHIVOS_TABLON)
+            return `At most ${MAX_ARCHIVOS_TABLON} files.`;
+        const out = [];
+        for (const ruta of v) {
+            const leido = d.leerArchivoLocal(ruta);
+            if ('error' in leido)
+                return leido.error;
+            out.push(leido);
+        }
+        const problema = out.length > 0 ? problemaConArchivos(out) : null;
+        return problema ?? out;
+    }
     /** Lo que dice la ficha de esta wallet que es, o null si no es agente. */
     async function miTipo() {
         if (!d.cuenta)
@@ -449,7 +481,9 @@ export function herramientasDelTablon(d) {
                         lineas.push('\nOnly the client and the assigned agent can read the brief.');
                     else {
                         try {
-                            lineas.push(`\nThe brief (checked against its hash on chain):\n\n${await panal.readBoardJobBrief(id)}`);
+                            const brief = await panal.readBoardJobBrief(id);
+                            lineas.push(`\nThe brief (checked against its hash on chain):\n\n${stripFilesManifest(brief)}` +
+                                listaDeArchivos('Files with the job', parseAttachmentsManifest(brief), `Download them with panal_download_board_file job_id ${id} from "job".`));
                         }
                         catch (err) {
                             lineas.push(`\nCould not read the brief: ${fallo(err)}`);
@@ -557,7 +591,12 @@ export function herramientasDelTablon(d) {
                     choose_hours: { type: 'number', description: 'Selection: time to choose after offers close (max 168). Default 24.' },
                     experienced_only: { type: 'boolean', description: 'Only agents at level 1 or higher.' },
                     relist: { type: 'boolean', description: 'If the agent does not deliver, post it again instead of refunding.' },
-                    retry_job_id: { type: 'string', description: 'Only re-send the texts of an already posted job.' },
+                    files: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: `Optional: paths of files on this machine to send with the job (at most ${MAX_ARCHIVOS_TABLON}, 25 MB each, 30 MB in total). Their hashes go inside the brief, so the chain covers them.`,
+                    },
+                    retry_job_id: { type: 'string', description: 'Only re-send the texts (and files) of an already posted job.' },
                     confirmed_by_user: { type: 'boolean', description: 'true only if the person approved posting and paying.' },
                 },
                 required: ['advert', 'brief', 'confirmed_by_user'],
@@ -577,16 +616,22 @@ export function herramientasDelTablon(d) {
                 // Para quién va delante del anuncio, y su hash lo deja fijo. Reintentar
                 // lo vuelve a componer igual, así que hay que pasar la misma audiencia.
                 const anuncio = anuncioPara(audiencia, textoAnuncio);
+                const adjuntos = archivosDeRutas(args.files);
+                if (typeof adjuntos === 'string')
+                    return `Not posted, nothing was spent: ${adjuntos}`;
                 const reintento = args.retry_job_id === undefined ? null : parseJobId(args.retry_job_id);
                 if (args.retry_job_id !== undefined) {
                     if (reintento === null)
                         return 'retry_job_id must be a board job number.';
                     try {
-                        await panal.publishBoardJobTexts(reintento, { anuncio, encargo });
-                        return `Texts of board job #${reintento} are in the mailbox now. Nothing was charged.`;
+                        // El mismo encargo que se hasheó: el texto con los adjuntos anunciados.
+                        const encargoFinal = appendAttachmentsManifest(encargo, adjuntos.map((a) => attachmentFrom(a.name, a.bytes, a.mime)));
+                        await panal.publishBoardJobTexts(reintento, { anuncio, encargo: encargoFinal });
+                        await panal.publishBoardJobFiles(reintento, adjuntos);
+                        return `Texts${adjuntos.length ? ' and files' : ''} of board job #${reintento} are in the mailbox now. Nothing was charged.`;
                     }
                     catch (err) {
-                        return `The mailbox still did not take them: ${fallo(err)}. Nothing was charged. They must be the exact texts that were posted.`;
+                        return `The mailbox still did not take them: ${fallo(err)}. Nothing was charged. They must be the exact texts and files that were posted.`;
                     }
                 }
                 const categoria = categoriaDeTexto(texto(args.category) ?? '');
@@ -616,6 +661,7 @@ export function herramientasDelTablon(d) {
                     ventanaEleccionS: Math.round(horas(args.choose_hours, 24) * 3600),
                     soloConExperiencia: args.experienced_only === true,
                     republicar: args.relist === true,
+                    adjuntos,
                 };
                 const problema = problemaAlPublicar(p);
                 if (problema)
@@ -641,9 +687,9 @@ export function herramientasDelTablon(d) {
                     return [
                         `Posted: board job #${r.jobId}, ${importe(cuanto, moneda)} locked in PanalTablon.`,
                         `  tx: ${tx(r.txHash)}`,
-                        r.textosGuardados
-                            ? `  Advert and brief are in the mailbox.`
-                            : `  WARNING: the texts did NOT reach the mailbox (${r.error}). Call panal_post_board_job again with retry_job_id ${r.jobId} and the same advert and brief: that only re-sends them.`,
+                        r.textosGuardados && r.archivosGuardados
+                            ? `  Advert and brief${adjuntos.length ? ` and ${adjuntos.length} file(s)` : ''} are in the mailbox.`
+                            : `  WARNING: the ${r.textosGuardados ? 'files' : 'texts'} did NOT reach the mailbox (${r.error}). Call panal_post_board_job again with retry_job_id ${r.jobId} and the same advert, brief and files: that only re-sends them.`,
                         modo === ModoTablon.Seleccion
                             ? `Agents can bid for ${duracion(p.ventanaOfertasS)}. Follow it with panal_board_job ${r.jobId}.`
                             : `The first agent that passes the rules takes it. Follow it with panal_board_job ${r.jobId}.`,
@@ -741,7 +787,9 @@ export function herramientasDelTablon(d) {
                     return 'job_id must be a board job number.';
                 try {
                     const entrega = await panal.readBoardJobResult(id);
-                    return `The delivery of board job #${id} (checked against the hash on chain):\n\n${entrega}\n\nApprove with panal_approve_board_job, or dispute with panal_dispute_board_job.`;
+                    return (`The delivery of board job #${id} (checked against the hash on chain):\n\n${stripFilesManifest(entrega)}` +
+                        listaDeArchivos('Delivered files', parseFilesManifest(entrega), `Download them with panal_download_board_file job_id ${id} from "delivery".`) +
+                        '\n\nApprove with panal_approve_board_job, or dispute with panal_dispute_board_job.');
                 }
                 catch (err) {
                     return `Could not read the delivery: ${fallo(err)}`;
@@ -962,7 +1010,9 @@ export function herramientasDelTablon(d) {
                 }
                 try {
                     const brief = await panal.readBoardJobBrief(id);
-                    return `${cabeza}\n\nThe brief (checked against its hash on chain):\n\n${brief}\n\nWhen the work is done, deliver it with panal_deliver_board_job.`;
+                    return (`${cabeza}\n\nThe brief (checked against its hash on chain):\n\n${stripFilesManifest(brief)}` +
+                        listaDeArchivos('Files with the job', parseAttachmentsManifest(brief), `Download them with panal_download_board_file job_id ${id} from "job".`) +
+                        '\n\nWhen the work is done, deliver it with panal_deliver_board_job.');
                 }
                 catch (err) {
                     return `${cabeza}\nBut the brief could not be read yet: ${fallo(err)}\nCalling panal_take_board_job again re-reads it without taking twice.`;
@@ -1036,13 +1086,18 @@ export function herramientasDelTablon(d) {
             name: 'panal_deliver_board_job',
             description: 'As the agent of a board job, deliver the work. The text is left in the board\'s mailbox first, signed ' +
                 'with its hash inside, and only then its hash is anchored in the escrow — so the client can always read ' +
-                'what was anchored. If the mailbox refuses it, nothing is anchored and it can be retried. Only text ' +
-                'travels this way. Costs gas.',
+                'what was anchored. If the mailbox refuses it, nothing is anchored and it can be retried. With files, ' +
+                'they are uploaded first and their hashes go inside the anchored text. Costs gas.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     job_id: { type: 'string', description: 'The board job number.' },
                     result: { type: 'string', description: 'The finished work, exactly as the client will receive it.' },
+                    files: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: `Optional: paths of files on this machine to deliver (at most ${MAX_ARCHIVOS_TABLON}, 25 MB each, 30 MB in total).`,
+                    },
                     confirmed_by_user: { type: 'boolean', description: 'true only if the person approved delivering this.' },
                 },
                 required: ['job_id', 'result', 'confirmed_by_user'],
@@ -1053,15 +1108,18 @@ export function herramientasDelTablon(d) {
                     return no;
                 // Tal cual, sin recortar: lo que se ancla es el hash de estos bytes.
                 const resultado = typeof args.result === 'string' ? args.result : '';
-                if (!resultado.trim())
+                const archivos = archivosDeRutas(args.files);
+                if (typeof archivos === 'string')
+                    return `Nothing was delivered: ${archivos}`;
+                if (!resultado.trim() && archivos.length === 0)
                     return 'result is empty: there is nothing to deliver.';
                 const id = parseJobId(args.job_id);
                 if (id === null)
                     return 'job_id must be a board job number.';
                 try {
-                    const { txHash, resultHash } = await panal.deliverBoardJob(id, resultado);
+                    const { txHash, resultHash } = await panal.deliverBoardJob(id, resultado, archivos);
                     d.log(`entregado del tablón #${id}`);
-                    return (`Board job #${id} delivered.\n  tx: ${tx(txHash)}\n  result hash: ${resultHash}\n\n` +
+                    return (`Board job #${id} delivered${archivos.length ? ` with ${archivos.length} file(s)` : ''}.\n  tx: ${tx(txHash)}\n  result hash: ${resultHash}\n\n` +
                         'The client can now read it and approve. Once approved, the payment is CREDITED in the escrow: ' +
                         'collect it with panal_withdraw. If the client does nothing for 72 h, panal_close_board_job settles it.');
                 }
@@ -1070,6 +1128,51 @@ export function herramientasDelTablon(d) {
                 }
             },
         },
+        {
+            name: 'panal_download_board_file',
+            description: 'Download the files of a board job to this machine, each one checked byte by byte against the hash in ' +
+                'the anchored text: from "job", the files the client sent with it (its client and its agent can); from ' +
+                '"delivery", the files the agent delivered (its client can). Signs a read credential (no transaction, ' +
+                'no money). Files land in MCP_DOWNLOAD_DIR.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    job_id: { type: 'string', description: 'The board job number.' },
+                    from: { type: 'string', description: '"job" (the attachments) or "delivery" (the delivered files).' },
+                    file: { type: 'string', description: 'Optional: the name of one file. Without it, all of them.' },
+                },
+                required: ['job_id', 'from'],
+            },
+            handler: async (args) => {
+                const no = disponible();
+                if (no)
+                    return no;
+                if (!d.cuenta)
+                    return 'Downloading needs this server\'s wallet (MCP_PRIVATE_KEY) to sign: there is none.';
+                const id = parseJobId(args.job_id);
+                if (id === null)
+                    return 'job_id must be a board job number.';
+                const de = texto(args.from)?.toLowerCase() === 'delivery' ? 'entrega' : texto(args.from)?.toLowerCase() === 'job' ? 'adjunto' : null;
+                if (!de)
+                    return 'from is "job" or "delivery".';
+                try {
+                    // El hash sale del texto anclado —encargo o entrega—, nunca del buzón.
+                    const anunciados = de === 'adjunto' ? parseAttachmentsManifest(await panal.readBoardJobBrief(id)) : parseFilesManifest(await panal.readBoardJobResult(id));
+                    const pedido = texto(args.file);
+                    const lista = pedido ? anunciados.filter((f) => f.name === pedido) : anunciados;
+                    if (anunciados.length === 0)
+                        return `Board job #${id} has no files ${de === 'adjunto' ? 'with the job' : 'in its delivery'}.`;
+                    if (lista.length === 0)
+                        return `"${pedido}" is not one of them: ${anunciados.map((f) => f.name).join(', ')}.`;
+                    const bytes = await panal.downloadBoardJobFiles(id, lista, de);
+                    const guardados = lista.map((f, i) => `  ${f.name} (${tamano(f.size)}) → ${d.guardarDescarga(f.name, bytes[i])}`);
+                    return `Downloaded and checked against the hash on chain:\n${guardados.join('\n')}`;
+                }
+                catch (err) {
+                    return `Could not download: ${fallo(err)}`;
+                }
+            },
+        },
     ];
     return { lectura, escritura };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panal-mcp",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Servidor MCP de Panal: busca y contrata agentes de IA on-chain desde Claude",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@panal/sdk": "^0.24.0",
+    "@panal/sdk": "^0.25.0",
     "viem": "^2.21.0"
   },
   "devDependencies": {