dsh-offpeak-guard 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.1 — 2026-11-06
+
+- 左侧会话行悬停操作新增盾牌按钮：直接在对话索引里豁免/取消豁免，豁免中的会话行保留盾牌标记。
+- 输入框状态条新增「豁免本会话 / 取消豁免」按钮，不用打开设置面板即可切换当前对话。
+- 设置面板的会话豁免列表新增搜索过滤，会话多时可按标题或 session id 查找。
+- 设置接口的浏览器请求补 `credentials: same-origin`，确保桌面 Web 主机下开关生效。
+
+## 0.3.0 — 2026-11-06
+
+- 新增峰时策略 `pauseMode`：`pause-now` 立即暂停，`finish-turn` 完成当前轮后暂停；设置面板可切换。
+- 子代理感知：会话有正在运行的子代理时先放行，子代理结束后再暂停父会话并记录，谷价开始自动恢复。
+- 精确模型识别：按 `provider/model` 精确匹配，`peakPricedModels` 精确列表 + `exemptModels` 豁免；设置面板可逐模型开关。
+- 新增设置面板（点击左栏计时打开）：峰时策略、模型管理、会话豁免、节假日同步状态。
+- 会话豁免：`offpeak_guard exempt/unexempt` 或设置面板，可随时取消。
+- 节假日动态识别：默认从公开节假日 API 同步当前/下一年，缓存到 `holidays.json`，失败回退内置 2026 列表；`holidaySource: builtin` 可完全离线。
+- 新增环境变量：`DSH_OFFPEAK_PAUSE_MODE`、`DSH_OFFPEAK_HOLIDAY_SOURCE`、`DSH_OFFPEAK_HOLIDAY_API`、`DSH_OFFPEAK_PEAK_MODELS`。
+- 状态 schema 扩展：等待中的任务、会话豁免、模型规则、峰时策略；兼容旧 `state.json`。
+
 ## 0.2.0 — 2026-11-05
 
 - 默认规则改为 DeepSeek 官方峰谷：工作日 09:00–12:00、14:00–18:00 峰时，周末与**中国法定节假日全天**谷价；内置 2026 年节假日列表。

package/README.en.md

@@ -7,14 +7,16 @@ Published on npm: install it from the DSH Plugins page, or run
 
 Schedule work around **DeepSeek peak/off-peak pricing** inside DeepSeek Harness:
 
-- **Time awareness**: per DeepSeek's official pricing, Beijing-time weekdays (excluding Chinese statutory holidays) `09:00–12:00` and `14:00–18:00` are peak; every other hour (weekends, holidays, lunch, night) is off-peak at 50%. Built-in Chinese holidays cover 2026; add later years with `holidays`.
-- **Model awareness**: only sessions using a peak-priced model (model name contains `deepseek` by default; exempt models one by one with `exemptModels`) are paused/resumed. Other models are untouched.
+- **Time awareness**: per DeepSeek's official pricing, Beijing-time weekdays (excluding Chinese statutory holidays) `09:00–12:00` and `14:00–18:00` are peak; every other hour (weekends, holidays, lunch, night) is off-peak at 50%. Holidays sync from a public API with a built-in 2026 fallback.
+- **Model awareness**: exact `provider / model` detection; models containing `deepseek` are managed by default, and the settings panel can toggle each model. `peakPricedModels` / `exemptModels` provide exact control.
+- **Peak strategy**: choose immediate pause or finish the current turn first; if a session has running subagents, they are allowed to finish and the parent is paused afterwards, then resumed at off-peak.
+- **Session exemptions**: exempt any session from the guard (settings panel or `offpeak_guard exempt/unexempt`), and un-exempt it at any time.
 - **Work planning**:
   - peak starts → running tasks are paused (the pending inbox is kept, no message is lost);
   - a task started during peak → stopped immediately, no peak-priced tokens spent;
   - off-peak starts → interrupted tasks are handed back to their session automatically;
   - the `offpeak_plan` tool queues "run this at noon" work for the next off-peak window.
-- **UI**: a status strip under the composer (state, countdown, model, paused/planned counts), plus a compact clock at the sidebar foot that blinks red before peak starts and green before off-peak starts.
+- **UI**: a status strip under the composer (state, countdown, model, paused/planned counts), plus a compact clock at the sidebar foot that blinks red before peak starts and green before off-peak starts. Click the clock to open settings. Hover a session row in the left sidebar for a shield button to exempt/un-exempt it; exempt rows keep a shield marker, and the composer strip has an **Exempt this session** toggle.
 
 ![Status strip under the composer](docs/peak-strip.png)
 
