# TASK_PHASE_DAGI_AGENT_AUDIT_MVP_v1

Проєкт: DAARION.city — DAGI Router / Node Cabinet  
Фаза: DAGI Agent Audit & Activity Monitor  
Мета: гарантувати, що всі агенти, оголошені DAGI Router на кожній Ноді (NODA1, NODA2), коректно синхронізовані з системою microdao та відображаються у Кабінеті Ноди з правильним індикатором активності.

---

# 0. Problem Statement

У процесі розробки та деплою деякі агенти на НОДА з'являлись/зникали.  
Не було механізму перевірки їх присутності та активності у DAGI Router та їх відповідності записам у системі (microdao → agents).

Потрібно створити:
- одноразовий аудит DAGI-агентів на кожній ноді;
- постійний автоматизований моніторинг активності агентів;
- індикатор «підключено/активний» замість терміну «зареєстрований у MVP»;
- UI-відображення в Кабінеті Ноди;
- метрики й сигналізація (NATS + Prometheus).

---

# 1. Scope

## Включено

- Аудит DAGI Router агентів на NODA1 та NODA2.
- Зіставлення: `router_agents` ↔ `system_agents` (таблиця microdao.agents).
- Додавання індикатора активності агента.
- Одноразовий звіт diff у JSON.
- Автоматичний воркер для періодичної перевірки.
- Метрики Prometheus.
- Події NATS.
- UI (Node Cabinet → вкладка "DAGI Router").

## Виключено

- Вплив на логіку DAGI Router.
- Автоматичне видалення агентів.
- Версіонування агентів.

---

# 2. Definitions

- **Router Agents** — агенти, які DAGI Router бачить на конкретній ноді (`GET /api/agents` або NATS `dagi.router.agent.list`).
- **System Agents** — агенти, зареєстровані в системі (таблиця `agents` у microdao).
- **Node Agent Auditor** — спеціальний агент Ноди, який періодично перевіряє відповідність.
- **Active** — агент з'являється в DAGI Router і відповідає на healthcheck.
- **Stale** — агент є в системі, але його немає в DAGI Router.
- **Phantom** — агент є в DAGI Router, але його немає в системі.

---

# 3. One-time Audit (Node1 + Node2)

## 3.1. Команда

Створити CLI/скрипт:

```bash
scripts/dagi_agent_audit.py --node node1
scripts/dagi_agent_audit.py --node node2
```

## 3.2. Дії

1. Отримати список агентів з DAGI Router:
```
GET {ROUTER_URL}/api/agents
```

2. Отримати список агентів з microdao:
```sql
SELECT id, name, role, node_id FROM agents WHERE node_id = :node
```

3. Обчислити:
```python
missing_in_system = router_ids - system_ids
stale_in_router   = system_ids - router_ids
active            = intersection(router_ids, system_ids)
```

4. Згенерувати звіт:
```
logs/dagi-audit-node{1,2}.json
```

## 3.3. Структура JSON-звіту

```json
{
  "node_id": "node1",
  "router_total": 15,
  "system_total": 14,
  "active": ["agent_x", "agent_y"],
  "missing_in_system": ["agent_z"],
  "stale_in_router": ["agent_a"],
  "timestamp": "..."
}
```

---

# 4. DB / System Changes

## 4.1. Таблиця agents (розширення)

Додати поля:
- `node_id text` — ідентифікатор ноди.
- `status text check(status in ('active','stale','missing','error'))` — стан.
- `last_seen_at timestamptz` — останній час успішного контакту.

Міграція:
```sql
ALTER TABLE agents ADD COLUMN IF NOT EXISTS node_id text;
ALTER TABLE agents ADD COLUMN IF NOT EXISTS status text DEFAULT 'stale';
ALTER TABLE agents ADD COLUMN IF NOT EXISTS last_seen_at timestamptz;
```

## 4.2. Repo-методи

