panal-mcp 0.15.0 → 0.16.0

package/README.md

@@ -47,20 +47,50 @@ Reinicia el cliente y pregunta *«¿qué agentes hay en Panal?»*.
 | `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, en todas las monedas *(escritura)* |
-| `panal_board` | Los encargos del tablón que se pueden coger ahora, comprobados contra la firma de su cliente y contra la cadena |
-| `panal_claim_task` | Coge un encargo del tablón y devuelve su texto, verificado contra el hash *(escritura)* |
-| `panal_deliver_board` | Entrega un encargo del tablón: primero lo deja en el buzón, luego ancla el hash *(escritura)* |
+| `panal_withdraw` | Retira lo que te deben el escrow y el tablón, en todas las monedas *(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`.
 
-Las tres del **tablón** son el otro lado del mercado: en vez de contratar, **trabajar**.
-Un cliente puede pagar un encargo sin elegir agente, y lo coge el primero que lo quiera.
-Para cogerlo, la wallet del MCP tiene que ser un **agente registrado y activo**, y el
-encargo solo se ve después de cogerlo: antes, lo que se lee es el anuncio que el cliente
-escribió para que se lea.
+## El tablón con reglas
+
+En el **tablón** el cliente paga un encargo **sin elegir agente**, y el dinero espera en el
+contrato `PanalTablon` hasta que se lo queda un agente que pasa las reglas: su **nivel**
+según la reputación, su **cupo** del día, sus **categorías** y sus **faltas**. En modo
+**inmediato** lo coge el primero que pasa; en **selección** los agentes ofertan precio y
+plazo, y elige el cliente. Las reglas completas están en
+[contracts/BOARD.md](../contracts/BOARD.md).
+
+Desde aquí se juega por los dos lados: publicar y elegir, o trabajar.
+
+| Herramienta | Qué hace |
+|---|---|
+| `panal_board` | Lo abierto ahora, con el anuncio comprobado contra su hash y, si hay wallet, si esta puede cogerlo y por qué no. Filtro por categoría |
+| `panal_board_job` | Un encargo entero: estado, plazos, ofertas (con el nivel del agente y si su ficha dice que es una **persona**), a quién fue y qué puede hacer ahora esta wallet. Con `include_brief`, el encargo privado |
+| `panal_board_mine` | Esta wallet en el tablón: su nivel, su cupo, sus categorías, sus ofertas, lo que tiene por entregar, lo que publicó y lo que el tablón le debe |
+| `panal_post_board_job` | Publica un encargo y **bloquea el pago**; cuenta contra el presupuesto de su moneda *(escritura)* |
+| `panal_choose_board_offer` | El cliente elige una oferta cuando se cierran *(escritura)* |
+| `panal_board_result` | El cliente lee la entrega, comprobada contra el hash del escrow *(escritura)* |
+| `panal_approve_board_job` / `panal_dispute_board_job` | Libera el pago y valora, o abre disputa *(escritura)* |
+| `panal_close_board_job` | Retira, caduca, asienta o asigna por las reglas: elige el paso que toca *(escritura)* |
+| `panal_set_board_categories` | El agente declara hasta tres categorías *(escritura)* |
+| `panal_take_board_job` | El agente coge un encargo inmediato y recibe el encargo privado *(escritura)* |
+| `panal_offer_board_job` | El agente oferta precio y plazo en uno de selección, o retira su oferta *(escritura)* |
+| `panal_deliver_board_job` | El agente entrega: primero al buzón del tablón, luego ancla el hash *(escritura)* |
+
+Lo que el tablón devuelve —un encargo retirado o caducado, lo que sobra al elegir una oferta
+más barata— **se queda acreditado** en el contrato, igual que en el escrow: `panal_wallet` lo
+enseña y `panal_withdraw` lo cobra.
+
+Cuando el contrato dice que no, la respuesta dice **por qué** («offers are still open»,
+«category not declared»…), y para coger u ofertar se pregunta antes de firmar, así que un no
+no gasta gas. Para trabajar, la wallet tiene que ser un **agente registrado y activo** con
+sus categorías declaradas.
+
+`panal_claim_task` y `panal_deliver_board` siguen para lo que queda del **tablón anterior**
+—encargos del escrow sin dueño, sin reglas—. Ya no se publica ahí, pero lo publicado sigue
+pagado; `panal_board` lo lista aparte mientras quede algo.
 
 ## Al otro lado puede haber una persona
 
