test(compat): validate ADK requests against a window of server contracts

Generalizes the #405 regression guard. Captures the requests the ADK emits
(states.create/update for v1) and validates each against a window of supported
server OpenAPI contracts vendored under tests/compat/server_specs/: `current`
(scale-agentex main) and `min-supported` (pre-#278, which still requires
task_id/agent_id in the state body).

Catches the 0.13.0 class of break — a client that drops a field an older
deployed server still requires. Verified: with the field-drop, states.update
fails "task_id/agent_id required" against min-supported while passing current.

Specs are vendored for deterministic CI (no network); refresh_specs.py re-pulls
them at the SHAs in manifest.json. Advance min-supported as the oldest deployed
server moves forward; extend _OPERATIONS for more ADK operations.

Stacked on #405 (needs the extra_body fix so states.update passes).

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

Author: max-parke-scale

tests/compat/__init__.py

@@ -0,0 +1,34 @@
+"""Re-vendor the server OpenAPI specs at the SHAs pinned in manifest.json.
+Usage: `python tests/compat/refresh_specs.py` (needs `gh` auth for the source repo)."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+_DIR = Path(__file__).parent / "server_specs"
+
+
+def main() -> None:
+    manifest = json.loads((_DIR / "manifest.json").read_text())
+    repo, path = manifest["source_repo"], manifest["source_path"]
+    for entry in manifest["specs"]:
+        content = subprocess.run(
+            [
+                "gh",
+                "api",
+                f"repos/{repo}/contents/{path}?ref={entry['sha']}",
+                "-H",
+                "Accept: application/vnd.github.raw",
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout
+        (_DIR / entry["file"]).write_text(content)
+        print(f"wrote {entry['file']} from {repo}@{entry['sha'][:12]}")
+
+
+if __name__ == "__main__":
+    main()