Reckue Dev

# Agent Protocol

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

## Транспорт

- **Протокол:** WebSocket (WSS)

- **Endpoint:** `wss://app.reckue.com/ws/agent`

- **Формат сообщений:** JSON

## Аутентификация

- Агент подключается с машинным токеном (JWT)

- Токен передаётся при WebSocket handshake в заголовке `Authorization: Bearer <token>`

- Токен выдаётся при регистрации агента через API

## Типы сообщений

### 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, exit_code? }` |

### 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 }` |

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

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

```json

{

  "type": "message_type",

  "id": "uuid-v4",

  "timestamp": "2026-01-15T12:00:00Z",

  "payload": { ... }

}

```

## Heartbeat

- Агент отправляет `heartbeat` каждые **30 секунд**

- Если сервер не получает heartbeat в течение **90 секунд**, агент считается оффлайн

- Сервер может отправить `ping`, агент должен ответить `pong`

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

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

| Попытка | Задержка |

| --- | --- |

| 1 | 1 секунда |

| 2 | 2 секунды |

| 3 | 4 секунды |

| 4 | 8 секунд |

| 5 | 16 секунд |

| 6 | 32 секунды |

| 7+ | 60 секунд (максимум) |

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

- При переподключении агент повторно отправляет `register`

## Пример сценария

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

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

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

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

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

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

7. Сервер отправляет агенту `session_start`

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

9. Пользователь вводит команды → сервер отправляет `session_input` → агент пишет в PTY

10. PTY выдаёт вывод → агент отправляет `session_output` → сервер передаёт в браузер

11. Пользователь закрывает терминал → сервер отправляет `session_stop`

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

## Безопасность

- Все соединения через WSS (TLS)

- JWT-токены с ограниченным сроком действия

- Каждый агент привязан к конкретному пользователю/организации

- Данные сессий передаются в base64 (бинарный контент)