@sema-agent/settings-schema 14.3.0 → 14.4.0

package/CHANGELOG.md

@@ -8,7 +8,33 @@
 
 ## Unreleased
 
-(空)
+## 14.4.0 — 2026-10-21 — minor:技能条目加两只可选工具名单 `SkillSpec.allowedTools?` / `disallowedTools?`(与引擎本地清单同名同形、逐条按作者所写承运;manifest 自动随到;读腿与兄弟列表同一条逐元素抢救律)
+
+> 档位(按发版纪律):**minor** —— 加性:`SkillSpec` 多两个可选键 `allowedTools` / `disallowedTools`;既有清单(不带这两个键)的解析结果、`/effective` 的 `skills[]`、一致性语料的读数逐字节不变。
+
+- **技能条目可以自带两只工具名单:`SkillSpec.allowedTools?` / `SkillSpec.disallowedTools?`(`string[]`,元素非空串)**。与引擎本地 `.sema/skills` 清单里同名两键同名同形(元素形与键名;读法见下) ——
+  此前中心分发的技能没有这两个位,引擎本地目录里写好的 `allowed-tools` / `disallowed-tools` 搬到中心就只剩正文,名单在 zod 的默认剥键下无声消失。
+  现在两只名单是 `SkillSpec` 的成员,**逐条按作者所写承运**:不去重、不排序、不规范化拼写,也不在这里判每一条是不是合法的规则拼写
+  (一条工具名、一段命名空间、一条带括号的规则各是什么意思,由消费方的授权判官在它那一处读;本包判的只有「非空字符串」)。
+  **消费方读法一句话**:**缺席 ⇒ 键不出现(不会被填成 `[]`);在场 ⇒ 整只数组原样交给消费方的判官**。`[]` 与缺席是两种承运形,读成什么由判官定 ——
+  引擎本地目录把空名单读作「未声明」,所以别把 `allowedTools: []` 实现成「一个工具都不许」。同一段名单文本在本地目录与中心分发两处被接受的范围也可能不同:
+  本地目录的装载器对不是规则拼写的条目会拒掉那条技能(不会以缩短的名单装上),本包照原样承运这样的条目、交给判官。
+  坏形(不是数组 / 元素不是字符串 / 元素是空串 / `null`)⇒ 写腿拒,拒句坐标点名到字段(`skills[i].allowedTools`),错在元素上时点名到元素(`skills[i].allowedTools[j]`);
+  `/effective` 的 manifest(`SkillsManifestSchema`、`toSkillsManifest`)本来就由 `SkillSpec` 派生(去掉 `content`、加 `contentHash`),所以两只名单自动随到 `skills[]`,没有第二份键表。
+  **读腿(`buildEffective` / `readEffectiveWire` 的逐条容错)里,两只名单是普通的嵌套集合,与 `scenarios` / `rosters` / MCP `allowTools` 走同一条既有律,没有为它们另立的读法**:
+  坏元素逐元素丢,告警 `entry-dropped` 的坐标到元素(`skills[i].disallowedTools[j]`),技能带着剩下的好元素存活;整只名单一个好元素都没有 ⇒ 不凭空造出 `[]`,
+  这条技能整条丢并告警 `entry-dropped`(坐标 `skills[i]`);若域里因此没有任何技能幸存(含它是唯一一条)⇒ 既有的零幸存者律:不发 `entry-dropped`,只发 `domain-defaulted`(`skills` 退成空清单)。
+  **如实披露的限度**:这条律落在拒绝名单上,意思是读腿上一只带坏元素的 `disallowedTools` 会被截短、技能照装(比作者所写更松),告警是响的;坏元素只可能来自写腿本会拒掉的文档
+  (手改的存量文件、别的写者),消费方可以把坐标落在 `…allowedTools[j]` / `…disallowedTools[j]` 的 `entry-dropped` 当硬停信号处理。纯值列表的抢救律(整只原子 vs 逐元素)在下一个 major 统一收口。
+  三问 —— **谁需要**:把引擎本地技能目录里的 `allowed-tools` / `disallowed-tools` 搬到中心分发的人(管理面写、服务端经 `/effective` 分发、worker 读);
+  **谁受伤**:① 不升级的**读取方** —— 旧读者(≤14.3.0 的 manifest 读者)不认这两个键,zod 默认剥掉,manifest 路径上没有剥键告警,于是名单在旧读者那里静默丢未知位
+  (`disallowedTools` 丢了 = 比作者所写更松);② **升了包的服务端与 client-core 的云端腿也还拿不到名单** —— 两处都是从 manifest 条目按手写键(name / description / content)建技能,没有这两个键;两位过境随各自的后续版本到货,
+  到货前,走这两条路的 worker 上两位无效;③ 存量文档里**已经有同名键但不是数组形**的技能(手写 `config.d/skills.json` 照搬引擎 frontmatter 的逗号串形
+  `allowedTools: "Read, Grep"`):此前这个键是未知键,技能存活并发 `unknown-keys-dropped`;现在这个键有了形状,不是数组 ⇒ 这条技能读腿上整条丢(`entry-dropped`,域里没有任何技能幸存则 `domain-defaulted`),写腿拒;
+  **补偿**:管理面写入名单之前,先确认读这条链的每一跳都已升级并接入这两个键 —— 升级顺序就是旋钮,本包不另设开关;存量文档先把同名键改成数组形或去掉。
+  钉:`test/skill-tool-lists-14.4.0.test.ts`(域形与 manifest 往返含空数组与缺席两形 · 重复 / 乱序 / 不配对拼写原样 · 缺席不物化键 · 域读与 `parseDomainLoud` 同一份零告警 ·
+  `buildEffective` → `resolveEffectiveForWorker` → `readEffectiveWire` 端到端 · 七种坏形 × 域形 / manifest 两条判据的坐标 · 读腿两条逐元素 ⇒ 告警到元素 · 与 `scenarios` 同一条律 ·
+  整只名单全坏 ⇒ 整条丢、域里无幸存者(唯一一条或每条都坏)⇒ `domain-defaulted` · 三份导出 schema 转 JSON Schema 两只名单零非标关键字)。
 
 ## 14.3.0 — 2026-10-21 — minor:信任阶梯词表做纯常量 `MIN_TRUST_WORDS`(`MinTrust` 由它派生;`trustRank` / `isAtLeast` 闭包零 zod,整函数抄走的消费方只登记一只全局)
 

