Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Clarify unknown agent-server version errors (#1382)

Graham Neubig1d4135fbbfff
diff --git a/__tests__/api/agent-server-compatibility-bundled-pin.test.ts b/__tests__/api/agent-server-compatibility-bundled-pin.test.ts
index 11d46298e2..9043ccce9e 100644
--- a/__tests__/api/agent-server-compatibility-bundled-pin.test.ts
+++ b/__tests__/api/agent-server-compatibility-bundled-pin.test.ts
@@ -8,6 +8,7 @@ import {
import type { Backend } from "#/api/backend-registry/types";
import {
AgentServerUnavailableError,
+ AgentServerUnknownVersionError,
AgentServerUnsupportedVersionError,
loadAgentServerInfo,
MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
@@ -86,14 +87,14 @@ describe("loadAgentServerInfo", () => {
});
});
- it("throws AgentServerUnsupportedVersionError when the local backend omits its version", async () => {
+ it("throws AgentServerUnknownVersionError when the local backend omits its version", async () => {
setRegisteredBackends([localBackend]);
setActiveSelection({ backendId: localBackend.id });
getServerInfoMock.mockResolvedValue({});
await expect(loadAgentServerInfo()).rejects.toMatchObject({
- name: AgentServerUnsupportedVersionError.name,
- actualVersion: "unknown",
+ name: AgentServerUnknownVersionError.name,
+ actualVersion: null,
requiredVersion: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
});
});
diff --git a/__tests__/api/option-service.test.ts b/__tests__/api/option-service.test.ts
index 3c06fccba0..36be4c4a75 100644
--- a/__tests__/api/option-service.test.ts
+++ b/__tests__/api/option-service.test.ts
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { http, HttpResponse } from "msw";
import {
AgentServerUnavailableError,
+ AgentServerUnknownVersionError,
AgentServerUnsupportedVersionError,
clearCachedAgentServerInfo,
isAgentServerToolAvailable,
@@ -61,8 +62,8 @@ describe("OptionService", () => {
);
await expect(OptionService.getConfig()).rejects.toMatchObject({
- name: AgentServerUnsupportedVersionError.name,
- actualVersion: "unknown",
+ name: AgentServerUnknownVersionError.name,
+ actualVersion: null,
});
});
diff --git a/src/api/agent-server-compatibility.test.ts b/src/api/agent-server-compatibility.test.ts
new file mode 100644
index 0000000000..153593c35e
--- /dev/null
+++ b/src/api/agent-server-compatibility.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import {
+ AgentServerUnknownVersionError,
+ AgentServerUnsupportedVersionError,
+ assertAgentServerVersionIsSupported,
+ getDisplayAgentServerVersion,
+ type AgentServerInfo,
+} from "./agent-server-compatibility";
+
+const serverInfo = (version?: string): AgentServerInfo =>
+ ({ version }) as AgentServerInfo;
+
+describe("agent-server version compatibility", () => {
+ it("classifies missing and unknown versions separately from old versions", () => {
+ for (const version of [undefined, "", "unknown", " UNKNOWN "]) {
+ expect(() =>
+ assertAgentServerVersionIsSupported(serverInfo(version)),
+ ).toThrow(AgentServerUnknownVersionError);
+ }
+ });
+
+ it("classifies malformed versions separately from old versions", () => {
+ expect(() =>
+ assertAgentServerVersionIsSupported(serverInfo("dev-build")),
+ ).toThrow(AgentServerUnknownVersionError);
+ });
+
+ it("keeps valid but too-old versions on the unsupported-version path", () => {
+ expect(() =>
+ assertAgentServerVersionIsSupported(serverInfo("0.0.1")),
+ ).toThrow(AgentServerUnsupportedVersionError);
+ });
+
+ it("does not render unknown or malformed versions as backend badges", () => {
+ expect(getDisplayAgentServerVersion(serverInfo("unknown"))).toBeNull();
+ expect(getDisplayAgentServerVersion(serverInfo("dev-build"))).toBeNull();
+ expect(getDisplayAgentServerVersion(serverInfo("1.28.0"))).toBe("1.28.0");
+ });
+});
diff --git a/src/api/agent-server-compatibility.ts b/src/api/agent-server-compatibility.ts
index fdd90b280f..990aa7019e 100644
--- a/src/api/agent-server-compatibility.ts
+++ b/src/api/agent-server-compatibility.ts
@@ -19,6 +19,8 @@ export const MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION =
defaults.compatibility.minimumAgentServer;
export const AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE =
"AGENT_SERVER_UNSUPPORTED_VERSION";
+export const AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE =
+ "AGENT_SERVER_UNKNOWN_VERSION";
export interface AgentServerInfo extends BaseServerInfo {
usable_tools?: string[] | null;
@@ -76,6 +78,25 @@ export class AgentServerUnsupportedVersionError extends AgentServerUnavailableEr
}
}
+export class AgentServerUnknownVersionError extends AgentServerUnavailableError {
+ readonly code = AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE;
+ readonly actualVersion: string | null;
+ readonly requiredVersion = MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION;
+
+ constructor(actualVersion: string | null) {
+ const reported = actualVersion ? ` It reported "${actualVersion}".` : "";
+ const message =
+ `Could not determine this backend's agent-server version.${reported} ` +
+ `Agent Canvas requires agent-server ${MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION} ` +
+ "or newer, but this backend did not return a valid version from " +
+ "/server_info. Restart or rebuild the agent-server backend, then try again.";
+ super(message);
+ this.name = "AgentServerUnknownVersionError";
+ this.message = message;
+ this.actualVersion = actualVersion;
+ }
+}
+
export const isAgentServerUnsupportedVersionError = (
error: unknown,
): error is AgentServerUnsupportedVersionError =>
@@ -85,6 +106,15 @@ export const isAgentServerUnsupportedVersionError = (
"code" in error &&
error.code === AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE);
+export const isAgentServerUnknownVersionError = (
+ error: unknown,
+): error is AgentServerUnknownVersionError =>
+ error instanceof AgentServerUnknownVersionError ||
+ (typeof error === "object" &&
+ error !== null &&
+ "code" in error &&
+ error.code === AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE);
+
/**
* Returns true when the agent-server probe failed with HTTP 401.
* In public mode this means the stored key is stale (server restarted
@@ -128,10 +158,30 @@ export function isSdkHttpStatusError(error: unknown, status: number): boolean {
);
}
-function getReportedAgentServerVersion(serverInfo: AgentServerInfo) {
- return typeof serverInfo.version === "string" && serverInfo.version.trim()
- ? serverInfo.version.trim()
- : UNKNOWN_AGENT_SERVER_VERSION;
+function getRawAgentServerVersion(serverInfo: AgentServerInfo): string | null {
+ if (typeof serverInfo.version !== "string") return null;
+ const trimmed = serverInfo.version.trim();
+ return trimmed || null;
+}
+
+function getComparableAgentServerVersion(
+ serverInfo: AgentServerInfo,
+): string | null {
+ const version = getRawAgentServerVersion(serverInfo);
+ if (!version || version.toLowerCase() === UNKNOWN_AGENT_SERVER_VERSION) {
+ return null;
+ }
+ return version;
+}
+
+export function getDisplayAgentServerVersion(
+ serverInfo: AgentServerInfo,
+): string | null {
+ const version = getComparableAgentServerVersion(serverInfo);
+ if (!version || !parseAgentServerVersion(version)) {
+ return null;
+ }
+ return version;
}
function compareAgentServerVersions(actual: string, required: string) {
@@ -187,13 +237,25 @@ function parseAgentServerVersion(version: string) {
export function assertAgentServerVersionIsSupported(
serverInfo: AgentServerInfo,
) {
- const actualVersion = getReportedAgentServerVersion(serverInfo);
+ const actualVersion = getComparableAgentServerVersion(serverInfo);
+ if (!actualVersion) {
+ clearCachedAgentServerInfo();
+ throw new AgentServerUnknownVersionError(
+ getRawAgentServerVersion(serverInfo),
+ );
+ }
+
const comparison = compareAgentServerVersions(
actualVersion,
MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
);
- if (comparison === null || comparison < 0) {
+ if (comparison === null) {
+ clearCachedAgentServerInfo();
+ throw new AgentServerUnknownVersionError(actualVersion);
+ }
+
+ if (comparison < 0) {
clearCachedAgentServerInfo();
throw new AgentServerUnsupportedVersionError(actualVersion);
}
diff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsx
index 2cdd02b9fc..6fd2266f1f 100644
--- a/src/components/features/backends/backend-form-modal.tsx
+++ b/src/components/features/backends/backend-form-modal.tsx
@@ -15,7 +15,10 @@ import { useActiveBackendContext } from "#/contexts/active-backend-context";
import { useNavigation } from "#/context/navigation-context";
import { useBackendsHealth } from "#/hooks/query/use-backends-health";
import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
-import { assertAgentServerVersionIsSupported } from "#/api/agent-server-compatibility";
+import {
+ assertAgentServerVersionIsSupported,
+ getDisplayAgentServerVersion,
+} from "#/api/agent-server-compatibility";
import ChevronDownSmallIcon from "#/icons/chevron-down-small.svg?react";
import { I18nKey } from "#/i18n/declaration";
import type { Backend, BackendKind } from "#/api/backend-registry/types";
@@ -187,7 +190,7 @@ function BackendStatusBadge({
timeout: 5000,
}),
).getServerInfo();
- return info.version ?? null;
+ return getDisplayAgentServerVersion(info);
},
retry: false,
staleTime: 60_000,
diff --git a/src/components/features/backends/backend-version.tsx b/src/components/features/backends/backend-version.tsx
index 98ffdea50e..308ff39435 100644
--- a/src/components/features/backends/backend-version.tsx
+++ b/src/components/features/backends/backend-version.tsx
@@ -4,6 +4,7 @@ import { useQuery } from "@tanstack/react-query";
import { ServerClient } from "@openhands/typescript-client/clients";
import { type Backend } from "#/api/backend-registry/types";
import { getAgentServerClientOptions } from "#/api/agent-server-client-options";
+import { getDisplayAgentServerVersion } from "#/api/agent-server-compatibility";
import { I18nKey } from "#/i18n/declaration";
export function BackendVersion({ backend }: { backend: Backend }) {
@@ -18,7 +19,7 @@ export function BackendVersion({ backend }: { backend: Backend }) {
timeout: 5000,
}),
).getServerInfo();
- return info.version ?? null;
+ return getDisplayAgentServerVersion(info);
},
retry: false,
staleTime: 60_000,