Skip to content

Commit 3f9b9cf

Browse files
airoweclaude
andcommitted
fix(timeouts): prove the longpress request envelope with a worst-case ledger
The longpress envelope (210 s) rested on a hand sum that nothing checked. A provider-integration ledger test now drives the Android cold-helper route at the maximum hold through the daemon with a fake adb provider that charges each call its own timeout on a virtual clock. The slowest branch (checksum mismatch, an install refused as INSTALL_FAILED_UPDATE_INCOMPATIBLE, uninstall, reinstall, one-shot hold) costs 279,990 ms; with the 30 s daemon-result margin the envelope must be at least 309,990 ms, so it rises to 310 s and its comment points at the test. The 120 s hold cap becomes LONG_PRESS_DURATION_MAX_MS, read by both the validator and the test. Closes #3326 Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent defd554 commit 3f9b9cf

5 files changed

Lines changed: 216 additions & 9 deletions

File tree

‎packages/command-registry/src/registry.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1298,10 +1298,10 @@ export const RAW_COMMAND_DESCRIPTORS = [
12981298
frameworkTier: 'extended',
12991299
timeoutPolicy: {
13001300
...SETTLE_FLAG_PRESERVE_DAEMON_TIMEOUT_POLICY,
1301-
// Android's cold path may inspect/install the helper, hand off a running
1302-
// snapshot helper, hold for 120 seconds, then use 15 seconds of helper
1303-
// completion overhead. Keep that complete route inside the envelope.
1304-
envelopeMs: 210_000,
1301+
// Covers the Android cold-helper worst case at the maximum hold plus the
1302+
// daemon-result margin. Proven by the ledger test:
1303+
// test/integration/provider-scenarios/android-longpress-ledger.test.ts.
1304+
envelopeMs: 310_000,
13051305
},
13061306
postActionObservation: postActionObservation('longpress'),
13071307
batchable: true,

‎packages/contracts/src/gesture-plan-types.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ export type GestureContactCount = 1 | 2 | 3 | 4 | 5;
1515

1616
export const GESTURE_DURATION_MIN_MS = 16;
1717
export const GESTURE_DURATION_MAX_MS = 10_000;
18+
export const LONG_PRESS_DURATION_MAX_MS = 120_000;
1819
export const DEFAULT_DRAG_SOURCE_HOLD_MS = 800;
1920
export const DEFAULT_DRAG_MOVE_MS = 500;
2021
export const DEFAULT_DRAG_DESTINATION_HOLD_MS = 0;

‎src/__tests__/command-descriptor-timeout-policy.test.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,9 @@ test('request envelopes deviating from the default are bounded, reviewed sets',
149149
reinstall: 180_000,
150150
uninstall: 180_000,
151151
install_source: 180_000,
152-
longpress: 210_000,
152+
// longpress: proven by the worst-case ledger test in
153+
// test/integration/provider-scenarios/android-longpress-ledger.test.ts.
154+
longpress: 310_000,
153155
// fold: proven by the worst-case ledger test in
154156
// test/integration/provider-scenarios/ios-fold.test.ts.
155157
fold: 255_000,
@@ -260,7 +262,7 @@ test('interaction --settle budgets add post-action settle time on top of the nor
260262
positionals: ['300', '500', '120000'],
261263
flags: {},
262264
}),
263-
210_000,
265+
310_000,
264266
);
265267
// Bare --settle adds its default budget after the longpress-specific base,
266268
// so a maximum hold still leaves room for post-action observation.
@@ -269,7 +271,7 @@ test('interaction --settle budgets add post-action settle time on top of the nor
269271
...base,
270272
flags: { settle: true },
271273
}),
272-
250_000,
274+
350_000,
273275
);
274276
// Bare timeoutMs without --settle remains wire-compatible with older touch
275277
// command clients: it is ignored instead of opting into settle semantics.

