Skip to content

Commit 77f1799

Browse files
committed
fix: count missed frontiers and tighten deep-extension shape (review)
The completeness verdict inverted in the failure paths: a frontier whose live element vanished or whose re-rooted request failed was silently dropped, so an all-miss extension reported pendingFrontiers=0 and the capture presented as complete while whole subtrees were missing. Missed frontiers are now counted, logged, and keep the depth-limited verdict — the pure decision lives in privateAXDepthLimited with in-bundle tests. The truncation hint no longer advertises --depth (an explicit --depth capture disables extension, so following it returned strictly less than the capture that produced the hint); the honest remedy is a plain re-run with a fresh extension budget. Shape: candidates collected only at the cap boundary and not at all when extension is disabled (exact --depth captures pay zero bookkeeping); the zero-caller 3-arg overload is gone; the response shape's keys are shared constants; the unsupported-selector diagnostic is restored; the exact-depth policy is hoisted to one named local.
1 parent 75e8e47 commit 77f1799

4 files changed

Lines changed: 123 additions & 54 deletions

File tree

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.h‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,26 @@
33

44
NS_ASSUME_NONNULL_BEGIN
55

6-
@interface RunnerAXSnapshotBridge : NSObject
6+
/// Keys of the `deepExtension` dictionary in the snapshot response, shared
7+
/// with the Swift consumer so the response shape has one spelling.
8+
FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionKey;
9+
FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionCallsKey;
10+
FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionNodesAddedKey;
11+
FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionPendingKey;
12+
FOUNDATION_EXPORT NSString *const RunnerAXSnapshotDeepExtensionMissedKey;
713

