spb/search-box Public

1<!--2Search-box.ai3Author: Simon-Pierre Boucher4Contact: contact@spboucher.ai5File: docs/event-protocol.md6Description: Research event protocol (SSE).7-->89# Event protocol1011Typed in `packages/events/src/index.ts`. Persisted per session with a monotonic `seq`;12streamed over SSE at `GET /api/research/:id/stream`.1314## Transport1516- `id:` field = `seq` → browsers resend `Last-Event-ID` on reconnect; the server replays17  from that position. `?from=0` replays a full session (used by the event-sourced UI).18- Heartbeat comment every 15s keeps proxies from idling out the connection.19- `event: end` closes the stream once the session is terminal and fully delivered.20- SSE responses set `Cache-Control: no-cache, no-transform` and `X-Accel-Buffering: no`21  so the ngrok/proxy chain doesn't buffer.2223## Event types2425| Type | Meaning |26|---|---|27| `session.started` / `session.status` / `session.completed` / `session.failed` | lifecycle |28| `plan.updated` | objectives set/revised (with public reason) |29| `thought` | public narration — never hidden chain of thought |30| `action.started` / `action.completed` | search/fetch with latency + outcome |31| `source.added` / `source.updated` | source lifecycle |32| `evidence.added` | quote + stance + source context |33| `claim.added` / `claim.updated` | hypothesis lifecycle, confidence changes |34| `contradiction.added` | surfaced disagreement |35| `budget.updated` | usage vs limits after each search/fetch |36| `synthesis.started` | answer writing begins |37| `answer.delta` / `answer.completed` | streaming final answer; completed carries the citation map |38