feat: expose daemon embedding and Android ADB APIs

Author: thymikee

.fallowrc.json

@@ -17,6 +17,7 @@
     "src/bin.ts",
     "src/companion-tunnel.ts",
     "src/daemon.ts",
+    "src/daemon-embedding.ts",
     "src/utils/update-check-entry.ts",
     "test/scripts/metro-prepare-packaged-smoke.mjs",
     "test/integration/*.test.ts",

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)

fallow-baselines/dupes.json

@@ -103,7 +103,7 @@
     "src/client.ts:632-658|src/index.ts:79-105",
     "src/commands/admin.ts:306-313|src/commands/apps.ts:286-295",
     "src/commands/capture-snapshot.ts:104-110|src/commands/selector-read-shared.ts:42-47",
-    "src/commands/interactions.ts:207-215|src/core/dispatch.ts:875-883",
+    "src/commands/interactions.ts:207-215|src/core/dispatch.ts:876-884",
     "src/commands/selector-read.ts:169-178|src/commands/selector-read.ts:403-410",
     "src/contracts.ts:422-427|src/contracts.ts:457-462",
     "src/core/__tests__/dispatch-open.test.ts:17-25|src/core/__tests__/dispatch-push.test.ts:12-20",
@@ -625,4 +625,4 @@
     "test/integration/smoke-open-remote-config.test.ts:146-170|test/scripts/metro-prepare-packaged-smoke.mjs:200-214",
     "test/scripts/metro-prepare-packaged-smoke.mjs:217-226|test/scripts/metro-prepare-packaged-smoke.mjs:245-254"
   ]
-}
+}

fallow-baselines/health.json

@@ -217,6 +217,9 @@
     "src/core/dispatch-resolve.ts": {
       "crap_high": {
         "count": 1
+      },
+      "crap_moderate": {
+        "count": 1
       }
     },
     "src/core/dispatch.ts": {
@@ -1080,4 +1083,4 @@
     "src/daemon/screenshot-overlay.ts:untested risk",
     "src/utils/screenshot-diff-non-text.ts:complexity"
   ]
-}
+}

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/daemon-embedding.ts

@@ -0,0 +1,38 @@
+export { createRequestHandler } from './daemon/request-router.ts';
+export type { AndroidAdbProviderResolver, RequestRouterDeps } from './daemon/request-router.ts';
+export { withDeviceInventoryProvider } from './core/dispatch-resolve.ts';
+export type { DeviceInventoryProvider, DeviceInventoryRequest } from './core/dispatch-resolve.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';