@sema-agent/server 7.137.0 → 7.138.0

package/dist/task-a2a.d.ts

@@ -1,4 +1,5 @@
-import type { A2aServerSpec } from "@sema-agent/core";
+import { type A2aServerSpec, type CompliancePosture, type LockedKey } from "@sema-agent/core";
+import { type A2aDraft, type PeerDesk, type PeerLease } from "./peer-seat.js";
 import { type DeclarationRefusal } from "./request-declaration-refusal.js";
 import type { StoredToolAxesRereadM19 } from "./stored-request-tool-axes-m19.js";
 import { type PrincipalAxisInput } from "./deployment-shape.js";
@@ -21,18 +22,42 @@ export interface A2aInjectionDrop {
     readonly reason: string;
     readonly field: string;
 }
-/** The deployment-facing shape this module reads: the principal axis only (the single-user gate). */
-export type A2aGateConfig = PrincipalAxisInput;
+/** The deployment-facing shape this module reads: the principal axis, the operator locks and the compliance posture. */
+export type A2aGateConfig = PrincipalAxisInput & {
+    readonly lockedConfigKeys?: readonly LockedKey[];
+    readonly compliancePosture?: CompliancePosture;
+};
 /**
- * Does THIS deployment honor caller-supplied per-request A2A peers? One veto — multi-tenant (deployment-shape row `multiTenant`): a tenant cannot
- * point the shared worker at an agent. The capability bit and the request leg both read this predicate, so there is exactly one place where the answer can be wrong.
+ * Does THIS deployment honor caller-supplied per-request A2A peers? The same three vetoes as `task-mcp.ts mcpInjectionHonored`, each with its own
+ * engine word: multi-tenant (deployment-shape row `multiTenant`: a tenant cannot point the shared worker at an agent), the operator lock `a2a`, and a
+ * compliance posture that denies `a2a_peers` (the engine refuses a task that declares a peer under either at prepare — advertising the bit would be
+ * "says yes, every use refused"). The capability bit and the request leg both read this predicate, so there is exactly one place where the answer can be wrong.
+ * A posture that cannot be resolved throws here (validated twice before this site; loud beats a quiet boolean, same as the MCP gate).
  */
 export declare function a2aInjectionHonored(config: A2aGateConfig): boolean;
 /**
- * 请求体 `a2aPeers[i]` 的**键闭集**(判序 = 本数组序:名 → 对端地址 → 它的 agent card 地址 → 凭据头 → 身份头 → 技能收窄 → 轴覆写)。两向钉在 core 的 `A2aServerSpec` 上:
- * 型上多一个键而表没跟 ⇒ 编译红(新键会被词表外的键门 400 掉 —— wire 上的静默回归);表里写一个型上没有的词 ⇒ 也红。于是这张表是从 core 的型**派生**出来的数据,而不是谁记得去同步的清单。
+ * 请求面一条 `a2aPeers[]` 对端在 wire 上的形(= `TaskRequestBody.a2aPeers` 的元素型):引擎的 `A2aServerSpec` 去掉凭据引用位、加上 `headers`(件)。
+ * 交给引擎之前一律经 {@link toA2aDraft} 拆成草稿 —— 引擎的声明收据对带 `headers` 的声明整条拒,件由部署的对端座在每次发送时作答。
  */
-export declare const A2A_PEER_ENTRY_KEYS: readonly ["name", "url", "cardUrl", "headers", "principalHeader", "allowSkills", "toolAxes"];
+export type RequestA2aPeer = Omit<A2aServerSpec, "credentials"> & {
+    headers?: Record<string, string>;
+};
+/**
+ * 请求体 `a2aPeers[i]` 的**处置表** —— 同时是键闭集(判序 = 书写序:名 → 对端地址 → 它的 agent card 地址 → 凭据头 → 身份头 → 技能收窄 → 轴覆写)与每个键的去处:
+ * `headers` 是件(进草稿,交给引擎的声明里不带),其余进声明。三道编译格:对请求形两向(`satisfies`:请求形多一个键而表没写 / 表里写一个请求形上没有的词 ⇒ 红);
+ * 对引擎的 `A2aServerSpec` 两道(引擎长出 / 退役一个键,或退役凭据引用位 ⇒ 红)。于是这张表是从型**派生**出来的数据,而不是谁记得去同步的清单。
+ */
+export declare const A2A_PEER_DISPOSITION: {
+    readonly name: "engine";
+    readonly url: "engine";
+    readonly cardUrl: "engine";
+    readonly headers: "seat";
+    readonly principalHeader: "engine";
+    readonly allowSkills: "engine";
+    readonly toolAxes: "engine";
+};
+/** 请求体 `a2aPeers[i]` 的键闭集 = 处置表的键(书写序即判序)。 */
+export declare const A2A_PEER_ENTRY_KEYS: readonly ("name" | "toolAxes" | "url" | "principalHeader" | "cardUrl" | "allowSkills" | "headers")[];
 /**
  * **请求入口的一次读**(`boot/resolve-spec.ts` 在腿首铸一份,受理门与读器——续跑重放腿只有读器——都吃这一份):`body.a2aPeers` 若是数组,返回同形数组
  * (每个对象条目换成它的 {@link PeerSnapshot};非对象条目原样;长度保真 —— 界外的条数仍是受理门撞帽拒与读器丢弃留声的依据,只快照界内的条目);不是数组(缺席 / `null` / 别的形)原样返回。
@@ -45,12 +70,14 @@ export declare function snapshotRequestA2a(raw: unknown, options: {
 }): unknown;
 /** 读这条对端的是哪条腿:`fresh` = 新提交;`resume` = 续跑重放升级前存下的请求体(`boot/resolve-spec.ts` 的 `opts.leg` 分流,同一个读法)。 */
 type A2aRequestLeg = "fresh" | "resume";
