@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/hitl/gateLedger.js

@@ -1,128 +1,41 @@
-/**
- * 连坐 abort 帧的 additive 超集机读位(#324 / [4907] 裁定;登记见 `docs/type-superset.json`)。
- *
- * `flushHeld` 对**已知不是 gate 主角**的帧 stamp `true`,别的帧一个字节不改。消费方(壳 / web /
- * desktop)据此把连坐簇按 repeated-error 族软化折叠,**不猜文案**。
- *
- * 🔴 刻意**不动** `isError` 与 `output`:core 5.51 的 `[DEFERRED]` / `gate.batch_halted` 词汇
- *    ([4826]③)尚未到货,那一面的定形归 core;本键只是机读位,到货后与官方形对表,
- *    additive 键保留兼容(裁定原文)。
- */
 export const SEMA_COLLATERAL_ABORT_KEY = '_sema_collateral_abort';
-/**
- * {@link GateLedger.noteStart} 那张在飞表的**容量上限**(L-69⑨,0.52.0)。
- *
- * 🔴 为什么必须有界:本表的写口是**每一张** `tool_start`,而它的删口(`tool_end` 收口)在两种真实
- *    形态下不会来 —— ①一个 turn 里 `tool_end` 先于本连接开始(durable re-attach 只消费 `runs.events`
- *    的一段);②run 被中止 / 连接断掉,在飞 call 的收口帧永远不到。无界表在长流多工具的 turn 上
- *    条目数会一直涨。
- *
- * 🔴 **上限量的是条目数(= 保留的引用数),不是字节数**(异源对抗复审 R1 finding① 采纳的措辞订正)。
- *    本表存的是 `ev.args` 的**引用**,不是拷贝 —— 而同一个 `ev` 在这一拍**照常 yield 下去**
- *    (`frameRouter.routeToolStart` 返回 `{kind:'yield', events:[ev]}`),投影成 `SDKMessage` 之后
- *    那份入参在端的转录面上本来就活着。所以本表对**驻留字节**的增量是「一个指针 × 条目数」,
- *    它不复制载荷、也不是这条链上第一个持有它的容器:同文件的 {@link GateLedger.noteGatedStart}
- *    从本批之前就持着同一形的引用,而且**整个 turn 不删、连条目数都不设上限**。
- *    ⚠️ 仍然如实说清**没有**守住的那一格:单条载荷本身**没有**字节预算(一次 `Write` 的
- *    `content` 有多大,这里就跟着多引用多大一份多久)。真要按字节记账得先定义「多大算大」并同批给出
- *    超限时的降级形(截断 = 交出一份假入参,不许;整条不留 = 那只 call 的 deny 现场退回诚实缺席),
- *    属独立一件;本批**不做单边近似**,如实登记在此。
- * 🔴 为什么是 **256** 而不是更小:上限守的是「条目数无界增长」,而它必须**远大于**同一时刻真正在飞的
- *    call 数,否则淘汰会打到还没收口的 call 身上(那正是本表要服务的对象)。引擎侧同一 turn 的并发
- *    工具批今天是个位数量级,单批 `tool_start` 连发也在两位数以内;256 给出的是两个数量级的余量。
- * 🔴 淘汰**按 FIFO 丢最早**(`Map` 的插入序):最早入表的那一条是**最久没有收口**的,它要么已经因为
- *    上面两种形态永远不会收口,要么它的消费窗(收口当拍)早就过去了 —— 丢它的代价最小。绝不按
- *    「随便丢一个」或整表清空(整表清空会把同批在飞的兄弟一起打掉)。
- * 🔴 **淘汰打到仍在飞的 call 时会怎样(成文的取舍,不是漏)**:那只 call 后来被分类器拒绝的话,
- *    宿主拿到的 `ctx` 只有 `toolCallId`、没有 `args` —— 即**诚实缺席**,端按可选处理照常降级渲
- *    (契约见 `docs/INTEGRATION-CLIENTS.md` §15c 第 3 条)。这条路上唯一的替代品是「不淘汰」,
- *    而那就是无界表。durable 重放会把 `tool_start` 再送一遍,那是被淘汰项**拿回快照**的机会 ——
- *    所以 `frameRouter.routeToolStart` 把本动词排在渲染去重闸**之前**(见该站点注)。
- */
 export const START_ARGS_MAX_ENTRIES = 256;
