create-panal-agent 0.2.0 → 0.4.0

package/dist/i18n.js

@@ -73,6 +73,7 @@ The language is taken from --lang, then PANAL_LANG, then your system locale.`,
         model: 'Your model, if your agent uses one. Any OpenAI-compatible API.',
         rpc: 'Your own RPC, if the public one falls short (it caps at ~15 calls/s).',
         data: 'Where to store delivered results.',
+        x402: 'Charge per call (optional). Leave it empty and your agent only takes escrow jobs.\nThe price is per request, in an EIP-2612 token — it cannot be MON, the scheme needs `permit`.',
     },
     readme: `# {name}
 
@@ -162,6 +163,7 @@ El idioma sale de --lang, luego de PANAL_LANG, y si no del locale del sistema.`,
         model: 'Tu modelo, si tu agente usa uno. Cualquier API compatible con OpenAI.',
         rpc: 'RPC propio, si el público se te queda corto (limita a ~15 llamadas/s).',
         data: 'Dónde guardar los resultados entregados.',
+        x402: 'Cobro por llamada (opcional). Déjalo vacío y tu agente solo acepta encargos del escrow.\nEl precio es por petición, en un token EIP-2612: no puede ser MON, el esquema necesita `permit`.',
     },
     readme: `# {name}
 
@@ -252,6 +254,7 @@ const zh = {
         model: '你的模型（如果代理需要）。任何兼容 OpenAI 的 API 均可。',
         rpc: '你自己的 RPC，当公共节点不够用时（其上限约为每秒 15 次调用）。',
         data: '交付结果的存放位置。',
+        x402: '按次收费（可选）。留空则你的代理只接受托管订单。\n价格按每次请求计算，使用支持 EIP-2612 的代币——不能是 MON，该方案依赖 `permit`。',
     },
     readme: `# {name}
 
@@ -337,6 +340,7 @@ const hi = {
         model: 'आपका मॉडल, अगर एजेंट किसी का उपयोग करता है। OpenAI-संगत कोई भी API।',
         rpc: 'अपना RPC, अगर सार्वजनिक कम पड़े (इसकी सीमा ~15 कॉल/सेकंड है)।',
         data: 'दिए गए परिणाम कहाँ सहेजें।',
+        x402: 'प्रति कॉल शुल्क (वैकल्पिक)। खाली छोड़ें तो आपका एजेंट केवल एस्क्रो वाले काम लेगा।\nकीमत प्रति अनुरोध है, EIP-2612 टोकन में — MON नहीं चल सकता, इस योजना को `permit` चाहिए।',
     },
     readme: `# {name}
 
@@ -426,6 +430,7 @@ const ar = {
         model: 'نموذجك، إن كان وكيلك يستخدم واحدًا. أي واجهة متوافقة مع OpenAI.',
         rpc: 'عقدة RPC خاصة بك، إن لم تكفِ العامة (حدّها نحو 15 طلبًا في الثانية).',
         data: 'مكان حفظ النتائج المُسلَّمة.',
+        x402: 'التحصيل لكل استدعاء (اختياري). اتركه فارغًا فيقبل وكيلك مهام الضمان فقط.\nالسعر لكل طلب، بعملة تدعم EIP-2612 — لا يصلح MON، فالمخطط يحتاج `permit`.',
     },
     readme: `# {name}
 
@@ -514,6 +519,7 @@ La langue vient de --lang, puis de PANAL_LANG, puis de la locale du système.`,
         model: 'Votre modèle, si votre agent en utilise un. Toute API compatible OpenAI.',
         rpc: 'Votre propre RPC, si le public ne suffit pas (limité à ~15 appels/s).',
         data: 'Où stocker les résultats livrés.',
+        x402: "Facturation à l'appel (facultatif). Laissez vide et votre agent ne prend que des missions sous entiercement.\nLe prix est par requête, dans un jeton EIP-2612 : pas de MON, le schéma exige `permit`.",
     },
     readme: `# {name}
 
@@ -606,6 +612,7 @@ O idioma vem de --lang, depois de PANAL_LANG e, por fim, do locale do sistema.`,
         model: 'O seu modelo, se o agente usar um. Qualquer API compatível com OpenAI.',
         rpc: 'RPC próprio, se o público não chegar (limita a ~15 chamadas/s).',
         data: 'Onde guardar os resultados entregues.',
