feat(adk): warn when the agentex server reports an unsupported version

[max-parke-scale]

What

The ADK warns once, loudly, when the agentex server it's talking to reports a contract version older than the SDK supports — the runtime complement to the build-time compat suite (#407). It reads the server's X-Agentex-Version response header and compares to MIN_SUPPORTED_SERVER_VERSION.

Why

#407 validates the client's requests against the supported-server window at build time; it can't see a deployment pointed at a server below the floor — the 0.13.0 failure mode (a current client against an older deployed server). This catches that at runtime.

How

• agentex/lib/_server_compat.py: parse + compare + warn once per process; AGENTEX_STRICT_SERVER_VERSION=1 raises instead. No-op when the header is absent or unparseable (servers predating the header can't be identified — silent by design).
• Installed as an httpx response event-hook in the ADK client factory create_async_agentex_client (hand-authored, preserved across Stainless codegen — deliberately not the generated _base_client.py).

Coverage / scope

Covers the ADK path — how agents build their client, i.e. the incident path. The bare slim client used by REST-only consumers isn't covered, because that would mean editing the Stainless-generated base client; bare-client coverage is a follow-up (needs a Stainless-supported hook).

Status

Dormant until servers emit the header — that's scaleapi/scale-agentex#321 (release pipeline + version) plus a small middleware to set X-Agentex-Version (a follow-up PR stacked on #321). The check tolerates the absent header (silent), so this is safe to merge now. MIN_SUPPORTED_SERVER_VERSION starts permissive (0.1.0) and is kept in sync with #407's min-supported.

Test

tests/lib/adk/test_server_compat.py: below-floor → warns once; at/above → silent; absent/unparseable → silent; strict → raises; factory installs the hook; the installed hook checks the header. ruff, pyright, and an import agentex.lib.adk smoke pass.

Implements AGX1-367.

🧑‍💻🤖 — posted via Claude Code

[dm36]

Shape is right — warn-once + strict-env escape hatch + no-op on absent header is exactly the cardinality you want when the header rides every response. Two substantive things worth flagging:

1. _parse() silently drops prerelease-tagged servers. 2.10.0-rc → int("0-rc") fails → returns None → silent no-op. That's the exact version Cengage was running. Not a regression-vs-incident (since the floor is currently 0.1.0 permissive), but the eventual floor bump won't catch prerelease servers because they always parse-fail. Worth splitting on - before . ('2.10.0-rc'.split('-')[0] → '2.10.0') so the prerelease tag becomes equivalent to the release version for comparison purposes.

2. Sync Agentex client isn't covered. PR body acknowledges this as intentional (ADK is the incident path), and the comment in install_on says async-only — worth one line in the module docstring confirming this is the contract, so the next contributor doesn't try to use it on a sync client and wonder why nothing fires.

Other small note for the merge queue: floor stays at 0.1.0 until scale-agentex#321 + the header middleware land, so this PR is dormant on merge — fine, but MIN_SUPPORTED_SERVER_VERSION will need a coordinated bump with #407's min-supported whenever the actual support window narrows.

[max-parke-scale]

Closing in favor of #408, which implements the same runtime SDK↔backend version guard (AGX1-367) more cleanly: it reads the backend's /openapi.json info.version (self-describing via scaleapi/scale-agentex#321), so it needs no server-side change, and it fails fast at ACP startup rather than warning per-response. Consolidating onto #408 per discussion.

🧑‍💻🤖 — posted via Claude Code