From 6fc227f34682842429948ca2e024ac3348b9a966 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 12:32:44 +0100 Subject: [PATCH 1/6] feat(open): report device kind, model and osVersion on open and session identity A CI integration that rents a device records what OS a capture ran on from the command result alone, so `open --json` and `session list --json` now carry the same device description `devices` already reports. `open` adds `model` and `osVersion` beside the `kind` it already echoed, and `session list` adds all three to each session's device. The daemon carries the value its discovery read (simctl, adb, or devicectl) or the value the provider's create-session answer granted, never the one the request asked for. A target that reports nothing omits the field rather than naming an OS it did not read, so a caller can tell a read version from silence. The WebDriver provider now reads the granted OS from the hub's returned capabilities (W3C `platformVersion` or its `appium:` variant) instead of reporting none. Co-Authored-By: Claude Opus 5.5 --- .../client-normalizers-device.test.ts | 54 ++++++++++ packages/client/src/client-normalizers.ts | 16 ++- .../src/output/result-serialization.test.ts | 100 ++++++++++++++++++ .../src/output/result-serialization.ts | 3 + packages/contracts/src/client-device-view.ts | 6 ++ .../daemon/src/resources/macos-app-lease.ts | 2 + .../session-inventory-session-device.test.ts | 86 +++++++++++++++ .../__tests__/session-open-surface.test.ts | 42 ++++++-- .../session-lifecycle/internal/inventory.ts | 14 +++ .../internal/session-open-surface.ts | 2 + packages/kernel/src/record.ts | 7 ++ .../provider-webdriver/src/runtime-session.ts | 26 ++++- .../cloud-webdriver-ios-text-entry.test.ts | 12 ++- website/docs/docs/client-api.md | 2 + website/docs/docs/commands.md | 2 + 15 files changed, 358 insertions(+), 16 deletions(-) create mode 100644 packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-inventory-session-device.test.ts diff --git a/packages/client/src/__tests__/client-normalizers-device.test.ts b/packages/client/src/__tests__/client-normalizers-device.test.ts index c3a1f1abc5..3da873dc9f 100644 --- a/packages/client/src/__tests__/client-normalizers-device.test.ts +++ b/packages/client/src/__tests__/client-normalizers-device.test.ts @@ -167,3 +167,57 @@ test('normalizeOpenDevice preserves Vega identifier shaping', () => { assert.equal('ios' in (vega ?? {}), false); assert.equal('android' in (vega ?? {}), false); }); + +// #4525: the SDK reads the OS a session or an open ran on off the same payload the CLI prints. +test('normalizeOpenDevice carries the device kind, model and OS version a daemon reports', () => { + const ios = normalizeOpenDevice({ + platform: 'ios', + id: 'SIM-001', + device: 'iPhone 17', + kind: 'simulator', + model: 'iPhone 17', + osVersion: '27.0', + device_udid: 'SIM-001', + }); + assert.equal(ios?.kind, 'simulator'); + assert.equal(ios?.model, 'iPhone 17'); + assert.equal(ios?.osVersion, '27.0'); + + // A daemon that reports nothing states nothing: no field is invented for it. + const unreported = normalizeOpenDevice({ + platform: 'android', + id: 'emulator-5554', + device: 'pixel-9', + }); + assert.equal('kind' in (unreported ?? {}), false); + assert.equal('model' in (unreported ?? {}), false); + assert.equal('osVersion' in (unreported ?? {}), false); + + // An empty string is not an OS version, and an unknown kind is not a kind. + const malformed = normalizeOpenDevice({ + platform: 'android', + id: 'emulator-5554', + device: 'pixel-9', + kind: 'phone', + osVersion: '', + }); + assert.equal('kind' in (malformed ?? {}), false); + assert.equal('osVersion' in (malformed ?? {}), false); +}); + +test('normalizeSession carries the session device kind, model and OS version', () => { + const session = normalizeSession({ + name: 'qa', + createdAt: 1, + platform: 'android', + target: 'mobile', + id: 'emulator-5554', + device: 'pixel-9', + kind: 'emulator', + model: 'sdk_gphone64_arm64', + osVersion: '16', + }); + assert.equal(session.device.kind, 'emulator'); + assert.equal(session.device.model, 'sdk_gphone64_arm64'); + assert.equal(session.device.osVersion, '16'); +}); diff --git a/packages/client/src/client-normalizers.ts b/packages/client/src/client-normalizers.ts index 2b99528c0c..52b3439fda 100644 --- a/packages/client/src/client-normalizers.ts +++ b/packages/client/src/client-normalizers.ts @@ -37,6 +37,7 @@ import { isRecord, readDeviceTarget, readNullableString, + readOptionalDeviceKind, readOptionalString, readRequiredDeviceKind, readRequiredNumber, @@ -124,7 +125,11 @@ export function normalizeDevice(value: unknown): AgentDeviceDevice { }; } -/** Reads the optional presentation-only hardware model and OS version of a listed device. */ +/** + * Reads the optional presentation-only hardware model and OS version a daemon response carries, + * for both a listed device and the device of an open session. Absent means the host or provider + * reported nothing; it is never inferred here. + */ function readDeviceDescription( record: Record, ): Pick { @@ -150,6 +155,7 @@ export function normalizeSession(value: unknown): AgentDeviceSession { const { record, platform, id, name, target } = readClientDeviceIdentity(value, 'name'); const deviceName = readRequiredString(record, 'device'); const appleOs = readAppleOs(record); + const kind = readOptionalDeviceKind(record, 'kind'); const identifiers = { session: name, ...buildDeviceIdentifiers(platform, id, deviceName), @@ -167,6 +173,10 @@ export function normalizeSession(value: unknown): AgentDeviceSession { name: deviceName, // Additive Apple-OS discriminant; present only when the daemon emits it (Apple devices). ...(appleOs ? { appleOs } : {}), + // Model and OS version are the daemon's discovery read; a session whose host reported + // neither carries neither. + ...readDeviceDescription(record), + ...(kind ? { kind } : {}), identifiers, ...buildClientDevicePlatformFields(platform, id, { simulatorSetPath: readNullableString(record, 'ios_simulator_device_set'), @@ -240,6 +250,7 @@ export function normalizeOpenDevice( return undefined; } const target = readDeviceTarget(value, 'target'); + const kind = readOptionalDeviceKind(value, 'kind'); const serial = isSerialAddressablePlatform(platform) ? (readOptionalString(value, 'serial') ?? id) : undefined; @@ -252,6 +263,9 @@ export function normalizeOpenDevice( target, id, name, + // The daemon echoes what discovery or the provider reported; an absent field stays absent. + ...readDeviceDescription(value), + ...(kind ? { kind } : {}), identifiers, ...buildClientDevicePlatformFields( platform, diff --git a/packages/command-output/src/output/result-serialization.test.ts b/packages/command-output/src/output/result-serialization.test.ts index cac3bc46bf..91bb7fdd3e 100644 --- a/packages/command-output/src/output/result-serialization.test.ts +++ b/packages/command-output/src/output/result-serialization.test.ts @@ -80,6 +80,106 @@ test('serializeOpenResult includes android serial for open payloads', () => { }); }); +// #4525: a CI integration records the OS a capture ran on from this result alone. +test('serializeOpenResult reports the device kind, model and OS version the host reported', () => { + const ios = serializeOpenResult({ + session: 'ios', + device: { + platform: 'ios', + target: 'mobile', + id: 'SIM-001', + name: 'iPhone 17', + kind: 'simulator', + model: 'iPhone 17', + osVersion: '27.0', + identifiers: { session: 'ios', deviceId: 'SIM-001', deviceName: 'iPhone 17' }, + ios: { udid: 'SIM-001' }, + }, + identifiers: { session: 'ios', deviceId: 'SIM-001', deviceName: 'iPhone 17' }, + }); + assert.deepEqual( + { + platform: ios.platform, + device: ios.device, + kind: ios.kind, + model: ios.model, + osVersion: ios.osVersion, + }, + { + platform: 'ios', + device: 'iPhone 17', + kind: 'simulator', + model: 'iPhone 17', + osVersion: '27.0', + }, + ); + + const android = serializeOpenResult({ + session: 'android', + device: { + platform: 'android', + target: 'mobile', + id: 'emulator-5554', + name: 'pixel-9', + kind: 'emulator', + model: 'sdk_gphone64_arm64', + osVersion: '16', + identifiers: { session: 'android', deviceId: 'emulator-5554', serial: 'emulator-5554' }, + android: { serial: 'emulator-5554' }, + }, + identifiers: { session: 'android', deviceId: 'emulator-5554', serial: 'emulator-5554' }, + }); + assert.equal(android.kind, 'emulator'); + assert.equal(android.model, 'sdk_gphone64_arm64'); + assert.equal(android.osVersion, '16'); + assert.equal(android.serial, 'emulator-5554'); + + // A rented cloud device keeps what its provider reported, on the same keys. + const remote = serializeOpenResult({ + session: 'remote', + device: { + platform: 'ios', + target: 'mobile', + id: 'browserstack:ios:lease-1', + name: 'iPhone 15', + kind: 'device', + osVersion: '17.2', + identifiers: { + session: 'remote', + deviceId: 'browserstack:ios:lease-1', + deviceName: 'iPhone 15', + }, + ios: { udid: 'browserstack:ios:lease-1' }, + }, + identifiers: { session: 'remote', deviceId: 'browserstack:ios:lease-1' }, + }); + assert.equal(remote.kind, 'device'); + assert.equal(remote.osVersion, '17.2'); + // The provider reported no hardware model, so the field stays out rather than naming one. + assert.equal('model' in remote, false); +}); + +test('serializeSessionListEntry reports the session device kind and OS version', () => { + const data = serializeSessionListEntry({ + name: 'qa', + createdAt: 123, + device: { + platform: 'ios', + target: 'mobile', + id: 'SIM-001', + name: 'iPhone 17', + kind: 'simulator', + osVersion: '27.0', + identifiers: { session: 'qa', deviceId: 'SIM-001', deviceName: 'iPhone 17' }, + ios: { udid: 'SIM-001' }, + }, + identifiers: { session: 'qa', deviceId: 'SIM-001', deviceName: 'iPhone 17' }, + }); + + assert.equal(data.kind, 'simulator'); + assert.equal(data.osVersion, '27.0'); +}); + test('serializeOpenResult carries an answered launch confirmation', () => { const data = serializeOpenResult({ session: 'qa', diff --git a/packages/command-output/src/output/result-serialization.ts b/packages/command-output/src/output/result-serialization.ts index 83107b392f..1c07c1211d 100644 --- a/packages/command-output/src/output/result-serialization.ts +++ b/packages/command-output/src/output/result-serialization.ts @@ -29,6 +29,9 @@ function serializeSessionDevice( target: device.target, device: device.name, id: device.id, + ...(device.kind ? { kind: device.kind } : {}), + ...(device.model ? { model: device.model } : {}), + ...(device.osVersion ? { osVersion: device.osVersion } : {}), ...(device.platform === 'ios' ? { device_udid: device.ios?.udid ?? device.id, diff --git a/packages/contracts/src/client-device-view.ts b/packages/contracts/src/client-device-view.ts index fbb0c578b9..1f84229804 100644 --- a/packages/contracts/src/client-device-view.ts +++ b/packages/contracts/src/client-device-view.ts @@ -65,6 +65,12 @@ export type AgentDeviceSessionDevice = { * Apple devices; `platform` still carries the leaf (`ios`/`macos`). */ appleOs?: AppleOS; + /** Simulator/emulator/physical split. Absent only from a daemon older than the field. */ + kind?: DeviceKind; + /** Hardware model, for example `iPhone 17 Pro` or `Pixel 9`, when the host or provider reports it. */ + model?: string; + /** OS version, for example `26.1` or `16`, when the host or provider reports it. Never inferred. */ + osVersion?: string; identifiers: AgentDeviceIdentifiers; ios?: { udid: string; diff --git a/packages/daemon/src/resources/macos-app-lease.ts b/packages/daemon/src/resources/macos-app-lease.ts index 8ac4950fef..ba20ba0223 100644 --- a/packages/daemon/src/resources/macos-app-lease.ts +++ b/packages/daemon/src/resources/macos-app-lease.ts @@ -332,6 +332,8 @@ const HOST_OPEN_RESULT_KEYS = [ 'device', 'id', 'kind', + 'model', + 'osVersion', 'serial', 'device_udid', 'ios_simulator_device_set', diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-inventory-session-device.test.ts b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-inventory-session-device.test.ts new file mode 100644 index 0000000000..2e3933611d --- /dev/null +++ b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-inventory-session-device.test.ts @@ -0,0 +1,86 @@ +import { test, expect } from 'vitest'; +import { daemonPlatformServicesFixture } from '../../../../__tests__/support/platform-services-fixture.ts'; +import { makeSessionStore } from '../../../../__tests__/support/store-factory.ts'; +import { makeSession } from '../../../../__tests__/support/handlers/session-test-harness.ts'; +import { handleSessionInventoryCommands } from '../inventory.ts'; +import type { DaemonRequest } from '../../../../core/daemon-request.ts'; +import { bindTestCommandHost, createTestHostEnvironment } from '@agent-device/test-kit'; +import type { SessionStore } from '../../../../core/session-store.ts'; + +bindTestCommandHost(); + +// #4525: a remote CI integration records which OS a capture ran on from the command result alone, +// so `session list` reports the device kind beside the model and OS version its host discovery read. +test('session_list reports the session device kind, model and OS version', async () => { + const sessionStore = makeSessionStore('agent-device-inventory-session-device-'); + sessionStore.publish( + 'ios-1', + makeSession('ios-1', { + platform: 'apple', + appleOs: 'ios', + id: 'SIM-001', + name: 'iPhone 17', + kind: 'simulator', + model: 'iPhone 17', + osVersion: '27.0', + booted: true, + }), + ); + sessionStore.publish( + 'android-1', + makeSession('android-1', { + platform: 'android', + id: 'emulator-5554', + name: 'pixel-9', + kind: 'emulator', + model: 'sdk_gphone64_arm64', + osVersion: '16', + booted: true, + }), + ); + // A host that read no description (for example a stopped AVD) states nothing about the OS. + sessionStore.publish( + 'android-stopped', + makeSession('android-stopped', { + platform: 'android', + id: 'emulator-5556', + name: 'pixel-8', + kind: 'emulator', + }), + ); + + const sessions = await listSessions(sessionStore); + const ios = sessions.find((session) => session.name === 'ios-1'); + expect(ios?.kind).toBe('simulator'); + expect(ios?.model).toBe('iPhone 17'); + expect(ios?.osVersion).toBe('27.0'); + + const android = sessions.find((session) => session.name === 'android-1'); + expect(android?.kind).toBe('emulator'); + expect(android?.model).toBe('sdk_gphone64_arm64'); + expect(android?.osVersion).toBe('16'); + + const stopped = sessions.find((session) => session.name === 'android-stopped'); + expect(stopped?.kind).toBe('emulator'); + expect(stopped && 'osVersion' in stopped).toBe(false); + expect(stopped && 'model' in stopped).toBe(false); +}); + +async function listSessions(sessionStore: SessionStore): Promise>> { + const req: DaemonRequest = { + token: 't', + session: 'default', + command: 'session_list', + positionals: [], + }; + const response = await handleSessionInventoryCommands({ + host: createTestHostEnvironment(), + req, + sessionName: 'default', + sessionStore, + platformServices: daemonPlatformServicesFixture(), + }); + expect(response?.ok).toBe(true); + if (!response?.ok) throw new Error('expected session_list to succeed'); + return response.data?.sessions as Array>; +} diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-open-surface.test.ts b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-open-surface.test.ts index d8bdb4deb7..e5bec4bc6a 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-open-surface.test.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-open-surface.test.ts @@ -29,6 +29,36 @@ test('buildOpenResult exposes the Vega serial without leaking an internal platfo assert.equal(result.target, 'tv'); }); +const IOS_OPEN_RESULT_BASE = { + sessionName: 'ios-launch-url', + sessionStateDir: '/tmp/state', + runnerLogPath: '/tmp/runner.log', + requestLogPath: '/tmp/request.ndjson', + eventLogPath: '/tmp/events.ndjson', + surface: 'app' as const, + device: IOS_SIMULATOR, + runtimeHintCount: () => 0, + sessionReused: false, +}; + +// #4525: `open --json` is the one source a remote CI integration reads the capture OS from. +test('buildOpenResult reports the OS version and model the host reported, and omits what it did not', () => { + const described = buildOpenResult({ + ...IOS_OPEN_RESULT_BASE, + device: { ...IOS_SIMULATOR, model: 'iPhone 17 Pro', osVersion: '27.0' }, + }); + assert.equal(described.kind, 'simulator'); + assert.equal(described.model, 'iPhone 17 Pro'); + assert.equal(described.osVersion, '27.0'); + + // A host or provider that reports nothing gets no field: the reader cannot tell a + // guessed OS from a read one, so silence is the only honest answer. + const unreported = buildOpenResult({ ...IOS_OPEN_RESULT_BASE, device: IOS_SIMULATOR }); + assert.equal(unreported.kind, 'simulator'); + assert.equal('model' in unreported, false); + assert.equal('osVersion' in unreported, false); +}); + test('buildOpenResult exposes typed device-selection evidence once at response level', () => { const result = buildOpenResult({ sessionName: 'ios-selection', @@ -58,17 +88,7 @@ test('buildOpenResult exposes typed device-selection evidence once at response l }); test('buildOpenResult reports an answered launch confirmation and omits one that never appeared', () => { - const base = { - sessionName: 'ios-launch-url', - sessionStateDir: '/tmp/state', - runnerLogPath: '/tmp/runner.log', - requestLogPath: '/tmp/request.ndjson', - eventLogPath: '/tmp/events.ndjson', - surface: 'app' as const, - device: IOS_SIMULATOR, - runtimeHintCount: () => 0, - sessionReused: false, - }; + const base = IOS_OPEN_RESULT_BASE; assert.equal( buildOpenResult({ ...base, launchConfirmation: { launchConfirmation: 'accepted' } }) diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/inventory.ts b/packages/daemon/src/sessions/session-lifecycle/internal/inventory.ts index 037ff25825..4d8275ab05 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/inventory.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/inventory.ts @@ -146,6 +146,8 @@ function publicSessionInfo({ address, session }: SessionRef, sessionStore: Sessi device: session.device.name, id: session.device.id, device_id: session.device.id, + kind: session.device.kind, + ...publicDeviceDescription(session.device), createdAt: session.createdAt, ...(isApplePlatform(session.device.platform) && !isMacOs(session.device) && { @@ -489,6 +491,18 @@ function publicDeviceInfo({ }; } +/** + * The presentation-only device description `session list` reports beside the session's identity: + * the hardware model and OS version the host's discovery read. Omitted when discovery reported + * neither, so a caller never reads a guessed OS for a session. + */ +function publicDeviceDescription(device: DeviceInfo): Record { + return { + ...(device.model ? { model: device.model } : {}), + ...(device.osVersion ? { osVersion: device.osVersion } : {}), + }; +} + function matchesRequestedPlatform( device: DeviceInfo, requestedPlatform: PlatformSelector | undefined, diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts index b3212eef7d..8bb18a5d46 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts @@ -72,6 +72,8 @@ export function buildOpenResult(params: { result.device = device.name; result.id = device.id; result.kind = device.kind; + if (device.model) result.model = device.model; + if (device.osVersion) result.osVersion = device.osVersion; if (isSerialAddressablePlatform(device.platform)) { result.serial = device.id; } diff --git a/packages/kernel/src/record.ts b/packages/kernel/src/record.ts index 700eff1e8b..0d7f531a61 100644 --- a/packages/kernel/src/record.ts +++ b/packages/kernel/src/record.ts @@ -72,6 +72,13 @@ export function readRequiredDeviceKind(record: Record, key: str return readRequired(record, key, parseDeviceKind, `Daemon response has invalid "${key}".`); } +export function readOptionalDeviceKind( + record: Record, + key: string, +): DeviceKind | undefined { + return readOptional(record, key, parseDeviceKind); +} + export function readDeviceTarget(record: Record, key: string): DeviceTarget { return readOptional(record, key, parseDeviceTarget) ?? 'mobile'; } diff --git a/packages/provider-webdriver/src/runtime-session.ts b/packages/provider-webdriver/src/runtime-session.ts index 8e91b83f9e..8fac268588 100644 --- a/packages/provider-webdriver/src/runtime-session.ts +++ b/packages/provider-webdriver/src/runtime-session.ts @@ -302,7 +302,7 @@ export class WebDriverSessionManager { requestPolicy: this.options.requestPolicy, }); const session = await this.createSessionWithPreparedCleanup(client, prepared, lease, req); - const device = this.deviceForLease(lease, prepared); + const device = this.deviceForLease(lease, prepared, session.capabilities); const capabilities = createCloudWebDriverCapabilities({ provider: this.options.provider, platform: prepared.platform, @@ -550,7 +550,11 @@ export class WebDriverSessionManager { }; } - private deviceForLease(lease: DeviceLease, prepared: CloudWebDriverPreparedSession): DeviceInfo { + private deviceForLease( + lease: DeviceLease, + prepared: CloudWebDriverPreparedSession, + capabilities: Record, + ): DeviceInfo { return { ...deviceFieldsFromPublicPlatform(prepared.platform), ...(prepared.platform === 'ios' ? { appleOs: 'ios' as const } : {}), @@ -561,6 +565,7 @@ export class WebDriverSessionManager { name: prepared.deviceName, kind: 'device', target: 'mobile', + ...deviceDescriptionFromWebDriverCapabilities(capabilities), booted: true, }; } @@ -612,6 +617,23 @@ export class WebDriverSessionManager { } } +/** + * The OS version an Appium-style hub echoes back in its create-session capabilities. W3C + * `platformVersion` and its `appium:` variant both count; a hub that reports neither leaves it unset + * rather than repeating what was asked for, so `open` never reports an OS the provider did not grant. + */ +function deviceDescriptionFromWebDriverCapabilities( + capabilities: Record, +): Pick { + const osVersion = readCapability(capabilities, 'platformVersion'); + return osVersion ? { osVersion } : {}; +} + +function readCapability(capabilities: Record, key: string): string | undefined { + const value = capabilities[key] ?? capabilities[`appium:${key}`]; + return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined; +} + /** * The transport gave up on `POST /session`; the provider may still finish it, * and nothing here can learn that session's id — so the error names the lease diff --git a/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts b/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts index e2cd86ef8f..42a4d056ae 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts @@ -448,7 +448,12 @@ async function openCloudIosSession(daemon: ProviderScenarioHarness): Promise cloudWebDriverTestJson({ - value: { sessionId: 'wd-1', capabilities: { platformName: 'iOS' } }, + value: { + sessionId: 'wd-1', + capabilities: { platformName: 'iOS', platformVersion: '17.2' }, + }, }), 'GET /wd/hub/session/wd-1/source': () => cloudWebDriverTestJson({ value: this.source() }), 'GET /wd/hub/session/wd-1/window/rect': () => diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md index 3a5153203b..26e2d6dc47 100644 --- a/website/docs/docs/client-api.md +++ b/website/docs/docs/client-api.md @@ -64,6 +64,8 @@ This example opens an app, takes a snapshot, interacts, handles typed errors, an `client.devices.capabilities()` returns `{ device, availableCommands }`, using the same capability matrix as the CLI. Use it to check which command names the selected target supports. +`client.apps.open()` answers with the attached device under `device`, which carries `kind` (`simulator`, `emulator`, or `device`) and the `model` and `osVersion` the host or provider reported, the same fields `client.sessions.list()` reports per session. A target that reports no OS leaves `osVersion` unset; nothing infers one. + For direct app launches on local or Limrun iOS simulators, `client.apps.open({ app, platform: 'ios', launchConsole: './artifacts/app.console.log' })` captures launch-time stdout/stderr. The option mirrors `open --launch-console` and is not valid for URL opens, other provider-owned simulators, or non-simulator targets. diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index f0abcae1df..a33fee85f6 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -258,6 +258,7 @@ agent-device capabilities --session checkout --json - `devices` lists available targets after applying `--platform` and [isolation scopes](#device-isolation-scopes). - Each device carries `model` (such as `iPhone 17 Pro` or `Pixel 9`) and `osVersion` (such as `26.1` or `16`) when platform tooling reports them: `simctl` for iOS simulators, `devicectl` or `xctrace` for physical iOS devices, and `ro.product.model` and `ro.build.version.release` for running Android devices. Android emulators report the system image model, such as `sdk_gphone64_arm64`. Stopped AVDs and other platforms omit both fields. They describe a device and are not selectors. +- `open --json` and `session list --json` report the attached device the same way: `kind` (`simulator`, `emulator`, or `device`), plus `model` and `osVersion` when the host reported them, so a CI job records the OS a run used from the command result alone. A cloud provider reports `osVersion` when its session answer names the OS it granted, which can differ from the requested one. A target that reports no OS omits `osVersion`; nothing infers one. - `capabilities` lists the commands the session device, or an explicit `--platform`/`--device`/`--udid`/`--serial` target, supports. JSON output includes `device` and `availableCommands`; use `availableCommands` instead of keeping your own platform support table. Android also reports `targetReadiness.press: "bounded-geometry"` when element presses check moving targets before dispatch. Test harnesses can use that capability to delegate tap readiness instead of adding a fixed transition delay. It does not wait for the result of the tap. ### HarmonyOS command boundary @@ -1213,6 +1214,7 @@ agent-device session list --json ``` - `session list` shows active daemon sessions for your workspace, or for the named session scope when `--session` or `AGENT_DEVICE_SESSION` is set. Add `--json` for raw session metadata. +- Each session's device carries `kind`, `model` and `osVersion`, reported the way [Device discovery](#device-discovery) describes. ## Cloud provider artifacts From d85dd50df7d022ffb1e3b94b46a9d2427e98144b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 12:38:14 +0100 Subject: [PATCH 2/6] fix(open): name the session-device test for its module and accept either platformVersion key Co-Authored-By: Claude Opus 5.5 --- ...sion-device.test.ts => inventory-session-device.test.ts} | 0 packages/provider-webdriver/src/runtime-session.ts | 6 ++++-- website/docs/docs/client-api.md | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) rename packages/daemon/src/sessions/session-lifecycle/internal/__tests__/{session-inventory-session-device.test.ts => inventory-session-device.test.ts} (100%) diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-inventory-session-device.test.ts b/packages/daemon/src/sessions/session-lifecycle/internal/__tests__/inventory-session-device.test.ts similarity index 100% rename from packages/daemon/src/sessions/session-lifecycle/internal/__tests__/session-inventory-session-device.test.ts rename to packages/daemon/src/sessions/session-lifecycle/internal/__tests__/inventory-session-device.test.ts diff --git a/packages/provider-webdriver/src/runtime-session.ts b/packages/provider-webdriver/src/runtime-session.ts index 8fac268588..26c92db152 100644 --- a/packages/provider-webdriver/src/runtime-session.ts +++ b/packages/provider-webdriver/src/runtime-session.ts @@ -630,8 +630,10 @@ function deviceDescriptionFromWebDriverCapabilities( } function readCapability(capabilities: Record, key: string): string | undefined { - const value = capabilities[key] ?? capabilities[`appium:${key}`]; - return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined; + for (const value of [capabilities[key], capabilities[`appium:${key}`]]) { + if (typeof value === 'string' && value.trim().length > 0) return value.trim(); + } + return undefined; } /** diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md index 26e2d6dc47..12d4a81e6c 100644 --- a/website/docs/docs/client-api.md +++ b/website/docs/docs/client-api.md @@ -64,7 +64,7 @@ This example opens an app, takes a snapshot, interacts, handles typed errors, an `client.devices.capabilities()` returns `{ device, availableCommands }`, using the same capability matrix as the CLI. Use it to check which command names the selected target supports. -`client.apps.open()` answers with the attached device under `device`, which carries `kind` (`simulator`, `emulator`, or `device`) and the `model` and `osVersion` the host or provider reported, the same fields `client.sessions.list()` reports per session. A target that reports no OS leaves `osVersion` unset; nothing infers one. +When the daemon can name the attached host device, `client.apps.open()` answers with it under `device`. Its `kind` (`simulator`, `emulator`, or `device`), `model` and `osVersion` are each optional and present only when the host or provider reported them, the same fields `client.sessions.list()` reports per session. A target that reports no OS leaves `osVersion` unset; nothing infers one. For direct app launches on local or Limrun iOS simulators, `client.apps.open({ app, platform: 'ios', launchConsole: './artifacts/app.console.log' })` captures launch-time stdout/stderr. The option mirrors `open --launch-console` and is not valid for URL opens, other provider-owned simulators, or non-simulator targets. From d312ff5e7440239e4f78d9287915365006cfa33d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 12:43:22 +0100 Subject: [PATCH 3/6] refactor(open): build the device fields of the open result in one helper Co-Authored-By: Claude Opus 5.5 --- .../internal/session-open-surface.ts | 35 ++++++++++--------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts index 8bb18a5d46..9f74c79869 100644 --- a/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts +++ b/packages/daemon/src/sessions/session-lifecycle/internal/session-open-surface.ts @@ -66,28 +66,31 @@ export function buildOpenResult(params: { if (timing) result.timing = timing; Object.assign(result, launchConfirmation ?? {}); if (runtime && runtimeHintCount(runtime) > 0) result.runtime = runtime; - if (device) { - result.platform = publicPlatformString(device); - result.target = device.target ?? 'mobile'; - result.device = device.name; - result.id = device.id; - result.kind = device.kind; - if (device.model) result.model = device.model; - if (device.osVersion) result.osVersion = device.osVersion; - if (isSerialAddressablePlatform(device.platform)) { - result.serial = device.id; - } - } - if (device && isIosFamily(device)) { - result.device_udid = device.id; - result.ios_simulator_device_set = device.simulatorSetPath ?? null; - } + if (device) Object.assign(result, deviceResponseData(device)); return { ...result, ...successText(`Opened: ${appName ?? appBundleId ?? sessionName}`), }; } +function deviceResponseData(device: DeviceInfo): Record { + const data: Record = { + platform: publicPlatformString(device), + target: device.target ?? 'mobile', + device: device.name, + id: device.id, + kind: device.kind, + }; + if (device.model) data.model = device.model; + if (device.osVersion) data.osVersion = device.osVersion; + if (isSerialAddressablePlatform(device.platform)) data.serial = device.id; + if (isIosFamily(device)) { + data.device_udid = device.id; + data.ios_simulator_device_set = device.simulatorSetPath ?? null; + } + return data; +} + function selectionResponseData( selection: DeviceSelectionResult | undefined, ): Record { From 6cc4f6539f3fa1a09081f49290cb896790d7eb4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 12:58:11 +0100 Subject: [PATCH 4/6] docs(session): say session list prints the device fields flat "Each session's device carries kind, model and osVersion" read as a nested object, but the CLI's session entry has `device` as the device name and the three fields beside it. A caller that followed the sentence read `sessions[0].device.osVersion` and got null. Name the flat shape and where the SDK reports the same fields. Co-Authored-By: Claude Opus 5.5 --- website/docs/docs/commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index a33fee85f6..67ada2a218 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -1214,7 +1214,7 @@ agent-device session list --json ``` - `session list` shows active daemon sessions for your workspace, or for the named session scope when `--session` or `AGENT_DEVICE_SESSION` is set. Add `--json` for raw session metadata. -- Each session's device carries `kind`, `model` and `osVersion`, reported the way [Device discovery](#device-discovery) describes. +- Each session entry carries `kind`, `model` and `osVersion` beside its `platform` and `device`, reported the way [Device discovery](#device-discovery) describes. `session list --json` prints them flat: read `sessions[0].osVersion`, not `sessions[0].device.osVersion`, which is the device name. From the SDK, read them on `session.device`. ## Cloud provider artifacts From 07abb8489f4503c24e696bc2c4f7f5d40c35c0e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 13:04:47 +0100 Subject: [PATCH 5/6] docs(session): say the session-list device fields are optional The sentence read as every entry carrying kind, model and osVersion. A target that reports no OS omits osVersion, so a reader would have taken the expected omission for a broken CLI. Say each field is reported when the host reported it. Co-Authored-By: Claude Opus 5.5 --- website/docs/docs/commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 67ada2a218..c65d4c6589 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -1214,7 +1214,7 @@ agent-device session list --json ``` - `session list` shows active daemon sessions for your workspace, or for the named session scope when `--session` or `AGENT_DEVICE_SESSION` is set. Add `--json` for raw session metadata. -- Each session entry carries `kind`, `model` and `osVersion` beside its `platform` and `device`, reported the way [Device discovery](#device-discovery) describes. `session list --json` prints them flat: read `sessions[0].osVersion`, not `sessions[0].device.osVersion`, which is the device name. From the SDK, read them on `session.device`. +- A session entry reports `kind`, `model` and `osVersion` beside its `platform` and `device` when the host reported them, the way [Device discovery](#device-discovery) describes. It omits a field nothing reported, so a missing `osVersion` is expected rather than a fault. `session list --json` prints these fields flat: read `sessions[0].osVersion`, not `sessions[0].device.osVersion`, which is the device name. The SDK reports the same fields on `session.device`, and omits them the same way. ## Cloud provider artifacts From 86e63d7f5f469c7b55ff68569f165028a4030083 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 13:12:34 +0100 Subject: [PATCH 6/6] test(provider): assert the granted osVersion on the open result too Co-Authored-By: Claude Opus 5.5 --- .../provider-scenarios/cloud-webdriver-ios-text-entry.test.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts b/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts index 42a4d056ae..c850de9a9a 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts @@ -444,8 +444,9 @@ async function openCloudIosSession(daemon: ProviderScenarioHarness): Promise(open); + const opened = assertRpcOk<{ appBundleId?: string; osVersion?: string }>(open); assert.equal(opened.appBundleId, 'com.example.demo'); + assert.equal(opened.osVersion, '17.2'); // The prepared cloud session chose iOS. This must become an explicit device leaf before the // runtime facts admission; a collapsed record may not borrow support from an owner label. const [session] = await daemon.client().sessions.list();