create-panal-agent 0.4.0 → 0.6.0

package/dist/i18n.js

@@ -74,6 +74,8 @@ The language is taken from --lang, then PANAL_LANG, then your system locale.`,
         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`.',
+        subcontrata: "Subcontracting (optional, off by default). Your agent can pay another one for what it cannot do itself (see ctx.consultar in agent.ts). Without a number here it never delegates.\nIt is in the x402 currency, NOT a cut of what you charge per task: a task is paid in MON and a question in $PANAL, and converting one into the other by eye would be inventing the budget.",
+        vigilante: "The watchman. Every 60 s it reviews your open tasks and recovers what got stuck: a delivery that was never anchored, work that died halfway, or a job that was paid for and never arrived.\nVIGILANTE=off turns it off. PUBLIC_URL is your https endpoint, used in the lost-job warning.",
     },
     readme: `# {name}
 
@@ -164,6 +166,8 @@ El idioma sale de --lang, luego de PANAL_LANG, y si no del locale del sistema.`,
         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`.',
+        subcontrata: "Subcontratar (opcional, apagado por defecto). Tu agente puede pagar a otro por lo que no sepa hacer (ver ctx.consultar en agent.ts). Sin un numero aqui, no delega nunca.\nVa en la moneda del x402 y NO se deduce de lo que cobras por tarea: una tarea se cobra en MON y una consulta en $PANAL, y convertir una en otra a ojo seria inventarse el presupuesto.",
+        vigilante: "El vigilante. Cada 60 s repasa tus tareas abiertas y recupera lo que se quedo colgado: una entrega que no llego a anclarse, un trabajo que murio a medias, o un encargo pagado que nunca llego.\nVIGILANTE=off lo apaga. PUBLIC_URL es tu endpoint https, para el aviso de encargo perdido.",
     },
     readme: `# {name}
 
@@ -255,6 +259,8 @@ const zh = {
         rpc: '你自己的 RPC，当公共节点不够用时（其上限约为每秒 15 次调用）。',
         data: '交付结果的存放位置。',
         x402: '按次收费（可选）。留空则你的代理只接受托管订单。\n价格按每次请求计算，使用支持 EIP-2612 的代币——不能是 MON，该方案依赖 `permit`。',
+        subcontrata: "转包（可选，默认关闭）。你的代理可以为自己做不了的事付钱给另一个代理（见 agent.ts 的 ctx.consultar）。这里没有数字就永远不会转包。\n它使用 x402 的币种，不是按任务收入的比例：任务用 MON 结算，提问用 $PANAL，凭感觉换算等于凭空编造预算。",
+        vigilante: "守望者。每 60 秒检查一次你未完成的任务，并挽回卡住的部分：没有上链的交付、中途死掉的工作，或已付款却从未送达的委托。\nVIGILANTE=off 可关闭。PUBLIC_URL 是你的 https 端点，用于丢失委托的提醒。",
     },
     readme: `# {name}
 
@@ -341,6 +347,8 @@ const hi = {
         rpc: 'अपना RPC, अगर सार्वजनिक कम पड़े (इसकी सीमा ~15 कॉल/सेकंड है)।',
         data: 'दिए गए परिणाम कहाँ सहेजें।',
         x402: 'प्रति कॉल शुल्क (वैकल्पिक)। खाली छोड़ें तो आपका एजेंट केवल एस्क्रो वाले काम लेगा।\nकीमत प्रति अनुरोध है, EIP-2612 टोकन में — MON नहीं चल सकता, इस योजना को `permit` चाहिए।',
+        subcontrata: "सबकॉन्ट्रैक्टिंग (वैकल्पिक, डिफ़ॉल्ट रूप से बंद)। आपका एजेंट जो खुद नहीं कर सकता, उसके लिए दूसरे को भुगतान कर सकता है (agent.ts में ctx.consultar देखें)। यहाँ संख्या के बिना वह कभी नहीं सौंपता।\nयह x402 की मुद्रा में है, प्रति कार्य आय का हिस्सा नहीं: कार्य MON में और प्रश्न $PANAL में चुकाया जाता है।",
+        vigilante: "प्रहरी। हर 60 सेकंड में आपके खुले कार्यों की जाँच करता है और जो अटक गया उसे वापस लाता है: वह डिलीवरी जो चेन पर दर्ज नहीं हुई, अधूरा रह गया काम, या भुगतान किया गया आदेश जो कभी नहीं पहुँचा।\nVIGILANTE=off इसे बंद करता है। PUBLIC_URL आपका https एंडपॉइंट है।",
     },
     readme: `# {name}
 
@@ -431,6 +439,8 @@ const ar = {
         rpc: 'عقدة RPC خاصة بك، إن لم تكفِ العامة (حدّها نحو 15 طلبًا في الثانية).',
         data: 'مكان حفظ النتائج المُسلَّمة.',
         x402: 'التحصيل لكل استدعاء (اختياري). اتركه فارغًا فيقبل وكيلك مهام الضمان فقط.\nالسعر لكل طلب، بعملة تدعم EIP-2612 — لا يصلح MON، فالمخطط يحتاج `permit`.',
+        subcontrata: "التعاقد من الباطن (اختياري، معطل افتراضيا). يمكن لوكيلك ان يدفع لوكيل اخر مقابل ما لا يجيده (انظر ctx.consultar في agent.ts). بدون رقم هنا لن يفوض ابدا.\nيكون بعملة x402، وليس نسبة مما تتقاضاه عن المهمة: المهمة تدفع بـ MON والسؤال بـ $PANAL.",
+        vigilante: "الحارس. كل 60 ثانية يراجع مهامك المفتوحة ويستعيد ما تعطل: تسليم لم يثبت على السلسلة، او عمل مات في منتصفه، او طلب مدفوع لم يصل قط.\nVIGILANTE=off يوقفه. PUBLIC_URL هو نقطة الوصول https لديك.",
     },
     readme: `# {name}
 
@@ -520,6 +530,8 @@ La langue vient de --lang, puis de PANAL_LANG, puis de la locale du système.`,
         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`.",
+        subcontrata: "Sous-traitance (optionnelle, desactivee par defaut). Votre agent peut payer un autre pour ce qu il ne sait pas faire (voir ctx.consultar dans agent.ts). Sans un nombre ici, il ne delegue jamais.\nC est dans la devise x402, PAS une part de ce que vous facturez par tache : une tache se paie en MON et une question en $PANAL.",
+        vigilante: "La sentinelle. Toutes les 60 s, elle passe en revue vos taches ouvertes et recupere ce qui est reste bloque : une livraison jamais ancree, un travail mort a mi-chemin, ou une commande payee qui n est jamais arrivee.\nVIGILANTE=off la desactive. PUBLIC_URL est votre endpoint https.",
     },
     readme: `# {name}
 
@@ -613,6 +625,8 @@ O idioma vem de --lang, depois de PANAL_LANG e, por fim, do locale do sistema.`,
         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`.',
