# 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 - [ ] **B2 — Direct gateway connection and authentication UX** - Server connection screen with validation, `GET /health`, bearer/no-auth configuration, optional `GET /v1/models` auth check, offline/unauthorized/retry states. - Store sensitive values using Android-appropriate secure storage; never log secrets. - Verification: connection-state tests and manual unhappy-path walkthrough. - [ ] **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. - [ ] **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. - [ ] **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 - [ ] **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`. - [ ] **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._ - [x] **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. - [x] **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. - [x] **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. - [x] **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. - [x] **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: 1. Read `PROJECT_PLAN.md`, `CHANGELOG.md`, `docs/ROADMAP.md`, git status, and the prior commit. 2. Choose the single highest-value unchecked item or a narrowly scoped sub-item. 3. Inspect existing implementation before rewriting it. Before committing: 1. Run relevant checks; record exact pass/fail scope in the changelog. 2. Update this plan: check the completed item, move it into **Completed**, and leave the next executable item unchecked. 3. Add a concise `CHANGELOG.md` entry under **Unreleased**. 4. Commit using Conventional Commits and push `origin/main`. 5. Do not claim a release without an uploaded, verified versioned APK.