diff --git a/docs/CONTRACTS.md b/docs/CONTRACTS.md index 39a0ccc3d..df22273ba 100644 --- a/docs/CONTRACTS.md +++ b/docs/CONTRACTS.md @@ -60,6 +60,13 @@ contributor guidance; it does not change runtime behavior or CI gates. queued messages, interrupt replacement, steer visibility, or leftover-steer recovery changes. - [`docs/rfcs/README.md`](rfcs/README.md): RFC conventions and current RFC index. +- [`docs/rfcs/session-sse-contract-v1.md`](rfcs/session-sse-contract-v1.md): + proposed contract vocabulary, cursor/resume semantics, replay identity, snapshot + fallback, event taxonomy, and implementation gates for the per-session SSE + stream `GET /api/sessions/{session_id}/events` (#4812). Distinct from the + existing global session-list stream `GET /api/sessions/events`. Start here for + any work that touches per-session SSE, `Last-Event-ID` replay, or session + lifecycle event delivery. Proposed RFCs do not authorize implementation. When a change touches streaming, recovery, replay, compression, context reconstruction, cancellation, approval/clarify, session metadata, or run state, diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md index 2f4c72df3..921bb2d45 100644 --- a/docs/rfcs/README.md +++ b/docs/rfcs/README.md @@ -66,3 +66,6 @@ First-time contributor RFCs should be discussed in an issue before opening a PR. #3058 control-surface companion to #3400 for Queue, Steer, Stop-and-send, Interrupt, and leftover-steer inputs submitted while a long-running agent session is active. +- [`session-sse-contract-v1.md`](session-sse-contract-v1.md) — #4812 Proposed + contract vocabulary, replay identity, event taxonomy, cursor/resume semantics, + and implementation gates for `GET /api/sessions/{session_id}/events`. diff --git a/docs/rfcs/session-sse-contract-v1.md b/docs/rfcs/session-sse-contract-v1.md new file mode 100644 index 000000000..58c330269 --- /dev/null +++ b/docs/rfcs/session-sse-contract-v1.md @@ -0,0 +1,242 @@ +# Session SSE Contract v1 + +- **Status:** Proposed +- **Author:** @rodboev +- **Created:** 2026-07-04 +- **Tracking:** #4812 + +Refs #4812 + +--- + +## Problem + +hermes-webui has no stable, cross-client contract for observing the lifecycle +of an individual session over SSE. Five or more future consumers — WebUI +reconnect/multi-tab, Android wrapper, iOS/PWA wrapper, desktop/TWA wrapper, and +test/CLI observers — each need a resumable, dedupe-safe event stream. Without a +shared contract, every client invents its own cursor, heartbeat, and event-type +semantics, multiplying coordination cost as new producers are added. + +The maintainer asked for a docs-only RFC first, holding implementation until +sequence and replay semantics are settled (comment 2026-06-24T17:14:05Z, +2026-06-25T04:50:06Z on #4812). This document settles the contract vocabulary +against current source before any route is added. + +## Goals + +- Define the SSE envelope and event-type vocabulary for a proposed per-session + stream `GET /api/sessions/{session_id}/events`. +- Specify replay identity using the existing run-journal cursor model. +- Specify the snapshot fallback for stale or evicted cursors. +- Document the distinction from the existing global session-list stream. +- Record open implementation gates that must be resolved before the endpoint + ships. + +## Non-goals + +- This RFC does **not** implement `GET /api/sessions/{session_id}/events`. No + route, handler, or related code is added in this PR. +- This RFC does **not** modify `GET /api/sessions/events` (the existing global + session-list invalidation stream at `api/routes.py:16118`). +- This RFC does **not** replace or modify existing streams: `/api/chat/stream`, + `/api/approval/stream`, or `/api/clarify/stream`. +- This RFC does **not** introduce Android, iOS, or PWA client code. +- This RFC does **not** claim Android/iOS background reconnect behavior or + production proxy delivery; those require owner-reaching proof in a later + implementation PR. +- This RFC does **not** promise a new session-global sequence counter in Phase 1. + +## Current source inventory + +### Existing global session-list stream + +`GET /api/sessions/events` is a **different endpoint** from the one this RFC +proposes. It is routed at `api/routes.py:12296-12297` and implemented by +`_handle_session_events_stream()` at `api/routes.py:16118-16131`. It emits bare +`sessions_changed` events and keepalives for any change to the session list. It +is a global invalidation signal, not a per-session lifecycle stream. The proposed +`GET /api/sessions/{session_id}/events` is per-session and path-distinct. + +### Heartbeat + +`_SSE_HEARTBEAT_INTERVAL_SECONDS = 5` (`api/routes.py:1018-1030`) is the current +heartbeat interval for SSE streams. Phase 1 reuses this constant rather than +adding a separate configurable knob. + +### Run-journal cursor and replay + +Current replay identity is run/stream-scoped: + +- `_parse_run_journal_event_id()` and `_parse_run_journal_after_seq()` at + `api/routes.py:15638-15665` parse the cursor from `Last-Event-ID`. +- `_runner_event_id()` at `api/routes.py:15730-15737` constructs the event `id` + field as `stream_id:seq`. +- Live event `id:` is emitted at `api/routes.py:15869-15885`. +- `_replay_run_journal()` reads events by `(session_id, stream_id)` at + `api/routes.py:15668-15700`. +- `api/streaming.py:6265-6285` writes current live agent streams to + `STREAMS[stream_id]`. +- `api/streaming.py:6620-6634` appends SSE events to the run journal and carries + per-item `event_id` into the live queue. + +The existing run journal represents `session_id`, `stream_id`, `seq`, and +`event_id`, but **not** a session-global monotonic sequence. Phase 1 must not +promise a session-global counter because current source does not provide one. + +## Proposed endpoint + +``` +GET /api/sessions/{session_id}/events +``` + +This endpoint is **path-distinct** from `GET /api/sessions/events`. The +`{session_id}` path segment is required; the global endpoint has no such segment. + +Response: `Content-Type: text/event-stream`. Authentication and session +visibility checks reuse existing mechanisms. + +## Envelope + +Each SSE event carries a JSON payload with this structure: + +```json +{ + "schema_version": 1, + "session_id": "", + "event_type": "", + "event_id": "", + "stream_id": "", + "seq": , + "emitted_at": "", + "payload": { ... }, + "meta": { ... } +} +``` + +- `schema_version`: integer, always `1` for Phase 1 events. +- `session_id`: the session this event belongs to. +- `event_type`: one of the event types listed in the taxonomy below. +- `event_id`: opaque client cursor (see Cursor and resume semantics). +- `stream_id`: the run journal stream this event came from, if applicable. +- `seq`: monotonic within a stream/run (see Cursor and resume semantics). +- `emitted_at`: server-side emission timestamp in ISO-8601 UTC. +- `payload`: event-type-specific data. +- `meta`: optional; reserved for tracing and debug metadata. + +## Event taxonomy (Phase 1 draft) + +| event_type | Source | Description | +|---|---|---| +| `chat_delta` | run journal / live stream | Token or chunk from an assistant reply. | +| `tool_call` | run journal / live stream | Tool invocation record. | +| `tool_result` | run journal / live stream | Tool result record. | +| `approval_request` | run journal | Approval prompt sent to the user. | +| `clarify_request` | run journal | Clarification prompt sent to the user. | +| `run_started` | run journal | Run entered active state. | +| `run_finished` | run journal | Run reached a terminal state (complete, cancelled, error). | +| `session_snapshot` | server fallback | Current session projection; emitted when replay is unavailable. | +| `heartbeat` | server | Keepalive emitted on the `_SSE_HEARTBEAT_INTERVAL_SECONDS` cadence. | + +The event-type table is a draft. The final table must be confirmed during +maintainer review before implementation. + +## Cursor and resume semantics + +`Last-Event-ID` is the standard SSE reconnect header. Clients send the last +`event_id` value seen on reconnect; the server uses it to resume replay from that +position. + +**`event_id` is opaque to clients.** Its current source-compatible form is +`stream_id:seq`, as constructed by `_runner_event_id()` at +`api/routes.py:15730-15737`. Clients must treat it as an opaque string and must +not parse or construct cursor values. + +**`seq` is monotonic within a stream/run.** It is not a session-global counter +and is not promised to increase monotonically across streams or runs. Phase 1 +does not claim a pre-existing session-global sequence because current source does +not provide one. + +**Clients dedupe by `event_id`.** If a reconnect causes overlap with already-seen +events, clients use `event_id` to detect and skip duplicates. + +## Replay source + +Phase 1 uses the **durable run journal** as the replay source for replayable +events. The live `STREAMS[stream_id]` queue (`api/streaming.py:6265-6285`) is +not a reliable replay source because it holds only recent in-memory state. + +A future implementation must replay from the run journal via the existing +`_replay_run_journal()` path (`api/routes.py:15668-15700`) and fall back to the +snapshot mechanism when journal entries are unavailable for a given cursor. + +## Snapshot fallback + +When the `Last-Event-ID` cursor is evicted, expired, unknown, or refers to a +stream that is no longer replayable, the server must: + +1. Emit a `session_snapshot` event containing the current session projection. +2. Continue the live stream from the present without pretending that missed + events were replayed. + +`session_snapshot` is a recovery boundary, not proof of exact missed-event +replay. Clients receiving a snapshot must treat prior cursor state as invalid and +resync from the snapshot payload. + +## Heartbeat + +Phase 1 reuses `_SSE_HEARTBEAT_INTERVAL_SECONDS` (`api/routes.py:1018-1030`) for +heartbeat cadence. A new per-session configurable heartbeat knob is **not** added +in Phase 1. The implementation PR must follow whatever value the constant holds +at implementation time; it must not hard-code a separate interval. + +## Security and privacy + +- Reuse existing auth and session visibility checks. A client must not be able to + subscribe to events for a session it does not own. +- Payloads must not include credentials, raw provider API keys, or unsanitized + internal error details. +- `meta` fields are for tracing and debug metadata and must not carry + security-sensitive values in production. + +## Implementation gates (open questions) + +The following decisions must be resolved before any implementation PR for this +endpoint is accepted: + +1. **Sequence semantics**: Maintainer must confirm that stream/run-scoped `seq` + (not session-global) is acceptable for Phase 1 clients. +2. **Retention policy**: How long are run journal entries retained for replay? + What is the eviction boundary that triggers the snapshot fallback? +3. **Event-type table**: The taxonomy above is a draft. The complete event-type + list must be confirmed during review of this RFC. +4. **Auth behavior on reconnect**: Does `Last-Event-ID` replay require the same + auth token, or can it continue across token refresh? +5. **Client proof**: At least one browser-based client (WebUI) and at least one + non-browser client (Android wrapper or CLI) must provide owner-reaching + reconnect proof before implementation closes #4812. +6. **Proxy and keepalive**: The 5 s heartbeat choice must survive real proxy + deployments. This requires manual-owner-proof or standards-doc evidence in the + implementation PR. + +## Bypass risks + +Future implementation work must not: + +- Introduce an in-memory-only cursor that bypasses the run journal. +- Conflate `GET /api/sessions/events` (global session-list invalidation) with + `GET /api/sessions/{session_id}/events` (per-session lifecycle). +- Promise a session-global monotonic sequence without defining a migration from + the current stream/run-scoped model. + +Tests in `tests/test_issue4812_session_sse_contract_rfc.py` assert these +boundaries so review catches regressions against this contract. + +## Rollout plan + +1. This RFC is accepted by maintainer review on #4812. +2. Retention and event-type decisions are confirmed. +3. Client proof (browser + non-browser) is provided. +4. An implementation PR adds `GET /api/sessions/{session_id}/events` following + this contract vocabulary. +5. Implementation PR closes #4812. diff --git a/tests/test_issue4812_session_sse_contract_rfc.py b/tests/test_issue4812_session_sse_contract_rfc.py new file mode 100644 index 000000000..6d0ab43ec --- /dev/null +++ b/tests/test_issue4812_session_sse_contract_rfc.py @@ -0,0 +1,189 @@ +"""Docs/source contract tests for issue #4812 session SSE contract RFC. + +These tests assert the invariants of docs/rfcs/session-sse-contract-v1.md +without requiring a running server or endpoint implementation. +""" + +import pathlib + +REPO = pathlib.Path(__file__).parent.parent +RFC = REPO / "docs" / "rfcs" / "session-sse-contract-v1.md" +RFC_README = REPO / "docs" / "rfcs" / "README.md" +CONTRACTS = REPO / "docs" / "CONTRACTS.md" + + +def _rfc() -> str: + return RFC.read_text(encoding="utf-8") + + +def _readme() -> str: + return RFC_README.read_text(encoding="utf-8") + + +def _contracts() -> str: + return CONTRACTS.read_text(encoding="utf-8") + + +class TestRFCExists: + def test_rfc_file_exists(self): + assert RFC.exists(), f"RFC file not found: {RFC}" + + def test_rfc_has_status_proposed(self): + assert "Status:** Proposed" in _rfc(), "RFC must have 'Status: Proposed' header" + + def test_rfc_has_author(self): + assert "Author:** @" in _rfc(), "RFC must have 'Author: @...' header" + + def test_rfc_has_created_date(self): + assert "Created:** " in _rfc(), "RFC must have 'Created: YYYY-MM-DD' header" + + def test_rfc_has_tracking_issue(self): + assert "Tracking:** #4812" in _rfc(), "RFC must have 'Tracking: #4812' header" + + def test_rfc_refs_not_closes(self): + text = _rfc() + assert "Refs #4812" in text, "RFC must use 'Refs #4812', not 'Closes #4812'" + assert "Closes #4812" not in text, "RFC must not use 'Closes #4812'" + + +class TestRFCIndexed: + def test_readme_indexes_rfc(self): + assert "session-sse-contract-v1.md" in _readme(), ( + "docs/rfcs/README.md must list session-sse-contract-v1.md" + ) + + def test_readme_indexes_rfc_with_issue(self): + assert "#4812" in _readme(), ( + "docs/rfcs/README.md index entry must reference #4812" + ) + + def test_contracts_indexes_rfc(self): + assert "session-sse-contract-v1.md" in _contracts(), ( + "docs/CONTRACTS.md must reference session-sse-contract-v1.md" + ) + + +class TestEndpointDistinction: + def test_rfc_names_proposed_per_session_endpoint(self): + assert "/api/sessions/{session_id}/events" in _rfc(), ( + "RFC must propose GET /api/sessions/{session_id}/events" + ) + + def test_rfc_distinguishes_global_sessions_events(self): + text = _rfc() + assert "/api/sessions/events" in text, ( + "RFC must mention existing GET /api/sessions/events" + ) + assert "/api/sessions/{session_id}/events" in text, ( + "RFC must distinguish per-session endpoint from global endpoint" + ) + + def test_rfc_states_global_endpoint_is_different(self): + text = _rfc() + assert "path-distinct" in text or "different endpoint" in text, ( + "RFC must explicitly state the two endpoints are distinct" + ) + + def test_contracts_distinguishes_both_endpoints(self): + text = _contracts() + assert "/api/sessions/{session_id}/events" in text, ( + "CONTRACTS.md must mention proposed per-session endpoint" + ) + assert "/api/sessions/events" in text, ( + "CONTRACTS.md must mention existing global sessions/events endpoint" + ) + + +class TestSequenceAndReplaySemantics: + def test_rfc_includes_last_event_id(self): + assert "Last-Event-ID" in _rfc(), "RFC must include Last-Event-ID" + + def test_rfc_includes_event_id(self): + assert "event_id" in _rfc(), "RFC must include event_id" + + def test_rfc_includes_stream_id(self): + assert "stream_id" in _rfc(), "RFC must include stream_id" + + def test_rfc_includes_seq(self): + assert '"seq"' in _rfc() or "`seq`" in _rfc(), "RFC must include seq field" + + def test_rfc_includes_session_snapshot(self): + assert "session_snapshot" in _rfc(), "RFC must include session_snapshot event" + + def test_rfc_states_seq_is_stream_scoped(self): + text = _rfc() + assert "monotonic within a stream" in text or "stream/run-scoped" in text, ( + "RFC must state seq is monotonic within a stream/run, not session-global" + ) + + def test_rfc_does_not_promise_session_global_counter(self): + text = _rfc() + assert "does not claim a pre-existing session-global sequence" in text or ( + "not a session-global counter" in text + ), ( + "RFC must explicitly state Phase 1 does not claim a session-global counter" + ) + + def test_rfc_states_event_id_is_opaque(self): + assert "opaque" in _rfc(), "RFC must state event_id is opaque to clients" + + def test_rfc_names_run_journal_as_replay_source(self): + text = _rfc() + assert "run journal" in text.lower(), ( + "RFC must name the run journal as the replay source" + ) + + def test_rfc_defines_session_snapshot_as_fallback(self): + text = _rfc() + assert "session_snapshot" in text + assert "fallback" in text.lower() or "snapshot fallback" in text.lower(), ( + "RFC must define session_snapshot as the stale-cursor fallback" + ) + + def test_rfc_snapshot_is_not_exact_replay(self): + text = _rfc() + assert "not proof of exact missed-event replay" in text or ( + "recovery boundary" in text + ), ( + "RFC must state snapshot is a recovery boundary, not exact missed-event replay" + ) + + +class TestHeartbeat: + def test_rfc_references_heartbeat_constant(self): + assert "_SSE_HEARTBEAT_INTERVAL_SECONDS" in _rfc(), ( + "RFC must reference _SSE_HEARTBEAT_INTERVAL_SECONDS rather than inventing a new constant" + ) + + def test_rfc_does_not_add_new_heartbeat_knob(self): + text = _rfc() + assert "new per-session configurable heartbeat" not in text or ( + "not** added" in text or "not added" in text.lower() + ), ( + "RFC must not add a new per-session heartbeat knob in Phase 1" + ) + + +class TestDocsOnlyScope: + def test_rfc_states_no_endpoint_implementation(self): + text = _rfc() + assert "does **not** implement" in text or "does not implement" in text, ( + "RFC must state it does not implement the endpoint" + ) + + def test_rfc_has_non_goals_section(self): + assert "Non-goals" in _rfc(), "RFC must have a Non-goals section" + + def test_rfc_lists_implementation_gates(self): + text = _rfc() + assert "implementation gate" in text.lower() or "open question" in text.lower(), ( + "RFC must list open implementation gates" + ) + + def test_contracts_preserves_no_implementation_warning(self): + text = _contracts() + assert "not authorize implementation" in text or ( + "Proposed RFCs are review guardrails, not implementation authorization" in text + ), ( + "CONTRACTS.md must preserve warning that proposed RFCs do not authorize implementation" + )