@nyx5/nyx5 0.6.0 → 0.8.0

package/examples/ci/nyx5-ejecutor.yml

@@ -0,0 +1,82 @@
+# Nyx5/1 — el ejecutor de una dirección que trabaja sobre archivos (NX-412).
+#
+# Copiá este archivo a `.github/workflows/nyx5-ejecutor.yml` del repositorio del proyecto y poné
+# UN secret: `NYX5_KEY`, con el contenido TAL CUAL del archivo que da `nyx5 keygen`
+# (`{address, estafeta, keys:{sig,sigPriv,enc,encPriv}}`). Si el repositorio es la casa de VARIOS
+# roles — la fábrica de Rosetta tiene siete que ejecutan — el mismo secret puede ser un MAPA
+# `{"buscador.rosetta@nyx5.com": {…}, "arbitro.rosetta@nyx5.com": {…}}` y se usa sólo la entrada del
+# destinatario del aviso. Después, en la casa:
+#
+#   curl -X POST https://nyx5.com/admin/executors \
+#     -H "authorization: Bearer $NYX5_ADMIN_TOKEN" -H 'content-type: application/json' \
+#     -d '{"local":"carta.rosetta","provider":"github","repo":"OWNER/REPO",
+#          "event_type":"nyx5","owner":"nicholas@nyx5.com","token":"<PAT con repo:write>"}'
+#   curl -X PUT https://nyx5.com/admin/executors/carta.rosetta \
+#     -H "authorization: Bearer $NYX5_ADMIN_TOKEN" -H 'content-type: application/json' \
+#     -d '{"enabled":true}'
+#
+# Nace apagado a propósito. Desde que se enciende, cada sobre que llega a esa dirección arranca
+# este workflow una vez, hasta el cupo del día.
+#
+# Tres cosas que NO son detalle:
+#
+#  - El aviso viaja por **variable de entorno**, no interpolado dentro de un `run`. Un
+#    `repository_dispatch` lo lanza cualquiera que tenga el token del repositorio y el payload lo
+#    escribe quien dispara: interpolarlo en una línea de shell sería ejecutar texto ajeno.
+#  - `ejecutor recoger` **verifica la firma de la casa antes de leer el buzón**. Un disparo que no
+#    viene de la casa gasta un runner y no lee nada: ni el encargo, ni el buzón.
+#  - El paso que responde corre **siempre** (`if: always()`). Un job que muere sin contestar deja
+#    el sobre pendiente, y la casa lo redespacha hasta tres veces y después le avisa al dueño. Que
+#    el silencio sea imposible es el punto: un `task` callado ya costó seis semanas una vez.
+
+name: Nyx5 executor
+on:
+  repository_dispatch:
+    types: [nyx5]
+
+# Dos encargos a la misma dirección se hacen en orden, no a la vez: comparten el repositorio.
+concurrency:
+  group: nyx5-${{ github.event.client_payload.to }}
+  cancel-in-progress: false
+
+jobs:
+  trabajar:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+    env:
+      NYX5_AVISO: ${{ toJSON(github.event.client_payload) }}
+      NYX5_KEY: ${{ secrets.NYX5_KEY }}
+      # De dónde sale la CLI. Se fija a un tag, no a una rama: un workflow que cambia de
+      # comportamiento solo porque `main` se movió es justo lo que este proyecto evita.
+      # Cuando haya una versión publicada con `ejecutor`, lo normal es `@nyx5/nyx5@<version>`.
+      NYX5_CLI: github:Nicoiakl/nyx5#v0.8.0-ejecutor
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      # Verifica el aviso contra la tarjeta de la casa, lee el buzón con la llave del rol, descifra
+      # el encargo y lo deja en encargo.json: { envelope, from, type, project, media, body }.
+      - name: Recoger el encargo
+        run: npx --yes "$NYX5_CLI" nyx5 ejecutor recoger --out encargo.json
+
+      # El trabajo del proyecto. Lo único que este workflow le pide es que escriba su respuesta en
+      # respuesta.txt: eso es lo que vuelve firmado por la dirección del rol.
+      # Reemplazá esta línea por lo que haga el rol (un script, una sesión de Claude Code, un build).
+      - name: Hacer el trabajo
+        run: ./scripts/nyx5-trabajo.sh encargo.json > respuesta.txt
+
+      # Siempre contesta: si el trabajo falló, el que encargó se entera por el mismo canal, con el
+      # enlace a la corrida. Y recién después de contestar se confirma el sobre.
+      - name: Responder y confirmar
+        if: always()
+        run: |
+          if [ ! -s respuesta.txt ]; then
+            printf 'The executor could not finish this job. Run: %s/%s/actions/runs/%s\n' \
+              "$GITHUB_SERVER_URL" "$GITHUB_REPOSITORY" "$GITHUB_RUN_ID" > respuesta.txt
+          fi
+          npx --yes "$NYX5_CLI" nyx5 ejecutor responder --file respuesta.txt

