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
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
+ }
@@ -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
+ }