@sema-agent/server 7.122.0 → 7.124.0

package/dist/model-entry-refusal.js

@@ -1,8 +1,8 @@
 import { CC_MODEL_TIER_ALIASES, DEFAULT_TIER_ORDER, expandTiers } from "@sema-agent/core";
-import { ModelEntry, isReportableRefusalName } from "@sema-agent/settings-schema";
+import { ModelEntry, formatConfigPath, isReportableRefusalName } from "@sema-agent/settings-schema";
 import { catalogBrainLane } from "./model-provider.js";
 import { readCatalogEntryHeaders } from "./model-entry-headers.js";
-import { describeSchemaIssueFields, describeSchemaIssues } from "./config-center/read-warnings.js";
+import { DroppedCatalogEntryRow, describeSchemaIssueFields, describeSchemaIssues } from "./web-admin-client/read-warnings.js";
 import { DEFAULT_MODEL_REF } from "./model-select.js";
 export const ENTRY_REFUSAL_REASON_OF = {
     "config.model_no_brain": "no_brain",
@@ -55,7 +55,7 @@ function entryInvalidRefusal(id, provider, fields, issues) {
             "deployment's catalog on its own (the other entries keep serving) instead of being served with a value nothing validated; fix the entry to bring it back",
     };
 }
-const MALFORMED_CARRIER_NOT_A_LIST = "(droppedIdentities is not a list)";
+const MALFORMED_CARRIER_NOT_A_LIST = "(droppedCatalogEntries is not a list)";
 export function judgeCatalogEntries(enabled, ctx, dropped) {
     const usable = [];
     const refused = {};
@@ -71,20 +71,25 @@ export function judgeCatalogEntries(enabled, ctx, dropped) {
     }
     const rows = dropped === undefined ? [] : Array.isArray(dropped) ? dropped : undefined;
     if (rows === undefined)
-        return { usable, refused, malformed: [MALFORMED_CARRIER_NOT_A_LIST] };
+        return { usable, refused, malformed: [MALFORMED_CARRIER_NOT_A_LIST], dropped: [] };
     const malformed = [];
+    const carried = [];
     for (const d of rows) {
-        const e = (typeof d === "object" && d !== null ? d : {});
-        if (typeof e.name !== "string") {
-            malformed.push(typeof e.entry === "string" ? e.entry : "(unknown coordinate)");
+        const row = DroppedCatalogEntryRow.safeParse(d);
+        if (!row.success) {
+            const index = typeof d === "object" && d !== null ? d.index : undefined;
+            malformed.push(typeof index === "number" && Number.isSafeInteger(index) && index >= 0 ? formatConfigPath(["models", index]) : "(unknown coordinate)");
             continue;
         }
-        if (Object.hasOwn(refused, e.name))
+        carried.push(row.data);
+        const { identity } = row.data;
+        if (identity?.name === undefined || identity.enabled === false)
             continue;
-        const fields = Array.isArray(e.fields) ? e.fields.filter((f) => typeof f === "string") : [];
-        mint(e.name, entryInvalidRefusal(typeof e.id === "string" ? e.id : "", "", fields, typeof e.issues === "string" ? e.issues : fields.join(", ")));
+        if (Object.hasOwn(refused, identity.name))
+            continue;
+        mint(identity.name, entryInvalidRefusal(identity.id ?? "", "", row.data.fields, row.data.issues));
     }
-    return { usable, refused, malformed };
+    return { usable, refused, malformed, dropped: carried };
 }
 export function buildModelRefusalsSignal(v) {
     if (v === undefined)
@@ -113,9 +118,9 @@ function nameSlot(name) {
 export function refusalEventOf(reason) {
     switch (reason) {
         case "no_brain":
-            return "sema_registry_model_no_brain";
+            return "web_admin_model_no_brain";
         case "entry_invalid":
-            return "sema_registry_model_entry_invalid";
+            return "web_admin_model_entry_invalid";
     }
 }
 export function refusalWarnFields(name, r) {
@@ -141,7 +146,7 @@ export function defaultModelRefusal(view, leg) {
             return (`MODEL_ID is required when no catalog default resolves [${DEFAULT_MODEL_MISSING_CODE}] — this model table has no default model` +
                 unavailable +
                 ". 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 config center) — either one is enough (a config center that answers after the boot budget " +
+                "(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).");
         case "catalog":
             return (`this catalog candidate has no default model [${DEFAULT_MODEL_MISSING_CODE}]` +
@@ -185,8 +190,8 @@ export function refusedNameMintedRefusal(view) {
         "rename the unavailable entry, fix it (see its own warn), or rebind / drop the tier binding that mints the name.");
 }
 export function malformedDroppedCarrierRefusal(entries) {
-    return (`the dropped-entry identity carrier of this candidate is malformed [${REFUSED_NAME_MINTED_CODE}]: ${entries.join(", ")} — ` +
-        "every row the settings-schema read writes there carries a string name, so this carrier was edited outside the read legs (e.g. a hand-edited last-known-good file); " +
-        "the candidate cannot prove the tier/alias expansion does not re-mint the unnamed entries, so its model plane is refused — restore or delete that carrier (a fresh read of the source re-mints it).");
+    return (`the dropped catalog entry carrier of this candidate is malformed [${REFUSED_NAME_MINTED_CODE}]: ${entries.join(", ")} — ` +
+        "every row the settings-schema read writes there has the carrier row shape (index, reasonCode, optional identity, fields, issues), so this carrier was edited outside the read legs (e.g. a hand-edited last-known-good file); " +
+        "the candidate cannot prove the tier/alias expansion does not re-mint the entries those rows stood for, so its model plane is refused — restore or delete that carrier (a fresh read of the source re-mints it).");
 }
 //# sourceMappingURL=model-entry-refusal.js.map

package/dist/model-provider.d.ts

@@ -60,7 +60,7 @@ export declare function modelBrainLane(provider: ModelProvider): ModelBrainLane;
  *
  * 🔴 为什么它与 {@link modelBrainLane} 不是同一只函数:两者的**输入保证不同**。
  *  · `MODEL_PROVIDER` 走 boot 闸(域外拒启)⇒ 到达 {@link modelBrainLane} 的恒是闭集词;
- *  · **目录条目**来自 settings-schema 的 `z.string()`,可以从 config-center **热应用**进来 —— 那条路上
+ *  · **目录条目**来自 settings-schema 的 `z.string()`,可以从 web-admin **热应用**进来 —— 那条路上
  *    没有、也不该有「拒启」这回事(一次热发布不能让在跑的副本死),所以这里必然存在一条「认不出」的臂。
  *
  * 🔴 那条臂**就是今天的语义,本批一个字节都没改**([ref]「不可避免的运行期 miss 臂必须说出来」):
@@ -82,7 +82,7 @@ export declare function catalogBrainLane(provider: string | undefined): ModelBra
  * `createBrain` 只在 anthropic 路由**装上**(`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 在场 ⇒
  * `config.anthropic` 在场)时才铸 `createRoutingBrain({anthropic}, {fallback: gatewayStack})`;没装时整台机器
  * 只有网关栈这一只 brain,**一切**条目(包括 `provider:"anthropic"` 的)都落 openai 兼容腿 ——
- * `apply-effective.ts` 那条 `sema_registry_model_no_brain` warn 说的「mis-routes to the gateway brain」即此。
+ * `apply-effective.ts` 那条 `web_admin_model_no_brain` warn 说的「mis-routes to the gateway brain」即此。
  *
  * 所以「这条路由要不要一个 openai 端点」的判据必须同时看词与装配:词判 {@link catalogBrainLane},
  * 装配判路由在不在。本函数是这一合取的**唯一**写法 —— 端点判官(`model-route-endpoint.ts`)、降级腿与

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

@@ -15,9 +15,10 @@
  * (`MODEL_GATEWAY_FALLBACK_URLS`)是主网关的镜像,没有主就没有镜像 ⇒ 拒。
  *
  * ## 执法点(判据只在这里,执法点在调用处 —— 与 S-475 `gateway-url-userinfo` 同形)
- *  · boot:`config.ts` 九域解析之后的跨域不变量区(锚 `CROSS-INVARIANT:model-route-endpoint`)⇒ 拒启;严格名册
+ *  · boot:`config.ts` 九域解析之后的跨域不变量区(锚 `CROSS-INVARIANT:model-route-endpoint`)⇒ 拒启;经 `model-route-gap.ts`
+ *    的 {@link judgeModelRouteGap}(env 读成本文件判据要的切面,与包根导出的纯判官是**同一只**);严格名册
  *    布防(`isRosterGateArmed`)时 env 腿是占位、从不被派发 ⇒ 不判它(备用网关那一条照判);
- *  · 热路径:`config-center/apply-effective.ts` 的模型面 stage ⇒ 模型面组拒(opus 腿 O3:同候选其余组照落)、上一代模型面继续服务;
+ *  · 热路径:`web-admin-client/apply-effective.ts` 的模型面 stage ⇒ 模型面组拒(opus 腿 O3:同候选其余组照落)、上一代模型面继续服务;
  *  · run-local:配置源解析完之后按真要派发的表再判一次(`run-local.ts`,7.98.0 合并复审 F2)—— 本入口没有名册门,
  *    loadConfig 对严格名册布防的占位豁免在这里兑现不了;没布防时恒惰性;
  *  · 登记:`config-invariants.ts` 的 `model-route-endpoint` 条(表的「不许有表外不变量」职责);
@@ -37,6 +38,23 @@ import type { Model } from "@sema-agent/core";
 export declare const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_endpoint_missing";
 /** 同族第二码:备用网关设了、主网关没设。与上一码分开是因为出路不同(补主网关 / 撤备用 vs 补主网关 / 给条目 baseUrl)。 */
 export declare const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
+/**
+ * **路由缺口的出路轴**(闭集;{@link judgeModelRouteGap} 的 `gap` 词,包根导出 —— 壳 / 包在引擎起来之前问同一句)。
+ *
+ * 与上面的**码**是两根轴:码是组拒的机读词(`ModelPlaneRefusalCode`,settings-schema 属主),这里是**出路**:
+ *  · `endpoint_missing` —— 缺的是网关端点:openai 兼容腿上的条目解析不到 base URL(或备用网关设了、主网关没设);
+ *    出路 = 设 `MODEL_GATEWAY_BASEURL`,或给条目自己的 `baseUrl`;
+ *  · `lane_credential_missing` —— 缺的是**车道凭据**:条目的 provider 词是 `anthropic`(用户选的是 anthropic 车道),
+ *    却因 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 都没有而没装上 anthropic 路由、落进了 openai 腿,那条腿又没有端点;
+ *    出路 = 补那两把钥匙之一(设网关是另一条出路,拒因句一并给);
+ *  · `none` —— 这份配置能派发到的每一条 openai 兼容路由都解析得到端点。
+ *
+ * **声明序 = 语义序**(缺口两词在前,`none` 最后);加一词 ⇒ 所有穷举 switch 当场编译红。
+ */
+export declare const MODEL_ROUTE_GAP_WORDS: readonly ["endpoint_missing", "lane_credential_missing", "none"];
+export type ModelRouteGap = (typeof MODEL_ROUTE_GAP_WORDS)[number];
+/** 有缺口的那两词(判决的结构化形只在有缺口时存在,`none` = 判决为 `undefined`)。 */
+export type ModelRouteGapBreach = Exclude<ModelRouteGap, "none">;
 /**
  * 拒因给出的**本机网关显式写法**。`src/` 里本机 8000 那个字面的**唯一**住处 —— 源码门钉在
  * `test/config-gateway-endpoint-required.test.ts` ⑧(出现在别处 = 有人又在铸缺省)。
@@ -82,6 +100,8 @@ export declare function modelRouteEndpointRefusal(view: ModelRouteEndpointView):
 /** S-768:部署级判决的结构化形 —— 码与拒因句由**同一次**判决给出(一个不变量 id 两个码,组拒码在判决那刻当数据带出,不从句子里抠)。 */
 export interface ModelRouteEndpointVerdict {
     readonly code: typeof GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE | typeof MODEL_ROUTE_ENDPOINT_MISSING_CODE;
+    /** 出路轴({@link MODEL_ROUTE_GAP_WORDS} 的缺口两词):同一次判决给出,不从句子或码里反推(`lane_credential_missing` 与 `endpoint_missing` 共用一个码)。 */
+    readonly gap: ModelRouteGapBreach;
     readonly reason: string;
 }
 /**

package/dist/model-route-endpoint.js

@@ -2,6 +2,7 @@ import { dispatchBrainLane } from "./model-provider.js";
 import { DEFAULT_MODEL_REF } 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", "none"];
 export const LOCAL_GATEWAY_HINT = "MODEL_GATEWAY_BASEURL=http://127.0.0.1:8000/v1";
 function declared(url) {
     return url !== undefined && url.trim() !== "" ? url : undefined;
@@ -24,11 +25,12 @@ export function judgeModelRouteEndpoint(view) {
             "after the primary fails; with no primary there is nothing to fail over from, and MODEL_GATEWAY_BASEURL has no " +
             `factory default. Set MODEL_GATEWAY_BASEURL to the primary gateway (for one on this machine: ${LOCAL_GATEWAY_HINT}), ` +
             "or unset MODEL_GATEWAY_FALLBACK_URLS.");
-        return { code: GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE, reason };
+        return { code: GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE, gap: "endpoint_missing", reason };
     }
     const anthropicMounted = view.anthropic !== undefined;
     const entries = Object.entries(view.models ?? {});
     const unresolved = [];
+    let laneCredentialMissing = false;
     for (const [name, m] of entries) {
         if (name === DEFAULT_MODEL_REF && entries.some(([k, other]) => k !== name && other === m))
             continue;
@@ -36,11 +38,15 @@ export function judgeModelRouteEndpoint(view) {
             continue;
         if (openaiRouteBaseUrl(m.baseUrl, gateway) !== undefined)
             continue;
-        unresolved.push(m.provider === "anthropic"
+        const anthropicWordWithoutRoute = m.provider === "anthropic";
+        laneCredentialMissing ||= anthropicWordWithoutRoute;
+        unresolved.push(anthropicWordWithoutRoute
             ? `"${name}" (provider "anthropic", but no Anthropic route is mounted — ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN are unset — so it falls to the openai-compatible lane)`
             : `"${name}"`);
     }
-    return unresolved.length > 0 ? { code: MODEL_ROUTE_ENDPOINT_MISSING_CODE, reason: routeEndpointMissingRefusal(unresolved) } : undefined;
+    if (unresolved.length === 0)
+        return undefined;
+    return { code: MODEL_ROUTE_ENDPOINT_MISSING_CODE, gap: laneCredentialMissing ? "lane_credential_missing" : "endpoint_missing", reason: routeEndpointMissingRefusal(unresolved) };
 }
 function routeEndpointMissingRefusal(quotedNames) {
     const one = quotedNames.length === 1;

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

@@ -0,0 +1,103 @@
+import { type ModelRouteEndpointVerdict, type ModelRouteGapBreach } from "./model-route-endpoint.js";
+/**
+ * 路由读数读的八把 env 键(**闭表**;`judgeModelRouteGap` 只碰这几把,测试用代理钉「读集 ⊆ 本表」)。
+ * 配置目录的 D1 对账门把 {@link readModelRouteEnv} 的调用当作这八把键的读点(`test/config-catalog.test.ts` 的 `DELEGATED_ENV_READERS`,键集取本表,不手抄)。
+ */
+export declare const MODEL_ROUTE_ENV_KEYS: {
+    readonly gatewayBaseUrl: "MODEL_GATEWAY_BASEURL";
+    readonly gatewayFallbackUrls: "MODEL_GATEWAY_FALLBACK_URLS";
+    readonly provider: "MODEL_PROVIDER";
+    readonly mainId: "MODEL_ID";
+    readonly cheapId: "MODEL_CHEAP_ID";
+    readonly anthropicApiKey: "ANTHROPIC_API_KEY";
+    readonly anthropicAuthToken: "ANTHROPIC_AUTH_TOKEN";
+    readonly anthropicBaseUrl: "ANTHROPIC_BASE_URL";
+};
+/** 一份 env 快照(`process.env` 也满足这个形)。 */
+export type ModelRouteEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * env 腿的 **cheap 槽**(`MODEL_CHEAP_ID`)铸不铸 —— 闭集四态,消费方用穷举 switch({@link mintedCheapId};`config.ts` 的启动通知):
+ *  · `absent` —— 没设;
+ *  · `without_main` —— 设了而主槽(`MODEL_ID`)没设:cheap 槽是主模型「同网关换个 id」的形,没有主槽就没有它要派生的东西 ⇒ 不铸(启动时说一句);
+ *  · `same_as_main` —— 与主 id 相同:同一个 id 说的就是主模型本身 ⇒ 不铸(启动时说一句);
+ *  · `minted` —— 铸(`id` = `MODEL_CHEAP_ID`)。
+ */
+export type EnvCheapSlot = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "without_main" | "same_as_main" | "minted";
+    readonly id: string;
+};
+/** cheap 槽铸出来的那个 id(不铸 ⇒ `undefined`)。**穷举 switch**:{@link EnvCheapSlot} 加一态不补臂 ⇒ 编译红。 */
+export declare function mintedCheapId(slot: EnvCheapSlot): string | undefined;
+/** {@link readModelRouteEnv} 的读数。 */
+export interface ModelRouteEnvReading {
+    /** `MODEL_GATEWAY_BASEURL`;**空串 = 未设**(compose `${X:-}` 常态),缺席不铸。 */
+    readonly gatewayBaseUrl: string | undefined;
+    /** `MODEL_GATEWAY_FALLBACK_URLS` 逐项 trim、丢空项。 */
+    readonly gatewayFallbackUrls: string[];
+    /** `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL`:空串 = 未设,别名各自独立(一个空别名不遮蔽另一个)。 */
+    readonly anthropicApiKey: string | undefined;
+    readonly anthropicAuthToken: string | undefined;
+    readonly anthropicBaseUrl: string | undefined;
+    /** anthropic 路由装不装 = 两把凭据任一在场(`createBrain` 同判);只读在场性。 */
+    readonly anthropicRouteMounted: boolean;
+    /**
+     * env 腿模型的 provider 词:显式 `MODEL_PROVIDER` 胜(原样,**不在此过闭集** —— 域外拒启是 `model-provider-word` 那条不变量的事);
+     * 缺席时「`ANTHROPIC_BASE_URL` + anthropic 凭据两样齐」⇒ `anthropic`(provider 推断),否则 `gateway`。
+     */
+    readonly provider: string;
+    /** `provider` 的来路(推断那一臂启动时要说一句)。 */
+    readonly providerSource: "explicit" | "inferred" | "default";
+    /** `MODEL_ID`;空串 = 没有 env 主槽(env 腿不铸任何可派发条目)。 */
+    readonly mainId: string;
+    /** cheap 槽铸不铸(见 {@link EnvCheapSlot})。 */
+    readonly cheapSlot: EnvCheapSlot;
+}
+/** 逗号串读法的归一点:逐项 trim、丢空项(缺席 = 空串 = `[]`)。本文件的 CSV 路由键与 `config.ts` 的逗号串旋钮(按名薄壳 `csv(name)`)同读这一只;
+ *  目录模块的回显分词与 `SERVICE_AUTH_TOKENS` 的 `k=v` 对分词是同形的另两处,尚未改调(清账版收,本函数届时挪到中性模块)。 */
+export declare const csvOf: (raw: string | undefined) => string[];
+/**
+ * **env 模型路由读数的唯一读口**(纯:按 {@link MODEL_ROUTE_ENV_KEYS} 点名取值,不读 `process.env`,不枚举入参)。
+ * `parseModelDomain`(起服铸 `ServiceConfig`)与 {@link judgeModelRouteGap}(判官)吃同一份读数。
+ */
+export declare function readModelRouteEnv(env: ModelRouteEnv): ModelRouteEnvReading;
+/**
+ * **env 腿的条目表** —— 主槽别名 `default` + 主槽 id(+ 铸出的 cheap 槽);没有 `MODEL_ID` ⇒ 空表(不铸占位条目:一个不存在的模型名
+ * 进可选目录 / 当缺省,正是 3.0.0 删掉的那种病)。`parseModelDomain` 铸真 `Model` 表与判官铸路由切面都经这一只,条目名与键序不会各写一份。
+ */
+export declare function envLaneTable<M extends {
+    readonly id: string;
+}>(mainId: string, main: M, cheap: M | undefined): Record<string, M>;
+/** {@link judgeModelRouteGap} 的旁路入参。 */
+export interface ModelRouteGapOptions {
+    /**
+     * env 腿的模型会不会被派发(缺省 `true`)。起服期严格名册布防(`CONFIG_REQUIRE_ROSTER=true` 且接了远程中心、非 dryRun)= 运维声明 env
+     * `MODEL_ID` 是**占位**:名册落地前计费提交 503、落地后整表换装 ⇒ env 腿从不被派发,不在「配置能派发到的」射程里(备用网关那一条与派发
+     * 无关,照判)。布防与否是中心接入的事实(不是路由键),快照读不出 ⇒ 由调用方给;壳问「本机引擎、配置在本机」那一形不用传。
+     */
+    readonly envLaneDispatchable?: boolean;
+}
+/**
+ * 判官的读数(闭集三词,穷举 switch 消费):
+ *  · `none` —— 无缺口,仅此一键;
+ *  · 缺口两词 —— `code` = 起服拒启的机读码(与 `reason` 里的方括号码同一个词;`lane_credential_missing` 也带 `config.model_route_endpoint_missing`),
+ *    `reason` = 起服拒启句原文(点名条目与出路)。
+ */
+export type ModelRouteGapReading = {
+    readonly gap: "none";
+} | {
+    [G in ModelRouteGapBreach]: {
+        readonly gap: G;
+        readonly code: ModelRouteEndpointVerdict["code"];
+        readonly reason: string;
+    };
+}[ModelRouteGapBreach];
+/**
+ * **起服前可调的模型路由缺口纯判官**(与起服判官同一实现;包根导出)。
+ *
+ * @param env 一份 env 快照(只读 {@link MODEL_ROUTE_ENV_KEYS} 那八把键;`process.env` 也行 —— 起服段就是这样调的)。
+ * @returns 三词之一;有缺口时带 `code` 与 `reason`(见 {@link ModelRouteGapReading})。
+ */
+export declare function judgeModelRouteGap(env: ModelRouteEnv, opts?: ModelRouteGapOptions): ModelRouteGapReading;
+//# sourceMappingURL=model-route-gap.d.ts.map

package/dist/model-route-gap.js

@@ -0,0 +1,80 @@
+import { DEFAULT_MODEL_REF } from "./model-select.js";
+import { judgeModelRouteEndpoint } from "./model-route-endpoint.js";
+export const MODEL_ROUTE_ENV_KEYS = {
+    gatewayBaseUrl: "MODEL_GATEWAY_BASEURL",
+    gatewayFallbackUrls: "MODEL_GATEWAY_FALLBACK_URLS",
+    provider: "MODEL_PROVIDER",
+    mainId: "MODEL_ID",
+    cheapId: "MODEL_CHEAP_ID",
+    anthropicApiKey: "ANTHROPIC_API_KEY",
+    anthropicAuthToken: "ANTHROPIC_AUTH_TOKEN",
+    anthropicBaseUrl: "ANTHROPIC_BASE_URL",
+};
+export function mintedCheapId(slot) {
+    switch (slot.kind) {
+        case "minted":
+            return slot.id;
+        case "absent":
+        case "without_main":
+        case "same_as_main":
+            return undefined;
+    }
+}
+const declaredValue = (v) => (v !== undefined && v !== "" ? v : undefined);
+export const csvOf = (raw) => (raw ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+export function readModelRouteEnv(env) {
+    const K = MODEL_ROUTE_ENV_KEYS;
+    const anthropicApiKey = declaredValue(env[K.anthropicApiKey]);
+    const anthropicAuthToken = declaredValue(env[K.anthropicAuthToken]);
+    const anthropicBaseUrl = declaredValue(env[K.anthropicBaseUrl]);
+    const anthropicRouteMounted = anthropicApiKey !== undefined || anthropicAuthToken !== undefined;
+    const explicitProvider = declaredValue(env[K.provider]);
+    const inferAnthropic = anthropicBaseUrl !== undefined && anthropicRouteMounted;
+    const mainId = env[K.mainId] ?? "";
+    const rawCheapId = env[K.cheapId];
+    return {
+        gatewayBaseUrl: declaredValue(env[K.gatewayBaseUrl]),
+        gatewayFallbackUrls: csvOf(env[K.gatewayFallbackUrls]),
+        anthropicApiKey,
+        anthropicAuthToken,
+        anthropicBaseUrl,
+        anthropicRouteMounted,
+        provider: explicitProvider ?? (inferAnthropic ? "anthropic" : "gateway"),
+        providerSource: explicitProvider !== undefined ? "explicit" : inferAnthropic ? "inferred" : "default",
+        mainId,
+        cheapSlot: !rawCheapId
+            ? { kind: "absent" }
+            : mainId === ""
+                ? { kind: "without_main", id: rawCheapId }
+                : rawCheapId === mainId
+                    ? { kind: "same_as_main", id: rawCheapId }
+                    : { kind: "minted", id: rawCheapId },
+    };
+}
+export function envLaneTable(mainId, main, cheap) {
+    if (mainId === "")
+        return {};
+    const table = { [DEFAULT_MODEL_REF]: main, [main.id]: main };
+    if (cheap !== undefined)
+        table[cheap.id] = cheap;
+    return table;
+}
+export function judgeModelRouteGap(env, opts = {}) {
+    const r = readModelRouteEnv(env);
+    const slot = (id) => ({ id, baseUrl: "", provider: r.provider });
+    const cheapId = mintedCheapId(r.cheapSlot);
+    const models = opts.envLaneDispatchable === false ? {} : envLaneTable(r.mainId, slot(r.mainId), cheapId !== undefined ? slot(cheapId) : undefined);
+    const verdict = judgeModelRouteEndpoint({
+        gatewayBaseUrl: r.gatewayBaseUrl,
+        gatewayFallbackUrls: r.gatewayFallbackUrls,
+        anthropic: r.anthropicRouteMounted ? {} : undefined,
+        models,
+    });
+    if (verdict === undefined)
+        return { gap: "none" };
+    return { gap: verdict.gap, code: verdict.code, reason: verdict.reason };
+}
+//# sourceMappingURL=model-route-gap.js.map

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

@@ -12,7 +12,7 @@ export declare const MODEL_ROUTE_URL_INVALID_CODE = "config.model_route_url_inva
  */
 export declare const MODEL_ROUTE_URL_FRAGMENT_CODE = "config.model_route_url_fragment";
 /**
- * 模型路由 base URL 的拒因(`undefined` = 这一位合法)—— 判由 `url-shape.ts` 那一只,本函数按**首个**拒因选码与出路句:
+ * 模型路由 base URL 的拒因(`undefined` = 这一位合法)—— 判由 settings-schema 的 `httpUrlFlaws`,本函数按**首个**拒因选码与出路句:
  *  ① 不是层级式 http(s) URL ⇒ `config.model_route_url_invalid`;
  *  ② 带 userinfo ⇒ `config.gateway_url_userinfo`;
  *  ③ 带 `#fragment` ⇒ `config.model_route_url_fragment`。

package/dist/model-route-url.js

@@ -1,4 +1,5 @@
-import { buildHttpUrlRefusal, httpUrlFlaws } from "./url-shape.js";
+import { httpUrlFlaws } from "@sema-agent/settings-schema";
+import { buildHttpUrlRefusal } from "./url-refusal.js";
 export const GATEWAY_URL_USERINFO_CODE = "config.gateway_url_userinfo";
 export const MODEL_ROUTE_URL_INVALID_CODE = "config.model_route_url_invalid";
 export const MODEL_ROUTE_URL_FRAGMENT_CODE = "config.model_route_url_fragment";

package/dist/model-select.d.ts

@@ -1,5 +1,10 @@
 import { type Model, type RunnerDeps } from "@sema-agent/core";
+import { type AtMention } from "@sema-agent/settings-schema";
 import type { ModelEntryRefusal } from "./model-entry-refusal.js";
+/** 座位缺席时的读法 —— 契约 prefault 解出来的值(今天是 `{mode:"all"}`),env 车道(没有中心)的 `config.atMention` 也是它。 */
+export declare const DEFAULT_AT_MENTION: AtMention;
+/** 一个 `models.atMention` 值的读法:缺席 ⇒ {@link DEFAULT_AT_MENTION};在场 ⇒ 契约 schema 判形,判不过 ⇒ `undefined`(调用方 fail-closed 并响亮)。 */
+export declare function readAtMention(raw: unknown): AtMention | undefined;
 /**
  * Resolve the model ref for a task spec from the request (CLI `/model` picker + `run --model`).
  *
@@ -37,7 +42,7 @@ export declare const DEFAULT_MODEL_REF = "default";
  * 起不再各抄一份「展开 + 解」。
  */
 export declare function resolveMainModel(plane: Pick<RunnerDeps, "models" | "tiers">): Model;
-export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>, allowlist?: readonly string[], refusals?: Readonly<Record<string, ModelEntryRefusal>>): {
+export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>, atMention: AtMention, refusals?: Readonly<Record<string, ModelEntryRefusal>>): {
     model: string;
     cleanedObjective: string;
     unknownExplicit?: string;
@@ -84,7 +89,7 @@ export declare function refusedCatalogEntry(ref: string, refusals: Readonly<Reco
     name: string;
     refusal: ModelEntryRefusal;
 } | undefined;
-/** [ref] 判别式拒因:名单在场且这次**用户选择**落在名单外。`resolved` 已是目录 name 形(归一后)。 */
+/** [ref] 判别式拒因:这次**用户选择**不在 `atMention` 许可之内(`none`,或 `only` 而不在名里)。`resolved` 已是目录 name 形(归一后)。 */
 export interface ModelNotAllowed {
     /** 调用方发来的原始 ref(name / 档位词 / 别名 / id / `@name`),已做过日志安全的 repr 归一。 */
     requested: string;
@@ -94,28 +99,26 @@ export interface ModelNotAllowed {
     source: "explicit" | "mention";
 }
 /**
- * [ref] / [ref] —— **归一条款**:membership 判定前把 ref 归一到**终端 catalog 条目**再比。
+ * [ref] / [ref] —— 「这个 ref 此刻可不可以被用户 `@` / 显式点选」的**唯一**判据(`models.atMention`,三态闭集,穷举 switch)。
  *
- * 为什么不能拿字符串直接跟名单比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)
- * 的值与 `config.models[<name>]` 是**同一个对象引用**——裸串比较会让 `@pro` 跳过一张按 name 写的名单
- * (同一只模型,两个键)。所以两边(ref 与每个名单条目)都先经 {@link matchCatalogModel} 解到目录条目,
- * 再按 **引用相等** 判同。id 形的 ref 不需要特别处理:`matchCatalogModel` 本身就是 name+id 双键索引,
- * 它会把 id 解成目录键,引用相等接着就对上了。
+ * 判序(一条规则):先把 ref 归一到**目录条目**({@link matchCatalogModel},name / 档位词 / 别名 / id 同一只);目录里根本没有的 ref ⇒ 恒 `true`
+ * —— 那是「未知模型」那道门的辖区(fresh 400 / resume 降级留声),本门只答「在目录里,但准不准点」,两道门同码同拒会让消费端分不清
+ * "没这模型"和"不让你点"。然后按 `mode`:
+ *  · `all`  ⇒ `true`;
+ *  · `none` ⇒ `false`(一个都不许);
+ *  · `only` ⇒ ref 归一到的那只条目**自己的目录名**在名单里 ⇒ `true`(名单按目录名直比)。
  *
- * 🔴 **刻意没有「id 相等」退路**(codex 复审 R1 [high],已采纳):目录**允许两条不同 name 的条目共享
- * 同一个上游 `Model.id`,却各自带不同的 `baseUrl` / `apiKeyEnv` / `cost` / provider** —— 那正是多网关、
- * 多账号部署形。按 id 判同会把 `safe` 与 `premium` 合并,于是一张只含 `safe` 的名单会放行 `premium`,
- * 而真正执行的是 `premium` 那份坐标与计费。判据只认**目录条目本身**:两条条目就是两只模型,哪怕上游
- * id 撞车。(引用相等因此不是"优化",是唯一正确的判据;它天然覆盖 tier 词/别名/id 三形。)
+ * 为什么 ref 侧要先归一、不拿 ref 串直比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)的值与 `config.models[<name>]`
+ * 是**同一个对象引用**——裸串比较会让 `@pro` 跳过一张按 name 写的名单(同一只模型,两个键)。名单侧不归一:`only` 的名在 stage 期已按本世代
+ * 可用目录收窄成目录名(settings-schema `narrowAtMention`),名单项是档位词 / 别名 / id 的形只可能来自绕过 stage 的写者 —— 它们准不了任何东西。
+ * 🔴 **刻意没有「id 相等」退路**(codex 复审 R1 [high]):目录**允许两条不同 name 的条目共享同一个上游 `Model.id`,却各自带不同的
+ * `baseUrl` / `apiKeyEnv` / `cost` / provider** —— 按 id 判同会把 `safe` 与 `premium` 合并,一张只含 `safe` 的名单会放行 `premium`。
+ * 🔴 S-704:名里写着一条**不可用**条目的名字 ⇒ 它准不了任何东西(不经 id 回退 / 别名改绑去准另一只模型 —— `matchCatalogModel` 的名字保留律)。
+ * `only` 的名在 stage 期已按本世代可用目录收窄过(settings-schema `narrowAtMention`,收窄到一个不剩 ⇒ `none`),所以这里的悬空名只来自绕过 stage 的写者(按名直比,悬空名不等于任何条目的名)。
  *
- * 缺席/空名单 ⇒ 恒 `true`(ship-dark:缺省 = 旧行为,全放行)。
- * 目录里根本没有的 ref ⇒ 恒 `true`:那是「未知模型」那道门的辖区(fresh 400 / resume 降级留声),
- * 本门只答「在目录里,但准不准点」——两道门同码同拒会让消费端分不清"没这模型"和"不让你点"。
- *
- * ⚠️ 射程:本门是**提交时**门。core 运行时路由(degrade 降级链 / cascade 梯 / roles 解析)按 operator
- * 配置自己走,**不经本门**——那不是一次用户选择,如实声明,不假装是运行时执法。
+ * ⚠️ 射程:本门是**提交时**门。core 运行时路由(degrade 降级链 / cascade 梯 / roles 解析)按 operator 配置自己走,**不经本门**。
  */
-export declare function isModelAllowlisted(ref: string, catalog: Record<string, unknown>, allowlist: readonly string[] | undefined, refusals?: Readonly<Record<string, ModelEntryRefusal>>): boolean;
+export declare function isAtMentionable(ref: string, catalog: Record<string, unknown>, atMention: AtMention, refusals?: Readonly<Record<string, ModelEntryRefusal>>): boolean;
 /**
  * [ref] —— ref → **终端 catalog name**(拒因/日志的可读形)。
  *
@@ -144,7 +147,7 @@ export type ModelImageInput = (typeof MODEL_IMAGE_INPUTS)[number];
  *  · 目录行 `GET /v1/models` 的 `vision`:`yes` ⇒ `true`,`no` ⇒ `false`,`undeclared` ⇒ **键缺席**(不替没声明的模型答「收」也不答「不收」);
  *  · 运行期的带图预检 {@link modelSupportsImages}:只有明说 `no` 才出信号。
  * 此前两处各判各的,且对「没声明」答法相反(目录行报 false、预检放行)——客户端只读得到目录那一位,于是在手写、没声明 `input` 的
- * 条目上把用户的图拦在了本地,而引擎其实会把图交给模型。env 车道与配置中心车道恒写 `input`,分叉只落在手写目录条目上。
+ * 条目上把用户的图拦在了本地,而引擎其实会把图交给模型。env 车道与 web-admin 车道恒写 `input`,分叉只落在手写目录条目上。
  * `input` 不是数组(手写错形)与条目不在,同归 `undeclared`:没有可信的声明。
  */
 export declare function modelImageInput(model: {

package/dist/model-select.js

@@ -1,10 +1,17 @@
 import { expandTiers, parseModelMention, resolveTaskModel as coreResolveTaskModel } from "@sema-agent/core";
+import { DOMAIN_SCHEMAS } from "@sema-agent/settings-schema";
+const AT_MENTION_SEAT = DOMAIN_SCHEMAS.models.shape.atMention;
+export const DEFAULT_AT_MENTION = Object.freeze(AT_MENTION_SEAT.parse(undefined));
+export function readAtMention(raw) {
+    const r = AT_MENTION_SEAT.safeParse(raw);
+    return r.success ? r.data : undefined;
+}
 export const DEFAULT_MODEL_REF = "default";
 export function resolveMainModel(plane) {
     const expanded = expandTiers(plane.models, plane.tiers ?? {}) ?? plane.models;
     return coreResolveTaskModel({ model: DEFAULT_MODEL_REF }, { ...(expanded !== undefined ? { models: expanded } : {}) }).model;
 }
-export function resolveTaskModel(bodyModel, objective, catalog, allowlist, refusals) {
+export function resolveTaskModel(bodyModel, objective, catalog, atMention, refusals) {
     const mention = parseModelMention(objective, [...Object.keys(refusals ?? {}), ...Object.keys(catalog)]);
     const mentionUsable = mention.model !== undefined && Object.hasOwn(catalog, mention.model) ? mention.model : undefined;
     const explicit = typeof bodyModel === "string" ? matchCatalogModel(bodyModel, catalog, refusals) : undefined;
@@ -20,7 +27,7 @@ export function resolveTaskModel(bodyModel, objective, catalog, allowlist, refus
     const unknown = present && explicit === undefined && refusedExplicit === undefined;
     const model = explicit ?? mentionUsable ?? DEFAULT_MODEL_REF;
     const picked = explicit !== undefined ? { ref: explicit, source: "explicit", requested: repr } : mentionUsable !== undefined ? { ref: mentionUsable, source: "mention", requested: mentionUsable } : undefined;
-    const notAllowed = picked !== undefined && !isModelAllowlisted(picked.ref, catalog, allowlist, refusals)
+    const notAllowed = picked !== undefined && !isAtMentionable(picked.ref, catalog, atMention, refusals)
         ? { requested: picked.requested, resolved: terminalCatalogName(picked.ref, catalog, refusals) ?? picked.ref, source: picked.source }
         : undefined;
     return {
@@ -51,24 +58,22 @@ export function refusedCatalogEntry(ref, refusals) {
             return { name, refusal: r };
     return undefined;
 }
-export function isModelAllowlisted(ref, catalog, allowlist, refusals) {
-    if (allowlist === undefined || allowlist.length === 0)
-        return true;
-    const entry = catalogEntryOf(ref, catalog, refusals);
-    if (entry === undefined)
+export function isAtMentionable(ref, catalog, atMention, refusals) {
+    const name = terminalCatalogName(ref, catalog, refusals);
+    if (name === undefined)
         return true;
-    for (const name of allowlist) {
-        const allowed = catalogEntryOf(name, catalog, refusals);
-        if (allowed === undefined)
-            continue;
-        if (allowed === entry)
+    switch (atMention.mode) {
+        case "all":
             return true;
+        case "none":
+            return false;
+        case "only":
+            return atMention.models.includes(name);
+        default: {
+            const unhandled = atMention;
+            throw new Error(`atMention: unknown mode ${JSON.stringify(unhandled)}`);
+        }
     }
-    return false;
-}
-function catalogEntryOf(ref, catalog, refusals) {
-    const name = matchCatalogModel(ref, catalog, refusals);
-    return name === undefined ? undefined : catalog[name];
 }
 export function terminalCatalogName(ref, catalog, refusals) {
     const key = matchCatalogModel(ref, catalog, refusals);