feat: expose daemon embedding and Android ADB APIs

Author: thymikee

README.md

@@ -94,13 +94,16 @@ Snapshots assign refs like `@e1`, `@e2`, and `@e3` to current-screen elements. R
 
 `agent-device` runs session-aware commands through platform backends: XCTest for iOS and tvOS, ADB plus the Android snapshot helper for Android, a local helper for macOS desktop automation, and AT-SPI for Linux desktop targets. See [Introduction](https://incubator.callstack.com/agent-device/docs/introduction) and [Commands](https://incubator.callstack.com/agent-device/docs/commands) for platform details.
 
+Node consumers can use the typed client and public subpaths for bridge integrations. `agent-device/android-adb` exposes the Android ADB provider contract and reusable helpers for ADB-backed app listing and foreground state. `agent-device/daemon` exposes the supported daemon embedding surface for integrations that intentionally reuse the upstream request router.
+
 ## Used By
 
 Used by teams and developers at Callstack, Expensify, Shopify, Kindred, Total Wine & More, LegendList, HerLyfe, App & Flow, and more.
 
 ## Documentation
 
 - [Installation](https://incubator.callstack.com/agent-device/docs/installation)
+- [Typed Client](https://incubator.callstack.com/agent-device/docs/client-api)
 - [Commands](https://incubator.callstack.com/agent-device/docs/commands)
 - [Replay & E2E](https://incubator.callstack.com/agent-device/docs/replay-e2e)
 - [Known limitations](https://incubator.callstack.com/agent-device/docs/known-limitations)

package.json

@@ -57,6 +57,10 @@
       "import": "./dist/src/android-snapshot-helper.js",
       "types": "./dist/src/android-snapshot-helper.d.ts"
     },
+    "./daemon": {
+      "import": "./dist/src/daemon-embedding.js",
+      "types": "./dist/src/daemon-embedding.d.ts"
+    },
     "./contracts": {
       "import": "./dist/src/contracts.js",
       "types": "./dist/src/contracts.d.ts"

rslib.config.ts

@@ -26,6 +26,7 @@ export default defineConfig({
           'android-apps': 'src/android-apps.ts',
           'android-adb': 'src/android-adb.ts',
           'android-snapshot-helper': 'src/android-snapshot-helper.ts',
+          'daemon-embedding': 'src/daemon-embedding.ts',
           contracts: 'src/contracts.ts',
           selectors: 'src/selectors.ts',
           finders: 'src/finders.ts',

src/android-adb.ts

@@ -9,3 +9,12 @@ export {
   type AndroidAdbProvider,
   type AndroidAdbSpawner,
 } from './platforms/android/adb-executor.ts';
+export {
+  getAndroidAppStateWithAdb,
+  listAndroidAppsWithAdb,
+} from './platforms/android/app-helpers.ts';
+export type {
+  AndroidAppListFilter,
+  AndroidAppListOptions,
+  AndroidAppListTarget,
+} from './platforms/android/app-helpers.ts';

src/core/__tests__/dispatch-resolve.test.ts

@@ -18,6 +18,7 @@ vi.mock('../../platforms/ios/devices.ts', async (importOriginal) => {
 import {
   resolveIosDevice,
   resolveTargetDevice,
+  withDeviceInventoryProvider,
   withResolveTargetDeviceCacheScope,
 } from '../dispatch-resolve.ts';
 import type { DeviceInfo } from '../../utils/device.ts';
@@ -173,3 +174,28 @@ test('resolveTargetDevice reuses cache across nested request scopes', async () =
 
   assert.equal(mockListAppleDevices.mock.calls.length, 1);
 });
+
+test('resolveTargetDevice uses injected device inventory without local discovery', async () => {
+  const result = await withDeviceInventoryProvider(
+    async (request) => {
+      assert.equal(request.platform, 'ios');
+      assert.equal(request.deviceName, 'Remote iPhone');
+      return [{ ...bootedSimulator, id: 'remote-ios-1', name: 'Remote iPhone' }];
+    },
+    async () => await resolveTargetDevice({ platform: 'ios', device: 'Remote iPhone' }),
+  );
+
+  assert.equal(result.id, 'remote-ios-1');
+  assert.equal(mockListAppleDevices.mock.calls.length, 0);
+});
+
+test('resolveTargetDevice treats empty injected inventory as authoritative', async () => {
+  const err = await withDeviceInventoryProvider(
+    async () => [],
+    async () => await resolveTargetDevice({ platform: 'ios' }),
+  ).catch((error) => error);
+
+  assert.ok(err instanceof AppError);
+  assert.equal(err.code, 'DEVICE_NOT_FOUND');
+  assert.equal(mockListAppleDevices.mock.calls.length, 0);
+});

src/core/dispatch-resolve.ts

@@ -30,6 +30,21 @@ type ResolveDeviceFlags = Pick<
 >;
 
 const resolveTargetDeviceCacheScope = new AsyncLocalStorage<Map<string, DeviceInfo>>();
+const deviceInventoryProviderScope = new AsyncLocalStorage<DeviceInventoryProvider>();
+
+export type DeviceInventoryRequest = {
+  platform?: PlatformSelector;
+  target?: DeviceTarget;
+  deviceName?: string;
+  udid?: string;
+  serial?: string;
+  iosSimulatorSetPath?: string;
+  androidSerialAllowlist?: string[];
+};
+
+export type DeviceInventoryProvider = (
+  request: DeviceInventoryRequest,
+) => Promise<DeviceInfo[] | null | undefined>;
 
 type AppleDeviceSelector = {
   platform?: Exclude<PlatformSelector, 'android'>;
@@ -134,6 +149,20 @@ export async function resolveTargetDevice(flags: ResolveDeviceFlags): Promise<De
         );
       }
 
+      const injectedDevices = await readInjectedDeviceInventory({
+        ...selector,
+        iosSimulatorSetPath,
+        androidSerialAllowlist: androidSerialAllowlist
+          ? Array.from(androidSerialAllowlist).sort()
+          : undefined,
+      });
+      if (injectedDevices) {
+        return cacheResolvedTargetDevice(
+          cacheKey,
+          await resolveDevice(injectedDevices, selector, { simulatorSetPath: iosSimulatorSetPath }),
+        );
+      }
+
       if (selector.platform === 'linux') {
         const devices = await listLinuxDevices();
         return cacheResolvedTargetDevice(cacheKey, await resolveDevice(devices, selector));
@@ -181,6 +210,34 @@ export async function withResolveTargetDeviceCacheScope<T>(task: () => Promise<T
   return await resolveTargetDeviceCacheScope.run(new Map(), task);
 }
 
+export async function withDeviceInventoryProvider<T>(
+  provider: DeviceInventoryProvider | undefined,
+  task: () => Promise<T>,
+): Promise<T> {
+  if (!provider) return await task();
+  return await deviceInventoryProviderScope.run(provider, task);
+}
+
+export async function withTargetDeviceResolutionScope<T>(
+  provider: DeviceInventoryProvider | undefined,
+  task: () => Promise<T>,
+): Promise<T> {
+  return await withDeviceInventoryProvider(
+    provider,
+    async () => await withResolveTargetDeviceCacheScope(task),
+  );
+}
+
+async function readInjectedDeviceInventory(
+  request: DeviceInventoryRequest,
+): Promise<DeviceInfo[] | null> {
+  const provider = deviceInventoryProviderScope.getStore();
+  if (!provider) return null;
+  const devices = await provider(request);
+  if (devices === undefined || devices === null) return null;
+  return devices.map((device) => ({ ...device }));
+}
+
 function readResolveTargetDeviceCache(cacheKey: string): DeviceInfo | undefined {
   const cache = resolveTargetDeviceCacheScope.getStore();
   const cached = cache?.get(cacheKey);

src/core/dispatch.ts

@@ -39,7 +39,13 @@ import {
 import { readNotificationPayload } from './dispatch-payload.ts';
 import { parseDeviceRotation } from './device-rotation.ts';
 
-export { resolveTargetDevice, withResolveTargetDeviceCacheScope } from './dispatch-resolve.ts';
+export {
+  resolveTargetDevice,
+  withDeviceInventoryProvider,
+  withResolveTargetDeviceCacheScope,
+  withTargetDeviceResolutionScope,
+} from './dispatch-resolve.ts';
+export type { DeviceInventoryProvider, DeviceInventoryRequest } from './dispatch-resolve.ts';
 export { shouldUseIosTapSeries, shouldUseIosDragSeries };
 
 export type BatchStep = {

src/daemon-embedding.ts

@@ -0,0 +1,38 @@
+export { createRequestHandler } from './daemon/request-router.ts';
+export type { RequestRouterDeps } from './daemon/request-router.ts';
+export { withDeviceInventoryProvider } from './core/dispatch.ts';
+export type { DeviceInventoryProvider, DeviceInventoryRequest } from './core/dispatch.ts';
+export { SessionStore } from './daemon/session-store.ts';
+export { LeaseRegistry } from './daemon/lease-registry.ts';
+export type {
+  AdmissionRequest,
+  AllocateLeaseRequest,
+  HeartbeatLeaseRequest,
+  LeaseRegistryOptions,
+  ReleaseLeaseRequest,
+  SimulatorLease,
+} from './daemon/lease-registry.ts';
+export {
+  cleanupDownloadableArtifact,
+  cleanupUploadedArtifact,
+  prepareDownloadableArtifact,
+  prepareUploadedArtifact,
+  trackDownloadableArtifact,
+  trackUploadedArtifact,
+} from './daemon/artifact-tracking.ts';
+export type {
+  DaemonArtifact,
+  DaemonInstallSource,
+  DaemonRequest,
+  DaemonResponse,
+  DaemonResponseData,
+  SessionRuntimeHints,
+  SessionState,
+} from './daemon/types.ts';
+export type { DeviceInfo, Platform, PlatformSelector } from './utils/device.ts';
+export type {
+  AndroidAdbExecutor,
+  AndroidAdbExecutorOptions,
+  AndroidAdbExecutorResult,
+  AndroidAdbProvider,
+} from './android-adb.ts';

src/daemon/request-router.ts

@@ -1,5 +1,4 @@
 import path from 'node:path';
-import type { CommandFlags } from '../core/dispatch.ts';
 import {
   withAndroidAdbProvider,
   type AndroidAdbExecutor,
@@ -8,7 +7,9 @@ import {
 import {
   dispatchCommand,
   resolveTargetDevice,
-  withResolveTargetDeviceCacheScope,
+  type CommandFlags,
+  type DeviceInventoryProvider,
+  withTargetDeviceResolutionScope,
 } from '../core/dispatch.ts';
 import { isCommandSupportedOnDevice } from '../core/capabilities.ts';
 import { AppError, normalizeError, toAppErrorCode } from '../utils/errors.ts';
@@ -603,6 +604,7 @@ export type RequestRouterDeps = {
   sessionStore: SessionStore;
   leaseRegistry: LeaseRegistry;
   androidAdbProvider?: AndroidAdbProviderResolver;
+  deviceInventoryProvider?: DeviceInventoryProvider;
   trackDownloadableArtifact: (opts: {
     artifactPath: string;
     tenantId?: string;
@@ -619,6 +621,7 @@ export function createRequestHandler(
     sessionStore,
     leaseRegistry,
     androidAdbProvider,
+    deviceInventoryProvider,
     trackDownloadableArtifact,
   } = deps;
 
@@ -639,7 +642,7 @@ export function createRequestHandler(
         }
 
         try {
-          return await withResolveTargetDeviceCacheScope(async () => {
+          return await withTargetDeviceResolutionScope(deviceInventoryProvider, async () => {
             const scopedReq = scopeRequestSession(req);
             emitDiagnostic({
               level: 'info',

src/platforms/android/__tests__/app-helpers.test.ts

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'vitest';
+import type { AndroidAdbExecutor } from '../adb-executor.ts';
+import { createDeviceAdbExecutor } from '../adb-executor.ts';
+import { getAndroidAppStateWithAdb, listAndroidAppsWithAdb } from '../app-helpers.ts';
+
+async function withMockedAdbScript(script: string, run: () => Promise<void>): Promise<void> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-android-app-helpers-'));
+  const adbPath = path.join(tmpDir, 'adb');
+  await fs.writeFile(adbPath, script, 'utf8');
+  await fs.chmod(adbPath, 0o755);
+
+  const previousPath = process.env.PATH;
+  process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+  try {
+    await run();
+  } finally {
+    process.env.PATH = previousPath;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+test('listAndroidAppsWithAdb uses an injected executor', async () => {
+  const calls: string[][] = [];
+  const adb: AndroidAdbExecutor = async (args) => {
+    calls.push(args);
+    if (args.includes('query-activities')) {
+      return {
+        exitCode: 0,
+        stdout: 'com.example.alpha/.MainActivity\ncom.example.beta/.MainActivity\n',
+        stderr: '',
+      };
+    }
+    return {
+      exitCode: 0,
+      stdout: 'package:com.example.beta\n',
+      stderr: '',
+    };
+  };
+
+  const apps = await listAndroidAppsWithAdb(adb, { filter: 'user-installed', target: 'mobile' });
+
+  assert.deepEqual(apps, [{ package: 'com.example.beta', name: 'Beta' }]);
+  assert.deepEqual(calls, [
+    [
+      'shell',
+      'cmd',
+      'package',
+      'query-activities',
+      '--brief',
+      '-a',
+      'android.intent.action.MAIN',
+      '-c',
+      'android.intent.category.LAUNCHER',
+    ],
+    ['shell', 'pm', 'list', 'packages', '-3'],
+  ]);
+});
+
+test('Android app helpers work with a local ADB provider', async () => {
+  await withMockedAdbScript(
+    [
+      '#!/bin/sh',
+      'if [ "$1" = "-s" ]; then',
+      '  shift',
+      '  shift',
+      'fi',
+      'if [ "$1" = "shell" ] && [ "$3" = "window" ]; then',
+      '  echo "mCurrentFocus=Window{42 u0 com.example.app/.MainActivity}"',
+      '  exit 0',
+      'fi',
+      'if [ "$1" = "shell" ] && [ "$3" = "package" ]; then',
+      '  echo "com.example.app/.MainActivity"',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    async () => {
+      const adb = createDeviceAdbExecutor({
+        platform: 'android',
+        id: 'emulator-5554',
+        name: 'Pixel',
+        kind: 'emulator',
+        booted: true,
+      });
+
+      const [apps, state] = await Promise.all([
+        listAndroidAppsWithAdb(adb, { target: 'mobile' }),
+        getAndroidAppStateWithAdb(adb),
+      ]);
+
+      assert.deepEqual(apps, [{ package: 'com.example.app', name: 'Example' }]);
+      assert.deepEqual(state, { package: 'com.example.app', activity: '.MainActivity' });
+    },
+  );
+});