# 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**: When switching execution to a new host, Hermes automatically transfers a bounded context window of the last 10 messages (or since the last synced point, up to 10 max). This context is transferred securely as a distinct system preamble, completely separately from the user's prompt text, avoiding stealth concatenation. Sensitive variables, tokens, API keys, and credentials are automatically stripped/redacted from the transferred context payload before sending.
   - **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. **Background Execution & Synchronization**:
   - Long-running host tasks (like heavy computations, builds, or lengthy agent turns) will continue safely in the background even if you minimize the application or switch apps.
   - When active tasks are running, a foreground service (notification: "Hermes Agent active") keeps the sync socket alive and commits incoming tool usage or results back to the local database timeline.
   - The service terminates automatically the moment the task completes or errors out, preserving battery life and conforming to Android Play Store `dataSync` foreground policies.

5. **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 test
```

Run Android Lint:

```powershell
.\gradlew.bat lint
```

Assemble Debug APK:

```powershell
.\gradlew.bat assembleDebug
```

---

## 📱 Instant QR Onboarding — Hermes Pair (`hermes-pair/`)

Inside the `hermes-pair/` directory is the cross-platform desktop companion application written in Rust. It runs on Windows and Linux to auto-discover your local IP and generate a secure QR code for instant onboarding with Hermes Android.

### 1. Download Prebuilt Binaries (GitHub Releases)

Download prebuilt binaries and `SHA256SUMS.txt` from the latest [GitHub Releases](https://github.com/ochenstarik-ui/hermes-android/releases).

#### Verifying SHA-256 Checksums:

- **Windows (PowerShell)**:
  ```powershell
  Get-FileHash .\hermes-pair-windows-x86_64.exe -Algorithm SHA256
  # Compare the resulting hash with SHA256SUMS.txt
  ```

- **Linux**:
  ```bash
  sha256sum -c SHA256SUMS.txt
  # or verify directly:
  sha256sum hermes-pair-linux-x86_64
  ```

### 2. Running Hermes Pair

#### Windows (GUI or CLI):
```powershell
# Launch GUI window (defaults to HTTPS pairing with TLS pinning)
.\hermes-pair-windows-x86_64.exe

# Terminal QR output with pinned certificate fingerprint
.\hermes-pair-windows-x86_64.exe qr --port 9119 --fingerprint "AA:BB:CC:DD:..."
```

#### Linux (GUI or Headless Server):
```bash
chmod +x hermes-pair-linux-x86_64

# Launch GUI window
./hermes-pair-linux-x86_64

# Headless / Terminal QR with pinned certificate fingerprint
./hermes-pair-linux-x86_64 --terminal --port 9119 --fingerprint "AA:BB:CC:DD:..."
```

### 3. Security Architecture: TLS Pinning & Strict Network Policy
- **Strict Network Policy**: Android's `network_security_config.xml` enforces `cleartextTrafficPermitted="false"` across base configurations, preventing unencrypted transport of authentication tokens or user prompts.
- **TLS Fingerprint Trust (`TlsFingerprintTrust`)**: During QR onboarding via [Pairing Protocol v2](docs/pairing-protocol-v2.md), the host passes its SHA-256 TLS certificate fingerprint. Hermes Android securely validates self-signed or enterprise TLS certificates without requiring device-wide root certificate installation or cleartext exceptions.

### 4. Building Hermes Pair from Source:
```bash
cd hermes-pair
cargo test
cargo build --release
```

The compiled binaries will be located at:
- **Windows**: `hermes-pair/target/release/hermes-pair.exe`
- **Linux**: `hermes-pair/target/release/hermes-pair`