refactor(android): one injectable host-adb transport for the remaining raw adb sites (#2052)

* refactor(android): one injectable host-adb transport

* refactor(android): enforce host-adb transport failure contract

* style(android): format relocated limrun transport test

* refactor(android): colocate host adb transport

* refactor(android): route host adb through composition

* fix(android): keep unbound adb host loud

Author: thymikee

packages/platform-android/src/adb-executor-host.test.ts

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
+import { bindAndroidAdbHostStub } from './adb-host.fixtures.ts';
+import { runAndroidHostAdb, withAndroidHostAdbTransport } from './adb-executor.ts';
+
+test('a scoped transport intercepts host adb without reaching the injected host', async () => {
+  let hostCalls = 0;
+  bindAndroidAdbHostStub({
+    execHostAdb: async () => {
+      hostCalls += 1;
+      return { stdout: 'host', stderr: '', exitCode: 0 };
+    },
+  });
+
+  const result = await withAndroidHostAdbTransport(
+    async (args, options) => {
+      assert.deepEqual(args, ['devices']);
+      assert.deepEqual(options, { timeoutMs: 1_234 });
+      return { stdout: 'transport', stderr: '', exitCode: 0 };
+    },
+    async () => await runAndroidHostAdb(['devices'], { timeoutMs: 1_234 }),
+  );
+
+  assert.equal(result.stdout, 'transport');
+  assert.equal(hostCalls, 0);
+});
+
+test('the local host arm always obtains a result before applying the shared failure contract', async () => {
+  let receivedOptions: Record<string, unknown> | undefined;
+  bindAndroidAdbHostStub({
+    execHostAdb: async (_args, options) => {
+      receivedOptions = options;
+      return { stdout: '', stderr: 'error: device offline', exitCode: 1 };
+    },
+  });
+
+  const error = await runAndroidHostAdb(['devices']).then(
+    () => assert.fail('expected the host adb call to reject'),
+    (cause: unknown) => cause,
+  );
+
+  assert.deepEqual(receivedOptions, { allowFailure: true });
+  assert.ok(error instanceof AppError);
+  assert.equal(error.details?.adbFailure, 'device_offline');
+  assert.equal(error.details?.retriable, true);
+  assert.match(String(error.details?.hint), /adb reconnect/i);
+});
+
+test('allowFailure returns a nonzero local result unchanged', async () => {
+  const scripted = { stdout: '', stderr: 'offline', exitCode: 7 };
+  bindAndroidAdbHostStub({ execHostAdb: async () => scripted });
+
+  assert.deepEqual(
+    await runAndroidHostAdb(['devices'], { allowFailure: true, timeoutMs: 5_000 }),
+    scripted,
+  );
+});
+
+test('unchecked transport results are normalized at the package boundary', async () => {
+  bindAndroidAdbHostStub({
+    coerceAdbResult: (result) => ({
+      ...result,
+      stdout: typeof result.stdout === 'string' ? result.stdout : '',
+      stderr: typeof result.stderr === 'string' ? result.stderr : '',
+      exitCode: Number(result.exitCode),
+    }),
+  });
+  const sloppy = { stdout: undefined, stderr: null, exitCode: '1' } as never;
+
+  const result = await withAndroidHostAdbTransport(
+    async () => sloppy,
+    async () => await runAndroidHostAdb(['devices'], { allowFailure: true }),
+  );
+
+  assert.deepEqual(result, { stdout: '', stderr: '', exitCode: 1 });
+});
+
+test('nested transport scopes are innermost-first and restore on scope exit', async () => {
+  bindAndroidAdbHostStub({
+    execHostAdb: async () => ({ stdout: 'host', stderr: '', exitCode: 0 }),
+  });
+  const transportFor = (name: string) => async () => ({
+    stdout: name,
+    stderr: '',
+    exitCode: 0,
+  });
+
+  await withAndroidHostAdbTransport(transportFor('outer'), async () => {
+    assert.equal((await runAndroidHostAdb(['devices'])).stdout, 'outer');
+    await withAndroidHostAdbTransport(transportFor('inner'), async () => {
+      assert.equal((await runAndroidHostAdb(['devices'])).stdout, 'inner');
+    });
+    assert.equal((await runAndroidHostAdb(['devices'])).stdout, 'outer');
+  });
+  assert.equal((await runAndroidHostAdb(['devices'])).stdout, 'host');
+});

packages/platform-android/src/adb-executor.ts

@@ -10,6 +10,7 @@ export {
   attachAdbFailureHint,
   classifyAndroidAdbFailure as classifyAdbFailure,
 } from './adb-failure.ts';
+export { runAndroidHostAdb, withAndroidHostAdbTransport } from './adb-host.ts';
 export { createAndroidPortReverseManager } from './adb-port-reverse.ts';
 export {
   createDeviceAdbExecutor,

packages/platform-android/src/adb-failure.ts

@@ -134,7 +134,6 @@ export function classifyAndroidAdbFailure(
 import { AppError } from '@agent-device/kernel/errors';
 import type { HostCommandResult } from '@agent-device/contracts/platform-runtime-host';
 import type { AndroidAdbExecutorResult } from './adb-transport.ts';
-import { requireAndroidAdbHost } from './adb-host.ts';
 
 /**
  * Enriches a failed adb command error in place with the classified hint,
@@ -178,12 +177,11 @@ function classifyAdbCommandError(error: AppError): AndroidAdbFailureClassificati
  * Site-provided `details` win on key collisions, and a site `hint` is preserved
  * over the classified one.
  *
- * Nonzero exits build their details via the host's execFailureDetails, whose
- * processExitError flag makes normalizeError append the first stderr line to
- * the curated message — the classified hint and the stderr-excerpt enrichment
- * compose instead of competing. Semantic failures thrown at exit 0 (e.g. an
- * `am start` error printed on a successful exit) stay unflagged so a stray
- * stderr line never decorates a message the process exit does not back up.
+ * Nonzero exits set processExitError so normalizeError appends the first stderr
+ * line to the curated message — the classified hint and stderr-excerpt
+ * enrichment compose instead of competing. Semantic failures thrown at exit 0
+ * (e.g. an `am start` error printed on a successful exit) stay unflagged so a
+ * stray stderr line never decorates a message the process exit does not back up.
  */
 export function androidAdbResultError(
   message: string,
@@ -193,7 +191,13 @@ export function androidAdbResultError(
   const failureDetails =
     result.exitCode === 0
       ? { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, ...details }
-      : requireAndroidAdbHost().execFailureDetails(result, details);
+      : {
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exitCode: result.exitCode,
+          processExitError: true,
+          ...details,
+        };
   return attachAdbFailureHint(new AppError('COMMAND_FAILED', message, failureDetails));
 }
 

packages/platform-android/src/adb-host.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import type {
   AndroidHelperInstallDecision,
   AndroidImeHelperArtifact,
@@ -95,6 +96,14 @@ export type AndroidAdbHost = Readonly<{
 
 let boundHost: AndroidAdbHost | undefined;
 
+/** Scoped override for host-global and explicitly serial-qualified adb argv. */
+export type AndroidAdbHostTransport = (
+  args: string[],
+  options?: AndroidAdbExecutorOptions,
+) => Promise<AndroidAdbExecutorResult>;
+
+const androidAdbHostTransportScope = new AsyncLocalStorage<AndroidAdbHostTransport>();
+
 /** Composition-time wiring; the last bind wins so test harnesses can rebind. */
 export function bindAndroidAdbHost(host: AndroidAdbHost): void {
   boundHost = host;
@@ -110,6 +119,39 @@ export function requireAndroidAdbHost(): AndroidAdbHost {
   return boundHost;
 }
 
+/**
+ * Runs host-level adb through one package-owned failure contract. A scoped
+ * transport wins over the injected local host port; nested scopes are
+ * innermost-first and restore automatically.
+ */
+export async function runAndroidHostAdb(
+  args: string[],
+  options?: AndroidAdbExecutorOptions,
+): Promise<AndroidAdbExecutorResult> {
+  const host = requireAndroidAdbHost();
+  const transport = androidAdbHostTransportScope.getStore();
+  const result = host.coerceAdbResult(
+    transport
+      ? await transport(args, options)
+      : await host.execHostAdb(args, { ...options, allowFailure: true }),
+  );
+  if (!options?.allowFailure && result.exitCode !== 0) {
+    const { androidAdbResultError } = await import('./adb-failure.ts');
+    throw androidAdbResultError(
+      `adb ${args.join(' ')} exited with code ${result.exitCode}`,
+      result,
+    );
+  }
+  return result;
+}
+
+export async function withAndroidHostAdbTransport<T>(
+  transport: AndroidAdbHostTransport,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return await androidAdbHostTransportScope.run(transport, fn);
+}
+
 export function emitAndroidAdbDiagnostic(event: AndroidAdbDiagnosticEvent): void {
   requireAndroidAdbHost().emitDiagnostic(event);
 }

packages/platform-android/src/ime-lifecycle.test.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { bindAndroidAdbHostStub } from './adb-host.fixtures.ts';
+import { withAndroidHostAdbTransport } from './adb-executor.ts';
+import { listAndroidAdbSerialsQuick } from './ime-lifecycle.ts';
+
+test('quick serial listing keeps an unbound adb host port loud', async () => {
+  await assert.rejects(
+    async () => await listAndroidAdbSerialsQuick(),
+    /Android adb host port is not bound/,
+  );
+});
+
+test('quick serial listing routes its global devices call through the scoped transport', async () => {
+  bindAndroidAdbHostStub();
+  const seenArgs: string[][] = [];
+
+  const serials = await withAndroidHostAdbTransport(
+    async (args) => {
+      seenArgs.push([...args]);
+      return {
+        stdout: 'List of devices attached\nemulator-5554\tdevice\n',
+        stderr: '',
+        exitCode: 0,
+      };
+    },
+    async () => await listAndroidAdbSerialsQuick(),
+  );
+
+  assert.deepEqual(serials, ['emulator-5554']);
+  assert.deepEqual(seenArgs, [['devices']]);
+});
+
+test('quick serial listing treats a classified transport failure as empty inventory', async () => {
+  bindAndroidAdbHostStub();
+  const serials = await withAndroidHostAdbTransport(
+    async () => ({ stdout: '', stderr: 'error: device offline', exitCode: 1 }),
+    async () => await listAndroidAdbSerialsQuick(),
+  );
+
+  assert.deepEqual(serials, []);
+});

packages/platform-android/src/ime-lifecycle.ts

@@ -4,7 +4,7 @@
 // `ime-activation.ts` (the activation transaction), and `ime-restore.ts` (restore + startup
 // orphan recovery).
 
-import { requireAndroidAdbHost } from './adb-host.ts';
+import { requireAndroidAdbHost, runAndroidHostAdb } from './adb-host.ts';
 
 export { activateAndroidTestIme } from './ime-activation.ts';
 export {
@@ -23,11 +23,9 @@ export {
 
 // Serials only, with no full-inventory name, boot-state, or target probes.
 export async function listAndroidAdbSerialsQuick(): Promise<string[]> {
-  // Resolved outside the try: an unbound host port is a wiring bug and must stay loud, while a
-  // failed adb execution legitimately reads as "no devices".
-  const host = requireAndroidAdbHost();
+  requireAndroidAdbHost();
   try {
-    const result = await host.execHostAdb(['devices'], { timeoutMs: 5_000 });
+    const result = await runAndroidHostAdb(['devices'], { timeoutMs: 5_000 });
     return result.stdout
       .split('\n')
       .map((line) => line.trim())

src/platforms/android/__tests__/adb-host-binding.test.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { test } from 'vitest';
+import { AppError } from '@agent-device/kernel/errors';
+import { runAndroidHostAdb } from '@agent-device/platform-android/adb-executor';
+import { mkdtempForTestSync } from '../../../__tests__/test-utils/tmp-dir.ts';
+import '../adb-host-binding.ts';
+
+test.skipIf(process.platform === 'win32')(
+  'the local host binding classifies a real nonzero adb process result',
+  async () => {
+    const tmpDir = mkdtempForTestSync('agent-device-adb-host-binding-');
+    const adbPath = path.join(tmpDir, 'adb');
+    fs.writeFileSync(
+      adbPath,
+      '#!/usr/bin/env node\nprocess.stderr.write("error: device offline\\n"); process.exit(1);',
+    );
+    fs.chmodSync(adbPath, 0o755);
+    const previousPath = process.env.PATH;
+    process.env.PATH = `${tmpDir}${path.delimiter}${previousPath ?? ''}`;
+    try {
+      const error = await runAndroidHostAdb(['devices']).then(
+        () => assert.fail('expected local adb to reject'),
+        (cause: unknown) => cause,
+      );
+
+      assert.ok(error instanceof AppError);
+      assert.equal(error.details?.adbFailure, 'device_offline');
+      assert.equal(error.details?.retriable, true);
+      assert.match(String(error.details?.hint), /adb reconnect/i);
+    } finally {
+      if (previousPath === undefined) {
+        delete process.env.PATH;
+      } else {
+        process.env.PATH = previousPath;
+      }
+    }
+  },
+);

src/platforms/android/adb-executor.ts

@@ -19,7 +19,9 @@ export {
   resolveAndroidTextInjector,
   resolveAndroidTouchProvider,
   resolveScopedAndroidAdbBackgroundTransport,
+  runAndroidHostAdb,
   withAndroidAdbProvider,
+  withAndroidHostAdbTransport,
   type AndroidAdbExecutor,
   type AndroidAdbExecutorOptions,
   type AndroidAdbExecutorResult,

src/platforms/android/emulator-lifecycle.ts

@@ -2,7 +2,8 @@ import type { DeviceInventoryRequest } from '@agent-device/contracts/device';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError, asAppError } from '@agent-device/kernel/errors';
 import type { ExecResult } from '../../utils/exec.ts';
-import { runCmd, runCmdDetached, whichCmd } from '../../utils/exec.ts';
+import { runCmdDetached, whichCmd } from '../../utils/exec.ts';
+import { runAndroidHostAdb } from './adb-executor.ts';
 import { Deadline, retryWithPolicy } from '../../utils/retry.ts';
 import { sleep } from '../../utils/timeouts.ts';
 import { bootFailureHint, classifyBootFailure } from '../boot-diagnostics.ts';
@@ -154,7 +155,7 @@ async function readAndroidBootProp(
   timeoutMs = ANDROID_BOOT_PROP_TIMEOUT_MS,
   signal?: AbortSignal,
 ): Promise<ExecResult> {
-  return await runCmd('adb', ['-s', serial, 'shell', 'getprop', 'sys.boot_completed'], {
+  return await runAndroidHostAdb(['-s', serial, 'shell', 'getprop', 'sys.boot_completed'], {
     allowFailure: true,
     signal,
     timeoutMs,

src/sdk/limrun-runtime-dependencies.test.ts

@@ -136,3 +136,27 @@ test('Limrun appstate forwards an in-flight abort through the provider ADB execu
   await expect(pending).rejects.toMatchObject({ name: 'AbortError' });
   assert.equal(observedSignal, controller.signal);
 });
+
+test('host.runAdb keeps its exported shape and routes through the host transport', async () => {
+  const { createLimrunRuntimeDependencies } = await import('./limrun-runtime-dependencies.ts');
+  const { withAndroidHostAdbTransport } = await import('../platforms/android/adb-executor.ts');
+  const dependencies = createLimrunRuntimeDependencies();
+  const seen: Array<{ args: string[]; options?: Record<string, unknown> }> = [];
+
+  const result = await withAndroidHostAdbTransport(
+    async (args, options) => {
+      seen.push({ args, ...(options ? { options } : {}) });
+      return { stdout: 'ok', stderr: '', exitCode: 0 };
+    },
+    async () =>
+      await dependencies.host.runAdb(['disconnect', 'emulator-5554'], {
+        allowFailure: true,
+        timeoutMs: 10_000,
+      }),
+  );
+
+  assert.deepEqual(result, { stdout: 'ok', stderr: '', exitCode: 0 });
+  assert.deepEqual(seen, [
+    { args: ['disconnect', 'emulator-5554'], options: { allowFailure: true, timeoutMs: 10_000 } },
+  ]);
+});