@nyx5/nyx5 0.6.0 → 0.8.0

package/src/plataformas/worker.js

@@ -13,10 +13,13 @@
 //   NYX5_FEE_BPS       fee de la casa en basis points (default 1000 = 10%)
 //   NYX5_INDEX         'on' para operar el índice federado (default off)
 //   NYX5_EMAIL         'on' para habilitar el puente de correo
+//   NYX5_IDEAS         'on' para el buzón ideas@ (registra y confirma, nunca ejecuta; exige NYX5_VAULT_KEY)
 //   DB                    binding D1
 
 import { Estafeta } from '../correo/estafeta.js';
+import { TERMS_HTML } from './terms-html.js';
 import { D1Store } from '../nucleo/almacen-d1.js';
+import { ObjetosR2 } from '../nucleo/objetos.js';
 import { extractText, resendProvider, addressFromHeader, decodeMimeWords } from '../puentes/email.js';
 
 // El catálogo sembrado de esta casa. Tres tareas deterministas y baratas: su función NO es
@@ -59,15 +62,30 @@ function estafetaDesde(env) {
     publicUrl: cfg('PUBLIC_URL') || `https://${domain}`,
     adminToken: cfg('ADMIN_TOKEN'),
     store: new D1Store(env.DB),
+    // Adjuntos cifrados (NX-413): el almacén de objetos es el bucket R2 del binding BLOBS. Sin
+    // binding la casa NO aloja adjuntos y /blob lo dice con un 503, en vez de aceptar un archivo
+    // que se perdería. El bucket y el binding los pone Nicholas al desplegar (ARQUITECTURA §4.9).
+    objetos: env.BLOBS ? new ObjetosR2(env.BLOBS) : null,
     policy: { registration: cfg('REGISTRATION') || 'invite' },
-    libro: { welcome: Number(cfg('WELCOME') || 0), feeBps: Number(cfg('FEE_BPS') || 1000) },
+    // /terms existe sólo si la casa lo enciende: son declaraciones vinculantes del dueño (aprobadas 14-sep-2026).
+    terms: cfg('TERMS') === 'on' ? TERMS_HTML : null,
+    libro: { welcome: Number(cfg('WELCOME') || 0), feeBps: Number(cfg('FEE_BPS') || 1000),
+      // Escrow que vence (NX-503), en horas: gracia para que el comprador recupere, y ventana de revisión.
+      reclaimGraceMs: (Number(cfg('RECLAIM_GRACE_HOURS')) || 24) * 3600_000, reviewWindowMs: (Number(cfg('REVIEW_WINDOW_HOURS')) || 72) * 3600_000 },
     index: { enabled: cfg('INDEX') === 'on' },
-    email: { enabled: cfg('EMAIL') === 'on' || !!provider, provider, footer: cfg('EMAIL_FOOTER') === 'on' },
+    email: { enabled: cfg('EMAIL') === 'on' || !!provider, provider, footer: cfg('EMAIL_FOOTER') === 'on', senders: String(cfg('EMAIL_SENDERS') || '').split(',') },
     // Trabajo sembrado: lo que la casa publica para que un agente recién unido tenga algo
     // que hacer y salga con historial. El catálogo vive en el código (cambiarlo es un
     // despliegue, con revisión y vuelta atrás) pero se ENCIENDE por casa: las dos casas
     // comparten este archivo, y una casa sin presupuesto que publica tareas solo frustra.
     tareas: cfg('SEED') === 'on' ? NYX5_TAREAS : {},
+    // Conector MCP remoto (OAuth + subagentes delegados). Se enciende por casa y exige la llave de
+    // la bóveda (secret NYX5_VAULT_KEY): sin ella no hay dónde guardar una llave, y /mcp no existe.
+    remoto: { enabled: cfg('MCP_REMOTE') === 'on', vaultKey: env.NYX5_VAULT_KEY, dias: Number(cfg('REMOTE_DAYS')) || 30 },
+    // Asistentes que contestan solos (src/correo/asistente.js). Sin clave de la API, no existen.
+    asistente: { apiKey: env.ANTHROPIC_API_KEY },
+    // ideas@ (src/correo/ideas.js): el buzón de vacaciones. Se enciende por casa y usa la bóveda.
+    ideas: { enabled: cfg('IDEAS') === 'on' },
     log: (...a) => console.log(...a),
   });
   return instancia;
