diff --git a/dev/issues/0131-agents-dashboard-v0-2-full-control.md b/dev/issues/0131-agents-dashboard-v0-2-full-control.md new file mode 100644 index 00000000..8034fe7d --- /dev/null +++ b/dev/issues/0131-agents-dashboard-v0-2-full-control.md @@ -0,0 +1,235 @@ +--- +id: "0131" +title: "agents v0.2: control per-agent unified mode + uptime/msg_24h + data_table_cpp_viz + clear/cache actions" +status: pendiente +type: feature +domain: + - agents + - tui + - infra +scope: app +priority: alta +depends: + - "0128" + - "0129" +blocks: [] +related: [] +created: 2026-05-22 +updated: 2026-05-22 +tags: [agents_and_robots, agents_dashboard, http, unified-mode, data-table, control] +dod_evidence_schema: + # Backend: agents_and_robots + - id: build_backend + kind: cmd + expected: "cd projects/element_agents/apps/agents_and_robots && go build -tags goolm ./... → exit 0" + required: true + - id: tests_backend + kind: cmd + expected: "cd projects/element_agents/apps/agents_and_robots && go test -tags goolm -count=1 ./internal/api/... → exit 0" + required: true + - id: stop_unified_works + kind: cmd + expected: "POST /agents/test-bot/stop devuelve {status:stopped}; GET /agents/test-bot → running=false en <2s" + required: true + - id: start_unified_works + kind: cmd + expected: "POST /agents/test-bot/start tras stop devuelve {status:started}; GET /agents/test-bot → running=true en <5s" + required: true + - id: restart_unified_works + kind: cmd + expected: "POST /agents/test-bot/restart sobre agente running deja running=true en <8s sin error" + required: true + - id: clear_memory_endpoint + kind: cmd + expected: "POST /agents/test-bot/clear_memory devuelve {status:cleared, messages_deleted:N}; SELECT COUNT(*) FROM messages WHERE agent_id='test-bot' == 0" + required: true + - id: delete_cache_endpoint + kind: cmd + expected: "POST /agents/test-bot/delete_cache devuelve {status:cleared, paths_deleted:[...]}; verificar que crypto.db cache borrado" + required: true + - id: uptime_exposed + kind: cmd + expected: "GET /agents incluye campo uptime_seconds:int >0 para agents running" + required: true + - id: msg_24h_exposed + kind: cmd + expected: "GET /agents incluye campo messages_24h:int (puede ser 0) calculado de tabla messages" + required: true + # Frontend: agents_dashboard + - id: build_frontend + kind: cmd + expected: "cmake --build cpp/build/windows --target agents_dashboard -j → exit 0" + required: true + - id: data_table_cpp_viz_used + kind: cmd + expected: "grep -E 'BeginTable|EndTable' projects/element_agents/apps/agents_dashboard/main.cpp devuelve 0 lineas (migrado a data_table_cpp_viz); grep data_table_cpp_viz app.md uses_functions = 1" + required: true + - id: per_agent_buttons_rendered + kind: screenshot + expected: "Tabla Agents muestra >=5 botones por fila: Start, Stop, Restart, Clear Memory, Delete Cache (puede iconos+tooltip)" + required: true + - id: uptime_visible + kind: screenshot + expected: "Tabla Agents columna uptime muestra valor humanizado (ej 12h, 3d) para agents running" + required: true + - id: msg_24h_visible + kind: screenshot + expected: "Tabla Agents columna msg/24h muestra contador real (no 'instances' como hack)" + required: true + # E2E: pytest + - id: e2e_tests_pass + kind: cmd + expected: "AGENTS_API_KEY=... pytest tests/test_connect_e2e.py → todos PASS (>=20 tests)" + required: true + - id: e2e_control_roundtrip + kind: cmd + expected: "Nuevo test_control_roundtrip: stop → poll running=false → start → poll running=true → restart → poll running=true. Todo dentro de 30s." + required: true + - id: e2e_clear_memory + kind: cmd + expected: "Nuevo test_clear_memory: insert filas en messages → POST /clear_memory → COUNT == 0" + required: true +--- + +# 0131 — agents v0.2: full per-agent control + data_table + nuevos botones + +## Contexto + +v0.1 (issues 0128+0129) entrego: +- HTTP API + apikey + TLS + SSE +- C++ frontend con Connection/Agents/Logs/Status feed +- Tabla agents con `running` derivado de backend + +**Gaps detectados durante uso real:** +1. **Control individual roto en unified mode** — Manager.Start/Stop esperan PID files por agente; en unified mode no existen → endpoints devuelven errores confusos ("not running" sobre agente que SI corre). +2. **No hay uptime ni msg_24h reales** — backend no expone esos campos. UI muestra `instances` como hack para msg_24h. +3. **Faltan acciones de gestion** — clear memory (mensajes en SQLite), delete cache (crypto E2EE), reset state. +4. **Tabla manual** — `ImGui::BeginTable` inline en main.cpp. El registry tiene `data_table_cpp_viz` (funcion canonica). Migrar. + +## Scope v0.2 + +### Backend (`projects/element_agents/apps/agents_and_robots/`) + +**1. Control per-agent en unified mode** + +Hoy launcher arranca todos los agents como goroutines bajo 1 PID via mode "unified". `Manager.Start/Stop/Restart` actuales solo funcionan en mode multi-process (PID por agente). + +Anadir registro de cancel-context por agente en el launcher: +- Por cada agente que arranca como goroutine, guardar `context.CancelFunc` en `Manager.unifiedCancels map[string]context.CancelFunc`. +- `Manager.StopUnifiedAgent(id)` llama cancel del agente especifico. +- `Manager.StartUnifiedAgent(id)` re-arranca solo ese agente sin restart del launcher entero. +- `Manager.RestartUnifiedAgent(id)` = Stop + Start. + +Handlers `handleStart/Stop/Restart` autodetectan via `IsUnifiedRunning()` y delegan a las nuevas variantes unified. + +**2. Uptime real** + +- `Manager.startedAt map[string]time.Time` poblado al arrancar cada goroutine. +- En `AgentStatus.UptimeSeconds`, calcular `time.Since(startedAt[id]).Seconds()` si running, else 0. +- Exponer en `agentResponse` como `uptime_seconds: int`. + +**3. Messages_24h** + +Cada agent persiste mensajes en su SQLite (`agents//data/memory.db`). El handler `handleListAgents` debe agregar por agente: +- Abrir DB del agente readonly +- `SELECT COUNT(*) FROM messages WHERE created_at > datetime('now', '-24 hours')` +- Cache 30s para no abrir DB en cada request + +Exponer como `messages_24h: int`. + +**4. Endpoint `POST /agents/{id}/clear_memory`** + +- Stop agent (si running) +- Open agent's memory.db +- `DELETE FROM messages` + `DELETE FROM facts` +- Optionally start back si estaba running (deber `?restart=true` opcional) +- Return `{status:"cleared", messages_deleted:N, facts_deleted:M}` + +**5. Endpoint `POST /agents/{id}/delete_cache`** + +- Stop agent (si running) +- Delete `agents//data/crypto/` directory (E2EE cache; agent re-init on next start) +- Delete `agents//data/cache/*` si existe +- Return `{status:"cleared", paths_deleted:[...]}` +- Optionally start back si estaba running (`?restart=true`) + +NOTA: delete_cache fuerza re-verificacion E2EE. El agente debe re-autenticarse via SSSS recovery key on next start. Documentar. + +### Frontend (`projects/element_agents/apps/agents_dashboard/`) + +**1. Migrar a `data_table_cpp_viz`** + +Hoy main.cpp usa `ImGui::BeginTable` inline. Sustituir por `data_table::Table` del registry (funcion `data_table_cpp_viz`). Anadir a `app.md::uses_functions`. Verificar via `fn doctor cpp-apps` que la app pasa de `CANDIDATE` a limpio. + +**2. Columnas tabla:** +- id +- status icon (running=green, stopped=gray, disabled=yellow, crashed=red) +- uptime (humanized via `human_duration_secs`) +- msg/24h (numero real, NO instances) +- actions (5 botones agrupados): + - `▶ Start` (disabled si running) + - `⏹ Stop` (disabled si !running) + - `↻ Restart` + - `🧠 Clear Memory` (confirmacion modal) + - `🗑 Delete Cache` (confirmacion modal) + +**3. Sort + filter** mantener via data_table_cpp_viz API. + +### E2E (`tests/`) + +Anadir 7 tests nuevos: +- `test_control_roundtrip` — stop → poll → start → poll → restart → poll. Usa `test-bot`. +- `test_clear_memory` — POST clear_memory, verifica COUNT(*) FROM messages == 0. +- `test_delete_cache` — POST delete_cache, verifica crypto/ borrado. +- `test_uptime_field_present` — /agents response incluye uptime_seconds key +- `test_msg_24h_field_present` — /agents response incluye messages_24h key +- `test_unified_stop_does_not_kill_launcher` — tras stop de 1 agente, otros siguen running. +- `test_clear_memory_requires_apikey` — sin Bearer → 401 + +## Tareas + +### Fase A — Backend (agents_and_robots) + +1. Agregar `unifiedCancels map[string]context.CancelFunc` + `startedAt map[string]time.Time` + mutex a `shell/process.Manager`. +2. Hook en `launcher` runtime para registrar/desregistrar cancels al arrancar/parar cada agent goroutine. +3. Implementar `StopUnifiedAgent`, `StartUnifiedAgent`, `RestartUnifiedAgent` (Stop+Start). +4. Refactor handlers `handleStartAgent/Stop/Restart` para autodetect unified vs multi. +5. Anadir `uptime_seconds` y `messages_24h` a `AgentResponse`. Implementar query 24h con cache 30s. +6. Implementar handlers `handleClearMemory`, `handleDeleteCache`. +7. Anadir rutas en `server.go`. +8. Tests Go unit `internal/api/*_test.go`. + +### Fase B — Frontend (agents_dashboard) + +1. Cambiar `parse_agents` para leer `uptime_seconds` y `messages_24h` del backend. +2. Migrar tabla a `data_table_cpp_viz`. Mantener filter + sort. +3. Anadir 5 botones por fila (Start/Stop/Restart/Clear/Delete). +4. Confirmacion modal para Clear/Delete. +5. Actualizar app.md::uses_functions con `data_table_cpp_viz`. + +### Fase C — E2E + verify + +1. Anadir 7 pytest tests. +2. Run all e2e from registry venv. >=20 tests pass. +3. Rebuild .exe + redeploy Windows. +4. Visual confirm: botones, uptime, msg_24h. + +## Acceptance + +- [ ] All 14 DoD items green (cmd + screenshots). +- [ ] >=20 e2e tests passing. +- [ ] App C++ deployed to Windows Desktop, visible buttons + working roundtrip. +- [ ] Backend unit tests pass. +- [ ] No regression: 0128 + 0129 funcionalidad existente intacta (curl smoke del v0.1 sigue green). + +## DoD humano + +- **Donde**: Windows Desktop → agents_dashboard.exe → tabla Agents. +- **Latencia**: stop → running=false reflected in UI within 2s (via SSE status diff). msg/24h refresh cada 30s ok. +- **Onboarding**: tooltip en boton "Clear Memory" explica que borra mensajes; "Delete Cache" explica que el agente tendra que re-autenticar via SSSS al volver a arrancar. + +## Riesgos + +- Refactor de Manager unified-mode toca el ciclo de vida del launcher (paso ~7 del create_agent pipeline). Tests existentes deben pasar. +- delete_cache borra crypto store; agente debe poder re-verify via env var `SSSS_RECOVERY_KEY_`. Si esa env var no esta, agente queda en estado degradado. Validar antes de borrar. +- data_table_cpp_viz puede tener limites de API que ImGui inline no tiene (sort custom, alignment). Verificar antes de migrar.