refactor: move Android system observation out of daemon (#2071)

Author: thymikee

packages/contracts/package.json

@@ -27,6 +27,10 @@
       "types": "./src/android-input-ownership.ts",
       "default": "./src/android-input-ownership.ts"
     },
+    "./android-observation": {
+      "types": "./src/android-observation.ts",
+      "default": "./src/android-observation.ts"
+    },
     "./android-snapshot-quality": {
       "types": "./src/android-snapshot-quality.ts",
       "default": "./src/android-snapshot-quality.ts"

packages/contracts/src/android-observation.ts

@@ -0,0 +1,50 @@
+import type { AppStateRuntimeResult } from './app-state-runtime.ts';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import type { SnapshotNode } from '@agent-device/kernel/snapshot';
+
+/** Focus facts that are safe to pass between the daemon and an Android owner. */
+export type AndroidBlockingDialogFocus = Readonly<{
+  package?: string;
+  focusedWindow: string;
+  raw: string;
+}>;
+
+/** One observation of Android's focused system-window state. */
+export type AndroidBlockingDialogObservation =
+  | Readonly<{ status: 'dialog'; focus: AndroidBlockingDialogFocus }>
+  | Readonly<{ status: 'clear' }>
+  | Readonly<{ status: 'unknown' }>;
+
+/** The minimal result needed by daemon-owned recovery to classify an adb tap. */
+export type AndroidObservationCommandResult = Readonly<{
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}>;
+
+/** Raw Android mechanics supplied by root composition to the package-owned observer. */
+export type AndroidObservationHost = Readonly<{
+  runAdb(
+    device: DeviceInfo,
+    args: readonly string[],
+    options?: Readonly<{ allowFailure?: boolean }>,
+  ): Promise<AndroidObservationCommandResult>;
+  readSnapshotNodes(device: DeviceInfo): Promise<SnapshotNode[]>;
+  openApp(device: DeviceInfo, appBundleId: string): Promise<void>;
+}>;
+
+/** Root-composed Android observations and narrowly scoped recovery actions. */
+export type AndroidObservationAdapter = Readonly<{
+  readAppState(device: DeviceInfo): Promise<AppStateRuntimeResult>;
+  readBlockingDialog(device: DeviceInfo): Promise<AndroidBlockingDialogObservation>;
+  readAppFocus(
+    device: DeviceInfo,
+    appBundleId: string,
+    options?: Readonly<{ requireNoBlockingDialog?: boolean }>,
+  ): Promise<boolean>;
+  readSnapshotNodes(device: DeviceInfo): Promise<SnapshotNode[]>;
+  tap(device: DeviceInfo, x: number, y: number): Promise<AndroidObservationCommandResult>;
+  openApp(device: DeviceInfo, appBundleId: string): Promise<void>;
+  readScreenSize(device: DeviceInfo): Promise<Readonly<{ width: number; height: number }>>;
+  isPermissionPackage(packageName: string): Promise<boolean>;
+}>;

packages/platform-android/src/index.ts

@@ -11,6 +11,10 @@ import type { DeviceShutdownRuntimeDependencies } from '@agent-device/contracts/
 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,
+} from '@agent-device/contracts/android-observation';
 
 const metadata = Object.freeze({
   family: 'android',
@@ -19,6 +23,29 @@ const metadata = Object.freeze({
 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(
+  host: AndroidObservationHost,
+): AndroidObservationAdapter {
+  let implementation: Promise<AndroidObservationAdapter> | undefined;
+  const load = () => {
+    implementation ??= import('./observation.ts').then(({ createAndroidObservationAdapter }) =>
+      createAndroidObservationAdapter(host),
+    );
+    return implementation;
+  };
+  return Object.freeze({
+    readAppState: async (...args) => await (await load()).readAppState(...args),
+    readBlockingDialog: async (...args) => await (await load()).readBlockingDialog(...args),
+    readAppFocus: async (...args) => await (await load()).readAppFocus(...args),
+    readSnapshotNodes: async (...args) => await (await load()).readSnapshotNodes(...args),
+    tap: async (...args) => await (await load()).tap(...args),
+    openApp: async (...args) => await (await load()).openApp(...args),
+    readScreenSize: async (...args) => await (await load()).readScreenSize(...args),
+    isPermissionPackage: async (...args) => await (await load()).isPermissionPackage(...args),
+  });
+}
+
 export async function readAndroidAppState(
   host: AndroidAppStateHost | AppStateRuntimeHost['android'],
   device: DeviceInfo,

packages/platform-android/src/observation.test.ts

@@ -0,0 +1,100 @@
+import { expect, test, vi } from 'vitest';
+import type { AndroidObservationHost } from '@agent-device/contracts/android-observation';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import { createAndroidObservationAdapter } from './observation.ts';
+
+const device = {
+  platform: 'android',
+  target: 'mobile',
+  id: 'emulator-5554',
+  name: 'Pixel',
+  kind: 'emulator',
+  booted: true,
+} satisfies DeviceInfo;
+
+function hostFor(stdoutByCommand: ReadonlyMap<string, string>): AndroidObservationHost {
+  return {
+    runAdb: vi.fn(async (_device, args) => ({
+      exitCode: 0,
+      stdout: stdoutByCommand.get(args.join(' ')) ?? '',
+      stderr: '',
+    })),
+    readSnapshotNodes: vi.fn(async () => []),
+    openApp: vi.fn(async () => {}),
+  };
+}
+
+test('answers focus and blocking-dialog questions from one observation-bound dump', async () => {
+  const host = hostFor(
+    new Map([
+      ['shell dumpsys window windows', 'mCurrentFocus=Window{1 u0 com.example.app/.MainActivity}'],
+    ]),
+  );
+  const observer = createAndroidObservationAdapter(host);
+
+  await expect(
+    observer.readAppFocus(device, 'com.example.app', { requireNoBlockingDialog: true }),
+  ).resolves.toBe(true);
+  expect(host.runAdb).toHaveBeenCalledTimes(1);
+});
+
+test('classifies an app-owned ANR without exposing dump mechanics to the daemon', async () => {
+  const host = hostFor(
+    new Map([
+      [
+        'shell dumpsys window windows',
+        'mCurrentFocus=Window{1 u0 Application Not Responding: com.example.app}',
+      ],
+    ]),
+  );
+
+  await expect(createAndroidObservationAdapter(host).readBlockingDialog(device)).resolves.toEqual({
+    status: 'dialog',
+    focus: {
+      package: 'com.example.app',
+      focusedWindow: 'Application Not Responding: com.example.app',
+      raw: 'mCurrentFocus=Window{1 u0 Application Not Responding: com.example.app}',
+    },
+  });
+});
+
+test('owns touch rounding and screen-size parsing behind raw host commands', async () => {
+  const host = hostFor(new Map([['shell wm size', 'Physical size: 1080x2400']]));
+  const observer = createAndroidObservationAdapter(host);
+
+  await expect(observer.readScreenSize(device)).resolves.toEqual({ width: 1080, height: 2400 });
+  await observer.tap(device, 12.6, 42.2);
+  expect(host.runAdb).toHaveBeenLastCalledWith(device, ['shell', 'input', 'tap', '13', '42'], {
+    allowFailure: true,
+  });
+});
+
+test('a transient empty dump never demotes a variant that previously answered', async () => {
+  const calls: string[] = [];
+  let primaryReads = 0;
+  const host: AndroidObservationHost = {
+    ...hostFor(new Map()),
+    runAdb: vi.fn(async (_device, args) => {
+      const key = args.join(' ');
+      calls.push(key);
+      if (key === 'shell dumpsys window windows') primaryReads += 1;
+      return {
+        exitCode: 0,
+        stdout:
+          primaryReads === 2 && key === 'shell dumpsys window windows'
+            ? ''
+            : 'mCurrentFocus=Window{1 u0 com.example.app/.MainActivity}',
+        stderr: '',
+      };
+    }),
+  };
+  const observer = createAndroidObservationAdapter(host);
+  const transientDevice = { ...device, id: 'emulator-transient' };
+
+  await observer.readAppState(transientDevice);
+  await observer.readAppState(transientDevice);
+  const thirdReadStart = calls.length;
+  await observer.readAppState(transientDevice);
+
+  expect(calls[thirdReadStart]).toBe('shell dumpsys window windows');
+});