@sema-agent/server 7.150.0 → 7.152.0

package/dist/model-entry-headers.d.ts

@@ -27,16 +27,15 @@
  * 执法点 = [ref] 的逐条判据 `judgeCatalogEntry`(同一个码、同一条 warn、同一条「显式选中它 ⇒ `request.model_unavailable`」的路),
  * 其余条目照常服务。拒因与 warn **只回显名字**(过 {@link displayHeaderName}),从不回显值。
  *
- * ## 两条读腿今天到不了这里(候裁「settings-schema `ModelEntry` 加 `headers`」,[ref] 字段归 server 自持)
- * settings-schema 6.3.0 的 `ModelEntry` 没有这个键 ⇒ 远端 `readEffectiveWire` 与本地 `FileConfigStore` 都 strip 它(并报未知键)。
- * 本模块服务的输入今天只有绕过读腿的那几条(盘上 LKG / 手写 effective);字段进 schema 之日,`config-provider.ts` 的本地投影加一行即通,
- * `test/catalog-entry-headers.test.ts` 的 🚧 [ref]-schema 两格翻红逼销账。**词表不在 schema 里另抄一份**:schema 的那个键应当是
- * 承载形(与 `compat` 同一种 parse-transparent + 自由形安全判),判据仍是本模块这一处 —— 或者整张表搬进 schema、本仓 import;
- * 二选一候裁,不许两处各有一份。
+ * ## 容器形不是本模块的判据(settings-schema 26.0.0 起)
+ * 「`headers` 是一只纯 JSON 对象」由契约包判(`ModelEntry` 的自由形对象键,与 `extraBody` 同一只判官):严写面整份拒,读腿上那一条目 `entry-dropped`
+ * (唯一 / 被引用时 `models` 整域退缺省并发 `domain-defaulted`),绕过读腿的输入在 `judgeCatalogEntry` 首判(`ModelEntry.safeParse`)拒、字段点名 `headers`。
+ * 到这里的袋恒是对象(型 `ModelEntry["headers"]`);本模块只判契约不判的那三件 —— 头名闭集 × 线路 × 值形。
  *
- * 依赖纪律:叶(只 type-import core、值引 `trace/redact.ts` 的名字回显尺)。
+ * 依赖纪律:叶(只 type-import core 与 settings-schema、值引 `trace/redact.ts` 的名字回显尺)。
  */
 import type { Model } from "@sema-agent/core";
+import type { ModelEntry } from "@sema-agent/settings-schema";
 /** 条目的线路词(core `Model["api"]`,不手抄)。 */
 type ModelApi = Model["api"];
 /**
@@ -69,17 +68,17 @@ export type CatalogEntryHeadersVerdict = {
     readonly issue: string;
 };
 /**
- * **唯一判据**:条目的 `headers`(`unknown`:承载形,不信类型)+ 条目的线路词(`api`)—— 两者都取判官那一次 settings-schema 解析的读数
+ * **唯一判据**:条目的 `headers`(契约包已判过容器形的袋;值仍是 `unknown`)+ 条目的线路词(`api`)—— 两者都取判官那一次 settings-schema 解析的读数
  * (缺席的 `api` 即 schema 的缺省),判据与铸点读同一只值,见 `judgeCatalogEntry`。
  * 整只判:任一名字 / 值不合 ⇒ 整只不收(留下好的那几个 = 让运维以为整袋生效了)。坏字段逐个列出(`headers.<名>`)。
  */
-export declare function readCatalogEntryHeaders(raw: unknown, api: ModelApi): CatalogEntryHeadersVerdict;
+export declare function readCatalogEntryHeaders(raw: ModelEntry["headers"], api: ModelApi): CatalogEntryHeadersVerdict;
 /**
  * **唯一铸点**(`toModel` 调):判过的袋 → `Model.headers` 的键。缺席 ⇒ 不铸键(一个 `undefined` 值的键也不铸:
  * 缺席只有一种拼法)。判不过 ⇒ **抛**:到这里的条目已经过 [ref] 逐条判据(判不过的进 `modelRefusals`、到不了 `toModel`),
  * 抛 = 两处判据分叉了,stage 整候选拒、响亮,不静默丢头。
  */
