dsh-pause-session 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-11-02
+
+### Added
+
+- Pause every running DSH session and its subagents at the next model-request
+  boundary, after the tool already running finishes.
+- Session-header and whole-app controls, with `Pausing`, `Paused`, and
+  `All Paused` states.
+- Durable pause registry that re-holds parked sessions after a DSH restart.
+- Clean resume that restores the recorded Agent preset composition, including
+  subagent delegation context and tool restrictions.
+- Goal re-arm toggle for cleanly paused sessions.
+- Decision list for sessions that did not pause cleanly, with continue,
+  continue-with-note, review-only, leave, and goal actions.
+- Localized English and Chinese UI copy, plugin-manager metadata, and a
+  user-facing README screenshot.
+- `/pause`, `/pause-resume`, `/pause-all`, `/pause-state`, `/pause-goal`, and
+  `/pause-triage*` command surface.
+
+### Changed
+
+- The package is published as `dsh-pause-session`; the slash-command namespace
+  remains `/pause*`.
+- One-shot and external subagent routes are reported as unresumable and are not
+  registered as local pause records.
+
+### Known Limitations
+
+- Background jobs and shell tasks outside the agent loop are not stopped.
+- A paused session still appears `running` to parts of DSH's session lifecycle;
+  exit, archive, compaction, and `wait_agent` can behave differently while held.
+- External one-shot subagent routes cannot be cold-resumed.
+
+[0.1.0]: https://github.com/timho1047/dsh-pause-session/releases/tag/v0.1.0

package/DEVELOPMENT.md

@@ -0,0 +1,55 @@
+# Development
+
+This is a personal DSH plugin repository. `dsh-plugins/` is not part of the
+official DSH source tree; it is only the author's local layout.
+
+## Layout
+
+- `src/` — host-half TypeScript: pause gate, park registry, resume path,
+  triage, and host services.
+- `src/client/` — Web client TypeScript/React: the session control, global
+  control, state mapping, and locale dictionaries.
+- `lib/` — committed build output. Run `pnpm run build` to refresh it before a
+  release commit.
+- `.scratch/pause-session/` — local-only design record (ignored by Git).
+- `REHEARSAL.md` — the manual end-to-end acceptance run.
+
+## DSH dependency links
+
+The development dependencies in [package.json](package.json) point at a
+DeepSeek Harness checkout through `link:../../deepseek-harness/...`. Local
+typecheck, build, and tests expect that checkout to be present at the same
+relative depth.
+
+The published npm packages currently lag the APIs this plugin uses
+(`0.2.2-alpha.2`), so replacing these links with registry versions would break
+the build. A fresh clone can run `pnpm pack` (the release path does not install
+dependencies), but cannot run the full verification suite without the harness
+checkout.
+
+## Build and test
+
+```sh
+pnpm install
+pnpm run verify     # typecheck + build + tests
+pnpm run build      # tsc for both faces, then tsdown
+```
+
+The host half builds to `lib/index.js`; the client half builds to
+`lib/client.js`, the browser module bundle loaded under the `dsh-pause-session` id.
+`tsdown.client.ts` is the vendored client-bundle preset shared by the plugins
+in this directory.
+
+## Design record
+
+The specification and task breakdown live under `.scratch/pause-session/`, local-only
+by this directory's convention. The load-bearing findings behind the design —
+where a pause can land, what a pause costs the surrounding app, and what a
+restart does to a paused session — are recorded in the spec's evidence section.
+Read it before changing the pause or resume path.
+
+## Manual acceptance
+
+[REHEARSAL.md](REHEARSAL.md) is the end-to-end acceptance run: precedence for
+what the automated suite already proves, how to install, the steps to walk, and
+the rollback if a profile will not start.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim HO
+
+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,131 @@
-# Temporary Holding Version
+# dsh-pause-session
 
