Skip to content

πŸ™Œ OpenHands: AI-Driven Development

test: strengthen agent server connection behavior (#17354)

aivong-openhands9cf5c2c1a410
diff --git a/__tests__/api/agent-server-compatibility-bundled-pin.test.ts b/__tests__/api/agent-server-compatibility-bundled-pin.test.ts
index 5be11fb4d0..6a49764095 100644
--- a/__tests__/api/agent-server-compatibility-bundled-pin.test.ts
+++ b/__tests__/api/agent-server-compatibility-bundled-pin.test.ts
@@ -1,4 +1,7 @@
-import { ServerClient } from "@openhands/typescript-client/clients";
+import {
+ ServerClient,
+ SettingsClient,
+} from "@openhands/typescript-client/clients";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
__resetActiveStoreForTests,
@@ -7,17 +10,29 @@ import {
} from "#/api/backend-registry/active-store";
import type { Backend } from "#/api/backend-registry/types";
import {
+ AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE,
+ AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE,
AgentServerUnavailableError,
AgentServerUnknownVersionError,
AgentServerUnsupportedVersionError,
clearCachedAgentServerInfo,
getCachedAgentServerInfo,
+ getCachedAgentServerVersion,
+ getCachedAgentServerSdkVersion,
+ validateLocalBackend,
+ INVALID_BACKEND_API_KEY_ERROR,
+ isAgentServerAuthError,
+ isAgentServerToolAvailable,
+ isAgentServerUnavailableError,
+ isAgentServerUnknownVersionError,
+ isAgentServerUnsupportedVersionError,
loadAgentServerInfo,
MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
} from "#/api/agent-server-compatibility";
-const { getServerInfoMock } = vi.hoisted(() => ({
+const { getServerInfoMock, getSettingsMock } = vi.hoisted(() => ({
getServerInfoMock: vi.fn(),
+ getSettingsMock: vi.fn(),
}));
vi.mock("@openhands/typescript-client/clients", () => ({
@@ -28,11 +43,17 @@ vi.mock("@openhands/typescript-client/clients", () => ({
}),
SettingsClient: vi.fn(function SettingsClientMock() {
return {
- getSettings: vi.fn(),
+ getSettings: getSettingsMock,
};
}),
}));
+const httpError = (status: number) =>
+ Object.assign(new Error(`HTTP ${status}`), {
+ name: "HttpError",
+ status,
+ });
+
const cloudBackend: Backend = {
id: "prod",
name: "Production",
@@ -51,22 +72,57 @@ const localBackend: Backend = {
beforeEach(() => {
window.localStorage.clear();
- clearCachedAgentServerInfo();
__resetActiveStoreForTests();
getServerInfoMock.mockReset();
+ getSettingsMock.mockReset();
vi.mocked(ServerClient).mockClear();
+ vi.mocked(SettingsClient).mockClear();
getServerInfoMock.mockResolvedValue({
version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
});
+ getSettingsMock.mockResolvedValue({});
+ clearCachedAgentServerInfo();
+ delete (window as unknown as Record<string, unknown>)
+ .__AGENT_CANVAS_AUTH_REQUIRED__;
});
afterEach(() => {
+ vi.restoreAllMocks();
window.localStorage.clear();
- clearCachedAgentServerInfo();
__resetActiveStoreForTests();
+ clearCachedAgentServerInfo();
+ delete (window as unknown as Record<string, unknown>)
+ .__AGENT_CANVAS_AUTH_REQUIRED__;
});
describe("loadAgentServerInfo", () => {
+ it("exposes stable compatibility error contracts through the public alias", () => {
+ expect(AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE).toBe(
+ "AGENT_SERVER_UNSUPPORTED_VERSION",
+ );
+ expect(AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE).toBe(
+ "AGENT_SERVER_UNKNOWN_VERSION",
+ );
+ expect(
+ isAgentServerUnavailableError(new AgentServerUnavailableError()),
+ ).toBe(true);
+ expect(
+ isAgentServerUnsupportedVersionError(
+ new AgentServerUnsupportedVersionError("1.27.0"),
+ ),
+ ).toBe(true);
+ expect(
+ isAgentServerUnknownVersionError(
+ new AgentServerUnknownVersionError("dev-build"),
+ ),
+ ).toBe(true);
+
+ (
+ window as unknown as Record<string, unknown>
+ ).__AGENT_CANVAS_AUTH_REQUIRED__ = true;
+ expect(isAgentServerAuthError(httpError(401))).toBe(true);
+ });
+
it("returns server info when the local backend reports the minimum compatible version", async () => {
setRegisteredBackends([localBackend]);
setActiveSelection({ backendId: localBackend.id });
@@ -77,22 +133,25 @@ describe("loadAgentServerInfo", () => {
version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
});
expect(ServerClient).toHaveBeenCalled();
+ expect(SettingsClient).not.toHaveBeenCalled();
});
- it("returns cached server info only for the probed backend host", async () => {
- setRegisteredBackends([localBackend]);
- setActiveSelection({ backendId: localBackend.id });
+ it("omits an empty local API key from the client options", async () => {
+ const backendWithoutKey = { ...localBackend, apiKey: "" };
+ setRegisteredBackends([backendWithoutKey]);
+ setActiveSelection({ backendId: backendWithoutKey.id });
await loadAgentServerInfo();
- expect(getCachedAgentServerInfo({ host: localBackend.host })).toMatchObject(
- {
- version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
- },
+ expect(ServerClient).toHaveBeenCalledWith(
+ expect.objectContaining({
+ host: backendWithoutKey.host,
+ timeout: 5000,
+ }),
+ );
+ expect(vi.mocked(ServerClient).mock.calls[0]?.[0]).not.toHaveProperty(
+ "apiKey",
);
- expect(
- getCachedAgentServerInfo({ host: "http://localhost:9001" }),
- ).toBeNull();
});
it("throws AgentServerUnsupportedVersionError when the local backend is too old", async () => {
@@ -133,9 +192,249 @@ describe("loadAgentServerInfo", () => {
// Empty registry β€” no backends at all (frontend-only with no config).
setRegisteredBackends([]);
- await expect(loadAgentServerInfo()).rejects.toThrow(
+ await expect(loadAgentServerInfo()).rejects.toMatchObject({
+ name: AgentServerUnavailableError.name,
+ message:
+ "No agent server backend is configured yet. Add a backend to get started.",
+ details: "No backend configured",
+ noBackendConfigured: true,
+ });
+ expect(ServerClient).not.toHaveBeenCalled();
+ });
+
+ it("preserves a 401 returned by the server-info probe", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ const unauthorized = httpError(401);
+ getServerInfoMock.mockRejectedValue(unauthorized);
+
+ await expect(loadAgentServerInfo()).rejects.toBe(unauthorized);
+ });
+
+ it("wraps an HTTP server-info failure as an unavailable error", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ getServerInfoMock.mockRejectedValue(httpError(503));
+
+ await expect(loadAgentServerInfo()).rejects.toMatchObject({
+ name: AgentServerUnavailableError.name,
+ details: "HTTP 503",
+ noBackendConfigured: false,
+ });
+ });
+
+ it("wraps a non-Error server-info failure without fabricated details", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ getServerInfoMock.mockRejectedValue("connection closed");
+
+ await expect(loadAgentServerInfo()).rejects.toMatchObject({
+ name: AgentServerUnavailableError.name,
+ details: null,
+ });
+ });
+
+ it("validates the key against settings when runtime auth is required", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ (
+ window as unknown as Record<string, unknown>
+ ).__AGENT_CANVAS_AUTH_REQUIRED__ = true;
+
+ await expect(loadAgentServerInfo()).resolves.toMatchObject({
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ });
+
+ expect(ServerClient).toHaveBeenCalledWith(
+ expect.objectContaining({
+ host: localBackend.host,
+ apiKey: localBackend.apiKey,
+ timeout: 5000,
+ }),
+ );
+ expect(SettingsClient).toHaveBeenCalledWith(
+ expect.objectContaining({
+ host: localBackend.host,
+ apiKey: localBackend.apiKey,
+ timeout: 5000,
+ }),
+ );
+ expect(getSettingsMock).toHaveBeenCalledTimes(1);
+ });
+
+ it("preserves a 401 returned by the authenticated settings probe", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ (
+ window as unknown as Record<string, unknown>
+ ).__AGENT_CANVAS_AUTH_REQUIRED__ = true;
+ const unauthorized = httpError(401);
+ getSettingsMock.mockRejectedValue(unauthorized);
+
+ await expect(loadAgentServerInfo()).rejects.toBe(unauthorized);
+ });
+
+ it("continues after a non-401 settings probe failure", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ (
+ window as unknown as Record<string, unknown>
+ ).__AGENT_CANVAS_AUTH_REQUIRED__ = true;
+ const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const forbidden = httpError(403);
+ getSettingsMock.mockRejectedValue(forbidden);
+
+ await expect(loadAgentServerInfo()).resolves.toMatchObject({
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ });
+ expect(warning).toHaveBeenCalledWith(
+ "[agent-server] getSettings() probe failed (non-401):",
+ forbidden,
+ );
+ warning.mockRestore();
+ });
+
+ it("uses advertised tools after a successful probe", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ getServerInfoMock.mockResolvedValue({
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ usable_tools: ["terminal"],
+ });
+
+ await loadAgentServerInfo();
+
+ expect(isAgentServerToolAvailable("terminal")).toBe(true);
+ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(false);
+ clearCachedAgentServerInfo();
+ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(true);
+ });
+
+ it("clears advertised tools when a later server-info probe fails", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ getServerInfoMock.mockResolvedValue({
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ usable_tools: ["terminal"],
+ });
+ await loadAgentServerInfo();
+ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(false);
+
+ getServerInfoMock.mockRejectedValue(new Error("connection closed"));
+
+ await expect(loadAgentServerInfo()).rejects.toBeInstanceOf(
AgentServerUnavailableError,
);
- expect(ServerClient).not.toHaveBeenCalled();
+ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(true);
+ });
+
+ it("allows tools when the server does not advertise a tool list", async () => {
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ getServerInfoMock.mockResolvedValue({
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ usable_tools: null,
+ });
+
+ await loadAgentServerInfo();
+
+ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(true);
+ clearCachedAgentServerInfo();
+ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(true);
+ });
+ it("returns cached server info only for the probed backend host", async () => {
+ expect(getCachedAgentServerInfo()).toBeNull();
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+
+ await loadAgentServerInfo();
+
+ expect(getCachedAgentServerInfo()).toEqual({
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ });
+
+ expect(getCachedAgentServerInfo({ host: localBackend.host })).toMatchObject(
+ {
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ },
+ );
+ expect(
+ getCachedAgentServerInfo({ host: "http://localhost:9001" }),
+ ).toBeNull();
+ });
+});
+
+describe("local backend validation", () => {
+ it.each(["session-key", ""])(
+ "authenticates before probing server info with the explicit backend and key %s",
+ async (apiKey) => {
+ setRegisteredBackends([{ ...localBackend, apiKey: "" }]);
+ setActiveSelection({ backendId: localBackend.id });
+ const backend = { host: "http://explicit.example.test", apiKey };
+ await expect(validateLocalBackend(backend, 1234)).resolves.toBe(
+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ );
+ const options = {
+ host: backend.host,
+ timeout: 1234,
+ ...(apiKey ? { apiKey } : {}),
+ };
+ expect(SettingsClient).toHaveBeenCalledWith(
+ expect.objectContaining(options),
+ );
+ expect(ServerClient).toHaveBeenCalledWith(
+ expect.objectContaining(options),
+ );
+ if (!apiKey)
+ expect(vi.mocked(SettingsClient).mock.calls[0][0]).not.toHaveProperty(
+ "apiKey",
+ );
+ expect(getSettingsMock.mock.invocationCallOrder[0]).toBeLessThan(
+ getServerInfoMock.mock.invocationCallOrder[0],
+ );
+ },
+ );
+ it("translates an authentication failure and does not probe the server", async () => {
+ expect(INVALID_BACKEND_API_KEY_ERROR).toBe("Invalid API key");
+ getSettingsMock.mockRejectedValue(httpError(401));
+ await expect(validateLocalBackend(localBackend, 1000)).rejects.toThrow(
+ INVALID_BACKEND_API_KEY_ERROR,
+ );
+ expect(getServerInfoMock).not.toHaveBeenCalled();
+ });
+ it("preserves a non-authentication probe failure", async () => {
+ const failure = new Error("network failure");
+ getServerInfoMock.mockRejectedValue(failure);
+ await expect(validateLocalBackend(localBackend, 1000)).rejects.toBe(
+ failure,
+ );
+ });
+});
+
+describe("cached display versions", () => {
+ it("returns no versions without a cache and limits populated values to the active host", async () => {
+ expect(getCachedAgentServerVersion()).toBeNull();
+ expect(getCachedAgentServerSdkVersion()).toBeNull();
+ setRegisteredBackends([localBackend]);
+ setActiveSelection({ backendId: localBackend.id });
+ getServerInfoMock.mockResolvedValue({
+ version: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ sdk_version: "9.8.7",
+ });
+ await loadAgentServerInfo();
+ expect(getCachedAgentServerVersion()).toBe(
+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ );
+ expect(getCachedAgentServerSdkVersion()).toBe("9.8.7");
+ expect(getCachedAgentServerVersion(localBackend.host)).toBe(
+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ );
+ expect(getCachedAgentServerSdkVersion(localBackend.host)).toBe("9.8.7");
+ expect(getCachedAgentServerVersion("http://elsewhere.test")).toBeNull();
+ expect(getCachedAgentServerSdkVersion("http://elsewhere.test")).toBeNull();
+ setRegisteredBackends([cloudBackend]);
+ setActiveSelection({ backendId: cloudBackend.id });
+ expect(getCachedAgentServerVersion(localBackend.host)).toBeNull();
+ expect(getCachedAgentServerSdkVersion(localBackend.host)).toBeNull();
});
});
diff --git a/src/api/agent-server-compatibility-prerelease.test.ts b/src/api/agent-server-compatibility-prerelease.test.ts
new file mode 100644
index 0000000000..da08039e5d
--- /dev/null
+++ b/src/api/agent-server-compatibility-prerelease.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("../../config/defaults.json", () => ({
+ default: {
+ compatibility: {
+ minimumAgentServer: "1.28.0-rc.2",
+ },
+ },
+}));
+
+import {
+ AgentServerUnsupportedVersionError,
+ assertAgentServerVersionIsSupported,
+ compareAgentServerVersions,
+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ type AgentServerInfo,
+} from "./agent-server-compatibility";
+
+const serverInfo = (version: string): AgentServerInfo =>
+ ({ version }) as AgentServerInfo;
+
+describe("agent-server prerelease minimum compatibility", () => {
+ it("accepts the stable release for a prerelease minimum", () => {
+ expect(MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION).toBe("1.28.0-rc.2");
+
+ expect(() =>
+ assertAgentServerVersionIsSupported(serverInfo("1.28.0")),
+ ).not.toThrow();
+ expect(compareAgentServerVersions("1.28.0", "1.28.0-rc.2")).toBe(1);
+ });
+
+ it("normalizes decorated input versions through the public comparator", () => {
+ expect(compareAgentServerVersions(" v1.28.0+build.7 ", "1.28.0")).toBe(0);
+ });
+
+ it("compares prerelease identifiers at the configured version boundary", () => {
+ expect(() =>
+ assertAgentServerVersionIsSupported(serverInfo("1.28.0-rc.1")),
+ ).toThrow(AgentServerUnsupportedVersionError);
+ expect(() =>
+ assertAgentServerVersionIsSupported(serverInfo("1.28.0-rc.2")),
+ ).not.toThrow();
+ expect(() =>
+ assertAgentServerVersionIsSupported(serverInfo("1.28.0-rc.3")),
+ ).not.toThrow();
+ });
+});
diff --git a/src/api/agent-server-compatibility.test.ts b/src/api/agent-server-compatibility.test.ts
index bde7fa0e6b..8e95df8222 100644
--- a/src/api/agent-server-compatibility.test.ts
+++ b/src/api/agent-server-compatibility.test.ts
@@ -1,49 +1,264 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
import {
+ AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE,
+ AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE,
+ AgentServerUnavailableError,
AgentServerUnknownVersionError,
AgentServerUnsupportedVersionError,
assertAgentServerVersionIsSupported,
- getDisplayAgentServerSdkVersion,
getDisplayAgentServerVersion,
+ getDisplayAgentServerSdkVersion,
+ isAgentServerAuthError,
+ isAgentServerUnavailableError,
+ isAgentServerUnknownVersionError,
+ isAgentServerUnsupportedVersionError,
+ isSdkHttpError,
+ isSdkHttpStatusError,
+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
type AgentServerInfo,
} from "./agent-server-compatibility";
-const serverInfo = (version?: string, sdkVersion?: string): AgentServerInfo =>
+const serverInfo = (version?: unknown, sdkVersion?: string): AgentServerInfo =>
({ version, sdk_version: sdkVersion }) as AgentServerInfo;
+const httpError = (status: unknown): Error & { status: unknown } =>
+ Object.assign(new Error(`HTTP ${String(status)}`), {
+ name: "HttpError",
+ status,
+ });
+
+const getThrownError = (action: () => void): Error => {
+ try {
+ action();
+ } catch (error) {
+ if (error instanceof Error) return error;
+ throw error;
+ }
+ throw new Error("Expected action to throw");
+};
+
+afterEach(() => {
+ delete (window as unknown as Record<string, unknown>)
+ .__AGENT_CANVAS_AUTH_REQUIRED__;
+});
+
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.each([
+ { version: undefined, reported: null },
+ { version: 128, reported: null },
+ { version: "", reported: null },
+ { version: " ", reported: null },
+ { version: "unknown", reported: "unknown" },
+ { version: " UNKNOWN ", reported: "UNKNOWN" },
+ ])("classifies $version as an unknown version", ({ version, reported }) => {
+ const error = getThrownError(() =>
+ assertAgentServerVersionIsSupported(serverInfo(version)),
+ );
+
+ expect(error).toBeInstanceOf(AgentServerUnknownVersionError);
+ expect(error).toMatchObject({
+ code: AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE,
+ actualVersion: reported,
+ requiredVersion: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ });
});
- it("classifies malformed versions separately from old versions", () => {
- expect(() =>
- assertAgentServerVersionIsSupported(serverInfo("dev-build")),
- ).toThrow(AgentServerUnknownVersionError);
+ it.each([
+ "dev-build",
+ "1.28",
+ "1.28.0.1",
+ "1.two.0",
+ "1.28.v0",
+ "Infinity.28.0",
+ "V1.28.0",
+ ])("classifies malformed version %s as unknown", (version) => {
+ const error = getThrownError(() =>
+ assertAgentServerVersionIsSupported(serverInfo(version)),
+ );
+
+ expect(error).toBeInstanceOf(AgentServerUnknownVersionError);
+ expect(error).toMatchObject({
+ actualVersion: version,
+ code: AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE,
+ });
});
- it("keeps valid but too-old versions on the unsupported-version path", () => {
+ it.each(["0.99.99", "1.27.999", "1.28.0-rc.1"])(
+ "rejects older version %s",
+ (version) => {
+ const error = getThrownError(() =>
+ assertAgentServerVersionIsSupported(serverInfo(version)),
+ );
+
+ expect(error).toBeInstanceOf(AgentServerUnsupportedVersionError);
+ expect(error).toMatchObject({
+ actualVersion: version,
+ code: AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE,
+ requiredVersion: MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ });
+ },
+ );
+
+ it.each([
+ MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION,
+ "1.28.1",
+ "1.29.0",
+ "2.0.0",
+ " v1.28.0+build.7 ",
+ ])("accepts compatible version %s", (version) => {
expect(() =>
- assertAgentServerVersionIsSupported(serverInfo("0.0.1")),
- ).toThrow(AgentServerUnsupportedVersionError);
+ assertAgentServerVersionIsSupported(serverInfo(version)),
+ ).not.toThrow();
});
- 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");
+ it.each([
+ { version: undefined, display: null },
+ { version: "unknown", display: null },
+ { version: "dev-build", display: null },
+ { version: "1.28.0", display: "1.28.0" },
+ { version: " v1.28.0+build.7 ", display: "v1.28.0+build.7" },
+ { version: "1.28.0-rc.1", display: "1.28.0-rc.1" },
+ ])("displays $version as $display", ({ version, display }) => {
+ expect(getDisplayAgentServerVersion(serverInfo(version))).toBe(display);
});
+});
+describe("agent-server compatibility errors", () => {
+ it("publishes stable error codes for callers", () => {
+ expect(AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE).toBe(
+ "AGENT_SERVER_UNSUPPORTED_VERSION",
+ );
+ expect(AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE).toBe(
+ "AGENT_SERVER_UNKNOWN_VERSION",
+ );
+ });
+
+ it("constructs unavailable errors for connection and missing-backend failures", () => {
+ expect(new AgentServerUnavailableError()).toMatchObject({
+ name: "AgentServerUnavailableError",
+ message:
+ "Could not connect to the configured agent server. Make sure it is running and reachable, then reload the page.",
+ details: null,
+ noBackendConfigured: false,
+ });
+ expect(
+ new AgentServerUnavailableError("No backend configured", {
+ noBackendConfigured: true,
+ }),
+ ).toMatchObject({
+ name: "AgentServerUnavailableError",
+ message:
+ "No agent server backend is configured yet. Add a backend to get started.",
+ details: "No backend configured",
+ noBackendConfigured: true,
+ });
+ });
+
+ it("describes unsupported and unknown versions exactly", () => {
+ expect(new AgentServerUnsupportedVersionError("1.27.0").message).toBe(
+ `Agent Canvas requires agent-server ${MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION} or newer; this backend is running 1.27.0. Please upgrade the agent-server backend.`,
+ );
+ expect(new AgentServerUnknownVersionError(null).message).toBe(
+ `Could not determine this backend's agent-server version. 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.`,
+ );
+ expect(new AgentServerUnknownVersionError("dev-build").message).toBe(
+ `Could not determine this backend's agent-server version. It reported "dev-build". 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.`,
+ );
+ });
+
+ it.each([
+ new AgentServerUnavailableError(),
+ { name: "AgentServerUnavailableError" },
+ { name: "AgentServerUnsupportedVersionError" },
+ { name: "AgentServerUnknownVersionError" },
+ ])("recognizes unavailable error %#", (error) => {
+ expect(isAgentServerUnavailableError(error)).toBe(true);
+ });
+
+ it.each([
+ null,
+ "AgentServerUnavailableError",
+ {},
+ { name: "AnotherError" },
+ { name: "" },
+ ])("rejects unavailable lookalike %#", (error) => {
+ expect(isAgentServerUnavailableError(error)).toBe(false);
+ });
+
+ it.each([
+ new AgentServerUnsupportedVersionError("1.27.0"),
+ { code: AGENT_SERVER_UNSUPPORTED_VERSION_ERROR_CODE },
+ ])("recognizes unsupported-version error %#", (error) => {
+ expect(isAgentServerUnsupportedVersionError(error)).toBe(true);
+ });
+
+ it.each([
+ null,
+ "AGENT_SERVER_UNSUPPORTED_VERSION",
+ {},
+ { code: "ANOTHER_ERROR" },
+ ])("rejects unsupported-version lookalike %#", (error) => {
+ expect(isAgentServerUnsupportedVersionError(error)).toBe(false);
+ });
+
+ it.each([
+ new AgentServerUnknownVersionError("dev-build"),
+ { code: AGENT_SERVER_UNKNOWN_VERSION_ERROR_CODE },
+ ])("recognizes unknown-version error %#", (error) => {
+ expect(isAgentServerUnknownVersionError(error)).toBe(true);
+ });
+
+ it.each([
+ null,
+ "AGENT_SERVER_UNKNOWN_VERSION",
+ {},
+ { code: "ANOTHER_ERROR" },
+ ])("rejects unknown-version lookalike %#", (error) => {
+ expect(isAgentServerUnknownVersionError(error)).toBe(false);
+ });
+});
+
+describe("SDK HTTP error classification", () => {
+ it("requires an Error named HttpError with a numeric status", () => {
+ expect(isSdkHttpError(httpError(401))).toBe(true);
+ expect(isSdkHttpError({ name: "HttpError", status: 401 })).toBe(false);
+ expect(isSdkHttpError(new Error("HTTP 401"))).toBe(false);
+ expect(
+ isSdkHttpError(
+ Object.assign(new Error("HTTP 401"), {
+ name: "AnotherError",
+ status: 401,
+ }),
+ ),
+ ).toBe(false);
+ expect(
+ isSdkHttpError(Object.assign(new Error(), { name: "HttpError" })),
+ ).toBe(false);
+ expect(isSdkHttpError(httpError("401"))).toBe(false);
+ });
+
+ it("matches only the requested HTTP status", () => {
+ expect(isSdkHttpStatusError(httpError(401), 401)).toBe(true);
+ expect(isSdkHttpStatusError(httpError(403), 401)).toBe(false);
+ expect(isSdkHttpStatusError(new Error("network"), 401)).toBe(false);
+ });
+
+ it("only treats 401 as an auth error when public auth is required", () => {
+ const authWindow = window as unknown as Record<string, unknown>;
+ expect(isAgentServerAuthError(httpError(401))).toBe(false);
+
+ authWindow.__AGENT_CANVAS_AUTH_REQUIRED__ = true;
+ expect(isAgentServerAuthError(httpError(401))).toBe(true);
+ expect(isAgentServerAuthError(httpError(403))).toBe(false);
+ });
it("uses sdk_version as the agent-server version fallback", () => {
expect(getDisplayAgentServerVersion(serverInfo(undefined, "1.36.1"))).toBe(
"1.36.1",
);
expect(() =>
- assertAgentServerVersionIsSupported(serverInfo(undefined, "1.36.1")),
+ assertAgentServerVersionIsSupported(
+ serverInfo(undefined, MINIMUM_COMPATIBLE_AGENT_SERVER_VERSION),
+ ),
).not.toThrow();
});
@@ -56,3 +271,12 @@ describe("agent-server version compatibility", () => {
);
});
});
+
+it.each([undefined, "unknown"])(
+ "does not display an absent or unknown SDK version: %s",
+ (version) => {
+ expect(
+ getDisplayAgentServerSdkVersion(serverInfo(version, version)),
+ ).toBeNull();
+ },
+);