+        x402: 'Cobrança por chamada (opcional). Deixe vazio e o seu agente só aceita trabalhos do escrow.\nO preço é por pedido, num token EIP-2612: não pode ser MON, o esquema precisa de `permit`.',
     },
     readme: `# {name}
 
@@ -696,6 +703,7 @@ const ru = {
         model: 'Ваша модель, если агент её использует. Любой API, совместимый с OpenAI.',
         rpc: 'Свой RPC, если публичного не хватает (лимит ~15 запросов/с).',
         data: 'Где хранить сданные результаты.',
+        x402: 'Плата за вызов (необязательно). Оставьте пустым — агент будет брать только заказы через эскроу.\nЦена за один запрос, в токене с EIP-2612: MON не подходит, схеме нужен `permit`.',
     },
     readme: `# {name}
 
@@ -787,6 +795,7 @@ const bn = {
         model: 'আপনার মডেল, যদি এজেন্ট ব্যবহার করে। OpenAI-সঙ্গতিপূর্ণ যেকোনো API।',
         rpc: 'নিজস্ব RPC, যদি সর্বজনীনটি যথেষ্ট না হয় (সীমা প্রায় ১৫ কল/সেকেন্ড)।',
         data: 'সরবরাহ করা ফলাফল কোথায় রাখা হবে।',
+        x402: 'প্রতি কলে চার্জ (ঐচ্ছিক)। ফাঁকা রাখলে আপনার এজেন্ট কেবল এসক্রো কাজ নেবে।\nদাম প্রতি অনুরোধে, EIP-2612 টোকেনে — MON চলবে না, স্কিমটির `permit` দরকার।',
     },
     readme: `# {name}
 
@@ -875,6 +884,7 @@ const ur = {
         model: 'آپ کا ماڈل، اگر ایجنٹ استعمال کرے۔ OpenAI سے ہم آہنگ کوئی بھی API۔',
         rpc: 'اپنا RPC، اگر عوامی کم پڑ جائے (حد تقریباً 15 کالز فی سیکنڈ)۔',
         data: 'فراہم کردہ نتائج کہاں محفوظ ہوں۔',
+        x402: 'فی کال وصولی (اختیاری)۔ خالی چھوڑ دیں تو آپ کا ایجنٹ صرف ایسکرو کے کام لے گا۔\nقیمت فی درخواست ہے، EIP-2612 ٹوکن میں — MON نہیں چل سکتا، اس اسکیم کو `permit` چاہیے۔',
     },
     readme: `# {name}
 

package/dist/index.js

@@ -163,6 +163,12 @@ function writeEnvExample(dest, t) {
         bloque(t.env.data),
         'DATA_DIR=./data',
         '',
+        bloque(t.env.x402),
+        'X402_PRICE=',
+        '# X402_TOKEN=0x2e2e44e7fa6178822d4397299f719e89d1a67777',
+        '# X402_SYMBOL=$PANAL',
+        '# X402_DESCRIPTION=',
+        '',
     ].join('\n');
     writeFileSync(join(dest, '.env.example'), contenido, 'utf8');
     return contenido;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.2.0",
+  "version": "0.4.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.4.0",
+    "@panal/sdk": "^0.6.0",
     "dotenv": "^17.0.0",
     "tsx": "^4.19.0",
     "viem": "^2.21.0"

package/template/src/agent.ts

@@ -12,24 +12,64 @@
  */
 
 export interface TaskContext {
-  /** El id de la tarea en el escrow, por si quieres registrarlo. */
-  taskId: bigint;
-  /** La dirección del cliente que te contrató. */
+  /**
+   * El id de la tarea en el escrow, o `null` si esto es una llamada x402: ahí
+   * no hay tarea ni plazo, te pagaron en el momento y respondes en el acto.
+   */
+  taskId: bigint | null;
+  /** La dirección del cliente que te contrató (o que acaba de pagarte). */
   client: string;
   /** Cuánto vas a cobrar, en unidades mínimas (wei). */
   amount: bigint;
-  /** Fecha límite de entrega, en segundos epoch. */
+  /** Fecha límite de entrega, en segundos epoch. Cero en una llamada x402. */
   deadline: bigint;
 }
 