-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.
+English | [中文](README.zh.md)
+
+<p align="center"><img src="icon.svg" width="64" height="64" alt="dsh-pause-session icon"></p>
+
+Pause every running DSH session and its subagents before you leave, then resume
+them later.
+
+dsh-pause-session stops each session at the same point: the tool call that is already
+running finishes, then the next model request is held. Subagent trees are
+included, and the pause survives a DSH restart.
+
+> Status: beta. Tested against DSH `0.2.2-alpha.2`; the end-to-end rehearsal is
+> tracked in [REHEARSAL.md](REHEARSAL.md).
+
+<p align="center">
+  <img src="docs/images/pause-controls.webp" alt="dsh-pause-session controls showing a paused session and All Paused for the whole app" width="100%">
+</p>
+
+*The session is paused; the global pill shows All Paused (1/1).*
+
+## Quick start
+
+1. Open the **Plugins** page in the DSH Web sidebar and install this directory
+   as a bundle. The repository ships the built `lib/` tree; if you changed the
+   source, run `pnpm run build` first. From a session in that profile,
+   `plugin_manager` can do the same with `install_bundle` and the directory's
+   absolute path. The local development layout is in
+   [DEVELOPMENT.md](DEVELOPMENT.md).
+2. Open the session you want to pause. Press the pause button beside its title
+   to pause that session and its subagents, or press the pill on the right side
+   of the header to pause every running session tree.
+3. The control shows **Pausing** until the running tools finish and the next
+   model requests are held. When the global pill shows **All Paused**, every
+   registered session is stopped.
+4. Next time, press **All Paused** to resume every cleanly paused session, or
+   press the session button to resume that session and its subagents.
+
+## The two controls
+
+| Control | Scope | What it does |
+|---|---|---|
+| Session header button | One session and its subagents | Pauses the current session tree, then resumes the same tree. |
+| Global pill | All running session trees | Pauses every registered session, then resumes every cleanly paused session. |
+
+A session with an unfinished tool is shown as **Pausing**. It moves to
+**Paused** only after the tool returns, the next model request is held, and the
+session state is saved.
+
+## What pause actually does
+
+- A tool call already running is allowed to finish. No new tool call or model
+  request is sent after the pause is taken.
+- The next model request is held before it reaches the provider.
+- Subagents already under the paused tree are stopped with the same rules.
+- The pause state is durable. If DSH exits or restarts, the sessions are held
+  again on the next mount.
+- The composer stays usable; the pause is released by the same control, not by
+  sending a message.
+
+## What is not stopped
+
+- Background jobs and shell tasks outside the agent loop are not stopped. The
+  global control names them as a caveat.
+- External one-shot subagent routes, such as Codex, Claude Code, ACP, and DSH
+  SDK executions, cannot accept another turn or be cold-resumed. They are
+  reported as unresumable and are not registered as paused local sessions.
+- A paused session still looks `running` to parts of DSH's session lifecycle.
+  Exit may take about five seconds; archiving, context compaction, and
+  `wait_agent` can behave differently while a session is held.
+
+## Resume and goals
+
+Cleanly paused sessions resume from the point where they stopped. A session
+goal is re-opened by default, which means it can continue running rounds and
+spending money on its own. Before leaving, turn off the goal switch on the
+session control if you do not want that. The setting is recorded in the pause
+record and applies when that session is resumed.
+
+Sessions that did not stop cleanly are never resumed silently. The global
+control opens a decision list where each row can be continued, continued with a
+note that the tool result is unknown, opened for review without running, or
+left paused.
+
+## Commands
+
+The buttons drive these commands; they are useful for scripts and for
+keyboard-first use:
+
+| Command | Purpose |
+|---|---|
+| `/pause` | Pause the current session and its subagents. |
+| `/pause-resume` | Resume the current paused session tree. |
+| `/pause-resume-all` | Resume every paused session that stopped cleanly. |
+| `/pause-all` | Pause every running session tree. |
+| `/pause-state` | Report the current session tree's pause state. |
+| `/pause-state-all` | Report the whole-app pause state. |
+| `/pause-goal` | Toggle the current session's goal re-arm on resume. |
+| `/pause-triage` | Read the decision list for sessions that did not pause cleanly. |
+| `/pause-triage-continue`, `note`, `review`, `leave`, `goal` | Take one decision on a listed session. |
+
+Status reads are commands too, so they appear as command rows in the session
+transcript.
+
+## Requirements
+
+- DSH `>=0.2.2-alpha.2 <0.3.0-0`. The package declares this as `engines.dsh`;
+  the Plugin Manager refuses an older runtime instead of starting an
+  incompatible resume path.
+- The standard Web profile. It mounts `sessionQuery` and `agentPresets`, which
+  the resume path uses to rebuild each session's scoped Agent composition.
+- Building from this repository requires the local development layout described
+  in [DEVELOPMENT.md](DEVELOPMENT.md).
+
+The plugin makes no network calls. Pause records live in the profile's storage
+and session state stays in the existing session logs.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the workspace layout, build commands,
+test suite, and the local DeepSeek Harness dependency links. The end-to-end
+manual acceptance run lives in [REHEARSAL.md](REHEARSAL.md).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,91 @@
+# dsh-pause-session
+
+[English](README.md) | 中文
+
+<p align="center"><img src="icon.svg" width="64" height="64" alt="dsh-pause-session 图标"></p>
+
+在离开前暂停所有运行中的 DSH 会话及其子代理，之后再恢复。
+
+dsh-pause-session 会把每个会话停在同一个点：当前已经运行的工具先跑完，然后拦住下一条模型请求。子代理树也会一起暂停，暂停状态可以跨 DSH 重启保留。
+
+> 状态：beta。已针对 DSH `0.2.2-alpha.2` 验证；完整的实机演练见 [REHEARSAL.md](REHEARSAL.md)。
+
+<p align="center">
+  <img src="docs/images/pause-controls.webp" alt="dsh-pause-session 控件：会话已暂停，全局显示全部已暂停" width="100%">
+</p>
+
+*会话已暂停；全局控件显示“全部已暂停”（1/1）。*
+
+## 快速开始
+
+1. 打开 DSH Web 侧边栏的 **Plugins** 页面，把本目录作为 bundle 安装。仓库里已经提交了构建好的 `lib/`；如果改过源码，先执行 `pnpm run build`。也可以在该 profile 的会话里用 `plugin_manager` 的 `install_bundle`，传入本目录的绝对路径。本地开发布局见 [DEVELOPMENT.md](DEVELOPMENT.md)。
+2. 打开要暂停的会话。按标题旁的暂停按钮，会暂停这个会话及其子代理；按头部右侧的胶囊，会暂停所有运行中的会话树。
+3. 控件会先显示 **正在暂停**（Pausing），等运行中的工具结束、下一条模型请求被拦住后，才会变成 **已暂停**（Paused）。全局胶囊变成 **全部已暂停**（All Paused）时，所有已登记的会话都已停住。
+4. 下次按 **全部已暂停** 可以恢复所有干净暂停的会话；按会话旁的控制可以只恢复这一个会话及其子代理。
+
+## 两个控件
+
+| 控件 | 范围 | 作用 |
+|---|---|---|
+| 会话标题旁 | 一个会话及其子代理 | 暂停当前会话树，之后恢复同一个会话树。 |
+| 头部右侧胶囊 | 所有运行中的会话树 | 暂停所有已登记会话，之后恢复所有干净暂停的会话。 |
+
+有工具在运行时，会话显示 **正在暂停**。只有工具返回、下一条模型请求被拦住并且会话状态已保存后，才会进入 **已暂停**。
+
+## 暂停具体做了什么
+
+- 已经在运行的工具会先跑完；暂停生效后不会再发新的工具调用或模型请求。
+- 下一条模型请求会在到达供应商之前被拦住。
+- 已经登记在暂停树里的子代理会按同样规则停下。
+- 暂停状态是持久化的。DSH 退出或重启后，下次挂载会重新拦住这些会话。
+- 输入框保持可用；暂停要通过同一个控件释放，而不是靠再发一条消息。
+
+## 哪些东西不会被停住
+
+- agent loop 之外的后台任务和 shell 任务不会被停住；全局控件会把它们列为限制。
+- Codex、Claude Code、ACP、DSH SDK 等外部一次性子代理不能继续下一轮，也不能冷恢复。它们会被报告为不可恢复，不会登记成本地暂停会话。
+- 暂停中的会话在 DSH 的部分生命周期里仍显示为 `running`。退出 DSH 可能需要约 5 秒；归档、上下文压缩和 `wait_agent` 在会话被拦住时的行为可能不同。
+
+## 恢复与目标
+
+干净暂停的会话会从停下的位置恢复。会话目标默认会在恢复时重新打开，这意味着它可以自己继续跑轮次并产生消耗。离开前如果不想这样，可以在会话控件上关掉目标开关。这个设置会写进暂停记录，在该会话恢复时生效。
+
+没有干净暂停的会话不会被静默恢复。全局控件会打开决策清单，每一行可以继续、带说明继续（说明工具结果未知）、只看不运行，或保持暂停。
+
+## 命令
+
+按钮驱动的就是这些命令；脚本和键盘操作用得上：
+
+| 命令 | 作用 |
+|---|---|
+| `/pause` | 暂停当前会话及其子代理。 |
+| `/pause-resume` | 恢复当前暂停的会话树。 |
+| `/pause-resume-all` | 恢复所有干净暂停的会话。 |
+| `/pause-all` | 暂停所有运行中的会话树。 |
+| `/pause-state` | 读取当前会话树的暂停状态。 |
+| `/pause-state-all` | 读取整体暂停状态。 |
+| `/pause-goal` | 切换当前会话恢复时是否重新打开目标。 |
+| `/pause-triage` | 读取未干净暂停会话的决策清单。 |
+| `/pause-triage-continue`、`note`、`review`、`leave`、`goal` | 对清单中的一个会话执行对应决策。 |
+
+状态读取本身也是命令，所以会在会话转录里留下命令行。
+
+## 要求
+
+- DSH `>=0.2.2-alpha.2 <0.3.0-0`。包通过 `engines.dsh` 声明该范围；插件管理器会拒绝旧版本运行时，而不是启动不兼容的恢复路径。
+- 标准 Web profile。它会挂载 `sessionQuery` 和 `agentPresets`，恢复路径用它们重建每个会话原本的 Agent 组合。
+- 如果从本仓库构建，还需要满足 [DEVELOPMENT.md](DEVELOPMENT.md) 里的本地开发布局。
+
+插件不发起网络请求。暂停记录保存在 profile 的存储中，会话状态仍保存在原有会话日志里。
+
+## 开发
+
+工作区布局、构建命令、测试和本地 DeepSeek Harness 依赖链接见 [DEVELOPMENT.md](DEVELOPMENT.md)。完整的人工验收流程见 [REHEARSAL.md](REHEARSAL.md)。
+
+## 更新记录
+
+发布记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。

