Skip to content

The agent that grows with you

feat(desktop): add guided subagent model and provider picker (#67347)

abundantbeing19d32c83d720
diff --git a/apps/desktop/src/app/settings/config-field.tsx b/apps/desktop/src/app/settings/config-field.tsx
index ec633f6ddea..bd0fd20a669 100644
--- a/apps/desktop/src/app/settings/config-field.tsx
+++ b/apps/desktop/src/app/settings/config-field.tsx
@@ -10,6 +10,7 @@ import type { ConfigFieldSchema } from '@/types/hermes'
import { ComboboxInput } from './combobox-input'
import { CONTROL_TEXT, EMPTY_SELECT_VALUE, FIELD_DESCRIPTIONS, FIELD_LABELS, FREE_INPUT_KEYS } from './constants'
+import { DelegationModelProviderField } from './delegation-model-provider-field'
import { FallbackModelsField } from './fallback-models-field'
import { fieldCopyForSchemaKey } from './field-copy'
import { ListRow, ToggleRow } from './primitives'
@@ -37,7 +38,9 @@ export function ConfigField({
enumOptions,
optionLabels,
onChange,
- descriptionExtra
+ descriptionExtra,
+ delegationProvider,
+ onDelegationChange
}: {
schemaKey: string
schema: ConfigFieldSchema
@@ -46,6 +49,8 @@ export function ConfigField({
optionLabels?: Record<string, string>
onChange: (value: unknown) => void
descriptionExtra?: ReactNode
+ delegationProvider?: string
+ onDelegationChange?: (model: string, provider: string) => void
}) {
const { t } = useI18n()
const c = t.settings.config
@@ -112,6 +117,20 @@ export function ConfigField({
return wideRow(<FallbackModelsField onChange={onChange} value={value} />)
}
+ // `delegation.model` renders the paired provider + model picker.
+ // The sibling `delegation.provider` is handled atomically by this control.
+ if (schemaKey === 'delegation.model') {
+ return wideRow(
+ <DelegationModelProviderField
+ model={String(value ?? '')}
+ onChange={({ model: nextModel, provider: nextProvider }) => {
+ onDelegationChange?.(nextModel, nextProvider)
+ }}
+ provider={delegationProvider ?? ''}
+ />
+ )
+ }
+
if (schema.type === 'boolean') {
return (
<ToggleRow
diff --git a/apps/desktop/src/app/settings/config-settings.tsx b/apps/desktop/src/app/settings/config-settings.tsx
index a112b3eea36..328fe52a52b 100644
--- a/apps/desktop/src/app/settings/config-settings.tsx
+++ b/apps/desktop/src/app/settings/config-settings.tsx
@@ -442,6 +442,11 @@ function ConfigSettingsInner({
const visibleFields = activeSectionId === 'voice' ? fields.filter(([key]) => voiceFieldVisible(key, config)) : fields
+ const filteredVisibleFields =
+ activeSectionId === 'advanced' && (subpage === undefined || subpage === 'delegation')
+ ? visibleFields.filter(([key]) => key !== 'delegation.provider')
+ : visibleFields
+
const showEmptyState =
visibleFields.length === 0 &&
(subpage === undefined
@@ -499,11 +504,12 @@ function ConfigSettingsInner({
) : null}
{showEmptyState ? (
<EmptyState description={c.emptyDesc} title={c.emptyTitle} />
- ) : visibleFields.length === 0 ? null : (
+ ) : filteredVisibleFields.length === 0 ? null : (
<div className="grid gap-1">
- {visibleFields.map(([key, field]) => (
+ {filteredVisibleFields.map(([key, field]) => (
<div className="scroll-mt-6 rounded-lg" id={`setting-field-${key}`} key={key}>
<ConfigField
+ delegationProvider={key === 'delegation.model' ? String(getNested(config, 'delegation.provider') ?? '') : undefined}
descriptionExtra={
key === 'memory.provider' && isExternalMemoryProvider(getNested(config, key)) ? (
<MemoryConnect profile={scopeProfile} provider={String(getNested(config, key))} />
@@ -515,6 +521,15 @@ function ConfigSettingsInner({
: enumOptionsFor(key, getNested(config, key), config)
}
onChange={value => updateConfig(setNested(config, key, value))}
+ onDelegationChange={(nextModel, nextProvider) => {
+ updateConfig(
+ setNested(
+ setNested(config, 'delegation.model', nextModel),
+ 'delegation.provider',
+ nextProvider
+ )
+ )
+ }}
optionLabels={key === 'tts.elevenlabs.voice_id' ? elevenLabsVoiceLabels : undefined}
schema={field}
schemaKey={key}
diff --git a/apps/desktop/src/app/settings/delegation-model-provider-field.test.tsx b/apps/desktop/src/app/settings/delegation-model-provider-field.test.tsx
new file mode 100644
index 00000000000..fc780404ef0
--- /dev/null
+++ b/apps/desktop/src/app/settings/delegation-model-provider-field.test.tsx
@@ -0,0 +1,157 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Radix Select calls scrollIntoView / pointer-capture APIs jsdom lacks.
+beforeAll(() => {
+ Element.prototype.scrollIntoView = vi.fn()
+ Element.prototype.hasPointerCapture = vi.fn(() => false)
+ Element.prototype.releasePointerCapture = vi.fn()
+})
+
+const getGlobalModelOptions = vi.fn()
+
+vi.mock('@/hermes', () => ({
+ getGlobalModelOptions: () => getGlobalModelOptions()
+}))
+
+const { DelegationModelProviderField, INHERIT_VALUE, MODEL_ONLY_VALUE } = await import(
+ './delegation-model-provider-field'
+)
+
+beforeEach(() => {
+ getGlobalModelOptions.mockResolvedValue({
+ providers: [
+ { name: 'Anthropic', slug: 'anthropic', models: ['claude-sonnet-4-6', 'claude-opus-4-6'] },
+ { name: 'OpenAI', slug: 'openai', models: ['gpt-5.1'] },
+ { name: 'Custom Endpoint', slug: 'custom', models: [] }
+ ]
+ })
+})
+
+afterEach(() => {
+ cleanup()
+ vi.clearAllMocks()
+})
+
+function renderField(model: string, provider: string, onChange = vi.fn()) {
+ const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+ render(
+ <QueryClientProvider client={client}>
+ <DelegationModelProviderField model={model} onChange={onChange} provider={provider} />
+ </QueryClientProvider>
+ )
+
+ return onChange
+}
+
+function renderFieldWithRerender(model: string, provider: string, onChange = vi.fn()) {
+ const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+ const view = render(
+ <QueryClientProvider client={client}>
+ <DelegationModelProviderField model={model} onChange={onChange} provider={provider} />
+ </QueryClientProvider>
+ )
+
+ return (nextModel: string, nextProvider: string) =>
+ view.rerender(
+ <QueryClientProvider client={client}>
+ <DelegationModelProviderField model={nextModel} onChange={onChange} provider={nextProvider} />
+ </QueryClientProvider>
+ )
+}
+
+describe('DelegationModelProviderField', () => {
+ it('renders "Inherit from main agent" by default when both fields are empty', async () => {
+ renderField('', '')
+
+ await waitFor(() => expect(getGlobalModelOptions).toHaveBeenCalled())
+
+ expect(screen.getByText('Inherit from main agent')).toBeTruthy()
+ // No model select trigger should be present in inherit mode
+ expect(screen.queryByLabelText('Subagent Model')).toBeNull()
+ })
+
+ it('renders provider and model selects when configured', async () => {
+ renderField('claude-sonnet-4-6', 'anthropic')
+
+ await waitFor(() => expect(getGlobalModelOptions).toHaveBeenCalled())
+
+ expect(screen.getByLabelText('Subagent Provider')).toBeTruthy()
+ expect(screen.getByLabelText('Subagent Model')).toBeTruthy()
+ expect(screen.getByText('claude-sonnet-4-6')).toBeTruthy()
+ })
+
+ it('represents model-only override without provider as Custom model', async () => {
+ renderField('my-custom-model', '')
+
+ await waitFor(() => expect(getGlobalModelOptions).toHaveBeenCalled())
+
+ expect(screen.getByText('Custom model (use parent credentials)')).toBeTruthy()
+ expect(screen.getByLabelText('Subagent Model')).toBeTruthy()
+ expect(screen.getByText('my-custom-model')).toBeTruthy()
+ })
+
+ it('resyncs when external config changes (e.g. profile switch)', async () => {
+ const rerender = renderFieldWithRerender('', '')
+
+ await waitFor(() => expect(screen.getByText('Inherit from main agent')).toBeTruthy())
+
+ rerender('gpt-5.1', 'openai')
+
+ await waitFor(() => {
+ expect(screen.getByText('OpenAI')).toBeTruthy()
+ expect(screen.getByText('gpt-5.1')).toBeTruthy()
+ })
+ })
+
+ it('clearing to Inherit emits { model: "", provider: "" } atomically', async () => {
+ const onChange = renderField('gpt-5.1', 'openai')
+
+ await waitFor(() => expect(screen.getByText('OpenAI')).toBeTruthy())
+
+ // Radix Select Trigger
+ const trigger = screen.getByLabelText('Subagent Provider')
+ fireEvent.click(trigger)
+
+ // Pick inherit
+ const inheritOption = await screen.findByRole('option', { name: 'Inherit from main agent' })
+ fireEvent.click(inheritOption)
+
+ expect(onChange).toHaveBeenCalledWith({ model: '', provider: '' })
+ })
+
+ it('switching provider resets model and emits atomically', async () => {
+ const onChange = renderField('gpt-5.1', 'openai')
+
+ await waitFor(() => expect(screen.getByText('OpenAI')).toBeTruthy())
+
+ const trigger = screen.getByLabelText('Subagent Provider')
+ fireEvent.click(trigger)
+
+ const anthropicOption = await screen.findByRole('option', { name: 'Anthropic' })
+ fireEvent.click(anthropicOption)
+
+ // Should switch provider to anthropic and clear model because gpt-5.1 is not an anthropic model
+ expect(onChange).toHaveBeenCalledWith({ model: '', provider: 'anthropic' })
+ })
+
+ it('switching to Custom model preserves draft model with empty provider', async () => {
+ const onChange = renderField('special-model', 'openai')
+
+ await waitFor(() => expect(screen.getByText('OpenAI')).toBeTruthy())
+
+ const trigger = screen.getByLabelText('Subagent Provider')
+ fireEvent.click(trigger)
+
+ const customModelOption = await screen.findByRole('option', {
+ name: 'Custom model (use parent credentials)'
+ })
+
+ fireEvent.click(customModelOption)
+
+ expect(onChange).toHaveBeenCalledWith({ model: 'special-model', provider: '' })
+ })
+})
diff --git a/apps/desktop/src/app/settings/delegation-model-provider-field.tsx b/apps/desktop/src/app/settings/delegation-model-provider-field.tsx
new file mode 100644
index 00000000000..a1ee7167909
--- /dev/null
+++ b/apps/desktop/src/app/settings/delegation-model-provider-field.tsx
@@ -0,0 +1,192 @@
+import type { ModelOptionProvider } from '@hermes/shared'
+import { useStore } from '@nanostores/react'
+import { useQuery } from '@tanstack/react-query'
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { getGlobalModelOptions } from '@/hermes'
+import { useI18n } from '@/i18n'
+import { findCatalogProvider } from '@/lib/model-options'
+import { cn } from '@/lib/utils'
+import { $customModels, withCustomModels } from '@/store/custom-models'
+
+import { CONTROL_TEXT, EMPTY_SELECT_VALUE } from './constants'
+import { ModelSelect } from './model-select'
+
+export interface DelegationModelProviderValue {
+ model: string
+ provider: string
+}
+
+export const INHERIT_VALUE = '__inherit__'
+export const MODEL_ONLY_VALUE = '__model_only__'
+
+interface DelegationModelProviderFieldProps {
+ model: string
+ provider: string
+ onChange: (next: DelegationModelProviderValue) => void
+}
+
+/**
+ * Guided picker for delegation.model + delegation.provider in Settings → Advanced.
+ *
+ * Replaces the two bare text fields with a paired provider and model picker
+ * sourced from `getGlobalModelOptions()` and `$customModels`, matching the
+ * Main Model and Fallback Models dropdown patterns.
+ *
+ * Special states:
+ * - "Inherit from main agent": writes provider="" and model=""
+ * - "Custom model (use parent credentials)": writes provider="" and model="<typed-model>"
+ * which is supported by the runtime resolver tools/delegate_tool.py.
+ * - Standard provider selection: writes provider="<slug>" and model="<model>"
+ */
+export function DelegationModelProviderField({
+ model,
+ provider,
+ onChange
+}: DelegationModelProviderFieldProps) {
+ const { t } = useI18n()
+ const m = t.settings.model
+ const c = t.settings.config
+
+ const modelOptions = useQuery({
+ queryKey: ['model-options', 'global'],
+ queryFn: () => getGlobalModelOptions()
+ })
+
+ const customModels = useStore($customModels)
+
+ const providers = useMemo(
+ () => withCustomModels((modelOptions.data?.providers ?? []).filter(p => p.slug), customModels),
+ [modelOptions.data?.providers, customModels]
+ )
+
+ // Determine current dropdown value
+ const derivePickerValue = (p: string, mdl: string): string => {
+ if (!p && !mdl) {
+ return INHERIT_VALUE
+ }
+
+ if (!p && mdl) {
+ return MODEL_ONLY_VALUE
+ }
+
+ return p
+ }
+
+ const [pickerValue, setPickerValue] = useState<string>(() => derivePickerValue(provider, model))
+ const [draftModel, setDraftModel] = useState<string>(model)
+
+ const lastCommittedRef = useRef<string>(JSON.stringify({ model, provider }))
+
+ // Resync if external config changes (e.g. profile switch)
+ // eslint-disable-next-line no-restricted-syntax -- legitimate non-atom ref write (see FallbackModelsField)
+ useEffect(() => {
+ const pair = JSON.stringify({ model, provider })
+
+ if (pair !== lastCommittedRef.current) {
+ lastCommittedRef.current = pair
+ setPickerValue(derivePickerValue(provider, model))
+ setDraftModel(model)
+ }
+ }, [model, provider])
+
+ const commit = (nextModel: string, nextProvider: string) => {
+ const serialized = JSON.stringify({ model: nextModel, provider: nextProvider })
+
+ if (serialized === lastCommittedRef.current) {
+ return
+ }
+
+ lastCommittedRef.current = serialized
+ onChange({ model: nextModel, provider: nextProvider })
+ }
+
+ const handleProviderChange = (selected: string) => {
+ setPickerValue(selected)
+
+ if (selected === INHERIT_VALUE) {
+ setDraftModel('')
+ commit('', '')
+ } else if (selected === MODEL_ONLY_VALUE) {
+ // Model-only override: provider is empty, model is preserved or empty draft
+ commit(draftModel, '')
+ } else {
+ // Provider changed to a concrete catalog provider.
+ // If the current model belongs to this new provider, keep it; otherwise reset model.
+ const provRow = findCatalogProvider(providers, selected)
+ const provModels = provRow?.models ?? []
+ const nextMdl = provModels.includes(draftModel) ? draftModel : ''
+ setDraftModel(nextMdl)
+ commit(nextMdl, selected)
+ }
+ }
+
+ const handleModelChange = (nextModel: string) => {
+ setDraftModel(nextModel)
+
+ if (pickerValue === INHERIT_VALUE) {
+ commit('', '')
+ } else if (pickerValue === MODEL_ONLY_VALUE) {
+ commit(nextModel, '')
+ } else {
+ commit(nextModel, pickerValue)
+ }
+ }
+
+ const selectedProviderRow: ModelOptionProvider | undefined = useMemo(
+ () => (pickerValue !== INHERIT_VALUE && pickerValue !== MODEL_ONLY_VALUE ? findCatalogProvider(providers, pickerValue) : undefined),
+ [providers, pickerValue]
+ )
+
+ const providerModels = selectedProviderRow?.models ?? []
+
+ // If a persisted provider isn't in catalog, keep it visible in options
+ const displayProviders = useMemo(() => {
+ if (
+ pickerValue &&
+ pickerValue !== INHERIT_VALUE &&
+ pickerValue !== MODEL_ONLY_VALUE &&
+ !findCatalogProvider(providers, pickerValue)
+ ) {
+ return [{ name: pickerValue, slug: pickerValue, models: [] }, ...providers]
+ }
+
+ return providers
+ }, [providers, pickerValue])
+
+ return (
+ <div className="flex flex-wrap items-center gap-2">
+ <Select onValueChange={handleProviderChange} value={pickerValue || EMPTY_SELECT_VALUE}>
+ <SelectTrigger aria-label={c.delegationProviderSelectLabel ?? 'Subagent Provider'} className={cn('min-w-48 flex-1', CONTROL_TEXT)}>
+ <SelectValue placeholder={m.provider} />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value={INHERIT_VALUE}>
+ {c.delegationInherit ?? 'Inherit from main agent'}
+ </SelectItem>
+ <SelectItem value={MODEL_ONLY_VALUE}>
+ {c.delegationModelOnly ?? 'Custom model (use parent credentials)'}
+ </SelectItem>
+ {displayProviders.map(p => (
+ <SelectItem key={p.slug} value={p.slug}>
+ {p.name}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+
+ {pickerValue !== INHERIT_VALUE && (
+ <ModelSelect
+ aria-label={c.delegationModelSelectLabel ?? 'Subagent Model'}
+ className="min-w-56 flex-1"
+ models={providerModels}
+ onValueChange={handleModelChange}
+ provider={selectedProviderRow}
+ providerSlug={pickerValue === MODEL_ONLY_VALUE ? '' : pickerValue}
+ value={draftModel}
+ />
+ )}
+ </div>
+ )
+}
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 82cee6c4d20..56bcb13ac6b 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -1231,7 +1231,11 @@ export const en: Translations = {
voiceShortcutHintTitle: 'Voice recording shortcut',
voiceShortcutHintDesc:
'Set the voice recording shortcut in Settings → Keyboard Shortcuts ("Start / stop voice conversation"). The voice.record_key config value only applies to the CLI and TUI.',
- showOptions: 'Show options'
+ showOptions: 'Show options',
+ delegationInherit: 'Inherit from main agent',
+ delegationModelOnly: 'Custom model (use parent credentials)',
+ delegationProviderSelectLabel: 'Subagent Provider',
+ delegationModelSelectLabel: 'Subagent Model'
},
hudModifier: {
title: 'Tap to summon HUD',
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 6461e87ba98..51618d11cc7 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -1013,6 +1013,10 @@ export interface Translations extends NoticeTranslations {
voiceShortcutHintTitle: string
voiceShortcutHintDesc: string
showOptions: string
+ delegationInherit: string
+ delegationModelOnly: string
+ delegationProviderSelectLabel: string
+ delegationModelSelectLabel: string
}
hudModifier: {
title: string
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index 82aafabd2ff..443d5cb296c 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -1284,8 +1284,12 @@ export const zhOverrides = {
attachmentSizeLabel: '预览 / 图片加载大小上限(MB)',
voiceShortcutHintTitle: '语音录制快捷键',
voiceShortcutHintDesc:
- '请在“设置 → 键盘快捷键”中设置语音录制快捷键(“开始 / 停止语音对话”)。voice.record_key 配置项仅适用于 CLI 和 TUI。',
- showOptions: '显示选项'
+ '在「设置 → 快捷键」(“开始 / 停止语音对话”)中设置语音录制快捷键。voice.record_key 配置仅适用于 CLI 和 TUI。',
+ showOptions: '显示选项',
+ delegationInherit: '继承主智能体配置',
+ delegationModelOnly: '自定义模型(沿用主智能体凭证)',
+ delegationProviderSelectLabel: '子智能体提供商',
+ delegationModelSelectLabel: '子智能体模型'
},
hudModifier: {
title: '轻按唤出 HUD',