Chat API

{
  // REQUIRED
  "text": "Refactor the auth flow to use the new Clerk SDK",   // string, trimmed; empty triggers 400

  // OPTIONAL: to resume an existing session
  "session_id": "f3b1c2d4-...",                                // omit for a new session

  // OPTIONAL: to override backend selection
  "agent_name": "claude_code",                                 // "openclaw" | "claude_code"

  // OPTIONAL: scope a new session to a project / Claude Code agent
  "agent_id": "blackhole",                                     // matches a folder under
                                                               // ~/xo-projects/<agent_id>/

  // OPTIONAL: workspace path hint (alternative to agent_id)
  "workspace": "/Users/me/xo-projects/blackhole",              // absolute path

  // OPTIONAL: skill / persona prefix
  "agent_type": "research",                                    // claude_code maps this to a /skill-name
                                                               // codex maps it to $skill-name

  // OpenClaw-only: defaults to "main"
  "model": "openclaw/research"
}

ws_path = Path(workspace).expanduser().resolve()
if   ws_path startswith ~/xo-projects/{X}/...   →  agent_id = X
elif ws_path startswith ~/claude-cowork/{X}/... →  agent_id = X
else                                             →  agent_id = None

{
  "stream_id":  "8f3a2b1c-...",     // UUID. Use for /api/chat/stream/{id} and /api/chat/abort.
  "session_id": "9d4e5f6a-..."      // UUID. The logical session id.
                                    //   New OpenClaw: may be null (see note below).
                                    //   New non-OpenClaw: always populated.
                                    //   Resumed: equals the session_id you sent.
}

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

event: session-created
data:  {"session_id":"<uuid>"}

event: text-delta
data:  {"text":"<partial text>","session_id":"<uuid>"}        // OpenClaw includes session_id
data:  {"text":"<partial text>"}                               // non-OpenClaw omits session_id

event: heartbeat
data:  {}                                                       // every 15 to 20s of silence

event: agent-error
data:  {"error_message":"<human readable>"}

event: done
data:  {"finish_reason":"stop","session_id":"<uuid>"}

event: error
data:  {"error_message":"Stream not found"}                    // only on bad/expired stream_id

─── normal new-session turn ─────────────
[session-created]    once at start, before any text-delta
[text-delta]         many; accumulate to form the assistant message
[heartbeat]*         interleaved during silent gaps
[done]               once at the end; server closes the stream

─── normal resume turn ──────────────────
[text-delta]+
[heartbeat]*
[done]

─── error path ──────────────────────────
(maybe a few text-delta first)
[agent-error]        terminal; server closes after this; no [done] follows

id: 1
event: session-created
data: {"session_id":"9d4e5f6a-1234-4567-89ab-cdef01234567"}

id: 2
event: text-delta
data: {"session_id":"9d4e5f6a-...","text":"Sure"}

id: 3
event: text-delta
data: {"session_id":"9d4e5f6a-...","text":", I can"}

id: 4
event: text-delta
data: {"session_id":"9d4e5f6a-...","text":" do that."}

event: heartbeat
data: {}

id: 5
event: done
data: {"finish_reason":"stop","session_id":"9d4e5f6a-..."}

1. The first GET pops `stream_info` from active_streams and starts a producer task.
2. A bookkeeping entry lands in `_recently_started[stream_id]` with a `done_event`.
3. A second GET on the same stream_id finds active_streams empty but
   _recently_started populated.
4. It waits (up to 300s) on done_event.
5. Once the original turn finishes, it emits:
     event: session-created  data: {"session_id":...}
     event: done             data: {"session_id":...}
6. The frontend should refetch messages from /api/messages/{session_id}.
   No text-delta events are replayed.

event: error
data: {"error_message":"Stream not found"}

const es = new EventSource(`${BASE}/api/chat/stream/${streamId}`);

es.addEventListener("session-created", (e) => {
  const { session_id } = JSON.parse(e.data);
  if (!currentSessionId) router.push(`/c/${session_id}`);
});

es.addEventListener("text-delta", (e) => {
  const { text } = JSON.parse(e.data);
  appendToAssistantMessage(text);
});

es.addEventListener("heartbeat", () => {
  resetDeadStreamTimer();
});

es.addEventListener("agent-error", (e) => {
  const { error_message } = JSON.parse(e.data);
  showErrorBanner(error_message);
  es.close();
});

es.addEventListener("error", (e) => {
  // Either: native EventSource error (network), OR
  //         our custom event:error (stream_id unknown).
  // Distinguish by checking if e.data exists.
  if ((e as MessageEvent).data) {
    const { error_message } = JSON.parse((e as MessageEvent).data);
    if (error_message === "Stream not found") {
      // Stream expired: refetch from /api/messages/{id}
    }
  }
  es.close();
});

es.addEventListener("done", (e) => {
  const { session_id } = JSON.parse(e.data);
  finalizeAssistantMessage();
  es.close();
});

{ "stream_id": "8f3a2b1c-..." }

{ "ok": true }

// request: any JSON body
// response:
{ "ok": true }

// request
{
  "project_name": "my-project",        // string, this is the session key, NOT a path
  "question":     "Hello",             // string
  "user_id":      "user_2bX9...",      // optional, default "default_user"
  "message_type": "@xo",               // optional, default "@xo"
  "agent_type":   "debug-tool"         // optional, becomes /{agent_type} skill prefix for Claude
}

// response (200)
{
  "id":              null,
  "message":         "Hello! How can I help...",
  "project_id":      "my-project",
  "user_id":         "user_2bX9...",
  "session_id":      "9d4e5f6a-...",
  "is_new_session":  true,
  "timestamp":       "2026-05-10T12:34:56.789012"
}

data: {"type":"token","token":"<partial text>"}

data: {"type":"error","error":"<message>"}

data: {"done":true}

data: {"error":"<exception message>"}