package/REHEARSAL.md

@@ -0,0 +1,90 @@
+# 演练：下班 → 过夜 → 上班
+
+这份文档是给**人**照着走的验收流程。代码侧的自动化测试已经覆盖了接缝；这里要证明的是真实机器上的那一整套动作。
+
+## 一、它要证明什么
+
+1. 按下暂停后，会话**停在下一条模型请求之前**，而不是停在工具中途。
+2. 界面能如实回答"现在都暂停了吗"，并且点名它兑现不了的承诺。
+3. 进程重启后暂停仍然成立；第二天一次恢复，会话从同一点继续，**模型上下文没有多出任何东西**。
+4. 未完全暂停的会话不会被静默唤醒，而是进清单交给你决定。
+
+## 二、已经做完的预检（无需重做）
+
+| 检查 | 结果 |
+|---|---|
+| 全量测试（typecheck + build + 全部用例） | 通过 |
+| 真实 Loader 组合：挂上插件真正 inject 的那几行 | 该行 `active`；裸组合里它停在 `pending`（如实断言） |
+| 一次性 profile + 绝对路径覆盖层冷启动 | **启动成功**，任务正常完成（退出码 0） |
+| 反向对照：给非法 `config` | **大声失败并点名插件与字段**，证明这一行真的被加载 |
+| 插件行加载失败会不会拦住启动 | **不会**——非 `required` 行只产生 `warning: 1 entry did not activate` |
+
+> 那次隔离验证建了一个一次性 profile `~/.dsh/profiles/<isolated-profile>`，与你的日常 profile 无关。
+
+## 三、安装（目标：`web` profile）
+
+选 `web` 的理由：它当前运行 `0.2.2-alpha.2`，与插件构建和验证所依据的版本一致。其他 profile 的版本可能不同，安装前先确认版本。
+
+1. 打开 Web 界面 → 侧边栏 **Plugins** 页面。
+2. 安装本目录（`<repository>`），或让会话里的 `plugin_manager` 执行 `install_bundle`。
+3. 安装结果里确认 `application: applied` 且 `warnings` 为空。
+
+**出问题的回滚**（照抄，别临场想）：
+
+- 插件行失败：**启动不会被拦住**，只会有一条 `warning: 1 entry did not activate`；在 Plugins 页面关掉它即可。
+- 整个应用起不来：用市场那个脱离宿主的恢复界面取消勾选本插件；或 `dsh plugin --profile web remove dsh-pause-session`，再把 `dsh-pause-session` 从该 profile `package.json` 的 `dsh.profile.bundles` 里删掉。
+
+## 四、演练 A：干净的下班 → 上班
+
+**先分清两颗按钮**（它们都是图标芯片，靠悬停文案区分）：
+
+| 按钮 | 位置 | 作用范围 |
+|---|---|---|
+| **会话那颗** | 会话标题旁 | **这个会话 + 它属下的全部子代理（含嵌套）** |
+| **胶囊** | 会话头部右侧的 utilities 行 | **所有**正在运行的会话树 |
+
+会话那颗只在**主会话**上出现——子代理会话上没有它（你不需要单独暂停子代理）。按下去的回答会报出登记了几个成员。再按一次的含义取决于状态：树里**还没有任何干净记录**时它是**取消**（把这次暂停收回来）；树里已经有停稳的成员时它是**释放**（父先子后，不干净的成员留在清单上）。
+
+用一个**无关紧要的会话**（不要用你正在干活的会话）：
+
+1. 让它跑一个会占住工具的动作，例如 `sleep 60`。
+2. 找到会话头部右侧的胶囊并按下。
+   - **期望**：胶囊显示"正在暂停"并**点名正在跑的工具**；此刻它还不会说全部已暂停。
+3. 等它变成"全部已暂停"。
+   - **期望**：只有在工具返回、请求停住、并且会话状态已保存之后才变色。
+   - **反例**：工具还在跑就显示“全部已暂停” → 失败。
+4. 确认会话**停在下一条请求之前**：它不应再出现新的模型输出；界面显示已暂停。
+5. 如果这个会话带着目标：在它的标题栏控件上把**目标开关关掉**（"恢复这个会话时不会自己重新启动它的目标"）。
+   - **期望**：开关状态来自宿主，按一下之后会被重新读取，而不是本地翻转。
+6. 直接退出 DSH（或强杀），重启。
+   - **期望**：重启后该会话仍是暂停状态；`/pause-state-all` 仍能读到它。
+7. 按恢复（胶囊或 `/pause-resume-all`）。
+   - **期望**：会话从停下的那点继续，模型回应的是暂停时那条待发输入；**上下文里没有"你被打断过"之类的新内容**。
+   - **期望（目标）**：第 5 步关掉开关的那些会话，恢复后**目标保持不启动**、不产生新的轮次；没关的照常推进。
+   - **前提**：早上的组合必须提供与昨天相同的工具集，否则 DSH 自己会补工具增减的系统消息，"线上零新增"的肉眼结论会失真。
+
+## 五、演练 B：未完全暂停的早晨
+
+1. 再起一个会话，让它跑一个长工具（`sleep 300`）。
+2. **不按停止**，直接强杀 DSH（`kill -9`）。
+   - 这一格模拟"合盖/被杀"，也就是没有受控停顿的那条路径。
+3. 重启后打开胶囊里的清单。
+   - **期望**：该会话在清单里，显示停在哪个工具、留下了什么痕迹。
+   - **可能的真相**：子代理常**根本没有保存的会话日志**，此时清单必须如实显示"读不到"，而不是编一行出来。
+4. 逐行试四个动作：直接继续 / 继续并附说明 / 只看不跑 / 今天先别碰。
+   - **期望**："只看不跑"**保持暂停、不激活 agent、不产生任何模型请求**——它只给你一个答复，现场要你自己去会话历史里看；"继续并附说明"的那条请求里带着"结果未知、不要盲目重试"的说明。
+
+## 六、已知代价与限制（不是 bug）
+
+- 暂停中的会话在核心看来仍是 running：退出 DSH 会约 5 秒后被强退（所以停止前必须 flush）；归档会报错或不等结算；压缩会以"已有工作"报错；等待该会话的 RPC 会挂住客户端；`wait_agent` 会白等到上限。
+- 暂停中的会话会在斜杠命令菜单里多出 `/pause-resume`、`/pause-state`、`/pause-goal`（以及全局的 `/pause-all`、`/pause-state-all`、`/pause-triage*`）——状态通道的形状就是这么来的。**每次读状态都是一次命令执行，因此会在对话里留下一行**（harness 无条件记录并渲染每一次命令执行，没有"不记录"的开关）。读取已改成事件驱动：一次暂停周期个位数次，停稳后不再读；但被暂停会话自己的转录里仍会剩下那么几行，无关会话不会再出现。
+- 对一个已经暂停的会话再按一次暂停**不会**产生新的停稳判定；要新判定必须先恢复、跑出新的工作周期、再停一次。
+- 时间上下文冻结在暂停时刻（"仿佛没中断"的字面含义）。
+- 一次性子代理路由（`subagent_codex` / `subagent_claude_code` 之类桥接）的工作跨重启无法续跑，只会被点名。
+- 后台 shell 任务不在 agent loop 内，插件停不住，只会被点名。
+
+## 七、还没被验证的地方（说清楚，不含糊）
+
+- 胶囊的完整视觉验收尚未做；本地 Web 页面已确认控件渲染、状态可读，并已在插件页看到 `Pause` 的标题与描述。
+- 唤醒在真实模型上的效果：空唤醒是否被服务商接受、兜底那条极简标记会不会诱发模型重述。
+- 真实整机重启（本次只做了隔离 profile 的冷启动 + 自动化重启用例）。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-pause-session
+      name: dsh-pause-session

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Pause">
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="#111827"/>
+  <rect x="20" y="18" width="9" height="28" rx="3" fill="#F5C451"/>
+  <rect x="35" y="18" width="9" height="28" rx="3" fill="#F5C451"/>
+</svg>