dataforge/agents_and_robots
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: regla delete_agent.md y cierre de issue 0048

Browse Source 
Nueva regla .claude/rules/delete_agent.md con instrucciones completas
para eliminar agentes (manual y automatizado). Actualiza index.md,
CLAUDE.md y cierra issue 0048.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Enmanuel
2026-04-10 23:44:42 +00:00
parent 50013b0ecb
commit 98da4f7521
5 changed files with 279 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/CLAUDE.md
+6 -1
View File
@@ -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 |
.claude/rules/delete_agent.md
+137
View File
@@ -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 <agent-id>
# Sin confirmacion (automatizacion)
./dev-scripts/agent/delete-full.sh <agent-id> --force
# Preservar usuario Matrix (soft delete, puede recrearse)
./dev-scripts/agent/delete-full.sh <agent-id> --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 <id>` | Desactiva usuario Matrix via Synapse admin API |
| `dev-scripts/agent/remove-launcher-import.sh <id>` | Elimina blank import de cmd/launcher/main.go |
| `dev-scripts/agent/remove-env-vars.sh <id>` | Elimina las 4 env vars del .env |
## Que se elimina
| Artefacto | Creado por | Eliminado por |
|-----------|-----------|---------------|
| `agents/<id>/` (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_<NORM>` en .env | `register.sh` | `remove-env-vars.sh` |
| `MATRIX_PASSWORD_<NORM>` en .env | `register.sh` | `remove-env-vars.sh` |
| `PICKLE_KEY_<NORM>` en .env | `register.sh` | `remove-env-vars.sh` |
| `SSSS_RECOVERY_KEY_<NORM>` en .env | `verify.sh` | `remove-env-vars.sh` |
| Usuario Matrix `@<id>:<server>` | `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/<id>/config.yaml"
# Matar procesos
kill <PID>
```
### 2. Desactivar usuario Matrix
```bash
curl -X POST "${MATRIX_HOMESERVER}/_synapse/admin/v1/deactivate/@<id>:${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/<id>"
```
### 4. Eliminar env vars
Borrar de `.env`:
```
MATRIX_TOKEN_<NORM>=...
MATRIX_PASSWORD_<NORM>=...
PICKLE_KEY_<NORM>=...
SSSS_RECOVERY_KEY_<NORM>=...
```
### 5. Eliminar archivos
```bash
rm -rf agents/<id>/
rm -f run/<id>.pid run/<id>.log
rm -rf logs/<id>/
```
### 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`)
.claude/rules/index.md
+2
View File
@@ -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`).
dev/issues/README.md
+1
View File
@@ -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 |
dev/issues/completed/0048-delete-agent-pipeline.md
+133
View File
@@ -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/<id>/` 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/@<id>:<server>` 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/<id>/ + 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 |