@fonlan/dsh-model-router 0.3.1 → 0.3.3

package/lib/index.js

@@ -59,6 +59,48 @@ function displayProvider(merged, active) {
 	if (merged.providers.length === 0) return null;
 	return merged.providers.find((p) => p.provider === active) ?? merged.providers[0];
 }
+/** The display name a merged model advertises (active provider's name). */
+function displayNameOf(model, config) {
+	const ids = model.providers.map((provider) => provider.provider);
+	return displayProvider(model, resolveActive(config, model.id, ids) ?? void 0)?.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).
+*/
+function sortModelsForList(models, config) {
+	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), void 0, {
+			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));
+	}
+	const listed = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const id of config.modelOrder ?? []) {
+		if (seen.has(id)) continue;
+		const model = models.find((candidate) => candidate.id === id);
+		if (model === void 0) 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. */
 function initialConfigFor(providerIds) {
 	if (providerIds.length === 0) return null;
@@ -159,6 +201,9 @@ function sameModels(a, b) {
 * 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.
 */
 function reconcileConfig(config, models) {
 	const keyToMerged = /* @__PURE__ */ new Map();
@@ -201,9 +246,22 @@ function reconcileConfig(config, models) {
 		const entry = syncConfig(view, model.id, ids).models[model.id];
 		if (entry !== void 0) next[model.id] = entry;
 	}
+	const storedOrder = config.modelOrder;
+	let modelOrder;
+	let orderChanged = false;
+	if (storedOrder !== void 0) {
+		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,
-		changed: !sameModels(next, config.models)
+		modelOrder,
+		changed: !sameModels(next, config.models) || orderChanged
 	};
 }
 /** Switch a model's active provider (no-op when already active). */
@@ -260,16 +318,28 @@ function normalizeConfig(value) {
 	if (typeof value !== "object" || value === null) return {
 		models,
 		showQuickSwitch: true,
-		ignoreModelIdPrefix: true
+		ignoreModelIdPrefix: true,
+		modelSort: "custom",
+		modelOrder: [],
+		recentlyUsed: {}
 	};
 	const root = value;
 	const showQuickSwitch = root.showQuickSwitch !== false;
 	const ignoreModelIdPrefix = root.ignoreModelIdPrefix !== false;
+	const modelSort = root.modelSort === "name" || root.modelSort === "recent" ? root.modelSort : "custom";
+	const modelOrder = Array.isArray(root.modelOrder) ? root.modelOrder.filter((x) => typeof x === "string") : [];
+	const recentlyUsed = {};
+	if (typeof root.recentlyUsed === "object" && root.recentlyUsed !== null) {
+		for (const [id, ts] of Object.entries(root.recentlyUsed)) if (typeof ts === "number" && Number.isFinite(ts)) recentlyUsed[id] = ts;
+	}
 	const raw = root.models;
 	if (typeof raw !== "object" || raw === null) return {
 		models,
 		showQuickSwitch,
-		ignoreModelIdPrefix
+		ignoreModelIdPrefix,
+		modelSort,
+		modelOrder,
+		recentlyUsed
 	};
 	for (const [id, entry] of Object.entries(raw)) {
 		if (typeof entry !== "object" || entry === null) continue;
@@ -285,7 +355,10 @@ function normalizeConfig(value) {
 	return {
 		models,
 		showQuickSwitch,
-		ignoreModelIdPrefix
+		ignoreModelIdPrefix,
+		modelSort,
+		modelOrder,
+		recentlyUsed
 	};
 }
 //#endregion
@@ -417,6 +490,22 @@ function routeFor(facts, modelId) {
 function entryRawId(merged, providerId) {
 	return merged.providers.find((provider) => provider.provider === providerId)?.id ?? merged.id;
 }
+function unroutable(model) {
+	return new LlmError(`model-router: no provider serves model "${model}"`, "NO_ADAPTER");
+}
+/**
+* Resolve one model id to its active provider and merged model, rejecting
+* unadvertised or currently unroutable ids before any provider I/O.
+*/
+function bindRoute(facts, modelId) {
+	const merged = mergedFor(facts, modelId);
+	const route = merged === null ? null : routeFor(facts, modelId);
+	if (merged === null || route === null) throw unroutable(modelId);
+	return {
+		route,
+		merged
+	};
+}
 var ModelRouterAdapter = class extends LlmAdapter {
 	facts;
 	constructor(facts) {
@@ -430,10 +519,11 @@ var ModelRouterAdapter = class extends LlmAdapter {
 		};
 	}
 	async listModels(_provider) {
+		const config = this.facts.config();
 		const { models } = this.facts.catalog();
 		const names = this.facts.providerNames();
 		const out = [];
-		for (const merged of models) {
+		for (const merged of sortModelsForList(models, config)) {
 			const display = displayProvider(merged, routeFor(this.facts, merged.id)?.provider);
 			if (display === null) continue;
 			out.push({
@@ -446,9 +536,32 @@ var ModelRouterAdapter = class extends LlmAdapter {
 		return out;
 	}
 	async resolveModel(_provider, model, signal) {
-		const route = routeFor(this.facts, model);
-		const merged = route === null ? null : mergedFor(this.facts, model);
-		if (route === null || merged === null) throw new LlmError(`model-router: no provider serves model "${model}"`, "NO_ADAPTER");
+		const { route, merged } = bindRoute(this.facts, model);
+		return this.resolveRoutedIdentity(route, merged, signal);
+	}
+	/**
+	* Bind the route generation at preparation time: a provider switch or
+	* catalog refresh between preparation and dispatch cannot combine one
+	* generation's metadata with another's endpoint, matching the host's
+	* one-generation dispatch contract.
+	*/
+	async prepareCall(_provider, model, signal) {
+		const { route, merged } = bindRoute(this.facts, model);
+		return {
+			model: await this.resolveRoutedIdentity(route, merged, signal),
+			stream: (options) => this.streamRouted(options, route, merged)
+		};
+	}
+	async *stream(options) {
+		const { route, merged } = bindRoute(this.facts, options.model);
+		yield* this.streamRouted(options, route, merged);
+	}
+	/**
+	* Delegate with the provider's raw local id (it may carry a vendor/
+	* prefix the real provider needs), then normalize the resolved identity
+	* back to the merged display id so sessions/metering never leak prefixes.
+	*/
+	async resolveRoutedIdentity(route, merged, signal) {
 		const resolved = await this.facts.llm().resolveModelInfo(route.provider, entryRawId(merged, route.provider), signal);
 		const display = displayProvider(merged, route.provider);
 		return {
@@ -458,10 +571,10 @@ var ModelRouterAdapter = class extends LlmAdapter {
 			name: display?.name ?? resolved.name
 		};
 	}
-	async *stream(options) {
-		const route = routeFor(this.facts, options.model);
-		const merged = route === null ? null : mergedFor(this.facts, options.model);
-		if (route === null || merged === null) throw new LlmError(`model-router: no provider serves model "${options.model}"`, "NO_ADAPTER");
+	async *streamRouted(options, route, merged) {
+		try {
+			this.facts.noteModelUsed(merged.id);
+		} catch {}
 		yield* this.facts.llm().stream({
 			...options,
 			provider: route.provider,
@@ -479,12 +592,22 @@ const RouterConfigSchema = z.object({
 		active: z.string()
 	})),
 	showQuickSwitch: z.boolean(),
-	ignoreModelIdPrefix: 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 = {
 	models: {},
 	showQuickSwitch: true,
-	ignoreModelIdPrefix: true
+	ignoreModelIdPrefix: true,
+	modelSort: "custom",
+	modelOrder: [],
+	recentlyUsed: {}
 };
 var ModelRouterService = class {
 	ctx;
@@ -501,6 +624,11 @@ var ModelRouterService = class {
 	registration;
 	/** How long a built catalog is considered fresh before being rebuilt. */
 	catalogTtlMs = 3e4;
+	/** Debounced recent-use persistence (see noteModelUsed / flushUsage). */
+	usageFlushMs = 1500;
+	usageDebounce = null;
+	pendingUsage = {};
+	usageFlushRunning = false;
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
@@ -517,6 +645,11 @@ var ModelRouterService = class {
 		this.refreshAndReconcile();
 	}
 	stop() {
+		if (this.usageDebounce !== null) {
+			clearTimeout(this.usageDebounce);
+			this.usageDebounce = null;
+		}
+		if (Object.keys(this.pendingUsage).length > 0) this.flushUsage();
 		this.registration?.();
 		this.registration = void 0;
 	}
@@ -541,6 +674,47 @@ var ModelRouterService = class {
 		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) {
+		if (this.scope === void 0) return;
+		this.pendingUsage[modelId] = Date.now();
+		if (this.usageDebounce !== null) return;
+		this.usageDebounce = setTimeout(() => {
+			this.usageDebounce = null;
+			this.flushUsage();
+		}, this.usageFlushMs);
+	}
+	/** Persist accumulated usage timestamps (merging with any concurrent writes). */
+	async flushUsage() {
+		if (this.usageFlushRunning) return;
+		this.usageFlushRunning = true;
+		const pending = this.pendingUsage;
+		this.pendingUsage = {};
+		try {
+			if (this.scope === void 0 || Object.keys(pending).length === 0) return;
+			const current = this.config();
+			await this.scope.replace({
+				...current,
+				recentlyUsed: {
+					...current.recentlyUsed,
+					...pending
+				}
+			});
+		} catch (error) {
+			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;
+		}
+	}
+	/**
 	* 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.
@@ -572,13 +746,13 @@ var ModelRouterService = class {
 		const catalog = await this.refreshCatalog(true);
 		if (this.scope === void 0) 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 === void 0 ? {} : { modelOrder }
 			});
 		} catch (error) {
 			this.ctx.logger.warn(`model-router: reconcile persist failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -599,12 +773,14 @@ var ModelRouterService = class {
 		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);
@@ -647,9 +823,8 @@ var ModelRouterService = class {
 		const current = this.config();
 		if (current.showQuickSwitch === value) return;
 		await this.scope.replace({
-			models: current.models,
-			showQuickSwitch: value,
-			ignoreModelIdPrefix: current.ignoreModelIdPrefix
+			...current,
+			showQuickSwitch: value
 		});
 	}
 	/**
@@ -663,19 +838,45 @@ var ModelRouterService = class {
 		const current = this.config();
 		if (current.ignoreModelIdPrefix === value) return;
 		await this.scope.replace({
-			models: current.models,
-			showQuickSwitch: current.showQuickSwitch,
+			...current,
 			ignoreModelIdPrefix: value
 		});
 		await this.refreshAndReconcile();
 	}
+	/** Switch the model-list display order mode (global, persisted). */
+	async setModelSort(mode) {
+		if (this.scope === void 0) 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) {
+		if (this.scope === void 0) 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();
+		if (clean.length === current.modelOrder.length && clean.every((id, at) => id === current.modelOrder[at])) return;
+		await this.scope.replace({
+			...current,
+			modelOrder: clean
+		});
+	}
 	async persist(models) {
 		if (this.scope === void 0) 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
+			...current,
+			models
 		});
 	}
 };
@@ -801,6 +1002,16 @@ function registerApiRoutes(ctx, service) {
 		await service.setIgnoreModelIdPrefix(p.value);
 		return service.state();
 	});
+	route("set-model-sort", async (p) => {
+		if (p.mode !== "custom" && p.mode !== "name" && p.mode !== "recent") throw new Error("mode 必须是 custom、name 或 recent");
+		await service.setModelSort(p.mode);
+		return service.state();
+	});
+	route("set-model-order", async (p) => {
+		if (!Array.isArray(p.order) || !p.order.every((id) => typeof id === "string")) throw new Error("order 必须是模型 id 数组");
+		await service.setModelOrder(p.order);
+		return service.state();
+	});
 	return () => {
 		for (const dispose of disposers) dispose();
 	};

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

@@ -8,7 +8,7 @@
  * flag is on, and delegation always uses the active provider's raw local id.
  */
 import { LlmAdapter, type LlmRuntime } from '@deepseek-ai/dsh-llm';
-import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, StreamChunk } from '@deepseek-ai/dsh-llm';
 import { type MergedModel, type RouterConfigShape } from '../shared/config.js';
 /** Facts the adapter reads from the owning service (live, per request). */
 export interface RouterFacts {
@@ -23,6 +23,8 @@ export interface RouterFacts {
     providerNames(): ReadonlyMap<string, string>;
     /** The LLM runtime to delegate to. */
     llm(): LlmRuntime;
+    /** Record one model request for the recent-use ordering (fire-and-forget). */
+    noteModelUsed(modelId: string): void;
 }
 /** One resolved route for a model id. */
 export interface ResolvedRoute {
@@ -44,11 +46,35 @@ export declare function mergedFor(facts: RouterFacts, modelId: string): MergedMo
 export declare function routeFor(facts: RouterFacts, modelId: string): ResolvedRoute | null;
 /** The raw provider-local id of one provider entry inside a merged model. */
 export declare function entryRawId(merged: MergedModel, providerId: string): string;
+/** One validated route plus the merged model it was resolved against. */
+export interface BoundRoute {
+    route: ResolvedRoute;
+    merged: MergedModel;
+}
+/**
+ * Resolve one model id to its active provider and merged model, rejecting
+ * unadvertised or currently unroutable ids before any provider I/O.
+ */
+export declare function bindRoute(facts: RouterFacts, modelId: string): BoundRoute;
 export declare class ModelRouterAdapter extends LlmAdapter {
     private readonly facts;
     constructor(facts: RouterFacts);
     providerInfo(provider: string): LlmProviderInfo;
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
     resolveModel(_provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /**
+     * Bind the route generation at preparation time: a provider switch or
+     * catalog refresh between preparation and dispatch cannot combine one
+     * generation's metadata with another's endpoint, matching the host's
+     * one-generation dispatch contract.
+     */
+    prepareCall(_provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Delegate with the provider's raw local id (it may carry a vendor/
+     * prefix the real provider needs), then normalize the resolved identity
+     * back to the merged display id so sessions/metering never leak prefixes.
+     */
+    private resolveRoutedIdentity;
+    private streamRouted;
 }

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

@@ -5,7 +5,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import { type RouterConfigShape } from '../shared/config.js';
+import { type ModelSortMode, 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;
@@ -13,10 +13,14 @@ export declare const NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
 export declare const RouterConfigSchema: z<RouterConfigShape>;
 /** 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;
@@ -46,6 +50,11 @@ export declare class ModelRouterService implements RouterFacts {
     private registration;
     /** How long a built catalog is considered fresh before being rebuilt. */
     private readonly catalogTtlMs;
+    /** Debounced recent-use persistence (see noteModelUsed / flushUsage). */
+    private readonly usageFlushMs;
+    private usageDebounce;
+    private pendingUsage;
+    private usageFlushRunning;
     constructor(ctx: Context);
     /** Register settings + adapter and wire topology listeners. */
     start(): void;
@@ -57,6 +66,15 @@ export declare class ModelRouterService implements RouterFacts {
     config(): RouterConfigShape;
     providerNames(): ReadonlyMap<string, string>;
     llm(): import("@deepseek-ai/dsh-llm").LlmRuntime;
+    /**
+     * 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;
+    /** Persist accumulated usage timestamps (merging with any concurrent writes). */
+    private flushUsage;
     /**
      * Return the live catalog, rebuilding it only when it is stale (older than
      * `catalogTtlMs`) or `force` is set. Concurrent callers share one in-flight
@@ -89,5 +107,13 @@ export declare class ModelRouterService implements RouterFacts {
      * turning on; split models re-initialize when turning off).
      */
     setIgnoreModelIdPrefix(value: boolean): Promise<void>;
+    /** Switch the model-list display order mode (global, persisted). */
+    setModelSort(mode: ModelSortMode): Promise<void>;
+    /**
+     * 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.
+     */
+    setModelOrder(order: string[]): Promise<void>;
     private persist;
 }

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

@@ -59,12 +59,27 @@ export interface RouterModelConfig {
     /** The provider requests currently route to. */
     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;
@@ -76,6 +91,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 declare const ROUTER_PROVIDER_ID = "model-router";
 export declare const ROUTER_SETTINGS_NS = "model-router";
@@ -100,6 +132,22 @@ export interface MergeOptions {
 export declare function mergeModels(providers: readonly ProviderInfo[], options?: MergeOptions): MergedModel[];
 /** The provider view a merged model should display for (follows active). */
 export declare function displayProvider(merged: MergedModel, active: string | undefined): ProviderModelInfo | null;
+/** The display name a merged model advertises (active provider's name). */
+export declare function displayNameOf(model: MergedModel, config: RouterConfigShape): string;
+/**
+ * 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 declare function sortModelsForList(models: readonly MergedModel[], config: RouterConfigShape): MergedModel[];
 /** Initial config for a model the user never configured: first in order wins. */
 export declare function initialConfigFor(providerIds: readonly string[]): RouterModelConfig | null;
 /**
@@ -131,9 +179,13 @@ export declare function syncConfig(config: RouterConfigShape, modelId: string, c
  * 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 declare function reconcileConfig(config: RouterConfigShape, models: readonly MergedModel[]): {
     models: Record<string, RouterModelConfig>;
+    modelOrder: string[] | undefined;
     changed: boolean;
 };
 /** Switch a model's active provider (no-op when already active). */