@kangyishuai/dsh-session-rewind 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kangyishuai
+
+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.md

@@ -1,3 +1,114 @@
-# Temporary Holding Version
+# @kangyishuai/dsh-session-rewind
 
-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.
+> In-place conversation rewind for DeepSeek Harness: send the conversation back to before any user message, withdraw everything after it from the model context and the transcript, optionally restore the workspace files those turns changed, and put the message back into the composer.
+
+[![npm](https://img.shields.io/npm/v/@kangyishuai/dsh-session-rewind?color=cb3837&logo=npm)](https://www.npmjs.com/package/@kangyishuai/dsh-session-rewind) [![DSH](https://img.shields.io/badge/verified%20on%20DSH-0.2.2--rc.1-4b6bfb)](#compatibility) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+[中文](./README.zh-CN.md)
+
+Unofficial plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness). Not affiliated with DeepSeek.
+
+> **Status: early.** Verified end to end on DSH 0.2.2-rc.1: 31 GUI assertions in a throwaway DSH home, 158 unit tests, and a CDP-driven desktop pass (conflict refusal, conversation + file rewind, created-file trash, modified-file restore, rescue restore, panel/audit/diagnostics). Young software — keep backups of anything you cannot lose.
+
+## What it does
+
+Long conversations drift. A few turns later you wish you had answered a prompt differently, but starting a new session loses everything before it, and continuing keeps the unwanted turns in the context window forever. This plugin rewinds **in place**:
+
+- **Two entries.** Press `Esc` `Esc` to open the rewind dialog, or click the ↶ button in any user message's action row (next to Copy).
+- **Two scopes, chosen per rewind.** The confirmation dialog offers **Rewind conversation only** (default) and **Rewind conversation and files**. The dialog first shows a dry-run preview: how many messages and roughly how many tokens will be withdrawn, which files will be restored or moved to the trash, conflicts, and skipped files.
+- **Conversation.** The target message and everything after it are withdrawn from the model-visible context and from the transcript. The session id, title and earlier history are untouched. Nothing is deleted from the log — one marker event is appended.
+- **Files (optional).** Files changed by `write` / `edit` / `apply_patch` in the withdrawn turns are restored to their pre-change content. Files created after the target are moved to the plugin's trash instead of deleted. A rescue point of the current files is created before anything is written; failures roll back from it.
+- **Composer.** The target message's text (and images) is put back into the composer, ready to edit and send again. An existing draft is never overwritten.
+- **Rewind panel.** A new header action opens a panel with four tabs: **Withdrawn** (every message each rewind removed, searchable, copy or put back in the composer), **History** (audit of each rewind: scope, message count, tokens, file results), **Rescue points** (restore files from an earlier rescue), and **Settings** (default scope, page size, confirm-on-list, diagnostics).
+
+## Install
+
+```bash
+dsh plugin --profile desktop add @kangyishuai/dsh-session-rewind
+```
+
+To run the working tree instead of a published version, pack it first — `link:` installs do not work (the host's `@deepseek-ai/*` resolution only covers packages whose real path is inside the profile):
+
+```bash
+cd packages/session-rewind
+pnpm pack --pack-destination /tmp
+dsh plugin --profile desktop add /tmp/kangyishuai-dsh-session-rewind-*.tgz
+```
+
+Re-run `pnpm pack` + `add` after changing the code. The plugin has a host half, so restart the DSH desktop app and refresh the page.
+
+## Usage
+
+**Keyboard — `Esc` `Esc`.** In an idle conversation, press Escape twice quickly. The rewind dialog lists user messages, newest first; search, page to older messages with ↑/↓, Enter or click to choose. Then the preview opens; pick a scope and confirm. While a turn is running, `Esc` `Esc` keeps its native meaning (stop the turn); press it again when idle.
+
+**Message action — ↶.** Every user message has a ↶ button next to Copy. It opens the same preview/confirmation dialog. Nothing is rewound until you confirm.
+
+**Commands.** `/rewind` opens the same candidate list. `/rewind @<seq> [chat|both]` executes directly (the preview's seq is shown in the list). `/rewind` is decorated by the client; the bare form never sends text to the model.
+
+**After a rewind** the target text returns to the composer (images are re-attached best-effort) and the composer is focused. If the composer already held a draft, the draft is kept and a notice says so.
+
+**What is refused**
+
+| Situation                                                                | What happens                                                                           |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| The session has a running turn                                           | The host refuses (`session-rewind/busy`); stop the turn first and retry.               |
+| The session is a subagent child                                          | No ↶ button and no `Esc` `Esc` dialog: the Harness refuses generic session RPCs there. |
+| The target message was shadowed by compaction                            | Refused; the rewind boundary must still be in the model context.                       |
+| A file was changed outside the agent since the last recorded state       | File mode is refused with a conflict list; no file is touched.                         |
+| A file is larger than 8 MiB, a symlink, or under `.git` / `node_modules` | That file is skipped and reported; other files still proceed.                          |
+| A rewind is already running on this session                              | Refused; one at a time.                                                                |
+
+## File restore scope & safety
+
+- **Tracked changes only.** Only DSH file tools `write`, `edit` and `apply_patch` are tracked, and only under the session's working directory. Changes made by `bash`, scripts, external programs or subagents are **not** tracked; the plugin never claims a complete workspace snapshot.
+- **Before every write.** The engine records the content before the tool runs, deduplicated by SHA-256 under `<DSH_HOME>/session-rewind/blobs/`. Before restoring, it verifies the current file still matches the last recorded state; any mismatch aborts the whole file operation with a conflict list.
+- **Rescue before mutation.** All current affected files are copied to a rescue point first. If that fails, nothing is written. A failed restore rolls back applied files from the rescue point; failed rollbacks are reported. The five latest rescue points per session can be restored from the Rewind panel (a new rescue is created first).
+- **Destructive operations go to trash.** Files created after the rewind target are moved to `<DSH_HOME>/session-rewind/trash/<session>/<auditId>/`, never `rm`'d. Files larger than 8 MiB, symlinks and excluded trees are left alone and reported.
+- **No undo.** This plugin deliberately does not implement conversation undo/redo (it would require patching DSH internals). The withdrawn content stays in the session log and the Rewind panel; file-level recovery is available through rescue points and trash.
+- **Order.** Preview and conflict checks run before anything is written; then the rescue point; then the conversation marker; then file writes. Once the marker is appended the conversation rewind stands even if file writes fail (they are reported and audited).
+
+## Data & retention
+
+All plugin data lives under `<DSH_HOME>/session-rewind/` (`DSH_HOME` defaults to `~/.dsh`):
+
+| Path                            | Contents                                             |
+| ------------------------------- | ---------------------------------------------------- |
+| `blobs/`                        | content-addressed file contents (SHA-256)            |
+| `sessions/<id>/entries.jsonl`   | per-session file change records (newest shown first) |
+| `trash/<session>/<auditId>/`    | files created after a rewind target                  |
+| `rescues/<session>/<rescueId>/` | rescue points (current files before a restore)       |
+| `audit.jsonl`                   | one line per rewind (append-only)                    |
+
+On startup the plugin also removes data for sessions that no longer exist (they were deleted); the audit log is kept. Retention: the 20 latest message anchors per session, the 5 latest rescue points, the 20 latest trash operations (30 days), and a 1 GiB soft cap across blobs/trash/rescues. When the cap is exceeded, old trash → old rescues → unreferenced blobs → oldest anchors are cleaned in that order; if still over the cap, new captures stop and diagnostics report it (no referenced data is deleted). Uninstalling keeps the data. The data root can be overridden with the plugin's `dataRoot` config.
+
+## Side effects & risks
+
+- **Appends one marker event per rewind** to the current session log; nothing is deleted or rewritten.
+- **Writes and deletes workspace files only in file mode**, after confirmation, with the safety described above.
+- **The marker is visible to the model** as a short `(empty message)` user message where the withdrawn turns used to be. It is not shown in the transcript.
+- **No network, no telemetry.** Everything is local; file snapshots may contain sensitive content, so treat `<DSH_HOME>/session-rewind/` like your workspace.
+- **Private client seams.** Hiding rows and injecting the ↶ button rely on DSH's internal view/slot registries. They are shape-checked at install and degrade to “context rewound, transcript not hidden” or “button missing” rather than breaking a session.
+- **POSIX/macOS paths only** in this version; Windows separators and permission bits are not verified.
+
+## Compatibility
+
+| DSH version | Status                                                                                                                      |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
+| 0.2.2-rc.1  | Verified: `pnpm smoke:session-rewind` (31/31) + 158 unit tests + CDP-driven desktop pass (conversation-only and file modes) |
+
+The plugin declares no `engines.dsh` and no `@deepseek-ai/*` peer range: DSH is pre-release and semver ranges over prereleases are unreliable (see [ADR 0005](../../docs/adr/0005-dsh-version-compatibility.md)). Treat the table as the compatibility statement. After a DSH upgrade run `pnpm probe:runtime`, `pnpm smoke:session-rewind`, and check the plugin's diagnostics tab; if a private seam changed, the plugin degrades instead of breaking the session.
+
+## Development
+
+```bash
+pnpm test                     # unit tests (host engine, host RPC, client helpers)
+pnpm verify                   # repo-wide gates
+pnpm smoke:session-rewind           # temp DSH home + real GUI end-to-end (needs dsh & ego-browser)
+pnpm smoke:session-rewind-desktop   # read-only desktop check (needs --remote-debugging-port=9222)
+```
+
+Design notes: [ADR 0006](../../docs/adr/0006-session-rewind-architecture.md) and [ADR 0007](../../docs/adr/0007-session-rewind-file-restore.md) (Chinese; the repository docs are written in Chinese).
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,114 @@
+# @kangyishuai/dsh-session-rewind
+
+> DeepSeek Harness 的「就地回溯」：把会话退回到任意一条用户消息之前，目标消息及其后的内容同时从模型上下文和渲染对话中撤回；可选择一并还原这些轮次改过的工作区文件；目标消息文本（和图片）自动回填输入框。
+
+[![npm](https://img.shields.io/npm/v/@kangyishuai/dsh-session-rewind?color=cb3837&logo=npm)](https://www.npmjs.com/package/@kangyishuai/dsh-session-rewind) [![DSH](https://img.shields.io/badge/verified%20on%20DSH-0.2.2--rc.1-4b6bfb)](#兼容性) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+[English](./README.md)
+
+非官方插件，与 DeepSeek 无关。面向 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness)。
+
+> **状态：早期。** 已在 DSH 0.2.2-rc.1 上端到端验证：一次性 DSH 目录里 31 项 GUI 断言 + 158 个单测 + CDP 驱动的桌面版实测（冲突拒绝、对话+文件回退、新建文件进回收站、修改文件还原、救援点恢复、面板/审计/诊断）。插件还年轻，重要数据请自行备份。
+
+## 它做什么
+
+长对话会跑偏。几轮之后你希望当初换个问法，但新开一个会话会丢掉之前的全部上下文，继续聊又会让不想要的几轮永远占着上下文窗口。这个插件做**就地回溯**：
+
+- **两个入口**：连按两次 `Esc` 打开回溯对话框；或点任意用户消息操作行里、复制按钮旁边的 ↶ 按钮。
+- **每次回溯二选一**：确认框里提供「**仅回退对话**」（默认）与「**回退对话和文件**」，并先展示 dry-run 预览：将撤回多少条消息、约多少 token、哪些文件会还原/移入回收站、冲突与被跳过的文件。
+- **对话**：目标消息及其后的内容从模型上下文和渲染对话中撤回；会话 id、标题和目标之前的历史不变；日志只追加一条 marker，不删历史。
+- **文件（可选）**：被撤回轮次里由 `write` / `edit` / `apply_patch` 改过的文件还原到改动前内容；目标之后新建的文件移入插件回收站而不是删除。写入前先建救援点，失败从救援点回滚。
+- **输入框**：目标消息文本（以及图片）放回输入框，改完可直接重发；已有草稿绝不覆盖。
+- **回溯面板**：会话头部新增一个入口，四个页签：**已撤回**（每次回溯撤回的全部消息，可搜索、复制、放回输入框）、**回溯记录**（审计：范围、条数、token、文件结果）、**救援点**（手动恢复文件）、**设置**（默认范围、每页数量、列表确认、诊断）。
+
+## 安装
+
+```bash
+dsh plugin --profile desktop add @kangyishuai/dsh-session-rewind
+```
+
+如果要用工作区里的代码而不是发布版，先打包再装——`link:` 装法不行（宿主的 `@deepseek-ai/*` 解析只覆盖真实路径位于 profile 内的包）：
+
+```bash
+cd packages/session-rewind
+pnpm pack --pack-destination /tmp
+dsh plugin --profile desktop add /tmp/kangyishuai-dsh-session-rewind-*.tgz
+```
+
+改完代码要重新 `pnpm pack` + `add`。插件带宿主半，装完重启 DSH 桌面版并刷新页面。
+
+## 用法
+
+**键盘 — `Esc` `Esc`。** 空闲会话里快速连按两次 Escape，打开回溯对话框：按时间倒序列出用户消息，可搜索、↑/↓ 选择、Enter 或点击；随后进入预览/确认框，选范围并确认。回合运行中 `Esc` `Esc` 保持原生「停止」含义；停下后再按两次即可。
+
+**消息操作 — ↶。** 每条用户消息的复制按钮旁都有 ↶；点开同一个预览/确认框，确认后才执行。
+
+**命令。** `/rewind` 打开同一份候选列表；`/rewind @<序号> [chat|both]` 直接执行（序号在列表里可见）。客户端会接管裸 `/rewind`，不会把命令发给模型。
+
+**回溯之后**，目标文本回到输入框（图片尽力重新挂回）并获得焦点。如果输入框里本来有草稿，不会被覆盖，并会提示草稿已保留。
+
+**会被拒绝的情况**
+
+| 情况                                                        | 表现                                                              |
+| ----------------------------------------------------------- | ----------------------------------------------------------------- |
+| 会话有正在运行的回合                                        | 宿主返回 `session-rewind/busy`；先停止回合再回溯。                |
+| 子代理会话                                                  | 没有 ↶ 按钮，`Esc` `Esc` 也不弹框：宿主拒绝对这类会话的通用 RPC。 |
+| 目标消息已被 compaction 遮蔽                                | 拒绝；回溯边界必须仍在模型上下文里。                              |
+| 文件在上次记录后被外部修改                                  | 文件模式整体拒绝并列出冲突文件；一个文件都不动。                  |
+| 文件超过 8 MiB、是符号链接、或在 `.git` / `node_modules` 下 | 该文件跳过并报告，其余文件继续。                                  |
+| 同一会话已有回溯在执行                                      | 拒绝；一次只允许一个。                                            |
+
+## 文件还原的范围与安全
+
+- **只追踪写类工具**：`write` / `edit` / `apply_patch`，且只限会话工作目录。`bash`、脚本、外部程序、子代理的改动**不在追踪范围**，插件不会声称做过完整工作区快照。
+- **写前记录**：工具执行前记录内容，按 SHA-256 去重存到 `<DSH_HOME>/session-rewind/blobs/`。还原前逐个比对「当前内容」与「最后一次记录的 after」，不一致就整体中止并列出冲突。
+- **先救援点、再写入**：还原前把当前受影响文件复制成救援点；救援点失败则一个字节都不写。恢复逐文件写回/移入回收站，写后校验哈希；失败用救援点回滚，回滚失败也会报告。每个会话保留最近 5 份救援点，可在回溯面板手动恢复（恢复前会再建一份救援点）。
+- **删除走回收站**：目标之后新建的文件移入 `<DSH_HOME>/session-rewind/trash/<session>/<auditId>/`，不会 `rm`。超限/符号链接/被排除目录的文件保持原样并报告。
+- **没有 undo**：本插件刻意不做真 undo/redo（那需要 patch 宿主内部）。被撤回的内容仍在会话日志和回溯面板里；文件层面可用救援点或回收站手动恢复。
+- **顺序**：预览与冲突检查 → 建救援点 → 追加会话 marker → 写文件。marker 一旦写入，对话回退即生效；文件失败只报告并写审计，不回滚对话。
+
+## 数据与保留
+
+所有数据在 `<DSH_HOME>/session-rewind/`（`DSH_HOME` 默认 `~/.dsh`）：
+
+| 路径                            | 内容                          |
+| ------------------------------- | ----------------------------- |
+| `blobs/`                        | 内容寻址的文件内容（SHA-256） |
+| `sessions/<id>/entries.jsonl`   | 每个会话的文件改动记录        |
+| `trash/<session>/<auditId>/`    | 回溯时新建文件的回收站        |
+| `rescues/<session>/<rescueId>/` | 还原前的救援点                |
+| `audit.jsonl`                   | 每次回溯一行（只追加）        |
+
+启动时会自动清理已删除会话的残留数据（entries/trash/救援点）；审计日志保留。保留策略：每会话最近 20 个消息锚点、最近 5 份救援点、最近 20 次回收站操作（30 天）、blobs/trash/rescues 合计 1 GiB 软上限。超限时按「旧回收站 → 旧救援点 → 无引用 blob → 最旧锚点」清理；仍超限则停止新捕获并在诊断里告警（不删有引用的数据）。卸载保留数据。数据根可用插件配置 `dataRoot` 覆盖。
+
+## 副作用与风险
+
+- **每次回溯追加一条 marker** 到当前会话日志；不删除、不改写历史。
+- **仅在文件模式下写/删工作区文件**，且经过确认与上述安全流程。
+- **marker 对模型可见**：在被撤回回合的位置，模型会看到一条很短的 `(empty message)` user 消息；界面不显示它。
+- **不联网、不上报**；文件快照可能含敏感内容，请把 `<DSH_HOME>/session-rewind/` 当工作区数据对待。
+- **客户端私有 seam**：隐藏行和注入 ↶ 按钮依赖 DSH 内部 view/slot 注册表；安装时做形状检查，失效时降级为「上下文已回溯、界面不隐藏」或「按钮消失」，不破坏会话。
+- **本版只验证 POSIX/macOS 路径**；Windows 分隔符与权限位未验证。
+
+## 兼容性
+
+| DSH 版本   | 状态                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| 0.2.2-rc.1 | 已验证：`pnpm smoke:session-rewind` 31/31 + 158 个单测 + CDP 驱动的桌面版实测（仅对话与文件模式） |
+
+插件不声明 `engines.dsh`，也不声明 `@deepseek-ai/*` 的 peer 范围：DSH 还在预发布阶段，预发布版本的 semver 范围不可靠（见 [ADR 0005](../../docs/adr/0005-dsh-version-compatibility.md)）。以这张表为准。DSH 升级后跑 `pnpm probe:runtime`、`pnpm smoke:session-rewind`，并看插件诊断页签；私有 seam 变了会降级而不是让会话出错。
+
+## 开发
+
+```bash
+pnpm test                     # 单测（宿主文件引擎、宿主 RPC、客户端 helper）
+pnpm verify                   # 仓库统一门禁
+pnpm smoke:session-rewind           # 临时 DSH 目录 + 真实 GUI 端到端（需要 dsh 与 ego-browser）
+pnpm smoke:session-rewind-desktop   # 只读桌面回归（需要以 --remote-debugging-port=9222 重启）
+```
+
+设计记录：[ADR 0006](../../docs/adr/0006-session-rewind-architecture.md)、[ADR 0007](../../docs/adr/0007-session-rewind-file-restore.md)。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: session-rewind
+      name: "@kangyishuai/dsh-session-rewind"