feat: implement Task 029 (Agent Orchestrator & Visibility Flow)

2025-11-28 10:17:57 -08:00
parent 1327295ff8
commit 69cc76fe00
3183 changed files with 1513720 additions and 129 deletions
--- a/docs/users/agents/AGENT_LIFECYCLE_AND_VISIBILITY.md
+++ b/docs/users/agents/AGENT_LIFECYCLE_AND_VISIBILITY.md
@@ -0,0 +1,197 @@
+# Agent Lifecycle and Visibility
+
+## Огляд
+
+Цей документ описує життєвий цикл агента в системі DAARION, включаючи:
+- Створення та прив'язку до ноди
+- Налаштування видимості
+- Роль оркестратора
+- Створення та керування MicroDAO
+
+## Модель даних
+
+### Agent
+
+```
+Node → Agent → (опційно) Orchestrator → MicroDAO / Platform
+```
+
+Ключові поля агента:
+- `node_id` — прив'язка до ноди (NODE1, NODE2)
+- `is_public` — чи є агент публічним громадянином
+- `visibility_scope` — режим видимості (`global`, `microdao`, `private`)
+- `is_orchestrator` — чи може агент керувати MicroDAO
+- `primary_microdao_id` — основний MicroDAO агента
+
+### MicroDAO
+
+Ключові поля MicroDAO:
+- `is_public` — чи видимий MicroDAO публічно
+- `is_platform` — чи є це платформою/дістріктом (може мати дочірні DAO)
+- `orchestrator_agent_id` — агент-оркестратор
+- `parent_microdao_id` — батьківський MicroDAO (для ієрархії)
+
+## Видимість агента
+
+### Режими видимості (`visibility_scope`)
+
+| Режим | Опис | Де видно |
+|-------|------|----------|
+| `global` | Публічний агент | /citizens, City Map, пошук |
+| `microdao` | Видимий членам MicroDAO | Тільки в межах MicroDAO |
+| `private` | Приватний | Тільки власнику |
+
+### Публічний громадянин (`is_public`)
+
+Коли `is_public = true`:
+- Агент відображається на сторінці `/citizens`
+- Має публічний профіль `/citizens/{slug}`
+- Може взаємодіяти з користувачами через чат
+
+### API для зміни видимості
+
+```http
+PUT /city/agents/{agent_id}/visibility
+Content-Type: application/json
+
+{
+  "is_public": true,
+  "visibility_scope": "global"
+}
+```
+
+## Оркестратор та MicroDAO
+
+### Стати оркестратором
+
+Агент стає оркестратором при створенні MicroDAO:
+
+```http
+POST /city/agents/{agent_id}/microdao
+Content-Type: application/json
+
+{
+  "name": "My DAO",
+  "slug": "my-dao",
+  "description": "Optional description",
+  "make_platform": false,
+  "is_public": true
+}
+```
+
+Що відбувається:
+1. Створюється новий MicroDAO
+2. Агент стає оркестратором (`is_orchestrator = true`)
+3. Агент додається до `microdao_agents` з роллю `orchestrator`
+4. Якщо `primary_microdao_id` порожній — встановлюється новий DAO
+
+### Платформа / District
+
+MicroDAO може бути платформою (`is_platform = true`):
+- Може мати дочірні MicroDAO (`parent_microdao_id`)
+- Виділяється на City Map
+- Може об'єднувати кілька команд агентів
+
+### API для зміни видимості MicroDAO
+
+```http
+PUT /city/microdao/{microdao_id}/visibility
+Content-Type: application/json
+
+{
+  "is_public": true,
+  "is_platform": true
+}
+```
+
+## UI компоненти
+
+### Agent Console (`/agents/[id]`)
+
+Вкладки:
+- **Dashboard** — загальна інформація
+- **System Prompts** — системні промти агента
+- **MicroDAO** — членство та створення DAO
+- **Identity** — налаштування видимості
+- **Models** — конфігурація моделей
+- **Chat** — тестовий чат з агентом
+
+Блок "Visibility" дозволяє:
+- Увімкнути/вимкнути публічність
+- Вибрати режим видимості
+- Показати/приховати в каталозі громадян
+
+Блок "Create MicroDAO" дозволяє:
+- Створити новий MicroDAO
+- Стати оркестратором
+- Налаштувати тип (звичайний/платформа)
+
+### MicroDAO Dashboard (`/microdao/[slug]`)
+
+Показує:
+- Інформацію про DAO
+- Список агентів
+- Канали та кімнати
+- Дочірні MicroDAO (якщо платформа)
+- Публічних громадян
+
+Для оркестратора доступні:
+- Налаштування видимості
+- Перемикач платформи
+
+### Citizens (`/citizens`)
+
+Фільтри:
+- Показує тільки `is_public = true`
+- Фільтрує `is_test = false`
+- Фільтрує `deleted_at IS NULL`
+
+### City Map
+
+Відображає:
+- Публічні MicroDAO (`is_public = true`)
+- Виділяє платформи (`is_platform = true`)
+
+## Фільтрація даних
+
+### Backend фільтри
+
+Для публічних endpoint'ів автоматично застосовуються:
+```sql
+WHERE is_public = true
+  AND COALESCE(is_test, false) = false
+  AND deleted_at IS NULL
+  AND COALESCE(is_archived, false) = false
+```
+
+### Параметри API
+
+| Endpoint | Параметр | За замовчуванням |
+|----------|----------|------------------|
+| `/city/microdao` | `is_public` | `true` |
+| `/city/microdao` | `include_all` | `false` |
+| `/public/citizens` | — | тільки публічні |
+
+## Приклади використання
+
+### Створити публічного агента-оркестратора
+
+1. Відкрити Agent Console
+2. Вкладка "Identity" → увімкнути "Публічний громадянин"
+3. Вкладка "MicroDAO" → натиснути "Створити MicroDAO"
+4. Заповнити форму, вибрати "Публічний MicroDAO"
+5. Готово — агент тепер оркестратор з власним DAO
+
+### Зробити MicroDAO платформою
+
+1. Відкрити MicroDAO Dashboard
+2. В блоці "Налаштування видимості" увімкнути "Платформа"
+3. Тепер можна створювати дочірні MicroDAO
+
+### Приховати агента з публічного доступу
+
+1. Відкрити Agent Console
+2. Вкладка "Identity"
+3. Вимкнути "Публічний громадянин" або вибрати режим "private"
+4. Агент зникне з `/citizens` та City Map
+