ARIA
e5c7d690b8
Second, short-lived-connection transport next to the WS: same frames, same outbox/cursor, same token, served over plain HTTP (stdlib ThreadingHTTPServer bridged into the asyncio loop; zero new deps). - http_server.py: /v1/health (unauthenticated), POST /v1/frame (accept-and-ack; validation rejections as 4xx error frames), SSE /v1/events (outbox catch-up with id=cursor, event: hello, 15s heartbeat, bounded-queue backpressure), long-poll /v1/poll (25s hold). Bearer token + X-Iris-Device (same allowlist as WS hello), 64 KiB body cap, per-device rate limit, optional TLS, non-fatal bind failure. - ws_server.py: inbound dispatch chain extracted to shared dispatch_frame() used by both transports. - adapter.py: ANDROID_HTTP_PORT/CERT/KEY config; start/stop next to the WS; delivery counting in _broadcast_or_log (an SSE subscriber is a live subscriber -> no push, docs/19 19.8); _reply() routes point-to-point replies into the in-flight HTTP response (reply sink) or broadcasts when the device has no live WS (19.7); status/typing/ channel events fan out to both transports. - ws_probe.py: --http mode (health + POST + SSE turn drive, same assertion flags); tests/README updated. - Tests: hermes-agent/tests/gateway/test_android_http.py (23 tests, incl. the 19.8 delivery-counting regression); test_android.py (74) still green.
72 lines
3.9 KiB
Markdown
72 lines
3.9 KiB
Markdown
# Iris × Hermes — Implementation Reference Library
|
||
|
||
A coder-facing reference library for building a **native Android + Desktop
|
||
experience** for [hermes-agent](https://github.com/NousResearch/hermes-agent),
|
||
connected through a **gateway platform plugin**.
|
||
|
||
This folder is the single source of truth for *what to build and why*. Read it
|
||
top-to-bottom once, then use the numbered docs as a lookup while implementing.
|
||
|
||
> ⚠️ **READ FIRST — two hard rules**
|
||
>
|
||
> 1. **`hermes-agent/` (sibling of this folder) is a read-only research
|
||
> reference. It must NEVER be committed, pushed, or shipped.** It is
|
||
> git-ignored at the repo root. We only *install* our plugin into a live
|
||
> hermes install (`~/.hermes/plugins/`); we never modify hermes core.
|
||
> 2. **ADB is installed and a device is connected** (`a5ca2a4b`, Xiaomi MIX 2S,
|
||
> Android 10 / API 29). Use it to install/launch/debug the app on-device.
|
||
|
||
---
|
||
|
||
## Reading order
|
||
|
||
| # | File | When to read |
|
||
| --- | ------ | -------------- |
|
||
| 0 | [`00-overview.md`](00-overview.md) | Always first. Vision, scope, disclaimers, locked decisions. |
|
||
| 1 | [`01-architecture.md`](01-architecture.md) | Before touching code. System shape + rationale. |
|
||
| 2 | [`02-monorepo.md`](02-monorepo.md) | When scaffolding the repo. |
|
||
| 3 | [`03-gateway-plugin.md`](03-gateway-plugin.md) | When building the Python plugin. |
|
||
| 4 | [`04-wire-protocol.md`](04-wire-protocol.md) | When implementing either side of the WS. |
|
||
| 5 | [`05-streaming.md`](05-streaming.md) | Streaming / reasoning / tools / intermediate. |
|
||
| 6 | [`06-channels-cron-search.md`](06-channels-cron-search.md) | Channels, threads, cron delivery, search. |
|
||
| 7 | [`07-media.md`](07-media.md) | Media upload/download + playback. |
|
||
| 8 | [`08-push.md`](08-push.md) | Push (FCM + ntfy), outbox, sync. |
|
||
| 9 | [`09-pairing-security.md`](09-pairing-security.md) | Pairing, auth, security model. |
|
||
| 10 | [`10-android-app.md`](10-android-app.md) | When building the Android app. |
|
||
| 11 | [`11-desktop-app.md`](11-desktop-app.md) | When building the Desktop app. |
|
||
| 12 | [`12-toolchain.md`](12-toolchain.md) | First time on a machine (JDK/SDK/uv/Firebase). |
|
||
| 13 | [`13-testing.md`](13-testing.md) | Writing tests + on-device ADB workflow. |
|
||
| 14 | [`14-milestones.md`](14-milestones.md) | Planning work / tracking progress. |
|
||
| 15 | [`15-hermes-reference.md`](15-hermes-reference.md) | **Cheat-sheet** of hermes-agent source to read. |
|
||
| 16 | [`16-open-questions.md`](16-open-questions.md) | Decisions made + open items. |
|
||
| 17 | [`17-future-control-surface.md`](17-future-control-surface.md) | **Backlog** — what the app could control beyond chat (cron, kanban, models, …). |
|
||
| 19 | [`19-http-fallback-transport.md`](19-http-fallback-transport.md) | **Design** — HTTP fallback leg (POST + SSE/long-poll) so the app can send/receive when the WS is down. |
|
||
|
||
Machine-readable / diagrams:
|
||
|
||
- [`protocol/frames.schema.json`](protocol/frames.schema.json) — wire-frame schema.
|
||
- [`diagrams/architecture.mmd`](diagrams/architecture.mmd) — mermaid architecture.
|
||
|
||
---
|
||
|
||
## The three deliverables (one monorepo)
|
||
|
||
1. **`gateway-plugin/`** — a Python hermes **platform plugin** named `android`.
|
||
Runs inside the `hermes gateway` process. Opens a WebSocket server the apps
|
||
connect to. Implements the full `BasePlatformAdapter` contract. **Zero new
|
||
Python dependencies, zero hermes-core changes.**
|
||
2. **`app/androidApp`** — native Kotlin + Jetpack Compose client.
|
||
3. **`app/desktopApp`** — Kotlin + Compose Multiplatform client that *shares*
|
||
the Android app's code and is "tweaked" for a big screen.
|
||
|
||
The Android and Desktop clients live in **one Compose Multiplatform Gradle
|
||
project** (`app/`) with a shared KMP module (`app/shared`).
|
||
|
||
---
|
||
|
||
## Status
|
||
|
||
- **Phase:** M0–M6 complete; M7 (polish + E2E + docs) in progress.
|
||
- **Owner decisions locked:** see [`16-open-questions.md`](16-open-questions.md).
|
||
- **Last updated:** 2026-08-19.
|