The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import { act } from 'react'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import * as notifications from '@/store/notifications'
import { markOnboardingDecided } from '@/store/onboarding-presence'
import { makeOAuthProvider } from '@/test/oauth-provider'
import type { AppHandoffStatus, OAuthProvider } from '@/types/hermes'
import {
$desktopOnboarding,
completeDesktopOnboarding,
confirmOnboardingModel,
DEFAULT_ONBOARDING_REASON,
type DesktopOnboardingState,
type OnboardingContext,
refreshOnboarding,
requestDesktopOnboarding,
resetBootRaceWindowForTests,
saveOnboardingLocalEndpoint,
setOnboardingModel,
submitOnboardingCode
} from './onboarding'
// Onboarding's due check answered "not due": first-run surfaces are free to show.
markOnboardingDecided()
const NOT_CONNECTED =
'Hermes is not connected to any AI provider yet. Run `hermes model` to pick one, or `hermes auth add <provider>`.'
function baseState(overrides: Partial<DesktopOnboardingState> = {}): DesktopOnboardingState {
return {
configured: false,
flow: { status: 'idle' },
mode: 'oauth',
providers: null,
reason: null,
requested: false,
firstRunSkipped: false,
manual: false,
localEndpoint: false,
freeTierReady: false,
...overrides
}
}
function installApiMock(api: (request: { path: string }) => Promise<unknown>) {
Object.defineProperty(window, 'hermesDesktop', {
configurable: true,
value: { api }
})
}
function emptyOpenRouterGateway(): OnboardingContext['requestGateway'] {
return async method => {
if (method === 'setup.status') {
return { provider_configured: true } as never
}
if (method === 'setup.runtime_check') {
return { error: 'No usable credentials found for openrouter.', ok: false, provider: 'openrouter' } as never
}
throw new Error(`unexpected gateway method: ${method}`)
}
}
function keylessCustomGateway(): OnboardingContext['requestGateway'] {
return async method => {
if (method === 'setup.status') {
return { provider_configured: true } as never
}
if (method === 'setup.runtime_check') {
return { ok: true, provider: 'custom' } as never
}
throw new Error(`unexpected gateway method: ${method}`)
}
}
function onboardingContext(requestGateway: OnboardingContext['requestGateway']): OnboardingContext {
return { requestGateway }
}
function fallbackTimeoutGateway(): OnboardingContext['requestGateway'] {
return async method => {
if (method === 'setup.status' || method === 'setup.runtime_check') {
throw new Error(`request timed out: ${method}`)
}
throw new Error(`unexpected gateway method: ${method}`)
}
}
describe('refreshOnboarding', () => {
it('keeps onboarding work in its initiating lifetime and profile', async () => {
const { startManualOnboarding, startProviderOAuth, saveOnboardingApiKey, closeManualOnboarding } =
await import('./onboarding')
const requests: { path: string; profile?: string }[] = []
let release!: () => void
let delayKey = true
installApiMock(async request => {
requests.push(request)
if (request.path === '/api/providers/oauth') {
return { providers: [] }
}
if (request.path.endsWith('/start')) {
return {
flow: 'device_code',
session_id: 'local-fixture',
user_code: 'FAKE',
verification_url: 'http://localhost/fixture',
expires_in: 600
}
}
if (request.path.includes('/poll/')) {
return { status: 'approved' }
}
if (request.path === '/api/env' && delayKey) {
await new Promise<void>(resolve => {
release = resolve
})
}
if (request.path.startsWith('/api/model/options')) {
return { providers: [{ slug: 'fixture', name: 'Fixture', models: ['fixture-model'] }] }
}
if (request.path.startsWith('/api/model/recommended-default')) {
return { model: 'fixture-model' }
}
return { ok: true }
})
vi.spyOn(window, 'open').mockReturnValue(null)
let profile = 'beta'
const ctx: OnboardingContext = {
get profile() {
return profile
},
requestGateway: async method =>
(method === 'setup.status' ? { provider_configured: true } : { ok: true }) as never
}
try {
startManualOnboarding(null, 'beta')
const pending = saveOnboardingApiKey('FIREWORKS_API_KEY', 'fake-key', 'Fireworks', ctx)
await vi.waitFor(() => expect(release).toBeTypeOf('function'))
closeManualOnboarding()
profile = 'alpha'
startManualOnboarding(null, 'alpha')
release()
await pending
expect(requests.some(r => r.path === '/api/model/set')).toBe(false)
expect($desktopOnboarding.get()).toMatchObject({ targetScope: { profile: 'alpha' }, flow: { status: 'idle' } })
closeManualOnboarding()
delayKey = false
profile = 'beta'
startManualOnboarding(null, 'beta')
const startAt = requests.length
await startProviderOAuth(makeOAuthProvider('fixture'), ctx)
await vi.waitFor(() => expect($desktopOnboarding.get().flow.status).toBe('confirming_model'), { timeout: 5000 })
expect(requests.slice(startAt).some(r => r.path.includes('/poll/'))).toBe(true)
// Manual flows defer the global-default flip to the confirm card (#102829):
// no /api/model/set lands between the OAuth poll and the confirm card.
// Lifetime/profile pinning is still asserted: everything that DID fire
// stayed on the initiating profile.
expect(requests.slice(startAt).some(r => r.path === '/api/model/set')).toBe(false)
expect(requests.slice(startAt).every(r => r.profile === 'beta')).toBe(true)
} finally {
closeManualOnboarding()
}
})
beforeEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
})
afterEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
resetBootRaceWindowForTests()
vi.restoreAllMocks()
})
it('refreshes OAuth providers again when onboarding was explicitly requested', async () => {
const api = vi.fn(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth') {
return { providers: [makeOAuthProvider('fresh')] }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
$desktopOnboarding.set(baseState({ providers: [makeOAuthProvider('cached')] }))
requestDesktopOnboarding('Need provider setup')
const ready = await refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
expect(ready).toBe(false)
expect(api).toHaveBeenCalledTimes(1)
expect($desktopOnboarding.get().providers?.map(p => p.id)).toEqual(['fresh'])
expect($desktopOnboarding.get().reason).toContain('No usable credentials found for openrouter.')
expect($desktopOnboarding.get().reason).toContain('setup.status reports configured credentials')
})
it('shows no sentence of its own over the picker when nothing is set up', async () => {
const unconfigured: OnboardingContext['requestGateway'] = async method => {
if (method === 'setup.status') {
return { provider_configured: false } as never
}
if (method === 'setup.runtime_check') {
return {
ok: false,
error: 'Hermes is not connected to any AI provider yet. Run `hermes model` to pick one.'
} as never
}
throw new Error(`unexpected gateway method: ${method}`)
}
expect(await refreshOnboarding(onboardingContext(unconfigured))).toBe(false)
expect($desktopOnboarding.get()).toMatchObject({ configured: false, reason: DEFAULT_ONBOARDING_REASON })
})
it.each([
['answers', async () => ({ ok: false, error: NOT_CONNECTED }) as never],
[
'fails',
async () => {
throw new Error(NOT_CONNECTED)
}
]
])('drops an earlier raw sentence once nothing is set up and the runtime check %s', async (_, runtimeCheck) => {
$desktopOnboarding.set(baseState({ reason: NOT_CONNECTED }))
const unconfigured: OnboardingContext['requestGateway'] = async method => {
if (method === 'setup.status') {
return { provider_configured: false } as never
}
if (method === 'setup.runtime_check') {
return runtimeCheck()
}
throw new Error(`unexpected gateway method: ${method}`)
}
expect(await refreshOnboarding(onboardingContext(unconfigured))).toBe(false)
expect($desktopOnboarding.get().reason).not.toContain('hermes model')
})
it('keeps cached providers when onboarding was not re-requested', async () => {
const api = vi.fn(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth') {
return { providers: [makeOAuthProvider('fresh')] }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
$desktopOnboarding.set(baseState({ providers: [makeOAuthProvider('cached')] }))
const ready = await refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
expect(ready).toBe(false)
expect(api).not.toHaveBeenCalled()
expect($desktopOnboarding.get().providers?.map(p => p.id)).toEqual(['cached'])
})
it('does not downgrade configured=true on fallback-only readiness failures', async () => {
const api = vi.fn(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth') {
return { providers: [makeOAuthProvider('fresh')] }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
// Simulate a returning user: cache is set and store is configured.
window.localStorage.setItem('hermes-desktop-onboarded-v1', '1')
$desktopOnboarding.set(
baseState({
configured: true,
providers: [makeOAuthProvider('cached')],
reason: null,
requested: false
})
)
const ready = await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
expect(ready).toBe(false)
expect(api).not.toHaveBeenCalled()
expect($desktopOnboarding.get().configured).toBe(true)
expect($desktopOnboarding.get().reason).toBeNull()
// The cache must survive the refresh — proving we didn't downgrade.
expect(window.localStorage.getItem('hermes-desktop-onboarded-v1')).toBe('1')
})
it('keeps an unknown readiness notice temporary and clears it on recovery (#124545)', async () => {
vi.useFakeTimers()
notifications.clearNotifications()
installApiMock(vi.fn())
$desktopOnboarding.set(baseState({ configured: true }))
try {
await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
expect(notifications.$notifications.get()).toEqual([
expect.objectContaining({ id: 'runtime-not-ready', kind: 'info' })
])
expect($desktopOnboarding.get().configured).toBe(true)
await vi.advanceTimersByTimeAsync(5_000)
expect(notifications.$notifications.get()).toEqual([])
// A later outage can show a fresh notice; an authoritative ready clears it
// without waiting for its timer, and must not dismiss unrelated errors.
await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
notifications.notify({ id: 'unrelated', kind: 'error', message: 'Keep me' })
await refreshOnboarding(onboardingContext(keylessCustomGateway()))
expect(notifications.$notifications.get().map(item => item.id)).toEqual(['unrelated'])
} finally {
notifications.clearNotifications()
vi.useRealTimers()
}
})
it('leaves configured unknown on a boot fallback instead of erasing the cache', async () => {
const notifySpy = vi.spyOn(notifications, 'notify')
installApiMock(vi.fn())
// Cold launch, no onboarded cache yet: `configured` is UNKNOWN, not false.
// A round that loses the race to a cold/queued backend answers neither
// probe, and recording that as "no provider" deleted the cache — which
// re-armed the blocking first-run picker on every launch afterwards.
$desktopOnboarding.set(baseState({ configured: null, providers: null, requested: false }))
const ready = await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
expect(ready).toBe(false)
expect($desktopOnboarding.get().configured).toBeNull()
expect(window.localStorage.getItem('hermes-desktop-onboarded-v1')).toBeNull()
// Nothing was ever verified, so there is no outage worth a toast.
expect(notifySpy).not.toHaveBeenCalled()
})
it('does not downgrade a configured install when the boot race answers ok:false', async () => {
const { notifySetupReady } = await import('@/store/live-sync')
installApiMock(vi.fn())
// Fully configured install (durable cache present), backend just booted:
// setup.ready bumped the boot generation moments ago. The runtime_check
// answers ok:false because the external secret source (BWS) has not
// hydrated yet — a hydration race, not a credential verdict (#124939).
window.localStorage.setItem('hermes-desktop-onboarded-v1', '1')
$desktopOnboarding.set(baseState({ configured: true, providers: null, requested: false }))
notifySetupReady()
const ready = await refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
expect(ready).toBe(false)
expect($desktopOnboarding.get().configured).toBe(true)
expect(window.localStorage.getItem('hermes-desktop-onboarded-v1')).toBe('1')
})
it('still downgrades when the same ok:false arrives long after boot', async () => {
const { notifySetupReady } = await import('@/store/live-sync')
installApiMock(vi.fn())
window.localStorage.setItem('hermes-desktop-onboarded-v1', '1')
$desktopOnboarding.set(baseState({ configured: true, providers: null, requested: false }))
// Boot happened, then the grace window elapsed: an ok:false now is a real
// verdict (the secret source had its chance), so onboarding must surface.
notifySetupReady()
const clock = vi.spyOn(Date, 'now').mockReturnValue(Date.now() + 60_000)
try {
const ready = await refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
expect(ready).toBe(false)
expect($desktopOnboarding.get().configured).toBe(false)
expect(window.localStorage.getItem('hermes-desktop-onboarded-v1')).toBeNull()
} finally {
clock.mockRestore()
}
})
it('keeps a persisted "choose later" when a passive round completes onboarding', () => {
window.localStorage.setItem('hermes-onboarding-skipped-v1', '1')
$desktopOnboarding.set(baseState({ configured: null, firstRunSkipped: true }))
completeDesktopOnboarding()
expect(window.localStorage.getItem('hermes-onboarding-skipped-v1')).toBe('1')
expect($desktopOnboarding.get().firstRunSkipped).toBe(true)
})
it('clears the skip only when the user actually connected a provider', () => {
window.localStorage.setItem('hermes-onboarding-skipped-v1', '1')
$desktopOnboarding.set(baseState({ configured: null, firstRunSkipped: true }))
completeDesktopOnboarding(true)
expect(window.localStorage.getItem('hermes-onboarding-skipped-v1')).toBeNull()
expect($desktopOnboarding.get().firstRunSkipped).toBe(false)
})
it('enters setup when the selected OpenRouter credential is genuinely empty', async () => {
// Outside the boot window: no setup.ready bump precedes the round, so an
// answered ok:false is a real verdict, not a hydration race.
installApiMock(vi.fn())
window.localStorage.setItem('hermes-desktop-onboarded-v1', '1')
$desktopOnboarding.set(
baseState({
configured: true,
providers: [makeOAuthProvider('cached')],
reason: null,
requested: false
})
)
const ready = await refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
expect(ready).toBe(false)
expect($desktopOnboarding.get().configured).toBe(false)
expect($desktopOnboarding.get().reason).toContain('No usable credentials found for openrouter.')
expect(window.localStorage.getItem('hermes-desktop-onboarded-v1')).toBeNull()
})
it('keeps a keyless custom runtime out of setup', async () => {
const api = vi.fn()
installApiMock(api)
$desktopOnboarding.set(baseState({ configured: false, reason: 'stale setup error', requested: true }))
const ready = await refreshOnboarding(onboardingContext(keylessCustomGateway()))
expect(ready).toBe(true)
expect(api).not.toHaveBeenCalled()
expect($desktopOnboarding.get()).toMatchObject({
configured: true,
reason: null,
requested: false
})
})
it('does not preserve configured when onboarding was explicitly requested', async () => {
const api = vi.fn(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth') {
return { providers: [makeOAuthProvider('fresh')] }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
$desktopOnboarding.set(
baseState({
configured: true,
providers: [makeOAuthProvider('cached')],
reason: null,
requested: true
})
)
const ready = await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
expect(ready).toBe(false)
// requested overrides preservation — should downgrade.
expect($desktopOnboarding.get().configured).toBe(false)
expect(api).toHaveBeenCalledTimes(1)
})
it('still surfaces onboarding when fallback failure happens before configured state', async () => {
const api = vi.fn(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth') {
return { providers: [makeOAuthProvider('fresh')] }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
$desktopOnboarding.set(baseState({ configured: false, providers: null, requested: true }))
const ready = await refreshOnboarding(onboardingContext(fallbackTimeoutGateway()))
expect(ready).toBe(false)
expect(api).toHaveBeenCalledTimes(1)
expect($desktopOnboarding.get().configured).toBe(false)
expect($desktopOnboarding.get().reason).toContain('request timed out')
})
it('deduplicates concurrent provider refresh calls', async () => {
let resolveProviders!: (value: { providers: OAuthProvider[] }) => void
const providersPromise = new Promise<{ providers: OAuthProvider[] }>(resolve => {
resolveProviders = value => {
resolve(value)
}
})
const api = vi.fn(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth') {
return providersPromise
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
$desktopOnboarding.set(baseState({ requested: true }))
const first = refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
const second = refreshOnboarding(onboardingContext(emptyOpenRouterGateway()))
await vi.waitFor(() => expect(api).toHaveBeenCalledTimes(1))
resolveProviders({ providers: [makeOAuthProvider('shared')] })
await Promise.all([first, second])
expect($desktopOnboarding.get().providers?.map(p => p.id)).toEqual(['shared'])
})
})
describe('OAuth onboarding', () => {
beforeEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
})
afterEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
resetBootRaceWindowForTests()
vi.restoreAllMocks()
})
it('a Nous sign-in shows its account and what moved on the confirm screen, not in a dialog after it', async () => {
const { startProviderOAuth } = await import('./onboarding')
const { $freeTierSignIn } = await import('./free-tier-sign-in')
const { setOnboardingSurfaceActive } = await import('./onboarding-presence')
const handoff: AppHandoffStatus = { lines: ['Your apps moved to [email protected]: linear.'], state: 'claimed' }
installApiMock(async ({ path }) => {
if (path.endsWith('/start')) {
return { expires_in: 600, flow: 'device_code', session_id: 's', user_code: 'C', verification_url: 'http://x' }
}
if (path.includes('/poll/')) {
return { account_email: '[email protected]', handoff_status: handoff, session_id: 's', status: 'approved' }
}
if (path.startsWith('/api/model/options')) {
return { providers: [{ models: ['nous/m'], name: 'Nous Portal', slug: 'nous' }] }
}
return path.startsWith('/api/model/recommended-default') ? { model: 'nous/m' } : { ok: true }
})
vi.spyOn(window, 'open').mockReturnValue(null)
setOnboardingSurfaceActive('onboarding', true)
await startProviderOAuth(makeOAuthProvider('nous', 'Nous Portal'), {
requestGateway: async method =>
// SAFETY: onboarding reads only `provider_configured` from setup.status and `ok` from the rest.
(method === 'setup.status' ? { provider_configured: true } : { ok: true }) as never
})
await vi.waitFor(() => expect($desktopOnboarding.get().flow.status).toBe('confirming_model'), { timeout: 5000 })
expect($desktopOnboarding.get().flow).toMatchObject({ signedIn: { email: '[email protected]', handoff } })
setOnboardingSurfaceActive('onboarding', false)
expect($freeTierSignIn.get()).toEqual({ status: 'closed' })
})
it('clears stale readiness errors after OAuth succeeds and model confirmation is shown', async () => {
const model = 'anthropic/claude-opus-4.8'
const calls: { body?: unknown; path: string }[] = []
installApiMock(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/providers/oauth/nous/submit') {
return { ok: true, status: 'approved' }
}
if (path.startsWith('/api/model/options')) {
return {
providers: [
{
name: 'Nous Portal',
slug: 'nous',
models: [model]
}
]
}
}
if (path.startsWith('/api/model/recommended-default?')) {
return { provider: 'nous', model, free_tier: false }
}
if (path === '/api/model/set') {
return { ok: true, provider: 'nous', model, gateway_tools: [] }
}
throw new Error(`unexpected api path: ${path}`)
})
const requestGateway: OnboardingContext['requestGateway'] = async (method, params) => {
if (method === 'reload.env') {
return {} as never
}
if (method === 'setup.status') {
return { provider_configured: true } as never
}
if (method === 'setup.runtime_check') {
expect(params).toEqual({ provider: 'nous' })
return { ok: true } as never
}
throw new Error(`unexpected gateway method: ${method}`)
}
$desktopOnboarding.set(
baseState({
flow: {
status: 'awaiting_user',
provider: makeOAuthProvider('nous', 'Nous Portal'),
start: {
auth_url: 'https://portal.example/auth',
expires_in: 600,
flow: 'pkce',
session_id: 'portal-session'
},
code: 'fresh-code'
},
reason:
'No access token found for Nous Portal login. setup.status reports configured credentials, but runtime resolution still failed.',
requested: true
})
)
await submitOnboardingCode(onboardingContext(requestGateway))
const state = $desktopOnboarding.get()
expect(state.reason).toBeNull()
expect(state.flow.status).toBe('confirming_model')
if (state.flow.status === 'confirming_model') {
expect(state.flow.label).toBe('Nous Portal')
expect(state.flow.currentModel).toBe(model)
}
expect(calls.some(c => c.path === '/api/model/set')).toBe(true)
const optionsIndex = calls.findIndex(c => c.path.startsWith('/api/model/options'))
const recommendedIndex = calls.findIndex(c => c.path.startsWith('/api/model/recommended-default'))
const setIndex = calls.findIndex(c => c.path === '/api/model/set')
expect(optionsIndex).toBeGreaterThanOrEqual(0)
expect(recommendedIndex).toBeGreaterThan(optionsIndex)
expect(setIndex).toBeGreaterThan(recommendedIndex)
})
it('does not advance when the default model assignment is not persisted', async () => {
const model = 'openai/gpt-5.5-pro'
installApiMock(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth/nous/submit') {
return { ok: true, status: 'approved' }
}
if (path.startsWith('/api/model/options')) {
return { providers: [{ name: 'Nous Portal', slug: 'nous', models: [model] }] }
}
if (path.startsWith('/api/model/recommended-default?')) {
return { provider: 'nous', model, free_tier: false }
}
if (path === '/api/model/set') {
return {
ok: false,
provider: 'nous',
model,
confirm_required: true,
confirm_message: 'Confirm this expensive model.'
}
}
throw new Error(`unexpected api path: ${path}`)
})
const requestGatewayMock = vi.fn(async (method: string) => {
if (method === 'reload.env') {
return {}
}
throw new Error(`unexpected gateway method: ${method}`)
})
const requestGateway = requestGatewayMock as OnboardingContext['requestGateway']
$desktopOnboarding.set(
baseState({
flow: {
status: 'awaiting_user',
provider: makeOAuthProvider('nous', 'Nous Portal'),
start: {
auth_url: 'https://portal.example/auth',
expires_in: 600,
flow: 'pkce',
session_id: 'portal-session'
},
code: 'fresh-code'
},
requested: true
})
)
await submitOnboardingCode(onboardingContext(requestGateway))
const state = $desktopOnboarding.get()
expect(state.flow.status).toBe('error')
expect(state.flow.status === 'error' ? state.flow.message : '').toContain('Confirm this expensive model.')
expect(requestGatewayMock).not.toHaveBeenCalledWith('setup.runtime_check', expect.anything())
})
})
describe('manual onboarding (Settings / Add provider on an already-configured install)', () => {
beforeEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
})
afterEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
vi.restoreAllMocks()
})
it('does not flip the global default until the user confirms on the confirm card', async () => {
const model = 'nous/hermes-5'
const calls: { body?: unknown; path: string }[] = []
installApiMock(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/providers/oauth/nous/submit') {
return { ok: true, status: 'approved' }
}
if (path.startsWith('/api/model/options')) {
return { providers: [{ name: 'Nous Portal', slug: 'nous', models: [model] }] }
}
if (path.startsWith('/api/model/recommended-default?')) {
return { provider: 'nous', model, free_tier: false }
}
if (path === '/api/model/set') {
return { ok: true, provider: 'nous', model, gateway_tools: [] }
}
throw new Error(`unexpected api path: ${path}`)
})
const requestGateway: OnboardingContext['requestGateway'] = async (method, params) => {
if (method === 'reload.env') {
return {} as never
}
if (method === 'setup.status') {
return { provider_configured: true } as never
}
if (method === 'setup.runtime_check') {
// Still validated against the just-connected provider, not the
// (unchanged) config default — this is what makes deferring the
// persist safe.
expect(params).toEqual({ provider: 'nous' })
return { ok: true } as never
}
throw new Error(`unexpected gateway method: ${method}`)
}
// The user already has a working, different default configured — the
// exact scenario from the bug report (anthropic default, connecting Nous
// Portal as an *additional* provider from Settings).
$desktopOnboarding.set(
baseState({
manual: true,
flow: {
status: 'awaiting_user',
provider: makeOAuthProvider('nous', 'Nous Portal'),
start: {
auth_url: 'https://portal.example/auth',
expires_in: 600,
flow: 'pkce',
session_id: 'portal-session'
},
code: 'fresh-code'
},
requested: true
})
)
await submitOnboardingCode(onboardingContext(requestGateway))
const state = $desktopOnboarding.get()
expect(state.flow.status).toBe('confirming_model')
// OAuth succeeded and the confirm card is showing the new provider's
// model, but nothing has been written to config yet.
expect(calls.some(c => c.path === '/api/model/set')).toBe(false)
// Dismissing here (closeManualOnboarding) leaves the previous default
// untouched precisely because this call never fires.
})
it('persists the confirmed model only when the user clicks Begin', async () => {
const model = 'nous/hermes-5'
const calls: { body?: unknown; path: string }[] = []
installApiMock(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/model/set') {
return { ok: true, provider: 'nous', model, gateway_tools: [] }
}
throw new Error(`unexpected api path: ${path}`)
})
$desktopOnboarding.set(
baseState({
manual: true,
configured: true,
flow: {
status: 'confirming_model',
providerSlug: 'nous',
currentModel: model,
label: 'Nous Portal',
saving: false
}
})
)
const onCompleted = vi.fn()
await confirmOnboardingModel({ requestGateway: vi.fn(), onCompleted })
const assign = calls.find(c => c.path === '/api/model/set')
expect(assign?.body).toMatchObject({ scope: 'main', provider: 'nous', model })
expect(onCompleted).toHaveBeenCalledTimes(1)
})
})
describe('saveOnboardingLocalEndpoint', () => {
beforeEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
})
afterEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
resetBootRaceWindowForTests()
vi.restoreAllMocks()
})
function readyGateway(): OnboardingContext['requestGateway'] {
return async method => {
if (method === 'reload.env') {
return {} as never
}
if (method === 'setup.status') {
return { provider_configured: true } as never
}
if (method === 'setup.runtime_check') {
return { ok: true } as never
}
throw new Error(`unexpected gateway method: ${method}`)
}
}
it('returns needsModelInput when the endpoint advertises no models (nothing to route to)', async () => {
const calls: string[] = []
installApiMock(async ({ path }: { path: string }) => {
calls.push(path)
if (path === '/api/providers/validate') {
return { ok: true, reachable: true, message: '', models: [] }
}
throw new Error(`unexpected api path: ${path}`)
})
const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', '', {
requestGateway: readyGateway()
})
expect(result.ok).toBe(false)
// The wizard reads this discriminator to reveal a manual model-name input.
expect(result.needsModelInput).toBe(true)
expect(result.message).toMatch(/didn't enumerate any models|advertised no models/)
// Must not attempt to persist an assignment without a model.
expect(calls).not.toContain('/api/model/set')
})
it('uses a manually provided model name and skips discovery when /v1/models is empty', async () => {
const calls: { body?: unknown; path: string }[] = []
installApiMock(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/providers/validate') {
// Endpoint reachable but the discovery list is empty — the bug-class
// case the wizard used to hard-fail on.
return { ok: true, reachable: true, message: '', models: [] }
}
if (path === '/api/model/set') {
return {
ok: true,
provider: 'custom',
model: 'command-a-plus-05-2026',
base_url: 'https://api.cohere.ai/compatibility/v1'
}
}
throw new Error(`unexpected api path: ${path}`)
})
const result = await saveOnboardingLocalEndpoint(
'https://api.cohere.ai/compatibility/v1',
'sk-secret',
{ requestGateway: readyGateway() },
'command-a-plus-05-2026'
)
expect(result.ok).toBe(true)
const assign = calls.find(c => c.path === '/api/model/set')
// The manually provided model name is persisted verbatim — the runtime
// honors it the same way as discover_models: false + an explicit models:.
expect(assign?.body).toMatchObject({
scope: 'main',
provider: 'custom',
model: 'command-a-plus-05-2026',
base_url: 'https://api.cohere.ai/compatibility/v1',
api_key: 'sk-secret'
})
})
it('uses a manually provided model name even when /v1/models enumerates models', async () => {
// The user is allowed to override the auto-discovered default by typing a
// model name before submitting. The wizard never pre-fills the model input
// in the happy path, but the store function must still honor modelName
// over probe.models[0] when both are available.
const calls: { body?: unknown; path: string }[] = []
installApiMock(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/providers/validate') {
return { ok: true, reachable: true, message: '', models: ['llama-3.1-8b'] }
}
if (path === '/api/model/set') {
return { ok: true, provider: 'custom', model: 'llama-3.1-8b', base_url: 'http://127.0.0.1:8000/v1' }
}
throw new Error(`unexpected api path: ${path}`)
})
const result = await saveOnboardingLocalEndpoint(
'http://127.0.0.1:8000/v1',
'',
{ requestGateway: readyGateway() },
' llama-3.3-70b '
)
expect(result.ok).toBe(true)
const assign = calls.find(c => c.path === '/api/model/set')
expect(assign?.body).toMatchObject({ model: 'llama-3.3-70b' })
})
it('auto-discovers the model and persists provider=custom + base_url, then finishes', async () => {
const calls: { body?: unknown; path: string }[] = []
const api = vi.fn(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/providers/validate') {
return { ok: true, reachable: true, message: '', models: ['llama-3.1-8b', 'qwen2.5-7b'] }
}
if (path === '/api/model/set') {
return { ok: true, provider: 'custom', model: 'llama-3.1-8b', base_url: 'http://127.0.0.1:8000/v1' }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
const onCompleted = vi.fn()
const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', '', {
onCompleted,
requestGateway: readyGateway()
})
expect(result.ok).toBe(true)
const assign = calls.find(c => c.path === '/api/model/set')
expect(assign?.body).toMatchObject({
scope: 'main',
provider: 'custom',
model: 'llama-3.1-8b',
base_url: 'http://127.0.0.1:8000/v1'
})
expect(onCompleted).toHaveBeenCalledTimes(1)
expect($desktopOnboarding.get().configured).toBe(true)
})
it('forwards the API key to the probe and persists it for auth-gated endpoints', async () => {
const calls: { body?: unknown; path: string }[] = []
const api = vi.fn(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/providers/validate') {
return { ok: true, reachable: true, message: '', models: ['gpt-oss-120b'] }
}
if (path === '/api/model/set') {
return { ok: true, provider: 'custom', model: 'gpt-oss-120b', base_url: 'https://text.example.com/v1' }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
const result = await saveOnboardingLocalEndpoint('https://text.example.com/v1', 'sk-secret', {
requestGateway: readyGateway()
})
expect(result.ok).toBe(true)
// The probe must receive the key so an auth-gated /v1/models enumerates.
const probe = calls.find(c => c.path === '/api/providers/validate')
expect(probe?.body).toMatchObject({
key: 'OPENAI_BASE_URL',
value: 'https://text.example.com/v1',
api_key: 'sk-secret'
})
// And the key must be persisted alongside the endpoint for runtime auth.
const assign = calls.find(c => c.path === '/api/model/set')
expect(assign?.body).toMatchObject({
scope: 'main',
provider: 'custom',
model: 'gpt-oss-120b',
base_url: 'https://text.example.com/v1',
api_key: 'sk-secret'
})
})
it('persists the resolved_base_url that served /models, not the URL as typed (#65488)', async () => {
const calls: { body?: unknown; path: string }[] = []
const api = vi.fn(async ({ body, path }: { body?: unknown; path: string }) => {
calls.push({ body, path })
if (path === '/api/providers/validate') {
// The probe fell through from the bare host root to its /v1 variant.
return {
ok: true,
reachable: true,
message: '',
models: ['llama-3.1-8b'],
resolved_base_url: 'http://127.0.0.1:1234/v1'
}
}
if (path === '/api/model/set') {
return { ok: true, provider: 'custom', model: 'llama-3.1-8b', base_url: 'http://127.0.0.1:1234/v1' }
}
throw new Error(`unexpected api path: ${path}`)
})
installApiMock(api)
const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:1234', '', {
requestGateway: readyGateway()
})
expect(result.ok).toBe(true)
// The runtime POSTs {base_url}/chat/completions verbatim, so Save must store
// the base that actually answered /models rather than the typed host root.
const assign = calls.find(c => c.path === '/api/model/set')
expect(assign?.body).toMatchObject({
scope: 'main',
provider: 'custom',
model: 'llama-3.1-8b',
base_url: 'http://127.0.0.1:1234/v1'
})
})
it('reports the runtime reason when resolution still fails after saving', async () => {
installApiMock(async ({ path }: { path: string }) => {
if (path === '/api/providers/validate') {
return { ok: true, reachable: true, message: '', models: ['llama-3.1-8b'] }
}
if (path === '/api/model/set') {
return { ok: true }
}
throw new Error(`unexpected api path: ${path}`)
})
const failingGateway: OnboardingContext['requestGateway'] = async method => {
if (method === 'reload.env') {
return {} as never
}
if (method === 'setup.status') {
return { provider_configured: true } as never
}
if (method === 'setup.runtime_check') {
return { ok: false, error: 'No provider can serve the selected model.' } as never
}
throw new Error(`unexpected gateway method: ${method}`)
}
const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', '', {
requestGateway: failingGateway
})
expect(result.ok).toBe(false)
expect(result.message).toContain('No provider can serve the selected model.')
expect($desktopOnboarding.get().configured).not.toBe(true)
})
})
describe('device-code poll expiry', () => {
beforeEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
})
afterEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
vi.restoreAllMocks()
vi.useRealTimers()
})
function deviceCodeProvider() {
// makeOAuthProvider builds a pkce provider; device-code flows need the
// device_code branch instead.
return { ...makeOAuthProvider('nous', 'Nous Portal'), flow: 'device_code' as const }
}
function deviceStart(expiresIn: number) {
return {
expires_in: expiresIn,
flow: 'device_code',
poll_interval: 5,
session_id: 'device-sess-1',
user_code: 'ABCD-EFGH',
verification_url: 'https://portal.example/device'
}
}
it('lapses to an error with actionable guidance when the window expires still pending', async () => {
vi.useFakeTimers()
installApiMock(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth/nous/start') {
return deviceStart(2)
}
if (path.startsWith('/api/providers/oauth/nous/poll/device-sess-1')) {
return { status: 'pending' }
}
throw new Error(`unexpected api path: ${path}`)
})
const { startProviderOAuth } = await import('./onboarding')
await startProviderOAuth(deviceCodeProvider(), onboardingContext(emptyOpenRouterGateway()))
expect($desktopOnboarding.get().flow.status).toBe('polling')
// Let both the poll interval and the expiry window lapse.
await act(async () => {
vi.advanceTimersByTime(3000)
})
expect($desktopOnboarding.get().flow.status).toBe('error')
})
it('keeps polling while the window is open and clears the expiry on cancel', async () => {
vi.useFakeTimers()
installApiMock(async ({ path }: { path: string }) => {
if (path === '/api/providers/oauth/nous/start') {
return deviceStart(600)
}
if (path.startsWith('/api/providers/oauth/nous/poll/device-sess-1')) {
return { status: 'pending' }
}
throw new Error(`unexpected api path: ${path}`)
})
const { startProviderOAuth, cancelOnboardingFlow } = await import('./onboarding')
await startProviderOAuth(deviceCodeProvider(), onboardingContext(emptyOpenRouterGateway()))
await act(async () => {
vi.advanceTimersByTime(10_000)
})
expect($desktopOnboarding.get().flow.status).toBe('polling')
cancelOnboardingFlow()
// Far past the original window: the cancelled flow must not flip to an
// expiry error after the fact.
await act(async () => {
vi.advanceTimersByTime(700_000)
})
expect($desktopOnboarding.get().flow.status).toBe('idle')
})
})
// The happy path (cross-provider pick reaches /api/model/set with the picked
// model's provider) is covered from the ConfirmingModelPanel in
// components/onboarding/flow.test.tsx so it exercises the onSelect wiring.
describe('setOnboardingModel', () => {
beforeEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
})
afterEach(() => {
window.localStorage.clear()
$desktopOnboarding.set(baseState())
resetBootRaceWindowForTests()
vi.restoreAllMocks()
})
function confirmingModelState(
overrides: Partial<Extract<DesktopOnboardingState['flow'], { status: 'confirming_model' }>> = {}
) {
return baseState({
flow: {
status: 'confirming_model',
currentModel: 'gpt-5.6-terra',
label: 'OpenAI OAuth (ChatGPT)',
providerSlug: 'openai',
saving: false,
...overrides
}
})
}
it('reverts the model, provider and label when persistence fails', async () => {
installApiMock(async () => {
throw new Error('backend down')
})
$desktopOnboarding.set(confirmingModelState())
await setOnboardingModel('deepseek/deepseek-v4-flash-0731', 'nous', 'Nous Portal')
const flow = $desktopOnboarding.get().flow
expect(flow.status).toBe('confirming_model')
if (flow.status === 'confirming_model') {
expect(flow.currentModel).toBe('gpt-5.6-terra')
expect(flow.providerSlug).toBe('openai')
expect(flow.label).toBe('OpenAI OAuth (ChatGPT)')
expect(flow.saving).toBe(false)
}
})
})