create-panal-agent 0.1.2 → 0.2.0

package/dist/index.js

@@ -2,20 +2,26 @@
 /**
  * create-panal-agent — genera un agente de Panal listo para funcionar.
  *
- *   npx create-panal-agent mi-agente
+ *   npx create-panal-agent mi-agente [--lang es] [--no-input]
  *
- * Copia la plantilla, le pone el nombre, y genera una wallet dedicada nueva
- * para el agente. Después son tres pasos: instalar, publicar el endpoint y
- * registrarse.
+ * Copia la plantilla, le pone el nombre, genera una wallet dedicada nueva y
+ * escribe la documentación del proyecto en el idioma de quien lo ejecuta.
+ * Después son tres pasos: instalar, publicar el endpoint y registrarse.
  *
  * Por qué existe: antes, poner un agente en Panal significaba leer una guía de
  * 529 líneas, montar un VPS y mantenerlo encendido. Eso no es un alta, es un
  * trabajo — y explica por qué el marketplace tenía cinco agentes.
+ *
+ * Por qué en diez idiomas: el alta es lo primero que ve un desarrollador, y en
+ * ella van las tres cosas que salen caras si se malinterpretan —la clave
+ * privada, el endpoint público y el gas—. Un aviso que no se entiende es un
+ * aviso que no existe.
  */
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { CATALOG, LANGS, fill, isLang, resolveLang } from './i18n.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** La plantilla se empaqueta junto al binario (ver `files` del package.json). */
 const TEMPLATE = resolve(HERE, '..', 'template');
@@ -34,33 +40,81 @@ const RENAMES = {
     _gitignore: '.gitignore',
 };
 const c = {
-    bold: (s) => `${s}`,
-    dim: (s) => `${s}`,
-    green: (s) => `${s}`,
-    yellow: (s) => `${s}`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
 };
 function fail(msg) {
     console.error(`\n${msg}\n`);
     process.exit(1);
 }
+/**
+ * Se admite `--lang es` y `--lang=es`. No es capricho: la primera forma es la
+ * que teclea una persona y la segunda la que escriben los scripts.
+ */
+function parseArgs(argv) {
+    const args = { name: null, lang: null, noInput: false, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h')
+            args.help = true;
+        else if (a === '--version' || a === '-v')
+            args.version = true;
+        else if (a === '--no-input' || a === '--yes' || a === '-y')
+            args.noInput = true;
+        else if (a === '--lang')
+            args.lang = argv[++i] ?? '';
+        else if (a.startsWith('--lang='))
+            args.lang = a.slice('--lang='.length);
+        else if (!a.startsWith('-') && args.name === null)
+            args.name = a;
+    }
+    return args;
+}
 /** Nombre válido de carpeta y de paquete npm. */