@@ -26,6 +28,10 @@ Red blink within the alert window before peak (sample):
 
 ![Sidebar clock blinking red](docs/sidebar-clock-blink.png)
 
+Click the clock to open the settings panel:
+
+![Settings panel](docs/settings-panel.png)
+
 ## Tools
 
 | Tool | Purpose |
@@ -42,12 +48,16 @@ The `offpeak-guard` row's `config` in `cordis.patch.yml`, or the plugin settings
 | --- | --- | --- |
 | `enabled` | `true` | Master switch |
 | `preset` | `auto` | `auto` picks by provider: WorkBuddy/CodeBuddy → `workbuddy`, otherwise `deepseek-official`; can be pinned to `deepseek-official` / `workbuddy` / `custom` |
+| `pauseMode` | `pause-now` | `pause-now` pauses immediately; `finish-turn` pauses after the current turn |
 | `timezone` | `Asia/Shanghai` | Pricing time zone (DeepSeek bills in Beijing time) |
 | `peakWeekdays` | `[1,2,3,4,5]` | Weekdays with peak windows (0 = Sunday); only used by `custom` |
 | `peakWindows` | 09:00–12:00, 14:00–18:00 | Peak windows; only used by `custom` |
 | `discount` | `0.5` | Off-peak discount, display only; only used by `custom` |
-| `holidays` | `[]` | Extra statutory holidays (`YYYY-MM-DD`), appended to the built-in 2026 list for the official/WorkBuddy presets |
-| `modelPattern` | `deepseek` | Model/provider name containing it counts as peak-priced |
+| `holidays` | `[]` | Extra statutory holidays (`YYYY-MM-DD`) appended to synced/built-in dates |
+| `holidaySource` | `auto` | `auto` syncs from the public holiday API; `builtin` stays offline |
+| `holidayApi` | timor.tech | Dynamic holiday API prefix |
+| `modelPattern` | `deepseek` | Fallback match when no exact model list is set |
+| `peakPricedModels` | `[]` | Exact peak-priced models (`provider/model` or `model`); takes priority over `modelPattern` |
 | `exemptModels` | `[]` | Model ids exempted one by one |
 | `pauseRunningOnPeak` | `true` | Pause running tasks when peak starts |
 | `deferNewTurnsOnPeak` | `true` | Stop tasks started during peak immediately |
@@ -65,12 +75,16 @@ Deployments can inject settings with environment variables. Priority: **env > co
 | --- | --- | --- |
 | `DSH_OFFPEAK_ENABLED` | `0` / `1` | `enabled` |
 | `DSH_OFFPEAK_PRESET` | `custom` | `preset` |
+| `DSH_OFFPEAK_PAUSE_MODE` | `finish-turn` | `pauseMode` |
 | `DSH_OFFPEAK_TIMEZONE` | `Asia/Shanghai` | `timezone` |
 | `DSH_OFFPEAK_PEAK_WEEKDAYS` | `1,2,3,4,5` | `peakWeekdays` |
 | `DSH_OFFPEAK_PEAK_WINDOWS` | `09:00-12:00,14:00-18:00` | `peakWindows` |
 | `DSH_OFFPEAK_DISCOUNT` | `0.5` | `discount` |
 | `DSH_OFFPEAK_HOLIDAYS` | `2026-10-01,2026-10-02` | `holidays` |
+| `DSH_OFFPEAK_HOLIDAY_SOURCE` | `builtin` | `holidaySource` |
+| `DSH_OFFPEAK_HOLIDAY_API` | `https://.../year` | `holidayApi` |
 | `DSH_OFFPEAK_MODEL_PATTERN` | `deepseek` | `modelPattern` |
+| `DSH_OFFPEAK_PEAK_MODELS` | `deepseek-flash,vendor/model` | `peakPricedModels` |
 | `DSH_OFFPEAK_EXEMPT_MODELS` | `deepseek-v4-pro,deepseek-flash` | `exemptModels` |
 | `DSH_OFFPEAK_PAUSE_RUNNING` | `0` / `1` | `pauseRunningOnPeak` |
 | `DSH_OFFPEAK_DEFER_NEW` | `0` / `1` | `deferNewTurnsOnPeak` |
@@ -87,12 +101,28 @@ Deployments can inject settings with environment variables. Priority: **env > co
 - `custom`: use `peakWeekdays` / `peakWindows` / `discount` / `holidays` exactly, for other providers or self-hosted pricing.
 
 
