feat(compat): runtime SDK↔backend version guard at ACP startup (#408)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: NiteshDhanpal

src/agentex/lib/core/compat/__init__.py

@@ -0,0 +1 @@
+

src/agentex/lib/core/compat/version_guard.py

@@ -0,0 +1,164 @@
+"""Runtime SDK ↔ backend contract-version guard.
+
+Complements the *build-time* cross-version compatibility tests (``tests/compat``):
+
+- **Build-time** (CI): is this *client* compatible with the window of supported server
+  contracts (``min-supported``..``current``)?
+- **Runtime** (this module): is the *server* the SDK is pointed at within that window?
+
+It runs once at ACP/worker startup, reads the backend's contract version (the version
+the server already reports via ``/openapi.json`` ``info.version``), and **fails fast with
+an actionable error** if the backend is older than this SDK supports — instead of the
+mismatch surfacing later as opaque 500s / missing-field errors deep in a request.
+
+``MIN_BACKEND_CONTRACT`` is the same source of truth as the ``min-supported`` server
+contract in ``tests/compat/server_specs/manifest.json``: the oldest agentex backend this
+SDK version supports. Bump both together when a breaking change raises the floor.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+import httpx
+
+from agentex.lib.utils.logging import make_logger
+
+logger = make_logger(__name__)
+
+# Oldest agentex backend contract this SDK is compatible with.
+# Keep in sync with the `min-supported` spec in tests/compat (#407); the version axis
+# itself comes from scale-agentex release tags (#321). Bump on a breaking SDK change.
+MIN_BACKEND_CONTRACT = "0.1.0"
+
+SKIP_ENV = "AGENTEX_SKIP_VERSION_CHECK"
+
+# Full-string SemVer. Accepts: `1.2.3`, leading `v`, surrounding whitespace, `-prerelease`
+# (captured), `+build` (ignored). Anchored at both ends so a malformed tail (`0.1.0rc1`,
+# `0.1.0.1`) is rejected → None → "unknown, proceed", not silently coerced to stable `0.1.0`.
+_VERSION_RE = re.compile(
+    r"^\s*v?(\d+)\.(\d+)\.(\d+)"  # major.minor.patch
+    r"(?:-([0-9A-Za-z.-]+))?"  # optional -prerelease (captured)
+    r"(?:\+[0-9A-Za-z.-]+)?"  # optional +build metadata (ignored)
+    r"\s*$"
+)
+
+
+class IncompatibleBackendError(RuntimeError):
+    """Raised when the agentex backend is older than this SDK's minimum supported contract."""
+
+
+def _parse(version: str | None) -> tuple[int, int, int, str | None] | None:
+    """Parse ``major.minor.patch[-prerelease]`` → ``(major, minor, patch, prerelease)``.
+
+    ``prerelease`` is the raw dot-separated identifier string (e.g. ``"rc.1"``), or None for
+    a stable release. Build metadata (after ``+``) is ignored. Returns None if unparseable.
+    """
+    m = _VERSION_RE.match(version or "")
+    if not m:
+        return None
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3)), m.group(4) or None)
+
+
+# Comparable SemVer precedence key. The 4th element keeps a uniform shape across stable and
+# prerelease so the whole tuple is orderable: (rank, identifiers), where stable rank 1 > prerelease
+# rank 0 (and the identifier list is only ever compared when both sides are prereleases, rank 0).
+_PreKey = tuple[int, int, int, tuple[int, list[tuple[int, int, str]]]]
+
+
+def _precedence_key(parsed: tuple[int, int, int, str | None]) -> _PreKey:
+    """SemVer §11 precedence key (directly comparable with ``<``).
+
+    A stable release outranks any prerelease of the same triplet (``0.1.0-rc.1 < 0.1.0``);
+    among prereleases, numeric identifiers rank below alphanumeric and compare field-by-field,
+    with a longer identifier list outranking a shorter prefix-equal one.
+    """
+    major, minor, patch, prerelease = parsed
+    if prerelease is None:
+        return (major, minor, patch, (1, []))  # stable sorts above every prerelease
+    identifiers: list[tuple[int, int, str]] = []
+    for ident in prerelease.split("."):
+        if ident.isdigit():
+            identifiers.append((0, int(ident), ""))  # numeric: lowest class, numeric order
+        else:
+            identifiers.append((1, 0, ident))  # alphanumeric: higher class, lexical order
+    return (major, minor, patch, (0, identifiers))
+
+
+def _truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+async def fetch_backend_version(base_url: str, *, timeout: float = 5.0) -> str | None:
+    """Return the backend's reported contract version (``/openapi.json`` ``info.version``), or None."""
+    url = base_url.rstrip("/") + "/openapi.json"
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(url)
+            resp.raise_for_status()
+            return (resp.json().get("info") or {}).get("version")
+    except Exception as exc:  # noqa: BLE001 - any failure → unknown, handled by caller
+        logger.warning("backend version guard: could not fetch %s (%s)", url, exc)
+        return None
+
+
+async def assert_backend_compatible(
+    base_url: str | None,
+    *,
+    min_version: str = MIN_BACKEND_CONTRACT,
+    sdk_version: str | None = None,
+) -> None:
+    """Fail fast at startup if the backend is older than ``min_version``.
+
+    No-op (warns, does not raise) when:
+      - ``AGENTEX_SKIP_VERSION_CHECK`` is set (explicit bypass),
+      - ``base_url`` is unset,
+      - the backend version can't be determined (unreachable / unparseable) — a transient
+        blip or a contract-less server shouldn't crash startup.
+
+    Raises ``IncompatibleBackendError`` only when the backend version is *known* and older
+    than ``min_version``.
+    """
+    if _truthy(SKIP_ENV):
+        logger.warning("%s set — skipping backend version guard", SKIP_ENV)
+        return
+    if not base_url:
+        return
+
+    if sdk_version is None:
+        from agentex._version import __version__ as sdk_version  # local import to avoid cycles
+
+    backend_version = await fetch_backend_version(base_url)
+    if backend_version is None:
+        logger.warning(
+            "backend version guard: could not determine backend version at %s; proceeding "
+            "(set %s=1 to silence).",
+            base_url,
+            SKIP_ENV,
+        )
+        return
+
+    backend, minimum = _parse(backend_version), _parse(min_version)
+    if backend is None or minimum is None:
+        logger.warning(
+            "backend version guard: unparseable version(s) backend=%r min=%r; proceeding.",
+            backend_version,
+            min_version,
+        )
+        return
+
+    if _precedence_key(backend) < _precedence_key(minimum):
+        raise IncompatibleBackendError(
+            f"agentex-sdk {sdk_version} requires agentex backend >= {min_version}, "
+            f"but {base_url} reports {backend_version}. "
+            f"Upgrade the backend, or pin agentex-sdk to a version compatible with backend "
+            f"{backend_version}. (Set {SKIP_ENV}=1 to bypass at your own risk.)"
+        )
+
+    logger.info(
+        "backend version guard OK: sdk=%s backend=%s (min=%s)",
+        sdk_version,
+        backend_version,
+        min_version,
+    )

