agent-device 0.20.9 → 0.21.0

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

@@ -1,4 +1,5 @@
 import XCTest
+import AgentDeviceSnapshotPresentation
 
 
 extension RunnerTests {
@@ -164,16 +165,6 @@ extension RunnerTests {
   }
 
 
-  func execute(command: Command) throws -> Response {
-    if command.command == .status {
-      return executeStatus(command: command)
-    }
-    if command.command == .uptime {
-      return executeUptime()
-    }
-    commandJournal.accept(command: command)
-    return try executeAccepted(command: command)
-  }
 
   func executeAccepted(command: Command) throws -> Response {
     commandJournal.start(command: command)
@@ -189,9 +180,7 @@ extension RunnerTests {
 
   func executeStatus(command: Command) -> Response {
     guard
-      let statusCommandId = command.statusCommandId?
-        .trimmingCharacters(in: .whitespacesAndNewlines),
-      !statusCommandId.isEmpty
+      let statusCommandId = command.statusCommandId?.trimmedNonEmpty
     else {
       return Response(
         ok: false,
@@ -202,7 +191,7 @@ extension RunnerTests {
         )
       )
     }
-    return Response(ok: true, data: commandJournal.status(commandId: statusCommandId))
+    return Response(ok: true, data: commandJournal.status(normalizedCommandId: statusCommandId))
   }
 
   func executeUptime() -> Response {
@@ -308,10 +297,7 @@ extension RunnerTests {
       ? Date().addingTimeInterval(Self.alertCommandTimeout(timeoutMs: command.timeoutMs))
       : nil
     if Thread.isMainThread {
-      let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(
-        command,
-        deadline: alertDeadline
-      )
+      let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(command)
       return try executeOnMainSafely(
         command: command,
         alertDeadline: alertDeadline,
@@ -321,10 +307,7 @@ extension RunnerTests {
     // Resolve this before the command's outer main-thread block. If the bounded probe abandons
     // slow XCTest enumeration, return the established recoverable response instead of queueing
     // command preparation behind work that may outlive the 30-second command watchdog.
-    let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(
-      command,
-      deadline: alertDeadline
-    )
+    let routeToSpringboard = shouldRouteToSpringboardBlockingSystemModal(command)
     if let unavailable = runnerUnavailableResponse(command: command) {
       return unavailable
     }
@@ -333,7 +316,6 @@ extension RunnerTests {
     }
     if command.command == .alert, let deadline = alertDeadline {
       return try runMainThreadWork(
-        command: command,
         timeout: max(0.001, deadline.timeIntervalSinceNow),
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -345,7 +327,6 @@ extension RunnerTests {
       }
     }
     return try runMainThreadWork(
-      command: command,
       timeout: mainThreadExecutionTimeout,
       timeoutError: mainThreadExecutionTimeoutError
     ) {
@@ -354,7 +335,6 @@ extension RunnerTests {
   }
 
   func runMainThreadWork<T>(
-    command: Command?,
     timeout: TimeInterval,
     timeoutError: @escaping () -> Error,
     onAbandoned: (() -> Void)? = nil,
@@ -512,7 +492,6 @@ extension RunnerTests {
     var hasRetried = false
     while true {
       let failureCountBefore = try runMainThreadWork(
-        command: command,
         timeout: mainThreadExecutionTimeout,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -529,7 +508,6 @@ extension RunnerTests {
         return response
       }
       let recordedFailureResponse = try runMainThreadWork(
-        command: command,
         timeout: mainThreadExecutionTimeout,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -539,7 +517,6 @@ extension RunnerTests {
       }
       if let recordedFailureResponse {
         try runMainThreadWork(
-          command: command,
           timeout: mainThreadExecutionTimeout,
           timeoutError: mainThreadExecutionTimeoutError
         ) {
@@ -554,7 +531,6 @@ extension RunnerTests {
         )
         hasRetried = true
         try runMainThreadWork(
-          command: command,
           timeout: mainThreadExecutionTimeout,
           timeoutError: mainThreadExecutionTimeoutError
         ) {
@@ -569,7 +545,6 @@ extension RunnerTests {
 
   private func executeSnapshotDispatchedOnce(command: Command) throws -> Response {
     let preparation = try runMainThreadWork(
-      command: command,
       timeout: mainThreadExecutionTimeout,
       timeoutError: mainThreadExecutionTimeoutError
     ) {
@@ -584,10 +559,10 @@ extension RunnerTests {
   }
 
   /// Pure command→options projection, extracted so the runner unit bundle can
-  /// prove the decoded wire field actually reaches capture options (#1634 P2).
-  static func snapshotOptions(from command: Command) -> SnapshotOptions {
+  /// prove the decoded wire field actually reaches presentation options (#1634 P2).
+  static func presentationOptions(from command: Command) -> PresentationOptions {
     let customActions = command.customActions ?? false
-    return SnapshotOptions(
+    return PresentationOptions(
       interactiveOnly: command.interactiveOnly ?? false,
       depth: command.depth,
       scope: command.scope,
@@ -602,7 +577,7 @@ extension RunnerTests {
   }
 
   private func executeSnapshotPrepared(command: Command, activeApp: XCUIApplication) throws -> Response {
-    let options = Self.snapshotOptions(from: command)
+    let options = Self.presentationOptions(from: command)
     do {
       let payload: DataPayload
       if options.raw {
@@ -636,7 +611,6 @@ extension RunnerTests {
     }
     do {
       try runMainThreadWork(
-        command: nil,
         timeout: 1,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -654,7 +628,6 @@ extension RunnerTests {
     }
     do {
       try runMainThreadWork(
-        command: nil,
         timeout: 1,
         timeoutError: mainThreadExecutionTimeoutError
       ) {
@@ -1117,13 +1090,14 @@ extension RunnerTests {
       guard let x = command.x, let y = command.y, let x2 = command.x2, let y2 = command.y2 else {
         return Response(ok: false, error: ErrorPayload(message: "drag requires x, y, x2, and y2"))
       }
+      let defaults = runnerDragCommandDefaults(command)
       return executeDragGesture(
         activeApp: activeApp,
         x: x,
         y: y,
         x2: x2,
         y2: y2,
-        durationMs: command.durationMs,
+        durationMs: defaults.durationMs,
         synthesized: command.synthesized == true,
         message: "dragged",
         synthesizedPolicyKind: .synthesizedDrag
@@ -1132,16 +1106,10 @@ extension RunnerTests {
       // Fused frame-resolve + drag scroll for non-tvOS. On iOS this intentionally stays on the
       // AX-free synthesized coordinate lane so scroll keeps working when XCTest cannot serialize
       // the accessibility tree.
-      guard let direction = command.direction,
-        direction == "up" || direction == "down" || direction == "left" || direction == "right"
+      guard let rawDirection = command.direction,
+        let direction = RunnerScrollDirection(rawValue: rawDirection)
       else {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "scroll requires direction up|down|left|right"
-          )
-        )
+        return invalidScrollDirectionResponse(commandName: "scroll")
       }
       let scrollPolicyKind = SynthesizedGesturePolicyKind.scroll
       guard let scrollContext = synthesizedCoordinateContext(
@@ -1160,9 +1128,10 @@ extension RunnerTests {
           error: ErrorPayload(message: "scroll could not resolve a usable interaction frame")
         )
       }
+      let defaults = runnerDragCommandDefaults(command)
       guard let plan = runnerScrollGesturePlan(
         direction: direction,
-        amount: command.amount,
+        amount: defaults.scrollAmount,
         pixels: command.pixels,
         referenceWidth: frame.width,
         referenceHeight: frame.height
@@ -1175,40 +1144,25 @@ extension RunnerTests {
           )
         )
       }
-      if let durationMs = command.durationMs,
-        durationMs.isFinite == false || durationMs < 0 || durationMs > 10000
-      {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "scroll durationMs must be between 0 and 10000"
-          )
-        )
+      guard scrollDurationIsValid(command.durationMs) else {
+        return invalidScrollDurationResponse(commandName: "scroll")
       }
-      return executeDragGesture(
+      return executeScrollDragGesture(
         activeApp: activeApp,
         x: frame.minX + plan.x1,
         y: frame.minY + plan.y1,
         x2: frame.minX + plan.x2,
         y2: frame.minY + plan.y2,
-        durationMs: command.durationMs,
-        synthesized: shouldUseSynthesizedScrollPath(),
+        durationMs: defaults.durationMs,
         message: "scrolled",
-        synthesizedContext: scrollContext.withReferenceFrame(frame),
-        synthesizedPolicyKind: scrollPolicyKind
+        context: scrollContext.withReferenceFrame(frame),
+        releaseBehavior: command.scrollReleaseBehavior
       )
     case .desktopScroll:
-      guard let direction = command.direction,
-        direction == "up" || direction == "down" || direction == "left" || direction == "right"
+      guard let rawDirection = command.direction,
+        let direction = RunnerScrollDirection(rawValue: rawDirection)
       else {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "desktopScroll requires direction up|down|left|right"
-          )
-        )
+        return invalidScrollDirectionResponse(commandName: "desktopScroll")
       }
       let appFrame = activeApp.frame
       let frame = resolvedTouchReferenceFrame(app: activeApp, appFrame: appFrame)
@@ -1237,16 +1191,8 @@ extension RunnerTests {
       let y = frame.midY
       let localX = x - (appFrame.isEmpty ? frame.minX : appFrame.minX)
       let localY = y - (appFrame.isEmpty ? frame.minY : appFrame.minY)
-      if let durationMs = command.durationMs,
-        durationMs.isFinite == false || durationMs < 0 || durationMs > 10000
-      {
-        return Response(
-          ok: false,
-          error: ErrorPayload(
-            code: "INVALID_ARGS",
-            message: "desktopScroll durationMs must be between 0 and 10000"
-          )
-        )
+      guard scrollDurationIsValid(command.durationMs) else {
+        return invalidScrollDurationResponse(commandName: "desktopScroll")
       }
       let touchFrame = resolvedTouchVisualizationFrame(
         app: activeApp,
@@ -1441,7 +1387,12 @@ extension RunnerTests {
         Self.alertCommandTimeout(timeoutMs: command.timeoutMs)
       )
       guard let alert = resolveAlert(app: activeApp, deadline: deadline) else {
-        return Response(ok: false, error: ErrorPayload(message: "alert not found"))
+        // Typed so the host retries on absence alone: a transport or runner failure carries no
+        // code and must not be mistaken for "no alert yet" (ALERT_NOT_FOUND_RUNNER_CODE).
+        return Response(
+          ok: false,
+          error: ErrorPayload(code: "ALERT_NOT_FOUND", message: "alert not found")
+        )
       }
       return handleAlert(alert, action: action, deadline: deadline)
     case .gesture:
@@ -1493,9 +1444,73 @@ extension RunnerTests {
     }
   }
 
-  /// Shared drag execution for `.drag` and the fused `.scroll`. The iOS synthesized lane keeps
-  /// each command's fallback policy explicit: scroll requires private synthesis, while explicit
-  /// synthesized drag can still use the coordinate fallback unless AX is known unavailable.
+  private func invalidScrollDirectionResponse(commandName: String) -> Response {
+    Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "INVALID_ARGS",
+        message: "\(commandName) requires direction up|down|left|right"
+      )
+    )
+  }
+
+  private func scrollDurationIsValid(_ durationMs: Double?) -> Bool {
+    guard let durationMs else { return true }
+    return durationMs.isFinite && durationMs >= 0 && durationMs <= 10000
+  }
+
+  private func invalidScrollDurationResponse(commandName: String) -> Response {
+    return Response(
+      ok: false,
+      error: ErrorPayload(
+        code: "INVALID_ARGS",
+        message: "\(commandName) durationMs must be between 0 and 10000"
+      )
+    )
+  }
+
+  private func executeScrollDragGesture(
+    activeApp: XCUIApplication,
+    x: Double,
+    y: Double,
+    x2: Double,
+    y2: Double,
+    durationMs: Double,
+    message: String,
+    context: SynthesizedCoordinateContext,
+    releaseBehavior: ScrollReleaseBehavior?
+  ) -> Response {
+#if os(iOS)
+    return executeDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      synthesized: true,
+      message: message,
+      synthesizedContext: context,
+      synthesizedPolicyKind: .scroll,
+      synthesizedProfile: scrollDragProfile(releaseBehavior: releaseBehavior)
+    )
+#else
+    return executeDragGesture(
+      activeApp: activeApp,
+      x: x,
+      y: y,
+      x2: x2,
+      y2: y2,
+      durationMs: durationMs,
+      synthesized: false,
+      message: message,
+      synthesizedPolicyKind: .scroll
+    )
+#endif
+  }
+
+  /// Shared drag execution for explicit drag commands. The iOS synthesized lane keeps its
+  /// fallback policy explicit; viewport scrolling owns a separate single drag specification.
   private func executeDragGesture(
     activeApp: XCUIApplication,
     x: Double,
@@ -1509,6 +1524,7 @@ extension RunnerTests {
     synthesizedPolicyKind: SynthesizedGesturePolicyKind,
     synthesizedProfile: SynthesizedDragProfile = .continuous
   ) -> Response {
+    let durationMs = durationMs ?? runnerDefaultDragDurationMs
     let commandName = dragCommandName(message: message)
     guard x.isFinite, y.isFinite, x2.isFinite, y2.isFinite else {
       return Response(
@@ -1540,7 +1556,7 @@ extension RunnerTests {
     )
     var fallback: GestureFallback?
     if synthesized {
-      let durationMs = min(max(durationMs ?? 250, 16), 10000)
+      let durationMs = min(max(durationMs, 16), 10000)
       let context = synthesizedCoordinateContext(
         app: activeApp,
         policy: synthesizedGesturePolicy(synthesizedPolicyKind)
@@ -1563,7 +1579,7 @@ extension RunnerTests {
       fallback = gestureFallback(strategy: "xctest-coordinate-drag", from: outcome)
     }
     let holdDuration = synthesized
-      ? synthesizedSwipeFallbackHoldDuration(durationMs: durationMs ?? 250)
+      ? synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
       : coordinateDragHoldDuration()
     let (timing, outcome) = performGesture(activeApp) {
       dragAt(
@@ -1592,7 +1608,7 @@ extension RunnerTests {
     y: Double,
     x2: Double,
     y2: Double,
-    durationMs: Double?,
+    durationMs: Double,
     message: String,
     context: SynthesizedCoordinateContext?,
     policyKind: SynthesizedGesturePolicyKind,
@@ -1632,7 +1648,7 @@ extension RunnerTests {
         )
       )
     }
-    let durationMs = min(max(durationMs ?? 250, 16), 10000)
+    let durationMs = min(max(durationMs, 16), 10000)
     let dragFrame = axFreeDragVisualizationFrame(
       x: plan.points.x,
       y: plan.points.y,
@@ -1682,7 +1698,7 @@ extension RunnerTests {
     y: Double,
     x2: Double,
     y2: Double,
-    durationMs: Double?,
+    durationMs: Double,
     message: String,
     fallback: GestureFallback?
   ) -> Response {
@@ -1694,7 +1710,7 @@ extension RunnerTests {
       x2: dragPoints.x2,
       y2: dragPoints.y2
     )
-    let holdDuration = synthesizedSwipeFallbackHoldDuration(durationMs: durationMs ?? 250)
+    let holdDuration = synthesizedSwipeFallbackHoldDuration(durationMs: durationMs)
     let (timing, outcome) = performGesture(activeApp) {
       dragAt(
         app: activeApp,
@@ -1724,14 +1740,6 @@ extension RunnerTests {
 #endif
   }
 
-  private func shouldUseSynthesizedScrollPath() -> Bool {
-#if os(iOS)
-    return true
-#else
-    return false
-#endif
-  }
-
   private func dragCommandName(message: String) -> String {
     return message == "scrolled" ? "scroll" : "drag"
   }
@@ -1762,9 +1770,6 @@ extension RunnerTests {
     )
   }
 
-  func runnerCommandFixture(_ json: String) throws -> Command {
-    try JSONDecoder().decode(Command.self, from: Data(json.utf8))
-  }
 
   private func shouldSkipAppActivationPreflight(_ command: Command) -> Bool {
 #if os(iOS)
@@ -1784,15 +1789,13 @@ extension RunnerTests {
   }
 
   private func shouldRouteToSpringboardBlockingSystemModal(
-    _ command: Command,
-    deadline: Date? = nil
+    _ command: Command
   ) -> Bool {
 #if os(iOS)
-    guard command.command == .alert || isCoordinateOnlyTap(command) else {
+    guard isCoordinateOnlyTap(command) else {
       return false
     }
-    let budgetDeadline = Date().addingTimeInterval(systemModalProbeBudget)
-    let probeDeadline = deadline.map { min($0, budgetDeadline) } ?? budgetDeadline
+    let probeDeadline = Date().addingTimeInterval(systemModalProbeBudget)
     // `runMainThreadWork` executes inline for a main-thread caller, so that path cannot use its
     // timeout machinery. Direct main-thread dispatch keeps the prior synchronous modal check;
     // normal off-main command dispatch uses the bounded probe and post-probe busy recovery.

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

@@ -1,5 +1,6 @@
 import Foundation
 import XCTest
+import AgentDeviceSnapshotPresentation
 
 enum RunnerCommandLifecycleState: String {
   case notAccepted
@@ -26,7 +27,7 @@ final class RunnerCommandJournal {
   private var order: [String] = []
 
   func accept(command: Command) {
-    guard let commandId = normalizedCommandId(command.commandId) else { return }
+    guard let commandId = command.commandId?.trimmedNonEmpty else { return }
     lock.lock()
     defer { lock.unlock() }
     entries[commandId] = RunnerCommandJournalEntry(
@@ -66,16 +67,13 @@ final class RunnerCommandJournal {
     )
   }
 
-  func status(commandId: String) -> DataPayload {
-    guard let normalized = normalizedCommandId(commandId) else {
-      return DataPayload(lifecycleState: RunnerCommandLifecycleState.notAccepted.rawValue)
-    }
+  func status(normalizedCommandId commandId: String) -> DataPayload {
     lock.lock()
-    let entry = entries[normalized]
+    let entry = entries[commandId]
     lock.unlock()
     guard let entry else {
       return DataPayload(
-        commandId: normalized,
+        commandId: commandId,
         lifecycleState: RunnerCommandLifecycleState.notAccepted.rawValue
       )
     }
@@ -98,7 +96,7 @@ final class RunnerCommandJournal {
     responseJson: String?,
     error: ErrorPayload?
   ) {
-    guard let commandId = normalizedCommandId(command.commandId) else { return }
+    guard let commandId = command.commandId?.trimmedNonEmpty else { return }
     lock.lock()
     defer { lock.unlock() }
     var entry = entries[commandId] ?? RunnerCommandJournalEntry(
@@ -126,12 +124,6 @@ final class RunnerCommandJournal {
     }
   }
 
-  private func normalizedCommandId(_ value: String?) -> String? {
-    guard let value else { return nil }
-    let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
-    return trimmed.isEmpty ? nil : trimmed
-  }
-
   private func encodeResponseJson(command: Command, response: Response) -> String? {
     guard shouldRetainResponseJson(command: command) else { return nil }
     guard let data = try? JSONEncoder().encode(response) else { return nil }