+## Settings panel
+
+Click the sidebar clock to open it:
+
+- **Peak strategy**: pause immediately or finish the current turn first;
+- **Models**: provider-grouped catalog with a checkbox per model (persisted as `modelRules`, overriding `modelPattern`);
+- **Session exemptions**: searchable list of live root sessions; hover a session row in the left sidebar for a shield button, or use the **Exempt this session** button in the composer strip to toggle the current conversation directly;
+- **Holidays**: show the dynamic sync state.
+
+## Subagents and waiting
+
+- Running subagents are allowed to finish; the parent is paused after the last child ends and resumed off-peak;
+- In `finish-turn` mode the current turn finishes; a queued next turn is stopped and recorded;
+- A finished turn is marked `completed`, so no spurious turn is started at off-peak.
+
 ## Data
 
 State and snapshots live in `$DSH_HOME/offpeak-guard/`:
 
-- `state.json`: paused tasks, off-peak plans, last phase;
-- `status.json`: read-only snapshot for the UI (mirrored to `~/.dsh/offpeak-guard/status.json`).
+- `state.json`: paused/waiting tasks, plans, session exemptions, exact model rules, peak strategy;
+- `status.json`: read-only snapshot for the UI (mirrored to `~/.dsh/offpeak-guard/status.json`);
+- `holidays.json`: cached dynamic holiday dates.
 
 Nothing is written into user workspaces.
 
@@ -102,8 +132,11 @@ Pause uses `sessionController.cancel`, which ends only the current turn and keep
 
 ## Boundaries
 
-- Built-in statutory holidays cover 2026 only; after the 2027 schedule is published, upgrade the plugin or append dates with `holidays` / `DSH_OFFPEAK_HOLIDAYS`, otherwise holidays are treated as ordinary weekdays.
+- Dynamic holidays come from a third-party public API (default timor.tech; only the year is sent). Offline failures fall back to the `holidays.json` cache and the built-in 2026 list; set `holidaySource: builtin` for fully offline operation.
+- Built-in statutory holidays cover 2026 only; the dynamic sync fills later years once published, or append dates with `holidays`.
 - Named presets have fixed windows; use `preset: custom` for other providers or self-hosted pricing.
 - Only root sessions with a working directory are handled; subagent sessions are skipped so parents do not hang.
+- Subagent results are consumed by the parent after it resumes; the guard stops the parent at child completion but cannot intercept messages already written into the parent history.
+- A session exemption affects future pauses/resumes only; use `resume_now` to resume an already paused session.
 - A plugin restart does not cancel tasks that are already running (so installing the plugin cannot kill the current conversation); the next peak or new task follows the rules again.
 - Manual `resume_now` grants those sessions a 10-minute grace period so they are not paused again immediately.

package/README.md

@@ -7,14 +7,17 @@
 
 在 DeepSeek Harness 里按 **DeepSeek 峰谷计价** 安排工作：
 
-- **时间识别**：按 DeepSeek 官方规则，北京时间周一至周五（不含中国法定节假日）`09:00–12:00`、`14:00–18:00` 为峰值原价；其余时间（含周末、法定节假日全天）为谷价，按 5 折计费。内置 2026 年法定节假日；后续年份可用 `holidays` 追加。
-- **模型识别**：只有使用峰谷计价模型（默认模型名含 `deepseek`，可在 `exemptModels` 里逐项豁免）的会话才会被暂停/恢复；用其它模型的会话不受影响。
+- **时间识别**：按 DeepSeek 官方规则，北京时间周一至周五（不含中国法定节假日）`09:00–12:00`、`14:00–18:00` 为峰值原价；其余时间（含周末、法定节假日全天）为谷价，按 5 折计费。节假日默认从公开 API 动态同步，失败时回退内置 2026 列表。
+- **模型识别**：按会话真实 `provider / model` 精确判断；默认名字含 `deepseek` 的模型受管理，可在设置面板逐模型开关，或用 `peakPricedModels` / `exemptModels` 精确控制。
+- **峰时策略**：可选「立即暂停」或「完成当前轮后暂停」；会话有子代理在跑时先放行子代理，子代理结束后再暂停父会话，谷价开始时恢复。
+- **会话豁免**：可让某个会话不参与插件的暂停/恢复（设置面板或 `offpeak_guard exempt/unexempt`），随时取消豁免。
 - **工作规划**：
   - 峰时开始 → 暂停正在运行的任务（保留待处理队列，不丢消息）；
   - 峰时新起的任务 → 立即停住，不花峰时 token；
   - 谷价开始 → 自动把被打断的任务交还会话继续执行；
   - 另提供 `offpeak_plan` 工具，把「12 点再跑」这类事排进下一个谷价窗口。
