# harbour-hermes

Native **Sailfish OS** client for the **Hermes Web UI** (`hermes-webui`):
chat with your Hermes agent from the phone — and use it with your **voice**.

## Features

- Sign in to your Hermes Web UI (session cookie persisted; password never stored)
- Sessions list, new session, open any session
- Chat with **live streaming** replies (SSE token deltas)
- **Voice dictation**: tap Mic, speak, tap Stop → server-side Whisper
  transcription lands in the composer (optionally sent right away)
- **Read aloud**: server-side TTS (voice/engine configurable) played through
  QMediaPlayer; optional auto-read of every completed reply
- **Voice dialog (hands-free)**: continuous listen → transcribe → send →
  read-aloud loop, auto-stopping on speech pauses (tunable)
- Cancel a running turn, resync from server state, cover page

## Requirements

- Sailfish OS 4.4+ (developed against Sailfish 5.1)
- A running `hermes-webui` instance reachable over HTTPS (the address is
  configured in the app — nothing is compiled in)
- Sailjail permissions `Internet;Audio;Microphone` (declared in the .desktop)

## Configuration

No configuration is compiled into the binary: everything lives in the app's
Settings (persisted in `~/.config/harbour/hermes.conf`, sandbox-persistent).
Defaults are neutral — empty means "the server decides" — and the login screen
requires a server address.

| Setting | Meaning |
|---|---|
| Server | Hermes Web UI address, e.g. `https://hermes.example.com` (required) |
| Read-aloud voice / TTS engine | empty = server defaults |
| Voice/engine presets | comma-separated lists used to fill the pickers |
| Read replies aloud | auto-play every reply (off by default) |
| Send right after dictation | auto-send when dictation lands (on by default) |
| Auto-stop pause / Mic sensitivity | voice-dialog tuning (1.5 s / medium) |
| Max recording time | voice-dialog safety cap (60 s) |

> **Read-aloud voices depend on your server.** The selected voice is sent to
> `hermes-webui`'s `/api/tts`, which only accepts voices present in its Edge
> TTS allowlist (`api/routes.py`; upstream ships Chinese, English, French and
> Indonesian voices). If your server rejects a voice (`400 invalid voice`),
> pick another one, leave the voice empty (server default), or add your
> language's voices to your own `hermes-webui`.

## Build

See [docs/BUILD.md](docs/BUILD.md) (Sailfish SDK, `sfdk build` / `sfdk deploy`)
and [docs/PROTOCOL.md](docs/PROTOCOL.md) for the HTTP/SSE protocol the app
speaks (validated live against a real instance).

## Status

Version 0.3.2 — protocol and C++ core validated against a real `hermes-webui`
(login, sessions, streaming chat, TTS, STT, voice dialog); on-device testing
still ongoing.