Referința protocolului

Aceasta este suprafața normativă a codai Shared Sessions v1.0.0 așa cum este servită de https://ai.codai.ro. Numele câmpurilor sunt snake_case pe fir; timestamp-urile numite *_at sunt string-uri ISO-8601; ts și last_seen sunt milisecunde întregi de la epoca Unix. JSON Schema-urile pentru fiecare obiect stau în repository-ul protocolului. Frame-urile realtime sunt pe pagina de streaming; share-urile și organizațiile au pagina lor.

Transport și headere

Toate rutele sunt HTTPS sub URL-ul de bază al gateway-ului și sunt JSON dacă nu se spune altfel. Autentificarea este o cheie API Bearer; principalul este utilizatorul căruia îi aparține cheia.

Authorization: Bearer codai_xxxxxxxx

Headere de dispozitiv

Un id de dispozitiv deja înregistrat la alt utilizator este refuzat cu 403 forbidden — Device id is registered to another account. — nu refolosit.

Selectarea v2 pe căi suprapuse

GET /v1/sessions și GET /v1/sessions/:id împart căile cu un API legacy de memorie read-only. Handler-ul de sesiuni partajate este selectat când request-ul poartă x-codai-device sau ?v=2. Trimite mereu x-codai-device; ?v=2 este pentru citiri rapide fără dispozitiv.

Referințe la sesiune

Oriunde o cale conține :id poți trimite fie id-ul UUID de server, fie propriul session_key. Când un session_key se ciocnește între utilizatori, sesiunea ta câștigă.

Obiecte

Session

{
  "id": "5b3e…-uuid",
  "session_key": "phone-7f1c…",
  "owner_user_id": "…-uuid",
  "title": "Book the dentist",
  "created_at": "2026-09-13T10:00:00.000Z",
  "last_event_at": "2026-09-13T10:04:12.512Z",
  "last_seq": 42,
  "executor_device_id": "…-uuid or null",
  "lease_expires_at": "2026-09-13T10:04:40.000Z or null",
  "e2e": false,
  "archived": false
}

session_key este ales de client (telefonul folosește același UUID pe care îl trimite ca x-codai-session-id la inferență); id este atribuit de server. Răspunsurile de listare adaugă role (al tău) și presence_count; răspunsul de detaliu adaugă role, members[], lease și presence[]; shared-with-me adaugă role și share_id.

Device

{
  "id": "…-uuid",
  "name": "Pixel 9",
  "platform": "android",
  "capabilities": ["screen", "local_llm", "terminal", "contacts"],
  "has_push_token": true,
  "lastSeenAt": "2026-09-13T10:04:12.512Z",
  "createdAt": "2026-09-01T08:00:00.000Z"
}

capabilities este o listă liberă de ≤ 64 string-uri de ≤ 64 caractere. Token-ul push nu este returnat niciodată — clienții văd has_push_token. Cele două timestamp-uri camelCase de pe acest obiect fac parte din v1 și nu vor fi redenumite.

Event

{
  "seq": 7,
  "kind": "tool_call",
  "ts": 1757757852512,
  "sender_device_id": "…-uuid",
  "turn_id": "t-…",
  "client_event_id": "c9f2…",
  "payload": { "name": "open_app", "args": { "package": "com.whatsapp" } }
}

• seq este atribuit de server, dens per sesiune, începând de la 1. Clienții nu îl trimit niciodată.
• kind: 1 – 64 caractere, opac pentru server; kind-urile necunoscute nu sunt respinse niciodată. Vocabularul de trace al executorului este turn_start, step_start, req_start, local_gen, tool_start, tool_call, tool_result, ask, ask_resolved, wait_user, deadline, error, usage, turn_end, plus assistant, user și screen_wait, emis de executor.
• ts: ceasul clientului; implicit ora serverului când lipsește.
• payload: orice obiect JSON (implicit {}); { "hide": "<base64>" } în modul E2E.

Kind-uri emise de server:

Control

{
  "id": "ctl-8d1a…",
  "kind": "steer",
  "text": "Use the second search result instead.",
  "turn_id": "t-…",
  "ask_id": null,
  "from_device_id": "…-uuid",
  "target_device_id": null,
  "seq": 8,
  "applied": false,
  "created_at": "2026-09-13T10:04:13.000Z"
}

kind ∈ send | answer | approve | deny | cancel | steer | inject. id este cheia de idempotență a clientului (1 – 128 caractere); text ≤ 100 000 caractere. target_device_id este setat doar de dispatch și este null altfel; un control țintit este destinat acelui singur dispozitiv și orice alt executor ar trebui să-l sară.

Lease

{ "session_id": "…-uuid", "device_id": "…-uuid", "expires_at": "2026-09-13T10:04:40.000Z" }

TTL 30 s; heartbeat la fiecare 10 s. Frame-urile lease realtime folosesc holder_device_id (nullable) în loc de device_id.

Presence

{ "device_id": "…-uuid", "user_id": "…-uuid", "role": "editor", "executor": false, "driving": false, "last_seen": 1757757852512, "online": true, "remote": true }

Efemer, niciodată persistat. remote este calculat pentru apelant și apare doar în GET /v1/sessions/:id; online apare doar în frame-urile presence (false pe frame-ul de plecare).

Share și Org

