Skip to content

# 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

1. Отримати список агентів з microdao:

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

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

    missing_in_system = router_ids - system_ids
    stale_in_router   = system_ids - router_ids
    active            = intersection(router_ids, system_ids)

1. Згенерувати звіт:

    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