@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/engineCapReader.d.ts

@@ -1,77 +1,15 @@
-/**
- * engineCapReader — 能力位窄读器的**四口共用实现**(0.76.1 CC-75;包内叶,不出 barrel、不上公面)。
- * 🔴 两个 interface 刻意**不导出**:消费方(各只读器)只需要 `createEngineCapReader`,型由推断得出 ⇒
- *    不给包内再添一圈可依赖的型面,也不让边界 `unknown` 在导出签名上多占两格。
- *
- * ── 它收的是哪四份 ────────────────────────────────────────────────────────────────────────────
- * `GET /v1/capabilities` 的每一个窄读器(`sqlEngineCapability` / `writeProtectionCapability` /
- * `webSearchBackendCapability` / `executionLaneCapability` / `approvalsStreamLiveCapability` /
- * `deviceExecutorManagementCapability`)此前各自持有**逐字相同**的四份代码(此后新增的读器直接建在本件上):
- *   ① `note(baseUrl, caps, opts?)` 的 **tee**(宿主 caps 探测链上的读面落点);
- *   ② `observed(baseUrl?)` 的 per-baseUrl 读口(空缺 ⇒ 未观测);
- *   ③ `forget(baseUrl)` 的换代失效口;
- *   ④ `__resetForTests()` 测试钩。
- * 各只真正**互不相同**的只有两件:**投影函数**(键路径 / 在场判据 / 值形校验)与 **doctor 措辞表** ——
- * 那两件留在各自文件里。
- * 🔴 **刻意不做声明式键路径表**:`sql` 的三座、`writeProtection` 的三位、`deviceExecutor` 的对象臂 +
- *    `why` 判别子各有自己的合形判据(开集串 / 非负有限整数 / 严格布尔 / `null` 是合法值还是畸形),
- *    把它们压进一张通用描述表 = 给同一份判据立第二个判官(而投影函数本身**就是**那一份判据,不是它的抄件)。
- *
- * ── 🔴 tee 的五条纪律(逐条在 {@link createEngineCapReader} 里实现,各只共享同一份)──────────────
- *   ① 空 / 非串 `baseUrl` ⇒ no-op(读账的键就是 baseUrl,没有键就没有格);
- *   ② 代际只在**入口快照一次**(`opts` 是调用方的对象,回体上的 getter 能在投影中途改它);
- *   ③ 投影抛出(getter / Proxy 的回体)⇒ 与「投影答 `undefined`」**同一处置**,当畸形;
- *   ④ 投影**之后再核一次代际**(投影执行的是不可信 getter,它能在中途让这一格换代);
- *   ⑤ 畸形 ⇒ **删格**,不留上一台引擎的旧读数。
- * 并且 **绝不 throw** —— 读面腿不许反噬 caps 探测链。
- * ⚠️ **不传 `opts.generation` = 与本件到货之前逐字节同行为**(照写):那是 additive 供给,不是强制门。
- *    本件**不**替调用方补一个「自己抓号」的代际(tee 自己抓号是假判据 —— 陈旧那一发在这里读到的
- *    永远是新代号),也不因为收编而把缺供给那一档悄悄变严。
- */
-/**
- * 一只能力位读器的**全部差异**(其余一律共用)。
- *
- * 🔴 `makeUnobserved` 是**工厂**而不是一个共享常量(异源对抗复审采纳,真病):各只读器的读数是**可变对象**
- *    (`{ kind: 'unobserved' }`),共享同一份会在两个方向上出事 —— ① 一个消费端就地改了拿到的读数
- *    (`r.kind = …`),另一个 baseUrl、另一个会话下次读到的「未观测」就已经不是未观测了,而 `forget` /
- *    `__resetForTests` 只清 Map、救不回那份被改坏的常量;② 即使无人改值,「两次未命中的返回值**引用相等**」
- *    本身就是收编**新增**的别名关系(六只原码每次未命中都新建一个对象)。冻结共享对象**不算**等价替代:
- *    那把一次静默串味换成了一次抛错,仍与原行为不同。
- * 🔴 `R` 不绑任何词表:`executionLane` / `approvalsStreamLive` 只有三种 `kind`,`sql` / `writeProtection` /
- *    `webSearchBackend` 四种,`deviceExecutor.management` 四种带判别子 —— 工厂只管缓存 / 代际 / tee / forget,
- *    读数的域由各读器自己的型说,本件一个词都不认识。
- */
 interface EngineCapReaderSpec<R> {
-    /** 这只读器守的能力位名(阅读与诊断锚;**不参与任何判定** —— 读账按 baseUrl 键,每只各持一份闭包 Map)。 */
     name: string;
-    /** caps 回体 → 本格读数;畸形一律 `undefined`(= 这一格不写)。抛出与 `undefined` 同一处置。 */
     project: (caps: unknown) => R | undefined;
-    /** 这一格空缺时铸的读数;**每次**未命中都调一次(见上)。 */
     makeUnobserved: () => R;
 }
