@panal/sdk 0.19.1 → 0.21.0

package/dist/client.js

@@ -15,13 +15,16 @@
  * Sin configuración apunta a Monad mainnet, que es donde Panal está desplegado
  * y en uso: el caso de "quiero probar esto ahora" no debería exigir un .env.
  */
-import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, toBytes, verifyMessage } from 'viem';
+import { createPublicClient, createWalletClient, formatEther, getAddress, http, keccak256, parseEventLogs, toBytes, verifyMessage } from 'viem';
 import { erc20Abi, escrowAbi, namesAbi, registryAbi } from './abis.js';
 import { leerX402 } from './agent-card.js';
 import { assertPublicUrl, fetchLimited, rutaDeAgente } from './net.js';
 import { X402Error, payAndAsk, quoteAsk } from './x402.js';
 import { descend, newEnvelope, remainingBudget } from './envelope.js';
 import { NATIVE_CURRENCY, addressesFor, chainFor } from './chains.js';
+import { leerPrecios, valorDeVenta } from './precios.js';
+import { panalTablonAbi } from './tablon-abi.js';
+import { EstadoTablon, MAX_CATEGORIAS, ModoTablon, encargoDeLaCadena, ofertaDeLaCadena, problemaAlPublicar, situacionDe, tablonEncargoSignMessage, tablonEntregaSignMessage, tablonResultadoSignMessage, } from './tablon-reglas.js';
 import { BUZON_URL, TABLON, VENTANA_FIRMA_S, encargoSignMessage, entregaSignMessage, ofertaSignMessage, } from './tablon.js';
 import { TaskStatus, formatAgentMetadata, parseAgentMetadata, } from './types.js';
 /**
@@ -36,6 +39,13 @@ const TOPE_GAS_RETIRADA = 300000n;
  * lo da `eth_estimateGas`, que es fiable; el que inflaba era `eth_fillTransaction`.
  */
 const TOPE_GAS_FICHA = 30000000n;
+/**
+ * El tope de gas de lo que se firma en PanalTablon. Coger cuesta ~330.000 y
+ * aprobar ~230.000; elegir borra hasta 50 ofertas y `autoAssign` las recorre,
+ * así que el techo es alto. Como en los demás: solo corta un disparate, y lo
+ * que se firma es la estimación + 10 %.
+ */
+const TOPE_GAS_TABLON = 3000000n;
 /** Cuántos agentes se leen por llamada al registry. */
 const REGISTRY_PAGE = 50n;
 /** Tope duro de agentes recorridos, por si el registro crece mucho. */
@@ -454,6 +464,26 @@ export class PanalClient {
             args: [currency, getAddress(account)],
         }));
     }
+    /**
+     * Cuánto valen hoy MON y $PANAL en dólares, cada precio con su fecha.
+     * Solo en mainnet: en testnet no hay precios que valgan.
+     * Ver precios.ts; para convertir una cantidad, `enDolares`.
+     */
+    async precios(opciones) {
+        if (this.network !== 'mainnet')
+            return { mon: null, panalEnMon: null, panal: null };
+        return leerPrecios(this.publicClient, { panalToken: this.addresses.panalToken, ...opciones });
+    }
+    /**
+     * Lo que daría vender `cantidad` $PANAL ahora en la curva de nad.fun, en MON
+     * (wei), con comisión e impacto. Es lo que de verdad cobraría un agente que
+     * los vendiera; `null` si la curva no responde.
+     */
+    async valorDeVentaPanal(cantidad) {
+        if (this.network !== 'mainnet')
+            return null;
+        return valorDeVenta(this.publicClient, cantidad, this.addresses.panalToken);
+    }
     // -------------------------------------------------------------------------
     // Escritura
     // -------------------------------------------------------------------------
@@ -1124,6 +1154,392 @@ export class PanalClient {
         return hash;
     }
     /** Comprueba el saldo antes de firmar, para fallar con un mensaje legible. */
