Hermes Agent
66 lines
4.0 KiB
Markdown
66 lines
4.0 KiB
Markdown
# Hermes Mobile Direct Gateway Architecture
|
|
|
|
Hermes Mobile is pivoting to a native Android client that talks directly to a remote upstream Hermes Agent gateway/API server. The `apps/companion` TypeScript server is legacy compatibility code and must not be required by Android or future releases.
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
Android app
|
|
Kotlin/Compose UI
|
|
connection/auth storage
|
|
transport DTOs
|
|
domain repositories
|
|
|
|
|
| HTTPS, bearer token when configured
|
|
v
|
|
Upstream Hermes Agent gateway/API server
|
|
auth/session authority
|
|
chat/completion authority
|
|
streaming/tool/artifact authority
|
|
provider credentials and Hermes runtime
|
|
```
|
|
|
|
The Android app remains a thin client. It may store server profiles, non-provider UI preferences, selected session IDs, and Android-secured bearer tokens. It must not embed provider credentials, clone Hermes backend behavior, or make the legacy companion server part of the release path.
|
|
|
|
## Documented Upstream Surface
|
|
|
|
The current repository/context documents these upstream Hermes API-server endpoints:
|
|
|
|
| Endpoint | Status | Mobile contract |
|
|
| --- | --- | --- |
|
|
| `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. |
|
|
| `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. |
|
|
|
|
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.
|
|
|
|
## Unverified Assumptions
|
|
|
|
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.
|
|
- 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`.
|
|
|
|
Android contracts may model these needs, but implementation must keep them capability-gated until verified.
|
|
|
|
## Compatibility Policy
|
|
|
|
- Direct gateway routes are the default target for all new Android transport work.
|
|
- Legacy companion routes such as `/api/health`, `/api/auth/validate`, `/api/chat`, `/api/files/*`, and `/api/terminal/*` are temporary compatibility only.
|
|
- UI and domain terminology should say "gateway", "server", or "upstream Hermes" unless explicitly describing legacy companion behavior.
|
|
- The transport/domain model exposes direct gateway capabilities first. `legacyCompanionAdapter` exists only to identify old adapters during migration.
|
|
- Backend behavior belongs upstream in Hermes Agent. Hermes Mobile may add client adapters and mappers, not server-side replacements.
|
|
|
|
## Android Contract Milestones
|
|
|
|
1. Auth and connection: validate URL, store bearer tokens securely, probe `GET /health`, and use `GET /v1/models` as the first authenticated check.
|
|
2. Sessions: keep repository interfaces for list/create/select/continue, but mark route mapping provisional until upstream session docs are verified.
|
|
3. Streaming: support final response and token delta reduction now; gate structured tool/artifact/session events behind server capabilities.
|
|
4. Companion removal: after direct gateway chat/session/streaming works end to end, remove legacy companion UI routes and then deprecate install/docs around `apps/companion`.
|