@sema-agent/server 7.131.0 → 7.133.0

package/dist/model-provider.d.ts

@@ -77,20 +77,52 @@ export declare function modelBrainLane(provider: ModelProvider): ModelBrainLane;
  */
 export declare function catalogBrainLane(provider: string | undefined): ModelBrainLane;
 /**
- * 🔴 S-623 —— 一条目录条目在**本部署**上真正落哪条 brain 腿(= `createBrain` 的组装事实,不是词面)。
+ * 🔴 **本部署装上的路由表的唯一铸法**(core 7.53.0 #1842;S-623 的「词 ∧ 路由装上」合取由此收成「问表」)。
  *
- * `createBrain` 只在 anthropic 路由**装上**(`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 在场 ⇒
- * `config.anthropic` 在场)时才铸 `createRoutingBrain({anthropic}, {fallback: gatewayStack})`;没装时整台机器
- * 只有网关栈这一只 brain,**一切**条目(包括 `provider:"anthropic"` 的)都落 openai 兼容腿 ——
- * `apply-effective.ts` 那条 `web_admin_model_no_brain` warn 说的「mis-routes to the gateway brain」即此。
+ * 键 = `createRoutingBrain` 选线读的那个词(`model.provider`),值 = 那条路由上的东西 —— `createBrain` 铸 brain 交给路由器,判词侧(启动摘要、端点判官、
+ * hook 选线)铸路由自己的配置交给 {@link brainLaneFor}(core 的判官从不读值,只问 `Object.hasOwn(routes, word)`)。两侧走同一只函数 ⇒ 同一组键,
+ * 「哪条路由装上了」只有这里一处写法。
  *
- * 所以「这条路由要不要一个 openai 端点」的判据必须同时看词与装配:词判 {@link catalogBrainLane},
- * 装配判路由在不在。本函数是这一合取的**唯一**写法 —— 端点判官(`model-route-endpoint.ts`)、降级腿与
- * 启动摘要(`brain.ts`)都调它,不再各写一个 `=== "anthropic" && config.anthropic`。
+ * `anthropic` 键在场 ⇔ anthropic 路由装上(`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 在场 ⇒ `config.anthropic` 在场);没装时**键缺席**,
+ * 绝不写成 `{ anthropic: undefined }` —— core 7.53.0 起「装上的键而值不是 brain」是一条坏线路(该请求 error terminal),不再回落网关
+ * (core CHANGELOG #1842「the key must be absent, not `undefined`」)。视图上 `anthropic` 的自有键带 `undefined`(配置对象的形)照样读成没装。
+ */
+export declare function mountRoutes<R extends object, T>(view: {
+    readonly anthropic?: R | undefined;
+}, mount: (route: R) => T): Readonly<Record<string, T>>;
+/**
+ * 🔴 **anthropic 路由的请求根** —— 唯一读法(S-1655 / core 7.53.0 #1905)。声明了 `ANTHROPIC_BASE_URL` ⇒ 它;没声明 ⇒ core 包根导出的 `ANTHROPIC_DEFAULT_BASE_URL`
+ * (引擎的 Anthropic brain 的请求根与配对律的车道缺省、`fable5Model` 预设的 `baseUrl` 读的同一只常量)。「没声明」按引擎的读法:缺席、空串、纯空白都是没声明
+ * (core 原话:「nothing, an empty string and whitespace read as undeclared」)。修前本仓两处手抄字面量:主路由的声明根(`brain.ts`,`??`)与 hook 的 anthropic 腿根
+ * (`hooks/hook-llm.ts`,`||`)—— 一个根、两份拷贝、两种合取。
+ */
+export declare function anthropicRouteRoot(route: {
+    readonly baseUrl?: string | undefined;
+}): string;
+/**
+ * **请求根「算不算声明了」的唯一尺**:缺席、空串、纯空白都是没声明(core 原话 "nothing, an empty string and whitespace read as undeclared"),声明了就原样带回。
+ * anthropic 路由的请求根({@link anthropicRouteRoot})、openai 兼容路由的有效端点(`model-route-endpoint.ts` 的 `openaiRouteBaseUrl`)与 env 值级端口的 `endpointDeclared` 读同一只。
+ */
+export declare function declaredRootUrl(url: string | undefined): string | undefined;
+/** 判词侧的路由表:值 = 路由自己的配置({@link mountRoutes} 的恒等铸法 —— 判官不读值,只问键)。 */
+export declare function routeTableOf<R extends object>(view: {
+    readonly anthropic?: R | undefined;
+}): Readonly<Record<string, R>>;
+/**
+ * 🔴 **一条目录条目在本部署上真正落哪条 brain 腿**(= 引擎路由器对同一只表的答案,不是词面)—— 唯一判词。
+ *
+ * 判据是 core 包根导出的 `brainLaneOf({ provider }, routes)`(core 7.53.0 #1842):`createRoutingBrain` 对每个请求问的正是它,所以引擎主路由与本仓的
+ * 四处调用点(主路由降级腿与启动摘要在 `brain.ts`、端点判官 `model-route-endpoint.ts`、hook 选线 `hooks/hook-llm.ts`)读**一个**答案。修前本仓自写一只
+ * 合取 `dispatchBrainLane(provider, anthropicRouteMounted)`(`catalogBrainLane(provider) === "anthropic" ∧ 路由装上`)—— 两份写法,S-1630 那次真病
+ * (hook 面按词面判线、主路由按装配判线)就是两份写法分叉的样子。
+ *
+ * core 的答案是路由名或 `undefined`(网关 fallback 服务它:词下没装路由,或没有 string 词)。本部署只装 `anthropic` 一条路由(表的唯一铸法 {@link mountRoutes}),
+ * 所以答案映到本仓两词闭集:`"anthropic"` ⇒ anthropic 腿,`undefined` ⇒ 网关腿;别的名字结构上不可能(表里没有那个键),真撞上 ⇒ **响亮抛**([ref]:运行期
+ * miss 臂必须说出来,不静默折网关)。
  *
- * 🔴 S-704(7.101.0):**目录条目**已到不了「anthropic 词、路由没装」这一格 —— 模型面 stage 的逐条判据把它判成不可用
- * (`config.model_no_brain`,不进 `config.models`)。这一格今天只剩 **env 腿**:`MODEL_PROVIDER=anthropic` 而没配 anthropic
- * 凭据的部署,env 模型落网关腿、用的是网关自己的 `MODEL_API_KEY`(凭据与端点同属网关,不越界;是否也该拒启另车)。
+ * S-704(7.101.0):**目录条目**到不了「anthropic 词、路由没装」这一格 —— 模型面 stage 的逐条判据把它判成不可用(`config.model_no_brain`,那一判问的是
+ * 「词想要的腿装没装」,{@link catalogBrainLane},与本判词是两个问题)。这一格今天只剩 **env 腿**:`MODEL_PROVIDER=anthropic` 而没配 anthropic 凭据的部署,
+ * env 模型落网关腿、用的是网关自己的 `MODEL_API_KEY`(凭据与端点同属网关,不越界)。
  */
