fix: detect agent version from copied source

[Michaelyklam]

Thinking Path

• The System panel should report the Hermes Agent version in supported Docker deployments.
• In the two-container Compose shape, the WebUI sees a copied Agent source volume, not a live git checkout.
• That source volume can lack both VERSION and .git, so the existing detection path falls through to not detected.
• Hermes Agent still carries its package version in hermes_cli/__init__.py; future gateway health payloads may also expose a version.
• This PR adds those fallbacks without changing non-Docker git/VERSION behavior.

What Changed

• Added an Agent source-tree fallback that reads hermes_cli.__version__ when VERSION and git describe are unavailable.
• Added a bounded gateway health fallback using GATEWAY_HEALTH_URL / HERMES_GATEWAY_HEALTH_URL or the Docker service default http://hermes-agent:8642.
• Extracts version fields from /health or /health/detailed payloads when present.
• Added regression coverage for copied-source and gateway-health version detection.
• Updated the unreleased changelog.

Why It Matters

This fixes the officially documented two-container setup showing Agent: not detected even when the Agent container is present and reachable, and removes the need for users to hand-write a VERSION file after each image update.

Closes #2691

Verification

• /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_update_banner_fixes.py -q — 66 passed
• /home/michael/.hermes/hermes-agent/venv/bin/python -m py_compile api/updates.py tests/test_update_banner_fixes.py
• git diff --check

Risks / Follow-ups

• The gateway health fallback only reports a version when the Agent gateway payload includes one; copied source trees are covered independently by hermes_cli.__version__.
• The probe is best-effort and uses a short timeout so local/non-Docker installs still fall back cleanly.

Model Used

AI-assisted change with repository inspection, targeted editing, and shell-based test verification.

[nesquena-hermes]

Read the diff at PR head eadafaac against origin/master, plus api/updates.py:145-170 (current _detect_agent_version()), api/config.py:90-138 (_discover_agent_dir), and the gateway's _handle_health at gateway/platforms/api_server.py:918-920 on the agent side.

Summary

Fix matches the bug shape in #2691 and the layering is right: this is a webui-side detection bug (agent-side already returns {"status":"ok","platform":"hermes-agent"} from /health), so a webui-only fix is correct. Two fallbacks are added, and ordering is good (cheap local file read before HTTP probe). A few concerns about the gateway health payload contract and one resilience edge.

Code reference

The new copied-source fallback (api/updates.py in the diff):

def _read_agent_source_version(agent_dir: Path) -> str | None:
    init_file = agent_dir / 'hermes_cli' / '__init__.py'
    try:
        text = init_file.read_text(encoding='utf-8')
    except (OSError, UnicodeDecodeError):
        return None
    m = re.search(r"""__version__\s*=\s*['"]([^'"]+)['"]""", text)
    if m and m.group(1).strip():
        return m.group(1).strip()
    return None

This is solid — hermes_cli/__init__.py:17 is __version__ = "0.14.0" (verified against the agent source tree). Regex is anchored on the __version__ = assignment, won't false-positive on other version strings.

Concern: gateway /health doesn't actually return a version today

Inspected ~/.hermes/hermes-agent/gateway/platforms/api_server.py:918-920:

async def _handle_health(self, request):
    return web.json_response({"status": "ok", "platform": "hermes-agent"})

And _handle_health_detailed at lines 922-941 returns gateway_state / platforms / pid / updated_at — also no version field. So _detect_agent_version_from_gateway_health() will, on every Docker user in the field today, succeed at the HTTP probe but find no version key and return None. The branch is correct as a future-proofing hook, but it won't fix #2691 by itself — the copied-source fallback (_read_agent_source_version) is what actually closes the issue today.

This is fine, but the PR description and CHANGELOG should be honest about that: the gateway probe is a forward-compatible scaffold that only fires once the agent gateway starts publishing version in /health (or /health/detailed). The test test_detect_agent_version_falls_back_to_gateway_health uses a FakeResponse that injects "version":"0.14.1" — that's a future-state contract, not the current one.

Suggestion: file a paired hermes-agent PR (or note in the body) to add "version": __version__ to the _handle_health and _handle_health_detailed payloads. The keys this PR checks for — version, agent_version, hermes_version, and agent.version — give the agent flexibility but at least one needs to start populating for the gateway branch to actually fire.

Resilience nit: timeout=0.75 is tight

def _detect_agent_version_from_gateway_health(timeout: float = 0.75) -> str | None:

For an in-Docker-network call between hermes-webui and hermes-agent over the compose bridge, 750ms is fine on warm containers, but cold-start probes (the moment the WebUI panel first loads after both containers come up) can take >1s to establish the first TCP connection if the agent is still booting aiohttp. Since the result is cached for 30 min (api/updates.py:35: CACHE_TTL = 1800), a single cold-miss returning 'not detected' will stick for half an hour. Bumping to ~2.0 or making it env-tunable would be safer. Tradeoff: longer worst-case System-panel load on truly unreachable agents.

Path validation looks right

parsed = urlparse(base)
if parsed.scheme not in ('http', 'https') or not parsed.netloc:
    return None

Good — defends against GATEWAY_HEALTH_URL being misconfigured to a file:// or empty value. The trailing-slash and /health//health/detailed suffix stripping in _gateway_health_base_url() is also fine.

Recommendation

• LGTM on the copied-source fallback — that's the actual Agent: not detected in two-container Docker setup — version detection has no API fallback #2691 fix.
• Gateway-probe branch is fine as a forward hook; flag it as such in the changelog so users don't expect it to fire on nousresearch/hermes-agent:0.14.0 today.
• Optionally bump default timeout to ~2.0s, or add HERMES_GATEWAY_HEALTH_TIMEOUT env override.
• Consider opening a small companion PR in nesquena/hermes-agent to add "version": __version__ to both _handle_health and _handle_health_detailed. Without that, the urllib branch is dead code in the wild.

Tests look right: test_detect_agent_version_reads_copied_source_tree exercises the real-world Docker path with VERSION + git both absent. test_detect_agent_version_falls_back_to_gateway_health covers the future-state contract. Both fakes use monkeypatch cleanly.

[nesquena-hermes]

Shipped in v0.51.105 via release/stage-398 (#2708) — squash-merged so the source branch doesn't auto-close on the keyword.

Thanks for the contribution! Your authorship is preserved via the Co-authored-by trailer on the merged commit.