Skip to content
Closed
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
11 changes: 11 additions & 0 deletions docs/decisions/2026-11-17-show-terminal-agent-setup-progress.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
date: 2026-11-17
title: "Show progress when opening terminal agent setup"
---

# Show progress when opening terminal agent setup

- **Context:** The server overview drew a full agent card, but only its Configure label accepted a click. After that click, model and engine reads could leave the terminal looking idle.
- **Decision:** Give the card one full-surface target and show a status while the connection guide reads local model and engine choices, using the existing setup deadline.
- **Consequences:** The title and body open the same review as Configure. Loading a model and preparing a connection still requires the review action.
- **Owner:** team.
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** — [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.

- **2026-11-17** — [Pair terminal connection engines with models](2026-11-17-pair-terminal-connection-engines-with-models.md) — filter the connection guide by active engines and compatible downloads.

- **2026-11-17** — [Open the dashboard from terminal onboarding](2026-11-17-open-dashboard-from-terminal-onboarding.md) — save completion and let downloads continue without loading the selected model.
Expand Down
34 changes: 32 additions & 2 deletions src/tui/workspace/server/connection-guide-actions.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import type { ConnectionDraft } from '../../../contract/index.js'
import { CONNECTION_AGENTS, DEFAULT_API_PORT, PROFILE_AGENTS } from '../../../contract/index.js'
import { setupWait } from '../../../terminal-setup/index.js'
import type { ActionContext } from '../actions.js'
import { workspaceLocation } from '../navigation/navigation-return.js'
import { record } from '../library/library-model.js'
Expand All @@ -17,6 +18,8 @@ const rows = (value: unknown) =>
: Array.isArray(record(value)['rows'])
? (record(value)['rows'] as unknown[]).map(record)
: []
const READING_CONNECTION_OPTIONS = 'Checking installed models and engines…'

export async function connectionGuideAction(id: string, ctx: ActionContext): Promise<boolean> {
if (connectionPickerAction(id, ctx)) return true
const s = ctx.get(),
Expand All @@ -43,8 +46,34 @@ export async function connectionGuideAction(id: string, ctx: ActionContext): Pro
return true
}
if (id === 'guide-open' || id.startsWith('guide-agent:')) {
const [installed, connectionEngines] = await Promise.all([c.installed(), readConnectionEngines(c)])
if (s.firstRun && ctx.get().firstRun !== s.firstRun) return true
if (s.message === READING_CONNECTION_OPTIONS) return true
const openingHere = () => {
const current = ctx.get()
return (
current.message === READING_CONNECTION_OPTIONS &&
current.page === s.page &&
current.overlay === s.overlay &&
current.firstRun === s.firstRun
)
}
ctx.update((v) => ({ ...v, message: READING_CONNECTION_OPTIONS }))
const options = await setupWait(
Promise.all([c.installed(), readConnectionEngines(c)]),
new AbortController().signal
).catch((error: unknown) => {
if (openingHere())
ctx.update((v) => ({
...v,
message: `Could not open connection setup. ${error instanceof Error ? error.message : String(error)}`,
}))
return null
})
if (!openingHere()) {
ctx.update((v) => (v.message === READING_CONNECTION_OPTIONS ? { ...v, message: '' } : v))
return true
}
if (!options) return true
const [installed, connectionEngines] = options
const download = connectionDownloadTarget(connectionDownload(s.workspace?.setups ?? []))
const preferred =
s.setup?.selections[0]?.plan.model_id ?? s.setup?.path?.job?.model ?? (s.model || download.model)
Expand All @@ -60,6 +89,7 @@ export async function connectionGuideAction(id: string, ctx: ActionContext): Pro
connectionReturn: s.firstRun ? undefined : (s.connectionReturn ?? workspaceLocation(s)),
overlay: 'connection-guide',
focus: agent ? 'guide-configure' : 'guide-path:agent',
message: '',
connection: {
step: agent ? 'review' : 'choose',
path: 'agent',
Expand Down
28 changes: 28 additions & 0 deletions src/tui/workspace/server/connection-guide.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import { workspaceFrame } from '../frame.js'
import type { WorkspaceController } from '../controller.js'
import { FIRST_RUN_STEPS } from '../../../contract/index.js'
import { hit } from '../draw/canvas.js'
import { workspaceInput } from '../input.js'
function fixture(fail = false) {
let state = { ...createWorkspace('server'), setupComplete: true }
const execute = vi.fn(async (name: string) => {
Expand Down Expand Up @@ -52,6 +53,33 @@ it('opens an agent sidebar item at review and verifies before preparing its conn
await activate('guide-copy', ctx)
expect(ctx.copy).toHaveBeenCalledWith('atc connect codex --model local-model')
})
it('opens Hermes from the card title and shows progress while checking installed models', async () => {
const { ctx, execute } = fixture()
type Installed = Awaited<ReturnType<WorkspaceController['installed']>>
let complete!: (models: Installed) => void
ctx.controller.installed = vi.fn(
() =>
new Promise<Installed>((resolve) => {
complete = resolve
})
)
ctx.update((s) => ({ ...s, serverQuery: 'Hermes Agent' }))
const frame = workspaceFrame(ctx.get(), 120, 36, 0)
const card = frame.targets.find((target) => target.id === 'server-agent:0')!
const { action } = workspaceInput(`\x1b[<0;${card.x + 8};${card.y + 2}M`, {} as never, ctx.get(), frame)
expect(action).toBe('server-agent:0')
const opening = activate(action!, ctx)
await vi.waitFor(() => expect(ctx.get().message).toBe('Checking installed models and engines…'))
expect(ctx.get().overlay).toBeNull()
complete([{ id: 'local-model', name: 'Local model', provider: 'llamacpp-upstream' }])
await opening
expect(ctx.get()).toMatchObject({
message: '',
overlay: 'connection-guide',
connection: { step: 'review', agent: 'hermes', model: 'local-model' },
})
expect(execute).not.toHaveBeenCalled()
})
it('returns failed inference to review without a success state or agent command', async () => {
const { ctx, execute } = fixture(true)
await activate('guide-agent:codex', ctx)
Expand Down
13 changes: 12 additions & 1 deletion src/tui/workspace/server/server-overview.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,18 @@ export function drawServerOverview(
COLORS.muted,
cardWidth - 4
)
button(c, id, cx + 2, cy + 3, 'Configure >', `Configure ${agent.label}`, focus, false, true)
const active = focus === id
text(
c,
cx + 2,
cy + 3,
active ? '>Configure > ' : ' Configure > ',
active ? COLORS.ground : COLORS.text,
cardWidth - 4,
active ? COLORS.accent : COLORS.surface,
true
)
c.targets.push({ id, x: cx, y: cy, width: cardWidth, height: 5, hint: `Configure ${agent.label}` })
})
scrollTrack(c, x + width - 1, y, rows * 5, offset, capacity, agents.length)
if (!agents.length) text(c, x, y + 1, 'No matching agents.', COLORS.muted, width)
Expand Down
Loading