panal-mcp 0.2.0 → 0.3.1

package/dist/fetch-result.d.ts

@@ -10,8 +10,18 @@
  * 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.
  */
-/** El mensaje que firma el cliente. Debe coincidir con el bot y el frontend. */
-export declare function resultSignMessage(taskId: bigint): string;
+/** Cuánto vale una firma de descarga: abre toda la entrega, así que poco. */
+export declare const VENTANA_FIRMA_S: number;
+/**
+ * El mensaje que firma el cliente. Debe coincidir con el bot y el frontend.
+ *
+ * Lleva la caducidad dentro: cambiarla invalida la firma. Antes no caducaba, y
+ * como además viajaba en la query acababa en el log del proxy — un pase de
+ * acceso permanente escrito en un archivo de texto.
+ */
+export declare function resultSignMessage(taskId: bigint, expira: number): string;
+/** El segundo en el que caduca una firma emitida ahora. */
+export declare function expiraEn(ventanaS?: number): number;
 /** El mensaje que firma el cliente para MANDAR el encargo. Mismo pacto. */
 export declare function briefSignMessage(taskId: bigint): string;
 /**
@@ -27,18 +37,5 @@ export declare function briefSignMessage(taskId: bigint): string;
  * 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.
- *
- * Sin esto, cualquiera puede registrar un agente cuyo endpoint sea
- * `http://169.254.169.254/latest/meta-data/` y usar este servidor para leer las
- * credenciales de la máquina donde corre.
- *
- * Queda una ventana de DNS rebinding: se resuelve aquí y `fetch` vuelve a
- * resolver por su cuenta. Cerrarla del todo exige un agente HTTP a medida; el
- * riesgo residual es aceptable porque la respuesta solo se compara contra un
- * hash y nunca se ejecuta.
- */
-export declare function assertPublicUrl(raw: string): Promise<URL>;
 /** Descarga acotada: se corta en cuanto se pasa del tope. */
-export declare function fetchResultText(botUrl: string, taskId: bigint, client: string, signature: string): Promise<string>;
+export declare function fetchResultText(botUrl: string, taskId: bigint, client: string, signature: string, expira: number): Promise<string>;

package/dist/fetch-result.js

@@ -10,14 +10,29 @@
  * 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 { lookup } from 'node:dns/promises';
-import { isIP } from 'node:net';
+// El guard de SSRF viene del SDK, no de una copia local. Había dos
+// 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';
 /** Tope de la respuesta. Sin esto, un endpoint hostil tumba el proceso. */
 const MAX_BYTES = 512 * 1024;
 const TIMEOUT_MS = 20_000;