-/** 一只能力位读器的四口(名字由各读器的公面导出逐字包装,型与行为逐字不变)。 */
 interface EngineCapReader<R> {
-    /** 宿主 caps probe 的读面 tee 落点;绝不 throw。 */
     note(baseUrl: string, caps: unknown, opts?: {
         generation?: number;
     }): void;
-    /**
-     * 本进程观测到的读数;空 / 非串 `baseUrl` ⇒ `makeUnobserved()`。
-     *
-     * 🔴 **缺省读锚不在这里**:`engineWireTarget()?.baseUrl` 写在**每只读器公面函数的默认参数**上
-     *    (d.ts 上它显形为 `observedSqlEngine(baseUrl?: string | undefined)` —— 默认值表达式不进声明面,
-     *    但**求值时机**是对外行为的一部分:零参与显式 `undefined` 都在**调用那一刻**取读锚)。两处都写默认值 ⇒
-     *    没装读锚时 `engineWireTarget()` 会被调**两次**;所以这一口收**必填可空**参数,默认值留在各读器。
-     */
     observed(baseUrl: string | undefined): R;
-    /** 换代失效口:清成未观测。空 / 非串 ⇒ no-op;绝不 throw。 */
     forget(baseUrl: string | undefined): void;
-    /** 测试钩:只清**本只**读器的那张 Map —— 不动装好的读锚、不动 caps 缓存的代际号、不动别只读器的表。 */
     __resetForTests(): void;
 }
-/**
- * 建一只能力位读器。per-baseUrl 读账 = **本次调用闭包里**的一张 Map ⇒ 一只读器一张表,
- * 一只读器收到畸形回体删自己的格,绝不连坐另一只(这是六只原码分表的理由,收编后逐字保留)。
- */
 export declare function createEngineCapReader<R>(spec: EngineCapReaderSpec<R>): EngineCapReader<R>;
 export {};

package/dist/engineCapReader.js

@@ -1,51 +1,13 @@
-/**
- * engineCapReader — 能力位窄读器的**四口共用实现**(0.76.1 CC-75;包内叶,不出 barrel、不上公面)。
- * 🔴 两个 interface 刻意**不导出**:消费方(各只读器)只需要 `createEngineCapReader`,型由推断得出 ⇒
- *    不给包内再添一圈可依赖的型面,也不让边界 `unknown` 在导出签名上多占两格。
- *
- * ── 它收的是哪四份 ────────────────────────────────────────────────────────────────────────────
- * `GET /v1/capabilities` 的每一个窄读器(`sqlEngineCapability` / `writeProtectionCapability` /
- * `webSearchBackendCapability` / `executionLaneCapability` / `approvalsStreamLiveCapability` /
- * `deviceExecutorManagementCapability`)此前各自持有**逐字相同**的四份代码(此后新增的读器直接建在本件上):
- *   ① `note(baseUrl, caps, opts?)` 的 **tee**(宿主 caps 探测链上的读面落点);
- *   ② `observed(baseUrl?)` 的 per-baseUrl 读口(空缺 ⇒ 未观测);
- *   ③ `forget(baseUrl)` 的换代失效口;
- *   ④ `__resetForTests()` 测试钩。
- * 各只真正**互不相同**的只有两件:**投影函数**(键路径 / 在场判据 / 值形校验)与 **doctor 措辞表** ——
- * 那两件留在各自文件里。
- * 🔴 **刻意不做声明式键路径表**:`sql` 的三座、`writeProtection` 的三位、`deviceExecutor` 的对象臂 +
- *    `why` 判别子各有自己的合形判据(开集串 / 非负有限整数 / 严格布尔 / `null` 是合法值还是畸形),
- *    把它们压进一张通用描述表 = 给同一份判据立第二个判官(而投影函数本身**就是**那一份判据,不是它的抄件)。
- *
- * ── 🔴 tee 的五条纪律(逐条在 {@link createEngineCapReader} 里实现,各只共享同一份)──────────────
- *   ① 空 / 非串 `baseUrl` ⇒ no-op(读账的键就是 baseUrl,没有键就没有格);
- *   ② 代际只在**入口快照一次**(`opts` 是调用方的对象,回体上的 getter 能在投影中途改它);
- *   ③ 投影抛出(getter / Proxy 的回体)⇒ 与「投影答 `undefined`」**同一处置**,当畸形;
- *   ④ 投影**之后再核一次代际**(投影执行的是不可信 getter,它能在中途让这一格换代);
- *   ⑤ 畸形 ⇒ **删格**,不留上一台引擎的旧读数。
- * 并且 **绝不 throw** —— 读面腿不许反噬 caps 探测链。
- * ⚠️ **不传 `opts.generation` = 与本件到货之前逐字节同行为**(照写):那是 additive 供给,不是强制门。
- *    本件**不**替调用方补一个「自己抓号」的代际(tee 自己抓号是假判据 —— 陈旧那一发在这里读到的
- *    永远是新代号),也不因为收编而把缺供给那一档悄悄变严。
- */
 import { snapshotCapsGeneration, capsGenerationStillCurrent } from './engineCapsGenerationGuard.js';
