Skip to content

Commit 50f4412

Browse files
authored
Hide bundled harnesses from onboarding (#2233)
1 parent b9f54c4 commit 50f4412

14 files changed

Lines changed: 758 additions & 1900 deletions

‎desktop/src/features/agents/AGENTS.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,12 @@ with a TypeScript lookup table or an id comparison in a component.
5454
flags were deliberately killed in #2148 (`CANONICAL_CONFIG_BEHAVIORS`).
5555
Surface differences are expressed via the `disclosure` preset, not new
5656
boolean props.
57-
7. **Onboarding does not change.** `onboarding-agent-defaults.spec.ts` is the
58-
acceptance gate for anything touching the shared renderer.
57+
7. **Onboarding setup detects readiness; it does not select defaults.** The
58+
setup page derives visible and ready harnesses from the runtime catalog and
59+
only offers install or sign-in actions. The following defaults page is the
60+
sole onboarding surface that chooses and persists `preferred_runtime`.
61+
`onboarding-agent-defaults.spec.ts` is the acceptance gate for anything
62+
touching this flow or the shared renderer.
5963

6064
## The tests that enforce this
6165

@@ -64,7 +68,8 @@ with a TypeScript lookup table or an id comparison in a component.
6468
- `ui/agentConfigFieldsContract.test.mjs` — canonical behaviors + disclosure
6569
presets. If this fails, you probably reintroduced a per-surface flag.
6670
- `desktop/tests/e2e/onboarding-agent-defaults.spec.ts` — onboarding behavior
67-
pin (35 tests).
71+
acceptance coverage for readiness, failure states, defaults, navigation, and
72+
persistence races.
6873
- Rust: `runtime_metadata_env_vars` tests pin spawn-time key application.
6974

7075
## Keep this file true

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

Lines changed: 101 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -25,41 +25,32 @@ import {
2525
type OnboardingTransitionDirection,
2626
OnboardingSlideTransition,
2727
} from "./OnboardingSlideTransition";
28-
import { ONBOARDING_RUNTIME_ORDER } from "./onboardingRuntimeSelection";
28+
import {
29+
getReadyOnboardingRuntimes,
30+
getVisibleOnboardingRuntimes,
31+
} from "./onboardingRuntimeSelection";
2932
import type { DefaultConfigStepActions } from "./types";
3033

3134
type DefaultConfigStepProps = {
3235
actions: DefaultConfigStepActions;
3336
direction: OnboardingTransitionDirection;
34-
selectedRuntimeIds: readonly string[];
37+
readyRuntimeIds: readonly string[];
3538
};
3639

3740
function formatHarnessLabel(runtime: AcpRuntimeCatalogEntry | undefined) {
3841
if (!runtime) return "Select a harness";
3942
return runtime.id === "buzz-agent" ? "Buzz" : runtime.label;
4043
}
4144

42-
function sortSelectedRuntimes(
43-
runtimes: readonly AcpRuntimeCatalogEntry[],
44-
selectedRuntimeIds: readonly string[],
45-
) {
46-
const selectedRuntimeIdSet = new Set(selectedRuntimeIds);
47-
return runtimes
48-
.filter((runtime) => selectedRuntimeIdSet.has(runtime.id))
49-
.sort((left, right) => {
50-
const leftIndex = ONBOARDING_RUNTIME_ORDER.indexOf(left.id);
51-
const rightIndex = ONBOARDING_RUNTIME_ORDER.indexOf(right.id);
52-
return (
53-
(leftIndex === -1 ? ONBOARDING_RUNTIME_ORDER.length : leftIndex) -
54-
(rightIndex === -1 ? ONBOARDING_RUNTIME_ORDER.length : rightIndex)
55-
);
56-
});
57-
}
58-
5945
function AgentDefaultsSection({
60-
selectedRuntimeIds,
46+
onPersistenceStateChange,
47+
readyRuntimeIds,
6148
}: {
62-
selectedRuntimeIds: readonly string[];
49+
onPersistenceStateChange: (state: {
50+
canComplete: boolean;
51+
flush: () => Promise<void>;
52+
}) => void;
53+
readyRuntimeIds: readonly string[];
6354
}) {
6455
const runtimesQuery = useAcpRuntimesQuery();
6556
const [config, setConfig] =
@@ -70,8 +61,10 @@ function AgentDefaultsSection({
7061
const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
7162
const coalescerRef = React.useRef<{
7263
enqueue: (value: GlobalAgentConfig) => void;
64+
flush: () => Promise<void>;
7365
cancel: () => void;
7466
} | null>(null);
67+
const [isSaving, setIsSaving] = React.useState(false);
7568

7669
React.useEffect(() => {
7770
let unmounted = false;
@@ -102,7 +95,9 @@ function AgentDefaultsSection({
10295
// set_global_agent_config returns a save result (config + restart
10396
// counts); the coalescer round-trips the persisted config only.
10497
async (next) => (await setGlobalAgentConfig(next)).config,
105-
() => undefined, // saving state not surfaced in this autosave UX
98+
(saving) => {
99+
if (!unmounted) setIsSaving(saving);
100+
},
106101
(saved) => {
107102
if (!unmounted) setConfig(saved);
108103
},
@@ -115,31 +110,48 @@ function AgentDefaultsSection({
115110
};
116111
}, []);
117112

118-
const selectedRuntimes = React.useMemo(
119-
() => sortSelectedRuntimes(runtimesQuery.data ?? [], selectedRuntimeIds),
120-
[runtimesQuery.data, selectedRuntimeIds],
113+
const effectiveReadyRuntimeIds = React.useMemo(
114+
() =>
115+
readyRuntimeIds.length > 0
116+
? readyRuntimeIds
117+
: getReadyOnboardingRuntimes(runtimesQuery.data ?? []).map(
118+
(runtime) => runtime.id,
119+
),
120+
[readyRuntimeIds, runtimesQuery.data],
121121
);
122-
const selectedRuntime = React.useMemo(() => {
123-
const preferredRuntime = selectedRuntimes.find(
124-
(runtime) => runtime.id === config.preferred_runtime,
125-
);
126-
return preferredRuntime ?? selectedRuntimes[0];
127-
}, [config.preferred_runtime, selectedRuntimes]);
128-
const selectedRuntimeId =
129-
selectedRuntime?.id ?? config.preferred_runtime ?? "";
122+
const readyRuntimeIdSet = React.useMemo(
123+
() => new Set(effectiveReadyRuntimeIds),
124+
[effectiveReadyRuntimeIds],
125+
);
126+
// Setup already confirmed readiness. Re-filter only for onboarding
127+
// visibility here; a transient auth recheck must not invalidate that handoff.
128+
const readyRuntimes = React.useMemo(
129+
() =>
130+
getVisibleOnboardingRuntimes(runtimesQuery.data ?? []).filter((runtime) =>
131+
readyRuntimeIdSet.has(runtime.id),
132+
),
133+
[readyRuntimeIdSet, runtimesQuery.data],
134+
);
135+
const selectedRuntime = React.useMemo(
136+
() =>
137+
readyRuntimes.find((runtime) => runtime.id === config.preferred_runtime),
138+
[config.preferred_runtime, readyRuntimes],
139+
);
140+
const selectedRuntimeId = selectedRuntime?.id ?? "";
130141
const configSurfaceLoading = isLoading || runtimesQuery.isLoading;
142+
131143
const configSurfaceError =
132144
runtimesQuery.isError ||
133145
(!configSurfaceLoading &&
134-
selectedRuntimeIds.length > 0 &&
135-
!selectedRuntime);
146+
effectiveReadyRuntimeIds.length > 0 &&
147+
readyRuntimes.length === 0);
136148
const harnessOptions = React.useMemo(
137149
() =>
138-
selectedRuntimes.map((runtime) => ({
150+
readyRuntimes.map((runtime) => ({
139151
label: formatHarnessLabel(runtime),
140152
value: runtime.id,
141153
})),
142-
[selectedRuntimes],
154+
[readyRuntimes],
143155
);
144156

145157
const handleHarnessChange = React.useCallback(
@@ -154,21 +166,27 @@ function AgentDefaultsSection({
154166
);
155167

156168
React.useEffect(() => {
157-
if (isLoading || !selectedRuntimeId) return;
158-
if (config.preferred_runtime === selectedRuntimeId) return;
159-
160-
// The user can go Back, change which harnesses are selected, then return to
161-
// this page without using this page's own harness dropdown. Reconcile that
162-
// effective harness change through the same reset path so a Codex model
163-
// never survives into Claude Code as a custom model (or vice versa).
164-
handleHarnessChange(selectedRuntimeId);
169+
if (configSurfaceLoading || selectedRuntimeId) return;
170+
if (readyRuntimes.length !== 1) return;
171+
handleHarnessChange(readyRuntimes[0].id);
165172
}, [
166-
config.preferred_runtime,
173+
configSurfaceLoading,
167174
handleHarnessChange,
168-
isLoading,
175+
readyRuntimes,
169176
selectedRuntimeId,
170177
]);
171178

179+
const flushPersistence = React.useCallback(
180+
() => coalescerRef.current?.flush() ?? Promise.resolve(),
181+
[],
182+
);
183+
React.useEffect(() => {
184+
onPersistenceStateChange({
185+
canComplete: selectedRuntimeId.length > 0 && !isSaving,
186+
flush: flushPersistence,
187+
});
188+
}, [flushPersistence, isSaving, onPersistenceStateChange, selectedRuntimeId]);
189+
172190
return (
173191
<section className="w-full space-y-4 text-left text-sm">
174192
{configSurfaceLoading ? (
@@ -236,8 +254,29 @@ function AgentDefaultsSection({
236254
export function DefaultConfigStep({
237255
actions,
238256
direction,
239-
selectedRuntimeIds,
257+
readyRuntimeIds,
240258
}: DefaultConfigStepProps) {
259+
const [persistenceState, setPersistenceState] = React.useState<{
260+
canComplete: boolean;
261+
flush: () => Promise<void>;
262+
}>({ canComplete: false, flush: () => Promise.resolve() });
263+
const [completionError, setCompletionError] = React.useState<string | null>(
264+
null,
265+
);
266+
const [isCompleting, setIsCompleting] = React.useState(false);
267+
268+
const handleComplete = React.useCallback(async () => {
269+
setIsCompleting(true);
270+
setCompletionError(null);
271+
try {
272+
await persistenceState.flush();
273+
actions.complete();
274+
} catch {
275+
setCompletionError("Couldn't save your default harness. Try again.");
276+
setIsCompleting(false);
277+
}
278+
}, [actions, persistenceState]);
279+
241280
return (
242281
<OnboardingSlideTransition
243282
className="flex min-h-full w-full flex-col items-center"
@@ -258,15 +297,27 @@ export function DefaultConfigStep({
258297

259298
<div className="flex w-full flex-1 items-center justify-center py-10">
260299
<div className="w-full max-w-[328px]">
261-
<AgentDefaultsSection selectedRuntimeIds={selectedRuntimeIds} />
300+
<AgentDefaultsSection
301+
onPersistenceStateChange={setPersistenceState}
302+
readyRuntimeIds={readyRuntimeIds}
303+
/>
304+
{completionError ? (
305+
<p
306+
className="mt-3 text-center text-xs text-destructive"
307+
role="alert"
308+
>
309+
{completionError}
310+
</p>
311+
) : null}
262312
</div>
263313
</div>
264314

265315
<OnboardingFooter>
266316
<Button
267317
className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
268318
data-testid="onboarding-finish"
269-
onClick={actions.complete}
319+
disabled={!persistenceState.canComplete || isCompleting}
320+
onClick={() => void handleComplete()}
270321
type="button"
271322
>
272323
Next

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

Lines changed: 7 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,11 @@
11
import * as React from "react";
22
import type { QueryClient } from "@tanstack/react-query";
33

4-
import {
5-
getGlobalAgentConfig,
6-
setGlobalAgentConfig,
7-
} from "@/shared/api/tauriGlobalAgentConfig";
84
import {
95
getIdentity,
106
importIdentity,
117
persistCurrentIdentity,
128
} from "@/shared/api/tauriIdentity";
13-
import { resetConfigForHarnessChange } from "@/features/agents/ui/agentConfigOptions";
149
import { Button } from "@/shared/ui/button";
1510
import { StartupWindowDragRegion } from "@/shared/ui/StartupWindowDragRegion";
1611
import { BackupStep } from "./BackupStep";
@@ -23,10 +18,6 @@ import {
2318
OnboardingChrome,
2419
} from "./OnboardingChrome";
2520
import { OnboardingFooterProvider } from "./OnboardingFooter";
26-
import {
27-
getPreferredRuntimeIdForSelection,
28-
runtimeSelectionNeedsDefaultsStep,
29-
} from "./onboardingRuntimeSelection";
3021
import { OnboardingSlideTransition } from "./OnboardingSlideTransition";
3122
import { SetupStep } from "./SetupStep";
3223

@@ -59,63 +50,10 @@ export function MachineOnboardingFlow({
5950
const [selectedPubkey, setSelectedPubkey] = React.useState<string | null>(
6051
null,
6152
);
62-
const [selectedRuntimeIds, setSelectedRuntimeIds] = React.useState<string[]>(
63-
[],
64-
);
65-
const [isRuntimeSelectionSaving, setIsRuntimeSelectionSaving] =
66-
React.useState(false);
67-
const [runtimeSelectionError, setRuntimeSelectionError] = React.useState<
68-
string | null
69-
>(null);
70-
const runtimeSaveSequence = React.useRef(0);
71-
const runtimeSaveChain = React.useRef<Promise<void>>(Promise.resolve());
72-
73-
const persistHarnessSelection = React.useCallback(
53+
const [readyRuntimeIds, setReadyRuntimeIds] = React.useState<string[]>([]);
54+
const handleReadyRuntimeIdsChange = React.useCallback(
7455
(runtimeIds: readonly string[]) => {
75-
const nextRuntimeIds = Array.from(new Set(runtimeIds));
76-
const preferredRuntimeId =
77-
getPreferredRuntimeIdForSelection(nextRuntimeIds);
78-
const sequence = runtimeSaveSequence.current + 1;
79-
runtimeSaveSequence.current = sequence;
80-
setSelectedRuntimeIds(nextRuntimeIds);
81-
setRuntimeSelectionError(null);
82-
setIsRuntimeSelectionSaving(true);
83-
84-
const save = runtimeSaveChain.current.then(async () => {
85-
const current = await getGlobalAgentConfig();
86-
const selectedHarnessChanged =
87-
current.preferred_runtime !== preferredRuntimeId;
88-
if (!selectedHarnessChanged) {
89-
await setGlobalAgentConfig({
90-
...current,
91-
preferred_runtime: preferredRuntimeId,
92-
});
93-
return;
94-
}
95-
96-
await setGlobalAgentConfig(
97-
resetConfigForHarnessChange(current, preferredRuntimeId ?? ""),
98-
);
99-
});
100-
runtimeSaveChain.current = save.then(
101-
() => undefined,
102-
() => undefined,
103-
);
104-
void save
105-
.catch((cause) => {
106-
if (runtimeSaveSequence.current === sequence) {
107-
setRuntimeSelectionError(
108-
cause instanceof Error
109-
? cause.message
110-
: "Couldn’t save your harness selection.",
111-
);
112-
}
113-
})
114-
.finally(() => {
115-
if (runtimeSaveSequence.current === sequence) {
116-
setIsRuntimeSelectionSaving(false);
117-
}
118-
});
56+
setReadyRuntimeIds(Array.from(new Set(runtimeIds)));
11957
},
12058
[],
12159
);
@@ -276,22 +214,13 @@ export function MachineOnboardingFlow({
276214
actions={{
277215
back: () =>
278216
setPage(identityWasImported ? "key-import" : "backup"),
279-
next: () => {
280-
if (selectedRuntimeIds.length === 0) return;
281-
if (!runtimeSelectionNeedsDefaultsStep(selectedRuntimeIds)) {
282-
complete(selectedPubkey ?? undefined);
283-
return;
284-
}
217+
next: (runtimeIds) => {
218+
setReadyRuntimeIds(Array.from(runtimeIds));
285219
setPage("config");
286220
},
287221
}}
288222
direction="forward"
289-
isSelectionSaving={isRuntimeSelectionSaving}
290-
onSelectedRuntimeIdsChange={(runtimeIds) => {
291-
void persistHarnessSelection(runtimeIds);
292-
}}
293-
selectionError={runtimeSelectionError}
294-
selectedRuntimeIds={selectedRuntimeIds}
223+
onReadyRuntimeIdsChange={handleReadyRuntimeIdsChange}
295224
/>
296225
) : (
297226
<DefaultConfigStep
@@ -300,7 +229,7 @@ export function MachineOnboardingFlow({
300229
complete: () => complete(selectedPubkey ?? undefined),
301230
}}
302231
direction="forward"
303-
selectedRuntimeIds={selectedRuntimeIds}
232+
readyRuntimeIds={readyRuntimeIds}
304233
/>
305234
)}
306235
</div>

0 commit comments

Comments
 (0)