-/** El mensaje que firma el cliente. Debe coincidir con el bot y el frontend. */
-export function resultSignMessage(taskId) {
-    return `Panal resultado #${taskId.toString()}`;
+/** Cuánto vale una firma de descarga: abre toda la entrega, así que poco. */
+export const VENTANA_FIRMA_S = 10 * 60;
+/**
+ * El mensaje que firma el cliente. Debe coincidir con el bot y el frontend.
+ *
+ * Lleva la caducidad dentro: cambiarla invalida la firma. Antes no caducaba, y
+ * como además viajaba en la query acababa en el log del proxy — un pase de
+ * acceso permanente escrito en un archivo de texto.
+ */
+export function resultSignMessage(taskId, expira) {
+    return `Panal resultado #${taskId.toString()} · ${expira}`;
+}
+/** El segundo en el que caduca una firma emitida ahora. */
+export function expiraEn(ventanaS = VENTANA_FIRMA_S) {
+    return Math.floor(Date.now() / 1000) + ventanaS;
 }
 /** El mensaje que firma el cliente para MANDAR el encargo. Mismo pacto. */
 export function briefSignMessage(taskId) {
@@ -72,77 +87,23 @@ export async function pushBrief(botUrl, taskId, brief, client, signature) {
         clearTimeout(timer);
     }
 }
-/** ¿Esta IP apunta dentro de nuestra propia red? */
-function isPrivateIp(ip) {
-    if (isIP(ip) === 6) {
-        const v6 = ip.toLowerCase();
-        if (v6 === '::1' || v6 === '::')
-            return true;
-        if (/^f[cd]/.test(v6) || v6.startsWith('fe80'))
-            return true;
-        // IPv4 mapeada: ::ffff:10.0.0.1
-        const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(v6);
-        return mapped ? isPrivateIp(mapped[1]) : false;
-    }
-    const [a = 0, b = 0] = ip.split('.').map(Number);
-    return (a === 0 ||
-        a === 10 ||
-        a === 127 ||
-        (a === 169 && b === 254) || // metadatos de la nube: credenciales
-        (a === 172 && b >= 16 && b <= 31) ||
-        (a === 192 && b === 168) ||
-        (a === 100 && b >= 64 && b <= 127) || // CGNAT
-        a >= 224);
-}
-/**
- * Rechaza una URL que apunte a algo que no sea internet pública.
- *
- * Sin esto, cualquiera puede registrar un agente cuyo endpoint sea
- * `http://169.254.169.254/latest/meta-data/` y usar este servidor para leer las
- * credenciales de la máquina donde corre.
- *
- * Queda una ventana de DNS rebinding: se resuelve aquí y `fetch` vuelve a
- * resolver por su cuenta. Cerrarla del todo exige un agente HTTP a medida; el
- * riesgo residual es aceptable porque la respuesta solo se compara contra un
- * hash y nunca se ejecuta.
- */
-export async function assertPublicUrl(raw) {
-    let url;
-    try {
-        url = new URL(raw);
-    }
-    catch {
-        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(`The agent endpoint must be https, and it is ${url.protocol}//`);
-    }
-    if (url.username || url.password)
-        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(`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(`Could not resolve ${host}.`);
-    for (const ip of ips) {
-        if (isPrivateIp(ip))
-            throw new Error(`The endpoint points at an internal address (${ip}): rejected.`);
-    }
-    return url;
-}
 /** Descarga acotada: se corta en cuanto se pasa del tope. */
-export async function fetchResultText(botUrl, taskId, client, signature) {
+export async function fetchResultText(botUrl, taskId, client, signature, expira) {
     const base = await assertPublicUrl(botUrl);
     const url = new URL(`/result/${taskId}`, base);
-    url.searchParams.set('address', client);
-    url.searchParams.set('signature', signature);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
     try {
-        const res = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+        // En cabeceras, no en la query: por ahí acababan en el log del proxy.
+        const res = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                accept: 'application/json',
+                'x-panal-address': client,
+                'x-panal-signature': signature,
+                'x-panal-expira': String(expira),
+            },
+        });
         if (!res.ok) {
             throw new Error(`The agent endpoint replied ${res.status}. Is it still up, and is the signature the client's?`);
         }

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: 'That quote does not exist or has expired (they last 5 minutes). ' +
-                    'Ask for a new one with panal_quote_hire and show it to the person before hiring.',
+                    '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

@@ -30,7 +30,7 @@ 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 { briefSignMessage, fetchResultText, pushBrief, resultSignMessage } from './fetch-result.js';
+import { briefSignMessage, expiraEn, fetchResultText, pushBrief, resultSignMessage } from './fetch-result.js';
 const SERVER_NAME = 'panal';
 /**
  * Sale del package.json, no de una constante a mano: la copiada se quedó en
@@ -97,7 +97,10 @@ function renderAgent(agent) {
     return [
         `${agent.metadata.name || '(no name)'} — ${agent.address}`,
         `  Status: ${agent.active ? 'active' : 'DELISTED (does not take jobs)'}`,
-        `  Price: ${price} per task`,
+        // "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 ? `  Description: ${agent.metadata.description}` : null,
         agent.metadata.botUrl ? `  Endpoint: ${agent.metadata.botUrl}` : null,
@@ -157,7 +160,21 @@ const READ_TOOLS = [
             const address = str(args.address);
             if (!address || !isAddress(address))
                 return 'I need a valid 0x address.';
-            return renderAgent(await panal.getAgent(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}`;
         },
     },
     {
@@ -178,6 +195,71 @@ const READ_TOOLS = [
             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: 'Panal marketplace figures: how many agents exist, how many are active, how many jobs so far.',
@@ -255,6 +337,7 @@ const WRITE_TOOLS = [
                     `and this costs ${formatEther(amount)} ${symbol}.`);
             }
             const quote = quotes.issue({
+                kind: 'hire',
                 worker: agent.address,
                 agentName: agent.metadata.name || agent.address,
                 brief,
@@ -276,6 +359,72 @@ const WRITE_TOOLS = [
             ].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: 'Hire the agent and LOCK THE REAL PAYMENT in escrow. Requires a quote_id from panal_quote_hire and ' +
@@ -301,7 +450,7 @@ const WRITE_TOOLS = [
             const id = str(args.quote_id);
             if (!id)
                 return 'The quote_id is missing. Ask for a quote with panal_quote_hire first.';
-            const redeemed = quotes.redeem(id);
+            const redeemed = quotes.redeem(id, 'hire');
             if ('error' in redeemed)
                 return redeemed.error;
             const quote = redeemed.quote;
@@ -388,8 +537,10 @@ const WRITE_TOOLS = [
                     'hash matches.');
             }
             try {
-                const signature = await account.signMessage({ message: resultSignMessage(taskId) });
-                const text = await fetchResultText(agent.metadata.botUrl, taskId, account.address, signature);
+                // La firma caduca: abre el resultado y todos los archivos de la tarea.
+                const expira = expiraEn();
+                const signature = await account.signMessage({ message: resultSignMessage(taskId, expira) });
+                const text = await fetchResultText(agent.metadata.botUrl, taskId, account.address, signature, expira);
                 // Lo que importa de todo esto: que el texto sea EXACTAMENTE el que se
                 // ancló. Sin esta comprobación, el agente podría entregar una cosa
                 // on-chain y enseñarte otra distinta.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panal-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Servidor MCP de Panal: busca y contrata agentes de IA on-chain desde Claude",
   "type": "module",
   "license": "MIT",
@@ -29,18 +29,19 @@
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "tsx src/server.ts",
+    "test": "tsx test/mcp.test.ts",
+    "prepublishOnly": "npm run build"
+  },
   "dependencies": {
-    "@panal/sdk": "^0.4.0",
+    "@panal/sdk": "workspace:^0.7.0",
     "viem": "^2.21.0"
   },
   "devDependencies": {
     "typescript": "^5.6.0",
     "tsx": "^4.19.0"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "start": "tsx src/server.ts",
-    "test": "tsx test/mcp.test.ts"
   }
-}
+}