@@ -81,12 +99,16 @@ function estafetaDesde(env) {
 //     interpretado como otro tipo, ni embebido en un iframe ajeno, ni filtrar de dónde vino.
 //   - CSP: la portada y la spec traen su CSS y un script inline propios y NADA externo, así que
 //     se declara exactamente eso. Si algún día se añade un recurso de fuera, esto grita.
+//     `connect-src 'self'` es OBLIGATORIO: sin él, `default-src 'none'` bloquea todo fetch y la app
+//     de /app no podía crear una dirección ni mandar un mensaje. Estuvo así en producción hasta el
+//     10-sep-2026 y nadie lo vio: la página cargaba bien y fallaba en silencio al primer botón.
+//     `manifest-src` e `img-src 'self'` son para instalarla en la pantalla de inicio.
 const SEGURIDAD = {
   'strict-transport-security': 'max-age=31536000; includeSubDomains',
   'x-content-type-options': 'nosniff',
   'x-frame-options': 'DENY',
   'referrer-policy': 'no-referrer',
-  'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+  'content-security-policy': "default-src 'none'; connect-src 'self'; manifest-src 'self'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; img-src data: 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
 };
 
 // Cuánto puede cachear cada superficie. La tarjeta del dominio y la spec son estables y se
@@ -97,6 +119,8 @@ function cacheDe(path, method) {
   if (path === '/.well-known/nyx5.json') return 'public, max-age=300, stale-while-revalidate=600';
   if (path === '/' || path === '/spec' || path === '/spec/' || path === '/llms.txt' || path === '/robots.txt' || path === '/sitemap.xml' || path === '/favicon.ico') return 'public, max-age=3600';
   if (path === '/tareas' || path.startsWith('/agents') || path === '/report' || path === '/report.json') return 'public, max-age=60';
+  if (path === '/manifest.webmanifest' || /^\/(icon-\d+|apple-touch-icon)\.png$/.test(path)) return 'public, max-age=86400';
+  if (path.startsWith('/.well-known/oauth-')) return 'public, max-age=300';
   return 'no-store';
 }
 
@@ -113,10 +137,23 @@ export default {
     const estafeta = estafetaDesde(env);
     const url = new URL(request.url);
     let body = null;
-    if (request.method === 'POST' || request.method === 'PUT') {
+    let raw = null;
+    // La subida de un adjunto (PUT /blob/<id>) llega como BYTES, no como JSON: un archivo no es
+    // JSON y pasarlo en base64 lo infla un tercio para nada. El tope de aquí es mayor que el de la
+    // ruta a propósito, para que el motivo del rechazo lo dé la ruta nombrando el límite real.
+    if (request.method === 'PUT' && /^\/blob\/[^/]+$/.test(url.pathname)) {
+      if (Number(request.headers.get('content-length') || 0) > 16 * 1024 * 1024) return Response.json({ reason: 'cuerpo demasiado grande' }, { status: 413 });
+      raw = new Uint8Array(await request.arrayBuffer());
+      if (raw.length > 16 * 1024 * 1024) return Response.json({ reason: 'cuerpo demasiado grande' }, { status: 413 });
+    } else if (request.method === 'POST' || request.method === 'PUT') {
       const len = Number(request.headers.get('content-length') || 0);
       if (len > 2 * 1024 * 1024) return Response.json({ reason: 'cuerpo demasiado grande' }, { status: 413 });
-      try { body = await request.json(); } catch { return Response.json({ reason: 'invalid JSON' }, { status: 400 }); }
+      // /oauth/token recibe form-urlencoded (RFC 6749 §4.1.3): Claude manda el canje y el refresco
+      // así. Leerlo todo como JSON devolvía 400 y el conector no llegaba nunca a tener token.
+      const texto = await request.text();
+      if ((request.headers.get('content-type') || '').includes('application/x-www-form-urlencoded')) body = Object.fromEntries(new URLSearchParams(texto));
+      else if (!texto.trim()) body = {};
+      else { try { body = JSON.parse(texto); } catch { return Response.json({ reason: 'invalid JSON' }, { status: 400 }); } }
     }
     // www redirige al apex con 301. Existe como registro para que el nombre no dé NXDOMAIN
     // (quien lo teclea o lo pega en un chat llegaba a la nada), pero la casa vive en el apex:
@@ -135,14 +172,22 @@ export default {
       query: url.searchParams,
       headers: Object.fromEntries([...request.headers].map(([k, v]) => [k.toLowerCase(), v])),
       body,
+      raw,
       ip: request.headers.get('cf-connecting-ip') || null,
     };
     const out = await estafeta.handleRequest(rx);
     if (out.pending) ctx.waitUntil(out.pending);
-    if (out.kick) ctx.waitUntil(estafeta.tick().catch((e) => console.log('tick error', e.message)));
+    // Un tick disparado por una petición no atiende asistentes (programado: false): tras responder,
+    // el edge sólo da 30 segundos y una respuesta de Claude puede tardar más. Los atiende el cron.
+    if (out.kick) ctx.waitUntil(estafeta.tick({ programado: false }).catch((e) => console.log('tick error', e.message)));
     // Un cuerpo binario (la imagen de compartir) llega como Buffer; el edge quiere bytes.
-    const cuerpo = out.contentType ? (Buffer.isBuffer(out.body) ? new Uint8Array(out.body) : out.body) : JSON.stringify(out.body);
+    // 204 y 304 no llevan cuerpo: un Response con cuerpo (aunque sea '') y uno de esos estados revienta.
+    const cuerpo = out.status === 204 || out.status === 304 ? null : out.contentType ? (Buffer.isBuffer(out.body) ? new Uint8Array(out.body) : out.body) : JSON.stringify(out.body);
     const headers = {
+      // Cabeceras que pone la ruta (hoy: el sobre x402 en PAYMENT-REQUIRED / PAYMENT-RESPONSE).
+      // Van PRIMERO para que una ruta no pueda pisar por descuido una cabecera de seguridad ni el
+      // content-type: lo que va debajo gana siempre.
+      ...(out.headers || {}),
       ...SEGURIDAD,
       'content-type': out.contentType || 'application/json',
       'cache-control': cacheDe(url.pathname, request.method),

package/src/puentes/ejecutor.js

@@ -0,0 +1,118 @@
+// Nyx5/1 — El lado CI del ejecutor (NX-412, 27-oct-2026): lo que corre DENTRO del job.
+//
+// La casa dispara el CI con un aviso de nueve campos y sin el contenido del sobre (ver
+// `src/correo/ci.js`). Este módulo es lo que el job hace con ese aviso, y son tres pasos:
+//
+//   1. VERIFICAR el aviso. Un `repository_dispatch` lo puede lanzar cualquiera que tenga el token
+//      del repositorio, y el payload lo escribe quien dispara. Así que el aviso se comprueba contra
+//      la tarjeta de la casa: `sig` tiene que ser una firma Ed25519 de `ci:<sobre>:<dirección>` por
+//      una de las llaves que la casa publica. Un aviso que no verifica NO se trabaja: ni se lee el
+//      buzón, ni se gasta un minuto de runner.
+//   2. RECOGER el encargo. El aviso no trae el contenido: el job lee `GET /mailbox/<local>` con la
+//      llave del rol (un secret del repositorio) y descifra el sobre. La llave nunca pasó por la
+//      casa ni por el chat.
+//   3. RESPONDER y CONFIRMAR. La respuesta va firmada por la dirección del rol, en el mismo hilo, y
+//      recién entonces se confirma el sobre: si el job muere a mitad, el sobre sigue pendiente y la
+//      casa lo vuelve a despachar. Confirmar antes de responder perdería el encargo en silencio.
+//
+// Cero dependencias y nada propio de GitHub: el aviso es un objeto JSON y de dónde salió es asunto
+// del workflow.
+
+import { Agent } from '../correo/agente.js';
+import { verifyBytes } from '../nucleo/crypto.js';
+
+const CAMPOS = ['nyx5', 'house', 'to', 'envelope', 'from', 'type', 'at', 'sig'];
+
+export function parsearAviso(texto) {
+  let a;
+  try { a = typeof texto === 'string' ? JSON.parse(texto) : texto; } catch { throw new Error('the notice is not JSON'); }
+  if (!a || typeof a !== 'object') throw new Error('the notice is not an object');
+  const faltan = CAMPOS.filter((c) => typeof a[c] !== 'string' || !a[c]);
+  if (faltan.length) throw new Error(`the notice is missing: ${faltan.join(', ')}`);
+  if (a.nyx5 !== '1') throw new Error(`unknown protocol version: ${a.nyx5}`);
+  if (!a.to.endsWith(`@${a.house}`)) throw new Error(`the notice says house ${a.house} but address ${a.to}`);
+  return a;
+}
+
+// La tarjeta de la casa, pedida a la casa misma. `estafeta` se pasa cuando no se quiere resolver por
+// DNS (pruebas, o una casa que todavía no publica su TXT).
+export async function tarjetaDeCasa(house, { estafeta = null, fetchImpl = globalThis.fetch } = {}) {
+  const base = (estafeta || `https://${house}`).replace(/\/$/, '');
+  const r = await fetchImpl(`${base}/.well-known/nyx5.json`);
+  if (!r.ok) throw new Error(`the house card of ${house} answered ${r.status}`);
+  const card = await r.json();
+  if (card.domain !== house) throw new Error(`that card says domain ${card.domain}, not ${house}`);
+  if (!Array.isArray(card.keys) || !card.keys.length) throw new Error(`the card of ${house} publishes no keys`);
+  return card;
+}
+
+// Verifica el aviso contra las llaves que la casa publica. Cualquiera de ellas sirve: una casa que
+// rota su llave firma con la nueva y sigue publicando la vieja un tiempo.
+export function verificarAviso(aviso, tarjeta) {
+  const mensaje = `ci:${aviso.envelope}:${aviso.to}`;
+  return tarjeta.keys.some((k) => { try { return verifyBytes(mensaje, aviso.sig, k.sig); } catch { return false; } });
+}
+
+const COMPLETA = (k) => !!(k?.sig && k?.sigPriv && k?.enc && k?.encPriv);
+
+// Qué formas de llave se aceptan, y por qué tres y no una. La canónica es la que escribe
+// `nyx5 keygen`: `{ address, estafeta, keys: { sig, sigPriv, enc, encPriv } }`. La plana es la misma
+// sin el envoltorio, que es lo que tiene a mano quien arma el secret desde otro lado. Y el MAPA
+// `{ "<dirección>": <una de las dos> }` existe porque un repositorio suele ser la casa de VARIOS
+// roles: la fábrica de Rosetta tiene siete que ejecutan, y pedir siete secrets para un workflow que
+// ya sabe a quién va dirigido el aviso es fricción sin nada a cambio. Del mapa se usa SÓLO la
+// entrada del destinatario del aviso.
+export function llaveDe(bulto, destino) {
+  if (!bulto || typeof bulto !== 'object') throw new Error('the role key must be a JSON object');
+  const dir = String(destino).toLowerCase();
+  const una = (k) => {
+    if (COMPLETA(k?.keys)) return { address: String(k.address || dir).toLowerCase(), keys: k.keys };
+    if (COMPLETA(k)) return { address: String(k.address || dir).toLowerCase(), keys: { sig: k.sig, sigPriv: k.sigPriv, enc: k.enc, encPriv: k.encPriv } };
+    return null;
+  };
+  const sola = una(bulto);
+  if (sola) return sola;
+  // Un mapa: se busca por la dirección del aviso y se ignora todo lo demás.
+  if (Object.hasOwn(bulto, dir)) {
+    const del = una(bulto[dir]);
+    if (del) return { address: dir, keys: del.keys };
+  }
+  const direcciones = Object.keys(bulto).filter((k) => k.includes('@'));
+  if (direcciones.length) throw new Error(`that key bundle has no entry for ${dir} (it carries ${direcciones.length})`);
+  throw new Error('the role key must carry sig, sigPriv, enc and encPriv (or be a map of address to key)');
+}
+
+function agenteDe(aviso, bulto, { estafeta = null, hosts = {}, fetchImpl = globalThis.fetch } = {}) {
+  const { address, keys } = llaveDe(bulto, aviso.to);
+  if (address !== String(aviso.to).toLowerCase()) throw new Error(`that key is of ${address}, and the notice is for ${aviso.to}`);
+  return new Agent({ address, keys, estafeta: estafeta || `https://${aviso.house}`, hosts, fetchImpl });
+}
+
+// Paso 1 + 2: verificar y recoger. Devuelve el sobre y el encargo ya descifrado.
+export async function recoger({ aviso, keys, estafeta = null, hosts = {}, fetchImpl = globalThis.fetch }) {
+  const a = parsearAviso(aviso);
+  const tarjeta = await tarjetaDeCasa(a.house, { estafeta, fetchImpl });
+  if (!verificarAviso(a, tarjeta)) throw new Error(`the notice is not signed by ${a.house}: nothing was read and nothing was done`);
+  const agente = agenteDe(a, keys, { estafeta, hosts, fetchImpl });
+  const bandeja = await agente.inbox({ limit: 200 });
+  const m = bandeja.find((x) => x.envelope?.id === a.envelope);
+  // Que no esté no es un error del aviso: el sobre pudo ser confirmado por una corrida anterior.
+  if (!m) return { aviso: a, agente, envelope: null, abierto: null, encargo: null, reason: 'that envelope is no longer in the mailbox: another run already took it' };
+  if (m.envelope.from !== a.from) throw new Error(`the notice says ${a.from} and the envelope in the mailbox is from ${m.envelope.from}`);
+  const abierto = await agente.open(m.envelope);
+  // `encargo` es lo normalizado: el workflow no tiene por que saber que el cuerpo vive bajo
+  // `content` ni que un sobre en claro y uno cifrado llegan por caminos distintos.
+  const encargo = { media: abierto.content?.media ?? null, body: abierto.content?.body ?? null, project: abierto.project || null, role: abierto.role || null };
+  return { aviso: a, agente, envelope: m.envelope, abierto, encargo, reason: null };
+}
+
+// Paso 3: responder y recién entonces confirmar. El orden importa: si el job muere entre las dos
+// cosas, el sobre sigue pendiente y la casa lo vuelve a despachar. Al revés se perdería callado.
+export async function responder({ aviso, keys, texto, estafeta = null, hosts = {}, fetchImpl = globalThis.fetch, ack = true, type = 'result' }) {
+  const a = parsearAviso(aviso);
+  if (typeof texto !== 'string' || !texto.trim()) throw new Error('an empty answer is not an answer');
+  const agente = agenteDe(a, keys, { estafeta, hosts, fetchImpl });
+  const env = await agente.send({ to: a.from, type, body: texto, thread: a.envelope, inReplyTo: a.envelope, project: a.project || undefined });
+  const acked = ack ? await agente.ack([a.envelope]) : [];
+  return { sent: env.id, acked };
+}

package/src/puentes/herramientas.js

@@ -0,0 +1,315 @@
+// Nyx5/1 — Las herramientas que un modelo usa para operar Nyx5, en UN solo lugar.
+// Las sirven dos puentes: el local por stdio (src/puentes/mcp.js, la llave del agente en el disco
+// del usuario) y el remoto por HTTP (src/puentes/mcp-remoto.js, un subagente delegado cuya llave
+// guarda la casa). Si cada puente tuviera su copia, una descripción o un arreglo llegaría a uno
+// solo y el otro seguiría prometiendo lo de antes.
+//
+// Las descripciones son lo único que el modelo lee para decidir si usa Nyx5: dicen la capacidad,
+// la garantía y el momento de uso, no el mecanismo. Las cuida test/mcp.test.js.
+
+import { proyectoDe, nombreDeProyecto } from '../correo/politica.js';
+import { MEDIA_GATE } from '../correo/asistente.js';
+import { MEDIA_COBRO_CONFIRMACION, MONEDAS, TIPOS_CUENTA } from '../correo/cobro.js';
+
+export const TOOLS = [
+  { name: 'nyx5_send', description: 'Delegate a task to another agent even if it is switched off: it waits in their mailbox and their reply reaches you signed when they answer. Use it when you need someone to do something and do not know whether they are available now. The result says whether it went encrypted (it does when the recipient has a key).',
+    inputSchema: { type: 'object', required: ['to', 'body'], properties: {
+      to: { type: 'array', items: { type: 'string' }, description: 'Direcciones destino, ej. ["asistente@beta.local"]' },
+      body: { description: 'Contenido: texto o JSON' },
+      type: { type: 'string', enum: ['message', 'task', 'result', 'receipt', 'intro'], default: 'message' },
+      thread: { type: 'string' }, in_reply_to: { type: 'string' },
+      project: { type: 'string', description: 'which project or chat this belongs to (e.g. "sigo", "rosetta"); the other side can filter its mailbox by it' },
+      role: { type: 'string', description: 'your role in that project, if any (e.g. "main", "lab")' },
+      summary: { type: 'string', description: 'ONE line, IN THE CLEAR, saying what this is about (max 140 chars). The body travels encrypted and nobody but the recipient opens it; this line does not, so the house can put it in the subject of the email notice and its owner can decide from a phone without opening anything. Write what it is ABOUT, never what the envelope protects: the house and their email provider read it. Optional, and it only reaches someone who registered an email for notices.' },
+      aval: { type: 'object', description: 'para entrar a un buzón con lista blanca sin estar en ella: { voucher, bond } de un tercero de la allowlist que te respaldó con una fianza', properties: { voucher: { type: 'string' }, bond: { type: 'string' } } },
+      encrypt: { type: 'boolean', default: true } } } },
+  { name: 'nyx5_inbox', description: 'What others sent you while you were not looking. Every envelope arrives with a verified signature (you know who really sent it) and comes decrypted. Check it when you start and before treating anything as unanswered. A request for a service you publish (media nyx5.pedido) is answered with nyx5_quote {service, to, in_reply_to}.',
+    inputSchema: { type: 'object', properties: { limit: { type: 'integer', default: 20 }, project: { type: 'string', description: 'only messages of this project (see nyx5_send)' } } } },
+  { name: 'nyx5_ack', description: 'Close the envelopes in your mailbox that you already handled so they stop coming back. Use it after acting on a message; what you acknowledge stays in the record.',
+    inputSchema: { type: 'object', required: ['ids'], properties: { ids: { type: 'array', items: { type: 'string' } } } } },
+  { name: 'nyx5_resolve', description: 'Check who an address really is before trusting it: returns their card, certified by their domain (verified identity, what they can do, how they charge). Use it before sending anything sensitive or paying them.',
+    inputSchema: { type: 'object', required: ['address'], properties: { address: { type: 'string' } } } },
+  { name: 'nyx5_outbox', description: 'What happened to the signed envelopes you sent: delivered, retrying, or bounced with the reason. Use it when you are unsure whether your message arrived; the estafeta records every attempt.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'nyx5_directory', description: 'Which agents a house offers and what each one does, every card certified by the domain. Use it when you are looking for a provider inside a house you already know.',
+    inputSchema: { type: 'object', properties: { house: { type: 'string' }, capability: { type: 'string' }, accepts: { type: 'string' }, q: { type: 'string' }, limit: { type: 'integer' } } } },
+  { name: 'nyx5_search', description: 'Find an agent that does what you need in any house, ranked by verified reputation (ledger-backed, null when unproven) with tag, language, price and min_score filters. Use it when you know nobody who solves your problem. The index answers signed and you verify the card before trusting: a hint, not an authority.',
+    inputSchema: { type: 'object', required: ['index'], properties: { index: { type: 'string', description: 'domain of the house that runs the index, or its URL' }, q: { type: 'string' }, tag: { type: 'string' }, lang: { type: 'string', description: 'language tag like "es" or "en-US"' }, capability: { type: 'string' }, accepts: { type: 'string' }, house: { type: 'string' }, price_max: { type: 'integer', description: 'tokens; agents without a published price never match' }, min_score: { type: 'number', description: '0..1; agents without history never match' }, limit: { type: 'integer' }, cursor: { type: 'string', description: 'next_cursor of the previous page; omit for the first page' } } } },
+  // ----- Libro -----
+  { name: 'nyx5_quote', description: 'Offer another agent a service with a price and the exact condition that must be met to get paid. In escrow the payment is held until the proof passes. Use it to sell something with an agreement that carries weight, not a spoken promise. Name a service from your profile and the published price and contract apply.',
+    inputSchema: { type: 'object', required: ['to'], properties: {
+      to: { type: 'string' }, contract: { type: 'string', enum: ['spot', 'escrow', 'metered'], default: 'spot' },
+      service: { type: 'string', description: 'id of a service in your profile: price, contract and concept default to what you published, and the house rejects a quote that differs from it' },
+      price: { type: 'integer', description: 'tokens, entero (required without service)' }, concept: { type: 'string', description: 'required without service' },
+      terms: { type: 'object', description: 'criterio de aceptación, plazo, scope del mandato, etc.' },
+      arbiter: { type: 'string' }, expires: { type: 'string', description: 'ISO-8601' },
+      referrer: { type: 'object', description: 'comisión de referido: { address, share } en basis points; la paga el vendedor de su parte, el comprador paga igual', properties: { address: { type: 'string' }, share: { type: 'integer' } } },
+      in_reply_to: { type: 'string', description: 'id of a service request (media nyx5.pedido) you are answering: the quote goes in its thread with the published terms, the test derived from your acceptance and the request input, and verifica@ as arbiter' } } } },
+  { name: 'nyx5_accept', description: 'Accept an offer and commit the payment. In escrow the money is held: the seller does not get paid until they deliver and meet the condition. You receive a signed receipt that no party can deny later.',
+    inputSchema: { type: 'object', required: ['quote'], properties: { quote: { type: 'object' } } } },
+  { name: 'nyx5_hire', description: 'Hire a service from an agent profile in one step: sends the request, waits for the quote and accepts it only if it matches the published catalogue (price, contract, your input, verifica@ as arbiter when a test is published); in escrow the payment is held until that test passes. Use it when you found a provider and want the deal closed.',
+    inputSchema: { type: 'object', required: ['agent', 'service'], properties: {
+      agent: { type: 'string', description: 'address of the seller' }, service: { type: 'string', description: 'id of a service in its profile (nyx5_profile op=get)' },
+      input: { type: 'object', description: 'what the seller needs to do the job; for a published test it also fills its fields (http_status: url; sha256: expect; json_path: url, path, expect)' },
+      note: { type: 'string' }, auto_accept: { type: 'boolean', default: true, description: 'false: only send the request; the quote lands in your mailbox for you to accept' },
+      max_price: { type: 'integer', description: 'tokens; above it nothing is requested nor accepted' }, wait: { type: 'number', description: 'seconds to wait for the quote, 1 to 90 (default 25)' } } } },
+  { name: 'nyx5_libro', description: 'Move a deal forward in the ledger, leaving a signed, irreversible entry at every step: deliver, release the payment if the proof passed, refund if it failed, back a claim with money (you lose it if you lied), or delegate spending with a cap. ops: pay {to, amount, concept}, deliver {contract, evidence_sha256}, release {contract}, refund {contract}, reclaim {contract}, bond {amount, claim, verifier}, forfeit {contract, reason}, mandate {grantee, cap, scope, expires, parent}, charge {mandate, amount, concept}, revoke {mandate}, balance, statement {limit, since, until}, contract {contract}. The answer arrives as a signed receipt in your mailbox.',
+    inputSchema: { type: 'object', required: ['op'], properties: { house: { type: 'string', description: 'dominio de la casa; por defecto el propio' }, op: { type: 'string' }, args: { type: 'object' } } } },
+  { name: 'nyx5_balance', description: 'How much you hold, which contracts and which spending permissions are active. Check it before committing a payment. A direct read authenticated with your signature, without going through the mail. With since or until, your statement for that range: opening balance, every entry with the house fee as its own line, closing balance.',
+    inputSchema: { type: 'object', properties: { house: { type: 'string' }, since: { type: 'string', description: 'ISO-8601: statement from this date (inclusive)' }, until: { type: 'string', description: 'ISO-8601: statement up to this date (exclusive)' }, limit: { type: 'integer', description: 'statement: how many entries, newest kept (max 1000)' } } } },
+  { name: 'nyx5_remind', description: 'Leave yourself a message that reaches you in the future, in your own mailbox, encrypted. Use it when a task must be picked up in hours or days and your session will end before then: your future self finds the context with the full thread, without depending on anyone waking you.',
+    inputSchema: { type: 'object', required: ['cuando', 'body'], properties: { cuando: { type: 'string', description: 'ISO-8601: cuándo debe llegarte' }, body: { description: 'lo que tu yo futuro necesita saber' }, thread: { type: 'string' } } } },
+  { name: 'nyx5_contract', description: 'The state and full history of a deal you are party to: every step with its hash and its signature. Use it to see where an escrow or a bond stands.',
+    inputSchema: { type: 'object', required: ['contract'], properties: { house: { type: 'string' }, contract: { type: 'string' } } } },
+  { name: 'nyx5_historial', description: 'The reputation of an agent is its ledger: deliveries accepted against returned, bonds standing against forfeited, with amounts. Check it before hiring a stranger. Every point of it cost tokens and is tied to a verified delivery, so it cannot be inflated by talking; with no record it returns null (nothing yet, not perfect).',
+    inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'a quién mirar; por defecto, tú mismo' } } } },
+  { name: 'nyx5_tareas', description: 'Paid work a house publishes that you can take right now: what to do, what it pays, and the deterministic check it will be verified with. Use it when you just joined and have no record yet, or when you need tokens to back your own claims with a bond.',
+    inputSchema: { type: 'object', properties: { house: { type: 'string' } } } },
+  { name: 'nyx5_tomar', description: 'Take a published task: the house holds the payment in a signed entry before you work, and releases it on its own when the deterministic check passes. If it fails, it is refunded and stays in your record. Use it to earn your first tokens; terms are copied from the catalogue and are not negotiable.',
+    inputSchema: { type: 'object', required: ['id'], properties: { id: { type: 'string', description: 'id de la tarea, de nyx5_tareas' }, house: { type: 'string' } } } },
+  { name: 'nyx5_email', description: 'Write by email to a human who is not on Nyx5 yet. Use it when the recipient has no agent address: their reply comes back to your mailbox (Reply-To). It enters unsigned, marked as not verified, never disguised; when they want the real thing, they register.',
+    inputSchema: { type: 'object', required: ['to', 'body'], properties: { to: { type: 'string', description: 'dirección de correo, ej. persona@gmail.com' }, subject: { type: 'string' }, body: { description: 'el texto del correo' } } } },
+  { name: 'nyx5_wait', description: 'Wait, up to a limit, for the next message in your mailbox (optionally only from one sender or one thread) and get it opened, with its signature verified, the moment it lands. Use it right after sending when the other side is live: it is how two agents hold a real-time conversation instead of polling.',
+    inputSchema: { type: 'object', properties: { from: { type: 'string', description: 'only messages from this address' }, thread: { type: 'string', description: 'only messages in this thread' }, since: { type: 'string', description: 'ISO time: only messages received after it. Default: now, so earlier unread mail is never mistaken for the reply' }, project: { type: 'string', description: 'only messages of this project (see nyx5_send)' }, seconds: { type: 'number', description: 'how long to wait, 1 to 90 (default 60)' } } } },
+  { name: 'nyx5_conversation', description: 'The signed history between you and one address, both directions and oldest first, including what you already acknowledged; without an address, the list of your conversations, each with its projects and what is pending per project. Use it to pick up where you left off, from any device: the history lives in the house.',
+    inputSchema: { type: 'object', properties: { with: { type: 'string', description: 'the other address; omit it to list your conversations' }, limit: { type: 'number', description: 'how many messages, newest kept (default 30)' }, project: { type: 'string', description: 'only messages of this project (see nyx5_send)' } } } },
+  { name: 'nyx5_group', description: 'A group address (g.name@house): one signed message reaches every member, encrypted for each, with a shared history nobody outside can read. Use it when work involves several agents. ops: create {name, members, post}, members {group}, add {group, members}, remove {group, members}, leave {group}. Only members post; admins change members.',
+    inputSchema: { type: 'object', required: ['op'], properties: { op: { type: 'string', enum: ['create', 'members', 'add', 'remove', 'leave'] }, name: { type: 'string', description: 'create: the group name (becomes g.name@house)' }, group: { type: 'string', description: 'the group address or name' }, members: { type: 'array', items: { type: 'string' }, description: 'addresses of this house' }, post: { type: 'string', enum: ['members', 'admins'], description: 'who can post (default members)' } } } },
+  { name: 'nyx5_profile', description: 'What an agent says about itself, certified by its house: name, what it does, languages, owner, tags, links, and what it sells at what price and contract. Read it before hiring a stranger (declared, not verified: the ledger record is). Set yours so others find you. ops: get {address}, set {profile} (an unknown key is rejected by name).',
+    inputSchema: { type: 'object', required: ['op'], properties: { op: { type: 'string', enum: ['get', 'set'] }, address: { type: 'string', description: 'get: whose profile (default: yours)' }, profile: { type: 'object', description: 'set: { display_name, summary, description, languages, tags, owner: {kind, name}, links, services: [{ id, name, summary, price: {tokens, usd?}, unit: job|call|hour, contract: spot|escrow|metered, acceptance?: {kind, template} }] }; null clears it' } } } },
+  { name: 'nyx5_notarize', description: 'Seal the hash of a document in the house ledger: a signed, dated record that anyone can verify later without an account. Use it before sharing work whose date or integrity may be disputed (a report, a dataset, an offer). Free; the same hash sealed twice by you returns the same seal. The seal arrives as a signed receipt.',
+    inputSchema: { type: 'object', required: ['sha256'], properties: { sha256: { type: 'string', description: 'hex sha256 of the document (64 characters)' }, name: { type: 'string' }, media: { type: 'string' }, note: { type: 'string' }, house: { type: 'string', description: 'house that seals; by default your own' } } } },
+  { name: 'nyx5_notarized', description: 'Verify a document hash against the house notary: the seals on it, who declared it and when, each signed by the house and checked against its domain card. Use it when someone claims a document existed at a date: the seal proves the hash was declared no later than then. No account needed.',
+    inputSchema: { type: 'object', required: ['sha256'], properties: { sha256: { type: 'string', description: 'hex sha256 of the document (64 characters)' }, house: { type: 'string', description: 'house to ask; by default your own' } } } },
+  // ----- qa@ como servicio (NX-606): dos envoltorios de nyx5_send con el media correcto -----
+  { name: 'nyx5_qa_spec', description: 'Turn a request into an acceptance contract: qa@<house> replies with numbered, checkable criteria and the sha256 of its text so you can seal it in the notary. Use it before delegating work whose "done" could be disputed. Paid from credit you pay to qa@ beforehand; the reply lands signed in your mailbox.',
+    inputSchema: { type: 'object', required: ['request'], properties: { to: { type: 'string', description: 'the qa address; default qa@<your house>' }, request: { type: 'string', description: 'what you want done, in your words' } } } },
+  { name: 'nyx5_qa_gate', description: 'Have a delivery judged against a sealed acceptance contract: qa@<house> answers pass, fail or abstain per criterion as JSON signed by the house. Use it before releasing an escrow. The contract hash must be sealed in the notary first; otherwise it is rejected before any cost. Abstention costs half.',
+    inputSchema: { type: 'object', required: ['spec_sha256', 'spec', 'delivery'], properties: { to: { type: 'string', description: 'the qa address; default qa@<your house>' }, spec_sha256: { type: 'string', description: 'hex sha256 of the contract text, already sealed with nyx5_notarize' }, spec: { type: 'string', description: 'the exact contract text (its sha256 must be spec_sha256)' }, delivery: { type: 'object', required: ['text'], properties: { text: { type: 'string', description: 'the delivery to judge (qa@ does not fetch urls)' }, url: { type: 'string' }, sha256: { type: 'string' } } }, note: { type: 'string' } } } },
+  // ----- NX-502: pedido de pago por transferencia (dinero real, fuera del Libro; NO en el remoto) -----
+  { name: 'nyx5_payment_request', description: 'Ask someone for a real-money bank transfer (Chile: CLP or USD). The account details travel encrypted to that person only; the house never sees nor holds them, and their signed confirmation with the bank reference reaches your mailbox when they pay. Use it to get paid outside the ledger. Nyx5 never touches the money.',
+    inputSchema: { type: 'object', required: ['to', 'amount', 'name', 'rut', 'bank', 'account_type', 'account_number'], properties: {
+      to: { type: 'string', description: 'address of who pays (a person, not a connected Claude: the house holds those keys)' },
+      amount: { type: ['string', 'number'], description: 'CLP: whole pesos, e.g. 15000; USD: up to two decimals, e.g. "12.50"' },
+      currency: { type: 'string', enum: MONEDAS, default: 'CLP' },
+      name: { type: 'string', description: 'name on the account (up to 120 characters)' }, rut: { type: 'string', description: 'RUT with its check digit, e.g. 12.345.678-5' },
+      bank: { type: 'string', description: 'bank name (up to 60 characters)' }, account_type: { type: 'string', enum: TIPOS_CUENTA },
+      account_number: { type: 'string', description: 'digits and dashes, up to 30' }, reference: { type: 'string', description: 'what this is for (up to 140 characters)' },
+      thread: { type: 'string' } } } },
+  { name: 'nyx5_payment_confirm', description: 'Tell whoever sent you a payment request that you paid it from your bank: your confirmation with the bank reference travels encrypted and signed, in reply to their request, so they hold your word and nothing else. Use it right after you made the transfer yourself. Nyx5 does not move the money and does not check the bank.',
+    inputSchema: { type: 'object', required: ['in_reply_to', 'bank_reference'], properties: {
+      in_reply_to: { type: 'string', description: 'id of the payment request envelope (media nyx5.cobro) in your mailbox' },
+      from: { type: 'string', description: 'who sent it, if you already acknowledged it (to find it in the conversation)' },
+      bank_reference: { type: 'string', description: 'the transfer reference your bank gave you (up to 80 characters)' } } } },
+  // ----- NX-413: adjuntos cifrados. La descripción dice el límite y qué NO sale del cifrado: es
+  // lo único que un agente lee antes de decidir qué expone. -----
+  { name: 'nyx5_attach', description: 'Encrypt a file so a message carries it for real: the recipient downloads it with their signature and checks the hash. Use it when you say "here are the files" and the other agent is on another machine. Up to 10 MB; the key never leaves the encrypted block, so the house holds bytes it cannot read.',
+    inputSchema: { type: 'object', required: ['name', 'to'], properties: {
+      name: { type: 'string', description: 'file name the recipient will see (max 120 chars); it travels INSIDE the encrypted block' },
+      to: { type: 'array', items: { type: 'string' }, description: 'addresses allowed to download it: the same recipients you will send the envelope to' },
+      path: { type: 'string', description: 'local file to read (this bridge runs beside you); use it or content' },
+      content: { type: 'string', description: 'the file content when you have it in hand, not on disk' },
+      base64: { type: 'boolean', description: 'true if content is base64 (a binary file)' },
+      media: { type: 'string', description: 'media type like application/pdf (default application/octet-stream)' } } } },
+  { name: 'nyx5_attachment', description: 'Download an attachment that arrived in an envelope and get the real bytes: it is decrypted with the key that came inside the encrypted block and rejected if the sha256 of the plaintext does not match what the sender signed. Use it when a message says it carries files, before acting on them.',
+    inputSchema: { type: 'object', required: ['id'], properties: {
+      id: { type: 'string', description: 'id of the envelope that carries it (nyx5_inbox or nyx5_conversation)' },
+      from: { type: 'string', description: 'who sent it, if you already acknowledged the envelope' },
+      blob: { type: 'string', description: 'which attachment, when the envelope carries several (default: all of them)' },
+      out_dir: { type: 'string', description: 'directory to write the files into (default: the current one)' } } } },
+  { name: 'nyx5_whoami', description: 'Your own address and what it may do: who delegated it, until when, whether the house holds its keys, and who may write to it. Check it before promising anything on behalf of your owner; the card is certified by the domain.',
+    inputSchema: { type: 'object', properties: {} } },
+];
+
+// Anotaciones MCP: le dicen al cliente qué herramienta sólo LEE. Claude las usa para decidir cuándo
+// pedir permiso (y el directorio oficial de conectores las exige). Son pistas, no garantías: la casa
+// sigue haciendo cumplir cada límite por su cuenta. Nació de un reporte de Nicholas: conectar desde
+// el teléfono le pidió tres permisos (inbox, send, wait) antes del primer mensaje.
+const SOLO_LECTURA = new Set(['nyx5_inbox', 'nyx5_resolve', 'nyx5_outbox', 'nyx5_directory', 'nyx5_search', 'nyx5_balance', 'nyx5_contract', 'nyx5_historial', 'nyx5_tareas', 'nyx5_wait', 'nyx5_conversation', 'nyx5_notarized', 'nyx5_whoami']);
+// `nyx5_attach` ESCRIBE en la casa (sube un objeto y gasta cupo) y `nyx5_attachment` escribe en el
+// disco de quien corre el puente: ninguna de las dos es de sólo lectura, aunque no mueva dinero.
+const MUEVE_DINERO = new Set(['nyx5_accept', 'nyx5_libro', 'nyx5_tomar', 'nyx5_hire']);
+const TITULOS = { nyx5_attach: 'Attach a file', nyx5_attachment: 'Download an attachment', nyx5_send: 'Send a message', nyx5_inbox: 'Read my mailbox', nyx5_ack: 'Mark messages as handled', nyx5_resolve: 'Check who an address is', nyx5_outbox: 'Delivery status of what I sent', nyx5_directory: 'Agents in a house', nyx5_search: 'Find an agent', nyx5_quote: 'Offer a service', nyx5_accept: 'Accept an offer and pay', nyx5_hire: 'Hire a published service', nyx5_libro: 'Ledger operation', nyx5_balance: 'My balance', nyx5_remind: 'Remind myself later', nyx5_contract: 'A deal and its history', nyx5_historial: 'Reputation of an agent', nyx5_tareas: 'Paid tasks available', nyx5_tomar: 'Take a paid task', nyx5_email: 'Email a person', nyx5_wait: 'Wait for a reply', nyx5_conversation: 'Conversation history', nyx5_group: 'Group of agents', nyx5_profile: 'Public profile', nyx5_notarize: 'Seal a document hash', nyx5_notarized: 'Verify a document seal', nyx5_whoami: 'Who am I', nyx5_qa_spec: 'Ask qa@ for an acceptance contract', nyx5_qa_gate: 'Ask qa@ to judge a delivery', nyx5_payment_request: 'Request a payment', nyx5_payment_confirm: 'Confirm a payment' };
+for (const t of TOOLS) {
+  t.title = TITULOS[t.name] || t.name;
+  t.annotations = { title: t.title, readOnlyHint: SOLO_LECTURA.has(t.name), destructiveHint: MUEVE_DINERO.has(t.name), idempotentHint: SOLO_LECTURA.has(t.name) || t.name === 'nyx5_ack' || t.name === 'nyx5_notarize', openWorldHint: true };
+}
+
+// Lo que el conector remoto expone: mensajería y nada que mueva saldo. El subagente de un teléfono
+// es de alcance `messages_only` (la casa se lo niega igual si lo intenta); ofrecerle herramientas
+// que van a fallar sólo le enseñaría al modelo a prometer lo que no puede cumplir.
+// Tampoco el pedido de pago (NX-502): la llave del subagente vive en la bóveda y la casa cifraría en
+// su nombre, o sea que el RUT y la cuenta pasarían por la casa en claro. Va sólo por el puente local.
+export const MENSAJERIA = new Set(['nyx5_send', 'nyx5_inbox', 'nyx5_ack', 'nyx5_resolve', 'nyx5_outbox', 'nyx5_directory', 'nyx5_search', 'nyx5_remind', 'nyx5_historial', 'nyx5_wait', 'nyx5_conversation', 'nyx5_group', 'nyx5_qa_spec', 'nyx5_qa_gate', 'nyx5_whoami']);
+
+export const INSTRUCCIONES = `Nyx5 gives an agent three things it has no other way of getting: an address of its own, a mailbox that holds while it is off, and a ledger where an agreement carries weight (payment is held until the proof passes; a false claim forfeits its bond). Use it to reach an agent that may not be available now, to find someone who does X in any house, or to close a deal that must be worth more than a promise. Before trusting a stranger, read their record: it is a query on the ledger, so every point of it cost tokens. Every message is signed and every movement of money leaves a receipt no party can deny. Tag what you send with a project name and filter by it to keep several chats apart.`;
+
+export function instrucciones({ remoto = false, address = null, contactos = [] } = {}) {
+  if (!remoto) return INSTRUCCIONES;
+  // Sus contactos van aquí para que el dueño pueda decir "escríbele a Nico" sin dictar direcciones.
+  const extra = contactos.length ? ` Your contacts, who can write to you and whom you can reach: ${contactos.join(', ')}. When your owner names one of them, write to their Claude (claude.<name>@<house>) if it is on this list.` : '';
+  // Lo que este camino NO puede hacer, dicho en voz alta (NX-808). MENSAJERIA excluye las
+  // herramientas de adjunto a propósito: la casa guarda esta llave, así que el archivo le pasaría
+  // en claro por delante. Callarlo dejaba al recién llegado concluyendo que Nyx5 no manda archivos.
+  // Texto aprobado por Nicholas el 3-nov-2026, palabra por palabra: no se edita sin volver a él.
+  const limites = 'This connector cannot send files: the house holds this key, so an attachment would pass through it in the clear.'
+    + " Because it holds this key, the house can also read this sub-agent's messages — your root key never passes through it."
+    + ' To send files, run `npx @nyx5/nyx5 join` once; the attachment tools come with a key only you hold.';
+  return `You act through ${address}, a messages-only address your owner delegated to you. You can send signed messages to any agent address, read your mailbox, and wait for a reply live, which is how you hold a real-time conversation with another agent. You cannot move money or operate the ledger. The house holds this key on behalf of your owner, who can revoke it at any time. ${limites} Before trusting a stranger, check who they really are: every card is certified by its domain.${extra}`;
+}
+
+export async function llamar(agent, name, args = {}, { permitidas = null, esperaMaxS = 90 } = {}) {
+  const text = (v) => ({ content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v, null, 2) }] });
+  if (permitidas && !permitidas.has(name)) return { ...text(`${name} is not available here: this is a messages-only address (no ledger, no payments)`), isError: true };
+  switch (name) {
+    case 'nyx5_send': { const r = await agent.send({ to: args.to, body: args.body, type: args.type, thread: args.thread, inReplyTo: args.in_reply_to, encrypt: args.encrypt ?? true, project: args.project, role: args.role, summary: args.summary, extensions: args.aval ? { 'urn:nyx5:ext:aval': args.aval } : undefined }); return text({ id: r.id, jobs: r.jobs, encrypted: r.encrypted, summary: r.envelope?.extensions?.['urn:nyx5:ext:resumen']?.text ?? null }); }
+    case 'nyx5_inbox': {
+      // La MISMA normalización que al enviar y que la casa (NFKC, sin invisibles): `trim().toLowerCase()`
+      // dejaba pasar un homógrafo por el filtro del puente mientras la casa lo colapsaba (14-sep-2026).
+      const proyecto = args.project ? nombreDeProyecto(args.project) : null;
+      const msgs = (await agent.inbox({ limit: args.limit ?? 20 })).filter((m) => !proyecto || proyectoDe(m.envelope) === proyecto);
+      const opened = [];
+      // `received` es la hora que entiende `since` de nyx5_wait (la de llegada al buzón, no la de
+      // creación): sin exponerla, el filtro no se podía usar bien (defecto reportado el 12-sep-2026).
+      for (const m of msgs) { try { const { sender, ...o } = await agent.open(m.envelope); opened.push({ ...o, received: m.received }); } catch (e) { opened.push({ id: m.envelope.id, from: m.envelope.from, error: e.message, received: m.received }); } }
+      return text(opened);
+    }
+    case 'nyx5_ack': return text({ acked: await agent.ack(args.ids) });
+    case 'nyx5_resolve': { const { _domain, ...card } = await agent.resolver.agentCard(args.address, { onBehalfOf: agent.address }); const last_seen = await agent.presence(args.address); return text({ ...card, ...(last_seen ? { presence: { last_seen } } : {}) }); }
+    case 'nyx5_outbox': return text(await agent.outbox());
+    case 'nyx5_directory': return text(await agent.directory(args.house, args));
+    case 'nyx5_search': return text(await agent.search(args.index, args));
+    case 'nyx5_quote': {
+      if (args.in_reply_to) {
+        // Contestar un pedido (NX-305): la cotización sale de la ficha y del input del pedido, en su hilo.
+        const pedido = await agent.pedido(args.in_reply_to, args.to || null);
+        if (!pedido) return { ...text(`no service request with id ${args.in_reply_to} in your mailbox (pass to if you already acknowledged it)`), isError: true };
+        const r = await agent.quoteFromCatalog(pedido, { service: args.service ?? null });
+        return text({ id: r.id, quote_id: r.quote.id, contract: r.quote.contract, price: r.quote.price, service: r.quote.service, arbiter: r.quote.arbiter || null, verify: r.quote.terms?.verify || null, in_reply_to: pedido.id });
+      }
+      if (args.service == null && (args.price == null || args.concept == null)) return { ...text('nyx5_quote needs price and concept, or a service id from your profile'), isError: true }; const r = await agent.quote({ to: args.to, contract: args.contract, price: args.price, concept: args.concept, terms: args.terms, arbiter: args.arbiter, expires: args.expires, referrer: args.referrer, service: args.service }); return text({ id: r.id, quote_id: r.quote.id, contract: r.quote.contract, price: r.quote.price, ...(r.quote.service ? { service: r.quote.service } : {}) }); }
+    case 'nyx5_accept': { const r = await agent.accept(args.quote); return text({ id: r.id, note: 'el recibo de libro@ llegará al buzón (nyx5_inbox)' }); }
+    case 'nyx5_hire': return text(await agent.hire({ agent: args.agent, service: args.service, input: args.input ?? {}, note: args.note, autoAccept: args.auto_accept ?? true, maxPrice: args.max_price ?? null, wait: Math.max(1, Math.min(Number(args.wait ?? 25) || 25, esperaMaxS)) }));
+    case 'nyx5_libro': { const r = await agent.libroOp(args.house || agent.domain, { op: args.op, ...(args.args || {}) }); return text({ id: r.id, note: 'la respuesta llega como recibo de libro@ al buzón' }); }
+    case 'nyx5_balance': return text(args.since || args.until ? await agent.statement(args.house, { since: args.since, until: args.until, limit: args.limit }) : await agent.balance(args.house));
+    case 'nyx5_remind': { const r = await agent.recordar({ cuando: args.cuando, body: args.body, thread: args.thread }); return text({ id: r.id, note: `te llegará a tu buzón el ${args.cuando}` }); }
+    case 'nyx5_historial': return text(await agent.historial(args.address || agent.address));
+    case 'nyx5_tareas': {
+      const dc = await agent.resolver.domainCard(args.house || agent.domain);
+      const res = await agent.fetch(`${dc._estafeta}/tareas`);
+      const j = await res.json();
+      if (!res.ok) return text({ error: j.reason || `HTTP ${res.status}` });
+      return text(j);
+    }
+    case 'nyx5_tomar': {
+      const dc = await agent.resolver.domainCard(args.house || agent.domain);
+      const j = await (await agent.fetch(`${dc._estafeta}/tareas`)).json();
+      const t = (j.tasks || j.tareas || []).find((x) => x.id === args.id);
+      if (!t) return text({ error: `no task with id ${args.id}`, available: (j.tasks || j.tareas || []).map((x) => x.id) });
+      const enviada = await agent.quote({ to: (j.desk || j.mostrador), contract: 'escrow', price: t.price, concept: t.concept, arbiter: (j.arbiter || j.arbitro), terms: t.terms });
+      return text({ enviada: enviada.id, tarea: t.id, price: t.price, siguiente: 'si hay cupo, el contrato te llega al buzón (nyx5_inbox); al terminar, nyx5_libro op=deliver' });
+    }
+    case 'nyx5_email': { const r = await agent.email({ to: args.to, subject: args.subject, body: args.body }); return text(r); }
+    case 'nyx5_contract': return text(await agent.contract(args.house || agent.domain, args.contract));
+    case 'nyx5_wait': {
+      const secs = Math.max(1, Math.min(Number(args.seconds ?? 60) || 60, esperaMaxS));
+      // Sin `since`, se espera lo que llegue DESDE AHORA. Defecto real (12-sep-2026): devolvía como
+      // "respuesta" un mensaje viejo que ya estaba en el buzón, y el que espera daba por contestada
+      // una conversación que no lo estaba. Lo pendiente de antes se avisa, no se confunde con lo nuevo.
+      // Lo que YA estaba sin leer se entrega igual (nada se pierde), pero marcado como anterior a la
+      // espera, para que nadie lo tome por la respuesta a lo que acaba de mandar.
+      const desde = args.since || new Date().toISOString();
+      const anterior = args.since ? null : (await agent.inbox({ limit: 50 })).find((m) => m.received < desde && (!args.from || m.envelope?.from === args.from) && (!args.thread || m.envelope?.thread === args.thread || m.envelope?.id === args.thread) && (!args.project || proyectoDe(m.envelope) === nombreDeProyecto(args.project)));
+      const m = anterior || await agent.wait({ from: args.from, thread: args.thread, since: desde, project: args.project, seconds: secs });
+      if (!m) return text({ message: null, waited_seconds: secs, note: 'nothing arrived; call again to keep listening' });
+      let abierto;
+      try { const { sender, ...o } = await agent.open(m.envelope); abierto = o; } catch (e) { abierto = { id: m.envelope.id, from: m.envelope.from, error: e.message }; }
+      return text({ ...abierto, received: m.received, ...(anterior ? { arrived_before_wait: true, note: 'this message was already unread in your mailbox before you started waiting: if you expected a reply to something you just sent, this is probably not it. Pass since (its received time) to wait only for newer mail.' } : {}) });
+    }
+    case 'nyx5_conversation': {
+      if (!args.with) return text(await agent.conversations({ project: args.project || null }));
+      const msgs = await agent.conversation(args.with, { limit: args.limit ?? 30, project: args.project || null });
+      const out = [];
+      for (const m of msgs) {
+        try { const { sender, ...o } = await agent.open(m.envelope); out.push({ dir: m.dir, at: m.at, status: m.status, ...o }); }
+        catch (e) { out.push({ dir: m.dir, at: m.at, id: m.envelope?.id, from: m.envelope?.from, error: e.message }); }
+      }
+      return text(out);
+    }
+    case 'nyx5_group': {
+      const op = args.op;
+      if (op === 'create') return text(await agent.createGroup(args.name, { members: args.members || [], post: args.post }));
+      if (op === 'members') return text(await agent.group(args.group));
+      if (op === 'add') return text(await agent.editGroup(args.group, { add: args.members || [] }));
+      if (op === 'remove') return text(await agent.editGroup(args.group, { remove: args.members || [] }));
+      if (op === 'leave') return text(await agent.leaveGroup(args.group));
+      return { ...text(`unknown group op: ${op}. Valid ones: create, members, add, remove, leave`), isError: true };
+    }
+    case 'nyx5_profile': {
+      if (args.op === 'get') return text(await agent.profile(args.address || agent.address));
+      if (args.op === 'set') return text(await agent.setProfile(args.profile === undefined ? null : args.profile));
+      return { ...text(`unknown profile op: ${args.op}. Valid ones: get, set`), isError: true };
+    }
+    case 'nyx5_notarize': { const r = await agent.notarize(args.house || agent.domain, { sha256: args.sha256, name: args.name, media: args.media, note: args.note }); return text({ id: r.id, note: 'the seal arrives as a signed receipt from libro@ in your mailbox (nyx5_inbox)' }); }
+    case 'nyx5_notarized': { const r = await agent.notarized(args.sha256, args.house || agent.domain); return text(r || { sha256: String(args.sha256).toLowerCase(), seals: [], note: 'no seal for this hash in this house' }); }
+    // qa@ (NX-606): mensajes, no Libro. El `pay` previo que carga el crédito va por nyx5_libro.
+    case 'nyx5_qa_spec': {
+      if (typeof args.request !== 'string' || !args.request.trim()) return { ...text('nyx5_qa_spec needs request: what you want done'), isError: true };
+      const to = args.to || `qa@${agent.domain}`;
+      const r = await agent.send({ to: [to], body: args.request });
+      return text({ id: r.id, to, note: `the contract arrives as a message from ${to} (nyx5_wait with from=${to}); its footer carries the sha256 to seal with nyx5_notarize` });
+    }
+    case 'nyx5_qa_gate': {
+      if (typeof args.spec !== 'string' || typeof args.spec_sha256 !== 'string' || typeof args.delivery?.text !== 'string') return { ...text('nyx5_qa_gate needs spec_sha256, spec (the exact sealed text) and delivery.text'), isError: true };
+      const to = args.to || `qa@${agent.domain}`;
+      const r = await agent.send({ to: [to], media: MEDIA_GATE, body: { spec_sha256: args.spec_sha256, spec: args.spec, delivery: { text: args.delivery.text, url: args.delivery.url, sha256: args.delivery.sha256 }, note: args.note } });
+      return text({ id: r.id, to, note: `the verdict arrives as a message from ${to} (nyx5_wait with from=${to}): JSON signed by the house, pass | fail | abstain` });
+    }
+    // NX-502: dinero real fuera del Libro. El cliente valida (RUT, monto), exige cifrado y se niega
+    // ante una dirección cuya llave guarda la casa; la casa sólo anota el evento sin monto.
+    case 'nyx5_payment_request': {
+      const r = await agent.paymentRequest({ to: args.to, amount: args.amount, currency: args.currency, name: args.name, rut: args.rut, bank: args.bank, account_type: args.account_type, account_number: args.account_number, reference: args.reference, thread: args.thread });
+      return text({ id: r.id, request_id: r.request_id, to: r.to, currency: r.currency, encrypted: r.encrypted, note: `their confirmation arrives as a message from ${r.to} with media ${MEDIA_COBRO_CONFIRMACION} (nyx5_wait with from=${r.to}); Nyx5 never touches the money` });
+    }
+    case 'nyx5_payment_confirm': {
+      const pedido = await agent.cobro(args.in_reply_to, args.from || null);
+      if (!pedido) return { ...text(`no payment request with id ${args.in_reply_to} in your mailbox (pass from if you already acknowledged it)`), isError: true };
+      const r = await agent.paymentConfirm(pedido, { bank_reference: args.bank_reference });
+      return text({ id: r.id, request_id: r.request_id, to: r.to, in_reply_to: r.in_reply_to, encrypted: r.encrypted, note: 'sent encrypted; Nyx5 does not move money, it only carries your confirmation' });
+    }
+    // NX-413. Sólo por el puente LOCAL: leer y escribir archivos exige un disco al lado del modelo,
+    // y en el remoto la llave del subagente vive en la bóveda, o sea que la casa cifraría en su
+    // nombre y el archivo pasaría por ella en claro. MENSAJERIA no las incluye.
+    case 'nyx5_attach': {
+      const fs = await import('node:fs');
+      if (!args.path && args.content == null) return { ...text('nyx5_attach needs path (a local file) or content'), isError: true };
+      const datos = args.path ? fs.readFileSync(args.path) : Buffer.from(String(args.content), args.base64 ? 'base64' : 'utf8');
+      const nombre = args.name || (args.path ? String(args.path).split('/').pop() : null);
+      const att = await agent.subirAdjunto(datos, { name: nombre, media: args.media, to: args.to || [] });
+      // La llave se devuelve porque es lo que hay que pasarle a nyx5_send; va al mismo turno del
+      // modelo que ya tiene el archivo, y de ahí entra al bloque cifrado del sobre, no al sobre.
+      return text({ attachment: att, note: `pass it in nyx5_send attachments; the key travels inside the encrypted block, so send it encrypted (encrypt: true, the default) or the house can open the file` });
+    }
+    case 'nyx5_attachment': {
+      const fs = await import('node:fs');
+      const sobre = await agent.conAdjuntos(args.id, args.from || null);
+      if (!sobre) return { ...text(`no envelope with id ${args.id} in your mailbox (pass from if you already acknowledged it)`), isError: true };
+      const dir = args.out_dir || '.';
+      const out = [];
+      for (const att of sobre.attachments) {
+        if (args.blob && String(att.blob).toLowerCase() !== String(args.blob).toLowerCase()) continue;
+        try {
+          const datos = await agent.bajarAdjunto(att, { from: sobre.from });
+          // El nombre lo escribe el REMITENTE: se usa sólo su parte final, nunca como ruta.
+          const destino = `${dir.replace(/\/$/, '')}/${String(att.name).split('/').pop()}`;
+          fs.mkdirSync(dir, { recursive: true });
+          fs.writeFileSync(destino, datos);
+          out.push({ name: att.name, media: att.media, bytes: datos.length, sha256_ok: true, path: destino });
+        } catch (e) { out.push({ name: att.name, blob: att.blob, error: e.message }); }
+      }
+      return text(out.length ? out : { error: `envelope ${args.id} carries no attachment with blob ${args.blob}` });
+    }
+    case 'nyx5_whoami': return text(await agent.whoami());
+    default: return { ...text(`unknown tool: ${name}`), isError: true };
+  }
+}