Skip to content

Commit addf05f

Browse files
committed
feat(ios): appstate reads the session app's XCUIApplication state through the runner
iOS appstate answered from the session record alone: after home it still named the app as if in front, and the runtime declared the read unavailable because no Apple target answers a sessionless foreground probe. The session app's own state is a fact the runner has: a new appState runner command reads XCUIApplication(bundleIdentifier:).state and names it (runningForeground, runningBackground, runningBackgroundSuspended, notRunning, unknown). It is a lifecycle read, so the activation preflight is skipped and the state reported is the one the app is in. The Apple runtime admits the read on iOS-family simulators and devices, the handler adds state and source: runner to the session answer when the runner answers, and keeps source: session otherwise. The frontmost app is still not read.
1 parent 6428c54 commit addf05f

30 files changed

Lines changed: 553 additions & 29 deletions

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,38 @@ extension RunnerTests {
4848
)
4949
}
5050

51+
/// The session app's `XCUIApplication.State` by name. A lifecycle read: the activation preflight
52+
/// is skipped, so `runningBackground` after `home` is reported rather than repaired away.
53+
func executeAppState(command: Command) -> Response {
54+
guard let bundleId = command.appBundleId?.trimmedNonEmpty else {
55+
return Response(
56+
ok: false,
57+
error: ErrorPayload(
58+
code: "INVALID_ARGS",
59+
message: "appState requires appBundleId",
60+
hint: "Set appBundleId to the session app's bundle identifier."
61+
)
62+
)
63+
}
64+
let state = XCUIApplication(bundleIdentifier: bundleId).state
65+
return Response(ok: true, data: DataPayload(applicationState: Self.applicationStateName(state)))
66+
}
67+
68+
/// `XCUIApplication.State` by the names the TypeScript `AppleApplicationState` type declares, the
69+
/// same names the activation disclosure gives its prior state.
70+
static func applicationStateName(_ state: XCUIApplication.State) -> String {
71+
switch state {
72+
case .unknown: return "unknown"
73+
case .notRunning: return "notRunning"
74+
case .runningBackground: return "runningBackground"
75+
case .runningForeground: return "runningForeground"
76+
#if !os(macOS)
77+
case .runningBackgroundSuspended: return "runningBackgroundSuspended"
78+
#endif
79+
@unknown default: return "unknown"
80+
}
81+
}
82+
5183
struct ActiveCommandContext {
5284
let app: XCUIApplication
5385
/// Set when `app` is a system surface served in place over the still-bound session app (#2438).
@@ -386,6 +418,8 @@ extension RunnerTests {
386418
}
387419
case .uptime:
388420
return executeUptime()
421+
case .appState:
422+
return executeAppState(command: command)
389423
case .activate:
390424
guard
391425
let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ extension RunnerTests {
1313
}
1414
switch command.command {
1515
case .status, .activate, .terminate, .targetReset, .shutdown, .recordStart, .recordStop, .uptime,
16-
.snapshot:
16+
.appState, .snapshot:
1717
return Response(
1818
ok: false,
1919
error: ErrorPayload(

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ final class RunnerCommandJournal {
139139
.remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText,
140140
.backInApp, .backSystem, .home, .rotate, .appSwitcher, .actionButton, .keyboardDismiss, .keyboardReturn,
141141
.alert, .sequence, .gesture, .gestureViewport, .recordStart, .recordStop,
142-
.status, .uptime, .activate, .terminate, .targetReset, .shutdown:
142+
.status, .uptime, .appState, .activate, .terminate, .targetReset, .shutdown:
143143
return true
144144
}
145145
}

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ enum CommandType: String, Codable, CaseIterable {
3333
case recordStop
3434
case status
3535
case uptime
36+
case appState
3637
case activate
3738
case terminate
3839
case targetReset
@@ -105,7 +106,9 @@ extension CommandType {
105106
case .actionButton:
106107
return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: false)
107108

108-
case .status:
109+
// appState is a read of the session app's XCUIApplication.state; skipping the activation
110+
// preflight is what makes its answer the state the app is in, not the one a repair leaves.
111+
case .status, .appState:
109112
return CommandTraits(isInteraction: false, readOnly: .always, isLifecycle: true)
110113

111114
// Normal preflight, not retried.
@@ -306,6 +309,7 @@ struct DataPayload: Codable {
306309
var referenceWidth: Double?
307310
var referenceHeight: Double?
308311
var currentUptimeMs: Double?
312+
var applicationState: String?
309313
var commandId: String?
310314
var lifecycleState: String?
311315
var lifecycleCommand: String?

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+ApplicationStateRawValueTests.swift‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,17 @@ extension RunnerTests {
2424
assertDecoderPins(.runningForeground, name: "runningForeground", raw: 4)
2525
}
2626

27+
/// The `appState` command names each state for the TypeScript `AppleApplicationState` type.
28+
func testApplicationStateNamesMatchTheAppStateContract() {
29+
XCTAssertEqual(Self.applicationStateName(.unknown), "unknown")
30+
XCTAssertEqual(Self.applicationStateName(.notRunning), "notRunning")
31+
#if !os(macOS)
32+
XCTAssertEqual(Self.applicationStateName(.runningBackgroundSuspended), "runningBackgroundSuspended")
33+
#endif
34+
XCTAssertEqual(Self.applicationStateName(.runningBackground), "runningBackground")
35+
XCTAssertEqual(Self.applicationStateName(.runningForeground), "runningForeground")
36+
}
37+
2738
private func assertDecoderPins(_ state: XCUIApplication.State, name: String, raw: Int) {
2839
XCTAssertEqual(
2940
Int(state.rawValue),

‎apple/runner/RUNNER_PROTOCOL.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,15 @@ than silently applied:
6363
{ "command": "rotate", "orientation": "landscape-left" }
6464
```
6565

66+
```json
67+
{ "command": "appState", "appBundleId": "com.example.app" }
68+
```
69+
70+
`appState` answers `data.applicationState` with the named app's `XCUIApplication.State` by name
71+
(`runningForeground`, `runningBackground`, `runningBackgroundSuspended`, `notRunning`, `unknown`).
72+
It is a lifecycle read, so the activation preflight is skipped and the state reported is the one
73+
the app is in, not the one a repair would leave.
74+
6675
The current command names and per-command traits are defined in:
6776

6877
- `RunnerCommand` in [`../../packages/platform-apple/src/runner/runner-contract.ts`](../../packages/platform-apple/src/runner/runner-contract.ts)

‎contracts/fixtures/runner-requests.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
{"name": "ios-simulator.interactions-type.append", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "type", "text": "hello", "delayMs": 10, "textEntryMode": "append", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
3333
{"name": "ios-simulator.interactions-type.newline", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "type", "text": "\n", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
3434
{"name": "ios-simulator.interactor-action-button.press", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "actionButton", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
35+
{"name": "ios-simulator.interactor-app-state.read", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "appState", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
3536
{"name": "ios-simulator.interactor-app-switcher.open", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "appSwitcher", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
3637
{"name": "ios-simulator.interactor-back.in-app", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "backInApp", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
3738
{"name": "ios-simulator.interactor-back.system", "producer": "packages/platform-apple/src/__tests__/runner-requests.test.ts", "request": {"command": "backSystem", "appBundleId": "com.example.app", "commandId": "<commandId>"}},
Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,22 @@
1+
import type { AppleApplicationState } from '@agent-device/kernel/snapshot';
2+
3+
export type { AppleApplicationState } from '@agent-device/kernel/snapshot';
4+
5+
/** Which app a session-scoped read is about; the Android foreground read needs nothing. */
6+
export type AppStateRuntimeInput = Readonly<{ appBundleId?: string }>;
7+
18
/** Neutral foreground identity returned by a selected platform/provider runtime. */
29
export type AppStateRuntimeResult = Readonly<{
310
package?: string;
411
activity?: string;
12+
/**
13+
* Apple: how the app named by the input is running, as a live runner reads it. It says nothing
14+
* about which app is frontmost; a session app in a background state has left the foreground.
15+
* Absent when no runner session is live to ask, so the read never starts one.
16+
*/
17+
applicationState?: AppleApplicationState;
518
}>;
619

720
export type AppStateRuntimeOperations = Readonly<{
8-
appState(): Promise<AppStateRuntimeResult>;
21+
appState(input?: AppStateRuntimeInput): Promise<AppStateRuntimeResult>;
922
}>;

‎packages/contracts/src/app-state.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { AppleApplicationState } from './app-state-runtime.ts';
12
import type { SessionSurface } from './session-surface.ts';
23

34
/**
@@ -16,7 +17,13 @@ export type AppStateCommandResult =
1617
platform: 'ios' | 'macos';
1718
appName: string;
1819
appBundleId?: string;
19-
source: 'session';
20+
/** `runner` when the runner read the session app's state; `session` when only the record answered. */
21+
source: 'session' | 'runner';
22+
/**
23+
* How the session app is running, as the runner reads it; absent with `source: 'session'`.
24+
* `runningBackground` after `home` says the app left the foreground, not what took it.
25+
*/
26+
state?: AppleApplicationState;
2027
surface: SessionSurface;
2128
/** iOS only — the session device's UDID. */
2229
device_udid?: string;

‎packages/contracts/src/interactor-types.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { AppStateRuntimeResult } from './app-state-runtime.ts';
12
import type { BackMode } from './back-mode.ts';
23
import type { IosSystemSurfaceProvenance } from './ios-system-surface.ts';
34
import type { DeviceRotation } from './device-rotation.ts';
@@ -309,6 +310,11 @@ export type Interactor = {
309310
*/
310311
doubleTap?(x: number, y: number): Promise<Record<string, unknown> | void>;
311312
longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
313+
/**
314+
* How the app the runner context names is running, as the platform reports it. The Apple runner
315+
* reads `XCUIApplication.state`; owners that read the foreground elsewhere leave it undefined.
316+
*/
317+
appState?(): Promise<AppStateRuntimeResult>;
312318
/**
313319
* Move the pointer to a point without pressing. Only pointer-driven
314320
* platforms (web today) implement it; touch platforms have no hover state

0 commit comments

Comments
 (0)