@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/engineCapsCache.js

@@ -1,106 +1,22 @@
-/**
- * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineCapsCache.ts 逐字搬入(零依赖;壳侧改 re-export)。
- * 🔴 **本批刻意不做「三套 caps 缓存收编成一套」**(设计稿 §2.4.1-B 风险点 + census §2.4):收编是
- * 行为改动,要单独一条测试与单独一批(B1 只搬现行为,不夹带)。selfKnowledge / sideChannel 的
- * 两套单键探测仍在壳侧,记账给下一批。
- */
-/**
- * engineCapsCache — 引擎 /v1/capabilities 的通用 boot-kick 缓存(同步读口)。
- *
- * selfKnowledge/sideChannel 各自有单键探测(先行件,语义已钉测试);本模块是后续键的通用面
- * (首个消费者:compactionModel,[1487]② server 1.243 接线的 cli 半场)。纪律同款:
- *   · kick 幂等(in-flight 去重),绝不 throw;
- *   · 判定固化;探测失败不缓存(引擎未起/瞬断 → 下次 kick 再判);
- *   · 同步读口 boolean(未判 = false = 调用方回落,version-safe)。
- * 与单键探测不同处:缓存整个 caps 对象(一次探测服务后续所有键),false 不设 TTL。
- *
- * 🔴 **失效口的由来**(#307 双扫 S25 勘误,2026-08-19)。本段此前自述「随每次
- * `createLiveConversationClient` 构造重 kick(引擎温切重启后新构造自然重探)」——**那句话不成立**:
- * {@link kickEngineCapsProbe} 首行就是 `capsByBase.has(baseUrl) ⇒ return`,而引擎温切
- * (respawn / restartEngine)重启后 baseUrl 常与重启前**一模一样**,于是「新构造」被这条幂等闸
- * 原样挡住,缓存里留的永远是**旧引擎**那一版的 caps。后果不是报错,是安静地按旧能力位走:
- * 新引擎新增的车道被判成「没有」(藏功能),旧引擎有而新引擎撤掉的车道被判成「有」(走死路)。
- * 此前除测试钩 {@link __resetEngineCapsCacheForTests} 外**没有任何生产失效路径**。
- * 修 = 显式失效口 {@link invalidateEngineCaps},由知道「引擎换人了」的那一层(壳的 respawn /
- * restartEngine)在重启后调用 —— 缓存自己无从分辨「同一个 baseUrl 后面还是不是同一个引擎」,
- * 猜(TTL / 每次构造清)只会把一个确定事实换成一个定时器。
- */
 const capsByBase = new Map();
 const inFlight = new Set();
-/**
- * in-flight 探测的 settle 载体(**带代际**;finally 只删自己那一条,engineCapsSettled 消费)。
- *
- * `superseded` = **代际变更信号**(对抗复审第四轮 [high] 采纳,2026-08-19):
- * {@link invalidateEngineCaps} 推进代际时 resolve 它,把等在**旧代际**上的调用方叫醒去重新求值,
- * 而不是让它们被吊在一个可能永不落地的旧探测上。叫醒**不等于放行** —— 醒来后仍走
- * {@link engineCapsSettled} 的循环:表里换上了新代际就接着等新探测,没换就按诚实缺席返回。
- */
 const settleByBase = new Map();
-/**
- * per-base **代际计数**(#307 S25 对抗复审 [high] 采纳,2026-08-19)。
- *
- * 为什么必须有:{@link invalidateEngineCaps} 清 `inFlight` 之后,同 base 立刻可以再 kick,于是
- * **两次探测并发跑在同一份无版本共享态上**。没有代际时的两个真后果(都发生在「重启撞上一次慢
- * capabilities 请求」这个恰恰最该正确的时刻):
- *   · 旧引擎那次探测**后**落地 ⇒ 它把 `capsByBase` 覆盖回**旧引擎**的能力位,失效等于没做;
- *   · 旧探测的 `finally` 删掉的是**新 run** 的 `inFlight`/`settleByBase` 条目 ⇒
- *     {@link engineCapsSettled} 提前 resolve(假「已落地」)+ 幂等闸被打开(重复探测)。
- * 代际 = 每个 run 出生时抓一份号,写缓存/清位之前核对「我这一号还是不是当代」——不是当代的 run
- * 只许**安静退场**,绝不许写、也绝不许清别人的位。号只增不减,`invalidate` 是唯一的推进者。
- */
 const genByBase = new Map();
