## What & why
`keyboard` and `button` drive Android through the simulator-server's
USB-HID transport (`pressKey` / `cmd:"button"`). The guest only receives
those HID events when the AVD exposes a hardware keyboard (`hw.keyboard
= yes`) — the default, but CI / headless AVDs are routinely created with
`hw.keyboard = no` (and `hw.mainKeys = no`), where the guest **silently
drops** them. Because that transport is fire-and-forget, both tools
returned `{ typed }` / `{ pressed }` **success while injecting
nothing**.
This still affects current `main`: after the keyboard refactor,
`makeAndroidImpl` routes Android **TV** to `adb input` but Android
**phones/tablets** still to `typeSimulatorServer` (the HID path).
Fixes#449 (found during 0.13.0 RC E2E testing on a `hw.keyboard=no` AVD
— `argent-test-ci-repro`, the config CI uses).
## Change
Route Android **phone/tablet** key / text / button injection through
`adb shell input text` and `input keyevent` (new
`utils/android-input.ts`), the same on-device transport Android TV and
Vega already use:
- **`keyboard`** — `platforms/android.ts` now sends the non-TV branch to
a `typeAndroidPhone` helper (adb `input`); the Android-TV and iOS
branches are untouched.
- **`button`** — the Android branch presses via `injectAndroidKeycode`;
iOS keeps the simulator-server HID path.
`adb input` lands regardless of `hw.keyboard`, on emulators (any config)
and physical devices alike, and a non-zero exit surfaces as a **thrown
error** instead of a silent no-op — directly addressing the
fire-and-forget concern already called out in the `button` tool. Touch
gestures are unchanged.
## Verification
- **Unit tests — 11/11 pass** (rebased on current `main`): new
`keyboard-android.test.ts` (vocabulary parity vs `NAMED_KEYS`, `input
text` shell-quoting incl. spaces, `input keyevent` mapping, empty-text
no-op, newline rejection) + updated `button.test.ts` (Android `back` now
asserts `KEYCODE_BACK` over adb).
- **eslint** on the changed files: clean.
- **Live tool-server** on a `hw.keyboard=no` AVD: the `keyboard` tool
now issues `adb … shell input text '…'` (vs the RC's HID `pressKey`),
and a failed inject **raises an error** rather than a fake success. The
`adb input` path was independently observed typing/deleting on this
exact AVD during RC testing (where the HID path silently no-op'd).
- Note: a full `tsc --build` / whole-suite run couldn't be completed in
my environment (the `argent-private` submodule isn't checked out, which
breaks the npm workspace install, and `main` added upstream deps my base
lacked). `platforms/android.ts` mirrors the existing `platforms/ios.ts`
branch structure one-for-one, and the pre-rebase revision of this change
passed `tsc --build` + eslint. CI here is authoritative for the full
typecheck.
## Reviewer notes
- `input text` receives the string as one shell-quoted argv token, so
spaces are preserved verbatim; newlines are rejected (they'd truncate
the `input` line) — callers use `key: "enter"`.
- `keys` counts by codepoint, matching the tv/vega/simulator-server
backends.
## Problem
The `button` tool's description states that buttons not present on the
target platform "are rejected with a clear error", but the
implementation accepts any button in the enum on any device. On iOS,
`button: "back"` (there is no hardware back key) returns `{ pressed:
"back" }` — a **silent no-op reported as success**, so an automated
caller believes a back-navigation happened when nothing did. Reproduced
live on an iOS 18.5 simulator.
## Root cause
`execute` (`tools/button/index.ts`) calls `sendCommand` and returns `{
pressed }` unconditionally, with no per-platform validation. The
"rejected … from the backend" promise is also architecturally
impossible: `sendCommand` (`utils/simulator-client.ts`) is
fire-and-forget — it pushes a WebSocket frame and never reads a reply,
so a backend rejection cannot surface to the caller.
## Fix
Validate the requested button against a per-platform set in the tool
layer (the platform is known synchronously from the UDID via
`resolveDevice`), throwing the existing `UnsupportedOperationError` (→
HTTP 400) for buttons that don't exist on the device:
- **iOS:** `home`, `power`, `volumeUp`, `volumeDown`, `appSwitch`,
`actionButton` (no `back`)
- **Android:** `home`, `back`, `power`, `volumeUp`, `volumeDown`,
`appSwitch` (no `actionButton`)
Cross-platform correctness is preserved — `back` still works on Android.
The zod enum stays the union of both platforms' buttons (a flat enum
can't express the dependency); the per-platform `Set` enforces the
refinement. The description is reworded to match (validation lives in
the tool, not "the backend").
## Testing
Adds `test/button.test.ts` — the tool previously had no test.
```
vitest run test/button.test.ts → 4 passed
```
Verified fail-before/pass-after: with `src/tools/button/index.ts`
reverted to `main`, the two rejection tests fail (old code resolves `{
pressed: "back" }` / `{ pressed: "actionButton" }`); with the fix, all
four pass.
---------
Co-authored-by: Filip131311 <contact@filipkaminski.com>
Ignacy Łątka