Skip to content

Commit 286c617

Browse files
committed
fix(android): bound helper fallback lifecycle
1 parent f038d70 commit 286c617

17 files changed

Lines changed: 613 additions & 117 deletions

‎src/commands/interaction/runtime/wait-deadline.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
import type { AgentDeviceRuntime, CommandContext } from '../../../runtime-contract.ts';
2-
31
export type WaitDeadlineResult<T> = { timedOut: false; value: T } | { timedOut: true };
42

3+
type AbortSignalSource = { signal?: AbortSignal };
4+
55
/**
66
* Applies a wait's remaining budget by cancellation, then waits for the operation to quiesce.
77
* This deliberately does not race-and-abandon the task: a late snapshot could otherwise mutate
88
* session state or keep ownership of a platform helper after the wait has returned.
99
*/
1010
export async function runWithinWaitDeadline<T>(
11-
runtime: Pick<AgentDeviceRuntime, 'signal'>,
12-
options: Pick<CommandContext, 'signal'>,
11+
runtime: AbortSignalSource,
12+
options: AbortSignalSource,
1313
remainingMs: number,
1414
task: (signal: AbortSignal) => Promise<T>,
1515
): Promise<WaitDeadlineResult<T>> {

‎src/contracts/interactor-types.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ export type RunnerContext = {
3131
/** Subset of {@link RunnerContext} forwarded to runner command invocations. */
3232
export type RunnerCallOptions = Pick<
3333
RunnerContext,
34+
| 'signal'
3435
| 'verbose'
3536
| 'logPath'
3637
| 'traceLogPath'

‎src/platforms/android/__tests__/snapshot-helper-session.test.ts‎

Lines changed: 126 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -140,27 +140,22 @@ test('allows a persistent session snapshot to use the helper command budget', as
140140
assert.equal(output?.metadata.sessionReused, false);
141141
});
142142

143-
test('caps a persistent session snapshot at the helper command budget', async () => {
143+
test('retires a persistent session that exceeds the helper command budget', async () => {
144144
const calls: string[][] = [];
145145
const provider = createSessionProvider({ calls, responseDelayMs: 50 });
146146

147-
await assert.rejects(
148-
() =>
149-
captureAndroidSnapshotWithHelperSession({
150-
adb: provider.exec,
151-
adbProvider: provider,
152-
deviceKey: 'android:emulator-5554',
153-
timeoutMs: 10,
154-
commandTimeoutMs: 20,
155-
}),
156-
(error) => {
157-
assert.equal((error as Error).message, 'Android snapshot helper session request timed out');
158-
const details = (error as { details?: Record<string, unknown> }).details;
159-
assert.equal(details?.timeoutMs, 20);
160-
assert.match(String(details?.command), /^snapshot snapshot-/);
161-
assert.equal(typeof details?.port, 'number');
162-
return true;
163-
},
147+
const output = await captureAndroidSnapshotWithHelperSession({
148+
adb: provider.exec,
149+
adbProvider: provider,
150+
deviceKey: 'android:emulator-5554',
151+
timeoutMs: 10,
152+
commandTimeoutMs: 20,
153+
});
154+
155+
assert.equal(output, undefined);
156+
assert.equal(
157+
calls.some((args) => args[0] === 'forward' && args[1] === '--remove'),
158+
true,
164159
);
165160
});
166161

@@ -194,6 +189,71 @@ test('cancels a stalled snapshot, retires its helper, and starts the next captur
194189
assert.equal(processes.length, 2);
195190
});
196191

192+
test('canceled capture joins canceled external cleanup before returning', async () => {
193+
const calls: string[][] = [];
194+
const cleanupAborts: string[][] = [];
195+
const provider = createSessionProvider({
196+
calls,
197+
cleanupAborts,
198+
stalledSnapshots: 1,
199+
stalledCleanup: true,
200+
});
201+
const controller = new AbortController();
202+
const capture = captureAndroidSnapshotWithHelperSession({
203+
adb: provider.exec,
204+
adbProvider: provider,
205+
deviceKey: 'android:emulator-5554',
206+
signal: controller.signal,
207+
});
208+
setTimeout(() => controller.abort(new Error('wait deadline exceeded')), 10);
209+
210+
const outcome = await Promise.race([
211+
capture.then(
212+
() => 'resolved',
213+
() => 'rejected',
214+
),
215+
new Promise<'still-pending'>((resolve) => setTimeout(() => resolve('still-pending'), 750)),
216+
]);
217+
218+
assert.equal(outcome, 'rejected');
219+
assert.equal(cleanupAborts.length, 2);
220+
});
221+
222+
test('failed capture does not fall back when device runtime retirement is unconfirmed', async () => {
223+
const calls: string[][] = [];
224+
const processes: FakeAndroidProcess[] = [];
225+
const provider = createSessionProvider({
226+
calls,
227+
processes,
228+
recoveryFailure: true,
229+
responseMode: 'malformed',
230+
stalledCleanup: true,
231+
});
232+
233+
await assert.rejects(
234+
captureAndroidSnapshotWithHelperSession({
235+
adb: provider.exec,
236+
adbProvider: provider,
237+
deviceKey: 'android:emulator-5554',
238+
}),
239+
(error: unknown) =>
240+
(error as { details?: { reason?: string } }).details?.reason ===
241+
'android_snapshot_helper_retirement_unconfirmed',
242+
);
243+
244+
await assert.rejects(
245+
captureAndroidSnapshotWithHelperSession({
246+
adb: provider.exec,
247+
adbProvider: { exec: provider.exec },
248+
deviceKey: 'android:emulator-5554',
249+
}),
250+
(error: unknown) =>
251+
(error as { details?: { reason?: string } }).details?.reason ===
252+
'android_snapshot_helper_retirement_unconfirmed',
253+
);
254+
assert.equal(processes.length, 1);
255+
});
256+
197257
test('restarts the helper session when capture options change', async () => {
198258
const calls: string[][] = [];
199259
const spawnArgs: string[][] = [];
@@ -258,7 +318,7 @@ test('force terminates the helper when quit is not acknowledged', async () => {
258318
assert.equal(processes[0]?.killed, true);
259319
});
260320

261-
test('force terminates a session whose UiAutomation connection timed out', async () => {
321+
test('force terminates and falls back from a session whose UiAutomation connection timed out', async () => {
262322
const calls: string[][] = [];
263323
const processes: FakeAndroidProcess[] = [];
264324
const provider = createSessionProvider({
@@ -267,56 +327,51 @@ test('force terminates a session whose UiAutomation connection timed out', async
267327
responseMode: 'ui-automation-timeout',
268328
});
269329

270-
await assert.rejects(
271-
captureAndroidSnapshotWithHelperSession({
272-
adb: provider.exec,
273-
adbProvider: provider,
274-
deviceKey: 'android:emulator-5554',
275-
}),
276-
/Timed out waiting for Android UiAutomation to connect/,
277-
);
330+
const output = await captureAndroidSnapshotWithHelperSession({
331+
adb: provider.exec,
332+
adbProvider: provider,
333+
deviceKey: 'android:emulator-5554',
334+
});
278335

336+
assert.equal(output, undefined);
279337
assert.equal(processes[0]?.killed, true);
280338
});
281339

282-
test('invalidates the helper session after a malformed response', async () => {
340+
test('invalidates and falls back from the helper session after a malformed response', async () => {
283341
const calls: string[][] = [];
284342
const provider = createSessionProvider({ calls, responseMode: 'malformed' });
285343

286-
await assert.rejects(
287-
() =>
288-
captureAndroidSnapshotWithHelperSession({
289-
adb: provider.exec,
290-
adbProvider: provider,
291-
deviceKey: 'android:emulator-5554',
292-
}),
293-
{
294-
message: 'Android snapshot helper session returned malformed output',
295-
},
296-
);
344+
const output = await captureAndroidSnapshotWithHelperSession({
345+
adb: provider.exec,
346+
adbProvider: provider,
347+
deviceKey: 'android:emulator-5554',
348+
});
297349

350+
assert.equal(output, undefined);
298351
assert.equal(
299352
calls.some((args) => args[0] === 'forward' && args[1] === '--remove'),
300353
true,
301354
);
302355
});
303356

304-
function createSessionProvider(options: {
357+
type SessionProviderOptions = {
305358
calls: string[][];
359+
cleanupAborts?: string[][];
306360
processes?: FakeAndroidProcess[];
307361
quitExitDelayMs?: number;
308362
quitResponseMode?: 'ok' | 'malformed';
309363
spawnArgs?: string[][];
310364
responseMode?: 'ok' | 'malformed' | 'ui-automation-timeout';
311365
responseDelayMs?: number;
366+
recoveryFailure?: boolean;
367+
stalledCleanup?: boolean;
312368
stalledSnapshots?: number;
313-
}): AndroidAdbProvider {
369+
};
370+
371+
function createSessionProvider(options: SessionProviderOptions): AndroidAdbProvider {
314372
let stalledSnapshots = options.stalledSnapshots ?? 0;
315373
return {
316-
exec: async (args) => {
317-
options.calls.push(args);
318-
return { exitCode: 0, stdout: '', stderr: '' };
319-
},
374+
exec: createSessionExec(options),
320375
spawn: (args) => {
321376
options.spawnArgs?.push(args);
322377
const port = readSessionPort(args);
@@ -411,6 +466,32 @@ function createSessionProvider(options: {
411466
};
412467
}
413468

469+
function createSessionExec(options: SessionProviderOptions): AndroidAdbExecutor {
470+
return async (args, execOptions) => {
471+
options.calls.push(args);
472+
const forceStopsRuntime = args.join(' ').includes('am force-stop');
473+
if (
474+
options.stalledCleanup &&
475+
execOptions?.signal &&
476+
((args[0] === 'forward' && args[1] === '--remove') || forceStopsRuntime)
477+
) {
478+
return await new Promise<never>((_resolve, reject) => {
479+
const signal = execOptions.signal;
480+
const onAbort = () => {
481+
options.cleanupAborts?.push(args);
482+
reject(signal?.reason);
483+
};
484+
signal?.addEventListener('abort', onAbort, { once: true });
485+
if (signal?.aborted) onAbort();
486+
});
487+
}
488+
if (options.recoveryFailure && forceStopsRuntime) {
489+
return { exitCode: 1, stdout: '', stderr: 'runtime still busy' };
490+
}
491+
return { exitCode: 0, stdout: '', stderr: '' };
492+
};
493+
}
494+
414495
function sessionResponse(params: {
415496
requestId: string;
416497
body: string;

0 commit comments

Comments
 (0)