feat(provider-webdriver): add TestMu AI device cloud provider

.fallowrc.json

@@ -2,6 +2,10 @@
   "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
   "entry": [
     "tsdown.config.ts",
+    "scripts/check-provider-plugin.mjs",
+    "packages/provider-testmu/test/package-smoke.mjs",
+    "packages/provider-testmu/tsdown.config.ts",
+    "packages/provider-testmu/src/plugin.ts",
     "vitest.mutation.config.ts",
     "src/sdk/index.ts",
     "src/sdk/io.ts",
@@ -10,6 +14,7 @@
     "src/sdk/remote-config.ts",
     "src/sdk/install-source.ts",
     "src/sdk/plugins.ts",
+    "src/sdk/plugin-webdriver.ts",
     "src/sdk/android-adb.ts",
     "src/sdk/contracts.ts",
     "src/sdk/selectors.ts",
@@ -56,6 +61,10 @@
     // @agent-device/provider-limrun owns the source import, while the published
     // root build externalizes @limrun/api and retains runtime imports in packed chunks.
     "@limrun/api",
+    // @agent-device/testmu imports agent-device type-only, and its tsconfig maps those specifiers
+    // through this workspace link to core source so typecheck needs no build; Fallow then credits
+    // the source files rather than the package.
+    "agent-device",
     // Oxlint resolves the shared config's JS plugins dynamically from their package names.
     "@nkzw/eslint-plugin",
     "eslint-plugin-no-only-tests",
@@ -66,6 +75,11 @@
     "@arethetypeswrong/cli"
   ],
   "ignoreExports": [
+    {
+      "comment": "The standalone packed-install harness loads this fixture from the selected package path and reads its request scenarios dynamically.",
+      "file": "packages/provider-*/test/package-smoke.mjs",
+      "exports": ["*"]
+    },
     {
       "comment": "Android perf mechanics are selected through the lazy platform host so importing agent-device does not eagerly load adb mechanics. Fallow cannot follow the dynamic property read in src/platform-runtime-perf-host.ts.",
       "file": "packages/platform-android/src/perf.ts",
@@ -287,7 +301,7 @@
     },
     {
       "comment": "Tool config default exports, loaded by the tool rather than imported.",
-      "file": "{oxlint.config.ts,tsdown.config.ts,vitest.mutation.config.ts,website/rspress.config.ts}",
+      "file": "{oxlint.config.ts,tsdown.config.ts,packages/provider-*/tsdown.config.ts,vitest.mutation.config.ts,website/rspress.config.ts}",
       "exports": ["default"]
     },
     {

README.md

@@ -137,15 +137,15 @@ The same session and evidence model works at every step: the agent explores the
 | --- | --- | --- |
 | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. |
 | CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). |
-| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://oss.callstack.com/agent-device/docs/remote-proxy), connect a [device cloud](https://oss.callstack.com/agent-device/docs/device-clouds) (BrowserStack, AWS Device Farm, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
+| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://oss.callstack.com/agent-device/docs/remote-proxy), connect a [device cloud](https://oss.callstack.com/agent-device/docs/device-clouds) (BrowserStack, AWS Device Farm, TestMu AI, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
 
 ## How it works
 
 `agent-device` keeps device state in sessions. It uses a local accessibility bridge for iOS Simulator snapshots and XCTest for iOS interactions, physical iOS, and tvOS; ADB and the snapshot helper on Android; HDC and ArkUI `uitest` on HarmonyOS; Vega CLI/VDA on the Vega Virtual Device; a local helper on macOS; and AT-SPI on Linux.
 
 Support depth varies by target. Newer backends such as HarmonyOS and Vega OS cover a subset of commands; run `agent-device capabilities --platform <platform>` to see what a target supports.
 
-Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Inspect ownership without a daemon via `agent-device device status`, and settle provably dead owners with `agent-device device release --stale`. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds).
+Sessions are scoped to the caller's git worktree, and host-local device claims stop parallel agents from taking over each other's simulators and emulators. Inspect ownership without a daemon via `agent-device device status`, and settle provably dead owners with `agent-device device release --stale`. The same commands drive hosted devices on [BrowserStack, AWS Device Farm, TestMu AI, and Limrun](https://oss.callstack.com/agent-device/docs/device-clouds).
 
 `agent-device` uses the inspect-act-verify process from Vercel's [agent-browser](https://github.com/vercel-labs/agent-browser) for mobile, TV, and desktop apps. Basic `--platform web` support runs `agent-browser` in the same session and replay system.
 

package.json

@@ -73,6 +73,10 @@
     "./plugins": {
       "types": "./dist/src/plugins.d.ts",
       "import": "./dist/src/plugins.js"
+    },
+    "./plugins/webdriver": {
+      "types": "./dist/src/plugins/webdriver.d.ts",
+      "import": "./dist/src/plugins/webdriver.js"
     }
   },
   "engines": {
@@ -175,7 +179,7 @@
     "check:unit": "pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
     "check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
     "prepack": "npm_config_dry_run=false pnpm release:prepare",
-    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/device-selection packages/host-kit packages/capture-kit packages/managed-allocation packages/provision-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/command-registry packages/session-journal packages/ad-replay packages/maestro packages/replay-port packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
+    "typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/device-selection packages/host-kit packages/capture-kit packages/managed-allocation packages/provision-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/command-registry packages/session-journal packages/ad-replay packages/maestro packages/replay-port packages/replay-test packages/provider-webdriver packages/provider-limrun packages/provider-testmu && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
     "test-app:install": "pnpm install --dir examples/test-app",
     "test-app:start": "pnpm --dir examples/test-app start",
     "test-app:ios": "pnpm --dir examples/test-app ios",
@@ -341,6 +345,7 @@
     "vite": "^8.2.1",
     "vitest": "^4.1.11",
     "yaml": "^2.9.0",
-    "yauzl": "^3.4.0"
+    "yauzl": "^3.4.0",
+    "@agent-device/testmu": "workspace:*"
   }
 }

