Skip to content

Hide bundled harnesses from onboarding #2233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
morgmart merged 11 commits into from
Jul 21, 2026
Merged

Hide bundled harnesses from onboarding #2233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
4277bb3
Hide bundled harnesses from onboarding
morgmart Jul 21, 2026
2fc936e
Detect harness readiness during onboarding
morgmart Jul 21, 2026
201e33f
Test onboarding harness readiness flow
morgmart Jul 21, 2026
bee0588
Trust onboarding readiness handoff
morgmart Jul 21, 2026
f3be775
Hide onboarding readiness checkmark
morgmart Jul 21, 2026
6afed8f
Update onboarding screenshot heading
morgmart Jul 21, 2026
f9dcc59
Update readiness tests for hidden checkmark
morgmart Jul 21, 2026
0bff8bb
Stop completed sign-in polling
morgmart Jul 21, 2026
78a394b
Auto-select sole onboarding harness
morgmart Jul 21, 2026
75599d3
Harden onboarding defaults persistence
morgmart Jul 21, 2026
8a584a6
Seed direct onboarding config readiness
morgmart Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions desktop/src/features/agents/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,12 @@ with a TypeScript lookup table or an id comparison in a component.
flags were deliberately killed in #2148 (`CANONICAL_CONFIG_BEHAVIORS`).
Surface differences are expressed via the `disclosure` preset, not new
boolean props.
7. **Onboarding does not change.** `onboarding-agent-defaults.spec.ts` is the
acceptance gate for anything touching the shared renderer.
7. **Onboarding setup detects readiness; it does not select defaults.** The
setup page derives visible and ready harnesses from the runtime catalog and
only offers install or sign-in actions. The following defaults page is the
sole onboarding surface that chooses and persists `preferred_runtime`.
`onboarding-agent-defaults.spec.ts` is the acceptance gate for anything
touching this flow or the shared renderer.

## The tests that enforce this

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

## Keep this file true
Expand Down
151 changes: 101 additions & 50 deletions desktop/src/features/onboarding/ui/DefaultConfigStep.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,41 +25,32 @@ import {
type OnboardingTransitionDirection,
OnboardingSlideTransition,
} from "./OnboardingSlideTransition";
import { ONBOARDING_RUNTIME_ORDER } from "./onboardingRuntimeSelection";
import {
getReadyOnboardingRuntimes,
getVisibleOnboardingRuntimes,
} from "./onboardingRuntimeSelection";
import type { DefaultConfigStepActions } from "./types";

type DefaultConfigStepProps = {
actions: DefaultConfigStepActions;
direction: OnboardingTransitionDirection;
selectedRuntimeIds: readonly string[];
readyRuntimeIds: readonly string[];
};

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

function sortSelectedRuntimes(
runtimes: readonly AcpRuntimeCatalogEntry[],
selectedRuntimeIds: readonly string[],
) {
const selectedRuntimeIdSet = new Set(selectedRuntimeIds);
return runtimes
.filter((runtime) => selectedRuntimeIdSet.has(runtime.id))
.sort((left, right) => {
const leftIndex = ONBOARDING_RUNTIME_ORDER.indexOf(left.id);
const rightIndex = ONBOARDING_RUNTIME_ORDER.indexOf(right.id);
return (
(leftIndex === -1 ? ONBOARDING_RUNTIME_ORDER.length : leftIndex) -
(rightIndex === -1 ? ONBOARDING_RUNTIME_ORDER.length : rightIndex)
);
});
}

