@@ -61,6 +61,50 @@ const BAKED_STRUCTURED_KEYS = new Set([
6161 BUZZ_AGENT_THINKING_EFFORT ,
6262] ) ;
6363
64+ // Canonical behaviors (PR 2 flag cleanup). These were per-surface props;
65+ // onboarding's values won every call and are now the only behavior:
66+ // - auto-select a valid model when the provider changes
67+ // - keep the model select usable during discovery
68+ // - preserve credential env vars across provider switches (the abandoned
69+ // provider's key stays in env_vars — visible/deletable under Advanced —
70+ // so flipping back never loses a typed key; spawned agents may therefore
71+ // see credentials for providers they don't use)
72+ // - require a provider before model/effort are editable (no saveable
73+ // invalid state — design principle #4). Note: legacy configs saved with
74+ // a model but no provider are cleared by the pre-existing orphan-model
75+ // effect on next edit — deliberate data healing, documented in PR.
76+ const autoSelectModelOnProviderChange = true ;
77+ const disableModelSelectDuringDiscovery = false ;
78+ const preserveCredentialEnvVarsOnProviderChange = true ;
79+ const requireProviderForModelAndEffort = true ;
80+
81+ /** The canonical behavior contract, exported for the contract test. */
82+ export const CANONICAL_CONFIG_BEHAVIORS = {
83+ autoSelectModelOnProviderChange,
84+ disableModelSelectDuringDiscovery,
85+ preserveCredentialEnvVarsOnProviderChange,
86+ requireProviderForModelAndEffort,
87+ } as const ;
88+
89+ /**
90+ * Disclosure preset → the eight visibility decisions it owns. Effort is
91+ * shown in both presets (onboarding never hid it; the old prop existed but
92+ * was never flipped). Exported for the contract test.
93+ */
94+ export function resolveDisclosure ( disclosure : "full" | "onboarding-essential" ) {
95+ const full = disclosure === "full" ;
96+ return {
97+ showAdvancedFields : full ,
98+ showCustomModelOption : full ,
99+ showCustomProviderOption : full ,
100+ showDescriptions : full ,
101+ showEffortField : true ,
102+ showProviderPlaceholderOption : full ,
103+ showRequiredIndicators : full ,
104+ showUnavailableEffortOptions : full ,
105+ } as const ;
106+ }
107+
64108export type AgentConfigFieldsProps = {
65109 bakedEnv : BakedEnvEntry [ ] ;
66110 selectedRuntime : AcpRuntimeCatalogEntry | undefined ;
@@ -71,26 +115,29 @@ export type AgentConfigFieldsProps = {
71115 onCustomModelEditingChange : ( value : boolean ) => void ;
72116 onIsCustomProviderChange : ( value : boolean ) => void ;
73117 onValidityChange ?: ( valid : boolean ) => void ;
74- autoSelectModelOnProviderChange ?: boolean ;
75- disableModelSelectDuringDiscovery ?: boolean ;
76- effortPlaceholderLabel ?: string ;
77- effortLabel ?: string ;
78- keepSelectedModelValueLabel ?: boolean ;
79- modelPlaceholderLabel ?: string ;
80118 placeholderClassName ?: string ;
81- providerLabel ?: string ;
82- preserveCredentialEnvVarsOnProviderChange ?: boolean ;
83- requireProviderForModelAndEffort ?: boolean ;
84119 selectClassName ?: string ;
120+ /**
121+ * Which disclosure preset to render (PR 2 flag cleanup — replaces eight
122+ * independent show* booleans):
123+ * - "full" (default): the evergreen stance — every field, escape hatch
124+ * (custom model/provider), description, required indicator, and
125+ * unavailable option is visible. Settings, defaults modal, dialogs.
126+ * - "onboarding-essential": onboarding page 4's first-run stance — only
127+ * valid forward choices. No advanced section, no custom escape hatches,
128+ * no descriptions (the page copy does that job), no un-choosing via
129+ * placeholder options, no greyed-out effort levels.
130+ * If a second surface wants the trimmed view, rename this value to plain
131+ * "essential" — and have the conversation about whether it should really
132+ * match onboarding.
133+ */
134+ disclosure ?: "full" | "onboarding-essential" ;
135+ /**
136+ * Harness-conditional, not part of the disclosure preset: provider choice
137+ * only exists for runtimes that support LLM provider selection. PR 3
138+ * derives this internally from selectedRuntime and deletes the prop.
139+ */
85140 showProviderField ?: boolean ;
86- showAdvancedFields ?: boolean ;
87- showCustomModelOption ?: boolean ;
88- showCustomProviderOption ?: boolean ;
89- showDescriptions ?: boolean ;
90- showEffortField ?: boolean ;
91- showProviderPlaceholderOption ?: boolean ;
92- showRequiredIndicators ?: boolean ;
93- showUnavailableEffortOptions ?: boolean ;
94141 unstyled ?: boolean ;
95142 useCustomSelect ?: boolean ;
96143 useChevronSelectIcon ?: boolean ;
@@ -106,30 +153,25 @@ export function AgentConfigFields({
106153 onCustomModelEditingChange,
107154 onIsCustomProviderChange,
108155 onValidityChange,
109- autoSelectModelOnProviderChange = false ,
110- disableModelSelectDuringDiscovery = true ,
111- effortPlaceholderLabel,
112- effortLabel = "Thinking/effort" ,
113- keepSelectedModelValueLabel = false ,
114- modelPlaceholderLabel = "Select model" ,
115156 placeholderClassName,
116- providerLabel = "LLM provider" ,
117- preserveCredentialEnvVarsOnProviderChange = false ,
118- requireProviderForModelAndEffort = false ,
119157 selectClassName,
158+ disclosure = "full" ,
120159 showProviderField = true ,
121- showAdvancedFields = true ,
122- showCustomModelOption = true ,
123- showCustomProviderOption = true ,
124- showDescriptions = true ,
125- showEffortField = true ,
126- showProviderPlaceholderOption = true ,
127- showRequiredIndicators = true ,
128- showUnavailableEffortOptions = true ,
129160 unstyled = false ,
130161 useCustomSelect = false ,
131162 useChevronSelectIcon = false ,
132163} : AgentConfigFieldsProps ) {
164+ const {
165+ showAdvancedFields,
166+ showCustomModelOption,
167+ showCustomProviderOption,
168+ showDescriptions,
169+ showEffortField,
170+ showProviderPlaceholderOption,
171+ showRequiredIndicators,
172+ showUnavailableEffortOptions,
173+ } = resolveDisclosure ( disclosure ) ;
174+
133175 const bakedProvider = React . useMemo (
134176 ( ) => bakedEnv . find ( ( e ) => e . key === "BUZZ_AGENT_PROVIDER" ) ?. value ?? null ,
135177 [ bakedEnv ] ,
@@ -206,9 +248,24 @@ export function AgentConfigFields({
206248 selectedRuntime,
207249 } ) ;
208250
251+ // Mount-time healing policy: onboarding page 4 edits the root config during
252+ // first-run (no higher layers to inherit from), so acting on open is safe
253+ // and intentional there — it heals stale state and picks a valid model.
254+ // Evergreen surfaces (Settings, dialogs) edit saved data that may pair with
255+ // higher layers (see PR #2148 review thread), so they only act after the
256+ // user explicitly edits the provider in this session.
257+ const healOnMount = disclosure === "onboarding-essential" ;
258+ const userEditedProviderRef = React . useRef ( false ) ;
259+ // Read inside effects via ref so biome's exhaustive-deps stays honest:
260+ // refs are stable, and healOnMount is captured at declaration.
261+ const mayMutateDependentFieldsRef = React . useRef ( false ) ;
262+ mayMutateDependentFieldsRef . current =
263+ healOnMount || userEditedProviderRef . current ;
264+
209265 const autoSelectedModelScopeRef = React . useRef < string | null > ( null ) ;
210266 React . useEffect ( ( ) => {
211267 if ( ! autoSelectModelOnProviderChange ) return ;
268+ if ( ! mayMutateDependentFieldsRef . current ) return ;
212269 const trimmedProvider = providerForDiscovery . trim ( ) ;
213270 if ( trimmedProvider . length === 0 || isCustomProvider ) {
214271 autoSelectedModelScopeRef . current = null ;
@@ -228,7 +285,6 @@ export function AgentConfigFields({
228285 onCustomModelEditingChange ( false ) ;
229286 onConfigChange ( { ...config , model : firstModel . id } ) ;
230287 } , [
231- autoSelectModelOnProviderChange ,
232288 config ,
233289 discoveredModelOptions ,
234290 isCustomProvider ,
@@ -241,7 +297,16 @@ export function AgentConfigFields({
241297
242298 const currentEffortForAutoClear =
243299 config . env_vars [ BUZZ_AGENT_THINKING_EFFORT ] ?? "" ;
300+ // Orphan-model clearing follows the mount-time healing policy above: the
301+ // backend resolves provider and model independently across layers
302+ // (agent → definition → global), so a saved global model WITHOUT a global
303+ // provider can be a deliberate, working pattern (provider supplied by a
304+ // higher layer). Clearing it on page-open in evergreen surfaces silently
305+ // breaks that agent on its next restart — see PR #2148 review thread.
306+ // Onboarding heals on open by design (discriminating spec: "gates stale
307+ // saved model and effort until provider selection").
244308 React . useEffect ( ( ) => {
309+ if ( ! mayMutateDependentFieldsRef . current ) return ;
245310 if ( ! dependentFieldsDisabled ) return ;
246311 if (
247312 ( config . model ?? "" ) . trim ( ) . length === 0 &&
@@ -276,6 +341,7 @@ export function AgentConfigFields({
276341 } ) ;
277342
278343 function handleProviderChange ( value : string ) {
344+ userEditedProviderRef . current = true ;
279345 const previousApiKey = getProviderApiKeyEnvVar ( effectiveProvider ) ;
280346 if ( value === CUSTOM_PROVIDER_DROPDOWN_VALUE ) {
281347 const nextEnvVars = { ...config . env_vars } ;
@@ -458,7 +524,7 @@ export function AgentConfigFields({
458524 className = { cn ( "text-sm font-medium" , fieldLabelClassName ) }
459525 htmlFor = "global-agent-provider"
460526 >
461- { providerLabel }
527+ Provider
462528 </ label >
463529 { ! useCustomSelect && useChevronSelectIcon ? (
464530 < div className = "relative" >
@@ -526,7 +592,7 @@ export function AgentConfigFields({
526592 fallbackModel === null &&
527593 ! dependentFieldsDisabled
528594 }
529- keepSelectedModelValueLabel = { keepSelectedModelValueLabel }
595+ keepSelectedModelValueLabel
530596 model = { dependentFieldsDisabled ? "" : ( config . model ?? "" ) }
531597 modelDiscoveryLoading = {
532598 dependentFieldsDisabled ? false : modelDiscoveryLoading
@@ -537,7 +603,7 @@ export function AgentConfigFields({
537603 onIsCustomModelEditingChange = { onCustomModelEditingChange }
538604 onModelChange = { handleModelChange }
539605 placeholderClassName = { placeholderClassName }
540- placeholder = { modelPlaceholderLabel }
606+ placeholder = "Select a model"
541607 provider = { providerForDiscovery }
542608 fieldClassName = { unstyled ? fieldClassName : undefined }
543609 labelClassName = { fieldLabelClassName }
@@ -556,7 +622,16 @@ export function AgentConfigFields({
556622 < EffortSelectField
557623 currentEffort = { dependentFieldsDisabled ? "" : currentEffort }
558624 disabled = { dependentFieldsDisabled }
559- emptyOptionLabel = { effortPlaceholderLabel }
625+ emptyOptionLabel = {
626+ // Semantic, not copy: onboarding-essential hides inheritance
627+ // concepts (first-run users pick, they don't inherit), so the
628+ // zero option is a plain placeholder. Full disclosure leaves
629+ // this unset so EffortSelectField computes the inherit/default
630+ // label ("Default (medium)", "Inherit (high)", …).
631+ disclosure === "onboarding-essential"
632+ ? "Select effort level"
633+ : undefined
634+ }
560635 effortDefault = { effortDefault }
561636 effortValid = { effortValid }
562637 fieldClassName = { unstyled ? fieldClassName : undefined }
@@ -565,7 +640,7 @@ export function AgentConfigFields({
565640 effortDefault !== null ? `Default (${ effortDefault } )` : undefined
566641 }
567642 inheritedEffort = { bakedEffort ?? undefined }
568- label = { effortLabel }
643+ label = "Effort"
569644 labelClassName = { fieldLabelClassName }
570645 onChange = { ( value ) => {
571646 const nextEnvVars = { ...config . env_vars } ;
0 commit comments