create-panal-agent 0.2.0 → 0.3.0

package/dist/i18n.js

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

package/dist/index.js

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

package/package.json

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

package/template/_package.json

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

package/template/src/agent.ts

@@ -12,16 +12,24 @@
  */
 
 export interface TaskContext {
-  /** El id de la tarea en el escrow, por si quieres registrarlo. */
-  taskId: bigint;
-  /** La dirección del cliente que te contrató. */
+  /**
+   * El id de la tarea en el escrow, o `null` si esto es una llamada x402: ahí
+   * no hay tarea ni plazo, te pagaron en el momento y respondes en el acto.
+   */
+  taskId: bigint | null;
+  /** La dirección del cliente que te contrató (o que acaba de pagarte). */
   client: string;
   /** Cuánto vas a cobrar, en unidades mínimas (wei). */
   amount: bigint;
-  /** Fecha límite de entrega, en segundos epoch. */
+  /** Fecha límite de entrega, en segundos epoch. Cero en una llamada x402. */
   deadline: bigint;
 }
 
+/** Cómo se llama esto en los logs: `#31` si viene del escrow, `x402` si no. */
+function etiqueta(ctx: TaskContext): string {
+  return ctx.taskId === null ? 'x402' : `#${ctx.taskId}`;
+}
+
 /**
  * Tu agente.
  *
@@ -49,6 +57,65 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<strin
     );
   }
 
+  // Un intento, una revisión y una corrección. Un modelo falla el formato de
+  // vez en cuando, y aquí eso no es un mensaje feo en un chat: el hash de lo
+  // que entregues queda anclado en la cadena y ya no se puede rectificar.
+  let queja: string | null = null;
+  for (let intento = 1; intento <= 2; intento++) {
+    const texto = await pedirAlModelo(brief, apiKey, queja);
+    const problema = revisar(brief, texto);
+    if (!problema) {
+      console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
+      return texto;
+    }
+    console.error(`[agente] ${etiqueta(ctx)} intento ${intento}: ${problema}`);
+    // A la segunda se entrega igual. Tu revisión puede equivocarse, y un falso
+    // positivo no debe costarle al cliente la tarea que ya pagó: es mejor
+    // entregar algo imperfecto y que él decida, que dejarlo sin nada.
+    if (intento === 2) {
+      console.error(`[agente] ${etiqueta(ctx)} se entrega pese a: ${problema}`);
+      return texto;
+    }
+    queja = problema;
+  }
+  throw new Error('inalcanzable');
+}
+
+/**
+ * TU CONTROL DE CALIDAD. Devuelve null si la respuesta vale, o el motivo si no.
+ *
+ * Lo que devuelvas aquí se le manda al modelo en el segundo intento, así que
+ * escribe el motivo como se lo dirías a él: "faltan los puertos 8790 y 8791"
+ * corrige mucho más que "respuesta incompleta".
+ *
+ * Merece la pena rellenarlo con lo que TU agente promete. Un ejemplo real: un
+ * agente que convertía texto a JSON recibió tres registros y devolvió uno,
+ * tirando los otros dos. Era JSON válido, así que ninguna comprobación de
+ * formato se enteró, y el cliente pagó por un tercio de su encargo. Se detectó
+ * comparando los números del encargo con los de la respuesta:
+ *
+ *     const perdidos = [...new Set(brief.match(/\d{2,}/g) ?? [])]
+ *       .filter((n) => !resultado.includes(n));
+ *     if (perdidos.length) return `faltan datos del encargo: ${perdidos.join(', ')}`;
+ *
+ * Ojo: eso vale para un agente que extrae datos, y es un desastre para uno que
+ * resume o traduce, donde descartar cifras es su trabajo. Comprueba lo que tú
+ * prometes, no lo que promete otro.
+ */
+function revisar(brief: string, resultado: string): string | null {
+  if (!resultado.trim()) return 'la respuesta vino vacía';
+
+  // El prompt de abajo prohíbe Markdown, porque ni el dashboard ni Telegram lo
+  // renderizan y el cliente ve los asteriscos en crudo. Pedirlo no basta: hay
+  // que comprobarlo.
+  if (/(\*\*|^#{1,6}\s|```)/m.test(resultado)) {
+    return 'la respuesta lleva Markdown (**, # o ```) y el cliente lo verá en crudo: devuélvela en texto plano';
+  }
+
+  return null;
+}
+
+async function pedirAlModelo(brief: string, apiKey: string, queja: string | null): Promise<string> {
   const res = await fetch(`${process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1'}/chat/completions`, {
     method: 'POST',
     headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
@@ -75,6 +142,9 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<strin
             'RULE 3: deliver finished professional work, with no preamble or meta-commentary.',
         },
         { role: 'user', content: brief },
+        // La corrección va como un mensaje más: decirle QUÉ falló acierta mucho
+        // más que repetirle la misma petición a ciegas esperando otra suerte.
+        ...(queja ? [{ role: 'user' as const, content: `Tu respuesta anterior no vale: ${queja}. Corrígela.` }] : []),
       ],
     }),
   });
