π 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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();+ },+);