From bea657938e49204d6597474fe0174226e54389a2 Mon Sep 17 00:00:00 2001
From: Markov <markov@uix.su>
Date: Sun, 15 Feb 2026 18:34:27 +0100
Subject: [PATCH] docs: agent manager, SDK, adapters, lifecycle

---
 IDEAS.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)

diff --git a/IDEAS.md b/IDEAS.md
index 270f4da..dca2693 100644
--- a/IDEAS.md
+++ b/IDEAS.md
@@ -540,6 +540,158 @@ CREATE TABLE task_files (
 
 ---
 
+## Управление агентами (Agent Manager)
+
+### Принцип
+
+**Агент = отдельный процесс.** Не привязан к OpenClaw или конкретному серверу. Может быть запущен локально, на другом сервере, в Docker — где угодно. Подключается к Tracker по WebSocket.
+
+### Архитектура
+
+```
+┌─────────────────────────┐
+│     Agent Process        │
+│  ┌───────────────────┐  │
+│  │  Agent SDK         │  │  ← общая Python-библиотека
+│  │  ┌──────────────┐ │  │
+│  │  │   Adapter     │ │  │  ← OpenClaw / OpenAI / Ollama / CLI
+│  │  └──────────────┘ │  │
+│  └─────────┬─────────┘  │
+└────────────┼────────────┘
+             │ WebSocket (локально или через интернет)
+      ┌──────┴──────┐
+      │   Tracker    │
+      │ AgentManager │
+      └─────────────┘
+```
+
+### Agent SDK (Python-пакет)
+
+Общая библиотека для всех агентов:
+
+```python
+from team_board.agent import Agent
+from team_board.adapters import OpenClawAdapter
+
+adapter = OpenClawAdapter(
+    gateway_url="http://localhost:18789",
+    gateway_token="...",
+)
+
+agent = Agent(
+    name="Кодер",
+    tracker_url="ws://localhost:8100",
+    adapter=adapter,
+    system_prompt="Ты — backend разработчик...",
+)
+
+agent.run()  # подключается к Tracker, слушает задачи
+```
+
+Что делает SDK:
+- **WebSocket клиент** → подключение к Tracker, переподключение при разрыве
+- **Heartbeat** → автоматический пинг каждые N секунд
+- **Обработка задач** → получил задачу → передал адаптеру → вернул результат
+- **Файловые операции** → загрузка/скачивание файлов задачи
+
+### Адаптеры (BaseAdapter)
+
+```python
+class BaseAdapter(ABC):
+    @abstractmethod
+    async def send(self, messages: list[Message]) -> Response:
+        """Отправить сообщения нейросети и получить ответ."""
+        ...
+
+    @abstractmethod
+    async def capabilities(self) -> list[str]:
+        """Возвращает capabilities адаптера."""
+        ...
+```
+
+Реализации:
+| Адаптер | Подключение | Особенности |
+|---------|-------------|-------------|
+| `OpenClawAdapter` | Webhooks / sessions_spawn | Доступ к инструментам OpenClaw |
+| `AnthropicAdapter` | Claude API напрямую | Чистый API, без инструментов |
+| `OpenAIAdapter` | GPT / Codex API | |
+| `OllamaAdapter` | Локальная модель | Бесплатно, офлайн |
+| `CLIAdapter` | Claude Code CLI | Доступ к файловой системе |
+
+### AgentManager (в Tracker)
+
+Tracker управляет жизненным циклом агентов:
+
+```yaml
+Реестр агентов:
+  - id: uuid
+    name: "Кодер"
+    adapter: "Claude Opus"
+    status: online | offline | busy | dead
+    host: "localhost"           # где запущен
+    pid: 12345                  # PID процесса (если локальный)
+    last_heartbeat: timestamp
+    current_tasks: [task_id]
+```
+
+Функции AgentManager:
+1. **Запуск** — поднимает агента как отдельный процесс (локально: subprocess/systemd)
+2. **Мониторинг** — следит за heartbeat, помечает dead если пропал
+3. **Перезапуск** — dead агент → повторный запуск (макс 3 попытки)
+4. **Назначение задач** — матчит задачу → подходящего агента по capabilities + загрузке
+5. **Остановка** — graceful shutdown через WebSocket команду
+
+### Запуск агентов
+
+**Локально (MVP):**
+```bash
+# Tracker запускает как subprocess
+python -m team_board.agent --name coder --tracker ws://localhost:8100
+```
+
+**Через systemd (production):**
+```ini
+[Unit]
+Description=Team Board Agent: Coder
+
+[Service]
+ExecStart=/opt/team-board/venv/bin/python -m team_board.agent --name coder
+Restart=on-failure
+RestartSec=5
+```
+
+**Удалённо (будущее):**
+- SSH: `ssh remote-host 'python -m team_board.agent --tracker ws://tracker:8100'`
+- Docker: `docker run team-board-agent --tracker ws://tracker:8100`
+- HTTP API на удалённом хосте
+
+### Heartbeat и мониторинг
+
+```
+Агент → Tracker: agent.heartbeat (каждые 30 сек)
+  {
+    status: "idle" | "busy",
+    current_tasks: [...],
+    uptime: 3600,
+    memory_mb: 150
+  }
+
+Если heartbeat не пришёл 90 секунд → статус = dead → перезапуск
+```
+
+### Таблица БД
+
+```sql
+-- Расширение таблицы agents
+ALTER TABLE agents ADD COLUMN host TEXT DEFAULT 'localhost';
+ALTER TABLE agents ADD COLUMN pid INT;
+ALTER TABLE agents ADD COLUMN last_heartbeat TIMESTAMPTZ;
+ALTER TABLE agents ADD COLUMN restart_count INT DEFAULT 0;
+ALTER TABLE agents ADD COLUMN max_restarts INT DEFAULT 3;
+```
+
+---
+
 ## Открытые вопросы
 
 1. Как интегрировать CLI-агентов (Claude Code, Cline)?