From 53046b21b429a15c1ecda9a90fa0c7c9678f7ef8 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Tue, 15 Sep 2026 11:36:52 +0800 Subject: [PATCH] fix(session-controller): reconcile list cache in linear time --- ...-09-15-linear-session-list-cache.i18n.yaml | 6 ++ .../2026-09-15-linear-session-list-cache.md | 25 ++++++++ ...2026-09-15-linear-session-list-cache.zh.md | 25 ++++++++ .../api/session-controller/README.i18n.yaml | 4 +- packages/api/session-controller/README.md | 2 + packages/api/session-controller/README.zh.md | 2 + .../src/client/sessions/manager.ts | 5 +- .../tests/manager.client.spec.ts | 58 +++++++++++++++++++ 8 files changed, 123 insertions(+), 4 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.md create mode 100644 .agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.zh.md diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.i18n.yaml new file mode 100644 index 0000000000..d3b6770fac --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.md +2026-09-15-linear-session-list-cache.md: fb09950f77c224d2b85bb76792bdf8c3c87e33f5 +2026-09-15-linear-session-list-cache.zh.md: b877f0659fff4e1b3d48aa4250e634120ddc365f diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.md b/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.md new file mode 100644 index 0000000000..fb09950f77 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.md @@ -0,0 +1,25 @@ +# Agent Note: Linear Session list cache reconciliation + +Status: implemented + +English | [中文](2026-09-15-linear-session-list-cache.zh.md) + +## Problem + +The Client Session list retains row objects for React reference stability. Scanning the entire new list for every cached ID makes snapshot rebuilds quadratic, including first hydration because new rows enter the cache before cleanup. Thousands of Sessions can occupy the browser thread during list updates. + +## Decision + +SessionManager builds one ID set from its reconciled rows and uses it for cache eviction and selected-row membership. Field comparisons, row identities, array reuse, lineage order, and retained subagent addresses keep their existing semantics. + +## Alternatives considered + +**Replace the row cache on every rebuild.** A new Map can also remove missing entries linearly, but requires changing the row-reuse path. A temporary membership set confines the change to membership checks. + +**Enforce unit-test wall-clock limits.** Shared CI load makes tight time budgets unreliable. An instance-local ID accessor counts membership reads during repeated refreshes; the original implementation exceeds the linear bound without depending on machine speed. + +## Consequences + +Reconciliation uses O(n + c) time and O(n) temporary membership storage for n current rows and c cached rows. Missing rows lose cached identity; unchanged rows and their array retain identity, and an off-list selection candidate can become current again when its row returns. + +Local macOS arm64 Node 26 measurements compile the production manager to JavaScript and time subscribed refreshes through the resulting list snapshot, with fresh synthetic Remote response objects. After three warmups, nine samples give median refresh times of 0.67, 1.40, 2.78, and 5.46 ms for 1,000, 2,600, 5,000, and 10,000 rows. The corresponding original medians are 4.86, 29.01, 30.62, and 459.89 ms. These measurements include list reconstruction and exclude server scanning, transport, DOM rendering, browser input, and memory measurement; they do not establish end-to-end reconnect latency. The focused manager tests cover eviction, empty lists, selection recovery, identity reuse, and the linear read bound. diff --git a/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.zh.md b/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.zh.md new file mode 100644 index 0000000000..b877f0659f --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-09-15-linear-session-list-cache.zh.md @@ -0,0 +1,25 @@ +# Agent Note: Session 列表缓存的线性对账 + +Status: implemented + +[English](2026-09-15-linear-session-list-cache.md) | 中文 + +## 问题 + +Client Session 列表保留行对象,以维持 React 引用稳定性。为每个缓存 ID 扫描整个新列表,会使快照重建成本按平方增长;首次加载也受影响,因为新行在清理之前就已进入缓存。数千个 Session 可能在列表更新时占用浏览器线程。 + +## 决策 + +SessionManager 从对账后的行构建一个 ID 集合,用于缓存淘汰和选中行的成员检查。字段比较、行对象标识、数组复用、派生顺序和保留的子智能体地址维持现有语义。 + +## 考虑过的替代方案 + +**每次重建都替换行缓存。** 新 Map 同样可以在线性时间内移除缺失条目,但需要修改行复用路径。临时成员集合把改动限定在成员检查。 + +**在单元测试中限制实际耗时。** 共享 CI 负载会使严格时间预算不可靠。实例局部的 ID 访问器统计重复刷新时的成员读取次数;原实现超过线性上限,无需依赖机器速度。 + +## 影响 + +对于 n 个当前行和 c 个缓存行,对账使用 O(n + c) 时间和 O(n) 临时成员存储。缺失行失去缓存标识;未变化的行及其数组保留标识,离开列表的候选选中项在行返回后可以再次成为当前项。 + +本地 macOS arm64 Node 26 测量将生产 manager 编译为 JavaScript,并在存在订阅时,从刷新开始计时到结果列表快照可读,Remote 响应使用新建的合成对象。预热三次后采集九个样本,1,000、2,600、5,000 和 10,000 行的刷新耗时中位数分别为 0.67、1.40、2.78 和 5.46 ms。原实现对应中位数为 4.86、29.01、30.62 和 459.89 ms。测量包含列表重建,排除服务端扫描、传输、DOM 渲染、浏览器输入和内存测量,因此不能证明端到端重连延迟。聚焦 manager 的测试覆盖淘汰、空列表、选择恢复、标识复用和线性读取上限。 diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index 2e81443d71..98418465b7 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/session-controller/README.md -README.md: 9b2cdeed600cd597ecfab076fe98a3a334533ba8 -README.zh.md: 04ed7808dc7ea581b489921f88349479d46d8037 +README.md: 1e8089b19c2dcba4691345b44498a37b33670b64 +README.zh.md: ce406f16edea8b47bd584adfa68efea7987510c4 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index 9b2cdeed60..1e8089b19c 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -30,6 +30,8 @@ The Client journal validates exact V3 event envelopes before publishing follow s Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Queue mutation and cancellation require live state; model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the default application. +Client list refreshes retain unchanged row objects and reuse the items array when order and values match. Cache membership checks use a per-refresh ID set, so reconciliation grows linearly with the current list and retained cache sizes. + The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, `append`, and `settle-assistant` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. The Web adapter explicitly opts into cursorless Assistant frames: each opening carries the active attempt's `startedAfterSeq`, `nextIndex`, and compact stream, and every stream member becomes a Client-only `assistant/live-chunk` entry ordered between durable cursors. The Host captures a follower-local arrival ordinal with that baseline and suppresses buffered frames at or before the cut; a replacement Agent may restart frame revision at one. A durable `assistant/message` or `assistant/attempt` arriving after an active opening stays staged only when its seq follows `startedAfterSeq` and its Turn and Step match; the matching end type, seq, and index publishes one named settlement delta that retires the attempt's transient rows and adds the durable entry while earlier same-step retries remain visible. Revision, dense-index, or settlement gaps for a known attempt reopen follow, while a controller that missed the start ignores unknown-attempt frames and publishes their durable settlement normally. An abandoned end publishes a settlement delta without a durable entry so its transient rows retire immediately. A durable gap-repair page has no Assistant baseline, so its held notification reopens follow once for a paired page and baseline. Every history record covers exactly its event seq. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. For each inbox change, the Host publishes the projection frame first and derives the queue replacement from that same validated post-fold value, so listener registration order cannot produce a stale queue frame.Client Agent contexts provide the identity used by the independent [`fileUpload`](../../client/file-upload/README.md) service; Session objects expose lifecycle, prompt, queue, and history operations rather than file transfer. The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. The echo stores ordered image previews and durable file references. Session derives its `transcript`, `queued`, or `steering` placement from the current running state and requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed, immediately when its identified prompt fails or is abandoned, and as failed on disposal. Each retirement fires `onRetire` exactly once; an observed retirement includes the ordered durable attachment references so the composer can release successful cards while preserving failed drafts. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index 04ed7808dc..ce406f16ed 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -30,6 +30,8 @@ Client journal 在发布 follow 快照、live entry 或历史页之前验证精 每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row,绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint;生命周期匹配的 predecessor cache 只能提供版本兼容的 title,作为可能过时的展示事实,绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence;`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。queue 变更与取消要求 live 状态;模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前,拒绝既没有非空白文本也没有附件的 content;queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证,在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时,prompt 重试直接返回原来的接受结果,不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法,以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外:当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child,可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝,且不会恢复。skill 目录优先使用已有 live Agent,否则使用所记录 preset 的常驻 scope,因此列表查询绝不会启动 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器;省略 `action` 时打开默认应用。 +Client 列表刷新保留未变化的行对象,并在顺序和值均相同时复用条目数组。缓存成员检查使用每次刷新构建的 ID 集合,因此对账成本随当前列表和保留缓存的规模线性增长。 + Client 适配器提供 `SessionEventStream`,即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow,只发布连续的 `replace`、`prepend`、`append` 与 `settle-assistant` 变更,并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词:`loadOlder()` 拉一页 50 条消息,而 `loadThrough(seq)`——轮次跳转加载器——按每页 200 条消息循环拉取直到窗口覆盖目标 seq,重复调用会下调共享目标,遇到无进展的页即停止,忙碌状态复用同一个 `loadingOlder` 快照位。Web 适配器显式选择接收无 cursor 的 Assistant frame:每个 opening 携带活跃 attempt 的 `startedAfterSeq`、`nextIndex` 与紧凑 stream,每个 stream member 都成为排在持久 cursor 之间的 Client-only `assistant/live-chunk` 条目。Host 会随该 baseline 捕获 follower 本地到达序号,并抑制该 cut 及之前的 buffered frame;replacement Agent 可以从 revision 一重新开始。活跃 opening 之后到达的持久 `assistant/message` 或 `assistant/attempt` 只有在其 seq 晚于 `startedAfterSeq` 且轮次与步骤匹配时才会保持暂存;匹配的 end type、seq 与 index 会发布一个具名 settlement delta,删除该 attempt 的瞬态 row、加入持久条目,并保留同一步骤中更早的 retry。已知 attempt 的 revision、密集 index 或 settlement 缺口会重新打开 follow;若 controller 错过 start,则忽略 unknown-attempt frame,并正常发布其持久 settlement。Abandoned end 会发布不含持久条目的 settlement delta,使瞬态 row 立即退出。持久缺口修复 page 不携带 Assistant baseline,因此 held notification 会重新打开 follow 一次,以取得配对的 page 与 baseline。每条历史 record 只覆盖自身的事件 seq。业务、persistence 或无法恢复的连续性错误会终止 stream,只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`;每代都以完整的进程本地 baseline 开始,因此重连会替换 queue、jobs 和 projection 状态,而不会把瞬态值当作持久事件。每次 inbox 变更时,Host 会先发布 projection frame,再从同一份已校验的折叠后值派生 queue replacement,因此监听器注册顺序不会产生陈旧的 queue frame。Client Agent 上下文提供独立 [`fileUpload`](../../client/file-upload/README.zh.md) 服务使用的身份;Session 对象提供生命周期、prompt、queue 与历史操作,不提供文件传输。 Session 对象还承载本地提交回显:`session.beginSubmission` 在调用方序列化与提示词之前,同步把一条回显写入 `SessionSnapshot.pendingSubmissions`,会话 UI 因此能在点击提交的当帧显示消息。回显按顺序存放图片预览与持久文件引用。Session 根据当前运行状态与请求的投递模式推导其 `transcript`、`queued` 或 `steering` 位置,并在序列化期间保留该位置。提示词的 `requestId` 是关联标识:Host 把它回显为 durable user source 的 `rpcId`,queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休,带标识的提示词失败或被放弃时立即退休,销毁时按 failed 退休。每次退休恰好触发一次 `onRetire`;observed 退休还会携带有序的持久附件引用,让 composer 释放成功卡片并保留失败草稿。回显只存在于 Client 内存;刷新与重连只从持久事件重建会话。 diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts index fd39fefedf..5843f9816e 100644 --- a/packages/api/session-controller/src/client/sessions/manager.ts +++ b/packages/api/session-controller/src/client/sessions/manager.ts @@ -934,14 +934,15 @@ export class SessionManager { this.entryCache.set(entry.sessionId, entry) return entry }) + const itemIds = new Set(items.map(entry => entry.sessionId)) for (const id of this.entryCache.keys()) { - if (!items.some(e => e.sessionId === id)) this.entryCache.delete(id) + if (!itemIds.has(id)) this.entryCache.delete(id) } const sameOrder = items.length === this.itemsCache.length && items.every((e, i) => e === this.itemsCache[i]) if (!sameOrder) this.itemsCache = items const selected = this.selected const current = selected !== undefined - && (items.some(item => item.sessionId === selected) || this.addresses.has(selected)) + && (itemIds.has(selected) || this.addresses.has(selected)) ? selected : undefined return { diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts index e6ffa43850..71af02e080 100644 --- a/packages/api/session-controller/tests/manager.client.spec.ts +++ b/packages/api/session-controller/tests/manager.client.spec.ts @@ -721,6 +721,64 @@ describe('remaining branches', () => { expect(manager.getListSnapshot().items).toBe(after.items) }) + it('reuses refreshed rows and evicts missing rows while retaining the selection candidate', async ({ mock, remote }) => { + const manager = makeManager(mock, remote, S2) + remote.session.list.mockResolvedValue(ok({ items: [summary(S1), summary(S2)] as never[] })) + await manager.refreshList() + const first = manager.getListSnapshot() + expect(first.current).toBe(S2) + + remote.session.list.mockResolvedValue(ok({ items: [summary(S1), summary(S2)] as never[] })) + await manager.refreshList() + expect(manager.getListSnapshot().items).toBe(first.items) + expect(manager.getListSnapshot().current).toBe(S2) + + remote.session.list.mockResolvedValue(ok({ items: [summary(S1)] as never[] })) + await manager.refreshList() + expect(manager.getListSnapshot().items).toEqual([first.items[0]]) + expect(manager.getListSnapshot().items[0]).toBe(first.items[0]) + expect(manager.getListSnapshot().current).toBeUndefined() + + remote.session.list.mockResolvedValue(ok({ items: [summary(S1), summary(S2)] as never[] })) + await manager.refreshList() + expect(manager.getListSnapshot().items[0]).toBe(first.items[0]) + expect(manager.getListSnapshot().items[1]).not.toBe(first.items[1]) + expect(manager.getListSnapshot().current).toBe(S2) + + remote.session.list.mockResolvedValue(ok({ items: [] as never[] })) + await manager.refreshList() + expect(manager.getListSnapshot().items).toEqual([]) + expect(manager.getListSnapshot().current).toBeUndefined() + + remote.session.list.mockResolvedValue(ok({ items: [summary(S1)] as never[] })) + await manager.refreshList() + expect(manager.getListSnapshot().items[0]).not.toBe(first.items[0]) + }) + + it('bounds cached-row ID reads linearly during repeated list refreshes', async ({ mock, remote }) => { + const count = 1_000 + const summaries = Array.from({ length: count }, (_, i) => summary(`list-${i}` as SessionId)) + const manager = makeManager(mock, remote, summaries[count - 1]!.sessionId) + remote.session.list.mockResolvedValue(ok({ items: summaries as never[] })) + await manager.refreshList() + const first = manager.getListSnapshot() + let reads = 0 + // Instance-local accessors count membership work without a machine-dependent timing budget. + for (const entry of first.items) { + const id = entry.sessionId + Object.defineProperty(entry, 'sessionId', { get: () => { reads++; return id }, configurable: true }) + } + for (let refresh = 0; refresh < 2; refresh++) { + reads = 0 + remote.session.list.mockResolvedValue(ok({ items: summaries.map(item => ({ ...item })) as never[] })) + await manager.refreshList() + const snapshot = manager.getListSnapshot() + expect(snapshot.items).toBe(first.items) + expect(snapshot.current).toBe(summaries[count - 1]!.sessionId) + expect(reads).toBeLessThanOrEqual(count * 3) + } + }) + it('carries parentSessionId from the added event into the lineage row', ({ mock, remote }) => { const manager = makeManager(mock, remote) manager.handleSessionAdded(summary(S1, { blank: true }))