panal-mcp 0.2.0 → 0.3.0

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

@@ -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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panal-mcp",
-  "version": "0.2.0",
+  "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": {