src/agentex/lib/core/temporal/workers/worker.py

@@ -30,6 +30,7 @@
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.registration import register_agent
 from agentex.lib.environment_variables import EnvironmentVariables
+from agentex.lib.core.compat.version_guard import assert_backend_compatible
 
 logger = make_logger(__name__)
 
@@ -278,6 +279,10 @@ async def start_health_check_server(self):
     async def _register_agent(self):
         env_vars = EnvironmentVariables.refresh()
         if env_vars and env_vars.AGENTEX_BASE_URL:
+            # Fail fast if this worker is pointed at a backend older than the SDK supports —
+            # the worker process never goes through the ACP server lifespan, so it needs its
+            # own guard (mirrors base_acp_server.lifespan_context).
+            await assert_backend_compatible(env_vars.AGENTEX_BASE_URL)
             await register_agent(env_vars)
         else:
             logger.warning("AGENTEX_BASE_URL not set, skipping worker registration")

src/agentex/lib/sdk/fastacp/base/base_acp_server.py

@@ -33,6 +33,7 @@
 from agentex.types.task_message_update import TaskMessageUpdate, StreamTaskMessageFull
 from agentex.types.task_message_content import TaskMessageContent
 from agentex.lib.core.tracing.span_queue import shutdown_default_span_queue