-/**
- * 建一只能力位读器。per-baseUrl 读账 = **本次调用闭包里**的一张 Map ⇒ 一只读器一张表,
- * 一只读器收到畸形回体删自己的格,绝不连坐另一只(这是六只原码分表的理由,收编后逐字保留)。
- */
 export function createEngineCapReader(spec) {
     const readingByBase = new Map();
     return {
         note(baseUrl, caps, opts) {
-            // ① 空 baseUrl no-op
             if (typeof baseUrl !== 'string' || baseUrl === '')
                 return;
-            // ② 代际只在入口**快照一次**:`opts` 是调用方的对象,回体上的 getter 能在投影中途改它;首末两次核对都用这份快照,
-            //    读 opts / 读代际抛出 ⇒ 不动格(与陈旧代际同一处置)。
             const gen = snapshotCapsGeneration(opts);
             if (gen === null)
-                return; // 调用方 opts 的 getter 抛出 = 供给坏了 ⇒ 不动格
-            // 陈旧代际在**投影之前**就退场:不执行回体上的 getter,也不动格。
+                return;
             if (!capsGenerationStillCurrent(baseUrl, gen))
                 return;
             let reading;
@@ -53,14 +15,10 @@ export function createEngineCapReader(spec) {
                 reading = spec.project(caps);
             }
             catch {
-                // ③ 抛 getter / Proxy 的回体 = 畸形,与「投影答 undefined」同一处置 —— 删格,不许留着上一台的读数。
                 reading = undefined;
             }
-            // ④ 投影之后**再核一次代际**:投影会执行回体上不可信的 getter,它可以在中途让这一格换代
-            //    (失效 + 新代际的 tee 已写入);此时无论投影返回还是抛出,都不许动新代际的格。
             if (!capsGenerationStillCurrent(baseUrl, gen))
                 return;
-            // ⑤ 畸形 ⇒ 删格
             if (reading === undefined) {
                 readingByBase.delete(baseUrl);
                 return;

package/dist/engineCapsCache.d.ts

@@ -1,129 +1,10 @@
-/**
- * ⇄ 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 / 每次构造清)只会把一个确定事实换成一个定时器。
- */
-/**
- * 该 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 declare function engineCapsGeneration(baseUrl: string): number;
-/** 构造期 kick(async 幂等);probe = client.capabilities 薄闭包。 */
 export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
-/**
- * 0.26.0(#225 件1 配套,消费请托自领):等**当前这一次**探测落地(成功或失败都算落地)。
- * 无 in-flight ⇒ 立即 resolve —— 判据永远是缓存里的位({@link engineCapTrue}),不是本 promise;
- * 本函数只解决「kick 完只能盲猜轮询窗」的时序问题(慢响应被猜短的窗渲成「没有这条车道」)。
- * 绝不 reject(探测失败=位维持未判,调用方按缺席降级)。
- */
 export declare function engineCapsSettled(baseUrl: string | undefined): Promise<void>;
-/**
- * 能力位的**可分辨读数**(#318 件③,cli [4752] 自领缺口2)——{@link engineCapTrue} 的三态化底座。
- *
- * 病:`engineCapTrue` 只回 `true`/`false`,于是 `false` 同时承载**四件互不相同**的事 ——
- * 「引擎明说没有」「还没探」「探测在飞」「探测失败」。对**放行判据**而言这个塌缩是正确且刻意的
- * (缺席一律 fail-closed 不渲 affordance,见 engineCapTrue 的头注),但对**自检/诊断面**(doctor)
- * 它是致命的:doctor 要报的正是「这台引擎到底说了什么」,把「不知道」印成「没有」就是谎报。
- * 这也是 doctor 此前无法复用本共享缓存、只能自己再探一遍的直接原因。
- *
- * 🔴 **闭集,且每个成员各自可行动**(A1 禁哨兵值双义):
- *  · `true` / `false` —— caps **已落地**且该键字面为该布尔值 = **引擎明说**;
- *  · `unprobed` —— 该 base 此刻没有已落地的 caps(没 kick / 在飞 / 探测失败 / 刚被
- *    {@link invalidateEngineCaps} 作废)。🔴 四种成因**故意合并**:它们对调用方是同一个动作 ——
- *    `await` 一次 {@link engineCapsSettled} 再读,或按「不知道」呈现。分开需要引擎没给的信息;
- *  · `absent` —— caps 已落地,但**没有这个键**:引擎比本包旧(还没这条车道)或比本包新(改名了);
- *  · `non_boolean` —— caps 已落地、键也在,但值不是布尔。这一档**不并进 `absent`**:那会是假话
- *    (键在),而它指向的是真问题(引擎申报了一个本口读不动的形 —— 比如把 caps 位写成了字符串),
- *    诊断面该看见它。
- *
- * 🔴 **本读口不改变任何放行语义**:{@link engineCapTrue} 逐字等价于 `engineCapState(...) === 'true'`
- * (下面就是这么实现的,单源)。放行面**继续**用 `engineCapTrue` —— 拿三态去开放行分支,等于把
- * fail-closed 改成「按成因区别对待」,那是另一件事,不在本口的授权内。
- */
 export type EngineCapState = 'true' | 'false' | 'unprobed' | 'absent' | 'non_boolean';
-/**
- * 同步读口(三态化):该 base 的 caps 里 key 的**可分辨**读数。语义逐条见 {@link EngineCapState}。
- *
- * `baseUrl` 缺席 ⇒ `unprobed`(没有 base 就没有任何一次探测,这不是「引擎说没有」)。
- */
 export declare function engineCapState(baseUrl: string | undefined, key: string): EngineCapState;
-/** 同步读口:该 base 的 caps 里 key 是否字面 true(未判/缺键 = false)。
- *  🔴 **语义一字不变**(#318 件③ 三态化后改为经 {@link engineCapState} 单源实现):放行面读的就是
- *  这一口,四种「不知道」继续一律折成 `false` = fail-closed。要分辨成因请读 {@link engineCapState}。 */
 export declare function engineCapTrue(baseUrl: string | undefined, key: string): boolean;
-/**
- * 同步读口(**嵌套**布尔键):`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 declare function engineCapNestedTrue(baseUrl: string | undefined, parentKey: string, key: string): boolean;
-/**
- * 一格能力位上「**有没有值**」的四态(0.59.0,S-131 请托的通用半场)。
- *
- * 🔴 为什么必须是四态而不是「有 / 没有」:`/v1/capabilities` 上有**至少三种**不同的「读不出来」,
- *    它们对运维是三条不同的下一步,折成一件就是把「不知道」渲成一个答案
- *    ([honest-absence-not-fabricated-zero]):
- *      · `unobserved` —— 这个 base 的 caps **一次都没落地**(没 kick / 还在飞 / 探测失败)。
- *        **不是**「引擎没有这个位」;
- *      · `not_reported` —— caps 在手,回体上**没有**这个键 ⇒ 老引擎。**不是**「这台部署没接」;
- *      · `null` —— 引擎**明确说** `null`。这是一个**正面事实**(上游用 `null` 表达「这台部署确实
- *        没有这个设施」的位就走这一档),把它折进上面两档等于把引擎真给的答案丢掉;
- *      · `value` —— 有值(对象 / 数组 / 串 / 数 / 布尔,原样带出)。
- * 🔴 **`value` 不做任何形校验**:形归各自的窄读器(单点铸判据),通用口再校一遍就会在上游 additive
- *    加成员那天把一个合法值挡在包边界外,还让「谁把它窄没的」在排障时说不清。
- */
 export type EngineCapValueState = {
     kind: 'unobserved';
 } | {
@@ -134,65 +15,7 @@ export type EngineCapValueState = {
     kind: 'value';
     value: unknown;
 };
-/**
- * 同步读口(**任意值 / 嵌套对象**):该 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 declare function engineCapValue(baseUrl: string | undefined, key: string): EngineCapValueState;
-/**
- * 同步读口(字符串键):该 base 的 caps 里 key 的字符串值,未判/缺键/非字符串 ⇒ undefined。
- *
- * 首个消费者 = `hooksWireCaps` 的 `/goal` CC-Stop 语义判档,它要读 `capabilities.version`
- * (SDK `Capabilities.version`,server 侧 = `serviceVersion()`,与 `/health.version` 同源)。
- * 🔴 纪律同 {@link engineCapTrue}:**未判即 undefined**,调用方必须按「探不到 ⇒ 降级」处理 ——
- * 引擎能力位缺席时任何「假定它有」的分支都是对用户/模型的谎报。
- */
 export declare function engineCapString(baseUrl: string | undefined, key: string): string | 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 declare function invalidateEngineCaps(baseUrl: string | undefined, probe?: () => Promise<unknown>): void;
-/** 测试钩子。 */
 export declare function __resetEngineCapsCacheForTests(): void;