+        subcontrata: "Subcontratar (opcional, desligado por omissao). O seu agente pode pagar a outro pelo que nao sabe fazer (ver ctx.consultar em agent.ts). Sem um numero aqui, nunca delega.\nVai na moeda do x402 e NAO e uma fatia do que cobra por tarefa: uma tarefa paga-se em MON e uma pergunta em $PANAL.",
+        vigilante: "O vigia. A cada 60 s reve as suas tarefas abertas e recupera o que ficou preso: uma entrega que nunca foi ancorada, trabalho que morreu a meio, ou uma encomenda paga que nunca chegou.\nVIGILANTE=off desliga-o. PUBLIC_URL e o seu endpoint https.",
     },
     readme: `# {name}
 
@@ -704,6 +718,8 @@ const ru = {
         rpc: 'Свой RPC, если публичного не хватает (лимит ~15 запросов/с).',
         data: 'Где хранить сданные результаты.',
         x402: 'Плата за вызов (необязательно). Оставьте пустым — агент будет брать только заказы через эскроу.\nЦена за один запрос, в токене с EIP-2612: MON не подходит, схеме нужен `permit`.',
+        subcontrata: "Субподряд (необязательно, по умолчанию выключен). Ваш агент может заплатить другому за то, чего не умеет сам (см. ctx.consultar в agent.ts). Без числа здесь он никогда не делегирует.\nУказывается в валюте x402, а НЕ долей от оплаты за задачу: задача оплачивается в MON, а вопрос в $PANAL.",
+        vigilante: "Сторож. Каждые 60 с проверяет ваши открытые задачи и вытаскивает то, что застряло: доставку, которая не попала в блокчейн, работу, оборвавшуюся на середине, или оплаченный заказ, который так и не пришел.\nVIGILANTE=off выключает его. PUBLIC_URL ваш https-эндпоинт.",
     },
     readme: `# {name}
 
@@ -796,6 +812,8 @@ const bn = {
         rpc: 'নিজস্ব RPC, যদি সর্বজনীনটি যথেষ্ট না হয় (সীমা প্রায় ১৫ কল/সেকেন্ড)।',
         data: 'সরবরাহ করা ফলাফল কোথায় রাখা হবে।',
         x402: 'প্রতি কলে চার্জ (ঐচ্ছিক)। ফাঁকা রাখলে আপনার এজেন্ট কেবল এসক্রো কাজ নেবে।\nদাম প্রতি অনুরোধে, EIP-2612 টোকেনে — MON চলবে না, স্কিমটির `permit` দরকার।',
+        subcontrata: "সাবকন্ট্রাক্টিং (ঐচ্ছিক, ডিফল্টে বন্ধ)। আপনার এজেন্ট যা নিজে পারে না, তার জন্য অন্যকে অর্থ দিতে পারে (agent.ts-এ ctx.consultar দেখুন)। এখানে সংখ্যা না থাকলে সে কখনও দায়িত্ব দেয় না।\nএটি x402-এর মুদ্রায়, কাজপ্রতি আয়ের অংশ নয়: কাজের দাম MON-এ আর প্রশ্নের দাম $PANAL-এ।",
+        vigilante: "প্রহরী। প্রতি ৬০ সেকেন্ডে আপনার খোলা কাজগুলি দেখে এবং আটকে যাওয়া জিনিস উদ্ধার করে: চেইনে না ওঠা ডেলিভারি, মাঝপথে মরে যাওয়া কাজ, বা টাকা দেওয়া হয়েছে অথচ কখনও পৌঁছায়নি এমন আদেশ।\nVIGILANTE=off এটি বন্ধ করে। PUBLIC_URL আপনার https এন্ডপয়েন্ট।",
     },
     readme: `# {name}
 
@@ -885,6 +903,8 @@ const ur = {
         rpc: 'اپنا RPC، اگر عوامی کم پڑ جائے (حد تقریباً 15 کالز فی سیکنڈ)۔',
         data: 'فراہم کردہ نتائج کہاں محفوظ ہوں۔',
         x402: 'فی کال وصولی (اختیاری)۔ خالی چھوڑ دیں تو آپ کا ایجنٹ صرف ایسکرو کے کام لے گا۔\nقیمت فی درخواست ہے، EIP-2612 ٹوکن میں — MON نہیں چل سکتا، اس اسکیم کو `permit` چاہیے۔',
+        subcontrata: "سب کنٹریکٹنگ (اختیاری، بذریعہ ڈیفالٹ بند)۔ آپ کا ایجنٹ جو خود نہیں کر سکتا اس کے لیے دوسرے کو ادائیگی کر سکتا ہے (agent.ts میں ctx.consultar دیکھیں)۔ یہاں نمبر کے بغیر وہ کبھی نہیں سونپتا۔\nیہ x402 کی کرنسی میں ہے، فی ٹاسک آمدنی کا حصہ نہیں: ٹاسک MON میں اور سوال $PANAL میں ادا ہوتا ہے۔",
+        vigilante: "نگہبان۔ ہر 60 سیکنڈ میں آپ کے کھلے کام دیکھتا ہے اور جو اٹکا ہے اسے بچاتا ہے: وہ ڈیلیوری جو چین پر درج نہ ہوئی، وہ کام جو بیچ میں مر گیا، یا ادا شدہ آرڈر جو کبھی نہ پہنچا۔\nVIGILANTE=off اسے بند کرتا ہے۔ PUBLIC_URL آپ کا https اینڈ پوائنٹ ہے۔",
     },
     readme: `# {name}
 

package/dist/index.js

@@ -169,6 +169,14 @@ function writeEnvExample(dest, t) {
         '# X402_SYMBOL=$PANAL',
         '# X402_DESCRIPTION=',
         '',
+        bloque(t.env.subcontrata),
+        'SUBCONTRATA_MAX=',
+        'SUBCONTRATA_SALTOS=2',
+        '',
+        bloque(t.env.vigilante),
+        'VIGILANTE_SEGUNDOS=60',
+        'PUBLIC_URL=',
+        '',
     ].join('\n');
     writeFileSync(join(dest, '.env.example'), contenido, 'utf8');
     return contenido;

package/package.json

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

package/template/_env.example

@@ -1,21 +1,13 @@
-# Clave privada de la wallet DEDICADA de tu agente.
-# Es la que cobra y la que firma las entregas. No uses tu wallet personal:
-# esta vive en un servidor. Solo necesita un poco de MON para el gas.
-AGENT_PRIVATE_KEY=
-
-# Puerto del servidor. Muchos hostings lo inyectan solos.
-PORT=8787
-
-# Tu modelo, si tu agente usa uno. Cualquier API compatible con OpenAI:
-#   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
-LLM_API_KEY=
-LLM_MODEL=deepseek-chat
-
-# RPC propio, si el público se te queda corto (limita a ~15 llamadas/s).
-RPC_URL=
-
-# Dónde guardar los resultados entregados.
-DATA_DIR=./data
+# Este archivo NO es el que acaba en el proyecto generado.
+#
+# El `.env.example` de verdad lo escribe `writeEnvExample()` en src/index.ts, a
+# partir del catálogo de idiomas (src/i18n.ts), porque sus comentarios van
+# traducidos a los diez idiomas. Este de aquí solo existe porque el copiador
+# exige encontrarlo, y se sobrescribe justo después.
+#
+# Si añades una variable nueva, va en DOS sitios y ninguno es este:
+#   1. `env` del catálogo en src/i18n.ts, en los diez idiomas
+#   2. `writeEnvExample()` en src/index.ts
+#
+# Documentarla aquí no la enseña a nadie: se pisa antes de que el usuario la
+# vea. Pasó con SUBCONTRATA_MAX y con el vigilante.

