feat(hardware-button): press phone volume and power buttons on Android and iOS #3848

Purpose

Agents can't press a phone's volume or power button. Today they fall back to raw adb shell input keyevent on Android and have no route at all on iOS. PR #3817 was going to add a hardware-key command, but it is being cut down to TV-only tv-remote keys, so phones are left out. This issue adds a small, honest phone vocabulary for those buttons. It is a separate decision from the TV remote keys.

iOS can press some hardware buttons; our implementation just has no route for them yet. XCUIDevice.Button has volumeUp and volumeDown, and Appium XCUITest mobile: pressButton accepts volumeup and volumedown on real devices. iOS does not expose a public power or lock button press.

API

agent-device hardware-button volume-up
agent-device hardware-button volume-down
agent-device hardware-button power

await client.command.hardwareButton({ button: 'volume-down' });
// => { action: 'hardware-button', button: 'volume-down', message: 'Pressed hardware button volume-down' }

• One positional argument, <volume-up|volume-down|power>. No aliases. An unknown name returns INVALID_ARGS before any device call.
• No hold verb or duration flag in the MVP (see "Long press" below).
• No --settle and no post-action observation. The command must not activate or re-foreground the session app. This uses action-button's trait set, not press's.
• The result reports that the press was dispatched. It does not report a resulting volume level or screen state.

Ownership: extend the system-button family, not a new dispatcher

packages/contracts/src/system-button-runtime.ts already owns no-argument device presses (home, appSwitcher, actionButton): one fact cell per button, a family unsupported default, and bindSystemButton. This change adds volumeUp, volumeDown and power to SYSTEM_BUTTONS and SYSTEM_BUTTON_LABELS, and adds optional Interactor members volumeUp?(), volumeDown?(), power?(). The positional picks the cell, the way keyboard <status|dismiss|enter> picks a keyboard-family cell.

• Every owner that already calls systemButtonRuntimeOperationFacts gets the new cells refused through its existing unsupported denial. Only the owners in the matrix below name a cell as available.
• No SystemControl union, no key table shared with tv-remote, no android-keycode:N escape hatch, and no case 'hardware-button' dispatcher that bypasses the family binder.
• home, app-switcher and action-button keep their existing commands. hardware-button does not accept home, app-switcher or action, so each button has exactly one public route. Folding action-button into hardware-button would be a separate migration decision.
• On TV targets (Android TV, tvOS), hardware-button refuses with a hint that points to tv-remote. After feat(tv-remote): add hardware and media buttons for TV targets #3817, tv-remote owns TV volume and power keys.

Support matrix (MVP)

Every known platform, device-kind, and provider refusal happens at fact admission, before any adb, runner, or provider dispatch, and uses an existing RuntimeOperationUnavailability reason. A physical device hardware-presence check may run in the runner, but it must refuse before pressing an absent button.

Within an admitted Apple leaf, if hasHardwareButton returns false at press time, the runner returns UNSUPPORTED_OPERATION with a hardware hint. This is the same pattern as actionButton in RunnerTests+CommandExecution.swift. It is never error-text matching.

Press events, not volume settings

hardware-button volume-down sends one button event. What the OS does with it (which stream changes, whether a HUD shows, whether the foreground app intercepts it) is device behavior, and the command does not claim any of it. Setting an absolute volume (Android cmd media_session volume --set, iOS: no public API) is a different feature. If it is wanted, it belongs in the settings catalog (packages/contracts/src/settings-catalog.ts, which has no volume entry today), not here.

power toggles the screen on Android. After a press that turns the screen off, later commands may hit a locked screen. The help text says so. It does not add an automatic wake.

Long press

Long press is not in the MVP. The backends do not agree:

• Android ADB: input keyevent --longpress <code>, already used by tv-remote longpress. Appium Android: mobile: pressKey { isLongPress: true }. Both use a fixed system long-press duration, not a caller-chosen duration.
• Local Apple and Appium iOS: XCUIDevice.press(_:) has no forDuration: overload. Appium's pressButton duration applies only to tvOS.
• Limrun iOS: buttonDown + wait + buttonUp could hold for a duration, but this is unverified.

If long press is added later, represent it as a press shape, without a separate runtime-operation fact cell (ADR 0019 §2). Unsupported shapes must refuse before the button event is sent. Its API and validation are a separate decision.

Out of scope / future (each its own decision)

Completion conditions

