@deepseek-ai/dsh-llm-pi-ai 0.1.2-alpha.2 → 0.1.2-alpha.4

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm-pi-ai/README.md
-README.md: dcafde78e176bd0acd142145d651d6d5b5539626
-README.zh.md: a7292638b8449d7192d3e003f0377967d11ef94d
+README.md: 5994a72f28b0a52890cb7bf7a5bc2ee33eedf418
+README.zh.md: 5f1c893128714caf24941943c57eaf3ab43314e0

package/README.md

@@ -106,7 +106,7 @@ Profiles are re-read once per operation through the optional settings seam: the
 
 ### Discover models from endpoints
 
-The plugin answers "which models can this provider serve?" for a route a configuration surface is editing or drafting. A route the installed catalog ships is answered from that catalog with no network call; only a route the catalog does not describe is interrogated over the wire (`openai-completions` and `openai-responses` shapes). The reply is candidate metadata a surface may offer for adoption — nothing is stored, and `settings.yaml` remains the only thing that decides what a route serves.
+The plugin answers "which models can this provider serve?" for a route a configuration surface is editing or drafting. A route the installed catalog ships is answered from that catalog with no network call; only a route the catalog does not describe is interrogated over the wire (`openai-completions` and `openai-responses` shapes). A named configured route supplies its stored credential and profile `headers` inside the Host, so deployment headers configured through `settings.yaml` or Cordis config reach `GET /models` without becoming discovery-request or Models-page fields; a key typed into the form still wins over the stored credential. The reply is candidate metadata a surface may offer for adoption — nothing is stored, and `settings.yaml` remains the only thing that decides what a route serves.
 
 ### Failures and recovery
 
