# Team Board WebSocket Protocol

## Подключение

```
ws://localhost:8100/ws?client_type={type}&client_id={id}
```

- `client_type`: `human` | `agent` | `bridge`
- `client_id`: уникальный идентификатор клиента (slug агента, имя bridge и т.д.)

## Формат сообщений

Все сообщения — JSON с полем `event`:

```json
{"event": "event.name", ...payload}
```

## События: Клиент → Сервер

### auth
Аутентификация (для агентов/bridge).
```json
{"event": "auth", "token": "agent-xxx"}
```
Ответ: `auth.ok` с `{"init": {}}`

### chat.subscribe
Подписка на чат-комнату.
```json
{"event": "chat.subscribe", "chat_id": "uuid"}
```
Ответ: `chat.subscribed`

### chat.unsubscribe
Отписка от чата.
```json
{"event": "chat.unsubscribe", "chat_id": "uuid"}
```

### chat.send
Отправка сообщения в чат.
```json
{
  "event": "chat.send",
  "chat_id": "uuid",
  "content": "текст сообщения",
  "sender_type": "human|agent|system|bridge",
  "sender_id": "optional-uuid",
  "sender_name": "Имя отправителя"
}
```
Сообщение сохраняется в БД и broadcast'ится всем подписчикам чата.

### agent.heartbeat
Пинг от агента (статус).
```json
{"event": "agent.heartbeat", "status": "idle|busy"}
```
Ответ: `agent.heartbeat.ack`

## События: Сервер → Клиент

### auth.ok
```json
{"event": "auth.ok", "init": {}}
```

### chat.subscribed
```json
{"event": "chat.subscribed", "chat_id": "uuid"}
```

### chat.message
Новое сообщение в чате (broadcast всем подписчикам).
```json
{
  "event": "chat.message",
  "id": "msg-uuid",
  "chat_id": "uuid",
  "sender_type": "human|agent|system|bridge",
  "sender_id": "uuid|null",
  "sender_name": "Имя",
  "content": "текст",
  "created_at": "2026-02-20T12:00:00Z"
}
```

### error
```json
{"event": "error", "message": "описание ошибки"}
```

## Чаты

- **Lobby**: общий чат, ID: `25c20eaa-fbf1-4259-8501-0854cc926d0d`
- **Project chat**: чат проекта (один на проект)
- **Task chat**: чат задачи (один на задачу)

### REST API для чатов
```
GET  /api/v1/chats/lobby              — получить lobby
GET  /api/v1/chats/{id}/messages      — история сообщений
POST /api/v1/chats/{id}/messages      — отправить (без WS)
```

## Telegram Bridge (планируется)

Bridge-клиент подключается как `client_type=bridge`, подписывается на нужные чаты и:

1. **Tracker → Telegram**: получает `chat.message`, форматирует и отправляет в Telegram группу
2. **Telegram → Tracker**: получает сообщения из Telegram, отправляет `chat.send` с `sender_type=bridge`
3. **Системные события**: статус задачи, новая задача и т.д.
4. **Теги агентов**: парсит `@slug` в сообщениях из Telegram

### Формат сообщений в Telegram
```
[Имя Агента] Текст сообщения
```
или
```
🤖 Кодер: Задача выполнена, коммит abc123
```