@sema-agent/server 7.127.1 → 7.128.0

package/dist/task-mcp.js

@@ -1,16 +1,18 @@
 import { mcpInjectionDroppedNotice, resolveComplianceDenies } from "@sema-agent/core";
 import { isUsableWireName } from "./wire-name-bound.js";
-import { HttpError } from "./security.js";
+import { HttpError, createCodedHttpError } from "./security.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "./mcp-content-origin.js";
 import { readMcpSourceLabel } from "./mcp-source-label.js";
+import { declaresMcpAssertionHeader, describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, readMcpIdentityHeaders, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
+import { echoKeyName } from "./request-key-closure.js";
 import { readMcpToolFaces } from "./mcp-tool-faces.js";
 import { isToolAxisIrreversibility, isToolEffect } from "./tool-axis-words.js";
 export const MAX_REQUEST_MCP_SERVERS = 32;
 export const MAX_REQUEST_MCP_DROP_NAMES = MAX_REQUEST_MCP_SERVERS;
 export const MCP_SERVER_ENTRY_KEYS = ["allowTools", "contentOrigin", "elicitation", "name", "source", "toolAxes", "toolFaces", "transport"];
 export const STDIO_MCP_TRANSPORT_KEYS = ["args", "command", "env", "kind"];
-export const HTTP_MCP_TRANSPORT_KEYS = ["headers", "kind", "principalHeader", "url"];
+export const HTTP_MCP_TRANSPORT_KEYS = ["assertionHeader", "headers", "kind", "principalHeader", "url"];
 export const MCP_ENTRY_EMPTY_RECORD_KEYS = ["toolAxes", "toolFaces"];
 export const MCP_ENTRY_EMPTY_ARRAY_KEYS = ["allowTools"];
 export const MCP_TRANSPORT_EMPTY_RECORD_KEYS = ["env", "headers"];
@@ -60,7 +62,7 @@ function normalizeServer(e, noteBadOrigin) {
             kind: "http",
             url: tr.url,
             ...(isStringRecord(tr.headers) ? { headers: tr.headers } : {}),
-            ...(typeof tr.principalHeader === "string" ? { principalHeader: tr.principalHeader } : {}),
+            ...readMcpIdentityHeaders(tr),
         };
     }
     else {
@@ -151,6 +153,33 @@ export function assertRequestMcpContentOrigin(bodyMcp) {
             ` (omit the key entirely for the default: this server's tools classify as external content)`, { code: "request.field_invalid" });
     }
 }
+export function assertRequestMcpIdentityHeaders(bodyMcp) {
+    if (!Array.isArray(bodyMcp))
+        return;
+    for (const e of bodyMcp) {
+        const refusal = requestEntryIdentityRefusal(e);
+        if (refusal !== undefined)
+            throw createCodedHttpError(400, refusal.errorCode, refusal.message);
+    }
+}
+export function requestEntryIdentityIssue(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return undefined;
+    const t = entry.transport;
+    if (!t || typeof t !== "object" || Array.isArray(t))
+        return undefined;
+    return mcpIdentityHeadersIssue(t);
+}
+export function requestEntryIdentityRefusal(entry) {
+    const issue = requestEntryIdentityIssue(entry);
+    if (issue === undefined)
+        return undefined;
+    const name = echoKeyName("", declaredName(entry));
+    if (issue === "both_set")
+        return { errorCode: "request.body_shape", message: describeMcpIdentityHeadersConflict(name) };
+    const value = (entry.transport).assertionHeader;
+    return { errorCode: "request.field_invalid", message: describeMcpAssertionHeaderNotAString(name, value) };
+}
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);
 }
@@ -198,8 +227,17 @@ function classifyHonored(baseline, entries, config, logger) {
     const reservedNames = config.mcpServers?.reservedNames ?? [];
     const closed = deploymentClosedMcpNames(baseline, reservedNames);
     const blocked = v.ok.filter((s) => closed.has(s.name)).map((s) => s.name);
+    for (const s of v.ok)
+        if (declaresMcpAssertionHeader(s) && !closed.has(s.name))
+            noteMcpAssertionHeaderNotSent(logger, s.name);
+    const mounted = new Set(v.ok.filter((s) => !closed.has(s.name)).map((s) => s.name));
+    for (const e of entries.slice(0, MAX_REQUEST_MCP_SERVERS)) {
+        const issue = requestEntryIdentityIssue(e);
+        if (issue !== undefined && mounted.has(declaredName(e)))
+            noteMcpAssertionHeaderIgnored(logger, declaredName(e), issue);
+    }
     return {
-        mcp: mergeRequestMcp(baseline, v.ok, reservedNames),
+        mcp: mergeRequestMcp(baseline, v.ok.map(toCoreMcpServerSpec), reservedNames),
         drops: [...v.dropped, ...blocked.map((server) => ({ server, reason: "name_reserved_by_deployment" }))],
         droppedTotal: v.droppedTotal + blocked.length,
     };

package/dist/trace/project.d.ts

@@ -266,7 +266,9 @@ export declare function reasoningEndEventData(ev: Record<string, unknown>): Segm
  *  core 1.203: `structured` = the tool's CC-shaped `details` card (edit/create/bash/… — core
  *  allowlists the card `type` and size-caps the whole card, omit-whole on overflow, so a subagent's child-TaskResult
  *  can never appear here) — SAME UNTRUSTED RAW contract as `output` (a card carries `originalFile`/stdout bodies),
