dsh-model-switch 0.0.0-stage → 0.4.18

package/lib/main-settings.js

@@ -0,0 +1,30 @@
+import { parseReasoningEffortId, resolveDefaultEffort, validateModelSelection } from "./capabilities.js";
+//#region lib/types/main-settings.js
+function routeShape(input) {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) throw new Error("Main default route must be an object");
+	const value = input;
+	if (typeof value.provider !== "string" || value.provider.trim() === "") throw new Error("Main default provider must be a non-empty string");
+	if (typeof value.model !== "string" || value.model.trim() === "") throw new Error("Main default model must be a non-empty string");
+	if (value.reasoningEffort !== void 0 && (typeof value.reasoningEffort !== "string" || value.reasoningEffort.trim() === "")) throw new Error("Main default reasoningEffort must be a non-empty string when present");
+	return {
+		provider: value.provider,
+		model: value.model,
+		...value.reasoningEffort === void 0 ? {} : { reasoningEffort: parseReasoningEffortId(value.reasoningEffort) }
+	};
+}
+/** Decode storage without resolving availability, so invalid/uninstalled choices remain visible. */
+function parseMainSettingsDocument(input) {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) throw new Error("Main settings must be an object");
+	const value = input;
+	if (value.version !== 1) throw new Error("Main settings version must be 1");
+	return {
+		version: 1,
+		defaultRoute: routeShape(value.defaultRoute)
+	};
+}
+/** Validate only when a caller creates a new session; existing sessions never re-read this document. */
+function routeForNewSession(catalog, settings) {
+	return resolveDefaultEffort(catalog, validateModelSelection(catalog, settings.defaultRoute));
+}
+//#endregion
+export { parseMainSettingsDocument, routeForNewSession };

package/lib/subagent-route-policy.js

@@ -0,0 +1,55 @@
+import { resolveDefaultEffort, validateModelSelection } from "./capabilities.js";
+//#region lib/types/subagent-route-policy.js
+function parsePolicy(catalog, policy) {
+	if (policy.mode === "follow-main") return { mode: "follow-main" };
+	if (policy.mode === "fixed") return {
+		mode: "fixed",
+		route: validateModelSelection(catalog, policy.route)
+	};
+	throw new Error("subagent policy mode must be follow-main or fixed");
+}
+function workflowSelection(override) {
+	return override.effort === void 0 ? {
+		provider: override.provider,
+		model: override.model
+	} : {
+		provider: override.provider,
+		model: override.model,
+		reasoningEffort: override.effort
+	};
+}
+function createSubagentRouteSnapshot(catalog, input) {
+	if (input.workflowOverride !== void 0) return {
+		version: 1,
+		source: "workflow-override",
+		selection: resolveDefaultEffort(catalog, validateModelSelection(catalog, workflowSelection(input.workflowOverride)))
+	};
+	const policy = parsePolicy(catalog, input.policy);
+	if (policy.mode === "fixed") return {
+		version: 1,
+		source: "fixed-policy",
+		selection: resolveDefaultEffort(catalog, policy.route)
+	};
+	return {
+		version: 1,
+		source: "official-inherit"
+	};
+}
+function restoreSubagentRouteSnapshot(catalog, input) {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) throw new Error("subagent route snapshot must be an object");
+	const value = input;
+	if (value.version !== 1) throw new Error("subagent route snapshot version must be 1");
+	const source = String(value.source);
+	if (source === "official-inherit" || source === "parent-request-header" || source === "main-fallback") return {
+		version: 1,
+		source: "official-inherit"
+	};
+	if (source === "fixed-policy" || source === "workflow-override") return {
+		version: 1,
+		source,
+		selection: validateModelSelection(catalog, value.selection)
+	};
+	throw new Error("subagent route snapshot source is invalid");
+}
+//#endregion
+export { createSubagentRouteSnapshot, restoreSubagentRouteSnapshot };

package/lib/subagent-runtime.js

