Files

T

egutierrez f5b857dbc6 feat: add bubbletea TUI dashboard for bot server management

Implementa un dashboard interactivo con bubbletea siguiendo el patrón
pure core / impure shell del proyecto:

- pkg/tui/ (PURE): Model, Update, View — solo fmt y strings, cero I/O.
  Update produce Intent[] (datos puros) en vez de side effects.
- shell/tui/ (IMPURE): Adapter convierte Intent[] en tea.Cmd[] con I/O real
  (process management, /proc stats, log tail).
- cmd/dashboard/ (composición): Bridge conecta pure Update con shell Adapter
  usando la Elm Architecture de bubbletea.

Pantallas: Main Menu → Agent List → Agent Actions (start/stop/restart/kill) → Logs.
Navegación: flechas ↑↓, Enter seleccionar, 0 volver, q salir.

Dependencias añadidas: bubbletea, lipgloss.
Actualiza .gitignore para anclar binarios a raíz (/agentctl, /dashboard).
Documenta nuevos scripts en CLAUDE.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-04 19:38:30 +00:00

6.9 KiB

Raw Blame History

CLAUDE.md — Contexto del proyecto agents_and_robots

Qué es este proyecto

Monorepo en Go para gestionar bots Matrix. Cada bot es un agente autónomo con personalidad, reglas de decisión y acceso a herramientas (LLM, SSH, HTTP, MCP). Los bots se comunican entre sí y con humanos a través de Matrix (mautrix-go).

Homeserver activo: https://matrix-af2f3d.organic-machine.com Server name: matrix-af2f3d.organic-machine.com

Filosofía de diseño — LA REGLA MÁS IMPORTANTE

El proyecto usa el patrón pure core / impure shell estrictamente:

pkg/      → PURE: solo tipos, funciones puras, cero side effects
shell/    → IMPURE: todo I/O, red, filesystem, procesos
agents/   → composición: reglas puras + ensamblado con shell en runtime.go

Nunca añadir side effects (I/O, red, llamadas a APIs) dentro de pkg/. Siempre que el core necesite "hacer algo", produce un []decision.Action (datos puros) que el shell interpreta.

El flujo es siempre:

Matrix event → Parse (pure) → Evaluate rules (pure) → []Action (pure data)
            → Runner.Execute (impure) → efectos reales

Módulo Go

github.com/enmanuel/agents

Estructura de directorios

pkg/decision/     → motor de reglas puro (Evaluate, Rule, MatchFunc, Action)
pkg/llm/          → tipos de LLM puros (CompleteFunc, CompletionRequest, Route)
pkg/tools/        → specs declarativas de herramientas (SSHCommandSpec, etc.)
pkg/message/      → parse y format de mensajes Matrix (puros)
pkg/personality/  → tipos de personalidad (Personality, Tone, etc.)

shell/llm/        → clientes LLM reales (anthropic.go, openai.go, factory.go)
shell/matrix/     → cliente Matrix mautrix-go (client.go, listener.go)
shell/ssh/        → ejecutor SSH real (executor.go)
shell/effects/    → Runner que interpreta []Action → side effects
shell/bus/        → comunicación inter-agente via Go channels
shell/protocols/  → adaptadores MCP (mcp.go)

agents/runtime.go      → Agent{}: ensambla core + shell, maneja eventos
agents/assistant/      → reglas puras + config del assistant-bot
agents/devops/         → reglas puras + config del devops-bot

internal/config/schema.go  → tipos completos del YAML de configuración
internal/config/loader.go  → Load() con expand env vars, LoadMeta() sin validación
cmd/launcher/main.go       → inicia agentes, tiene rulesRegistry
cmd/agentctl/main.go       → CLI de gestión (list, start, stop, remove)
cmd/register/main.go       → registra bots en Synapse via admin API
dev-scripts/               → scripts bash para operaciones del día a día

Agentes existentes

ID	Estado	LLM	Descripción
assistant-bot	activo	GPT-4o	Asistente general, responde DMs
devops-bot	pendiente	Claude	SSH, deployments, healthchecks

Dependencias clave

