dsh-input-traffic 0.2.10-beta.1 → 0.2.10-beta.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+### 变更：冻结按钮文案与 session-guard 的分工说明
+
+- **按钮文案**：`steer.freeze` →「冻结追加」（Freeze & append / 凍結して追加 / 동결 후 추가），
+  `steer.resume` →「恢复追加」（Resume & append / 再開して追加 / 재개 후 추가）——与 session-guard 新增的
+  「暂停会话 / 继续会话」按钮并列，避免两个「恢复」混淆。只改文案，行为不变。
+- **职责边界**（README 新增小节）：本插件只负责「排」——决定用户输入进 `next-step` 还是 `next-turn`、
+  什么档位、何时被消费（`updateQueue(steer|remove|edit)` / `send` / `cancel`）；session-guard 只负责「停」——
+  `agent/pre-step` step 门、回合级暂停、请求级 hold。`next-step` 的物理含义是「与工具返回同级的下一步
+  （同一 turn 内）」，`next-turn` 才是新回合。
+
 ### 新增：DSH 双版本兼容（0.1.1-rc.2 / 0.1.2-rc.1）
 
 - **单一产物，运行时自适应**：同一份 `lib/client.js` 在两个版本都能加载，无版本号字符串分支。

package/README.en.md

@@ -108,7 +108,18 @@ The freeze button hands off to a **sessionGuard bridge** (`src/client/session-gu
   - `src/client/freeze-store.ts` — session-scoped freeze state (`Map<sessionId, {frozen, pending}>`, shared by button ↔ dock);
   - `src/client/session-guard-bridge.ts` — session-guard RPC bridge (fail-open, silently skipped when session-guard is absent);
   - `src/client/index.ts` — slot registration + composer-block injection (`conversation.blocks.set`).
-- **Scope comparison**: this plugin's freeze button = **per-session** (locks that one session by id); session-guard's **auto peak gate = global** (pauses all running sessions on peak entry, resumes all on exit). They complement each other — the gate handles the global case, the button the single-session case.
+- **Scope comparison**: this plugin's freeze button = **per-session** (locks that one session by id); session-guard's **peak auto gate / step gate = global or per-session pause** (holds on peak entry, releases off-peak). They complement each other — this plugin owns the queue and freezing, session-guard owns when progress may happen.
+
+**Division of labour (important): this plugin only "orders", session-guard only "stops"**
+
+| | This plugin (input-traffic) | session-guard |
+|---|---|---|
+| Job | **which queue** user input goes to, at what tier, and when it is consumed | **when progress may happen** (step / turn / request) |
+| DSH primitives | the `next-step` / `next-turn` pending queues + `updateQueue(steer\|remove\|edit)` / `send` / `cancel` | `agent/pre-step` (step gate), `agent.cancel({keepInbox:true})` + `goals.pause`, `agent/request` hold |
+| Freeze | detach `queued` + `steering` rows (**tiers preserved**) + composer block | `stopNextTurn`: **release the step gate first**, then turn-level pause (otherwise both wait on each other) |
+| Resume | re-submit by tier (red cancel+send / yellow steer / green send) | `resume`: continue from the pause point |
+
+The two queues mean: `next-step` = "the next step, **same level as a tool result**, still inside the same turn"; `next-turn` = "a new turn". That is why the yellow tier inserts into the current turn and the green tier waits for the turn to close.
 
 ## Queue management
 

package/README.md

@@ -123,7 +123,18 @@
   - `src/client/freeze-store.ts` — 会话级冻结状态 store（`Map<sessionId, {frozen, pending}>`，供按钮 ↔ dock 共享）；
   - `src/client/session-guard-bridge.ts` — session-guard RPC 透传（fail-open，未装则静默）；
   - `src/client/index.ts` — slot 注册 + composer block 注入（`conversation.blocks.set`）。
-- **作用域对比**：本插件冻结按钮 = **会话级**（按 sessionId 锁那一个会话）；session-guard **自动高峰门 = 全局**（入峰暂停全部、退峰自动恢复全部）。两者互补——自动门管全局、按钮管单会话。
+- **作用域对比**：本插件冻结按钮 = **会话级**（按 sessionId 锁那一个会话）；session-guard 的高峰自动门 / step 门 = **全局或会话级暂停**（入峰拉门、退峰自动放行）。
+
+**分工（重要）：本插件只负责「排」，session-guard 只负责「停」**
+
+| | 本插件（input-traffic） | session-guard |
+|---|---|---|
+| 职责 | 用户输入进**哪条队列、什么档位、何时被消费** | **何时允许推进**（step / 回合 / 请求） |
+| DSH 原语 | `next-step` / `next-turn` 两条待处理队列 + `updateQueue(steer\|remove\|edit)` / `send` / `cancel` | `agent/pre-step`（step 门）、`agent.cancel({keepInbox:true})` + `goals.pause`、`agent/request` hold |
+| 冻结 | 摘 `queued` + `steering` 行（**保留档位**）+ composer block | `stopNextTurn`：**先释放 step 门**再做回合级暂停（否则两边互等） |
+| 恢复 | 按档位重投（红 cancel+send / 黄 steer / 绿 send） | `resume`：从暂停点续跑 |
+
+两条队列的物理含义：`next-step` = 「与**工具返回同级**的下一个 step，仍在同一个 turn 内」；`next-turn` = 「新的回合」。所以黄档是「插到当前回合的下一步」，绿档是「等回合结束后再开一轮」——这正是三档能被 API 在同一次 turn 中途看到的原因。
 
 ## 队列管理
 

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-input-traffic",
-  "version": "0.2.10-beta.1",
+  "version": "0.2.10-beta.2",
   "main": "./lib/index.js",
   "description": "Busy-time input queue: three-tier planning, drag-to-reorder, interject/interrupt, batch clear, session freeze.",
   "contributes": {