agent-device 0.16.7 → 0.16.9

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Lifecycle.swift

@@ -216,14 +216,14 @@ extension RunnerTests {
   // MARK: - Command Classification
 
   func isReadOnlyCommand(_ command: Command) -> Bool {
-    switch command.command {
-    case .interactionFrame, .findText, .readText, .snapshot, .screenshot:
+    switch command.command.traits.readOnly {
+    case .always:
       return true
-    case .alert:
-      let action = (command.action ?? "get").lowercased()
-      return action == "get"
-    default:
+    case .never:
       return false
+    case .conditional:
+      // Today only `alert` is conditional: read-only when getting, mutating otherwise.
+      return (command.action ?? "get").lowercased() == "get"
     }
   }
 
@@ -234,36 +234,11 @@ extension RunnerTests {
   }
 
   func isInteractionCommand(_ command: CommandType) -> Bool {
-    switch command {
-    case
-      .tap,
-      .longPress,
-      .drag,
-      .remotePress,
-      .type,
-      .swipe,
-      .back,
-      .backInApp,
-      .backSystem,
-      .rotate,
-      .appSwitcher,
-      .keyboardDismiss,
-      .pinch,
-      .rotateGesture,
-      .transformGesture:
-      return true
-    default:
-      return false
-    }
+    return command.traits.isInteraction
   }
 
   func isRunnerLifecycleCommand(_ command: CommandType) -> Bool {
-    switch command {
-    case .shutdown, .recordStop, .screenshot, .uptime:
-      return true
-    default:
-      return false
-    }
+    return command.traits.isLifecycle
   }
 
   // MARK: - Interaction Stabilization

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift

@@ -34,6 +34,74 @@ enum CommandType: String, Codable {
   case shutdown
 }
 
+/// Runner command traits — see CONTEXT.md ("Runner command traits").
+///
+/// Single source of truth for how the runner classifies a command across three
+/// independent axes, replacing the three hand-maintained switches that used to live
+/// in RunnerTests+Lifecycle.swift (isInteractionCommand / isReadOnlyCommand /
+/// isRunnerLifecycleCommand). The classification is load-bearing for ADR-0002 session
+/// invalidation: `readOnly` gates the retry that nulls currentApp/currentBundleId.
+struct CommandTraits {
+  /// Whether the command needs the foreground-guard + stabilization preflight before running.
+  let isInteraction: Bool
+  /// Whether the command is eligible for the session-invalidating retry.
+  /// `.conditional` is resolved against the request (alert is read-only only for its `get` action).
+  let readOnly: ReadOnly
+  /// Whether the command skips the app-activation preflight entirely.
+  let isLifecycle: Bool
+
+  enum ReadOnly {
+    case always
+    case never
+    /// Alert-only today. Resolved in `isReadOnlyCommand` with alert's rule (read-only for the
+    /// `get` action, mutating otherwise). A new `.conditional` command would inherit that rule
+    /// until the resolver is generalized — give it explicit handling there if its semantics differ.
+    case conditional
+  }
+}
+
+extension CommandType {
+  /// The classification for this command. Exhaustive by construction: a new CommandType
+  /// cannot compile without being classified here, so commands can no longer silently drift
+  /// out of classification the way the parallel switches allowed.
+  var traits: CommandTraits {
+    switch self {
+    // Interaction commands: require the foreground-guard + stabilization preflight.
+    // tapSeries/dragSeries are the series forms of tap/drag; keyboardReturn is the sibling
+    // of keyboardDismiss — all three were missing from the historical switch (drift the
+    // table now prevents) and are classified as interactions here.
+    case .tap, .tapSeries, .longPress, .drag, .dragSeries, .remotePress, .type, .swipe,
+         .back, .backInApp, .backSystem, .rotate, .appSwitcher,
+         .keyboardDismiss, .keyboardReturn, .pinch, .rotateGesture, .transformGesture:
+      return CommandTraits(isInteraction: true, readOnly: .never, isLifecycle: false)
+
+    // Read-only reads: eligible for the session-invalidating retry.
+    case .interactionFrame, .findText, .readText, .snapshot:
+      return CommandTraits(isInteraction: false, readOnly: .always, isLifecycle: false)
+
+    // Screenshot is both a read and a runner-lifecycle command (skips app-activation preflight).
+    case .screenshot:
+      return CommandTraits(isInteraction: false, readOnly: .always, isLifecycle: true)
+
+    // Alert is read-only only for its `get` action (resolved by isReadOnlyCommand).
+    case .alert:
+      return CommandTraits(isInteraction: false, readOnly: .conditional, isLifecycle: false)
+
+    // Runner-lifecycle commands: skip the app-activation preflight.
+    case .recordStop, .uptime, .shutdown:
+      return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: true)
+
+    // Normal preflight, not retried.
+    // NOTE: mouseClick stays non-interaction for now — it is macOS-only and the foreground
+    // guard interacts with bespoke macOS activation, so classifying it needs a macOS smoke
+    // check first (tracked as a follow-up). Also preserved: querySelector is NOT read-only;
+    // recordStart is NOT a lifecycle command; home/alert remain non-interaction by design.
+    case .mouseClick, .querySelector, .home, .recordStart:
+      return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: false)
+    }
+  }
+}
+
 struct Command: Codable {
   let command: CommandType
   let appBundleId: String?
@@ -154,10 +222,12 @@ struct DataPayload: Codable {
 struct ErrorPayload: Codable {
   let code: String?
   let message: String
+  let hint: String?
 
-  init(code: String? = nil, message: String) {
+  init(code: String? = nil, message: String, hint: String? = nil) {
     self.code = code
     self.message = message
+    self.hint = hint
   }
 }
 

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift

@@ -1,6 +1,9 @@
 import XCTest
 
 extension RunnerTests {
+  private static let axSnapshotErrorCode = "IOS_AX_SNAPSHOT_FAILED"
+  private static let axSnapshotHint =
+    "XCTest could not serialize this iOS accessibility tree. Try a smaller read such as snapshot -s <visible label or id> -d 8, use direct selector commands such as find id <value> click, or use screenshot/logs/appstate in the same session. If you own the app and need full-tree inspection, consider flagging this screen for accessibility-tree simplification: reduce unnecessary accessible wrapper nesting and expose stable ids on actionable controls."
   private static let collapsedTabCandidateTypes: Set<XCUIElement.ElementType> = [
     .button,
     .link,
@@ -33,6 +36,12 @@ extension RunnerTests {
     let visible: Bool
   }
 
+  struct SnapshotCaptureFailure: Error {
+    let code: String
+    let message: String
+    let hint: String
+  }
+
   // MARK: - Snapshot Entry
 
   func elementTypeName(_ type: XCUIElement.ElementType) -> String {
@@ -75,12 +84,12 @@ extension RunnerTests {
     }
   }
 
-  func snapshotFast(app: XCUIApplication, options: SnapshotOptions) -> DataPayload {
+  func snapshotFast(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
     if let blocking = blockingSystemAlertSnapshot() {
       return blocking
     }
 
-    guard let context = makeSnapshotTraversalContext(app: app, options: options) else {
+    guard let context = try makeSnapshotTraversalContext(app: app, options: options) else {
       return DataPayload(nodes: [], truncated: false)
     }
 
@@ -186,12 +195,12 @@ extension RunnerTests {
     return DataPayload(nodes: nodes, truncated: truncated)
   }
 
-  func snapshotRaw(app: XCUIApplication, options: SnapshotOptions) -> DataPayload {
+  func snapshotRaw(app: XCUIApplication, options: SnapshotOptions) throws -> DataPayload {
     if let blocking = blockingSystemAlertSnapshot() {
       return blocking
     }
 
-    guard let context = makeSnapshotTraversalContext(app: app, options: options) else {
+    guard let context = try makeSnapshotTraversalContext(app: app, options: options) else {
       return DataPayload(nodes: [], truncated: false)
     }
 
@@ -304,14 +313,11 @@ extension RunnerTests {
   private func makeSnapshotTraversalContext(
     app: XCUIApplication,
     options: SnapshotOptions
-  ) -> SnapshotTraversalContext? {
-    let viewport = snapshotViewport(app: app)
+  ) throws -> SnapshotTraversalContext? {
+    let viewport = safeSnapshotViewport(app: app)
     let queryRoot = options.scope.flatMap { findScopeElement(app: app, scope: $0) } ?? app
 
-    let rootSnapshot: XCUIElementSnapshot
-    do {
-      rootSnapshot = try queryRoot.snapshot()
-    } catch {
+    guard let rootSnapshot = try captureSnapshotRoot(queryRoot) else {
       return nil
     }
 
@@ -326,6 +332,70 @@ extension RunnerTests {
     )
   }
 
+  private func captureSnapshotRoot(_ element: XCUIElement) throws -> XCUIElementSnapshot? {
+    var rootSnapshot: XCUIElementSnapshot?
+    var swiftErrorMessage: String?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      do {
+        rootSnapshot = try element.snapshot()
+      } catch {
+        swiftErrorMessage = describeSnapshotError(error)
+      }
+    })
+
+    if let rootSnapshot {
+      return rootSnapshot
+    }
+    let message = exceptionMessage ?? swiftErrorMessage ?? "snapshot returned no root"
+    if Self.isAxIllegalArgument(message) {
+      throw axSnapshotFailure(message)
+    }
+    return nil
+  }
+
+  private func safeSnapshotViewport(app: XCUIApplication) -> CGRect {
+    var viewport = CGRect.infinite
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      viewport = snapshotViewport(app: app)
+    })
+    if let exceptionMessage {
+      NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_VIEWPORT_IGNORED_EXCEPTION=%@", exceptionMessage)
+    }
+    return viewport
+  }
+
+  private func describeSnapshotError(_ error: Error) -> String {
+    let localized = error.localizedDescription
+    let debug = String(describing: error)
+    if localized.isEmpty { return debug }
+    if debug == localized { return localized }
+    return "\(localized) (\(debug))"
+  }
+
+  private func axSnapshotFailure(_ message: String) -> SnapshotCaptureFailure {
+    let failureMessage: String
+    if Self.hasAxIllegalArgumentCode(message) {
+      failureMessage = "iOS XCTest snapshot failed with kAXErrorIllegalArgument. \(message)"
+    } else {
+      failureMessage = "iOS XCTest snapshot failed while serializing the accessibility tree. \(message)"
+    }
+    return SnapshotCaptureFailure(
+      code: Self.axSnapshotErrorCode,
+      message: failureMessage,
+      hint: Self.axSnapshotHint
+    )
+  }
+
+  private static func isAxIllegalArgument(_ message: String) -> Bool {
+    let normalized = message.lowercased()
+    return hasAxIllegalArgumentCode(normalized)
+      || (normalized.contains("illegal argument") && normalized.contains("snapshot"))
+  }
+
+  private static func hasAxIllegalArgumentCode(_ message: String) -> Bool {
+    return message.lowercased().contains("kaxerrorillegalargument")
+  }
+
   private func evaluateSnapshot(
     _ snapshot: XCUIElementSnapshot,
     in context: SnapshotTraversalContext