Protokół komunikacji

Pipe v0.50.5

Opis#

Backend nasłuchuje równocześnie na:

1. Unix socket (/tmp/vps-agent.sock) – dla klientów na tym samym serwerze (Telegram bot)
2. TCP 127.0.0.1:7379 – dla SSH tunnel z laptopa (CLI)

Komunikacja odbywa się przez prosty protokół JSON lines (jedna linia JSON = jedna wiadomość). W trybie Kubernetes dostęp do portu TCP daje kubectl port-forward svc/pipe 7379:7379.

Format wiadomości#

Żądanie – wiadomość użytkownika#

{
  "message": "tekst wiadomosci",
  "session_id": "uuid-per-uzytkownik",
  "interface": "cli:<user>|telegram:<user_id>|web:<user>",
  "token": "tajny-token",
  "attachments": [{"name": "zrzut.png", "mime": "image/png", "data": "<base64>"}]
}

attachments jest opcjonalne (pliki, zdjęcia, zrzuty ekranu); z załącznikami message może być puste. Limity: 10 MB na plik, 20 MB i 10 plików na wiadomość – przekroczenie albo zły base64 kończy się ramka błędu bez wywołania agenta. Rodzaj backend ustala z zawartości: obraz idzie do modelu jako image_url, tekst jest wklejany do wiadomości (po redakcji sekretów), inne pliki zapisuje w DATA_DIR/uploads/ i podaje agentowi ścieżkę. Linia żądania może mieć do 32 MiB (READ_LIMIT serwera).

Żądanie – potwierdzenie operacji#

{
  "confirm": true,
  "session_id": "uuid-per-uzytkownik",
  "token": "tajny-token"
}

Żądanie – komenda klienta#

Komendy "/" klientów (Telegram, CLI) wysyłają {"command": ...}:

{
  "command": "run_skill",
  "session_id": "uuid-per-uzytkownik",
  "interface": "cli:kuba",
  "name": "odnow_certyfikat",
  "args": "tylko dla example.com",
  "token": "tajny-token"
}

Treść wiadomości dla agenta (scan_server, run_skill, investigate, akcja message ze skrzynki) buduje backend – klient wysyła tylko komendę. Wiadomości zbudowane przez backend nie uczą VIBE. Pole command skilla to nazwa zgodna z zasadami Telegrama (małe litery, cyfry, _, do 32 znaków). Jest puste, gdy nazwa skilla jest zarezerwowana (status, mapa, server, skille, katalogi, vibe, alerty, cele, rutyny, zmiany, wykres, zdrowie, raport, koszt, cofnij, dziennik, audyt, ...) albo po skróceniu koliduje z innym skillem.

Odpowiedź#

{
  "response": "tekst odpowiedzi",
  "status": "ok|confirm|error",
  "done": false
}

Serwer wysyła wiele linii JSON (streaming). Ostatnia linia ma "done": true. Ramka może zawierać dodatkowo (wtedy response jest pusty, więc starsi klienci ją pomijaja):

Załącznik – plik dla użytkownika, np. diagram:

{"response": "", "status": "ok", "done": false, "attachment": {
  "name": "mapa-infrastruktury.png", "mime": "image/png", "caption": "Mapa infrastruktury",
  "data": "<base64>", "source": "<kod Mermaid>", "text": "<podglad ASCII albo pusty>"}}

Postęp – status pośredni (np. co robi worker), do pokazania na bieżąco, nie wchodzi do odpowiedzi:

{"response": "", "status": "ok", "done": false, "event": {"type": "progress", "text": "web-1 $ uptime", "source": "worker:web-1"}}

Ramki z diagramami mają setki KB – klient musi czytać linie z większym limitem niż domyślne 64 KiB asyncio (open_connection(..., limit=32 * 1024 * 1024)).

Zdarzenia czuwania (subscribe)#

Po {"command": "subscribe"} serwer wysyła {"event": {"type": "subscribed", "lang": "pl|en", "lang_chosen": bool, "view": "simple|tech", "view_chosen": bool, "ts": 1761679200.5}} (lang_chosen – język wybrano komendą language, klient powinien go przejąć; view_chosen – tak samo dla widoku), a potem, bez done:

{"response": "", "status": "ok", "done": false, "event": {"type": "language", "lang": "en", "at": "..."}}

(język Pipe zmieniony z dowolnego kanału – klient przełącza swoje komunikaty; zdarzenie nie trafia do historii alerts; tak samo {"type": "view", "view": "simple"} po zmianie widoku)

{"response": "", "status": "ok", "done": false, "event": {
  "type": "alert", "id": "3f2a9c1d0b", "key": "disk:/", "severity": "warning|critical",
  "title": "Dysk / zapelniony w 93%", "detail": "wolne 3.1 GB z 40 GB (/dev/sda1)",
  "since": "2026-09-24 14:02", "state": "new|resolved|event", "history": "", "at": "2026-09-24 14:02"}}