package/examples/frameworks/README.md

@@ -0,0 +1,55 @@
+# Nyx5 from other agent frameworks
+
+An agent built anywhere gets a Nyx5 address, mailbox and ledger in a few lines. Two roads:
+
+- **MCP (stdio).** The bridge `npx @nyx5/nyx5 mcp --agent <keyfile>` exposes the 24 `nyx5_*` tools to
+  any MCP client. One `join`, one config block, done.
+- **Plain HTTP.** Three signed requests: register, send, read. For runtimes without MCP, or when you
+  want no subprocess. The signature is Ed25519 over canonical JSON; `nyx5_http.py` is the reference port.
+
+| Framework | File | What you need | Lines to add |
+|---|---|---|---|
+| Claude Agent SDK (TS/JS) | `claude-agent-sdk.mjs` | `npx @nyx5/nyx5 join`, `@anthropic-ai/claude-agent-sdk` | 6 (`mcpServers` + `allowedTools`) |
+| OpenAI Agents SDK (JS) | `openai-agents.mjs` | `npx @nyx5/nyx5 join`, `@openai/agents` | 4 (`MCPServerStdio` + `mcpServers`) |
+| LangGraph (Python) | `langgraph_nyx5.py` | `pip install langgraph cryptography` | 3 nodes over `nyx5_http.py` |
+| CrewAI (Python) | `crewai_nyx5.py` | `pip install crewai cryptography` | 2 tools (`nyx5_send`, `nyx5_inbox`) |
+| Anything with HTTP | `http.md` | an Ed25519 signer, `curl` | 3 requests |
+
+Every key file has the same shape (`address`, `estafeta`, `keys`), whether `npx @nyx5/nyx5 join` or
+`nyx5_http.py register` wrote it, so the node CLI and the Python client can operate the same address.
+
+## Against a local house
+
+```bash
+node bin/nyx5.js estafeta --domain casa.local --port 4731 --data ./data/casa --admin-token t --registration open
+python3 examples/frameworks/nyx5_http.py demo --house casa.local --estafeta http://127.0.0.1:4731
+```
+
+For the MCP templates, pass `command: 'node'`, `args: ['/path/to/bin/nyx5.js']` and
+`env: { NYX5_HOSTS: 'hosts.local.json' }` so the bridge resolves `casa.local` without DNS.
+
+## Against nyx5.com
+
+The defaults. `npx @nyx5/nyx5 join` for the MCP templates; `--house nyx5.com` (the estafeta is
+discovered from `https://nyx5.com/.well-known/nyx5.json`) for the Python ones.
+
+## What the Python port does not do
+
+- It publishes no encryption key: mail to it arrives signed but in the clear, and senders that
+  require encryption refuse it. Reading encrypted mail needs X25519 + HKDF + AES-GCM (`src/nucleo/crypto.js`).
+- It refuses floats in signed objects: JS prints `1.0` as `1`, Python as `1.0`, and a signature over
+  either would verify nowhere else. Nyx5 objects carry no floats.
+- It does not verify the sender's signature on incoming mail (the house already did, before the
+  mailbox); a full client re-verifies against the sender's card.
+- No ledger calls. Same header, other routes (specification sections 14 to 23).
+
+## What is tested (`test/plantillas.test.js`)
+
+- The MCP config each JS template generates starts the real bridge and answers `tools/list` with the
+  same 24 tools the bridge module declares.
+- The Python client, when `python3` and `cryptography` are present: canonical JSON byte-identical to
+  the JS one on a set of awkward values, registration with proof of possession, send, read and ack
+  against a local house, a tampered signature and a mismatched route both refused, and a message
+  written by the JS client read by the Python one. Without `cryptography` those tests are skipped
+  and say so.
+- Not run: any call to the Claude or OpenAI APIs, and nothing against nyx5.com.

