@sema-agent/client-core 0.61.0 → 0.62.1

package/dist/subagentContentStore.js

@@ -10,6 +10,14 @@
  *
  * WIRE FACTS: with `forwardSubagentEvents: true` on the task request, the live stream carries the
  * subagent's text_delta / reasoning_delta / tool_start / tool_end stamped with EventIdentity
+ * —— 🔴 **durable 腿(重放)送的是同一段的聚合形** `text` / `reasoning`(整段全文,同样带
+ * EventIdentity)。两类都要收:只收增量的话,续听重放尾的宿主整条子代转录都是空的
+ * (0.62.0 补;两类的处置**不同**,见 {@link publishSubagentContentEvent} 的吸收规则)
+ * 🔴 **重放的幂等闸覆盖四个臂**(`text` / `reasoning` / `tool_start` / `tool_end`):重连 = 新的一条
+ * 流,缝前那道事件序号去重只在同一条流内有效,所以「整轮重放」拦得住的只能是这本账。判据形相同
+ * (先问身份、再问账本),身份与账本各按臂取:散文两臂 = 聚合帧 `eventId` + 已上屏的整段正文;
+ * 工具两臂 = `toolCallId` + `items` 上那张卡,收口另带一本**自己额度**的收口身份账(同一次调用
+ * 会有**第二发**真收口 —— 门 park 之后恢复执行,见 {@link publishSubagentContentEvent})。
  * (§E1 redact upstream; §E2 identity). 🔴 EventIdentity 的键是 `eventId` / `parentToolCallId`
  * (+ LIVE 白名单四臂上的 `sourceTaskId` / `bgAgentId`)—— **没有 `taskId`**(sdk `events.d.ts` 的
  * `interface EventIdentity` 直证;`taskId` 只长在 `meta` 首帧上)。所以内容帧到不了「自带引擎
@@ -89,7 +97,252 @@ export function coerceOutput(v) {
 const MAX_ITEMS_PER_TASK = 200;
 const MAX_TASKS = 32;
 const NOTIFY_COALESCE_MS = 250;
+/** 不配时生效的两位(理由见 {@link SubagentContentStoreConfig} 顶注)。 */
+export const SUBAGENT_CONTENT_STORE_DEFAULTS = Object.freeze({
+    maxBytesPerTask: 2 * 1024 * 1024,
+    maxBytesTotal: 16 * 1024 * 1024,
+});
+let storeConfig = { ...SUBAGENT_CONTENT_STORE_DEFAULTS };
+/**
+ * 配字节预算(宿主启动时调一次;两位可分开配,只给一位时另一位保持现值)。
+ *
+ * 🔴 **fail-loud**:0 / 负数 / 非有限数 / 非整数一律 `throw` —— 一个被**静默忽略**的预算配置正是
+ *    这本账本要消灭的那类失败(宿主以为配上了,而账本还在按缺省无声地丢或不丢)。
+ * 🔴 拒绝是**原子**的:任何一位不合法就整只拒,既有配置一个字节不动(半套配置比不配更坏)。
+ */
+export function configureSubagentContentStore(next) {
+    const check = (name, v) => {
+        if (v === undefined)
+            return undefined;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) {
+            throw new TypeError(`configureSubagentContentStore: \`${name}\` must be a positive integer number of bytes (got ${String(v)})`);
+        }
+        return v;
+    };
+    const perTask = check('maxBytesPerTask', next.maxBytesPerTask);
+    const total = check('maxBytesTotal', next.maxBytesTotal);
+    // 🔴 两位的**关系**也要验(车内异源复审逼出:两位各自合法、合起来自相矛盾)。每子代帽大于总帽时,
+    //    单条子代可以合法地涨到每子代帽 —— 而总帽淘汰**不动当期那条**(它正在写),于是那一条就整只
+    //    越过了总帽,总帽从此形同虚设。判的是**落值之后**的那一对,不是这次传进来的那一位:只配一位
+    //    时另一位保持现值,矛盾同样可能是这次配出来的。
+    const nextPerTask = perTask ?? storeConfig.maxBytesPerTask;
+    const nextTotal = total ?? storeConfig.maxBytesTotal;
+    if (nextPerTask > nextTotal) {
+        throw new RangeError(`configureSubagentContentStore: \`maxBytesPerTask\` (${String(nextPerTask)}) must not exceed ` +
+            `\`maxBytesTotal\` (${String(nextTotal)}) — a per-task budget above the total is unreachable by ` +
+            'construction, and the total stops bounding anything.');
+    }
+    // 两位都验完才落 —— 第二位不合法时第一位也不许生效。
+    storeConfig.maxBytesPerTask = nextPerTask;
+    storeConfig.maxBytesTotal = nextTotal;
+}
+/** 当前生效的两位(**快照**:改返回值不影响账本)。 */
+export function subagentContentStoreConfig() {
+    return { ...storeConfig };
+}
+/** 测试钩:把预算复位到缺省。 */
+export function __resetSubagentContentStoreConfigForTests() {
+    storeConfig = { ...SUBAGENT_CONTENT_STORE_DEFAULTS };
+}
 const tasks = new Map();
