Skip to content

Commit 7e86d46

Browse files
committed
feat(action-button): press the iPhone Action Button
Add `agent-device action-button` and `client.command.actionButton()`: one press of the iPhone/iPad Action Button, shaped like `home` rather than `tv-remote`. XCUITest exposes `XCUIDevice.press(.action)` with no hold duration, so there is no `long-press` and no `--duration-ms`, and the slide surface on the same edge belongs to Camera Control, which this command does not drive. The press is declared as a runner-lifecycle command on the Swift side so the app-activation preflight cannot foreground the app the press is meant to leave alone, and no post-action observation is declared. Which model actually carries the button is not in `DeviceInfo`, so the Apple fact claims the iPhone/iPad leaf and the runner answers for the hardware with `hasHardwareButton(.action)`, reporting a typed `UNSUPPORTED_OPERATION`. Every other platform states its own refusal cell. Verified on iOS Simulators: an iPhone 17 Pro press returns `Pressed Action Button` with no runner activation for that command, and an iPhone SE (3rd gen) refuses with `UNSUPPORTED_OPERATION` on both the CLI and the typed client, repeatably and without invalidating the session. Closes #2699
1 parent d688926 commit 7e86d46

66 files changed

Lines changed: 537 additions & 7 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2080,6 +2080,18 @@ extension RunnerTests {
20802080
case .appSwitcher:
20812081
performAppSwitcherGesture(app: activeApp)
20822082
return Response(ok: true, data: DataPayload(message: "appSwitcher"))
2083+
case .actionButton:
2084+
guard pressActionButton() else {
2085+
return Response(
2086+
ok: false,
2087+
error: ErrorPayload(
2088+
code: "UNSUPPORTED_OPERATION",
2089+
message: "actionButton requires a device model with an Action Button",
2090+
hint: "The Action Button is on iPhone 15 Pro and later and iPad Pro (M4) and later. Assign a Shortcut or App Intent to it in Settings > Action Button."
2091+
)
2092+
)
2093+
}
2094+
return Response(ok: true, data: DataPayload(message: "actionButton"))
20832095
case .keyboardDismiss:
20842096
let result = dismissKeyboard(app: activeApp)
20852097
if result.wasVisible && !result.dismissed {

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ final class RunnerCommandJournal {
137137
return false
138138
case .tap, .mouseClick, .longPress, .drag,
139139
.remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText, .back,
140-
.backInApp, .backSystem, .home, .rotate, .appSwitcher, .keyboardDismiss, .keyboardReturn,
140+
.backInApp, .backSystem, .home, .rotate, .appSwitcher, .actionButton, .keyboardDismiss, .keyboardReturn,
141141
.alert, .sequence, .gesture, .gestureViewport, .recordStart, .recordStop,
142142
.status, .uptime, .activate, .terminate, .targetReset, .shutdown:
143143
return true

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,25 @@ extension RunnerTests {
124124
#endif
125125
}
126126

127+
/// Presses the iPhone Action Button.
128+
///
129+
/// `XCUIDevice.press(_:)` has no hold-duration overload, so a single press is the whole gesture
130+
/// this API can express. `hasHardwareButton(.action)` is what separates a model with the button
131+
/// from one without; returning false rather than pressing anyway is what stops a model without
132+
/// the hardware from reporting a press that never happened.
133+
@discardableResult
134+
func pressActionButton() -> Bool {
135+
#if os(iOS)
136+
if #available(iOS 16.0, *) {
137+
guard XCUIDevice.shared.hasHardwareButton(.action) else { return false }
138+
}
139+
XCUIDevice.shared.press(.action)
140+
return true
141+
#else
142+
return false
143+
#endif
144+
}
145+
127146
func findElement(app: XCUIApplication, text: String) -> XCUIElement? {
128147
let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR identifier CONTAINS[c] %@ OR value CONTAINS[c] %@", text, text, text)
129148
let element = app.descendants(matching: .any).matching(predicate).firstMatch

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ enum CommandType: String, Codable {
2323
case home
2424
case rotate
2525
case appSwitcher
26+
case actionButton
2627
case keyboardDismiss
2728
case keyboardReturn
2829
case alert
@@ -94,7 +95,11 @@ extension CommandType {
9495
return CommandTraits(isInteraction: false, readOnly: .conditional, isLifecycle: false)
9596

9697
// Runner-lifecycle commands: skip the app-activation preflight.
97-
case .recordStop, .uptime, .terminate, .targetReset, .shutdown:
98+
// .actionButton joins this group for its one property, not for a lifecycle meaning: a hardware
99+
// Action Button press has to reach a Shortcut or App Intent whether the session app is
100+
// foregrounded, backgrounded, or terminated, and the activation preflight would foreground it
101+
// first (#2699). It is not read-only, so it never takes the session-invalidating retry.
102+
case .actionButton, .recordStop, .uptime, .terminate, .targetReset, .shutdown:
98103
return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: true)
99104

100105
case .status:

‎packages/command-registry/src/__tests__/command-result.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,7 @@ test('CommandResultMap is seeded only from already-existing contract result type
150150
| 'back'
151151
| 'orientation'
152152
| 'app-switcher'
153+
| 'action-button'
153154
| 'clipboard'
154155
| 'appstate'
155156
| 'keyboard'

‎packages/command-registry/src/command-result.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import type {
1010
TriggerAppEventCommandResult,
1111
} from '@agent-device/contracts/device';
1212
import type {
13+
ActionButtonCommandResult,
1314
AppSwitcherCommandResult,
1415
BackCommandResult,
1516
HomeCommandResult,
@@ -56,6 +57,7 @@ import type { ReplayCommandResult, ReplaySuiteResult } from '@agent-device/contr
5657
* re-read of the handler's literal return; see the per-type docstrings.
5758
*/
5859
export interface CommandResultMap {
60+
'action-button': ActionButtonCommandResult;
5961
'app-switcher': AppSwitcherCommandResult;
6062
appstate: AppStateCommandResult;
6163
back: BackCommandResult;

‎packages/command-registry/src/registry.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ import { networkDumpUse } from '@agent-device/contracts/network-runtime-plan';
3939
import { inventoryUse } from '@agent-device/contracts/platform-module';
4040
import {
4141
alertRuntimePlanUses,
42+
actionButtonRuntimeUse,
4243
appEventRuntimeUse,
4344
appStateRuntimeUses,
4445
appSwitcherRuntimeUse,
@@ -1524,6 +1525,19 @@ export const RAW_COMMAND_DESCRIPTORS = [
15241525
batchable: true,
15251526
platformExecution: { kind: 'device-runtime', uses: [appSwitcherRuntimeUse] },
15261527
},
1528+
{
1529+
name: 'action-button',
1530+
...(ownerFilesEnabled ? { ownerFiles: ['src/commands/system/index.ts'] as const } : {}),
1531+
catalog: { group: 'public', key: 'actionButton' },
1532+
frameworkTier: 'extended',
1533+
// Admission is the owner's `actionButton` fact, the same ADR 0019 §9 shape as `home`. The
1534+
// generic mutating traits are load-bearing beyond their shared shape: no post-action
1535+
// observation is declared, because the Action Button's Shortcut/App Intent delivery is
1536+
// expected to reach a backgrounded or terminated app, and settling would re-capture (and so
1537+
// foreground) the app the press is supposed to leave alone (#2699).
1538+
...GENERIC_MUTATING_COMMAND_TRAITS,
1539+
platformExecution: { kind: 'device-runtime', uses: [actionButtonRuntimeUse] },
1540+
},
15271541
{
15281542
name: 'install-from-source',
15291543
deviceClaimPolicy: 'none',

‎packages/contracts/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,10 @@
6464
"types": "./src/app-state-runtime.ts",
6565
"default": "./src/app-state-runtime.ts"
6666
},
67+
"./action-button-runtime": {
68+
"types": "./src/action-button-runtime.ts",
69+
"default": "./src/action-button-runtime.ts"
70+
},
6771
"./app-switcher-runtime": {
6872
"types": "./src/app-switcher-runtime.ts",
6973
"default": "./src/app-switcher-runtime.ts"
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import type { Interactor, RunnerContext } from './interactor-types.ts';
2+
import type { RuntimeOperationFact } from './platform-runtime.ts';
3+
import type { SnapshotRuntimeExecution } from './snapshot-runtime.ts';
4+
5+
/**
6+
* Neutral intent for one Action Button press: no arguments, because `XCUIDevice.press(.action)`
7+
* takes none. Only runner metadata travels, so this is `home`'s shape — the two differ in what
8+
* they do to the device, not in what they carry.
9+
*/
10+
export type ActionButtonInput = Readonly<{
11+
options?: Readonly<{ appBundleId?: string }>;
12+
/** Same runner metadata a capture needs; reuses that type rather than restating it. */
13+
execution?: SnapshotRuntimeExecution;
14+
}>;
15+
16+
/** The press returns nothing; a result type here would be a surface the command never has. */
17+
export type ActionButtonRuntimeOperations = Readonly<{
18+
actionButton(input: ActionButtonInput): Promise<void>;
19+
}>;
20+
21+
export type ActionButtonRuntimeOperationFacts = Readonly<{
22+
actionButton: RuntimeOperationFact;
23+
}>;
24+
25+
export function actionButtonRuntimeOperationFacts(
26+
input: Readonly<{ actionButton: RuntimeOperationFact }>,
27+
): ActionButtonRuntimeOperationFacts {
28+
return Object.freeze({ actionButton: input.actionButton });
29+
}
30+
31+
/**
32+
* Captures one selected owner's interactor authority for the lifetime of a request binding.
33+
*
34+
* The member is required rather than optional even though only Apple can press the button, which is
35+
* how `tvRemote` already handles a button only some owners have. An optional member would turn a
36+
* fact that advertises the press without an interactor that performs it into a successful-looking
37+
* no-op, and the response would report a press that never happened. Owners without the hardware
38+
* declare the refusal on the interactor, and the fact is what keeps that throw off every supported
39+
* path.
40+
*/
41+
export function bindActionButton(
42+
signal: AbortSignal,
43+
resolveInteractor: (runner: RunnerContext) => Promise<Interactor>,
44+
): ActionButtonRuntimeOperations {
45+
return Object.freeze({
46+
actionButton: async (input: ActionButtonInput) => {
47+
signal.throwIfAborted();
48+
const interactor = await resolveInteractor({
49+
...input.execution,
50+
appBundleId: input.options?.appBundleId,
51+
signal,
52+
});
53+
await interactor.actionButton();
54+
},
55+
});
56+
}

‎packages/contracts/src/client-system.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,8 @@ export type OrientationCommandOptions = DeviceCommandBaseOptions & {
9292

9393
export type AppSwitcherCommandOptions = DeviceCommandBaseOptions;
9494

95+
export type ActionButtonCommandOptions = DeviceCommandBaseOptions;
96+
9597
export type TvRemoteCommandOptions = DeviceCommandBaseOptions & {
9698
button: TvRemoteButton;
9799
durationMs?: number;

0 commit comments

Comments
 (0)