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.
• 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.
• Confirm adaptive accessibility: font scaling, TalkBack labels, contrast, keyboard/IME behavior, and reduced-motion tolerance.
• Document beta install/run steps after the native build is verified.

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

• 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.