@fonlan/dsh-model-router 0.3.6 → 0.3.8

package/src/client/index.tsx

@@ -15,27 +15,22 @@ import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-ui-model-selection/client'
 import { LOCALE_NS, zh, en } from './locales'
-import { makeSettingsSection, type SettingsScopeFace } from './settings-section'
+import { makeSettingsSection } from './settings-section'
 import { registerModelRouterSeat } from './model-seat'
 
-/** The settings namespace this page edits (must match the host half). */
-const ROUTER_NS = 'model-router'
-
 /** The settings sidebar entry this page owns (must stay stable). */
 const SECTION_ID = 'model-router'
 
 /** Slots face: the settings.section list slot is declared at runtime by the
  *  settings shell (ui-settings-general), which external plugins do not depend
  *  on; the register call below is typed through this local face (erased at
- *  build time). Its inject face binds the model-router settings scope, which
- *  reaches the component as the scope prop. */
+ *  build time). */
 interface SectionEntry {
   name: string
   id?: string
   order?: number
   label?: () => string
   locale?: string
-  inject?: () => unknown
 }
 
 interface Slots {
@@ -47,7 +42,7 @@ interface Slots {
  *  `remote.session` is included like the host ui-model-selection declares it:
  *  the seat's `directoryFor` depends on the namespace, which mounts
  *  asynchronously at startup. */
-export const inject = ['slots', 'locale', 'modelDirectories', 'sessions', 'settingsScope', 'connection', 'remote', 'remote.session']
+export const inject = ['slots', 'locale', 'modelDirectories', 'sessions', 'connection', 'remote', 'remote.session']
 
 /** Client plugin body. */
 export function apply(ctx: ClientContext): void {
@@ -60,24 +55,24 @@ export function apply(ctx: ClientContext): void {
   const SettingsSection = makeSettingsSection(ctx)
 
   // The page registers on the settings.section list slot under a stable id, so
-  // it appears in the settings sidebar's left navigation. The bound
-  // model-router settings scope (the same namespace the host half registers)
-  // travels through the inject face and reaches the component as scope.
-  const services = ctx as unknown as {
-    slots: Slots
-    settingsScope: { bind(spec: { namespace: string }): SettingsScopeFace }
-  }
-  const scope = services.settingsScope.bind({ namespace: ROUTER_NS })
-
-  services.slots.inject('settings.section', () =>
-    services.slots.register(
+  // it appears in the settings sidebar's left navigation.
+  //
+  // dsh >= 0.1.7 dropped the client-side `settingsScope` service (plugin
+  // configuration became loader-entry config, projected by the host), and the
+  // old conditional registration therefore never fired: the section silently
+  // disappeared from Settings. Register unconditionally — the page reads and
+  // writes through this plugin's own fenced API (see ./settings-section), so
+  // it needs no settings service at all. Never gate a slot registration on a
+  // service that may not exist: the failure mode is an invisible page.
+  const slots = (ctx as unknown as { slots: Slots }).slots
+  slots.inject('settings.section', () =>
+    slots.register(
       {
         name: 'settings.section',
         id: SECTION_ID,
         order: 300,
         label: () => t('settingsTitle'),
         locale: LOCALE_NS,
-        inject: () => ({ scope }),
       },
       SettingsSection,
     ),

package/src/client/model-seat.tsx

@@ -15,15 +15,10 @@ import type { SessionId } from '@deepseek-ai/dsh-session/types'
 type ClientContext = Context
 import type { ModelDirectoryState } from '@deepseek-ai/dsh-client-ui-model-selection/client'
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import {
-  IconCheckOutline16,
-  IconChevronDownOutline14,
-  IconChevronRightOutline14,
-  IconWarningOutline16,
-  Toast,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+import { Toast } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-ui-model-selection/client'
+import { CheckIcon, ChevronDownIcon, ChevronRightIcon, WarningIcon } from './icons'
 import { api, type ModelRouterState, type RouterModelView } from './api'
 import { LOCALE_NS } from './locales'
 import './model-seat.css'
@@ -392,7 +387,7 @@ export function ModelRouterSeat({
           <span className="mr-seat-triggerEffort">{effortLabel}</span>
         )}
         <span className={`mr-seat-chevron${open ? ' mr-seat-chevronOpen' : ''}`} aria-hidden>
-          <IconChevronDownOutline14 />
+          <ChevronDownIcon />
         </span>
       </button>
       {open && (
@@ -415,7 +410,7 @@ export function ModelRouterSeat({
                 <span className="mr-seat-cellLabel">{t('menuModel')}</span>
                 <span className="mr-seat-cellValue">{modelLabel}</span>
                 <span className="mr-seat-cellChevron" aria-hidden>
-                  <IconChevronRightOutline14 />
+                  <ChevronRightIcon />
                 </span>
               </button>
               {providerRowVisible && (
@@ -429,7 +424,7 @@ export function ModelRouterSeat({
                   <span className="mr-seat-cellLabel">{t('menuProvider')}</span>
                   <span className="mr-seat-cellValue">{activeProviderName}</span>
                   <span className="mr-seat-cellChevron" aria-hidden>
-                    <IconChevronRightOutline14 />
+                    <ChevronRightIcon />
                   </span>
                 </button>
               )}
@@ -444,7 +439,7 @@ export function ModelRouterSeat({
                   <span className="mr-seat-cellLabel">{t('menuEffort')}</span>
                   <span className="mr-seat-cellValue">{effortLabel}</span>
                   <span className="mr-seat-cellChevron" aria-hidden>
-                    <IconChevronRightOutline14 />
+                    <ChevronRightIcon />
                   </span>
                 </button>
               )}
@@ -505,7 +500,7 @@ export function ModelRouterSeat({
                               )}
                             </span>
                             <span className="mr-seat-check" aria-hidden>
-                              {selected ? <IconCheckOutline16 /> : null}
+                              {selected ? <CheckIcon /> : null}
                             </span>
                           </button>
                         )
@@ -562,7 +557,7 @@ export function ModelRouterSeat({
                             )}
                           </span>
                           <span className="mr-seat-check" aria-hidden>
-                            {selected ? <IconCheckOutline16 /> : null}
+                            {selected ? <CheckIcon /> : null}
                           </span>
                         </button>
                       )
@@ -603,7 +598,7 @@ export function ModelRouterSeat({
                     )}
                   </span>
                   <span className="mr-seat-check" aria-hidden>
-                    {effectiveEffort === level.effort ? <IconCheckOutline16 /> : null}
+                    {effectiveEffort === level.effort ? <CheckIcon /> : null}
                   </span>
                 </button>
               ))}
@@ -615,7 +610,7 @@ export function ModelRouterSeat({
         <Toast
           key={toast.seq}
           text={toast.text}
-          icon={<IconWarningOutline16 />}
+          icon={<WarningIcon />}
           anchor={rootRef.current?.closest('[data-composer-card]') ?? null}
           onDone={() => setToast(null)}
         />
@@ -654,12 +649,19 @@ interface SeatScopeFace {
   slots: SlotsFace
 }
 
+/**
+ * Idle directory snapshot for the inert seat face. Mirrors the shape the
+ * official `ModelDirectory` store starts from, including `pending` (the
+ * selection an in-flight `select` submitted; null when none) — required by
+ * `ModelDirectoryState` and present in both 0.1.x and 0.2.x.
+ */
 const EMPTY_DIRECTORY_STATE: ModelDirectoryState = {
   current: null,
   routable: null,
   groups: [],
   failures: [],
   status: 'idle',
+  pending: null,
   error: null,
 }
 

package/src/client/settings-section.tsx

@@ -6,14 +6,14 @@
  * page draws its own static header (title plus a one-line summary) over the
  * router controls: every routed model with its providers, their order and the
  * provider the model currently routes to. All reads/mutations go through the
- * plugin's fenced API; the server persists through the `model-router` settings
- * namespace, so a switch here is live for the next request globally.
+ * plugin's fenced API; the server persists into this plugin's loader-entry
+ * config (dsh >= 0.1.7), so a switch here is live for the next request
+ * globally.
  *
- * The bound settings scope (the same `model-router` namespace the host half
- * registers) supplies the page's dispatch state: while the namespace is merely
- * loading the page stays mounted, and when it is unavailable (deployment
- * without the host half) nothing renders. A read-only deployment shows the
- * banner and disables the mutation controls.
+ * The page needs no settings service: whether the deployment can persist is
+ * reported by the API itself (`state.writable`), so the page registers and
+ * mounts everywhere the host half serves its API. A read-only deployment
+ * shows the banner and disables the mutation controls.
  */
 import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
 import type { Context } from '@deepseek-ai/cordis'
@@ -23,20 +23,6 @@ import { LOCALE_NS } from './locales'
 import { api, type ModelRouterState, type ModelSortMode, type RouterModelView } from './api'
 import './settings-section.css'
 
-/** Client settings scope face (subset of the app client modules). */
-export interface SettingsScopeFace {
-  getSnapshot(): {
-    status: 'loading' | 'ready' | 'unavailable'
-    writable: boolean
-  }
-  subscribe(listener: () => void): () => void
-}
-
-export interface SettingsSectionProps {
-  /** The bound `model-router` settings scope (from the slot entry's inject face). */
-  scope: SettingsScopeFace
-}
-
 function arrayMove<T>(list: readonly T[], from: number, to: number): T[] {
   const next = [...list]
   const [item] = next.splice(from, 1)
@@ -65,7 +51,7 @@ function useLocaleRevision(ctx: ClientContext): number {
   return useSyncExternalStore(subscribe, getSnapshot)
 }
 
-export function makeSettingsSection(ctx: ClientContext): (props: SettingsSectionProps) => JSX.Element | null {
+export function makeSettingsSection(ctx: ClientContext): () => JSX.Element {
   // Bound translation is namespace-typed; the page's props use the plain
   // Translate face (string keys), which the dict satisfies structurally.
   const t: Translate = (() => {
@@ -76,14 +62,7 @@ export function makeSettingsSection(ctx: ClientContext): (props: SettingsSection
     }
   })()
 
-  return function ModelRouterSettingsSection(props: SettingsSectionProps): JSX.Element | null {
-    const { scope } = props
-    // Bind the methods: React invokes getSnapshot/subscribe as bare functions,
-    // and SettingsScopeController's methods depend on `this`.
-    const snapshot = useSyncExternalStore(
-      (listener) => scope.subscribe(listener),
-      () => scope.getSnapshot(),
-    )
+  return function ModelRouterSettingsSection(): JSX.Element {
     useLocaleRevision(ctx)
     const [state, setState] = useState<ModelRouterState | null>(null)
     const [error, setError] = useState<string | null>(null)
@@ -98,7 +77,8 @@ export function makeSettingsSection(ctx: ClientContext): (props: SettingsSection
     const load = useCallback(async () => {
       setLoading(true)
       try {
-        setState(await api.state())
+        const next = await api.state()
+        setState(next)
         setError(null)
       } catch (cause) {
         setError(cause instanceof Error ? cause.message : String(cause))
@@ -213,12 +193,11 @@ export function makeSettingsSection(ctx: ClientContext): (props: SettingsSection
       }
     }, [state, t])
 
-    // The namespace is served by the host once the scope is ready. While it is
-    // merely loading, keep the page mounted (the sidebar already dispatched
-    // it); if it is unavailable (deployment without the host half), render
-    // nothing.
-    if (snapshot.status === 'unavailable') return null
-    const writable = snapshot.writable
+    // Persistence capability is reported by the host half through the API
+    // itself. A host that predates the field reads as writable: the page must
+    // not block edits (with a wrong "read-only" banner) merely because the
+    // host half and the client bundle are briefly out of step.
+    const writable = state?.writable ?? true
 
     const models = useMemo(() => state?.models ?? [], [state])
 
@@ -229,7 +208,7 @@ export function makeSettingsSection(ctx: ClientContext): (props: SettingsSection
           <p className="mr-page-sub">{t('sectionSub')}</p>
         </header>
         <div className="mr-body">
-          {!writable && (
+          {!loading && state !== null && !writable && (
             <p className="mr-settings-readonly" role="status">{t('readOnly')}</p>
           )}
           <div className="mr-root">

package/src/index.ts

@@ -3,14 +3,15 @@
  *
  * Registers one `model-router` LLM adapter that aggregates every configured
  * provider and model (strict model-id merge), routes each request to the
- * model's currently active provider by in-process delegation, persists the
- * per-model provider order/active config in the `model-router` settings
- * namespace, and serves the fenced JSON API the web settings page calls.
+ * model's currently active provider by in-process delegation, keeps the
+ * per-model provider order/active config in the entry config of this bundle
+ * (dsh >= 0.1.7: the `Config` schema below is the settings document), and
+ * serves the fenced JSON API the web settings page calls.
  */
 import type { Context } from '@deepseek-ai/cordis'
-import z from '@deepseek-ai/schemastery'
-import { ModelRouterService } from './server/service.js'
+import { ModelRouterService, RouterConfigSchema } from './server/service.js'
 import { registerApiRoutes } from './server/rpc.js'
+import type { RouterConfigShape } from './shared/config.js'
 
 export const name = '@fonlan/dsh-model-router'
 
@@ -20,10 +21,12 @@ export const name = '@fonlan/dsh-model-router'
 // no settings page).
 export const inject = ['llm']
 
-export const Config = z.object({})
+// The entry config IS the router document: the settings plane writes it
+// (settings page / settings.replace) and a changed config restarts this entry.
+export const Config = RouterConfigSchema
 
-export function apply(ctx: Context): void {
-  const service = new ModelRouterService(ctx)
+export function apply(ctx: Context, config: RouterConfigShape): void {
+  const service = new ModelRouterService(ctx, config)
 
   ctx.effect(() => {
     service.start()

package/src/server/catalog.ts

@@ -7,7 +7,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import { credentialRef, type CredentialProvider } from '@deepseek-ai/dsh-credentials'
-import type { SettingsProvider } from '@deepseek-ai/dsh-settings'
+import type { SettingsDescriptor } from '@deepseek-ai/dsh-settings'
 import { mergeModels, ROUTER_PROVIDER_ID, type MergedModel, type ProviderInfo } from '../shared/config.js'
 
 /** Live router catalog: everything the router can advertise and route to. */
@@ -39,10 +39,21 @@ interface ConfigurableEntry {
   settingsPath: readonly string[]
 }
 
-/** Read the resolved value of another plugin's settings section, if registered. */
+/**
+ * Read the resolved value of another plugin's settings section, if the
+ * settings plane describes it. The descriptor's `ns` is the profile entry id,
+ * so the value is that entry's resolved Config (defaults → composition base →
+ * user layer). `describe()` lists only entries that declare volatile
+ * (form-writable) fields, and redaction is off here because the caller reads a
+ * non-secret field (`apiKeyEnv`). An undescribed section, or an unavailable
+ * settings service, yields undefined.
+ */
 function settingsSection(ctx: Context, ns: string): unknown {
   try {
-    return (ctx.settings as SettingsProvider).get(ns as never)
+    const descriptor: SettingsDescriptor | undefined = ctx.settings
+      .describe({ redactSecrets: false })
+      .find(candidate => candidate.ns === ns)
+    return descriptor?.value
   } catch {
     return undefined
   }

package/src/server/service.ts

@@ -5,7 +5,6 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
-import type { SettingsScope } from '@deepseek-ai/dsh-settings'
 import type { AdapterRegistrationHandle } from '@deepseek-ai/dsh-llm'
 import {
   initialConfigFor,
@@ -25,32 +24,57 @@ import { ModelRouterAdapter, type RouterFacts } from './adapter.js'
 
 export const NS = ROUTER_SETTINGS_NS
 
-/** Settings document schema: one entry per model id. */
-export const RouterConfigSchema: z<RouterConfigShape> = z.object({
+/**
+ * The slice of the host settings service this plugin writes through. dsh >=
+ * 0.1.7 owns plugin configuration as entry config (the plugin's `Config`
+ * schema), so the router reads the document it was applied with and persists
+ * updates via `settings.replace`, which writes the profile patch.
+ */
+export interface SettingsReplaceFace {
+  replace(ns: string, section: object, expectedRevision?: number): Promise<void>
+}
+
+/**
+ * Settings document schema: one entry per model id.
+ *
+ * Every writable field stays `.volatile()`: the settings plane refuses a
+ * namespace whose form has no volatile field, and `settings.replace` refuses
+ * non-volatile paths. The exported schema is nevertheless ASSERTED to the
+ * plain `z<RouterConfigShape>` (the declared type it had before the
+ * schemastery bump) for two reasons:
+ *  - since schemastery 3.18.3 a `.volatile()` field's output types as
+ *    `Volatile<T>`, so `: z<RouterConfigShape>` no longer *compiles*, while the
+ *    inferred schema type cannot be named in the emitted declarations either
+ *    (TS2742: it would need a pnpm-nested cosmokit type, and `pnpm build` runs
+ *    tsc in declaration mode);
+ *  - the plain shape is what consumers actually observe: the loader hands the
+ *    fields over as live `{ get() }` cells and `normalizeConfig` unwinds them.
+ * The assertion is type-level only — the runtime schema keeps its volatile
+ * markers, which is what the settings plane reads.
+ */
+export const RouterConfigSchema = z.object({
+  // Volatile marks what the settings plane may write: the settings page and
+  // settings.replace both refuse non-volatile fields.
   models: z.dict(z.object({
     order: z.array(z.string()),
     active: z.string(),
-  })),
+  })).volatile(),
   // Older documents predate the toggles; normalizeConfig defaults both on.
   // Schemastery object keys are input-optional, so absent is valid here.
-  showQuickSwitch: z.boolean(),
-  ignoreModelIdPrefix: z.boolean(),
-  modelSort: z.union([z.const('custom'), z.const('name'), z.const('recent')]),
-  modelOrder: z.array(z.string()),
-  recentlyUsed: z.dict(z.number()),
-})
-
-const EMPTY_CONFIG: RouterConfigShape = {
-  models: {},
-  showQuickSwitch: true,
-  ignoreModelIdPrefix: true,
-  modelSort: 'custom',
-  modelOrder: [],
-  recentlyUsed: {},
-}
+  showQuickSwitch: z.boolean().volatile(),
+  ignoreModelIdPrefix: z.boolean().volatile(),
+  modelSort: z.union([z.const('custom'), z.const('name'), z.const('recent')]).volatile(),
+  modelOrder: z.array(z.string()).volatile(),
+  recentlyUsed: z.dict(z.number()).volatile(),
+}) as unknown as z<RouterConfigShape>
 
 /** The settings-page state view served by the API. */
 export interface ModelRouterState {
+  /**
+   * Whether this deployment can persist configuration. False (a profile
+   * without the host settings service) makes the page render read-only.
+   */
+  writable: boolean
   /** Whether provider switching is shown inside the composer model picker menu. */
   showQuickSwitch: boolean
   /** Whether model ids are matched with their leading vendor/ prefix ignored. */
@@ -83,28 +107,38 @@ export class ModelRouterService implements RouterFacts {
   }
   private inflight: Promise<RouterCatalog> | null = null
   private cachedAt = 0
-  private scope: SettingsScope<RouterConfigShape> | undefined
+  /** Optional host settings service; absent in profiles without one (no persistence). */
+  private settings: SettingsReplaceFace | undefined
+  /** Live config document (seeded from the entry config, updated on write). */
+  private configDoc: RouterConfigShape
   private registration: AdapterRegistrationHandle | undefined
 
   /** How long a built catalog is considered fresh before being rebuilt. */
   private readonly catalogTtlMs = 30_000
 
-  /** Debounced recent-use persistence (see noteModelUsed / flushUsage). */
-  private readonly usageFlushMs = 1_500
+  /**
+   * Debounced recent-use persistence (see noteModelUsed / flushUsage). Kept
+   * long on purpose: every persist writes the entry config, which restarts
+   * this plugin's entry, so usage bookkeeping must not stream live traffic.
+   */
+  private readonly usageFlushMs = 60_000
   private usageDebounce: ReturnType<typeof setTimeout> | null = null
   private pendingUsage: Record<string, number> = {}
   private usageFlushRunning = false
 
-  constructor(ctx: Context) {
+  constructor(ctx: Context, config: RouterConfigShape) {
     this.ctx = ctx
+    this.configDoc = normalizeConfig(config)
   }
 
-  /** Register settings + adapter and wire topology listeners. */
+  /** Register the settings seam + adapter and wire topology listeners. */
   start(): void {
     // Optional settings service: without one the router still routes
-    // (config falls back to catalog order) but cannot persist.
+    // (config falls back to catalog order) but cannot persist. The service's
+    // shape is only used through SettingsReplaceFace; there is no namespace
+    // registration to make on dsh >= 0.1.7.
     this.ctx.inject(['settings'], (sctx) => {
-      this.scope = sctx.settings.register(NS, RouterConfigSchema) as SettingsScope<RouterConfigShape>
+      this.settings = (sctx as unknown as { settings?: SettingsReplaceFace }).settings
     })
 
     const adapter = new ModelRouterAdapter(this)
@@ -121,14 +155,17 @@ export class ModelRouterService implements RouterFacts {
   }
 
   stop(): void {
-    // Flush any pending recent-use writes before the scope is torn down.
+    // Drop pending recent-use bookkeeping instead of flushing it: on dsh >=
+    // 0.1.7 every persist is an entry-config write, which reloads this plugin
+    // (teardown included), so writing from stop() would re-enter the loader
+    // while it is tearing this very entry down. The timestamps are best-effort
+    // ordering hints for the `recent` display mode, so losing the last
+    // debounce window is harmless.
     if (this.usageDebounce !== null) {
       clearTimeout(this.usageDebounce)
       this.usageDebounce = null
     }
-    if (Object.keys(this.pendingUsage).length > 0) {
-      void this.flushUsage()
-    }
+    this.pendingUsage = {}
     this.registration?.()
     this.registration = undefined
   }
@@ -140,12 +177,7 @@ export class ModelRouterService implements RouterFacts {
   }
 
   config(): RouterConfigShape {
-    if (this.scope === undefined) return EMPTY_CONFIG
-    try {
-      return normalizeConfig(this.scope.get())
-    } catch {
-      return EMPTY_CONFIG
-    }
+    return this.configDoc
   }
 
   providerNames(): ReadonlyMap<string, string> {
@@ -163,7 +195,7 @@ export class ModelRouterService implements RouterFacts {
    * write.
    */
   noteModelUsed(modelId: string): void {
-    if (this.scope === undefined) return
+    if (this.settings === undefined) return
     this.pendingUsage[modelId] = Date.now()
     if (this.usageDebounce !== null) return
     this.usageDebounce = setTimeout(() => {
@@ -179,9 +211,9 @@ export class ModelRouterService implements RouterFacts {
     const pending = this.pendingUsage
     this.pendingUsage = {}
     try {
-      if (this.scope === undefined || Object.keys(pending).length === 0) return
+      if (this.settings === undefined || Object.keys(pending).length === 0) return
       const current = this.config()
-      await this.scope.replace({
+      await this.writeConfig({
         ...current,
         recentlyUsed: { ...current.recentlyUsed, ...pending },
       })
@@ -233,12 +265,12 @@ export class ModelRouterService implements RouterFacts {
   /** Refresh (forced), then persist any config drift (migration, new/vanished models). */
   async refreshAndReconcile(): Promise<void> {
     const catalog = await this.refreshCatalog(true)
-    if (this.scope === undefined) return
+    if (this.settings === undefined) return
     const current = this.config()
     const { models, modelOrder, changed } = reconcileConfig(current, catalog.models)
     if (!changed) return
     try {
-      await this.scope.replace({
+      await this.writeConfig({
         ...current,
         models,
         ...(modelOrder === undefined ? {} : { modelOrder }),
@@ -264,6 +296,7 @@ export class ModelRouterService implements RouterFacts {
     const names = catalog.providerNames
     const creds = catalog.credentialConfigured
     return {
+      writable: this.settings !== undefined,
       showQuickSwitch: config.showQuickSwitch,
       ignoreModelIdPrefix: config.ignoreModelIdPrefix,
       modelSort: config.modelSort,
@@ -319,12 +352,9 @@ export class ModelRouterService implements RouterFacts {
 
   /** Toggle the composer quick route-switcher button (global, persisted). */
   async setShowQuickSwitch(value: boolean): Promise<void> {
-    if (this.scope === undefined) {
-      throw new Error('model-router: settings service is not available in this profile')
-    }
     const current = this.config()
     if (current.showQuickSwitch === value) return
-    await this.scope.replace({ ...current, showQuickSwitch: value })
+    await this.writeConfig({ ...current, showQuickSwitch: value })
   }
 
   /**
@@ -334,23 +364,17 @@ export class ModelRouterService implements RouterFacts {
    * turning on; split models re-initialize when turning off).
    */
   async setIgnoreModelIdPrefix(value: boolean): Promise<void> {
-    if (this.scope === undefined) {
-      throw new Error('model-router: settings service is not available in this profile')
-    }
     const current = this.config()
     if (current.ignoreModelIdPrefix === value) return
-    await this.scope.replace({ ...current, ignoreModelIdPrefix: value })
+    await this.writeConfig({ ...current, ignoreModelIdPrefix: value })
     await this.refreshAndReconcile()
   }
 
   /** Switch the model-list display order mode (global, persisted). */
   async setModelSort(mode: ModelSortMode): Promise<void> {
-    if (this.scope === undefined) {
-      throw new Error('model-router: settings service is not available in this profile')
-    }
     const current = this.config()
     if (current.modelSort === mode) return
-    await this.scope.replace({ ...current, modelSort: mode })
+    await this.writeConfig({ ...current, modelSort: mode })
   }
 
   /**
@@ -359,9 +383,6 @@ export class ModelRouterService implements RouterFacts {
    * always covers the live catalog.
    */
   async setModelOrder(order: string[]): Promise<void> {
-    if (this.scope === undefined) {
-      throw new Error('model-router: settings service is not available in this profile')
-    }
     await this.refreshCatalog()
     const ids = new Set(this.cached.models.map(model => model.id))
     const clean = order.filter(id => ids.has(id))
@@ -372,14 +393,20 @@ export class ModelRouterService implements RouterFacts {
     const sameOrder = clean.length === current.modelOrder.length
       && clean.every((id, at) => id === current.modelOrder[at])
     if (sameOrder) return
-    await this.scope.replace({ ...current, modelOrder: clean })
+    await this.writeConfig({ ...current, modelOrder: clean })
   }
 
-  private async persist(models: Record<string, { order: string[]; active: string }>): Promise<void> {
-    if (this.scope === undefined) {
+  /** Write the document through the host settings service (entry config). */
+  private async writeConfig(next: RouterConfigShape): Promise<void> {
+    if (this.settings === undefined) {
       throw new Error('model-router: settings service is not available in this profile')
     }
+    await this.settings.replace(NS, next, undefined)
+    this.configDoc = normalizeConfig(next)
+  }
+
+  private async persist(models: Record<string, { order: string[]; active: string }>): Promise<void> {
     const current = this.config()
-    await this.scope.replace({ ...current, models })
+    await this.writeConfig({ ...current, models })
   }
 }