🙌 OpenHands: AI-Driven Development
feat: add agent delegation settings page (#483)
Xingyao Wanga4534c15f426
diff --git a/AGENTS.md b/AGENTS.mdindex 13a99d55b9..c65c422736 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -423,6 +423,8 @@ return new ConversationClient(getAgentServerClientOptions()).someMethod(...);- Collapsible thinking: `ThinkAction` events and LLM extended reasoning (`reasoning_content` / `thinking_blocks` on `ActionEvent`) are rendered as collapsible sections via `CollapsibleThinking` (`src/components/conversation-events/chat/event-message-components/collapsible-thinking.tsx`). Collapsed by default to keep the chat compact — the thinking is often in English regardless of the user's conversation language. The `getReasoningContent()` helper in `event-thought-helpers.ts` extracts the content, preferring `reasoning_content` (plain string) and falling back to Anthropic `thinking_blocks`. i18n keys: `THINKING$TITLE`, `THINKING$EXPAND`, `THINKING$COLLAPSE`. Tests: `__tests__/components/conversation-events/chat/event-message-think-action.test.tsx`.+- Agent delegation settings: the `Settings > Agent` page (`src/routes/agent-settings.tsx`) is intentionally NOT a `SdkSectionPage` wrapper. It mirrors upstream OpenHands#14418 — it flatMaps every section of `agent_settings_schema` and finds the `enable_sub_agents` field by key, so it works regardless of which section the real backend exposes the field in. Don't refactor it back to `SdkSectionPage` unless you also know the real backend's section name and add a fallback for the live "SDK schema unavailable" path. The toggle persists via `agent_settings_diff`. Nav item lives in `OSS_NAV_ITEMS` (settings-nav.tsx) with the robot icon (`SETTINGS$NAV_AGENT`). The mock schema in `settings-handlers.ts` puts the field in a `general` section. **Client-side gate**: `getAgentTools()` in `agent-server-adapter.ts` only attaches `task_tool_set` to new conversations when `agent_settings.enable_sub_agents === true`. Without that gate the agent server would still receive the tool whenever it advertised it in `/api/server_info`, so the toggle had no effect on running conversations.+- Settings naming is backend-aware today: local `/settings` is profile-oriented (`use-settings-nav-items.ts` renames the first settings item/title/subtitle to `LLM Profiles` and `chat-input-model.tsx` / `chat-input-actions.tsx` link there as `LLM Profiles`), while cloud keeps the generic `LLM Settings` copy because cloud still edits raw settings rather than saved profiles. The local profile editor (`llm-settings-local-view.tsx`) should keep explicit create/edit profile headings plus helper text so users know they are saving a profile, not mutating the current conversation directly.- ESLint config (flat, ESLint 9): the project uses `eslint.config.js` (not `.eslintrc`) and runs on `[email protected]`, not 10. The constraint pinning us below 10 is `[email protected]`, which still calls `context.getFilename()` at rule-load time — that API was removed in ESLint 10 and `@eslint/compat`'s `fixupPluginRules` does NOT shim it. Don't try to bump eslint past 9 until eslint-plugin-react ships a v10-compatible release. Import rules come from `eslint-plugin-import-x` (the maintained fork of `eslint-plugin-import`) but are registered under both `import-x/` and `import/` prefixes via `plugins: { import: importXPlugin, ... }` so existing `// eslint-disable-next-line import/...` directives keep working. `linterOptions.reportUnusedDisableDirectives` is set to `"warn"` (not "off") so stale airbnb-era disable comments still surface in lint output without failing CI. The TS-overrides block has an `ignores: ["src/hooks/query/query-keys.ts"]` so the `no-restricted-syntax` rule banning raw `["settings", ...]` query keys doesn't fire on the file that defines the helpers themselves. No `.npmrc` / `legacy-peer-deps` flag is needed — all our plugins declare ESLint 9 peer compatibility.diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.tsindex 25a27af462..a0e60c442b 100644--- a/__tests__/api/agent-server-adapter.test.ts+++ b/__tests__/api/agent-server-adapter.test.ts@@ -66,6 +66,7 @@ describe("buildStartConversationRequest", () => {agent_settings: {...DEFAULT_SETTINGS.agent_settings,agent: "CodeActAgent",+ enable_sub_agents: true,llm: {model: "nested-model",api_key: " nested-key ",@@ -182,7 +183,7 @@ describe("buildStartConversationRequest", () => {]);});- it("includes task_tool_set when the server advertises it but not browser tools", () => {+ it("includes task_tool_set when sub-agents are enabled and the server advertises it but not browser tools", () => {mockIsAgentServerToolAvailable.mockImplementation((toolName: string) => toolName === "task_tool_set",);@@ -192,6 +193,7 @@ describe("buildStartConversationRequest", () => {...DEFAULT_SETTINGS,agent_settings: {...DEFAULT_SETTINGS.agent_settings,+ enable_sub_agents: true,llm: { model: "nested-model" },},},@@ -210,6 +212,26 @@ describe("buildStartConversationRequest", () => {]);});+ it("omits task_tool_set when sub-agents are disabled even if the server advertises it", () => {+ const payload = buildStartConversationRequest({+ settings: {+ ...DEFAULT_SETTINGS,+ agent_settings: {+ ...DEFAULT_SETTINGS.agent_settings,+ enable_sub_agents: false,+ llm: { model: "nested-model" },+ },+ },+ }) as {+ agent: {+ tools: Array<{ name: string; params: Record<string, unknown> }>;+ };+ };++ const toolNames = payload.agent.tools.map((t) => t.name);+ expect(toolNames).not.toContain("task_tool_set");+ });+it("derives confirmation and security settings the same way as OpenHands", () => {const payload = buildStartConversationRequest({settings: {diff --git a/__tests__/routes/agent-settings.test.tsx b/__tests__/routes/agent-settings.test.tsxindex 1a83347192..ba9ab5bb10 100644--- a/__tests__/routes/agent-settings.test.tsx+++ b/__tests__/routes/agent-settings.test.tsx@@ -39,7 +39,7 @@ describe("AgentSettingsScreen", () => {vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);});- it("renders the agent type selector defaulting to OpenHands", async () => {+ it("renders the agent type selector defaulting to OpenHands with sub-agents toggle", async () => {vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings({agent_settings: {@@ -52,10 +52,81 @@ describe("AgentSettingsScreen", () => {renderAgentSettingsScreen();await screen.findByTestId("agent-settings-screen");expect(screen.getByTestId("agent-type-selector")).toBeInTheDocument();+ // Sub-agents toggle visible on the OpenHands branch.+ expect(+ screen.getByTestId("agent-settings-enable-sub-agents"),+ ).toBeInTheDocument();// ACP-only fields stay hidden on the OpenHands branch.expect(screen.queryByTestId("agent-command-input")).not.toBeInTheDocument();});+ it("saves enable_sub_agents when toggling on the OpenHands path", async () => {+ const user = userEvent.setup();+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({+ agent_settings: {+ ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,+ agent_kind: "openhands",+ enable_sub_agents: false,+ },+ }),+ );+ const save = vi.spyOn(SettingsService, "saveSettings");++ renderAgentSettingsScreen();+ await screen.findByTestId("agent-settings-screen");++ // Toggle sub-agents on via the enclosing label+ const toggle = screen.getByTestId("agent-settings-enable-sub-agents");+ const label = toggle.closest("label")!;+ await user.click(label);++ await user.click(screen.getByTestId("agent-save-button"));++ await waitFor(() => {+ expect(save).toHaveBeenCalledTimes(1);+ });+ const call = save.mock.calls[0]?.[0] as {+ agent_settings_diff?: Record<string, unknown>;+ };+ expect(call.agent_settings_diff).toEqual({+ agent_kind: "openhands",+ enable_sub_agents: true,+ });+ });++ it("hides sub-agents toggle when ACP is selected", async () => {+ const user = userEvent.setup();+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(+ buildSettings({+ agent_settings: {+ ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,+ agent_kind: "openhands",+ },+ }),+ );++ renderAgentSettingsScreen();+ await screen.findByTestId("agent-settings-screen");++ // Sub-agents toggle should be visible initially+ expect(+ screen.getByTestId("agent-settings-enable-sub-agents"),+ ).toBeInTheDocument();++ // Switch to ACP+ await user.click(screen.getByTestId("agent-type-selector"));+ await user.click(+ await screen.findByRole("option", { name: "SETTINGS$AGENT_TYPE_ACP" }),+ );++ // Sub-agents toggle should be hidden, ACP fields should appear+ expect(+ screen.queryByTestId("agent-settings-enable-sub-agents"),+ ).not.toBeInTheDocument();+ expect(screen.getByTestId("agent-command-input")).toBeInTheDocument();+ });+it("shows the ACP form when the active agent_kind is acp", async () => {vi.spyOn(SettingsService, "getSettings").mockResolvedValue(buildSettings({@@ -165,7 +236,10 @@ describe("AgentSettingsScreen", () => {const call = save.mock.calls[0]?.[0] as {agent_settings_diff?: Record<string, unknown>;};- expect(call.agent_settings_diff).toEqual({ agent_kind: "openhands" });+ expect(call.agent_settings_diff).toEqual({+ agent_kind: "openhands",+ enable_sub_agents: false,+ });});it("disables Save when the user has cleared the command on the ACP path", async () => {diff --git a/package-lock.json b/package-lock.jsonindex 45185a3e4d..6ac159ef68 100644--- a/package-lock.json+++ b/package-lock.json@@ -3454,7 +3454,7 @@},"node_modules/@openhands/typescript-client": {"version": "0.1.1",- "resolved": "git+https://github.com/OpenHands/typescript-client.git#ef62e82fc3dfb03991a1c8025429caf354427263",+ "resolved": "git+ssh://[email protected]/OpenHands/typescript-client.git#ef62e82fc3dfb03991a1c8025429caf354427263","license": "MIT","dependencies": {"@openrouter/sdk": "^0.12.35",diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.tsindex 1f740234fd..c645237f3e 100644--- a/src/api/agent-server-adapter.ts+++ b/src/api/agent-server-adapter.ts@@ -415,7 +415,7 @@ function getConversationSecurityAnalyzer(conversationSettings: SettingsRecord) {}}-function getAgentTools() {+function getAgentTools(agentSettings: SettingsRecord) {const tools = DEFAULT_TOOL_NAMES.map((name) => ({ name, params: {} }));if (browserToolsEnabled() &&@@ -423,12 +423,16 @@ function getAgentTools() {) {tools.push({ name: BROWSER_TOOL_SET_NAME, params: {} });}- // Enables sub-agent delegation. The agent server's tool_router preloads- // `task_tool_set` and registers the built-in subagents (code-explorer,- // bash-runner, web-researcher, general-purpose), so exposing the tool here- // is all the client needs to do. Older servers that don't advertise it in- // /api/server_info's `usable_tools` are skipped via the capability probe.- if (isAgentServerToolAvailable(TASK_TOOL_SET_NAME)) {+ // Sub-agent delegation: only expose `task_tool_set` when the user has+ // opted in via Settings > Agent. The agent server's tool_router preloads+ // the tool and registers the built-in subagents (code-explorer,+ // bash-runner, web-researcher, general-purpose) when it's requested.+ // Older servers that don't advertise the tool in /api/server_info's+ // `usable_tools` are skipped via the capability probe.+ if (+ agentSettings.enable_sub_agents === true &&+ isAgentServerToolAvailable(TASK_TOOL_SET_NAME)+ ) {tools.push({ name: TASK_TOOL_SET_NAME, params: {} });}return tools;@@ -543,7 +547,7 @@ function buildConfiguredAgentSettings(settings: Settings): SettingsRecord {return {...agentSettings,llm,- tools: getAgentTools(),+ tools: getAgentTools(agentSettings),include_default_tools: includeDefaultTools,};}diff --git a/src/constants/settings-nav.tsx b/src/constants/settings-nav.tsxindex fafa18b833..585adc2985 100644--- a/src/constants/settings-nav.tsx+++ b/src/constants/settings-nav.tsx@@ -2,6 +2,7 @@ import { AppWindow, Shield } from "lucide-react";import KeyIcon from "#/icons/key.svg?react";import MemoryIcon from "#/icons/memory_icon.svg?react";import CircuitIcon from "#/icons/u-circuit.svg?react";+import RobotIcon from "#/icons/u-robot.svg?react";export interface SettingsNavItem {icon: React.ReactElement;@@ -20,7 +21,7 @@ export interface SettingsNavItem {export const OSS_NAV_ITEMS: SettingsNavItem[] = [{- icon: <CircuitIcon width={16} height={16} />,+ icon: <RobotIcon width={16} height={16} />,to: "/settings/agent",text: "SETTINGS$NAV_AGENT",subtitle: "SETTINGS$PAGE_AGENT_SUBLINE",diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex 6c1c636f44..4e1a23d1ff 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -1818,7 +1818,7 @@"uk": "Базовий URL","ca": "URL base"},- "SETTINGS$AGENT": {+ "SETTINGS$NAV_AGENT": {"en": "Agent","ja": "エージェント","zh-CN": "代理",@@ -2141,6 +2141,40 @@"uk": "Агент","ca": "Agent"},+ "SCHEMA$ENABLE_SUB_AGENTS$DESCRIPTION": {+ "en": "Enable sub-agent delegation via TaskToolSet.",+ "ja": "TaskToolSet を介したサブエージェントへの委任を有効にします。",+ "zh-CN": "通过 TaskToolSet 启用子智能体委派。",+ "zh-TW": "透過 TaskToolSet 啟用子智能體委派。",+ "ko-KR": "TaskToolSet을 통한 하위 에이전트 위임을 활성화합니다.",+ "no": "Aktiver delegering til underagenter via TaskToolSet.",+ "it": "Abilita la delega ai sottoagenti tramite TaskToolSet.",+ "pt": "Ative a delegação para subagentes via TaskToolSet.",+ "es": "Habilita la delegación a subagentes mediante TaskToolSet.",+ "ar": "مكّن تفويض المهام إلى الوكلاء الفرعيين عبر TaskToolSet.",+ "fr": "Activez la délégation aux sous-agents via TaskToolSet.",+ "tr": "TaskToolSet aracılığıyla alt ajanlara yetki devrini etkinleştirin.",+ "de": "Aktivieren Sie die Delegierung an Sub-Agenten über TaskToolSet.",+ "uk": "Увімкніть делегування субагентам через TaskToolSet.",+ "ca": "Activa la delegació a subagents mitjançant TaskToolSet."+ },+ "SCHEMA$ENABLE_SUB_AGENTS$LABEL": {+ "en": "Enable sub-agents",+ "ja": "サブエージェントを有効にする",+ "zh-CN": "启用子智能体",+ "zh-TW": "啟用子智能體",+ "ko-KR": "하위 에이전트 활성화",+ "no": "Aktiver underagenter",+ "it": "Abilita sottoagenti",+ "pt": "Ativar subagentes",+ "es": "Habilitar subagentes",+ "ar": "تمكين الوكلاء الفرعيين",+ "fr": "Activer les sous-agents",+ "tr": "Alt ajanları etkinleştir",+ "de": "Sub-Agenten aktivieren",+ "uk": "Увімкнути субагентів",+ "ca": "Activa subagents"+ },"SCHEMA$CONDENSER$ENABLED$DESCRIPTION": {"en": "Enable the LLM summarizing condenser.","ja": "LLM要約コンデンサーを有効にします。",@@ -4963,23 +4997,6 @@"uk": "LLM","ca": "LLM"},- "SETTINGS$NAV_AGENT": {- "en": "Agent",- "ja": "Agent",- "zh-CN": "Agent",- "zh-TW": "Agent",- "ko-KR": "Agent",- "no": "Agent",- "it": "Agent",- "pt": "Agent",- "es": "Agent",- "ar": "Agent",- "fr": "Agent",- "tr": "Agent",- "de": "Agent",- "uk": "Agent",- "ca": "Agent"- },"SETTINGS$AGENT_PAGE_DESCRIPTION": {"en": "Choose between the built-in OpenHands agent and an external ACP (Agent Client Protocol) subprocess such as Claude Code, Codex, or Gemini CLI.","ja": "Choose between the built-in OpenHands agent and an external ACP (Agent Client Protocol) subprocess such as Claude Code, Codex, or Gemini CLI.",diff --git a/src/mocks/settings-handlers.ts b/src/mocks/settings-handlers.tsindex 25f901cd8b..15a9e71780 100644--- a/src/mocks/settings-handlers.ts+++ b/src/mocks/settings-handlers.ts@@ -62,6 +62,27 @@ const MOCK_AGENT_SETTINGS_SCHEMA: NonNullable<> = {model_name: "AgentSettings",sections: [+ {+ key: "general",+ label: "General",+ fields: [+ {+ key: "enable_sub_agents",+ label: "Enable sub-agents",+ description:+ "Allow the agent to delegate work to specialized built-in sub-agents.",+ section: "general",+ section_label: "General",+ value_type: "boolean",+ default: false,+ choices: [],+ depends_on: [],+ prominence: "major",+ secret: false,+ required: false,+ },+ ],+ },{key: "llm",label: "LLM",@@ -297,6 +318,7 @@ export const MOCK_DEFAULT_USER_SETTINGS: Settings = {enable_default_condenser: true,condenser_max_size: null,},+ enable_sub_agents: false,},conversation_settings_schema: MOCK_CONVERSATION_SETTINGS_SCHEMA,conversation_settings: {diff --git a/src/routes/agent-settings.tsx b/src/routes/agent-settings.tsxindex 56bc4741d3..2027358930 100644--- a/src/routes/agent-settings.tsx+++ b/src/routes/agent-settings.tsx@@ -3,16 +3,23 @@ import { useTranslation } from "react-i18next";import { AxiosError } from "axios";import { useSettings } from "#/hooks/query/use-settings";import { useSaveSettings } from "#/hooks/mutation/use-save-settings";+import { useAgentSettingsSchema } from "#/hooks/query/use-agent-settings-schema";import { SettingsDropdownInput } from "#/components/features/settings/settings-dropdown-input";import { SettingsInput } from "#/components/features/settings/settings-input";+import { SettingsSwitch } from "#/components/features/settings/settings-switch";import { BrandButton } from "#/components/features/settings/brand-button";import { Typography } from "#/ui/typography";import { I18nKey } from "#/i18n/declaration";+import { SettingsFieldSchema } from "#/types/settings";import {displayErrorToast,displaySuccessToast,} from "#/utils/custom-toast-handlers";import { retrieveAxiosErrorMessage } from "#/utils/retrieve-axios-error-message";+import {+ resolveSchemaFieldDescription,+ resolveSchemaFieldLabel,+} from "#/utils/sdk-settings-field-metadata";import {ACP_PROVIDERS,ACP_CUSTOM_PRESET_KEY,@@ -25,11 +32,9 @@ export const handle = { hideTitle: true };type AgentType = "openhands" | "acp";+const ENABLE_SUB_AGENTS_FIELD_KEY = "enable_sub_agents";const COMMAND_PLACEHOLDER_FALLBACK = "npx -y <package-name>";-/** Coerce a possibly-undefined unknown to ``string[]`` by keeping only string- * entries; non-arrays and non-string entries are discarded. Used when- * loading already-stored ``acp_command`` / ``acp_args`` lists from settings. */function toStringArray(value: unknown): string[] {return Array.isArray(value)? value.filter((v): v is string => typeof v === "string")@@ -40,14 +45,6 @@ function detectPreset(commandText: string,providers: ACPProviderConfig[],): string {- // The preset dropdown silently follows the textarea: editing the- // command into something that exactly matches another preset's- // ``default_command`` re-selects that preset (and editing it away- // from every preset flips to "Custom"). This is intentional — the- // textarea is the source of truth; the dropdown is a read-out of- // "which preset, if any, does this command match." A user pasting a- // built-in command they had stashed elsewhere shouldn't have to- // also click the matching preset.const normalized = parseCommand(commandText).join(" ");for (const provider of providers) {if (normalized === provider.default_command.join(" ")) {@@ -57,29 +54,53 @@ function detectPreset(return ACP_CUSTOM_PRESET_KEY;}+function findEnableSubAgentsField(+ fields: SettingsFieldSchema[] | undefined,+): SettingsFieldSchema | undefined {+ return fields?.find((field) => field.key === ENABLE_SUB_AGENTS_FIELD_KEY);+}++function getEnableSubAgentsValue(+ settingsValue: unknown,+ field: SettingsFieldSchema | undefined,+) {+ if (typeof settingsValue === "boolean") return settingsValue;+ return field?.default === true;+}+function AgentSettingsScreen() {const { t } = useTranslation("openhands");const { data: settings, isLoading } = useSettings();const { mutate: saveSettings, isPending: isSaving } = useSaveSettings();+ const { data: schema } = useAgentSettingsSchema(+ settings?.agent_settings_schema,+ );++ // --- Sub-agents (OpenHands path) ---+ const fields = React.useMemo(+ () => schema?.sections.flatMap((section) => section.fields),+ [schema],+ );+ const subAgentsField = findEnableSubAgentsField(fields);+ const initialSubAgentsEnabled = React.useMemo(+ () =>+ getEnableSubAgentsValue(+ settings?.agent_settings?.[ENABLE_SUB_AGENTS_FIELD_KEY],+ subAgentsField,+ ),+ [subAgentsField, settings?.agent_settings],+ );+ const [subAgentsEnabled, setSubAgentsEnabled] = useState(+ initialSubAgentsEnabled,+ );+ // --- ACP path ---const [agentType, setAgentType] = useState<AgentType>("openhands");const [commandText, setCommandText] = useState("");const [acpModel, setAcpModel] = useState("");const [isDirty, setIsDirty] = useState(false);- // Track the settings reference we last initialised the form from. The form- // re-initialises when the server returns a new settings object (after save,- // or after an update from another tab) but not just because a re-render- // produced a new identity — otherwise an in-flight refetch could wipe- // in-progress edits.const lastInitializedSettingsRef = useRef<unknown>(null);-- // Capture the raw ``acp_server`` and the rendered textarea contents at- // load time so handleSave can detect "user opened settings and clicked- // Save without touching anything" — that case has to preserve an- // otherwise-unknown ``acp_server`` value (e.g. a provider the canvas- // registry doesn't carry yet, set out-of-band via the API), instead of- // demoting it to ``"custom"`` and silently losing the original key.const loadedAcpServerRef = useRef<string | null>(null);const loadedCommandTextRef = useRef<string>("");@@ -93,23 +114,6 @@ function AgentSettingsScreen() {if (kind === "acp") {setAgentType("acp");- // Reconstruct the textarea contents from the persisted settings:- //- // spawn = acp_command + acp_args- //- // BUT acp_command may be the "default-preset shortcut" ``[]``, with- // the real command living in the registry under ``acp_server``.- // Without expanding the default before merging, a user with- // ``acp_command: []`` + ``acp_args: ["--extra-arg"]`` would see- // just ``--extra-arg`` in the textarea (no prefix), and saving- // would persist ``acp_command: ["--extra-arg"]`` + flip the- // preset to ``custom`` — silently losing the registry-default- // prefix. Expand first, then merge.- //- // The merge is also what makes ``acp_args: []`` safe on save (see- // ``handleSave`` below): any API-set ``acp_args`` lands in the- // textarea here, so writing the textarea back as ``acp_command``- // round-trips the full command without losing the args.const rawAcpServer = settings.agent_settings?.acp_server;const acpServer =typeof rawAcpServer === "string" ? rawAcpServer : undefined;@@ -141,15 +145,16 @@ function AgentSettingsScreen() {setIsDirty(false);}, [settings]);+ // Sync the sub-agents toggle when settings reload+ useEffect(() => {+ setSubAgentsEnabled(initialSubAgentsEnabled);+ }, [initialSubAgentsEnabled]);+if (isLoading) return null;const isAcp = agentType === "acp";const commandTokens = parseCommand(commandText);const isAcpInvalid = isAcp && commandTokens.length === 0;- // ``selectedPreset`` is derived from ``commandText`` rather than tracked as- // state. Keeping it in state would mean three sync points (effect, textarea- // onChange, dropdown onSelectionChange) that can drift — deriving inline- // keeps the dropdown honest about what would actually be saved.const selectedPreset = detectPreset(commandText, ACP_PROVIDERS);const selectedProvider = ACP_PROVIDERS.find(({ key }) => key === selectedPreset,@@ -161,66 +166,83 @@ function AgentSettingsScreen() {formatCommand(ACP_PROVIDERS[0]?.default_command ?? []) ||COMMAND_PLACEHOLDER_FALLBACK;+ // Dirty tracking: for OpenHands path, also check sub-agents toggle+ const isOpenHandsDirty =+ !isAcp && subAgentsEnabled !== initialSubAgentsEnabled;+ const effectiveIsDirty = isDirty || isOpenHandsDirty;+const handleSave = () => {- // The textarea is the single source of truth for the launch tokens:- // when a built-in preset is selected and untouched, we save the- // empty ``acp_command`` shortcut + provider key (the adapter- // expands it from the registry at conversation-create time, see- // ``buildConfiguredAcpAgentSettings``). When a preset has been- // edited or the user picked Custom, we save the literal tokens.- // Either way, ``acp_args: []`` is reset so API-set args can't- // duplicate at spawn time — safe because the load path already- // merged any ``acp_args`` into the textarea, so the tokens we save- // here include them.- const useDefault = !!(selectedProvider && isDefaultProviderCommand);- // Preserve an unknown loaded ``acp_server`` (e.g. a provider the- // canvas registry doesn't carry yet, set out-of-band via the API)- // when the user opens settings and saves without touching the- // command. Without this branch, ``detectPreset`` would route the- // unknown key into ``ACP_CUSTOM_PRESET_KEY`` and the original- // server name would be silently demoted on save.- const loadedServer = loadedAcpServerRef.current;- const commandUnchanged = commandText === loadedCommandTextRef.current;- const loadedServerIsUnknown =- !!loadedServer &&- loadedServer !== ACP_CUSTOM_PRESET_KEY &&- !ACP_PROVIDERS.some((p) => p.key === loadedServer);- const preserveUnknownServer =- isAcp && commandUnchanged && loadedServerIsUnknown;- const providerKey = !isAcp- ? "openhands"- : preserveUnknownServer+ if (isAcp) {+ const useDefault = !!(selectedProvider && isDefaultProviderCommand);+ const loadedServer = loadedAcpServerRef.current;+ const commandUnchanged = commandText === loadedCommandTextRef.current;+ const loadedServerIsUnknown =+ !!loadedServer &&+ loadedServer !== ACP_CUSTOM_PRESET_KEY &&+ !ACP_PROVIDERS.some((p) => p.key === loadedServer);+ const preserveUnknownServer =+ isAcp && commandUnchanged && loadedServerIsUnknown;+ const providerKey = preserveUnknownServer? (loadedServer as string): selectedProvider && isDefaultProviderCommand? selectedProvider.key: ACP_CUSTOM_PRESET_KEY;- const agentSettingsDiff = buildAcpAgentSettingsDiff(providerKey, {- command: useDefault ? [] : commandTokens,- model: acpModel.trim() || null,- allowUnknownServer: preserveUnknownServer,- });-- if (!agentSettingsDiff) {- // Unreachable through the UI (the providerKey is derived from- // either a known preset or the custom sentinel), but defensive.- return;- }+ const agentSettingsDiff = buildAcpAgentSettingsDiff(providerKey, {+ command: useDefault ? [] : commandTokens,+ model: acpModel.trim() || null,+ allowUnknownServer: preserveUnknownServer,+ });++ if (!agentSettingsDiff) return;- saveSettings(- { agent_settings_diff: agentSettingsDiff },- {- onError: (error) => {- const message = retrieveAxiosErrorMessage(error as AxiosError);- displayErrorToast(message || t(I18nKey.ERROR$GENERIC));+ saveSettings(+ { agent_settings_diff: agentSettingsDiff },+ {+ onError: (error) => {+ const message = retrieveAxiosErrorMessage(error as AxiosError);+ displayErrorToast(message || t(I18nKey.ERROR$GENERIC));+ },+ onSuccess: () => {+ displaySuccessToast(t(I18nKey.SETTINGS$SAVED));+ setIsDirty(false);+ },+ },+ );+ } else {+ // OpenHands path: save agent_kind + sub-agents toggle+ saveSettings(+ {+ agent_settings_diff: {+ agent_kind: "openhands",+ enable_sub_agents: subAgentsEnabled,+ },},- onSuccess: () => {- displaySuccessToast(t(I18nKey.SETTINGS$SAVED));- setIsDirty(false);+ {+ onError: (error) => {+ const message = retrieveAxiosErrorMessage(error as AxiosError);+ displayErrorToast(message || t(I18nKey.ERROR$GENERIC));+ },+ onSuccess: () => {+ displaySuccessToast(t(I18nKey.SETTINGS$SAVED));+ setIsDirty(false);+ },},- },- );+ );+ }};+ // Sub-agents field metadata for OpenHands section+ const subAgentsLabel = subAgentsField+ ? resolveSchemaFieldLabel(t, subAgentsField.key, subAgentsField.label)+ : t(I18nKey.SCHEMA$ENABLE_SUB_AGENTS$LABEL);+ const subAgentsDescription = subAgentsField+ ? resolveSchemaFieldDescription(+ t,+ subAgentsField.key,+ subAgentsField.description,+ )+ : t(I18nKey.SCHEMA$ENABLE_SUB_AGENTS$DESCRIPTION);+return (<divdata-testid="agent-settings-screen"@@ -228,7 +250,7 @@ function AgentSettingsScreen() {><div><Typography.H2 className="mb-2">- {t(I18nKey.SETTINGS$AGENT)}+ {t(I18nKey.SETTINGS$NAV_AGENT)}</Typography.H2><Typography.Paragraph className="text-sm text-[#A3A3A3]">{t(I18nKey.SETTINGS$AGENT_PAGE_DESCRIPTION)}@@ -238,7 +260,7 @@ function AgentSettingsScreen() {<SettingsDropdownInputtestId="agent-type-selector"name="agent-type"- label={t(I18nKey.SETTINGS$AGENT)}+ label={t(I18nKey.SETTINGS$NAV_AGENT)}items={[{key: "openhands",@@ -252,8 +274,6 @@ function AgentSettingsScreen() {const newType = key as AgentType;setAgentType(newType);if (newType === "acp" && !commandText) {- // First-time switch into ACP: prefill the textarea with the- // first registered provider.const preferred = ACP_PROVIDERS[0];if (preferred) {setCommandText(formatCommand(preferred.default_command));@@ -263,6 +283,25 @@ function AgentSettingsScreen() {}}/>+ {!isAcp && (+ <div className="flex flex-col gap-1.5">+ <SettingsSwitch+ testId="agent-settings-enable-sub-agents"+ isToggled={subAgentsEnabled}+ onToggle={(val) => {+ setSubAgentsEnabled(val);+ }}+ >+ {subAgentsLabel}+ </SettingsSwitch>+ {subAgentsDescription ? (+ <Typography.Paragraph className="text-tertiary-alt text-xs leading-5">+ {subAgentsDescription}+ </Typography.Paragraph>+ ) : null}+ </div>+ )}+{isAcp && (<><SettingsDropdownInput@@ -335,7 +374,7 @@ function AgentSettingsScreen() {testId="agent-save-button"type="button"variant="primary"- isDisabled={isSaving || !isDirty || isAcpInvalid}+ isDisabled={isSaving || !effectiveIsDirty || isAcpInvalid}onClick={handleSave}>{isSaving ? t(I18nKey.SETTINGS$SAVING) : t(I18nKey.BUTTON$SAVE)}diff --git a/src/services/settings.ts b/src/services/settings.tsindex 1827372227..9fe3297d77 100644--- a/src/services/settings.ts+++ b/src/services/settings.ts@@ -46,6 +46,7 @@ export const DEFAULT_SETTINGS: Settings = {enabled: true,max_size: 240,},+ enable_sub_agents: false,mcp_config: {sse_servers: [],stdio_servers: [],