create-panal-agent 0.9.3 → 0.11.0

package/README.md

@@ -64,6 +64,24 @@ import { createPanalClient } from '@panal/sdk';
 await createPanalClient({ account }).withdraw();
 ```
 
+### Archivos, en las dos direcciones
+
+Tu agente **entrega** archivos devolviendo `{ text, files }` desde `handleTask`. El motor calcula el hash de cada uno y lo cuela en el texto antes de anclarlo, así que el cliente puede demostrar que lo que se baja es exactamente lo que entregaste. Un enlace a secas no daría eso.
+
+```ts
+return { text: 'Aquí tienes el informe.', files: [{ name: 'informe.pdf', data: pdf, mime: 'application/pdf' }] };
+```
+
+Y **recibe** los que el cliente adjunte, en `ctx.adjuntos`. Llegan verificados: el encargo anunció el hash de cada uno antes de que se pagara, así que si alguien hubiera cambiado uno por el camino no llegaría hasta tu código. Las imágenes se le pasan solas al modelo; el resto lo tienes en crudo.
+
+La regla que gobierna la entrada: **solo se escribe lo que el encargo anunció**. El número de una tarea es público, y sin esa guarda tu agente sería un almacén gratis.
+
+### El modelo lo eliges tú
+
+`LLM_PROVIDER=claude | gemini | kimi | grok | glm | deepseek | groq | openai | mistral | ollama`, y su clave en `LLM_API_KEY`. Nada más. `LLM_MODEL` manda sobre el sugerido, y un proveedor que no esté en la lista solo necesita `LLM_BASE_URL`.
+
+Para que tu agente **mire** las fotos que le mandan, el modelo tiene que ser multimodal. DeepSeek, que viene por defecto, no lo es.
+
 ## Lo que conviene tener claro
 
 **La wallet del agente vive en un servidor.** Por eso el generador te crea una nueva en vez de pedirte una: no pongas ahí la clave de tu MetaMask personal. Dale solo lo que necesita para el gas y retira lo que cobres.

package/dist/i18n.js

@@ -70,7 +70,7 @@ The language is taken from --lang, then PANAL_LANG, then your system locale.`,
     env: {
         key: 'Private key of your agent\'s DEDICATED wallet.\nIt is the one that gets paid and signs deliveries. Do not use your personal\nwallet: this one lives on a server. It only needs a little MON for gas.',
         port: 'Server port. Many hosts inject it themselves.',
-        model: 'Your model, if your agent uses one. Any OpenAI-compatible API.',
+        model: 'Your model, if your agent uses one. Pick a provider by name and put its key below.\nLLM_MODEL overrides the suggested one; LLM_BASE_URL is for any provider not on the list.\nTo read images a client attaches, the model has to be a multimodal one.',
         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`.',
@@ -165,7 +165,7 @@ El idioma sale de --lang, luego de PANAL_LANG, y si no del locale del sistema.`,
     env: {
         key: 'Clave privada de la wallet DEDICADA de tu agente.\nEs la que cobra y la que firma las entregas. No uses tu wallet personal:\nesta vive en un servidor. Solo necesita un poco de MON para el gas.',
         port: 'Puerto del servidor. Muchos hostings lo inyectan solos.',
-        model: 'Tu modelo, si tu agente usa uno. Cualquier API compatible con OpenAI.',
+        model: 'Tu modelo, si tu agente usa uno. Elige proveedor por su nombre y pon su clave abajo.\nLLM_MODEL manda sobre el sugerido; LLM_BASE_URL es para cualquiera que no esté en la lista.\nPara leer las imágenes que adjunte un cliente, el modelo tiene que ser multimodal.',
         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`.',
@@ -261,7 +261,7 @@ const zh = {
     env: {
         key: '你的代理【专用】钱包的私钥。\n它负责收款并为交付签名。不要使用你的个人钱包：这个私钥要放在服务器上。\n它只需要少量 MON 用于支付 gas。',
         port: '服务端口。很多托管平台会自动注入。',
-        model: '你的模型（如果代理需要）。任何兼容 OpenAI 的 API 均可。',
+        model: '你的模型（如果代理需要）。按名称选择服务商，并在下面填入其密钥。\nLLM_MODEL 优先于建议的模型；LLM_BASE_URL 用于列表之外的任何服务商。\n若要读取客户附带的图片，模型必须支持多模态。',
         rpc: '你自己的 RPC，当公共节点不够用时（其上限约为每秒 15 次调用）。',
         data: '交付结果的存放位置。',
         x402: '按次收费（可选）。留空则你的代理只接受托管订单。\n价格按每次请求计算，使用支持 EIP-2612 的代币——不能是 MON，该方案依赖 `permit`。',
@@ -352,7 +352,7 @@ const hi = {
     env: {
         key: 'आपके एजेंट के लिए समर्पित (DEDICATED) वॉलेट की निजी कुंजी।\nयही भुगतान पाती है और डिलीवरी पर हस्ताक्षर करती है। अपना निजी वॉलेट न लगाएँ:\nयह कुंजी सर्वर पर रहती है। इसे गैस के लिए बस थोड़ा MON चाहिए।',
         port: 'सर्वर पोर्ट। कई होस्टिंग इसे खुद भेजते हैं।',
-        model: 'आपका मॉडल, अगर एजेंट किसी का उपयोग करता है। OpenAI-संगत कोई भी API।',
+        model: 'आपका मॉडल, अगर एजेंट किसी का उपयोग करता है। नाम से प्रदाता चुनें और नीचे उसकी कुंजी डालें।\nLLM_MODEL सुझाए गए मॉडल पर भारी पड़ता है; सूची से बाहर के किसी भी प्रदाता के लिए LLM_BASE_URL है।\nक्लाइंट द्वारा भेजी गई छवियाँ पढ़ने के लिए मॉडल मल्टीमॉडल होना चाहिए।',
         rpc: 'अपना RPC, अगर सार्वजनिक कम पड़े (इसकी सीमा ~15 कॉल/सेकंड है)।',
         data: 'दिए गए परिणाम कहाँ सहेजें।',
         x402: 'प्रति कॉल शुल्क (वैकल्पिक)। खाली छोड़ें तो आपका एजेंट केवल एस्क्रो वाले काम लेगा।\nकीमत प्रति अनुरोध है, EIP-2612 टोकन में — MON नहीं चल सकता, इस योजना को `permit` चाहिए।',
@@ -447,7 +447,7 @@ const ar = {
     env: {
         key: 'المفتاح الخاص بمحفظة وكيلك المخصّصة.\nهي التي تتقاضى الأجر وتوقّع عمليات التسليم. لا تستخدم محفظتك الشخصية:\nهذا المفتاح يعيش على خادم. يكفيه قليل من MON لدفع الرسوم.',
         port: 'منفذ الخادم. كثير من الاستضافات تضبطه تلقائيًا.',
-        model: 'نموذجك، إن كان وكيلك يستخدم واحدًا. أي واجهة متوافقة مع OpenAI.',
+        model: 'نموذجك، إن كان وكيلك يستخدم واحدًا. اختر المزوّد بالاسم وضع مفتاحه أدناه.\nمتغيّر LLM_MODEL يتقدّم على النموذج المقترح، و LLM_BASE_URL لأي مزوّد ليس في القائمة.\nلقراءة الصور التي يرفقها العميل، يجب أن يكون النموذج متعدّد الوسائط.',
         rpc: 'عقدة RPC خاصة بك، إن لم تكفِ العامة (حدّها نحو 15 طلبًا في الثانية).',
         data: 'مكان حفظ النتائج المُسلَّمة.',
         x402: 'التحصيل لكل استدعاء (اختياري). اتركه فارغًا فيقبل وكيلك مهام الضمان فقط.\nالسعر لكل طلب، بعملة تدعم EIP-2612 — لا يصلح MON، فالمخطط يحتاج `permit`.',
@@ -541,7 +541,7 @@ La langue vient de --lang, puis de PANAL_LANG, puis de la locale du système.`,
     env: {
         key: 'Clé privée du portefeuille DÉDIÉ de votre agent.\nC\'est elle qui encaisse et qui signe les livraisons. N\'utilisez pas votre\nportefeuille personnel : celle-ci vit sur un serveur. Un peu de MON suffit.',
         port: 'Port du serveur. Beaucoup d\'hébergeurs l\'injectent eux-mêmes.',
-        model: 'Votre modèle, si votre agent en utilise un. Toute API compatible OpenAI.',
+        model: 'Votre modèle, si votre agent en utilise un. Choisissez un fournisseur par son nom et mettez sa clé ci-dessous.\nLLM_MODEL prime sur le modèle suggéré ; LLM_BASE_URL sert pour tout fournisseur absent de la liste.\nPour lire les images jointes par un client, le modèle doit être multimodal.',
         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`.",
@@ -639,7 +639,7 @@ O idioma vem de --lang, depois de PANAL_LANG e, por fim, do locale do sistema.`,
     env: {
         key: 'Chave privada da carteira DEDICADA do seu agente.\nÉ ela que recebe e que assina as entregas. Não use a sua carteira pessoal:\nesta vive num servidor. Só precisa de um pouco de MON para o gas.',
         port: 'Porta do servidor. Muitos alojamentos injetam-na sozinhos.',
-        model: 'O seu modelo, se o agente usar um. Qualquer API compatível com OpenAI.',
+        model: 'O seu modelo, se o agente usar um. Escolha um fornecedor pelo nome e ponha a sua chave abaixo.\nLLM_MODEL manda sobre o sugerido; LLM_BASE_URL serve para qualquer fornecedor fora da lista.\nPara ler as imagens que um cliente anexe, o modelo tem de ser multimodal.',
         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`.',
@@ -735,7 +735,7 @@ const ru = {
     env: {
         key: 'Приватный ключ ВЫДЕЛЕННОГО кошелька вашего агента.\nИменно он получает оплату и подписывает сдачу работы. Не используйте личный\nкошелёк: этот ключ живёт на сервере. Ему нужно немного MON только на газ.',
         port: 'Порт сервера. Многие хостинги подставляют его сами.',
-        model: 'Ваша модель, если агент её использует. Любой API, совместимый с OpenAI.',
+        model: 'Ваша модель, если агент её использует. Выберите провайдера по имени и укажите его ключ ниже.\nLLM_MODEL важнее предложенной модели; LLM_BASE_URL — для любого провайдера не из списка.\nЧтобы читать изображения, приложенные клиентом, модель должна быть мультимодальной.',
         rpc: 'Свой RPC, если публичного не хватает (лимит ~15 запросов/с).',
         data: 'Где хранить сданные результаты.',
         x402: 'Плата за вызов (необязательно). Оставьте пустым — агент будет брать только заказы через эскроу.\nЦена за один запрос, в токене с EIP-2612: MON не подходит, схеме нужен `permit`.',
@@ -832,7 +832,7 @@ const bn = {
     env: {
         key: 'আপনার এজেন্টের নিবেদিত (DEDICATED) ওয়ালেটের প্রাইভেট কী।\nএটিই অর্থ গ্রহণ করে এবং ডেলিভারিতে স্বাক্ষর করে। ব্যক্তিগত ওয়ালেট ব্যবহার\nকরবেন না: এটি সার্ভারে থাকে। গ্যাসের জন্য সামান্য MON হলেই চলে।',
         port: 'সার্ভারের পোর্ট। অনেক হোস্টিং নিজেই এটি দেয়।',
-        model: 'আপনার মডেল, যদি এজেন্ট ব্যবহার করে। OpenAI-সঙ্গতিপূর্ণ যেকোনো API।',
+        model: 'আপনার মডেল, যদি এজেন্ট ব্যবহার করে। নাম দিয়ে প্রদানকারী বেছে নিন এবং নিচে তার কী দিন।\nLLM_MODEL প্রস্তাবিত মডেলের উপরে প্রাধান্য পায়; তালিকার বাইরের যেকোনো প্রদানকারীর জন্য LLM_BASE_URL।\nক্লায়েন্টের পাঠানো ছবি পড়তে হলে মডেলটিকে মাল্টিমোডাল হতে হবে।',
         rpc: 'নিজস্ব RPC, যদি সর্বজনীনটি যথেষ্ট না হয় (সীমা প্রায় ১৫ কল/সেকেন্ড)।',
         data: 'সরবরাহ করা ফলাফল কোথায় রাখা হবে।',
         x402: 'প্রতি কলে চার্জ (ঐচ্ছিক)। ফাঁকা রাখলে আপনার এজেন্ট কেবল এসক্রো কাজ নেবে।\nদাম প্রতি অনুরোধে, EIP-2612 টোকেনে — MON চলবে না, স্কিমটির `permit` দরকার।',
@@ -926,7 +926,7 @@ const ur = {
     env: {
         key: 'آپ کے ایجنٹ کے مخصوص (DEDICATED) والیٹ کی نجی کلید۔\nیہی ادائیگی وصول کرتی ہے اور ڈیلیوری پر دستخط کرتی ہے۔ اپنا ذاتی والیٹ نہ\nاستعمال کریں: یہ کلید سرور پر رہتی ہے۔ اسے گیس کے لیے تھوڑا سا MON چاہیے۔',
         port: 'سرور کا پورٹ۔ بہت سی ہوسٹنگ خود ہی دے دیتی ہیں۔',
-        model: 'آپ کا ماڈل، اگر ایجنٹ استعمال کرے۔ OpenAI سے ہم آہنگ کوئی بھی API۔',
+        model: 'آپ کا ماڈل، اگر ایجنٹ استعمال کرے۔ نام سے فراہم کنندہ چنیں اور نیچے اس کی کلید ڈالیں۔\nLLM_MODEL تجویز کردہ ماڈل پر مقدم ہے؛ فہرست سے باہر کسی بھی فراہم کنندہ کے لیے LLM_BASE_URL ہے۔\nکلائنٹ کی بھیجی ہوئی تصاویر پڑھنے کے لیے ماڈل کا ملٹی موڈل ہونا ضروری ہے۔',
         rpc: 'اپنا RPC، اگر عوامی کم پڑ جائے (حد تقریباً 15 کالز فی سیکنڈ)۔',
         data: 'فراہم کردہ نتائج کہاں محفوظ ہوں۔',
         x402: 'فی کال وصولی (اختیاری)۔ خالی چھوڑ دیں تو آپ کا ایجنٹ صرف ایسکرو کے کام لے گا۔\nقیمت فی درخواست ہے، EIP-2612 ٹوکن میں — MON نہیں چل سکتا، اس اسکیم کو `permit` چاہیے۔',

package/dist/index.js

@@ -150,12 +150,11 @@ function writeEnvExample(dest, t) {
         'PORT=8787',
         '',
         bloque(t.env.model),
-        '#   OpenAI     https://api.openai.com/v1        gpt-4o-mini',
-        '#   DeepSeek   https://api.deepseek.com/v1      deepseek-chat',
-        '#   Groq       https://api.groq.com/openai/v1   llama-3.3-70b-versatile',
-        'LLM_BASE_URL=https://api.deepseek.com/v1',
+        '#   claude · gemini · kimi · grok · glm · deepseek · groq · openai · mistral · ollama',
+        'LLM_PROVIDER=deepseek',
         'LLM_API_KEY=',
-        'LLM_MODEL=deepseek-chat',
+        '# LLM_MODEL=',
+        '# LLM_BASE_URL=',
         '',
         bloque(t.env.rpc),
         'RPC_URL=',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.9.3",
+  "version": "0.11.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.7.0",
+    "@panal/sdk": "^0.12.0",
     "dotenv": "^17.0.0",
     "tsx": "^4.19.0",
     "viem": "^2.21.0"

package/template/src/agent.ts

@@ -11,9 +11,19 @@
  * anclado en la cadena al entregar. Si luego sirves otra cosa, se nota.
  */
 
-import type { CallEnvelope } from '@panal/sdk';
+import { esImagenSoportada, llmChat, resolverLlm, type CallEnvelope, type LlmConfig } from '@panal/sdk';
 import { textoAPdf } from './pdf.js';
 
+/** Un archivo que el CLIENTE te mandó con el encargo. */
+export interface AdjuntoRecibido {
+  /** Nombre ya limpio, tal y como lo anunció el encargo. */
+  name: string;
+  /** Tipo MIME, si lo declaró: `image/png`, `application/pdf`… */
+  mime?: string;
+  /** El contenido. Su hash ya se comprobó contra lo que la cadena cubre. */
+  bytes: Uint8Array;
+}
+
 export interface TaskContext {
   /**
    * El id de la tarea en el escrow, o `null` si esto es una llamada x402: ahí
@@ -27,6 +37,20 @@ export interface TaskContext {
   /** Fecha límite de entrega, en segundos epoch. Cero en una llamada x402. */
   deadline: bigint;
 
+  /**
+   * LO QUE EL CLIENTE TE ADJUNTÓ: una foto, un PDF que revisar, un CSV.
+   *
+   * Llegan verificados. El encargo anunció el hash de cada uno ANTES de que se
+   * pagara, así que estos bytes son exactamente los que la cadena cubre — si
+   * alguien hubiera cambiado uno por el camino, no habría llegado hasta aquí.
+   *
+   * Las imágenes se le pasan solas al modelo, si el tuyo sabe mirarlas. El
+   * resto lo tienes aquí en crudo para hacer lo que sepas hacer con ello.
+   *
+   * Vacío en una llamada x402: ahí no hay tarea donde anclar un adjunto.
+   */
+  adjuntos: AdjuntoRecibido[];
+
   /**
    * PREGUNTAR A OTRO AGENTE, Y PAGARLE.
    *
@@ -115,10 +139,15 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
   // código, consultar una API, lo que quieras. No tiene por qué usar un modelo.
   // ──────────────────────────────────────────────────────────────────────────
 
-  const apiKey = process.env.LLM_API_KEY;
-  if (!apiKey) {
+  // El modelo, sea cual sea. `LLM_PROVIDER=claude|kimi|grok|glm|gemini|…` o
+  // `LLM_BASE_URL` a pelo para cualquiera que no esté en la lista.
+  let cfg: LlmConfig;
+  try {
+    cfg = resolverLlm(process.env);
+  } catch (err) {
     // Sin modelo configurado se entrega algo honesto en vez de fallar: el
     // cliente ya pagó, y dejarlo sin nada le cuesta el plazo entero.
+    console.error(`[agente] ${etiqueta(ctx)} sin modelo: ${err instanceof Error ? err.message : err}`);
     return (
       `No puedo completar este encargo ahora mismo: al agente le falta configurar su modelo.\n\n` +
       `Lo que pediste:\n${brief}\n\n` +
@@ -127,16 +156,28 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     );
   }
 
+  // Lo que el cliente adjuntó y un modelo puede MIRAR. El resto de adjuntos
+  // sigue en `ctx.adjuntos` para que hagas con ellos lo que sepas hacer.
+  const imagenes = ctx.adjuntos
+    .filter((a) => esImagenSoportada(a.mime))
+    .map((a) => ({ mime: a.mime!, bytes: a.bytes }));
+  if (ctx.adjuntos.length > 0) {
+    console.log(
+      `[agente] ${etiqueta(ctx)} ${ctx.adjuntos.length} adjunto(s), ${imagenes.length} para el modelo: ` +
+        ctx.adjuntos.map((a) => a.name).join(', '),
+    );
+  }
+
   // ¿Esto lo sé hacer yo, o me conviene preguntar? La decisión es del agente,
   // no del cliente: él pidió un trabajo, no una arquitectura.
-  const ayuda = await pedirAyudaSiHaceFalta(brief, ctx, apiKey);
+  const ayuda = await pedirAyudaSiHaceFalta(brief, ctx, cfg);
 
   // 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, ayuda);
+    const texto = await pedirAlModelo(brief, cfg, queja, ayuda, imagenes, ctx.adjuntos);
     const problema = revisar(brief, texto);
     if (!problema) {
       console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
@@ -172,12 +213,12 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
 async function pedirAyudaSiHaceFalta(
   brief: string,
   ctx: TaskContext,
-  apiKey: string,
+  cfg: LlmConfig,
 ): Promise<string | null> {
   // Sin presupuesto no hay nada que decidir, y así se ahorra la llamada.
   if (ctx.presupuesto <= 0n) return null;
 
-  const decision = await decidirDelegacion(brief, apiKey);
+  const decision = await decidirDelegacion(brief, cfg);
   if (!decision) return null;
 
   try {
@@ -197,44 +238,52 @@ async function pedirAyudaSiHaceFalta(
   }
 }
 
+/**
+ * Saca el JSON de una respuesta, aunque venga envuelto.
+ *
+ * `response_format: json_object` sólo lo entiende parte del mercado, y este
+ * agente puede correr contra cualquiera. Se pide JSON en el prompt y se busca
+ * el objeto a la vuelta: unos lo envuelven en ```json y otros le ponen una
+ * frase delante, y las dos cosas son fáciles de perdonar.
+ */
+function extraerJson(crudo: string): unknown {
+  const sinValla = crudo.replace(/^\s*```(?:json)?\s*/i, '').replace(/\s*```\s*$/, '');
+  const ini = sinValla.indexOf('{');
+  const fin = sinValla.lastIndexOf('}');
+  if (ini === -1 || fin <= ini) return null;
+  try {
+    return JSON.parse(sinValla.slice(ini, fin + 1));
+  } catch {
+    return null;
+  }
+}
+
 /** Una llamada corta al modelo: ¿delego, y a quién? Formato JSON o nada. */
 async function decidirDelegacion(
   brief: string,
-  apiKey: string,
+  cfg: LlmConfig,
 ): Promise<{ skill: string; pregunta: string } | null> {
   try {
-    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}` },
-      // Corto a propósito: si decidir tarda más que trabajar, no compensa.
-      signal: AbortSignal.timeout(30_000),
-      body: JSON.stringify({
-        model: process.env.LLM_MODEL ?? 'gpt-4o-mini',
-        response_format: { type: 'json_object' },
-        messages: [
-          {
-            role: 'system',
-            content:
-              'You are an agent deciding whether to PAY another specialist agent out of your own earnings ' +
-              'to do part of a job. Answer with JSON only.\n' +
-              '{"delegate": false} if you can do the job yourself. This is the right answer almost always.\n' +
-              '{"delegate": true, "skill": "…", "question": "…"} ONLY if the job clearly needs expertise ' +
-              'outside your own, and a specialist answer would measurably improve the result.\n' +
-              '"skill" is one or two words to search a marketplace by (e.g. "translation", "legal", "json").\n' +
-              '"question" is the self-contained question for that specialist: it will be sent on its own, ' +
-              'so it must make sense without the rest of the job.\n' +
-              'Paying costs real money. If in doubt, do not delegate.',
-          },
-          { role: 'user', content: brief },
-        ],
-      }),
-    });
-    if (!res.ok) return null;
-    const data = (await res.json()) as { choices?: { message?: { content?: string } }[] };
-    const crudo = data.choices?.[0]?.message?.content;
-    if (!crudo) return null;
-    const parsed = JSON.parse(crudo) as { delegate?: boolean; skill?: string; question?: string };
-    if (parsed.delegate !== true) return null;
+    const crudo = await llmChat(
+      // Corto a propósito, y sin reintentos: si decidir tarda más que trabajar
+      // —o cuesta más—, no compensa. Ante la duda se trabaja solo.
+      { ...cfg, timeoutMs: 30_000, maxRetries: 0, maxTokens: 400 },
+      {
+        system:
+          'You are an agent deciding whether to PAY another specialist agent out of your own earnings ' +
+          'to do part of a job. Answer with JSON only, no prose and no code fences.\n' +
+          '{"delegate": false} if you can do the job yourself. This is the right answer almost always.\n' +
+          '{"delegate": true, "skill": "…", "question": "…"} ONLY if the job clearly needs expertise ' +
+          'outside your own, and a specialist answer would measurably improve the result.\n' +
+          '"skill" is one or two words to search a marketplace by (e.g. "translation", "legal", "json").\n' +
+          '"question" is the self-contained question for that specialist: it will be sent on its own, ' +
+          'so it must make sense without the rest of the job.\n' +
+          'Paying costs real money. If in doubt, do not delegate.',
+        user: brief,
+      },
+    );
+    const parsed = extraerJson(crudo) as { delegate?: boolean; skill?: string; question?: string } | null;
+    if (!parsed || parsed.delegate !== true) return null;
     const skill = parsed.skill?.trim();
     const pregunta = parsed.question?.trim();
     if (!skill || !pregunta) return null;
@@ -314,71 +363,80 @@ function conPdfSiLoPidio(brief: string, texto: string, ctx: TaskContext): TaskRe
 
 async function pedirAlModelo(
   brief: string,
-  apiKey: string,
+  cfg: LlmConfig,
   queja: string | null,
   ayuda: string | null,
+  imagenes: { mime: string; bytes: Uint8Array }[],
+  adjuntos: AdjuntoRecibido[],
 ): 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}` },
+  // Todo va en un solo turno de usuario, con cada parte etiquetada. Los tres
+  // dialectos aceptan varios turnos, pero cada uno los cuenta a su manera, y
+  // lo que aquí importa no es de quién es cada mensaje: es que el modelo no
+  // confunda el material de apoyo con el encargo.
+  const partes = [brief];
+
+  // Los adjuntos que el modelo NO puede mirar. Se nombran para que sepa que
+  // existen: sin esto contesta como si el cliente no hubiera mandado nada, y
+  // el cliente ve una respuesta que ignora la mitad de lo que pidió.
+  const noMirables = adjuntos.filter((a) => !imagenes.some((i) => i.bytes === a.bytes));
+  if (noMirables.length > 0) {
+    partes.push(
+      `[El cliente adjuntó estos archivos, que no puedes abrir: ${noMirables
+        .map((a) => `${a.name}${a.mime ? ` (${a.mime})` : ''}`)
+        .join(', ')}. El agente los tiene y los procesa aparte.]`,
+    );
+  }
+
+  // Lo que contestó el especialista, si se le preguntó. Va marcado como
+  // material de apoyo y no como parte del encargo: sin esa aclaración el
+  // modelo tiende a copiarlo tal cual y a entregar la respuesta de otro.
+  if (ayuda) {
+    partes.push(
+      'Material de apoyo, pagado a un agente especialista. Úsalo si ayuda y descártalo si no; ' +
+        `no lo copies tal cual ni lo menciones en la entrega:\n\n${ayuda}`,
+    );
+  }
+
+  // La corrección va como una parte más: decirle QUÉ falló acierta mucho más
+  // que repetirle la misma petición a ciegas esperando otra suerte.
+  if (queja) partes.push(`Tu respuesta anterior no vale: ${queja}. Corrígela.`);
+
+  return llmChat(
     // Sin este tope, un modelo que se cuelga deja la tarea colgada para
     // siempre: el cliente ni cobra el resultado ni recupera su dinero hasta
     // que vence el plazo. Pasó de verdad, en mainnet.
-    signal: AbortSignal.timeout(120_000),
-    body: JSON.stringify({
-      model: process.env.LLM_MODEL ?? 'gpt-4o-mini',
-      messages: [
-        {
-          role: 'system',
-          content:
-            // Estas tres reglas cuestan de acertar a mano y se pagan caras:
-            // 1. Sin la del idioma, el modelo contesta en el suyo aunque el
-            //    cliente escriba en otro, y el cliente recibe algo inservible.
-            // 2. Sin la del formato, entrega Markdown y el cliente ve `**esto**`
-            //    en crudo, porque ni el dashboard ni Telegram lo renderizan.
-            // 3. Sin la del registro, envuelve el trabajo en "¡Claro! Aquí
-            //    tienes…" y el entregable parece un chat, no un producto.
-            'You are a professional agent on the Panal marketplace. ' +
-            // El "never fall back to English" y lo de los títulos no son
-            // adorno: en producción, una petición en portugués volvió entera en
-            // inglés porque el prompt listaba los títulos de sección en inglés y
-            // el modelo los copiaba; y otra en chino devolvió las claves en
-            // inglés. Los dos fallos con la regla del idioma ya puesta.
-            'RULE 1, before anything else: detect the language of the request and reply in that exact same ' +
-            'language; never switch part-way, and never fall back to English because the request is not in ' +
-            'English. If the instructions below name sections, headings or field names, translate those too: ' +
-            'they are written in one language only because these instructions are. ' +
-            'RULE 2: plain text only, never Markdown — no # headings, no ** bold, no backticks. ' +
-            'RULE 3: deliver finished professional work, with no preamble or meta-commentary.\n' +
-            // El agente adjunta el archivo por su cuenta; el modelo no se entera
-            // y, sin esta regla, se disculpa por no poder generarlo.
-            'RULE 4: the client may ask for the result as a PDF or a file. The agent attaches it after ' +
-            'you answer. Never mention files, PDFs or attachments — not even to say you cannot make them.',
-        },
-        { role: 'user', content: brief },
-        // Lo que contestó el especialista, si se le preguntó. Va marcado como
-        // material de apoyo y no como parte del encargo: sin esa aclaración el
-        // modelo tiende a copiarlo tal cual y a entregar la respuesta de otro.
-        ...(ayuda
-          ? [
-              {
-                role: 'user' as const,
-                content:
-                  'Material de apoyo, pagado a un agente especialista. Úsalo si ayuda y descártalo si no; ' +
-                  `no lo copies tal cual ni lo menciones en la entrega:\n\n${ayuda}`,
-              },
-            ]
-          : []),
-        // 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.` }] : []),
-      ],
-    }),
-  });
-
-  if (!res.ok) throw new Error(`El modelo respondió ${res.status}`);
-  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.');
-  return text;
+    { ...cfg, timeoutMs: cfg.timeoutMs ?? 120_000 },
+    {
+      system:
+        // Estas cuatro reglas cuestan de acertar a mano y se pagan caras:
+        // 1. Sin la del idioma, el modelo contesta en el suyo aunque el
+        //    cliente escriba en otro, y el cliente recibe algo inservible.
+        // 2. Sin la del formato, entrega Markdown y el cliente ve `**esto**`
+        //    en crudo, porque ni el dashboard ni Telegram lo renderizan.
+        // 3. Sin la del registro, envuelve el trabajo en "¡Claro! Aquí
+        //    tienes…" y el entregable parece un chat, no un producto.
+        'You are a professional agent on the Panal marketplace. ' +
+        // El "never fall back to English" y lo de los títulos no son
+        // adorno: en producción, una petición en portugués volvió entera en
+        // inglés porque el prompt listaba los títulos de sección en inglés y
+        // el modelo los copiaba; y otra en chino devolvió las claves en
+        // inglés. Los dos fallos con la regla del idioma ya puesta.
+        'RULE 1, before anything else: detect the language of the request and reply in that exact same ' +
+        'language; never switch part-way, and never fall back to English because the request is not in ' +
+        'English. If the instructions below name sections, headings or field names, translate those too: ' +
+        'they are written in one language only because these instructions are. ' +
+        'RULE 2: plain text only, never Markdown — no # headings, no ** bold, no backticks. ' +
+        'RULE 3: deliver finished professional work, with no preamble or meta-commentary.\n' +
+        // El agente adjunta el archivo por su cuenta; el modelo no se entera
+        // y, sin esta regla, se disculpa por no poder generarlo. Ojo al
+        // matiz: prohibirle hablar de archivos A SECAS le hacía callar
+        // también sobre la foto que le acababan de mandar.
+        'RULE 4: the client may ask for the result as a PDF or a file. The agent attaches it after ' +
+        'you answer. Never mention files, PDFs or attachments you would have to produce — not even to ' +
+        'say you cannot make them. This does NOT apply to images the client sent you: those you can ' +
+        'and should refer to, because the client knows they sent them.',
+      user: partes.join('\n\n'),
+      ...(imagenes.length > 0 ? { imagenes } : {}),
+    },
+  );
 }

package/template/src/server.ts

@@ -25,12 +25,16 @@ import { createServer, type IncomingMessage, type ServerResponse } from 'node:ht
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
+  MAX_FILE_BYTES,
   appendFilesManifest,
   assertCanServe,
   buildQuote,
   createPanalClient,
   LoopDetected,
   MAINNET_ADDRESSES,
+  monad,
+  matchAttachment,
+  parseAttachmentsManifest,
   parseEnvelope,
   parsePaymentHeader,
   permitNonce,
@@ -38,6 +42,7 @@ import {
   sanitizeFileName,
   TaskStatus,
   verifyAndSettle,
+  type AttachedFile,
   type CallEnvelope,
   type DeliveredFile,
   type PermitDomain,
@@ -46,7 +51,7 @@ import { privateKeyToAccount } from 'viem/accounts';
 import { isAddress, keccak256, parseEther, toBytes, verifyMessage } from 'viem';
 import type { Address } from 'viem';
 import { handleTask } from './agent.js';
-import type { TaskContext, TaskFile, TaskResult } from './agent.js';
+import type { AdjuntoRecibido, TaskContext, TaskFile, TaskResult } from './agent.js';
 import { arrancarVigilante } from './vigilante.js';
 
 const PORT = Number(process.env.PORT ?? 8787);
@@ -54,6 +59,21 @@ const DATA_DIR = process.env.DATA_DIR ?? './data';
 /** Tope del cuerpo de una petición: sin esto, cualquiera te tumba el proceso. */
 const MAX_BODY = 256 * 1024;
 
+/**
+ * Tope del encargo, en CARACTERES, y anunciado en `/agent.json`.
+ *
+ * Va en caracteres y no en bytes porque es lo que el cliente puede contar
+ * antes de pagar: el tope de cuerpo de arriba protege el proceso, pero nadie
+ * sabe cuántos kilobytes ocupa su texto. Sin un número publicado, un encargo
+ * demasiado largo se descubre PAGANDO —el pago queda bloqueado, el agente
+ * responde 400, y el cliente espera al plazo para recuperarlo.
+ *
+ * El límite real lo pone MAX_BODY; este número queda holgadamente por debajo
+ * (32k caracteres son unos 128 KB incluso en el peor caso de UTF-8) para que
+ * lo que se promete se cumpla siempre, y no solo con texto latino.
+ */
+const MAX_BRIEF_CHARS = 32_000;
+
 const key = process.env.AGENT_PRIVATE_KEY?.trim();
 if (!key || !/^0x[0-9a-fA-F]{64}$/.test(key)) {
   console.error('Falta AGENT_PRIVATE_KEY (0x + 64 hex) en el .env. Copia .env.example y rellénalo.');
@@ -177,6 +197,14 @@ 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());
+/**
+ * Carpeta de lo que MANDA el cliente, separada de lo que entrega el agente.
+ *
+ * Mezclarlas sería servir por `/files/:id/:name` un archivo que subió el
+ * cliente como si fuera parte de la entrega, con su hash anclado y todo. No lo
+ * es: son las dos direcciones del mismo mecanismo y no se tocan.
+ */
+const inboxDir = (taskId: bigint) => join(DATA_DIR, 'inbox', taskId.toString());
 
 function saveResult(taskId: bigint, text: string): void {
   writeFileSync(resultPath(taskId), text, 'utf8');
@@ -255,6 +283,76 @@ function normalizarSalida(salida: TaskResult): { text: string; files: TaskFile[]
   return { text: salida.text, files: salida.files ?? [] };
 }
 
+// ---------------------------------------------------------------------------
+// Adjuntos: lo que el cliente manda CON el encargo
+// ---------------------------------------------------------------------------
+//
+// El brief queda cerrado al contratar —el escrow ancla su keccak256 y más
+// abajo se rechaza cualquier texto que no lo dé—, así que una foto no puede
+// viajar dentro. Lo que viaja dentro es su HASH, anunciado en un bloque
+// `[panal-attach/1]`. Los bytes suben después, por `POST /upload/:taskId`.
+//
+// De ahí sale la única regla que hay que recordar aquí: SÓLO SE ESCRIBE LO QUE
+// EL ENCARGO ANUNCIÓ. Cualquier otro byte se rechaza sin llegar al disco. El
+// número de una tarea es público, y sin esa guarda tu agente sería un almacén
+// gratis para cualquiera que sepa contar.
+
+const adjuntoPath = (taskId: bigint, nombre: string) => join(inboxDir(taskId), nombre);
+
+/**
+ * Repasa qué adjuntos anunciados están ya en disco y cuáles faltan.
+ *
+ * El hash se comprueba AL LEER y no sólo al escribir. Entre las dos cosas hay
+ * un disco, a veces un reinicio y a veces un volumen que se vuelve a montar; y
+ * un trabajo hecho a partir de un archivo corrupto es peor que un trabajo sin
+ * hacer, porque se entrega y se ancla.
+ */
+function repasarAdjuntos(
+  taskId: bigint,
+  brief: string,
+): { recibidos: AdjuntoRecibido[]; faltan: AttachedFile[] } {
+  const recibidos: AdjuntoRecibido[] = [];
+  const faltan: AttachedFile[] = [];
+
+  for (const anunciado of parseAttachmentsManifest(brief)) {
+    let bytes: Buffer;
+    try {
+      bytes = readFileSync(adjuntoPath(taskId, anunciado.name));
+    } catch {
+      faltan.push(anunciado);
+      continue;
+    }
+    if (!matchAttachment([anunciado], bytes, anunciado.name)) {
+      console.error(`[panal] #${taskId} el adjunto "${anunciado.name}" en disco no da su hash: se pide de nuevo`);
+      faltan.push(anunciado);
+      continue;
+    }
+    recibidos.push({
+      name: anunciado.name,
+      ...(anunciado.mime ? { mime: anunciado.mime } : {}),
+      bytes: new Uint8Array(bytes),
+    });
+  }
+  return { recibidos, faltan };
+}
+
+/** Escribe un adjunto ya verificado. */
+function guardarAdjunto(taskId: bigint, nombre: string, bytes: Uint8Array): void {
+  mkdirSync(inboxDir(taskId), { recursive: true });
+  writeFileSync(adjuntoPath(taskId, nombre), bytes);
+}
+
+/**
+ * El sobre de una tarea que espera adjuntos.
+ *
+ * Cuando el encargo viene de otro agente y trae adjuntos, entre el brief y la
+ * última subida hay un rato en el que no se puede trabajar. El sobre lleva el
+ * presupuesto y el camino de la cadena, y perderlo significaría reanudar sin
+ * ellos. En memoria a propósito: si el proceso muere, la cadena que lo trajo
+ * murió con él, y reanudar sin sobre es exactamente lo que hace el vigilante.
+ */
+const sobrePendiente = new Map<string, CallEnvelope>();
+
 /** Tareas que se están procesando ahora mismo: evita trabajar dos veces. */
 const inFlight = new Set<string>();
 
@@ -399,7 +497,13 @@ async function credencialValida(
  * necesita ver en los logs.
  */
 function contexto(
-  base: { taskId: bigint | null; client: string; amount: bigint; deadline: bigint },
+  base: {
+    taskId: bigint | null;
+    client: string;
+    amount: bigint;
+    deadline: bigint;
+    adjuntos: AdjuntoRecibido[];
+  },
   sobre: CallEnvelope | null,
 ): TaskContext {
   return {
@@ -437,10 +541,36 @@ async function work(taskId: bigint, brief: string, sobre: CallEnvelope | null):
     // Lo PRIMERO, antes de trabajar: si el proceso muere a mitad, esto es lo
     // único que permite retomarlo. Guardarlo después sería guardarlo nunca.
     saveBrief(taskId, brief);
+
+    // Si el encargo anuncia adjuntos, no se empieza hasta tenerlos todos.
+    //
+    // La guarda va AQUÍ y no en la ruta HTTP porque el vigilante también llama
+    // a `work` —al retomar una tarea tras un reinicio— y ahí no hay petición
+    // 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);
+    if (faltan.length > 0) {
+      console.log(
+        `[panal] #${taskId} en espera de ${faltan.length} adjunto(s): ${faltan.map((f) => f.name).join(', ')}`,
+      );
+      return;
+    }
+    if (recibidos.length > 0) console.log(`[panal] #${taskId} con ${recibidos.length} adjunto(s) del cliente`);
+
     const task = await leerTarea(taskId);
     const salida = await handleTask(
       brief,
-      contexto({ taskId, client: task.client, amount: task.amount, deadline: task.deadline }, sobre),
+      contexto(
+        {
+          taskId,
+          client: task.client,
+          amount: task.amount,
+          deadline: task.deadline,
+          adjuntos: recibidos,
+        },
+        sobre,
+      ),
     );
 
     // Tu handleTask puede devolver un texto a secas —lo normal— o un texto con
@@ -547,6 +677,25 @@ function json(res: ServerResponse, status: number, body: unknown): void {
   res.end(JSON.stringify(body));
 }
 
+/**
+ * El cuerpo en crudo, con su propio tope.
+ *
+ * Va aparte de `readBody` a propósito: los 256 KB de MAX_BODY protegen las
+ * rutas de texto y tienen que seguir siendo pequeños. Una foto no cabe ahí, y
+ * subirle el tope a todas las rutas para que quepa sería abrir la puerta que
+ * ese límite cierra.
+ */
+async function readBodyBytes(req: IncomingMessage, max: number): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  for await (const chunk of req) {
+    total += (chunk as Buffer).length;
+    if (total > max) throw new Error(`cuerpo demasiado grande (tope ${max} bytes)`);
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
 async function readBody(req: IncomingMessage): Promise<string> {
   const chunks: Buffer[] = [];
   let total = 0;
@@ -728,9 +877,15 @@ const server = createServer((req, res) => {
       res.setHeader('access-control-allow-methods', 'GET, POST, OPTIONS');
       // Las credenciales van en cabeceras propias, y esas NO son simples: sin
       // declararlas aquí el navegador bloquea la descarga en el preflight.
+      //
+      // Cada cabecera nueva hay que añadirla A ESTA LISTA. Se olvidó con
+      // `x-panal-filename` al añadir los adjuntos, y el efecto es de los que
+      // no se ven leyendo el código: el servidor está bien, la ruta está bien,
+      // y el navegador se niega a hacer la petición sin dejar rastro en el log
+      // del agente.
       res.setHeader(
         'access-control-allow-headers',
-        'content-type, x-panal-address, x-panal-signature, x-panal-expira, x-payment, x-payment-payer',
+        'content-type, x-panal-address, x-panal-signature, x-panal-expira, x-panal-filename, x-payment, x-payment-payer',
       );
       res.setHeader('access-control-max-age', '86400');
       res.writeHead(204).end();
@@ -743,24 +898,56 @@ 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 x402 =
+        X402_PRICE !== null
+          ? {
+              method: 'POST' as const,
+              path: '/x402/ask',
+              ...(base ? { url: `${base}/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.',
+            }
+          : null;
+
       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.',
-              },
-            }
-          : {}),
+        chainId: monad.id,
+        endpoints: {
+          base,
+          postBrief: {
+            method: 'POST',
+            path: '/brief/:taskId',
+            signMessage: 'Panal brief #<taskId>  (EIP-191, firmado por el cliente de la tarea)',
+            body: `{"brief": string (máx. ${MAX_BRIEF_CHARS} chars), "address": "0x…", "signature": "0x…"}`,
+            maxBriefChars: MAX_BRIEF_CHARS,
+          },
+          postAttachment: {
+            method: 'POST',
+            path: '/upload/:taskId',
+            signMessage: 'Panal brief #<taskId>  (la MISMA firma que el encargo, no hace falta otra)',
+            body: 'los bytes en crudo; el nombre en la cabecera X-Panal-Filename',
+            howTo:
+              'anuncia cada adjunto en el brief con un bloque [panal-attach/1] ANTES de contratar, y sube los bytes aquí después. Sólo se aceptan los que el encargo anuncie.',
+            maxAttachmentBytes: MAX_FILE_BYTES,
+          },
+          getResult: {
+            method: 'GET',
+            path: '/result/:taskId',
+            signMessage: 'Panal resultado #<taskId> · <epoch>  (EIP-191, cabeceras X-Panal-*)',
+          },
+          ...(x402 ? { x402Ask: x402 } : {}),
+        },
+        // ALIAS ANTIGUO, en la raíz. Aquí es donde esta plantilla lo publicaba
+        // antes, y hay clientes ahí fuera que solo miran este sitio. Se sirve
+        // por compatibilidad y desaparecerá; lo que se lee es `endpoints`.
+        ...(x402 ? { x402Ask: x402 } : {}),
       });
       return;
     }
@@ -849,7 +1036,18 @@ const server = createServer((req, res) => {
       try {
         const salida = await handleTask(
           prompt,
-          contexto({ taskId: null, client: leido.payment.payer, amount: cobro.amount, deadline: 0n }, sobre),
+          contexto(
+            {
+              taskId: null,
+              client: leido.payment.payer,
+              amount: cobro.amount,
+              deadline: 0n,
+              // Una llamada x402 es una pregunta y una respuesta: no hay tarea
+              // donde anclar un adjunto, así que tampoco hay adjuntos.
+              adjuntos: [],
+            },
+            sobre,
+          ),
         );
         // 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
@@ -902,6 +1100,16 @@ const server = createServer((req, res) => {
         json(res, 400, { error: 'faltan taskId, brief o signature' });
         return;
       }
+      // El tope que anuncia /agent.json, aplicado. Se dice el número en la
+      // respuesta: el cliente ya pagó, y saber cuánto recortar es la
+      // diferencia entre reenviarlo y perder el encargo.
+      if (body.brief.length > MAX_BRIEF_CHARS) {
+        json(res, 400, {
+          error: `el encargo son ${body.brief.length} caracteres y el tope es ${MAX_BRIEF_CHARS}`,
+          maxBriefChars: MAX_BRIEF_CHARS,
+        });
+        return;
+      }
       const taskId = BigInt(idCrudo);
 
       // El sobre de la cadena, si este encargo viene de otro agente. Se mira
@@ -957,12 +1165,143 @@ const server = createServer((req, res) => {
         return;
       }
 
+      // El encargo se guarda YA, antes de contestar: la subida que viene
+      // detrás lo necesita en disco para saber qué bytes puede aceptar.
+      saveBrief(taskId, body.brief);
+      const { faltan } = repasarAdjuntos(taskId, body.brief);
+      if (faltan.length > 0) {
+        // No es un error: es la otra mitad del encargo, que aún viene de
+        // camino. Se contesta exactamente qué se espera para que el cliente lo
+        // suba sin tener que adivinarlo.
+        if (sobre) sobrePendiente.set(taskId.toString(), sobre);
+        json(res, 202, {
+          ok: true,
+          faltanAdjuntos: faltan.map((f) => ({ name: f.name, size: f.size, hash: f.hash })),
+          subirA: `/upload/${taskId}`,
+        });
+        return;
+      }
+
       json(res, 202, { ok: true });
       // Sin await: el cliente no debería esperar a que termines de trabajar.
       void work(taskId, body.brief, sobre);
       return;
     }
 
+    // ---- El cliente sube los adjuntos que su encargo anunció ----------------
+    //
+    // Se firma UNA vez, con el mismo `Panal brief #<id>` que abrió el encargo.
+    // Pedir una firma por archivo sería pedirle tres popups a alguien que ya
+    // pagó, y no compraría nada: lo que decide qué entra no es la firma, es el
+    // manifiesto que la cadena ya cubre.
+    const subida = /^\/upload\/(\d+)$/.exec(url.pathname);
+    if (subida && req.method === 'POST') {
+      const taskId = BigInt(subida[1]!);
+      /** Rechaza vaciando el cuerpo: si no, el cliente ve un reset en vez del motivo. */
+      const rechazar = (status: number, cuerpo: unknown): void => {
+        req.resume();
+        json(res, status, cuerpo);
+      };
+
+      // Lo local primero, que no cuesta ni RPC ni ancho de banda.
+      const brief = loadBrief(taskId);
+      if (!brief) {
+        rechazar(409, { error: 'manda antes el encargo a POST /brief/' + taskId });
+        return;
+      }
+      const anunciados = parseAttachmentsManifest(brief);
+      if (anunciados.length === 0) {
+        rechazar(409, { error: 'ese encargo no anuncia ningún adjunto' });
+        return;
+      }
+
+      const cred = credencialesDe(req, url);
+      if (!cred.address || !cred.signature) {
+        rechazar(400, { error: 'faltan address y signature (cabeceras x-panal-address / x-panal-signature)' });
+        return;
+      }
+
+      const task = await leerTarea(taskId);
+      if (task.worker.toLowerCase() !== account.address.toLowerCase()) {
+        rechazar(403, { error: 'esa tarea no es de este agente' });
+        return;
+      }
+      if (task.status !== TaskStatus.Open) {
+        rechazar(409, { error: `la tarea está ${TaskStatus[task.status]}` });
+        return;
+      }
+      if (cred.address.toLowerCase() !== task.client.toLowerCase()) {
+        rechazar(403, { error: 'solo el cliente de la tarea puede subirle adjuntos' });
+        return;
+      }
+      if (!(await signedBy(briefSignMessage(taskId), cred.signature, task.client))) {
+        rechazar(401, { error: 'la firma no es del cliente de esta tarea' });
+        return;
+      }
+
+      // Nada puede pesar más que el mayor de los adjuntos anunciados: el
+      // tamaño va DENTRO del manifiesto, o sea dentro de lo que la cadena
+      // cubre. Se mira antes de leer para no tragarse los bytes de nadie.
+      const tope = Math.min(MAX_FILE_BYTES, Math.max(...anunciados.map((f) => f.size)));
+      const declarado = Number(req.headers['content-length'] ?? 0);
+      if (declarado > tope) {
+        rechazar(413, { error: `ese archivo son ${declarado} bytes y el mayor que anunciaste mide ${tope}` });
+        return;
+      }
+
+      let bytes: Buffer;
+      try {
+        bytes = await readBodyBytes(req, tope);
+      } catch (err) {
+        json(res, 413, { error: err instanceof Error ? err.message : 'cuerpo demasiado grande' });
+        return;
+      }
+
+      // La guarda. Se busca por hash, así que el nombre que venga en la
+      // cabecera no decide nada: sólo desempata si el mismo archivo se
+      // adjuntó dos veces.
+      // El nombre viene percent-encoded: una cabecera HTTP no admite
+      // caracteres fuera de latin-1, y «recibo ñ.png» es un nombre normal.
+      let nombre: string | undefined;
+      const cabecera = req.headers['x-panal-filename'];
+      if (typeof cabecera === 'string') {
+        try {
+          nombre = decodeURIComponent(cabecera);
+        } catch {
+          nombre = cabecera;
+        }
+      }
+      const anunciado = matchAttachment(anunciados, bytes, nombre);
+      if (!anunciado) {
+        json(res, 403, {
+          error: 'esos bytes no son ninguno de los adjuntos que anuncia el encargo',
+          esperados: anunciados.map((f) => ({ name: f.name, size: f.size, hash: f.hash })),
+        });
+        return;
+      }
+
+      guardarAdjunto(taskId, anunciado.name, bytes);
+      const { faltan: pendientes } = repasarAdjuntos(taskId, brief);
+      console.log(
+        `[panal] #${taskId} adjunto "${anunciado.name}" recibido (${bytes.byteLength} bytes) · faltan ${pendientes.length}`,
+      );
+
+      json(res, 202, {
+        ok: true,
+        guardado: anunciado.name,
+        faltanAdjuntos: pendientes.map((f) => ({ name: f.name, size: f.size, hash: f.hash })),
+      });
+
+      // Con el último adjunto ya se puede trabajar. El encargo estaba en
+      // espera desde que llegó; esto es lo que lo suelta.
+      if (pendientes.length === 0) {
+        const sobreGuardado = sobrePendiente.get(taskId.toString()) ?? null;
+        sobrePendiente.delete(taskId.toString());
+        void work(taskId, brief, sobreGuardado);
+      }
+      return;
+    }
+
     // ---- El cliente recoge su resultado -------------------------------------
     const match = /^\/result\/(\d+)$/.exec(url.pathname);
     if (match && req.method === 'GET') {