agent-device 0.20.10 → 0.21.1

package/apple/snapshot-bridge/SnapshotBridgeCapture.m

@@ -0,0 +1,138 @@
+#import "SnapshotBridgeCapture.h"
+
+static NSString *const attributesKey = @"UIAccessibilitySnapshotKeyAttributes";
+static NSString *const childrenKey = @"UIAccessibilitySnapshotKeyChildren";
+static NSString *const childCountKey = @"UIAccessibilitySnapshotKeyChildrenCount";
+static NSString *const elementKey = @"UIAccessibilitySnapshotKeyElement";
+static const NSUInteger maximumRequests = 32;
+
+@interface SnapshotTreeCapture : NSObject
+@property(nonatomic, copy) SnapshotElementReader reader;
+@property(nonatomic) NSUInteger acceptedDepth;
+@property(nonatomic) NSUInteger remainingNodes;
+@property(nonatomic) NSUInteger maximumNodes;
+@property(nonatomic) NSUInteger requests;
+@property(nonatomic) NSUInteger rejected;
+@property(nonatomic) BOOL truncated;
+- (nullable NSDictionary *)read:(id)element depth:(NSUInteger)depth error:(NSError **)error;
+- (nullable NSDictionary *)materialize:(NSDictionary *)tree depth:(NSUInteger)depth nativeLevels:(NSUInteger)nativeLevels error:(NSError **)error;
+@end
+
+@implementation SnapshotTreeCapture
+- (nullable NSDictionary *)read:(id)element depth:(NSUInteger)depth error:(NSError **)error
+{
+  NSUInteger attemptDepth = MIN(depth, self.acceptedDepth);
+  for (NSUInteger retries = 0;; retries++) {
+    if (self.requests >= maximumRequests) {
+      if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:1
+          userInfo:@{NSLocalizedDescriptionKey: @"snapshot continuation request budget exhausted"}];
+      return nil;
+    }
+    self.requests++;
+    NSError *failure = nil;
+    id tree = self.reader(element, attemptDepth, MIN(self.maximumNodes, self.remainingNodes + 1), &failure);
+    if (tree) return tree;
+    NSNumber *nativeCode = failure.userInfo[@"accessibility-error"];
+    BOOL rejected = ([nativeCode isKindOfClass:NSNumber.class] && nativeCode.integerValue == -25201) ||
+        ([failure.domain isEqualToString:@"com.apple.dt.xctest.automation-support.error"] && failure.code == 5);
+    if (rejected) self.rejected++;
+    if (!rejected || attemptDepth <= 1 || retries >= 2) {
+      if (error) *error = failure;
+      return nil;
+    }
+    attemptDepth = MAX(1, attemptDepth / 2);
+    self.acceptedDepth = attemptDepth;
+  }
+}
+
+- (nullable NSDictionary *)materialize:(NSDictionary *)tree depth:(NSUInteger)depth nativeLevels:(NSUInteger)nativeLevels error:(NSError **)error
+{
+  if (![tree isKindOfClass:NSDictionary.class] ||
+      ![tree[attributesKey] isKindOfClass:NSDictionary.class] ||
+      ![tree[childrenKey] isKindOfClass:NSArray.class]) {
+    if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:2
+        userInfo:@{NSLocalizedDescriptionKey: @"malformed snapshot continuation"}];
+    return nil;
+  }
+  if (self.remainingNodes == 0) {
+    self.truncated = YES;
+    return nil;
+  }
+  self.remainingNodes--;
+  NSArray *children = tree[childrenKey];
+  NSNumber *childCount = tree[childCountKey];
+  BOOL knownChildCount = [childCount isKindOfClass:NSNumber.class] && childCount.doubleValue >= 0 &&
+      childCount.doubleValue == (double)childCount.unsignedIntegerValue;
+  if (nativeLevels <= 1 && !knownChildCount && depth <= 1) self.truncated = YES;
+  if (depth > 1 && nativeLevels <= 1 && !knownChildCount) {
+    if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:6
+        userInfo:@{NSLocalizedDescriptionKey: @"snapshot boundary child count unavailable"}];
+    return nil;
+  }
+  BOOL withheld = knownChildCount && childCount.unsignedIntegerValue > children.count;
+  if (depth <= 1 || self.remainingNodes == 0) {
+    self.truncated |= children.count > 0 || withheld;
+    if (children.count == 0) return tree;
+    NSMutableDictionary *bounded = [tree mutableCopy];
+    bounded[childrenKey] = @[];
+    return bounded;
+  }
+  if (withheld && children.count < self.remainingNodes) {
+    id element = tree[elementKey];
+    if (!element) {
+      if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:3
+          userInfo:@{NSLocalizedDescriptionKey: @"snapshot continuation element unavailable"}];
+      return nil;
+    }
+    NSDictionary *continuation = [self read:element depth:depth error:error];
+    if (!continuation) return nil;
+    nativeLevels = MIN(depth, self.acceptedDepth);
+    children = continuation[childrenKey];
+    if (![children isKindOfClass:NSArray.class] || children.count < MIN(childCount.unsignedIntegerValue, self.remainingNodes)) {
+      if (error) *error = [NSError errorWithDomain:@"agent-device.snapshot" code:4
+          userInfo:@{NSLocalizedDescriptionKey: @"snapshot continuation children unavailable"}];
+      return nil;
+    }
+  }
+  if (withheld && children.count < childCount.unsignedIntegerValue) self.truncated = YES;
+  NSMutableArray *materialized = nil;
+  NSUInteger index = 0;
+  for (NSDictionary *child in children) {
+    if (self.remainingNodes == 0) {
+      self.truncated = YES;
+      if (!materialized) materialized = [[children subarrayWithRange:NSMakeRange(0, index)] mutableCopy];
+      break;
+    }
+    NSDictionary *node = [self materialize:child depth:depth - 1 nativeLevels:(nativeLevels > 0 ? nativeLevels - 1 : 0) error:error];
+    if (!node) return nil;
+    if (node != child && !materialized) materialized = [[children subarrayWithRange:NSMakeRange(0, index)] mutableCopy];
+    [materialized addObject:node];
+    index++;
+  }
+  if (!materialized && children == tree[childrenKey]) return tree;
+  NSMutableDictionary *result = [tree mutableCopy];
+  result[childrenKey] = materialized ?: children;
+  return result;
+}
+@end
+
+NSDictionary *captureSnapshotTree(id element, NSUInteger maxDepth, NSUInteger maxNodes,
+                                  NSUInteger nativeLevelsHint, SnapshotElementReader reader,
+                                  BOOL *truncated, SnapshotCaptureRecovery *recovery, NSError **error)
+{
+  SnapshotTreeCapture *capture = [SnapshotTreeCapture new];
+  capture.reader = reader;
+  capture.acceptedDepth = nativeLevelsHint > 0 ? MIN(maxDepth + 1, nativeLevelsHint) : maxDepth + 1;
+  capture.remainingNodes = maxNodes;
+  capture.maximumNodes = maxNodes;
+  NSDictionary *tree = [capture read:element depth:maxDepth + 1 error:error];
+  NSDictionary *result = tree ? [capture materialize:tree depth:maxDepth + 1 nativeLevels:capture.acceptedDepth error:error] : nil;
+  *truncated = capture.truncated;
+  if (recovery) {
+    recovery->requests = capture.requests;
+    recovery->rejected = capture.rejected;
+    recovery->continuations = capture.requests - capture.rejected - (tree ? 1 : 0);
+    recovery->acceptedLevels = tree ? capture.acceptedDepth : 0;
+  }
+  return result;
+}

