From af2b8669616153d0ba6de99dd94594cb32b47676 Mon Sep 17 00:00:00 2001 From: ZdenekSrotyr Date: Wed, 6 May 2026 15:29:20 +0200 Subject: [PATCH] docs(version): clarify APP_VERSION scope + middleware /api prefix rationale --- app/main.py | 2 ++ app/version.py | 24 +++++++++++++++++------- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/app/main.py b/app/main.py index 66ed650..f3b6213 100644 --- a/app/main.py +++ b/app/main.py @@ -185,6 +185,8 @@ def create_app() -> FastAPI: @app.middleware("http") async def _add_version_headers(request, call_next): response = await call_next(request) + # /api/* only — headers are advisory to the agnes CLI; UI/docs/marketplace + # traffic doesn't consume them. if request.url.path.startswith("/api/"): response.headers["X-Agnes-Latest-Version"] = APP_VERSION response.headers["X-Agnes-Min-Version"] = MIN_COMPAT_CLI_VERSION diff --git a/app/version.py b/app/version.py index f7c02b9..0de3db5 100644 --- a/app/version.py +++ b/app/version.py @@ -1,12 +1,22 @@ -"""Single source of truth for app + CLI compat versions. +"""Version constants used by FastAPI's `version=` field and the +`X-Agnes-{Latest,Min}-Version` response-header middleware. -`APP_VERSION` is read from package metadata so it tracks `pyproject.toml` -without a manual literal to keep in sync. +`APP_VERSION` reads from package metadata so it tracks `pyproject.toml` +without a manual literal to keep in sync. **This is not a project-wide +single source of truth** — `AGNES_VERSION` env var (set by CI/Docker +builds) continues to drive `/api/version`, `/cli/install.sh`, and the +admin UI. Those call sites pre-date `app/version.py` and are out of scope +for this change. -`MIN_COMPAT_CLI_VERSION` is the oldest CLI version the server still accepts -on `/api/*`. Bumped manually when shipping a wire-protocol break. Day-one -value of "0.0.0" means no enforcement — set the floor the first time a -deliberate break ships. +`MIN_COMPAT_CLI_VERSION` is the oldest CLI version the server advertises +as compatible on `/api/*` response headers. Enforcement lives in the +client: `cli/client.py:_check_version_headers` exits the CLI when its +local version is below this floor. The middleware itself does not reject +requests — older clients just get a header they're free to ignore (in +practice, only the agnes CLI inspects it). + +Day-one value of `MIN_COMPAT_CLI_VERSION` is `0.0.0` (no enforcement); +bumped manually when shipping a wire-protocol break. """ from importlib.metadata import PackageNotFoundError