-export declare function dispatchBrainLane(provider: string | undefined, anthropicRouteMounted: boolean): ModelBrainLane;
+export declare function brainLaneFor(provider: string | undefined, routes: Readonly<Record<string, unknown>>): ModelBrainLane;
 //# sourceMappingURL=model-provider.d.ts.map

package/dist/model-provider.js

@@ -1,3 +1,4 @@
+import { ANTHROPIC_DEFAULT_BASE_URL, brainLaneOf } from "@sema-agent/core";
 export const MODEL_PROVIDER_WORDS = ["gateway", "vllm", "anthropic"];
 export function isModelProvider(word) {
     return word !== undefined && MODEL_PROVIDER_WORDS.includes(word);
@@ -23,7 +24,25 @@ export function modelBrainLane(provider) {
 export function catalogBrainLane(provider) {
     return isModelProvider(provider) ? modelBrainLane(provider) : "gateway";
 }
-export function dispatchBrainLane(provider, anthropicRouteMounted) {
-    return anthropicRouteMounted && catalogBrainLane(provider) === "anthropic" ? "anthropic" : "gateway";
+export function mountRoutes(view, mount) {
+    const route = view.anthropic;
+    return route !== undefined ? { anthropic: mount(route) } : {};
+}
+export function anthropicRouteRoot(route) {
+    return declaredRootUrl(route.baseUrl) ?? ANTHROPIC_DEFAULT_BASE_URL;
+}
+export function declaredRootUrl(url) {
+    return url !== undefined && url.trim() !== "" ? url : undefined;
+}
+export function routeTableOf(view) {
+    return mountRoutes(view, (route) => route);
+}
+export function brainLaneFor(provider, routes) {
+    const line = brainLaneOf({ provider }, routes);
+    if (line === undefined)
+        return "gateway";
+    if (line === "anthropic")
+        return "anthropic";
+    throw new Error(`brainLaneFor: the engine's route judge answered route "${line}", which this deployment never mounts (the route table holds only the anthropic route) — the table was built outside mountRoutes`);
 }
 //# sourceMappingURL=model-provider.js.map

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

@@ -20,8 +20,8 @@
  *    经 {@link judgeServedModelRoute}:目录被采纳 ⇒ 判目录表(目录视图),目录缺席 / 被整拒 / 没有启用条目 ⇒ 判 env 表(env 视图);
  *    严格名册布防(`isRosterGateArmed`)时 env 表是占位、从不被派发 ⇒ 不判它(备用网关那一条与表无关,照判)。
  *    不在 `loadConfig()`:那是目录应用**之前**,env 表还不知道会不会服务(目录一旦采纳就整张换掉它);
- *  · 包根导出的 `judgeModelRouteGap(env)`(`model-route-gap.ts`)问的是**env 腿**:「这份 env 交给引擎、没有目录时起不起得来」—— 同一只判据的 env 视图,
- *    目录在场时起服以目录为准;
+ *  · 壳 / 包问「这台引擎服务哪张表、起服判官怎么说」读 `GET /v1/models` 的 `modelPlane`(`model-plane-face.ts`,同一只 {@link judgeServedModelRoute});
+ *    起服前没有「将要服务的表」可判,所以没有起服前的预判口;
  *  · 热路径:`web-admin-client/apply-effective.ts` 的模型面 stage ⇒ 模型面组拒(opus 腿 O3:同候选其余组照落)、上一代模型面继续服务(目录视图);
  *  · run-local:配置源解析完之后按真要派发的表判(`run-local.ts`)—— 本入口没有名册门,不豁免占位;
  *  · 登记:`config-invariants.ts` 的 `model-route-endpoint` 条(表的「不许有表外不变量」职责);
@@ -43,22 +43,19 @@ export declare const MODEL_ROUTE_ENDPOINT_MISSING_CODE = "config.model_route_end
 /** 同族第二码:备用网关设了、主网关没设。与上一码分开是因为出路不同(补主网关 / 撤备用 vs 补主网关 / 给条目 baseUrl)。 */
 export declare const GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE = "config.gateway_fallback_without_primary";
 /**
- * **路由缺口的出路轴**(闭集;{@link judgeModelRouteGap} 的 `gap` 词,包根导出 —— 壳 / 包在引擎起来之前问同一句)。
+ * **路由缺口的出路轴**(闭集;`GET /v1/models.modelPlane.gap` 的词,包根导出其型)。**只有缺口两词** —— 通过 = 判决为 `undefined`(没有第三个词可说「无缺口」)。
  *
  * 与上面的**码**是两根轴:码是组拒的机读词(`ModelPlaneRefusalCode`,settings-schema 属主),这里是**出路**:
  *  · `endpoint_missing` —— 缺的是网关端点:openai 兼容腿上的条目解析不到 base URL(或备用网关设了、主网关没设);
  *    出路 = 设 `MODEL_GATEWAY_BASEURL`,或(目录视图)给条目自己的 `baseUrl` / (env 视图)挂 anthropic 路由、或不设 `MODEL_ID` 让目录缺省服务;
  *  · `lane_credential_missing` —— 缺的是**车道凭据**:条目的 provider 词是 `anthropic`(用户选的是 anthropic 车道),
  *    却因 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 都没有而没装上 anthropic 路由、落进了 openai 腿,那条腿又没有端点;
- *    出路 = 补那两把钥匙之一(设网关是另一条出路,拒因句一并给);
- *  · `none` —— 这份配置能派发到的每一条 openai 兼容路由都解析得到端点。
+ *    出路 = 补那两把钥匙之一(设网关是另一条出路,拒因句一并给)。
  *
- * **声明序 = 语义序**(缺口两词在前,`none` 最后);加一词 ⇒ 所有穷举 switch 当场编译红。
+ * **声明序 = 语义序**;加一词 ⇒ 所有穷举 switch 当场编译红。
  */
-export declare const MODEL_ROUTE_GAP_WORDS: readonly ["endpoint_missing", "lane_credential_missing", "none"];
+export declare const MODEL_ROUTE_GAP_WORDS: readonly ["endpoint_missing", "lane_credential_missing"];
 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` ⑧(出现在别处 = 有人又在铸缺省)。
@@ -97,7 +94,7 @@ export interface ModelRouteEndpointView {
  *
  * 判序即语义:
  *  ① 备用网关设了、主网关没设 ⇒ `config.gateway_fallback_without_primary`(备用是主的镜像,这一条与条目无关,先说);
- *  ② 逐条目:按 {@link dispatchBrainLane} 落 openai 腿、且 {@link openaiRouteBaseUrl} 解析不到 ⇒ 收集名字,
+ *  ② 逐条目:按 {@link brainLaneFor}(引擎路由器对本部署路由表的答案)落 openai 腿、且 {@link openaiRouteBaseUrl} 解析不到 ⇒ 收集名字,
  *     一句话**全部点名**(运维一次改完,而不是改一个撞下一个)。
  *
  * `default` 键是目录里另一条的别名(env 腿 `{default: m, [m.id]: m}`、center 腿 `models.default = models[picked]`),
@@ -107,8 +104,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;
+    /** 出路轴({@link MODEL_ROUTE_GAP_WORDS}):同一次判决给出,不从句子或码里反推(`lane_credential_missing` 与 `endpoint_missing` 共用一个码)。 */
+    readonly gap: ModelRouteGap;
     readonly reason: string;
 }
 /**

package/dist/model-route-endpoint.js

@@ -1,17 +1,14 @@
-import { dispatchBrainLane } from "./model-provider.js";
+import { brainLaneFor, catalogBrainLane, declaredRootUrl, routeTableOf } from "./model-provider.js";
 import { DEFAULT_MODEL_REF, 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", "none"];
+export const MODEL_ROUTE_GAP_WORDS = ["endpoint_missing", "lane_credential_missing"];
 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;
-}
 export function openaiRouteBaseUrl(routeBaseUrl, gatewayBaseUrl) {
-    return declared(routeBaseUrl) ?? declared(gatewayBaseUrl);
+    return declaredRootUrl(routeBaseUrl) ?? declaredRootUrl(gatewayBaseUrl);
 }
 function unresolvedRouteLabel(name, provider) {
-    return provider === "anthropic"
+    return catalogBrainLane(provider) === "anthropic"
         ? `"${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}"`;
 }
@@ -23,7 +20,7 @@ export function modelRouteEndpointRefusal(view, leg) {
     return judgeModelRouteEndpoint(view, leg)?.reason;
 }
 export function judgeModelRouteEndpoint(view, leg) {
-    const gateway = declared(view.gatewayBaseUrl);
+    const gateway = declaredRootUrl(view.gatewayBaseUrl);
     if (gateway === undefined && view.gatewayFallbackUrls.length > 0) {
         const reason = (`env MODEL_GATEWAY_FALLBACK_URLS is set but MODEL_GATEWAY_BASEURL is not [${GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE}] — ` +
             "the fallback URLs are mirrors of the primary gateway (same provider, same account, same key scope), tried only " +
@@ -32,18 +29,18 @@ export function judgeModelRouteEndpoint(view, leg) {
             "or unset MODEL_GATEWAY_FALLBACK_URLS.");
         return { code: GATEWAY_FALLBACK_WITHOUT_PRIMARY_CODE, gap: "endpoint_missing", reason };
     }
-    const anthropicMounted = view.anthropic !== undefined;
+    const routes = routeTableOf(view);
     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;
-        if (dispatchBrainLane(m.provider, anthropicMounted) !== "gateway")
+        if (brainLaneFor(m.provider, routes) !== "gateway")
             continue;
         if (openaiRouteBaseUrl(m.baseUrl, gateway) !== undefined)
             continue;
-        laneCredentialMissing ||= m.provider === "anthropic";
+        laneCredentialMissing ||= catalogBrainLane(m.provider) === "anthropic";
         unresolved.push(unresolvedRouteLabel(name, m.provider));
     }
     if (unresolved.length === 0)

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

@@ -0,0 +1,22 @@
+/**
+ * `@sema-agent/server/model-route-env` —— 模型路由 env 读法的**精选入口**(纯数据 + 纯函数;import 不写文件、不起句柄、不装监听器、不出声 —— 依赖的包在装载时读自己的环境变量不在此列)。
+ *
+ * 为什么有这只文件:引擎(core)是 BYOM —— 它只吃调用方交的路由表与 `baseUrl` / `apiKey`,从不读 `MODEL_*` / `ANTHROPIC_*` 这些 env 键。
+ * 「env 里哪几把键是模型路由、空串算不算设了、provider 怎么推断、这只模型走哪条车道、这条车道的端点 / 凭据取哪一对键」的读法属本服务,
+ * 在引擎起之前就要答这句话的调用方(壳首启、客户端运行时、sdk 转口)读这一只,不各抄一份键名与车道判。
+ *
+ * 为什么是子路径而不是包根:包根的依赖闭包是整台服务(存储、HTTP、沙箱……),这里只需要一张键表和几只纯函数;
+ * 值依赖仅 `@sema-agent/core`(车道判词)与 `@sema-agent/settings-schema`,仓内只有四只纯叶(`test/model-route-env-port.test.ts` 钉死)。
+ *
+ * 为什么是精选而不是把 `model-route-gap.ts` 整只暴露:那个模块里还有起服自己的读法助手(逗号串分词、cheap 槽铸 id)。把它们变成公开面,等于替实现细节背上 semver。
+ * 要加名字 = 改这只文件 + 同批改 `test/model-route-env-port.test.ts` 的闭集(新增公开面必须是一次有意的动作)。
+ *
+ *  · `MODEL_ROUTE_ENV_KEYS` —— 九把路由 env 键的闭表(字段名 → 键名);
+ *  · `readModelRouteEnv(env)` —— 读口:`env` 交整张 `Record<string, string | undefined>`(`process.env` 或等价快照),只按表点名取值;
+ *  · `envLaneTable(mainId, main, cheap)` —— env 腿的条目表(别名 `default` + 主槽 id + cheap 槽 id);
+ *  · `laneAndEndpointFor(env, model, routes)` —— 值级端口:车道 + 端点 / 凭据的键名(不含任何 env 值)。
+ */
+export { MODEL_ROUTE_ENV_KEYS, readModelRouteEnv, envLaneTable, laneAndEndpointFor } from "./model-route-gap.js";
+export type { EnvCheapSlot, LaneAndEndpoint, ModelRouteEnv, ModelRouteEnvName, ModelRouteEnvReading, ModelRouteSubject } from "./model-route-gap.js";
+export type { ModelBrainLane } from "./model-provider.js";
+//# sourceMappingURL=model-route-env.d.ts.map

package/dist/model-route-env.js

@@ -0,0 +1,2 @@
+export { MODEL_ROUTE_ENV_KEYS, readModelRouteEnv, envLaneTable, laneAndEndpointFor } from "./model-route-gap.js";
+//# sourceMappingURL=model-route-env.js.map

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

@@ -1,11 +1,33 @@
-import { type ModelRouteEndpointVerdict, type ModelRouteGapBreach } from "./model-route-endpoint.js";
 /**
- * 路由读数读的八把 env 键(**闭表**;`judgeModelRouteGap` 只碰这几把,测试用代理钉「读集 ⊆ 本表」)。
- * 配置目录的 D1 对账门把 {@link readModelRouteEnv} 的调用当作这八把键的读点(`test/config-catalog.test.ts` 的 `DELEGATED_ENV_READERS`,键集取本表,不手抄)。
+ * **env 模型路由读数的唯一读口**:`readModelRouteEnv(env)`、env 腿的条目表 `envLaneTable`,与车道值级端口 `laneAndEndpointFor`。
+ *
+ * ## 形(一只读口、一处调用)
+ * 「env 里哪几把键是模型路由、空串 = 未设、provider 的显式 / 推断 / 缺省、env 腿铸哪几个条目槽」的读法只在这里:
+ *  · {@link readModelRouteEnv}:`parseModelDomain`(`config.ts`,起服铸 `ServiceConfig` 的路由字段)吃它的读数(`process.env` 与测试快照是同一个入参位);
+ *  · {@link envLaneTable}:env 腿的条目名与键序(`parseModelDomain` 铸真 `Model` 表经它);
+ *  · {@link laneAndEndpointFor}:值级端口 —— 「这只模型在这张路由表上走哪条车道、这条车道的端点 / 凭据取哪一对 env 键」。车道只经 `brainLaneFor`
+ *    (core `brainLaneOf` 对路由表的答案)取,键名取 {@link MODEL_ROUTE_ENV_KEYS};**只交键名不交值**。
+ * 路由判据本身(「将要服务的那张表里每条 openai 兼容路由是否解析得到端点」)不在这里:唯一属主是 `model-route-endpoint.ts` 的 `judgeModelRouteEndpoint`,
+ * 起服段与 `GET /v1/models.modelPlane` 经 `judgeServedModelRoute` 问它 —— 它们判的是**将要服务的那张表**(env 表或目录表),不是本文件读出的 env 视图。
+ *
+ * ## 对外
+ * 本模块的精选再导出是子路径 `@sema-agent/server/model-route-env`(`src/model-route-env.ts`):引擎 core 是 BYOM(只吃调用方给的路由表,不读这些键),
+ * 别仓要在引擎起之前回答「走哪条车道、端点 / 凭据取哪一对键」,读这一只,不各抄一份键名与车道判。
+ *
+ * ## 纯
+ * 不读 `process.env`、不读文件、不枚举快照 —— 只按 {@link MODEL_ROUTE_ENV_KEYS} 点名取值(依赖闭包里没有 `node:*` / `process`,
+ * `test/model-route-env-reading.test.ts` 钉)。同入同出;返回值是新对象。provider 词域外的值在这里按引擎派发的口径读作网关腿(`brainLaneFor`:域外词的路由表里没有那个键 ⇒ 引擎路由器落网关 fallback),不在此拒(域外拒启是 `model-provider-word` 那条不变量的事)。
+ */
+import { type ModelBrainLane } from "./model-provider.js";
+/**
+ * 路由读数读的九把 env 键(**闭表**;{@link readModelRouteEnv} 只碰这几把,测试用代理钉「读集 ⊆ 本表」)。
+ * 配置目录的 D1 对账门把 {@link readModelRouteEnv} 的调用当作这九把键的读点(`test/config-catalog.test.ts` 的 `DELEGATED_ENV_READERS`,键集取本表,不手抄);
+ * 表与配置目录的 `modelPlane` 域同源(`test/model-route-env-port.test.ts` 对拍:表里每把键是目录的一行、目录里该域的端点 / 凭据行都在表里)。
  */
 export declare const MODEL_ROUTE_ENV_KEYS: {
     readonly gatewayBaseUrl: "MODEL_GATEWAY_BASEURL";
     readonly gatewayFallbackUrls: "MODEL_GATEWAY_FALLBACK_URLS";
+    readonly gatewayApiKey: "MODEL_API_KEY";
     readonly provider: "MODEL_PROVIDER";
     readonly mainId: "MODEL_ID";
     readonly cheapId: "MODEL_CHEAP_ID";
@@ -36,6 +58,12 @@ export interface ModelRouteEnvReading {
     readonly gatewayBaseUrl: string | undefined;
     /** `MODEL_GATEWAY_FALLBACK_URLS` 逐项 trim、丢空项。 */
     readonly gatewayFallbackUrls: string[];
+    /**
+     * `MODEL_API_KEY`(网关腿的部署级凭据):**原样**读 —— 与其余各把不同,空串**不**折成未设。brain 装配以**真值**判这把凭据发不发(空串部署一个凭据字节都不发),
+     * 起服铸的 `ServiceConfig.gatewayApiKey` 逐字保留空串(compose 的 `${VAR:-}` 模板与空 Secret 挂载天天产它);读数改折叠会改变那一位。
+     * 它只与网关端点配对(没有 {@link gatewayBaseUrl} 就不装载),配对由消费方判。
+     */
+    readonly gatewayApiKey: string | undefined;
     /** `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL`:空串 = 未设,别名各自独立(一个空别名不遮蔽另一个)。 */
     readonly anthropicApiKey: string | undefined;
     readonly anthropicAuthToken: string | undefined;
@@ -59,7 +87,7 @@ export interface ModelRouteEnvReading {
 export declare const csvOf: (raw: string | undefined) => string[];
 /**
  * **env 模型路由读数的唯一读口**(纯:按 {@link MODEL_ROUTE_ENV_KEYS} 点名取值,不读 `process.env`,不枚举入参)。
- * `parseModelDomain`(起服铸 `ServiceConfig`)与 {@link judgeModelRouteGap}(判官)吃同一份读数。
+ * `parseModelDomain`(起服铸 `ServiceConfig`)吃它的读数。
  */
 export declare function readModelRouteEnv(env: ModelRouteEnv): ModelRouteEnvReading;
 /**
@@ -69,36 +97,38 @@ export declare function readModelRouteEnv(env: ModelRouteEnv): ModelRouteEnvRead
 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 键的名字(闭集字面量并集:加键 / 改名 ⇒ 消费方的穷举处编译红)。 */
+export type ModelRouteEnvName = (typeof MODEL_ROUTE_ENV_KEYS)[keyof typeof MODEL_ROUTE_ENV_KEYS];
+/** {@link laneAndEndpointFor} 问的那只模型:只读它的 route 词 `provider`(`Model` / 目录条目 / `{ provider }` 都结构满足)。 */
+export interface ModelRouteSubject {
+    readonly provider?: string | undefined;
+}
+/** {@link laneAndEndpointFor} 的答案:**键名**与在场性,不含任何 env 值。 */
+export interface LaneAndEndpoint {
+    /** 这只模型在这张路由表上落哪条 brain 腿(引擎路由器对同一只表的答案)。 */
+    readonly lane: ModelBrainLane;
+    /** 这条腿的端点那把 env 键:网关腿 `MODEL_GATEWAY_BASEURL`、anthropic 腿 `ANTHROPIC_BASE_URL`。值由调用方自己从 env 取。 */
+    readonly endpointEnvName: ModelRouteEnvName;
+    /**
+     * 这把端点键在 env 里声明了吗(缺席 / 空串 / 纯空白都是未设 —— 与引擎装配选请求根是同一把尺)。网关腿**没有出厂缺省端点**:未声明 = 这条腿此刻没有端点;
+     * anthropic 腿未声明 = 请求根落引擎的 Anthropic 官方缺省根。
+     */
+    readonly endpointDeclared: boolean;
     /**
-     * env 腿的模型会不会被派发(缺省 `true`)。起服期严格名册布防(`CONFIG_REQUIRE_ROSTER=true` 且接了远程中心、非 dryRun)= 运维声明 env
-     * `MODEL_ID` 是**占位**:名册落地前计费提交 503、落地后整表换装 ⇒ env 腿从不被派发,不在「配置能派发到的」射程里(备用网关那一条与派发
-     * 无关,照判)。布防与否是中心接入的事实(不是路由键),快照读不出 ⇒ 由调用方给;壳问「本机引擎、配置在本机」那一形不用传。
+     * 这条腿此刻真会带上的凭据那把 env 键;没有会装载的凭据 ⇒ `undefined`。
+     *  · anthropic 腿:`ANTHROPIC_AUTH_TOKEN` 压过 `ANTHROPIC_API_KEY`(引擎装配同序),空串别名不遮蔽另一把;
+     *  · 网关腿:`MODEL_API_KEY`,**只在端点声明时**(凭据只与网关自己的根配对;没有网关就不装载),空串 = 没有凭据(keyless 部署)。
      */
-    readonly envLaneDispatchable?: boolean;
+    readonly apiKeyEnvName: ModelRouteEnvName | undefined;
 }
 /**
- * 判官的读数(闭集三词,穷举 switch 消费):
- *  · `none` —— 无缺口,仅此一键;
- *  · 缺口两词 —— `code` = 机读码(与 `reason` 里的方括号码同一个词;`lane_credential_missing` 也带 `config.model_route_endpoint_missing`),
- *    `reason` = 起服判官对 env 表拒启时的句子原文(env 视图:点名条目与三条 env 出路)。
- */
-export type ModelRouteGapReading = {
-    readonly gap: "none";
-} | {
-    [G in ModelRouteGapBreach]: {
-        readonly gap: G;
-        readonly code: ModelRouteEndpointVerdict["code"];
-        readonly reason: string;
-    };
-}[ModelRouteGapBreach];
-/**
- * **起服前可调的模型路由缺口纯判官**(与起服判官判 env 表时同一实现、同一句拒因;包根导出)。答的是 **env 腿**:没有目录在管时,这份 env 起不起得来
- * (目录在场时起服以目录为准,见文件头注)。
+ * **车道值级端口**:这只模型在这张路由表上走哪条车道,这条车道的端点 / 凭据取 env 的哪一对键。
+ *
+ * 车道 = `brainLaneFor(model.provider, routes)` —— core `brainLaneOf` 对路由表的答案(引擎路由器对每个请求问的那一只),不另写一份合取;
+ * 键名 = {@link MODEL_ROUTE_ENV_KEYS}。`routes` 是 core 路由表的原型(`Object.hasOwn(routes, 词)` 的表;`anthropic` 键在场 ⇔ anthropic 路由装上)。
+ * **只交键名不交值**:凭据与端点的值调用方自己从 env 取,本函数的答案里没有任何 env 值。
  *
- * @param env 一份 env 快照(只读 {@link MODEL_ROUTE_ENV_KEYS} 那八把键;`process.env` 也行)。
- * @returns 三词之一;有缺口时带 `code` 与 `reason`(见 {@link ModelRouteGapReading})。
+ * 纯:不读 `process.env`,只按键表点名取值、不枚举入参。路由表里有本部署从不装的键(表在 `mountRoutes` 之外铸)⇒ 抛(`brainLaneFor` 的响亮臂),不折网关。
  */
-export declare function judgeModelRouteGap(env: ModelRouteEnv, opts?: ModelRouteGapOptions): ModelRouteGapReading;
+export declare function laneAndEndpointFor(env: ModelRouteEnv, model: ModelRouteSubject, routes: Readonly<Record<string, unknown>>): LaneAndEndpoint;
 //# sourceMappingURL=model-route-gap.d.ts.map

package/dist/model-route-gap.js

@@ -1,8 +1,9 @@
+import { brainLaneFor, declaredRootUrl } from "./model-provider.js";
 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",
+    gatewayApiKey: "MODEL_API_KEY",
     provider: "MODEL_PROVIDER",
     mainId: "MODEL_ID",
     cheapId: "MODEL_CHEAP_ID",
@@ -38,6 +39,7 @@ export function readModelRouteEnv(env) {
     return {
         gatewayBaseUrl: declaredValue(env[K.gatewayBaseUrl]),
         gatewayFallbackUrls: csvOf(env[K.gatewayFallbackUrls]),
+        gatewayApiKey: env[K.gatewayApiKey],
         anthropicApiKey,
         anthropicAuthToken,
         anthropicBaseUrl,
@@ -62,19 +64,23 @@ export function envLaneTable(mainId, main, cheap) {
         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,
-    }, "env");
-    if (verdict === undefined)
-        return { gap: "none" };
-    return { gap: verdict.gap, code: verdict.code, reason: verdict.reason };
+export function laneAndEndpointFor(env, model, routes) {
+    const K = MODEL_ROUTE_ENV_KEYS;
+    const reading = readModelRouteEnv(env);
+    const lane = brainLaneFor(model.provider, routes);
+    switch (lane) {
+        case "anthropic":
+            return {
+                lane,
+                endpointEnvName: K.anthropicBaseUrl,
+                endpointDeclared: declaredRootUrl(reading.anthropicBaseUrl) !== undefined,
+                apiKeyEnvName: reading.anthropicAuthToken !== undefined ? K.anthropicAuthToken : reading.anthropicApiKey !== undefined ? K.anthropicApiKey : undefined,
+            };
+        case "gateway": {
+            const endpointDeclared = declaredRootUrl(reading.gatewayBaseUrl) !== undefined;
+            const credentialLoaded = endpointDeclared && reading.gatewayApiKey !== undefined && reading.gatewayApiKey !== "";
+            return { lane, endpointEnvName: K.gatewayBaseUrl, endpointDeclared, apiKeyEnvName: credentialLoaded ? K.gatewayApiKey : undefined };
+        }
+    }
 }
 //# sourceMappingURL=model-route-gap.js.map

package/dist/observability/corrupt-read-seat.d.ts

@@ -120,6 +120,13 @@ export declare const JSONL_REPLAY_SEATS: {
         readonly note: "S-582 fail-closed: an unreadable consume/release line would resurrect a claimed import ticket as unclaimed (one human consent redeemed twice). The face refuses every read and write until a person inspects the file.";
         readonly remedy: "the permission-rule lane is fail-closed until a person inspects the file (moving it aside restarts the lane with an empty log)";
     };
+    readonly "workflow-park-decisions": {
+        readonly direction: "fail-closed";
+        readonly event: "workflow_park_decisions_corrupt_read";
+        readonly face: "workflow park decision ledger";
+        readonly note: string;
+        readonly remedy: string;
+    };
     readonly "approval-ask-journal": {
         readonly direction: "fail-open";
         readonly tag: "server.approval-ask-journal.corrupt-record-skipped";

package/dist/observability/corrupt-read-seat.js

@@ -126,6 +126,15 @@ export const JSONL_REPLAY_SEATS = {
         note: "S-582 fail-closed: an unreadable consume/release line would resurrect a claimed import ticket as unclaimed (one human consent redeemed twice). The face refuses every read and write until a person inspects the file.",
         remedy: RULE_LANE_REMEDY,
     },
+    "workflow-park-decisions": {
+        direction: "fail-closed",
+        event: "workflow_park_decisions_corrupt_read",
+        face: "workflow park decision ledger",
+        note: "fail-closed: an unreadable line may be the decision that REPLACED an earlier one for the same approval — replaying the rest would bring the replaced decision back and hand it to the engine on the session's next run. " +
+            "Every decide on a workflow child's approval is refused until a person inspects the file; a run start reads the ledger as holding no decisions (counted under server.workflow-park-decision.store-unreadable) and starts without them.",
+        remedy: "deciding workflow child approvals on this deployment is refused until a person inspects the file (runs keep starting, without the held decisions). Moving it aside drops every held decision in it — " +
+            "the approvals they answered stay pending and can be decided again — so it is safe to move aside and restart",
+    },
     "approval-ask-journal": { direction: "fail-open", tag: "server.approval-ask-journal.corrupt-record-skipped" },
     "run-store": { direction: "fail-open", tag: "server.run-store.corrupt-record-skipped" },
     "resume-anchor": { direction: "fail-open", tag: "server.resume-anchor.corrupt-record-skipped" },

package/dist/observability/cost-taxonomy.d.ts

@@ -18,6 +18,7 @@
  * MODEL_COST_* — opt-in pricing). The per-run usage extraction (sandbox wall-clock from the run's remote-env
  * spans, tool-call count from the trace) is the data-source wiring fed in by the caller; this layer is the math.
  */
+import type { TaskResult } from "@sema-agent/core";
 /** Deployment infra pricing (config; default 0 = not priced, mirrors MODEL_COST_*). */
 export interface InfraCostRates {
     /** $ (micro-USD) per tool invocation. */
@@ -40,13 +41,12 @@ export interface InfraCostBreakdown {
     egressMicroUsd: number;
     totalMicroUsd: number;
 }
-/** Core's LLM-family breakdown (mirror of core `Stats.costBreakdown`), accepted read-only for composition. */
-export interface LlmCostBreakdown {
-    llmRootMicroUsd: number;
-    nestedSubagentMicroUsd: number;
-    memoryConsolidationMicroUsd: number;
-    compactionMicroUsd: number;
-}
+/**
+ * Core's LLM-family breakdown — core's own `TaskResult.stats.costBreakdown` type, accepted read-only for composition (S-1687: not a hand-copied
+ * mirror — core 7.52.0 added the `sideCallMicroUsd` "of which" line and a copy would have missed it). Its partition lines add up to core's
+ * `costMicroUsd`; `sideCallMicroUsd` (the classifier's and mods' model calls) is an "of which" line INSIDE `llmRootMicroUsd`, never added to them.
+ */
+export type LlmCostBreakdown = NonNullable<TaskResult["stats"]["costBreakdown"]>;
 /** The combined supervisor cost surface: core's LLM axes + the service's infra axes + a reconciled grand total. */
 export interface SupervisorCostBreakdown {
     llm: LlmCostBreakdown | null;

package/dist/observability/err-text.d.ts

@@ -3,4 +3,10 @@
  *  或 `Error` 实例的 message getter 返回带会抛 length getter 的非字符串——裸写 `e instanceof Error ? e.message : String(e)`
  *  在 catch 里自己抛,外层 catch 吞掉 setTerminal ⇒ run 卡 running、claim 悬挂到 reaper。这里**不抛、恒返字符串**。 */
 export declare function errorText(e: unknown): string;
+/**
+ * 运维日志里一个错误的**类名**(`err.name`;非 Error 抛出物取 `typeof`)—— 日志只带类名、不带消息原文({@link errorText} 是原文那一只):
+ * 投递口 / 库连接上抛出的错误,消息可能带对端文本或库侧文本,类名足够回答「是哪一类故障」,原文留给抛出处自己的错误路径。
+ * `name` 的 getter 抛、或它交回的不是字符串(拼进模板串会抛的 Symbol 等)⇒ `<unreadable>`。
+ */
+export declare function errorKindOf(err: unknown): string;
 //# sourceMappingURL=err-text.d.ts.map

package/dist/observability/err-text.js

@@ -1,10 +1,24 @@
-export function errorText(e) {
+const KIND_UNREADABLE = "<unreadable>";
+function readOr(read, marker) {
     try {
-        const m = e instanceof Error ? e.message : e;
-        return typeof m === "string" ? m : String(m);
+        return read();
     }
     catch {
-        return "<unprintable>";
+        return marker;
     }
 }
+export function errorText(e) {
+    return readOr(() => {
+        const m = e instanceof Error ? e.message : e;
+        return typeof m === "string" ? m : String(m);
+    }, "<unprintable>");
+}
+export function errorKindOf(err) {
+    return readOr(() => {
+        if (!(err instanceof Error))
+            return typeof err;
+        const name = err.name;
+        return typeof name === "string" ? name : KIND_UNREADABLE;
+    }, KIND_UNREADABLE);
+}
 //# sourceMappingURL=err-text.js.map