feat(browserstack): add --provider-appium-version to pin the hosted Appium server

BrowserStack runs Appium 1.x for an App Automate session unless the request names a
version in `bstack:options.appiumVersion`. The `mobile:` commands the WebDriver
interactor issues (`deepLink`, `pressButton`, `activateApp`) need a 2.x or newer
server, so a session left on the default fails those commands.

`--provider-appium-version <version>` (alias `--appium-version`) joins the BrowserStack
device-feature table beside `--provider-timezone` and friends, and threads through the
same connection profile, lease scope, remote config and doctor surfaces. It is
operator-only (`projectConfig: false`) and not recorded.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Procopis-QG

CHANGELOG.md

@@ -10,6 +10,10 @@
   "Untitled Project" / "Untitled Build" with an empty name — even after #2495 carried the flags to
   the provider (#2494). The builder now emits `appium:deviceName`, `appium:platformVersion`, and
   `appium:app` and no legacy key, verified against live App Automate sessions.
+- Added: `--provider-appium-version <version>` (alias `--appium-version`) pins the Appium server
+  BrowserStack runs for the session, as `bstack:options.appiumVersion`. Unset, BrowserStack falls
+  back to Appium 1.x, which predates the `mobile:` commands the interactor issues (`deepLink`,
+  `pressButton`, `activateApp`).
 - Changed (sessions): the implicit session is now keyed by workspace **and platform**, so one checkout
   can drive iOS and Android without inventing a `--session` name for every command (#2580). An
   implicit session was addressed by `cwd:<workspace>:default`, one slot per checkout, and it stayed

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

@@ -230,6 +230,16 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     projectConfig: false,
     recorded: false,
   },
+  {
+    key: 'providerAppiumVersion',
+    names: ['--provider-appium-version', '--appium-version'],
+    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)',
+    projectConfig: false,
+    recorded: false,
+  },
   {
     key: 'providerLanguage',
     names: ['--provider-language', '--language'],

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

@@ -82,6 +82,7 @@ export const COMMON_COMMAND_SUPPORTED_FLAG_KEYS = flagKeys(
   'providerDeviceOrientation',
   'providerGeoLocation',
   'providerTimezone',
+  'providerAppiumVersion',
   'providerLanguage',
   'providerLocale',
   'providerNetworkProfile',

packages/contracts/src/client-connection.ts

@@ -69,6 +69,7 @@ export type AgentDeviceRequestOverrides = Pick<
   | 'providerDeviceOrientation'
   | 'providerGeoLocation'
   | 'providerTimezone'
+  | 'providerAppiumVersion'
   | 'providerLanguage'
   | 'providerLocale'
   | 'providerNetworkProfile'

packages/contracts/src/lease-scope.ts

@@ -219,6 +219,7 @@ const LEASE_ALLOCATE_PROVIDER_FLAG_KEYS = [
   'providerDeviceOrientation',
   'providerGeoLocation',
   'providerTimezone',
+  'providerAppiumVersion',
   'providerLanguage',
   'providerLocale',
   'providerNetworkProfile',

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

@@ -29,6 +29,7 @@ export type CloudProviderProfileFields = {
   providerDeviceOrientation?: ProviderDeviceOrientation;
   providerGeoLocation?: string;
   providerTimezone?: string;
+  providerAppiumVersion?: string;
   providerLanguage?: string;
   providerLocale?: string;
   providerNetworkProfile?: string;

packages/provider-webdriver/src/browserstack-device-features.test.ts

@@ -14,6 +14,7 @@ const DEVICE_FEATURE_FIELDS = [
   'providerDeviceOrientation',
   'providerGeoLocation',
   'providerTimezone',
+  'providerAppiumVersion',
   'providerLanguage',
   'providerLocale',
   'providerNetworkProfile',
@@ -34,6 +35,7 @@ test('configured device features project onto BrowserStack vendor capability key
       providerDeviceOrientation: 'portrait',
       providerGeoLocation: 'US',
       providerTimezone: 'New_York',
+      providerAppiumVersion: '3.2.0',
       providerLanguage: 'Fr',
       providerLocale: 'Fr',
       providerNetworkProfile: '4g-lte-advanced-good',
@@ -46,6 +48,7 @@ test('configured device features project onto BrowserStack vendor capability key
     deviceOrientation: 'portrait',
     geoLocation: 'US',
     timezone: 'New_York',
+    appiumVersion: '3.2.0',
     language: 'Fr',
     locale: 'Fr',
     networkProfile: '4g-lte-advanced-good',

packages/provider-webdriver/src/browserstack-device-features.ts

@@ -20,6 +20,7 @@ export type BrowserStackDeviceFeatureFields = Pick<
   | 'providerDeviceOrientation'
   | 'providerGeoLocation'
   | 'providerTimezone'
+  | 'providerAppiumVersion'
   | 'providerLanguage'
   | 'providerLocale'
   | 'providerNetworkProfile'
@@ -64,6 +65,14 @@ export const BROWSERSTACK_DEVICE_FEATURE_SPECS: readonly BrowserStackDeviceFeatu
     flag: '--provider-timezone',
     type: 'string',
   },
+  {
+    // BrowserStack defaults to Appium 1.x when unset; `mobile:` commands the interactor issues
+    // (deepLink, pressButton, activateApp) need a 2.x+ server.
+    field: 'providerAppiumVersion',
+    capability: 'appiumVersion',
+    flag: '--provider-appium-version',
+    type: 'string',
+  },
   {
     field: 'providerLanguage',
     capability: 'language',

scripts/integration-progress-model.ts

@@ -259,6 +259,7 @@ function summarizeProviderScenarioFlagExclusions() {
         'providerDeviceOrientation',
         'providerGeoLocation',
         'providerTimezone',
+        'providerAppiumVersion',
         'providerLanguage',
         'providerLocale',
         'providerNetworkProfile',

src/cli-schema/command-overrides.ts

@@ -83,6 +83,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
       'providerDeviceOrientation',
       'providerGeoLocation',
       'providerTimezone',
+      'providerAppiumVersion',
       'providerLanguage',
       'providerLocale',
       'providerNetworkProfile',