fix: Fall back to sdk_version when version is unknown

[malhotra5]

Problem

The agent-server binary may report version: "unknown" when build metadata isn't injected at build time (common in dev builds or containerized deployments). This breaks the version compatibility check even though sdk_version is valid and indicates a compatible version.

Example server info response:

{
  "version": "unknown",
  "sdk_version": "1.19.1",
  ...
}

The GUI shows "Unsupported agent server version" error even though sdk_version: 1.19.1 is >= the required 1.17.0.

Solution

Fall back to sdk_version when version is missing or "unknown". The SDK version is reliable (comes from the installed package) and represents the actual API compatibility level.

Changes

• Modified getServerVersion() in src/api/agent-server-compatibility.ts to check if version is valid before using it
• If version is "unknown" or missing, use sdk_version instead

---

This PR was created by an AI agent (OpenHands) to fix version compatibility issues when running agent-server-gui with containerized agent-server deployments.

@malhotra5 can click here to continue refining the PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-server-gui	Ready	Preview, Comment	May 1, 2026 3:41am

[neubig]

@OpenHands why do we have two different variables version and server_version in the first place? Is that a bug in the sdk?

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[neubig]

@neubig I think there’s a small naming mix-up here: the API payload has version and sdk_version; there isn’t actually a server_version field in the SDK/API. serverVersion is just our frontend’s local variable/error property name.

I checked software-agent-sdk’s /server_info model (openhands-agent-server/openhands/agent_server/server_details_router.py), and it intentionally exposes both:

• version = version of the openhands-agent-server package
• sdk_version = version of the openhands-sdk package

So I don’t think this is a bug in the TypeScript SDK. The real issue is that in some dev/containerized builds, the agent-server package metadata can come back as "unknown", while sdk_version is still populated and is the better signal for API compatibility.

So the bug is really on the GUI side: we were assuming version was always usable, when in practice sdk_version is a valid fallback for compatibility checks.

This comment was created by an AI agent (OpenHands) on behalf of the user.

[openhands-ai]

Final summary:

• Reviewed PR fix: Fall back to sdk_version when version is unknown #60 context and the current change on fix/version-fallback-to-sdk-version.
• Investigated the reviewer’s question against the upstream software-agent-sdk code.
• Confirmed the API intentionally exposes two fields: version and sdk_version.
• Confirmed there is no server_version field in the SDK/API; serverVersion is only a frontend-local variable/error property name.
• Answered the PR comment on GitHub, explaining that this is not an SDK naming bug; the GUI bug was assuming version was always usable when sdk_version is the correct fallback if version is "unknown".

Conciseness check:

• No code changes were made since the last summary.
• No extraneous repo changes were introduced.
• Only a PR comment was added.

[neubig]

I think this seems reasonable.