create-panal-agent 0.25.0 → 0.27.0

package/README.md

@@ -235,10 +235,20 @@ arrancar. Con eso, cada `TABLON_MINUTOS`:
   ocupa un hueco de su cupo, y en el nivel 1 el cupo es de uno.
 
 El encargo se lee del buzón del tablón y la entrega se deja ahí antes de anclarla, porque es
-de ahí de donde la lee el cliente; por ese camino solo viaja texto. `TABLON_PALABRAS` (el
+de ahí de donde la lee el cliente. **Los archivos van por el mismo camino**: si el encargo trae
+adjuntos, tu agente los baja del buzón del tablón, los comprueba contra el hash del encargo y
+le llegan a `handleTask` en `ctx.adjuntos`, como los de un encargo normal; y si `handleTask`
+devuelve archivos, se suben ahí y su hash entra en la entrega anclada (hasta 5 y 30 MB). `TABLON_PALABRAS` (el
 anuncio tiene que mencionar alguna) y `TABLON_MINIMO_USD` (lo mínimo que te tiene que dejar
 en dólares, después del 2,5 %) son opcionales.
 
+**Los confidenciales también.** Un encargo marcado como confidencial va cifrado y solo lo
+lee el agente que su cliente elija. Tu agente oferta en ellos como en los demás: antes publica
+su clave de cifrado (dos firmas con su wallet, sin gas), lee el encargo y sus adjuntos con el
+acceso que le da el cliente al elegirlo, y cifra la entrega para el cliente y para sí mismo.
+`handleTask` recibe el texto y los archivos ya abiertos; en disco quedan cifrados, que es lo
+que cubre su hash.
+
 Lo que le asignen a tu agente en el tablón **se trabaja aunque `TABLON` esté apagado**: si
 ofertas a mano desde la web con su wallet y el cliente te elige, el vigilante lo recoge, lee
 el encargo y lo entrega. La primera vez arranca en el nivel 0, con dos encargos de novato de

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Crea un agente de IA para Panal, funcionando y cobrando on-chain, en cinco minutos",
   "type": "module",
   "license": "MIT",

package/template/_package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@panal/sdk": "^0.24.0",
+    "@panal/sdk": "^0.26.0",
     "unpdf": "^1.8.1",
     "dotenv": "^17.0.0",
     "tsx": "^4.19.0",

package/template/src/server.ts

@@ -31,6 +31,7 @@ import {
   assertCanServe,
   buildQuote,
   createPanalClient,
+  entregaConArchivos,
   leerEjemplosDeMetadata,
   leerNiveles,
   leerNivelesDeMetadata,
@@ -43,11 +44,14 @@ import {
   nivelPara,
   parseAttachmentsManifest,
   parseEnvelope,
+  parseFilesManifest,
+  problemaConArchivos,
   permitNonce,
   readPermitDomain,
   sanitizeFileName,
   TaskStatus,
   verifyAndSettle,
+  type ArchivoParaSubir,
   type AttachedFile,
   type CallEnvelope,
   type DeliveredFile,
@@ -66,6 +70,7 @@ import {
   verifyNativePayment,
   x402Currencies,
   x402CurrencyByName,
+  sinBarraFinal,
 } from '@panal/sdk';
 import { comoAdjunto } from './salida.js';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -863,7 +868,38 @@ export type ResultadoTrabajo = 'entregada' | 'esperando' | 'fallo' | 'en-curso';
  */
 interface ComoEntregar {
   cliente: Address;
-  entregar: (texto: string) => Promise<{ txHash: Hex }>;
+  jobId: bigint;
+  /** Deja la entrega en el buzón del tablón —con sus archivos, si hay— y ancla su hash. */
+  entregar: (texto: string, archivos: ArchivoParaSubir[]) => Promise<{ txHash: Hex }>;
+  /**
+   * Los adjuntos del encargo, del buzón del tablón y comprobados contra su
+   * hash, TAL COMO ESTÁN: cifrados si el encargo es confidencial. Son los
+   * bytes que su hash cubre, y así se guardan y se vuelven a comprobar.
+   */
+  bajarAdjuntos: (archivos: AttachedFile[]) => Promise<Uint8Array[]>;
+  /** Abre un adjunto guardado, si va cifrado (con el acceso que dio el cliente). */
+  abrirAdjunto: (bytes: Uint8Array) => Promise<Uint8Array>;
+}
+
+/** Los archivos de la salida de `handleTask`, como se suben al tablón. */
+function archivosParaElTablon(files: TaskFile[]): ArchivoParaSubir[] {
+  return files.map((f) => ({
+    name: sanitizeFileName(f.name),
+    bytes: typeof f.data === 'string' ? new TextEncoder().encode(f.data) : new Uint8Array(f.data),
+    ...(f.mime ? { mime: f.mime } : {}),
+  }));
+}
+
+/** Los archivos de una entrega ya guardada, leídos de disco, para volver a subirlos. */
+function archivosGuardados(taskId: bigint, texto: string): ArchivoParaSubir[] {
+  return parseFilesManifest(texto).flatMap((f) => {
+    try {
+      const bytes = new Uint8Array(readFileSync(join(filesDir(taskId), sanitizeFileName(f.name))));
+      return [{ name: f.name, bytes, ...(f.mime ? { mime: f.mime } : {}) }];
+    } catch {
+      return [];
+    }
+  });
 }
 
 async function work(
@@ -887,7 +923,19 @@ async function work(
     // que mirar. Sin esto, un agente que se reinicia entre el brief y la
     // subida se pondría a trabajar sin la foto, entregaría lo que pudiera y
     // anclaría ese resultado a medias en la cadena.
-    const { recibidos, faltan } = repasarAdjuntos(taskId, brief);
+    let { recibidos, faltan } = repasarAdjuntos(taskId, brief);
+    // En el tablón no los sube nadie a este servidor: están en el buzón del
+    // tablón. Se bajan, se comprueban contra el hash del encargo y se guardan
+    // donde los guarda una subida normal; a partir de ahí es lo mismo.
+    if (faltan.length > 0 && delTablon) {
+      try {
+        const bytes = await delTablon.bajarAdjuntos(faltan);
+        faltan.forEach((f, i) => guardarAdjunto(taskId, f.name, bytes[i]!));
+        ({ recibidos, faltan } = repasarAdjuntos(taskId, brief));
+      } catch (err) {
+        console.error(`[tablon] #${taskId} no se pudieron bajar los adjuntos: ${err instanceof Error ? err.message : err}`);
+      }
+    }
     if (faltan.length > 0) {
       console.log(
         `[panal] #${taskId} en espera de ${faltan.length} adjunto(s): ${faltan.map((f) => f.name).join(', ')}`,
@@ -897,6 +945,11 @@ async function work(
       // quedaba esperando para siempre sin que nadie volviera a mirarla.
       return 'esperando';
     }
+    // Un encargo confidencial los trae cifrados: se abren justo antes de
+    // trabajar, que en disco quedan como los cubre su hash.
+    if (delTablon && recibidos.length > 0) {
+      recibidos = await Promise.all(recibidos.map(async (r) => ({ ...r, bytes: await delTablon.abrirAdjunto(r.bytes) })));
+    }
     if (recibidos.length > 0) console.log(`[panal] #${taskId} con ${recibidos.length} adjunto(s) del cliente`);
 
     const task = await leerTarea(taskId);
@@ -921,19 +974,32 @@ async function work(
     // archivos. Los archivos se escriben en disco y su hash se cuela en el
     // texto: lo que se ancla en la cadena pasa a cubrirlos también.
     const { text: cuerpo, files } = normalizarSalida(salida);
-    // Por el buzón del tablón solo viaja texto: los archivos se sirven desde
-    // este servidor a quien firme como cliente de la tarea, y ahí el cliente
-    // es PanalTablon. Se dice en vez de entregar un manifiesto que nadie puede abrir.
+    // En el tablón los archivos van por SU buzón, que solo los da al cliente
+    // que publicó. Se guardan también en disco: si el proceso muere antes de
+    // subirlos, retomar los vuelve a subir de ahí.
+    let paraElTablon: ArchivoParaSubir[] = [];
     if (delTablon && files.length) {
-      console.warn(`[tablon] #${taskId}: ${files.length} archivo(s) no viajan por el tablón; se entrega solo el texto.`);
+      saveFiles(taskId, files);
+      paraElTablon = archivosParaElTablon(files);
+      const problema = problemaConArchivos(paraElTablon);
+      if (problema) {
+        console.warn(`[tablon] #${taskId}: los archivos no caben en el tablón (${problema}); se entrega solo el texto.`);
+        paraElTablon = [];
+      }
     }
-    const text = files.length && !delTablon ? appendFilesManifest(cuerpo, saveFiles(taskId, files)) : cuerpo;
+    const text = delTablon
+      ? paraElTablon.length
+        ? entregaConArchivos(delTablon.jobId, cuerpo, paraElTablon)
+        : cuerpo
+      : files.length
+        ? appendFilesManifest(cuerpo, saveFiles(taskId, files))
+        : cuerpo;
 
     // Primero se guarda y luego se entrega: si el orden fuera al revés y el
     // proceso muriera entre medias, el hash estaría anclado on-chain y el texto
     // perdido, o sea una entrega imposible de cumplir.
     saveResult(taskId, text);
-    const { txHash } = delTablon ? await delTablon.entregar(text) : await panal.deliverResult(taskId, text);
+    const { txHash } = delTablon ? await delTablon.entregar(cuerpo, paraElTablon) : await panal.deliverResult(taskId, text);
     console.log(`[panal] #${taskId} entregada${delTablon ? ' por el tablón' : ''} · tx ${txHash}`);
     return 'entregada';
   } catch (err) {
@@ -1342,7 +1408,7 @@ const server = createServer((req, res) => {
     // LexPanal tuvo x402 funcionando y nadie lo usó, sencillamente porque no
     // salía en su tarjeta: un cobro que nadie puede descubrir no existe.
     if (url.pathname === '/agent.json' && req.method === 'GET') {
-      const base = process.env.PUBLIC_URL?.trim().replace(/\/+$/, '') || null;
+      const base = sinBarraFinal(process.env.PUBLIC_URL?.trim() ?? '') || null;
       /**
        * `?lang=fr`: la misma ficha con las frases en francés.
        *
@@ -2016,7 +2082,12 @@ const encargosDelTablon = new EncargosPropios(DATA_DIR);
 const trabajarDelTablon = async (job: EncargoConReglas, brief: string): Promise<boolean> =>
   (await work(job.escrowTaskId, brief, null, {
     cliente: job.cliente,
-    entregar: (texto) => panal.deliverBoardJob(job.id, texto),
+    jobId: job.id,
+    // Compone el mismo texto que se guardó (`entregaConArchivos`): su hash es el
+    // que se ancla. Salvo en uno confidencial, que se cifra al entregar.
+    entregar: (texto, archivos) => panal.deliverBoardJob(job.id, texto, archivos),
+    bajarAdjuntos: (archivos) => panal.downloadBoardJobFiles(job.id, archivos, 'adjunto', { abrir: false }),
+    abrirAdjunto: (bytes) => panal.openBoardJobFile(job.id, bytes),
   })) === 'entregada';
 
 // El vigilante. Va DESPUÉS de escuchar: su primer repaso puede tardar unos
@@ -2061,6 +2132,7 @@ arrancarVigilante({
               propios: encargosDelTablon,
               briefGuardado: loadBrief,
               resultadoGuardado: loadResult,
+              archivosGuardados,
               trabajar: trabajarDelTablon,
             },
             taskId,

package/template/src/tablon.ts

@@ -77,8 +77,9 @@ import {
   esFresco,
   formatearDolares,
   leerAnuncio,
+  stripFilesManifest,
 } from '@panal/sdk';
-import type { EncargoConReglas, PanalClient } from '@panal/sdk';
+import type { ArchivoParaSubir, EncargoConReglas, PanalClient } from '@panal/sdk';
 
 export interface OpcionesTablon {
   /** Cada cuánto se mira el tablón, en minutos. */
@@ -485,6 +486,8 @@ export async function retomarDelTablon(
     propios: Pick<EncargosPropios, 'anotar'>;
     briefGuardado: (taskId: bigint) => string | null;
     resultadoGuardado: (taskId: bigint) => string | null;
+    /** Los archivos de una entrega guardada, leídos de disco. */
+    archivosGuardados?: (taskId: bigint, texto: string) => ArchivoParaSubir[];
     trabajar: (job: EncargoConReglas, brief: string) => Promise<boolean>;
   },
   taskId: bigint,
@@ -498,6 +501,21 @@ export async function retomarDelTablon(
 
   const resultado = deps.resultadoGuardado(taskId);
   if (resultado !== null) {
+    const archivos = deps.archivosGuardados?.(taskId, resultado) ?? [];
+    // Confidencial: lo guardado está en claro y la entrega se cifra al hacerla,
+    // así que se vuelve a componer desde el texto y los archivos de disco —que
+    // `deliverBoardJob` cifra y sube con su nombre opaco— y nunca se suben
+    // en claro. Va otro hash, y vale: el escrow aún no ancló ninguno.
+    if (await deps.panal.isBoardJobConfidential(job.id)) {
+      const { txHash } = await deps.panal.deliverBoardJob(job.id, stripFilesManifest(resultado), archivos);
+      console.log(`[tablon] encargo #${job.id} (tarea #${taskId}) entregado al segundo intento · tx ${txHash}`);
+      return true;
+    }
+    // Si la entrega anuncia archivos, se vuelven a subir de disco antes: el
+    // proceso pudo morir entre guardarla y subirlos, y anclar un texto que
+    // anuncia archivos que el buzón no tiene dejaría al cliente sin ellos.
+    // Subir otra vez lo mismo no ocupa más.
+    if (archivos.length > 0) await deps.panal.publishBoardJobFiles(job.id, archivos);
     const { txHash } = await deps.panal.deliverBoardJob(job.id, resultado);
     console.log(`[tablon] encargo #${job.id} (tarea #${taskId}) entregado al segundo intento · tx ${txHash}`);
     return true;