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-scripts/agent/deactivate-matrix.sh b/dev-scripts/agent/deactivate-matrix.sh new file mode 100755 index 0000000..3360e0a --- /dev/null +++ b/dev-scripts/agent/deactivate-matrix.sh @@ -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 +# +# 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 diff --git a/dev-scripts/agent/delete-full.sh b/dev-scripts/agent/delete-full.sh new file mode 100755 index 0000000..207b5bc --- /dev/null +++ b/dev-scripts/agent/delete-full.sh @@ -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 # con confirmacion +# ./dev-scripts/agent/delete-full.sh --force # sin confirmacion +# ./dev-scripts/agent/delete-full.sh --keep-matrix # preserva usuario Matrix +# ./dev-scripts/agent/delete-full.sh --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:-}" + 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:-} (usuario Matrix desactivado)" +else + echo -e " ${YLW}Usuario Matrix preservado (--keep-matrix)${RST}" +fi +echo "" diff --git a/dev-scripts/agent/remove-env-vars.sh b/dev-scripts/agent/remove-env-vars.sh new file mode 100755 index 0000000..be635ec --- /dev/null +++ b/dev-scripts/agent/remove-env-vars.sh @@ -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 +# +# Elimina las 4 variables generadas por register.sh y verify.sh: +# MATRIX_TOKEN_, MATRIX_PASSWORD_, +# PICKLE_KEY_, SSSS_RECOVERY_KEY_ + +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 diff --git a/dev-scripts/agent/remove-launcher-import.sh b/dev-scripts/agent/remove-launcher-import.sh new file mode 100755 index 0000000..973303c --- /dev/null +++ b/dev-scripts/agent/remove-launcher-import.sh @@ -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 +# +# 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 diff --git a/dev-scripts/agent/remove.sh b/dev-scripts/agent/remove.sh index 8198199..287056e 100755 --- a/dev-scripts/agent/remove.sh +++ b/dev-scripts/agent/remove.sh @@ -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 +# # Uso: # ./dev-scripts/agent/remove.sh assistant-bot 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 |