panal-mcp 0.1.3 → 0.3.0

package/dist/fetch-result.d.ts

@@ -12,6 +12,21 @@
  */
 /** El mensaje que firma el cliente. Debe coincidir con el bot y el frontend. */
 export declare function resultSignMessage(taskId: bigint): string;
+/** El mensaje que firma el cliente para MANDAR el encargo. Mismo pacto. */
+export declare function briefSignMessage(taskId: bigint): string;
+/**
+ * Le entrega el encargo al agente: POST /brief/<taskId>, firmado.
+ *
+ * Existe porque contratar sin esto deja la tarea a medias. On-chain solo queda
+ * el hash del encargo; el texto tiene que llegarle al agente por su endpoint o
+ * el agente se queda mirando una tarea pagada sin saber qué se le pide. Antes
+ * el MCP contrataba y le decía al usuario "ahora hazle llegar el texto tú",
+ * que en una conversación con un modelo no lo hace nadie.
+ *
+ * Devuelve null si fue bien, o el motivo si no. No lanza: cuando esto falla el
+ * pago YA está bloqueado, así que lo útil es contarlo, no romper.
+ */
+export declare function pushBrief(botUrl: string, taskId: bigint, brief: string, client: string, signature: string): Promise<string | null>;
 /**
  * Rechaza una URL que apunte a algo que no sea internet pública.
  *

package/dist/fetch-result.js

@@ -19,6 +19,59 @@ const TIMEOUT_MS = 20_000;
 export function resultSignMessage(taskId) {
     return `Panal resultado #${taskId.toString()}`;
 }
+/** El mensaje que firma el cliente para MANDAR el encargo. Mismo pacto. */
+export function briefSignMessage(taskId) {
+    return `Panal brief #${taskId.toString()}`;
+}
+/**
+ * Le entrega el encargo al agente: POST /brief/<taskId>, firmado.
+ *
+ * Existe porque contratar sin esto deja la tarea a medias. On-chain solo queda
+ * el hash del encargo; el texto tiene que llegarle al agente por su endpoint o
+ * el agente se queda mirando una tarea pagada sin saber qué se le pide. Antes
+ * el MCP contrataba y le decía al usuario "ahora hazle llegar el texto tú",
+ * que en una conversación con un modelo no lo hace nadie.
+ *
+ * Devuelve null si fue bien, o el motivo si no. No lanza: cuando esto falla el
+ * pago YA está bloqueado, así que lo útil es contarlo, no romper.
+ */
+export async function pushBrief(botUrl, taskId, brief, client, signature) {
+    let url;
+    try {
+        const base = await assertPublicUrl(botUrl);
+        url = new URL(`/brief/${taskId}`, base);
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ brief, address: client, signature }),
+            signal: controller.signal,
+            redirect: 'error',
+        });
+        if (res.ok)
+            return null;
+        // El cuerpo del error dice cuál de las comprobaciones del agente falló
+        // —firma, estado, o que el texto no cuadra con el hash—, y eso es
+        // exactamente lo que hay que enseñar para poder arreglarlo.
+        const detalle = (await res.text().catch(() => '')).slice(0, 300);
+        return `the agent replied ${res.status}${detalle ? `: ${detalle}` : ''}`;
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            return `the endpoint did not answer within ${TIMEOUT_MS / 1000} s`;
+        }
+        return err instanceof Error ? err.message : String(err);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** ¿Esta IP apunta dentro de nuestra propia red? */
 function isPrivateIp(ip) {
     if (isIP(ip) === 6) {
@@ -59,24 +112,24 @@ export async function assertPublicUrl(raw) {
         url = new URL(raw);
     }
     catch {
-        throw new Error(`El endpoint del agente no es una URL válida: ${raw}`);
+        throw new Error(`The agent endpoint is not a valid URL: ${raw}`);
     }
     if (url.protocol !== 'https:') {
         // La petición lleva una firma del cliente en la query: en claro la lee cualquiera.
-        throw new Error(`El endpoint del agente tiene que ser https, y es ${url.protocol}//`);
+        throw new Error(`The agent endpoint must be https, and it is ${url.protocol}//`);
     }
     if (url.username || url.password)
-        throw new Error('El endpoint lleva credenciales embebidas: se rechaza.');
+        throw new Error('The endpoint carries embedded credentials: rejected.');
     const host = url.hostname.replace(/^\[|\]$/g, '');
     if (/^(localhost|.*\.local|.*\.internal)$/i.test(host)) {
-        throw new Error(`El endpoint apunta a un nombre local (${host}): se rechaza.`);
+        throw new Error(`The endpoint points at a local name (${host}): rejected.`);
     }
     const ips = isIP(host) ? [host] : (await lookup(host, { all: true })).map((r) => r.address);
     if (!ips.length)
-        throw new Error(`No se pudo resolver ${host}.`);
+        throw new Error(`Could not resolve ${host}.`);
     for (const ip of ips) {
         if (isPrivateIp(ip))
-            throw new Error(`El endpoint apunta a una dirección interna (${ip}): se rechaza.`);
+            throw new Error(`The endpoint points at an internal address (${ip}): rejected.`);
     }
     return url;
 }
@@ -91,11 +144,11 @@ export async function fetchResultText(botUrl, taskId, client, signature) {
     try {
         const res = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } });
         if (!res.ok) {
-            throw new Error(`El endpoint del agente respondió ${res.status}. ¿Sigue en pie y la firma es la del cliente?`);
+            throw new Error(`The agent endpoint replied ${res.status}. Is it still up, and is the signature the client's?`);
         }
         const reader = res.body?.getReader();
         if (!reader)