+/** Un archivo que entregas junto al texto. */
+export interface TaskFile {
+  /** Cómo se va a llamar. Sin rutas: `informe.pdf`, no `salida/informe.pdf`. */
+  name: string;
+  /** El contenido. Un Buffer/Uint8Array para binario, un string para texto. */
+  data: Uint8Array | string;
+  /** Tipo MIME, si lo sabes: `application/pdf`, `image/png`… */
+  mime?: string;
+}
+
+/**
+ * Lo que devuelve tu agente: un texto, o un texto con archivos.
+ *
+ * Los archivos no viajan a la cadena —no cabrían—, pero SU HASH sí: el motor
+ * lo mete en el texto de la entrega antes de anclarlo. Así el cliente puede
+ * descargarlos y demostrar que son exactamente los que le entregaste. Un
+ * enlace a secas no daría eso: quien lo aloja podría cambiar el archivo
+ * después de cobrar y no habría con qué demostrarlo.
+ */
+export type TaskResult = string | { text: string; files?: TaskFile[] };
+
+/** Cómo se llama esto en los logs: `#31` si viene del escrow, `x402` si no. */
+function etiqueta(ctx: TaskContext): string {
+  return ctx.taskId === null ? 'x402' : `#${ctx.taskId}`;
+}
+
 /**
  * Tu agente.
  *
  * @param brief  El encargo, tal y como lo escribió el cliente.
  * @param ctx    Datos de la tarea, por si te sirven.
- * @returns      El trabajo terminado.
+ * @returns      El trabajo terminado: un texto, o `{ text, files }` si además
+ *               entregas archivos. Por ejemplo:
+ *
+ *                   return {
+ *                     text: 'Aquí tienes el informe que pediste.',
+ *                     files: [{ name: 'informe.pdf', data: pdf, mime: 'application/pdf' }],
+ *                   };
+ *
+ *               No tienes que calcular ningún hash ni servir ninguna descarga:
+ *               de eso se ocupa `server.ts`. Ojo con una cosa, y solo con una:
+ *               si construyes el nombre a partir del encargo, límpialo antes,
+ *               porque lo escribe quien te contrató.
  */
-export async function handleTask(brief: string, ctx: TaskContext): Promise<string> {
+export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskResult> {
   // ──────────────────────────────────────────────────────────────────────────
   // EJEMPLO: un agente que responde con un LLM.
   //
@@ -49,6 +89,65 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<strin
     );
   }
 
+  // Un intento, una revisión y una corrección. Un modelo falla el formato de
+  // vez en cuando, y aquí eso no es un mensaje feo en un chat: el hash de lo
+  // que entregues queda anclado en la cadena y ya no se puede rectificar.
+  let queja: string | null = null;
+  for (let intento = 1; intento <= 2; intento++) {
+    const texto = await pedirAlModelo(brief, apiKey, queja);
+    const problema = revisar(brief, texto);
+    if (!problema) {
+      console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
+      return texto;
+    }
+    console.error(`[agente] ${etiqueta(ctx)} intento ${intento}: ${problema}`);
+    // A la segunda se entrega igual. Tu revisión puede equivocarse, y un falso
+    // positivo no debe costarle al cliente la tarea que ya pagó: es mejor
+    // entregar algo imperfecto y que él decida, que dejarlo sin nada.
+    if (intento === 2) {
+      console.error(`[agente] ${etiqueta(ctx)} se entrega pese a: ${problema}`);
+      return texto;
+    }
+    queja = problema;
+  }
+  throw new Error('inalcanzable');
+}
+
+/**
+ * TU CONTROL DE CALIDAD. Devuelve null si la respuesta vale, o el motivo si no.
+ *
+ * Lo que devuelvas aquí se le manda al modelo en el segundo intento, así que
+ * escribe el motivo como se lo dirías a él: "faltan los puertos 8790 y 8791"
+ * corrige mucho más que "respuesta incompleta".
+ *
+ * Merece la pena rellenarlo con lo que TU agente promete. Un ejemplo real: un
+ * agente que convertía texto a JSON recibió tres registros y devolvió uno,
+ * tirando los otros dos. Era JSON válido, así que ninguna comprobación de
+ * formato se enteró, y el cliente pagó por un tercio de su encargo. Se detectó
+ * comparando los números del encargo con los de la respuesta:
+ *
+ *     const perdidos = [...new Set(brief.match(/\d{2,}/g) ?? [])]
+ *       .filter((n) => !resultado.includes(n));
+ *     if (perdidos.length) return `faltan datos del encargo: ${perdidos.join(', ')}`;
+ *
+ * Ojo: eso vale para un agente que extrae datos, y es un desastre para uno que
+ * resume o traduce, donde descartar cifras es su trabajo. Comprueba lo que tú
+ * prometes, no lo que promete otro.
+ */
+function revisar(brief: string, resultado: string): string | null {
+  if (!resultado.trim()) return 'la respuesta vino vacía';
+
+  // El prompt de abajo prohíbe Markdown, porque ni el dashboard ni Telegram lo
+  // renderizan y el cliente ve los asteriscos en crudo. Pedirlo no basta: hay
+  // que comprobarlo.
+  if (/(\*\*|^#{1,6}\s|```)/m.test(resultado)) {
+    return 'la respuesta lleva Markdown (**, # o ```) y el cliente lo verá en crudo: devuélvela en texto plano';
+  }
+
+  return null;
+}
+
+async function pedirAlModelo(brief: string, apiKey: string, queja: string | null): Promise<string> {
   const res = await fetch(`${process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1'}/chat/completions`, {
     method: 'POST',
     headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
@@ -75,6 +174,9 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<strin
             'RULE 3: deliver finished professional work, with no preamble or meta-commentary.',
         },
         { role: 'user', content: brief },
+        // La corrección va como un mensaje más: decirle QUÉ falló acierta mucho
+        // más que repetirle la misma petición a ciegas esperando otra suerte.
+        ...(queja ? [{ role: 'user' as const, content: `Tu respuesta anterior no vale: ${queja}. Corrígela.` }] : []),
       ],
     }),
   });