+from agentex.lib.core.compat.version_guard import assert_backend_compatible
 from agentex.lib.sdk.fastacp.base.constants import (
     FASTACP_HEADER_SKIP_EXACT,
     FASTACP_HEADER_SKIP_PREFIXES,
@@ -104,6 +105,9 @@ def get_lifespan_function(self):
         async def lifespan_context(app: FastAPI):  # noqa: ARG001
             env_vars = EnvironmentVariables.refresh()
             if env_vars.AGENTEX_BASE_URL:
+                # Runtime SDK<->backend contract guard: fail fast if the backend is older
+                # than this SDK supports, instead of opaque 500s later. See compat.version_guard.
+                await assert_backend_compatible(env_vars.AGENTEX_BASE_URL)
                 await register_agent(env_vars, agent_card=self._agent_card)
                 self.agent_id = env_vars.AGENT_ID
             else:

tests/lib/core/temporal/__init__.py

@@ -0,0 +1,70 @@
+"""AgentexWorker wires the backend version guard into worker startup.
+
+A Temporal worker runs as its own process and never goes through the ACP server
+lifespan, so the guard must run inside `_register_agent` — before `register_agent`,
+and only when `AGENTEX_BASE_URL` is set.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import Mock, AsyncMock
+
+import pytest
+
+from agentex.lib.core.temporal.workers import worker as worker_mod
+from agentex.lib.core.compat.version_guard import IncompatibleBackendError
+
+
+def _worker():
+    # explicit health_check_port so __init__ doesn't read EnvironmentVariables
+    return worker_mod.AgentexWorker(task_queue="test-queue", health_check_port=8080)
+
+
+def _patch_env(monkeypatch, base_url):
+    env = Mock()
+    env.AGENTEX_BASE_URL = base_url
+    fake_cls = Mock()
+    fake_cls.refresh.return_value = env
+    monkeypatch.setattr(worker_mod, "EnvironmentVariables", fake_cls)
+    return env
+
+
+async def test_guard_runs_before_register_agent(monkeypatch):
+    env = _patch_env(monkeypatch, "http://backend")
+    order: list[str] = []
+    guard = AsyncMock(side_effect=lambda *a, **k: order.append("guard"))
+    register = AsyncMock(side_effect=lambda *a, **k: order.append("register"))
+    monkeypatch.setattr(worker_mod, "assert_backend_compatible", guard)
+    monkeypatch.setattr(worker_mod, "register_agent", register)
+
+    await _worker()._register_agent()
+
+    guard.assert_awaited_once_with("http://backend")
+    register.assert_awaited_once_with(env)
+    assert order == ["guard", "register"]  # guard must precede registration
+
+
+async def test_incompatible_backend_blocks_registration(monkeypatch):
+    _patch_env(monkeypatch, "http://backend")
+    guard = AsyncMock(side_effect=IncompatibleBackendError("backend too old"))
+    register = AsyncMock()
+    monkeypatch.setattr(worker_mod, "assert_backend_compatible", guard)
+    monkeypatch.setattr(worker_mod, "register_agent", register)
+
+    with pytest.raises(IncompatibleBackendError):
+        await _worker()._register_agent()
+
+    register.assert_not_awaited()  # fail fast — never register against an unsupported backend
+
+
+async def test_no_base_url_skips_guard_and_registration(monkeypatch):
+    _patch_env(monkeypatch, None)
+    guard = AsyncMock()
+    register = AsyncMock()
+    monkeypatch.setattr(worker_mod, "assert_backend_compatible", guard)
+    monkeypatch.setattr(worker_mod, "register_agent", register)
+
+    await _worker()._register_agent()
+
+    guard.assert_not_awaited()
+    register.assert_not_awaited()