ROADMAP-22 — P3 — SSE streaming protocol for run steps and tokens (design note first) #114

Series: ROADMAP — filed from the 2026-10-27 whole-project assessment · Backlog task: M17-T01 · Priority: P3 · Effort: large (design note first)

Problem

LLMClient.chat returns a monolithic LLMResponse; POST /runs blocks until the full loop finishes. Steps are written to Postgres as they happen (pg_trace.py), so the write side of streaming already exists — only the read side is missing. Clients must poll /trace to see anything.

Acceptance criteria (after a short design note in docs/)

• text/event-stream events: thought, tool_call, tool_result, token (if the provider layer gains streaming), final
• The loop emits events through a TraceSink-style optional callback — core stays decoupled from the transport
• Sync POST /runs remains the default and unchanged; stream mode optional
• LLMAdapter streaming is a stretch: if provider token streaming is out of scope for v1, emit step-level events only and note token streaming as follow-up
• Integration test with an isomorphic fake stream

Suggested branch / commit

feat/sse-streaming · feat(api): SSE step-level streaming for run execution