diff --git a/dev/issues/0044-formalize-agent-creation-pipeline.md b/dev/issues/0044-formalize-agent-creation-pipeline.md new file mode 100644 index 0000000..3003a63 --- /dev/null +++ b/dev/issues/0044-formalize-agent-creation-pipeline.md @@ -0,0 +1,175 @@ +# 0044 — Formalizar pipeline de creacion de agentes + +**Estado:** pendiente + +## Objetivo + +Definir, documentar y garantizar que el pipeline de creacion de agentes/robots sea completo, robusto y consistente — tanto cuando se ejecuta manualmente via `dev-scripts/` como cuando father-bot lo ejecuta via Matrix. El pipeline debe culminar siempre con el **propio bot recien creado enviando un mensaje de bienvenida a los desarrolladores**. + +## Contexto + +- `dev-scripts/agent/create-full.sh` ya ejecuta un pipeline de 6-7 pasos: scaffold → build → register → verify E2EE → [convert robot] → auto-avatar → notify-developer. +- `notify-developer.sh` ya usa el token del bot recien creado para enviar DMs a los devs listados en `DEVELOPER_MATRIX_USERS`. +- Father-bot (issue 0037) puede crear agentes via Matrix, ejecutando `create-full.sh` internamente. +- **Problema actual**: no hay garantia de que todos los pasos se ejecuten siempre ni de que el bot quede operativo antes de hablar a los devs. Falta un "health check" final. + +## Pipeline formalizado + +Estos son los pasos obligatorios, en orden estricto. Todo agente o robot creado debe pasar por TODOS: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ PIPELINE DE CREACION DE AGENTES/ROBOTS │ +│ │ +│ 1. SCAFFOLD → crear archivos base desde template │ +│ 2. BUILD → go build -tags goolm ./... │ +│ 3. REGISTER → crear usuario Matrix + token │ +│ 4. VERIFY E2EE → cross-signing + recovery key │ +│ 5. CONVERT (robot) → eliminar LLM/prompts si type=robot │ +│ 6. AUTO-AVATAR → generar y aplicar foto de perfil │ +│ 7. DISPLAY NAME → configurar nombre visible en Matrix │ +│ 8. PERSONALIZE → config.yaml, agent.go, system prompt │ +│ 9. REBUILD → recompilar tras personalizacion │ +│ 10. START/RESTART → arrancar el launcher con el bot │ +│ 11. HEALTH CHECK → verificar que el bot esta activo │ +│ 12. SELF-INTRODUCE → el bot envia bienvenida a los devs │ +│ │ +│ Env var requerida: DEVELOPER_MATRIX_USERS │ +│ Si no esta definida, paso 12 se salta con warning. │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Detalle de cada paso + +#### 1. SCAFFOLD +- Ejecutar `new-agent.sh "Display Name"` o copiar desde template +- Crea: `agents//agent.go`, `config.yaml`, `prompts/system.md`, `data/` +- Registra blank import en `cmd/launcher/main.go` + +#### 2. BUILD +- `go build -tags goolm ./...` +- Si falla: **STOP**, reportar error + +#### 3. REGISTER +- `register.sh "Display Name"` +- Crea usuario Matrix, genera token, password, pickle key +- Anade env vars a `.env` + +#### 4. VERIFY E2EE +- `verify.sh ` +- Genera cross-signing keys, firma device +- Anade recovery key a `.env` + +#### 5. CONVERT (solo robots) +- `convert-to-robot.sh ` +- Elimina config LLM, prompts, ajusta type a robot + +#### 6. AUTO-AVATAR +- `agentctl auto-avatar ` +- Genera avatar automatico (DiceBear/RoboHash/Multiavatar) +- Lo sube como foto de perfil del usuario Matrix + +#### 7. DISPLAY NAME (NUEVO) +- Configurar el display name en Matrix via API: + ``` + PUT /_matrix/client/v3/profile/@:/displayname + {"displayname": ""} + ``` +- Actualmente no se hace de forma consistente — el display name queda como el MXID + +#### 8. PERSONALIZE +- Editar `config.yaml`: descripcion, LLM, tools, personalidad +- Editar `agent.go`: reglas especificas (si aplica) +- Escribir `prompts/system.md`: identidad, capacidades, seguridad +- **Incluir siempre seccion de seguridad anti-injection** + +#### 9. REBUILD +- `go build -tags goolm ./...` tras personalizacion +- Si falla: corregir y reintentar antes de continuar + +#### 10. START/RESTART +- `./dev-scripts/server/restart.sh` o arrancar el launcher +- Esperar ~5 segundos para que el bot sincronice + +#### 11. HEALTH CHECK (NUEVO) +- Verificar en logs que el bot arranco correctamente: + - `"e2ee ready"` o `"starting matrix sync"` + - `"runner started"` o `"agent running"` +- Si no aparecen en 30s: **reportar error**, no continuar al paso 12 + +#### 12. SELF-INTRODUCE (MEJORAR) +- El **propio bot recien creado** envia DM a cada developer en `DEVELOPER_MATRIX_USERS` +- Mensaje de bienvenida con: + - Nombre y tipo (agent/robot) + - Descripcion breve de capacidades + - Comandos disponibles (si es robot) + - Instrucciones de uso ("Invitame a un room" o "Escribeme por DM") +- Usa `notify-developer.sh` (que ya usa el token del bot) +- Si `DEVELOPER_MATRIX_USERS` no esta definido: warning, no error + +## Tareas + +### Fase 1 — Display name automatico + +- [ ] **1.1** Agregar paso de display name en `create-full.sh` (POST al API de Matrix con el token del bot) +- [ ] **1.2** Verificar que father-bot tambien ejecute este paso al crear agentes +- [ ] **1.3** Retroactivamente configurar display name para agentes existentes que no lo tengan + +### Fase 2 — Health check post-arranque + +- [ ] **2.1** Crear `dev-scripts/agent/health-check.sh ` que revise logs del agente buscando mensajes de arranque exitoso +- [ ] **2.2** Integrarlo en `create-full.sh` tras el restart (o tras notify, si el restart lo hace el usuario) +- [ ] **2.3** Father-bot debe ejecutar health check antes de confirmar al usuario + +### Fase 3 — Mejorar mensaje de bienvenida + +- [ ] **3.1** Enriquecer el mensaje de `notify-developer.sh`: + - Incluir descripcion del agente (leer de config.yaml) + - Incluir lista de tools habilitadas (si es agent con tools) + - Formato Markdown con estructura clara +- [ ] **3.2** Garantizar que el mensaje se envia DESPUES de que el bot este activo (health check ok) +- [ ] **3.3** Si el DM falla (el bot no esta synceando), reintentar 3 veces con backoff + +### Fase 4 — Consistencia entre manual y father-bot + +- [ ] **4.1** Documentar el pipeline completo (12 pasos) en `.claude/rules/create_agent.md` +- [ ] **4.2** Actualizar system prompt de father-bot para que ejecute TODOS los pasos, incluyendo: + - Display name (paso 7) + - Rebuild tras personalizacion (paso 9) + - Health check (paso 11) + - Self-introduce (paso 12) +- [ ] **4.3** Actualizar skill `/create-agent` y `/create-bot` para que sigan el mismo pipeline +- [ ] **4.4** Test E2E que verifique que el bot creado envia bienvenida a los devs + +### Fase 5 — Cleanup y docs + +- [ ] **5.1** Actualizar `CLAUDE.md` con el pipeline formalizado +- [ ] **5.2** Actualizar `dev-scripts/agent/README.md` con diagrama del pipeline +- [ ] **5.3** Agregar `DEVELOPER_MATRIX_USERS` a `.env.example` con documentacion + +## Decisiones de diseno + +1. **El bot mismo habla a los devs**: no un script externo ni otro bot. El `notify-developer.sh` ya usa el token del bot recien creado, asi que el DM viene del propio bot. Esto es intencional — los devs ven el mensaje directamente del bot nuevo. + +2. **Health check antes de self-introduce**: si el bot no arranco, no puede enviar DMs. El health check evita intentos fallidos y da un diagnostico util. + +3. **Display name obligatorio**: sin display name, el bot aparece como `@id:server` en Element, confundiendo a los usuarios. Debe configurarse siempre. + +4. **Pipeline identico para manual y father-bot**: no debe haber diferencia en el resultado final. Un agente creado por `create-full.sh` y uno creado por father-bot deben pasar por los mismos 12 pasos. + +5. **DEVELOPER_MATRIX_USERS como gate**: si no esta configurada, el paso 12 se salta con warning. Nunca bloquea la creacion. + +## Prerequisitos + +- Father-bot funcional (issue 0037) — completado +- Auto-avatar (issue 0042) — completado +- Scripts de creacion existentes — ya implementados + +## Riesgos + +| Riesgo | Mitigacion | +|--------|------------| +| Bot no arranca y no puede enviar bienvenida | Health check detecta el fallo antes de intentar | +| Display name no se actualiza (API falla) | Warning, no bloqueante; se puede corregir despues | +| Father-bot no ejecuta todos los pasos | System prompt actualizado con los 12 pasos; E2E test lo verifica | +| DEVELOPER_MATRIX_USERS no configurado | Warning explicito; documentado en .env.example | diff --git a/dev/issues/README.md b/dev/issues/README.md index 1a5e4f9..9189daf 100644 --- a/dev/issues/README.md +++ b/dev/issues/README.md @@ -54,3 +54,4 @@ afectados y notas de implementacion. | 41 | Videollamadas con agentes via LiveKit | [0041-livekit-videocall.md](0041-livekit-videocall.md) | pendiente | | 42 | Auto-avatar con proveedores gratuitos | [0042-auto-avatar-providers.md](completed/0042-auto-avatar-providers.md) | completado | | 43 | Guardrails de seguridad para Father Bot | [0043-father-bot-security-guardrails.md](0043-father-bot-security-guardrails.md) | pendiente | +| 44 | Formalizar pipeline de creacion de agentes | [0044-formalize-agent-creation-pipeline.md](0044-formalize-agent-creation-pipeline.md) | pendiente |