+/** 整本账本当下保留的内容字节(逐次增删维护;总帽读它)。 */
+let totalBytes = 0;
+/**
+ * 一段文本的 **UTF-8 字节数**,不做编码分配。
+ *
+ * 🔴 为什么不用 `TextEncoder`:它每次都要**分配**一个字节数组,而这条路是逐 token 的热路径
+ *    (实测 ~23 帧/s 的增量流)。算术形零分配、结果逐字节相同。
+ * 🔴 为什么不按 `str.length`(UTF-16 单元)算:账本里装的是引擎送来的文本,一段 CJK 的真实占用
+ *    是串长度的三倍 —— 按串长度算等于把预算对中文内容放宽两倍。
+ */
+function utf8Len(str) {
+    let n = 0;
+    for (let i = 0; i < str.length; i++) {
+        const c = str.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff && i + 1 < str.length) {
+            // 合法代理对 = 一个 4 字节码位(高位后面不是低位时按 3 字节的孤代理项算,与编码器同)
+            const next = str.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                n += 4;
+                i++;
+            }
+            else
+                n += 3;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}
+/**
+ * 把 `chunk` 追加到 `prev` 之后,**字节账真正增加了多少**。
+ *
+ * 🔴 不能直接用 `utf8Len(chunk)`(车内异源复审逼出的真病):一对代理对被上游拆成**两帧**送来时,
+ *    前一帧尾部那枚高位代理项按孤代理项算 3 字节、后一帧首部那枚低位代理项也算 3 字节,合计 6;
+ *    而拼起来之后它是一个 4 字节码位。每拆一次就虚高 2 字节,而段闭合时是按**拼接后的串**扣账
+ *    —— 加 6 扣 4,差额永久留在账上。长流里这个漂移会一路把总账推高,最后把还在用的账本淘汰掉。
+ * ⇒ 只在**拼接边界**上修正一次(O(1)),不重扫整条缓冲(缓冲能有 MB 级,而这是逐 token 的热路径)。
+ */
+function appendBytes(prev, chunk) {
+    const add = utf8Len(chunk);
+    if (prev.length === 0 || chunk.length === 0)
+        return add;
+    const lastPrev = prev.charCodeAt(prev.length - 1);
+    const firstNew = chunk.charCodeAt(0);
+    const joinsPair = lastPrev >= 0xd800 && lastPrev <= 0xdbff && firstNew >= 0xdc00 && firstNew <= 0xdfff;
+    return joinsPair ? add - 2 : add;
+}
+/** 一条 item 的字节账(`truncated` 是关于预算的元信息,自身不计)。 */
+function itemBytesOf(it) {
+    switch (it.kind) {
+        case 'text':
+        case 'thinking':
+        case 'echo':
+            return utf8Len(it.text);
+        case 'tool': {
+            let n = utf8Len(it.name) + utf8Len(it.output ?? '');
+            // 工具参数是**开集** `unknown`:序列化一次算体量(每张卡只算一次,不在增量热路径上)。
+            try {
+                if (it.input !== undefined)
+                    n += utf8Len(JSON.stringify(it.input) ?? '');
+            }
+            catch {
+                // 循环引用/不可序列化 ⇒ 这一位按 0 计(它进不了展示面,也就占不了这本账的预算)
+            }
+            return n;
+        }
+        case 'truncated':
+            return 0;
+    }
+}
+/** 从串**头部**裁掉至少 `want` 字节;返回剩下的尾巴与真正裁掉的字节数(不劈开合法代理对)。 */
+function trimHeadBytes(str, want) {
+    let removed = 0;
+    let i = 0;
+    while (i < str.length && removed < want) {
+        const c = str.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff && i + 1 < str.length) {
+            const next = str.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                removed += 4;
+                i += 2;
+                continue;
+            }
+        }
+        removed += c < 0x80 ? 1 : c < 0x800 ? 2 : 3;
+        i += 1;
+    }
+    return { rest: str.slice(i), removed };
+}
+/** 字节账的唯一增减口(两本账同拍走,永不分叉)。 */
+function addBytes(s, n) {
+    s.bytes += n;
+    totalBytes += n;
+}
+/** 记一次丢弃:更新/建立留痕记录(每条子代恒一条,恒排在最前)。 */
+function noteDropped(s, dropped) {
+    if (dropped <= 0)
+        return;
+    s.droppedBytes += dropped;
+    const head = s.items[0];
+    if (head?.kind === 'truncated') {
+        head.droppedBytes = s.droppedBytes;
+        head.keptFrom = s.droppedBytes;
+        return;
+    }
+    s.items.unshift({ kind: 'truncated', droppedBytes: s.droppedBytes, keptFrom: s.droppedBytes });
+    s.itemBytes.unshift(0);
+    rebuildOpenTools(s);
+}
+/** items 被增删之后重建「开着的工具卡 → 下标」表(下标随 splice/unshift 整体漂移)。
+ *  🔴 同批把**卡已不在 items 上**的阶段水位清掉:水位是「这张卡现在承载的是哪一阶段」,卡没了它
+ *     就没有指涉对象,而这张表按 `toolCallId` 一条一条长 —— 不跟着卡清 = 一条长 turn 上的无界增长
+ *     (本账本的立身之本就是有界)。守的是内存面,不是行为面,理由见 `toolPhase` 头注的那一笔。 */
+function rebuildOpenTools(s) {
+    s.openTools.clear();
+    const live = new Set();
+    s.items.forEach((it, i) => {
+        if (it.kind === 'tool') {
+            live.add(it.id);
+            if (it.output === undefined)
+                s.openTools.set(it.id, i);
+        }
+    });
+    for (const id of s.toolPhase.keys()) {
+        if (!live.has(id))
+            s.toolPhase.delete(id);
+    }
+}
+/**
+ * 每子代帽:超出就**从最早的内容开始丢**,丢不动了再从缓冲头部裁。
+ *
+ * 🔴 顺序是「先 item 后缓冲」而不是反过来:缓冲是**活体尾巴**(用户正在看的那一段),item 是更早
+ *    的历史。反过来做会把用户眼前正在流的字丢掉,而屏上更早那一段完好无损 —— 那是错的一头。
+ * 🔴 留痕记录自身不参与丢弃(它是关于预算的元信息;丢掉它等于把「有东西被丢了」这件事也丢了)。
+ */
+function enforceTaskCap(s) {
+    const cap = storeConfig.maxBytesPerTask;
+    if (s.bytes <= cap)
+        return false;
+    let dropped = 0;
+    const first = () => (s.items[0]?.kind === 'truncated' ? 1 : 0);
+    while (s.bytes > cap && s.items.length > first()) {
+        const idx = first();
+        const b = s.itemBytes[idx] ?? 0;
+        s.items.splice(idx, 1);
+        s.itemBytes.splice(idx, 1);
+        addBytes(s, -b);
+        dropped += b;
+    }
+    if (s.bytes > cap) {
+        const cut = trimHeadBytes(s.thinkBuf, s.bytes - cap);
+        s.thinkBuf = cut.rest;
+        addBytes(s, -cut.removed);
+        dropped += cut.removed;
+    }
+    if (s.bytes > cap) {
+        const cut = trimHeadBytes(s.textBuf, s.bytes - cap);
+        s.textBuf = cut.rest;
+        addBytes(s, -cut.removed);
+        dropped += cut.removed;
+    }
+    if (dropped > 0) {
+        rebuildOpenTools(s);
+        noteDropped(s, dropped);
+        return true;
+    }
+    return false;
+}
+/**
+ * 总帽:整条**最久未用**的子代账本被清掉(`tasks` 的迭代序就是 LRU 序,活跃项每次访问都会重插)。
+ * 🔴 刻意不动**当期**那条(它正在写),也刻意不做「每条各裁一点」——半截的转录比一条整齐的缺席更难读。
+ */
+function enforceTotalCap(currentKey) {
+    while (totalBytes > storeConfig.maxBytesTotal) {
+        let victim;
+        for (const k of tasks.keys()) {
+            if (k !== currentKey) {
+                victim = k;
+                break;
+            }
+        }
+        if (victim === undefined)
+            return; // 只剩当期那条:它已被每子代帽按住,这是能做到的最好结果
+        dropTask(victim);
+    }
+}
+/** 删一条子代账本并把它的字节从总账里扣掉(唯一删除口)。 */
+function dropTask(key) {
+    const s = tasks.get(key);
+    if (!s)
+        return;
+    totalBytes -= s.bytes;
+    tasks.delete(key);
+}
 // parentToolCallId ↔ engine taskId aliasing: CONTENT events carry ONLY {eventId, parentToolCallId}
 // (EventIdentity — no taskId on the wire), while the panel rows / 查看态 lookups key by the ENGINE task id
 // (task_progress carries BOTH). Content arriving before the first tick parks under the parent key and is
