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

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

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

{gridfleet_testkit-0.2.1 → gridfleet_testkit-0.3.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the GridFleet testkit (`gridfleet-testkit` on PyPI) are documented here.
 
+## [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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gridfleet-testkit
-Version: 0.2.1
+Version: 0.3.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,26 @@ 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`.
+
 ## Examples
 
 Baseline screenshot examples:

{gridfleet_testkit-0.2.1 → gridfleet_testkit-0.3.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,26 @@ 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`.
+
 ## Examples
 
 Baseline screenshot examples:

gridfleet_testkit-0.3.0/gridfleet_testkit/__init__.py

@@ -0,0 +1,54 @@
+"""Supported Python integration helpers for GridFleet.
+
+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, 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,
+    register_run_cleanup,
+)
+from .sessions import build_error_session_payload
+
+try:
+    __version__ = version("gridfleet-testkit")
+except PackageNotFoundError:
+    __version__ = "0.3.0"
+
+__all__ = [
+    "GRIDFLEET_API_URL",
+    "GRID_URL",
+    "AllocatedDevice",
+    "GridFleetClient",
+    "HeartbeatThread",
+    "NoClaimableDevicesError",
+    "__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.3.0/gridfleet_testkit/allocation.py

@@ -0,0 +1,144 @@
+"""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 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
+
+    @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 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."""
+    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))
+
+    connection_target = _optional_string_value(payload, "connection_target")
+    config = client.get_device_config(connection_target) if fetch_config and connection_target else None
+    live_capabilities = client.get_device_capabilities(device_id) if fetch_capabilities else 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,
+        live_capabilities=live_capabilities,
+    )
+
+
+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)

{gridfleet_testkit-0.2.1 → gridfleet_testkit-0.3.0}/gridfleet_testkit/client.py

@@ -38,14 +38,16 @@ class NoClaimableDevicesError(RuntimeError):
         message: str,
         *,
         retry_after_sec: int,
+        run_id: str = "",
         next_available_at: str | None = None,
     ) -> None:
+        self.run_id = run_id
         self.retry_after_sec = retry_after_sec
         self.next_available_at = next_available_at
         super().__init__(message)
 
 
-def _raise_for_status(resp: Any) -> None:
+def _raise_for_status(resp: Any, *, run_id: str) -> None:
     if resp.status_code == 409:
         try:
             payload = resp.json()
@@ -61,12 +63,40 @@ def _raise_for_status(resp: Any) -> None:
                 next_available_at = details.get("next_available_at")
                 raise NoClaimableDevicesError(
                     str(error.get("message") or "No unclaimed devices available in this run"),
+                    run_id=run_id,
                     retry_after_sec=retry_after,
                     next_available_at=next_available_at if isinstance(next_available_at, str) else None,
                 )
     resp.raise_for_status()
 
 
+def _is_safe_release_conflict(resp: Any) -> bool:
+    try:
+        payload = resp.json()
+    except Exception:
+        return False
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    return isinstance(detail, str) and "is not claimed" in detail.lower()
+
+
+def _query_params(values: dict[str, Any]) -> list[tuple[str, str | int | float | bool | None]]:
+    params: list[tuple[str, str | int | float | bool | None]] = []
+    for key, value in values.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            params.append((key, str(value).lower()))
+        else:
+            params.append((key, str(value)))
+    return params
+
+
+def _raise_or_warn(operation: str, suppress_errors: bool, exc: Exception) -> None:
+    if not suppress_errors:
+        raise exc
+    logger.warning("Failed to %s with GridFleet: %s", operation, exc)
+
+
 class HeartbeatThread(threading.Thread):
     """Background thread that sends periodic heartbeat pings for an active test run."""
 
@@ -115,6 +145,66 @@ class GridFleetClient:
         self.base_url = base_url.rstrip("/")
         self._auth = auth if auth is not None else _default_auth()
 
+    def list_devices(
+        self,
+        *,
+        pack_id: str | None = None,
+        platform_id: str | None = None,
+        status: str | None = None,
+        host_id: str | None = None,
+        identity_value: str | None = None,
+        connection_target: str | None = None,
+        device_type: str | None = None,
+        connection_type: str | None = None,
+        os_version: str | None = None,
+        search: str | None = None,
+        hardware_health_status: str | None = None,
+        hardware_telemetry_state: str | None = None,
+        needs_attention: bool | None = None,
+        tags: dict[str, str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """List devices with backend filter passthrough."""
+        params = _query_params(
+            {
+                "pack_id": pack_id,
+                "platform_id": platform_id,
+                "status": status,
+                "host_id": host_id,
+                "identity_value": identity_value,
+                "connection_target": connection_target,
+                "device_type": device_type,
+                "connection_type": connection_type,
+                "os_version": os_version,
+                "search": search,
+                "hardware_health_status": hardware_health_status,
+                "hardware_telemetry_state": hardware_telemetry_state,
+                "needs_attention": needs_attention,
+            }
+        )
+        if tags:
+            params.extend((f"tags.{key}", value) for key, value in tags.items())
+        resp = httpx.get(
+            f"{self.base_url}/devices",
+            params=params,
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        payload = resp.json()
+        if isinstance(payload, dict) and isinstance(payload.get("items"), list):
+            return cast("list[dict[str, Any]]", payload["items"])
+        return cast("list[dict[str, Any]]", payload)
+
+    def get_device(self, device_id: str) -> dict[str, Any]:
+        """Fetch one device detail row by backend device id."""
+        resp = httpx.get(
+            f"{self.base_url}/devices/{device_id}",
+            timeout=10,
+            auth=self._auth,
+        )
+        resp.raise_for_status()
+        return cast("dict[str, Any]", resp.json())
+
     def get_device_config(self, connection_target: str, reveal: bool = True) -> dict[str, Any]:
         """Fetch device config by looking up the current runtime connection target."""
         resp = httpx.get(
@@ -211,7 +301,7 @@ class GridFleetClient:
             timeout=10,
             auth=self._auth,
         )
-        _raise_for_status(resp)
+        _raise_for_status(resp, run_id=run_id)
         return cast("dict[str, Any]", resp.json())
 
     def release_device(self, run_id: str, *, device_id: str, worker_id: str) -> None:
@@ -223,6 +313,24 @@ class GridFleetClient:
         )
         resp.raise_for_status()
 
+    def release_device_safe(self, run_id: str, *, device_id: str, worker_id: str) -> bool:
+        """Release a claim while tolerating already-terminal run/device states.
+
+        Returns True when the manager accepts the release, False when the run is
+        gone or the claim is explicitly already unclaimed. Other HTTP errors,
+        including wrong-worker conflicts, still raise.
+        """
+        resp = httpx.post(
+            f"{self.base_url}/runs/{run_id}/release",
+            json={"device_id": device_id, "worker_id": worker_id},
+            timeout=10,
+            auth=self._auth,
+        )
+        if resp.status_code == 404 or (resp.status_code == 409 and _is_safe_release_conflict(resp)):
+            return False
+        resp.raise_for_status()
+        return True
+
     def release_device_with_cooldown(
         self,
         run_id: str,
@@ -274,6 +382,100 @@ class GridFleetClient:
         resp.raise_for_status()
         return cast("dict[str, Any]", resp.json())
 
+    def register_session(
+        self,
+        *,
+        session_id: str,
+        test_name: str | None = None,
+        device_id: str | None = None,
+        connection_target: str | None = None,
+        status: str = "running",
+        requested_pack_id: str | None = None,
+        requested_platform_id: str | None = None,
+        requested_device_type: str | None = None,
+        requested_connection_type: str | None = None,
+        requested_capabilities: dict[str, Any] | None = None,
+        error_type: str | None = None,
+        error_message: str | None = None,
+        run_id: str | None = None,
+        suppress_errors: bool = True,
+    ) -> dict[str, Any] | None:
+        """Register a Grid/Appium session with the manager."""
+        try:
+            resp = httpx.post(
+                f"{self.base_url}/sessions",
+                json={
+                    "session_id": session_id,
+                    "test_name": test_name,
+                    "device_id": device_id,
+                    "connection_target": connection_target,
+                    "status": status,
+                    "requested_pack_id": requested_pack_id,
+                    "requested_platform_id": requested_platform_id,
+                    "requested_device_type": requested_device_type,
+                    "requested_connection_type": requested_connection_type,
+                    "requested_capabilities": requested_capabilities,
+                    "error_type": error_type,
+                    "error_message": error_message,
+                    "run_id": run_id,
+                },
+                timeout=5,
+                auth=self._auth,
+            )
+            resp.raise_for_status()
+        except (httpx.HTTPError, TypeError, ValueError) as exc:
+            _raise_or_warn("register session", suppress_errors, exc)
+            return None
+        return cast("dict[str, Any]", resp.json())
+
+    def update_session_status(
+        self,
+        session_id: str,
+        status: str,
+        *,
+        suppress_errors: bool = True,
+    ) -> dict[str, Any] | None:
+        """Update a registered session status."""
+        try:
+            resp = httpx.patch(
+                f"{self.base_url}/sessions/{session_id}/status",
+                json={"status": status},
+                timeout=5,
+                auth=self._auth,
+            )
+            resp.raise_for_status()
+        except (httpx.HTTPError, TypeError, ValueError) as exc:
+            _raise_or_warn("report session status", suppress_errors, exc)
+            return None
+        return cast("dict[str, Any]", resp.json())
+
+    def register_session_from_driver(
+        self,
+        driver: Any,
+        *,
+        test_name: str | None = None,
+        run_id: str | None = None,
+        suppress_errors: bool = True,
+    ) -> dict[str, Any] | None:
+        """Extract session metadata from an Appium driver and register it."""
+        capabilities = getattr(driver, "capabilities", {})
+        if not isinstance(capabilities, dict):
+            capabilities = {}
+        session_id = getattr(driver, "session_id", None)
+        if not isinstance(session_id, str) or not session_id:
+            raise RuntimeError("Created Appium driver did not expose a session ID")
+        device_id = capabilities.get("appium:gridfleet:deviceId") or capabilities.get("gridfleet:deviceId")
+        connection_target = capabilities.get("appium:udid") or capabilities.get("appium:deviceName")
+        return self.register_session(
+            session_id=session_id,
+            test_name=test_name,
+            device_id=device_id if isinstance(device_id, str) and device_id else None,
+            connection_target=connection_target if isinstance(connection_target, str) and connection_target else None,
+            requested_capabilities=capabilities,
+            run_id=run_id,
+            suppress_errors=suppress_errors,
+        )
+
     def complete_run(self, run_id: str) -> None:
         httpx.post(
             f"{self.base_url}/runs/{run_id}/complete",