dsh-subagent-control 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +78 -34
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.1
4
+
5
+ - Documentation: bilingual README (English + 简体中文) with usage examples, the
6
+ security model, and the name-collision note.
7
+ - Release: publishing now runs on GitHub Actions with npm trusted publishing
8
+ (OIDC) and provenance. No npm token is stored in the repository.
9
+ - No runtime change: the three tools and their JSON Schemas are identical to
10
+ 1.0.0.
11
+
3
12
  ## 1.0.0
4
13
 
5
14
  First release.
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # dsh-subagent-control
2
2
 
3
+ **English** · [简体中文](#简体中文)
4
+
3
5
  Three tools that let any DSH agent — **including a team member** — list, steer and stop the subagents it started.
4
6
 
5
7
  `list_subagents` · `send_subagent_message` · `interrupt_subagent`
@@ -10,112 +12,154 @@ Three tools that let any DSH agent — **including a team member** — list, ste
10
12
 
11
13
  ### The problem
12
14
 
13
- The Harness ships `list_agents`, `send_message` and `interrupt_agent`. When the Agent Team bundle is active it registers tools with **those same three names** in every team member's exact Agent scope, and the more specific registration wins. Inside a teammate scope the team versions take over: they resolve `target` against the team roster only, and interrupting is a Lead-only operation.
15
+ The Harness ships `list_agents`, `send_message` and `interrupt_agent`. When the Agent Team bundle is active, it registers tools with **those same three names** in every team member's exact Agent scope, and the more specific registration wins. Inside a teammate scope the team versions take over: they resolve `target` against the team roster only, and interrupting is a Lead-only operation.
14
16
 
15
- The result: a teammate can start a subagent with `subagent`, but cannot list it, follow up with it, or stop it — even though `ctx.subagents` (the subagent service) has supported all three for any live agent all along, and the authority rules already allow an ancestor to manage its own descendants.
17
+ The result: a teammate can start a subagent with `subagent`, but cannot list it, follow up with it, or stop it — even though the subagent service (`ctx.subagents`) has supported all three for any live agent all along, and its authority rules already allow an ancestor to manage its own descendants.
16
18
 
17
- This bundle does not fight over the taken names. It registers three **new** names, globally, so the Lead and every teammate get them at once. Authority is still enforced by the service: a caller can message its own direct children and interrupt its own descendants.
19
+ This bundle does not fight over the taken names. It registers three **new** names, globally, so the Lead and every teammate get them at once.
18
20
 
19
21
  ### Tools
20
22
 
21
- | Tool | Parameters | Calls |
23
+ | Tool | Parameters | Underlying call |
22
24
  | --- | --- | --- |
23
25
  | `list_subagents` | `scope?`: `"children"` \| `"descendants"` (default `children`) | `ctx.subagents.listChildren()` / `listDescendants()` |
24
26
  | `send_subagent_message` | `subagent_id`, `message` (both required) | `ctx.subagents.sendMessage()` |
25
27
  | `interrupt_subagent` | `subagent_id` (required) | `ctx.subagents.interrupt()` with ancestor authority |
26
28
 
27
- `list_subagents` returns one line per subagent: `id status "label" depth=`. `status` is `running` or `inactive` — `inactive` means no turn is executing, not that the subagent is gone.
29
+ ### Usage
30
+
31
+ ```
32
+ list_subagents
33
+ → 3b0f9c1e running "review the patch" depth=1
34
+
35
+ list_subagents scope=descendants
36
+ → 3b0f9c1e running "review the patch" depth=1
37
+ 7d2a44b0 inactive "check the tests" depth=2
38
+
39
+ send_subagent_message subagent_id=3b0f9c1e message="also look at locale/zh.json"
40
+ → messageId=...
41
+
42
+ interrupt_subagent subagent_id=3b0f9c1e
43
+ → accepted=true
44
+ ```
45
+
46
+ Each listing line is `id status "label" depth=`. `status` is `running` or `inactive` — **inactive means no turn is executing, not that the subagent is gone**. Use `send_subagent_message` to wake it.
28
47
 
29
48
  ### Behaviour and limits
30
49
 
31
- - One-shot subagents are not listed. They cannot accept a follow-up message, so showing them would only invite a call that is guaranteed to fail.
32
- - A child whose record cannot be read comes back as a diagnostic entry (`corrupt` / `unsupported` / `unavailable`) instead of turning the whole listing into an error.
33
- - `send_subagent_message` reaches a direct child only. This is the service's rule, not an extra restriction here.
34
- - `interrupt_subagent` reaches the caller's descendants, so a team Lead can also stop a grandchild.
35
- - Every failure is a normal error result that names the cause: no calling agent, unknown id, or an id that is not yours.
50
+ - **One-shot subagents are hidden.** They cannot accept a follow-up message, so listing them would only invite a call that is guaranteed to fail.
51
+ - **A broken record is reported, not thrown.** A child whose state cannot be read comes back as a diagnostic entry (`corrupt` / `unsupported` / `unavailable`) instead of turning the whole listing into an error.
52
+ - **`send_subagent_message` reaches direct children only.** That is the service's own rule; the plugin does not widen it.
53
+ - **`interrupt_subagent` reaches descendants**, so a team Lead can also stop a grandchild.
54
+ - **Every failure names its cause**: no calling agent, unknown id, or an id that is not yours.
55
+ - **No config, no storage.** The bundle writes nothing and reads nothing outside the three services.
36
56
 
37
57
  ### Install
38
58
 
39
- Through the plugin manager / market, or by asking the agent:
59
+ Through the plugin panel / market, or by asking the agent:
40
60
 
41
61
  ```
42
62
  plugin_manager install_bundle target "dsh-subagent-control@1.0.0"
43
63
  ```
44
64
 
45
- From a checkout, pass the directory path instead of the npm spec. The bundle applies immediately — no restart. Verify the three tool names appear and the plugin row is enabled.
65
+ From a checkout, pass the **directory path** instead of the npm spec. The bundle applies immediately — no restart needed. Afterwards the three tool names are visible and the plugin row is enabled.
46
66
 
47
67
  ### Compatibility
48
68
 
49
69
  - DSH with the `tools`, `subagents` and `agents` services (0.2.x and later).
50
70
  - Node `^22.19.0 || >=24.0.0`.
51
- - No runtime dependencies, no peer dependencies: the module imports nothing. A plain tool table with explicit JSON Schemas installs the same way from npm or from a linked checkout.
71
+ - **Zero dependencies** — no runtime dependency, no peer dependency, not a single `import`. The tools are plain tool-table objects with explicit JSON Schemas, so they install and behave identically from npm or from a linked checkout.
72
+
73
+ ### Name collisions
52
74
 
53
- ### Known name conflict
75
+ `dsh-subagent-library` also registers a global `list_subagents` tool. Two global registrations of one name cannot both win: install one of them, or remember that the other may shadow this one.
54
76
 
55
- `dsh-subagent-library` also registers a global `list_subagents` tool. Two global registrations of one name cannot both win — install one of them, or remember that the other may shadow this one.
77
+ The three new names were chosen precisely because they do **not** collide with the built-in `list_agents` / `send_message` / `interrupt_agent`.
56
78
 
57
79
  ### Uninstall
58
80
 
59
- Remove or disable the bundle in the plugin panel. Nothing else is written: no config, no storage.
81
+ Remove or disable the bundle in the plugin panel. Nothing is left behind.
60
82
 
61
83
  ### License
62
84
 
63
- MIT — see [LICENSE](./LICENSE).
85
+ MIT — see [LICENSE](./LICENSE). Issues and source live at
86
+ [github.com/SpaceRelay/dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control).
64
87
 
65
88
  ---
66
89
 
67
- ## 中文
90
+ ## 简体中文
68
91
 
69
92
  ### 它解决什么问题
70
93
 
71
94
  Harness 自带 `list_agents`、`send_message`、`interrupt_agent`。开启 Agent Team 后，团队插件会把**同名的三个工具**注册进每个团队成员的精确作用域，而更具体的作用域优先。于是在成员作用域里生效的是团队版：`target` 只认队友名，打断只有组长能做。
72
95
 
73
- 结果是：团队成员能用 `subagent` 派出子代理，却列不出、追问不了、也打断不了它。而底层的 `ctx.subagents` 服务本来就支持这三件事，权限规则也允许祖先管理自己的后代。
96
+ 结果是：团队成员能用 `subagent` 派出子代理，却列不出、追问不了、也打断不了它。而底层的子代理服务（`ctx.subagents`）本来就支持这三件事，权限规则也允许祖先管理自己的后代。
74
97
 
75
- 本插件不去抢那三个被占用的名字，而是全局注册三个**新名字**，组员立刻可用。权限仍由服务裁决：调用者可以给自己直接派出的子代理发消息，也可以打断自己名下的所有后代。
98
+ 本插件不去抢那三个被占用的名字，而是全局注册三个**新名字**，组长和每个组员立刻都能用。
76
99
 
77
100
  ### 工具
78
101
 
79
- | 工具 | 参数 | 调用 |
102
+ | 工具 | 参数 | 底层调用 |
80
103
  | --- | --- | --- |
81
104
  | `list_subagents` | `scope?`：`"children"` 或 `"descendants"`，默认 `children` | `ctx.subagents.listChildren()` / `listDescendants()` |
82
- | `send_subagent_message` | `subagent_id`、`message`（必填） | `ctx.subagents.sendMessage()` |
105
+ | `send_subagent_message` | `subagent_id`、`message`（均必填） | `ctx.subagents.sendMessage()` |
83
106
  | `interrupt_subagent` | `subagent_id`（必填） | `ctx.subagents.interrupt()`（祖先权限） |
84
107
 
85
- `list_subagents` 每个子代理一行：`id status "label" depth=`。`status` 为 `running` 或 `inactive`；`inactive` 表示当前没有在跑，不代表子代理已经消失。
108
+ ### 用法
109
+
110
+ ```
111
+ list_subagents
112
+ → 3b0f9c1e running "review the patch" depth=1
113
+
114
+ list_subagents scope=descendants
115
+ → 3b0f9c1e running "review the patch" depth=1
116
+ 7d2a44b0 inactive "check the tests" depth=2
117
+
118
+ send_subagent_message subagent_id=3b0f9c1e message="顺手看一下 locale/zh.json"
119
+ → messageId=...
120
+
121
+ interrupt_subagent subagent_id=3b0f9c1e
122
+ → accepted=true
123
+ ```
124
+
125
+ 每行格式是 `id status "label" depth=`。`status` 为 `running` 或 `inactive`——**inactive 表示当前没有在跑，不代表子代理已经消失**；用 `send_subagent_message` 可以把它叫醒。
86
126
 
87
127
  ### 行为与边界
88
128
 
89
- - 一次性子代理不会被列出：它们无法接收后续消息，列出来只会诱导一次注定失败的调用。
90
- - 某个子代理记录读不出来时，会作为诊断条目（`corrupt` / `unsupported` / `unavailable`）返回，而不是让整个列表报错。
91
- - `send_subagent_message` 只能发给直接子代理，这是服务本身的规则，插件没有额外收紧。
92
- - `interrupt_subagent` 覆盖调用者的所有后代，所以组长也能打断孙代。
93
- - 任何失败都是普通的错误结果，并说明原因：没有调用者、id 不存在、或者不是你的子代理。
129
+ - **一次性子代理不会被列出。** 它们无法接收后续消息，列出来只会诱导一次注定失败的调用。
130
+ - **记录损坏时报告，而不是抛错。** 某个子代理状态读不出来，会作为诊断条目（`corrupt` / `unsupported` / `unavailable`）返回，而不是让整个列表失败。
131
+ - **`send_subagent_message` 只能发给直接子代理。** 这是服务本身的规则，插件没有放宽。
132
+ - **`interrupt_subagent` 覆盖所有后代**，所以组长也能打断孙代。
133
+ - **任何失败都说明原因**：没有调用者、id 不存在、或者不是你的子代理。
134
+ - **不写配置、不落存储。** 除了这三个服务，插件不读写任何东西。
94
135
 
95
136
  ### 安装
96
137
 
97
- 在插件面板/市场中安装，或者让智能体执行：
138
+ 在插件面板 / 市场中安装，或者让智能体执行：
98
139
 
99
140
  ```
100
141
  plugin_manager install_bundle target "dsh-subagent-control@1.0.0"
101
142
  ```
102
143
 
103
- 从本地目录安装时，把 npm 规格换成目录路径。安装即时生效，无需重启；装完确认三个工具名可见、插件行为已启用。
144
+ 从本地目录安装时，把 npm 规格换成**目录路径**。安装即时生效，无需重启；装完后三个工具名可见、插件行为已启用。
104
145
 
105
146
  ### 兼容性
106
147
 
107
148
  - 具备 `tools`、`subagents`、`agents` 三个服务的 DSH（0.2.x 及以上）。
108
149
  - Node `^22.19.0 || >=24.0.0`。
109
- - 无运行时依赖、无 peer 依赖：模块不 import 任何东西，工具是带显式 JSON Schema 的普通定义对象，npm 安装与软链安装行为一致。
150
+ - **零依赖**：没有运行时依赖、没有 peer 依赖，模块里一行 `import` 都没有。工具是带显式 JSON Schema 的普通定义对象，所以 npm 安装与软链安装行为完全一致。
110
151
 
111
- ### 已知撞名
152
+ ### 撞名
112
153
 
113
154
  `dsh-subagent-library` 也注册了全局的 `list_subagents`。同一个名字的两个全局注册不可能同时生效——二选一安装，或记住其中一个可能被另一个覆盖。
114
155
 
156
+ 这三个新名字是特意挑的，**不会**和内置的 `list_agents` / `send_message` / `interrupt_agent` 冲突。
157
+
115
158
  ### 卸载
116
159
 
117
- 在插件面板里移除或停用即可。插件不写任何配置和存储。
160
+ 在插件面板里移除或停用即可，不会留下任何残留。
118
161
 
119
162
  ### 许可
120
163
 
121
- MIT，见 [LICENSE](./LICENSE)。
164
+ MIT，见 [LICENSE](./LICENSE)。源码与问题反馈：
165
+ [github.com/SpaceRelay/dsh-subagent-control](https://github.com/SpaceRelay/dsh-subagent-control)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-subagent-control",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Three tools — list_subagents, send_subagent_message, interrupt_subagent — that let any agent, including a team member, list, steer and stop the subagents it started.",
5
5
  "license": "MIT",
6
6
  "author": {