package/apple/snapshot-bridge/SnapshotBridgeRuntime.h

@@ -0,0 +1,34 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+extern NSString *const kProtocolVersionKey;
+extern NSString *const kSourceVersionKey;
+extern NSString *const kRequestIdKey;
+extern NSString *const kSourceVersion;
+extern const NSUInteger kProtocolVersion;
+extern const uint32_t kMaximumFrameBytes;
+extern const NSUInteger kMaximumDepth;
+extern const NSUInteger kMaximumNodes;
+extern const NSUInteger kMaximumDurationMs;
+
+NSDictionary *failureResponse(NSString *requestId,
+                              NSString *kind,
+                              NSString *code,
+                              NSString *message);
+
+@interface BridgeRuntime : NSObject
+- (nullable instancetype)initWithError:(NSString *_Nullable *_Nullable)error;
+- (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
+                                    maxDepth:(NSUInteger)maxDepth
+                                    maxNodes:(NSUInteger)maxNodes
+                            nativeLevelsHint:(NSUInteger)nativeLevelsHint
+                                  requestId:(NSString *)requestId
+                                generation:(NSString *)generation
+                              maxDurationMs:(NSUInteger)maxDurationMs
+                                    error:(NSDictionary *_Nullable *_Nonnull)error;
+@end
+
+BridgeRuntime *_Nullable sharedRuntime(NSString *_Nullable *_Nullable error);
+
+NS_ASSUME_NONNULL_END

package/apple/snapshot-bridge/SnapshotBridgeRuntime.m

@@ -0,0 +1,411 @@
+/*
+ * The private Simulator AX reader is adapted from Meta Platforms, Inc. idb v1.5.2
+ * SimulatorFrameworkBridge/AccessibilityService.m and AccessibilityRuntime.m.
+ * See LICENSE.idb for the upstream notice and license.
+ */
+
+#import "SnapshotBridgeRuntime.h"
+#import "SnapshotBridgeCapture.h"
+
+#import <CoreGraphics/CoreGraphics.h>
+#import <objc/message.h>
+#import <objc/runtime.h>
+
+#import <dlfcn.h>
+#import <signal.h>
+#import <unistd.h>
+
+NSString *const kProtocolVersionKey = @"protocolVersion";
+NSString *const kSourceVersionKey = @"sourceVersion";
+NSString *const kRequestIdKey = @"requestId";
+NSString *const kSourceVersion = @"agent-device-simulator-ax-v1.5.5";
+const NSUInteger kProtocolVersion = 1;
+const uint32_t kMaximumFrameBytes = 16 * 1024 * 1024;
+const NSUInteger kMaximumDepth = 128;
+const NSUInteger kMaximumNodes = 10000;
+const NSUInteger kMaximumDurationMs = 120000;
+
+static NSString *const kAttributeElementType = @"XC_kAXXCAttributeElementType";
+static NSString *const kAttributeElementBaseType = @"XC_kAXXCAttributeElementBaseType";
+static NSString *const kAttributeLabel = @"XC_kAXXCAttributeLabel";
+static NSString *const kAttributeValue = @"XC_kAXXCAttributeValue";
+static NSString *const kAttributeIdentifier = @"XC_kAXXCAttributeIdentifier";
+static NSString *const kAttributeFrame = @"XC_kAXXCAttributeFrame";
+static NSString *const kAttributeAutomationType = @"XC_kAXXCAttributeAutomationType";
+static NSString *const kAttributeChildren = @"XC_kAXXCAttributeChildren";
+static NSString *const kSnapshotAttributes = @"UIAccessibilitySnapshotKeyAttributes";
+static NSString *const kSnapshotChildren = @"UIAccessibilitySnapshotKeyChildren";
+static NSString *const kXctAutomationSupportPath =
+    @"/Developer/Library/PrivateFrameworks/XCTAutomationSupport.framework/XCTAutomationSupport";
+static NSString *const kAxRuntimePath =
+    @"/System/Library/PrivateFrameworks/AXRuntime.framework/AXRuntime";
+static NSString *const kAccessibilityErrorKey = @"accessibility-error";
+
+typedef NSDictionary<NSString *, id> *_Nullable (*DefaultSnapshotParametersFn)(void);
+typedef NSArray<NSNumber *> *_Nullable (*AttributeNumbersForNamesFn)(NSArray<NSString *> *names);
+typedef uint32_t (*AXValueGetTypeFn)(const void *value);
+typedef Boolean (*AXValueGetValueFn)(const void *value, uint32_t type, void *out);
+typedef bool (*AutomationEnabledFn)(void);
+
+@interface XCTAccessibilityFramework : NSObject
+- (instancetype)initForRemoteAccess;
+- (nullable id)userTestingSnapshotForElement:(id)element
+                                      options:(NSDictionary<NSString *, id> *)options
+                                        error:(NSError **)error;
+@end
+
+@interface XCAccessibilityElement : NSObject
+- (nullable void *)AXUIElement;
+@end
+
+@protocol XCAccessibilityElementFactory <NSObject>
++ (nullable XCAccessibilityElement *)elementWithProcessIdentifier:(pid_t)pid;
+@end
+
+@protocol AXForegroundElement <NSObject>
++ (nullable id<AXForegroundElement>)primaryApp;
+- (pid_t)pid;
+@end
+
+static NSNumber *finiteNumber(double value)
+{
+  return isfinite(value) ? @(value) : nil;
+}
+
+static NSDictionary *_Nullable rectDictionary(CGRect rect)
+{
+  NSNumber *x = finiteNumber(rect.origin.x);
+  NSNumber *y = finiteNumber(rect.origin.y);
+  NSNumber *width = finiteNumber(rect.size.width);
+  NSNumber *height = finiteNumber(rect.size.height);
+  if (!x || !y || !width || !height) {
+    return nil;
+  }
+  return @{ @"X" : x, @"Y" : y, @"Width" : width, @"Height" : height };
+}
+
+@interface SnapshotWatchdogState : NSObject
+@property(atomic) BOOL completed;
+@end
+
+@implementation SnapshotWatchdogState
+@end
+
+static dispatch_source_t startRequestWatchdog(NSUInteger durationMs, SnapshotWatchdogState *state)
+{
+  dispatch_source_t watchdog = dispatch_source_create(
+      DISPATCH_SOURCE_TYPE_TIMER,
+      0,
+      0,
+      dispatch_get_global_queue(QOS_CLASS_UTILITY, 0));
+  dispatch_source_set_timer(
+      watchdog,
+      dispatch_time(DISPATCH_TIME_NOW, (uint64_t)durationMs * NSEC_PER_MSEC),
+      DISPATCH_TIME_FOREVER,
+      0);
+  dispatch_source_set_event_handler(watchdog, ^{
+    if (!state.completed) kill(getpid(), SIGKILL);
+  });
+  dispatch_resume(watchdog);
+  return watchdog;
+}
+
+static void finishRequestWatchdog(dispatch_source_t watchdog, SnapshotWatchdogState *state)
+{
+  state.completed = YES;
+  dispatch_source_cancel(watchdog);
+}
+
+@implementation BridgeRuntime {
+  XCTAccessibilityFramework *_framework;
+  Class<XCAccessibilityElementFactory> _elementClass;
+  DefaultSnapshotParametersFn _defaultSnapshotParameters;
+  AttributeNumbersForNamesFn _attributeNumbersForNames;
+  AXValueGetTypeFn _valueGetType;
+  AXValueGetValueFn _valueGetValue;
+  AutomationEnabledFn _automationEnabled;
+}
+
+- (nullable instancetype)initWithError:(NSString *_Nullable *_Nullable)error
+{
+  self = [super init];
+  if (!self) return nil;
+
+  dlopen(kAxRuntimePath.UTF8String, RTLD_NOW);
+  dlopen(kXctAutomationSupportPath.UTF8String, RTLD_NOW);
+
+  Class frameworkClass = objc_lookUpClass("XCTAccessibilityFramework");
+  _elementClass = (Class<XCAccessibilityElementFactory>)objc_lookUpClass("XCAccessibilityElement");
+  if (!frameworkClass || !_elementClass) {
+    if (error) *error = @"XCTAutomationSupport accessibility classes are unavailable";
+    return nil;
+  }
+
+  _framework = [(XCTAccessibilityFramework *)[frameworkClass alloc] initForRemoteAccess];
+  if (!_framework || ![_framework respondsToSelector:@selector(userTestingSnapshotForElement:options:error:)]) {
+    if (error) *error = @"XCTAccessibilityFramework snapshot API is unavailable";
+    return nil;
+  }
+
+  _defaultSnapshotParameters = (DefaultSnapshotParametersFn)dlsym(RTLD_DEFAULT, "XCTDefaultSnapshotParameters");
+  _attributeNumbersForNames = (AttributeNumbersForNamesFn)dlsym(
+      RTLD_DEFAULT, "XCAXAccessibilityAttributesForStringAttributes");
+  _valueGetType = (AXValueGetTypeFn)dlsym(RTLD_DEFAULT, "AXValueGetType");
+  _valueGetValue = (AXValueGetValueFn)dlsym(RTLD_DEFAULT, "AXValueGetValue");
+  _automationEnabled = (AutomationEnabledFn)dlsym(RTLD_DEFAULT, "_AXSAutomationEnabled");
+  if (!_defaultSnapshotParameters || !_attributeNumbersForNames || !_valueGetType || !_valueGetValue) {
+    if (error) *error = @"AX snapshot conversion functions are unavailable";
+    return nil;
+  }
+  return self;
+}
+
+- (BOOL)assertAutomationMode:(BOOL)wanted
+{
+  Class settingsClass = NSClassFromString(@"AXSettings");
+  SEL sharedInstance = NSSelectorFromString(@"sharedInstance");
+  SEL setter = NSSelectorFromString(@"setAutomationEnabled:");
+  if (settingsClass && [settingsClass respondsToSelector:sharedInstance]) {
+    id settings = ((id (*)(id, SEL))objc_msgSend)(settingsClass, sharedInstance);
+    if ([settings respondsToSelector:setter]) {
+      ((void (*)(id, SEL, BOOL))objc_msgSend)(settings, setter, wanted);
+    }
+  }
+  return _automationEnabled != NULL && _automationEnabled();
+}
+
+- (BOOL)isPrimaryForegroundProcess:(pid_t)pid
+{
+  Class<AXForegroundElement> elementClass = (Class<AXForegroundElement>)objc_lookUpClass("AXElement");
+  if (![elementClass respondsToSelector:@selector(primaryApp)]) return NO;
+  id<AXForegroundElement> application = [elementClass primaryApp];
+  return [application respondsToSelector:@selector(pid)] && [application pid] == pid;
+}
+
+- (nullable id)jsonValue:(id)value name:(NSString *)name
+{
+  if (!value || value == [NSNull null]) return nil;
+  if ([value isKindOfClass:NSString.class] || [value isKindOfClass:NSNumber.class]) return value;
+
+  const void *raw = (__bridge const void *)value;
+  if (_valueGetType(raw) == 3) {
+    CGRect rect = CGRectZero;
+    if (_valueGetValue(raw, 3, &rect)) return rectDictionary(rect);
+  }
+  if ([name isEqualToString:kAttributeFrame]) return nil;
+  return nil;
+}
+
+- (nullable NSDictionary *)nodeFromSnapshot:(id)snapshot
+                              namesByNumber:(NSDictionary<NSNumber *, NSString *> *)namesByNumber
+                                      depth:(NSUInteger)depth
+                                   maxDepth:(NSUInteger)maxDepth
+                                   maxNodes:(NSUInteger)maxNodes
+                                      count:(NSUInteger *)count
+                                  truncated:(BOOL *)truncated
+                                  malformed:(BOOL *)malformed
+{
+  if (![snapshot isKindOfClass:NSDictionary.class]) {
+    *malformed = YES;
+    return nil;
+  }
+  if (*count >= maxNodes) {
+    *truncated = YES;
+    return nil;
+  }
+  (*count)++;
+
+  NSDictionary *attributes = ((NSDictionary *)snapshot)[kSnapshotAttributes];
+  if (![attributes isKindOfClass:NSDictionary.class]) {
+    *malformed = YES;
+    return nil;
+  }
+  NSMutableDictionary *node = [NSMutableDictionary dictionary];
+  for (NSNumber *number in attributes) {
+    NSString *name = namesByNumber[number];
+    if (!name || [name isEqualToString:kAttributeChildren]) continue;
+    id safe = [self jsonValue:attributes[number] name:name];
+    if (safe) node[name] = safe;
+  }
+
+  NSArray *children = ((NSDictionary *)snapshot)[kSnapshotChildren];
+  if (![children isKindOfClass:NSArray.class]) {
+    *malformed = YES;
+    return nil;
+  }
+  NSMutableArray *builtChildren = [NSMutableArray array];
+  if (depth >= maxDepth) {
+    if (children.count > 0) *truncated = YES;
+  } else {
+    for (id child in children) {
+      NSDictionary *built = [self nodeFromSnapshot:child
+                                     namesByNumber:namesByNumber
+                                             depth:depth + 1
+                                          maxDepth:maxDepth
+                                             maxNodes:maxNodes
+                                             count:count
+                                         truncated:truncated
+                                         malformed:malformed];
+      if (built) [builtChildren addObject:built];
+      if (*malformed) return nil;
+      if (*truncated) break;
+      if (*count >= maxNodes) {
+        if (builtChildren.count < children.count) *truncated = YES;
+        break;
+      }
+    }
+  }
+  node[kAttributeChildren] = builtChildren;
+  return node;
+}
+
+- (nullable NSDictionary *)snapshotForProcess:(pid_t)pid
+                                    maxDepth:(NSUInteger)maxDepth
+                                    maxNodes:(NSUInteger)maxNodes
+                            nativeLevelsHint:(NSUInteger)nativeLevelsHint
+                                  requestId:(NSString *)requestId
+                                generation:(NSString *)generation
+                              maxDurationMs:(NSUInteger)maxDurationMs
+                                      error:(NSDictionary *_Nullable *_Nonnull)error
+{
+  SnapshotWatchdogState *watchdogState = [SnapshotWatchdogState new];
+  dispatch_source_t watchdog = startRequestWatchdog(maxDurationMs, watchdogState);
+  XCAccessibilityElement *root = [_elementClass elementWithProcessIdentifier:pid];
+  if (!root) {
+    if (error) *error = failureResponse(requestId, @"application_unavailable", @"application-element-missing", @"application element is unavailable");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  void *raw = [root AXUIElement];
+  if (!raw) {
+    if (error) *error = failureResponse(requestId, @"application_unavailable", @"application-element-missing", @"application element is unavailable");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+
+  NSArray<NSString *> *names = @[
+    kAttributeElementType,
+    kAttributeElementBaseType,
+    kAttributeLabel,
+    kAttributeValue,
+    kAttributeIdentifier,
+    kAttributeFrame,
+    kAttributeAutomationType,
+    kAttributeChildren,
+  ];
+  NSArray<NSNumber *> *numbers = _attributeNumbersForNames(names);
+  if (![numbers isKindOfClass:NSArray.class] || numbers.count != names.count) {
+    if (error) *error = failureResponse(requestId, @"reader_unavailable", @"attribute-vocabulary-mismatch", @"AX attribute vocabulary is incompatible");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  NSMutableDictionary<NSNumber *, NSString *> *namesByNumber = [NSMutableDictionary dictionary];
+  [numbers enumerateObjectsUsingBlock:^(NSNumber *number, NSUInteger index, BOOL *stop) {
+    (void)stop;
+    if ([number isKindOfClass:NSNumber.class]) namesByNumber[number] = names[index];
+  }];
+  NSMutableDictionary *options = [_defaultSnapshotParameters() mutableCopy];
+  if (!options) options = [NSMutableDictionary dictionary];
+  options[@"attributes"] = numbers;
+  options[@"maxDepth"] = @(maxDepth);
+  options[@"maxChildren"] = @(maxNodes);
+  options[@"maxArrayCount"] = @(maxNodes);
+  BOOL automationEnabled = [self assertAutomationMode:YES];
+  NSError *runtimeError = nil;
+  id snapshot = nil;
+  BOOL acquisitionTruncated = NO;
+  SnapshotCaptureRecovery recovery = {0, 0, 0, 0};
+  @try {
+    if (![self isPrimaryForegroundProcess:pid]) {
+      if (error) *error = failureResponse(requestId, @"unsupported", @"foreground-owner-unverified", @"target app is not the primary foreground accessibility owner");
+      finishRequestWatchdog(watchdog, watchdogState);
+      return nil;
+    }
+    snapshot = captureSnapshotTree((__bridge id)raw, maxDepth, maxNodes, nativeLevelsHint,
+        ^id(id element, NSUInteger depth, NSUInteger nodes, NSError **captureError) {
+          if (![self isPrimaryForegroundProcess:pid]) {
+            if (captureError) *captureError = [NSError errorWithDomain:@"agent-device.snapshot" code:5
+                userInfo:@{NSLocalizedDescriptionKey: @"foreground owner changed during continuation"}];
+            return nil;
+          }
+          NSMutableDictionary *bounded = [options mutableCopy];
+          bounded[@"maxDepth"] = @(depth);
+          bounded[@"maxChildren"] = @(nodes);
+          bounded[@"maxArrayCount"] = @(nodes);
+          return [_framework userTestingSnapshotForElement:element options:bounded error:captureError];
+        }, &acquisitionTruncated, &recovery, &runtimeError);
+    if (![self isPrimaryForegroundProcess:pid]) {
+      if (error) *error = failureResponse(requestId, @"unsupported", @"foreground-owner-changed", @"foreground accessibility ownership changed during acquisition");
+      finishRequestWatchdog(watchdog, watchdogState);
+      return nil;
+    }
+  } @catch (NSException *exception) {
+    if (error) *error = failureResponse(requestId, @"reader_unavailable", @"private-api-exception", exception.reason ?: @"AX snapshot raised an exception");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  if (!snapshot && [runtimeError.domain isEqualToString:@"agent-device.snapshot"]) {
+    BOOL exhausted = runtimeError.code == 1;
+    if (error) *error = failureResponse(requestId, exhausted ? @"reader_unavailable" : @"malformed_tree",
+        exhausted ? @"continuation-budget-exhausted" : @"snapshot-tree-malformed", runtimeError.localizedDescription);
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  if (!snapshot) {
+    NSNumber *axError = runtimeError.userInfo[kAccessibilityErrorKey];
+    NSInteger code = [axError respondsToSelector:@selector(integerValue)] ? axError.integerValue : runtimeError.code;
+    NSString *kind = code == -25216 ? @"application_not_responding" : @"application_unavailable";
+    NSString *message = runtimeError.localizedDescription ?: @"AX snapshot returned no tree";
+    if (error) *error = failureResponse(requestId, kind, code == -25216 ? @"application-timeout" : @"application-server-unavailable", message);
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  BOOL truncated = NO;
+  BOOL malformed = NO;
+  NSUInteger count = 0;
+  NSDictionary *tree = [self nodeFromSnapshot:snapshot
+                                namesByNumber:namesByNumber
+                                        depth:0
+                                     maxDepth:maxDepth
+                                        maxNodes:maxNodes
+                                        count:&count
+                                    truncated:&truncated
+                                    malformed:&malformed];
+  if (!tree) {
+    if (error) *error = failureResponse(requestId, @"malformed_tree", malformed ? @"snapshot-tree-malformed" : @"snapshot-root-invalid", malformed ? @"AX snapshot contained a malformed node" : @"AX snapshot did not contain a materialized root node");
+    finishRequestWatchdog(watchdog, watchdogState);
+    return nil;
+  }
+  finishRequestWatchdog(watchdog, watchdogState);
+  return @{
+    kProtocolVersionKey : @(kProtocolVersion),
+    kSourceVersionKey : kSourceVersion,
+    kRequestIdKey : requestId ?: @"",
+    @"generation" : generation ?: @"",
+    @"ok" : @YES,
+    @"pid" : @(pid),
+    @"tree" : tree,
+    @"truncated" : @((BOOL)(truncated || acquisitionTruncated)),
+    @"automationEnabled" : @(automationEnabled),
+    @"recovery" : @{
+      @"requests" : @(recovery.requests),
+      @"rejected" : @(recovery.rejected),
+      @"continuations" : @(recovery.continuations),
+      @"acceptedLevels" : @(recovery.acceptedLevels),
+    },
+  };
+}
+@end
+BridgeRuntime *sharedRuntime(NSString **error)
+{
+  static BridgeRuntime *runtime;
+  static dispatch_once_t once;
+  static NSString *setupError;
+  dispatch_once(&once, ^{
+    NSString *localError = nil;
+    runtime = [[BridgeRuntime alloc] initWithError:&localError];
+    setupError = [localError copy];
+  });
+  if (!runtime && error) *error = setupError ?: @"AX bridge runtime is unavailable";
+  return runtime;
+}

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunner/AgentDeviceRunnerApp.m

@@ -58,10 +58,62 @@ int main(int argc, const char *argv[]) {
 #import <UIKit/UIKit.h>
 
 @interface AgentDeviceRunnerViewController : UIViewController
+@property(nonatomic, strong) UILabel *alertActionStatus;
+@property(nonatomic, assign) NSUInteger firstAlertActions;
+@property(nonatomic, assign) NSUInteger replacementAlertActions;
+@property(nonatomic, assign) BOOL alertFixtureStarted;
 @end
 
 @implementation AgentDeviceRunnerViewController
 
+#if TARGET_OS_IOS
+- (void)updateAlertActionStatus {
+  self.alertActionStatus.text = [NSString stringWithFormat:@"First actions: %lu; replacement actions: %lu",
+                                                         (unsigned long)self.firstAlertActions,
+                                                         (unsigned long)self.replacementAlertActions];
+}
+
+- (void)presentAlertFixtureReplacement:(BOOL)replacement {
+  NSArray<NSString *> *arguments = NSProcessInfo.processInfo.arguments;
+  BOOL sameTitle = [arguments containsObject:@"--agent-device-alert-same-title"];
+  BOOL sameBody = [arguments containsObject:@"--agent-device-alert-same-body"];
+  NSString *title = replacement && !sameTitle ? @"Next confirmation" : @"First confirmation";
+  NSString *body = replacement && !sameBody ? @"Second request" : @"First request";
+  UIAlertController *alert = [UIAlertController alertControllerWithTitle:title
+                                                               message:body
+                                                        preferredStyle:UIAlertControllerStyleAlert];
+  __weak UIAlertController *weakAlert = alert;
+  for (NSString *buttonTitle in @[@"Cancel", @"OK"]) {
+    UIAlertActionStyle style = [buttonTitle isEqualToString:@"Cancel"]
+        ? UIAlertActionStyleCancel : UIAlertActionStyleDefault;
+    [alert addAction:[UIAlertAction actionWithTitle:buttonTitle style:style handler:^(UIAlertAction *action) {
+      (void)action;
+      if (replacement) {
+        self.replacementAlertActions += 1;
+      } else {
+        self.firstAlertActions += 1;
+      }
+      [self updateAlertActionStatus];
+      if (!replacement) {
+        [weakAlert dismissViewControllerAnimated:NO completion:^{
+          [self presentAlertFixtureReplacement:YES];
+        }];
+      }
+    }]];
+  }
+  [self presentViewController:alert animated:NO completion:nil];
+}
+
+- (void)viewDidAppear:(BOOL)animated {
+  [super viewDidAppear:animated];
+  if (!self.alertFixtureStarted &&
+      [NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-replacement-regression"]) {
+    self.alertFixtureStarted = YES;
+    [self presentAlertFixtureReplacement:NO];
+  }
+}
+#endif
+
 - (void)agentDeviceTextEntryDidChange:(UITextField *)textField {
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-disappear-after-input"] &&
       textField.text.length > 0) {
@@ -88,6 +140,12 @@ int main(int argc, const char *argv[]) {
 
   // Keep the fixture behind a launch argument so normal runner snapshots remain unchanged.
 #if TARGET_OS_IOS
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-alert-replacement-regression"]) {
+    self.alertActionStatus = label;
+    label.accessibilityIdentifier = @"agent-device-alert-actions";
+    [self updateAlertActionStatus];
+  }
+
   if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-text-entry-regression"]) {
     UITextField *textField = [[UITextField alloc] init];
     textField.accessibilityIdentifier = @"agent-device-hardware-keyboard-input";