1. agent-device hardware-button volume-down on a local Android emulator returns { action: 'hardware-button', button: 'volume-down', message }, and adb shell cmd media_session volume --stream 3 --get reads one step lower than before. volume-up raises it back.
2. agent-device hardware-button power on a local Android emulator changes adb shell dumpsys power mWakefulness from Awake to Asleep. A second press restores Awake.
3. On a physical iPhone over the local runner, hardware-button volume-up succeeds. The evidence is the system volume HUD in a screenshot taken right after, or a changed AVAudioSession.outputVolume read in a fixture app. The session app is not activated or re-foregrounded.
4. hardware-button volume-up on an iOS Simulator, and hardware-button power on any Apple leaf, refuse at admission with a typed reason and hint. No runner request is issued, and a test asserts this. The runner still builds for the Simulator destination.
5. Appium Android: a unit test asserts mobile: pressKey with { keycode: 24 | 25 | 26 }. Appium iOS: a unit test asserts mobile: pressButton with { name: 'volumeup' | 'volumedown' }, and that power is refused. A live run on any Appium Android session, and on a real-device Appium iOS session if available, is posted on the PR. If none is possible, the PR says so.
6. hardware-button volume-up on Android TV and tvOS refuses with a hint to tv-remote. On web, Linux, macOS, HarmonyOS, Vega and Limrun iOS, it refuses at admission.
7. hardware-button sideways returns INVALID_ARGS before any adb, runner or provider call.
8. A provider scenario under test/integration/provider-scenarios/ covers the Android ADB argv and the response shape (integration-progress stays complete). The MCP tool and client.command.hardwareButton exist, and the MCP output schema is derived from CommandResultMap.
9. CLI help, website/docs/docs/commands.md, and every refusal hint name the same backends the facts admit.
10. pnpm check:affected --run passes, including the registry, owner-files and generic-route completeness gates.

Dependencies

• Blocked by: feat(tv-remote): add hardware and media buttons for TV targets #3817 landing in its TV-only form (it removes hardware-key and folds TV volume/power into tv-remote). Rebase onto it so there is exactly one route per target class.
• If the command registry has no room for a descriptor, make a statement-neutral registry split under ADR 0027. Do not raise its cap to bypass the gate. The TV-only update to feat(tv-remote): add hardware and media buttons for TV targets #3817 removes its descriptor and its proposed cap increase.
• Device verification needs a physical iPhone for condition 3 (see docs/agents/device-verification.md). The Android conditions run on any emulator.

Remaining uncertainties

• Whether a volume XCUIDevice.press on a physical iPhone shows the HUD or changes outputVolume while an XCUITest session is attached. Not live-verified. Appium documents it as working on real devices.
• Whether a cloud Appium iOS session reports real-device vs simulator in a way the fact can read before dispatch. If not, the iOS cell refuses unless the provider declares real devices.

Sources

• Apple, XCUIDevice.Button (home, volumeUp, volumeDown, action, camera; Xcode 16.3): https://developer.apple.com/documentation/xcuiautomation/xcuidevice/button
• Apple, hasHardwareButton(_:) (iOS 16+): https://developer.apple.com/documentation/xcuiautomation/xcuidevice/hashardwarebutton(_:)
• Xcode 27.1 SDK header XCUIAutomation.framework/Headers/XCUIDeviceButton.h: XCUIDeviceButtonVolumeUp/Down are XCUI_SIMULATOR_UNAVAILABLE. XCUIDevice.h has only pressButton: (no duration) and no lock button.
• Appium XCUITest mobile: pressButton, performIoHidEvent, lock: https://github.com/appium/appium-xcuitest-driver/blob/master/docs/reference/execute-methods.md#mobile-pressbutton
• Appium UiAutomator2 mobile: pressKey (isLongPress), lock: https://github.com/appium/appium-uiautomator2-driver#mobile-presskey
• Android KeyEvent constants: https://developer.android.com/reference/android/view/KeyEvent
• @limrun/api 0.64.1 ios-client.d.ts PerformAction buttonDown/buttonUp button names.
• Precedent: feat(action-button): press the iPhone Action Button #2699 / feat(action-button): press the iPhone Action Button #2702 (action-button), refactor(system-button): declare home, app-switcher and action-button as one button family #2715 (system-button family), PR feat(tv-remote): add hardware and media buttons for TV targets #3817 (Android emulator volume transcript, as reported).