agent-device 0.21.0 → 0.21.1

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

@@ -2,30 +2,30 @@ import XCTest
 
 private enum KeyboardDismissObservationTiming {
   static let timeout: TimeInterval = 2
-  // #1542: dismissing the keyboard can trigger the host app's own content-offset
-  // adjustment (e.g. a ScrollView correcting the inset it grew to keep a focused
-  // field above the keyboard). That adjustment is a separate, unsynchronized
-  // animation the keyboard's own `waitForNonExistence` above knows nothing about:
-  // the keyboard AX element can vanish well before the app settles. The very next
-  // command is frequently a synthesized, AX-free drag (scroll/gesture — kept
-  // AX-free so it still works under #1105-family AX degradation), which has no
-  // XCTest quiescence wait of its own, so it can land mid-animation and net to
-  // zero. These bounds cap the settle wait this trades in.
-  // A spring-driven content-offset correction can pass through a near-zero-
-  // velocity inflection (the top of an overshoot) that two adjacent samples
-  // alone cannot distinguish from true rest. Requiring 3 consecutive matching
-  // samples demands ~2 full sample intervals of actual stillness before
-  // stopping early, so a momentary pause mid-animation cannot look settled.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
   static let settleTimeout: TimeInterval = 2.0
   static let settleSampleInterval: TimeInterval = 0.15
   static let settleRequiredConsecutiveMatches: Int = 3
 }
 
-// The mechanism that actually resigned the keyboard, disclosed to the caller
-// (#1598) so a response never claims "dismissed" without saying how — a
-// safe-area tap has a very different reliability/side-effect profile than
-// tapping the keyboard's own Done key, and callers need to know which one
-// fired.
+
+
+
+
+
 enum RunnerKeyboardDismissMechanism: String {
   case dismissKey
 }
@@ -61,25 +61,25 @@ extension RunnerTests {
       return (wasVisible: true, dismissed: !visible, visible: visible, mechanism: visible ? nil : .dismissKey)
     }
 
-    // #1606 review P1 (twice): generic background-tap dismissal is
-    // deliberately UNSUPPORTED. No geometry or role query can prove a
-    // coordinate is side-effect-free — a full-screen unlabeled Pressable is
-    // indistinguishable from an inert backdrop, so a "safe-area" tap can
-    // navigate or submit while reporting a successful dismiss. The dismiss
-    // key is the only mechanism the runner can vouch for.
+
+
+
+
+
+
     return (wasVisible: true, dismissed: false, visible: isKeyboardVisible(app: app), mechanism: nil)
 #endif
   }
 
 
-  // AX-free on purpose (screenshot bytes, not the accessibility tree) so it holds
-  // under the same AX degradation the synthesized gesture lane is built to survive.
-  // Bounded and self-terminating: returns as soon as `requiredConsecutiveMatches`
-  // consecutive samples match, so an already-settled screen (the common case)
-  // pays close to nothing. The stopping decision itself
-  // (`runnerScreenshotStabilitySettled`) is a pure function of the samples taken
-  // so far, so it is unit-testable without a real screenshot pipeline; this loop
-  // is the thin, untestable I/O shell around it.
+
+
+
+
+
+
+
+
   private func waitForScreenshotStability(
     timeout: TimeInterval,
     sampleInterval: TimeInterval,
@@ -252,15 +252,15 @@ extension RunnerTests {
   }
 }
 
