π 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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.tsxindex 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,