@nyx5/nyx5 0.1.0 → 0.2.0

package/src/correo/estafeta.js

@@ -23,6 +23,9 @@ import { Resolver, parseAddress } from './resolver.js';
 import { validateEnvelope, applyInboxPolicy, RateLimiter } from './politica.js';
 import { generateSigningKeys, signObject, verifyObject, signBytes, verifyBytes, canonical, uuid, unb64u, sha256hex } from '../nucleo/crypto.js';
 import { Libro, MEDIA, LibroError } from '../libro/libro.js';
+import { veredicto, pruebasDe, pruebasDisponibles } from '../libro/verifica.js';
+import { contratoPublico, ACP } from '../libro/contratos.js';
+import { Tareas } from '../libro/tareas.js';
 import { APP_HTML } from '../plataformas/app-html.js';
 import { SPEC_HTML, LLMS_TXT } from '../plataformas/spec-html.js';
 import { HOME_HTML } from '../plataformas/home-html.js';
@@ -38,7 +41,7 @@ export class Estafeta {
     port = 4000, host = '127.0.0.1', publicUrl,
     hosts = {}, fetchImpl = globalThis.fetch,
     policy = {}, retry = {}, workerIntervalMs = 1000, libro = {},
-    index = {}, email = {},
+    index = {}, email = {}, verifica = {}, eventos = true, tareas = {},
     extensions = null,
     log = (...a) => console.log(`[estafeta ${domain}]`, ...a),
   }) {
@@ -55,6 +58,12 @@ export class Estafeta {
     this.retry = { baseMs: 1000, maxMs: 60_000, giveUpMs: 3 * 24 * 3600 * 1000, ...retry };
     this.workerIntervalMs = workerIntervalMs;
     this.index = { enabled: false, crawlMinutes: 15, maxHouses: 500, ...index };
+    // verifica@: el evaluador de referencia. `enabled` lo enciende; `maxPorTick` acota lo que
+    // el cron hace en una pasada para no comerse el minuto entero verificando.
+    this.verifica = { enabled: true, maxPorTick: 10, timeoutMs: 10_000, ...verifica };
+    this.eventos = eventos !== false;
+    // Trabajo sembrado: la casa es el primer comprador. Sin catálogo, apagado.
+    this.tareas = new Tareas(tareas);
     // Puente de correo: entrada siempre disponible si la casa la enciende; salida solo si hay proveedor.
     // `email.provider` es una función async(payload) (ver src/puentes/email.js); sin ella, la salida queda pendiente.
     this.email = { enabled: !!(email.enabled || email.provider), provider: email.provider || null };
@@ -114,9 +123,27 @@ export class Estafeta {
     //   postmaster@ -> avisos de entrega y rebotes    libro@ -> operaciones y recibos del Libro
     if (!await this.store.getAgent('postmaster')) await this.registerAgent({ local: 'postmaster', sig: this.keys.sig, capabilities: { accepts: [] }, inbox: { policy: 'allowlist', allowlist: [] } });
     if (!await this.store.getAgent('libro')) await this.registerAgent({ local: 'libro', sig: this.keys.sig, capabilities: { accepts: [MEDIA.op], libro: { fee_bps: this.libro.feeBps, ops: this.libro.ops } }, inbox: { policy: 'open' } });
+    // verifica@ — el evaluador de referencia de la casa. Tres pruebas deterministas y nada
+    // más: un verificador que se equivoca castiga inocentes. Declara en su tarjeta cuáles
+    // puede correr en ESTE runtime (en el edge no hay shell), para no prometer lo que no hace.
+    if (this.verifica.enabled && !await this.store.getAgent('verifica')) {
+      await this.registerAgent({ local: 'verifica', sig: this.keys.sig, capabilities: { accepts: [MEDIA.op], verifica: { pruebas: pruebasDisponibles() }, listed: true }, inbox: { policy: 'open' } });
+    // tareas@ — el mostrador del trabajo sembrado. Existe solo si la casa publicó tareas.
+    if (this.tareas.enabled && !await this.store.getAgent('tareas')) {
+      await this.registerAgent({ local: 'tareas', sig: this.keys.sig, capabilities: { accepts: [MEDIA.cotizacion], tareas: { por_agente_dia: this.tareas.porAgenteDia }, listed: true }, inbox: { policy: 'open' } });
+    }
+    }
   }
-  isSystem(local) { return local === 'postmaster' || local === 'libro'; }
-  static RESERVED = new Set(['postmaster', 'libro', 'casa', 'admin', 'root', 'abuse', 'security', 'hostmaster', 'noreply', 'no-reply', 'support', 'estafeta', 'nyx5', 'indice']);
+  // Instrumentación: nombre, fecha, actor y números. Nunca contenido de sobres ni datos del
+  // humano. Un fallo al registrar un evento JAMÁS puede voltear la operación que lo produjo:
+  // medir es secundario, mover tokens no.
+  async _evento(name, actor, data = {}) {
+    if (!this.eventos || !this.store.putEvent) return;
+    try { await this.store.putEvent({ id: uuid(), name, ts: iso(), actor: actor || null, data }); }
+    catch (e) { this.log(`evento ${name} no registrado: ${e.message}`); }
+  }
+  isSystem(local) { return ['postmaster', 'libro', 'verifica', 'tareas'].includes(local); }
+  static RESERVED = new Set(['postmaster', 'libro', 'verifica', 'tareas', 'casa', 'admin', 'root', 'abuse', 'security', 'hostmaster', 'noreply', 'no-reply', 'support', 'estafeta', 'nyx5', 'indice']);
 
   // ---------- servicio de registro ----------
   // Invitaciones: la casa emite códigos con usos y vencimiento; un agente los presenta al inscribirse.
@@ -167,7 +194,7 @@ export class Estafeta {
   }
 
   // ---------- agentes ----------
-  async registerAgent({ local, sig, enc = null, capabilities = {}, inbox = { policy: 'open' }, webhook = null, valid_until = null, delegation = null, welcome = null }) {
+  async registerAgent({ local, sig, enc = null, capabilities = {}, inbox = { policy: 'open' }, webhook = null, notify_email = null, valid_until = null, delegation = null, welcome = null }) {
     local = String(local).toLowerCase();
     const address = `${local}@${this.domain}`;
     parseAddress(address);
@@ -214,11 +241,11 @@ export class Estafeta {
     let creado = true;
     if (!prev) {
       creado = await (this.store.putAgentIfAbsent
-        ? this.store.putAgentIfAbsent(local, { ...card, webhook })
-        : (this.store.putAgent(local, { ...card, webhook }), true));
+        ? this.store.putAgentIfAbsent(local, { ...card, webhook, notify_email })
+        : (this.store.putAgent(local, { ...card, webhook, notify_email }), true));
       if (!creado) throw Object.assign(new Error('ese nombre acaba de ser tomado; solo su dueño o la casa pueden actualizarlo'), { status: 409 });
     } else {
-      await this.store.putAgent(local, { ...card, webhook });
+      await this.store.putAgent(local, { ...card, webhook, notify_email });
     }
     const gift = welcome ?? this.libro.welcome;
     if (creado && !prev && !this.isSystem(local) && !delegation && gift > 0) await this.libro.topup(address, gift, 'regalo de bienvenida', { agent: address });
@@ -233,7 +260,7 @@ export class Estafeta {
     if (!Estafeta.validLocal(local)) return null;
     const rec = await this.store.getAgent(local);
     if (!rec) return null;
-    const { webhook, ...card } = rec;
+    const { webhook, notify_email, ...card } = rec;
     return card;
   }
 
@@ -302,6 +329,7 @@ export class Estafeta {
     for (const job of due) await this._deliver(job);
     await this.store.pruneNonces?.(now() - 600_000);
     if (this.index.enabled) await this._indexCrawlIfDue();
+    if (this.verifica.enabled) await this._verificarPendientes();
     await this.flushPushes();
   }
   async _deliver(job) {
@@ -375,6 +403,40 @@ export class Estafeta {
     await this.store.removeJob(job.id); await this._outbox(job, { delivered: delivered.length, failed: failed.length });
   }
 
+  // ----- verifica@: escrows que declararon prueba y nombraron árbitro a la casa -----
+  // El asiento no se mueve por lo que alguien dijo, sino por lo que la prueba devolvió. Y si
+  // la prueba no pudo correr (red caída, timeout), NO se decide: el escrow queda como estaba.
+  async _verificarPendientes() {
+    const arbitro = `verifica@${this.domain}`;
+    let contratos;
+    try { contratos = await this.store.libroListContracts(); } catch { return; }
+    const candidatos = contratos.filter((c) => c.kind === 'escrow' && ['held', 'delivered'].includes(c.state) && c.arbiter === arbitro && pruebasDe(c));
+    for (const c of candidatos.slice(0, this.verifica.maxPorTick)) {
+      // Solo se verifica lo que ya se declaró entregado, salvo que el contrato pida verificar
+      // desde el arranque (terms.verify_on: 'accept'), útil para un endpoint que ya debía estar en pie.
+      if (c.state === 'held' && (c.terms?.verify_on || 'deliver') !== 'accept') continue;
+      const v = await veredicto(pruebasDe(c), { fetchImpl: this.fetch, timeoutMs: this.verifica.timeoutMs, entregado: c.evidence ?? null, entregadoSha256: c.evidence_sha256 ?? null });
+      if (v.indeciso) { this.log(`verifica ${c.id}: sin veredicto (${v.razon})`); continue; }
+      // La decisión viaja como sobre firmado a libro@ y entra por `inbound`, la MISMA puerta
+      // que usa cualquier agente (invariante 2). No se toca el Libro por dentro: si la firma
+      // de verifica@ no verifica, la casa se rechaza a sí misma. El veredicto va en el
+      // contenido, así que el porqué queda escrito y auditable en el contrato.
+      const env = signObject({
+        nyx5: '1', id: uuid(), from: `verifica@${this.domain}`, to: [`libro@${this.domain}`],
+        created: iso(), expires: null, thread: c.id, in_reply_to: null, type: 'task',
+        content: { media: MEDIA.op, body: { op: v.pasa ? 'release' : 'refund', contract: c.id, note: v.razon, veredicto: { pasa: v.pasa, razon: v.razon, resultados: v.resultados } } },
+      }, this.keys);
+      // Se espera el resultado antes de mirar el siguiente: así el estado ya cambió y este
+      // contrato no vuelve a elegirse en el mismo tick ni en el siguiente.
+      const r = await this.inbound(env);
+      if (!r.ok) this.log(`verifica ${c.id}: la casa rechazó su propia decisión (${r.code}): ${r.reason}`);
+      else {
+        this.log(`verifica ${c.id}: ${v.pasa ? 'libera' : 'devuelve'} — ${v.razon}`);
+        await this._evento('verificado', `verifica@${this.domain}`, { contract: c.id, pasa: v.pasa, pruebas: (pruebasDe(c) || []).map((x) => x.type), amount: c.amount });
+      }
+    }
+  }
+
   // Sobres emitidos por los agentes de sistema (postmaster@, libro@), firmados con la clave del dominio.
   // Destinatarios locales: directo al buzón. Remotos: por la cola, como cualquier envío.
   async _systemSend(fromLocal, to, { type = 'receipt', content, thread = null, in_reply_to = null, deliverAfter = null }) {
@@ -394,6 +456,55 @@ export class Estafeta {
     return env;
   }
 
+  // ----- tareas@: la casa toma el lado comprador de una tarea sembrada -----
+  // El agente manda su cotización firmada; la casa la compara contra el catálogo publicado y,
+  // si coincide y hay cupo, la acepta operando el Libro como cualquier comprador. La casa NO
+  // firma por el agente: el vendedor de ese escrow es él, con su propia llave.
+  async _tomarTarea(env, senderCard) {
+    const q = env.content?.body;
+    if (env.content?.media !== MEDIA.cotizacion || q?.tipo !== 'cotizacion') {
+      return { ok: false, code: 400, reason: `tareas@ acepta una cotización (${MEDIA.cotizacion}) por la tarea publicada; mira GET /tareas` };
+    }
+    const tarea = this.tareas.tarea(q.terms?.seed_task);
+    if (!tarea) return { ok: false, code: 404, reason: `no hay una tarea sembrada con id ${q.terms?.seed_task}. Las publicadas están en GET /tareas` };
+    if (q.seller !== env.from) return { ok: false, code: 403, reason: 'el vendedor de la cotización debe ser quien la manda' };
+    if (q.buyer !== `tareas@${this.domain}`) return { ok: false, code: 400, reason: `la cotización debe ir dirigida a tareas@${this.domain}` };
+    const encaja = this.tareas.coincide(q, tarea, { arbitro: `verifica@${this.domain}` });
+    if (!encaja.ok) return { ok: false, code: 409, reason: encaja.reason };
+    const contratos = await this.store.libroListContracts();
+    const cupo = this.tareas.cupo(tarea, env.from, contratos);
+    // 409, no 429: un 429 es transitorio y la estafeta lo reintentaría durante tres días, así
+    // que el agente se quedaría esperando sin saber por qué. Sin cupo, se le dice ahora.
+    if (!cupo.ok) return { ok: false, code: 409, reason: cupo.reason };
+
+    // La casa acepta con un sobre firmado a libro@, por la misma puerta que todos.
+    const aceptacion = signObject({
+      nyx5: '1', id: uuid(), from: `tareas@${this.domain}`, to: [`libro@${this.domain}`],
+      created: iso(), expires: null, thread: q.id, in_reply_to: env.id, type: 'task',
+      content: { media: MEDIA.op, body: { op: 'accept', quote: q } },
+    }, this.keys);
+    const r = await this.inbound(aceptacion);
+    if (!r.ok) return { ok: false, code: r.code || 409, reason: `la casa no pudo tomar la tarea: ${r.reason}` };
+    const contrato = Object.values(r.results || {})[0]?.contract || null;
+    this.log(`tarea ${tarea.id} tomada por ${env.from} (contrato ${contrato?.id})`);
+    await this._evento('seed_task_taken', env.from, { task: tarea.id, contract: contrato?.id || null, price: tarea.price });
+    return { ok: true, code: 202, result: { contract: contratoPublico(contrato), task: tarea.id }, recibos: [] };
+  }
+
+  // Los cinco eventos que dicen si el mecanismo se está ejerciendo de verdad, leídos del
+  // resultado de la op (no de lo que alguien dijo que iba a pasar).
+  async _eventoDeOp(env, result) {
+    if (!this.eventos) return;
+    const op = env.content?.body?.op;
+    const c = result?.contract;
+    const m = result?.mandate;
+    if (op === 'mandate' && m) return this._evento('mandate_created', m.grantor, { mandate: m.id, grantee: m.grantee, cap: m.cap, parent: m.parent || null });
+    if (op === 'accept' && c) return this._evento('first_quote', c.buyer, { contract: c.id, kind: c.kind, amount: c.amount, seller: c.seller });
+    if (op === 'release' && c?.kind === 'escrow') return this._evento('escrow_released', c.seller, { contract: c.id, amount: c.amount, by: env.from, arbitrado: env.from === `verifica@${this.domain}` });
+    if (op === 'refund' && c) return this._evento('escrow_refunded', c.buyer, { contract: c.id, amount: c.amount, by: env.from });
+    if (op === 'forfeit' && c) return this._evento('bond_forfeited', c.seller, { contract: c.id, amount: c.amount, by: env.from, vouchee: c.vouchee || null });
+  }
+
   // Avisos del postmaster al remitente (rebotes y acuses de entrega). Llevan el hash del sobre original.
   async _notify(job, to, status, reason) {
     await this._systemSend('postmaster', [job.envelope.from], {
@@ -457,6 +568,14 @@ export class Estafeta {
           for (const rc of r.recibos || []) recibosPendientes.push(rc);
           for (const av of r.avisos || []) avisosPendientes.push(av);
           results[to] = r.result;
+          if (!r.duplicate) await this._eventoDeOp(env, r.result);
+        } else if (local === 'tareas' && this.tareas.enabled) {
+          // Mostrador del trabajo sembrado: el agente cotiza la tarea publicada y la casa la
+          // acepta si coincide EXACTAMENTE con el catálogo y hay cupo. Nada se negocia aquí.
+          const r = await this._tomarTarea(env, senderCard);
+          if (!r.ok) { rejected.push({ to, code: r.code, reason: r.reason }); continue; }
+          for (const rc of r.recibos || []) recibosPendientes.push(rc);
+          results[to] = r.result;
         } else if (p.stamp) {
           // Una estampilla paga UN buzón: el sobre declara un monto, no un monto por destinatario.
           if (stampUsed) { rejected.push({ to, code: 402, reason: 'la estampilla del sobre ya se usó en otro destinatario' }); continue; }
@@ -497,7 +616,7 @@ export class Estafeta {
         seen: { id: env.id, rec: { from: env.from, accepted: union } },
         mails, libro: libroBundles,
       });
-      for (const m of mails) this._push(m.local, env);
+      for (const m of mails) { this._push(m.local, env); this._notifyEmail(m.local, env); }
     }
     for (const rc of recibosPendientes) await this._systemSend('libro', rc.to, { in_reply_to: env.id, thread: rc.thread || env.thread || null, content: { media: MEDIA.recibo, body: rc.body } });
     // Avisos de plazo: sobres del Libro programados para el futuro (un escrow que llega a su
@@ -520,6 +639,25 @@ export class Estafeta {
     this._pushes.push(pendiente);
     return pendiente;
   }
+  // Aviso por email: si el agente registró `notify_email` y la casa tiene proveedor de salida, le
+  // llega un correo cuando alguien le escribe un mensaje real. No avisa por recibos del Libro ni
+  // rebotes del postmaster (ruido), ni por lo que el propio destinatario se manda por el puente.
+  _notifyEmail(local, env) {
+    if (!this.email.provider) return;
+    const pendiente = Promise.resolve(this.store.getAgent(local)).then(async (rec) => {
+      if (!rec?.notify_email) return;
+      let fromLocal = ''; try { fromLocal = parseAddress(env.from).local; } catch { /* remitente de pasarela */ }
+      if (env.type === 'receipt' || fromLocal === 'libro' || fromLocal === 'postmaster') return;
+      const emailOrig = env.extensions?.['urn:nyx5:ext:email']?.from;
+      if (emailOrig && emailOrig === rec.notify_email) return; // no te avises de tu propio correo
+      const quien = emailOrig || env.from;
+      await this.emailOut({ fromAgent: `${local}@${this.domain}`, to: rec.notify_email,
+        subject: `Tienes un mensaje nuevo en Nyx5 de ${quien}`,
+        text: `${quien} le escribió a ${local}@${this.domain}.\n\nÁbrelo en tu buzón: https://${this.domain}/app\n\n(Este es un aviso automático; el contenido está en tu buzón, no en este correo.)` });
+    }).catch((e) => this.log(`notify_email ${local} falló: ${e.message}`));
+    this._pushes.push(pendiente);
+    return pendiente;
+  }
   // Espera los avisos en vuelo y vacía la lista.
   flushPushes() { const p = this._pushes; this._pushes = []; return Promise.allSettled(p); }
 
@@ -628,6 +766,14 @@ export class Estafeta {
       if (rx.method === 'GET' && path === '/llms.txt') return { status: 200, body: LLMS_TXT, contentType: 'text/plain; charset=utf-8' };
       if (rx.method === 'GET' && path === '/.well-known/nyx5.json') return send(200, await this.domainCard());
       let m;
+      // Reputación = una consulta al libro. Es PÚBLICA a propósito: sirve justamente para que
+      // un desconocido decida antes de contratar, igual que la tarjeta. No expone contenido ni
+      // contrapartes: solo cuántas entregas, cuántas fianzas y cuántos tokens se movieron.
+      if (rx.method === 'GET' && (m = /^\/agents\/([^/]+)\/historial$/.exec(path))) {
+        const local = decodeURIComponent(m[1]).toLowerCase();
+        if (!(await this.store.getAgent(local))) return send(404, { reason: 'agente inexistente' });
+        return send(200, await this.libro.historial(`${local}@${this.domain}`));
+      }
       if (rx.method === 'GET' && (m = /^\/agents\/([^/]+)$/.exec(path))) {
         const card = await this.agentCard(decodeURIComponent(m[1]).toLowerCase());
         return card ? send(200, card) : send(404, { reason: 'agente inexistente' });
@@ -661,6 +807,7 @@ export class Estafeta {
         const { signature: _s, ts: _t, invite: _i, _welcome, ...clean } = body;
         const card = await this.registerAgent({ ...clean, welcome: _welcome });
         this.log(`registro ${card.address} via ${via}`);
+        if (!card.delegation) await this._evento('join', card.address, { via, listed: card.capabilities?.listed === true });
         return send(201, { ...card, registered_via: via });
       }
       if (rx.method === 'POST' && path === '/invitations') {
@@ -718,13 +865,35 @@ export class Estafeta {
         const c = await this.store.libroGetContract(decodeURIComponent(m[1]));
         if (!c) return send(404, { reason: 'contrato inexistente' });
         if (![c.seller, c.buyer, c.verifier, c.arbiter].includes(who.address)) return send(403, { reason: 'no eres parte' });
-        return send(200, c);
+        return send(200, contratoPublico(c));
       }
       if (rx.method === 'POST' && path === '/libro/topup') {
         if ((rx.headers.authorization || '') !== `Bearer ${this.adminToken}`) return send(401, { reason: 'solo la casa carga saldo' });
         const { account, amount, concept } = rx.body || {};
         return send(201, await this.libro.topup(account, amount, concept || 'carga de la casa'));
       }
+      // Los eventos son de la casa: dicen cuántos agentes llegaron y si el mecanismo se ejerce.
+      // No son públicos porque juntos dibujan la actividad de la casa; el historial de cada
+      // agente, que es lo que un desconocido necesita, sí lo es.
+      // El catálogo es público: un agente que acaba de unirse tiene que poder leer qué hay
+      // que hacer, cuánto paga y con qué prueba se comprueba, sin autenticarse.
+      if (rx.method === 'GET' && path === '/tareas') {
+        if (!this.tareas.enabled) return send(404, { reason: 'esta casa no siembra trabajo' });
+        return send(200, {
+          mostrador: `tareas@${this.domain}`, arbitro: `verifica@${this.domain}`,
+          por_agente_dia: this.tareas.porAgenteDia,
+          como: `cotiza la tarea a tareas@${this.domain} como escrow, con arbiter=verifica@${this.domain} y terms exactamente iguales a los publicados`,
+          tareas: this.tareas.publicadas().map((t) => ({ ...t, terms: this.tareas.terminosDe(this.tareas.tarea(t.id)) })),
+        });
+      }
+      if (rx.method === 'GET' && path === '/eventos') {
+        if ((rx.headers.authorization || '') !== `Bearer ${this.adminToken}`) return send(401, { reason: 'solo la casa lee sus eventos' });
+        const p = Object.fromEntries(rx.query);
+        const eventos = (await this.store.listEvents?.({ name: p.name || null, since: p.since || null, limit: Number(p.limit || 500) })) || [];
+        const conteo = {};
+        for (const e of eventos) conteo[e.name] = (conteo[e.name] || 0) + 1;
+        return send(200, { conteo, eventos });
+      }
       if (rx.method === 'GET' && path === '/libro/diario') {
         if ((rx.headers.authorization || '') !== `Bearer ${this.adminToken}`) return send(401, { reason: 'solo la casa lee el diario completo' });
         return send(200, { balances: (await this.store.libroState()).balances, journal: await this.libro.journal() });

package/src/correo/unirse.js

@@ -0,0 +1,117 @@
+// Nyx5/1 — Unirse: un agente entra a una casa en un solo paso, sin humano.
+//
+// `join` acuña la llave en la máquina del agente, descubre la casa por DNS/well-known,
+// registra el nombre (prueba de posesión), deja un primer sobre en el propio buzón y
+// devuelve todo lo que un agente necesita para seguir solo: dirección, archivo de llaves,
+// bloque MCP, saldo y el historial que otros van a leer.
+//
+// No es una cuenta: no hay correo, ni contraseña, ni nada del humano. La única fricción
+// deliberada del sistema aparece después, en `mandate`, cuando alguien pone presupuesto.
+
+import { Agent } from './agente.js';
+import { Resolver, parseAddress } from './resolver.js';
+import { Estafeta } from './estafeta.js';
+
+// Sufijo corto y legible; con 4 bytes hay 4.294.967.296 combinaciones por raíz.
+const sufijo = () => Buffer.from(crypto.getRandomValues(new Uint8Array(4))).toString('hex');
+const NOMBRE_OK = /^[a-z0-9]([a-z0-9-]{1,30}[a-z0-9])?$/;
+
+// Un nombre por defecto que no colisiona y no miente sobre quién es: la raíz viene del
+// runtime si se conoce (claude, cursor…), y el sufijo la vuelve única.
+export function nombreSugerido(raiz = 'agente') {
+  const base = String(raiz).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 20) || 'agente';
+  return `${base}-${sufijo()}`;
+}
+
+export function bloqueMcp({ address, keyfile, comando = 'npx', args = ['-y', '@nyx5/nyx5'] }) {
+  return {
+    mcpServers: {
+      nyx5: { command: comando, args: [...args, 'mcp', '--agent', keyfile], env: {} },
+    },
+    _agent: address,
+  };
+}
+
+/**
+ * Une un agente a una casa en un paso.
+ * @param {object} opts
+ * @param {string} [opts.house='nyx5.com']  dominio de la casa
+ * @param {string} [opts.name]              nombre local; si falta, se sugiere uno único
+ * @param {string} [opts.runtime]           raíz del nombre sugerido (claude, cursor…)
+ * @param {string} [opts.invite]            código, si la casa no está abierta
+ * @param {boolean} [opts.listed=false]     aparecer en el directorio (opt-in, invariante del proyecto)
+ * @param {object} [opts.capabilities]      { mcp, a2a, skills… } para la tarjeta
+ * @param {number} [opts.intentos=5]        reintentos ante colisión de nombre
+ * @returns {Promise<object>} { address, keys, card, balance, historial, mcp, first }
+ */
+export async function join({
+  house = 'nyx5.com', name = null, runtime = 'agente', invite = null, listed = false,
+  capabilities = {}, intentos = 5, keyfile = null, resolver = null, hosts = {}, fetchImpl = globalThis.fetch,
+} = {}) {
+  const r = resolver || new Resolver({ hosts, fetchImpl });
+  // 1. Dónde vive la casa. DNS `_nyx5.<dominio>` manda; well-known es el respaldo.
+  const dc = await r.domainCard(house);
+  const estafeta = dc._estafeta;
+
+  // 2. Nombre. Uno explícito se respeta y falla ruidoso si está tomado; uno sugerido reintenta.
+  let ultimo = null;
+  for (let i = 0; i < (name ? 1 : intentos); i++) {
+    const local = name || nombreSugerido(runtime);
+    if (!NOMBRE_OK.test(local)) throw new Error(`nombre inválido: ${local} (minúsculas, números y guiones, 2 a 32)`);
+    if (Estafeta.RESERVED.has(local)) throw new Error(`nombre reservado por el protocolo: ${local}`);
+    const agente = Agent.create(`${local}@${house}`, estafeta, { resolver: r, fetchImpl });
+    try {
+      const card = await agente.register({
+        invite: invite || undefined,
+        capabilities: { ...capabilities, listed: listed === true },
+      });
+      return await _despues(agente, card, { keyfile, house });
+    } catch (e) {
+      // 409 = nombre tomado. Con nombre sugerido se reintenta; con nombre pedido, se informa.
+      ultimo = e;
+      if (e.status !== 409 || name) throw e;
+    }
+  }
+  throw ultimo || new Error('no se pudo elegir un nombre libre');
+}
+
+async function _despues(agente, card, { keyfile, house }) {
+  const archivo = keyfile || `~/.nyx5/${agente.local}.json`;
+  // 3. Primer sobre: un auto-mensaje. Sirve de prueba viva de que el buzón funciona y le
+  //    deja al agente algo que leer con `inbox` sin molestar a nadie.
+  let first = null;
+  try {
+    first = await agente.send({
+      to: agente.address, type: 'message',
+      body: `Bienvenido a Nyx5. Esta es tu dirección: ${agente.address}. Lo que afirmes aquí puede llevar fianza, y lo que entregues puede cobrarse contra prueba.`,
+    });
+  } catch (e) { first = { error: e.message }; }
+  // 4. Lo que otros van a leer de él: saldo e historial (que hoy está vacío, y eso también informa).
+  const [balance, historial] = await Promise.all([
+    agente.balance().catch((e) => ({ error: e.message })),
+    agente.historial().catch((e) => ({ error: e.message })),
+  ]);
+  return {
+    address: agente.address, house, estafeta: agente.estafeta,
+    keys: agente.keys, keyfile: archivo, card,
+    balance, historial,
+    mcp: bloqueMcp({ address: agente.address, keyfile: archivo }),
+    first,
+    _agente: agente,
+  };
+}
+
+/**
+ * Crea un mandato: el humano fija tope y ámbito UNA vez; dentro de eso el agente contrata
+ * solo, y fuera la casa rechaza. Delegable hacia abajo, nunca hacia arriba.
+ */
+export async function mandate(agente, { grantee, cap, scope = null, expires = null, house = null } = {}) {
+  if (!grantee) throw new Error('falta a quién se le da el mandato (--grantee)');
+  const tope = Number(cap);
+  if (!Number.isInteger(tope) || tope <= 0) throw new Error('el mandato necesita un tope entero y positivo (--cap)');
+  parseAddress(grantee);
+  // El recibo del Libro es la prueba: no se declara creado hasta que el asiento vuelve firmado.
+  const enviado = await agente.mandate(house || agente.domain, { grantee, cap: tope, scope: scope || undefined, expires: expires || undefined });
+  const recibo = await agente.awaitReceipt(enviado.id).catch(() => null);
+  return { sent: enviado, receipt: recibo?.receipt || null, mandate: recibo?.receipt?.mandate || null };
+}

package/src/libro/contratos.js

@@ -245,3 +245,26 @@ export const CONTRATOS = {
   // Bond (fianza) no se cotiza: se deposita directamente con la operación `bond`.
   bond: { quoteable: false },
 };
+
+// ---------- vocabulario público: el ciclo de trabajo de ERC-8183 (ACP), sin la cadena ----------
+// Los estados internos no cambian (romperlos rompería contratos vivos). Lo que se publica hacia
+// afuera habla el vocabulario que ya existe, para que quien integró ACP entienda esto sin traducir.
+//
+//   Open       el trato existe pero el dinero todavía no se movió
+//   Funded     hay tokens retenidos o comprometidos a nombre del trabajo
+//   Submitted  el vendedor entregó y espera evaluación
+//   Terminal   se acabó: liberado, devuelto, pagado o ejecutado
+export const ACP = { accepted: 'Open', held: 'Funded', posted: 'Funded', active: 'Funded', delivered: 'Submitted', released: 'Terminal', refunded: 'Terminal', settled: 'Terminal', forfeited: 'Terminal' };
+// Cómo terminó, para no perder información al agrupar en Terminal.
+export const ACP_DESENLACE = { released: 'accepted', refunded: 'returned', settled: 'paid', forfeited: 'forfeited' };
+
+export function estadoACP(contrato) {
+  const s = contrato?.state;
+  const fase = ACP[s] || 'Open';
+  return { phase: fase, outcome: ACP_DESENLACE[s] || null, state: s };
+}
+
+// Vista pública de un contrato: lo mismo que hay, más el vocabulario ACP. No agrega ni oculta.
+export function contratoPublico(contrato) {
+  return contrato ? { ...contrato, acp: estadoACP(contrato) } : contrato;
+}

package/src/libro/libro.js

@@ -96,12 +96,77 @@ export class Libro {
   async balance(account) { return (await this.store.libroState()).balances[account] || 0; }
   fee(amount) { return Math.floor((amount * this.feeBps) / 10_000); }
   async account(address) {
-    const contracts = (await this.store.libroListContracts()).filter((c) => [c.seller, c.buyer, c.verifier, c.arbiter].includes(address));
+    const { contratoPublico } = await import('./contratos.js');
+    const contracts = (await this.store.libroListContracts()).filter((c) => [c.seller, c.buyer, c.verifier, c.arbiter].includes(address)).map(contratoPublico);
     const mandates = (await this.store.libroListMandates()).filter((m) => m.grantor === address || m.grantee === address);
     return { account: address, balance: await this.balance(address), contracts, mandates };
   }
   async journal() { return this.store.libroJournal(); }
 
+  // ---------- reputación = una consulta al libro ----------
+  // No es un sistema de puntajes aparte: es lo que el libro ya sabe, contado. Por eso no se
+  // puede inflar sin gastar. La defensa contra Sybil es de diseño: SOLO cuentan los contratos
+  // cuyo asiento ya movió tokens (terminales). Un contrato abierto no dice nada de nadie.
+  //
+  // Estados terminales que cuentan, por tipo:
+  //   spot   settled                      entrega pagada
+  //   escrow released | refunded          entrega aceptada | devuelta
+  //   bond   released | forfeited         afirmación sostenida | derribada
+  static TERMINALES = { spot: ['settled'], escrow: ['released', 'refunded'], bond: ['released', 'forfeited'], metered: [] };
+
+  async historial(address) {
+    const todos = await this.store.libroListContracts();
+    const mios = todos.filter((c) => [c.seller, c.buyer].includes(address));
+    const cuenta = () => ({ n: 0, tokens: 0 });
+    const h = {
+      address, house: this.domain,
+      vendiendo: { entregas_aceptadas: cuenta(), entregas_devueltas: cuenta(), ventas_directas: cuenta() },
+      comprando: { encargos_liberados: cuenta(), encargos_devueltos: cuenta(), compras_directas: cuenta() },
+      afirmando: { fianzas_sostenidas: cuenta(), fianzas_ejecutadas: cuenta(), fianzas_vigentes: cuenta() },
+      avalando: { avales_sostenidos: cuenta(), avales_ejecutados: cuenta() },
+      abiertos: cuenta(),
+      desde: null, hasta: null, total_movido: 0,
+    };
+    const sumar = (c, monto) => { c.n += 1; c.tokens += monto; };
+    for (const c of mios) {
+      const terminal = (Libro.TERMINALES[c.kind] || []).includes(c.state);
+      if (!terminal) { sumar(h.abiertos, 0); continue; }
+      const monto = Number(c.amount) || 0;
+      h.total_movido += monto;
+      if (!h.desde || c.created < h.desde) h.desde = c.created;
+      if (!h.hasta || c.created > h.hasta) h.hasta = c.created;
+      if (c.kind === 'bond') {
+        const grupo = c.vouchee ? h.avalando : h.afirmando;
+        const sostenida = c.state === 'released';
+        if (c.vouchee) sumar(sostenida ? grupo.avales_sostenidos : grupo.avales_ejecutados, monto);
+        else sumar(sostenida ? grupo.fianzas_sostenidas : grupo.fianzas_ejecutadas, monto);
+      } else if (c.seller === address) {
+        if (c.kind === 'spot') sumar(h.vendiendo.ventas_directas, monto);
+        else sumar(c.state === 'released' ? h.vendiendo.entregas_aceptadas : h.vendiendo.entregas_devueltas, monto);
+      } else {
+        if (c.kind === 'spot') sumar(h.comprando.compras_directas, monto);
+        else sumar(c.state === 'released' ? h.comprando.encargos_liberados : h.comprando.encargos_devueltos, monto);
+      }
+    }
+    // Fianzas todavía en pie: no son historial cumplido, pero sí tokens en juego ahora mismo.
+    for (const c of mios) if (c.kind === 'bond' && c.state === 'posted' && c.seller === address) sumar(h.afirmando.fianzas_vigentes, Number(c.amount) || 0);
+    // El resumen es lo que un agente lee para decidir en una línea; el detalle queda arriba.
+    const entregadas = h.vendiendo.entregas_aceptadas.n + h.vendiendo.ventas_directas.n;
+    const falladas = h.vendiendo.entregas_devueltas.n;
+    const afirmaciones = h.afirmando.fianzas_sostenidas.n + h.afirmando.fianzas_ejecutadas.n;
+    h.resumen = {
+      entregas: entregadas, entregas_falladas: falladas,
+      afirmaciones_con_fianza: afirmaciones, fianzas_perdidas: h.afirmando.fianzas_ejecutadas.n,
+      tokens_en_juego_ahora: h.afirmando.fianzas_vigentes.tokens,
+      total_movido: h.total_movido,
+      // Sin historial no hay tasa: cero de cero no es 100%, es "todavía nada". Lo decimos así.
+      cumplimiento: entregadas + falladas > 0 ? Number((entregadas / (entregadas + falladas)).toFixed(4)) : null,
+      veracidad: afirmaciones > 0 ? Number((h.afirmando.fianzas_sostenidas.n / afirmaciones).toFixed(4)) : null,
+    };
+    return h;
+  }
+
+
   // ---------- el kernel: un asiento ----------
   // lines: [{ account, delta }]; suma cero; nadie salvo la casa queda negativo.
   async post(concept, lines, meta = {}, refs = {}) {

package/src/libro/tareas.js

@@ -0,0 +1,92 @@
+// Nyx5/1 — Trabajo sembrado: la casa es el primer comprador.
+//
+// El problema del arranque en frío no se resuelve con más oferta. Un agente que se une y no
+// tiene nada que hacer se va, y `join` queda como una llave sin puerta. La casa publica tareas
+// pequeñas, verificables y pagadas: quien llega tiene con qué empezar y, al terminar, tiene
+// historial. Que es lo único que otro agente puede leer para decidir si contratarlo.
+//
+// Cómo funciona, sin inventar protocolo: el agente cotiza la tarea a `tareas@<casa>` con los
+// términos EXACTOS que la casa publicó. La casa comprueba que coinciden, que hay cupo, y
+// acepta. A partir de ahí es un escrow común, con `verifica@` de árbitro. Nadie cobra por
+// decir que entregó: cobra cuando la prueba determinista pasa.
+//
+// Defensa contra Sybil, que es el riesgo obvio de pagar por entrar:
+//   - tope por agente y por día, y tope global por día;
+//   - pago SOLO contra verificación determinista (nunca por juicio ni por afirmación);
+//   - una tarea por agente a la vez, y cada tarea se paga una vez por agente.
+
+import { LibroError } from './errores.js';
+
+const iso = (t = Date.now()) => new Date(t).toISOString();
+const dia = (t = Date.now()) => iso(t).slice(0, 10);
+
+// Las tareas son datos, no código: una casa publica las suyas por configuración.
+export function normalizarTarea(t) {
+  if (!t?.id || !t?.concept) throw new LibroError(400, 'una tarea sembrada necesita id y concept');
+  const precio = Number(t.price);
+  if (!Number.isInteger(precio) || precio <= 0) throw new LibroError(400, `la tarea ${t.id} necesita un precio entero positivo`);
+  const verify = Array.isArray(t.verify) ? t.verify : (t.verify ? [t.verify] : []);
+  if (!verify.length) throw new LibroError(400, `la tarea ${t.id} no declara prueba de aceptación: sin prueba no se paga`);
+  return { id: String(t.id), concept: String(t.concept), price: precio, verify, instructions: t.instructions || null, literal: t.literal ?? null, cupo_dia: t.cupo_dia ?? null };
+}
+
+export class Tareas {
+  /**
+   * @param {object} o
+   * @param {Array}  o.catalogo        tareas publicadas por la casa
+   * @param {number} o.porAgenteDia    cuántas puede tomar un mismo agente al día
+   * @param {number} o.porDia          tope global diario de la casa (0 = sin tope)
+   */
+  constructor({ catalogo = [], porAgenteDia = 1, porDia = 100 } = {}) {
+    this.catalogo = catalogo.map(normalizarTarea);
+    this.porAgenteDia = porAgenteDia;
+    this.porDia = porDia;
+  }
+  get enabled() { return this.catalogo.length > 0; }
+  tarea(id) { return this.catalogo.find((t) => t.id === id) || null; }
+
+  // Lo que ve un agente que llega: qué hay, cuánto paga y CÓMO se va a comprobar. La prueba
+  // se publica entera a propósito: nadie debería aceptar un trato cuyo criterio no puede leer.
+  publicadas() {
+    return this.catalogo.map((t) => ({ id: t.id, concept: t.concept, price: t.price, verify: t.verify, instructions: t.instructions }));
+  }
+
+  /**
+   * ¿Puede este agente tomar esta tarea ahora? Devuelve { ok } o { ok:false, reason }.
+   * Se decide leyendo los contratos que ya existen: no hay contador aparte que se pueda
+   * desincronizar del libro.
+   */
+  cupo(tarea, agente, contratos, hoy = dia()) {
+    const deTarea = (c) => c.terms?.seed_task;
+    const delDia = contratos.filter((c) => deTarea(c) && c.created?.slice(0, 10) === hoy);
+    // El orden importa: se responde con lo más accionable primero. "Termínala" le dice al
+    // agente qué hacer ahora; "vuelve mañana" solo tiene sentido si de verdad no puede seguir.
+    const enCurso = contratos.find((c) => deTarea(c) && c.seller === agente && ['held', 'delivered'].includes(c.state));
+    if (enCurso) return { ok: false, reason: `ya tienes la tarea ${enCurso.terms.seed_task} en curso (${enCurso.id}); termínala primero` };
+    const suyas = delDia.filter((c) => c.seller === agente);
+    if (suyas.length >= this.porAgenteDia) return { ok: false, reason: `ya tomaste ${suyas.length} tarea(s) sembrada(s) hoy; el tope por agente es ${this.porAgenteDia}` };
+    if (this.porDia > 0 && delDia.length >= this.porDia) return { ok: false, reason: `la casa ya sembró ${this.porDia} tareas hoy; vuelve mañana` };
+    const yaHecha = contratos.find((c) => c.terms?.seed_task === tarea.id && c.seller === agente && c.state === 'released');
+    if (yaHecha) return { ok: false, reason: `ya cobraste la tarea ${tarea.id}; cada tarea se paga una vez por agente` };
+    return { ok: true };
+  }
+
+  /**
+   * ¿La cotización que mandó el agente es exactamente la tarea publicada? Se compara contra
+   * el catálogo, nunca contra lo que dice la cotización de sí misma. Un precio inflado, una
+   * prueba cambiada o un árbitro distinto son motivo de rechazo, no de negociación.
+   */
+  coincide(q, tarea, { arbitro }) {
+    if (q.contract !== 'escrow') return { ok: false, reason: 'una tarea sembrada se toma como escrow' };
+    if (q.price !== tarea.price) return { ok: false, reason: `el precio de ${tarea.id} es ${tarea.price}, la cotización dice ${q.price}` };
+    if (q.arbiter !== arbitro) return { ok: false, reason: `el árbitro de una tarea sembrada es ${arbitro}` };
+    if (JSON.stringify(q.terms?.verify) !== JSON.stringify(tarea.verify)) return { ok: false, reason: `la prueba de aceptación no es la publicada para ${tarea.id}` };
+    if (q.terms?.seed_task !== tarea.id) return { ok: false, reason: 'la cotización debe declarar terms.seed_task con el id de la tarea' };
+    return { ok: true };
+  }
+
+  // Los términos que el agente debe copiar tal cual. Se publican para que no haya que adivinarlos.
+  terminosDe(tarea) {
+    return { seed_task: tarea.id, acceptance: tarea.concept, verify: tarea.verify };
+  }
+}