dsh-context-truth 0.1.2 → 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/lib/index.js CHANGED
@@ -37,6 +37,13 @@
37
37
  * the public `llm/stream` waterfall. Only the tail changes: the replayed
38
38
  * conversation prefix — the part the provider caches — stays byte-identical.
39
39
  *
40
+ * The call is identified by that `purpose` tag whenever the caller sets one; the
41
+ * directive-text fallback demands that the trailing message *begin* with the
42
+ * directive, so a tool result that merely quotes the engine — a source dump, a
43
+ * log excerpt, a grep hit — is never mistaken for a call. Getting that wrong is
44
+ * not harmless: a look-alike request would be patched too, and it would also
45
+ * consume the one-shot warning, leaving a later real failure silent.
46
+ *
40
47
  * WHAT IT MEASURES
41
48
  * ----------------
42
49
  * Primary: `tokenMeter.measure(session).totalTokens` — the host's price for the
@@ -46,10 +53,16 @@
46
53
  * point is derived the way `dsh-compaction-basic` derives it:
47
54
  * `min(window * thresholdRatio, window - reservedCompletion - headroom)`.
48
55
  *
49
- * NO IMPORTS, NO BUILD: this file is dependency-free ESM on purpose, so the
50
- * plugin installs into any profile without a node_modules copy or a toolchain.
51
- * It is both the source and the runtime artifact (`lib/index.js`).
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`).
52
64
  */
65
+ import z from '@deepseek-ai/schemastery'
53
66
 
54
67
  /** Stable cordis plugin name (loader diagnostics, and the runtime-context section name). */
55
68
  export const name = 'context-truth'
@@ -60,8 +73,22 @@ export const CONTEXT_NAME = 'context-truth'
60
73
  /** Prompt variable carrying the rendered line. */
61
74
  export const VARIABLE_NAME = 'context_occupancy'
62
75
 
63
- /** Service required before the contribution can register. */
64
- export const inject = ['systemPrompt']
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']
65
92
 
66
93
  /** Orders the line first inside the runtime-context block (sandbox is 110, approval 115). */
67
94
  const DEFAULT_ORDER = 100
@@ -69,9 +96,16 @@ const DEFAULT_ORDER = 100
69
96
  /** Substring that identifies the compaction engine's directive wherever `purpose` is absent. */
70
97
  const COMPACTION_INSTRUCTION_MARKER = 'acting as a compaction engine'
71
98
 
99
+ /**
100
+ * Opening words of that directive. The fallback test requires the trailing
101
+ * message to start here, which is what separates "this message IS the directive"
102
+ * from "this message happens to quote it".
103
+ */
104
+ const COMPACTION_INSTRUCTION_HEAD = 'You are now acting as a compaction engine'
105
+
72
106
  /** Default rules appended to the compaction directive. Keep the first one first: it is the idempotence marker. */
73
107
  const DEFAULT_COMPACTION_RULES = [
74
- "- Never record the assistant's own statements about its remaining context, token budget, or context-window pressure (for example \"context is nearly exhausted\", \"running out of budget\", \"hand off before context runs out\"). Those readings are measured by the host and delivered separately; a model's guess about them is not a durable fact.",
108
+ "- Never record the assistant's own statements about its remaining context, token budget, or context-window pressure — not even quoted, paraphrased, or listed as an example, and not when an earlier checkpoint already carries one: drop that wording instead of copying it forward. Those readings are measured by the host and delivered separately; a model's guess about them is not a durable fact.",
75
109
  '- Never record a plan to stop, defer, or hand off work whose only justification was context pressure. Record the actual task state instead.',
76
110
  ]
77
111
 
@@ -85,10 +119,17 @@ const DEFAULT_OPTIONS = {
85
119
  /** Emit the auto-compaction point and the headroom left before it. */
86
120
  showAutoCompactionPoint: true,
87
121
  /**
88
- * Mirror of `dsh-compaction-basic`'s policy. Keep these equal to the profile's
89
- * compaction config; the line only reports the point, it never enforces it.
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.
90
131
  */
91
- thresholdRatio: 0.8,
132
+ thresholdRatio: 0.7,
92
133
  headroomTokens: 65536,
93
134
  /** Reserved completion tokens; `null` reads the routed request's own maxTokens. */
94
135
  reservedCompletionTokens: null,
@@ -97,6 +138,13 @@ const DEFAULT_OPTIONS = {
97
138
  tightAt: 0.85,
98
139
  /** Fraction of the compaction point a reading must fall back below to leave a band. */
99
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',
100
148
  /**
101
149
  * Display quantum as a percentage of the window. The rendered text changes
102
150
  * only when the reading crosses a quantum, which is what keeps re-injection
@@ -104,27 +152,176 @@ const DEFAULT_OPTIONS = {
104
152
  * snapshot would then be re-committed on every single step.
105
153
  */
106
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,
107
168
  /** Append the "this line is the only authority" clause. */
108
169
  authoritative: true,
109
170
  /** Add the explicit "earlier claims are stale" clause to the calm band. */
110
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,
111
185
  /** Log each band change through ctx.logger, when a logger is present. */
112
186
  logBandChanges: true,
113
187
  /** Append `compactionRules` to the summarizer directive. */
114
188
  patchCompactionPrompt: true,
115
189
  /** Rules appended to the summarizer directive; `[]` disables the append. */
116
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,
117
230
  }
118
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
+
119
283
  /** Clamp a numeric option, falling back when it is not a finite number. */
120
284
  function num(value, fallback) {
121
285
  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
122
286
  }
123
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
+
124
321
  /** Merge user config over the defaults with light validation. */
125
322
  function resolveOptions(config) {
126
- const raw = config !== null && typeof config === 'object' ? config : {}
127
- const merged = { ...DEFAULT_OPTIONS, ...raw }
323
+ const raw = plainConfig(config)
324
+ const merged = raw !== null && typeof raw === 'object' ? { ...DEFAULT_OPTIONS, ...raw } : DEFAULT_OPTIONS
128
325
  const rules = Array.isArray(merged.compactionRules)
129
326
  ? merged.compactionRules.filter((rule) => typeof rule === 'string' && rule.trim().length > 0)
130
327
  : DEFAULT_COMPACTION_RULES
@@ -141,8 +338,29 @@ function resolveOptions(config) {
141
338
  moderateAt: num(merged.moderateAt, DEFAULT_OPTIONS.moderateAt),
142
339
  tightAt: num(merged.tightAt, DEFAULT_OPTIONS.tightAt),
143
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,
144
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)),
145
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
+ ),
146
364
  }
147
365
  }
148
366
 
@@ -160,25 +378,93 @@ function percentOf(value, total) {
160
378
  return Math.round((value / total) * 100)
161
379
  }
162
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
+
163
417
  /** Resolve a service that may or may not be mounted, without ever throwing. */
164
418
  function safeGet(ctx, key) {
419
+ let viaMethod
165
420
  try {
166
- return ctx.get(key)
421
+ viaMethod = ctx.get(key)
167
422
  } catch {
168
- return undefined
423
+ viaMethod = undefined
169
424
  }
425
+ if (isService(viaMethod)) return viaMethod
426
+ let viaProperty
427
+ try {
428
+ viaProperty = ctx[key]
429
+ } catch {
430
+ viaProperty = undefined
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')
170
446
  }
171
447
 
172
448
  /**
173
449
  * Read the host's own occupancy figure for one session.
174
450
  * @returns `{ used, window, reserved, threshold }`; any field may be `undefined`.
175
451
  */
176
- function readOccupancy(ctx, session, options) {
452
+ function readOccupancy(ctx, session, options, injectedMeter) {
177
453
  const result = {}
178
454
  let used
179
455
  let window_
180
456
 
181
- const meter = safeGet(ctx, 'tokenMeter')
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')
182
468
  if (meter !== undefined && typeof meter.measure === 'function') {
183
469
  try {
184
470
  const measured = meter.measure(session)
@@ -296,37 +582,58 @@ function quantize(used, window_, options) {
296
582
  }
297
583
 
298
584
  /**
299
- * Quantize the remaining headroom DOWN on a step that tightens as the room runs
300
- * out. Two rules meet here: the reading must never promise more room than the
301
- * session has (so it always rounds down), and it must stay useful to within a
302
- * few thousand tokens once compaction is close (so the step shrinks near zero).
303
- * Every step is a function of the reading, so a whole display bucket renders to
304
- * one identical string.
585
+ * Display step for the remaining-headroom figure. Every step is a function of the
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.
305
595
  */
306
- function quantizeHeadroom(headroom, window_, options) {
307
- if (!Number.isFinite(headroom) || headroom < 0) return undefined
596
+ function headroomDisplayStep(headroom, window_, options) {
308
597
  const coarse = displayStep(window_, options)
309
598
  const tiers = [
310
599
  coarse,
311
600
  Math.max(1000, Math.round(coarse * 0.4)),
312
- Math.max(1000, Math.round(coarse * 0.1)),
313
- 2000,
601
+ Math.max(1000, Math.round(coarse * 0.2)),
314
602
  ]
315
- let step = tiers[tiers.length - 1]
316
603
  for (const tier of tiers) {
317
- if (headroom >= 4 * tier) {
318
- step = tier
319
- break
320
- }
604
+ if (headroom >= 4 * tier) return tier
321
605
  }
606
+ return tiers[tiers.length - 1]
607
+ }
608
+
609
+ /**
610
+ * Quantize the remaining headroom DOWN on a step that tightens as the room runs
611
+ * out. Two rules meet here: the reading must never promise more room than the
612
+ * session has (so it always rounds down), and it must stay useful to within a
613
+ * few thousand tokens once compaction is close (so the step shrinks near zero).
614
+ */
615
+ function quantizeHeadroom(headroom, window_, options) {
616
+ if (!Number.isFinite(headroom) || headroom < 0) return undefined
617
+ const step = headroomDisplayStep(headroom, window_, options)
322
618
  return Math.floor(headroom / step) * step
323
619
  }
324
620
 
325
- /** The clause that closes every variant. */
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
+ */
326
633
  function authorityClause(language) {
327
634
  return language === 'zh'
328
- ? '本行由宿主实测,是上下文压力的唯一权威——不要凭对话长度或轮数自行估计。'
329
- : "This host-measured line is the only authority on context pressure; never estimate it from the conversation's length."
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.'
330
637
  }
331
638
 
332
639
  /** The clause that retires claims inherited from earlier turns and checkpoints. */
@@ -336,6 +643,212 @@ function staleClause(language) {
336
643
  : 'Earlier claims that context is nearly exhausted — including ones inside compacted checkpoints — are stale.'
337
644
  }
338
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
+
696
+ /** "under 50K" / "不足 50K" — the honest form of a figure below one display step. */
697
+ function underStep(step, zh) {
698
+ return zh ? `不足 ${formatTokens(step)}` : `under ${formatTokens(step)}`
699
+ }
700
+
701
+ /** "under 5" / "不足 5" — the same honesty for a percentage the caller suffixes with `%`. */
702
+ function underPercent(step, window_, zh) {
703
+ const value = Math.max(1, Math.round(percentOf(step, window_) ?? 1))
704
+ return zh ? `不足 ${value}` : `under ${value}`
705
+ }
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
+
339
852
  /** Render the reading for one band. Pure: same inputs, same bytes. */
340
853
  function render(band, reading, options) {
341
854
  const zh = options.language === 'zh'
@@ -344,27 +857,72 @@ function render(band, reading, options) {
344
857
  if (band === 'ample' && options.staleClaimClause) parts.push(staleClause(options.language))
345
858
  const tail = parts.length === 0 ? '' : ` ${parts.join(' ')}`
346
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
+
347
872
  if (band === 'unknown') {
348
873
  return zh
349
874
  ? `上下文实况:本会话尚未取到用量读数。不要据此声称上下文紧张。${tail}`
350
875
  : `Context occupancy: no reading yet in this session. Do not claim context is scarce on that basis.${tail}`
351
876
  }
352
877
 
353
- const used = formatTokens(reading.quantized)
878
+ // A figure that rounds below one display step says so instead of rendering "0".
879
+ // A floored zero used to contradict the headroom on the same line — the reading
880
+ // was 30–50K against a 50K step — and read as an empty window.
881
+ const step = Number.isFinite(reading.step) && reading.step > 0 ? reading.step : undefined
882
+ const flooredUsed = reading.quantized === 0 && Number.isFinite(reading.used) && reading.used > 0
883
+ const used = flooredUsed && step !== undefined ? underStep(step, zh) : formatTokens(reading.quantized)
354
884
  const window_ = formatTokens(reading.window)
355
- const percent = reading.percent
885
+ const percent =
886
+ flooredUsed && step !== undefined ? underPercent(step, reading.window, zh) : `${reading.percent}`
356
887
  const head = reading.headroom
888
+ const headStep =
889
+ Number.isFinite(reading.headroomStep) && reading.headroomStep > 0 ? reading.headroomStep : undefined
890
+ const flooredHead = head === 0 && Number.isFinite(reading.headroomRaw) && reading.headroomRaw > 0
357
891
  const point = Number.isFinite(reading.threshold)
358
892
  ? zh
359
893
  ? ` 自动压缩阈值 ${formatTokens(reading.threshold)}(窗口的 ${percentOf(reading.threshold, reading.window)}%)。`
360
894
  : ` Automatic compaction fires at ${formatTokens(reading.threshold)} (${percentOf(reading.threshold, reading.window)}% of the window).`
361
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.
362
916
  const remaining =
363
- head !== undefined
364
- ? zh
365
- ? ` 距阈值还有约 ${head === 0 && reading.headroomRaw > 0 ? '不足 1K' : formatTokens(head)} tokens。`
366
- : ` About ${head === 0 && reading.headroomRaw > 0 ? 'less than 1K' : formatTokens(head)} tokens of headroom remain before it.`
367
- : ''
917
+ head === undefined || reading.headroomRaw === 0
918
+ ? ''
919
+ : flooredHead && headStep !== undefined
920
+ ? zh
921
+ ? ` 距阈值不足 ${formatTokens(headStep)} tokens。`
922
+ : ` Under ${formatTokens(headStep)} tokens of headroom remain before it.`
923
+ : zh
924
+ ? ` 距阈值还有约 ${formatTokens(head)} tokens。`
925
+ : ` About ${formatTokens(head)} tokens of headroom remain before it.`
368
926
  const head0 = zh
369
927
  ? `上下文实况(宿主实测):已用 ${used} / ${window_}(${percent}%)。`
370
928
  : `Context occupancy (host-measured): ${used} / ${window_} tokens used (${percent}%).`
@@ -372,20 +930,18 @@ function render(band, reading, options) {
372
930
  switch (band) {
373
931
  case 'ample':
374
932
  return zh
375
- ? `${head0}${point}${remaining} 上下文不紧张——不要因为"上下文不够"而收尾、交接子代理或缩小范围。${tail}`
376
- : `${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}`
377
935
  case 'moderate':
378
936
  return zh
379
- ? `${head0}${point}${remaining} 仍有充足余量,继续推进即可,顺手把关键状态写进文档或提交。${tail}`
380
- : `${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}`
381
939
  case 'tight':
382
- return zh
383
- ? `${head0}${point}${remaining} 余量确实不多了——收完当前这一步、把状态落到磁盘,再考虑交接。${tail}`
384
- : `${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}`
385
941
  default:
386
942
  return zh
387
- ? `${head0}${point} 已到或越过自动压缩点——接下来可能发生压缩折叠,别让关键状态只存在于本窗口。${tail}`
388
- : `${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}`
389
945
  }
390
946
  }
391
947
 
@@ -422,6 +978,12 @@ function patchCompactionInstruction(text, rules) {
422
978
 
423
979
  /**
424
980
  * Test whether one LLM request is the compaction summarization call.
981
+ *
982
+ * A tag set by the caller is authoritative and is never second-guessed. Without
983
+ * one, the trailing message must *be* the directive: a message that merely
984
+ * contains the marker somewhere — a tool result dumping the engine source or a
985
+ * session log is the common case — is an ordinary request.
986
+ *
425
987
  * @param options - request envelope observed at the `llm/stream` waterfall.
426
988
  * @returns whether the request carries the compaction directive.
427
989
  */
@@ -429,9 +991,18 @@ function isCompactionRequest(options) {
429
991
  if (options === null || typeof options !== 'object') return false
430
992
  const messages = options.messages
431
993
  if (!Array.isArray(messages) || messages.length === 0) return false
994
+ if (options.purpose !== undefined) return options.purpose === 'compaction'
432
995
  const text = messageText(messages[messages.length - 1])
433
- if (text === undefined || !text.includes(COMPACTION_INSTRUCTION_MARKER)) return false
434
- return options.purpose === undefined || options.purpose === 'compaction'
996
+ return typeof text === 'string' && text.trimStart().startsWith(COMPACTION_INSTRUCTION_HEAD)
997
+ }
998
+
999
+ /**
1000
+ * Whether the request identifies itself as the engine's call. Used only to decide
1001
+ * who may spend the one-shot warning: a heuristic match must never be able to
1002
+ * silence a later, real failure.
1003
+ */
1004
+ function isTaggedCompactionRequest(options) {
1005
+ return options !== null && typeof options === 'object' && options.purpose === 'compaction'
435
1006
  }
436
1007
 
437
1008
  /**
@@ -469,11 +1040,44 @@ function patchCompactionRequest(options, rules) {
469
1040
  * @param config - optional overrides of the defaults documented above.
470
1041
  */
471
1042
  export function apply(ctx, config) {
472
- const options = resolveOptions(config)
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)
473
1049
 
474
- if (options.enabled) {
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
+ )
1077
+
1078
+ if (resolve().enabled) {
475
1079
  try {
476
- installContextLine(ctx, options)
1080
+ installContextLine(ctx, resolve, services)
477
1081
  } catch (error) {
478
1082
  if (isAlreadyRegistered(error)) {
479
1083
  const logger = ctx.logger
@@ -486,7 +1090,8 @@ export function apply(ctx, config) {
486
1090
  }
487
1091
  }
488
1092
 
489
- installCompactionPatch(ctx, options)
1093
+ installCompactionPatch(ctx, resolve)
1094
+ installIdleFold(ctx, resolve, services)
490
1095
  }
491
1096
 
492
1097
  /** Whether a registration failed because the name is already taken in this layer. */
@@ -495,12 +1100,18 @@ function isAlreadyRegistered(error) {
495
1100
  }
496
1101
 
497
1102
  /** Install the `llm/stream` listener that extends the summarizer directive. */
498
- function installCompactionPatch(ctx, options) {
499
- if (!options.patchCompactionPrompt || options.compactionRules.length === 0) return
1103
+ function installCompactionPatch(ctx, resolve) {
500
1104
  let warned = false
501
1105
  ctx.on('llm/stream', (request, next) => {
502
1106
  try {
503
- if (!patchCompactionRequest(request, options.compactionRules) && isCompactionRequest(request) && !warned) {
1107
+ const options = resolve()
1108
+ if (!options.patchCompactionPrompt || options.compactionRules.length === 0) return next()
1109
+ const applied = patchCompactionRequest(request, options.compactionRules)
1110
+ // Only a request its own caller tagged as compaction may spend the one-shot
1111
+ // warning. Warning on a heuristic match let an ordinary turn — one whose
1112
+ // trailing tool result quoted the directive — burn the warning, and a real
1113
+ // failure after that would have been completely silent.
1114
+ if (!applied && isTaggedCompactionRequest(request) && !warned) {
504
1115
  warned = true
505
1116
  const logger = ctx.logger
506
1117
  if (logger !== undefined && typeof logger.warn === 'function') {
@@ -514,19 +1125,191 @@ function installCompactionPatch(ctx, options) {
514
1125
  })
515
1126
  }
516
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
+
517
1296
  /** Install the dynamic runtime-context line. */
518
- function installContextLine(ctx, options) {
1297
+ function installContextLine(ctx, resolve, services) {
519
1298
  /** Last band published per session (hysteresis memory); never rendered. */
520
1299
  const bands = new WeakMap()
1300
+ /** Per-session pace state for the headroom estimate; never rendered raw. */
1301
+ const paces = new WeakMap()
521
1302
  /** Last text handed out, so a failed read degrades to the previous line. */
522
- let lastText = renderUnknown(options)
1303
+ let lastText = renderUnknown(resolve())
523
1304
 
524
1305
  const line = (assembly) => {
1306
+ // Resolved per assembly, so a settings change shows up on the next prompt.
1307
+ const options = resolve()
525
1308
  try {
526
1309
  const session = assembly?.agent?.session
527
1310
  if (session === undefined || session === null) return lastText
528
1311
 
529
- const reading = readOccupancy(ctx, session, options)
1312
+ const reading = readOccupancy(ctx, session, options, services.meter)
530
1313
  const window_ = reading.window
531
1314
  const ratio =
532
1315
  Number.isFinite(reading.used) && Number.isFinite(window_) && window_ > 0
@@ -568,12 +1351,34 @@ function installContextLine(ctx, options) {
568
1351
  band === 'unknown' || headroomRaw === undefined
569
1352
  ? undefined
570
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)
571
1370
  lastText = render(
572
1371
  band,
573
1372
  {
574
1373
  quantized,
1374
+ step: displayStep(window_, options),
575
1375
  headroom,
1376
+ headroomStep:
1377
+ headroomRaw === undefined ? undefined : headroomDisplayStep(headroomRaw, window_, options),
576
1378
  headroomRaw,
1379
+ free,
1380
+ freeRaw,
1381
+ steps,
577
1382
  used: reading.used,
578
1383
  window: window_,
579
1384
  threshold: reading.threshold,
@@ -591,7 +1396,10 @@ function installContextLine(ctx, options) {
591
1396
  ctx.systemPrompt.variable(VARIABLE_NAME, (assembly) => line(assembly))
592
1397
  ctx.systemPrompt.context({
593
1398
  name: CONTEXT_NAME,
594
- order: options.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,
595
1403
  text: `{{${VARIABLE_NAME}}}`,
596
1404
  })
597
1405
  }
@@ -608,11 +1416,25 @@ export const internals = {
608
1416
  settleBand,
609
1417
  quantize,
610
1418
  quantizeHeadroom,
1419
+ headroomDisplayStep,
611
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,
612
1433
  render,
613
1434
  renderUnknown,
614
1435
  messageText,
615
1436
  patchCompactionInstruction,
616
1437
  patchCompactionRequest,
617
1438
  isCompactionRequest,
1439
+ isTaggedCompactionRequest,
618
1440
  }