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 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 track of which queued messages are yours across a page reload. Send a stable id if your integration reconnects.

The endpoint is trigger-only, and it never waits: it validates the request, gives the message to the session, and responds straight away whether or not the turn can start yet.

202 Accepted
{
  "sessionId": "canonical-session-id",
  "messageId": "0d5e...",
  "outcome": { "messageId": "0d5e...", "requested": "queue", "applied": "queue" },
  "queuePosition": 1
}

A 202 means the server has your message, not that a turn is running. If the session was idle, the turn started. If a turn was already in flight, your message joined the session's queue and runs when that turn ends. queuePosition tells you which happened: 1 means nothing was ahead of it. If you previously treated the 202 as "the turn has begun" — starting a timer, or polling from that moment — take the real start from the turn_start event instead.

messageId is the server's id for this message, and it is what the queue is keyed by. Keep it if you want to reword or withdraw the message before it runs. outcome reports what the server did with it: requested is what you asked for, applied is what happened, and a degradedBecause appears only when the two differ. Ask for queue and it is always what you get — the server owns the queue, so every runtime can do it. Ask for steer or stage and you may get queue back with a reason: unsupported (this runtime cannot do it at all), not-steerable (this runtime can steer, but the session you asked about cannot take a message mid-task), turn-owned-elsewhere (a turn is running and a different client started it, so this one may not write into it), pending-interaction (the agent is waiting on a person), or session-idle (nothing was running, so your message just ran — the one reason not worth reporting to anybody).

When a stage does come back as stage, degradedBecause tells you where the words went. Absent, they reached the agent's own record right away. unsupported means this runtime keeps no such record, and not-stageable means it keeps one but the session you asked about is not holding its agent open; in both of those the words are held and handed to the agent with its next reply instead. All three emit a context_staged event, so a stage that landed is never silent.

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.

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, the messages waiting to run (queuedMessages, empty when nothing is), and a cursor (the highest event sequence number the snapshot reflects). Those five fields are the whole of a session's live state: hydrate from them and you are exactly as correct as a client that has been connected all along.
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":[],"queuedMessages":[],"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" }

The Message Queue

Every session has one queue, and the server holds it. A message sent while a turn is running lands there and runs when that turn ends; a message sent to an idle session runs immediately and never appears. The queue belongs to the session rather than to whoever filled it, so a message queued in the app is visible to your integration, and one queued by your integration is visible in every open browser window. It survives a dropped connection, a reconnect, and a server restart.

You learn the queue two ways, and they carry the same list:

• queuedMessages on the snapshot, so a cold connect starts out knowing what is waiting.
• queue_update on the stream, on every change: a message accepted, dispatched, reworded, moved, or removed, by any client.

queue_update always carries the whole queue, head first, never a diff. Replace your copy with it rather than merging into one. That is deliberate: a client that missed an update is fully corrected by the next one, so there is no incremental state to get wrong. Like every other event it carries a seq, so apply it under the same watermark rule as the rest — an event at or below the highest seq you have already applied is a duplicate, and dropping it is correct.

outcome is present when the update was caused by a message being accepted, and it is the same receipt the 202 returned. Use it to tell "my own send landed" from "someone else changed the queue".

Every entry in queue and in queuedMessages is a QueuedMessage:

Three routes read and change it. Each answers with the queue as it now stands, so you do not need to wait for the stream to catch up:

GET is redundant with the snapshot on purpose: opening a stream to read one small list is a poor trade for a script or a debugging session.

A move names another message to land before or after, never an index. An index means something different to every client the moment anyone else edits the queue, and two clients editing one queue is exactly what this surface is for. A PATCH that names neither content nor move is refused as 400; an id this queue does not hold — including a move anchored to one — is 404 QUEUED_MESSAGE_NOT_FOUND.

Removing a message removes its pending run with it, so a message you withdraw does not surface later.

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.

Four events go only to whoever they are about

Most events on this stream are written to every connection. Four are not: interaction_pending, approval_pending, notification and notification_read. Each carries something about what your agents are doing or what is waiting on you, so each goes only to a connection that could act on it.

interaction_pending carries what an agent is waiting for — the tool it wants to run, the command or path it would run it against, and the session's working directory. approval_pending carries the capability being asked for and a sentence describing what would happen. The two notification events carry the titles and bodies of your inbox.

In practice that means one thing: a connection presenting an X-DorkOS-Agent header never receives it. The same connection also stops receiving activity on a session_status frame whose lifecycle is blocked — that field names the tool and the command a session is parked on, which is the same detail by another route. The lifecycle itself is still sent, so a reader still knows the session is waiting; it just does not learn what for. And on a session's own stream (GET /api/sessions/:id/events) the snapshot's pendingInteractions comes back empty and the approval_required / question_prompt / elicitation_prompt frames are not sent. An agent could never answer a prompt (POST /api/sessions/:id/approve refuses every one of them), so it no longer sees them either. A connection holding one of your per-user API keys still receives them, because it can already read the same detail on that session's own stream. GET /api/sessions/pending-interactions, which is what a page reads on load, filters the same way — and answers 200 with an empty list rather than an error, so a caller cannot tell "you may not see this" from "there is nothing waiting".