+/** 请求面对端 → 草稿:按 {@link A2A_PEER_DISPOSITION} 拆(`headers` 进件,其余进声明;拆法与 MCP 请求腿同一只 `splitDeclaration`)。件缺席或空 ⇒ 草稿不带件。纯函数,不登记。 */
+export declare function toA2aDraft(peer: RequestA2aPeer): A2aDraft;
 /**
  * Shape-check the raw `body.a2aPeers`. `null` → a non-array (caller error; the route may 400). Otherwise the
- * valid subset + the dropped (malformed/over-cap) entries as {@link A2aInjectionDrop} facts (peer name · reason · body coordinate).
+ * valid subset as drafts (nothing registered) + the dropped (malformed/over-cap) entries as {@link A2aInjectionDrop} facts (peer name · reason · body coordinate).
  */
 export declare function validateRequestA2a(raw: unknown): {
-    ok: A2aServerSpec[];
+    ok: A2aDraft[];
     dropped: A2aInjectionDrop[];
 } | null;
 /**
@@ -69,13 +96,14 @@ export declare function requestA2aDeclarationRefusal(list: unknown): Declaration
 /** fresh 提交腿的 `a2aPeers` 门:{@link requestA2aDeclarationRefusal} 有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` / 机读位原样)。 */
 export declare function assertRequestA2aEntries(bodyA2a: unknown): void;
 /**
- * Merge GATED per-request peers OVER the deployment baseline (center/config). The baseline WINS on a name
+ * Merge GATED per-request peer drafts OVER the deployment baseline (center/config): **select first, then mint**. The baseline WINS on a name
  * clash — a caller can ADD a peer but can never SHADOW a configured one. This is load-bearing on THIS lane
  * specifically: the peer name is the tool-namespace segment (`a2a__<peer>__<skill>`), so shadowing would let
- * a caller keep the tool NAMES the model was told about while swapping the agent behind them.
+ * a caller keep the tool NAMES the model was told about while swapping the agent behind them. A draft that loses to the baseline never reaches
+ * the desk; each winner is minted once on `desk` under `lease` (`peer-seat.ts` `mintDeclaration`: the reference at the top level, zero header values).
  * Returns the baseline unchanged when there is nothing to add.
  */
-export declare function mergeRequestA2a(baseline: A2aServerSpec[] | undefined, gated: A2aServerSpec[]): A2aServerSpec[] | undefined;
+export declare function mergeRequestA2a(baseline: A2aServerSpec[] | undefined, drafts: readonly A2aDraft[], desk: Pick<PeerDesk, "declare">, lease: PeerLease): A2aServerSpec[] | undefined;
 /**
  * The single entry point the spec-builder calls: compute the effective `TaskSpec.a2a` = deployment baseline
  * (`a2aForScenario(config.a2aPeers, scenario)`) + the caller's gated per-request peers. Off the honored lane
@@ -83,7 +111,9 @@ export declare function mergeRequestA2a(baseline: A2aServerSpec[] | undefined, g
  * peers a closed gate dropped, so a shell never silently believes its declaration took effect (it also reads
  * `capabilities.a2aInjection`).
  */
