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

[max-parke-scale]

What

Hardens the 0.13.0 split (agentex-sdk + agentex-client share the agentex.* namespace), four ways:

1. Floor bump — agentex-client>=0.13.0 (first release where it ships separately). Floor-only (no == ceiling: release-please can't bump it).
2. Lock sync — uv.lock lagged pyproject at 0.12.0; synced to 0.13.0 so frozen installs resolve a client that satisfies the floor.
3. Import-time guard (agentex.lib) — canaries the agentex-client REST surface and raises a clear, actionable ImportError if a symbol/resource the ADK needs is absent, instead of a cryptic cannot import name 'Event' from 'agentex.types'. It does not gate on version — newer clients are additive and pass; versions are reported in the message for diagnosis only.
4. Wheel-install smoke (scripts/check-wheel-install, wired into the build CI job) — builds both wheels, installs them together into a fresh venv, imports agentex.lib.adk + the agentex.types/resources surface.

Guard scope (honest)

Catches an incomplete client surface (a needed symbol/resource missing) — the incident's failure — regardless of version direction. Newer clients are not rejected (by design: clients are additive; removals aren't planned).

Does not catch a fully missing client surface: import agentex fails in the client's own __init__ (eager from . import types) before agentex.lib runs. The wheel smoke covers that at the build layer — so guard + smoke are complementary.

Tests

tests/lib/test_version_guard.py: passes with the full surface; passes for a newer client (version is not a gate); raises on a missing canary symbol. Wheel smoke verified locally (positive + sdk-only --no-deps teeth check). ruff/pyright clean.

Notes

Issue #2 of 3 from the 0.13.0 incident; ships in 0.13.1 (#405 + #407 merged). Route-doubling (#3) is on a separate investigation.

🧑‍💻🤖 — posted via Claude Code

Greptile Summary

• Raises the ADK dependency floor to agentex-client>=0.13.0 and syncs the lockfile metadata.
• Adds an import-time compatibility guard for agentex-client version skew and missing generated surface.
• Adds guard unit tests plus a CI wheel-install smoke test that builds and imports the split packages together.

Confidence Score: 5/5

The changes are narrowly scoped to packaging metadata, an import compatibility guard, and CI smoke coverage for the split package install path.

No code issues were identified in the reviewed changes, and the added tests directly cover the intended version-skew and missing-surface behaviors.

T-Rex Logs

What T-Rex did

• Ran the dependency floor checks to verify packaging metadata and resolver behavior across before and after states.
• Assessed the agentex import guard scenario when Event and states are missing, observed an ImportError, and later confirmed a complete surface run reported SUCCESS.
• Executed a wheel smoke test in CI to validate wheel builds and import readiness, resulting in successful builds for agentex_client-0.13.0 and agentex_sdk-0.13.0, a fresh venv install, and a final import that confirms the Event namespace OK.

_{Ran code and verified through T-Rex}

_{Reviews (7): Last reviewed commit: "fix(packaging): guard agentex-client sur..." | Re-trigger Greptile}

[dm36]

agentex-sdk==0.13.0 already declares agentex-client>=0.12.0 on PyPI, so the Cengage break must've hit a more subtle path (resolver race, stale cache, or partial-lockfile sync) rather than a missing dep. This guard is the right shape for that — converts a cryptic ImportError into an actionable, version-stamped error. +1.

One small thing: pair the raise with a logger.error so APM picks it up even if a customer's outer try/except swallows the ImportError.

[greptile-apps]

Update the lockfile

This PR raises the ADK dependency to agentex-client>=0.13.0, but uv.lock still records the workspace packages as 0.12.0 and the ADK lock metadata still has only the editable agentex-client dependency without this floor. A frozen or locked install can keep resolving the stale 0.12.0 metadata, so tests and local installs may not exercise the package contract this change is meant to enforce. Please regenerate uv.lock so it records the 0.13.0 package versions and updated ADK dependency floor.

Artifacts

Repro: TOML metadata inspection script

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Repro: lock inspection output showing stale package versions and missing dependency floor

• Keeps the command output available without making the summary code-heavy.

Repro: uv lock check attempt showing uv unavailable

• Keeps the command output available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: adk/pyproject.toml
Line: 18

Comment:
**Update the lockfile**

This PR raises the ADK dependency to `agentex-client>=0.13.0`, but `uv.lock` still records the workspace packages as `0.12.0` and the ADK lock metadata still has only the editable `agentex-client` dependency without this floor. A frozen or locked install can keep resolving the stale 0.12.0 metadata, so tests and local installs may not exercise the package contract this change is meant to enforce. Please regenerate `uv.lock` so it records the 0.13.0 package versions and updated ADK dependency floor.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[max-parke-scale]

Lockfile is now updated.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​agentex-sdk@​0.12.0 ⏵ 0.13.0	+5
	pypi/​agentex-client@​0.12.0 ⏵ 0.13.0	+1

View full report

[max-parke-scale]

agentex-sdk==0.13.0 already declares agentex-client>=0.12.0 on PyPI, so the Cengage break must've hit a more subtle path (resolver race, stale cache, or partial-lockfile sync) rather than a missing dep. This guard is the right shape for that — converts a cryptic ImportError into an actionable, version-stamped error. +1.

One small thing: pair the raise with a logger.error so APM picks it up even if a customer's outer try/except swallows the ImportError.

We actually needed client@0.13.0. Looking into the logger.

[dm36]

Correction on my comment above — re-read the diff more carefully and the adk/pyproject.toml change is doing more than I gave it credit for. The three pieces together close bug #2:

1. Floor bump (agentex-client>=0.12.0 → >=0.13.0) — this is the primary fix. Cengage hit agentex-sdk==0.13.0 paired with stale agentex-client==0.12.0 from cache or lockfile; the old floor allowed that combo, the new one blocks it.
2. Runtime guard — backstop for anything that still gets past pip (corrupted cache, manual downgrade). Cryptic ImportError → version-stamped actionable error.
3. scripts/check-wheel-install — pre-publish smoke that builds both wheels into a fresh venv and verifies the agentex.* namespace works. Regression-test layer.

The logger.error suggestion from my earlier comment still stands as an APM-visibility add, but the framing of "this only converts a cryptic error" understated the actual install-correctness fix.

[dm36]

approving looks like a couple of greptile comments

[max-parke-scale]

Re: pairing the guard's raise with a logger.error so APM catches it even if a caller swallows the ImportError —

Good instinct on observability, but I left the raise without a paired logger.error: log-and-raise tends to be an antipattern (duplicate log lines as it bubbles up, muddied ownership of who actually logs).

The guard fires at import/startup, so an uncaught ImportError crashloops the pod — already visible in k8s events + APM without an extra log. For the signal to genuinely vanish, a caller would have to wrap the startup import in try/except and swallow it, which is its own bug.

The real lever for the silent-failure class is error-level alerting on the symptom (e.g. /states 4xx rate) — a follow-up action item from the postmortem — rather than logging at the raise.

🧑‍💻🤖 — posted via Claude Code