π OpenHands: AI-Driven Development
Gate browser tool requests on server support (#64)
Graham Neubig6a628ede6e2e
diff --git a/.pr/issue-64/browser-tool-advertised.gif b/.pr/issue-64/browser-tool-advertised.gifnew file mode 100644index 0000000000..0b8e2b3d62Binary files /dev/null and b/.pr/issue-64/browser-tool-advertised.gif differdiff --git a/.pr/issue-64/browser-tool-advertised.png b/.pr/issue-64/browser-tool-advertised.pngnew file mode 100644index 0000000000..c120831c46Binary files /dev/null and b/.pr/issue-64/browser-tool-advertised.png differdiff --git a/.pr/issue-64/browser-tool-not-advertised.gif b/.pr/issue-64/browser-tool-not-advertised.gifnew file mode 100644index 0000000000..b51c2d1d62Binary files /dev/null and b/.pr/issue-64/browser-tool-not-advertised.gif differdiff --git a/.pr/issue-64/browser-tool-not-advertised.png b/.pr/issue-64/browser-tool-not-advertised.pngnew file mode 100644index 0000000000..01bf2cd382Binary files /dev/null and b/.pr/issue-64/browser-tool-not-advertised.png differdiff --git a/AGENTS.md b/AGENTS.mdindex dfd9bcc9da..66614413ad 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -46,6 +46,8 @@- runtime git panels: `/api/git/changes`, `/api/git/diff`- Static mock verification needs a build created with `VITE_MOCK_API=true` (use `npm run build:mock`); the client must start MSW whenever that flag is enabled, even in production/static builds, otherwise routes like `/settings` and the conversations pane fall through to the static server and crash on undefined `.filter`/`.map` assumptions.- Frontend compatibility guard: `OptionService.getConfig()` now uses `/server_info.version` to block unsupported agent-server versions before the app loads. Git history in `software-agent-sdk` shows `/api/settings/agent-schema` and `/api/settings/conversation-schema` first shipped in tag `v1.17.0`, so Agent Canvas currently treats `< 1.17.0` (or unknown/unparseable versions) as incompatible, `useConfig` stops retrying that case, and `src/root.tsx` renders a blocking unsupported-version notice on every route.+- `/server_info` tool capability metadata from `software-agent-sdk` PR #3028 ended up shipping as `usable_tools` (not `available_tools`). Frontend browser-tool gating should key off `usable_tools`, and still default to allowing tools when the server does not advertise tool metadata.+- Useful regression tests for mock mode live in `__tests__/api/option-service.test.ts`, `__tests__/api/mock-conversation-handlers.test.ts`, and `__tests__/api/mock-settings-handlers.test.ts`.- Browser-verified mock-mode tour artifact was generated at `artifacts/frontend-tour.gif`.- Live `agent_server` compatibility quirks discovered during browser verification:diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.tsindex ef8a66ad6e..28da05b8b4 100644--- a/__tests__/api/agent-server-adapter.test.ts+++ b/__tests__/api/agent-server-adapter.test.ts@@ -1,4 +1,4 @@-import { describe, expect, it, vi } from "vitest";+import { beforeEach, describe, expect, it, vi } from "vitest";import {buildStartConversationRequest,@@ -8,11 +8,13 @@ import {} from "#/api/agent-server-adapter";import { DEFAULT_SETTINGS } from "#/services/settings";-const { mockGetAgentServerWorkingDir } = vi.hoisted(() => ({- mockGetAgentServerWorkingDir: vi.fn(- () => "/workspace/project/agent-canvas",- ),-}));+const { mockGetAgentServerWorkingDir, mockIsAgentServerToolAvailable } =+ vi.hoisted(() => ({+ mockGetAgentServerWorkingDir: vi.fn(+ () => "/workspace/project/agent-canvas",+ ),+ mockIsAgentServerToolAvailable: vi.fn(() => true),+ }));vi.mock("#/api/agent-server-config", () => ({getAgentServerBaseUrl: vi.fn(() => "http://127.0.0.1:8000"),@@ -21,6 +23,15 @@ vi.mock("#/api/agent-server-config", () => ({getConfiguredWorkerUrls: vi.fn(() => []),}));+vi.mock("#/api/agent-server-compatibility", () => ({+ isAgentServerToolAvailable: mockIsAgentServerToolAvailable,+}));++beforeEach(() => {+ mockIsAgentServerToolAvailable.mockReturnValue(true);+});++describe("buildStartConversationRequest", () => {it("uses nested settings as the source of truth and keeps SDK tool names", () => {const payload = buildStartConversationRequest({@@ -85,6 +96,31 @@ describe("buildStartConversationRequest", () => {expect(payload.initial_message.content[0]?.text).toBe("hello");});++ it("omits browser_tool_set when the server does not advertise browser support", () => {+ mockIsAgentServerToolAvailable.mockReturnValue(false);++ const payload = buildStartConversationRequest({+ settings: {+ ...DEFAULT_SETTINGS,+ agent_settings: {+ ...DEFAULT_SETTINGS.agent_settings,+ llm: { model: "nested-model" },+ },+ },+ }) as {+ agent: {+ tools: Array<{ name: string; params: Record<string, unknown> }>;+ };+ };++ expect(payload.agent.tools).toEqual([+ { name: "terminal", params: {} },+ { name: "file_editor", params: {} },+ { name: "task_tracker", params: {} },+ ]);+ });+it("derives confirmation and security settings the same way as OpenHands", () => {const payload = buildStartConversationRequest({settings: {diff --git a/__tests__/api/option-service.test.ts b/__tests__/api/option-service.test.tsindex 7db1b1c92f..11a32b1baa 100644--- a/__tests__/api/option-service.test.ts+++ b/__tests__/api/option-service.test.ts@@ -1,14 +1,21 @@-import { describe, expect, it } from "vitest";+import { beforeEach, describe, expect, it } from "vitest";import { http, HttpResponse } from "msw";import {AgentServerIncompatibilityError,AgentServerUnavailableError,+ clearCachedAgentServerInfo,+ isAgentServerToolAvailable,MINIMUM_SUPPORTED_AGENT_SERVER_VERSION,} from "#/api/agent-server-compatibility";import OptionService from "#/api/option-service/option-service.api";import { server } from "#/mocks/node";describe("OptionService", () => {+ beforeEach(() => {+ clearCachedAgentServerInfo();+ });++it("returns config in mock mode without a live backend", async () => {const config = await OptionService.getConfig();@@ -64,6 +71,41 @@ describe("OptionService", () => {});});+ it("caches usable_tools from server_info for later tool gating", async () => {+ server.use(+ http.get("/server_info", () =>+ HttpResponse.json({+ uptime: 0,+ idle_time: 0,+ version: MINIMUM_SUPPORTED_AGENT_SERVER_VERSION,+ usable_tools: ["terminal", "file_editor", "task_tracker"],+ }),+ ),+ );++ await OptionService.getConfig();++ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(false);+ expect(isAgentServerToolAvailable("terminal")).toBe(true);+ });++ it("allows all tools when the server does not advertise tool metadata", async () => {+ server.use(+ http.get("/server_info", () =>+ HttpResponse.json({+ uptime: 0,+ idle_time: 0,+ version: MINIMUM_SUPPORTED_AGENT_SERVER_VERSION,+ }),+ ),+ );++ await OptionService.getConfig();++ expect(isAgentServerToolAvailable("browser_tool_set")).toBe(true);+ expect(isAgentServerToolAvailable("terminal")).toBe(true);+ });+it("returns models from mocked LLM endpoints", async () => {const models = await OptionService.getModels();diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.tsindex 1de5da6f68..5ad52abac1 100644--- a/src/api/agent-server-adapter.ts+++ b/src/api/agent-server-adapter.ts@@ -1,6 +1,7 @@import { DEFAULT_SETTINGS } from "#/services/settings";-import { Settings, SettingsValue } from "#/types/settings";import { ExecutionStatus } from "#/types/agent-server/core";+import { Settings, SettingsValue } from "#/types/settings";+import { isAgentServerToolAvailable } from "./agent-server-compatibility";import { getAgentServerWorkingDir } from "./agent-server-config";import { getEffectiveLocalBackend } from "./backend-registry/active-store";import {@@ -190,7 +191,10 @@ function getConversationSecurityAnalyzer(conversationSettings: SettingsRecord) {function getAgentTools() {const tools = DEFAULT_TOOL_NAMES.map((name) => ({ name, params: {} }));- if (browserToolsEnabled()) {+ if (+ browserToolsEnabled() &&+ isAgentServerToolAvailable(BROWSER_TOOL_SET_NAME)+ ) {tools.push({ name: BROWSER_TOOL_SET_NAME, params: {} });}return tools;diff --git a/src/api/agent-server-compatibility.ts b/src/api/agent-server-compatibility.tsindex e61d012955..359082f13f 100644--- a/src/api/agent-server-compatibility.ts+++ b/src/api/agent-server-compatibility.ts@@ -1,14 +1,30 @@/* eslint-disable max-classes-per-file */import { HttpError } from "@openhands/typescript-client/client/http-client";import { getBundledBackend } from "#/api/backend-registry/bundled";-import { createServerClient, type ServerInfo } from "#/api/typescript-client";+import {+ createServerClient,+ type ServerInfo as BaseServerInfo,+} from "#/api/typescript-client";export const MINIMUM_SUPPORTED_AGENT_SERVER_VERSION = "1.17.0";const AGENT_SERVER_INFO_TIMEOUT_MS = 5000;const SEMVER_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/;-const getServerVersion = (serverInfo: ServerInfo): string => serverInfo.version;+export interface AgentServerInfo extends BaseServerInfo {+ usable_tools?: string[] | null;+}++let cachedAgentServerInfo: AgentServerInfo | null = null;++const getServerVersion = (serverInfo: AgentServerInfo): string => serverInfo.version;++const getAdvertisedTools = (serverInfo: AgentServerInfo | null) => {+ if (Array.isArray(serverInfo?.usable_tools)) {+ return serverInfo.usable_tools;+ }+ return null;+};const parseSemver = (version: string | null,@@ -94,21 +110,34 @@ export const isAgentServerUnavailableError = ("name" in error &&error.name === "AgentServerUnavailableError");+export function clearCachedAgentServerInfo() {+ cachedAgentServerInfo = null;+}++export function isAgentServerToolAvailable(toolName: string) {+ const availableTools = getAdvertisedTools(cachedAgentServerInfo);+ if (!Array.isArray(availableTools)) {+ return true;+ }+ return availableTools.includes(toolName);+}+export async function ensureCompatibleAgentServer() {// The compatibility check is a *local* agent-server concern β it verifies// that the runtime hosting the GUI is at the right version. It must NEVER// run against the active backend, because cloud SaaS hosts don't expose// /api/server_info and would fail with a CORS error besides.const bundled = getBundledBackend();- let serverInfo: ServerInfo;+ let serverInfo: AgentServerInfo;try {- serverInfo = await createServerClient({+ serverInfo = (await createServerClient({host: bundled.host,sessionApiKey: bundled.apiKey || null,timeout: AGENT_SERVER_INFO_TIMEOUT_MS,- }).getServerInfo();+ }).getServerInfo()) as AgentServerInfo;} catch (error) {+ clearCachedAgentServerInfo();if (error instanceof HttpError) {throw error;}@@ -117,6 +146,7 @@ export async function ensureCompatibleAgentServer() {throw new AgentServerUnavailableError(details);}+ cachedAgentServerInfo = serverInfo;const serverVersion = getServerVersion(serverInfo);if (!isSupportedAgentServerVersion(serverVersion)) {diff --git a/src/mocks/settings-handlers.ts b/src/mocks/settings-handlers.tsindex 14e909a78e..401e3487e2 100644--- a/src/mocks/settings-handlers.ts+++ b/src/mocks/settings-handlers.ts@@ -343,6 +343,12 @@ export const SETTINGS_HANDLERS = [uptime: 0,idle_time: 0,version: "1.18.1",+ usable_tools: [+ "terminal",+ "file_editor",+ "task_tracker",+ "browser_tool_set",+ ],agents: ["CodeActAgent"],default_agent: "CodeActAgent",models: MOCK_MODELS,diff --git a/vitest.setup.ts b/vitest.setup.tsindex fe6e71e918..2c0f9c10de 100644--- a/vitest.setup.ts+++ b/vitest.setup.ts@@ -74,10 +74,19 @@ beforeAll(() => {server.listen({ onUnhandledRequest: "bypass" });vi.stubGlobal("ResizeObserver", MockResizeObserver);});-afterEach(() => {+afterEach(async () => {server.resetHandlers();// Cleanup the document body after each testcleanup();+ // Drain any queued microtasks before jsdom is torn down between test files.+ // Without this, async state updates queued during render (for example by+ // HeroUI v2 components wrapped in framer-motion's LazyMotion) can resolve+ // after `window` is gone and trigger spurious unhandled rejections in+ // react-dom's `resolveUpdatePriority`. We use `Promise.resolve()` (a+ // microtask) rather than `setTimeout(0)` so this stays compatible with+ // tests that install fake timers.+ await Promise.resolve();+ await Promise.resolve();});afterAll(() => {server.close();