@sema-agent/server 7.130.0 → 7.132.0

package/dist/task-mcp.d.ts

@@ -37,10 +37,9 @@ export declare const MAX_REQUEST_MCP_SERVERS = 32;
  * ——同一条链上后续的正常事件全部排在它们后面。修前的名字数组把超上限折成**一条**聚合串,所以无界的
  * 是本批新写的那两个循环。
  *
- * 为什么不改成「数组太长就 400」(codex 的另一条建议,**未采纳**):今天 33 台的请求是**照常受理、挂前
- * 32 台**的,加一条新的拒绝面为了一个资源边界去改受理语义,爆炸半径比病本身大(而且 resume 腿重放存量
- * body 会当场砖死一批已 park 的任务——本仓 `opts.leg` 三处先例逐字写着「砖死 resume 比降级糟」)。
- * 有界点名两头都占:该说的仍然说得出,量级钉死在与挂载同阶。
+ * 新提交腿上超过 {@link MAX_REQUEST_MCP_SERVERS} 条的列表在腿首整份 400({@link requestMcpDeclarationRefusal}),走不到这里;
+ * 有界点名守的是**重放存量 body** 的腿(那条腿不拒 —— 砖死 resume 比降级糟,本仓 `opts.leg` 三处先例)与闸关腿:
+ * 存量 body 的长度只受当时的 HTTP 体上限约束,该说的仍然说得出,量级钉死在与挂载同阶。
  */
 export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
 /**
@@ -58,26 +57,20 @@ export declare const MAX_REQUEST_MCP_DROP_NAMES = 32;
  * (唯一一格不在 core 型上的键 = http 传输的 `assertionHeader`:引擎尚无座,本仓承载 —— 那一支的门钉在
  * `mcp-assertion-header.ts` 的 {@link RequestMcpServerSpec} 上,引擎一旦长出同名座,那里的退役门当场红。)
  *
- * ## 两个消费点的处置**刻意不同**(同一张表,不同的门)
- *  · 提交腿({@link normalizeServer})对词表外的键**宽容**(读不认识的键就当没有)—— 那条腿要能安全地
- *    重放存量 body,一个 4xx 打在 resume 上会永久砖死一条 parked 任务(本仓三处 `opts.leg` 先例);
- *  · 探测口**响亮拒**(400,点名 `mcpServers[i].<键>`)—— 它问的是「这台到底能不能用」,把一个拼错的键
- *    悄悄忽略再回一份好看的名单,正是那条面要根除的假答案。
- * 两个门,一个词表。表在这里,门在各自的腿上。
+ * ## 一个回答者,两扇门;读器另算
+ * 「这份声明能不能原样用」只有 {@link requestMcpDeclarationRefusal} 一只回答者:词表外的键(条目层 / 本形 `transport` 层)⇒ `400 request.body_shape` 带 `unknownKeys`,
+ * fresh 提交腿({@link assertRequestMcpEntries})与探测口同码同句 —— 一个拼错的键被悄悄不读,声明方会以为它生效了。
+ * 读器({@link normalizeServer})对词表外的键仍**宽容**(读不认识的键就当没有):它只服务重放存量 body 的腿,一个 4xx 打在 resume 上会永久砖死一条 parked 任务(本仓三处 `opts.leg` 先例)。
+ *
+ * ## 受理键的判官表也钉在这张表上
+ * 逐键判官表 {@link ENTRY_KEY_JUDGES} 是 `{ [K in 本表的键]: 判官 }` 的映射型 —— 本表多一个键而没写判官 ⇒ 编译红,不会出现「这个键写坏了却被悄悄受理」的新键。
  */
-export declare const MCP_SERVER_ENTRY_KEYS: readonly ["allowTools", "contentOrigin", "elicitation", "name", "source", "toolAxes", "toolFaces", "transport"];
+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"];
-/** 条目层:`{}` 与缺席等价的可选 Record 键。 */
-export declare const MCP_ENTRY_EMPTY_RECORD_KEYS: readonly ["toolAxes", "toolFaces"];
-/** 条目层:`[]` 与缺席等价的可选数组键。 */
-export declare const MCP_ENTRY_EMPTY_ARRAY_KEYS: readonly ["allowTools"];
-/** 传输层(两种合起来):`{}` / `[]` 与缺席等价的键。 */
-export declare const MCP_TRANSPORT_EMPTY_RECORD_KEYS: readonly ["env", "headers"];
-export declare const MCP_TRANSPORT_EMPTY_ARRAY_KEYS: readonly ["args"];
 /**
  * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
  * (`requirePrincipal !== true`) — the requester is the super-admin of their own worker, so their `.mcp.json` is
@@ -145,97 +138,56 @@ type ValidatedRequestMcp = {
  * 任务。同样是失败,同步 400 至少是**立刻可诊断**的那一种,而且拒得出理由(锁在哪、怎么改)。
  */
 export declare function assertRequestMcpUnlocked(bodyMcp: unknown, lockedKeys: ReadonlySet<LockedKey>): void;