‎src/commands/interaction/runtime/gestures.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
import type { DragGestureInput } from '@agent-device/contracts/gesture-plan-types';
1+
import {
2+
LONG_PRESS_DURATION_MAX_MS,
3+
type DragGestureInput,
4+
} from '@agent-device/contracts/gesture-plan-types';
25
import type {
36
HoverCommandResult,
47
LongPressCommandResult,
@@ -149,7 +152,7 @@ export const longPressCommand: RuntimeCommand<
149152
const durationMs =
150153
options.durationMs === undefined
151154
? undefined
152-
: requireIntInRange(options.durationMs, 'durationMs', 0, 120_000);
155+
: requireIntInRange(options.durationMs, 'durationMs', 0, LONG_PRESS_DURATION_MAX_MS);
153156
const point = requireResolvedPoint(resolved);
154157
const backendResult = await runtime.backend.longPress(toBackendContext(runtime, options), point, {
155158
durationMs,
Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
import { resolveCommandTimeoutPolicy } from '@agent-device/command-registry/registry';
2+
import { resolveCommandRequestTimeoutMs } from '@agent-device/command-registry/timeout-policy';
3+
import { LONG_PRESS_DURATION_MAX_MS } from '@agent-device/contracts/gesture-plan-types';
4+
import type {
5+
AndroidAdbExecutorOptions,
6+
AndroidAdbExecutorResult,
7+
AndroidAdbProvider,
8+
} from '@agent-device/platform-android/mechanics';
9+
import assert from 'node:assert/strict';
10+
import fs from 'node:fs';
11+
import { test, vi } from 'vitest';
12+
import { ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT } from '../../../src/__tests__/test-utils/android-snapshot-helper.ts';
13+
import { respondToAndroidSettingsAdbCommand } from './android-world.ts';
14+
import { assertRpcOk } from './assertions.ts';
15+
import { PROVIDER_SCENARIO_ANDROID } from './fixtures.ts';
16+
import { createProviderScenarioHarness } from './harness.ts';
17+
18+
// The longpress envelope must outlast the Android cold-helper route's worst case plus the margin
19+
// that lets the daemon's own typed result arrive first; otherwise the client gives up on a request
20+
// the device is still finishing. This test proves that bound against the real route: it imports no platform-android step figure, so it stays true
21+
// however the route's steps change. The only imported figure is the hold cap the validator reads.
22+
type LongPressLedgerCall = Readonly<{
23+
tool: 'exec' | 'install' | 'pull';
24+
args: readonly string[];
25+
timeoutMs: number;
26+
}>;
27+
28+
const HELPER = ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT.manifest;
29+
const HELPER_REMOTE_APK = `/data/app/~~ledger/${HELPER.packageName}/base.apk`;
30+
const ok: AndroidAdbExecutorResult = { stdout: '', stderr: '', exitCode: 0 };
31+
32+
function gestureHelperOutput(): string {
33+
return [
34+
`INSTRUMENTATION_RESULT: agentDeviceProtocol=${HELPER.statusProtocol}`,
35+
'INSTRUMENTATION_RESULT: helperApiVersion=1',
36+
'INSTRUMENTATION_RESULT: ok=true',
37+
'INSTRUMENTATION_RESULT: kind=swipe',
38+
'INSTRUMENTATION_CODE: 0',
39+
].join('\n');
40+
}
41+
42+
/**
43+
* The slowest cold-helper branch the route allows: the installed helper reports the bundled
44+
* versionCode, so identity falls through to the APK checksum (`pm path` + pull); the pulled APK
45+
* mismatches, so the helper is replaced; the first replace is rejected as
46+
* INSTALL_FAILED_UPDATE_INCOMPATIBLE, so the route uninstalls and installs again; then the hold runs
47+
* one-shot because no live helper session exists.
48+
*/
49+
function createLongPressLedgerAdbProvider(params: {
50+
isTracking: () => boolean;
51+
onCall: (call: LongPressLedgerCall) => void;
52+
}): { provider: AndroidAdbProvider; ledger: LongPressLedgerCall[] } {
53+
const ledger: LongPressLedgerCall[] = [];
54+
let installAttempts = 0;
55+
// A call without a bounded timeoutMs is not a worst case the envelope assertion can see, so it
56+
// fails the test rather than costing 0 virtual ms.
57+
const record = (
58+
tool: LongPressLedgerCall['tool'],
59+
args: readonly string[],
60+
options?: AndroidAdbExecutorOptions,
61+
): void => {
62+
if (!params.isTracking()) return;
63+
assert.ok(
64+
Number.isFinite(options?.timeoutMs) && options!.timeoutMs! > 0,
65+
`longpress ledger call has no bounded timeoutMs: ${tool} ${args.join(' ')}`,
66+
);
67+
const call: LongPressLedgerCall = { tool, args: [...args], timeoutMs: options!.timeoutMs! };
68+
ledger.push(call);
69+
params.onCall(call);
70+
};
71+
const provider: AndroidAdbProvider = {
72+
snapshotHelperArtifact: ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT,
73+
exec: async (args, options) => {
74+
record('exec', args, options);
75+
if (args.includes('--show-versioncode') && args.includes(HELPER.packageName)) {
76+
return {
77+
...ok,
78+
stdout: `package:${HELPER.packageName} versionCode:${HELPER.versionCode}\n`,
79+
};
80+
}
81+
if (args[0] === 'shell' && args[1] === 'pm' && args[2] === 'path') {
82+
return { ...ok, stdout: `package:${HELPER_REMOTE_APK}\n` };
83+
}
84+
if (args[0] === 'uninstall' && args[1] === HELPER.packageName) {
85+
return { ...ok, stdout: 'Success\n' };
86+
}
87+
if (args.includes('instrument') && args.includes('gesture')) {
88+
return { ...ok, stdout: gestureHelperOutput() };
89+
}
90+
if (args[0] === 'shell' && args[1] === 'am' && args[2] === 'start') {
91+
return { ...ok, stdout: 'Starting: Intent' };
92+
}
93+
return respondToAndroidSettingsAdbCommand([...args], '', '', {});
94+
},
95+
pull: async (remotePath, localPath, options) => {
96+
record('pull', [remotePath, localPath], options);
97+
fs.writeFileSync(localPath, 'a previously installed helper build');
98+
return ok;
99+
},
100+
install: async (apkPath, options) => {
101+
record('install', [apkPath], options);
102+
installAttempts += 1;
103+
if (installAttempts === 1) {
104+
return {
105+
stdout: '',
106+
stderr: 'Failure [INSTALL_FAILED_UPDATE_INCOMPATIBLE: signatures do not match]',
107+
exitCode: 1,
108+
};
109+
}
110+
return { ...ok, stdout: 'Success\n' };
111+
},
112+
};
113+
return { provider, ledger };
114+
}
115+
116+
function gestureDurationMs(call: LongPressLedgerCall): number | undefined {
117+
const payloadIndex = call.args.indexOf('payloadBase64');
118+
if (payloadIndex < 0) return undefined;
119+
const payload = JSON.parse(
120+
Buffer.from(call.args[payloadIndex + 1]!, 'base64').toString('utf8'),
121+
) as { durationMs?: unknown };
122+
return typeof payload.durationMs === 'number' ? payload.durationMs : undefined;
123+
}
124+
125+
function assertLongPressLedgerPhaseCoverage(ledger: readonly LongPressLedgerCall[]): void {
126+
const printed = `\nLedger:\n${JSON.stringify(ledger, null, 2)}`;
127+
const isVersionRead = (call: LongPressLedgerCall) =>
128+
call.tool === 'exec' && call.args.includes('--show-versioncode');
129+
const isApkPathRead = (call: LongPressLedgerCall) =>
130+
call.tool === 'exec' && call.args.includes('pm') && call.args.includes('path');
131+
const isGesture = (call: LongPressLedgerCall) =>
132+
call.tool === 'exec' && call.args.includes('instrument') && call.args.includes('gesture');
133+
134+
assert.ok(ledger.some(isVersionRead), `ledger is missing the helper version read${printed}`);
135+
assert.ok(ledger.some(isApkPathRead), `ledger is missing the helper APK path read${printed}`);
136+
assert.ok(
137+
ledger.some((call) => call.tool === 'pull'),
138+
`ledger is missing the helper APK pull${printed}`,
139+
);
140+
assert.equal(
141+
ledger.filter((call) => call.tool === 'install').length,
142+
2,
143+
`ledger must record the rejected helper install and its retry${printed}`,
144+
);
145+
assert.ok(
146+
ledger.some((call) => call.args[0] === 'uninstall'),
147+
`ledger is missing the incompatible-helper uninstall${printed}`,
148+
);
149+
const gestures = ledger.filter(isGesture);
150+
assert.equal(gestures.length, 1, `ledger must record exactly one gesture dispatch${printed}`);
151+
assert.equal(
152+
gestureDurationMs(gestures[0]!),
153+
LONG_PRESS_DURATION_MAX_MS,
154+
`the gesture dispatch must carry the maximum hold${printed}`,
155+
);
156+
}
157+
158+
test('longpress cold-helper worst-case ledger covers the client envelope with the daemon-result margin', async () => {
159+
// Matches REQUEST_TIMEOUT_BUDGET_MARGIN_MS, packages/command-registry/src/timeout-policy.ts.
160+
// Not imported: it is not exported (fallow would flag an export used only by a test).
161+
const REQUIRED_DAEMON_RESULT_MARGIN_MS = 30_000;
162+
163+
let virtualElapsedMs = 0;
164+
let tracking = false;
165+
const { provider, ledger } = createLongPressLedgerAdbProvider({
166+
isTracking: () => tracking,
167+
onCall: (call) => {
168+
virtualElapsedMs += Math.max(0, call.timeoutMs - 1);
169+
},
170+
});
171+
const dateSpy = vi.spyOn(Date, 'now');
172+
const daemon = await createProviderScenarioHarness({
173+
deviceInventoryProvider: async () => [PROVIDER_SCENARIO_ANDROID],
174+
androidAdbProvider: () => provider,
175+
});
176+
const selection = { platform: 'android', serial: PROVIDER_SCENARIO_ANDROID.id } as const;
177+
const positionals = ['195', '320', String(LONG_PRESS_DURATION_MAX_MS)];
178+
try {
179+
await daemon.client().apps.open({ app: 'com.android.settings', ...selection, testIme: false });
180+
tracking = true;
181+
const originNowMs = Date.now();
182+
dateSpy.mockImplementation(() => originNowMs + virtualElapsedMs);
183+
assertRpcOk(await daemon.callCommand('longpress', positionals, selection));
184+
} finally {
185+
dateSpy.mockRestore();
186+
await daemon.close();
187+
}
188+
189+
assertLongPressLedgerPhaseCoverage(ledger);
190+
191+
const envelopeMs = resolveCommandRequestTimeoutMs(resolveCommandTimeoutPolicy('longpress'), {
192+
positionals,
193+
flags: {},
194+
});
195+
assert.ok(envelopeMs !== undefined, 'longpress must declare a bounded envelope');
196+
assert.ok(
197+
virtualElapsedMs + REQUIRED_DAEMON_RESULT_MARGIN_MS <= envelopeMs,
198+
`longpress ledger worst case (${virtualElapsedMs}ms) + ${REQUIRED_DAEMON_RESULT_MARGIN_MS}ms ` +
199+
`margin exceeds the ${envelopeMs}ms envelope.\nLedger:\n${JSON.stringify(ledger, null, 2)}`,
200+
);
201+
}, 20_000);

0 commit comments

Comments
 (0)