Hermes Mobile — Delivery Plan

Operational contract: Codex must read this file before each work loop. Work exactly one coherent milestone at a time. Move completed items to the completed section in the same commit that implements them. Add a concise entry to CHANGELOG.md in the same commit. Never mark work complete without running its listed verification.

Product guardrails

Native Android client for upstream Hermes Agent: Kotlin + Jetpack Compose.
Material 3 base, deliberately customized through a reusable design system.
Thin client: Hermes remains the authority for auth, sessions, streaming, tool semantics, and backend behavior.
No WebView-first app, no cloned Hermes backend, no embedded credentials.
Adaptive, accessible, compact-but-readable UI: phone, tablet, light/dark, font scaling, IME/keyboard, long code/output must remain safe.
Keep DTO/transport, domain/UI models, repositories, view models/state, and composables separated.
Never commit APKs, build outputs, credentials, or generated local environment files.

Release policy

Start artifacts at v0.1.0-beta.1.
Patch: compatible fixes/polish. Minor: a coherent feature milestone. Major: stable v1.0.0+ only.
A release requires a pushed source commit, passing relevant checks, a versioned APK artifact, and a Telegram release post.

Now — direct gateway pivot

Complete the Android/client contract pivot before implementing backend behavior. The next release path targets a remote upstream Hermes Agent gateway/API server directly; apps/companion is legacy compatibility only.

Beta path — upstream-connected MVP

B3 — Direct gateway session contract and durable chat state
- Fetch/list/search/select/create sessions through repository contracts after upstream session routes are verified.
- Restore selected session and protect against duplicate sends / lost drafts.
- Verification: fake-repository UI tests; direct gateway compatibility checks where available.
- Foundation verified 2026-07-24: repository search contract and fake implementation, capability-negotiated session list/create/get/delete request mapping, durable selected-session/draft/pending-send storage, and duplicate-send reducer/UI protection.
- Still blocked: official upstream docs do not document a session-search endpoint or query schema, and no live gateway compatibility exercise is available in this sandbox. Keep B3 unchecked until search and real gateway behavior are verified.
Queued after B3 — B4: Direct gateway streaming, reconnects, and resilient long-running work
- Stream event reducer: final response/token deltas first; tool lifecycle, session events, artifacts, cancel, and reconnect/backoff only where upstream capability is verified.
- Preserve partial output and make recovery obvious and safe.
- Verification: deterministic fake stream tests and real direct gateway exercise.
Queued — B5: Tool, artifact, and output experience
- Compact tool cards with lifecycle/status, expandable output, copy/share/save affordances.
- Safe rendering for large logs and code; no unbounded nested scroll failures.
- Artifact/file handoff only where upstream capability is actually supported.
- Verification: large-output and rotation/resume checks.

Beta hardening and release

Queued — R1: Adaptive/accessibility quality pass
- Small phone, normal phone, tablet/two-pane behavior; portrait/landscape.
- Font scaling, TalkBack semantics, contrast, touch targets, reduced motion, IME behavior.
- Verification: emulator/device matrix evidence documented in docs/ROADMAP.md.
Queued — R2: Beta packaging and install guide
- Version v0.1.0-beta.1, reproducible debug/beta APK build, install/run guide, known limitations.
- Publish source commit, APK, release notes, and verification result.
- Verification: clean install on a real device or emulator plus full required checks.

V2 backlog

Multiple server profiles and fast switching.
Rich file/artifact workflows based on upstream capability.
Notifications for task completion.
Mature tablet/two-pane session + optional terminal/log pane.
Offline cache/search and diagnostic export with privacy controls.
Remove legacy companion Android routes and deprecate apps/companion install/runtime docs after direct gateway chat/session/streaming is verified.

Completed

Move finished items here with date, commit, and verification. Keep this section factual; do not claim unverified work.