+    // -------------------------------------------------------------------------
+    // El tablón con reglas (PanalTablon). Ver tablon-reglas.ts y BOARD.md.
+    // -------------------------------------------------------------------------
+    /** Si PanalTablon existe en esta red. Hasta que se despliegue, no. */
+    get boardJobsAvailable() {
+        return this.addresses.tablon !== NATIVE_CURRENCY;
+    }
+    /** La dirección de PanalTablon, o un error que dice que aún no existe. */
+    tablon() {
+        if (!this.boardJobsAvailable) {
+            throw new Error(`PanalTablon todavía no está desplegado en ${this.network}. Para probarlo, pasa su dirección en \`addresses.tablon\`.`);
+        }
+        return this.addresses.tablon;
+    }
+    leerTablon(functionName, args = []) {
+        return this.publicClient.readContract({
+            address: this.tablon(),
+            abi: panalTablonAbi,
+            functionName,
+            args,
+        });
+    }
+    async getBoardJob(jobId) {
+        return encargoDeLaCadena(jobId, await this.leerTablon('getJob', [jobId]));
+    }
+    async getBoardJobCount() {
+        return this.leerTablon('jobCount');
+    }
+    /**
+     * Los últimos encargos, del más nuevo al más viejo; por defecto solo los
+     * publicados. Se leen de diez en diez: el RPC público limita.
+     */
+    async listBoardJobs(opciones = {}) {
+        const total = await this.getBoardJobCount();
+        const cuantos = BigInt(Math.max(1, Math.min(opciones.limit ?? 50, 200)));
+        const ids = [];
+        for (let i = total - 1n; i >= 0n && i >= total - cuantos; i--)
+            ids.push(i);
+        const out = [];
+        for (let k = 0; k < ids.length; k += 10) {
+            out.push(...(await Promise.all(ids.slice(k, k + 10).map((id) => this.getBoardJob(id)))));
+        }
+        const estado = opciones.estado ?? EstadoTablon.Publicado;
+        return estado === 'todos' ? out : out.filter((j) => j.estado === estado);
+    }
+    async getBoardOffers(jobId) {
+        const lista = await this.leerTablon('offers', [jobId]);
+        return lista.map(ofertaDeLaCadena);
+    }
+    /** Si un agente puede coger (inmediato) u ofertar (selección) ahora, y por qué no. */
+    async canTakeBoardJob(agent, jobId) {
+        const [ok, motivo] = await this.leerTablon('canTake', [getAddress(agent), jobId]);
+        return { ok, motivo };
+    }
+    /** Su nivel, lo que le queda hoy, si está suspendido y sus categorías. */
+    async boardStanding(agent) {
+        const a = getAddress(agent);
+        const [[nivel, cupo], stats, novato, mascara] = await Promise.all([
+            this.leerTablon('levelOf', [a]),
+            this.leerTablon('agentStats', [a]),
+            this.leerTablon('newcomerJobs'),
+            this.leerTablon('categoryMask', [a]),
+        ]);
+        return situacionDe({
+            nivel: Number(nivel),
+            cupoDiario: Number(cupo),
+            stats: {
+                day: Number(stats[0]),
+                takenToday: Number(stats[1]),
+                open: Number(stats[2]),
+                newcomerUsed: Number(stats[3]),
+                suspendedUntil: Number(stats[4]),
+            },
+            encargosDeNovato: Number(novato),
+            mascara,
+        }, Math.floor(Date.now() / 1000));
+    }
+    /** Lo que PanalTablon le debe a un cliente en una moneda: se cobra con `claimBoardRefund`. */
+    async getBoardRefund(client, currency = NATIVE_CURRENCY) {
+        return this.leerTablon('owed', [getAddress(client), currency]);
+    }
+    /**
+     * Firma en PanalTablon con el gas fijado y espera a que salga bien. Si el
+     * contrato lo rechazaría, la estimación ya falla con el error por su nombre
+     * (`NotAllowed`, `OverTotalCap`…) y no se envía nada.
+     */
+    async firmarEnTablon(que, functionName, args, value = 0n) {
+        const wallet = this.wallet();
+        const llamada = { address: this.tablon(), abi: panalTablonAbi, functionName, args, value };
+        await this.comprobarReserva(que, llamada);
+        const hash = await wallet.writeContract({
+            ...llamada,
+            gas: await this.gasFijo(que, llamada, TOPE_GAS_TABLON),
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        const recibo = await this.publicClient.waitForTransactionReceipt({ hash });
+        if (recibo.status !== 'success')
+            throw new Error(`${que} revirtió (tx ${hash}): se cobró el gas y no cambió nada.`);
+        return { hash, recibo };
+    }
+    /** `approve` exacto a PanalTablon para un pago en token. Nunca infinito. */
+    async aprobarAlTablon(token, importe) {
+        const aFirmar = { address: token, abi: erc20Abi, functionName: 'approve', args: [this.tablon(), importe] };
+        const hash = await this.wallet().writeContract({
+            ...aFirmar,
+            gas: await this.gasFijo('El approve', aFirmar),
+            chain: chainFor(this.network),
+            account: this.account,
+        });
+        await this.esperarExito(hash, 'El approve');
+    }
+    /**
+     * Publica un encargo en el tablón con reglas. El encargo y el anuncio NO se
+     * suben aquí: a la cadena va su keccak256, y los textos se dejan en el
+     * buzón, que los comprueba contra esos hashes.
+     */
+    async postBoardJob(p) {
+        const problema = problemaAlPublicar(p);
+        if (problema)
+            throw new Error(problema);
+        const moneda = p.moneda ?? NATIVE_CURRENCY;
+        const nativa = moneda.toLowerCase() === NATIVE_CURRENCY.toLowerCase();
+        await this.assertFunds(moneda, p.importe, nativa);
+        const taskHash = keccak256(toBytes(p.encargo));
+        const advertHash = keccak256(toBytes(p.anuncio));
+        const seleccion = p.modo === ModoTablon.Seleccion;
+        const params = {
+            taskHash,
+            advertHash,
+            category: p.categoria,
+            currency: moneda,
+            amount: p.importe,
+            workDuration: BigInt(p.plazoEntregaS),
+            expiresAt: BigInt(Math.floor(Date.now() / 1000) + p.caducaEnS),
+            mode: p.modo,
+            applyWindow: BigInt(seleccion ? (p.ventanaOfertasS ?? 0) : 0),
+            chooseWindow: BigInt(seleccion ? (p.ventanaEleccionS ?? 0) : 0),
+            experiencedOnly: p.soloConExperiencia ?? false,
+            relist: p.republicar ?? false,
+            campaignId: p.campana?.id ?? `0x${'0'.repeat(64)}`,
+            campaignCapPerAgent: p.campana?.topePorAgente ?? 0,
+        };
+        if (!nativa)
+            await this.aprobarAlTablon(moneda, p.importe);
+        const { hash, recibo } = await this.firmarEnTablon('La publicación', 'post', [params], nativa ? p.importe : 0n);
+        const [ev] = parseEventLogs({ abi: panalTablonAbi, logs: recibo.logs, eventName: 'JobPosted' });
+        if (!ev)
+            throw new Error(`La publicación salió (tx ${hash}) pero no se encontró el evento JobPosted.`);
+        const jobId = ev.args.jobId;
+        // Los textos van DESPUÉS de la cadena: hasta que el encargo existe, el buzón
+        // no tiene hash con qué comprobarlos. Si fallan, el encargo está pagado y
+        // sin anunciar: se dice y se reintenta con `publishBoardJobTexts`.
+        try {
+            await this.publishBoardJobTexts(jobId, { anuncio: p.anuncio, encargo: p.encargo });
+            return { jobId, txHash: hash, taskHash, advertHash, textosGuardados: true };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            return { jobId, txHash: hash, taskHash, advertHash, textosGuardados: false, error };
+        }
+    }
+    /**
+     * Deja en el buzón el anuncio y el encargo de un encargo ya publicado. Sin
+     * firma: el buzón solo acepta los textos que dan los hashes de la cadena.
+     * Repetirlo no molesta.
+     */
+    async publishBoardJobTexts(jobId, textos) {
+        const base = `${this.buzonUrl}/${this.tablon()}`;
+        for (const [ruta, campo, texto] of [
+            ['anuncio', 'anuncio', textos.anuncio],
+            ['brief', 'brief', textos.encargo],
+        ]) {
+            const { status, text } = await fetchLimited(`${base}/${ruta}/${jobId}`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ [campo]: texto }),
+                timeoutMs: 15_000,
+                maxBytes: 10_000,
+            });
+            if (status !== 200) {
+                throw new Error(`El buzón no aceptó el ${campo === 'brief' ? 'encargo' : 'anuncio'} del #${jobId} (${status}: ${text.slice(0, 160)}).`);
+            }
+        }
+    }
+    /** Lo que se firma para leer del buzón: dirección, firma y caducidad. */
+    async credencialesDeBuzon(mensaje) {
+        const expira = Math.floor(Date.now() / 1000) + VENTANA_FIRMA_S;
+        const firma = await this.wallet().signMessage({ account: this.account, message: mensaje(expira) });
+        return { 'x-panal-address': this.account.address, 'x-panal-signature': firma, 'x-panal-expira': String(expira) };
+    }
+    /**
+     * El anuncio de cada encargo publicado, comprobado contra su `advertHash`.
+     * Un anuncio que no cuadre no se devuelve: el buzón no puede inventarse uno.
+     */
+    async listBoardJobAdverts(opciones = {}) {
+        const [encargos, respuesta] = await Promise.all([
+            this.listBoardJobs({ limit: opciones.limit }),
+            fetchLimited(`${this.buzonUrl}/${this.tablon()}/lista`, { timeoutMs: 15_000, maxBytes: 2_000_000 }),
+        ]);
+        if (respuesta.status !== 200)
+            throw new Error(`El buzón respondió ${respuesta.status} al pedir los anuncios.`);
+        const { anuncios = [] } = JSON.parse(respuesta.text);
+        const porId = new Map(anuncios.map((a) => [a.jobId, a.anuncio]));
+        return encargos.flatMap((j) => {
+            const anuncio = porId.get(j.id.toString());
+            if (typeof anuncio !== 'string')
+                return [];
+            if (keccak256(toBytes(anuncio)).toLowerCase() !== j.advertHash.toLowerCase())
+                return [];
+            return [{ ...j, anuncio }];
+        });
+    }
+    /**
+     * El encargo privado. Lo leen su cliente y su agente en cuanto lo tiene, y
+     * se comprueba contra el `taskHash` de la cadena antes de devolverlo.
+     */
+    async readBoardJobBrief(jobId) {
+        const job = await this.getBoardJob(jobId);
+        const yo = this.account?.address.toLowerCase();
+        if (yo !== job.cliente.toLowerCase() && yo !== job.agente.toLowerCase()) {
+            throw new Error(`El encargo #${jobId} solo lo leen su cliente y el agente que lo tenga.`);
+        }
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/encargo/${jobId}`, {
+            headers: await this.credencialesDeBuzon((e) => tablonEncargoSignMessage(jobId, e)),
+            timeoutMs: 15_000,
+            maxBytes: 1_000_000,
+        });
+        if (status === 404)
+            throw new Error(`El buzón no tiene el encargo #${jobId}: su cliente no llegó a dejarlo.`);
+        if (status !== 200)
+            throw new Error(`El buzón respondió ${status} al pedir el encargo #${jobId}.`);
+        const { brief } = JSON.parse(text);
+        if (typeof brief !== 'string' || keccak256(toBytes(brief)).toLowerCase() !== job.taskHash.toLowerCase()) {
+            throw new Error(`El encargo #${jobId} del buzón no cuadra con el taskHash de la cadena: no se trabaja sobre él.`);
+        }
+        return brief;
+    }
+    /**
+     * Entregar un encargo del tablón con reglas: se deja en el buzón y DESPUÉS
+     * se ancla su hash en el escrow. Al revés, un fallo del buzón dejaría al
+     * cliente con una entrega anclada que no puede descargar.
+     */
+    async deliverBoardJob(jobId, texto) {
+        this.wallet();
+        const job = await this.getBoardJob(jobId);
+        if (job.agente.toLowerCase() !== this.account.address.toLowerCase()) {
+            throw new Error(`El encargo #${jobId} lo tiene ${job.agente}, no tú.`);
+        }
+        if (job.estado !== EstadoTablon.Asignado)
+            throw new Error(`El encargo #${jobId} no está asignado: no hay nada que entregar.`);
+        const hashEntrega = keccak256(toBytes(texto));
+        const cabeceras = await this.credencialesDeBuzon((e) => tablonEntregaSignMessage(jobId, hashEntrega, e));
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/entrega/${jobId}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                entrega: texto,
+                address: cabeceras['x-panal-address'],
+                signature: cabeceras['x-panal-signature'],
+                expira: Number(cabeceras['x-panal-expira']),
+            }),
+            timeoutMs: 30_000,
+            maxBytes: 100_000,
+        });
+        if (status !== 200) {
+            throw new Error(`El buzón no aceptó la entrega del #${jobId} (${status}: ${text.slice(0, 160)}). No se ha anclado nada.`);
+        }
+        return this.deliverResult(job.escrowTaskId, texto);
+    }
+    /**
+     * La entrega, para su cliente. Se comprueba contra el `resultHash` anclado
+     * en el escrow: el buzón no puede cambiarla.
+     */
+    async readBoardJobResult(jobId) {
+        const job = await this.getBoardJob(jobId);
+        if (this.account?.address.toLowerCase() !== job.cliente.toLowerCase()) {
+            throw new Error(`La entrega del #${jobId} solo la descarga su cliente.`);
+        }
+        const { status, text } = await fetchLimited(`${this.buzonUrl}/${this.tablon()}/result/${jobId}`, {
+            headers: await this.credencialesDeBuzon((e) => tablonResultadoSignMessage(jobId, e)),
+            timeoutMs: 15_000,
+            maxBytes: 1_000_000,
+        });
+        if (status === 404)
+            throw new Error(`El encargo #${jobId} todavía no tiene entrega en el buzón.`);
+        if (status !== 200)
+            throw new Error(`El buzón respondió ${status} al pedir la entrega del #${jobId}.`);
+        const { resultText } = JSON.parse(text);
+        const tarea = await this.getTask(job.escrowTaskId);
+        if (typeof resultText !== 'string' || keccak256(toBytes(resultText)).toLowerCase() !== tarea.resultHash.toLowerCase()) {
+            throw new Error(`La entrega del #${jobId} no cuadra con el resultHash anclado en el escrow.`);
+        }
+        return resultText;
+    }
+    /** Coger un encargo inmediato. Antes de firmar pregunta si se puede, y por qué no. */
+    async takeBoardJob(jobId) {
+        this.wallet();
+        const { ok, motivo } = await this.canTakeBoardJob(this.account.address, jobId);
+        if (!ok)
+            throw new Error(`No se puede coger el encargo #${jobId}: ${motivo}.`);
+        const { hash } = await this.firmarEnTablon('Coger el encargo', 'take', [jobId]);
+        return { txHash: hash, escrowTaskId: (await this.getBoardJob(jobId)).escrowTaskId };
+    }
+    /**
+     * Ofertar en un encargo de selección: precio y plazo (0 = el del encargo).
+     * Volver a llamar cambia la oferta. Un precio por encima del presupuesto vale:
+     * solo lo puede elegir el cliente, poniendo la diferencia.
+     */
+    async offerOnBoardJob(jobId, precio, plazoEntregaS = 0) {
+        this.wallet();
+        const { ok, motivo } = await this.canTakeBoardJob(this.account.address, jobId);
+        if (!ok)
+            throw new Error(`No se puede ofertar en el encargo #${jobId}: ${motivo}.`);
+        return (await this.firmarEnTablon('La oferta', 'applyFor', [jobId, precio, BigInt(plazoEntregaS)])).hash;
+    }
+    async withdrawBoardOffer(jobId) {
+        return (await this.firmarEnTablon('Retirar la oferta', 'withdrawOffer', [jobId])).hash;
+    }
+    /**
+     * El cliente elige una oferta. Si pide más que el presupuesto, se manda la
+     * diferencia exacta (en $PANAL, con su `approve` exacto); si pide menos, la
+     * diferencia queda para cobrar con `claimBoardRefund`.
+     */
+    async chooseBoardOffer(jobId, agent) {
+        const [job, ofertas] = await Promise.all([this.getBoardJob(jobId), this.getBoardOffers(jobId)]);
+        const oferta = ofertas.find((o) => o.agente.toLowerCase() === agent.toLowerCase());
+        if (!oferta)
+            throw new Error(`${agent} no tiene oferta en el encargo #${jobId}.`);
+        const diferencia = oferta.precio > job.importe ? oferta.precio - job.importe : 0n;
+        const nativa = job.moneda.toLowerCase() === NATIVE_CURRENCY.toLowerCase();
+        if (diferencia > 0n) {
+            await this.assertFunds(job.moneda, diferencia, nativa);
+            if (!nativa)
+                await this.aprobarAlTablon(job.moneda, diferencia);
+        }
+        const { hash } = await this.firmarEnTablon('Elegir la oferta', 'choose', [jobId, getAddress(agent)], nativa ? diferencia : 0n);
+        return { txHash: hash, escrowTaskId: (await this.getBoardJob(jobId)).escrowTaskId };
+    }
+    /** Asignar un encargo de selección cuyo cliente no eligió. Lo puede llamar cualquiera. */
+    async autoAssignBoardJob(jobId) {
+        return (await this.firmarEnTablon('La asignación', 'autoAssign', [jobId])).hash;
+    }
+    /** El cliente aprueba la entrega (1-5) y el encargo se cierra. */
+    async approveBoardJob(jobId, rating) {
+        if (!Number.isInteger(rating) || rating < 1 || rating > 5)
+            throw new Error('La valoración es un entero de 1 a 5.');
+        return (await this.firmarEnTablon('La aprobación', 'approve', [jobId, rating])).hash;
+    }
+    async disputeBoardJob(jobId) {
+        return (await this.firmarEnTablon('La disputa', 'dispute', [jobId])).hash;
+    }
+    /**
+     * Cerrar las cuentas de un encargo. Si el escrow se puede adelantar
+     * —cancelar sin entrega pasado el plazo, liberar a las 72 h, devolver una
+     * disputa atascada— lo hace primero. Lo puede llamar cualquiera.
+     */
+    async settleBoardJob(jobId) {
+        return (await this.firmarEnTablon('El cierre', 'settle', [jobId])).hash;
+    }
+    /** El cliente retira un encargo que nadie tiene todavía. */
+    async withdrawBoardJob(jobId) {
+        return (await this.firmarEnTablon('Retirar el encargo', 'withdrawJob', [jobId])).hash;
+    }
+    async expireBoardJob(jobId) {
+        return (await this.firmarEnTablon('La caducidad', 'expire', [jobId])).hash;
+    }
+    /** Cobrar lo que PanalTablon le debe a esta cuenta en una moneda. */
+    async claimBoardRefund(currency = NATIVE_CURRENCY) {
+        this.wallet();
+        const importe = await this.getBoardRefund(this.account.address, currency);
+        if (importe === 0n)
+            throw new Error('No hay nada que cobrar en esa moneda.');
+        const { hash } = await this.firmarEnTablon('El cobro', 'claim', [currency]);
+        return { txHash: hash, importe };
+    }
+    /** Las categorías del agente en el tablón: hasta tres, sin repetir. */
+    async setBoardCategories(categorias) {
+        if (categorias.length > MAX_CATEGORIAS)
+            throw new Error(`Hasta ${MAX_CATEGORIAS} categorías.`);
+        if (new Set(categorias).size !== categorias.length)
+            throw new Error('Hay categorías repetidas.');
+        if (categorias.some((c) => !Number.isInteger(c) || c < 0 || c > 255))
+            throw new Error('Las categorías van de 0 a 255.');
+        return (await this.firmarEnTablon('Las categorías', 'setCategories', [categorias])).hash;
+    }
     async assertFunds(currency, amount, isNative) {
         const owner = this.account.address;
         const balance = isNative

package/dist/ejemplos.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Panal — los encargos de ejemplo de un agente.
+ *
+ * Un token más de los que viven en el `metadataURI` on-chain, junto a `bot:`,
+ * los de marca, los de nivel y el de tipo:
+ *
+ *     Lint · Revisa código · solidity · bot:https://… · ejemplo:Revisa este contrato ERC-20
+ *
+ * POR QUÉ EXISTE
+ *
+ * Al contratar, debajo de la caja del encargo salían cuatro ejemplos fijos
+ * («Audita este contrato», «Resume este PDF»…) para CUALQUIER agente: a uno de
+ * traducción le proponían auditar un contrato. Se quitaron. Lo que los
+ * sustituye son los del propio agente, escritos por quien sabe qué hace.
+ *
+ * POR QUÉ EN LA CADENA Y NO SOLO EN LA FICHA DEL BOT
+ *
+ * Por lo mismo que los niveles (ver `niveles.ts`): así los escribe también
+ * quien no programa —una persona que trabaja desde el buzón no tiene servidor
+ * donde ponerlos—, se editan desde el panel o desde la app, y siguen ahí con
+ * el bot caído. La ficha del bot los repite traducidos (`examples`), porque la
+ * cadena guarda una sola versión y la traducción solo puede vivir allí.
+ *
+ * POR QUÉ LA CLAVE SE RECONOCE TAN ESTRICTA
+ *
+ * Un ejemplo es texto libre, así que no hay valor que validar como el precio
+ * de un nivel. Lo que separa un token de una frase es la forma de la clave:
+ * `ejemplo:` en minúsculas y pegada al texto, que es como la escribe
+ * `componerEjemplo`. Una descripción que diga «Ejemplo: traduzco tu web» —con
+ * mayúscula, o con espacio tras los dos puntos— se queda como descripción. Si
+ * bastara con ver la palabra, esa frase desaparecería de la ficha de su dueño
+ * y saldría como un botón.
+ *
+ * LO QUE UN EJEMPLO NO ES
+ *
+ * No es un encargo ya escrito que se pague tal cual. Al pulsarlo se copia en
+ * la caja para que el cliente lo complete con lo suyo —el contrato, el texto,
+ * los datos—, y lo que se ancla en la cadena es lo que el cliente envía.
+ */
+/** Cuántos ofrece el formulario, y cuántos se leen. Más no caben bajo la caja. */
+export declare const EJEMPLOS_EDITABLES = 3;
+/** Tope de cada ejemplo, en caracteres. Una frase, no un encargo. */
+export declare const MAX_EJEMPLO = 140;
+/**
+ * `ejemplo:Revisa este contrato` → `'Revisa este contrato'`, o `null` si el
+ * segmento no es un ejemplo.
+ *
+ * Devolver `null` es lo normal: por aquí pasan TODOS los segmentos de la
+ * ficha, incluida la descripción libre del agente.
+ */
+export declare function leerEjemploDeSegmento(segmento: string): string | null;
+/** true si este segmento es un ejemplo. Para que los lectores de ficha lo aparten. */
+export declare function esTokenDeEjemplo(segmento: string): boolean;
+/**
+ * Los ejemplos que un agente publica en la cadena, en el orden en que los
+ * escribió. `[]` es lo normal.
+ *
+ * Los repetidos se quedan en uno: dos botones iguales no son dos ideas.
+ */
+export declare function leerEjemplosDeMetadata(metadataURI: string | null | undefined): string[];
+/**
+ * Qué le pasa a lo que alguien escribe, para poder decírselo.
+ *
+ * `null` es que está bien o que está vacío. Un «·» partiría la ficha en dos y
+ * el trozo de después saldría como una skill; demasiado largo se recortaría
+ * sin avisar. En los dos casos se firmaría algo distinto de lo que su dueño
+ * ve, así que se canta antes.
+ */
+export declare function falloDeEjemplo(texto: string): 'separador' | 'largo' | null;
+/**
+ * El texto → su segmento, o `null` si no se puede escribir tal cual.
+ *
+ * `null` en vez de arreglarlo: quien llama tiene que enseñar el error, no
+ * firmar una ficha que su dueño no reconoce. Vacío también es `null`, y eso
+ * es lo normal: el formulario enseña tres y casi nadie rellena las tres.
+ */
+export declare function componerEjemplo(texto: string): string | null;
+/**
+ * Los ejemplos de la ficha que sirve el agente (`examples`), ya saneados.
+ *
+ * Esa ficha la escribe un servidor ajeno: se aceptan solo cadenas, se limpian
+ * y se recortan, y se leen como mucho los mismos que caben en la cadena.
+ */
+export declare function leerEjemplos(card: unknown): string[];
+/**
+ * Los de la cadena, con el texto —traducido— de la ficha cuando cuadra.
+ *
+ * La cadena guarda una sola versión, en el idioma de su dueño. La ficha que
+ * sirve el agente los repite traducidos al idioma pedido, en el mismo orden.
+ * Se usan los de la ficha solo si son LOS MISMOS en número: si no cuadran, la
+ * ficha está desfasada respecto a la cadena (el agente la relee cada pocos
+ * minutos) y se enseñan los de la cadena, que son los vigentes.
+ *
+ * Sin nada en la cadena valen los de la ficha: un ejemplo no mueve dinero, y
+ * un agente puede declararlos solo en su código.
+ */
+export declare function conEjemplosDeLaFicha(enCadena: string[], deLaFicha: string[]): string[];