ARIA
9286937e2d
Hermes can append a text "runtime footer" (model, context %, workdir, latency, cost) to final replies, but only when display.runtime_footer is enabled in the hermes config. We want the same info but controlled by the APP, not the gateway config. So the gateway now ALWAYS sends the data as a structured `runtime` object on final assistant messages, and the app decides whether/what to show. Gateway (gateway-plugin/): - protocol.py: new runtime_footer() helper + `runtime` field on the message / message.stop frames. Keys (all optional, absent when the data is unavailable — e.g. no cost for local models): model (vendor prefix dropped), context_pct (0-100), cwd (home-relative), latency (seconds), cost (USD). - adapter.py: a post_api_request plugin hook captures the turn's model + prompt tokens + start time (platform-filtered to android so other platforms don't pollute the buffer). _build_runtime_footer() resolves the model's context window (cached, best-effort, off the event loop via asyncio.to_thread with a timeout) and computes context_pct. The runtime object is attached on every final send (streaming message.stop and non-streaming message, plus the fallback paths). - outbox.py: `runtime` preserved in history reconstruction so the footer survives a restart / first open. App (app/shared/): - Protocol.kt: RuntimeMeta data class + `runtime` on MessagePayload / MessageStopPayload / HistoryMessage. - ChatStore.kt: `runtime` on MessageItem, wired through live + history reconciliation. - SecureStore.kt (+ Android/Desktop actuals): runtimeFooterEnabled + runtimeFooterFields (persisted per device). - IrisController.kt: StateFlows + toggleRuntimeFooter() / toggleRuntimeField(); RUNTIME_FIELD_KEYS / default set / parser. - SettingsScreen.kt: "Runtime footer" switch; when on, an expandable chip menu (Model · Context % · Workdir · Latency · Cost) to pick fields. - ChatScreen.kt: footer rendered on the SAME line as the timestamp (footer left, time right, Telegram-style), only for final non-streaming assistant answers; Inspector pane now shows the runtime fields too. Docs: 04-wire-protocol.md + frames.schema.json document the `runtime` object. Verified end-to-end on device: final replies carry `qwen3.8-27B-exl3-4.5bpw · 53% · ~ · 38s` with the time right-aligned on the same line; 69/69 gateway tests pass, Kotlin builds + tests pass.
Iris × Hermes — Implementation Reference Library
A coder-facing reference library for building a native Android + Desktop experience for 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
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.- 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 |
Always first. Vision, scope, disclaimers, locked decisions. |
| 1 | 01-architecture.md |
Before touching code. System shape + rationale. |
| 2 | 02-monorepo.md |
When scaffolding the repo. |
| 3 | 03-gateway-plugin.md |
When building the Python plugin. |
| 4 | 04-wire-protocol.md |
When implementing either side of the WS. |
| 5 | 05-streaming.md |
Streaming / reasoning / tools / intermediate. |
| 6 | 06-channels-cron-search.md |
Channels, threads, cron delivery, search. |
| 7 | 07-media.md |
Media upload/download + playback. |
| 8 | 08-push.md |
Push (FCM + ntfy), outbox, sync. |
| 9 | 09-pairing-security.md |
Pairing, auth, security model. |
| 10 | 10-android-app.md |
When building the Android app. |
| 11 | 11-desktop-app.md |
When building the Desktop app. |
| 12 | 12-toolchain.md |
First time on a machine (JDK/SDK/uv/Firebase). |
| 13 | 13-testing.md |
Writing tests + on-device ADB workflow. |
| 14 | 14-milestones.md |
Planning work / tracking progress. |
| 15 | 15-hermes-reference.md |
Cheat-sheet of hermes-agent source to read. |
| 16 | 16-open-questions.md |
Decisions made + open items. |
| 17 | 17-future-control-surface.md |
Backlog — what the app could control beyond chat (cron, kanban, models, …). |
Machine-readable / diagrams:
protocol/frames.schema.json— wire-frame schema.diagrams/architecture.mmd— mermaid architecture.
The three deliverables (one monorepo)
gateway-plugin/— a Python hermes platform plugin namedandroid. Runs inside thehermes gatewayprocess. Opens a WebSocket server the apps connect to. Implements the fullBasePlatformAdaptercontract. Zero new Python dependencies, zero hermes-core changes.app/androidApp— native Kotlin + Jetpack Compose client.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. - Last updated: 2026-08-19.