feat: execute gateway session SSE

docs/DIRECT_GATEWAY_ARCHITECTURE.md

@@ -30,10 +30,24 @@ The current repository/context documents these upstream Hermes API-server endpoi
 | --- | --- | --- |
 | `GET /health` | Documented | Primary reachability and compatibility probe. Response shape beyond a successful JSON response is treated as server-specific. |
 | `GET /v1/models` | Documented | Authenticated compatibility probe for bearer-token connections and future model picker source. |
+| `GET /v1/capabilities` | Documented | Capability negotiation source. Current upstream behavior advertises endpoints as `{method, path}` objects and feature support as booleans. |
 | `POST /v1/chat/completions` | Documented | Baseline OpenAI-compatible chat path. Mobile must assume this may not expose Hermes session IDs or structured tool events. |
 | `POST /v1/responses` | Documented | Preferred future request/streaming path if upstream exposes richer response events. Exact Hermes event mapping is not yet verified. |
+| `/api/sessions/*` | Documented and capability-advertised | List/create/get/update/delete/messages/fork/chat/chat-stream routes exist, but mobile must use only the exact advertised method/path object and must not infer search or other routes. |
+| `POST /api/sessions/{session_id}/chat/stream` | Documented and capability-advertised | SSE session turn. Core mobile support begins with `message.started`, `assistant.delta`, authoritative `assistant.completed`, `error`, and `done`; tool events remain gated by `tool_progress_events`. |
 
-These are the only upstream API-server routes currently treated as documented by this repository. Any route not listed here must be labeled provisional until checked against official Hermes Agent docs or a running gateway.
+Any route not listed here must be labeled provisional until checked against official Hermes Agent docs or a running gateway. Session search remains explicitly unverified and unmapped.
+
+## Direct stream lease contract
+
+- Parse `session_chat_streaming`, `tool_progress_events`, and `endpoints.session_chat_stream` from `GET /v1/capabilities`.
+- Require the advertised session stream endpoint to be `POST`, use an absolute path containing `{session_id}`, and send the documented JSON `input` field.
+- Bind the request URL, route generation, session ID, endpoint path, and structured-event gate into one immutable lease before the HTTP call starts.
+- Execute that prebuilt request through OkHttp without consulting route selection again until the call ends.
+- Never apply an SSE event whose `session_id` differs from the bound lease. A later Local/Remote re-evaluation applies only to a later request.
+- Append `assistant.delta` text deterministically, then replace it with the authoritative `assistant.completed.content` response when present.
+- Report HTTP, I/O, or malformed-SSE failure only against the route/session lease that owned the failed call; an upstream `error` event fails the session without invalidating the route.
+- Decode tool lifecycle/progress only when `tool_progress_events` is advertised; B4 does not render or persist those structured payloads.
 
 ## Unverified Assumptions
 
@@ -41,8 +55,8 @@ The following are useful design assumptions, not confirmed contracts:
 
 - Bearer authentication is accepted through an `Authorization: Bearer <token>` header on `/v1/*`.
 - `/health` returns a stable `status` field.
-- `/v1/responses` can provide enough streaming metadata to preserve Hermes sessions, tool lifecycle, artifacts, cancellation, and reconnect state.
-- Hermes session listing, creation, continuation, and deletion have stable direct HTTP endpoints.
+- `/v1/responses` can provide enough streaming metadata to preserve Hermes sessions, artifacts, cancellation, and reconnect state.
+- Hermes session search has a stable direct HTTP endpoint.
 - Tool result and artifact listing/download have stable direct HTTP endpoints.
 - Cancellation has a stable direct HTTP endpoint.
 - Error payloads consistently include `message` or `error`.