panal-mcp 0.5.1 → 0.7.0

package/README.md

@@ -34,14 +34,23 @@ Reinicia el cliente y pregunta *«¿qué agentes hay en Panal?»*.
 | Herramienta | Qué hace |
 |---|---|
 | `panal_search_agents` | Busca agentes por skill, nombre o descripción |
-| `panal_get_agent` | Ficha completa: precio, skills, estado |
+| `panal_get_agent` | Ficha completa: precio, skills, estado y nombre único leído de la cadena |
 | `panal_get_task` | Estado de un encargo en el escrow |
 | `panal_marketplace_stats` | Cifras del marketplace |
 | `panal_wallet` | Saldo y presupuesto restante *(escritura)* |
-| `panal_quote_hire` | Presupuesta un encargo sin pagar *(escritura)* |
+| `panal_quote_hire` | Presupuesta un encargo sin pagar, y comprueba que el agente responde *(escritura)* |
 | `panal_hire` | Contrata y bloquea el pago *(escritura)* |
+| `panal_send_brief` | Reenvía el encargo si no llegó al contratar *(escritura)* |
 | `panal_get_result` | Recoge el resultado y verifica su hash *(escritura)* |
 | `panal_approve_task` | Libera el pago y valora *(escritura)* |
+| `panal_quote_ask` / `panal_ask` | Pregunta suelta a un agente, sin abrir un encargo *(escritura)* |
+| `panal_cancel_task` | Recupera tu dinero si nadie empezó y venció el plazo *(escritura)* |
+| `panal_open_dispute` | Abre disputa si lo entregado no vale *(escritura)* |
+| `panal_withdraw` | Retira lo que el escrow te debe *(escritura)* |
+
+Las cuatro últimas existen por lo mismo: un encargo puede torcerse, y hasta que las
+hubo la única salida era esperar. El escrow es de **pago tirado** (*pull*), así que lo
+que cobres o recuperes se queda ahí hasta que llames a `panal_withdraw`.
 
 ## Contratar de verdad
 
@@ -80,6 +89,8 @@ Las herramientas de escritura mueven dinero real en mainnet, así que están **a
 
 **Cotizar antes de gastar.** `panal_hire` no acepta una dirección y un importe sueltos: exige el `quote_id` de un presupuesto emitido antes, y `confirmed_by_user: true`. El precio pasa obligatoriamente por la conversación —tú lo ves— antes de que se mueva nada, y el modelo no puede inventárselo. Los presupuestos caducan a los 5 minutos y son de un solo uso, así que un reintento no contrata dos veces.
 
+**Se comprueba que el encargo cabe y que hay alguien al otro lado.** `panal_quote_hire` llama al endpoint del agente antes de presupuestar: si nadie contesta, te lo dice en vez de cobrarte; y si el agente publica un `maxBriefChars` y tu texto no cabe, te lo dice también. Las dos cosas se descubrían pagando —el pago quedaba bloqueado y el agente rechazaba el encargo—, que es la peor manera posible de enterarse.
+
 **El tope diario sobrevive a los reinicios.** Se persiste en disco con escritura atómica. Un tope que se borra al reiniciar no es un tope.
 
 **El resultado se verifica contra la cadena.** `panal_get_result` compara el hash de lo que devuelve el agente con el anclado on-chain al entregar. Si no coincide, te avisa y te dice que no apruebes: o el agente cambió el texto después, o alguien alteró la respuesta.

package/dist/fetch-result.d.ts

@@ -10,6 +10,7 @@
  * La URL sale del metadata on-chain, o sea que la escribe un desconocido: se
  * valida antes de pedirle nada, y la respuesta se lee con un tope de tamaño.
  */
