@sema-agent/settings-schema 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -6,6 +6,40 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 1.10.0 — 2026-09-09 — `models.models[].compat` 引擎兼容声明席(镜像 `OpenAICompletionsCompat`;新键=minor)
+
+- 引擎 `OpenAICompletionsCompat`(五键 `thinkingFormat` / `reasoningEffortLevels` / `maxTokensField` /
+  `requiresReasoningContentOnAssistantMessages` / `supportsReasoningEffort`)早就能按模型发兼容声明,但 `ModelEntry`
+  没有这个键 ⇒ 目录条目写了 `compat` 在 parse 期被 strip 剥掉,声明**根本到不了引擎**;`extraBody` 也穿不过(引擎的
+  OpenAI 保留键表拦下 `chat_template_kwargs` / `enable_thinking`)。1.10.0 起 `ModelEntry.compat?`
+  (`z.unknown().optional()`)。
+- **三问**:①谁需要 —— vLLM / Qwen 类**缺省开思考**的网关(关思考只能靠 `chat_template_kwargs.enable_thinking=false`),
+  以及任何要按模型钉 `max_tokens` 拼写 / reasoning 档位的部署;②谁受伤 —— 无:additive 可选键,缺席 = 键不铸 = 今日行为,
+  存量配置零迁移;③补偿 —— 不加旋钮(不写就没有这个键)。
+- **解析透明**,与 1.7.2 `source` / 1.9.0 `toolFaces` 同一条规矩:形与词表(`thinkingFormat` 有哪几个词)的校验归
+  消费方摄入侧**单点**,本仓刻意不复述那张表 —— 本域整域 all-or-nothing,一次形/词拒会把整套模型目录抹掉(1.7.1 升级
+  回归的形)。
+- 唯一保留的解析拒 = 与兄弟字段 `extraBody` **同一只**自由形安全判据(secret 形键/值、访问器、循环、非 JSON、过深):
+  1.10.0 把这条流水线从 `extraBody` 里抽成共用的 `vetFreeFormJson(v, field)`(getter-free 描述符走查 → 单次
+  `JSON.stringify` → 复扫的 clone 即持久值),两个字段同调一处,不留第二份判据。`extraBody` 的「必须是 plain JSON
+  对象」形门是它自己的(它要被摊进请求体),行为逐字不变(消息文本与判定结果均未变)。深度上限仍是 `MAX_EXTRA_BODY_DEPTH`
+  (`./hash` 上的已发布导出,不改名 —— 改名是 BREAKING,收益纯属观感),其 JSDoc 已改写成「所有自由形字段共用的一只上限」。
+- 红先:`test/model-compat-1.10.test.ts` 七格(①原样保留 ①b 五键全量 ②缺席不铸 ③坏形不整域默认 ④安全判据拒
+  ⑤`loadLocalConfig` 全链到 `effective.models.models[].compat` ⑤b `readEffectiveWire` wire 腿同样透传且不降级整域)。
+- 消费方点名(能力显式表态制):**worker 服务**(投影/env/读面,随其 7.69.0)、**CLI**(探针写目录条目)、
+  **config-center 产品**(models 域透传)。
+- 顺带:`package-lock.json` 的 `packages[""].version` 自 1.6.0 起停在 `1.5.0`(历次发版只改了顶层 `version`),
+  本节一并对齐到 1.10.0。
+
+## 1.9.0 — 2026-09-08 — `mcp.servers[].toolFaces` 覆盖层声明面(core 7.8.0 design/388 片 1 F7;新键=minor)
+
+- core 7.8.0 起 `McpServerSpec.toolFaces?: Record<remoteToolName, { family?, pathTarget?: {param, aliases?, access, skillScopeEligible?}, renderHints?, ruleFace? }>`
+  是工具名册的 face 覆盖层。本仓只加**解析透明**的键(`z.unknown().optional()`),与 1.7.2 `source` 同一条规矩:形的校验属 core 摄入侧
+  (不合 schema 的工具**不挂**并通告一次 `config.tool_face_invalid`),本仓不复述那张表——这一域 all-or-nothing,任一字段解析拒都会让整套
+  mcp 服务器静默消失(S-144 类病)。缺席 = 不铸键。
+- 红先:`test/mcp-tool-faces-1.9.test.ts`(1.8.0 上「带 toolFaces 的 server 键原样到消费方」红)。
+- 消费方:sema-server(MCP 配置面三腿透传,随 7.66.0)、cli(settings 面)。
+
 ## 1.8.0 — 2026-09-07 — `ModelRole` 闭集对齐 core:加 `classifier` / `consolidate`(新词=minor)
 
 - cli [6554] 真案:core `ModelRole` 早有 `classifier`(auto 权限分类器,FALLBACK classifier→summarize→default、tier 缺省 flash)

