refactor(runtime): construct the Android runtime module with its adb host binding

The Android runtime now calls adb from inside its package for listApps and
appState, which needs the process-wide adb host port bound. That dependency
was hidden in a registry wrapper doing a side-effect import, with a paragraph
explaining why it and loadAndroidMechanics did not subsume each other and an
import-order test pinning the ordering. The package now declares the
dependency: createAndroidRuntimeModule({ bindAdbHost }) awaits the binding
before the runtime loads, and the composition root supplies the one binding
implementation (evaluating its adb host module). The wrapper, the paragraph
and the import-order test are gone; the routed listApps test stays and a
routed appState test joins it.

Author: thymikee

packages/platform-android/src/index.ts

@@ -48,13 +48,27 @@ export async function readAndroidAppStateWithExecutor(
   return await read(run, signal);
 }
 
-export const runtimeModule = Object.freeze({
-  ...metadata,
-  loadRuntime: async (host) => {
-    const { createAndroidPlatformRuntime } = await import('./runtime.ts');
-    return createAndroidPlatformRuntime(host);
-  },
-} satisfies PlatformRuntimeModule);
+/** What the composition root supplies before this package's runtime can reach a device. */
+export type AndroidRuntimeModuleDependencies = Readonly<{
+  /**
+   * Binds the process-wide adb host port (`bindAndroidAdbHost`) the runtime's mechanics run
+   * through. Awaited before the runtime loads, so no caller has to import anything first.
+   */
+  bindAdbHost(): Promise<void>;
+}>;
+
+export function createAndroidRuntimeModule(
+  dependencies: AndroidRuntimeModuleDependencies,
+): PlatformRuntimeModule {
+  return Object.freeze({
+    ...metadata,
+    loadRuntime: async (host) => {
+      await dependencies.bindAdbHost();
+      const { createAndroidPlatformRuntime } = await import('./runtime.ts');
+      return createAndroidPlatformRuntime(host);
+    },
+  } satisfies PlatformRuntimeModule);
+}
 
 export function createAndroidInventoryModule(
   config: AndroidInventoryConfig,

packages/platform-android/src/runtime-facade.test.ts

@@ -7,11 +7,36 @@ vi.mock('./logs/runtime.ts', async (loadOriginal) => {
   return await loadOriginal();
 });
 
-import { runtimeModule } from './index.ts';
+import { createAndroidRuntimeModule } from './index.ts';
 
 test('defers Android app-log mechanics until runtime load', async () => {
+  const runtimeModule = createAndroidRuntimeModule({ bindAdbHost: async () => {} });
   expect(mechanics.evaluations).toBe(0);
   expect(runtimeModule.family).toBe('android');
   await runtimeModule.loadRuntime({} as never);
   expect(mechanics.evaluations).toBe(1);
 });
+
+test('binds the adb host it was constructed with before the runtime loads', async () => {
+  const order: string[] = [];
+  const bindAdbHost = vi.fn(async () => {
+    order.push('bind-adb-host');
+  });
+  const runtimeModule = createAndroidRuntimeModule({ bindAdbHost });
+
+  expect(bindAdbHost).not.toHaveBeenCalled();
+  await runtimeModule.loadRuntime({} as never);
+  order.push('runtime-loaded');
+
+  expect(order).toEqual(['bind-adb-host', 'runtime-loaded']);
+});
+
+test('a binding that fails keeps the runtime unloaded', async () => {
+  const runtimeModule = createAndroidRuntimeModule({
+    bindAdbHost: async () => {
+      throw new Error('adb host unavailable');
+    },
+  });
+
+  await expect(runtimeModule.loadRuntime({} as never)).rejects.toThrow('adb host unavailable');
+});

src/platform-runtime-android-adb-binding.test.ts

@@ -1,6 +1,5 @@
-import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import { afterEach, expect, test, vi } from 'vitest';
+import { expect, test, vi } from 'vitest';
 
 const adb = vi.hoisted(() => ({ calls: [] as string[][] }));
 
@@ -11,9 +10,17 @@ vi.mock('@agent-device/host-kit/command', async (importOriginal) => {
     whichCmd: async (executable: string) => `/usr/bin/${executable}`,
     runCmd: async (cmd: string, args: string[]) => {
       adb.calls.push([cmd, ...args]);
-      return args.includes('query-activities')
-        ? { stdout: 'com.example.app/.MainActivity\n', stderr: '', exitCode: 0 }
-        : { stdout: '', stderr: '', exitCode: 0 };
+      if (args.includes('query-activities')) {
+        return { stdout: 'com.example.app/.MainActivity\n', stderr: '', exitCode: 0 };
+      }
+      if (args.includes('dumpsys')) {
+        return {
+          stdout: 'mCurrentFocus=Window{1 u0 com.example.app/.MainActivity}\n',
+          stderr: '',
+          exitCode: 0,
+        };
+      }
+      return { stdout: '', stderr: '', exitCode: 0 };
     },
   };
 });
