@fonlan/dsh-model-router 0.1.0

package/lib/types/server/rpc.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ModelRouterService } from './service.js';
+export declare function registerApiRoutes(ctx: Context, service: ModelRouterService): () => void;

package/lib/types/server/service.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { type RouterConfigShape } from '../shared/config.js';
+import { type RouterCatalog } from './catalog.js';
+import { type RouterFacts } from './adapter.js';
+export declare const NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Settings document schema: one entry per model id. */
+export declare const RouterConfigSchema: z<RouterConfigShape>;
+/** 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 declare class ModelRouterService implements RouterFacts {
+    private readonly ctx;
+    private cached;
+    private inflight;
+    private scope;
+    private registration;
+    constructor(ctx: Context);
+    /** Register settings + adapter and wire topology listeners. */
+    start(): void;
+    stop(): void;
+    catalog(): {
+        models: RouterCatalog['models'];
+        byId: RouterCatalog['byId'];
+    };
+    config(): RouterConfigShape;
+    providerNames(): ReadonlyMap<string, string>;
+    llm(): import("@deepseek-ai/dsh-llm").LlmRuntime;
+    /** Rebuild the catalog (in-flight dedupe; failures keep the last good one). */
+    refreshCatalog(): Promise<RouterCatalog>;
+    /** Refresh, then persist any config drift (new providers/models, vanish). */
+    refreshAndReconcile(): Promise<void>;
+    /** Effective active provider for one model id (null when unroutable). */
+    activeFor(modelId: string): string | null;
+    /** The complete state view for the settings page. */
+    state(): Promise<ModelRouterState>;
+    /** Switch the active provider for one model (persisted, live on next request). */
+    switchActive(modelId: string, providerId: string): Promise<void>;
+    /** Replace the preference order for one model (active left untouched). */
+    reorder(modelId: string, order: string[]): Promise<void>;
+    private persist;
+}

package/lib/types/shared/config.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @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 declare const ROUTER_PROVIDER_ID = "model-router";
+export declare const ROUTER_SETTINGS_NS = "model-router";
+/** Merge every provider's models into one entry per exact model id. */
+export declare function mergeModels(providers: readonly ProviderInfo[]): MergedModel[];
+/** The provider view a merged model should display for (follows active). */
+export declare function displayProvider(merged: MergedModel, active: string | undefined): ProviderModelInfo | null;
+/** Initial config for a model the user never configured: first in order wins. */
+export declare function initialConfigFor(providerIds: readonly string[]): RouterModelConfig | null;
+/**
+ * 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 declare function resolveActive(config: RouterConfigShape, modelId: string, catalogProviderIds: readonly string[]): string | null;
+/**
+ * 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 declare function syncConfig(config: RouterConfigShape, modelId: string, catalogProviderIds: readonly string[]): {
+    models: Record<string, RouterModelConfig>;
+    changed: boolean;
+};
+/** Switch a model's active provider (no-op when already active). */
+export declare function setActive(config: RouterConfigShape, modelId: string, providerId: string, catalogProviderIds: readonly string[]): {
+    models: Record<string, RouterModelConfig>;
+    changed: boolean;
+};
+/** Replace a model's provider preference order (active left untouched). */
+export declare function setOrder(config: RouterConfigShape, modelId: string, order: readonly string[], catalogProviderIds: readonly string[]): {
+    models: Record<string, RouterModelConfig>;
+    changed: boolean;
+};
+/** Shape-validate an unknown value as a RouterConfigShape (lenient). */
+export declare function normalizeConfig(value: unknown): RouterConfigShape;

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@fonlan/dsh-model-router",
+  "version": "0.1.0",
+  "description": "DSH plugin: a virtual model-router provider that aggregates every configured provider and model, routes each request to the model's currently active provider, and ships a settings page for per-model provider ordering and switching.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fonlan/dsh-model-router.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fonlan/dsh-model-router/issues"
+  },
+  "homepage": "https://github.com/fonlan/dsh-model-router",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "model-router",
+    "provider",
+    "routing"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "vitest": "^3.2.0"
+  },
+  "packageManager": "pnpm@11.21.0"
+}

package/src/client/api.ts

