Skip to content

Commit ad990b0

Browse files
authored
Reduce agent config flags to canonical behaviors + disclosure presets (#2148)
1 parent 7f769b2 commit ad990b0

3 files changed

Lines changed: 175 additions & 56 deletions

File tree

‎desktop/src/features/agents/ui/AgentConfigFields.tsx‎

Lines changed: 115 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
64108
export 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 };
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
/**
2+
* Contract tests for the canonical agent-config behaviors and disclosure
3+
* presets (PR 2 flag cleanup).
4+
*
5+
* Before PR 2, AgentConfigFields exposed 23 optional props and no test pinned
6+
* any surface's behavior — a flag could be flipped or reintroduced and the
7+
* suite would stay green. These tests pin the decided contract:
8+
*
9+
* 1. The four canonical behaviors hold (onboarding's values won every call).
10+
* 2. "full" disclosure shows everything (the evergreen stance).
11+
* 3. "onboarding-essential" hides escape hatches and power tools, but
12+
* NEVER the effort field (onboarding never hid it).
13+
*
14+
* If a future change needs a different behavior or preset, it must edit these
15+
* assertions — which is the conversation the flag cleanup was designed to force.
16+
*/
17+
18+
import assert from "node:assert/strict";
19+
import test from "node:test";
20+
21+
import {
22+
CANONICAL_CONFIG_BEHAVIORS,
23+
resolveDisclosure,
24+
} from "./AgentConfigFields.tsx";
25+
26+
test("canonical behaviors: onboarding's values are the only behavior", () => {
27+
assert.deepEqual(CANONICAL_CONFIG_BEHAVIORS, {
28+
// Changing provider auto-selects a valid model (no dead-end empty model).
29+
autoSelectModelOnProviderChange: true,
30+
// Model select stays usable while discovery loads (no flash-disable).
31+
disableModelSelectDuringDiscovery: false,
32+
// Switching provider keeps the old provider's typed API key in env_vars.
33+
preserveCredentialEnvVarsOnProviderChange: true,
34+
// Model/effort are locked until a provider exists (no saveable invalid state).
35+
requireProviderForModelAndEffort: true,
36+
});
37+
});
38+
39+
test("full disclosure shows every field, escape hatch, and description", () => {
40+
const full = resolveDisclosure("full");
41+
for (const [key, value] of Object.entries(full)) {
42+
assert.equal(value, true, `full preset must show ${key}`);
43+
}
44+
});
45+
46+
test("onboarding-essential hides power tools but never the effort field", () => {
47+
const essential = resolveDisclosure("onboarding-essential");
48+
assert.deepEqual(essential, {
49+
showAdvancedFields: false,
50+
showCustomModelOption: false,
51+
showCustomProviderOption: false,
52+
showDescriptions: false,
53+
// Effort was never hidden by onboarding; both presets show it.
54+
showEffortField: true,
55+
showProviderPlaceholderOption: false,
56+
showRequiredIndicators: false,
57+
showUnavailableEffortOptions: false,
58+
});
59+
});

‎desktop/src/features/onboarding/ui/DefaultConfigStep.tsx‎

Lines changed: 1 addition & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -195,11 +195,6 @@ function AgentDefaultsSection({
195195
config={config}
196196
isCustomModelEditing={isCustomModelEditing}
197197
isCustomProvider={isCustomProvider}
198-
autoSelectModelOnProviderChange
199-
disableModelSelectDuringDiscovery={false}
200-
effortPlaceholderLabel="Select effort level"
201-
keepSelectedModelValueLabel
202-
modelPlaceholderLabel="Select a model"
203198
onConfigChange={(next) => {
204199
// Always apply optimistically so the UI never reverts mid-save,
205200
// then enqueue the persist — the coalescer serialises multiple
@@ -209,20 +204,10 @@ function AgentDefaultsSection({
209204
}}
210205
onCustomModelEditingChange={setIsCustomModelEditing}
211206
onIsCustomProviderChange={setIsCustomProvider}
212-
preserveCredentialEnvVarsOnProviderChange
213-
effortLabel="Effort"
214207
placeholderClassName="text-foreground/70"
215-
providerLabel="Provider"
216-
requireProviderForModelAndEffort
217208
selectClassName="h-12 rounded-2xl border-foreground/15 bg-white px-4 py-2 text-sm shadow-none hover:bg-white/95"
218-
showAdvancedFields={false}
219-
showCustomModelOption={false}
220-
showCustomProviderOption={false}
221-
showDescriptions={false}
209+
disclosure="onboarding-essential"
222210
showProviderField={selectedRuntimeSupportsModelProvider}
223-
showRequiredIndicators={false}
224-
showProviderPlaceholderOption={false}
225-
showUnavailableEffortOptions={false}
226211
unstyled
227212
useCustomSelect
228213
/>

0 commit comments

Comments
 (0)