docs: agent integration research (runners model, contract, SDK)

AGENTS-INTEGRATION.md

@@ -0,0 +1,192 @@
+# Интеграция агентов — ресёрч
+
+## Аналогия с GitLab Runners
+
+| GitLab | Team Board |
+|--------|------------|
+| Runner | Agent Instance |
+| Runner Token | Agent Token |
+| `.gitlab-ci.yml` | Контракт (contract.json) |
+| Job | Task |
+| Executor (docker/shell) | Adapter (OpenClaw/Anthropic/CLI) |
+| Runner registration | `POST /api/v1/agents/register` |
+| Runner tags | Agent capabilities |
+
+## Архитектура подключения
+
+```
+1. Админ создаёт Agent в UI → получает registration token
+2. На сервере запускается Agent Instance с этим токеном
+3. Agent Instance регистрируется: POST /ws?token=<reg_token>
+4. Tracker подтверждает → выдаёт session token
+5. Agent слушает задачи через WebSocket
+6. При получении задачи → выполняет через адаптер
+```
+
+## Контракт агента (contract)
+
+Файл, описывающий что агент умеет и как с ним взаимодействовать.
+Хранится в трекере, привязан к конкретному агенту.
+
+```json
+{
+  "version": "1",
+  "capabilities": ["coding", "review", "docs"],
+  "max_concurrent_tasks": 2,
+  "timeout_seconds": 600,
+  "accept_task_types": ["coding", "review"],
+  "tools": {
+    "file_read": true,
+    "file_write": true,
+    "git_commit": true,
+    "git_pr": true,
+    "web_search": false,
+    "shell_exec": false
+  },
+  "limits": {
+    "max_file_size_mb": 10,
+    "max_files_per_task": 20,
+    "max_comment_length": 5000
+  }
+}
+```
+
+## Операции агента (через WebSocket)
+
+Агент должен уметь:
+
+### Задачи
+| Операция | WS Event | Описание |
+|----------|----------|----------|
+| Получить задачу | `task.assigned` (входящее) | Трекер назначает задачу агенту |
+| Взять задачу | `task.take` | Агент сам берёт задачу из TODO |
+| Обновить статус | `task.status` | draft→ready→in_progress→review→completed |
+| Обновить описание | `task.update` | Изменить title, description |
+| Создать задачу | `task.create` | Агент создаёт подзадачу |
+| Создать подзадачу | `task.create` (с parent_id) | Декомпозиция |
+| Добавить зависимость | `task.dependency.add` | TEA-3 depends on TEA-1 |
+
+### Комментарии
+| Операция | WS Event | Описание |
+|----------|----------|----------|
+| Добавить комментарий | `task.comment` | Текст, code snippets |
+| Читать комментарии | `task.comments.list` | История обсуждения |
+
+### Файлы
+| Операция | WS Event / HTTP | Описание |
+|----------|-----------------|----------|
+| Загрузить файл | `POST /api/v1/tasks/{id}/files` | Результат работы |
+| Скачать файл | `GET /api/v1/tasks/{id}/files/{fid}` | Входные данные |
+| Список файлов | `task.files.list` | Что есть в задаче |
+
+### Чат
+| Операция | WS Event | Описание |
+|----------|----------|----------|
+| Сообщение в чат | `chat.send` | Обсуждение |
+| Читать чат | `chat.history` | Контекст |
+
+## Страница настройки в UI
+
+### /settings/agents
+```
+┌─────────────────────────────────────────────┐
+│ Агенты                          [+ Создать] │
+├─────────────────────────────────────────────┤
+│ ● Кодер          online    2 tasks          │
+│   claude-opus    coding, review             │
+│   Подключён: 2 часа назад                  │
+│                                             │
+│ ● Аналитик       offline                    │
+│   gpt-4          analytics, docs            │
+│   Последний раз: вчера                      │
+│                                             │
+│ ○ Тестировщик    не зарегистрирован         │
+│   Токен: tb-agent-abc123... [Копировать]    │
+└─────────────────────────────────────────────┘
+```
+
+### Создание агента
+1. Имя + slug
+2. Системный промпт (роль)
+3. Контракт (capabilities, tools, limits)
+4. Генерация registration token
+5. Инструкция по запуску:
+```bash
+team-board-agent register \
+  --tracker wss://team.uix.su/ws \
+  --token tb-agent-abc123... \
+  --adapter anthropic \
+  --api-key sk-ant-...
+```
+
+## Регистрация и аутентификация
+
+### Шаг 1: Создание (UI)
+- Админ создаёт агента в UI
+- Генерируется одноразовый registration token
+- Токен показывается один раз
+
+### Шаг 2: Регистрация (Agent Instance)
+```
+Agent → Tracker: ws connect + registration token
+Tracker: validates token, marks agent as registered
+Tracker → Agent: session token (долгоживущий)
+Agent: сохраняет session token локально
+```
+
+### Шаг 3: Работа
+```
+Agent → Tracker: ws connect + session token
+Tracker: validates, marks online
+Agent ←→ Tracker: events (tasks, chat, files)
+```
+
+### Отзыв токена
+- Админ в UI нажимает "Отозвать"
+- Tracker закрывает WebSocket
+- Agent не может переподключиться
+- Нужна новая регистрация
+
+## SDK (Python)
+
+```python
+from team_board import Agent, AnthropicAdapter
+
+agent = Agent(
+    tracker_url="wss://team.uix.su/ws",
+    token="tb-session-xyz...",
+)
+
+@agent.on_task
+async def handle_task(task):
+    # Читаем описание и файлы
+    files = await task.list_files()
+    
+    # Работаем через адаптер
+    result = await agent.adapter.complete(
+        system=agent.system_prompt,
+        messages=[{"role": "user", "content": task.description}],
+    )
+    
+    # Добавляем комментарий
+    await task.comment(result.text)
+    
+    # Загружаем файл
+    await task.upload_file("result.py", result.code)
+    
+    # Меняем статус
+    await task.set_status("review")
+
+agent.run()
+```
+
+## Приоритеты реализации
+
+1. [ ] Tracker: token generation + WS auth
+2. [ ] Tracker: agent events (task.take, task.status, task.comment, task.create)
+3. [ ] Tracker: file upload/download API
+4. [ ] UI: /settings/agents page
+5. [ ] SDK: Python package (team-board-agent)
+6. [ ] SDK: AnthropicAdapter + OpenClawAdapter
+7. [ ] Первый агент: тестовый (echo/summarize)
+8. [ ] Первый реальный агент: Кодер (через OpenClaw/Claude)