dsh-context-truth 0.1.3 → 0.2.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 +186 -0
- package/README-en.md +68 -5
- package/README.md +123 -5
- package/lib/index.js +795 -39
- package/package.json +9 -1
- package/test/index.test.js +718 -25
package/lib/index.js
CHANGED
|
@@ -53,10 +53,16 @@
|
|
|
53
53
|
* point is derived the way `dsh-compaction-basic` derives it:
|
|
54
54
|
* `min(window * thresholdRatio, window - reservedCompletion - headroom)`.
|
|
55
55
|
*
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
* It is
|
|
56
|
+
* ONE PEER IMPORT, STILL NO BUILD: the sole import is
|
|
57
|
+
* `@deepseek-ai/schemastery` — the host's own schema package, declared as a peer
|
|
58
|
+
* dependency. It is published on npm, so npm installs it with the plugin, and
|
|
59
|
+
* the host that runs the plugin already ships it. It exists only so the settings
|
|
60
|
+
* page can render a form for the options below: the host reads a plugin's form
|
|
61
|
+
* from `fiber.runtime.Config`, and only a real schema (something with `toJSON`)
|
|
62
|
+
* is accepted. Everything else stays dependency-free ESM, and this file is both
|
|
63
|
+
* the source and the runtime artifact (`lib/index.js`).
|
|
59
64
|
*/
|
|
65
|
+
import z from '@deepseek-ai/schemastery'
|
|
60
66
|
|
|
61
67
|
/** Stable cordis plugin name (loader diagnostics, and the runtime-context section name). */
|
|
62
68
|
export const name = 'context-truth'
|
|
@@ -67,8 +73,22 @@ export const CONTEXT_NAME = 'context-truth'
|
|
|
67
73
|
/** Prompt variable carrying the rendered line. */
|
|
68
74
|
export const VARIABLE_NAME = 'context_occupancy'
|
|
69
75
|
|
|
70
|
-
/**
|
|
71
|
-
|
|
76
|
+
/**
|
|
77
|
+
* Services that must be wired before this plugin can act.
|
|
78
|
+
*
|
|
79
|
+
* `systemPrompt` carries the line and `tokenMeter` supplies the authoritative
|
|
80
|
+
* reading; both resolve in a plugin context.
|
|
81
|
+
*
|
|
82
|
+
* `compaction` IS DELIBERATELY ABSENT. Declaring it left this entry `pending
|
|
83
|
+
* (waiting for service: compaction)` forever — the plugin stopped loading
|
|
84
|
+
* entirely, taking the occupancy line with it — because in this build the
|
|
85
|
+
* compaction engine is provided inside a scope no plugin context can reach.
|
|
86
|
+
* Probed live: `ctx.get`, `ctx.reflect.get(name, false)`, `ctx.compaction` and
|
|
87
|
+
* even a running `agent.ctx` all return nothing for `compaction`, while
|
|
88
|
+
* `tokenMeter` resolves on all of them. See `installIdleFold` for what that means
|
|
89
|
+
* for capability 3.
|
|
90
|
+
*/
|
|
91
|
+
export const inject = ['systemPrompt', 'tokenMeter']
|
|
72
92
|
|
|
73
93
|
/** Orders the line first inside the runtime-context block (sandbox is 110, approval 115). */
|
|
74
94
|
const DEFAULT_ORDER = 100
|
|
@@ -99,10 +119,17 @@ const DEFAULT_OPTIONS = {
|
|
|
99
119
|
/** Emit the auto-compaction point and the headroom left before it. */
|
|
100
120
|
showAutoCompactionPoint: true,
|
|
101
121
|
/**
|
|
102
|
-
* Mirror of
|
|
103
|
-
* compaction config; the line only reports the point, it never
|
|
122
|
+
* Mirror of the mounted compaction backend's policy. Keep these equal to the
|
|
123
|
+
* profile's compaction config; the line only reports the point, it never
|
|
124
|
+
* enforces it.
|
|
125
|
+
*
|
|
126
|
+
* 0.7 rather than upstream's 0.8 because this profile runs `@aiwayds/dsh-dcp`,
|
|
127
|
+
* whose bundle sets `thresholdRatio: 0.7` (verified against the live engine:
|
|
128
|
+
* thresholdRatio=0.7, headroomTokens=65536, retainRatio=0.16). The displayed
|
|
129
|
+
* point is unchanged either way — the budget term binds at 678,464 — but the
|
|
130
|
+
* mirror must match for the case where it does not.
|
|
104
131
|
*/
|
|
105
|
-
thresholdRatio: 0.
|
|
132
|
+
thresholdRatio: 0.7,
|
|
106
133
|
headroomTokens: 65536,
|
|
107
134
|
/** Reserved completion tokens; `null` reads the routed request's own maxTokens. */
|
|
108
135
|
reservedCompletionTokens: null,
|
|
@@ -111,6 +138,13 @@ const DEFAULT_OPTIONS = {
|
|
|
111
138
|
tightAt: 0.85,
|
|
112
139
|
/** Fraction of the compaction point a reading must fall back below to leave a band. */
|
|
113
140
|
hysteresis: 0.05,
|
|
141
|
+
/**
|
|
142
|
+
* Closing sentence of the `tight` band. `none` (default) lets the numbers speak
|
|
143
|
+
* and leaves the decision to the model; `inform` states what the fold costs;
|
|
144
|
+
* `stop` restores the 0.1.3 imperative that told it to finish the step and
|
|
145
|
+
* hand off.
|
|
146
|
+
*/
|
|
147
|
+
tightAdvice: 'none',
|
|
114
148
|
/**
|
|
115
149
|
* Display quantum as a percentage of the window. The rendered text changes
|
|
116
150
|
* only when the reading crosses a quantum, which is what keeps re-injection
|
|
@@ -118,27 +152,176 @@ const DEFAULT_OPTIONS = {
|
|
|
118
152
|
* snapshot would then be re-committed on every single step.
|
|
119
153
|
*/
|
|
120
154
|
quantumPercent: 5,
|
|
155
|
+
/**
|
|
156
|
+
* Translate the remaining headroom into this session's own pace ("~6 more
|
|
157
|
+
* steps"). Display-only: it never moves a band edge, the threshold, or the
|
|
158
|
+
* decision to fold. It needs the host's per-step counter (`agent.phase`); when
|
|
159
|
+
* that is absent the clause is omitted rather than guessed.
|
|
160
|
+
*/
|
|
161
|
+
paceEstimate: true,
|
|
162
|
+
/** Recent per-step deltas the estimate takes the median of. */
|
|
163
|
+
paceSamples: 16,
|
|
164
|
+
/** Samples required before any estimate is shown. */
|
|
165
|
+
paceMinSamples: 3,
|
|
166
|
+
/** Margin a higher rung must clear before the line promises more steps. */
|
|
167
|
+
paceMargin: 0.25,
|
|
121
168
|
/** Append the "this line is the only authority" clause. */
|
|
122
169
|
authoritative: true,
|
|
123
170
|
/** Add the explicit "earlier claims are stale" clause to the calm band. */
|
|
124
171
|
staleClaimClause: true,
|
|
172
|
+
/**
|
|
173
|
+
* Report how much of the window is still unused. This is the figure that
|
|
174
|
+
* answers "how much context do I have left" — the headroom figure answers
|
|
175
|
+
* "how far to the fold", and conflating them is what produced "Very low
|
|
176
|
+
* context" next to 350K of free window.
|
|
177
|
+
*/
|
|
178
|
+
freeClause: true,
|
|
179
|
+
/**
|
|
180
|
+
* Define what the fold is in the `tight` and `critical` bands. Without it the
|
|
181
|
+
* remaining-room figure reads as "context left" rather than "room before a
|
|
182
|
+
* routine reorganization", which is what a live model acted on.
|
|
183
|
+
*/
|
|
184
|
+
foldClause: true,
|
|
125
185
|
/** Log each band change through ctx.logger, when a logger is present. */
|
|
126
186
|
logBandChanges: true,
|
|
127
187
|
/** Append `compactionRules` to the summarizer directive. */
|
|
128
188
|
patchCompactionPrompt: true,
|
|
129
189
|
/** Rules appended to the summarizer directive; `[]` disables the append. */
|
|
130
190
|
compactionRules: DEFAULT_COMPACTION_RULES,
|
|
191
|
+
/**
|
|
192
|
+
* Fold at the idle boundary once the reading is within `foldAtIdleMarginPercent`
|
|
193
|
+
* of the compaction point.
|
|
194
|
+
*
|
|
195
|
+
* The host's automatic compaction is a *crossing* trigger, and the behaviour it
|
|
196
|
+
* produces near the point — batching, avoiding risky edits, stopping
|
|
197
|
+
* mid-iteration to commit WIP — is exactly what keeps the reading just below it.
|
|
198
|
+
* Measured on a live session: four hours with no fold, every turn two to eight
|
|
199
|
+
* steps long, and three consecutive "continue" instructions unable to finish one
|
|
200
|
+
* task. Folding at the model's own turn boundary breaks that loop, and the
|
|
201
|
+
* official engine only accepts `compactNow` while the agent is idle, which is
|
|
202
|
+
* precisely when this fires.
|
|
203
|
+
*
|
|
204
|
+
* Off by default: it spends a summarizer call and rewrites the window, which is
|
|
205
|
+
* a policy decision rather than telemetry.
|
|
206
|
+
*/
|
|
207
|
+
foldAtIdle: false,
|
|
208
|
+
/** Headroom, as a percent of the window, at or below which the idle fold fires. */
|
|
209
|
+
foldAtIdleMarginPercent: 5,
|
|
210
|
+
/**
|
|
211
|
+
* How the fold is requested.
|
|
212
|
+
*
|
|
213
|
+
* `command` (the preferred half of `auto`) runs the session's own `/compact`
|
|
214
|
+
* through the **agent's** command view, so the fold is executed by whichever
|
|
215
|
+
* backend that agent's realm mounts — the same engine a human's `/compact`
|
|
216
|
+
* reaches. That matters twice over: it is the only path that works on a stock
|
|
217
|
+
* deployment (upstream discussion 9425: a profile-scope plugin cannot inject a
|
|
218
|
+
* preset realm's `compaction` service), and it keeps the summary style
|
|
219
|
+
* consistent with the folds the session would get on its own.
|
|
220
|
+
*
|
|
221
|
+
* `service` calls `ctx.compaction.compactNow()` directly, which is all a
|
|
222
|
+
* same-scope provider needs (e.g. `@aiwayds/dsh-dcp`) and is the only option
|
|
223
|
+
* when the realm registers no `compact` command.
|
|
224
|
+
*
|
|
225
|
+
* `auto` tries the command first and falls back to the service.
|
|
226
|
+
*/
|
|
227
|
+
foldAtIdleMethod: 'auto',
|
|
228
|
+
/** Minimum gap between idle-fold attempts, so a failure cannot hammer the engine. */
|
|
229
|
+
foldAtIdleCooldownMs: 60000,
|
|
131
230
|
}
|
|
132
231
|
|
|
232
|
+
/**
|
|
233
|
+
* Settings schema. The host turns a plugin's `Config` into a form on the settings
|
|
234
|
+
* page and writes edits back into the profile patch, so every option is
|
|
235
|
+
* switchable without editing YAML. Defaults here mirror `DEFAULT_OPTIONS`;
|
|
236
|
+
* `resolveOptions` stays the only place that interprets them, so a value the form
|
|
237
|
+
* never writes behaves exactly like one it does.
|
|
238
|
+
*
|
|
239
|
+
* `.volatile()` ON EVERY FIELD (EXCEPT `enabled`) IS LOAD-BEARING. The settings
|
|
240
|
+
* service builds its form with `volatileForm(schema)`, which keeps only nodes
|
|
241
|
+
* marked volatile and drops the whole entry when nothing survives — a schema
|
|
242
|
+
* without a single marker renders **no form at all**, silently. Volatile is also
|
|
243
|
+
* the truth: the loader commits such a change straight into the running
|
|
244
|
+
* reference (`_commitVolatile`) instead of reloading the plugin, which is why
|
|
245
|
+
* `apply` reads its options through a resolver rather than a snapshot. `enabled`
|
|
246
|
+
* is deliberately left out: it decides whether the context line is registered at
|
|
247
|
+
* all, and the plugin list already carries an on/off switch for that.
|
|
248
|
+
*/
|
|
249
|
+
export const Config = z.object({
|
|
250
|
+
enabled: z.boolean().default(true),
|
|
251
|
+
order: z.number().default(DEFAULT_ORDER).volatile(),
|
|
252
|
+
language: z.string().default('en').volatile(),
|
|
253
|
+
showAutoCompactionPoint: z.boolean().default(true).volatile(),
|
|
254
|
+
thresholdRatio: z.number().default(0.7).volatile(),
|
|
255
|
+
headroomTokens: z.number().step(1).min(0).default(65536).volatile(),
|
|
256
|
+
reservedCompletionTokens: z.number().step(1).min(0).volatile(),
|
|
257
|
+
moderateAt: z.number().default(0.5).volatile(),
|
|
258
|
+
tightAt: z.number().default(0.85).volatile(),
|
|
259
|
+
hysteresis: z.number().min(0).default(0.05).volatile(),
|
|
260
|
+
tightAdvice: z.string().default('none').volatile(),
|
|
261
|
+
quantumPercent: z.number().min(0).default(5).volatile(),
|
|
262
|
+
paceEstimate: z.boolean().default(true).volatile(),
|
|
263
|
+
paceSamples: z.number().step(1).min(2).default(16).volatile(),
|
|
264
|
+
paceMinSamples: z.number().step(1).min(1).default(3).volatile(),
|
|
265
|
+
paceMargin: z.number().min(0).default(0.25).volatile(),
|
|
266
|
+
authoritative: z.boolean().default(true).volatile(),
|
|
267
|
+
staleClaimClause: z.boolean().default(true).volatile(),
|
|
268
|
+
freeClause: z.boolean().default(true).volatile(),
|
|
269
|
+
foldClause: z.boolean().default(true).volatile(),
|
|
270
|
+
logBandChanges: z.boolean().default(true).volatile(),
|
|
271
|
+
patchCompactionPrompt: z.boolean().default(true).volatile(),
|
|
272
|
+
// A field with no schema default is materialized as `[]`, and `[]` means "append
|
|
273
|
+
// nothing" here — so the default must carry the real rules, or merely adding the
|
|
274
|
+
// schema switches capability 2 off. Found live: the running config read
|
|
275
|
+
// `compactionRules: []` and the summarizer directive went unpatched.
|
|
276
|
+
compactionRules: z.array(z.string()).default(DEFAULT_COMPACTION_RULES).volatile(),
|
|
277
|
+
foldAtIdle: z.boolean().default(false).volatile(),
|
|
278
|
+
foldAtIdleMarginPercent: z.number().min(0.1).max(50).default(5).volatile(),
|
|
279
|
+
foldAtIdleMethod: z.string().default('auto').volatile(),
|
|
280
|
+
foldAtIdleCooldownMs: z.number().step(1).min(0).default(60000).volatile(),
|
|
281
|
+
})
|
|
282
|
+
|
|
133
283
|
/** Clamp a numeric option, falling back when it is not a finite number. */
|
|
134
284
|
function num(value, fallback) {
|
|
135
285
|
return typeof value === 'number' && Number.isFinite(value) ? value : fallback
|
|
136
286
|
}
|
|
137
287
|
|
|
288
|
+
/** The marker `cosmokit` puts on a volatile config reference. */
|
|
289
|
+
const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* Materialize one config value.
|
|
293
|
+
*
|
|
294
|
+
* A field declared `.volatile()` is stored by the host as a live *reference*, not
|
|
295
|
+
* a plain value — that is the mechanism that lets the settings page change an
|
|
296
|
+
* option without reloading the plugin (`loader._commitVolatile` writes into the
|
|
297
|
+
* running reference). So `ctx.config` hands this plugin reference objects, and
|
|
298
|
+
* the host's own adapters unwrap them the same way (`plainOptions`). Detection is
|
|
299
|
+
* structural and matches `cosmokit.isVolatile`.
|
|
300
|
+
*/
|
|
301
|
+
function plainValue(value) {
|
|
302
|
+
if (
|
|
303
|
+
value !== null &&
|
|
304
|
+
typeof value === 'object' &&
|
|
305
|
+
VOLATILE_WRITE in value &&
|
|
306
|
+
typeof value.get === 'function'
|
|
307
|
+
) {
|
|
308
|
+
return plainValue(value.get())
|
|
309
|
+
}
|
|
310
|
+
return value
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** Materialize a whole config object, one level deep, as the host does. */
|
|
314
|
+
function plainConfig(config) {
|
|
315
|
+
if (config === null || typeof config !== 'object') return config
|
|
316
|
+
const out = {}
|
|
317
|
+
for (const [key, value] of Object.entries(config)) out[key] = plainValue(value)
|
|
318
|
+
return out
|
|
319
|
+
}
|
|
320
|
+
|
|
138
321
|
/** Merge user config over the defaults with light validation. */
|
|
139
322
|
function resolveOptions(config) {
|
|
140
|
-
const raw = config
|
|
141
|
-
const merged = { ...DEFAULT_OPTIONS, ...raw }
|
|
323
|
+
const raw = plainConfig(config)
|
|
324
|
+
const merged = raw !== null && typeof raw === 'object' ? { ...DEFAULT_OPTIONS, ...raw } : DEFAULT_OPTIONS
|
|
142
325
|
const rules = Array.isArray(merged.compactionRules)
|
|
143
326
|
? merged.compactionRules.filter((rule) => typeof rule === 'string' && rule.trim().length > 0)
|
|
144
327
|
: DEFAULT_COMPACTION_RULES
|
|
@@ -155,8 +338,29 @@ function resolveOptions(config) {
|
|
|
155
338
|
moderateAt: num(merged.moderateAt, DEFAULT_OPTIONS.moderateAt),
|
|
156
339
|
tightAt: num(merged.tightAt, DEFAULT_OPTIONS.tightAt),
|
|
157
340
|
hysteresis: Math.max(0, num(merged.hysteresis, DEFAULT_OPTIONS.hysteresis)),
|
|
341
|
+
tightAdvice:
|
|
342
|
+
merged.tightAdvice === 'stop' ? 'stop' : merged.tightAdvice === 'inform' ? 'inform' : 'none',
|
|
343
|
+
foldClause: merged.foldClause === true,
|
|
344
|
+
freeClause: merged.freeClause === true,
|
|
158
345
|
quantumPercent: Math.max(0, num(merged.quantumPercent, DEFAULT_OPTIONS.quantumPercent)),
|
|
346
|
+
paceEstimate: merged.paceEstimate === true,
|
|
347
|
+
paceSamples: Math.max(2, Math.round(num(merged.paceSamples, DEFAULT_OPTIONS.paceSamples))),
|
|
348
|
+
paceMinSamples: Math.max(1, Math.round(num(merged.paceMinSamples, DEFAULT_OPTIONS.paceMinSamples))),
|
|
349
|
+
paceMargin: Math.max(0, num(merged.paceMargin, DEFAULT_OPTIONS.paceMargin)),
|
|
159
350
|
compactionRules: rules,
|
|
351
|
+
foldAtIdle: merged.foldAtIdle === true,
|
|
352
|
+
foldAtIdleMarginPercent: Math.min(
|
|
353
|
+
50,
|
|
354
|
+
Math.max(0.1, num(merged.foldAtIdleMarginPercent, DEFAULT_OPTIONS.foldAtIdleMarginPercent)),
|
|
355
|
+
),
|
|
356
|
+
foldAtIdleMethod:
|
|
357
|
+
merged.foldAtIdleMethod === 'command' || merged.foldAtIdleMethod === 'service'
|
|
358
|
+
? merged.foldAtIdleMethod
|
|
359
|
+
: 'auto',
|
|
360
|
+
foldAtIdleCooldownMs: Math.max(
|
|
361
|
+
0,
|
|
362
|
+
num(merged.foldAtIdleCooldownMs, DEFAULT_OPTIONS.foldAtIdleCooldownMs),
|
|
363
|
+
),
|
|
160
364
|
}
|
|
161
365
|
}
|
|
162
366
|
|
|
@@ -174,25 +378,93 @@ function percentOf(value, total) {
|
|
|
174
378
|
return Math.round((value / total) * 100)
|
|
175
379
|
}
|
|
176
380
|
|
|
381
|
+
/** Read a wired service by property for diagnostics; never throws. */
|
|
382
|
+
function serviceOr(ctx, key) {
|
|
383
|
+
try {
|
|
384
|
+
return ctx[key]
|
|
385
|
+
} catch {
|
|
386
|
+
return undefined
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
/**
|
|
391
|
+
* Name the mounted compaction backend by its prototype chain, for diagnostics.
|
|
392
|
+
*
|
|
393
|
+
* Which backend owns the seam decides two things this plugin cares about: whether
|
|
394
|
+
* a fold can be requested at all (`compactNow` reachable from a plugin context —
|
|
395
|
+
* the stock backend is not, see upstream discussion 9425), and whether capability
|
|
396
|
+
* 2 has anything to patch (a deterministic backend makes no summarizer call, so
|
|
397
|
+
* the directive rules never apply).
|
|
398
|
+
*
|
|
399
|
+
* @returns the chain, or `none` when no service is reachable.
|
|
400
|
+
*/
|
|
401
|
+
function backendIdentity(service) {
|
|
402
|
+
try {
|
|
403
|
+
if (!isService(service)) return 'none'
|
|
404
|
+
const chain = []
|
|
405
|
+
let proto = Object.getPrototypeOf(service)
|
|
406
|
+
while (proto !== null && proto.constructor !== undefined && chain.length < 5) {
|
|
407
|
+
if (proto.constructor.name === 'Object') break
|
|
408
|
+
chain.push(proto.constructor.name)
|
|
409
|
+
proto = Object.getPrototypeOf(proto)
|
|
410
|
+
}
|
|
411
|
+
return chain.length === 0 ? 'anonymous' : chain.join('>')
|
|
412
|
+
} catch {
|
|
413
|
+
return 'unknown'
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
|
|
177
417
|
/** Resolve a service that may or may not be mounted, without ever throwing. */
|
|
178
418
|
function safeGet(ctx, key) {
|
|
419
|
+
let viaMethod
|
|
179
420
|
try {
|
|
180
|
-
|
|
421
|
+
viaMethod = ctx.get(key)
|
|
181
422
|
} catch {
|
|
182
|
-
|
|
423
|
+
viaMethod = undefined
|
|
424
|
+
}
|
|
425
|
+
if (isService(viaMethod)) return viaMethod
|
|
426
|
+
let viaProperty
|
|
427
|
+
try {
|
|
428
|
+
viaProperty = ctx[key]
|
|
429
|
+
} catch {
|
|
430
|
+
viaProperty = undefined
|
|
183
431
|
}
|
|
432
|
+
return isService(viaProperty) ? viaProperty : undefined
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
/**
|
|
436
|
+
* Whether a value is a reachable service.
|
|
437
|
+
*
|
|
438
|
+
* Load-bearing: cordis answers a property read for a service this fiber does not
|
|
439
|
+
* have with a **string** ("not injected" style diagnostics), not `undefined`. An
|
|
440
|
+
* earlier revision accepted anything non-undefined, so the idle fold concluded it
|
|
441
|
+
* had a service and then failed the `compactNow` shape check — and the "no service
|
|
442
|
+
* mounted" warning fired on every trigger while the real reason stayed invisible.
|
|
443
|
+
*/
|
|
444
|
+
function isService(value) {
|
|
445
|
+
return value !== null && (typeof value === 'object' || typeof value === 'function')
|
|
184
446
|
}
|
|
185
447
|
|
|
186
448
|
/**
|
|
187
449
|
* Read the host's own occupancy figure for one session.
|
|
188
450
|
* @returns `{ used, window, reserved, threshold }`; any field may be `undefined`.
|
|
189
451
|
*/
|
|
190
|
-
function readOccupancy(ctx, session, options) {
|
|
452
|
+
function readOccupancy(ctx, session, options, injectedMeter) {
|
|
191
453
|
const result = {}
|
|
192
454
|
let used
|
|
193
455
|
let window_
|
|
194
456
|
|
|
195
|
-
|
|
457
|
+
// `injectedMeter` is a resolver (see `apply`), not a value: reading it per use
|
|
458
|
+
// follows a host that swaps the service.
|
|
459
|
+
let meter
|
|
460
|
+
if (injectedMeter !== undefined) {
|
|
461
|
+
try {
|
|
462
|
+
meter = injectedMeter()
|
|
463
|
+
} catch {
|
|
464
|
+
meter = undefined
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
if (meter === undefined) meter = safeGet(ctx, 'tokenMeter')
|
|
196
468
|
if (meter !== undefined && typeof meter.measure === 'function') {
|
|
197
469
|
try {
|
|
198
470
|
const measured = meter.measure(session)
|
|
@@ -312,14 +584,21 @@ function quantize(used, window_, options) {
|
|
|
312
584
|
/**
|
|
313
585
|
* Display step for the remaining-headroom figure. Every step is a function of the
|
|
314
586
|
* reading, so a whole bucket renders to one identical string.
|
|
587
|
+
*
|
|
588
|
+
* The floor is deliberately coarse. An earlier build shrank the step to 2K as the
|
|
589
|
+
* room ran out, which re-injected the line on nearly every step in exactly the
|
|
590
|
+
* band that was already talking about the fold: over one long session the tight
|
|
591
|
+
* band was committed 333 times at a median gap of 45s, with runs of 4–20s. Within
|
|
592
|
+
* a few tens of thousands of tokens of the point, the pace estimate is the useful
|
|
593
|
+
* signal, not the exact remainder — and the sub-step rendering ("Under 10K") keeps
|
|
594
|
+
* a remainder smaller than one step honest.
|
|
315
595
|
*/
|
|
316
596
|
function headroomDisplayStep(headroom, window_, options) {
|
|
317
597
|
const coarse = displayStep(window_, options)
|
|
318
598
|
const tiers = [
|
|
319
599
|
coarse,
|
|
320
600
|
Math.max(1000, Math.round(coarse * 0.4)),
|
|
321
|
-
Math.max(1000, Math.round(coarse * 0.
|
|
322
|
-
2000,
|
|
601
|
+
Math.max(1000, Math.round(coarse * 0.2)),
|
|
323
602
|
]
|
|
324
603
|
for (const tier of tiers) {
|
|
325
604
|
if (headroom >= 4 * tier) return tier
|
|
@@ -339,11 +618,22 @@ function quantizeHeadroom(headroom, window_, options) {
|
|
|
339
618
|
return Math.floor(headroom / step) * step
|
|
340
619
|
}
|
|
341
620
|
|
|
342
|
-
/**
|
|
621
|
+
/**
|
|
622
|
+
* The clause that closes every variant.
|
|
623
|
+
*
|
|
624
|
+
* The "do not count it down yourself" half is not decoration. A live session
|
|
625
|
+
* showed the model reading the figure correctly and then spending it in its head
|
|
626
|
+
* across the steps that followed — `30K → 28K → 16K → 10K → 7K → 5K` — while the
|
|
627
|
+
* host's own number sat still at `About 10K` (it is restated only when it changes,
|
|
628
|
+
* which is what keeps this line from re-injecting every step). Twelve minutes
|
|
629
|
+
* later it announced "Context is nearly exhausted (~5K)", a figure the host never
|
|
630
|
+
* reported. The measured number has to be labelled a measurement, not an
|
|
631
|
+
* allowance to draw down.
|
|
632
|
+
*/
|
|
343
633
|
function authorityClause(language) {
|
|
344
634
|
return language === 'zh'
|
|
345
|
-
? '
|
|
346
|
-
:
|
|
635
|
+
? '本行是宿主的后台遥测,也是上下文压力的唯一权威——不要提起它、不要凭对话长度或轮数估计压力、不要自行倒计时(读数变化时它会自动重述),也不要对压缩采取任何动作:折叠由宿主在步与步之间自动完成。'
|
|
636
|
+
: 'Background telemetry from the host, and the only authority on context pressure: do not mention it, do not estimate or count it down yourself — it is restated whenever it changes — and take no action about compaction; the host folds between steps automatically.'
|
|
347
637
|
}
|
|
348
638
|
|
|
349
639
|
/** The clause that retires claims inherited from earlier turns and checkpoints. */
|
|
@@ -353,6 +643,56 @@ function staleClause(language) {
|
|
|
353
643
|
: 'Earlier claims that context is nearly exhausted — including ones inside compacted checkpoints — are stale.'
|
|
354
644
|
}
|
|
355
645
|
|
|
646
|
+
/**
|
|
647
|
+
* The `tight` band's closing sentence, when one is configured.
|
|
648
|
+
*
|
|
649
|
+
* `none` is the default and adds nothing: the numbers are the message. The 0.1.4
|
|
650
|
+
* build described the coming fold here, and a live session showed what that
|
|
651
|
+
* costs — the band re-injects most often, so the model read a fresh fold notice
|
|
652
|
+
* every step or two, began narrating "I should compact" in its own replies, and
|
|
653
|
+
* lost momentum. A sentence about an automatic, host-owned event turned into a
|
|
654
|
+
* task the model thought it owned.
|
|
655
|
+
*
|
|
656
|
+
* `inform` restores the 0.1.4 factual sentence, `stop` the 0.1.3 imperative.
|
|
657
|
+
*/
|
|
658
|
+
function tightClause(zh, options) {
|
|
659
|
+
if (options.tightAdvice === 'stop') {
|
|
660
|
+
return zh
|
|
661
|
+
? ' 余量确实不多了——收完当前这一步、把状态落到磁盘,再考虑交接。'
|
|
662
|
+
: ' Headroom is genuinely small — finish the current step, land durable state, then hand off.'
|
|
663
|
+
}
|
|
664
|
+
if (options.tightAdvice === 'inform') {
|
|
665
|
+
return zh
|
|
666
|
+
? ' 到那时较早的对话会被折成一段 LLM 摘要、本窗口被重写——别让关键状态只存在于对话里。'
|
|
667
|
+
: ' At that point the older turns are folded into an LLM-written summary and this window is rewritten — keep nothing critical only in the conversation.'
|
|
668
|
+
}
|
|
669
|
+
return ''
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
/**
|
|
673
|
+
* What the fold *is*, for the two bands whose remaining room is small.
|
|
674
|
+
*
|
|
675
|
+
* The numbers alone left a gap a live session walked straight into: eleven
|
|
676
|
+
* seconds after the line said `Under 10K tokens of headroom remain before it`, the
|
|
677
|
+
* model wrote "Very low context. I must do this in as few commands as possible."
|
|
678
|
+
* It had read the figure correctly — it simply took "room before the fold" to mean
|
|
679
|
+
* "context left", when the window still held 350K and the fold only reorganizes
|
|
680
|
+
* it. This clause is that missing definition, stated as a fact: it orders nothing,
|
|
681
|
+
* so it cannot become the "finish the step and hand off" nudge of 0.1.3.
|
|
682
|
+
*
|
|
683
|
+
* `brief` is for the `critical` band, which already says a fold is expected and
|
|
684
|
+
* only needs the part that defuses "exhausted".
|
|
685
|
+
*/
|
|
686
|
+
function foldClause(zh, options, brief = false) {
|
|
687
|
+
if (options.foldClause !== true) return ''
|
|
688
|
+
if (brief) {
|
|
689
|
+
return zh ? ' 窗口并未耗尽——折叠之后工作照常继续。' : ' The window is not exhausted — work continues after the fold.'
|
|
690
|
+
}
|
|
691
|
+
return zh
|
|
692
|
+
? ' 折叠是例行操作,不是窗口的终点:较早的对话会被折成摘要,之后工作照常继续。'
|
|
693
|
+
: ' The fold is routine, not the end of the window: older turns become a summary and work continues after it.'
|
|
694
|
+
}
|
|
695
|
+
|
|
356
696
|
/** "under 50K" / "不足 50K" — the honest form of a figure below one display step. */
|
|
357
697
|
function underStep(step, zh) {
|
|
358
698
|
return zh ? `不足 ${formatTokens(step)}` : `under ${formatTokens(step)}`
|
|
@@ -364,6 +704,151 @@ function underPercent(step, window_, zh) {
|
|
|
364
704
|
return zh ? `不足 ${value}` : `under ${value}`
|
|
365
705
|
}
|
|
366
706
|
|
|
707
|
+
/**
|
|
708
|
+
* Step-count ladder for the pace estimate. Coarse on purpose: the runtime
|
|
709
|
+
* snapshot is re-committed only when its bytes change, so a figure that drifts
|
|
710
|
+
* every step would cost more in re-injection than it explains. The rendered rung
|
|
711
|
+
* moves only when the estimate crosses it.
|
|
712
|
+
*
|
|
713
|
+
* The top rung is open-ended (`20+`) because that is where the estimate is both
|
|
714
|
+
* least useful and most volatile: a live session's raw count ranged 23–38 across
|
|
715
|
+
* consecutive steps, which straddled a `21 / 34` boundary and flipped the line
|
|
716
|
+
* five times in 90 seconds. Above ~20 steps the exact figure changes no decision.
|
|
717
|
+
*/
|
|
718
|
+
const PACE_LADDER = [1, 2, 3, 5, 8, 13, 20]
|
|
719
|
+
|
|
720
|
+
/** Median of a small numeric array; does not mutate the input. */
|
|
721
|
+
function median(values) {
|
|
722
|
+
if (!Array.isArray(values) || values.length === 0) return undefined
|
|
723
|
+
const sorted = [...values].sort((left, right) => left - right)
|
|
724
|
+
const middle = sorted.length >> 1
|
|
725
|
+
return sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
/**
|
|
729
|
+
* Fold one prompt assembly into the per-session pace state.
|
|
730
|
+
*
|
|
731
|
+
* Sampling happens ONLY when the host's `(turn, step)` pair advances. One step
|
|
732
|
+
* can assemble more than once — retries, the compaction summarizer, session
|
|
733
|
+
* titling — and those extra assemblies are not work and must not enter the
|
|
734
|
+
* average as if they were.
|
|
735
|
+
*
|
|
736
|
+
* A negative delta means the meter re-based because a fold landed (measured in
|
|
737
|
+
* this deployment: 200K -> under 50K within three seconds). The history is
|
|
738
|
+
* dropped instead of being averaged against it, otherwise a single fold poisons
|
|
739
|
+
* the estimate for many steps afterwards. The estimate is the median of the
|
|
740
|
+
* recent positive deltas, so one 30K tool dump cannot drag it; a step that added
|
|
741
|
+
* nothing is not evidence about pace and is ignored.
|
|
742
|
+
*
|
|
743
|
+
* @returns `{ state, perStep, samples }`; `perStep` stays undefined until
|
|
744
|
+
* `paceMinSamples` samples exist, and stays undefined when the host exposes no
|
|
745
|
+
* step counter at all.
|
|
746
|
+
*/
|
|
747
|
+
function nextPaceState(previous, sample, options) {
|
|
748
|
+
const turn = sample === undefined || sample === null ? undefined : sample.turn
|
|
749
|
+
const step = sample === undefined || sample === null ? undefined : sample.step
|
|
750
|
+
const used = sample === undefined || sample === null ? undefined : sample.used
|
|
751
|
+
const observed = previous === undefined || previous === null ? undefined : previous
|
|
752
|
+
|
|
753
|
+
// No usable counter: keep whatever state we already have.
|
|
754
|
+
if (!Number.isFinite(turn) || !Number.isFinite(step) || !Number.isFinite(used)) {
|
|
755
|
+
return { state: observed, perStep: observed?.perStep, samples: observed?.recent.length ?? 0 }
|
|
756
|
+
}
|
|
757
|
+
if (observed === undefined) return { state: { turn, step, used, recent: [] }, perStep: undefined, samples: 0 }
|
|
758
|
+
|
|
759
|
+
// Same step assembled again: no new work, so nothing is sampled.
|
|
760
|
+
if (observed.turn === turn && observed.step === step) {
|
|
761
|
+
return { state: observed, perStep: observed.perStep, samples: observed.recent.length }
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
const delta = used - observed.used
|
|
765
|
+
const recent =
|
|
766
|
+
delta < 0
|
|
767
|
+
? []
|
|
768
|
+
: delta === 0
|
|
769
|
+
? observed.recent
|
|
770
|
+
: [...observed.recent, delta].slice(-options.paceSamples)
|
|
771
|
+
const perStep = recent.length >= options.paceMinSamples ? median(recent) : undefined
|
|
772
|
+
return { state: { turn, step, used, recent, perStep }, perStep, samples: recent.length }
|
|
773
|
+
}
|
|
774
|
+
|
|
775
|
+
/**
|
|
776
|
+
* The estimate for one assembly, keeping per-session state in `store`.
|
|
777
|
+
* Undefined whenever the feature is off, the host has no step counter, or the
|
|
778
|
+
* session is too young — in which case the clause is absent, not zero.
|
|
779
|
+
*/
|
|
780
|
+
function samplePace(store, session, assembly, used, options) {
|
|
781
|
+
if (options.paceEstimate !== true || !Number.isFinite(used)) return undefined
|
|
782
|
+
const agent = assembly === undefined || assembly === null ? undefined : assembly.agent
|
|
783
|
+
const phase = agent === undefined || agent === null ? undefined : agent.phase
|
|
784
|
+
const next = nextPaceState(store.get(session), { turn: phase?.turn, step: phase?.step, used }, options)
|
|
785
|
+
if (next.state !== undefined) store.set(session, next.state)
|
|
786
|
+
return next.perStep
|
|
787
|
+
}
|
|
788
|
+
|
|
789
|
+
/** Whole steps the remaining headroom covers at the observed rate. */
|
|
790
|
+
function paceSteps(headroom, perStep) {
|
|
791
|
+
if (!Number.isFinite(headroom) || headroom < 0) return undefined
|
|
792
|
+
if (!Number.isFinite(perStep) || perStep <= 0) return undefined
|
|
793
|
+
return Math.floor(headroom / perStep)
|
|
794
|
+
}
|
|
795
|
+
|
|
796
|
+
/** Index of the largest ladder rung a step count still reaches, or undefined. */
|
|
797
|
+
function paceRung(steps) {
|
|
798
|
+
if (!Number.isFinite(steps) || steps < 1) return undefined
|
|
799
|
+
let index = 0
|
|
800
|
+
for (let i = 0; i < PACE_LADDER.length; i += 1) if (steps >= PACE_LADDER[i]) index = i
|
|
801
|
+
return index
|
|
802
|
+
}
|
|
803
|
+
|
|
804
|
+
/**
|
|
805
|
+
* Settle the rung the line publishes.
|
|
806
|
+
*
|
|
807
|
+
* The estimate's own wobble is wider than one rung, so publishing it raw made the
|
|
808
|
+
* line flip: measured in a live session, `13 -> 21 -> 34+ -> 21 -> 34+` inside 90
|
|
809
|
+
* seconds, where one snapshot re-commit was caused by nothing but the flip (the
|
|
810
|
+
* headroom and the band were both unchanged). The rung therefore settles the way
|
|
811
|
+
* a band does, and asymmetrically:
|
|
812
|
+
*
|
|
813
|
+
* - downward — fewer remaining steps, i.e. less room promised — takes effect at
|
|
814
|
+
* once, the same direction the headroom itself rounds;
|
|
815
|
+
* - upward — promising more room — must clear the higher rung by `paceMargin`,
|
|
816
|
+
* so a straddling estimate cannot flip the line, while a genuinely slower
|
|
817
|
+
* session still gets the higher figure (the rule cannot freeze).
|
|
818
|
+
*
|
|
819
|
+
* @returns `{ state, steps }`, where `steps` re-derives the rung to render.
|
|
820
|
+
*/
|
|
821
|
+
function settlePace(steps, previous, options) {
|
|
822
|
+
const index = paceRung(steps)
|
|
823
|
+
if (index === undefined) return { state: previous, steps: undefined }
|
|
824
|
+
if (previous === undefined || previous === null || !Number.isFinite(previous.published)) {
|
|
825
|
+
return { state: { published: index }, steps: PACE_LADDER[index] }
|
|
826
|
+
}
|
|
827
|
+
if (index <= previous.published) return { state: { published: index }, steps: PACE_LADDER[index] }
|
|
828
|
+
const required = PACE_LADDER[index] * (1 + Math.max(0, options.paceMargin))
|
|
829
|
+
if (steps >= required) return { state: { published: index }, steps: PACE_LADDER[index] }
|
|
830
|
+
return { state: previous, steps: PACE_LADDER[previous.published] }
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
/**
|
|
834
|
+
* The pace clause, bucketed onto {@link PACE_LADDER}.
|
|
835
|
+
*
|
|
836
|
+
* The rung is the largest one the estimate still reaches, so the figure rounds
|
|
837
|
+
* DOWN like the headroom does: the line must never promise more remaining steps
|
|
838
|
+
* than the session's own rate supports. The top rung renders as "34+".
|
|
839
|
+
*/
|
|
840
|
+
function paceSentence(steps, zh) {
|
|
841
|
+
if (!Number.isFinite(steps) || steps < 1) return ''
|
|
842
|
+
let rung = PACE_LADDER[0]
|
|
843
|
+
for (const edge of PACE_LADDER) if (steps >= edge) rung = edge
|
|
844
|
+
const open = rung === PACE_LADDER[PACE_LADDER.length - 1]
|
|
845
|
+
const label = open ? `${rung}+` : String(rung)
|
|
846
|
+
const plural = rung === 1 ? '' : 's'
|
|
847
|
+
return zh
|
|
848
|
+
? ` 按本会话近期节奏,这点余量约合 ${label} 步。`
|
|
849
|
+
: ` At this session's recent rate that is roughly ${label} more step${plural}.`
|
|
850
|
+
}
|
|
851
|
+
|
|
367
852
|
/** Render the reading for one band. Pure: same inputs, same bytes. */
|
|
368
853
|
function render(band, reading, options) {
|
|
369
854
|
const zh = options.language === 'zh'
|
|
@@ -372,6 +857,18 @@ function render(band, reading, options) {
|
|
|
372
857
|
if (band === 'ample' && options.staleClaimClause) parts.push(staleClause(options.language))
|
|
373
858
|
const tail = parts.length === 0 ? '' : ` ${parts.join(' ')}`
|
|
374
859
|
|
|
860
|
+
// The estimate qualifies the remaining headroom, so it rides only on the two
|
|
861
|
+
// bands where that headroom is the decision at hand — together with the
|
|
862
|
+
// definition of what the fold is, without which the figure reads as "context
|
|
863
|
+
// left" rather than "room before a routine reorganization".
|
|
864
|
+
const pace = band === 'tight' || band === 'critical' ? paceSentence(reading.steps, zh) : ''
|
|
865
|
+
const fold =
|
|
866
|
+
band === 'tight'
|
|
867
|
+
? foldClause(zh, options)
|
|
868
|
+
: band === 'critical'
|
|
869
|
+
? foldClause(zh, options, true)
|
|
870
|
+
: ''
|
|
871
|
+
|
|
375
872
|
if (band === 'unknown') {
|
|
376
873
|
return zh
|
|
377
874
|
? `上下文实况:本会话尚未取到用量读数。不要据此声称上下文紧张。${tail}`
|
|
@@ -396,8 +893,28 @@ function render(band, reading, options) {
|
|
|
396
893
|
? ` 自动压缩阈值 ${formatTokens(reading.threshold)}(窗口的 ${percentOf(reading.threshold, reading.window)}%)。`
|
|
397
894
|
: ` Automatic compaction fires at ${formatTokens(reading.threshold)} (${percentOf(reading.threshold, reading.window)}% of the window).`
|
|
398
895
|
: ''
|
|
896
|
+
// How much of the window is still unused — the figure that actually answers
|
|
897
|
+
// "how much context do I have left?". The headroom above answers a different
|
|
898
|
+
// question ("how far to the fold"), and a live model answered the first with
|
|
899
|
+
// the second: "Very low context" at 10K of headroom, while 350K of the window
|
|
900
|
+
// was free. Quantized onto the same step as `used`, so it moves on exactly the
|
|
901
|
+
// same crossings and costs no extra re-injection.
|
|
902
|
+
const freeRaw = reading.freeRaw
|
|
903
|
+
const flooredFree = reading.free === 0 && Number.isFinite(freeRaw) && freeRaw > 0
|
|
904
|
+
const free =
|
|
905
|
+
options.freeClause !== true || !Number.isFinite(reading.free)
|
|
906
|
+
? ''
|
|
907
|
+
: flooredFree && step !== undefined
|
|
908
|
+
? zh
|
|
909
|
+
? ` 窗口还有${underStep(step, zh)} 未使用。`
|
|
910
|
+
: ` Under ${formatTokens(step)} of the window is still free.`
|
|
911
|
+
: zh
|
|
912
|
+
? ` 窗口还有约 ${formatTokens(reading.free)} 未使用。`
|
|
913
|
+
: ` About ${formatTokens(reading.free)} of the window is still free.`
|
|
914
|
+
// Nothing left to report once the reading has reached the point: "About 0
|
|
915
|
+
// tokens of headroom remain" is noise on the one line that should stay calm.
|
|
399
916
|
const remaining =
|
|
400
|
-
head === undefined
|
|
917
|
+
head === undefined || reading.headroomRaw === 0
|
|
401
918
|
? ''
|
|
402
919
|
: flooredHead && headStep !== undefined
|
|
403
920
|
? zh
|
|
@@ -413,20 +930,18 @@ function render(band, reading, options) {
|
|
|
413
930
|
switch (band) {
|
|
414
931
|
case 'ample':
|
|
415
932
|
return zh
|
|
416
|
-
? `${head0}${point}${remaining} 上下文不紧张——不要因为"上下文不够"而收尾、交接子代理或缩小范围。${tail}`
|
|
417
|
-
: `${head0}${point}${remaining} Context is NOT scarce — do not wrap up, hand off to a subagent, or narrow scope for context reasons.${tail}`
|
|
933
|
+
? `${head0}${free}${point}${remaining} 上下文不紧张——不要因为"上下文不够"而收尾、交接子代理或缩小范围。${tail}`
|
|
934
|
+
: `${head0}${free}${point}${remaining} Context is NOT scarce — do not wrap up, hand off to a subagent, or narrow scope for context reasons.${tail}`
|
|
418
935
|
case 'moderate':
|
|
419
936
|
return zh
|
|
420
|
-
? `${head0}${point}${remaining} 仍有充足余量,继续推进即可,顺手把关键状态写进文档或提交。${tail}`
|
|
421
|
-
: `${head0}${point}${remaining} There is still real headroom — keep going, and keep durable notes or commits current as you work.${tail}`
|
|
937
|
+
? `${head0}${free}${point}${remaining} 仍有充足余量,继续推进即可,顺手把关键状态写进文档或提交。${tail}`
|
|
938
|
+
: `${head0}${free}${point}${remaining} There is still real headroom — keep going, and keep durable notes or commits current as you work.${tail}`
|
|
422
939
|
case 'tight':
|
|
423
|
-
return zh
|
|
424
|
-
? `${head0}${point}${remaining} 余量确实不多了——收完当前这一步、把状态落到磁盘,再考虑交接。${tail}`
|
|
425
|
-
: `${head0}${point}${remaining} Headroom is genuinely small — finish the current step, land durable state, then hand off.${tail}`
|
|
940
|
+
return `${head0}${free}${point}${remaining}${pace}${fold}${tightClause(zh, options)}${tail}`
|
|
426
941
|
default:
|
|
427
942
|
return zh
|
|
428
|
-
? `${head0}${point} 已到或越过自动压缩点——接下来可能发生压缩折叠,别让关键状态只存在于本窗口。${tail}`
|
|
429
|
-
: `${head0}${point} At or past the automatic compaction point — expect earlier turns to be folded; keep nothing critical only in this window.${tail}`
|
|
943
|
+
? `${head0}${free}${point}${remaining}${pace}${fold} 已到或越过自动压缩点——接下来可能发生压缩折叠,别让关键状态只存在于本窗口。${tail}`
|
|
944
|
+
: `${head0}${free}${point}${remaining}${pace}${fold} At or past the automatic compaction point — expect earlier turns to be folded; keep nothing critical only in this window.${tail}`
|
|
430
945
|
}
|
|
431
946
|
}
|
|
432
947
|
|
|
@@ -525,11 +1040,44 @@ function patchCompactionRequest(options, rules) {
|
|
|
525
1040
|
* @param config - optional overrides of the defaults documented above.
|
|
526
1041
|
*/
|
|
527
1042
|
export function apply(ctx, config) {
|
|
528
|
-
|
|
1043
|
+
// Read options through this on every use. A field declared `.volatile()` is a
|
|
1044
|
+
// live reference, so a settings change lands here without reloading the plugin
|
|
1045
|
+
// — a snapshot taken once at apply time would silently ignore every later
|
|
1046
|
+
// toggle. The listeners below are therefore installed unconditionally and gate
|
|
1047
|
+
// themselves per event instead of at install time.
|
|
1048
|
+
const resolve = () => resolveOptions(config)
|
|
1049
|
+
|
|
1050
|
+
// Services are acquired through `ctx.inject`, not `ctx.get`. `get` resolves
|
|
1051
|
+
// through `ctx.reflect` and returned nothing for `compaction` in a live
|
|
1052
|
+
// deployment: the idle fold's first real trigger (22:44, inside the margin, at
|
|
1053
|
+
// an idle boundary) logged "no compaction service is mounted" and folded
|
|
1054
|
+
// nothing. Injecting also keeps this plugin loading on deployments that mount
|
|
1055
|
+
// no compaction service at all, since the callback simply never runs.
|
|
1056
|
+
// Services are read per use through the proxy cordis wires for the declared
|
|
1057
|
+
// injections, never snapshotted: a host that swaps an implementation (or
|
|
1058
|
+
// provides one only later) must be followed. `readOccupancy` and the fold also
|
|
1059
|
+
// fall back to `safeGet`, which costs nothing and keeps the plugin usable if a
|
|
1060
|
+
// deployment resolves the names differently.
|
|
1061
|
+
const services = {
|
|
1062
|
+
meter: () => ctx.tokenMeter,
|
|
1063
|
+
// `ctx.compaction` answers with a diagnostic string when the service is not
|
|
1064
|
+
// reachable, which `isService` rejects; the fold therefore stays inactive and
|
|
1065
|
+
// logs why, once, instead of failing per trigger.
|
|
1066
|
+
compaction: () => ctx.compaction,
|
|
1067
|
+
}
|
|
1068
|
+
const compactionService = serviceOr(ctx, 'compaction')
|
|
1069
|
+
logLine(
|
|
1070
|
+
ctx,
|
|
1071
|
+
'info',
|
|
1072
|
+
'context-truth: services wired (tokenMeter=%s compaction=%s/%s)',
|
|
1073
|
+
typeof serviceOr(ctx, 'tokenMeter'),
|
|
1074
|
+
typeof compactionService,
|
|
1075
|
+
backendIdentity(compactionService),
|
|
1076
|
+
)
|
|
529
1077
|
|
|
530
|
-
if (
|
|
1078
|
+
if (resolve().enabled) {
|
|
531
1079
|
try {
|
|
532
|
-
installContextLine(ctx,
|
|
1080
|
+
installContextLine(ctx, resolve, services)
|
|
533
1081
|
} catch (error) {
|
|
534
1082
|
if (isAlreadyRegistered(error)) {
|
|
535
1083
|
const logger = ctx.logger
|
|
@@ -542,7 +1090,8 @@ export function apply(ctx, config) {
|
|
|
542
1090
|
}
|
|
543
1091
|
}
|
|
544
1092
|
|
|
545
|
-
installCompactionPatch(ctx,
|
|
1093
|
+
installCompactionPatch(ctx, resolve)
|
|
1094
|
+
installIdleFold(ctx, resolve, services)
|
|
546
1095
|
}
|
|
547
1096
|
|
|
548
1097
|
/** Whether a registration failed because the name is already taken in this layer. */
|
|
@@ -551,11 +1100,12 @@ function isAlreadyRegistered(error) {
|
|
|
551
1100
|
}
|
|
552
1101
|
|
|
553
1102
|
/** Install the `llm/stream` listener that extends the summarizer directive. */
|
|
554
|
-
function installCompactionPatch(ctx,
|
|
555
|
-
if (!options.patchCompactionPrompt || options.compactionRules.length === 0) return
|
|
1103
|
+
function installCompactionPatch(ctx, resolve) {
|
|
556
1104
|
let warned = false
|
|
557
1105
|
ctx.on('llm/stream', (request, next) => {
|
|
558
1106
|
try {
|
|
1107
|
+
const options = resolve()
|
|
1108
|
+
if (!options.patchCompactionPrompt || options.compactionRules.length === 0) return next()
|
|
559
1109
|
const applied = patchCompactionRequest(request, options.compactionRules)
|
|
560
1110
|
// Only a request its own caller tagged as compaction may spend the one-shot
|
|
561
1111
|
// warning. Warning on a heuristic match let an ordinary turn — one whose
|
|
@@ -575,19 +1125,191 @@ function installCompactionPatch(ctx, options) {
|
|
|
575
1125
|
})
|
|
576
1126
|
}
|
|
577
1127
|
|
|
1128
|
+
/** Log through the host logger when present; logging must never break a turn. */
|
|
1129
|
+
function logLine(ctx, level, format, ...args) {
|
|
1130
|
+
try {
|
|
1131
|
+
const logger = ctx.logger
|
|
1132
|
+
if (logger !== undefined && typeof logger[level] === 'function') logger[level](format, ...args)
|
|
1133
|
+
} catch {
|
|
1134
|
+
// A logger that throws is the logger's problem, not the turn's.
|
|
1135
|
+
}
|
|
1136
|
+
}
|
|
1137
|
+
|
|
1138
|
+
/**
|
|
1139
|
+
* Whether an idle session is close enough to the compaction point that its next
|
|
1140
|
+
* turns would be short sprints. Pure, so the decision is testable without stubs.
|
|
1141
|
+
*
|
|
1142
|
+
* @param reading - `{ used, threshold, window }` as returned by `readOccupancy`.
|
|
1143
|
+
* @param options - resolved plugin options.
|
|
1144
|
+
* @returns `{ fold }` plus the numbers behind the decision, for the log line.
|
|
1145
|
+
*/
|
|
1146
|
+
function shouldFoldAtIdle(reading, options) {
|
|
1147
|
+
if (options.foldAtIdle !== true) return { fold: false }
|
|
1148
|
+
const used = reading === null || reading === undefined ? undefined : reading.used
|
|
1149
|
+
const threshold = reading === null || reading === undefined ? undefined : reading.threshold
|
|
1150
|
+
const window_ = reading === null || reading === undefined ? undefined : reading.window
|
|
1151
|
+
if (!Number.isFinite(used) || !Number.isFinite(threshold) || threshold <= 0) return { fold: false }
|
|
1152
|
+
if (!Number.isFinite(window_) || window_ <= 0) return { fold: false }
|
|
1153
|
+
const margin = Math.round((window_ * options.foldAtIdleMarginPercent) / 100)
|
|
1154
|
+
const headroom = Math.round(threshold - used)
|
|
1155
|
+
return { fold: headroom <= margin, headroom, margin }
|
|
1156
|
+
}
|
|
1157
|
+
|
|
1158
|
+
/**
|
|
1159
|
+
* Fold at the idle boundary when the session is nearly out of room. See
|
|
1160
|
+
* `foldAtIdle` in DEFAULT_OPTIONS for why the host's crossing trigger is not
|
|
1161
|
+
* enough on its own. Every failure is logged and swallowed, and an attempt is
|
|
1162
|
+
* rate-limited: a trigger must never break a turn or hammer the engine.
|
|
1163
|
+
*/
|
|
1164
|
+
function installIdleFold(ctx, resolve, services) {
|
|
1165
|
+
let inFlight = false
|
|
1166
|
+
let attemptedAt = 0
|
|
1167
|
+
let warnedNoService = false
|
|
1168
|
+
ctx.on('agent/status', ({ agent, status } = {}) => {
|
|
1169
|
+
if (status !== 'idle' || agent === null || agent === undefined) return
|
|
1170
|
+
const options = resolve()
|
|
1171
|
+
if (options.foldAtIdle !== true) return
|
|
1172
|
+
if (inFlight || Date.now() - attemptedAt < options.foldAtIdleCooldownMs) return
|
|
1173
|
+
let decision
|
|
1174
|
+
try {
|
|
1175
|
+
const session = agent.session
|
|
1176
|
+
if (session === null || session === undefined) return
|
|
1177
|
+
decision = shouldFoldAtIdle(readOccupancy(ctx, session, options), options)
|
|
1178
|
+
} catch {
|
|
1179
|
+
return
|
|
1180
|
+
}
|
|
1181
|
+
if (!decision.fold) return
|
|
1182
|
+
inFlight = true
|
|
1183
|
+
attemptedAt = Date.now()
|
|
1184
|
+
const signal = new AbortController().signal
|
|
1185
|
+
Promise.resolve()
|
|
1186
|
+
.then(() => requestFold(ctx, agent, options, services, signal))
|
|
1187
|
+
.then(
|
|
1188
|
+
(how) => {
|
|
1189
|
+
if (how === undefined) {
|
|
1190
|
+
if (!warnedNoService) {
|
|
1191
|
+
warnedNoService = true
|
|
1192
|
+
logLine(
|
|
1193
|
+
ctx,
|
|
1194
|
+
'warn',
|
|
1195
|
+
'context-truth: foldAtIdle is enabled, but neither the realm /compact command nor a reachable compaction service answered (upstream discussion 9425); the idle fold stays inactive',
|
|
1196
|
+
)
|
|
1197
|
+
}
|
|
1198
|
+
return
|
|
1199
|
+
}
|
|
1200
|
+
logLine(
|
|
1201
|
+
ctx,
|
|
1202
|
+
'info',
|
|
1203
|
+
'context-truth: folded at idle via %s (headroom=%s margin=%s)',
|
|
1204
|
+
how,
|
|
1205
|
+
decision.headroom,
|
|
1206
|
+
decision.margin,
|
|
1207
|
+
)
|
|
1208
|
+
},
|
|
1209
|
+
(error) =>
|
|
1210
|
+
logLine(
|
|
1211
|
+
ctx,
|
|
1212
|
+
'warn',
|
|
1213
|
+
'context-truth: idle fold failed: %s',
|
|
1214
|
+
error === null || error === undefined ? 'unknown error' : (error.message ?? error),
|
|
1215
|
+
),
|
|
1216
|
+
)
|
|
1217
|
+
.finally(() => {
|
|
1218
|
+
inFlight = false
|
|
1219
|
+
})
|
|
1220
|
+
})
|
|
1221
|
+
}
|
|
1222
|
+
|
|
1223
|
+
/**
|
|
1224
|
+
* Ask for one fold, at the agent's own idle boundary.
|
|
1225
|
+
*
|
|
1226
|
+
* Two channels, in this order, and the order is the point:
|
|
1227
|
+
*
|
|
1228
|
+
* 1. `commands.execute(agent, '/compact', …)` runs the session's own slash
|
|
1229
|
+
* command **through the agent's realm view**, so the fold lands on whichever
|
|
1230
|
+
* backend that agent mounts — the same engine a human's `/compact` reaches.
|
|
1231
|
+
* This is the only channel that works on a stock deployment: a plugin entry
|
|
1232
|
+
* lives at profile scope and cannot inject a preset realm's `compaction`
|
|
1233
|
+
* service (upstream discussion 9425). It is also the channel that keeps the
|
|
1234
|
+
* summary style consistent with the session's own folds.
|
|
1235
|
+
* 2. `ctx.compaction.compactNow()` on a provider reachable from the plugin's own
|
|
1236
|
+
* scope — the direct path, and the only one available when the realm registers
|
|
1237
|
+
* no `compact` command (e.g. a preset that drops `command-compact`).
|
|
1238
|
+
*
|
|
1239
|
+
* @returns which channel answered, or `undefined` when neither could be reached.
|
|
1240
|
+
*/
|
|
1241
|
+
async function requestFold(ctx, agent, options, services, signal) {
|
|
1242
|
+
if (options.foldAtIdleMethod !== 'service') {
|
|
1243
|
+
const commands = safeGet(ctx, 'commands')
|
|
1244
|
+
if (commands !== undefined && typeof commands.execute === 'function') {
|
|
1245
|
+
try {
|
|
1246
|
+
await commands.execute(agent, '/compact', [], signal)
|
|
1247
|
+
return 'command'
|
|
1248
|
+
} catch (error) {
|
|
1249
|
+
// A realm without the command, or a refusal, is not fatal: the service
|
|
1250
|
+
// channel below is still worth trying.
|
|
1251
|
+
logLine(
|
|
1252
|
+
ctx,
|
|
1253
|
+
'info',
|
|
1254
|
+
'context-truth: /compact request did not fold (%s); trying the compaction service',
|
|
1255
|
+
error === null || error === undefined ? 'unknown error' : (error.message ?? error),
|
|
1256
|
+
)
|
|
1257
|
+
}
|
|
1258
|
+
}
|
|
1259
|
+
}
|
|
1260
|
+
if (options.foldAtIdleMethod === 'command') return undefined
|
|
1261
|
+
// Ranked candidates, and the winner is the first that actually carries
|
|
1262
|
+
// `compactNow` — never "the first that is not undefined".
|
|
1263
|
+
//
|
|
1264
|
+
// That distinction is load-bearing: a property read for a service this fiber
|
|
1265
|
+
// does not have answers with a **diagnostic string**, not `undefined` (the foot
|
|
1266
|
+
// gun reported in upstream discussion 9425). An earlier revision took that
|
|
1267
|
+
// string as "found", skipped the `ctx.get` candidate that would have worked,
|
|
1268
|
+
// and then failed its own shape check — so the fold silently never fired while
|
|
1269
|
+
// the service was reachable the whole time.
|
|
1270
|
+
const candidates = []
|
|
1271
|
+
try {
|
|
1272
|
+
candidates.push(safeGet(agent.ctx, 'compaction'))
|
|
1273
|
+
} catch {
|
|
1274
|
+
// an agent without its own context is expected
|
|
1275
|
+
}
|
|
1276
|
+
try {
|
|
1277
|
+
candidates.push(safeGet(ctx, 'compaction'))
|
|
1278
|
+
} catch {
|
|
1279
|
+
// a context without `get` is expected on some harnesses
|
|
1280
|
+
}
|
|
1281
|
+
if (services.compaction !== undefined) {
|
|
1282
|
+
try {
|
|
1283
|
+
candidates.push(services.compaction())
|
|
1284
|
+
} catch {
|
|
1285
|
+
// a wired property that throws is simply not a candidate
|
|
1286
|
+
}
|
|
1287
|
+
}
|
|
1288
|
+
const compaction = candidates.find(
|
|
1289
|
+
(candidate) => isService(candidate) && typeof candidate.compactNow === 'function',
|
|
1290
|
+
)
|
|
1291
|
+
if (compaction === undefined) return undefined
|
|
1292
|
+
await compaction.compactNow(agent, signal)
|
|
1293
|
+
return 'service'
|
|
1294
|
+
}
|
|
1295
|
+
|
|
578
1296
|
/** Install the dynamic runtime-context line. */
|
|
579
|
-
function installContextLine(ctx,
|
|
1297
|
+
function installContextLine(ctx, resolve, services) {
|
|
580
1298
|
/** Last band published per session (hysteresis memory); never rendered. */
|
|
581
1299
|
const bands = new WeakMap()
|
|
1300
|
+
/** Per-session pace state for the headroom estimate; never rendered raw. */
|
|
1301
|
+
const paces = new WeakMap()
|
|
582
1302
|
/** Last text handed out, so a failed read degrades to the previous line. */
|
|
583
|
-
let lastText = renderUnknown(
|
|
1303
|
+
let lastText = renderUnknown(resolve())
|
|
584
1304
|
|
|
585
1305
|
const line = (assembly) => {
|
|
1306
|
+
// Resolved per assembly, so a settings change shows up on the next prompt.
|
|
1307
|
+
const options = resolve()
|
|
586
1308
|
try {
|
|
587
1309
|
const session = assembly?.agent?.session
|
|
588
1310
|
if (session === undefined || session === null) return lastText
|
|
589
1311
|
|
|
590
|
-
const reading = readOccupancy(ctx, session, options)
|
|
1312
|
+
const reading = readOccupancy(ctx, session, options, services.meter)
|
|
591
1313
|
const window_ = reading.window
|
|
592
1314
|
const ratio =
|
|
593
1315
|
Number.isFinite(reading.used) && Number.isFinite(window_) && window_ > 0
|
|
@@ -629,6 +1351,22 @@ function installContextLine(ctx, options) {
|
|
|
629
1351
|
band === 'unknown' || headroomRaw === undefined
|
|
630
1352
|
? undefined
|
|
631
1353
|
: quantizeHeadroom(headroomRaw, window_, options)
|
|
1354
|
+
// Sampled on every assembly so the state stays current even in bands that
|
|
1355
|
+
// do not render it; the rung settles before it is rendered.
|
|
1356
|
+
const perStep = samplePace(paces, session, assembly, reading.used, options)
|
|
1357
|
+
const settled = settlePace(paceSteps(headroomRaw, perStep), paces.get(session)?.pace, options)
|
|
1358
|
+
const sampled = paces.get(session)
|
|
1359
|
+
if (sampled !== undefined && settled.state !== undefined) {
|
|
1360
|
+
paces.set(session, { ...sampled, pace: settled.state })
|
|
1361
|
+
}
|
|
1362
|
+
const steps = settled.steps
|
|
1363
|
+
// Window still unused, on the same display step as `used` (floored, so it
|
|
1364
|
+
// never promises more room than the window has).
|
|
1365
|
+
const freeRaw =
|
|
1366
|
+
Number.isFinite(window_) && Number.isFinite(reading.used)
|
|
1367
|
+
? Math.max(0, window_ - reading.used)
|
|
1368
|
+
: undefined
|
|
1369
|
+
const free = band === 'unknown' || freeRaw === undefined ? undefined : quantize(freeRaw, window_, options)
|
|
632
1370
|
lastText = render(
|
|
633
1371
|
band,
|
|
634
1372
|
{
|
|
@@ -638,6 +1376,9 @@ function installContextLine(ctx, options) {
|
|
|
638
1376
|
headroomStep:
|
|
639
1377
|
headroomRaw === undefined ? undefined : headroomDisplayStep(headroomRaw, window_, options),
|
|
640
1378
|
headroomRaw,
|
|
1379
|
+
free,
|
|
1380
|
+
freeRaw,
|
|
1381
|
+
steps,
|
|
641
1382
|
used: reading.used,
|
|
642
1383
|
window: window_,
|
|
643
1384
|
threshold: reading.threshold,
|
|
@@ -655,7 +1396,10 @@ function installContextLine(ctx, options) {
|
|
|
655
1396
|
ctx.systemPrompt.variable(VARIABLE_NAME, (assembly) => line(assembly))
|
|
656
1397
|
ctx.systemPrompt.context({
|
|
657
1398
|
name: CONTEXT_NAME,
|
|
658
|
-
order:
|
|
1399
|
+
// `order` is fixed at registration: the host snapshots the contribution list
|
|
1400
|
+
// per assembly, and moving it live would reshuffle the cached prefix for a
|
|
1401
|
+
// change nobody asked to see mid-turn.
|
|
1402
|
+
order: resolve().order,
|
|
659
1403
|
text: `{{${VARIABLE_NAME}}}`,
|
|
660
1404
|
})
|
|
661
1405
|
}
|
|
@@ -674,6 +1418,18 @@ export const internals = {
|
|
|
674
1418
|
quantizeHeadroom,
|
|
675
1419
|
headroomDisplayStep,
|
|
676
1420
|
displayStep,
|
|
1421
|
+
PACE_LADDER,
|
|
1422
|
+
median,
|
|
1423
|
+
nextPaceState,
|
|
1424
|
+
samplePace,
|
|
1425
|
+
paceSteps,
|
|
1426
|
+
paceRung,
|
|
1427
|
+
settlePace,
|
|
1428
|
+
paceSentence,
|
|
1429
|
+
tightClause,
|
|
1430
|
+
foldClause,
|
|
1431
|
+
shouldFoldAtIdle,
|
|
1432
|
+
backendIdentity,
|
|
677
1433
|
render,
|
|
678
1434
|
renderUnknown,
|
|
679
1435
|
messageText,
|