codai Sessions API
Shared-sessions protocol v2: one conversation shared live between several devices (desktop, phone, CLI, agents). A session has an append-only event log with a server-assigned dense `seq`, persisted controls (`send`, `answer`, `approve`, …), a single executor lease (TTL 30 s, heartbeat every 10 s) and a presence set. Every operation here needs a codai API key **and** the `x-codai-device` header — a client-chosen UUID that is registered on first use (`x-codai-device-name` / `x-codai-device-platform` optional; an `x-codai-push-token` header upserts the FCM token used by Dispatch). `GET /v1/sessions` and `GET /v1/sessions/{id}` fall through to the legacy read-only memory API when the header is absent, unless `?v=2` is set. `{id}` accepts the server UUID **or** the client `session_key`. Roles: `owner` (the creator) ≥ `editor` ≥ `viewer`; shares are managed under `/v1/sessions/{id}/shares`. Link-share callers present the token via `x-codai-share-token` or `?share=`. Realtime frames are also available over WebSocket at `wss://ai.codai.ro/v1/sessions/{id}/ws?after=` (not modelled here). Same `Authorization: Bearer` header auth (raw keys in `?key=` are rejected with close code 4401); the device id may ride in `?device=`. Upstream frames: `{t: control}`, `{t: events}`, `{t: presence, driving}`; downstream frames mirror the SSE events plus `ack` and `error`. WS `error` frames DO carry `details` (`holder_device_id`, `expected_last_seq`/`last_seq`) — over HTTP only the message does.