-- **界面**：输入框下方一条状态条，显示当前峰/谷、距下次切换的倒计时、当前模型，以及暂停/规划数量；左侧栏底部另有一枚常驻计时，临近切换时闪色提醒（峰价快开始闪红、谷价快开始闪绿）。
+- **界面**：输入框下方一条状态条，显示当前峰/谷、距下次切换的倒计时、当前模型，以及暂停/规划数量；左侧栏底部另有一枚常驻计时，临近切换时闪色提醒（峰价快开始闪红、谷价快开始闪绿）。**点击左栏计时打开设置面板**：切换峰时策略、逐模型管理、会话豁免、查看节假日同步状态。
+- **就地豁免**：把鼠标移到左侧会话行，行尾会出现盾牌按钮，点一下即可豁免/取消该会话；豁免中的会话行会显示盾牌标记。输入框状态条右侧也有「豁免本会话」按钮，直接在当前对话里切换。
 
 ![输入框下方的峰谷状态条](docs/peak-strip.png)
 
@@ -26,6 +29,10 @@
 
 ![左栏峰谷计时闪红](docs/sidebar-clock-blink.png)
 
+点击左栏计时打开设置面板：
+
+![峰谷守卫设置面板](docs/settings-panel.png)
+
 ## 工具
 
 | 工具 | 用途 |
@@ -42,12 +49,16 @@
 | --- | --- | --- |
 | `enabled` | `true` | 总开关 |
 | `preset` | `auto` | `auto` 按 provider 自动选：WorkBuddy/CodeBuddy → `workbuddy`，其余 → `deepseek-official`；也可固定为 `deepseek-official` / `workbuddy` / `custom` |
+| `pauseMode` | `pause-now` | `pause-now` 峰时立即暂停；`finish-turn` 当前轮跑完后再暂停 |
 | `timezone` | `Asia/Shanghai` | 计价时区（DeepSeek 计费按北京时间） |
 | `peakWeekdays` | `[1,2,3,4,5]` | 峰时适用的星期（0=周日）；仅 `custom` 预设使用 |
 | `peakWindows` | 09:00–12:00、14:00–18:00 | 峰时窗口；仅 `custom` 预设使用，官方调价时改这里 |
 | `discount` | `0.5` | 谷价折扣，仅用于显示「5 折」；仅 `custom` 预设使用 |
-| `holidays` | `[]` | 追加的法定节假日（`YYYY-MM-DD`），官方/WorkBuddy 预设会在内置 2026 列表上追加 |
-| `modelPattern` | `deepseek` | 模型名/供应商名包含它即视为峰谷计价模型 |
+| `holidays` | `[]` | 追加的法定节假日（`YYYY-MM-DD`），在动态/内置列表上追加 |
+| `holidaySource` | `auto` | `auto` 从公开节假日 API 动态同步；`builtin` 只用内置/配置列表 |
+| `holidayApi` | timor.tech | 动态节假日 API 前缀 |
+| `modelPattern` | `deepseek` | 未配置精确列表时，模型名/供应商名包含它即视为峰谷计价模型 |
+| `peakPricedModels` | `[]` | 精确的峰谷计价模型列表（`provider/model` 或 `model`）；非空时优先于 `modelPattern` |
 | `exemptModels` | `[]` | 逐项豁免的模型 id |
 | `pauseRunningOnPeak` | `true` | 峰时开始时暂停正在运行的任务 |
 | `deferNewTurnsOnPeak` | `true` | 峰时新起的任务立即停住 |
@@ -65,12 +76,16 @@
 | --- | --- | --- |
 | `DSH_OFFPEAK_ENABLED` | `0` / `1` | `enabled` |
 | `DSH_OFFPEAK_PRESET` | `custom` | `preset` |
+| `DSH_OFFPEAK_PAUSE_MODE` | `finish-turn` | `pauseMode` |
 | `DSH_OFFPEAK_TIMEZONE` | `Asia/Shanghai` | `timezone` |
 | `DSH_OFFPEAK_PEAK_WEEKDAYS` | `1,2,3,4,5` | `peakWeekdays` |
 | `DSH_OFFPEAK_PEAK_WINDOWS` | `09:00-12:00,14:00-18:00` | `peakWindows` |
 | `DSH_OFFPEAK_DISCOUNT` | `0.5` | `discount` |
 | `DSH_OFFPEAK_HOLIDAYS` | `2026-10-01,2026-10-02` | `holidays` |