-/**
- * [ref](core 5.60.0 提货批件②)—— 请求体里 `mcpServers[].contentOrigin` 的**值域门**,腿首同步拒。
- *
- * ## 先把 core 的硬条款抄下来,因为本腿的全部争议都在它上面
- * `McpServerSpec.contentOrigin` 顶注逐字:「TRUST SOURCE — a DEPLOYMENT-plane key … any assembly layer
- * that accepts REQUEST-side MCP entries **must reject or strip this key** from them … A single-tenant
- * superuser surface (a host reading its own `--mcp-config` file) **IS the deployment plane and needs no
- * such gate**.」
- *
- * ## 本仓怎么兑现这条义务(**结构性**,不是靠纪律)
- * 请求腿的条目只有在 {@link mcpInjectionHonored} 为真时才被读进 `TaskSpec.mcp`,而那只谓词的语义正是
- * 「本部署是单用户 ⇒ 请求者就是这台 worker 的超管」—— core 点名豁免的那一格。多租户部署
- * (`requirePrincipal===true`)整只 `mcpServers` 被忽略,租户**结构上**够不着这个键(钉见
- * `test/task-mcp.test.ts` 的多租户格)。同一条腿今天已经透传 `toolAxes`(喂**审批门**,权限比本键**高**
- * 一档 —— core 明写 contentOrigin「no gate/policy/roster effect」)与 stdio 的**任意命令**(worker 宿主
- * 上的真无限制执行);在那两样之后,「我声明我自己这台 server 的内容不算外来」不构成任何新的暴露面。
- * 名字撞车时 baseline 恒赢(`mergeRequestMcp`)⇒ 调用方也改写不了一台**已配置** server 的声明。
- *
- * ## 为什么 fresh 腿是 400 而不是静默丢键
- * 静默丢键会把一次**信任边界声明**变成探针 —— 调用方以为声明生效了,其实没有。本仓 `opts.leg` 的成文
- * 契约(`ServiceDeps.resolveSpec` 顶注)逐字写着 fresh 腿「may fail-loud 400 on combos that would
- * silently discard caller payload」,这正是那种 combo。
- *
- * ## 🔴 但只在 fresh 腿(与 {@link assertRequestMcpUnlocked} **刻意分歧**)
- * 锁那条敢在 resume 腿同拒,是因为它有一个本门**没有**的前提:锁在场 ⇒ core 的 preflight 无论如何都会
- * 拒这条腿,放进去只换来一个跑起来又终态失败的任务。而坏 `contentOrigin` 在本仓两个平面都被**降级**掉了
- * (`normalizeServer` / `resolveMcpServers`),core 根本看不到它,也就永远不会拒。
- * 与此同时 `checkpoint_ctx` 存的是**原始** `TaskRequestBody`,耐久 resume 逐字重放它,从本门逃出去的
- * `HttpError` 会被 `src/http/server.ts` 折成 `409 resume_blocked_by_policy` ⇒ 一条**升级前** park、body 里
- * 带着当时被静默忽略的坏值的任务,升级后**永久**恢复不了(codex 交叉复审 R1-[high],验真后采纳)。
- * ⇒ 照本仓成文的三处 `opts.leg` 先例(`appendSystemPrompt` 案 / `@model` 名单 [ref] 终裁 (a) /
- * `compactionModel` 案,都逐字写着「砖死 resume 比降级糟」):fresh fail-loud,resume 降级 + 留声
- * (留声点 = {@link resolveRequestMcp} 的 `mcp_content_class_dropped`)。挂点判据在 `boot/resolve-spec.ts`。
- *
- * ## 位置与射程
- * 排在腿首、`assertRequestMcpUnlocked` 旁边 —— **任何副作用之前**(附件绑定 / per-session cwd·env 写入;
- * 理由逐字见 `boot/resolve-spec.ts` 那两行的注)。判据是**纯值域**、与**租户车道**无关:一个写坏的请求
- * 在哪条车道上都是写坏的,而多租户腿本来就要忽略整只数组,告诉调用方「你这个键写错了」只多不少。
- * 形不合(非数组 / 条目非对象)**不归本门**——那是 `validateRequestMcp` 的既有宽容形,本门不抢裁决。
- */
-export declare function assertRequestMcpContentOrigin(bodyMcp: unknown): void;
-/**
- * S-1515 —— `mcpServers[].transport`(http)上两个身份头的**值域门**(fresh 腿限定,同步 400):`principalHeader` 与 `assertionHeader`
- * **同设**(`request.body_shape`),或 `assertionHeader` 在场而**不是字符串**(`request.field_invalid`)。
- *
- * 前者:两个键回答同一个问题(「这台 http 服务器的请求上用哪个头送身份」),同设 = 两个答案。settings 面由契约包在解析期判拒;
- * 请求面在这里判拒 —— **同一条规则、两处执行者**,判据与拒句单点在 `mcp-assertion-header.ts`(对契约包原句逐字,差分钉守)。
- * 后者:契约包的 zod 类型拒它;请求面若把它读成"没写过",一条鉴权声明就无声消失、server 却照常挂上去连。
- *
- * ## 位置与 leg 分流(与 {@link assertRequestMcpContentOrigin} 同款理由,不发明第二套)
- * 排在腿首、任何副作用之前;**只在 fresh 腿**:`checkpoint_ctx` 存的是原始 `TaskRequestBody`,耐久 resume 逐字重放它,
- * 从这里逃出去的 `HttpError` 会被折成 `409 resume_blocked_by_policy`,把一条 park 任务永久砖死。resume 腿走读器
- * ({@link normalizeServer}):**降级到升级前的读法**(server 照挂、`principalHeader` 胜、`assertionHeader` 不生效)+ `classifyHonored` 一行 warn ——
- * 不拒、也不摘 server。判据是纯值域、与租户车道无关(多租户腿本来就忽略整只数组,告诉调用方「你这条写错了」只多不少)。
- */
-export declare function assertRequestMcpIdentityHeaders(bodyMcp: unknown): void;
 /** 一条**原始**请求条目上两个身份头的问题类(没有问题 / 不是对象 / 不是 http 传输 ⇒ `undefined`)—— 提交腿的门、探测口、重放腿的披露三处共读,
  *  判据本体在 `mcp-assertion-header.ts`;这里只负责把「条目 → 传输对象」那一步读出来。 */
 export declare function requestEntryIdentityIssue(entry: unknown): McpIdentityHeadersIssue | undefined;
