@sema-agent/server 7.135.0 → 7.137.0

package/dist/task-a2a.js

@@ -1,68 +1,213 @@
-import { resolveComplianceDenies } from "@sema-agent/core";
-import { isUsableWireName } from "@sema-agent/settings-schema";
-import { HttpError, createCodedHttpError } from "./security.js";
+import { types } from "node:util";
+import { describeNotStringArray, describeValueShape, findUrlCredential, isStringArray } from "@sema-agent/settings-schema";
+import { errorKindOf } from "./observability/err-text.js";
 import { readPlainStringRecord } from "./plain-string-record.js";
 import { readRequestToolAxes } from "./request-tool-axes.js";
-import { echoKeyName } from "./request-key-closure.js";
-import { limitRefusal } from "./limit-refusal.js";
-import { buildRequestUrlCredentialRefusal, findUrlCredential, urlCredentialHeaderExit } from "./url-credential.js";
-import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
+import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyNames } from "./request-key-closure.js";
+import { urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential-refusal.js";
+import { declarationEntryNotObject, declarationIssueFacts, declarationNameIssue, declarationOverCapFacts, declaredName, judgeDeclarationKeys, requestDeclarationRefusal, throwDeclarationRefusal, } from "./request-declaration-refusal.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 export const MAX_REQUEST_A2A_PEERS = 32;
 export function a2aInjectionHonored(config) {
-    if (config.lockedConfigKeys?.includes("a2a") === true)
-        return false;
-    if (config.compliancePosture !== undefined) {
-        const denies = resolveComplianceDenies(config.compliancePosture);
-        if (denies.has("a2a_peers"))
-            return false;
-    }
     return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
 const HTTP_URL_RE = /^https?:\/\//i;
-function normalizeA2aPeer(e, leg, storedToolAxes) {
-    const dropped = { spec: null };
-    if (!e || typeof e !== "object")
-        return dropped;
-    const o = e;
-    if (!isUsableWireName(o.name))
-        return dropped;
-    if (typeof o.url !== "string" || !HTTP_URL_RE.test(o.url))
-        return dropped;
-    if (o.cardUrl !== undefined && (typeof o.cardUrl !== "string" || !HTTP_URL_RE.test(o.cardUrl)))
-        return dropped;
-    const headers = o.headers === undefined ? undefined : readPlainStringRecord(o.headers);
-    if (headers !== undefined && (!headers.ok || (headers.stripped.length > 0 && leg === "fresh")))
-        return dropped;
-    const lost = headers?.ok === true && headers.stripped.length > 0 ? { headersLost: headers.stripped.map((m) => echoKeyName("headers.", m.name)) } : {};
-    if (o.principalHeader !== undefined && typeof o.principalHeader !== "string")
-        return dropped;
-    if (o.allowSkills !== undefined && !(Array.isArray(o.allowSkills) && o.allowSkills.every((s) => typeof s === "string")))
-        return dropped;
+export const A2A_PEER_ENTRY_KEYS = ["name", "url", "cardUrl", "headers", "principalHeader", "allowSkills", "toolAxes"];
+const A2A_PEER_ENTRY_KEY_SET = new Set(A2A_PEER_ENTRY_KEYS);
+const NO_TOLERATED_KEYS = new Set();
+const A2A_SEAT = {
+    list: "a2aPeers",
+    cap: MAX_REQUEST_A2A_PEERS,
+    subject: "peer",
+    declaration: "an A2A peer declaration",
+    declarations: "A2A peer declarations",
+};
+function peerUrlIssue(key) {
+    return (entry, at) => {
+        const value = entry[key];
+        if (key === "cardUrl" && value === undefined)
+            return undefined;
+        if (typeof value !== "string" || !HTTP_URL_RE.test(value)) {
+            return { path: key, reason: `must be a string starting with "http://" or "https://" (never file://, never a bare host) — got ${describeValueShape(value)}` };
+        }
+        const found = findUrlCredential(value);
+        return found === undefined ? undefined : { path: key, reason: urlCredentialRefusalReason(found, urlCredentialHeaderExit(`${at}.headers`)), credential: found };
+    };
+}
+const HEADERS_RESERVED_MEMBER_PATH = "headers.__proto__";
+const PEER_SNAPSHOT = Symbol("a2aPeerSnapshot");
+function openCloneNode(v, ancestors) {
+    if (v === null || v === undefined || typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+        return { done: { ok: true, value: v } };
+    if (typeof v !== "object")
+        return { done: { ok: false, because: `a ${typeof v} value` } };
+    if (types.isProxy(v))
+        return { done: { ok: false, because: "not inspectable" } };
+    if (ancestors.has(v))
+        return { done: { ok: false, because: "cyclic" } };
+    const list = Array.isArray(v);
+    const proto = Object.getPrototypeOf(v);
+    if (list ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+        return { done: { ok: false, because: "not plain data" } };
+    return { frame: { source: v, keys: Object.getOwnPropertyNames(v), target: list ? [] : {}, next: 0 } };
+}
+function putCloneMember(target, key, value, enumerable) {
+    if (enumerable && key !== "__proto__")
+        target[key] = value;
+    else
+        Object.defineProperty(target, key, { value, enumerable, writable: true, configurable: true });
+}
+function cloneDeclaration(value) {
+    try {
+        const ancestors = new Set();
+        const root = openCloneNode(value, ancestors);
+        if ("done" in root)
+            return root.done;
+        ancestors.add(root.frame.source);
+        const stack = [root.frame];
+        for (let frame = stack[stack.length - 1]; frame !== undefined; frame = stack[stack.length - 1]) {
+            const key = frame.keys[frame.next];
+            if (key === undefined) {
+                if (Array.isArray(frame.source) && Array.isArray(frame.target))
+                    frame.target.length = frame.source.length;
+                ancestors.delete(frame.source);
+                stack.pop();
+                continue;
+            }
+            frame.next += 1;
+            if (key === "length" && Array.isArray(frame.target))
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(frame.source, key);
+            if (descriptor === undefined)
+                return { ok: false, because: "not inspectable" };
+            if (!("value" in descriptor))
+                return { ok: false, because: "an accessor member" };
+            const child = openCloneNode(descriptor.value, ancestors);
+            if ("done" in child) {
+                if (!child.done.ok)
+                    return child.done;
+                putCloneMember(frame.target, key, child.done.value, descriptor.enumerable === true);
+                continue;
+            }
+            putCloneMember(frame.target, key, child.frame.target, descriptor.enumerable === true);
+            ancestors.add(child.frame.source);
+            stack.push(child.frame);
+        }
+        return { ok: true, value: root.frame.target };
+    }
+    catch (error) {
+        return { ok: false, because: `not inspectable: ${errorKindOf(error)}` };
+    }
+}
+function isPeerSnapshot(value) {
+    return Object.hasOwn(value, PEER_SNAPSHOT);
+}
+function mintPeerSnapshot(entry, reread) {
+    const source = entry;
+    const allowSkills = source.allowSkills;
+    const headers = source.headers;
+    const toolAxes = source.toolAxes;
+    const toolAxesRead = toolAxes === undefined ? undefined : readRequestToolAxes(toolAxes, "a2a");
+    return Object.freeze({
+        [PEER_SNAPSHOT]: true,
+        name: source.name,
+        url: source.url,
+        cardUrl: source.cardUrl,
+        principalHeader: source.principalHeader,
+        allowSkills: Array.isArray(allowSkills) ? Array.from(allowSkills) : allowSkills,
+        headers: headers === undefined ? undefined : readPlainStringRecord(headers),
+        toolAxes: toolAxesRead,
+        toolAxesDeclared: reread && toolAxesRead !== undefined && !toolAxesRead.ok ? cloneDeclaration(toolAxes) : undefined,
+        unknownKeys: Object.keys(source).filter((name) => !A2A_PEER_ENTRY_KEY_SET.has(name)),
+    });
+}
+function snapshotPeer(entry, reread) {
+    return isPeerSnapshot(entry) ? entry : mintPeerSnapshot(entry, reread);
+}
+export function snapshotRequestA2a(raw, options) {
+    if (!Array.isArray(raw))
+        return raw;
+    const kept = raw.slice(0, MAX_REQUEST_A2A_PEERS).map((e) => (e !== null && typeof e === "object" && !Array.isArray(e) ? snapshotPeer(e, options.reread) : e));
+    if (raw.length > MAX_REQUEST_A2A_PEERS)
+        kept.length = raw.length;
+    return kept;
+}
+function toolAxesIssue(read) {
+    return { path: "toolAxes", reason: read.problem };
+}
+function toolAxesNotCloneableIssue(read, clone) {
+    const because = clone === undefined || clone.ok ? "unavailable" : clone.because;
+    return { path: "toolAxes", reason: `declaration not cloneable (${because}) — the one-time migration re-reads the stored declaration as plain JSON data and this one is not; ${read.problem}` };
+}
+const A2A_PEER_KEY_JUDGES = {
+    name: declarationNameIssue,
+    url: peerUrlIssue("url"),
+    cardUrl: peerUrlIssue("cardUrl"),
+    headers: (o) => {
+        const read = o.headers;
+        if (read === undefined)
+            return undefined;
+        if (!read.ok)
+            return { path: "headers", reason: `must be a plain object of string values — ${read.member === undefined ? read.fault : `its member "${echoKeyName("", read.member)}" ${read.fault}`}` };
+        const reserved = read.stripped[0];
+        return reserved === undefined ? undefined : { path: HEADERS_RESERVED_MEMBER_PATH, reason: reserved.fault };
+    },
+    principalHeader: (o) => (o.principalHeader === undefined || typeof o.principalHeader === "string" ? undefined : { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }),
+    allowSkills: (o) => o.allowSkills === undefined || isStringArray(o.allowSkills)
+        ? undefined
+        : { path: "allowSkills", reason: `must be an array of strings (omit the key to leave the peer's skills unrestricted) — got ${describeNotStringArray(o.allowSkills)}` },
+    toolAxes: (o) => {
+        const read = o.toolAxes;
+        return read === undefined || read.ok ? undefined : toolAxesIssue(read);
+    },
+};
+function normalizeA2aPeer(e, leg, at, storedToolAxes) {
+    const dropBecause = (issue) => ({ spec: null, because: declarationIssueFacts(at, issue) });
+    const notObject = declarationEntryNotObject(A2A_SEAT, e, at);
+    if (notObject !== undefined)
+        return { spec: null, because: { field: at, reason: notObject } };
+    const o = snapshotPeer(e, storedToolAxes !== undefined);
+    for (const key of A2A_PEER_ENTRY_KEYS) {
+        const issue = A2A_PEER_KEY_JUDGES[key](o, at);
+        if (issue === undefined)
+            continue;
+        if (issue.credential !== undefined)
+            continue;
+        if (leg === "resume" && issue.path === HEADERS_RESERVED_MEMBER_PATH)
+            continue;
+        if (key === "toolAxes" && storedToolAxes !== undefined)
+            continue;
+        return dropBecause(issue);
+    }
     const spec = { name: o.name, url: o.url };
-    if (typeof o.cardUrl === "string")
+    if (o.cardUrl !== undefined)
         spec.cardUrl = o.cardUrl;
+    const { headers, toolAxes: axes } = o;
     if (headers?.ok === true)
         spec.headers = headers.record;
-    if (typeof o.principalHeader === "string")
+    const lost = headers?.ok === true && headers.stripped.length > 0 ? { headersLost: headers.stripped.map((m) => echoKeyName("headers.", m.name)) } : {};
+    if (o.principalHeader !== undefined)
         spec.principalHeader = o.principalHeader;
-    if (Array.isArray(o.allowSkills))
+    if (o.allowSkills !== undefined)
         spec.allowSkills = o.allowSkills;
-    if (o.toolAxes !== undefined) {
-        const axes = readRequestToolAxes(o.toolAxes, "a2a");
-        if (!axes.ok && storedToolAxes !== undefined) {
-            const before = storedToolAxes.a2a(o.toolAxes);
+    if (axes !== undefined) {
+        if (!axes.ok) {
+            const unread = dropBecause(toolAxesIssue(axes));
+            if (storedToolAxes === undefined)
+                return unread;
+            const declared = o.toolAxesDeclared;
+            if (declared === undefined || !declared.ok)
+                return dropBecause(toolAxesNotCloneableIssue(axes, declared));
+            const before = storedToolAxes.a2a(declared.value);
             if (before === null)
-                return dropped;
+                return unread;
             const again = readRequestToolAxes(before, "a2a");
             if (!again.ok)
-                return dropped;
+                return unread;
             if (again.toolAxes !== undefined)
                 spec.toolAxes = again.toolAxes;
             return { spec, toolAxesReread: axes.problem, ...lost };
         }
-        if (!axes.ok)
-            return dropped;
         if (axes.toolAxes !== undefined)
             spec.toolAxes = axes.toolAxes;
     }
@@ -81,59 +226,44 @@ function validateRequestA2aEntries(raw, leg, storedToolAxes) {
     const dropped = [];
     const toolAxesReread = [];
     const headersLost = [];
-    for (const e of raw.slice(0, MAX_REQUEST_A2A_PEERS)) {
-        const { spec: v, toolAxesReread: reread, headersLost: lost } = normalizeA2aPeer(e, leg, storedToolAxes);
-        if (v) {
-            ok.push(v);
-            if (reread !== undefined)
-                toolAxesReread.push({ peer: v.name, problem: reread });
-            if (lost !== undefined)
-                headersLost.push({ peer: v.name, lost });
+    for (const [i, e] of raw.slice(0, MAX_REQUEST_A2A_PEERS).entries()) {
+        const read = normalizeA2aPeer(e, leg, `${A2A_SEAT.list}[${i}]`, storedToolAxes);
+        if (read.spec !== null) {
+            ok.push(read.spec);
+            if (read.toolAxesReread !== undefined)
+                toolAxesReread.push({ peer: read.spec.name, problem: read.toolAxesReread });
+            if (read.headersLost !== undefined)
+                headersLost.push({ peer: read.spec.name, lost: read.headersLost });
         }
         else
-            dropped.push(e && typeof e === "object" && typeof e.name === "string" ? String(e.name).slice(0, 128) : "<malformed>");
+            dropped.push({ peer: declaredName(e).slice(0, 128), ...read.because });
+    }
+    if (raw.length > MAX_REQUEST_A2A_PEERS) {
+        dropped.push({ peer: `(+${raw.length - MAX_REQUEST_A2A_PEERS} over cap of ${MAX_REQUEST_A2A_PEERS})`, ...declarationOverCapFacts(A2A_SEAT, raw.length) });
     }
-    if (raw.length > MAX_REQUEST_A2A_PEERS)
-        dropped.push(`(+${raw.length - MAX_REQUEST_A2A_PEERS} over cap of ${MAX_REQUEST_A2A_PEERS})`);
     return { ok, dropped, toolAxesReread, headersLost };
 }
-const A2A_PEER_URL_KEYS = ["url", "cardUrl"];
-function requestA2aPeerUrlRefusal(list) {
-    if (!Array.isArray(list))
-        return undefined;
-    if (list.length > MAX_REQUEST_A2A_PEERS) {
-        return limitRefusal("a2aPeers", "entries", list.length, MAX_REQUEST_A2A_PEERS, {
-            tail: "The request is refused rather than mounting the first peers and dropping the rest: the whole list is stored with the task, and each peer's url / cardUrl is checked for credentials",
-        });
+function requestA2aPeerRefusal(entry, at) {
+    const snapshot = snapshotPeer(entry, false);
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyNames(snapshot.unknownKeys, `${at}.`, A2A_PEER_ENTRY_KEY_SET, NO_TOLERATED_KEYS, buckets);
+    if (buckets.unknown.length > 0) {
+        const unknownKeys = buckets.unknown.sort();
+        return {
+            errorCode: "request.body_shape",
+            message: `body: unrecognized key(s) on an A2A peer declaration — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
+                `${keyClosureClause(unknownKeys, "unknown (not an a2aPeers[] key — check the spelling)")}. ` +
+                `Accepted per entry: ${[...A2A_PEER_ENTRY_KEYS].sort().join(",")}`,
+            unknownKeys: unknownKeys.slice(0, MAX_KEY_ECHO),
+        };
     }
-    for (const [i, peer] of list.entries()) {
-        if (peer === null || typeof peer !== "object")
-            continue;
-        const entry = peer;
-        for (const key of A2A_PEER_URL_KEYS) {
-            const value = entry[key];
-            const found = typeof value === "string" ? findUrlCredential(value) : undefined;
-            if (found === undefined)
-                continue;
-            const at = `a2aPeers[${i}]`;
-            return buildRequestUrlCredentialRefusal(`${at}.${key}`, found, urlCredentialHeaderExit(`${at}.headers`), typeof entry.name === "string" && entry.name !== "" ? `peer "${echoKeyName("", entry.name)}"` : undefined);
-        }
-    }
-    return undefined;
+    return judgeDeclarationKeys(A2A_SEAT, snapshot, at, A2A_PEER_ENTRY_KEYS, A2A_PEER_KEY_JUDGES);
 }
-export function assertRequestA2aPeerUrls(bodyA2a) {
-    const refusal = requestA2aPeerUrlRefusal(bodyA2a);
-    if (refusal !== undefined)
-        throw createCodedHttpError(400, "request.field_invalid", refusal.message, refusal.facts);
+export function requestA2aDeclarationRefusal(list) {
+    return requestDeclarationRefusal(A2A_SEAT, list, requestA2aPeerRefusal);
 }
-export function assertRequestA2aUnlocked(bodyA2a, lockedKeys) {
-    if (!lockedKeys.has("a2a"))
-        return;
-    if (bodyA2a === undefined || bodyA2a === null)
-        return;
-    throw new HttpError(GOVERNANCE_HTTP_STATUS["config.locked_key"], "`a2aPeers` is administratively locked by this deployment (locked key \"a2a\") — task-supplied A2A peers are refused; locks are config-time and there is no request-time unlock", {
-        code: "config.locked_key",
-    });
+export function assertRequestA2aEntries(bodyA2a) {
+    throwDeclarationRefusal(requestA2aDeclarationRefusal(bodyA2a));
 }
 export function mergeRequestA2a(baseline, gated) {
     if (gated.length === 0)

package/dist/task-mcp.d.ts

@@ -24,7 +24,7 @@
  */
 import { type CompliancePosture, type EngineNotice, type LockedKey, type McpInjectionDropReason, type McpServerSpec } from "@sema-agent/core";
 import { type McpIdentityHeadersIssue, type RequestMcpServerSpec } from "./mcp-assertion-header.js";
-import { type UrlCredentialFacts } from "./url-credential.js";
+import { type DeclarationRefusal } from "./request-declaration-refusal.js";
 import type { StoredToolAxesRereadM19 } from "./stored-request-tool-axes-m19.js";
 /** Bound on caller-supplied servers (anti-DoS; a real local `.mcp.json` has a handful). */
 export declare const MAX_REQUEST_MCP_SERVERS = 32;
@@ -142,30 +142,22 @@ export declare function assertRequestMcpUnlocked(bodyMcp: unknown, lockedKeys: R
 /** 一条**原始**请求条目上两个身份头的问题类(没有问题 / 不是对象 / 不是 http 传输 ⇒ `undefined`)—— 提交腿的门、探测口、重放腿的披露三处共读,
  *  判据本体在 `mcp-assertion-header.ts`;这里只负责把「条目 → 传输对象」那一步读出来。 */
 export declare function requestEntryIdentityIssue(entry: unknown): McpIdentityHeadersIssue | undefined;
-/** 请求面 `mcpServers` 的一次拒:码 + 句 + 词表外的键名表(只在闭集那一形上在场)+ 机读位(只在「url 带凭据」那一形上在场)。两扇门(fresh 提交腿 / 探测口)同一份,状态恒 400。 */
-export interface RequestMcpRefusal {
-    readonly errorCode: "request.body_shape" | "request.field_invalid";
-    readonly message: string;
-    /** 词表外的键,全路径形(`mcpServers[0].transport.header`;已清洗 + 截长 + 排序 + 封顶)。 */
-    readonly unknownKeys?: readonly string[];
-    /** [ref]:`transport.url` 带凭据 ⇒ 拒体顶层的 `field`(`mcpServers[i].transport.url`)+ `reason`(判官的拒因词,闭集)—— 与 `request.field_invalid` 上既有的 `field` / `reason` 同名同读。 */
-    readonly facts?: UrlCredentialFacts;
-}
 /**
  * 请求面 `mcpServers`「这份声明能不能原样用」的**唯一回答者** —— fresh 提交腿({@link assertRequestMcpEntries})与探测口
  * (`capabilities/mcp-probe.ts` 的 `readMcpProbeBody`)都问它、都原样转述它的答案(码与句逐字相同)。`undefined` = 能原样用,或列表缺席 / `null`(没声明;各门自己定缺席的意思)。
  *
  * ## 律:一个回答者、一个拒形,先列表后条目、条目里先键名后键值,第一处坏形即答
- *  ① **列表**:在场却不是数组 / 超过 {@link MAX_REQUEST_MCP_SERVERS} 条 / 某一条不是对象 ⇒ `400 request.field_invalid`,点名 `mcpServers` 或 `mcpServers[i]`(句尾同一句,见 {@link LIST_REFUSAL_TAIL})。
+ *  ① **列表**:在场却不是数组 / 超过 {@link MAX_REQUEST_MCP_SERVERS} 条 / 某一条不是对象 ⇒ `400 request.field_invalid`,点名 `mcpServers` 或 `mcpServers[i]`(句尾同一句,见 `request-declaration-refusal.ts` 的 `LIST_REFUSAL_TAIL`);
+ *     超上限是撞帽拒的全仓同一形(`limit-refusal.ts`:头一句 `mcpServers has N entries — at most 32 are accepted`,体带 `field` · `reason:"over_cap"` · `count` · `cap`)。
  *     整份拒而不是挂前 32 条 / 摘掉读不出的那条 / 整只忽略:一份被悄悄截短、少了几条或整只没生效的声明,在发送方那里读起来是「生效了」。
  *  ② **键名**:条目层、或 `transport` 按 `kind` 那一形的键闭集之外的键 ⇒ `400 request.body_shape`,拒体带 `unknownKeys`(拼错的键被悄悄不读,同样读起来像生效了)。
  *  ③ **身份头的键组合**(`principalHeader` 与 `assertionHeader` 同设 / `assertionHeader` 非串)⇒ {@link requestEntryIdentityRefusal}(同设那一句对契约包解析期原句逐字)。
- *  ④ **受理键的值** ⇒ 逐键问判官表 {@link ENTRY_KEY_JUDGES},`400 request.field_invalid`,拒句点名 `mcpServers[i].<键路径>`、server 名与**该键判官的原因句**({@link entryFieldRefusal})。
+ *  ④ **受理键的值** ⇒ 逐键问判官表 {@link ENTRY_KEY_JUDGES},`400 request.field_invalid`,拒句点名 `mcpServers[i].<键路径>`、server 名与**该键判官的原因句**({@link declarationFieldRefusal})。
  *     判官**就是读器用的那一只**,不是第二份:`toolAxes` = {@link readRequestToolAxes}(引擎根导出的 `readToolAxes` + 请求腿不收 `boundaryFlow`);`toolFaces` = 引擎根导出的 `readToolFaces`;
  *     `startupTimeoutMs` = 引擎根导出的 `mcpStartupTimeoutMs`(坏值抛 `config.mcp_startup_timeout_invalid`,本门把那一句作原因句);`contentOrigin` = `isContentOriginWord`;`source` = `isMcpSourceLabel`;
  *     `name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = 契约包读器 {@link readRequestMcpTransport} 的纯数据记录读法;`elicitation` = {@link isElicitationFlag};
  *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestMcpTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`;读器在契约包,本仓只据 `lost[0]` 拒、据 `lost` 在重放腿逐处点名);
- *     读器交回的 http `url` 再问「带不带凭据」= `url-credential.ts` 的 `findUrlCredential`([ref];拒体另带机读 `field` + `reason`,见 {@link transportUrlCredentialIssue})。
+ *     读器交回的 http `url` 再问「带不带凭据」= 契约包根的 `findUrlCredential`([ref];拒体另带机读 `field` + `reason`,见 {@link transportUrlCredentialIssue})。
  * 于是判官受理的条目,读器({@link normalizeServer})交回的就是申报本身(只差判官自己的合法归一:空容器 / `skillScopeEligible:false` 折成缺席、`toolAxes` 取引擎的拷贝)——
  * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(引擎尚无座,
  * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `specWithholdsMcpAssertionHeader`(开关 `MCP_ASSERTION_HEADER_SENT` 假时「声明了」即「被扣下」),不是第二份判法(见 `readMcpProbeBody`)。
@@ -176,7 +168,7 @@ export interface RequestMcpRefusal {
  * 关于 `contentOrigin` 的信任语义(core 把它定性为**部署面**键):请求腿的条目只有在 {@link mcpInjectionHonored} 为真(单用户 = 请求者就是这台 worker 的超管)时才被读进 `TaskSpec.mcp`,
  * 多租户部署整只数组被忽略 ⇒ 租户**结构上**够不着这个键;名字撞车时 baseline 恒赢({@link mergeRequestMcp})⇒ 调用方也改写不了一台**已配置** server 的声明。
  */
-export declare function requestMcpDeclarationRefusal(list: unknown): RequestMcpRefusal | undefined;
+export declare function requestMcpDeclarationRefusal(list: unknown): DeclarationRefusal | undefined;
 /**
  * fresh 提交腿的 `mcpServers` 门:{@link requestMcpDeclarationRefusal} 有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` 原样)。
  *
@@ -198,7 +190,7 @@ export declare function assertRequestMcpEntries(bodyMcp: unknown): void;
  * A caller can ADD servers but can never SHADOW or REFILL a deployment-declared one: a center entry that was skipped
  * (disabled / missing env ref / malformed `toolFaces`) still occupies its name, otherwise "skipped" would silently
  * mean "free for the caller to remount without the operator's `allowTools` / `toolFaces`" (车CF codex r2 [high]).
- * Same posture as `mergeUserSkills`.
+ * Same posture as `buildRunSkills`.
  */
 export declare function deploymentClosedMcpNames(baseline: McpServerSpec[] | undefined, reservedNames: readonly string[]): ReadonlySet<string>;
 /**

package/dist/task-mcp.js

@@ -1,13 +1,14 @@
 import { mcpInjectionDroppedNotice, mcpStartupTimeoutMs, readToolFaces, resolveComplianceDenies } from "@sema-agent/core";
-import { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeBadWireName, describeNotStringArray, describeValueShape, isContentOriginWord, isStringArray, isUsableWireName, readRequestMcpTransport, stripControlAndBidi, } from "@sema-agent/settings-schema";
-import { HttpError, createCodedHttpError } from "./security.js";
+import { MCP_CONTENT_ORIGINS, describeBadContentOrigin, describeNotStringArray, describeValueShape, findUrlCredential, isContentOriginWord, isStringArray, isUsableWireName, readRequestMcpTransport, stripControlAndBidi, } from "@sema-agent/settings-schema";
+import { HttpError } from "./security.js";
 import { GOVERNANCE_HTTP_STATUS } from "./governance-http-status.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 import { MCP_SOURCE_LABEL_MAX, isMcpSourceLabel, readMcpSourceLabel } from "./mcp-source-label.js";
 import { describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, specWithholdsMcpAssertionHeader, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
 import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
 import { readRequestToolAxes } from "./request-tool-axes.js";
-import { findUrlCredential, urlCredentialFacts, urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential.js";
+import { urlCredentialHeaderExit, urlCredentialRefusalReason } from "./url-credential-refusal.js";
+import { MALFORMED_NAME, declarationFieldRefusal, declarationNameIssue, declaredName, judgeDeclarationKeys, requestDeclarationRefusal, throwDeclarationRefusal, } from "./request-declaration-refusal.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", "startupTimeoutMs", "toolAxes", "toolFaces", "transport"];
@@ -27,12 +28,6 @@ function isElicitationFlag(v) {
     return typeof v === "boolean";
 }
 const bad = (field) => ({ ok: false, field });
-const MALFORMED_NAME = "<malformed>";
-function declaredName(e) {
-    return e && typeof e === "object" && typeof e.name === "string" && e.name !== ""
-        ? String(e.name)
-        : MALFORMED_NAME;
-}
 function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     if (!e || typeof e !== "object")
         return bad("entry");
@@ -133,34 +128,21 @@ function requestEntryIdentityRefusal(entry, at) {
         return { errorCode: "request.body_shape", message: describeMcpIdentityHeadersConflict(echoKeyName("", declaredName(entry))) };
     const transport = entry.transport;
     const value = isRecord(transport) ? transport.assertionHeader : undefined;
-    return entryFieldRefusal(entry, at, { path: "transport.assertionHeader", reason: describeMcpAssertionHeaderNotAString(value) });
+    return declarationFieldRefusal(MCP_SEAT, entry, at, { path: "transport.assertionHeader", reason: describeMcpAssertionHeaderNotAString(value) });
 }
 export function requestMcpDeclarationRefusal(list) {
-    if (list === undefined || list === null)
-        return undefined;
-    if (!Array.isArray(list))
-        return listRefusal(`mcpServers is ${describeValueShape(list)}, not an array of MCP server declarations`);
-    if (list.length > MAX_REQUEST_MCP_SERVERS)
-        return listRefusal(`mcpServers carries ${list.length} declarations, above this deployment's ceiling of ${MAX_REQUEST_MCP_SERVERS}`);
-    for (let i = 0; i < list.length; i++) {
-        const refusal = requestEntryRefusal(list[i], `mcpServers[${i}]`);
-        if (refusal !== undefined)
-            return refusal;
-    }
-    return undefined;
+    return requestDeclarationRefusal(MCP_SEAT, list, requestEntryRefusal);
 }
 export function assertRequestMcpEntries(bodyMcp) {
-    const refusal = requestMcpDeclarationRefusal(bodyMcp);
-    if (refusal === undefined)
-        return;
-    const extra = { ...(refusal.unknownKeys === undefined ? {} : { unknownKeys: [...refusal.unknownKeys] }), ...(refusal.facts ?? {}) };
-    throw createCodedHttpError(400, refusal.errorCode, refusal.message, Object.keys(extra).length === 0 ? undefined : extra);
-}
-const LIST_REFUSAL_TAIL = "The request is refused rather than acting on part of the list: declarations that silently did not apply would read as in effect to whoever sent them. " +
-    "Fix the list (an empty list declares none).";
-function listRefusal(head) {
-    return { errorCode: "request.field_invalid", message: `${head}. ${LIST_REFUSAL_TAIL}` };
+    throwDeclarationRefusal(requestMcpDeclarationRefusal(bodyMcp));
 }
+const MCP_SEAT = {
+    list: "mcpServers",
+    cap: MAX_REQUEST_MCP_SERVERS,
+    subject: "server",
+    declaration: "an MCP server declaration",
+    declarations: "MCP server declarations",
+};
 const ENTRY_KEY_SET = new Set(MCP_SERVER_ENTRY_KEYS);
 const STDIO_TRANSPORT_KEY_SET = new Set(STDIO_MCP_TRANSPORT_KEYS);
 const HTTP_TRANSPORT_KEY_SET = new Set(HTTP_MCP_TRANSPORT_KEYS);
@@ -194,7 +176,7 @@ const ENTRY_KEY_JUDGES = {
                 ` (omit the key for the default: this server's tools classify as external content)`,
         },
     elicitation: (o) => (o.elicitation === undefined || isElicitationFlag(o.elicitation) ? undefined : { path: "elicitation", reason: `must be a boolean — got ${describeValueShape(o.elicitation)}` }),
-    name: (o) => (isUsableWireName(o.name) ? undefined : { path: "name", reason: `must be a non-empty string within the wire-name length bound — got ${describeBadWireName(o.name)}` }),
+    name: declarationNameIssue,
     source: (o) => o.source === undefined || isMcpSourceLabel(o.source)
         ? undefined
         : { path: "source", reason: `must be a non-empty string of at most ${MCP_SOURCE_LABEL_MAX} characters (a display label) — got ${describeValueShape(o.source)}` },
@@ -228,19 +210,7 @@ const ENTRY_KEY_JUDGES = {
         return read.transport.kind === "http" ? transportUrlCredentialIssue(read.transport.url) : undefined;
     },
 };
-const ENTRY_REFUSAL_TAIL = "The request is refused rather than mounting the server without it: a declaration that silently did not apply would leave the server running differently from what you declared. " +
-    "Fix the entry (an optional key may also be omitted).";
-function entryFieldRefusal(entry, at, issue) {
-    const server = echoKeyName("", declaredName(entry));
-    return {
-        errorCode: "request.field_invalid",
-        message: `${at}.${issue.path} (server "${server}") is not a usable declaration — ${stripControlAndBidi(issue.reason)}. ${ENTRY_REFUSAL_TAIL}`,
-        ...(issue.credential === undefined ? {} : { facts: urlCredentialFacts(`${at}.${issue.path}`, issue.credential) }),
-    };
-}
 function requestEntryRefusal(entry, at) {
-    if (!isRecord(entry))
-        return listRefusal(`${at} is ${describeValueShape(entry)}, not an MCP server declaration (an object)`);
     const unknownKeys = entryUnknownKeys(entry, at);
     if (unknownKeys.length > 0) {
         return {
@@ -254,12 +224,7 @@ function requestEntryRefusal(entry, at) {
     const identity = requestEntryIdentityRefusal(entry, at);
     if (identity !== undefined)
         return identity;
-    for (const key of MCP_SERVER_ENTRY_KEYS) {
-        const issue = ENTRY_KEY_JUDGES[key](entry);
-        if (issue !== undefined)
-            return entryFieldRefusal(entry, at, issue);
-    }
-    return undefined;
+    return judgeDeclarationKeys(MCP_SEAT, entry, at, MCP_SERVER_ENTRY_KEYS, ENTRY_KEY_JUDGES);
 }
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);

package/dist/task-settings.d.ts

@@ -73,7 +73,7 @@ export declare const PERMISSION_MODE_WORDS: string;
  * through verbatim (`dontAsk` included: folding the auto-deny mode to `default`, the asking mode, would turn a refusal
  * into a card). An UNKNOWN string coerces to `default` (fail-safe: the most-asking mode).
  * [ref]-②: fresh submits can no longer REACH the unknown-word arm — the HTTP gate 400s a non-member value
- * (admission.ts, sibling of promptProfile) and the wire type is a closed enum. This lenient fold stays for the one
+ * (admission.ts, sibling of toolMaterializeStrategy) and the wire type is a closed enum. This lenient fold stays for the one
  * population the gate deliberately does not cover: RESUME replay of a persisted pre-gate body (outputStyle/model
  * two-layer posture — bricking a resume over a value that was legal at submit time is worse than the quiet fold).
  */
@@ -477,7 +477,7 @@ export declare const REQUEST_SETTINGS_REFUSAL_PREFIX = "request settings cannot
 /**
  * Build the per-request permission ToolPolicy from the parsed settings: the two **rule lists** (`deny` / `ask`) through ONE compiler
  * ({@link createRuleListPolicy} → core `createPermissionRulePolicy`) — a `deny` rule hard-blocks, an `ask` rule forces an approval
- * gate, `deny` > `ask` on overlap. 两表的 **covering 语义同源**([ref]):底下是 core 的同一只 `namespacedRuleNameCovers`,本仓不持第二套 glob。
+ * gate, `deny` > `ask` on overlap. 两表的 **covering 语义同源**([ref]):底下是 core 的同一只 `ruleNameCovers`,本仓不持第二套 glob。
  * The `allow` bucket is not here: a policy says deny / ask only (core 7.42.0); the list rides into `TaskSpec.allowedTools` at
  * {@link applyTaskSettings}, the one write point.
  *