dsh-context-truth 0.0.0-stage → 0.1.2
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 +29 -0
- package/LICENSE +21 -0
- package/README-en.md +137 -0
- package/README.md +144 -2
- package/cordis.patch.yml +27 -0
- package/lib/index.js +618 -0
- package/package.json +56 -4
- package/scripts/build.sh +18 -0
- package/test/index.test.js +331 -0
package/scripts/build.sh
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
#!/bin/bash
|
|
2
|
+
# dsh-context-truth ships no compilation step: lib/index.js is dependency-free ESM
|
|
3
|
+
# and is both the source and the runtime artifact. This script validates the entry
|
|
4
|
+
# and runs the suite, so the standard dev_build_plugin pipeline has something real
|
|
5
|
+
# to run — and fails loudly on a broken file.
|
|
6
|
+
set -euo pipefail
|
|
7
|
+
cd "$(cd "$(dirname "$0")/.." && pwd)"
|
|
8
|
+
|
|
9
|
+
node --input-type=module -e "
|
|
10
|
+
import { pathToFileURL } from 'node:url'
|
|
11
|
+
const m = await import(pathToFileURL('lib/index.js').href)
|
|
12
|
+
if (typeof m.name !== 'string' || m.name === '') throw new Error('name export missing')
|
|
13
|
+
if (!Array.isArray(m.inject)) throw new Error('inject export missing')
|
|
14
|
+
if (typeof m.apply !== 'function') throw new Error('apply export missing')
|
|
15
|
+
console.log('dsh-context-truth: lib/index.js OK — name=' + m.name + ' inject=' + m.inject.join(','))
|
|
16
|
+
"
|
|
17
|
+
|
|
18
|
+
node --test "test/*.test.js"
|
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
import assert from 'node:assert/strict'
|
|
2
|
+
import test from 'node:test'
|
|
3
|
+
|
|
4
|
+
import { apply, internals, name, inject, CONTEXT_NAME, VARIABLE_NAME } from '../lib/index.js'
|
|
5
|
+
|
|
6
|
+
const { resolveOptions, readOccupancy, settleBand, quantize, quantizeHeadroom, render, patchCompactionInstruction, patchCompactionRequest, isCompactionRequest, messageText, DEFAULT_OPTIONS } = internals
|
|
7
|
+
|
|
8
|
+
/** A 1M window reserving the DeepSeek adapter's default 256K completion tokens. */
|
|
9
|
+
const WINDOW = 1000000
|
|
10
|
+
const MAX_TOKENS = 256000
|
|
11
|
+
/** min(0.8 * 1M, 1M - 256K - 64K) — the compaction point this deployment runs at. */
|
|
12
|
+
const THRESHOLD = 678464
|
|
13
|
+
|
|
14
|
+
/** Minimal ctx capturing what the plugin registers. */
|
|
15
|
+
function stubContext({ used, meter, projections } = {}) {
|
|
16
|
+
const registered = { variable: undefined, context: undefined, listeners: {} }
|
|
17
|
+
const tokenMeter = meter === undefined ? { measure: () => ({ totalTokens: used }) } : meter
|
|
18
|
+
const ctx = {
|
|
19
|
+
logger: undefined,
|
|
20
|
+
get: (key) => {
|
|
21
|
+
if (key === 'tokenMeter') return tokenMeter
|
|
22
|
+
if (key === 'sessionProjections') return projections
|
|
23
|
+
return undefined
|
|
24
|
+
},
|
|
25
|
+
systemPrompt: {
|
|
26
|
+
variable: (variableName, provider) => {
|
|
27
|
+
registered.variable = { name: variableName, provider }
|
|
28
|
+
},
|
|
29
|
+
context: (contribution) => {
|
|
30
|
+
registered.context = contribution
|
|
31
|
+
},
|
|
32
|
+
},
|
|
33
|
+
on: (event, listener) => {
|
|
34
|
+
registered.listeners[event] = listener
|
|
35
|
+
},
|
|
36
|
+
}
|
|
37
|
+
return { ctx, registered }
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Minimal session exposing exactly the two readers the plugin uses. */
|
|
41
|
+
function stubSession({ window: contextWindow = WINDOW, maxTokens = MAX_TOKENS } = {}) {
|
|
42
|
+
return {
|
|
43
|
+
requestContext: () => ({ contextWindow }),
|
|
44
|
+
requestHeader: () => ({ config: { maxTokens } }),
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The dynamic line for one session, through the registered provider. */
|
|
49
|
+
function lineFor(registered, session) {
|
|
50
|
+
return registered.variable.provider({ agent: { session } })
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const INSTRUCTION = [
|
|
54
|
+
'You are now acting as a compaction engine for this AI coding assistant. Condense the conversation ABOVE.',
|
|
55
|
+
'',
|
|
56
|
+
'Rules:',
|
|
57
|
+
'- Output only the checkpoint text: do not call any tool or take any other action.',
|
|
58
|
+
].join('\n')
|
|
59
|
+
|
|
60
|
+
/** A request shaped like the one dsh-compaction-basic dispatches. */
|
|
61
|
+
function compactionRequest() {
|
|
62
|
+
return {
|
|
63
|
+
provider: 'deepseek-account',
|
|
64
|
+
model: 'deepseek-flash',
|
|
65
|
+
purpose: 'compaction',
|
|
66
|
+
messages: [
|
|
67
|
+
{ role: 'system', content: [{ type: 'text', text: 'system prompt' }] },
|
|
68
|
+
{ role: 'user', content: [{ type: 'text', text: 'earlier turn' }] },
|
|
69
|
+
{ role: 'user', content: [{ type: 'text', text: INSTRUCTION }] },
|
|
70
|
+
],
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
test('exports the cordis plugin shape', () => {
|
|
75
|
+
assert.equal(name, 'context-truth')
|
|
76
|
+
assert.deepEqual(inject, ['systemPrompt'])
|
|
77
|
+
assert.equal(typeof apply, 'function')
|
|
78
|
+
})
|
|
79
|
+
|
|
80
|
+
test('registers one variable, one ordered context, and the stream interceptor', () => {
|
|
81
|
+
const { ctx, registered } = stubContext({ used: 100000 })
|
|
82
|
+
apply(ctx, {})
|
|
83
|
+
assert.equal(registered.variable.name, VARIABLE_NAME)
|
|
84
|
+
assert.equal(registered.context.name, CONTEXT_NAME)
|
|
85
|
+
assert.equal(registered.context.text, `{{${VARIABLE_NAME}}}`)
|
|
86
|
+
assert.equal(registered.context.order, 100)
|
|
87
|
+
assert.equal(typeof registered.listeners['llm/stream'], 'function')
|
|
88
|
+
})
|
|
89
|
+
|
|
90
|
+
test('derives the compaction point the way dsh-compaction-basic does', () => {
|
|
91
|
+
const { ctx } = stubContext({ used: 170000 })
|
|
92
|
+
const reading = readOccupancy(ctx, stubSession(), resolveOptions({}))
|
|
93
|
+
assert.equal(reading.used, 170000)
|
|
94
|
+
assert.equal(reading.window, WINDOW)
|
|
95
|
+
assert.equal(reading.reserved, MAX_TOKENS)
|
|
96
|
+
assert.equal(reading.threshold, THRESHOLD)
|
|
97
|
+
})
|
|
98
|
+
|
|
99
|
+
test('a healthy session renders numbers, the compaction point, and the calm band', () => {
|
|
100
|
+
const { ctx, registered } = stubContext({ used: 172437 })
|
|
101
|
+
apply(ctx, {})
|
|
102
|
+
const line = lineFor(registered, stubSession())
|
|
103
|
+
assert.match(line, /Context occupancy \(host-measured\): 150K \/ 1\.00M tokens used \(15%\)/)
|
|
104
|
+
assert.match(line, /Automatic compaction fires at 678K \(68% of the window\)/)
|
|
105
|
+
assert.match(line, /About 500K tokens of headroom remain/)
|
|
106
|
+
assert.match(line, /Context is NOT scarce/)
|
|
107
|
+
assert.match(line, /only authority on context pressure/)
|
|
108
|
+
assert.match(line, /are stale/)
|
|
109
|
+
})
|
|
110
|
+
|
|
111
|
+
test('rising pressure moves the band; falling pressure needs the hysteresis margin', () => {
|
|
112
|
+
const options = resolveOptions({})
|
|
113
|
+
assert.equal(settleBand(0.2, undefined, options), 'ample')
|
|
114
|
+
assert.equal(settleBand(0.6, 'ample', options), 'moderate')
|
|
115
|
+
assert.equal(settleBand(0.9, 'moderate', options), 'tight')
|
|
116
|
+
assert.equal(settleBand(1.05, 'tight', options), 'critical')
|
|
117
|
+
// Just under the compaction point stays critical: the drop is smaller than the margin.
|
|
118
|
+
assert.equal(settleBand(0.99, 'critical', options), 'critical')
|
|
119
|
+
// A compaction that actually lands falls clear of the floor and re-arms the calm band.
|
|
120
|
+
assert.equal(settleBand(0.1, 'critical', options), 'ample')
|
|
121
|
+
assert.equal(settleBand(0.52, 'moderate', options), 'moderate')
|
|
122
|
+
assert.equal(settleBand(0.4, 'moderate', options), 'ample')
|
|
123
|
+
})
|
|
124
|
+
|
|
125
|
+
test('quantization makes nearby readings byte-identical and steps coarsely', () => {
|
|
126
|
+
const options = resolveOptions({})
|
|
127
|
+
// 5% of a 1M window: the display bucket is [150000, 200000).
|
|
128
|
+
assert.equal(quantize(172437, WINDOW, options), 150000)
|
|
129
|
+
assert.equal(quantize(199999, WINDOW, options), 150000)
|
|
130
|
+
assert.equal(quantize(200001, WINDOW, options), 200000)
|
|
131
|
+
|
|
132
|
+
const { ctx, registered } = stubContext({ used: 172437 })
|
|
133
|
+
apply(ctx, {})
|
|
134
|
+
const session = stubSession()
|
|
135
|
+
const first = lineFor(registered, session)
|
|
136
|
+
ctx.get = (key) => (key === 'tokenMeter' ? { measure: () => ({ totalTokens: 172500 }) } : undefined)
|
|
137
|
+
const second = lineFor(registered, session)
|
|
138
|
+
assert.equal(first, second, 'a reading inside the same display step must not change the rendered snapshot')
|
|
139
|
+
ctx.get = (key) => (key === 'tokenMeter' ? { measure: () => ({ totalTokens: 223000 }) } : undefined)
|
|
140
|
+
assert.notEqual(lineFor(registered, session), second, 'crossing a display step must change it')
|
|
141
|
+
})
|
|
142
|
+
|
|
143
|
+
test('the displayed headroom never promises more room than the session has', () => {
|
|
144
|
+
const options = resolveOptions({})
|
|
145
|
+
for (const used of [172437, 400000, 600000, 610000, 650000, 670000, 678463]) {
|
|
146
|
+
const headroom = THRESHOLD - used
|
|
147
|
+
const shown = quantizeHeadroom(headroom, WINDOW, options)
|
|
148
|
+
assert.ok(shown <= headroom, `shown ${shown} must not exceed the real ${headroom}`)
|
|
149
|
+
assert.ok(headroom - shown < 50000, `shown ${shown} must stay useful against ${headroom}`)
|
|
150
|
+
}
|
|
151
|
+
// Near the compaction point the step tightens, so the number stays actionable.
|
|
152
|
+
for (const headroom of [120000, 65000, 28464, 8464]) {
|
|
153
|
+
const shown = quantizeHeadroom(headroom, WINDOW, options)
|
|
154
|
+
assert.ok(headroom - shown < 12000, `shown ${shown} must be tight against ${headroom}`)
|
|
155
|
+
}
|
|
156
|
+
// The step coarsens as the room grows, which is what keeps re-injection rare.
|
|
157
|
+
assert.equal(quantizeHeadroom(THRESHOLD - 172437, WINDOW, options), 500000)
|
|
158
|
+
assert.equal(quantizeHeadroom(THRESHOLD - 610000, WINDOW, options), 65000)
|
|
159
|
+
})
|
|
160
|
+
|
|
161
|
+
test('the tight band drops the calm language and names the small headroom', () => {
|
|
162
|
+
const { ctx, registered } = stubContext({ used: 610000 })
|
|
163
|
+
apply(ctx, {})
|
|
164
|
+
const line = lineFor(registered, stubSession())
|
|
165
|
+
assert.match(line, /Headroom is genuinely small/)
|
|
166
|
+
assert.doesNotMatch(line, /Context is NOT scarce/)
|
|
167
|
+
assert.match(line, /About 65K tokens of headroom remain/)
|
|
168
|
+
})
|
|
169
|
+
|
|
170
|
+
test('over the compaction point the line stops promising headroom', () => {
|
|
171
|
+
const { ctx, registered } = stubContext({ used: 700000 })
|
|
172
|
+
apply(ctx, {})
|
|
173
|
+
const line = lineFor(registered, stubSession())
|
|
174
|
+
assert.match(line, /At or past the automatic compaction point/)
|
|
175
|
+
})
|
|
176
|
+
|
|
177
|
+
test('a broken meter degrades to the fallback text instead of throwing', () => {
|
|
178
|
+
const { ctx, registered } = stubContext({
|
|
179
|
+
meter: {
|
|
180
|
+
measure: () => {
|
|
181
|
+
throw new Error('meter replay is corrupt')
|
|
182
|
+
},
|
|
183
|
+
},
|
|
184
|
+
})
|
|
185
|
+
apply(ctx, {})
|
|
186
|
+
const line = lineFor(registered, stubSession())
|
|
187
|
+
assert.match(line, /no reading yet in this session/)
|
|
188
|
+
assert.match(line, /Do not claim context is scarce/)
|
|
189
|
+
})
|
|
190
|
+
|
|
191
|
+
test('the provider-reported projection is the fallback when the meter is absent', () => {
|
|
192
|
+
const { ctx } = stubContext({
|
|
193
|
+
meter: undefined,
|
|
194
|
+
projections: {
|
|
195
|
+
stateOf: () => ({ contextWindow: WINDOW, pressureTokens: 100000, surfaceTokens: 70000, sampledSurfaceTokens: 50000 }),
|
|
196
|
+
},
|
|
197
|
+
})
|
|
198
|
+
const reading = readOccupancy(ctx, stubSession(), resolveOptions({}))
|
|
199
|
+
assert.equal(reading.used, 120000)
|
|
200
|
+
assert.equal(reading.window, WINDOW)
|
|
201
|
+
})
|
|
202
|
+
|
|
203
|
+
test('a missing window still renders a usable line', () => {
|
|
204
|
+
const { ctx, registered } = stubContext({ used: 5000 })
|
|
205
|
+
apply(ctx, {})
|
|
206
|
+
const line = lineFor(registered, { requestContext: () => ({}), requestHeader: () => undefined })
|
|
207
|
+
assert.match(line, /no reading yet in this session/)
|
|
208
|
+
})
|
|
209
|
+
|
|
210
|
+
test('language and switches are honoured', () => {
|
|
211
|
+
const options = resolveOptions({ language: 'zh', staleClaimClause: false, authoritative: false })
|
|
212
|
+
const rendered = render('ample', { quantized: 150000, window: WINDOW, threshold: THRESHOLD, percent: 15 }, options)
|
|
213
|
+
assert.match(rendered, /上下文实况(宿主实测)/)
|
|
214
|
+
assert.doesNotMatch(rendered, /唯一权威/)
|
|
215
|
+
assert.doesNotMatch(rendered, /作废/)
|
|
216
|
+
})
|
|
217
|
+
|
|
218
|
+
test('disabled mounts nothing at all', () => {
|
|
219
|
+
const { ctx, registered } = stubContext({ used: 1000 })
|
|
220
|
+
apply(ctx, { enabled: false, patchCompactionPrompt: false })
|
|
221
|
+
assert.equal(registered.variable, undefined)
|
|
222
|
+
assert.equal(registered.context, undefined)
|
|
223
|
+
assert.equal(registered.listeners['llm/stream'], undefined)
|
|
224
|
+
})
|
|
225
|
+
|
|
226
|
+
test('a second mount in the same scope stays inert instead of failing', () => {
|
|
227
|
+
let variableCalls = 0
|
|
228
|
+
let listenerCalls = 0
|
|
229
|
+
const ctx = {
|
|
230
|
+
logger: undefined,
|
|
231
|
+
get: () => undefined,
|
|
232
|
+
systemPrompt: {
|
|
233
|
+
variable: () => {
|
|
234
|
+
variableCalls += 1
|
|
235
|
+
throw new Error('prompt variable "context_occupancy" is already registered')
|
|
236
|
+
},
|
|
237
|
+
context: () => {
|
|
238
|
+
throw new Error('unreachable')
|
|
239
|
+
},
|
|
240
|
+
},
|
|
241
|
+
on: () => {
|
|
242
|
+
listenerCalls += 1
|
|
243
|
+
},
|
|
244
|
+
}
|
|
245
|
+
assert.doesNotThrow(() => apply(ctx, {}))
|
|
246
|
+
assert.equal(variableCalls, 1, 'the duplicate mount tries exactly once')
|
|
247
|
+
assert.equal(listenerCalls, 0, 'the inert instance installs no interceptor')
|
|
248
|
+
})
|
|
249
|
+
|
|
250
|
+
test('an unrelated registration failure still surfaces', () => {
|
|
251
|
+
const ctx = {
|
|
252
|
+
logger: undefined,
|
|
253
|
+
get: () => undefined,
|
|
254
|
+
systemPrompt: {
|
|
255
|
+
variable: () => {
|
|
256
|
+
throw new Error('prompt variable name is invalid')
|
|
257
|
+
},
|
|
258
|
+
context: () => {},
|
|
259
|
+
},
|
|
260
|
+
on: () => {},
|
|
261
|
+
}
|
|
262
|
+
assert.throws(() => apply(ctx, {}), /name is invalid/)
|
|
263
|
+
})
|
|
264
|
+
|
|
265
|
+
test('the compaction directive gains the rules and keeps its own text intact', () => {
|
|
266
|
+
const rules = resolveOptions({}).compactionRules
|
|
267
|
+
const patched = patchCompactionInstruction(INSTRUCTION, rules)
|
|
268
|
+
assert.ok(patched.startsWith(INSTRUCTION), 'the original directive must be preserved verbatim')
|
|
269
|
+
assert.ok(patched.includes(rules[0]))
|
|
270
|
+
assert.ok(patched.includes(rules[1]))
|
|
271
|
+
assert.equal(patchCompactionInstruction(patched, rules), undefined, 'patching twice must be a no-op')
|
|
272
|
+
assert.equal(patchCompactionInstruction('an ordinary user message', rules), undefined)
|
|
273
|
+
assert.equal(patchCompactionInstruction(INSTRUCTION, []), undefined)
|
|
274
|
+
})
|
|
275
|
+
|
|
276
|
+
test('only the compaction request is recognised, and only its tail changes', () => {
|
|
277
|
+
const rules = resolveOptions({}).compactionRules
|
|
278
|
+
const request = compactionRequest()
|
|
279
|
+
const prefixBefore = JSON.stringify(request.messages.slice(0, -1))
|
|
280
|
+
|
|
281
|
+
assert.equal(isCompactionRequest(request), true)
|
|
282
|
+
assert.equal(patchCompactionRequest(request, rules), true)
|
|
283
|
+
assert.equal(JSON.stringify(request.messages.slice(0, -1)), prefixBefore, 'the cached prefix must stay byte-identical')
|
|
284
|
+
assert.ok(messageText(request.messages.at(-1)).includes(rules[0]))
|
|
285
|
+
assert.equal(patchCompactionRequest(request, rules), true, 'a second pass reports success without re-patching')
|
|
286
|
+
assert.equal(request.messages.at(-1).content[0].text.split(rules[0]).length - 1, 1, 'rules appear exactly once')
|
|
287
|
+
|
|
288
|
+
const normal = { purpose: 'agent', messages: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }] }
|
|
289
|
+
assert.equal(isCompactionRequest(normal), false)
|
|
290
|
+
assert.equal(patchCompactionRequest(normal, rules), false)
|
|
291
|
+
assert.equal(normal.messages.length, 1)
|
|
292
|
+
})
|
|
293
|
+
|
|
294
|
+
test('an immutable envelope is reported as unpatched rather than throwing', () => {
|
|
295
|
+
const rules = resolveOptions({}).compactionRules
|
|
296
|
+
const frozen = Object.freeze(compactionRequest())
|
|
297
|
+
assert.equal(patchCompactionRequest(frozen, rules), false)
|
|
298
|
+
assert.equal(isCompactionRequest(frozen), true, 'detection still works, so the listener can warn once')
|
|
299
|
+
})
|
|
300
|
+
|
|
301
|
+
test('the interceptor patches through the waterfall and always calls next', () => {
|
|
302
|
+
const { ctx, registered } = stubContext({ used: 100000 })
|
|
303
|
+
apply(ctx, {})
|
|
304
|
+
const request = compactionRequest()
|
|
305
|
+
let called = 0
|
|
306
|
+
const result = registered.listeners['llm/stream'](request, () => {
|
|
307
|
+
called += 1
|
|
308
|
+
return 'stream'
|
|
309
|
+
})
|
|
310
|
+
assert.equal(called, 1)
|
|
311
|
+
assert.equal(result, 'stream')
|
|
312
|
+
assert.ok(messageText(request.messages.at(-1)).includes(DEFAULT_OPTIONS.compactionRules[0]))
|
|
313
|
+
|
|
314
|
+
// A non-compaction request passes through untouched.
|
|
315
|
+
const normal = { purpose: 'agent', messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }] }
|
|
316
|
+
registered.listeners['llm/stream'](normal, () => 'stream')
|
|
317
|
+
assert.equal(messageText(normal.messages.at(-1)), 'hi')
|
|
318
|
+
})
|
|
319
|
+
|
|
320
|
+
test('the rules can be replaced or switched off', () => {
|
|
321
|
+
const custom = resolveOptions({ compactionRules: ['- Custom rule.'] })
|
|
322
|
+
assert.deepEqual(custom.compactionRules, ['- Custom rule.'])
|
|
323
|
+
const request = compactionRequest()
|
|
324
|
+
assert.equal(patchCompactionRequest(request, custom.compactionRules), true)
|
|
325
|
+
assert.ok(messageText(request.messages.at(-1)).includes('- Custom rule.'))
|
|
326
|
+
|
|
327
|
+
const { ctx, registered } = stubContext({ used: 1000 })
|
|
328
|
+
apply(ctx, { patchCompactionPrompt: false })
|
|
329
|
+
assert.equal(registered.listeners['llm/stream'], undefined)
|
|
330
|
+
assert.ok(registered.variable, 'the measured line stays installed')
|
|
331
|
+
})
|