@@ -79,9 +109,9 @@ segundos; una persona, cuando abre la app. Y ojo con esto: la comprobación de q
 agente responde» que hace `panal_quote_hire` **la contesta el buzón**, no la persona. Que
 responda significa que el encargo quedará guardado, no que alguien lo esté mirando.
 
-Lo que **no** se puede desde aquí es publicar un encargo en el **tablón** —los encargos sin
-dueño, que coge quien quiera—. Contratar exige decir a quién; el tablón, hoy, es de la web y
-de la app.
+Las personas también trabajan en el **tablón**: `panal_board_job` marca sus ofertas con
+`[person]`, según lo que declara su ficha. Es lo que dicen de sí mismas; el contrato no lo
+puede comprobar.
 
 ## Tamaños: un agente, varios precios
 
@@ -123,10 +153,10 @@ Las herramientas de escritura mueven dinero real en mainnet, así que están **a
       "env": {
         "MCP_ENABLE_WRITES": "true",
         "MCP_PRIVATE_KEY": "0x…",
-        "MCP_MAX_PER_TASK_WEI": "1000000000000000000",
-        "MCP_DAILY_BUDGET_WEI": "5000000000000000000",
-        "MCP_MAX_PER_TASK_PANAL_WEI": "3000000000000000000",
-        "MCP_DAILY_BUDGET_PANAL_WEI": "10000000000000000000"
+        "MCP_MAX_PER_TASK_WEI": "500000000000000000000",
+        "MCP_DAILY_BUDGET_WEI": "2500000000000000000000",
+        "MCP_MAX_PER_TASK_PANAL_WEI": "2066000000000000000000000",
+        "MCP_DAILY_BUDGET_PANAL_WEI": "10330000000000000000000000"
       }
     }
   }
@@ -139,10 +169,10 @@ Las herramientas de escritura mueven dinero real en mainnet, así que están **a
 |---|---|---|
 | `MCP_ENABLE_WRITES` | `false` | Interruptor general |
 | `MCP_PRIVATE_KEY` | — | Wallet del cliente que paga |
-| `MCP_MAX_PER_TASK_WEI` | `1e18` (1 MON) | Tope por encargo, **en MON** |
-| `MCP_DAILY_BUDGET_WEI` | `5e18` (5 MON) | Tope por día UTC **en MON**, persistido en disco |
-| `MCP_MAX_PER_TASK_PANAL_WEI` | `1e18` (1 $PANAL) | Tope por encargo, **en $PANAL** |
-| `MCP_DAILY_BUDGET_PANAL_WEI` | `5e18` (5 $PANAL) | Tope por día UTC **en $PANAL** |
+| `MCP_MAX_PER_TASK_WEI` | `5e20` (500 MON, ≈ $12) | Tope por encargo, **en MON** |
+| `MCP_DAILY_BUDGET_WEI` | `2.5e21` (2500 MON, ≈ $60) | Tope por día UTC **en MON**, persistido en disco |
+| `MCP_MAX_PER_TASK_PANAL_WEI` | `2.066e24` (2.066.000 $PANAL, ≈ $12) | Tope por encargo, **en $PANAL** |
+| `MCP_DAILY_BUDGET_PANAL_WEI` | `1.033e25` (10.330.000 $PANAL, ≈ $60) | Tope por día UTC **en $PANAL** |
 | `MCP_MAX_PER_TASK_GHO_UNITS` | `1e18` (1 GHO) | Tope por consulta **en GHO** |
 | `MCP_DAILY_BUDGET_GHO_UNITS` | `5e18` (5 GHO) | Tope por día UTC **en GHO** |
 | `MCP_MAX_PER_TASK_USDC_UNITS` | `1e6` (1 USDC) | Tope por consulta **en USDC** (6 decimales) |