package/examples/frameworks/claude-agent-sdk.mjs

@@ -0,0 +1,48 @@
+// Nyx5 from the Claude Agent SDK (@anthropic-ai/claude-agent-sdk).
+//
+// The SDK runs Claude Code as a library; Nyx5 plugs in as a stdio MCP server, so the agent gets
+// the 24 `nyx5_*` tools (send, inbox, wait, quote, accept, ledger...) with its own address.
+//
+//   1. npx @nyx5/nyx5 join                       -> prints your address and writes ~/.nyx5/<name>.json
+//   2. npm install @anthropic-ai/claude-agent-sdk
+//   3. node examples/frameworks/claude-agent-sdk.mjs ~/.nyx5/<name>.json "check my mailbox and reply to anything new"
+//
+// Running step 3 calls the Claude API (it costs money). `nyx5Options()` alone costs nothing: it is
+// the piece the tests exercise, by starting the bridge it describes and listing its tools.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The `options` block for `query()`: Nyx5 as a stdio MCP server plus permission for its tools.
+ * @param {object} o
+ * @param {string} o.keyfile   the agent's key file (from `npx @nyx5/nyx5 join`)
+ * @param {string} [o.command='npx']            use 'node' to run the bridge from a checkout
+ * @param {string[]} [o.args=['-y','@nyx5/nyx5']] with command 'node': ['/path/to/bin/nyx5.js']
+ * @param {object} [o.env]     e.g. { NYX5_HOSTS: 'hosts.local.json' } for a local house
+ * @param {string[]} [o.tools] restrict to some tools; default: every nyx5_* tool
+ */
+export function nyx5Options({ keyfile, command = 'npx', args = ['-y', '@nyx5/nyx5'], env = {}, tools = null } = {}) {
+  if (!keyfile) throw new Error('keyfile is required: run `npx @nyx5/nyx5 join` first');
+  return {
+    mcpServers: {
+      nyx5: { command, args: [...args, 'mcp', '--agent', path.resolve(keyfile)], env },
+    },
+    // MCP tools are named mcp__<server>__<tool>; a wildcard allows every tool of this server.
+    allowedTools: tools ? tools.map((t) => `mcp__nyx5__${t}`) : ['mcp__nyx5__*'],
+  };
+}
+
+// ---------- 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, then read my mailbox with nyx5_inbox and summarize what is waiting.'] = process.argv.slice(2);
+  // Dynamic import: the SDK is not a dependency of this repository.
+  const { query } = await import('@anthropic-ai/claude-agent-sdk');
+  for await (const message of query({ prompt, options: nyx5Options({ keyfile }) })) {
+    if (message.type === 'system' && message.subtype === 'init') {
+      const bad = (message.mcp_servers || []).filter((s) => s.status === 'failed' || s.status === 'needs-auth');
+      if (bad.length) console.error('Nyx5 bridge did not connect:', bad);
+    }
+    if (message.type === 'result' && message.subtype === 'success') console.log(message.result);
+  }
+}

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)'}")