package/dist/hash.d.ts

@@ -20,9 +20,13 @@ export declare const MAX_HASH_DEPTH = 200;
  *  getVersion/getEffective (hard-DoS poison pill) — the two caps were each hardened in isolation but never
  *  reconciled (R18). The real max wrapper is ~4–6; 32 is a deliberate ≫ margin. */
 export declare const MAX_HASH_WRAPPER_RESERVE = 32;
-/** Depth cap for a standalone `extraBody` value, reconciled with the hash cap MINUS the wrapper reserve so that
- *  ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any real
- *  extraBody (OpenAI-style request params nest <10 deep). */
+/** Depth cap for a standalone FREE-FORM config value, reconciled with the hash cap MINUS the wrapper reserve so
+ *  that ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any
+ *  real free-form value (OpenAI-style request params nest <10 deep).
+ *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody` and, since
+ *  1.10.0, `ModelEntry.compat`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`), so one cap
+ *  serves both. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
+ *  (renaming it would be a BREAKING change for a purely cosmetic gain). */
 export declare const MAX_EXTRA_BODY_DEPTH: number;
 /** Deterministic JSON with sorted object keys (so key order never affects the hash). */
 export declare function stableStringify(v: unknown, depth?: number): string;

package/dist/hash.js

@@ -20,9 +20,13 @@ export const MAX_HASH_DEPTH = 200;
  *  getVersion/getEffective (hard-DoS poison pill) — the two caps were each hardened in isolation but never
  *  reconciled (R18). The real max wrapper is ~4–6; 32 is a deliberate ≫ margin. */
 export const MAX_HASH_WRAPPER_RESERVE = 32;
-/** Depth cap for a standalone `extraBody` value, reconciled with the hash cap MINUS the wrapper reserve so that
- *  ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any real
- *  extraBody (OpenAI-style request params nest <10 deep). */
+/** Depth cap for a standalone FREE-FORM config value, reconciled with the hash cap MINUS the wrapper reserve so
+ *  that ANYTHING the validator accepts is guaranteed hashable in every context it's later hashed in. 168 ≫ any
+ *  real free-form value (OpenAI-style request params nest <10 deep).
+ *  Scope: the ONE cap for EVERY free-form field vetted by `vetFreeFormJson` (`ModelEntry.extraBody` and, since
+ *  1.10.0, `ModelEntry.compat`) — they sit at the SAME wrapper depth (`{models:{models:[{…}]}}`), so one cap
+ *  serves both. The `EXTRA_BODY` spelling is kept because this is a published export on the `./hash` subpath
+ *  (renaming it would be a BREAKING change for a purely cosmetic gain). */
 export const MAX_EXTRA_BODY_DEPTH = MAX_HASH_DEPTH - MAX_HASH_WRAPPER_RESERVE;
 /** Deterministic JSON with sorted object keys (so key order never affects the hash). */
 export function stableStringify(v, depth = 0) {

package/dist/types.d.ts

@@ -184,6 +184,24 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
      *  through), e.g. {frequency_penalty:0.5, presence_penalty:0.3}. Non-secret model metadata — same class
      *  as cost/tier. Shipped on /effective.models.models[].extraBody; the service merges it into the request. */
     extraBody: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, Record<string, unknown> | undefined, unknown>;
