SSE Protocol

Read this before building any client that talks to a DorkOS session over HTTP.

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, a bit like ordering a coffee and getting a text when it's ready.

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" }

X-Client-Id is optional. Omit it and the server generates a UUID for you, but then it can't tell your own reconnects apart from a fresh client, so you lose precise write-lock ownership tracking across a page reload. Send a stable id if your integration reconnects.

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

terminalReason tells you why the turn stopped so you can render the right thing:

• completed: normal finish. Show the final message as-is.
• aborted_tools, aborted_streaming: the user or client interrupted the turn. Show it as stopped, not failed.
• max_turns, blocking_limit, rapid_refill_breaker, prompt_too_long: a limit was hit. Tell the user what limit and let them retry or adjust (shorter prompt, new session).
• image_error, model_error: something went wrong upstream. Show a retry affordance.
• stop_hook_prevented, hook_stopped: a configured hook intervened. Surface the hook's message if you have one; otherwise say a hook stopped the turn.
• tool_deferred: the turn ended waiting on a background task. Treat the session as still in progress.
• error: an unhandled runtime or SDK crash mid-stream. Show a generic failure state and offer retry.
• Absent, or a value not listed here: treat it like completed but don't assume; new SDK versions can add reasons the server passes through unchanged.

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
{ "interactionId": "eli_123", "action": "accept", "content": { "api_key": "sk-..." } }

POST /api/sessions/:id/submit-elicitation
Content-Type: application/json
{ "interactionId": "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