Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
date: 2026-11-17
title: "Keep agent configuration in onboarding"
---

# 2026-11-17 — Keep agent configuration in onboarding

- **Context:** Choosing to connect an agent completed setup and opened Overview, where the user had to find and select the agent again.
- **Decision:** Open the existing connection guide at the agent picker in both clients. Keep the final onboarding step visible behind the guide and return to it on Back. Run the existing configuration flow when the user chooses to configure the selected agent.
- **Consequences:** The guide retains the selected model and provider. When a download is pending, the existing waiting screen still offers an explicit exit. Continuing after the model is ready opens the agent picker directly.
- **Alternatives:** Automatically opening the dashboard's agent guide would finish onboarding before the user chose an agent and make it harder to return to the connection choices.
- **Owner:** team
- **Links:** [Web onboarding](../../packages/admin-ui/src/workspace/setup/SetupWizard.tsx), [terminal connection step](../../src/tui/workspace/setup/connection-choice.ts).
2 changes: 2 additions & 0 deletions docs/decisions/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ add a new one that says which record it supersedes.

## Records

- **2026-11-17** — [Keep agent configuration in onboarding](2026-11-17-keep-agent-configuration-in-onboarding.md) — open the shared agent picker directly from the connection step.

- **2026-11-17** — [Configure agents through core](2026-11-17-configure-agents-through-core.md) — use the shared registry for host configuration and launches.