+    /** Per-model wire-compat declaration for the OpenAI-completions lane — mirrors the engine's
+     *  `OpenAICompletionsCompat` (five keys: `thinkingFormat` / `reasoningEffortLevels` / `maxTokensField` /
+     *  `requiresReasoningContentOnAssistantMessages` / `supportsReasoningEffort`). Real need: a vLLM/Qwen-class
+     *  gateway that thinks by DEFAULT can only be turned off with `chat_template_kwargs.enable_thinking=false`,
+     *  which `extraBody` cannot carry (the engine reserves those request keys) — and without this key a catalog
+     *  entry that declares it is stripped at parse, so the declaration never reaches the engine at all.
+     *
+     *  **Parse-transparent** (`z.unknown()`), same rule as `McpServerSpec.source` (1.7.2) and `.toolFaces` (1.9.0):
+     *  the SHAPE and the VOCABULARY (which `thinkingFormat` words exist) are the consuming side's single point —
+     *  this package deliberately does NOT restate that table. This domain parses all-or-nothing, so a shape/word
+     *  rejection HERE would blank the entire model catalog over one bad key (the 1.7.1 upgrade regression). ABSENT
+     *  = key not minted = today's behaviour, zero migration.
+     *
+     *  The ONE rejection that remains is the free-form SAFETY judgment shared with `extraBody`
+     *  ({@link vetFreeFormJson}): a secret-shaped key/value, an accessor, a cycle, non-JSON, or too deep to hash
+     *  later. That is not shape validation — it is the boundary every free-form value must clear to enter the
+     *  persisted config and `stableHash` (R18). */
+    compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
     /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
      *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
     quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -219,6 +237,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
         cacheWrite: number;
     } | undefined;
     extraBody?: Record<string, unknown> | undefined;
+    compat?: unknown;
     notes?: string | undefined;
 }, {
     id: string;
@@ -248,6 +267,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
         cacheWrite?: number | undefined;
     } | undefined;
     extraBody?: unknown;
+    compat?: unknown;
     quotaWeight?: number | undefined;
     enabled?: boolean | undefined;
     notes?: string | undefined;
@@ -281,6 +301,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
         cacheWrite: number;
     } | undefined;
     extraBody?: Record<string, unknown> | undefined;
+    compat?: unknown;
     notes?: string | undefined;
 }, {
     id: string;
@@ -310,6 +331,7 @@ export declare const ModelEntry: z.ZodEffects<z.ZodObject<{
         cacheWrite?: number | undefined;
     } | undefined;
     extraBody?: unknown;
+    compat?: unknown;
     quotaWeight?: number | undefined;
     enabled?: boolean | undefined;
     notes?: string | undefined;
@@ -504,6 +526,24 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
          *  through), e.g. {frequency_penalty:0.5, presence_penalty:0.3}. Non-secret model metadata — same class
          *  as cost/tier. Shipped on /effective.models.models[].extraBody; the service merges it into the request. */
         extraBody: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, Record<string, unknown> | undefined, unknown>;
+        /** Per-model wire-compat declaration for the OpenAI-completions lane — mirrors the engine's
+         *  `OpenAICompletionsCompat` (five keys: `thinkingFormat` / `reasoningEffortLevels` / `maxTokensField` /
+         *  `requiresReasoningContentOnAssistantMessages` / `supportsReasoningEffort`). Real need: a vLLM/Qwen-class
+         *  gateway that thinks by DEFAULT can only be turned off with `chat_template_kwargs.enable_thinking=false`,
+         *  which `extraBody` cannot carry (the engine reserves those request keys) — and without this key a catalog
+         *  entry that declares it is stripped at parse, so the declaration never reaches the engine at all.
+         *
+         *  **Parse-transparent** (`z.unknown()`), same rule as `McpServerSpec.source` (1.7.2) and `.toolFaces` (1.9.0):
+         *  the SHAPE and the VOCABULARY (which `thinkingFormat` words exist) are the consuming side's single point —
+         *  this package deliberately does NOT restate that table. This domain parses all-or-nothing, so a shape/word
+         *  rejection HERE would blank the entire model catalog over one bad key (the 1.7.1 upgrade regression). ABSENT
+         *  = key not minted = today's behaviour, zero migration.
+         *
+         *  The ONE rejection that remains is the free-form SAFETY judgment shared with `extraBody`
+         *  ({@link vetFreeFormJson}): a secret-shaped key/value, an accessor, a cycle, non-JSON, or too deep to hash
+         *  later. That is not shape validation — it is the boundary every free-form value must clear to enter the
+         *  persisted config and `stableHash` (R18). */
+        compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
         /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
          *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
         quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -539,6 +579,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite: number;
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
+        compat?: unknown;
         notes?: string | undefined;
     }, {
         id: string;
@@ -568,6 +609,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite?: number | undefined;
         } | undefined;
         extraBody?: unknown;
