@epoch-agent/core 0.8.1 → 0.10.0

package/README.md

@@ -241,6 +241,34 @@ clone 下来一个仓库就能让我们跑它写的命令。而它还多一层
 `isContextNearlyFull()`。`shouldCompress()` 用的就是它们，设置页画的也是它们 ——
 两处各写一遍乘法的症状是「界面说还早、引擎已经压了」。
 
+## 线有两条，闸有三道（2026-09-10）
+
+上面那条是**软线**（省钱：该压了）。2026-09-10 起还有一条**硬线**
+（`isPromptOversize`，窗口的 0.9，同样在 protocol），它问的是另一件事：
+**这一发还发得出去吗。**
+
+| 闸                               | 吃哪个数              | 越线之后                                  |
+| -------------------------------- | --------------------- | ----------------------------------------- |
+| 轮间压缩（`maybeCompress`）      | provider 报的提示词   | 软线交给 `shouldCompress`；**硬线不认它** |
+| 第一发送出去之前（`turn === 1`） | `estimateRunTokens()` | 只判硬线（估算偏，拿它触发软线会白压）    |
+| provider 报 `1030` 之后          | —                     | 压一次重发一次，**一次 run 只一次**       |
+
+三条读代码时必须知道的：
+
+- **硬线不认冷却期和熔断。** 那两道是省钱用的闸，「只会让压缩更晚发生」这条性质
+  在软线上安全、在窗口边缘不安全：一个刚起的进程 `turnsSinceCompress` 是 0，
+  于是 `--resume` 接回长会话之后头 5 发一次都不压 —— 而第 1 发就是最大的那一发；
+- **第一发那道是唯一在「provider 还没报过任何数」时也有话说的**，因为它拿的是
+  估算（`run-estimate.ts` 那四项：system + 工具定义 + 消息 + 图片）；
+- **`1030` 那道有上限**：压缩器的尾部预算跟着 `contextLength` 走（≈ 窗口 15%），
+  能力表虚报 10 倍以上时它压完等于没压。那一档有一条会红的用例
+  （`__tests__/first-send-guard.test.ts`），真修要么改能力表，要么
+  `epoch config set contextLength`。
+
+⚠️ **这三道压的都是「这一次 run 的 messages」，run 一结束就没了。**
+真正会撑爆窗口的那一份（跨消息累积的会话历史）由 runtime 的
+`AgentSession.autoCompact` 管 —— 判据在那儿，别在这一层找。
+
 ⚠️ **`compression.*` 判不进 `SettingsFileSchema` 白名单**，三条判据逐条在
 `config/sources.ts` 文件头（2026-08-16 那一节）。最要紧的一条：仓库作者拿
 `enabled: false` 能让别人在这个仓库里开的长会话悄悄撞满窗口，而症状出现在