π OpenHands: AI-Driven Development
[codex] Bump minimum compatible agent server (#1342)
Graham Neubigbbf9ce966765
diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.tsindex a798b20e68..57bfaea81a 100644--- a/__tests__/api/agent-server-adapter.test.ts+++ b/__tests__/api/agent-server-adapter.test.ts@@ -425,7 +425,7 @@ describe("buildStartConversationRequest", () => {});it("does NOT mirror conversation secrets onto agent_context for ACP β request.secrets is the sole channel", () => {- // The pinned minimum agent-server (1.25.0) injects the ACP spawn env from+ // The compatible agent-server line injects the ACP spawn env from// ``secret_registry``, which is seeded from ``request.secrets``// (sdk#3299/#3464; the agent_context drain is gone entirely in sdk#3528).// Mirroring the map onto ``agent_context.secrets`` would keep a second,@@ -519,7 +519,7 @@ describe("buildStartConversationRequest", () => {expect(payload.secrets.CODEX_AUTH_JSON?.kind).toBe("LookupSecret");expect(payload.secrets.MY_TOKEN?.kind).toBe("LookupSecret");// ``request.secrets`` is the sole channel β no agent_context mirror- // (the β₯1.25.0 agent-server injects the spawn env from secret_registry).+ // (agent-server >=1.25.0 injects the spawn env from secret_registry).expect(payload.agent_settings.agent_context?.secrets).toBeUndefined();// The configured model rides along unchanged.expect(payload.agent_settings.acp_model).toBe("gpt-5.5/medium");diff --git a/__tests__/api/agent-server-compatibility-bundled-pin.test.ts b/__tests__/api/agent-server-compatibility-bundled-pin.test.tsindex d617696404..11d46298e2 100644--- a/__tests__/api/agent-server-compatibility-bundled-pin.test.ts+++ b/__tests__/api/agent-server-compatibility-bundled-pin.test.ts@@ -8,7 +8,9 @@ import {import type { Backend } from "#/api/backend-registry/types";import {AgentServerUnavailableError,+ AgentServerUnsupportedVersionError,loadAgentServerInfo,+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,} from "#/api/agent-server-compatibility";const { getServerInfoMock } = vi.hoisted(() => ({@@ -21,6 +23,11 @@ vi.mock("@openhands/typescript-client/clients", () => ({getServerInfo: getServerInfoMock,};}),+ SettingsClient: vi.fn(function SettingsClientMock() {+ return {+ getSettings: vi.fn(),+ };+ }),}));const cloudBackend: Backend = {@@ -44,7 +51,9 @@ beforeEach(() => {__resetActiveStoreForTests();getServerInfoMock.mockReset();vi.mocked(ServerClient).mockClear();- getServerInfoMock.mockResolvedValue({ version: "1.0.0" });+ getServerInfoMock.mockResolvedValue({+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,+ });});afterEach(() => {@@ -53,6 +62,42 @@ afterEach(() => {});describe("loadAgentServerInfo", () => {+ it("returns server info when the local backend reports the minimum compatible version", async () => {+ setRegisteredBackends([localBackend]);+ setActiveSelection({ backendId: localBackend.id });++ const result = await loadAgentServerInfo();++ expect(result).toMatchObject({+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,+ });+ expect(ServerClient).toHaveBeenCalled();+ });++ it("throws AgentServerUnsupportedVersionError when the local backend is too old", async () => {+ setRegisteredBackends([localBackend]);+ setActiveSelection({ backendId: localBackend.id });+ getServerInfoMock.mockResolvedValue({ version: "1.27.1" });++ await expect(loadAgentServerInfo()).rejects.toMatchObject({+ name: AgentServerUnsupportedVersionError.name,+ actualVersion: "1.27.1",+ requiredVersion: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,+ });+ });++ it("throws AgentServerUnsupportedVersionError 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",+ requiredVersion: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,+ });+ });+it("does not borrow a registered local backend when the active backend is cloud", async () => {setRegisteredBackends([localBackend, cloudBackend]);setActiveSelection({ backendId: cloudBackend.id });diff --git a/__tests__/api/option-service.test.ts b/__tests__/api/option-service.test.tsindex 5debec4cfe..3c06fccba0 100644--- a/__tests__/api/option-service.test.ts+++ b/__tests__/api/option-service.test.ts@@ -2,8 +2,10 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { http, HttpResponse } from "msw";import {AgentServerUnavailableError,+ AgentServerUnsupportedVersionError,clearCachedAgentServerInfo,isAgentServerToolAvailable,+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,} from "#/api/agent-server-compatibility";import OptionService from "#/api/option-service/option-service.api";import { server } from "#/mocks/node";@@ -21,10 +23,14 @@ describe("OptionService", () => {expect(config.updated_at).toBeTruthy();});- it("loads config regardless of agent server version", async () => {+ it("loads config when the agent server is compatible", async () => {server.use(http.get("*/server_info", () =>- HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.0.0" }),+ HttpResponse.json({+ uptime: 0,+ idle_time: 0,+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,+ }),),);@@ -33,15 +39,30 @@ describe("OptionService", () => {});});- it("loads config even when the server does not advertise a version", async () => {+ it("throws when the agent server is too old", async () => {+ server.use(+ http.get("*/server_info", () =>+ HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.27.1" }),+ ),+ );++ await expect(OptionService.getConfig()).rejects.toMatchObject({+ name: AgentServerUnsupportedVersionError.name,+ actualVersion: "1.27.1",+ requiredVersion: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,+ });+ });++ it("throws when the server does not advertise a version", async () => {server.use(http.get("*/server_info", () =>HttpResponse.json({ uptime: 0, idle_time: 0 }),),);- await expect(OptionService.getConfig()).resolves.toMatchObject({- feature_flags: expect.objectContaining({ hide_llm_settings: false }),+ await expect(OptionService.getConfig()).rejects.toMatchObject({+ name: AgentServerUnsupportedVersionError.name,+ actualVersion: "unknown",});});@@ -61,7 +82,7 @@ describe("OptionService", () => {HttpResponse.json({uptime: 0,idle_time: 0,- version: "1.21.1",+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,usable_tools: ["terminal", "file_editor", "task_tracker"],}),),@@ -79,7 +100,7 @@ describe("OptionService", () => {HttpResponse.json({uptime: 0,idle_time: 0,- version: "1.21.1",+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,}),),);diff --git a/__tests__/components/backends/add-backend-modal.test.tsx b/__tests__/components/backends/add-backend-modal.test.tsxindex 3067c0adcb..a835cabdb9 100644--- a/__tests__/components/backends/add-backend-modal.test.tsx+++ b/__tests__/components/backends/add-backend-modal.test.tsx@@ -44,7 +44,7 @@ function renderWithProviders(beforeEach(() => {window.localStorage.clear();getServerInfoMock.mockReset();- getServerInfoMock.mockResolvedValue({ version: "1.24.0" });+ getServerInfoMock.mockResolvedValue({ version: "1.28.0" });__resetActiveStoreForTests();});@@ -203,6 +203,26 @@ describe("AddBackendModal β two-column layout", () => {expect(onClose).not.toHaveBeenCalled();});+ it("keeps the modal open when the local backend is below the compatible version floor", async () => {+ getServerInfoMock.mockResolvedValueOnce({ version: "1.27.1" });+ const onClose = vi.fn();+ renderWithProviders(<AddBackendModal onClose={onClose} />);++ const user = userEvent.setup();+ await user.type(screen.getByTestId("add-backend-name"), "Old Tunnel");+ await user.type(+ screen.getByTestId("add-backend-host"),+ "https://127.0.0.1:8000",+ );+ await user.type(screen.getByTestId("add-backend-api-key"), "session-key");+ await user.click(screen.getByTestId("add-backend-submit"));++ expect(await screen.findByTestId("add-backend-error")).toHaveTextContent(+ "Agent Canvas requires agent-server 1.28.0 or newer",+ );+ expect(onClose).not.toHaveBeenCalled();+ });+it("closes when the header close button is clicked", async () => {const user = userEvent.setup();const onClose = vi.fn();diff --git a/__tests__/components/backends/api-key-entry-screen.test.tsx b/__tests__/components/backends/api-key-entry-screen.test.tsxindex 7f298fff90..110a930bbd 100644--- a/__tests__/components/backends/api-key-entry-screen.test.tsx+++ b/__tests__/components/backends/api-key-entry-screen.test.tsx@@ -18,7 +18,7 @@ vi.mock("@openhands/typescript-client/clients", () => ({}),// ServerClient needed by useBackendsHealth (imported transitively)ServerClient: vi.fn(function ServerClientMock() {- return { getServerInfo: vi.fn().mockResolvedValue({ version: "1.0.0" }) };+ return { getServerInfo: vi.fn().mockResolvedValue({ version: "1.28.0" }) };}),}));diff --git a/__tests__/components/backends/backend-selector.test.tsx b/__tests__/components/backends/backend-selector.test.tsxindex 247aa89d27..e0dff14d72 100644--- a/__tests__/components/backends/backend-selector.test.tsx+++ b/__tests__/components/backends/backend-selector.test.tsx@@ -126,7 +126,7 @@ beforeEach(() => {vi.mocked(ServerClient).mockReset();vi.mocked(ServerClient).mockImplementation(function ServerClientMock() {return {- getServerInfo: vi.fn().mockResolvedValue({ version: "1.18.0" }),+ getServerInfo: vi.fn().mockResolvedValue({ version: "1.28.0" }),} as unknown as ServerClient;});vi.mocked(SettingsClient).mockReset();diff --git a/__tests__/components/backends/manage-backends-modal.test.tsx b/__tests__/components/backends/manage-backends-modal.test.tsxindex 48cfd783f5..00f864f3e0 100644--- a/__tests__/components/backends/manage-backends-modal.test.tsx+++ b/__tests__/components/backends/manage-backends-modal.test.tsx@@ -17,7 +17,7 @@ import {} from "#/contexts/active-backend-context";import { ManageBackendsModal } from "#/components/features/backends/manage-backends-modal";-const getServerInfoMock = vi.fn().mockResolvedValue({ version: "1.18.0" });+const getServerInfoMock = vi.fn().mockResolvedValue({ version: "1.28.0" });const getSettingsMock = vi.fn().mockResolvedValue({});vi.mock("@openhands/typescript-client/clients", () => ({@@ -65,7 +65,7 @@ function TestSeed({beforeEach(() => {window.localStorage.clear();getServerInfoMock.mockReset();- getServerInfoMock.mockResolvedValue({ version: "1.18.0" });+ getServerInfoMock.mockResolvedValue({ version: "1.28.0" });getSettingsMock.mockReset();getSettingsMock.mockResolvedValue({});__resetActiveStoreForTests();@@ -113,6 +113,25 @@ describe("ManageBackendsModal", () => {).toHaveAttribute("data-status", "disconnected");});+ it("shows disconnected for a reachable backend below the compatible version floor", async () => {+ getServerInfoMock.mockResolvedValue({ version: "1.27.1" });++ renderWithProviders(<ManageBackendsModal onClose={vi.fn()} />);++ expect(+ await screen.findByTestId("manage-backends-version-Local"),+ ).toBeInTheDocument();+ expect(getServerInfoMock).toHaveBeenCalled();+ await waitFor(() =>+ expect(+ screen.getByTestId("manage-backends-status-Local"),+ ).toHaveTextContent("ONBOARDING$BACKEND_STATUS_DISCONNECTED"),+ );+ expect(+ screen.getByTestId("manage-backends-status-detail-Local"),+ ).toHaveTextContent("Agent Canvas requires agent-server 1.28.0 or newer");+ });+it("closes when the header close button is clicked", async () => {const user = userEvent.setup();const onClose = vi.fn();diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsxindex f938cfb9e6..1d0b404903 100644--- a/__tests__/components/onboarding/onboarding-modal.test.tsx+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx@@ -163,7 +163,7 @@ beforeEach(() => {if (options?.host?.startsWith("https://127.0.0.1:8000")) {return Promise.reject(new Error("Failed to fetch"));}- return Promise.resolve({ version: "1.18.0" });+ return Promise.resolve({ version: "1.28.0" });});// ChooseAgentStep's Next button now persists the selection via// saveSettings before advancing. Stub it so the rest of the flowdiff --git a/__tests__/hooks/query/use-backends-health.test.tsx b/__tests__/hooks/query/use-backends-health.test.tsxindex 5f2199b3b6..57c9b5f8d6 100644--- a/__tests__/hooks/query/use-backends-health.test.tsx+++ b/__tests__/hooks/query/use-backends-health.test.tsx@@ -1,4 +1,7 @@-import { SettingsClient } from "@openhands/typescript-client/clients";+import {+ ServerClient,+ SettingsClient,+} from "@openhands/typescript-client/clients";import React from "react";import { QueryClient, QueryClientProvider } from "@tanstack/react-query";import { act, renderHook, waitFor } from "@testing-library/react";@@ -16,9 +19,13 @@ import type { Backend } from "#/api/backend-registry/types";import { useBackendsHealth } from "#/hooks/query/use-backends-health";const getSettingsMock = vi.fn();+const getServerInfoMock = vi.fn();const getCurrentCloudApiKeyMock = vi.fn();vi.mock("@openhands/typescript-client/clients", () => ({+ ServerClient: vi.fn(function ServerClientMock() {+ return { getServerInfo: getServerInfoMock };+ }),SettingsClient: vi.fn(function SettingsClientMock() {return { getSettings: getSettingsMock };}),@@ -54,7 +61,10 @@ function wrapper({ children }: { children: React.ReactNode }) {beforeEach(() => {getSettingsMock.mockReset();+ getServerInfoMock.mockReset();+ getServerInfoMock.mockResolvedValue({ version: "1.28.0" });getCurrentCloudApiKeyMock.mockReset();+ vi.mocked(ServerClient).mockClear();vi.mocked(SettingsClient).mockClear();window.localStorage.clear();__resetHealthStoreForTests();@@ -67,7 +77,7 @@ afterEach(() => {});describe("useBackendsHealth", () => {- it("probes local backends via authenticated settings and reports connected", async () => {+ it("probes local backends via authenticated settings and compatible server info", async () => {getSettingsMock.mockResolvedValue({});const { result } = renderHook(() => useBackendsHealth([localBackend]), {@@ -78,9 +88,27 @@ describe("useBackendsHealth", () => {expect(result.current[localBackend.id].isConnected).toBe(true),);expect(getSettingsMock).toHaveBeenCalled();+ expect(getServerInfoMock).toHaveBeenCalled();expect(getCurrentCloudApiKeyMock).not.toHaveBeenCalled();});+ it("reports disconnected when the local backend is below the compatible version floor", async () => {+ getSettingsMock.mockResolvedValue({});+ getServerInfoMock.mockResolvedValue({ version: "1.27.1" });++ const { result } = renderHook(() => useBackendsHealth([localBackend]), {+ wrapper,+ });++ await waitFor(() =>+ expect(result.current[localBackend.id]).toMatchObject({+ isConnected: false,+ lastError:+ "Agent Canvas requires agent-server 1.28.0 or newer; this backend is running 1.27.1. Please upgrade the agent-server backend.",+ }),+ );+ });+it("reports disconnected when the local probe throws", async () => {getSettingsMock.mockRejectedValue(new Error("ECONNREFUSED"));@@ -111,6 +139,7 @@ describe("useBackendsHealth", () => {lastError: "Invalid API key",}),);+ expect(getServerInfoMock).not.toHaveBeenCalled();});it("probes cloud backends via getCurrentCloudApiKey", async () => {diff --git a/__tests__/root.test.tsx b/__tests__/root.test.tsxindex 6b09f32d89..e041920e2f 100644--- a/__tests__/root.test.tsx+++ b/__tests__/root.test.tsx@@ -66,25 +66,28 @@ describe("App root agent-server availability guard", () => {});- it("renders the routed page even when the connected server reports an old version", async () => {+ it("shows the manage-backends modal when the connected server reports an old version", async () => {server.use(http.get("/server_info", () =>- HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.0.0" }),+ HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.27.1" }),),);renderApp(["/"]);await waitFor(() => {- expect(screen.getByTestId("app-outlet")).toBeInTheDocument();+ expect(+ screen.getByTestId("agent-server-onboarding-screen"),+ ).toBeInTheDocument();});- expect(- screen.queryByTestId("agent-server-onboarding-screen"),- ).not.toBeInTheDocument();+ await waitFor(() => {+ expect(screen.getByTestId("manage-backends-modal")).toBeInTheDocument();+ });+ expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();});- it("renders the routed page when the server omits a version field", async () => {+ it("shows the manage-backends modal when the server omits a version field", async () => {server.use(http.get("/server_info", () =>HttpResponse.json({ uptime: 0, idle_time: 0 }),@@ -94,8 +97,11 @@ describe("App root agent-server availability guard", () => {renderApp(["/"]);await waitFor(() => {- expect(screen.getByTestId("app-outlet")).toBeInTheDocument();+ expect(+ screen.getByTestId("agent-server-onboarding-screen"),+ ).toBeInTheDocument();});+ expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();});it("shows the manage-backends modal when the backend is unreachable", async () => {diff --git a/bin/agent-canvas.mjs b/bin/agent-canvas.mjsindex 35533afd5c..20456c6513 100755--- a/bin/agent-canvas.mjs+++ b/bin/agent-canvas.mjs@@ -39,6 +39,9 @@ Default stack versions:automation: ${defaults.versions.automation}automation-sdk: ${defaults.versions.automationSdk}+Compatibility:+ agent-server: >= ${defaults.compatibility.minimumAgentServer}+Default ports:ingress: ${defaults.ports.proxy}agent-server: ${defaults.ports.agentServer}diff --git a/config/defaults.json b/config/defaults.jsonindex 0ffe79e7f6..8bbb456165 100644--- a/config/defaults.json+++ b/config/defaults.json@@ -8,6 +8,10 @@"automationSdk": "1.28.1"},+ "compatibility": {+ "minimumAgentServer": "1.28.0"+ },+"images": {"agentServer": "ghcr.io/openhands/agent-server","agentCanvas": "ghcr.io/openhands/agent-canvas"diff --git a/docs/ACP_AGENTS.md b/docs/ACP_AGENTS.mdindex 1baf017ae1..ab2be745e6 100644--- a/docs/ACP_AGENTS.md+++ b/docs/ACP_AGENTS.md@@ -147,11 +147,11 @@ point Canvas at it). In short:# to it directly). The image pre-installs the ACP CLI wrappers. The# canvas_ui tool is mounted so the agent-server can import the module Canvas# references in every start request.-# Minimum image: 1.25.0-python (first release with software-agent-sdk#3510;-# older images deadlock the first ACP turn). Override SHA with a newer build.+# Minimum image: 1.28.0-python (first compatible ACP provider/model protocol+# surface for current Canvas). Override SHA with a newer build.docker run -d --name oh-acp -p 8010:8000 -v acp-data:/workspace \-v "$(pwd)/tools:/canvas-tools:ro" -e OH_EXTRA_PYTHON_PATH=/canvas-tools \- ghcr.io/openhands/agent-server:1.25.0-python+ ghcr.io/openhands/agent-server:1.28.0-python# 2. Canvas pointed at the container.VITE_BACKEND_BASE_URL=http://localhost:8010 npm run dev:frontenddiff --git a/playwright.mock-llm.config.ts b/playwright.mock-llm.config.tsindex ce80b46321..60f5207b20 100644--- a/playwright.mock-llm.config.ts+++ b/playwright.mock-llm.config.ts@@ -167,6 +167,7 @@ export default defineConfig({"--auth-required","--route /api/automation=http://localhost:18001","--route /api=http://localhost:18000",+ "--route /server_info=http://localhost:18000","--route /sockets=http://localhost:18000",].join(" "),url: `http://localhost:${PUBLIC_MODE_PORT}/`,diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.tsindex 6b132b7396..e8f0f48195 100644--- a/src/api/agent-server-adapter.ts+++ b/src/api/agent-server-adapter.ts@@ -945,7 +945,7 @@ export function buildStartConversationRequest(// Every saved secret rides as a LookupSecret the agent-server resolves back// from its own store at spawn time β ``request.secrets`` is the sole channel,// uniform for ACP and non-ACP (agent-canvas#1039). For ACP the resolution- // runs off the event loop (software-agent-sdk#3510, β₯1.25.0), so the loopback+ // runs off the event loop (software-agent-sdk#3510, >=1.25.0), so the loopback// fetch can't deadlock.if (options.customSecrets && options.customSecrets.length > 0) {const backend = getEffectiveLocalBackend();diff --git a/src/api/agent-server-compatibility.ts b/src/api/agent-server-compatibility.tsindex 63ee467502..fdd90b280f 100644--- a/src/api/agent-server-compatibility.ts+++ b/src/api/agent-server-compatibility.ts@@ -10,8 +10,15 @@ import {getEffectiveLocalBackend,isNoBackend,} from "#/api/backend-registry/active-store";+import defaults from "../../config/defaults.json";const AGENT_SERVER_INFO_TIMEOUT_MS = 5000;+const UNKNOWN_AGENT_SERVER_VERSION = "unknown";++export const MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION =+ defaults.compatibility.minimumAgentServer;+export const AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE =+ "AGENT_SERVER_UNSUPPORTED_VERSION";export interface AgentServerInfo extends BaseServerInfo {usable_tools?: string[] | null;@@ -55,6 +62,29 @@ export const isAgentServerUnavailableError = ("name" in error &&error.name === "AgentServerUnavailableError");+export class AgentServerUnsupportedVersionError extends AgentServerUnavailableError {+ readonly code = AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE;+ readonly actualVersion: string;+ readonly requiredVersion = MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION;++ constructor(actualVersion: string) {+ const message = `Agent Canvas requires agent-server ${MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION} or newer; this backend is running ${actualVersion}. Please upgrade the agent-server backend.`;+ super(message);+ this.name = "AgentServerUnsupportedVersionError";+ this.message = message;+ this.actualVersion = actualVersion;+ }+}++export const isAgentServerUnsupportedVersionError = (+ error: unknown,+): error is AgentServerUnsupportedVersionError =>+ error instanceof AgentServerUnsupportedVersionError ||+ (typeof error === "object" &&+ error !== null &&+ "code" in error &&+ error.code === AGENT_SERVER_UNSUPPORTED_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@@ -98,6 +128,77 @@ 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 compareAgentServerVersions(actual: string, required: string) {+ const parsedActual = parseAgentServerVersion(actual);+ const parsedRequired = parseAgentServerVersion(required);++ if (!parsedActual || !parsedRequired) {+ return null;+ }++ for (const key of ["major", "minor", "patch"] as const) {+ if (parsedActual[key] > parsedRequired[key]) {+ return 1;+ }+ if (parsedActual[key] < parsedRequired[key]) {+ return -1;+ }+ }++ if (parsedActual.prerelease && !parsedRequired.prerelease) {+ return -1;+ }+ if (!parsedActual.prerelease && parsedRequired.prerelease) {+ return 1;+ }+ if (parsedActual.prerelease && parsedRequired.prerelease) {+ return parsedActual.prerelease.localeCompare(parsedRequired.prerelease);+ }++ return 0;+}++function parseAgentServerVersion(version: string) {+ const trimmed = version.trim().replace(/^v/, "");+ const [withoutBuild] = trimmed.split("+");+ const [core, prerelease] = withoutBuild.split("-", 2);+ const parts = core.split(".");++ if (parts.length !== 3) {+ return null;+ }++ const [major, minor, patch] = parts.map((part) => Number(part));+ if (+ ![major, minor, patch].every((part) => Number.isInteger(part) && part >= 0)+ ) {+ return null;+ }++ return { major, minor, patch, prerelease };+}++export function assertAgentServerVersionIsSupported(+ serverInfo: AgentServerInfo,+) {+ const actualVersion = getReportedAgentServerVersion(serverInfo);+ const comparison = compareAgentServerVersions(+ actualVersion,+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,+ );++ if (comparison === null || comparison < 0) {+ clearCachedAgentServerInfo();+ throw new AgentServerUnsupportedVersionError(actualVersion);+ }+}+export async function loadAgentServerInfo() {// The probe is a *local* agent-server concern β it verifies the runtime// hosting the GUI is reachable. It must NEVER run against the active@@ -144,6 +245,8 @@ export async function loadAgentServerInfo() {throw new AgentServerUnavailableError(details);}+ assertAgentServerVersionIsSupported(serverInfo);+// /server_info is unprotected, so a stale session key still gets 200.// In public mode, validate the key against a protected endpoint so a// server restart with a new LOCAL_BACKEND_API_KEY surfaces immediatelydiff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsxindex 35b1be14bb..d96839804c 100644--- a/src/components/features/backends/backend-form-modal.tsx+++ b/src/components/features/backends/backend-form-modal.tsx@@ -15,6 +15,7 @@ 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 ChevronDownSmallIcon from "#/icons/chevron-down-small.svg?react";import { I18nKey } from "#/i18n/declaration";import type { Backend, BackendKind } from "#/api/backend-registry/types";@@ -145,13 +146,14 @@ async function testBackendConnection(// Cloud backends authenticate via OAuth; preflight GET is not applicable.if (backend.kind !== "local") return;- await new ServerClient(+ const serverInfo = await new ServerClient(getAgentServerClientOptions({host: backend.host,sessionApiKey: backend.apiKey || null,timeout: 5000,}),).getServerInfo();+ assertAgentServerVersionIsSupported(serverInfo);}/**diff --git a/src/components/features/backends/manage-backends-modal.tsx b/src/components/features/backends/manage-backends-modal.tsxindex d3f41b620a..e1c7173072 100644--- a/src/components/features/backends/manage-backends-modal.tsx+++ b/src/components/features/backends/manage-backends-modal.tsx@@ -91,6 +91,10 @@ function BackendRow({}: BackendRowProps) {const { t } = useTranslation("openhands");const isInvalidApiKey = isInvalidBackendApiKeyHealthError(health?.lastError);+ const statusDetail =+ !isInvalidApiKey && health?.isConnected === false && health.lastError+ ? health.lastError+ : null;let statusLabel: string;let statusClassName = "text-[var(--oh-muted)]";@@ -140,6 +144,15 @@ function BackendRow({>{statusLabel}</span>+ {statusDetail ? (+ <span+ data-testid={`manage-backends-status-detail-${backend.name}`}+ title={statusDetail}+ className="text-xs text-red-300/80 whitespace-normal break-words"+ >+ {statusDetail}+ </span>+ ) : null}</div><span className="px-2 py-1 rounded-full text-[11px] uppercase tracking-wide text-[var(--oh-text-tertiary)] bg-[var(--oh-surface)] border border-[var(--oh-border)]">{backend.kind === "cloud"diff --git a/src/hooks/query/use-backends-health.ts b/src/hooks/query/use-backends-health.tsindex 4a2e10083a..4164340754 100644--- a/src/hooks/query/use-backends-health.ts+++ b/src/hooks/query/use-backends-health.ts@@ -1,8 +1,14 @@import React from "react";import { useQueries } from "@tanstack/react-query";-import { SettingsClient } from "@openhands/typescript-client/clients";+import {+ ServerClient,+ SettingsClient,+} from "@openhands/typescript-client/clients";import { getCurrentCloudApiKey } from "#/api/cloud/organization-service.api";-import { isSdkHttpStatusError } from "#/api/agent-server-compatibility";+import {+ assertAgentServerVersionIsSupported,+ isSdkHttpStatusError,+} from "#/api/agent-server-compatibility";import type { Backend } from "#/api/backend-registry/types";import { getAgentServerClientOptions } from "#/api/agent-server-client-options";import {@@ -27,8 +33,9 @@ export function isInvalidBackendApiKeyHealthError(* Probe a single backend for connectivity. The probe path differs by* backend kind:*- * - Local agent-server: GET `/api/settings` via the typescript-client.- * Unlike `/server_info`, this validates the configured session API key.+ * - Local agent-server: GET `/api/settings`, then `/server_info` via the+ * typescript-client. The settings call validates the configured session+ * API key; the server info call validates the version compatibility floor.* - Cloud: GET `/api/keys/current` via the bundled local* agent-server's `/api/cloud-proxy`. That endpoint is lightweight,* requires auth, and `getCurrentCloudApiKey` already absorbs the@@ -46,13 +53,15 @@ async function probeBackend(backend: Backend): Promise<true> {}try {- await new SettingsClient(- getAgentServerClientOptions({- host: backend.host,- sessionApiKey: backend.apiKey || null,- timeout: PROBE_TIMEOUT_MS,- }),- ).getSettings();+ const clientOptions = getAgentServerClientOptions({+ host: backend.host,+ sessionApiKey: backend.apiKey || null,+ timeout: PROBE_TIMEOUT_MS,+ });++ await new SettingsClient(clientOptions).getSettings();+ const serverInfo = await new ServerClient(clientOptions).getServerInfo();+ assertAgentServerVersionIsSupported(serverInfo);} catch (error) {if (isSdkHttpStatusError(error, 401)) {throw new Error(INVALID_BACKEND_API_KEY_ERROR);diff --git a/src/mocks/settings-handlers.ts b/src/mocks/settings-handlers.tsindex 67d01c0984..f04d2e4301 100644--- a/src/mocks/settings-handlers.ts+++ b/src/mocks/settings-handlers.ts@@ -590,7 +590,7 @@ const MOCK_VERIFIED_MODELS_BY_PROVIDER = MOCK_MODELS.reduce<return acc;}, {});-const MOCK_AGENT_SERVER_VERSION = "1.24.0";+const MOCK_AGENT_SERVER_VERSION = "1.28.1";// --- Handlers for options/config/settings ---// Uses wildcard "*" prefix to match both relative paths and absolute URLs