-/** 问题类 → wire 拒面(码 + 句子):两扇拒绝门(提交腿 / 探测口)同一份。条目名进句子,过唯一的回显清洗(剥控制 / 双向字符 + 截长);
- *  读不出名字的条目用与丢弃点同一个占位。 */
-export declare function requestEntryIdentityRefusal(entry: unknown): {
-    errorCode: "request.body_shape" | "request.field_invalid";
-    message: string;
-} | undefined;
+/** 请求面 `mcpServers` 的一次拒:码 + 句 + 词表外的键名表(只在闭集那一形上在场)。两扇门(fresh 提交腿 / 探测口)同一份,状态恒 400。 */
+export interface RequestMcpRefusal {
+    readonly errorCode: "request.body_shape" | "request.field_invalid";
+    readonly message: string;
+    /** 词表外的键,全路径形(`mcpServers[0].transport.header`;已清洗 + 截长 + 排序 + 封顶)。 */
+    readonly unknownKeys?: readonly string[];
+}
 /**
- * S-1604 —— `mcpServers[].toolAxes` 的**值域门**(fresh 腿限定,同步 400):判官是引擎根导出的 `readMcpToolAxes`(与部署腿铸 spec 处同一只),
- * 判出 `ok:false` ⇒ `400 request.field_invalid`,点名 `mcpServers[i].toolAxes`、server 名与引擎的原因句(点名工具与成员,不带值)。
- *
- * ## 为什么拒而不是剔
- * `toolAxes` 是调用方对这台 server 每只工具的**双向**风险轴声明(能压低一只工具的效应让审批门放行,也能抬高)。静默剔掉坏成员 = 调用方拿到 2xx、
- * 以为整份声明生效,实际只有另一半在力 —— 一份没有生效的信任根声明。引擎的读法本就是「整份一坏全拒、好的那几只也不留、什么都不默认」,
- * 请求腿修前自铸的读者与它相反;从此只有一只判官,两条腿同读。
- *
- * ## 位置与 leg 分流(与 {@link assertRequestMcpContentOrigin} / {@link assertRequestMcpIdentityHeaders} 同款理由,不发明第二套)
- * 排在腿首、任何副作用之前;**只在 fresh 腿**:`checkpoint_ctx` 存的是原始 `TaskRequestBody`,耐久 resume 逐字重放它,从这里逃出去的 `HttpError`
- * 会被折成 `409 resume_blocked_by_policy`,把一条升级前 park 的任务永久砖死。resume 腿走读器({@link normalizeServer}):同一只判官判出坏形 ⇒ 这一条 server
- * 不进 + `malformed_entry` 点名(运维 warn + 用户面通告,不抛);一次性迁移 M19 的窗开着时先按升级前读法重读一次(见那只读器的注)。
- * 判据是纯值域、与租户车道无关(多租户腿本来就忽略整只数组,告诉调用方「你这条写错了」只多不少)。
- * 探测口读同一只 {@link requestEntryToolAxesRefusal},同一句拒。
+ * 请求面 `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})。
+ *     整份拒而不是挂前 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})。
+ *     判官**就是读器用的那一只**,不是第二份:`toolAxes` = 引擎根导出的 `readMcpToolAxes`;`toolFaces` = `readMcpToolFaces`;`contentOrigin` = `isContentOriginWord`;`source` = `isMcpSourceLabel`;
+ *     `name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = {@link readPlainStringRecord};`elicitation` = {@link isElicitationFlag};
+ *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`)。
+ *     判官只在引擎里、包根没给读口的键(今天只有 `startupTimeoutMs`)不在这里判,原样过境、由引擎在拨号时按 server 拒(不写第二份判据;到货读口即换)。
+ * 于是判官受理的条目,读器({@link normalizeServer})交回的就是申报本身(只差判官自己的合法归一:空容器 / `skillScopeEligible:false` 折成缺席、`toolAxes` 取引擎的拷贝)——
+ * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(引擎尚无座,
+ * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `declaresMcpAssertionHeader`,不是第二份判法(见 `readMcpProbeBody`)。
+ *
+ * ## 射程
+ * 纯值域、与租户车道无关(一个写坏的请求在哪条车道上都是写坏的;多租户腿本来就忽略整只数组,告诉调用方「你写错了」只多不少)。
+ * 重放存量 body 的腿**不问它**:那条腿走宽容读器(见 {@link assertRequestMcpEntries} 的 leg 分流)。
+ * 关于 `contentOrigin` 的信任语义(core 把它定性为**部署面**键):请求腿的条目只有在 {@link mcpInjectionHonored} 为真(单用户 = 请求者就是这台 worker 的超管)时才被读进 `TaskSpec.mcp`,
+ * 多租户部署整只数组被忽略 ⇒ 租户**结构上**够不着这个键;名字撞车时 baseline 恒赢({@link mergeRequestMcp})⇒ 调用方也改写不了一台**已配置** server 的声明。
  */
