Skip to content

Commit 1fddbe9

Browse files
thymikeeclaude
andcommitted
refactor(android): record the answering helper transport on its capture timer
The snapshot helper's capture timers now name the transport they drove, and the session timer records whether the session answered. profile.ts reads those fields per event instead of inferring a silent session from event order, and no longer re-spells the producer names platform-android owns. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 21e3ffb commit 1fddbe9

4 files changed

Lines changed: 158 additions & 41 deletions

File tree

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
import { afterEach, beforeEach, test } from 'vitest';
2+
import assert from 'node:assert/strict';
3+
import { promises as fs } from 'node:fs';
4+
import path from 'node:path';
5+
import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics';
6+
import type { DeviceInfo } from '@agent-device/kernel/device';
7+
import {
8+
ANDROID_SNAPSHOT_HELPER_CAPTURE_PHASE as ONE_SHOT_PHASE,
9+
ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE as SESSION_PHASE,
10+
snapshotAndroid,
11+
} from '../snapshot.ts';
12+
import { resetAndroidSnapshotHelperInstallCache } from '../snapshot-helper-install.ts';
13+
import { resetAndroidSnapshotHelperSessions } from '../snapshot-helper-session-lifecycle.ts';
14+
import { ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT } from './test-utils/android-snapshot-helper.ts';
15+
import { createPersistentSnapshotHelperProvider } from './snapshot-helper-session.fixtures.ts';
16+
import { mkdtempForTest } from './test-utils/tmp-dir.ts';
17+
18+
const device: DeviceInfo = {
19+
platform: 'android',
20+
id: 'emulator-5554',
21+
name: 'Pixel',
22+
kind: 'emulator',
23+
booted: true,
24+
};
25+
26+
beforeEach(async () => {
27+
await resetAndroidSnapshotHelperSessions();
28+
resetAndroidSnapshotHelperInstallCache();
29+
});
30+
31+
afterEach(async () => {
32+
await resetAndroidSnapshotHelperSessions();
33+
});
34+
35+
async function captureTimers(sessionResponseMode?: 'malformed') {
36+
const provider = createPersistentSnapshotHelperProvider({
37+
calls: [],
38+
spawnArgs: [],
39+
processes: [],
40+
sessionResponseMode,
41+
oneShotXml: '<hierarchy><node text="one-shot fallback" bounds="[0,0][10,10]" /></hierarchy>',
42+
});
43+
const tmpDir = await mkdtempForTest('agent-device-android-capture-timers-');
44+
const logPath = path.join(tmpDir, 'diag.ndjson');
45+
try {
46+
await withDiagnosticsScope(
47+
{ debug: true, logPath, session: 'android-test', requestId: 'req-1', command: 'snapshot' },
48+
async () =>
49+
await snapshotAndroid(device, {
50+
helperAdb: provider,
51+
helperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
52+
}),
53+
);
54+
return (await fs.readFile(logPath, 'utf8'))
55+
.split('\n')
56+
.filter(Boolean)
57+
.map((line) => JSON.parse(line) as { phase: string; data?: Record<string, unknown> })
58+
.filter(({ phase }) => phase === SESSION_PHASE || phase === ONE_SHOT_PHASE)
59+
.map(({ phase, data }) => ({ phase, transport: data?.transport, answered: data?.answered }));
60+
} finally {
61+
await fs.rm(tmpDir, { recursive: true, force: true });
62+
}
63+
}
64+
65+
test('each helper capture timer records its transport and whether the session answered', async () => {
66+
assert.deepEqual(await captureTimers(), [
67+
{ phase: SESSION_PHASE, transport: 'persistent-session', answered: true },
68+
]);
69+
await resetAndroidSnapshotHelperSessions();
70+
assert.deepEqual(await captureTimers('malformed'), [
71+
{ phase: SESSION_PHASE, transport: 'persistent-session', answered: false },
72+
{ phase: ONE_SHOT_PHASE, transport: 'instrumentation', answered: undefined },
73+
]);
74+
});

