---
name: agents_and_robots
lang: go
domain: agents
version: 0.2.0
description: "Plataforma Go de bots autonomos Matrix con arquitectura pure core / impure shell. Launcher, agentctl, dashboard TUI, register y HTTP API REST+SSE."
tags: [agents, matrix, bots, llm, element, e2ee, tools, service]
uses_functions: []
uses_types: []
framework: "mautrix"
entry_point: "cmd/launcher/main.go"
dir_path: "projects/element_agents/apps/agents_and_robots"
repo_url: "https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/egutierrez/agents_and_robots.git"
service:
  port: 8487
  health_endpoint: /health
  health_timeout_s: 5
  systemd_unit: agents_and_robots.service
  systemd_scope: system
  restart_policy: always
  runtime: systemd-system
  pc_targets:
    - organic-machine.com
  is_local_only: false
e2e_checks:
  - id: build
    cmd: "go build -tags goolm ./..."
    timeout_s: 120
  - id: tests
    cmd: "go test -tags goolm -count=1 ./internal/api/... ./cmd/launcher/..."
    timeout_s: 60
  - id: smoke_health
    cmd: "AGENTS_API_KEY=test-e2e-smoke ./bin/launcher --api-port 18487 &"
    health: "http://127.0.0.1:18487/health"
    timeout_s: 10
  - id: smoke_auth
    cmd: "curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:18487/agents"
    expect_stdout_contains: "401"
    timeout_s: 5
---

## Deploy

- **VPS:** organic-machine.com (SSH alias: organic-machine.com)
- **Remote path:** /home/ubuntu/CodeProyects/agents_and_robots
- **Build:** `go build -tags goolm -ldflags="-s -w" -o bin/launcher ./cmd/launcher`
- **Run (manual):** `./bin/launcher --log-level info --api-port 8487`
- **Run (systemd):** `systemctl start agents_and_robots.service` (unit en `systemd/agents_and_robots.service`)
- **Binarios:** launcher, agentctl, register, dashboard, verify (en bin/)
- **Config:** agents/*/config.yaml + .env con tokens Matrix, API keys LLM, pickle keys E2EE

## HTTP API (v0.1)

Puerto: **8487** (local, Traefik termina TLS en `agents.organic-machine.com`).
Auth: `Authorization: Bearer $AGENTS_API_KEY` (32 bytes hex en `.env`).

| Verbo | Path | Descripcion |
|---|---|---|
| GET | `/health` | Liveness (sin auth) |
| GET | `/agents` | Lista todos los agentes con estado |
| GET | `/agents/{id}` | Detalle + logs recientes |
| POST | `/agents/{id}/start` | Arrancar agente |
| POST | `/agents/{id}/stop` | Parar agente |
| POST | `/agents/{id}/restart` | Stop + Start |
| GET | `/agents/{id}/logs?n=200` | Snapshot de logs |
| GET | `/sse/status` | SSE: diffs de estado cada 2s |
| GET | `/sse/agents/{id}/logs` | SSE: tail -f del logfile |

**TODO v0.2:** POST `/agents/{id}/message`, PUT `/agents/{id}/config`, SSE messages stream.
**TODO escala:** si se anade un 2do cliente HTTP (otro VPS, otro frontend), reemplazar el pubsub in-memory con NATS o Redis.

## Systemd

Unit en `systemd/agents_and_robots.service`. Para instalar en el VPS:

```bash
# En el VPS (ubuntu@organic-machine.com)
sudo cp systemd/agents_and_robots.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now agents_and_robots.service
```

Importante: usa `Restart=always` (no `on-failure`) para reiniciar incluso tras exit limpio.

## Traefik + DNS (post-merge, humano)

Pasos que el humano completa tras mergear el PR:
1. Crear DNS A record `agents.organic-machine.com` apuntando a la IP del VPS.
2. En Traefik (standalone o Coolify): ruta `agents.organic-machine.com → 127.0.0.1:8487` con HTTPS+LE.
3. Verificar: `curl -fsS https://agents.organic-machine.com/health`.
4. Generar API key: `openssl rand -hex 32` y escribir `AGENTS_API_KEY=<key>` en `.env` del VPS.

## Notas

4 binarios principales:
- **launcher** — Inicia agentes como goroutines, descubre configs, sync Matrix, HTTP API
- **agentctl** — CLI: list, start, stop, remove agentes
- **register** — Registra usuarios bot en Synapse via admin API
- **dashboard** — TUI interactiva (bubbletea) para gestion de agentes

Agentes desplegados: assistant-bot, asistente-2, meteorologo, wikipedia-bot, exchange-bot, reminder-bot, test-bot, father-bot (orchestrator).

Dependencias clave: mautrix-go, go-openai, mcp-go, cobra, bubbletea, modernc/sqlite, zerolog.
No requiere CGO (usa pure Go SQLite via modernc).


## Capability growth log

Una linea por bump SemVer. Bump-type segun `.claude/commands/version.md`:
- `major`: breaking observable (CLI args, schema BBDD propia, formato wire).
- `minor`: feature aditiva (nuevo panel, endpoint, opcion).
- `patch`: bugfix sin cambio observable.

- v0.1.0 (2026-05-18) — baseline.
- v0.2.0 (2026-05-22) — HTTP API REST+SSE (internal/api), systemd unit, --api-port flag en launcher.