@@ -115,9 +368,21 @@ function stateFor(taskId, parentToolCallId) {
         if (tasks.size >= MAX_TASKS) {
             const oldest = tasks.keys().next().value;
             if (oldest !== undefined)
-                tasks.delete(oldest);
+                dropTask(oldest); // 条数淘汰同样要把字节从总账里扣掉
         }
-        s = { items: [], textBuf: '', thinkBuf: '', openTools: new Map(), parentToolCallId };
+        s = {
+            items: [],
+            itemBytes: [],
+            textBuf: '',
+            thinkBuf: '',
+            openTools: new Map(),
+            parentToolCallId,
+            bytes: 0,
+            droppedBytes: 0,
+            seenAggregateIds: new Set(),
+            recordedSegments: new Set(),
+            toolPhase: new Map(),
+        };
         tasks.set(taskId, s);
     }
     else {
@@ -126,25 +391,57 @@ function stateFor(taskId, parentToolCallId) {
     return s;
 }
 function pushItem(s, item) {
+    const b = itemBytesOf(item);
     s.items.push(item);
+    s.itemBytes.push(b);
+    addBytes(s, b);
     if (s.items.length > MAX_ITEMS_PER_TASK) {
-        s.items.splice(0, s.items.length - MAX_ITEMS_PER_TASK);
+        const cut = s.items.length - MAX_ITEMS_PER_TASK;
+        let freed = 0;
+        for (let i = 0; i < cut; i++)
+            freed += s.itemBytes[i] ?? 0;
+        s.items.splice(0, cut);
+        s.itemBytes.splice(0, cut);
+        addBytes(s, -freed);
+        // 条数帽丢掉的同样是**内容**,同样要留痕(此前这条路是无声的)。
+        noteDropped(s, freed);
         // open-tool indexes shifted — rebuild from the surviving items
-        s.openTools.clear();
-        s.items.forEach((it, i) => {
-            if (it.kind === 'tool' && it.output === undefined)
-                s.openTools.set(it.id, i);
-        });
+        rebuildOpenTools(s);
     }
 }
 /** Close out streaming buffers into items (segment boundary: a tool starts, or the run settles). */
 function flushBuffers(s) {
-    if (s.thinkBuf.trim())
-        pushItem(s, { kind: 'thinking', text: s.thinkBuf });
+    // 🔴 缓冲的字节此前已经计过账;搬进 item 时先扣掉缓冲那一份,再由 pushItem 计 item 那一份
+    //    (纯空白段被丢弃时同样要扣 —— 少扣一次,总账就会一路虚高到把别人的账本淘汰掉)。
+    addBytes(s, -utf8Len(s.thinkBuf));
+    const think = s.thinkBuf;
     s.thinkBuf = '';
-    if (s.textBuf.trim())
-        pushItem(s, { kind: 'text', text: s.textBuf });
+    if (think.trim()) {
+        pushItem(s, { kind: 'thinking', text: think });
+        rememberSegment(s, think);
+    }
+    addBytes(s, -utf8Len(s.textBuf));
+    const text = s.textBuf;
     s.textBuf = '';
+    if (text.trim()) {
+        pushItem(s, { kind: 'text', text });
+        rememberSegment(s, text);
+    }
+}
+/** 有界 FIFO 记号(两本小账共用;只用来做幂等判定,不参与预算)。 */
+const MAX_REPLAY_KEYS = 64;
+function remember(set, key) {
+    if (set.has(key))
+        return;
+    if (set.size >= MAX_REPLAY_KEYS) {
+        const oldest = set.values().next().value;
+        if (oldest !== undefined)
+            set.delete(oldest);
+    }
+    set.add(key);
+}
+function rememberSegment(s, text) {
+    remember(s.recordedSegments, text);
 }
 function scheduleNotify(taskId) {
     pendingNotify.add(taskId);
@@ -196,6 +493,9 @@ function aliasContentKey(parentToolCallId, taskId) {
         pendingNotify.add(taskId);
     const parked = tasks.get(parentToolCallId);
     if (parked && !tasks.has(taskId)) {
+        // 🔴 这是**换键**不是删除:同一本账换个键继续用,内容一个字节都没走 ⇒ 这里**不许**走
+        //    {@link dropTask}(那一口会把它的字节从总账里扣掉,而字节还在)。扣了之后总账会一路虚低,
+        //    总帽从此形同虚设。删除只有三个口:clearSubagentContent / 条数淘汰 / 总帽淘汰。
         tasks.delete(parentToolCallId);
         tasks.set(taskId, parked);
         scheduleNotify(taskId);
@@ -211,6 +511,101 @@ export function registerSubagentAlias(parentToolCallId, taskId) {
         return;
     taskToParent.set(taskId, parentToolCallId);
 }
+/**
+ * 这一条**聚合帧**是不是「已经收下过的那一条」(durable 重放的两道闸;命中 ⇒ 整帧丢弃)。
+ *
+ * 🔴 工具两臂**同一条判据形、不同的身份**:它们不进这一口(见 publish 的工具两臂),因为
+ *    `toolCallId` 就是那次调用的身份、账本就是 `items` 自己 —— 比一本有界 FIFO 强,也不占它的额度。
+ *
+ * 为什么光靠缓冲前缀吸收不够(异源复审逼出的真病):吸收规则只认**当前缓冲**那一段。一条
+ * 跨过工具边界的 turn,早先那些段早就段闭合成 item、缓冲已空 —— 重放时它们的聚合帧再来一遍,
+ * `''` 是任何串的前缀,于是整段被当成新内容塞回缓冲,而且塞在**后面那段**之后(顺序也是错的)。
+ *
+ * 两道闸,顺序刻意如此:
+ *   ① **事件身份**(`eventId`)—— 精确、无损:同一条账本帧重放多少次都只收一次。
+ *   ② **整段内容**(`recordedSegments`)—— 兜底:上游没给身份、或本进程这条流是重连后新起的
+ *      (身份没在这本账上留过),内容判据仍拦得住「这一段已经上过屏」。
+ * 📋 **如实留白**:闸 ② 的代价是——一条 turn 里出现**两段逐字节相同**的正文时,durable 腿上只会
+ *    留下一段。取舍是明写的:每次重连都把整轮正文再渲一遍是**必然**发生的用户可见损坏,而
+ *    「同一条 turn 里说了两遍一模一样的话」是罕见形,且活体腿上两段都在。
+ */
+function replaySeen(s, ev) {
+    const id = ev.eventId;
+    if (typeof id === 'string' && id.length > 0) {
+        if (s.seenAggregateIds.has(id))
+            return true;
+        remember(s.seenAggregateIds, id);
+    }
+    const body = ev.text;
+    if (typeof body === 'string' && s.recordedSegments.has(body))
+        return true;
+    return false;
+}
+/**
+ * 这一发工具帧比卡上现在承载的那一阶段**旧或一样**吗(旧 ⇒ 整帧丢弃)。
+ *
+ * 判据是 `eventId` 的字典序 —— 前提是它**时间可排序**(core 铸的 uuidv7,sdk `EventIdentity` 逐字)。
+ * 两侧任一缺席 ⇒ 判不出新旧,答 `false`(退回「后到的落账」:重放送的是同一份值,落账是空操作)。
+ * 逐字相等 ⇒ 同一条帧又来一遍 ⇒ 同样答 `true`(整帧丢弃,一次也不重复落账)。
+ */
+function notNewer(eventId, mark) {
+    if (typeof eventId !== 'string' || eventId.length === 0)
+        return false;
+    if (typeof mark !== 'string' || mark.length === 0)
+        return false;
+    return eventId <= mark;
+}
+/** 读一张卡的阶段水位(没有 ⇒ 这张卡还没落过对应那一半的帧)。 */
+function phaseOf(s, id) {
+    return id === undefined ? undefined : s.toolPhase.get(id);
+}
+/** 抬一张卡的阶段水位(身份缺席 ⇒ 不抬:一个抬不动的水位比一个抬错的水位诚实)。 */
+function markPhase(s, id, half, eventId) {
+    if (id === undefined || typeof eventId !== 'string' || eventId.length === 0)
+        return;
+    const cur = s.toolPhase.get(id);
+    if (cur === undefined) {
+        s.toolPhase.set(id, { [half]: eventId });
+        return;
+    }
+    cur[half] = eventId;
+}
+/**
+ * 这条 `toolCallId` 在本账本里已经有卡了吗(有 ⇒ 返回下标,没有 ⇒ `-1`)。
+ *
+ * 🔴 为什么账本就是 `items` 自己、不另铸第三本小账:一次工具调用的卡**在不在屏上**只有 `items`
+ *    说了算。另开一本记号账就会有两处真源,而它们脱节的方式是可预期的 —— 条数帽/字节帽把卡丢掉
+ *    之后记号还在,重放于是被永久挡住,屏上那一格从此空着且无人知道。这里逐条问 `items`,
+ *    答案与屏上看到的恒等(上限 200 条,每帧一次线性扫,量级可忽略)。
+ * 🔴 从尾往前找:同一 id 的卡至多一张(本闸的作用就是维持这条),从尾找只是让常见形(刚落的那张)
+ *    第一下命中。
+ */
+function toolCardIndexOf(s, id) {
+    for (let i = s.items.length - 1; i >= 0; i--) {
+        const it = s.items[i];
+        if (it?.kind === 'tool' && it.id === id)
+            return i;
+    }
+    return -1;
+}
+/**
+ * 聚合帧对当前缓冲的**吸收判定**(两个聚合臂共用一份;`null` = 这一帧整只丢弃)。
+ *
+ * 三形,顺序刻意如此:
+ *   ① 缓冲是全文的**前缀**(缓冲为空时同样成立)⇒ 换成全文 —— 活体已流过的那半段被这一份接管,
+ *      同一条帧重复送达因此**幂等**(全文以自己为前缀)。
+ *   ② 缓冲是全文被**预算裁过**的尾巴(全文以缓冲结尾)⇒ **丢弃这一帧**。没有这一条,一段已经被
+ *      裁掉头部的正文,每重放一次就会被整只追加回来:内容重复、顺序错乱,而且截尾统计会一路虚涨
+ *      (裁掉的字节被反复重算)——「丢了多少」那个数会变成一句假话。
+ *   ③ 两者都不是 ⇒ 真分岔,退回**追加**、两段都留下(少渲一段比替引擎判定「哪一段才算数」更坏)。
+ */
+function absorbAggregate(buf, agg) {
+    if (agg.startsWith(buf))
+        return agg;
+    if (buf.length > 0 && agg.endsWith(buf))
+        return null;
+    return buf + agg;
+}
 function canonicalKey(ev) {
     // the wire's content events carry no taskId — runStream passes parentToolCallId in both slots
     if (ev.taskId !== ev.parentToolCallId)
@@ -222,44 +617,157 @@ export function publishSubagentContentEvent(ev) {
     const s = stateFor(key, ev.parentToolCallId);
     switch (ev.type) {
         case 'text_delta':
-            if (typeof ev.delta === 'string')
+            if (typeof ev.delta === 'string') {
+                // 🔴 增量按**拼接边界**记账(见 appendBytes:代理对被拆成两帧时按 chunk 单算会永久虚高)。
+                addBytes(s, appendBytes(s.textBuf, ev.delta));
                 s.textBuf += ev.delta;
+            }
             break;
         case 'reasoning_delta':
-            if (typeof ev.delta === 'string')
+            if (typeof ev.delta === 'string') {
+                addBytes(s, appendBytes(s.thinkBuf, ev.delta));
                 s.thinkBuf += ev.delta;
+            }
+            break;
+        // ── 聚合两臂(durable 重放腿:一段的权威全文)──────────────────────────────────────────
+        // 🔴 **吸收**而不是追加:活体已经流过的那一段是这一段全文的**前缀**,追加会让同一段内容
+        //    上屏两遍(缝前的事件序号去重管不到这一形——聚合帧与那串增量帧是不同的事件身份)。
+        //    · 全文以当前缓冲为前缀 ⇒ 缓冲整体换成全文(活体流过 0 字节时同样成立,`''` 是任何串的前缀);
+        //      同一条聚合帧重复送达时因此是**幂等**的(全文以自己为前缀)。
+        //    · 前缀对不上(理论上不该发生:同段的两次不同陈述)⇒ 退回**追加**的老语义并把两段都留下,
+        //      少渲一段比替引擎判定「哪一段才算数」更诚实。
+        // 🔴 不在这里段闭合:段边界仍由 tool_start / settle 给,与活体腿逐字同一条 —— 在这里 flush
+        //    会让「同一段的第二次重放」落成第二个 item(缓冲已空,吸收规则就没有前缀可比了)。
+        case 'text':
+            if (typeof ev.text === 'string' && ev.text.length > 0 && !replaySeen(s, ev)) {
+                const next = absorbAggregate(s.textBuf, ev.text);
+                if (next !== null) {
+                    // 吸收/追加两形都可能改变缓冲长度 ⇒ 按**差额**记账(不是按帧长度加)。
+                    const before = utf8Len(s.textBuf);
+                    s.textBuf = next;
+                    addBytes(s, utf8Len(s.textBuf) - before);
+                }
+            }
+            break;
+        case 'reasoning':
+            if (typeof ev.text === 'string' && ev.text.length > 0 && !replaySeen(s, ev)) {
+                const next = absorbAggregate(s.thinkBuf, ev.text);
+                if (next !== null) {
+                    const before = utf8Len(s.thinkBuf);
+                    s.thinkBuf = next;
+                    addBytes(s, utf8Len(s.thinkBuf) - before);
+                }
+            }
             break;
+        // ── 工具两臂(活体与 durable 重放送的是同一形)────────────────────────────────────────
+        // 🔴 与聚合两臂**同一条判据形**(先问身份、再问账本),但身份与账本都换成工具自己的那一套:
+        //    身份 = `toolCallId`(wire 给的那次调用的 id),账本 = `items` 自己(见 toolCardIndexOf)。
+        //    刻意**不写** `seenAggregateIds`:那本记号账是有界 FIFO,额度按「聚合帧只在重放腿上来」定的
+        //    (活体走 `*_delta`,一个字都不写);工具帧**活体也来**,跟着写会把还在屏上的散文身份整窗
+        //    挤掉 —— 修一个臂的重放去重、弄坏另一个臂的,不是修。
+        // 🔴 顺序上「开着的卡恒收口」排在最前:一张在飞的卡如果被任何一道闸拦掉收口,它就**永远在飞**
+        //    (屏上显示成还在跑),而那比多渲一次结果坏得多。
         case 'tool_start': {
+            const startId = ev.toolCallId;
+            const seen = startId !== undefined && toolCardIndexOf(s, startId) >= 0;
+            if (seen && notNewer(ev.eventId, phaseOf(s, startId)?.start))
+                break;
+            // 段闭合可能触发条数裁剪(pushItem 从头 splice + unshift 留痕)⇒ 裁剪**前**取的下标与引用一律
+            // 作废:flush 之后按 toolCallId **重新**找卡。找不到 = 这张卡刚被裁掉 ⇒ 落到下面「新的一次」
+            // 建卡那一支(§26b 留白①),绝不对着已删的引用改名补参、也绝不把差额记到顶上那条留痕上。
+            if (seen && phaseOf(s, startId)?.start === undefined)
+                flushBuffers(s);
+            const at = startId !== undefined ? toolCardIndexOf(s, startId) : -1;
+            if (at >= 0) {
+                // 这次调用的卡已在账 ⇒ **不铸第二张**。剩下的两件按阶段水位判:
+                // 🔴 ① 这一发比卡上现在承载的那一阶段旧(或就是同一条帧又来一遍)⇒ 整帧丢弃。少了这一条,
+                //    门 park 那一阶段的 start 重放会把批复时**改过的执行参数**盖回原参数 —— 屏上就成了
+                //    「这个参数产生了那个结果」,而那个结果根本不是它跑出来的。
+                // 🔴 ② 这张卡有没有落过 `tool_start`:收口先到时下面那支会合成一张占位卡(名字 `Tool`、
+                //    参数 `{}`),那张卡**没有** start 水位 —— 迟到的这一发是它的**第一个段边界**,要补做
+                //    一次段闭合(不补的话工具前后两段散文会黏成一段、且一段都进不了已上屏正文那本记号账,
+                //    随后整轮重放时两段都拦不住)。反过来,水位已在 = 这一发是重放或下一阶段,**不**段闭合:
+                //    边界在活体那一轮已经给过,在这里切开会把还在流的那一段提前截断。
+                // 名字与参数就地补齐/更新(重放送来的是同一份值,补齐是空操作;字节按**差额**记账)。
+                const it = s.items[at];
+                const before = itemBytesOf(it);
+                if (ev.toolName !== undefined)
+                    it.name = ev.toolName;
+                if (ev.args !== undefined)
+                    it.input = ev.args;
+                const delta = itemBytesOf(it) - before;
+                s.itemBytes[at] = (s.itemBytes[at] ?? 0) + delta;
+                addBytes(s, delta);
+                markPhase(s, startId, 'start', ev.eventId);
+                break;
+            }
             flushBuffers(s);
-            const id = ev.toolCallId ?? `${ev.taskId}-tool-${s.items.length}`;
+            const id = startId ?? `${ev.taskId}-tool-${s.items.length}`;
             pushItem(s, { kind: 'tool', id, name: ev.toolName ?? 'Tool', input: ev.args ?? {} });
             s.openTools.set(id, s.items.length - 1);
+            markPhase(s, id, 'start', ev.eventId);
             break;
         }
         case 'tool_end': {
             const id = ev.toolCallId;
             const idx = id !== undefined ? s.openTools.get(id) : undefined;
             if (idx !== undefined && s.items[idx]?.kind === 'tool') {
+                // 卡还开着 ⇒ 结果照落。这一支**排在所有闸之前**:一张在飞的卡被任何一道闸拦掉收口,
+                // 它就永远显示成还在跑,那比多渲一次结果坏得多。
                 const it = s.items[idx];
                 it.output = ev.output ?? '';
                 it.isError = ev.isError === true;
+                // 结果正文是**这一刻**才落到已在账的那条 item 上的 ⇒ 补记它的字节。
+                const add = utf8Len(it.output);
+                s.itemBytes[idx] = (s.itemBytes[idx] ?? 0) + add;
+                addBytes(s, add);
                 if (id !== undefined)
                     s.openTools.delete(id);
+                markPhase(s, id, 'end', ev.eventId);
+                break;
             }
-            else {
-                // orphan close (start lost to the ring / arrived first) — synthesize a resolved card
-                pushItem(s, {
-                    kind: 'tool',
-                    id: id ?? `${ev.taskId}-tool-${s.items.length}`,
-                    name: ev.toolName ?? 'Tool',
-                    input: ev.args ?? {},
-                    output: ev.output ?? '',
-                    isError: ev.isError === true,
-                });
+            const settledAt = id !== undefined ? toolCardIndexOf(s, id) : -1;
+            if (settledAt >= 0) {
+                // 卡在账、却已不在「开着」表上 = 这次调用的结果**早就落过**。两种可能,判据是阶段水位:
+                //   · 比卡上现在那一份**旧或就是同一条帧**(durable 重放 / 旧一阶段迟到)⇒ 整帧丢弃 ——
+                //     再落一次会把结果字节重复计进预算,走到下面那支还会另铸一张已完成的卡;更坏的是
+                //     旧一阶段会把屏上的真结果盖回去;
+                //   · **更新的一发**收口(门 park 掉这次调用、批复后恢复执行,上游按同一个 `toolCallId`
+                //     再发一对 start/end)⇒ **后到的才是真结果**,就地替换。把「已 settled」当成永久完成
+                //     会把真结果吞掉,屏上停在那句「被门拦下」上。
+                // 🔴 身份缺席(判不出新旧)时走替换那一支:重放送的是同一份值,替换是空操作(差额恒 0)。
+                if (notNewer(ev.eventId, phaseOf(s, id)?.end))
+                    break;
+                const it = s.items[settledAt];
+                const before = itemBytesOf(it);
+                it.output = ev.output ?? '';
+                it.isError = ev.isError === true;
+                const delta = itemBytesOf(it) - before;
+                s.itemBytes[settledAt] = (s.itemBytes[settledAt] ?? 0) + delta;
+                addBytes(s, delta);
+                markPhase(s, id, 'end', ev.eventId);
+                break;
             }
+            // orphan close (start lost to the ring / arrived first) — synthesize a resolved card.
+            // 🔴 这里**不**段闭合:段边界由 `tool_start` 给(收口先到时那一发迟到的 start 会补做,见上)。
+            //    在这里闭合会把**还在流的**那一段提前切成 item —— 每子代帽配得很紧时,那一段随即变成
+            //    「最早的内容」而被帽整只丢掉,而它其实是用户眼前正在看的字。
+            const synthId = id ?? `${ev.taskId}-tool-${s.items.length}`;
+            pushItem(s, {
+                kind: 'tool',
+                id: synthId,
+                name: ev.toolName ?? 'Tool',
+                input: ev.args ?? {},
+                output: ev.output ?? '',
+                isError: ev.isError === true,
+            });
+            markPhase(s, synthId, 'end', ev.eventId);
             break;
         }
     }
+    // 两道帽在**每一次写入之后**执行(不是定时扫):越限那一刻就丢,账本永远不会先胀起来再回落。
+    enforceTaskCap(s);
+    enforceTotalCap(key);
     scheduleNotify(key);
 }
 /** 查看态 composer echo (C2 steer optimistic display) — segment-closes the buffers first so the echo
@@ -269,6 +777,8 @@ export function pushSubagentLocalEcho(taskId, text) {
     const s = stateFor(taskId, tasks.get(taskId)?.parentToolCallId ?? '');
     flushBuffers(s);
     pushItem(s, { kind: 'echo', text });
+    enforceTaskCap(s);
+    enforceTotalCap(taskId);
     scheduleNotify(taskId);
 }
 export function getSubagentContentSnapshot(taskId) {
@@ -310,6 +820,9 @@ export function planSubagentViewSlots(taskId) {
         else if (it.kind === 'thinking') {
             out.push({ kind: 'thinking', slot: `k${i}`, text: it.text });
         }
+        else if (it.kind === 'truncated') {
+            out.push({ kind: 'truncated', slot: `x${i}`, droppedBytes: it.droppedBytes, keptFrom: it.keptFrom });
+        }
         else {
             out.push({ kind: 'echo', slot: `e${i}`, text: it.text });
         }
@@ -336,7 +849,7 @@ export function settleSubagentContent(taskId) {
     scheduleNotify(taskId);
 }
 export function clearSubagentContent(taskId) {
-    tasks.delete(taskId);
+    dropTask(taskId); // 唯一删除口:字节同拍从总账里扣掉
 }
 const bgFacts = new Map();
 export function recordBgTerminalFacts(taskId, facts) {