@fonlan/dsh-model-router 0.1.0

package/src/server/service.ts

@@ -0,0 +1,239 @@
+/**
+ * The model-router service: settings persistence, live catalog cache, the
+ * virtual adapter registration, topology-triggered reconciliation, and the
+ * mutation actions the API surface exposes.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { settingsNamespace, type SettingsScope } from '@deepseek-ai/dsh-settings'
+import type { AdapterRegistrationHandle } from '@deepseek-ai/dsh-llm'
+import {
+  initialConfigFor,
+  normalizeConfig,
+  ROUTER_PROVIDER_ID,
+  ROUTER_SETTINGS_NS,
+  resolveActive,
+  setActive,
+  setOrder,
+  syncConfig,
+  type RouterConfigShape,
+} from '../shared/config.js'
+import { buildCatalog, type RouterCatalog } from './catalog.js'
+import { ModelRouterAdapter, type RouterFacts } from './adapter.js'
+
+export const NS = settingsNamespace(ROUTER_SETTINGS_NS)
+
+/** Settings document schema: one entry per model id. */
+export const RouterConfigSchema: z<RouterConfigShape> = z.object({
+  models: z.dict(z.object({
+    order: z.array(z.string()),
+    active: z.string(),
+  })),
+})
+
+const EMPTY_CONFIG: RouterConfigShape = { models: {} }
+
+/** The settings-page state view served by the API. */
+export interface ModelRouterState {
+  providers: Array<{ id: string; name: string; credentialConfigured: boolean }>
+  models: Array<{
+    id: string
+    /** Display name following the effective active provider. */
+    name: string
+    /** Effective active provider (never null while the model has providers). */
+    active: string | null
+    /** Effective provider preference order. */
+    order: string[]
+    providers: Array<{ id: string; name: string; credentialConfigured: boolean }>
+  }>
+}
+
+export class ModelRouterService implements RouterFacts {
+  private readonly ctx: Context
+  private cached: RouterCatalog = {
+    providers: [],
+    providerNames: new Map(),
+    models: [],
+    byId: new Map(),
+    credentialConfigured: new Map(),
+  }
+  private inflight: Promise<RouterCatalog> | null = null
+  private scope: SettingsScope<RouterConfigShape> | undefined
+  private registration: AdapterRegistrationHandle | undefined
+
+  constructor(ctx: Context) {
+    this.ctx = ctx
+  }
+
+  /** Register settings + 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.
+    this.ctx.inject(['settings'], (sctx) => {
+      this.scope = sctx.settings.register(NS, RouterConfigSchema) as SettingsScope<RouterConfigShape>
+    })
+
+    const adapter = new ModelRouterAdapter(this)
+    this.registration = this.ctx.llm.registerAdapter([ROUTER_PROVIDER_ID], adapter)
+
+    // Provider topology changes (added/removed providers, catalog swaps)
+    // invalidate the cache and reconcile the stored document.
+    this.ctx.on('llm/adapters-updated', () => {
+      void this.refreshAndReconcile()
+    })
+
+    // First load + reconcile: never block plugin startup on the catalog.
+    void this.refreshAndReconcile()
+  }
+
+  stop(): void {
+    this.registration?.()
+    this.registration = undefined
+  }
+
+  // ── RouterFacts ──────────────────────────────────────────────────────────
+
+  catalog(): { models: RouterCatalog['models']; byId: RouterCatalog['byId'] } {
+    return { models: this.cached.models, byId: this.cached.byId }
+  }
+
+  config(): RouterConfigShape {
+    if (this.scope === undefined) return EMPTY_CONFIG
+    try {
+      return normalizeConfig(this.scope.get())
+    } catch {
+      return EMPTY_CONFIG
+    }
+  }
+
+  providerNames(): ReadonlyMap<string, string> {
+    return this.cached.providerNames
+  }
+
+  llm() {
+    return this.ctx.llm
+  }
+
+  // ── catalog lifecycle ────────────────────────────────────────────────────
+
+  /** Rebuild the catalog (in-flight dedupe; failures keep the last good one). */
+  refreshCatalog(): Promise<RouterCatalog> {
+    if (this.inflight !== null) return this.inflight
+    this.inflight = buildCatalog(this.ctx)
+      .then((catalog) => {
+        this.cached = catalog
+        return catalog
+      })
+      .catch((error) => {
+        this.ctx.logger.warn(`model-router: catalog refresh failed: ${error instanceof Error ? error.message : String(error)}`)
+        return this.cached
+      })
+      .finally(() => {
+        this.inflight = null
+      })
+    return this.inflight
+  }
+
+  /** Refresh, then persist any config drift (new providers/models, vanish). */
+  async refreshAndReconcile(): Promise<void> {
+    const catalog = await this.refreshCatalog()
+    if (this.scope === undefined) return
+    const current = this.config()
+    const next = { ...current.models }
+    let changed = false
+    for (const model of catalog.models) {
+      const ids = model.providers.map(provider => provider.provider)
+      const result = syncConfig(current, model.id, ids)
+      if (result.changed) changed = true
+      for (const [id, entry] of Object.entries(result.models)) {
+        if (entry === undefined) delete next[id]
+        else next[id] = entry
+      }
+    }
+    // Drop stored entries whose model no longer exists anywhere.
+    for (const id of Object.keys(next)) {
+      if (!catalog.byId.has(id)) {
+        delete next[id]
+        changed = true
+      }
+    }
+    if (!changed) return
+    try {
+      await this.scope.replace({ models: next })
+    } catch (error) {
+      this.ctx.logger.warn(`model-router: reconcile persist failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  // ── actions ──────────────────────────────────────────────────────────────
+
+  /** Effective active provider for one model id (null when unroutable). */
+  activeFor(modelId: string): string | null {
+    const ids = this.cached.byId.get(modelId)?.providers.map(provider => provider.provider) ?? []
+    return resolveActive(this.config(), modelId, ids)
+  }
+
+  /** The complete state view for the settings page. */
+  async state(): Promise<ModelRouterState> {
+    await this.refreshCatalog()
+    const catalog = this.cached
+    const config = this.config()
+    const names = catalog.providerNames
+    const creds = catalog.credentialConfigured
+    return {
+      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) => {
+        const ids = model.providers.map(provider => provider.provider)
+        const stored = config.models[model.id] ?? initialConfigFor(ids)
+        const active = resolveActive(config, model.id, ids)
+        const activeEntry = model.providers.find(provider => provider.provider === active) ?? model.providers[0]
+        return {
+          id: model.id,
+          name: activeEntry?.name ?? model.id,
+          active,
+          order: stored?.order ?? [...ids],
+          providers: model.providers.map(provider => ({
+            id: provider.provider,
+            name: names.get(provider.provider) ?? provider.provider,
+            credentialConfigured: creds.get(provider.provider) ?? true,
+          })),
+        }
+      }),
+    }
+  }
+
+  /** Switch the active provider for one model (persisted, live on next request). */
+  async switchActive(modelId: string, providerId: string): Promise<void> {
+    await this.refreshCatalog()
+    const ids = this.cached.byId.get(modelId)?.providers.map(provider => provider.provider)
+    if (ids === undefined || ids.length === 0) {
+      throw new Error(`model-router: model "${modelId}" is not served by any provider`)
+    }
+    const { models, changed } = setActive(this.config(), modelId, providerId, ids)
+    if (!changed) return
+    await this.persist(models)
+  }
+
+  /** Replace the preference order for one model (active left untouched). */
+  async reorder(modelId: string, order: string[]): Promise<void> {
+    await this.refreshCatalog()
+    const ids = this.cached.byId.get(modelId)?.providers.map(provider => provider.provider)
+    if (ids === undefined || ids.length === 0) {
+      throw new Error(`model-router: model "${modelId}" is not served by any provider`)
+    }
+    const { models, changed } = setOrder(this.config(), modelId, order, ids)
+    if (!changed) return
+    await this.persist(models)
+  }
+
+  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')
+    }
+    await this.scope.replace({ models })
+  }
+}

package/src/shared/config.ts

@@ -0,0 +1,231 @@
+/**
+ * @fonlan/dsh-model-router shared routing core — pure functions, no side
+ * effects, unit-tested in test/config.test.ts and shared verbatim between the
+ * server half (route resolution at request time) and the client bundle
+ * (settings page rendering).
+ *
+ * Decided semantics (grilling session, all recommendations accepted):
+ * - Strict merge: models are merged across providers by exact model id only.
+ * - Per-model provider config: an order[] (future auto-failover preference)
+ *   plus an independent active provider (what requests actually route to).
+ * - First-seen provider order: for a never-configured model the initial
+ *   order is provider discovery order and the initial active is its head.
+ * - Vanished providers: pruned from order; when active vanishes, fall back to
+ *   the first remaining provider automatically.
+ * - New providers for a known model: appended at the end of order; active
+ *   untouched.
+ */
+
+/** One provider's view of one model. */
+export interface ProviderModelInfo {
+  /** Provider id the model belongs to. */
+  provider: string
+  /** Provider-local model id (== merged model id, strict merge). */
+  id: string
+  /** Provider-local display name. */
+  name: string
+  /** Provider-local context window (tokens), when advertised. */
+  contextWindow?: number
+  /** Provider-local max output tokens, when advertised. */
+  maxTokens?: number
+}
+
+/** One configured provider as discovered from the host. */
+export interface ProviderInfo {
+  id: string
+  /** Provider display name when advertised. */
+  name?: string
+  models: Array<Omit<ProviderModelInfo, 'provider'>>
+}
+
+/** One merged model across all providers (strict id merge). */
+export interface MergedModel {
+  id: string
+  /** Per-provider entries in provider discovery order. */
+  providers: ProviderModelInfo[]
+}
+
+/** Router configuration for one model. */
+export interface RouterModelConfig {
+  /** Provider ids in preference order (future auto-failover). */
+  order: string[]
+  /** The provider requests currently route to. */
+  active: string
+}
+
+/** The whole router config document. */
+export interface RouterConfigShape {
+  models: Record<string, RouterModelConfig>
+}
+
+export const ROUTER_PROVIDER_ID = 'model-router'
+export const ROUTER_SETTINGS_NS = 'model-router'
+
+/** Merge every provider's models into one entry per exact model id. */
+export function mergeModels(providers: readonly ProviderInfo[]): MergedModel[] {
+  const byId = new Map<string, MergedModel>()
+  for (const provider of providers) {
+    for (const model of provider.models) {
+      let merged = byId.get(model.id)
+      if (merged === undefined) {
+        merged = { id: model.id, providers: [] }
+        byId.set(model.id, merged)
+      }
+      merged.providers.push({
+        provider: provider.id,
+        id: model.id,
+        name: model.name,
+        contextWindow: model.contextWindow,
+        maxTokens: model.maxTokens,
+      })
+    }
+  }
+  return [...byId.values()]
+}
+
+/** The provider view a merged model should display for (follows active). */
+export function displayProvider(
+  merged: MergedModel,
+  active: string | undefined,
+): ProviderModelInfo | null {
+  if (merged.providers.length === 0) return null
+  return merged.providers.find(p => p.provider === active) ?? merged.providers[0]
+}
+
+/** 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
+  return { order: [...providerIds], active: providerIds[0] }
+}
+
+/**
+ * Effective active provider for a model id.
+ *
+ * Rules: a stored active still present in the catalog wins; otherwise the
+ * first stored order entry still present wins; otherwise the first provider
+ * of the catalog wins; an empty catalog yields null.
+ */
+export function resolveActive(
+  config: RouterConfigShape,
+  modelId: string,
+  catalogProviderIds: readonly string[],
+): string | null {
+  if (catalogProviderIds.length === 0) return null
+  const stored = config.models[modelId]
+  if (stored !== undefined) {
+    if (catalogProviderIds.includes(stored.active)) return stored.active
+    const firstRemaining = stored.order.find(id => catalogProviderIds.includes(id))
+    if (firstRemaining !== undefined) return firstRemaining
+  }
+  return catalogProviderIds[0]
+}
+
+/**
+ * Reconcile one model's config against the live catalog: prune vanished
+ * providers, append newly discovered ones, and repair a vanished active by
+ * falling back to the first remaining provider. Returns the new config, or
+ * undefined when the catalog leaves nothing to route to.
+ */
+export function syncConfig(
+  config: RouterConfigShape,
+  modelId: string,
+  catalogProviderIds: readonly string[],
+): { models: Record<string, RouterModelConfig>; changed: boolean } {
+  const next = { ...config.models }
+  let changed = false
+
+  const existing = next[modelId]
+  if (catalogProviderIds.length === 0) {
+    if (existing !== undefined) {
+      delete next[modelId]
+      changed = true
+    }
+    return { models: next, changed }
+  }
+
+  if (existing === undefined) {
+    const initial = initialConfigFor(catalogProviderIds)
+    if (initial !== null) {
+      next[modelId] = initial
+      changed = true
+    }
+    return { models: next, changed }
+  }
+
+  const catalog = new Set(catalogProviderIds)
+  const order = existing.order.filter(id => catalog.has(id))
+  if (order.length !== existing.order.length) changed = true
+  for (const id of catalogProviderIds) {
+    if (!order.includes(id)) {
+      order.push(id)
+      changed = true
+    }
+  }
+  let active = existing.active
+  if (!catalog.has(active)) {
+    active = order[0]
+    changed = true
+  }
+  if (changed) {
+    next[modelId] = { order, active }
+  }
+  return { models: next, changed }
+}
+
+/** Switch a model's active provider (no-op when already active). */
+export function setActive(
+  config: RouterConfigShape,
+  modelId: string,
+  providerId: string,
+  catalogProviderIds: readonly string[],
+): { models: Record<string, RouterModelConfig>; changed: boolean } {
+  if (!catalogProviderIds.includes(providerId)) {
+    throw new Error(`provider ${providerId} is not in the catalog for model ${modelId}`)
+  }
+  const synced = syncConfig(config, modelId, catalogProviderIds)
+  const next = synced.models
+  const entry = next[modelId]
+  if (entry === undefined) return { models: next, changed: synced.changed }
+  if (entry.active === providerId) return { models: next, changed: synced.changed }
+  next[modelId] = { ...entry, active: providerId }
+  return { models: next, changed: true }
+}
+
+/** Replace a model's provider preference order (active left untouched). */
+export function setOrder(
+  config: RouterConfigShape,
+  modelId: string,
+  order: readonly string[],
+  catalogProviderIds: readonly string[],
+): { models: Record<string, RouterModelConfig>; changed: boolean } {
+  const catalog = new Set(catalogProviderIds)
+  const clean = order.filter(id => catalog.has(id))
+  for (const id of catalogProviderIds) {
+    if (!clean.includes(id)) clean.push(id)
+  }
+  const synced = syncConfig(config, modelId, catalogProviderIds)
+  const next = synced.models
+  const entry = next[modelId]
+  if (entry === undefined) return { models: next, changed: synced.changed }
+  const sameOrder = entry.order.length === clean.length && entry.order.every((id, i) => id === clean[i])
+  if (sameOrder) return { models: next, changed: synced.changed }
+  next[modelId] = { ...entry, order: [...clean] }
+  return { models: next, changed: true }
+}
+
+/** Shape-validate an unknown value as a RouterConfigShape (lenient). */
+export function normalizeConfig(value: unknown): RouterConfigShape {
+  const models: Record<string, RouterModelConfig> = {}
+  if (typeof value !== 'object' || value === null) return { models }
+  const raw = (value as { models?: unknown }).models
+  if (typeof raw !== 'object' || raw === null) return { models }
+  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 }
+    const order = Array.isArray(e.order) ? e.order.filter((x): x is string => typeof x === 'string') : []
+    const active = typeof e.active === 'string' ? e.active : order[0] ?? ''
+    if (active === '') continue
+    models[id] = { order, active }
+  }
+  return { models }
+}