- *  so it gets the same deep redaction before it is persisted or echoed. `label`(core 展示名,同 tool_start 的
+ *  so it gets the same deep redaction before it is persisted or echoed — except a media card's `file.base64` (image / document
+ *  cards: the second encoding of the same bytes the `output` block carries), which, like the block's `data`, is an encoding of
+ *  bytes and not text ({@link projectToolStructured}; the durable face drops it in the ledger confluence). `label`(core 展示名,同 tool_start 的
  *  label 待遇 verbatim)白名单排查(2026-07-24)补齐进函数本体——此前外包给调用点各自手动拼接,7 处只有
  *  3 处记得拼,resume leg + ledger-sink 落盘两处漏了,持久化记录本身缺 label 一写盘就永久追不回来。 */
 export declare function toolEndEventData(ev: {

package/dist/trace/project.js

@@ -3,7 +3,7 @@ import { isAskClass, isAskOrigin, isModeReleaseReason, isPermissionMode, isPersi
 import { Value } from "typebox/value";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { redactSecrets, redactDeep } from "./redact.js";
-import { projectToolOutput } from "./tool-output-media.js";
+import { projectToolOutput, projectToolStructured } from "./tool-output-media.js";
 import { injectionTierOrAbsent } from "./injection-tier.js";
 import { semaProvenanceOrAbsent } from "./sema-provenance.js";
 import { resupplyFields, terminalFrameFacetFields } from "./task-notification-facets.js";
@@ -289,7 +289,7 @@ export function toolEndEventData(ev) {
         ...(ev.output !== undefined ? { output: projectToolOutput(ev.output) } : {}),
         ...(ev.truncated ? { truncated: true } : {}),
         ...(Number.isFinite(ev.totalChars) ? { totalChars: ev.totalChars } : {}),
-        ...(ev.structured !== undefined ? { structured: redactDeep(ev.structured) } : {}),
+        ...(ev.structured !== undefined ? { structured: projectToolStructured(ev.structured, redactDeep) } : {}),
         ...(typeof ev.errorCode === "string" && ev.errorCode.length <= 128 ? { errorCode: ev.errorCode } : {}),
         ...(typeof ev.delivered === "string" && MCP_DELIVERY_VERDICTS.includes(ev.delivered) ? { delivered: ev.delivered } : {}),
         ...(gate !== undefined ? { gate } : {}),

package/dist/trace/self-minted-wire.d.ts

@@ -509,6 +509,25 @@ export declare const SELF_MINTED_WIRE: {
                 readonly attr: "durableMediaDescriptor+totalChars";
                 readonly since: "7.127.0";
             };
+            /**
+             * 7.127.2:同一条律的第二个座位 —— `tool_end.structured` 的**媒体卡**(Read 的图像 / 文档 details 卡 `{ type: "image" | "document", file: { base64?, … } }`)的
+             * `file.base64` 是同一份字节的第二份编码:活面逐字过境(不跑文本脱敏,卡上其余成员照常深度脱敏)、同一个连接积压判据一并计、降级时一并去掉;
+             * 钉 test/tool-end-media-durable.test.ts、test/live-media-backlog.test.ts。7.127.0 / 7.127.1 上这个键还过文本脱敏,且积压判据不计它。
+             */
+            readonly "SSE tool_end#structured.file.base64(\u5A92\u4F53\u5361)": {
+                readonly attr: "verbatim-bytes;backlog>64MiB⇒key-dropped";
+                readonly since: "7.127.2";
+            };
+            /**
+             * 7.127.2:同一媒体卡在**持久面**(账本行与 `GET /v1/runs/:id/events` / `GET /v1/tasks/:id/turns` / trace SSE 回放)只剩卡形自己的「不带字节」形 ——
+             * `file` 上没有 `base64` 键,其余成员逐字;帧级 `truncated` / `totalChars` 不因剥卡而动(它们只说 `output`)(账本汇点同一次调用剥:
+             * `redactLedgerEventData` → `toolEndMediaAsDescriptors`;钉 test/tool-end-media-durable.test.ts、test/wire-structured-events.test.ts)。
+             * 7.127.0 / 7.127.1 写下的存量行在读面上同样不再带字节。
+             */
+            readonly "GET /v1/runs/:id/events#tool_end.structured.file.base64(\u5A92\u4F53\u5361)": {
+                readonly attr: "durableMediaCardKeyDropped";
+                readonly since: "7.127.2";
+            };
         };
     };
 };

package/dist/trace/self-minted-wire.js

@@ -171,6 +171,8 @@ export const SELF_MINTED_WIRE = {
             "engine_notice permission.rule_row_dropped#detail.rows[].rule": { attr: "redactListEntry", since: "7.120.0" },
             "SSE tool_end#output[].data(媒体块)": { attr: "verbatim-bytes;backlog>64MiB⇒descriptor+totalChars", since: "7.127.0" },
             "GET /v1/runs/:id/events#tool_end.output[](媒体块)": { attr: "durableMediaDescriptor+totalChars", since: "7.127.0" },
+            "SSE tool_end#structured.file.base64(媒体卡)": { attr: "verbatim-bytes;backlog>64MiB⇒key-dropped", since: "7.127.2" },
+            "GET /v1/runs/:id/events#tool_end.structured.file.base64(媒体卡)": { attr: "durableMediaCardKeyDropped", since: "7.127.2" },
         },
     },
 };

