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/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
- * NO IMPORTS, NO BUILD: this file is dependency-free ESM on purpose, so the
57
- * plugin installs into any profile without a node_modules copy or a toolchain.
58
- * 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`).
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
- /** Service required before the contribution can register. */
71
- 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']
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 `dsh-compaction-basic`'s policy. Keep these equal to the profile's
103
- * 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.
104
131
  */
105
- thresholdRatio: 0.8,
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 !== null && typeof config === 'object' ? 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
- return ctx.get(key)
421
+ viaMethod = ctx.get(key)
181
422
  } catch {
182
- return undefined
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
- 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')
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.1)),
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
- /** 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
+ */
343
633
  function authorityClause(language) {
344
634
  return language === 'zh'
345
- ? '本行由宿主实测,是上下文压力的唯一权威——不要凭对话长度或轮数自行估计。'
346
- : "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.'
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
- 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)
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 (options.enabled) {
1078
+ if (resolve().enabled) {
531
1079
  try {
532
- installContextLine(ctx, options)
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, options)
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, options) {
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, options) {
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(options)
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: 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,
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,