‎packages/platform-android/src/snapshot.ts‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import {
3636
ANDROID_SNAPSHOT_HELPER_COMMAND_TIMEOUT_MS,
3737
type AndroidHelperSessionScope,
3838
type AndroidSnapshotHelperCaptureOptions,
39+
type AndroidSnapshotHelperTransport,
3940
} from './snapshot-helper-types.ts';
4041
import {
4142
captureAndroidSnapshotWithHelper,
@@ -102,10 +103,17 @@ const HELPER_CONTENT_RECAPTURE_DELAY_MS = 250;
102103
* a busy screen run a snapshot past the daemon request envelope.
103104
*/
104105
const HELPER_CONTENT_RECAPTURE_WINDOW_MS = 10_000;
105-
/** The diagnostic phase of a capture through the snapshot helper's persistent session. */
106+
/**
107+
* The diagnostic phase of a capture through the snapshot helper's persistent session. Its
108+
* `data.transport` names the session transport, and `data.answered` is false when the session
109+
* returned no capture (off, backed off, failed to start, or retired) and a one-shot capture follows.
110+
*/
106111
export const ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE =
107112
'android_snapshot_helper_session_capture';
108-
/** The diagnostic phase of a one-shot `am instrument` snapshot helper capture. */
113+
/**
114+
* The diagnostic phase of a one-shot `am instrument` snapshot helper capture. Its `data.transport`
115+
* names the instrumentation transport.
116+
*/
109117
export const ANDROID_SNAPSHOT_HELPER_CAPTURE_PHASE = 'android_snapshot_helper_capture';
110118

111119
export type AndroidSnapshotOptions = SnapshotOptions & {
@@ -469,15 +477,18 @@ async function captureAndroidUiHierarchyFromHelper(params: {
469477
signal,
470478
});
471479
captureOptions.idleWait = params.idleWait;
480+
let sessionCapture: AndroidSnapshotHelperOutput | undefined;
472481
try {
473-
const sessionCapture = await withDiagnosticTimer(
482+
sessionCapture = await withDiagnosticTimer(
474483
ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE,
475-
async () => await captureAndroidSnapshotWithHelperSession(captureOptions),
476-
{
484+
async () => (sessionCapture = await captureAndroidSnapshotWithHelperSession(captureOptions)),
485+
() => ({
477486
packageName: artifact.manifest.packageName,
478487
version: artifact.manifest.version,
479488
timeoutMs: ANDROID_SNAPSHOT_HELPER_CAPTURE_TIMEOUT_MS,
480-
},
489+
transport: 'persistent-session' satisfies AndroidSnapshotHelperTransport,
490+
answered: sessionCapture !== undefined,
491+
}),
481492
);
482493
if (sessionCapture) return sessionCapture;
483494
} catch (error) {
@@ -500,6 +511,7 @@ async function captureAndroidUiHierarchyFromHelper(params: {
500511
version: artifact.manifest.version,
501512
timeoutMs: ANDROID_SNAPSHOT_HELPER_CAPTURE_TIMEOUT_MS,
502513
commandTimeoutMs: ANDROID_SNAPSHOT_HELPER_COMMAND_TIMEOUT_MS,
514+
transport: 'instrumentation' satisfies AndroidSnapshotHelperTransport,
503515
},
504516
);
505517
}

‎scripts/perf/profile.test.ts‎

Lines changed: 53 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
ANDROID_SNAPSHOT_HELPER_CAPTURE_PHASE,
77
ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE,
88
ANDROID_TOUCH_HELPER_GESTURE_PHASE,
9+
type AndroidSnapshotHelperTransport,
910
} from '@agent-device/platform-android/mechanics';
1011
import { test } from 'vitest';
1112
import {
@@ -125,32 +126,46 @@ test('reads the settle wait of a --settle response and nothing from other respon
125126
});
126127

127128
// Trimmed from Android heavy-feed request logs.
128-
const androidCapture = (session: Record<string, unknown>, oneShot = false) =>
129+
const sessionTimer = (answered: boolean, event: Record<string, unknown> = {}) =>
130+
line({
131+
phase: ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE,
132+
...event,
133+
data: {
134+
transport: 'persistent-session' satisfies AndroidSnapshotHelperTransport,
135+
answered,
136+
...(event.data as Record<string, unknown> | undefined),
137+
},
138+
});
139+
const oneShotTimer = [
140+
line({
141+
level: 'debug',
142+
phase: 'exec_command',
143+
durationMs: 373,
144+
data: { command: 'adb', event: 'settled' },
145+
}),
146+
line({
147+
phase: ANDROID_SNAPSHOT_HELPER_CAPTURE_PHASE,
148+
durationMs: 373,
149+
data: { transport: 'instrumentation' satisfies AndroidSnapshotHelperTransport },
150+
}),
151+
];
152+
const androidCapture = (...timers: string[]) =>
129153
[
130-
line({ phase: ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE, ...session }),
131-
...(oneShot
132-
? [
133-
line({
134-
level: 'debug',
135-
phase: 'exec_command',
136-
durationMs: 373,
137-
data: { command: 'adb', event: 'settled' },
138-
}),
139-
line({ phase: ANDROID_SNAPSHOT_HELPER_CAPTURE_PHASE, durationMs: 373 }),
140-
]
141-
: []),
154+
...timers,
142155
line({ phase: 'snapshot_capture', durationMs: 380, data: { backend: 'android' } }),
143156
].join('\n');
144157

145158
test('names the Android helper transport that answered each capture', () => {
146-
const session = profileRequestLog(androidCapture({ durationMs: 40 }));
159+
const session = profileRequestLog(androidCapture(sessionTimer(true, { durationMs: 40 })));
147160
assert.deepEqual(session.snapshotSources, {
148161
'android-helper/persistent-session': { count: 1, totalMs: 40, failures: 0 },
149162
});
150163
assert.deepEqual(session.fallbacks, []);
151164

152-
// With the session off, the session timer settles cleanly and a one-shot capture answers.
153-
const sessionOff = profileRequestLog(androidCapture({ durationMs: 0 }, true));
165+
// With the session off, the session timer settles unanswered and a one-shot capture answers.
166+
const sessionOff = profileRequestLog(
167+
androidCapture(sessionTimer(false, { durationMs: 0 }), ...oneShotTimer),
168+
);
154169
assert.deepEqual(sessionOff.snapshotSources, {
155170
'android-helper/persistent-session': { count: 1, totalMs: 0, failures: 1 },
156171
'android-helper/instrumentation': { count: 1, totalMs: 373, failures: 0 },
@@ -165,7 +180,10 @@ test('names the Android helper transport that answered each capture', () => {
165180

166181
const sessionFailed = profileRequestLog(
167182
[
168-
androidCapture({ level: 'error', durationMs: 5000, data: { error: 'socket closed' } }, true),
183+
androidCapture(
184+
sessionTimer(false, { level: 'error', durationMs: 5000, data: { error: 'socket closed' } }),
185+
...oneShotTimer,
186+
),
169187
line({
170188
level: 'warn',
171189
phase: 'android_snapshot_helper_session_fallback',
@@ -184,6 +202,24 @@ test('names the Android helper transport that answered each capture', () => {
184202
]);
185203
});
186204

205+
test('reads whether the Android session answered from its own timer, not from event order', () => {
206+
// A content re-capture can follow a session capture that answered. The answer still counts.
207+
const recaptured = profileRequestLog(
208+
androidCapture(sessionTimer(true, { durationMs: 40 }), ...oneShotTimer),
209+
);
210+
assert.deepEqual(recaptured.snapshotSources['android-helper/persistent-session'], {
211+
count: 1,
212+
totalMs: 40,
213+
failures: 0,
214+
});
215+
216+
// A request that ends before any one-shot capture still records the unanswered session.
217+
const unanswered = profileRequestLog(androidCapture(sessionTimer(false, { durationMs: 12 })));
218+
assert.deepEqual(unanswered.snapshotSources, {
219+
'android-helper/persistent-session': { count: 1, totalMs: 12, failures: 1 },
220+
});
221+
});
222+
187223
test('counts Android helper gestures as runner commands', () => {
188224
const profile = profileRequestLog(
189225
[

‎scripts/perf/profile.ts‎

Lines changed: 13 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,6 @@ type DiagnosticEvent = {
3131
data?: Record<string, unknown>;
3232
};
3333

34-
// Android: the snapshot helper answers through its persistent session, or through a one-shot
35-
// `am instrument` capture when the session is off or fails. Touch gestures run in the helper too.
36-
const ANDROID_SESSION_PRODUCER = 'android-helper/persistent-session';
37-
const ANDROID_ONE_SHOT_PRODUCER = 'android-helper/instrumentation';
3834
const STABILIZATION_PHASE = /settle|stabiliz/i;
3935
const FALLBACK_TEXT_LIMIT = 140;
4036

@@ -74,19 +70,15 @@ export function profileRequestLog(ndjson: string): SampleProfile {
7470
fallbacks: [],
7571
};
7672
const fallbacks = new Set<string>();
77-
const addSource = (producer: string, event: DiagnosticEvent): boolean => {
73+
const addSource = (producer: string, event: DiagnosticEvent, answered = true): void => {
7874
const entry = (profile.snapshotSources[producer] ??= { count: 0, totalMs: 0, failures: 0 });
7975
entry.count += 1;
8076
entry.totalMs += eventDuration(event) ?? 0;
8177
const error = text(event.data?.error);
82-
if (!error && event.level !== 'error') return true;
83-
entry.failures += 1;
84-
fallbacks.add(`${producer}: ${error ?? 'failed'}`);
85-
return false;
78+
const failed = error !== undefined || event.level === 'error';
79+
if (failed || !answered) entry.failures += 1;
80+
if (failed) fallbacks.add(`${producer}: ${error ?? 'failed'}`);
8681
};
87-
// A session capture that settles cleanly but is followed by a one-shot capture did not answer:
88-
// the session is off, and the one-shot capture served the request.
89-
let sessionAnswered = false;
9082
let firstTs: number | undefined;
9183
let lastTs: number | undefined;
9284
for (const line of ndjson.split('\n')) {
@@ -113,12 +105,15 @@ export function profileRequestLog(ndjson: string): SampleProfile {
113105
addTiming(profile.runnerCommands, text(data.command) ?? 'unknown', duration);
114106
} else if (phase === SNAPSHOT_SOURCE_ACQUIRE_PHASE) {
115107
addSource(text(data.producer) ?? 'unknown', event);
116-
} else if (phase === ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE) {
117-
sessionAnswered = addSource(ANDROID_SESSION_PRODUCER, event);
118-
} else if (phase === ANDROID_SNAPSHOT_HELPER_CAPTURE_PHASE) {
119-
if (sessionAnswered) profile.snapshotSources[ANDROID_SESSION_PRODUCER]!.failures += 1;
120-
sessionAnswered = false;
121-
addSource(ANDROID_ONE_SHOT_PRODUCER, event);
108+
} else if (
109+
phase === ANDROID_SNAPSHOT_HELPER_SESSION_CAPTURE_PHASE ||
110+
phase === ANDROID_SNAPSHOT_HELPER_CAPTURE_PHASE
111+
) {
112+
addSource(
113+
`android-helper/${text(data.transport) ?? 'unknown'}`,
114+
event,
115+
data.answered !== false,
116+
);
122117
} else if (phase === ANDROID_TOUCH_HELPER_GESTURE_PHASE) {
123118
addTiming(profile.runnerCommands, 'gesture', duration);
124119
if (event.level === 'error') fallbacks.add(`${phase}: ${text(data.error) ?? 'failed'}`);

0 commit comments

Comments
 (0)