@@ -0,0 +1,186 @@
+import { ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import OfficialSubagentRuntime from "@deepseek-ai/dsh-subagent";
+//#region lib/types/subagent-runtime.js
+/** Raised only when an explicit startup check finds an unsupported public surface. */
+var StartupIncompatibilityError = class extends Error {
+	name = "StartupIncompatibilityError";
+	surface;
+	/**
+	* @param surfaceOrMessage - the incompatible public surface, or the error message.
+	* @param message - the missing or incompatible requirement.
+	*/
+	constructor(surfaceOrMessage, message) {
+		super(message ?? surfaceOrMessage);
+		this.surface = message === void 0 ? "startup" : surfaceOrMessage;
+	}
+};
+function present(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+function spawnHasAnyRouteField(options) {
+	return present(options?.provider) || present(options?.model) || options?.reasoningEffort !== void 0;
+}
+function fixedRoute(settings) {
+	if (!present(settings.subagentProvider) || !present(settings.subagentModel)) return void 0;
+	return {
+		provider: settings.subagentProvider,
+		model: settings.subagentModel,
+		...present(settings.subagentReasoningEffort) ? { reasoningEffort: ReasoningEffortId(settings.subagentReasoningEffort) } : {}
+	};
+}
+/** Inject a fixed Default Subagent route, or leave the request for Official inherit. */
+function routeSubagentRequest(request, settings) {
+	if (spawnHasAnyRouteField(request.agentOptions)) return request;
+	if (settings.subagentMode !== "fixed") return request;
+	const selected = fixedRoute(settings);
+	if (selected === void 0) return request;
+	return {
+		...request,
+		agentOptions: {
+			...request.agentOptions,
+			provider: selected.provider,
+			model: selected.model,
+			...selected.reasoningEffort === void 0 ? {} : { reasoningEffort: selected.reasoningEffort }
+		}
+	};
+}
+function assertPublicMethod(value, surface, method) {
+	if (value === null || typeof value !== "object" && typeof value !== "function" || typeof Reflect.get(value, method) !== "function") throw new StartupIncompatibilityError(surface, surface + " must expose public " + method + "()");
+}
+function constructible(value) {
+	if (typeof value !== "function") return false;
+	try {
+		Reflect.construct(Object, [], value);
+		return true;
+	} catch (error) {
+		if (error instanceof TypeError) return false;
+		throw error;
+	}
+}
+function assertOfficialRuntimeSurface() {
+	const runtime = OfficialSubagentRuntime;
+	if (!constructible(runtime)) throw new StartupIncompatibilityError("OfficialSubagentRuntime", "OfficialSubagentRuntime must be constructible");
+	const prototype = Reflect.get(runtime, "prototype");
+	assertPublicMethod(prototype, "OfficialSubagentRuntime", "start");
+	assertPublicMethod(prototype, "OfficialSubagentRuntime", "startContinuable");
+}
+function assertRoutingSurface(ctx) {
+	const modelSwitch = ctx.modelSwitch;
+	assertPublicMethod(modelSwitch, "Model Switch runtime", "currentSettings");
+}
+function routingSurface(ctx) {
+	return ctx.modelSwitch;
+}
+function assertMountedSurface(ctx) {
+	assertPublicMethod(ctx.subagents, "mounted Subagent runtime", "start");
+	assertPublicMethod(ctx.subagents, "mounted Subagent runtime", "startContinuable");
+	assertPublicMethod(ctx.subagents, "mounted Subagent runtime", "resolveMaxDepth");
+}
+function once(dispose) {
+	let pending;
+	return () => {
+		pending ??= Promise.resolve().then(() => dispose()).then(() => void 0);
+		return pending;
+	};
+}
+var CleanupLedger = class {
+	attempts = [];
+	add(dispose) {
+		this.attempts.push(once(dispose));
+	}
+	async disposeAll() {
+		const failures = [];
+		for (const dispose of [...this.attempts].reverse()) try {
+			await dispose();
+		} catch (error) {
+			failures.push(error);
+		}
+		return failures;
+	}
+};
+function startupFailure(error, cleanupFailures) {
+	if (cleanupFailures.length === 0) throw error;
+	throw new AggregateError([error, ...cleanupFailures], "Subagent runtime startup and cleanup failed", { cause: error });
+}
+function cleanupDisposer(ledger) {
+	return async () => {
+		const failures = await ledger.disposeAll();
+		if (failures.length > 0) throw new AggregateError(failures, "Subagent runtime cleanup failed");
+	};
+}
+/**
+* Mount a candidate and use the fallback only for typed startup incompatibility.
+*
+* Every resource registered by an attempt is disposed in reverse order before a
+* fallback starts and again when the mounted result is disposed. Cleanup keeps
+* running after failures, and a startup error stays first in any aggregate.
+*
+* @param candidate - startup callback for the routed candidate.
+* @param fallback - startup callback for the untouched official runtime.
+* @returns the selected value and an idempotent disposer.
+* @throws the candidate error unless it is a StartupIncompatibilityError.
+* @throws the fallback startup error when fallback startup fails.
+*/
+async function mountWithStartupFallback(candidate, fallback) {
+	const ledger = new CleanupLedger();
+	try {
+		return {
+			value: await candidate((dispose) => ledger.add(dispose)),
+			dispose: cleanupDisposer(ledger)
+		};
+	} catch (error) {
+		const cleanupFailures = await ledger.disposeAll();
+		if (!(error instanceof StartupIncompatibilityError)) startupFailure(error, cleanupFailures);
+		if (cleanupFailures.length > 0) startupFailure(error, cleanupFailures);
+	}
+	try {
+		return {
+			value: await fallback((dispose) => ledger.add(dispose)),
+			dispose: cleanupDisposer(ledger)
+		};
+	} catch (error) {
+		startupFailure(error, await ledger.disposeAll());
+	}
+}
+async function mountProfileRuntime(ctx) {
+	return (await mountWithStartupFallback(async (track) => {
+		assertOfficialRuntimeSurface();
+		assertRoutingSurface(ctx);
+		const candidate = ctx.plugin(ModelSwitchSubagentRuntime);
+		track(() => candidate.dispose());
+		await candidate;
+		const surface = ctx.inject(["subagents"], (surfaceCtx) => {
+			assertMountedSurface(surfaceCtx);
+		});
+		track(() => surface.dispose());
+		await surface;
+		return candidate;
+	}, async (track) => {
+		const official = ctx.plugin(OfficialSubagentRuntime);
+		track(() => official.dispose());
+		await official;
+		return official;
+	})).dispose;
+}
+/** Profile replacement that selects the routed runtime or the untouched official runtime. */
+const profileSubagentRuntime = Object.assign(async (ctx) => mountProfileRuntime(ctx), { inject: ["modelSwitch"] });
+/** Official runtime with only a pre-descriptor route-selection adapter. */
+var ModelSwitchSubagentRuntime = class extends OfficialSubagentRuntime {
+	static inject = ["modelSwitch"];
+	routed(name, request) {
+		const provider = this.ctx.subagents.getProvider(name);
+		if (provider !== void 0 && provider.capabilities.agentOptions !== true) return request;
+		return routeSubagentRequest(request, routingSurface(this.ctx).currentSettings());
+	}
+	start(name, request) {
+		return super.start(name, this.routed(name, request));
+	}
+	startContinuable(spec) {
+		return super.startContinuable({
+			...spec,
+			request: this.routed(spec.provider, spec.request)
+		});
+	}
+};
+//#endregion
+export { ModelSwitchSubagentRuntime, StartupIncompatibilityError, profileSubagentRuntime as default, profileSubagentRuntime, mountWithStartupFallback, routeSubagentRequest };

package/lib/types/adapter-registry.d.ts

@@ -0,0 +1,60 @@
+import type { WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+export interface SearchModel {
+    readonly id: string;
+    readonly name: string;
+}
+export interface SearchProviderMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly models: readonly SearchModel[];
+}
+export interface ModelSwitchSearchAdapter {
+    readonly provider: string;
+    readonly label?: string;
+    /** Independent web_search models, not the conversational/native-network catalog. */
+    readonly models?: readonly SearchModel[];
+    supportsModel(model: string): boolean;
+    search(model: string, request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+export type ImageOutputFormat = 'png' | 'jpeg' | 'webp';
+export interface ModelSwitchImageRequest {
+    readonly prompt: string;
+    readonly path?: string;
+    readonly source?: string;
+    readonly outputFormat?: ImageOutputFormat;
+    readonly aspectRatio?: string;
+}
+export interface ModelSwitchGeneratedImage {
+    readonly path: string;
+    readonly mediaType: string;
+    readonly width: number;
+    readonly height: number;
+    readonly bytes?: number;
+    readonly attachmentId?: string;
+    readonly name?: string;
+    readonly revisedPrompt?: string;
+}
+export interface ModelSwitchImageAdapter {
+    readonly provider: string;
+    supportsModel(model: string): boolean;
+    generate(model: string, request: ModelSwitchImageRequest, execution: unknown): Promise<ModelSwitchGeneratedImage>;
+}
+export interface ModelSwitchProviderAdapters {
+    readonly provider: string;
+    /** Native Agent providers own their context and are excluded from DSH switch compaction. */
+    readonly role?: 'llm' | 'agent';
+    readonly search?: ModelSwitchSearchAdapter;
+    readonly image?: ModelSwitchImageAdapter;
+}
+/** Lifecycle-owned registry for optional provider integrations. */
+export declare class ModelSwitchAdapterRegistry {
+    private readonly entries;
+    private readonly listeners;
+    subscribe(listener: () => void): () => void;
+    private changed;
+    /** Explicit projection: never serialize an executable adapter or its extra fields. */
+    searchCatalog(): readonly SearchProviderMetadata[];
+    register(adapters: ModelSwitchProviderAdapters): () => void;
+    get(provider: string): ModelSwitchProviderAdapters | undefined;
+    list(): readonly ModelSwitchProviderAdapters[];
+}

package/lib/types/capabilities-rpc.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection';
+import type { ModelSwitchAdapterRegistry } from './adapter-registry.js';
+import type { RuntimeCapabilities } from './runtime-capabilities.js';
+export declare const CAPABILITIES_RPC_METHOD = "plugin-rpc/model-switch";
+export interface CapabilitiesSnapshot {
+    readonly revision: number;
+    readonly capabilities: RuntimeCapabilities;
+}
+/** Bounded long-poll on the existing registry; each caller owns and disposes its subscription. */
+export declare function capabilitiesRpc(registry: ModelSwitchAdapterRegistry, snapshot: () => RuntimeCapabilities, lifetime: AbortSignal): ConnectionRpcHandler;
+export declare function installCapabilitiesRpc(ctx: Context, registry: ModelSwitchAdapterRegistry, snapshot: () => RuntimeCapabilities): void;

package/lib/types/capabilities.d.ts

@@ -0,0 +1,22 @@
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import type { ModelSelection } from '@deepseek-ai/dsh-agent';
+export type { ModelSelection, ReasoningEffortId };
+export type ModelCapability = 'chat' | 'search' | 'vision' | 'image';
+export interface ModelCapabilities {
+    capabilities: readonly ModelCapability[];
+    reasoningEfforts?: readonly ReasoningEffortId[];
+    defaultReasoningEffort?: ReasoningEffortId;
+}
+export interface ProviderCapabilities {
+    models: Readonly<Record<string, ModelCapabilities>>;
+}
+export interface CapabilityCatalog {
+    providers: Readonly<Record<string, ProviderCapabilities>>;
+}
+export declare class CapabilityValidationError extends Error {
+    readonly name = "CapabilityValidationError";
+}
+export declare function parseReasoningEffortId(value: unknown, label?: string): ReasoningEffortId;
+export declare function defineCapabilityCatalog(catalog: CapabilityCatalog): CapabilityCatalog;
+export declare function validateModelSelection(catalog: CapabilityCatalog, input: unknown, requiredCapability?: ModelCapability): ModelSelection;
+export declare function resolveDefaultEffort(catalog: CapabilityCatalog, selection: ModelSelection): ModelSelection;

package/lib/types/client/ModelSwitchSettings.d.ts

@@ -0,0 +1,32 @@
+import { type ReactNode } from 'react';
+import type { ModelProviderGroup } from '@deepseek-ai/dsh-api-session-controller/types';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { InjectFace, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import { type CapabilityRouteView, type MainSettingsView, type ModelSwitchSettingsView, type SubagentSettingsView } from '../client-contract.js';
+import type { RuntimeCapabilities } from '../runtime-capabilities.js';
+import { type CapabilitiesSnapshot } from './search-capabilities.js';
+import type { ModelSwitchLocaleKey } from './locales.js';
+import type { ConfigViewForm } from './derived-config-form.js';
+export interface ModelSwitchSettingsFace {
+    t: (key: ModelSwitchLocaleKey) => string;
+    hooks: {
+        mainSettings: ConfigViewForm<MainSettingsView>;
+        subagentSettings: ConfigViewForm<SubagentSettingsView>;
+        searchSettings: ConfigViewForm<CapabilityRouteView>;
+        imageSettings: ConfigViewForm<CapabilityRouteView>;
+        switchSettings: Pick<ConfigForm<ModelSwitchSettingsView>, 'getSnapshot' | 'subscribe'>;
+    };
+    capabilities: RuntimeCapabilities;
+    saveMain: (next: MainSettingsView, expectedRevision: number) => Promise<number>;
+    setSubagent: (field: 'mode' | 'provider' | 'model' | 'reasoningEffort', value: string | undefined) => Promise<void>;
+    setCapability: (route: 'search' | 'image', field: 'provider' | 'model', value: string | undefined) => Promise<void>;
+    setCompactOnSwitch: (value: boolean) => Promise<void>;
+    loadCatalog: () => Promise<readonly ModelProviderGroup[]>;
+    /** Host capabilities long-poll; absent in legacy faces, which keep the static-capabilities path. */
+    loadCapabilities?: (revision?: number, signal?: AbortSignal) => Promise<CapabilitiesSnapshot>;
+    subscribeProviderOrder?: (listener: () => void) => () => void;
+    /** ProviderDirectory-owned role lookup; absent when the owner seam is unavailable. */
+    providerRoleOf?: (key: string) => string;
+}
+export type ModelSwitchSettingsProps = PropsRuntime<'settings.section'> & InjectFace<ModelSwitchSettingsFace>;
+export declare function ModelSwitchSettings(props: ModelSwitchSettingsProps): ReactNode;

package/lib/types/client/antigravity-catalog.d.ts

@@ -0,0 +1,30 @@
+import { type PluginRpcClient } from './plugin-rpc.ts';
+/** DSH-parent subagent access to the Antigravity Enabled catalog. */
+import type { ModelProviderGroup } from '@deepseek-ai/dsh-api-session-controller/types';
+/** Provider key owned by the Antigravity card. */
+export declare const ANTIGRAVITY_PROVIDER_KEY = "antigravity";
+/** Agent role owned by ProviderDirectory (dsh-llm-providers-ui), never hardcoded by Model Switch. */
+export declare const AGENT_ROLE = "agent";
+/**
+ * Antigravity's authenticated plugin route; this plugin has no build dependency on its owner.
+ */
+export declare const ANTIGRAVITY_CATALOG_METHOD = "plugin-rpc/antigravity";
+export declare const ANTIGRAVITY_CATALOG_ENDPOINT = "catalog";
+/** Decode the Enabled-catalog payload; anything malformed decodes to no groups. */
+export declare function decodeAntigravityCatalogGroups(value: unknown): ModelProviderGroup[];
+/**
+ * Read the Enabled catalog; resolves to no groups when Antigravity is absent,
+ * unreachable, or malformed. Never throws: the Host catalog stays authoritative.
+ */
+export declare function fetchAntigravityCatalogGroups(rpc: PluginRpcClient | undefined): Promise<ModelProviderGroup[]>;
+/** Overlay Enabled-catalog groups onto the Host catalog without duplicating ids. */
+export declare function withAntigravityCatalog(base: readonly ModelProviderGroup[], extra: readonly ModelProviderGroup[]): ModelProviderGroup[];
+/** Read one Provider role from the owner directory; undefined when the seam is absent. */
+export declare function readProviderRole(directory: unknown, key: string): string | undefined;
+/** Whether a ProviderDirectory-owned role marks an Agent provider. */
+export declare function isAgentRole(role: string | undefined): boolean;
+/** Resolve a stored native `…-high|medium|low` id to the collapsed catalog row. */
+export declare function matchCatalogModel(models: readonly ModelProviderGroup['models'][number][], modelId: string | undefined): {
+    model: ModelProviderGroup['models'][number];
+    effort?: string;
+} | undefined;

package/lib/types/client/derived-config-form.d.ts

@@ -0,0 +1,10 @@
+import type { ConfigForm, ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client';
+export interface ConfigViewForm<T> {
+    getSnapshot(): ConfigFormSnapshot<T>;
+    subscribe(listener: () => void): () => void;
+    set(field: keyof T & string, value: unknown): Promise<void>;
+    unset(field: keyof T & string): Promise<void>;
+}
+export declare function deriveConfigForm<Source, View>(source: ConfigForm<Source>, project: (value: Source) => View, fields: {
+    [K in keyof View & string]: keyof Source & string;
+}): ConfigViewForm<View>;

package/lib/types/client/derived-settings-scope.d.ts

@@ -0,0 +1,4 @@
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+export type SettingsFieldMap<View> = Readonly<Partial<Record<keyof View & string, string>>>;
+/** Projection over one shared SettingsScope controller/store, with explicit view-to-owner field mapping. */
+export declare function deriveSettingsScope<Source, View>(source: SettingsScope<Source>, project: (value: Source) => View, fields?: SettingsFieldMap<View>): SettingsScope<View>;

package/lib/types/client/index.d.ts

@@ -0,0 +1,10 @@
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type ModelSwitchLocaleKey } from './locales.js';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'settings.model-switch': ModelSwitchLocaleKey;
+    }
+}
+export declare const name = "dsh-model-switch-client";
+export declare const inject: string[];
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,45 @@
+export declare const zh: {
+    readonly nav: "模型切换";
+    readonly title: "模型切换";
+    readonly subtitle: "为主会话、子代理和能力工具设置默认模型。修改只影响新请求。";
+    readonly conversationRoutes: "对话路由";
+    readonly capabilityRoutes: "能力路由";
+    readonly sendProtection: "发送保护";
+    readonly settingsSynced: "设置已同步";
+    readonly remoteSettingsUnavailable: "官方 DSH 在非本机浏览器禁用配置读取与写入；请在 Host 的 127.0.0.1 页面打开设置。";
+    readonly defaultBadge: "默认";
+    readonly cancel: "取消";
+    readonly compactOnSwitch: "切换时压缩";
+    readonly compactOnSwitchHelp: "发送且换了模型时，先按目标窗口检查上下文；超了就用切换前的模型压一次历史，再继续请求。只选模型、不发送，不会压缩。官方自动压缩和 /compact 不受影响。压缩会产生额外模型用量，摘要可能省略细节。";
+    readonly main: "主模型";
+    readonly provider: "提供商";
+    readonly model: "模型";
+    readonly providerDefault: "使用提供商默认值";
+    readonly providerDefaultShort: "Provider 默认";
+    readonly effort: "推理强度";
+    readonly save: "保存";
+    readonly saving: "保存中…";
+    readonly saved: "已保存";
+    readonly subagent: "子代理默认路由";
+    readonly subagentHelp: "DSH 已有官方子代理模型白名单：模型自己点名 provider/model 时以它为准。这里只在未点名时使用。";
+    readonly subagentOff: "未指定时使用官方继承";
+    readonly agentBadge: "Agent";
+    readonly search: "Web 搜索";
+    readonly searchHelp: "下拉选择的是期望使用的搜索 Adapter/模型；仅当全局 Web searchProvider=model-switch 时官方 web_search 才会使用该选择，否则保持原有路由不变。";
+    readonly image: "图像生成";
+    readonly imageHelp: "统一 generate_image 会调用所选 Codex 或 Grok Adapter；Provider 原有图片工具仍保留。";
+    readonly unavailable: "未接入";
+    readonly loading: "正在加载设置…";
+    readonly readonly: "设置为只读";
+    readonly requestFailed: "保存失败";
+    readonly catalogFailed: "无法加载模型目录。";
+    readonly conflict: "设置已在其他位置更改，请检查最新值后重试。";
+    readonly 'reason.central-subagent-routing': "Alpha.4 没有全局子代理启动路由接口。";
+    readonly 'reason.packaged-preset-roots': "Alpha.4 不支持插件提供额外 preset root。";
+    readonly 'reason.tool-owner-suppression': "Alpha.4 没有工具所有者或来源抑制接口。";
+    readonly 'reason.search-provider-adapters': "当前公开版本没有可按模型切换的搜索 Provider Adapter。";
+    readonly 'reason.vision-provider-adapters': "尚无 Provider 注册可独立路由的 Vision Adapter。";
+    readonly 'reason.image-provider-adapters': "当前公开版本没有图像生成 Provider Adapter。";
+};
+export declare const en: Record<keyof typeof zh, string>;
+export type ModelSwitchLocaleKey = keyof typeof zh;

package/lib/types/client/main-row-controller.d.ts

@@ -0,0 +1,49 @@
+import type { ModelProviderGroup } from '@deepseek-ai/dsh-api-session-controller/types';
+import type { ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client';
+import { type CapabilityRouteView, type MainSettingsView, type SubagentSettingsView } from '../client-contract.js';
+import type { ModelSwitchLocaleKey } from './locales.js';
+type Share<T> = (selector: (snapshot: ConfigFormSnapshot<T>) => ConfigFormSnapshot<T>) => ConfigFormSnapshot<T>;
+export interface SettingsControllerInputs {
+    useMainSettings: Share<MainSettingsView>;
+    useSubagentSettings: Share<SubagentSettingsView>;
+    saveMain(next: MainSettingsView, expectedRevision: number): Promise<number>;
+    loadCatalog(): Promise<readonly ModelProviderGroup[]>;
+    subscribeProviderOrder?: (listener: () => void) => () => void;
+    t(key: ModelSwitchLocaleKey): string;
+}
+export interface Choice {
+    id: string;
+    name: string;
+    unavailable?: true;
+}
+/** Build a settings route for a newly selected model using only that model's default effort. */
+export declare function selectRouteModel(groups: readonly ModelProviderGroup[], provider: string, model: string): MainSettingsView;
+export declare function deriveRouteChoices(groups: readonly ModelProviderGroup[], route: CapabilityRouteView | undefined, allowedProviders?: readonly string[]): {
+    providers: Choice[];
+    models: Choice[];
+};
+export declare function expectedMainRevision(mirror: number, accepted?: number): number;
+export declare function acceptedRevisionAfterFailure(accepted: number | undefined, error: unknown): number | undefined;
+export declare function deriveMainChoices(groups: readonly ModelProviderGroup[], draft?: MainSettingsView): {
+    providers: Choice[];
+    models: Choice[];
+    efforts: Choice[];
+};
+export declare function useModelSwitchSettingsController(input: SettingsControllerInputs): {
+    main: ConfigFormSnapshot<MainSettingsView>;
+    subagent: ConfigFormSnapshot<SubagentSettingsView>;
+    draft: MainSettingsView | undefined;
+    groups: readonly ModelProviderGroup[];
+    providers: Choice[];
+    models: Choice[];
+    efforts: Choice[];
+    busy: boolean;
+    message: string | undefined;
+    disabled: boolean;
+    setProvider: (provider: string) => void;
+    setModel: (id: string) => void;
+    setReasoningEffort: (value: string) => void;
+    reset: () => void;
+    save: () => Promise<void>;
+};
+export {};

package/lib/types/client/nav-icon.d.ts

@@ -0,0 +1,3 @@
+/** Official settings.section has no icon field. Swap the default gear for a model-switch glyph. */
+/** Keep the Model Switch nav glyph in place across Settings re-renders. */
+export declare function installModelSwitchNavIcon(): () => void;

package/lib/types/client/picker/ComposerPicker.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Composer model seat: suffix-grouped Model / Effort / Context / Fast / Thinking.
+ */
+import type { ModelSelection } from '@deepseek-ai/dsh-api-session-controller/types';
+import type { PickerKey } from './locales.ts';
+import type { PickerDirectoryView } from './PickerDirectory.ts';
+import type { PickerInteractionOperations } from './popup-dismissal.ts';
+import { type RuntimeProviderLock } from '../runtime-lock.ts';
+export type { PickerDirectoryFace, PickerDirectoryOperations, PickerDirectorySnapshot, PickerDirectoryView } from './PickerDirectory.ts';
+interface ComposerPickerBaseProps {
+    locked: boolean;
+    providerLock?: RuntimeProviderLock;
+    /** Hide/disable Agent-role groups on existing DSH sessions that are not native-bound. */
+    agentLocked?: boolean;
+    available: boolean;
+    /** Explain a disabled picker when the official Host has no persistent settings channel. */
+    unavailableReason?: string;
+    directory: PickerDirectoryView;
+    t: (key: PickerKey, params?: Record<string, string>) => string;
+    embedded?: boolean;
+    tone?: 'capsule';
+    resolveInteractionOperations?: () => PickerInteractionOperations | undefined;
+    /** Resolve a provider key to its ProviderDirectory role; absent means DSH-owned LLM (whale). */
+    roleOf?: (providerKey: string) => string | undefined;
+}
+export type ComposerPickerProps = ComposerPickerBaseProps & ({
+    draft?: never;
+    onDraftChange?: never;
+} | {
+    draft?: ModelSelection;
+    onDraftChange: (selection: ModelSelection) => void;
+});
+export interface ModelPaneHeaderProps {
+    title: string;
+    backLabel: string;
+    searchLabel: string;
+    closeSearchLabel: string;
+    searchable: boolean;
+    searching: boolean;
+    query: string;
+    onBack: () => void;
+    onStartSearch: () => void;
+    onCloseSearch: () => void;
+    onQueryChange: (query: string) => void;
+}
+export declare function ModelPaneHeader({ title, backLabel, searchLabel, closeSearchLabel, searchable, searching, query, onBack, onStartSearch, onCloseSearch, onQueryChange, }: ModelPaneHeaderProps): import("react").JSX.Element;
+export declare function ComposerPicker({ locked, providerLock, agentLocked, available, unavailableReason, directory, t, draft, onDraftChange, embedded, tone, resolveInteractionOperations, roleOf, }: ComposerPickerProps): import("react").JSX.Element | null;

package/lib/types/client/picker/PickerDirectory.d.ts

@@ -0,0 +1,31 @@
+import type { ModelSelection } from '@deepseek-ai/dsh-api-session-controller/types';
+import type { ModelDirectoryState } from '@deepseek-ai/dsh-client-ui-model-selection/client';
+import type { PlanCommitOutcome } from '../../picker/plan-review.ts';
+export type PickerDirectorySnapshot = Pick<ModelDirectoryState, 'current' | 'routable' | 'groups' | 'failures' | 'status' | 'error'>;
+export interface PickerDirectoryStore {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => PickerDirectorySnapshot;
+}
+/** Cohesive picker operations shared by composer, Plan Review, and plugin adapters. */
+export interface PickerDirectoryOperations {
+    getDirectorySnapshot: () => PickerDirectorySnapshot;
+    load: () => void;
+    select: (selection: ModelSelection) => Promise<PlanCommitOutcome>;
+}
+/** The exact state and operations one picker render consumes. */
+export interface PickerDirectoryView extends PickerDirectoryOperations {
+    snapshot: PickerDirectorySnapshot;
+}
+export interface ProviderOrderStore {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => readonly string[];
+}
+export interface PickerDirectoryFace extends PickerDirectoryOperations {
+    hooks: {
+        directory: PickerDirectoryStore;
+        providerOrder: ProviderOrderStore;
+    };
+}
+export declare function pickerDirectoryView(snapshot: PickerDirectorySnapshot, operations: PickerDirectoryOperations): PickerDirectoryView;
+/** Directory view whose groups follow the shared LLM Providers card order. */
+export declare function pickerDirectoryViewOrdered(snapshot: PickerDirectorySnapshot, operations: PickerDirectoryOperations, order: readonly string[], catalogKeys?: Readonly<Record<string, string>>): PickerDirectoryView;

package/lib/types/client/picker/PickerSeatBoundary.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react';
+interface PickerSeatBoundaryProps {
+    children: ReactNode;
+    errorLabel: (message: string) => string;
+}
+export declare function PickerSeatBoundary({ children, errorLabel }: PickerSeatBoundaryProps): import("react").JSX.Element;
+export {};