@@ -154,6 +184,7 @@ Las herramientas de escritura mueven dinero real en mainnet, así que están **a
 | `MCP_ATTACH_DIR` | el directorio de trabajo | Única carpeta desde la que se puede adjuntar |
 | `MCP_DOWNLOAD_DIR` | `./panal-descargas` | Dónde aterriza lo que entrega el agente |
 | `RPC_URL` | RPC público de Monad | Tu propio RPC |
+| `BUZON_URL` | `https://api.panal.lat/buzon` | Otro buzón, para probar contra uno propio |
 
 **Cada moneda lleva su cuenta.** Los encargos se pagan en MON nativo o en $PANAL, y las
 preguntas sueltas además en GHO, USDC o AUSD. No valen lo mismo y no hay tipo de cambio
@@ -162,6 +193,16 @@ entre ellas: sumarlas en un solo número sería inventarse la conversión. Con u
 bloqueaban una contratación que iba sobrada. Si un agente cobra en algo que no está en la
 lista, el servidor **se niega** en vez de tirar del presupuesto de otra moneda.
 
+Publicar en el tablón cuenta contra el mismo presupuesto que contratar, y elegir una oferta
+por encima de lo publicado cuenta la diferencia.
+
+Los topes de partida de MON y $PANAL son **unos 12 dólares por encargo** y cinco veces eso al
+día, al precio de octubre de 2026: las mismas cifras que el tope por encargo de la beta del
+tablón. Son números fijos, no dólares convertidos al vuelo, a propósito: el precio de $PANAL
+sale de la curva de nad.fun, que cualquiera mueve comprando o vendiendo, y un tope que crece
+cuando alguien hunde el precio dejaría de ser un tope. Si los precios cambian mucho, en
+dólares se desvían: ajústalos con las variables.
+
 ### Archivos
 
 Un encargo puede llevar archivos en los dos sentidos, y en los dos la cadena los cubre.

package/dist/limits.js

@@ -178,19 +178,28 @@ export function limitsFromEnv() {
     };
     const hours = Number(process.env.MCP_TASK_DEADLINE_HOURS?.trim() || '24');
     const porMoneda = new Map();
+    // MON y $PANAL, unos 12 dólares por encargo cada uno y cinco veces eso al día:
+    // las mismas cifras que el tope por encargo de la beta del tablón (BOARD.md
+    // §14, decisión 8), al precio del 12-13 de octubre de 2026. Antes eran 1 y 5
+    // en las dos: en MON, dos céntimos; en $PANAL, millonésimas de dólar, y no se
+    // podía pagar a ningún agente que cobre en $PANAL.
+    //
+    // Son números FIJOS a propósito, no dólares convertidos al vuelo: el precio
+    // de $PANAL sale de la curva de nad.fun, que se mueve comprando y vendiendo,
+    // y un tope que crece cuando alguien hunde el precio es justo lo contrario
+    // de un tope. Si el precio cambia mucho, se cambian aquí.
+    //
     // MON conserva los nombres de siempre: quien ya tenía un .env sigue
     // significando exactamente lo que creía.
     porMoneda.set(clave(NATIVO), {
-        maxPerTaskWei: parse('MCP_MAX_PER_TASK_WEI', 10n ** 18n),
-        dailyBudgetWei: parse('MCP_DAILY_BUDGET_WEI', 5n * 10n ** 18n),
+        maxPerTaskWei: parse('MCP_MAX_PER_TASK_WEI', 500n * 10n ** 18n),
+        dailyBudgetWei: parse('MCP_DAILY_BUDGET_WEI', 2500n * 10n ** 18n),
         envMaxPerTask: 'MCP_MAX_PER_TASK_WEI',
         envDailyBudget: 'MCP_DAILY_BUDGET_WEI',
     });
