dsh-injection-manager 1.10.4 → 2.0.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.
Files changed (49) hide show
  1. package/CHANGELOG.md +267 -0
  2. package/CONTRIBUTING.md +2 -2
  3. package/README.md +282 -94
  4. package/README.zh.md +236 -97
  5. package/client.js +3325 -295
  6. package/docs/ARCHITECTURE.md +111 -24
  7. package/docs/COMPATIBILITY.md +28 -7
  8. package/docs/DETAIL.md +148 -0
  9. package/docs/DETAIL.zh.md +105 -1
  10. package/docs/FAQ.md +49 -7
  11. package/docs/PERFORMANCE.md +60 -6
  12. package/docs/images/demo.gif +0 -0
  13. package/docs/images/dock.png +0 -0
  14. package/docs/images/panel-dark.png +0 -0
  15. package/docs/images/panel-drawer.png +0 -0
  16. package/docs/images/panel-insights.png +0 -0
  17. package/docs/images/panel-manage-expanded.png +0 -0
  18. package/docs/images/panel-manage.png +0 -0
  19. package/docs/images/panel-settings.png +0 -0
  20. package/docs/images/panel-sidebar.png +0 -0
  21. package/docs/preview.svg +177 -23
  22. package/icon.svg +19 -5
  23. package/index.js +100 -14
  24. package/lib/actions.js +12 -4
  25. package/lib/apply.js +14 -2
  26. package/lib/compaction.js +126 -0
  27. package/lib/content.js +360 -0
  28. package/lib/events.js +216 -0
  29. package/lib/health.js +210 -0
  30. package/lib/pressure.js +146 -0
  31. package/lib/routes.js +293 -9
  32. package/lib/snapshot.js +256 -29
  33. package/lib/stats.js +394 -0
  34. package/lib/text.js +160 -0
  35. package/lib/trend.js +168 -0
  36. package/locale/de.json +251 -6
  37. package/locale/en.json +251 -6
  38. package/locale/es.json +251 -6
  39. package/locale/fr.json +251 -6
  40. package/locale/ja.json +251 -6
  41. package/locale/pt.json +251 -6
  42. package/locale/ru.json +252 -7
  43. package/locale/zh.json +249 -4
  44. package/package.json +16 -3
  45. package/screenshots.json +7 -5
  46. package/docs/images/panel-about.png +0 -0
  47. package/docs/images/panel-budget.png +0 -0
  48. package/docs/images/panel-policy.png +0 -0
  49. package/docs/images/panel-suites.png +0 -0
