agent-device 0.21.0 → 0.21.2

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

@@ -1,33 +1,33 @@
 import XCTest
 import AgentDeviceSnapshotPresentation
 
-// MARK: - Snapshot capture plans (ADR 0004)
-//
-// Each snapshot strategy declares an ordered chain of capture backends. One runner walks the
-// chain: capture, classify, accept the first payload the quality classifier calls usable, and
-// stamp the outcome with a structured quality verdict so the daemon renders state instead of
-// re-deriving it from node shapes. Recovery ordering is data here, never a per-call-site branch.
-
-/// Structured quality verdict shipped with every iOS snapshot payload.
+
+
+
+
+
+
+
+
 struct SnapshotQuality: Codable {
-  /// healthy: first backend produced a usable tree. recovered: a later backend did.
-  /// sparse: no backend produced a usable tree; the best attempt is returned as-is.
+
+
   let state: String
-  /// Backend that produced the returned payload: tree | queries | private-ax.
+
   let backend: String
-  /// Why recovery ran (first failure), why the payload is degraded, or why an internal backend
-  /// selection was honored.
+
+
   let reason: String?
-  /// Machine-readable reason: ax-rejected | sparse-tree | budget | no-nodes | capture-failed |
-  /// presentation-failed | deferred | requested-backend.
+
+
   let reasonCode: String?
-  /// Private AX ladder cap when the accepted tree is shallower than requested.
+
   let effectiveDepth: Int?
-  /// Leaves that merge many labels — a container marked accessible hides its descendants.
+
   let collapsedLeafIndexes: [Int]?
-  /// Coverage of the bounded custom-action pass, when the capture asked for one.
+
   let customActions: SnapshotCustomActionCoverage?
-  /// Response-level timing for the accepted backend attempt, never repeated per node.
+
   var timing: SnapshotCaptureTiming? = nil
 }
 
@@ -41,18 +41,18 @@ struct EffectiveSnapshotCapturePlan {
   let plan: [SnapshotBackendKind]
   let xCTestChannelState: SnapshotXCTestChannelPlanState
   let treeCaptureSliceBudgetOverride: TimeInterval?
-  /// Non-nil only when the plan was narrowed by an explicit internal backend preference. This
-  /// keeps the quality marker tied to the plan decision rather than to an untrusted request field.
+
+
   let preferredBackend: SnapshotBackendKind?
 }
 
-/// What the plan runner does when every backend failed or stayed sparse.
+
 enum SnapshotCaptureTerminalPolicy {
-  /// Return the best sparse payload; if the tree backend hit a real AX serialization failure
-  /// on an interactive request, fail closed: invalidate the cached target and mark runnerFatal
-  /// (AX-unavailable target invalidation, CONTEXT.md).
+
+
+
   case sparseWithFatalOnAXFailure
-  /// Re-throw the tree backend's AX failure (raw diagnostics preserve errors, ADR 0004).
+
   case throwOnAXFailure
 }
 
@@ -79,9 +79,9 @@ extension RunnerTests {
   }
 
   static let sparseRecoveryTruncatedNodeThreshold = 8
-  /// Umbrella wall-clock budget for one capture plan. Individual backends bound themselves,
-  /// but chained recovery tiers must never stack past the 30s main-thread watchdog: when the
-  /// budget is spent, remaining tiers are skipped and the best payload so far is returned.
+
+
+
   static let snapshotPlanBudget: TimeInterval = 20
   static let penalizedXCTestProbeTreeSliceBudget: TimeInterval = 1
   static let collapsedLeafMinimumSegments = 10
@@ -90,21 +90,21 @@ extension RunnerTests {
     payload?.nodes?.count ?? 0
   }
 
-  // MARK: Plan definitions
+
 
   static let regularVisiblePlan: [SnapshotBackendKind] = [.recursiveTree, .querySweep, .privateAX]
-  /// Derived from the backend trait rather than hand-listed: a backend that cannot serve the raw
-  /// projection drops out of the raw plan by construction, and a new one joins it by declaring the
-  /// trait instead of by someone remembering this line.
+
+
+
   static let rawDiagnosticPlan: [SnapshotBackendKind] = regularVisiblePlan.filter(\.supportsRawProjection)
 