package/template/_package.json

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@panal/sdk": "^0.6.0",
+    "@panal/sdk": "^0.6.1",
     "dotenv": "^17.0.0",
     "tsx": "^4.19.0",
     "viem": "^2.21.0"

package/template/src/agent.ts

@@ -11,6 +11,9 @@
  * anclado en la cadena al entregar. Si luego sirves otra cosa, se nota.
  */
 
+import type { CallEnvelope } from '@panal/sdk';
+import { textoAPdf } from './pdf.js';
+
 export interface TaskContext {
   /**
    * El id de la tarea en el escrow, o `null` si esto es una llamada x402: ahí
@@ -23,6 +26,41 @@ export interface TaskContext {
   amount: bigint;
   /** Fecha límite de entrega, en segundos epoch. Cero en una llamada x402. */
   deadline: bigint;
+
+  /**
+   * PREGUNTAR A OTRO AGENTE, Y PAGARLE.
+   *
+   * Busca en el mercado quién dice saber hacer eso, les pide precio —gratis—,
+   * elige al más barato que quepa en tu presupuesto, le paga y te devuelve su
+   * respuesta. Tú decides cuándo merece la pena; el motor se encarga del resto.
+   *
+   *     const glosario = await ctx.consultar('traducción', 'traduce estos términos al alemán: …');
+   *
+   * Cuesta DINERO TUYO, del que acabas de cobrar. Tres cosas que conviene
+   * tener claras antes de usarlo:
+   *
+   *   - Si no pusiste SUBCONTRATA_MAX en el .env, esto lanza. Es deliberado:
+   *     un agente no debería empezar a gastar por defecto.
+   *   - Puede lanzar aunque haya presupuesto, si la cadena que te llamó ya lo
+   *     agotó o se quedó sin saltos. Heredar una cadena no amplía sus límites.
+   *   - No lo captures en silencio. Que entregues algo peor porque no pudiste
+   *     delegar es justo lo que necesitas ver en los logs.
+   *
+   * @param skill     Qué buscas, en el idioma en que la gente escribe sus
+   *                  skills: 'traducción', 'legal', 'json'…
+   * @param pregunta  Lo que le preguntas. Va tal cual al otro agente.
+   */
+  consultar(skill: string, pregunta: string): Promise<string>;
+
+  /** Lo que puedes gastarte en `consultar` en este encargo. Cero = no delegas. */
+  presupuesto: bigint;
+
+  /**
+   * El sobre de la cadena, si quien te llamó era otro agente. `null` si el
+   * encargo viene de una persona. Solo lo necesitas para mirarlo en los logs:
+   * `consultar` ya lo respeta por su cuenta.
+   */
+  envelope: CallEnvelope | null;
 }
 
 /** Un archivo que entregas junto al texto. */
@@ -89,16 +127,20 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     );
   }
 
+  // ¿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);
+
   // 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 texto = await pedirAlModelo(brief, apiKey, queja, ayuda);
     const problema = revisar(brief, texto);
     if (!problema) {
       console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
-      return texto;
+      return conPdfSiLoPidio(brief, texto, ctx);
     }
     console.error(`[agente] ${etiqueta(ctx)} intento ${intento}: ${problema}`);
     // A la segunda se entrega igual. Tu revisión puede equivocarse, y un falso
@@ -106,13 +148,103 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     // 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;
+      return conPdfSiLoPidio(brief, texto, ctx);
     }
     queja = problema;
   }
   throw new Error('inalcanzable');
 }
 
+/**
+ * TU AGENTE DECIDIENDO SI SUBCONTRATA. Devuelve lo que le contestó otro, o null.
+ *
+ * Esto es lo que separa a un agente de un endpoint: mira el encargo, reconoce
+ * lo que no es suyo y va a comprarlo con su dinero. Nadie se lo ha pedido.
+ *
+ * La decisión la toma el propio modelo, en una llamada aparte y barata, con una
+ * regla incómoda de escribir y necesaria: NO delegar es la respuesta correcta
+ * casi siempre. Un agente que pregunta por todo se funde lo que cobró, y en
+ * cuanto el trabajo es suyo la respuesta de un tercero solo añade ruido.
+ *
+ * Bórralo entero si tu agente no necesita a nadie. Muchos no lo necesitan, y
+ * ese es el caso sano.
+ */
+async function pedirAyudaSiHaceFalta(
+  brief: string,
+  ctx: TaskContext,
+  apiKey: string,
+): 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);
+  if (!decision) return null;
+
+  try {
+    const respuesta = await ctx.consultar(decision.skill, decision.pregunta);
+    console.log(`[agente] ${etiqueta(ctx)} subcontrató "${decision.skill}": ${respuesta.length} caracteres`);
+    return respuesta;
+  } catch (err) {
+    // Que no se pueda delegar NO cancela el encargo: el cliente pagó por un
+    // trabajo y lo va a recibir, hecho con lo que este agente sepa. Se deja
+    // dicho en voz alta porque es justo lo que el autor querrá ver el día que
+    // la respuesta salga más floja de lo normal.
+    console.error(
+      `[agente] ${etiqueta(ctx)} quería preguntar a un agente de "${decision.skill}" y no pudo: ` +
+        `${err instanceof Error ? err.message : err}. Sigue por su cuenta.`,
+    );
+    return null;
+  }
+}
+
+/** Una llamada corta al modelo: ¿delego, y a quién? Formato JSON o nada. */
+async function decidirDelegacion(
+  brief: string,
+  apiKey: string,
+): 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 skill = parsed.skill?.trim();
+    const pregunta = parsed.question?.trim();
+    if (!skill || !pregunta) return null;
+    return { skill, pregunta };
+  } catch {
+    // Decidir mal no puede tumbar el encargo: ante la duda, se trabaja solo.
+    return null;
+  }
+}
+
 /**
  * TU CONTROL DE CALIDAD. Devuelve null si la respuesta vale, o el motivo si no.
  *
@@ -144,10 +276,48 @@ function revisar(brief: string, resultado: string): string | null {
     return 'la respuesta lleva Markdown (**, # o ```) y el cliente lo verá en crudo: devuélvela en texto plano';
   }
 
+  // Si el cliente pide "y mándamelo en PDF", el modelo tiende a contestar que
+  // él no genera archivos — mientras el archivo va adjunto. Prohibírselo en el
+  // prompt reduce el problema pero no lo cierra: llegó a salir "no menciono el
+  // PDF porque no debo". Se comprueba, y se reintenta.
+  //
+  // Se busca la palabra JUNTO A una frase autorreferencial, no la palabra
+  // suelta: alguien puede encargar de verdad trabajo sobre PDFs, y ahí la
+  // palabra es el encargo.
+  const meta = /(no (puedo|incluyo|voy a|debo|menciono|se adjunt|se genera)|el sistema (se encarg|lo adjunt)|i (cannot|can't|am not)|the system will)/i;
+  for (const linea of resultado.split('\n')) {
+    if (/\b(pdf|archivo|fichero|adjunto|attachment|file)\b/i.test(linea) && meta.test(linea)) {
+      return 'has comentado que no generas archivos; el agente los adjunta solo. Reescríbelo sin ninguna referencia a archivos, PDFs ni adjuntos: solo el trabajo';
+    }
+  }
+
   return null;
 }
 
-async function pedirAlModelo(brief: string, apiKey: string, queja: string | null): Promise<string> {
+/**
+ * Adjunta el trabajo en PDF si el encargo lo pedía. El texto se entrega igual.
+ *
+ * Se mira el encargo en vez de mandarlo siempre: a un agente también lo llaman
+ * otros programas, y adjuntarles un archivo que no pidieron es peso muerto.
+ *
+ * Bórralo si tu agente no entrega PDFs, o cámbialo por lo que tú generes: una
+ * imagen, un CSV, un ZIP. El motor calcula el hash de lo que devuelvas aquí y
+ * lo ancla en la cadena, así que el cliente puede demostrar que el archivo que
+ * se baja es exactamente el que le entregaste.
+ */
+function conPdfSiLoPidio(brief: string, texto: string, ctx: TaskContext): TaskResult {
+  if (!/\bpdf\b/i.test(brief)) return texto;
+  const pdf = textoAPdf(`Panal - entrega ${etiqueta(ctx)}`, texto);
+  console.log(`[agente] ${etiqueta(ctx)} PDF de ${pdf.byteLength} bytes adjunto`);
+  return { text: texto, files: [{ name: 'entrega.pdf', data: pdf, mime: 'application/pdf' }] };
+}
+
+async function pedirAlModelo(
+  brief: string,
+  apiKey: string,
+  queja: string | null,
+  ayuda: 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}` },
@@ -171,9 +341,26 @@ async function pedirAlModelo(brief: string, apiKey: string, queja: string | null
             'You are a professional agent on the Panal marketplace. ' +
             'RULE 1: detect the language of the request and reply in that exact same language; never switch. ' +
             '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.',
+            '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.` }] : []),

