Skip to content

Commit 467e134

Browse files
committed
feat(android): detect Fire OS devices as Android TV targets and document Fire TV support
Fire TV devices running Fire OS are Android-based and automate over ADB, but TV detection only read the AOSP leanback/television features and app launch used the LEANBACK_LAUNCHER category alone. Fire OS devices declare amazon.hardware.fire_tv and may declare no leanback feature, and Fire OS apps can register under either launcher category. - Inventory: treat amazon.hardware.fire_tv as a TV feature signal. - App launch and listing on a TV target: query LEANBACK_LAUNCHER first, fall back to LAUNCHER, and launch the resolved component under the category it resolved under. - Docs and versioned help: Fire TV (Fire OS) connects as an Android TV device; Vega OS remains VVD-only and is a different OS; Electron/Chromium macOS apps automate through the accessibility tree.
1 parent b08b5e7 commit 467e134

18 files changed

Lines changed: 277 additions & 71 deletions

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717

1818
<!-- Intro rule: category line, job pitch with the platform list, works-with/proof lines, nothing else. Per-platform transports, tool names, vendor lists, and support caveats belong in "How it works" and website/docs, never here. Every name in the proof lines must link to public evidence. -->
1919

20-
Let your coding agent verify its changes in the running app. `agent-device` lets agents inspect, control, debug, and verify apps on iOS, Android, and HarmonyOS (simulators, emulators, and physical devices), plus tvOS, Android TV, Amazon Vega OS TV (Vega Virtual Device), web, macOS, and Linux. Agents read token-efficient accessibility snapshots instead of reasoning over screenshots alone, act through refs and selectors, and save evidence for review. It also coordinates device access across parallel agent worktrees and connects to remote device clouds.
20+
Let your coding agent verify its changes in the running app. `agent-device` lets agents inspect, control, debug, and verify apps on iOS, Android, and HarmonyOS (simulators, emulators, and physical devices), plus tvOS, Android TV, Fire TV (Fire OS), Amazon Vega OS TV (Vega Virtual Device), web, macOS, and Linux. Agents read token-efficient accessibility snapshots instead of reasoning over screenshots alone, act through refs and selectors, and save evidence for review. It also coordinates device access across parallel agent worktrees and connects to remote device clouds.
2121

2222
Works with Claude Code, Codex, Cursor, Windsurf, Cline, Goose, and any agent that can run a CLI or connect over MCP, or as the runtime under agents you build with the [AI SDK](https://oss.callstack.com/agent-device/docs/ai-sdk) or [Eve](https://oss.callstack.com/agent-device/docs/eve). Developers at [Expensify](https://www.callstack.com/blog/how-expensify-uses-agent-device-for-mobile-bug-evidence-and-profiling), [Shopify](https://x.com/mustafa01ali/status/2036577353178943826), and [others](#who-uses-agent-device) use it to verify their apps.
2323

@@ -155,7 +155,7 @@ The same session and evidence model works at every step: the agent explores the
155155

156156
## How it works
157157

158-
`agent-device` keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android; HDC and ArkUI `uitest` on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS; and AT-SPI on Linux.
158+
`agent-device` keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android, Android TV, and Fire OS; HDC and ArkUI `uitest` on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS; and AT-SPI on Linux.
159159

160160
Support depth varies by target. Some backends, such as HarmonyOS and Vega OS, cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports.
161161

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,32 @@ async function withMockedAdbScript(script: string, run: () => Promise<void>): Pr
2424
}
2525
}
2626

