@@ -6,32 +6,17 @@ import type { SessionState } from './types.ts';
66import { readSimpleSelectorTarget } from '@agent-device/selectors' ;
77import { asAppError } from '@agent-device/kernel/errors' ;
88import type { ElementSelectorTapOptions } from '@agent-device/contracts/interactor-types' ;
9+ import { queryAppleRuntimeSelector } from '../platform-runtime-apple-resources.ts' ;
10+ import type { AppleRunnerRequestOptions } from './apple-runner-options.ts' ;
911
1012export type DirectIosSelectorTarget = ElementSelectorTapOptions & { raw : string } ;
1113
12- /**
13- * Is this session eligible for a direct, tree-independent local XCTest
14- * runner read/tap? Both the Maestro selector-tap route and the offscreen
15- * refusal double-check probe (`src/daemon/offscreen-target-probe.ts`) share
16- * this "local runner, not a provider-owned device" boundary — provider-owned
17- * iOS devices resolve through their own interactor-backed runtime instead.
18- *
19- * The one difference between the two callers is explicit, not baked in: the
20- * Maestro tap route skips itself while a post-gesture stabilization is
21- * pending (it hands off to the tree-based runtime path instead), but the
22- * double-check must NOT inherit that skip — it exists specifically to cover
23- * the window where the bulk AX tree is stale (pending or just-cleared
24- * stabilization), so excluding that window would defeat its purpose.
25- */
2614export function isLocalIosRunnerSession (
2715 session : SessionState | undefined ,
2816 options : { skipPendingPostGestureStabilization : boolean } ,
2917) : session is SessionState {
3018 if ( ! session ) return false ;
3119 if ( ! isIosFamily ( session . device ) ) return false ;
32- // This fast path talks directly to the local XCTest runner. Provider-owned
33- // iOS devices must resolve through their interactor-backed snapshot runtime
34- // instead, which keeps selectors and interaction guarantees on one backend.
3520 if ( isActiveProviderDevice ( session . device ) ) return false ;
3621 if ( options . skipPendingPostGestureStabilization && isPostGestureStabilizationPending ( session ) ) {
3722 return false ;
@@ -50,12 +35,6 @@ export function readSimpleIosSelectorTarget(params: {
5035 return readSimpleSelectorTarget ( selectorExpression ) ;
5136}
5237
53- /**
54- * The selector a bulk-tree node's OWN attributes give us for a direct runner
55- * re-read: prefer the stable `id` (accessibility identifier), fall back to
56- * `label`. Neither is guaranteed unique on the runner side — an ambiguous
57- * match is the caller's problem to fail closed on, not this parser's.
58- */
5938export function deriveDirectIosNodeSelector (
6039 node : Pick < SnapshotNode , 'identifier' | 'label' > ,
6140) : { key : 'id' | 'label' ; value : string } | null {
@@ -66,23 +45,44 @@ export function deriveDirectIosNodeSelector(
6645 return null ;
6746}
6847
48+ export type DirectIosSelectorQueryResult = {
49+ found : boolean ;
50+ text ?: string ;
51+ node ?: SnapshotNode ;
52+ } ;
53+
54+ export async function queryDirectIosSelector (
55+ session : SessionState ,
56+ selector : Pick < DirectIosSelectorTarget , 'key' | 'value' > ,
57+ requestOptions : AppleRunnerRequestOptions ,
58+ ) : Promise < DirectIosSelectorQueryResult > {
59+ const data = await queryAppleRuntimeSelector (
60+ session . device ,
61+ selector ,
62+ session . appBundleId ,
63+ requestOptions ,
64+ ) ;
65+ const found = data . found === true ;
66+ const node = readDirectIosSelectorNode ( data ) ;
67+ return {
68+ found,
69+ ...( typeof data . text === 'string' ? { text : data . text } : { } ) ,
70+ ...( node ? { node } : { } ) ,
71+ } ;
72+ }
73+
74+ function readDirectIosSelectorNode ( data : Record < string , unknown > ) : SnapshotNode | undefined {
75+ const nodes = data . nodes ;
76+ if ( ! Array . isArray ( nodes ) ) return undefined ;
77+ const node = nodes [ 0 ] ;
78+ if ( ! node || typeof node !== 'object' ) return undefined ;
79+ return node as SnapshotNode ;
80+ }
81+
6982export function isDirectIosSelectorFallbackError (
7083 error : unknown ,
7184 options : {
72- /**
73- * Read/query callers (wait/get/is): a runner ELEMENT_NOT_FOUND re-resolves
74- * against the daemon tree, but AMBIGUOUS_MATCH still surfaces as-is.
75- */
7685 allowElementNotFound ?: boolean ;
77- /**
78- * ADR 0011 delegation-on-error for interaction dispatches: the runner's
79- * semantic failure shapes (ELEMENT_NOT_FOUND, AMBIGUOUS_MATCH) fall back
80- * to the tree-based runtime path, which supplies runtime disambiguation,
81- * non-hittable promotion/annotation, occlusion refusal, and rich selector
82- * diagnostics/hints. Must stay OFF for Maestro replay dispatches
83- * (allowNonHittableCoordinateFallback): replay matching is intentionally
84- * runner-native, so those error shapes must surface unchanged.
85- */
8686 delegateSemanticFailures ?: boolean ;
8787 } = { } ,
8888) : boolean {
@@ -91,22 +91,10 @@ export function isDirectIosSelectorFallbackError(
9191 return options . delegateSemanticFailures === true || options . allowElementNotFound === true ;
9292 }
9393 if ( appError . code === 'AMBIGUOUS_MATCH' ) return options . delegateSemanticFailures === true ;
94- // Regular interactions delegate off-screen matches to the shared tree, which
95- // can prefer an on-screen candidate or raise offscreen_selector. Maestro
96- // replay keeps the typed runner outcome so its compatibility resolver can
97- // apply Maestro-specific ranking and tab-strip inference instead.
9894 if ( appError . code === 'ELEMENT_OFFSCREEN' ) {
9995 return options . delegateSemanticFailures !== false ;
10096 }
10197 if ( appError . code !== 'COMMAND_FAILED' ) return false ;
102- // Transport-failure classification stays message-based deliberately: the
103- // sniffed shapes originate at 4+ scattered throw sites (runner-transport
104- // deadline errors, runner-contract connect errors, runner-session's invalid
105- // response) plus raw undici "fetch failed" TypeErrors that are only wrapped
106- // into AppError at this boundary — and isRetryableRunnerError performs the
107- // same message sniffing for retry policy. A typed transport marker needs a
108- // wrapping layer around all of them in one change; tracked as Tier-3 error
109- // cleanup, not worth entangling with this fallback decision.
11098 const message = appError . message . toLowerCase ( ) ;
11199 return (
112100 message . includes ( 'fetch failed' ) ||
0 commit comments