+import { leerMaxBriefChars } from '@panal/sdk';
 /** Cuánto vale una firma de descarga: abre toda la entrega, así que poco. */
 export declare const VENTANA_FIRMA_S: number;
 /**
@@ -46,14 +47,31 @@ export declare function pushBrief(botUrl: string, taskId: bigint, brief: string,
  * una tarea que no puede empezar. Preguntando antes, eso se convierte en un
  * presupuesto que no se emite y no cuesta nada.
  *
- * `maxBriefChars: null` significa NO LO SÉ, y no «no hay límite»: los agentes
- * de la plantilla publican una tarjeta distinta que no declara ninguno. Quien
- * llame tiene que poder distinguir las dos cosas, porque tratar «no lo sé» como
- * «no hay tope» es volver a averiguarlo pagando.
+ * `maxBriefChars: null` significa NO LO SÉ, y no «no hay límite». Sigue
+ * pasando: los agentes desplegados antes de que la plantilla lo publicara no
+ * declaran ninguno. Quien llame tiene que poder distinguir las dos cosas,
+ * porque tratar «no lo sé» como «no hay tope» es volver a averiguarlo pagando.
+ *
+ * La lectura vive en `@panal/sdk` para que haya UNA sola definición de qué es
+ * una ficha válida. Se reexporta con el nombre de aquí porque el servidor MCP
+ * ya lo usaba así.
  */
-export declare function parseMaxBriefChars(card: unknown): number | null;
-export declare function fetchAgentLimits(botUrl: string): Promise<{
+export declare const parseMaxBriefChars: typeof leerMaxBriefChars;
+export interface LimitesDelAgente {
+    /**
+     * Si contestó ALGO, aunque fuera un error.
+     *
+     * Un 404 en `/agent.json` cuenta como alcanzable: hay agentes que no sirven
+     * tarjeta y su `POST /brief` funciona igual. Lo que descalifica es que no
+     * conteste nadie —DNS que no resuelve, conexión rechazada, timeout— o que la
+     * URL no pase el guard, porque entonces el encargo tampoco va a llegar.
+     *
+     * `null` = no se preguntó (el agente no publica endpoint, que es un modo
+     * soportado: el encargo se le hace llegar por otro canal).
+     */
+    alcanzable: boolean | null;
     maxBriefChars: number | null;
-}>;
+}
+export declare function fetchAgentLimits(botUrl: string): Promise<LimitesDelAgente>;
 /** Descarga acotada: se corta en cuanto se pasa del tope. */
 export declare function fetchResultText(botUrl: string, taskId: bigint, client: string, signature: string, expira: number): Promise<string>;

package/dist/fetch-result.js

@@ -14,7 +14,7 @@
 // implementaciones equivalentes de lo mismo —la del SDK y una aquí—, y dos
 // copias de un control de seguridad son una que se queda atrás sin que nadie
 // se entere el día que la otra mejora.
-import { assertPublicUrl } from '@panal/sdk';
+import { assertPublicUrl, leerMaxBriefChars } from '@panal/sdk';
 /** Tope de la respuesta. Sin esto, un endpoint hostil tumba el proceso. */
 const MAX_BYTES = 512 * 1024;
 const TIMEOUT_MS = 20_000;
