docs/WEBSOCKET-PROTOCOL.md

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:

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

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

auth

Аутентификация (для агентов/bridge).

{"event": "auth", "token": "agent-xxx"}

Ответ: auth.ok с {"init": {}}

chat.subscribe

Подписка на чат-комнату.

{"event": "chat.subscribe", "chat_id": "uuid"}

Ответ: chat.subscribed

chat.unsubscribe

Отписка от чата.

{"event": "chat.unsubscribe", "chat_id": "uuid"}

chat.send

Отправка сообщения в чат.

{
  "event": "chat.send",
  "chat_id": "uuid",
  "content": "текст сообщения",
  "sender_type": "human|agent|system|bridge",
  "sender_id": "optional-uuid",
  "sender_name": "Имя отправителя"
}

Сообщение сохраняется в БД и broadcast'ится всем подписчикам чата.

agent.heartbeat

Пинг от агента (статус).

{"event": "agent.heartbeat", "status": "idle|busy"}

Ответ: agent.heartbeat.ack

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

auth.ok

{"event": "auth.ok", "init": {}}

chat.subscribed

{"event": "chat.subscribed", "chat_id": "uuid"}

chat.message

Новое сообщение в чате (broadcast всем подписчикам).

{
  "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

{"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