@@ -83,7 +185,5 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<strin
   const data = (await res.json()) as { choices?: { message?: { content?: string } }[] };
   const text = data.choices?.[0]?.message?.content?.trim();
   if (!text) throw new Error('El modelo devolvió una respuesta vacía.');
-
-  console.log(`[agente] #${ctx.taskId} resuelta: ${text.length} caracteres`);
   return text;
 }

package/template/src/server.ts

@@ -24,11 +24,25 @@ import 'dotenv/config';
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { createPanalClient, TaskStatus } from '@panal/sdk';
+import {
+  appendFilesManifest,
+  buildQuote,
+  createPanalClient,
+  MAINNET_ADDRESSES,
+  parsePaymentHeader,
+  permitNonce,
+  readPermitDomain,
+  sanitizeFileName,
+  TaskStatus,
+  verifyAndSettle,
+  type DeliveredFile,
+  type PermitDomain,
+} from '@panal/sdk';
 import { privateKeyToAccount } from 'viem/accounts';
-import { keccak256, toBytes, verifyMessage } from 'viem';
+import { isAddress, keccak256, parseEther, toBytes, verifyMessage } from 'viem';
 import type { Address } from 'viem';
 import { handleTask } from './agent.js';
+import type { TaskFile, TaskResult } from './agent.js';
 
 const PORT = Number(process.env.PORT ?? 8787);
 const DATA_DIR = process.env.DATA_DIR ?? './data';
@@ -45,12 +59,66 @@ const panal = createPanalClient({ account, rpcUrl: process.env.RPC_URL });
 
 console.log(`Agente ${account.address} escuchando en :${PORT}`);
 
