@deepseek-ai/dsh-llm-deepseek-api-key 0.2.1-rc.2 → 0.2.1-rc.4

package/README.i18n.yaml

@@ -3,26 +3,26 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm-deepseek-api-key/README.md
 /:
-  en: 3bc991d01c87c9c6
-  zh: ba63ebb46b72bc3e
+  en: d0825db7a1a9d8ee
+  zh: d0825db7a1a9d8ee
 /deepseek-ai-dsh-llm-deepseek-api-key:
   en: b6871195e386cc64
   zh: 742b05a3ca80883c
 /deepseek-ai-dsh-llm-deepseek-api-key/summary:
-  en: ad5a00f16f233d42
-  zh: 743d55599144836b
+  en: f937052cf8ff4812
+  zh: 899d61f5021136d6
 /deepseek-ai-dsh-llm-deepseek-api-key/table-of-contents:
   en: 23386452a66b2fbd
   zh: 4cf93c4bf17b3da2
 /deepseek-ai-dsh-llm-deepseek-api-key/use-this-package:
-  en: 10333177c9033b9e
-  zh: 069faa6a125cb6a9
+  en: 2aad8a660b90561d
+  zh: 3f425b3d1ea023e1
 /deepseek-ai-dsh-llm-deepseek-api-key/understand-the-implementation:
-  en: 002ac925beb4e75b
-  zh: 815d06f116604a09
+  en: d614c1ea3a9eb382
+  zh: 5ca070349bb22d56
 /deepseek-ai-dsh-llm-deepseek-api-key/further-exploration:
-  en: e8bf99d78aa7035f
-  zh: e4a74d2d48b6d271
+  en: 347659458510940c
+  zh: ccfb03e18b356a39
 /deepseek-ai-dsh-llm-deepseek-api-key/model-experience:
   en: 215e7ba838619b7b
   zh: a311da3843709f90
@@ -33,14 +33,14 @@
   en: e5624a2c7bb26e90
   zh: 44da0286a548f24a
 /deepseek-ai-dsh-llm-deepseek-api-key/model-experience/authenticated-model-requests/token-effect:
-  en: fecefb75b719c317
-  zh: f0c2322f657c5914
+  en: 9dd6430752202069
+  zh: 53068bf7f828156f
 /deepseek-ai-dsh-llm-deepseek-api-key/model-experience/authenticated-model-requests/kv-cache-effect:
-  en: 2004df60d997da79
-  zh: a215a6586b44746b
+  en: 8226f9d956013ad9
+  zh: bace9524b7acc1fa
 /deepseek-ai-dsh-llm-deepseek-api-key/known-limitations-and-deferred-work:
-  en: d5880c883b1b678f
-  zh: bf7a4da24ba75280
+  en: e0a41598c126c187
+  zh: 857ab65c27f41612
 /deepseek-ai-dsh-llm-deepseek-api-key/known-limitations-and-deferred-work/dev-note:
   en: 0525041e573e96b6
   zh: b05ed8d852498e6b

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "DeepSeek api-key authentication and model discovery."
+description: "DeepSeek API-key authentication, model discovery, and the official model listing."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Register authentication and model discovery for `deepseek-official`. This plugin shares the [Messages transport](../llm-deepseek/README.md) and owns credential resolution and catalog availability.
+Register authentication, model discovery, and the official model listing for `deepseek-official`. This plugin shares the [Messages transport](../llm-deepseek/README.md) and owns credential resolution, catalog availability, and model admission.
 
 Authentication resolution returns the validated API key in `x-api-key` for both Messages and Files requests.
 
@@ -37,17 +37,30 @@ Authentication resolution returns the validated API key in `x-api-key` for both
 
 The endpoint and credential reference come from one configuration resolution. In-flight requests retain that snapshot; subsequent updates affect subsequent calls. Account login state cannot change this route’s credential.
 