@@ -83,7 +153,5 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<strin
   const data = (await res.json()) as { choices?: { message?: { content?: string } }[] };
   const text = data.choices?.[0]?.message?.content?.trim();
   if (!text) throw new Error('El modelo devolvió una respuesta vacía.');
-
-  console.log(`[agente] #${ctx.taskId} resuelta: ${text.length} caracteres`);
   return text;
 }

package/template/src/server.ts

@@ -24,9 +24,19 @@ import 'dotenv/config';
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { createPanalClient, TaskStatus } from '@panal/sdk';
+import {
+  buildQuote,
+  createPanalClient,
+  MAINNET_ADDRESSES,
+  parsePaymentHeader,
+  permitNonce,
+  readPermitDomain,
+  TaskStatus,
+  verifyAndSettle,
+  type PermitDomain,
+} from '@panal/sdk';
 import { privateKeyToAccount } from 'viem/accounts';
-import { keccak256, toBytes, verifyMessage } from 'viem';
+import { isAddress, keccak256, parseEther, toBytes, verifyMessage } from 'viem';
 import type { Address } from 'viem';
 import { handleTask } from './agent.js';
 
@@ -45,6 +55,58 @@ const panal = createPanalClient({ account, rpcUrl: process.env.RPC_URL });
 
 console.log(`Agente ${account.address} escuchando en :${PORT}`);
 
+// ---------------------------------------------------------------------------
+// x402: cobrar por llamada, sin escrow.
+//
+// El escrow es para encargos que valen algo: bloquea el pago, hay plazo y hay
+// disputa. Para una consulta de dos milésimas todo eso sobra —el trámite cuesta
+// más que el servicio—, y ahí entra x402: el cliente firma una autorización de
+// pago (gratis, sin gas), tú cobras y respondes en la misma llamada.
+//
+// Es OPCIONAL: sin X402_PRICE en el .env, esta ruta no existe y tu agente
+// funciona igual solo con encargos del escrow.
+//
+// Solo se puede cobrar en un ERC-20 con EIP-2612, no en MON: el esquema entero
+// se apoya en `permit`, y la moneda nativa no lo tiene.
+// ---------------------------------------------------------------------------
+
+const X402_PRICE = (() => {
+  const raw = process.env.X402_PRICE?.trim();
+  if (!raw) return null;
+  try {
+    const wei = parseEther(raw);
+    return wei > 0n ? wei : null;
+  } catch {
+    console.error(`X402_PRICE="${raw}" no es un número válido: el cobro por llamada queda desactivado.`);
+    return null;
+  }
+})();
+const X402_TOKEN: Address = (() => {
+  const raw = process.env.X402_TOKEN?.trim();
+  return raw && isAddress(raw) ? (raw as Address) : MAINNET_ADDRESSES.panalToken;
+})();
+const X402_SYMBOL = process.env.X402_SYMBOL?.trim() || '$PANAL';
+// En inglés porque viaja en el 402 y lo lee un desconocido de cualquier parte.
+// Cámbialo por lo tuyo con X402_DESCRIPTION en el .env.
+const X402_DESCRIPTION = process.env.X402_DESCRIPTION?.trim() || 'One question to the agent, answered on the spot.';
+
+if (X402_PRICE !== null) {
+  console.log(`Cobro por llamada activo: ${process.env.X402_PRICE} ${X402_SYMBOL} en POST /x402/ask`);
+}
+
+/**
+ * El dominio EIP-712 del token, leído de la cadena una sola vez.
+ *
+ * Se cachea porque no cambia nunca y leerlo en cada petición añade una llamada
+ * al RPC al camino de una respuesta que cobras al momento. Si el RPC falla, se
+ * vuelve a intentar en la siguiente: no se cachea el error.
+ */
+let dominioCache: PermitDomain | null = null;
+async function dominioPermit(): Promise<PermitDomain> {
+  if (!dominioCache) dominioCache = await readPermitDomain(panal.publicClient, X402_TOKEN);
+  return dominioCache;
+}
+
 // ---------------------------------------------------------------------------
 // Almacén: los resultados en disco, para poder servirlos después.
 // ---------------------------------------------------------------------------
