create-panal-agent 0.13.1 → 0.13.2

package/package.json

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

package/template/src/agent.ts

@@ -13,7 +13,7 @@
 
 import { llmChat, resolverLlm, type CallEnvelope, type LlmConfig } from '@panal/sdk';
 import { leerAdjuntos, type AdjuntoRecibido, type AdjuntosLeidos } from './adjuntos.js';
-import { comoArchivo, formatoPedido } from './salida.js';
+import { comoArchivo, formatoPedido, nombreDelTema } from './salida.js';
 import { historialComoTexto, type Turno } from './memoria.js';
 
 /**
@@ -199,7 +199,7 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     const problema = revisar(brief, texto);
     if (!problema) {
       console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
-      return conArchivoSiLoPidio(brief, texto, ctx);
+      return await conArchivoSiLoPidio(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
@@ -207,7 +207,7 @@ 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 conArchivoSiLoPidio(brief, texto, ctx);
+      return await conArchivoSiLoPidio(brief, texto, ctx);
     }
     queja = problema;
   }
@@ -372,10 +372,10 @@ function revisar(brief: string, resultado: string): string | null {
  * lo ancla en la cadena, así que el cliente puede demostrar que el archivo que
  * se baja es exactamente el que le entregaste.
  */
-function conArchivoSiLoPidio(brief: string, texto: string, ctx: TaskContext): TaskResult {
+async function conArchivoSiLoPidio(brief: string, texto: string, ctx: TaskContext): Promise<TaskResult> {
   const formato = formatoPedido(brief);
   if (!formato) return texto;
-  const archivo = comoArchivo(formato, 'entrega', `Panal - entrega ${etiqueta(ctx)}`, texto);
+  const archivo = comoArchivo(formato, await nombreDelTema(brief, 'entrega'), `Panal - entrega ${etiqueta(ctx)}`, texto);
   const bytes = typeof archivo.data === 'string' ? archivo.data.length : archivo.data.byteLength;
   console.log(`[agente] ${etiqueta(ctx)} ${archivo.name} de ${bytes} bytes adjunto`);
   // El TEXTO se sigue entregando: es lo que se ancla en la cadena. El archivo

package/template/src/register.ts

@@ -38,6 +38,27 @@ const PERFIL = {
   // vacía NO la sustituye `??`. Con `??` el botUrl acababa siendo '' y la
   // comprobación de "no has puesto tu URL" no saltaba nunca.
   botUrl: process.env.PUBLIC_URL?.trim() || 'https://cambia-esto.example.com',
+
+  // TU CARA, si quieres tenerla. Todo esto es opcional y va vacío por defecto:
+  // un agente sin logo no vale menos, es lo que hay hoy en todo el mercado.
+  //
+  // Lo que compra ponerlo es que el cliente pueda MIRARTE antes de pagarte. En
+  // el mercado sales entre desconocidos, y un repositorio que se puede abrir
+  // dice más de ti que cualquier descripción que escribas de ti mismo.
+  //
+  // Se guarda en tu ficha del registro, así que cambiarlo cuesta una
+  // transacción: `npm run register` otra vez y ya.
+  links: {
+    // El logo sale en tu tarjeta, en el mercado y en la app. Https, cuadrado y
+    // pequeño: se pinta a 56 px, no hace falta más.
+    logo: '',
+    web: '',
+    // Tu perfil o el repositorio del agente: valen `usuario` y `usuario/repo`.
+    github: '',
+    // Solo el usuario; también se traga el enlace entero si lo pegas.
+    x: '',
+    telegram: '',
+  },
 };
 
 /** Lo que cobras por tarea. */

package/template/src/salida.ts

@@ -15,6 +15,7 @@
  * peso y confusión.
  */
 
+import { llmChat, resolverLlm, stripFilesManifest } from '@panal/sdk';
 import { textoAPdf } from './pdf.js';
 import { escribirZip } from './zip.js';
 
@@ -36,7 +37,20 @@ export interface ArchivoDeSalida {
  * Devuelve `null` cuando no pide nada, que es el caso normal.
  */
 export function formatoPedido(brief: string): Formato | null {
-  const t = brief.toLowerCase();
+  // El manifiesto de adjuntos NO es lo que pidio el cliente: es contabilidad
+  // del protocolo, y va pegada al FINAL del brief. Sin quitarla, sus lineas
+  // `name:` y `mime:` son las ultimas menciones de un formato que hay en el
+  // texto, y esta funcion se queda justamente con la ultima.
+  //
+  // El efecto es que el adjunto elige el formato de SALIDA. Comprobado en un
+  // encargo real de mainnet (#67): el cliente pidio JSON, adjunto un `.txt`, y
+  // el manifiesto —`name: pedidos n.txt`, `mime: text/plain`— gano al «devuelve
+  // solo el JSON» que estaba escrito antes. Se entrego un .txt.
+  //
+  // No es raro ni un caso de laboratorio: casi todo adjunto lleva en el nombre
+  // una extension que aqui es un formato. Adjuntar un PDF hacia que la entrega
+  // fuera un PDF, se pidiera lo que se pidiera.
+  const t = stripFilesManifest(brief).toLowerCase();
   const mencion: { formato: Formato; en: number }[] = [];
 
   for (const [formato, patron] of PATRONES) {
@@ -334,6 +348,159 @@ export function comoTabla(texto: string): string | null {
   ].join('\n');
 }
 
+/* ── cómo se llama el archivo ────────────────────────────────────────────── */
+
+/**
+ * Los reservados de Windows y los separadores de ruta.
+ *
+ * NO se tocan las letras: un nombre en chino, en árabe o con tildes es un
+ * nombre perfectamente válido, y quitárselos sería justo lo contrario de lo
+ * que hace falta aquí.
+ */
+const PROHIBIDOS = /[/\\:*?"<>|]/g;
+
+/** Cuántos caracteres como mucho. Un nombre no es un resumen. */
+const MAX_NOMBRE = 60;
+
+/** ¿Es un carácter imprimible? Los de control no valen en un nombre. */
+function imprimible(c: string): boolean {
+  const p = c.codePointAt(0) ?? 0;
+  return p >= 0x20 && p !== 0x7f;
+}
+
+/**
+ * Un título cualquiera, convertido en nombre de archivo.
+ *
+ * Se exporta para poder probarlo sin gastar una llamada al modelo.
+ */
+export function comoNombre(crudo: string): string {
+  const linea = crudo.split(/\r?\n/).find((l) => l.trim()) ?? '';
+  const limpio = [...linea]
+    .filter(imprimible)
+    .join('')
+    .trim()
+    // El modelo devuelve el título entrecomillado más veces de las que parece.
+    .replace(/^["'`«“]+|["'`»”]+$/g, '')
+    // Y a veces le pone extensión, que aquí la pone `comoArchivo`.
+    .replace(/\.(pdf|docx?|xlsx?|md|txt|csv|json|zip)$/i, '')
+    .replace(PROHIBIDOS, ' ')
+    .replace(/\s+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .toLowerCase();
+  // Por code points y no con `.slice`: cortar por unidades UTF-16 parte por la
+  // mitad un carácter fuera del plano básico.
+  return [...limpio].slice(0, MAX_NOMBRE).join('').replace(/[-.]+$/, '');
+}
+
+/**
+ * La cabecera `content-disposition` de un archivo que se descarga.
+ *
+ * DOS FORMAS DEL NOMBRE, Y LAS DOS HACEN FALTA (RFC 6266). Una cabecera HTTP
+ * solo admite latin-1, y desde que el nombre del archivo lo escribe el modelo
+ * en el idioma del cliente, un entregable puede llamarse
+ * `两个整数相除.pdf`. Interpolarlo tal cual en `filename="…"` no da un nombre
+ * feo: Node LANZA `ERR_INVALID_CHAR` al escribir la cabecera y la descarga
+ * responde 500. El archivo estaba entregado, pagado y anclado en la cadena, y
+ * el cliente no podía bajárselo.
+ *
+ *   filename=   una versión en ASCII, para quien no entienda lo otro
+ *   filename*=  el nombre de verdad, en UTF-8 percent-encoded
+ *
+ * Los navegadores prefieren `filename*` cuando está, así que el nombre bueno
+ * es el que se ve. Y las comillas se van del ASCII a propósito: una comilla
+ * dentro de `filename="…"` parte la cabecera por la mitad.
+ */
+export function comoAdjunto(nombre: string): string {
+  const ascii =
+    [...nombre]
+      .map((c) => {
+        const p = c.codePointAt(0) ?? 0;
+        return p >= 0x20 && p < 0x7f && c !== '"' && c !== '\\' ? c : '_';
+      })
+      .join('')
+      .replace(/_{2,}/g, '_')
+      .replace(/^[_.]+|[_.]+$/g, '') || 'archivo';
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(nombre)}`;
+}
+
+/**
+ * Lo que se le pide al modelo. Corto a propósito: es un nombre, no un resumen.
+ *
+ * Las dos reglas que de verdad cambian el resultado son las dos últimas. Sin
+ * la del SUJETO, el modelo nombra la acción —«escribir-casos-de-prueba»— y
+ * todos los archivos de un mismo agente vuelven a llamarse igual, que es el
+ * problema que esto viene a arreglar. Y sin la del IDIOMA contesta en inglés
+ * aunque el encargo venga en otro, porque el inglés es su idioma por defecto.
+ */
+const PIDE_UN_NOMBRE =
+  'You name files. Given a client request, reply with ONLY a file name for the deliverable.\n' +
+  'Two to five words. No extension, no quotes, no path, no explanation, no punctuation at the ends.\n' +
+  'Name the SUBJECT the work is about, never the action asked for: for "write the test cases for a ' +
+  'function that divides two integers" answer "division de dos enteros", not "escribir casos de prueba".\n' +
+  'Write it in the SAME language the client wrote in, in their own script. Do not translate it to English.';
+
+/**
+ * El nombre del archivo que se entrega, sacado del TEMA del encargo.
+ *
+ * ANTES TODOS SE LLAMABAN IGUAL. Cada agente tenía un nombre fijo —
+ * `casos-de-prueba.pdf`, `revision.pdf`, `traducciones.pdf`—, así que un
+ * cliente que encargara tres cosas al mismo agente acababa con tres archivos
+ * del mismo nombre en su carpeta de descargas, pisándose unos a otros o
+ * quedando como «casos-de-prueba (2).pdf». Y estaba en castellano para todo el
+ * mundo, cuando el contenido va en el idioma del cliente desde hace tiempo.
+ *
+ * EL TEMA SALE DEL ENCARGO, no de la entrega. La entrega es texto plano sin
+ * título —el prompt prohíbe los encabezados a propósito—, así que su primera
+ * línea es el primer caso de prueba, no de qué va la cosa. El encargo, en
+ * cambio, lo escribió el cliente: dice el tema y está en su idioma.
+ *
+ * NUNCA LANZA Y NUNCA DEVUELVE VACÍO. Si el modelo no contesta, tarda o
+ * devuelve algo que no sirve, se usa el nombre de siempre. Nombrar un archivo
+ * no puede impedir entregarlo: el pago ya está bloqueado.
+ */
+export async function nombreDelTema(brief: string, deReserva: string): Promise<string> {
+  try {
+    const cfg = resolverLlm(process.env);
+    const respuesta = await llmChat(
+      // NO SE TOCA NI LA TEMPERATURA NI EL TOPE DE TOKENS, y las dos cosas se
+      // aprendieron probando contra el modelo de verdad.
+      //
+      // Aquí ponía `temperature: 0` —lo natural para pedir algo determinista— y
+      // el modelo lo rechazaba con un 400: hay modelos que solo aceptan 1. Y
+      // ponía `maxTokens: 32` —es un nombre, no un texto— y la respuesta volvía
+      // con `choices` vacío, porque un modelo que razona antes de contestar se
+      // gasta ese presupuesto pensando y no le queda para escribir.
+      //
+      // Los dos fallos son INVISIBLES: se cae al nombre de siempre, que es
+      // exactamente lo que había antes, así que la función habría quedado
+      // muerta sin que nadie lo notara. Se hereda lo que el operador ya tiene
+      // configurado, que es lo que funciona en el resto de sus llamadas.
+      //
+      // Lo único propio es el reloj: un timeout más corto que el del trabajo y
+      // un solo reintento, porque esto va DESPUÉS de tener la entrega hecha y
+      // no puede retrasarla.
+      { ...cfg, timeoutMs: 20_000, maxRetries: 1 },
+      // El encargo entero no hace falta: el tema está al principio, y mandarlo
+      // completo puede ser mandar un contrato de treinta páginas para sacar
+      // cuatro palabras.
+      // Sin el manifiesto, por lo mismo que en `formatoPedido`: son 1.500
+      // caracteres de presupuesto y un hash de 64 ocupa sitio sin decir nada
+      // del tema. Con adjuntos cortos llegaba a colarse entero.
+      { system: PIDE_UN_NOMBRE, user: stripFilesManifest(brief).trim().slice(0, 1_500) },
+    );
+    const nombre = comoNombre(respuesta);
+    if (nombre) return nombre;
+    console.warn(`[salida] el modelo no dio un nombre usable; el archivo va como «${deReserva}»`);
+  } catch (err) {
+    console.warn(
+      `[salida] no se pudo nombrar el archivo (${err instanceof Error ? err.message.split('\n')[0] : err}); ` +
+        `va como «${deReserva}»`,
+    );
+  }
+  return deReserva;
+}
+
 /**
  * El archivo listo para adjuntar a la entrega.
  *

package/template/src/server.ts

@@ -47,6 +47,7 @@ import {
   type DeliveredFile,
   type PermitDomain,
 } from '@panal/sdk';
+import { comoAdjunto } from './salida.js';
 import { privateKeyToAccount } from 'viem/accounts';
 import { isAddress, keccak256, parseEther, toBytes, verifyMessage } from 'viem';
 import type { Address } from 'viem';
@@ -1419,7 +1420,7 @@ const server = createServer((req, res) => {
         'content-length': bytes.byteLength,
         // `attachment` a propósito: lo que hay dentro lo eligió el agente, y no
         // se le deja que el navegador del cliente lo ejecute como una página.
-        'content-disposition': `attachment; filename="${nombre}"`,
+        'content-disposition': comoAdjunto(nombre),
         'x-content-type-options': 'nosniff',
       });
       res.end(bytes);