118 lines
6.7 KiB
Markdown
118 lines
6.7 KiB
Markdown
# Hermes Android Native Remote Client
|
|
|
|
A production-grade, native Android client application for **Hermes**, implementing Protocol & Architecture Contract v1 with **Multi-Hermes Connection Manager** and **Unified Sessions**.
|
|
|
|
Built with **Kotlin**, **Jetpack Compose (Material 3)**, **Coroutines**, **Room Database**, **OkHttp**, and **Android Keystore (EncryptedSharedPreferences)**.
|
|
|
|
---
|
|
|
|
## 🌟 Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ Hermes Android Client │
|
|
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Jetpack Compose UI (M3) │ │
|
|
│ │ • Multi-Host Switcher • Unified Sessions • Attributed Chat │ │
|
|
│ └─────────────────────────────────┬─────────────────────────────────┘ │
|
|
│ │ StateFlow / Actions │
|
|
│ ┌─────────────────────────────────▼─────────────────────────────────┐ │
|
|
│ │ Unified Session Repository │ │
|
|
│ │ • Logical Unified Sessions • Context Synchronization Delta │ │
|
|
│ │ • Host-Tagged Event Routing • Local Persistence (Room DB) │ │
|
|
│ └──────────────────┬──────────────────────────────┬─────────────────┘ │
|
|
│ │ │ │
|
|
│ ┌──────────────────▼──────────────────┐ ┌────────▼─────────────────┐ │
|
|
│ │ Hermes Connection Manager │ │ Encrypted Token Vault │ │
|
|
│ │ • Map<HostId, HostRuntime> │ │ (Host-Scoped Keystore) │ │
|
|
│ └───────┬─────────────────────────┬───┘ └──────────────────────────┘ │
|
|
│ │ │ │
|
|
│ ┌───────▼─────────────┐ ┌───────▼─────────────┐ │
|
|
│ │ Host #1 Runtime │ │ Host #2 Runtime │ │
|
|
│ │ (OkHttp WS + REST) │ │ (OkHttp WS + REST) │ │
|
|
│ └───────┬─────────────┘ └───────┬─────────────┘ │
|
|
└──────────┼─────────────────────────┼────────────────────────────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────────┐ ┌──────────────────────┐
|
|
│ Hermes Host #1 │ │ Hermes Host #2 │
|
|
│ (Windows Office) │ │ (Linux Server) │
|
|
│ `hermes serve` │ │ `hermes serve` │
|
|
└──────────────────────┘ └──────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Key Multi-Host Features
|
|
|
|
1. **Multi-Hermes Connection Manager**:
|
|
- Save and manage multiple independent Hermes installations (e.g. Workstation, Linux Server, Cloud VM).
|
|
- Independent WebSocket connections, concurrent state management, and isolated reconnect loops.
|
|
- Individual host health badges: `Online`, `Connecting`, `Offline`, `Auth Expired`.
|
|
|
|
2. **Unified Sessions & Context Synchronization**:
|
|
- Create one logical conversation (`UnifiedSession`) that spans multiple physical Hermes hosts.
|
|
- Seamlessly switch active execution hosts mid-conversation via the top-bar dropdown.
|
|
- **Delta Context Sync**: Injects conversation history and task context to newly attached hosts automatically without full-history re-transmission or secret leakage.
|
|
- **Host Attribution**: Every response bubble, tool card, and thinking trace displays its originating host badge (e.g. `[Office PC]`, `[Linux Server]`).
|
|
- **Non-Blocking Host Switching**: If Host #1 is executing a long tool or computation and you switch to Host #2, Host #1 completes its work in the background and commits results into the shared timeline.
|
|
|
|
3. **Isolated Host Security & Approvals**:
|
|
- Host-scoped credentials stored securely in Android Keystore (`hostId -> tokens`).
|
|
- **Host-Targeted Approvals & Clarifications**: Dangerous command approvals (`approval.request`) and sudo prompts route back strictly to the exact host runtime and native session that emitted them.
|
|
|
|
4. **Local Persistence (Room DB)**:
|
|
- Full offline caching for `UnifiedSession`, `HostSessionBinding`, and `UnifiedMessage`.
|
|
- Raw native session browser for inspecting individual host histories.
|
|
|
|
---
|
|
|
|
## 🖥️ Hermes Host Setup
|
|
|
|
### Windows Host
|
|
|
|
```powershell
|
|
hermes serve --host 0.0.0.0 --port 9119
|
|
```
|
|
|
|
With OAuth / GitHub Auth:
|
|
```powershell
|
|
$env:HERMES_AUTH_REQUIRED="true"
|
|
$env:HERMES_AUTH_PROVIDERS="github"
|
|
$env:HERMES_AUTH_GITHUB_CLIENT_ID="<your_client_id>"
|
|
$env:HERMES_AUTH_GITHUB_CLIENT_SECRET="<your_client_secret>"
|
|
hermes serve --host 0.0.0.0 --port 9119
|
|
```
|
|
|
|
### Linux Host
|
|
|
|
```bash
|
|
export HERMES_AUTH_REQUIRED="true"
|
|
export HERMES_AUTH_PROVIDERS="github"
|
|
export HERMES_AUTH_GITHUB_CLIENT_ID="<your_client_id>"
|
|
export HERMES_AUTH_GITHUB_CLIENT_SECRET="<your_client_secret>"
|
|
|
|
hermes serve --host 0.0.0.0 --port 9119
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Testing & Verification
|
|
|
|
Run the full automated test suite:
|
|
|
|
```powershell
|
|
.\gradlew.bat testDebugUnitTest
|
|
```
|
|
|
|
Run Android Lint:
|
|
|
|
```powershell
|
|
.\gradlew.bat lintDebug
|
|
```
|
|
|
|
Assemble Debug APK:
|
|
|
|
```powershell
|
|
.\gradlew.bat assembleDebug
|
|
```
|