π OpenHands: AI-Driven Development
Fix live agent-server frontend integration
openhandse406274c1242
diff --git a/.env.sample b/.env.sampleindex dba2545e2b..9e3cccbae2 100644--- a/.env.sample+++ b/.env.sample@@ -1,7 +1,7 @@# OpenHands Agent Server targetVITE_BACKEND_HOST="127.0.0.1:8000" # Host:port used by the Vite dev proxyVITE_BACKEND_BASE_URL="http://127.0.0.1:8000" # Base URL used by browser-side direct requests-# VITE_SESSION_API_KEY="" # Optional X-Session-API-Key for authenticated backends+# VITE_SESSION_API_KEY="" # Set to the same value as backend SESSION_API_KEY or OH_SESSION_API_KEYS_0 when auth is enabled# VITE_WORKING_DIR="/workspace/project" # Workspace path used when starting conversations# VITE_WORKER_URLS="" # Optional comma-separated worker URLs for the Browser tab# VITE_ENABLE_BROWSER_TOOLS="true" # Set to false to omit BrowserToolSet from new conversationsdiff --git a/AGENTS.md b/AGENTS.mdindex 93176b23f0..81cc746116 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -22,9 +22,12 @@- 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:+ - Latest `openhands-agent-server` live-mode notes (verified against 1.18.1):+ - `/api/settings/agent-schema` and `/api/settings/conversation-schema` exist on recent servers, but they return `401` when the server was started with `SESSION_API_KEY` or `OH_SESSION_API_KEYS_0`; the frontend must send the same value as `VITE_SESSION_API_KEY` / `X-Session-API-Key`.+ - The provider/model picker should use `/api/llm/providers`, `/api/llm/models`, and `/api/llm/models/verified`; `/api/v1/config/providers/search` and `/api/v1/config/models/search` 404 on current live agent-server releases.+ - When the browser is accessing the frontend through a remote host (for example an All Hands work URL) but `VITE_BACKEND_BASE_URL` points at `127.0.0.1`/`localhost`, browser-side REST calls must fall back to the frontend origin so Vite can proxy `/api` and `/sockets` to the local backend.- `GET /api/conversations` expects repeated `ids` params (`?ids=a&ids=b`), not Axios's default bracket form (`ids[]=a`), so the shared Axios client needs a custom params serializer.- Runtime git panels should prefer the conversation's reported `workspace.working_dir` when present; falling back to `/workspace/project` can produce 500s like `Not a git repository` for direct local workspaces such as `/workspace/project/agent-server-gui`.- - Live settings currently load with the `SDK settings schema unavailable.` placeholder when the backend does not expose `/api/settings/agent-schema` and `/api/settings/conversation-schema`; this is expected for the current local backend.- README expectation: the very first section should be a concrete from-scratch quickstart for running this frontend against a real `openhands-agent-server` (clone, install backend, optional `.env`, run `npm run dev`). Keep live-backend instructions ahead of general project overview.diff --git a/README.md b/README.mdindex b18281079c..93794be86d 100644--- a/README.md+++ b/README.md@@ -34,6 +34,8 @@ openhands-agent-server --host 127.0.0.1 --port 8000The frontend expects the backend at `127.0.0.1:8000` by default, so this is the easiest from-scratch setup.+If you start the backend with `SESSION_API_KEY` or `OH_SESSION_API_KEYS_0`, every `/api/*` route is authenticated with `X-Session-API-Key`. In that case the frontend must send the same key via `VITE_SESSION_API_KEY`.+If you prefer installing from source or want the full SDK setup flow, see the OpenHands SDK docs: <https://docs.openhands.dev/sdk/getting-started>### 3. Optional: create a `.env` file@@ -50,6 +52,7 @@ Then update the values you need:VITE_BACKEND_HOST="127.0.0.1:8000"VITE_BACKEND_BASE_URL="http://127.0.0.1:8000"VITE_FRONTEND_PORT="3001"+# Use the same value as backend SESSION_API_KEY or OH_SESSION_API_KEYS_0 when auth is enabled.# VITE_SESSION_API_KEY="your-session-api-key"# VITE_WORKING_DIR="/absolute/path/to/the-workspace-used-by-agent-server"```@@ -59,6 +62,7 @@ Notes:- `VITE_BACKEND_HOST` is used by the Vite dev proxy for `/api`, `/server_info`, and `/sockets`.- `VITE_BACKEND_BASE_URL` is used by browser-side direct requests. Keep it pointed at the same backend.- `VITE_WORKING_DIR` should match the workspace path the backend will use when starting new conversations.+- If the backend is secured with `SESSION_API_KEY` or `OH_SESSION_API_KEYS_0`, set `VITE_SESSION_API_KEY` to the same value or live requests will fail with `401 Unauthorized`.- If your backend does not require `X-Session-API-Key`, leave `VITE_SESSION_API_KEY` unset.### 4. Start the frontend@@ -77,7 +81,8 @@ After the page opens:- you should be able to open or create a conversation- `/conversations/:id` should load conversation content- `/settings` should load- - if your backend does not expose settings schemas, the UI will show `SDK settings schema unavailable.` instead of crashing+ - on secured backends, make sure `VITE_SESSION_API_KEY` matches the backend session key+ - if your backend is too old to expose settings schemas, the UI will show an actionable `SDK settings schema unavailable.` message instead of crashing### Mock modediff --git a/__tests__/api/agent-server-config.test.ts b/__tests__/api/agent-server-config.test.tsnew file mode 100644index 0000000000..684573c17a--- /dev/null+++ b/__tests__/api/agent-server-config.test.ts@@ -0,0 +1,42 @@+import { afterEach, describe, expect, it } from "vitest";+import { getAgentServerBaseUrl } from "#/api/agent-server-config";++const STORAGE_KEY = "openhands-agent-server-config";+const ORIGINAL_LOCATION = window.location;++function mockWindowLocation(url: string) {+ Object.defineProperty(window, "location", {+ configurable: true,+ value: new URL(url),+ });+}++afterEach(() => {+ window.localStorage.clear();+ Object.defineProperty(window, "location", {+ configurable: true,+ value: ORIGINAL_LOCATION,+ });+});++describe("getAgentServerBaseUrl", () => {+ it("uses the browser origin when a remote browser is pointed at localhost backend config", () => {+ mockWindowLocation("https://work-1.example.dev/settings");+ window.localStorage.setItem(+ STORAGE_KEY,+ JSON.stringify({ baseUrl: "http://127.0.0.1:8000" }),+ );++ expect(getAgentServerBaseUrl()).toBe("https://work-1.example.dev");+ });++ it("preserves a non-local backend URL from stored config", () => {+ mockWindowLocation("https://work-1.example.dev/settings");+ window.localStorage.setItem(+ STORAGE_KEY,+ JSON.stringify({ baseUrl: "https://agent.example.com" }),+ );++ expect(getAgentServerBaseUrl()).toBe("https://agent.example.com");+ });+});diff --git a/__tests__/api/config-service.test.ts b/__tests__/api/config-service.test.tsnew file mode 100644index 0000000000..7499833f89--- /dev/null+++ b/__tests__/api/config-service.test.ts@@ -0,0 +1,27 @@+import { describe, expect, it } from "vitest";+import ConfigService from "#/api/config-service/config-service.api";++describe("ConfigService", () => {+ it("derives providers from llm endpoints", async () => {+ const page = await ConfigService.searchProviders({ limit: 10 });++ expect(page.next_page_id).toBeNull();+ expect(page.items.some((provider) => provider.name === "anthropic")).toBe(true);+ expect(+ page.items.find((provider) => provider.name === "anthropic")?.verified,+ ).toBe(true);+ });++ it("derives provider models from llm endpoints", async () => {+ const page = await ConfigService.searchModels({+ provider__eq: "anthropic",+ limit: 20,+ });++ expect(page.next_page_id).toBeNull();+ expect(page.items.some((model) => model.name === "claude-opus-4-5-20251101")).toBe(+ true,+ );+ expect(page.items.every((model) => model.provider === "anthropic")).toBe(true);+ });+});diff --git a/artifacts/frontend-tour.gif b/artifacts/frontend-tour.gifindex 9526c50531..44a626e586 100644Binary files a/artifacts/frontend-tour.gif and b/artifacts/frontend-tour.gif differdiff --git a/src/api/agent-server-config.ts b/src/api/agent-server-config.tsindex da84fddeb8..6d3b2708d5 100644--- a/src/api/agent-server-config.ts+++ b/src/api/agent-server-config.ts@@ -36,11 +36,46 @@ function normalizeBaseUrl(value?: string | null): string | null {return `http://${trimmed}`;}+function shouldUseProxyOrigin(baseUrl: string): boolean {+ if (typeof window === "undefined") {+ return false;+ }++ try {+ const configuredUrl = new URL(baseUrl);+ const localHosts = new Set(["127.0.0.1", "localhost", "0.0.0.0"]);+ const browserHostname = window.location.hostname;++ return (+ localHosts.has(configuredUrl.hostname) &&+ !localHosts.has(browserHostname)+ );+ } catch {+ return false;+ }+}++function resolveAgentServerBaseUrl(baseUrl: string | null): string | null {+ if (!baseUrl) {+ return null;+ }++ if (shouldUseProxyOrigin(baseUrl)) {+ return window.location.origin;+ }++ return baseUrl;+}+export function getAgentServerBaseUrl(): string {- const envUrl = normalizeBaseUrl(import.meta.env.VITE_BACKEND_BASE_URL);+ const envUrl = resolveAgentServerBaseUrl(+ normalizeBaseUrl(import.meta.env.VITE_BACKEND_BASE_URL),+ );if (envUrl) return envUrl;- const storedUrl = normalizeBaseUrl(readStoredConfig().baseUrl);+ const storedUrl = resolveAgentServerBaseUrl(+ normalizeBaseUrl(readStoredConfig().baseUrl),+ );if (storedUrl) return storedUrl;if (typeof window !== "undefined") {diff --git a/src/api/config-service/config-service.api.ts b/src/api/config-service/config-service.api.tsindex 61d57be643..42ef44dea6 100644--- a/src/api/config-service/config-service.api.ts+++ b/src/api/config-service/config-service.api.ts@@ -1,42 +1,117 @@import { openHands } from "../open-hands-axios";import type {+ LLMModel,LLMModelPage,+ LLMProvider,ProviderPage,SearchModelsParams,SearchProvidersParams,} from "./config-service.types";-function toSearchParams(- params: SearchModelsParams | SearchProvidersParams,-): string {- const searchParams = new URLSearchParams();- for (const [key, value] of Object.entries(params)) {- if (value !== undefined && value !== null) {- searchParams.append(key, String(value));- }+function filterByQuery<T extends { name: string }>(items: T[], query?: string): T[] {+ if (!query) {+ return items;}- return searchParams.toString();++ const normalizedQuery = query.toLowerCase();+ return items.filter((item) => item.name.toLowerCase().includes(normalizedQuery));+}++function filterByVerified<T extends { verified: boolean }>(+ items: T[],+ verified?: boolean,+): T[] {+ if (verified === undefined) {+ return items;+ }++ return items.filter((item) => item.verified === verified);+}++function limitItems<T>(items: T[], limit?: number): T[] {+ if (!limit || limit <= 0) {+ return items;+ }++ return items.slice(0, limit);}class ConfigService {static async searchModels(params: SearchModelsParams = {},): Promise<LLMModelPage> {- const qs = toSearchParams(params);- const { data } = await openHands.get<LLMModelPage>(- `/api/v1/config/models/search?${qs}`,+ const [modelsResponse, verifiedResponse] = await Promise.all([+ openHands.get<{ models: string[] }>("/api/llm/models"),+ openHands.get<{ models: Record<string, string[]> }>(+ "/api/llm/models/verified",+ ),+ ]);++ const provider = params.provider__eq ?? null;+ const verifiedNames = new Set(+ provider ? (verifiedResponse.data.models?.[provider] ?? []) : [],);- return data;+ const verifiedItems: LLMModel[] = [...verifiedNames].map((name) => ({+ provider,+ name,+ verified: true,+ }));++ const prefixedItems: LLMModel[] = provider+ ? (modelsResponse.data.models ?? [])+ .filter((model) => model.startsWith(`${provider}/`))+ .map((model) => model.slice(provider.length + 1))+ .filter((name) => name.length > 0 && !verifiedNames.has(name))+ .map((name) => ({+ provider,+ name,+ verified: false,+ }))+ : [];++ const items = limitItems(+ filterByVerified(+ filterByQuery([...verifiedItems, ...prefixedItems], params.query),+ params.verified__eq,+ ),+ params.limit,+ );++ return {+ items,+ next_page_id: null,+ };}static async searchProviders(params: SearchProvidersParams = {},): Promise<ProviderPage> {- const qs = toSearchParams(params);- const { data } = await openHands.get<ProviderPage>(- `/api/v1/config/providers/search?${qs}`,+ const [providersResponse, verifiedResponse] = await Promise.all([+ openHands.get<{ providers: string[] }>("/api/llm/providers"),+ openHands.get<{ models: Record<string, string[]> }>(+ "/api/llm/models/verified",+ ),+ ]);++ const verifiedProviders = new Set(+ Object.keys(verifiedResponse.data.models ?? {}),);- return data;+ const providers: LLMProvider[] = (providersResponse.data.providers ?? []).map(+ (name) => ({+ name,+ verified: verifiedProviders.has(name),+ }),+ );++ const items = limitItems(+ filterByVerified(filterByQuery(providers, params.query), params.verified__eq),+ params.limit,+ );++ return {+ items,+ next_page_id: null,+ };}}diff --git a/src/components/features/settings/sdk-settings/sdk-section-page.tsx b/src/components/features/settings/sdk-settings/sdk-section-page.tsxindex 882667c26b..0d9584759d 100644--- a/src/components/features/settings/sdk-settings/sdk-section-page.tsx+++ b/src/components/features/settings/sdk-settings/sdk-section-page.tsx@@ -78,6 +78,25 @@ const normalizeView = (return "basic";};+const getSchemaUnavailableMessage = (+ error: unknown,+ fallbackMessage: string,+): string => {+ if (!(error instanceof AxiosError)) {+ return fallbackMessage;+ }++ if (error.response?.status === 401) {+ return `${fallbackMessage} This agent server requires X-Session-API-Key. Set VITE_SESSION_API_KEY in the frontend to the same value used by the backend SESSION_API_KEY or OH_SESSION_API_KEYS_0.`;+ }++ if (error.response?.status === 404) {+ return `${fallbackMessage} This backend does not expose /api/settings/* schema endpoints. Upgrade to a recent openhands-agent-server release.`;+ }++ return fallbackMessage;+};+export interface SdkSectionHeaderProps {values: SettingsFormValues;isDisabled: boolean;@@ -141,14 +160,12 @@ export function SdkSectionPage({const conversationSchemaQuery = useConversationSettingsSchema(settings?.conversation_settings_schema,);- const schema =+ const activeSchemaQuery =settingsSource === "conversation_settings"- ? conversationSchemaQuery.data- : agentSchemaQuery.data;- const isSchemaLoading =- settingsSource === "conversation_settings"- ? conversationSchemaQuery.isLoading- : agentSchemaQuery.isLoading;+ ? conversationSchemaQuery+ : agentSchemaQuery;+ const schema = activeSchemaQuery.data;+ const isSchemaLoading = activeSchemaQuery.isLoading;const { data: config } = useConfig();const { data: me } = useMe();const { hasPermission } = usePermission(me?.role ?? "member");@@ -184,6 +201,14 @@ export function SdkSectionPage({const showAdvanced =forceShowAdvancedView || hasAdvancedSettings(filteredSchema);const showAll = allowAllView && hasMinorSettings(filteredSchema);+ const schemaUnavailableMessage = React.useMemo(+ () =>+ getSchemaUnavailableMessage(+ activeSchemaQuery.error,+ t(I18nKey.SETTINGS$SDK_SCHEMA_UNAVAILABLE),+ ),+ [activeSchemaQuery.error, t],+ );const initialValues = React.useMemo(() => {if (!settings || !filteredSchema) return null;@@ -305,7 +330,7 @@ export function SdkSectionPage({if (!filteredSchema || filteredSchema.sections.length === 0) {return (<Typography.Paragraph className="text-tertiary-alt">- {t(I18nKey.SETTINGS$SDK_SCHEMA_UNAVAILABLE)}+ {schemaUnavailableMessage}</Typography.Paragraph>);}diff --git a/src/hooks/query/use-agent-settings-schema.ts b/src/hooks/query/use-agent-settings-schema.tsindex fd9136d382..2e79769024 100644--- a/src/hooks/query/use-agent-settings-schema.ts+++ b/src/hooks/query/use-agent-settings-schema.ts@@ -10,7 +10,7 @@ const useSettingsSchema = () => {const isOnIntermediatePage = useIsOnIntermediatePage();const { data: userIsAuthenticated } = useIsAuthed();- const { data, isLoading, isFetching } = useQuery({+ const { data, error, isLoading, isFetching } = useQuery({queryKey: ["settings-schema", type],queryFn:type === "conversation"@@ -29,6 +29,7 @@ const useSettingsSchema = (if (fallbackSchema) {return {data: fallbackSchema,+ error: null,isLoading: false,isFetching: false,};@@ -36,6 +37,7 @@ const useSettingsSchema = (return {data,+ error,isLoading,isFetching,};