refactor(runtime): let platform runtimes list apps and read app state directly (#2295)

* refactor(runtime): let platform runtimes list apps and read app state directly

The root host carried two adapters, appInventory and appState, that only
forwarded a platform call back into that platform's own package. Each platform
runtime now performs its own listApps and appState call through a lazy import
inside its package, keeping the deferred load, the AbortSignal threading, and
the package/bundleId -> id rename. PlatformRuntimeHost loses both keys, so
Android, Apple and Harmony fixtures no longer stub the two platforms they do
not own.

Android is the one platform runtime whose package now reaches adb directly.
The adb host that adb mechanics require is bound by a module side effect that
only the root can perform, so the Android runtime-module registration binds it
before the module loads. loadAndroidMechanics keeps its own binding import for
the root host ports that reach mechanics without binding a runtime; neither
binder subsumes the other.

Android appstate now runs one foreground-focus loop instead of two. The host
shaped readAndroidAppState/AndroidAppStateHost pair is gone: limrun's adapter
already closes over its own adb executor, so it calls the executor variant
directly, and that variant took the per-attempt abort check the host variant
had. AppStateRuntimeCommand and AppStateRuntimeCommandResult described the
deleted host port and go with it.

Tests: the new ordering test in
src/platform-runtime-android-adb-binding.test.ts was seen red by deleting the
binding import from that registration (order came back
["android-runtime", "adb-host"]); the composed-gateway listApps test in the
same file was seen red by reverting the Android runtime's inlined listApps to a
host.appInventory lookup (TypeError reading 'android'); the new abort test in
packages/platform-android/src/app-state.test.ts was seen red by removing both
signal?.throwIfAborted() calls from readAndroidFocusWithExecutor (the second
dumpsys was issued and the call resolved). All green after.

* chore(gates): drop the retired app-inventory/app-state host allowances

The two PLATFORM_RUNTIME_HOST_FILES rows point at host files this change
deletes, and the ./platform-runtime-app-state-host.ts composition allowance has
no importer left.

* 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/contracts/src/app-inventory-runtime.ts

@@ -14,27 +14,3 @@ export type ListAppsInput = Readonly<{
 export type AppInventoryRuntimeOperations = Readonly<{
   listApps(input: ListAppsInput): Promise<readonly InstalledAppInfo[]>;
 }>;
-
-export type AppInventoryRuntimeHost = Readonly<{
-  apple: Readonly<{
-    listApps(
-      device: DeviceInfo,
-      filter: AppsFilter,
-      signal: AbortSignal,
-    ): Promise<readonly InstalledAppInfo[]>;
-  }>;
-  android: Readonly<{
-    listApps(
-      device: DeviceInfo,
-      filter: AppsFilter,
-      signal: AbortSignal,
-    ): Promise<readonly InstalledAppInfo[]>;
-  }>;
-  harmonyos: Readonly<{
-    listApps(
-      device: DeviceInfo,
-      filter: AppsFilter,
-      signal: AbortSignal,
-    ): Promise<readonly InstalledAppInfo[]>;
-  }>;
-}>;

packages/contracts/src/app-state-runtime.ts

@@ -1,38 +1,9 @@
-import type { DeviceInfo } from '@agent-device/kernel/device';
-
 /** Neutral foreground identity returned by a selected platform/provider runtime. */
 export type AppStateRuntimeResult = Readonly<{
   package?: string;
   activity?: string;
 }>;
 
-export type AppStateRuntimeCommand = Readonly<{
-  args: readonly string[];
-  allowFailure?: boolean;
-  timeoutMs?: number;
-}>;
-
-export type AppStateRuntimeCommandResult = Readonly<{
-  stdout: string;
-}>;
-
 export type AppStateRuntimeOperations = Readonly<{
   appState(): Promise<AppStateRuntimeResult>;
 }>;
-
-export type AppStateRuntimeHost = Readonly<{
-  android: Readonly<{
-    run(
-      device: DeviceInfo,
-      command: AppStateRuntimeCommand,
-      signal: AbortSignal,
-    ): Promise<AppStateRuntimeCommandResult>;
-  }>;
-  harmonyos: Readonly<{
-    run(
-      device: DeviceInfo,
-      command: AppStateRuntimeCommand,
-      signal: AbortSignal,
-    ): Promise<AppStateRuntimeCommandResult>;
-  }>;
-}>;

packages/contracts/src/platform-runtime-operations.ts

@@ -1,14 +1,11 @@
 import type { AppLogRuntimeHost, AppLogRuntimeOperations } from './app-log-runtime.ts';
-import type {
-  AppInventoryRuntimeHost,
-  AppInventoryRuntimeOperations,
-} from './app-inventory-runtime.ts';
+import type { AppInventoryRuntimeOperations } from './app-inventory-runtime.ts';
 import type {
   AndroidAppDeploymentExecutor,
   AppDeploymentRuntimeOperations,
   AppleAppDeploymentExecutor,
 } from './app-deployment-runtime.ts';
-import type { AppStateRuntimeHost, AppStateRuntimeOperations } from './app-state-runtime.ts';
+import type { AppStateRuntimeOperations } from './app-state-runtime.ts';
 import type { NetworkRuntimeHost, NetworkRuntimeOperations } from './network-runtime.ts';
 import type { ScreenRecordingRuntimeHost } from './screen-recording-runtime-host.ts';
 import type { ScreenRecordingRuntimeOperations } from './screen-recording-runtime.ts';
@@ -721,8 +718,6 @@ export const keyboardRuntimePlanUses = Object.freeze([
 export type PlatformRuntimeHost = AppLogRuntimeHost &
   NetworkRuntimeHost &
   Readonly<{
-    appInventory: AppInventoryRuntimeHost;
-    appState: AppStateRuntimeHost;
     /** Focused native ports; deployment semantics remain in the owning family packages. */
     appleDeployment: AppleAppDeploymentExecutor;
     androidDeployment: AndroidAppDeploymentExecutor;

packages/platform-android/src/app-state.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from 'vitest';
-import { parseAndroidForegroundApp } from './app-state.ts';
+import { parseAndroidForegroundApp, readAndroidAppStateWithExecutor } from './app-state.ts';
 
 test('parses Android window and activity foreground markers', () => {
   expect(
@@ -28,3 +28,18 @@ test('scans repeated uncontrolled focus text without regular-expression backtrac
     parseAndroidForegroundApp(`ResumedActivity:${'ResumedActivity:a'.repeat(20_000)}`),
   ).toBeNull();
 });
+
+test('stops between dumpsys attempts once the request is aborted', async () => {
+  const controller = new AbortController();
+  const issued: string[][] = [];
+  const run = async (args: string[]) => {
+    issued.push(args);
+    controller.abort(new Error('request canceled'));
+    return { exitCode: 0, stdout: 'mCurrentFocus=Window{1 u0 StatusBar}', stderr: '' };
+  };
+
+  await expect(readAndroidAppStateWithExecutor(run, controller.signal)).rejects.toThrow(
+    'request canceled',
+  );
+  expect(issued).toEqual([['shell', 'dumpsys', 'window', 'windows']]);
+});

packages/platform-android/src/app-state.ts

@@ -1,19 +1,6 @@
-import type {
-  AppStateRuntimeCommand,
-  AppStateRuntimeCommandResult,
-  AppStateRuntimeResult,
-} from '@agent-device/contracts/app-state-runtime';
-import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { AppStateRuntimeResult } from '@agent-device/contracts/app-state-runtime';
 import { parseAndroidFocusSegment } from './app-parsers.ts';
 
-export type AndroidAppStateHost = Readonly<{
-  run(
-    device: DeviceInfo,
-    command: AppStateRuntimeCommand,
-    signal: AbortSignal,
-  ): Promise<AppStateRuntimeCommandResult>;
-}>;
-
 const FOCUS_COMMANDS = [
   ['shell', 'dumpsys', 'window', 'windows'],
   ['shell', 'dumpsys', 'window'],
@@ -29,60 +16,35 @@ export type AndroidCommandExecutor = (
 
 export async function readAndroidAppStateWithExecutor(
   run: AndroidCommandExecutor,
+  signal?: AbortSignal,
 ): Promise<AppStateRuntimeResult> {
-  const windowFocus = await readAndroidFocusWithExecutor(run, FOCUS_COMMANDS);
+  const windowFocus = await readAndroidFocusWithExecutor(run, FOCUS_COMMANDS, signal);
   if (windowFocus) return windowFocus;
 
-  const activityFocus = await readAndroidFocusWithExecutor(run, ACTIVITY_COMMANDS);
+  const activityFocus = await readAndroidFocusWithExecutor(run, ACTIVITY_COMMANDS, signal);
   if (activityFocus) return activityFocus;
   return {};
 }
 
 async function readAndroidFocusWithExecutor(
   run: AndroidCommandExecutor,
   commands: readonly (readonly string[])[],
+  signal?: AbortSignal,
 ): Promise<AppStateRuntimeResult | null> {
   for (const args of commands) {
+    signal?.throwIfAborted();
     const result = await run([...args], { allowFailure: true });
+    signal?.throwIfAborted();
     const parsed = parseAndroidForegroundApp(result.stdout ?? '');
     if (parsed) return parsed;
   }
   return null;
 }
 
-export async function readAndroidAppState(
-  host: AndroidAppStateHost,
-  device: DeviceInfo,
-  signal: AbortSignal,
-): Promise<AppStateRuntimeResult> {
-  const windowFocus = await readAndroidFocus(host, device, FOCUS_COMMANDS, signal);
-  if (windowFocus) return windowFocus;
-
-  const activityFocus = await readAndroidFocus(host, device, ACTIVITY_COMMANDS, signal);
-  if (activityFocus) return activityFocus;
-  return {};
-}
-
 export function parseAndroidForegroundApp(text: string): AppStateRuntimeResult | null {
   return parseAndroidFocusSegment(text, (segment) => parseAndroidComponentFromSegment(segment));
 }
 
-async function readAndroidFocus(
-  host: AndroidAppStateHost,
-  device: DeviceInfo,
-  commands: readonly (readonly string[])[],
-  signal: AbortSignal,
-): Promise<AppStateRuntimeResult | null> {
-  for (const args of commands) {
-    signal.throwIfAborted();
-    const result = await host.run(device, { args, allowFailure: true }, signal);
-    signal.throwIfAborted();
-    const parsed = parseAndroidForegroundApp(result.stdout);
-    if (parsed) return parsed;
-  }
-  return null;
-}
-
 function parseAndroidComponentFromSegment(segment: string): AppStateRuntimeResult | null {
   const match = segment.match(/\b([A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+)\/([A-Za-z0-9_.$]+)/);
   return match?.[1] && match[2] ? { package: match[1], activity: match[2] } : null;

packages/platform-android/src/index.ts

@@ -1,16 +1,11 @@
-import type {
-  AppStateRuntimeHost,
-  AppStateRuntimeResult,
-} from '@agent-device/contracts/app-state-runtime';
+import type { AppStateRuntimeResult } from '@agent-device/contracts/app-state-runtime';
 import type {
   InventoryPlatformModule,
   PlatformModuleMetadata,
 } from '@agent-device/contracts/platform-module';
 import type { PlatformRuntimeModule } from '@agent-device/contracts/platform-runtime-operations';
 import type { DeviceShutdownRuntimeDependencies } from '@agent-device/contracts/device-shutdown-runtime';
-import type { DeviceInfo } from '@agent-device/kernel/device';
 import type { AndroidInventoryConfig } from './inventory-config.ts';
-import type { AndroidAppStateHost } from './app-state.ts';
 import type {
   AndroidObservationAdapter,
   AndroidObservationHost,
@@ -21,7 +16,6 @@ const metadata = Object.freeze({
 } satisfies PlatformModuleMetadata);
 
 export type { AndroidInventoryConfig } from './inventory-config.ts';
-export type { AndroidAppStateHost } from './app-state.ts';
 
 /** Package-owned Android observation policy, loaded only when a daemon request needs it. */
 export function createAndroidObservationAdapter(
@@ -46,29 +40,35 @@ export function createAndroidObservationAdapter(
   });
 }
 
-export async function readAndroidAppState(
-  host: AndroidAppStateHost | AppStateRuntimeHost['android'],
-  device: DeviceInfo,
-  signal: AbortSignal,
-): Promise<AppStateRuntimeResult> {
-  const { readAndroidAppState: read } = await import('./app-state.ts');
-  return await read(host, device, signal);
-}
-
 export async function readAndroidAppStateWithExecutor(
   run: import('./app-state.ts').AndroidCommandExecutor,
-): Promise<import('@agent-device/contracts/app-state-runtime').AppStateRuntimeResult> {
+  signal?: AbortSignal,
+): Promise<AppStateRuntimeResult> {
   const { readAndroidAppStateWithExecutor: read } = await import('./app-state.ts');
-  return await read(run);
+  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/mechanics.ts

@@ -72,7 +72,6 @@ export async function listAndroidAppsWithAdb(
 export {
   closeAndroidApp,
   isAmStartError,
-  listAndroidApps,
   openAndroidApp,
   openAndroidDevice,
   parseAndroidLaunchComponent,

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

@@ -150,11 +150,6 @@ function host(options: {
       readProcessMarker: async () => options.marker,
     },
     networkTransports: { resolve: async () => ({ mode: 'local' }) },
-    appInventory: {
-      apple: { listApps: async () => [] },
-      android: { listApps: async () => [] },
-      harmonyos: { listApps: async () => [] },
-    },
   };
 }
 
@@ -192,16 +187,7 @@ function unusedAppLogHost(): Omit<
       terminate: async () => 'already-missing',
     },
     processTransports: { resolve: async () => ({ mode: 'local' }) },
-    appInventory: {
-      apple: { listApps: async () => [] },
-      android: { listApps: async () => [] },
-      harmonyos: { listApps: async () => [] },
-    },
     clock: { now: () => 1, sleep: async () => {} },
-    appState: {
-      android: { run: async () => ({ stdout: '' }) },
-      harmonyos: { run: async () => ({ stdout: '' }) },
-    },
     deviceReadiness: {
       applePhysical: { ensureConnected: async () => {} },
       appleAutomation: {

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');
+});

packages/platform-android/src/runtime.fixtures.ts

@@ -39,17 +39,6 @@ const audioProbeHost: PlatformRuntimeHost['audioProbe'] = {
   ownedProcesses: { replace: () => {}, clear: () => {} },
 };
 
-export const emptyAppInventory = {
-  apple: { listApps: async () => [] },
-  android: { listApps: async () => [] },
-  harmonyos: { listApps: async () => [] },
-};
-
-const emptyAppState = {
-  android: { run: async () => ({ stdout: '' }) },
-  harmonyos: { run: async () => ({ stdout: '' }) },
-};
-
 function localAndroidScreenRecording() {
   return {
     mode: 'local' as const,
@@ -72,7 +61,6 @@ export function androidRuntimeHost(overrides: Record<string, unknown> = {}): Pla
   return {
     androidTools: { probeClipboardShellSupport: async () => 'supported' as const },
     processTransports: { resolve: async () => ({ mode: 'local' as const }) },
-    appInventory: emptyAppInventory,
     localInteractors: { resolve: async () => ({}) },
     audioProbe: audioProbeHost,
     screenRecording: { android: { resolve: async () => localAndroidScreenRecording() } },
@@ -89,7 +77,6 @@ export function androidNavigationHost(
       probeClipboardShellSupport,
       runAdb: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
     },
-    appState: emptyAppState,
     deviceReadiness: { android: { ensureReady: async (selected: DeviceInfo) => selected } },
   });
 }