B2 — Direct gateway connection, authentication, and local-first routing UX — 2026-07-24, commit e5cc27e (feat: add local-first gateway routing).
- Added one logical profile with optional Local HTTPS, required Remote HTTPS, Android-keystore-protected bearer/no-auth configuration, and active Local/Remote diagnostics.
- Added bounded redirect-disabled GET /health probes followed by bearer-authenticated GET /v1/models, deterministic Local preference/Remote fallback, and immutable request leases.
- Added foreground, explicit reconnect, connectivity-change, and request-failure re-evaluation hooks; removed Android calls to undocumented legacy companion /api/* routes without changing apps/companion.
- Recorded the upstream stable gateway identity-binding need in docs/BLOCKERS.md.
- Verification: direct Kotlin/JUnit execution of ConnectionStateTest and GatewayHttpProbeTest passed 12 tests; GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew --no-daemon -Pkotlin.compiler.execution.strategy=in-process :app:compileDebugUnitTestKotlin :app:assembleDebug passed from apps/mobile/android with temporary restored sandbox-only Gradle socket shims (37 tasks, 6 executed); git diff --check passed.
- Unhappy paths verified deterministically: missing/cleartext/credential-bearing/path-bearing/duplicate URLs, missing bearer token, incompatible or offline Local fallback, Remote offline, unauthorized compatibility response, stored legacy HTTP rejection, and failed-route lease invalidation. Device UI walkthrough was attempted but ADB could not start because this sandbox prohibits local control sockets.
F0 — Audit and safely land existing work — 2026-07-24, commit da79d48 (feat: land native mobile foundation).
- Reviewed existing Android and companion edits; preserved the native Android chat/workspace/settings work and companion chat hardening.
- Confirmed generated build outputs are ignored and added ignores for .gradle-user/ and .dev/.
- Reconciled docs/ROADMAP.md to the actual native Android beta state and remaining validation gaps.
- Verification: git diff --check passed; npm run typecheck --workspace @hermes-mobile/companion passed; npm run lint --workspace @hermes-mobile/companion passed; npm run build --workspace @hermes-mobile/companion passed; npm run typecheck passed; npm run lint passed; npm run build passed.
- Android debug build attempted with GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew :app:assembleDebug from apps/mobile/android; blocked before compilation because network socket creation is not permitted while downloading Gradle 8.11.1.
F1 — Compose design system extraction — 2026-07-24, commit 9ed0969 (feat: extract compose design system).
- Extracted color, semantic status, spacing, typography, shape, elevation, and motion tokens.
- Added light and dark Hermes Compose themes backed by Material 3 color schemes.
- Split shared Compose cards, rows, controls, notices, message bubbles, list scaffolds, and code surfaces out of MainActivity.kt.
- Added Compose previews for small phone, normal phone, tablet width, light theme, and dark theme component coverage.
- Verification: git diff --check passed; GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew :app:assembleDebug from apps/mobile/android passed.
F2 — Polished fake-data chat proving ground — 2026-07-24, commit f65d4ac (feat: add fake chat proving ground).
- Added a local fake chat inbox with session rail/list, context controls, keyboard-safe composer, and send/cancel/retry interactions.
- Added typed user, assistant, system, error, and streaming message models; selectable markdown-friendly text, horizontally scrollable copyable code, and expandable tool results.
- Added seeded empty, loading, reconnecting, and error states plus reducer tests for send, cancel, retry, and tool expansion.
- Verification: git diff --check passed; GRADLE_USER_HOME=/root/hermes-mobile/.gradle-user ./gradlew :app:testDebugUnitTest :app:assembleDebug from apps/mobile/android passed.
B1 — Transport/domain contracts — 2026-07-24, commit feat: add transport domain contracts.
- Added transport DTOs and domain repository contracts for server profiles, authentication, sessions, messages, stream events, tool results, and artifacts.
- Added DTO-to-domain/UI mappers, stream reducer behavior, and a fake Hermes repository for previews and unit tests.
- Kept the companion path as an optional adapter capability without changing upstream Hermes semantics.
- Verification: parent preflight immediately before B1 completion passed: script PASS; Android :app:assembleDebug BUILD SUCCESSFUL, 35 tasks total and 6 executed. Parent also verified git diff --check passed.
B2a — Direct gateway planning and compatibility contract — 2026-07-24, commit docs: pivot mobile contract to direct gateway.
- Added docs/DIRECT_GATEWAY_ARCHITECTURE.md with documented upstream endpoints separated from unverified assumptions.
- Reprioritized the beta path around direct gateway auth, sessions, streaming, and later companion removal.
- Updated Android transport/domain/fake capability contracts and connection copy so new code no longer assumes a companion server.
- Verification: git diff --check passed; Android :app:testDebugUnitTest :app:assembleDebug passed from apps/mobile/android.

Work-loop checklist

Before coding:

Read PROJECT_PLAN.md, CHANGELOG.md, docs/ROADMAP.md, git status, and the prior commit.
Choose the single highest-value unchecked item or a narrowly scoped sub-item.
Inspect existing implementation before rewriting it.

Before committing:

Run relevant checks; record exact pass/fail scope in the changelog.
Update this plan: check the completed item, move it into Completed, and leave the next executable item unchecked.
Add a concise CHANGELOG.md entry under Unreleased.
Commit using Conventional Commits and push origin/main.
Do not claim a release without an uploaded, verified versioned APK.

10 KiB Raw Blame History