bonzi/hermes-mobile
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: execute gateway session SSE

Browse Source
This commit is contained in:
Hermes Agent
2026-07-24 12:39:51 +00:00
parent 8e7b5c6b44
commit 2a03caa7a9
13 changed files with 713 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/BLOCKERS.md
+4 -2
View File
@@ -11,8 +11,10 @@ Upstream compatibility needed for stronger binding: a documented stable gateway
The official Hermes Agent API server documentation checked on 2026-07-24 documents authenticated `GET /v1/capabilities` and session endpoint capability entries for list, create, get, update, delete, messages, fork, chat, and chat streaming. It does not document a session-search endpoint, query parameter/body schema, response envelope, or a `session_search` capability entry.
B3 therefore keeps `searchSessions` in the Android repository contract and verifies it with the fake repository, but deliberately provides no direct-gateway HTTP mapping for search. List/create/get/delete request construction is safe only when the live gateway advertises the corresponding endpoint string through `GET /v1/capabilities`.
B3 therefore keeps `searchSessions` in the Android repository contract and verifies it with the fake repository, but deliberately provides no direct-gateway HTTP mapping for search. Current official upstream API-server behavior represents capability endpoints as structured `{method, path}` objects; the earlier Android B3 string-only endpoint parser has not been exercised against a live gateway and is not treated as verified compatibility.
A local Hermes API-server configuration was present on 2026-07-24 with `API_SERVER_ENABLED=true`, host `0.0.0.0`, port `18793`, and a configured key. No process was listening on port `18793`, and `GET http://127.0.0.1:18793/health` was unreachable (`curl` HTTP code `000`), so no live session compatibility exercise was available.
Upstream evidence needed to unblock B3: official documentation for session search including capability key, HTTP method, path, query/body schema, response envelope, and empty/error semantics, followed by a live compatibility exercise against an upstream Hermes gateway.
Source checked: `https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/` on 2026-07-24.
Sources checked on 2026-07-24: `https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server/`; installed official upstream checkout `NousResearch/hermes-agent` at commit `36f2a966c`, including `gateway/platforms/api_server.py` capability and session-stream behavior.
docs/DIRECT_GATEWAY_ARCHITECTURE.md
+17 -3
View File
@@ -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`.
docs/ROADMAP.md
+2 -1
View File
@@ -9,6 +9,7 @@ Done:
- Android connection flow stores one logical gateway profile with optional Local HTTPS, required Remote HTTPS, Android-keystore-protected bearer/no-auth configuration, and active Local/Remote diagnostics.
- Local-first route selection uses bounded `GET /health` probes, authenticated `GET /v1/models` compatibility checks, deterministic Remote fallback, and foreground/connectivity/request-failure re-evaluation without switching in-flight leases.
- Android no longer calls undocumented legacy companion `/api/*` routes from the direct-gateway client path.
- Capability-gated session streaming binds each OkHttp call to an immutable route/session lease, parses SSE into authoritative final responses, ignores cross-session events, and reports transport failure only against the failed lease.
- Chat UI supports conversation list/thread navigation, native composer, busy state, selectable replies, error bubbles, and new-chat reset.
- Direct gateway compatibility contract is documented in `docs/DIRECT_GATEWAY_ARCHITECTURE.md`.
- Legacy companion chat, terminal, and file utilities remain in the repo during migration but are not the target architecture.
@@ -16,7 +17,7 @@ Done:
- Companion and workspace TypeScript typecheck, build, and lint pass as of 2026-07-24.
Remaining for beta:
- Complete B3 after upstream documents a session-search endpoint/query schema and a live gateway can verify advertised session CRUD behavior; the independently verifiable durable-state and capability-gated request foundation landed on 2026-07-24.
- Complete B3 after upstream documents a session-search endpoint/query schema and a live gateway can verify advertised session CRUD behavior; the independently verifiable durable-state foundation landed on 2026-07-24, but the current upstream `{method, path}` capability envelope has not been exercised live.
- Exercise the connection/settings unhappy paths on a real device or emulator; this sandbox cannot start ADB because local control sockets are prohibited.
- Exercise a real device or emulator against a running upstream Hermes gateway/API server.
- Verify direct gateway behavior end to end beyond B2: chat request/response, session continuity expectations, streamed/final output handling, and failure recovery.