会话保温 dzwalker/dsh-session-keepwarm

dsh-session-keepwarm

让最近用过的会话常驻浏览器，切回来时直接复用已加载的历史，不用重新读取。

Why this exists

Since DSH 0.1.7 the client keeps a session resident only while a SessionReference is outstanding
(see the Client references section of packages/api/session-controller/README.zh.md): a main-view
switch releases the outgoing session, and when the last reference is released the generation — local data, scoped Context and history window — is torn down. Switching back builds a new generation and re-reads the first history page (at least 50 messages across two turn boundaries), which the UI shows as "Loading history…".

This plugin holds one extra reference per recently used session (under its own source key
sessionKeepwarm), so the last release never fires for those sessions. Switching back then reuses
the resident window — Session.open() is idempotent for an already-open session, so no history is fetched again. The set is an LRU capped by the keepWarm setting, which bounds the memory the old "keep everything" behaviour used to spend.

Behaviour

- Watches the sessions.list snapshot: a row that gains retainedBy.mainView > 0 is the session
just switched to; it moves to the front of the LRU and is retained.
- When the LRU grows past keepWarm, the oldest reference is released.
- Plain sessions only; subagent rows keep their own lifecycle.
- Holding a reference keeps client-local data and the history stream only — it never starts or holds a Host Agent.

Settings

The settings form is derived from this plugin's Config schema (profile entry id session-keepwarm):

| key | default | meaning |
| enabled | true | master switch; turning it off releases every held reference |
| keepWarm | 5 | how many recently used sessions stay resident (1–20) |

Boundaries

- Same tab only. The client shares no session state between tabs or browsers (no SharedWorker or
BroadcastChannel), so a second window has its own heap and always loads on first open.
- First open still loads: keep-warm only affects switching back to a session this tab already
visited and still holds.
- Held sessions keep their history in browser memory plus one stream each; a larger keepWarm costs
more memory.

Install

dsh plugin --profile web add dsh-session-keepwarm

Then enable it in the profile. The plugin declares its host contract as
@deepseek-ai/dsh-api-session-controller ^0.1.7-rc.2 || ^0.2.0-rc.1 — the range the
dsh startup gate and the plugin market read — and is tested on DSH 0.1.7-rc.2 and
0.2.0-rc.1.

Build

npm install # esbuild
npm run build

Exit condition

If the DSH client gains a "retain the last N sessions" setting (or an equivalent deferred-teardown
policy), prefer that and remove this plugin.

为什么会有这个插件

从 DSH 0.1.7 起，只有当某个 SessionReference 还没释放时，客户端才会让会话常驻（见 packages/api/session-controller/README.zh.md 的 Client references 一节）：主视图切换会释放切出的会话，最后一个引用释放时，这一代数据——本地数据、作用域内的上下文和历史窗口——就被拆掉。切回来会重建一代数据，重新读取第一页历史（至少 50 条消息，跨两个轮次边界），界面显示为「Loading history…」。

这个插件为每个最近用过的会话多持有一个引用（用自己的来源键 sessionKeepwarm），所以这些会话永远不会触发最后一次释放。切回来时直接复用常驻窗口——Session.open() 对已打开的会话是幂等的，不会再拉历史。这个集合是 LRU，上限由 keepWarm 设置决定，从而限制住旧的「全部保留」行为曾经占用的内存。

行为

- 监听 sessions.list 快照：某一行出现 retainedBy.mainView > 0，说明它就是刚切过去的会话；把它移到 LRU 最前面并保留。
- LRU 超过 keepWarm 时，释放最旧的引用。
- 只处理普通会话；子代理行有自己的生命周期。
- 持有引用只保住客户端本地数据和历史流——绝不会启动或持有 Host Agent。

设置

设置表单由本插件的 Config schema 生成（配置档条目 id 为 session-keepwarm）：

| key | default | meaning |
| enabled | true | master switch; turning it off releases every held reference |
| keepWarm | 5 | how many recently used sessions stay resident (1–20) |

边界

- 仅限同一标签页。 客户端不在标签页或浏览器之间共享会话状态（没有 SharedWorker，也没有 BroadcastChannel），所以第二个窗口有自己的堆，首次打开时照样加载。
- 首次打开仍会加载：keep-warm 只影响切回本标签页访问过、且仍持有的会话。
- 被持有的会话把历史留在浏览器内存里，每个会话再加一条流；keepWarm 越大，内存开销越高。

安装

dsh plugin --profile web add dsh-session-keepwarm

然后在配置档里启用它。插件声明的主机契约是 @deepseek-ai/dsh-api-session-controller ^0.1.7-rc.2 || ^0.2.0-rc.1——也就是 dsh 启动门禁和插件市场读取的范围——并已在 DSH 0.1.7-rc.2 和 0.2.0-rc.1 上测试。

构建

npm install # esbuild
npm run build

退出条件

如果 DSH 客户端将来支持「保留最近 N 个会话」的设置（或等效的延迟拆除策略），请优先用它，并移除本插件。
从 DSH 0.1.7 起，客户端按引用计数管理会话（见 packages/api/session-controller/README.zh.md 的 Client 引用一节）：

引用保活本地会话数据、作用域 Context 和历史流……
最后一个引用释放时，generation 先退出可访问映射，再执行清理。

主视图切换会话时先 retain 新目标、再 release 旧目标；旧会话没有别的持有者时计数归零，那一代（含已解码的历史窗口）被销毁。切回来是新的一代，于是重新拉首页历史（≥50 条消息、跨 ≥2 个 turn），界面上就是「载入历史」。

本插件替最近用过的 N 个会话各持一张凭据（来源键 sessionKeepwarm），让它们的最后一个引用永远不归零：同一标签页内切走再切回零重读、瞬间复用（Session.open() 对已打开会话是幂等的）——同时 LRU 上限保证内存有界，不像旧模型那样无限保留。

行为

- 观测 sessions.list 快照：某行出现 retainedBy.mainView > 0 即视为「刚被切过去的会话」，推到 LRU 头部并 retain；
- LRU 超出 keepWarm 时释放最旧的引用；
- 只处理普通会话；子代理行有自己的生命周期，不保活；
- 只保活客户端本地数据与历史流，不会启动或持有 Host Agent。

配置

设置表单由本插件的 Config schema 派生（条目 id session-keepwarm）：

| 字段 | 默认 | 含义 |
| enabled | true | 总开关；关闭即释放全部引用 |
| keepWarm | 5 | 保活几个最近用过的会话（1–20） |

边界（做不到什么）

- 只对同一个标签页有效：客户端不在标签页/浏览器之间共享会话状态，第二个窗口永远是独立的一份堆，首次打开一定重新拉历史。
- 首次打开任何会话（包括被保活的那些第一次）仍要拉一次历史——保活只影响「切走之后切回来」。
- 被保活会话的历史留在浏览器内存 + 各一条流；keepWarm 越大占用越高。

安装

dsh plugin --profile web add dsh-session-keepwarm

然后在 profile 里启用。插件把宿主契约声明为 @deepseek-ai/dsh-api-session-controller 的 ^0.1.7-rc.2 || ^0.2.0-rc.1（dsh 启动门禁与插件市场都读这个范围），已在 DSH 0.1.7-rc.2 与 0.2.0-rc.1 实测。

构建

npm install # esbuild
npm run build

退出条件

上游若为客户端加入「保留最近 N 个会话」的设置（或恢复等价的延迟销毁策略），应优先用上游设置并移除本插件。