Skip to content

πŸ™Œ 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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 flow
diff --git a/__tests__/hooks/query/use-backends-health.test.tsx b/__tests__/hooks/query/use-backends-health.test.tsx
index 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.tsx
index 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.mjs
index 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.json
index 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.md
index 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:frontend
diff --git a/playwright.mock-llm.config.ts b/playwright.mock-llm.config.ts
index 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.ts
index 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.ts
index 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 immediately
diff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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