agent-device 0.20.6 → 0.20.8

package/README.md

@@ -15,7 +15,7 @@
 
 Let your coding agent verify its changes in the running app.
 
-`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, tvOS, Android TV, Amazon Vega OS TV through the Vega Virtual Device (VVD), web, macOS, and Linux. Agents can read token-efficient accessibility snapshots where supported, find elements by ref or selector, run device actions, and save evidence for review. Initial Vega OS support is VVD-only and covers discovery, app lifecycle, and complete TV-remote control; physical Fire TV, capture, and selector backends remain unsupported.
+`agent-device` lets coding agents inspect, control, and verify apps on iOS, Android, HarmonyOS, tvOS, Android TV, Amazon Vega OS TV through the Vega Virtual Device (VVD), web, macOS, and Linux. Agents can read token-efficient accessibility snapshots where supported, find elements by ref or selector, run device actions, and save evidence for review. HarmonyOS support uses HDC and ArkUI `uitest` on connected devices and DevEco emulators; use `capabilities --platform harmonyos` to inspect its evidence-backed command subset. Initial Vega OS support is VVD-only and covers discovery, app lifecycle, and complete TV-remote control; physical Fire TV, capture, and selector backends remain unsupported.
 
 Your coding agent or QA tool reads each result and chooses the next command. `agent-device` runs the command and saves evidence when asked.
 
@@ -109,7 +109,7 @@ See [Commands](https://oss.callstack.com/agent-device/docs/commands) for the com
 
 ## How it works
 
-`agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, Vega CLI/VDA on the Vega Virtual Device, a local helper on macOS, and AT-SPI on Linux.
+`agent-device` keeps device state in sessions. It sends commands to XCTest on iOS and tvOS, ADB and the snapshot helper on Android, HDC and ArkUI `uitest` on HarmonyOS, Vega CLI/VDA on the Vega Virtual Device, a local helper on macOS, and AT-SPI on Linux.
 
 Node.js apps can use the typed client or public subpaths. `agent-device/android-adb` provides the Android ADB provider interface, helpers for logcat, the clipboard, the keyboard, and apps, and port reverse management.
 
