SSE Protocol

DorkOS delivers all real-time state over two durable Server-Sent Events (SSE) streams: a per-session event stream (GET /api/sessions/:id/events) that carries everything about one session, and a global stream (GET /api/events) that carries session-list changes and system events. Sending a message does not stream anything back — it triggers a turn whose output arrives on the session event stream.

Triggering a Turn

Send a message to start a turn:

POST /api/sessions/:id/messages
Content-Type: application/json
X-Client-Id: your-client-uuid

{ "content": "Hello, Claude", "cwd": "/path/to/project" }

The endpoint is trigger-only. It validates the request, acquires the session write-lock, starts the turn server-side, and responds immediately:

202 Accepted
{ "sessionId": "canonical-session-id" }

For a brand-new session the returned sessionId is the canonical id assigned by the runtime during the turn — it may differ from the id you supplied. Use it for all subsequent requests. The turn's tokens are delivered solely on GET /api/sessions/:id/events; if you are not already subscribed, open the stream before (or right after) the POST.

If another client holds the write lock, the server returns 409 with { code: "SESSION_LOCKED", lockedBy, lockedAt }. See Session Write Coordination.

Session Event Stream

Subscribe to a session's durable event stream:

GET /api/sessions/:id/events

The stream has three phases:

1. Snapshot. On a cold connect the server emits a single snapshot event carrying the completed message history (messages), the in-progress turn (inProgressTurn, or null when idle), the server-held status, any pendingInteractions awaiting your response, and a cursor — the highest event sequence number the snapshot reflects.
2. Replay. On reconnect, the browser (or your SSE client) echoes the last received id: back as Last-Event-ID. The server skips the snapshot and replays only the events you missed, gap-free. If the cursor can no longer be served (e.g., the server restarted), the stream falls back to a fresh snapshot — you never silently miss events.
3. Live. Events stream as the turn produces them. Every event carries a per-session monotonic seq, and every SSE frame carries an id: line of the form <sessionId>-<epoch>-<seq> for resumption.

event: snapshot
data: {"messages":[...],"inProgressTurn":null,"status":{...},"pendingInteractions":[],"cursor":42}

id: abc123-1760000000000-43
event: turn_start
data: {"seq":43,"type":"turn_start","userMessage":"Hello, Claude"}

id: abc123-1760000000000-44
event: text_delta
data: {"seq":44,"type":"text_delta","text":"Hello! How can I help?"}

id: abc123-1760000000000-45
event: turn_end
data: {"seq":45,"type":"turn_end","terminalReason":"completed"}

This one stream is also the cross-client sync mechanism: every client subscribed to the same session sees the same snapshot, replay, and live events — including turns triggered by other clients or by the CLI. There is no separate sync endpoint and nothing to enable.

Session Event Types

All events share { seq: number, type: string }. Payloads below list the type-specific fields.

Turn Events

Text Events

Tool Events

Interactive Events

Interactive events carry server-authoritative countdown fields — startedAt (ms since epoch) and remainingMs — so a reconnecting client resumes the timeout where it left off instead of resetting it. The same interactions also appear in the snapshot's pendingInteractions, so a freshly connected client always recovers prompts it has not answered.

Status & Progress Events

Responding to Interactive Events

# Approve
POST /api/sessions/:id/approve
Content-Type: application/json
{ "toolCallId": "tc_123" }

# Deny
POST /api/sessions/:id/deny
Content-Type: application/json
{ "toolCallId": "tc_123" }

POST /api/sessions/:id/submit-answers
Content-Type: application/json
{ "toolCallId": "tc_123", "answers": { "0": "option_a" } }

POST /api/sessions/:id/submit-elicitation
Content-Type: application/json
{ "elicitationId": "eli_123", "action": "submit", "content": { "api_key": "sk-..." } }

POST /api/sessions/:id/submit-elicitation
Content-Type: application/json
{ "elicitationId": "eli_123", "action": "cancel" }

Global Events Stream

For the session list, relay activity, tunnel status, and extension events, subscribe to the unified global stream:

GET /api/events

This single persistent connection multiplexes all background events, distinguished by the SSE event: field:

These session-list events keep sidebars and dashboards live without polling GET /api/sessions.

Session Write Coordination

POST /api/sessions/:id/messages prevents concurrent writes via client IDs.

• If another client holds the write lock, the server returns 409 with { error: "Session locked", code: "SESSION_LOCKED", lockedBy, lockedAt }
• The lock is bound to the turn: it is released when the turn completes or errors, not when the HTTP response ends
• Locks auto-expire after 5 minutes as a backstop

Connection Lifecycle

GET /api/events

Next Steps