@panal/sdk 0.16.0 → 0.17.0

package/dist/agent-card.d.ts

@@ -98,6 +98,14 @@ export interface FichaNivel {
     /** Y el de todos los adjuntos juntos. */
     maxAttachCharsTotal?: number;
 }
+/** Dónde deja el cliente los bytes de lo que su encargo anuncia. */
+export interface FichaPostAttachment {
+    method?: 'POST';
+    /** Ruta relativa, con `:taskId` dentro. */
+    path?: string;
+    /** Tope por archivo, en bytes. */
+    maxAttachmentBytes?: number;
+}
 export interface AgentCard {
     /** La dirección on-chain que este dominio declara suya. Es lo que verifica. */
     agent?: Address;
@@ -108,6 +116,18 @@ export interface AgentCard {
     chainId?: number;
     name?: string;
     description?: string;
+    /**
+     * El idioma en el que va este `description` y estos `tiers`, si se pidió con
+     * `?lang=` y el agente pudo traducirlos.
+     *
+     * AUSENTE NO ES «está en inglés»: es que va en el idioma en que su dueño lo
+     * escribió, aunque hayas pedido otro. Hay que mirarlo antes de guardar una
+     * ficha como si fuera una traducción, porque la traducción se encarga por
+     * detrás: pedirla antes de que esté lista devuelve la ficha original con un
+     * 200 impecable. Un indexador que no lo mirara guardaría el texto original
+     * como las diez traducciones y no volvería a por ellas nunca.
+     */
+    lang?: string;
     skills?: string[];
     price?: {
         amountWei?: string;
@@ -135,6 +155,16 @@ export interface AgentCard {
         postBrief?: FichaPostBrief;
         getResult?: FichaGetResult;
         x402Ask?: FichaX402;
+        /**
+         * Dónde subir los archivos que el encargo anuncia, si los acepta.
+         *
+         * AUSENTE ES «no los acepta». Importa porque el manifiesto de adjuntos
+         * viaja DENTRO del brief —dentro de lo que se hashea al pagar—, así que un
+         * agente sin esta ruta acepta el encargo, trabaja sin los archivos,
+         * entrega y cobra sin que nada dé error. Por eso el cliente pregunta antes
+         * de ofrecer el clip; ver `leerCapacidades` en la web.
+         */
+        postAttachment?: FichaPostAttachment;
         indexer?: string | null;
     };
     /** Alias ANTIGUO de `endpoints.x402Ask`. Se lee; no se escribe. */

package/dist/client.js

@@ -18,7 +18,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 { assertPublicUrl, fetchLimited, rutaDeAgente } from './net.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
@@ -780,7 +780,7 @@ export class PanalClient {
         if (!base)
             throw new X402Error(`El agente ${agent} no publica endpoint en su metadata.`);
         try {
-            const url = await assertPublicUrl(new URL('/agent.json', base).toString(), options);
+            const url = await assertPublicUrl(rutaDeAgente(base, 'agent.json'), options);
             const res = await fetchLimited(url, { timeoutMs: 10_000 });
             if (res.status === 200) {
                 // `leerX402` entiende las dos formas. Antes esto solo miraba
@@ -791,13 +791,13 @@ export class PanalClient {
                 if (anunciado?.url)
                     return anunciado.url;
                 if (anunciado?.path)
-                    return new URL(anunciado.path, base).toString();
+                    return rutaDeAgente(base, anunciado.path);
             }
         }
         catch {
             /* sin tarjeta o ilegible: se cae a la convención */
         }
-        return new URL('/x402/ask', base).toString();
+        return rutaDeAgente(base, 'x402/ask');
     }
     /** Retira lo acreditado en una moneda (patrón pull payment). */
     async withdraw(currency = NATIVE_CURRENCY) {

package/dist/index.d.ts

@@ -39,7 +39,10 @@ export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhau
 export type { CallEnvelope } from './envelope.js';
 export type { UrlGuardOptions } from './net.js';
 export { leerDireccion, leerMaxBriefChars, leerNiveles, leerX402, nivelPara } from './agent-card.js';
-export type { AgentCard, FichaGetResult, FichaNivel, FichaPostBrief, FichaX402, Nivel } from './agent-card.js';
-export { componerNivel, esTokenDeNivel, leerNivelDeSegmento, leerNivelesDeMetadata, NIVELES_EDITABLES, precioAWei, weiAPrecio, } from './niveles.js';
+export type { AgentCard, FichaGetResult, FichaNivel, FichaPostAttachment, FichaPostBrief, FichaX402, Nivel, } from './agent-card.js';
+export { componerNivel, conTextoDeLaFicha, esTokenDeNivel, leerNivelDeSegmento, leerNivelesDeMetadata, NIVELES_EDITABLES, precioAWei, weiAPrecio, } from './niveles.js';
+export { esTokenDeTipo, leerTipo, leerTipoDeSegmento, tokenDeTipo } from './tipo.js';
+export type { TipoDeAgente } from './tipo.js';
+export { rutaDeAgente } from './net.js';
 export { fichaEnIdioma, IDIOMAS, NOMBRE_IDIOMA, normalizarIdioma } from './idiomas.js';
 export type { Idioma } from './idiomas.js';

package/dist/index.js

@@ -42,7 +42,13 @@ export { ENVELOPE_HEADERS, DEFAULT_DEPTH, MAX_DEPTH, BudgetExhausted, DepthExhau
 export { leerDireccion, leerMaxBriefChars, leerNiveles, leerX402, nivelPara } from './agent-card.js';
 // Los niveles escritos en el metadataURI on-chain. Mismo tipo `Nivel` que los
 // de la ficha; en niveles.ts está por qué viven en los dos sitios.
-export { componerNivel, esTokenDeNivel, leerNivelDeSegmento, leerNivelesDeMetadata, NIVELES_EDITABLES, precioAWei, weiAPrecio, } from './niveles.js';
+export { componerNivel, conTextoDeLaFicha, esTokenDeNivel, leerNivelDeSegmento, leerNivelesDeMetadata, NIVELES_EDITABLES, precioAWei, weiAPrecio, } from './niveles.js';
+// Quién hay al otro lado: una persona o un programa. Va en la misma cadena que
+// los niveles, y por lo mismo lo tienen que reconocer todos los que la leen.
+export { esTokenDeTipo, leerTipo, leerTipoDeSegmento, tokenDeTipo } from './tipo.js';
 // La ficha en el idioma de quien la lee. En idiomas.ts está por qué traduce el
 // propio agente y no un servicio de Panal.
+// Unir una ruta con la URL de un agente. Ver por qué en `net.ts`: un agente
+// puede vivir en un subcamino, y `new URL('/x', base)` se lo come.
+export { rutaDeAgente } from './net.js';
 export { fichaEnIdioma, IDIOMAS, NOMBRE_IDIOMA, normalizarIdioma } from './idiomas.js';

package/dist/net.d.ts

@@ -53,3 +53,18 @@ export declare function fetchLimited(url: URL | string, init?: RequestInit & {
     headers: Headers;
     text: string;
 }>;
+/**
+ * Una ruta del agente, colgando de DONDE está el agente.
+ *
+ * Parece una tontería y no lo es: `new URL('/brief/12', base)` descarta el
+ * camino de la base. Con un agente que vive en la raíz de su dominio
+ * —`https://bot.panal.lat`— da lo mismo y funcionó siempre; con uno que vive
+ * en un subcamino —`https://api.panal.lat/buzon/0xAAA`, que es donde reciben
+ * los que no tienen servidor propio— manda la petición a
+ * `https://api.panal.lat/brief/12`, que no es de nadie.
+ *
+ * Y lo que se rompe así no avisa: el 404 se lee como «ese agente no contesta»
+ * con el pago ya bloqueado, y a las 72 h se libera solo. Por eso la unión de
+ * rutas se hace en un sitio y no a mano en cada llamada.
+ */
+export declare function rutaDeAgente(base: string, ruta: string): string;

package/dist/net.js

@@ -148,3 +148,20 @@ export async function fetchLimited(url, init = {}) {
     const { status, headers, bytes } = await fetchBytesLimited(url, init);
     return { status, headers, text: new TextDecoder().decode(bytes) };
 }
+/**
+ * Una ruta del agente, colgando de DONDE está el agente.
+ *
+ * Parece una tontería y no lo es: `new URL('/brief/12', base)` descarta el
+ * camino de la base. Con un agente que vive en la raíz de su dominio
+ * —`https://bot.panal.lat`— da lo mismo y funcionó siempre; con uno que vive
+ * en un subcamino —`https://api.panal.lat/buzon/0xAAA`, que es donde reciben
+ * los que no tienen servidor propio— manda la petición a
+ * `https://api.panal.lat/brief/12`, que no es de nadie.
+ *
+ * Y lo que se rompe así no avisa: el 404 se lee como «ese agente no contesta»
+ * con el pago ya bloqueado, y a las 72 h se libera solo. Por eso la unión de
+ * rutas se hace en un sitio y no a mano en cada llamada.
+ */
+export function rutaDeAgente(base, ruta) {
+    return `${base.replace(/\/+$/, '')}/${ruta.replace(/^\/+/, '')}`;
+}

package/dist/niveles.d.ts

@@ -100,3 +100,34 @@ export declare function componerNivel(nivel: {
     maxAttachChars?: number | null;
     maxAttachCharsTotal?: number | null;
 }): string | null;
+/**
+ * Los niveles de la cadena, con el texto de la ficha del agente.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ HACE FALTA JUNTARLOS, EN VEZ DE ELEGIR UNO
+ *
+ * Un nivel es dos cosas distintas con dueños distintos:
+ *
+ *   - El PRECIO y los topes. Es lo que se bloquea en el escrow, y tiene que
+ *     salir de la cadena: son los únicos que siguen ahí con el bot caído, y los
+ *     únicos que nadie puede cambiarte entre que miras y pagas.
+ *
+ *   - El NOMBRE y la descripción. Son una etiqueta, y la ficha del agente es el
+ *     único sitio donde pueden estar TRADUCIDAS: `?lang=fr` devuelve la ficha
+ *     en francés, la cadena guarda una sola versión y traducirla costaría una
+ *     transacción por idioma.
+ *
+ * Quedarse solo con los de la cadena —que es lo que se hizo primero— deja el
+ * escaparate entero en francés y los tres niveles de cada agente en español.
+ * Quedarse solo con los de la ficha devuelve el problema de antes: un agente
+ * caído se queda sin niveles y se le encarga el tamaño grande al precio del
+ * pequeño.
+ *
+ * SE EMPAREJAN POR PRECIO, que es la identidad de un nivel: el agente arma su
+ * ficha a partir de lo que tiene en la cadena, así que los importes coinciden
+ * exactos. Lo que no empareje se queda con su texto de la cadena, que es la
+ * respuesta correcta cuando la ficha dice otra cosa: enseñar el nombre de un
+ * nivel junto a un precio que no es el suyo sería peor que no traducirlo.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+export declare function conTextoDeLaFicha(enCadena: Nivel[], deLaFicha: Nivel[]): Nivel[];

package/dist/niveles.js

@@ -208,3 +208,49 @@ export function componerNivel(nivel) {
 function entero(v) {
     return typeof v === 'number' && Number.isInteger(v) && v > 0 ? String(v) : '';
 }
+/**
+ * Los niveles de la cadena, con el texto de la ficha del agente.
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * POR QUÉ HACE FALTA JUNTARLOS, EN VEZ DE ELEGIR UNO
+ *
+ * Un nivel es dos cosas distintas con dueños distintos:
+ *
+ *   - El PRECIO y los topes. Es lo que se bloquea en el escrow, y tiene que
+ *     salir de la cadena: son los únicos que siguen ahí con el bot caído, y los
+ *     únicos que nadie puede cambiarte entre que miras y pagas.
+ *
+ *   - El NOMBRE y la descripción. Son una etiqueta, y la ficha del agente es el
+ *     único sitio donde pueden estar TRADUCIDAS: `?lang=fr` devuelve la ficha
+ *     en francés, la cadena guarda una sola versión y traducirla costaría una
+ *     transacción por idioma.
+ *
+ * Quedarse solo con los de la cadena —que es lo que se hizo primero— deja el
+ * escaparate entero en francés y los tres niveles de cada agente en español.
+ * Quedarse solo con los de la ficha devuelve el problema de antes: un agente
+ * caído se queda sin niveles y se le encarga el tamaño grande al precio del
+ * pequeño.
+ *
+ * SE EMPAREJAN POR PRECIO, que es la identidad de un nivel: el agente arma su
+ * ficha a partir de lo que tiene en la cadena, así que los importes coinciden
+ * exactos. Lo que no empareje se queda con su texto de la cadena, que es la
+ * respuesta correcta cuando la ficha dice otra cosa: enseñar el nombre de un
+ * nivel junto a un precio que no es el suyo sería peor que no traducirlo.
+ * ───────────────────────────────────────────────────────────────────────────
+ */
+export function conTextoDeLaFicha(enCadena, deLaFicha) {
+    if (enCadena.length === 0 || deLaFicha.length === 0)
+        return enCadena;
+    return enCadena.map((n) => {
+        const igual = deLaFicha.find((f) => f.wei === n.wei);
+        if (!igual)
+            return n;
+        return {
+            ...n,
+            // Solo se pisa lo que la ficha REALMENTE trae: un nivel con nombre no
+            // puede perderlo porque la ficha venga a medias.
+            name: igual.name ?? n.name,
+            description: igual.description ?? n.description,
+        };
+    });
+}

package/dist/tipo.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Panal — quién hay al otro lado: una persona o un programa.
+ *
+ * Un token más de los que viven en el `metadataURI` on-chain, junto a `bot:`,
+ * los de marca y los de nivel:
+ *
+ *     Marta · Traduce contratos ES⇄FR · traducción · tipo:persona · bot:…
+ *
+ * POR QUÉ ESTÁ EN LA CADENA Y NO EN LA TARJETA
+ *
+ * Porque es lo que decide en qué mercado sale y con quién se le compara, y eso
+ * no puede depender de que un servidor conteste. Una persona que apaga el
+ * ordenador el viernes no se convierte en un bot el sábado.
+ *
+ * POR QUÉ NO SE ADIVINA
+ *
+ * Se podría intentar: quien usa el buzón de Panal parece una persona, quien
+ * tiene servidor propio parece un bot. Las dos cosas son falsas —un bot puede
+ * usar el buzón y una persona puede montarse un servidor—, y equivocarse aquí
+ * es etiquetar a alguien de lo que no es. Así que se declara, y quien no
+ * declara nada es lo que han sido todos los agentes registrados hasta hoy: un
+ * programa.
+ *
+ * LO QUE ESTE TOKEN NO ES
+ *
+ * No es una verificación. Nadie comprueba que detrás de `tipo:persona` haya
+ * una persona, igual que nadie comprueba que detrás de un nombre haya quien
+ * dice. Lo que hace es que la respuesta sea SUYA y esté firmada, en vez de que
+ * la deduzca el mercado por su cuenta.
+ */
+/** Quién trabaja: una persona, o un programa. */
+export type TipoDeAgente = 'persona' | 'bot';
+/**
+ * Qué dice un segmento, o `null` si no es uno de estos.
+ *
+ * Solo se reconocen los dos valores. `tipo:` con cualquier otra cosa detrás no
+ * es un tipo desconocido que haya que respetar: es texto que alguien escribió
+ * mal, y tratarlo como token lo borraría de su descripción sin decírselo.
+ */
+export declare function leerTipoDeSegmento(segmento: string): TipoDeAgente | null;
+/** true si este segmento es un tipo. Para que los lectores de ficha lo aparten. */
+export declare function esTokenDeTipo(segmento: string): boolean;
+/**
+ * Quién hay detrás de esta ficha. Sin token, un programa.
+ *
+ * Ausente NO es «no se sabe» a efectos de enseñarlo: hay que ponerlo en algún
+ * mercado, y el sitio honrado para los diez agentes que ya estaban registrados
+ * antes de que esto existiera es el de programas, que es lo que son.
+ */
+export declare function leerTipo(metadataURI: string | null | undefined): TipoDeAgente;
+/**
+ * El token que hay que escribir, o `null` si no hay que escribir ninguno.
+ *
+ * `bot` no escribe nada a propósito. Es lo que se supone sin token, así que
+ * escribirlo alarga la ficha de todos los agentes —y el gas de registrarlos—
+ * para no decir nada que no se supiera.
+ */
+export declare function tokenDeTipo(tipo: TipoDeAgente): string | null;

package/dist/tipo.js

@@ -0,0 +1,77 @@
+/**
+ * Panal — quién hay al otro lado: una persona o un programa.
+ *
+ * Un token más de los que viven en el `metadataURI` on-chain, junto a `bot:`,
+ * los de marca y los de nivel:
+ *
+ *     Marta · Traduce contratos ES⇄FR · traducción · tipo:persona · bot:…
+ *
+ * POR QUÉ ESTÁ EN LA CADENA Y NO EN LA TARJETA
+ *
+ * Porque es lo que decide en qué mercado sale y con quién se le compara, y eso
+ * no puede depender de que un servidor conteste. Una persona que apaga el
+ * ordenador el viernes no se convierte en un bot el sábado.
+ *
+ * POR QUÉ NO SE ADIVINA
+ *
+ * Se podría intentar: quien usa el buzón de Panal parece una persona, quien
+ * tiene servidor propio parece un bot. Las dos cosas son falsas —un bot puede
+ * usar el buzón y una persona puede montarse un servidor—, y equivocarse aquí
+ * es etiquetar a alguien de lo que no es. Así que se declara, y quien no
+ * declara nada es lo que han sido todos los agentes registrados hasta hoy: un
+ * programa.
+ *
+ * LO QUE ESTE TOKEN NO ES
+ *
+ * No es una verificación. Nadie comprueba que detrás de `tipo:persona` haya
+ * una persona, igual que nadie comprueba que detrás de un nombre haya quien
+ * dice. Lo que hace es que la respuesta sea SUYA y esté firmada, en vez de que
+ * la deduzca el mercado por su cuenta.
+ */
+/** El prefijo del token, en minúsculas. */
+const PREFIJO = 'tipo:';
+/**
+ * Qué dice un segmento, o `null` si no es uno de estos.
+ *
+ * Solo se reconocen los dos valores. `tipo:` con cualquier otra cosa detrás no
+ * es un tipo desconocido que haya que respetar: es texto que alguien escribió
+ * mal, y tratarlo como token lo borraría de su descripción sin decírselo.
+ */
+export function leerTipoDeSegmento(segmento) {
+    const s = segmento.trim();
+    if (!s.toLowerCase().startsWith(PREFIJO))
+        return null;
+    const valor = s.slice(PREFIJO.length).trim().toLowerCase();
+    return valor === 'persona' || valor === 'bot' ? valor : null;
+}
+/** true si este segmento es un tipo. Para que los lectores de ficha lo aparten. */
+export function esTokenDeTipo(segmento) {
+    return leerTipoDeSegmento(segmento) !== null;
+}
+/**
+ * Quién hay detrás de esta ficha. Sin token, un programa.
+ *
+ * Ausente NO es «no se sabe» a efectos de enseñarlo: hay que ponerlo en algún
+ * mercado, y el sitio honrado para los diez agentes que ya estaban registrados
+ * antes de que esto existiera es el de programas, que es lo que son.
+ */
+export function leerTipo(metadataURI) {
+    if (!metadataURI)
+        return 'bot';
+    for (const seg of metadataURI.split('·')) {
+        const tipo = leerTipoDeSegmento(seg);
+        if (tipo)
+            return tipo;
+    }
+    return 'bot';
+}
+/**
+ * El token que hay que escribir, o `null` si no hay que escribir ninguno.
+ *
+ * `bot` no escribe nada a propósito. Es lo que se supone sin token, así que
+ * escribirlo alarga la ficha de todos los agentes —y el gas de registrarlos—
+ * para no decir nada que no se supiera.
+ */
+export function tokenDeTipo(tipo) {
+    return tipo === 'persona' ? `${PREFIJO}persona` : null;
+}

package/dist/types.js

@@ -8,6 +8,7 @@
  * se veía al mirar la ficha en el marketplace.
  */
 import { esTokenDeNivel } from './niveles.js';
+import { esTokenDeTipo } from './tipo.js';
 /** Estados de una tarea en el escrow, en el mismo orden que el enum de Solidity. */
 export var TaskStatus;
 (function (TaskStatus) {
@@ -170,6 +171,10 @@ export function parseAgentMetadata(metadataURI) {
         // `leerNivelesDeMetadata`; aquí solo hace falta reconocerlos.
         if (esTokenDeNivel(seg))
             continue;
+        // Y quién hay detrás, por lo mismo: sin apartarlo, `tipo:persona` saldría
+        // anunciado como una skill de esa persona.
+        if (esTokenDeTipo(seg))
+            continue;
         rest.push(seg);
     }
     // Los campos que falten quedan vacíos en vez de desplazar a los siguientes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panal/sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "SDK de Panal: contrata agentes de IA autonomos on-chain en Monad",
   "type": "module",
   "license": "MIT",