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

merge: issue/0048-delete-agent-pipeline — Pipeline de eliminacion de agentes y robots

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Enmanuel
2026-04-10 23:45:04 +00:00
parent 6107aefb52 98da4f7521
commit 53a22538d8
10 changed files with 597 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-scripts/agent/deactivate-matrix.sh
Executable
+47
View File
@@ -0,0 +1,47 @@
#!/usr/bin/env bash
# deactivate-matrix.sh — desactiva un usuario Matrix via Synapse admin API
#
# Uso:
# ./dev-scripts/agent/deactivate-matrix.sh <agent-id>
#
# Desactiva la cuenta del bot en el homeserver. La accion es irreversible
# desde la API (el usuario no podra volver a loguearse).
#
# Requiere en .env:
# MATRIX_ADMIN_TOKEN, MATRIX_HOMESERVER, MATRIX_SERVER_NAME
source "$(dirname "$0")/../_common.sh"
load_env
need_arg "${1:-}"
ID="$1"
NORM="$(normalize_id "$ID")"
[[ -n "${MATRIX_ADMIN_TOKEN:-}" ]] || fail "MATRIX_ADMIN_TOKEN no esta en .env"
[[ -n "${MATRIX_HOMESERVER:-}" ]] || fail "MATRIX_HOMESERVER no esta en .env"
[[ -n "${MATRIX_SERVER_NAME:-}" ]] || fail "MATRIX_SERVER_NAME no esta en .env"
USER_ID="@${ID}:${MATRIX_SERVER_NAME}"
info "Desactivando $USER_ID en $MATRIX_HOMESERVER..."
# Synapse admin API: deactivate user
# https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#deactivate-account
HTTP_CODE=$(curl -s -o /tmp/_deactivate_response.json -w '%{http_code}' \
-X POST \
"${MATRIX_HOMESERVER}/_synapse/admin/v1/deactivate/${USER_ID}" \
-H "Authorization: Bearer ${MATRIX_ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"erase": false}')
if [[ "$HTTP_CODE" == "200" ]]; then
ok "$USER_ID desactivado exitosamente"
elif [[ "$HTTP_CODE" == "404" ]]; then
warn "Usuario $USER_ID no encontrado en el servidor (ya eliminado?)"
else
BODY=$(cat /tmp/_deactivate_response.json 2>/dev/null || echo "(sin respuesta)")
fail "Error al desactivar $USER_ID — HTTP $HTTP_CODE: $BODY"
fi
rm -f /tmp/_deactivate_response.json
dev-scripts/agent/delete-full.sh
Executable
+207
View File
@@ -0,0 +1,207 @@
#!/usr/bin/env bash
# delete-full.sh — pipeline completo para eliminar un agente o robot
#
# 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
#
# Uso:
# ./dev-scripts/agent/delete-full.sh <agent-id> # con confirmacion
# ./dev-scripts/agent/delete-full.sh <agent-id> --force # sin confirmacion
# ./dev-scripts/agent/delete-full.sh <agent-id> --keep-matrix # preserva usuario Matrix
# ./dev-scripts/agent/delete-full.sh <agent-id> --force --keep-matrix
#
# Requiere en .env:
# MATRIX_ADMIN_TOKEN, MATRIX_HOMESERVER, MATRIX_SERVER_NAME (para desactivar Matrix)
source "$(dirname "$0")/../_common.sh"
load_env
need_arg "${1:-}"
ID="$1"
NORM="$(normalize_id "$ID")"
SCRIPT_DIR="$(dirname "$0")"
FORCE=false
KEEP_MATRIX=false
# Parse flags
shift
while [[ $# -gt 0 ]]; do
case "$1" in
--force|-f)
FORCE=true
shift
;;
--keep-matrix)
KEEP_MATRIX=true
shift
;;
*)
warn "Flag desconocido: $1"
shift
;;
esac
done
TOTAL_STEPS=7
echo ""
echo -e "${RED}═══════════════════════════════════════════════════════${RST}"
echo -e "${RED} Eliminando agente: ${GRN}$ID${RST}"
echo -e "${RED}═══════════════════════════════════════════════════════${RST}"
echo ""
# ── Paso 1: Validar existencia ──────────────────────────────────────────────
info "Paso 1/${TOTAL_STEPS} — Validando existencia..."
AGENT_DIR=""
CFG_PATH=""
# Buscar en agents/ y agents/_specials/
if [[ -d "agents/$ID" ]]; then
AGENT_DIR="agents/$ID"
CFG_PATH="agents/$ID/config.yaml"
elif [[ -d "agents/_specials/$ID" ]]; then
AGENT_DIR="agents/_specials/$ID"
CFG_PATH="agents/_specials/$ID/config.yaml"
else
fail "Agente '$ID' no encontrado en agents/ ni agents/_specials/"
fi
# Leer info del agente para mostrar al usuario
AGENT_DESC=""
AGENT_TYPE="agent"
if [[ -f "$CFG_PATH" ]]; then
AGENT_DESC=$(grep -m1 'description:' "$CFG_PATH" | cut -d'"' -f2)
TYPE_LINE=$(grep -m1 'type:' "$CFG_PATH" | awk '{print $2}')
[[ -n "$TYPE_LINE" ]] && AGENT_TYPE="$TYPE_LINE"
fi
ok "Agente $ID encontrado en $AGENT_DIR/"
dim " Tipo: $AGENT_TYPE"
[[ -n "$AGENT_DESC" ]] && dim " Descripcion: $AGENT_DESC"
echo ""
# ── Confirmacion interactiva ────────────────────────────────────────────────
if [[ "$FORCE" != true ]]; then
echo -e "${YLW}ATENCION: Esta accion es irreversible.${RST}"
echo -e "Se eliminaran:"
echo -e " - Directorio ${AGENT_DIR}/ (codigo, config, datos, crypto)"
if [[ "$KEEP_MATRIX" != true ]]; then
echo -e " - Usuario Matrix @${ID}:${MATRIX_SERVER_NAME:-<server>}"
fi
echo -e " - Variables de entorno en .env"
echo -e " - Import en cmd/launcher/main.go"
echo ""
read -rp "Escribir '$ID' para confirmar: " CONFIRM
if [[ "$CONFIRM" != "$ID" ]]; then
fail "Eliminacion cancelada"
fi
echo ""
fi
# ── Paso 2: Detener proceso ─────────────────────────────────────────────────
info "Paso 2/${TOTAL_STEPS} — Deteniendo proceso..."
PIDS="$(find_agent_pids "$ID")"
if [[ -n "$PIDS" ]]; then
echo "$PIDS" | while read -r pid; do
kill "$pid" 2>/dev/null && ok "Proceso $pid detenido" || warn "No se pudo detener proceso $pid"
done
# Esperar a que terminen
sleep 1
else
dim " No hay procesos corriendo para $ID"
fi
# Limpiar PID file
rm -f "$(pid_file "$ID")" 2>/dev/null
echo ""
# ── Paso 3: Desactivar usuario Matrix ───────────────────────────────────────
info "Paso 3/${TOTAL_STEPS} — Desactivando usuario Matrix..."
if [[ "$KEEP_MATRIX" == true ]]; then
dim " --keep-matrix: usuario Matrix preservado"
else
if [[ -n "${MATRIX_ADMIN_TOKEN:-}" && -n "${MATRIX_HOMESERVER:-}" && -n "${MATRIX_SERVER_NAME:-}" ]]; then
"$SCRIPT_DIR/deactivate-matrix.sh" "$ID" || warn "No se pudo desactivar usuario Matrix (continuando)"
else
warn "Faltan variables de Matrix en .env — usuario no desactivado"
fi
fi
echo ""
# ── Paso 4: Eliminar import del launcher ────────────────────────────────────
info "Paso 4/${TOTAL_STEPS} — Eliminando import del launcher..."
"$SCRIPT_DIR/remove-launcher-import.sh" "$ID"
echo ""
# ── Paso 5: Eliminar variables de entorno ────────────────────────────────────
info "Paso 5/${TOTAL_STEPS} — Eliminando variables de entorno..."
"$SCRIPT_DIR/remove-env-vars.sh" "$ID"
echo ""
# ── Paso 6: Eliminar archivos ───────────────────────────────────────────────
info "Paso 6/${TOTAL_STEPS} — Eliminando archivos..."
# Directorio del agente
if [[ -d "$AGENT_DIR" ]]; then
rm -rf "$AGENT_DIR"
ok "$AGENT_DIR/ eliminado"
fi
# Runtime files
for f in "run/${ID}.pid" "run/${ID}.log"; do
if [[ -f "$f" ]]; then
rm -f "$f"
ok "$f eliminado"
fi
done
# Log directory
if [[ -d "logs/$ID" ]]; then
rm -rf "logs/$ID"
ok "logs/$ID/ eliminado"
fi
echo ""
# ── Paso 7: Recompilar ─────────────────────────────────────────────────────
info "Paso 7/${TOTAL_STEPS} — Recompilando..."
if $GO build -tags goolm ./... 2>&1; then
ok "Compilacion exitosa"
else
fail "Error de compilacion — revisa cmd/launcher/main.go manualmente"
fi
echo ""
# ── Resumen ─────────────────────────────────────────────────────────────────
echo -e "${GRN}═══════════════════════════════════════════════════════${RST}"
echo -e "${GRN} ✓ Agente $ID eliminado completamente${RST}"
echo -e "${GRN}═══════════════════════════════════════════════════════${RST}"
echo ""
echo -e " ${BLU}Eliminado:${RST}"
echo -e " $AGENT_DIR/"
echo -e " cmd/launcher/main.go (import)"
echo -e " .env (MATRIX_TOKEN_${NORM}, MATRIX_PASSWORD_${NORM}, PICKLE_KEY_${NORM}, SSSS_RECOVERY_KEY_${NORM})"
if [[ "$KEEP_MATRIX" != true ]]; then
echo -e " @${ID}:${MATRIX_SERVER_NAME:-<server>} (usuario Matrix desactivado)"
else
echo -e " ${YLW}Usuario Matrix preservado (--keep-matrix)${RST}"
fi
echo ""
dev-scripts/agent/remove-env-vars.sh
Executable
+35
View File
@@ -0,0 +1,35 @@
#!/usr/bin/env bash
# remove-env-vars.sh — elimina las variables de entorno de un agente del .env
#
# Uso:
# ./dev-scripts/agent/remove-env-vars.sh <agent-id>
#
# Elimina las 4 variables generadas por register.sh y verify.sh:
# MATRIX_TOKEN_<NORM>, MATRIX_PASSWORD_<NORM>,
# PICKLE_KEY_<NORM>, SSSS_RECOVERY_KEY_<NORM>
source "$(dirname "$0")/../_common.sh"
need_arg "${1:-}"
ID="$1"
NORM="$(normalize_id "$ID")"
ENV_FILE=".env"
[[ -f "$ENV_FILE" ]] || fail ".env no encontrado"
VARS=(
"MATRIX_TOKEN_${NORM}"
"MATRIX_PASSWORD_${NORM}"
"PICKLE_KEY_${NORM}"
"SSSS_RECOVERY_KEY_${NORM}"
)
for var in "${VARS[@]}"; do
if grep -q "^${var}=" "$ENV_FILE"; then
sed -i "/^${var}=/d" "$ENV_FILE"
ok "$var eliminado de $ENV_FILE"
else
dim " $var no encontrado en $ENV_FILE (ya eliminado?)"
fi
done
dev-scripts/agent/remove-launcher-import.sh
Executable
+26
View File
@@ -0,0 +1,26 @@
#!/usr/bin/env bash
# remove-launcher-import.sh — elimina el blank import de un agente del launcher
#
# Uso:
# ./dev-scripts/agent/remove-launcher-import.sh <agent-id>
#
# Elimina la linea de blank import del agente en cmd/launcher/main.go.
# Soporta imports normales y con alias (e.g. testbot "...").
source "$(dirname "$0")/../_common.sh"
need_arg "${1:-}"
ID="$1"
LAUNCHER="cmd/launcher/main.go"
[[ -f "$LAUNCHER" ]] || fail "$LAUNCHER no encontrado"
# Buscar la linea del import (blank import o con alias)
if grep -q "agents/$ID\"" "$LAUNCHER"; then
# Eliminar la linea que contiene el import del agente
sed -i "\|agents/$ID\"|d" "$LAUNCHER"
ok "Import de $ID eliminado de $LAUNCHER"
else
warn "$ID no tiene import en $LAUNCHER (ya eliminado?)"
fi
dev-scripts/agent/remove.sh
+3
View File
@@ -1,6 +1,9 @@
#!/usr/bin/env bash
# remove.sh — deshabilita un agente (enabled: false). No borra datos.
#
# Para eliminacion completa (irreversible), usar delete-full.sh:
# ./dev-scripts/agent/delete-full.sh <agent-id>
#
# Uso:
# ./dev-scripts/agent/remove.sh assistant-bot
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 |