dsh-human-wait 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.2 — 2026-11-15
+
+- Rewrote the README for users: when the plugin helps, what it does and does not change (a table
+  with the four cases), how to install and where the setting lives. The Chinese README is now
+  primary and `README.en.md` is the English translation.
+- Moved the implementation notes, the acceptance record and the tests to `docs/implementation.md`
+  and `docs/implementation.en.md`.
+
 ## 0.2.1 — 2026-10-27
 
 - Adds a browser half (`client.js`), so the plugin gets its own settings page under **Plugins**:

package/README.en.md

@@ -0,0 +1,69 @@
+# dsh-human-wait
+
+**Stops the PTC `run_code` deadline while DSH is waiting for you.**
+
+PTC mode wraps the whole program — including any question, plan review or approval raised mid-run — in one 120-second wall clock. Think a little too long and the run is already gone:
+
+```
+Error: code run failed (timeout): execution deadline reached (120000ms)
+```
+
+and the question card is reported as **interrupted**. With this plugin, the time you spend answering is no longer charged to that budget; a runaway program is still cut off when the budget runs out.
+
+> English | [中文](README.md)
+
+## When you need it
+
+- You run programs in PTC mode that ask you questions or need approvals, and you want to read before answering
+- You have seen a question card flip to "interrupted", or the timeout above
+
+## What it changes, and what it does not
+
+| Situation | Without it | With it |
+| --- | --- | --- |
+| A question inside the run, answered in 20 s | fine | fine |
+| Same run, answered after 4 minutes | aborted at 120 s, question shown as interrupted | keeps waiting, the answer is delivered |
+| Never answered | aborted at 120 s | aborted once the wait hits the cap (24 h by default) |
+| A program that spins for 10 minutes without asking anything | aborted at 120 s | aborted at 120 s — unchanged |
+
+## Install
+
+1. Open **Settings → Plugins → Market** and search for `dsh-human-wait`
+2. Install it
+3. **Quit DSH completely, then start it again**
+
+## Settings
+
+**Settings → Plugins → Installed → Human wait**:
+
+- **Longest wait** (24 hours by default; "unlimited" removes the cap)
+- Quick buttons: 1 hour / 24 hours / unlimited
+- **Restore default** appears once the field differs from the shipped value
+- A one-line summary sits on the card
+
+A change takes effect in about 1.5 seconds, no restart.
+
+## FAQ
+
+**It still timed out?** Check three things: the session header shows the `PTC` badge; the plugin's `enabled` is not set to false in the profile patch; the log has a line starting with `[dsh-human-wait]`. If the wrapper did not see that wait, it cannot pause for it.
+
+**The error kind became `abort`?** Expected. The plugin aborts through its own signal, so the runtime classifies it as `abort` instead of `timeout`; the text still contains `execution deadline reached`.
+
+**Does it affect standard sessions?** No. Standard sessions never had this timeout — they wait indefinitely by design.
+
+## Privacy and cost
+
+- Wraps three host service calls in memory only; writes no files and opens no network connections
+- Does not modify the conversation, and does not change the program's own execution budget
+
+## Uninstall
+
+Disable or remove it in the plugin panel, then restart DSH; the host's original methods come back.
+
+## Technical notes
+
+How it works, the two settings, the fail-open behaviour and the acceptance record: [docs/implementation.en.md](https://github.com/SpaceRelay/dsh-subagent-control/blob/main/human-wait/docs/implementation.en.md)
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Issues: [github.com/SpaceRelay/dsh-subagent-control/issues](https://github.com/SpaceRelay/dsh-subagent-control/issues)

package/README.md

@@ -1,184 +1,69 @@
 # dsh-human-wait
 
-**Stops the PTC `run_code` deadline while DSH is waiting for you.** In PTC mode a question
-(`ask_user_question`), the plan review raised by `exit_plan_mode`, or a sandbox approval is a
-nested call inside the one `run_code` program — and `dsh-ptc-runtime-node` measures a single
-wall-clock budget across the whole program, *including the time you spend answering*. Wait
-longer than what is left of that budget and the run dies with:
+**PTC 模式下，DSH 在等你回答问题时，不再让执行超时继续倒数。**
+
+PTC（`run_code`）把整个程序——包括中途弹出的问题、计划审批、权限批准——包在一条 120 秒的墙钟预算里。你想久一点再回答，程序就已经超时了：
 
 ```
 Error: code run failed (timeout): execution deadline reached (120000ms)
 ```
 
-and the question card is reported as **已中断 / interrupted**. This plugin keeps the deadline
-for execution but pauses it while a human-interaction wait is pending. A runaway program is
-still cut off after its budget; a question you think about for an hour is not.
-
-> 中文摘要：PTC 模式下提问、计划审批和批准都是 `run_code` 里的嵌套调用，共用同一条 120 秒墙钟预算，
-> 所以「想久一点再回答」会让你看到的是一次 `execution deadline reached (120000ms)` 超时。本插件
-> 保留执行的截止时间，但在**等待你回答/批准期间暂停计时**；等待本身另有上限（默认 24 小时，可设为无限）。
-
----
-
-## What it does
-
-| Situation | Without the plugin | With the plugin |
-| --- | --- | --- |
-| A question inside `run_code`, you answer in 20 s, run budget was 120 s | OK | OK |
-| Same run, you answer after 4 minutes | run aborted at 120 s, question interrupted | run keeps waiting; the answer is delivered |
-| Same run, you never answer | run aborted at 120 s | run aborted once the wait exceeds `humanWaitCapMs` (24 h) |
-| A program that spins for 10 minutes without asking anything | aborted at 120 s | aborted at 120 s — unchanged |
-
-It works by:
-
-1. wrapping `ptcRuntime.run` and moving the deadline into the plugin, so it can be paused;
-2. wrapping `userQuestions.ask` / `userQuestions.askTimed` and `approval.request` — the three
-   service calls that exist only because a human is being waited on;
-3. charging the budget only while no such wait is pending (`node:async_hooks`
-   `AsyncLocalStorage` keeps the accounting scoped to the run that is actually waiting).
+问题卡还会被标成「已中断」。装上这个插件，等待你回答的那段时间不再计入预算；程序自己跑飞了，照样在预算到点时被掐断。
 
-A single `run_code` call can still pass its own `timeoutMs`; that number keeps working as the
-execution budget and is what the plugin enforces.
+> [English](README.en.md) | 中文
 
-## Install
+## 什么时候用得上
 
-The plugin is a normal DSH bundle: one inserted host row, plus a browser half that renders the
-settings page under **Plugins**. Pick one route:
+- 用 PTC 模式跑程序，中途要你回答问题或审批，而你想读完再答
+- 遇到过「问题卡突然变成已中断」或者上面那条超时
 
-**A. From the registry (recommended).** Use the Plugins settings page, or a
-`plugin_manager install_bundle` call in a session, with the spec `dsh-human-wait@0.2.1`; the
-plugin manager adds both the dependency and the bundle entry for you.
+## 它改什么、不改什么
 
-**B. From a tarball, by hand.** In `<DSH_HOME>/profiles/<profile>/package.json` add the dependency
-and the bundle name, then install it:
+| 情况 | 没装 | 装了 |
+| --- | --- | --- |
+| 程序里提问，20 秒答完 | 正常 | 正常 |
+| 同一个程序，4 分钟后才答 | 120 秒就被中止，问题卡显示已中断 | 继续等，答案照常送达 |
+| 一直不答 | 120 秒中止 | 等到最长等待上限（默认 24 小时）才中止 |
+| 程序自己死循环 10 分钟 | 120 秒中止 | 120 秒中止，行为不变 |
 
-```jsonc
-{
-  "dependencies": {
-    "dsh-human-wait": "file:D:/path/to/dsh-human-wait-0.2.1.tgz"
-  },
-  "dsh": { "profile": { "bundles": ["dsh-human-wait"] } }
-}
-```
+## 安装
 
-```powershell
-# pnpm ships with the desktop runtime
-& "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\pnpm.cjs" install --dir "$env:USERPROFILE\.dsh\profiles\desktop"
-```
+1. 打开 设置 → 插件 → 市场，搜索 `dsh-human-wait`
+2. 点安装
+3. **完全退出 DSH，再重新打开**
 
-Then **quit DSH from the tray icon and start it again** — bundles are composed at boot. The
-Electron-managed profile cannot be booted through the `dsh` CLI (`profile "desktop" is managed
-exclusively by the Electron application`), so restarting the app is the only way to apply it.
-Removing the bundle name from `dsh.profile.bundles` and deleting the dependency disables the
-plugin again; the wrappers are also restored at unload time.
+## 设置
 
-## Configuration
+设置 → 插件 → 已安装 → **人机等待**：
 
-The row ships sensible defaults; override them in the same profile's `cordis.patch.yml` when
-you want something else:
+- **最长等待**（默认 24 小时；选「无限」表示不设上限）
+- 快捷按钮：1 小时 / 24 小时 / 无限
+- 字段偏离出厂值时会出现「恢复默认」
+- 卡片上有一行摘要
 
-```yaml
-- id: human-wait
-  name: 'dsh-human-wait'
-  config:
-    enabled: true
-    humanWaitCapMs: 86400000   # 24 h; -1 = no cap at all
-```
+改完约 1.5 秒生效，不用重启。
 
-| Option | Default | Meaning |
-| --- | --- | --- |
-| `enabled` | `true` | Turn the pause on/off. `false` reproduces the shipped behaviour exactly. |
-| `humanWaitCapMs` | `86400000` | Longest time one run may spend waiting for a human. `-1` removes the cap. |
-
-How the clock works: the plugin re-arms a single timer on every accounting event (run start, a
-wait starting or ending, or the timer itself firing), so there is no fixed sampling period and
-no configuration knob for one.
-
-Both options are **volatile**: they are read again while the plugin is running, so a change
-takes effect within about a second and a half, with no restart. Editing the
-patch by hand is still read at boot.
-
-## Settings page
-
-The plugin ships a browser half, so it gets its own card on its page under **Plugins** (the same
-place as Team limits):
-
-- a number field for `humanWaitCapMs`, with quick buttons for 1 hour / 24 hours / unlimited;
-- an "overridden" chip and a "restore default" action for that field;
-- a one-line summary on the card itself.
-
-`enabled` stays in the patch layer (`cordis.patch.yml`), where it is read live within about a
-second and a half.
-
-The values are written back to this profile's patch layer through the normal settings path;
-uninstalling the plugin does not roll them back.
-
-## What counts as a human wait
-
-- `userQuestions.ask` — blocking questions, including the `plan-review` question from
-  `exit_plan_mode`;
-- `userQuestions.askTimed` — timed questions;
-- `approval.request` — sandbox/policy approvals that block on the user.
-
-Tool calls that finish on their own (bash, file reads, web fetches, subagents) are **not**
-waits: their time is still charged to the run, exactly as before.
-
-## Behaviour notes
-
-- **Fail-open.** If `ptcRuntime` / `userQuestions` / `approval` are missing, if
-  `AbortSignal.any` is unavailable, or if a wrapper cannot be installed, the plugin logs one
-  warning and leaves the shipped deadline untouched.
-- **Restored on unload.** Every wrapper is removed when the plugin unloads (or is disabled and
-  the profile restarted); the original methods are back.
-- **The terminal error changes kind.** When the paused execution budget runs out, the runtime
-  reports `kind: "abort"` instead of `kind: "timeout"`, because the plugin aborts the run
-  through its signal. The message still contains `execution deadline reached (<budget>ms)`, so
-  the surfaced text is the same.
-- **Only PTC sessions are affected.** Standard sessions never had this timeout: their
-  questions wait indefinitely by design.
-- **Not a public extension point.** The plugin patches methods of two host services
-  (`ptcRuntime`, `userQuestions`) and one approval service. That is the only way to implement
-  this today; a future DSH release may change those internals and make the patch a no-op. The
-  plugin is written so that this failure mode is safe, not fatal.
-
-Verified against DSH desktop **0.2.1-rc.3** (`dsh-ptc-runtime-node` 0.2.1, node 24.21).
-`ptc-runtime-node/lib/index.js` is where the shipped timer lives:
-
-```js
-const wallTimer = spec.timeoutMs === null ? void 0 : setTimeout(() => {
-  timedOut = true;
-  controller.abort("execution deadline reached");
-}, spec.timeoutMs);
-```
+## 常见问题
 
-## Troubleshooting
+**还是超时了？** 确认三件事：会话头部显示 PTC 标记；插件的 `enabled` 没在 profile 补丁里被关掉；日志里有 `[dsh-human-wait]` 开头的那行说明。如果等待期间恰好插件没看到这次等待，它就不会暂停计时。
 
-- Look for `[dsh-human-wait]` lines in the DSH log; the plugin logs either
-  `PTC run deadlines now pause while a human is waiting (wait cap: …)` or the reason it stayed
-  out of the way.
-- If a wait still dies with `execution deadline reached`, the wrapper did not see the wait.
-  Check that PTC mode is actually in use (the session header shows the `PTC` badge) and that
-  `enabled` is not `false`.
+**错误类型变成 `abort` 了？** 正常。插件用自己的信号中止程序，所以 kind 从 `timeout` 变成 `abort`，提示文字里仍然有 `execution deadline reached`。
 
-## Development
+**普通会话受影响吗？** 不受影响。普通会话本来就会一直等你回答，没有这个超时。
 
-```powershell
-npm test        # node --test, no dependencies
-```
+## 隐私与开销
 
-## License
+- 只在内存里包住三个宿主服务的调用，不写文件、不联网
+- 不修改会话内容，也不改变程序本身的执行预算
 
-MIT
+## 卸载
 
-## Acceptance record
+在插件面板里停用或卸载，然后重启 DSH；宿主原来的方法会恢复。
 
-Recorded 2026-10-26 against `dsh-human-wait` 0.1.0 in the desktop profile (PTC mode, shipped 120 s budget):
+## 技术细节
 
-| Test | Scenario | Observed |
-| --- | --- | --- |
-| A | nested `ask_user_question`, answered after 294037 ms | answer delivered, run continued, no `execution deadline reached` |
-| B | plan review submitted through `exit_plan_mode`, approved after 313073 ms | plan approved, run continued, no automatic cancellation at 120 s |
-| C | `run_code` running `while (true) {}` | killed after ~120 s with `Error: code run failed (abort): execution deadline reached (120000ms)` |
+实现原理、两个配置项、失败时的降级行为与验收记录：[docs/implementation.md](https://github.com/SpaceRelay/dsh-subagent-control/blob/main/human-wait/docs/implementation.md)
 
-Test C's `(abort)` label is expected — the plugin aborts through its own signal, so the runtime classifies the failure as `abort` instead of `timeout` while the message text stays `execution deadline reached (120000ms)`.
+## 许可
 
+MIT，见 [LICENSE](./LICENSE)。问题反馈：[github.com/SpaceRelay/dsh-subagent-control/issues](https://github.com/SpaceRelay/dsh-subagent-control/issues)

package/docs/implementation.en.md

@@ -0,0 +1,77 @@
+# dsh-human-wait — implementation notes
+
+For maintainers. User-facing docs live in [../README.en.md](../README.en.md).
+
+## The problem
+
+In PTC mode, `dsh-ptc-runtime-node` puts one wall-clock budget around the entire `run_code` program, nested tool calls and approval waits included:
+
+```js
+const wallTimer = spec.timeoutMs === null ? void 0 : setTimeout(() => {
+  timedOut = true
+  controller.abort("execution deadline reached")
+}, spec.timeoutMs)
+```
+
+So the time spent waiting for you burns the budget too. This project takes the timer over and charges it only while no human-interaction wait is pending.
+
+## How it works
+
+1. Wrap `ptcRuntime.run`: the deadline moves into the plugin, which can pause it.
+2. Wrap the three points where a human is actually being waited on: `userQuestions.ask`, `userQuestions.askTimed`, `approval.request`.
+3. Use `node:async_hooks` `AsyncLocalStorage` to scope the accounting to the run that is really waiting, charging the budget only while no such wait is pending.
+
+A single `run_code` call can still pass its own `timeoutMs`; that number keeps working as the execution budget.
+
+## Configuration
+
+The row ships sensible defaults; override them in the same profile's `cordis.patch.yml`:
+
+```yaml
+- id: human-wait
+  name: 'dsh-human-wait'
+  config:
+    enabled: true
+    humanWaitCapMs: 86400000   # 24 h; -1 = no cap at all
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch for pausing. `false` reproduces the shipped behaviour exactly. |
+| `humanWaitCapMs` | `86400000` | Longest time one run may spend waiting for a human. `-1` removes the cap. |
+
+Both options are **volatile**: they are re-read while the plugin runs, so a change applies in about 1.5 seconds without a restart. A hand-edited patch is read at boot.
+
+## Settings page
+
+`client.js` is a hand-written browser half registered on the `plugins.bundle.config` slot (key `dsh-human-wait`): a `humanWaitCapMs` number field, 1 hour / 24 hours / unlimited quick buttons, a field-level "overridden" chip with "restore default", and a one-line summary on the card. `enabled` stays in the patch layer.
+
+## Behaviour notes
+
+- **Fail-open.** If `ptcRuntime` / `userQuestions` / `approval` are missing, if `AbortSignal.any` is unavailable, or if a wrapper cannot be installed, the plugin logs one warning and leaves the shipped deadline untouched.
+- **Restored on unload.** Every wrapper is removed when the plugin unloads (or is disabled and the profile restarted); the original methods are back.
+- **The terminal error changes kind.** When the paused execution budget runs out, the runtime reports `kind: "abort"` instead of `kind: "timeout"`, because the plugin aborts the run through its signal. The message still contains `execution deadline reached (<budget>ms)`.
+- **Only PTC sessions are affected.** Standard sessions never had this timeout: their questions wait indefinitely by design.
+- **Not a public extension point.** The plugin patches methods of two host services (`ptcRuntime`, `userQuestions`) and one approval service. That is the only way to implement this today; a future DSH release may change those internals and make the patch a no-op. The plugin is written so that this failure mode is safe, not fatal.
+
+## Verified environment and acceptance record
+
+Verified against DSH desktop **0.2.1-rc.3** (`dsh-ptc-runtime-node` 0.2.1, Node 24.21).
+
+Recorded 2026-10-26 against `dsh-human-wait` 0.1.0 in the desktop profile (PTC mode, shipped 120 s budget):
+
+| Test | Scenario | Observed |
+| --- | --- | --- |
+| A | nested `ask_user_question`, answered after 294037 ms | answer delivered, run continued, no `execution deadline reached` |
+| B | plan review submitted through `exit_plan_mode`, approved after 313073 ms | plan approved, run continued, no automatic cancellation at 120 s |
+| C | `run_code` running `while (true) {}` | killed after ~120 s with `Error: code run failed (abort): execution deadline reached (120000ms)` |
+
+Test C's `(abort)` label is expected — the plugin aborts through its own signal, so the runtime classifies the failure as `abort` instead of `timeout` while the message text stays `execution deadline reached (120000ms)`.
+
+## Tests
+
+```powershell
+npm test    # node --test, no dependencies
+```
+
+Coverage: re-reading both settings, wrapping and restoring the three wait points, the fail-open branches, and the browser half (bundle id, slot key, page rendering).

package/docs/implementation.md

@@ -0,0 +1,77 @@
+# dsh-human-wait 实现说明
+
+面向维护者。用户向说明见 [../README.md](../README.md)。
+
+## 问题
+
+PTC 模式下，`dsh-ptc-runtime-node` 用一条墙钟预算覆盖整个 `run_code` 程序，嵌套的工具调用与审批等待都算在里面：
+
+```js
+const wallTimer = spec.timeoutMs === null ? void 0 : setTimeout(() => {
+  timedOut = true
+  controller.abort("execution deadline reached")
+}, spec.timeoutMs)
+```
+
+于是「等你回答问题」也烧预算。本项目把这个计时器接管过来，只在没有人类交互等待时计费。
+
+## 做法
+
+1. 包装 `ptcRuntime.run`：把 deadline 移进插件，由插件自己计时并可暂停。
+2. 包装三个人类等待点：`userQuestions.ask`、`userQuestions.askTimed`、`approval.request`。只有这三类调用会产生「等待人」的时间。
+3. 用 `node:async_hooks` 的 `AsyncLocalStorage` 把计费限定在真正在等待的那次运行上，只在没有等待挂起时扣预算。
+
+单个 `run_code` 调用仍可自带 `timeoutMs`，它继续作为执行预算生效。
+
+## 配置
+
+行内默认值够用；要改就在 profile 的 `cordis.patch.yml` 里覆盖：
+
+```yaml
+- id: human-wait
+  name: 'dsh-human-wait'
+  config:
+    enabled: true
+    humanWaitCapMs: 86400000   # 24 小时；-1 = 不设上限
+```
+
+| 选项 | 默认 | 含义 |
+| --- | --- | --- |
+| `enabled` | `true` | 暂停总开关。`false` 完全回到宿主原生行为 |
+| `humanWaitCapMs` | `86400000` | 单次运行等待人类的最长时间，`-1` 表示不限 |
+
+两个选项都是 **volatile**：插件运行期间会被重新读取，改完约 1.5 秒生效，不用重启。手动改补丁则在下次启动时读取。
+
+## 设置页
+
+`client.js` 是手写的浏览器半边，注册在 `plugins.bundle.config` 槽（key `dsh-human-wait`）：一个 `humanWaitCapMs` 数字框、1 小时 / 24 小时 / 无限三个快捷按钮、字段级「已覆盖」与「恢复默认」，卡片上还有一行摘要。`enabled` 留在补丁层。
+
+## 行为说明
+
+- **Fail-open。** 缺少 `ptcRuntime` / `userQuestions` / `approval`、没有 `AbortSignal.any`、或者包装装不上时，插件只打一条警告，宿主原有 deadline 原样保留。
+- **卸载时恢复。** 插件卸载（或被停用后重启）时每个包装都会被拆掉，宿主原方法恢复。
+- **错误 kind 会变。** 暂停后的执行预算耗尽时，运行时报告 `kind: "abort"` 而不是 `"timeout"`，因为插件是通过自己的信号中止的；消息文本里仍有 `execution deadline reached (<budget>ms)`。
+- **只影响 PTC 会话。** 标准会话本来就没有这个超时。
+- **不是公开扩展点。** 插件包装的是两个宿主服务（`ptcRuntime`、`userQuestions`）和审批服务的方法，这是当前唯一可行的实现方式；未来 DSH 版本改动这些内部实现可能让它变成空操作——代码写成这种失败是安全的，不是致命的。
+
+## 验证环境与验收记录
+
+验证环境：DSH desktop **0.2.1-rc.3**（`dsh-ptc-runtime-node` 0.2.1，Node 24.21）。
+
+2026-10-26 在 `dsh-human-wait` 0.1.0 上测得（桌面 profile，PTC 模式，出厂 120 秒预算）：
+
+| 用例 | 场景 | 结果 |
+| --- | --- | --- |
+| A | 嵌套 `ask_user_question`，294037 ms 后才回答 | 答案送达，运行继续，没有 `execution deadline reached` |
+| B | `exit_plan_mode` 计划审批，313073 ms 后才批准 | 计划通过，运行继续，没有被 120 秒取消 |
+| C | `run_code` 里 `while (true) {}` | 约 120 秒后被终止，`Error: code run failed (abort): execution deadline reached (120000ms)` |
+
+用例 C 的 `(abort)` 是预期行为：插件用自己的信号中止，运行时因此把失败归类为 `abort` 而不是 `timeout`，消息文本不变。
+
+## 测试
+
+```powershell
+npm test    # node --test，无依赖
+```
+
+覆盖：两个配置项的重读、三个等待点的包装与恢复、fail-open 分支，以及浏览器半边的 bundle id / 槽位 / 页面渲染。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-human-wait",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Pauses the PTC run_code deadline while DSH is waiting for you to answer a question, review a plan or approve a request, so long human waits are no longer reported as `execution deadline reached (120000ms)`.",
   "license": "MIT",
   "author": {
@@ -33,6 +33,8 @@
     "locale/*.json",
     "icon.svg",
     "README.md",
+    "README.en.md",
+    "docs",
     "CHANGELOG.md",
     "LICENSE"
   ],