Skip to content

πŸ™Œ 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.gif
new file mode 100644
index 0000000000..0b8e2b3d62
Binary files /dev/null and b/.pr/issue-64/browser-tool-advertised.gif differ
diff --git a/.pr/issue-64/browser-tool-advertised.png b/.pr/issue-64/browser-tool-advertised.png
new file mode 100644
index 0000000000..c120831c46
Binary files /dev/null and b/.pr/issue-64/browser-tool-advertised.png differ
diff --git a/.pr/issue-64/browser-tool-not-advertised.gif b/.pr/issue-64/browser-tool-not-advertised.gif
new file mode 100644
index 0000000000..b51c2d1d62
Binary files /dev/null and b/.pr/issue-64/browser-tool-not-advertised.gif differ
diff --git a/.pr/issue-64/browser-tool-not-advertised.png b/.pr/issue-64/browser-tool-not-advertised.png
new file mode 100644
index 0000000000..01bf2cd382
Binary files /dev/null and b/.pr/issue-64/browser-tool-not-advertised.png differ
diff --git a/AGENTS.md b/AGENTS.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 test
cleanup();
+ // 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();