Skip to content

Commit b00e530

Browse files
committed
fix(android): cancel stalled wait captures
1 parent b5a2bd3 commit b00e530

22 files changed

Lines changed: 501 additions & 104 deletions

‎src/commands/interaction/runtime/selector-read-shared.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ export async function captureSelectorSnapshot(
8181
...(result.quality ? { snapshotQuality: result.quality } : {}),
8282
createdAt: now(runtime),
8383
} satisfies SnapshotState);
84+
(options.signal ?? runtime.signal)?.throwIfAborted();
8485
if (
8586
captureOptions.updateSession &&
8687
session &&

‎src/commands/interaction/runtime/selector-read-stable.test.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -338,12 +338,23 @@ test('runtime wait stable times out with capture stats when never settling', asy
338338

339339
test('runtime wait stable times out when a backend capture stalls past the wait budget', async () => {
340340
const clock = createFakeClock();
341+
let captureAborted = false;
341342
const device = createAgentDevice({
342343
backend: {
343344
platform: 'macos',
344-
// Simulates the stalled macOS AX capture: the promise never settles, so
345-
// only the real-timer deadline can end the wait.
346-
captureSnapshot: () => new Promise<BackendSnapshotResult>(() => {}),
345+
// Simulates a stalled macOS AX capture that honors the backend cancellation contract.
346+
captureSnapshot: (context) =>
347+
new Promise<BackendSnapshotResult>((_resolve, reject) => {
348+
assert.ok(context.signal);
349+
context.signal.addEventListener(
350+
'abort',
351+
() => {
352+
captureAborted = true;
353+
reject(context.signal?.reason);
354+
},
355+
{ once: true },
356+
);
357+
}),
347358
} satisfies AgentDeviceBackend,
348359
artifacts: createLocalArtifactAdapter(),
349360
sessions: createMemorySessionStore([{ name: 'default' }]),
@@ -367,6 +378,7 @@ test('runtime wait stable times out when a backend capture stalls past the wait
367378
return true;
368379
},
369380
);
381+
assert.equal(captureAborted, true);
370382
});
371383

372384
test('runtime wait stable uses provided defaults when quietMs/timeoutMs are omitted', async () => {

‎src/commands/interaction/runtime/selector-read.test.ts‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -723,6 +723,59 @@ test('runtime wait keeps the plain timeout when readable polls simply never matc
723723
);
724724
});
725725

726+
test('runtime wait reports a stalled final capture over an earlier unreadable verdict', async () => {
727+
let captureCount = 0;
728+
const initial = makeSnapshotState([{ index: 0, depth: 0, type: 'Other', label: 'Initial' }]);
729+
const sessions = createMemorySessionStore([{ name: 'default', snapshot: initial }]);
730+
const device = createAgentDevice({
731+
backend: {
732+
platform: 'android',
733+
captureSnapshot: (context) => {
734+
captureCount += 1;
735+
if (captureCount === 1) throw unreadableCaptureError();
736+
return new Promise((resolve) => {
737+
context.signal?.addEventListener(
738+
'abort',
739+
() => {
740+
setTimeout(
741+
() =>
742+
resolve({
743+
snapshot: makeSnapshotState([
744+
{ index: 0, depth: 0, type: 'Other', label: 'Late capture' },
745+
]),
746+
}),
747+
5,
748+
);
749+
},
750+
{ once: true },
751+
);
752+
});
753+
},
754+
} satisfies AgentDeviceBackend,
755+
artifacts: createLocalArtifactAdapter(),
756+
sessions,
757+
policy: localCommandPolicy(),
758+
clock: createFakeClock(),
759+
});
760+
761+
await assert.rejects(
762+
device.selectors.wait({
763+
session: 'default',
764+
target: { kind: 'selector', selector: 'label="Screen X"', timeoutMs: 400 },
765+
}),
766+
(error: unknown) => {
767+
assert.ok(error instanceof Error);
768+
assert.equal(error.message, 'wait timed out for selector: label="Screen X"');
769+
assert.equal(
770+
(error as { details?: Record<string, unknown> }).details?.reason,
771+
'wait_capture_stalled',
772+
);
773+
return true;
774+
},
775+
);
776+
assert.deepEqual((await sessions.get('default'))?.snapshot, initial);
777+
});
778+
726779
function failingWaitDevice(produceError: () => Error): {
727780
device: ReturnType<typeof createAgentDevice>;
728781
attempts: () => number;

‎src/commands/interaction/runtime/selector-read.ts‎

Lines changed: 79 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ import {
3333
buildIndexMap,
3434
filterIdentitySet,
3535
} from '../../../replay/target-evidence-tree.ts';
36+
import { runWithinWaitDeadline } from './wait-deadline.ts';
3637
import {
3738
annotationLocalIdentity,
3839
type TargetAnnotationV1,
@@ -578,15 +579,31 @@ async function waitForSelector(
578579
// polling; only the deadline turns this into the fail-closed refusal.
579580
let landmarkMismatch: WaitLandmarkMismatchEvidence | undefined;
580581
const unreadable = createUnreadablePollTracker();
582+
let captureStalled = false;
581583
while (now(runtime) - start < timeout) {
582584
// Presence-only poll: skip scroll-hint derivation (#1270), same as waitForFindMatch.
583-
const capture = await unreadable.attempt(() =>
584-
captureSelectorSnapshot(runtime, options, {
585-
updateSession: true,
586-
includeHiddenContentHints: false,
587-
...capturePolicy,
588-
}),
585+
const poll = await runUnreadableWaitPoll(
586+
runtime,
587+
options,
588+
unreadable,
589+
start,
590+
timeout,
591+
async (signal) =>
592+
await captureSelectorSnapshot(
593+
runtime,
594+
{ ...options, signal },
595+
{
596+
updateSession: true,
597+
includeHiddenContentHints: false,
598+
...capturePolicy,
599+
},
600+
),
589601
);
602+
if (poll.timedOut) {
603+
captureStalled = true;
604+
break;
605+
}
606+
const capture = poll.value;
590607
if (capture) {
591608
const nodes = capture.snapshot.nodes;
592609
const matchList = listSelectorChainMatches(nodes, chain, {
@@ -608,6 +625,9 @@ async function waitForSelector(
608625
}
609626
await sleep(runtime, POLL_INTERVAL_MS);
610627
}
628+
if (captureStalled) {
629+
throw waitCaptureStalledError(`wait timed out for selector: ${selectorExpression}`, timeout);
630+
}
611631
if (landmarkMismatch) {
612632
throw new AppError(
613633
'COMMAND_FAILED',
@@ -628,10 +648,12 @@ async function waitForSelector(
628648
* deadline so persistent breakage keeps its capture diagnosis instead of a
629649
* generic timeout.
630650
*/
631-
function createUnreadablePollTracker(): {
651+
type UnreadablePollTracker = {
632652
attempt: <T>(capture: () => Promise<T>) => Promise<T | undefined>;
633653
rethrowIfNeverReadable: () => void;
634-
} {
654+
};
655+
656+
function createUnreadablePollTracker(): UnreadablePollTracker {
635657
let sawReadableCapture = false;
636658
let lastUnreadableError: unknown;
637659
return {
@@ -702,19 +724,64 @@ async function waitForText(
702724
const timeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
703725
const start = now(runtime);
704726
const unreadable = createUnreadablePollTracker();
727+
let captureStalled = false;
705728
while (now(runtime) - start < timeout) {
706-
const found = await unreadable.attempt(async () =>
707-
runtime.backend.findText
708-
? (await runtime.backend.findText(toBackendContext(runtime, options), text)).found
709-
: await snapshotContainsText(runtime, options, text),
729+
const poll = await runUnreadableWaitPoll(
730+
runtime,
731+
options,
732+
unreadable,
733+
start,
734+
timeout,
735+
async (signal) =>
736+
runtime.backend.findText
737+
? (
738+
await runtime.backend.findText(
739+
toBackendContext(runtime, { ...options, signal }),
740+
text,
741+
)
742+
).found
743+
: await snapshotContainsText(runtime, { ...options, signal }, text),
710744
);
745+
if (poll.timedOut) {
746+
captureStalled = true;
747+
break;
748+
}
749+
const found = poll.value;
711750
if (found) return { kind: 'text', text, waitedMs: now(runtime) - start };
712751
await sleep(runtime, POLL_INTERVAL_MS);
713752
}
753+
if (captureStalled) {
754+
throw waitCaptureStalledError(`wait timed out for text: ${text}`, timeout);
755+
}
714756
unreadable.rethrowIfNeverReadable();
715757
throw new AppError('COMMAND_FAILED', `wait timed out for text: ${text}`);
716758
}
717759

760+
async function runUnreadableWaitPoll<T>(
761+
runtime: AgentDeviceRuntime,
762+
options: WaitCommandOptions,
763+
unreadable: UnreadablePollTracker,
764+
start: number,
765+
timeoutMs: number,
766+
capture: (signal: AbortSignal) => Promise<T>,
767+
) {
768+
return await runWithinWaitDeadline(
769+
runtime,
770+
options,
771+
timeoutMs - (now(runtime) - start),
772+
async (signal) => await unreadable.attempt(() => capture(signal)),
773+
);
774+
}
775+
776+
function waitCaptureStalledError(message: string, timeoutMs: number): AppError {
777+
return new AppError('COMMAND_FAILED', message, {
778+
reason: 'wait_capture_stalled',
779+
captureStalled: true,
780+
timeoutMs,
781+
hint: 'A snapshot capture stalled past the wait timeout. Retry, or use screenshot to inspect the current surface.',
782+
});
783+
}
784+
718785
async function snapshotContainsText(
719786
runtime: AgentDeviceRuntime,
720787
options: WaitCommandOptions,

‎src/commands/interaction/runtime/stable-capture.ts‎

Lines changed: 13 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
type CapturedSnapshot,
77
type SelectorSnapshotOptions,
88
} from './selector-read-shared.ts';
9+
import { runWithinWaitDeadline } from './wait-deadline.ts';
910

1011
/**
1112
* The quiet-window stable-capture loop shared by `wait stable` and the
@@ -184,35 +185,24 @@ function stableCaptureDelayMs(params: {
184185
// Resolves undefined when the capture does not return within remainingMs. A
185186
// stalled backend capture (observed with macOS AX captures) must not push the
186187
// stable wait past the user-supplied timeout into the daemon request timeout.
187-
// The deadline uses a real timer even when runtime.clock is injected: test
188-
// clocks advance synthetic time synchronously and cannot represent a hung
189-
// backend call.
188+
// The deadline cancels and joins the capture before returning so no late capture
189+
// can overwrite session state or retain a platform helper.
190190
async function captureStableSignalWithinDeadline(
191191
runtime: AgentDeviceRuntime,
192192
options: CommandContext & SelectorSnapshotOptions,
193193
remainingMs: number,
194194
): Promise<CapturedSnapshot | undefined> {
195-
const capture = captureSelectorSnapshot(runtime, options, {
196-
updateSession: false,
197-
interactiveOnly: true,
195+
const result = await runWithinWaitDeadline(runtime, options, remainingMs, async (signal) => {
196+
return await captureSelectorSnapshot(
197+
runtime,
198+
{ ...options, signal },
199+
{
200+
updateSession: false,
201+
interactiveOnly: true,
202+
},
203+
);
198204
});
199-
let timer: NodeJS.Timeout | undefined;
200-
try {
201-
const result = await Promise.race([
202-
capture,
203-
new Promise<undefined>((resolve) => {
204-
timer = setTimeout(() => resolve(undefined), remainingMs);
205-
}),
206-
]);
207-
if (result === undefined) {
208-
// The abandoned capture settles (or fails) on its own; swallow it so it
209-
// cannot surface as an unhandled rejection after the wait already threw.
210-
capture.catch(() => {});
211-
}
212-
return result;
213-
} finally {
214-
if (timer !== undefined) clearTimeout(timer);
215-
}
205+
return result.timedOut ? undefined : result.value;
216206
}
217207

218208
function digestSnapshotNodes(nodes: SnapshotNode[]): string {
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import type { AgentDeviceRuntime, CommandContext } from '../../../runtime-contract.ts';
2+
3+
export type WaitDeadlineResult<T> = { timedOut: false; value: T } | { timedOut: true };
4+
5+
/**
6+
* Applies a wait's remaining budget by cancellation, then waits for the operation to quiesce.
7+
* This deliberately does not race-and-abandon the task: a late snapshot could otherwise mutate
8+
* session state or keep ownership of a platform helper after the wait has returned.
9+
*/
10+
export async function runWithinWaitDeadline<T>(
11+
runtime: Pick<AgentDeviceRuntime, 'signal'>,
12+
options: Pick<CommandContext, 'signal'>,
13+
remainingMs: number,
14+
task: (signal: AbortSignal) => Promise<T>,
15+
): Promise<WaitDeadlineResult<T>> {
16+
const deadlineController = new AbortController();
17+
const parentSignal = options.signal ?? runtime.signal;
18+
const signal = parentSignal
19+
? AbortSignal.any([parentSignal, deadlineController.signal])
20+
: deadlineController.signal;
21+
let deadlineExpired = false;
22+
const timer = setTimeout(
23+
() => {
24+
deadlineExpired = true;
25+
deadlineController.abort(new DOMException('Wait deadline exceeded', 'TimeoutError'));
26+
},
27+
Math.max(0, remainingMs),
28+
);
29+
timer.unref();
30+
31+
try {
32+
const value = await task(signal);
33+
if (deadlineExpired && !parentSignal?.aborted) return { timedOut: true };
34+
signal.throwIfAborted();
35+
return { timedOut: false, value };
36+
} catch (error) {
37+
if (deadlineExpired && !parentSignal?.aborted) return { timedOut: true };
38+
throw error;
39+
} finally {
40+
clearTimeout(timer);
41+
}
42+
}

‎src/contracts/interactor-types.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ import type {
1717

1818
export type RunnerContext = {
1919
requestId?: string;
20+
signal?: AbortSignal;
2021
appBundleId?: string;
2122
verbose?: boolean;
2223
logPath?: string;
@@ -71,6 +72,7 @@ export const MAESTRO_NON_HITTABLE_FALLBACK_MESSAGE = 'tapped via non-hittable co
7172

7273
export type SnapshotOptions = BaseSnapshotOptions & {
7374
appBundleId?: string;
75+
signal?: AbortSignal;
7476
includeRects?: boolean;
7577
includeHiddenContentHints?: boolean;
7678
surface?: SessionSurface;

‎src/core/dispatch-context.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import type { Point } from '../kernel/snapshot.ts';
1313

1414
export type DispatchContext = ScreenshotDispatchFlags & {
1515
requestId?: string;
16+
signal?: AbortSignal;
1617
appBundleId?: string;
1718
activity?: string;
1819
launchConsole?: string;

‎src/core/dispatch.ts‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ export async function dispatchGestureViewport(
9898
function runnerContextFromDispatchContext(context?: DispatchContext): RunnerContext {
9999
return {
100100
requestId: context?.requestId,
101+
signal: context?.signal,
101102
appBundleId: context?.appBundleId,
102103
verbose: context?.verbose,
103104
logPath: context?.logPath,
@@ -631,15 +632,17 @@ async function handleSnapshotCommand(
631632
interactor: Interactor,
632633
context: DispatchContext | undefined,
633634
): Promise<Record<string, unknown>> {
635+
const snapshotContext = context ?? {};
634636
return await interactor.snapshot({
635-
appBundleId: context?.appBundleId,
636-
interactiveOnly: context?.snapshotInteractiveOnly,
637-
depth: context?.snapshotDepth,
638-
scope: context?.snapshotScope,
639-
raw: context?.snapshotRaw,
640-
includeRects: context?.snapshotIncludeRects,
641-
includeHiddenContentHints: context?.snapshotIncludeHiddenContentHints,
642-
surface: context?.surface,
637+
appBundleId: snapshotContext.appBundleId,
638+
signal: snapshotContext.signal,
639+
interactiveOnly: snapshotContext.snapshotInteractiveOnly,
640+
depth: snapshotContext.snapshotDepth,
641+
scope: snapshotContext.snapshotScope,
642+
raw: snapshotContext.snapshotRaw,
643+
includeRects: snapshotContext.snapshotIncludeRects,
644+
includeHiddenContentHints: snapshotContext.snapshotIncludeHiddenContentHints,
645+
surface: snapshotContext.surface,
643646
});
644647
}
645648

0 commit comments

Comments
 (0)