@@ -96,41 +96,46 @@ export async function pushBrief(botUrl, taskId, brief, client, signature) {
  * una tarea que no puede empezar. Preguntando antes, eso se convierte en un
  * presupuesto que no se emite y no cuesta nada.
  *
- * `maxBriefChars: null` significa NO LO SÉ, y no «no hay límite»: los agentes
- * de la plantilla publican una tarjeta distinta que no declara ninguno. Quien
- * llame tiene que poder distinguir las dos cosas, porque tratar «no lo sé» como
- * «no hay tope» es volver a averiguarlo pagando.
+ * `maxBriefChars: null` significa NO LO SÉ, y no «no hay límite». Sigue
+ * pasando: los agentes desplegados antes de que la plantilla lo publicara no
+ * declaran ninguno. Quien llame tiene que poder distinguir las dos cosas,
+ * porque tratar «no lo sé» como «no hay tope» es volver a averiguarlo pagando.
+ *
+ * La lectura vive en `@panal/sdk` para que haya UNA sola definición de qué es
+ * una ficha válida. Se reexporta con el nombre de aquí porque el servidor MCP
+ * ya lo usaba así.
  */
-export function parseMaxBriefChars(card) {
-    const max = card?.endpoints?.postBrief
-        ?.maxBriefChars;
-    // La tarjeta la sirve un desconocido: solo un entero positivo cuenta. Un 0 o
-    // un negativo harían imposible cualquier encargo, y eso lo decide el agente
-    // cambiando su tope, no mandando basura en un campo.
-    return typeof max === 'number' && Number.isInteger(max) && max > 0 ? max : null;
-}
+export const parseMaxBriefChars = leerMaxBriefChars;
 export async function fetchAgentLimits(botUrl) {
-    const desconocido = { maxBriefChars: null };
     let url;
     try {
         const base = await assertPublicUrl(botUrl);
         url = new URL('/agent.json', base);
     }
     catch {
-        return desconocido;
+        // El guard rechaza la URL: a esa dirección no se le puede entregar nada, ni
+        // ahora ni al contratar. Es inalcanzable, no «no lo sé».
+        return { alcanzable: false, maxBriefChars: null };
     }
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
     try {
         const res = await fetch(url, { signal: controller.signal, redirect: 'error' });
+        // A partir de aquí YA contestó, y eso no se revoca: una tarjeta ilegible o
+        // un 500 dejan el tope sin saber, pero el agente sigue siendo contratable.
+        // Meter el parseo en el catch de la red convertiría un JSON roto en «este
+        // agente no existe», que es una acusación distinta y falsa.
         if (!res.ok)
-            return desconocido;
-        return { maxBriefChars: parseMaxBriefChars(await res.json()) };
+            return { alcanzable: true, maxBriefChars: null };
+        try {
+            return { alcanzable: true, maxBriefChars: parseMaxBriefChars(await res.json()) };
+        }
+        catch {
+            return { alcanzable: true, maxBriefChars: null };
+        }
     }
     catch {
-        // Un agente sin tarjeta, o que tarda, no impide contratarlo: solo deja el
-        // límite sin comprobar. Fallar aquí seria peor que el problema.
-        return desconocido;
+        return { alcanzable: false, maxBriefChars: null };
     }
     finally {
         clearTimeout(timer);

package/dist/server.js

@@ -405,7 +405,16 @@ const WRITE_TOOLS = [
             // tarea. Aquí no cuesta nada y evita dejar dinero atrapado hasta que
             // vence el plazo.
             if (agent.metadata.botUrl) {
-                const { maxBriefChars } = await fetchAgentLimits(agent.metadata.botUrl);
+                const { alcanzable, maxBriefChars } = await fetchAgentLimits(agent.metadata.botUrl);
+                // Que el endpoint no conteste descalifica el encargo entero: el brief se
+                // entrega DESPUÉS de crear la tarea, así que contratar ahora dejaría el
+                // pago bloqueado en una tarea que nadie puede empezar. Aquí no cuesta
+                // nada y basta con reintentar cuando el agente vuelva.
+                if (alcanzable === false) {
+                    return (`${agent.metadata.name || address} publishes ${agent.metadata.botUrl} but nothing answers there, ` +
+                        `so the job could not be delivered even after paying. Nothing was quoted and nothing was spent. ` +
+                        `Try again when the agent is back up.`);
+                }
                 if (maxBriefChars !== null && brief.length > maxBriefChars) {
                     return (`That job does not fit: ${agent.metadata.name || address} accepts ${maxBriefChars} characters ` +
                         `and this brief is ${brief.length}. Nothing was quoted and nothing was spent. ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panal-mcp",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Servidor MCP de Panal: busca y contrata agentes de IA on-chain desde Claude",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@panal/sdk": "^0.10.0",
+    "@panal/sdk": "^0.11.0",
     "viem": "^2.21.0"
   },
   "devDependencies": {