agent-device 0.21.13 → 0.21.15

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift

@@ -48,6 +48,39 @@ extension RunnerTests {
     )
   }
 
+
+
+  @MainActor
+  func executeAppState(command: Command) -> Response {
+    guard let bundleId = command.appBundleId?.trimmedNonEmpty else {
+      return Response(
+        ok: false,
+        error: ErrorPayload(
+          code: "INVALID_ARGS",
+          message: "appState requires appBundleId",
+          hint: "Set appBundleId to the session app's bundle identifier."
+        )
+      )
+    }
+    let state = XCUIApplication(bundleIdentifier: bundleId).state
+    return Response(ok: true, data: DataPayload(applicationState: Self.applicationStateName(state)))
+  }
+
+
+
+  static func applicationStateName(_ state: XCUIApplication.State) -> String {
+    switch state {
+    case .unknown: return "unknown"
+    case .notRunning: return "notRunning"
+    case .runningBackground: return "runningBackground"
+    case .runningForeground: return "runningForeground"
+#if !os(macOS)
+    case .runningBackgroundSuspended: return "runningBackgroundSuspended"
+#endif
+    @unknown default: return "unknown"
+    }
+  }
+
   struct ActiveCommandContext {
     let app: XCUIApplication
 
@@ -133,7 +166,7 @@ extension RunnerTests {
       return try runMainThreadWork(
         "command_execution",
         timeout: max(0.001, deadline.timeIntervalSinceNow),
-        timeoutError: mainThreadExecutionTimeoutError
+        timeoutError: Self.mainThreadExecutionTimeoutError
       ) {
         try self.executeOnMainSafely(
           command: command,
@@ -144,8 +177,8 @@ extension RunnerTests {
     }
     return try runMainThreadWork(
       "command_execution",
-      timeout: mainThreadExecutionTimeout,
-      timeoutError: mainThreadExecutionTimeoutError
+      timeout: Self.mainThreadExecutionTimeout,
+      timeoutError: Self.mainThreadExecutionTimeoutError
     ) {
       try self.executeOnMainSafely(command: command, routeToSpringboard: routeToSpringboard)
     }
@@ -153,6 +186,7 @@ extension RunnerTests {
 
 
 
+  @MainActor
   private func executeOnMainSafely(
     command: Command,
     alertDeadline: Date? = nil,
@@ -222,7 +256,7 @@ extension RunnerTests {
         invalidateCachedTarget(reason: "xctest_recorded_failure")
         return failureResponse
       }
-      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
+      if !hasRetried, command.traits.retryOnSessionLoss, shouldRetryResponse(response) {
         NSLog(
           "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
           command.command.rawValue
@@ -247,8 +281,8 @@ extension RunnerTests {
     while true {
       let failureCountBefore = try runMainThreadWork(
         "recorded_failure_count",
-        timeout: mainThreadExecutionTimeout,
-        timeoutError: mainThreadExecutionTimeoutError
+        timeout: Self.mainThreadExecutionTimeout,
+        timeoutError: Self.mainThreadExecutionTimeoutError
       ) {
         self.currentXCTestFailureCount()
       }
@@ -264,8 +298,8 @@ extension RunnerTests {
       }
       let recordedFailureResponse = try runMainThreadWork(
         "recorded_failure_count",
-        timeout: mainThreadExecutionTimeout,
-        timeoutError: mainThreadExecutionTimeoutError
+        timeout: Self.mainThreadExecutionTimeout,
+        timeoutError: Self.mainThreadExecutionTimeoutError
       ) {
         self.didRecordXCTestFailure(since: failureCountBefore)
           ? self.xctestRecordedFailureResponse(command: command, response: response)
@@ -274,14 +308,14 @@ extension RunnerTests {
       if let recordedFailureResponse {
         try runMainThreadWork(
           "target_invalidation",
-          timeout: mainThreadExecutionTimeout,
-          timeoutError: mainThreadExecutionTimeoutError
+          timeout: Self.mainThreadExecutionTimeout,
+          timeoutError: Self.mainThreadExecutionTimeoutError
         ) {
           self.invalidateCachedTarget(reason: "xctest_recorded_failure")
         }
         return recordedFailureResponse
       }
-      if !hasRetried, shouldRetryCommand(command), shouldRetryResponse(response) {
+      if !hasRetried, command.traits.retryOnSessionLoss, shouldRetryResponse(response) {
         NSLog(
           "AGENT_DEVICE_RUNNER_RETRY command=%@ reason=response_unavailable",
           command.command.rawValue
@@ -289,8 +323,8 @@ extension RunnerTests {
         hasRetried = true
         try runMainThreadWork(
           "target_invalidation",
-          timeout: mainThreadExecutionTimeout,
-          timeoutError: mainThreadExecutionTimeoutError
+          timeout: Self.mainThreadExecutionTimeout,
+          timeoutError: Self.mainThreadExecutionTimeoutError
         ) {
           self.invalidateCachedTarget(reason: "response_unavailable")
           self.sleepFor(self.retryCooldown)
@@ -301,6 +335,7 @@ extension RunnerTests {
     }
   }
 
+  @MainActor
   private func executeOnMain(
     command: Command,
     alertDeadline: Date?,
@@ -386,6 +421,8 @@ extension RunnerTests {
       }
     case .uptime:
       return executeUptime()
+    case .appState:
+      return executeAppState(command: command)
     case .activate:
       guard
         let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
@@ -404,7 +441,7 @@ extension RunnerTests {
         return Response(ok: false, error: ErrorPayload(message: "terminate requires appBundleId"))
       }
       XCUIApplication(bundleIdentifier: bundleId).terminate()
-      if currentBundleId == bundleId {
+      if mainOwned.bundleId == bundleId {
         invalidateCachedTarget(reason: "target_terminated")
       }
       return Response(ok: true, data: DataPayload(message: "app terminated"))
@@ -418,88 +455,130 @@ extension RunnerTests {
     )
   }
 
+
+
+
+  @MainActor
   func prepareActiveCommandContext(
     command: Command,
     routeToSpringboard: Bool = false
   ) -> ActiveCommandPreparation {
-    var activeApp = currentApp ?? app
-    var systemSurface: SystemSurfaceHost? = nil
     if routeToSpringboard {
-      activeApp = springboard
-    } else if shouldSkipAppActivationPreflight(command) {
-      activeApp = resolveAppWithoutActivation(command: command)
-    } else if let presented = presentedSystemSurfaceHost() {
+      return .context(ActiveCommandContext(app: springboard))
+    }
+    switch command.traits.launchPolicy {
+    case .noApp:
+
+
+      if let presented = presentedSystemSurfaceHost() {
+        return .context(ActiveCommandContext(app: presented.app, systemSurface: presented.host))
+      }
+
+
+      return .context(ActiveCommandContext(app: mainOwned.app ?? app))
+    case .presentedSurface:
+
+
+#if os(iOS)
+      return .context(ActiveCommandContext(app: resolveAppWithoutActivation(command: command)))
+#else
+
+
+
+      return prepareActivatedTarget(command: command)
+#endif
+    case .existingApp:
+
+
+      return prepareActivatedTarget(command: command)
+    case .mayLaunch:
+      if shouldSkipAppActivationPreflight(command) {
+
+
+        return .context(ActiveCommandContext(app: resolveAppWithoutActivation(command: command)))
+      }
+      return prepareActivatedTarget(command: command)
+    }
+  }
+
+
+
+
+
+  @MainActor
+  private func prepareActivatedTarget(command: Command) -> ActiveCommandPreparation {
+    if let presented = presentedSystemSurfaceHost() {
 
 
 
-      activeApp = presented.app
-      systemSurface = presented.host
-      if isInteractionCommand(command.command) {
+      if command.traits.isInteraction {
         applyInteractionStabilizationIfNeeded()
       }
-    } else if !isRunnerLifecycleCommand(command.command) {
-      let normalizedBundleId = command.appBundleId?
-        .trimmingCharacters(in: .whitespacesAndNewlines)
-      let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
-      if let bundleId = requestedBundleId,
-        let notRunning = notRunningReadResponse(command: command, bundleId: bundleId)
-      {
-        return .response(notRunning)
+      return .context(ActiveCommandContext(app: presented.app, systemSurface: presented.host))
+    }
+
+    let normalizedBundleId = command.appBundleId?
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    let requestedBundleId = (normalizedBundleId?.isEmpty == true) ? nil : normalizedBundleId
+    if let bundleId = requestedBundleId,
+      let notRunning = notRunningRefusal(command: command, bundleId: bundleId)
+    {
+      return .response(notRunning)
+    }
+    if let bundleId = requestedBundleId {
+      if mainOwned.bundleId != bundleId || mainOwned.app == nil {
+        _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
+      } else {
+        refreshCachedTargetIfProcessChanged(bundleId: bundleId)
       }
+    } else {
+
+      invalidateCachedTarget(reason: "missing_app_bundle")
+    }
+
+
+    var activeApp = mainOwned.app ?? app
+    if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
+      activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
+    } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
+      ensureRunnerHostAppActive(reason: "missing_app_bundle")
+      activeApp = app
+    }
+
+    let skipExistenceWait = canUseFastForegroundAppGuard(
+      activeApp: activeApp,
+      requestedBundleId: requestedBundleId
+    )
+    if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
       if let bundleId = requestedBundleId {
-        if currentBundleId != bundleId || currentApp == nil {
-          _ = activateTarget(bundleId: bundleId, reason: "bundle_changed")
-        } else {
-          refreshCachedTargetIfProcessChanged(bundleId: bundleId)
+        activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
+        guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
+          return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: bundleId)))
         }
       } else {
-
-        invalidateCachedTarget(reason: "missing_app_bundle")
+        return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: nil)))
       }
+    }
 
-      activeApp = currentApp ?? app
-      if let bundleId = requestedBundleId, targetNeedsActivation(activeApp) {
-        activeApp = activateTarget(bundleId: bundleId, reason: "stale_target")
-      } else if requestedBundleId == nil, targetNeedsActivation(activeApp) {
-        ensureRunnerHostAppActive(reason: "missing_app_bundle")
+    if command.traits.isInteraction {
+      if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
+        activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
+      } else if requestedBundleId == nil, activeApp.state != .runningForeground {
+        ensureRunnerHostAppActive(reason: "interaction_missing_app_bundle")
         activeApp = app
       }
-
-      let skipExistenceWait = canUseFastForegroundAppGuard(
+      let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
         activeApp: activeApp,
         requestedBundleId: requestedBundleId
       )
-      if !skipExistenceWait && !activeApp.waitForExistence(timeout: appExistenceTimeout) {
-        if let bundleId = requestedBundleId {
-          activeApp = activateTarget(bundleId: bundleId, reason: "missing_after_wait")
-          guard activeApp.waitForExistence(timeout: appExistenceTimeout) else {
-            return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: bundleId)))
-          }
-        } else {
-          return .response(Response(ok: false, error: .targetAppUnavailable(bundleId: nil)))
-        }
-      }
-
-      if isInteractionCommand(command.command) {
-        if let bundleId = requestedBundleId, activeApp.state != .runningForeground {
-          activeApp = activateTarget(bundleId: bundleId, reason: "interaction_foreground_guard")
-        } else if requestedBundleId == nil, activeApp.state != .runningForeground {
-          ensureRunnerHostAppActive(reason: "interaction_missing_app_bundle")
-          activeApp = app
-        }
-        let skipInteractionExistenceWait = canUseFastForegroundAppGuard(
-          activeApp: activeApp,
-          requestedBundleId: requestedBundleId
+      if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
+        return .response(
+          Response(ok: false, error: .targetAppUnavailable(bundleId: requestedBundleId))
         )
-        if !skipInteractionExistenceWait && !activeApp.waitForExistence(timeout: 2) {
-          return .response(
-            Response(ok: false, error: .targetAppUnavailable(bundleId: requestedBundleId))
-          )
-        }
-        applyInteractionStabilizationIfNeeded()
       }
+      applyInteractionStabilizationIfNeeded()
     }
-    return .context(ActiveCommandContext(app: activeApp, systemSurface: systemSurface))
+    return .context(ActiveCommandContext(app: activeApp))
   }
 
 
@@ -509,9 +588,8 @@ extension RunnerTests {
   private func presentedSystemSurfaceHost() -> (host: SystemSurfaceHost, app: XCUIApplication)? {
 #if os(iOS)
     for host in SystemSurfaceHostRegistry.hosts {
-      let candidate = XCUIApplication(bundleIdentifier: host.bundleId)
-      if candidate.state == .runningForeground {
-        return (host, candidate)
+      if systemSurfaceHostState(host) == .runningForeground {
+        return (host, XCUIApplication(bundleIdentifier: host.bundleId))
       }
     }
     return nil
@@ -520,6 +598,21 @@ extension RunnerTests {
 #endif
   }
 
+
+
+
+
+
+
+  private func systemSurfaceHostState(_ host: SystemSurfaceHost) -> XCUIApplication.State {
+
+
+
+
+
+    return XCUIApplication(bundleIdentifier: host.bundleId).state
+  }
+
   func currentXCTestFailureCount() -> Int {
     return testRun?.failureCount ?? 0
   }
@@ -533,7 +626,7 @@ extension RunnerTests {
     if response.data?.runnerFatal == true {
       return nil
     }
-    guard !isReadOnlyCommand(command), !isRunnerLifecycleCommand(command.command) else {
+    guard command.traits.convertsRecordedFailure else {
       return nil
     }
     return Response(
@@ -546,19 +639,12 @@ extension RunnerTests {
     )
   }
 
-  func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
-#if os(iOS)
-    if command.command == .alert {
-      return true
-    }
-
 
 
 
-
-    if command.command == .actionButton {
-      return true
-    }
+  @MainActor
+  func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
+#if os(iOS)
 
 
 
@@ -605,25 +691,27 @@ extension RunnerTests {
       && command.y != nil
   }
 
+  @MainActor
   private func hasCachedTargetForActivationSkip(command: Command) -> Bool {
-    guard let currentApp, currentApp.state == .runningForeground else { return false }
+    guard let boundApp = mainOwned.app, boundApp.state == .runningForeground else { return false }
     guard let bundleId = command.appBundleId?.trimmingCharacters(in: .whitespacesAndNewlines),
       !bundleId.isEmpty
     else {
       return true
     }
-    return currentBundleId == bundleId
+    return mainOwned.bundleId == bundleId
   }
 
+  @MainActor
   func resolveAppWithoutActivation(command: Command) -> XCUIApplication {
     guard let bundleId = command.appBundleId?
       .trimmingCharacters(in: .whitespacesAndNewlines),
       !bundleId.isEmpty
     else {
-      return currentApp ?? app
+      return mainOwned.app ?? app
     }
-    if currentBundleId == bundleId, let currentApp {
-      return currentApp
+    if mainOwned.bundleId == bundleId, let boundApp = mainOwned.app {
+      return boundApp
     }
     return XCUIApplication(bundleIdentifier: bundleId)
   }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -2,18 +2,19 @@ import XCTest
 import AgentDeviceSnapshotPresentation
 
 extension RunnerTests {
+  @MainActor
   func executeOnMainPrepared(
     command: Command,
     activeApp: XCUIApplication,
     alertDeadline: Date? = nil
   ) throws -> Response {
     var activeApp = activeApp
-    if command.command != .tap && command.command != .type && !isReadOnlyCommand(command) {
+    if command.invalidatesRememberedTextEntryTap {
       clearRememberedTextEntryTap()
     }
     switch command.command {
     case .status, .activate, .terminate, .targetReset, .shutdown, .recordStart, .recordStop, .uptime,
-      .snapshot:
+      .appState, .snapshot:
       return Response(
         ok: false,
         error: ErrorPayload(
@@ -78,20 +79,15 @@ extension RunnerTests {
               app: activeApp,
               policy: synthesizedGesturePolicy(policyKind)
             )
-            let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+            switch performSynthesizedGesture(activeApp, kind: policyKind, context: context, synthesize: {
               synthesizedTapAt(
                 app: activeApp,
                 x: touchPoint.x,
                 y: touchPoint.y,
                 context: context
               )
-            }
-            if case .performed = outcome {
-              logSynthesizedGesturePolicyDecision(
-                kind: policyKind,
-                context: context,
-                fallbackAttempted: false
-              )
+            }) {
+            case .performed(let timing):
               if isTextEntry {
                 waitForTextEntryReadinessAfterTap(app: activeApp, element: element)
               }
@@ -107,13 +103,12 @@ extension RunnerTests {
                   ? match.usedNonHittableFallback
                   : nil
               )
+            case .xctestFallback(let message, let hint):
+              fallback = GestureFallback(strategy: "xctest-coordinate-tap", message: message, hint: hint)
+            case .refused(_, let message, let hint):
+              clearRememberedTextEntryTap()
+              return unsupportedResponse(message: message, hint: hint)
             }
-            logSynthesizedGesturePolicyDecision(
-              kind: policyKind,
-              context: context,
-              fallbackAttempted: true
-            )
-            fallback = gestureFallback(strategy: "xctest-coordinate-tap", from: outcome)
           }
           let (timing, outcome) = performGesture(activeApp) {
             if expectedPoint != nil || match.usedNonHittableFallback {
@@ -149,7 +144,7 @@ extension RunnerTests {
       }
       if let x = command.x, let y = command.y {
         let xCTestChannelPenalized = isSnapshotXCTestChannelPenalized(
-          bundleId: currentBundleId
+          bundleId: mainOwned.bundleId
         )
         let xCTestTextInputProbeSkipped = !shouldProbeCoordinateTapTextInput(
           xCTestChannelPenalized: xCTestChannelPenalized
@@ -162,7 +157,7 @@ extension RunnerTests {
           textInput = nil
           NSLog(
             "AGENT_DEVICE_RUNNER_COORDINATE_TAP_TEXT_INPUT_PROBE_SKIPPED bundle=%@",
-            currentBundleId ?? ""
+            mainOwned.bundleId ?? ""
           )
         }
         var fallback: GestureFallback?
@@ -172,16 +167,18 @@ extension RunnerTests {
             app: activeApp,
             policy: synthesizedGesturePolicy(policyKind)
           )
-          let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+          switch performSynthesizedGesture(activeApp, kind: policyKind, context: context, synthesize: {
             synthesizedTapAt(app: activeApp, x: x, y: y, context: context)
-          }
-          if case .performed = outcome {
-            logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: false)
+          }) {
+          case .performed(let timing):
             rememberTextEntryTap(textInput)
             return gestureResponse(message: "tapped", timing: timing)
+          case .xctestFallback(let message, let hint):
+            fallback = GestureFallback(strategy: "xctest-coordinate-tap", message: message, hint: hint)
+          case .refused(_, let message, let hint):
+            clearRememberedTextEntryTap()
+            return unsupportedResponse(message: message, hint: hint)
           }
-          logSynthesizedGesturePolicyDecision(kind: policyKind, context: context, fallbackAttempted: true)
-          fallback = gestureFallback(strategy: "xctest-coordinate-tap", from: outcome)
         }
         let touchFrame = resolvedTouchVisualizationFrame(app: activeApp, x: x, y: y)
         let (timing, outcome) = performGesture(activeApp) { tapAt(app: activeApp, x: x, y: y) }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift

@@ -139,7 +139,7 @@ final class RunnerCommandJournal {
          .remotePress, .type, .swipe, .scroll, .desktopScroll, .findText, .querySelector, .readText,
          .backInApp, .backSystem, .home, .rotate, .appSwitcher, .actionButton, .keyboardDismiss, .keyboardReturn,
          .alert, .sequence, .gesture, .gestureViewport, .recordStart, .recordStop,
-         .status, .uptime, .activate, .terminate, .targetReset, .shutdown:
+         .status, .uptime, .appState, .activate, .terminate, .targetReset, .shutdown:
       return true
     }
   }

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+GestureExecution.swift

@@ -25,13 +25,17 @@ extension RunnerTests {
     case .performed:
       return nil
     case .unsupported(let message, let hint):
-      return Response(
-        ok: false,
-        error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message, hint: hint)
-      )
+      return unsupportedResponse(message: message, hint: hint)
     }
   }
 
+  func unsupportedResponse(message: String, hint: String?) -> Response {
+    Response(
+      ok: false,
+      error: ErrorPayload(code: "UNSUPPORTED_OPERATION", message: message, hint: hint)
+    )
+  }
+
 
   enum GestureFrame {
     case none
@@ -45,15 +49,6 @@ extension RunnerTests {
     let hint: String?
   }
 
-  func gestureFallback(strategy: String, from outcome: RunnerInteractionOutcome) -> GestureFallback? {
-    switch outcome {
-    case .performed:
-      return nil
-    case .unsupported(let message, let hint):
-      return GestureFallback(strategy: strategy, message: message, hint: hint)
-    }
-  }
-
 
 
 
@@ -62,6 +57,7 @@ extension RunnerTests {
 
 
 
+  @MainActor
   func performGesture(
     _ app: XCUIApplication,
     idleTimeout: Bool = true,