@epoch-agent/view 2.8.0 → 3.0.0

package/README.md

@@ -21,6 +21,19 @@
 | `DIFF_CONTEXT_LINES` / `DIFF_MAX_LINES`   | 折叠与截断的阈值（后者的口径见下）                   |
 | `HistoryItem*` / `ToolDisplayItem` 等类型 | item 的判别联合                                      |
 
+## 展示项的 `at`：那句话是什么时候说的（2026-10-27）
+
+`HistoryItemBase` 上多了一格 `at?: number`（epoch 毫秒），和 `seq` 并列：`seq` 是
+**锚点**（从哪儿开始），`at` 是**人读的那一半**（屏幕上那句 `8月25日 13:31`）。
+
+- 它从 `StreamEventMeta.at` 进来（`applyStreamEvent` 的第三个参数），**只在新建项
+  时落一次** —— 同 `seq`：追加进已有项时不覆盖，否则时间会跟着流式往后漂
+- **TUI 一个都不传**（它吃裸事件，没有信封也没有那个形态），所以那边恒缺席
+- **缺席时不补**：那是「不知道」，不是「现在」—— 宿主不许拿 `Date.now()` 兜底
+
+回放（`GET /messages`）那条路不经过 `applyStreamEvent`，它从
+`WireReplayMessage.timestamp` 自己填一次（`web/src/state/replay.ts`）。
+
 ## 行级 diff 的两个口径（2026-10-09）
 
 | 事                      | 口径                                                                                              |

package/dist/index.d.ts

@@ -23,6 +23,28 @@ import { WireSessionReference, WireFileReference, WireImageReference, EpochUserC
 
 interface HistoryItemBase {
     text?: string;
+    /**
+     * 这一项**是什么时候**的（epoch 毫秒，来自 `WireEnvelope.ts`）。2026-10-27 加。
+     *
+     * ## 只为一件事：把它印在屏幕上
+     *
+     * `seq` 回答「从哪儿开始」（锚点），这一个是**人读的那一半** —— 用户那一段话
+     * 底下那句话（`8月25日 13:31`），以及回合脚注右端那一格。两处都只认一个数，
+     * 而它必须在这一项**被造出来的那一刻**冻进来：事后再问「这句话是什么时候说的」
+     * 已经问不出来了（`history` 只存展示项，不存帧）。
+     *
+     * ## 三处它**没有值**（调用方必须当它可能不存在）
+     *
+     * 1. **TUI** —— 那边吃裸 `AgentEvent`，没有信封，也没有这个形态（同 `seq`）；
+     * 2. **回放**（`GET /messages`）—— 走 `WireReplayMessage.timestamp` 另填一次，
+     *    不是「没有」；真的没有的是老版本宿主自己拼的项；
+     * 3. **一轮里由多帧合成的项**取的是**第一帧**（同 `seq` 的口径：要回答
+     *    「这项从哪开始的」，用最后一帧会让时间跟着流式往后漂）。
+     *
+     * ⚠️ **缺席时不许补一个「现在」**：老历史的时间是**不知道**，印一个刚读的
+     * 挂钟等于给一条两年前的记录盖上今天的日期 —— 那比不画贵得多。
+     */
+    at?: number;
     /**
      * 这一项**从哪一帧开始**的广播序号（`WireEnvelope.seq`）。
      *
@@ -277,6 +299,8 @@ interface StreamReduceResult {
 interface StreamEventMeta {
     /** `WireEnvelope.seq`。TUI 不传（它吃的是裸事件，没有信封） */
     seq?: number;
+    /** `WireEnvelope.ts`（epoch 毫秒）—— 屏幕上那个日期时间。TUI 同 `seq` */
+    at?: number;
 }
 /**
  * 把一个事件折叠进当前状态。纯函数：不改入参，返回新数组。

package/dist/index.js

@@ -1,6 +1,9 @@
 // src/reducer.ts
 function anchor(meta) {
-  return meta?.seq !== void 0 ? { seq: meta.seq } : {};
+  return {
+    ...meta?.seq !== void 0 ? { seq: meta.seq } : {},
+    ...meta?.at !== void 0 ? { at: meta.at } : {}
+  };
 }
 var LIVE_TAIL_LINES = 20;
 var LIVE_TAIL_CHARS = 4e3;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-agent/view",
-  "version": "2.8.0",
+  "version": "3.0.0",
   "private": false,
   "description": "epoch-agent 展示层纯逻辑：AgentEvent → 可渲染 item，tui 与 web 共用",
   "repository": {
@@ -22,7 +22,7 @@
     "dist"
   ],
   "dependencies": {
-    "@epoch-agent/protocol": "2.8.0"
+    "@epoch-agent/protocol": "3.0.0"
   },
   "devDependencies": {
     "tsup": "^8.3.6",