+        compat?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -601,6 +643,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite: number;
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
+        compat?: unknown;
         notes?: string | undefined;
     }, {
         id: string;
@@ -630,6 +673,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite?: number | undefined;
         } | undefined;
         extraBody?: unknown;
+        compat?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -753,6 +797,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite: number;
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
+        compat?: unknown;
         notes?: string | undefined;
     }[];
     roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -808,6 +853,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite?: number | undefined;
         } | undefined;
         extraBody?: unknown;
+        compat?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -865,6 +911,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite: number;
         } | undefined;
         extraBody?: Record<string, unknown> | undefined;
+        compat?: unknown;
         notes?: string | undefined;
     }[];
     roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -920,6 +967,7 @@ export declare const ModelsConfig: z.ZodEffects<z.ZodObject<{
             cacheWrite?: number | undefined;
         } | undefined;
         extraBody?: unknown;
+        compat?: unknown;
         quotaWeight?: number | undefined;
         enabled?: boolean | undefined;
         notes?: string | undefined;
@@ -7334,6 +7382,12 @@ export declare const McpServerSpec: z.ZodObject<{
      *  both legs stripped it (default-strip object); this is the declaration half of the consumer-side fix
      *  (ticket B-036 / S-143), the projection half lives in the consumer. */
     source: z.ZodOptional<z.ZodUnknown>;
+    /** 1.9.0 —— core 7.8.0(design/388 片 1 F7)`toolFaces` 覆盖层:按远端工具名 key 的 face 声明
+     *  (`{ family?, pathTarget?: {param, aliases?, access, skillScopeEligible?}, renderHints?, ruleFace? }`)。
+     *  与 `source` 同一条规矩:**解析透明**(`z.unknown()`),形的校验属 core 摄入侧(不合 schema 的工具**不挂**并
+     *  通告一次 `config.tool_face_invalid`);本仓不复述那张表 —— 这一域 all-or-nothing,任一字段解析拒都会
+     *  让整套 mcp 服务器静默消失。缺席 = 不铸键。 */
+    toolFaces: z.ZodOptional<z.ZodUnknown>;
     notes: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
@@ -7356,6 +7410,7 @@ export declare const McpServerSpec: z.ZodObject<{
     allowTools?: string[] | undefined;
     contentOrigin?: "local" | "execution" | "external" | undefined;
     source?: unknown;
+    toolFaces?: unknown;
 }, {
     name: string;
     transport: {
@@ -7377,6 +7432,7 @@ export declare const McpServerSpec: z.ZodObject<{
     elicitation?: boolean | undefined;
     contentOrigin?: "local" | "execution" | "external" | undefined;
     source?: unknown;
+    toolFaces?: unknown;
 }>;
 export type McpServerSpec = z.infer<typeof McpServerSpec>;
 export declare const McpConfig: z.ZodEffects<z.ZodObject<{
@@ -7465,6 +7521,12 @@ export declare const McpConfig: z.ZodEffects<z.ZodObject<{
          *  both legs stripped it (default-strip object); this is the declaration half of the consumer-side fix
          *  (ticket B-036 / S-143), the projection half lives in the consumer. */
         source: z.ZodOptional<z.ZodUnknown>;
+        /** 1.9.0 —— core 7.8.0(design/388 片 1 F7)`toolFaces` 覆盖层:按远端工具名 key 的 face 声明
+         *  (`{ family?, pathTarget?: {param, aliases?, access, skillScopeEligible?}, renderHints?, ruleFace? }`)。
+         *  与 `source` 同一条规矩:**解析透明**(`z.unknown()`),形的校验属 core 摄入侧(不合 schema 的工具**不挂**并
+         *  通告一次 `config.tool_face_invalid`);本仓不复述那张表 —— 这一域 all-or-nothing,任一字段解析拒都会
+         *  让整套 mcp 服务器静默消失。缺席 = 不铸键。 */
+        toolFaces: z.ZodOptional<z.ZodUnknown>;
         notes: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
@@ -7487,6 +7549,7 @@ export declare const McpConfig: z.ZodEffects<z.ZodObject<{
         allowTools?: string[] | undefined;
         contentOrigin?: "local" | "execution" | "external" | undefined;
         source?: unknown;
+        toolFaces?: unknown;
     }, {
         name: string;
         transport: {
@@ -7508,6 +7571,7 @@ export declare const McpConfig: z.ZodEffects<z.ZodObject<{
         elicitation?: boolean | undefined;
         contentOrigin?: "local" | "execution" | "external" | undefined;
         source?: unknown;
+        toolFaces?: unknown;
     }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     servers: {
@@ -7531,6 +7595,7 @@ export declare const McpConfig: z.ZodEffects<z.ZodObject<{
         allowTools?: string[] | undefined;
         contentOrigin?: "local" | "execution" | "external" | undefined;
         source?: unknown;
+        toolFaces?: unknown;
     }[];
 }, {
     servers?: {
@@ -7554,6 +7619,7 @@ export declare const McpConfig: z.ZodEffects<z.ZodObject<{
         elicitation?: boolean | undefined;
         contentOrigin?: "local" | "execution" | "external" | undefined;
         source?: unknown;
+        toolFaces?: unknown;
     }[] | undefined;
 }>, {
     servers: {
@@ -7577,6 +7643,7 @@ export declare const McpConfig: z.ZodEffects<z.ZodObject<{
         allowTools?: string[] | undefined;
         contentOrigin?: "local" | "execution" | "external" | undefined;
         source?: unknown;
+        toolFaces?: unknown;
     }[];
 }, {
     servers?: {
@@ -7600,6 +7667,7 @@ export declare const McpConfig: z.ZodEffects<z.ZodObject<{
         elicitation?: boolean | undefined;
         contentOrigin?: "local" | "execution" | "external" | undefined;
         source?: unknown;
+        toolFaces?: unknown;
     }[] | undefined;
 }>;
 export type McpConfig = z.infer<typeof McpConfig>;
@@ -9379,6 +9447,24 @@ export declare const DOMAIN_SCHEMAS: {
              *  through), e.g. {frequency_penalty:0.5, presence_penalty:0.3}. Non-secret model metadata — same class
              *  as cost/tier. Shipped on /effective.models.models[].extraBody; the service merges it into the request. */
             extraBody: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, Record<string, unknown> | undefined, unknown>;
+            /** Per-model wire-compat declaration for the OpenAI-completions lane — mirrors the engine's
+             *  `OpenAICompletionsCompat` (five keys: `thinkingFormat` / `reasoningEffortLevels` / `maxTokensField` /
+             *  `requiresReasoningContentOnAssistantMessages` / `supportsReasoningEffort`). Real need: a vLLM/Qwen-class
+             *  gateway that thinks by DEFAULT can only be turned off with `chat_template_kwargs.enable_thinking=false`,
+             *  which `extraBody` cannot carry (the engine reserves those request keys) — and without this key a catalog
+             *  entry that declares it is stripped at parse, so the declaration never reaches the engine at all.
+             *
+             *  **Parse-transparent** (`z.unknown()`), same rule as `McpServerSpec.source` (1.7.2) and `.toolFaces` (1.9.0):
+             *  the SHAPE and the VOCABULARY (which `thinkingFormat` words exist) are the consuming side's single point —
+             *  this package deliberately does NOT restate that table. This domain parses all-or-nothing, so a shape/word
+             *  rejection HERE would blank the entire model catalog over one bad key (the 1.7.1 upgrade regression). ABSENT
+             *  = key not minted = today's behaviour, zero migration.
+             *
+             *  The ONE rejection that remains is the free-form SAFETY judgment shared with `extraBody`
+             *  ({@link vetFreeFormJson}): a secret-shaped key/value, an accessor, a cycle, non-JSON, or too deep to hash
+             *  later. That is not shape validation — it is the boundary every free-form value must clear to enter the
+             *  persisted config and `stableHash` (R18). */
+            compat: z.ZodEffects<z.ZodOptional<z.ZodUnknown>, unknown, unknown>;
             /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
              *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
             quotaWeight: z.ZodDefault<z.ZodNumber>;
@@ -9414,6 +9500,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite: number;
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
+            compat?: unknown;
             notes?: string | undefined;
         }, {
             id: string;
@@ -9443,6 +9530,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite?: number | undefined;
             } | undefined;
             extraBody?: unknown;
+            compat?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9476,6 +9564,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite: number;
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
+            compat?: unknown;
             notes?: string | undefined;
         }, {
             id: string;
@@ -9505,6 +9594,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite?: number | undefined;
             } | undefined;
             extraBody?: unknown;
+            compat?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9628,6 +9718,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite: number;
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
+            compat?: unknown;
             notes?: string | undefined;
         }[];
         roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -9683,6 +9774,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite?: number | undefined;
             } | undefined;
             extraBody?: unknown;
+            compat?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -9740,6 +9832,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite: number;
             } | undefined;
             extraBody?: Record<string, unknown> | undefined;
+            compat?: unknown;
             notes?: string | undefined;
         }[];
         roles: Partial<Record<"default" | "summarize" | "subagent" | "team" | "synthesize" | "verifier" | "classifier" | "consolidate", {
@@ -9795,6 +9888,7 @@ export declare const DOMAIN_SCHEMAS: {
                 cacheWrite?: number | undefined;
             } | undefined;
             extraBody?: unknown;
+            compat?: unknown;
             quotaWeight?: number | undefined;
             enabled?: boolean | undefined;
             notes?: string | undefined;
@@ -10138,6 +10232,12 @@ export declare const DOMAIN_SCHEMAS: {
              *  both legs stripped it (default-strip object); this is the declaration half of the consumer-side fix
              *  (ticket B-036 / S-143), the projection half lives in the consumer. */
             source: z.ZodOptional<z.ZodUnknown>;
+            /** 1.9.0 —— core 7.8.0(design/388 片 1 F7)`toolFaces` 覆盖层:按远端工具名 key 的 face 声明
+             *  (`{ family?, pathTarget?: {param, aliases?, access, skillScopeEligible?}, renderHints?, ruleFace? }`)。
+             *  与 `source` 同一条规矩:**解析透明**(`z.unknown()`),形的校验属 core 摄入侧(不合 schema 的工具**不挂**并
+             *  通告一次 `config.tool_face_invalid`);本仓不复述那张表 —— 这一域 all-or-nothing,任一字段解析拒都会
+             *  让整套 mcp 服务器静默消失。缺席 = 不铸键。 */
+            toolFaces: z.ZodOptional<z.ZodUnknown>;
             notes: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             name: string;
@@ -10160,6 +10260,7 @@ export declare const DOMAIN_SCHEMAS: {
             allowTools?: string[] | undefined;
             contentOrigin?: "local" | "execution" | "external" | undefined;
             source?: unknown;
+            toolFaces?: unknown;
         }, {
             name: string;
             transport: {
@@ -10181,6 +10282,7 @@ export declare const DOMAIN_SCHEMAS: {
             elicitation?: boolean | undefined;
             contentOrigin?: "local" | "execution" | "external" | undefined;
             source?: unknown;
+            toolFaces?: unknown;
         }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         servers: {
@@ -10204,6 +10306,7 @@ export declare const DOMAIN_SCHEMAS: {
             allowTools?: string[] | undefined;
             contentOrigin?: "local" | "execution" | "external" | undefined;
             source?: unknown;
+            toolFaces?: unknown;
         }[];
     }, {
         servers?: {
@@ -10227,6 +10330,7 @@ export declare const DOMAIN_SCHEMAS: {
             elicitation?: boolean | undefined;
             contentOrigin?: "local" | "execution" | "external" | undefined;
             source?: unknown;
+            toolFaces?: unknown;
         }[] | undefined;
     }>, {
         servers: {
@@ -10250,6 +10354,7 @@ export declare const DOMAIN_SCHEMAS: {
             allowTools?: string[] | undefined;
             contentOrigin?: "local" | "execution" | "external" | undefined;
             source?: unknown;
+            toolFaces?: unknown;
         }[];
     }, {
         servers?: {
@@ -10273,6 +10378,7 @@ export declare const DOMAIN_SCHEMAS: {
             elicitation?: boolean | undefined;
             contentOrigin?: "local" | "execution" | "external" | undefined;
             source?: unknown;
+            toolFaces?: unknown;
         }[] | undefined;
     }>;
     readonly plugins: z.ZodEffects<z.ZodObject<{

package/dist/types.js

@@ -209,6 +209,40 @@ export function extraBodyUnsafe(v) {
     }
     return false;
 }
+/** THE vetting pipeline for every FREE-FORM JSON value that lands in the persisted config — `ModelEntry.extraBody`
+ *  and `ModelEntry.compat` share this ONE function (1.10.0; before that it was inline in `extraBody` and a second
+ *  free-form field would have copied it). The judgment is identical for every such field, so it lives in one place:
+ *
+ *   1. getter-free descriptor walk ({@link extraBodyUnsafe}) over the RAW value — never invokes a getter, and any
+ *      reflective throw (a hostile Proxy trap could throw a secret-bearing message) collapses into a FIXED message;
+ *   2. a SINGLE `JSON.stringify` — its clone is re-scanned, so a Proxy that fakes its descriptors still can't ship
+ *      a secret, and that same clone IS what we return to persist, so a non-idempotent `toJSON` cannot validate one
+ *      serialization and persist another (the pre-R10 superRefine+transform stringified TWICE).
+ *
+ *  `field` only NAMES the field in the message — it never changes the judgment. What this does NOT do is validate
+ *  SHAPE: a field's shape/vocabulary is the consumer's single point (1.7.2 / 1.9.0 rule), and this domain parses
+ *  all-or-nothing, so a shape rejection here would blank the whole catalog. */
+function vetFreeFormJson(v, field) {
+    let rawUnsafe;
+    try {
+        rawUnsafe = extraBodyUnsafe(v);
+    }
+    catch {
+        return { ok: false, message: `${field} could not be validated (reflective access threw)` }; // R11
+    }
+    if (rawUnsafe)
+        return { ok: false, message: `${field}: a key/value is a secret shape, non-JSON (Infinity/function/Map), an accessor, cyclic, or too deep` };
+    let clone;
+    try {
+        clone = JSON.parse(JSON.stringify(v)); // the ONLY serialization — its result is what we scan AND persist
+    }
+    catch {
+        return { ok: false, message: `${field} is not JSON-serializable` };
+    }
+    if (extraBodyUnsafe(clone))
+        return { ok: false, message: `${field}: its serialized form carries a secret` };
+    return { ok: true, value: clone };
+}
 /** A k8s resource quantity ("250m", "1", "0.5", "512Mi", "1Gi", "128M") — catches garbage at config-submit
  *  rather than surfacing as a reconcile ApplyError at the apiserver (consistent with ENV_NAME/DURATION guards). */
 export const K8S_QUANTITY = z.string().regex(/^\d+(\.\d+)?(m|[kKMGTPE]i?)?$/, 'must be a k8s quantity like "250m", "512Mi", "1Gi"');
@@ -313,10 +347,9 @@ export const ModelEntry = z.object({
     extraBody: z
         .unknown()
         .optional()
-        // ONE transform that validates AND canonicalizes with a SINGLE JSON.stringify — the scanned clone IS the
-        // persisted value, so a non-idempotent getter/Proxy can't validate one serialization and persist another
-        // (the prior superRefine+transform stringified TWICE — review R10). getter-free descriptor walk bounds size
-        // BEFORE the stringify; the clone is re-scanned so a Proxy that fakes its descriptors still can't ship a secret.
+        // The SHAPE gate (plain JSON object) is extraBody's OWN — it is spread into a request body, so a non-object
+        // is meaningless here; the SAFETY judgment is the shared vetFreeFormJson pipeline (see its doc: getter-free
+        // walk → single stringify → re-scanned clone IS the persisted value).
         .transform((v, ctx) => {
         if (v === undefined)
             return undefined;
@@ -325,33 +358,42 @@ export const ModelEntry = z.object({
             ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody must be a plain JSON object" });
             return z.NEVER;
         }
-        // wrap in try/catch: a hostile Proxy's getOwnPropertyDescriptor/ownKeys trap could THROW a secret-bearing
-        // message — never surface it; treat any reflective failure as invalid with a FIXED message. R11.
-        let rawUnsafe;
-        try {
-            rawUnsafe = extraBodyUnsafe(v);
-        }
-        catch {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody could not be validated (reflective access threw)" });
+        const vetted = vetFreeFormJson(v, "extraBody");
+        if (!vetted.ok) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
             return z.NEVER;
         }
-        if (rawUnsafe) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody: a key/value is a secret shape, non-JSON (Infinity/function/Map), an accessor, cyclic, or too deep" });
-            return z.NEVER;
-        }
-        let clone;
-        try {
-            clone = JSON.parse(JSON.stringify(v)); // the ONLY serialization — its result is what we scan AND persist
-        }
-        catch {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody is not JSON-serializable" });
-            return z.NEVER;
-        }
-        if (extraBodyUnsafe(clone)) {
-            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "extraBody: its serialized form carries a secret" });
+        return vetted.value;
+    }),
+    /** Per-model wire-compat declaration for the OpenAI-completions lane — mirrors the engine's
+     *  `OpenAICompletionsCompat` (five keys: `thinkingFormat` / `reasoningEffortLevels` / `maxTokensField` /
+     *  `requiresReasoningContentOnAssistantMessages` / `supportsReasoningEffort`). Real need: a vLLM/Qwen-class
+     *  gateway that thinks by DEFAULT can only be turned off with `chat_template_kwargs.enable_thinking=false`,
+     *  which `extraBody` cannot carry (the engine reserves those request keys) — and without this key a catalog
+     *  entry that declares it is stripped at parse, so the declaration never reaches the engine at all.
+     *
+     *  **Parse-transparent** (`z.unknown()`), same rule as `McpServerSpec.source` (1.7.2) and `.toolFaces` (1.9.0):
+     *  the SHAPE and the VOCABULARY (which `thinkingFormat` words exist) are the consuming side's single point —
+     *  this package deliberately does NOT restate that table. This domain parses all-or-nothing, so a shape/word
+     *  rejection HERE would blank the entire model catalog over one bad key (the 1.7.1 upgrade regression). ABSENT
+     *  = key not minted = today's behaviour, zero migration.
+     *
+     *  The ONE rejection that remains is the free-form SAFETY judgment shared with `extraBody`
+     *  ({@link vetFreeFormJson}): a secret-shaped key/value, an accessor, a cycle, non-JSON, or too deep to hash
+     *  later. That is not shape validation — it is the boundary every free-form value must clear to enter the
+     *  persisted config and `stableHash` (R18). */
+    compat: z
+        .unknown()
+        .optional()
+        .transform((v, ctx) => {
+        if (v === undefined)
+            return undefined;
+        const vetted = vetFreeFormJson(v, "compat");
+        if (!vetted.ok) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: vetted.message });
             return z.NEVER;
         }
-        return clone;
+        return vetted.value;
     }),
     /** 配额倍率(EXPERT-REDESIGN §4-1):该模型烧 token 双窗额度的倍率,默认 1。折算时点=weight-at-burn
      *  (记账时固化到 UsageEntry.quotaWeightAtUse/weightedTokens):改倍率只影响此后记账,不回算窗口内历史。 */
@@ -1912,6 +1954,12 @@ export const McpServerSpec = z.object({
      *  both legs stripped it (default-strip object); this is the declaration half of the consumer-side fix
      *  (ticket B-036 / S-143), the projection half lives in the consumer. */
     source: z.unknown().optional(),
+    /** 1.9.0 —— core 7.8.0(design/388 片 1 F7)`toolFaces` 覆盖层:按远端工具名 key 的 face 声明
+     *  (`{ family?, pathTarget?: {param, aliases?, access, skillScopeEligible?}, renderHints?, ruleFace? }`)。
+     *  与 `source` 同一条规矩:**解析透明**(`z.unknown()`),形的校验属 core 摄入侧(不合 schema 的工具**不挂**并
+     *  通告一次 `config.tool_face_invalid`);本仓不复述那张表 —— 这一域 all-or-nothing,任一字段解析拒都会
+     *  让整套 mcp 服务器静默消失。缺席 = 不铸键。 */
+    toolFaces: z.unknown().optional(),
     notes: z.string().optional(),
 });
 export const McpConfig = z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-registry, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",