h1. Agent Protocol

Протокол взаимодействия между Rust Agent (на Windows-машинах) и NestJS API (Control Plane).

h2. Транспорт

• Протокол: WebSocket (WSS)
• Endpoint: @wss://app.reckue.com/ws/agent@
• Формат сообщений: JSON

h2. Аутентификация

• Агент подключается с машинным токеном (JWT)
• Токен передаётся при WebSocket handshake в заголовке @Authorization: Bearer @
• Токен выдаётся при регистрации агента через API

h2. Типы сообщений

h3. Agent -> Server

|. Тип |. Описание |_. Payload |
| @register@ | Регистрация агента при подключении | @{ hostname, os, version, capabilities }@ |
| @heartbeat@ | Подтверждение активности | @{ timestamp, cpu_usage, memory_usage }@ |
| @session_output@ | Вывод терминальной сессии | @{ session_id, data (base64) }@ |
| @session_status@ | Статус сессии изменился | @{ session_id, status: "started" / "stopped" / "error", exit_code? }@ |

h3. Server -> Agent

|. Тип |. Описание |_. Payload |
| @session_start@ | Запустить новую терминальную сессию | @{ session_id, shell?, cols?, rows? }@ |
| @session_stop@ | Остановить сессию | @{ session_id }@ |
| @session_input@ | Ввод пользователя в сессию | @{ session_id, data (base64) }@ |
| @workspace_init@ | Инициализировать рабочее пространство | @{ workspace_id, config }@ |

h2. Формат сообщения

Каждое сообщение — JSON-объект:

{
  "type": "message_type",
  "id": "uuid-v4",
  "timestamp": "2026-01-15T12:00:00Z",
  "payload": { ... }
}

h2. Heartbeat

• Агент отправляет @heartbeat@ каждые 30 секунд
• Если сервер не получает heartbeat в течение 90 секунд, агент считается оффлайн
• Сервер может отправить @ping@, агент должен ответить @pong@

h2. Reconnect (переподключение)

Стратегия: exponential backoff

|. Попытка |. Задержка |
| 1 | 1 секунда |
| 2 | 2 секунды |
| 3 | 4 секунды |
| 4 | 8 секунд |
| 5 | 16 секунд |
| 6 | 32 секунды |
| 7+ | 60 секунд (максимум) |

• После успешного подключения счётчик сбрасывается
• При переподключении агент повторно отправляет @register@

h2. Пример сценария

Агент запускается на Windows-машине¶

Агент подключается к @wss://app.reckue.com/ws/agent@ с JWT-токеном¶

Агент отправляет @register@ с информацией о машине¶

Сервер подтверждает регистрацию¶

Агент начинает отправлять @heartbeat@ каждые 30 секунд¶

Пользователь в браузере открывает терминал¶

Сервер отправляет агенту @session_start@¶

Агент создаёт PTY-процесс и отправляет @session_status: started@¶

Пользователь вводит команды -> сервер отправляет @session_input@ -> агент пишет в PTY¶

PTY выдаёт вывод -> агент отправляет @session_output@ -> сервер передаёт в браузер¶

Пользователь закрывает терминал -> сервер отправляет @session_stop@¶

Агент завершает PTY-процесс и отправляет @session_status: stopped@¶

h2. Безопасность

• Все соединения через WSS (TLS)
• JWT-токены с ограниченным сроком действия
• Каждый агент привязан к конкретному пользователю/организации
• Данные сессий передаются в base64 (бинарный контент)