hermes-mobile/docs/ROADMAP.md

# Hermes Mobile Beta Roadmap

## Current Milestone: Native Android Direct Gateway Contract

### P0 First-run Setup Wizard — completed 2026-07-24

- Welcome/privacy guidance precedes configuration; Remote HTTPS is required and Local HTTPS is optional for the same logical gateway profile.
- Authentication choices are None, Bearer token, or username/password. Password login exchanges credentials directly with the configured remote gateway and stores encrypted credentials/session state outside Compose UI models.
- Test-and-finish uses the existing local-first route selection, requires a successful compatibility check before completion, and exposes the same profile for later Settings edits.
- Existing completed valid profiles skip mandatory setup; valid profiles with recorded legacy provenance receive a one-time setup-version migration without forcing re-entry. A failed/offline first-run None or Bearer test cannot create a restart bypass.
- Compose semantics, minimum touch targets, adaptive layout behavior, and phone/tablet/light/dark previews cover the wizard source contract.
- Earlier full-suite Gradle output recorded 106 unit tests with 0 failures/errors. After the latest Android source change, the existing focused report records 30 passing `SetupWizardReducerTest` cases and the ignored debug APK has a later build timestamp. No real device, release, or real gateway credential walkthrough has been performed; those remain part of R1/R2 evidence.
- Task 5 source-current re-verification on 2026-07-24 passed the external recovery preflight and documented offline Gradle test/assembly command (43 tasks, 1 executed); the generated Gradle XML report records 106 passing tests with 0 failures/errors, including 29 `SetupWizardReducerTest` cases. A localhost gateway health probe returned HTTP 200, establishing reachability only. The debug APK is package `cloud.molberg.hermesmobile`, version `0.1.0-beta.1` (`10001`), SHA-256 `45e4ab4783a74eb766070b0f670a2631a9ebdc044468bbe03087788f8106f150`; `git diff --check` passed. No ADB device/emulator or `/dev/kvm` was available; no device installation, real authentication, release, or end-to-end gateway verification was performed.
- A later Task 5 rerun in the current sandbox on 2026-07-24 did not supersede the passing Gradle output: the guide's exact Gradle command failed before project execution because no usable wildcard IP was available, and the offline/no-daemon variant failed because Gradle could not open its daemon TCP socket. Direct JUnit execution of the existing source-current compiled `SetupWizardReducerTest` classes passed all 29 tests. The existing XML reports and ignored APK remained unchanged; metadata/hash inspection still matched the values above. ADB 37.0.0 could not start its daemon, and `/dev/kvm` plus `/dev/bus/usb` were absent. This adds fresh focused reducer execution only; no fresh Gradle compilation/test task, APK assembly, device, authentication, release, or end-to-end evidence.
- Task 5 delivery verification on 2026-07-25 passed `/root/.openclaw/workspace/scripts/hermes-mobile-preflight.sh`; from `apps/mobile/android`, `GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew --offline --no-daemon -Dorg.gradle.jvmargs= -Dorg.gradle.daemon=false -Pkotlin.compiler.execution.strategy=in-process :app:testDebugUnitTest :app:assembleDebug` passed (43 tasks, 1 executed); `git diff --check` passed. Current Gradle XML reports record 107 tests with 0 failures/errors/skips. The ignored debug APK reports package `cloud.molberg.hermesmobile`, version `0.1.0-beta.1` (`10001`), size 17,710,960 bytes, and SHA-256 `714e8e9cdd3f2eed93b285f233b1f4573d5d13fc2078bb717631f9b38f8428d4`. ADB reports no attached devices; no emulator/AVD or `/dev/kvm` is available. No device installation, release, or gateway end-to-end verification was performed.

Status: in progress. Android foundation work is complete, and the beta path now targets a remote upstream Hermes Agent gateway/API server directly. The legacy `apps/companion` server is compatibility-only and not required for future Android releases.

Done:
- Native Kotlin/Compose Android shell replaces the web-first mobile path for the beta surface.
- Android connection flow stores one logical gateway profile with optional Local HTTPS, required Remote HTTPS, Android-keystore-protected bearer/no-auth configuration, and active Local/Remote diagnostics.
- Local-first route selection uses bounded `GET /health` probes, authenticated `GET /v1/models` compatibility checks, deterministic Remote fallback, and foreground/connectivity/request-failure re-evaluation without switching in-flight leases.
- Android no longer calls undocumented legacy companion `/api/*` routes from the direct-gateway client path.
- Capability-gated session streaming binds each OkHttp call to an immutable route/session lease, parses SSE into authoritative final responses, ignores cross-session events, and reports transport failure only against the failed lease.
- Chat UI supports conversation list/thread navigation, native composer, busy state, selectable replies, error bubbles, and new-chat reset.
- Direct gateway compatibility contract is documented in `docs/DIRECT_GATEWAY_ARCHITECTURE.md`.
- Android source packaging identifies the first beta as `versionName` `0.1.0-beta.1` / `versionCode` `10001`, produces a versioned debug APK name, and has a direct-gateway build/install guide in `docs/ANDROID_BETA_BUILD.md`.
- Legacy companion chat, terminal, and file utilities remain in the repo during migration but are not the target architecture.
- Local build artifacts, Android transient build output, `.gradle-user/`, and `.dev/` are ignored.
- Companion and workspace TypeScript typecheck, build, and lint pass as of 2026-07-24.

