# Справочник API веб пилота

Редакция 2026-09-15

Статус: Редакция 15 сентября 2026 года; состояние функций уточняется документом готовности

## Сервер и конфигурация

`main-enterprise-web` слушает только loopback (по умолчанию порт 4452). HTTPS и
домен обслуживает обратный прокси. `YADRO_WEB_CONFIG` указывает на закрытый JSON
конфигурации, `YADRO_WEB_ASSETS` — каталог пяти статических файлов. Конфигурация
перечитывается при каждом запросе; секреты нельзя размещать в каталоге сайта.

Конфигурация: `origin` (точный HTTPS origin), `coreUrl` (HTTP loopback Двигателя),
`modelReady` (готовность подтверждённого подключения модели), `accounts` — записи
`id`, `label`, `passwordHash`, опциональные `staffToken` и `operatorToken`.
`passwordHash` — SHA-256 случайного длинного кода доступа, а не обычного короткого
пароля. Это локальные демонстрационные учётные записи, не корпоративный SSO.

## Вход и сеансы
Каждый интерфейс имеет самостоятельный префикс `/yadro/staff/api/` или
`/yadro/helm/api/` и отдельную cookie. POST `session` принимает `{login,password}`,
требует точный `Origin`, JSON и `X-Yadro-Web: 1`. Ответ и GET `session`:
`{user:{id,label},csrf,modelReady}`. Все изменения требуют `X-Yadro-CSRF` из
текущей сессии, JSON и точный Origin. DELETE `session` с телом `{}` завершает сеанс.

Сеансы существуют только в памяти: максимум 8 часов, 30 минут бездействия.
Перезапуск завершает все сеансы. Cookies: Secure, HttpOnly, SameSite=Strict,
Path=/, префикс __Host. Изменение учётной записи, ключей или привязки Двигателя
отзывает сеанс. На каждом запросе проверяются действующие права в Двигателе.
Браузер не получает bearer-ключей и не выбирает actor/user или адрес Двигателя.

## Маршруты Штата

- GET `agents`, `snapshot?agent_ref=…`, `history?agent_ref=…`, `status?agent_ref=…`.
- GET `poll?cursor=…&wait=…` (ожидание максимум 25 секунд) отдаёт только сообщения
  и статусы печати. Команды компьютера и браузера не передаются.
- POST `message`: `{agent_ref,text,client_message_id,attachments?}`. Без готовой
  модели возвращает 503; повторное сообщение не инициируется веб-шлюзом.
- POST `interrupt`: `{agent_ref}`.
- POST `ack`: `{command_ids:[…]}` — только сообщения, ранее выданные этой сессии.

## Маршруты Штурвала

- GET `agents`, `access`, `agent-state?agent_id=…`.
- POST `agent-changes/prepare`: `{agentId,expectedRevision,reason,change}`,
  где `change` — `{kind:"settings.update",patch:{name?,description?,language?}}`.
- POST `agent-changes/commit`: `{operationId,digest}` — только предложение,
  подготовленное в текущей сессии. Двигатель дополнительно проверяет владельца,
  ревизию, срок и подтверждение.
- GET `agent-changes/<operationId>` читает результат собственного предложения.
  В случае неопределённого ответа на запись необходимо читать статус;
  веб-шлюз автоматически не повторяет изменение.

## Ограничения транспорта
Другие маршруты, поля и произвольные адреса запрещены. Вход и ответ ограничены
4 МиБ; параллельные API-запросы, входы, число сессий и предложений ограничены.
Upstream timeout — 35 секунд с ограничением и заголовков, и тела; перенаправления
не выполняются. Ответы не кэшируются; статические файлы разрешены точным списком,
CSP не разрешает inline-скрипты и встраивание в чужие страницы.