-/** 造一份 turn 级 gate 台账(**不是单例**,见文件头注)。 */
 export function createGateLedger() {
     const startedCalls = new Set();
     const endedCalls = new Set();
-    /** 只存帧:出身不在入表当拍冻结(那一拍 gate 身份还没到),改在 `flushHeld` 当拍求值。 */
     const heldAskEnds = new Map();
     const gatedStartArgsByCall = new Map();
-    /** 每一张 tool_start 的 args 快照(在飞窗;有界 FIFO,见 {@link START_ARGS_MAX_ENTRIES})。 */
     const startArgsByCall = new Map();
     const deniedCalls = new Set();
     const pendingFsCalls = [];
     const resolvedAnswers = new Map();
     const decidedGates = new Set();
-    /** 「已解决」判据的**同因连续命中**闸(#357):判据源 + 连续次数,见 `noteAlreadyResolvedGate`。 */
     let alreadyResolvedKey;
     let alreadyResolvedStreak = 0;
-    // ── 批级判据(四样同生共死,退休点见 `retireBatchState` 的两处调用)────────────────────────
-    /** 本批 park 属 fs/shell 族的准入证(唯一性兜底的前置)。 */
     let fsOrShellFamilyGate = false;
-    /** 本批里被 `dropHeld` 摘出扣留表的 call(decide 成功会把主角摘走,判据还得认它)。 */
     const droppedFromBatch = new Set();
-    /** 本批登记过几张 park。≠1 ⇒ 归属无从证明 ⇒ 整表不标(硬门)。 */
     let batchParkCount = 0;
-    /** 上一次 park 登记之后有没有新帧进过扣留表 —— 用来把「同一张 park 被 durable 重放」认出来。 */
     let heldSinceLastPark = false;
-    /** 本 turn 见过的 fs 写 / shell 执行族 gated tool_start —— 只做**族成员**判据,不做主角判据。 */
     const fsOrShellGatedCalls = new Set();
     let lastFsOrShellGatedCall;
-    /**
-     * flush 当拍解析「谁是主角」:登记在案的优先;否则唯一性兜底(要准入证 + 扣留表内族成员唯一);
-     * 都拿不到 ⇒ `undefined` = 不知道,调用方一个都不 stamp。
-     *
-     * 🔴 返回 `undefined` 与返回空集合是**两件事**,别合并([honest-absence-not-fabricated-zero]):
-     *    空集合意味着「知道谁是主角,且一个都不是」。
-     * 🔴 兜底在**扣留表内**求唯一 —— 主角必在这一批被同一次 abort 连坐的 call 里;拿整个 turn 的
-     *    历史集求唯一会把「已经收口过的旧 call」算进来,又是一次「拿旁证冒充身份」。
-     */
     const resolveGateSubjects = () => {
-        // 🔴 硬门:归属可结构性证明 = 本批恰好一张 park。零张(同步帧腿 / 纯取消批)与多张(两次
-        //    gate 的 abort 混进同一张扣留表)都无解 —— 诚实不标,绝不猜。
         if (batchParkCount !== 1)
             return undefined;
-        // 准入证:这张 park 的 gate **本体**属 fs 写 / shell 执行族 —— 主角必是该族的某个 call。
         if (!fsOrShellFamilyGate)
             return undefined;
-        // 前置:每一条扣留帧的 `tool_start` 都得是本连接亲眼见过的。族成员判据取自 tool_start 当拍
-        // 记的集合,没见过 start 的 call 在「唯一」这件事上是隐形的;而续流只消费 `runs.events` 的一段
-        // (re-attach 从 `lastEventId` 起),主角的 start 完全可能落在这次连接之外 —— 那时表里剩下的
-        // 唯一族成员是**旁观者**,会被当成主角、反手给真主角打上连坐位。信息不全就不许声称「唯一」。
         for (const id of heldAskEnds.keys()) {
             if (!startedCalls.has(id))
                 return undefined;
         }
-        // 主角 = 本批(扣留帧 ∪ 已出批帧)里**唯一**属该族的 call。并上出批帧是因为决断成功那一下会
-        // 把主角的毒化帧 `dropHeld` 掉;不并上就等于主角「不在这一批」,整批判据当场失效。
         const family = [...new Set([...heldAskEnds.keys(), ...droppedFromBatch])].filter((id) => fsOrShellGatedCalls.has(id));
         return family.length === 1 ? new Set(family) : undefined;
     };
-    /**
-     * `dropHeld` / `dropHeldForDecidedPark` 的**唯一**实现(两个动词共用一份,批级退休那条不变量
-     * 只写一处 —— 两份写法各自漂正是本模块存在的理由)。
-     * `callId === undefined` = 「这次什么都不摘」:退休检查照跑,别的一律不动。
-     */
     const dropHeldImpl = (callId) => {
         if (callId !== undefined && heldAskEnds.delete(callId))
             droppedFromBatch.add(callId);
-        // 🔴 扣留表空 = 这一批没有(或不再有)任何待判的帧,批级判据当场退休 —— 不能等下一次
-        //    flush:「决断成功但本批压根没有毒化帧」的路径上 `flushHeld` 一次都不会跑,判据会就这么
-        //    活到下一批去把那一批的**真主角**判成连坐(实测 `new-main=STAMP`)。
-        // 🔴 「摘的那个不在表里」也要走这一步(不能早退):零 HOLD 批正是**每次** delete 都落空的
-        //    形状,早退就等于那种批永远不退休 —— 上一版的漏洞就在这里。
         if (heldAskEnds.size === 0)
             retireBatchState();
     };
-    /**
-     * 件④ 保守臂的判据:候选在扣留表里**同族唯一**吗。
-     *
-     * 「族」的口径与**取件谓词**同轴(那才是可能撞车的那一层 —— `findPendingForTask` 是按族选行的):
-     *   · 候选属 fs 写 / shell 执行族(`fsOrShellGatedCalls`,tool_start 当拍记)⇒ 数扣留表里同属
-     *     该族的条数(两个 Bash / 一个 Write 一个 Edit 都算同族,因为取件谓词对它们不可分);
-     *   · 否则(ask / kind-only 等)⇒ 数扣留表里 `toolName` 逐字相同的条数。
-     * 不在扣留表里 ⇒ `false`(没有可摘的帧,也就谈不上「唯一」)。
-     */
     const soleOfItsFamilyInHold = (callId) => {
         const ev = heldAskEnds.get(callId);
         if (ev === undefined)
@@ -141,7 +54,6 @@ export function createGateLedger() {
         }
         return n === 1;
     };
-    /** 一批判完(或整批被摘空)⇒ 四样批级判据同批退休:下一批从零证起。 */
     const retireBatchState = () => {
         fsOrShellFamilyGate = false;
         droppedFromBatch.clear();
@@ -163,8 +75,6 @@ export function createGateLedger() {
         },
         forgetRunScopedState() {
             seq = undefined;
-            // 🔴 三张 per-call 表一起清(理由见接口头注的安全格):`toolCallId` 不保证跨 run 唯一,
-            //    留着任何一张都会让新 run 的同名 call 走进「渲旧入参、决新绑定」那条路。
             startedCalls.clear();
             gatedStartArgsByCall.clear();
             startArgsByCall.clear();
@@ -182,13 +92,8 @@ export function createGateLedger() {
             return gatedStartArgsByCall;
         },
         noteStart(callId, ev) {
-            // 🔴 **先删再写**:同一 callId 重放(durable 重放的 tool_start 在别的入口被 markStarted 挡掉,
-            //    但本动词不依赖那道闸)必须刷新它在 FIFO 里的位置,否则「覆盖」会让它保持旧的插入序、
-            //    在还活着的时候被当成最老的一条淘汰掉。`Map.set` 对已有键**不**改插入序,这一行是承重的。
             startArgsByCall.delete(callId);
             startArgsByCall.set(callId, ev.args);
-            // 有界:超容量丢**最早**入表的那一条(`Map` 迭代序 = 插入序)。while 而不是 if —— 上限被
-            // 调小时(或将来某次批量写入)一次要淘汰多条,if 会让表永久停在超限状态。
             while (startArgsByCall.size > START_ARGS_MAX_ENTRIES) {
                 const oldest = startArgsByCall.keys().next();
                 if (oldest.done === true)
@@ -209,9 +114,6 @@ export function createGateLedger() {
             endedCalls.add(callId);
         },
         hold(callId, ev) {
-            // 🔴 只有**新** call 进批才算「批里来了新东西」:durable re-attach 会把仍被扣留的毒化帧
-            //    连同 park 一起重放,那一下若也置位,同一张 park 就会被当成第二张而触发硬门弃判
-            //    (实测:重放后本该带位的兄弟帧变成 ABSENT)。覆盖同一 callId = 重放,不置位。
             if (!heldAskEnds.has(callId))
                 heldSinceLastPark = true;
             heldAskEnds.set(callId, ev);
@@ -220,43 +122,28 @@ export function createGateLedger() {
             dropHeldImpl(callId);
         },
         dropHeldForDecidedPark(candidateCallId, trustedCallId) {
-            // ① wire 身份**对上了这次真被决断的那一行** ⇒ 身份确证,点名摘。
-            //    🔴 摘的永远是「真的被决断的那一行」(`candidateCallId`),wire 身份在这里的角色是**确证**
-            //    而不是另一个独立的摘取目标 —— 异源复审 finding①:决断腿按队列首行选行、这里却按 wire
-            //    身份摘帧,两边指向不同 call 时就是 split-brain(用户批的是旁观者,被摘的是主角帧)。
-            //    取件腿今天已经优先按同一个身份选行(见 `surfaceFsApprovalAndDecide` 的 parkGatedCallId),
-            //    所以正常路径上两者恒相等;不相等只发生在「身份在场但队列里没有那一行」的回落形 ——
-            //    那时决断落在别的行上,任何一帧都证明不了自己已过时,走②/③ 的保守判。
             if (trustedCallId !== undefined && trustedCallId === candidateCallId) {
                 dropHeldImpl(trustedCallId);
                 return;
             }
-            // ② 无可信身份:候选同族唯一才摘 —— 同族多条时任何选择都是猜,而猜错的代价是一帧永久消失。
             if (candidateCallId !== undefined && soleOfItsFamilyInHold(candidateCallId)) {
                 dropHeldImpl(candidateCallId);
                 return;
             }
-            // ③ 判不出 ⇒ 一条都不摘(退休检查仍照跑,见 dropHeldImpl 头注)。
             dropHeldImpl(undefined);
         },
         heldCount() {
             return heldAskEnds.size;
         },
         *flushHeld() {
-            // 🔴 出身在**这一拍**求值(不是入表当拍):五个 flush 出口全部晚于 park 被看见,
-            //    gate 身份此时已在手。`undefined` = 不知道谁是主角 ⇒ 整表一个字节不改。
             const subjects = resolveGateSubjects();
             for (const [callId, ev] of heldAskEnds) {
                 endedCalls.add(callId);
-                // 已知不是主角 ⇒ additive 机读位(帧的其余部分逐字节原样);主角与「不知道」走原路。
                 yield subjects !== undefined && !subjects.has(callId)
                     ? { ...ev, [SEMA_COLLATERAL_ABORT_KEY]: true }
                     : ev;
             }
             heldAskEnds.clear();
-            // 🔴 判完即弃:这一批帧就是这张 gate 的 abort 批。不退休 ⇒ 判完之后又来一批**背后没有
-            //    任何 gate**的 abort 帧(例如整轮被取消)时,上一批的证会给它们派判词。
-            //    身份不在退休之列(turn 级事实),它靠上面的「∩ 本批」求交集来限定作用域。
             retireBatchState();
         },
         markDenied(callId) {
@@ -296,14 +183,6 @@ export function createGateLedger() {
             return lastFsOrShellGatedCall;
         },
         noteParkGate(evidence) {
-            // 自上次登记以来没有**新 call** 进过扣留表 ⇒ 按 durable 重放同一张 park 处置:不计新的一张。
-            // 🔴 而且**一个字节都不写**。「没有新帧进批」证明得了「这一批的组成没变」,证明不了
-            //    「这张 park 就是上一张」—— 一张**真的新 park** 同样可以零毒化帧(例如上一张 park 走
-            //    already-resolved 重放救回、续流紧接着来一张别的 gate 的 park)。此时若顺手刷新族属,
-            //    本批的判据就被一张与这批帧无关的 gate 改写:实测 `WebFetch` 主角 + `Bash` 旁观者的批
-            //    被一张零毒化 `Bash` park 改成 fs/shell 族,兜底选中旁观者、反手给真主角打位
-            //    (`web-main=STAMP`)。真是重放时族属本就相同,不写零损失;是新 park 时不写才安全。
-            //    (本批的帧全部早于第一张 park,归属本来就该按第一张算。)
             if (batchParkCount > 0 && !heldSinceLastPark)
                 return;
             batchParkCount += 1;