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.