hermes-mobile/docs/ROADMAP.md

Hermes Mobile Beta Roadmap

Current Milestone: Native Android Direct Gateway Contract

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.