@panal/sdk 0.10.1 → 0.12.0

package/README.md

@@ -94,6 +94,57 @@ const uri = formatAgentMetadata({
 });
 ```
 
+### Archivos: en las dos direcciones
+
+La cadena solo guarda un hash, así que ni un PDF ni una foto caben en ella. La salida fácil —entregar un enlace— es una trampa: el hash cubriría el enlace y no el archivo, y quien lo aloja podría cambiarlo después de cobrar. Lo que se hace es anclar el **hash de los bytes** dentro del texto, y así la cadena de custodia se cierra sin confiar en el servidor que sirve la descarga.
+
+**El agente entrega archivos** (`[panal-files/1]` dentro del texto de la entrega):
+
+```ts
+import { appendFilesManifest, downloadDeliveredFile, parseFilesManifest } from '@panal/sdk';
+
+// Quien entrega: el manifiesto entra en el texto ANTES de anclarlo.
+const texto = appendFilesManifest('Aquí tienes el informe.', archivos);
+
+// Quien recibe: si los bytes no dan el hash anclado, la descarga lanza.
+for (const f of parseFilesManifest(texto)) await downloadDeliveredFile(f, { baseUrl, address, signature, expira });
+```
+
+**El cliente adjunta archivos** (`[panal-attach/1]` dentro del brief). El hash se calcula **antes de pagar** y viaja dentro del encargo, así que el `taskHash` del escrow lo cubre desde el primer momento:
+
+```ts
+import { attachmentFrom, appendAttachmentsManifest, matchAttachment, parseAttachmentsManifest } from '@panal/sdk';
+
+// Cliente, antes de contratar:
+const foto = attachmentFrom('recibo.png', bytes, 'image/png');
+const brief = appendAttachmentsManifest('Léeme este recibo.', [foto]);  // esto es lo que se hashea
+
+// Agente, al recibir una subida: lo que nadie anunció, no se escribe.
+const anunciado = matchAttachment(parseAttachmentsManifest(brief), subidos, nombre);
+if (!anunciado) throw new Error('esos bytes no se pagaron');
+```
+
+Los bytes suben aparte, después de contratar. `stripFilesManifest` quita los dos bloques cuando el texto va a ojos de una persona.
+
+### El modelo, libre
+
+Un agente cobra y entrega on-chain; qué modelo piensa por dentro es asunto suyo. No hay SDK de ningún proveedor: son tres formatos de red, y con esos tres se habla con todos.
+
+```ts
+import { llmChat, resolverLlm } from '@panal/sdk';
+
+const cfg = resolverLlm(process.env);           // LLM_PROVIDER=claude|kimi|grok|glm|gemini|deepseek|groq|ollama…
+const respuesta = await llmChat(cfg, {
+  system: 'Eres un agente de Panal.',
+  user: brief,
+  imagenes: [{ mime: 'image/png', bytes }],     // lo que adjuntó el cliente
+});
+```
+
+El dialecto (`openai`, `anthropic`, `gemini`) se adivina por la URL; `LLM_DIALECT` lo fuerza si haces de puente con algo raro. Un proveedor que no esté en la lista no necesita tocar el SDK: se pone `LLM_BASE_URL` a pelo. Y los modelos sugeridos son una comodidad, no una promesa — `LLM_MODEL` manda siempre.
+
+Ojo con una cosa: quien mira la foto es **el modelo**. Si el que configuraste no es multimodal, la llamada falla con lo que diga el proveedor.
+
 ## Contratar desde Claude
 
 Si prefieres hacerlo conversando en vez de programando, existe [`panal-mcp`](../mcp), un servidor MCP construido sobre este SDK.

package/dist/agent-card.d.ts

@@ -0,0 +1,121 @@
+/**
+ * La ficha que un agente sirve en `GET /agent.json`.
+ *
+ * POR QUÉ ESTE ARCHIVO EXISTE
+ *
+ * Había dos formatos. El bot colocaba el cobro por llamada en
+ * `endpoints.x402Ask`; la plantilla lo ponía en la raíz, como `x402Ask`. Los
+ * dos servían la misma información y ningún lector veía las dos, porque cada
+ * uno parseaba con un tipo escrito a mano allí donde hacía falta.
+ *
+ * No fue un descuido de nadie: el tipo `AgentJson` vivía dentro del bot, así
+ * que la plantilla —que no depende del bot— no tenía de dónde copiarlo y
+ * escribió su propio objeto. Dos implementaciones honestas de una idea que
+ * nunca se escribió en un sitio común divergen solas.
+ *
+ * Aquí está esa idea, en el paquete del que ya dependen la plantilla y el MCP.
+ * Quien sirva una ficha, que la sirva con esta forma; quien la lea, que la lea
+ * con `leerX402` y `leerMaxBriefChars`, que entienden también la forma vieja.
+ *
+ * COMPATIBILIDAD
+ *
+ * Hay agentes desplegados sirviendo el formato antiguo, y no se les puede
+ * pedir que se actualicen para seguir siendo contratables. Los lectores
+ * aceptan las dos formas y lo seguirán haciendo: quien escribe se moderniza,
+ * quien lee perdona. Es la misma regla que ya seguía `agentAddress`.
+ */
+import type { Address } from 'viem';
+/** Cobro por llamada (x402), tal y como lo anuncia un agente. */
+export interface FichaX402 {
+    method?: 'POST';
+    /** Ruta relativa. `url` gana si están las dos. */
+    path?: string;
+    url?: string;
+    scheme?: string;
+    /** Token ERC-20 en el que cobra. */
+    asset?: Address;
+    assetSymbol?: string;
+    /** Precio por llamada, en wei del token, como cadena decimal. */
+    amount?: string;
+    payTo?: Address;
+    howTo?: string;
+}
+/** Cómo mandarle el encargo a un agente, y cuánto texto acepta. */
+export interface FichaPostBrief {
+    method?: 'POST';
+    path?: string;
+    signMessage?: string;
+    body?: string;
+    /**
+     * Tope de caracteres del encargo.
+     *
+     * Publicarlo es lo que evita que un cliente bloquee el pago con un encargo
+     * que el agente va a rechazar. Ausente significa NO LO DICE, que no es lo
+     * mismo que «no hay tope»: tratarlo como ilimitado es volver a averiguarlo
+     * pagando.
+     */
+    maxBriefChars?: number;
+}
+/** Cómo descargar el resultado ya entregado. */
+export interface FichaGetResult {
+    method?: 'GET';
+    path?: string;
+    signMessage?: string;
+}
+/**
+ * La ficha completa. Casi todo es opcional a propósito: los dos motores tienen
+ * capacidades distintas —el de la plantilla no lee el registry al servirla, y
+ * el del bot sí— y un esquema que obligue a rellenar lo que no se sabe termina
+ * rellenándose con mentiras.
+ */
+export interface AgentCard {
+    /** La dirección on-chain que este dominio declara suya. Es lo que verifica. */
+    agent?: Address;
+    /** Alias antiguo de `agent`. Se sigue leyendo; no lo escribas en fichas nuevas. */
+    agentAddress?: Address;
+    protocol?: 'panal';
+    network?: string;
+    chainId?: number;
+    name?: string;
+    description?: string;
+    skills?: string[];
+    price?: {
+        amountWei?: string;
+        currency?: Address;
+        symbol?: string;
+    } | null;
+    active?: boolean | null;
+    contracts?: {
+        escrow?: Address;
+        registry?: Address;
+        token?: Address;
+    };
+    endpoints?: {
+        base?: string | null;
+        postBrief?: FichaPostBrief;
+        getResult?: FichaGetResult;
+        x402Ask?: FichaX402;
+        indexer?: string | null;
+    };
+    /** Alias ANTIGUO de `endpoints.x402Ask`. Se lee; no se escribe. */
+    x402Ask?: FichaX402;
+    howToHire?: string[];
+}
+/** La dirección que la ficha declara suya, mirando también el alias viejo. */
+export declare function leerDireccion(card: unknown): string | null;
+/**
+ * El bloque de cobro por llamada, venga en el sitio nuevo o en el viejo.
+ *
+ * El sitio canónico gana si están los dos: un agente que sirva ambos está en
+ * mitad de una migración, y el nuevo es el que va a seguir manteniendo.
+ */
+export declare function leerX402(card: unknown): FichaX402 | null;
+/**
+ * El tope de caracteres del encargo, o `null` si la ficha no lo dice.
+ *
+ * `null` es NO LO SÉ y hay que tratarlo así. La ficha la sirve un desconocido,
+ * así que solo cuenta un entero positivo: un 0 o un negativo harían imposible
+ * cualquier encargo, y eso lo decide el agente bajando su tope, no mandando
+ * basura en un campo.
+ */
+export declare function leerMaxBriefChars(card: unknown): number | null;

package/dist/agent-card.js

@@ -0,0 +1,54 @@
+/**
+ * La ficha que un agente sirve en `GET /agent.json`.
+ *
+ * POR QUÉ ESTE ARCHIVO EXISTE
+ *
+ * Había dos formatos. El bot colocaba el cobro por llamada en
+ * `endpoints.x402Ask`; la plantilla lo ponía en la raíz, como `x402Ask`. Los
+ * dos servían la misma información y ningún lector veía las dos, porque cada
+ * uno parseaba con un tipo escrito a mano allí donde hacía falta.
+ *
+ * No fue un descuido de nadie: el tipo `AgentJson` vivía dentro del bot, así
+ * que la plantilla —que no depende del bot— no tenía de dónde copiarlo y
+ * escribió su propio objeto. Dos implementaciones honestas de una idea que
+ * nunca se escribió en un sitio común divergen solas.
+ *
+ * Aquí está esa idea, en el paquete del que ya dependen la plantilla y el MCP.
+ * Quien sirva una ficha, que la sirva con esta forma; quien la lea, que la lea
+ * con `leerX402` y `leerMaxBriefChars`, que entienden también la forma vieja.
+ *
+ * COMPATIBILIDAD
+ *
+ * Hay agentes desplegados sirviendo el formato antiguo, y no se les puede
+ * pedir que se actualicen para seguir siendo contratables. Los lectores
+ * aceptan las dos formas y lo seguirán haciendo: quien escribe se moderniza,
+ * quien lee perdona. Es la misma regla que ya seguía `agentAddress`.
+ */
+/** La dirección que la ficha declara suya, mirando también el alias viejo. */
+export function leerDireccion(card) {
+    const c = card;
+    const dir = typeof c?.agent === 'string' ? c.agent : typeof c?.agentAddress === 'string' ? c.agentAddress : '';
+    return dir || null;
+}
+/**
+ * El bloque de cobro por llamada, venga en el sitio nuevo o en el viejo.
+ *
+ * El sitio canónico gana si están los dos: un agente que sirva ambos está en
+ * mitad de una migración, y el nuevo es el que va a seguir manteniendo.
+ */
+export function leerX402(card) {
+    const c = card;
+    return c?.endpoints?.x402Ask ?? c?.x402Ask ?? null;
+}
+/**
+ * El tope de caracteres del encargo, o `null` si la ficha no lo dice.
+ *
+ * `null` es NO LO SÉ y hay que tratarlo así. La ficha la sirve un desconocido,
+ * así que solo cuenta un entero positivo: un 0 o un negativo harían imposible
+ * cualquier encargo, y eso lo decide el agente bajando su tope, no mandando
+ * basura en un campo.
+ */
+export function leerMaxBriefChars(card) {
+    const max = card?.endpoints?.postBrief?.maxBriefChars;
+    return typeof max === 'number' && Number.isInteger(max) && max > 0 ? max : null;
+}

package/dist/client.js

@@ -17,6 +17,7 @@
  */
 import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes } from 'viem';
 import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
+import { leerX402 } from './agent-card.js';
 import { assertPublicUrl, fetchLimited } from './net.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
@@ -753,8 +754,11 @@ export class PanalClient {
             const url = await assertPublicUrl(new URL('/agent.json', base).toString(), options);
             const res = await fetchLimited(url, { timeoutMs: 10_000 });
             if (res.status === 200) {
-                const card = JSON.parse(res.text);
-                const anunciado = card.endpoints?.x402Ask;
+                // `leerX402` entiende las dos formas. Antes esto solo miraba
+                // `endpoints.x402Ask`, así que con la ficha de un agente de plantilla
+                // no encontraba nada y caía a la convención: funcionaba de casualidad,
+                // y solo mientras el agente escuchara justo en /x402/ask.
+                const anunciado = leerX402(JSON.parse(res.text));
                 if (anunciado?.url)
                     return anunciado.url;
                 if (anunciado?.path)

package/dist/files.d.ts

@@ -33,6 +33,11 @@
  * on-chain, no contra algo que venga en el texto. Así un agente no puede
  * mandar a su cliente a un tercero. `url` absoluta existe para quien aloja
  * fuera, y es igual de segura porque la garantía la da el hash, no el sitio.
+ *
+ * La segunda mitad del archivo hace lo mismo en la otra dirección: los
+ * adjuntos que el CLIENTE manda con su encargo —una foto, un PDF que hay que
+ * revisar— anunciados dentro del brief con `[panal-attach/1]`, para que el
+ * hash de la tarea los cubra desde el momento del pago.
  */
 import type { Hex } from 'viem';
 import { type UrlGuardOptions } from './net.js';
@@ -40,16 +45,26 @@ import { type UrlGuardOptions } from './net.js';
 export declare const FILES_BLOCK = "[panal-files/1]";
 /** Tope por defecto de una descarga: 25 MB. */
 export declare const MAX_FILE_BYTES: number;
-/** Un archivo anunciado en la entrega. */
-export interface DeliveredFile {
+/**
+ * Lo que hace falta para reconocer unos bytes sin fiarse de quien los sirve.
+ *
+ * Es lo único que comparten las dos direcciones —el archivo que el agente
+ * entrega y la foto que el cliente adjunta—, y por eso `verifyFileBytes` pide
+ * esto y no un `DeliveredFile`: la comprobación es la misma en los dos
+ * sentidos, y el sitio de descarga no pinta nada en ella.
+ */
+export interface HashedFile {
     /** Nombre del archivo, sin rutas. */
     name: string;
     /** Tamaño en bytes. Se comprueba junto al hash. */
     size: number;
-    /** Tipo MIME, si el agente lo declaró. */
+    /** Tipo MIME, si quien lo mandó lo declaró. */
     mime?: string;
     /** keccak256 de los bytes. Es la garantía; todo lo demás es logística. */
     hash: Hex;
+}
+/** Un archivo anunciado en la entrega. */
+export interface DeliveredFile extends HashedFile {
     /** Ruta relativa, a resolver contra el botUrl registrado del agente. */
     path?: string;
     /** URL absoluta, para quien aloja fuera de su propio servidor. */
@@ -93,7 +108,7 @@ export declare function parseFilesManifest(text: string): DeliveredFile[];
  */
 export declare function stripFilesManifest(text: string): string;
 /** Comprueba unos bytes contra lo que el manifiesto prometía. Lanza si no cuadra. */
-export declare function verifyFileBytes(file: DeliveredFile, bytes: Uint8Array): void;
+export declare function verifyFileBytes(file: HashedFile, bytes: Uint8Array): void;
 /**
  * De dónde se baja un archivo.
  *
@@ -128,3 +143,41 @@ export interface DownloadOptions extends UrlGuardOptions {
  * que no cuadra "avisando" no serviría de nada: quien llama lo guardaría igual.
  */
 export declare function downloadDeliveredFile(file: DeliveredFile, options?: DownloadOptions): Promise<Uint8Array>;
+/** Cabecera del bloque de adjuntos. Versionada: se ancla en la cadena. */
+export declare const ATTACH_BLOCK = "[panal-attach/1]";
+/** Un archivo que el cliente adjunta al encargo. */
+export type AttachedFile = HashedFile;
+/**
+ * Describe unos bytes para anunciarlos en el brief.
+ *
+ * El nombre se limpia aquí y no al recibirlo: lo que se anuncia tiene que ser
+ * lo mismo que luego se busca, y un nombre saneado a medias haría que el
+ * agente no reconociera su propio adjunto.
+ */
+export declare function attachmentFrom(name: string, bytes: Uint8Array, mime?: string): AttachedFile;
+/**
+ * Construye el bloque de adjuntos.
+ *
+ * Orden de claves fijo y `\n`, por lo mismo que en la entrega: este texto entra
+ * en el brief, y el brief se hashea. Un espacio de más y el agente rechaza el
+ * encargo con el pago ya bloqueado.
+ */
+export declare function buildAttachmentsManifest(files: AttachedFile[]): string;
+/** El encargo con los adjuntos anunciados al final. Esto es lo que se hashea. */
+export declare function appendAttachmentsManifest(brief: string, files: AttachedFile[]): string;
+/** Lee los adjuntos anunciados en un encargo. No lanza por un bloque roto. */
+export declare function parseAttachmentsManifest(brief: string): AttachedFile[];
+/**
+ * ¿Estos bytes son alguno de los adjuntos anunciados?
+ *
+ * Es la guarda del agente al recibir una subida: se busca por HASH, no por
+ * nombre, porque el nombre lo elige quien sube y el hash no. Devuelve el
+ * adjunto tal y como se anunció —con su nombre ya limpio— o `null`, y un
+ * `null` significa exactamente una cosa: esos bytes no se pagaron, no se
+ * escriben.
+ *
+ * `name` sólo desempata cuando el mismo archivo se adjuntó dos veces con
+ * nombres distintos; los bytes son los mismos, así que cualquiera valdría,
+ * pero devolver el que pidieron evita guardarlo con el nombre del otro.
+ */
+export declare function matchAttachment(files: AttachedFile[], bytes: Uint8Array, name?: string): AttachedFile | null;

package/dist/files.js

@@ -33,6 +33,11 @@
  * on-chain, no contra algo que venga en el texto. Así un agente no puede
  * mandar a su cliente a un tercero. `url` absoluta existe para quien aloja
  * fuera, y es igual de segura porque la garantía la da el hash, no el sitio.
+ *
+ * La segunda mitad del archivo hace lo mismo en la otra dirección: los
+ * adjuntos que el CLIENTE manda con su encargo —una foto, un PDF que hay que
+ * revisar— anunciados dentro del brief con `[panal-attach/1]`, para que el
+ * hash de la tarea los cubra desde el momento del pago.
  */
 import { keccak256 } from 'viem';
 import { assertPublicUrl, fetchBytesLimited } from './net.js';
@@ -97,49 +102,74 @@ export function appendFilesManifest(text, files) {
     return `${cuerpo}\n\n${buildFilesManifest(files)}\n`;
 }
 /**
- * Lee los archivos anunciados en el texto de una entrega.
+ * Lee los bloques `clave: valor` que van bajo una cabecera dada.
  *
- * Nunca lanza por un bloque mal formado: devuelve los que sí se entienden. Un
- * manifiesto roto no puede impedirle al cliente leer la parte escrita de su
- * entrega, que ya pagó.
+ * Lo comparten el manifiesto de entrega y el de adjuntos: los dos se anclan en
+ * la cadena y los dos tienen que leerse igual en todas partes. Un bloque
+ * termina en la primera línea vacía o que ya no es `clave: valor`, y eso basta
+ * para que dos manifiestos pegados no se contaminen: ninguna cabecera lleva
+ * dos puntos.
  */
-export function parseFilesManifest(text) {
+function parseBloques(text, tag) {
     const out = [];
     const lineas = text.split(/\r?\n/);
     for (let i = 0; i < lineas.length; i++) {
-        if (lineas[i].trim() !== FILES_BLOCK)
+        if (lineas[i].trim() !== tag)
             continue;
         const campos = {};
         for (let j = i + 1; j < lineas.length; j++) {
             const linea = lineas[j];
-            if (!linea.trim() || linea.trim() === FILES_BLOCK)
+            if (!linea.trim())
                 break;
             const sep = linea.indexOf(':');
             if (sep === -1)
                 break;
             campos[linea.slice(0, sep).trim().toLowerCase()] = linea.slice(sep + 1).trim();
         }
-        const { name, size, hash, mime, path, url } = campos;
-        if (!name || !hash || !/^0x[0-9a-fA-F]{64}$/.test(hash))
-            continue;
-        const bytes = Number(size);
-        if (!Number.isInteger(bytes) || bytes < 0)
+        out.push(campos);
+    }
+    return out;
+}
+/** Lo común a los dos manifiestos: un nombre limpio, un tamaño y un hash. */
+function parseComun(campos) {
+    const { name, size, hash, mime } = campos;
+    if (!name || !hash || !/^0x[0-9a-fA-F]{64}$/.test(hash))
+        return null;
+    const bytes = Number(size);
+    if (!Number.isInteger(bytes) || bytes < 0)
+        return null;
+    try {
+        return {
+            name: sanitizeFileName(name),
+            size: bytes,
+            hash: hash.toLowerCase(),
+            ...(mime ? { mime } : {}),
+        };
+    }
+    catch {
+        // Nombre inservible: se descarta ese archivo, no el manifiesto entero.
+        return null;
+    }
+}
+/**
+ * Lee los archivos anunciados en el texto de una entrega.
+ *
+ * Nunca lanza por un bloque mal formado: devuelve los que sí se entienden. Un
+ * manifiesto roto no puede impedirle al cliente leer la parte escrita de su
+ * entrega, que ya pagó.
+ */
+export function parseFilesManifest(text) {
+    const out = [];
+    for (const campos of parseBloques(text, FILES_BLOCK)) {
+        const comun = parseComun(campos);
+        if (!comun)
             continue;
+        // Sin `path` ni `url` el archivo no se puede bajar de ningún sitio, y
+        // anunciarlo sólo serviría para prometer algo que no se puede cumplir.
+        const { path, url } = campos;
         if (!path && !url)
             continue;
-        try {
-            out.push({
-                name: sanitizeFileName(name),
-                size: bytes,
-                hash: hash.toLowerCase(),
-                ...(mime ? { mime } : {}),
-                ...(path ? { path } : {}),
-                ...(url ? { url } : {}),
-            });
-        }
-        catch {
-            // Nombre inservible: se descarta ese archivo, no la entrega entera.
-        }
+        out.push({ ...comun, ...(path ? { path } : {}), ...(url ? { url } : {}) });
     }
     return out;
 }
@@ -154,7 +184,7 @@ export function stripFilesManifest(text) {
     const fuera = [];
     let dentro = false;
     for (const linea of lineas) {
-        if (linea.trim() === FILES_BLOCK) {
+        if (linea.trim() === FILES_BLOCK || linea.trim() === ATTACH_BLOCK) {
             dentro = true;
             continue;
         }
@@ -233,3 +263,110 @@ export async function downloadDeliveredFile(file, options = {}) {
     verifyFileBytes(file, bytes);
     return bytes;
 }
+// ---------------------------------------------------------------------------
+// La otra dirección: lo que el CLIENTE adjunta a su encargo.
+//
+// El escrow ancla `keccak256(brief)` al contratar, y el agente rechaza el
+// encargo si el texto que le llega no da exactamente ese hash. Eso deja el
+// brief cerrado, que es justo lo que se quiere… y también significa que una
+// foto no puede viajar dentro: no cabe en 32.000 caracteres, y meterla en
+// base64 cambiaría el texto que ya se hasheó.
+//
+// Se hace lo mismo que en la entrega, en espejo. El navegador calcula el hash
+// de la foto ANTES de pagar y lo anuncia dentro del brief; los bytes suben
+// después, por su cuenta. La cadena de custodia queda cerrada igual:
+//
+//     taskHash on-chain → texto del brief → hash del adjunto → bytes
+//
+// Y hay una propiedad que sale gratis y es la que de verdad importa para el
+// agente: puede RECHAZAR cualquier byte que no estuviera anunciado. Nadie le
+// deja archivos en el disco; sólo entran los que el cliente pagó por anunciar.
+//
+// No lleva `path` ni `url`, y no es un olvido: el cliente es un navegador y no
+// aloja nada. Por eso es un bloque aparte y no un `[panal-files/1]` sin ruta —
+// un manifiesto de entrega sin sitio de descarga es una promesa rota, y ahí
+// conviene seguir rechazándolo.
+// ---------------------------------------------------------------------------
+/** Cabecera del bloque de adjuntos. Versionada: se ancla en la cadena. */
+export const ATTACH_BLOCK = '[panal-attach/1]';
+/**
+ * Describe unos bytes para anunciarlos en el brief.
+ *
+ * El nombre se limpia aquí y no al recibirlo: lo que se anuncia tiene que ser
+ * lo mismo que luego se busca, y un nombre saneado a medias haría que el
+ * agente no reconociera su propio adjunto.
+ */
+export function attachmentFrom(name, bytes, mime) {
+    return {
+        name: sanitizeFileName(name),
+        size: bytes.byteLength,
+        hash: keccak256(bytes),
+        ...(mime ? { mime } : {}),
+    };
+}
+/**
+ * Construye el bloque de adjuntos.
+ *
+ * Orden de claves fijo y `\n`, por lo mismo que en la entrega: este texto entra
+ * en el brief, y el brief se hashea. Un espacio de más y el agente rechaza el
+ * encargo con el pago ya bloqueado.
+ */
+export function buildAttachmentsManifest(files) {
+    return files
+        .map((f) => {
+        const lineas = [ATTACH_BLOCK, `name: ${sanitizeFileName(f.name)}`, `size: ${f.size}`];
+        if (f.mime)
+            lineas.push(`mime: ${f.mime}`);
+        lineas.push(`hash: ${f.hash}`);
+        return lineas.join('\n');
+    })
+        .join('\n\n');
+}
+/** El encargo con los adjuntos anunciados al final. Esto es lo que se hashea. */
+export function appendAttachmentsManifest(brief, files) {
+    if (files.length === 0)
+        return brief;
+    return `${brief.trimEnd()}\n\n${buildAttachmentsManifest(files)}\n`;
+}
+/** Lee los adjuntos anunciados en un encargo. No lanza por un bloque roto. */
+export function parseAttachmentsManifest(brief) {
+    const out = [];
+    for (const campos of parseBloques(brief, ATTACH_BLOCK)) {
+        const comun = parseComun(campos);
+        if (comun)
+            out.push(comun);
+    }
+    return out;
+}
+/**
+ * ¿Estos bytes son alguno de los adjuntos anunciados?
+ *
+ * Es la guarda del agente al recibir una subida: se busca por HASH, no por
+ * nombre, porque el nombre lo elige quien sube y el hash no. Devuelve el
+ * adjunto tal y como se anunció —con su nombre ya limpio— o `null`, y un
+ * `null` significa exactamente una cosa: esos bytes no se pagaron, no se
+ * escriben.
+ *
+ * `name` sólo desempata cuando el mismo archivo se adjuntó dos veces con
+ * nombres distintos; los bytes son los mismos, así que cualquiera valdría,
+ * pero devolver el que pidieron evita guardarlo con el nombre del otro.
+ */
+export function matchAttachment(files, bytes, name) {
+    const real = keccak256(bytes).toLowerCase();
+    const iguales = files.filter((f) => f.hash.toLowerCase() === real && f.size === bytes.byteLength);
+    if (iguales.length === 0)
+        return null;
+    if (name) {
+        let limpio = null;
+        try {
+            limpio = sanitizeFileName(name);
+        }
+        catch {
+            limpio = null;
+        }
+        const exacto = limpio ? iguales.find((f) => f.name === limpio) : undefined;
+        if (exacto)
+            return exacto;
+    }
+    return iguales[0];
+}

package/dist/index.d.ts

@@ -29,10 +29,14 @@ export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
 export type { AskResult, PayAndAskOptions, PermitDomain, X402Accept, X402Quote } from './x402.js';
 export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
-export { FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendFilesManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
-export type { DeliveredFile, DownloadOptions } from './files.js';
+export { ATTACH_BLOCK, FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendAttachmentsManifest, appendFilesManifest, attachmentFrom, buildAttachmentsManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, matchAttachment, parseAttachmentsManifest, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
+export type { AttachedFile, DeliveredFile, DownloadOptions, HashedFile } from './files.js';
+export { MAX_IMAGEN_BYTES, MIMES_IMAGEN, PROVEEDORES, LlmError, dialectoDe, esImagenSoportada, llmChat, resolverLlm, } from './llm.js';
+export type { LlmConfig, LlmDialecto, LlmImagen, LlmPeticion, LlmProveedor } from './llm.js';
 export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';
 export type { SettleDeps, SettleResult, X402Payment, X402ServerAccept, X402ServerQuote, } from './x402-server.js';
 export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';
 export type { CallEnvelope } from './envelope.js';
 export type { UrlGuardOptions } from './net.js';
+export { leerDireccion, leerMaxBriefChars, leerX402 } from './agent-card.js';
+export type { AgentCard, FichaGetResult, FichaPostBrief, FichaX402 } from './agent-card.js';

package/dist/index.js

@@ -27,9 +27,16 @@ export { erc20Abi, escrowAbi, registryAbi } from './abis.js';
 export { X402_SCHEME, X402Error, payAndAsk, quoteAsk } from './x402.js';
 export { assertPublicUrl, fetchBytesLimited, fetchLimited, isPrivateIp } from './net.js';
 // Archivos: entregar un PDF o un vídeo anclando SU hash, no el del enlace.
-export { FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendFilesManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
+// Y en la otra dirección, adjuntar una foto al encargo con la misma garantía.
+export { ATTACH_BLOCK, FILES_BLOCK, MAX_FILE_BYTES, FileVerificationError, appendAttachmentsManifest, appendFilesManifest, attachmentFrom, buildAttachmentsManifest, buildFilesManifest, downloadDeliveredFile, fileUrl, matchAttachment, parseAttachmentsManifest, parseFilesManifest, sanitizeFileName, stripFilesManifest, verifyFileBytes, } from './files.js';
+// El modelo, libre: tres dialectos de red y con esos tres se habla con todos
+// (Claude, Gemini, Kimi, Grok, GLM, DeepSeek, Groq, OpenAI, Ollama…).
+export { MAX_IMAGEN_BYTES, MIMES_IMAGEN, PROVEEDORES, LlmError, dialectoDe, esImagenSoportada, llmChat, resolverLlm, } from './llm.js';
 // x402: la otra mitad, cobrar por llamada. Portada del bot de LexPanal, donde
 // lleva meses cobrando en produccion.
 export { X402_VERSION, X402_SERVER_SCHEME, buildQuote, enqueueByPayer, parsePaymentHeader, permitNonce, permitTypedData, readPermitDomain, resourceId, splitSignature, verifyAndSettle, } from './x402-server.js';
 // El sobre que viaja entre agentes: profundidad, presupuesto y detección de ciclos.
 export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhausted, LoopDetected, assertCanServe, descend, envelopeHeaders, newEnvelope, parseEnvelope, remainingBudget, } from './envelope.js';
+// La ficha de GET /agent.json: un solo formato, y lectores que perdonan el
+// antiguo. En agent-card.ts está por qué llegó a haber dos.
+export { leerDireccion, leerMaxBriefChars, leerX402 } from './agent-card.js';

package/dist/llm.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Panal SDK — hablarle a un modelo sin casarse con quien lo sirve.
+ *
+ * Un agente de Panal cobra on-chain y entrega on-chain; qué modelo piensa por
+ * dentro es asunto suyo, y no debería costarle un cambio de código. Aquí no
+ * hay SDK de ningún proveedor: son tres formatos de red, y con esos tres se
+ * habla con todos.
+ *
+ *   - `openai`     · OpenAI, Kimi (Moonshot), Grok (xAI), GLM (Zhipu),
+ *                    DeepSeek, Groq, OpenRouter, Mistral, Together, Ollama…
+ *                    Es el formato que ha copiado casi todo el mundo.
+ *   - `anthropic`  · Claude. Cambia la ruta, la cabecera de la clave y dónde
+ *                    va el system; el resto es lo mismo.
+ *   - `gemini`     · Google. Cambia hasta cómo se llaman los campos.
+ *
+ * El dialecto se ADIVINA a partir de la URL, así que en el caso normal basta
+ * con poner el proveedor y la clave. Se puede forzar si haces de puente con
+ * algo raro.
+ *
+ * Las imágenes viajan en base64 dentro de la petición, en el formato que cada
+ * dialecto entiende. Eso es lo que permite que un cliente mande una foto y el
+ * agente la MIRE — pero ojo, quien la mira es el modelo: si el que has
+ * configurado no es multimodal, la llamada falla con lo que diga el
+ * proveedor, y eso es justo lo que su autor necesita leer.
+ *
+ * Sin dependencias a propósito, base64 incluido: este archivo lo carga todo
+ * agente que arranca, y no sale a cuenta arrastrar un paquete por 12 líneas.
+ */
+/** Los tres formatos de red que sabemos hablar. */
+export type LlmDialecto = 'openai' | 'anthropic' | 'gemini';
+export interface LlmProveedor {
+    /** Base de la API, sin la ruta del método. */
+    baseUrl: string;
+    dialecto: LlmDialecto;
+    /**
+     * Un modelo que existía cuando se escribió esto.
+     *
+     * Es una comodidad, no una promesa: los nombres cambian cada pocos meses y
+     * ninguna lista dentro de un paquete sobrevive a eso. `LLM_MODEL` manda
+     * siempre, y es lo que se debe poner en producción.
+     */
+    modeloSugerido?: string;
+}
+/**
+ * Los proveedores conocidos, por nombre corto.
+ *
+ * Lo que fija cada entrada es la URL y el dialecto —lo estructural, lo que no
+ * cambia—. Añadir uno nuevo es una línea, y usar uno que no esté en la lista
+ * no requiere tocar este archivo: se pone `LLM_BASE_URL` a pelo.
+ */
+export declare const PROVEEDORES: Record<string, LlmProveedor>;
+/**
+ * Qué dialecto habla una URL.
+ *
+ * Se mira el host y no la ruta: un proxy corporativo cambia el camino, pero
+ * quien contesta al otro lado sigue siendo el mismo. Lo que no se reconoce se
+ * trata como OpenAI, que es lo que implementa casi todo el mundo — y si se
+ * falla, se falla del lado que tiene arreglo con `LLM_DIALECT`.
+ */
+export declare function dialectoDe(baseUrl: string): LlmDialecto;
+export interface LlmConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    dialecto: LlmDialecto;
+    /** Corta la llamada. Un modelo colgado deja la tarea colgada. */
+    timeoutMs?: number;
+    /** Reintentos ante 429 y 5xx. Los 4xx no se reintentan: son de configuración. */
+    maxRetries?: number;
+    maxTokens?: number;
+    temperature?: number;
+}
+/** Una imagen que se le enseña al modelo. */
+export interface LlmImagen {
+    mime: string;
+    bytes: Uint8Array;
+}
+export interface LlmPeticion {
+    system?: string;
+    user: string;
+    /** Lo que el cliente adjuntó, ya filtrado a formatos que un modelo entiende. */
+    imagenes?: LlmImagen[];
+}
+export declare class LlmError extends Error {
+    /** De configuración: reintentarlo sólo gasta tiempo y dinero. */
+    readonly fatal: boolean;
+    constructor(message: string, 
+    /** De configuración: reintentarlo sólo gasta tiempo y dinero. */
+    fatal?: boolean);
+}
+/**
+ * Lee la configuración del entorno.
+ *
+ * `LLM_PROVIDER` es el camino corto (`claude`, `kimi`, `gemini`…) y
+ * `LLM_BASE_URL` el largo, para cualquiera que no esté en la lista. Si están
+ * los dos, manda la URL: quien la escribe a mano sabe lo que quiere.
+ */
+export declare function resolverLlm(env: Record<string, string | undefined>): LlmConfig;
+/**
+ * Los formatos que aceptan los tres dialectos a la vez.
+ *
+ * Es la intersección y no la unión: un agente que acepta un TIFF porque su
+ * proveedor de hoy lo admite se rompe el día que cambie de proveedor, y se
+ * rompe con el cliente esperando y el pago bloqueado.
+ */
+export declare const MIMES_IMAGEN: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+/** Tope por imagen. Por encima, los proveedores empiezan a rechazar peticiones. */
+export declare const MAX_IMAGEN_BYTES: number;
+export declare function esImagenSoportada(mime: string | undefined): boolean;
+/**
+ * Una pregunta, una respuesta, con reintentos.
+ *
+ * Se reintentan 429 y 5xx —el proveedor está saturado, es cuestión de
+ * esperar— y NO se reintenta un 4xx: una clave mal escrita o un modelo que no
+ * existe dan lo mismo al segundo intento, y mientras tanto el plazo de la
+ * tarea corre.
+ */
+export declare function llmChat(cfg: LlmConfig, pet: LlmPeticion): Promise<string>;

package/dist/llm.js

@@ -0,0 +1,357 @@
+/**
+ * Panal SDK — hablarle a un modelo sin casarse con quien lo sirve.
+ *
+ * Un agente de Panal cobra on-chain y entrega on-chain; qué modelo piensa por
+ * dentro es asunto suyo, y no debería costarle un cambio de código. Aquí no
+ * hay SDK de ningún proveedor: son tres formatos de red, y con esos tres se
+ * habla con todos.
+ *
+ *   - `openai`     · OpenAI, Kimi (Moonshot), Grok (xAI), GLM (Zhipu),
+ *                    DeepSeek, Groq, OpenRouter, Mistral, Together, Ollama…
+ *                    Es el formato que ha copiado casi todo el mundo.
+ *   - `anthropic`  · Claude. Cambia la ruta, la cabecera de la clave y dónde
+ *                    va el system; el resto es lo mismo.
+ *   - `gemini`     · Google. Cambia hasta cómo se llaman los campos.
+ *
+ * El dialecto se ADIVINA a partir de la URL, así que en el caso normal basta
+ * con poner el proveedor y la clave. Se puede forzar si haces de puente con
+ * algo raro.
+ *
+ * Las imágenes viajan en base64 dentro de la petición, en el formato que cada
+ * dialecto entiende. Eso es lo que permite que un cliente mande una foto y el
+ * agente la MIRE — pero ojo, quien la mira es el modelo: si el que has
+ * configurado no es multimodal, la llamada falla con lo que diga el
+ * proveedor, y eso es justo lo que su autor necesita leer.
+ *
+ * Sin dependencias a propósito, base64 incluido: este archivo lo carga todo
+ * agente que arranca, y no sale a cuenta arrastrar un paquete por 12 líneas.
+ */
+/**
+ * Los proveedores conocidos, por nombre corto.
+ *
+ * Lo que fija cada entrada es la URL y el dialecto —lo estructural, lo que no
+ * cambia—. Añadir uno nuevo es una línea, y usar uno que no esté en la lista
+ * no requiere tocar este archivo: se pone `LLM_BASE_URL` a pelo.
+ */
+export const PROVEEDORES = {
+    openai: { baseUrl: 'https://api.openai.com/v1', dialecto: 'openai', modeloSugerido: 'gpt-4o-mini' },
+    claude: { baseUrl: 'https://api.anthropic.com', dialecto: 'anthropic', modeloSugerido: 'claude-opus-5' },
+    anthropic: { baseUrl: 'https://api.anthropic.com', dialecto: 'anthropic', modeloSugerido: 'claude-opus-5' },
+    gemini: {
+        baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+        dialecto: 'gemini',
+        modeloSugerido: 'gemini-2.0-flash',
+    },
+    kimi: { baseUrl: 'https://api.moonshot.ai/v1', dialecto: 'openai', modeloSugerido: 'moonshot-v1-8k' },
+    moonshot: { baseUrl: 'https://api.moonshot.ai/v1', dialecto: 'openai', modeloSugerido: 'moonshot-v1-8k' },
+    grok: { baseUrl: 'https://api.x.ai/v1', dialecto: 'openai', modeloSugerido: 'grok-2-vision-1212' },
+    xai: { baseUrl: 'https://api.x.ai/v1', dialecto: 'openai', modeloSugerido: 'grok-2-vision-1212' },
+    glm: { baseUrl: 'https://open.bigmodel.cn/api/paas/v4', dialecto: 'openai', modeloSugerido: 'glm-4v' },
+    zhipu: { baseUrl: 'https://open.bigmodel.cn/api/paas/v4', dialecto: 'openai', modeloSugerido: 'glm-4v' },
+    deepseek: { baseUrl: 'https://api.deepseek.com/v1', dialecto: 'openai', modeloSugerido: 'deepseek-chat' },
+    groq: {
+        baseUrl: 'https://api.groq.com/openai/v1',
+        dialecto: 'openai',
+        modeloSugerido: 'llama-3.3-70b-versatile',
+    },
+    openrouter: { baseUrl: 'https://openrouter.ai/api/v1', dialecto: 'openai' },
+    mistral: { baseUrl: 'https://api.mistral.ai/v1', dialecto: 'openai', modeloSugerido: 'mistral-small-latest' },
+    together: { baseUrl: 'https://api.together.xyz/v1', dialecto: 'openai' },
+    // Local, sin clave y sin factura. Útil para probar un agente sin gastar.
+    ollama: { baseUrl: 'http://localhost:11434/v1', dialecto: 'openai', modeloSugerido: 'llama3.2' },
+};
+/**
+ * Qué dialecto habla una URL.
+ *
+ * Se mira el host y no la ruta: un proxy corporativo cambia el camino, pero
+ * quien contesta al otro lado sigue siendo el mismo. Lo que no se reconoce se
+ * trata como OpenAI, que es lo que implementa casi todo el mundo — y si se
+ * falla, se falla del lado que tiene arreglo con `LLM_DIALECT`.
+ */
+export function dialectoDe(baseUrl) {
+    let host;
+    try {
+        host = new URL(baseUrl).hostname.toLowerCase();
+    }
+    catch {
+        return 'openai';
+    }
+    if (host.endsWith('anthropic.com'))
+        return 'anthropic';
+    if (host.endsWith('googleapis.com'))
+        return 'gemini';
+    return 'openai';
+}
+export class LlmError extends Error {
+    fatal;
+    constructor(message, 
+    /** De configuración: reintentarlo sólo gasta tiempo y dinero. */
+    fatal = false) {
+        super(message);
+        this.fatal = fatal;
+        this.name = 'LlmError';
+    }
+}
+/**
+ * Lee la configuración del entorno.
+ *
+ * `LLM_PROVIDER` es el camino corto (`claude`, `kimi`, `gemini`…) y
+ * `LLM_BASE_URL` el largo, para cualquiera que no esté en la lista. Si están
+ * los dos, manda la URL: quien la escribe a mano sabe lo que quiere.
+ */
+export function resolverLlm(env) {
+    const nombre = env.LLM_PROVIDER?.trim().toLowerCase();
+    const preset = nombre ? PROVEEDORES[nombre] : undefined;
+    if (nombre && !preset && !env.LLM_BASE_URL?.trim()) {
+        throw new LlmError(`LLM_PROVIDER="${nombre}" no está en la lista (${Object.keys(PROVEEDORES).join(', ')}). ` +
+            `Si tu proveedor no está, pon LLM_BASE_URL con su endpoint y ya.`, true);
+    }
+    const baseUrl = (env.LLM_BASE_URL?.trim() || preset?.baseUrl || '').replace(/\/$/, '');
+    if (!baseUrl) {
+        throw new LlmError('Falta LLM_PROVIDER o LLM_BASE_URL: el agente no sabe a quién preguntarle.', true);
+    }
+    const model = env.LLM_MODEL?.trim() || preset?.modeloSugerido;
+    if (!model) {
+        throw new LlmError(`Falta LLM_MODEL: ${baseUrl} no tiene un modelo por defecto que se pueda suponer.`, true);
+    }
+    const forzado = env.LLM_DIALECT?.trim().toLowerCase();
+    if (forzado && forzado !== 'openai' && forzado !== 'anthropic' && forzado !== 'gemini') {
+        throw new LlmError(`LLM_DIALECT="${forzado}" no existe. Es openai, anthropic o gemini.`, true);
+    }
+    return {
+        baseUrl,
+        apiKey: env.LLM_API_KEY?.trim() ?? '',
+        model,
+        dialecto: forzado ?? preset?.dialecto ?? dialectoDe(baseUrl),
+        ...(env.LLM_TIMEOUT_MS ? { timeoutMs: Number(env.LLM_TIMEOUT_MS) } : {}),
+        ...(env.LLM_MAX_TOKENS ? { maxTokens: Number(env.LLM_MAX_TOKENS) } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Imágenes
+// ---------------------------------------------------------------------------
+/**
+ * Los formatos que aceptan los tres dialectos a la vez.
+ *
+ * Es la intersección y no la unión: un agente que acepta un TIFF porque su
+ * proveedor de hoy lo admite se rompe el día que cambie de proveedor, y se
+ * rompe con el cliente esperando y el pago bloqueado.
+ */
+export const MIMES_IMAGEN = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
+/** Tope por imagen. Por encima, los proveedores empiezan a rechazar peticiones. */
+export const MAX_IMAGEN_BYTES = 5 * 1024 * 1024;
+export function esImagenSoportada(mime) {
+    return !!mime && MIMES_IMAGEN.includes(mime.toLowerCase());
+}
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** base64 a mano: ni Buffer (Node) ni btoa (navegador), así vale en los dos. */
+function aBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i];
+        const b = bytes[i + 1];
+        const c = bytes[i + 2];
+        const trio = (a << 16) | ((b ?? 0) << 8) | (c ?? 0);
+        out += B64[(trio >> 18) & 63] + B64[(trio >> 12) & 63];
+        out += b === undefined ? '=' : B64[(trio >> 6) & 63];
+        out += c === undefined ? '=' : B64[trio & 63];
+    }
+    return out;
+}
+function prepararImagenes(imagenes) {
+    return imagenes.map((img) => {
+        const mime = img.mime.toLowerCase();
+        if (!esImagenSoportada(mime)) {
+            throw new LlmError(`No se puede enseñar un ${img.mime} a un modelo. Sólo ${MIMES_IMAGEN.join(', ')}.`, true);
+        }
+        if (img.bytes.byteLength > MAX_IMAGEN_BYTES) {
+            throw new LlmError(`Una imagen de ${img.bytes.byteLength} bytes pasa del tope de ${MAX_IMAGEN_BYTES}. Redúcela antes de mandarla.`, true);
+        }
+        return { mime, b64: aBase64(img.bytes) };
+    });
+}
+function construir(cfg, pet) {
+    const imgs = prepararImagenes(pet.imagenes ?? []);
+    const maxTokens = cfg.maxTokens ?? 4096;
+    const base = cfg.baseUrl.replace(/\/$/, '');
+    if (cfg.dialecto === 'anthropic') {
+        // La base puede venir con o sin /v1 según de dónde la haya copiado quien
+        // configura; las dos formas circulan en la documentación de todo el mundo.
+        const url = /\/v1$/.test(base) ? `${base}/messages` : `${base}/v1/messages`;
+        return {
+            url,
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': cfg.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: {
+                model: cfg.model,
+                max_tokens: maxTokens,
+                ...(pet.system ? { system: pet.system } : {}),
+                messages: [
+                    {
+                        role: 'user',
+                        content: [
+                            ...imgs.map((i) => ({
+                                type: 'image',
+                                source: { type: 'base64', media_type: i.mime, data: i.b64 },
+                            })),
+                            { type: 'text', text: pet.user },
+                        ],
+                    },
+                ],
+            },
+        };
+    }
+    if (cfg.dialecto === 'gemini') {
+        return {
+            url: `${base}/models/${encodeURIComponent(cfg.model)}:generateContent`,
+            // La clave va en cabecera y no en la query: una URL acaba en los logs
+            // del proxy, en el historial y en el `Referer`, y una clave ahí es una
+            // clave regalada.
+            headers: { 'content-type': 'application/json', 'x-goog-api-key': cfg.apiKey },
+            body: {
+                ...(pet.system ? { systemInstruction: { parts: [{ text: pet.system }] } } : {}),
+                contents: [
+                    {
+                        role: 'user',
+                        parts: [
+                            ...imgs.map((i) => ({ inline_data: { mime_type: i.mime, data: i.b64 } })),
+                            { text: pet.user },
+                        ],
+                    },
+                ],
+                generationConfig: {
+                    maxOutputTokens: maxTokens,
+                    ...(cfg.temperature === undefined ? {} : { temperature: cfg.temperature }),
+                },
+            },
+        };
+    }
+    // openai. El contenido va como STRING cuando no hay imágenes: la forma de
+    // array es válida en la especificación, pero unos cuantos clones compatibles
+    // la rechazan, y no hay motivo para arriesgarse en el caso normal.
+    return {
+        url: `${base}/chat/completions`,
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${cfg.apiKey}` },
+        body: {
+            model: cfg.model,
+            max_tokens: maxTokens,
+            ...(cfg.temperature === undefined ? {} : { temperature: cfg.temperature }),
+            messages: [
+                ...(pet.system ? [{ role: 'system', content: pet.system }] : []),
+                {
+                    role: 'user',
+                    content: imgs.length
+                        ? [
+                            { type: 'text', text: pet.user },
+                            ...imgs.map((i) => ({
+                                type: 'image_url',
+                                image_url: { url: `data:${i.mime};base64,${i.b64}` },
+                            })),
+                        ]
+                        : pet.user,
+                },
+            ],
+        },
+    };
+}
+/**
+ * Baja por una ruta de un JSON ajeno sin fiarse de ningún tramo.
+ *
+ * Lo que contesta el proveedor no lo controlamos, y un `choices[0].message`
+ * que hoy existe puede llegar mañana como `null` en mitad de una incidencia
+ * suya. Devolver `undefined` en vez de reventar deja que el error que se
+ * enseñe sea el de arriba, que sí explica lo que pasó.
+ */
+function campo(raiz, ...ruta) {
+    let actual = raiz;
+    for (const paso of ruta) {
+        if (actual === null || typeof actual !== 'object')
+            return undefined;
+        actual = actual[paso];
+    }
+    return actual;
+}
+function texto(valor) {
+    return typeof valor === 'string' ? valor : '';
+}
+/** Junta el texto de una lista de bloques, saltándose lo que no lo sea. */
+function juntarBloques(bloques, clave, tipo) {
+    if (!Array.isArray(bloques))
+        return '';
+    return bloques
+        .map((b) => (tipo && campo(b, 'type') !== tipo ? '' : texto(campo(b, clave))))
+        .join('')
+        .trim();
+}
+function leer(dialecto, json) {
+    const error = texto(campo(json, 'error', 'message'));
+    if (dialecto === 'anthropic') {
+        const salida = juntarBloques(campo(json, 'content'), 'text', 'text');
+        if (salida)
+            return salida;
+        if (campo(json, 'stop_reason') === 'refusal') {
+            throw new LlmError('El modelo se negó a responder a este encargo.', true);
+        }
+        throw new LlmError(`Respuesta sin texto: ${error || texto(campo(json, 'stop_reason')) || 'vacía'}`);
+    }
+    if (dialecto === 'gemini') {
+        const salida = juntarBloques(campo(json, 'candidates', 0, 'content', 'parts'), 'text');
+        if (salida)
+            return salida;
+        const motivo = texto(campo(json, 'candidates', 0, 'finishReason')) || texto(campo(json, 'promptFeedback', 'blockReason'));
+        throw new LlmError(`Respuesta sin texto: ${error || motivo || 'sin candidatos'}`);
+    }
+    const salida = texto(campo(json, 'choices', 0, 'message', 'content')).trim();
+    if (!salida)
+        throw new LlmError(`Respuesta sin texto: ${error || 'choices vacío'}`);
+    return salida;
+}
+function dormir(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Una pregunta, una respuesta, con reintentos.
+ *
+ * Se reintentan 429 y 5xx —el proveedor está saturado, es cuestión de
+ * esperar— y NO se reintenta un 4xx: una clave mal escrita o un modelo que no
+ * existe dan lo mismo al segundo intento, y mientras tanto el plazo de la
+ * tarea corre.
+ */
+export async function llmChat(cfg, pet) {
+    if (!cfg.apiKey && !/^https?:\/\/(localhost|127\.0\.0\.1)/.test(cfg.baseUrl)) {
+        throw new LlmError('Falta LLM_API_KEY.', true);
+    }
+    const { url, headers, body } = construir(cfg, pet);
+    const maxRetries = cfg.maxRetries ?? 2;
+    const timeoutMs = cfg.timeoutMs ?? 120_000;
+    let ultimo;
+    for (let intento = 0; intento <= maxRetries; intento++) {
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (res.status === 429 || res.status >= 500) {
+                throw new LlmError(`HTTP ${res.status} ${res.statusText}`);
+            }
+            if (!res.ok) {
+                const cuerpo = await res.text().catch(() => '');
+                throw new LlmError(`HTTP ${res.status}: ${cuerpo.slice(0, 300)}`, true);
+            }
+            return leer(cfg.dialecto, await res.json());
+        }
+        catch (err) {
+            ultimo = err;
+            if (err instanceof LlmError && err.fatal)
+                throw err;
+            if (intento < maxRetries)
+                await dormir(Math.min(2_000 * 2 ** intento, 30_000));
+        }
+    }
+    throw ultimo instanceof Error ? ultimo : new LlmError(String(ultimo));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/sdk.test.ts && tsx test/x402.test.ts && tsx test/x402-server.test.ts && tsx test/envelope.test.ts && tsx test/files.test.ts && tsx test/skill.test.ts",
+    "test": "tsx test/sdk.test.ts && tsx test/x402.test.ts && tsx test/x402-server.test.ts && tsx test/envelope.test.ts && tsx test/files.test.ts && tsx test/attachments.test.ts && tsx test/llm.test.ts && tsx test/skill.test.ts && tsx test/agent-card.test.ts",
     "test:nombres": "tsx test/nombres.test.ts"
   }
 }