@@ -0,0 +1,56 @@
+/** Client transport for the model-router settings API. */
+export interface RouterProviderView {
+  id: string
+  name: string
+  credentialConfigured: boolean
+}
+
+export interface RouterModelView {
+  id: string
+  name: string
+  active: string | null
+  order: string[]
+  providers: RouterProviderView[]
+}
+
+export interface ModelRouterState {
+  providers: RouterProviderView[]
+  models: RouterModelView[]
+}
+
+export class ModelRouterApiError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(message)
+  }
+}
+
+async function call<T>(method: string, payload: Record<string, unknown> = {}): Promise<T> {
+  let response: Response
+  try {
+    response = await fetch(`/plugins/@fonlan/dsh-model-router/api/${method}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+  } catch (error) {
+    throw new ModelRouterApiError('network', error instanceof Error ? error.message : String(error))
+  }
+  const parsed: { ok?: boolean; value?: unknown; error?: { code?: string; message?: string } } | null
+    = await response.json().catch(() => null)
+  if (!response.ok || parsed === null || parsed.ok !== true || parsed.value === undefined) {
+    throw new ModelRouterApiError(
+      parsed?.error?.code ?? 'http',
+      parsed?.error?.message ?? `HTTP ${response.status}`,
+    )
+  }
+  return parsed.value as T
+}
+
+export const api = {
+  state: () => call<ModelRouterState>('state'),
+  switchActive: (modelId: string, providerId: string) =>
+    call<ModelRouterState>('switch-active', { modelId, providerId }),
+  reorder: (modelId: string, order: string[]) =>
+    call<ModelRouterState>('reorder', { modelId, order }),
+  refresh: () => call<ModelRouterState>('refresh'),
+}

package/src/client/index.tsx

@@ -0,0 +1,35 @@
+/**
+ * @fonlan/dsh-model-router client half: the Model Router settings page plus
+ * bilingual dictionaries. The composer model picker needs no client
+ * injection — the host catalog already renders the `model-router` group and
+ * each model's description carries the active provider.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import { LOCALE_NS, zh, en } from './locales'
+import { makeSettingsSection } from './settings-section'
+
+/** Services required before mounting (provided by the client runtime). */
+export const inject = ['slots', 'locale']
+
+/** Client plugin body. */
+export function apply(ctx: ClientContext): void {
+  const t = ctx.locale.bind(LOCALE_NS)
+  ctx.effect(() => {
+    const off = ctx.locale.register(LOCALE_NS, { zh, en })
+    return () => off()
+  }, 'model-router: dictionaries')
+
+  const SettingsSection = makeSettingsSection(ctx)
+  ctx.slots.inject('settings.section', () =>
+    ctx.slots.register({
+      name: 'settings.section',
+      id: 'model-router',
+      order: 300,
+      label: () => t('settingsTitle'),
+      locale: LOCALE_NS,
+    }, SettingsSection as never),
+  )
+}

package/src/client/locales.ts

@@ -0,0 +1,39 @@
+// Locale namespace = the plugin's cordis id (kebab). DSH flat namespace keys
+// (settings + locale) use the internal id `model-router`; the scoped npm
+// package name is reserved for package-bound identifiers (exported `name`,
+// module-loader id, the /plugins/<pkg>/… route base).
+export const LOCALE_NS = 'model-router'
+
+export const zh = {
+  settingsTitle: '模型路由',
+  settingsDescription: '每个模型按 model id 聚合所有提供商；点击提供商切换该模型当前使用的路由，拖拽调整优先级顺序（供后续自动切换使用）。',
+  loading: '加载中…',
+  loadFailed: '加载失败：{message}',
+  retry: '重试',
+  refresh: '刷新',
+  empty: '没有可路由的提供商或模型，请先在设置中添加提供商。',
+  modelsCount: '共 {count} 个模型',
+  activeBadge: '当前',
+  noCredential: '未配置 API 密钥，不可选',
+  dragHint: '拖拽调整优先级顺序',
+  switchFailed: '切换失败：{message}',
+  reorderFailed: '排序失败：{message}',
+  providerCount: '{count} 个提供商',
+}
+
+export const en = {
+  settingsTitle: 'Model Router',
+  settingsDescription: 'Each model aggregates its providers by exact model id. Click a provider to switch where this model currently routes; drag to adjust the preference order (used by automatic failover later).',
+  loading: 'Loading…',
+  loadFailed: 'Load failed: {message}',
+  retry: 'Retry',
+  refresh: 'Refresh',
+  empty: 'No routable providers or models yet — add providers in settings first.',
+  modelsCount: '{count} models',
+  activeBadge: 'active',
+  noCredential: 'No API key configured — not selectable',
+  dragHint: 'Drag to adjust preference order',
+  switchFailed: 'Switch failed: {message}',
+  reorderFailed: 'Reorder failed: {message}',
+  providerCount: '{count} providers',
+}

package/src/client/settings-section.css

@@ -0,0 +1,210 @@
+/* Model Router settings page — theme-consistent via DSW alias variables. */
+.mr-root {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 4px 0 24px;
+}
+
+.mr-description {
+  margin: 0;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 13px;
+  line-height: 20px;
+}
+
+.mr-toolbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.mr-count {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.mr-button {
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+  background: var(--dsw-alias-interactive-bg-hover);
+  border: 1px solid var(--dsw-alias-border-l3);
+  border-radius: 8px;
+  font-size: 12px;
+  line-height: 18px;
+  padding: 3px 10px;
+}
+
+.mr-button:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+  filter: brightness(1.08);
+}
+
+.mr-button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.mr-error {
+  background: var(--dsw-alias-interactive-bg-hover-danger);
+  color: var(--dsw-alias-state-error-primary);
+  border-radius: 8px;
+  padding: 7px 8px;
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.mr-empty {
+  color: var(--dsw-alias-label-tertiary);
+  padding: 16px 0;
+  font-size: 13px;
+  line-height: 20px;
+}
+
+.mr-models {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.mr-card {
+  border: 1px solid var(--dsw-alias-border-inverted);
+  border-radius: 12px;
+  padding: 10px 12px;
+  background: var(--dsw-alias-bg-module-platform);
+  transition: opacity 0.12s;
+}
+
+.mr-card-busy {
+  opacity: 0.6;
+  pointer-events: none;
+}
+
+.mr-card-header {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  min-width: 0;
+}
+
+.mr-model-name {
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+  font-weight: 600;
+  line-height: 20px;
+}
+
+.mr-model-id {
+  color: var(--dsw-alias-label-tertiary);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  line-height: 18px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  overflow: hidden;
+  min-width: 0;
+  flex: 1;
+}
+
+.mr-provider-count {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+  flex: none;
+}
+
+.mr-drag-hint {
+  margin: 2px 0 6px;
+  color: var(--dsw-alias-label-caption);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+.mr-providers {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.mr-provider {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  padding: 2px 8px 2px 4px;
+}
+
+.mr-provider-active {
+  background: var(--dsw-alias-interactive-bg-hover);
+  border-color: var(--dsw-alias-border-l3);
+}
+
+.mr-provider-nocred {
+  opacity: 0.55;
+}
+
+.mr-provider-drop {
+  border-color: var(--dsw-alias-border-brand);
+}
+
+.mr-grip {
+  color: var(--dsw-alias-label-caption);
+  cursor: grab;
+  font-size: 12px;
+  line-height: 20px;
+  flex: none;
+  user-select: none;
+}
+
+.mr-grip:active {
+  cursor: grabbing;
+}
+
+.mr-provider-button {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+  color: var(--dsw-alias-label-primary);
+  background: none;
+  border: none;
+  text-align: left;
+  cursor: pointer;
+  font: inherit;
+  padding: 4px 0;
+}
+
+.mr-provider-button:disabled {
+  cursor: default;
+}
+
+.mr-provider-name {
+  font-size: 13px;
+  line-height: 20px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  overflow: hidden;
+}
+
+.mr-provider-nocred-label {
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 12px;
+  line-height: 18px;
+  flex: none;
+}
+
+.mr-active-badge {
+  flex: none;
+  color: var(--dsw-alias-label-inverted, #fff);
+  background: var(--dsw-alias-border-brand, #4d6bfe);
+  border-radius: 999px;
+  font-size: 11px;
+  line-height: 16px;
+  padding: 0 8px;
+}