egutierrez
98da4f7521
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>
134 lines
6.1 KiB
Markdown
134 lines
6.1 KiB
Markdown
# 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 |
|