feat: report component versions across server, worker, SDK, and CLI

[kaiitunnz]

Purpose

Once releases are versioned, an operator needs to see which version each running component is on — especially in a cluster where the root server and worker nodes may be rolled to different versions at different times. Today, the version is baked into the build (FLOWMESH_RELEASE_VERSION, the SDK User-Agent) but isn't reported anywhere a client can read it. This surfaces the version across all four components, so skew is observable.

Changes

• Server — adds GET /api/v1/system/version returning {"version": "..."}. Worker and node versions are advertised through the existing registration meta landed in the worker/node registries and are surfaced on the workers/nodes API, including flowmesh node worker list.
• Worker / Supervisor — the worker reports FLOWMESH_RELEASE_VERSION in its registration meta (riding the same path as WorkerCapabilities, no proto change); the node reports it via NodeInfo.version.
• Shared / SDK — a VersionResponse model and client.system.version() (sync + async), plus a version field on the SDK Worker and Node models. Version is optional and None when unreported.
• CLI — flowmesh --version / -V prints the CLI version; flowmesh info now reports the client version alongside the server version and health, and falls back to an unknown server version against a server that predates the /system/version endpoint.
• Tests / Docs — round-trip coverage for the worker/node version fields, the /system/version endpoint, the SDK VersionResponse, the CLI flag, and the nodes.register() version passthrough; docs/API.md lists the new endpoint.

Sidenote: also fixes a pre-existing bug where workers self-registering over gRPC reported an empty node_alias — the supervisor servicer only carried node_id. It now threads the node's alias through, matching the REST registration path.

Design

FLOWMESH_RELEASE_VERSION (server/worker) and the SDK and CLI _version.py modules remain the single source of truth — all kept in lockstep by scripts/dev/bump_version.py — so nothing new needs syncing at release time. Worker/node versions ride on the existing registration meta into Redis. The node registry drops null-valued fields before the Redis hset, where a None would otherwise be rejected. Skew handling is report-only by design — versions are exposed everywhere.

Test Plan

uv run pytest tests/ --ignore=tests/worker/test_mp_executor_cleanup_gpu.py
uv run pre-commit run --all-files
uv run flowmesh --version

Manually validated end-to-end on freshly built images, single-node and two-node:

• Single node — GET /api/v1/system/version returns the release version without auth; flowmesh worker list / flowmesh node list show the worker's and node's version; flowmesh info reports matching client and server versions; bare flowmesh prints the command help.
• Two nodes on different versions — with the root and a worker node deployed from images built at different release versions, the root's node list shows each node's distinct version, and a CPU worker spawned under each node reports its node's version — confirming the API surfaces server↔node↔worker skew.

Test Result

$ uv run pytest tests/ --ignore=tests/worker/test_mp_executor_cleanup_gpu.py    # All passed
$ uv run pre-commit run --all-files                       # isort / black / ruff / mypy / codespell passed
$ uv run flowmesh --version                               # flowmesh 0.1.3

Single-node: /system/version, worker list, and node list all reported 0.1.3, and flowmesh info showed matching client/server versions. Two-node skew: the root reported 0.1.3 while the worker node and the worker running under it reported a distinct build version, both surfaced through node list / worker list against the root.

---

Pre-submission Checklist

• I have read the contribution guidelines.
• I have run pre-commit on the changed files and fixed any issues.
• I have added or updated tests covering my changes (if applicable).
• I have verified that the affected server/SDK/CLI/shared tests pass locally.
• If I changed shared schemas or proto definitions, I have checked downstream compatibility across Server and Worker.
• If I changed the SDK or CLI, I have verified the affected packages work.
• If this is a breaking change, I have prefixed the PR title with [BREAKING] and described migration steps above.
• I have updated documentation or config examples if user-facing behavior changed.

[timzsu]

5 comments. PTAL

[timzsu]

Should we add the CLI version check to scripts/ci/check_release_version.py?

[timzsu]

LGTM.