@@ -28,6 +35,12 @@ const sessionArtifacts = {
   }),
 };
 
+const scope = {
+  signal: new AbortController().signal,
+  diagnostics: { emit: () => {} },
+  progress: { report: () => {} },
+};
+
 const device: DeviceInfo = {
   platform: 'android',
   id: 'emulator-5554',
@@ -39,15 +52,7 @@ const device: DeviceInfo = {
 
 test('the composed gateway lists Android apps from inside the platform package', async () => {
   const gateway = createPlatformRuntimeGateway(sessionArtifacts);
-  const binding = await gateway.bind({
-    device,
-    intent: { kind: 'ordinary' },
-    scope: {
-      signal: new AbortController().signal,
-      diagnostics: { emit: () => {} },
-      progress: { report: () => {} },
-    },
-  });
+  const binding = await gateway.bind({ device, intent: { kind: 'ordinary' }, scope });
 
   await expect(binding.operations.listApps?.({ device, filter: 'all' })).resolves.toEqual([
     { id: 'com.example.app', name: 'Example' },
@@ -70,37 +75,23 @@ test('the composed gateway lists Android apps from inside the platform package',
   await gateway.shutdown();
 });
 
-afterEach(() => {
-  vi.doUnmock('./platform-runtime-android-adb-host.ts');
-  vi.doUnmock('@agent-device/platform-android');
-  vi.resetModules();
-});
+test('the composed gateway reads Android app state from inside the platform package', async () => {
+  const gateway = createPlatformRuntimeGateway(sessionArtifacts);
+  const binding = await gateway.bind({ device, intent: { kind: 'ordinary' }, scope });
 
-test('the root binds the adb host before it loads the Android runtime module', async () => {
-  const order: string[] = [];
-  vi.resetModules();
-  vi.doMock('./platform-runtime-android-adb-host.ts', () => {
-    order.push('adb-host');
-    return {};
-  });
-  vi.doMock('@agent-device/platform-android', async (importOriginal) => {
-    const original = await importOriginal<typeof import('@agent-device/platform-android')>();
-    return {
-      ...original,
-      runtimeModule: Object.freeze({
-        ...original.runtimeModule,
-        loadRuntime: async (host: PlatformRuntimeHost) => {
-          order.push('android-runtime');
-          return await original.runtimeModule.loadRuntime(host);
-        },
-      }),
-    };
+  await expect(binding.operations.appState?.()).resolves.toEqual({
+    package: 'com.example.app',
+    activity: '.MainActivity',
   });
+  expect(adb.calls).toContainEqual([
+    'adb',
+    '-s',
+    device.id,
+    'shell',
+    'dumpsys',
+    'window',
+    'windows',
+  ]);
 
-  const { createPlatformRuntimeGateway: create } = await import('./platform-runtime.ts');
-  const gateway = create(sessionArtifacts);
-  await gateway.inspectFacts(device).catch(() => {});
-
-  expect(order).toEqual(['adb-host', 'android-runtime']);
   await gateway.shutdown();
 });

src/platform-runtime.ts

@@ -28,9 +28,9 @@ import {
 import {
   createAndroidObservationAdapter as createPackageAndroidObservationAdapter,
   createAndroidInventoryModule,
+  createAndroidRuntimeModule,
   readAndroidAppStateWithExecutor,
   loadShutdownRuntime as loadAndroidShutdownRuntime,
-  runtimeModule as androidRuntimeModule,
 } from '@agent-device/platform-android';
 import {
   createHarmonyInventoryModule,
@@ -114,17 +114,10 @@ export function createPlatformDeviceInventoryGateways(
   });
 }
 
-/**
- * Android mechanics call adb through a process-wide host that only this root can bind. Root binds it
- * from two places: this registry entry, which covers everything the Android runtime reaches from
- * inside its own package, and `loadAndroidMechanics`, which covers the root host ports that call
- * into mechanics without ever binding a runtime. Neither one subsumes the other.
- */
-const androidRuntimeModuleWithBoundAdbHost: PlatformRuntimeModule = Object.freeze({
-  ...androidRuntimeModule,
-  loadRuntime: async (host) => {
+const androidRuntimeModule = createAndroidRuntimeModule({
+  // Evaluating the root's adb host module binds the process-wide port exactly once.
+  bindAdbHost: async () => {
     await import('./platform-runtime-android-adb-host.ts');
-    return await androidRuntimeModule.loadRuntime(host);
   },
 });
 
@@ -134,7 +127,7 @@ export const platformRuntimeModules: ReadonlyMap<Platform, PlatformRuntimeModule
   PlatformRuntimeModule
 >([
   ['apple', appleRuntimeModule],
-  ['android', androidRuntimeModuleWithBoundAdbHost],
+  ['android', androidRuntimeModule],
   ['harmonyos', harmonyosRuntimeModule],
   ['vega', vegaRuntimeModule],
   ['linux', linuxRuntimeModule],