function AgentDefaultsSection({
selectedRuntimeIds,
onPersistenceStateChange,
readyRuntimeIds,
}: {
selectedRuntimeIds: readonly string[];
onPersistenceStateChange: (state: {
canComplete: boolean;
flush: () => Promise<void>;
}) => void;
readyRuntimeIds: readonly string[];
}) {
const runtimesQuery = useAcpRuntimesQuery();
const [config, setConfig] =
Expand All @@ -70,8 +61,10 @@ function AgentDefaultsSection({
const [bakedEnv, setBakedEnv] = React.useState<BakedEnvEntry[]>([]);
const coalescerRef = React.useRef<{
enqueue: (value: GlobalAgentConfig) => void;
flush: () => Promise<void>;
cancel: () => void;
} | null>(null);
const [isSaving, setIsSaving] = React.useState(false);

React.useEffect(() => {
let unmounted = false;
Expand Down Expand Up @@ -102,7 +95,9 @@ function AgentDefaultsSection({
// set_global_agent_config returns a save result (config + restart
// counts); the coalescer round-trips the persisted config only.
async (next) => (await setGlobalAgentConfig(next)).config,
() => undefined, // saving state not surfaced in this autosave UX
(saving) => {
if (!unmounted) setIsSaving(saving);
},
(saved) => {
if (!unmounted) setConfig(saved);
},
Expand All @@ -115,31 +110,48 @@ function AgentDefaultsSection({
};
}, []);

const selectedRuntimes = React.useMemo(
() => sortSelectedRuntimes(runtimesQuery.data ?? [], selectedRuntimeIds),
[runtimesQuery.data, selectedRuntimeIds],
const effectiveReadyRuntimeIds = React.useMemo(
() =>
readyRuntimeIds.length > 0
? readyRuntimeIds
: getReadyOnboardingRuntimes(runtimesQuery.data ?? []).map(
(runtime) => runtime.id,
),
[readyRuntimeIds, runtimesQuery.data],
);
const selectedRuntime = React.useMemo(() => {
const preferredRuntime = selectedRuntimes.find(
(runtime) => runtime.id === config.preferred_runtime,
);
return preferredRuntime ?? selectedRuntimes[0];
}, [config.preferred_runtime, selectedRuntimes]);
const selectedRuntimeId =
selectedRuntime?.id ?? config.preferred_runtime ?? "";
const readyRuntimeIdSet = React.useMemo(
() => new Set(effectiveReadyRuntimeIds),
[effectiveReadyRuntimeIds],
);
// Setup already confirmed readiness. Re-filter only for onboarding
// visibility here; a transient auth recheck must not invalidate that handoff.
const readyRuntimes = React.useMemo(
() =>
getVisibleOnboardingRuntimes(runtimesQuery.data ?? []).filter((runtime) =>
readyRuntimeIdSet.has(runtime.id),
),
[readyRuntimeIdSet, runtimesQuery.data],
);
const selectedRuntime = React.useMemo(
() =>
readyRuntimes.find((runtime) => runtime.id === config.preferred_runtime),
[config.preferred_runtime, readyRuntimes],
);
const selectedRuntimeId = selectedRuntime?.id ?? "";
const configSurfaceLoading = isLoading || runtimesQuery.isLoading;

const configSurfaceError =
runtimesQuery.isError ||
(!configSurfaceLoading &&
selectedRuntimeIds.length > 0 &&
!selectedRuntime);
effectiveReadyRuntimeIds.length > 0 &&
readyRuntimes.length === 0);
const harnessOptions = React.useMemo(
() =>
selectedRuntimes.map((runtime) => ({
readyRuntimes.map((runtime) => ({
label: formatHarnessLabel(runtime),
value: runtime.id,
})),
[selectedRuntimes],
[readyRuntimes],
);

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

React.useEffect(() => {
if (isLoading || !selectedRuntimeId) return;
if (config.preferred_runtime === selectedRuntimeId) return;

// The user can go Back, change which harnesses are selected, then return to
// this page without using this page's own harness dropdown. Reconcile that
// effective harness change through the same reset path so a Codex model
// never survives into Claude Code as a custom model (or vice versa).
handleHarnessChange(selectedRuntimeId);
if (configSurfaceLoading || selectedRuntimeId) return;
if (readyRuntimes.length !== 1) return;
handleHarnessChange(readyRuntimes[0].id);
}, [
config.preferred_runtime,
configSurfaceLoading,
handleHarnessChange,
isLoading,
readyRuntimes,
selectedRuntimeId,
]);

const flushPersistence = React.useCallback(
() => coalescerRef.current?.flush() ?? Promise.resolve(),
[],
);
React.useEffect(() => {
onPersistenceStateChange({
canComplete: selectedRuntimeId.length > 0 && !isSaving,
flush: flushPersistence,
});
}, [flushPersistence, isSaving, onPersistenceStateChange, selectedRuntimeId]);

return (
<section className="w-full space-y-4 text-left text-sm">
{configSurfaceLoading ? (
Expand Down Expand Up @@ -236,8 +254,29 @@ function AgentDefaultsSection({
export function DefaultConfigStep({
actions,
direction,
selectedRuntimeIds,
readyRuntimeIds,
}: DefaultConfigStepProps) {
const [persistenceState, setPersistenceState] = React.useState<{
canComplete: boolean;
flush: () => Promise<void>;
}>({ canComplete: false, flush: () => Promise.resolve() });
const [completionError, setCompletionError] = React.useState<string | null>(
null,
);
const [isCompleting, setIsCompleting] = React.useState(false);

const handleComplete = React.useCallback(async () => {
setIsCompleting(true);
setCompletionError(null);
try {
await persistenceState.flush();
actions.complete();
} catch {
setCompletionError("Couldn't save your default harness. Try again.");
setIsCompleting(false);
}
}, [actions, persistenceState]);

return (
<OnboardingSlideTransition
className="flex min-h-full w-full flex-col items-center"
Expand All @@ -258,15 +297,27 @@ export function DefaultConfigStep({

<div className="flex w-full flex-1 items-center justify-center py-10">
<div className="w-full max-w-[328px]">
<AgentDefaultsSection selectedRuntimeIds={selectedRuntimeIds} />
<AgentDefaultsSection
onPersistenceStateChange={setPersistenceState}
readyRuntimeIds={readyRuntimeIds}
/>
{completionError ? (
<p
className="mt-3 text-center text-xs text-destructive"
role="alert"
>
{completionError}
</p>
) : null}
</div>
</div>

<OnboardingFooter>
<Button
className={`${ONBOARDING_PRIMARY_CTA_CLASS} text-sm`}
data-testid="onboarding-finish"
onClick={actions.complete}
disabled={!persistenceState.canComplete || isCompleting}
onClick={() => void handleComplete()}
type="button"
>
Next
Expand Down
85 changes: 7 additions & 78 deletions desktop/src/features/onboarding/ui/MachineOnboardingFlow.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,11 @@
import * as React from "react";
import type { QueryClient } from "@tanstack/react-query";

import {
getGlobalAgentConfig,
setGlobalAgentConfig,
} from "@/shared/api/tauriGlobalAgentConfig";
import {
getIdentity,
importIdentity,
persistCurrentIdentity,
} from "@/shared/api/tauriIdentity";
import { resetConfigForHarnessChange } from "@/features/agents/ui/agentConfigOptions";
import { Button } from "@/shared/ui/button";
import { StartupWindowDragRegion } from "@/shared/ui/StartupWindowDragRegion";
import { BackupStep } from "./BackupStep";
Expand All @@ -23,10 +18,6 @@ import {
OnboardingChrome,
} from "./OnboardingChrome";
import { OnboardingFooterProvider } from "./OnboardingFooter";
import {
getPreferredRuntimeIdForSelection,
runtimeSelectionNeedsDefaultsStep,
} from "./onboardingRuntimeSelection";
import { OnboardingSlideTransition } from "./OnboardingSlideTransition";
import { SetupStep } from "./SetupStep";

Expand Down Expand Up @@ -59,63 +50,10 @@ export function MachineOnboardingFlow({
const [selectedPubkey, setSelectedPubkey] = React.useState<string | null>(
null,
);
const [selectedRuntimeIds, setSelectedRuntimeIds] = React.useState<string[]>(
[],
);
const [isRuntimeSelectionSaving, setIsRuntimeSelectionSaving] =
React.useState(false);
const [runtimeSelectionError, setRuntimeSelectionError] = React.useState<
string | null
>(null);
const runtimeSaveSequence = React.useRef(0);
const runtimeSaveChain = React.useRef<Promise<void>>(Promise.resolve());

const persistHarnessSelection = React.useCallback(
const [readyRuntimeIds, setReadyRuntimeIds] = React.useState<string[]>([]);

@bradseiler bradseiler Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Should this be seeded when the flow starts directly on the config page? reopenMachineConfig can mount MachineOnboardingFlow with initialPage="config", so Setup never reports ready IDs; this stays empty, the harness dropdown has no options, and Finish remains disabled until the user goes Back through setup.

Updated by Codex 🤖

@morgmart morgmart Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Addressed in 8a584a6. When the flow mounts directly on the config page without a Setup handoff, the defaults page now derives ready visible runtime IDs from the settled runtime catalog. The normal Setup handoff still takes precedence. Extended the existing first-community Back regression to verify the sole ready harness is selected and Finish is enabled.

const handleReadyRuntimeIdsChange = React.useCallback(
(runtimeIds: readonly string[]) => {
const nextRuntimeIds = Array.from(new Set(runtimeIds));
const preferredRuntimeId =
getPreferredRuntimeIdForSelection(nextRuntimeIds);
const sequence = runtimeSaveSequence.current + 1;
runtimeSaveSequence.current = sequence;
setSelectedRuntimeIds(nextRuntimeIds);
setRuntimeSelectionError(null);
setIsRuntimeSelectionSaving(true);

const save = runtimeSaveChain.current.then(async () => {
const current = await getGlobalAgentConfig();
const selectedHarnessChanged =
current.preferred_runtime !== preferredRuntimeId;
if (!selectedHarnessChanged) {
await setGlobalAgentConfig({
...current,
preferred_runtime: preferredRuntimeId,
});
return;
}

await setGlobalAgentConfig(
resetConfigForHarnessChange(current, preferredRuntimeId ?? ""),
);
});
runtimeSaveChain.current = save.then(
() => undefined,
() => undefined,
);
void save
.catch((cause) => {
if (runtimeSaveSequence.current === sequence) {
setRuntimeSelectionError(
cause instanceof Error
? cause.message
: "Couldn’t save your harness selection.",
);
}
})
.finally(() => {
if (runtimeSaveSequence.current === sequence) {
setIsRuntimeSelectionSaving(false);
}
});
setReadyRuntimeIds(Array.from(new Set(runtimeIds)));
},
[],
);
Expand Down Expand Up @@ -276,22 +214,13 @@ export function MachineOnboardingFlow({
actions={{
back: () =>
setPage(identityWasImported ? "key-import" : "backup"),
next: () => {
if (selectedRuntimeIds.length === 0) return;
if (!runtimeSelectionNeedsDefaultsStep(selectedRuntimeIds)) {
complete(selectedPubkey ?? undefined);
return;
}
next: (runtimeIds) => {
setReadyRuntimeIds(Array.from(runtimeIds));
setPage("config");
},
}}
direction="forward"
isSelectionSaving={isRuntimeSelectionSaving}
onSelectedRuntimeIdsChange={(runtimeIds) => {
void persistHarnessSelection(runtimeIds);
}}
selectionError={runtimeSelectionError}
selectedRuntimeIds={selectedRuntimeIds}
onReadyRuntimeIdsChange={handleReadyRuntimeIdsChange}
/>
) : (
<DefaultConfigStep
Expand All @@ -300,7 +229,7 @@ export function MachineOnboardingFlow({
complete: () => complete(selectedPubkey ?? undefined),
}}
direction="forward"
selectedRuntimeIds={selectedRuntimeIds}
readyRuntimeIds={readyRuntimeIds}
/>
)}
</div>
Expand Down
Loading
Loading