Egutierrez
81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
---
|
|
name: message_bus
|
|
description: "Bus de mensajería unificado sobre NATS+JetStream con cifrado E2E por room (patrón megolm/olm reducido). Peers uniformes: procesos, chat humano y agentes LLM hablan el mismo protocolo."
|
|
tags: [messaging, nats, e2e, bus, service]
|
|
repo_url: "https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/message_bus"
|
|
---
|
|
|
|
## Notas
|
|
|
|
Bus de mensajería con identidad uniforme: un solo tejido de comunicación donde cualquier
|
|
participante —procesos/workers, interfaces de chat humanas, agentes LLM— es un peer de primera
|
|
clase. Todos hablan el mismo protocolo y se diferencian solo por las rooms a las que se unen y
|
|
por lo que hacen con lo que reciben.
|
|
|
|
### Qué reemplaza
|
|
|
|
Este project sustituye dos piezas de infraestructura existentes:
|
|
|
|
- **`agents_and_robots`** (`egutierrez/agents_and_robots` en Gitea): plataforma Go de bots Matrix
|
|
autónomos acoplada a `maunium.net/go/mautrix`. Su lógica de agente (`pkg/{decision,personality,
|
|
knowledge,memory,llm,skills,tools,orchestration,acl}`) se preserva; solo cambia la capa de
|
|
transporte (Matrix → este bus).
|
|
- **El servidor Matrix self-hosted (Synapse)** de `organic-machine.com`.
|
|
|
|
La integración con `agents_and_robots` es una fase posterior: v1 construye y valida el bus de forma
|
|
autónoma (service de membresía/claves + librería cliente + peers demo).
|
|
|
|
### Decisión arquitectónica
|
|
|
|
NATS (+ JetStream) como motor de transporte; una capa fina encima aporta lo que NATS no tiene:
|
|
membresía de rooms, invitaciones con reparto de clave, y cifrado E2E del payload. No se construye un
|
|
broker ni un protocolo propios.
|
|
|
|
### Alcance v1 (decisiones acordadas)
|
|
|
|
- **Solo el bus**: service de membresía/claves + librería cliente Go + peers demo (worker + chat),
|
|
todo arrancable con `go run`. Integración con `agents_and_robots` en fase aparte.
|
|
- **Rotación de clave activa**: al hacer LEAVE/KICK la clave de room `K` rota a un nuevo epoch y se
|
|
re-reparte solo a los miembros restantes. Forward secrecy real (paridad con Matrix), no el modo
|
|
"sin rotación" del documento de diseño original.
|
|
- **Media en object store**: los adjuntos no viajan por el bus. Se cifran y se suben a un object
|
|
store; por NATS solo viaja una referencia (hash + nonce). El bus transporta mensajes, no blobs.
|
|
- **NATS embebido**: el service arranca un `nats-server` embebido con JetStream para que todo
|
|
funcione con `go run` sin instalar nada. Flag `--nats-url` para apuntar a un NATS externo en
|
|
producción.
|
|
|
|
### Criptografía (funciones del registry, capability group `e2e-messaging`)
|
|
|
|
El cifrado E2E se compone de primitivas del registry, no de código inline:
|
|
|
|
- `generate_identity_go_cybersecurity` — par Ed25519 (firma) + X25519 (intercambio de claves).
|
|
- `seal_aead_go_cybersecurity` / `open_aead_go_cybersecurity` — ChaCha20-Poly1305 sobre el payload.
|
|
- `seal_key_box_go_cybersecurity` / `open_key_box_go_cybersecurity` — sealed box anónimo (nacl/box)
|
|
para repartir `K` a un invitado por su pubkey X25519.
|
|
- `sign_ed25519_go_cybersecurity` / `verify_ed25519_go_cybersecurity` — firma por-mensaje.
|
|
|
|
### Apps
|
|
|
|
- `apps/unibus/` — el bus completo: librería cliente (`pkg/client`), service de membresía/claves
|
|
(`cmd/membershipd`, tag `service`), object store, y peers demo (`cmd/worker`, `cmd/chat`).
|
|
|
|
### Terminología: peer, bot, bot agente
|
|
|
|
Convención única del proyecto (reemplaza la antigua distinción "agentes" vs "robots" de
|
|
`agents_and_robots`):
|
|
|
|
- **peer** — cualquier participante del bus. Es la unidad del protocolo: todos los peers son
|
|
iguales y se diferencian solo por las rooms a las que se unen y por lo que hacen al recibir un
|
|
mensaje. Un peer puede ser un proceso, un humano o un bot.
|
|
- **bot** — término único para todo peer automatizado (programático), tenga o no un LLM. Sustituye
|
|
la dualidad previa donde un peer sin LLM se llamaba "robot" y uno con LLM "agente". A partir de
|
|
ahora todos los participantes automatizados son **bots**.
|
|
- **bot agente** (abreviado "agente") — un bot que contiene un LLM en su lógica de decisión. Es un
|
|
subtipo de bot, no una categoría aparte.
|
|
- **humano** — peer con una persona detrás, que usa un cliente de interfaz (hoy el playground web).
|
|
No es un bot.
|
|
|
|
Implicación para la Fase 2 (migración de `agents_and_robots`): los dos tipos actuales `Agent`
|
|
(`agents/runtime.go`) y `Robot` (`agents/robot.go`) se unifican conceptualmente bajo **bot**; un
|
|
**bot agente** es simplemente el bot cuyo handler invoca un LLM.
|