microdao-daarion/docs/runbook/sofiia-console-ops.md

Sofiia Console — Operations Runbook

1. Rebuild & Deploy (NODA2)

cd /opt/microdao-daarion  # or ~/github-projects/microdao-daarion on dev

# Rebuild sofiia-console (UI + backend)
docker compose -f docker-compose.node2-sofiia.yml build sofiia-console --no-cache
docker compose -f docker-compose.node2-sofiia.yml up -d sofiia-console

# Rebuild gateway (for agent registry changes)
docker compose -f docker-compose.node2-sofiia.yml build gateway --no-cache
docker compose -f docker-compose.node2-sofiia.yml up -d gateway

2. Confirm Build Version

# Via API
APIKEY=$(grep SOFIIA_CONSOLE_API_KEY .env | cut -d= -f2)
curl -s http://localhost:8002/api/meta/version -H "X-API-Key: $APIKEY"
# Expected: {"version":"0.4.0","build_sha":"dev","build_time":"local",...}

# In UI: header shows "v0.4.0 dev" badge (top right)

3. Verify Agents List

APIKEY=$(grep SOFIIA_CONSOLE_API_KEY .env | cut -d= -f2)

# NODA2 agents
curl -s "http://localhost:8002/api/agents?nodes=NODA2" -H "X-API-Key: $APIKEY" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(f'items={len(d[\"items\"])} stats={d[\"stats\"]} errors={d[\"node_errors\"]}')"

# NODA1 agents  
curl -s "http://localhost:8002/api/agents?nodes=NODA1" -H "X-API-Key: $APIKEY" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(f'items={len(d[\"items\"])} stats={d[\"stats\"]} errors={d[\"node_errors\"]}')"

# All nodes
curl -s "http://localhost:8002/api/agents?nodes=NODA1,NODA2" -H "X-API-Key: $APIKEY" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(f'items={len(d[\"items\"])} stats={d[\"stats\"]} errors={d[\"node_errors\"]}')"

# Direct gateway check (NODA2)
curl -s http://localhost:9300/health | python3 -c "
import sys,json; d=json.load(sys.stdin)
print(f'agents={d[\"agents_count\"]}')
for k,v in sorted(d[\"agents\"].items()): print(f'  {k}: badges={v.get(\"badges\",[])}')
"

4. UI Debug Panel

У вкладці 📁 Проєкти → Agents:

1. Натисніть кнопку 🔍 Debug в панелі дій
2. Debug panel показує:
   • fetch: час останнього запиту
   • nodes: вибрані ноди
   • items: кількість агентів
   • ok/total: кількість успішних нод
   • errors: помилки нод (якщо є)

5. Troubleshooting

Агенти не відображаються в UI

1. Перевірте API ключ у налаштуваннях UI
2. Натисніть ↻ Sync
3. Відкрийте 🔍 Debug — перевірте errors
4. Перевірте gateway health: curl http://localhost:9300/health

Gateway падає при старті

docker logs dagi-gateway-node2 --tail 50

Типова причина: ImportError у http_api_doc.py → doc_service.py Рішення: перевірте що в doc_service.py є stub-функції (doc_service, update_document, list_document_versions, publish_document_artifact).

SQLite "no such column: last_applied_hash"

БД у volume має стару схему. Вирішення — міграції виконуються автоматично при старті через _MIGRATION_SQL_STMTS у db.py. Restart контейнера вирішує:

docker restart sofiia-console

NODA2 gateway_url недоступний з контейнера

У config/nodes_registry.yml NODA2 використовує host.docker.internal:9300. Якщо UI запущений не в Docker — замініть на localhost:9300.

Monitor / AISTALK не відображаються

Перевірте що в gateway-bot/http_api.py:

• MONITOR_CONFIG і AISTALK_CONFIG визначені через load_agent_config
• Вони додані в AGENT_REGISTRY
• Файл gateway-bot/monitor_prompt.txt існує

docker exec dagi-gateway-node2 python3 -c "
from http_api import AGENT_REGISTRY
print(list(AGENT_REGISTRY.keys()))
"

6. Monitor Policy

Monitor (agent_id=monitor) є обов'язковим агентом на кожній ноді.

Перевірка

APIKEY=$(grep SOFIIA_CONSOLE_API_KEY .env | cut -d= -f2)
curl -s "http://localhost:8002/api/agents?nodes=NODA1,NODA2" -H "X-API-Key: $APIKEY" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print('missing:', d.get('required_missing_nodes'))"

• required_missing=[] — все ОК
• required_missing=[{"node_id":"NODA1","agent_id":"monitor"}] — Monitor відсутній на NODA1 → перевірте gateway registry → rebuild gateway

Governance event

Якщо Monitor відсутній на онлайн-ноді — автоматично записується governance_event типу node_required_agent_missing (severity=high).

7. Voice & Telegram Capabilities

У вкладці Agents:

• 🎙 Voice badge — агент підтримує голос (AISTALK)
• 💬 Telegram badge — агент активний у Telegram
• Фільтри 🎙 Voice і 💬 Telegram — client-side фільтрація

API

curl -s "http://localhost:8002/api/agents?nodes=NODA1" -H "X-API-Key: $APIKEY" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); 
  voice=[a['agent_id'] for a in d['items'] if a.get('capabilities',{}).get('voice')]
  print('voice:', voice)"

8. Document Versioning

API для версій документів (в межах Sofiia Console):

# Список версій
GET /api/projects/{project_id}/documents/{doc_id}/versions

# Оновити документ (зберігає нову версію)
POST /api/projects/{project_id}/documents/{doc_id}/update
{"content_md": "# Новий зміст", "author_id": "user", "reason": "оновлення", "dry_run": false}

# Відновити версію
POST /api/projects/{project_id}/documents/{doc_id}/restore
{"version_id": "...", "author_id": "user"}

9. Agent Registry SSoT

Canonical реєстр: config/agent_registry.yml

Gateway завантажує агентів з gateway-bot/http_api.py::AGENT_REGISTRY (Python dict). Щоб додати нового агента:

1. Додайте запис в config/agent_registry.yml
2. Додайте *_CONFIG = load_agent_config(...) і запис в AGENT_REGISTRY у gateway-bot/http_api.py
3. Створіть gateway-bot/<agent_id>_prompt.txt
4. Rebuild gateway

10. Ports Reference

Сервіс	Port	URL
Sofiia Console UI	8002	http://localhost:8002
Gateway	9300	http://localhost:9300/health
Router	9102	http://localhost:9102/health
Memory	8000	http://localhost:8000/health
Qdrant	6333	http://localhost:6333/healthz