diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 34b58a0..8938db9 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -48,6 +48,10 @@ Todo agente/robot debe pasar por: scaffold → build → register → verify E2E Env var clave: `DEVELOPER_MATRIX_USERS` — el propio bot envia DM de bienvenida a estos usuarios. +## Pipeline de eliminacion de agentes (7 pasos) + +Revierte todo lo que `create-full.sh` genera: validate → stop → deactivate Matrix → remove import → remove env vars → delete files → rebuild. Lo ejecuta `delete-full.sh`. Detalle completo en `.claude/rules/delete_agent.md`. + ## Estructura ``` @@ -79,7 +83,7 @@ cmd/agentctl/ CLI de gestion crons/ catálogo de automatizaciones nombradas (schedule.yaml + prompts) knowledges/ base de conocimiento compartida entre agentes (*.md + SQLite FTS5) dev-scripts/server/ start, stop, restart, ps, logs, dashboard -dev-scripts/agent/ new, register, verify, avatar, remove, list +dev-scripts/agent/ new, register, verify, avatar, remove, delete-full, list dev-scripts/cron/ new, list, apply — gestión de automatizaciones cron dev-scripts/e2e/ install, run — E2E tests con Playwright e2e/ proyecto Node.js con Playwright (tests, fixtures, Element Web) @@ -110,6 +114,7 @@ Guias detalladas en `.claude/rules/index.md`: | `create_agent.md` | Crear nuevo bot/agente/robot | | `create_tool.md` | Añadir tool para function calling | | `create_command.md` | Añadir comando !xxx | +| `delete_agent.md` | Eliminar un bot/agente/robot | | `create_issue.md` | Crear issue en dev/issues/ | | `fix_issue.md` | Implementar un issue existente | diff --git a/.claude/rules/delete_agent.md b/.claude/rules/delete_agent.md new file mode 100644 index 0000000..b47baa9 --- /dev/null +++ b/.claude/rules/delete_agent.md @@ -0,0 +1,137 @@ +# Policy: Eliminar un agente o robot + +Guia ejecutable para Claude. Seguir paso a paso sin desviarse. + +## Pipeline de eliminacion (7 pasos) + +Revierte todo lo que `create-full.sh` genera: + +``` + 1. VALIDATE → verificar que el agente existe + 2. STOP → detener el proceso si esta corriendo + 3. DEACTIVATE → desactivar usuario Matrix (Synapse admin API) + 4. REMOVE IMPORT → eliminar blank import del launcher + 5. REMOVE ENV VARS → eliminar las 4 env vars del .env + 6. DELETE FILES → borrar directorio del agente + runtime files + 7. REBUILD → recompilar el launcher +``` + +## Ruta rapida — script automatizado + +```bash +# Con confirmacion interactiva +./dev-scripts/agent/delete-full.sh + +# Sin confirmacion (automatizacion) +./dev-scripts/agent/delete-full.sh --force + +# Preservar usuario Matrix (soft delete, puede recrearse) +./dev-scripts/agent/delete-full.sh --keep-matrix +``` + +El script ejecuta los 7 pasos en orden. Si algun paso falla de forma no-fatal, continua con los siguientes. + +## Inputs — preguntar al usuario si no los da + +| Input | Requerido | Default | Ejemplo | +|-------|-----------|---------|---------| +| `agent-id` | si | — | `wikipedia-bot` | +| `--force` | no | false | sin confirmacion | +| `--keep-matrix` | no | false | preserva usuario Matrix | + +## Scripts atomicos disponibles + +Cada paso es un script independiente reutilizable: + +| Script | Que hace | +|--------|----------| +| `dev-scripts/agent/deactivate-matrix.sh ` | Desactiva usuario Matrix via Synapse admin API | +| `dev-scripts/agent/remove-launcher-import.sh ` | Elimina blank import de cmd/launcher/main.go | +| `dev-scripts/agent/remove-env-vars.sh ` | Elimina las 4 env vars del .env | + +## Que se elimina + +| Artefacto | Creado por | Eliminado por | +|-----------|-----------|---------------| +| `agents//` (agent.go, config.yaml, prompts/, data/) | `new-agent.sh` | delete-full.sh paso 6 | +| Blank import en `cmd/launcher/main.go` | `new-agent.sh` | `remove-launcher-import.sh` | +| `MATRIX_TOKEN_` en .env | `register.sh` | `remove-env-vars.sh` | +| `MATRIX_PASSWORD_` en .env | `register.sh` | `remove-env-vars.sh` | +| `PICKLE_KEY_` en .env | `register.sh` | `remove-env-vars.sh` | +| `SSSS_RECOVERY_KEY_` en .env | `verify.sh` | `remove-env-vars.sh` | +| Usuario Matrix `@:` | `register.sh` | `deactivate-matrix.sh` | +| Cross-signing keys + crypto store | `verify.sh` | Eliminados con `data/crypto/` | +| Avatar y display name | `auto-avatar` | Se eliminan al desactivar usuario Matrix | +| PID file, log files | Runtime | delete-full.sh paso 6 | + +## Eliminacion manual (sin script) + +Si el script no esta disponible o falla, estos son los pasos manuales: + +### 1. Detener el agente + +```bash +# Buscar PIDs +pgrep -f "launcher.*agents//config.yaml" +# Matar procesos +kill +``` + +### 2. Desactivar usuario Matrix + +```bash +curl -X POST "${MATRIX_HOMESERVER}/_synapse/admin/v1/deactivate/@:${MATRIX_SERVER_NAME}" \ + -H "Authorization: Bearer ${MATRIX_ADMIN_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"erase": false}' +``` + +### 3. Eliminar import del launcher + +Editar `cmd/launcher/main.go` y borrar la linea: +```go +_ "github.com/enmanuel/agents/agents/" +``` + +### 4. Eliminar env vars + +Borrar de `.env`: +``` +MATRIX_TOKEN_=... +MATRIX_PASSWORD_=... +PICKLE_KEY_=... +SSSS_RECOVERY_KEY_=... +``` + +### 5. Eliminar archivos + +```bash +rm -rf agents// +rm -f run/.pid run/.log +rm -rf logs// +``` + +### 6. Recompilar + +```bash +go build -tags goolm ./... +``` + +## Disable vs Delete + +- **`remove.sh`** (disable): marca `enabled: false` en config.yaml. El agente no arranca pero todos los archivos, datos y usuario Matrix se preservan. Reversible. +- **`delete-full.sh`** (delete): elimina todo. Irreversible (excepto con `--keep-matrix`). + +Usar `remove.sh` cuando se quiere desactivar temporalmente. Usar `delete-full.sh` cuando se quiere eliminar permanentemente. + +## Proteccion contra agentes del sistema + +Los directorios con prefijo `_` en `agents/` son del sistema (`_template`, `_template_robot`, `_specials`). El script permite eliminar agentes dentro de `_specials/` (como `father-bot`) pero **no** elimina los templates. + +## Reglas + +- **Siempre confirmar** antes de eliminar (a menos que se use `--force`) +- **Rebuild obligatorio** tras eliminar el import — si no, el launcher no compila +- **No eliminar agentes que no existen** — validar primero +- **Desactivar Matrix es no-fatal** — si falla, los demas pasos continuan +- **Nunca eliminar templates** (`_template`, `_template_robot`) diff --git a/.claude/rules/index.md b/.claude/rules/index.md index 40107bc..19c3d08 100644 --- a/.claude/rules/index.md +++ b/.claude/rules/index.md @@ -10,6 +10,7 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co | **Crear herramienta** | [create_tool.md](create_tool.md) | Al añadir una nueva tool para LLM function calling | | **Crear comando** | [create_command.md](create_command.md) | Al añadir un comando directo (!xxx) a un agente | | **Crear skill** | [create_skill.md](create_skill.md) | Al crear una nueva skill (flujo multi-paso declarativo) | +| **Eliminar agente** | [delete_agent.md](delete_agent.md) | Al eliminar completamente un bot/agente/robot | | **Crear issue** | [create_issue.md](create_issue.md) | Al crear un nuevo issue/feature request en `dev/issues/` | | **Arreglar issue** | [fix_issue.md](fix_issue.md) | Al implementar/arreglar un issue existente de `dev/issues/` | @@ -19,6 +20,7 @@ Guias operativas para LLMs que trabajan en este codebase. Cada regla describe co - **Crear herramienta**: cuando el usuario pida añadir una nueva herramienta/tool al sistema. Incluye el patron Def (puro) + Exec (impuro), registro en runtime.go y habilitacion en config. - **Crear comando**: cuando el usuario pida añadir un comando directo (!xxx) a un agente. Los comandos se resuelven sin pasar por reglas ni LLM. - **Crear skill**: cuando el usuario pida añadir una skill (flujo multi-paso declarativo). Las skills combinan tools, logica condicional y conocimiento de dominio en un SKILL.md con recursos opcionales. +- **Eliminar agente**: cuando el usuario pida eliminar, borrar o destruir un bot/agente/robot. Incluye parar proceso, desactivar usuario Matrix, limpiar launcher, env vars y archivos. Script: `delete-full.sh`. - **Crear issue**: cuando el usuario pida crear un nuevo issue, feature request o task. Usa el template en `.claude/templates/issue.md`. - **Arreglar issue**: cuando el usuario pida implementar, arreglar o trabajar en un issue existente. Incluye crear rama (`/git-branch`), implementar las tareas con tests, cerrar el issue, e integrar a master (`/git-push`). diff --git a/dev/issues/README.md b/dev/issues/README.md index aef3628..d05dea5 100644 --- a/dev/issues/README.md +++ b/dev/issues/README.md @@ -58,3 +58,4 @@ afectados y notas de implementacion. | 45 | DM rooms sin E2EE en notify-developer.sh | [0045-notify-encrypted-rooms.md](completed/0045-notify-encrypted-rooms.md) | completado | | 46 | Progreso en tiempo real para Father Bot | [0046-father-bot-progress.md](completed/0046-father-bot-progress.md) | completado | | 47 | System prompt no se carga para agentes en _specials/ | [0047-fix-system-prompt-path.md](completed/0047-fix-system-prompt-path.md) | completado | +| 48 | Pipeline de eliminacion de agentes y robots | [0048-delete-agent-pipeline.md](completed/0048-delete-agent-pipeline.md) | completado | diff --git a/dev/issues/completed/0048-delete-agent-pipeline.md b/dev/issues/completed/0048-delete-agent-pipeline.md new file mode 100644 index 0000000..fe5fcd7 --- /dev/null +++ b/dev/issues/completed/0048-delete-agent-pipeline.md @@ -0,0 +1,133 @@ +# 0048 — Pipeline de eliminacion de agentes y robots + +## Objetivo + +Crear un pipeline completo de eliminacion que revierta todo lo que `create-full.sh` genera: parar el proceso, desactivar el usuario Matrix, limpiar el launcher, eliminar env vars y borrar archivos. Actualmente `remove.sh` solo marca `enabled: false` en el config — no elimina nada. + +## Contexto + +El pipeline de creacion (`create-full.sh`) genera 7 categorias de artefactos: +1. Directorio `agents//` con agent.go, config.yaml, prompts/, data/ +2. Blank import en `cmd/launcher/main.go` +3. 4 env vars en `.env` (TOKEN, PASSWORD, PICKLE_KEY, SSSS_RECOVERY_KEY) +4. Usuario Matrix registrado en Synapse +5. Cross-signing keys y crypto store E2EE +6. Avatar y display name en Matrix +7. Archivos de runtime (PID, logs) + +Hoy no existe forma de revertir esto automaticamente. El `remove.sh` actual solo deshabilita. + +## Arquitectura + +Archivos afectados: + +- `dev-scripts/agent/delete-full.sh` — **NEW** — script orquestador (7 pasos) +- `dev-scripts/agent/deactivate-matrix.sh` — **NEW** — desactiva usuario Matrix via Synapse admin API +- `dev-scripts/agent/remove-launcher-import.sh` — **NEW** — elimina blank import del launcher +- `dev-scripts/agent/remove-env-vars.sh` — **NEW** — elimina las 4 env vars del agente +- `dev-scripts/agent/remove.sh` — MODIFICAR — agregar referencia a delete-full.sh +- `.claude/rules/delete_agent.md` — **NEW** — regla para el pipeline de eliminacion +- `.claude/rules/index.md` — MODIFICAR — agregar entrada de la nueva regla + +Todo es shell scripting e instrucciones — no toca `pkg/` ni `shell/` (no hay componentes puros/impuros). + +## Tareas + +### Fase 1: Scripts atomicos + +- **1.1** Crear `dev-scripts/agent/deactivate-matrix.sh` — desactivar usuario via `POST /_synapse/admin/v1/deactivate/@:` con MATRIX_ADMIN_TOKEN +- **1.2** Crear `dev-scripts/agent/remove-launcher-import.sh` — eliminar la linea del blank import en cmd/launcher/main.go usando sed/awk +- **1.3** Crear `dev-scripts/agent/remove-env-vars.sh` — eliminar las 4 lineas del .env (MATRIX_TOKEN_, MATRIX_PASSWORD_, PICKLE_KEY_, SSSS_RECOVERY_KEY_) + +### Fase 2: Script orquestador + +- **2.1** Crear `dev-scripts/agent/delete-full.sh` con 7 pasos en orden: + 1. VALIDATE — verificar que el agente existe + 2. STOP — parar el proceso si esta corriendo + 3. DEACTIVATE MATRIX — desactivar usuario en el servidor + 4. REMOVE LAUNCHER IMPORT — quitar blank import + 5. REMOVE ENV VARS — limpiar .env + 6. DELETE FILES — rm -rf agents// + runtime files + 7. REBUILD — go build -tags goolm ./... +- **2.2** Agregar flag `--keep-matrix` para preservar el usuario Matrix (soft delete) +- **2.3** Agregar confirmacion interactiva antes de borrar (con `--force` para skip) + +### Fase 3: Documentacion y regla + +- **3.1** Crear `.claude/rules/delete_agent.md` con instrucciones para LLMs +- **3.2** Actualizar `.claude/rules/index.md` con la nueva regla +- **3.3** Actualizar `dev-scripts/agent/remove.sh` para referenciar delete-full.sh + +### Fase 4: Cleanup + +- **4.1** Verificar que delete-full.sh funciona end-to-end (crear agente temporal, eliminarlo, verificar limpieza) + +## Ejemplo de uso + +```bash +# Eliminacion completa con confirmacion +./dev-scripts/agent/delete-full.sh wikipedia-bot + +# Eliminacion sin confirmacion (scripts automatizados) +./dev-scripts/agent/delete-full.sh wikipedia-bot --force + +# Eliminacion preservando usuario Matrix (puede reutilizarse) +./dev-scripts/agent/delete-full.sh wikipedia-bot --keep-matrix +``` + +Salida esperada: +``` +═══════════════════════════════════════════════════════ + Eliminando agente: wikipedia-bot +═══════════════════════════════════════════════════════ + +→ Paso 1/7 — Validando existencia... +✓ Agente wikipedia-bot encontrado en agents/wikipedia-bot/ + +→ Paso 2/7 — Deteniendo proceso... +✓ Proceso detenido (PID 12345) + +→ Paso 3/7 — Desactivando usuario Matrix... +✓ @wikipedia-bot:matrix-af2f3d.organic-machine.com desactivado + +→ Paso 4/7 — Eliminando import del launcher... +✓ Blank import eliminado de cmd/launcher/main.go + +→ Paso 5/7 — Eliminando variables de entorno... +✓ MATRIX_TOKEN_WIKIPEDIA_BOT eliminado de .env +✓ MATRIX_PASSWORD_WIKIPEDIA_BOT eliminado de .env +✓ PICKLE_KEY_WIKIPEDIA_BOT eliminado de .env +✓ SSSS_RECOVERY_KEY_WIKIPEDIA_BOT eliminado de .env + +→ Paso 6/7 — Eliminando archivos... +✓ agents/wikipedia-bot/ eliminado +✓ run/wikipedia-bot.pid eliminado +✓ logs/wikipedia-bot/ eliminado + +→ Paso 7/7 — Recompilando... +✓ Compilacion exitosa + +═══════════════════════════════════════════════════════ + ✓ Agente wikipedia-bot eliminado completamente +═══════════════════════════════════════════════════════ +``` + +## Decisiones de diseno + +1. **Scripts atomicos + orquestador**: cada paso es un script independiente reutilizable, el orquestador los llama en orden. Misma filosofia que create-full.sh. +2. **Confirmacion por defecto**: borrar es destructivo e irreversible. El flag `--force` es para automatizacion. +3. **`--keep-matrix`**: permite reutilizar el usuario Matrix si se quiere recrear el agente con el mismo ID. +4. **Rebuild obligatorio**: tras eliminar el import, el launcher no compilaria sin rebuild. + +## Prerequisitos + +Ninguno — solo depende de los scripts existentes en `dev-scripts/`. + +## Riesgos + +| Riesgo | Mitigacion | +|--------|-----------| +| Borrar agente equivocado | Confirmacion interactiva + mostrar info del agente antes de borrar | +| Agente con datos importantes en data/ | Warning explicito antes de borrar; --keep-matrix preserva usuario | +| Launcher no compila tras eliminar import | Rebuild es paso obligatorio; si falla, error claro | +| Usuario Matrix no se puede desactivar (admin token invalido) | Error no-fatal con warning; los demas pasos continuan |