@@ -117,7 +117,7 @@ Node.js apps can use the typed client or public subpaths. `agent-device/android-
 
 ### What is agent-device?
 
-`agent-device` is a command-line tool that lets coding agents inspect, control, and verify apps and save evidence for review. It supports iOS, Android, TV, web, macOS, and Linux.
+`agent-device` is a command-line tool that lets coding agents inspect, control, and verify apps and save evidence for review. It supports iOS, Android, HarmonyOS, TV, web, macOS, and Linux.
 
 ### Does it work with React Native, Expo, Flutter, and native apps?
 

package/android/ime-helper/dist/agent-device-android-ime-helper-0.20.8.apk.sha256

@@ -0,0 +1 @@
+2877cc7e16930bcbc35e5550ae12d036af70f3b53ba4a977a2b9af1ed87cde0b  agent-device-android-ime-helper-0.20.8.apk

package/android/ime-helper/dist/{agent-device-android-ime-helper-0.20.6.manifest.json → agent-device-android-ime-helper-0.20.8.manifest.json}

@@ -1,10 +1,10 @@
 {
   "name": "android-ime-helper",
-  "version": "0.20.6",
-  "assetName": "agent-device-android-ime-helper-0.20.6.apk",
-  "sha256": "7f719c5e1698e827948a9de22bf31aab065d7f2cb7d17731793b586fd3f88f4f",
+  "version": "0.20.8",
+  "assetName": "agent-device-android-ime-helper-0.20.8.apk",
+  "sha256": "2877cc7e16930bcbc35e5550ae12d036af70f3b53ba4a977a2b9af1ed87cde0b",
   "packageName": "com.callstack.agentdevice.imehelper",
-  "versionCode": 20006,
+  "versionCode": 20008,
   "serviceComponent": "com.callstack.agentdevice.imehelper/.TestInputMethodService",
   "broadcastProtocol": "android-ime-helper-v1"
 }

package/android/snapshot-helper/dist/agent-device-android-snapshot-helper-0.20.8.apk.sha256

@@ -0,0 +1 @@
+8cf893c902a0a9f2d24c654b45f88f183fc8930d31f8991a109906b57c39b5b5  agent-device-android-snapshot-helper-0.20.8.apk

package/android/snapshot-helper/dist/{agent-device-android-snapshot-helper-0.20.6.manifest.json → agent-device-android-snapshot-helper-0.20.8.manifest.json}

@@ -1,13 +1,13 @@
 {
   "name": "android-snapshot-helper",
-  "version": "0.20.6",
-  "releaseTag": "v0.20.6",
-  "assetName": "agent-device-android-snapshot-helper-0.20.6.apk",
+  "version": "0.20.8",
+  "releaseTag": "v0.20.8",
+  "assetName": "agent-device-android-snapshot-helper-0.20.8.apk",
   "apkUrl": null,
-  "sha256": "696f8e518bbc2ad66225cb80f2e9e70d2b19b75d382918edd8fce3009200e434",
-  "checksumName": "agent-device-android-snapshot-helper-0.20.6.apk.sha256",
+  "sha256": "8cf893c902a0a9f2d24c654b45f88f183fc8930d31f8991a109906b57c39b5b5",
+  "checksumName": "agent-device-android-snapshot-helper-0.20.8.apk.sha256",
   "packageName": "com.callstack.agentdevice.snapshothelper",
-  "versionCode": 20006,
+  "versionCode": 20008,
   "instrumentationRunner": "com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation",
   "minSdk": 23,
   "targetSdk": 36,

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

@@ -105,6 +105,26 @@ int main(int argc, const char *argv[]) {
       [textField.heightAnchor constraintEqualToConstant:44],
     ]];
   }
+
+  if ([NSProcessInfo.processInfo.arguments containsObject:@"--agent-device-selector-read-regression"]) {
+    NSString *const duplicateIdentifier = @"agent-device-selector-read-duplicate";
+
+    UIButton *visibleButton = [UIButton buttonWithType:UIButtonTypeSystem];
+    visibleButton.accessibilityIdentifier = duplicateIdentifier;
+    [visibleButton setTitle:@"Readable target" forState:UIControlStateNormal];
+    visibleButton.translatesAutoresizingMaskIntoConstraints = NO;
+    [self.view addSubview:visibleButton];
+
+    UILabel *offscreenLabel = [[UILabel alloc] initWithFrame:CGRectMake(-200, -200, 100, 40)];
+    offscreenLabel.accessibilityIdentifier = duplicateIdentifier;
+    offscreenLabel.text = @"Decorative duplicate";
+    [self.view addSubview:offscreenLabel];
+
+    [NSLayoutConstraint activateConstraints:@[
+      [visibleButton.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
+      [visibleButton.topAnchor constraintEqualToAnchor:label.bottomAnchor constant:24],
+    ]];
+  }
 #endif
 }
 

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.h

@@ -1,4 +1,5 @@
 #import <Foundation/Foundation.h>
+#import <CoreGraphics/CoreGraphics.h>
 #import <XCTest/XCTest.h>
 
 NS_ASSUME_NONNULL_BEGIN
@@ -11,6 +12,15 @@ FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionNodesAddedKey;
 FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionPendingKey;
 FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionMissedKey;
 
+/// Keys of the `customActions` dictionary in the snapshot response: how many
+/// merged elements were eligible for an action read, and how many the bounded
+/// pass actually reached. Present only when the capture asked for actions.
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotCustomActionsKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotCustomActionsReadKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotCustomActionsCandidatesKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotCustomActionsTruncatedKey;
+FOUNDATION_EXPORT NSString *const RunnerAXSnapshotCustomActionsBlockedKey;
+
 /// A depth-capped childless node awaiting an element-rooted follow-up request.
 /// Public so the runner unit bundle can drive the extension's miss paths with
 /// fabricated snapshots — the executed contract that missed frontiers are
@@ -29,12 +39,68 @@ FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionMissedKey;
 /// not). The response gains a `deepExtension` {calls, nodesAdded,
 /// pendingFrontiers, missedFrontiers} dictionary when any frontier existed and
 /// the call limit allowed extension. Pass 0 to disable extension entirely.
+///
+/// `customActionLimit` bounds the per-element custom-action reads described on
+/// `customActionNamesForElement:axClient:`; pass 0 to skip them entirely.
 + (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
                                                     maxDepth:(NSInteger)maxDepth
                                                     maxNodes:(NSInteger)maxNodes
                                       deepExtensionCallLimit:(NSInteger)deepExtensionCallLimit
+                                           customActionLimit:(NSInteger)customActionLimit
                                                     deadline:(nullable NSDate *)deadline;
 
+/// Names of the element's UIAccessibilityCustomActions, or nil when it has
+/// none.
+///
+/// One element per call on purpose. The bulk snapshot request cannot carry this
+/// attribute: adding it makes testmanagerd's reply decoder reject the nested
+/// arrays a custom action serializes into ("value for key 'NS.objects' was of
+/// unexpected class 'NSArray'"), drop the reply, and time the request out after
+/// ~65s instead of the usual ~110ms. Per-element reads use a different XPC
+/// message and answer normally.
+///
+/// Reading is all we can do: the actions are not invocable from the runner.
+/// XCUIElement exposes no custom-action API; XCAXClient_iOS's
+/// performAction:onElement:value: answers kAXErrorCannotComplete for every AX
+/// action number; setAttribute: on the custom-actions attribute reports success
+/// and does nothing; parameterizedAttribute: answers kAXErrorNoValue; and the
+/// raw AXUIElement C API cannot be aimed at app elements because
+/// XCAccessibilityElement is token-based and answers nil for AXUIElement.
++ (nullable NSArray<NSString *> *)customActionNamesForElement:(id)element
+                                                    axClient:(id)axClient
+                                                   completed:(BOOL *)completed;
+
+/// Bounds one element's contribution to the response (max actions, max name
+/// length). Reports whether anything was clipped so truncation is disclosed
+/// rather than silently presented as a complete list.
++ (NSArray<NSString *> *)cappedActionNames:(NSArray<NSString *> *)names
+                                 truncated:(BOOL *)truncated;
+
+/// The bounded read pass over merged leaves, exposed for the runner unit
+/// bundle: the containment contract (a hung read blocks the pass and is
+/// disclosed, and adds no further dispatches) is only executable from here.
+/// Returns {read, candidates, truncated, blocked}.
++ (NSDictionary<NSString *, NSNumber *> *)
+    annotateCustomActionsOnMergedLeaves:(nullable NSArray<RunnerAXSnapshotFrontier *> *)leaves
+                               axClient:(id)axClient
+                                  limit:(NSInteger)limit
+                              rootFrame:(CGRect)rootFrame
+                               deadline:(nullable NSDate *)deadline;
+
+/// Reads dispatched but not yet returned. The AX call cannot be cancelled, so a
+/// read that blew its deadline stays counted here until it finally returns —
+/// which is precisely the state in which further reads must be refused rather
+/// than queued behind it. Consumed by the read pass to disclose the skip.
++ (NSInteger)customActionReadsInFlight;
+
+/// Total reads ever dispatched. The containment invariant is "a blocked capture
+/// adds no work", which is only observable as this counter standing still.
++ (NSInteger)customActionReadDispatchCount;
+
+/// The shared AX client (`XCUIDevice.accessibilityInterface`), or nil when the
+/// private interface is unavailable.
++ (nullable id)accessibilityClient;
+
 + (NSInteger)processIdentifierForApplication:(XCUIApplication *)application;
 
 /// The frontier-extension loop, exposed for the runner unit bundle: a frontier
@@ -49,6 +115,7 @@ FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionMissedKey;
                                          nodeCount:(NSInteger *)nodeCount
                                          truncated:(BOOL *)truncated
                                       callsAllowed:(NSInteger)callsAllowed
+                                      mergedLeaves:(nullable NSMutableArray<RunnerAXSnapshotFrontier *> *)mergedLeaves
                                           deadline:(nullable NSDate *)deadline;
 
 @end

package/dist/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.m

@@ -2,6 +2,7 @@
 
 #import <CoreGraphics/CoreGraphics.h>
 #import <objc/message.h>
+#import <stdatomic.h>
 
 static NSString *const RunnerAXSnapshotOkKey = @"ok";
 static NSString *const RunnerAXSnapshotErrorKey = @"error";
@@ -14,6 +15,60 @@ NSString *const RunnerAXSnapshotDeepExtensionNodesAddedKey = @"nodesAdded";
 NSString *const RunnerAXSnapshotDeepExtensionPendingKey = @"pendingFrontiers";
 NSString *const RunnerAXSnapshotDeepExtensionMissedKey = @"missedFrontiers";
 
+NSString *const RunnerAXSnapshotCustomActionsKey = @"customActions";
+NSString *const RunnerAXSnapshotCustomActionsReadKey = @"read";
+NSString *const RunnerAXSnapshotCustomActionsCandidatesKey = @"candidates";
+NSString *const RunnerAXSnapshotCustomActionsTruncatedKey = @"truncated";
+NSString *const RunnerAXSnapshotCustomActionsBlockedKey = @"blocked";
+
+/// The AX server's name for UIAccessibilityCustomActions (React Native's
+/// `accessibilityActions` prop lands here too).
+static NSString *const RunnerAXCustomActionsAttribute = @"XC_kAXXCAttributeCustomActions";
+
+/// A single read costs ~100ms against a responsive app. This bound exists for
+/// the unresponsive case: without it one wedged element would swallow the whole
+/// capture's budget and starve every remaining candidate, turning a bounded
+/// enrichment into a capture-length stall.
+static const NSTimeInterval RunnerAXCustomActionReadTimeout = 1.0;
+
+/// The AX call is a synchronous XPC round trip that cannot be cancelled once
+/// issued, so the deadline above only frees the CALLER — the call itself keeps
+/// running. Containment therefore has two parts, and both are needed:
+///
+///  1. every read runs on this one serial queue, so a wedged call can never be
+///     joined by a second concurrent user of the shared XCAXClient;
+///  2. a single-flight guard (below) refuses to dispatch while an abandoned
+///     read is still outstanding, so repeated captures cannot pile up work
+///     behind it.
+///
+/// Reads resume by themselves once the hung call returns (or the runner
+/// restarts); nothing has to be reset by hand.
+static dispatch_queue_t RunnerAXCustomActionReadQueue(void)
+{
+  static dispatch_queue_t queue;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    queue = dispatch_queue_create("com.callstack.agentdevice.runner.ax-custom-actions",
+                                  DISPATCH_QUEUE_SERIAL);
+  });
+  return queue;
+}
+
+/// Reads dispatched but not yet returned. Non-zero after a read blew its
+/// deadline, which is exactly the condition the single-flight guard refuses on.
+static atomic_int RunnerAXCustomActionReadsInFlight = 0;
+
+/// Total dispatches. The invariant the containment fix exists to protect is
+/// "a blocked capture adds no work", which is only observable as this counter
+/// staying put, so it is recorded rather than inferred.
+static atomic_long RunnerAXCustomActionReadDispatches = 0;
+
+/// Output caps. The element budget bounds how many elements we read; these
+/// bound what any ONE element can put in the response, so a pathological app
+/// cannot spend the whole snapshot on one node's action list.
+static const NSUInteger RunnerAXCustomActionsMaxPerElement = 8;
+static const NSUInteger RunnerAXCustomActionNameMaxLength = 80;
+
 typedef id (*RunnerAXObjectMsgSend)(id, SEL);
 typedef NSInteger (*RunnerAXIntegerMsgSend)(id, SEL);
 typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
@@ -33,10 +88,11 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
                                                     maxDepth:(NSInteger)maxDepth
                                                     maxNodes:(NSInteger)maxNodes
                                       deepExtensionCallLimit:(NSInteger)deepExtensionCallLimit
+                                           customActionLimit:(NSInteger)customActionLimit
                                                     deadline:(nullable NSDate *)deadline
 {
   @try {
-    id axClient = [self objectFrom:XCUIDevice.sharedDevice selectorName:@"accessibilityInterface"];
+    id axClient = [self accessibilityClient];
     if (nil == axClient) {
       return [self failure:@"XCUIDevice accessibilityInterface is unavailable"];
     }
@@ -64,13 +120,16 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
     // zero extension bookkeeping.
     NSMutableArray<RunnerAXSnapshotFrontier *> *candidates =
         deepExtensionCallLimit > 0 ? [NSMutableArray array] : nil;
+    NSMutableArray<RunnerAXSnapshotFrontier *> *merged =
+        customActionLimit > 0 ? [NSMutableArray array] : nil;
     NSMutableDictionary *rootNode = [self dictionaryForSnapshot:root
                                                           depth:0
                                                        maxDepth:maxDepth
                                                        maxNodes:maxNodes
                                                       nodeCount:&nodeCount
                                                       truncated:&truncated
-                                                      frontiers:candidates];
+                                                      frontiers:candidates
+                                                    mergedLeaves:merged];
     if (nil == rootNode) {
       return [self failure:@"AX snapshot root could not be serialized"];
     }
@@ -85,7 +144,20 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
                                                       nodeCount:&nodeCount
                                                       truncated:&truncated
                                                    callsAllowed:deepExtensionCallLimit
+                                                   mergedLeaves:merged
                                                        deadline:deadline];
+    CGRect rootFrame = CGRectZero;
+    NSDictionary *rootFrameValue = rootNode[@"frame"];
+    if ([rootFrameValue isKindOfClass:NSDictionary.class]) {
+      rootFrame = CGRectMake(
+        [rootFrameValue[@"x"] doubleValue], [rootFrameValue[@"y"] doubleValue],
+        [rootFrameValue[@"width"] doubleValue], [rootFrameValue[@"height"] doubleValue]);
+    }
+    NSDictionary *customActions = [self annotateCustomActionsOnMergedLeaves:merged
+                                                                   axClient:axClient
+                                                                      limit:customActionLimit
+                                                                  rootFrame:rootFrame
+                                                                   deadline:deadline];
 
     NSMutableDictionary *response = [NSMutableDictionary dictionaryWithDictionary:@{
       RunnerAXSnapshotOkKey: @YES,
@@ -95,6 +167,9 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
     if (nil != deepExtension) {
       response[RunnerAXSnapshotDeepExtensionKey] = deepExtension;
     }
+    if (customActions.count > 0) {
+      response[RunnerAXSnapshotCustomActionsKey] = customActions;
+    }
     return response.copy;
   } @catch (NSException *exception) {
     return [self failure:exception.reason ?: exception.name ?: @"AX snapshot bridge exception"];
@@ -115,6 +190,7 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
                                          nodeCount:(NSInteger *)nodeCount
                                          truncated:(BOOL *)truncated
                                       callsAllowed:(NSInteger)callsAllowed
+                                      mergedLeaves:(nullable NSMutableArray<RunnerAXSnapshotFrontier *> *)mergedLeaves
                                           deadline:(nullable NSDate *)deadline
 {
   if (callsAllowed <= 0 || frontiers.count == 0) {
@@ -167,7 +243,8 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
                                                           maxNodes:maxNodes
                                                          nodeCount:nodeCount
                                                          truncated:truncated
-                                                         frontiers:subCandidates];
+                                                         frontiers:subCandidates
+                                                      mergedLeaves:mergedLeaves];
       if (nil != childNode) {
         [children addObject:childNode];
       }
@@ -306,6 +383,250 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
   return attributes;
 }
 
+/// Reads custom actions for the merged leaves in traversal order until the
+/// limit or the capture deadline is spent. Each read is its own AX round trip
+/// (~100ms on an idle simulator), so this is strictly opt-in and strictly
+/// bounded.
+///
+/// Returns {read, candidates} so the response can DISCLOSE an incomplete pass.
+/// An unread element is byte-identical to one that genuinely has no actions, so
+/// silence here would teach a reader that later cards have no affordances —
+/// exactly the mis-inference this capture exists to prevent.
+///
+/// `candidates` counts only elements still eligible at read time: a leaf that
+/// deep extension filled in since serialization is not a merged element, so
+/// counting it would inflate the denominator with nodes that never needed a
+/// read. A leaf whose live element vanished stays counted and unread, because
+/// that one really is an element we failed to answer for.
+///
+/// On-screen candidates are read first. The budget is smaller than a long
+/// feed's card count, so the order decides which elements an agent can act on
+/// at all — and it also makes the disclosure's remedy true: scrolling changes
+/// the on-screen set, so a re-run reads elements the previous pass could not.
+/// Note that `--scope` deliberately is NOT the ordering key: scope is applied
+/// when the Swift walk builds nodes, long after this pass, so it cannot narrow
+/// the read budget without duplicating the scope predicate here.
++ (NSDictionary<NSString *, NSNumber *> *)
+    annotateCustomActionsOnMergedLeaves:(nullable NSArray<RunnerAXSnapshotFrontier *> *)leaves
+                               axClient:(id)axClient
+                                  limit:(NSInteger)limit
+                              rootFrame:(CGRect)rootFrame
+                               deadline:(nullable NSDate *)deadline
+{
+  if (limit <= 0 || leaves.count == 0) {
+    return @{};
+  }
+  NSMutableArray<RunnerAXSnapshotFrontier *> *onScreen = [NSMutableArray array];
+  NSMutableArray<RunnerAXSnapshotFrontier *> *offScreen = [NSMutableArray array];
+  for (RunnerAXSnapshotFrontier *leaf in leaves) {
+    if ([leaf.node[@"children"] isKindOfClass:NSArray.class]
+        && [(NSArray *)leaf.node[@"children"] count] > 0) {
+      continue;
+    }
+    [([self isFrameOnScreen:leaf.node[@"frame"] rootFrame:rootFrame] ? onScreen : offScreen)
+        addObject:leaf];
+  }
+  NSInteger candidates = onScreen.count + offScreen.count;
+  NSInteger attempts = 0;
+  NSInteger reads = 0;
+  NSInteger annotated = 0;
+  NSInteger truncatedElements = 0;
+  BOOL blocked = NO;
+  for (RunnerAXSnapshotFrontier *leaf in [onScreen arrayByAddingObjectsFromArray:offScreen]) {
+    if (attempts >= limit || (nil != deadline && deadline.timeIntervalSinceNow <= 0)) {
+      break;
+    }
+    // An abandoned read from an earlier capture is still outstanding. Stop the
+    // pass here rather than spending a deadline per element on reads that will
+    // all be refused, and record why so the response does not present the
+    // unread elements as "has no actions".
+    if ([self customActionReadsInFlight] > 0) {
+      blocked = YES;
+      break;
+    }
+    id element = [self accessibilityElementForSnapshot:leaf.snapshot];
+    if (nil == element) {
+      continue;
+    }
+    // The attempt is what the budget buys; only a completed read counts as
+    // read, so a timed-out element stays in the undisclosed remainder instead
+    // of being reported as "read, and it has no actions".
+    attempts += 1;
+    BOOL completed = NO;
+    NSArray<NSString *> *names = [self customActionNamesForElement:element
+                                                          axClient:axClient
+                                                         completed:&completed];
+    if (!completed) {
+      continue;
+    }
+    reads += 1;
+    BOOL truncated = NO;
+    NSArray<NSString *> *capped = [self cappedActionNames:names ?: @[] truncated:&truncated];
+    if (truncated) {
+      truncatedElements += 1;
+    }
+    if (capped.count > 0) {
+      leaf.node[@"actions"] = capped;
+      annotated += 1;
+    }
+  }
+  NSLog(
+    @"AGENT_DEVICE_RUNNER_PRIVATE_AX_CUSTOM_ACTIONS reads=%ld attempts=%ld annotated=%ld "
+     "candidates=%ld onScreen=%ld truncated=%ld blocked=%d dispatches=%ld",
+    (long)reads, (long)attempts, (long)annotated, (long)candidates, (long)onScreen.count,
+    (long)truncatedElements, (int)blocked, (long)[self customActionReadDispatchCount]);
+  return @{
+    RunnerAXSnapshotCustomActionsReadKey: @(reads),
+    RunnerAXSnapshotCustomActionsCandidatesKey: @(candidates),
+    RunnerAXSnapshotCustomActionsTruncatedKey: @(truncatedElements),
+    RunnerAXSnapshotCustomActionsBlockedKey: @(blocked),
+  };
+}
+
+/// An empty root frame means the capture has no viewport to judge against, so
+/// every candidate counts as on-screen and the order stays document order.
++ (BOOL)isFrameOnScreen:(id)frameValue rootFrame:(CGRect)rootFrame
+{
+  if (CGRectIsEmpty(rootFrame)) {
+    return YES;
+  }
+  if (![frameValue isKindOfClass:NSDictionary.class]) {
+    return NO;
+  }
+  NSDictionary *frame = (NSDictionary *)frameValue;
+  CGRect rect = CGRectMake(
+    [frame[@"x"] doubleValue], [frame[@"y"] doubleValue],
+    [frame[@"width"] doubleValue], [frame[@"height"] doubleValue]);
+  return !CGRectIsEmpty(rect) && CGRectIntersectsRect(rect, rootFrame);
+}
+
++ (nullable NSArray<NSString *> *)customActionNamesForElement:(id)element
+                                                    axClient:(id)axClient
+                                                   completed:(BOOL *)completed
+{
+  if (NULL != completed) {
+    *completed = NO;
+  }
+  if (nil == element || nil == axClient) {
+    return nil;
+  }
+  SEL selector = NSSelectorFromString(@"attributesForElement:attributes:error:");
+  if (![axClient respondsToSelector:selector]) {
+    return nil;
+  }
+  // Single flight. An abandoned read still owns the serial queue, so
+  // dispatching here would only queue work behind it — and repeating the
+  // capture would keep queueing more. Refuse without dispatching instead.
+  if (atomic_load(&RunnerAXCustomActionReadsInFlight) > 0) {
+    NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_CUSTOM_ACTIONS_READ_BLOCKED");
+    return nil;
+  }
+  // The AX call is a synchronous XPC round trip with no timeout of its own, so
+  // it runs off-thread behind a bounded wait. On timeout the result box is
+  // never read, so a late-returning wedged call cannot race this thread.
+  atomic_fetch_add(&RunnerAXCustomActionReadsInFlight, 1);
+  atomic_fetch_add(&RunnerAXCustomActionReadDispatches, 1);
+  NSMutableArray *box = [NSMutableArray array];
+  dispatch_semaphore_t finished = dispatch_semaphore_create(0);
+  dispatch_async(RunnerAXCustomActionReadQueue(), ^{
+    typedef id (*RunnerAXAttributesMsgSend)(id, SEL, id, id, NSError **);
+    RunnerAXAttributesMsgSend send = (RunnerAXAttributesMsgSend)objc_msgSend;
+    NSError *error = nil;
+    id result = nil;
+    @try {
+      result = send(axClient, selector, element, @[ RunnerAXCustomActionsAttribute ], &error);
+    } @catch (NSException *exception) {
+      result = nil;
+    }
+    if (nil != result) {
+      [box addObject:result];
+    }
+    // Clear in-flight BEFORE signalling, so a waiter that wakes on this signal
+    // never observes its own completed read as still outstanding.
+    atomic_fetch_sub(&RunnerAXCustomActionReadsInFlight, 1);
+    dispatch_semaphore_signal(finished);
+  });
+  long waited = dispatch_semaphore_wait(
+    finished,
+    dispatch_time(DISPATCH_TIME_NOW, (int64_t)(RunnerAXCustomActionReadTimeout * NSEC_PER_SEC)));
+  if (waited != 0) {
+    NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_CUSTOM_ACTIONS_READ_TIMEOUT");
+    return nil;
+  }
+  if (NULL != completed) {
+    *completed = YES;
+  }
+  id values = box.firstObject;
+  if (![values isKindOfClass:NSDictionary.class]) {
+    return nil;
+  }
+  id actions = ((NSDictionary *)values)[RunnerAXCustomActionsAttribute];
+  if (![actions isKindOfClass:NSArray.class]) {
+    return nil;
+  }
+  NSMutableArray<NSString *> *names = [NSMutableArray array];
+  for (id action in (NSArray *)actions) {
+    if (![action isKindOfClass:NSDictionary.class]) {
+      continue;
+    }
+    id name = ((NSDictionary *)action)[@"CustomActionName"];
+    if ([name isKindOfClass:NSString.class] && [(NSString *)name length] > 0) {
+      [names addObject:name];
+    }
+  }
+  return names.count > 0 ? names.copy : nil;
+}
+
+/// Bounds what one element can contribute to the response. The names come from
+/// the app, so their count and length are the app's choice, not ours — a list
+/// long enough to dominate a snapshot is a plausible accident (generated rows)
+/// as well as a hostile case. Truncation is reported, never silent: a clipped
+/// list is exactly as misleading as an unread element if it looks complete.
++ (NSArray<NSString *> *)cappedActionNames:(NSArray<NSString *> *)names
+                                 truncated:(BOOL *)truncated
+{
+  if (NULL != truncated) {
+    *truncated = NO;
+  }
+  NSMutableArray<NSString *> *capped = [NSMutableArray array];
+  for (NSString *name in names) {
+    if (capped.count >= RunnerAXCustomActionsMaxPerElement) {
+      if (NULL != truncated) {
+        *truncated = YES;
+      }
+      break;
+    }
+    if (name.length > RunnerAXCustomActionNameMaxLength) {
+      // Clip on composed character boundaries so a truncated name stays a
+      // valid string rather than a split grapheme.
+      NSRange clip = [name rangeOfComposedCharacterSequencesForRange:
+                             NSMakeRange(0, RunnerAXCustomActionNameMaxLength)];
+      [capped addObject:[[name substringWithRange:clip] stringByAppendingString:@"…"]];
+      if (NULL != truncated) {
+        *truncated = YES;
+      }
+      continue;
+    }
+    [capped addObject:name];
+  }
+  return capped.copy;
+}
+
++ (NSInteger)customActionReadsInFlight
+{
+  return atomic_load(&RunnerAXCustomActionReadsInFlight);
+}
+
++ (NSInteger)customActionReadDispatchCount
+{
+  return (NSInteger)atomic_load(&RunnerAXCustomActionReadDispatches);
+}
+
++ (nullable id)accessibilityClient
+{
+  return [self objectFrom:XCUIDevice.sharedDevice selectorName:@"accessibilityInterface"];
+}
+
 + (nullable id)accessibilityElementForSnapshot:(id)snapshot
 {
   id element = nil;
@@ -384,6 +705,7 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
                                               nodeCount:(NSInteger *)nodeCount
                                               truncated:(BOOL *)truncated
                                               frontiers:(NSMutableArray<RunnerAXSnapshotFrontier *> *)frontiers
+                                           mergedLeaves:(NSMutableArray<RunnerAXSnapshotFrontier *> *)mergedLeaves
 {
   if (nil == snapshot || *nodeCount >= maxNodes) {
     *truncated = YES;
@@ -410,7 +732,8 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
                                                           maxNodes:maxNodes
                                                          nodeCount:nodeCount
                                                          truncated:truncated
-                                                         frontiers:frontiers];
+                                                         frontiers:frontiers
+                                                      mergedLeaves:mergedLeaves];
       if (nil != childNode) {
         [children addObject:childNode];
       }
@@ -420,6 +743,18 @@ typedef id (*RunnerAXSnapshotMsgSend)(id, SEL, id, id, id, NSError **);
       }
     }
   }
+  if (children.count == 0 && nil != mergedLeaves
+      && [result[@"label"] isKindOfClass:NSString.class]
+      && [(NSString *)result[@"label"] length] > 0) {
+    // A labelled childless node is the shape a merged card takes: the container
+    // is marked accessible, so its real controls never appear as children. Only
+    // these are worth an action read — unlabelled leaves are decoration.
+    RunnerAXSnapshotFrontier *candidate = [[RunnerAXSnapshotFrontier alloc] init];
+    candidate.snapshot = snapshot;
+    candidate.node = result;
+    candidate.depth = depth;
+    [mergedLeaves addObject:candidate];
+  }
   if (children.count == 0 && nil != frontiers && depth >= maxDepth - 1) {
     // Childless node at the cap boundary: either a real leaf or a branch whose
     // children the AX server withheld. The two are indistinguishable here, so