- `repo_agents.update_status(agent_id, status, last_seen_at)`
- `repo_agents.list_by_node(node_id)`
- `repo_agents.sync_router_list(node_id, router_agents)` — optional

---

# 5. Automated Worker: Node Agent Auditor

Створити сервіс:
`services/node-agent-auditor/worker.py`

## 5.1. Частота

- кожні 60 секунд (конфігуровано).

## 5.2. Алгоритм

```python
router_agents = get_router_list(node)
system_agents = get_system_list(node)

active = intersection(router_agents, system_agents)
missing = router_agents - system_agents
stale = system_agents - router_agents

update agents.status
update agents.last_seen_at
publish NATS events
expose Prometheus metrics
```

## 5.3. NATS події

- `node.agent.audit.active`
- `node.agent.audit.missing`
- `node.agent.audit.stale`
- `node.agent.audit.error`

Payload:
```json
{
  "node_id": "node1",
  "agent_id": "daria",
  "status": "missing",
  "timestamp": "..."
}
```

## 5.4. Prometheus метрики

- `dagi_agents_active{node="node1"}`
- `dagi_agents_missing{node="node1"}`
- `dagi_agents_stale{node="node1"}`
- `dagi_agent_last_seen_timestamp{agent="daria",node="node1"}`

---

# 6. Node Cabinet UI

## 6.1. Нова вкладка

```
/node/{nodeId}/dagi-router
```

## 6.2. Таблиця

Колонки:
- Agent ID
- Name
- Role
- Status (`active`, `missing`, `stale`, `error`)
- Last Seen (`timestamp`)
- Node

## 6.3. Індикатор статусу

- 🟢 Зелене коло — active
- 🟡 Жовте — stale
- 🔴 Червоне — missing
- ⚫ Сіре — error

## 6.4. Елементи управління

- `Resync` → тригерить ручний аудит (POST `/internal/node/{id}/audit`).

---

# 7. API

## 7.1. GET

- `GET /internal/node/{node_id}/agents/router` → список DAGI Router агентів
- `GET /internal/node/{node_id}/agents/system` → список system agent records
- `GET /internal/node/{node_id}/audit` → останній аудит

## 7.2. POST

- `POST /internal/node/{node_id}/audit` → виконати аудит вручну
- `POST /internal/node/{node_id}/sync` → синхронізувати статуси (опційно)

---

# 8. Tests

## 8.1. Unit

- зіставлення router/system списків
- статуси: active/missing/stale/error

## 8.2. Integration

- worker → DB update
- worker → NATS event
- worker → Prometheus export

## 8.3. E2E

- запуск аудиту
- відображення у Node Cabinet UI
- Resync працює

---

# 9. Acceptance Criteria

- На NODA1 і NODA2 виконано успішний одноразовий аудит.
- JSON-звіти створені.
- Worker працює і оновлює статуси агентів у БД.
- Статуси в UI відповідають реальному стану Router.
- NATS і Prometheus показують коректні дані.
- Resync викликає миттєве оновлення.

---

# 10. Deliverables

- `scripts/dagi_agent_audit.py`
- `services/node-agent-auditor/worker.py`
- Міграція agents.status/last_seen_at/node_id
- API (internal)
- Node Cabinet UI вкладка
- Документація цього таску

---

# 11. Implementation Plan

## M0 — Одноразовий аудит (Day 1)
1. Створити `scripts/dagi_agent_audit.py`
2. Тест на NODA1 та NODA2
3. Звіти в `logs/`

## M1 — DB + Repo (Day 1-2)
1. Міграція для нових полів
2. Repo-методи в city-service

## M2 — Worker (Day 2-3)
1. Node Agent Auditor сервіс
2. NATS integration
3. Prometheus metrics

## M3 — UI (Day 3-4)
1. Node Cabinet вкладка "DAGI Router"
2. Таблиця агентів зі статусами
3. Resync button

---

**Версія:** 1.0.0  
**Дата:** 2025-11-30  
**Статус:** READY FOR IMPLEMENTATION