-export declare function resolveRequestA2a(baseline: A2aServerSpec[] | undefined, bodyA2a: unknown, config: A2aGateConfig, logger?: {
+export declare function resolveRequestA2a(baseline: A2aServerSpec[] | undefined, bodyA2a: unknown, config: A2aGateConfig, 
+/** 对端座的 desk 与本腿的宿主租约(必填,与 MCP 请求腿同一对):胜出草稿在它下面铸成带引用的声明。 */
+desk: Pick<PeerDesk, "declare">, lease: PeerLease, logger?: {
     info?(m: string, meta?: unknown): void;
     warn(m: string, meta?: unknown): void;
 }, 

package/dist/task-a2a.js

@@ -1,18 +1,36 @@
 import { types } from "node:util";
+import { resolveComplianceDenies } from "@sema-agent/core";
 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 { declarationKeys, readPlainStringRecord, splitDeclaration } from "./plain-string-record.js";
+import { mintDeclaration, peerSentence } from "./peer-seat.js";
 import { readRequestToolAxes } from "./request-tool-axes.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 { principalHeaderOwnershipIssue } from "./task-mcp.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_LOCK_WORD) === true)
+        return false;
+    if (config.compliancePosture !== undefined && resolveComplianceDenies(config.compliancePosture).has(A2A_COMPLIANCE_WORD))
+        return false;
     return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config);
 }
+const A2A_LOCK_WORD = "a2a";
+const A2A_COMPLIANCE_WORD = "a2a_peers";
 const HTTP_URL_RE = /^https?:\/\//i;
-export const A2A_PEER_ENTRY_KEYS = ["name", "url", "cardUrl", "headers", "principalHeader", "allowSkills", "toolAxes"];
+export const A2A_PEER_DISPOSITION = {
+    name: "engine",
+    url: "engine",
+    cardUrl: "engine",
+    headers: "seat",
+    principalHeader: "engine",
+    allowSkills: "engine",
+    toolAxes: "engine",
+};
+export const A2A_PEER_ENTRY_KEYS = declarationKeys(A2A_PEER_DISPOSITION);
 const A2A_PEER_ENTRY_KEY_SET = new Set(A2A_PEER_ENTRY_KEYS);
 const NO_TOLERATED_KEYS = new Set();
 const A2A_SEAT = {
@@ -133,11 +151,11 @@ export function snapshotRequestA2a(raw, options) {
     return kept;
 }
 function toolAxesIssue(read) {
-    return { path: "toolAxes", reason: read.problem };
+    return { path: "toolAxes", reason: peerSentence(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}` };
+    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; ${peerSentence(read.problem)}` };
 }
 const A2A_PEER_KEY_JUDGES = {
     name: declarationNameIssue,
@@ -152,7 +170,11 @@ const A2A_PEER_KEY_JUDGES = {
         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)}` }),
+    principalHeader: (o) => o.principalHeader === undefined
+        ? undefined
+        : typeof o.principalHeader !== "string"
+            ? { path: "principalHeader", reason: `must be a string (a header name) — got ${describeValueShape(o.principalHeader)}` }
+            : principalHeaderOwnershipIssue(o.principalHeader, "a2a", "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)}` },
@@ -162,10 +184,10 @@ const A2A_PEER_KEY_JUDGES = {
     },
 };
 function normalizeA2aPeer(e, leg, at, storedToolAxes) {
-    const dropBecause = (issue) => ({ spec: null, because: declarationIssueFacts(at, issue) });
+    const dropBecause = (issue) => ({ draft: null, because: declarationIssueFacts(at, issue) });
     const notObject = declarationEntryNotObject(A2A_SEAT, e, at);
     if (notObject !== undefined)
-        return { spec: null, because: { field: at, reason: notObject } };
+        return { draft: 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);
@@ -206,12 +228,16 @@ function normalizeA2aPeer(e, leg, at, storedToolAxes) {
                 return unread;
             if (again.toolAxes !== undefined)
                 spec.toolAxes = again.toolAxes;
-            return { spec, toolAxesReread: axes.problem, ...lost };
+            return { draft: toA2aDraft(spec), toolAxesReread: peerSentence(axes.problem), ...lost };
         }
         if (axes.toolAxes !== undefined)
             spec.toolAxes = axes.toolAxes;
     }