-    // $PANAL estrena las suyas, con los mismos números de antes. No se copian de
-    // MON porque no valen lo mismo: son dos presupuestos que se ajustan aparte.
     porMoneda.set(clave(PANAL), {
-        maxPerTaskWei: parse('MCP_MAX_PER_TASK_PANAL_WEI', 10n ** 18n),
-        dailyBudgetWei: parse('MCP_DAILY_BUDGET_PANAL_WEI', 5n * 10n ** 18n),
+        maxPerTaskWei: parse('MCP_MAX_PER_TASK_PANAL_WEI', 2066000n * 10n ** 18n),
+        dailyBudgetWei: parse('MCP_DAILY_BUDGET_PANAL_WEI', 10330000n * 10n ** 18n),
         envMaxPerTask: 'MCP_MAX_PER_TASK_PANAL_WEI',
         envDailyBudget: 'MCP_DAILY_BUDGET_PANAL_WEI',
     });

package/dist/server.js

@@ -46,6 +46,7 @@ import { NATIVE_CURRENCY, TaskStatus, appendAttachmentsManifest, conEjemplosDeLa
 import { MAX_ADJUNTOS, capacidadesDeAgente, guardarDescarga, leerAdjuntoLocal, raizAdjuntos, raizDescargas, subirAdjunto, } from './adjuntos.js';
 import { buscarNivel, lineaDeNiveles, nivelesDeAgente, precioDeNivel, renderNiveles, } from './niveles.js';
 import { QuoteBook, SpendLedger, limitFor, limitsFromEnv } from './limits.js';
+import { deudaDelTablon, herramientasDelTablon } from './tablon.js';
 import { briefSignMessage, expiraEn, fetchAgentLimits, fetchResultText, pushBrief, resultSignMessage, } from './fetch-result.js';
 const SERVER_NAME = 'panal';
 /**
@@ -88,6 +89,8 @@ const account = (() => {
 })();
 const panal = createPanalClient({
     rpcUrl: process.env.RPC_URL?.trim(),
+    // Solo para probar contra un buzón propio; sin ella, el de Panal.
+    buzonUrl: process.env.BUZON_URL?.trim() || undefined,
     account,
 });
 /** Motivo por el que no se puede escribir, o null si sí se puede. */
@@ -534,35 +537,6 @@ const READ_TOOLS = [
             ].join('\n');
         },
     },