package/dist/trace/tool-output-media.d.ts

@@ -4,21 +4,34 @@
  */
 export declare function projectToolOutput(output: unknown): unknown;
 /**
- * `tool_end` 载荷的媒体降级(持久面恒用;活面只在连接积压时用):带 `data` 的媒体块换成描述符,有任何一块被换 ⇒ 帧级 `truncated: true`
- * 且帧级 `totalChars` 在场 —— core 不变量「Present iff truncated」:被界之前那个值的真实大小。帧上已有 `totalChars`(core 已截断:
- * 文本被切而媒体留着)⇒ **原样保留**(它说的是更早的原值,本仓手里的已是切过的值,重算只会低报);没有 ⇒ 按 {@link trueSizeOf}
- * 逐块求和(core 没截,`output` 就是原值 —— 文本块是本服务脱敏后的字节,即本服务交付的内容)。
- * 没有媒体块 ⇒ 原样返回同一引用(纯文本 / 串形 output 一个字节不变);已是描述符的块(无 `data`)原样 ⇒ 幂等。
+ * 媒体卡座位的**唯一一只遍历**(与 {@link projectToolOutput} 同律):媒体卡逐成员过 `redact`,`file` 里 `base64` 逐字、其余成员照脱;
+ * 其它一切整只过 `redact`。保键序(逐键映射),不改入参。
+ *
+ * 形判与遍历只此一只,**脱敏器由调用面给**(「什么算该脱」是各面自己的事,「字节座位不过它」是这里的事):
+ *  · `tool_end` 活面 / 持久面(`toolEndEventData` 经 `trace/project.ts`):凭据脱敏 `redactDeep`;
+ *  · 会话存档读面(`audit.ts` 的 `toolResult.details` 叶):模型文本段脱敏的深扫(`redactDeepWith(v, redactModelText)`)。
+ * `redact` 必须是整值→整值的纯函数(环 / 深度守卫在它里面,遍历不重做);非媒体卡原样交给它,所以非媒体卡的读数就是调用面自己的深扫。
+ */
+export declare function projectToolStructured(structured: unknown, redact: (value: unknown) => unknown): unknown;
+/**
+ * `tool_end` 载荷的媒体降级(持久面恒用;活面只在连接积压时用),**一次调用降两个座位**:
+ *  · `output`:带 `data` 的媒体块换成描述符,有任何一块被换 ⇒ 帧级 `truncated: true` 且帧级 `totalChars` 在场 —— core 不变量
+ *    「Present iff truncated」:被界之前那个值的真实大小。帧上已有 `totalChars`(core 已截断:文本被切而媒体留着)⇒ **原样保留**
+ *    (它说的是更早的原值,本仓手里的已是切过的值,重算只会低报);没有 ⇒ 按 {@link trueSizeOf} 逐块求和(core 没截,`output` 就是原值 ——
+ *    文本块是本服务脱敏后的字节,即本服务交付的内容)。已是描述符的块(无 `data`)原样 ⇒ 幂等。
+ *  · `structured`:媒体卡去掉 `file.base64`(core 卡形自己的「不带字节」形),其余成员逐字。帧级 `truncated` / `totalChars` 只说 `output`,
+ *    单独剥卡**不动**它们(`output` 已是 core 描述符而卡仍带 ≤48K 字节的帧,和卡超 48K 时 core 自己略去 `base64` 的帧,在这两个键上读数一致)。
+ * 两处都没有媒体字节 ⇒ 原样返回同一引用(纯文本 / 串形 output / 非媒体卡一个字节不变)。
  */
 export declare function toolEndMediaAsDescriptors(data: Record<string, unknown>): Record<string, unknown>;
 /** 活面一条连接允许压住的待发字节上界(含本帧媒体)。一帧媒体最大约为部署媒体预算的 4/3(缺省约 40 MiB),
  *  上界取它之上一点:空闲连接上一整帧最大的图照样整块过,第二帧起只在读者跟上之后才整块。 */
 export declare const LIVE_MEDIA_BACKLOG_BYTES: number;
