dsh-session-rewind 0.0.0-stage → 1.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 2310770803
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,153 @@
+# dsh-session-rewind
+
+[中文](README.md) | English
+
+A DSH Web plugin that puts **Rewind** on every finished Turn: a per-Turn control
+in the Chat timeline plus one entry in the Session header, branching the
+conversation at that Turn and restoring the files that Turn changed.
+
+In DSH Web, rewind to any **finished Turn**: every Turn in the Chat timeline has a
+`Rewind` button, and the Session header adds one more entry point that lists every
+rewindable Turn of the session. Rewinding forks a new session at that Turn and
+restores the files that Turn changed.
+
+## Two entry points
+
+| Where | What it does |
+| --- | --- |
+| The ↶ in the Session header (`conversation.session.header.actions`) | Lists **every** finished Turn of this session (Turn N + prompt preview + file count); pick with ↑↓, confirm with Enter, go back with Esc. After picking a Turn, choose "Rewind conversation only" or "Rewind and restore N files" — no need to scroll back to that Turn. |
+| `Rewind` at the end of each finished Turn (`conversation.chat.turnTail`) | Rewinds that one Turn directly; the panel lets you check the files to restore and choose "Rewind conversation" or "Restore files only". |
+
+## What it does
+
+Choosing a Turn opens a small panel with two independent halves:
+
+1. **Rewind the conversation.** A committed Turn cannot be edited in place: the
+   session log is append-only and branching is the supported operation. The
+   panel therefore creates a *new* session that ends exactly at that Turn
+   (`sessions.fork` with the Turn's `turn/end` seq), opens it, and pre-fills its
+   composer with the Turn's original user prompt so you can edit it and send it
+   again. The original session is left untouched.
+2. **Restore the files that Turn changed.** While a Turn runs, every file the
+   model creates or rewrites is captured *before* the mutation and stored as a
+   content-addressed blob. The panel lists those files; the checked ones are put
+   back to their pre-Turn content (a file the Turn created is removed).
+
+The two halves can be used together (`Rewind conversation`) or separately
+(`Restore files only`).
+
+### Why a fork instead of an in-place rewind
+
+The community plugin [`SiriLee/dsh-rewind`](https://github.com/SiriLee/dsh-rewind)
+offers an **in-place rewind** (inside the same session it moves the
+model-visible surface back to an earlier user message by appending a
+`surfaceOp: replace` marker). We borrowed its **entry points and interaction**
+(a ↶ next to each message/Turn, a mode picker, a file impact list,
+↑↓/Enter/Esc, a header candidate list) but deliberately did **not** adopt its
+in-place rollback, because:
+
+- An in-place rewind needs more than an appended marker: the front end must also
+  hide the rolled-back rows, and DSH exposes no extension point for that. The
+  reference plugin does it by wrapping the private `uiConversation.views`
+  registry, and its own source comments say *"The seam is private … not an
+  extension point"* — it breaks with version upgrades.
+- `sessions.fork` is the branching capability DSH officially gives the UI — the
+  built-in "branch in new chat" button uses it — so it is stable across upgrades
+  and naturally satisfies "context truncated + editable + resendable".
+
+If you would rather have an in-place rewind (same session, no new session), you
+can install `dsh-rewind-plugin` separately; the two do not conflict.
+
+## Install
+
+**Install from the plugin market (recommended):** **Plugins → Discover** →
+**Index sources** → add
+`https://raw.githubusercontent.com/2310770803/dsh-session-rewind/main/index.json`
+→ search `rewind` or `Session Rewind` → install. The index format and the release
+process are documented in [docs/publishing.md](docs/publishing.md).
+
+This machine (profile `desktop`) already has that index source written into
+`cordis.patch.yml`, so opening Discover shows the entry.
+
+**Install from the source directory** (what this machine currently does):
+
+```js
+// plugin_manager
+{ action: 'install_bundle', target: 'E:\\\\DeepSeek Harness\\\\dsh-session-rewind' }
+```
+
+## How it is put together
+
+| half | mechanism |
+| --- | --- |
+| conversation | Client `sessions.fork({ sessionId, atSeq })` + `uiWorkspace.openSession`, the same idiom as the built-in branch button; the draft is pre-seeded through the Conversation store's per-session `localStorage` key so the composer already holds the original prompt |
+| files (capture) | `fs/write-intent` / `fs/edit-intent` waterfalls (`{ prepend: true }`), with the tool execution mapped back to its Session through a `tools/pre-execute` `WeakMap` — the same coupling `workspace-changes` uses |
+| files (restore) | text pre-images through the `fs` service (path resolution, locks, version guard); binary pre-images and deletions through Node, on the archive's own recorded absolute path |
+
+## Where data lives
+
+```
+$DSH_HOME/plugin-data/dsh-session-rewind/
+  index.json           per-session, per-Turn file records
+  blobs/<sha256>.bin   the pre-Turn bytes
+```
+
+Nothing leaves the machine: the four Host routes are loopback-only,
+same-origin `/api` routes with DSH Web's own Host/Origin trust fence.
+
+`GET /api/session-rewind.selfcheck` reports what the running Host has actually
+wired up (archive totals, whether the Web half is in the boot graph, the route
+list). It is read-only and never exposes session content.
+
+## Limits
+
+- Only mutations that go through the DSH filesystem service inside a Turn are
+  captured. Files changed by a shell command, by `git`, or outside a Turn are
+  not recorded and therefore not restored.
+- Files written by tools that bypass the `fs` write-intent waterfall are not
+  captured either: the Office tools (`word_create`, `excel_update`, …) call the
+  filesystem service directly, so a `.docx`/`.xlsx` they produce is **not** in the
+  archive and cannot be rewound. Plain text, Markdown, and source code edited
+  through the `write`/`edit` tools are covered.
+- A Turn snapshots at most 200 files, and no pre-image larger than 2 MiB; larger
+  files are listed as "not restorable" instead of being silently skipped.
+- Files inside `.git` are never captured, so a restore cannot corrupt the
+  repository.
+- The archive keeps the newest 400 Turns; older records are pruned with their
+  blobs.
+- A restore writes the recorded content back. It does not re-run anything, and it
+  does not delete files the Turn merely *modified*.
+- A plugin-originated write has no Agent context, so the `fs` service refuses it
+  by default. Restores rebuild the policy from the Turn's own workspace
+  (`workspace-write`) and widen to `danger-full-access` only for a path the
+  archive recorded outside it.
+- Capture starts with the Turn that is open when the plugin mounts: a Turn
+  already running at install time is recovered from the live log tail, but a
+  plugin loaded later than the Turn's first write cannot see earlier mutations.
+- The naming and wording of the panel follow the DSH locale service; the bundled
+  dictionaries are Chinese and English.
+
+## Tests
+
+The package ships the suites used to verify it; they need no browser and no
+profile:
+
+```
+node test/selftest.mjs      # Turn location, prompt extraction, archive, restorer
+node test/route-smoke.mjs   # all routes, their fences, and path allow-listing
+node test/client-smoke.mjs  # the Web half: both slots, panel, candidate list, fork, draft
+```
+
+## Package layout
+
+| file | role |
+| --- | --- |
+| `cordis.patch.yml` | inserts the `session-rewind` plugin row |
+| `src/index.js` | Host entry, re-exports `apply` / `inject` / `name` |
+| `src/plugin.js` | Host wiring: Turn tracking, mutation capture, the four routes |
+| `src/lib/archive.js` | durable pre-Turn archive, pruning, blob store |
+| `src/lib/restore.js` | putting one captured file back |
+| `src/lib/route.js` | routes and the `/api` trust fence |
+| `lib/client.js` | Web half: the turn-tail control, the header entry, the panel |
+| `locale/*.json` | `meta.title` / `meta.description` for the plugin list |
+| `index.json` | format-1 plugin-market index (see `docs/publishing.md`) |

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-session-rewind · 会话回退
+
+A DSH Web plugin that puts **Rewind** on every finished Turn: a per-Turn control
+in the Chat timeline plus one entry in the Session header, branching the
+conversation at that Turn and restoring the files that Turn changed.
+
+在 DSH Web 里回退到任意**已完成的回合**：对话时间线的每个回合旁有 `回退` 按钮，会话标题栏还有一个
+总入口，列出本会话所有可回退的回合；回退会从该回合处分叉出新会话，并把该回合改动过的文件恢复原状。
+
+## 两个入口 · Two entry points
+
+| 位置 | 作用 |
+| --- | --- |
+| **你发出的那条消息旁的 ↶** | 点开选「仅回退对话」或「回退对话并恢复文件」。**就地回退**：这条消息及之后的对话内容从模型上下文撤回，原话立刻回到本会话输入框，改完直接重发。 |
+| 会话标题栏的 ↶（`conversation.session.header.actions`） | 列出本会话**所有**可回退的消息（第 N 轮 + 提问预览 + 文件数），↑↓ 选择、Enter 确认、Esc 返回；选中后同样是就地回退，也可以选「在新会话中分支」。 |
+| 每个已完成回合末尾的 `回退`（`conversation.chat.turnTail`） | 旧入口，保留兼容：就这一轮做分叉回退，面板里可勾选要恢复的文件。 |
+
+**核心行为（就地回退）**：选中你某条消息 → 追加一条 `surfaceOp: replace` 标记，把模型可见的
+surface 从这条消息起整体撤回 → 被撤回的行从对话里消失（轨迹面板仍可查，日志从未删改）→
+这条消息的**原文放进输入框**，你可以修改后重新发送。会话不换、不新建。
+
+## What it does · 功能
+
+Choosing a Turn opens a small panel with two independent halves:
+
+1. **Rewind the conversation.** A committed Turn cannot be edited in place: the
+   session log is append-only and branching is the supported operation. The
+   panel therefore creates a *new* session that ends exactly at that Turn
+   (`sessions.fork` with the Turn's `turn/end` seq), opens it, and pre-fills its
+   composer with the Turn's original user prompt so you can edit it and send it
+   again. The original session is left untouched.
+2. **Restore the files that Turn changed.** While a Turn runs, every file the
+   model creates or rewrites is captured *before* the mutation and stored as a
+   content-addressed blob. The panel lists those files; the checked ones are put
+   back to their pre-Turn content (a file the Turn created is removed).
+
+The two halves can be used together (`回退对话`) or separately
+(`仅恢复文件`).
+
+选中某个回合后：
+
+1. **回退对话**：会话日志是只追加的，所以“回退”= 在该回合的 `turn/end` 处**分叉**出一个新会话并打开它，
+   同时把该回合原本的用户输入写回新会话的输入框，你可以直接修改后重新发送；原会话完全不动。
+2. **恢复文件**：该回合运行期间，每个被创建或改写的文件都会在**写入前**抓取一份原始字节存档。
+   面板会列出这些文件，勾选的会被恢复为修改前的内容；该回合新建的文件会被删除。
+
+### 就地撤回 vs 分叉：两个都给了
+
+- **就地回退（主）**：同一会话内撤回，靠一条 `surfaceOp: replace` 标记实现——这是 DSH 自己
+  压缩（compaction）用的同一机制，日志只追加、不删改。
+- **分叉（次）**：`sessions.fork` 在该回合 `turn/end` 处新建一份会话，内置「在新对话中分支」
+  按钮用的就是它，升级最稳。
+
+唯一的妥协在**前端隐藏被撤回的行**：DSH 没有为用户消息提供动作槽，也没有公开「隐藏某段行」
+的接口，所以这里按参考插件 `SiriLee/dsh-rewind` 的做法在前端补：给每条用户消息注入一个 ↶
+（锚点取行内最后一个按钮的父节点），回退后按 `data-chat-turn` 隐藏该行及之后的行。全部特性
+检测、卸载即还原；DSH 若在未来提供动作槽，这里会切成槽位实现。
+
+### 参考插件为什么没有全盘照搬
+
+社区里的 [`SiriLee/dsh-rewind`](https://github.com/SiriLee/dsh-rewind) 提供**就地回退**（同一会话内
+把模型可见 surface 切回更早的用户消息，靠追加一条 `surfaceOp: replace` 标记实现）。我们借鉴了它的
+**入口与交互**（每条消息/每轮旁的 ↶、模式选择、文件影响清单、↑↓/Enter/Esc、标题栏候选列表），但**没有**
+采用它的就地撤回，原因是：
+
+- 就地撤回不仅要追加标记，还必须在**前端**把被撤回的行隐藏起来，而 DSH 没有为此提供扩展点——
+  参考插件是通过包装私有的 `uiConversation.views` registry 做到的，其源码自己注明
+  *"The seam is private … not an extension point"*，随版本升级会破。
+- `sessions.fork` 是 DSH 给 UI 的官方分支能力（内置「在新对话中分支」按钮用的就是它），
+  升级稳定，且天然满足“上下文被截断 + 可改可重发”。
+
+如果你更希望要就地撤回（同一会话、不产生新会话），可以另装 `dsh-rewind-plugin`；两者不冲突。
+
+## Install · 安装
+
+**从插件市场安装（推荐）**：左侧 **插件 → 发现（Discover）** → **索引源** → 添加
+`https://raw.githubusercontent.com/2310770803/dsh-session-rewind/main/index.json`
+→ 搜索 `rewind` 或 `会话回退` → 安装。索引格式与发布流程见 [docs/publishing.md](docs/publishing.md)。
+
+本机（profile `desktop`）已把这个索引源写进 `cordis.patch.yml`，打开「发现」即可看到条目。
+
+**从源码目录安装**（本机当前就是这种方式）：
+
+```js
+// plugin_manager
+{ action: 'install_bundle', target: 'E:\\DeepSeek Harness\\dsh-session-rewind' }
+```
+
+## How it is put together · 实现
+
+| half | mechanism |
+| --- | --- |
+| conversation | Client `sessions.fork({ sessionId, atSeq })` + `uiWorkspace.openSession`, the same idiom as the built-in branch button; the draft is pre-seeded through the Conversation store's per-session `localStorage` key so the composer already holds the original prompt |
+| files (capture) | `fs/write-intent` / `fs/edit-intent` waterfalls (`{ prepend: true }`), with the tool execution mapped back to its Session through a `tools/pre-execute` `WeakMap` — the same coupling `workspace-changes` uses |
+| files (restore) | text pre-images through the `fs` service (path resolution, locks, version guard); binary pre-images and deletions through Node, on the archive's own recorded absolute path |
+
+## Where data lives · 数据位置
+
+```
+$DSH_HOME/plugin-data/dsh-session-rewind/
+  index.json           per-session, per-Turn file records
+  blobs/<sha256>.bin   the pre-Turn bytes
+```
+
+Nothing leaves the machine: the four Host routes are loopback-only,
+same-origin `/api` routes with DSH Web's own Host/Origin trust fence.
+
+`GET /api/session-rewind.selfcheck` reports what the running Host has actually
+wired up (archive totals, whether the Web half is in the boot graph, the route
+list). It is read-only and never exposes session content.
+
+## Limits · 限制
+
+- Only mutations that go through the DSH filesystem service inside a Turn are
+  captured. Files changed by a shell command, by `git`, or outside a Turn are
+  not recorded and therefore not restored.
+- Files written by tools that bypass the `fs` write-intent waterfall are not
+  captured either: the Office tools (`word_create`, `excel_update`, …) call the
+  filesystem service directly, so a `.docx`/`.xlsx` they produce is **not** in the
+  archive and cannot be rewound. Plain text, Markdown, and source code edited
+  through the `write`/`edit` tools are covered.
+- A Turn snapshots at most 200 files, and no pre-image larger than 2 MiB; larger
+  files are listed as "not restorable" instead of being silently skipped.
+- Files inside `.git` are never captured, so a restore cannot corrupt the
+  repository.
+- The archive keeps the newest 400 Turns; older records are pruned with their
+  blobs.
+- A restore writes the recorded content back. It does not re-run anything, and it
+  does not delete files the Turn merely *modified*.
+- A plugin-originated write has no Agent context, so the `fs` service refuses it
+  by default. Restores rebuild the policy from the Turn's own workspace
+  (`workspace-write`) and widen to `danger-full-access` only for a path the
+  archive recorded outside it.
+- Capture starts with the Turn that is open when the plugin mounts: a Turn
+  already running at install time is recovered from the live log tail, but a
+  plugin loaded later than the Turn's first write cannot see earlier mutations.
+- The naming and wording of the panel follow the DSH locale service; the bundled
+  dictionaries are Chinese and English.
+
+## Tests · 测试
+
+The package ships the suites used to verify it; they need no browser and no
+profile:
+
+```
+node test/selftest.mjs      # Turn location, prompt extraction, archive, restorer
+node test/route-smoke.mjs   # all routes, their fences, and path allow-listing
+node test/client-smoke.mjs  # the Web half: both slots, panel, candidate list, fork, draft
+```
+
+## Package layout
+
+| file | role |
+| --- | --- |
+| `cordis.patch.yml` | inserts the `session-rewind` plugin row |
+| `src/index.js` | Host entry, re-exports `apply` / `inject` / `name` |
+| `src/plugin.js` | Host wiring: Turn tracking, mutation capture, the four routes |
+| `src/lib/archive.js` | durable pre-Turn archive, pruning, blob store |
+| `src/lib/restore.js` | putting one captured file back |
+| `src/lib/route.js` | routes and the `/api` trust fence |
+| `lib/client.js` | Web half: the turn-tail control, the header entry, the panel |
+| `locale/*.json` | `meta.title` / `meta.description` for the plugin list |
+| `index.json` | format-1 plugin-market index (see `docs/publishing.md`) |

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# Add one dual-face plugin row to the Web profile.
+#
+# The Host half (src/index.js) archives the pre-Turn content of every workspace
+# file a Turn mutates and serves the two rewind routes; dsh.client discovers the
+# browser half from this same package manifest and mounts a rewind control in
+# the Chat turn tail of every finished Turn.
+- insert:
+    - id: session-rewind
+      name: dsh-session-rewind

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Session Rewind">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#111827"/>
+  <path d="M27 13a15 15 0 1 1-13.4 8.2" fill="none" stroke="#7DA2F7" stroke-width="5" stroke-linecap="round"/>
+  <path d="M12.5 9.5v12h12" fill="none" stroke="#7DA2F7" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M37 30h11a3 3 0 0 1 3 3v16a3 3 0 0 1-3 3H37a3 3 0 0 1-3-3V33a3 3 0 0 1 3-3z" fill="none" stroke="#E5E7EB" stroke-width="3"/>
+  <path d="M15 40h8M15 46h8M15 52h8" fill="none" stroke="#E5E7EB" stroke-width="3" stroke-linecap="round"/>
+</svg>