Standardise an opt-in SSE progress-streaming response for /evaluate and /chat

[m-messer]

Summary

Standardises an opt-in Server-Sent Events (SSE) progress-streaming response for /evaluate and /chat, as proposed in #43.

Previously the spec only documented 200 → application/json, while ChatCapabilities.supportsStreaming and LLMConfiguration.stream implied streaming was in scope with no wire contract behind them. This defines that contract once, generically, so both endpoints stream identically and new endpoints get it for free.

Contract:

• Opt-in via Accept: text/event-stream. HTTP status stays 200 for the life of the stream, including failures.
• The stream is: zero or more progress frames (event: = stage name, data: = SseProgressStep), optional : keep-alive comments, and exactly one terminal frame.
• Terminal frame carries the operation's normal 200 body (event: completed) or an ErrorResponse under error (event: failed), plus a steps[] replay of every progress step.
• X-Request-Id / X-Api-Version are sent once as response headers at stream open.
• configuration.llm.stream (token-level LLM streaming) is now explicitly documented as distinct from API-layer progress streaming.

Key schema additions (shared, reused by both operations):

Schema	Role
SseProgressStep	stage / message / timestamp; stage is an informative string, not an enum
SseTerminalSteps	shared steps[] replay fragment
StreamingCapabilities	supportsStreaming + supportedProgressStages, composed via allOf into ChatCapabilities and EvaluateCapabilities
SseEvaluateTerminalFrame / SseChatTerminalFrame	terminal-frame data, reusing each operation's existing 200 body
EvaluateResponse	the /evaluate 200 body extracted into a named schema so the terminal frame can reuse it

ChatCapabilities.supportsStreaming moves into the shared fragment; EvaluateCapabilities gains streaming advertisement for the first time. Both /health examples now show supportsStreaming + supportedProgressStages.

Related issue

Closes #43

Scope

• This pull request is focused on a single concern.
• The change was started from the latest main branch, or from a fork if direct branch creation is not available.

Validation

• npm run lint — valid, no new warnings (8 pre-existing warnings unchanged)
• npm run bundle — succeeds; all new components resolve

Notes for reviewers

• Compatibility: additive / non-breaking. New optional text/event-stream content, new optional capability fields, description edits. The one refactor is /evaluate's 200 body moving from an inline array to the named EvaluateResponse component (semantically identical).
• SseChatTerminalFrame.output uses anyOf: [Message, "null"] rather than the repo's usual type: [object, "null"] + allOf: [$ref] idiom, because the failed-frame example sets output: null and must validate. The error fields keep the existing repo idiom (no null example exercises them).
• Follow-up: the shimmy reference implementation needs a matching PR — terminal-frame field names, /health capability output, its embedded spec copy, and stream tests.

🤖 Generated with Claude Code

[maximiliansoelch]

@m-messer Do you plan to actively use this?
The spec changes look reasonable to me, but it's hard to judge from the spec alone whether the contract holds up in practice. A reference implementation that uses it successfully would help confirm the spec covers everything needed. Would it be possible to have the shimmy follow-up you mentioned (or at least a draft of it) before we merge this?

[m-messer]

@maximiliansoelch Of course, here is the shimmy PR on using SSE: lambda-feedback/shimmy#28

In particular, take a look at: https://github.com/lambda-feedback/shimmy/pull/28/changes#diff-1ee1003a66dcdc217b95324d29e9959e0795e3f021bb886f9b2bf26c149ef59e and the files in the progress directory.

I am happy to answer any questions you have on the implementation.