-/** 一帧 `tool_end` 载荷里媒体块 `data` 的字节数(base64 串长;没有媒体 = 0)。 */
+/** 一帧 `tool_end` 载荷里媒体字节的串长(base64):`output` 媒体块的 `data` 与 `structured` 媒体卡的 `file.base64` 一起计(同一帧、同一条连接上的字节;没有媒体 = 0)。 */
 export declare function liveMediaBytesOf(frame: Record<string, unknown>): number;
 /**
- * 活面的积压判据(一只):`backlogBytes` = 这条连接 / 这个订阅者此刻还没送出去的字节。本帧媒体 + 积压 > 上界 ⇒ 媒体降描述符,
- * 否则原样(同一引用)。非 `tool_end` 载荷由调用方不送进来;没有媒体的 `tool_end` 恒原样。
+ * 活面的积压判据(一只):`backlogBytes` = 这条连接 / 这个订阅者此刻还没送出去的字节。本帧媒体(`output` 块 + `structured` 卡的字节一起计)+ 积压 > 上界
+ * ⇒ 媒体降持久形(块换描述符、卡去 `file.base64`,同一只 {@link toolEndMediaAsDescriptors}),否则原样(同一引用)。非 `tool_end` 载荷由调用方不送进来;没有媒体的 `tool_end` 恒原样。
  * 降级是 F 类兜底(观众少见一张图),每降一帧在**这里**记一次 `server.tool-end-media.live-backlog-degraded` —— 三处写口都经这一只函数,
  * 留痕因此只有一处;帧上它与引擎的媒体预算降级同形,计数是运维看出「多少观众丢了图」的唯一位。
  */

package/dist/trace/tool-output-media.js

@@ -12,6 +12,21 @@ export function projectToolOutput(output) {
         return redactDeep(output);
     return output.map((b) => (isMediaBlock(b) ? Object.fromEntries(Object.entries(b).map(([k, v]) => [k, k === "data" ? v : redactDeep(v)])) : redactDeep(b)));
 }
