feat(broker): align reported version with product release line

[willwashburn]

Closes #904.

Summary

The Rust broker crate previously reported its Cargo package version (3.0.0) in health, session, and telemetry payloads — even when shipped inside an agent-relay / @agent-relay/sdk 6.x release. That made install/support debugging and telemetry filtering confusing.

This PR embeds the product release-line version into the broker at compile time, keeping the Cargo crate version as a developer-build fallback rather than the source of truth.

Changes

• New helper crates/broker/src/util/version.rs exposing a BROKER_VERSION const and broker_version() accessor, backed by option_env!("AGENT_RELAY_VERSION") with CARGO_PKG_VERSION as the fallback.
• Replaced every direct env!("CARGO_PKG_VERSION") call in listen_api.rs (health + /api/config), telemetry.rs, and swarm.rs with the helper.
• Exposed --version on agent-relay-broker so packagers / smoke tests can verify the shipped version.
• Wired AGENT_RELAY_VERSION through publish.yml (the build-broker job now needs: build so it can read needs.build.outputs.new_version), build-broker-binary.yml (uses the dispatch tag or package.json version), and package-validation.yml (now fails if broker --version does not match package.json).
• Cross.toml passthrough updated so the env var reaches the aarch64-musl cross container.
• Added unit tests for the version helper.

Acceptance criteria from #904

• Released broker binaries report the same version as the agent-relay / @agent-relay/sdk release that shipped them (workflow sets AGENT_RELAY_VERSION from needs.build.outputs.new_version).
• Local cargo build --bin agent-relay-broker still reports a reasonable fallback (CARGO_PKG_VERSION).
• /api/config, health/session, and telemetry use one helper instead of direct env! calls.
• package-validation.yml verifies broker --version matches the release version.

Test plan

• cargo test -p agent-relay-broker --lib — 625 existing + 2 new tests pass.
• cargo clippy -p agent-relay-broker --bin agent-relay-broker -- -D warnings clean.
• Local manual check: AGENT_RELAY_VERSION=6.2.99 cargo build → agent-relay-broker --version reports 6.2.99; plain cargo build reports 3.0.0 (the crate fallback).
• CI green on this PR (covered by package-validation, rust-ci, test).

https://claude.ai/code/session_01Cs6t4GfxUHbnptziCekJAR

---

Generated by Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1cf62889-f7b0-44ce-bc53-4b7a36a0250a

📥 Commits

Reviewing files that changed from the base of the PR and between 22f90a1 and 2dddbec.

📒 Files selected for processing (2)

• .github/workflows/package-validation.yml
• crates/broker/src/util/version.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/broker/src/util/version.rs

---

📝 Walkthrough

Walkthrough

Adds a compile-time AGENT_RELAY_VERSION injected by CI/cross builds; introduces util::version BROKER_VERSION and broker_version(); updates CLI, /health, swarm handshake, and telemetry to use broker_version(); package-validation ensures the built binary reports the expected product version.

Changes

Broker version alignment with product releases

Layer / File(s)	Summary
Broker version module and runtime constant crates/broker/src/util/version.rs, crates/broker/src/util/mod.rs	New util::version module defines BROKER_VERSION constant selected from the AGENT_RELAY_VERSION build-time env var (release builds) or CARGO_PKG_VERSION (dev builds). Helper function broker_version() ensures consistent reporting. Unit tests verify version selection logic and non-empty value.
Build-time version injection and validation .github/workflows/publish.yml, .github/workflows/package-validation.yml, .github/workflows/build-broker-binary.yml, Cross.toml	Publish workflow configures build-broker job dependency on build job and injects AGENT_RELAY_VERSION from release output into unix and windows broker builds. Package-validation and manual build workflows set/resolve AGENT_RELAY_VERSION and package-validation verifies agent-relay-broker --version matches package.json. Cross.toml forwards env into cross-compile containers.
Runtime version consumption across components crates/broker/src/cli/mod.rs, crates/broker/src/listen_api.rs, crates/broker/src/swarm.rs, crates/broker/src/telemetry.rs	CLI --version flag, API state initialization and /health response, session handshake hello payload, and telemetry event properties are updated to call broker_version() instead of env!(\"CARGO_PKG_VERSION\"), ensuring all outputs reflect the injected product version.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• khaliqgant

Poem

🐰 I baked a version in the build,
A tiny tag the workflows filled.
From dispatch tag to cargo song,
The broker hums the release all day long. 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: aligning the reported broker version with the product release line, which is the core objective of this PR.
Description check	✅ Passed	The description includes a comprehensive Summary section explaining the problem and solution, detailed Changes listing all modifications, explicit Acceptance criteria checkmarks, and a Test plan with execution results.
Linked Issues check	✅ Passed	All acceptance criteria from #904 are met: broker binaries report product release version via AGENT_RELAY_VERSION injection [904], local cargo build uses CARGO_PKG_VERSION fallback [904], single broker_version() helper replaces direct env! calls in listen_api/telemetry/swarm [904], and package-validation verifies broker --version matches release version [904].
Out of Scope Changes check	✅ Passed	All changes directly support the objective of embedding and reporting the product release version in the broker binary, with no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/fix-issue-904-Ree1A

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[barryollama]

Code Review: Approved ✅

This PR effectively solves the version alignment issue described in #904.

Summary

The broker crate now correctly reports the product release-line version (e.g., 6.2.x) instead of the internal Cargo crate version (3.0.0) in health, session, telemetry payloads, and the --version output.

What’s Reviewed

Correctness

• The version.rs helper uses option_env! with an empty-string guard — this correctly handles CI edge cases where the env var might be set but unresolved.
• All direct env!("CARGO_PKG_VERSION") calls have been replaced with the centralized helper.

Security

• No hardcoded secrets or credentials introduced.
• No new attack surface — all changes are compile-time constant resolution.

Code Quality

• Clear documentation in version.rs explaining the fallback strategy.
• Unit tests verify non-empty output and compile-time env matching.
• Consistent naming (broker_version, BROKER_VERSION).

CI/CD Integration

• Cross.toml properly forwards AGENT_RELAY_VERSION to aarch64 cross-compile containers.
• package-validation.yml includes a verification step that fails the build if versions don’t match — excellent guardrail.
• The needs: build dependency in publish.yml workflow ensures the broker build gets the correct new_version output.

Testing

• Local manual verification steps noted in PR description.
• CI verification via package-validation.yml covers the acceptance criteria.

Minor Suggestions

(none blocking)

1. Consider documenting the version override behavior in crates/broker/README.md or top-level BROKING.md for developers building from source.
2. In build-broker-binary.yml, the fallback to npm pkg get version on branch pushes ensures the version is always meaningful — good defensive pattern.

Verdict

Clean implementation with good test coverage and CI guardrails. Ready to merge.