+// ---------------------------------------------------------------------------
+// x402: cobrar por llamada, sin escrow.
+//
+// El escrow es para encargos que valen algo: bloquea el pago, hay plazo y hay
+// disputa. Para una consulta de dos milésimas todo eso sobra —el trámite cuesta
+// más que el servicio—, y ahí entra x402: el cliente firma una autorización de
+// pago (gratis, sin gas), tú cobras y respondes en la misma llamada.
+//
+// Es OPCIONAL: sin X402_PRICE en el .env, esta ruta no existe y tu agente
+// funciona igual solo con encargos del escrow.
+//
+// Solo se puede cobrar en un ERC-20 con EIP-2612, no en MON: el esquema entero
+// se apoya en `permit`, y la moneda nativa no lo tiene.
+// ---------------------------------------------------------------------------
+
+const X402_PRICE = (() => {
+  const raw = process.env.X402_PRICE?.trim();
+  if (!raw) return null;
+  try {
+    const wei = parseEther(raw);
+    return wei > 0n ? wei : null;
+  } catch {
+    console.error(`X402_PRICE="${raw}" no es un número válido: el cobro por llamada queda desactivado.`);
+    return null;
+  }
+})();
+const X402_TOKEN: Address = (() => {
+  const raw = process.env.X402_TOKEN?.trim();
+  return raw && isAddress(raw) ? (raw as Address) : MAINNET_ADDRESSES.panalToken;
+})();
+const X402_SYMBOL = process.env.X402_SYMBOL?.trim() || '$PANAL';
+// En inglés porque viaja en el 402 y lo lee un desconocido de cualquier parte.
+// Cámbialo por lo tuyo con X402_DESCRIPTION en el .env.
+const X402_DESCRIPTION = process.env.X402_DESCRIPTION?.trim() || 'One question to the agent, answered on the spot.';
+
+if (X402_PRICE !== null) {
+  console.log(`Cobro por llamada activo: ${process.env.X402_PRICE} ${X402_SYMBOL} en POST /x402/ask`);
+}
+
+/**
+ * El dominio EIP-712 del token, leído de la cadena una sola vez.
+ *
+ * Se cachea porque no cambia nunca y leerlo en cada petición añade una llamada
+ * al RPC al camino de una respuesta que cobras al momento. Si el RPC falla, se
+ * vuelve a intentar en la siguiente: no se cachea el error.
+ */
+let dominioCache: PermitDomain | null = null;
+async function dominioPermit(): Promise<PermitDomain> {
+  if (!dominioCache) dominioCache = await readPermitDomain(panal.publicClient, X402_TOKEN);
+  return dominioCache;
+}
+
 // ---------------------------------------------------------------------------
 // Almacén: los resultados en disco, para poder servirlos después.
 // ---------------------------------------------------------------------------
 
 mkdirSync(DATA_DIR, { recursive: true });
 const resultPath = (taskId: bigint) => join(DATA_DIR, `result-${taskId}.txt`);
+/** Carpeta de los archivos de una tarea. Una por tarea, para no mezclarlas. */
+const filesDir = (taskId: bigint) => join(DATA_DIR, 'files', taskId.toString());
 
 function saveResult(taskId: bigint, text: string): void {
   writeFileSync(resultPath(taskId), text, 'utf8');
@@ -63,6 +131,46 @@ function loadResult(taskId: bigint): string | null {
   }
 }
 
+/**
+ * Guarda en disco los archivos de una entrega y devuelve su manifiesto.
+ *
+ * El nombre se limpia con `sanitizeFileName` ANTES de tocar el disco: llega en
+ * lo que devuelve `handleTask`, y un agente que construya el nombre a partir
+ * del encargo del cliente estaría dejando que un desconocido elija dónde
+ * escribir. Un `../../.env` acabaría en la raíz del proyecto.
+ */
+function saveFiles(taskId: bigint, files: TaskFile[]): DeliveredFile[] {
+  const dir = filesDir(taskId);
+  mkdirSync(dir, { recursive: true });
+
+  return files.map((f) => {
+    const name = sanitizeFileName(f.name);
+    const bytes = typeof f.data === 'string' ? new TextEncoder().encode(f.data) : new Uint8Array(f.data);
+    writeFileSync(join(dir, name), bytes);
+    return {
+      name,
+      size: bytes.byteLength,
+      ...(f.mime ? { mime: f.mime } : {}),
+      // El hash de los BYTES, no del enlace: es lo único que sobrevive a que
+      // alguien cambie el archivo después de haber cobrado.
+      hash: keccak256(bytes),
+      path: `/files/${taskId}/${encodeURIComponent(name)}`,
+    };
+  });
+}
+
+/**
+ * Deja lo que devolvió `handleTask` en una forma sola.
+ *
+ * Se acepta un string a secas porque es lo que devuelve el 95 % de los agentes
+ * y obligarles a envolverlo en un objeto sería cobrarles la complejidad de una
+ * función que no usan.
+ */
+function normalizarSalida(salida: TaskResult): { text: string; files: TaskFile[] } {
+  if (typeof salida === 'string') return { text: salida, files: [] };
+  return { text: salida.text, files: salida.files ?? [] };
+}
+
 /** Tareas que se están procesando ahora mismo: evita trabajar dos veces. */
 const inFlight = new Set<string>();
 
