@sema-agent/client-core 0.41.0 → 0.43.0

package/dist/model/catalogLoader.js

@@ -234,10 +234,41 @@ export async function loadCatalogWithSources(opts) {
     const timeoutMs = opts?.timeoutMs ?? DEFAULT_CATALOG_TIMEOUT_MS;
     const attempts = [];
     const warnings = [];
-    let hit = null;
     let lastDialed;
+    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
+    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
+    // 校验与合并是它的活,两边不重叠也不互相重写。
+    const resolveWith = async (p) => {
+        const onlineUrl = p?.url ?? lastDialed ?? sources[0];
+        const resolveOpts = {
+            ...(onlineUrl !== undefined ? { onlineUrl } : {}),
+            fetchJson: async () => {
+                if (p === null)
+                    throw new Error(`all ${sources.length} catalog source(s) failed; see attempts[]`);
+                return p.doc;
+            },
+            ...(opts?.overrides !== undefined ? { overrides: opts.overrides } : {}),
+            ...(opts?.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+        };
+        return resolveModelCatalog(resolveOpts);
+    };
+    // ══ 🔴 [4982] 候选② 的**同形存量**(0.42.0 异源复审 [high] 采纳)══════════════════════════
+    //
+    // 病根与「缓存腿从没被问过」是**同一条**:候选链的停止判据锚在**传输层**(`hit !== null`)而不是
+    // **内容判决**。后果比缓存那一格更重 —— 首源发得下来但内容不合格时,`break` 让**后续健康源
+    // 永远不会被请求**:一次坏发布、或一个 CDN 的半更新窗,就能把整条后备链压掉。
+    // ⇒ 停止判据换成 `accepted !== null`(内容判决),逐源「传输 → 旁签 → **内容校验**」,
+    //   只有真被接受的那一份才停链。
+    //
+    // 🔴 `rejected` 是**诚实兜底**不是备选源:全链都被拒时,拿**第一份被拒的**去出结果,
+    //    这样 `online.reason` 说的是真话(`schema-version-unsupported`),而不是退成
+    //    「一个源都没连上」(`fetch-failed`)—— 那会把「内容坏了」谎报成「网络坏了」。
+    //    它**绝不**参与「用哪份目录」的竞争:被拒就是被拒,`online.ok === false` 时合并结果本就
+    //    回落内置表。
+    let accepted = null;
+    let rejected = null;
     for (const src of sources) {
-        if (hit !== null)
+        if (accepted !== null)
             break;
         const got = await guardedGet(src, allowedHosts, fetchImpl, timeoutMs);
         if (got.outcome !== 'insecure-url' && got.outcome !== 'host-not-allowed')
@@ -289,7 +320,17 @@ export async function loadCatalogWithSources(opts) {
             warnings.push(`catalog sha256 sidecar unavailable for ${finalUrl} (${shaGot.outcome}) — payload accepted without the checksum`);
         }
         attempts.push({ url: src, outcome: 'ok', ...(got.status !== undefined ? { status: got.status } : {}), shaChecked });
-        hit = { url: finalUrl, doc, raw: got.text, shaChecked };
+        const candidate = { url: finalUrl, doc, raw: got.text, shaChecked };
+        // 内容判决就在这里做 —— 传输成功**不等于**这份目录能用。
+        const verdict = await resolveWith(candidate);
+        if (verdict.online.ok) {
+            accepted = { hit: candidate, base: verdict };
+            continue;
+        }
+        if (rejected === null)
+            rejected = { hit: candidate, base: verdict };
+        warnings.push(`catalog source ${finalUrl} was fetched but REJECTED by content validation ` +
+            `(${verdict.online.reason ?? 'unknown'}) — trying the next source`);
     }
     // ── 缓存腿(口缺席 ⇒ 整条不启用,cacheHit 键缺席)────────────────────────────────────────
     const cache = opts?.cache;
@@ -297,7 +338,15 @@ export async function loadCatalogWithSources(opts) {
     let cacheHit = cache !== undefined ? false : undefined;
     let cacheStale;
     let cachedSourceUrl;
-    if (hit === null && cache !== undefined && cachePath !== undefined) {
+    /**
+     * 读一次缓存信封 → `SourceHit`(+ 陈旧判)。**永不抛**;坏形/缺件记 warn 返 null。
+     * 🔴 [4982] 候选②(0.42.0)提出来的:此前这段是内联的,只有「传输全败」那一条路走得到它。
+     *    现在有**两个**调用点(传输全败 / 传输 ok 但内容被拒),提成一处才不会有两份读法。
+     *    `alreadyWarned` = 第二次调用时不重复堆同一批 warn(同一份坏缓存说两遍是噪音)。
+     */
+    const readCachedHit = async (alreadyWarned) => {
+        if (cache === undefined || cachePath === undefined)
+            return null;
         let text = null;
         let readError;
         try {
@@ -306,52 +355,109 @@ export async function loadCatalogWithSources(opts) {
         catch (e) {
             readError = shortError(e);
         }
-        if (readError !== undefined)
+        if (readError !== undefined && !alreadyWarned)
             warnings.push(`catalog cache read failed: ${readError}`);
-        if (typeof text === 'string' && text.length > 0) {
-            let env;
-            let envError;
-            try {
-                env = JSON.parse(text);
-            }
-            catch (e) {
-                envError = shortError(e);
-            }
-            if (envError !== undefined)
+        if (typeof text !== 'string' || text.length === 0)
+            return null;
+        let env;
+        let envError;
+        try {
+            env = JSON.parse(text);
+        }
+        catch (e) {
+            envError = shortError(e);
+        }
+        if (envError !== undefined) {
+            if (!alreadyWarned)
                 warnings.push(`catalog cache is not parsable JSON (ignored): ${envError}`);
-            const doc = env?.catalog;
-            const url = env?.sourceUrl;
-            if (doc !== undefined && typeof url === 'string' && url.length > 0) {
-                // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
-                // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
-                hit = { url, doc, raw: text, shaChecked: false };
-                cacheHit = true;
-                cachedSourceUrl = url;
-                if (opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number') {
-                    cacheStale = opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS;
-                }
-            }
-            else if (envError === undefined) {
+            return null;
+        }
+        const doc = env?.catalog;
+        const url = env?.sourceUrl;
+        if (doc === undefined || typeof url !== 'string' || url.length === 0) {
+            if (!alreadyWarned)
                 warnings.push('catalog cache envelope missing sourceUrl/catalog (ignored)');
-            }
+            return null;
         }
-    }
-    // ── 委托:载荷判决 / 三层合并 / 来源标注全在 resolveModelCatalog ──────────────────────────
-    // 传给它的 `fetchJson` 只是「把已经拿到的这一份交出去」的闭包 —— 候选链与传输门是本文件的活,
-    // 校验与合并是它的活,两边不重叠也不互相重写。
-    const payload = hit;
-    const onlineUrl = payload?.url ?? lastDialed ?? sources[0];
-    const resolveOpts = {
-        ...(onlineUrl !== undefined ? { onlineUrl } : {}),
-        fetchJson: async () => {
-            if (payload === null)
-                throw new Error(`all ${sources.length} catalog source(s) failed; see attempts[]`);
-            return payload.doc;
-        },
-        ...(opts?.overrides !== undefined ? { overrides: opts.overrides } : {}),
-        ...(opts?.nowMs !== undefined ? { nowMs: opts.nowMs } : {}),
+        // 缓存里那份**就是**当初的线上载荷 —— 照样过 validateOnlineCatalog(下面同一条路),
+        // 不给它开后门:一份当年合法、今天已超区间的文档必须照样被拒。
+        const stale = opts?.nowMs !== undefined && typeof env?.fetchedAt === 'number'
+            ? opts.nowMs - env.fetchedAt > CATALOG_CACHE_STALE_MS
+            : undefined;
+        return {
+            hit: { url, doc, raw: text, shaChecked: false },
+            ...(stale !== undefined ? { stale } : {}),
+        };
     };
-    const base = await resolveModelCatalog(resolveOpts);
+    // ══ 缓存腿:**内容判决**缺席时才问它(传输全败 与 内容被拒 两条路共用这一格)═══════════════
+    //
+    // 🔴 [4982] 候选②(P0-KPI,0.42.0):此前这条腿的门槛是 `hit === null`,而 `hit` 只记录**传输层**
+    //    结果(200 + 旁签过就算 hit)。于是「线上目录发得下来、但内容被 validateOnlineCatalog 拒」
+    //    这条缝里,loader 认为「有 hit」⇒ **永不查缓存**(即便缓存里躺着一份上次真正被接受过的
+    //    合法目录),用户只拿到内置精简表;而 `cacheHit:false` 这个**诚实位反过来说谎** —— 它读起来
+    //    是「没有缓存」,真相是「有缓存,但从头到尾没人问过它」。
+    //    判据锚在**真正决定结果的量**上:决定「用不用得上目录」的是**内容判决**(`accepted`),
+    //    不是传输判决(`hit !== null`)。异源复审 [high] 之后,候选链的停止判据也换成了同一个量
+    //    (见上方 `accepted` 头注)—— 两处同根同治,不留同形存量。
+    // 🔴 缓存那份**不开后门**:它照样过同一个 `resolveModelCatalog`。也被拒时**不拿它顶替**
+    //    (一份同样不合格的文档顶替不了什么),`cacheHit` 诚实留在 `false` —— 本位的语义是
+    //    「这次的目录**是从缓存来的**」,不是「问过缓存」;抬成 true 会让「缓存救场了」与
+    //    「缓存也坏了」在读数上不可分。「问过但没用上」那件事由 warning 说。
+    /**
+     * 线上腿的**归因汇总**(异源复审 [medium] 采纳,0.42.0)。
+     *
+     * 🔴 修的是一句会指错方向的话:此前只要**任一**源产生 `rejected`,回落 warning 就写
+     *    「every online catalog source was fetched but REJECTED」。而其余源完全可能是网络失败、
+     *    畸形 JSON、sha 不匹配、或被域白名单挡下 —— 把一次 CDN/网络事故说成「目录发布损坏」,
+     *    运维会照着错误方向查,恢复时间平白变长。
+     * ⇒ 按 `attempts` 的**真实计数**分两类措辞:全部进过内容校验且全被拒 ⇒ 说 "every … REJECTED";
+     *   混合故障 ⇒ 逐类报数,并保留内容拒绝的 reason。
+     */
+    const onlineLegSummary = () => {
+        const contentRejected = attempts.filter((a) => a.outcome === 'ok').length;
+        const otherFailures = attempts.length - contentRejected;
+        const reason = rejected?.base.online.reason ?? 'unknown';
+        if (otherFailures === 0 && contentRejected > 0) {
+            return `every online catalog source (${contentRejected}) was fetched but REJECTED by content validation (${reason})`;
+        }
+        return (`the online catalog leg failed in more than one way: ${contentRejected} source(s) were fetched but ` +
+            `REJECTED by content validation (${reason}), ${otherFailures} source(s) failed before content ` +
+            'validation (transport / integrity / policy — see attempts[])');
+    };
+    let cached = null;
+    if (accepted === null)
+        cached = await readCachedHit(false);
+    let payload;
+    let base;
+    if (accepted !== null) {
+        payload = accepted.hit;
+        base = accepted.base;
+    }
+    else if (cached !== null) {
+        const fromCache = await resolveWith(cached.hit);
+        if (fromCache.online.ok) {
+            payload = cached.hit;
+            base = fromCache;
+            cacheHit = true;
+            cachedSourceUrl = cached.hit.url;
+            if (cached.stale !== undefined)
+                cacheStale = cached.stale;
+            if (rejected !== null)
+                warnings.push(`${onlineLegSummary()} — fell back to the cached catalog (${cached.hit.url})`);
+        }
+        else {
+            // 缓存那份也不合格 ⇒ 诚实回落:`online` 报的仍是**线上腿自己**的判词(有被拒的那一份就用
+            // 它的,一个都没连上就是 fetch-failed),绝不拿缓存的判词冒充线上的。
+            payload = rejected?.hit ?? null;
+            base = rejected?.base ?? (await resolveWith(null));
+            warnings.push(`${onlineLegSummary()}, and the cached catalog was rejected by content validation too — ` +
+                'falling back to the built-in table');
+        }
+    }
+    else {
+        payload = rejected?.hit ?? null;
+        base = rejected?.base ?? (await resolveWith(null));
+    }
     // 线上腿真的被接受了才写缓存(被 validateOnlineCatalog 拒掉的载荷绝不进缓存 ——
     // 否则下一次断网时我们会把一份已知不合格的文档当兜底)。
     if (base.online.ok && payload !== null && cacheHit !== true && cache !== undefined && cachePath !== undefined) {

package/dist/printToolResultFrame.d.ts

@@ -86,6 +86,25 @@ export interface ToolEndResultArmLike {
     settledBy?: unknown;
     /** 见 {@link settledBy} —— 两键同批同源(#263 半场,0.30.8),合读、缺席不反推、转录不是认证。 */
     approver?: unknown;
+    /**
+     * 这次 deny **是哪一条拒绝臂**(core ≥5.35 `AskDenyResolution`;A-D2 半场,0.42.0)——
+     * `human_refused` / `window_expired` / `no_approver` / `blanket_allow_refused` /
+     * `approver_unavailable` / `task_aborted` / `presentation_failed` / `approver_error` /
+     * `approver_contract`。
+     *
+     * 🔴 与 {@link settledBy} **合读而不互替**:settledBy 只说「这次等待是哪一**种**收场」,本位
+     * 分类的是**拒绝臂本身**。单锚 settledBy 会把「审批方违约」(approver 回了契约外的东西)
+     * 那一臂一起误收进「窗口走完了」。
+     * 🔴 **判据用正面匹配,不用「不等于」**(异源复审 [medium] 采纳,0.42.0):要判「审批窗口自己
+     * 走完了」,写 `settledBy === 'timeout' && resolution === 'window_expired'`。
+     * **绝不**写 `resolution !== 'approver_contract'` —— 那个不等式对**缺席**(旧引擎不发这一位)和
+     * 对**任何未来新码**都为真,于是「不知道是怎么拒的」会被折成「窗口自然结束」,正是本位存在要防的
+     * 那件事;两条正交轴在那种写法里被一个否定比较替代掉了。缺席与未知值一律进 `default` 分支。
+     * 🔴 **缺席不带语义,不许反推**:每一次真执行了的调用、每一次 policy/hook 直拒、以及
+     * durable/decide 腿的结算都不带这一位;缺席 ≠「不是拒绝」也 ≠「人拒的」。
+     * 🔴 本形同样是**防御性读形**(`unknown`):九词是引擎的闭集,消费方分支已知值 + 永远带 default。
+     */
+    resolution?: unknown;
     parentToolCallId?: unknown;
     uuid?: unknown;
     session_id?: unknown;

package/dist/seatContract.d.ts

@@ -64,8 +64,32 @@
  * method exists (`start`/`stop`/`interrupt`/`sendMessage`/`onEvent`/`onToolPermissionRequest`/
  * `respondToToolPermission` are all real CC LocalSessions methods — see the 854-channel census).
  *
+ * ══ 🔴 证据等级标注:本文件的 CC 断言取自**桌面 unpack**,本地语料库不可复验 ════════════════
+ *
+ * (test [5087] 提出的「语料**种类**缺口」,cli [5088] 认领三件之①,随 0.42.0 落;判据形见下)
+ *
+ * 本文件里所有以「CC 如何如何」为形的断言 —— 上面那句「212 methods / 854-channel census /
+ * 方法名逐字保留」、下面 `checkLocalSessionEvent` 的「CC 的 `fQe` 逐字段对照」、以及一切引
+ * `.vite/build/index.chunk-*.js` 坐标的句子 —— **证据等级 = 桌面 unpack(CC Electron app 的
+ * `.vite/build` 产物),本地语料库不可复验**。
+ *
+ * 为什么这一条必须写在这里(而不是只写进台账):
+ *   · 本仓手边可复验的参照语料**只覆盖终端 CLI 形态**的静态产物,**没有**桌面壳的 unpack 产物。
+ *     这不是「语料版本旧」,是**产物形态不对** —— 拿 CLI 形态的语料去 grep 桌面壳里的符号只会得到
+ *     零命中,而零命中在这里**既不能证真也不能证伪**;
+ *   · 「CC 取证纪律」要求 CC 断言的合法证据只有两种:本机 claude 实测,或语料二进制直证。本文件
+ *     的这一批两种都够不着 ⇒ 断言**保留**(它当初是照着真产物写的),但**必须带着这个等级一起读**;
+ *   · 🔴 **这段注释随 `dist/*.d.ts` 出包**,三端读到的就是它。只把等级写进不进 tarball 的台账,
+ *     消费端读到的仍是一句看起来可复验、实际不可复验的断言(与本文件 `workerBadge` 出身订正
+ *     同一条理由)。
+ *
+ * **对下游的判据**:凡要对这些断言做「CC 到底是不是这样」的复核,**别拿终端 CLI 形态的语料当反证**
+ * ——零命中是语料形态缺口的必然结果,不是断言错。真正的复核路只有一条:取一份 CC 桌面版
+ * unpack 产物再对照(已在册为独立小件,做成后参照语料库增桌面形态子目录)。
+ *
  * Event payload contract: ported in FORM from CC's `onEvent` runtime validator `fQe`
- * (unpack `.vite/build/index.chunk-CnWKsyE_.js:369773`). The load-bearing property we keep
+ * (unpack `.vite/build/index.chunk-CnWKsyE_.js:369773`;**证据等级:桌面 unpack,本地语料库
+ * 不可复验** —— 见上方标注段). The load-bearing property we keep
  * byte-faithful ([1832] axiom 2, independently proven by CC's own code): on an otherwise
  * fully-schema'd IPC surface, the `message`/`messages` fields (= CC session-vocabulary SDKMessage
  * bodies, our transcript plane) are UNVALIDATED passthrough positions, while every other field is a

package/dist/seatContract.js

@@ -64,8 +64,32 @@
  * method exists (`start`/`stop`/`interrupt`/`sendMessage`/`onEvent`/`onToolPermissionRequest`/
  * `respondToToolPermission` are all real CC LocalSessions methods — see the 854-channel census).
  *
+ * ══ 🔴 证据等级标注:本文件的 CC 断言取自**桌面 unpack**,本地语料库不可复验 ════════════════
+ *
+ * (test [5087] 提出的「语料**种类**缺口」,cli [5088] 认领三件之①,随 0.42.0 落;判据形见下)
+ *
+ * 本文件里所有以「CC 如何如何」为形的断言 —— 上面那句「212 methods / 854-channel census /
+ * 方法名逐字保留」、下面 `checkLocalSessionEvent` 的「CC 的 `fQe` 逐字段对照」、以及一切引
+ * `.vite/build/index.chunk-*.js` 坐标的句子 —— **证据等级 = 桌面 unpack(CC Electron app 的
+ * `.vite/build` 产物),本地语料库不可复验**。
+ *
+ * 为什么这一条必须写在这里(而不是只写进台账):
+ *   · 本仓手边可复验的参照语料**只覆盖终端 CLI 形态**的静态产物,**没有**桌面壳的 unpack 产物。
+ *     这不是「语料版本旧」,是**产物形态不对** —— 拿 CLI 形态的语料去 grep 桌面壳里的符号只会得到
+ *     零命中,而零命中在这里**既不能证真也不能证伪**;
+ *   · 「CC 取证纪律」要求 CC 断言的合法证据只有两种:本机 claude 实测,或语料二进制直证。本文件
+ *     的这一批两种都够不着 ⇒ 断言**保留**(它当初是照着真产物写的),但**必须带着这个等级一起读**;
+ *   · 🔴 **这段注释随 `dist/*.d.ts` 出包**,三端读到的就是它。只把等级写进不进 tarball 的台账,
+ *     消费端读到的仍是一句看起来可复验、实际不可复验的断言(与本文件 `workerBadge` 出身订正
+ *     同一条理由)。
+ *
+ * **对下游的判据**:凡要对这些断言做「CC 到底是不是这样」的复核,**别拿终端 CLI 形态的语料当反证**
+ * ——零命中是语料形态缺口的必然结果,不是断言错。真正的复核路只有一条:取一份 CC 桌面版
+ * unpack 产物再对照(已在册为独立小件,做成后参照语料库增桌面形态子目录)。
+ *
  * Event payload contract: ported in FORM from CC's `onEvent` runtime validator `fQe`
- * (unpack `.vite/build/index.chunk-CnWKsyE_.js:369773`). The load-bearing property we keep
+ * (unpack `.vite/build/index.chunk-CnWKsyE_.js:369773`;**证据等级:桌面 unpack,本地语料库
+ * 不可复验** —— 见上方标注段). The load-bearing property we keep
  * byte-faithful ([1832] axiom 2, independently proven by CC's own code): on an otherwise
  * fully-schema'd IPC surface, the `message`/`messages` fields (= CC session-vocabulary SDKMessage
  * bodies, our transcript plane) are UNVALIDATED passthrough positions, while every other field is a
@@ -370,7 +394,10 @@ const checkSeatChromeEnvelope = (v, field) => {
 };
 /**
  * onEvent payload validator — line-for-line FORM port of CC's `fQe`
- * (`.vite/build/index.chunk-CnWKsyE_.js:369773`). Field-by-field mapping:
+ * (`.vite/build/index.chunk-CnWKsyE_.js:369773`)。
+ * 🔴 **证据等级:桌面 unpack,本地语料库不可复验**(0.42.0 标注件,判据与复核路见文件头注的
+ *    「证据等级标注」段;下面每一条 `CC …` 对照句都受该等级约束)。
+ * Field-by-field mapping:
  *  - `type`/`sessionId`: required strings (same);`type` 另加闭集成员校验(REF-CC-065,词由本宿主铸);
  *  - `message`: CC's minified source reads `typeof e.message<"u"` inside a comma expression whose
  *    value is discarded — i.e. NO validation, a deliberate transcript-plane passthrough. Same here.