-  // MARK: XCTest accessibility channel penalty (cross-attempt memory, #1105/#1156)
-  //
-  // On some deep/dynamic screens the XCTest bulk snapshot no longer fails fast with
-  // kAXErrorIllegalArgument (the #758 signature) — it grinds for many seconds first. One slow
-  // grind is tolerable; re-grinding on every subsequent capture of the same screen buries the
-  // main thread past the execution watchdog. After a slow, timed-out, or abandoned XCTest-backed
-  // capture, later plans for the same bundle use non-XCTest recovery tiers until the penalty expires.
+
+
+
+
+
+
+
 
   func penalizeSnapshotXCTestChannel(bundleId: String?, reason: String) {
     snapshotXCTestChannelPenaltyLock.lock()
@@ -133,7 +133,7 @@ extension RunnerTests {
     snapshotXCTestChannelPenaltyLock.lock()
     defer { snapshotXCTestChannelPenaltyLock.unlock() }
     guard Date() < snapshotXCTestChannelPenaltyUntil else { return false }
-    // A penalty recorded without a bundle id applies to whatever target is current.
+
     guard let penalized = snapshotXCTestChannelPenaltyBundleId else { return true }
     return penalized == bundleId
   }
@@ -144,16 +144,16 @@ extension RunnerTests {
     return pending
   }
 
-  /// The pre-seeded first-failure a penalized plan stamps into its verdict. The deferred case
-  /// uses the dedicated 'deferred' code: the breaker pre-selected the backend, nothing new
-  /// degraded on this capture, and the daemon keys warning suppression and the settle budget
-  /// reset off exactly that distinction. The bounded probe keeps 'budget': its short XCTest
-  /// slice genuinely constrains what this capture could read.
-  ///
-  /// `requestPinnedBackend` separates the two ways the plan can arrive at the same
-  /// deferred shape. A capture that ASKED for a private-AX-only reading (custom
-  /// actions) degraded nothing, so reporting slow accessibility work would name a
-  /// cause that does not exist.
+
+
+
+
+
+
+
+
+
+
   static func xcTestChannelStateFirstFailure(
     _ state: SnapshotXCTestChannelPlanState,
     requestPinnedBackend: Bool = false,
@@ -187,10 +187,10 @@ extension RunnerTests {
     }
   }
 
-  /// Pure gate: a capture is planned as penalized when the channel penalty is
-  /// active OR the daemon pinned the private-AX backend (same-backend evidence
-  /// probe) — both mean "do not enter XCTest tree work first, and stamp the
-  /// pre-selection as 'deferred' rather than a degradation".
+
+
+
+
   static func snapshotXCTestChannelTreatedAsPenalized(
     penalized: Bool,
     preferredBackend: String?
@@ -198,11 +198,11 @@ extension RunnerTests {
     penalized || preferredBackend == SnapshotBackendKind.privateAX.rawValue
   }
 
-  /// Pure plan-reorder rule: an internal preferred backend pins the regular plan to that backend;
-  /// this is the only force seam used by same-backend evidence and conformance captures. A
-  /// penalized XCTest accessibility channel uses independent backends when the platform has one,
-  /// otherwise it keeps XCTest work on a short probe. The raw diagnostic plan keeps tree-first
-  /// errors, and unknown plans are left untouched.
+
+
+
+
+
   static func effectiveSnapshotCapturePlan(
     _ plan: [SnapshotBackendKind],
     xCTestChannelPenalized: Bool,
@@ -252,7 +252,7 @@ extension RunnerTests {
     kind.usesXCTestAccessibilityChannel && hasAbandonedTreeCapture()
   }
 
-  // MARK: Plan runner
+
 
   func runSnapshotCapturePlan(
     _ plan: [SnapshotBackendKind],
@@ -264,16 +264,16 @@ extension RunnerTests {
     var best: (kind: SnapshotBackendKind, capture: SnapshotBackendCapture)?
     var firstFailure: (reason: String, code: String)?
     var axFailure: SnapshotCaptureFailure?
-    // A caller may share the pre-plan system-modal probe's deadline; otherwise own the full budget (#1244).
+
     let deadline = deadline ?? Date().addingTimeInterval(Self.snapshotPlanBudget)
     let suppressXCTestPenalty = consumeSnapshotXCTestPenaltyWarmupExemption()
 
-    // Reorder is iOS-only because hostile screens can make XCTest tree/query work grind while
-    // the app remains visually responsive. Simulators can avoid that channel through private AX;
-    // physical devices have no independent semantic backend yet, so they use a bounded probe.
-    // A daemon-preferred private-AX capture (same-backend evidence probe) takes the exact
-    // penalized route: privateAX-first plan, 'deferred' verdict — the backend was pre-selected
-    // deliberately, so no degradation warning should render for it.
+
+
+
+
+
+
     var xCTestChannelPenalized = false
     var xCTestChannelPenalizedByBreaker = false
 #if os(iOS)
@@ -290,8 +290,8 @@ extension RunnerTests {
       preferredBackend: options.preferredBackend
     )
     let effectivePlan = effective.plan
-    // Only a customActions-implied pin is request-pinned; the daemon's
-    // same-backend evidence probe pins for its own reasons and keeps 'deferred'.
+
+
     firstFailure = Self.xcTestChannelStateFirstFailure(
       effective.xCTestChannelState,
       requestPinnedBackend: options.customActions && !xCTestChannelPenalizedByBreaker,
@@ -314,8 +314,8 @@ extension RunnerTests {
         }
         break
       }
-      // While an abandoned tree capture is still grinding inside testmanagerd, XCTest-backed
-      // tiers would block behind it; only independent backends stay responsive (#1105).
+
+
       if shouldSkipSnapshotBackendForAbandonedTreeCapture(kind) {
         NSLog("AGENT_DEVICE_RUNNER_SNAPSHOT_TIER_SKIPPED_XCTEST_OCCUPIED tier=%@", kind.rawValue)
         if firstFailure == nil {
@@ -384,11 +384,11 @@ extension RunnerTests {
       case .throwAxFailure:
         throw axFailure
       case .failClosed:
-        // Fail closed on any interactive AX serialization failure that no backend recovered:
-        // invalidate the cached target so the next command reacquires it (AX-unavailable target
-        // invalidation, CONTEXT.md). A sparse `best` from a later tier (e.g. the query sweep's
-        // synthetic root) must NOT suppress this — reaching the terminal already means no backend
-        // produced a usable tree.
+
+
+
+
+
         return snapshotAccessibilityUnavailable(failure: axFailure)
       case .sparseBest:
         break
@@ -415,22 +415,6 @@ extension RunnerTests {
   ) throws -> SnapshotBackendAttempt {
     let hint = SnapshotPresentation.captureHint(for: options)
     var timer = SnapshotPhaseTimer()
-    // Scoped depth is relative to a presentation-selected root, so its hint stays broad and the
-    // backend capability gate applies only to an unscoped regular frontier.
-    let requestedRegularDepth = options.raw || SnapshotScopePolicy.isActive(options.scope)
-      ? nil
-      : options.depth
-    guard kind.canServeRegularPresentedDepth(requestedRegularDepth) else {
-      NSLog(
-        "AGENT_DEVICE_RUNNER_SNAPSHOT_BACKEND_DEPTH_UNSUPPORTED backend=%@ depth=%ld",
-        kind.rawValue,
-        requestedRegularDepth ?? -1
-      )
-      return SnapshotBackendAttempt(
-        outcome: .noCapture,
-        timing: timer.timing
-      )
-    }
     let acquisition: SnapshotAcquisition?
     do {
       acquisition = try timer.measure(.acquisition) {
@@ -523,8 +507,8 @@ extension RunnerTests {
     )
   }
 
-  /// A backend that answers a request with the other projection loses its tier and says why, so
-  /// the miss lands in the quality verdict instead of shipping as a correct-looking capture.
+
+
   static func snapshotProjectionMismatchFailure(
     _ kind: SnapshotBackendKind,
     requested: CaptureHint.Projection,
@@ -538,9 +522,9 @@ extension RunnerTests {
     )
   }
 
-  // MARK: Quality classifier (the single source of "is this snapshot degraded")
 
-  /// Returns a degradation reason + machine code when the payload is too degraded to accept.
+
+
   static func sparsePayloadReason(_ payload: DataPayload) -> (reason: String, code: String)? {
     guard let nodes = payload.nodes, !nodes.isEmpty else {
       return ("snapshot returned no nodes", "no-nodes")
@@ -554,9 +538,9 @@ extension RunnerTests {
     return nil
   }
 
-  /// Terminal action when a capture plan exhausted every backend with an AX serialization
-  /// failure still pending. Pure so the fail-closed-vs-sparse policy is unit-testable without
-  /// a live app (the ordering gap the architecture review flagged).
+
+
+
   enum SnapshotPlanTerminalAction: Equatable {
     case throwAxFailure
     case failClosed
@@ -581,8 +565,8 @@ extension RunnerTests {
       node.type == "Application" || node.type == "Window" ? node.rect : nil
     }
     return nodes.allSatisfy { node in
-      // Application/Window labels are just the app/window name, and full-screen roots
-      // compute as hittable; neither says anything about tree health.
+
+
       let isRootContainer = node.type == "Application" || node.type == "Window"
       guard Self.structuralOnlyNodeTypes.contains(node.type) else { return false }
       guard !isRootContainer else { return true }
@@ -598,18 +582,18 @@ extension RunnerTests {
     }
   }
 
-  /// Private AX can stringify an unserializable accessibility label as the JavaScript object
-  /// placeholder. It is transport residue, not UI content, and must not make a shell-only tree
-  /// look healthy.
+
+
+
   static func isSemanticSnapshotText(_ text: String?) -> Bool {
     guard let text else { return false }
     let normalized = text.trimmingCharacters(in: .whitespacesAndNewlines)
     return !normalized.isEmpty && normalized.lowercased() != "[object object]"
   }
 
-  /// A leaf whose label joins many short segments is a container marked as an accessibility
-  /// element: the platform folds every descendant into one merged node. Nothing below it can
-  /// be addressed — by automation or by assistive tech. This is app-side; no backend recovers it.
+
+
+
   static func collapsedLeafIndexes(_ nodes: [PresentedNode]) -> [Int]? {
     let parents = Set(nodes.compactMap { $0.parentIndex })
     let collapsed = nodes.filter { node in
@@ -621,7 +605,7 @@ extension RunnerTests {
     return collapsed.isEmpty ? nil : collapsed.map(\.index)
   }
 
-  // MARK: Outcome stamping
+
 
   private func stampedSnapshotPayload(
     _ capture: SnapshotBackendCapture,
@@ -642,13 +626,13 @@ extension RunnerTests {
       timing: capture.timing
     )
     return DataPayload(
-      // Legacy human text for older daemons that read message instead of snapshotQuality.
+
       message: Self.legacyQualityMessage(quality) ?? payload.message,
       nodes: payload.nodes,
-      // Completeness, never provenance: a whole tree that a later backend produced (state
-      // "recovered") stays untruncated, so strict absence reads can trust it. Only a real cap
-      // (payload truncation, a depth-limited private AX capture) or a sparse terminal payload
-      // is truncated.
+
+
+
+
       truncated: payload.truncated == true || state == "sparse" || capture.effectiveDepth != nil,
       qualityPayload: capture.qualityPayload.flatMap { quality in
         guard let nodes = quality.nodes else { return nil }
@@ -660,14 +644,14 @@ extension RunnerTests {
     )
   }
 
-  /// Response level, one line per incompleteness. An unread merged element is
-  /// byte-identical to one with no actions, and a clipped list looks complete,
-  /// so both have to name themselves.
+
+
+
   static func customActionCoverageWarnings(_ coverage: SnapshotCustomActionCoverage) -> [String] {
     var lines: [String] = []
     if coverage.blocked {
-      // Scrolling is the remedy for a budget stop, not for this one — saying it
-      // here would send the reader off doing something that cannot help.
+
+
       lines.append(
         "Custom actions were not read: an earlier accessibility read is still hung, so this "
           + "capture skipped the read pass instead of queueing behind it. No element's actions "
@@ -719,9 +703,9 @@ extension RunnerTests {
     }
     parts.append(contentsOf: customActionWarnings)
     if let depth = quality.effectiveDepth {
-      // No --depth remedy here: an explicit --depth capture disables the
-      // frontier extension, so following it would return strictly less than
-      // this capture did. A plain re-run retries with a fresh extension budget.
+
+
+
       parts.append(
         "The accessibility server rejected deeper requests; content below depth \(depth) may be missing — re-run snapshot to retry deeper content."
       )
@@ -730,3 +714,514 @@ extension RunnerTests {
   }
 }
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+