+function isMediaCard(s) {
+    if (s === null || typeof s !== "object" || Array.isArray(s))
+        return false;
+    const card = s;
+    if (card.type !== "image" && card.type !== "document")
+        return false;
+    const file = card.file;
+    return file !== null && typeof file === "object" && !Array.isArray(file) && typeof file.base64 === "string";
+}
+export function projectToolStructured(structured, redact) {
+    if (!isMediaCard(structured))
+        return redact(structured);
+    const file = Object.fromEntries(Object.entries(structured.file).map(([k, v]) => [k, k === "base64" ? v : redact(v)]));
+    return Object.fromEntries(Object.entries(structured).map(([k, v]) => [k, k === "file" ? file : redact(v)]));
+}
 function trueSizeOf(b) {
     if (isMediaBlock(b))
         return b.data.length;
@@ -23,28 +38,40 @@ function trueSizeOf(b) {
 }
 export function toolEndMediaAsDescriptors(data) {
     const output = data.output;
-    if (!Array.isArray(output) || !output.some(isMediaBlock))
+    const outputHasMedia = Array.isArray(output) && output.some(isMediaBlock);
+    const structured = data.structured;
+    if (!outputHasMedia && !isMediaCard(structured))
         return data;
-    const totalChars = typeof data.totalChars === "number" && Number.isFinite(data.totalChars) ? data.totalChars : output.reduce((n, b) => n + trueSizeOf(b), 0);
-    const stripped = output.map((b) => isMediaBlock(b)
-        ? {
-            type: b.type,
-            ...(typeof b.mimeType === "string" && b.mimeType.length <= MIME_ECHO_MAX ? { mimeType: b.mimeType } : {}),
-            bytes: Math.floor((b.data.length * 3) / 4),
-            truncated: true,
-        }
-        : b);
-    return { ...data, output: stripped, truncated: true, totalChars };
+    const next = { ...data };
+    if (outputHasMedia) {
+        const blocks = output;
+        const totalChars = typeof data.totalChars === "number" && Number.isFinite(data.totalChars) ? data.totalChars : blocks.reduce((n, b) => n + trueSizeOf(b), 0);
+        next.output = blocks.map((b) => isMediaBlock(b)
+            ? {
+                type: b.type,
+                ...(typeof b.mimeType === "string" && b.mimeType.length <= MIME_ECHO_MAX ? { mimeType: b.mimeType } : {}),
+                bytes: Math.floor((b.data.length * 3) / 4),
+                truncated: true,
+            }
+            : b);
+        next.truncated = true;
+        next.totalChars = totalChars;
+    }
+    if (isMediaCard(structured)) {
+        const { base64: _bytes, ...file } = structured.file;
+        next.structured = { ...structured, file };
+    }
+    return next;
 }
 export const LIVE_MEDIA_BACKLOG_BYTES = 64 * 1024 * 1024;
 export function liveMediaBytesOf(frame) {
+    const structured = frame.structured;
+    let n = isMediaCard(structured) ? structured.file.base64.length : 0;
     const output = frame.output;
-    if (!Array.isArray(output))
-        return 0;
-    let n = 0;
-    for (const b of output)
-        if (isMediaBlock(b))
-            n += b.data.length;
+    if (Array.isArray(output))
+        for (const b of output)
+            if (isMediaBlock(b))
+                n += b.data.length;
     return n;
 }
 export function liveToolEndForBacklog(frame, backlogBytes) {

package/dist/web-admin-client/facade.d.ts

@@ -50,7 +50,7 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
 export { mutateInPlace, applyEffective, type ApplyReport, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, type ModelPlaneDomain, type ModelPlaneOf, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, type RestartSlice, type RestartSliceCtx, type EngineRestartSignal, } from "./restart-signal.js";
-export { applyCenterSkills, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
+export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
 export { applyCenterReadFace, CENTER_READ_FACE_LIVE_KEYS, type CenterReadFaceApply, type CenterReadFaceReport, type ReadFaceBaseline } from "./read-face.js";
 export type { CenterSkillManifest, CenterMcpServer, CenterA2aPeer, CenterModel, CenterReadFace, EffectiveConfig, ExecutionRuling, SessionMirrorRuling, } from "./types.js";
 //# sourceMappingURL=facade.d.ts.map

package/dist/web-admin-client/facade.js

@@ -1,6 +1,6 @@
 export { fetchEffective, fetchPrincipalCaps, fetchPrincipalOrgMemory, WebAdminHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./http-client.js";
 export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, logEffectiveDiff, MODEL_PLANE_DOMAINS, withModelPlaneOf, fullyLandedForLkg, } from "./apply-effective.js";
 export { restartReasons, modelPlaneChanged, } from "./restart-signal.js";
-export { applyCenterSkills, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
+export { applySkillsManifest, resolveMcpServers, mcpForScenario, resolveA2aPeers, a2aForScenario } from "./skills-mcp.js";
 export { applyCenterReadFace, CENTER_READ_FACE_LIVE_KEYS } from "./read-face.js";
 //# sourceMappingURL=facade.js.map

package/dist/web-admin-client/http-client.d.ts

@@ -88,8 +88,8 @@ export declare class WebAdminHttpError extends Error {
  * sha256 matches the manifest hash (integrity + rewrite check). The content is immutable per hash, so the
  * caller caches by hash and never re-fetches an unchanged skill. Throws a {@link WebAdminHttpError}
  * (carrying `.status`) on an HTTP error — INCLUDING 404 — or a plain Error on hash mismatch. Callers that
- * want "unknown hash → undefined" parity with the local backend inspect `.status === 404` and swallow it;
- * the legacy `applyCenterSkills` path keeps treating every throw as "skip this skill, keep baseline".
+ * want "unknown hash → undefined" parity with the local backend inspect `.status === 404` and swallow it —
+ * `RemoteConfigProvider.fetchSkillContent` does exactly that, and it is the only caller on the skills read port.
  */
 export declare function fetchSkillContent(center: CenterEndpoint, contentHash: string, fetchImpl?: typeof fetch): Promise<string>;
 /** [ref]b / [ref]① — §9.4 by-digest 补拉二函(fetchSkillContent 同姿势:HTTP+Bearer+8s 超时+

package/dist/web-admin-client/skills-mcp.d.ts

@@ -2,30 +2,33 @@ import type { A2aServerSpec, McpServerSpec } from "@sema-agent/core";
 import type { CenterMcp, ScopedA2aPeer } from "../config-types.js";
 import type { Logger } from "../observability/logger.js";
 import type { LoadedSkill } from "../capabilities/skills.js";
-import type { CenterEndpoint } from "./center-request.js";
+import type { ConfigProvider } from "../config-provider.js";
 import type { CenterA2aPeer, CenterMcpServer, CenterSkillManifest } from "./types.js";
 /**
- * Merge center skills OVER the image baseline ([ref]-sibling B1; `web-admin docs/MCP-SKILLS.md`). Load order =
- * `loadSkills(SKILLS_DIR)` baseline → center skills lazily fetched by hash and overlaid BY NAME (center
- * wins on a clash → can override a built-in; guarded center-side by publisher RBAC + the publish gate).
- * `enabled:false` is skipped. Content is verified + cached by hash (same hash fetched once). A skill whose
- * content fetch/verify fails is skipped (the baseline version, if any, stays) — never blocks startup.
+ * 技能正文的来源 = **拉到这份清单的配置源自己**(S-1556):`fetchSkillContent(contentHash)` 按 hash 答正文 —— 远程 = 中心内容端点
+ * (传输自验 hash;未知 hash ⇒ `undefined`),本地 = config.d 里内联的正文(与清单同一种容错读);`skillBodyCacheDir` = 这只配置源
+ * 声明的正文盘缓存目录(远程且开着 LKG 才有;本地恒缺席 —— 正文本就在这块盘上)。本函数不知道、也不问是哪一种。
+ */
+export type SkillBodySource = Pick<ConfigProvider, "fetchSkillContent" | "skillBodyCacheDir">;
+/**
+ * The skills domain's ONE read port (S-1556; [ref]-sibling B1; `web-admin docs/MCP-SKILLS.md`). Load order =
+ * `loadSkills(SKILLS_DIR)` baseline → the config source's skills (web-admin center OR local `config.d` — same manifest
+ * shape, same code path) overlaid BY NAME (config wins on a clash → can override a built-in; guarded center-side by
+ * publisher RBAC + the publish gate). `enabled:false` is skipped and never fetched. Bodies come from `bodies` by content
+ * hash, deduped in memory (same hash read once). A skill whose body is absent at the source or fails to read (incl. the
+ * remote transport's hash check) is NOT installed — exactly one `web_admin_skill_failed` warn names it (`reason`:
+ * `body_absent` | `read_failed`), the baseline of that name (if any) stays, and boot is never blocked.
  * Restart-to-apply: this runs at boot, before `buildScenarios` bakes skills into scenarios.
  */
-export declare function applyCenterSkills(baseline: LoadedSkill[], manifest: {
+export declare function applySkillsManifest(baseline: LoadedSkill[], manifest: {
     skills: CenterSkillManifest[];
-}, 
-/** S-651:中心端点(基址 + 凭证来源;每次正文拉取取一次值)。 */
-center: CenterEndpoint, logger?: Logger, fetchImpl?: typeof fetch, 
-/** LKG 姊妹面(clay 拍 2026-07-18):skill 正文的 content-addressed 盘缓存目录。读序=内存→盘(验
- *  hash,坏文件忽略)→中心(成功后 best-effort 回写)。让 LKG-boot 在中心不可达时不再于正文拉取上
- *  挂数秒(live 实测黑洞 +5.3s/skill 批),顺带省正常 refresh 的重复拉取。undefined=无盘缓存(原行为)。 */
-diskCacheDir?: string): Promise<LoadedSkill[]>;
+}, bodies: SkillBodySource, logger?: Logger): Promise<LoadedSkill[]>;
 /**
  * Resolve center MCP servers (`/effective.mcp`) into core `McpServerSpec`s + the scenarios each applies to.
  * env-NAME refs → real values from THIS service's env (secret boundary unchanged); a server with any missing
- * ref is skipped (`resolveRefs` → null). `enabled:false` skipped. Restart-to-apply (filtered per scenario in
- * `resolveSpec` via `mcpForScenario`).
+ * ref is skipped (`resolveRefs` → null). `enabled:false` skipped. A server whose `toolFaces` / `toolAxes` declaration is
+ * malformed is skipped whole (both are trust-root declarations — see `mcp-tool-faces.ts` / `mcp-tool-axes.ts`). Restart-to-apply
+ * (filtered per scenario in `resolveSpec` via `mcpForScenario`).
  */
 export declare function resolveMcpServers(mcp: {
     servers: CenterMcpServer[];

package/dist/web-admin-client/skills-mcp.js

@@ -1,11 +1,13 @@
 import { readMcpSourceLabel } from "../mcp-source-label.js";
 import { readMcpToolFaces } from "../mcp-tool-faces.js";
+import { readMcpToolAxes } from "../mcp-tool-axes.js";
 import { skillContentHash } from "@sema-agent/settings-schema";
 import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "../mcp-content-origin.js";
-import { fetchSkillContent } from "./http-client.js";
+import { noteMcpAssertionHeaderNotSent } from "../mcp-assertion-header.js";
 import { SHA256_HEX_RE } from "../digest-form.js";
 import { describeBadWireName, isUsableWireName } from "../wire-name-bound.js";
-export async function applyCenterSkills(baseline, manifest, center, logger, fetchImpl = fetch, diskCacheDir) {
+export async function applySkillsManifest(baseline, manifest, bodies, logger) {
+    const diskCacheDir = bodies.skillBodyCacheDir;
     const { promises: fsp } = await import("node:fs");
     const { join: joinPath } = await import("node:path");
     const diskRead = async (hash) => {
@@ -18,7 +20,7 @@ export async function applyCenterSkills(baseline, manifest, center, logger, fetc
             const text = await fsp.readFile(joinPath(diskCacheDir, hex), "utf8");
             if (skillContentHash(text) === hash)
                 return text;
-            logger?.warn("web_admin_skill_cache_corrupt", { hash, note: "on-disk body fails its own hash — ignored, refetching from center" });
+            logger?.warn("web_admin_skill_cache_corrupt", { hash, note: "on-disk body fails its own hash — ignored, re-reading from the config source" });
         }
         catch {
         }
@@ -43,14 +45,19 @@ export async function applyCenterSkills(baseline, manifest, center, logger, fetc
         if (m.enabled === false)
             continue;
         if (seenNames.has(m.name))
-            logger?.warn("web_admin_skill_duplicate_name", { name: m.name, note: "duplicate name in center manifest — last entry wins" });
+            logger?.warn("web_admin_skill_duplicate_name", { name: m.name, note: "duplicate name in the skills manifest — last entry wins" });
         seenNames.add(m.name);
         try {
             let content = contentCache.get(m.contentHash);
             if (content === undefined)
                 content = await diskRead(m.contentHash);
             if (content === undefined) {
-                content = await fetchSkillContent(center, m.contentHash, fetchImpl);
+                const answered = await bodies.fetchSkillContent(m.contentHash);
+                if (answered === undefined) {
+                    logger?.warn("web_admin_skill_failed", { name: m.name, hash: m.contentHash, reason: "body_absent", note: "the config source holds no body for this hash — this entry is NOT installed; the baseline skill of this name (if any) stays" });
+                    continue;
+                }
+                content = answered;
                 diskWrite(m.contentHash, content);
             }
             contentCache.set(m.contentHash, content);
@@ -59,7 +66,7 @@ export async function applyCenterSkills(baseline, manifest, center, logger, fetc
             logger?.info("web_admin_skill", { name: m.name, hash: m.contentHash, scenarios: m.scenarios, overrodeBuiltin });
         }
         catch (err) {
-            logger?.warn("web_admin_skill_failed", { name: m.name, hash: m.contentHash, err: String(err), note: "keeping baseline if any; skipping center version" });
+            logger?.warn("web_admin_skill_failed", { name: m.name, hash: m.contentHash, reason: "read_failed", err: String(err), note: "reading the body from the config source failed — this entry is NOT installed; the baseline skill of this name (if any) stays" });
         }
     }
     await Promise.all(pendingWrites);
@@ -117,22 +124,34 @@ export function resolveMcpServers(mcp, logger) {
             continue;
         }
         const toolFaces = facesRead.faces === undefined ? {} : { toolFaces: facesRead.faces };
+        const axesRead = readMcpToolAxes(s.toolAxes);
+        if (!axesRead.ok) {
+            logger?.warn("web_admin_mcp_tool_axes_invalid", {
+                server: s.name,
+                problem: axesRead.problem,
+                note: "server SKIPPED — a toolAxes declaration is a TRUST-ROOT declaration (it can lower an effect so a call skips the approval fence, or raise one); mounting the server without it, or with a half of it, would silently change what you declared. Fix the entry and republish.",
+            });
+            continue;
+        }
+        const toolAxes = axesRead.toolAxes === undefined ? {} : { toolAxes: axesRead.toolAxes };
         if (s.transport.kind === "stdio") {
             const env = resolveRefs(s.transport.envRefs, s.name, "env", logger);
             if (env === null)
                 continue;
             out.push({
                 scenarios: s.scenarios ?? [],
-                spec: { name: s.name, transport: { kind: "stdio", command: s.transport.command, args: s.transport.args, ...(Object.keys(env).length ? { env } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces },
+                spec: { name: s.name, transport: { kind: "stdio", command: s.transport.command, args: s.transport.args, ...(Object.keys(env).length ? { env } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
             });
         }
         else {
             const headers = resolveRefs(s.transport.headerRefs, s.name, "header", logger);
             if (headers === null)
                 continue;
+            if (s.transport.assertionHeader !== undefined)
+                noteMcpAssertionHeaderNotSent(logger, s.name);
             out.push({
                 scenarios: s.scenarios ?? [],
-                spec: { name: s.name, transport: { kind: "http", url: s.transport.url, ...(Object.keys(headers).length ? { headers } : {}), ...(s.transport.principalHeader ? { principalHeader: s.transport.principalHeader } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces },
+                spec: { name: s.name, transport: { kind: "http", url: s.transport.url, ...(Object.keys(headers).length ? { headers } : {}), ...(s.transport.principalHeader ? { principalHeader: s.transport.principalHeader } : {}) }, ...allow, ...elicit, ...contentOrigin, ...source, ...toolFaces, ...toolAxes },
             });
         }
     }

package/dist/web-admin-client/types.d.ts

@@ -151,6 +151,18 @@ export interface CenterMcpServer {
      * 形上先写一个结构,等于把同一张判据表抄成两份(而其中一份没有执行力)。
      */
     toolFaces?: unknown;
+    /**
+     * S-1475(settings-schema 12.2.x `McpServerSpec.toolAxes`,解析透明 `z.unknown()`)—— 部署侧为这台 server 的**每只工具**声明的
+     * 风险轴(`effect` / `egress` / `irreversibility`),键 = server 的**原始(未加命名空间)**工具名,上 core
+     * `McpServerSpec.toolAxes`。
+     *
+     * 🔴 类型是 `unknown` 而不是那个结构,**刻意的**(与 {@link CenterMcpServer.toolFaces} 逐字同姿):本类型是两条部署腿的**承载形**
+     * (本地 config.d 经 `z.unknown()` 解析透明地过来、远端 /effective 是直读 JSON),形判与投影的单一属主是 `mcp-tool-axes.ts` 的
+     * `readMcpToolAxes`(`resolveMcpServers` 在铸 spec 那一刻调它;产出的型是引擎的 `McpServerSpec["toolAxes"]`)。坏形 ⇒ 整条
+     * server 不进 + 一行 `web_admin_mcp_tool_axes_invalid`。
+     * (同批解析透明键 `authForm` / `entryKind` 的语义归连接器,本层仍只承载。)
+     */
+    toolAxes?: unknown;
     transport: {
         kind: "stdio";
         command: string;
@@ -160,11 +172,17 @@ export interface CenterMcpServer {
     /** `principalHeader` ([ref]): the header name into which the runner injects the task's authenticated
      *  end-user principal per-task, so a consumer MCP (e.g. oa-mcp) can enforce per-user RBAC. Not a ref — a
      *  literal header name. The runner fills the value (never the model). */
+    /** `assertionHeader` (settings-schema ≥12.2.0): the header NAME a hosted connector's assertion travels in. Mutually exclusive with
+     *  `principalHeader` (both answer "which header carries the identity this server sends"; the contract package refuses both-set at parse
+     *  time — the request face enforces the same rule at acceptance, see `mcp-assertion-header.ts`). A literal header name, not a ref.
+     *  This version CARRIES it up to the minting of the engine spec and does not send it (the engine's http transport has no seat yet):
+     *  `resolveMcpServers` leaves it off the spec and says one info line per mounted server. */
      | {
         kind: "http";
         url: string;
         headerRefs?: Record<string, string>;
         principalHeader?: string;
+        assertionHeader?: string;
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.127.1",
+  "version": "7.128.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",