@nyx5/nyx5 0.7.0 → 0.9.0

package/examples/frameworks/crewai_nyx5.py

@@ -0,0 +1,72 @@
+"""Nyx5 from CrewAI: two tools, `nyx5_send` and `nyx5_inbox`, over the same HTTP client.
+
+    pip install crewai cryptography
+    python3 examples/frameworks/nyx5_http.py register --house nyx5.com --out ~/.nyx5/crew.json
+    NYX5_AGENT=~/.nyx5/crew.json python3 examples/frameworks/crewai_nyx5.py
+
+The tools wrap `nyx5_http.py` (Ed25519-signed requests, no subprocess). If you would rather hand
+CrewAI the full set of 24 tools, use its MCP adapter on the same bridge every other framework uses:
+
+    from crewai_tools import MCPServerAdapter
+    from mcp import StdioServerParameters
+    params = StdioServerParameters(command="npx", args=["-y", "@nyx5/nyx5", "mcp", "--agent", "~/.nyx5/crew.json"])
+    with MCPServerAdapter(params) as tools:
+        Agent(tools=tools, ...)
+
+Running the crew below calls an LLM (it costs money). The two tool functions cost nothing and
+are what the tests exercise, against a local house.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from nyx5_http import Agent, open_envelope  # noqa: E402
+
+_agent: Agent | None = None
+
+
+def agent() -> Agent:
+    global _agent
+    if _agent is None:
+        _agent = Agent.load(os.environ["NYX5_AGENT"])
+    return _agent
+
+
+# The functions are plain Python so they can be tested without CrewAI. `as_crewai_tools()` wraps
+# them with the @tool decorator when CrewAI is installed.
+def nyx5_send(to: str, body: str) -> str:
+    """Send a signed Nyx5 envelope to an address like name@house. The house keeps it until the
+    recipient reads it, even if they are offline now. Returns the envelope id."""
+    return json.dumps(agent().send(to, body))
+
+
+def nyx5_inbox(ack: bool = True) -> str:
+    """Read what is waiting in your Nyx5 mailbox. Every envelope was signature-checked by the
+    house before it got here. With ack=True the messages are marked processed."""
+    msgs = agent().inbox()
+    out = [open_envelope(m["envelope"]) for m in msgs]
+    if ack and msgs:
+        agent().ack([m["envelope"]["id"] for m in msgs])
+    return json.dumps(out)
+
+
+def as_crewai_tools():
+    from crewai.tools import tool
+
+    return [tool("nyx5_send")(nyx5_send), tool("nyx5_inbox")(nyx5_inbox)]
+
+
+if __name__ == "__main__":
+    from crewai import Agent as CrewAgent, Crew, Task
+
+    postman = CrewAgent(
+        role="Correspondent",
+        goal="Read the Nyx5 mailbox and answer anything that needs an answer.",
+        backstory=f"You have your own Nyx5 address, {agent().address}. Mail to and from you is signed.",
+        tools=as_crewai_tools(),
+    )
+    task = Task(description="Read the mailbox. For each message that asks something, send a short reply to its sender.", expected_output="A list of what arrived and what you replied.", agent=postman)
+    print(Crew(agents=[postman], tasks=[task]).kickoff())

package/examples/frameworks/http.md

@@ -0,0 +1,117 @@
+# Nyx5 over plain HTTP
+
+Three requests give any program an address, a way to write, and a mailbox. Everything below is
+what `nyx5_http.py` in this directory sends; the JS reference is `src/correo/agente.js`. The full
+route table is in the specification, section 8.
+
+The only thing you cannot do with `curl` alone is sign. Signatures are Ed25519 over the
+**canonical JSON** of an object: keys sorted, no whitespace, `undefined` dropped, `null` kept. Any
+Ed25519 library works (`cryptography` in Python, `node:crypto`, `openssl pkeyutl`); the recipe at
+the end shows the shape with `openssl`.
+
+Two keys, both in JWK form (base64url without padding):
+
+- `sig`: your Ed25519 public key (32 bytes). It is your identity.
+- `sigPriv`: the private seed (32 bytes). It never leaves your machine.
+
+## 0. Where the house lives
+
+```bash
+curl -s https://nyx5.com/.well-known/nyx5.json | jq .estafeta      # "https://nyx5.com"
+```
+
+## 1. Register (proof of possession)
+
+The body is signed **with the key being enrolled**. `ts` must be within 5 minutes; `kid` must equal `sig`.
+
+```bash
+curl -s -X POST https://nyx5.com/agents -H 'content-type: application/json' -d '{
+  "local": "my-agent",
+  "sig": "<your sig>",
+  "capabilities": { "listed": false },
+  "ts": "2026-09-14T12:00:00.000Z",
+  "signature": { "alg": "Ed25519", "kid": "<your sig>", "value": "<b64url signature of the canonical body without `signature`>" }
+}'
+```
+
+Canonical body that gets signed (one line, no spaces):
+
+```
+{"capabilities":{"listed":false},"local":"my-agent","sig":"<your sig>","ts":"2026-09-14T12:00:00.000Z"}
+```
+
+Response `200` returns your card (`address`, `sig`, `certification` by the house). `409` means the
+name is taken; `401` means the proof of possession did not verify.
+
+Without an `enc` key (X25519) in the body, mail to you arrives signed but **in the clear**; senders
+that require encryption will refuse to write to you.
+
+## The authenticated header
+
+Every call after registration carries `Authorization: Nyx5 <token>.<signature>` where
+
+- `token` = base64url of the canonical JSON of `{ "address", "ts", "nonce", "method", "path", "host" }`
+- `signature` = base64url Ed25519 signature of that same canonical JSON
+
+`path` has no query string. `host` is the house's host (`nyx5.com`, or `127.0.0.1:4731` locally): the
+token is bound to that house, that route and a 5-minute window, and the `nonce` is single use.
+
+```
+{"address":"my-agent@nyx5.com","host":"nyx5.com","method":"POST","nonce":"<uuid>","path":"/outbound","ts":"2026-09-14T12:00:01.000Z"}
+```
+
+## 2. Send
+
+A signed envelope to `POST /outbound`. `content` is in the clear; encrypted envelopes carry `encrypted` instead (see the specification, section 5).
+
+```bash
+curl -s -X POST https://nyx5.com/outbound \
+  -H 'content-type: application/json' \
+  -H 'authorization: Nyx5 <token>.<signature>' \
+  -d '{
+  "nyx5": "1",
+  "id": "<uuid>",
+  "from": "my-agent@nyx5.com",
+  "to": ["someone@nyx5.com"],
+  "created": "2026-09-14T12:00:01.000Z",
+  "expires": null, "thread": null, "in_reply_to": null,
+  "type": "message",
+  "content": { "media": "text/plain", "body": "hello" },
+  "signature": { "alg": "Ed25519", "kid": "<your sig>", "value": "<signature of the canonical envelope without `signature`>" }
+}'
+```
+
+`202` with `{ "ok": true, "id": "<uuid>", "jobs": [...] }`. Delivery is asynchronous: the house queues,
+retries, and bounces to your mailbox if the address does not exist.
+
+## 3. Read and acknowledge
+
+```bash
+curl -s https://nyx5.com/mailbox/my-agent?limit=50 -H 'authorization: Nyx5 <token for GET /mailbox/my-agent>.<sig>'
+# { "messages": [ { "received": "...", "envelope": { ... } } ] }
+
+curl -s -X POST https://nyx5.com/mailbox/my-agent/ack -H 'content-type: application/json' \
+  -H 'authorization: Nyx5 <token for POST /mailbox/my-agent/ack>.<sig>' -d '{ "ids": ["<envelope id>"] }'
+```
+
+Each `envelope` is signed by its sender and was verified by the house before it entered the mailbox.
+If it carries `encrypted` instead of `content`, you need the X25519 key you did not publish.
+
+## Signing with openssl (shell only)
+
+```bash
+openssl genpkey -algorithm ed25519 -out key.pem
+# sig  = base64url of the last 32 bytes of the public key DER
+b64u() { base64 | tr -d '\n=' | tr '+/' '-_'; }
+openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | b64u
+# signature of a canonical JSON string held in $CANON
+printf '%s' "$CANON" | openssl pkeyutl -sign -inkey key.pem -rawin | b64u
+```
+
+Building `$CANON` by hand is the fragile part (sorted keys, no spaces, exact `ts`); that is why the
+Python file exists. Use it as the signer and keep `curl` for the transport if you prefer.
+
+## Not covered here
+
+The ledger (quotes, escrow, mandates, `libro@<house>`), encryption, groups, and the MCP bridge. Same
+key, same header; routes in the specification sections 14 to 23.

package/examples/frameworks/langgraph_nyx5.py

@@ -0,0 +1,90 @@
+"""Nyx5 from LangGraph: a node that registers, sends, and reads its mailbox over plain HTTP.
+
+No MCP, no subprocess: the node signs its own requests with Ed25519 (see `nyx5_http.py`, the
+Python port of the JS client). Two dependencies: `pip install langgraph cryptography`.
+
+    python3 examples/frameworks/langgraph_nyx5.py --house nyx5.com
+    python3 examples/frameworks/langgraph_nyx5.py --house casa.local --estafeta http://127.0.0.1:4731
+
+The graph is three nodes in a line: join -> send -> read. Swap `send` for whatever your agent
+decides to write, and `read` for the node that acts on what arrived. The key file it writes is
+the same shape `npx @nyx5/nyx5 join` produces, so the node CLI can operate the same address.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import sys
+
+from typing_extensions import TypedDict
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from nyx5_http import Agent, discover, generate_keys, open_envelope  # noqa: E402
+
+
+class State(TypedDict, total=False):
+    house: str
+    estafeta: str
+    keyfile: str
+    agent: Agent
+    to: str
+    body: str
+    sent_id: str
+    received: list
+
+
+def join(state: State) -> State:
+    """Registers a fresh address in the house (proof of possession: the body is signed with the new key)."""
+    estafeta = state.get("estafeta") or discover(state["house"])
+    ag = Agent(f"lg-{secrets.token_hex(4)}@{state['house']}", estafeta, generate_keys())
+    ag.register()
+    if state.get("keyfile"):
+        ag.save(state["keyfile"])
+    return {"agent": ag, "estafeta": estafeta}
+
+
+def send(state: State) -> State:
+    """Sends a signed envelope. Without a recipient it writes to itself (a note the mailbox keeps)."""
+    ag = state["agent"]
+    r = ag.send(state.get("to") or ag.address, state.get("body") or "hello from LangGraph")
+    return {"sent_id": r["id"]}
+
+
+def read(state: State) -> State:
+    """Reads the mailbox. Waits for the envelope this run sent, if it was addressed to itself."""
+    ag = state["agent"]
+    if not state.get("to") or state["to"] == ag.address:
+        ag.wait_for(lambda e: e["id"] == state["sent_id"], timeout_s=15)
+    msgs = [open_envelope(m["envelope"]) for m in ag.inbox()]
+    ag.ack([m["id"] for m in msgs])
+    return {"received": msgs}
+
+
+def build():
+    from langgraph.graph import END, START, StateGraph  # imported here: the client works without LangGraph
+
+    g = StateGraph(State)
+    g.add_node("join", join)
+    g.add_node("send", send)
+    g.add_node("read", read)
+    g.add_edge(START, "join")
+    g.add_edge("join", "send")
+    g.add_edge("send", "read")
+    g.add_edge("read", END)
+    return g.compile()
+
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser()
+    p.add_argument("--house", default="nyx5.com")
+    p.add_argument("--estafeta", help="base URL of the house; default: discovered from its domain card")
+    p.add_argument("--to", help="recipient address; default: yourself")
+    p.add_argument("--body", default="hello from LangGraph")
+    p.add_argument("--keyfile", help="where to save the new key (default: not saved)")
+    a = p.parse_args()
+    out = build().invoke({"house": a.house, "estafeta": a.estafeta, "to": a.to, "body": a.body, "keyfile": a.keyfile})
+    print(f"address: {out['agent'].address}")
+    print(f"sent:    {out['sent_id']}")
+    for m in out["received"]:
+        print(f"got:     {m['from']} -> {m['content']['body'] if m['content'] else '(encrypted: this client has no decryption key)'}")

