feat(sdk): add webhook helper for forward-route handlers

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 64
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-dfcee301cded58822f489f034b6fcd42f392df406ca3780e7213698cec59c777.yml
-openapi_spec_hash: 3aae4790b24edf6ea9469c1680d513ae
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/sgp/agentex-sdk-cd43ba4b554ca024dd7ee7b74e4f4700a743282c17def704a0967e6ff251c09b.yml
+openapi_spec_hash: 9369ccc9c0289e9d6f641a526d244d1c
 config_hash: 138b7c0b394e7393133c8ff16a6d0eb3

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: