dsh-team-limits 1.3.5 → 1.3.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.3.7
+
+- Rewrote the README for users: what the four numbers do, how to reach the page, and the two things
+  that surprise people (values survive uninstall; higher limits mean more concurrent sessions).
+  `README.en.md` is the English translation.
+- Moved the implementation notes, the settings-page structure and the security notes to
+  `docs/implementation.md` and `docs/implementation.en.md`.
+
+## 1.3.6
+
+- Declares `engines` (`node` and `dsh`). The package declared neither, so the installer could not
+  check it against the running harness.
+
 ## 1.3.5
 
 - Removed the leftover debugging path and the trace calls that appended to it on every load. The

package/README.en.md

@@ -0,0 +1,57 @@
+# dsh-team-limits
+
+**Adjust Agent Team's member count, task count, message size and teardown timeout from the plugin page.**
+
+> English | [中文](README.md)
+
+## When you need it
+
+- 16 team members by default, and that is not enough
+- Tasks start queueing (256 by default)
+- Long messages from subagents get truncated (64 KB by default)
+- You want the shipped values back without digging through config files
+
+## Install
+
+1. Open **Settings → Plugins → Market** and search for `dsh-team-limits`
+2. Install it
+3. **Quit DSH completely, then start it again**
+
+## Where to change it
+
+**Settings → Plugins → Installed → Team limits** — four number fields:
+
+| Setting | Shipped default | This page starts at |
+| --- | --- | --- |
+| Members | 16 | **32** |
+| Tasks | 256 | **512** |
+| Message size (bytes) | 65536 | **131072** |
+| Teardown timeout (ms) | 5000 | 5000 |
+
+Edits are saved as you type — there is no Save button. As soon as a field differs from the shipped value, **Restore default** appears next to it.
+
+## Good to know
+
+- **The values live in the profile's patch layer.** Uninstalling the bundle does not roll them back; use **Restore default** first if you want the stock numbers.
+- **Raising limits is not free.** More members means more concurrent model sessions, each costing tokens and a session directory. Raise only what you need.
+- A terminal-only profile does not render the page, but the limits still apply.
+
+## FAQ
+
+**Installed it and there is no page?** DSH was not fully quit. Quit from the tray and start it again.
+
+**Changed a number and nothing happened?** Edits are written immediately and applied through the normal load path; if the plugin is an old version, reinstall it.
+
+**How do I get the stock numbers back?** Press **Restore default** on each field.
+
+## Uninstall
+
+Disable or remove it in the plugin panel. To restore the numbers as well, use **Restore default** first.
+
+## Technical notes
+
+How it works, where the four fields come from and how the values are written: [docs/implementation.en.md](https://github.com/SpaceRelay/dsh-subagent-control/blob/main/team-limits/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,77 +1,57 @@
 # dsh-team-limits
 
-**English** · [简体中文](#简体中文)
+**在插件页里调整 Agent Team 的人数、任务数、单条消息大小与清理超时。**
 
-Optional companion bundle for [dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control): it adds editable **Team limits** fields to the plugin's own page (Settings → Plugins → Installed → Team limits), so the Agent Team limits are number fields you can change and reset — instead of values frozen in a patch file.
+> [English](README.en.md) | 中文
 
-## English
+## 什么时候用得上
 
-### What it does
+- 默认最多 16 个队友，队伍不够用
+- 任务一多就排队（默认 256 条）
+- 子代理回传的长消息被截断（默认 64 KB）
+- 想回出厂值，但不想去翻配置文件
 
-DeepSeek Harness ships the Agent Team plugin with these limits:
+## 安装
 
-| Setting | Shipped default | This page starts at |
-| --- | --- | --- |
-| `maxMembers` | 16 | **32** |
-| `maxTasks` | 256 | **512** |
-| `maxMessageBytes` | 65536 | **131072** |
-| `disposalTimeoutMs` | 5000 | 5000 |
-
-The page has four number fields. Edits are written onto the shipped `agent-team` row through the host's config editor as you type (debounced, no Save button), and each field offers **Restore default** once it differs from the shipped value. The config editor persists the values in the profile patch layer and applies them on the normal Loader path. The bundle's own patch therefore holds no numbers, so a DSH upgrade that changes the shipped defaults does not silently resurrect old values.
-
-### Before you install
-
-- **Restart DSH after installing**, then open Settings → Plugins → Installed → Team limits; the fields sit right below the bundle description.
-- **Values live in the profile patch layer.** Uninstalling the bundle does not roll them back; set the fields back to the shipped defaults (or remove the `agent-team` override in the profile patch) if you want the stock numbers again.
-- **Raising limits is not free.** More members means more concurrent model sessions; each one costs tokens and a session directory. Raise only what you need.
-- The client page needs the harness browser bundle; nothing is rendered in terminal-only profiles, but the limits still apply.
-
-### Install
+1. 打开 设置 → 插件 → 市场，搜索 `dsh-team-limits`
+2. 点安装
+3. **完全退出 DSH，再重新打开**
 
-Through the plugin panel / market, or by asking the agent:
+## 在哪里改
 
-```
-plugin_manager install_bundle target "dsh-team-limits@1.3.2"
-```
+设置 → 插件 → 已安装 → **团队限额**，四个数字框：
 
-### License
-
-MIT — see [LICENSE](./LICENSE). Issues: <https://github.com/SpaceRelay/dsh-subagent-control/issues>
-
----
+| 设置项 | 出厂默认 | 本页初始值 |
+| --- | --- | --- |
+| 最多成员数 | 16 | **32** |
+| 最多任务数 | 256 | **512** |
+| 单条消息上限（字节） | 65536 | **131072** |
+| 清理超时（毫秒） | 5000 | 5000 |
 
-## 简体中文
+改动边输边存，没有保存按钮。某个字段一旦偏离出厂值，旁边就会出现「恢复默认」。
 
-这是 [dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control) 的可选同伴包：在**插件自己的页面**上（设置 → 插件 → 已安装 → 团队限额）加一组可编辑的「团队限额」字段，把 Agent Team 的上限变成能直接填、能恢复默认的数字输入框，而不是写死在补丁文件里的值。
+## 注意
 
-### 它做什么
+- **数值存在 profile 的补丁层里。** 卸载本插件不会把它们变回出厂值，要恢复请先在页面上点「恢复默认」。
+- **提高上限不是免费的。** 队友更多意味着更多并发的模型会话，每个都消耗 token 和一个会话目录，按需要调。
+- 纯终端的 profile 不显示这个页面，但限额照样生效。
 
-Agent Team 出厂限制如下：
+## 常见问题
 
-| 配置 | 出厂默认 | 本页面初始值 |
-| --- | --- | --- |
-| `maxMembers` | 16 | **32** |
-| `maxTasks` | 256 | **512** |
-| `maxMessageBytes` | 65536 | **131072** |
-| `disposalTimeoutMs` | 5000 | 5000 |
+**装完没看到页面？** 没有完全退出 DSH。从托盘退出再打开。
 
-页面有四个数字输入框。改动边输边写（防抖，没有保存按钮），每个字段一旦偏离出厂值就会出现**恢复默认**。宿主侧的配置编辑器会把这些值写到自带的 `agent-team` 行上，持久化进 profile 的补丁层，并按正常加载流程生效。因此本包自己的补丁里不再存数值：DSH 升级改变了出厂默认，也不会悄悄把旧数字带回来。
+**改了没反应？** 页面上的改动会即时写入，按正常加载流程生效；如果插件是旧版本，重装一次。
 
-### 安装前要知道
+**想全部回到出厂值？** 每个字段点一次「恢复默认」。
 
-- **安装后重启 DSH**，然后打开 设置 → 插件 → 已安装 → 团队限额；输入框就在插件描述下面。
-- **数值存在 profile 的补丁层里。** 卸载本包不会把它们撤回；要恢复出厂值，请在页面上点「恢复默认」，或删除 profile 补丁里 `agent-team` 那条覆盖。
-- **提高上限不是免费的。** 队友更多意味着更多并发的模型会话，每个都消耗 token 与一个会话目录；按实际需要调。
-- 这个页面依赖 Harness 的浏览器端；纯终端 profile 不渲染页面，但限额照样生效。
+## 卸载
 
-### 安装
+在插件面板里停用或卸载。想把数字也恢复，请先在页面上点「恢复默认」。
 
-在插件面板 / 市场中安装，或者让智能体执行：
+## 技术细节
 
-```
-plugin_manager install_bundle target "dsh-team-limits@1.3.2"
-```
+实现方式、四个字段的来源与写入路径：[docs/implementation.md](https://github.com/SpaceRelay/dsh-subagent-control/blob/main/team-limits/docs/implementation.md)
 
-### 许可
+## 许可
 
-MIT，见 [LICENSE](./LICENSE)。问题反馈：<https://github.com/SpaceRelay/dsh-subagent-control/issues>
+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,42 @@
+# dsh-team-limits — implementation notes
+
+For maintainers. User-facing docs live in [../README.en.md](../README.en.md).
+
+## What it changes
+
+The bundle attaches to the shipped `agent-team` row and turns four limit fields into editable values. Shipped defaults:
+
+| Field | Shipped default | This bundle |
+| --- | --- | --- |
+| `maxMembers` | 16 | 32 |
+| `maxTasks` | 256 | 512 |
+| `maxMessageBytes` | 65536 | 131072 |
+| `disposalTimeoutMs` | 5000 | 5000 |
+
+## Structure
+
+- `index.js` — the host half. Declares a `Config` (all four fields `.volatile()`) and, in `apply`, pushes the current values onto the `agent-team` row through `ctx.configEditor`: `configuration()` finds the row, `edit(entry, current => ({ ...current, ...values }))` writes it. `edit()` runs inside `hmr.runExclusive(...)`, and a plugin's `apply` already runs inside an HMR transaction, so calling it directly throws `HMR transactions cannot be nested`; the push is therefore wrapped in `ctx.get('hmr').executing.exit(...)`.
+- `client.js` — the browser half, hand-written with no build step, registered on the `plugins.bundle.config` slot with key `dsh-team-limits`. The page reads and writes values through `ctx.configForms`, and each field carries an "overridden" marker plus "restore default".
+- `cordis.patch.yml` — inserts one `team-limits` row (a placeholder component so the package has a mountable entry and a listed component) and **holds no numbers**.
+
+## Why the patch has no numbers
+
+Before 1.2.0 the numbers were written straight into the patch as an `agent-team` override. Two problems: a DSH upgrade that changed the shipped defaults would silently resurrect old numbers, and users could not change anything from the UI. Now the values live only in the profile's patch layer (written by `configEditor`), and this package's own patch stays empty.
+
+## How a change takes effect
+
+1. The user edits a field → the client writes it back to `Config` → `apply` pushes it with `configEditor.edit()` into the profile patch layer
+2. The Loader's normal reconciliation re-applies the `agent-team` row
+3. All four fields are volatile: a change does not remount the plugin, and the plugin polls every 1.5 s to notice it and push again
+
+## Uninstall behaviour
+
+Uninstalling does not roll the values back — they belong to the profile's patch layer, not to this bundle. To restore the shipped values, press **Restore default**, or delete the `config` under the `agent-team` row in the profile patch.
+
+## Tests
+
+```powershell
+node test/smoke.mjs
+```
+
+Coverage: registry shape, the four defaults, the parameters of the push, and degradation when `configEditor` is absent.

package/docs/implementation.md

@@ -0,0 +1,42 @@
+# dsh-team-limits 实现说明
+
+面向维护者。用户向说明见 [../README.md](../README.md)。
+
+## 它改的是什么
+
+本包把自己挂到宿主自带的 `agent-team` 行上，把四个限额字段变成可编辑项。宿主出厂值：
+
+| 字段 | 出厂默认 | 本包默认 |
+| --- | --- | --- |
+| `maxMembers` | 16 | 32 |
+| `maxTasks` | 256 | 512 |
+| `maxMessageBytes` | 65536 | 131072 |
+| `disposalTimeoutMs` | 5000 | 5000 |
+
+## 结构
+
+- `index.js`：宿主半边。声明一个 `Config`（四个字段各自 `.volatile()`），并在 `apply` 里把当前值推到 `agent-team` 行。写入走 `ctx.configEditor`：先 `configuration()` 找到 `agent-team` 行，再 `edit(entry, current => ({...current, ...values}))`。`edit()` 内部是 `hmr.runExclusive(...)`，而插件 `apply` 本身跑在 HMR 事务里，直接用会报 `HMR transactions cannot be nested`，所以推送被包进 `ctx.get('hmr').executing.exit(...)`。
+- `client.js`：浏览器半边，手写无构建，注册在 `plugins.bundle.config` 槽、key 为 `dsh-team-limits`。页面用 `ctx.configForms` 读当前值并回写，字段带「已覆盖」标记与「恢复默认」。
+- `cordis.patch.yml`：插入一行 `team-limits`（占位组件，让包有可挂载的入口与可列出的组件），**不含任何数字**。
+
+## 为什么补丁里不写数字
+
+1.2.0 之前，数值是直接写在补丁里覆盖 `agent-team` 的。那样有两个问题：DSH 升级改了出厂默认，旧数字会悄悄复活；用户也没法在界面上改。现在数值只存在 profile 的补丁层（由 `configEditor` 写入），本包的补丁保持空。
+
+## 生效路径
+
+1. 用户改字段 → 客户端把值写回 `Config` → 插件 `apply` 用 `configEditor.edit()` 写进 profile 补丁层
+2. Loader 走正常协调流程把 `agent-team` 行重新应用
+3. 四个字段是 volatile 的：改动不重挂插件，插件用 1.5 秒轮询感知变化再推一次
+
+## 卸载行为
+
+卸载本包不会回滚已写入的数值：它们属于 profile 的补丁层，不属于本包。要恢复出厂值，在页面上点「恢复默认」，或手动删除 profile 补丁里 `agent-team` 的那条 `config`。
+
+## 测试
+
+```powershell
+node test/smoke.mjs
+```
+
+覆盖：注册形状、四个字段的默认值、推送参数、以及 `configEditor` 缺失时的降级。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-team-limits",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "Optional companion bundle for the DeepSeek Harness Agent Team limits: members, tasks, message bytes and teardown timeout.",
   "license": "MIT",
   "author": {
@@ -33,6 +33,8 @@
     "locale/*.json",
     "icon.svg",
     "README.md",
+    "README.en.md",
+    "docs",
     "LICENSE",
     "CHANGELOG.md"
   ],
@@ -44,6 +46,10 @@
     "team",
     "limits"
   ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.1-rc.1 <0.3.0-0"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"