packages/command-registry/src/flag-definitions-connection.ts

@@ -1,5 +1,8 @@
 import { LEASE_BACKENDS } from '@agent-device/kernel/contracts';
-import { PROVIDER_DEVICE_ORIENTATIONS } from '@agent-device/contracts/remote';
+import {
+  PROVIDER_DEVICE_ORIENTATIONS,
+  PROVIDER_DEVICE_TYPES,
+} from '@agent-device/contracts/remote';
 import type { FlagDefinition } from './flag-types.ts';
 
 export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
@@ -175,6 +178,17 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     projectConfig: false,
     recorded: false,
   },
+  {
+    key: 'providerDeviceType',
+    names: ['--provider-device-type'],
+    type: 'enum',
+    enumValues: PROVIDER_DEVICE_TYPES,
+    usageLabel: '--provider-device-type real|virtual',
+    usageDescription:
+      'TestMu AI device pool: real devices or virtual devices (emulators and simulators). Defaults to virtual',
+    projectConfig: false,
+    recorded: false,
+  },
   {
     key: 'providerProject',
     names: ['--provider-project'],
@@ -237,7 +251,7 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     type: 'string',
     usageLabel: '--provider-appium-version <version>',
     usageDescription:
-      'Hosted cloud provider Appium server version, for example 3.2.0. Without it BrowserStack falls back to its default (Appium 1.x)',
+      'Hosted cloud provider Appium server version, for example 3.2.0. Without it each provider starts its own default (Appium 1.x on BrowserStack)',
     projectConfig: false,
     recorded: false,
   },

packages/command-registry/src/flag-groups.ts