-export declare function assertRequestMcpToolAxes(bodyMcp: unknown): void;
+export declare function requestMcpDeclarationRefusal(list: unknown): RequestMcpRefusal | undefined;
 /**
- * 一条**原始**请求条目上 `toolAxes` 的拒面(码 + 句子);没有问题 / 条目不是对象 / 没写 `toolAxes` ⇒ `undefined`。提交腿的门({@link assertRequestMcpToolAxes})与探测口
- * (`mcp-probe.ts` 的 `entryValueIssue`)两扇拒绝门同读这一只,所以两处是**同一句**。判官是引擎的 `readMcpToolAxes`,句子里的原因句逐字取它的 `problem`
- * (只剥控制与双向字符:工具名是调用方写的);不回显值 —— 引擎的句子点名工具与成员、不带值。`at` = 条目的键路径(`mcpServers[3]`)。
+ * fresh 提交腿的 `mcpServers` 门:{@link requestMcpDeclarationRefusal} 有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` 原样)。
+ *
+ * ## 位置与 leg 分流(沿用本仓成文的 `opts.leg` 姿势,不发明第二套)
+ * 排在腿首、`assertRequestMcpUnlocked` 旁边 —— **任何副作用之前**(①阶段会把附件行持久绑定到 session,②阶段会写 per-session 的 cwd/env 表;一个最终 400 的请求若已经改掉这两样,
+ * 它就改变了后续被接受的任务会物化什么、在哪执行)。**只在 fresh 腿**:`checkpoint_ctx` 存的是**原始** `TaskRequestBody`,耐久 resume 逐字重放它,从这里逃出去的 `HttpError`
+ * 会被 `src/http/server.ts` 折成 `409 resume_blocked_by_policy` ⇒ 一条**升级前** park、body 里带着当时被受理的坏值的任务,升级后永久恢复不了
+ * (本仓三处 `opts.leg` 先例 —— `appendSystemPrompt` 案 / `@model` 名单 [ref] 终裁 (a) / `compactionModel` 案 —— 逐字写着「砖死 resume 比降级糟」)。
+ * 重放腿走读器({@link normalizeServer} / {@link classifyRequestMcp}),处置:整只不是数组 ⇒ 整只忽略 + 运维 warn `mcp_injection_ignored`;条目不是对象 / 坏硬键
+ * (`name` / `transport` 硬字段 / `allowTools` / `toolAxes` / `toolFaces`)⇒ 这一条 server 整条不进 + 运维 warn `mcp_injection_dropped` + 用户面通告 `mcp.injection_dropped` 点名 `field`
+ * (`toolAxes` 在一次性迁移 M19 的窗开着时先按升级前读法重读一次,过了就挂,见读器的注);超上限的尾项 ⇒ `over_cap` 点名;坏软键(`contentOrigin` / `elicitation` / `source`)
+ * 与词表外的键 ⇒ 丢键、server 照挂(`contentOrigin` 另有 `mcp_content_class_dropped` 留声);`transport` 软字段 ⇒ 只不交坏的那几处(`env` / `headers` 对 JSON 存体按 7.131.x 的判据整键交或不交,
+ * 交出去的剔掉 `__proto__` 名成员),server 照挂,运维 warn `mcp_transport_members_dropped` 逐处点名 —— 续跑重放腿不静默丢声明。
  */