package/conformance/VERSION

@@ -1 +1 @@
-14.3.0
+14.4.0

package/dist/types.d.ts

@@ -1793,6 +1793,8 @@ export declare const SkillSpec: z.ZodObject<{
     rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
     content: z.ZodDefault<z.ZodString>;
     enabled: z.ZodDefault<z.ZodBoolean>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     notes: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SkillSpec = z.infer<typeof SkillSpec>;
@@ -1804,6 +1806,8 @@ export declare const SkillsConfig: z.ZodObject<{
         rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
         content: z.ZodDefault<z.ZodString>;
         enabled: z.ZodDefault<z.ZodBoolean>;
+        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -1828,6 +1832,8 @@ export declare const SkillsManifestSchema: z.ZodObject<{
         rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
         description: z.ZodDefault<z.ZodString>;
         scenarios: z.ZodPrefault<z.ZodArray<z.ZodString>>;
+        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         contentHash: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -2480,6 +2486,8 @@ export declare const DOMAIN_SCHEMAS: {
             rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
             content: z.ZodDefault<z.ZodString>;
             enabled: z.ZodDefault<z.ZodBoolean>;
+            allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
             notes: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>;

package/dist/types.js

@@ -2338,6 +2338,21 @@ export const SkillSpec = z.object({
     /** The markdown body injected into the model context on invoke (progressive disclosure). Stored in full here; shipped as a hash in /effective. */
     content: z.string().default(""),
     enabled: z.boolean().default(true),
+    /** Tool allow list the skill declares — carried entry by entry as the author wrote it (same name and element shape as the
+     *  engine's local `.sema/skills` manifest `SkillSpec.allowedTools`). ABSENT = the key is not there (no list is carried);
+     *  PRESENT = the whole array, `[]` included, goes to the consumer's judge — two carried shapes, and what each reads as is the
+     *  judge's call (the engine's local skills directory reads an empty list as "not declared"). This contract only CARRIES: no
+     *  de-duplication, no sorting, no spelling check, no roster intersection — what an entry means (a tool, a namespace, a rule,
+     *  a path) is read in ONE place, the consumer's grant judge; the element shape judged here is "a non-empty string" and nothing
+     *  more. A malformed shape (not an array / a non-string or empty entry) is refused with a path naming the field
+     *  (`skills[i].allowedTools`) and, when the fault is an element, the element (`skills[i].allowedTools[j]`). Read leg: the list is an ordinary nested collection and follows the one salvage law that
+     *  `scenarios` / `rosters` / `mcp.servers[].allowTools` follow (a bad element is dropped with an `entry-dropped` warning whose
+     *  path reaches the element; a list with no good element makes the skill unreadable and the skill is dropped; when no skill of the domain survives, the domain falls back to its default with `domain-defaulted`). Travels on
+     *  `/effective` with the rest of the manifest ({@link SkillsManifestSchema} derives from this schema). */
+    allowedTools: z.array(z.string().min(1)).optional(),
+    /** Tool deny list the skill declares — same carrying and reading rules as {@link SkillSpec.allowedTools} (absent = no list
+     *  carried, present = the whole array goes to the consumer's judge, `[]` included; never de-duplicated, sorted or judged here). */
+    disallowedTools: z.array(z.string().min(1)).optional(),
     notes: z.string().optional(),
 });
 export const SkillsConfig = z

package/llms-full.txt

@@ -1,6 +1,6 @@
 <!--
 llms-full.txt — 自包含全文 · 消费方(使用者)视角 · @sema-agent/settings-schema
-重写日期: 2026-10-21 | 包版本: 14.3.0
+重写日期: 2026-10-21 | 包版本: 14.4.0
 生成方式: 无生成脚本——按当前树 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版。
 证据约定: 每条"它怎么工作"的断言附 (文件: 符号) 坐标,刻意不用行号(行号逐版腐烂;符号名由
 typecheck 与 test/package-surface.test.ts、test/docs-hygiene.test.ts 等常驻门钉住)。无证据推断显式标【推断】。
@@ -105,6 +105,7 @@ registry:公网 npmjs,无需私有 registry 配置。
 --- 6.4.0:`ModelEntry.headers?`(`z.unknown().optional()` 解析透明,无默认;与 `compat` 同一只变换 —— 缺席不铸键,其余只过与 `compat`/`extraBody` 共用的 `vetFreeFormJson` 安全判据,拒句同形只换字段名;登记在 `PARSE_TRANSPARENT_KEYS`,`validatedBy: "consumer"`)——部署 ↔ 供应商的 per-model 附加请求头,例 `{"anthropic-beta":"context-1m-2025-08-07"}`(开 1M 上下文);头名闭集白名单 × 读它的线路 × 值形的判据**唯一属主是 sema-server**(坏声明 ⇒ 该条目整条不可用,不是丢头照常),本包刻意不做形校验(字符串 / 数组 / 大小写不规范的名 / 白名单外的名一律逐字过,由 server 判)。修前(≤6.3.0)每条读腿都剥它并报 `unknown-keys-dropped` ---
   · rosters:`RosterEntry[]`(`primaryModel`/`cheapModel` 标记角色;`ROSTER_PRIMARY_ROLES`/`ROSTER_CHEAP_ROLES`)。
   · skills:`SkillSpec[]`(content 全文;wire 转 manifest 见 §4.5)。
+--- 14.4.0:`SkillSpec.allowedTools?` / `disallowedTools?`(`string[]`,元素非空串;与引擎本地 `.sema/skills` 清单同名同形)—— 逐条按作者所写承运:不去重 / 不排序 / 不判拼写(本包只判「非空字符串」);缺席 = 键不出现,在场 = 整只数组交给消费方的判官(`[]` 与缺席是两种承运形,读成什么由判官定;引擎本地目录把空名单读作未声明);manifest 由 `SkillSpec` 派生,两键自动随到 `/effective` 的 `skills[]`;读腿的逐条容错对它们与 `scenarios` / `rosters` / MCP `allowTools` 同一条律:坏元素逐元素丢并告警 `entry-dropped`(坐标到元素 `skills[i].<名单>[j]`),整只名单全坏 ⇒ 整条技能丢(告警 `skills[i]`;域里没有任何技能幸存 ⇒ 不发 `entry-dropped`、只发既有的 `domain-defaulted`);所以读腿上带坏元素的 `disallowedTools` 会被截短、技能照装(告警是响的),限度与消费方的处置见 CHANGELOG 该条。
   · mcp:`McpServerSpec[]` —— `transport` 判别 stdio(command/args/envRefs)| http(url/headerRefs/
     principalHeader/assertionHeader;后两者互斥);`allowTools?`、`scenarios`/`rosters` 过滤、`elicitation`(默认 false,inbound elicitation
     的 per-server opt-in)、`contentOrigin?`(信任出处声明,闭词表 `MCP_CONTENT_ORIGINS =

package/llms.txt

@@ -1,6 +1,6 @@
 <!--
 llms.txt — 消费方(使用者)视角索引 · @sema-agent/settings-schema
-重写日期: 2026-10-21 | 包版本: 14.3.0
+重写日期: 2026-10-21 | 包版本: 14.4.0
 生成方式: 无生成脚本——按当前树的 src/*.ts 导出面 + package.json + README/CHANGELOG 手写事实版;
 每条断言附证据坐标(文件:符号),刻意不用行号(行号随每版腐烂,符号名由 typecheck/test 钉住)。
 刷新触发: package.json 版号变更(test/docs-hygiene.test.ts D 组钉「包版本:」与 package.json 相等、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "14.3.0",
+  "version": "14.4.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, 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",