Локальний API агента

Демон Sentinel надає версійований API HTTP/JSON через локальний сокет Unix /run/simaai-sentinel/api.sock. Він не прослуховує жоден TCP-порт. API і термінальний інтерфейс використовують той самий кеш і заблоковане сховище контрольних точок, тому трасування, запущені агентом, одразу видно в інтерфейсі користувача та CLI.

curl --unix-socket /run/simaai-sentinel/api.sock http://localhost/v1/health

Кінцеві точки

Метод і шлях	Призначення
GET /v1/health	Версія, актуальність, кількість зразків і показників, помилки та активне трасування.
GET /v1/cache	Повний документ кешу в реальному часі.
GET /v1/metrics	Визначення показників, одиниці вимірювання, описи та порогові значення.
GET /v1/samples/latest	Останні значення показників із часовими мітками.
GET /v1/traces/active	Активне трасування або null.
POST /v1/traces	Запустити іменоване трасування.
POST /v1/traces/stop	Зупинити та зберегти активне трасування.
POST /v1/traces/{id}/stop	Зупинити активне трасування, лише якщо його ID досі збігається.
GET /v1/runs	Перелік зведень активних і завершених запусків.
GET /v1/runs/{name-or-id}	Отримати збережений запуск і необроблені зразки.
GET /v1/compare?runs=A,B	Порівняти два або більше запусків; перший із них є базовим.
GET /v1/peripherals	Підключені периферійні пристрої, з пам’яті.
POST /v1/peripherals/refresh	Повторно сканувати, а потім повернути новий каталог.

Приклад запиту на запуск:

curl --unix-socket /run/simaai-sentinel/api.sock \
  -H 'Content-Type: application/json' \
  -d '{"name":"baseline","note":"before optimization","tags":["compiler-v1"]}' \
  http://localhost/v1/traces

Зупинити активне трасування:

curl --unix-socket /run/simaai-sentinel/api.sock \
  -X POST http://localhost/v1/traces/stop

Клієнти, які спершу прочитали активне трасування, мають вказувати його ID під час зупинки:

curl --unix-socket /run/simaai-sentinel/api.sock \
  -X POST http://localhost/v1/traces/20261004T120000.000Z-baseline/stop

Умовна форма повертає HTTP 409 і нічого не зупиняє, якщо інший клієнт замінив трасування. Порівняння ID і зупинка виконуються під тим самим блокуванням сховища запусків.

Імена мають бути унікальними, і активним може бути лише одне трасування. Конфліктні операції життєвого циклу повертають HTTP 409. Невідомі запуски та маршрути повертають HTTP 404. Некоректні запити повертають HTTP 400. Для недоступних показників відповіді використовують JSON null. Відповіді порівняння за замовчуванням містять метадані запусків, статистику та дельти відносно базового запуску. Додавайте raw=1 лише тоді, коли потрібні зразки з часовими мітками.

Периферійні пристрої

Потік виявлення сканує периферійні пристрої плати під час запуску демона, коли ядро повідомляє про зміну пристроїв, а також за запитами на оновлення. Провайдери пристроїв лише читають інтерфейси ядра й ніколи не відкривають потік даних. Щоб прочитати список оверлеїв U-Boot для блоку board, кожне сканування також запускає fw_printenv -n dtbos від root. Він ніколи не змінює середовище, але бере його блокування, що створює /var/lock/fw_printenv.lock. GET /v1/peripherals повертає останній результат:

{"revision": 1791155282460, "observed_at": "2026-10-04T23:08:02.460Z",
 "board": {"model": "SiMa.ai Modalix SoM 16Gig Board", "configured_cameras": [...], ...},
 "devices": [{"type": "camera", "id": "camera:v4l2:3f2a9c0d41b7e650", ...}],
 "errors": [{"provider": "camera.v4l2", "code": "io.permission_denied", "reason": "..."}]}

Поле	Значення
revision	Змінюється щоразу, коли змінюються board, devices або errors. Під час запуску демона воно починається з випадкового значення, тому перезапуск чи зміна системного годинника навряд чи повторять попереднє значення; порівнюйте його лише на рівність. Воно залишається меншим за 2^52, тому є точним у засобах читання JSON, які використовують числа типу double.
observed_at	Час початку сканування, на якому ґрунтується цей результат; null, доки не завершиться перше сканування.
board	Як плату налаштовано для камер: модель, оверлеї, які застосовує U-Boot, камери, налаштовані деревом пристроїв (кожна з id камери camera.mipi, яка є її сенсором, якщо така камера є в каталозі), і сенсори, які підтримують встановлені оверлеї. Зчитується під час того самого сканування, що й devices; відсутній, доки не завершиться перше сканування. Див. конфігурація камер плати.
devices	Один об’єкт на кожен пристрій, позначений тегом type. id стабільний між повторними підключеннями до того самого порту й ніколи не є іменем /dev/videoN.
errors	Провайдери, що завершилися збоєм під час останнього сканування, і поля блоку board, які не вдалося прочитати повністю (провайдер board.<field>, наприклад board.overlays). Пристрої такого провайдера з його останнього успішного сканування залишаються в devices, а невдалий запуск fw_printenv зберігає останній список оверлеїв. hotplug.unavailable означає, що uevent ядра неможливо отримувати, тому повторні сканування відбуваються лише за запитом на оновлення.