interaction_resolved is deliberately NOT filtered. It carries a session id, an interaction id and an outcome, and nothing about what was asked; a client that never received the pending has nothing to close. approval_resolved and approval_grant_changed are unfiltered for the same reason: one says a card is over, the other says only that the permission list moved.

GET /api/notifications filters the same way the events do, and answers 200 with an empty list rather than an error. Marking something read is refused outright instead, because "I have seen this" is a claim only a person looking at a screen can make.

What you get when you connect

Shortly after connecting you receive one session_status event for every session the server currently sees as working, waiting on a person, or stopped with an error. Sessions that are idle send nothing, because there is nothing to say about them. Treat these as ordinary session_status events — same shape, same handler, no special ordering to wait for.

This is what lets a page that opened five minutes late still know that a session is stuck: the transitions themselves happened while you were not connected, so only the state they left behind can tell you. The next real transition replaces whatever these told you.

They are read from what the server is holding in memory right now, so they are a picture of the live fleet rather than of all history: a restart clears it, and Claude Code sessions are also forgotten after about half an hour of quiet. Nothing else expires on a timer today, so a session left waiting on a person — or one whose turn never finished — keeps being announced on every connect until it moves again. Reconnecting is not what clears it.

Session Write Coordination

Several clients may write to one session at the same time. Their messages do not collide, and none of them is turned away: the queue puts them in one order and every client watches that order change on the stream.

• X-Client-Id identifies you across reconnects and labels the messages you queued (enqueuedBy). It is not a claim on the session and it is never checked for permission.
• A write lock still exists, and it is now entirely internal: it is what guarantees only one turn runs on a session at a time. It is bound to the turn rather than to the HTTP request, released when the turn completes or errors, and expires after 5 minutes of inactivity as a backstop against a turn that went dark.
• Because the queue answers the "someone else is writing" case, the lock is no longer an answer any endpoint gives you. 409 SESSION_LOCKED is gone from POST /api/sessions/:id/messages.

Connection Lifecycle

GET /api/events

Next Steps

WebSocket streams

Every durable stream on this page — GET /api/events, GET /api/sessions/:id/events, and GET /api/rooms/:id/events — also answers a WebSocket upgrade at the same URL. Same three phases, same snapshot, same replay, same ordering guarantees. Only the packaging differs.

Reach for this only if your client runs inside a browser tab and needs several streams open at once. Everywhere else, plain SSE is simpler.

// Same path, ws:// (or wss://) instead of http://
const socket = new WebSocket(
  'ws://localhost:4242/api/sessions/' + sessionId + '/events?cwd=' + encodeURIComponent(cwd)
);

socket.onmessage = (message) => {
  const frame = JSON.parse(message.data);
  if (frame.event === '__heartbeat') return; // liveness only, see below
  handle(frame.event, frame.data);
  if (frame.id) lastEventId = frame.id; // keep this — it is your resume cursor
};

Each message is one JSON text frame carrying the same three things an SSE frame carries:

Four differences to know about:

• Resuming uses a query parameter, not a header. A browser WebSocket takes a URL and nothing else, so send the last id you saw as ?resume=<id> rather than as Last-Event-ID. Send the whole id, not just the trailing number — the middle part identifies the server process, and it is what stops a cursor from a restarted server replaying the wrong events.
• Heartbeats are frames. SSE keeps a connection alive with a comment your parser ignores. A WebSocket has no comment, and its built-in ping is invisible to browser JavaScript, so the server sends a frame named __heartbeat instead. Treat any frame as proof the stream is alive, and skip that one before handling it.
• Refusals arrive as a close code, not an HTTP status. A browser cannot see the status of a handshake that failed, so the server accepts the connection and immediately closes it with 4000 + status — 4401 for "sign in", 4403 for "not allowed", 4404 for "no such thing". Read event.code in onclose and subtract 4000. This is how these three streams refuse a request they understood — a missing credential, an unknown room, a bad id — for browser and non-browser clients alike: the handshake completes and the socket closes immediately, so do not wait for an HTTP status that will not come. Two cases still answer at the handshake instead: an unexpected server-side error is a real 500, and a path no endpoint claims is closed with no response at all.
• Reconnecting is yours to do. A WebSocket does not retry on its own the way EventSource does. Reconnect with backoff, and pass ?resume= so you pick up exactly where you left off.

If you are behind a reverse proxy or a dev server, make sure it forwards WebSocket upgrades as well as ordinary requests — most need to be told explicitly, and the symptom is a stream that connects to nothing while every other request works fine.