-export declare function buildModelHeadersKey(entryName: string, raw: unknown, api: ModelApi): {
+export declare function buildModelHeadersKey(entryName: string, raw: ModelEntry["headers"], api: ModelApi): {
     headers?: Record<string, string>;
 };
 export {};

package/dist/model-entry-headers.js

@@ -15,10 +15,6 @@ function isCatalogEntryHeaderName(name) {
 export function readCatalogEntryHeaders(raw, api) {
     if (raw === undefined)
         return { ok: true, headers: undefined };
-    const proto = typeof raw === "object" && raw !== null ? Object.getPrototypeOf(raw) : undefined;
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw) || (proto !== Object.prototype && proto !== null)) {
-        return { ok: false, fields: ["headers"], issue: `headers: expected a plain object of { <header name>: <value> } (allowed names: ${CATALOG_ENTRY_HEADER_NAMES.join(", ")})` };
-    }
     const fields = [];
     const issues = [];
     const bag = {};

package/dist/model-entry-refusal.d.ts

@@ -1,6 +1,6 @@
 import { ModelEntry, type ModelEntryRefusalCode, type ModelPlaneRefusalCode, type ModelRefusalsSignal } from "@sema-agent/settings-schema";
 import { type DroppedCatalogEntry } from "./web-admin-client/read-warnings.js";
-import { type ModelTableLeg } from "./model-select.js";
+import { type ModelRefusalLeg } from "./model-select.js";
 import type { CandidateRejectionNote } from "./web-admin-client/candidate-gate.js";
 /**
  * 条目拒因码 → 本仓铸它的成因 —— **以码为键**([ref]):码闭集的属主是 settings-schema(`MODEL_ENTRY_REFUSAL_CODES`,6.2.0 起;此前本仓
@@ -173,11 +173,14 @@ export interface DefaultModelView {
  * **之后**判的理由(此前 `parseModelDomain` 在目录应用之前就对 `MODEL_ID` 空串拒启,把只配了目录的用户无谓拒掉)。
  *
  * 拒因一句:码 + 这条腿上**真实**的出路 + 若目录在场但每条都不可用,点名它们与各自的码。env 腿句首保留 `MODEL_ID is required`
- * 这个既有的可 grep 片段(壳与运维脚本认它);目录腿不提 `MODEL_ID`(见 {@link ModelTableLeg})。
+ * 这个既有的可 grep 片段(壳与运维脚本认它);目录腿不提 `MODEL_ID`(见 {@link ModelRefusalLeg})。
  * env 腿若是因「候选被判官整拒」才回落到这张表({@link DefaultModelView.candidateRejectionNotes}),同一行再追加「回落原因」:被拒的文档名 + 拒码 + 原因类词 + 文档路径 ——
- * 不带配置值、不带链接指向的目标路径、不抄任何 `error` 原文;只追加,句首的 grep 锚不动,没有被拒候选时整句逐字不变。
+ * 不带配置值、不带链接指向的目标路径、不抄任何 `error` 原文;只追加,句首的 grep 锚不动。
+ * env 腿句尾的「出路」按**这个进程的配置源是不是 web-admin**说真话({@link ModelRefusalLeg.webAdminIsConfigSource},调用点读 `configSourceKind` 递进来;本函数不读 env、
+ * 不读配置):是 ⇒ `MODEL_ID` 或目录(`config.d/models.json` 或 web-admin;web-admin 在 boot 预算之后才答的算 boot 时缺席,`CONFIG_BOOT_FETCH_BUDGET_MS` 调大才等得到它),
+ * 整句逐字是此前那一句;不是 ⇒ 只说 `MODEL_ID` 与 `config.d/models.json` 两条,不提 web-admin 与那根旋钮(对这个进程它们不是出路)。句首锚两形都不动。
  */
-export declare function defaultModelRefusal(view: DefaultModelView, leg: ModelTableLeg): string | undefined;
+export declare function defaultModelRefusal(view: DefaultModelView, target: ModelRefusalLeg): string | undefined;
 /** 一个被铸出的被拒名字:`name` = 被拒条目的名字,`target` = 增广把它指向的那条条目,`via` = 它是以什么身份被铸出的。 */
 export interface MintedRefusedName {
     readonly name: string;

package/dist/model-entry-refusal.js

@@ -185,24 +185,30 @@ function candidateFellBackClause(notes) {
     const rows = notes.map((n) => `"${n.document}" [${n.code}] ${n.cause}${n.path !== undefined ? `: ${n.path}` : ""}`);
     return ` (the config candidate was rejected whole and none of its domains applied, so its catalog is not in this table; fix or remove the named document(s) — the config_candidate_rejected warn line has the full diagnostics — rejected: ${rows.join(" | ")})`;
 }
-export function defaultModelRefusal(view, leg) {
+export function defaultModelRefusal(view, target) {
     if (Object.hasOwn(view.models, DEFAULT_MODEL_REF) && view.models[DEFAULT_MODEL_REF] !== undefined)
         return undefined;
     const refused = Object.entries(view.modelRefusals).map(([n, r]) => `${nameSlot(n)} [${r.code}]`);
     const unavailable = refused.length > 0 ? ` (every enabled catalog entry is unavailable on this host: ${refused.join(", ")})` : "";
-    switch (leg) {
+    switch (target.leg) {
         case "env":
             return (`MODEL_ID is required when no catalog default resolves [${DEFAULT_MODEL_MISSING_CODE}] — this model table has no default model` +
                 unavailable +
                 candidateFellBackClause(view.candidateRejectionNotes) +
-                ". Set MODEL_ID=<model name your gateway serves>, or enable at least one model this host can serve in the catalog " +
-                "(config.d/models.json, or the web-admin) — either one is enough (a web-admin that answers after the boot budget " +
-                "counts as absent at boot: raise CONFIG_BOOT_FETCH_BUDGET_MS to wait for it).");
+                ". Set MODEL_ID=<model name your gateway serves>, or enable at least one model this host can serve in the catalog (config.d/models.json" +
+                (target.webAdminIsConfigSource
+                    ? ", or the web-admin) — either one is enough (a web-admin that answers after the boot budget " +
+                        "counts as absent at boot: raise CONFIG_BOOT_FETCH_BUDGET_MS to wait for it)."
+                    : ") — either one is enough."));
         case "catalog":
             return (`this catalog candidate has no default model [${DEFAULT_MODEL_MISSING_CODE}]` +
                 unavailable +
                 " — fix the named entries (each has its own warn with the reason) or enable / bind a default this host can serve, in the catalog itself " +
                 "(a catalog in force replaces the env model table, so MODEL_ID cannot stand in for it).");
+        default: {
+            const unreachable = target;
+            throw new Error(`defaultModelRefusal: leg outside the closed set: ${JSON.stringify(unreachable)}`);
+        }
     }
 }
 function mintedVia(name, own, tiers) {

package/dist/model-plane-face.d.ts

@@ -61,5 +61,5 @@ export interface ModelPlaneSeats {
  * `modelPlane` 的**唯一读口**(起服后的 HTTP 路由与起服前的探针各调一次,见文件头「两条读路,一只读口」):进程事实只在这里取齐 ——
  * 名册布防读 `isRosterGateArmed(config.webAdmin)`(装配第 2 段的路由判官传的同一只谓词),两只座读调用方递来的运行时取值口 —— 再交铸点。
  */
-export declare function readModelPlaneFace(config: ServedModelRouteView & Pick<ServiceConfig, "webAdmin">, seats: ModelPlaneSeats): ModelPlaneFace;
+export declare function readModelPlaneFace(config: ServedModelRouteView & Pick<ServiceConfig, "webAdmin" | "configProvider">, seats: ModelPlaneSeats): ModelPlaneFace;
 //# sourceMappingURL=model-plane-face.d.ts.map

package/dist/model-plane-face.js

@@ -1,5 +1,6 @@
 import { judgeServedModelRoute } from "./model-route-endpoint.js";
 import { servedModelTableLeg } from "./model-select.js";
+import { configSourceKind } from "./config-provider.js";
 import { isRosterGateArmed } from "./config.js";
 export const CATALOG_STANCES = ["absent", "adopted", "refused"];
 function catalogStanceOf(served, wholeRefused) {
@@ -15,6 +16,7 @@ function catalogStanceOf(served, wholeRefused) {
 export function readModelPlaneFace(config, seats) {
     return buildModelPlaneFace(config, {
         envTableIsPlaceholder: isRosterGateArmed(config.webAdmin),
+        webAdminIsConfigSource: configSourceKind(config) === "remote",
         candidateRejection: seats.candidateRejectionState?.(),
         latestPlaneRefusal: seats.latestPlaneRefusalState?.(),
     });
@@ -22,7 +24,7 @@ export function readModelPlaneFace(config, seats) {
 function buildModelPlaneFace(config, facts) {
     const servedTable = servedModelTableLeg(config);
     const wholeRefused = facts.candidateRejection !== undefined || facts.latestPlaneRefusal !== undefined;
-    const verdict = judgeServedModelRoute(config, { envTableIsPlaceholder: facts.envTableIsPlaceholder });
+    const verdict = judgeServedModelRoute(config, { envTableIsPlaceholder: facts.envTableIsPlaceholder, webAdminIsConfigSource: facts.webAdminIsConfigSource });
     return {
         servedTable,
         catalog: catalogStanceOf(servedTable, wholeRefused),

package/dist/model-route-endpoint.d.ts

@@ -18,7 +18,7 @@
  * 缓存口径答它,而条目行上的 `api` / 缓存族仍按词写),网关在不在都一样。
  *
  * ## 执法点(判据只在这里,执法点在调用处 —— 与 [ref] `gateway-url-userinfo` 同形)
- * **判官只判「将要服务的那张表」,拒因句按视图说真话**(视图词 = {@link ModelTableLeg} 两词,进判据入参,不靠调用方拼句):
+ * **判官只判「将要服务的那张表」,拒因句按视图说真话**(视图词 = {@link ModelRefusalLeg},进判据入参,不靠调用方拼句):
  *  · boot:装配第 2 段**目录应用之后**的跨域不变量区(`boot/stage-02-web-admin-pull.ts`,锚 `CROSS-INVARIANT:model-route-endpoint`)⇒ 拒启 ——
  *    经 {@link judgeServedModelRoute}:目录被采纳 ⇒ 判目录表(目录视图),目录缺席 / 被整拒 / 没有启用条目 ⇒ 判 env 表(env 视图);
  *    严格名册布防(`isRosterGateArmed`)时 env 表是占位、从不被派发 ⇒ 不判它(备用网关那一条与表无关,照判)。
@@ -40,7 +40,7 @@
  * `brain.ts` / `hooks/hook-llm.ts` 都可以安全引它。
  */
 import type { Model } from "@sema-agent/core";
-import { type ModelTableLeg } from "./model-select.js";
+import { type ModelRefusalLeg } from "./model-select.js";
 /** 机读码(拼法随 `config.*` 家族,按**规则**命名不按键名):一条 openai 路由解析不到端点。 */
 export declare const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
 /** 同族第二码:备用网关设了、主网关没设。与上一码分开是因为出路不同(补主网关 / 撤备用 vs 补主网关 / 给条目 baseUrl)。 */
@@ -83,7 +83,7 @@ export type OpenaiRouteEndpoint = {
  * 单条 openai 路由的有效端点 / 拒因(拒因与部署级判据是**同一只**铸点 {@link routeEndpointMissingRefusal};`leg` = 这条路由所在的表的视图词)。
  * `route` = 这条路由的条目(只读 `baseUrl` 与 `provider`);条目都没有(模型名解不出)⇒ 传 `undefined`,按「无自有 baseUrl、非 anthropic 词」判。
  */
-export declare function resolveOpenaiRouteEndpoint(routeName: string, route: Pick<Model, "baseUrl" | "provider"> | undefined, gatewayBaseUrl: string | undefined, leg: ModelTableLeg): OpenaiRouteEndpoint;
+export declare function resolveOpenaiRouteEndpoint(routeName: string, route: Pick<Model, "baseUrl" | "provider"> | undefined, gatewayBaseUrl: string | undefined, leg: ModelRefusalLeg): OpenaiRouteEndpoint;
 /** 部署级判据读的切面(`ServiceConfig` 与 `CrossInvariantView` 都结构满足)。 */
 export interface ModelRouteEndpointView {
     readonly gatewayBaseUrl?: string;
@@ -104,7 +104,7 @@ export interface ModelRouteEndpointView {
  * `default` 键是目录里另一条的别名(env 腿 `{default: m, [m.id]: m}`、center 腿 `models.default = models[picked]`),
  * 与别的键指同一只对象时不重复点名;只有它一个键时(手搓夹具)照样点名 `default`。
  */
-export declare function modelRouteEndpointRefusal(view: ModelRouteEndpointView, leg: ModelTableLeg): string | undefined;
+export declare function modelRouteEndpointRefusal(view: ModelRouteEndpointView, leg: ModelRefusalLeg): string | undefined;
 /** [ref]:部署级判决的结构化形 —— 码与拒因句由**同一次**判决给出(一个不变量 id 两个码,组拒码在判决那刻当数据带出,不从句子里抠)。 */
 export interface ModelRouteEndpointVerdict {
     readonly code: typeof GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE | typeof MODEL_ROUTE_ENDPOINT_MISSING_CODE;
@@ -115,9 +115,9 @@ export interface ModelRouteEndpointVerdict {
 /**
  * **判据属主**([ref] 起的结构化形;{@link modelRouteEndpointRefusal} 是它的句子投影):`undefined` = 通过。判序即 {@link modelRouteEndpointRefusal}
  * 头注所列 —— ① 备用无主先说,② 逐条目解析不到端点全部点名。加一枝 = 在这里同时给出码与句(返回型强制两者同在)。
- * `leg` = `view.models` 是哪一张表({@link ModelTableLeg}):判据本身两视图同一把,**句子**按视图铸(出路在 env 表与目录表上不是同一组)。
+ * `leg` = `view.models` 是哪一张表(+ env 腿句尾要的部署事实,{@link ModelRefusalLeg}):判据本身两视图同一把,**句子**按视图铸(出路在 env 表与目录表上不是同一组;env 腿句尾提不提 web-admin 看它是不是配置源)。
  */
-export declare function judgeModelRouteEndpoint(view: ModelRouteEndpointView, leg: ModelTableLeg): ModelRouteEndpointVerdict | undefined;
+export declare function judgeModelRouteEndpoint(view: ModelRouteEndpointView, leg: ModelRefusalLeg): ModelRouteEndpointVerdict | undefined;
 /** {@link judgeServedModelRoute} 读的切面:路由判据的切面 + 「服务的是哪张表」的事实(`ServiceConfig` 结构满足)。 */
 export interface ServedModelRouteView extends ModelRouteEndpointView {
     readonly model: object;
@@ -131,6 +131,12 @@ export interface ServedModelRouteOptions {
      * 布防是中心接入的事实,配置读不出 ⇒ 由调用方给。没有名册门的入口(run-local)传 `false`。
      */
     readonly envTableIsPlaceholder: boolean;
+    /**
+     * **web-admin 是不是这个进程的配置源**(`configSourceKind(config) === "remote"`;只有服务的是 env 表时句子读它):env 腿拒因句「让目录缺省来服务」那一条出路是否提 web-admin
+     * (与缺省模型拒启句同一件事实,类型见 {@link ModelRefusalLeg})。配置源判官在 `config-provider.ts`,判官这一侧引不得它(环)⇒ 由调用点读、递进来;必填、没有缺省值 ——
+     * 少递编译红。没有配置源的装配(见 {@link assertServedModelRoute})不经本字段。
+     */
+    readonly webAdminIsConfigSource: boolean;
 }
 /**
  * **起服段的路由判官:只判「将要服务的那张表」**。`undefined` = 通过。
@@ -149,5 +155,5 @@ export declare function judgeServedModelRoute(config: ServedModelRouteView, opts
  * 全零统计、退出 0)。装配第 2 段与 `run-local` 要锚、要在目录应用之后判,调的是 {@link judgeServedModelRoute};本函数只是它的抛出形。
  * 源码类钉(`test/served-model-route.test.ts` ⑨):`src/` 与 `scripts/` 里每个调 `loadConfig()` 的入口,要么在同文件里判过路由,要么是登记在册的例外。
  */
-export declare function assertServedModelRoute(config: ServedModelRouteView, opts: ServedModelRouteOptions): void;
+export declare function assertServedModelRoute(config: ServedModelRouteView, opts: Omit<ServedModelRouteOptions, "webAdminIsConfigSource">): void;
 //# sourceMappingURL=model-route-endpoint.d.ts.map

package/dist/model-route-endpoint.js

@@ -1,5 +1,5 @@
 import { brainLaneFor, catalogBrainLane, declaredRootUrl, routeTableOf } from "./model-provider.js";
-import { DEFAULT_MODEL_REF, servedModelTableLeg } from "./model-select.js";
+import { DEFAULT_MODEL_REF, modelRefusalLegOf, servedModelTableLeg } from "./model-select.js";
 export const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
 export const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
 export const MODEL_ROUTE_GAP_WORDS = ["endpoint_missing", "lane_credential_missing"];
@@ -54,29 +54,32 @@ export function judgeModelRouteEndpoint(view, leg) {
     }
     return endpointMissing === undefined ? undefined : { code: MODEL_ROUTE_ENDPOINT_MISSING_CODE, gap: "endpoint_missing", reason: endpointMissing };
 }
-function laneUnmountedRefusal(quotedNames, leg) {
+function catalogSourcesPhrase(target) {
+    return target.webAdminIsConfigSource ? "config.d/models.json, or the web-admin" : "config.d/models.json";
+}
+function laneUnmountedRefusal(quotedNames, target) {
     const one = quotedNames.length === 1;
     const head = `${one ? `model ${quotedNames[0]} asks` : `models ${quotedNames.join(", ")} ask`} for the anthropic lane (provider "anthropic"), but no Anthropic route is mounted on this ` +
         `deployment — ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are both unset [${MODEL_ROUTE_ENDPOINT_MISSING_CODE}]. ${one ? "It is" : "They are"} not served rather than ` +
         "handed to the openai-compatible gateway under an anthropic label (that lane would answer with its own key, its own wire format and its own cache accounting). ";
-    switch (leg) {
+    switch (target.leg) {
         case "env":
             return (head +
                 "Pick one way out: (1) set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN (plus ANTHROPIC_BASE_URL for a non-default endpoint); " +
                 "(2) set MODEL_PROVIDER=gateway (or vllm) to serve the env model on the openai-compatible gateway; " +
-                "(3) leave MODEL_ID unset and let the default entry of a catalog (config.d/models.json, or the web-admin) serve — a catalog in force replaces the env model table.");
+                `(3) leave MODEL_ID unset and let the default entry of a catalog (${catalogSourcesPhrase(target)}) serve — a catalog in force replaces the env model table.`);
         case "catalog":
             return head + `Set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN in this service's env, or change ${one ? "the entry's" : "each named entry's"} provider to an OpenAI-compatible route ("gateway" / "vllm") with its own baseUrl.`;
     }
 }
-function routeEndpointMissingRefusal(quotedNames, leg) {
+function routeEndpointMissingRefusal(quotedNames, target) {
     const one = quotedNames.length === 1;
     const subject = one ? `model ${quotedNames[0]} rides` : `models ${quotedNames.join(", ")} ride`;
     const head = `${subject} the openai-compatible lane but ${one ? "resolves" : "resolve"} to no endpoint [${MODEL_ROUTE_ENDPOINT_MISSING_CODE}] — `;
     const noDefault = "MODEL_GATEWAY_BASEURL has no factory default: the former silent placeholder (this machine's port 8000) let such a " +
         "deployment start fine and then fail on the first model call, far from the cause (\"fetch failed … ECONNREFUSED\", or " +
         "a container dialling its own loopback when compose passes an empty value). ";
-    switch (leg) {
+    switch (target.leg) {
         case "catalog":
             return (head +
                 `${one ? "it has no" : "none has a"} baseUrl of its own, and MODEL_GATEWAY_BASEURL is unset. ` +
@@ -89,17 +92,17 @@ function routeEndpointMissingRefusal(quotedNames, leg) {
                 `This process serves the env model table because no catalog is in force (none configured, the config source unreachable, the candidate refused, or no enabled model in it). Pick one way out: ` +
                 `(1) set MODEL_GATEWAY_BASEURL explicitly — for a gateway on this machine: ${LOCAL_GATEWAY_HINT}; ` +
                 "(2) mount the Anthropic route — MODEL_PROVIDER=anthropic with ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN (plus ANTHROPIC_BASE_URL for a non-default endpoint); " +
-                "(3) leave MODEL_ID unset and let the default entry of a catalog (config.d/models.json, or the web-admin) serve — a catalog in force replaces the env model table. " +
+                `(3) leave MODEL_ID unset and let the default entry of a catalog (${catalogSourcesPhrase(target)}) serve — a catalog in force replaces the env model table. ` +
                 "(With CONFIG_REQUIRE_ROSTER=true on a remote registry the env model is declared a placeholder that is never served, and is not judged here.)");
     }
 }
 export function judgeServedModelRoute(config, opts) {
-    const leg = servedModelTableLeg(config);
-    const view = leg === "env" && opts.envTableIsPlaceholder ? { ...config, models: {} } : config;
-    return judgeModelRouteEndpoint(view, leg);
+    const served = servedModelTableLeg(config);
+    const view = served === "env" && opts.envTableIsPlaceholder ? { ...config, models: {} } : config;
+    return judgeModelRouteEndpoint(view, modelRefusalLegOf(served, opts.webAdminIsConfigSource));
 }
 export function assertServedModelRoute(config, opts) {
-    const verdict = judgeServedModelRoute(config, opts);
+    const verdict = judgeServedModelRoute(config, { ...opts, webAdminIsConfigSource: false });
     if (verdict !== undefined)
         throw new Error(verdict.reason);
 }

package/dist/model-select.d.ts

@@ -53,6 +53,28 @@ export declare function servedModelTableLeg(config: {
     readonly model: object;
     readonly envModel: object;
 }): ModelTableLeg;
+/**
+ * 拒因句的**腿**:进程服务的是哪张表({@link ModelTableLeg} 两词)+ env 腿的句子要的一件**部署事实**。缺省模型判官(`defaultModelRefusal`)与路由端点判官
+ * (`judgeModelRouteEndpoint` / `modelRouteEndpointRefusal` / `resolveOpenaiRouteEndpoint`)的 env 腿句尾读的是**同一件事实、同一个类型** —— 再有一条 env 腿的拒因句
+ * 要说「目录从哪来」,也读这一只,不另立第二份。
+ * 这一件事实只有 env 腿的句尾读(目录腿的句子不提 `MODEL_ID`、也不提 web-admin),所以挂在 `env` 这一支上 —— 目录腿的调用点(热路径的候选判)手里没有也不需要它,
+ * 少递这一格的 env 腿调用点编译红(必填,没有缺省值)。
+ *  · `webAdminIsConfigSource` —— **web-admin 是不是这个进程的配置源**(`configSourceKind(config) === "remote"`,配置源判官的唯一读法;调用点读、判官不读):
+ *    是 ⇒ 目录只可能从 web-admin 来(远端源不读本地 `config.d`),句尾的出路里 web-admin 与「boot 预算之后才答的算缺席」这根旋钮是真的;
+ *    不是 ⇒ 句尾只剩 `MODEL_ID` 与 `config.d/models.json`。判据**只有这一个事实**:配没配中心本身不是它(`CONFIG_PROVIDER=local` 而配了中心的部署,中心照样管 fleet 面,
+ *    模型目录却只读本地 `config.d`);中心车道配齐的谓词 `centerLaneConfigured` 也不是它(那是 fleet 租约 / 用量环的门,要 worker 与已声明的凭证,比「目录从中心来」窄)。
+ *    判官不能自己读它:配置源判官住在 `config-provider.ts`,后者经 `config-invariants.ts` 引路由端点判官 —— 反向再引就是环。
+ */
+export type ModelRefusalLeg = {
+    readonly leg: "env";
+    readonly webAdminIsConfigSource: boolean;
+} | {
+    readonly leg: "catalog";
+};
+/** 调用点把「服务的是哪张表」(`servedModelTableLeg`)与那件部署事实合成判官的腿;穷举 switch —— {@link ModelTableLeg} 加一词不补臂 ⇒ 编译红。 */
+export declare function modelRefusalLegOf(served: ModelTableLeg, webAdminIsConfigSource: boolean): ModelRefusalLeg;
+/** 目录腿(判的是一份目录候选 / 目录表):不带部署事实,所以是一个常量 —— 热路径的两处判官调用点共用它。 */
+export declare const CATALOG_REFUSAL_LEG: ModelRefusalLeg;
 /**
  * 目录服务、而 env 里还设着 `MODEL_ID` ⇒ 启动时说一行(沿 `config_env_set_but_ineffective` 通告族:值合法、却不参与服务)。
  * 这不是拒:目录一旦被采纳就整张换掉 env 表,`MODEL_ID` 在这一形下本来就不是缺省来源(缺省来自目录)—— 运维该知道自己的那一行

package/dist/model-select.js

@@ -11,6 +11,15 @@ export const MODEL_TABLE_LEGS = ["env", "catalog"];
 export function servedModelTableLeg(config) {
     return config.model === config.envModel ? "env" : "catalog";
 }
+export function modelRefusalLegOf(served, webAdminIsConfigSource) {
+    switch (served) {
+        case "env":
+            return { leg: "env", webAdminIsConfigSource };
+        case "catalog":
+            return { leg: "catalog" };
+    }
+}
+export const CATALOG_REFUSAL_LEG = { leg: "catalog" };
 export function buildEnvModelIdNotServedNotice(config) {
     if (servedModelTableLeg(config) !== "catalog" || config.envModel.id === "")
         return undefined;

package/dist/model-unreachable-notice.d.ts

@@ -8,6 +8,17 @@
  * (test 立案原话)。core 没有现成的「模型不可达」用户通告码 ⇒ 本仓铸,走既有的本仓铸码族([ref] 形:白名单 / 归属 / 消毒 / 隔离四件判据
  * 一个不绕),不开第二条通道。core 7.38.0([ref])起本码在 core 码册里:受众 `NOTICE_AUDIENCE` = user、铸者 `NOTICE_MINTER` = `"server"`。
  *
+ * ## 建议句(7.152.0):**说这一次失败真实的出路**
+ * 7.151.0 及以前,正文末句与 `detail.remedy` 对所有建连失败一律说「查 VPN / 代理;代理变过就重启」—— 对「拒连到一个没人监听的地址」(本机模型服务没起、
+ * 网关地址写错了端口)是错的方向:没走代理、没有 VPN 的人被指去查 VPN。现在建议句取自**失败类上的一张闭表**(`outbound-dispatcher.ts` 的
+ * `MODEL_UNREACHABLE_REMEDIES`,选句 {@link connectFailureRemedyOf} —— 运维日志 `outbound_connect_failed` 的 `hint` 尾句读同一行),
+ * 正文末句(`advice`)与 `detail.remedy` 是**同一行的两句**,不各写各的;失败类取自那张码闭集上每个码的 `failureClass`,本文件不另写码 → 类的映射。
+ * 选句规则(模型调用这一臂)三条,先到先得:
+ *  ① 这一跳走了代理(`proxyInUse` 非空)⇒ 通用句(拒连 / 解析不了可能是**代理**那一头的事,出路仍是「查 VPN / 代理」);
+ *  ② 失败类 `refused`(直连)⇒ 查那个地址上有没有服务在听、模型网关地址配得对不对;`unresolved`(直连)⇒ 地址写法 / DNS / VPN;`unreachable` ⇒ 通用句;
+ *  ③ 码不在闭集里(类型上到不了,读者收 `string`)⇒ 通用句 —— 声明的未分类臂({@link connectFailureRemedyOf} 里写明),不抛、不静默。
+ * 建议句(`advice` / `remedy`)里没有任何配置值、代理地址、凭据(出路只说「那个地址」「网关地址配置」;模型端点的 `host:port` 只在正文前半句与 `detail.targetHost`,与既有一致,代理只以变量名出现)。
+ *
  * ## 判据(一句):**这一次模型调用的终局是 `stopReason: "error"`,且它发出的最后一条请求在建连时就失败了**
  * 「最后一条请求落在哪」由出网观察者记在调用作用域上(`model-reach-scope.ts`,undici 诊断通道,见 `outbound-dispatcher.ts`)——
  * 不按目标主机 + 时间去猜。于是:

package/dist/model-unreachable-notice.js

@@ -1,21 +1,21 @@
 import { currentModelReachLeg, withModelCallReach } from "./model-reach-scope.js";
+import { connectFailureRemedyOf } from "./outbound-dispatcher.js";
 import { defaultEngineNoticeRouter } from "./trace/engine-notice-wire.js";
 const SERVER_MODEL_UNREACHABLE = "server.model_unreachable";
-const MODEL_UNREACHABLE_REMEDY = "check VPN / proxy; restart if the proxy changed since boot";
 function announceModelUnreachable(leg, failure, router = defaultEngineNoticeRouter) {
     if (leg.announced.has(failure.targetHost))
         return;
     leg.announced.add(failure.targetHost);
     const via = failure.proxyInUse !== null ? ` through the proxy from ${failure.proxyInUse}` : "";
+    const { advice, remedy } = connectFailureRemedyOf(failure, "model_call");
     router.route({
         code: SERVER_MODEL_UNREACHABLE,
-        message: `The model endpoint could not be reached: the connection to ${failure.targetHost}${via} failed (${failure.code}). ` +
-            "Check the VPN / proxy; if the proxy changed since the server started, restart it (proxy settings are read once at startup).",
+        message: `The model endpoint could not be reached: the connection to ${failure.targetHost}${via} failed (${failure.code}). ${advice}`,
         detail: {
             code: failure.code,
             targetHost: failure.targetHost,
             ...(failure.proxyInUse !== null ? { proxyInUse: failure.proxyInUse } : {}),
-            remedy: MODEL_UNREACHABLE_REMEDY,
+            remedy,
             sessionId: leg.sessionId,
             ...(leg.taskId !== undefined ? { taskId: leg.taskId } : {}),
         },