Sentinel повідомляє лише апаратні факти. Чи підтримує застосунок пристрій або режим, вирішує сам застосунок.

POST /v1/peripherals/refresh чекає на сканування, яке починається після запиту, і повертає HTTP 200 із цим каталогом — тим самим документом, що й GET. Одночасні запити на оновлення використовують спільні сканування. Після кожного сканування потік виявлення робить паузу в 1 секунду, тож запит на оновлення може чекати до цього часу, перш ніж почнеться його сканування, а повторні запити не можуть тримати виявлення постійно запущеним. Він повертає HTTP 504, якщо сканування не завершується протягом 10 секунд, і HTTP 429, коли вже очікують 8 запитів на оновлення. Обидва маршрути повертають HTTP 503, якщо виявлення вимкнено (--no-peripherals) або його зупинено.

simaai-sentinel peripherals виводить той самий результат у вигляді таблиці; додайте --json, щоб отримати необроблений документ, і --refresh, щоб спочатку виконати повторне сканування.

Записи пристроїв описано окремо для кожного типу: USB-камери, Камери MIPI CSI-2, мікрофони. Блок board описано на сторінці конфігурація камер плати.

peripherals/catalog-example.json — це повна відповідь від DevKit, у якій для USB-камери залишено по одному режиму на кожен формат. Її блок board переписано з DevKit, а не захоплено з реальної відповіді. Тест Sentinel перевіряє її на відповідність схемі, тож клієнти можуть тестуватися з її допомогою.

Безпека та паралельний доступ

Сокет є локальним для DevKit, і Sentinel ніколи не відкриває його для віддаленого доступу. Він навмисно доступний локальним користувачам, щоб такі клієнти, як Insight і CLI, працювали без root. Операції керування запускають і зупиняють трасування телеметрії та запитують повторне сканування периферійних пристроїв; API не видаляє запуски, не виконує робочі навантаження й не змінює апаратне забезпечення. Повторне сканування лише читає дані, а пауза в 1 секунду після кожного сканування обмежує обсяг роботи, який можуть спричинити запити на оновлення. Якщо локальний користувач постійно тримає 8 запитів на оновлення в очікуванні, інші запити на оновлення повертають HTTP 429, а GET і далі працює. Віддалений доступ має забезпечувати автентифікований проксі Kerrigan/Fleet Manager, а не переадресація цього сокета чи додавання неавтентифікованого TCP-слухача.

Запис у кеш використовує атомарне перейменування. Операції із запусками використовують те саме ексклюзивне блокування файлу, що й CLI, TUI та реєстратор демона. Якщо клієнт не повинен зупинити трасування, яке замінило те, що він бачив, використовуйте маршрут зупинки з ID.

Навичка агента

Під час встановлення згенерований скрипт встановлення Sentinel запускає sima-cli playbooks install з точним Git-комітом Sentinel, з якого було зібрано пакет. Це узгоджує ревізії середовища виконання та навички без додавання вкладених ресурсів навички до артефакту Vulcan. Менеджер playbook встановлює навичку для кожного підтримуваного агента й записує її вихідний коміт у локальний реєстр.

Встановлення Sentinel на DevKit завжди починається з sima-cli neat install sentinel, тому окремий крок встановлення навички там зазвичай не потрібен. Щоб використовувати навичку Sentinel у середовищі, де пакет DevKit не встановлено (наприклад, у контейнері SDK або на робочій станції розробника), встановіть навичку безпосередньо з GitHub за допомогою sima-cli цього середовища:

sima-cli playbooks install gh:sima-neat/sentinel/skills/use-sentinel

Щоб протестувати ревізію до того, як вона потрапить у main, додайте Git ref:

sima-cli playbooks install --force \
  gh:sima-neat/sentinel/skills/use-sentinel@feature/checkpoint-run-comparison

Оновлення та видалення навички й надалі здійснюється через sima-cli playbooks.