- **2026-11-17** — [Show progress when opening terminal agent setup](2026-11-17-show-terminal-agent-setup-progress.md) — make the full agent card clickable and show the options check.
Expand Down
6 changes: 0 additions & 6 deletions packages/admin-ui/src/workspace/WorkspaceApp.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -270,12 +270,6 @@ function WorkspaceContent() {
setPage('server')
setServerSection(destination === 'endpoint' ? 'configuration' : 'overview')
}}
onChat={() => {
setWizard(false)
setSetupDismissed(true)
setPage('playground')
setTask('chat')
}}
onConfigure={() => setWizard(true)}
workspace={workspace}
onPrepared={(id) => setPrepared((items) => [...new Set([...items, id])])}
Expand Down
8 changes: 2 additions & 6 deletions packages/admin-ui/src/workspace/bug-hunt.test.tsx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/** Cases from the October 2026 bug hunt over the web admin: each one failed before its fix. */
import { act, fireEvent, render, renderHook, screen, waitFor, within } from '@testing-library/react'
import { act, fireEvent, render, renderHook, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { afterEach, expect, it, vi } from 'vitest'
import { WORKSPACE_OPERATIONS } from '@contract'
Expand Down Expand Up @@ -146,11 +146,7 @@ it('keeps the server on the network the person chose when an agent connection is
await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(screen.getByRole('button', { name: /Connect an agent/ }))
await userEvent.click(
within(screen.getByRole('heading', { name: 'Codex CLI' }).closest('article')!).getByRole('button', {
name: 'Configure',
})
)
await userEvent.click(screen.getByRole('button', { name: 'Codex CLI', exact: true }))
await userEvent.click(await screen.findByRole('button', { name: 'Configure & start' }))
await waitFor(() => expect(execute).toHaveBeenCalledWith('api.start', expect.anything()))
const config = execute.mock.calls.find(([name]) => name === 'config.update')?.[1] as {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,18 @@ export function ConnectionGuide({
initialAgent,
preferredModel,
preferredProvider,
onboarding = false,
onClose,
onDone = onClose,
onBack,
onSettings,
onPrepared,
onConfigure,
}: ConnectionGuideProps) {
const { step, setStep, heading } = useConnectionStep(initialAgent ? 'review' : 'choose')
useConnectionEscape(onClose, step === 'preparing')
const { step, setStep, heading } = useConnectionStep(
initialAgent ? 'review' : onboarding ? 'agent' : 'choose'
)
const dismiss = step === 'done' ? onDone : onClose
const [path, setPath] = useState<'agent' | 'endpoint'>('agent')
const [agent, setAgent] = useState(initialAgent ?? 'claude')
const [more, setMore] = useState(false)
Expand All @@ -51,6 +55,7 @@ export function ConnectionGuide({
setProvider,
} = useConnectionModel(w, preferredModel, preferredProvider)
const retryFocus = useConnectionRetryFocus(checking, modelError, retryModels)
useConnectionEscape(dismiss, step === 'preparing', onboarding ? retryFocus.ref : undefined)
const [port, setPort] = useState(String(w.snapshot?.api.port || DEFAULT_API_PORT))
const [error, setError] = useState('')
const [status, setStatus] = useState('')
Expand Down Expand Up @@ -122,7 +127,8 @@ export function ConnectionGuide({
agent={path === 'agent' ? agent : undefined}
name={name}
heading={heading}
onClose={onClose}
onClose={dismiss}
showDownloads={!onboarding}
/>
{(error || modelError) && (
<p role="alert" className="ew-error">
Expand Down Expand Up @@ -235,7 +241,7 @@ export function ConnectionGuide({
>
Connect another tool
</Action>
<Action primary onClick={onClose}>
<Action primary onClick={onDone}>
Done
</Action>
</div>
Expand All @@ -244,7 +250,10 @@ export function ConnectionGuide({
{(['agent', 'endpoint', 'review'].includes(step) || (step === 'choose' && onBack)) && (
<div className="wizard-bottom">
<Action
onClick={() => (step === 'choose' ? onBack?.() : setStep(step === 'review' ? path : 'choose'))}
onClick={() => {
if (step === 'choose' || (onboarding && step === 'agent')) (onBack ?? onClose)()
else setStep(step === 'review' ? path : 'choose')
}}
>
Back
</Action>
Expand All @@ -260,11 +269,13 @@ export function ConnectionGuide({
)}
</div>
)}
<ConnectionHelp
disabled={step === 'preparing'}
onSettings={onSettings}
onModels={() => setPickingModel(true)}
/>
{onSettings && (
<ConnectionHelp
disabled={step === 'preparing'}
onSettings={onSettings}
onModels={() => setPickingModel(true)}
/>
)}
{pickingModel && (
<ConnectionModelPicker
workspace={w}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,15 @@ export function ConnectionHeading({
name,
heading,
onClose,
showDownloads = true,
}: {
workspace: Workspace
step: string
agent?: string
name: string
heading: Ref<HTMLHeadingElement>
onClose: () => void
showDownloads?: boolean
}) {
const chosen = ['review', 'preparing', 'done'].includes(step)
const title =
Expand All @@ -46,7 +48,7 @@ export function ConnectionHeading({
{title}
</h2>
</div>
<FloatingDownloads workspace={workspace} />
{showDownloads && <FloatingDownloads workspace={workspace} />}
<Action ariaLabel="Close setup guide" disabled={step === 'preparing'} onClick={onClose}>
<X size={18} />
</Action>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,11 @@ export interface ConnectionGuideProps {
preferredModel?: string
preferredProvider?: string
initialAgent?: string
onboarding?: boolean
onClose: () => void
onDone?: () => void
onBack?: () => void
onSettings: () => void
onSettings?: () => void
onPrepared?: (agent: string) => void
/** Keep the local result open while another client observes shared setup completion. */
onConfigure?: () => void
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { useState } from 'react'
import { act, render, screen, waitFor, within } from '@testing-library/react'
import { act, render, screen, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { expect, it, vi } from 'vitest'
import { workspaceFixture } from '@/test/workspace-fixture'
Expand Down Expand Up @@ -41,11 +41,7 @@ async function openOnboardingReview(name = 'Old model') {
await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(screen.getByRole('button', { name: /Connect an agent/ }))
await userEvent.click(
within(screen.getByRole('heading', { name: 'Codex CLI' }).closest('article')!).getByRole('button', {
name: 'Configure',
})
)
await userEvent.click(screen.getByRole('button', { name: 'Codex CLI', exact: true }))
expect(screen.getByRole('heading', { name: 'Connect Codex CLI' })).toBeInTheDocument()
}
it('changes models inside onboarding without losing the selected agent or visiting a previous stage', async () => {
Expand Down Expand Up @@ -137,7 +133,7 @@ it('explicit picker Back preserves endpoint settings and the current model', asy
expect(screen.getByText('http://127.0.0.1:1777/v1')).toBeInTheDocument()
})

it('preserves the selected installed model through onboarding handoff and guide reopening', async () => {
it('preserves the selected installed model when reopening the guide inside onboarding', async () => {
let savedModel = ''
const { workspace, execute } = workspaceFixture(
{
Expand All @@ -156,11 +152,8 @@ it('preserves the selected installed model through onboarding handoff and guide
await waitFor(() => expect(screen.getByLabelText('Model')).toHaveValue('new-model'))
expect(execute).toHaveBeenCalledWith('config.update', { values: { 'tui.model': 'new-model' } })
await userEvent.click(screen.getByRole('button', { name: 'Close setup guide' }))
await userEvent.click(
within(screen.getByRole('heading', { name: 'Codex CLI' }).closest('article')!).getByRole('button', {
name: 'Configure',
})
)
await userEvent.click(screen.getByRole('button', { name: /Connect an agent/ }))
await userEvent.click(screen.getByRole('button', { name: 'Codex CLI', exact: true }))
await waitFor(() => expect(screen.getByLabelText('Model')).toHaveValue('new-model'))
await userEvent.click(screen.getByRole('button', { name: 'Configure & start' }))
await screen.findByRole('heading', { name: 'Codex CLI connection is ready' })
Expand Down Expand Up @@ -205,11 +198,7 @@ it('saves the actual download model before handoff instead of restoring a previo
await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(screen.getByRole('button', { name: /Connect an agent/ }))
await userEvent.click(
within(screen.getByRole('heading', { name: 'Codex CLI' }).closest('article')!).getByRole('button', {
name: 'Configure',
})
)
await userEvent.click(screen.getByRole('button', { name: 'Codex CLI', exact: true }))
await waitFor(() => expect(screen.getByLabelText('Model')).toHaveValue(downloadedId))
expect(screen.getByRole('button', { name: 'Configure & start' })).toBeDisabled()
expect(execute).not.toHaveBeenCalledWith('models.load', expect.anything())
Expand Down
Original file line number Diff line number Diff line change
@@ -1,16 +1,24 @@
import { useEffect } from 'react'
import { useEffect, type RefObject } from 'react'

/** Escape dismisses an existing-server guide; inner menus and dialogs consume it first. */
export function useConnectionEscape(onClose: () => void, preparing: boolean) {
export function useConnectionEscape(
onClose: () => void,
preparing: boolean,
scope?: RefObject<HTMLElement | null>
) {
useEffect(() => {
const close = (event: KeyboardEvent) => {
const root = scope?.current
const target: HTMLElement | Document = root ?? document
const close = (event: Event) => {
if (!(event instanceof KeyboardEvent)) return
if (event.key !== 'Escape' || event.defaultPrevented || preparing) return
if (document.querySelector('[aria-modal="true"]')) return
const dialogs = document.querySelectorAll('[aria-modal="true"]')
if (dialogs.length && dialogs[dialogs.length - 1] !== root?.closest('[aria-modal="true"]')) return
event.preventDefault()
event.stopImmediatePropagation()
onClose()
}
document.addEventListener('keydown', close)
return () => document.removeEventListener('keydown', close)
}, [onClose, preparing])
target.addEventListener('keydown', close)
return () => target.removeEventListener('keydown', close)
}, [onClose, preparing, scope])
}
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ it('counts a connection prepared during first-run after returning to Overview',
'models.installed': [model],
'models.catalog': [],
'keys.list': [{ id: 'key' }],
'connection.info': { endpoint: 'http://127.0.0.1:1337/v1' },
'connection.profile': () =>
'connection.info': { endpoint: 'http://127.0.0.1:1337/v1', configurable_agents: ['codex'] },
'connection.configure': () =>
new Promise((resolve) => {
finishProfile = resolve
}),
Expand All @@ -45,21 +45,24 @@ it('counts a connection prepared during first-run after returning to Overview',
await userEvent.click(setup.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(setup.getByRole('button', { name: 'Continue', exact: true }))
await userEvent.click(setup.getByRole('button', { name: /Connect an agent/ }))
expect(screen.queryByRole('dialog', { name: 'Set up Atomic Server' })).not.toBeInTheDocument()
await userEvent.click(screen.getAllByRole('button', { name: 'Codex CLI', exact: true })[0])
expect(setup.getByRole('heading', { name: 'Choose your agent' })).toBeInTheDocument()
await userEvent.keyboard('{Escape}')
await userEvent.click(setup.getByRole('button', { name: /Connect an agent/ }))
await userEvent.click(setup.getByRole('button', { name: 'Codex CLI', exact: true }))
await waitFor(() => expect(screen.getByRole('button', { name: 'Configure & start' })).toBeEnabled())
await userEvent.click(screen.getByRole('button', { name: 'Configure & start' }))
await waitFor(() => expect(finishProfile).toBeDefined())
view.rerender(<WorkspaceApp />)
expect(screen.queryByRole('dialog', { name: 'Set up Atomic Server' })).not.toBeInTheDocument()
expect(screen.getByRole('heading', { name: 'Preparing your server' })).toBeInTheDocument()
await act(async () => finishProfile({ launch_command: 'atc connect codex --model local-model' }))
expect(setup.getByRole('heading', { name: 'Preparing your server' })).toBeInTheDocument()
await act(async () =>
finishProfile({ configured: true, launch_command: 'atc connect codex --model local-model' })
)
expect(await screen.findByText('atc connect codex --model local-model')).toBeInTheDocument()
await userEvent.click(await screen.findByRole('button', { name: 'Done', exact: true }))
expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
expect(screen.getByRole('button', { name: /Connections.*1 prepared/ })).toBeInTheDocument()
expect(screen.getByRole('button', { name: 'Connection prepared' })).toBeInTheDocument()
expect(execute.mock.calls.filter(([name]) => name === 'setup.manual')).toHaveLength(1)
expect(execute.mock.calls.filter(([name]) => name === 'setup.manual')).toHaveLength(0)
Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true })
fireEvent(window, new Event('resize'))
await userEvent.click(screen.getByRole('button', { name: 'Toggle sidebar' }))
Expand Down
13 changes: 10 additions & 3 deletions packages/admin-ui/src/workspace/setup/Purpose.tsx
Original file line number Diff line number Diff line change
@@ -1,24 +1,31 @@
// Lifted from Atomic-Chat/web-app/src/preview/onboarding/Onboarding.tsx @ 807b4d9; adapted: shared server workspace destinations.
import { useState } from 'react'
import { useRef, useState } from 'react'
import type { WorkspaceSnapshot } from '@contract'
import { describeError } from '@/services/admin-api'
import { ChevronRight, Network, Terminal } from 'lucide-react'
import { DirectoryRow } from '../DirectoryRow'

export function Destinations({
choose,
refresh,
}: {
choose: (destination: 'endpoint' | 'agents') => void | Promise<void>
choose: (destination: 'endpoint' | 'agents', snapshot: WorkspaceSnapshot | null) => void | Promise<void>
refresh: () => Promise<WorkspaceSnapshot | null>
}) {
const [busy, setBusy] = useState(false)
const choosing = useRef(false)
const [error, setError] = useState('')
const run = async (destination: 'endpoint' | 'agents') => {
if (choosing.current) return
choosing.current = true
setBusy(true)
setError('')
try {
await choose(destination)
await choose(destination, await refresh())
} catch (e) {
setError(describeError(e))
} finally {
choosing.current = false
setBusy(false)
}
}
Expand Down
48 changes: 48 additions & 0 deletions packages/admin-ui/src/workspace/setup/SetupFooter.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import type { FirstRunStep } from '@contract'
import { Action } from '../Controls'

export function SetupFooter({
step,
disabled,
waiting,
actionRef,
back,
skip,
next,
}: {
step: FirstRunStep
disabled: boolean
waiting: { label: string; continue: () => void | Promise<unknown> } | null
actionRef: (element: HTMLDivElement | null) => void
back: () => void
skip: () => Promise<void>
next: () => void
}) {
return (
<footer className="first-run-footer">
<Action disabled={disabled} onClick={back}>
Back
</Action>
<div className="first-run-actions" ref={actionRef}>
{waiting ? (
<Action primary disabled={disabled} onClick={waiting.continue}>
{waiting.label}
</Action>
) : (
<>
<span className="first-run-skip">
<Action disabled={disabled} onClick={skip}>
{step === 'connect' ? 'Go to dashboard' : 'Skip setup'}
</Action>
</span>
{['permissions', 'cloud', 'media'].includes(step) && (
<Action primary disabled={disabled} onClick={next}>
Continue
</Action>
)}
</>
)}
</div>
</footer>
)
}
Loading
Loading