@aspen138/dsh-btw 0.1.1 → 0.2.0

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.
package/index.js CHANGED
@@ -1,312 +1,584 @@
1
- /**
2
- * dsh-btw — Antigravity-style `/btw` side questions for DeepSeek Harness.
3
- *
4
- * A `/btw <question>` line asks one question "by the way" while a task is in
5
- * progress. It must not steer the main task, so this plugin does **not** write
6
- * anything the main conversation can see: the question starts one **forked
7
- * child agent** (seeded with the parent's completed turns, full tool set), the
8
- * child works in its own session, and its final answer comes back as the
9
- * command result. The child is disposed once it settles. The parent session
10
- * gains only the log-only `command/run` + `command/done` pair.
11
- *
12
- * Why a child agent instead of one bare model call: the side question is
13
- * allowed to *check things* — read a file, grep, run a command — using the
14
- * same tool pipeline, sandbox, and approval policy as the main conversation.
15
- * It therefore cannot answer from stale context alone, which is the whole
16
- * difference from a plain "ask about the transcript" feature.
17
- *
18
- * Design limits (documented in README.md):
19
- * - the child is a real agent: every tool, its own turn, its own tokens;
20
- * - results are delivered to this caller only (`delivery: 'caller'`), so no
21
- * completion notice is injected into the parent conversation;
22
- * - the child session persists (durable), the execution handle does not.
23
- *
24
- * @module dsh-btw
25
- */
26
-
27
- /** Command name without the slash. */
28
- const COMMAND_NAME = 'btw'
29
-
30
- /** Command identity reported to clients that select first-party row faces. */
31
- const DEFINITION_ID = '@local/dsh-btw'
32
-
33
- /** Defaults for every tunable value; the bundle patch may override each one. */
34
- const DEFAULTS = Object.freeze({
35
- maxQuestionChars: 8000,
36
- childProvider: 'fork',
37
- approvalPolicy: 'ask',
38
- sideAgentPreset: 'read-only',
39
- disposeChild: true,
40
- sideAgentTimeoutMs: 180000,
41
- answerMaxChars: 12000,
42
- })
43
-
44
- /**
45
- * Machine-readable trailer that names the child session behind one answer.
46
- *
47
- * The Client half uses it to open that child's conversation in the right
48
- * Sidebar, which is where DSH renders the side agent's tool calls and its native
49
- * approval prompts. It is stripped from every rendered answer.
50
- */
51
- const CHILD_MARKER = 'dsh-btw:child='
52
-
53
- /**
54
- * Wrap one raw question into the child's task text.
55
- *
56
- * The child inherits the parent conversation as its seed, so this prompt only
57
- * has to state the side-question contract: answer this one thing, do not take
58
- * over the main task, and prefer checking the workspace over guessing.
59
- *
60
- * @param question - trimmed user question.
61
- * @returns the task text handed to the child agent.
62
- */
63
- function frameQuestion(question) {
64
- return [
65
- '【侧问】这是一次不打断主线任务的侧问。',
66
- '',
67
- `问题:${question}`,
68
- '',
69
- '要求:',
70
- '1. 只回答这一个问题。不要继续、改写或推进主线任务;不要修改与回答问题无关的文件。',
71
- '2. 需要事实依据就去查:读文件、搜索、跑只读命令都可以;不要凭印象猜。',
72
- '3. 如果确实需要写操作(改文件、执行有副作用的命令),先说明你要做什么;需要审批时等待审批。',
73
- '4. 答案要短,直接给结论和依据;不要复述上面已经说过的整段对话。',
74
- ].join('\n')
75
- }
76
-
77
- /**
78
- * Normalize the raw bundle config into the options this plugin understands.
79
- *
80
- * A plain Host bundle cannot import the Loader's schema package, so values are
81
- * read defensively instead of being validated by a `Config` export.
82
- *
83
- * @param raw - untrusted row config.
84
- * @returns normalized options.
85
- */
86
- function normalizeConfig(raw) {
87
- const input = raw !== null && typeof raw === 'object' ? raw : {}
88
- const number = (value, fallback, min, max) =>
89
- typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max ? value : fallback
90
- const text = (value, fallback) => (typeof value === 'string' && value !== '' ? value : fallback)
91
- return {
92
- maxQuestionChars: number(input.maxQuestionChars, DEFAULTS.maxQuestionChars, 1, 100000),
93
- childProvider: text(input.childProvider, DEFAULTS.childProvider),
94
- approvalPolicy: input.approvalPolicy === 'inherit' ? 'inherit' : DEFAULTS.approvalPolicy,
95
- sideAgentPreset: text(input.sideAgentPreset, DEFAULTS.sideAgentPreset),
96
- disposeChild: typeof input.disposeChild === 'boolean' ? input.disposeChild : DEFAULTS.disposeChild,
97
- sideAgentTimeoutMs: number(input.sideAgentTimeoutMs, DEFAULTS.sideAgentTimeoutMs, 5000, 3600000),
98
- answerMaxChars: number(input.answerMaxChars, DEFAULTS.answerMaxChars, 200, 200000),
99
- provider: typeof input.provider === 'string' ? input.provider : '',
100
- model: typeof input.model === 'string' ? input.model : '',
101
- }
102
- }
103
-
104
- /** Concatenate the text blocks of a child's final answer. */
105
- function answerText(output) {
106
- if (!Array.isArray(output)) return ''
107
- const parts = []
108
- for (const block of output) {
109
- if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
110
- parts.push(block.text)
111
- }
112
- }
113
- return parts.join('\n').trim()
114
- }
115
-
116
- /** Trim one answer to the configured ceiling without cutting a word in half. */
117
- function clip(text, maxChars) {
118
- if (text.length <= maxChars) return text
119
- return `${text.slice(0, maxChars)}\n\n…(答案过长,已截断到 ${maxChars} 字符)`
120
- }
121
-
122
- /** Human sentence for one failed child run. */
123
- function failureText(result) {
124
- const diagnostic = result !== null && typeof result === 'object' && typeof result.diagnostic === 'string' ? result.diagnostic : ''
125
- const stop = result !== null && typeof result === 'object' && typeof result.stopReason === 'string' ? result.stopReason : 'error'
126
- if (diagnostic !== '') return `侧问失败(${stop}):${diagnostic}`
127
- return `侧问失败(${stop}):子 agent 没有产出答案。`
128
- }
129
-
130
- /**
131
- * Run one side question as a disposable forked child agent.
132
- *
133
- * The child is seeded from the parent's completed turns, inherits the parent's
134
- * preset (therefore the same tool set), and reports only to this caller. When
135
- * the configured approval policy is `ask`, write tools pause for the same
136
- * approval flow the main conversation uses instead of running unattended.
137
- *
138
- * @param ctx - Host plugin context.
139
- * @param invocation - the settled command invocation.
140
- * @param question - trimmed question.
141
- * @param config - normalized options.
142
- * @returns `{ text, childId }` on success.
143
- */
144
- async function runSideAgent(ctx, invocation, question, config) {
145
- const agents = ctx.get('agents')
146
- const subagents = ctx.get('subagents')
147
- if (subagents === null || subagents === undefined || typeof subagents.startActivation !== 'function') {
148
- throw new Error('当前 profile 没有 subagent 服务,/btw 无法运行子 agent。')
149
- }
150
- const parent = agents !== null && agents !== undefined && typeof agents.get === 'function'
151
- ? agents.get(invocation.agent.id)
152
- : undefined
153
- if (parent === undefined) throw new Error('当前会话不是本进程的活会话,/btw 无法继承上下文。')
154
-
155
- const agentOptions = {}
156
- if (config.provider !== '' && config.model !== '') {
157
- agentOptions.provider = config.provider
158
- agentOptions.model = config.model
159
- }
160
-
161
- // One cancellation owning both the caller's signal and this plugin's ceiling:
162
- // a child whose approval never gets answered must not keep the command open
163
- // forever.
164
- const controller = new AbortController()
165
- const forwardAbort = () => controller.abort()
166
- const callerSignal = invocation.signal
167
- if (callerSignal !== undefined && callerSignal !== null) {
168
- if (callerSignal.aborted === true) controller.abort()
169
- else if (typeof callerSignal.addEventListener === 'function') callerSignal.addEventListener('abort', forwardAbort, { once: true })
170
- }
171
- const timer = setTimeout(() => controller.abort(), config.sideAgentTimeoutMs)
172
-
173
- let activation
174
- try {
175
- activation = await subagents.startActivation({
176
- provider: config.childProvider,
177
- label: `侧问:${question.slice(0, 48)}`,
178
- request: {
179
- prompt: [{ type: 'text', text: frameQuestion(question) }],
180
- parent,
181
- ...(Object.keys(agentOptions).length === 0 ? {} : { agentOptions }),
182
- },
183
- signal: controller.signal,
184
- delivery: 'caller',
185
- })
186
- } catch (error) {
187
- clearTimeout(timer)
188
- if (callerSignal !== undefined && callerSignal !== null && typeof callerSignal.removeEventListener === 'function') {
189
- callerSignal.removeEventListener('abort', forwardAbort)
190
- }
191
- throw error
192
- }
193
-
194
- try {
195
- // Apply the side agent's permission bundle before its first tool call can
196
- // settle. `read-only` / `workspace-write` carry approval: 'ask', which is
197
- // what turns a write into a permission request instead of a silent write.
198
- if (config.sideAgentPreset !== 'inherit') {
199
- const presets = ctx.get('permissionPresets')
200
- const sessions = ctx.get('sessions')
201
- const childSession = sessions !== null && sessions !== undefined && typeof sessions.get === 'function'
202
- ? sessions.get(activation.childId)
203
- : undefined
204
- if (presets !== null && presets !== undefined && typeof presets.set === 'function' && childSession !== undefined) {
205
- try {
206
- presets.set(childSession, config.sideAgentPreset)
207
- } catch {
208
- /* unknown preset or a child that already settled */
209
- }
210
- }
211
- }
212
-
213
- // Write tools ask, like the main conversation under an ask policy. The
214
- // child starts on activation, so this runs immediately after creation —
215
- // before its first tool call can settle.
216
- if (config.approvalPolicy === 'ask') {
217
- const approval = ctx.get('approval')
218
- const child = agents !== null && agents !== undefined && typeof agents.get === 'function'
219
- ? agents.get(activation.childId)
220
- : undefined
221
- if (approval !== null && approval !== undefined && typeof approval.setPolicy === 'function' && child !== undefined) {
222
- try {
223
- approval.setPolicy(child, 'ask')
224
- } catch {
225
- /* a child that already settled needs no policy */
226
- }
227
- }
228
- }
229
-
230
- const result = await activation.result
231
- if (result === null || typeof result !== 'object') throw new Error('子 agent 没有返回结果。')
232
- if (result.stopReason !== 'completed') throw new Error(failureText(result))
233
- const text = answerText(result.output)
234
- if (text === '') throw new Error('子 agent 没有产出正文。')
235
- return { text: clip(text, config.answerMaxChars), childId: String(activation.childId) }
236
- } finally {
237
- clearTimeout(timer)
238
- if (callerSignal !== undefined && callerSignal !== null && typeof callerSignal.removeEventListener === 'function') {
239
- callerSignal.removeEventListener('abort', forwardAbort)
240
- }
241
- if (config.disposeChild) {
242
- try {
243
- await activation.dispose()
244
- } catch {
245
- /* the answer already exists; a failed release must not hide it */
246
- }
247
- }
248
- }
249
- }
250
-
251
- /**
252
- * Register `/btw` for every composed human-command adapter.
253
- *
254
- * The handler settles the whole child run before returning, so the answer
255
- * arrives as the command result in the same lifecycle record that the Chat
256
- * layer already renders. Only one side question per parent session may run at
257
- * a time: a second one is refused rather than queued behind the first.
258
- *
259
- * @param ctx - Host plugin context.
260
- * @param rawConfig - raw bundle config from the Loader row.
261
- */
262
- export function apply(ctx, rawConfig) {
263
- const config = normalizeConfig(rawConfig)
264
- const inFlight = new Map()
265
-
266
- const handler = async (invocation) => {
267
- const question = typeof invocation.rawInput === 'string' ? invocation.rawInput.trim() : ''
268
- if (question === '') {
269
- return {
270
- kind: 'success',
271
- text: '用法:/btw <问题>\n侧问会起一个继承当前上下文的临时子 agent(可用工具、写操作需审批),答案不进主干上下文。',
272
- }
273
- }
274
- if (question.length > config.maxQuestionChars) {
275
- return { kind: 'error', text: `问题过长(${question.length} 字符,上限 ${config.maxQuestionChars})。` }
276
- }
277
- const sessionId = invocation.agent.id
278
- if (inFlight.has(sessionId)) {
279
- return { kind: 'error', text: '上一个侧问还在跑,等它结束再问。' }
280
- }
281
- inFlight.set(sessionId, invocation.commandId)
282
- try {
283
- const result = await runSideAgent(ctx, invocation, question, config)
284
- // The trailer names the child session so the Client can open that
285
- // conversation (tool calls and native approval prompts) in the Sidebar.
286
- return { kind: 'success', text: `${result.text}\n\n[[${CHILD_MARKER}${result.childId}]]` }
287
- } catch (error) {
288
- if (invocation.signal !== undefined && invocation.signal !== null && invocation.signal.aborted === true) {
289
- return { kind: 'error', text: '侧问已取消。' }
290
- }
291
- const message = error instanceof Error ? error.message : String(error)
292
- return { kind: 'error', text: message }
293
- } finally {
294
- inFlight.delete(sessionId)
295
- }
296
- }
297
-
298
- ctx.effect(function* registerCommand() {
299
- yield () => {
300
- inFlight.clear()
301
- }
302
- yield ctx.commands.register({
303
- definitionId: DEFINITION_ID,
304
- name: COMMAND_NAME,
305
- description: '侧问:起一个继承上下文、能用工具的临时子 agent,答案不进主干上下文',
306
- input: { hint: '<问题>' },
307
- handler,
308
- })
309
- }, 'dsh-btw command')
310
- }
311
-
312
- export const inject = ['commands']
1
+ /**
2
+ * dsh-btw — Antigravity-style `/btw` side questions for DeepSeek Harness.
3
+ *
4
+ * A `/btw <question>` line asks one question "by the way" while a task is in
5
+ * progress. It must not steer the main task, so this plugin does **not** write
6
+ * anything the main conversation can see: the question starts one **forked
7
+ * child agent** (seeded with the parent's completed turns, full tool set), the
8
+ * child works in its own session, and its final answer comes back as the
9
+ * command result. The child is disposed once it settles. The parent session
10
+ * gains only the log-only `command/run` + `command/done` pair.
11
+ *
12
+ * Why a child agent instead of one bare model call: the side question is
13
+ * allowed to *check things* — read a file, grep, run a command — using the
14
+ * same tool pipeline, sandbox, and approval policy as the main conversation.
15
+ * It therefore cannot answer from stale context alone, which is the whole
16
+ * difference from a plain "ask about the transcript" feature.
17
+ *
18
+ * Design limits (documented in README.md):
19
+ * - the child is a real agent: every tool, its own turn, its own tokens;
20
+ * - results are delivered to this caller only (`delivery: 'caller'`), so no
21
+ * completion notice is injected into the parent conversation;
22
+ * - the child session persists (durable), the execution handle does not.
23
+ *
24
+ * @module dsh-btw
25
+ */
26
+
27
+ /** Command name without the slash. */
28
+ const COMMAND_NAME = 'btw'
29
+
30
+ /** Command identity reported to clients that select first-party row faces. */
31
+ const DEFINITION_ID = '@local/dsh-btw'
32
+
33
+ /** Defaults for every tunable value; the bundle patch may override each one. */
34
+ const DEFAULTS = Object.freeze({
35
+ maxQuestionChars: 8000,
36
+ childProvider: 'fork',
37
+ approvalPolicy: 'ask',
38
+ sideAgentPreset: 'read-only',
39
+ disposeChild: true,
40
+ sideAgentTimeoutMs: 900000,
41
+ answerMaxChars: 12000,
42
+ })
43
+
44
+ /**
45
+ * Machine-readable trailer that names the child session behind one answer.
46
+ *
47
+ * The Client half uses it to open that child's conversation in the right
48
+ * Sidebar, which is where DSH renders the side agent's tool calls and its native
49
+ * approval prompts. It is stripped from every rendered answer.
50
+ */
51
+ const CHILD_MARKER = 'dsh-btw:child='
52
+
53
+ /**
54
+ * Frame one side question, optionally continuing an earlier thread.
55
+ *
56
+ * A follow-up is a *new* child agent told what the thread already established.
57
+ * Reusing the child session through `sendMessage` would be cheaper, but resuming
58
+ * a child publishes a settlement notice into the parent conversation — the one
59
+ * thing this feature must never do — and that notice is produced by the
60
+ * subagent manager, so no tool restriction can suppress it.
61
+ *
62
+ * @param question - trimmed question.
63
+ * @param turns - earlier question/answer pairs in this thread, oldest first.
64
+ * @returns the task text handed to the child agent.
65
+ */
66
+ function frameThread(question, turns) {
67
+ const history = []
68
+ for (const turn of turns) {
69
+ history.push(`问:${turn.q}`)
70
+ history.push(`答:${turn.a}`)
71
+ }
72
+ return [
73
+ '【侧问】这是一次不打断主线任务的侧问。',
74
+ ...(history.length === 0 ? [] : ['', '本侧问此前已经问过(仅供你理解上下文,不要重复回答):', ...history]),
75
+ '',
76
+ `问题:${question}`,
77
+ '',
78
+ '要求:',
79
+ '1. 只回答这一个问题。不要继续、改写或推进主线任务;不要修改与回答问题无关的文件。',
80
+ '2. 需要事实依据就去查:读文件、搜索、跑只读命令都可以;不要凭印象猜。',
81
+ '3. 不要调用 send_message,也不要给父会话发任何消息或状态通知——答案直接作为本轮的回复文本返回。',
82
+ '4. 答案要短,直接给结论和依据;不要复述上面已经说过的整段对话。',
83
+ ].join('\n')
84
+ }
85
+
86
+ /** In-memory side-question threads, keyed by the child id the client knows. */
87
+ const THREADS = new Map()
88
+
89
+ /** Record one settled turn and return the thread's turns, capped for the prompt. */
90
+ function rememberTurn(key, question, answer) {
91
+ const turns = THREADS.get(key) ?? []
92
+ turns.push({ q: question, a: answer })
93
+ while (turns.length > 8) turns.shift()
94
+ THREADS.set(key, turns)
95
+ return turns
96
+ }
97
+
98
+
99
+ /**
100
+ * Normalize the raw bundle config into the options this plugin understands.
101
+ *
102
+ * A plain Host bundle cannot import the Loader's schema package, so values are
103
+ * read defensively instead of being validated by a `Config` export.
104
+ *
105
+ * @param raw - untrusted row config.
106
+ * @returns normalized options.
107
+ */
108
+ function normalizeConfig(raw) {
109
+ const input = raw !== null && typeof raw === 'object' ? raw : {}
110
+ const number = (value, fallback, min, max) =>
111
+ typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max ? value : fallback
112
+ const text = (value, fallback) => (typeof value === 'string' && value !== '' ? value : fallback)
113
+ return {
114
+ maxQuestionChars: number(input.maxQuestionChars, DEFAULTS.maxQuestionChars, 1, 100000),
115
+ childProvider: text(input.childProvider, DEFAULTS.childProvider),
116
+ approvalPolicy: input.approvalPolicy === 'inherit' ? 'inherit' : DEFAULTS.approvalPolicy,
117
+ sideAgentPreset: text(input.sideAgentPreset, DEFAULTS.sideAgentPreset),
118
+ disposeChild: typeof input.disposeChild === 'boolean' ? input.disposeChild : DEFAULTS.disposeChild,
119
+ sideAgentTimeoutMs: number(input.sideAgentTimeoutMs, DEFAULTS.sideAgentTimeoutMs, 30000, 7200000),
120
+ answerMaxChars: number(input.answerMaxChars, DEFAULTS.answerMaxChars, 200, 200000),
121
+ provider: typeof input.provider === 'string' ? input.provider : '',
122
+ model: typeof input.model === 'string' ? input.model : '',
123
+ }
124
+ }
125
+
126
+ /** Concatenate the text blocks of a child's final answer. */
127
+ function answerText(output) {
128
+ if (!Array.isArray(output)) return ''
129
+ const parts = []
130
+ for (const block of output) {
131
+ if (block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string') {
132
+ parts.push(block.text)
133
+ }
134
+ }
135
+ return parts.join('\n').trim()
136
+ }
137
+
138
+ /** Trim one answer to the configured ceiling without cutting a word in half. */
139
+ function clip(text, maxChars) {
140
+ if (text.length <= maxChars) return text
141
+ return `${text.slice(0, maxChars)}\n\n…(答案过长,已截断到 ${maxChars} 字符)`
142
+ }
143
+
144
+ /** Human sentence for one failed child run. */
145
+ function failureText(result) {
146
+ const diagnostic = result !== null && typeof result === 'object' && typeof result.diagnostic === 'string' ? result.diagnostic : ''
147
+ const stop = result !== null && typeof result === 'object' && typeof result.stopReason === 'string' ? result.stopReason : 'error'
148
+ if (diagnostic !== '') return `侧问失败(${stop}):${diagnostic}`
149
+ return `侧问失败(${stop}):子 agent 没有产出答案。`
150
+ }
151
+
152
+ /**
153
+ * Run one side question as a disposable forked child agent.
154
+ *
155
+ * The child is seeded from the parent's completed turns, inherits the parent's
156
+ * preset (therefore the same tool set), and reports only to this caller. When
157
+ * the configured approval policy is `ask`, write tools pause for the same
158
+ * approval flow the main conversation uses instead of running unattended.
159
+ *
160
+ * @param ctx - Host plugin context.
161
+ * @param invocation - the settled command invocation.
162
+ * @param question - trimmed question.
163
+ * @param config - normalized options.
164
+ * @returns `{ text, childId }` on success.
165
+ */
166
+ async function runSideAgent(ctx, invocation, question, config, parentKey) {
167
+ const turns = parentKey === undefined ? [] : THREADS.get(parentKey) ?? []
168
+ const agents = ctx.get('agents')
169
+ const subagents = ctx.get('subagents')
170
+ if (subagents === null || subagents === undefined || typeof subagents.startActivation !== 'function') {
171
+ throw new Error('当前 profile 没有 subagent 服务,/btw 无法运行子 agent。')
172
+ }
173
+ const parent = agents !== null && agents !== undefined && typeof agents.get === 'function'
174
+ ? agents.get(invocation.agent.id)
175
+ : undefined
176
+ if (parent === undefined) throw new Error('当前会话不是本进程的活会话,/btw 无法继承上下文。')
177
+
178
+ const agentOptions = {}
179
+ if (config.provider !== '' && config.model !== '') {
180
+ agentOptions.provider = config.provider
181
+ agentOptions.model = config.model
182
+ }
183
+
184
+ // One cancellation owning both the caller's signal and this plugin's ceiling:
185
+ // a child whose approval never gets answered must not keep the command open
186
+ // forever.
187
+ const controller = new AbortController()
188
+ const forwardAbort = () => controller.abort()
189
+ const callerSignal = invocation.signal
190
+ if (callerSignal !== undefined && callerSignal !== null) {
191
+ if (callerSignal.aborted === true) controller.abort()
192
+ else if (typeof callerSignal.addEventListener === 'function') callerSignal.addEventListener('abort', forwardAbort, { once: true })
193
+ }
194
+ const timer = setTimeout(() => controller.abort(), config.sideAgentTimeoutMs)
195
+
196
+ let activation
197
+ try {
198
+ activation = await subagents.startActivation({
199
+ provider: config.childProvider,
200
+ label: `侧问:${question.slice(0, 48)}`,
201
+ request: {
202
+ prompt: [{ type: 'text', text: frameThread(question, turns) }],
203
+ parent,
204
+ ...(Object.keys(agentOptions).length === 0 ? {} : { agentOptions }),
205
+ },
206
+ signal: controller.signal,
207
+ delivery: 'caller',
208
+ })
209
+ } catch (error) {
210
+ clearTimeout(timer)
211
+ if (callerSignal !== undefined && callerSignal !== null && typeof callerSignal.removeEventListener === 'function') {
212
+ callerSignal.removeEventListener('abort', forwardAbort)
213
+ }
214
+ throw error
215
+ }
216
+
217
+ /**
218
+ * The child inherits the parent's tool set, `send_message` included, and the
219
+ * inherited fork guidance tells it to report back with that tool. For a side
220
+ * question that would inject a status row into the main conversation — the
221
+ * one thing this feature exists to avoid — so the tool is removed from this
222
+ * child's scope before its first step.
223
+ */
224
+ restrictReportingTools(ctx, activation)
225
+
226
+ try {
227
+ // Apply the side agent's permission bundle before its first tool call can
228
+ // settle. `read-only` / `workspace-write` carry approval: 'ask', which is
229
+ // what turns a write into a permission request instead of a silent write.
230
+ if (config.sideAgentPreset !== 'inherit') {
231
+ const presets = ctx.get('permissionPresets')
232
+ const sessions = ctx.get('sessions')
233
+ const childSession = sessions !== null && sessions !== undefined && typeof sessions.get === 'function'
234
+ ? sessions.get(activation.childId)
235
+ : undefined
236
+ if (presets !== null && presets !== undefined && typeof presets.set === 'function' && childSession !== undefined) {
237
+ try {
238
+ presets.set(childSession, config.sideAgentPreset)
239
+ } catch {
240
+ /* unknown preset or a child that already settled */
241
+ }
242
+ }
243
+ }
244
+
245
+ // Write tools ask, like the main conversation under an ask policy. The
246
+ // child starts on activation, so this runs immediately after creation —
247
+ // before its first tool call can settle.
248
+ if (config.approvalPolicy === 'ask') {
249
+ const approval = ctx.get('approval')
250
+ const child = agents !== null && agents !== undefined && typeof agents.get === 'function'
251
+ ? agents.get(activation.childId)
252
+ : undefined
253
+ if (approval !== null && approval !== undefined && typeof approval.setPolicy === 'function' && child !== undefined) {
254
+ try {
255
+ approval.setPolicy(child, 'ask')
256
+ } catch {
257
+ /* a child that already settled needs no policy */
258
+ }
259
+ }
260
+ }
261
+
262
+ const result = await activation.result
263
+ if (result === null || typeof result !== 'object') throw new Error('子 agent 没有返回结果。')
264
+ if (result.stopReason !== 'completed') throw new Error(failureText(result))
265
+ const text = answerText(result.output)
266
+ if (text === '') throw new Error('子 agent 没有产出正文。')
267
+ const childId = String(activation.childId)
268
+ // Keep the thread so a follow-up can carry it, under the id the client knows.
269
+ if (parentKey !== undefined) rememberTurn(parentKey, question, text)
270
+ return { text: clip(text, config.answerMaxChars), childId }
271
+ } finally {
272
+ clearTimeout(timer)
273
+ if (callerSignal !== undefined && callerSignal !== null && typeof callerSignal.removeEventListener === 'function') {
274
+ callerSignal.removeEventListener('abort', forwardAbort)
275
+ }
276
+ if (config.disposeChild) {
277
+ try {
278
+ await activation.dispose()
279
+ } catch {
280
+ /* the answer already exists; a failed release must not hide it */
281
+ }
282
+ }
283
+ }
284
+ }
285
+
286
+ /**
287
+ * Remove the reporting tools from one side agent's scope.
288
+ *
289
+ * `ctx.tools.restrict()` is the weakest tool mechanism the Harness offers: it can
290
+ * only remove tools, it is scoped to one agent's context, and it keeps schema
291
+ * presentation, lookup, and execution aligned. Removing `send_message` (and the
292
+ * team tool that would page another agent) is what keeps a side answer from
293
+ * arriving in the main conversation as a notice.
294
+ *
295
+ * @param ctx - Host plugin context.
296
+ * @param activation - the freshly started side activation.
297
+ */
298
+ function restrictReportingTools(ctx, activation) {
299
+ const agents = ctx.get('agents')
300
+ const child = agents !== null && agents !== undefined && typeof agents.get === 'function'
301
+ ? agents.get(activation.childId)
302
+ : undefined
303
+ if (child === undefined || child === null || typeof child !== 'object') return
304
+ const tools = toolsOf(child)
305
+ if (tools === undefined || typeof tools.restrict !== 'function') return
306
+ try {
307
+ // `restrict` takes `{ allow?, deny? }` — a predicate is rejected, and an
308
+ // empty filter is a no-op — and returns the effect disposer, which stays
309
+ // owned by the child's own context lifetime.
310
+ tools.restrict({ deny: ['send_message', 'spawn_teammate', 'wait_agent', 'list_agents', 'interrupt_agent'] })
311
+ } catch {
312
+ /* a child that already started keeps the prompt-level instruction instead */
313
+ }
314
+ }
315
+
316
+ /**
317
+ * Resolve the tool registry visible to one agent.
318
+ *
319
+ * A Cordis context hands out traceable proxies on access, so the registry is
320
+ * read through the agent's own context rather than assumed to hang off a fixed
321
+ * property name.
322
+ *
323
+ * @param child - the live child agent.
324
+ * @returns the tool registry, or undefined when this build exposes none.
325
+ */
326
+ function toolsOf(child) {
327
+ const candidate = child.ctx
328
+ if (candidate === null || candidate === undefined || typeof candidate !== 'object') return undefined
329
+ if (typeof candidate.get === 'function') {
330
+ const tools = candidate.get('tools')
331
+ if (tools !== null && tools !== undefined) return tools
332
+ }
333
+ if (typeof candidate.tools === 'object' && candidate.tools !== null) return candidate.tools
334
+ return undefined
335
+ }
336
+
337
+ /** Route that serves this plugin's own settings to its settings page. */
338
+ const SETTINGS_ROUTE = '/api/dsh-btw/settings'
339
+
340
+ /** The config keys the settings page may read and write. */
341
+ const EDITABLE_KEYS = Object.freeze([
342
+ 'maxQuestionChars',
343
+ 'childProvider',
344
+ 'approvalPolicy',
345
+ 'sideAgentPreset',
346
+ 'disposeChild',
347
+ 'sideAgentTimeoutMs',
348
+ 'answerMaxChars',
349
+ 'provider',
350
+ 'model',
351
+ ])
352
+
353
+ /** Coerce one submitted value to the type its config key expects. */
354
+ function coerce(key, value) {
355
+ if (key === 'disposeChild') return value === true || value === 'true'
356
+ if (key === 'maxQuestionChars' || key === 'sideAgentTimeoutMs' || key === 'answerMaxChars') {
357
+ const number = Number(value)
358
+ return Number.isFinite(number) ? number : undefined
359
+ }
360
+ return typeof value === 'string' ? value : undefined
361
+ }
362
+
363
+ /**
364
+ * Serve this plugin's editable settings over one same-origin route.
365
+ *
366
+ * The route lives behind DSH's own browser authentication funnel (it is an
367
+ * `/api` path on the Host web server, and the browser reaches it with the
368
+ * session it already authenticated with), so the page needs no credential of
369
+ * its own. Reads report the effective config; writes go through
370
+ * `configEditor.edit`, which persists to the profile patch and reconciles the
371
+ * Loader — the same path the plugin manager uses.
372
+ *
373
+ * @param ctx - Host plugin context.
374
+ * @param config - normalized options.
375
+ * @returns a disposer, or undefined when the Host has no web server.
376
+ */
377
+ function mountSettingsRoute(ctx, config) {
378
+ const webServer = ctx.get('webServer')
379
+ if (webServer === null || webServer === undefined || typeof webServer.register !== 'function') return undefined
380
+
381
+ const readBody = (req) =>
382
+ new Promise((resolve, reject) => {
383
+ const chunks = []
384
+ let size = 0
385
+ req.on('data', (chunk) => {
386
+ size += chunk.length
387
+ if (size > 64 * 1024) {
388
+ reject(new Error('body too large'))
389
+ req.destroy()
390
+ return
391
+ }
392
+ chunks.push(chunk)
393
+ })
394
+ req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
395
+ req.on('error', reject)
396
+ })
397
+
398
+ const reply = (res, status, value) => {
399
+ const body = JSON.stringify(value)
400
+ res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
401
+ res.end(body)
402
+ }
403
+
404
+ const currentConfig = () => {
405
+ const editor = ctx.get('configEditor')
406
+ if (editor === null || editor === undefined || typeof editor.configuration !== 'function') return undefined
407
+ const rows = editor.configuration()
408
+ const row = rows.find((item) => item.entry?.id === 'dsh-btw' || item.entry?.options?.id === 'dsh-btw')
409
+ if (row === undefined) return undefined
410
+ return { row, merged: { ...row.inherited, ...row.override } }
411
+ }
412
+
413
+ const handler = async (req, res) => {
414
+ try {
415
+ if (req.method === 'GET') {
416
+ const found = currentConfig()
417
+ const values = {}
418
+ const merged = found === undefined ? { ...config } : found.merged
419
+ for (const key of EDITABLE_KEYS) values[key] = merged[key] ?? config[key]
420
+ reply(res, 200, { ok: true, values, editable: EDITABLE_KEYS, supported: found !== undefined })
421
+ return
422
+ }
423
+ if (req.method === 'POST') {
424
+ const raw = await readBody(req)
425
+ let parsed
426
+ try {
427
+ parsed = JSON.parse(raw)
428
+ } catch {
429
+ reply(res, 400, { ok: false, error: 'invalid JSON' })
430
+ return
431
+ }
432
+ const editor = ctx.get('configEditor')
433
+ if (editor === null || editor === undefined || typeof editor.edit !== 'function') {
434
+ reply(res, 503, { ok: false, error: 'configEditor unavailable in this profile' })
435
+ return
436
+ }
437
+ const found = currentConfig()
438
+ if (found === undefined) {
439
+ reply(res, 409, { ok: false, error: 'plugin row not found in the profile patch' })
440
+ return
441
+ }
442
+ const next = { ...found.merged }
443
+ for (const key of EDITABLE_KEYS) {
444
+ if (!(key in (parsed ?? {}))) continue
445
+ const value = coerce(key, parsed[key])
446
+ if (value !== undefined) next[key] = value
447
+ }
448
+ try {
449
+ await editor.edit(found.row.entry, () => next)
450
+ } catch (error) {
451
+ reply(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) })
452
+ return
453
+ }
454
+ reply(res, 200, { ok: true, values: next })
455
+ return
456
+ }
457
+ reply(res, 405, { ok: false, error: 'method not allowed' })
458
+ } catch (error) {
459
+ try {
460
+ reply(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) })
461
+ } catch {
462
+ /* the response may already be gone */
463
+ }
464
+ }
465
+ }
466
+
467
+ return webServer.register({ kind: 'exact', path: SETTINGS_ROUTE, handler })
468
+ }
469
+
470
+ /**
471
+ * Register `/btw` for every composed human-command adapter.
472
+ *
473
+ * The handler settles the whole child run before returning, so the answer
474
+ * arrives as the command result in the same lifecycle record that the Chat
475
+ * layer already renders. Only one side question per parent session may run at
476
+ * a time: a second one is refused rather than queued behind the first.
477
+ *
478
+ * @param ctx - Host plugin context.
479
+ * @param rawConfig - raw bundle config from the Loader row.
480
+ */
481
+ export function apply(ctx, rawConfig) {
482
+ const config = normalizeConfig(rawConfig)
483
+ /**
484
+ * Side questions that are still settling, keyed by parent session.
485
+ *
486
+ * The entry records when it was taken. A child whose turn never settles (an
487
+ * approval nobody answered, a provider that stalls) would otherwise block the
488
+ * session forever, so an entry older than the configured timeout is treated as
489
+ * stale and replaced instead of refusing the new question.
490
+ */
491
+ const inFlight = new Map()
492
+
493
+ /** Whether a fresh side question may start for this parent. */
494
+ const busy = (parentId) => {
495
+ const since = inFlight.get(parentId)
496
+ if (since === undefined) return false
497
+ if (Date.now() - since < config.sideAgentTimeoutMs) return true
498
+ inFlight.delete(parentId)
499
+ return false
500
+ }
501
+
502
+ const handler = async (invocation) => {
503
+ const raw = typeof invocation.rawInput === 'string' ? invocation.rawInput.trim() : ''
504
+
505
+ // `/btw --continue <childId> <question>` continues an existing side
506
+ // conversation. The Client builds this form from the panel's follow-up box.
507
+ // `rawInput` arrives with the leading whitespace the user typed preserved,
508
+ // so the marker is matched after trimming.
509
+ const followUp = /^--continue\s+(\S+)\s+([\s\S]+)$/u.exec(raw)
510
+ if (followUp !== null) {
511
+ const childId = followUp[1]
512
+ const question = followUp[2].trim()
513
+ if (question === '') return { kind: 'error', text: '追问内容为空。' }
514
+ const parentId = invocation.agent.id
515
+ if (busy(parentId)) {
516
+ return { kind: 'error', text: '上一个侧问还在跑,等它结束再问。' }
517
+ }
518
+ inFlight.set(parentId, Date.now())
519
+ try {
520
+ // A follow-up is a fresh child seeded with this thread's earlier turns:
521
+ // resuming the old child would notify the parent conversation.
522
+ const result = await runSideAgent(ctx, invocation, question, config, childId)
523
+ return { kind: 'success', text: `${result.text}\n\n[[${CHILD_MARKER}${result.childId}]]` }
524
+ } catch (error) {
525
+ const message = error instanceof Error ? error.message : String(error)
526
+ return { kind: 'error', text: message }
527
+ } finally {
528
+ inFlight.delete(parentId)
529
+ }
530
+ }
531
+
532
+ const question = raw
533
+ if (question === '') {
534
+ return {
535
+ kind: 'success',
536
+ text: '用法:/btw <问题>\n侧问会起一个继承当前上下文的临时子 agent(可用工具、写操作需审批),答案不进主干上下文。',
537
+ }
538
+ }
539
+ if (question.length > config.maxQuestionChars) {
540
+ return { kind: 'error', text: `问题过长(${question.length} 字符,上限 ${config.maxQuestionChars})。` }
541
+ }
542
+ const sessionId = invocation.agent.id
543
+ if (busy(sessionId)) {
544
+ return { kind: 'error', text: '上一个侧问还在跑,等它结束再问。' }
545
+ }
546
+ inFlight.set(sessionId, Date.now())
547
+ try {
548
+ const result = await runSideAgent(ctx, invocation, question, config)
549
+ // The trailer names the child session so the Client can open that
550
+ // conversation (tool calls and native approval prompts) in the Sidebar.
551
+ return { kind: 'success', text: `${result.text}\n\n[[${CHILD_MARKER}${result.childId}]]` }
552
+ } catch (error) {
553
+ if (invocation.signal !== undefined && invocation.signal !== null && invocation.signal.aborted === true) {
554
+ return { kind: 'error', text: '侧问已取消。' }
555
+ }
556
+ const message = error instanceof Error ? error.message : String(error)
557
+ return { kind: 'error', text: message }
558
+ } finally {
559
+ inFlight.delete(sessionId)
560
+ }
561
+ }
562
+
563
+ ctx.effect(function* registerCommand() {
564
+ yield () => {
565
+ inFlight.clear()
566
+ }
567
+ yield ctx.commands.register({
568
+ definitionId: DEFINITION_ID,
569
+ name: COMMAND_NAME,
570
+ description: '侧问:起一个继承上下文、能用工具的临时子 agent,答案不进主干上下文',
571
+ input: { hint: '<问题>' },
572
+ handler,
573
+ })
574
+ }, 'dsh-btw command')
575
+
576
+ ctx.effect(() => {
577
+ const dispose = mountSettingsRoute(ctx, config)
578
+ return () => {
579
+ if (typeof dispose === 'function') dispose()
580
+ }
581
+ }, 'dsh-btw settings route')
582
+ }
583
+
584
+ export const inject = ['commands']