8-
+ (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
9-
maxDepth:(NSInteger)maxDepth
10-
maxNodes:(NSInteger)maxNodes;
14+
@interface RunnerAXSnapshotBridge : NSObject
1115

12-
/// Same as above, plus chained element-rooted follow-up requests from
13-
/// depth-capped frontier nodes (the AX depth limit is per-request, so
14-
/// re-rooting reaches content the app-rooted request could not). The response
15-
/// gains a `deepExtension` {calls, nodesAdded, pendingFrontiers} dictionary
16-
/// when any frontier existed and calls were allowed.
16+
/// Captures the app's accessibility tree, then chains element-rooted follow-up
17+
/// requests from depth-capped frontier nodes (the AX depth limit is
18+
/// per-request, so re-rooting reaches content the app-rooted request could
19+
/// not). The response gains a `deepExtension` {calls, nodesAdded,
20+
/// pendingFrontiers, missedFrontiers} dictionary when any frontier existed and
21+
/// the call limit allowed extension. Pass 0 to disable extension entirely.
1722
+ (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
1823
maxDepth:(NSInteger)maxDepth
1924
maxNodes:(NSInteger)maxNodes
20-
deepExtensionCalls:(NSInteger)deepExtensionCalls
25+
deepExtensionCallLimit:(NSInteger)deepExtensionCallLimit
2126
deadline:(nullable NSDate *)deadline;
2227

2328
+ (NSInteger)processIdentifierForApplication:(XCUIApplication *)application;

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerAXSnapshotBridge.m‎

Lines changed: 42 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,12 @@
77
static NSString *const RunnerAXSnapshotErrorKey = @"error";
88
static NSString *const RunnerAXSnapshotRootKey = @"root";
99
static NSString *const RunnerAXSnapshotTruncatedKey = @"truncated";
10-
static NSString *const RunnerAXSnapshotDeepExtensionKey = @"deepExtension";
10+
11+
NSString *const RunnerAXSnapshotDeepExtensionKey = @"deepExtension";
12+
NSString *const RunnerAXSnapshotDeepExtensionCallsKey = @"calls";
13+
NSString *const RunnerAXSnapshotDeepExtensionNodesAddedKey = @"nodesAdded";
14+
NSString *const RunnerAXSnapshotDeepExtensionPendingKey = @"pendingFrontiers";
15+
NSString *const RunnerAXSnapshotDeepExtensionMissedKey = @"missedFrontiers";
1116

1217
typedef id (*RunnerAXObjectMsgSend)(id, SEL);
1318
typedef NSInteger (*RunnerAXIntegerMsgSend)(id, SEL);
@@ -32,18 +37,7 @@ @implementation RunnerAXSnapshotBridge
3237
+ (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
3338
maxDepth:(NSInteger)maxDepth
3439
maxNodes:(NSInteger)maxNodes
35-
{
36-
return [self snapshotTreeForApplication:application
37-
maxDepth:maxDepth
38-
maxNodes:maxNodes
39-
deepExtensionCalls:0
40-
deadline:nil];
41-
}
42-
43-
+ (NSDictionary<NSString *, id> *)snapshotTreeForApplication:(XCUIApplication *)application
44-
maxDepth:(NSInteger)maxDepth
45-
maxNodes:(NSInteger)maxNodes
46-
deepExtensionCalls:(NSInteger)deepExtensionCalls
40+
deepExtensionCallLimit:(NSInteger)deepExtensionCallLimit
4741
deadline:(nullable NSDate *)deadline
4842
{
4943
@try {
@@ -71,7 +65,10 @@ @implementation RunnerAXSnapshotBridge
7165

7266
BOOL truncated = NO;
7367
NSInteger nodeCount = 0;
74-
NSMutableArray<RunnerAXSnapshotFrontier *> *candidates = [NSMutableArray array];
68+
// nil disables candidate collection entirely — exact --depth captures pay
69+
// zero extension bookkeeping.
70+
NSMutableArray<RunnerAXSnapshotFrontier *> *candidates =
71+
deepExtensionCallLimit > 0 ? [NSMutableArray array] : nil;
7572
NSMutableDictionary *rootNode = [self dictionaryForSnapshot:root
7673
depth:0
7774
maxDepth:maxDepth
@@ -84,15 +81,15 @@ @implementation RunnerAXSnapshotBridge
8481
}
8582

8683
NSMutableArray<RunnerAXSnapshotFrontier *> *frontiers =
87-
[self cappedFrontiersFromCandidates:candidates maxDepth:maxDepth];
84+
[self cappedFrontiersFromCandidates:candidates ?: @[] maxDepth:maxDepth];
8885
NSDictionary *deepExtension = [self extendSnapshotFrontiers:frontiers
8986
axClient:axClient
9087
attributes:attributes
9188
maxDepth:maxDepth
9289
maxNodes:maxNodes
9390
nodeCount:&nodeCount
9491
truncated:&truncated
95-
callsAllowed:deepExtensionCalls
92+
callsAllowed:deepExtensionCallLimit
9693
deadline:deadline];
9794

9895
NSMutableDictionary *response = [NSMutableDictionary dictionaryWithDictionary:@{
@@ -130,6 +127,11 @@ + (nullable NSDictionary *)extendSnapshotFrontiers:(NSMutableArray<RunnerAXSnaps
130127
}
131128
NSInteger callsUsed = 0;
132129
NSInteger nodesAdded = 0;
130+
// A frontier whose live element vanished (list churn between serialization
131+
// and extension) or whose re-rooted request failed leaves its subtree
132+
// unresolved — it must count as missed, never as drained, or an all-miss
133+
// extension would present a capped capture as complete.
134+
NSInteger missedFrontiers = 0;
133135
while (frontiers.count > 0) {
134136
if (callsUsed >= callsAllowed || *nodeCount >= maxNodes
135137
|| (nil != deadline && deadline.timeIntervalSinceNow <= 0)) {
@@ -140,6 +142,8 @@ + (nullable NSDictionary *)extendSnapshotFrontiers:(NSMutableArray<RunnerAXSnaps
140142
[frontiers removeObjectAtIndex:0];
141143
id element = [self accessibilityElementForSnapshot:frontier.snapshot];
142144
if (nil == element) {
145+
missedFrontiers += 1;
146+
NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_DEEP_EXTENSION_MISS=element unavailable");
143147
continue;
144148
}
145149
callsUsed += 1;
@@ -151,6 +155,7 @@ + (nullable NSDictionary *)extendSnapshotFrontiers:(NSMutableArray<RunnerAXSnaps
151155
maxNodes:maxNodes - *nodeCount
152156
error:&error];
153157
if (nil == subRoot) {
158+
missedFrontiers += 1;
154159
NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_DEEP_EXTENSION_MISS=%@",
155160
error.localizedDescription ?: @"nil subtree");
156161
continue;
@@ -181,12 +186,13 @@ + (nullable NSDictionary *)extendSnapshotFrontiers:(NSMutableArray<RunnerAXSnaps
181186
[frontiers addObjectsFromArray:[self cappedFrontiersFromCandidates:subCandidates
182187
maxDepth:maxDepth]];
183188
}
184-
NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_DEEP_EXTENSION calls=%ld nodes=%ld pending=%ld",
185-
(long)callsUsed, (long)nodesAdded, (long)frontiers.count);
189+
NSLog(@"AGENT_DEVICE_RUNNER_PRIVATE_AX_DEEP_EXTENSION calls=%ld nodes=%ld pending=%ld missed=%ld",
190+
(long)callsUsed, (long)nodesAdded, (long)frontiers.count, (long)missedFrontiers);
186191
return @{
187-
@"calls": @(callsUsed),
188-
@"nodesAdded": @(nodesAdded),
189-
@"pendingFrontiers": @(frontiers.count),
192+
RunnerAXSnapshotDeepExtensionCallsKey: @(callsUsed),
193+
RunnerAXSnapshotDeepExtensionNodesAddedKey: @(nodesAdded),
194+
RunnerAXSnapshotDeepExtensionPendingKey: @(frontiers.count),
195+
RunnerAXSnapshotDeepExtensionMissedKey: @(missedFrontiers),
190196
};
191197
}
192198

@@ -223,6 +229,14 @@ + (nullable id)requestSnapshotFromClient:(id)axClient
223229
{
224230
SEL requestSelector = NSSelectorFromString(@"requestSnapshotForElement:attributes:parameters:error:");
225231
if (![axClient respondsToSelector:requestSelector]) {
232+
if (NULL != error) {
233+
*error = [NSError errorWithDomain:@"agent-device.runner"
234+
code:1
235+
userInfo:@{
236+
NSLocalizedDescriptionKey:
237+
@"AX client does not support requestSnapshotForElement"
238+
}];
239+
}
226240
return nil;
227241
}
228242
NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
@@ -411,11 +425,13 @@ + (nullable NSMutableDictionary *)dictionaryForSnapshot:(id)snapshot
411425
}
412426
}
413427
}
414-
if (children.count == 0 && nil != frontiers) {
415-
// Childless node: either a real leaf or a branch whose children the AX
416-
// server withheld at its cap. The two are indistinguishable here, so all
417-
// childless nodes become candidates; the caller keeps only the deepest
418-
// observed level, where every capped branch necessarily ends.
428+
if (children.count == 0 && nil != frontiers && depth >= maxDepth - 1) {
429+
// Childless node at the cap boundary: either a real leaf or a branch whose
430+
// children the AX server withheld. The two are indistinguishable here, so
431+
// boundary childless nodes become candidates; the caller keeps only the
432+
// deepest observed level, where every capped branch necessarily ends.
433+
// Shallower childless nodes are provably real leaves and are never
434+
// collected.
419435
RunnerAXSnapshotFrontier *frontier = [[RunnerAXSnapshotFrontier alloc] init];
420436
frontier.snapshot = snapshot;
421437
frontier.node = result;

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+AXSnapshotFallback.swift‎

Lines changed: 62 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,23 @@ extension RunnerTests {
77
/// depth-capped Bluesky-class tree resolves in 1-3 chained requests (~100-300ms
88
/// each); the bound exists so a pathological tree cannot stack requests past
99
/// the capture-plan deadline, which is also enforced per call.
10-
static let privateAXDeepExtensionCallLimit = 8
10+
private static let privateAXDeepExtensionCallLimit = 8
11+
12+
/// A capture is depth-limited unless its frontier extension resolved every
13+
/// capped node: frontiers left pending (budget/deadline) or missed (element
14+
/// vanished, re-rooted request failed) mean subtrees are still absent, and
15+
/// presenting such a capture as complete would hide exactly the content the
16+
/// extension exists to recover. nil extension counts = extension never ran.
17+
static func privateAXDepthLimited(
18+
effectiveDepth: Int,
19+
requestedDepth: Int,
20+
pendingFrontiers: Int?,
21+
missedFrontiers: Int?
22+
) -> Bool {
23+
guard effectiveDepth < requestedDepth else { return false }
24+
guard let pendingFrontiers, let missedFrontiers else { return true }
25+
return pendingFrontiers > 0 || missedFrontiers > 0
26+
}
1127
/// Deep React Native trees make the AX server reject bulk snapshot requests outright with
1228
/// kAXErrorIllegalArgument once the requested depth crosses a tree-size-dependent limit
1329
/// (observed between depth 56 and 64 on the Bluesky Home feed; the limit moves with live
@@ -70,15 +86,16 @@ extension RunnerTests {
7086
) -> SnapshotBackendCapture? {
7187
#if os(iOS) && targetEnvironment(simulator)
7288
let requestedDepth = options.depth ?? 64
73-
// An explicit --depth request is honored as asked; only default-depth captures consult
74-
// (and feed) the accepted-depth memory.
89+
// An explicit --depth request is honored as asked: no accepted-depth
90+
// memory, no frontier extension past it.
91+
let exactDepthRequested = options.depth != nil
7592
let rememberedDepth =
76-
options.depth == nil
77-
? rememberedPrivateAXAcceptedDepth(
93+
exactDepthRequested
94+
? nil
95+
: rememberedPrivateAXAcceptedDepth(
7896
bundleId: currentBundleId,
7997
processIdentifier: currentAppProcessIdentifier
8098
)
81-
: nil
8299
let attemptDepths = Self.privateAXAttemptDepths(
83100
requestedDepth: requestedDepth,
84101
rememberedDepth: rememberedDepth
@@ -98,8 +115,7 @@ extension RunnerTests {
98115
for: app,
99116
maxDepth: depth,
100117
maxNodes: Self.privateAXSnapshotMaxNodes,
101-
// An explicit --depth request is a precise ask — no extension past it.
102-
deepExtensionCalls: options.depth == nil ? Self.privateAXDeepExtensionCallLimit : 0,
118+
deepExtensionCallLimit: exactDepthRequested ? 0 : Self.privateAXDeepExtensionCallLimit,
103119
deadline: deadline
104120
)
105121
if response["ok"] as? Bool == true {
@@ -120,7 +136,7 @@ extension RunnerTests {
120136
// Only a capture that actually descended records memory: a first-rung success on a
121137
// remembered depth deliberately does NOT refresh the TTL, so expiry re-probes the full
122138
// requested depth once per window instead of capping this screen class forever.
123-
if options.depth == nil, effectiveDepth != attemptDepths.first {
139+
if !exactDepthRequested, effectiveDepth != attemptDepths.first {
124140
rememberPrivateAXAcceptedDepth(
125141
bundleId: currentBundleId,
126142
processIdentifier: currentAppProcessIdentifier,
@@ -149,18 +165,22 @@ extension RunnerTests {
149165
return nil
150166
}
151167

152-
// A capture whose frontier extension drained every capped node is complete
153-
// despite the per-request depth cap — reporting it as depth-limited would
154-
// send agents chasing a --depth re-run that cannot add anything.
155-
let deepExtension = response["deepExtension"] as? [String: Any]
156-
let extensionDrained =
157-
deepExtension != nil && (deepExtension?["pendingFrontiers"] as? Int ?? 1) == 0
158-
let depthLimited = effectiveDepth < requestedDepth && !extensionDrained
168+
// A capture whose frontier extension resolved every capped node is
169+
// complete despite the per-request depth cap — reporting it as
170+
// depth-limited would send agents chasing deeper content that is not
171+
// there. Pending or missed frontiers keep the depth-limited verdict.
172+
let deepExtension = response[RunnerAXSnapshotDeepExtensionKey] as? [String: Any]
173+
let depthLimited = Self.privateAXDepthLimited(
174+
effectiveDepth: effectiveDepth,
175+
requestedDepth: requestedDepth,
176+
pendingFrontiers: deepExtension?[RunnerAXSnapshotDeepExtensionPendingKey] as? Int,
177+
missedFrontiers: deepExtension?[RunnerAXSnapshotDeepExtensionMissedKey] as? Int
178+
)
159179
NSLog(
160180
"AGENT_DEVICE_RUNNER_PRIVATE_AX_SNAPSHOT_USED nodes=%ld depth=%ld extended=%ld",
161181
nodes.count,
162182
effectiveDepth,
163-
deepExtension?["nodesAdded"] as? Int ?? 0
183+
deepExtension?[RunnerAXSnapshotDeepExtensionNodesAddedKey] as? Int ?? 0
164184
)
165185
return SnapshotBackendCapture(
166186
payload: DataPayload(nodes: nodes, truncated: (response["truncated"] as? Bool) == true),
@@ -346,6 +366,31 @@ extension RunnerTests {
346366
XCTAssertEqual(Self.privateAXAttemptDepths(requestedDepth: 24, rememberedDepth: 56), [24, 12])
347367
}
348368

369+
func testPrivateAXDepthLimitedRequiresEveryFrontierResolved() {
370+
// Un-capped capture is never depth-limited, extension or not.
371+
XCTAssertFalse(
372+
Self.privateAXDepthLimited(
373+
effectiveDepth: 64, requestedDepth: 64, pendingFrontiers: nil, missedFrontiers: nil))
374+
// Capped with no extension outcome (never ran) stays depth-limited.
375+
XCTAssertTrue(
376+
Self.privateAXDepthLimited(
377+
effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: nil, missedFrontiers: nil))
378+
// Fully drained extension clears the verdict.
379+
XCTAssertFalse(
380+
Self.privateAXDepthLimited(
381+
effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 0))
382+
// Budget exhaustion (pending frontiers) keeps it.
383+
XCTAssertTrue(
384+
Self.privateAXDepthLimited(
385+
effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 2, missedFrontiers: 0))
386+
// The #1627 review blocker: an all-miss extension (elements vanished or
387+
// re-rooted requests failed) resolved nothing — it must NOT present the
388+
// capture as complete just because the queue emptied.
389+
XCTAssertTrue(
390+
Self.privateAXDepthLimited(
391+
effectiveDepth: 56, requestedDepth: 64, pendingFrontiers: 0, missedFrontiers: 8))
392+
}
393+
349394
func testPrivateAXAcceptedDepthMemoryMatchesBundleProcessAndExpires() {
350395
defer { clearPrivateAXAcceptedDepth(reason: "test-cleanup") }
351396

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SnapshotCapturePlan.swift‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -553,8 +553,11 @@ extension RunnerTests {
553553
)
554554
}
555555
if let depth = quality.effectiveDepth {
556+
// No --depth remedy here: an explicit --depth capture disables the
557+
// frontier extension, so following it would return strictly less than
558+
// this capture did. A plain re-run retries with a fresh extension budget.
556559
parts.append(
557-
"The accessibility server rejected deeper requests; this tree is capped at depth \(depth) — re-run with --depth \(depth) --scope <container> for deeper content."
560+
"The accessibility server rejected deeper requests; content below depth \(depth) may be missing — re-run snapshot to retry deeper content."
558561
)
559562
}
560563
return parts.isEmpty ? nil : parts.joined(separator: " ")

0 commit comments

Comments
 (0)