diff --git a/docs/decisions/2026-11-17-keep-agent-configuration-in-onboarding.md b/docs/decisions/2026-11-17-keep-agent-configuration-in-onboarding.md
new file mode 100644
index 0000000..f77c27c
--- /dev/null
+++ b/docs/decisions/2026-11-17-keep-agent-configuration-in-onboarding.md
@@ -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).
diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md
index 403513d..1e86454 100644
--- a/docs/decisions/INDEX.md
+++ b/docs/decisions/INDEX.md
@@ -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.
diff --git a/packages/admin-ui/src/workspace/WorkspaceApp.tsx b/packages/admin-ui/src/workspace/WorkspaceApp.tsx
index 53cccd9..11d4de3 100644
--- a/packages/admin-ui/src/workspace/WorkspaceApp.tsx
+++ b/packages/admin-ui/src/workspace/WorkspaceApp.tsx
@@ -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])])}
diff --git a/packages/admin-ui/src/workspace/bug-hunt.test.tsx b/packages/admin-ui/src/workspace/bug-hunt.test.tsx
index f81cefa..516243d 100644
--- a/packages/admin-ui/src/workspace/bug-hunt.test.tsx
+++ b/packages/admin-ui/src/workspace/bug-hunt.test.tsx
@@ -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'
@@ -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 {
diff --git a/packages/admin-ui/src/workspace/server/connection/ConnectionGuide.tsx b/packages/admin-ui/src/workspace/server/connection/ConnectionGuide.tsx
index b931ce3..e48376e 100644
--- a/packages/admin-ui/src/workspace/server/connection/ConnectionGuide.tsx
+++ b/packages/admin-ui/src/workspace/server/connection/ConnectionGuide.tsx
@@ -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)
@@ -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('')
@@ -122,7 +127,8 @@ export function ConnectionGuide({
agent={path === 'agent' ? agent : undefined}
name={name}
heading={heading}
- onClose={onClose}
+ onClose={dismiss}
+ showDownloads={!onboarding}
/>
{(error || modelError) && (
@@ -235,7 +241,7 @@ export function ConnectionGuide({
>
Connect another tool
-
+
Done
@@ -244,7 +250,10 @@ export function ConnectionGuide({
{(['agent', 'endpoint', 'review'].includes(step) || (step === 'choose' && onBack)) && (
(step === 'choose' ? onBack?.() : setStep(step === 'review' ? path : 'choose'))}
+ onClick={() => {
+ if (step === 'choose' || (onboarding && step === 'agent')) (onBack ?? onClose)()
+ else setStep(step === 'review' ? path : 'choose')
+ }}
>
Back
@@ -260,11 +269,13 @@ export function ConnectionGuide({
)}
)}
- setPickingModel(true)}
- />
+ {onSettings && (
+ setPickingModel(true)}
+ />
+ )}
{pickingModel && (
onClose: () => void
+ showDownloads?: boolean
}) {
const chosen = ['review', 'preparing', 'done'].includes(step)
const title =
@@ -46,7 +48,7 @@ export function ConnectionHeading({
{title}
-
+ {showDownloads && }
diff --git a/packages/admin-ui/src/workspace/server/connection/connection-guide-types.ts b/packages/admin-ui/src/workspace/server/connection/connection-guide-types.ts
index c663f96..6259755 100644
--- a/packages/admin-ui/src/workspace/server/connection/connection-guide-types.ts
+++ b/packages/admin-ui/src/workspace/server/connection/connection-guide-types.ts
@@ -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
diff --git a/packages/admin-ui/src/workspace/server/connection/connection-model-flow.test.tsx b/packages/admin-ui/src/workspace/server/connection/connection-model-flow.test.tsx
index 47bacb5..dc4d886 100644
--- a/packages/admin-ui/src/workspace/server/connection/connection-model-flow.test.tsx
+++ b/packages/admin-ui/src/workspace/server/connection/connection-model-flow.test.tsx
@@ -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'
@@ -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 () => {
@@ -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(
{
@@ -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' })
@@ -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())
diff --git a/packages/admin-ui/src/workspace/server/connection/useConnectionEscape.ts b/packages/admin-ui/src/workspace/server/connection/useConnectionEscape.ts
index 3c46f09..4a7d1bf 100644
--- a/packages/admin-ui/src/workspace/server/connection/useConnectionEscape.ts
+++ b/packages/admin-ui/src/workspace/server/connection/useConnectionEscape.ts
@@ -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
+) {
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])
}
diff --git a/packages/admin-ui/src/workspace/server/onboarding-connection.test.tsx b/packages/admin-ui/src/workspace/server/onboarding-connection.test.tsx
index 9412164..fad84f9 100644
--- a/packages/admin-ui/src/workspace/server/onboarding-connection.test.tsx
+++ b/packages/admin-ui/src/workspace/server/onboarding-connection.test.tsx
@@ -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
}),
@@ -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()
- 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' }))
diff --git a/packages/admin-ui/src/workspace/setup/Purpose.tsx b/packages/admin-ui/src/workspace/setup/Purpose.tsx
index 7325a2e..de287be 100644
--- a/packages/admin-ui/src/workspace/setup/Purpose.tsx
+++ b/packages/admin-ui/src/workspace/setup/Purpose.tsx
@@ -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
+ choose: (destination: 'endpoint' | 'agents', snapshot: WorkspaceSnapshot | null) => void | Promise
+ refresh: () => Promise
}) {
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)
}
}
diff --git a/packages/admin-ui/src/workspace/setup/SetupFooter.tsx b/packages/admin-ui/src/workspace/setup/SetupFooter.tsx
new file mode 100644
index 0000000..f178749
--- /dev/null
+++ b/packages/admin-ui/src/workspace/setup/SetupFooter.tsx
@@ -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 } | null
+ actionRef: (element: HTMLDivElement | null) => void
+ back: () => void
+ skip: () => Promise
+ next: () => void
+}) {
+ return (
+
+ )
+}
diff --git a/packages/admin-ui/src/workspace/setup/SetupWizard.tsx b/packages/admin-ui/src/workspace/setup/SetupWizard.tsx
index d27dbbb..4269838 100644
--- a/packages/admin-ui/src/workspace/setup/SetupWizard.tsx
+++ b/packages/admin-ui/src/workspace/setup/SetupWizard.tsx
@@ -20,6 +20,8 @@ import { Permissions } from './Permissions'
import { Destinations } from './Purpose'
import { OptionalMedia } from './OptionalMedia'
import { WaitingSetup } from './WaitingSetup'
+import { ConnectionGuide } from '../server/connection/ConnectionGuide'
+import { SetupFooter } from './SetupFooter'
import './onboarding.css'
const SETUP_STEP_LABELS: Record = {
@@ -41,13 +43,14 @@ export function SetupWizard({
onClose,
onOpenGoal,
onDestination,
+ onPrepared,
+ onConfigure,
}: {
workspace: Workspace
onClose: () => void
onOpenGoal: (id: string, agent?: string) => void
onPrepared?: (id: string) => void
onConfigure?: () => void
- onChat?: () => void
onDestination?: (destination: Destination) => void
}) {
const [step, setStep] = useState(w.snapshot?.setups.length ? 'permissions' : 'model')
@@ -60,7 +63,7 @@ export function SetupWizard({
const [engineDialog, setEngineDialog] = useState('')
const [choosingEngine, setChoosingEngine] = useState(false)
const [engineRevision, setEngineRevision] = useState(0)
- const choosing = useRef(false)
+ const [agentSetup, setAgentSetup] = useState(false)
const [category, setCategory] = useState('image')
const [modelActionContainer, setModelActionContainer] = useState(null)
const heading = useRef(null)
@@ -68,12 +71,12 @@ export function SetupWizard({
useEffect(() => {
if (content.current) content.current.scrollTop = 0
heading.current?.focus({ preventScroll: true })
- }, [step, waiting])
+ }, [step, waiting, agentSetup])
const finishing = w.pending.includes('setup.manual')
const checking = finishing || w.pending.includes('cloud.connect')
const dialog = useDialog(
() => {
- if (!checking) {
+ if (!checking && !agentSetup) {
if (waiting) {
setWaiting(null)
return
@@ -106,6 +109,11 @@ export function SetupWizard({
if (onDestination) onDestination(destination)
else onOpenGoal('api')
}
+ const continueTo = (destination: Destination) => {
+ if (destination === 'endpoint') return finish(destination)
+ setWaiting(null)
+ setAgentSetup(true)
+ }
return (
-
- {waiting
- ? waitingPending
- ? 'Getting your model ready'
- : 'Your model is downloaded'
- : FIRST_RUN_TITLES[step]}
-
+ {!agentSetup && (
+
+ {waiting
+ ? waitingPending
+ ? 'Getting your model ready'
+ : 'Your model is downloaded'
+ : FIRST_RUN_TITLES[step]}
+
+ )}
{waiting && }
{!waiting && step === 'model' && (
>
)}
- {!waiting && step === 'connect' && w.error && (
+ {!waiting && !agentSetup && step === 'connect' && w.error && (
setStep('model')}>Choose another model
)}
- {!waiting && step === 'connect' && (
- {
- if (choosing.current) return
- choosing.current = true
- try {
- // Decide on the server's word, not the last poll (none right after the admin opens); when
- // the server cannot say, wait: the waiting screen lets the person go on anyway.
- const snapshot = await w.refresh()
- if (!snapshot || setupDownloadsPending(snapshot))
- setWaiting({ destination, snapshot, previous: w.snapshot })
- else await finish(destination)
- } finally {
- choosing.current = false
- }
- }}
+ {agentSetup ? (
+ setAgentSetup(false)}
+ onDone={onClose}
/>
+ ) : (
+ !waiting &&
+ step === 'connect' && (
+ w.refresh()}
+ choose={(destination, snapshot) => {
+ if (setupDownloadsPending(snapshot))
+ setWaiting({ destination, snapshot, previous: w.snapshot })
+ else return continueTo(destination)
+ }}
+ />
+ )
)}
-
+ waiting={
+ waiting && {
+ label: waitingPending ? 'Open control panel' : 'Continue',
+ continue: () => (waitingPending ? finish : continueTo)(waiting.destination),
+ }
+ }
+ skip={step === 'connect' ? () => openDashboard(false) : skip}
+ next={next}
+ />
+ )}
{review && step === 'model' && (
{
snapshotFixture({ setup: null })
)
await userEvent.dblClick(await screen.findByRole('button', { name: /Configure an endpoint/ }))
- answer(snapshotFixture({ setup: null, setups: [] }))
+ await act(async () => answer(snapshotFixture({ setup: null, setups: [] })))
await vi.waitFor(() => expect(manual(workspace)).toHaveLength(1))
await new Promise((resolve) => setTimeout(resolve, 50))
expect(manual(workspace)).toHaveLength(1)
diff --git a/packages/admin-ui/src/workspace/setup/waiting-setup.test.tsx b/packages/admin-ui/src/workspace/setup/waiting-setup.test.tsx
index 8f4a335..0bd7a74 100644
--- a/packages/admin-ui/src/workspace/setup/waiting-setup.test.tsx
+++ b/packages/admin-ui/src/workspace/setup/waiting-setup.test.tsx
@@ -72,6 +72,25 @@ it('keeps paused download status truthful and exposes existing controls in a dis
const downloading = [{ setup_id: 's1', stage: 'downloading_model', plan: { model_id: 'Qwen' } }]
+it('continues to agent selection when the download finishes while waiting', async () => {
+ const { workspace, execute } = workspaceFixture({}, { setup: null, setups: downloading })
+ const onDestination = vi.fn()
+ const wizard = () => (
+
+ )
+ const view = render(wizard())
+ for (let i = 0; i < 3; i++)
+ await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
+ await userEvent.click(screen.getByRole('button', { name: /Connect an agent/ }))
+ expect(screen.getByRole('heading', { name: 'Getting your model ready' })).toBeInTheDocument()
+ workspace.snapshot = { ...workspace.snapshot!, setups: [] }
+ view.rerender(wizard())
+ await userEvent.click(screen.getByRole('button', { name: 'Continue', exact: true }))
+ expect(screen.getByRole('heading', { name: 'Choose your agent' })).toBeInTheDocument()
+ expect(execute).not.toHaveBeenCalledWith('setup.manual')
+ expect(onDestination).not.toHaveBeenCalled()
+})
+
it('goes directly from the connection step to the dashboard while a model downloads', async () => {
const { workspace, execute } = workspaceFixture({}, { setup: null, setups: downloading })
const onClose = vi.fn()
diff --git a/src/tui/workspace/server/connection-guide-actions.ts b/src/tui/workspace/server/connection-guide-actions.ts
index 1508156..854d317 100644
--- a/src/tui/workspace/server/connection-guide-actions.ts
+++ b/src/tui/workspace/server/connection-guide-actions.ts
@@ -45,7 +45,8 @@ export async function connectionGuideAction(id: string, ctx: ActionContext): Pro
ctx.update((v) => ({ ...v, serverView: 'overview', focus: 'api-toggle' }))
return true
}
- if (id === 'guide-open' || id.startsWith('guide-agent:')) {
+ const openingAgentSetup = id === 'guide-open:agent'
+ if (id === 'guide-open' || openingAgentSetup || id.startsWith('guide-agent:')) {
if (s.message === READING_CONNECTION_OPTIONS) return true
const openingHere = () => {
const current = ctx.get()
@@ -88,10 +89,11 @@ export async function connectionGuideAction(id: string, ctx: ActionContext): Pro
connectionEngines,
connectionReturn: s.firstRun ? undefined : (s.connectionReturn ?? workspaceLocation(s)),
overlay: 'connection-guide',
- focus: agent ? 'guide-configure' : 'guide-path:agent',
+ ...(openingAgentSetup ? { finalSetup: null } : {}),
+ focus: agent ? 'guide-configure' : openingAgentSetup ? 'guide-select:claude' : 'guide-path:agent',
message: '',
connection: {
- step: agent ? 'review' : 'choose',
+ step: agent ? 'review' : openingAgentSetup ? 'agent' : 'choose',
path: 'agent',
agent: agent || 'claude',
model,
@@ -137,6 +139,10 @@ export async function connectionGuideAction(id: string, ctx: ActionContext): Pro
const error = guidePortError(d.port)
patch(error ? { error } : { step: 'review', error: '' })
} else if (id === 'guide-back') {
+ if (s.firstRun === 'connect' && d.step === 'agent') {
+ ctx.update((v) => ({ ...v, connection: null, overlay: null, focus: 'first-connect:agent', hover: '' }))
+ return true
+ }
patch({ step: d.step === 'review' ? d.path : 'choose', error: '' })
ctx.update((v) => ({
...v,
diff --git a/src/tui/workspace/setup/connection-choice.ts b/src/tui/workspace/setup/connection-choice.ts
index c353e79..fbfbdb8 100644
--- a/src/tui/workspace/setup/connection-choice.ts
+++ b/src/tui/workspace/setup/connection-choice.ts
@@ -4,8 +4,9 @@ import { finalSetupState } from './waiting-setup.js'
import type { ActionContext } from '../actions.js'
import type { Canvas } from '../draw/canvas.js'
import { drawConnectionChoices } from '../server/connection-art.js'
+import { connectionGuideAction } from '../server/connection-guide-actions.js'
-/** Desktop onboarding hands off to the owning page; its connection wizard stays optional. */
+/** Keep agent setup in onboarding until the user finishes the guide. */
export async function firstConnectionAction(id: string, ctx: ActionContext): Promise {
const leavingWait = id === 'wait-continue'
if (leavingWait && ctx.get().finalSetup) {
@@ -31,6 +32,8 @@ export async function firstConnectionAction(id: string, ctx: ActionContext): Pro
}))
return true
}
+ if (id === 'first-connect:agent' && (!leavingWait || !firstRunDownloadsPending(ctx.get())))
+ return connectionGuideAction('guide-open:agent', ctx)
await finishFirstRun(ctx)
const endpoint = id === 'first-connect:endpoint'
ctx.update((s) => ({
diff --git a/src/tui/workspace/setup/waiting-setup.test.ts b/src/tui/workspace/setup/waiting-setup.test.ts
index 55945e8..f20f42a 100644
--- a/src/tui/workspace/setup/waiting-setup.test.ts
+++ b/src/tui/workspace/setup/waiting-setup.test.ts
@@ -13,6 +13,7 @@ function fixture() {
firstRun: 'connect' as const,
model: 'qwen',
workspace: {
+ api: { port: 1337 },
setups: [
{ id: 'download', stage: 'downloading', plan: { model_id: 'qwen', total_download_bytes: 100 } },
],
@@ -28,7 +29,11 @@ function fixture() {
send: vi.fn(),
copy: vi.fn(),
cancel: vi.fn(),
- controller: { runtime: { execute } } as unknown as WorkspaceController,
+ controller: {
+ installed: async () => [{ id: 'qwen', name: 'Qwen', provider: 'llamacpp-upstream' }],
+ setup: { installed: async () => ['llamacpp-upstream'] },
+ runtime: { execute },
+ } as unknown as WorkspaceController,
}
return { ctx, execute, action: (id: string) => activate(id, ctx) }
}
@@ -91,6 +96,31 @@ const shown = (state: ReturnType, width = 120, height =
.cells.map((row) => row.map((cell) => cell.char).join(''))
.join('\n')
+it.each([false, true])('opens agent selection inside onboarding after waiting=%s', async (wait) => {
+ const t = fixture()
+ if (wait) await t.action('first-connect:agent')
+ t.ctx.update((s) => ({
+ ...s,
+ workspace: { ...s.workspace!, setups: [{ id: 'download', stage: 'ready', plan: { model_id: 'qwen' } }] },
+ }))
+ t.ctx.controller.runtime.snapshot = vi.fn(async () => t.ctx.get().workspace!)
+ await t.action(wait ? 'wait-continue' : 'first-connect:agent')
+ expect(t.ctx.get()).toMatchObject({
+ firstRun: 'connect',
+ finalSetup: null,
+ page: 'welcome',
+ overlay: 'connection-guide',
+ connection: { step: 'agent', model: 'qwen' },
+ })
+ expect(shown(t.ctx.get())).toContain('Choose your agent')
+ await t.action('guide-select:codex')
+ expect(t.ctx.get().connection).toMatchObject({ step: 'review', agent: 'codex', model: 'qwen' })
+ await t.action('guide-back')
+ await t.action('guide-back')
+ expect(t.ctx.get()).toMatchObject({ firstRun: 'connect', overlay: null, focus: 'first-connect:agent' })
+ expect(t.execute).not.toHaveBeenCalled()
+})
+
it('registers the address with the server, validates it, and Escape returns to the explicit destination choice', async () => {
const t = fixture()
await t.action('first-connect:endpoint')