feat: add runtime server version compatibility check at worker registration

Added automatic server version validation when workers start:

**Client (client.py):**
- New method: get_cluster_info() fetches server version from GET /api/cluster/info
- Returns server version, capabilities, and supported SDK versions

**Worker (worker.py):**
- _register() now checks server version before registering worker
- Validates server major version is 0 (prerelease) or 2+ (stable)
- SDK 0.1.x compatible with server 0.x and 2.x
- Raises clear error if incompatible: "Server version X is incompatible with sdk-python 0.1.x"
- Logs warning and continues if version check fails (non-fatal)

**README:**
- Added Compatibility section documenting server 0.x and 2.x support
- Notes automatic version checking at startup

Prevents cryptic protocol errors when SDK paired with incompatible server.
Workers now fail fast with actionable version mismatch messages.

Fixes #257

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: durable-workflow-ops

README.md

@@ -75,6 +75,14 @@ Full documentation is available at [durable-workflow.github.io/docs/2.0/sdks/pyt
 - Python ≥ 3.10
 - A running [Durable Workflow server](https://github.com/durable-workflow/server)
 
+## Compatibility
+
+SDK version 0.1.x is compatible with:
+- **Server 0.x** (development/prerelease versions 0.1.0 through 0.1.9+)
+- **Server 2.x** (stable release versions 2.0.0+)
+
+The worker automatically checks server version at startup and raises a clear error if incompatible.
+
 ## Development
 
 ```bash

src/durable_workflow/client.py

@@ -299,6 +299,10 @@ async def _do_request() -> httpx.Response:
             return None
         return resp.json()
 
+    async def get_cluster_info(self) -> dict[str, Any]:
+        """Fetch server version and capabilities from /api/cluster/info."""
+        return await self._request("GET", "/cluster/info", worker=False, context="get_cluster_info")
+
     def get_workflow_handle(
         self, workflow_id: str, *, run_id: str | None = None, workflow_type: str = ""
     ) -> WorkflowHandle:

src/durable_workflow/worker.py

@@ -52,6 +52,33 @@ def __init__(
         self._in_flight: set[asyncio.Task[Any]] = set()
 
     async def _register(self) -> None:
+        # Check server version compatibility
+        try:
+            info = await self.client.get_cluster_info()
+            server_version = info.get("version", "unknown")
+
+            # Parse major version (e.g., "0.1.9" -> 0, "2.0.0" -> 2)
+            try:
+                major = int(server_version.split(".")[0])
+            except (ValueError, IndexError):
+                log.warning("unable to parse server version %r; skipping compatibility check", server_version)
+                major = None
+
+            # Require server major version 0 or 2+ (0.x is pre-release, 2.x is stable)
+            # SDK 0.1.x is compatible with server 0.1.x and 2.x
+            if major is not None and major not in (0, 2):
+                raise RuntimeError(
+                    f"Server version {server_version} is incompatible with sdk-python 0.1.x "
+                    f"(requires server 0.x or 2.x). "
+                    f"Upgrade the server or use a compatible SDK version."
+                )
+
+            log.debug("server version %s is compatible", server_version)
+        except Exception as e:
+            if isinstance(e, RuntimeError) and "incompatible" in str(e):
+                raise
+            log.warning("failed to check server version compatibility: %s", e)
+
         await self.client.register_worker(
             worker_id=self.worker_id,
             task_queue=self.task_queue,