-    return { spec, ...lost };
+    return { draft: toA2aDraft(spec), ...lost };
+}
+export function toA2aDraft(peer) {
+    const split = splitDeclaration(peer, A2A_PEER_DISPOSITION);
+    return { spec: split.engine, ...(split.pieces === undefined ? {} : { pieces: split.pieces }) };
 }
 export function validateRequestA2a(raw) {
     const v = validateRequestA2aEntries(raw, "fresh");
@@ -228,12 +254,12 @@ function validateRequestA2aEntries(raw, leg, storedToolAxes) {
     const headersLost = [];
     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.draft !== null) {
+            ok.push(read.draft);
             if (read.toolAxesReread !== undefined)
-                toolAxesReread.push({ peer: read.spec.name, problem: read.toolAxesReread });
+                toolAxesReread.push({ peer: read.draft.spec.name, sentence: read.toolAxesReread });
             if (read.headersLost !== undefined)
-                headersLost.push({ peer: read.spec.name, lost: read.headersLost });
+                headersLost.push({ peer: read.draft.spec.name, lost: read.headersLost });
         }
         else
             dropped.push({ peer: declaredName(e).slice(0, 128), ...read.because });
@@ -265,14 +291,14 @@ export function requestA2aDeclarationRefusal(list) {
 export function assertRequestA2aEntries(bodyA2a) {
     throwDeclarationRefusal(requestA2aDeclarationRefusal(bodyA2a));
 }
-export function mergeRequestA2a(baseline, gated) {
-    if (gated.length === 0)
+export function mergeRequestA2a(baseline, drafts, desk, lease) {
+    if (drafts.length === 0)
         return baseline;
     const taken = new Set((baseline ?? []).map((p) => p.name));
-    const add = gated.filter((p) => !taken.has(p.name));
-    return add.length === 0 ? baseline : [...(baseline ?? []), ...add];
+    const winners = drafts.filter((d) => !taken.has(d.spec.name));
+    return winners.length === 0 ? baseline : [...(baseline ?? []), ...winners.map((d) => mintDeclaration(desk, d, lease))];
 }
-export function resolveRequestA2a(baseline, bodyA2a, config, logger, leg = "fresh", storedToolAxes) {
+export function resolveRequestA2a(baseline, bodyA2a, config, desk, lease, logger, leg = "fresh", storedToolAxes) {
     if (bodyA2a === undefined || bodyA2a === null)
         return baseline;
     if (!a2aInjectionHonored(config)) {
@@ -286,7 +312,7 @@ export function resolveRequestA2a(baseline, bodyA2a, config, logger, leg = "fres
     }
     if (v.dropped.length > 0)
         logger?.warn("a2a_injection_dropped", { dropped: v.dropped });
-    const merged = mergeRequestA2a(baseline, v.ok);
+    const merged = mergeRequestA2a(baseline, v.ok, desk, lease);
     const baselineNames = new Set((baseline ?? []).map((p) => p.name));
     for (const r of v.toolAxesReread) {
         if (baselineNames.has(r.peer))
@@ -294,7 +320,7 @@ export function resolveRequestA2a(baseline, bodyA2a, config, logger, leg = "fres
         logger?.warn("a2a_tool_axes_read_as_before_upgrade", {
             peer: r.peer,
             migration: "M19",
-            problem: r.problem,
+            problem: r.sentence,
             note: "this replayed request was stored before the upgrade and the peer's toolAxes declaration does not pass the engine's reader; while one-time migration M19 is open it is read the way the pre-upgrade reader reads it (members that do not fit are dropped) and the peer stays mounted — once the window closes the same request leaves this peer unmounted",
         });
     }

package/dist/task-mcp.d.ts

@@ -24,7 +24,8 @@
  */
 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 DeclarationRefusal } from "./request-declaration-refusal.js";
+import { type McpDraft, type PeerDesk, type PeerLease } from "./peer-seat.js";
+import { type DeclarationKeyIssue, 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;
@@ -52,11 +53,11 @@ export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
  * 再写一份就是一份手抄投影([ref]:任何仓第一排查点),而两份哪天分岔,窄的那一份会把**合法**的键当成
  * 拼写错误 400 掉。
  *
- * ## 🔴 两向钉在 core 的 `McpServerSpec` 上(不是手抄)
- * 下面六道编译期门:型上多一个键而表没跟 ⇒ 红;表里写一个型上没有的词(改名 / 拼错 / 删键后的残条目)
- * ⇒ 也红。于是这三张表是从 core 的型**派生**出来的数据,而不是誰记得去同步的清单。
- * (唯一一格不在 core 型上的键 = http 传输的 `assertionHeader`:引擎尚无座,本仓承载 —— 那一支的门钉在
- * `mcp-assertion-header.ts` 的 {@link RequestMcpServerSpec} 上,引擎一旦长出同名座,那里的退役门当场红。)
+ * ## 🔴 两向钉在请求面条目形上(不是手抄)
+ * 条目层:下面四道编译期门两向钉在请求面条目形 {@link RequestMcpServerSpec}(条目层 = 引擎 `McpServerSpec` 的条目层)上:型上多一个键而表没跟 ⇒ 红;表里写一个型上没有的词
+ * (改名 / 拼错 / 删键后的残条目)⇒ 也红。传输层:两张键表**就是**两臂处置表的键(`mcp-assertion-header.ts` 的 {@link MCP_STDIO_TRANSPORT_DISPOSITION} /
+ * {@link MCP_HTTP_TRANSPORT_DISPOSITION}),处置表对契约包的请求传输形两向钉、对引擎的传输形再钉两道 —— 一张表同时说「收哪些键」与「每个键去哪」。
+ * 于是这几张表是从型**派生**出来的数据,而不是谁记得去同步的清单。
  *
  * ## 一个回答者,两扇门;读器另算
  * 「这份声明能不能原样用」只有 {@link requestMcpDeclarationRefusal} 一只回答者:词表外的键(条目层 / 本形 `transport` 层)⇒ `400 request.body_shape` 带 `unknownKeys`,
@@ -66,12 +67,11 @@ export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
  * ## 受理键的判官表也钉在这张表上
  * 逐键判官表 {@link ENTRY_KEY_JUDGES} 是 `{ [K in 本表的键]: 判官 }` 的映射型 —— 本表多一个键而没写判官 ⇒ 编译红,不会出现「这个键写坏了却被悄悄受理」的新键。
  */
-export declare const MCP_SERVER_ENTRY_KEYS: readonly ["allowTools", "contentOrigin", "elicitation", "name", "source", "startupTimeoutMs", "toolAxes", "toolFaces", "transport"];
-/** `transport.kind:"stdio"` 的键闭集(两向钉在 core 那一支上)。 */
-export declare const STDIO_MCP_TRANSPORT_KEYS: readonly ["args", "command", "env", "kind"];
-/** `transport.kind:"http"` 的键闭集(同上)。`assertionHeader` 是本仓承载、引擎尚无座的一格(见 {@link RequestMcpServerSpec}):
- *  表两向钉在**请求面的 http 传输型**上 = 引擎的键 ∪ 这一格;引擎一旦长出同名座,`mcp-assertion-header.ts` 的退役门当场红。 */
-export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ["assertionHeader", "headers", "kind", "principalHeader", "url"];
+export declare const MCP_SERVER_ENTRY_KEYS: readonly ["allowTools", "contentOrigin", "elicitation", "name", "sessionMetaKey", "source", "startupTimeoutMs", "toolAxes", "toolFaces", "transport"];
+/** `transport.kind:"stdio"` 的键闭集 = stdio 臂处置表的键(`env` 是件,其余进声明)。 */
+export declare const STDIO_MCP_TRANSPORT_KEYS: readonly ("kind" | "command" | "args" | "env")[];
+/** `transport.kind:"http"` 的键闭集 = http 臂处置表的键(`headers` 是件,`assertionHeader` 承载不发送,其余进声明)。 */
+export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ("kind" | "url" | "principalHeader" | "headers" | "assertionHeader")[];
 /**
  * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
  * (deployment-shape row `multiTenant` does not hold) — the requester is the super-admin of their own worker, so their `.mcp.json` is
@@ -157,9 +157,10 @@ export declare function requestEntryIdentityIssue(entry: unknown): McpIdentityHe
  *     `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` 再问「带不带凭据」= 契约包根的 `findUrlCredential`([ref];拒体另带机读 `field` + `reason`,见 {@link transportUrlCredentialIssue})。
+ *     读器交回的 http `url` 再问「带不带凭据」= 契约包根的 `findUrlCredential`([ref];拒体另带机读 `field` + `reason`,见 {@link transportUrlCredentialIssue});
+ *     http `principalHeader` 再问「这个名有没有别的属主」= 引擎包根的 `headerOwnershipCollision`(见 {@link principalHeaderOwnershipIssue})。
  * 于是判官受理的条目,读器({@link normalizeServer})交回的就是申报本身(只差判官自己的合法归一:空容器 / `skillScopeEligible:false` 折成缺席、`toolAxes` 取引擎的拷贝)——
- * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(引擎尚无座,
+ * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(本部署不发送断言,
  * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `specWithholdsMcpAssertionHeader`(开关 `MCP_ASSERTION_HEADER_SENT` 假时「声明了」即「被扣下」),不是第二份判法(见 `readMcpProbeBody`)。
  *
  * ## 射程
@@ -184,6 +185,14 @@ export declare function requestMcpDeclarationRefusal(list: unknown): Declaration
  * 交出去的剔掉 `__proto__` 名成员),server 照挂,运维 warn `mcp_transport_members_dropped` 逐处点名 —— 续跑重放腿不静默丢声明。
  */
 export declare function assertRequestMcpEntries(bodyMcp: unknown): void;
+/**
+ * `principalHeader` 的**名**有没有别的属主:判官是引擎包根的 `headerOwnershipCollision`(拨号时判同一条的那一只;这里只问身份头这一个名,件头名由引擎在发送时判)——
+ * 名(任何大小写)是这一协议的传输自己写的头(MCP:`mcp-session-id` · `mcp-protocol-version` · `content-type` · `accept` · `last-event-id`;A2A 没有),或是引擎的断言头
+ * (`connector-assertion`)⇒ 这一台拨号时必被拒,新提交在门上按名拒。原因句只点名**属主的拼写**(引擎 / 协议的词),不回显调用方写的串。
+ * 新提交腿上按名 400(MCP 门表的 `transport`、A2A 判官表的 `principalHeader`)。续跑重放腿不 4xx:MCP 的读器不问它 —— 存量体里这一形照挂,由引擎在拨号时拒那一台、兄弟照挂;
+ * A2A 的读器问同一张判官表 —— 这一条对端整条不进、`a2a_injection_dropped` 点名原因(引擎物化时同样拒那一台;结局同,原因说在本仓这一行)。
+ */
+export declare function principalHeaderOwnershipIssue(principalHeader: string | undefined, protocol: "mcp" | "a2a", path: string): DeclarationKeyIssue | undefined;
 /**
  * The ONE predicate for "this MCP server name belongs to the deployment": the scenario baseline (what mounted for
  * this scenario) ∪ every name the deployment DECLARED (`CenterMcp.reservedNames` — mounted or not, any scenario).
@@ -194,12 +203,14 @@ export declare function assertRequestMcpEntries(bodyMcp: unknown): void;
  */
 export declare function deploymentClosedMcpNames(baseline: McpServerSpec[] | undefined, reservedNames: readonly string[]): ReadonlySet<string>;
 /**
- * Merge GATED per-request MCP servers OVER the deployment baseline (center/config). Names closed by the deployment
- * ({@link deploymentClosedMcpNames}) are dropped from `gated`. `reservedNames` has NO default: a security predicate's
- * input is never implied — a caller with no deployment declaration passes `[]` and says so. Returns the baseline unchanged
- * when nothing is added.
+ * Merge GATED per-request MCP drafts OVER the deployment baseline (center/config): **select first, then mint**. Names closed by the deployment
+ * ({@link deploymentClosedMcpNames}) are dropped from `drafts` before anything is registered — a draft that loses to the deployment never
+ * reaches the desk; each winner is minted once on `desk` under `lease` (`peer-seat.ts` `mintDeclaration`: the reference on its transport, zero
+ * piece values). `desk` / `lease` = the process's peer desk and this leg's host lease (`boot/resolve-spec.ts` passes `peerDesk` and `opts.lease`).
+ * `reservedNames` has NO default: a security predicate's input is never implied — a caller with no deployment declaration passes `[]` and says so.
+ * Returns the baseline unchanged when nothing is added.
  */
-export declare function mergeRequestMcp(baseline: McpServerSpec[] | undefined, gated: McpServerSpec[], reservedNames: readonly string[]): McpServerSpec[] | undefined;
+export declare function mergeRequestMcp(baseline: McpServerSpec[] | undefined, drafts: readonly McpDraft[], reservedNames: readonly string[], desk: Pick<PeerDesk, "declare">, lease: PeerLease): McpServerSpec[] | undefined;
 /**
  * The single entry point the spec-builder calls: compute the effective `TaskSpec.mcp` = deployment baseline + the
  * caller's gated per-request servers. Off the honored lane (or with no caller servers) returns the baseline
@@ -216,7 +227,9 @@ export declare function resolveRequestMcp(baseline: McpServerSpec[] | undefined,
     mcpServers?: {
         reservedNames: readonly string[];
     };
-}, logger?: {
+}, 
+/** 对端座的 desk 与本腿的宿主租约(必填):胜出草稿在它下面铸成带引用的声明 —— 一条腿交给引擎的请求面声明只经它带引用。 */
+desk: Pick<PeerDesk, "declare">, lease: PeerLease, logger?: {
     info?(m: string, meta?: unknown): void;
     warn(m: string, meta?: unknown): void;
 }, 

package/dist/task-mcp.js

@@ -1,19 +1,21 @@
-import { mcpInjectionDroppedNotice, mcpStartupTimeoutMs, readToolFaces, resolveComplianceDenies } from "@sema-agent/core";
+import { MCP_ASSERTION_HEADER, headerOwnershipCollision, judgeSessionMetaKey, mcpInjectionDroppedNotice, mcpStartupTimeoutMs, readToolFaces, resolveComplianceDenies } from "@sema-agent/core";
 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 { MCP_HTTP_TRANSPORT_DISPOSITION, MCP_STDIO_TRANSPORT_DISPOSITION, describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, specWithholdsMcpAssertionHeader, toMcpDraft, } from "./mcp-assertion-header.js";
+import { declarationKeys } from "./plain-string-record.js";
+import { mintDeclaration, peerSentence } from "./peer-seat.js";
 import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
 import { readRequestToolAxes } from "./request-tool-axes.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"];
-export const STDIO_MCP_TRANSPORT_KEYS = ["args", "command", "env", "kind"];
-export const HTTP_MCP_TRANSPORT_KEYS = ["assertionHeader", "headers", "kind", "principalHeader", "url"];
+export const MCP_SERVER_ENTRY_KEYS = ["allowTools", "contentOrigin", "elicitation", "name", "sessionMetaKey", "source", "startupTimeoutMs", "toolAxes", "toolFaces", "transport"];
+export const STDIO_MCP_TRANSPORT_KEYS = declarationKeys(MCP_STDIO_TRANSPORT_DISPOSITION);
+export const HTTP_MCP_TRANSPORT_KEYS = declarationKeys(MCP_HTTP_TRANSPORT_DISPOSITION);
 export function mcpInjectionHonored(config) {
     if (config.lockedConfigKeys?.includes("mcp") === true)
         return false;
@@ -52,7 +54,7 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
         const again = readRequestToolAxes(storedToolAxes.mcp(o.toolAxes), "mcp");
         if (again.ok) {
             judged = again;
-            toolAxesReread = stripControlAndBidi(axes.problem);
+            toolAxesReread = peerSentence(stripControlAndBidi(axes.problem));
         }
     }
     if (!judged.ok)
@@ -73,6 +75,11 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
         return bad("toolFaces");
     if (faces.faces !== undefined)
         spec.toolFaces = faces.faces;
+    const metaKey = judgeSessionMetaKey(o.sessionMetaKey);
+    if ("problem" in metaKey)
+        return bad("sessionMetaKey");
+    if (metaKey.key !== undefined)
+        spec.sessionMetaKey = metaKey.key;
     return { ok: true, spec, ...(toolAxesReread !== undefined ? { toolAxesReread } : {}), transportLost: read.lost };
 }
 export function validateRequestMcp(raw) {
@@ -92,7 +99,7 @@ function validateRequestMcpEntries(raw, storedToolAxes) {
         if (v.ok) {
             ok.push(v.spec);
             if (v.toolAxesReread !== undefined)
-                toolAxesReread.push({ server: v.spec.name, problem: v.toolAxesReread });
+                toolAxesReread.push({ server: v.spec.name, sentence: v.toolAxesReread });
             if (v.transportLost.length > 0)
                 transportLost.push({ server: v.spec.name, lost: v.transportLost.map((i) => i.path) });
         }
@@ -164,6 +171,17 @@ function transportUrlCredentialIssue(url) {
         return undefined;
     return { path: "transport.url", reason: urlCredentialRefusalReason(found, urlCredentialHeaderExit("transport.headers")), credential: found };
 }
+export function principalHeaderOwnershipIssue(principalHeader, protocol, path) {
+    if (principalHeader === undefined)
+        return undefined;
+    const collision = headerOwnershipCollision({ principalHeader }, protocol);
+    if (collision === undefined)
+        return undefined;
+    return {
+        path,
+        reason: `names the header "${collision.first}" (header names are case-insensitive), which is not the principal header's to own — it is ${protocol === "mcp" && collision.first !== MCP_ASSERTION_HEADER ? "a header the MCP transport writes itself" : "the engine's connector assertion header"}; name the principal header something of its own`,
+    };
+}
 const ENTRY_KEY_JUDGES = {
     allowTools: (o) => o.allowTools === undefined || isStringArray(o.allowTools)
         ? undefined
@@ -177,6 +195,10 @@ const ENTRY_KEY_JUDGES = {
         },
     elicitation: (o) => (o.elicitation === undefined || isElicitationFlag(o.elicitation) ? undefined : { path: "elicitation", reason: `must be a boolean — got ${describeValueShape(o.elicitation)}` }),
     name: declarationNameIssue,
+    sessionMetaKey: (o) => {
+        const read = judgeSessionMetaKey(o.sessionMetaKey);
+        return "problem" in read ? { path: "sessionMetaKey", reason: peerSentence(read.problem) } : undefined;
+    },
     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)}` },
@@ -190,16 +212,16 @@ const ENTRY_KEY_JUDGES = {
         catch (e) {
             if (e.code !== "config.mcp_startup_timeout_invalid")
                 throw e;
-            return { path: "startupTimeoutMs", reason: e instanceof Error ? e.message : String(e) };
+            return { path: "startupTimeoutMs", reason: peerSentence(e instanceof Error ? e.message : String(e)) };
         }
     },
     toolAxes: (o) => {
         const read = readRequestToolAxes(o.toolAxes, "mcp");
-        return read.ok ? undefined : { path: "toolAxes", reason: read.problem };
+        return read.ok ? undefined : { path: "toolAxes", reason: peerSentence(read.problem) };
     },
     toolFaces: (o) => {
         const read = readToolFaces(o.toolFaces);
-        return read.ok ? undefined : { path: "toolFaces", reason: read.problem };
+        return read.ok ? undefined : { path: "toolFaces", reason: peerSentence(read.problem) };
     },
     transport: (o) => {
         const read = readRequestMcpTransport(o.transport);
@@ -207,7 +229,9 @@ const ENTRY_KEY_JUDGES = {
             return read.issue;
         if (read.lost[0] !== undefined)
             return read.lost[0];
-        return read.transport.kind === "http" ? transportUrlCredentialIssue(read.transport.url) : undefined;
+        if (read.transport.kind !== "http")
+            return undefined;
+        return transportUrlCredentialIssue(read.transport.url) ?? principalHeaderOwnershipIssue(read.transport.principalHeader, "mcp", "transport.principalHeader");
     },
 };
 function requestEntryRefusal(entry, at) {
@@ -229,27 +253,27 @@ function requestEntryRefusal(entry, at) {
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);
 }
-export function mergeRequestMcp(baseline, gated, reservedNames) {
-    if (gated.length === 0)
+export function mergeRequestMcp(baseline, drafts, reservedNames, desk, lease) {
+    if (drafts.length === 0)
         return baseline;
     const closed = deploymentClosedMcpNames(baseline, reservedNames);
-    const add = gated.filter((s) => !closed.has(s.name));
-    return add.length === 0 ? baseline : [...(baseline ?? []), ...add];
+    const winners = drafts.filter((d) => !closed.has(d.spec.name));
+    return winners.length === 0 ? baseline : [...(baseline ?? []), ...winners.map((d) => mintDeclaration(desk, d, lease))];
 }
-export function resolveRequestMcp(baseline, bodyMcp, config, logger, notice, storedToolAxes) {
+export function resolveRequestMcp(baseline, bodyMcp, config, desk, lease, logger, notice, storedToolAxes) {
     if (bodyMcp === undefined || bodyMcp === null)
         return baseline;
-    const { mcp, drops } = classifyRequestMcp(baseline, bodyMcp, config, logger, storedToolAxes);
+    const { mcp, drops } = classifyRequestMcp(baseline, bodyMcp, config, desk, lease, logger, storedToolAxes);
     mintInjectionDropNotices(drops, notice);
     return mcp;
 }
-function classifyRequestMcp(baseline, bodyMcp, config, logger, storedToolAxes) {
+function classifyRequestMcp(baseline, bodyMcp, config, desk, lease, logger, storedToolAxes) {
     if (bodyMcp !== undefined && bodyMcp !== null && !Array.isArray(bodyMcp)) {
         logger?.warn("mcp_injection_ignored", { reason: "mcpServers not an array" });
         return { mcp: baseline, drops: [] };
     }
     const entries = Array.isArray(bodyMcp) ? bodyMcp : [];
-    const outcome = mcpInjectionHonored(config) ? classifyHonored(baseline, entries, config, logger, storedToolAxes) : classifyGateClosed(baseline, entries);
+    const outcome = mcpInjectionHonored(config) ? classifyHonored(baseline, entries, config, desk, lease, logger, storedToolAxes) : classifyGateClosed(baseline, entries);
     if (outcome.drops.length > 0)
         logger?.warn("mcp_injection_dropped", { dropped: outcome.drops, droppedTotal: outcome.droppedTotal });
     return { mcp: outcome.mcp, drops: outcome.drops };
@@ -261,7 +285,7 @@ function classifyGateClosed(baseline, entries) {
         droppedTotal: entries.length,
     };
 }
-function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
+function classifyHonored(baseline, entries, config, desk, lease, logger, storedToolAxes) {
     const v = validateRequestMcpEntries(entries, storedToolAxes);
     if (v.badContentOrigin.length > 0) {
         logger?.warn("mcp_content_class_dropped", {
@@ -288,7 +312,7 @@ function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
         logger?.warn("mcp_tool_axes_read_as_before_upgrade", {
             server: r.server,
             migration: "M19",
-            problem: r.problem,
+            problem: r.sentence,
             note: "this replayed request was stored before the upgrade and its toolAxes declaration does not pass the engine's reader; while one-time migration M19 is open it is read the way the pre-upgrade server read it (members that did not fit are dropped, a declaration that is not an object counts as none) and the server stays mounted — once the window closes the same request leaves this server unmounted",
         });
     }
@@ -305,7 +329,7 @@ function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
         });
     }
     return {
-        mcp: mergeRequestMcp(baseline, v.ok.map(toCoreMcpServerSpec), reservedNames),
+        mcp: mergeRequestMcp(baseline, v.ok.map(toMcpDraft), reservedNames, desk, lease),
         drops: [...v.dropped, ...blocked.map((server) => ({ server, reason: "name_reserved_by_deployment" }))],
         droppedTotal: v.droppedTotal + blocked.length,
     };