-            throw new Error('El endpoint del agente respondió sin cuerpo.');
+            throw new Error('The agent endpoint replied with no body.');
         const chunks = [];
         let total = 0;
         for (;;) {
@@ -105,14 +158,14 @@ export async function fetchResultText(botUrl, taskId, client, signature) {
             total += value.byteLength;
             if (total > MAX_BYTES) {
                 await reader.cancel();
-                throw new Error(`El resultado pasa de ${MAX_BYTES / 1024} KB: se corta por seguridad.`);
+                throw new Error(`The result exceeds ${MAX_BYTES / 1024} KB: cut off for safety.`);
             }
             chunks.push(value);
         }
         const body = Buffer.concat(chunks).toString('utf8');
         const parsed = JSON.parse(body);
         if (typeof parsed.resultText !== 'string')
-            throw new Error('La respuesta del agente no trae `resultText`.');
+            throw new Error('The agent response has no `resultText`.');
         return parsed.resultText;
     }
     finally {

package/dist/limits.d.ts

@@ -6,8 +6,19 @@
  * servidor, y nunca en el prompt: un prompt se puede negociar, un `if` no.
  */
 import type { Address } from 'viem';
+/**
+ * Las dos maneras de pagar a un agente, y no son intercambiables.
+ *
+ * `hire` bloquea el pago en el escrow y abre una tarea con plazo, entrega y
+ * disputa. `ask` paga una consulta suelta por x402 y se resuelve en la misma
+ * llamada HTTP. Los precios son distintos —Spec cobra 100 $PANAL por tarea y
+ * 0,5 por consulta—, así que canjear un presupuesto por el camino que no es
+ * cobraría doscientas veces de más.
+ */
+export type QuoteKind = 'hire' | 'ask';
 export interface Quote {
     id: string;
+    kind: QuoteKind;
     worker: Address;
     agentName: string;
     brief: string;
@@ -26,8 +37,14 @@ export interface Quote {
 export declare class QuoteBook {
     private readonly quotes;
     issue(data: Omit<Quote, 'id' | 'expiresAt'>): Quote;
-    /** Devuelve el presupuesto, o el motivo por el que no vale. */
-    redeem(id: string): {
+    /**
+     * Devuelve el presupuesto, o el motivo por el que no vale.
+     *
+     * `kind` no es decorativo: obliga a canjear cada presupuesto por el camino
+     * para el que se pidió. Sin esto, el id de una consulta de 0,5 $PANAL se
+     * podría canjear como contratación y bloquear los 100 $PANAL de la tarea.
+     */
+    redeem(id: string, kind: QuoteKind): {
         quote: Quote;
     } | {
         error: string;

package/dist/limits.js

@@ -24,14 +24,26 @@ export class QuoteBook {
         this.quotes.set(quote.id, quote);
         return quote;
     }
-    /** Devuelve el presupuesto, o el motivo por el que no vale. */
-    redeem(id) {
+    /**
+     * Devuelve el presupuesto, o el motivo por el que no vale.
+     *
+     * `kind` no es decorativo: obliga a canjear cada presupuesto por el camino
+     * para el que se pidió. Sin esto, el id de una consulta de 0,5 $PANAL se
+     * podría canjear como contratación y bloquear los 100 $PANAL de la tarea.
+     */
+    redeem(id, kind) {
         this.prune();
         const quote = this.quotes.get(id);
         if (!quote) {
             return {
-                error: 'Ese presupuesto no existe o ya caducó (duran 5 minutos). ' +
-                    'Pide uno nuevo con panal_quote_hire y enséñaselo a la persona antes de contratar.',
+                error: 'That quote does not exist or has expired (they last 5 minutes). ' +
+                    'Ask for a new one and show it to the person before spending.',
+            };
+        }
+        if (quote.kind !== kind) {
+            return {
+                error: `That quote_id is for ${quote.kind === 'ask' ? 'a per-call question (panal_ask)' : 'hiring a job (panal_hire)'}, ` +
+                    `not for this. The two have different prices; ask for the right quote instead of reusing this id.`,
             };
         }
         // De un solo uso: sin esto, un reintento del modelo contrataría dos veces.

package/dist/server.js

@@ -22,14 +22,30 @@
  * RESERVADO para los mensajes del protocolo —un `console.log` suelto ahí
  * corrompe la sesión entera—, así que todo el registro va por stderr.
  */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
 import { formatEther, isAddress, keccak256, parseEther, toBytes } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { NATIVE_CURRENCY, TaskStatus, createPanalClient, } from '@panal/sdk';
 import { QuoteBook, SpendLedger, limitsFromEnv } from './limits.js';
-import { fetchResultText, resultSignMessage } from './fetch-result.js';
+import { briefSignMessage, fetchResultText, pushBrief, resultSignMessage } from './fetch-result.js';
 const SERVER_NAME = 'panal';
-const SERVER_VERSION = '0.1.0';
+/**
+ * Sale del package.json, no de una constante a mano: la copiada se quedó en
+ * 0.1.0 mientras el paquete iba por 0.1.3, y un servidor que se anuncia con
+ * una versión falsa hace imposible saber qué está corriendo el usuario.
+ */
+const SERVER_VERSION = (() => {
+    try {
+        const aqui = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(resolve(aqui, '..', 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
 /** Versiones del protocolo que sabemos hablar; la primera es la preferida. */
 const SUPPORTED_PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 const EXPLORER = 'https://monadvision.com';
@@ -61,12 +77,11 @@ const panal = createPanalClient({
 /** Motivo por el que no se puede escribir, o null si sí se puede. */
 function writesBlockedReason() {
     if (!writesRequested) {
-        return ('Este servidor está en SOLO LECTURA. Para contratar hay que arrancarlo con ' +
-            'MCP_ENABLE_WRITES=true y una MCP_PRIVATE_KEY con fondos. Dile a la persona que lo configure ella: ' +
-            'no intentes rodearlo.');
+        return ('This server is READ-ONLY. To hire, it must be started with MCP_ENABLE_WRITES=true and an ' +
+            'MCP_PRIVATE_KEY with funds. Tell the person to configure it themselves: do not try to work around it.');
     }
     if (!account) {
-        return 'MCP_ENABLE_WRITES está activo pero no hay una MCP_PRIVATE_KEY válida, así que no hay wallet con la que pagar.';
+        return 'MCP_ENABLE_WRITES is on but there is no valid MCP_PRIVATE_KEY, so there is no wallet to pay with.';
     }
     return null;
 }
@@ -78,15 +93,18 @@ function symbolOf(currency) {
 }
 function renderAgent(agent) {
     const price = `${formatEther(agent.pricePerTask)} ${symbolOf(agent.currency)}`;
-    const skills = agent.metadata.skills.length ? agent.metadata.skills.join(', ') : '(sin skills declaradas)';
+    const skills = agent.metadata.skills.length ? agent.metadata.skills.join(', ') : '(no skills declared)';
     return [
-        `${agent.metadata.name || '(sin nombre)'} — ${agent.address}`,
-        `  Estado: ${agent.active ? 'activo' : 'DADO DE BAJA (no acepta encargos)'}`,
-        `  Precio: ${price} por tarea`,
+        `${agent.metadata.name || '(no name)'} — ${agent.address}`,
+        `  Status: ${agent.active ? 'active' : 'DELISTED (does not take jobs)'}`,
+        // "Per task" y no "Price" a secas: hay dos precios (tarea por escrow y
+        // consulta por x402) y llamar "el precio" a uno de ellos fue justo lo que
+        // hizo invisible al otro.
+        `  Per task: ${price} (escrow, with deadline and dispute window)`,
         `  Skills: ${skills}`,
-        agent.metadata.description ? `  Descripción: ${agent.metadata.description}` : null,
+        agent.metadata.description ? `  Description: ${agent.metadata.description}` : null,
         agent.metadata.botUrl ? `  Endpoint: ${agent.metadata.botUrl}` : null,
-        `  Ficha: ${EXPLORER}/address/${agent.address}`,
+        `  Profile: ${EXPLORER}/address/${agent.address}`,
     ]
         .filter(Boolean)
         .join('\n');
@@ -94,13 +112,13 @@ function renderAgent(agent) {
 function renderTask(task) {
     const deadline = new Date(Number(task.deadline) * 1000).toISOString();
     return [
-        `Tarea #${task.id} — ${TaskStatus[task.status] ?? task.status}`,
-        `  Cliente: ${task.client}`,
-        `  Agente:  ${task.worker}`,
-        `  Importe: ${formatEther(task.amount)} ${symbolOf(task.currency)}`,
-        `  Plazo:   ${deadline}`,
-        `  Hash del encargo: ${task.taskHash}`,
-        task.resultHash && !/^0x0+$/.test(task.resultHash) ? `  Hash del resultado: ${task.resultHash}` : null,
+        `Task #${task.id} — ${TaskStatus[task.status] ?? task.status}`,
+        `  Client: ${task.client}`,
+        `  Agent:   ${task.worker}`,
+        `  Amount:  ${formatEther(task.amount)} ${symbolOf(task.currency)}`,
+        `  Deadline: ${deadline}`,
+        `  Job hash: ${task.taskHash}`,
+        task.resultHash && !/^0x0+$/.test(task.resultHash) ? `  Result hash: ${task.resultHash}` : null,
     ]
         .filter(Boolean)
         .join('\n');
@@ -109,13 +127,13 @@ const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
 const READ_TOOLS = [
     {
         name: 'panal_search_agents',
-        description: 'Busca agentes de IA en el marketplace Panal (Monad mainnet) por texto libre sobre su nombre, ' +
-            'descripción y skills. Sin búsqueda devuelve todos los activos. Datos leídos de la cadena en vivo.',
+        description: 'Search AI agents on the Panal marketplace (Monad mainnet) by free text over their name, ' +
+            'description and skills. With no query it returns every active agent. Read live from the chain.',
         inputSchema: {
             type: 'object',
             properties: {
-                query: { type: 'string', description: 'Qué buscas, p. ej. "traducción" o "resúmenes legales".' },
-                include_inactive: { type: 'boolean', description: 'Incluir agentes dados de baja. Por defecto no.' },
+                query: { type: 'string', description: 'What you are looking for, e.g. "translation" or "legal summaries".' },
+                include_inactive: { type: 'boolean', description: 'Include delisted agents. Off by default.' },
             },
         },
         handler: async (args) => {
@@ -124,60 +142,139 @@ const READ_TOOLS = [
             });
             if (!found.length) {
                 return str(args.query)
-                    ? `Ningún agente activo encaja con "${str(args.query)}". Prueba con un término más general o mira todos sin búsqueda.`
-                    : 'Ahora mismo no hay agentes activos en el marketplace.';
+                    ? `No active agent matches "${str(args.query)}". Try a broader term, or list them all with no query.`
+                    : 'There are no active agents on the marketplace right now.';
             }
-            return `${found.length} agente(s):\n\n${found.map(renderAgent).join('\n\n')}`;
+            return `${found.length} agent(s):\n\n${found.map(renderAgent).join('\n\n')}`;
         },
     },
     {
         name: 'panal_get_agent',
-        description: 'Ficha completa de un agente de Panal por su dirección.',
+        description: 'Full profile of a Panal agent, by address.',
         inputSchema: {
             type: 'object',
-            properties: { address: { type: 'string', description: 'Dirección 0x… del agente.' } },
+            properties: { address: { type: 'string', description: 'The agent 0x… address.' } },
             required: ['address'],
         },
         handler: async (args) => {
             const address = str(args.address);
             if (!address || !isAddress(address))
-                return 'Necesito una dirección 0x válida.';
-            return renderAgent(await panal.getAgent(address));
+                return 'I need a valid 0x address.';
+            const agent = await panal.getAgent(address);
+            // El perfil es donde alguien mira el precio, así que aquí sí se paga la
+            // llamada al manifiesto del agente: enseñar solo el de tarea era la
+            // razón de que el precio por consulta fuese invisible desde aquí. En
+            // `panal_search_agents` no se hace, porque serían N llamadas HTTP a
+            // servidores ajenos por cada búsqueda.
+            let porLlamada;
+            try {
+                const q = await panal.quoteAgent(address, 'Price check.');
+                porLlamada = `  Per question: ${formatEther(BigInt(q.amount))} ${q.assetSymbol ?? symbolOf(q.asset)} (x402, answered on the spot)`;
+            }
+            catch {
+                porLlamada = '  Per question: not offered (this agent only takes jobs through escrow)';
+            }
+            return `${renderAgent(agent)}\n${porLlamada}`;
         },
     },
     {
         name: 'panal_get_task',
-        description: 'Estado de un encargo en el escrow de Panal: importe, plazo, agente y si ya se entregó.',
+        description: 'State of a job in the Panal escrow: amount, deadline, agent, and whether it was delivered.',
         inputSchema: {
             type: 'object',
-            properties: { task_id: { type: 'number', description: 'Id numérico de la tarea.' } },
+            properties: { task_id: { type: 'number', description: 'Numeric task id.' } },
             required: ['task_id'],
         },
         handler: async (args) => {
             const id = Number(args.task_id);
             if (!Number.isInteger(id) || id < 0)
-                return 'El id de la tarea es un entero mayor o igual que cero.';
+                return 'The task id is an integer greater than or equal to zero.';
             const count = await panal.getTaskCount();
             if (BigInt(id) >= count)
-                return `La tarea #${id} no existe: ahora mismo hay ${count}.`;
+                return `Task #${id} does not exist: there are ${count} so far.`;
             return renderTask(await panal.getTask(BigInt(id)));
         },
     },
+    {
+        name: 'panal_quote_ask',
+        description: 'Ask an agent what it charges for ONE question, answered on the spot (x402 per-call pricing). ' +
+            'Costs nothing and needs no wallet. This is a DIFFERENT price from the per-task price in the ' +
+            'agent profile: per-task means hiring a job through escrow, with a deadline and a dispute window. ' +
+            'The two can differ by a lot, so quote the one you actually mean to use.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agent: { type: 'string', description: 'The agent 0x… address.' },
+                prompt: { type: 'string', description: 'The question, so the agent can price it if it prices per question.' },
+            },
+            required: ['agent', 'prompt'],
+        },
+        handler: async (args) => {
+            const address = str(args.agent);
+            const prompt = str(args.prompt);
+            if (!address || !isAddress(address))
+                return 'I need a valid 0x address for the agent.';
+            if (!prompt)
+                return 'I need the question.';
+            const agent = await panal.getAgent(address);
+            const name = agent.metadata.name || address;
+            let quote;
+            try {
+                quote = await panal.quoteAgent(address, prompt);
+            }
+            catch (err) {
+                // Cobrar por llamada es opcional: un agente puede trabajar solo por
+                // escrow. Se dice cuál es la alternativa en vez de dejarlo en error.
+                const msg = err instanceof Error ? err.message : String(err);
+                return (`${name} does not answer per-question requests (${msg}).\n` +
+                    `It can still be hired for a job: ${formatEther(agent.pricePerTask)} ${symbolOf(agent.currency)} ` +
+                    `per task, via panal_quote_hire.`);
+            }
+            const amount = BigInt(quote.amount);
+            const symbol = quote.assetSymbol ?? symbolOf(quote.asset);
+            const saved = quotes.issue({
+                kind: 'ask',
+                worker: agent.address,
+                agentName: name,
+                brief: prompt,
+                amount,
+                currency: quote.asset,
+                symbol,
+                botUrl: agent.metadata.botUrl,
+            });
+            return [
+                `${name} charges per question:`,
+                `  Price: ${formatEther(amount)} ${symbol} for this one question`,
+                `  Paid to: ${quote.payTo}`,
+                quote.description ? `  Covers: ${quote.description}` : null,
+                '',
+                `For comparison, hiring it for a job costs ${formatEther(agent.pricePerTask)} ${symbolOf(agent.currency)} ` +
+                    'per task (escrow, with deadline and dispute window).',
+                '',
+                `quote_id: ${saved.id}  (valid for 5 minutes)`,
+                '',
+                'Show this price to the person. Only if they say yes, call panal_ask with that quote_id and ' +
+                    'confirmed_by_user: true. This moves real money.',
+            ]
+                .filter((l) => l !== null)
+                .join('\n');
+        },
+    },
     {
         name: 'panal_marketplace_stats',
-        description: 'Cifras del marketplace Panal: cuántos agentes hay, cuántos activos y cuántos encargos van.',
+        description: 'Panal marketplace figures: how many agents exist, how many are active, how many jobs so far.',
         inputSchema: { type: 'object', properties: {} },
         handler: async () => {
             const [agents, taskCount] = await Promise.all([panal.listAgents(), panal.getTaskCount()]);
             const active = agents.filter((a) => a.active);
             return [
-                `Agentes registrados: ${agents.length}`,
-                `Agentes activos: ${active.length}`,
-                `Encargos creados: ${taskCount}`,
+                `Registered agents: ${agents.length}`,
+                `Active agents: ${active.length}`,
+                `Jobs created: ${taskCount}`,
                 `Escrow: ${panal.addresses.escrow}`,
                 `Registry: ${panal.addresses.registry}`,
                 '',
-                active.length ? `Activos ahora:\n${active.map(renderAgent).join('\n\n')}` : 'No hay agentes activos.',
+                active.length ? `Active now:\n${active.map(renderAgent).join('\n\n')}` : 'No active agents.',
             ].join('\n');
         },
     },
@@ -185,8 +282,8 @@ const READ_TOOLS = [
 const WRITE_TOOLS = [
     {
         name: 'panal_wallet',
-        description: 'Estado de la wallet con la que este servidor pagaría: dirección, saldo y cuánto queda del ' +
-            'presupuesto de hoy. Úsala antes de contratar para saber si hay fondos.',
+        description: 'State of the wallet this server would pay with: address, balance, and how much of today\'s budget ' +
+            'is left. Call it before hiring to know whether there are funds.',
         inputSchema: { type: 'object', properties: {} },
         handler: async () => {
             const blocked = writesBlockedReason();
@@ -197,21 +294,21 @@ const WRITE_TOOLS = [
             const left = limits.dailyBudgetWei > spent ? limits.dailyBudgetWei - spent : 0n;
             return [
                 `Wallet: ${address}`,
-                `Saldo: ${formatEther(balance)} MON`,
-                `Tope por encargo: ${formatEther(limits.maxPerTaskWei)}`,
-                `Presupuesto de hoy: gastado ${formatEther(spent)} de ${formatEther(limits.dailyBudgetWei)} · queda ${formatEther(left)}`,
+                `Balance: ${formatEther(balance)} MON`,
+                `Per-job cap: ${formatEther(limits.maxPerTaskWei)}`,
+                `Today's budget: spent ${formatEther(spent)} of ${formatEther(limits.dailyBudgetWei)} · ${formatEther(left)} left`,
             ].join('\n');
         },
     },
     {
         name: 'panal_quote_hire',
-        description: 'Presupuesta un encargo SIN pagar nada. Devuelve el precio real del agente y un quote_id. ' +
-            'Enseña siempre el precio a la persona y espera su visto bueno antes de llamar a panal_hire.',
+        description: 'Quote a job WITHOUT paying anything. Returns the agent real price and a quote_id. ' +
+            'Always show the price to the person and wait for their approval before calling panal_hire.',
         inputSchema: {
             type: 'object',
             properties: {
-                agent: { type: 'string', description: 'Dirección 0x… del agente.' },
-                brief: { type: 'string', description: 'El encargo, redactado con todo el detalle necesario.' },
+                agent: { type: 'string', description: 'The agent 0x… address.' },
+                brief: { type: 'string', description: 'The job, written with all the detail the agent will need.' },
             },
             required: ['agent', 'brief'],
         },
@@ -222,24 +319,25 @@ const WRITE_TOOLS = [
             const address = str(args.agent);
             const brief = str(args.brief);
             if (!address || !isAddress(address))
-                return 'Necesito una dirección 0x válida del agente.';
+                return 'I need a valid 0x address for the agent.';
             if (!brief)
-                return 'Necesito el texto del encargo.';
+                return 'I need the text of the job.';
             const agent = await panal.getAgent(address);
             if (!agent.active)
-                return `${agent.metadata.name || address} está dado de baja y no acepta encargos.`;
+                return `${agent.metadata.name || address} is delisted and does not take jobs.`;
             const amount = agent.pricePerTask;
             const symbol = symbolOf(agent.currency);
             if (amount > limits.maxPerTaskWei) {
-                return (`Ese agente cobra ${formatEther(amount)} ${symbol} y el tope por encargo de este servidor es ` +
-                    `${formatEther(limits.maxPerTaskWei)}. No se puede contratar sin que la persona suba MCP_MAX_PER_TASK_WEI.`);
+                return (`That agent charges ${formatEther(amount)} ${symbol} and this server per-job cap is ` +
+                    `${formatEther(limits.maxPerTaskWei)}. It cannot be hired unless the person raises MCP_MAX_PER_TASK_WEI.`);
             }
             const spent = ledger.spentToday();
             if (spent + amount > limits.dailyBudgetWei) {
-                return (`Se pasaría del presupuesto de hoy: llevas ${formatEther(spent)} de ${formatEther(limits.dailyBudgetWei)} ` +
-                    `y esto cuesta ${formatEther(amount)} ${symbol}.`);
+                return (`That would blow today's budget: ${formatEther(spent)} of ${formatEther(limits.dailyBudgetWei)} spent ` +
+                    `and this costs ${formatEther(amount)} ${symbol}.`);
             }
             const quote = quotes.issue({
+                kind: 'hire',
                 worker: agent.address,
                 agentName: agent.metadata.name || agent.address,
                 brief,
@@ -249,29 +347,95 @@ const WRITE_TOOLS = [
                 botUrl: agent.metadata.botUrl,
             });
             return [
-                `Presupuesto para ${quote.agentName}:`,
-                `  Precio: ${formatEther(amount)} ${symbol}`,
-                `  Plazo: ${limits.deadlineHours} h desde que se contrate`,
-                `  Encargo: ${brief.length > 200 ? `${brief.slice(0, 200)}…` : brief}`,
+                `Quote for ${quote.agentName}:`,
+                `  Price: ${formatEther(amount)} ${symbol}`,
+                `  Deadline: ${limits.deadlineHours} h from the moment it is hired`,
+                `  Job: ${brief.length > 200 ? `${brief.slice(0, 200)}…` : brief}`,
                 '',
-                `quote_id: ${quote.id}  (vale 5 minutos)`,
+                `quote_id: ${quote.id}  (valid for 5 minutes)`,
                 '',
-                'Enséñale este precio a la persona. Solo si dice que sí, llama a panal_hire con ese quote_id ' +
-                    'y confirmed_by_user: true. Esto mueve dinero real.',
+                'Show this price to the person. Only if they say yes, call panal_hire with that quote_id ' +
+                    'and confirmed_by_user: true. This moves real money.',
             ].join('\n');
         },
     },
+    {
+        name: 'panal_ask',
+        description: 'Pay an agent for ONE question and get its answer in the same call (x402). Requires a quote_id from ' +
+            'panal_quote_ask and an explicit yes from the person. This spends real money. Unlike panal_hire ' +
+            'there is no escrow, no deadline and no dispute: once paid, it is paid.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                quote_id: { type: 'string', description: 'The id returned by panal_quote_ask.' },
+                confirmed_by_user: {
+                    type: 'boolean',
+                    description: 'true only if the person has seen the price and approved it.',
+                },
+            },
+            required: ['quote_id', 'confirmed_by_user'],
+        },
+        handler: async (args) => {
+            const blocked = writesBlockedReason();
+            if (blocked)
+                return blocked;
+            if (args.confirmed_by_user !== true) {
+                return 'I will not pay without confirmed_by_user: true. Show the quote to the person and ask first.';
+            }
+            const id = str(args.quote_id);
+            if (!id)
+                return 'The quote_id is missing. Ask for a quote with panal_quote_ask first.';
+            const redeemed = quotes.redeem(id, 'ask');
+            if ('error' in redeemed)
+                return redeemed.error;
+            const quote = redeemed.quote;
+            // Los mismos topes que contratar. Una consulta es barata, pero nada
+            // impide encadenar mil: el presupuesto del día es lo que lo impide.
+            if (quote.amount > limits.maxPerTaskWei) {
+                return (`That question costs ${formatEther(quote.amount)} ${quote.symbol} and this server per-item cap is ` +
+                    `${formatEther(limits.maxPerTaskWei)}. Raise MCP_MAX_PER_TASK_WEI if that is intended.`);
+            }
+            const spent = ledger.spentToday();
+            if (spent + quote.amount > limits.dailyBudgetWei) {
+                return (`That would blow today's budget: ${formatEther(spent)} of ${formatEther(limits.dailyBudgetWei)} spent ` +
+                    `and this costs ${formatEther(quote.amount)} ${quote.symbol}.`);
+            }
+            try {
+                // `maxSpend` va atado al importe del presupuesto que la persona
+                // aprobó, no al tope del servidor: si el agente sube el precio entre
+                // el presupuesto y el sí, la firma no se produce.
+                const res = await panal.askAgent(quote.worker, quote.brief, { maxSpend: quote.amount });
+                // Se registra lo REALMENTE pagado, que es lo que devuelve el SDK.
+                ledger.record(res.paid);
+                log(`consulta pagada a ${quote.worker}: ${formatEther(res.paid)} ${quote.symbol}`);
+                return [
+                    `Paid ${formatEther(res.paid)} ${quote.symbol} to ${quote.agentName}.`,
+                    res.txHash ? `  tx: ${EXPLORER}/tx/${res.txHash}` : null,
+                    '',
+                    'Answer:',
+                    res.answer,
+                ]
+                    .filter((l) => l !== null)
+                    .join('\n');
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log(`fallo al pagar la consulta: ${msg}`);
+                return `Could not pay for the question: ${msg}`;
+            }
+        },
+    },
     {
         name: 'panal_hire',
-        description: 'Contrata al agente y BLOQUEA EL PAGO REAL en el escrow. Exige un quote_id de panal_quote_hire y ' +
-            'que la persona haya dicho que sí de forma explícita. No lo llames por iniciativa propia.',
+        description: 'Hire the agent and LOCK THE REAL PAYMENT in escrow. Requires a quote_id from panal_quote_hire and ' +
+            'an explicit yes from the person. Never call it on your own initiative.',
         inputSchema: {
             type: 'object',
             properties: {
-                quote_id: { type: 'string', description: 'El id devuelto por panal_quote_hire.' },
+                quote_id: { type: 'string', description: 'The id returned by panal_quote_hire.' },
                 confirmed_by_user: {
                     type: 'boolean',
-                    description: 'true solo si la persona ha visto el precio y ha dado su visto bueno.',
+                    description: 'true only if the person has seen the price and approved it.',
                 },
             },
             required: ['quote_id', 'confirmed_by_user'],
@@ -281,12 +445,12 @@ const WRITE_TOOLS = [
             if (blocked)
                 return blocked;
             if (args.confirmed_by_user !== true) {
-                return 'No contrato sin confirmed_by_user: true. Enséñale el presupuesto a la persona y pregúntale primero.';
+                return 'I will not hire without confirmed_by_user: true. Show the quote to the person and ask first.';
             }
             const id = str(args.quote_id);
             if (!id)
-                return 'Falta el quote_id. Pide antes un presupuesto con panal_quote_hire.';
-            const redeemed = quotes.redeem(id);
+                return 'The quote_id is missing. Ask for a quote with panal_quote_hire first.';
+            const redeemed = quotes.redeem(id, 'hire');
             if ('error' in redeemed)
                 return redeemed.error;
             const quote = redeemed.quote;
@@ -294,63 +458,83 @@ const WRITE_TOOLS = [
             // pueden haber pasado minutos y otros encargos.
             const spent = ledger.spentToday();
             if (spent + quote.amount > limits.dailyBudgetWei) {
-                return `Mientras tanto se agotó el presupuesto de hoy (${formatEther(spent)} de ${formatEther(limits.dailyBudgetWei)}).`;
+                return `Today's budget ran out in the meantime (${formatEther(spent)} of ${formatEther(limits.dailyBudgetWei)}).`;
             }
             const deadline = BigInt(Math.floor(Date.now() / 1000) + limits.deadlineHours * 3600);
             try {
                 const result = await panal.hire({ agent: quote.worker, brief: quote.brief, deadline });
                 ledger.record(result.amount);
                 log(`contratada #${result.taskId} a ${quote.worker} por ${formatEther(result.amount)} ${quote.symbol}`);
+                // Contratar sin entregar el encargo deja la tarea a medias: el pago
+                // bloqueado y el agente esperando un texto que nadie le manda. Se hace
+                // aquí, no se le pide al usuario, porque quien está leyendo esto es un
+                // modelo en mitad de una conversación y no va a abrir una terminal.
+                let entregaBrief;
+                if (!quote.botUrl) {
+                    entregaBrief = 'That agent publishes no endpoint: get the job to them through whatever channel you use.';
+                }
+                else {
+                    const firma = await account.signMessage({ message: briefSignMessage(result.taskId) });
+                    const fallo = await pushBrief(quote.botUrl, result.taskId, quote.brief, account.address, firma);
+                    if (fallo === null) {
+                        entregaBrief = `Job delivered to ${quote.botUrl}: the agent is already working on it.`;
+                        log(`brief #${result.taskId} entregado en ${quote.botUrl}`);
+                    }
+                    else {
+                        entregaBrief =
+                            `WARNING: the payment is locked but the job did NOT arrive (${fallo}).\n` +
+                                `The agent cannot start. Retry with panal_send_brief ${result.taskId}, ` +
+                                `or the payment returns on its own when the deadline passes.`;
+                        log(`brief #${result.taskId} NO entregado: ${fallo}`);
+                    }
+                }
                 return [
-                    `Contratado. Tarea #${result.taskId} creada y pago bloqueado en el escrow.`,
-                    `  Agente: ${quote.agentName}`,
-                    `  Importe: ${formatEther(result.amount)} ${quote.symbol}`,
+                    `Hired. Task #${result.taskId} created and payment locked in escrow.`,
+                    `  Agent: ${quote.agentName}`,
+                    `  Amount: ${formatEther(result.amount)} ${quote.symbol}`,
                     `  tx: ${EXPLORER}/tx/${result.txHash}`,
                     '',
-                    quote.botUrl
-                        ? `El agente publica endpoint (${quote.botUrl}): el resultado se podrá descargar de ahí.`
-                        : 'Ese agente no publica endpoint: pídele el resultado por el canal que uses con él.',
+                    entregaBrief,
                     '',
-                    'IMPORTANTE: el encargo NO viaja on-chain, solo su hash. Hazle llegar el texto al agente.',
-                    `Cuando entregue, revisa con panal_get_task ${result.taskId} y aprueba con panal_approve_task.`,
+                    `When it delivers, check with panal_get_task ${result.taskId} and approve with panal_approve_task.`,
                 ].join('\n');
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
                 log(`fallo al contratar: ${msg}`);
-                return `No se pudo contratar: ${msg}`;
+                return `Could not hire: ${msg}`;
             }
         },
     },
     {
         name: 'panal_get_result',
-        description: 'Recoge el resultado de una tarea ya entregada. El texto vive fuera de la cadena: se le pide al ' +
-            'endpoint del agente firmando como cliente, y se comprueba que su hash coincide con el anclado ' +
-            'on-chain. Solo funciona para tareas que contrató la wallet de este servidor.',
+        description: 'Collect the result of a delivered task. The text lives off-chain: it is requested from the agent ' +
+            'endpoint by signing as the client, and its hash is checked against the one anchored on-chain. ' +
+            'Only works for tasks hired by this server wallet.',
         inputSchema: {
             type: 'object',
-            properties: { task_id: { type: 'number', description: 'Id de la tarea entregada.' } },
+            properties: { task_id: { type: 'number', description: 'Id of the delivered task.' } },
             required: ['task_id'],
         },
         handler: async (args) => {
             if (!account)
-                return 'Sin MCP_PRIVATE_KEY no se puede firmar la petición del resultado.';
+                return 'Without MCP_PRIVATE_KEY the request for the result cannot be signed.';
             const id = Number(args.task_id);
             if (!Number.isInteger(id) || id < 0)
                 return 'El id de la tarea es un entero mayor o igual que cero.';
             const taskId = BigInt(id);
             const task = await panal.getTask(taskId);
             if (task.client.toLowerCase() !== account.address.toLowerCase()) {
-                return `La tarea #${id} la contrató ${task.client}, no esta wallet. Solo el cliente puede recoger el resultado.`;
+                return `Task #${id} was hired by ${task.client}, not this wallet. Only the client can collect the result.`;
             }
             if (/^0x0+$/.test(task.resultHash)) {
-                return `La tarea #${id} todavía no tiene resultado entregado (estado: ${TaskStatus[task.status] ?? task.status}).`;
+                return `Task #${id} has no delivered result yet (status: ${TaskStatus[task.status] ?? task.status}).`;
             }
             const agent = await panal.getAgent(task.worker);
             if (!agent.metadata.botUrl) {
-                return (`El agente ${agent.metadata.name || task.worker} no publica endpoint, así que el resultado no se puede ` +
-                    `descargar por aquí. En la cadena consta su hash (${task.resultHash}): pídeselo por vuestro canal y ` +
-                    'comprueba que el hash coincide.');
+                return (`Agent ${agent.metadata.name || task.worker} publishes no endpoint, so the result cannot be downloaded ` +
+                    `here. Its hash is on-chain (${task.resultHash}): ask them through your channel and check that the ` +
+                    'hash matches.');
             }
             try {
                 const signature = await account.signMessage({ message: resultSignMessage(taskId) });
@@ -360,28 +544,80 @@ const WRITE_TOOLS = [
                 // on-chain y enseñarte otra distinta.
                 const actual = keccak256(toBytes(text));
                 if (actual.toLowerCase() !== task.resultHash.toLowerCase()) {
-                    return (`⚠️ El resultado que devuelve el agente NO coincide con el anclado on-chain.\n` +
-                        `  esperado: ${task.resultHash}\n  recibido: ${actual}\n\n` +
-                        'No lo apruebes: o el agente cambió el texto después de entregar, o alguien alteró la respuesta. ' +
-                        'Puedes abrir una disputa desde https://panal.lat/dashboard.');
+                    return (`⚠️ The result the agent serves does NOT match the one anchored on-chain.\n` +
+                        `  expected: ${task.resultHash}\n  received: ${actual}\n\n` +
+                        'Do not approve it: either the agent changed the text after delivering, or someone altered the ' +
+                        'response. You can open a dispute at https://panal.lat/dashboard.');
                 }
-                return `Resultado de la tarea #${id} (hash verificado contra la cadena):\n\n${text}`;
+                return `Result of task #${id} (hash verified against the chain):\n\n${text}`;
             }
             catch (err) {
-                return `No se pudo recoger el resultado: ${err instanceof Error ? err.message : err}`;
+                return `Could not collect the result: ${err instanceof Error ? err.message : err}`;
+            }
+        },
+    },
+    {
+        name: 'panal_send_brief',
+        description: 'Deliver the job again to an already-hired agent, when the automatic send from panal_hire did not ' +
+            'arrive. It costs NO money: the payment is already locked, this only repeats the HTTP delivery. ' +
+            'The text must be EXACTLY the one hired, because its hash is on the chain.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task_id: { type: 'number', description: 'Id of the already-created task.' },
+                brief: { type: 'string', description: 'The job, word for word as it was when hired.' },
+            },
+            required: ['task_id', 'brief'],
+        },
+        handler: async (args) => {
+            const blocked = writesBlockedReason();
+            if (blocked)
+                return blocked;
+            const id = Number(args.task_id);
+            if (!Number.isInteger(id) || id < 0)
+                return 'I need a valid task id.';
+            const brief = str(args.brief);
+            if (!brief)
+                return 'I need the text of the job.';
+            const task = await panal.getTask(BigInt(id));
+            if (task.client.toLowerCase() !== account.address.toLowerCase()) {
+                return `Task #${id} was not hired by this wallet, so its signature is not valid for delivering the job.`;
+            }
+            if (task.status !== TaskStatus.Open) {
+                return `Task #${id} is ${TaskStatus[task.status]}: it no longer accepts the job.`;
+            }
+            // Se comprueba aquí antes de molestar al agente: así el error dice que el
+            // texto no es el mismo, en vez de un 409 sin contexto desde el endpoint.
+            if (keccak256(toBytes(brief)) !== task.taskHash) {
+                return [
+                    'That text is NOT the one hired: its hash does not match the one on the chain.',
+                    `  hired hash: ${task.taskHash}`,
+                    `  your text hash: ${keccak256(toBytes(brief))}`,
+                    'It must be identical, character for character. One extra space already changes it.',
+                ].join('\n');
+            }
+            const agent = await panal.getAgent(task.worker);
+            if (!agent.metadata.botUrl)
+                return 'That agent publishes no endpoint: there is nowhere to send the job.';
+            const firma = await account.signMessage({ message: briefSignMessage(BigInt(id)) });
+            const fallo = await pushBrief(agent.metadata.botUrl, BigInt(id), brief, account.address, firma);
+            if (fallo === null) {
+                log(`brief #${id} entregado (reintento) en ${agent.metadata.botUrl}`);
+                return `Job delivered. The agent is already working on task #${id}.`;
             }
+            return `It still does not arrive (${fallo}). The payment stays locked and returns on its own when the deadline passes.`;
         },
     },
     {
         name: 'panal_approve_task',
-        description: 'Aprueba el resultado entregado, LIBERA EL PAGO al agente y le deja una valoración de 1 a 5. ' +
-            'Solo tras enseñarle el resultado a la persona y que ella decida la nota.',
+        description: 'Approve the delivered result, RELEASE THE PAYMENT to the agent and leave a 1-5 rating. ' +
+            'Only after showing the result to the person and letting them decide the score.',
         inputSchema: {
             type: 'object',
             properties: {
                 task_id: { type: 'number', description: 'Id de la tarea entregada.' },
-                rating: { type: 'number', description: 'Valoración de 1 a 5 que ha decidido la persona.' },
-                confirmed_by_user: { type: 'boolean', description: 'true solo si la persona lo ha aprobado.' },
+                rating: { type: 'number', description: 'The 1-5 rating the person decided.' },
+                confirmed_by_user: { type: 'boolean', description: 'true only if the person approved it.' },
             },
             required: ['task_id', 'rating', 'confirmed_by_user'],
         },
@@ -390,20 +626,20 @@ const WRITE_TOOLS = [
             if (blocked)
                 return blocked;
             if (args.confirmed_by_user !== true) {
-                return 'No libero el pago sin confirmed_by_user: true. Enséñale el resultado a la persona primero.';
+                return 'I will not release the payment without confirmed_by_user: true. Show the result to the person first.';
             }
             const id = Number(args.task_id);
             const rating = Number(args.rating);
             if (!Number.isInteger(id) || id < 0)
-                return 'El id de la tarea es un entero.';
+                return 'The task id is an integer.';
             if (!Number.isInteger(rating) || rating < 1 || rating > 5)
-                return 'La valoración es un entero de 1 a 5.';
+                return 'The rating is an integer from 1 to 5.';
             try {
                 const hash = await panal.approveTask(BigInt(id), rating);
-                return `Pago liberado para la tarea #${id} con valoración ${rating}/5.\n  tx: ${EXPLORER}/tx/${hash}`;
+                return `Payment released for task #${id} with a ${rating}/5 rating.\n  tx: ${EXPLORER}/tx/${hash}`;
             }
             catch (err) {
-                return `No se pudo aprobar: ${err instanceof Error ? err.message : err}`;
+                return `Could not approve: ${err instanceof Error ? err.message : err}`;
             }
         },
     },
@@ -450,7 +686,7 @@ async function handle(req) {
             const name = typeof req.params?.name === 'string' ? req.params.name : '';
             const tool = TOOLS.find((t) => t.name === name);
             if (!tool) {
-                replyError(req.id, -32602, `No existe la herramienta "${name}".`);
+                replyError(req.id, -32602, `There is no tool named "${name}".`);
                 return;
             }
             const args = req.params?.arguments ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panal-mcp",
-  "version": "0.1.3",
+  "version": "0.3.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.4.0",
+    "@panal/sdk": "^0.6.1",
     "viem": "^2.21.0"
   },
   "devDependencies": {