package/template/src/pdf.ts

@@ -0,0 +1,180 @@
+/**
+ * Un PDF de verdad, sin dependencias. Puedes borrar este archivo si tu agente
+ * no entrega PDFs.
+ *
+ * No es una plantilla ni un HTML impreso: se escriben los objetos del PDF a
+ * mano, con su tabla xref y sus offsets en bytes. Sale un archivo que abre
+ * cualquier lector, y no añade ni un paquete a tus dependencias — meter una
+ * librería de 4 MB para pintar texto monoespaciado en un A4 no sale a cuenta.
+ *
+ * Se usa desde `agent.ts`:
+ *
+ *     const pdf = textoAPdf('Mi informe', texto);
+ *     return { text: texto, files: [{ name: 'informe.pdf', data: pdf, mime: 'application/pdf' }] };
+ *
+ * El motor calcula su hash y lo ancla en la cadena; tú no tocas nada de eso.
+ *
+ * Lo que hace bien y cuesta acertar a mano: parte las líneas largas para que no
+ * se salgan del papel, pagina solo, y traduce los símbolos que la codificación
+ * del PDF no tiene en vez de destrozarlos en silencio.
+ */
+
+/** A4 en puntos, que es la unidad del PDF. */
+const ANCHO = 595;
+const ALTO = 842;
+const MARGEN = 50;
+const CUERPO = 9.5;
+const INTERLINEA = 12.5;
+/** Cuántas líneas caben en una página con estos márgenes. */
+const LINEAS_POR_PAGINA = Math.floor((ALTO - MARGEN * 2) / INTERLINEA);
+/** Ancho de caracteres a 9.5pt en Courier: 0.6 em, redondeado a la baja. */
+const COLUMNAS = Math.floor((ANCHO - MARGEN * 2) / (CUERPO * 0.6));
+
+/**
+ * Escapa un texto para meterlo entre paréntesis en un PDF.
+ *
+ * Los paréntesis delimitan las cadenas, así que uno sin escapar rompe el
+ * archivo entero — y un JSON viene lleno de ellos.
+ */
+function escapar(texto: string): string {
+  return texto.replace(/\\/g, '\\\\').replace(/\(/g, '\\(').replace(/\)/g, '\\)');
+}
+
+/**
+ * Parte las líneas largas para que no se salgan del papel.
+ *
+ * Un PDF no ajusta el texto solo: lo que no cabe, sencillamente no se ve. Con
+ * un JSON de una sola línea eso significa entregar una hoja casi en blanco.
+ */
+function ajustar(lineas: string[]): string[] {
+  const out: string[] = [];
+  for (const linea of lineas) {
+    if (linea.length <= COLUMNAS) {
+      out.push(linea);
+      continue;
+    }
+    // Se conserva la sangría al partir: en un JSON es lo que deja ver la
+    // estructura, y sin ella el corte lo vuelve ilegible.
+    const sangria = /^\s*/.exec(linea)![0].slice(0, 20);
+    let resto = linea;
+    let primera = true;
+    while (resto.length > 0) {
+      const ancho = primera ? COLUMNAS : COLUMNAS - sangria.length;
+      out.push((primera ? '' : sangria) + resto.slice(0, ancho));
+      resto = resto.slice(ancho);
+      primera = false;
+    }
+  }
+  return out;
+}
+
+/**
+ * Sustitutos ASCII de los símbolos que WinAnsiEncoding no tiene.
+ *
+ * Sin esto, `Buffer.from(txt, 'latin1')` los recorta al byte bajo y salen
+ * caracteres que no significan nada: un "≠" acababa impreso como "`", así que
+ * un caso de prueba que decía "b ≠ 0" pasaba a decir "b ` 0". Silencioso, y
+ * dentro de un entregable que se cobra.
+ */
+const SUSTITUTOS: Record<string, string> = {
+  '≠': '!=', '≤': '<=', '≥': '>=', '≈': '~=', '±': '+/-', '×': 'x', '÷': '/',
+  '→': '->', '←': '<-', '⇒': '=>', '∞': 'infinito', '∅': 'vacio',
+  '“': '"', '”': '"', '„': '"', '‘': "'", '’': "'", '‹': '<', '›': '>',
+  '–': '-', '—': '-', '…': '...', '•': '-', '·': '·', '™': '(TM)', '€': 'EUR',
+};
+
+/**
+ * Latin-1, que es lo que entiende WinAnsiEncoding —la codificación de las
+ * fuentes base del PDF—, sustituyendo antes lo que no cabe.
+ *
+ * Lo que no tiene sustituto se marca con "?" a propósito: un interrogante
+ * avisa de que ahí faltaba algo; un carácter aleatorio miente.
+ */
+function aLatin1(texto: string): Buffer {
+  const convertido = [...texto]
+    .map((c) => {
+      if (SUSTITUTOS[c]) return SUSTITUTOS[c];
+      return c.codePointAt(0)! <= 0xff ? c : '?';
+    })
+    .join('');
+  return Buffer.from(convertido, 'latin1');
+}
+
+/** Construye el PDF. Devuelve los bytes, listos para escribir o entregar. */
+export function textoAPdf(titulo: string, contenido: string): Uint8Array {
+  const lineas = ajustar([titulo, '', ...contenido.split('\n')]);
+
+  // Se reparte en páginas antes de escribir nada: hay que saber cuántas son
+  // para numerar los objetos, y en un PDF los objetos se referencian por número.
+  const paginas: string[][] = [];
+  for (let i = 0; i < lineas.length; i += LINEAS_POR_PAGINA) {
+    paginas.push(lineas.slice(i, i + LINEAS_POR_PAGINA));
+  }
+  if (paginas.length === 0) paginas.push(['(sin contenido)']);
+
+  // Numeración: 1 catálogo, 2 árbol de páginas, 3 fuente, y luego cada página
+  // con su flujo de contenido, dos objetos por página.
+  const FUENTE = 3;
+  const primeraPagina = 4;
+  const idPagina = (i: number) => primeraPagina + i * 2;
+  const idContenido = (i: number) => primeraPagina + i * 2 + 1;
+
+  const objetos: Buffer[] = [];
+  const add = (n: number, cuerpo: string | Buffer) => {
+    objetos[n] = Buffer.concat([
+      aLatin1(`${n} 0 obj\n`),
+      typeof cuerpo === 'string' ? aLatin1(cuerpo) : cuerpo,
+      aLatin1('\nendobj\n'),
+    ]);
+  };
+
+  const kids = paginas.map((_, i) => `${idPagina(i)} 0 R`).join(' ');
+  add(1, '<< /Type /Catalog /Pages 2 0 R >>');
+  add(2, `<< /Type /Pages /Kids [${kids}] /Count ${paginas.length} >>`);
+  add(FUENTE, '<< /Type /Font /Subtype /Type1 /BaseFont /Courier /Encoding /WinAnsiEncoding >>');
+
+  paginas.forEach((lineasPagina, i) => {
+    add(
+      idPagina(i),
+      `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${ANCHO} ${ALTO}] ` +
+        `/Resources << /Font << /F1 ${FUENTE} 0 R >> >> /Contents ${idContenido(i)} 0 R >>`,
+    );
+
+    const flujo = aLatin1(
+      [
+        'BT',
+        `/F1 ${CUERPO} Tf`,
+        `${INTERLINEA} TL`,
+        `${MARGEN} ${ALTO - MARGEN} Td`,
+        ...lineasPagina.map((l) => `(${escapar(l)}) Tj T*`),
+        'ET',
+      ].join('\n'),
+    );
+    // /Length va en BYTES, no en caracteres: con acentos no es lo mismo, y un
+    // lector estricto rechaza el archivo si no cuadra.
+    add(idContenido(i), Buffer.concat([aLatin1(`<< /Length ${flujo.length} >>\nstream\n`), flujo, aLatin1('\nendstream')]));
+  });
+
+  // Ensamblado: hay que ir apuntando el offset en bytes de cada objeto, porque
+  // la tabla xref del final los indexa por posición absoluta en el archivo.
+  const total = objetos.length - 1;
+  const partes: Buffer[] = [aLatin1('%PDF-1.4\n')];
+  const offsets: number[] = [];
+  let cursor = partes[0]!.length;
+
+  for (let n = 1; n <= total; n++) {
+    offsets[n] = cursor;
+    partes.push(objetos[n]!);
+    cursor += objetos[n]!.length;
+  }
+
+  const xref = [
+    'xref',
+    `0 ${total + 1}`,
+    '0000000000 65535 f ',
+    ...Array.from({ length: total }, (_, i) => `${String(offsets[i + 1]).padStart(10, '0')} 00000 n `),
+  ].join('\n');
+
+  partes.push(aLatin1(`${xref}\ntrailer\n<< /Size ${total + 1} /Root 1 0 R >>\nstartxref\n${cursor}\n%%EOF\n`));
+  return new Uint8Array(Buffer.concat(partes));
+}

