@fonlan/dsh-model-router 0.3.0 → 0.3.3

package/src/server/service.ts

@@ -16,6 +16,8 @@ import {
   resolveActive,
   setActive,
   setOrder,
+  sortModelsForList,
+  type ModelSortMode,
   type RouterConfigShape,
 } from '../shared/config.js'
 import { buildCatalog, type RouterCatalog } from './catalog.js'
@@ -33,16 +35,30 @@ export const RouterConfigSchema: z<RouterConfigShape> = z.object({
   // 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 }
+const EMPTY_CONFIG: RouterConfigShape = {
+  models: {},
+  showQuickSwitch: true,
+  ignoreModelIdPrefix: true,
+  modelSort: 'custom',
+  modelOrder: [],
+  recentlyUsed: {},
+}
 
 /** The settings-page state view served by the API. */
 export interface ModelRouterState {
-  /** Whether the composer quick route-switcher button is enabled. */
+  /** Whether provider switching is shown inside the composer model picker menu. */
   showQuickSwitch: boolean
   /** Whether model ids are matched with their leading vendor/ prefix ignored. */
   ignoreModelIdPrefix: boolean
+  /** The model-list display order mode (custom | name | recent). */
+  modelSort: ModelSortMode
+  /** Explicit model id order for custom mode (display order). */
+  modelOrder: string[]
   providers: Array<{ id: string; name: string; credentialConfigured: boolean }>
   models: Array<{
     id: string
@@ -66,9 +82,19 @@ export class ModelRouterService implements RouterFacts {
     credentialConfigured: new Map(),
   }
   private inflight: Promise<RouterCatalog> | null = null
+  private cachedAt = 0
   private scope: SettingsScope<RouterConfigShape> | undefined
   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
+  private usageDebounce: ReturnType<typeof setTimeout> | null = null
+  private pendingUsage: Record<string, number> = {}
+  private usageFlushRunning = false
+
   constructor(ctx: Context) {
     this.ctx = ctx
   }
@@ -95,6 +121,14 @@ export class ModelRouterService implements RouterFacts {
   }
 
   stop(): void {
+    // Flush any pending recent-use writes before the scope is torn down.
+    if (this.usageDebounce !== null) {
+      clearTimeout(this.usageDebounce)
+      this.usageDebounce = null
+    }
+    if (Object.keys(this.pendingUsage).length > 0) {
+      void this.flushUsage()
+    }
     this.registration?.()
     this.registration = undefined
   }
@@ -122,14 +156,68 @@ export class ModelRouterService implements RouterFacts {
     return this.ctx.llm
   }
 
+  /**
+   * Record one model request for the `recent` display order. Fire-and-forget
+   * (the adapter never awaits it): timestamps accumulate in memory and are
+   * persisted debounced, so a burst of requests coalesces into one settings
+   * write.
+   */
+  noteModelUsed(modelId: string): void {
+    if (this.scope === undefined) return
+    this.pendingUsage[modelId] = Date.now()
+    if (this.usageDebounce !== null) return
+    this.usageDebounce = setTimeout(() => {
+      this.usageDebounce = null
+      void this.flushUsage()
+    }, this.usageFlushMs)
+  }
+
+  /** Persist accumulated usage timestamps (merging with any concurrent writes). */
+  private async flushUsage(): Promise<void> {
+    if (this.usageFlushRunning) return
+    this.usageFlushRunning = true
+    const pending = this.pendingUsage
+    this.pendingUsage = {}
+    try {
+      if (this.scope === undefined || Object.keys(pending).length === 0) return
+      const current = this.config()
+      await this.scope.replace({
+        ...current,
+        recentlyUsed: { ...current.recentlyUsed, ...pending },
+      })
+    } catch (error) {
+      // Re-queue the failed batch so a transient write failure does not lose
+      // usage history; the next request retries it.
+      this.pendingUsage = { ...pending, ...this.pendingUsage }
+      this.ctx.logger.warn(`model-router: usage persist failed: ${error instanceof Error ? error.message : String(error)}`)
+    } finally {
+      this.usageFlushRunning = false
+    }
+  }
+
   // ── catalog lifecycle ────────────────────────────────────────────────────
 
-  /** Rebuild the catalog (in-flight dedupe; failures keep the last good one). */
-  refreshCatalog(): Promise<RouterCatalog> {
+  /**
+   * Return the live catalog, rebuilding it only when it is stale (older than
+   * `catalogTtlMs`) or `force` is set. Concurrent callers share one in-flight
+   * build; a failed build keeps the last good catalog.
+   *
+   * The TTL is what keeps the composer quick-switcher snappy: every
+   * `state()` RPC goes through here, and without a cache each one rebuilt the
+   * catalog — including per-provider `listModels` network calls — which is
+   * what made the button gray out (routerLoading) for the whole duration.
+   * Topology events (`llm/adapters-updated`) and explicit user refreshes pass
+   * `force` so the cache never hides real changes.
+   */
+  refreshCatalog(force = false): Promise<RouterCatalog> {
+    if (!force && this.inflight === null && Date.now() - this.cachedAt < this.catalogTtlMs) {
+      return Promise.resolve(this.cached)
+    }
     if (this.inflight !== null) return this.inflight
     this.inflight = buildCatalog(this.ctx, this.config().ignoreModelIdPrefix)
       .then((catalog) => {
         this.cached = catalog
+        this.cachedAt = Date.now()
         return catalog
       })
       .catch((error) => {
@@ -142,18 +230,18 @@ export class ModelRouterService implements RouterFacts {
     return this.inflight
   }
 
-  /** Refresh, then persist any config drift (migration, new/vanished models). */
+  /** Refresh (forced), then persist any config drift (migration, new/vanished models). */
   async refreshAndReconcile(): Promise<void> {
-    const catalog = await this.refreshCatalog()
+    const catalog = await this.refreshCatalog(true)
     if (this.scope === undefined) return
     const current = this.config()
-    const { models, changed } = reconcileConfig(current, catalog.models)
+    const { models, modelOrder, changed } = reconcileConfig(current, catalog.models)
     if (!changed) return
     try {
       await this.scope.replace({
+        ...current,
         models,
-        showQuickSwitch: current.showQuickSwitch,
-        ignoreModelIdPrefix: current.ignoreModelIdPrefix,
+        ...(modelOrder === undefined ? {} : { modelOrder }),
       })
     } catch (error) {
       this.ctx.logger.warn(`model-router: reconcile persist failed: ${error instanceof Error ? error.message : String(error)}`)
@@ -178,12 +266,14 @@ export class ModelRouterService implements RouterFacts {
     return {
       showQuickSwitch: config.showQuickSwitch,
       ignoreModelIdPrefix: config.ignoreModelIdPrefix,
+      modelSort: config.modelSort,
+      modelOrder: config.modelOrder,
       providers: catalog.providers.map(provider => ({
         id: provider.id,
         name: names.get(provider.id) ?? provider.id,
         credentialConfigured: creds.get(provider.id) ?? true,
       })),
-      models: catalog.models.map((model) => {
+      models: sortModelsForList(catalog.models, config).map((model) => {
         const ids = model.providers.map(provider => provider.provider)
         const stored = config.models[model.id] ?? initialConfigFor(ids)
         const active = resolveActive(config, model.id, ids)
@@ -234,11 +324,7 @@ export class ModelRouterService implements RouterFacts {
     }
     const current = this.config()
     if (current.showQuickSwitch === value) return
-    await this.scope.replace({
-      models: current.models,
-      showQuickSwitch: value,
-      ignoreModelIdPrefix: current.ignoreModelIdPrefix,
-    })
+    await this.scope.replace({ ...current, showQuickSwitch: value })
   }
 
   /**
@@ -253,23 +339,47 @@ export class ModelRouterService implements RouterFacts {
     }
     const current = this.config()
     if (current.ignoreModelIdPrefix === value) return
-    await this.scope.replace({
-      models: current.models,
-      showQuickSwitch: current.showQuickSwitch,
-      ignoreModelIdPrefix: value,
-    })
+    await this.scope.replace({ ...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 })
+  }
+
+  /**
+   * Replace the explicit custom model order (global, persisted). Vanished
+   * ids are pruned and missing catalog models appended, so the stored order
+   * 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))
+    for (const model of this.cached.models) {
+      if (!clean.includes(model.id)) clean.push(model.id)
+    }
+    const current = this.config()
+    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 })
+  }
+
   private async persist(models: Record<string, { order: string[]; active: string }>): Promise<void> {
     if (this.scope === undefined) {
       throw new Error('model-router: settings service is not available in this profile')
     }
     const current = this.config()
-    await this.scope.replace({
-      models,
-      showQuickSwitch: current.showQuickSwitch,
-      ignoreModelIdPrefix: current.ignoreModelIdPrefix,
-    })
+    await this.scope.replace({ ...current, models })
   }
 }

package/src/shared/config.ts

@@ -64,12 +64,28 @@ export interface RouterModelConfig {
   active: string
 }
 
+/**
+ * How the router orders the model list it advertises to the host model
+ * picker (the `model-router` group in DSH's model selection box).
+ *
+ * - `custom`: the explicit `modelOrder` array wins; models absent from it are
+ *   appended in catalog (first-seen) order.
+ * - `name`: models sorted by their display name (active provider's name),
+ *   falling back to the merged id.
+ * - `recent`: models sorted by most-recently-used first (timestamp desc);
+ *   never-used models come last in catalog order.
+ *
+ * Absent/unknown documents normalize to `custom` (the pre-existing catalog
+ * order, so upgrading is a no-op until the user changes it).
+ */
+export type ModelSortMode = 'custom' | 'name' | 'recent'
+
 /** The whole router config document. */
 export interface RouterConfigShape {
   models: Record<string, RouterModelConfig>
   /**
-   * Whether the quick route-switcher button is shown beside the composer
-   * model selector (settings → 模型路由 → 显示快速路由切换按钮). Stored
+   * Whether the provider switching entry is shown inside the composer model
+   * picker menu (settings → 模型路由 → 在模型选择菜单中显示提供商切换). Stored
    * globally; absent/unknown documents normalize to `true`.
    */
   showQuickSwitch: boolean
@@ -81,6 +97,23 @@ export interface RouterConfigShape {
    * `true`.
    */
   ignoreModelIdPrefix: boolean
+  /**
+   * The model-list display order mode (settings → 模型路由 → 模型显示顺序).
+   * Absent/unknown documents normalize to `custom`.
+   */
+  modelSort: ModelSortMode
+  /**
+   * Explicit model id order for `custom` mode, in display order. Kept
+   * reconciled against the catalog (vanished ids pruned, new ids appended).
+   * Absent/unknown documents normalize to `[]`.
+   */
+  modelOrder: string[]
+  /**
+   * Merged model id → last-use epoch millis, for `recent` mode. Written by
+   * the router adapter whenever a model request streams. Absent/unknown
+   * documents normalize to `{}`.
+   */
+  recentlyUsed: Record<string, number>
 }
 
 export const ROUTER_PROVIDER_ID = 'model-router'
@@ -152,6 +185,59 @@ export function displayProvider(
   return merged.providers.find(p => p.provider === active) ?? merged.providers[0]
 }
 
+/** The display name a merged model advertises (active provider's name). */
+export function displayNameOf(
+  model: MergedModel,
+  config: RouterConfigShape,
+): string {
+  const ids = model.providers.map(provider => provider.provider)
+  const active = resolveActive(config, model.id, ids)
+  return displayProvider(model, active ?? undefined)?.name ?? model.id
+}
+
+/**
+ * Order the merged catalog the way the model picker should list it, per the
+ * configured `modelSort` mode. Always returns a permutation of `models`
+ * (never drops or duplicates entries).
+ *
+ * - `custom`: `config.modelOrder` first (in stored order), then any model not
+ *   present in it, in catalog order.
+ * - `name`: display-name ascending (numeric-aware, case-insensitive), ties
+ *   keep catalog order (stable sort).
+ * - `recent`: most-recently-used first; never-used models sink to the tail in
+ *   catalog order. Ties (equal timestamps, or both unused) keep catalog
+ *   order (stable sort).
+ */
+export function sortModelsForList(
+  models: readonly MergedModel[],
+  config: RouterConfigShape,
+): MergedModel[] {
+  if (config.modelSort === 'name') {
+    const byName = new Map(models.map(model => [model, displayNameOf(model, config)]))
+    return [...models].sort((left, right) =>
+      byName.get(left)!.localeCompare(byName.get(right)!, undefined, { numeric: true, sensitivity: 'base' }),
+    )
+  }
+  if (config.modelSort === 'recent') {
+    const recent = config.recentlyUsed ?? {}
+    return [...models].sort((left, right) =>
+      (recent[right.id] ?? -Infinity) - (recent[left.id] ?? -Infinity),
+    )
+  }
+  // custom: explicit order first (deduped), then the catalog-order tail
+  const listed: MergedModel[] = []
+  const seen = new Set<string>()
+  for (const id of config.modelOrder ?? []) {
+    if (seen.has(id)) continue
+    const model = models.find(candidate => candidate.id === id)
+    if (model === undefined) continue
+    seen.add(id)
+    listed.push(model)
+  }
+  const tail = models.filter(model => !seen.has(model.id))
+  return [...listed, ...tail]
+}
+
 /** Initial config for a model the user never configured: first in order wins. */
 export function initialConfigFor(providerIds: readonly string[]): RouterModelConfig | null {
   if (providerIds.length === 0) return null
@@ -256,11 +342,14 @@ function sameModels(a: Record<string, RouterModelConfig>, b: Record<string, Rout
  * for `active`, and `order` becomes the deduped union in exact-key-first
  * order. Stored keys no longer mapping to any merged model are dropped (this
  * also covers turning the flag off — split models re-initialize fresh).
+ *
+ * `modelOrder` (custom display order) is reconciled the same way: vanished
+ * ids are pruned, newly discovered models are appended in catalog order.
  */
 export function reconcileConfig(
   config: RouterConfigShape,
   models: readonly MergedModel[],
-): { models: Record<string, RouterModelConfig>; changed: boolean } {
+): { models: Record<string, RouterModelConfig>; modelOrder: string[] | undefined; changed: boolean } {
   // stored key → merged id it belongs to (exact key wins; prefixed raw keys
   // map to their stripped merged id only while the flag is on)
   const keyToMerged = new Map<string, string>()
@@ -306,7 +395,31 @@ export function reconcileConfig(
     if (entry !== undefined) next[model.id] = entry
   }
 
-  return { models: next, changed: !sameModels(next, config.models) }
+  // Reconcile the custom display order against the live catalog: prune
+  // vanished ids, append newly discovered models in catalog order. Documents
+  // that predate the field (modelOrder undefined) keep it absent — the
+  // service's normalizeConfig materializes it on the next write, and an old
+  // document must not report drift merely because the field is missing.
+  const storedOrder = config.modelOrder
+  let modelOrder: string[] | undefined
+  let orderChanged = false
+  if (storedOrder !== undefined) {
+    const catalogIds = new Set(models.map(model => model.id))
+    modelOrder = storedOrder.filter(id => catalogIds.has(id))
+    orderChanged = modelOrder.length !== storedOrder.length
+    for (const model of models) {
+      if (!modelOrder.includes(model.id)) {
+        modelOrder.push(model.id)
+        orderChanged = true
+      }
+    }
+  }
+
+  return {
+    models: next,
+    modelOrder,
+    changed: !sameModels(next, config.models) || orderChanged,
+  }
 }
 
 /** Switch a model's active provider (no-op when already active). */
@@ -354,13 +467,34 @@ export function setOrder(
 export function normalizeConfig(value: unknown): RouterConfigShape {
   const models: Record<string, RouterModelConfig> = {}
   if (typeof value !== 'object' || value === null) {
-    return { models, showQuickSwitch: true, ignoreModelIdPrefix: true }
+    return { models, showQuickSwitch: true, ignoreModelIdPrefix: true, modelSort: 'custom', modelOrder: [], recentlyUsed: {} }
+  }
+  const root = value as {
+    models?: unknown
+    showQuickSwitch?: unknown
+    ignoreModelIdPrefix?: unknown
+    modelSort?: unknown
+    modelOrder?: unknown
+    recentlyUsed?: unknown
   }
-  const root = value as { models?: unknown; showQuickSwitch?: unknown; ignoreModelIdPrefix?: unknown }
   const showQuickSwitch = root.showQuickSwitch !== false
   const ignoreModelIdPrefix = root.ignoreModelIdPrefix !== false
+  const modelSort: ModelSortMode = root.modelSort === 'name' || root.modelSort === 'recent'
+    ? root.modelSort
+    : 'custom'
+  const modelOrder = Array.isArray(root.modelOrder)
+    ? root.modelOrder.filter((x): x is string => typeof x === 'string')
+    : []
+  const recentlyUsed: Record<string, number> = {}
+  if (typeof root.recentlyUsed === 'object' && root.recentlyUsed !== null) {
+    for (const [id, ts] of Object.entries(root.recentlyUsed as Record<string, unknown>)) {
+      if (typeof ts === 'number' && Number.isFinite(ts)) recentlyUsed[id] = ts
+    }
+  }
   const raw = root.models
-  if (typeof raw !== 'object' || raw === null) return { models, showQuickSwitch, ignoreModelIdPrefix }
+  if (typeof raw !== 'object' || raw === null) {
+    return { models, showQuickSwitch, ignoreModelIdPrefix, modelSort, modelOrder, recentlyUsed }
+  }
   for (const [id, entry] of Object.entries(raw as Record<string, unknown>)) {
     if (typeof entry !== 'object' || entry === null) continue
     const e = entry as { order?: unknown; active?: unknown }
@@ -369,5 +503,5 @@ export function normalizeConfig(value: unknown): RouterConfigShape {
     if (active === '') continue
     models[id] = { order, active }
   }
-  return { models, showQuickSwitch, ignoreModelIdPrefix }
+  return { models, showQuickSwitch, ignoreModelIdPrefix, modelSort, modelOrder, recentlyUsed }
 }

package/src/client/route-switcher.css

@@ -1,136 +0,0 @@
-/* Quick provider route control beside DSH's composer model seat. */
-.mr-route-anchor {
-  /* Menu's wrapper span: never let the row crush the trigger. */
-  flex: none;
-  min-width: 0;
-}
-
-.mr-route-trigger {
-  min-width: 0;
-  max-width: 180px;
-  height: 28px;
-  display: flex;
-  align-items: center;
-  gap: 2px;
-  padding: 0 6px;
-  border: none;
-  border-radius: 24px;
-  color: var(--dsw-alias-label-secondary);
-  background: transparent;
-  cursor: pointer;
-  font: inherit;
-  font-size: 12px;
-  font-weight: 500;
-  line-height: 20px;
-  outline: none;
-}
-
-.mr-route-trigger:hover:not(:disabled) {
-  background: var(--dsw-alias-interactive-bg-hover);
-}
-
-.mr-route-trigger:focus-visible {
-  box-shadow: 0 0 0 2px var(--dsw-alias-border-l3);
-}
-
-.mr-route-trigger:disabled {
-  color: var(--dsw-alias-label-dimmed);
-  cursor: default;
-  opacity: 0.7;
-}
-
-.mr-route-trigger-label {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.mr-route-trigger-chevron {
-  color: var(--dsw-alias-label-caption);
-  flex: none;
-  transition: transform 0.12s;
-}
-
-.mr-route-trigger[aria-expanded="true"] .mr-route-trigger-chevron {
-  transform: rotate(180deg);
-}
-
-.mr-route-item-copy {
-  min-width: 0;
-  display: flex;
-  align-items: baseline;
-  gap: 6px;
-}
-
-.mr-route-item-name {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.mr-route-item-note {
-  flex: none;
-  color: var(--dsw-alias-label-tertiary);
-  font-size: 11px;
-  line-height: 16px;
-}
-
-/*
- * Mobile portrait: the composer row is an inline-size container. Keep the
- * fixed control row intact — attachment, permission, provider (icon-only),
- * context meter, send — and let the model seat absorb the remaining width.
- * The breakpoint matches DSH's own narrow-composer rule (<=460px).
- */
-@container (width <= 460px) {
-  .mr-route-anchor {
-    flex: 0 0 auto;
-  }
-
-  .mr-route-trigger {
-    /* The trigger now carries globe + chevron, so let it size naturally
-       instead of forcing a 28px circle that could overflow the row. */
-    height: 28px;
-    padding: 4px 6px;
-    justify-content: center;
-    border-radius: 999px;
-  }
-
-  /*
-   * Make the composer's trailing group (the parent of our [data-slot] right
-   * wrapper) shrinkable on narrow rows so the globe/chevron trigger never
-   * spills left over the permission control. The model seat inside it
-   * absorbs the compression (flex 1 1 0, min-width 0 below).
-   */
-  div:has(> [data-slot="conversation.input.right"]) {
-    flex: 1 1 auto;
-    min-width: 0;
-    justify-content: flex-end;
-    /* Mirror the trailing group's internal gap (12px) so the provider
-       trigger has equal spacing to the permission button on its left and
-       the model seat on its right. */
-    margin-left: 12px;
-  }
-
-  .mr-route-trigger-label {
-    display: none;
-  }
-
-  /*
-   * The model seat: each slot is wrapped in a display:contents
-   * [data-slot] div, so the ModelSelect root div (the real flex item of the
-   * composer row) is [data-slot="conversation.input.model"] > *. Give it
-   * the remaining row width; the other controls keep fixed sizes.
-   */
-  [data-slot="conversation.input.right"] + [data-slot="conversation.input.model"] > * {
-    flex: 1 1 0;
-    min-width: 0;
-    max-width: 100%;
-  }
-
-  [data-slot="conversation.input.right"] + [data-slot="conversation.input.model"] [aria-haspopup="menu"] {
-    width: 100%;
-    max-width: 100%;
-  }
-}