unibots/app.md

---
name: unibots
lang: go
domain: infra
version: 0.2.0
description: "Plataforma de bots en Go (core puro + shell impuro: LLM, memoria, tools, crons, dashboard TUI) que hablan por el bus unibus. Migrada desde agents_and_robots con Matrix-out: el transporte ya no es Matrix sino unibus (rooms + E2E)."
tags: [bots, messaging, unibus-client, llm, service]
uses_functions: []
uses_types: []
framework: ""
entry_point: "cmd/dashboard"
dir_path: "projects/message_bus/apps/unibots"
repo_url: "https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/unibots"
e2e_checks:
  - id: build
    cmd: "CGO_ENABLED=0 go build ./..."
    timeout_s: 180
  - id: vet
    cmd: "CGO_ENABLED=0 go vet ./..."
    timeout_s: 120
  - id: unit
    cmd: "CGO_ENABLED=0 go test ./..."
    timeout_s: 180
---

## Qué es

`unibots` es la plataforma de **bots** que consumen el bus de mensajería
[`unibus`](../unibus/). Es la evolución de `agents_and_robots`: el mismo cerebro
(personalidad, reglas de decisión, memoria, tools, crons, LLM) pero con el
**transporte migrado de Matrix a unibus** (operación "Matrix-out", 07/06/2026).

Un **bot** es todo peer automatizado del bus, con o sin LLM. Un **bot agente** es
un bot que contiene un LLM. El término único en código, nombres y docs es **bot**.
Ver [[convencion-bot-vs-agente]].

### Arquitectura

Cada bot combina un **core puro** (`pkg/`: transformaciones, reglas de decisión,
personalidad — determinista, sin I/O) con un **shell impuro** (`shell/`: LLM, SSH,
base de datos, tools, side effects). El acoplamiento a Matrix se eliminó de raíz;
en su lugar hay un **seam neutral**:

- `pkg/transport` — interfaz `Transport` + tipo `InboundMessage` agnósticos del
  transporte. El core (`agents/handler.go::handleInbound`) no sabe si detrás hay
  Matrix, unibus o un mock.
- `shell/transportunibus/` — implementación de `Transport` sobre la librería
  cliente de unibus (`github.com/enmanuel/unibus/pkg/client`). Modelo **"todo son
  rooms"** + **E2E** (`room.ModeMatrix`): el bot descubre las rooms a las que
  pertenece por polling de `client.ListMyRooms()` (endpoint `GET
  /members/{endpoint}/rooms` de unibus ≥ v0.4.0), hace `Join` + `Subscribe`,
  descifra y responde en la misma room. `busSender` adapta runner / cron / tools
  a ese transporte.

### Comandos (`cmd/`)

| Comando | Qué hace |
|---|---|
| `cmd/dashboard` | TUI interactiva de gestión de bots (entry point principal) |
| `cmd/launcher` | Supervisa y relanza los bots cuando salen sin cancelación |
| `cmd/agentctl` | CLI de control: arrancar/parar/estado de bots, HTTP API + SSE |
| `cmd/register` | Alta de un bot nuevo |

### Configuración de un bot

Cada bot declara un bloque `bus:` (sustituye al antiguo `matrix:`):

```yaml
bus:
  nats_url: nats://127.0.0.1:4250
  ctrl_url: http://127.0.0.1:8470
  identity_path: local_files/<bot>.id
  handle: <nombre-publico>
  command_prefix: "!"
  threads: true
```

`unibots` es **código de aplicación**, no funciones del registry: orquesta la
librería cliente de `unibus` y no reimplementa protocolo ni cripto. Por eso
`uses_functions` está vacío — el crypto/transporte lo aporta `unibus`, que a su
vez importa las primitivas del dominio `cybersecurity` del registry.

> Nota de módulo Go: el `module` interno sigue siendo `github.com/enmanuel/agents`
> (heredado de agents_and_robots) para no reescribir ~100 imports durante el move.
> El repositorio Gitea es `dataforge/unibots`. El desajuste nombre-módulo/repo es
> cosmético y no afecta al build; renombrar el módulo a `github.com/enmanuel/unibots`
> queda como tarea futura opcional.

## Ejemplo

Levantar el bus y lanzar la plataforma de bots contra él:

```bash
# 1. Bus de membresía/claves (NATS embebido :4250, control plane HTTP :8470)
cd projects/message_bus/apps/unibus
go run ./cmd/membershipd

# 2. En otra terminal: la TUI de gestión de bots
cd projects/message_bus/apps/unibots
go run ./cmd/dashboard

# Alternativa headless: supervisor que mantiene los bots vivos
go run ./cmd/launcher
```

## Cuando usarla

- Cuando quieras **correr bots autónomos** (con o sin LLM) que conversen por el
  bus unibus en vez de Matrix.
- Como **plataforma destino del ecosistema de bots**: a partir de ahora se trabaja
  aquí, no en `agents_and_robots` (archivado como museo de la era Matrix).
- Para añadir un **bot nuevo**: `cmd/register` + un bloque `bus:` en su config; el
  core es transport-agnóstico, así que solo escribes la lógica del handler (regla
  `.claude/rules/create_agent.md`).

## Gotchas

- **Matrix-out total.** Se borraron `shell/matrix/`, `tools/matrix/`, `cmd/verify/`
  (cross-signing) y la dependencia `maunium.net/go/mautrix`. El build es
  `CGO_ENABLED=0 go build ./...` a secas, sin `-tags goolm` ni `libolm`. Presencia,
  typing y avatares desaparecieron: no existen en unibus.
- **Imports relativos a unibus y al registry.** `go.mod` usa `replace
  github.com/enmanuel/unibus => ../unibus` y `replace fn-registry => ../../../..`.
  Ambos son paths relativos a la ubicación de la app: si se mueve, hay que
  reajustarlos o el build rompe. (Se ajustaron al traer la app desde
  `~/DataProyects/Github/agents_and_robots`.)
- **Identidad = secreto crítico.** Cada `local_files/<bot>.id` lleva las claves
  privadas del bot (Ed25519 + X25519), 0600, gitignorado. Perderlo cambia la
  identidad pública del bot en el bus.
- **El bot descubre rooms por polling.** No hay push de invitaciones: el transporte
  unibus hace polling de `ListMyRooms()`. La latencia de incorporación a una room
  ≈ el intervalo de polling.
- **Build sin CGO.** Crypto del registry (`cybersecurity`) + driver SQLite pure-Go
  (`modernc.org/sqlite`) compilan limpio sin `gcc`.

## Gaps abiertos (heredados del Matrix-out)

- **Directorio de bots** (handle → endpoint público) para que un frontend pueda
  invitar a un bot por nombre.
- **Orquestador multi-bot** aparcado: existía atado a mautrix, aún sin recablear al
  bus.
- **Docs internas desactualizadas**: `README.md` y `.claude/CLAUDE.md` todavía
  describen la era Matrix (homeserver, `-tags goolm`, `matrix:`). Pendiente de
  reescritura para reflejar el transporte unibus.

## Capability growth log

- v0.2.0 (2026-06-07) — la app deja de ser el scaffold del echobot y pasa a ser la
  plataforma completa de bots importada desde `agents_and_robots` con el transporte
  migrado a unibus (Matrix-out). El módulo Go conserva el path
  `github.com/enmanuel/agents`; los `replace` de unibus y fn-registry se reajustaron
  a la nueva ubicación. `agents_and_robots` queda archivado; el trabajo activo
  continúa aquí.