package/template/src/server.ts

@@ -26,15 +26,19 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import {
   appendFilesManifest,
+  assertCanServe,
   buildQuote,
   createPanalClient,
+  LoopDetected,
   MAINNET_ADDRESSES,
+  parseEnvelope,
   parsePaymentHeader,
   permitNonce,
   readPermitDomain,
   sanitizeFileName,
   TaskStatus,
   verifyAndSettle,
+  type CallEnvelope,
   type DeliveredFile,
   type PermitDomain,
 } from '@panal/sdk';
@@ -42,7 +46,8 @@ 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 { TaskFile, TaskResult } from './agent.js';
+import type { TaskContext, TaskFile, TaskResult } from './agent.js';
+import { arrancarVigilante } from './vigilante.js';
 
 const PORT = Number(process.env.PORT ?? 8787);
 const DATA_DIR = process.env.DATA_DIR ?? './data';
@@ -98,6 +103,43 @@ if (X402_PRICE !== null) {
   console.log(`Cobro por llamada activo: ${process.env.X402_PRICE} ${X402_SYMBOL} en POST /x402/ask`);
 }
 
+// ---------------------------------------------------------------------------
+// SUBCONTRATAR: lo que tu agente puede gastarse en preguntar a otros
+// ---------------------------------------------------------------------------
+//
+// Tu agente puede pagar a otro por lo que no sepa hacer (ver `ctx.consultar` en
+// agent.ts). Eso es dinero suyo saliendo, así que necesita un tope, y el tope
+// se pone AQUÍ y no en el prompt: un prompt se negocia, un número no.
+//
+// Va en la moneda del x402 —$PANAL por defecto— y NO se deduce de lo que cobras
+// por la tarea. Es tentador decir "que gaste como mucho el 30 % de lo que le
+// pagan", pero una tarea se cobra en MON y una consulta se paga en $PANAL: son
+// monedas distintas sin tipo de cambio, y convertir una en otra a ojo sería
+// inventarse el presupuesto. Si no pones nada, tu agente no delega.
+//
+//   SUBCONTRATA_MAX=0.5     # como mucho 0,5 $PANAL por encargo
+//   SUBCONTRATA_SALTOS=2    # cuántos agentes puede encadenar (tope duro: 8)
+//
+const SUBCONTRATA_MAX = (() => {
+  const raw = process.env.SUBCONTRATA_MAX?.trim();
+  if (!raw) return 0n;
+  try {
+    const wei = parseEther(raw);
+    return wei > 0n ? wei : 0n;
+  } catch {
+    console.error(`SUBCONTRATA_MAX="${raw}" no es un número válido: tu agente no subcontratará.`);
+    return 0n;
+  }
+})();
+const SUBCONTRATA_SALTOS = (() => {
+  const n = Number(process.env.SUBCONTRATA_SALTOS?.trim() || '2');
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 2;
+})();
+
+if (SUBCONTRATA_MAX > 0n) {
+  console.log(`Subcontratación activa: hasta ${process.env.SUBCONTRATA_MAX} ${X402_SYMBOL} por encargo`);
+}
+
 /**
  * El dominio EIP-712 del token, leído de la cadena una sola vez.
  *
@@ -131,6 +173,32 @@ function loadResult(taskId: bigint): string | null {
   }
 }
 
+/**
+ * El encargo recibido, guardado en cuanto llega y antes de trabajar.
+ *
+ * No es un caché: es lo único que permite retomar una tarea si el proceso se
+ * muere a mitad. El escrow guarda `keccak256(encargo)`, no el encargo, así que
+ * si no lo guardas tú aquí, un reinicio lo pierde para siempre y la tarea se
+ * queda abierta con el dinero del cliente dentro hasta que vence el plazo.
+ */
+const briefPath = (taskId: bigint) => join(DATA_DIR, `brief-${taskId}.txt`);
+function saveBrief(taskId: bigint, text: string): void {
+  try {
+    writeFileSync(briefPath(taskId), text, 'utf8');
+  } catch (err) {
+    // No se aborta: perder la copia solo cuesta no poder retomar. Trabajar
+    // ahora mismo sigue siendo posible, y es lo que el cliente está esperando.
+    console.error(`[panal] #${taskId} no se pudo guardar el encargo: ${err instanceof Error ? err.message : err}`);
+  }
+}
+function loadBrief(taskId: bigint): string | null {
+  try {
+    return readFileSync(briefPath(taskId), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Guarda en disco los archivos de una entrega y devuelve su manifiesto.
  *
@@ -194,18 +262,71 @@ async function signedBy(message: string, signature: string, expected: Address):
 // El trabajo
 // ---------------------------------------------------------------------------
 
-async function work(taskId: bigint, brief: string): Promise<void> {
+/**
+ * Monta el contexto que recibe tu `handleTask`, con la capacidad de delegar.
+ *
+ * `consultar` es lo que convierte a tu agente en cliente de otro: busca en el
+ * mercado quién sabe hacer eso, pide precio a los candidatos —gratis, con el
+ * 402—, se queda con el más barato que quepa en el presupuesto, le paga y
+ * devuelve su respuesta.
+ *
+ * Los tres límites se aplican antes de firmar ningún pago:
+ *
+ *   - PRESUPUESTO. Nunca más de SUBCONTRATA_MAX, y si esta llamada viene de
+ *     otro agente, nunca más de lo que quede en el sobre. Heredar una cadena
+ *     no puede AMPLIAR lo que autorizó quien la empezó.
+ *   - PROFUNDIDAD. Cada salto gasta uno. Al llegar a cero hay que resolver solo.
+ *   - CICLOS. Si tu agente ya aparece en el camino, se corta: A→B→C→A daría
+ *     vueltas cobrando en cada una.
+ *
+ * Si algo de eso falta, `consultar` lanza. No lo captures en silencio: que tu
+ * agente entregue algo peor porque no pudo delegar es información que el autor
+ * necesita ver en los logs.
+ */
+function contexto(
+  base: { taskId: bigint | null; client: string; amount: bigint; deadline: bigint },
+  sobre: CallEnvelope | null,
+): TaskContext {
+  return {
+    ...base,
+    envelope: sobre,
+    presupuesto: SUBCONTRATA_MAX,
+    consultar: async (skill: string, pregunta: string) => {
+      if (SUBCONTRATA_MAX <= 0n) {
+        throw new Error(
+          'Este agente no tiene presupuesto para subcontratar: pon SUBCONTRATA_MAX en el .env si quieres que delegue.',
+        );
+      }
+      const res = await panal.ask(skill, pregunta, {
+        maxSpend: SUBCONTRATA_MAX,
+        depth: SUBCONTRATA_SALTOS,
+        // El sobre recibido, si lo hay. Sin él se abre una cadena nueva.
+        envelope: sobre,
+        // Sin esto un agente que busca su propia skill se contrataría a sí
+        // mismo, se pagaría a sí mismo y se quedaría esperando su respuesta.
+        exclude: [account.address],
+      });
+      console.log(
+        `[panal] consulta a ${res.agent} por ${res.paid} (${skill}) · trace ${sobre?.trace ?? 'nuevo'}`,
+      );
+      return res.answer;
+    },
+  };
+}
+
+async function work(taskId: bigint, brief: string, sobre: CallEnvelope | null): Promise<void> {
   const key = taskId.toString();
   if (inFlight.has(key)) return;
   inFlight.add(key);
   try {
+    // 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);
     const task = await panal.getTask(taskId);
-    const salida = await handleTask(brief, {
-      taskId,
-      client: task.client,
-      amount: task.amount,
-      deadline: task.deadline,
-    });
+    const salida = await handleTask(
+      brief,
+      contexto({ taskId, client: task.client, amount: task.amount, deadline: task.deadline }, sobre),
+    );
 
     // 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
@@ -378,6 +499,22 @@ const server = createServer((req, res) => {
         return;
       }
 
+      // El sobre, antes que nada. Cortar el ciclo aquí importa más que en el
+      // escrow: en x402 el cobro va ANTES de trabajar, así que una vuelta de
+      // más no es tiempo perdido, es dinero cobrado por dar vueltas. Y va
+      // antes del 402 a propósito: si la cadena está viciada, ni se cotiza.
+      const sobre = parseEnvelope(req.headers);
+      try {
+        assertCanServe(sobre, account.address);
+      } catch (err) {
+        if (err instanceof LoopDetected) {
+          console.error(`[x402] ciclo cortado: ${err.message}`);
+          json(res, 508, { error: err.message, trace: err.trace });
+          return;
+        }
+        throw err;
+      }
+
       const domain = await dominioPermit();
       const pagoCrudo = req.headers['x-payment'];
 
@@ -431,12 +568,10 @@ const server = createServer((req, res) => {
       // 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,
-        });
+        const salida = await handleTask(
+          prompt,
+          contexto({ taskId: null, client: leido.payment.payer, amount: cobro.amount, deadline: 0n }, 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
         // tienen dónde agarrarse. Se responde el texto y se avisa en el log en
@@ -489,6 +624,23 @@ const server = createServer((req, res) => {
         return;
       }
       const taskId = BigInt(idCrudo);
+
+      // El sobre de la cadena, si este encargo viene de otro agente. Se mira
+      // ANTES de leer la tarea: si es un ciclo, hasta el eth_call sobra.
+      const sobre = parseEnvelope(req.headers);
+      try {
+        assertCanServe(sobre, account.address);
+      } catch (err) {
+        if (err instanceof LoopDetected) {
+          // 508 Loop Detected. Existe para esto exactamente, y decirlo con el
+          // código correcto deja que quien llama lo distinga de un fallo suyo.
+          console.error(`[panal] ciclo cortado en #${taskId}: ${err.message}`);
+          json(res, 508, { error: err.message, trace: err.trace });
+          return;
+        }
+        throw err;
+      }
+
       const task = await panal.getTask(taskId);
 
       // Cuatro comprobaciones, y las cuatro importan: que la tarea sea tuya,
@@ -526,7 +678,7 @@ const server = createServer((req, res) => {
 
       json(res, 202, { ok: true });
       // Sin await: el cliente no debería esperar a que termines de trabajar.
-      void work(taskId, body.brief);
+      void work(taskId, body.brief, sobre);
       return;
     }
 
@@ -621,3 +773,28 @@ const server = createServer((req, res) => {
 });
 
 server.listen(PORT);
+
+// El vigilante. Va DESPUÉS de escuchar: su primer repaso puede tardar unos
+// segundos contra el RPC, y durante ese rato el agente ya tiene que estar
+// atendiendo peticiones normales.
+arrancarVigilante({
+  panal,
+  yo: account.address,
+  dataDir: DATA_DIR,
+  briefGuardado: loadBrief,
+  // La misma guarda que usa work(): una sola fuente de verdad sobre qué se
+  // está trabajando ahora mismo.
+  enCurso: (taskId) => inFlight.has(taskId.toString()),
+  resultadoGuardado: loadResult,
+  // Retomar un trabajo a medias es exactamente lo mismo que hacerlo la primera
+  // vez. El sobre va en null: la cadena que lo trajo ya no existe —el proceso
+  // que la sostenía murió—, así que esta reanudación no puede seguir gastando
+  // en nombre de nadie. Si el encargo necesitaba subcontratar, lo hará con el
+  // presupuesto propio de este agente y no con el de quien llamó.
+  trabajar: (taskId, brief) => work(taskId, brief, null),
+  reentregar: async (taskId, texto) => {
+    const { txHash } = await panal.deliverResult(taskId, texto);
+    console.log(`[vigilante] #${taskId} entregada al segundo intento · tx ${txHash}`);
+  },
+  urlPublica: process.env.PUBLIC_URL?.trim(),
+});

package/template/src/vigilante.ts

@@ -0,0 +1,244 @@
+/**
+ * El vigilante: se entera de las tareas aunque nadie llame a la puerta.
+ *
+ * Un agente normal solo trabaja cuando alguien le hace POST /brief. Eso deja
+ * tres agujeros que cuestan dinero de verdad, y los tres han pasado:
+ *
+ *   1. EL ENCARGO QUE NO LLEGÓ. El cliente pagó on-chain y el push del brief
+ *      falló —móvil, wallet que se traga la firma, pestaña cerrada, tu agente
+ *      caído dos minutos—. El pago se queda bloqueado y tú no te enteras.
+ *   2. EL TRABAJO A MEDIAS. Recibiste el encargo, te pusiste a trabajar y el
+ *      proceso murió. Al arrancar no queda ni rastro: la tarea sigue abierta
+ *      para siempre.
+ *   3. LA ENTREGA QUE NO SE ANCLÓ. Terminaste el trabajo, lo guardaste, y la
+ *      transacción de entrega falló. Tienes el resultado en disco y el cliente
+ *      no tiene nada.
+ *
+ * LO QUE NO PUEDE HACER, y conviene tenerlo claro antes de esperarlo: el
+ * escrow guarda `keccak256(encargo)`, no el encargo. Un vigilante que ve una
+ * tarea nueva sabe que existe, de quién es y cuánto paga, pero NO qué le
+ * pidieron. Si el encargo nunca llegó, no hay nada que inventar: se avisa con
+ * el enlace de reenvío y se espera. Adivinar sería entregar cualquier cosa
+ * anclando su hash, que es peor que no entregar.
+ *
+ * SE SONDEA, NO SE ESCUCHAN EVENTOS. `eth_getLogs` del RPC público está
+ * limitado a 100 bloques, así que un agente parado veinte minutos ya no puede
+ * recuperar su propio hueco. Leer el contador de tareas y mirar las nuevas es
+ * una llamada cada vuelta, funciona igual tras cualquier parón y no depende de
+ * que el RPC conserve nada.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { keccak256, toBytes } from 'viem';
+import type { Address } from 'viem';
+import { TaskStatus, type PanalClient } from '@panal/sdk';
+
+export interface VigilanteDeps {
+  panal: PanalClient;
+  /** La dirección de este agente. */
+  yo: Address;
+  /** Dónde guardar hasta dónde se miró. */
+  dataDir: string;
+  /** Trabaja una tarea de la que YA se tiene el encargo. */
+  trabajar: (taskId: bigint, brief: string) => Promise<void>;
+  /**
+   * ¿Se está trabajando esa tarea AHORA MISMO?
+   *
+   * Sin esto, el vigilante no sabe distinguir un trabajo en curso de uno
+   * muerto: los dos se ven igual desde fuera —tarea abierta, encargo en disco,
+   * sin resultado—. Se vio en la primera prueba real, donde anunció que
+   * retomaba una tarea que estaba corriendo tan tranquila. No llegó a
+   * duplicarla porque `work` tiene su propia guarda, pero el aviso era falso, y
+   * un trabajo más largo que el intervalo lo repetiría en cada vuelta.
+   */
+  enCurso: (taskId: bigint) => boolean;
+  /** El encargo recibido, si se guardó. */
+  briefGuardado: (taskId: bigint) => string | null;
+  /** El resultado ya calculado, si lo hay. */
+  resultadoGuardado: (taskId: bigint) => string | null;
+  /** Reintenta anclar un resultado que ya está calculado. */
+  reentregar: (taskId: bigint, texto: string) => Promise<void>;
+  /** URL pública del agente, para el aviso de encargo huérfano. */
+  urlPublica?: string;
+}
+
+/** Cada cuánto se mira, en segundos. */
+const CADA = (() => {
+  const n = Number(process.env.VIGILANTE_SEGUNDOS?.trim() || '60');
+  // Menos de 15 s no aporta nada y sí gasta el límite del RPC.
+  return Number.isFinite(n) && n >= 15 ? Math.floor(n) : 60;
+})();
+
+/**
+ * Cuánto se espera antes de dar por perdido un encargo.
+ *
+ * El camino normal es: la transacción se mina y el cliente empuja el encargo
+ * unos segundos después. Sin esta espera, el vigilante gritaría en cada tarea
+ * legítima y el aviso dejaría de significar nada.
+ */
+const GRACIA_MS = 3 * 60 * 1000;
+
+/** Cuántas tareas hacia atrás se miran al arrancar sin marca previa. */
+const REPASO_INICIAL = 50n;
+
+export function arrancarVigilante(deps: VigilanteDeps): { parar: () => void } {
+  if (process.env.VIGILANTE === 'off') {
+    console.log('Vigilante desactivado (VIGILANTE=off).');
+    return { parar: () => {} };
+  }
+
+  const marcaPath = join(deps.dataDir, 'vigilante.json');
+  /** Tareas vistas sin encargo, con el momento en que se vieron. */
+  const huerfanas = new Map<string, number>();
+  /** De las que ya se avisó, para no repetir el aviso cada vuelta. */
+  const avisadas = new Set<string>();
+  let parado = false;
+
+  const leerMarca = (): bigint => {
+    try {
+      const raw = JSON.parse(readFileSync(marcaPath, 'utf8')) as { visto?: string };
+      return BigInt(raw.visto ?? '0');
+    } catch {
+      return -1n; // sin marca: se hace el repaso inicial
+    }
+  };
+  const escribirMarca = (visto: bigint): void => {
+    try {
+      writeFileSync(marcaPath, JSON.stringify({ visto: visto.toString() }, null, 2));
+    } catch (err) {
+      // Perder la marca solo cuesta repetir el repaso, así que no se para nada.
+      console.error(`[vigilante] no se pudo guardar la marca: ${err instanceof Error ? err.message : err}`);
+    }
+  };
+
+  async function repasar(): Promise<void> {
+    const total = await deps.panal.getTaskCount();
+    const marca = leerMarca();
+    // La primera vez se miran las últimas REPASO_INICIAL en vez de las 30.000
+    // que pueda haber: las viejas están cerradas y no cambian.
+    const desde = marca >= 0n ? marca + 1n : total > REPASO_INICIAL ? total - REPASO_INICIAL : 0n;
+
+    // Las nuevas, más las que quedaron pendientes de vueltas anteriores.
+    const pendientes = new Set<string>(huerfanas.keys());
+    for (let i = desde; i < total; i++) pendientes.add(i.toString());
+    if (pendientes.size === 0) {
+      escribirMarca(total - 1n);
+      return;
+    }
+
+    for (const id of pendientes) {
+      if (parado) return;
+      const taskId = BigInt(id);
+      try {
+        await revisarUna(taskId);
+      } catch (err) {
+        console.error(`[vigilante] #${taskId}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+    escribirMarca(total - 1n);
+  }
+
+  async function revisarUna(taskId: bigint): Promise<void> {
+    const task = await deps.panal.getTask(taskId);
+    const id = taskId.toString();
+
+    // Ni mía, ni viva: fuera de la lista y a otra cosa.
+    if (task.worker.toLowerCase() !== deps.yo.toLowerCase()) {
+      huerfanas.delete(id);
+      return;
+    }
+    if (task.status !== TaskStatus.Open) {
+      huerfanas.delete(id);
+      avisadas.delete(id);
+      return;
+    }
+
+    // Se está trabajando ahora mismo: no es un hueco, es el camino normal. Ni
+    // se retoma, ni se avisa de que falte el encargo — lo tiene y lo está
+    // usando. El vigilante solo se ocupa de lo que ya no se mueve.
+    if (deps.enCurso(taskId)) {
+      huerfanas.delete(id);
+      return;
+    }
+
+    // CASO 3: el resultado está calculado y la tarea sigue abierta, así que la
+    // entrega no llegó a anclarse. Se reintenta, que es gratis para el cliente
+    // y le devuelve una tarea que daba por perdida.
+    const resultado = deps.resultadoGuardado(taskId);
+    if (resultado !== null) {
+      console.log(`[vigilante] #${taskId} tenía resultado sin anclar: se reintenta la entrega`);
+      await deps.reentregar(taskId, resultado);
+      huerfanas.delete(id);
+      return;
+    }
+
+    // CASO 2: el encargo está guardado pero no hay resultado, o sea que el
+    // trabajo se quedó a medias. Se retoma.
+    const brief = deps.briefGuardado(taskId);
+    if (brief !== null) {
+      // Se comprueba el hash ANTES de trabajar. El archivo lleva en disco desde
+      // otra ejecución y no vale fiarse: si no cuadra con lo que hay en la
+      // cadena, trabajar sobre él sería entregar algo que el cliente no pidió.
+      if (keccak256(toBytes(brief)) !== task.taskHash) {
+        console.error(
+          `[vigilante] #${taskId} el encargo guardado NO cuadra con el taskHash de la cadena: se ignora`,
+        );
+        huerfanas.delete(id);
+        return;
+      }
+      console.log(`[vigilante] #${taskId} se quedó a medias: se retoma el trabajo`);
+      await deps.trabajar(taskId, brief);
+      huerfanas.delete(id);
+      return;
+    }
+
+    // CASO 1: hay tarea y no hay encargo. Aquí no se puede hacer nada más que
+    // avisar: el texto no está en la cadena y adivinarlo sería inventárselo.
+    const visto = huerfanas.get(id);
+    if (visto === undefined) {
+      huerfanas.set(id, Date.now());
+      return;
+    }
+    if (Date.now() - visto < GRACIA_MS || avisadas.has(id)) return;
+
+    avisadas.add(id);
+    // En cuánto vence, no cuándo. La fecha absoluta se imprimía en UTC junto a
+    // una marca de log en hora local, y un plazo de dos horas se leía como
+    // vencido. Lo que hace falta saber aquí es cuánto margen queda.
+    const restanMin = Math.round((Number(task.deadline) * 1000 - Date.now()) / 60000);
+    const vence =
+      restanMin <= 0
+        ? 'YA VENCIDO'
+        : restanMin < 60
+          ? `en ${restanMin} min`
+          : `en ${Math.floor(restanMin / 60)} h ${restanMin % 60} min`;
+    console.error(
+      `[vigilante] #${taskId} PAGADA Y SIN ENCARGO. ${task.client} bloqueó su pago hace más de ` +
+        `${Math.round(GRACIA_MS / 60000)} min y el texto no ha llegado nunca. No se puede adivinar: el escrow ` +
+        `solo guarda su hash.\n` +
+        `  Que lo reenvíe desde ${deps.urlPublica ? `${deps.urlPublica}/reenviar?task=${taskId}` : 'tu /reenviar'}` +
+        ` o desde https://panal.lat/dashboard.\n` +
+        `  Si nadie lo hace, el plazo vence ${vence} y el cliente recupera su dinero.`,
+    );
+  }
+
+  console.log(`Vigilante activo: repasa cada ${CADA} s (VIGILANTE=off para apagarlo).`);
+  // Una pasada al arrancar, que es cuando más falta hace: recoge todo lo que
+  // se perdió mientras el proceso estaba caído.
+  void repasar().catch((err) => console.error(`[vigilante] primer repaso: ${err instanceof Error ? err.message : err}`));
+
+  const timer = setInterval(() => {
+    void repasar().catch((err) => console.error(`[vigilante] ${err instanceof Error ? err.message : err}`));
+  }, CADA * 1000);
+  // Sin unref, este intervalo mantiene vivo el proceso para siempre aunque
+  // todo lo demás haya terminado.
+  timer.unref?.();
+
+  return {
+    parar: () => {
+      parado = true;
+      clearInterval(timer);
+    },
+  };
+}