@nyx5/nyx5 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Cómo contribuir a Chasqui
+
+Chasqui es la implementación de referencia de un protocolo. La prioridad no es agregar
+funciones: es que el estándar (`docs/SPEC.md`) y el código digan exactamente lo mismo.
+
+## Reglas duras
+
+1. **Cero dependencias.** No se agregan paquetes npm. Todo se resuelve con `node:` builtins.
+   Si algo parece necesitar una dependencia, casi siempre la respuesta es que no se necesita.
+2. **Un cambio de comportamiento sin test es un cambio a medias.** El test se escribe contra el
+   defecto real, no contra un ejemplo inventado. `npm test` corre en verde antes de cualquier PR.
+3. **Los invariantes no se rompen.** Están en `CLAUDE.md` y en `docs/SPEC.md §12`. El primero manda
+   sobre todos: *sin firma verificable no hay entrega*. Si tu cambio los toca, ábrelo como discusión
+   antes de escribir código.
+4. **El SPEC y el código se mueven juntos.** Un cambio en el formato del sobre, en un código de
+   error o en una operación del Libro cambia `docs/SPEC.md` en el mismo PR.
+
+## Antes de abrir un PR
+
+```
+npm test          # todas las pruebas verdes
+npm run demo      # correo: tarea cifrada, respuesta, acuse
+npm run demo:contratos   # libro: escrow, fianza, mandato en cadena
+```
+
+## Cómo se extiende (sin tocar el kernel)
+
+- **Nuevo contrato**: una entrada en `src/libro/contratos.js` (`ops.<nombre>` y, si se cotiza,
+  `CONTRATOS.<kind>`). No se toca `src/libro/libro.js`.
+- **Nueva política de buzón**: `src/correo/politica.js` (`applyInboxPolicy`).
+- **Nueva extensión**: un URI `urn:chasqui:ext:*` declarado en la tarjeta; los datos viajan en
+  `extensions[uri]` del sobre. Los campos desconocidos se conservan y se firman, pero se ignoran.
+
+## Estilo
+
+Sustantivos del dominio en español (sobre, estafeta, tarjeta, libro, asiento, casa, mandato,
+fianza, estampilla); nombres de métodos y campos JSON en inglés cuando ya son convención
+(`send`, `accept`, `release`). Sin abreviaturas crípticas. El código se lee como el que lo rodea.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,133 @@
+# Nyx5/1
+
+**Correo y Libro para agentes de IA, en una sola pieza.** Un agente tiene tres cosas que no
+tiene de otra forma: una **dirección** propia (`agente@dominio`), un **buzón** que guarda aunque
+esté apagado, y un **libro contable** donde un acuerdo pesa —el pago se retiene hasta cumplir, y
+una afirmación falsa cuesta dinero—. Cada mensaje va firmado; cada movimiento de dinero deja un
+recibo que nadie puede negar. Sin dependencias, sobre Node y Cloudflare Workers.
+
+```bash
+node examples/hola-mundo.mjs   # una casa, dos agentes, un sobre firmado y cifrado (~20 líneas)
+```
+
+- **Correo**: direcciones `agente@dominio`, buzón que guarda aunque estés apagado, firma verificable, cifrado extremo a extremo, compatible con MCP y A2A.
+- **Libro**: el ledger de cada casa. Cotizaciones firmadas, contratos (spot, escrow, fianza, medido), mandatos en cadena, estampillas, recibos que nadie puede negar. Sin login: se opera escribiéndole a `libro@<casa>` con la misma identidad del Correo.
+
+**Enlaces**: la casa → [nyx5.com](https://nyx5.com) · la especificación en una página → [nyx5.com/spec](https://nyx5.com/spec) ·
+`docs/SPEC.md` (el estándar) · `docs/ARQUITECTURA.md` (operación y producción) ·
+`CONTRIBUTING.md` · `SECURITY.md` · licencia [Apache-2.0](LICENSE) ·
+implementación de referencia en `src/` (Node 20+, cero dependencias).
+
+## Probar en 1 minuto
+
+```bash
+npm run demo             # correo: dos dominios, tarea cifrada, respuesta, acuse de entrega
+npm run demo:offline     # correo: el destino está apagado: cola, reintento, entrega al volver
+npm run demo:spam        # correo: firma falsa, remitente inexistente, allowlist, proof-of-work, duplicados
+npm run demo:contratos   # libro: spot, escrow, fianza, mandato en cadena, agente delegado, estampilla
+npm run demo:piloto      # libro: una flota con presupuesto, escrow + verificación medida, costo por entrega
+npm test                 # 70 pruebas automatizadas
+```
+
+## Probar por partes (dos terminales)
+
+`hosts.local.json` ya mapea `alfa.local` y `beta.local` a los puertos 4001 y 4002 (en producción esto lo hace el DNS).
+
+Terminal 1 y 2, una estafeta por dominio:
+```bash
+node bin/nyx5.js estafeta --domain alfa.local --port 4001 --data ./data/alfa --admin-token secreto-alfa
+node bin/nyx5.js estafeta --domain beta.local --port 4002 --data ./data/beta --admin-token secreto-beta
+```
+
+Terminal 3, los agentes:
+```bash
+node bin/nyx5.js keygen --address nicolas@alfa.local   --estafeta http://127.0.0.1:4001
+node bin/nyx5.js keygen --address asistente@beta.local --estafeta http://127.0.0.1:4002
+node bin/nyx5.js register --agent keys/nicolas.json   --admin-token secreto-alfa
+node bin/nyx5.js register --agent keys/asistente.json --admin-token secreto-beta --mcp http://127.0.0.1:4010/mcp
+
+node bin/nyx5.js card --address asistente@beta.local
+node bin/nyx5.js send --agent keys/nicolas.json --to asistente@beta.local --type task --json --body '{"skill":"resumir","input":"hola"}'
+node bin/nyx5.js inbox --agent keys/asistente.json --ack
+node bin/nyx5.js outbox --agent keys/nicolas.json
+```
+
+Apaga la terminal 2, envía otro sobre, mira `outbox` (queda en `retrying`), vuelve a levantar beta y mira cómo llega.
+
+Registro como servicio: levanta la estafeta con `--registration invite` (o `open`), emite códigos con `node bin/nyx5.js invite --estafeta http://127.0.0.1:4001 --admin-token secreto-alfa --uses 5 --welcome 100`, y cada agente entra con `register --agent keys/x.json --invite CODIGO` sin tocar el token de la casa. `node bin/nyx5.js directory --house alfa.local --capability mcp` lista quién ofrece qué.
+
+Políticas de buzón al registrar: `--policy allowlist --allow socio@gamma.local`, `--policy pow --pow-bits 16`, o `--policy stamp` (cobra por recibir; el precio se fija en la tarjeta).
+
+## El Libro por terminal
+
+```bash
+node bin/nyx5.js topup   --estafeta http://127.0.0.1:4001 --admin-token secreto-alfa --account nicolas@alfa.local --amount 1000
+node bin/nyx5.js keygen  --address verifica@alfa.local --estafeta http://127.0.0.1:4001
+node bin/nyx5.js register --agent keys/verifica.json --admin-token secreto-alfa
+node bin/nyx5.js quote   --agent keys/verifica.json --to nicolas@alfa.local --price 40 --concept "verificación" --contract escrow
+node bin/nyx5.js inbox   --agent keys/nicolas.json          # copia el content.body de la cotización a un archivo
+node bin/nyx5.js accept  --agent keys/nicolas.json --quote cotizacion.json
+node bin/nyx5.js inbox   --agent keys/nicolas.json          # llega el recibo de libro@ con el contrato y el asiento
+node bin/nyx5.js libro   --agent keys/verifica.json --op deliver --json --body '{"contract":"<id>","evidence_sha256":"..."}'
+node bin/nyx5.js libro   --agent keys/nicolas.json  --op release --json --body '{"contract":"<id>"}'
+node bin/nyx5.js balance --agent keys/nicolas.json
+node bin/nyx5.js delegate --agent keys/nicolas.json --name bot --scope '{"types":["message","result"],"cap":100}'
+```
+
+Fianza: `--op bond --body '{"amount":50,"claim":"desplegado y verificado","verifier":"verifica@alfa.local"}'`. Mandato: `--op mandate --body '{"grantee":"bot.nicolas@alfa.local","cap":200}'`; luego el mandatario cobra con `--op charge --body '{"mandate":"<id>","amount":30,"concept":"tokens de modelo"}'`.
+
+## Usarlo desde Claude Desktop / Claude Code (puente MCP)
+
+Cualquier cliente MCP puede leer y escribir sobres como herramientas. En `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chasqui": {
+      "command": "node",
+      "args": ["/ruta/a/chasqui/bin/nyx5.js", "mcp", "--agent", "/ruta/a/chasqui/keys/nicolas.json"],
+      "env": { "CHASQUI_HOSTS": "/ruta/a/chasqui/hosts.local.json" }
+    }
+  }
+}
+```
+
+Herramientas expuestas: correo `nyx5_send`, `nyx5_inbox`, `nyx5_ack`, `nyx5_resolve`, `nyx5_outbox`, `nyx5_directory`; libro `nyx5_quote`, `nyx5_accept`, `nyx5_libro`, `nyx5_balance`, `nyx5_contract`. Con eso, Claude puede decir "revisa mi buzón, acepta la cotización de verifica si es menor a 50 y libera el escrow del constructor".
+
+## Pasar a un dominio real (ej. sigo.uk)
+
+1. Levanta la estafeta en un servidor con TLS: `--domain sigo.uk --public-url https://mail.sigo.uk`.
+2. Copia `keys[0].sig` de `data/sigo.uk/domain.json` y publica en DNS: `_nyx5.sigo.uk TXT "v=nyx51; url=https://mail.sigo.uk; sig=<esa clave>"`.
+3. Registra tus agentes (`nicolas@sigo.uk`, `asistente@sigo.uk`).
+4. Cualquier estafeta del mundo ya puede resolverte y escribirte, sin `hosts.json`.
+
+Detalles, esquema de base de datos, seguridad operativa y hoja de ruta en `docs/ARQUITECTURA.md`.
+
+## Estructura
+
+```
+CLAUDE.md                guía para Claude Code
+bin/nyx5.js           CLI (correo: estafeta, keygen, register, invite, directory, card, send, inbox, ack, outbox, mcp · libro: topup, balance, quote, accept, libro, contract, delegate)
+src/nucleo/crypto.js     Ed25519, X25519+AES-GCM, JSON canónico, sha256, proof-of-work
+src/nucleo/almacen.js    persistencia en archivos de ambos componentes (interfaz para Postgres/D1)
+src/correo/resolver.js   DNS / well-known / override, cadena de confianza y de delegación, caché, rotación
+src/correo/politica.js   validación de sobres, allowlist / pow / stamp / rate limit
+src/correo/estafeta.js   servidor de dominio: registro (admin/invite/open), directorio, cola, reintentos, verificación, buzones, webhooks, libro@
+src/correo/agente.js     cliente: correo (send, inbox, open, reply, receipt, delegate) + libro (quote, accept, deliver, release, refund, bond, forfeit, mandate, charge, revoke, balance)
+src/libro/libro.js       kernel del ledger: asientos firmados, primitivas, verificación de cotizaciones, estampillas
+src/libro/contratos.js   contratos: spot, escrow, fianza, medido, mandatos en cadena
+src/puentes/mcp.js       puente MCP por stdio
+demo/                    e2e, offline, spam, contratos, piloto-d4 (economía de una flota)
+examples/                hola-mundo.mjs (el ejemplo mínimo, ~20 líneas)
+test/                    correo, libro, registro, invariantes+D1, índice, concurrencia, altos, diferidos (70)
+```
+
+## Para seguir construyendo con Claude Code
+
+Abre el repo en Claude Code; `CLAUDE.md` le da el mapa y los invariantes. Prompts útiles, en orden:
+
+1. "Piloto en casa: crea un script `demo/piloto.js` que registre mis sesiones como agentes, cargue el presupuesto mensual por frente como topup, y modele una cajita como escrow con prueba de aceptación." (Fase 1 de la hoja de ruta.)
+2. "Implementa `D1Store` (Cloudflare D1) con la misma interfaz que `FileStore`, incluidos los métodos `libro*`, usando el esquema de `docs/ARQUITECTURA.md` sección 4.2, y haz que `Estafeta` acepte `store` como opción."
+3. "Agrega un `Dockerfile` y un `fly.toml` para correr la estafeta de sigo.uk con volumen persistente."
+4. "Implementa la extensión `urn:nyx5:ext:email`: un receptor SMTP mínimo que deposite correos en el buzón con `from_verified: false`."
+5. "Agrega el contrato `bounty` en `contratos.js` (fondos retenidos; cobra el primero que pase el criterio) con su test."

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Política de seguridad
+
+Chasqui mueve identidad, mensajes cifrados y un ledger. Una vulnerabilidad aquí no es un bug
+cualquiera. Agradecemos el reporte responsable.
+
+## Cómo reportar
+
+Reporta en privado a **security@chsq.uk**. No abras un issue público para una vulnerabilidad.
+Incluye: qué invariante se rompe, cómo reproducirlo, y el impacto. Respondemos el recibo del
+reporte lo antes posible y coordinamos una divulgación una vez que haya un arreglo.
+
+## Qué es una vulnerabilidad aquí
+
+El modelo de amenazas está en `docs/SPEC.md §12`. En corto, es un reporte de seguridad si permite:
+
+- **Entregar un sobre sin firma verificable** (rompe el invariante 1) o hacer pasar por verificado
+  algo que no lo es.
+- **Leer contenido cifrado** desde la estafeta o un relay (el invariante 8: la estafeta no lo lee).
+- **Mover tokens sin un sobre firmado** a `libro@`, dejar un asiento que no cuadra, o hacer que
+  alguien salvo `casa@` quede en negativo (invariante 3).
+- **Registrar una clave que no se controla**, pisar un nombre ajeno, o exceder el ámbito de un
+  mandato o de una tarjeta delegada (invariantes 6 y 9).
+- **Filtrar una clave privada** (de dominio o de agente) por cualquier endpoint.
+
+## Alcance
+
+Esta es una implementación de referencia. Un despliegue en producción (Cloudflare Workers + D1)
+suma su propia superficie: la configuración del despliegue es responsabilidad de quien lo opera.

package/bin/nyx5.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Nyx5/1 — CLI
+//
+//   nyx5 estafeta --domain alfa.local --port 4001 --data ./data/alfa --admin-token secreto [--registration admin|invite|open] [--welcome 100] [--fee 0.10]
+//   nyx5 keygen   --address nicolas@alfa.local --estafeta http://127.0.0.1:4001 --out ./keys/nicolas.json
+//   nyx5 register --agent ./keys/nicolas.json --admin-token secreto [--policy open|allowlist|pow|stamp] [--allow a@b,c@d] [--pow-bits 16] [--webhook URL] [--mcp URL] [--a2a URL]
+//   nyx5 register --agent ./keys/nicolas.json --invite CODIGO        (o sin nada, si la casa tiene registration=open)
+//   nyx5 invite   --estafeta http://127.0.0.1:4001 --admin-token secreto [--uses 1] [--expires ISO] [--note "para Marta"]
+//   nyx5 directory [--house alfa.local | --estafeta URL] [--capability mcp] [--accepts media] [--q texto]
+//   nyx5 search   --index indice.local [--q texto] [--capability mcp] [--accepts media] [--house uno.local]
+//   nyx5 card     --address asistente@beta.local
+//   nyx5 send     --agent ./keys/nicolas.json --to asistente@beta.local --body "hola" [--json] [--type task] [--plain]
+//   nyx5 inbox    --agent ./keys/nicolas.json [--ack]
+//   nyx5 ack      --agent ./keys/nicolas.json --id <id>[,<id>]
+//   nyx5 outbox   --agent ./keys/nicolas.json
+//   nyx5 mcp      --agent ./keys/nicolas.json          (servidor MCP por stdio)
+//   --- Libro ---
+//   nyx5 topup    --estafeta http://127.0.0.1:4001 --admin-token secreto --account nicolas@alfa.local --amount 1000
+//   nyx5 balance  --agent ./keys/nicolas.json [--house alfa.local]
+//   nyx5 quote    --agent ./keys/verifica.json --to nicolas@alfa.local --price 40 --concept "verificación" [--contract spot|escrow|metered] [--terms '{...}'] [--arbiter a@casa] [--expires ISO]
+//   nyx5 accept   --agent ./keys/nicolas.json --quote <archivo.json o JSON>     (o `inbox` te muestra la cotización; cópiala)
+//   nyx5 libro    --agent ./keys/nicolas.json --op release --args '{"contract":"..."}' [--house alfa.local]
+//   nyx5 contract --agent ./keys/nicolas.json --id <contrato>
+//   nyx5 delegate --agent ./keys/constructor.json --name tester --scope '{"types":["message","result"],"cap":100}' --out ./keys/tester.json
+//
+// Resolución local: --hosts hosts.json, o CHASQUI_HOSTS, o ./hosts.local.json si existe.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { Estafeta } from '../src/correo/estafeta.js';
+import { Agent } from '../src/correo/agente.js';
+import { Resolver } from '../src/correo/resolver.js';
+import { runMcpServer } from '../src/puentes/mcp.js';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const { values: o } = parseArgs({ args: rest, allowPositionals: true, options: {
+  domain: { type: 'string' }, port: { type: 'string' }, data: { type: 'string' }, 'admin-token': { type: 'string' }, 'public-url': { type: 'string' },
+  'require-relay': { type: 'boolean' }, hosts: { type: 'string' }, registration: { type: 'string' }, welcome: { type: 'string' }, fee: { type: 'string' },
+  invite: { type: 'string' }, uses: { type: 'string' }, expires: { type: 'string' }, note: { type: 'string' }, capability: { type: 'string' }, accepts: { type: 'string' }, q: { type: 'string' },
+  address: { type: 'string' }, estafeta: { type: 'string' }, out: { type: 'string' }, agent: { type: 'string' },
+  policy: { type: 'string' }, allow: { type: 'string' }, 'pow-bits': { type: 'string' }, webhook: { type: 'string' }, mcp: { type: 'string' }, a2a: { type: 'string' },
+  to: { type: 'string' }, body: { type: 'string' }, type: { type: 'string' }, json: { type: 'boolean' }, plain: { type: 'boolean' }, thread: { type: 'string' }, 'reply-to': { type: 'string' },
+  ack: { type: 'boolean' }, id: { type: 'string' },
+  account: { type: 'string' }, amount: { type: 'string' }, house: { type: 'string' }, price: { type: 'string' }, concept: { type: 'string' }, contract: { type: 'string' }, terms: { type: 'string' },
+  quote: { type: 'string' }, op: { type: 'string' }, name: { type: 'string' }, scope: { type: 'string' },
+  args: { type: 'string' }, index: { type: 'string' }, arbiter: { type: 'string' }, receipt: { type: 'string' }, limit: { type: 'string' },
+} });
+
+const need = (k) => { if (!o[k]) { console.error(`falta --${k}`); process.exit(2); } return o[k]; };
+const loadHosts = () => {
+  const file = o.hosts || process.env.CHASQUI_HOSTS || (fs.existsSync('hosts.local.json') ? 'hosts.local.json' : null);
+  if (!file && ['send', 'inbox', 'card', 'directory'].includes(cmd)) console.error('aviso: sin hosts.local.json en este cwd; la resolución irá por DNS/well-known');
+  return file ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+};
+const loadAgent = () => Agent.load(need('agent'), { hosts: loadHosts() });
+const warnHosts = (h) => { if (!Object.keys(h).length && !process.env.CHASQUI_HOSTS) console.error('aviso: sin hosts.local.json en este directorio; la resolución irá por DNS/well-known'); return h; };
+const print = (v) => console.log(JSON.stringify(v, null, 2));
+
+try {
+  switch (cmd) {
+    case 'estafeta': {
+      const e = new Estafeta({
+        domain: need('domain'), port: Number(o.port || 4000), dataDir: need('data'),
+        adminToken: o['admin-token'] || process.env.CHASQUI_ADMIN_TOKEN || need('admin-token'),
+        publicUrl: o['public-url'], hosts: loadHosts(),
+        policy: { require_relay: !!o['require-relay'], registration: o.registration || 'admin' },
+        libro: { welcome: Number(o.welcome || 0), feePct: o.fee != null ? Number(o.fee) : null },
+      });
+      await e.start();
+      process.on('SIGINT', async () => { await e.stop(); process.exit(0); });
+      break;
+    }
+    case 'keygen': {
+      const a = Agent.create(need('address'), need('estafeta'));
+      const out = o.out || `./keys/${a.local}.json`;
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, JSON.stringify({ address: a.address, estafeta: a.estafeta, keys: a.keys }, null, 2), { mode: 0o600 });
+      console.log(`claves de ${a.address} guardadas en ${out} (guárdalo como una contraseña)`);
+      console.log(`clave pública de firma: ${a.keys.sig}`);
+      break;
+    }
+    case 'register': {
+      const a = await loadAgent();
+      const inbox = { policy: o.policy || 'open' };
+      if (o.allow) inbox.allowlist = o.allow.split(',').map((s) => s.trim());
+      if (o['pow-bits']) inbox.pow_bits = Number(o['pow-bits']);
+      const capabilities = {};
+      if (o.mcp) capabilities.mcp = o.mcp;
+      if (o.a2a) capabilities.a2a = o.a2a;
+      print(await a.register({ adminToken: o['admin-token'] || process.env.CHASQUI_ADMIN_TOKEN, invite: o.invite, inbox, capabilities, webhook: o.webhook }));
+      break;
+    }
+    case 'invite': {
+      const res = await fetch(`${need('estafeta')}/invitations`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${o['admin-token'] || process.env.CHASQUI_ADMIN_TOKEN}` }, body: JSON.stringify({ uses: Number(o.uses || 1), expires: o.expires || null, note: o.note || null, welcome: o.welcome != null ? Number(o.welcome) : null }) });
+      print(await res.json()); break;
+    }
+    case 'directory': {
+      const params = new URLSearchParams(Object.entries({ capability: o.capability, accepts: o.accepts, q: o.q }).filter(([, v]) => v));
+      let base = o.estafeta;
+      if (!base) { const r = new Resolver({ hosts: loadHosts() }); base = (await r.domainCard(need('house')))._estafeta; }
+      const d = await (await fetch(`${base}/agents?${params}`)).json();
+      console.log(`${d.total} agente(s)`);
+      for (const a of d.agents) console.log(`  ${a.address.padEnd(36)} ${Object.keys(a.capabilities || {}).filter((k) => k !== 'accepts').join(',') || '-'}  buzón=${a.inbox?.policy}${a.delegated_by ? '  delegado por ' + a.delegated_by : ''}`);
+      break;
+    }
+    case 'search': {
+      const r = new Resolver({ hosts: loadHosts() });
+      const idx = need('index');
+      const base = idx.startsWith('http') ? idx.replace(/\/$/, '') : (await r.domainCard(idx))._estafeta;
+      const params = new URLSearchParams(Object.entries({ q: o.q, capability: o.capability, accepts: o.accepts, house: o.house, limit: o.limit }).filter(([, v]) => v));
+      const d = await (await fetch(`${base}/index/agents?${params}`)).json();
+      console.log(`${d.total} agente(s) en el índice ${d.index || idx}`);
+      for (const a of d.agents || []) console.log(`  ${a.address.padEnd(40)} casa=${a._house || '-'}  ${Object.keys(a.capabilities || {}).filter((k) => k !== 'accepts').join(',') || '-'}`);
+      break;
+    }
+    case 'card': {
+      const r = new Resolver({ hosts: loadHosts() });
+      const { _domain, ...card } = await r.agentCard(need('address'));
+      print(card);
+      break;
+    }
+    case 'send': {
+      const a = await loadAgent();
+      const body = o.json ? JSON.parse(need('body')) : need('body');
+      const r = await a.send({ to: need('to').split(',').map((s) => s.trim()), body, type: o.type || 'message', encrypt: !o.plain, thread: o.thread, inReplyTo: o['reply-to'], receipt: o.receipt });
+      print({ id: r.id, jobs: r.jobs, encrypted: !!r.envelope.encrypted });
+      break;
+    }
+    case 'inbox': {
+      const a = await loadAgent();
+      const msgs = await a.inbox({ limit: Number(o.limit || 50) });
+      if (!msgs.length) { console.log('buzón vacío'); break; }
+      const abiertos = [];
+      for (const m of msgs) {
+        try { const op = await a.open(m.envelope); const { sender, ...rest } = op; abiertos.push(m.envelope.id); print({ ...rest, received: m.received, relay_verified: m.relay_verified }); }
+        catch (e) { print({ id: m.envelope.id, from: m.envelope.from, error: e.message }); }
+      }
+      // --ack confirma SOLO lo abierto con éxito: un sobre que no descifra se queda en el buzón.
+      if (o.ack && abiertos.length) console.log('ack:', await a.ack(abiertos));
+      break;
+    }
+    case 'ack': print({ acked: await (await loadAgent()).ack(need('id').split(',')) }); break;
+    case 'outbox': print(await (await loadAgent()).outbox()); break;
+    case 'mcp': await runMcpServer({ agentFile: need('agent'), hosts: loadHosts() }); break;
+
+    // ----- Libro -----
+    case 'topup': {
+      const res = await fetch(`${need('estafeta')}/libro/topup`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${o['admin-token'] || process.env.CHASQUI_ADMIN_TOKEN}` }, body: JSON.stringify({ account: need('account'), amount: Number(need('amount')), concept: o.concept }) });
+      print(await res.json()); break;
+    }
+    case 'balance': print(await (await loadAgent()).balance(o.house)); break;
+    case 'quote': {
+      const a = await loadAgent();
+      const r = await a.quote({ to: need('to'), contract: o.contract || 'spot', price: Number(need('price')), concept: need('concept'), terms: o.terms ? JSON.parse(o.terms) : undefined, arbiter: o.arbiter, expires: o.expires, house: o.house });
+      print({ sent: r.id, quote: r.quote }); break;
+    }
+    case 'accept': {
+      const raw = need('quote');
+      const q = fs.existsSync(raw) ? JSON.parse(fs.readFileSync(raw, 'utf8')) : JSON.parse(raw);
+      print(await (await loadAgent()).accept(q.content?.body || q)); break;
+    }
+    case 'libro': {
+      const a = await loadAgent();
+      const extra = o.args ? JSON.parse(o.args) : (o.json ? JSON.parse(o.body || '{}') : {});
+      print(await a.libroOp(o.house || a.domain, { op: need('op'), ...extra })); break;
+    }
+    case 'contract': { const a = await loadAgent(); print(await a.contract(o.house || a.domain, need('id'))); break; }
+    case 'delegate': {
+      const a = await loadAgent();
+      const sub = await a.delegate(need('name'), { scope: o.scope ? JSON.parse(o.scope) : {} });
+      const out = o.out || `./keys/${sub.local}.json`;
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, JSON.stringify({ address: sub.address, estafeta: sub.estafeta, keys: sub.keys }, null, 2), { mode: 0o600 });
+      console.log(`agente delegado ${sub.address} creado; claves en ${out}`); break;
+    }
+    default:
+      console.log(fs.readFileSync(new URL(import.meta.url)).toString().split('\n').slice(1, 27).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'));
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (e) {
+  console.error('error:', e.message);
+  process.exit(1);
+}