{"response": "", "status": "ok", "done": false, "event": {
  "type": "routine", "name": "poranny-przeglad", "status": "OK|PROBLEM", "report": "...", "at": "..."}}

{"response": "", "status": "ok", "done": false, "event": {
  "type": "reminder", "id": "6d1546", "kind": "message|task", "text": "...", "report": "",
  "to": "telegram:123", "set_at": "2026-10-01 20:02", "due": "2026-10-01 20:02:42", "at": "..."}}

{"response": "", "status": "ok", "done": false, "event": {
  "type": "activity", "id": "<id wywolania narzedzia>", "phase": "start|wait|end", "tool": "execute_command",
  "label": "docker restart web", "nodes": ["c:web"], "ok": null, "entry": "", "workers": {},
  "output": "web", "full": "...", "code": 0, "auto": true}}

Zdarzenia activity dostaje każdy klient w strumieniu rozmowy (poza rola viewer) – mówią, co agent robi i na których węzłach schematu (graph). wait = czeka na potwierdzenie; end ma ok (true/false/null po odmowie) i entry – identyfikator wpisu dziennika, gdy zmiana została wykonana. Przy komendach (execute_command, remote_exec, git_command, cron_manage, write_file) end niesie też wycinek wyniku: output (do 3 linii: przy błędzie linie z błędem i ostatnia, przy sukcesie koniec, plus alarm bezpiecznika), full (do 60 linii / 4000 znaków, do rozwinięcia) i code (kod wyjścia). To ten sam wynik, który dostał model, już po redakcji sekretów; w widoku prostym tych pól nie ma. auto: true – zmiana wykonana bez pytania (samodzielność, docs/security.md). Klient, który zna tylko progress, może zdarzenia activity pominąć.

to to interfejs, który ustawił przypomnienie – klient decyduje, komu je pokazać. Dla kind: task pole report zawiera raport workera.

{"response": "", "status": "ok", "done": false, "event": {
  "type": "digest", "title": "Raport vps1 -- 29.09.2026 07:00", "text": "<calosc jako tekst>",
  "sections": [{"title": "Stan", "lines": ["..."]}, {"title": "Zmiany od wczoraj", "lines": ["..."]}],
  "attachment": {"name": "wykres-load.png", "mime": "image/png", "data": "<base64>", "...": "..."}, "at": "..."}}

{"type": "investigation", "key", "title", "report", "auto", "alert_id", "severity", "fix_message"} – ustalenia workera, który sam zbadał krytyczny alert czuwania (AUTO_INVESTIGATE) albo alert z webhooka (WEBHOOK_INVESTIGATE=1); obie drogi to jedno Watcher.auto_investigate(), a fix_message to treść przycisku Napraw. history w alercie – ostatnie wystąpienie tego samego problemu (pamięć incydentów).

{"type": "insight", "key", "kind", "severity": "info|warning", "title", "text"} – podpowiedź bez LLM (prognoza zapełnienia dysku, miejsce do odzyskania, restarty kontenera, czekający restart serwera, rosnący RAM). {"type": "notice", "title", "text"} – podsumowanie tego, co czekało w ciszy nocnej. {"type": "login", "id", "code", "device", "ip", "title", "text"} – ktoś przed stroną /web prosi o dostęp; przyciski skrzynki (Wpuść, Tylko podgląd, Odrzuć) wołają komendę web. Zawsze z powiadomieniem, tylko dla administratorów.

Skrzynka. Zdarzenia alert, insight, digest, welcome, routine, investigation i notice trafiają do skrzynki i mają dodatkowo feed_id, push (czy powiadomić teraz: poziom, cisza nocna, limit podpowiedzi), held (czeka na koniec ciszy) i actions (przyciski: index, label, kind, admin...). Klient powiadamia tylko przy push: true, a przycisk wysyła feed_act z feed_id i index. Brak push (starszy backend) = powiadom.

{"type": "approval", "id", "command", "target", "requested_by", "reason", "plan", "status"} – zewnętrzny agent (MCP) czeka na zgodę administratora; klient pokazuje przyciski i wysyła approve.

{"type": "welcome", "title", "sections", "score", "grade", "text", "attachment"?} – raz po instalacji, gdy podłączy się pierwszy subskrybent.

