Skip to content

Commit 6eb8195

Browse files
committed
fix(android): name the OEM install dialog on helper install timeouts
The first install of each helper package on some OEM builds (ColorOS) opens the system install-confirmation flow and adb blocks until it is dismissed, so an unattended first snapshot failed with the generic "adb server may be wedged" advice. Route both helper installs through one seam that rewrites that generic hint, keep the timeout classification and install-failure marker, and carry the IME helper's curated advice into its activation diagnostic.
1 parent 23fd3c9 commit 6eb8195

15 files changed

Lines changed: 428 additions & 16 deletions

‎packages/host-kit/src/internal/exec.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -597,7 +597,7 @@ function createTimeoutError(
597597
* its own `timeoutMs`. Callers classify with this rather than matching the message text,
598598
* so a command whose own output says "timed out" is not mistaken for one exec killed.
599599
*/
600-
export function isCommandTimeoutError(error: unknown): boolean {
600+
export function isCommandTimeoutError(error: unknown): error is AppError {
601601
return (
602602
error instanceof AppError &&
603603
error.code === 'COMMAND_FAILED' &&

‎packages/platform-android/src/__tests__/app-deployment.test.ts‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';
33
import { promises as fs } from 'node:fs';
44
import os from 'node:os';
55
import path from 'node:path';
6+
import { AppError } from '@agent-device/kernel/errors';
67
import { installAndroidInstallablePath } from '../app-deployment.ts';
78
import {
89
inferAndroidAppName,
@@ -80,6 +81,51 @@ test('installAndroidInstallablePath uses provider install capability when availa
8081
assert.deepEqual(installCalls, [{ source: apkPath, replace: true }]);
8182
});
8283

84+
test('an app install timeout keeps the generic adb-server advice', async () => {
85+
// The OEM install dialog can hold an app install too, but the helper-specific advice names an
86+
// agent-device helper package, so it must not leak onto the app-under-test install path.
87+
const apkPath = path.join(os.tmpdir(), `agent-device-app-install-timeout-${Date.now()}.apk`);
88+
await fs.writeFile(apkPath, 'placeholder', 'utf8');
89+
const device: DeviceInfo = {
90+
platform: 'android',
91+
id: 'emulator-5554',
92+
name: 'Pixel',
93+
kind: 'emulator',
94+
booted: true,
95+
};
96+
97+
try {
98+
await withAndroidAdbProvider(
99+
{
100+
exec: async (args) => {
101+
throw new Error(`unexpected adb exec: ${args.join(' ')}`);
102+
},
103+
install: async () => {
104+
throw new AppError('COMMAND_FAILED', 'adb timed out after 30000ms', {
105+
stdout: '',
106+
stderr: '',
107+
exitCode: 1,
108+
timeoutMs: 30_000,
109+
});
110+
},
111+
},
112+
{ serial: 'emulator-5554' },
113+
async () =>
114+
await assert.rejects(
115+
() => installAndroidInstallablePath(device, apkPath),
116+
(error) => {
117+
const details = (error as AppError).details;
118+
assert.equal(details?.adbFailure, 'timeout');
119+
assert.match(String(details?.hint), /wedged/);
120+
return true;
121+
},
122+
),
123+
);
124+
} finally {
125+
await fs.rm(apkPath, { force: true });
126+
}
127+
});
128+
83129
test('installAndroidInstallablePath installs .aab via bundletool build-apks + install-apks', async () => {
84130
const tmpDir = await mkdtempForTest('agent-device-android-install-aab-');
85131
const bundletoolPath = path.join(tmpDir, 'bundletool');

‎packages/platform-android/src/__tests__/ime-helper.test.ts‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { promises as fs } from 'node:fs';
44
import path from 'node:path';
55
import { beforeEach, test } from 'vitest';
66
import './test-utils/android-host-test-setup.ts';
7+
import { AppError } from '@agent-device/kernel/errors';
78
import {
89
ensureAndroidImeHelper,
910
resetAndroidImeHelperInstallCache,
@@ -146,6 +147,48 @@ test('ensureAndroidImeHelper skips install when a newer version is already prese
146147
assert.equal(result.reason, 'current');
147148
});
148149

150+
test('ensureAndroidImeHelper install timeout points at the OEM install dialog', async () => {
151+
const tmpDir = await mkdtempForTest('ime-helper-install-timeout-');
152+
const apkPath = path.join(tmpDir, 'helper.apk');
153+
await fs.writeFile(apkPath, 'helper-apk');
154+
const adb: AndroidAdbExecutor = async (args) => {
155+
if (args.includes('--show-versioncode')) {
156+
return { exitCode: 1, stdout: '', stderr: 'not found' };
157+
}
158+
throw new Error(`unexpected adb call: ${args.join(' ')}`);
159+
};
160+
const adbProvider: AndroidAdbProvider = {
161+
exec: adb,
162+
install: async () => {
163+
// An unattended first install blocks on the OEM install-confirmation dialog until
164+
// adb gives up, leaving no output behind.
165+
throw new AppError('COMMAND_FAILED', 'adb timed out after 30000ms', {
166+
stdout: '',
167+
stderr: '',
168+
exitCode: 1,
169+
timeoutMs: 30_000,
170+
});
171+
},
172+
};
173+
174+
await assert.rejects(
175+
() =>
176+
ensureAndroidImeHelper({
177+
adb,
178+
adbProvider,
179+
artifact: { apkPath, manifest: { ...manifest, sha256: sha256Text('helper-apk') } },
180+
deviceKey: 'android:R52N30PZXBT',
181+
}),
182+
(error) => {
183+
const details = (error as AppError).details;
184+
assert.equal(details?.adbFailure, 'timeout');
185+
assert.match(String(details?.hint), /install-confirmation dialog/);
186+
assert.doesNotMatch(String(details?.hint), /wedged/);
187+
return true;
188+
},
189+
);
190+
});
191+
149192
function sha256Text(text: string): string {
150193
return crypto.createHash('sha256').update(text).digest('hex');
151194
}
Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
import assert from 'node:assert/strict';
2+
import crypto from 'node:crypto';
3+
import { promises as fs } from 'node:fs';
4+
import path from 'node:path';
5+
import { beforeEach, test } from 'vitest';
6+
import './test-utils/android-host-test-setup.ts';
7+
import { AppError } from '@agent-device/kernel/errors';
8+
import {
9+
ensureAndroidSnapshotHelper,
10+
resetAndroidSnapshotHelperInstallCache,
11+
} from '../snapshot-helper-install.ts';
12+
import type { AndroidAdbExecutor, AndroidAdbProvider } from '../adb-executor.ts';
13+
import type { AndroidAdbInstaller } from '../adb-transport.ts';
14+
import type { AndroidSnapshotHelperManifest } from '../snapshot-helper-types.ts';
15+
import { mkdtempForTest } from './test-utils/tmp-dir.ts';
16+
17+
const manifest: AndroidSnapshotHelperManifest = {
18+
name: 'android-snapshot-helper',
19+
version: '0.13.3',
20+
apkUrl: null,
21+
sha256: 'a'.repeat(64),
22+
packageName: 'com.callstack.agentdevice.snapshothelper',
23+
versionCode: 13003,
24+
instrumentationRunner: 'com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation',
25+
minSdk: 23,
26+
targetSdk: 36,
27+
outputFormat: 'uiautomator-xml',
28+
statusProtocol: 'android-snapshot-helper-v1',
29+
installArgs: ['install', '-r'],
30+
};
31+
32+
beforeEach(() => {
33+
resetAndroidSnapshotHelperInstallCache();
34+
});
35+
36+
test('a snapshot helper install timeout points at the OEM install dialog', async () => {
37+
const apkPath = await writeHelperApk('snapshot-helper-install-timeout-');
38+
const adbProvider = missingPackageProvider(async () => {
39+
throw adbInstallTimeout();
40+
});
41+
42+
await assert.rejects(
43+
() =>
44+
ensureAndroidSnapshotHelper({
45+
adb: adbProvider.exec,
46+
adbProvider,
47+
artifact: { apkPath, manifest: { ...manifest, sha256: sha256Text('helper-apk') } },
48+
deviceKey: 'android:R52N30PZXBT',
49+
}),
50+
(error) => {
51+
const details = (error as AppError).details;
52+
assert.equal(details?.adbFailure, 'timeout');
53+
assert.equal(details?.androidSnapshotHelperInstallFailure, true);
54+
assert.match(String(details?.hint), /install-confirmation dialog/);
55+
assert.doesNotMatch(String(details?.hint), /wedged/);
56+
return true;
57+
},
58+
);
59+
});
60+
61+
test('an exec-shaped helper install timeout names the dialog, not a wedged adb server', async () => {
62+
// The reporter's shape: a local USB device whose provider has no semantic installer, so the
63+
// install crosses the legacy exec fallback.
64+
const apkPath = await writeHelperApk('snapshot-helper-install-timeout-exec-');
65+
const exec: AndroidAdbExecutor = async (args) => {
66+
if (args.includes('--show-versioncode')) {
67+
return { exitCode: 1, stdout: '', stderr: 'not found' };
68+
}
69+
if (args[0] === 'install') throw adbInstallTimeout();
70+
throw new Error(`unexpected adb call: ${args.join(' ')}`);
71+
};
72+
73+
await assert.rejects(
74+
() =>
75+
ensureAndroidSnapshotHelper({
76+
adb: exec,
77+
adbProvider: exec,
78+
artifact: { apkPath, manifest: { ...manifest, sha256: sha256Text('helper-apk') } },
79+
deviceKey: 'android:R52N30PZXBT',
80+
}),
81+
(error) => {
82+
const details = (error as AppError).details;
83+
assert.equal(details?.adbFailure, 'timeout');
84+
assert.match(String(details?.hint), /install-confirmation dialog/);
85+
return true;
86+
},
87+
);
88+
});
89+
90+
function adbInstallTimeout(): AppError {
91+
// An unattended first install on ColorOS: adb blocks on the system install-confirmation dialog
92+
// and the exec layer kills the command, so stdout/stderr stay empty.
93+
return new AppError('COMMAND_FAILED', 'adb timed out after 30000ms', {
94+
stdout: '',
95+
stderr: '',
96+
exitCode: 1,
97+
timeoutMs: 30_000,
98+
});
99+
}
100+
101+
async function writeHelperApk(prefix: string): Promise<string> {
102+
const tmpDir = await mkdtempForTest(prefix);
103+
const apkPath = path.join(tmpDir, 'helper.apk');
104+
await fs.writeFile(apkPath, 'helper-apk');
105+
return apkPath;
106+
}
107+
108+
function missingPackageProvider(install: AndroidAdbInstaller): AndroidAdbProvider {
109+
return {
110+
exec: async (args) => {
111+
if (args.includes('--show-versioncode')) {
112+
return { exitCode: 1, stdout: '', stderr: 'not found' };
113+
}
114+
throw new Error(`unexpected adb call: ${args.join(' ')}`);
115+
},
116+
install,
117+
};
118+
}
119+
120+
function sha256Text(text: string): string {
121+
return crypto.createHash('sha256').update(text).digest('hex');
122+
}

‎packages/platform-android/src/adb-failure.test.ts‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import {
55
androidAdbResultError,
66
androidDiscoveryCommandError,
77
attachAdbFailureHint,
8+
attachAndroidHelperInstallTimeoutHint,
89
classifyAndroidAdbFailure,
910
} from './adb-failure.ts';
1011
import { bindAndroidAdbHostStub } from './adb-host.fixtures.ts';
@@ -71,6 +72,51 @@ test('attachAdbFailureHint classifies timeouts first and never overwrites a site
7172
assert.equal(attachAdbFailureHint(foreign).details?.adbFailure, undefined);
7273
});
7374

75+
test('attachAndroidHelperInstallTimeoutHint names the OEM install dialog, not a wedged server', () => {
76+
const helperInstallTimeout = attachAndroidHelperInstallTimeoutHint(
77+
attachAdbFailureHint(
78+
new AppError('COMMAND_FAILED', 'adb timed out after 30000ms', {
79+
timeoutMs: 30_000,
80+
stdout: '',
81+
stderr: '',
82+
}),
83+
),
84+
);
85+
assert.equal(helperInstallTimeout.details?.adbFailure, 'timeout');
86+
assert.match(String(helperInstallTimeout.details?.hint), /install-confirmation dialog/);
87+
assert.doesNotMatch(String(helperInstallTimeout.details?.hint), /wedged/);
88+
89+
// The helper hint is scoped to helper installs: any other adb timeout keeps the
90+
// generic advice, because nothing at that call site knows about a package installer.
91+
const shellTimeout = attachAdbFailureHint(
92+
new AppError('COMMAND_FAILED', 'adb timed out after 5000ms', { timeoutMs: 5000 }),
93+
);
94+
assert.match(String(shellTimeout.details?.hint), /wedged/);
95+
96+
// Only a timeout is rewritten: an exit-coded install rejection keeps its own classification,
97+
// and anything that is not a COMMAND_FAILED AppError passes through untouched.
98+
const installRejection = attachAndroidHelperInstallTimeoutHint(
99+
new AppError('COMMAND_FAILED', 'adb install rejected', { stderr: 'device offline' }),
100+
);
101+
assert.equal(installRejection.details?.adbFailure, undefined);
102+
assert.equal(installRejection.details?.hint, undefined);
103+
104+
// A hint curated nearer the failure — a provider's own advice — outranks this heuristic.
105+
const curated = attachAndroidHelperInstallTimeoutHint(
106+
new AppError('COMMAND_FAILED', 'adb timed out after 30000ms', {
107+
timeoutMs: 30_000,
108+
hint: 'the cloud session expired',
109+
}),
110+
);
111+
assert.equal(curated.details?.hint, 'the cloud session expired');
112+
113+
const unsupported = new AppError('UNSUPPORTED_OPERATION', 'helper unavailable', {
114+
timeoutMs: 30_000,
115+
});
116+
assert.equal(attachAndroidHelperInstallTimeoutHint(unsupported), unsupported);
117+
assert.equal(attachAndroidHelperInstallTimeoutHint('adb install failed'), 'adb install failed');
118+
});
119+
74120
test('androidAdbResultError flags process exits but never a semantic exit-0 failure', () => {
75121
bindAndroidAdbHostStub();
76122
const nonzero = androidAdbResultError(

‎packages/platform-android/src/adb-failure.ts‎

Lines changed: 26 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,9 @@ const ANDROID_ADB_TIMEOUT_FAILURE: AndroidAdbFailureClassification = Object.free
117117
hint: 'adb timed out — the adb server may be wedged. Run adb kill-server && adb start-server, check adb devices, then retry.',
118118
});
119119

120+
const ANDROID_HELPER_INSTALL_TIMEOUT_HINT =
121+
'The helper install timed out — some OEM builds (ColorOS is one) hold the first install of each package behind a system install-confirmation dialog and adb waits for it. Check the device screen, confirm any pending install prompt, then retry; if none is showing, run adb kill-server && adb start-server and retry.';
122+
120123
export function classifyAndroidAdbFailure(
121124
stderr: string,
122125
stdout = '',
@@ -132,6 +135,7 @@ export function classifyAndroidAdbFailure(
132135
}
133136

134137
import { AppError } from '@agent-device/kernel/errors';
138+
import { isCommandTimeoutError } from '@agent-device/host-kit/command';
135139
import type { HostCommandResult } from '@agent-device/contracts/platform-runtime-host';
136140
import type { AndroidAdbExecutorResult } from './adb-transport.ts';
137141

@@ -158,6 +162,26 @@ export function attachAdbFailureHint<T>(error: T): T {
158162
return error;
159163
}
160164

165+
/**
166+
* Rewrites the hint on a helper-APK install timeout to name the likelier cause. Some OEM builds
167+
* (ColorOS is one) hold the package installer open on a system install-confirmation dialog for
168+
* the first install of a package; the command yields no stderr, so the generic timeout hint reads
169+
* as a wedged adb server and points away from the only fix. Reach it only through
170+
* `installAndroidHelperPackage`, the Android helper install seam: every other adb timeout keeps
171+
* the generic advice. Only that generic advice is replaced — a hint curated nearer the failure
172+
* (a provider's own advice, or a request cancellation) survives, as elsewhere in this module.
173+
*/
174+
export function attachAndroidHelperInstallTimeoutHint<T>(error: T): T {
175+
if (!isCommandTimeoutError(error)) return error;
176+
const curatedHint = error.details?.hint;
177+
if (typeof curatedHint === 'string' && curatedHint !== ANDROID_ADB_TIMEOUT_FAILURE.hint) {
178+
return error;
179+
}
180+
const classified = attachAdbFailureHint(error);
181+
classified.details = { ...classified.details, hint: ANDROID_HELPER_INSTALL_TIMEOUT_HINT };
182+
return classified;
183+
}
184+
161185
// Timeout wins over text matchers: the exec layer deliberately builds timeout
162186
// errors around "timed out after Nms" because partial output from the killed
163187
// process is untrustworthy — classifying that partial stderr (e.g. flagging a
@@ -231,17 +255,11 @@ export function androidDiscoveryCommandError(
231255
}
232256

233257
export function attachAndroidDiscoveryTimeout<T>(error: T): T {
234-
if (
235-
!(error instanceof AppError) ||
236-
error.code !== 'COMMAND_FAILED' ||
237-
typeof error.details?.timeoutMs !== 'number'
238-
) {
239-
return error;
240-
}
258+
if (!isCommandTimeoutError(error)) return error;
241259
error.details = {
242260
...error.details,
243261
adbFailure: ANDROID_ADB_TIMEOUT_FAILURE.reason,
244-
...(typeof error.details.hint === 'string'
262+
...(typeof error.details?.hint === 'string'
245263
? {}
246264
: {
247265
hint: ANDROID_ADB_TIMEOUT_FAILURE.hint,

‎packages/platform-android/src/adb-transfer.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ type AndroidAdbTransferProviderOptions = {
2020
provider?: AndroidAdbProvider | AndroidAdbExecutor;
2121
};
2222

23+
/** Everything a caller can ask a package install to do: install flags, exec options, and routing. */
24+
export type AndroidAdbPackageInstallOptions = AndroidAdbInstallOptions &
25+
AndroidAdbTransferProviderOptions;
26+
2327
export async function pullAndroidAdbFile(
2428
remotePath: string,
2529
localPath: string,
@@ -45,7 +49,7 @@ export async function pullAndroidAdbFile(
4549

4650
export async function installAndroidAdbPackage(
4751
apkPath: string,
48-
options?: AndroidAdbInstallOptions & AndroidAdbTransferProviderOptions,
52+
options?: AndroidAdbPackageInstallOptions,
4953
): Promise<AndroidAdbExecutorResult> {
5054
const { device, provider, ...installOptions } = options ?? {};
5155
const resolved = resolveAndroidAdbTransferProvider(device, provider);

0 commit comments

Comments
 (0)