build: establish Android beta packaging
This commit is contained in:
Hermes Agent
@@ -0,0 +1,94 @@
|
||||
# Android Beta Build and Install
|
||||
|
||||
This guide covers the native Kotlin/Compose direct-gateway client at version `v0.1.0-beta.1`. It does not build or require `apps/companion`, publish an APK, or complete the beta release criteria by itself.
|
||||
|
||||
## Package identity
|
||||
|
||||
- Application ID: `cloud.molberg.hermesmobile`
|
||||
- Android `versionName`: `0.1.0-beta.1`
|
||||
- Android `versionCode`: `10001`
|
||||
- Debug APK: `apps/mobile/android/app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk`
|
||||
|
||||
`versionName` is the user-visible semantic version. `versionCode` is an internal monotonically increasing Android package revision and must increase for every later installable build.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- JDK 17 or newer supported by the checked-in Android Gradle Plugin.
|
||||
- Android SDK platform 35, matching build tools, and platform tools.
|
||||
- Network access for the first dependency resolution, or a complete compatible Gradle cache.
|
||||
- For installation, a real Android device with USB debugging enabled or a running emulator visible to `adb`.
|
||||
- For use, an HTTPS upstream Hermes Agent gateway/API server and its bearer token when authentication is enabled.
|
||||
|
||||
Do not run Capacitor synchronization for this client. The beta application source is the native project under `apps/mobile/android`.
|
||||
|
||||
## Build and test
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
cd apps/mobile/android
|
||||
GRADLE_USER_HOME="$PWD/../../../.gradle-user" ./gradlew \
|
||||
:app:testDebugUnitTest \
|
||||
:app:assembleDebug
|
||||
```
|
||||
|
||||
The expected APK is:
|
||||
|
||||
```text
|
||||
app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
|
||||
```
|
||||
|
||||
Confirm the package metadata before distributing the file:
|
||||
|
||||
```bash
|
||||
aapt dump badging app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk \
|
||||
| sed -n '1p'
|
||||
sha256sum app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
|
||||
```
|
||||
|
||||
Expected badging includes package `cloud.molberg.hermesmobile`, `versionCode='10001'`, and `versionName='0.1.0-beta.1'`.
|
||||
|
||||
The debug APK is signed with the local Android debug key. It is suitable for beta verification, not a production signing or store-release workflow. APKs and build output must remain untracked.
|
||||
|
||||
## Clean install and run
|
||||
|
||||
Confirm that exactly one intended target is attached:
|
||||
|
||||
```bash
|
||||
adb devices -l
|
||||
```
|
||||
|
||||
Remove any prior installation, then install the newly built APK. Uninstalling clears existing Hermes Mobile app data and stored gateway credentials.
|
||||
|
||||
```bash
|
||||
adb uninstall cloud.molberg.hermesmobile || true
|
||||
adb install app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
|
||||
adb shell monkey -p cloud.molberg.hermesmobile -c android.intent.category.LAUNCHER 1
|
||||
```
|
||||
|
||||
In Hermes Mobile Settings, configure the upstream gateway directly:
|
||||
|
||||
1. Enter the required Remote HTTPS gateway base URL and, optionally, a Local HTTPS URL for the same trusted gateway.
|
||||
2. Select bearer authentication and enter the gateway token when required, or select no authentication only when the gateway is configured that way.
|
||||
3. Save and test the connection. The client probes `/health`, validates compatibility through the authenticated gateway surface, and displays the active Local or Remote route.
|
||||
4. Exercise chat/session behavior only where the gateway advertises the required capabilities.
|
||||
|
||||
Do not enter a legacy companion URL or companion access key. The beta path is the direct upstream Hermes gateway architecture described in `docs/DIRECT_GATEWAY_ARCHITECTURE.md`.
|
||||
|
||||
## Required install evidence
|
||||
|
||||
Record all of the following before claiming R2 installation verification or a beta release:
|
||||
|
||||
- The source commit used for the build.
|
||||
- Passing Android unit tests and APK assembly.
|
||||
- `aapt` package/version output and the APK SHA-256.
|
||||
- A successful clean `adb install` on a named real device or emulator.
|
||||
- App launch plus direct-gateway configuration and connection result.
|
||||
- Any observed limitations or failures, without treating source-only checks as device evidence.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- R1 adaptive/accessibility verification still requires the documented real-device/emulator matrix.
|
||||
- B3 remains blocked on an official session-search contract and live upstream gateway compatibility evidence.
|
||||
- Direct gateway chat, streaming, tools, artifacts, and recovery remain capability-gated; unsupported or unverified routes are not inferred.
|
||||
- The debug APK is not a published release artifact. No beta release exists until all release criteria in `docs/ROADMAP.md` are genuinely satisfied.
|
||||
@@ -6,6 +6,14 @@ R1 cannot be marked complete from the current sandbox. On 2026-07-24, the requir
|
||||
|
||||
Required unblock evidence: run the required preflight and focused Android tests in an environment that permits them, then record the small-phone, normal-phone, and tablet checks in `docs/ROADMAP.md` across portrait/landscape, font scaling, TalkBack, light/dark contrast, touch targets, reduced motion, and IME behavior. Source review, `git diff --check`, and direct execution of cached test classes are supporting evidence only and do not complete R1.
|
||||
|
||||
## R2 — Clean beta build/install verification
|
||||
|
||||
The `v0.1.0-beta.1` Android package metadata and direct-gateway build/install guide are present in source. On 2026-07-24, the required recovery preflight passed and the source-current offline Gradle `:app:testDebugUnitTest :app:assembleDebug` command passed. Installation verification cannot be completed in the current sandbox.
|
||||
|
||||
ADB is installed, but the R1 evidence above confirms that its daemon sockets are prohibited and that no emulator executable, AVD, `/dev/kvm`, USB device bus, or running target is available. Therefore no source-current beta APK package inspection, clean uninstall/install, launch, or direct-gateway device connection was verified here. No APK was published or uploaded, and no final release criterion is claimed.
|
||||
|
||||
Required unblock evidence: in a permitted environment, run the preflight and Android checks from `docs/ANDROID_BETA_BUILD.md`, record `aapt` package/version output and the APK SHA-256, clean-install on one named real device or emulator, launch the app, configure the upstream Hermes gateway directly, and record the connection result in `docs/ROADMAP.md`.
|
||||
|
||||
## Stable gateway identity binding
|
||||
|
||||
The documented direct gateway routes currently available to Hermes Mobile (`GET /health` and authenticated `GET /v1/models`) do not expose a verified stable gateway instance identifier.
|
||||
|
||||
+5
-2
@@ -12,6 +12,7 @@ Done:
|
||||
- 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.
|
||||
@@ -22,9 +23,9 @@ Remaining for beta:
|
||||
- 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.
|
||||
- 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.
|
||||
- Document beta install/run steps after the native build is verified.
|
||||
- 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
|
||||
|
||||
@@ -42,6 +43,8 @@ Source-level evidence without device verification: orientation is no longer mani
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user