@@ -224,8 +286,114 @@ const server = createServer((req, res) => {
     }
 
     // Tarjeta de presentación: quién eres y qué sabes hacer.
+    //
+    // Si cobras por llamada hay que ANUNCIARLO aquí. Durante meses el bot de
+    // LexPanal tuvo x402 funcionando y nadie lo usó, sencillamente porque no
+    // salía en su tarjeta: un cobro que nadie puede descubrir no existe.
     if (url.pathname === '/agent.json' && req.method === 'GET') {
-      json(res, 200, { agent: account.address, protocol: 'panal', network: 'monad-mainnet' });
+      json(res, 200, {
+        agent: account.address,
+        protocol: 'panal',
+        network: 'monad-mainnet',
+        ...(X402_PRICE !== null
+          ? {
+              x402Ask: {
+                method: 'POST',
+                path: '/x402/ask',
+                scheme: 'eip2612-permit',
+                asset: X402_TOKEN,
+                assetSymbol: X402_SYMBOL,
+                amount: X402_PRICE.toString(),
+                payTo: account.address,
+                howTo: 'POST {"prompt":"…"} and you get a 402 with the quote. Sign it and repeat with X-Payment.',
+              },
+            }
+          : {}),
+      });
+      return;
+    }
+
+    // ---- Cobro por llamada: pagas y te respondo en el acto ------------------
+    if (url.pathname === '/x402/ask' && req.method === 'POST') {
+      if (X402_PRICE === null) {
+        json(res, 404, { error: 'this agent does not charge per call; hire it through the escrow' });
+        return;
+      }
+      const body = JSON.parse(await readBody(req)) as { prompt?: string };
+      const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
+      if (!prompt || prompt.length > 2000) {
+        json(res, 400, { error: 'prompt required, max 2000 characters' });
+        return;
+      }
+
+      const domain = await dominioPermit();
+      const pagoCrudo = req.headers['x-payment'];
+
+      // Sin pago: se responde 402 con el presupuesto. Este es el paso que le da
+      // por fin sentido a un código de estado que llevaba desde los noventa
+      // reservado y sin usar, porque no había forma de pagar en la web.
+      if (typeof pagoCrudo !== 'string' || !pagoCrudo.trim()) {
+        // Si el cliente dice quién es, se le regala su nonce y se ahorra una
+        // consulta a la cadena antes de poder firmar.
+        const quien = req.headers['x-payment-payer'];
+        const payer = typeof quien === 'string' && isAddress(quien) ? (quien as Address) : null;
+        const nonce = payer ? await permitNonce(panal.publicClient, X402_TOKEN, payer).catch(() => undefined) : undefined;
+
+        res.setHeader('www-authenticate', `eip2612-permit realm="panal", chain="${domain.chainId}"`);
+        json(
+          res,
+          402,
+          buildQuote({
+            asset: X402_TOKEN,
+            assetSymbol: X402_SYMBOL,
+            amount: X402_PRICE,
+            payTo: account.address,
+            resource: '/x402/ask',
+            description: X402_DESCRIPTION,
+            domain,
+            payerNonce: nonce,
+          }),
+        );
+        return;
+      }
+
+      const leido = parsePaymentHeader(pagoCrudo);
+      if (!leido.ok) {
+        json(res, 400, { error: leido.error });
+        return;
+      }
+
+      // SE COBRA ANTES DE SERVIR. Si se sirviera primero y el cobro fallara, el
+      // trabajo estaría regalado y no habría forma de recuperarlo.
+      const cobro = await verifyAndSettle(
+        { publicClient: panal.publicClient, walletClient: panal.walletClient ?? null, token: X402_TOKEN, domain, payee: account.address },
+        leido.payment,
+        X402_PRICE,
+      );
+      if (!cobro.ok) {
+        json(res, cobro.status, { error: cobro.error });
+        return;
+      }
+      console.log(`[x402] cobrado ${cobro.amount} de ${leido.payment.payer} · tx ${cobro.txHash}`);
+
+      // Ya está cobrado: pase lo que pase a partir de aquí, hay que responder
+      // algo. Si el modelo revienta, se dice; callarse sería quedarse el dinero.
+      try {
+        const answer = await handleTask(prompt, {
+          taskId: null,
+          client: leido.payment.payer,
+          amount: cobro.amount,
+          deadline: 0n,
+        });
+        res.setHeader('x-payment-tx', cobro.txHash);
+        json(res, 200, { answer, paid: { txHash: cobro.txHash, amount: cobro.amount.toString(), asset: X402_TOKEN } });
+      } catch (err) {
+        console.error(`[x402] cobrado pero falló al responder: ${err instanceof Error ? err.message : err}`);
+        json(res, 502, {
+          error: 'the payment went through but the agent could not answer',
+          paid: { txHash: cobro.txHash, amount: cobro.amount.toString() },
+        });
+      }
       return;
     }