Vezi partajare și organizații. Share: { id, session_id, principal_type: user|org|link, principal_id, role: viewer|editor|owner, has_token, expires_at, created_by_user_id, created_at } (+ token o singură dată). Org: { id, name, ownerUserId, createdAt } — camelCase pe fir — cu roluri de membru owner | admin | member.

Roluri

1. owner când owner_user_id al sesiunii ești tu.
2. Altfel rolul maxim peste share-urile neexpirate care ți se potrivesc direct, oricărei organizații din care faci parte sau token-ului de link pe care îl prezinți.
3. Altfel niciun rol → 403 not_a_member. Un id necunoscut este 404 not_found.

Rute HTTP

Fiecare mutație urmează validare → autentificare → autorizare → audit → execuție. O validare eșuată este 400 bad_request cu details care descrie câmpurile.

Sesiuni

members[] = { user_id, role, remote, devices: [{ device_id, name, platform, last_seen_at, remote }] }, o intrare per utilizator membru (owner, share-uri directe către utilizatori, membrii share-urilor către organizații și tu, dacă ai venit printr-un link).

Evenimente

IncomingEvent = { kind, ts?, turn_id?, client_event_id?, payload? } — niciodată seq. accepted numără evenimentele stocate nou; duplicatele (după client_event_id) sunt raportate cu seq-ul lor original.

Controls și dispatch

Lease

Dispozitive

Semantica lease-ului

• TTL 30 s, reînnoit prin PUT …/lease la fiecare 10 s. expires_at este returnat la preluare și la fiecare heartbeat.
• Preluarea este compare-and-set. POST …/lease reușește când lease-ul este liber, expirat sau deja deținut de dispozitivul apelant. Dacă alt dispozitiv deține un lease activ → 409 lease_held; deținătorul este numit în message ca (holder_device_id=…).
• Force. { "force": true } (owner) ia un lease activ de la alt dispozitiv. Serverul adaugă un eveniment lease_transferred și îl auditează. Fostul deținător află la următorul heartbeat (409 lease_held, Lease lost to another device.) și trebuie să oprească execuția, să devină viewer și să arate cine conduce.
• Heartbeat pe un lease expirat este 409 lease_held cu Lease expired. și fără deținător.
• Eliberarea este idempotentă: released: false când nu îl dețineai.
• Fiecare preluare/heartbeat/eliberare publică un frame lease și oglindește executor_device_id / lease_expires_at pe sesiune.
• Adăugarea de evenimente sau marcarea unui control ca aplicat fără lease-ul activ → 409 lease_held.

Idempotență

Append optimist. expected_last_seq pe un body de evenimente face adăugarea condiționată: dacă last_seq al sesiunii diferă → 409 seq_conflict și nu se scrie nimic. Alocarea de seq se face într-o singură tranzacție — last_seq este incrementat cu numărul de evenimente noi și acestea sunt inserate ca base+1 … base+n, așa că seq este dens și fără goluri.

Dispatch

Pornește o sarcină pe un dispozitiv anume din orice client editor+. Doar dispozitivele owner-ului pot deține lease-ul, așa că device_id trebuie să aparțină owner-ului — orice altceva este 404 not_found (Target device not found for this session.). Alege id-ul din GET /v1/sessions/:id → members[].devices.

La POST …/dispatch serverul persistă un control send al cărui eveniment-ecou poartă payload.control.target_device_id, îl auditează și — dacă ținta are token push — trimite un mesaj FCM HTTP v1 data-only, high-priority { "type": "dispatch", "session_id", "control_id" }. Push-ul este fail-open: un eșec nu face niciodată request-ul să eșueze; controlul este durabil oricum. pushed: false cu push_reason ∈ no_push_token | no_token | auth_failed | network_error | unregistered | http_<status> înseamnă pus în coadă, nelivrat încă — nu o eroare. La unregistered serverul șterge token-ul push al dispozitivului.

Fluxul de trezire pe dispozitiv: push → pornește executorul headless → GET /v1/devices/me/dispatch (sau GET …/controls?applied=false&target=me, înainte de a deține lease-ul) → POST …/lease (force: true dacă politica permite) → execută send-ul consumat → POST …/control/:cid/applied → bucla normală. Dispatch-ul nu atinge niciodată lease-ul.

Erori

{ "error": { "message": "Another device holds a live executor lease. (holder_device_id=1c2f…)", "type": "invalid_request_error", "code": "lease_held" } }

details este inclus pentru bad_request (rezultatul validării la nivel de câmp). Pentru lease_held și seq_conflict valoarea utilă este încorporată în message; re-GET sesiunea pentru last_seq-ul curent.

Erorile WebSocket pe mesajele up folosesc { v: 1, t: "error", ref?, error: {…} } și includ details.

Limite

Nu există rate limit per rută specific acestei suprafețe; se aplică limitele generale per cheie API ale gateway-ului.

Versionare

Frame-urile poartă v: 1. Câmpurile adăugate nu sunt breaking; un kind nou de eveniment nu este breaking (viewerii ignoră kind-urile necunoscute). Nimic din ce este listat aici nu este eliminat sau redenumit în cadrul v1; deprecierile sunt anunțate în CHANGELOG.md din repository-ul protocolului înainte ca comportamentul să se schimbe.

Checklist de conformitate