microdao-daarion/docs/tasks/TASK_PHASE_DAGI_AGENT_AUDIT_MVP_v1.md

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/скрипт:

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:

SELECT id, name, role, node_id FROM agents WHERE node_id = :node

3. Обчислити:

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-звіту

{
  "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 — останній час успішного контакту.

Міграція:

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. Алгоритм

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:

{
  "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