docs(session): correct the events page and activation wording

2026-10-25 19:36:04 +08:00
1 parent 7c7b021766
commit 12a8c3adf7
@@ -33,8 +33,8 @@
  en: 03e24cdee8519a92
  zh: 82dc02eb26d7d7f4
 /agent-note-session-history-control-state-and-remote-event-transport/decision/session-controller/session-journal:
-  en: bb710f8cf35f2028
-  zh: aae2cfb8cd848069
+  en: 4de2965717900b96
+  zh: 1d129003824fa6bd
 /agent-note-session-history-control-state-and-remote-event-transport/decision/session-controller/session-live-control:
  en: a11d627cd68650c3
  zh: 9aff565b9f712853
@@ -174,9 +174,9 @@ Reading titles, lists, and projections does not require an Agent. An observation

 #### Session journal

-`session.page` returns a history window clipped on message boundaries with contiguous internal sequence numbers. Every request must carry an explicit `throughSeq`; this value comes from the corresponding `session.follow` generation's opening cursor and fixes the read at the same log cut. A tail page without `beforeSeq` must end exactly at `throughSeq`, where `-1` denotes an empty log. `beforeSeq` only selects an older page before that cut and cannot replace the synchronization cursor. `maxMessages` limits user/assistant message count without dropping chunks, tools, or state events between those messages.
+`session.events` returns a history window clipped on message boundaries with contiguous internal sequence numbers. `throughSeq` is optional: when omitted, the read selects the observed log end and returns it as the page's inclusive `cursor`; a supplied value fixes the read at that cut. A page without `beforeSeq` ends exactly at the selected cut, where `-1` denotes an empty log. `beforeSeq` only selects an older page before that cut and cannot replace the synchronization cursor. `maxMessages` limits user/assistant message count without dropping chunks, tools, or state events between those messages. The deprecated `session.page` entry returns the same type.

-The tail page also carries a projection baseline no later than `throughSeq`; older pages carry only historical entries. The Client merges pages and subsequent live control updates by projection watermark.
+A page carries only its records, `hasMore`, and inclusive `cursor`; a projection baseline comes from a follow opening snapshot or the control stream, never from a page. The Client merges pages and subsequent live control updates by projection watermark.

 Ordinary Sessions and direct subagents use one `SessionAddress` protocol. A direct-subagent address carries parent Session, child Session, and mode; a cold Host read verifies durable ownership and descriptor rather than authorizing access from the child id alone.

@@ -174,9 +174,9 @@ Session Remote 方法传递 `SessionId` 或 `SessionAddress`，不靠参数类

 #### Session 日志

-`session.page` 返回一段按消息边界裁剪、内部 seq 连续的历史窗口。每个请求必须显式携带 `throughSeq`；该值来自对应 `session.follow` generation 的 opening cursor，并把本次读取固定在同一个日志切点。无 `beforeSeq` 的 tail page 必须精确结束于 `throughSeq`，其中 `-1` 表示空日志；`beforeSeq` 只选择该切点之前的更早页面，不能替代同步 cursor。`maxMessages` 限制 user／assistant 消息数，不丢弃这些消息之间的 chunk、tool 或状态事件。
+`session.events` 返回一段按消息边界裁剪、内部 seq 连续的历史窗口。`throughSeq` 可省略：省略时选取观察到的日志末尾，并把该切点作为页面的 inclusive `cursor` 返回；显式提供时把本次读取固定在该切点。无 `beforeSeq` 的 page 精确结束于所选切点，其中 `-1` 表示空日志；`beforeSeq` 只选择该切点之前的更早页面，不能替代同步 cursor。`maxMessages` 限制 user／assistant 消息数，不丢弃这些消息之间的 chunk、tool 或状态事件。已弃用的 `session.page` 入口返回同一类型。

-tail page 同时携带不晚于 `throughSeq` 的 projection baseline；旧页只携带历史 entries。Client 以 projection watermark 合并 page 与后续 live control 更新。
+page 只携带记录、`hasMore` 和 inclusive `cursor`；projection baseline 来自 follow 的开场快照或 control 流，不来自 page。Client 以 projection watermark 合并 page 与后续 live control 更新。

 普通 Session 与 direct subagent 使用同一个 `SessionAddress` 协议。direct subagent 地址同时携带父 Session、子 Session 与 mode，Host 冷读时验证持久 ownership 和 descriptor，不能只凭 child id 越权读取。

@@ -30,8 +30,8 @@
  en: 9d2d50cb76754b74
  zh: 9ceed3652475f18d
 /agent-note-historical-session-reads-prepare-before-write-publication/decision/follow-and-agent-promotion:
-  en: 301b18b0952f4896
-  zh: 2e3941c35907d629
+  en: 46da45b9b63e7298
+  zh: 3d55099479a80bd9
 /agent-note-historical-session-reads-prepare-before-write-publication/problem-to-solution-mapping:
  en: e067e187cd4d0a8c
  zh: b0c79b635a637296
@@ -102,7 +102,7 @@ No external caller can append before the handle exists. `append`, `flush`, and `

 ### Follow and Agent promotion

-`session.follow` opens history through the read path, restores the Session and projections, starts Agent promotion from the separately retained Observation, and then delivers the opening snapshot. Agent resume uses write open, so it waits for publication before the Agent accepts a new turn. History visibility and write readiness are separate timing points without introducing an unpublished append state.
+`session.follow` opens history through the read path, restores the Session and projections, starts Agent promotion from the separately retained Observation when the caller requests activation, and then delivers the opening snapshot. Agent resume uses write open, so it waits for publication before the Agent accepts a new turn. History visibility and write readiness are separate timing points without introducing an unpublished append state.

 ## Problem-to-solution mapping

@@ -102,7 +102,7 @@ Handle 返回前，外部 caller 无法 append。因此 `append`、`flush` 与 `

 ### Follow 与 Agent promotion

-`session.follow` 通过 read path 打开历史、恢复 Session 与 projections，先用单独 retain 的 Observation 启动 Agent promotion，再交付 opening snapshot。Agent resume 使用 write open，因此会在 Agent 接收新一轮对话前等待 publication。历史可见与写入就绪成为两个明确时间点，同时不引入 unpublished append state。
+`session.follow` 通过 read path 打开历史、恢复 Session 与 projections，在调用方请求激活时先用单独 retain 的 Observation 启动 Agent promotion，再交付 opening snapshot。Agent resume 使用 write open，因此会在 Agent 接收新一轮对话前等待 publication。历史可见与写入就绪成为两个明确时间点，同时不引入 unpublished append state。

 ## 问题与方案对照

@@ -632,7 +632,10 @@ export interface SessionWaitValue {
  readonly output: SessionWaitOutput
 }

-/** One `session.history` page and its inclusive cut: the supplied `throughSeq`, otherwise the log end it was read at. */
+/**
+ * One `session.events` page (or its deprecated `page` alias) with its inclusive cut:
+ * the supplied `throughSeq`, otherwise the log end it was read at.
+ */
 export interface SessionEventsPage extends SessionPage {
  readonly cursor: number
 }
@@ -65,7 +65,7 @@ describe('plan history resource', () => {
    expect(await read(b.provider, address, controller.signal)).toEqual([])
    expect(b.events).not.toHaveBeenCalled()
  })
-  it('reports page failures with their Remote code', async () => {
+  it('reports an opening events failure with its Remote code', async () => {
    const b = setup([])
    const error = new RemoteError('plan/read-failed', 'connection lost', {})
    b.events.mockResolvedValueOnce({ ok: false, error })