@sema-agent/settings-schema 14.6.0 → 14.7.0

package/dist/mcp-request-entry.js

@@ -24,68 +24,80 @@
  * (语义逐字搬),是一项已知待收的分歧。
  */
 import { echoCallerText } from "./caller-text-echo.js";
-import { captureStringArray, dataDescriptor } from "./definition-copy.js";
-import { isPlainJsonObject, jsonShapeOf } from "./plain-json-object.js";
+import { UNINSPECTABLE, captureStringArray, dataDescriptor, inspect, ownEntriesOf, ownFieldsOf, ownValueOf, readKey } from "./own-key-read.js";
+import { isJsonArray, isPlainJsonObject, jsonShapeOf } from "./plain-json-object.js";
 import { MCP_CONTENT_ORIGINS } from "./types.js";
 import { startsWithHttpScheme } from "./url-shape.js";
 // ── 值的种类描述(拒句只说「你写的是什么形」,不回显值:值可能带凭据、可能任意长)──────────────────────────────────────
-/** 撤销 / 读不出的 Proxy 的拒句(`got ` 之后的名词短语)—— **全包唯一的一句**:`Array.isArray` 对已撤销的 Proxy 抛 `TypeError`,陷阱抛出来也一样,读器与描述器都不能因此被带出去。 */
-const UNINSPECTABLE = "an object that could not be inspected (a proxy trap threw)";
-/**
- * 唯一的**安全检视内核**:读器与描述器要碰不可信的值(`Array.isArray` 对已撤销的 Proxy 抛、`get` / 原型陷阱抛、会抛的自有 getter)都经它 ——
- * 「检视不了」的**律与句都单源**:抛了 ⇒ `ok:false` 带 {@link UNINSPECTABLE} 那一句,不再各处各包一个 try、各写一句。
- */
-function inspect(read) {
-    try {
-        return { ok: true, value: read() };
-    }
-    catch {
-        return { ok: false, sentence: UNINSPECTABLE };
+/** 值的**种类词**(不回显值本身):`null` / `array` / `typeof` 词(`object` / `function` / `string` …);读不出的对象 ⇒ 全包唯一的那一句。形状只问座位(总,不抛):两只坏值描述器共用这一只。 */
+function describeKindWord(v) {
+    const shape = jsonShapeOf(v);
+    switch (shape) {
+        case "null":
+            return "null";
+        case "array":
+            return "array";
+        case "uninspectable":
+            return UNINSPECTABLE;
+        case "plain":
+        case "non_plain_object":
+        case "primitive":
+            return typeof v;
+        default: {
+            const unhandled = shape;
+            throw new Error(`describeKindWord: unhandled shape ${String(unhandled)}`);
+        }
     }
 }
-/** 三只描述器的壳:检视抛了就说「检视不了」那一句(经 {@link inspect})。 */
-function inspectSafely(describe) {
-    const read = inspect(describe);
-    return read.ok ? read.value : read.sentence;
-}
-/** 值的**种类**(不回显值本身)。总(不抛):经 {@link inspectSafely}。 */
+/** 值的**种类**(不回显值本身)。总(不抛):形状只问座位,读不出的对象说全包唯一的「检视不了」那一句。 */
 export function describeValueShape(v) {
-    return inspectSafely(() => {
-        if (v === undefined)
-            return "nothing (the key is absent)";
-        if (v === null)
+    if (v === undefined)
+        return "nothing (the key is absent)";
+    const shape = jsonShapeOf(v);
+    switch (shape) {
+        case "null":
             return "null";
-        if (Array.isArray(v))
+        case "array":
             return "an array";
-        if (typeof v === "string")
-            return v.length === 0 ? "an empty string" : `a string of ${v.length} characters`;
-        if (typeof v === "object")
-            return "an object";
-        return `a ${typeof v}`;
-    });
+        case "uninspectable":
+            return UNINSPECTABLE;
+        case "plain":
+        case "non_plain_object":
+            return typeof v === "function" ? "a function" : "an object";
+        case "primitive":
+            return typeof v === "string" ? (v.length === 0 ? "an empty string" : `a string of ${v.length} characters`) : `a ${typeof v}`;
+        default: {
+            const unhandled = shape;
+            throw new Error(`describeValueShape: unhandled shape ${String(unhandled)}`);
+        }
+    }
 }
-/** 「不是字符串数组」的种类:数组里混了非串元素说那一句,否则回落到 {@link describeValueShape}。总(不抛):经 {@link inspectSafely}。 */
+/** 「不是字符串数组」的种类:数组里混了非串元素说那一句,否则回落到 {@link describeValueShape}。总(不抛):`isJsonArray` 是座位的总版。 */
 export function describeNotStringArray(v) {
-    return inspectSafely(() => (Array.isArray(v) ? "an array with a non-string element" : describeValueShape(v)));
+    return isJsonArray(v) ? "an array with a non-string element" : describeValueShape(v);
 }
-/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。总(不抛):经 {@link inspectSafely}。 */
+/** 「不是字符串值的对象」的种类:对象里混了非串值说那一句,否则回落到 {@link describeValueShape}。总(不抛)。 */
 export function describeNotStringRecord(v) {
-    return inspectSafely(() => (isPlainJsonObject(v) ? "an object with a non-string value" : describeValueShape(v)));
+    return isPlainJsonObject(v) ? "an object with a non-string value" : describeValueShape(v);
 }
 /**
- * 字符串数组(空数组合法)。与传输读器读 `args` 是**同一只读法**(`./definition-copy` 的 `captureStringArray`:按下标、自有下标、一次读、非串即坏、不走迭代协议):
- * 稀疏数组(洞)、`length` 读不出安全非负整数的数组、读元素时抛的数组都不是 —— 洞不顺原型链读到 `Object.prototype` / `Array.prototype` 上的数字键。
+ * 字符串数组(空数组合法)—— 类型守卫,所以按 `./own-key-read` 的 `captureStringArray` 的**严归类**读(整容器读,自有下标各一份描述符,非串即坏、不走迭代协议):
+ * 下标是访问器或不可枚举的数组不是(getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份);稀疏数组(洞)、`length` 读不出安全非负整数的数组、
+ * 读不出的数组都不是 —— 洞不顺原型链读到 `Object.prototype` / `Array.prototype` 上的数字键。传输读器读 `args` 交出去的是副本,用同一只函数的宽归类。
  */
 export function isStringArray(v) {
-    return captureStringArray(v) !== undefined;
+    return captureStringArray(v, "strict") !== undefined;
 }
 /**
- * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)。与传输读器读 `env` / `headers` 是**同一个**定义
- * ({@link readPlainStringRecord}):包内没有第二把更宽的尺。
+ * 纯数据的「名 → 串」记录(空对象合法;数组、`Map`、类实例、自有 `__proto__` 成员、有非串成员的对象都不是)—— 类型守卫,所以是**严归类**:成员经内核的
+ * `ownEntriesOf` 读(整容器读的严归类:每个自有串键一份描述符;访问器成员或不可枚举的成员 ⇒ 不是,getter 一次都不调 —— 守卫为真,调用方随后的普通读读到的就是判过的那一份)。
+ * 传输读器读 `env` / `headers`({@link readPlainStringRecord})交出去的是**副本**,按宽归类读(不可枚举的成员照读、访问器调一次);值与成员名的判据(是串、不叫 `__proto__`)两边同一条。
  */
 export function isStringRecord(v) {
-    const read = readPlainStringRecord(v);
-    return read.ok && !read.reservedMember;
+    if (!isPlainJsonObject(v))
+        return false;
+    const entries = ownEntriesOf(v);
+    return entries.ok && entries.value.every(([name, value]) => name !== RESERVED_MEMBER_NAME && typeof value === "string");
 }
 // ── 调用方写的串的回显口径 ──────────────────────────────────────────────────────────────────────────
 /** 句子里点名一个值的写法:{@link echoCallerText} 外加一对双引号;内部的引号与反斜杠逐字(不转义)。 */
@@ -115,7 +127,7 @@ export function isUsableWireName(v) {
  */
 export function describeBadWireName(v) {
     if (typeof v !== "string")
-        return v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+        return describeKindWord(v);
     if (v.length === 0)
         return "empty";
     const head = quotedCallerText(v);
@@ -135,7 +147,7 @@ export function isContentOriginWord(v) {
 }
 /** 坏内容出处值的**可打印**摘要:串 ⇒ 引号形的回显({@link quotedCallerText}:剥控制与双向字符、截 64 字);非串只说种类。 */
 export function describeBadContentOrigin(v) {
-    return typeof v === "string" ? quotedCallerText(v) : v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+    return typeof v === "string" ? quotedCallerText(v) : describeKindWord(v);
 }
 // ── 两个身份头 ──────────────────────────────────────────────────────────────────────────────────────
 /**
@@ -155,35 +167,35 @@ export function readMcpIdentityHeaders(transport) {
 /**
  * 两个身份头的**唯一读法**(公开读者与传输快照共用):只有 `principalHeader` **干净地读成缺席**时才读 `assertionHeader`;`principalHeader` 在场(不论值形)⇒ `assertionHeader` 一次不读;
  * 任何一个读不出 ⇒ 整体读不出(`ok:false`,向上传),不折成 `undefined` —— 不然「principal 读不出」会落到 assertion、读它的 getter。
+ * **只读自有键**(身份只认自有键):键只靠继承可见(含 `Object.prototype` 被污染成数据值)⇒ 不读它的值、当缺席,但**记下**(`principalInherited` / `assertionInherited`)—— 传输读器据此点名,
+ * 身份轴上不静默;公开读者没有 `lost` 通道,只读值。
  */
 function identityFieldsOf(record) {
-    const principal = ownValueOf(record, "principalHeader");
-    if (!principal.ok)
-        return principal;
-    if (principal.value !== undefined)
-        return { ok: true, value: { principalHeader: principal.value, assertionHeader: undefined } };
-    const assertion = ownValueOf(record, "assertionHeader");
-    if (!assertion.ok)
-        return assertion;
-    return { ok: true, value: { principalHeader: undefined, assertionHeader: assertion.value } };
-}
-/** 一个字段的值,**只读自有属性**(`Object.hasOwn`):原型链上的值 / 被污染的 getter 一律当缺席。**自身就是守护读**(经 `inspect`):`getOwnPropertyDescriptor` 陷阱抛、会抛的自有 getter、
- *  已撤销的 Proxy ⇒ `ok:false`(读不出),调用方各自决定怎么办、不再各包一层。 */
-function ownValueOf(record, key) {
-    return inspect(() => (Object.hasOwn(record, key) ? record[key] : undefined));
-}
-/** 按顺序读若干字段,**第一个读不出的就停**(后面的一个不读),整体读不出向上传。 */
-function ownFieldsOf(record, keys) {
-    const out = Object.create(null);
-    for (const key of keys) {
-        const read = ownValueOf(record, key);
-        if (!read.ok)
-            return read;
-        Object.defineProperty(out, key, dataDescriptor(read.value));
+    const principal = readKey(record, "principalHeader");
+    if (principal.presence === "unreadable")
+        return { ok: false, sentence: UNINSPECTABLE };
+    if (principal.presence === "own" && principal.value !== undefined) {
+        return { ok: true, value: { principalHeader: principal.value, assertionHeader: undefined, principalInherited: false, assertionInherited: false } };
     }
-    return { ok: true, value: out };
+    const assertion = readKey(record, "assertionHeader");
+    if (assertion.presence === "unreadable")
+        return { ok: false, sentence: UNINSPECTABLE };
+    return {
+        ok: true,
+        value: {
+            principalHeader: undefined,
+            assertionHeader: assertion.presence === "own" ? assertion.value : undefined,
+            principalInherited: principal.presence === "inherited",
+            assertionInherited: assertion.presence === "inherited",
+        },
+    };
 }
 const transportBad = (path, reason) => ({ ok: false, issue: { path, reason } });
+/** 身份头只靠继承可见时的 `lost` 条目:不读它的值,但点名(身份轴不静默;句子不回显值)。机读位不带(`fault` 的闭集不为它加词)。 */
+const inheritedIdentityIssue = (key) => ({
+    path: `transport.${key}`,
+    reason: "inherited key ignored (the key is visible only through the prototype chain; a transport's identity headers are read from its own keys)",
+});
 /**
  * 请求面 `transport` 的**唯一读器**:读器投影 transport 用它,发送前 / 受理时的判形读它报的 `lost` —— 同一只函数两个消费点,「读器丢了什么」与「门拒什么」不可能分岔。
  *  · 硬坏形(`transport` 不是对象 / `kind` 出闭集 / stdio 缺 `command` / http 的 `url` 不是 http(s))⇒ `ok:false`,`path` 是读器点名的键路径;
@@ -214,7 +226,7 @@ export function readRequestMcpTransport(t) {
         }
     }
     const tr = t;
-    // 字段只读一次:同一个检视里把「这一种传输要读的字段」读成局部快照(`get` 陷阱抛的 Proxy / 会抛的自有 getter ⇒ 整只不交,不抛),之后只读快照;这一种传输用不到的字段一次也不读
+    // 字段只读一次:经读内核把「这一种传输要读的字段」读成局部快照(描述符 / `has` 陷阱抛的 Proxy / 会抛的自有 getter ⇒ 整只不交,不抛;`get` 陷阱不被问),之后只读快照;这一种传输用不到的字段一次也不读
     const snapshotRead = snapshotTransport(tr);
     if (!snapshotRead.ok)
         return transportBad("transport", `must be an object with a "kind" of "stdio" or "http" — got ${snapshotRead.sentence}`);
@@ -225,7 +237,7 @@ export function readRequestMcpTransport(t) {
             if (typeof snap.command !== "string" || snap.command.length === 0)
                 return transportBad("transport.command", `must be a non-empty string (the command to run) — got ${describeValueShape(snap.command)}`);
             const rawArgs = snap.args; // 交出去的是副本(不是调用方数组的原引用),稀疏 / 读不出的数组整键丢、进 `lost`
-            const args = rawArgs === undefined ? undefined : captureStringArray(rawArgs);
+            const args = rawArgs === undefined ? undefined : captureStringArray(rawArgs, "wide");
             const argsIssue = rawArgs !== undefined && args === undefined ? { path: "transport.args", reason: `must be an array of strings — got ${describeNotStringArray(rawArgs)}` } : undefined;
             const env = readTransportRecord("transport.env", snap.env);
             return {
@@ -256,7 +268,7 @@ export function readRequestMcpTransport(t) {
                     ...(headers.record !== undefined ? { headers: headers.record } : {}),
                     ...ids,
                 },
-                lost: issuesOf(...headers.issues, principalIssue),
+                lost: issuesOf(...headers.issues, principalIssue, snap.principalInherited ? inheritedIdentityIssue("principalHeader") : undefined, snap.assertionInherited ? inheritedIdentityIssue("assertionHeader") : undefined),
             };
         }
         case "other":
@@ -286,7 +298,7 @@ function snapshotTransport(tr) {
         const ids = identityFieldsOf(tr);
         if (!ids.ok)
             return ids;
-        return { ok: true, value: { kind: "http", url: fields.value.url, headers: fields.value.headers, principalHeader: ids.value.principalHeader, assertionHeader: ids.value.assertionHeader } };
+        return { ok: true, value: { kind: "http", url: fields.value.url, headers: fields.value.headers, principalHeader: ids.value.principalHeader, assertionHeader: ids.value.assertionHeader, principalInherited: ids.value.principalInherited, assertionInherited: ids.value.assertionInherited } };
     }
     return { ok: true, value: { kind: "other", value: kind.value } };
 }
@@ -317,7 +329,7 @@ function notPlainDetail(shape, v) {
 }
 /**
  * 读一份「名 → 串」记录。记录交不交:是朴素 JSON 对象(座位的判据,见 `./plain-json-object`:原型是 `null`,或原型自己的原型是 `null`;纯数据 —— `Map`、`Set`、类实例、建在原型上的记录都不是),
- * 且每个成员的值都是串。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算 —— 引擎的收据按全部自有属性名读),值按属性描述读:数据属性取值,访问器调一次(访问器或描述 trap 抛了同判为坏)。
+ * 且每个成员的值都是串。成员 = `Object.getOwnPropertyNames` 的每一个名字(不可枚举的也算 —— 引擎的收据按全部自有属性名读),值经内核 `readKey` 读(一份描述符:数据属性取值,访问器调一次,不问 `get` 陷阱;访问器或描述 trap 抛了同判为坏)。
  * 读原型与成员名时代理 trap 抛了 ⇒ 整张不交(读器对调用方递来的任何对象都不抛;`JSON` 存体里不会有代理,这条只落在直接调读器的嵌入方身上)。
  * 交出去的是副本(原型 `Object.prototype`、成员全可枚举),调用方的对象不被交出去、也不被改;名叫 `__proto__` 的成员不进副本,`reservedMember` 记下它。
  * 名叫 `__proto__` 而值也坏的成员,句子一次说全两件事(名坏在前、值坏并列):调用方照值改完再撞第二条是两步才改对。
@@ -337,15 +349,10 @@ function readPlainStringRecord(v) {
     const members = Object.create(null);
     let reservedMember = false;
     for (const name of names) {
-        let value;
-        let unreadable = false;
-        try {
-            const d = Object.getOwnPropertyDescriptor(v, name);
-            value = d === undefined ? undefined : Object.hasOwn(d, "value") ? d.value : d.get === undefined ? undefined : Reflect.apply(d.get, v, []);
-        }
-        catch {
-            unreadable = true;
-        }
+        // 成员经内核读(契约见函数头注):一份描述符里取值 —— 数据属性取值、访问器调一次、从不问 Proxy 的 `get` 陷阱;成员在两次读之间被删掉 ⇒ 不是串(不读继承来的值)
+        const read = readKey(v, name);
+        const unreadable = read.presence === "unreadable";
+        const value = read.presence === "own" ? read.value : undefined;
         if (unreadable || typeof value !== "string") {
             const valueFault = unreadable ? "could not be read (its getter threw)" : `must be a string — got ${describeValueShape(value)}`;
             const reserved = name === RESERVED_MEMBER_NAME;