Kontrakt
Sidecar to serwer gRPC na gnieździe Unix. Nasłuchuj na ścieżce z NEBO_APP_SOCK i zaimplementuj apps.v0.UIService. Nebo wywołuje HandleRequest dla każdego żądania; HealthCheck i Configure należą do usługi, ale obecnie nie są wywoływane. Gniazdo musi pojawić się w czasie startup_timeout z manifestu, który domyślnie wynosi 10 sekund i może wynosić najwyżej 120.
syntax = "proto3";
package apps.v0;
service UIService {
rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
rpc Configure(SettingsMap) returns (Empty);
rpc HandleRequest(HttpRequest) returns (HttpResponse);
}
message HttpRequest {
string method = 1; // GET, POST, PUT, DELETE, ...
string path = 2; // relative to /apps/{id}/api/
string query = 3; // raw query string
map<string, string> headers = 4;
bytes body = 5;
}
message HttpResponse {
int32 status_code = 1;
map<string, string> headers = 2;
bytes body = 3;
} Sidecary działają na macOS i Linuksie.
Gdzie Nebo szuka pliku binarnego
W folderze aplikacji Nebo używa pierwszego istniejącego z poniższych:
- Pliku o nazwie
binary - Pliku o nazwie
app - Pierwszego pliku w
tmp/ - Pierwszego pliku w
bin/ - Pierwszego pliku wykonywalnego w
sidecar/target/release/, do lokalnego programowania
Plik binarny musi być zwykłym plikiem wykonywalnym, a nie dowiązaniem symbolicznym, i mieć najwyżej 500 MB. Opublikowane aplikacje mają go w bin/<name>. Gdy plik zmieni się na dysku, Nebo uruchamia sidecar ponownie.
Środowisko
Sidecar startuje z pustym środowiskiem i tymi zmiennymi:
| Zmienna | Wartość |
|---|---|
NEBO_APP_ID, NEBO_APP_NAME, NEBO_APP_VERSION | Tożsamość aplikacji. |
NEBO_APP_DIR | Folder aplikacji. |
NEBO_APP_SOCK | Gniazdo do nasłuchiwania, <app folder>/<id>.sock. Nebo ustawia jego tryb na 0600. |
NEBO_DATA_DIR | Folder danych aplikacji, <data>/appdata/agents/<id>/. Jest to też katalog roboczy. |
NEBO_API_URL | Lokalne API bota, http://127.0.0.1:<port>. |
NEBO_APP_TOKEN | Token do wywoływania API aplikacji bota. |
PATH, HOME, TMPDIR, LANG, LC_ALL, TZ | Przekazywana bez zmian. |
Standardowe wyjście i standardowe wyjście błędów trafiają do sidecar.log w folderze danych. Standardowe wejście to potok; koniec pliku oznacza, że Nebo zniknęło i sidecar powinien się zakończyć. Sidecar działa we własnej grupie procesów.
Żądania ze strony
Żądanie do /apps/<id>/api/<path>, które strona wysyła przez neboFetch ze ścieżką względną, trafia do HandleRequest z path ustawionym na <path>. Ścieżki zaczynające się od _ są odrzucane. Treść żądania jest ograniczona do 10 MB, a odpowiedzi do 32 MB.
Narzędzia dla pracownika
Zadeklaruj narzędzia w pliku agent.json aplikacji. Każde staje się narzędziem o nazwie app__<app>__<name>, ładowanym, gdy pracownik go potrzebuje. Wywołanie staje się żądaniem do sidecara pod method i path.
"tools": [
{
"name": "list_deals",
"description": "List open deals, optionally filtered by stage.",
"method": "GET",
"path": "/deals",
"input_schema": { "type": "object", "properties": { "stage": { "type": "string" } } }
}
] Wywoływanie Nebo
Sidecar może korzystać z tych samych usług co strona, wywołując $NEBO_API_URL/api/v1/apps/$NEBO_APP_ID/... z nagłówkiem Authorization: Bearer $NEBO_APP_TOKEN.
| Trasa | Działanie |
|---|---|
GET /storage, GET|PUT|DELETE /storage/<key> | Magazyn klucz–wartość aplikacji. |
POST /agents/invoke, POST /agents/stream | Pyta pracownika: {message, agent, data}. Odpowiedzi strumieniowe to zdarzenia wysyłane przez serwer (SSE). |
POST /janus/complete, POST /janus/stream | Bezpośrednie wywołanie modelu: {messages, model, temperature, max_tokens, system}. |
POST /http/proxy | Żądanie zewnętrzne, {url, method, headers, body}, dozwolone przez uprawnienia network: aplikacji. |
GET /identity | Pracownik aplikacji. |
Cykl życia
- Nebo sprawdza gniazdo co trzy sekundy.
- Sidecar, który uległ awarii, uruchamia się ponownie po jednej sekundzie, a odstęp podwaja się do najwyżej 60 sekund. Po pięciu awariach z rzędu zostaje oznaczony jako niedziałający. Sidecar, który działa przez 60 sekund, znów jest uznawany za sprawny.
- Żądanie do zatrzymanego sidecara uruchamia go i czeka do 15 sekund. Żądania GET i HEAD są ponawiane.
- Aby zatrzymać sidecar, Nebo wysyła SIGTERM do jego grupy procesów, a po dwóch sekundach go zabija.