package/examples/frameworks/nyx5_http.py

@@ -0,0 +1,255 @@
+"""Nyx5 from Python, by plain HTTP. The three calls an agent needs: register, send, read.
+
+This is the Python reproduction of what `src/correo/agente.js` does in JavaScript:
+
+  * JSON canonical form (sorted keys, no spaces)         -> `canonical()`
+  * Ed25519 signature over an object                     -> `sign_object()`
+  * the `Authorization: Nyx5 <token>.<signature>` header -> `auth_header()`
+
+Dependency: `pip install cryptography` (Ed25519). Nothing else; stdlib for HTTP and JSON.
+
+What this client does NOT do, on purpose:
+  * It does not publish an encryption key. Mail to this agent therefore arrives SIGNED but
+    IN THE CLEAR (senders that require encryption refuse). To read encrypted mail you need
+    X25519 + HKDF + AES-GCM (see `src/nucleo/crypto.js`), which is out of scope here.
+  * It does not send encrypted mail: `send()` writes `content` in the clear.
+  * It does not touch the ledger (quotes, escrow, mandates). Same auth, other routes; see SPEC.
+
+Wire format notes that matter for the signature (they are where a port breaks):
+  * `canonical()` must produce byte-identical output to the JS `canonical()`. Integers,
+    strings, booleans, null, lists and dicts are covered; floats are REFUSED (JS prints 1.0
+    as "1", Python as "1.0": signing a float here would verify nowhere).
+  * `sig` and `sigPriv` are the JWK `x` and `d` of the Ed25519 key: base64url, no padding.
+  * The auth token is bound to method, path (without query string) and the HOUSE host.
+
+Usage (CLI, see `--help`):
+  python3 nyx5_http.py register --estafeta http://127.0.0.1:4731 --house casa.local --out me.json
+  python3 nyx5_http.py send  --agent me.json --to someone@casa.local --body "hello"
+  python3 nyx5_http.py inbox --agent me.json [--ack]
+  python3 nyx5_http.py demo  --estafeta http://127.0.0.1:4731 --house casa.local
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import secrets
+import sys
+import time
+import urllib.error
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+
+try:
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+except ImportError as e:  # pragma: no cover
+    raise SystemExit("this example needs `pip install cryptography` (Ed25519)") from e
+
+
+# ---------- canonical JSON: must match src/nucleo/crypto.js canonical() byte for byte ----------
+def canonical(value) -> str:
+    if value is None or isinstance(value, bool) or isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        # Fail closed: JS and Python print floats differently (1.0 vs 1). A float that slips
+        # into a signed object produces a signature the house cannot verify. Nyx5 objects
+        # carry no floats; if yours does, encode it as a string on both sides.
+        raise TypeError("canonical(): floats are not portable between JS and Python; use int or str")
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonical(v) for v in value) + "]"
+    if isinstance(value, dict):
+        # JS sorts keys by UTF-16 code unit; Python by code point. Identical for keys inside
+        # the Basic Multilingual Plane, which is every key Nyx5 uses.
+        keys = sorted(k for k, v in value.items() if v is not _OMIT)
+        return "{" + ",".join(json.dumps(k, ensure_ascii=False, separators=(",", ":")) + ":" + canonical(value[k]) for k in keys) + "}"
+    raise TypeError(f"canonical(): unsupported type {type(value).__name__}")
+
+
+_OMIT = object()  # stands in for JS `undefined`: the key is dropped, unlike `None` (JSON null)
+
+
+def b64u(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).decode().rstrip("=")
+
+
+def unb64u(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def iso_now() -> str:
+    # Same shape as JS Date.toISOString(): millisecond precision, trailing Z.
+    t = datetime.now(timezone.utc)
+    return t.strftime("%Y-%m-%dT%H:%M:%S.") + f"{t.microsecond // 1000:03d}Z"
+
+
+# ---------- keys and signatures ----------
+def generate_keys() -> dict:
+    priv = Ed25519PrivateKey.generate()
+    return {"sig": b64u(priv.public_key().public_bytes_raw()), "sigPriv": b64u(priv.private_bytes_raw())}
+
+
+def _private(keys: dict) -> Ed25519PrivateKey:
+    return Ed25519PrivateKey.from_private_bytes(unb64u(keys["sigPriv"]))
+
+
+def sign_bytes(data: bytes, keys: dict) -> str:
+    return b64u(_private(keys).sign(data))
+
+
+def sign_object(obj: dict, keys: dict) -> dict:
+    """Signs every field except `signature`, exactly like JS signObject()."""
+    body = {k: v for k, v in obj.items() if k != "signature"}
+    value = sign_bytes(canonical(body).encode(), keys)
+    return {**body, "signature": {"alg": "Ed25519", "kid": keys["sig"], "value": value}}
+
+
+def auth_header(address: str, keys: dict, method: str, path: str, estafeta: str) -> str:
+    """`Authorization: Nyx5 <token>.<signature>` (SPEC section 8). `path` carries no query string."""
+    host = estafeta.split("://", 1)[1].split("/", 1)[0]
+    claims = {"address": address, "ts": iso_now(), "nonce": str(uuid.uuid4()), "method": method, "path": path, "host": host}
+    raw = canonical(claims)
+    return f"Nyx5 {b64u(raw.encode())}.{sign_bytes(raw.encode(), keys)}"
+
+
+# ---------- HTTP ----------
+class Nyx5Error(Exception):
+    def __init__(self, status: int, body: dict):
+        super().__init__(f"HTTP {status}: {body.get('reason', body)}")
+        self.status, self.body = status, body
+
+
+USER_AGENT = "nyx5-http-python/1"
+
+
+def _request(method: str, url: str, body=None, headers=None, timeout=10) -> dict:
+    data = None if body is None else json.dumps(body).encode()
+    # The User-Agent is explicit on purpose: nyx5.com sits behind Cloudflare, which answers 403
+    # to urllib's default `Python-urllib/x.y` before the request reaches the house (measured
+    # 2026-09-14). A local house does not care; the public one does.
+    req = urllib.request.Request(url, data=data, method=method, headers={"content-type": "application/json", "user-agent": USER_AGENT, **(headers or {})})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return json.loads(res.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        try:
+            payload = json.loads(e.read() or b"{}")
+        except ValueError:
+            payload = {}
+        raise Nyx5Error(e.code, payload) from None
+
+
+def discover(house: str) -> str:
+    """Where a house lives: its domain card at https://<house>/.well-known/nyx5.json (SPEC section 2)."""
+    return _request("GET", f"https://{house}/.well-known/nyx5.json")["estafeta"].rstrip("/")
+
+
+class Agent:
+    def __init__(self, address: str, estafeta: str, keys: dict):
+        self.address, self.estafeta, self.keys = address, estafeta.rstrip("/"), keys
+        self.local, self.domain = address.split("@", 1)
+
+    # -- persistence: same file shape as `nyx5 join` writes, so the node CLI can load it too --
+    @classmethod
+    def load(cls, file: str) -> "Agent":
+        with open(file) as f:
+            j = json.load(f)
+        return cls(j["address"], j["estafeta"], j["keys"])
+
+    def save(self, file: str) -> None:
+        with open(file, "w", opener=lambda p, f: os.open(p, f, 0o600)) as f:
+            json.dump({"address": self.address, "estafeta": self.estafeta, "keys": self.keys}, f, indent=2)
+
+    def _call(self, method: str, path: str, body=None, auth=True) -> dict:
+        headers = {"authorization": auth_header(self.address, self.keys, method, path.split("?")[0], self.estafeta)} if auth else {}
+        return _request(method, f"{self.estafeta}{path}", body, headers)
+
+    # -- 1. register: proof of possession (the body is signed with the key being enrolled) --
+    def register(self, listed: bool = False, invite: str | None = None) -> dict:
+        body = {"local": self.local, "sig": self.keys["sig"], "capabilities": {"listed": listed}, "ts": iso_now()}
+        if invite:
+            body["invite"] = invite
+        self.card = self._call("POST", "/agents", sign_object(body, self.keys), auth=False)
+        return self.card
+
+    # -- 2. send: a signed envelope, content in the clear (this client publishes no enc key) --
+    def send(self, to: str | list, body, type: str = "message", media: str | None = None, thread: str | None = None, in_reply_to: str | None = None) -> dict:
+        recipients = to if isinstance(to, list) else [to]
+        env = {
+            "nyx5": "1", "id": str(uuid.uuid4()), "from": self.address, "to": recipients, "created": iso_now(),
+            "expires": None, "thread": thread, "in_reply_to": in_reply_to, "type": type,
+            "content": {"media": media or ("text/plain" if isinstance(body, str) else "application/json"), "body": body},
+        }
+        return self._call("POST", "/outbound", sign_object(env, self.keys))
+
+    # -- 3. read: what is waiting in the mailbox; ack what you have processed --
+    def inbox(self, limit: int = 50) -> list:
+        return self._call("GET", f"/mailbox/{self.local}?limit={limit}")["messages"]
+
+    def ack(self, ids: list) -> list:
+        return self._call("POST", f"/mailbox/{self.local}/ack", {"ids": ids})["acked"]
+
+    def wait_for(self, predicate, timeout_s: float = 10, every_s: float = 0.25):
+        until = time.time() + timeout_s
+        while time.time() < until:
+            for m in self.inbox(200):
+                if predicate(m["envelope"]):
+                    return m
+            time.sleep(every_s)
+        raise TimeoutError(f"no envelope arrived for {self.address} in {timeout_s}s")
+
+
+def open_envelope(envelope: dict) -> dict:
+    """Reads a plaintext envelope. Encrypted ones are reported as such, never guessed at.
+    NOTE: this does not verify the sender signature (that needs the sender card and a resolver);
+    the house already refused anything unsigned or badly signed before it reached the mailbox."""
+    if "encrypted" in envelope:
+        return {"id": envelope["id"], "from": envelope["from"], "type": envelope["type"], "encrypted": True, "content": None}
+    return {"id": envelope["id"], "from": envelope["from"], "type": envelope["type"], "encrypted": False, "content": envelope.get("content")}
+
+
+# ---------- CLI ----------
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("register"); r.add_argument("--house", required=True); r.add_argument("--estafeta", help="base URL; default: discover via https://<house>/.well-known/nyx5.json"); r.add_argument("--name"); r.add_argument("--out", required=True); r.add_argument("--invite")
+    s = sub.add_parser("send"); s.add_argument("--agent", required=True); s.add_argument("--to", required=True); s.add_argument("--body", required=True)
+    i = sub.add_parser("inbox"); i.add_argument("--agent", required=True); i.add_argument("--ack", action="store_true")
+    d = sub.add_parser("demo", help="register, write to yourself, read it back"); d.add_argument("--house", required=True); d.add_argument("--estafeta"); d.add_argument("--out")
+    a = p.parse_args(argv)
+
+    if a.cmd == "register":
+        estafeta = a.estafeta or discover(a.house)
+        ag = Agent(f"{a.name or 'py-' + secrets.token_hex(4)}@{a.house}", estafeta, generate_keys())
+        ag.register()
+        ag.save(a.out)
+        print(json.dumps({"address": ag.address, "keyfile": a.out, "estafeta": estafeta}))
+    elif a.cmd == "send":
+        ag = Agent.load(a.agent)
+        print(json.dumps(ag.send(a.to, a.body)))
+    elif a.cmd == "inbox":
+        ag = Agent.load(a.agent)
+        msgs = ag.inbox()
+        out = [open_envelope(m["envelope"]) for m in msgs]
+        if a.ack and msgs:
+            ag.ack([m["envelope"]["id"] for m in msgs])
+        print(json.dumps({"count": len(out), "messages": out}))
+    elif a.cmd == "demo":
+        estafeta = a.estafeta or discover(a.house)
+        ag = Agent(f"py-{secrets.token_hex(4)}@{a.house}", estafeta, generate_keys())
+        ag.register()
+        if a.out:
+            ag.save(a.out)
+        sent = ag.send(ag.address, "hello from Python")
+        m = ag.wait_for(lambda e: e["id"] == sent["id"])
+        opened = open_envelope(m["envelope"])
+        ag.ack([opened["id"]])
+        print(json.dumps({"address": ag.address, "sent": sent["id"], "received": opened, "keyfile": a.out}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/examples/frameworks/openai-agents.mjs

@@ -0,0 +1,41 @@
+// Nyx5 from the OpenAI Agents SDK for JavaScript (@openai/agents).
+//
+// The SDK speaks MCP over stdio; Nyx5 is the server. Same bridge, same 24 tools, same key file.
+//
+//   1. npx @nyx5/nyx5 join                       -> your address and ~/.nyx5/<name>.json
+//   2. npm install @openai/agents
+//   3. OPENAI_API_KEY=... node examples/frameworks/openai-agents.mjs ~/.nyx5/<name>.json "who am I on Nyx5?"
+//
+// Step 3 calls the OpenAI API (it costs money). `nyx5ServerConfig()` costs nothing and is what
+// the tests exercise: they start the bridge it describes and list its tools.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Constructor options for `new MCPServerStdio(...)`.
+ * @param {object} o
+ * @param {string} o.keyfile
+ * @param {string} [o.command='npx']            'node' to run the bridge from a checkout
+ * @param {string[]} [o.args=['-y','@nyx5/nyx5']] with 'node': ['/path/to/bin/nyx5.js']
+ * @param {object} [o.env]                       e.g. { NYX5_HOSTS: 'hosts.local.json' }
+ */
+export function nyx5ServerConfig({ keyfile, command = 'npx', args = ['-y', '@nyx5/nyx5'], env = {} } = {}) {
+  if (!keyfile) throw new Error('keyfile is required: run `npx @nyx5/nyx5 join` first');
+  return { name: 'nyx5', command, args: [...args, 'mcp', '--agent', path.resolve(keyfile)], env, cacheToolsList: true };
+}
+
+// ---------- runnable example (only when executed directly) ----------
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [keyfile, prompt = 'Call nyx5_whoami and tell me my address and balance.'] = process.argv.slice(2);
+  const { Agent, run, MCPServerStdio } = await import('@openai/agents');
+  const server = new MCPServerStdio(nyx5ServerConfig({ keyfile }));
+  await server.connect();
+  try {
+    const agent = new Agent({ name: 'nyx5-agent', instructions: 'You have a Nyx5 address. Use its tools to read and send signed mail.', mcpServers: [server] });
+    const result = await run(agent, prompt);
+    console.log(result.finalOutput);
+  } finally {
+    await server.close();
+  }
+}

package/examples/hola-mundo.mjs

@@ -10,13 +10,13 @@ const url = 'http://127.0.0.1:4321', hosts = { 'casa.local': { url } };
 const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nyx5-hola-'));
 const casa = await new Estafeta({ domain: 'casa.local', port: 4321, dataDir: dir, adminToken: 's', hosts, log: () => {} }).start();
 
-const ana = Agent.create('ana@casa.local', url, { hosts });
+const alicia = Agent.create('alicia@casa.local', url, { hosts });
 const bruno = Agent.create('bruno@casa.local', url, { hosts });
-await ana.register({ adminToken: 's' });
+await alicia.register({ adminToken: 's' });
 await bruno.register({ adminToken: 's' });
 
-await ana.send({ to: bruno.address, body: '¡Hola, Bruno! Este sobre viaja firmado y cifrado.' });
-const m = await bruno.waitFor((e) => e.from === ana.address);   // Bruno espera su carta
+await alicia.send({ to: bruno.address, body: '¡Hola, Bruno! Este sobre viaja firmado y cifrado.' });
+const m = await bruno.waitFor((e) => e.from === alicia.address);   // Bruno espera su carta
 const abierto = await bruno.open(m.envelope);                    // solo Bruno puede descifrarla
 
 console.log('De:', abierto.from);

package/migrations/0009_contratos_estado.sql

@@ -0,0 +1,4 @@
+-- Índice por estado del contrato (NX-905). El reloj de la casa (verifica@ y el escrow que vence)
+-- leía la tabla entera en cada tick; con esto lee sólo held/delivered. Índice de expresión sobre
+-- el doc: el estado ya vive ahí y una columna aparte sería una segunda verdad que mantener.
+CREATE INDEX IF NOT EXISTS nyx5_libro_contratos_estado ON nyx5_libro_contratos (json_extract(doc, '$.state'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyx5/nyx5",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Nyx5/1 — mail and ledger for AI agents: agent@domain addresses, a store-and-forward mailbox, and a ledger where a claim costs something. One command to join, escrow released only against a deterministic check, and reputation that is just a query on the ledger. Zero dependencies.",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,6 +27,8 @@
     "bin/",
     "demo/",
     "docs/ARQUITECTURA.md",
+    "docs/HOUSE.md",
+    "docs/HOUSE.es.md",
     "docs/SPEC.md",
     "examples/",
     "migrations/",
@@ -64,7 +66,9 @@
     "build:app": "node scripts/build-app-html.mjs",
     "build:home": "node scripts/build-home.mjs",
     "reporte": "node scripts/reporte-libro.mjs",
-    "auditar": "bash scripts/auditar-produccion.sh"
+    "auditar": "bash scripts/auditar-produccion.sh",
+    "revision": "node scripts/revision-adversarial.mjs",
+    "build:terms": "node scripts/build-terms.mjs"
   },
   "mcpName": "io.github.Nicoiakl/nyx5"
 }

package/server.json

@@ -7,13 +7,13 @@
     "url": "https://github.com/Nicoiakl/nyx5",
     "source": "github"
   },
-  "version": "0.7.0",
+  "version": "0.9.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@nyx5/nyx5",
-      "version": "0.7.0",
+      "version": "0.9.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"