-function validateName(raw) {
-    const name = raw.trim().replace(/^\.\//, '');
+function validateName(raw, t) {
+    const name = (raw ?? '').trim().replace(/^\.\//, '');
     if (!name)
-        fail('Dile cómo se llama tu agente:  npx create-panal-agent mi-agente');
-    if (!/^[a-z0-9][a-z0-9._-]*$/.test(name)) {
-        fail(`"${name}" no vale como nombre.\n` +
-            'Usa minúsculas, números y guiones: mi-agente, traductor-tecnico, resumidor.');
-    }
+        fail(t.errNoName);
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(name))
+        fail(fill(t.errBadName, { name }));
     return name;
 }
+/**
+ * Selector interactivo. Solo aparece cuando hay una persona delante: sin TTY
+ * —en CI, en un Dockerfile, tras una tubería— preguntar cuelga el proceso, así
+ * que en ese caso se cae al inglés sin ruido.
+ */
+async function askLang() {
+    const { createInterface } = await import('node:readline/promises');
+    console.log('');
+    LANGS.forEach((l, i) => {
+        console.log(`  ${c.bold(String(i + 1).padStart(2))}  ${l.label}${i === 0 ? c.dim('  (default)') : ''}`);
+    });
+    console.log('');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // La pregunta va en inglés porque todavía no sabemos en qué idioma leer.
+        const answer = (await rl.question(`${CATALOG.en.pickLang} [1-${LANGS.length}] `)).trim();
+        const n = Number(answer);
+        if (Number.isInteger(n) && n >= 1 && n <= LANGS.length)
+            return LANGS[n - 1].code;
+        if (isLang(answer.toLowerCase()))
+            return answer.toLowerCase();
+        return 'en';
+    }
+    finally {
+        rl.close();
+    }
+}
 /** Copia la plantilla sustituyendo los marcadores. */
-function copyTemplate(dest, name) {
+function copyTemplate(dest, name, t) {
     cpSync(TEMPLATE, dest, { recursive: true });
     for (const [from, to] of Object.entries(RENAMES)) {
         const src = join(dest, from);
         if (!existsSync(src))
-            fail(`La plantilla está incompleta: falta ${from}. El paquete está mal instalado.`);
+            fail(fill(t.errTemplateMissing, { name: from }));
         renameSync(src, join(dest, to));
     }
     const walk = (dir) => {
@@ -78,38 +132,93 @@ function copyTemplate(dest, name) {
     };
     walk(dest);
 }
-function main() {
-    const name = validateName(process.argv[2] ?? '');
-    const dest = resolve(process.cwd(), name);
-    if (existsSync(dest) && readdirSync(dest).length > 0) {
-        fail(`La carpeta ${name}/ ya existe y no está vacía. Elige otro nombre o bórrala.`);
+/**
+ * El `.env.example` se escribe aquí, no se copia: sus comentarios explican qué
+ * es cada clave y son justo lo que hay que entender antes de pegar una clave
+ * privada en un servidor.
+ */
+function writeEnvExample(dest, t) {
+    const bloque = (texto) => texto
+        .split('\n')
+        .map((l) => `# ${l}`)
+        .join('\n');
+    const contenido = [
+        bloque(t.env.key),
+        'AGENT_PRIVATE_KEY=',
+        '',
+        bloque(t.env.port),
+        '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',
+        'LLM_API_KEY=',
+        'LLM_MODEL=deepseek-chat',
+        '',
+        bloque(t.env.rpc),
+        'RPC_URL=',
+        '',
+        bloque(t.env.data),
+        'DATA_DIR=./data',
+        '',
+    ].join('\n');
+    writeFileSync(join(dest, '.env.example'), contenido, 'utf8');
+    return contenido;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    // --help y --version salen antes que nada: son las dos cosas que se piden
+    // cuando aún no se sabe qué hace el comando.
+    const pedido = resolveLang(args.lang, process.env);
+    if (args.lang && !pedido)
+        fail(fill(CATALOG.en.errBadLang, { name: args.lang }));
+    if (args.version) {
+        const pkg = JSON.parse(readFileSync(resolve(HERE, '..', 'package.json'), 'utf8'));
+        console.log(pkg.version);
+        return;
     }
+    if (args.help) {
+        console.log(`\n${(pedido ? CATALOG[pedido] : CATALOG.en).usage}\n`);
+        return;
+    }
+    // Sin idioma decidido: se pregunta si hay alguien delante, y si no, inglés.
+    const interactivo = !args.noInput && process.stdin.isTTY === true && process.stdout.isTTY === true;
+    const lang = pedido ?? (interactivo ? await askLang() : 'en');
+    const t = CATALOG[lang];
+    const name = validateName(args.name, t);
+    const dest = resolve(process.cwd(), name);
+    if (existsSync(dest) && readdirSync(dest).length > 0)
+        fail(fill(t.errDirExists, { name }));
     if (!existsSync(TEMPLATE))
-        fail(`No encuentro la plantilla en ${TEMPLATE}. El paquete está mal instalado.`);
+        fail(fill(t.errTemplateMissing, { name: TEMPLATE }));
     mkdirSync(dest, { recursive: true });
-    copyTemplate(dest, name);
+    copyTemplate(dest, name, t);
+    const envExample = writeEnvExample(dest, t);
     // Wallet dedicada, generada aquí. La alternativa —"crea una wallet y pega la
     // clave"— es donde la gente acaba pegando la de su MetaMask personal, que es
     // exactamente lo que no debe vivir en un servidor.
     const privateKey = generatePrivateKey();
     const address = privateKeyToAccount(privateKey).address;
-    const envExample = readFileSync(join(dest, '.env.example'), 'utf8');
     writeFileSync(join(dest, '.env'), envExample.replace('AGENT_PRIVATE_KEY=', `AGENT_PRIVATE_KEY=${privateKey}`), 'utf8');
-    console.log(`\n${c.green('✓')} ${c.bold(name)} creado.\n`);
-    console.log(`  Wallet del agente: ${c.bold(address)}`);
-    console.log(c.dim(`  Su clave está en ${name}/.env, que ya está en el .gitignore.\n`));
-    console.log(c.bold('Lo que falta:\n'));
-    console.log(`  ${c.bold('1.')} Instalar y darle algo de MON para el gas`);
-    console.log(c.dim(`       cd ${name} && npm install`));
-    console.log(c.dim(`       manda ~0.5 MON a ${address}\n`));
-    console.log(`  ${c.bold('2.')} Escribir lo que hace tu agente`);
-    console.log(c.dim(`       edita src/agent.ts  ${c.dim('(es el único archivo que tienes que tocar)')}`));
-    console.log(c.dim(`       si usa un modelo, pon LLM_API_KEY en el .env\n`));
-    console.log(`  ${c.bold('3.')} Publicarlo en una URL https y registrarte`);
-    console.log(c.dim(`       npm start           ${c.dim('(y expón el puerto con https)')}`));
-    console.log(c.dim(`       PUBLIC_URL=https://tu-dominio npm run register\n`));
-    console.log(`${c.yellow('Ojo:')} el endpoint tiene que ser https y público. Sin él el cliente no puede`);
-    console.log('mandarte el encargo ni descargar su resultado, y el agente queda de adorno.\n');
-    console.log(c.dim('Guía completa: https://github.com/AgentHiv/Panal/tree/main/create-agent\n'));
+    // El README del proyecto, en su idioma. Es donde vive lo que no cabe en la
+    // pantalla de alta: cómo se cobra, qué hace cada archivo y qué rompe agentes.
+    writeFileSync(join(dest, 'README.md'), fill(t.readme, { name, address }), 'utf8');
+    console.log(`\n${c.green('✓')} ${c.bold(fill(t.created, { name }))}\n`);
+    console.log(`  ${t.walletLabel} ${c.bold(address)}`);
+    console.log(c.dim(`  ${fill(t.walletNote, { name })}\n`));
+    console.log(c.bold(`${t.stepsTitle}\n`));
+    console.log(`  ${c.bold('1.')} ${t.s1Title}`);
+    console.log(c.dim(`       ${fill(t.s1Install, { name })}`));
+    console.log(c.dim(`       ${fill(t.s1Fund, { address })}\n`));
+    console.log(`  ${c.bold('2.')} ${t.s2Title}`);
+    console.log(c.dim(`       ${t.s2Edit}`));
+    console.log(c.dim(`       ${t.s2Key}\n`));
+    console.log(`  ${c.bold('3.')} ${t.s3Title}`);
+    console.log(c.dim(`       ${t.s3Start}`));
+    console.log(c.dim(`       ${t.s3Register}\n`));
+    console.log(`${c.yellow(t.warnLabel)} ${t.warnBody}\n`);
+    console.log(c.dim(`${t.docs}\n`));
 }
-main();
+void main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Crea un agente de IA para Panal, funcionando y cobrando on-chain, en cinco minutos",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/scaffold.test.ts"
+    "test": "tsx test/i18n.test.ts && tsx test/scaffold.test.ts"
   }
 }

package/template/src/agent.ts

@@ -52,6 +52,10 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<strin
   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}` },
+    // 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: [

package/template/src/server.ts

@@ -26,7 +26,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createPanalClient, TaskStatus } from '@panal/sdk';
 import { privateKeyToAccount } from 'viem/accounts';
-import { verifyMessage } from 'viem';
+import { keccak256, toBytes, verifyMessage } from 'viem';
 import type { Address } from 'viem';
 import { handleTask } from './agent.js';
 
@@ -116,6 +116,82 @@ async function work(taskId: bigint, brief: string): Promise<void> {
 // HTTP
 // ---------------------------------------------------------------------------
 
+/**
+ * Página de reenvío manual (GET /reenviar?task=<id>).
+ *
+ * Todo va incrustado: ni CDN ni fuentes ni librerías. Dentro del navegador de
+ * una wallet, cada recurso externo es una cosa más que puede no cargar, y esta
+ * página existe precisamente para cuando algo ya ha fallado.
+ */
+const PAGINA_REENVIO = `<!doctype html>
+<html lang="es"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Reenviar brief · Panal</title>
+<style>
+:root{color-scheme:dark light}
+body{margin:0;padding:24px 18px;font:16px/1.5 system-ui,-apple-system,sans-serif;background:#0f0f11;color:#e8e8ea;max-width:34rem;margin-inline:auto}
+h1{font-size:1.25rem;margin:0 0 .25rem}
+p.sub{margin:0 0 1.5rem;color:#9a9aa2;font-size:.9rem}
+label{display:block;margin:1rem 0 .35rem;font-size:.85rem;color:#b8b8c0}
+input,textarea{width:100%;box-sizing:border-box;padding:.7rem .8rem;border-radius:10px;border:1px solid #33333a;background:#17171b;color:inherit;font:inherit}
+textarea{min-height:9rem;resize:vertical}
+button{width:100%;margin-top:1rem;padding:.85rem;border:0;border-radius:10px;background:#f5c518;color:#1a1a1a;font:600 1rem system-ui;cursor:pointer}
+button.sec{background:#26262c;color:#e8e8ea}
+#estado{margin-top:1.1rem;padding:.8rem;border-radius:10px;font-size:.9rem;white-space:pre-wrap;word-break:break-word}
+#estado.bien{background:#12301c;color:#7ee2a8}
+#estado.mal{background:#33161a;color:#ff9d9d}
+#estado:empty{display:none}
+</style></head><body>
+<h1>Reenviar el brief</h1>
+<p class="sub">Para cuando el envío automático no llegó. Copia el texto exacto del pedido desde panal.lat (botón "Copiar brief del pedido") y pégalo aquí.</p>
+<label for="id">Número de tarea</label>
+<input id="id" inputmode="numeric" placeholder="24">
+<label for="brief">Texto del pedido</label>
+<textarea id="brief" placeholder="Pega aquí el brief, tal cual"></textarea>
+<button id="conectar" class="sec">Conectar wallet</button>
+<button id="enviar">Firmar y enviar</button>
+<div id="estado"></div>
+<script>
+var q = new URLSearchParams(location.search);
+function $(s){ return document.querySelector(s); }
+// Solo dígitos, siempre. Un teclado de móvil cuela un punto sin que lo veas y
+// la petición se va a /brief/25. → 404, con el usuario mirando un número que
+// parece correcto.
+function soloDigitos(v){ return String(v || '').replace(/[^0-9]/g, ''); }
+$('#id').value = soloDigitos(q.get('task'));
+$('#id').addEventListener('input', function(){ this.value = soloDigitos(this.value); });
+var cuenta = null;
+function estado(msg, mal){ var e = $('#estado'); e.textContent = msg; e.className = mal ? 'mal' : 'bien'; }
+$('#conectar').onclick = async function(){
+  if (!window.ethereum) { estado('Aquí no hay wallet. Abre esta página desde el navegador de MetaMask, no desde Chrome.', true); return; }
+  try {
+    var r = await ethereum.request({ method: 'eth_requestAccounts' });
+    cuenta = r[0];
+    $('#conectar').textContent = cuenta.slice(0,6) + '…' + cuenta.slice(-4);
+    estado('Wallet conectada.');
+  } catch (e) { estado('Conexión rechazada.', true); }
+};
+$('#enviar').onclick = async function(){
+  var id = soloDigitos($('#id').value);
+  var brief = $('#brief').value;
+  if (!id || !brief.trim()) { estado('Falta el número de tarea o el texto.', true); return; }
+  if (!cuenta) { estado('Conecta la wallet primero: hay que firmar con la misma que pagó.', true); return; }
+  try {
+    estado('Firma el mensaje en tu wallet. No cuesta gas.');
+    var firma = await ethereum.request({ method: 'personal_sign', params: ['Panal brief #' + id, cuenta] });
+    estado('Enviando…');
+    var res = await fetch('/brief/' + id, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ brief: brief, address: cuenta, signature: firma })
+    });
+    var txt = await res.text();
+    if (res.ok) estado('Aceptado. El agente ya está trabajando en tu pedido.');
+    else estado('Rechazado (' + res.status + '):\\n' + txt, true);
+  } catch (e) { estado('Falló: ' + (e && e.message ? e.message : e), true); }
+};
+</script></body></html>`;
+
 function json(res: ServerResponse, status: number, body: unknown): void {
   res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
   res.end(JSON.stringify(body));
@@ -153,26 +229,50 @@ const server = createServer((req, res) => {
       return;
     }
 
+    // Reenvío manual del brief, para cuando el envío automático del dashboard
+    // no llega: móvil, wallet que se traga la firma, pestaña cerrada a medias.
+    // Se sirve desde el propio agente a propósito: mismo origen, sin CORS de
+    // por medio, y funciona dentro del navegador de una wallet.
+    if (url.pathname === '/reenviar' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      res.end(PAGINA_REENVIO);
+      return;
+    }
+
     // ---- El cliente te manda el encargo -------------------------------------
-    if (url.pathname === '/brief' && req.method === 'POST') {
+    // La ruta canónica es POST /brief/<taskId>: es la que llama el dashboard de
+    // panal.lat y la que documenta el bot de referencia. Se admite también
+    // POST /brief con el taskId dentro del cuerpo, porque hay clientes que ya
+    // hablaban así y romperlos no arregla nada.
+    const rutaBrief = /^\/brief(?:\/(\d+))?$/.exec(url.pathname);
+    if (rutaBrief && req.method === 'POST') {
       const body = JSON.parse(await readBody(req)) as {
         taskId?: string | number;
         brief?: string;
+        address?: string;
         signature?: string;
       };
-      if (body.taskId === undefined || !body.brief || !body.signature) {
+      const idCrudo = rutaBrief[1] ?? body.taskId;
+      if (idCrudo === undefined || !body.brief || !body.signature) {
         json(res, 400, { error: 'faltan taskId, brief o signature' });
         return;
       }
-      const taskId = BigInt(body.taskId);
+      const taskId = BigInt(idCrudo);
       const task = await panal.getTask(taskId);
 
-      // Tres comprobaciones, y las tres importan: que la tarea sea tuya, que
-      // siga abierta, y que quien manda el brief sea el cliente que pagó.
+      // Cuatro comprobaciones, y las cuatro importan: que la tarea sea tuya,
+      // que siga abierta, que quien dice firmar sea el cliente que pagó, y que
+      // la firma lo demuestre.
       if (task.worker.toLowerCase() !== account.address.toLowerCase()) {
         json(res, 403, { error: 'esa tarea no es de este agente' });
         return;
       }
+      // El dashboard manda además quién firma; si no cuadra con el cliente de
+      // la tarea, se corta antes de gastar una verificación de firma.
+      if (body.address && body.address.toLowerCase() !== task.client.toLowerCase()) {
+        json(res, 403, { error: 'esa dirección no es el cliente de la tarea' });
+        return;
+      }
       if (task.status !== TaskStatus.Open) {
         json(res, 409, { error: `la tarea está ${TaskStatus[task.status]}` });
         return;
@@ -181,6 +281,17 @@ const server = createServer((req, res) => {
         json(res, 401, { error: 'la firma no es del cliente de esta tarea' });
         return;
       }
+      // Y que el texto sea EL que se encargó. Para esto existe el taskHash: sin
+      // esta comprobación, un cliente podría pagar por una cosa on-chain y
+      // pedirte otra por HTTP, y en una disputa el árbitro no tendría con qué
+      // decidir. Un carácter de más y esto salta, que es justo lo que se busca.
+      if (keccak256(toBytes(body.brief)) !== task.taskHash) {
+        json(res, 409, {
+          error: 'ese texto no es el que se registró en la cadena para esta tarea',
+          taskHash: task.taskHash,
+        });
+        return;
+      }
 
       json(res, 202, { ok: true });
       // Sin await: el cliente no debería esperar a que termines de trabajar.