Skip to content

🙌 OpenHands: AI-Driven Development

feat: add agent delegation settings page (#483)

Xingyao Wanga4534c15f426
diff --git a/AGENTS.md b/AGENTS.md
index 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.ts
index 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.tsx
index 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.json
index 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.ts
index 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.tsx
index 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.json
index 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.ts
index 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.tsx
index 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 (
<div
data-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() {
<SettingsDropdownInput
testId="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.ts
index 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: [],