@@ -210,7 +210,7 @@ These limits define where the adapter stops and future work begins. They are cur
 - **Provider-native discovery answers through this plugin's ambient context** — a route naming no credential defers to the catalog provider's own resolution, which asks for environment values (`AZURE_OPENAI_API_KEY`, `AWS_PROFILE`, and each provider's own set) and for local credential files. Both questions are answered here: the credential seam is consulted before the process environment, and file existence is checked against the host process's filesystem with `~` expanded. What it cannot do is *read* a credential file's contents — a provider that parses `~/.aws/credentials` itself does so directly, outside the seam.
 - **Settings can add or override routes, not remove composition routes** — the user layer merges over the composition base, so deleting a `cordis.yml`-provided provider is a composition change.
 - **The layered merge has no delete for dict keys** — a `reasoningEfforts` level, `modelOverrides` entry, or `compat` field the base declares can be overridden but not removed by the user layer.
-- **`headers` can carry a credential the redactor never sees** — the profile's `headers` dict is plain strings; store credentials as `apiKeyEnv` references.
+- **`headers` can carry a credential the redactor never sees** — profile resolution rejects names and values Fetch cannot represent, but the dict remains plain strings; store credentials as `apiKeyEnv` references.
 - **A route's catalog never refreshes itself** — the catalog is whatever `settings.yaml` says; nothing here queries a provider for the models it serves.
 - **One wire protocol per route** — a mixed-protocol catalog route cannot host a model of the other protocol; splitting the provider across two route keys is the workaround.
 - **A modality declaration is not verified** — a model declaring `image` its gateway does not serve is refused by the provider after prompt admission. The durable image remains in history and the same misdeclared model can fail again; switching to a text-only model remains possible because the shared LLM runtime projects image references into stable text for that request.
@@ -232,3 +232,5 @@ This Dev Note is non-authoritative working context: undecided directions and not
 - The `compat` switch set is pinned to pi-ai's compat types by drift gates; an upstream upgrade that adds a field, gives a further protocol a compat type, or widens a value union fails the build until someone classifies it.
 
 </details>
+
+**Runtime invariant:** No companion is published. This package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam.

package/README.zh.md

@@ -106,7 +106,7 @@ profile 通过可选 settings seam 每次操作重新读取：base 与用户的
 
 ### 从端点发现模型
 
-插件会回答"该提供方可以提供哪些模型？"，供配置界面正在编辑或起草的路由使用。已安装目录提供的路由直接由目录回答，不发网络请求；只有目录未描述的路由才会经网络询问（`openai-completions` 与 `openai-responses` 形状）。回答是界面可以提供给用户采纳的候选元数据——不存储任何内容，`settings.yaml` 仍然是决定路由服务内容的唯一事实。
+插件会回答"该提供方可以提供哪些模型？"，供配置界面正在编辑或起草的路由使用。已安装目录提供的路由直接由目录回答，不发网络请求；只有目录未描述的路由才会经网络询问（`openai-completions` 与 `openai-responses` 形状）。已配置且具名的路由会在 Host 内部提供已存凭据与 profile `headers`，因此通过 `settings.yaml` 或 Cordis 配置设置的部署标头可以到达 `GET /models`，但不会成为发现请求或 Models 页面的字段；表单中新键入的密钥仍优先于已存凭据。回答是界面可以提供给用户采纳的候选元数据——不存储任何内容，`settings.yaml` 仍然是决定路由服务内容的唯一事实。
 
 ### 失败与恢复
 
@@ -210,7 +210,7 @@ pi-ai 事件变成 harness 的推理、文本、工具调用、用量与 finish
 - **提供方原生发现经本插件的 ambient context 回答**——不点名凭据的路由交由目录提供方自身解析，它会询问环境值（`AZURE_OPENAI_API_KEY`、`AWS_PROFILE` 及各提供方自有集合）与本地凭据文件。两个问题都在这里得到回答：凭据 seam 先于进程环境被查询，文件存在性则针对宿主进程的文件系统以 `~` 展开后检查。它做不到的是*读取*凭据文件内容——自行解析 `~/.aws/credentials` 的提供方会直接读取，不经该 seam。
 - **设置可以新增或覆盖路由，不能移除组合路由**——用户层覆盖组合 base，因此删除 `cordis.yml` 提供的提供方属于组合变更。
 - **分层合并对字典键没有删除**——base 声明的 `reasoningEfforts` 等级、`modelOverrides` 条目或 `compat` 字段可以被用户层覆盖，但不能被移除。
-- **`headers` 可以携带 redactor 永远看不到的凭据**——profile 的 `headers` 字典是纯字符串；以 `apiKeyEnv` 引用存储凭据。
+- **`headers` 可以携带 redactor 永远看不到的凭据**——profile 解析会拒绝 Fetch 无法表示的名称与值，但该字典仍是纯字符串；以 `apiKeyEnv` 引用存储凭据。
 - **路由目录不会自行刷新**——目录就是 `settings.yaml` 的内容；这里没有任何机制向提供方查询它提供的模型。
 - **每条路由一种协议格式**——混合协议目录路由无法承载另一协议格式的模型；把提供方拆到两个路由键是变通办法。
 - **模态声明不受校验**——声明 `image` 而其网关不支持的模型会在提示词准入后被提供方拒绝。持久图片仍留在历史中，同一误声明模型可能再次失败；切换到纯文本模型仍然可行，因为共享 LLM 运行时会针对该请求把图片引用投影为稳定文本。
@@ -232,3 +232,5 @@ pi-ai 事件变成 harness 的推理、文本、工具调用、用量与 finish
 - `compat` 开关集合由漂移门禁钉在 pi-ai 的 compat 类型上；上游升级若新增字段、为更多协议赋予 compat 类型或扩大值联合，会在有人分类前让构建失败。
 
 </details>
+
+**运行时不变式：** 不发布伴生入口。本包没有独立事件序列或可变数据关系，相关约定在所属 seam 强制执行。

package/lib/index.js

@@ -984,7 +984,7 @@ const Config = z.object({ providers: z.dict(profile).default({}) });
 * renders and the value an absent section resolves to; wrapping it would break
 * both.
 * @param config - the resolved section to check.
-* @throws Error naming the route and model that cannot be served.
+* @throws Error naming the route and configuration entry that cannot be served.
 */
 function assertServiceable(config) {
 	resolveProfiles(config.providers);
@@ -995,6 +995,14 @@ function rejectRemovedFields(provider, source) {
 	if ("provider" in legacy) throw new Error(`llm-pi-ai: provider "${provider}" sets "provider", which moved to the providers dict key`);
 	if ("maxRetries" in legacy || "maxRetryDelayMs" in legacy) throw new Error(`llm-pi-ai: provider "${provider}" sets maxRetries or maxRetryDelayMs, which were removed; compose agent recovery with dsh-llm-retry`);
 }
+/** Reject a profile header that Fetch cannot put on a provider request. */
+function assertValidHeaders(provider, headers) {
+	for (const [name, value] of Object.entries(headers ?? {})) try {
+		new Headers([[name, value]]);
+	} catch {
+		throw new Error(`llm-pi-ai: provider "${provider}" header "${name}" is not valid for Fetch; use a valid HTTP field name and a single-line value representable as bytes`);
+	}
+}
 /**
 * Validate profiles and return a detached route-keyed map suitable for
 * per-request reads. This is the one explicit resolve step, so an omitted dict
@@ -1012,6 +1020,7 @@ function resolveProfiles(providers) {
 		if (provider.length === 0) throw new Error("llm-pi-ai: provider names must be non-empty");
 		if (source.baseURL !== void 0 && source.baseURL.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" has an empty baseURL`);
 		if (source.displayName !== void 0 && source.displayName.length === 0) throw new Error(`llm-pi-ai: provider "${provider}" has an empty displayName`);
+		assertValidHeaders(provider, source.headers);
 		const streamIdleTimeoutMs = source.streamIdleTimeoutMs ?? 3e5;
 		if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) throw new Error(`llm-pi-ai: provider "${provider}" streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
 		const maxRequestImageBytes = source.maxRequestImageBytes ?? 20971520;
@@ -2140,16 +2149,14 @@ function usableProbeKey(raw) {
 /**
 * Interrogate one draft provider endpoint for the models it advertises.
 * @param request - the endpoint, protocol, and one-shot credential to use.
-* @param storedApiKey - the credential the named route already stored, asked
-*   for only when the draft carries none and only on the path that reaches the
-*   network. A configuration surface never holds a stored secret — it edits a
-*   redacted descriptor — so without this an already-configured route would be
-*   interrogated unauthenticated and answer 401.
+* @param storedProfile - Host-owned headers and lazy credential resolution for
+*   the named route. It is read only on the path that reaches the network; the
+*   credential is resolved only when the draft carries none.
 * @returns the advertised models in endpoint order.
 * @throws LlmError when the protocol has no readable listing, the endpoint
 *   refuses or fails the request, or the reply is not a model listing.
 */
-async function discoverModels(request, storedApiKey) {
+async function discoverModels(request, storedProfile) {
 	if (request.provider !== void 0) {
 		const installed = catalogModels(request.provider);
 		if (installed.size > 0) return [...installed.values()].map((model) => ({
@@ -2163,17 +2170,18 @@ async function discoverModels(request, storedApiKey) {
 	const api = request.api ?? "openai-completions";
 	if (!LISTABLE_PROTOCOLS.has(api)) throw new LlmError(`pi-ai protocol "${api}" has no model listing this build can read; enter this provider's models by hand`, "DISCOVERY_UNSUPPORTED");
 	const url = listingUrl(request.baseURL);
-	const supplied = request.apiKey ?? await storedApiKey?.();
+	const stored = storedProfile?.();
+	const supplied = request.apiKey ?? await stored?.resolveApiKey();
 	const apiKey = supplied === void 0 ? void 0 : usableProbeKey(supplied);
 	let response;
 	try {
+		const headers = new Headers(stored?.headers === void 0 ? void 0 : Object.entries(stored.headers));
+		headers.set("accept", "application/json");
+		if (apiKey !== void 0) headers.set("authorization", `Bearer ${apiKey}`);
+		for (const [name, value] of Object.entries(attributionHeaders())) headers.set(name, value);
 		response = await fetch(url, {
 			method: "GET",
-			headers: {
-				accept: "application/json",
-				...apiKey === void 0 ? {} : { authorization: `Bearer ${apiKey}` },
-				...attributionHeaders()
-			},
+			headers,
 			...request.signal === void 0 ? {} : { signal: request.signal }
 		});
 	} catch (error) {
@@ -2503,23 +2511,20 @@ function apply(ctx, config) {
 		directoryFacts = entries;
 	};
 	ensureDirectory();
-	/**
-	* The credential a named route already resolves, for an interrogation whose
-	* draft carries none. A route being declared for the first time names no
-	* profile yet, and a profile that names no credential defers to pi-ai's own
-	* discovery, so both answer `undefined` and the endpoint is asked
-	* unauthenticated — the same posture a request to that route would take.
-	*/
-	const storedApiKey = async (provider) => {
+	/** Host-owned request inputs for discovery of one configured route. */
+	const storedDiscoveryProfile = (provider) => {
 		if (provider === void 0) return void 0;
 		const profile = profiles().get(provider);
 		if (profile === void 0) return void 0;
-		return resolveApiKey(provider, profile);
+		return {
+			headers: profile.headers,
+			resolveApiKey: () => resolveApiKey(provider, profile)
+		};
 	};
 	ctx.llm.registerModelDiscovery(NS, (request, signal) => discoverModels({
 		...request,
 		...signal === void 0 ? {} : { signal }
-	}, () => storedApiKey(request.provider)));
+	}, () => storedDiscoveryProfile(request.provider)));
 	let registration;
 	let registeredFacts;
 	const ensureRegistrationFacts = () => {

package/lib/types/config.d.ts

@@ -110,7 +110,7 @@ export interface PiAiProviderProfile {
      * to answer instead.
      */
     defaultInput?: PiAiModality[];
-    /** Provider request headers; Harness attribution wins reserved names. */
+    /** Provider request headers, validated against Fetch when the profile resolves; Harness attribution wins reserved names. */
     headers?: Record<string, string>;
     /** Provider-neutral pi-ai reasoning level. */
     reasoning?: ModelThinkingLevel;
@@ -196,7 +196,7 @@ export declare const Config: z<Config>;
  * renders and the value an absent section resolves to; wrapping it would break
  * both.
  * @param config - the resolved section to check.
- * @throws Error naming the route and model that cannot be served.
+ * @throws Error naming the route and configuration entry that cannot be served.
  */
 export declare function assertServiceable(config: Config): void;
 /**

package/lib/types/discovery.d.ts

@@ -22,17 +22,22 @@
  * @module dsh-llm-pi-ai/discovery
  */
 import type { LlmDiscoveredModel, LlmModelDiscoveryOperation } from '@deepseek-ai/dsh-llm';
+/** Host-owned profile inputs that a configuration draft deliberately omits. */
+export interface StoredModelDiscoveryProfile {
+    /** Deployment headers configured on the named route. */
+    readonly headers: Readonly<Record<string, string>> | undefined;
+    /** Resolve the named route's credential only when the draft carries none. */
+    readonly resolveApiKey: () => Promise<string | undefined>;
+}
 /**
  * Interrogate one draft provider endpoint for the models it advertises.
  * @param request - the endpoint, protocol, and one-shot credential to use.
- * @param storedApiKey - the credential the named route already stored, asked
- *   for only when the draft carries none and only on the path that reaches the
- *   network. A configuration surface never holds a stored secret — it edits a
- *   redacted descriptor — so without this an already-configured route would be
- *   interrogated unauthenticated and answer 401.
+ * @param storedProfile - Host-owned headers and lazy credential resolution for
+ *   the named route. It is read only on the path that reaches the network; the
+ *   credential is resolved only when the draft carries none.
  * @returns the advertised models in endpoint order.
  * @throws LlmError when the protocol has no readable listing, the endpoint
  *   refuses or fails the request, or the reply is not a model listing.
  */
-export declare function discoverModels(request: LlmModelDiscoveryOperation, storedApiKey?: () => Promise<string | undefined>): Promise<readonly LlmDiscoveredModel[]>;
+export declare function discoverModels(request: LlmModelDiscoveryOperation, storedProfile?: () => StoredModelDiscoveryProfile | undefined): Promise<readonly LlmDiscoveredModel[]>;
 //# sourceMappingURL=discovery.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm-pi-ai",
   "description": "pi-ai-backed DeepSeek adapter for the DeepSeek Harness LLM seam (design-verification twin of dsh-llm-deepseek)",
-  "version": "0.1.2-alpha.2",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -18,48 +18,41 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
-    "lib/invariant.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-authorization": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-fs": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-fs": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-authorization": "^0.1.2-alpha.4"
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.84.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.4",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-authorization": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-llm-deepseek": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-fs": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-attachment": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-authorization": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-fs": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-llm-deepseek": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.4"
   }
 }

package/lib/invariant.js

@@ -1,23 +0,0 @@
-//#region lib/types/invariant.js
-/**
-* Package-owned invariant companion for `@deepseek-ai/dsh-llm-pi-ai`.
-* @module @deepseek-ai/dsh-llm-pi-ai/invariant
-*/
-const PACKAGE_NAME = "@deepseek-ai/dsh-llm-pi-ai";
-/** Cordis companion plugin name. */
-const name = "llm-pi-ai-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* No runtime invariant: this package exposes no independent event sequence or mutable data relation
-* beyond contracts enforced at its owning seam.
-*/
-const install = () => {};
-/**
-* Register this package's invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-llm-pi-ai`.
- * @module @deepseek-ai/dsh-llm-pi-ai/invariant
- */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "llm-pi-ai-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export declare const apply: (ctx: Context) => Promise<() => void>;
-//# sourceMappingURL=invariant.d.ts.map