feat: pivot mobile client to direct gateway
This commit is contained in:
Hermes Agent
@@ -0,0 +1,65 @@
|
||||
# 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`.
|
||||
+11
-11
@@ -1,23 +1,23 @@
|
||||
# Hermes Mobile Beta Roadmap
|
||||
|
||||
## Current Milestone: Native Android Beta Chat and Connection UX
|
||||
## Current Milestone: Native Android Direct Gateway Contract
|
||||
|
||||
Status: in progress, close to beta validation. F0 source landing and F1 design-system extraction are complete; Android debug builds now pass in the shared Gradle cache environment.
|
||||
Status: in progress. Android foundation work is complete, and the beta path now targets a remote upstream Hermes Agent gateway/API server directly. The legacy `apps/companion` server is compatibility-only and not required for future Android releases.
|
||||
|
||||
Done:
|
||||
- Native Kotlin/Compose Android shell replaces the web-first mobile path for the beta surface.
|
||||
- Companion settings flow stores companion URL and access key locally, validates bearer auth, and surfaces health errors in-app.
|
||||
- Android connection flow stores a gateway URL and bearer token locally, validates URL/auth state, and surfaces offline/unauthorized/retry states in-app.
|
||||
- Chat UI supports conversation list/thread navigation, native composer, busy state, selectable replies, error bubbles, and new-chat reset.
|
||||
- Companion `/api/chat` invokes Hermes through the CLI with `hermes chat -Q --source tool -q <prompt>`.
|
||||
- Companion chat responses sanitize terminal banners/help/control output, truncate large replies for mobile, report CLI availability, and return structured failure responses.
|
||||
- Workspace utilities remain native: command runner, health view, file browsing, read, and write.
|
||||
- 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.
|
||||
- Local build artifacts, Android transient build output, `.gradle-user/`, and `.dev/` are ignored.
|
||||
- Companion and workspace TypeScript typecheck, build, and lint pass as of 2026-07-24.
|
||||
|
||||
Remaining for beta:
|
||||
- Android debug build validation passed on 2026-07-24: `GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew :app:assembleDebug` from `apps/mobile/android`.
|
||||
- Exercise a real paired device against a running companion and authenticated Hermes CLI.
|
||||
- Exercise upstream-compatible transport/auth/session/streaming behavior end to end: bearer auth, health, chat request/response, session continuity expectations, streamed/final output handling, and failure recovery.
|
||||
- Exercise a real device or emulator against a running upstream Hermes gateway/API server.
|
||||
- Verify direct gateway behavior end to end: bearer auth, `GET /health`, `GET /v1/models`, chat request/response, session continuity expectations, streamed/final output handling, and failure recovery.
|
||||
- Verify or revise provisional session, streaming, tool-event, artifact, and cancellation route assumptions against official upstream docs.
|
||||
- Add or run focused Android UI validation for chat/settings flows on small and large screens.
|
||||
- Confirm adaptive accessibility: font scaling, TalkBack labels, contrast, keyboard/IME behavior, and reduced-motion tolerance.
|
||||
- Document beta install/run steps after the native build is verified.
|
||||
@@ -26,9 +26,9 @@ Remaining for beta:
|
||||
|
||||
- Native Kotlin/Compose Android app is the shipped beta client.
|
||||
- No WebView, Capacitor runtime dependency, fake backend, embedded secrets, or new external infrastructure is introduced for beta.
|
||||
- Companion transport and auth are upstream-compatible and exercised against the real Hermes CLI.
|
||||
- Chat/session/streaming behavior is exercised with Hermes, including success, CLI unavailable, timeout, non-zero exit, and malformed response cases.
|
||||
- Direct gateway transport and auth are exercised against the upstream Hermes gateway/API server.
|
||||
- Chat/session/streaming behavior is exercised with Hermes, including success, unauthorized, timeout, server error, malformed response, and stream interruption cases.
|
||||
- Settings connection flow is reliable: save, validate, health, Hermes test, offline/unauthorized states, and recovery are clear.
|
||||
- Adaptive accessibility passes on target Android devices or emulators.
|
||||
- Required checks pass: `./gradlew :app:assembleDebug` from `apps/mobile/android`, companion typecheck/build, and relevant lint.
|
||||
- Required checks pass: `./gradlew :app:testDebugUnitTest :app:assembleDebug` from `apps/mobile/android` and relevant source lint.
|
||||
- Release notes clearly list remaining known beta limitations.
|
||||
|
||||
Reference in New Issue
Block a user