27+
test('listAndroidAppsWithAdb queries both launcher categories for a TV target', async () => {
28+
// Fire OS apps register under either launcher category, so a TV listing merges both queries.
29+
const calls: (readonly string[])[] = [];
30+
const adb: AndroidAdbExecutor = async (args) => {
31+
calls.push(args);
32+
if (args.includes('query-activities')) {
33+
return {
34+
exitCode: 0,
35+
stdout: args.includes('android.intent.category.LAUNCHER')
36+
? 'com.example.fireosapp/.MainActivity\n'
37+
: '',
38+
stderr: '',
39+
};
40+
}
41+
return { exitCode: 0, stdout: '', stderr: '' };
42+
};
43+
44+
const apps = await listAndroidAppsWithAdb(adb, { filter: 'all', target: 'tv' });
45+
46+
assert.deepEqual(apps, [{ package: 'com.example.fireosapp', name: 'Fireosapp' }]);
47+
assert.deepEqual(calls.map((call) => call.at(-1)).sort(), [
48+
'android.intent.category.LAUNCHER',
49+
'android.intent.category.LEANBACK_LAUNCHER',
50+
]);
51+
});
52+
2753
test('listAndroidAppsWithAdb uses an injected executor', async () => {
2854
const calls: (readonly string[])[] = [];
2955
const adb: AndroidAdbExecutor = async (args) => {

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

Lines changed: 117 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { test } from 'vitest';
22
import assert from 'node:assert/strict';
3-
import { openAndroidApp } from '../app-lifecycle.ts';
3+
import { listAndroidApps, openAndroidApp } from '../app-lifecycle.ts';
44
import { withAndroidAdbProvider } from '../adb-executor.ts';
55
import type { DeviceInfo } from '@agent-device/kernel/device';
66
import { AppError } from '@agent-device/kernel/errors';
@@ -755,6 +755,122 @@ test('openAndroidApp fallback resolve-activity includes MAIN/LAUNCHER flags', as
755755
);
756756
});
757757

758+
test('openAndroidApp TV fallback carries the resolved LAUNCHER category into the component launch', async () => {
759+
// A Fire OS app that declares no LEANBACK_LAUNCHER activity resolves under LAUNCHER only; the
760+
// fallback launch must carry that category, not the target's LEANBACK_LAUNCHER.
761+
await withFakeAdb(
762+
(args) => {
763+
if (args[0] === 'shell' && args[1] === 'am' && args[2] === 'start') {
764+
if (args.includes('-p')) {
765+
return [
766+
'Starting: Intent { act=android.intent.action.MAIN cat=[android.intent.category.DEFAULT,android.intent.category.LEANBACK_LAUNCHER] pkg=com.example.tvapp }',
767+
'Error: Activity not started, unable to resolve Intent { act=android.intent.action.MAIN cat=[android.intent.category.DEFAULT,android.intent.category.LEANBACK_LAUNCHER] flg=0x10000000 pkg=com.example.tvapp }',
768+
].join('\n');
769+
}
770+
return 'Status: ok';
771+
}
772+
if (
773+
args[0] === 'shell' &&
774+
args[1] === 'cmd' &&
775+
args[2] === 'package' &&
776+
args[3] === 'resolve-activity'
777+
) {
778+
if (args.includes('android.intent.category.LEANBACK_LAUNCHER')) {
779+
return { stdout: '', stderr: 'No activity found', exitCode: 1 };
780+
}
781+
return 'com.example.tvapp/com.example.tvapp.MainActivity';
782+
}
783+
return undefined;
784+
},
785+
async ({ calls, device }) => {
786+
await openAndroidApp(device, 'com.example.tvapp');
787+
assert.deepEqual(calls, [
788+
[
789+
'shell',
790+
'am',
791+
'start',
792+
'-W',
793+
'-a',
794+
'android.intent.action.MAIN',
795+
'-c',
796+
'android.intent.category.DEFAULT',
797+
'-c',
798+
'android.intent.category.LEANBACK_LAUNCHER',
799+
'-p',
800+
'com.example.tvapp',
801+
],
802+
// resolve-activity tries LEANBACK_LAUNCHER first on a TV target...
803+
[
804+
'shell',
805+
'cmd',
806+
'package',
807+
'resolve-activity',
808+
'--brief',
809+
'-a',
810+
'android.intent.action.MAIN',
811+
'-c',
812+
'android.intent.category.LEANBACK_LAUNCHER',
813+
'com.example.tvapp',
814+
],
815+
// ...then LAUNCHER, which resolves the component.
816+
[
817+
'shell',
818+
'cmd',
819+
'package',
820+
'resolve-activity',
821+
'--brief',
822+
'-a',
823+
'android.intent.action.MAIN',
824+
'-c',
825+
'android.intent.category.LAUNCHER',
826+
'com.example.tvapp',
827+
],
828+
// The fallback launch uses the category the component resolved under.
829+
[
830+
'shell',
831+
'am',
832+
'start',
833+
'-W',
834+
'-a',
835+
'android.intent.action.MAIN',
836+
'-c',
837+
'android.intent.category.DEFAULT',
838+
'-c',
839+
'android.intent.category.LAUNCHER',
840+
'-n',
841+
'com.example.tvapp/com.example.tvapp.MainActivity',
842+
],
843+
]);
844+
},
845+
{ device: { ...ANDROID_EMULATOR, target: 'tv' } },
846+
);
847+
});
848+
849+
test('listAndroidApps on a TV target queries LEANBACK_LAUNCHER then LAUNCHER', async () => {
850+
await withFakeAdb(
851+
(args) => {
852+
if (args.includes('query-activities')) {
853+
return args.includes('android.intent.category.LAUNCHER')
854+
? 'com.example.fireosapp/.MainActivity\n'
855+
: '';
856+
}
857+
return undefined;
858+
},
859+
async ({ calls, device }) => {
860+
const apps = await listAndroidApps(device, 'all');
861+
assert.deepEqual(apps, [{ package: 'com.example.fireosapp', name: 'Fireosapp' }]);
862+
const queriedCategories = calls
863+
.filter((call) => call.includes('query-activities'))
864+
.map((call) => call.at(-1));
865+
assert.deepEqual(queriedCategories, [
866+
'android.intent.category.LEANBACK_LAUNCHER',
867+
'android.intent.category.LAUNCHER',
868+
]);
869+
},
870+
{ device: { ...ANDROID_EMULATOR, target: 'tv' } },
871+
);
872+
});
873+
758874
// In-process replacement for the old PATH-stub default adb script: any
759875
// `am start` succeeds with the "Status: ok" marker (so the primary launch
760876
// never falls back to resolve-activity), everything else is empty success.

‎packages/platform-android/src/app-helpers.ts‎

Lines changed: 9 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,7 @@ import {
55
parseAndroidUserInstalledPackages,
66
} from './app-parsers.ts';
77
import { inferAndroidAppName } from './app-deployment-resolution.ts';
8-
9-
const ANDROID_LAUNCHER_CATEGORY = 'android.intent.category.LAUNCHER';
10-
const ANDROID_LEANBACK_CATEGORY = 'android.intent.category.LEANBACK_LAUNCHER';
8+
import { androidLauncherCategories } from './launcher-categories.ts';
119

1210
export type AndroidAppListFilter = AppsFilter;
1311
export type AndroidAppListTarget = 'mobile' | 'tv' | 'auto';
@@ -38,28 +36,19 @@ async function listAndroidLaunchablePackagesWithAdb(
3836
): Promise<Set<string>> {
3937
const discoveredPackages = (
4038
await Promise.all(
41-
resolveAndroidLaunchCategoriesForAdb(target).map(async (category) => {
42-
const result = await runAdbShell(adb, buildAndroidQueryActivitiesArgs(category), {
43-
allowFailure: true,
44-
});
45-
return result.exitCode === 0 ? parseAndroidLaunchablePackageOutput(result.stdout) : [];
46-
}),
39+
androidLauncherCategories(target, { includeFallbackCategories: true }).map(
40+
async (category) => {
41+
const result = await runAdbShell(adb, buildAndroidQueryActivitiesArgs(category), {
42+
allowFailure: true,
43+
});
44+
return result.exitCode === 0 ? parseAndroidLaunchablePackageOutput(result.stdout) : [];
45+
},
46+
),
4747
)
4848
).flat();
4949
return new Set(discoveredPackages);
5050
}
5151

52-
function resolveAndroidLaunchCategoriesForAdb(target: AndroidAppListTarget): string[] {
53-
switch (target) {
54-
case 'mobile':
55-
return [ANDROID_LAUNCHER_CATEGORY];
56-
case 'tv':
57-
return [ANDROID_LEANBACK_CATEGORY];
58-
default:
59-
return [ANDROID_LAUNCHER_CATEGORY, ANDROID_LEANBACK_CATEGORY];
60-
}
61-
}
62-
6352
function buildAndroidQueryActivitiesArgs(category: string): string[] {
6453
return [
6554
'cmd',

‎packages/platform-android/src/app-lifecycle.ts‎

Lines changed: 18 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,9 @@ import {
2323
parseAndroidLaunchablePackages,
2424
parseAndroidUserInstalledPackages,
2525
} from './app-parsers.ts';
26+
import { androidLaunchCategory, androidLauncherCategories } from './launcher-categories.ts';
2627
import { getAndroidAppState, getAndroidResumedActivity } from './window-state.ts';
2728

28-
const ANDROID_LAUNCHER_CATEGORY = 'android.intent.category.LAUNCHER';
29-
const ANDROID_LEANBACK_CATEGORY = 'android.intent.category.LEANBACK_LAUNCHER';
3029
const ANDROID_DEFAULT_CATEGORY = 'android.intent.category.DEFAULT';
3130
const ANDROID_LOCALHOST_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
3231
/** Owns localhost URL reverses, so a teardown that removes only owned mappings removes them too. */
@@ -53,8 +52,8 @@ export async function listAndroidApps(
5352

5453
async function listAndroidLaunchablePackages(device: DeviceInfo): Promise<Set<string>> {
5554
const packages = new Set<string>();
56-
for (const category of resolveAndroidLaunchCategories(device, {
57-
includeFallbackWhenUnknown: true,
55+
for (const category of androidLauncherCategories(device.target, {
56+
includeFallbackCategories: true,
5857
})) {
5958
const result = await runAndroidShell(
6059
device,
@@ -80,26 +79,6 @@ async function listAndroidLaunchablePackages(device: DeviceInfo): Promise<Set<st
8079
return packages;
8180
}
8281

83-
function resolveAndroidLauncherCategory(device: DeviceInfo): string {
84-
return resolveAndroidLaunchCategories(device)[0] ?? ANDROID_LAUNCHER_CATEGORY;
85-
}
86-
87-
function resolveAndroidLaunchCategories(
88-
device: DeviceInfo,
89-
options: { includeFallbackWhenUnknown?: boolean } = {},
90-
): string[] {
91-
if (device.target === 'tv') {
92-
return [ANDROID_LEANBACK_CATEGORY];
93-
}
94-
if (device.target === 'mobile') {
95-
return [ANDROID_LAUNCHER_CATEGORY];
96-
}
97-
if (options.includeFallbackWhenUnknown) {
98-
return [ANDROID_LAUNCHER_CATEGORY, ANDROID_LEANBACK_CATEGORY];
99-
}
100-
return [ANDROID_LAUNCHER_CATEGORY];
101-
}
102-
10382
async function listAndroidUserInstalledPackages(device: DeviceInfo): Promise<string[]> {
10483
const result = await runAndroidShell(device, ['pm', 'list', 'packages', '-3']);
10584
return parseAndroidUserInstalledPackages(result.stdout);
@@ -225,7 +204,7 @@ async function startAndroidApp(
225204
const helperLaunch = await tryAndroidHelperLaunch(device, app, options);
226205
if (helperLaunch) return helperLaunch;
227206
const resolved = await resolveAndroidApp(device, app);
228-
const launchCategory = resolveAndroidLauncherCategory(device);
207+
const launchCategory = androidLaunchCategory(device.target);
229208
if (resolved.type === 'intent') {
230209
return await openAndroidIntent(device, resolved.value, options);
231210
}
@@ -405,16 +384,22 @@ async function openAndroidPackage(
405384
if (primaryResult.exitCode === 0 && !isAmStartError(primaryResult.stdout, primaryResult.stderr)) {
406385
return primaryResult;
407386
}
408-
const component = await resolveAndroidLaunchComponent(device, packageName);
409-
if (!component) {
387+
const resolvedComponent = await resolveAndroidLaunchComponent(device, packageName);
388+
if (!resolvedComponent) {
410389
if (!(await isAndroidPackageInstalled(device, packageName))) {
411390
throw buildAndroidPackageNotInstalledError(packageName);
412391
}
413392
throw androidAdbResultError(`Failed to launch ${packageName}`, primaryResult);
414393
}
394+
// The fallback launches under the category the component actually resolved under, which on a TV
395+
// target can be LAUNCHER for an app that declares no LEANBACK_LAUNCHER activity.
415396
return await runAndroidShell(
416397
device,
417-
buildAndroidActivityLaunchArgs(component, launchCategory, options),
398+
buildAndroidActivityLaunchArgs(
399+
resolvedComponent.component,
400+
resolvedComponent.category,
401+
options,
402+
),
418403
);
419404
}
420405

@@ -516,10 +501,10 @@ function looksLikeMissingAndroidPackageOutput(output: string): boolean {
516501
async function resolveAndroidLaunchComponent(
517502
device: DeviceInfo,
518503
packageName: string,
519-
): Promise<string | null> {
520-
const categories = Array.from(
521-
new Set(resolveAndroidLaunchCategories(device, { includeFallbackWhenUnknown: true })),
522-
);
504+
): Promise<{ component: string; category: string } | null> {
505+
const categories = androidLauncherCategories(device.target, {
506+
includeFallbackCategories: true,
507+
});
523508
for (const category of categories) {
524509
const result = await runAndroidShell(
525510
device,
@@ -540,7 +525,7 @@ async function resolveAndroidLaunchComponent(
540525
continue;
541526
}
542527
const component = parseAndroidLaunchComponent(result.stdout);
543-
if (component) return component;
528+
if (component) return { component, category };
544529
}
545530
return null;
546531
}

‎packages/platform-android/src/inventory.test.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,7 @@ test.each([
145145
test.each([
146146
['feature:android.software.leanback_only\nfeature:android.hardware.wifi\n', 'tv'],
147147
['feature:android.hardware.type.television=1\n', 'tv'],
148+
['feature:android.hardware.wifi\nfeature:amazon.hardware.fire_tv\n', 'tv'],
148149
['feature:android.software.leanback_extra\nfeature:android.hardware.wifi\n', 'mobile'],
149150
] as const)(
150151
'Android inventory reads the feature list %j as a %s target',
@@ -168,6 +169,36 @@ test.each([
168169
},
169170
);
170171

172+
test('Android inventory classifies a device by has-feature amazon.hardware.fire_tv before the feature list', async () => {
173+
// The characteristics probe says nothing, no AOSP leanback/television feature answers, and
174+
// only the Amazon Fire TV feature answers true: the device must be a tv target from the
175+
// has-feature probe, without the pm list features fallback deciding it.
176+
const featureListProbeCalls: string[] = [];
177+
const host = createHost(async (request) => {
178+
const key = request.args.join('\0');
179+
if (key === 'devices\0-l')
180+
return result('List of devices attached\nAFTKMST12 device model:AFTKMST12\n');
181+
if (key.includes('pm\0list\0features')) {
182+
featureListProbeCalls.push(key);
183+
return result('feature:android.hardware.wifi\n');
184+
}
185+
if (key.includes('has-feature')) {
186+
return result(key.includes('amazon.hardware.fire_tv') ? 'true\n' : 'false\n');
187+
}
188+
const probe = RUNNING_EMULATOR_PROBES.find(([fragment]) => key.includes(fragment));
189+
if (probe) return result(probe[1]);
190+
throw new Error(`Unexpected command: ${request.executable} ${request.args.join(' ')}`);
191+
});
192+
193+
const [device] = await createAndroidInventory(host).discover(
194+
{ androidAvdSelection: 'running-only' },
195+
scope,
196+
);
197+
198+
assert.equal(device?.target, 'tv');
199+
assert.deepEqual(featureListProbeCalls, []);
200+
});
201+
171202
test('Android inventory fails closed when adb is unavailable', async () => {
172203
const host = createHost(async () => result(''), { adb: undefined });
173204
await assert.rejects(

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,14 @@ const DEVICE_DESCRIPTION_TIMEOUT_MS = 2_000;
2929
const DEVICE_DESCRIPTION_PROBE = shellFragment(
3030
'getprop ro.product.model; getprop ro.build.version.release',
3131
);
32+
// Fire OS devices declare amazon.hardware.fire_tv and may not declare the AOSP leanback
33+
// features, so TV detection must read it as a TV signal too (Amazon: "Identify Fire TV
34+
// Devices", adb shell pm list features).
3235
const TV_FEATURES = [
3336
'android.software.leanback',
3437
'android.software.leanback_only',
3538
'android.hardware.type.television',
39+
'amazon.hardware.fire_tv',
3640
] as const;
3741

3842
type AndroidInventoryContext = Readonly<{

0 commit comments

Comments
 (0)