maunium.net/go/mautrix v0.21.1     → Matrix client
github.com/sashabaranov/go-openai  → OpenAI + Ollama-compatible
github.com/mark3labs/mcp-go        → MCP protocol server/client
golang.org/x/crypto/ssh            → SSH execution
github.com/spf13/cobra             → CLI
gopkg.in/yaml.v3                   → Config parsing

Configuración de agentes

Cada agente vive en agents/<id>/:

config.yaml — configuración completa (ver schema en internal/config/schema.go)
agent.go — reglas puras que implementan Rules() []decision.Rule
prompts/system.md — system prompt del LLM
data/ — datos de runtime (SQLite, crypto, logs) — en .gitignore

El config.yaml soporta variables de entorno con ${VAR} y $VAR. El loader usa os.ExpandEnv.

Secciones principales del config: agent, personality, llm, tools, matrix, agents (peers), ssh, security, schedules, observability, resilience, storage.

Cómo añadir un nuevo bot

Generar scaffold: ./dev-scripts/new-agent.sh <id> "Display Name"
Registrarlo en Matrix: ./dev-scripts/register.sh <id> "Display Name"
Añadir el token al .env
Añadir una línea en cmd/launcher/main.go → rulesRegistry
Editar agents/<id>/agent.go con las reglas reales
Arrancar: ./dev-scripts/start.sh <id>

Dev-scripts disponibles

./dev-scripts/list.sh                    # ver todos los bots y estado
./dev-scripts/start.sh [agent-id]       # iniciar uno o todos
./dev-scripts/stop.sh [agent-id]        # detener uno o todos
./dev-scripts/restart.sh [agent-id]     # reiniciar uno o todos
./dev-scripts/ps.sh [agent-id]          # procesos con detalle (PID, mem, CPU, uptime)
./dev-scripts/remove.sh <agent-id>      # deshabilitar (sin borrar datos)
./dev-scripts/register.sh <id> [name]   # registrar bot en Matrix
./dev-scripts/logs.sh [agent-id]        # tail -f de logs
./dev-scripts/new-agent.sh <id> [name]  # scaffold completo

# Gestión unificada del servidor
./dev-scripts/server.sh start [id]      # iniciar agentes
./dev-scripts/server.sh stop [id]       # detener agentes
./dev-scripts/server.sh restart [id]    # reiniciar agentes
./dev-scripts/server.sh status          # resumen general del servidor
./dev-scripts/server.sh ps [id]         # procesos con detalle
./dev-scripts/server.sh logs [id]       # tail -f de logs
./dev-scripts/server.sh kill [id]       # SIGKILL forzado (emergencia)

PID files: run/<id>.pid | Log files: run/<id>.log

Gestión de procesos

Los bots corren como procesos independientes lanzados por agentctl o dev-scripts/start.sh. Cada proceso escribe su PID en run/<id>.pid y su log en run/<id>.log. is_running() usa kill -0 <pid> para verificar sin matar el proceso.

Variables de entorno críticas

MATRIX_HOMESERVER         # URL del servidor Matrix
MATRIX_SERVER_NAME        # nombre del servidor (parte después de :)
MATRIX_ADMIN_TOKEN        # token admin para registrar bots (cmd/register)
MATRIX_TOKEN_<BOT>        # access token de cada bot
OPENAI_API_KEY            # OpenAI
ANTHROPIC_API_KEY         # Anthropic/Claude
SSH_PRIVATE_KEY_PATH      # clave SSH para el devops-bot

Nunca commitear .env. Plantilla en .env.example.

Preferencias del usuario

Idioma: español en configs/comentarios de dominio, inglés en código Go
Estilo: FP estricto (pure core / impure shell), sin abstracción prematura
Desarrollo: trunk-based, Gitea como remote
Go version: 1.23.5 en /usr/local/go/bin
No usar frameworks de agentes externos — arquitectura propia

Próximas extensiones naturales

Scheduling: cron runner en shell/ para ScheduleCfg
Conversation history: mantener []Message por room en memoria/SQLite
RBAC real: conectar SecurityCfg.Roles al listener
E2EE: habilitar encryption.enabled: true con crypto store de mautrix
MCP: exponer tools del devops-bot como MCP server en el puerto configurado
A2A: agent card HTTP endpoint para comunicación con agentes externos

6.9 KiB Raw Blame History