@nyx5/nyx5 0.5.0 → 0.7.0

package/src/puentes/herramientas.js

@@ -0,0 +1,190 @@
+// 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 } from '../correo/politica.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")' },
+      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 reply may have landed between sessions.',
+    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' } } } } } },
+  { 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_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. Use it to pick up where a conversation was left, from any device: the history lives in the house, not in your session.',
+    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' } } } },
+  { 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']);
+const MUEVE_DINERO = new Set(['nyx5_accept', 'nyx5_libro', 'nyx5_tomar']);
+const TITULOS = { 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_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' };
+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.
+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_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.` : '';
+  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. 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, extensions: args.aval ? { 'urn:nyx5:ext:aval': args.aval } : undefined }); return text({ id: r.id, jobs: r.jobs, encrypted: r.encrypted }); }
+    case 'nyx5_inbox': {
+      const proyecto = args.project ? String(args.project).trim().toLowerCase() : 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.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_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) === String(args.project).trim().toLowerCase()));
+      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' }); }
+    case 'nyx5_whoami': return text(await agent.whoami());
+    default: return { ...text(`unknown tool: ${name}`), isError: true };
+  }
+}

package/src/puentes/mcp-remoto.js

@@ -0,0 +1,71 @@
+// Nyx5/1 — Puente MCP remoto: el mismo conjunto de herramientas, por Streamable HTTP en /mcp.
+//
+// Es lo que deja a cualquier Claude (claude.ai en el navegador, Desktop, el teléfono) usar Nyx5
+// agregando una URL, sin instalar nada. Cada llamada llega con un token OAuth que apunta a un
+// subagente delegado cuya llave guarda la casa (ver src/puentes/oauth.js); el puente arma ese
+// agente en el mismo proceso y ejecuta la herramienta con él. Nunca con la llave del dueño.
+//
+// Del transporte (MCP 2025-06-18 / 2025-11-25) se usa lo mínimo que un servidor de sólo
+// herramientas necesita: un POST por mensaje JSON-RPC, respuesta application/json, 202 para
+// notificaciones, 405 al GET (no hay flujo iniciado por el servidor) y sin sesión: cada petición
+// trae su token, así que no hay estado que perder entre instancias del edge.
+import { TOOLS, MENSAJERIA, llamar, instrucciones } from './herramientas.js';
+import { validarAcceso } from './oauth.js';
+import { VERSION } from '../version.js';
+
+export const VERSIONES = ['2025-11-25', '2025-06-18', '2025-03-26'];
+const HERRAMIENTAS = TOOLS.filter((t) => MENSAJERIA.has(t.name));
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+// Un Origin presente tiene que ser un origen real: el spec pide 403 ante uno inválido (protección
+// contra DNS rebinding). No se exige una lista cerrada: la protección de fondo es el token.
+function origenValido(o) {
+  try { const u = new URL(o); return u.protocol === 'https:' || (u.protocol === 'http:' && LOOPBACK.has(u.hostname)); }
+  catch { return false; }
+}
+
+export async function atenderMcp(est, rx) {
+  if (rx.method !== 'POST') return { status: 405, headers: { allow: 'POST' }, body: { reason: 'this MCP endpoint takes POST only; it does not open a server-initiated stream' } };
+  if (rx.headers.origin !== undefined && !origenValido(rx.headers.origin)) return { status: 403, body: { reason: 'invalid Origin header' } };
+  const acceso = await validarAcceso(est, rx);
+  if (!acceso.ok) return acceso.out;
+  const pv = rx.headers['mcp-protocol-version'];
+  if (pv && !VERSIONES.includes(pv)) return { status: 400, body: { jsonrpc: '2.0', id: null, error: { code: -32600, message: `unsupported MCP-Protocol-Version ${pv}; supported: ${VERSIONES.join(', ')}` } } };
+  const sub = acceso.token.sub;
+  if (!await est.remotoRate.allow(`mcp:${sub}`)) return { status: 429, headers: est._retryAfter(), body: { jsonrpc: '2.0', id: null, error: { code: -32000, message: 'too many requests; slow down' } } };
+
+  const msg = rx.body;
+  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return { status: 400, body: { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'send exactly one JSON-RPC message per POST' } } };
+  // Notificación (sin id) o respuesta del cliente: se acepta y no se contesta nada.
+  if (msg.id === undefined || msg.id === null || typeof msg.method !== 'string') return { status: 202, contentType: 'application/json', body: '' };
+
+  const { id, method, params } = msg;
+  const ok = (result, extra = {}) => ({ status: 200, body: { jsonrpc: '2.0', id, result }, ...extra });
+  switch (method) {
+    case 'initialize': {
+      const pedida = params?.protocolVersion;
+      const propia = `${sub}@${est.domain}`;
+      const contactos = ((await est.store.getAgent(sub))?.inbox?.allowlist || []).filter((x) => x !== propia);
+      return ok({
+        protocolVersion: VERSIONES.includes(pedida) ? pedida : '2025-06-18',
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'nyx5', title: 'Nyx5', version: VERSION },
+        instructions: instrucciones({ remoto: true, address: propia, contactos }),
+      });
+    }
+    case 'ping': return ok({});
+    case 'tools/list': return ok({ tools: HERRAMIENTAS });
+    case 'tools/call': {
+      const agent = await est.agenteDeBoveda(sub);
+      if (!agent) return (await validarAcceso(est, { headers: {} })).out;
+      let result;
+      // Un error de la herramienta vuelve como resultado con isError (el modelo puede corregirse),
+      // no como error del protocolo (spec 2025-11-25).
+      try { result = await llamar(agent, params?.name, params?.arguments || {}, { permitidas: MENSAJERIA, esperaMaxS: 90 }); }
+      catch (e) { result = { content: [{ type: 'text', text: `error: ${e.message}` }], isError: true }; }
+      // kick: lo que la herramienta dejó en la cola sale ya, no en el próximo minuto del cron.
+      return ok(result, { kick: true });
+    }
+    default: return { status: 200, body: { jsonrpc: '2.0', id, error: { code: -32601, message: `method not supported: ${method}` } } };
+  }
+}

package/src/puentes/mcp.js

@@ -6,113 +6,19 @@
 
 import readline from 'node:readline';
 import { Agent } from '../correo/agente.js';
+import { TOOLS, llamar, INSTRUCCIONES } from './herramientas.js';
+import { VERSION } from '../version.js';
 
-// La versión la dice el paquete, no un literal: un servidor que reporta una versión que no es
-// la suya hace imposible depurar "en qué versión pasó esto". Si no se puede leer, se declara
-// desconocida en vez de inventar un número.
-let VERSION = '0.0.0-unknown';
-try {
-  const { readFileSync } = await import('node:fs');
-  VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version || VERSION;
-} catch {}
+export { TOOLS };
 
 const PROTOCOL = '2025-06-18';
 const SUPPORTED = new Set(['2025-06-18', '2025-03-26']);
 
-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 recipient verifies it is really you, and nobody else can read the content (encrypted).',
-    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' },
-      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 reply may have landed between sessions.',
-    inputSchema: { type: 'object', properties: { limit: { type: 'integer', default: 20 } } } },
-  { 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, not just yours. Use it when you know nobody who solves your problem. The index answers signed and you verify the card before trusting: it is a hint, not an authority.',
-    inputSchema: { type: 'object', required: ['index'], properties: { index: { type: 'string', description: 'dominio de la casa del índice, o URL' }, q: { type: 'string' }, capability: { type: 'string' }, accepts: { type: 'string' }, house: { type: 'string' }, limit: { type: 'integer' } } } },
-  // ----- 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.',
-    inputSchema: { type: 'object', required: ['to', 'price', 'concept'], properties: {
-      to: { type: 'string' }, contract: { type: 'string', enum: ['spot', 'escrow', 'metered'], default: 'spot' },
-      price: { type: 'integer', description: 'tokens, entero' }, concept: { type: 'string' },
-      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' } } } } } },
-  { 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_libro', description: 'Move a deal forward in the ledger, leaving a signed and 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: deliver {contract, evidence_sha256}, release {contract}, refund {contract}, bond {amount, claim, verifier}, forfeit {contract, reason}, mandate {grantee, cap, scope, expires, parent}, charge {mandate, amount, concept}, revoke {mandate}, balance, statement {limit}, 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.',
-    inputSchema: { type: 'object', properties: { house: { type: 'string' } } } },
-  { 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' } } } },
-];
-
 export async function runMcpServer({ agentFile, hosts = {} }) {
   const agent = await Agent.load(agentFile, { hosts });
   const out = (msg) => process.stdout.write(JSON.stringify(msg) + '\n');
   const text = (v) => ({ content: [{ type: 'text', text: typeof v === 'string' ? v : JSON.stringify(v, null, 2) }] });
-
-  async function call(name, args = {}) {
-    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, extensions: args.aval ? { 'urn:nyx5:ext:aval': args.aval } : undefined }); return text({ id: r.id, jobs: r.jobs }); }
-      case 'nyx5_inbox': {
-        const msgs = await agent.inbox({ limit: args.limit ?? 20 });
-        const opened = [];
-        for (const m of msgs) { try { opened.push(await agent.open(m.envelope)); } catch (e) { opened.push({ id: m.envelope.id, from: m.envelope.from, error: e.message }); } }
-        return text(opened.map(({ sender, ...o }) => o));
-      }
-      case 'nyx5_ack': return text({ acked: await agent.ack(args.ids) });
-      case 'nyx5_resolve': { const { _domain, ...card } = await agent.resolver.agentCard(args.address); return text(card); }
-      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': { 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 }); return text({ id: r.id, quote_id: r.quote.id, contract: r.quote.contract, price: r.quote.price }); }
-      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_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(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));
-      default: return { ...text(`herramienta desconocida: ${name}`), isError: true };
-    }
-  }
+  const call = (name, args) => llamar(agent, name, args);
 
   const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
   for await (const line of rl) {
@@ -123,7 +29,7 @@ export async function runMcpServer({ agentFile, hosts = {} }) {
     if (method === 'notifications/initialized' || method?.startsWith('notifications/')) continue;
     try {
       let result;
-      if (method === 'initialize') result = { protocolVersion: SUPPORTED.has(params?.protocolVersion) ? params.protocolVersion : PROTOCOL, capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'nyx5', version: VERSION }, instructions: `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.` };
+      if (method === 'initialize') result = { protocolVersion: SUPPORTED.has(params?.protocolVersion) ? params.protocolVersion : PROTOCOL, capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'nyx5', version: VERSION }, instructions: INSTRUCCIONES };
       else if (method === 'ping') result = {};
       else if (method === 'tools/list') result = { tools: TOOLS };
       else if (method === 'tools/call') { try { result = await call(params?.name, params?.arguments); } catch (e) { result = { ...text(`error: ${e.message}`), isError: true }; } }