-/** 该 base 的当代号(从没失效过 = 0)。 */
 function capsGeneration(baseUrl) {
     return genByBase.get(baseUrl) ?? 0;
 }
-/**
- * 该 base 的**当代号**(公面读口;0.60.0)。
- *
- * ── 它解决的是哪一件事(异源对抗复审 [medium] 采纳,真病)────────────────────────────────────
- * {@link kickEngineCapsProbe} 的代际闸挡的是「旧探测写脏 `capsByBase`」,而那道闸在 **probe 返回
- * 之后**才跑。宿主的 caps 探测闭包里通常还挂着若干**读面 tee**(`noteEngineCapsForSqlEngine` /
- * `noteEngineCapsForWriteProtection` …),它们是**在 probe 内部**、也就是在那道闸之前落地的 ⇒
- * 一次慢的旧探测可以在 `invalidateEngineCaps` + 新探测都走完之后才返回,把**上一台引擎**的读数
- * 重新写进那些 tee 表。屏面上的形态最坏:一行**肯定句**(「这台部署有 12 行写保护」)说的却是
- * 一台已经不在的引擎。
- *
- * ── 用法(宿主侧)──────────────────────────────────────────────────────────────────────────
- * 在**起探测的那一刻**抓一份号,tee 落地时原样交回:
- * ```ts
- * const gen = engineCapsGeneration(baseUrl)
- * kickEngineCapsProbe(baseUrl, async () => {
- *   const caps = await client.capabilities()
- *   noteEngineCapsForWriteProtection(baseUrl, caps, { generation: gen })   // 陈旧 ⇒ 这一发被丢掉
- *   return caps
- * })
- * ```
- * 🔴 **不传 = 与本位到货之前逐字节同行为**(照写),所以它是 additive 供给、不是强制门 —— 端没跟上
- * 之前不会有任何东西变坏,跟上之后那条竞态才真正关掉。
- * 🔴 **tee 自己抓号是假判据**:陈旧那一发在 tee 时读到的是**新**代号,看起来永远是当代的。
- *    号必须在**探测出生**那一刻抓。
- */
 export function engineCapsGeneration(baseUrl) {
     return capsGeneration(baseUrl);
 }
