gridfleet-testkit 0.2.1__tar.gz → 0.4.0__tar.gz

{gridfleet_testkit-0.2.1 → gridfleet_testkit-0.4.0}/.gitignore

@@ -14,6 +14,7 @@ venv/
 htmlcov/
 
 # Frontend
+node_modules/
 frontend/node_modules/
 frontend/dist/
 

gridfleet_testkit-0.4.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog — GridFleet Testkit
+
+All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
+
+## [0.4.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.3.0...gridfleet-testkit-v0.4.0) (2026-05-06)
+
+
+### Features
+
+* **testkit:** wire ?include=config,capabilities through claim/reserve and hydrate inline ([#95](https://github.com/quidow/gridfleet/issues/95)) ([20ed20d](https://github.com/quidow/gridfleet/commit/20ed20d9ee362890923146e771ad8805b45e5bfa))
+
+## [0.3.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.2.1...gridfleet-testkit-v0.3.0) (2026-05-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **testkit:** promote public api helpers ([#92](https://github.com/quidow/gridfleet/issues/92))
+
+### Features
+
+* **testkit:** add xdist recipe primitives ([#93](https://github.com/quidow/gridfleet/issues/93)) ([58fd3c3](https://github.com/quidow/gridfleet/commit/58fd3c3402ba7e735aae55e27abbe65a05c8ffe8))
+* **testkit:** promote public api helpers ([#92](https://github.com/quidow/gridfleet/issues/92)) ([80d4483](https://github.com/quidow/gridfleet/commit/80d44832903f532de3da238d020b5dc27eb8b30e))
+
+
+### Bug Fixes
+
+* **agent:** trigger release for port conflict cleanup ([6a561ca](https://github.com/quidow/gridfleet/commit/6a561ca480c62b9abb2d5141fa98fc4e1a7696b6))
+
+## [0.2.1](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.2.0...gridfleet-testkit-v0.2.1) (2026-05-03)
+
+
+### Bug Fixes
+
+* **testkit:** bound supported python metadata ([c5fff86](https://github.com/quidow/gridfleet/commit/c5fff86cbb2a4897ac571c7c5b989f0361e49743))
+
+## [0.2.0](https://github.com/quidow/gridfleet/compare/gridfleet-testkit-v0.1.0...gridfleet-testkit-v0.2.0) (2026-05-03)
+
+
+### Features
+
+* **testkit:** add run-scoped device cooldowns ([#54](https://github.com/quidow/gridfleet/issues/54)) ([6163dc9](https://github.com/quidow/gridfleet/commit/6163dc959334e933b43c20a99ad4edcbdae6c98b))
+
+
+### Bug Fixes
+
+* idempotent device release after lifecycle cleanup ([#12](https://github.com/quidow/gridfleet/issues/12)) ([7a98a5d](https://github.com/quidow/gridfleet/commit/7a98a5d18330150aab0a852f6b894d1d53de257c))
+
+## 0.1.0 — Initial Public Preview
+
+- Initial public preview of the GridFleet testkit.
+- Python pytest/Appium helper package with device reservation, capability injection, and session lifecycle fixtures.

{gridfleet_testkit-0.2.1 → gridfleet_testkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.2.1
+Version: 0.4.0
 Summary: Supported pytest and run-orchestration helpers for GridFleet integrations
 Project-URL: Homepage, https://github.com/quidow/gridfleet
 Project-URL: Repository, https://github.com/quidow/gridfleet
@@ -162,22 +162,35 @@ finally:
 
 | Helper | Purpose |
 | --- | --- |
+| `GridFleetClient.list_devices(filters)` | List devices using backend filters such as `status`, `pack_id`, `platform_id`, `host_id`, `connection_target`, and `tags.*` |
+| `GridFleetClient.get_device(device_id)` | Fetch one full device detail row by backend device id |
 | `GridFleetClient.get_device_config(connection_target, reveal=True)` | Look up a device by runtime connection target and fetch its config |
 | `GridFleetClient.get_driver_pack_catalog()` | Fetch enabled driver-pack catalog data for Appium platform selection |
 | `GridFleetClient.reserve_devices(...)` | Create a run/reservation and return the manager response |
 | `GridFleetClient.claim_device(run_id, worker_id=...)` | Claim one reserved device for a worker |
 | `GridFleetClient.claim_device_with_retry(run_id, worker_id=..., max_wait_sec=300)` | Claim one reserved device, sleeping according to server `Retry-After` responses |
 | `GridFleetClient.release_device(run_id, device_id=..., worker_id=...)` | Release a worker claim without cooldown |
+| `GridFleetClient.release_device_safe(run_id, device_id=..., worker_id=...)` | Release a worker claim and tolerate 404/409 when cleanup races with run finalization or a prior release |
 | `GridFleetClient.release_device_with_cooldown(run_id, device_id=..., worker_id=..., reason=..., ttl_seconds=...)` | Release a worker claim and keep that run from reclaiming the device until cooldown expires |
 | `GridFleetClient.signal_ready(run_id)` | Move a run to `ready` |
 | `GridFleetClient.signal_active(run_id)` | Move a run to `active` |
 | `GridFleetClient.heartbeat(run_id)` | Send a run heartbeat and read current state |
 | `GridFleetClient.report_preparation_failure(run_id, device_id, message, source="ci_preparation")` | Exclude one reserved device after setup fails |
+| `GridFleetClient.register_session(fields)` | Register a Grid/Appium session with optional requested capability metadata |
+| `GridFleetClient.register_session_from_driver(driver, fields)` | Extract session id and capabilities from an Appium driver and register the session |
+| `GridFleetClient.update_session_status(session_id, status)` | Report final session status |
 | `GridFleetClient.complete_run(run_id)` | Complete a run |
 | `GridFleetClient.cancel_run(run_id)` | Cancel a run |
 | `GridFleetClient.start_heartbeat(run_id, interval=30)` | Start a background heartbeat thread |
+| `build_error_session_payload(fields)` | Build a `/api/sessions` payload for driver-creation failures without importing pytest |
+| `hydrate_allocated_device(claim_response, run_id, client)` | Combine a claim response with optional device config and live capabilities |
+| `hydrate_allocated_device_from_driver(allocated, driver, client)` | Return a new allocated-device object with capabilities from a running driver |
 | `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` and signal cleanup that completes or cancels a run |
 
+### Worker Identity
+
+`worker_id` is an arbitrary string used for claim ownership, telemetry, and cooldown attribution. For pytest-xdist, pass `request.config.workerinput["workerid"]` from worker processes; values are normally `gw0`, `gw1`, and so on. For controller-only flows, use `"controller"` or a stable hostname. For custom schedulers, use a UUID or job-specific worker name.
+
 ### Reservation Flow
 
 ```python
@@ -247,6 +260,45 @@ else:
 
 Cooldowns are scoped to the active run. They prevent the same run from reclaiming the device until `ttl_seconds` expires, but completing or cancelling the run releases the physical device normally.
 
+For pytest-xdist controller/worker orchestration, see [Testkit xdist recipe](../docs/guides/testkit-xdist-recipe.md). The recipe is copyable guidance, not a public testkit abstraction.
+
+### Allocated Device Hydration
+
+Use `hydrate_allocated_device(claim_response, run_id=run_id, client=client)` immediately after a worker claim when a custom plugin needs a stable object instead of raw claim JSON.
+
+```python
+from gridfleet_testkit import GridFleetClient, hydrate_allocated_device
+
+client = GridFleetClient("http://manager-ip:8000/api")
+run_id = "run-123"
+claim = client.claim_device_with_retry(run_id, worker_id="gw0", max_wait_sec=300)
+allocated = hydrate_allocated_device(claim, run_id=run_id, client=client)
+
+assert allocated.device_id == claim["device_id"]
+assert allocated.platform_name in {"Android", "iOS", "tvOS", "Roku"}
+```
+
+The helper fetches static device config by default when `connection_target` is present. It fetches live capabilities only when `fetch_capabilities=True`.
+
+### Reduced HTTP round-trips on claim
+
+`gridfleet-testkit` 0.4.0 lets the manager inline the device config and live capabilities into the claim/reserve response, eliminating per-worker follow-up GETs.
+
+```python
+client = GridFleetClient()
+claim = client.claim_device(run_id, worker_id="w0", include=("config", "capabilities"))
+allocated = hydrate_allocated_device(claim, run_id=run_id, client=client)
+# zero follow-up GETs; allocated.config / allocated.live_capabilities populated inline
+```
+
+**Masking change**: inline `config` is always masked — sensitive values are replaced with `"********"`. Use `client.get_device_config(connection_target, reveal=True)` if you need raw secrets after the driver session is up. `allocated.config_is_masked` is `True` whenever the inline path was taken.
+
+`reserve_devices` accepts `include=("config",)` only — `include=("capabilities",)` raises `ReserveCapabilitiesUnsupportedError` client-side because reserve-time capabilities are not yet device-bound. Pass `include=` on the per-worker `claim_device` call instead.
+
+`include=` must be a sequence of strings (tuple or list) — order is preserved in the emitted query parameter. Passing a bare string like `include="config"` raises `TypeError` to avoid silently splitting the value into characters.
+
+`hydrate_allocated_device` accepts claim responses only. For multi-device reservations, iterate `reserve_response["devices"]`, call `claim_device` per worker, and hydrate each claim response.
+
 ## Examples
 
 Baseline screenshot examples:

{gridfleet_testkit-0.2.1 → gridfleet_testkit-0.4.0}/README.md

@@ -128,22 +128,35 @@ finally:
 
 | Helper | Purpose |
 | --- | --- |
+| `GridFleetClient.list_devices(filters)` | List devices using backend filters such as `status`, `pack_id`, `platform_id`, `host_id`, `connection_target`, and `tags.*` |
+| `GridFleetClient.get_device(device_id)` | Fetch one full device detail row by backend device id |
 | `GridFleetClient.get_device_config(connection_target, reveal=True)` | Look up a device by runtime connection target and fetch its config |
 | `GridFleetClient.get_driver_pack_catalog()` | Fetch enabled driver-pack catalog data for Appium platform selection |
 | `GridFleetClient.reserve_devices(...)` | Create a run/reservation and return the manager response |
 | `GridFleetClient.claim_device(run_id, worker_id=...)` | Claim one reserved device for a worker |
 | `GridFleetClient.claim_device_with_retry(run_id, worker_id=..., max_wait_sec=300)` | Claim one reserved device, sleeping according to server `Retry-After` responses |
 | `GridFleetClient.release_device(run_id, device_id=..., worker_id=...)` | Release a worker claim without cooldown |
+| `GridFleetClient.release_device_safe(run_id, device_id=..., worker_id=...)` | Release a worker claim and tolerate 404/409 when cleanup races with run finalization or a prior release |
 | `GridFleetClient.release_device_with_cooldown(run_id, device_id=..., worker_id=..., reason=..., ttl_seconds=...)` | Release a worker claim and keep that run from reclaiming the device until cooldown expires |
 | `GridFleetClient.signal_ready(run_id)` | Move a run to `ready` |
 | `GridFleetClient.signal_active(run_id)` | Move a run to `active` |
 | `GridFleetClient.heartbeat(run_id)` | Send a run heartbeat and read current state |
 | `GridFleetClient.report_preparation_failure(run_id, device_id, message, source="ci_preparation")` | Exclude one reserved device after setup fails |
+| `GridFleetClient.register_session(fields)` | Register a Grid/Appium session with optional requested capability metadata |
+| `GridFleetClient.register_session_from_driver(driver, fields)` | Extract session id and capabilities from an Appium driver and register the session |
+| `GridFleetClient.update_session_status(session_id, status)` | Report final session status |
 | `GridFleetClient.complete_run(run_id)` | Complete a run |
 | `GridFleetClient.cancel_run(run_id)` | Cancel a run |
 | `GridFleetClient.start_heartbeat(run_id, interval=30)` | Start a background heartbeat thread |
+| `build_error_session_payload(fields)` | Build a `/api/sessions` payload for driver-creation failures without importing pytest |
+| `hydrate_allocated_device(claim_response, run_id, client)` | Combine a claim response with optional device config and live capabilities |
+| `hydrate_allocated_device_from_driver(allocated, driver, client)` | Return a new allocated-device object with capabilities from a running driver |
 | `register_run_cleanup(client, run_id, heartbeat_thread=None)` | Register `atexit` and signal cleanup that completes or cancels a run |
 
+### Worker Identity
+
+`worker_id` is an arbitrary string used for claim ownership, telemetry, and cooldown attribution. For pytest-xdist, pass `request.config.workerinput["workerid"]` from worker processes; values are normally `gw0`, `gw1`, and so on. For controller-only flows, use `"controller"` or a stable hostname. For custom schedulers, use a UUID or job-specific worker name.
+
 ### Reservation Flow
 
 ```python
@@ -213,6 +226,45 @@ else:
 
 Cooldowns are scoped to the active run. They prevent the same run from reclaiming the device until `ttl_seconds` expires, but completing or cancelling the run releases the physical device normally.
 
+For pytest-xdist controller/worker orchestration, see [Testkit xdist recipe](../docs/guides/testkit-xdist-recipe.md). The recipe is copyable guidance, not a public testkit abstraction.
+
+### Allocated Device Hydration
+
+Use `hydrate_allocated_device(claim_response, run_id=run_id, client=client)` immediately after a worker claim when a custom plugin needs a stable object instead of raw claim JSON.
+
+```python
+from gridfleet_testkit import GridFleetClient, hydrate_allocated_device
+
+client = GridFleetClient("http://manager-ip:8000/api")
+run_id = "run-123"
+claim = client.claim_device_with_retry(run_id, worker_id="gw0", max_wait_sec=300)
+allocated = hydrate_allocated_device(claim, run_id=run_id, client=client)
+
+assert allocated.device_id == claim["device_id"]
+assert allocated.platform_name in {"Android", "iOS", "tvOS", "Roku"}
+```
+
+The helper fetches static device config by default when `connection_target` is present. It fetches live capabilities only when `fetch_capabilities=True`.
+
+### Reduced HTTP round-trips on claim
+
+`gridfleet-testkit` 0.4.0 lets the manager inline the device config and live capabilities into the claim/reserve response, eliminating per-worker follow-up GETs.
+
+```python
+client = GridFleetClient()
+claim = client.claim_device(run_id, worker_id="w0", include=("config", "capabilities"))
+allocated = hydrate_allocated_device(claim, run_id=run_id, client=client)
+# zero follow-up GETs; allocated.config / allocated.live_capabilities populated inline
+```
+
+**Masking change**: inline `config` is always masked — sensitive values are replaced with `"********"`. Use `client.get_device_config(connection_target, reveal=True)` if you need raw secrets after the driver session is up. `allocated.config_is_masked` is `True` whenever the inline path was taken.
+
+`reserve_devices` accepts `include=("config",)` only — `include=("capabilities",)` raises `ReserveCapabilitiesUnsupportedError` client-side because reserve-time capabilities are not yet device-bound. Pass `include=` on the per-worker `claim_device` call instead.
+
+`include=` must be a sequence of strings (tuple or list) — order is preserved in the emitted query parameter. Passing a bare string like `include="config"` raises `TypeError` to avoid silently splitting the value into characters.
+
+`hydrate_allocated_device` accepts claim responses only. For multi-device reservations, iterate `reserve_response["devices"]`, call `claim_device` per worker, and hydrate each claim response.
+
 ## Examples
 
 Baseline screenshot examples:

gridfleet_testkit-0.4.0/gridfleet_testkit/__init__.py

@@ -0,0 +1,71 @@
+"""Supported Python integration helpers for GridFleet.
+
+**0.4.0 masking change**: when callers opt in to inline `config` via
+`claim_device(include=("config",))`, the inline `config` payload is **always
+masked** (sensitive values are replaced with `"********"`). Code that needs raw
+secrets must continue to call `client.get_device_config(connection_target,
+reveal=True)` explicitly. `AllocatedDevice.config_is_masked` is `True` whenever
+the inline path was taken.
+
+Environment variables read by the client:
+
+- GRID_URL: Selenium Grid URL used by Appium helper defaults.
+- GRIDFLEET_API_URL: GridFleet manager API base URL.
+- GRIDFLEET_TESTKIT_USERNAME: optional Basic auth username.
+- GRIDFLEET_TESTKIT_PASSWORD: optional Basic auth password.
+
+Recipe-local run-state sharing variables are intentionally not exported from
+this package because run-state sharing is consumer policy.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .allocation import (
+    AllocatedDevice,
+    UnavailableInclude,
+    hydrate_allocated_device,
+    hydrate_allocated_device_from_driver,
+)
+from .appium import (
+    build_appium_options,
+    create_appium_driver,
+    get_connection_target_from_driver,
+    get_device_config_for_driver,
+)
+from .client import (
+    GRID_URL,
+    GRIDFLEET_API_URL,
+    GridFleetClient,
+    HeartbeatThread,
+    NoClaimableDevicesError,
+    ReserveCapabilitiesUnsupportedError,
+    UnknownIncludeError,
+    register_run_cleanup,
+)
+from .sessions import build_error_session_payload
+
+try:
+    __version__ = version("gridfleet-testkit")
+except PackageNotFoundError:
+    __version__ = "0.4.0"
+
+__all__ = [
+    "GRIDFLEET_API_URL",
+    "GRID_URL",
+    "AllocatedDevice",
+    "GridFleetClient",
+    "HeartbeatThread",
+    "NoClaimableDevicesError",
+    "ReserveCapabilitiesUnsupportedError",
+    "UnavailableInclude",
+    "UnknownIncludeError",
+    "__version__",
+    "build_appium_options",
+    "build_error_session_payload",
+    "create_appium_driver",
+    "get_connection_target_from_driver",
+    "get_device_config_for_driver",
+    "hydrate_allocated_device",
+    "hydrate_allocated_device_from_driver",
+    "register_run_cleanup",
+]

gridfleet_testkit-0.4.0/gridfleet_testkit/allocation.py

@@ -0,0 +1,196 @@
+"""Allocated-device hydration helpers for GridFleet testkit consumers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .client import GridFleetClient
+
+
+@dataclass(frozen=True)
+class UnavailableInclude:
+    """One include key the backend could not satisfy on this allocation."""
+
+    include: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class AllocatedDevice:
+    """Combined view of a claimed device, ready for driver creation."""
+
+    run_id: str
+    device_id: str
+    identity_value: str
+    name: str
+    pack_id: str
+    platform_id: str
+    platform_label: str | None
+    os_version: str | None
+    connection_target: str | None
+    host_ip: str | None
+    device_type: str
+    connection_type: str
+    manufacturer: str | None
+    model: str | None
+    claimed_by: str
+    claimed_at: str
+    config: dict[str, Any] | None
+    live_capabilities: dict[str, Any] | None
+    unavailable_includes: tuple[UnavailableInclude, ...] = ()
+    config_is_masked: bool = False
+
+    @property
+    def is_real_device(self) -> bool:
+        return self.device_type == "real_device"
+
+    @property
+    def is_simulator(self) -> bool:
+        return self.device_type in {"simulator", "emulator"}
+
+    @property
+    def udid(self) -> str | None:
+        if self.connection_target:
+            return self.connection_target
+        value = (self.live_capabilities or {}).get("appium:udid")
+        return value if isinstance(value, str) and value else None
+
+    @property
+    def device_ip(self) -> str | None:
+        """Best-effort address, preferring host IP before live device/config IP fields."""
+        if self.host_ip:
+            return self.host_ip
+        live_value = (self.live_capabilities or {}).get("appium:deviceIP")
+        if isinstance(live_value, str) and live_value:
+            return live_value
+        config_value = (self.config or {}).get("ip")
+        return config_value if isinstance(config_value, str) and config_value else None
+
+    @property
+    def platform_name(self) -> str:
+        return self.platform_label or self.platform_id
+
+
+def _string_value(payload: dict[str, Any], key: str, *, default: str | None = None) -> str:
+    value = payload.get(key, default)
+    if isinstance(value, str) and value:
+        return value
+    raise ValueError(f"Allocated device payload is missing {key}")
+
+
+def _optional_string_value(payload: dict[str, Any], key: str) -> str | None:
+    value = payload.get(key)
+    return value if isinstance(value, str) and value else None
+
+
+def _needs_device_detail(payload: dict[str, Any]) -> bool:
+    return any(payload.get(key) is None for key in ("name", "device_type", "connection_type", "manufacturer", "model"))
+
+
+def _merge_device_detail(payload: dict[str, Any], detail: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(payload)
+    for key in ("name", "device_type", "connection_type", "manufacturer", "model"):
+        if merged.get(key) is None and detail.get(key) is not None:
+            merged[key] = detail[key]
+    if merged.get("host_ip") is None and detail.get("ip_address") is not None:
+        merged["host_ip"] = detail["ip_address"]
+    return merged
+
+
+def _parse_unavailable_includes(payload: dict[str, Any]) -> tuple[UnavailableInclude, ...]:
+    raw = payload.get("unavailable_includes")
+    if not isinstance(raw, list):
+        return ()
+    parsed: list[UnavailableInclude] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            continue
+        include = entry.get("include")
+        reason = entry.get("reason")
+        if isinstance(include, str) and include and isinstance(reason, str) and reason:
+            parsed.append(UnavailableInclude(include=include, reason=reason))
+    return tuple(parsed)
+
+
+def hydrate_allocated_device(
+    claim_response: dict[str, Any],
+    *,
+    run_id: str,
+    client: GridFleetClient,
+    fetch_config: bool = True,
+    fetch_capabilities: bool = False,
+) -> AllocatedDevice:
+    """Combine a claim response with optional static config and live capabilities.
+
+    Accepts a ``ClaimResponse`` payload from ``GridFleetClient.claim_device`` only.
+    Reserve responses (``RunCreateResponse.devices`` entries before any worker
+    has claimed) lack ``claimed_by`` / ``claimed_at`` and will raise
+    ``ValueError``. Iterate ``reserve_response['devices']`` and call
+    ``claim_device`` per worker before hydrating.
+    """
+    payload = dict(claim_response)
+    device_id = _string_value(payload, "device_id")
+    if _needs_device_detail(payload):
+        payload = _merge_device_detail(payload, client.get_device(device_id))
+
+    unavailable_includes = _parse_unavailable_includes(payload)
+    unavailable_set = {entry.include for entry in unavailable_includes}
+
+    connection_target = _optional_string_value(payload, "connection_target")
+    inline_config = payload.get("config")
+    if isinstance(inline_config, dict):
+        config: dict[str, Any] | None = inline_config
+        config_is_masked = True
+    elif fetch_config and connection_target and "config" not in unavailable_set:
+        config = client.get_device_config(connection_target)
+        config_is_masked = False
+    else:
+        config = None
+        config_is_masked = False
+    inline_capabilities = payload.get("live_capabilities")
+    if isinstance(inline_capabilities, dict):
+        live_capabilities: dict[str, Any] | None = inline_capabilities
+    elif fetch_capabilities and "capabilities" not in unavailable_set:
+        live_capabilities = client.get_device_capabilities(device_id)
+    else:
+        live_capabilities = None
+
+    return AllocatedDevice(
+        run_id=run_id,
+        device_id=device_id,
+        identity_value=_string_value(payload, "identity_value"),
+        name=_string_value(payload, "name", default=device_id),
+        pack_id=_string_value(payload, "pack_id"),
+        platform_id=_string_value(payload, "platform_id"),
+        platform_label=_optional_string_value(payload, "platform_label"),
+        os_version=_optional_string_value(payload, "os_version"),
+        connection_target=connection_target,
+        host_ip=_optional_string_value(payload, "host_ip"),
+        device_type=_string_value(payload, "device_type"),
+        connection_type=_string_value(payload, "connection_type"),
+        manufacturer=_optional_string_value(payload, "manufacturer"),
+        model=_optional_string_value(payload, "model"),
+        claimed_by=_string_value(payload, "claimed_by"),
+        claimed_at=_string_value(payload, "claimed_at"),
+        config=config,
+        config_is_masked=config_is_masked,
+        live_capabilities=live_capabilities,
+        unavailable_includes=unavailable_includes,
+    )
+
+
+def hydrate_allocated_device_from_driver(
+    allocated: AllocatedDevice,
+    driver: Any,
+    *,
+    client: GridFleetClient,
+) -> AllocatedDevice:
+    """Refresh live capabilities from a running Appium driver session."""
+    capabilities = getattr(driver, "capabilities", None)
+    if isinstance(capabilities, dict):
+        live_capabilities = dict(capabilities)
+    else:
+        live_capabilities = client.get_device_capabilities(allocated.device_id)
+    return replace(allocated, live_capabilities=live_capabilities)