Files

T

egutierrez 98da4f7521 docs: regla delete_agent.md y cierre de issue 0048

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>

2026-04-10 23:44:42 +00:00

6.1 KiB

Raw Blame History

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:

Directorio agents/<id>/ con agent.go, config.yaml, prompts/, data/
Blank import en cmd/launcher/main.go
4 env vars en .env (TOKEN, PASSWORD, PICKLE_KEY, SSSS_RECOVERY_KEY)
Usuario Matrix registrado en Synapse
Cross-signing keys y crypto store E2EE
Avatar y display name en Matrix
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// + 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

# 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

Scripts atomicos + orquestador: cada paso es un script independiente reutilizable, el orquestador los llama en orden. Misma filosofia que create-full.sh.
Confirmacion por defecto: borrar es destructivo e irreversible. El flag --force es para automatizacion.
--keep-matrix: permite reutilizar el usuario Matrix si se quiere recrear el agente con el mismo ID.
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

6.1 KiB Raw Blame History