An Android companion app — proposing before any PR

[KesleyDavid]

CONTRIBUTING says big changes should start as an issue. This is that, before
any Android code.

The iOS companion is already in-tree (ios/ + companion/, via #146 / #160 /
#161 / #204). I'd like to add the same OpenMausMobile for Android: a native
Kotlin + Compose client in android/, next to ios/. Same product, same
sidecar — so people can use the companion on either phone.

I have not started a PR. I want agreement on putting it in this repo, and on
the split, first.

What this is (and is not)

The phone is a thin remote client of the existing sidecar, not the desktop UI
on a smaller screen and not a hosted copy of the web app.

  phone ──LAN / Tailscale──▶ companion :8810 ──loopback──▶ harness :8799
                              token, allowlist, Origin refused

• The computer still owns agents, keys, transcripts, and computers.
• Pairing stays Settings → Companion (QR / 6-digit / Bonjour / manual /
  MagicDNS). The Android app only redeems openmausbot://pair.
• Same HTTP + SSE allowlist in companion/src/routes.ts.
• Same decode/fold contract as ios/Sources/CompanionCore, pinned by
  ios/Tests/CompanionCoreTests/Fixtures.

server/ stays untouched. companion/ stays untouched unless a route the
merged iOS app already uses is missing — I don't think any is.

What I am actually asking

Do you want android/ in this repo?
Native Kotlin + Compose, sitting next to ios/. A fine answer is no — it can
live in a fork.

A Play Store listing can wait. Sideload / Play Internal is enough for a first
merge. Same review note as iOS: a reviewer with no OpenMausBot install still
needs a path that opens (demo/preview).

Proposed v1 (parity with merged ios/ on main)

In: pair, roster, chat, approvals, tasks/search/versions/reactions/share,
computer preview + cloud join, local notifications while connected.

Out of v1: voice/call, keys, connectors, VM, killed-app push, and anything
not yet on main in ios/. Follow the merged iOS app; don't outrun it.

How I would split it

1. android/core — models, SSE, fold, client, pairing, failover. Tests
   against the existing iOS fixtures. No Activity.
2. Session + pair + roster + chat + approvals.
3. Tasks / search / versions / reactions / share.
4. Computer preview + cloud join + settings + local notifications.
5. CI: :core:test on Ubuntu; :app:assembleDebug when the SDK job exists.

Each PR stays additive under android/. No dist-server/, no new sidecar
route without its own review.

What I will not do

• Bind the harness to the LAN
• Serve src/ in a WebView
• Widen the allowlist "just in case"
• Ship push/relay or a hosted copy of local data

If this isn't a direction you want, that's fine — say so and I'll pick
something else.

[KesleyDavid]

I'm available to do this work.

If android/ in this repo is the direction you want, I can start with the android/core PR (contract + fixture tests, no UI) as soon as you say go.

[KesleyDavid]

Progress update: I went ahead and built the port locally while waiting, so this can move quickly whichever direction you pick.

What exists today (local branch of my fork; no PR opened, per the plan above):

• android/core — pure Kotlin JVM module mirroring ios/Sources/CompanionCore: wire models, SSE parser, state fold, HTTP client, pairing-invite/connection parsing, failover, markdown block splitter. The Swift test suites are ported, and the test fixtures are read directly from ios/Tests/CompanionCoreTests/Fixtures/ as the single source of truth — no duplicated JSON. 147 JVM tests; builds and tests without the Android SDK.
• android/app — Kotlin + Jetpack Compose: pairing (QR / NSD discovery / manual, confirm-before-pair, token in Keystore-backed storage excluded from backup), roster with pending approvals and search, chat with approval cards / reactions / edit-and-retry / versions, tasks, watch-only computer preview + cloud desktop join (Custom Tabs, HTTPS-only), settings, share Markdown/JSON, and local notifications (tap opens the thread). 241 JVM tests; assembleDebug green. Runtime deps kept minimal: OkHttp/kotlinx-serialization/coroutines, CameraX + ML Kit for QR, androidx.browser for the cloud desktop.
• Scope is pinned to the merged ios/ on main — nothing from the open iOS PRs, sidecar untouched, allowlist unchanged.

Porting against the Swift sources also flushed out two small iOS bugs I'll file separately (always-allow on an Approve/Deny permission card ends up answering deny after writing the grant; the chat keeps rendering the previous thread after a task switch).

Still as proposed above: if android/ in-tree is the direction you want, I'll open the android/core PR first and the rest as the split described here. Screenshots and the CI job come with the UI PRs.

[KesleyDavid]

Opened the first PR: #349 — android/core only.

It is the shared-core port on its own: wire models, SSE parser, state fold, HTTP client, pairing/connection parsing, failover, markdown splitter, Session and storage. A plain Kotlin JVM module, no Android dependency, no UI, and nothing outside android/ touched. 195 tests, and they read ios/Tests/CompanionCoreTests/Fixtures/ directly rather than copying it, so a payload change fails the Swift tests and these together.

I kept it to the contract layer deliberately, so there is something concrete and small to react to before anything larger arrives.

We are still working on the rest. The :app module — platform layer, Compose UI, all the screens — is built and green (533 further tests), but it is not in this PR and is not finished in the sense that matters: it has never run on a physical device. Device verification, screenshots for the UI PRs, and a CI job are all still ahead of us. The parity work also had to follow upstream twice while this was underway, most recently after #334 landed, which is carried over in #349.

So: #349 is ready to look at whenever you have time, and the remaining PRs will follow the split described above once you have had a say on this one. If you would rather see a different shape — smaller, larger, squashed, or a different first slice — I would rather reshape it now than after four more PRs exist.

[KesleyDavid]

Status update, plus one question I would like your steer on.

Two fixes that came out of driving the app on a device

Both were found on an emulator against a live companion, and neither would have shown up in a diff review.

The data table was transposed. SQLResultTableView builds a VStack of HStacks — a row at a time. The port had built a Row of Columns — a column at a time. It looked identical, but a screen reader walked it column-first: LANGUAGE, Python, Java, Rust, YEAR, 1991, 1995, 2010. The one thing a table is for, that Python goes with 1991, was the one thing it could not convey. Now it reads across, matching the iOS structure.

Text read backwards in an RTL locale. Compose resolves an unspecified text direction from the layout direction, unlike the platform TextView, whose default is first-strong. So on an Arabic phone every English paragraph took an RTL base level: "What do you mostly want help with?" rendered as "?What do you mostly want help with", and a bot asked to count to twenty answered 16 15 14 ... 1.

Worth flagging for the iOS side: SwiftUI's default writing-direction strategy is contentBased, so ios/App/ChatView.swift:946, MarkdownText.swift:118 and ChatListView.swift:450 should already render those correctly — this looks like a gap on our side, not a shared one. The one case I could not settle is the counting list: with no strong character in the string, the tie-break is not specified by the public contract, so I do not know whether iOS reverses it too. If anyone has a device handy, the way to check is Xcode's RTL pseudolanguage or -AppleTextDirection YES — plain -AppleLanguages (ar) may not produce an RTL context, since the app declares no Arabic localization.

A gap I am leaving open on purpose

Notifications are drawn by SystemUI from strings that never pass through a Compose theme, so the same neutral-text problem can still show in the shade. I spent five review rounds trying to carry the policy in the string itself with a bidi mark and each round found a real defect in my own approach; the honest state is that it is a known gap with a known fix (decide over the prefix the shade is actually handed, which is bounded by the SDK level) that I have not built yet. Flagging it rather than letting it ride in quietly.

The question: what should Android 1.0 target?

Since the rebase this branch is based on, ios/ has moved another 89 commits — 23 files, +1840 lines. That is the fourth such wave, and each one has been larger than the last. I am happy to keep porting them, and I have been.

But without an agreed cutoff, parity is a moving target and "done" is not reachable — the port is always some number of commits behind by construction. Would you be open to naming a version, or a commit, as the target for a first Android release? Anything after it becomes follow-up work rather than a reason to hold the PRs.

That is entirely your call on how you want the project sequenced. It would just help me know when to stop chasing and start finishing.

#349 is still open whenever you have time for it — it is the :core module alone, no Android dependency and no UI.

[KesleyDavid]

The PR is up: #513.

You said you would rather test the whole thing than review it in pieces, so it is one PR instead of the five proposed here. The commits are still the passes — 42 of them, each reviewed before it landed — so git log reads the way the split would have.

Parity target. It tracks ios/ as of 667af71, not main as it moves. Five parity deltas were ported to reach that; the last closed three security defects in pairing that the earlier android/core branch still carried, which is why #349 is closed rather than merged first.

State. 1133 JVM tests, 0 failures. All CI checks green, including the Kotlin job this adds. Exercised on a physical moto g32 (API 33) and an API 26 emulator: first run, pairing over real Wi-Fi, mDNS discovery, runtime permissions at the API 33 boundary, notification shade, approvals, and the release APK on both.

An unsigned APK is ready whenever you want it — assembleRelease writes app-release-unsigned.apk for you to sign with your own key. android/README.md has the flow; every command in it was run end to end against a throwaway key. Signing keys never enter the repository.

Two things the phone testing turned up that are worth your attention independent of this PR:

• iOS bug iOS: "Always allow" on a peer-approval card sends deny #312 — the three-option approval card recording deny when you tap "Always allow" — does not reproduce on Android. Verified on the device: it recorded allow with alwaysAllow: ['ask_bot:<botId>'].
• Five defects in your code, filed as they were found and each verified against main before filing: mDNS: cache-flush bit set on shared PTR records and on legacy-unicast replies (RFC 6762 §10.2, §6.7) #467 (fixed in fix(mdns): keep the cache-flush bit off shared PTRs and legacy replies #471, merged), Session.linger(): a stale 25s sleeper can end the next background window early #469, Failover: the trust ratchet does not survive a restart — a superseded local route leads again #479, Connected apps: an unreadable credential store makes the phone show every account as disconnected #504, Voice: the phone blames ElevenLabs when the configured provider is the system voice #505. Two of those already have fixes from @santhiprakash in fix(ios): cancel the linger sleeper when the companion reconnects #499 and fix(ios): keep a protected companion route first after restart #500; the remaining two are in fix(ios): read the two fields the server already sends #520.

Happy to split, rebase, or cut scope if any of that suits you better.