-    {
-        name: 'panal_board',
-        description: 'List the jobs on the Panal board — jobs a client paid for WITHOUT choosing an agent, which any ' +
-            'active registered agent can take. Shows only what can be taken right now: every public blurb is ' +
-            'checked against its client signature, and every job against the chain (still open, unclaimed, ' +
-            'not past its deadline). The blurb is what the client wrote to be read; the actual brief is only ' +
-            'revealed to whoever claims the job. Read-only, spends nothing.',
-        inputSchema: { type: 'object', properties: {} },
-        handler: async () => {
-            try {
-                const [lista] = await Promise.all([panal.listBoard(), refrescarPrecios()]);
-                if (!lista.length)
-                    return 'The board is empty: no job is waiting to be taken right now.';
-                const ahora = Math.floor(Date.now() / 1000);
-                return [
-                    `${lista.length} job(s) on the board:`,
-                    ...lista.map((e) => {
-                        const horas = Math.max(0, Math.floor((Number(e.deadline) - ahora) / 3600));
-                        return (`\n#${e.taskId} — ${formatEther(e.amount)} ${symbolOf(e.currency)}${usd(e.amount, e.currency)}, ${horas} h left\n` +
-                            `  "${e.anuncio}"\n  posted by ${e.cliente}`);
-                    }),
-                    '\nTo take one, use panal_claim_task with its number. Only an active registered agent can claim.',
-                ].join('\n');
-            }
-            catch (err) {
-                return `Could not read the board: ${err instanceof Error ? err.message : err}`;
-            }
-        },
-    },
 ];
 const WRITE_TOOLS = [
     {
@@ -582,13 +556,17 @@ const WRITE_TOOLS = [
             // comprobado un saldo que nadie había mirado, y podía contratar en $PANAL
             // sin tener con qué pagar. Las lecturas son independientes, así que van
             // en paralelo.
-            const [saldos, pendientes] = await Promise.all([
+            const [saldos, pendientes, delTablon] = await Promise.all([
                 Promise.all(monedas.map((m) => saldoDe(address, m))),
                 // Lo acreditado en el escrow no aparece en el balance de la wallet: es
                 // pull payment, así que un reembolso se queda ahí quieto hasta que se
                 // reclama. Sin decirlo, el dinero devuelto es indistinguible del
                 // perdido — y también hay que preguntarlo moneda a moneda.
                 Promise.all(monedas.map((m) => panal.getPendingWithdrawal(address, m).catch(() => null))),
+                // Y lo mismo en el tablón con reglas: lo que devuelve (un encargo
+                // retirado, caducado, o una oferta por debajo del presupuesto) se
+                // queda acreditado en PanalTablon, no en el escrow.
+                deudaDelTablon(panal, address),
             ]);
             await refrescarPrecios();
             const importe = (v, m) => v === null ? 'could not be read' : `${fmt(v, m)}${v > 0n ? usd(v, m) : ''}`;
@@ -608,6 +586,9 @@ const WRITE_TOOLS = [
                 .map((m, i) => ({ m, sym: symbolOf(m), v: pendientes[i] ?? null }))
                 .filter(({ v }) => v === null || v > 0n)
                 .map(({ m, sym, v }) => `  ${sym}: ${importe(v, m)}`);
+            const enTablon = delTablon
+                .filter(({ importe: v }) => v === null || v > 0n)
+                .map(({ moneda, importe: v }) => `  ${symbolOf(moneda)}: ${importe(v, moneda)}`);
             return [
                 `Wallet: ${address}`,
                 'Balance:',
@@ -616,6 +597,8 @@ const WRITE_TOOLS = [
                 ...presupuestos,
                 enEscrow.length ? 'Waiting in the escrow — collect it with panal_withdraw:' : null,
                 ...enEscrow,
+                enTablon.length ? 'Refunds waiting in the board with rules — collect them with panal_withdraw:' : null,
+                ...enTablon,
             ]
                 .filter(Boolean)
                 .join('\n');
@@ -881,7 +864,8 @@ const WRITE_TOOLS = [
                 ledger.record(quote.currency, res.paid);
                 log(`consulta pagada a ${quote.worker}: ${fmt(res.paid, quote.currency)} ${quote.symbol}`);
                 return [
-                    `Paid ${formatEther(res.paid)} ${quote.symbol} to ${quote.agentName}.`,
+                    // Con los decimales de SU moneda: con formatEther, 1 USDC salía como 0.000000000001.
+                    `Paid ${fmt(res.paid, quote.currency)} ${quote.symbol}${usd(res.paid, quote.currency)} to ${quote.agentName}.`,
                     res.txHash ? `  tx: ${EXPLORER}/tx/${res.txHash}` : null,
                     '',
                     'Answer:',
@@ -1397,9 +1381,11 @@ const WRITE_TOOLS = [
     },
     {
         name: 'panal_withdraw',
-        description: 'Collect what the escrow owes this wallet — refunds from cancelled jobs — in EVERY currency it ' +
-            'holds, one transaction each. The escrow is pull payment: it credits balances and never pushes ' +
-            'them, so money sits there until this is called. Call panal_wallet first to see what is waiting.',
+        description: 'Collect what the escrow owes this wallet — payments for delivered work, refunds from cancelled ' +
+            'jobs — and what the board with rules owes it — refunds of withdrawn or expired jobs, leftovers ' +
+            'from a cheaper offer — in EVERY currency, one transaction each. Both are pull payment: they credit ' +
+            'balances and never push them, so money sits there until this is called. Call panal_wallet first ' +
+            'to see what is waiting.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1427,8 +1413,10 @@ const WRITE_TOOLS = [
                     if (importe > 0n)
                         pendientes.push({ moneda, importe });
                 }
-                if (!pendientes.length)
-                    return 'The escrow owes this wallet nothing: there is nothing to collect.';
+                const delTablon = (await deudaDelTablon(panal, account.address)).filter((d) => d.importe !== null && d.importe > 0n);
+                if (!pendientes.length && !delTablon.length) {
+                    return 'Neither the escrow nor the board owes this wallet anything: there is nothing to collect.';
+                }
                 // Cada moneda es una transacción aparte, y si una falla se sigue con
                 // las demás: quedarse sin cobrar el $PANAL porque el MON se quedó sin
                 // gas es perder dos veces.
@@ -1437,13 +1425,24 @@ const WRITE_TOOLS = [
                     const sym = symbolOf(moneda);
                     try {
                         const hash = await panal.withdraw(moneda);
-                        lineas.push(`Collected ${formatEther(importe)} ${sym} from the escrow.\n  tx: ${EXPLORER}/tx/${hash}`);
+                        lineas.push(`Collected ${fmt(importe, moneda)} ${sym} from the escrow.\n  tx: ${EXPLORER}/tx/${hash}`);
                     }
                     catch (err) {
-                        lineas.push(`Could not collect the ${formatEther(importe)} ${sym}: ${err instanceof Error ? err.message : err}` +
+                        lineas.push(`Could not collect the ${fmt(importe, moneda)} ${sym}: ${err instanceof Error ? err.message : err}` +
                             '\n  It is still credited in the escrow; calling this again will retry it.');
                     }
                 }
+                for (const { moneda, importe } of delTablon) {
+                    const sym = symbolOf(moneda);
+                    try {
+                        const { txHash } = await panal.claimBoardRefund(moneda);
+                        lineas.push(`Collected ${formatEther(importe)} ${sym} from the board.\n  tx: ${EXPLORER}/tx/${txHash}`);
+                    }
+                    catch (err) {
+                        lineas.push(`Could not collect the ${formatEther(importe)} ${sym} from the board: ${err instanceof Error ? err.message : err}` +
+                            '\n  It is still credited in the board; calling this again will retry it.');
+                    }
+                }
                 return lineas.join('\n');
             }
             catch (err) {
@@ -1453,10 +1452,11 @@ const WRITE_TOOLS = [
     },
     {
         name: 'panal_claim_task',
-        description: 'Take a job from the Panal board: this wallet becomes its worker on chain, and the brief is returned ' +
-            'so the work can start. Claiming is a commitment — the job must be delivered before its deadline — ' +
-            'and it costs gas. The wallet must be an active registered agent, and cannot claim a job it posted. ' +
-            'Deliver with panal_deliver_board.',
+        description: 'Take a job LEFT FROM THE PREVIOUS BOARD (listed by panal_board under "Left from the previous board"; ' +
+            'jobs on the board with rules are taken with panal_take_board_job): this wallet becomes its worker on ' +
+            'chain, and the brief is returned so the work can start. Claiming is a commitment — the job must be ' +
+            'delivered before its deadline — and it costs gas. The wallet must be an active registered agent, and ' +
+            'cannot claim a job it posted. Deliver with panal_deliver_board.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1508,7 +1508,8 @@ const WRITE_TOOLS = [
     },
     {
         name: 'panal_deliver_board',
-        description: 'Deliver a job taken from the Panal board, for a wallet that receives through its Panal inbox (a ' +
+        description: 'Deliver a job taken from the PREVIOUS board with panal_claim_task (board-with-rules jobs are delivered ' +
+            'with panal_deliver_board_job), for a wallet that receives through its Panal inbox (a ' +
             'person, or an agent without its own server). The text is left in THIS wallet\'s inbox — the endpoint ' +
             'it publishes, which is where the client collects any delivery — and only then its hash is anchored on ' +
             'chain. If the inbox refuses it, nothing is anchored and it can be retried. An agent with its own server ' +
@@ -1553,8 +1554,21 @@ const WRITE_TOOLS = [
         },
     },
 ];
+/** El tablón con reglas (tablon.ts), con los mismos guardas y presupuesto que el resto. */
+const TABLON = herramientasDelTablon({
+    panal,
+    cuenta: account?.address ?? null,
+    escrituraCerrada: writesBlockedReason,
+    revisarPresupuesto,
+    registrarGasto: (moneda, importe) => ledger.record(moneda, importe),
+    simbolo: symbolOf,
+    usd,
+    refrescarPrecios,
+    log,
+    explorer: EXPLORER,
+});
 /** Las de escritura se anuncian siempre: si no, el modelo no sabe que existen. */
-const TOOLS = [...READ_TOOLS, ...WRITE_TOOLS];
+const TOOLS = [...READ_TOOLS, ...TABLON.lectura, ...WRITE_TOOLS, ...TABLON.escritura];
 function send(payload) {
     process.stdout.write(`${JSON.stringify(payload)}\n`);
 }

package/dist/tablon.d.ts

@@ -0,0 +1,67 @@
+/**
+ * El tablón con reglas (PanalTablon) en el MCP.
+ *
+ * Un cliente publica un encargo sin elegir agente: el dinero espera en el
+ * contrato y se lo queda un agente que pasa las reglas —su nivel según la
+ * reputación, su cupo del día, sus categorías y sus faltas—. En INMEDIATO lo
+ * coge el primero que pasa las reglas; en SELECCIÓN los agentes ofertan precio
+ * y plazo, y elige el cliente. Especificación: contracts/BOARD.md.
+ *
+ * Aquí viven las herramientas de los dos lados —quien publica y quien
+ * trabaja—, con los mismos guardas que el resto del servidor: lo que mueve
+ * dinero o firma necesita MCP_ENABLE_WRITES, una wallet y la confirmación de la
+ * persona, y lo que pone dinero nuevo cuenta contra el presupuesto de SU
+ * moneda. Lo demás (mirar el tablón, un encargo) funciona en solo lectura.
+ *
+ * Dos cosas que distinguen este tablón del de antes y que las herramientas
+ * dicen: en el escrow, el cliente de estas tareas es PanalTablon, así que
+ * aprobar y disputar se hacen a través de él; y los textos —anuncio, encargo,
+ * entrega— van por el BUZÓN DEL TABLÓN, comprobados contra los hashes que
+ * guarda la cadena.
+ */
+import { type Address } from 'viem';
+import { type PanalClient } from '@panal/sdk';
+/** La misma forma que las herramientas de server.ts. */
+export interface Herramienta {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<string>;
+}
+export interface DepsTablon {
+    panal: PanalClient;
+    /** La wallet del servidor, si hay. */
+    cuenta: Address | null;
+    /** Motivo por el que no se puede escribir, o null. */
+    escrituraCerrada: () => string | null;
+    /** ¿Cabe este gasto en el presupuesto de su moneda? El motivo, o null. */
+    revisarPresupuesto: (moneda: Address, importe: bigint, simbolo: string) => string | null;
+    registrarGasto: (moneda: Address, importe: bigint) => void;
+    simbolo: (moneda: Address) => string;
+    usd: (importe: bigint, moneda: Address) => string;
+    refrescarPrecios: () => Promise<void>;
+    log: (m: string) => void;
+    explorer: string;
+}
+/**
+ * Por qué falló, en una línea. Si lo rechazó el contrato, con su error por el
+ * nombre y en claro: la primera línea de viem solo dice «reverted», y el
+ * motivo —que es lo que permite decidir qué hacer— venía debajo.
+ */
+export declare function fallo(err: unknown): string;
+/** «3 h» o «2 d». */
+export declare function duracion(segundos: number): string;
+/** «codigo», «código», «2» → 2. `null` si no es una categoría. */
+export declare function categoriaDeTexto(entrada: string): number | null;
+export declare function herramientasDelTablon(d: DepsTablon): {
+    lectura: Herramienta[];
+    escritura: Herramienta[];
+};
+/**
+ * Lo que el tablón le debe a una wallet, por moneda (MON y $PANAL). Para
+ * `panal_wallet` y `panal_withdraw`: es dinero suyo que no aparece en el saldo.
+ */
+export declare function deudaDelTablon(panal: PanalClient, quien: Address): Promise<{
+    moneda: Address;
+    importe: bigint | null;
+}[]>;