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.
- package/CHANGELOG.md +267 -0
- package/CONTRIBUTING.md +2 -2
- package/README.md +282 -94
- package/README.zh.md +236 -97
- package/client.js +3325 -295
- package/docs/ARCHITECTURE.md +111 -24
- package/docs/COMPATIBILITY.md +28 -7
- package/docs/DETAIL.md +148 -0
- package/docs/DETAIL.zh.md +105 -1
- package/docs/FAQ.md +49 -7
- package/docs/PERFORMANCE.md +60 -6
- package/docs/images/demo.gif +0 -0
- package/docs/images/dock.png +0 -0
- package/docs/images/panel-dark.png +0 -0
- package/docs/images/panel-drawer.png +0 -0
- package/docs/images/panel-insights.png +0 -0
- package/docs/images/panel-manage-expanded.png +0 -0
- package/docs/images/panel-manage.png +0 -0
- package/docs/images/panel-settings.png +0 -0
- package/docs/images/panel-sidebar.png +0 -0
- package/docs/preview.svg +177 -23
- package/icon.svg +19 -5
- package/index.js +100 -14
- package/lib/actions.js +12 -4
- package/lib/apply.js +14 -2
- package/lib/compaction.js +126 -0
- package/lib/content.js +360 -0
- package/lib/events.js +216 -0
- package/lib/health.js +210 -0
- package/lib/pressure.js +146 -0
- package/lib/routes.js +293 -9
- package/lib/snapshot.js +256 -29
- package/lib/stats.js +394 -0
- package/lib/text.js +160 -0
- package/lib/trend.js +168 -0
- package/locale/de.json +251 -6
- package/locale/en.json +251 -6
- package/locale/es.json +251 -6
- package/locale/fr.json +251 -6
- package/locale/ja.json +251 -6
- package/locale/pt.json +251 -6
- package/locale/ru.json +252 -7
- package/locale/zh.json +249 -4
- package/package.json +16 -3
- package/screenshots.json +7 -5
- package/docs/images/panel-about.png +0 -0
- package/docs/images/panel-budget.png +0 -0
- package/docs/images/panel-policy.png +0 -0
- package/docs/images/panel-suites.png +0 -0
package/lib/events.js
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
// Injection events: an append-only feed of what changed a session's first-turn
|
|
2
|
+
// context, so the insights tab can show a timeline instead of only totals.
|
|
3
|
+
//
|
|
4
|
+
// One JSON file under $DSH_HOME/injection-manager/events.json. Writes are
|
|
5
|
+
// tmp+rename (a crash keeps the previous feed), the feed is capped at 300
|
|
6
|
+
// events, and dedupe keys make replayed host events idempotent: a compaction
|
|
7
|
+
// receipt observed twice must not become two rows.
|
|
8
|
+
//
|
|
9
|
+
// Privacy boundary: events describe policy and session metadata only. The
|
|
10
|
+
// normalizer below flattens params to primitives and truncates every string, so
|
|
11
|
+
// a caller cannot accidentally persist prompt text or a skill body here.
|
|
12
|
+
import { createHash } from 'node:crypto'
|
|
13
|
+
import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
|
|
14
|
+
import { dirname, join } from 'node:path'
|
|
15
|
+
import { resolveDshHome } from './policy.js'
|
|
16
|
+
|
|
17
|
+
const VERSION = 1
|
|
18
|
+
const FILE_NAME = 'events.json'
|
|
19
|
+
// Single string value ceiling inside params. Long enough for a suite label or a
|
|
20
|
+
// file relpath, short enough that a feed row can never carry a document.
|
|
21
|
+
const PARAM_TEXT_LIMIT = 200
|
|
22
|
+
const MAX_PARAM_ENTRIES = 24
|
|
23
|
+
|
|
24
|
+
/** The fixed kind enum. The UI owns the locale text (`ev.<kind>`). */
|
|
25
|
+
export const EVENT_KINDS = Object.freeze([
|
|
26
|
+
'session-created',
|
|
27
|
+
'policy-saved',
|
|
28
|
+
'preset',
|
|
29
|
+
'budget',
|
|
30
|
+
'switch',
|
|
31
|
+
'undo',
|
|
32
|
+
'import',
|
|
33
|
+
'compaction',
|
|
34
|
+
'prune',
|
|
35
|
+
'model-switch',
|
|
36
|
+
'mode-toggle',
|
|
37
|
+
'diagnostic',
|
|
38
|
+
])
|
|
39
|
+
|
|
40
|
+
export const EVENT_LIMIT = 300
|
|
41
|
+
|
|
42
|
+
export const eventsFilePath = () => join(resolveDshHome(), 'injection-manager', FILE_NAME)
|
|
43
|
+
|
|
44
|
+
let cache = null
|
|
45
|
+
let writing = null
|
|
46
|
+
let dirty = false
|
|
47
|
+
|
|
48
|
+
function blank() {
|
|
49
|
+
return { version: VERSION, events: [] }
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function isPlainEvent(value) {
|
|
53
|
+
return value !== null && typeof value === 'object' && typeof value.kind === 'string' && typeof value.at === 'number'
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
async function load() {
|
|
57
|
+
if (cache !== null) return cache
|
|
58
|
+
try {
|
|
59
|
+
const parsed = JSON.parse(await readFile(eventsFilePath(), 'utf8'))
|
|
60
|
+
const events = Array.isArray(parsed?.events) ? parsed.events.filter(isPlainEvent) : []
|
|
61
|
+
cache = { version: VERSION, events: events.slice(-EVENT_LIMIT) }
|
|
62
|
+
} catch {
|
|
63
|
+
cache = blank()
|
|
64
|
+
}
|
|
65
|
+
return cache
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Keep the newest EVENT_LIMIT entries, then write once per burst. */
|
|
69
|
+
async function flush() {
|
|
70
|
+
if (writing !== null) {
|
|
71
|
+
dirty = true
|
|
72
|
+
return writing
|
|
73
|
+
}
|
|
74
|
+
writing = (async () => {
|
|
75
|
+
try {
|
|
76
|
+
do {
|
|
77
|
+
dirty = false
|
|
78
|
+
const state = cache ?? blank()
|
|
79
|
+
const events = state.events.slice(-EVENT_LIMIT)
|
|
80
|
+
const body = JSON.stringify({ version: VERSION, events })
|
|
81
|
+
const target = eventsFilePath()
|
|
82
|
+
await mkdir(dirname(target), { recursive: true })
|
|
83
|
+
const temporary = `${target}.tmp-${process.pid}`
|
|
84
|
+
await writeFile(temporary, body, 'utf8')
|
|
85
|
+
await rename(temporary, target)
|
|
86
|
+
} while (dirty)
|
|
87
|
+
} catch {
|
|
88
|
+
/* the feed is a nicety; a failed write must never break a policy save */
|
|
89
|
+
} finally {
|
|
90
|
+
writing = null
|
|
91
|
+
}
|
|
92
|
+
})()
|
|
93
|
+
return writing
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function hashText(text) {
|
|
97
|
+
return createHash('sha256').update(text).digest('hex').slice(0, 16)
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function clampPrimitive(value) {
|
|
101
|
+
if (typeof value === 'string') return value.length > PARAM_TEXT_LIMIT ? value.slice(0, PARAM_TEXT_LIMIT) : value
|
|
102
|
+
if (typeof value === 'number') return Number.isFinite(value) ? value : 0
|
|
103
|
+
if (typeof value === 'boolean' || value === null) return value
|
|
104
|
+
return undefined
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Params are flat primitives only. Nested objects are dropped rather than
|
|
109
|
+
* serialized: it keeps the feed row small, and it removes the easiest path by
|
|
110
|
+
* which session text could end up in a durable file.
|
|
111
|
+
*/
|
|
112
|
+
function normalizeParams(raw) {
|
|
113
|
+
if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return {}
|
|
114
|
+
const out = {}
|
|
115
|
+
let entries = 0
|
|
116
|
+
for (const [key, value] of Object.entries(raw)) {
|
|
117
|
+
if (entries >= MAX_PARAM_ENTRIES) break
|
|
118
|
+
if (typeof key !== 'string' || key.length === 0) continue
|
|
119
|
+
if (Array.isArray(value)) {
|
|
120
|
+
const list = value.map(clampPrimitive).filter((entry) => entry !== undefined).slice(0, 20)
|
|
121
|
+
if (list.length > 0) {
|
|
122
|
+
out[key] = list
|
|
123
|
+
entries += 1
|
|
124
|
+
}
|
|
125
|
+
continue
|
|
126
|
+
}
|
|
127
|
+
const primitive = clampPrimitive(value)
|
|
128
|
+
if (primitive === undefined) continue
|
|
129
|
+
out[key] = primitive
|
|
130
|
+
entries += 1
|
|
131
|
+
}
|
|
132
|
+
return out
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
function stableStringify(value) {
|
|
136
|
+
if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
|
|
137
|
+
if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
|
|
138
|
+
const keys = Object.keys(value).sort()
|
|
139
|
+
return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** Dedupe key for an event whose identity is its timestamp, kind and params. */
|
|
143
|
+
export function dedupeKeyFor(kind, params, at) {
|
|
144
|
+
return `${Math.round(Number(at) || 0)}|${kind}|${hashText(stableStringify(params ?? {}))}`
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Append one event. Resolves `{added:true,event}` or `{added:false,...}` instead
|
|
149
|
+
* of throwing: every call site is a side effect of a real mutation, and a feed
|
|
150
|
+
* failure must never turn a saved policy into an error.
|
|
151
|
+
*/
|
|
152
|
+
export async function appendEvent(entry = {}) {
|
|
153
|
+
try {
|
|
154
|
+
const kind = typeof entry.kind === 'string' ? entry.kind : ''
|
|
155
|
+
if (!EVENT_KINDS.includes(kind)) return { added: false, error: 'unknown-kind' }
|
|
156
|
+
const at = Number.isFinite(entry.at) ? Math.round(entry.at) : Date.now()
|
|
157
|
+
const params = normalizeParams(entry.params)
|
|
158
|
+
const explicit = typeof entry.dedupeKey === 'string' && entry.dedupeKey.length > 0 ? entry.dedupeKey.slice(0, 120) : undefined
|
|
159
|
+
const dedupeKey = explicit ?? dedupeKeyFor(kind, params, at)
|
|
160
|
+
const state = await load()
|
|
161
|
+
if (state.events.some((event) => event.dedupeKey === dedupeKey)) return { added: false, duplicate: true, dedupeKey }
|
|
162
|
+
const sessionId = typeof entry.sessionId === 'string' && entry.sessionId.length > 0 ? entry.sessionId : undefined
|
|
163
|
+
const tokensDelta = Number.isFinite(entry.tokensDelta) ? Math.round(entry.tokensDelta) : 0
|
|
164
|
+
const event = {
|
|
165
|
+
id: `evt_${hashText(`${dedupeKey}|${sessionId ?? ''}`)}`,
|
|
166
|
+
at,
|
|
167
|
+
kind,
|
|
168
|
+
params,
|
|
169
|
+
tokensDelta,
|
|
170
|
+
sessionId,
|
|
171
|
+
dedupeKey,
|
|
172
|
+
}
|
|
173
|
+
state.events.push(event)
|
|
174
|
+
if (state.events.length > EVENT_LIMIT) state.events = state.events.slice(-EVENT_LIMIT)
|
|
175
|
+
await flush()
|
|
176
|
+
return { added: true, event }
|
|
177
|
+
} catch {
|
|
178
|
+
return { added: false, error: 'append-failed' }
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/** Test/module hook: wait for any queued write. */
|
|
183
|
+
export function flushEvents() {
|
|
184
|
+
return writing ?? Promise.resolve()
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
function publicEvent(event) {
|
|
188
|
+
const out = { id: event.id, at: event.at, kind: event.kind, params: event.params, tokensDelta: event.tokensDelta }
|
|
189
|
+
if (typeof event.sessionId === 'string') out.sessionId = event.sessionId
|
|
190
|
+
return out
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Read the newest `limit` events, oldest first inside the window so a timeline
|
|
195
|
+
* renders top-to-bottom without the caller re-sorting. `sessionId` filters to
|
|
196
|
+
* one conversation; omitting it reads the whole feed.
|
|
197
|
+
*/
|
|
198
|
+
export async function readEvents(sessionId, limit = 60) {
|
|
199
|
+
const state = await load()
|
|
200
|
+
// Route callers pass the query string verbatim; coerce before clamping.
|
|
201
|
+
const requested = Number(limit)
|
|
202
|
+
const max = Math.min(EVENT_LIMIT, Math.max(1, Number.isFinite(requested) ? Math.round(requested) : 60))
|
|
203
|
+
const filtered =
|
|
204
|
+
typeof sessionId === 'string' && sessionId.length > 0 ? state.events.filter((event) => event.sessionId === sessionId) : state.events.slice()
|
|
205
|
+
const sorted = filtered.sort((left, right) => (left.at ?? 0) - (right.at ?? 0))
|
|
206
|
+
const selected = sorted.slice(-max)
|
|
207
|
+
return {
|
|
208
|
+
events: selected.map(publicEvent),
|
|
209
|
+
coverage: { from: selected.length > 0 ? selected[0].at : null, count: selected.length, limit: max },
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** Test hook: forget the in-memory feed (the file stays as written). */
|
|
214
|
+
export function resetEventsCache() {
|
|
215
|
+
cache = null
|
|
216
|
+
}
|
package/lib/health.js
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
// Health: deterministic, read-only findings over one snapshot.
|
|
2
|
+
//
|
|
3
|
+
// Pure on purpose. The panel, the `/health` route and `/inject health` must all
|
|
4
|
+
// derive the same checks from the same snapshot; anything that needs an extra
|
|
5
|
+
// disk read or a second assemble belongs in the snapshot, not here. The only
|
|
6
|
+
// clock value used is `snapshot.generatedAt`, so two calls on one snapshot are
|
|
7
|
+
// byte-identical.
|
|
8
|
+
//
|
|
9
|
+
// Two codes from the contract are deliberately never emitted:
|
|
10
|
+
// - `duplicate-skill`: the skill registry resolves duplicate names to one
|
|
11
|
+
// winner before `snapshot()` returns, so losing provider candidates are not
|
|
12
|
+
// observable through the public API. Inventing them would be a lie.
|
|
13
|
+
// - `tool-name-collision`: `ctx.tools.schemas()` returns the resolved tool
|
|
14
|
+
// set; a duplicate name cannot reach it.
|
|
15
|
+
// The enum stays complete so a future host build with a visible catalog can add
|
|
16
|
+
// them without changing the UI contract.
|
|
17
|
+
import { percent } from './measure.js'
|
|
18
|
+
|
|
19
|
+
export const HEALTH_CODES = Object.freeze([
|
|
20
|
+
'heavy-suite',
|
|
21
|
+
'duplicate-skill',
|
|
22
|
+
'tool-name-collision',
|
|
23
|
+
'budget-gap',
|
|
24
|
+
'catalog-truncated',
|
|
25
|
+
'locked-items',
|
|
26
|
+
'unknown-window',
|
|
27
|
+
'no-policy',
|
|
28
|
+
'empty-catalog',
|
|
29
|
+
])
|
|
30
|
+
|
|
31
|
+
export const HEALTH_ACTION_KINDS = Object.freeze(['switch-group', 'set-budget', 'open-content', 'open-tab'])
|
|
32
|
+
|
|
33
|
+
const SEVERITY_ORDER = { high: 0, warn: 1, info: 2 }
|
|
34
|
+
// A suite is worth flagging once it is a quarter of the first turn, or once it
|
|
35
|
+
// is large in absolute terms even in a big prompt.
|
|
36
|
+
const HEAVY_SHARE = 25
|
|
37
|
+
const HEAVY_TOKENS = 30000
|
|
38
|
+
const HEAVY_MAX_CHECKS = 3
|
|
39
|
+
// Locked items (instruction files, required contexts) only matter as a share;
|
|
40
|
+
// a handful of percent is normal and should not produce a permanent warning.
|
|
41
|
+
const LOCKED_SHARE = 10
|
|
42
|
+
const LOCKED_WARN_SHARE = 30
|
|
43
|
+
|
|
44
|
+
const num = (value) => {
|
|
45
|
+
const parsed = Number(value)
|
|
46
|
+
return Number.isFinite(parsed) ? parsed : 0
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function groupAction(group) {
|
|
50
|
+
const channel = String(group?.channel ?? '')
|
|
51
|
+
const groupId = String(group?.id ?? '')
|
|
52
|
+
const key = groupId.startsWith(`${channel}:`) ? groupId.slice(channel.length + 1) : groupId
|
|
53
|
+
// The payload is directly executable against POST /action:
|
|
54
|
+
// {kind:'group', channel, group, enabled} — plus the semantic key/op the
|
|
55
|
+
// panel uses to build its own one-click button.
|
|
56
|
+
return { kind: 'switch-group', payload: { channel, group: groupId, key, enabled: false, op: 'off' } }
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function topSavableGroup(groups) {
|
|
60
|
+
return groups
|
|
61
|
+
.filter((group) => num(group?.savableTokens) > 0)
|
|
62
|
+
.slice()
|
|
63
|
+
.sort((left, right) => num(right.tokens) - num(left.tokens))[0]
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Build the complete health report for one snapshot.
|
|
68
|
+
* @returns {{summary:{high:number,warn:number,info:number,checkedAt:number|null},checks:Array<object>}}
|
|
69
|
+
*/
|
|
70
|
+
export function buildHealth(snapshot) {
|
|
71
|
+
const checks = []
|
|
72
|
+
if (snapshot === null || typeof snapshot !== 'object') {
|
|
73
|
+
return { summary: { high: 0, warn: 0, info: 0, checkedAt: null }, checks }
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const totals = snapshot.totals ?? {}
|
|
77
|
+
const total = Math.max(0, num(totals.tokens))
|
|
78
|
+
const items = Array.isArray(snapshot.items) ? snapshot.items : []
|
|
79
|
+
const groups = Array.isArray(snapshot.groups) ? snapshot.groups : []
|
|
80
|
+
const policy = snapshot.policy ?? {}
|
|
81
|
+
const context = snapshot.context ?? {}
|
|
82
|
+
const skills = snapshot.skillsState ?? {}
|
|
83
|
+
const preview = policy.preview ?? {}
|
|
84
|
+
|
|
85
|
+
// heavy-suite: one suite carrying a quarter of the request, or 30k token.
|
|
86
|
+
const heavy = groups
|
|
87
|
+
.filter((group) => num(group?.savableTokens) > 0)
|
|
88
|
+
.map((group) => ({ group, share: percent(num(group.tokens), Math.max(1, total)) }))
|
|
89
|
+
.filter((entry) => entry.share >= HEAVY_SHARE || num(entry.group.tokens) >= HEAVY_TOKENS)
|
|
90
|
+
.sort((left, right) => num(right.group.tokens) - num(left.group.tokens))
|
|
91
|
+
.slice(0, HEAVY_MAX_CHECKS)
|
|
92
|
+
for (const entry of heavy) {
|
|
93
|
+
const group = entry.group
|
|
94
|
+
checks.push({
|
|
95
|
+
code: 'heavy-suite',
|
|
96
|
+
severity: entry.share >= 50 || num(group.tokens) >= 60000 ? 'high' : 'warn',
|
|
97
|
+
params: {
|
|
98
|
+
label: String(group.label ?? group.id ?? ''),
|
|
99
|
+
tokens: num(group.tokens),
|
|
100
|
+
share: entry.share,
|
|
101
|
+
count: num(group.count),
|
|
102
|
+
channel: String(group.channel ?? ''),
|
|
103
|
+
},
|
|
104
|
+
action: groupAction(group),
|
|
105
|
+
})
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
// budget-gap: the saved policy's projection does not fit the saved budget.
|
|
109
|
+
const budget = num(policy.budget?.tokens)
|
|
110
|
+
const projected = num(preview.after)
|
|
111
|
+
if (budget > 0 && projected > budget) {
|
|
112
|
+
const gap = projected - budget
|
|
113
|
+
const suggestion = topSavableGroup(groups)
|
|
114
|
+
checks.push({
|
|
115
|
+
code: 'budget-gap',
|
|
116
|
+
severity: projected >= budget * 2 ? 'high' : 'warn',
|
|
117
|
+
params: {
|
|
118
|
+
current: projected,
|
|
119
|
+
target: budget,
|
|
120
|
+
gap,
|
|
121
|
+
// The locale copy for budget-gap interpolates {tokens}; keep this field
|
|
122
|
+
// alongside the structured gap so the panel never renders "— tokens".
|
|
123
|
+
tokens: gap,
|
|
124
|
+
share: percent(gap, Math.max(1, projected)),
|
|
125
|
+
...(suggestion === undefined
|
|
126
|
+
? {}
|
|
127
|
+
: {
|
|
128
|
+
suggestion: {
|
|
129
|
+
label: String(suggestion.label ?? suggestion.id ?? ''),
|
|
130
|
+
tokens: num(suggestion.savableTokens),
|
|
131
|
+
channel: String(suggestion.channel ?? ''),
|
|
132
|
+
group: String(suggestion.id ?? ''),
|
|
133
|
+
},
|
|
134
|
+
}),
|
|
135
|
+
},
|
|
136
|
+
action:
|
|
137
|
+
suggestion === undefined
|
|
138
|
+
? { kind: 'set-budget', payload: { tokens: projected } }
|
|
139
|
+
: groupAction(suggestion),
|
|
140
|
+
})
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
// catalog-truncated: the skill catalog cuts descriptions at 500 characters.
|
|
144
|
+
const truncatedCount = num(skills.truncated)
|
|
145
|
+
if (truncatedCount > 0) {
|
|
146
|
+
const sample = items.find((item) => item?.channel === 'skills' && item?.truncated === true)
|
|
147
|
+
checks.push({
|
|
148
|
+
code: 'catalog-truncated',
|
|
149
|
+
severity: 'info',
|
|
150
|
+
params: { count: truncatedCount, limit: 500 },
|
|
151
|
+
...(sample === undefined
|
|
152
|
+
? {}
|
|
153
|
+
: { action: { kind: 'open-content', payload: { channel: 'skills', id: String(sample.id ?? '') } } }),
|
|
154
|
+
})
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
// locked-items: what cannot be switched off at all.
|
|
158
|
+
const locks = Array.isArray(snapshot.locks) ? snapshot.locks : []
|
|
159
|
+
const lockedTokens = locks.reduce((sum, lock) => sum + num(lock?.tokens), 0)
|
|
160
|
+
const lockedShare = percent(lockedTokens, Math.max(1, total))
|
|
161
|
+
if (locks.length > 0 && lockedShare >= LOCKED_SHARE) {
|
|
162
|
+
checks.push({
|
|
163
|
+
code: 'locked-items',
|
|
164
|
+
severity: lockedShare >= LOCKED_WARN_SHARE ? 'warn' : 'info',
|
|
165
|
+
params: { count: locks.length, tokens: lockedTokens, share: lockedShare },
|
|
166
|
+
action: { kind: 'open-tab', payload: { tab: 'manage' } },
|
|
167
|
+
})
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
// unknown-window: without a denominator, occupancy percentages are unknowable.
|
|
171
|
+
if (context.window === null || context.window === undefined) {
|
|
172
|
+
checks.push({
|
|
173
|
+
code: 'unknown-window',
|
|
174
|
+
severity: 'info',
|
|
175
|
+
params: { used: context.used === null || context.used === undefined ? null : num(context.used) },
|
|
176
|
+
})
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
// no-policy: this workspace still has everything on and never saved a policy.
|
|
180
|
+
const savable = num(totals.savableTokens)
|
|
181
|
+
if (policy.exists !== true && policy.preset === 'all' && savable > 0) {
|
|
182
|
+
checks.push({
|
|
183
|
+
code: 'no-policy',
|
|
184
|
+
severity: 'info',
|
|
185
|
+
params: { savableTokens: savable, manageable: items.filter((item) => item?.locked !== true).length },
|
|
186
|
+
action: { kind: 'open-tab', payload: { tab: 'settings' } },
|
|
187
|
+
})
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// empty-catalog: a complete skill catalog with zero entries.
|
|
191
|
+
if (num(skills.total) === 0 && skills.complete === true) {
|
|
192
|
+
checks.push({
|
|
193
|
+
code: 'empty-catalog',
|
|
194
|
+
severity: 'info',
|
|
195
|
+
params: { complete: true },
|
|
196
|
+
action: { kind: 'open-tab', payload: { tab: 'settings' } },
|
|
197
|
+
})
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
checks.sort(
|
|
201
|
+
(left, right) =>
|
|
202
|
+
(SEVERITY_ORDER[left.severity] ?? 9) - (SEVERITY_ORDER[right.severity] ?? 9) ||
|
|
203
|
+
num(right.params?.tokens) - num(left.params?.tokens) ||
|
|
204
|
+
String(left.code).localeCompare(String(right.code)),
|
|
205
|
+
)
|
|
206
|
+
|
|
207
|
+
const summary = { high: 0, warn: 0, info: 0, checkedAt: num(snapshot.generatedAt) || null }
|
|
208
|
+
for (const check of checks) summary[check.severity] += 1
|
|
209
|
+
return { summary, checks }
|
|
210
|
+
}
|
package/lib/pressure.js
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
// How full the context window is, read from the host instead of guessed.
|
|
2
|
+
//
|
|
3
|
+
// The harness already measures every request: `ctx.tokenMeter` folds the
|
|
4
|
+
// durable log into a provider-reported pressure number plus the capacity of the
|
|
5
|
+
// route that will answer, and the `contextBreakdown` projection splits the
|
|
6
|
+
// surviving surface into system / tools / messages. This plugin owned a
|
|
7
|
+
// numerator before (an "anchor" of what the session already costs) and no
|
|
8
|
+
// denominator, which is why every question about a number ended in "compare it
|
|
9
|
+
// with something else". This module supplies the denominator.
|
|
10
|
+
//
|
|
11
|
+
// Nothing here estimates a token. Every field is either the host's own number
|
|
12
|
+
// or null; the panel prints "—" rather than inventing a fallback.
|
|
13
|
+
import { percent } from './measure.js'
|
|
14
|
+
|
|
15
|
+
export const EMPTY_CONTEXT = {
|
|
16
|
+
window: null,
|
|
17
|
+
windowSource: null,
|
|
18
|
+
pressure: null,
|
|
19
|
+
projected: null,
|
|
20
|
+
used: null,
|
|
21
|
+
occupancy: null,
|
|
22
|
+
remaining: null,
|
|
23
|
+
breakdown: null,
|
|
24
|
+
source: 'none',
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const positive = (value) => (Number.isFinite(value) && value > 0 ? Math.round(value) : null)
|
|
28
|
+
|
|
29
|
+
// Adapter capacity is an async call into the provider registration; the answer
|
|
30
|
+
// for one route never changes within a process, so one small cache is enough.
|
|
31
|
+
const windowCache = new Map()
|
|
32
|
+
const WINDOW_CACHE_LIMIT = 32
|
|
33
|
+
|
|
34
|
+
function breakdownOf(values) {
|
|
35
|
+
const raw = values === undefined || values === null ? undefined : values.contextBreakdown
|
|
36
|
+
if (raw === undefined || raw === null) return null
|
|
37
|
+
const system = Math.max(0, Math.round(Number(raw.systemTokens) || 0))
|
|
38
|
+
const tools = Math.max(0, Math.round(Number(raw.toolsTokens) || 0))
|
|
39
|
+
const messages = Math.max(0, Math.round(Number(raw.messageTokens) || 0))
|
|
40
|
+
const total = system + tools + messages
|
|
41
|
+
if (total <= 0) return null
|
|
42
|
+
return { system, tools, messages, total }
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The route the session will actually call, when one is already recorded. */
|
|
46
|
+
function routeOf(session) {
|
|
47
|
+
try {
|
|
48
|
+
const header = typeof session.requestHeader === 'function' ? session.requestHeader() : undefined
|
|
49
|
+
const config = header === undefined || header === null ? undefined : header.config
|
|
50
|
+
if (config === undefined || config === null) return null
|
|
51
|
+
const provider = typeof config.provider === 'string' ? config.provider : ''
|
|
52
|
+
const model = typeof config.model === 'string' ? config.model : ''
|
|
53
|
+
if (provider === '' || model === '') return null
|
|
54
|
+
return { provider, model }
|
|
55
|
+
} catch {
|
|
56
|
+
return null
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
async function capacityOf(ctx, session, signal) {
|
|
61
|
+
const route = routeOf(session)
|
|
62
|
+
if (route === null) return null
|
|
63
|
+
const key = `${route.provider}/${route.model}`
|
|
64
|
+
if (windowCache.has(key)) return windowCache.get(key)
|
|
65
|
+
const llm = ctx.get('llm')
|
|
66
|
+
if (llm === undefined || llm === null || typeof llm.resolveModelInfo !== 'function') return null
|
|
67
|
+
let window = null
|
|
68
|
+
try {
|
|
69
|
+
const options = signal === undefined ? [route.provider, route.model] : [route.provider, route.model, signal]
|
|
70
|
+
const info = await llm.resolveModelInfo(...options)
|
|
71
|
+
window = positive(info?.context?.contextWindow)
|
|
72
|
+
} catch {
|
|
73
|
+
return null
|
|
74
|
+
}
|
|
75
|
+
windowCache.set(key, window)
|
|
76
|
+
if (windowCache.size > WINDOW_CACHE_LIMIT) {
|
|
77
|
+
const oldest = windowCache.keys().next()
|
|
78
|
+
if (!oldest.done) windowCache.delete(oldest.value)
|
|
79
|
+
}
|
|
80
|
+
return window
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* One synchronous read of the host's context measurement.
|
|
85
|
+
*
|
|
86
|
+
* `used` is what the NEXT request is expected to carry: the last provider
|
|
87
|
+
* sample moved by whatever entered or left the surface since. `occupancy` is
|
|
88
|
+
* the only place this plugin divides by the window, so the panel, the tool card
|
|
89
|
+
* and the dock chip cannot disagree about the percentage.
|
|
90
|
+
*/
|
|
91
|
+
export async function readContext(ctx, agent, signal) {
|
|
92
|
+
const session = agent?.session
|
|
93
|
+
if (session === undefined || session === null) return { ...EMPTY_CONTEXT }
|
|
94
|
+
|
|
95
|
+
const result = { ...EMPTY_CONTEXT, windowSource: null }
|
|
96
|
+
const meter = ctx.get('tokenMeter')
|
|
97
|
+
if (meter !== undefined && meter !== null && typeof meter.contextPressure === 'function') {
|
|
98
|
+
try {
|
|
99
|
+
const pressure = meter.contextPressure(session) ?? {}
|
|
100
|
+
result.window = positive(pressure.contextWindow)
|
|
101
|
+
if (result.window !== null) result.windowSource = 'projection'
|
|
102
|
+
result.pressure = positive(pressure.pressureTokens)
|
|
103
|
+
result.projected = positive(pressure.projectedTokens)
|
|
104
|
+
result.used = result.projected ?? result.pressure
|
|
105
|
+
if (result.window !== null || result.used !== null) result.source = 'tokenMeter'
|
|
106
|
+
} catch {
|
|
107
|
+
/* a host without the projection keeps the nulls */
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const projections = ctx.get('sessionProjections')
|
|
112
|
+
if (projections !== undefined && projections !== null && typeof projections.snapshot === 'function') {
|
|
113
|
+
try {
|
|
114
|
+
const cut = projections.snapshot(session)
|
|
115
|
+
result.breakdown = breakdownOf(cut === null || cut === undefined ? undefined : cut.values)
|
|
116
|
+
} catch {
|
|
117
|
+
/* composition is optional; the totals still stand */
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
if (result.window === null) {
|
|
122
|
+
result.window = await capacityOf(ctx, session, signal)
|
|
123
|
+
if (result.window !== null) result.windowSource = 'llm'
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
if (result.window !== null && result.used !== null) {
|
|
127
|
+
result.occupancy = percent(result.used, result.window)
|
|
128
|
+
result.remaining = Math.max(0, result.window - result.used)
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
return result
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Threshold buckets the panel colours: comfortable, tight, about to compact. */
|
|
135
|
+
export function occupancyTone(context) {
|
|
136
|
+
const value = context === undefined || context === null ? null : context.occupancy
|
|
137
|
+
if (!Number.isFinite(value)) return 'unknown'
|
|
138
|
+
if (value >= 90) return 'danger'
|
|
139
|
+
if (value >= 70) return 'warn'
|
|
140
|
+
return 'ok'
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** Test hook: the adapter-capacity cache is per process, not per session. */
|
|
144
|
+
export function resetWindowCache() {
|
|
145
|
+
windowCache.clear()
|
|
146
|
+
}
|