state: new – nowy albo eskalowany alert, resolved – problem minął, event – zdarzenie jednorazowe (nowy publiczny port, zatrzymany kontener). investigate z id prosi agenta o zbadanie alertu. Klucze alertów mają prefiks grupy: disk:, memory, load, container:, port: (co WATCH_INTERVAL) oraz cert:, site:, dns:, backup: (sprawdzenia bez konfiguracji, co CHECKS_INTERVAL). vuln:system – pilne podatności z poprawką w pakietach systemu, vuln:images – w obrazach kontenerów, vuln:servers – na zdalnych serwerach (cele ssh), vuln:apps – krytyczne w zależnościach aplikacji (trwałe; wysyłane ponownie, gdy dojdzie nowa). hook:<zrodlo>:<nazwa> – alerty z webhooków (trwałe do komunikatu resolved). auth:ssh (seria nieudanych logowań) jest trwały; security:<sekcja>:<klucz>, auth:breach:... i auth:login:... to zdarzenia jednorazowe. digest przychodzi raz dziennie o DIGEST_TIME.

Autoryzacja tokenem#

Pole token jest wymagane, gdy skonfigurowano jakikolwiek token: AGENT_TOKEN (rola admin), AGENT_VIEWER_TOKEN (rola viewer) albo tokeny klientów (python3 -m backend.tokens add NAZWA --role admin|viewer, w data/tokens.json sam skrót SHA-256). Bez żadnego tokenu backend przyjmuje każde żądanie (rola admin).

Rola viewer (tylko odczyt): {"confirm": true} i undo z execute są odrzucane, narzędzia zmieniające stan zwracają modelowi odmowę (klient nie dostaje pytania o TAK). Sesja należy do tożsamości, która ją założyła (token admina, viewera albo nazwany token) – żądanie z innym tokenem i tym samym session_id dostaje Ta sesja nalezy do innego klienta.

Token jest sprawdzany dla każdego typu żądania – również dla potwierdzeń (confirm), żeby nieuwierzytelniony klient nie mógł zatwierdzić operacji oczekującej w cudzej sesji. Przy błędnym tokenie backend odpowiada:

{"response": "Blad: Nieprawidlowy token autoryzacji.", "status": "error", "done": true}

Stany odpowiedzi#

Przebieg sesji#

1. Klient nawiązuje połączenie (Unix socket lub TCP)
2. Klient wysyła żądanie (linia JSON + \n)
3. Serwer odpowiada jedna lub wieloma liniami JSON
4. Ostatnia linia ma "done": true
5. Jeśli "status": "confirm" – klient pyta użytkownika o potwierdzenie
6. Klient wysyła {"confirm": true|false, "session_id": "..."}
7. Serwer kontynuuje przetwarzanie i wysyła kolejne odpowiedzi

Implementacja w Pythonie#

import asyncio
import json

async def chat_with_agent(message: str, session_id: str) -> list[dict]:
    reader, writer = await asyncio.open_unix_connection("/tmp/vps-agent.sock", limit=32 * 1024 * 1024)
    
    request = {"message": message, "session_id": session_id, "interface": "my-client"}
    writer.write(json.dumps(request).encode() + b"\n")
    await writer.drain()
    
    responses = []
    while True:
        raw = await reader.readline()
        resp = json.loads(raw)
        if resp.get("attachment"):
            save(resp["attachment"])            # np. base64 -> plik PNG
        elif resp.get("event"):
            show_progress(resp["event"])
        else:
            responses.append(resp)
        if resp.get("done"):
            break
    
    writer.close()
    return responses

Wymagania dla nowych klientów#

• Jeden session_id per użytkownik (np. str(user_id))
• Wysyłaj interface (<klient>:<uzytkownik>) – identyfikuje użytkownika w audit logu i w VIBE
• Obsłuż status confirm – zapytaj użytkownika i wyślij odpowiedź
• Obsłuż attachment (pokaż obraz albo zapisz plik) i event typu progress (pokaż na bieżąco)
• Czytaj linie z limitem >= 32 MiB
• Obsłuż długie odpowiedzi – podziel na mniejsze wiadomości jeśli platforma ma limit
• Alerty: osobne, trwałe połączenie z subscribe i ponawianiem po rozłączeniu; wyślij "since" z ts ostatniego zdarzenia, które widziałeś, a serwer najpierw dośle to, co cię ominęło (np. wynik /aktualizuj, który przychodzi zaraz po restarcie backendu). pipe web robi to przez id: / Last-Event-ID w SSE

Webhooki (HTTP)#

Osobny port (WEBHOOK_PORT, domyślnie wyłączony), przyjmuje alerty z innych systemów:

POST /hook/alertmanager | /hook/grafana | /hook/uptime-kuma | /hook/github | /hook/generic
Authorization: Bearer <WEBHOOK_TOKEN>        (albo ?token=..., albo podpis X-Hub-Signature-256 GitHuba)
Content-Type: application/json

202 {"ok": true, "alerts": 2, "events": 1}
GET /health -> 200 {"ok": true}

Format ogólny (/hook/generic): {"title", "message", "severity": "critical|warning", "status": "firing|resolved", "name"}. Limit tresci 1 MiB. Bez WEBHOOK_TOKEN serwer webhooków nie startuje.

Popraw tę stronę na GitHubie