@nyx5/nyx5 0.1.0 → 0.2.1

package/migrations/0005_eventos.sql

@@ -0,0 +1,16 @@
+-- Instrumentación mínima del sprint join/mandate/verifica. Sin esto, la distribución es ciega:
+-- no se sabe si llegan agentes (join), si alguien les pone presupuesto (mandate_created), ni
+-- si el mecanismo se ejerce de verdad (escrow_released, bond_forfeited).
+--
+-- Qué NO se guarda, a propósito: contenido de sobres, direcciones de correo humanas, IPs.
+-- Un evento lleva el nombre, la fecha, el actor (dirección del agente, que ya es pública) y
+-- un puñado de datos numéricos. Sirve para contar, no para perfilar.
+CREATE TABLE IF NOT EXISTS nyx5_eventos (
+  id      TEXT PRIMARY KEY,
+  name    TEXT NOT NULL,
+  ts      TEXT NOT NULL,
+  actor   TEXT,
+  data    TEXT NOT NULL DEFAULT '{}'
+);
+CREATE INDEX IF NOT EXISTS nyx5_eventos_name_ts ON nyx5_eventos (name, ts);
+CREATE INDEX IF NOT EXISTS nyx5_eventos_ts ON nyx5_eventos (ts);

package/package.json

@@ -1,38 +1,57 @@
 {
   "name": "@nyx5/nyx5",
-  "version": "0.1.0",
-  "description": "Nyx5/1 — correo y libro para agentes de IA: direcciones agente@dominio, buzón store-and-forward, sobres firmados y cifrados, y un ledger de doble entrada con contratos (escrow, fianza, medido). Implementación de referencia, sin dependencias.",
+  "version": "0.2.1",
+  "description": "Nyx5/1 — mail and ledger for AI agents: agent@domain addresses, a store-and-forward mailbox, and a ledger where a claim costs something. One command to join, escrow released only against a deterministic check, and reputation that is just a query on the ledger. Zero dependencies.",
   "type": "module",
   "license": "Apache-2.0",
   "homepage": "https://nyx5.com",
-  "repository": { "type": "git", "url": "git+https://github.com/Nicoiakl/nyx5.git" },
-  "bugs": { "url": "https://github.com/Nicoiakl/nyx5/issues" },
-  "engines": { "node": ">=20" },
-  "bin": { "nyx5": "./bin/nyx5.js" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nicoiakl/nyx5.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nicoiakl/nyx5/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "nyx5": "bin/nyx5.js"
+  },
   "files": [
-    "src/",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.es.md",
+    "README.md",
+    "SECURITY.md",
+    "agents.md",
     "bin/",
-    "migrations/",
     "demo/",
-    "examples/",
-    "docs/SPEC.md",
     "docs/ARQUITECTURA.md",
-    "README.md",
-    "LICENSE",
-    "CONTRIBUTING.md",
-    "SECURITY.md"
+    "docs/SPEC.en.md",
+    "docs/SPEC.md",
+    "examples/",
+    "migrations/",
+    "src/"
   ],
   "keywords": [
     "agents",
+    "ai-agents",
     "agent-communication",
     "protocol",
-    "messaging",
-    "ledger",
+    "mcp",
+    "model-context-protocol",
+    "a2a",
     "escrow",
+    "reputation",
+    "agent-identity",
+    "ledger",
     "ed25519",
     "end-to-end-encryption",
     "cloudflare-workers",
-    "mcp"
+    "x402",
+    "agent-payments",
+    "verification"
   ],
   "scripts": {
     "demo": "node demo/e2e.js",

package/src/correo/agente.js

@@ -45,8 +45,8 @@ export class Agent {
   // ---------- registro ----------
   // Tres caminos: adminToken (la casa inscribe), invite (código de la casa) o abierto si la casa lo permite.
   // Sin adminToken y sin estar registrado, el cuerpo va firmado con la propia clave (prueba de posesión).
-  async register({ adminToken, invite, capabilities, inbox, webhook, valid_until } = {}) {
-    const body = { local: this.local, sig: this.keys.sig, enc: this.keys.enc, capabilities, inbox, webhook, valid_until };
+  async register({ adminToken, invite, capabilities, inbox, webhook, notify_email, valid_until } = {}) {
+    const body = { local: this.local, sig: this.keys.sig, enc: this.keys.enc, capabilities, inbox, webhook, notify_email, valid_until };
     if (adminToken) this.card = await this._call('POST', '/agents', body, { admin: adminToken });
     else if (this.card) this.card = await this._call('POST', '/agents', body);
     else this.card = await this._call('POST', '/agents', signObject({ ...body, invite: invite || undefined, ts: iso() }, this.keys), { noAuth: true });
@@ -168,6 +168,15 @@ export class Agent {
   // Lecturas directas (sin pasar por correo) en la casa indicada; por defecto, la propia estafeta.
   async balance(house) { return this._callAt(house, 'GET', `/libro/cuenta/${encodeURIComponent(this.address)}`); }
   async contract(house, id) { return this._callAt(house, 'GET', `/libro/contrato/${encodeURIComponent(id)}`); }
+  // Historial público de cualquier agente (por defecto, el propio): la reputación es el libro.
+  async historial(address = this.address) {
+    const { local, domain } = parseAddress(address);
+    const base = domain === this.domain ? this.estafeta : (await this.resolver.domainCard(domain))._estafeta;
+    const res = await this.fetch(`${base}/agents/${encodeURIComponent(local)}/historial`, { signal: AbortSignal.timeout(10_000) });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw Object.assign(new Error(json.reason || `HTTP ${res.status}`), { status: res.status });
+    return json;
+  }
   async _callAt(house, method, path) {
     if (!house || house === this.domain) return this._call(method, path);
     const dc = await this.resolver.domainCard(house);

package/src/correo/estafeta.js

@@ -23,9 +23,12 @@ 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';
+import { SPEC_HTML, SPEC_HTML_ES, LLMS_TXT } from '../plataformas/spec-html.js';
+import { HOME_HTML, HOME_HTML_ES } from '../plataformas/home-html.js';
 import { inboundEnvelope, outboundPayload, isEmailAddress } from '../puentes/email.js';
 
 const now = () => Date.now();
@@ -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); }
 
@@ -621,13 +759,26 @@ export class Estafeta {
       if (rx.method === 'GET' && path === '/health') return send(200, { ok: true, domain: this.domain, agents: (await this.store.listAgents()).length, queue: (await this.store.listQueue()).length });
       // Cliente web para personas: se sirve desde la propia casa (mismo origen, sin CORS).
       // El HTML genera las llaves en el navegador del usuario; la casa nunca las ve.
+      // Inglés primario en la portada; el español vive en /es-home. Ambas se enlazan con hreflang.
       if (rx.method === 'GET' && path === '/') return { status: 200, body: HOME_HTML, contentType: 'text/html; charset=utf-8' };
+      if (rx.method === 'GET' && (path === '/es-home' || path === '/es-home/')) return { status: 200, body: HOME_HTML_ES, contentType: 'text/html; charset=utf-8' };
       if (rx.method === 'GET' && (path === '/app' || path === '/app/')) return { status: 200, body: APP_HTML, contentType: 'text/html; charset=utf-8' };
       // La especificación en una página, indexable. Se genera desde docs/SPEC.md (build:spec).
+      // El inglés es la versión canónica de la spec (es donde busca quien integra un protocolo);
+      // el español vive en /es y ambas se enlazan entre sí con hreflang.
       if (rx.method === 'GET' && (path === '/spec' || path === '/spec/')) return { status: 200, body: SPEC_HTML, contentType: 'text/html; charset=utf-8' };
+      if (rx.method === 'GET' && (path === '/es' || path === '/es/' || path === '/spec/es')) return { status: 200, body: SPEC_HTML_ES, contentType: 'text/html; charset=utf-8' };
       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 +812,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 +870,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;
+}