docs/AGENTS-INTEGRATION.md

# Интеграция агентов — ресёрч

## Аналогия с 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)