@@ -92,13 +200,19 @@ async function work(taskId: bigint, brief: string): Promise<void> {
   inFlight.add(key);
   try {
     const task = await panal.getTask(taskId);
-    const text = await handleTask(brief, {
+    const salida = await handleTask(brief, {
       taskId,
       client: task.client,
       amount: task.amount,
       deadline: task.deadline,
     });
 
+    // Tu handleTask puede devolver un texto a secas —lo normal— o un texto con
+    // 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);
+    const text = 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.
@@ -224,8 +338,125 @@ const server = createServer((req, res) => {
     }
 
     // Tarjeta de presentación: quién eres y qué sabes hacer.
+    //
+    // Si cobras por llamada hay que ANUNCIARLO aquí. Durante meses el bot de
+    // 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') {
-      json(res, 200, { agent: account.address, protocol: 'panal', network: 'monad-mainnet' });
+      json(res, 200, {
+        agent: account.address,
+        protocol: 'panal',
+        network: 'monad-mainnet',
+        ...(X402_PRICE !== null
+          ? {
+              x402Ask: {
+                method: 'POST',
+                path: '/x402/ask',
+                scheme: 'eip2612-permit',
+                asset: X402_TOKEN,
+                assetSymbol: X402_SYMBOL,
+                amount: X402_PRICE.toString(),
+                payTo: account.address,
+                howTo: 'POST {"prompt":"…"} and you get a 402 with the quote. Sign it and repeat with X-Payment.',
+              },
+            }
+          : {}),
+      });
+      return;
+    }
+
+    // ---- Cobro por llamada: pagas y te respondo en el acto ------------------
+    if (url.pathname === '/x402/ask' && req.method === 'POST') {
+      if (X402_PRICE === null) {
+        json(res, 404, { error: 'this agent does not charge per call; hire it through the escrow' });
+        return;
+      }
+      const body = JSON.parse(await readBody(req)) as { prompt?: string };
+      const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
+      if (!prompt || prompt.length > 2000) {
+        json(res, 400, { error: 'prompt required, max 2000 characters' });
+        return;
+      }
+
+      const domain = await dominioPermit();
+      const pagoCrudo = req.headers['x-payment'];
+
+      // Sin pago: se responde 402 con el presupuesto. Este es el paso que le da
+      // por fin sentido a un código de estado que llevaba desde los noventa
+      // reservado y sin usar, porque no había forma de pagar en la web.
+      if (typeof pagoCrudo !== 'string' || !pagoCrudo.trim()) {
+        // Si el cliente dice quién es, se le regala su nonce y se ahorra una
+        // consulta a la cadena antes de poder firmar.
+        const quien = req.headers['x-payment-payer'];
+        const payer = typeof quien === 'string' && isAddress(quien) ? (quien as Address) : null;
+        const nonce = payer ? await permitNonce(panal.publicClient, X402_TOKEN, payer).catch(() => undefined) : undefined;
+
+        res.setHeader('www-authenticate', `eip2612-permit realm="panal", chain="${domain.chainId}"`);
+        json(
+          res,
+          402,
+          buildQuote({
+            asset: X402_TOKEN,
+            assetSymbol: X402_SYMBOL,
+            amount: X402_PRICE,
+            payTo: account.address,
+            resource: '/x402/ask',
+            description: X402_DESCRIPTION,
+            domain,
+            payerNonce: nonce,
+          }),
+        );
+        return;
+      }
+
+      const leido = parsePaymentHeader(pagoCrudo);
+      if (!leido.ok) {
+        json(res, 400, { error: leido.error });
+        return;
+      }
+
+      // SE COBRA ANTES DE SERVIR. Si se sirviera primero y el cobro fallara, el
+      // trabajo estaría regalado y no habría forma de recuperarlo.
+      const cobro = await verifyAndSettle(
+        { publicClient: panal.publicClient, walletClient: panal.walletClient ?? null, token: X402_TOKEN, domain, payee: account.address },
+        leido.payment,
+        X402_PRICE,
+      );
+      if (!cobro.ok) {
+        json(res, cobro.status, { error: cobro.error });
+        return;
+      }
+      console.log(`[x402] cobrado ${cobro.amount} de ${leido.payment.payer} · tx ${cobro.txHash}`);
+
+      // Ya está cobrado: pase lo que pase a partir de aquí, hay que responder
+      // algo. Si el modelo revienta, se dice; callarse sería quedarse el dinero.
+      try {
+        const salida = await handleTask(prompt, {
+          taskId: null,
+          client: leido.payment.payer,
+          amount: cobro.amount,
+          deadline: 0n,
+        });
+        // En una llamada x402 no hay tarea, así que no hay nada que anclar ni
+        // ninguna firma con la que proteger una descarga: los archivos no
+        // tienen dónde agarrarse. Se responde el texto y se avisa en el log en
+        // vez de callarlo, que si no el autor busca el fallo donde no está.
+        const { text: answer, files } = normalizarSalida(salida);
+        if (files.length) {
+          console.error(
+            `[x402] tu handleTask devolvió ${files.length} archivo(s) y una llamada x402 no puede entregarlos: ` +
+              'no hay tarea que los ancle ni firma que proteja la descarga. Solo va el texto.',
+          );
+        }
+        res.setHeader('x-payment-tx', cobro.txHash);
+        json(res, 200, { answer, paid: { txHash: cobro.txHash, amount: cobro.amount.toString(), asset: X402_TOKEN } });
+      } catch (err) {
+        console.error(`[x402] cobrado pero falló al responder: ${err instanceof Error ? err.message : err}`);
+        json(res, 502, {
+          error: 'the payment went through but the agent could not answer',
+          paid: { txHash: cobro.txHash, amount: cobro.amount.toString() },
+        });
+      }
       return;
     }
 
@@ -327,6 +558,60 @@ const server = createServer((req, res) => {
       return;
     }
 
+    // ---- El cliente se baja los archivos de su entrega ----------------------
+    //
+    // Se protege igual que el resultado, y con LA MISMA firma: `Panal resultado
+    // #<id>` abre el texto y todos sus archivos. Firmar una vez por archivo
+    // sería pedirle al cliente cuatro firmas por una entrega de cuatro PDFs.
+    const archivo = /^\/files\/(\d+)\/([^/]+)$/.exec(url.pathname);
+    if (archivo && req.method === 'GET') {
+      const taskId = BigInt(archivo[1]!);
+      const address = url.searchParams.get('address');
+      const signature = url.searchParams.get('signature');
+      if (!address || !signature) {
+        json(res, 400, { error: 'faltan address y signature' });
+        return;
+      }
+      const task = await panal.getTask(taskId);
+      if (address.toLowerCase() !== task.client.toLowerCase()) {
+        json(res, 403, { error: 'solo el cliente de la tarea puede descargar sus archivos' });
+        return;
+      }
+      if (!(await signedBy(resultSignMessage(taskId), signature, task.client))) {
+        json(res, 401, { error: 'firma inválida' });
+        return;
+      }
+
+      // El nombre viene de la URL, o sea de fuera: se limpia igual que al
+      // escribirlo. Sin esto, `/files/31/..%2F..%2F.env` leería el .env.
+      let nombre: string;
+      try {
+        nombre = sanitizeFileName(decodeURIComponent(archivo[2]!));
+      } catch {
+        json(res, 400, { error: 'nombre de archivo inválido' });
+        return;
+      }
+
+      let bytes: Buffer;
+      try {
+        bytes = readFileSync(join(filesDir(taskId), nombre));
+      } catch {
+        json(res, 404, { error: 'esa tarea no tiene ese archivo' });
+        return;
+      }
+
+      res.writeHead(200, {
+        'content-type': 'application/octet-stream',
+        'content-length': bytes.byteLength,
+        // `attachment` a propósito: lo que hay dentro lo eligió el agente, y no
+        // se le deja que el navegador del cliente lo ejecute como una página.
+        'content-disposition': `attachment; filename="${nombre}"`,
+        'x-content-type-options': 'nosniff',
+      });
+      res.end(bytes);
+      return;
+    }
+
     json(res, 404, { error: 'no existe' });
   })().catch((err) => {
     console.error(`[http] ${err instanceof Error ? err.message : err}`);