-/// True once the `requiredConsecutiveMatches` most recent samples are all present
-/// and byte-identical — i.e. the screen held still across that whole run of
-/// polls, not just the last two. A spring-driven content-offset correction can
-/// pass through a near-zero-velocity inflection that two adjacent samples alone
-/// cannot distinguish from true rest; requiring a longer run of matches demands
-/// real elapsed stillness before stopping early. `nil` entries (a screenshot
-/// capture that failed) never count toward a match, so a flaky capture cannot
-/// look like stability; the caller's bounded loop still terminates on its
-/// deadline regardless.
+
+
+
+
+
+
+
+
+
 func runnerScreenshotStabilitySettled(
   _ samples: [Data?],
   requiredConsecutiveMatches: Int
@@ -273,3 +273,62 @@ func runnerScreenshotStabilitySettled(
   return window.allSatisfy { $0 == firstData }
 }
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

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

@@ -22,7 +22,7 @@ func runnerCGImage(from image: RunnerImage) -> CGImage? {
 }
 
 extension RunnerTests {
-  // MARK: - Recording
+
 
   func captureRunnerFrame() -> RunnerImage? {
     var image: RunnerImage?
@@ -70,7 +70,7 @@ extension RunnerTests {
     return (NSTemporaryDirectory() as NSString).appendingPathComponent(safeFileName)
   }
 
-  // MARK: - Target Activation
+
 
   func ensureRunnerHostAppActive(reason: String) {
     NSLog(
@@ -103,9 +103,9 @@ extension RunnerTests {
 
   func resetTargetAfterExternalRelaunch() -> Response {
     invalidateCachedTarget(reason: "external_app_relaunch")
-    // The app process is replaced, but the retained runner survives. Clear
-    // process-bound capture state explicitly because invalidation drops the
-    // old PID before refreshCachedTargetIfProcessChanged can observe it.
+
+
+
     clearSnapshotXCTestChannelPenalty(reason: "external_app_relaunch")
     clearPrivateAXAcceptedDepth(reason: "external_app_relaunch")
     beginFirstInteractionStabilization()
@@ -191,7 +191,7 @@ extension RunnerTests {
       initialState.rawValue,
       reason
     )
-    // activate avoids terminating and relaunching the target app
+
     if initialState == .runningForeground {
       NSLog(
         "AGENT_DEVICE_RUNNER_ACTIVATE_SKIPPED bundle=%@ reason=already_foreground",
@@ -229,7 +229,7 @@ extension RunnerTests {
     performWithQuiescenceSkippedIfSupported(target, operation: operation)
   }
 
-  // Some apps never report post-gesture quiescence, even after XCTest has synthesized the event.
+
   private func performWithQuiescenceSkippedIfSupported(
     _ target: XCUIApplication,
     operation: () -> Void
@@ -285,7 +285,7 @@ extension RunnerTests {
     return false
   }
 
-  // MARK: - Command Classification
+
 
   func isReadOnlyCommand(_ command: Command) -> Bool {
     switch command.command.traits.readOnly {
@@ -294,7 +294,7 @@ extension RunnerTests {
     case .never:
       return false
     case .conditional:
-      // Today only `alert` is conditional: read-only when getting, mutating otherwise.
+
       return (command.action ?? "get").lowercased() == "get"
     }
   }
@@ -313,7 +313,7 @@ extension RunnerTests {
     return command.traits.isLifecycle
   }
 
-  // MARK: - Interaction Stabilization
+
 
   func applyInteractionStabilizationIfNeeded() {
     if needsPostSnapshotInteractionDelay {
@@ -326,8 +326,8 @@ extension RunnerTests {
     }
   }
 
-  /// Start the post-activation settling window. Measured from now, so the time the caller spends
-  /// getting back to us counts towards it instead of being charged twice.
+
+
   func beginFirstInteractionStabilization() {
     firstInteractionReadyUptime =
       ProcessInfo.processInfo.systemUptime + firstInteractionAfterActivateDelay
@@ -335,7 +335,7 @@ extension RunnerTests {
 
   func sleepFor(_ delay: TimeInterval) {
     guard delay > 0 else { return }
-    // Keep XCTest/UI sources moving during command-local pauses such as delayed typing.
+
     if Thread.isMainThread {
       let deadline = Date().addingTimeInterval(delay)
       while Date() < deadline {

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

@@ -1,6 +1,6 @@
 import AgentDeviceSnapshotPresentation
 
-// MARK: - Wire Models
+
 
 enum CommandType: String, Codable {
   case tap
@@ -39,72 +39,72 @@ 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.
-    // keyboardReturn is the sibling of keyboardDismiss (missing from the historical switch —
-    // drift the table now prevents). .scroll is the fused frame-resolve + drag scroll; same
-    // classification as .drag. .desktopScroll is the macOS frame-resolve + wheel event sibling.
-    // .sequence is the fused multi-step gesture batch.
+
+
+
+
+
     case .tap, .longPress, .drag, .remotePress, .type, .swipe, .scroll, .desktopScroll,
          .back, .backInApp, .backSystem, .rotate, .appSwitcher,
          .keyboardDismiss, .keyboardReturn, .sequence, .gesture:
       return CommandTraits(isInteraction: true, readOnly: .never, isLifecycle: false)
 
-    // Read-only reads: eligible for the session-invalidating retry.
+
     case .findText, .readText, .snapshot, .gestureViewport:
       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, .terminate, .targetReset, .shutdown:
       return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: true)
 
     case .status:
       return CommandTraits(isInteraction: false, readOnly: .always, 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, .activate:
       return CommandTraits(isInteraction: false, readOnly: .never, isLifecycle: false)
     }
@@ -156,7 +156,7 @@ enum ScrollReleaseBehavior: String, Codable {
   case inertial
 }
 
-/// Canonical one- or two-pointer plan produced by the portable TypeScript planner.
+
 struct RunnerGesturePlan: Codable {
   let topology: String
   let intent: String
@@ -188,22 +188,22 @@ struct RunnerGesturePoint: Codable {
   let y: Double
 }
 
-/// One allowlisted coordinate gesture step inside a fused `sequence` command.
-/// `kind` is decoded as a raw String (not an enum) so the runner can return a clear
-/// INVALID_ARGS for an unknown kind instead of a generic decode failure.
+
+
+
 struct SequenceStep: Codable {
   let kind: String
   let x: Double?
   let y: Double?
   let durationMs: Double?
   let pauseMs: Double?
-  /// For `tap` steps on iOS non-tv: use the synthesized HID fast path instead of the
-  /// drag-based XCUICoordinate path, matching the individual command behavior.
+
+
   let synthesized: Bool?
 }
 
-/// Per-step result for a `sequence` response. `ok:false` carries the failing step's
-/// errorCode/errorMessage; execution stops at the first failed step.
+
+
 struct SequenceStepResult: Codable {
   let ok: Bool
   let kind: String
@@ -220,9 +220,9 @@ struct Response: Codable {
 }
 
 extension Response {
-  // The daemon pairs this gesture-clock anchor with its own receipt time to map
-  // gesture uptimes onto wall-clock for the recording touch overlay. Error responses
-  // carry no anchor so the daemon falls back instead of pairing a stale value.
+
+
+
   func stampingCurrentUptimeMs(_ value: Double) -> Response {
     guard ok else { return self }
     var payload = data ?? DataPayload()
@@ -241,6 +241,8 @@ struct DataPayload: Codable {
   var truncated: Bool?
   var qualityPayload: SnapshotQualityPayload? = nil
   var snapshotQuality: SnapshotQuality?
+
+  var systemSurface: SystemSurfaceProvenancePayload?
   var gestureStartUptimeMs: Double?
   var gestureEndUptimeMs: Double?
   var x: Double?
@@ -275,6 +277,12 @@ struct DataPayload: Codable {
   var sequenceResults: [SequenceStepResult]?
 }
 
+
+struct SystemSurfaceProvenancePayload: Codable {
+  let bundleId: String
+  let kind: String
+}
+
 struct SnapshotQualityPayload: Codable {
   let nodes: [PresentedNode]
   let truncated: Bool

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

@@ -81,7 +81,7 @@ extension RunnerTests {
     return navigationBackKeywords.firstIndex { text.contains($0) }
   }
 
-  // isFinite/>0 alone don't reject CGRect.infinite — its origin (~-9e307) is finite.
+
   static func isUsableNavigationFrame(_ frame: CGRect) -> Bool {
     guard frame.width.isFinite, frame.height.isFinite, frame.width > 0, frame.height > 0 else {
       return false
@@ -93,7 +93,7 @@ extension RunnerTests {
     guard isUsableNavigationFrame(candidate), isUsableNavigationFrame(window) else {
       return false
     }
-    // Accept the compact navigation/search header band without matching deep content controls.
+
     let maxY = window.minY + min(max(window.height * 0.22, 96), 180)
     return candidate.midY >= window.minY && candidate.midY <= maxY
   }
@@ -102,9 +102,9 @@ extension RunnerTests {
     guard isUsableNavigationFrame(frame) else {
       return nil
     }
-    // Aim at the standard leading navigation slot, bounded for compact and tablet widths.
+
     let xOffset = min(max(frame.width * 0.08, 28), 44)
-    // Sit below the status/dynamic-island region and inside common custom RN search headers.
+
     let yOffset = min(max(frame.height * 0.155, 56), 132)
     return CGPoint(x: frame.minX + xOffset, y: frame.minY + yOffset)
   }
@@ -169,4 +169,71 @@ extension RunnerTests {
     return element.exists ? element : nil
   }
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 }