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

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

Auth and connection: validate URL, store bearer tokens securely, probe GET /health, and use GET /v1/models as the first authenticated check.
Sessions: keep repository interfaces for list/create/select/continue, but mark route mapping provisional until upstream session docs are verified.
Streaming: support final response and token delta reduction now; gate structured tool/artifact/session events behind server capabilities.
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.

4.0 KiB Raw Blame History