Remaining for beta:
- Complete B3 after upstream documents a session-search endpoint/query schema and a live gateway can verify advertised session CRUD behavior; the independently verifiable durable-state foundation landed on 2026-07-24, but the current upstream `{method, path}` capability envelope has not been exercised live.
- Exercise the connection/settings unhappy paths on a real device or emulator; this sandbox cannot start ADB because local control sockets are prohibited.
- Exercise a real device or emulator against a running upstream Hermes gateway/API server.
- Verify direct gateway behavior end to end beyond B2: chat request/response, session continuity expectations, streamed/final output handling, and failure recovery.
- Verify or revise provisional session, streaming, tool-event, artifact, and cancellation route assumptions against official upstream docs.
- Add or run focused Android UI validation for chat/settings flows on small and large screens in an environment with a permitted emulator or real device.
- Confirm adaptive accessibility: font scaling, TalkBack labels, contrast, keyboard/IME behavior, and reduced-motion tolerance.
- Build the source-current `v0.1.0-beta.1` APK, verify its package metadata, and record a clean install, launch, and direct-gateway connection on a named real device or emulator.

## R1 Adaptive/Accessibility Matrix

Source-level safeguards were added and reviewed on 2026-07-24, but this table is **not device evidence**. R1 remains incomplete until each row is exercised and recorded on an emulator or physical device.

| Configuration | Required checks | Status on 2026-07-24 |
| --- | --- | --- |
| Small phone, portrait and landscape | Navigation, chat list/detail, composer with IME, 200% font scale | Blocked — ADB daemon sockets are prohibited and no emulator executable is installed |
| Normal phone, portrait and landscape | Bottom navigation, rotation continuity, long messages/code, light/dark contrast | Blocked — ADB daemon sockets are prohibited and no emulator executable is installed |
| Tablet, portrait and landscape | Navigation rail, two-pane sessions/chat, pane focus order, resizing | Blocked — ADB daemon sockets are prohibited and no emulator executable is installed |
| Accessibility services | TalkBack labels/order/announcements, switch and selected-state descriptions, 48dp targets | Blocked — requires emulator/device accessibility service walkthrough |
| Motion and keyboard | Animator duration scale off, IME resize/insets, send/cancel visibility | Blocked — requires emulator/device settings and keyboard interaction |

Source-level evidence without device verification: orientation is no longer manifest-locked; the activity uses `adjustResize`; the required recovery preflight passed immediately before this run; `git diff --check` passed; and direct JUnit execution of the cached, source-current Android unit classes passed all 61 tests, including all 4 `AdaptiveQualityTest` cases covering adaptive thresholds, dense-control stacking, long-text bounds, and selected light/dark contrast pairs. A direct writable-cache Gradle retry was blocked before project execution by `java.net.SocketException: Operation not permitted`. ADB 37.0.0 exists at `/opt/android-sdk/platform-tools/adb`, but its daemon cannot create the sandbox-prohibited smart-socket/netlink sockets. No emulator executable, AVD, `/dev/kvm`, USB device bus, or running target is available.

## Beta Release Criteria

No beta release is claimed. Source packaging and documentation are complete, but APK assembly in this sandbox, clean installation, direct-gateway device exercise, R1, and B3 remain unverified or externally blocked.

- Native Kotlin/Compose Android app is the shipped beta client.
- No WebView, Capacitor runtime dependency, fake backend, embedded secrets, or new external infrastructure is introduced for beta.
- Direct gateway transport and auth are exercised against the upstream Hermes gateway/API server.
- Chat/session/streaming behavior is exercised with Hermes, including success, unauthorized, timeout, server error, malformed response, and stream interruption cases.
- Settings connection flow is reliable: save, validate, health, Hermes test, offline/unauthorized states, and recovery are clear.
- Adaptive accessibility passes on target Android devices or emulators.
- Required checks pass: `./gradlew :app:testDebugUnitTest :app:assembleDebug` from `apps/mobile/android` and relevant source lint.
- Release notes clearly list remaining known beta limitations.