-export declare function requestEntryToolAxesRefusal(entry: unknown, at: string): {
-    errorCode: "request.field_invalid";
-    message: string;
-} | undefined;
+export declare function assertRequestMcpEntries(bodyMcp: unknown): void;
 /**
  * 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).

package/dist/task-mcp.js

@@ -1,22 +1,19 @@
 import { mcpInjectionDroppedNotice, readMcpToolAxes, resolveComplianceDenies } from "@sema-agent/core";
-import { isUsableWireName } from "./wire-name-bound.js";
+import { MCP_CONTENT_ORIGINS, describeNotStringArray, describeValueShape, isContentOriginWord, isStringArray, isUsableWireName, readMcpIdentityHeaders, } from "@sema-agent/settings-schema";
+import { describeBadContentOrigin, describeBadWireName } from "./caller-text-echo.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 { MCP_SOURCE_LABEL_MAX, isMcpSourceLabel, readMcpSourceLabel } from "./mcp-source-label.js";
+import { declaresMcpAssertionHeader, describeMcpAssertionHeaderNotAString, describeMcpIdentityHeadersConflict, mcpIdentityHeadersIssue, noteMcpAssertionHeaderIgnored, noteMcpAssertionHeaderNotSent, toCoreMcpServerSpec } from "./mcp-assertion-header.js";
+import { MAX_KEY_ECHO, echoKeyName, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
 import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 import { readMcpToolFaces } from "./mcp-tool-faces.js";
+import { readPlainStringRecord } from "./plain-string-record.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 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_ENTRY_EMPTY_RECORD_KEYS = ["toolAxes", "toolFaces"];
-export const MCP_ENTRY_EMPTY_ARRAY_KEYS = ["allowTools"];
-export const MCP_TRANSPORT_EMPTY_RECORD_KEYS = ["env", "headers"];
-export const MCP_TRANSPORT_EMPTY_ARRAY_KEYS = ["args"];
 export function mcpInjectionHonored(config) {
     if (config.lockedConfigKeys?.includes("mcp") === true)
         return false;
@@ -24,8 +21,67 @@ export function mcpInjectionHonored(config) {
         return false;
     return config.requirePrincipal !== true;
 }
-function isStringRecord(v) {
-    return !!v && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function isElicitationFlag(v) {
+    return typeof v === "boolean";
+}
+const transportBad = (path, reason) => ({ ok: false, issue: { path, reason } });
+function readRequestTransport(t) {
+    if (!t || typeof t !== "object")
+        return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${describeValueShape(t)}`);
+    const tr = t;
+    const lost = [];
+    if (tr.kind === "stdio") {
+        if (typeof tr.command !== "string" || tr.command.length === 0)
+            return transportBad("transport.command", `must be a non-empty string (the command to run) — got ${describeValueShape(tr.command)}`);
+        if (tr.args !== undefined && !isStringArray(tr.args))
+            lost.push({ path: "transport.args", reason: `must be an array of strings — got ${describeNotStringArray(tr.args)}` });
+        const env = readTransportRecord("transport.env", tr.env, lost);
+        return {
+            ok: true,
+            transport: {
+                kind: "stdio",
+                command: tr.command,
+                ...(isStringArray(tr.args) ? { args: tr.args } : {}),
+                ...(env !== undefined ? { env } : {}),
+            },
+            lost,
+        };
+    }
+    if (tr.kind === "http") {
+        if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
+            return transportBad("transport.url", "must be an absolute http(s) URL (put credentials in transport.headers, never in the URL)");
+        const ids = readMcpIdentityHeaders(tr);
+        const headers = readTransportRecord("transport.headers", tr.headers, lost);
+        if (tr.principalHeader !== undefined && ids.principalHeader === undefined) {
+            lost.push({ path: "transport.principalHeader", reason: `must be a string (the HTTP header NAME the end-user principal is injected into) — got ${describeValueShape(tr.principalHeader)}` });
+        }
+        return {
+            ok: true,
+            transport: {
+                kind: "http",
+                url: tr.url,
+                ...(headers !== undefined ? { headers } : {}),
+                ...ids,
+            },
+            lost,
+        };
+    }
+    return transportBad("transport.kind", `must be "stdio" or "http" — got ${describeValueShape(tr.kind)}`);
+}
+function readTransportRecord(path, raw, lost) {
+    if (raw === undefined)
+        return undefined;
+    const read = readPlainStringRecord(raw);
+    if (!read.ok) {
+        lost.push({ path, reason: `must be a plain object of string values — ${read.member === undefined ? read.fault : `its member "${echoKeyName("", read.member)}" ${read.fault}`}` });
+        return undefined;
+    }
+    for (const m of read.stripped)
+        lost.push({ path: echoKeyName(`${path}.`, m.name), reason: m.fault });
+    return read.record;
 }
 const bad = (field) => ({ ok: false, field });
 const MALFORMED_NAME = "<malformed>";
@@ -40,47 +96,22 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
     const o = e;
     if (!isUsableWireName(o.name))
         return bad("name");
-    const t = o.transport;
-    if (!t || typeof t !== "object")
-        return bad("transport");
-    const tr = t;
-    let transport;
-    if (tr.kind === "stdio") {
-        if (typeof tr.command !== "string" || tr.command.length === 0)
-            return bad("transport.command");
-        transport = {
-            kind: "stdio",
-            command: tr.command,
-            ...(Array.isArray(tr.args) && tr.args.every((a) => typeof a === "string") ? { args: tr.args } : {}),
-            ...(isStringRecord(tr.env) ? { env: tr.env } : {}),
-        };
-    }
-    else if (tr.kind === "http") {
-        if (typeof tr.url !== "string" || !/^https?:\/\//i.test(tr.url))
-            return bad("transport.url");
-        transport = {
-            kind: "http",
-            url: tr.url,
-            ...(isStringRecord(tr.headers) ? { headers: tr.headers } : {}),
-            ...readMcpIdentityHeaders(tr),
-        };
-    }
-    else {
-        return bad("transport.kind");
-    }
-    const spec = { name: o.name, transport };
+    const read = readRequestTransport(o.transport);
+    if (!read.ok)
+        return bad(read.issue.path);
+    const spec = { name: o.name, transport: read.transport };
     if (o.allowTools !== undefined) {
-        if (!Array.isArray(o.allowTools) || !o.allowTools.every((a) => typeof a === "string"))
+        if (!isStringArray(o.allowTools))
             return bad("allowTools");
         spec.allowTools = o.allowTools;
     }
-    if (typeof o.elicitation === "boolean")
+    if (isElicitationFlag(o.elicitation))
         spec.elicitation = o.elicitation;
     const axes = readMcpToolAxes(o.toolAxes);
     let judged = axes;
     let toolAxesReread;
     if (!axes.ok && storedToolAxes !== undefined) {
-        const again = readMcpToolAxes(storedToolAxes(o.toolAxes));
+        const again = readMcpToolAxes(storedToolAxes.mcp(o.toolAxes));
         if (again.ok) {
             judged = again;
             toolAxesReread = axes.problem.replace(CONTROL_AND_BIDI_STRIP_RE, "");
@@ -97,12 +128,14 @@ function normalizeServer(e, noteBadOrigin, storedToolAxes) {
             noteBadOrigin(spec.name, o.contentOrigin);
     }
     Object.assign(spec, readMcpSourceLabel(spec.name, o.source));
+    if (o.startupTimeoutMs !== undefined)
+        spec.startupTimeoutMs = o.startupTimeoutMs;
     const faces = readMcpToolFaces(o.toolFaces);
     if (!faces.ok)
         return bad("toolFaces");
     if (faces.faces !== undefined)
         spec.toolFaces = faces.faces;
-    return { ok: true, spec, ...(toolAxesReread !== undefined ? { toolAxesReread } : {}) };
+    return { ok: true, spec, ...(toolAxesReread !== undefined ? { toolAxesReread } : {}), transportLost: read.lost };
 }
 export function validateRequestMcp(raw) {
     if (raw !== undefined && raw !== null && !Array.isArray(raw))
@@ -115,19 +148,22 @@ function validateRequestMcpEntries(raw, storedToolAxes) {
     const dropped = [];
     const badContentOrigin = [];
     const toolAxesReread = [];
+    const transportLost = [];
     for (const e of raw.slice(0, MAX_REQUEST_MCP_SERVERS)) {
         const v = normalizeServer(e, (server, value) => badContentOrigin.push({ server, value: describeBadContentOrigin(value) }), storedToolAxes);
         if (v.ok) {
             ok.push(v.spec);
             if (v.toolAxesReread !== undefined)
                 toolAxesReread.push({ server: v.spec.name, problem: v.toolAxesReread });
+            if (v.transportLost.length > 0)
+                transportLost.push({ server: v.spec.name, lost: v.transportLost.map((i) => i.path) });
         }
         else
             dropped.push({ server: declaredName(e), reason: "malformed_entry", field: v.field });
     }
     for (const e of raw.slice(MAX_REQUEST_MCP_SERVERS, MAX_REQUEST_MCP_SERVERS + MAX_REQUEST_MCP_DROP_NAMES))
         dropped.push({ server: declaredName(e), reason: "over_cap" });
-    return { ok, dropped, droppedTotal: Math.max(0, raw.length - ok.length), badContentOrigin, toolAxesReread };
+    return { ok, dropped, droppedTotal: Math.max(0, raw.length - ok.length), badContentOrigin, toolAxesReread, transportLost };
 }
 export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
     if (!lockedKeys.has("mcp"))
@@ -138,30 +174,6 @@ export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
         code: "config.locked_key",
     });
 }
-export function assertRequestMcpContentOrigin(bodyMcp) {
-    if (!Array.isArray(bodyMcp))
-        return;
-    for (const e of bodyMcp) {
-        if (!e || typeof e !== "object" || Array.isArray(e))
-            continue;
-        const v = e.contentOrigin;
-        if (v === undefined)
-            continue;
-        if (isContentOriginWord(v))
-            continue;
-        throw new HttpError(400, `mcpServers[].contentOrigin must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(v)}` +
-            ` (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;
@@ -170,39 +182,117 @@ export function requestEntryIdentityIssue(entry) {
         return undefined;
     return mcpIdentityHeadersIssue(t);
 }
-export function requestEntryIdentityRefusal(entry) {
+function requestEntryIdentityRefusal(entry, at) {
     const issue = requestEntryIdentityIssue(entry);
-    if (issue === undefined)
+    if (issue === undefined || !isRecord(entry))
         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) };
+        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) });
 }
-export function assertRequestMcpToolAxes(bodyMcp) {
-    if (!Array.isArray(bodyMcp))
-        return;
-    for (let i = 0; i < bodyMcp.length; i++) {
-        const refusal = requestEntryToolAxesRefusal(bodyMcp[i], `mcpServers[${i}]`);
+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)
-            throw createCodedHttpError(400, refusal.errorCode, refusal.message);
+            return refusal;
     }
+    return undefined;
 }
-export function requestEntryToolAxesRefusal(entry, at) {
-    if (!entry || typeof entry !== "object" || Array.isArray(entry))
-        return undefined;
-    const read = readMcpToolAxes(entry.toolAxes);
-    if (read.ok)
-        return undefined;
+export function assertRequestMcpEntries(bodyMcp) {
+    const refusal = requestMcpDeclarationRefusal(bodyMcp);
+    if (refusal !== undefined)
+        throw createCodedHttpError(400, refusal.errorCode, refusal.message, refusal.unknownKeys === undefined ? undefined : { unknownKeys: [...refusal.unknownKeys] });
+}
+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}` };
+}
+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);
+const NO_TOLERATED_KEYS = new Set();
+function entryUnknownKeys(entry, at) {
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyClosure(entry, `${at}.`, ENTRY_KEY_SET, NO_TOLERATED_KEYS, buckets);
+    const t = entry.transport;
+    if (isRecord(t)) {
+        const keys = t.kind === "stdio" ? STDIO_TRANSPORT_KEY_SET : t.kind === "http" ? HTTP_TRANSPORT_KEY_SET : undefined;
+        if (keys !== undefined)
+            scanKeyClosure(t, `${at}.transport.`, keys, NO_TOLERATED_KEYS, buckets);
+    }
+    return buckets.unknown.sort();
+}
+const ENTRY_KEY_JUDGES = {
+    allowTools: (o) => o.allowTools === undefined || isStringArray(o.allowTools)
+        ? undefined
+        : { path: "allowTools", reason: `must be an array of strings (omit the key to leave the server's tools unrestricted) — got ${describeNotStringArray(o.allowTools)}` },
+    contentOrigin: (o) => o.contentOrigin === undefined || isContentOriginWord(o.contentOrigin)
+        ? undefined
+        : {
+            path: "contentOrigin",
+            reason: `must be one of ${MCP_CONTENT_ORIGINS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(o.contentOrigin)}` +
+                ` (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)}` }),
+    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)}` },
+    startupTimeoutMs: () => undefined,
+    toolAxes: (o) => {
+        const read = readMcpToolAxes(o.toolAxes);
+        return read.ok ? undefined : { path: "toolAxes", reason: read.problem };
+    },
+    toolFaces: (o) => {
+        const read = readMcpToolFaces(o.toolFaces);
+        return read.ok ? undefined : { path: "toolFaces", reason: read.problem };
+    },
+    transport: (o) => {
+        const read = readRequestTransport(o.transport);
+        return read.ok ? read.lost[0] : read.issue;
+    },
+};
+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}.toolAxes (server "${server}") is not a usable declaration — ${read.problem.replace(CONTROL_AND_BIDI_STRIP_RE, "")}. ` +
-            `The whole declaration is refused: the tools that were fine are not kept and nothing is defaulted, because a toolAxes declaration is your own risk-axis judgement for this server's tools ` +
-            `(it can move a tool down or up), and a half-applied one would silently differ from what you declared. Fix the entry, or omit the key to declare nothing.`,
+        message: `${at}.${issue.path} (server "${server}") is not a usable declaration — ${issue.reason.replace(CONTROL_AND_BIDI_STRIP_RE, "")}. ${ENTRY_REFUSAL_TAIL}`,
     };
 }
+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 {
+            errorCode: "request.body_shape",
+            message: `body: unrecognized key(s) on an MCP declaration — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
+                `${keyClosureClause(unknownKeys, "unknown (not an mcpServers[] key — check the spelling)")}. ` +
+                `Accepted per entry: ${[...MCP_SERVER_ENTRY_KEYS].sort().join(",")} (transport.kind "stdio": ${[...STDIO_MCP_TRANSPORT_KEYS].sort().join(",")}; "http": ${[...HTTP_MCP_TRANSPORT_KEYS].sort().join(",")})`,
+            unknownKeys: unknownKeys.slice(0, MAX_KEY_ECHO),
+        };
+    }
+    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;
+}
 export function deploymentClosedMcpNames(baseline, reservedNames) {
     return new Set([...(baseline ?? []).map((s) => s.name), ...reservedNames]);
 }
@@ -243,7 +333,7 @@ function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
     if (v.badContentOrigin.length > 0) {
         logger?.warn("mcp_content_class_dropped", {
             entries: v.badContentOrigin,
-            allowed: CONTENT_ORIGIN_WORDS,
+            allowed: MCP_CONTENT_ORIGINS,
             note: "declaration DROPPED — these servers keep the pre-378 default (external content, session gets marked); the servers themselves still mount",
         });
     }
@@ -269,6 +359,18 @@ function classifyHonored(baseline, entries, config, logger, storedToolAxes) {
             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",
         });
     }
+    for (const t of v.transportLost) {
+        if (!mounted.has(t.server))
+            continue;
+        logger?.warn("mcp_transport_members_dropped", {
+            server: t.server,
+            lost: t.lost.slice(0, MAX_KEY_ECHO),
+            ...(t.lost.length > MAX_KEY_ECHO ? { lostTotal: t.lost.length } : {}),
+            note: "this replayed request carries parts of this server's transport declaration that cannot be handed to the engine — an env / headers record that is not a plain object of string values (left out whole, as the pre-upgrade server read it), " +
+                "a member named \"__proto__\" in env / headers (only that member is left out: the engine refuses the name), args that are not a list of strings, a principalHeader that is not a string; " +
+                "the server mounts with the rest. A new submission with the same entry is refused (400)",
+        });
+    }
     return {
         mcp: mergeRequestMcp(baseline, v.ok.map(toCoreMcpServerSpec), reservedNames),
         drops: [...v.dropped, ...blocked.map((server) => ({ server, reason: "name_reserved_by_deployment" }))],