-/** 构造期 kick(async 幂等);probe = client.capabilities 薄闭包。 */
 export function kickEngineCapsProbe(baseUrl, probe) {
     if (!baseUrl || capsByBase.has(baseUrl) || inFlight.has(baseUrl))
         return;
-    // 出生代际:落地时拿它与当代号核对(见 genByBase 头注)。
     const gen = capsGeneration(baseUrl);
     inFlight.add(baseUrl);
     let wake = () => { };
     const superseded = new Promise((resolve) => {
         wake = () => resolve();
     });
-    // settle 位用**手工兑现**的 promise,而不是 IIFE 的返回值 —— 这样它能在**调用方代码跑起来之前**
-    // 就落位。
-    // 🔴 顺序是判据的一部分(对抗复审第五轮 [medium] 采纳,2026-08-19):`probe` 是**调用方给的
-    // 闭包**,它同步段里完全可以回头调 `invalidateEngineCaps(baseUrl, 替代探测)`(两参原子形正是
-    // 为温切设计的,而温切逻辑就住在这种回调里)。旧写法先跑 IIFE(= 先跑调用方代码)、后
-    // `settleByBase.set` ⇒ 嵌套 kick 装好的**新代际**条目当场被外层这一行覆盖回旧条目,随后旧 run 的
-    // finally 又把它删掉 ⇒ `engineCapsSettled` 在替代探测仍在途时返回,能力读口报 false/undefined。
-    // 先落位再调用方代码 = 重入时外层没有任何机会回头覆盖别人。
     let markSettled = () => { };
     const settled = new Promise((resolve) => {
         markSettled = () => resolve();
@@ -109,7 +25,6 @@ export function kickEngineCapsProbe(baseUrl, probe) {
     void (async () => {
         try {
             const caps = await probe();
-            // 🔴 被 invalidate 顶掉的旧 run 绝不写缓存 —— 它拿到的是**上一个引擎**的能力位。
             if (gen !== capsGeneration(baseUrl))
                 return;
             if (caps && typeof caps === 'object') {
@@ -117,45 +32,20 @@ export function kickEngineCapsProbe(baseUrl, probe) {
             }
         }
         catch {
-            // 失败不缓存:下次 kick 再判
         }
         finally {
-            // 幂等闸位只由**当代** run 归还;旧 run 归还会把新 run 的在途位抹掉(重复探测)。
             if (gen === capsGeneration(baseUrl)) {
                 inFlight.delete(baseUrl);
             }
-            // settle 位按代际认领:表里那条不是我这一代的(= 已被新 run 顶掉)就别动它,
-            // 否则 engineCapsSettled 会对着仍在跑的新探测提前 resolve。
             if (settleByBase.get(baseUrl)?.gen === gen)
                 settleByBase.delete(baseUrl);
             markSettled();
         }
     })();
 }
-/**
- * 0.26.0(#225 件1 配套,消费请托自领):等**当前这一次**探测落地(成功或失败都算落地)。
- * 无 in-flight ⇒ 立即 resolve —— 判据永远是缓存里的位({@link engineCapTrue}),不是本 promise;
- * 本函数只解决「kick 完只能盲猜轮询窗」的时序问题(慢响应被猜短的窗渲成「没有这条车道」)。
- * 绝不 reject(探测失败=位维持未判,调用方按缺席降级)。
- */
 export async function engineCapsSettled(baseUrl) {
     if (!baseUrl)
         return;
-    // 🔴 **跨代际接力**(#307 S25 对抗复审第二轮 [medium] 采纳,2026-08-19)。此前本函数抓住**一条**
-    // promise 就不再回头看:调用方 W 抓的是旧代际探测 P0,随后 {@link invalidateEngineCaps} 推进代际
-    // 并起了 P1 —— P0 先落地就把 W 放走,而 P0 已被代际闸挡住不许写缓存 ⇒ W 当场读到空缓存,把
-    // **新引擎的能力位当成缺席**。这正是本批要消灭的那类假缺席,只是搬到了 settle 面上。
-    // 修 = 每等完一条就**重新求值**表里的当代条目([loop-termination-requires-reevaluation]):
-    // 表里换上了更新代际的那条就改等它。代际严格递增 ⇒ 循环必然终止;每轮都真 await 一条 promise ⇒
-    // 不是忙等。
-    //
-    // 🔴 **等的是「这条探测落地」或「代际变了」两者先到者**(第四轮 [high] 采纳)。只等 promise 是
-    // 不够的:引擎重启恰恰是最容易把旧探测**吊死**的时刻(旧进程没了,那个 fetch 可能永远不返回),
-    // 于是「P0 挂死 ⇒ 两参原子失效已经起了 P1 且 P1 已经把新能力位写进缓存 ⇒ 而 invalidate 之前取件的
-    // 等待者仍永久卡在 P0 上」——缓存里明明是对的,等待者却永远拿不到。代际信号把它叫醒去重新求值。
-    // ⚠️ 叫醒 **不是** 放行:醒来后照走本循环 —— 表里换上了新代际(两参原子形保证同拍就在)就接着等
-    // 新探测;没换(单参形、调用方这一刻没有替代探测)才返回,那时判据回到缓存位本身 = 未判 =
-    // 诚实缺席。所以「被叫醒」既不会漏掉新引擎的位,也不会硬等一个可能永远不来的 kick。
     for (;;) {
         const entry = settleByBase.get(baseUrl);
         if (entry === undefined)
@@ -166,25 +56,16 @@ export async function engineCapsSettled(baseUrl) {
             entry.superseded,
         ]);
         const next = settleByBase.get(baseUrl);
-        // 表里没有**更新代际**的一条 ⇒ 没得再等了(当代要么已落地、要么根本没起新探测:
-        // 那种情况下判据回到缓存位本身 = 未判 = 诚实缺席,由调用方按缺席降级)。
         if (next === undefined || next.gen <= awaitedGen)
             return;
     }
 }
-/**
- * 同步读口(三态化):该 base 的 caps 里 key 的**可分辨**读数。语义逐条见 {@link EngineCapState}。
- *
- * `baseUrl` 缺席 ⇒ `unprobed`(没有 base 就没有任何一次探测,这不是「引擎说没有」)。
- */
 export function engineCapState(baseUrl, key) {
     if (!baseUrl)
         return 'unprobed';
     const caps = capsByBase.get(baseUrl);
     if (caps === undefined)
         return 'unprobed';
-    // 🔴 `in` 而不是 `!== undefined`:引擎显式发 `{"foo": undefined}` 在 JSON 上不可能,但本表也接
-    //    宿主注入的对象;`in` 问的是「键在不在」,正是 `absent` 这一档要答的问题。
     if (!(key in caps))
         return 'absent';
     const v = caps[key];
@@ -194,25 +75,9 @@ export function engineCapState(baseUrl, key) {
         return 'false';
     return 'non_boolean';
 }
-/** 同步读口:该 base 的 caps 里 key 是否字面 true(未判/缺键 = false)。
- *  🔴 **语义一字不变**(#318 件③ 三态化后改为经 {@link engineCapState} 单源实现):放行面读的就是
- *  这一口,四种「不知道」继续一律折成 `false` = fail-closed。要分辨成因请读 {@link engineCapState}。 */
 export function engineCapTrue(baseUrl, key) {
     return engineCapState(baseUrl, key) === 'true';
 }
-/**
- * 同步读口(**嵌套**布尔键):`caps[parentKey][key] === true`。未判/父键缺席/父键非对象(server 用
- * `false` 表示整族不供)/子键缺席/非 true ⇒ **false** = fail-closed,与 {@link engineCapTrue} 同规。
- *
- * 为什么要有它:`/v1/capabilities` 的一部分能力是**分组**发的,而不是全平铺 —— 例如 server 7.48.0 的
- * `fleet: { stream, sessionScope, observe, resume, bgNotifyFailClosed, steerPriority, hookFailureNotice }`
- * (`dist/http/routes/capabilities.js:52`),整族不供时该键**整个是 `false`** 而不是一个空对象。
- * 拿平铺口 {@link engineCapTrue} 去读这种键恒 false(白读),而白读的后果不是报错、是**安静地把新
- * 车道判成没有**(藏功能)—— 与本模块头注记的那次缓存失效事故同一种坏法。
- *
- * 🔴 `false` 父键与「父键在场但子键缺席」**都折 false**:两者对放行面是同一件事(这台引擎不供)。
- *    要分辨成因请自己读 caps 对象;本口只答放行问题。
- */
 export function engineCapNestedTrue(baseUrl, parentKey, key) {
     if (!baseUrl)
         return false;
@@ -221,20 +86,6 @@ export function engineCapNestedTrue(baseUrl, parentKey, key) {
         return false;
     return parent[key] === true;
 }
-/**
- * 同步读口(**任意值 / 嵌套对象**):该 base 的 caps 里 key 上到底有没有值,四态诚实作答。
- *
- * 为什么要有它:`engineCapTrue` / `engineCapNestedTrue` / `engineCapString` 三口的返回域分别是
- * `boolean` / `boolean` / `string|undefined` —— 它们**把四种「读不出」全折成 fail-closed 的一档**,
- * 那对**放行**问题是对的(能力位缺席就别走那条车道),但对**读面/诊断**问题是错的:一格
- * `sql: {engine,isolation,txnMode} | null`(server ≥7.60.0)用这三口读,`null`(这台部署确实没库)
- * 与「老引擎不报」与「还没探到」在屏上会变成同一句话。S-131 那次因此在**壳里**长出了一份窄读器
- * (归层债),本口是它在包侧的座位。
- *
- * 🔴 本口只答「有没有值」,**不答「值成不成形」** —— 后者归各能力位自己的窄读器
- *   (例:`sql` 的 {@link import("./sqlEngineCapability.js").projectSqlEngineCapability})。
- *   两层刻意分开:通用口不认识任何一个具体位的形,窄读器不该重新实现一遍缓存与代际。
- */
 export function engineCapValue(baseUrl, key) {
     if (!baseUrl)
         return { kind: 'unobserved' };
@@ -244,63 +95,18 @@ export function engineCapValue(baseUrl, key) {
     if (!(key in caps))
         return { kind: 'not_reported' };
     const v = caps[key];
-    // 🔴 `undefined` 与「键不在」同判 `not_reported`:JSON 上没有 `undefined` 这个值,一个显式
-    //    `undefined` 只可能来自宿主自建管线,把它读成「有值」会让下游拿到一个空手。
     if (v === undefined)
         return { kind: 'not_reported' };
     if (v === null)
         return { kind: 'null' };
     return { kind: 'value', value: v };
 }
-/**
- * 同步读口(字符串键):该 base 的 caps 里 key 的字符串值,未判/缺键/非字符串 ⇒ undefined。
- *
- * 首个消费者 = `hooksWireCaps` 的 `/goal` CC-Stop 语义判档,它要读 `capabilities.version`
- * (SDK `Capabilities.version`,server 侧 = `serviceVersion()`,与 `/health.version` 同源)。
- * 🔴 纪律同 {@link engineCapTrue}:**未判即 undefined**,调用方必须按「探不到 ⇒ 降级」处理 ——
- * 引擎能力位缺席时任何「假定它有」的分支都是对用户/模型的谎报。
- */
 export function engineCapString(baseUrl, key) {
     if (!baseUrl)
         return undefined;
     const v = capsByBase.get(baseUrl)?.[key];
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-/**
- * **生产失效口**(#307 双扫 S25,client-core 0.37.0):把该 base 的探测结果作废,
- * 使**下一次** {@link kickEngineCapsProbe} 真正重探(而不是被幂等闸原样挡回)。
- *
- * 消费方 = **知道「这个 baseUrl 后面换了一个引擎进程」的那一层**,目前唯一一处是壳的引擎温切:
- * cli `respawn` / `restartEngine` 成功后、重新构造 `createLiveConversationClient` **之前**调用。
- * 库这一层看到的只有一个字符串 base,分辨不出对面是不是同一个进程,所以失效必须由上面显式下达 ——
- * 见模块头注:靠 TTL 或「每次构造清」去猜,是把一个确定事实换成一个定时器。
- *
- * 语义与边界:
- *   · **推进代际**({@link genByBase}) + 清 `capsByBase`(已判结果) + 清 `inFlight`(在途去重位)。
- *   · **不 abort** 在途探测(没有可 abort 的把手,probe 是调用方给的薄闭包),改用代际让它
- *     **安静退场**:被顶掉的旧 run 落地后既不写缓存、也不归还任何位。所以本口在**探测在途时
- *     调用是安全的** —— 旧引擎那次响应绝不会覆盖新引擎的能力位(2026-08-19 对抗复审 [high])。
- *   · `settleByBase` **不清**:{@link engineCapsSettled} 的语义是「等**当前这一次**探测落地」,
- *     把在途 promise 抽走会让正在 await 的调用方立即拿到 resolve(假「已落地」)。旧 run 的
- *     settle 位在被新 run 顶掉后由代际认领保护,旧 run 的 `finally` 不会误删。
- *   · 空串 ⇒ no-op。**从没探过也从没失效过的 base ⇒ 真 no-op**(不留代际条目):那种 base 上
- *     既无判定也无在途 run,没有任何陈旧写入可挡,留条目只会让任意串撑大表。
- *   · 绝不 throw(与本模块其余口同款:失效口在错误路径上响 = 把一个清理动作变成新的故障源)。
- *
- * 🔴 **推荐用两参形 `invalidateEngineCaps(baseUrl, probe)`**(对抗复审第三轮 [medium] 采纳,
- * 2026-08-19)。单参形与「下一次 kick」之间有一个**真窗**:失效之后、新探测注册之前,如果旧代际
- * 探测正好在这一拍落地,`settleByBase` 里已经没有更新代际的条目 ⇒ {@link engineCapsSettled} 把
- * 等待者放走,而缓存刚被清空 ⇒ 等待者把**当代引擎的能力位读成缺席**。窗口只在调用方于失效与 kick
- * 之间 `await` 了什么时才张开(同步块里 JS 单线程,旧探测的续体根本插不进来),但引擎温切本身就是
- * 异步流程,所以它是可达的。
- * 两参形把「推进代际」与「注册替代探测」放进**同一个同步块** ⇒ 窗口按构造不存在,等待者会被接力
- * 到新探测上(见 {@link engineCapsSettled} 的跨代际接力)。壳的 respawn/restartEngine 应当用它。
- * 单参形保留给「只想丢掉缓存、这一刻没有替代探测」的调用方 —— 那种情形下等待者读到**未判**
- * 是诚实结局(判据永远是缓存位),不是缺陷:硬等一个可能永远不会来的 kick 才是。
- *
- * @param probe 可选的**替代探测**(与新引擎同一拍注册)。给了就等价于「失效 + 立刻 kick」,
- *              且中间没有任何可插入点。
- */
 export function invalidateEngineCaps(baseUrl, probe) {
     if (!baseUrl)
         return;
@@ -312,16 +118,11 @@ export function invalidateEngineCaps(baseUrl, probe) {
         genByBase.set(baseUrl, capsGeneration(baseUrl) + 1);
         capsByBase.delete(baseUrl);
         inFlight.delete(baseUrl);
-        // 代际变更信号:把等在旧代际上的调用方叫醒去重新求值(见 settleByBase 与 engineCapsSettled
-        // 头注)。叫醒 ≠ 放行;下面 kick 的注册是**同步**发生的,所以醒来的续体(微任务)必然已经能
-        // 看到替代探测,不会从空隙里溜走。
         settleByBase.get(baseUrl)?.wake();
     }
-    // 原子替代:同一同步块内注册新代际的探测(上面刚清了 caps/inFlight,kick 的幂等闸必放行)。
     if (probe !== undefined)
         kickEngineCapsProbe(baseUrl, probe);
 }
-/** 测试钩子。 */
 export function __resetEngineCapsCacheForTests() {
     capsByBase.clear();
     inFlight.clear();

package/dist/engineCapsGenerationGuard.d.ts

@@ -1,6 +1,4 @@
-/** 调用方 `opts.generation` 的一次性快照;`null` = 读不出(供给坏了)。 */
 export declare function snapshotCapsGeneration(opts: {
     generation?: number;
 } | undefined): number | undefined | null;
-/** 入口快照的代际是否仍是当代;`gen` 缺席 = 调用方没供代际 = 恒当代;读代际抛出 = 不是。 */
 export declare function capsGenerationStillCurrent(baseUrl: string, gen: number | undefined): boolean;

package/dist/engineCapsGenerationGuard.js

@@ -1,14 +1,4 @@
-/**
- * engineCapsGenerationGuard — 六只能力位读器 tee 共用的**代际两问**(0.74.2;不出公面,只供包内 import)。
- *
- *  · {@link snapshotCapsGeneration}:从调用方 `opts` 上**一次性**读代际。`opts` 是调用方的对象,回体上的 getter 能在投影中途改它、
- *    也能让这一次读抛出 ⇒ 读不出答 `null`(tee 按「不动格」处置),别把调用方对象再读第二次。
- *  · {@link capsGenerationStillCurrent}:入口快照的代际现在还是不是当代。读代际抛出 ⇒ `false`(不动格,与陈旧代际同一处置)。
- *
- * 两只都**带值返回**而不是吞掉:tee 里因此没有一处「只求不抛」的空 catch(failloud 门 §C1)。
- */
 import { engineCapsGeneration } from './engineCapsCache.js';
-/** 调用方 `opts.generation` 的一次性快照;`null` = 读不出(供给坏了)。 */
 export function snapshotCapsGeneration(opts) {
     try {
         return opts?.generation;
@@ -17,7 +7,6 @@ export function snapshotCapsGeneration(opts) {
         return null;
     }
 }
-/** 入口快照的代际是否仍是当代;`gen` 缺席 = 调用方没供代际 = 恒当代;读代际抛出 = 不是。 */
 export function capsGenerationStillCurrent(baseUrl, gen) {
     if (gen === undefined)
         return true;