@@ -78,6 +78,7 @@ export const COMMON_COMMAND_SUPPORTED_FLAG_KEYS = flagKeys(
   'device',
   'providerApp',
   'providerOsVersion',
+  'providerDeviceType',
   'providerProject',
   'providerBuild',
   'providerSessionName',

packages/contracts/src/__tests__/lease-scope.test.ts

@@ -204,6 +204,7 @@ test('readLeaseAllocateProviderFlags carries the provider-allocation flags and d
       device: 'iPhone 15',
       providerApp: 'bs://abc',
       providerOsVersion: '17',
+      providerDeviceType: 'real',
       providerProject: 'MyProject',
       providerBuild: 'Build-1',
       providerSessionName: 'smoke',
@@ -220,6 +221,7 @@ test('readLeaseAllocateProviderFlags carries the provider-allocation flags and d
       device: 'iPhone 15',
       providerApp: 'bs://abc',
       providerOsVersion: '17',
+      providerDeviceType: 'real',
       providerProject: 'MyProject',
       providerBuild: 'Build-1',
       providerSessionName: 'smoke',

packages/contracts/src/client-connection.ts

@@ -70,6 +70,7 @@ export type AgentDeviceRequestOverrides = Pick<
   | 'clientId'
   | 'providerApp'
   | 'providerOsVersion'
+  | 'providerDeviceType'
   | 'providerProject'
   | 'providerBuild'
   | 'providerSessionName'

packages/contracts/src/facades/remote.ts

@@ -11,17 +11,20 @@ export type {
   ResolvedMetroKind,
 } from '../metro.ts';
 export type {
+  ConnectionProviderCapabilities,
   ProviderConnectionResource,
   ProviderConnectionVerification,
 } from '../provider-connection.ts';
 export {
   PROVIDER_DEVICE_ORIENTATIONS,
+  PROVIDER_DEVICE_TYPES,
   PROVIDER_PROFILE_FIELD_FLAG_ALIASES,
   PROVIDER_PROFILE_FIELD_FLAGS,
 } from '../remote-config-fields.ts';
 export type {
   CloudProviderProfileFields,
   ProviderDeviceOrientation,
+  ProviderDeviceType,
   RemoteConfigMetroOptions,
   RemoteConnectionProfileFields,
 } from '../remote-config-fields.ts';

packages/contracts/src/lease-scope.ts

@@ -221,6 +221,7 @@ const LEASE_ALLOCATE_PROVIDER_FLAG_KEYS = [
   // The Cloud provider profile fields; pinned exhaustive against that vocabulary below.
   'providerApp',
   'providerOsVersion',
+  'providerDeviceType',
   'providerProject',
   'providerBuild',
   'providerSessionName',

packages/contracts/src/provider-connection.ts

@@ -17,3 +17,13 @@ export type ProviderConnectionVerification = {
   device: ProviderConnectionResource;
   app: ProviderConnectionResource;
 };
+
+export type ConnectionProviderCapabilities = {
+  leaseKind: 'proxy' | 'direct-device-provider' | 'remote-provider';
+  requiresAppAttachment: boolean;
+  requiresRemoteDaemon: boolean;
+  supportsArtifacts: boolean;
+  supportsDeferredAppSelection: boolean;
+  supportsDirectPortReverse: boolean;
+  usesCloudWebDriverLease: boolean;
+};

packages/contracts/src/provider-profile-fields.test.ts

@@ -12,6 +12,7 @@ const DECLARATION: ProviderProfileFieldDeclaration = {
   fields: {
     providerApp: 'consumed',
     providerOsVersion: 'refused',
+    providerDeviceType: 'consumed',
     providerProject: 'consumed',
     providerBuild: 'consumed',
     providerSessionName: 'consumed',

packages/contracts/src/remote-config-fields.ts

@@ -20,9 +20,14 @@ import type { MetroPrepareKind } from './metro.ts';
 export const PROVIDER_DEVICE_ORIENTATIONS = ['portrait', 'landscape'] as const;
 export type ProviderDeviceOrientation = (typeof PROVIDER_DEVICE_ORIENTATIONS)[number];
 
+/** Device pool a hosted provider session is created in: physical devices or emulators/simulators. */
+export const PROVIDER_DEVICE_TYPES = ['real', 'virtual'] as const;
+export type ProviderDeviceType = (typeof PROVIDER_DEVICE_TYPES)[number];
+
 export type CloudProviderProfileFields = {
   providerApp?: string;
   providerOsVersion?: string;
+  providerDeviceType?: ProviderDeviceType;
   providerProject?: string;
   providerBuild?: string;
   providerSessionName?: string;
@@ -48,6 +53,7 @@ export const PROVIDER_PROFILE_FIELD_FLAGS: Readonly<
 > = {
   providerApp: '--provider-app',
   providerOsVersion: '--provider-os-version',
+  providerDeviceType: '--provider-device-type',
   providerProject: '--provider-project',
   providerBuild: '--provider-build',
   providerSessionName: '--provider-session-name',

packages/kernel/src/errors.test.ts

@@ -178,3 +178,20 @@ test('discloseDispatchAfterSteps keeps no only while no step of the series was d
   const plain = new Error('socket closed');
   assert.equal(discloseDispatchAfterSteps(plain, 4), plain);
 });
+
+test('bundled plugin errors preserve codes and details without changing subclass checks', async () => {
+  const copyPath = './errors.ts?plugin-copy';
+  const { AppError: PluginError } = await import(copyPath);
+  assert.notEqual(PluginError, AppError);
+  const foreign = new PluginError('INVALID_ARGS', 'bad plugin profile', { provider: 'example' });
+  assert.ok(foreign instanceof AppError);
+  const normalized = normalizeError(foreign);
+  assert.equal(normalized.code, 'INVALID_ARGS');
+  assert.equal(normalized.message, 'bad plugin profile');
+  assert.deepEqual(normalized.details, { provider: 'example' });
+  const ordinary = Object.assign(new Error('bad plugin profile'), { code: 'INVALID_ARGS' });
+  assert.equal(ordinary instanceof AppError, false);
+  class SpecificError extends AppError {}
+  assert.ok(new SpecificError('COMMAND_FAILED', 'specific') instanceof SpecificError);
+  assert.equal(foreign instanceof SpecificError, false);
+});

packages/kernel/src/errors.ts

@@ -36,6 +36,31 @@ export type KnownAppErrorCode = (typeof KNOWN_APP_ERROR_CODES)[number];
 // include a default branch.
 export type AppErrorCode = KnownAppErrorCode | (string & {});
 
+const APP_ERROR_BRAND = Symbol.for('agent-device.AppError');
+
+export class AppError extends Error {
+  static [Symbol.hasInstance](value: unknown): boolean {
+    if (this !== AppError) return Function.prototype[Symbol.hasInstance].call(this, value);
+    return (
+      typeof value === 'object' &&
+      value !== null &&
+      (value as Record<symbol, unknown>)[APP_ERROR_BRAND] === true
+    );
+  }
+
+  code: AppErrorCode;
+  details?: AppErrorDetails;
+  cause?: unknown;
+
+  constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown) {
+    super(message);
+    Object.defineProperty(this, APP_ERROR_BRAND, { value: true });
+    this.code = code;
+    this.details = details;
+    this.cause = cause;
+  }
+}
+
 export function toAppErrorCode(
   code: string | undefined,
   fallback: AppErrorCode = 'COMMAND_FAILED',
@@ -219,19 +244,6 @@ export type DaemonError = {
   supportedOn?: string;
 };
 
-export class AppError extends Error {
-  code: AppErrorCode;
-  details?: AppErrorDetails;
-  cause?: unknown;
-
-  constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown) {
-    super(message);
-    this.code = code;
-    this.details = details;
-    this.cause = cause;
-  }
-}
-
 /** Rehydrate a daemon transport error into the error type used by local callers. */
 export function throwDaemonError(error: DaemonError): never {
   throw new AppError(

packages/provider-limrun/src/device.ts

@@ -14,6 +14,7 @@ export const LIMRUN_PROFILE_FIELDS: ProviderProfileFieldDeclaration = {
   fields: {
     providerApp: 'consumed',
     providerOsVersion: 'refused',
+    providerDeviceType: 'refused',
     providerProject: 'refused',
     providerBuild: 'refused',
     providerSessionName: 'refused',

packages/provider-testmu/README.md

@@ -0,0 +1,17 @@
+# @agent-device/testmu
+
+Use TestMu AI Android and iOS virtual and real devices with [agent-device](https://agent-device.dev).
+You need a TestMu AI account and its API credentials.
+
+```sh
+npm install -g agent-device
+agent-device plugins add @agent-device/testmu
+export LT_USERNAME=your-username
+export LT_ACCESS_KEY=your-access-key
+agent-device connect testmu --platform ios --device "iPhone 16" --provider-os-version 18.0 --provider-app ./MyApp.zip
+```
+
+See the [TestMu AI guide](https://agent-device.dev/docs/testmu) for setup and supported operations.
+To update the plugin, run `agent-device plugins update @agent-device/testmu`.
+
+After adding or updating a plugin, close your sessions and run `agent-device daemon stop` before reconnecting.