fix(packaging): guard agentex-client skew, bump floor, smoke-test wheel install

Harden the 0.13.0 split (agentex-sdk + agentex-client share the agentex.*
namespace) against the partial-install/skew break:

- Bump the agentex-client floor to >=0.13.0 (first release where it ships
  separately) so an old client can't satisfy the dep. Kept floor-only: a
  ceiling would exclude the co-versioned slim (release-please can't bump it).
- Sync uv.lock to the 0.13.0 workspace versions (it lagged pyproject at 0.12.0)
  so frozen installs resolve a client that satisfies the new floor.
- Add an import-time guard (agentex.lib) that raises a clear, actionable error
  when the installed agentex-client/agentex-sdk versions are skewed, or the
  client REST surface is incomplete (canary import) — instead of a cryptic
  `cannot import name 'Event' from 'agentex.types'`. Catches skews the floor pin
  can't (frozen locks, --no-deps, pre-built images). It can't preempt a fully
  missing client surface (import agentex fails in the client's own __init__
  first) — the wheel smoke covers that.
- Add scripts/check-wheel-install (wired into the build CI job): builds both
  wheels, installs them together into a fresh venv, and imports agentex.lib.adk
  plus the agentex.types/resources client surface — catching a wheel that ships
  an incomplete agentex.* namespace.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: max-parke-scale

.github/workflows/ci.yml

@@ -61,6 +61,10 @@ jobs:
         # force-include can't build via the sdist-then-wheel default.
         run: uv build --all-packages --wheel
 
+      - name: Smoke-test wheel install
+        # Both wheels must install together into one working agentex.* namespace.
+        run: ./scripts/check-wheel-install
+
       - name: Get GitHub OIDC Token
         if: |-
           github.repository == 'stainless-sdks/agentex-sdk-python' &&

adk/pyproject.toml

@@ -15,7 +15,7 @@ readme = "README.md"
 dependencies = [
     # Co-released in lockstep; floor-only by design — a ceiling would
     # eventually exclude the co-versioned slim (release-please can't bump it).
-    "agentex-client>=0.12.0",
+    "agentex-client>=0.13.0",
     # CLI surface (agentex.lib.cli.*, agentex.lib.sdk.config.*)
     "typer>=0.16,<0.17",
     "questionary>=2.0.1,<3",

scripts/check-wheel-install

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Smoke: agentex-client + agentex-sdk must install together into one working
+# agentex.* namespace. Builds + installs in a clean temp dir to avoid stale dist/.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+work="$(mktemp -d)"
+echo "==> building both wheels into $work/dist"
+uv build --all-packages --wheel --out-dir "$work/dist"
+
+venv="$work/venv"
+uv venv "$venv" >/dev/null
+echo "==> installing both wheels into a fresh venv"
+uv pip install --python "$venv" "$work"/dist/agentex_client-*.whl "$work"/dist/agentex_sdk-*.whl
+
+echo "==> importing the merged namespace from the installed wheels"
+"$venv/bin/python" - <<'PY'
+import agentex.lib.adk  # ADK overlay — ships in agentex-sdk
+from agentex.types import Event  # client surface — ships in agentex-client
+from agentex.resources import states  # client surface that "didn't land" in the incident
+
+print("agentex namespace OK:", Event.__name__, states.__name__)
+PY

src/agentex/lib/__init__.py

@@ -0,0 +1,4 @@
+from agentex.lib._version_guard import verify_client_compatibility
+
+# Fail fast + clearly on a skewed/incomplete agentex-client install.
+verify_client_compatibility()

src/agentex/lib/_version_guard.py

@@ -0,0 +1,37 @@
+"""Fail fast with a clear error on a skewed/incomplete agentex-client install
+instead of a cryptic `cannot import name ... from agentex.types`."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def _installed(package: str) -> str | None:
+    try:
+        return version(package)
+    except PackageNotFoundError:
+        return None
+
+
+def verify_client_compatibility() -> None:
+    sdk, client = _installed("agentex-sdk"), _installed("agentex-client")
+
+    # Published in lockstep — a version mismatch means a skewed client (floor
+    # pins can be bypassed by frozen locks, --no-deps, or pre-built images).
+    if sdk and client and sdk != client:
+        raise ImportError(
+            f"agentex-sdk {sdk} requires the co-released agentex-client {sdk}, but "
+            f"agentex-client {client} is installed — reinstall both at the same "
+            f"version (`pip install --force-reinstall agentex-sdk`)."
+        )
+
+    # Surface canary: a partial install can leave the client REST surface
+    # incomplete even when versions match. `Event` went missing in the incident.
+    try:
+        from agentex.types import Event as _Event  # noqa: F401
+    except (ImportError, AttributeError) as exc:
+        raise ImportError(
+            f"agentex-sdk could not import the agentex-client REST surface "
+            f"(agentex-sdk={sdk or '?'}, agentex-client={client or '?'}) — reinstall "
+            f"both at the same version (`pip install --force-reinstall agentex-sdk`)."
+        ) from exc

tests/lib/test_version_guard.py

@@ -0,0 +1,28 @@
+"""Tests for the agentex-client compatibility guard (0.13.0 split regression)."""
+
+from __future__ import annotations
+
+import pytest
+
+import agentex.lib._version_guard as guard
+
+
+def test_passes_when_versions_match_and_surface_present() -> None:
+    guard.verify_client_compatibility()  # workspace: both members at the same version
+
+
+def test_raises_on_version_skew(monkeypatch: pytest.MonkeyPatch) -> None:
+    versions = {"agentex-sdk": "0.13.0", "agentex-client": "0.12.0"}
+    monkeypatch.setattr(guard, "version", lambda pkg: versions[pkg])
+    with pytest.raises(ImportError, match="agentex-client 0.12.0 is installed"):
+        guard.verify_client_compatibility()
+
+
+def test_raises_when_client_surface_incomplete(monkeypatch: pytest.MonkeyPatch) -> None:
+    import agentex.types
+
+    # Versions match, but the canary symbol is gone — a partial/incomplete surface.
+    monkeypatch.setattr(guard, "version", lambda pkg: "0.13.0")
+    monkeypatch.delattr(agentex.types, "Event", raising=False)
+    with pytest.raises(ImportError, match="could not import the agentex-client REST surface"):
+        guard.verify_client_compatibility()