Agent Protocol¶

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

Транспорт¶

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

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

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

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

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

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

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

Агент запускается на 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

Files (0)