chore: release main

[stainless-app]

✨ Stainless prepared a new release

agentex-client: 0.14.0

0.14.0 (2026-06-18)

Full Changelog: agentex-client-v0.13.1...agentex-client-v0.14.0

Features

• compat: runtime SDK↔backend version guard at ACP startup (#408) (433c999)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

Greptile Summary

This release (v0.14.0) adds a runtime SDK↔backend contract-version guard that runs once at ACP server/worker startup, fetches /openapi.json from the configured backend, and raises IncompatibleBackendError if the backend is older than MIN_BACKEND_CONTRACT — replacing silent 500s with an actionable startup failure.

• compat/version_guard.py: Full SemVer parser with prerelease precedence (§11), an assert_backend_compatible async function that warns-and-proceeds on unreachable/unparseable backends and only fails hard on a known incompatible version, and an AGENTEX_SKIP_VERSION_CHECK escape hatch.
• BaseACPServer.lifespan_context and AgentexWorker._register_agent: Guard is invoked before register_agent in both startup paths, so neither path can proceed against an unsupported backend.
• Tests: 208-line unit test suite covers parse edge cases, SemVer precedence, HTTP MockTransport flows, env-var bypass, and worker integration; all async tests rely on asyncio_mode = "auto" already configured in pyproject.toml.

Confidence Score: 5/5

Safe to merge — the guard only raises when the backend version is definitively known to be older than the floor, and fails open (warns, proceeds) on any uncertainty.

The SemVer parsing and comparison logic is correct and fully exercised by the test suite; the fail-open design on unreachable/unparseable backends prevents false startup failures; and the guard is correctly positioned before registration in both startup paths.

No files require special attention.

Important Files Changed

Filename	Overview
src/agentex/lib/core/compat/version_guard.py	New runtime SDK↔backend contract-version guard with correct SemVer parsing, full prerelease precedence, and well-designed fail-fast semantics (unknown versions warn-and-proceed; only verified-older backends raise).
src/agentex/lib/core/temporal/workers/worker.py	Adds assert_backend_compatible call before register_agent in _register_agent, gated on the same AGENTEX_BASE_URL condition — mirrors the ACP server lifespan placement correctly.
src/agentex/lib/sdk/fastacp/base/base_acp_server.py	Adds assert_backend_compatible call in lifespan_context before register_agent and agent_id assignment; a raised IncompatibleBackendError will correctly abort server startup.
tests/test_version_guard.py	Comprehensive unit tests covering parse edge cases, SemVer precedence rules, HTTP transport via MockTransport, env-var bypass, and end-to-end flows; all tests use asyncio.run() wrapper so no async-mode issues.
tests/lib/core/temporal/workers/test_worker_version_guard.py	Async integration tests for worker guard wiring; uses async def functions, which are correctly handled by the project-wide asyncio_mode = "auto" in pyproject.toml.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant W as AgentexWorker / BaseACPServer
    participant G as assert_backend_compatible
    participant B as Backend (/openapi.json)
    participant R as register_agent

    W->>G: assert_backend_compatible(base_url)
    alt AGENTEX_SKIP_VERSION_CHECK set
        G-->>W: warn + return (no-op)
    else base_url unset
        G-->>W: return (no-op)
    else
        G->>B: GET /openapi.json
        alt network error / non-JSON / missing info.version
            B-->>G: error or missing field
            G-->>W: warn + return (proceed)
        else parseable version returned
            B-->>G: "{"info": {"version": "x.y.z"}}"
            G->>G: _parse + _precedence_key comparison
            alt "backend >= MIN_BACKEND_CONTRACT"
                G-->>W: log OK + return
                W->>R: register_agent(env_vars)
            else "backend < MIN_BACKEND_CONTRACT"
                G-->>W: raise IncompatibleBackendError
                Note over W: startup aborted (fail fast)
            end
        end
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant W as AgentexWorker / BaseACPServer
    participant G as assert_backend_compatible
    participant B as Backend (/openapi.json)
    participant R as register_agent

    W->>G: assert_backend_compatible(base_url)
    alt AGENTEX_SKIP_VERSION_CHECK set
        G-->>W: warn + return (no-op)
    else base_url unset
        G-->>W: return (no-op)
    else
        G->>B: GET /openapi.json
        alt network error / non-JSON / missing info.version
            B-->>G: error or missing field
            G-->>W: warn + return (proceed)
        else parseable version returned
            B-->>G: "{"info": {"version": "x.y.z"}}"
            G->>G: _parse + _precedence_key comparison
            alt "backend >= MIN_BACKEND_CONTRACT"
                G-->>W: log OK + return
                W->>R: register_agent(env_vars)
            else "backend < MIN_BACKEND_CONTRACT"
                G-->>W: raise IncompatibleBackendError
                Note over W: startup aborted (fail fast)
            end
        end
    end

Loading

_{Reviews (2): Last reviewed commit: "chore: release main" | Re-trigger Greptile}

[greptile-apps]

Release skips ADK

The new runtime guard is implemented under src/agentex/lib, but the root agentex-client wheel excludes src/agentex/lib/**; those files ship from the agentex-sdk/ADK package instead. This manifest bumps only the root client package while leaving adk at 0.13.1, and the ADK package metadata still points at agentex-sdk 0.13.1, so publishing this release can advertise the startup version guard without publishing the package that contains BaseACPServer, AgentexWorker, or compat.version_guard. Users upgrading the ADK package would still run without the guard. Please release/bump the ADK package for this change as well, and keep its client dependency aligned if it depends on the co-released client version.

Prompt To Fix With AI

This is a comment left during a code review.
Path: .release-please-manifest.json
Line: 3

Comment:
**Release skips ADK**

The new runtime guard is implemented under `src/agentex/lib`, but the root `agentex-client` wheel excludes `src/agentex/lib/**`; those files ship from the `agentex-sdk`/ADK package instead. This manifest bumps only the root client package while leaving `adk` at `0.13.1`, and the ADK package metadata still points at `agentex-sdk` `0.13.1`, so publishing this release can advertise the startup version guard without publishing the package that contains `BaseACPServer`, `AgentexWorker`, or `compat.version_guard`. Users upgrading the ADK package would still run without the guard. Please release/bump the ADK package for this change as well, and keep its client dependency aligned if it depends on the co-released client version.

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