@@ -0,0 +1,126 @@
1
+ // Compaction receipts: what the harness already threw away for this session.
2
+ //
3
+ // The session log records `compaction/summary` (a summarizing compaction, with
4
+ // the heuristic price of everything it shadowed) and `compaction/prune`
5
+ // (a model-free prune of the same shape). Both carry `shadowedTokenCount`, so
6
+ // "how much did compaction save me" is a fact in the log rather than something
7
+ // this plugin has to infer from a shrinking total.
8
+ //
9
+ // The events are read from `session/event` as they commit. That listener only
10
+ // sees events from the moment this plugin is loaded, so the count is labelled
11
+ // as such instead of pretending to be the whole session — the alternative is
12
+ // replaying the durable log, which the session API explicitly deprecates for
13
+ // production callers.
14
+ import { appendEvent } from './events.js'
15
+
16
+ const bySession = new Map()
17
+ const LIMIT = 200
18
+
19
+ const EMPTY = { count: 0, prunes: 0, failures: 0, saved: 0, lastAt: null, lastSaved: 0, lastKind: null }
20
+
21
+ function blank() {
22
+ return { count: 0, prunes: 0, failures: 0, saved: 0, lastAt: null, lastSaved: 0, lastKind: null }
23
+ }
24
+
25
+ /**
26
+ * Dedupe key for a replay-safe compaction event. The host commits an event once,
27
+ * but a listener can be re-attached or a process can see the same committed
28
+ * event twice; a stable id keeps the feed from growing duplicate rows. The
29
+ * session id is part of the key because compaction ids are only scoped to one
30
+ * session.
31
+ */
32
+ function compactionKey(sessionId, kind, data) {
33
+ const id = data?.compactionId ?? data?.seq ?? data?.id
34
+ if (typeof id === 'string' || typeof id === 'number') return `compaction:${sessionId}:${kind}:${String(id)}`
35
+ return undefined
36
+ }
37
+
38
+ function logCompaction(sessionId, kind, data, saved) {
39
+ // Fire-and-forget: the receipt above is the durable number; the feed row is
40
+ // presentation, and the session event loop must not wait on a file write.
41
+ void appendEvent({
42
+ sessionId,
43
+ kind,
44
+ params: {
45
+ op: kind === 'prune' ? 'prune' : 'summary',
46
+ saved,
47
+ compactionId: typeof data?.compactionId === 'string' ? data.compactionId : undefined,
48
+ },
49
+ tokensDelta: -saved,
50
+ dedupeKey: compactionKey(sessionId, kind, data),
51
+ })
52
+ }
53
+
54
+ function remember(sessionId) {
55
+ let state = bySession.get(sessionId)
56
+ if (state === undefined) {
57
+ state = blank()
58
+ bySession.set(sessionId, state)
59
+ if (bySession.size > LIMIT) {
60
+ const oldest = bySession.keys().next()
61
+ if (!oldest.done) bySession.delete(oldest.value)
62
+ }
63
+ }
64
+ return state
65
+ }
66
+
67
+ /** Fold one committed session event into the per-session receipt. */
68
+ export function recordEvent(sessionId, event) {
69
+ if (typeof sessionId !== 'string' || sessionId === '') return
70
+ const type = event === undefined || event === null ? undefined : event.type
71
+ if (type !== 'compaction/summary' && type !== 'compaction/prune' && type !== 'compaction/end') return
72
+
73
+ const state = remember(sessionId)
74
+ const data = event.data ?? {}
75
+ if (type === 'compaction/summary') {
76
+ const saved = Math.max(0, Math.round(Number(data.shadowedTokenCount) || 0))
77
+ state.count += 1
78
+ state.saved += saved
79
+ state.lastAt = Date.now()
80
+ state.lastSaved = saved
81
+ state.lastKind = 'summary'
82
+ logCompaction(sessionId, 'compaction', data, saved)
83
+ return
84
+ }
85
+ if (type === 'compaction/prune') {
86
+ const saved = Math.max(0, Math.round(Number(data.shadowedTokenCount) || 0))
87
+ state.prunes += 1
88
+ state.saved += saved
89
+ state.lastAt = Date.now()
90
+ state.lastSaved = saved
91
+ state.lastKind = 'prune'
92
+ logCompaction(sessionId, 'prune', data, saved)
93
+ return
94
+ }
95
+ if (typeof data.error === 'string' && data.error.length > 0) {
96
+ state.failures += 1
97
+ void appendEvent({
98
+ sessionId,
99
+ kind: 'diagnostic',
100
+ params: { phase: 'compaction', error: data.error, compactionId: typeof data.compactionId === 'string' ? data.compactionId : undefined },
101
+ dedupeKey: compactionKey(sessionId, 'failure', data),
102
+ })
103
+ }
104
+ }
105
+
106
+ /** Subscribe the recorder to the host's committed-event feed. */
107
+ export function watchCompaction(ctx) {
108
+ return ctx.on('session/event', (session, event) => {
109
+ const id = session === undefined || session === null ? undefined : session.id
110
+ if (typeof id !== 'string') return
111
+ recordEvent(id, event)
112
+ })
113
+ }
114
+
115
+ /** The receipt for one agent's session, or the empty receipt. */
116
+ export function compactionOf(agent) {
117
+ const id = agent === undefined || agent === null ? undefined : agent?.session?.id
118
+ const state = typeof id === 'string' ? bySession.get(id) : undefined
119
+ if (state === undefined) return { ...EMPTY }
120
+ return { ...state }
121
+ }
122
+
123
+ /** Test hook: drop every remembered receipt. */
124
+ export function resetCompaction() {
125
+ bySession.clear()
126
+ }
package/lib/content.js ADDED
@@ -0,0 +1,360 @@
1
+ // Content inspection: the actual bytes behind one snapshot row.
2
+ //
3
+ // The panel can tell a user "this tool is 342 token" without ever showing what
4
+ // it says. This module answers the follow-up question — "show me the original"
5
+ // — for exactly the items the snapshot already lists, and for nothing else.
6
+ //
7
+ // Two hard rules:
8
+ // - Reads are whitelisted. A path is only opened when it came out of the
9
+ // snapshot's own collection (a skill's registered path, an instruction
10
+ // file the harness probes). There is no API here that takes a caller
11
+ // supplied path.
12
+ // - Truncation is UTF-8 safe. A cut inside a multi-byte character would turn
13
+ // the tail into U+FFFD, so the limit is enforced on bytes at a code-point
14
+ // boundary.
15
+ import { open } from 'node:fs/promises'
16
+ import { join, resolve as resolvePath } from 'node:path'
17
+ import { countText } from './measure.js'
18
+ import { cachedSources, collectSources, isLockedContext, resolveCwd } from './snapshot.js'
19
+
20
+ /** 256 KiB per the HTTP contract; also the default for any caller. */
21
+ export const CONTENT_LIMIT = 256 * 1024
22
+ /** Model tool budget: one item at a time must never dump 256 KiB into a turn. */
23
+ export const TOOL_CONTENT_LIMIT = 32 * 1024
24
+
25
+ export const CONTENT_CHANNELS = Object.freeze(['sections', 'contexts', 'skills', 'tools', 'instructions'])
26
+
27
+ function failure(status, error, message) {
28
+ const out = { ok: false, status, error }
29
+ if (message !== undefined) out.message = message
30
+ return out
31
+ }
32
+
33
+ /**
34
+ * Cut a string to at most `limit` UTF-8 bytes without splitting a code point or
35
+ * a surrogate pair. Returns the byte length of the kept prefix, so `bytes` in a
36
+ * response always describes the content actually returned.
37
+ */
38
+ export function truncateUtf8(text, limit = CONTENT_LIMIT) {
39
+ const source = typeof text === 'string' ? text : ''
40
+ const total = Buffer.byteLength(source, 'utf8')
41
+ if (total <= limit) return { text: source, truncated: false, bytes: total }
42
+ if (limit <= 0) return { text: '', truncated: total > 0, bytes: 0 }
43
+ let low = 0
44
+ let high = source.length
45
+ while (low < high) {
46
+ const mid = Math.ceil((low + high) / 2)
47
+ if (Buffer.byteLength(source.slice(0, mid), 'utf8') <= limit) low = mid
48
+ else high = mid - 1
49
+ }
50
+ let cut = low
51
+ const code = source.charCodeAt(cut - 1)
52
+ if (code >= 0xd800 && code <= 0xdbff) cut -= 1
53
+ const kept = source.slice(0, cut)
54
+ return { text: kept, truncated: true, bytes: Buffer.byteLength(kept, 'utf8') }
55
+ }
56
+
57
+ /**
58
+ * Every absolute path the current snapshot collection is allowed to open:
59
+ * registered skill files (including a SKILL.md under a directory resource
60
+ * base) and probed instruction files. Derived only from collection output.
61
+ */
62
+ export function allowedPaths(sources) {
63
+ const allowed = new Set()
64
+ const add = (candidate) => {
65
+ if (typeof candidate !== 'string' || candidate.length === 0) return
66
+ try {
67
+ allowed.add(resolvePath(candidate))
68
+ } catch {
69
+ /* an unrepresentable path is simply not whitelisted */
70
+ }
71
+ }
72
+ const skills = Array.isArray(sources?.skillState?.all) ? sources.skillState.all : []
73
+ for (const skill of skills) {
74
+ add(skill?.path)
75
+ if (skill?.resourceBase?.kind === 'directory' && typeof skill.resourceBase.path === 'string') {
76
+ add(join(skill.resourceBase.path, 'SKILL.md'))
77
+ }
78
+ }
79
+ const files = Array.isArray(sources?.instructions?.files) ? sources.instructions.files : []
80
+ for (const file of files) add(file?.path)
81
+ return allowed
82
+ }
83
+
84
+ /**
85
+ * Read the first `limit` bytes of a whitelisted file and decode them as UTF-8.
86
+ * A path that is not in `allowed` throws before any filesystem access.
87
+ */
88
+ export async function readTextFile(path, limit = CONTENT_LIMIT, allowed) {
89
+ if (!(allowed instanceof Set)) throw new Error('path-not-allowed')
90
+ const resolved = resolvePath(String(path))
91
+ if (!allowed.has(resolved)) throw new Error('path-not-allowed')
92
+
93
+ const handle = await open(resolved, 'r')
94
+ try {
95
+ const info = await handle.stat()
96
+ const totalBytes = Number.isFinite(info.size) ? info.size : 0
97
+ const wanted = Math.min(totalBytes, limit + 4)
98
+ const buffer = Buffer.alloc(wanted)
99
+ let offset = 0
100
+ while (offset < wanted) {
101
+ const { bytesRead } = await handle.read(buffer, offset, wanted - offset, offset)
102
+ if (bytesRead <= 0) break
103
+ offset += bytesRead
104
+ }
105
+ const decoder = new TextDecoder('utf-8', { fatal: false })
106
+ let text = decoder.decode(buffer.subarray(0, offset), { stream: true })
107
+ if (offset >= totalBytes) text += decoder.decode()
108
+ const cut = truncateUtf8(text, limit)
109
+ return {
110
+ text: cut.text,
111
+ truncated: offset < totalBytes || cut.truncated,
112
+ bytes: cut.bytes,
113
+ totalBytes,
114
+ }
115
+ } finally {
116
+ await handle.close()
117
+ }
118
+ }
119
+
120
+ const mcpServerOf = (name) => {
121
+ if (typeof name !== 'string' || !name.startsWith('mcp__')) return undefined
122
+ const rest = name.slice('mcp__'.length)
123
+ const end = rest.indexOf('__')
124
+ return end > 0 ? rest.slice(0, end) : rest.split('_')[0]
125
+ }
126
+
127
+ // Content ids are the same strings `/summary` items[].id carries: the snapshot
128
+ // prefixes them with the singular channel name (`tool:read`, not `tools:read`).
129
+ const ITEM_ID_PREFIX = {
130
+ sections: 'section:',
131
+ contexts: 'context:',
132
+ skills: 'skill:',
133
+ tools: 'tool:',
134
+ instructions: 'instructions:',
135
+ }
136
+
137
+ function itemId(channel, name) {
138
+ return `${ITEM_ID_PREFIX[channel] ?? `${channel}:`}${name}`
139
+ }
140
+
141
+ // Snapshot ids are singular (`tool:read`, `section:harness:identity`) while the
142
+ // channel names are plural; both spellings are accepted so a panel can pass an
143
+ // id from either place.
144
+ const ID_PREFIXES = {
145
+ sections: ['section:', 'sections:'],
146
+ contexts: ['context:', 'contexts:'],
147
+ skills: ['skill:', 'skills:'],
148
+ tools: ['tool:', 'tools:'],
149
+ instructions: ['instructions:'],
150
+ }
151
+
152
+ function nameFromId(channel, id) {
153
+ for (const prefix of ID_PREFIXES[channel] ?? []) {
154
+ if (id.startsWith(prefix)) return id.slice(prefix.length)
155
+ }
156
+ return id
157
+ }
158
+
159
+ function toolProvider(name) {
160
+ const server = mcpServerOf(name)
161
+ return server === undefined ? undefined : `mcp:${server}`
162
+ }
163
+
164
+ function formatJson(value) {
165
+ try {
166
+ return JSON.stringify(value, null, 2)
167
+ } catch {
168
+ return JSON.stringify({ name: String(value?.name ?? ''), description: String(value?.description ?? ''), parameters: {} }, null, 2)
169
+ }
170
+ }
171
+
172
+ function skillFrontmatter(name, description, whenToUse) {
173
+ const lines = ['---', `name: ${name}`, `description: ${JSON.stringify(description)}`]
174
+ if (typeof whenToUse === 'string' && whenToUse.length > 0) lines.push(`whenToUse: ${JSON.stringify(whenToUse)}`)
175
+ lines.push('---', '')
176
+ return lines.join('\n')
177
+ }
178
+
179
+ function findSkill(sources, name) {
180
+ const skills = Array.isArray(sources?.skillState?.all) ? sources.skillState.all : []
181
+ return skills.find((skill) => String(skill?.name ?? '') === name)
182
+ }
183
+
184
+ function findInstruction(sources, name) {
185
+ const files = Array.isArray(sources?.instructions?.files) ? sources.instructions.files : []
186
+ return files.find((file) => file?.path === name || file?.display === name)
187
+ }
188
+
189
+ async function readSkill(sources, skill, name, limit) {
190
+ const allowed = allowedPaths(sources)
191
+ const candidates = []
192
+ if (typeof skill?.path === 'string' && skill.path.length > 0) candidates.push(skill.path)
193
+ if (skill?.resourceBase?.kind === 'directory' && typeof skill.resourceBase.path === 'string') {
194
+ candidates.push(join(skill.resourceBase.path, 'SKILL.md'))
195
+ }
196
+ for (const candidate of candidates) {
197
+ try {
198
+ const file = await readTextFile(candidate, limit, allowed)
199
+ if (file.text.trim().length > 0) {
200
+ return {
201
+ ok: true,
202
+ contentType: 'markdown',
203
+ content: file.text,
204
+ bytes: file.bytes,
205
+ truncated: file.truncated,
206
+ sourcePath: resolvePath(candidate),
207
+ note: 'file',
208
+ }
209
+ }
210
+ } catch {
211
+ /* try the next candidate, then fall back to the catalog line */
212
+ }
213
+ }
214
+ const description = typeof skill?.description === 'string' ? skill.description : ''
215
+ const fallback = skillFrontmatter(name, description, skill?.whenToUse)
216
+ const cut = truncateUtf8(fallback, limit)
217
+ return { ok: true, contentType: 'markdown', content: cut.text, bytes: cut.bytes, truncated: cut.truncated, note: 'catalog' }
218
+ }
219
+
220
+ /**
221
+ * Collect the original text behind one snapshot item.
222
+ *
223
+ * `id` is the same string `/summary` items[].id carries (`<channel>:<name>`);
224
+ * a bare name is accepted as a convenience. Returns `{ok:true,...}` on success
225
+ * or `{ok:false,status,error}` so the route can map 400/404/504 without
226
+ * embedding HTTP statuses in this module.
227
+ */
228
+ export async function collectContent(ctx, agent, channel, id, signal, options = {}) {
229
+ const limit = Number.isFinite(options.limit) && options.limit > 0 ? Math.round(options.limit) : CONTENT_LIMIT
230
+ if (!CONTENT_CHANNELS.includes(channel)) {
231
+ return failure(400, 'invalid-channel', `channel must be one of ${CONTENT_CHANNELS.join('|')}`)
232
+ }
233
+ if (typeof id !== 'string' || id.trim().length === 0) {
234
+ return failure(400, 'invalid-id', 'id is required')
235
+ }
236
+ const raw = id.trim()
237
+ const name = nameFromId(channel, raw)
238
+ if (name.length === 0) return failure(404, 'not_found', 'empty item name')
239
+
240
+ try {
241
+ const sources = cachedSources(agent) ?? (await collectSources(ctx, agent, await resolveCwd(ctx, agent, signal), signal))
242
+ if (signal?.aborted === true) return failure(504, 'timeout', 'content collection exceeded the 2s budget')
243
+
244
+ if (channel === 'sections' || channel === 'contexts') {
245
+ const bucket = channel === 'sections' ? sources.assembly?.sections : sources.assembly?.contexts
246
+ const entries = Array.isArray(bucket) ? bucket : []
247
+ const entry = entries.find((candidate) => String(candidate?.name ?? '') === name)
248
+ if (entry === undefined) return failure(404, 'not_found', `no ${channel} item named ${name}`)
249
+ const text = typeof entry.text === 'string' ? entry.text : ''
250
+ const measure = countText(text)
251
+ const cut = truncateUtf8(text, limit)
252
+ const locked = channel === 'contexts' && (entry.required === true || isLockedContext(name))
253
+ return {
254
+ ok: true,
255
+ item: { id: itemId(channel, name), channel, name, tokens: measure.tokens, chars: measure.chars, locked },
256
+ contentType: 'text',
257
+ content: cut.text,
258
+ bytes: cut.bytes,
259
+ truncated: cut.truncated,
260
+ limit,
261
+ note: 'assemble',
262
+ }
263
+ }
264
+
265
+ if (channel === 'tools') {
266
+ const schemas = Array.isArray(sources.schemas) ? sources.schemas : []
267
+ const schema = schemas.find((candidate) => String(candidate?.name ?? '') === name)
268
+ if (schema === undefined) return failure(404, 'not_found', `no tool named ${name}`)
269
+ const description = typeof schema.description === 'string' ? schema.description : ''
270
+ let rawParameters = ''
271
+ try {
272
+ rawParameters = JSON.stringify(schema.parameters ?? {}) ?? ''
273
+ } catch {
274
+ rawParameters = ''
275
+ }
276
+ const measure = countText(`${name}\n${description}\n${rawParameters}`)
277
+ const formatted = formatJson({ name, description, parameters: schema.parameters ?? {} })
278
+ const cut = truncateUtf8(formatted, limit)
279
+ const provider = toolProvider(name)
280
+ return {
281
+ ok: true,
282
+ item: {
283
+ id: itemId('tools', name),
284
+ channel: 'tools',
285
+ name,
286
+ tokens: measure.tokens,
287
+ chars: measure.chars,
288
+ ...(provider === undefined ? {} : { provider }),
289
+ locked: false,
290
+ },
291
+ contentType: 'json',
292
+ content: cut.text,
293
+ bytes: cut.bytes,
294
+ truncated: cut.truncated,
295
+ limit,
296
+ note: 'snapshot',
297
+ }
298
+ }
299
+
300
+ if (channel === 'skills') {
301
+ const skill = findSkill(sources, name)
302
+ if (skill === undefined) return failure(404, 'not_found', `no skill named ${name}`)
303
+ const description = typeof skill.description === 'string' ? skill.description : ''
304
+ const measure = countText(`${name}\n${description}`)
305
+ const file = await readSkill(sources, skill, name, limit)
306
+ return {
307
+ ok: true,
308
+ item: {
309
+ id: itemId('skills', name),
310
+ channel: 'skills',
311
+ name,
312
+ tokens: measure.tokens,
313
+ chars: measure.chars,
314
+ ...(typeof skill.provider === 'string' ? { provider: skill.provider } : {}),
315
+ locked: false,
316
+ },
317
+ contentType: file.contentType,
318
+ content: file.content,
319
+ bytes: file.bytes,
320
+ truncated: file.truncated,
321
+ limit,
322
+ ...(file.sourcePath === undefined ? {} : { sourcePath: file.sourcePath }),
323
+ note: file.note,
324
+ }
325
+ }
326
+
327
+ // instructions
328
+ const file = findInstruction(sources, name)
329
+ if (file === undefined) return failure(404, 'not_found', `no instruction file matching ${name}`)
330
+ if (file.status === 'missing') return failure(404, 'not_found', `${file.display} is not present on disk`)
331
+ const allowed = allowedPaths(sources)
332
+ let read
333
+ try {
334
+ read = await readTextFile(file.path, limit, allowed)
335
+ } catch (error) {
336
+ return failure(500, 'unreadable', String(error?.message ?? error))
337
+ }
338
+ return {
339
+ ok: true,
340
+ item: {
341
+ id: itemId('instructions', file.path),
342
+ channel: 'instructions',
343
+ name: file.display,
344
+ tokens: Number(file.tokens) || 0,
345
+ chars: Number(file.chars) || 0,
346
+ locked: true,
347
+ },
348
+ contentType: 'markdown',
349
+ content: read.text,
350
+ bytes: read.bytes,
351
+ truncated: read.truncated,
352
+ limit,
353
+ sourcePath: resolvePath(file.path),
354
+ note: 'file',
355
+ }
356
+ } catch (error) {
357
+ if (signal?.aborted === true) return failure(504, 'timeout', 'content collection exceeded the 2s budget')
358
+ return failure(500, 'content-failed', String(error?.message ?? error))
359
+ }
360
+ }