diff --git a/dev/issues/0033-bot-commands-no-prefix.md b/dev/issues/0033-bot-commands-no-prefix.md new file mode 100644 index 0000000..cb05670 --- /dev/null +++ b/dev/issues/0033-bot-commands-no-prefix.md @@ -0,0 +1,117 @@ +# 0033 — Comandos de robots sin prefijo ! + +## Objetivo + +Permitir que los robots respondan a comandos sin necesitar el prefijo `!`. Actualmente los bots requieren `!help`, `!ping`, etc. El objetivo es que un robot pueda configurar sus comandos para que funcionen tambien sin prefijo: `help`, `ping`, `status`. + +Esto es especialmente util para robots interactivos donde el prefijo `!` es friccion innecesaria — los robots solo responden comandos, asi que todo mensaje es potencialmente un comando. + +## Contexto + +- Los robots (`agent.type: robot`) solo responden a comandos, no tienen LLM +- El sistema de comandos actual en `agents/handler.go` parsea el prefijo `!` en `shell/matrix/listener.go` +- El campo `matrix.filters.command_prefix` ya existe en el config pero esta hardcoded a `!` +- Los agentes con LLM necesitan el prefijo para distinguir comandos de mensajes normales +- Los robots NO necesitan esta distincion — todo mensaje a un robot es un comando o se ignora + +## Arquitectura + +``` +shell/matrix/listener.go MOD — parsear comandos con o sin prefijo segun config +pkg/decision/types.go MOD — asegurar que Command se popula sin prefijo +agents/handler.go MOD — routing de comandos: si robot y sin prefijo, intentar match +agents/robot.go MOD — handleEvent acepta comandos sin prefijo +internal/config/schema.go MOD — documentar command_prefix: "" como "sin prefijo" +agents/_template_robot/config.yaml MOD — ejemplo con command_prefix: "" +``` + +### Patron pure core / impure shell + +- `pkg/decision/types.go` — puro: solo tipos, MessageContext ya tiene campo Command +- `shell/matrix/listener.go` — impuro: parseo del evento Matrix, detectar comando con/sin prefijo +- `agents/robot.go` + `agents/handler.go` — composicion: routing de comandos + +### Comportamiento esperado + +| Config | Mensaje | Resultado | +|--------|---------|-----------| +| `command_prefix: "!"` | `!help` | Ejecuta help | +| `command_prefix: "!"` | `help` | Ignora (sin prefijo) | +| `command_prefix: ""` | `help` | Ejecuta help | +| `command_prefix: ""` | `!help` | Ejecuta help (retrocompatible) | +| `command_prefix: ""` | `hola mundo` | "Comando desconocido: hola" | + +Cuando `command_prefix` es vacio: +- El primer token del mensaje se trata como nombre de comando +- Si el primer token empieza con `!`, se le quita el prefijo y se busca igual +- Si no hay match, responder "Comando desconocido" (comportamiento actual) + +## Tareas + +### Fase 1: Parser de comandos flexible + +- [ ] **1.1** Modificar `shell/matrix/listener.go` — al parsear el evento, si `command_prefix` es vacio, tratar el primer token como comando (sin requerir `!`). Si tiene prefijo `!`, quitarlo igualmente para retrocompatibilidad. +- [ ] **1.2** Asegurar que `MessageContext.Command` se popula correctamente en ambos modos. +- [ ] **1.3** NO cambiar el comportamiento para agentes con LLM (`type: agent`) — solo afecta cuando `command_prefix: ""`. + +### Fase 2: Routing en robot + +- [ ] **2.1** Verificar que `agents/robot.go` ya maneja correctamente el campo `Command` de MessageContext — no deberia necesitar cambios si el parser hace bien su trabajo. +- [ ] **2.2** Si es necesario, ajustar `handleEvent` en robot para aceptar comandos sin prefijo. + +### Fase 3: Config y template + +- [ ] **3.1** Documentar en `internal/config/schema.go` que `command_prefix: ""` significa "sin prefijo". +- [ ] **3.2** Actualizar `agents/_template_robot/config.yaml` para mostrar `command_prefix: ""` como opcion comentada. + +### Fase 4: Tests + +- [ ] **4.1** Tests unitarios para el parser de comandos: con prefijo `!`, sin prefijo, prefijo vacio en config. +- [ ] **4.2** Tests para robot handleEvent con comandos sin prefijo. +- [ ] **4.3** Tests de regresion: verificar que agentes con LLM siguen funcionando igual con `command_prefix: "!"`. +- [ ] **4.4** `go build -tags goolm ./...` y `go test -tags goolm ./...` + +### Fase 5: Cleanup + +- [ ] **5.1** Actualizar `.claude/rules/create_command.md` mencionando la opcion sin prefijo para robots. + +## Ejemplo de uso + +```yaml +# config.yaml del robot +agent: + type: robot +matrix: + filters: + command_prefix: "" # sin prefijo — todo mensaje es potencial comando +``` + +``` +Usuario: help +Bot: Comandos disponibles: help, ping, status, info, version + +Usuario: ping +Bot: pong (latencia: 23ms) + +Usuario: !help # retrocompatible +Bot: Comandos disponibles: help, ping, status, info, version + +Usuario: hola mundo +Bot: Comando desconocido: hola. Usa 'help' para ver los comandos disponibles. +``` + +## Decisiones de diseno + +- **Solo para robots**: los agentes con LLM siguen necesitando `!` para distinguir comandos de mensajes naturales. Cambiar esto para agentes romperia el flujo de reglas → LLM. +- **Retrocompatibilidad con `!`**: aunque el prefijo este vacio, seguir aceptando `!` para no confundir a usuarios acostumbrados. +- **Comando desconocido explicito**: cuando todo es un potencial comando, responder "desconocido" con sugerencia de `help` es mejor UX que silencio. +- **Cambio en listener, no en robot**: el parseo debe ocurrir en la capa impura (listener), no en la logica de routing. + +## Prerequisitos + +- Issue 0030 completado (Robot vs Agent separacion) ✓ + +## Riesgos + +- **Falsos positivos**: mensajes que no son comandos se interpretaran como comandos desconocidos. Mitigacion: esto es intencional para robots (solo reciben comandos). +- **Retrocompatibilidad**: agentes existentes con `command_prefix: "!"` no deben cambiar. Mitigacion: el cambio solo aplica cuando prefix es vacio. diff --git a/dev/issues/0034-e2e-create-bot-skill.md b/dev/issues/0034-e2e-create-bot-skill.md new file mode 100644 index 0000000..b4e7e5e --- /dev/null +++ b/dev/issues/0034-e2e-create-bot-skill.md @@ -0,0 +1,142 @@ +# 0034 — E2E: verificar skill /create-bot con robot de prueba + +## Objetivo + +Crear un robot de prueba usando la skill `/create-bot` y escribir tests E2E con Playwright que verifiquen que el robot se creo correctamente y responde a comandos en Matrix. Esto valida el pipeline completo: scaffold → build → register → verify → comandos funcionales. + +## Contexto + +- La skill `/create-bot` existe en `.claude/skills/create-bot/` y ejecuta `create-full.sh` + conversion a robot +- Ya hay E2E tests para agentes (`assistant-bot`, `asistente-2`) en `e2e/tests/` +- No hay tests que validen robots ni el pipeline de creacion de bots +- Los robots solo responden a comandos (`!xxx`), no tienen LLM — los assertions pueden ser estrictos (deterministicos) +- El issue 0032 hace lo mismo pero para agentes con LLM — este es el equivalente para robots + +## Arquitectura + +``` +agents/test-bot/ NEW — robot creado por /create-bot +agents/test-bot/agent.go NEW — Rules() retorna nil +agents/test-bot/config.yaml NEW — config tipo robot +agents/test-bot/commands.go NEW — comandos custom de prueba +cmd/launcher/main.go MOD — blank import + registro de comandos custom +e2e/tests/test-bot.spec.ts NEW — tests E2E del robot +e2e/tests/create-bot-pipeline.spec.ts NEW — tests del pipeline de creacion +``` + +### Patron pure core / impure shell + +- `pkg/` — sin cambios +- `shell/` — sin cambios +- `agents/test-bot/` — composicion: agent.go puro (nil rules) + config YAML + commands.go +- `e2e/` — tests Playwright (fuera del modulo Go) + +## Tareas + +### Fase 1: Crear robot de prueba con /create-bot + +- [ ] **1.1** Ejecutar `/create-bot test-bot "Test Bot"` con los siguientes inputs: + - `bot-id`: `test-bot` + - `display-name`: `"Test Bot"` + - `description`: `"Robot de prueba para validar el pipeline de creacion de bots"` + - Comandos custom: `!echo ` (repite el texto), `!dice` (numero aleatorio 1-6) +- [ ] **1.2** Verificar que `create-full.sh` completa las 4 etapas sin errores +- [ ] **1.3** Verificar que el config tiene `agent.type: robot` +- [ ] **1.4** Verificar que no existe `agents/test-bot/prompts/` (robots no tienen system prompt) +- [ ] **1.5** Implementar los comandos custom en `agents/test-bot/commands.go`: + - `!echo `: devuelve el texto tal cual (util para assertions exactas) + - `!dice`: devuelve un numero aleatorio entre 1 y 6 +- [ ] **1.6** Registrar comandos en `cmd/launcher/main.go` +- [ ] **1.7** Verificar compilacion: `go build -tags goolm ./...` +- [ ] **1.8** Arrancar y verificar que el robot responde: `./dev-scripts/server/start.sh` + +### Fase 2: E2E tests del robot + +- [ ] **2.1** Crear `e2e/tests/test-bot.spec.ts` con los siguientes tests: + - **!help funciona**: enviar `!help` → verificar que lista comandos built-in + custom (echo, dice) + - **!ping funciona**: enviar `!ping` → verificar respuesta (assertion estricta) + - **!echo funciona**: enviar `!echo hello world` → verificar que responde "hello world" (assertion estricta) + - **!dice funciona**: enviar `!dice` → verificar que responde un numero entre 1 y 6 + - **Comando desconocido**: enviar `!unknown` → verificar respuesta de error + - **Mensaje normal ignorado**: enviar "hola" sin prefijo → verificar que NO responde (silencio) + - **Sin errores de descifrado**: verificar `assertNoDecryptionErrors` en cada test +- [ ] **2.2** Seguir el patron de los tests existentes para fixtures, imports y estructura +- [ ] **2.3** Ejecutar los tests: `./dev-scripts/e2e/run.sh test-bot` + +### Fase 3: E2E test del pipeline de creacion (validacion estructural) + +- [ ] **3.1** Crear `e2e/tests/create-bot-pipeline.spec.ts` que valide la estructura: + - Verificar que `agents/test-bot/agent.go` existe y `Rules()` retorna nil + - Verificar que `agents/test-bot/config.yaml` tiene `agent.type: robot` + - Verificar que NO existe `agents/test-bot/prompts/system.md` + - Verificar que `cmd/launcher/main.go` tiene el blank import + - Verificar que `agents/test-bot/commands.go` existe +- [ ] **3.2** Estos tests pueden ser scripts bash o tests Node.js — no requieren Playwright + +### Fase 4: Tests + +- [ ] **4.1** Ejecutar suite E2E completa: `./dev-scripts/e2e/run.sh` +- [ ] **4.2** Verificar que tests existentes siguen pasando (no regresion) +- [ ] **4.3** Verificar build completo: `go build -tags goolm ./...` y `go test -tags goolm ./...` + +### Fase 5: Cleanup y docs + +- [ ] **5.1** Actualizar `CLAUDE.md` tabla de agentes con `test-bot` (tipo robot) +- [ ] **5.2** Documentar en `e2e/README.md` el nuevo spec y la estrategia de testing para robots + +## Ejemplo de uso + +``` +# 1. Crear el robot con la skill +> /create-bot test-bot "Test Bot" +(skill ejecuta create-full.sh, convierte a robot, crea comandos) + +# 2. Arrancar y probar manualmente +> ./dev-scripts/server/start.sh +> (en Matrix) !help +< Comandos disponibles: +< !help — Muestra esta ayuda +< !ping — Verifica conectividad +< !echo — Repite el texto +< !dice — Lanza un dado (1-6) + +> !echo hola mundo +< hola mundo + +> !dice +< 4 + +> hola # mensaje sin prefijo +> (sin respuesta) # robot lo ignora + +# 3. Correr E2E +> ./dev-scripts/e2e/run.sh test-bot + ✓ !help lista todos los comandos (2s) + ✓ !ping responde (2s) + ✓ !echo repite el texto (2s) + ✓ !dice devuelve numero valido (2s) + ✓ comando desconocido muestra error (2s) + ✓ mensaje sin prefijo es ignorado (5s) + 6 passed +``` + +## Decisiones de diseno + +- **Assertions estrictas**: a diferencia de los tests de agentes con LLM (assertions flexibles por no-determinismo), los tests de robots son 100% deterministicos. Cada comando tiene una respuesta predecible → assertions exactas. +- **`!echo` como comando de prueba**: permite enviar cualquier texto y verificar que lo devuelve exactamente — ideal para debugging y assertions. +- **`!dice` como comando con variabilidad**: permite testear que el bot responde algo valido dentro de un rango, sin ser deterministico exacto. +- **Test de silencio**: verificar que un mensaje normal NO genera respuesta es critico para robots — asegura que el robot no intenta procesar mensajes como un agente LLM. +- **Robot permanente**: el robot de prueba se queda en el repo como referencia de creacion y target permanente para E2E. + +## Prerequisitos + +- Issue 0030 completado (Robot vs Agent separacion) ✓ +- Skill `/create-bot` funcionando (en `.claude/skills/create-bot/`) +- E2E infrastructure funcionando (issue 0022 completado) ✓ +- Variables de entorno del homeserver configuradas + +## Riesgos + +- **create-full.sh no soporta robots nativamente**: el script crea un agente por defecto, la skill lo convierte despues. Riesgo bajo — la conversion es solo editar config y borrar prompts. +- **Timing en test de silencio**: verificar que el bot NO responde requiere esperar un timeout. Mitigacion: timeout corto (5s) ya que los robots responden en <1s. +- **E2EE verification**: el robot necesita cross-signing funcional. Mitigacion: `verify.sh` ya maneja esto. diff --git a/dev/issues/README.md b/dev/issues/README.md index 56996f5..6e7b3f5 100644 --- a/dev/issues/README.md +++ b/dev/issues/README.md @@ -43,3 +43,5 @@ afectados y notas de implementacion. | 30 | Separacion Robot vs Agente | [0030-robot-vs-agent.md](completed/0030-robot-vs-agent.md) | completado | | 31 | Expandir file tools (write, list, append, delete) | [0031-expand-file-tools.md](completed/0031-expand-file-tools.md) | completado | | 32 | E2E: verificar skill /create-agent | [0032-e2e-create-agent-skill.md](0032-e2e-create-agent-skill.md) | pendiente | +| 33 | Comandos de robots sin prefijo ! | [0033-bot-commands-no-prefix.md](0033-bot-commands-no-prefix.md) | pendiente | +| 34 | E2E: verificar skill /create-bot | [0034-e2e-create-bot-skill.md](0034-e2e-create-bot-skill.md) | pendiente |