-`models` is an independently configurable catalog for this provider; defaults and protocol capabilities come from the shared transport. Discovery does not probe inference endpoints. The settings namespace is the Cordis entry id, or the plugin name without an entry. Product profiles retain the official entry id `llm-deepseek` and use `llm-deepseek-account` for the account route.
+`models` is an independently configurable catalog for this provider; defaults and protocol capabilities come from the shared transport. While `models` equals the built-in catalog and the Messages origin is the official API, `https://api.deepseek.com`, the route serves the official `GET https://api.deepseek.com/models` listing instead. Listing requests carry the API key in `x-api-key` and the harness `User-Agent`, and reject redirects; without an API key the route requests nothing. Any other endpoint, including one named by `baseURL` or `$DEEPSEEK_BASE_URL`, serves `models` and requests no listing. Discovery does not probe inference endpoints.
+
+The first access waits for the listing up to `modelsTimeoutMs`. Later accesses use the loaded listing and refresh it in the background once it is older than `modelsMaxAgeMs`; an idle route sends no requests. A failed or empty listing keeps the previous one; before any listing loads, the route serves the built-in catalog of the current version (`deepseek-flash` and `deepseek-v4-pro`). A listing HTTP 401 fails only that load. Each loaded listing, the first failure of a failing streak with the catalog it falls back to, and each listing entry hidden because its declarations are unreadable or unusable are written to stderr with the `[llm-deepseek-api-key]` tag; stdout remains available for protocol messages, and secrets are never logged.
+
+Listed models are offered, merged with this build's entries, and refused before network I/O with `CLIENT_UPGRADE_REQUIRED` or `MODEL_UNSUPPORTED` by the [account route's rules](../llm-deepseek-account/README.md#use-this-package); model ids the listing does not name pass through unchanged.
+
+A `models` list that differs from the built-in catalog replaces the catalog and stops listing requests; the Models page stores an edited catalog there. Removing that list, as **Restore defaults** on the Models page does, returns the route to the listing, and the next access loads the listing again even when the cached one is still fresh. A list identical to the built-in catalog counts as uncustomized.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `modelsTimeoutMs` | `5,000` | Deadline of one listing request and of a first-access wait |
+| `modelsMaxAgeMs` | `600,000` | Listing age after which the next access refreshes it; a failed load retries after the same age |
+
+The settings namespace is the Cordis entry id, or the plugin name without an entry. Product profiles retain the official entry id `llm-deepseek` and use `llm-deepseek-account` for the account route.
 
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
 
-Registrations and listeners dispose with the plugin. Shared Host wiring supplies attachments, request extensions, anonymous identity, and atomic retry-policy updates; this plugin registers only its own route.
+Registrations and listeners dispose with the plugin, and disposal aborts an in-flight listing request. Shared Host wiring supplies attachments, request extensions, anonymous identity, and atomic retry-policy updates; this plugin registers only its own route and uses the transport's `connect` and `admit` hooks for the listed catalog and the gate. The listing request, its cache, and catalog resolution come from the shared transport; the cache lives in memory and is keyed by endpoint and a SHA-256 of the key, so another key loads its own listing. A `loader/volatile-update` listener discards the cached listing whenever the route starts or stops following it.
 
 <a id="further-exploration"></a>
 ## Further Exploration
 
-[LLM streaming](../../../docs/subsystems/llm-streaming.md) · [Messages](../llm-deepseek/README.md)
+[LLM streaming](../../../docs/subsystems/llm-streaming.md) · [Messages](../llm-deepseek/README.md) · [Official listing decision](../../../.agents/notes/implemented/architecture/2026-10-22-deepseek-official-model-listing.md)
 
 <a id="model-experience"></a>
 ## Model Experience
@@ -60,17 +73,23 @@ Requests on `deepseek-official` add no model-visible text from this plugin; the
 
 #### Token effect
 
-Authentication and discovery add no input tokens; the selected model and request content determine actual usage.
+Authentication, discovery, and the listing add no input tokens. The followed listing sets each model's context window and default output cap, which each request's logged context and header record.
 
 #### KV Cache effect
 
-Credentials and catalog availability do not enter model input; the protocol transport owns request-prefix serialization.
+Credentials and catalog availability do not enter model input; the protocol transport owns request-prefix serialization. A listing change to a model's system prompt or tool update mode changes how later system prompt or tool updates are serialized.
 
 ## Known Limitations and Deferred Work
 
 <a id="known-limitations-and-deferred-work"></a>
 
-- The catalog is configuration metadata, not remote validation that a model is accepted; actual calls can still fail.
+- A configured catalog is configuration metadata, not remote validation that a model is accepted; actual calls can still fail.
+- The Models page shows the built-in catalog while the route follows the listing, so a model only the listing offers appears only in model selectors. Editing that catalog on the page stores the rows the page shows, which drops such a model until **Restore defaults**.
+- A customized catalog does not receive models the listing adds later.
+- Customization is judged against the running version's built-in catalog, so a saved `models` list equal to an earlier version's built-in catalog counts as customized once the built-in catalog changes and stops following the listing until **Restore defaults**.
+- The listing cache lives in memory; a start without network serves the built-in catalog until a listing loads.
+- A listing change during a running process reaches the Web model picker at its next catalog refresh; the plugin does not announce it.
+- When the current version can serve no listed model, the route offers no models.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "DeepSeek API key authentication and model discovery."
+description: "DeepSeek API-key authentication, model discovery, and the official model listing."
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-为 `deepseek-official` 注册独立的鉴权和模型发现插件。通过 [llm-deepseek](../llm-deepseek/README.zh.md) 共用 Messages 请求实现；本包拥有凭据解析和目录可用性判断。
+为 `deepseek-official` 注册鉴权、模型发现和官方模型列表。通过 [llm-deepseek](../llm-deepseek/README.zh.md) 共用 Messages 请求实现；本包拥有凭据解析、目录可用性判断和模型准入。
 
 鉴权解析将验证后的 API key 放入 `x-api-key`，供 Messages 和 Files 请求共同使用。
 
@@ -37,17 +37,30 @@ kind: "package-reference"
 
 端点和凭据引用来自同一次配置解析；进行中的请求保留该快照，后续配置更新仅影响后续请求。账号登录态不影响该路由使用的凭据。
 
-`models` 是该 provider 独立的可配置目录；默认值和协议能力来自共享传输包。目录判断不探测推理端点。设置命名空间采用 Cordis entry id，没有 entry 时采用插件名。产品保留 official 的 `llm-deepseek` entry id，账号使用 `llm-deepseek-account`。
+`models` 是该 provider 独立的可配置目录；默认值和协议能力来自共享传输包。当 `models` 等于内置目录、且 Messages 的 origin 是官方 API `https://api.deepseek.com` 时，路由改为提供官方 `GET https://api.deepseek.com/models` 列表。列表请求用 `x-api-key` 携带 API key，带上 harness 的 `User-Agent`，并拒绝重定向；没有 API key 时不发任何请求。其他端点，包括由 `baseURL` 或 `$DEEPSEEK_BASE_URL` 指定的端点，提供 `models`，不请求列表。目录判断不探测推理端点。
+
+第一次访问会等待列表，最长 `modelsTimeoutMs`。之后的访问直接使用已加载的列表，列表超过 `modelsMaxAgeMs` 后在后台刷新；路由空闲时不发请求。获取失败或得到空列表时保留上一份；还没有加载到任何列表时，路由提供当前版本内置的目录（`deepseek-flash` 与 `deepseek-v4-pro`）。列表请求返回 HTTP 401 只让这一次加载失败。每次加载成功、连续失败中的第一次失败及其退回的目录、以及每个因声明无法读取或不可用而被隐藏的列表条目，都会以 `[llm-deepseek-api-key]` 标签写到 stderr；stdout 保留给协议消息，且不记录任何密钥。
+
+列出的模型按[账号路由的规则](../llm-deepseek-account/README.zh.md#use-this-package)提供、与本版本的内置条目合并，并在网络请求之前以 `CLIENT_UPGRADE_REQUIRED` 或 `MODEL_UNSUPPORTED` 拒绝；列表没有列出的模型 id 照常透传。
+
+与内置目录不同的 `models` 列表会替换整个目录，并停止请求列表；模型页把编辑后的目录存在这里。删除这个列表（即模型页上的**恢复默认模型**）后，路由重新使用列表，即使缓存的列表尚未过期，下一次访问也会重新加载。与内置目录完全相同的列表视为未自定义。
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `modelsTimeoutMs` | `5,000` | 单次列表请求以及首次访问等待的上限 |
+| `modelsMaxAgeMs` | `600,000` | 列表超过这个时长后，下一次访问时刷新；获取失败后同样在这个时长后重试 |
+
+设置命名空间采用 Cordis entry id，没有 entry 时采用插件名。产品保留 official 的 `llm-deepseek` entry id，账号使用 `llm-deepseek-account`。
 
 <a id="understand-the-implementation"></a>
 ## 理解实现
 
-注册和监听随插件生命周期释放。共享 Host 绑定提供附件访问、请求扩展、匿名标识和重试策略的原子更新；本包只注册自己的路由。
+注册和监听随插件生命周期释放，释放时会中止进行中的列表请求。共享 Host 绑定提供附件访问、请求扩展、匿名标识和重试策略的原子更新；本包只注册自己的路由，并通过传输层的 `connect` 与 `admit` 钩子接入列表目录和门控。列表请求、缓存和目录解析来自共享传输包；缓存只在内存中，以端点和 API key 的 SHA-256 为键，因此换一个 key 会加载它自己的列表。一个 `loader/volatile-update` 监听器在路由开始或停止使用列表时丢弃缓存的列表。
 
 <a id="further-exploration"></a>
 ## 进一步探索
 
-[LLM streaming](../../../docs/subsystems/llm-streaming.zh.md) · [Messages](../llm-deepseek/README.zh.md)
+[LLM streaming](../../../docs/subsystems/llm-streaming.zh.md) · [Messages](../llm-deepseek/README.zh.md) · [官方列表决策](../../../.agents/notes/implemented/architecture/2026-10-22-deepseek-official-model-listing.zh.md)
 
 <a id="model-experience"></a>
 ## 模型体验
@@ -60,17 +73,23 @@ kind: "package-reference"
 
 #### Token effect
 
-鉴权和目录过滤不增加输入 token；实际调用的 token 由所选模型与请求内容决定。
+鉴权、目录过滤和列表都不增加输入 token。所使用的列表决定每个模型的上下文窗口和默认输出上限，每次请求记录的上下文和请求头会写明这些值。
 
 #### KV Cache effect
 
-凭据与目录可用性不进入模型输入；协议传输拥有请求前缀的序列化。
+凭据与目录可用性不进入模型输入；协议传输拥有请求前缀的序列化。列表改变某个模型的 system prompt 模式或工具更新模式时，之后的 system prompt 更新或工具更新的序列化方式随之改变。
 
 ## 已知限制与后续工作
 
 <a id="known-limitations-and-deferred-work"></a>
 
-- 目录是配置元数据，不验证远端是否接受模型；实际调用仍可能失败。
+- 配置的目录是配置元数据，不验证远端是否接受模型；实际调用仍可能失败。
+- 路由使用列表时，模型页显示的仍是内置目录，因此只有列表提供的模型只出现在模型选择器中。在模型页编辑目录会保存页面上显示的行，这类模型会消失，直到点**恢复默认模型**。
+- 自定义的目录收不到列表之后新增的模型。
+- 是否自定义按当前版本的内置目录判断：保存的 `models` 列表若等于旧版本的内置目录，内置目录变化后就算作自定义，不再跟随列表，直到点**恢复默认模型**。
+- 列表缓存只在内存中；没有网络的启动会一直提供内置目录，直到加载到列表。
+- 进程运行期间的列表变化在 Web 模型选择器下一次刷新目录时生效；插件不主动通知。
+- 当前版本不能用任何已列出的模型时，路由不提供模型。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -1,11 +1,14 @@
-import { LlmError, assertUsableApiKey } from "@deepseek-ai/dsh-llm";
+import { APP_IDENTITY, LlmError, assertUsableApiKey } from "@deepseek-ai/dsh-llm";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
-import { catalogModelInfo, deepSeekConfigFields, plainOptions as plainOptions$1, registerDeepSeekProvider, resolveAdapterOptions as resolveAdapterOptions$1 } from "@deepseek-ai/dsh-llm-deepseek";
+import { ModelListingCache, PUBLIC_BASE_URL, catalogModelInfo, deepSeekConfigFields, isBuiltInCatalog, modelListingConfigFields, modelListingURL, plainOptions as plainOptions$1, refuseListedModel, registerDeepSeekProvider, requestModelListing, resolveAdapterOptions as resolveAdapterOptions$1, resolveListedCatalog, resolveListingTiming } from "@deepseek-ai/dsh-llm-deepseek";
 import z from "@deepseek-ai/schemastery";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 //#region lib/types/config.js
+/** Origin of the official API, the only endpoint whose `/models` listing this route follows. */
+const OFFICIAL_ORIGIN = new URL(PUBLIC_BASE_URL).origin;
 const Config = z.object({
 	...deepSeekConfigFields,
+	...modelListingConfigFields,
 	apiKeyEnv: z.string().role("credential-ref").default("DEEPSEEK_API_KEY").volatile()
 });
 /** Read one validated provider configuration.
@@ -18,15 +21,23 @@ function plainOptions(config) {
 		apiKeyEnv: config.apiKeyEnv.get()
 	};
 }
-/** Resolve API-key and protocol settings together.
+/** Resolve API-key, listing, and protocol settings together.
 * @param config - raw deployment settings.
 * @param environment - application launch environment.
-* @returns validated endpoint facts and the matching credential reference.
+* @returns validated endpoint facts, the matching credential reference, and the listing the catalog follows.
 */
 function resolveAdapterOptions(config, environment) {
+	const { modelsTimeoutMs: _timeout, modelsMaxAgeMs: _maxAge, apiKeyEnv, ...messages } = config;
+	const timing = resolveListingTiming(config, "llm-deepseek-api-key");
+	const connection = resolveAdapterOptions$1(messages, environment);
+	const listed = new URL(connection.baseURL).origin === OFFICIAL_ORIGIN && isBuiltInCatalog(connection.models);
 	return {
-		...resolveAdapterOptions$1(config, environment),
-		apiKeyEnv: credentialRef(config.apiKeyEnv ?? "DEEPSEEK_API_KEY")
+		...connection,
+		apiKeyEnv: credentialRef(apiKeyEnv ?? "DEEPSEEK_API_KEY"),
+		...listed ? { listing: {
+			url: modelListingURL(connection.baseURL),
+			...timing
+		} } : {}
 	};
 }
 //#endregion
@@ -34,6 +45,8 @@ function resolveAdapterOptions(config, environment) {
 const name = "llm-deepseek-api-key";
 const inject = ["llm"];
 const PROVIDER = "deepseek-official";
+/** Console tag of listing diagnostics; product profiles mount no console exporter for `ctx.logger`. */
+const LOG_TAG = "[llm-deepseek-api-key]";
 function apply(ctx, config) {
 	const options = () => resolveAdapterOptions(plainOptions(config), launchEnvironmentOf(ctx));
 	options();
@@ -49,6 +62,52 @@ function apply(ctx, config) {
 		}
 		throw new LlmError(`llm-deepseek: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials service (the web Models page writes it), or export ${ref} in the launching environment`, "MISSING_CREDENTIAL");
 	};
+	/** The API key, or `undefined` when none is configured; other credential failures propagate. */
+	const presentApiKey = async (connection) => {
+		try {
+			return await resolveApiKey(connection);
+		} catch (error) {
+			if (error instanceof LlmError && error.code === "MISSING_CREDENTIAL") return void 0;
+			throw error;
+		}
+	};
+	const listings = new ModelListingCache({
+		credential: async () => presentApiKey(options()),
+		load: (url, apiKey, signal) => requestModelListing(url, { "x-api-key": apiKey }, signal),
+		now: () => Date.now(),
+		info: (message) => {
+			console.error(LOG_TAG, message);
+		},
+		warn: (message) => {
+			console.warn(LOG_TAG, message);
+		}
+	});
+	let reportedListing;
+	/** Resolve the catalog of one operation, reporting each listing's hidden entries once. */
+	const connectionOf = (connection, view) => {
+		if (view === void 0) return {
+			...connection,
+			offered: connection.models,
+			refusals: /* @__PURE__ */ new Map()
+		};
+		const catalog = resolveListedCatalog({
+			listing: view.listing?.entries,
+			supported: connection.models,
+			overrides: {},
+			routeMaxTokens: connection.maxTokens,
+			clientVersion: APP_IDENTITY.version
+		});
+		if (view.listing !== reportedListing) {
+			reportedListing = view.listing;
+			for (const problem of catalog.problems) console.warn(LOG_TAG, problem);
+		}
+		return {
+			...connection,
+			models: catalog.resolution,
+			offered: catalog.offered,
+			refusals: catalog.refusals
+		};
+	};
 	ctx.llm.registerConfigurableProviders([{
 		provider: PROVIDER,
 		displayName: "DeepSeek",
@@ -56,20 +115,51 @@ function apply(ctx, config) {
 		settingsPath: []
 	}]);
 	registerDeepSeekProvider(ctx, PROVIDER, {
-		options,
 		providerName: "DeepSeek",
-		resolveAuth: async (connection) => ({ headers: { "x-api-key": await resolveApiKey(connection) } }),
-		discoverModels: async (provider) => {
+		options: () => {
 			const connection = options();
+			return connectionOf(connection, connection.listing === void 0 ? void 0 : listings.current());
+		},
+		connect: async (signal) => {
+			const connection = options();
+			if (connection.listing === void 0) return connectionOf(connection, void 0);
+			let view;
 			try {
-				await resolveApiKey(connection);
+				view = await listings.view(connection.listing, signal);
 			} catch (error) {
-				if (error instanceof LlmError && error.code === "MISSING_CREDENTIAL") return [];
-				throw error;
+				if (signal?.aborted === true) throw error;
+				return connectionOf(connection, void 0);
 			}
-			return connection.models.map((model) => catalogModelInfo(provider, model));
+			return connectionOf(connection, view);
+		},
+		resolveAuth: async (connection) => ({ headers: { "x-api-key": await resolveApiKey(connection) } }),
+		admit: (connection, model) => {
+			refuseListedModel(model, connection.refusals.get(model));
+		},
+		discoverModels: async (provider) => {
+			const connection = options();
+			if (connection.listing === void 0) {
+				if (await presentApiKey(connection) === void 0) return [];
+				return connection.models.map((model) => catalogModelInfo(provider, model));
+			}
+			const view = await listings.view(connection.listing);
+			return view.authenticated ? connectionOf(connection, view).offered.map((model) => catalogModelInfo(provider, model)) : [];
+		}
+	});
+	let following = options().listing !== void 0;
+	ctx.on("loader/volatile-update", () => {
+		let next;
+		try {
+			next = options().listing !== void 0;
+		} catch (_rejectedConfiguration) {
+			return;
 		}
+		if (next !== following) listings.invalidate();
+		following = next;
 	});
+	ctx.effect(() => () => {
+		listings.dispose();
+	}, "llm-deepseek-api-key: model listing");
 }
 //#endregion
 export { Config, apply, inject, name, plainOptions, resolveAdapterOptions };

package/lib/types/config.d.ts

@@ -1,17 +1,18 @@
-/** API-key configuration resolved together with one Messages endpoint generation. */
+/** API-key configuration resolved together with one Messages endpoint generation and its model listing. */
 import type { Volatile } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { type CredentialRef } from '@deepseek-ai/dsh-credentials';
 import type { LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
-import { type Config as ProtocolConfig } from '@deepseek-ai/dsh-llm-deepseek';
-import type { Options as ProtocolOptions, DeepSeekConnectionOptions } from '@deepseek-ai/dsh-llm-deepseek';
+import type { Config as ProtocolConfig, DeepSeekConnectionOptions, ListingSettings, ModelListingConfig, ModelListingOptions, Options as ProtocolOptions } from '@deepseek-ai/dsh-llm-deepseek';
 /** Messages configuration with a per-request API-key reference. */
-export interface Config extends ProtocolConfig {
+export interface Config extends ProtocolConfig, ModelListingConfig {
     /** Credential reference resolved per request; defaults to DEEPSEEK_API_KEY. */
     apiKeyEnv: Volatile<string>;
 }
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     apiKeyEnv: z<string, string, "volatile-defined">;
+    modelsTimeoutMs: z<number, number, "volatile-defined">;
+    modelsMaxAgeMs: z<number, number, "volatile-defined">;
     baseURL: z<string, string, "volatile">;
     thinking: z<"enabled" | "disabled", "enabled" | "disabled", "volatile">;
     reasoningEffort: z<"low" | "off" | "high" | "max", "low" | "off" | "high" | "max", "volatile">;
@@ -32,6 +33,8 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     retryPolicy: z<NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, "volatile">;
 }>>, Schemastery.ObjectT<NoInfer<{
     apiKeyEnv: z<string, string, "volatile-defined">;
+    modelsTimeoutMs: z<number, number, "volatile-defined">;
+    modelsMaxAgeMs: z<number, number, "volatile-defined">;
     baseURL: z<string, string, "volatile">;
     thinking: z<"enabled" | "disabled", "enabled" | "disabled", "volatile">;
     reasoningEffort: z<"low" | "off" | "high" | "max", "low" | "off" | "high" | "max", "volatile">;
@@ -52,23 +55,28 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     retryPolicy: z<NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, "volatile">;
 }>>, "plain">;
 /** Plain deployment inputs for the API-key provider. */
-export type Options = ProtocolOptions & {
+export type Options = ProtocolOptions & ModelListingOptions & {
     apiKeyEnv?: string;
 };
 /** Endpoint and credential reference captured from the same configuration generation. */
 export interface ResolvedDeepSeekOptions extends DeepSeekConnectionOptions {
     /** Credential reference used only for this connection snapshot. */
     apiKeyEnv: CredentialRef;
+    /**
+     * The official `/models` listing this generation follows; absent when `models`
+     * differs from the built-in catalog or the endpoint is not the official API.
+     */
+    listing?: ListingSettings;
 }
 /** Read one validated provider configuration.
  * @param config - live plugin configuration.
  * @returns detached resolver inputs.
  */
 export declare function plainOptions(config: Config): Options;
-/** Resolve API-key and protocol settings together.
+/** Resolve API-key, listing, and protocol settings together.
  * @param config - raw deployment settings.
  * @param environment - application launch environment.
- * @returns validated endpoint facts and the matching credential reference.
+ * @returns validated endpoint facts, the matching credential reference, and the listing the catalog follows.
  */
 export declare function resolveAdapterOptions(config: Options, environment?: LaunchEnvironmentSnapshot): ResolvedDeepSeekOptions;
 //# sourceMappingURL=config.d.ts.map

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-/** API-key authentication and credential-gated discovery for the official DeepSeek route. */
+/** API-key authentication, credential-gated discovery, and the official model listing for the official DeepSeek route. */
 import type { Context } from '@deepseek-ai/cordis';
 import { Config } from './config.ts';
 export { Config, plainOptions, resolveAdapterOptions } from './config.ts';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-deepseek-api-key",
   "description": "DeepSeek api-key provider authentication and discovery",
-  "version": "0.2.1-rc.2",
+  "version": "0.2.1-rc.4",
   "publishConfig": {
     "access": "public"
   },
@@ -30,18 +30,18 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.5",
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-credentials": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.4",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-rc.4",
+    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.4",
+    "@deepseek-ai/dsh-credentials": "0.2.1-rc.4",
     "@deepseek-ai/cordis-plugin-loader": "~1.0.6"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "~4.0.5",
-    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-credentials": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.4",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-rc.4",
+    "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.4",
+    "@deepseek-ai/dsh-credentials": "0.2.1-rc.4",
     "@deepseek-ai/cordis-plugin-loader": "~1.0.6"
   },
   "peerDependenciesMeta": {