feat(cloud-webdriver): BrowserStack device-feature capabilities, and fix cloud orientation (#1544)

* feat(cloud-webdriver): support BrowserStack device-feature capabilities

Adds the eight BrowserStack "device feature" session capabilities that had no
representation in agent-device: deviceOrientation, geoLocation, timezone,
language, locale, networkProfile, customNetwork, and resignApp.

These are vendor capabilities, so they are emitted inside `bstack:options`
rather than at the top level. BrowserStack's YAML config lists them unnested
and its SDK relocates them; agent-device talks to the hub directly, so it
nests them itself.

A single spec table drives both the flag reader and the capability builder, so
adding a capability is a table row rather than a branch in each. A structural
test asserts every field owns exactly one row, since a field the table forgets
would parse off the CLI, ride the profile, and then be silently dropped before
the hub ever saw it.

Rejects combinations the provider cannot act on unambiguously: an unknown
orientation is caught at the flag boundary instead of being forwarded to a hub
that accepts and then ignores it, --provider-no-resign-app is refused on
Android, and a named network profile cannot be combined with a custom network
shape.

Also fixes a latent shallow-merge bug in buildBrowserStackCapabilities: a
caller supplying its own `bstack:options` replaced the whole object and
silently dropped the project, build, and session labels. It is now merged
per key.

* fix(cloud-webdriver): rotate via WebDriver orientation endpoints

`setOrientation` on the cloud WebDriver path sent `mobile: rotate`, which is
not a driver command at all. UiAutomator2's own error enumerates its
extensions and `rotate` is absent from the list, so `agent-device orientation`
was a hard failure on every hosted provider.

It also forwarded agent-device's four-way rotation vocabulary verbatim
("landscape-left", "portrait-upside-down"), where the protocol accepts only
uppercase PORTRAIT/LANDSCAPE. Every other platform has a translation layer;
this path was the only one without one.

Now two transports, ordered by backend. `POST /rotation` takes exact four-way
degrees and leads on Android, since it is the only endpoint that can express
upside-down and left-versus-right. `POST /orientation` is two-way and leads on
XCUITest, which rejects `/rotation`. Each falls back to the other, because only
BrowserStack's UiAutomator2 is verified and a provider whose driver disagrees
should degrade rather than hard-fail.

Verified live against BrowserStack App Automate:
  POST /rotation {"x":0,"y":0,"z":0} -> 200 {"value":"ROTATION_0"}

The rotation-to-surface-index mapping moves to contracts/device-rotation.ts and
the existing adb path now reads from it, so the local and hosted mappings
cannot drift apart.

Note this rotates the current display, not persistent device rotation, so an
activity that does not pin its own orientation may still need rotating once it
is in the foreground.

The capability was declared "partial" without the transport existing, and no
test covered setOrientation on the cloud path; only adb and the Apple runner
were covered. Both gaps are now closed.

* fix(cloud-webdriver): narrow orientation fallback and gate provider-owned flags

Addresses review on #1544.

The orientation fallback caught every error, so a timeout, an auth rejection, a
dead session or a provider 5xx on the first transport was swallowed and retried
against the second. When that one also failed the caller got "rejected both
endpoints" with the real cause discarded. Fallback is now keyed on structured
unsupported-endpoint signals only — HTTP 404/405, or a W3C `unknown command` /
`unknown method` code — matching the repo rule of keying on typed details rather
than message text. Everything else rethrows unchanged.

Device-feature capabilities are BrowserStack-owned, but the flags were accepted
by any cloud provider, persisted into the generated profile, and then silently
dropped at session creation. `connect aws-device-farm` now rejects them with a
typed error naming each offending flag, raised before the provider's own
required-argument checks so the caller is told what is unsupported rather than
what else is missing. Ownership is modelled on the capability spec table, so a
new capability inherits the guard without a second list to maintain.

Adds provider-backed orientation scenarios driven through public daemon dispatch
against the fake WebDriver provider: the four-way endpoint on the happy path,
the documented collapse onto the two-way endpoint when the driver does not
implement `/rotation`, and a provider 5xx that must surface without consulting
the second transport. The fake server's route handling became a table in the
process — it had grown to ten branches in one function.

* fix(cloud-webdriver): read W3C error codes before status, enforce ownership at the runtime boundary

Addresses the second review pass on #1544.

The fallback classifier returned on any 404/405 before consulting the W3C error
code, so an HTTP 404 carrying `invalid session id` was masked as a missing route
and retried against the second transport. The structured code now takes
precedence whenever the driver sent one; bare status is consulted only when no
code exists. Two cases pin it: a 404 `invalid session id` and a 405 `timeout`
must both surface rather than fall through.

Provider ownership was enforced only in the CLI profile builder, which the typed
client and hand-authored remote-config profiles bypass entirely — both reach
session preparation without passing through `connect`, so the capabilities were
accepted and then dropped. The check now lives on the capability-ownership
module and runs inside AWS Device Farm's `prepareSession`, with the CLI builder
calling the same helper instead of its own copy. Covered by a scenario that
drives the runtime boundary directly and asserts the rejection happens before
any provider session is created.

Author: leovarmak

packages/contracts/src/client-connection.ts

@@ -61,6 +61,14 @@ export type AgentDeviceRequestOverrides = Pick<
   | 'providerProject'
   | 'providerBuild'
   | 'providerSessionName'
+  | 'providerDeviceOrientation'
+  | 'providerGeoLocation'
+  | 'providerTimezone'
+  | 'providerLanguage'
+  | 'providerLocale'
+  | 'providerNetworkProfile'
+  | 'providerCustomNetwork'
+  | 'providerNoResignApp'
   | 'awsProjectArn'
   | 'awsDeviceArn'
   | 'awsAppArn'

packages/contracts/src/device-rotation.ts

@@ -8,6 +8,30 @@ export const DEVICE_ROTATIONS = [
 ] as const;
 export type DeviceRotation = (typeof DEVICE_ROTATIONS)[number];
 
+/**
+ * Android `Surface.ROTATION_*` index per rotation, which is also the value the `user_rotation`
+ * system setting takes and, multiplied by 90, the `z` degrees the WebDriver `/rotation` endpoint
+ * takes. One table so the adb path and the cloud WebDriver path cannot drift apart.
+ */
+export const DEVICE_ROTATION_SURFACE_INDEX = {
+  portrait: 0,
+  'landscape-left': 1,
+  'portrait-upside-down': 2,
+  'landscape-right': 3,
+} as const satisfies Record<DeviceRotation, 0 | 1 | 2 | 3>;
+
+export function deviceRotationSurfaceDegrees(rotation: DeviceRotation): 0 | 90 | 180 | 270 {
+  return (DEVICE_ROTATION_SURFACE_INDEX[rotation] * 90) as 0 | 90 | 180 | 270;
+}
+
+/**
+ * Collapses the four-way rotation onto the two values the WebDriver `/orientation` endpoint accepts.
+ * Lossy by nature: both landscape rotations report `LANDSCAPE`, both portraits `PORTRAIT`.
+ */
+export function deviceRotationOrientation(rotation: DeviceRotation): 'PORTRAIT' | 'LANDSCAPE' {
+  return DEVICE_ROTATION_SURFACE_INDEX[rotation] % 2 === 0 ? 'PORTRAIT' : 'LANDSCAPE';
+}
+
 export function parseDeviceRotation(input: string | undefined): DeviceRotation {
   if (input === undefined) {
     throw new AppError(

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

@@ -12,12 +12,28 @@ import type {
 
 import type { MetroPrepareKind } from './metro.ts';
 
+/**
+ * Screen orientation a hosted provider session starts in. Distinct from `DeviceRotation`
+ * (`contracts/device-rotation.ts`): that is a four-way runtime rotation command, this is the
+ * two-way session-creation capability hosted providers accept.
+ */
+export const PROVIDER_DEVICE_ORIENTATIONS = ['portrait', 'landscape'] as const;
+export type ProviderDeviceOrientation = (typeof PROVIDER_DEVICE_ORIENTATIONS)[number];
+
 export type CloudProviderProfileFields = {
   providerApp?: string;
   providerOsVersion?: string;
   providerProject?: string;
   providerBuild?: string;
   providerSessionName?: string;
+  providerDeviceOrientation?: ProviderDeviceOrientation;
+  providerGeoLocation?: string;
+  providerTimezone?: string;
+  providerLanguage?: string;
+  providerLocale?: string;
+  providerNetworkProfile?: string;
+  providerCustomNetwork?: string;
+  providerNoResignApp?: boolean;
   awsProjectArn?: string;
   awsDeviceArn?: string;
   awsAppArn?: string;

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

@@ -0,0 +1,126 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+
+import { AppError } from '@agent-device/kernel/errors';
+import {
+  BROWSERSTACK_DEVICE_FEATURE_SPECS,
+  buildBrowserStackDeviceFeatureCapabilities,
+  readBrowserStackDeviceFeatureFields,
+} from './browserstack-device-features.ts';
+
+// Every device-feature field must own a spec row: a field the table forgets parses off the CLI,
+// rides the profile, and is then silently dropped before the hub ever sees it.
+const DEVICE_FEATURE_FIELDS = [
+  'providerDeviceOrientation',
+  'providerGeoLocation',
+  'providerTimezone',
+  'providerLanguage',
+  'providerLocale',
+  'providerNetworkProfile',
+  'providerCustomNetwork',
+  'providerNoResignApp',
+] as const;
+
+test('every device-feature field maps to exactly one capability spec', () => {
+  const fields = BROWSERSTACK_DEVICE_FEATURE_SPECS.map((spec) => spec.field);
+  assert.deepEqual([...fields].sort(), [...DEVICE_FEATURE_FIELDS].sort());
+  const capabilities = BROWSERSTACK_DEVICE_FEATURE_SPECS.map((spec) => spec.capability);
+  assert.equal(new Set(capabilities).size, capabilities.length);
+});
+
+test('configured device features project onto BrowserStack vendor capability keys', () => {
+  const capabilities = buildBrowserStackDeviceFeatureCapabilities(
+    {
+      providerDeviceOrientation: 'portrait',
+      providerGeoLocation: 'US',
+      providerTimezone: 'New_York',
+      providerLanguage: 'Fr',
+      providerLocale: 'Fr',
+      providerNetworkProfile: '4g-lte-advanced-good',
+      providerNoResignApp: true,
+    },
+    'ios',
+  );
+
+  assert.deepEqual(capabilities, {
+    deviceOrientation: 'portrait',
+    geoLocation: 'US',
+    timezone: 'New_York',
+    language: 'Fr',
+    locale: 'Fr',
+    networkProfile: '4g-lte-advanced-good',
+    // The flag is the opt-out, so its presence has to invert into an explicit false.
+    resignApp: false,
+  });
+});
+
+test('unset device features emit no capability keys', () => {
+  assert.deepEqual(buildBrowserStackDeviceFeatureCapabilities({}, 'android'), {});
+});
+
+test('app re-signing opt-out is rejected on Android with a recovery hint', () => {
+  assert.throws(
+    () => buildBrowserStackDeviceFeatureCapabilities({ providerNoResignApp: true }, 'android'),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'INVALID_ARGS');
+      assert.match(error.message, /--provider-no-resign-app applies to ios sessions only/);
+      assert.match(String(error.details?.hint), /--platform ios/);
+      return true;
+    },
+  );
+});
+
+test('a named network profile and a custom network shape cannot both be configured', () => {
+  assert.throws(
+    () =>
+      buildBrowserStackDeviceFeatureCapabilities(
+        { providerNetworkProfile: '4g-lte-advanced-good', providerCustomNetwork: '1000' },
+        'android',
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'INVALID_ARGS');
+      assert.match(String(error.details?.hint), /only one of/);
+      return true;
+    },
+  );
+});
+
+test('device-feature flags are read off an untyped daemon request flag bag', () => {
+  const fields = readBrowserStackDeviceFeatureFields({
+    providerDeviceOrientation: 'landscape',
+    providerTimezone: 'New_York',
+    providerNoResignApp: true,
+    unrelatedFlag: 'ignored',
+  });
+
+  assert.deepEqual(fields, {
+    providerDeviceOrientation: 'landscape',
+    providerTimezone: 'New_York',
+    providerNoResignApp: true,
+  });
+});
+
+test('an unrecognized orientation is rejected at the flag boundary, not forwarded to the hub', () => {
+  assert.throws(
+    () => readBrowserStackDeviceFeatureFields({ providerDeviceOrientation: 'landscape-left' }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'INVALID_ARGS');
+      assert.match(String(error.details?.hint), /portrait\|landscape/);
+      return true;
+    },
+  );
+});
+
+test('empty and non-string flag values are treated as unset', () => {
+  assert.deepEqual(
+    readBrowserStackDeviceFeatureFields({
+      providerTimezone: '',
+      providerGeoLocation: 42,
+      providerNoResignApp: 'yes',
+    }),
+    {},
+  );
+});