Releul de host-uri

Releul de host-uri permite oricărui client al tău să execute un vocabular mic și fix de operații pe unul dintre desktopurile tale care are aplicația codai desktop deschisă. Desktopul ține o conexiune SSE de ieșire către gateway și se anunță ca host; un solicitant face POST cu un exec și gateway-ul îl retransmite, apoi retransmite răspunsul înapoi. Nimic nu este persistat, nimic nu ascultă pe desktop și în v1 host-ul și solicitantul trebuie să aparțină aceluiași utilizator.

   telefon / browser / script               gateway                       desktop (host)
   ──────────────────────────             ─────────                      ───────────────
   POST /v1/hosts/:dev/exec  ───────▶  rendezvous după device id ─────▶  event: exec  (pe SSE-ul lui)
        { op, args }                                                       rulează op-ul local
   200 { ok, result }        ◀───────  rendezvous după req_id    ◀─────  POST /v1/hosts/exec/:reqId/result

Această suprafață este servită de https://ai.codai.ro și nu face parte din specificația publicată Shared Sessions v1; tratează-o ca remote sessions v1.

Ce desktopuri sunt online

curl https://ai.codai.ro/v1/hosts -H "Authorization: Bearer $CODAI_API_KEY"

{
  "hosts": [
    {
      "device_id": "1c2f…-uuid",
      "name": "Work laptop",
      "platform": "desktop",
      "os": "windows",
      "hostname": "DRAGOS-PC",
      "roots": ["E:\\gh\\codai", "C:\\Users\\dragos\\Documents"],
      "since": 1790160000000,
      "last_seen": 1790160045000
    }
  ]
}

Apar doar dispozitivele tale, cele văzute cel mai recent întâi. since și last_seen sunt milisecunde epoch; un host dispare din listă 45 de secunde după ultimul heartbeat. roots sunt directoarele pe care desktopul le va lăsa operațiile pe fișiere să le atingă.

Rulează ceva pe un host

POST /v1/hosts/:deviceId/exec — necesită cheia ta și un header x-codai-device care identifică solicitantul.

curl https://ai.codai.ro/v1/hosts/1c2f…/exec \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "x-codai-device: $(uuidgen)" -H "x-codai-device-platform: cli" \
  -H "Content-Type: application/json" \
  -d '{ "op": "shell", "args": { "cmd": "git status --short", "cwd": "E:\\gh\\codai" }, "timeout_ms": 30000, "label": "docs check" }'

Răspunsul — răspunsul host-ului, exact așa cum a venit:

{
  "req_id": "c0de…-uuid",
  "ok": true,
  "result": { "code": 0, "stdout": " M apps/docs/content/docs/en/sessions/hosts.mdx\n", "stderr": "", "truncated": false, "timed_out": false, "duration_ms": 412 },
  "error": null
}

Un eșec pe partea host-ului — o cale în afara roots, un argument greșit, o comandă care nu a putut porni — este tot HTTP 200 cu ok: false și error setat. Doar problemele releului sunt erori HTTP:

Operații

Desktopul implementează fiecare op cu propriile comenzi verificate de permisiuni; căile de fișiere trebuie să fie sub roots-urile host-ului.

Construiește un host

Ai nevoie de această secțiune doar dacă îți scrii propriul host (aplicația codai desktop este deja unul).

event: hello
data: {"device_id":"1c2f…","heartbeat_ms":15000}

event: ping
data: {"t":1790160045000}

event: exec
data: {"req_id":"c0de…","op":"shell","args":{"cmd":"git status --short","cwd":"E:\\gh\\codai"},"timeout_ms":30000,"label":"docs check","from_device_id":"9a0b…","ts":1790160050000}

curl -X POST https://ai.codai.ro/v1/hosts/exec/c0de…/result \
  -H "Authorization: Bearer $CODAI_API_KEY" -H "x-codai-device: 1c2f…" \
  -H "Content-Type: application/json" \
  -d '{ "ok": true, "result": { "code": 0, "stdout": "…", "stderr": "", "truncated": false, "timed_out": false, "duration_ms": 412 } }'