+| `DSH_OFFPEAK_HOLIDAY_SOURCE` | `builtin` | `holidaySource` |
+| `DSH_OFFPEAK_HOLIDAY_API` | `https://.../year` | `holidayApi` |
 | `DSH_OFFPEAK_MODEL_PATTERN` | `deepseek` | `modelPattern` |
+| `DSH_OFFPEAK_PEAK_MODELS` | `deepseek-flash,vendor/model` | `peakPricedModels` |
 | `DSH_OFFPEAK_EXEMPT_MODELS` | `deepseek-v4-pro,deepseek-flash` | `exemptModels` |
 | `DSH_OFFPEAK_PAUSE_RUNNING` | `0` / `1` | `pauseRunningOnPeak` |
 | `DSH_OFFPEAK_DEFER_NEW` | `0` / `1` | `deferNewTurnsOnPeak` |
@@ -86,13 +101,31 @@
 - `workbuddy`：WorkBuddy 积分规则，峰时窗口与官方相同；按 provider 自动选择时用于标注来源。
 - `custom`：完全使用 `peakWeekdays` / `peakWindows` / `discount` / `holidays`，适合其他供应商或自建计价。
 
+## 设置面板
+
+点击左栏计时打开：
+
+- **峰时策略**：立即暂停 / 完成当前轮后暂停；
+- **模型管理**：按 provider 分组列出模型目录，勾选即精确纳入峰谷管理（写入 `state.json` 的 `modelRules`，优先于 `modelPattern`）；
+- **会话豁免**：勾选某个会话后，它不再被暂停/恢复；取消勾选立即恢复管理；
+- **节假日**：显示动态同步状态。
+
+面板里的修改立即生效并持久化。
+
+## 子代理与等待
+
+- 峰时开始时若会话有**正在运行的子代理**，先放行父会话与子代理；
+- 子代理结束后，父会话按当前策略暂停（`waiting-children`），谷价开始后自动恢复；
+- 「完成当前轮后暂停」模式下，当前轮允许跑完；如果随后又排入了下一轮，下一轮会在峰时被拦下并记录，谷价开始恢复；
+- 当前轮跑完且没有后续轮次时，记录标记为 `completed`，不会在谷价时无意义地再起一轮。
 
 ## 数据
 
 状态与快照都在 `$DSH_HOME/offpeak-guard/`：
 
-- `state.json`：暂停中的任务、错峰规划、上次时段；
-- `status.json`：给输入框状态条读的只读快照（同时镜像到 `~/.dsh/offpeak-guard/status.json`）。
+- `state.json`：暂停/等待中的任务、错峰规划、会话豁免、精确模型规则、峰时策略；
+- `status.json`：给输入框状态条/设置面板读的只读快照（同时镜像到 `~/.dsh/offpeak-guard/status.json`）；
+- `holidays.json`：动态同步的节假日缓存。
 
 不写用户工作区。
 
@@ -102,8 +135,11 @@
 
 ## 边界
 
-- 内置法定节假日目前覆盖 2026 年；2027 年安排公布后可升级插件，或用 `holidays` / `DSH_OFFPEAK_HOLIDAYS` 追加，否则节假日会被当作普通工作日。
+- 动态节假日来自第三方公开 API（默认 timor.tech，只发送年份）；离线或接口失败时回退 `holidays.json` 缓存与内置 2026 列表。可设 `holidaySource: builtin` 完全离线。
+- 内置法定节假日目前覆盖 2026 年；2027 年安排公布后动态同步会自动补，或用 `holidays` / `DSH_OFFPEAK_HOLIDAYS` 追加，否则节假日会被当作普通工作日。
 - 命名预设的窗口是固定的；需要其他供应商/自建计价时用 `preset: custom` 配 `peakWindows`。
 - 只处理有工作目录、非子代理的根会话，避免打断子代理让父会话卡住。
+- 子代理结果在父会话恢复后由模型继续消费；插件能在子代理结束时停住父会话，但无法在传输层拦截已经进入父会话历史的消息。
+- 「会话豁免」只影响后续暂停/恢复，不会自动把已经暂停的任务立即恢复；需要时用 `resume_now`。
 - 插件自身重启时不会主动打断正在跑的任务（避免刚安装就停掉当前对话）；之后进入峰时或新起任务仍按规则处理。
 - 手动「立即恢复」会给这些会话 10 分钟豁免，避免峰时刚恢复又被停回去。