dsh-dev-plan-presets 0.0.0-stage → 0.3.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/guard.js ADDED
@@ -0,0 +1,364 @@
1
+ /**
2
+ * 子代理模型守门(吸收 dsh-subagent-model-pin 的核心能力)。
3
+ *
4
+ * 语义:
5
+ * - 只管理子代理:有 parentSession 或 origin=subagent 的 Agent;主会话永不 select、永不 reject。
6
+ * - 创建时按 modelGuardMode 决定:pin=选中目标路由;audit=只记录 would-pin;off=什么都不做。
7
+ * - 每个被管理的子代理挂 agent/pre-step 守卫,逐步核对即将发请求的 modelSelection;
8
+ * pin + killOnViolation 时在发请求前 reject、cancel 子代理并通知父会话;audit 只记录。
9
+ * - honorExplicit=true 时,创建时检测到子代理被显式指定了非父级路由就不钉、也不挂守卫,
10
+ * 避免“说尊重却仍然打断”的自相矛盾。
11
+ * - 审计只记录路由、事件与 agent id,不记录任何凭据。
12
+ *
13
+ * 本文件不 import Node 内置模块,也不 import @deepseek-ai/*,便于单测。
14
+ */
15
+
16
+ import { routeMatches, routeOf } from './settings.js'
17
+ import { PRESET_ID } from './preset.js'
18
+
19
+ const MAX_TEXT = 240
20
+ const shortId = (value) => (typeof value === 'string' ? value.slice(0, 12) : '')
21
+
22
+ /**
23
+ * 判断一个 session header 是否代表子代理。
24
+ * @param {{ parentSession?: string, origin?: string } | undefined} header
25
+ */
26
+ export function isSubagentHeader(header) {
27
+ if (!header || typeof header !== 'object') return false
28
+ // fork 主对话也会带 parentSession(delegationDepth:0、无 origin),不能据此当子代理。
29
+ if (header.origin === 'subagent') return true
30
+ const depth = header.delegationDepth
31
+ return typeof depth === 'number' && Number.isFinite(depth) && depth > 0
32
+ }
33
+
34
+ /** 取父会话对象;拿不到就返回 undefined(调用方应跳过守门,避免误伤)。 */
35
+ const parentSessionOf = (ctx, agent) => {
36
+ try {
37
+ const parentId = agent?.session?.header?.parentSession
38
+ if (!parentId) return undefined
39
+ return ctx.get('agents')?.get?.(parentId)?.session
40
+ } catch {
41
+ return undefined
42
+ }
43
+ }
44
+
45
+ /**
46
+ * 读取会话当前 preset:优先 agentPresets.presetForSession(session)(含已不在 roster 的历史选择),
47
+ * 回退 session.header.agentPreset。拿不到时返回 undefined,调用方必须跳过守门。
48
+ */
49
+ export function presetOfSession(ctx, session) {
50
+ if (!session) return undefined
51
+ try {
52
+ const registry = ctx.get('agentPresets')
53
+ if (typeof registry?.presetForSession === 'function') {
54
+ const preset = registry.presetForSession(session)
55
+ if (typeof preset === 'string' && preset.length > 0) return preset
56
+ }
57
+ } catch {
58
+ /* 回退 header */
59
+ }
60
+ const fromHeader = session?.header?.agentPreset
61
+ return typeof fromHeader === 'string' && fromHeader.length > 0 ? fromHeader : undefined
62
+ }
63
+
64
+ /**
65
+ * 默认守门范围:只管理父会话 preset=dev-plan 的子代理;guardAllSubagents=true 时恢复全局。
66
+ * 父会话或 preset 无法可靠判断时返回 false(宁可跳过,也不误伤其他插件)。
67
+ */
68
+ export function shouldGuardAgent(ctx, agent, settings) {
69
+ if (settings?.guardAllSubagents === true) return true
70
+ const parent = parentSessionOf(ctx, agent)
71
+ if (!parent) return false
72
+ return presetOfSession(ctx, parent) === PRESET_ID
73
+ }
74
+
75
+ const parentRouteOf = (ctx, agent) => {
76
+ try {
77
+ const parentId = agent?.session?.header?.parentSession
78
+ if (!parentId) return undefined
79
+ const parent = ctx.get('agents')?.get?.(parentId)
80
+ const current = parent?.model?.current?.()
81
+ if (!current?.provider || !current?.model) return undefined
82
+ return { provider: current.provider, model: current.model }
83
+ } catch {
84
+ return undefined
85
+ }
86
+ }
87
+
88
+ const notifyParent = (ctx, agent, text) => {
89
+ try {
90
+ const parentId = agent?.session?.header?.parentSession
91
+ if (!parentId) return
92
+ const parent = ctx.get('agents')?.get?.(parentId)
93
+ if (typeof parent?.inject !== 'function') return
94
+ parent.inject({
95
+ content: [{ type: 'text', text }],
96
+ source: { kind: 'dev-plan-presets' },
97
+ })
98
+ } catch {
99
+ /* 通知失败不能反过来破坏守门 */
100
+ }
101
+ }
102
+
103
+ const describeRoute = (route) =>
104
+ route && route.provider && route.model ? `${route.provider}/${route.model}` : '(unknown)'
105
+
106
+ const stopChild = (ctx, agent, reason, hooks) => {
107
+ try {
108
+ if (typeof agent?.cancel === 'function') agent.cancel({ kind: 'user' })
109
+ } catch {
110
+ /* ignore */
111
+ }
112
+ notifyParent(
113
+ ctx,
114
+ agent,
115
+ `⚠️ [dev-plan-presets] 子代理 ${shortId(agent?.id)} ${reason},已中止。`,
116
+ )
117
+ hooks?.audit?.('stopped', { agent: shortId(agent?.id), reason })
118
+ }
119
+
120
+ const recordViolation = (hooks, agent, got, want, detail) => {
121
+ const entry = {
122
+ at: new Date().toISOString(),
123
+ agent: shortId(agent?.id),
124
+ session: shortId(agent?.session?.id),
125
+ from: describeRoute(got),
126
+ want: describeRoute(want),
127
+ text: String(detail).slice(0, MAX_TEXT),
128
+ }
129
+ try {
130
+ hooks?.recordViolation?.(entry)
131
+ } catch {
132
+ /* ignore */
133
+ }
134
+ }
135
+
136
+ const violationText = (got, want) =>
137
+ `越界使用模型 ${describeRoute(got)}(应为 ${describeRoute(want)})`
138
+
139
+ /**
140
+ * 给一个子代理装逐步守卫。
141
+ * 监听器注册在 agent.ctx 上,但**返回值必须由插件自己的生命周期持有**:
142
+ * agent 作用域销毁和插件卸载两边都会调用同一个幂等 disposer。
143
+ * @returns 幂等卸载函数;注册失败时返回 undefined。
144
+ */
145
+ const installStepGuard = (ctx, agent, settings, hooks, target) => {
146
+ let stopped = false
147
+ let active = true
148
+ const handler = async (payload, next) => {
149
+ const decision = await next()
150
+ try {
151
+ if (decision?.kind === 'reject') return decision
152
+ if (settings.modelGuardMode === 'off') return decision
153
+ if (stopped) return { kind: 'reject' }
154
+ const got = payload?.modelSelection
155
+ if (routeMatches(got, target)) return decision
156
+ const detail = violationText(got, target)
157
+ recordViolation(hooks, agent, got, target, detail)
158
+ hooks?.audit?.('violation', {
159
+ agent: shortId(agent?.id),
160
+ from: describeRoute(got),
161
+ want: describeRoute(target),
162
+ })
163
+ if (settings.modelGuardMode === 'pin' && settings.killOnViolation) {
164
+ stopped = true
165
+ stopChild(ctx, agent, detail, hooks)
166
+ return { kind: 'reject' }
167
+ }
168
+ return decision
169
+ } catch {
170
+ return decision
171
+ }
172
+ }
173
+ let off
174
+ try {
175
+ off = agent.ctx.on('agent/pre-step', handler)
176
+ } catch (error) {
177
+ hooks?.warn?.(`无法为子代理 ${shortId(agent?.id)} 安装模型守卫:${String(error?.message ?? error)}`)
178
+ return undefined
179
+ }
180
+ const dispose = () => {
181
+ if (!active) return
182
+ active = false
183
+ try {
184
+ if (typeof off === 'function') off()
185
+ } catch {
186
+ /* ignore */
187
+ }
188
+ }
189
+ // agent 作用域销毁时也释放;插件总 disposer 会先/后调用同一个 dispose,靠 active 幂等。
190
+ try {
191
+ if (typeof agent.ctx.effect === 'function') agent.ctx.effect(() => dispose)
192
+ } catch {
193
+ /* 没有 effect 时至少还有插件总 disposer */
194
+ }
195
+ return dispose
196
+ }
197
+
198
+ /**
199
+ * 处理一个 agent/created 事件。导出以便单测直接调用。
200
+ * @param {any} ctx
201
+ * @param {any} agent
202
+ * @param {import('./settings.js').DEFAULT_SETTINGS} settings
203
+ * @param {{ recordViolation?: Function, audit?: Function, warn?: Function }} hooks
204
+ * @param {{ provider: string, model: string, reasoningEffort?: string }} [target]
205
+ */
206
+ export function onAgentCreated(ctx, agent, settings, hooks = {}, target = routeOf(settings)) {
207
+ if (!agent || settings.modelGuardMode === 'off') return
208
+ const header = agent.session?.header
209
+ // 主会话在这里被挡掉:没有父会话,也不是 origin=subagent。
210
+ if (!isSubagentHeader(header)) return
211
+
212
+ // 默认只守 dev-plan 父会话派出的子代理;判断不了父会话 preset 时不守门。
213
+ if (settings.guardAllSubagents !== true) {
214
+ const parent = parentSessionOf(ctx, agent)
215
+ const preset = parent ? presetOfSession(ctx, parent) : undefined
216
+ if (preset !== PRESET_ID) {
217
+ if (preset === undefined) {
218
+ hooks?.audit?.('guard-skip-unknown-parent-preset', {
219
+ agent: shortId(agent?.id),
220
+ parentFound: Boolean(parent),
221
+ })
222
+ }
223
+ return
224
+ }
225
+ }
226
+
227
+ const mode = settings.modelGuardMode
228
+ const current = (() => {
229
+ try {
230
+ return agent.model?.current?.()
231
+ } catch {
232
+ return undefined
233
+ }
234
+ })()
235
+
236
+ if (mode === 'audit') {
237
+ const dispose = installStepGuard(ctx, agent, settings, hooks, target)
238
+ hooks?.audit?.('would-pin', {
239
+ agent: shortId(agent?.id),
240
+ from: describeRoute(current),
241
+ want: describeRoute(target),
242
+ })
243
+ return dispose
244
+ }
245
+
246
+ const parentRoute = parentRouteOf(ctx, agent)
247
+ const explicit = Boolean(
248
+ current &&
249
+ parentRoute &&
250
+ (current.provider !== parentRoute.provider || current.model !== parentRoute.model),
251
+ )
252
+ if (explicit && settings.honorExplicit) {
253
+ hooks?.audit?.('skip-explicit', {
254
+ agent: shortId(agent?.id),
255
+ from: describeRoute(current),
256
+ want: describeRoute(target),
257
+ })
258
+ return
259
+ }
260
+
261
+ // pin:守卫必须在 select 尝试之前装好。这样即使 select 不存在/抛错且 kill=false,
262
+ // 后续 pre-step 仍能记录越界,而不是变成完全不设防。
263
+ const dispose = installStepGuard(ctx, agent, settings, hooks, target)
264
+
265
+ // 已经在目标路由上:保留守卫防后续漂移即可。
266
+ if (routeMatches(current, target)) {
267
+ hooks?.audit?.('already', { agent: shortId(agent?.id), want: describeRoute(target) })
268
+ return dispose
269
+ }
270
+
271
+ const model = agent.model
272
+ if (typeof model?.select !== 'function') {
273
+ const detail = '当前 DSH 不支持 agent.model.select,无法钉住子代理路由'
274
+ recordViolation(hooks, agent, current, target, detail)
275
+ if (settings.killOnViolation) stopChild(ctx, agent, detail, hooks)
276
+ return dispose
277
+ }
278
+
279
+ try {
280
+ model.select({ ...target })
281
+ hooks?.audit?.('pinned', {
282
+ agent: shortId(agent?.id),
283
+ from: describeRoute(current),
284
+ want: describeRoute(target),
285
+ })
286
+ } catch (error) {
287
+ const detail = `钉住子代理路由失败:${String(error?.message ?? error)}`
288
+ recordViolation(hooks, agent, current, target, detail)
289
+ if (settings.killOnViolation) stopChild(ctx, agent, detail, hooks)
290
+ }
291
+ return dispose
292
+ }
293
+
294
+ /**
295
+ * 安装全局 agent/created 监听,并跟踪每个子代理的 step guard。
296
+ * 总 disposer 同时解绑事件监听和所有已装守卫:插件 HMR/卸载后旧设置不能继续拦截仍运行的 agent。
297
+ * @returns 幂等总卸载函数。
298
+ */
299
+ export function installModelGuard(ctx, settings, hooks = {}) {
300
+ if (settings.modelGuardMode === 'off') return () => {}
301
+ const target = routeOf(settings)
302
+ const steps = new Map()
303
+ let active = true
304
+
305
+ const release = (agent) => {
306
+ const dispose = steps.get(agent)
307
+ if (dispose === undefined) return
308
+ steps.delete(agent)
309
+ try {
310
+ dispose()
311
+ } catch {
312
+ /* ignore */
313
+ }
314
+ }
315
+
316
+ const listener = (payload) => {
317
+ const agent = payload?.agent
318
+ try {
319
+ const dispose = onAgentCreated(ctx, agent, settings, hooks, target)
320
+ if (typeof dispose === 'function' && agent && typeof agent === 'object') {
321
+ release(agent)
322
+ steps.set(agent, dispose)
323
+ }
324
+ } catch (error) {
325
+ hooks?.warn?.(`模型守门处理 agent 失败:${String(error?.message ?? error)}`)
326
+ }
327
+ }
328
+ const disposedListener = (payload) => {
329
+ try {
330
+ release(payload?.agent)
331
+ } catch {
332
+ /* ignore */
333
+ }
334
+ }
335
+
336
+ const offs = []
337
+ try {
338
+ offs.push(ctx.on('agent/created', listener))
339
+ offs.push(ctx.on('agent/disposed', disposedListener))
340
+ } catch (error) {
341
+ hooks?.warn?.(`无法注册模型守门:${String(error?.message ?? error)}`)
342
+ }
343
+
344
+ return () => {
345
+ if (!active) return
346
+ active = false
347
+ for (const off of offs) {
348
+ try {
349
+ if (typeof off === 'function') off()
350
+ } catch {
351
+ /* ignore */
352
+ }
353
+ }
354
+ const pending = [...steps.values()]
355
+ steps.clear()
356
+ for (const dispose of pending) {
357
+ try {
358
+ dispose()
359
+ } catch {
360
+ /* ignore */
361
+ }
362
+ }
363
+ }
364
+ }
package/icon.svg ADDED
@@ -0,0 +1,12 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Dev plan presets: a plan sheet with a read-only eye and a sealed pen">
2
+ <rect x="1" y="1" width="62" height="62" rx="14" fill="#101828"/>
3
+ <rect x="10" y="9" width="30" height="44" rx="4" fill="#1f2a3d" stroke="#3fbf9f" stroke-width="1.5"/>
4
+ <rect x="15" y="16" width="20" height="2.4" rx="1.2" fill="#3fbf9f"/>
5
+ <rect x="15" y="22" width="15" height="2.4" rx="1.2" fill="#3fbf9f" opacity="0.7"/>
6
+ <rect x="15" y="28" width="18" height="2.4" rx="1.2" fill="#3fbf9f" opacity="0.45"/>
7
+ <circle cx="45" cy="24" r="8.5" fill="#101828" stroke="#e6edf6" stroke-width="1.6"/>
8
+ <circle cx="45" cy="24" r="3" fill="#e6edf6"/>
9
+ <path d="M37.5 35.5 L50 48" stroke="#e0a43a" stroke-width="4" stroke-linecap="round"/>
10
+ <path d="M36.2 34.2 L38.8 36.8" stroke="#e0a43a" stroke-width="4" stroke-linecap="round"/>
11
+ <path d="M49 47 L52.5 50.5" stroke="#e0a43a" stroke-width="4" stroke-linecap="round"/>
12
+ </svg>