feat: implementar tipo Robot como runtime ligero para bots command-only

Introduce la separacion Robot vs Agent en el sistema:

- agents/types.go: interfaz Runner comun (Run, Stop, Done, RegisterCommand)
  que tanto Agent como Robot satisfacen
- agents/robot.go: struct Robot — runtime minimo que solo conecta a Matrix
  y despacha comandos. Sin LLM, reglas, memoria, knowledge, skills ni tools.
  Mensajes normales se ignoran silenciosamente
- internal/config/schema.go: campo Type en AgentMeta ("agent"|"robot")
- cmd/launcher: usa Runner interface para manejar ambos tipos uniformemente.
  Si cfg.Agent.Type == "robot" crea NewRobot en vez de New (tanto en
  arranque como en hot-reload)
- agents/_template_robot/config.yaml: plantilla minima (~55 lineas) para
  robots command-only

El Robot soporta built-in commands reducidos (help, ping, status, info,
version) y comandos custom via RegisterCommand. No incluye tools, tool,
clear ni prompts ya que no tiene LLM ni memoria.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-08 23:12:33 +00:00
parent ac5cde3f3e
commit f11f76f39b
6 changed files with 477 additions and 67 deletions
+57
View File
@@ -0,0 +1,57 @@
# ============================================
# ROBOT PLANTILLA (command-only, sin LLM)
# ============================================
# Referencia canonica para robots. NO se lanza (template: true).
# Un robot solo responde a comandos (!xxx). Mensajes normales se ignoran.
# Copiar y adaptar para nuevos robots.
agent:
id: "_template_robot"
name: "Template Robot"
version: "0.0.0"
type: robot # robot = command-only, sin LLM ni reglas
enabled: true
template: true # el launcher ignora este robot
description: "Robot plantilla. No se lanza."
tags: [template, robot]
# ============================================
# PERSONALIDAD (minima para robots)
# ============================================
personality:
prefix: ""
language: es
# ============================================
# MATRIX
# ============================================
matrix:
homeserver: "https://matrix.example.com"
user_id: "@robot:matrix.example.com"
access_token_env: MATRIX_TOKEN_ROBOT
device_id: "DEVICEID"
encryption:
enabled: false
store_path: "./agents/_template_robot/data/crypto/"
pickle_key_env: PICKLE_KEY_ROBOT
trust_mode: tofu
recovery_key_env: ""
rooms:
listen: []
respond: []
admin: []
filters:
command_prefix: "!"
mention_respond: false # robots no responden a menciones (no hay LLM)
dm_respond: false # robots no responden a DMs (no hay LLM)
ignore_bots: true
ignore_users: []
unauthorized_response: silent
min_power_level: 0
threads:
enabled: true
auto_thread: false
+294
View File
@@ -0,0 +1,294 @@
package agents
import (
"context"
"fmt"
"io"
"log/slog"
"os"
"path/filepath"
"strings"
"time"
"maunium.net/go/mautrix/event"
"github.com/enmanuel/agents/internal/config"
"github.com/enmanuel/agents/pkg/command"
"github.com/enmanuel/agents/pkg/decision"
"github.com/enmanuel/agents/shell/matrix"
)
// Robot is a lightweight runtime for command-only bots.
// Unlike Agent, it has no LLM, rules, memory, knowledge, skills, or tools.
// It connects to Matrix and dispatches commands; non-command messages are ignored.
type Robot struct {
cfg *config.AgentConfig
matrix *matrix.Client
logger *slog.Logger
// E2EE crypto store — non-nil when encryption is enabled; closed on shutdown.
cryptoStore io.Closer
// Lifecycle
cancel context.CancelFunc
done chan struct{}
// Commands — handlers keyed by canonical name; aliases maps alias → canonical.
commands map[string]CommandHandler
cmdAliases map[string]string
customSpecs []command.Spec
startTime time.Time
// Personality prefix for replies
prefix string
// Matrix listener
listener *matrix.Listener
}
// NewRobot creates a lightweight command-only bot from its config and logger.
// It initializes only the Matrix client, E2EE (if configured), and built-in commands.
func NewRobot(cfg *config.AgentConfig, logger *slog.Logger) (*Robot, error) {
matrixClient, err := matrix.New(cfg.Matrix)
if err != nil {
return nil, fmt.Errorf("matrix client: %w", err)
}
// E2EE — initialize before the sync loop starts
var cryptoStore io.Closer
if cfg.Matrix.Encryption.Enabled {
storePath := filepath.Join(cfg.Matrix.Encryption.StorePath, "crypto.db")
pickleKey := os.Getenv(cfg.Matrix.Encryption.PickleKeyEnv)
logger.Info("initializing e2ee", "store", storePath)
cryptoStore, err = matrixClient.InitCrypto(context.Background(), storePath, pickleKey, cfg.Agent.ID)
if err != nil {
return nil, fmt.Errorf("e2ee init: %w", err)
}
// Auto-fetch cross-signing private keys from SSSS if recovery key is configured.
if envName := cfg.Matrix.Encryption.RecoveryKeyEnv; envName != "" {
if rk := os.Getenv(envName); rk != "" {
if err := matrixClient.FetchCrossSigningKeys(context.Background(), rk); err != nil {
logger.Warn("failed to fetch cross-signing keys from SSSS (non-fatal)", "err", err)
} else {
logger.Info("cross-signing private keys fetched from SSSS")
}
}
}
// Sign own device with the self-signing key so Element shows it as verified.
if err := matrixClient.SignOwnDevice(context.Background()); err != nil {
logger.Warn("failed to sign own device (non-fatal)", "err", err)
} else {
logger.Info("own device signed with cross-signing key")
}
logger.Info("e2ee ready")
}
r := &Robot{
cfg: cfg,
matrix: matrixClient,
logger: logger,
cryptoStore: cryptoStore,
done: make(chan struct{}),
commands: make(map[string]CommandHandler),
cmdAliases: command.BuiltinNames(),
startTime: time.Now(),
prefix: cfg.Personality.Prefix,
}
// Register built-in commands (robot-appropriate subset).
r.registerBuiltinCommands()
// Matrix event listener
r.listener = matrix.NewListener(matrixClient, cfg.Matrix, r.handleEvent, logger)
return r, nil
}
// registerBuiltinCommands registers command handlers appropriate for a robot.
// Robots support: help, ping, status, info, version.
// They do NOT support: tools, tool, clear, prompts (no LLM, no memory, no tools).
func (r *Robot) registerBuiltinCommands() {
r.commands["help"] = r.cmdHelp
r.commands["ping"] = r.cmdPing
r.commands["status"] = r.cmdStatus
r.commands["info"] = r.cmdInfo
r.commands["version"] = r.cmdVersion
}
// RegisterCommand adds a custom command handler for this robot.
func (r *Robot) RegisterCommand(spec command.Spec, handler CommandHandler) {
r.commands[spec.Name] = handler
r.cmdAliases[spec.Name] = spec.Name
for _, alias := range spec.Aliases {
r.cmdAliases[alias] = spec.Name
}
r.customSpecs = append(r.customSpecs, spec)
r.logger.Info("command_registered", "command", spec.Name, "aliases", spec.Aliases)
}
// Run starts the robot sync loop. Blocks until ctx is cancelled.
func (r *Robot) Run(ctx context.Context) error {
ctx, r.cancel = context.WithCancel(ctx)
defer close(r.done)
if r.cryptoStore != nil {
defer r.cryptoStore.Close()
}
r.logger.Info("robot starting",
"id", r.cfg.Agent.ID,
"name", r.cfg.Agent.Name,
"type", "robot",
)
// Set presence to online
if err := r.matrix.SetPresence(ctx, event.PresenceOnline); err != nil {
r.logger.Warn("failed to set presence online", "err", err)
}
defer func() {
offlineCtx := context.Background()
if err := r.matrix.SetPresence(offlineCtx, event.PresenceOffline); err != nil {
r.logger.Warn("failed to set presence offline", "err", err)
}
}()
return r.listener.Run(ctx)
}
// Stop cancels this robot's individual context, causing Run to return.
func (r *Robot) Stop() {
if r.cancel != nil {
r.cancel()
}
}
// Done returns a channel that is closed when Run has returned.
func (r *Robot) Done() <-chan struct{} {
return r.done
}
// handleEvent is called by the matrix Listener for each filtered incoming event.
// For a robot, only commands are processed; all other messages are silently ignored.
func (r *Robot) handleEvent(ctx context.Context, msgCtx decision.MessageContext, evt *event.Event) {
roomID := evt.RoomID.String()
// Only process commands. Non-command messages are silently ignored.
if msgCtx.Command == "" {
r.logger.Debug("non-command message, ignoring (robot)",
"sender", msgCtx.SenderID,
"room", roomID,
)
return
}
r.logger.Info("command_received",
"command", msgCtx.Command,
"sender", msgCtx.SenderID,
"room", roomID,
"args", msgCtx.Args,
)
// Resolve aliases
cmdName := msgCtx.Command
if canonical, ok := r.cmdAliases[cmdName]; ok {
cmdName = canonical
}
if handler, ok := r.commands[cmdName]; ok {
r.logger.Info("command_executed", "command", cmdName)
reply := handler(ctx, msgCtx)
_ = r.sendReply(ctx, roomID, msgCtx.EventID, msgCtx.ThreadID, reply)
return
}
// Unknown command
r.logger.Info("command_unknown", "command", msgCtx.Command)
_ = r.sendReply(ctx, roomID, msgCtx.EventID, msgCtx.ThreadID,
fmt.Sprintf("Comando desconocido: `!%s`. Usa `!help` para ver comandos disponibles.", msgCtx.Command))
}
// sendReply sends a markdown reply that respects thread context.
func (r *Robot) sendReply(ctx context.Context, roomID, eventID, threadID, markdown string) error {
if threadID != "" {
return r.matrix.SendThreadMarkdown(ctx, roomID, threadID, eventID, markdown)
}
return r.matrix.SendReplyMarkdown(ctx, roomID, eventID, markdown)
}
// ── Built-in command handlers (robot subset) ─────────────────────────────
func (r *Robot) cmdHelp(_ context.Context, _ decision.MessageContext) string {
var b strings.Builder
b.WriteString("**Comandos disponibles:**\n\n")
// Built-in commands appropriate for robots
robotBuiltins := []command.Spec{
{Name: "help", Aliases: []string{"h"}, Description: "Lista comandos disponibles", Usage: "!help"},
{Name: "ping", Description: "Alive check", Usage: "!ping"},
{Name: "status", Description: "Info del robot: uptime", Usage: "!status"},
{Name: "info", Description: "Nombre, version y descripcion", Usage: "!info"},
{Name: "version", Aliases: []string{"v"}, Description: "Version del robot", Usage: "!version"},
}
for _, spec := range robotBuiltins {
writeSpec(&b, spec)
}
// Agent-specific commands (registered via RegisterCommand)
if len(r.customSpecs) > 0 {
b.WriteString("\n**Comandos del robot:**\n\n")
for _, spec := range r.customSpecs {
if spec.Hidden {
continue
}
writeSpec(&b, spec)
}
}
return b.String()
}
func (r *Robot) cmdPing(_ context.Context, _ decision.MessageContext) string {
return fmt.Sprintf("pong — %s", time.Now().Format(time.RFC3339))
}
func (r *Robot) cmdStatus(_ context.Context, _ decision.MessageContext) string {
uptime := time.Since(r.startTime).Truncate(time.Second)
var b strings.Builder
fmt.Fprintf(&b, "**Estado de %s:**\n\n", r.cfg.Agent.Name)
fmt.Fprintf(&b, "- **Tipo:** robot\n")
fmt.Fprintf(&b, "- **Uptime:** %s\n", uptime)
fmt.Fprintf(&b, "- **Comandos custom:** %d\n", len(r.customSpecs))
return b.String()
}
func (r *Robot) cmdInfo(_ context.Context, _ decision.MessageContext) string {
var b strings.Builder
b.WriteString("## Identidad\n\n")
fmt.Fprintf(&b, "- **Nombre:** %s\n", r.cfg.Agent.Name)
fmt.Fprintf(&b, "- **ID:** `%s`\n", r.cfg.Agent.ID)
fmt.Fprintf(&b, "- **Tipo:** robot\n")
if r.cfg.Agent.Version != "" {
fmt.Fprintf(&b, "- **Version:** %s\n", r.cfg.Agent.Version)
}
fmt.Fprintf(&b, "- **Descripcion:** %s\n", r.cfg.Agent.Description)
uptime := time.Since(r.startTime).Round(time.Second)
b.WriteString("\n## Uptime\n\n")
fmt.Fprintf(&b, "- **Activo desde:** %s\n", uptime)
return b.String()
}
func (r *Robot) cmdVersion(_ context.Context, _ decision.MessageContext) string {
v := r.cfg.Agent.Version
if v == "" {
v = "sin version"
}
return fmt.Sprintf("%s %s", r.cfg.Agent.Name, v)
}
+20
View File
@@ -0,0 +1,20 @@
package agents
import (
"context"
"github.com/enmanuel/agents/pkg/command"
)
// Runner is the common interface that both Agent and Robot satisfy.
// The launcher uses this to manage agents and robots uniformly.
type Runner interface {
// Run starts the Matrix sync loop. Blocks until ctx is cancelled.
Run(ctx context.Context) error
// Stop cancels the runner's internal context, causing Run to return.
Stop()
// Done returns a channel closed when Run has returned.
Done() <-chan struct{}
// RegisterCommand adds a custom command handler.
RegisterCommand(spec command.Spec, handler CommandHandler)
}
+45 -29
View File
@@ -158,8 +158,6 @@ func main() {
continue
}
rules := rulesFor(cfg.Agent.ID, logger)
// Per-agent logger → writes to logs/<agent-id>/YYYY-MM-DD.jsonl
agentLogger, agentCleanup, aErr := agentlog.NewAgentLogger(agentlog.LoggerConfig{
BaseDir: logDir,
@@ -172,41 +170,59 @@ func main() {
agentCleanup = func() {}
}
// Resolve centralized ACL for this agent
agentACL := pksecurity.ResolveACL(cfg.Agent.ID, deps.secPolicy)
agentLogger.Debug("resolved acl for agent",
"agent", cfg.Agent.ID,
"acl_empty", agentACL.Empty(),
)
// Branch: robot (command-only, lightweight) vs agent (full runtime).
var runner agents.Runner
a, err := agents.New(cfg, rules, agentACL, agentLogger)
if err != nil {
logger.Error("failed to create agent", "id", cfg.Agent.ID, "err", err)
agentCleanup()
continue
}
if cfg.Agent.Type == "robot" {
robot, rErr := agents.NewRobot(cfg, agentLogger)
if rErr != nil {
logger.Error("failed to create robot", "id", cfg.Agent.ID, "err", rErr)
agentCleanup()
continue
}
runner = robot
agentLogger.Info("created robot", "id", cfg.Agent.ID)
} else {
rules := rulesFor(cfg.Agent.ID, logger)
// Connect agent to bus for orchestration
a.SetBus(agentBus)
// Resolve centralized ACL for this agent
agentACL := pksecurity.ResolveACL(cfg.Agent.ID, deps.secPolicy)
agentLogger.Debug("resolved acl for agent",
"agent", cfg.Agent.ID,
"acl_empty", agentACL.Empty(),
)
// If orchestrator is active, wire interceptor and membership notify
if orch != nil {
a.SetInterceptor(orch.orchestrator.Intercept)
a.SetMembershipNotify(orch.orchestrator.NotifyMembership)
a, cErr := agents.New(cfg, rules, agentACL, agentLogger)
if cErr != nil {
logger.Error("failed to create agent", "id", cfg.Agent.ID, "err", cErr)
agentCleanup()
continue
}
orch.orchestrator.RegisterParticipant(orchestration.ParticipantInfo{
ID: cfg.Agent.ID,
MatrixUserID: cfg.Matrix.UserID,
Description: cfg.Agent.Description,
Capabilities: cfg.Agent.Tags,
})
// Connect agent to bus for orchestration
a.SetBus(agentBus)
// Grab the first available Matrix client for room scanning
scannerOnce.set(a.RawMatrixClient())
// If orchestrator is active, wire interceptor and membership notify
if orch != nil {
a.SetInterceptor(orch.orchestrator.Intercept)
a.SetMembershipNotify(orch.orchestrator.NotifyMembership)
orch.orchestrator.RegisterParticipant(orchestration.ParticipantInfo{
ID: cfg.Agent.ID,
MatrixUserID: cfg.Matrix.UserID,
Description: cfg.Agent.Description,
Capabilities: cfg.Agent.Tags,
})
// Grab the first available Matrix client for room scanning
scannerOnce.set(a.RawMatrixClient())
}
runner = a
}
registry.register(&runningAgent{
agent: a,
runner: runner,
cfg: cfg,
cfgPath: path,
logger: agentLogger,
+60 -38
View File
@@ -17,9 +17,9 @@ import (
agentlog "github.com/enmanuel/agents/shell/logger"
)
// runningAgent holds a live agent and the metadata needed to recreate it.
// runningAgent holds a live runner (Agent or Robot) and the metadata needed to recreate it.
type runningAgent struct {
agent *agents.Agent
runner agents.Runner
cfg *config.AgentConfig
cfgPath string
logger *slog.Logger
@@ -50,21 +50,26 @@ func newAgentRegistry(deps *launchDeps) *agentRegistry {
}
}
// register adds a running agent to the registry and starts its goroutine.
// register adds a running agent/robot to the registry and starts its goroutine.
func (r *agentRegistry) register(ra *runningAgent) {
r.mu.Lock()
r.agents[ra.cfg.Agent.ID] = ra
r.mu.Unlock()
runtimeType := ra.cfg.Agent.Type
if runtimeType == "" {
runtimeType = "agent"
}
go func() {
ra.logger.Info("agent running")
if err := ra.agent.Run(r.deps.parentCtx); err != nil {
ra.logger.Error("agent stopped with error", "err", err)
ra.logger.Info("runner started", "type", runtimeType)
if err := ra.runner.Run(r.deps.parentCtx); err != nil {
ra.logger.Error("runner stopped with error", "err", err, "type", runtimeType)
}
}()
}
// stopAndWait stops a running agent and waits for it to finish.
// stopAndWait stops a running agent/robot and waits for it to finish.
// Caller must NOT hold r.mu.
func (r *agentRegistry) stopAndWait(id string) {
r.mu.Lock()
@@ -74,11 +79,11 @@ func (r *agentRegistry) stopAndWait(id string) {
return
}
ra.agent.Stop()
ra.runner.Stop()
select {
case <-ra.agent.Done():
case <-ra.runner.Done():
case <-time.After(10 * time.Second):
ra.logger.Warn("agent did not stop within 10s, forcing", "id", id)
ra.logger.Warn("runner did not stop within 10s, forcing", "id", id)
}
// Unsubscribe from bus so no stale channel remains.
@@ -133,32 +138,45 @@ func (r *agentRegistry) reload(id string, rulesFor func(string, *slog.Logger) []
newCleanup = func() {}
}
// 5. Create new agent (validates config before discarding the old one).
rules := rulesFor(cfg.Agent.ID, newLogger)
agentACL := pksecurity.ResolveACL(cfg.Agent.ID, r.deps.secPolicy)
newLogger.Debug("resolved acl for agent (reload)", "agent", cfg.Agent.ID, "acl_empty", agentACL.Empty())
newAgent, err := agents.New(cfg, rules, agentACL, newLogger)
if err != nil {
newLogger.Error("reload: failed to create agent", "id", id, "err", err)
newCleanup()
return
}
// 5. Create new runner (validates config before discarding the old one).
var newRunner agents.Runner
// 6. Wire bus and orchestration.
newAgent.SetBus(r.deps.agentBus)
if r.deps.orch != nil {
newAgent.SetInterceptor(r.deps.orch.orchestrator.Intercept)
newAgent.SetMembershipNotify(r.deps.orch.orchestrator.NotifyMembership)
r.deps.orch.orchestrator.RegisterParticipant(orchestration.ParticipantInfo{
ID: cfg.Agent.ID,
MatrixUserID: cfg.Matrix.UserID,
Description: cfg.Agent.Description,
Capabilities: cfg.Agent.Tags,
})
if cfg.Agent.Type == "robot" {
robot, rErr := agents.NewRobot(cfg, newLogger)
if rErr != nil {
newLogger.Error("reload: failed to create robot", "id", id, "err", rErr)
newCleanup()
return
}
newRunner = robot
} else {
rules := rulesFor(cfg.Agent.ID, newLogger)
agentACL := pksecurity.ResolveACL(cfg.Agent.ID, r.deps.secPolicy)
newLogger.Debug("resolved acl for agent (reload)", "agent", cfg.Agent.ID, "acl_empty", agentACL.Empty())
newAgent, aErr := agents.New(cfg, rules, agentACL, newLogger)
if aErr != nil {
newLogger.Error("reload: failed to create agent", "id", id, "err", aErr)
newCleanup()
return
}
// Wire bus and orchestration (only for agents, not robots).
newAgent.SetBus(r.deps.agentBus)
if r.deps.orch != nil {
newAgent.SetInterceptor(r.deps.orch.orchestrator.Intercept)
newAgent.SetMembershipNotify(r.deps.orch.orchestrator.NotifyMembership)
r.deps.orch.orchestrator.RegisterParticipant(orchestration.ParticipantInfo{
ID: cfg.Agent.ID,
MatrixUserID: cfg.Matrix.UserID,
Description: cfg.Agent.Description,
Capabilities: cfg.Agent.Tags,
})
}
newRunner = newAgent
}
newRA := &runningAgent{
agent: newAgent,
runner: newRunner,
cfg: cfg,
cfgPath: cfgPath,
logger: newLogger,
@@ -170,14 +188,18 @@ func (r *agentRegistry) reload(id string, rulesFor func(string, *slog.Logger) []
r.mu.Unlock()
// 7. Start new goroutine.
runtimeType := cfg.Agent.Type
if runtimeType == "" {
runtimeType = "agent"
}
go func() {
newLogger.Info("agent running")
if err := newAgent.Run(r.deps.parentCtx); err != nil {
newLogger.Error("agent stopped with error", "err", err)
newLogger.Info("runner started", "type", runtimeType)
if err := newRunner.Run(r.deps.parentCtx); err != nil {
newLogger.Error("runner stopped with error", "err", err, "type", runtimeType)
}
}()
newLogger.Info("agent_reloaded", "id", id)
newLogger.Info("runner_reloaded", "id", id, "type", runtimeType)
}
// reloadAll reloads every registered agent sequentially.
@@ -194,12 +216,12 @@ func (r *agentRegistry) reloadAll(rulesFor func(string, *slog.Logger) []decision
}
}
// waitAll blocks until all registered agents have stopped.
// waitAll blocks until all registered runners have stopped.
func (r *agentRegistry) waitAll() {
r.mu.Lock()
dones := make([]<-chan struct{}, 0, len(r.agents))
for _, ra := range r.agents {
dones = append(dones, ra.agent.Done())
dones = append(dones, ra.runner.Done())
}
r.mu.Unlock()
+1
View File
@@ -24,6 +24,7 @@ type AgentMeta struct {
ID string `yaml:"id"`
Name string `yaml:"name"`
Version string `yaml:"version"`
Type string `yaml:"type"` // "agent" (default) or "robot" (command-only, no LLM)
Enabled bool `yaml:"enabled"`
Template bool `yaml:"template"` // if true, launcher will skip this agent
Description string `yaml:"description"`